fix(maestro): harden grouped sidebar interactions

Closes #118

crates/maestro-cli/src/sessions.rs

@@ -3,6 +3,7 @@
 use std::collections::HashMap;
 use std::io::Write;
 
+use maestro_protocol::display::abbreviate_dir;
 use maestro_protocol::{
     ActivityState, ClientError, CreateSessionRequest, DaemonClient, DaemonInfo, Session,
     SessionStatus, WorktreeSpec,
@@ -138,21 +139,6 @@ pub(crate) fn blocked_label(s: &Session) -> String {
         .unwrap_or_default()
 }
 
-/// Render a path with the daemon's home dir collapsed to `~`. Mirrors the web
-/// UI's abbreviation so CLI and browser show the same directory shorthand.
-pub(crate) fn abbreviate_dir(path: &std::path::Path, home: &str) -> String {
-    let p = path.to_string_lossy();
-    if !home.is_empty() {
-        if p == home {
-            return "~".into();
-        }
-        if let Some(rest) = p.strip_prefix(&format!("{home}/")) {
-            return format!("~/{rest}");
-        }
-    }
-    p.into_owned()
-}
-
 #[cfg(test)]
 mod tests {
     use std::collections::HashMap;

crates/maestro-cli/src/worktrees.rs

@@ -6,10 +6,10 @@
 
 use std::io::Write;
 
+use maestro_protocol::display::abbreviate_dir;
 use maestro_protocol::{ClientError, DaemonClient, DaemonInfo, InTheWay, RetainedWorktree};
 
 use crate::cli::{ListWorktreesArgs, ReclaimArgs};
-use crate::sessions::abbreviate_dir;
 
 /// `maestro worktrees list`
 pub async fn run_list(

crates/maestro-config/src/lib.rs

@@ -22,7 +22,8 @@ use std::collections::BTreeMap;
 use std::net::SocketAddr;
 use std::path::{Path, PathBuf};
 
-use serde::Deserialize;
+use serde::de::Error as _;
+use serde::{Deserialize, Deserializer};
 
 /// Directory name under `$XDG_CONFIG_HOME` (default `~/.config`).
 pub const DIR_NAME: &str = "maestro";
@@ -146,11 +147,14 @@ pub struct WebSection {
 
 /// `[tui]` — `maestro tui` settings (NAP-275 epic, phase 2 NAP-277).
 ///
-/// Leader key, chord timeout, and per-mode keymap overrides. The TUI ships
-/// with a default keymap; entries in `keymap_normal` / `keymap_insert` are
-/// applied **over** the defaults, so a partial override is enough.
+/// Theme, leader key, chord timeout, and per-mode keymap overrides. The TUI
+/// ships with a default keymap; entries in `keymap_normal` / `keymap_insert`
+/// are applied **over** the defaults, so a partial override is enough.
 #[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct TuiSection {
+    /// Named palette preset. Defaults to the dark preset.
+    #[serde(default, deserialize_with = "deserialize_theme")]
+    pub theme: Option<TuiTheme>,
     /// Canonical key form, e.g. `"ctrl-a"`. Default `ctrl-a`.
     #[serde(default)]
     pub leader: Option<String>,
@@ -167,6 +171,33 @@ pub struct TuiSection {
     pub keymap_insert: BTreeMap<String, String>,
 }
 
+/// Palette presets supported by the TUI's `[tui].theme` setting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TuiTheme {
+    /// The terminal-native dark palette and the default.
+    Dark,
+    /// A high-contrast light palette.
+    Light,
+    /// Named ANSI colours, allowing the terminal to provide the colour set.
+    Ansi,
+}
+
+fn deserialize_theme<'de, D>(deserializer: D) -> Result<Option<TuiTheme>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw = Option::<String>::deserialize(deserializer)?;
+    raw.map(|name| match name.as_str() {
+        "dark" => Ok(TuiTheme::Dark),
+        "light" => Ok(TuiTheme::Light),
+        "ansi" => Ok(TuiTheme::Ansi),
+        _ => Err(D::Error::custom(format!(
+            "invalid [tui].theme {name:?}; expected \"dark\", \"light\", or \"ansi\""
+        ))),
+    })
+    .transpose()
+}
+
 /// `[spawn]` — command presets for the spawn form (#22, part of #21).
 ///
 /// Defined in shared config so every binary sees the same list: the web reads
@@ -596,6 +627,30 @@ bind_addr = "127.0.0.1:9090"
         );
     }
 
+    #[test]
+    fn tui_theme_parses_named_presets_and_defaults_when_absent() {
+        assert_eq!(TuiSection::default().theme, None);
+        let cfg = file_with("[tui]\ntheme = \"light\"\n");
+        assert_eq!(cfg.tui.theme, Some(TuiTheme::Light));
+        let cfg = file_with("[tui]\ntheme = \"ansi\"\n");
+        assert_eq!(cfg.tui.theme, Some(TuiTheme::Ansi));
+    }
+
+    #[test]
+    fn tui_theme_rejects_unknown_names_with_the_field_name() {
+        let err =
+            toml::from_str::<MaestroConfigFile>("[tui]\ntheme = \"solarized\"\n").unwrap_err();
+        let message = err.to_string();
+        assert!(
+            message.contains("[tui].theme"),
+            "diagnostic should name the field: {message}"
+        );
+        assert!(
+            message.contains("solarized"),
+            "diagnostic should name the invalid value: {message}"
+        );
+    }
+
     fn file_with(body: &str) -> MaestroConfigFile {
         toml::from_str(body).expect("parse")
     }

crates/maestro-daemon/src/session.rs

@@ -62,6 +62,11 @@ pub struct SessionRecord {
     /// resumes and [`Session::activity_detail`] is cleared with it. This
     /// field is daemon-local bookkeeping only — it never rides the wire.
     pub reported_activity: Option<crate::activity::ReportedActivity>,
+    /// Flipped once the natural-exit settle step (#82) has been applied or
+    /// refused for this session. `Dead` is observable before settling ends
+    /// (#115), so this is the observable that says its outcomes are safe to
+    /// assert on. Daemon-local bookkeeping; never rides the wire.
+    pub settled: bool,
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -294,6 +299,17 @@ impl SessionManager {
         sessions.get(&id).map(|r| r.session.status)
     }
 
+    /// Whether the natural-exit settle step (#82) has finished for this
+    /// session: `Some(true)` once applied or refused, `Some(false)` while
+    /// still pending, `None` if the session is unknown. `Dead` is observable
+    /// before settling ends (#115), so anything asserting on a dead
+    /// session's worktree waits on this rather than inferring settle
+    /// completion from its side effects.
+    pub async fn is_settled(&self, id: Uuid) -> Option<bool> {
+        let sessions = self.inner.sessions.lock().await;
+        sessions.get(&id).map(|r| r.settled)
+    }
+
     /// Spawn a new session. On success returns the freshly-created `Session`.
     pub async fn create(&self, req: CreateSessionRequest) -> Result<Session, SessionError> {
         let (effective_cwd, worktree_path, worktree_base_repo) = match &req.worktree {
@@ -429,6 +445,7 @@ impl SessionManager {
                     worktree_branch: req.worktree.as_ref().map(|w| w.branch.clone()),
                     bridge,
                     reported_activity: None,
+                    settled: false,
                 },
             );
         }
@@ -657,6 +674,7 @@ impl SessionManager {
                     worktree_branch: None,
                     bridge,
                     reported_activity: None,
+                    settled: false,
                 },
             );
             let _ = self
@@ -1069,6 +1087,14 @@ async fn mark_session_dead(inner: &Arc<Inner>, id: Uuid) {
             }
         }
     }
+    // Settle has now been applied or refused either way (#115): from here on
+    // its outcomes are safe to observe.
+    {
+        let mut sessions = inner.sessions.lock().await;
+        if let Some(record) = sessions.get_mut(&id) {
+            record.settled = true;
+        }
+    }
 
     let _ = inner.sidecar.write(&session);
     let _ = inner.events.send(CatalogEvent::SessionUpdated { session });

crates/maestro-daemon/tests/activity.rs

@@ -189,8 +189,23 @@ fn a_foreground_pipeline_whose_leader_exited_is_still_awaiting_input() {
         "never observed a foreground group whose leader had exited"
     );
 
-    assert!(
-        awaiting_input(pane.pane_pid, &pane.tty, &ProcGroups::snapshot()),
-        "a surviving pipeline member still holds the tty"
-    );
+    // The leader can be gone while the surviving stage is still setting up:
+    // `true` exits as soon as both stages are forked, before the reader has
+    // opened the tty and parked. Poll for the answer, but only accept it
+    // while the state this test exists for still holds — otherwise a shell
+    // that regained the terminal would satisfy it vacuously.
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut holds = false;
+    while std::time::Instant::now() < deadline {
+        let groups = ProcGroups::snapshot();
+        let still_leaderless = pgrp_and_tpgid(pane.pane_pid).is_some_and(|(pgrp, tpgid)| {
+            tpgid > 0 && tpgid != pgrp && pgrp_and_tpgid(tpgid).is_none()
+        });
+        if still_leaderless && awaiting_input(pane.pane_pid, &pane.tty, &groups) {
+            holds = true;
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    assert!(holds, "a surviving pipeline member still holds the tty");
 }

crates/maestro-daemon/tests/session_manager.rs

@@ -397,6 +397,12 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
     init_bare_repo(origin.path());
     push_all_to_origin(repo.path(), origin.path());
 
+    // Subscribe before the watcher starts so every pass's emission is
+    // captured — otherwise the breakdown event can land between the
+    // snapshot observation below and the drain, and the quiet window
+    // would see it as an illegitimate re-emit.
+    let mut events = fx.manager.events();
+
     fx.manager.start_liveness_watcher_with_blocked_work(
         Duration::from_millis(50),
         Duration::from_millis(100),
@@ -418,14 +424,38 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
     })
     .await;
 
-    // A steady state must not re-emit every tick (#83 change-detection).
-    let mut events = fx.manager.events();
+    // Consume through the emission that carried the breakdown (#83
+    // change-detection): the quiet window below must start after the last
+    // legitimate change, not race it into the channel.
+    loop {
+        match tokio::time::timeout(Duration::from_secs(5), events.recv()).await {
+            Ok(Ok(CatalogEvent::SessionUpdated { session }))
+                if matches!(
+                    &session.blocked_work,
+                    Some(b) if b.uncommitted_files >= 1 && b.untracked_files >= 1
+                ) =>
+            {
+                break;
+            }
+            Ok(Ok(_)) => continue,
+            _ => panic!("never saw the SessionUpdated carrying the breakdown"),
+        }
+    }
     while events.try_recv().is_ok() {}
     tokio::time::sleep(Duration::from_millis(400)).await;
-    assert!(
-        !matches!(events.try_recv(), Ok(CatalogEvent::SessionUpdated { .. })),
-        "an unchanged worktree must not re-emit SessionUpdated"
-    );
+    // Only a *changed* indicator counts as a re-emit (#83 change-detection).
+    // The activity pass may still legitimately announce e.g. Active→Idle
+    // (its debounce is time-based, not worktree-based), and its payload
+    // carries today's blocked_work unchanged.
+    while let Ok(CatalogEvent::SessionUpdated { session }) = events.try_recv() {
+        assert!(
+            matches!(
+                &session.blocked_work,
+                Some(b) if b.uncommitted_files >= 1 && b.untracked_files >= 1
+            ),
+            "an unchanged worktree must not re-emit a changed indicator"
+        );
+    }
 }
 
 /// Cleanup on kill is unconditional once the guard passes (#79): even a spec
@@ -848,6 +878,17 @@ async fn natural_exit_of_a_pristine_worktree_removes_it() {
     })
     .await;
 
+    // (`Dead` is observable a moment before the settle step removes the tree.)
+    wait_for_async(Duration::from_secs(3), || async {
+        !wt_path.exists()
+            && fx
+                .retained_store()
+                .load_all()
+                .map(|all| all.is_empty())
+                .unwrap_or(false)
+    })
+    .await;
+
     assert!(
         !wt_path.exists(),
         "a pristine worktree leaves nothing behind"
@@ -905,6 +946,14 @@ async fn natural_exit_without_a_retained_store_destroys_nothing() {
     })
     .await;
 
+    // The settle step has been applied or refused either way — here refused,
+    // since there is no store to record the tree into. Only from this point
+    // is "the tree survived" a settled fact rather than a race (#115).
+    wait_for_async(Duration::from_secs(3), || async {
+        manager.is_settled(s.id).await == Some(true)
+    })
+    .await;
+
     assert!(
         wt_path.exists(),
         "nothing may be destroyed when it cannot be recorded"

crates/maestro-hooks/src/lib.rs

@@ -25,13 +25,25 @@ pub const HOOK_MARKER: &str = "maestro-claude-hook";
 pub const SCRIPT_FILE_NAME: &str = "maestro-claude-hook.sh";
 
 /// Claude Code hook event → `ActivityState` spelling posted to the daemon.
-pub const HOOK_EVENTS: [(&str, &str); 3] = [
-    // Tool finished: the agent is demonstrably producing work.
+///
+/// `PreToolUse` is what makes a session `Active` *during* a long tool call —
+/// `PostToolUse` alone only fires once it ends (#114). `StopFailure` is
+/// Claude Code's own name for "the turn ended on an API error"; there is no
+/// failure signal in `Stop` or `SessionEnd` payloads, so those never report
+/// `Error`.
+pub const HOOK_EVENTS: [(&str, &str); 5] = [
+    // Tool starting: the agent is demonstrably producing work, even if the
+    // tool itself runs for minutes.
+    ("PreToolUse", "Active"),
+    // Tool finished successfully.
     ("PostToolUse", "Active"),
     // Permission / idle notices: Claude is blocked on the user.
     ("Notification", "AwaitingInput"),
     // Turn ended: waiting on the user again.
     ("Stop", "AwaitingInput"),
+    // Turn ended on an API error; the payload's `error` field is forwarded
+    // as the report's `detail` (#114).
+    ("StopFailure", "Error"),
 ];
 
 /// The shipped hook script. POSIX sh so any `/bin/sh` works.
@@ -39,17 +51,27 @@ pub const HOOK_SCRIPT: &str = r#"#!/bin/sh
 # Installed by maestro (#106): report Claude Code activity to its daemon.
 # Exits silently unless running inside a session maestro spawned (#103 env).
 # Event -> ActivityState mapping:
-#   PostToolUse   -> Active         (tool finished; agent is working)
+#   PreToolUse    -> Active         (tool started; agent is working)
+#   PostToolUse   -> Active         (tool finished)
 #   Notification  -> AwaitingInput  (permission / idle notice)
 #   Stop          -> AwaitingInput  (turn ended; waiting on the user)
+#   StopFailure   -> Error          (turn ended on an API error)
 state="$1"
 [ -n "$MAESTRO_SESSION_ID" ] || exit 0
 [ -n "$MAESTRO_URL" ] || exit 0
-# Drain the hook payload so the parent never sees a broken pipe.
-cat >/dev/null 2>&1
+payload=$(cat 2>/dev/null) || true
+body="{\"state\":\"$state\"}"
+# StopFailure payloads carry the outcome in "error". Only a plain enum
+# spelling is reported as the detail — anything else (quotes, backslashes,
+# prose) would risk breaking the JSON body, and the spelling already names
+# the failure.
+detail=$(printf '%s' "$payload" | sed -n 's/.*"error"[[:space:]]*:[[:space:]]*"\([a-z_]*\)".*/\1/p')
+if [ -n "$detail" ]; then
+    body="{\"state\":\"$state\",\"detail\":\"$detail\"}"
+fi
 curl -fsS --connect-timeout 1 --max-time 2 \
     -H 'Content-Type: application/json' \
-    -d "{\"state\":\"$state\"}" \
+    -d "$body" \
     "$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity" \
     >/dev/null 2>&1 || true
 exit 0

crates/maestro-hooks/src/tests.rs

@@ -7,7 +7,7 @@ use std::process::{Command, Stdio};
 
 use super::*;
 
-fn sh(script: &str, args: &[&str], envs: &[(&str, &str)]) -> std::process::Output {
+fn sh(script: &str, args: &[&str], envs: &[(&str, &str)], payload: &[u8]) -> std::process::Output {
     let mut cmd = Command::new("/bin/sh");
     // `sh -c CMD NAME ARGS…`: NAME fills $0, so the real arguments start at $1.
     let mut argv = vec!["-c", script, HOOK_MARKER];
@@ -26,21 +26,48 @@ fn sh(script: &str, args: &[&str], envs: &[(&str, &str)]) -> std::process::Outpu
         .spawn()
         .expect("spawn /bin/sh");
     // Feed a Claude-Code-style payload on stdin; the script must drain it.
-    child
-        .stdin
-        .take()
-        .unwrap()
-        .write_all(br#"{"session_id":"x"}"#)
-        .ok();
+    child.stdin.take().unwrap().write_all(payload).ok();
     child.wait_with_output().expect("wait")
 }
 
+const SESSION: &str = "01234567-89ab-cdef-0123-456789abcdef";
+
+/// Accept exactly one HTTP request on a throwaway listener, answer 204, and
+/// hand back the raw request text. Runs `run` with the base URL once the
+/// acceptor thread is in place.
+fn capture_request(run: impl FnOnce(String) -> std::process::Output) -> String {
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        let (mut sock, _) = listener.accept().unwrap();
+        let mut buf = [0u8; 4096];
+        let n = sock.read(&mut buf).unwrap();
+        sock.write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n")
+            .unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    });
+    let out = run(format!("http://{addr}"));
+    assert!(out.status.success(), "{:?}", out.stderr);
+    handle.join().unwrap()
+}
+
+fn session_envs(url: &str) -> Vec<(&'static str, String)> {
+    vec![
+        ("MAESTRO_URL", url.to_string()),
+        ("MAESTRO_SESSION_ID", SESSION.to_string()),
+    ]
+}
+
+fn owned_envs<'a>(envs: &'a [(&'static str, String)]) -> Vec<(&'static str, &'a str)> {
+    envs.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
 /// The hook must be invisible outside maestro: no env vars (#103 unset) ⇒
 /// exit 0, no output, stdin drained.
 #[test]
 fn script_exits_silently_without_maestro_env() {
     for (event, _) in HOOK_EVENTS {
-        let out = sh(HOOK_SCRIPT, &[event], &[]);
+        let out = sh(HOOK_SCRIPT, &[event], &[], br#"{"session_id":"x"}"#);
         assert!(out.status.success(), "{event:?}: {:?}", out.stderr);
         assert!(out.stdout.is_empty(), "{event:?}: {:?}", out.stdout);
         assert!(out.stderr.is_empty(), "{event:?}: {:?}", out.stderr);
@@ -51,46 +78,82 @@ fn script_exits_silently_without_maestro_env() {
 /// activity endpoint and still exits 0.
 #[test]
 fn script_posts_mapped_state_to_the_activity_endpoint() {
-    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
-    let addr = listener.local_addr().unwrap();
-    let server = move || {
-        let (mut sock, _) = listener.accept().unwrap();
-        let mut buf = [0u8; 4096];
-        let n = sock.read(&mut buf).unwrap();
-        let raw = String::from_utf8_lossy(&buf[..n]).to_string();
-        sock.write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n")
-            .unwrap();
-        raw
-    };
-    let handle = std::thread::spawn(server);
-
-    let url = format!("http://{addr}");
-    let session = "01234567-89ab-cdef-0123-456789abcdef";
     // The installer bakes the mapped state into the command's argv; the
     // script relays whatever it is given.
-    let out = sh(
-        HOOK_SCRIPT,
-        &["Active"],
-        &[("MAESTRO_URL", &url), ("MAESTRO_SESSION_ID", session)],
-    );
-    assert!(out.status.success());
-
-    let request = handle.join().unwrap();
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Active"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"session_id":"x"}"#,
+        )
+    });
     assert!(request.starts_with("POST "), "{request}");
     assert!(
-        request.contains(&format!("/api/sessions/{session}/activity")),
+        request.contains(&format!("/api/sessions/{SESSION}/activity")),
         "{request}"
     );
     assert!(request.contains(r#""state":"Active""#), "{request}");
 }
 
-/// Every event maps to the state the issue specifies.
+/// Every event maps to the state the contract specifies.
 #[test]
 fn event_state_mapping_matches_the_contract() {
     let map: std::collections::HashMap<&str, &str> = HOOK_EVENTS.into_iter().collect();
+    assert_eq!(map["PreToolUse"], "Active");
     assert_eq!(map["PostToolUse"], "Active");
-    assert_eq!(map["Stop"], "AwaitingInput");
     assert_eq!(map["Notification"], "AwaitingInput");
+    assert_eq!(map["Stop"], "AwaitingInput");
+    assert_eq!(map["StopFailure"], "Error");
+}
+
+/// A `StopFailure` payload names the API error that ended the turn; the
+/// script reports its `error` spelling as the report's `detail` so a card
+/// can show why (#114).
+#[test]
+fn script_reports_the_error_spelling_as_detail() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Error"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"session_id":"abc","hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"Error""#), "{request}");
+    assert!(request.contains(r#""detail":"rate_limit""#), "{request}");
+}
+
+/// An `error` value that is not a plain enum spelling (or a payload without
+/// one at all) must never produce a broken body — no detail is posted.
+#[test]
+fn script_posts_no_detail_for_an_unexpected_error_value() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Error"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"hook_event_name":"StopFailure","error":"429 \"Too Many\" \\ requests"}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"Error""#), "{request}");
+    assert!(!request.contains("detail"), "{request}");
+}
+
+/// Events whose payload carries no error fields post a bare body — never an
+/// empty or stale detail.
+#[test]
+fn script_posts_no_detail_for_events_without_an_error() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["AwaitingInput"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"hook_event_name":"Stop","stop_hook_active":false}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"AwaitingInput""#), "{request}");
+    assert!(!request.contains("detail"), "{request}");
 }
 
 /// A dead or unreachable daemon must never fail — or slow down — a session.
@@ -104,6 +167,7 @@ fn script_ignores_daemon_failure() {
             ("MAESTRO_URL", "http://127.0.0.1:1"),
             ("MAESTRO_SESSION_ID", "00000000-0000-0000-0000-000000000000"),
         ],
+        br#"{"session_id":"x"}"#,
     );
     assert!(out.status.success());
 }
@@ -138,9 +202,10 @@ fn fresh_install_registers_every_event() {
     install(&settings_path(home), &script_path(home)).unwrap();
 
     let cmds = installed_commands(&settings_path(home));
-    assert_eq!(cmds.len(), 3);
+    assert_eq!(cmds.len(), HOOK_EVENTS.len());
     let joined = cmds.join("\n");
-    assert!(joined.contains("Active"));
+    assert_eq!(joined.matches("Active").count(), 2);
+    assert!(joined.contains("Error"));
     assert_eq!(joined.matches("AwaitingInput").count(), 2);
     for cmd in &cmds {
         assert!(cmd.contains(SCRIPT_FILE_NAME));
@@ -158,7 +223,10 @@ fn install_is_idempotent() {
     install(&settings_path(home), &script_path(home)).unwrap();
     let twice = std::fs::read_to_string(settings_path(home)).unwrap();
     assert_eq!(once, twice);
-    assert_eq!(installed_commands(&settings_path(home)).len(), 3);
+    assert_eq!(
+        installed_commands(&settings_path(home)).len(),
+        HOOK_EVENTS.len()
+    );
 }
 
 /// An older maestro entry under the same events is updated in place, not
@@ -188,7 +256,11 @@ fn install_updates_an_older_maestro_hook_in_place() {
     install(&settings, &new_script).unwrap();
 
     let cmds = installed_commands(&settings);
-    assert_eq!(cmds.len(), 3, "old entry replaced, not kept: {cmds:?}");
+    assert_eq!(
+        cmds.len(),
+        HOOK_EVENTS.len(),
+        "old entry replaced, not kept: {cmds:?}"
+    );
     assert!(!cmds.iter().any(|c| c == old_script));
     let root: serde_json::Value =
         serde_json::from_str(&std::fs::read_to_string(&settings).unwrap()).unwrap();
@@ -231,11 +303,11 @@ fn install_preserves_foreign_hooks_and_removes_stale_maestro_ones() {
     assert_eq!(pre[0]["hooks"][0]["command"], "my-own-linter.sh");
     // Stale maestro event gone.
     assert!(root["hooks"].get("UserPromptSubmit").is_none());
-    // Our three events present, nothing else maestro-related anywhere.
+    // Our events present, nothing else maestro-related anywhere.
     let cmds = installed_commands(&settings);
     assert_eq!(
         cmds.iter().filter(|c| c.contains(HOOK_MARKER)).count(),
-        3,
+        HOOK_EVENTS.len(),
         "{cmds:?}"
     );
 }

crates/maestro-protocol/src/display.rs

@@ -0,0 +1,321 @@
+//! Path-abbreviation helpers shared by every client that renders a session's
+//! directory (CLI, TUI, web (#117)). Ports of `web/src/types.ts` and
+//! `web/src/tree.ts`'s `abbreviateCwd`, `abbreviateFolderName`, `mergeLinear`,
+//! and `sessionTreePath` — keep them in sync.
+
+use std::path::{Path, PathBuf};
+
+use crate::Session;
+
+/// Collapse a daemon's home dir to `~`. `home` empty leaves the path
+/// untouched. Mirrors the web's `abbreviateCwd`.
+pub fn abbreviate_dir(path: &Path, home: &str) -> String {
+    let p = path.to_string_lossy();
+    if !home.is_empty() {
+        if p == home {
+            return "~".into();
+        }
+        if let Some(rest) = p.strip_prefix(&format!("{home}/")) {
+            return format!("~/{rest}");
+        }
+    }
+    p.into_owned()
+}
+
+/// Result of [`abbreviate_folder_name`]: the last path segment kept verbatim,
+/// and — when there was something to collapse — the shortened lead-in a
+/// caller can render dimmed (the web's `.folder-stem`).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AbbreviatedFolderName {
+    /// The collapsed earlier segments, joined by `/`, with no trailing
+    /// slash. `None` when `name` had two or fewer segments — nothing to
+    /// gain from collapsing, so `last` carries the name unabbreviated.
+    pub stem: Option<String>,
+    pub last: String,
+}
+
+/// `~/git.naps.pt/naps62/maestro` → stem `~/g/n`, last `maestro`: keep the
+/// last segment verbatim, collapse every earlier one to its first character.
+/// Two-or-fewer segments are left alone. Mirrors the web's
+/// `abbreviateFolderName`, minus the HTML escaping/wrapping — a ratatui
+/// caller styles `stem` dim itself rather than parsing markup out of it.
+pub fn abbreviate_folder_name(name: &str) -> AbbreviatedFolderName {
+    let parts: Vec<&str> = name.split('/').collect();
+    if parts.len() <= 2 {
+        return AbbreviatedFolderName {
+            stem: None,
+            last: name.to_string(),
+        };
+    }
+    let last = parts[parts.len() - 1].to_string();
+    let stem = parts[..parts.len() - 1]
+        .iter()
+        .map(|p| {
+            if *p == "~" {
+                "~".to_string()
+            } else {
+                p.chars().next().map(String::from).unwrap_or_default()
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("/");
+    AbbreviatedFolderName {
+        stem: Some(stem),
+        last,
+    }
+}
+
+/// The directory a session lives in: its live `current_cwd` if the daemon
+/// has observed one, else the spawn `cwd`. Mirrors the web's `sessionCwd`.
+fn session_cwd(s: &Session) -> Option<PathBuf> {
+    if let Some(cur) = &s.current_cwd {
+        if !cur.as_os_str().is_empty() {
+            return Some(cur.clone());
+        }
+    }
+    if !s.cwd.as_os_str().is_empty() {
+        return Some(s.cwd.clone());
+    }
+    None
+}
+
+/// Where a session sits in the directory tree. A worktree session belongs to
+/// its repository, not to the worktree (#99): otherwise `~/tea/agent-skills`
+/// grows a `~/tea/agent-skills/worktrees/largo-clarinet` folder holding one
+/// session of the same name, and the repository stops being where you look
+/// for the work. Mirrors the web's `sessionTreePath`.
+pub fn session_tree_path(s: &Session) -> Option<PathBuf> {
+    if let Some(wt) = &s.worktree {
+        return Some(wt.base_repo.clone());
+    }
+    session_cwd(s)
+}
+
+/// One node of a directory tree grouping sessions by path, generic over the
+/// leaf payload since building the tree itself (grouping key, sort order,
+/// filtering) is not this crate's job — only [`merge_linear`] is.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TreeNode<T> {
+    Folder(TreeFolder<T>),
+    Leaf(T),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TreeFolder<T> {
+    pub name: String,
+    pub path: String,
+    pub children: Vec<TreeNode<T>>,
+}
+
+/// Fold a folder with a single folder-child into one node (`a` + `b` →
+/// `a/b`), repeating down the chain, then recurse into the surviving
+/// branches. The merged node keeps the deepest path so collapse/expand state
+/// stays stable as it grows. Mirrors the web's `mergeLinear`.
+pub fn merge_linear<T>(folder: TreeFolder<T>) -> TreeFolder<T> {
+    let mut cur = folder;
+    loop {
+        let single_folder_child =
+            cur.children.len() == 1 && matches!(cur.children[0], TreeNode::Folder(_));
+        if !single_folder_child {
+            break;
+        }
+        let child = match cur.children.pop().expect("checked len == 1 above") {
+            TreeNode::Folder(f) => f,
+            TreeNode::Leaf(_) => unreachable!("checked matches! above"),
+        };
+        cur = TreeFolder {
+            name: format!("{}/{}", cur.name, child.name),
+            path: child.path,
+            children: child.children,
+        };
+    }
+    cur.children = cur
+        .children
+        .into_iter()
+        .map(|c| match c {
+            TreeNode::Folder(f) => TreeNode::Folder(merge_linear(f)),
+            leaf => leaf,
+        })
+        .collect();
+    cur
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{SessionStatus, SessionWorktree};
+    use chrono::{TimeZone, Utc};
+    use std::collections::HashMap;
+    use uuid::Uuid;
+
+    fn session(cwd: &str) -> Session {
+        Session {
+            id: Uuid::from_u128(1),
+            cwd: PathBuf::from(cwd),
+            command: "bash".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+            status: SessionStatus::Running,
+            created_at: Utc.with_ymd_and_hms(2026, 8, 25, 12, 0, 0).unwrap(),
+            foreground: None,
+            activity: Default::default(),
+            activity_detail: None,
+            last_activity_at: Utc::now(),
+            activity_since: Utc::now(),
+            current_cwd: None,
+            blocked_work: None,
+        }
+    }
+
+    #[test]
+    fn abbreviate_dir_collapses_home() {
+        assert_eq!(
+            abbreviate_dir(Path::new("/home/naps/maestro"), "/home/naps"),
+            "~/maestro"
+        );
+        assert_eq!(abbreviate_dir(Path::new("/home/naps"), "/home/naps"), "~");
+    }
+
+    #[test]
+    fn abbreviate_dir_leaves_paths_outside_home_untouched() {
+        assert_eq!(
+            abbreviate_dir(Path::new("/srv/work/api"), "/home/naps"),
+            "/srv/work/api"
+        );
+        assert_eq!(
+            abbreviate_dir(Path::new("/srv/work/api"), ""),
+            "/srv/work/api"
+        );
+    }
+
+    #[test]
+    fn abbreviate_folder_name_collapses_the_stem() {
+        let got = abbreviate_folder_name("~/git.naps.pt/naps62/maestro");
+        assert_eq!(
+            got,
+            AbbreviatedFolderName {
+                stem: Some("~/g/n".into()),
+                last: "maestro".into(),
+            }
+        );
+    }
+
+    /// Two-or-fewer segments are left alone — nothing to gain from collapsing.
+    #[test]
+    fn abbreviate_folder_name_two_segment_no_op() {
+        assert_eq!(
+            abbreviate_folder_name("~/work"),
+            AbbreviatedFolderName {
+                stem: None,
+                last: "~/work".into(),
+            }
+        );
+        assert_eq!(
+            abbreviate_folder_name("work"),
+            AbbreviatedFolderName {
+                stem: None,
+                last: "work".into(),
+            }
+        );
+    }
+
+    #[test]
+    fn session_tree_path_prefers_worktree_base_repo() {
+        let mut s = session("/home/n/tea/agent-skills/worktrees/largo-clarinet");
+        s.worktree = Some(SessionWorktree {
+            path: PathBuf::from("/home/n/tea/agent-skills/worktrees/largo-clarinet"),
+            base_repo: PathBuf::from("/home/n/tea/agent-skills"),
+        });
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/agent-skills"))
+        );
+    }
+
+    #[test]
+    fn session_tree_path_falls_back_to_cwd_without_a_worktree() {
+        let s = session("/home/n/tea/arr");
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/arr"))
+        );
+    }
+
+    #[test]
+    fn session_tree_path_prefers_live_current_cwd_over_spawn_cwd() {
+        let mut s = session("/home/n/tea/arr");
+        s.current_cwd = Some(PathBuf::from("/home/n/tea/arr/crates"));
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/arr/crates"))
+        );
+    }
+
+    fn leaf(name: &str) -> TreeNode<String> {
+        TreeNode::Leaf(name.into())
+    }
+
+    fn folder(name: &str, path: &str, children: Vec<TreeNode<String>>) -> TreeFolder<String> {
+        TreeFolder {
+            name: name.into(),
+            path: path.into(),
+            children,
+        }
+    }
+
+    /// The web's mergeLinear test: keeps the deepest path so collapse state
+    /// survives growth.
+    #[test]
+    fn merge_linear_folds_a_chain_and_keeps_the_deepest_path() {
+        let tree = folder("a", "a", vec![TreeNode::Folder(folder("b", "a/b", vec![]))]);
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "a/b");
+        assert_eq!(merged.path, "a/b");
+    }
+
+    #[test]
+    fn merge_linear_stops_where_a_directory_branches() {
+        let tree = folder(
+            "git",
+            "git",
+            vec![
+                TreeNode::Folder(folder("one", "git/one", vec![])),
+                TreeNode::Folder(folder("two", "git/two", vec![])),
+            ],
+        );
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "git");
+        assert_eq!(merged.children.len(), 2);
+    }
+
+    #[test]
+    fn merge_linear_stops_at_a_leaf() {
+        let tree = folder("a", "a", vec![leaf("session")]);
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "a");
+        assert_eq!(merged.children, vec![leaf("session")]);
+    }
+
+    #[test]
+    fn merge_linear_recurses_into_surviving_branches() {
+        let tree = folder(
+            "root",
+            "root",
+            vec![
+                TreeNode::Folder(folder(
+                    "a",
+                    "root/a",
+                    vec![TreeNode::Folder(folder("b", "root/a/b", vec![leaf("s")]))],
+                )),
+                leaf("other"),
+            ],
+        );
+        let merged = merge_linear(tree);
+        assert_eq!(merged.children.len(), 2);
+        let TreeNode::Folder(nested) = &merged.children[0] else {
+            panic!("expected folder")
+        };
+        assert_eq!(nested.name, "a/b");
+    }
+}

crates/maestro-protocol/src/lib.rs

@@ -9,6 +9,7 @@
 
 #[cfg(feature = "client")]
 pub mod client;
+pub mod display;
 pub mod routes;
 
 #[cfg(feature = "client")]

crates/maestro-tui/src/action.rs

@@ -34,6 +34,7 @@ pub enum Action {
     // Sidebar highlight movement
     SidebarNext,
     SidebarPrev,
+    ToggleSidebarGroup,
 
     // Catalog actions on the highlighted sidebar row
     AttachHighlighted,
@@ -81,6 +82,7 @@ impl Action {
             "FocusSidebar" => return Ok(Action::FocusSidebar),
             "SidebarNext" => return Ok(Action::SidebarNext),
             "SidebarPrev" => return Ok(Action::SidebarPrev),
+            "ToggleSidebarGroup" => return Ok(Action::ToggleSidebarGroup),
             "AttachHighlighted" => return Ok(Action::AttachHighlighted),
             "ToggleAttachHighlighted" => return Ok(Action::ToggleAttachHighlighted),
             "NewDraftPane" => return Ok(Action::NewDraftPane),

crates/maestro-tui/src/app.rs

@@ -30,14 +30,16 @@ use crate::catalog::CatalogStore;
 use crate::config::TuiConfig;
 use crate::draft::DraftInputResult;
 use crate::emulators::SessionEmulators;
-use crate::input::{canonicalise, ChordResult, ChordState, ClickTracker, InputKey};
+use crate::input::{
+    canonicalise, ChordResult, ChordState, ClickTracker, InputKey, MouseKind, Region,
+};
 use crate::keymap::Mode;
 use crate::overlays::HelpOverlay;
 use crate::pane::{Pane, PaneStatus};
 use crate::render::{draw, RegionMap, RenderInputs};
 use crate::session_task::{SessionInput, SessionTask};
 use crate::sidebar::Sidebar;
-use crate::state::{AppState, Focus, OverlayKind, PaneRef};
+use crate::state::{AppState, Focus, OverlayKind, PaneRef, SidebarItem};
 use crate::tabs::TabBar;
 use crate::worktrees::WorktreesView;
 use crate::TuiError;
@@ -52,6 +54,7 @@ enum OverlayDecision {
 
 pub struct App {
     cfg: TuiConfig,
+    home_dir: String,
     catalog: CatalogStore,
     emulators: SessionEmulators,
     state: AppState,
@@ -137,6 +140,7 @@ impl App {
             .expect("build reqwest client");
         Self {
             cfg,
+            home_dir: std::env::var("HOME").unwrap_or_default(),
             catalog,
             emulators: SessionEmulators::default(),
             state: AppState::new(),
@@ -158,6 +162,9 @@ impl App {
         mut self,
         terminal: &mut Terminal<CrosstermBackend<Stdout>>,
     ) -> Result<(), TuiError> {
+        if let Ok(info) = self.daemon.daemon_info().await {
+            self.home_dir = info.home_dir;
+        }
         let mut events = EventStream::new();
         loop {
             self.redraw(terminal)?;
@@ -197,6 +204,10 @@ impl App {
             return Ok(false);
         }
 
+        if self.handle_sidebar_mouse(&key) {
+            return Ok(false);
+        }
+
         let known = self.cfg.keymap.known_bindings(self.state.mode);
         match self.chord.feed(&key, &known) {
             ChordResult::Pending => Ok(false),
@@ -224,6 +235,34 @@ impl App {
         }
     }
 
+    /// Clicks select rendered sidebar items directly. Double-clicks continue
+    /// through the keymap so the configured attach binding remains intact.
+    fn handle_sidebar_mouse(&mut self, key: &InputKey) -> bool {
+        let InputKey::Mouse {
+            kind: MouseKind::Click,
+            region: Region::SidebarRow,
+            row,
+            ..
+        } = key
+        else {
+            return false;
+        };
+        let Some(item) = self.region.sidebar_item_at(*row) else {
+            return true;
+        };
+        self.state.focus = Focus::Sidebar;
+        match item {
+            SidebarItem::Group(key) => {
+                self.state.sidebar_highlight = Some(SidebarItem::Group(key.clone()));
+                self.toggle_sidebar_group(key);
+            }
+            SidebarItem::Session(id) => {
+                self.state.sidebar_highlight = Some(SidebarItem::Session(id));
+            }
+        }
+        true
+    }
+
     /// Carry out what `dispatch` decided. The only place in `App` that talks to
     /// the daemon.
     async fn perform(&mut self, effects: Vec<Effect>) {
@@ -330,15 +369,22 @@ impl App {
                 self.state.focus = Focus::Pane;
             }
             Action::SidebarNext => {
-                let order = visible_sidebar_order(&self.catalog.snapshot());
+                let order = visible_sidebar_order(
+                    &self.catalog.snapshot(),
+                    &self.state.collapsed_sidebar_groups,
+                );
                 self.state.move_sidebar_highlight(&order, 1);
                 self.state.focus = Focus::Sidebar;
             }
             Action::SidebarPrev => {
-                let order = visible_sidebar_order(&self.catalog.snapshot());
+                let order = visible_sidebar_order(
+                    &self.catalog.snapshot(),
+                    &self.state.collapsed_sidebar_groups,
+                );
                 self.state.move_sidebar_highlight(&order, -1);
                 self.state.focus = Focus::Sidebar;
             }
+            Action::ToggleSidebarGroup => self.toggle_highlighted_sidebar_group(),
             Action::NewTab => self.state.new_tab(),
             Action::CloseTab => {
                 if let Some(sid) = self.state.close_tab() {
@@ -403,13 +449,50 @@ impl App {
     /// Return the session under the sidebar highlight, falling back to the
     /// first listed session so the user can attach without arrowing first.
     fn pick_sidebar_target(&self) -> Option<Uuid> {
-        if let Some(sid) = self.state.sidebar_highlight {
+        if let Some(SidebarItem::Session(sid)) = self.state.sidebar_highlight {
             return Some(sid);
         }
+        if self.state.sidebar_highlight.is_some() {
+            return None;
+        }
         let snap = self.catalog.snapshot();
         snap.sessions.first().map(|s| s.id)
     }
 
+    fn toggle_highlighted_sidebar_group(&mut self) {
+        let key = match self.state.sidebar_highlight.clone() {
+            Some(SidebarItem::Group(key)) => Some(key),
+            Some(SidebarItem::Session(id)) => self
+                .catalog
+                .snapshot()
+                .sessions
+                .into_iter()
+                .find(|s| s.id == id)
+                .and_then(|s| maestro_protocol::display::session_tree_path(&s)),
+            None => None,
+        };
+        if let Some(key) = key {
+            self.toggle_sidebar_group(key);
+        }
+    }
+
+    fn toggle_sidebar_group(&mut self, key: PathBuf) {
+        let contains_highlight = match self.state.sidebar_highlight {
+            Some(SidebarItem::Session(id)) => {
+                self.catalog
+                    .snapshot()
+                    .sessions
+                    .iter()
+                    .find(|s| s.id == id)
+                    .and_then(maestro_protocol::display::session_tree_path)
+                    .as_ref()
+                    == Some(&key)
+            }
+            _ => false,
+        };
+        self.state.toggle_sidebar_group(key, contains_highlight);
+    }
+
     /// Encode a keystroke for the focused pane. `None` when there is nothing
     /// attached to send it to.
     fn forward_to_session(&mut self, key: &InputKey) -> Option<Effect> {
@@ -811,7 +894,7 @@ impl App {
             .collect();
         let sidebar = Sidebar {
             sessions: snap.sessions.clone(),
-            highlight: self.state.sidebar_highlight,
+            highlight: self.state.sidebar_highlight.clone(),
             attached,
         };
         let tab_bar = TabBar {
@@ -833,6 +916,7 @@ impl App {
 
         let inputs = RenderInputs {
             sidebar: &sidebar,
+            home_dir: &self.home_dir,
             tab_bar: &tab_bar,
             pane: pane.as_ref(),
             state: &self.state,
@@ -881,8 +965,16 @@ impl App {
 /// Order the sidebar walks for `j`/`k`: the sessions in the same order
 /// [`crate::sidebar::Sidebar::render`] emits them. Keeps highlight movement in
 /// visual sync with what the user sees.
-fn visible_sidebar_order(snap: &crate::catalog::CatalogSnapshot) -> Vec<Uuid> {
-    snap.sessions.iter().map(|s| s.id).collect()
+fn visible_sidebar_order(
+    snap: &crate::catalog::CatalogSnapshot,
+    collapsed: &std::collections::HashSet<PathBuf>,
+) -> Vec<SidebarItem> {
+    Sidebar {
+        sessions: snap.sessions.clone(),
+        highlight: None,
+        attached: HashSet::new(),
+    }
+    .rendered_items_with_collapsed(collapsed)
 }
 
 /// Wire encoding for a keystroke headed to a session's PTY. `None` for keys
@@ -1134,9 +1226,32 @@ mod tests {
             }],
         });
         app.dispatch(Action::SidebarNext);
+        app.dispatch(Action::SidebarNext);
         app
     }
 
+    fn test_session(sid: Uuid, cwd: &str) -> maestro_protocol::Session {
+        use chrono::Utc;
+        use maestro_protocol::{Session, SessionStatus};
+        Session {
+            id: sid,
+            command: "bash".into(),
+            cwd: cwd.into(),
+            env: Default::default(),
+            metadata: Default::default(),
+            worktree: None,
+            status: SessionStatus::Running,
+            created_at: Utc::now(),
+            foreground: None,
+            activity: Default::default(),
+            activity_detail: None,
+            last_activity_at: Utc::now(),
+            activity_since: Utc::now(),
+            current_cwd: None,
+            blocked_work: None,
+        }
+    }
+
     #[test]
     fn attach_highlighted_asks_for_an_attach() {
         let sid = Uuid::from_u128(11);
@@ -1148,6 +1263,94 @@ mod tests {
         assert_eq!(app.state.active_tab().session(), Some(sid));
     }
 
+    #[test]
+    fn group_highlight_is_not_a_session_action_target() {
+        use maestro_protocol::CatalogEvent;
+
+        let sid = Uuid::from_u128(14);
+        let mut app = make_app();
+        app.catalog.apply_event(CatalogEvent::Snapshot {
+            sessions: vec![test_session(sid, "/repo")],
+        });
+        app.dispatch(Action::SidebarNext);
+        assert_eq!(
+            app.state.sidebar_highlight,
+            Some(SidebarItem::Group(PathBuf::from("/repo")))
+        );
+        assert!(app.dispatch(Action::AttachHighlighted).is_empty());
+        assert!(app.dispatch(Action::KillHighlighted).is_empty());
+        assert!(app.state.overlay().is_none());
+    }
+
+    #[test]
+    fn collapsing_the_group_containing_a_card_highlight_keeps_a_visible_group_highlight() {
+        let sid = Uuid::from_u128(15);
+        let mut app = app_with_highlighted_session(sid);
+        assert_eq!(app.state.sidebar_highlight, Some(SidebarItem::Session(sid)));
+        assert!(app.dispatch(Action::ToggleSidebarGroup).is_empty());
+        assert_eq!(
+            app.state.sidebar_highlight,
+            Some(SidebarItem::Group(PathBuf::from("/")))
+        );
+        assert!(app
+            .state
+            .collapsed_sidebar_groups
+            .contains(&PathBuf::from("/")));
+        assert_eq!(app.state.focus, Focus::Sidebar);
+    }
+
+    #[test]
+    fn clicking_a_group_toggles_it_and_selects_the_group() {
+        let sid = Uuid::from_u128(16);
+        let mut app = app_with_highlighted_session(sid);
+        app.region.sidebar = Some(ratatui::layout::Rect::new(0, 0, 28, 10));
+        app.region.sidebar_items = vec![SidebarItem::Group(PathBuf::from("/"))];
+        let click = InputKey::Mouse {
+            kind: MouseKind::Click,
+            region: Region::SidebarRow,
+            col: 3,
+            row: 2,
+        };
+        assert!(app.handle_sidebar_mouse(&click));
+        assert_eq!(
+            app.state.sidebar_highlight,
+            Some(SidebarItem::Group(PathBuf::from("/")))
+        );
+        assert!(app
+            .state
+            .collapsed_sidebar_groups
+            .contains(&PathBuf::from("/")));
+        assert_eq!(app.state.focus, Focus::Sidebar);
+    }
+
+    #[tokio::test]
+    async fn sidebar_click_dismisses_a_toast_before_handling_the_click() {
+        use crossterm::event::{MouseButton, MouseEvent, MouseEventKind};
+
+        let sid = Uuid::from_u128(17);
+        let mut app = app_with_highlighted_session(sid);
+        app.state.toast("notice");
+        app.region.sidebar = Some(ratatui::layout::Rect::new(0, 0, 28, 10));
+        app.region.sidebar_items = vec![SidebarItem::Group(PathBuf::from("/"))];
+
+        let quit = app
+            .handle_event(CtEvent::Mouse(MouseEvent {
+                kind: MouseEventKind::Down(MouseButton::Left),
+                column: 3,
+                row: 2,
+                modifiers: crossterm::event::KeyModifiers::NONE,
+            }))
+            .await
+            .unwrap();
+
+        assert!(!quit);
+        assert!(app.state.overlay().is_none());
+        assert!(app
+            .state
+            .collapsed_sidebar_groups
+            .contains(&PathBuf::from("/")));
+    }
+
     #[test]
     fn confirming_a_kill_asks_for_the_kill() {
         let sid = Uuid::from_u128(12);

crates/maestro-tui/src/config.rs

@@ -8,13 +8,15 @@
 
 use std::time::Duration;
 
-use maestro_config::TuiSection;
+use maestro_config::{TuiSection, TuiTheme};
 
 use crate::input::InputKey;
 use crate::keymap::{Keymap, KeymapError, Mode};
+use crate::palette::Palette;
 
 #[derive(Debug)]
 pub struct TuiConfig {
+    pub palette: Palette,
     pub leader: InputKey,
     pub chord_timeout: Duration,
     pub keymap: Keymap,
@@ -43,6 +45,7 @@ const DEFAULT_NORMAL: &[(&str, &str)] = &[
     ("k", "SidebarPrev"),
     ("down", "SidebarNext"),
     ("up", "SidebarPrev"),
+    ("c", "ToggleSidebarGroup"),
     // Catalog actions
     ("enter", "AttachHighlighted"),
     ("s", "NewDraftPane"),
@@ -76,6 +79,11 @@ impl TuiConfig {
     /// field of the loaded `MaestroConfigFile`). The shipped defaults are
     /// applied first, then user overrides on top.
     pub fn load(section: &TuiSection) -> Result<Self, TuiConfigError> {
+        let palette = match section.theme.unwrap_or(TuiTheme::Dark) {
+            TuiTheme::Dark => Palette::DARK,
+            TuiTheme::Light => Palette::LIGHT,
+            TuiTheme::Ansi => Palette::ANSI,
+        };
         let leader_str = section.leader.as_deref().unwrap_or("ctrl-a");
         let leader = InputKey::parse(leader_str)
             .map_err(|_| TuiConfigError::BadLeader(leader_str.to_string()))?;
@@ -131,6 +139,7 @@ impl TuiConfig {
         }
 
         Ok(TuiConfig {
+            palette,
             leader,
             chord_timeout,
             keymap,
@@ -143,6 +152,28 @@ impl TuiConfig {
 mod tests {
     use super::*;
     use crate::action::Action;
+    use maestro_config::{TuiSection, TuiTheme};
+
+    #[test]
+    fn absent_theme_selects_the_dark_default() {
+        let cfg = TuiConfig::load(&TuiSection::default()).unwrap();
+        assert_eq!(cfg.palette, Palette::DARK);
+    }
+
+    #[test]
+    fn named_themes_select_the_matching_complete_palette() {
+        for (theme, expected) in [
+            (TuiTheme::Dark, Palette::DARK),
+            (TuiTheme::Light, Palette::LIGHT),
+            (TuiTheme::Ansi, Palette::ANSI),
+        ] {
+            let section = TuiSection {
+                theme: Some(theme),
+                ..Default::default()
+            };
+            assert_eq!(TuiConfig::load(&section).unwrap().palette, expected);
+        }
+    }
 
     #[test]
     fn defaults_cover_core_actions() {

crates/maestro-tui/src/draft.rs

@@ -41,7 +41,7 @@ use chrono::{DateTime, Utc};
 use maestro_config::{builtin_presets, custom_preset};
 use maestro_protocol::{BranchInfo, CreateSessionRequest, Project, SpawnPreset, WorktreeSpec};
 use ratatui::layout::{Constraint, Layout, Rect};
-use ratatui::style::{Color, Modifier, Style};
+use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph};
 use ratatui::Frame;
@@ -1510,7 +1510,7 @@ impl DraftPane {
             f.render_widget(
                 Paragraph::new(Line::from(Span::styled(
                     format!("error: {error}"),
-                    Style::default().fg(Color::Red),
+                    crate::palette::active().error_style(),
                 ))),
                 row,
             );

crates/maestro-tui/src/lib.rs

@@ -13,6 +13,7 @@ pub mod fast_forward;
 pub mod input;
 pub mod keymap;
 pub mod overlays;
+pub mod palette;
 pub mod pane;
 pub mod projects;
 pub mod render;
@@ -89,6 +90,7 @@ pub async fn run(cfg: RunConfig) -> Result<(), TuiError> {
         Err(_) => maestro_config::MaestroConfigFile::default(),
     };
     let tui_cfg = TuiConfig::load(&cfg_file.tui).map_err(|e| TuiError::Config(e.to_string()))?;
+    palette::set_active(tui_cfg.palette);
 
     let catalog = CatalogStore::default();
     let ws_url = daemon

crates/maestro-tui/src/palette.rs

@@ -0,0 +1,501 @@
+//! Named colour roles for the TUI.
+//!
+//! Every colour the TUI paints on its own chrome comes from here, named for
+//! what it means rather than what it looks like: the card surface, the
+//! selection surface, the panel border in its focused and unfocused forms,
+//! the text weights (`fg` / `muted` / `dim`), and one role per
+//! [`ActivityState`]. Call sites ask the palette for a role; they never spell
+//! a colour out.
+//!
+//! Values are [`Color::Rgb`], so contrast is a property of the palette rather
+//! than of the user's terminal theme — and can therefore be asserted (see
+//! [`contrast_ratio`] and this module's tests).
+//!
+//! Each surface carries its own activity colours. A state colour picked for
+//! the dark card background is not legible on the selection background, so
+//! the selected card uses the selection surface's own state colours; the dot
+//! keeps carrying the state either way (docs/SIDEBAR.md).
+//!
+//! [`Palette::DARK`] is the default. [`Palette::LIGHT`] is its light peer and
+//! [`Palette::ANSI`] uses terminal-provided ANSI colours.
+//!
+//! Out of scope: PTY cell colours. Those belong to the program running in the
+//! pane and pass through `pane::translate_color` verbatim.
+
+use maestro_protocol::ActivityState;
+use ratatui::style::{Color, Modifier, Style};
+
+/// A background and the foreground roles legible on it.
+///
+/// The sidebar has two: the card surface every card sits on, and the
+/// selection surface the highlighted card swaps in.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Surface {
+    /// The surface itself.
+    pub bg: Color,
+    /// Primary text on this surface.
+    pub fg: Color,
+    /// Secondary text — the blocked-work, exited, detail and command
+    /// fragments of a card's meta line.
+    pub muted: Color,
+    /// The quietest legible text on this surface, for decoration that must
+    /// not compete with content.
+    pub dim: Color,
+    /// `ActivityState::Active`.
+    pub active: Color,
+    /// `ActivityState::Idle`.
+    pub idle: Color,
+    /// `ActivityState::AwaitingInput`.
+    pub awaiting: Color,
+    /// `ActivityState::Error`.
+    pub error: Color,
+}
+
+impl Surface {
+    /// The bare surface: a background with no foreground override.
+    pub fn base(&self) -> Style {
+        Style::default().bg(self.bg)
+    }
+
+    /// Primary text on this surface.
+    pub fn text_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.fg)
+    }
+
+    /// Secondary text on this surface.
+    pub fn muted_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.muted)
+    }
+
+    /// The quietest text on this surface.
+    pub fn dim_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.dim)
+    }
+
+    /// The colour carrying `state` on this surface.
+    pub fn activity(&self, state: ActivityState) -> Color {
+        match state {
+            ActivityState::Active => self.active,
+            ActivityState::Idle => self.idle,
+            ActivityState::AwaitingInput => self.awaiting,
+            ActivityState::Error => self.error,
+        }
+    }
+
+    /// Every foreground role on this surface, paired with its role name.
+    /// Used by the contrast tests, and by anything that needs to reason about
+    /// the surface as a whole.
+    pub fn roles(&self) -> [(&'static str, Color); 7] {
+        [
+            ("fg", self.fg),
+            ("muted", self.muted),
+            ("dim", self.dim),
+            ("active", self.active),
+            ("idle", self.idle),
+            ("awaiting", self.awaiting),
+            ("error", self.error),
+        ]
+    }
+}
+
+/// The full set of colour roles the TUI paints with.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Palette {
+    /// The surface an unselected card sits on.
+    pub card: Surface,
+    /// The surface the highlighted card swaps in.
+    pub selection: Surface,
+    /// Background for TUI-owned chrome outside cards. Fixed-RGB chrome must
+    /// paint this background too; otherwise its contrast depends on the
+    /// operator's terminal theme.
+    pub chrome_bg: Color,
+    /// Panel border while that panel holds focus.
+    pub border_focused: Color,
+    /// Panel border while it does not.
+    pub border_unfocused: Color,
+    /// Focus affordances that are not the border itself — markers, titles and
+    /// the like on the panel that holds focus.
+    pub focus_accent: Color,
+    /// Sidebar group headings.
+    pub group_row: Color,
+    /// Status-bar mode indicator, normal mode.
+    pub mode_normal_bg: Color,
+    pub mode_normal_fg: Color,
+    /// Status-bar mode indicator, insert mode.
+    pub mode_insert_bg: Color,
+    pub mode_insert_fg: Color,
+    /// Error text outside a card — form errors, failed actions.
+    pub error_text: Color,
+}
+
+impl Palette {
+    /// The dark terminal-native palette and the default preset.
+    pub const DARK: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x1f, 0x23, 0x2b),
+            fg: Color::Rgb(0xe5, 0xe7, 0xeb),
+            muted: Color::Rgb(0xae, 0xb7, 0xc4),
+            dim: Color::Rgb(0x85, 0x8f, 0x9e),
+            active: Color::Rgb(0x72, 0xd6, 0x87),
+            idle: Color::Rgb(0xae, 0xb7, 0xc4),
+            awaiting: Color::Rgb(0xf2, 0xc9, 0x5c),
+            error: Color::Rgb(0xff, 0x82, 0x7a),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x3d, 0x51, 0x44),
+            fg: Color::Rgb(0xf3, 0xf7, 0xf4),
+            muted: Color::Rgb(0xd0, 0xd9, 0xd3),
+            dim: Color::Rgb(0xa1, 0xb0, 0xa6),
+            active: Color::Rgb(0x9a, 0xf0, 0xa6),
+            idle: Color::Rgb(0xc4, 0xcf, 0xc7),
+            awaiting: Color::Rgb(0xf6, 0xd9, 0x78),
+            error: Color::Rgb(0xff, 0xa8, 0xa3),
+        },
+        chrome_bg: Color::Rgb(0x1f, 0x23, 0x2b),
+        border_focused: Color::Rgb(0x72, 0xd6, 0x87),
+        border_unfocused: Color::Rgb(0x68, 0x73, 0x84),
+        focus_accent: Color::Rgb(0x72, 0xd6, 0x87),
+        group_row: Color::Rgb(0xb6, 0xc1, 0xd3),
+        mode_normal_bg: Color::Rgb(0x72, 0xd6, 0x87),
+        mode_normal_fg: Color::Rgb(0x1f, 0x23, 0x2b),
+        mode_insert_bg: Color::Rgb(0xf2, 0xc9, 0x5c),
+        mode_insert_fg: Color::Rgb(0x1f, 0x23, 0x2b),
+        error_text: Color::Rgb(0xff, 0x82, 0x7a),
+    };
+
+    /// A high-contrast light peer to [`Self::DARK`].
+    pub const LIGHT: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0xff, 0xff, 0xff),
+            fg: Color::Rgb(0x27, 0x31, 0x3d),
+            muted: Color::Rgb(0x4c, 0x5b, 0x6b),
+            dim: Color::Rgb(0x68, 0x78, 0x8a),
+            active: Color::Rgb(0x21, 0x7a, 0x3c),
+            idle: Color::Rgb(0x4c, 0x5b, 0x6b),
+            awaiting: Color::Rgb(0x8f, 0x63, 0x00),
+            error: Color::Rgb(0xb4, 0x23, 0x18),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0xb5, 0xcf, 0xba),
+            fg: Color::Rgb(0x1d, 0x2a, 0x24),
+            muted: Color::Rgb(0x3f, 0x55, 0x45),
+            dim: Color::Rgb(0x52, 0x68, 0x5a),
+            active: Color::Rgb(0x15, 0x5b, 0x2e),
+            idle: Color::Rgb(0x3f, 0x55, 0x45),
+            awaiting: Color::Rgb(0x69, 0x46, 0x00),
+            error: Color::Rgb(0xa5, 0x1d, 0x14),
+        },
+        chrome_bg: Color::Rgb(0xff, 0xff, 0xff),
+        border_focused: Color::Rgb(0x21, 0x7a, 0x3c),
+        border_unfocused: Color::Rgb(0x65, 0x73, 0x6b),
+        focus_accent: Color::Rgb(0x21, 0x7a, 0x3c),
+        group_row: Color::Rgb(0x3f, 0x55, 0x45),
+        mode_normal_bg: Color::Rgb(0x21, 0x7a, 0x3c),
+        mode_normal_fg: Color::Rgb(0xff, 0xff, 0xff),
+        mode_insert_bg: Color::Rgb(0xb6, 0x81, 0x08),
+        mode_insert_fg: Color::Rgb(0x0b, 0x12, 0x0e),
+        error_text: Color::Rgb(0xb4, 0x23, 0x18),
+    };
+
+    /// A palette of named ANSI colours for terminals without truecolour.
+    pub const ANSI: Palette = Palette {
+        card: Surface {
+            bg: Color::Black,
+            fg: Color::White,
+            muted: Color::Gray,
+            dim: Color::DarkGray,
+            active: Color::Green,
+            idle: Color::Gray,
+            awaiting: Color::Yellow,
+            error: Color::Red,
+        },
+        selection: Surface {
+            bg: Color::Blue,
+            fg: Color::White,
+            muted: Color::White,
+            dim: Color::LightBlue,
+            active: Color::LightGreen,
+            idle: Color::White,
+            awaiting: Color::LightYellow,
+            error: Color::LightRed,
+        },
+        chrome_bg: Color::Black,
+        border_focused: Color::LightGreen,
+        border_unfocused: Color::DarkGray,
+        focus_accent: Color::LightGreen,
+        group_row: Color::LightCyan,
+        mode_normal_bg: Color::Green,
+        mode_normal_fg: Color::Black,
+        mode_insert_bg: Color::Yellow,
+        mode_insert_fg: Color::Black,
+        error_text: Color::LightRed,
+    };
+
+    /// The default preset, retained as a named compatibility constant.
+    pub const DEFAULT: Palette = Self::DARK;
+
+    /// All preset names and their complete palettes.
+    pub fn presets() -> [(&'static str, Palette); 3] {
+        [
+            ("dark", Self::DARK),
+            ("light", Self::LIGHT),
+            ("ansi", Self::ANSI),
+        ]
+    }
+
+    /// Resolve a config name to a palette.
+    pub fn named(name: &str) -> Option<Palette> {
+        match name {
+            "dark" => Some(Self::DARK),
+            "light" => Some(Self::LIGHT),
+            "ansi" => Some(Self::ANSI),
+            _ => None,
+        }
+    }
+
+    /// Every role, including the backgrounds it is painted against.
+    pub fn roles(&self) -> [(&'static str, Color); 26] {
+        [
+            ("card.bg", self.card.bg),
+            ("card.fg", self.card.fg),
+            ("card.muted", self.card.muted),
+            ("card.dim", self.card.dim),
+            ("card.active", self.card.active),
+            ("card.idle", self.card.idle),
+            ("card.awaiting", self.card.awaiting),
+            ("card.error", self.card.error),
+            ("selection.bg", self.selection.bg),
+            ("selection.fg", self.selection.fg),
+            ("selection.muted", self.selection.muted),
+            ("selection.dim", self.selection.dim),
+            ("selection.active", self.selection.active),
+            ("selection.idle", self.selection.idle),
+            ("selection.awaiting", self.selection.awaiting),
+            ("selection.error", self.selection.error),
+            ("chrome_bg", self.chrome_bg),
+            ("border_focused", self.border_focused),
+            ("border_unfocused", self.border_unfocused),
+            ("focus_accent", self.focus_accent),
+            ("group_row", self.group_row),
+            ("mode_normal_bg", self.mode_normal_bg),
+            ("mode_normal_fg", self.mode_normal_fg),
+            ("mode_insert_bg", self.mode_insert_bg),
+            ("mode_insert_fg", self.mode_insert_fg),
+            ("error_text", self.error_text),
+        ]
+    }
+
+    /// The surface a card sits on: the selection surface when it is the
+    /// highlighted card, the card surface otherwise.
+    pub fn surface(&self, selected: bool) -> &Surface {
+        if selected {
+            &self.selection
+        } else {
+            &self.card
+        }
+    }
+
+    /// Border style for a panel, by whether it holds focus.
+    pub fn border_style(&self, focused: bool) -> Style {
+        if focused {
+            Style::default().bg(self.chrome_bg).fg(self.border_focused)
+        } else {
+            Style::default()
+                .bg(self.chrome_bg)
+                .fg(self.border_unfocused)
+        }
+    }
+
+    /// Style for a sidebar group heading.
+    pub fn group_row_style(&self) -> Style {
+        Style::default()
+            .bg(self.chrome_bg)
+            .fg(self.group_row)
+            .add_modifier(Modifier::BOLD)
+    }
+
+    /// Style for the status bar's mode indicator.
+    pub fn mode_style(&self, insert: bool) -> Style {
+        if insert {
+            Style::default()
+                .fg(self.mode_insert_fg)
+                .bg(self.mode_insert_bg)
+        } else {
+            Style::default()
+                .fg(self.mode_normal_fg)
+                .bg(self.mode_normal_bg)
+        }
+    }
+
+    /// Style for error text outside a card.
+    pub fn error_style(&self) -> Style {
+        Style::default().bg(self.chrome_bg).fg(self.error_text)
+    }
+}
+
+impl Default for Palette {
+    fn default() -> Self {
+        Self::DEFAULT
+    }
+}
+
+fn active_slot() -> &'static std::sync::RwLock<Palette> {
+    static ACTIVE: std::sync::OnceLock<std::sync::RwLock<Palette>> = std::sync::OnceLock::new();
+    ACTIVE.get_or_init(|| std::sync::RwLock::new(Palette::DEFAULT))
+}
+
+/// Set the palette used by the running TUI.
+pub(crate) fn set_active(palette: Palette) {
+    *active_slot().write().expect("active palette lock poisoned") = palette;
+}
+
+/// The palette in force. Config-driven preset selection lands here at TUI
+/// startup, before the first frame is drawn.
+pub fn active() -> Palette {
+    *active_slot().read().expect("active palette lock poisoned")
+}
+
+/// WCAG relative luminance of an RGB role. Non-RGB colours have no fixed
+/// luminance — they are whatever the terminal theme says — so they return
+/// `None` and cannot be contrast-checked.
+pub fn relative_luminance(color: Color) -> Option<f64> {
+    let Color::Rgb(r, g, b) = color else {
+        return None;
+    };
+    fn channel(v: u8) -> f64 {
+        let v = v as f64 / 255.0;
+        if v <= 0.03928 {
+            v / 12.92
+        } else {
+            ((v + 0.055) / 1.055).powf(2.4)
+        }
+    }
+    Some(0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b))
+}
+
+/// WCAG contrast ratio between two RGB roles, 1.0 (identical) to 21.0
+/// (black on white). `None` if either colour is not RGB.
+pub fn contrast_ratio(a: Color, b: Color) -> Option<f64> {
+    let (la, lb) = (relative_luminance(a)?, relative_luminance(b)?);
+    let (hi, lo) = if la >= lb { (la, lb) } else { (lb, la) };
+    Some((hi + 0.05) / (lo + 0.05))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const STATES: [ActivityState; 4] = [
+        ActivityState::Active,
+        ActivityState::Idle,
+        ActivityState::AwaitingInput,
+        ActivityState::Error,
+    ];
+
+    /// Text roles clear WCAG AA (4.5:1) against their own surface; `dim` is
+    /// decoration and only has to clear the 3:1 non-text threshold.
+    #[test]
+    fn every_role_is_legible_on_its_own_surface() {
+        for (preset, p) in [("dark", Palette::DARK), ("light", Palette::LIGHT)] {
+            for (surface_name, surface) in [("card", &p.card), ("selection", &p.selection)] {
+                for (role, color) in surface.roles() {
+                    let ratio = contrast_ratio(surface.bg, color)
+                        .unwrap_or_else(|| panic!("{preset}.{surface_name}.{role} must be RGB"));
+                    let floor = if role == "dim" { 3.0 } else { 4.5 };
+                    assert!(
+                        ratio >= floor,
+                        "{preset}.{surface_name}.{role} contrast {ratio:.2} is below {floor}"
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn every_preset_supplies_every_role() {
+        for (name, p) in Palette::presets() {
+            assert_eq!(p.roles().len(), 26, "{name} role set is incomplete");
+        }
+        assert_eq!(Palette::named("dark"), Some(Palette::DARK));
+        assert_eq!(Palette::named("light"), Some(Palette::LIGHT));
+        assert_eq!(Palette::named("ansi"), Some(Palette::ANSI));
+        assert_eq!(Palette::named("unknown"), None);
+    }
+
+    /// The selection background exists to be seen as a different surface, not
+    /// merely a slightly different shade of the card.
+    #[test]
+    fn selection_background_is_distinguishable_from_the_card_background() {
+        for (name, p) in [("dark", Palette::DARK), ("light", Palette::LIGHT)] {
+            let ratio = contrast_ratio(p.card.bg, p.selection.bg).unwrap();
+            assert!(
+                ratio >= 1.6,
+                "{name} card and selection backgrounds differ by only {ratio:.2}"
+            );
+        }
+    }
+
+    /// The bug this palette fixes: a state colour chosen for the dark card
+    /// background is not legible on the selection background, so the
+    /// selection surface carries its own — distinct — state colours.
+    #[test]
+    fn selection_state_colours_are_not_the_card_state_colours() {
+        for (name, p) in Palette::presets() {
+            for state in STATES {
+                assert_ne!(
+                    p.card.activity(state),
+                    p.selection.activity(state),
+                    "{name} {state:?} must have a selection-specific colour"
+                );
+            }
+        }
+    }
+
+    /// Other panels' roles are RGB too, so a preset swap moves all of them.
+    /// Foregrounds are checked against the chrome background they are
+    /// actually painted on; they must never rely on the terminal default.
+    #[test]
+    fn chrome_roles_are_rgb_values() {
+        for (preset, p) in [("dark", Palette::DARK), ("light", Palette::LIGHT)] {
+            for (name, color) in p.roles().into_iter().skip(16) {
+                assert!(
+                    relative_luminance(color).is_some(),
+                    "{preset}.{name} must be an RGB value"
+                );
+            }
+            // The mode indicator paints fg on bg; both pairs must stay readable.
+            for (name, fg, bg) in [
+                ("normal", p.mode_normal_fg, p.mode_normal_bg),
+                ("insert", p.mode_insert_fg, p.mode_insert_bg),
+            ] {
+                let ratio = contrast_ratio(fg, bg).unwrap();
+                assert!(
+                    ratio >= 4.5,
+                    "{preset} mode {name} contrast {ratio:.2} is below 4.5"
+                );
+            }
+            for (name, fg, floor) in [
+                ("border_focused", p.border_focused, 3.0),
+                ("border_unfocused", p.border_unfocused, 3.0),
+                ("focus_accent", p.focus_accent, 3.0),
+                ("group_row", p.group_row, 4.5),
+                ("error_text", p.error_text, 4.5),
+            ] {
+                let ratio = contrast_ratio(fg, p.chrome_bg).unwrap();
+                assert!(
+                    ratio >= floor,
+                    "{preset}.{name} contrast {ratio:.2} is below {floor} on chrome_bg"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn contrast_ratio_matches_known_values() {
+        let black = Color::Rgb(0, 0, 0);
+        let white = Color::Rgb(255, 255, 255);
+        assert!((contrast_ratio(black, white).unwrap() - 21.0).abs() < 0.01);
+        assert!((contrast_ratio(white, white).unwrap() - 1.0).abs() < 0.01);
+        assert_eq!(contrast_ratio(Color::Cyan, white), None);
+    }
+}

crates/maestro-tui/src/pane.rs

@@ -106,6 +106,9 @@ fn translate_cell_style(cell: &vt100::Cell) -> Style {
     s
 }
 
+/// PTY cell colours pass through verbatim: they belong to the program
+/// running in the pane, not to the TUI's own chrome, so they are deliberately
+/// not palette roles (see `crate::palette`).
 fn translate_color(c: vt100::Color) -> Option<Color> {
     match c {
         vt100::Color::Default => None,

crates/maestro-tui/src/render.rs

@@ -3,7 +3,7 @@
 //! hit-test mouse clicks.
 
 use ratatui::layout::{Constraint, Direction, Layout, Rect};
-use ratatui::style::{Color, Style};
+use ratatui::style::Style;
 use ratatui::text::Span;
 use ratatui::widgets::{Block, Borders, Paragraph};
 use ratatui::Frame;
@@ -11,9 +11,10 @@ use ratatui::Frame;
 use crate::input::Region;
 use crate::keymap::Mode;
 use crate::overlays::{HelpOverlay, KillConfirm, Toast};
+use crate::palette;
 use crate::pane::Pane;
 use crate::sidebar::Sidebar;
-use crate::state::{AppState, Focus, OverlayKind};
+use crate::state::{AppState, Focus, OverlayKind, SidebarItem};
 use crate::tabs::TabBar;
 use crate::worktrees::{ReclaimConfirm, WorktreesView};
 
@@ -22,6 +23,7 @@ use crate::worktrees::{ReclaimConfirm, WorktreesView};
 #[derive(Debug, Default, Clone)]
 pub struct RegionMap {
     pub sidebar: Option<Rect>,
+    pub sidebar_items: Vec<SidebarItem>,
     pub tab_bar: Option<Rect>,
     pub pane: Option<Rect>,
     pub modal: Option<Rect>,
@@ -51,6 +53,24 @@ impl RegionMap {
         }
         Region::Unknown
     }
+
+    /// Resolve a mouse row against the rendered sidebar sequence. The title
+    /// occupies one inner row; groups occupy one row and visible cards two.
+    pub fn sidebar_item_at(&self, row: u16) -> Option<SidebarItem> {
+        let area = self.sidebar?;
+        let mut cursor = area.y.saturating_add(2);
+        for item in &self.sidebar_items {
+            let height = match item {
+                SidebarItem::Group(_) => 1,
+                SidebarItem::Session(_) => 2,
+            };
+            if row >= cursor && row < cursor.saturating_add(height) {
+                return Some(item.clone());
+            }
+            cursor = cursor.saturating_add(height);
+        }
+        None
+    }
 }
 
 fn inside(r: Rect, col: u16, row: u16) -> bool {
@@ -62,6 +82,7 @@ fn inside(r: Rect, col: u16, row: u16) -> bool {
 #[derive(Debug)]
 pub struct RenderInputs<'a> {
     pub sidebar: &'a Sidebar,
+    pub home_dir: &'a str,
     pub tab_bar: &'a TabBar,
     pub pane: Option<&'a Pane>,
     /// Inline spawn form when the active tab's pane is a draft (issue #63).
@@ -101,44 +122,46 @@ pub fn draw(f: &mut Frame, inputs: RenderInputs<'_>) -> RegionMap {
     let right = cols[1];
 
     if inputs.state.sidebar_visible {
-        inputs
-            .sidebar
-            .render_with_focus(f, sidebar_area, inputs.state.focus == Focus::Sidebar);
+        inputs.sidebar.render_with_focus_and_collapsed_home(
+            f,
+            sidebar_area,
+            inputs.state.focus == Focus::Sidebar,
+            &inputs.state.collapsed_sidebar_groups,
+            inputs.home_dir,
+        );
         map.sidebar = Some(sidebar_area);
+        map.sidebar_items = inputs
+            .sidebar
+            .rendered_items_with_collapsed(&inputs.state.collapsed_sidebar_groups);
     }
 
-    // 1-row tab bar + 1-row horizontal rule (doubles as the pane's focus
-    // indicator) + flex pane area below. Saves the 4 rows the old
-    // `Length(3) + Borders::ALL` layout was eating before any content showed.
+    // The pane always owns its full border, so focus changes only recolour
+    // chrome and never change the rectangles handed to the input router.
     let rows = Layout::default()
         .direction(Direction::Vertical)
-        .constraints([
-            Constraint::Length(1),
-            Constraint::Length(1),
-            Constraint::Min(0),
-        ])
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
         .split(right);
     let tab_area = rows[0];
-    let separator_area = rows[1];
-    let pane_area = rows[2];
+    let pane_area = rows[1];
 
     inputs.tab_bar.render(f, tab_area);
     map.tab_bar = Some(tab_area);
 
     let pane_focused = inputs.state.focus == Focus::Pane;
-    f.render_widget(
-        Block::default()
-            .borders(Borders::TOP)
-            .border_style(focus_style(pane_focused)),
-        separator_area,
-    );
+    let pane_block = Block::default()
+        .borders(Borders::ALL)
+        .border_style(focus_style(pane_focused));
+    let pane_inner = pane_block.inner(pane_area);
+    f.render_widget(pane_block, pane_area);
     if let Some(p) = inputs.pane {
-        p.render(f, pane_area);
+        p.render(f, pane_inner);
     }
     if let Some(d) = inputs.draft {
-        d.render(f, pane_area, pane_focused);
+        d.render(f, pane_inner, pane_focused);
     }
-    map.pane = Some(pane_area);
+    // `RegionMap::pane` is also the PTY resize source. Keep it aligned with
+    // the cells the emulator actually owns, excluding the persistent border.
+    map.pane = Some(pane_inner);
 
     // Status bar — always visible, never eclipsed by overlays so the user can
     // always see the current mode + key hints.
@@ -193,14 +216,10 @@ pub fn draw(f: &mut Frame, inputs: RenderInputs<'_>) -> RegionMap {
     map
 }
 
-/// Border style for a panel based on whether it currently has focus.
-/// Focused = cyan; unfocused = the terminal default.
+/// Border style for a panel based on whether it currently has focus. Both
+/// forms are palette roles (`border_focused` / `border_unfocused`).
 fn focus_style(focused: bool) -> Style {
-    if focused {
-        Style::default().fg(Color::Cyan)
-    } else {
-        Style::default()
-    }
+    palette::active().border_style(focused)
 }
 
 /// Render the always-visible status bar at the bottom of the frame. Surfaces
@@ -219,10 +238,7 @@ fn render_status_bar(f: &mut Frame, area: Rect, state: &AppState) {
         Mode::Normal => "j/k: nav  •  enter: attach  •  s: new draft  •  ?: help  •  ^Wq: quit",
         Mode::Insert => "^a: back to normal",
     };
-    let mode_style = match state.mode {
-        Mode::Normal => Style::default().fg(Color::Black).bg(Color::Cyan),
-        Mode::Insert => Style::default().fg(Color::Black).bg(Color::Yellow),
-    };
+    let mode_style = palette::active().mode_style(state.mode == Mode::Insert);
     let line = ratatui::text::Line::from(vec![
         Span::styled(format!(" {mode_label} "), mode_style),
         Span::raw(format!("  {focus_label}  •  {hint}")),
@@ -244,6 +260,7 @@ mod tests {
                 width: 10,
                 height: 20,
             }),
+            sidebar_items: Vec::new(),
             tab_bar: Some(Rect {
                 x: 10,
                 y: 0,
@@ -273,6 +290,7 @@ mod tests {
                 width: 10,
                 height: 20,
             }),
+            sidebar_items: Vec::new(),
             tab_bar: Some(Rect {
                 x: 10,
                 y: 0,
@@ -297,6 +315,40 @@ mod tests {
         assert_eq!(map.region_at(3, 12), Region::SidebarRow); // outside modal
     }
 
+    #[test]
+    fn sidebar_mouse_rows_follow_group_and_two_line_card_heights() {
+        use std::path::PathBuf;
+        use uuid::Uuid;
+
+        let group_a = SidebarItem::Group(PathBuf::from("/a"));
+        let card_a = SidebarItem::Session(Uuid::from_u128(1));
+        let group_b = SidebarItem::Group(PathBuf::from("/b"));
+        let card_b = SidebarItem::Session(Uuid::from_u128(2));
+        let map = RegionMap {
+            sidebar: Some(Rect::new(0, 0, 28, 10)),
+            sidebar_items: vec![group_a.clone(), card_a.clone(), group_b.clone(), card_b],
+            ..RegionMap::default()
+        };
+        assert_eq!(map.sidebar_item_at(2), Some(group_a));
+        assert_eq!(map.sidebar_item_at(3), Some(card_a.clone()));
+        assert_eq!(map.sidebar_item_at(4), Some(card_a));
+        assert_eq!(map.sidebar_item_at(5), Some(group_b));
+
+        let collapsed = RegionMap {
+            sidebar: Some(Rect::new(0, 0, 28, 10)),
+            sidebar_items: vec![
+                SidebarItem::Group(PathBuf::from("/a")),
+                SidebarItem::Group(PathBuf::from("/b")),
+                SidebarItem::Session(Uuid::from_u128(2)),
+            ],
+            ..RegionMap::default()
+        };
+        assert_eq!(
+            collapsed.sidebar_item_at(3),
+            Some(SidebarItem::Group(PathBuf::from("/b")))
+        );
+    }
+
     /// Issue #63: an empty pane is a draft — the frame must show the spawn
     /// form where the terminal would otherwise be.
     #[test]
@@ -323,6 +375,7 @@ mod tests {
         let help = HelpOverlay { lines: Vec::new() };
         let inputs = RenderInputs {
             sidebar: &sidebar,
+            home_dir: "",
             tab_bar: &tab_bar,
             pane: None,
             draft: Some(draft),
@@ -357,4 +410,99 @@ mod tests {
             assert!(out.contains(s), "missing {s:?}:\n{out}");
         }
     }
+
+    #[test]
+    fn panel_rectangles_are_stable_when_focus_moves() {
+        use crate::overlays::HelpOverlay;
+        use crate::sidebar::Sidebar;
+        use std::collections::HashSet;
+
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: HashSet::new(),
+        };
+        let tab_bar = TabBar {
+            tab_names: vec!["1".into()],
+            active_idx: 0,
+        };
+        let help = HelpOverlay { lines: Vec::new() };
+        let draw_map = |focus| {
+            let mut state = AppState::new();
+            state.focus = focus;
+            let inputs = RenderInputs {
+                sidebar: &sidebar,
+                home_dir: "",
+                tab_bar: &tab_bar,
+                pane: None,
+                draft: None,
+                state: &state,
+                help: &help,
+                worktrees: None,
+            };
+            let backend = ratatui::backend::TestBackend::new(80, 24);
+            let mut terminal = ratatui::Terminal::new(backend).unwrap();
+            let mut map = None;
+            terminal.draw(|f| map = Some(draw(f, inputs))).unwrap();
+            map.unwrap()
+        };
+
+        let sidebar_focus = draw_map(Focus::Sidebar);
+        let pane_focus = draw_map(Focus::Pane);
+        assert_eq!(sidebar_focus.sidebar, pane_focus.sidebar);
+        assert_eq!(sidebar_focus.tab_bar, pane_focus.tab_bar);
+        assert_eq!(sidebar_focus.pane, pane_focus.pane);
+        assert_eq!(sidebar_focus.pane, Some(Rect::new(29, 2, 50, 20)));
+    }
+
+    #[test]
+    fn panel_border_colours_follow_focus_without_restyling_the_pane() {
+        use crate::overlays::HelpOverlay;
+        use crate::sidebar::Sidebar;
+        use std::collections::HashSet;
+
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: HashSet::new(),
+        };
+        let tab_bar = TabBar {
+            tab_names: vec!["1".into()],
+            active_idx: 0,
+        };
+        let help = HelpOverlay { lines: Vec::new() };
+        let render = |focus| {
+            let mut state = AppState::new();
+            state.focus = focus;
+            let inputs = RenderInputs {
+                sidebar: &sidebar,
+                home_dir: "",
+                tab_bar: &tab_bar,
+                pane: None,
+                draft: None,
+                state: &state,
+                help: &help,
+                worktrees: None,
+            };
+            let backend = ratatui::backend::TestBackend::new(80, 24);
+            let mut terminal = ratatui::Terminal::new(backend).unwrap();
+            terminal
+                .draw(|f| {
+                    draw(f, inputs);
+                })
+                .unwrap();
+            terminal.backend().buffer().clone()
+        };
+
+        let sidebar_focused = render(Focus::Sidebar);
+        let pane_focused = render(Focus::Pane);
+        let p = palette::active();
+        assert_eq!(sidebar_focused[(0, 0)].style().fg, Some(p.border_focused));
+        assert_eq!(pane_focused[(0, 0)].style().fg, Some(p.border_unfocused));
+        assert_eq!(
+            sidebar_focused[(28, 1)].style().fg,
+            Some(p.border_unfocused)
+        );
+        assert_eq!(pane_focused[(28, 1)].style().fg, Some(p.border_focused));
+    }
 }

crates/maestro-tui/src/sidebar.rs

@@ -2,12 +2,13 @@
 //!
 //! Line 1: status glyph (● attached / ○ live / ✗ dead) + name.
 //! Line 2: activity dot + duration in the state's colour, plus the
-//! blocked-work and exited fragments when they apply. Absent entirely when
-//! it has nothing to say.
+//! adaptive detail, blocked-work, exited, and command fragments.
 
-use std::collections::HashSet;
+use std::collections::{BTreeMap, HashSet};
+use std::path::PathBuf;
 
 use chrono::Utc;
+use maestro_protocol::display::{abbreviate_dir, abbreviate_folder_name, session_tree_path};
 use maestro_protocol::{ActivityState, Session, SessionStatus};
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Modifier, Style};
@@ -16,8 +17,11 @@ use ratatui::widgets::{Block, Borders, Paragraph};
 use ratatui::Frame;
 use uuid::Uuid;
 
-/// Time-in-state alone earns a meta line only once the session has sat in
-/// its current activity state this long (docs/SIDEBAR.md).
+use crate::palette;
+use crate::state::SidebarItem;
+
+/// Time-in-state earns a duration fragment once the session has sat in its
+/// current activity state this long (docs/SIDEBAR.md).
 const META_LINE_AFTER_SECS: i64 = 30;
 /// A payload predating #102 defaults `activity_since` to the Unix epoch. Per
 /// docs/SIDEBAR.md such a session contributes no duration — the dot still
@@ -30,43 +34,63 @@ const META_INDENT: &str = "    ";
 /// Spawn-similar and kill, shown on the highlighted card's top-right corner.
 const ACTIONS: &str = "⧉ ✕";
 
-/// Every card sits on this background so cards read as cards against the
-/// panel; the highlighted card swaps it for the focus background instead
-/// (`Modifier::REVERSED` made the card unreadable against a background).
-const CARD_BG: Color = Color::Black;
-fn card_base(highlighted: bool) -> Style {
-    if highlighted {
-        Style::default().fg(Color::Black).bg(Color::Cyan)
-    } else {
-        Style::default().bg(CARD_BG)
-    }
+/// Cards use the selection surface only while the sidebar owns focus. An
+/// unfocused highlight remains an edge-marked cursor without claiming the
+/// keyboard via a filled selection background.
+fn card_base(highlighted: bool, focused: bool) -> Style {
+    palette::active()
+        .surface(highlighted && focused)
+        .text_style()
 }
 
 /// Renderable sidebar state.
 #[derive(Debug, Clone)]
 pub struct Sidebar {
     pub sessions: Vec<Session>,
-    pub highlight: Option<Uuid>,
+    pub highlight: Option<SidebarItem>,
     pub attached: HashSet<Uuid>,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SidebarGroup {
+    pub key: PathBuf,
+    pub sessions: Vec<Session>,
+    pub collapsed: bool,
+}
+
 impl Sidebar {
     pub fn render(&self, f: &mut Frame, area: Rect) {
         self.render_with_focus(f, area, false);
     }
 
-    /// Same as [`Sidebar::render`] but tints the right-edge separator in the
-    /// focus colour when `focused`. Box borders eat too many rows/cols for
-    /// the v1 layout — a single vertical rule keeps the panel boundary
-    /// without stealing space.
+    /// Render the panel with a persistent border. Focus changes its colour
+    /// and whether the highlighted card claims the selection surface, never
+    /// its geometry.
     pub fn render_with_focus(&self, f: &mut Frame, area: Rect, focused: bool) {
-        let border_style = if focused {
-            Style::default().fg(Color::Cyan)
-        } else {
-            Style::default()
-        };
+        self.render_with_focus_and_collapsed(f, area, focused, &HashSet::new());
+    }
+
+    pub fn render_with_focus_and_collapsed(
+        &self,
+        f: &mut Frame,
+        area: Rect,
+        focused: bool,
+        collapsed: &HashSet<PathBuf>,
+    ) {
+        self.render_with_focus_and_collapsed_home(f, area, focused, collapsed, &home_dir());
+    }
+
+    pub fn render_with_focus_and_collapsed_home(
+        &self,
+        f: &mut Frame,
+        area: Rect,
+        focused: bool,
+        collapsed: &HashSet<PathBuf>,
+        home: &str,
+    ) {
+        let border_style = palette::active().border_style(focused);
         let block = Block::default()
-            .borders(Borders::RIGHT)
+            .borders(Borders::ALL)
             .border_style(border_style);
         let inner = block.inner(area);
         f.render_widget(block, area);
@@ -76,25 +100,117 @@ impl Sidebar {
             "sessions",
             Style::default().add_modifier(Modifier::BOLD),
         ))];
-        for s in &self.sessions {
-            let highlighted = self.highlight == Some(s.id);
-            let base = card_base(highlighted);
-            lines.push(Line::from(self.name_row(s, width)));
-            if let Some(meta) = self.meta_row(s, width) {
-                lines.push(Line::from(pad_to_width(meta, width, base)));
+        for group in self.groups(collapsed) {
+            lines.push(Line::from(self.group_row(&group, width, focused, home)));
+            if !group.collapsed {
+                for s in &group.sessions {
+                    let highlighted = self.highlight == Some(SidebarItem::Session(s.id));
+                    let base = card_base(highlighted, focused);
+                    lines.push(Line::from(self.name_row(s, width, focused)));
+                    let meta = self.meta_row(s, width, focused);
+                    lines.push(Line::from(pad_to_width(meta, width, base)));
+                }
             }
         }
         f.render_widget(Paragraph::new(lines), inner);
     }
 
-    fn name_row(&self, s: &Session, width: usize) -> Vec<Span<'static>> {
+    /// Items in exactly the order and height they occupy on screen.
+    pub fn rendered_items(&self) -> Vec<SidebarItem> {
+        self.rendered_items_with_collapsed(&HashSet::new())
+    }
+
+    pub fn rendered_items_with_collapsed(&self, collapsed: &HashSet<PathBuf>) -> Vec<SidebarItem> {
+        self.groups(collapsed)
+            .into_iter()
+            .flat_map(|group| {
+                let mut items = vec![SidebarItem::Group(group.key)];
+                if !group.collapsed {
+                    items.extend(
+                        group
+                            .sessions
+                            .into_iter()
+                            .map(|s| SidebarItem::Session(s.id)),
+                    );
+                }
+                items
+            })
+            .collect()
+    }
+
+    pub fn groups(&self, collapsed: &HashSet<PathBuf>) -> Vec<SidebarGroup> {
+        let mut grouped: BTreeMap<PathBuf, Vec<Session>> = BTreeMap::new();
+        for session in &self.sessions {
+            if let Some(key) = session_tree_path(session) {
+                grouped.entry(key).or_default().push(session.clone());
+            }
+        }
+        grouped
+            .into_iter()
+            .map(|(key, mut sessions)| {
+                sessions
+                    .sort_by(|a, b| name_for(a).cmp(&name_for(b)).then_with(|| a.id.cmp(&b.id)));
+                SidebarGroup {
+                    collapsed: collapsed.contains(&key),
+                    key,
+                    sessions,
+                }
+            })
+            .collect()
+    }
+
+    fn group_row(
+        &self,
+        group: &SidebarGroup,
+        width: usize,
+        focused: bool,
+        home: &str,
+    ) -> Vec<Span<'static>> {
+        let highlighted = self.highlight == Some(SidebarItem::Group(group.key.clone()));
+        let palette = palette::active();
+        let surface = palette.surface(highlighted && focused);
+        let base = Style::default().bg(surface.bg).fg(if highlighted {
+            surface.fg
+        } else {
+            palette.group_row
+        });
+        let edge = highlighted && !focused;
+        let prefix = if edge { "▏ " } else { "  " };
+        let chevron = if group.collapsed { "▸ " } else { "▾ " };
+        let path = abbreviate_dir(&group.key, home);
+        let name = abbreviate_folder_name(&path);
+        let count = format!(" ({})", group.sessions.len());
+        let prefix = Span::styled(
+            prefix,
+            if edge {
+                base.fg(palette.focus_accent)
+            } else {
+                base
+            },
+        );
+        let chevron = Span::styled(chevron, base);
+        let count = Span::styled(count, surface.muted_style());
+        let label_budget = width.saturating_sub(prefix.width() + chevron.width() + count.width());
+        let mut label = Vec::new();
+        if let Some(stem) = name.stem {
+            label.push(Span::styled(format!("{stem}/"), surface.dim_style()));
+        }
+        label.push(Span::styled(name.last, base));
+
+        let mut spans = vec![prefix, chevron];
+        spans.extend(fit_to_width(label, label_budget));
+        spans.push(count);
+        pad_to_width(spans, width, base)
+    }
+
+    fn name_row(&self, s: &Session, width: usize, focused: bool) -> Vec<Span<'static>> {
         let glyph = match (s.status, self.attached.contains(&s.id)) {
             (SessionStatus::Dead, _) => "✗",
             (SessionStatus::Running, true) => "●",
             (SessionStatus::Running, false) => "○",
         };
-        let highlighted = self.highlight == Some(s.id);
-        let base = card_base(highlighted);
+        let highlighted = self.highlight == Some(SidebarItem::Session(s.id));
+        let base = card_base(highlighted, focused);
         // Line-1 actions are keyboard affordances shown on the highlighted
         // row only; they reserve their width so the name truncates with `…`
         // before it can ever reach them (docs/SIDEBAR.md).
@@ -110,8 +226,16 @@ impl Sidebar {
         let sep = if highlighted { 1 } else { 0 };
         let name_budget = usable.saturating_sub(prefix + sep);
 
+        let edge = highlighted && !focused;
         let mut spans: Vec<Span<'static>> = vec![
-            Span::styled(INDENT, base),
+            Span::styled(
+                if edge { "▏ " } else { INDENT },
+                if edge {
+                    base.fg(palette::active().focus_accent)
+                } else {
+                    base
+                },
+            ),
             Span::styled(format!("{glyph} "), base),
         ];
         spans.extend(
@@ -121,10 +245,7 @@ impl Sidebar {
         );
         let used: usize = spans.iter().map(|sp| sp.width()).sum();
         if let Some(fill) = usable.checked_sub(used).filter(|&n| n > 0) {
-            spans.push(Span::styled(
-                " ".repeat(fill),
-                Style::default().bg(base.bg.unwrap_or(Color::Reset)),
-            ));
+            spans.push(Span::styled(" ".repeat(fill), base));
         }
         if highlighted {
             spans.push(Span::styled(ACTIONS, base));
@@ -132,8 +253,8 @@ impl Sidebar {
         spans
     }
 
-    /// The adaptive second line: `<dot> <duration> [<blocked work> | exited]`.
-    fn meta_row(&self, s: &Session, width: usize) -> Option<Vec<Span<'static>>> {
+    /// The adaptive second line: `<dot> [<duration>] [<detail>] [<blocked work> | exited] <command>`.
+    fn meta_row(&self, s: &Session, width: usize, focused: bool) -> Vec<Span<'static>> {
         let now = Utc::now();
         let held = held_for(s, now);
         let held_secs = held.map(|d| d.num_seconds()).unwrap_or(0);
@@ -141,44 +262,70 @@ impl Sidebar {
         // on line 1; the kill confirm names the specifics.
         let blocked = s.blocked_work.filter(|b| !b.is_clear());
         let dead = s.status == SessionStatus::Dead;
-        let errored = s.activity == ActivityState::Error;
-        if (held.is_none() || held_secs < META_LINE_AFTER_SECS)
-            && blocked.is_none()
-            && !dead
-            && !errored
-        {
-            return None;
-        }
-        let base = card_base(self.highlight == Some(s.id));
-        let dot_style = base.patch(Style::default().fg(activity_color(s.activity)));
-        let muted = Style::default().bg(base.bg.unwrap_or(Color::Reset));
+        let highlighted = self.highlight == Some(SidebarItem::Session(s.id));
+        let base = card_base(highlighted, focused);
+        let dot_style =
+            base.patch(Style::default().fg(activity_color(s.activity, highlighted, focused)));
+        let muted = palette::active()
+            .surface(highlighted && focused)
+            .muted_style();
+        let edge = highlighted && !focused;
         let mut spans = vec![
-            Span::styled(META_INDENT, base),
+            Span::styled(
+                if edge { "  ▏ " } else { META_INDENT },
+                if edge {
+                    base.fg(palette::active().focus_accent)
+                } else {
+                    base
+                },
+            ),
             Span::styled("●", dot_style),
         ];
-        if let Some(d) = held {
+        if let Some(d) = held.filter(|_| held_secs >= META_LINE_AFTER_SECS) {
             spans.push(Span::styled(" ", base));
             spans.push(Span::styled(format_state_duration(d), dot_style));
         }
+        let mut tail: Vec<Span<'static>> = Vec::new();
         if let Some(b) = blocked {
-            spans.push(Span::styled(format!(" ⚠ {b}"), muted));
+            tail.push(Span::styled(format!(" ⚠ {b}"), muted));
         }
         if dead {
-            spans.push(Span::styled(" exited", muted));
+            tail.push(Span::styled(" exited", muted));
         }
-        Some(fit_to_width(spans, width))
+        let command = Span::styled(format!(" {}", s.command), muted);
+
+        // Reserve the triggered status fragments before detail and command.
+        // If the row is exceptionally narrow, keep one column for the
+        // unconditional command and truncate the status tail first. Detail
+        // then receives only space left after the full command reservation;
+        // when the full command cannot fit, it is the final truncation target.
+        let head_w: usize = spans.iter().map(|sp| sp.width()).sum();
+        let available = width.saturating_sub(head_w);
+        let command_floor = usize::from(available > 0);
+        let tail = fit_to_width(tail, available.saturating_sub(command_floor));
+        let tail_w: usize = tail.iter().map(|sp| sp.width()).sum();
+        let command_w = command.width().min(available.saturating_sub(tail_w));
+        if let Some(detail) = s.activity_detail.as_deref().filter(|d| !d.is_empty()) {
+            let budget = available.saturating_sub(tail_w + command_w);
+            spans.extend(fit_to_width(
+                vec![Span::styled(format!(" {detail}"), muted)],
+                budget,
+            ));
+        }
+        spans.extend(tail);
+        spans.extend(fit_to_width(vec![command], command_w));
+        spans
     }
 }
 
-/// ratatui colour for an [`ActivityState`], per docs/SIDEBAR.md. The state
-/// word is never spelled out — this colour carries it.
-fn activity_color(state: ActivityState) -> Color {
-    match state {
-        ActivityState::Active => Color::Green,
-        ActivityState::Idle => Color::DarkGray,
-        ActivityState::AwaitingInput => Color::Yellow,
-        ActivityState::Error => Color::Red,
-    }
+/// Palette role carrying an [`ActivityState`], per docs/SIDEBAR.md. The
+/// state word is never spelled out — this colour carries it. The highlighted
+/// card takes its state colours from the selection surface: a colour picked
+/// for the dark card background is not legible on the selection background.
+fn activity_color(state: ActivityState, highlighted: bool, focused: bool) -> Color {
+    palette::active()
+        .surface(highlighted && focused)
+        .activity(state)
 }
 
 /// docs/SIDEBAR.md duration format — floored whole seconds / minutes / hours,
@@ -232,8 +379,7 @@ fn fit_to_width(spans: Vec<Span<'static>>, max: usize) -> Vec<Span<'static>> {
 fn pad_to_width(mut spans: Vec<Span<'static>>, width: usize, base: Style) -> Vec<Span<'static>> {
     let used: usize = spans.iter().map(|sp| sp.width()).sum();
     if let Some(fill) = width.checked_sub(used).filter(|&n| n > 0) {
-        let pad_style = Style::default().bg(base.bg.unwrap_or(Color::Reset));
-        spans.push(Span::styled(" ".repeat(fill), pad_style));
+        spans.push(Span::styled(" ".repeat(fill), base));
     }
     spans
 }
@@ -247,6 +393,10 @@ fn name_for(s: &Session) -> String {
     }
 }
 
+fn home_dir() -> String {
+    std::env::var("HOME").unwrap_or_default()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -280,9 +430,24 @@ mod tests {
     }
 
     fn draw(sidebar: &Sidebar, w: u16, h: u16) -> Buffer {
+        draw_with_focus(sidebar, w, h, true)
+    }
+
+    fn draw_with_focus(sidebar: &Sidebar, w: u16, h: u16, focused: bool) -> Buffer {
         let backend = TestBackend::new(w, h);
         let mut terminal = Terminal::new(backend).unwrap();
-        terminal.draw(|f| sidebar.render(f, f.area())).unwrap();
+        terminal
+            .draw(|f| sidebar.render_with_focus(f, f.area(), focused))
+            .unwrap();
+        terminal.backend().buffer().clone()
+    }
+
+    fn draw_collapsed(sidebar: &Sidebar, w: u16, h: u16, collapsed: &HashSet<PathBuf>) -> Buffer {
+        let backend = TestBackend::new(w, h);
+        let mut terminal = Terminal::new(backend).unwrap();
+        terminal
+            .draw(|f| sidebar.render_with_focus_and_collapsed(f, f.area(), true, collapsed))
+            .unwrap();
         terminal.backend().buffer().clone()
     }
 
@@ -308,7 +473,10 @@ mod tests {
 
     /// Row text without the trailing space padding and right border.
     fn content(row: &str) -> &str {
-        row.trim_end().trim_end_matches('│').trim_end()
+        row.trim()
+            .trim_start_matches('│')
+            .trim_end_matches('│')
+            .trim()
     }
 
     #[test]
@@ -329,6 +497,102 @@ mod tests {
         );
     }
 
+    #[test]
+    fn groups_worktrees_under_their_base_repository() {
+        let mut s = session_named(1, "claude");
+        s.cwd = "/home/u/repos/worktrees/feature".into();
+        s.worktree = Some(maestro_protocol::SessionWorktree {
+            path: s.cwd.clone(),
+            base_repo: "/home/u/repos/maestro".into(),
+        });
+        let groups = (Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        })
+        .groups(&HashSet::new());
+        assert_eq!(groups[0].key, PathBuf::from("/home/u/repos/maestro"));
+    }
+
+    #[test]
+    fn does_not_render_groups_without_sessions() {
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: Default::default(),
+        };
+        assert!(sidebar.groups(&HashSet::new()).is_empty());
+        assert!(sidebar.rendered_items().is_empty());
+    }
+
+    #[test]
+    fn collapsing_a_group_hides_cards_but_keeps_the_count_and_item() {
+        let sidebar = Sidebar {
+            sessions: vec![session_named(1, "claude"), session_named(2, "bash")],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let key = PathBuf::from("/tmp");
+        let mut collapsed = HashSet::new();
+        collapsed.insert(key.clone());
+        let groups = sidebar.groups(&collapsed);
+        assert_eq!(groups[0].sessions.len(), 2);
+        assert!(groups[0].collapsed);
+        assert_eq!(
+            sidebar.rendered_items_with_collapsed(&collapsed),
+            vec![SidebarItem::Group(key)]
+        );
+        let rendered = render_to_string(&draw_collapsed(&sidebar, 40, 6, &collapsed));
+        assert!(rendered.contains("(2)"));
+        assert!(!rendered.contains("claude"));
+    }
+
+    #[test]
+    fn long_group_labels_yield_to_the_always_visible_count() {
+        let mut session = session_named(1, "claude");
+        session.cwd = "/very/long/project/path/extraordinarily-long-project-name".into();
+        let sidebar = Sidebar {
+            sessions: vec![session],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let key = PathBuf::from("/very/long/project/path/extraordinarily-long-project-name");
+        let collapsed = HashSet::from([key]);
+        let rendered = render_to_string(&draw_collapsed(&sidebar, 28, 6, &collapsed));
+
+        assert!(rendered.contains('…'));
+        assert!(
+            rendered.contains("(1)"),
+            "group count was truncated: {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn shared_display_helpers_abbreviate_group_labels() {
+        let path = maestro_protocol::display::abbreviate_dir(
+            std::path::Path::new("/home/u/git.naps.pt/naps62/maestro"),
+            "/home/u",
+        );
+        let name = maestro_protocol::display::abbreviate_folder_name(&path);
+        assert_eq!(path, "~/git.naps.pt/naps62/maestro");
+        assert_eq!(name.stem.as_deref(), Some("~/g/n"));
+        assert_eq!(name.last, "maestro");
+    }
+
+    #[test]
+    fn rendered_cards_are_always_two_lines_after_one_group_row() {
+        let sidebar = Sidebar {
+            sessions: vec![session_named(1, "claude")],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sidebar, 40, 8));
+        assert!(all[2].contains("/tmp"));
+        assert!(all[3].contains("claude"));
+        assert!(all[4].contains("bash"));
+        assert!(!all[5].contains("bash"));
+    }
+
     #[test]
     fn attached_session_uses_filled_glyph() {
         let sid = Uuid::from_u128(1);
@@ -404,10 +668,10 @@ mod tests {
         }
     }
 
-    /// A freshly-active session stays one line — never an empty placeholder
-    /// row (docs/SIDEBAR.md).
+    /// A fresh session still gets its unconditional second line, but no
+    /// duration until it has been held in state for 30 seconds.
     #[test]
-    fn freshly_active_session_stays_one_line() {
+    fn fresh_session_renders_two_lines_without_duration() {
         let mut s = session_named(1, "claude");
         s.activity_since = Utc::now() - Duration::seconds(10);
         let sb = Sidebar {
@@ -416,12 +680,22 @@ mod tests {
             attached: Default::default(),
         };
         let all = rows(&draw(&sb, 28, 8));
-        assert_eq!(content(&all[0]), "sessions");
+        assert_eq!(content(&all[1]), "sessions");
         assert!(row_containing(&all, "claude").contains('○'));
         assert!(
-            content(&all[2]).is_empty(),
-            "line 2 must be absent, got {:?}",
-            all[2]
+            all[4].contains('●'),
+            "line 2 must carry the dot: {:?}",
+            all[3]
+        );
+        assert!(
+            all[4].contains("bash"),
+            "line 2 must carry the command: {:?}",
+            all[3]
+        );
+        assert!(
+            !all[4].contains("10s"),
+            "fresh cards have no duration: {:?}",
+            all[3]
         );
     }
 
@@ -460,12 +734,13 @@ mod tests {
     /// is never spelled out (docs/SIDEBAR.md colour table).
     #[test]
     fn meta_line_dot_uses_the_contract_colour_per_state() {
-        for (state, expected) in [
-            (ActivityState::Active, Color::Green),
-            (ActivityState::Idle, Color::DarkGray),
-            (ActivityState::AwaitingInput, Color::Yellow),
-            (ActivityState::Error, Color::Red),
+        for state in [
+            ActivityState::Active,
+            ActivityState::Idle,
+            ActivityState::AwaitingInput,
+            ActivityState::Error,
         ] {
+            let expected = palette::active().card.activity(state);
             let mut s = session_named(1, "claude");
             s.activity = state;
             s.activity_since = Utc::now() - Duration::seconds(120);
@@ -481,6 +756,54 @@ mod tests {
         }
     }
 
+    /// The selected card keeps carrying its state on the dot, but in the
+    /// selection surface's own colours. A state colour picked for the dark
+    /// card background painted onto the selection background is the contrast
+    /// bug this palette fixes — this test fails if it comes back.
+    #[test]
+    fn selected_card_never_paints_a_card_state_colour_on_the_selection_background() {
+        let p = palette::active();
+        for state in [
+            ActivityState::Active,
+            ActivityState::Idle,
+            ActivityState::AwaitingInput,
+            ActivityState::Error,
+        ] {
+            let mut s = session_named(1, "claude");
+            s.activity = state;
+            s.activity_since = Utc::now() - Duration::seconds(120);
+            let sb = Sidebar {
+                sessions: vec![s],
+                highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
+                attached: Default::default(),
+            };
+            let buf = draw(&sb, 28, 8);
+            let on_selection = |fg: Color| {
+                (0..buf.area.height).any(|y| {
+                    (0..buf.area.width).any(|x| {
+                        let st = buf[(x, y)].style();
+                        st.bg == Some(p.selection.bg) && st.fg == Some(fg)
+                    })
+                })
+            };
+            assert!(
+                !on_selection(p.card.activity(state)),
+                "{state:?}: card surface colour {:?} painted onto the selection background",
+                p.card.activity(state)
+            );
+            assert!(
+                on_selection(p.selection.activity(state)),
+                "{state:?}: the dot must still carry the state on the selected card"
+            );
+            let ratio = palette::contrast_ratio(p.selection.bg, p.selection.activity(state))
+                .expect("palette roles are RGB");
+            assert!(
+                ratio >= 4.5,
+                "{state:?} on the selection background is only {ratio:.2}:1"
+            );
+        }
+    }
+
     /// Rule 3 of docs/SIDEBAR.md: a dead session always gets a meta line,
     /// even freshly dead, with the muted `exited` fragment.
     #[test]
@@ -502,11 +825,12 @@ mod tests {
         );
     }
 
-    /// The sidebar is narrow: the meta line truncates with `…` and never
-    /// wraps onto a third row (docs/SIDEBAR.md).
+    /// The sidebar is narrow: the command truncates with `…` and never wraps
+    /// onto a third row (docs/SIDEBAR.md).
     #[test]
-    fn meta_line_truncates_instead_of_wrapping() {
+    fn meta_line_command_truncates_instead_of_wrapping() {
         let mut s = session_named(1, "claude");
+        s.command = "a command that cannot fit".into();
         s.activity_since = Utc::now() - Duration::seconds(5);
         s.blocked_work = Some(InTheWay {
             uncommitted_files: 120,
@@ -522,7 +846,94 @@ mod tests {
         let meta = content(&all[idx + 1]);
         assert!(
             meta.trim_end().ends_with('…'),
-            "truncated meta line must end with …: {meta:?}"
+            "truncated command must end with …: {meta:?}"
+        );
+        assert!(
+            content(&all[idx + 2]).trim().is_empty(),
+            "meta line must not wrap: {:?}",
+            all[idx + 2]
+        );
+    }
+
+    /// #112: the agent-reported detail sits right after the duration on the
+    /// meta line, in the muted style (docs/SIDEBAR.md).
+    #[test]
+    fn errored_session_shows_its_reported_detail_on_the_meta_line() {
+        let mut s = session_named(1, "claude");
+        s.activity = ActivityState::Error;
+        s.activity_since = Utc::now() - Duration::seconds(90);
+        s.activity_detail = Some("cargo build failed".into());
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 40, 8));
+        let idx = all.iter().position(|l| l.contains("claude")).unwrap();
+        let meta = &all[idx + 1];
+        assert!(meta.contains('●'), "meta line carries the dot: {meta:?}");
+        assert!(
+            meta.contains("1m"),
+            "duration precedes the detail: {meta:?}"
+        );
+        assert!(
+            meta.contains("cargo build failed"),
+            "reported detail must render: {meta:?}"
+        );
+    }
+
+    /// A fresh Error report earns line 2 on its own (contract rule 4), with
+    /// the detail even though no duration has accrued.
+    #[test]
+    fn fresh_errored_session_earns_a_meta_line_for_its_detail() {
+        let mut s = session_named(1, "claude");
+        s.activity = ActivityState::Error;
+        s.activity_since = Utc::now() - Duration::seconds(5);
+        s.activity_detail = Some("waiting for approval".into());
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 40, 8));
+        let idx = all.iter().position(|l| l.contains("claude")).unwrap();
+        assert!(
+            all[idx + 1].contains("waiting for approval"),
+            "detail must render on a fresh report's own meta line: {:?}",
+            all[idx + 1]
+        );
+    }
+
+    /// #112 via docs/SIDEBAR.md: the detail truncates with `…` ahead of the
+    /// trailing fragments — a long detail never pushes blocked work or
+    /// `exited` off the line, and never wraps.
+    #[test]
+    fn long_detail_yields_to_blocked_work_and_exited() {
+        let mut s = session_named(1, "claude");
+        s.status = SessionStatus::Dead;
+        s.activity_since = Utc::now() - Duration::seconds(5);
+        s.activity_detail =
+            Some("an absurdly long error message that cannot possibly fit ".repeat(3));
+        s.blocked_work = Some(InTheWay {
+            unpushed_commits: 2,
+            ..InTheWay::default()
+        });
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 42, 8));
+        let idx = all.iter().position(|l| l.contains("claude")).unwrap();
+        let meta = content(&all[idx + 1]);
+        assert!(meta.contains('…'), "truncated detail ends with …: {meta:?}");
+        assert!(
+            meta.contains("2 unpushed commits"),
+            "blocked work stays on the line: {meta:?}"
+        );
+        assert!(
+            meta.contains("exited"),
+            "exited fragment stays on the line: {meta:?}"
         );
         assert!(
             content(&all[idx + 2]).trim().is_empty(),
@@ -550,10 +961,6 @@ mod tests {
             rendered.contains("exited"),
             "dead session must still show line 2:\n{rendered}"
         );
-        assert!(
-            !rendered.contains('h') || !rendered.contains("● "),
-            "no duration may follow the dot for an epoch stamp:\n{rendered}"
-        );
         for line in rendered.lines().filter(|l| l.contains('●')) {
             assert!(
                 !line
@@ -598,6 +1005,90 @@ mod tests {
         );
     }
 
+    #[test]
+    fn command_renders_on_line_two_even_when_name_is_metadata() {
+        let s = session_named(1, "friendly name");
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 40, 6));
+        assert!(
+            all[3].contains("friendly name"),
+            "name must stay on line 1: {:?}",
+            all[2]
+        );
+        assert!(
+            all[4].contains("bash"),
+            "command must be on line 2: {:?}",
+            all[3]
+        );
+    }
+
+    #[test]
+    fn narrow_meta_line_keeps_dot_and_truncates_command() {
+        let s = session_named(1, "name");
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 10, 6));
+        assert!(
+            all[4].contains('●'),
+            "dot must survive narrow cards: {:?}",
+            all[3]
+        );
+        assert!(
+            all[4].contains('…'),
+            "command should truncate: {:?}",
+            all[3]
+        );
+    }
+
+    #[test]
+    fn blocked_warning_survives_before_a_truncated_command() {
+        let mut s = session_named(1, "name");
+        s.command = "a command that cannot fit".into();
+        s.blocked_work = Some(InTheWay {
+            uncommitted_files: 1,
+            ..Default::default()
+        });
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 29, 6));
+        assert!(all[4].contains("⚠ 1 uncommitted file"), "{:?}", all[4]);
+        let meta = content(&all[4]);
+        assert!(meta.ends_with('…'), "command must truncate: {meta:?}");
+    }
+
+    #[test]
+    fn long_detail_yields_to_status_and_command() {
+        let mut s = session_named(1, "name");
+        s.activity_detail = Some("a very long agent-reported detail".into());
+        s.blocked_work = Some(InTheWay {
+            uncommitted_files: 1,
+            ..Default::default()
+        });
+        let sb = Sidebar {
+            sessions: vec![s],
+            highlight: None,
+            attached: Default::default(),
+        };
+        let all = rows(&draw(&sb, 40, 6));
+        assert!(all[4].contains("⚠ 1 uncommitted file"), "{:?}", all[4]);
+        assert!(
+            all[4].contains("bash"),
+            "command must survive: {:?}",
+            all[3]
+        );
+        assert!(all[4].contains('…'), "detail must truncate: {:?}", all[4]);
+    }
+
     /// Reversed video makes a card unreadable against a background; cards
     /// use explicit backgrounds instead (docs/SIDEBAR.md, #108).
     #[test]
@@ -606,7 +1097,7 @@ mod tests {
         highlighted.activity_since = Utc::now() - Duration::seconds(120);
         let sb = Sidebar {
             sessions: vec![highlighted],
-            highlight: Some(Uuid::from_u128(1)),
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
         };
         let buf = draw(&sb, 28, 8);
@@ -631,36 +1122,74 @@ mod tests {
         let two = session_named(2, "bash");
         let sb = Sidebar {
             sessions: vec![one, two],
-            highlight: Some(Uuid::from_u128(1)),
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
         };
         let buf = draw(&sb, 28, 8);
         let all = rows(&buf);
         let claude_y = all.iter().position(|l| l.contains("claude")).unwrap();
-        let bash_y = all.iter().position(|l| l.contains("bash")).unwrap();
+        let bash_y = all.iter().position(|l| l.contains("○ bash")).unwrap();
 
+        let p = palette::active();
         assert_eq!(
-            buf[(0, claude_y as u16)].style().bg,
-            Some(Color::Cyan),
-            "focused card must sit on the focus background"
+            buf[(1, claude_y as u16)].style().bg,
+            Some(p.selection.bg),
+            "focused card must sit on the selection surface"
         );
         assert_eq!(
-            buf[(0, claude_y as u16)].style().fg,
-            Some(Color::Black),
-            "focused card text must stay readable on cyan"
+            buf[(1, claude_y as u16)].style().fg,
+            Some(p.selection.fg),
+            "focused card text must use the selection foreground role"
         );
         assert_eq!(
-            buf[(0, bash_y as u16)].style().bg,
-            Some(Color::Black),
-            "unfocused cards must still have a card background"
+            buf[(1, bash_y as u16)].style().bg,
+            Some(p.card.bg),
+            "unfocused cards must still sit on the card surface"
         );
         // The panel itself (header row) stays on the terminal default.
         assert!(
-            matches!(buf[(0, 0)].style().bg, None | Some(Color::Reset)),
+            matches!(buf[(1, 1)].style().bg, None | Some(Color::Reset)),
             "panel must keep the terminal default background"
         );
     }
 
+    #[test]
+    fn highlighted_card_is_hollow_when_sidebar_is_unfocused() {
+        let sb = Sidebar {
+            sessions: vec![session_named(1, "claude")],
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
+            attached: Default::default(),
+        };
+        let buf = draw_with_focus(&sb, 28, 8, false);
+        let y = (0..buf.area.height)
+            .find(|&y| (0..buf.area.width).any(|x| buf[(x, y)].symbol() == "c"))
+            .expect("highlighted session row");
+        assert_eq!(
+            buf[(1, y)].style().bg,
+            Some(palette::active().card.bg),
+            "unfocused highlight must not paint the selection surface"
+        );
+        assert!(
+            (0..buf.area.width).any(|x| buf[(x, y)].symbol() == "▏"),
+            "unfocused highlight must retain a visible edge marker"
+        );
+        let ordinary = draw_with_focus(
+            &Sidebar {
+                sessions: vec![session_named(1, "claude")],
+                highlight: None,
+                attached: Default::default(),
+            },
+            28,
+            8,
+            false,
+        );
+        assert!(
+            !(0..ordinary.area.height)
+                .any(|row| (0..ordinary.area.width).any(|x| ordinary[(x, row)].symbol() == "▏")),
+            "ordinary unhighlighted cards must not carry the cursor marker"
+        );
+    }
+
     /// The card background paints the full card width, not just the glyphs.
     #[test]
     fn card_background_covers_the_full_card_width() {
@@ -672,10 +1201,10 @@ mod tests {
         };
         let buf = draw(&sb, 28, 8);
         let y = buf.content.iter().position(|c| c.symbol() == "c").unwrap() as u16 / buf.area.width;
-        for x in 0..27 {
+        for x in 1..27 {
             assert_eq!(
                 buf[(x, y)].style().bg,
-                Some(Color::Black),
+                Some(palette::active().card.bg),
                 "gap in card background at col {x}"
             );
         }
@@ -686,7 +1215,7 @@ mod tests {
     fn highlighted_row_anchors_the_actions_top_right() {
         let sb = Sidebar {
             sessions: vec![session_named(1, "claude")],
-            highlight: Some(Uuid::from_u128(1)),
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
         };
         let all = rows(&draw(&sb, 28, 8));
@@ -703,7 +1232,7 @@ mod tests {
         let two = session_named(2, "bash");
         let sb = Sidebar {
             sessions: vec![one, two],
-            highlight: Some(Uuid::from_u128(1)),
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
         };
         let all = rows(&draw(&sb, 28, 8));
@@ -724,7 +1253,7 @@ mod tests {
         }
         let sb = Sidebar {
             sessions: vec![s],
-            highlight: Some(Uuid::from_u128(1)),
+            highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
         };
         let all = rows(&draw(&sb, 28, 8));

crates/maestro-tui/src/state.rs

@@ -8,6 +8,9 @@
 //!
 //! v1.5 will replace `Tab::pane`'s single slot with a split tree.
 
+use std::collections::HashSet;
+use std::path::PathBuf;
+
 use uuid::Uuid;
 
 use crate::draft::DraftPane;
@@ -19,6 +22,16 @@ pub enum Focus {
     Pane,
 }
 
+/// One selectable item in the rendered sidebar sequence.
+///
+/// Group paths, unlike a session's position in the catalog, survive catalog
+/// redraws and make a highlighted collapsed group unambiguous.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum SidebarItem {
+    Group(PathBuf),
+    Session(Uuid),
+}
+
 /// What a tab's pane slot holds: a live session, or an inline draft form.
 // The draft variant dwarfs `Session(Uuid)`; tabs are moved rarely enough
 // that boxing every access costs more than the copy does.
@@ -70,7 +83,10 @@ pub struct AppState {
     pub focus: Focus,
     pub mode: Mode,
     pub sidebar_visible: bool,
-    pub sidebar_highlight: Option<Uuid>,
+    pub sidebar_highlight: Option<SidebarItem>,
+    /// Group paths whose cards are hidden. This is UI state rather than
+    /// catalog state, so it survives every catalog redraw.
+    pub collapsed_sidebar_groups: HashSet<PathBuf>,
     /// Private: every transition goes through [`AppState::show_overlay`],
     /// [`AppState::dismiss_overlay`] or [`AppState::toast`]. Poking the field
     /// from four call sites is what left a toast on screen with no way to
@@ -96,6 +112,7 @@ impl AppState {
             mode: Mode::Normal,
             sidebar_visible: true,
             sidebar_highlight: None,
+            collapsed_sidebar_groups: HashSet::new(),
             overlay: None,
         }
     }
@@ -213,19 +230,32 @@ impl AppState {
     }
 
     /// Move the sidebar highlight by `delta` (positive = down) within the
-    /// given ordered list of selectable session ids. Wraps. No-op on empty.
-    pub fn move_sidebar_highlight(&mut self, order: &[Uuid], delta: i32) {
+    /// rendered item sequence. Wraps. No-op on empty.
+    pub fn move_sidebar_highlight(&mut self, order: &[SidebarItem], delta: i32) {
         if order.is_empty() {
             return;
         }
         let len = order.len() as i32;
         let cur = self
             .sidebar_highlight
-            .and_then(|id| order.iter().position(|x| *x == id))
+            .as_ref()
+            .and_then(|id| order.iter().position(|x| x == id))
             .map(|i| i as i32)
             .unwrap_or(-1);
         let next = (cur + delta).rem_euclid(len) as usize;
-        self.sidebar_highlight = Some(order[next]);
+        self.sidebar_highlight = Some(order[next].clone());
+    }
+
+    /// Toggle a group. When collapsing a group containing the current card,
+    /// leave the highlight on the group row that remains visible.
+    pub fn toggle_sidebar_group(&mut self, key: PathBuf, contains_highlight: bool) {
+        if self.collapsed_sidebar_groups.remove(&key) {
+            return;
+        }
+        self.collapsed_sidebar_groups.insert(key.clone());
+        if contains_highlight {
+            self.sidebar_highlight = Some(SidebarItem::Group(key));
+        }
     }
 
     /// Toggle sidebar visibility.
@@ -318,22 +348,30 @@ mod tests {
         let a = Uuid::from_u128(1);
         let b = Uuid::from_u128(2);
         let c = Uuid::from_u128(3);
-        let order = vec![a, b, c];
+        let order = vec![
+            SidebarItem::Session(a),
+            SidebarItem::Group("repo".into()),
+            SidebarItem::Session(b),
+            SidebarItem::Session(c),
+        ];
 
         // No prior highlight + delta +1 lands on first item.
         state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(a));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
 
         state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(b));
+        assert_eq!(
+            state.sidebar_highlight,
+            Some(SidebarItem::Group("repo".into()))
+        );
         state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(c));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
         // Wraps forward.
         state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(a));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(c)));
         // Wraps backward.
         state.move_sidebar_highlight(&order, -1);
-        assert_eq!(state.sidebar_highlight, Some(c));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
     }
 
     #[test]
@@ -343,6 +381,22 @@ mod tests {
         assert_eq!(state.sidebar_highlight, None);
     }
 
+    #[test]
+    fn collapsing_highlighted_group_moves_a_card_highlight_to_the_group() {
+        let key = PathBuf::from("/repo");
+        let mut state = AppState::new();
+        state.sidebar_highlight = Some(SidebarItem::Session(Uuid::from_u128(9)));
+        state.toggle_sidebar_group(key.clone(), true);
+        assert_eq!(
+            state.sidebar_highlight,
+            Some(SidebarItem::Group(key.clone()))
+        );
+        assert!(state.collapsed_sidebar_groups.contains(&key));
+        state.toggle_sidebar_group(key.clone(), false);
+        assert!(!state.collapsed_sidebar_groups.contains(&key));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Group(key)));
+    }
+
     #[test]
     fn attach_binds_focuses_pane_and_enters_insert_mode() {
         let mut state = AppState::new();

crates/maestro/src/main.rs

@@ -19,8 +19,7 @@ use tracing_subscriber::EnvFilter;
 #[command(
     name = "maestro",
     version,
-    about = "Unified CLI / daemon / TUI for the Maestro terminal-session orchestrator",
-    arg_required_else_help = true
+    about = "Unified CLI / daemon / TUI for the Maestro terminal-session orchestrator"
 )]
 struct Cli {
     /// Override the daemon HTTP base clients talk to (e.g.
@@ -37,8 +36,11 @@ struct Cli {
     #[arg(short, long, global = true, action = clap::ArgAction::Count)]
     verbose: u8,
 
+    /// A missing subcommand defaults to the TUI (#119): a bare `maestro` opens
+    /// the terminal UI. Builds without the `tui` feature have no UI surface,
+    /// so they print help and exit 0 instead.
     #[command(subcommand)]
-    command: Command,
+    command: Option<Command>,
 }
 
 #[derive(Debug, Subcommand)]
@@ -89,7 +91,22 @@ fn main() -> ExitCode {
 }
 
 async fn dispatch(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
-    match cli.command {
+    let command = match cli.command {
+        Some(command) => command,
+        None => {
+            #[cfg(feature = "tui")]
+            {
+                Command::Tui(maestro_tui::cli::TuiArgs { daemon_url: None })
+            }
+            #[cfg(not(feature = "tui"))]
+            {
+                use clap::CommandFactory;
+                let _ = <Cli as CommandFactory>::command().print_help();
+                return Ok(());
+            }
+        }
+    };
+    match command {
         #[cfg(feature = "cli")]
         Command::List(args) => {
             maestro_cli::dispatch(
@@ -166,19 +183,19 @@ fn init_tracing(cli: &Cli) {
 }
 
 #[cfg(feature = "cli")]
-fn is_cli_subcommand(command: &Command) -> bool {
+fn is_cli_subcommand(command: &Option<Command>) -> bool {
     matches!(
         command,
-        Command::List(_)
-            | Command::Spawn(_)
-            | Command::Attach(_)
-            | Command::Kill(_)
-            | Command::Hooks(_)
+        Some(Command::List(_))
+            | Some(Command::Spawn(_))
+            | Some(Command::Attach(_))
+            | Some(Command::Kill(_))
+            | Some(Command::Hooks(_))
     )
 }
 
 #[cfg(not(feature = "cli"))]
-fn is_cli_subcommand(_command: &Command) -> bool {
+fn is_cli_subcommand(_command: &Option<Command>) -> bool {
     false
 }
 
@@ -216,12 +233,20 @@ mod tests {
     }
 
     /// Parse argv the way `main` does, returning just the dispatched subcommand.
-    fn command_of(argv: &[&str]) -> Command {
+    fn command_of(argv: &[&str]) -> Option<Command> {
         Cli::try_parse_from(argv)
             .unwrap_or_else(|e| panic!("parse {argv:?}: {e}"))
             .command
     }
 
+    #[test]
+    fn bare_invocation_parses_to_no_subcommand() {
+        // The TUI-vs-help default is applied in `dispatch`; parsing must not
+        // reject an empty argv.
+        assert!(command_of(&["maestro"]).is_none());
+        assert!(command_of(&["maestro", "--verbose"]).is_none());
+    }
+
     #[cfg(feature = "cli")]
     #[test]
     fn cli_subcommands_are_classified_as_cli() {

crates/maestro/tests/cli.rs

@@ -54,11 +54,35 @@ fn version_flag_succeeds() {
     assert!(text.contains("maestro"), "--version output: {text}");
 }
 
+/// A bare `maestro` must never fall back to help on a build that has a TUI:
+/// the missing subcommand defaults to `tui` (#119). Point at a port with
+/// nothing listening so the TUI's health probe fails fast instead of blocking
+/// on a terminal.
+#[cfg(feature = "tui")]
 #[test]
-fn no_args_prints_help_and_fails() {
-    // `arg_required_else_help = true` => exit non-zero but show usage.
+fn bare_invocation_dispatches_to_the_tui() {
+    let (ok, text) = run(&["--daemon-url", "http://127.0.0.1:9"]);
+    assert!(
+        !ok,
+        "TUI against a dead daemon should exit non-zero:\n{text}"
+    );
+    assert!(
+        text.contains("daemon unreachable"),
+        "bare invocation should have run the TUI's daemon probe:\n{text}"
+    );
+    assert!(
+        !text.contains("Usage"),
+        "bare invocation must not print help when a TUI exists:\n{text}"
+    );
+}
+
+/// Builds without the `tui` feature keep the historical behaviour: no args =>
+/// help, exit 0 (#119).
+#[cfg(not(feature = "tui"))]
+#[test]
+fn bare_invocation_prints_help_and_exits_zero() {
     let (ok, text) = run(&[]);
-    assert!(!ok, "bare invocation should fail:\n{text}");
+    assert!(ok, "bare invocation should exit 0:\n{text}");
     assert!(text.contains("Usage"), "expected usage text:\n{text}");
 }
 

docs/INSTALL.md

@@ -119,6 +119,9 @@ The wizard always installs the default-feature build.
 
 `maestro tui` is the keyboard-and-mouse driven terminal UI client. It ships
 in the default feature set, so a vanilla `cargo install maestro` builds it.
+A bare `maestro` opens the TUI too — the missing subcommand defaults to `tui`
+(#119), so `maestro --daemon-url http://host:7070` works as well. Builds
+without the `tui` feature have no UI to open and print help instead (exit 0).
 Drop the `tui` feature to skip it on hosts that don't need the UI surface
 (`--no-default-features --features cli,daemon`).
 
@@ -131,6 +134,7 @@ cover every v1 action — only override what you want to change:
 
 ```toml
 [tui]
+theme = "dark"              # dark (default), light, or ansi
 leader = "ctrl-a"            # one byte that escapes Insert mode
 chord_timeout_ms = 1000      # how long to hold a partial chord like `g`
 
@@ -149,6 +153,11 @@ chord_timeout_ms = 1000      # how long to hold a partial chord like `g`
 # want extra Insert-mode bindings)
 ```
 
+`theme` selects the complete TUI palette. `dark` is the default and follows
+Maestro's terminal-native dark product palette; `light` is its light peer;
+`ansi` uses the terminal's named ANSI colours for terminals without truecolour.
+An unknown name is rejected as an `[tui].theme` configuration error.
+
 The full action vocabulary is the `Action` enum in
 `crates/maestro-tui/src/action.rs`.
 

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,61 +24,75 @@ 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 `⚠ <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:
+Line 2 reads left to right:
 
 ```
-<dot> <duration> [<detail>] [<blocked work> | exited] [<command>]
+<dot> [<duration>] [<detail>] [<blocked work> | exited] <command>
 ```
 
+Its minimum content is therefore the dot and the command.
+
 `<dot>` is a single filled glyph (`●` on both clients) carrying the activity
-state's colour, and `<duration>` 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 `<duration>` 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.
+
+`<duration>` 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.
 
 `<detail>` 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
 while an agent-reported state is in force (see Precedence): when the report
-lapses at its TTL or is replaced, the detail goes with it.
+lapses at its TTL or is replaced, the detail goes with it. The detail
+truncates with `…` ahead of the trailing fragments — a long detail never
+pushes `<blocked work>`, `exited`, or `<command>` off the line, and neither
+client ever lets it wrap.
 
-`<command>` 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).
+`<command>` 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
 
 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`      |
+| Activity state   | Web token | TUI palette role |
+| ---------------- | --------- | ---------------- |
+| `Active`         | `--live`  | `active`         |
+| `Idle`           | `--muted` | `idle`           |
+| `AwaitingInput`  | `--warn`  | `awaiting`       |
+| `Error`          | `--danger`| `error`          |
 
 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.
+and `prefers-color-scheme` variants for each). The TUI names roles, not
+colours: a role's value comes from the active palette
+(`maestro-tui/src/palette.rs`), never from a colour spelled out at the use
+site.
+
+A palette holds one role set per **surface** — the card surface every card
+sits on, and the selection surface the highlighted card swaps in — so each
+state role resolves to the value picked for the surface it is painted on. The
+highlighted card therefore takes its state colours from the selection
+surface; a colour chosen for the card background is never painted onto the
+selection background. Contrast is a property of the palette (values are RGB)
+and is asserted in the palette's tests, not left to the terminal theme.
 
 The duration text inherits its state's colour; the blocked-work, exited and
-command fragments use the muted colour (`--faint` / default style), since the
-⚠ glyph already signals severity.
+command fragments use the surface's `muted` role, since the ⚠ glyph already
+signals severity.
 
 ## Duration format
 
@@ -104,6 +117,20 @@ When the TTL expires, inference resumes and the session's reported detail —
 if any — clears with the report. Clients never blend the two: whichever source
 is in force supplies both the colour and the clock for `activity_since`.
 
+Two rulings specific to a reported `Error` (#114):
+
+- **The five-minute TTL applies to `Error` like to any other state.** A
+  session that failed is still failed after five minutes, but a card pinned
+  red forever lies once the session moves on; when the report lapses the card
+  returns to the daemon's own inference — usually `Idle` for a session that
+  has gone quiet.
+- **Only a new report clears an `Error` before its TTL.** The next
+  `ActivityState` of any kind replaces it (with #106's hook that is typically
+  `PreToolUse` → `Active` when the user prompts again). PTY output and
+  process changes do not clear it — only the agent itself may withdraw what
+  the agent itself reported. Re-reporting `Error` extends the TTL rather than
+  stacking reports.
+
 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

web/src/activity.test.ts

@@ -4,9 +4,7 @@ import {
   activityColorSlug,
   activityDurationLabel,
   activityHeldMs,
-  showsMetaLine,
 } from "./activity.js";
-import type { Session } from "./types.js";
 
 describe("activityHeldMs", () => {
   it("measures time spent in the current state", () => {
@@ -60,42 +58,3 @@ describe("activityColorSlug", () => {
     expect(activityColorSlug("Teleported")).toBe("idle");
   });
 });
-
-function session(overrides: Partial<Session>): Session {
-  return {
-    id: "11111111-2222-3333-4444-555555555555",
-    cwd: "/home/naps/tea/maestro",
-    command: "claude",
-    env: {},
-    metadata: {},
-    status: "Running",
-    created_at: "2026-08-24T10:00:00Z",
-    activity: "Active",
-    ...overrides,
-  };
-}
-
-describe("showsMetaLine", () => {
-  const fresh = new Date(Date.now() - 10_000).toISOString();
-
-  it("stays hidden for a freshly-active session", () => {
-    expect(showsMetaLine(session({ activity_since: fresh }))).toBe(false);
-  });
-
-  it("appears once the state has been held past 30 seconds", () => {
-    const held = new Date(Date.now() - 31_000).toISOString();
-    expect(showsMetaLine(session({ activity_since: held }))).toBe(true);
-  });
-
-  it("appears for blocked work, exited sessions and reported errors", () => {
-    expect(
-      showsMetaLine(session({ activity_since: fresh, blocked_work: { uncommitted_files: 1 } })),
-    ).toBe(true);
-    expect(showsMetaLine(session({ activity_since: fresh, status: "Dead" }))).toBe(true);
-    expect(showsMetaLine(session({ activity_since: fresh, activity: "Error" }))).toBe(true);
-  });
-
-  it("needs no activity timestamp when another trigger holds", () => {
-    expect(showsMetaLine(session({ activity_since: undefined, status: "Dead" }))).toBe(true);
-  });
-});

web/src/activity.ts

@@ -2,11 +2,10 @@
 // the shared duration format. Both clients compute it identically; the TUI
 // mirrors this in crates/maestro-tui.
 
-import type { ActivityState, IsoTimestamp, Session } from "./types.js";
-import { sessionBlockers } from "./types.js";
+import type { ActivityState, IsoTimestamp } from "./types.js";
 
-/** A state held shorter than this keeps the card to one line (contract rule 1). */
-const META_LINE_MIN_HOLD_MS = 30_000;
+/** A state held shorter than this has no duration fragment. */
+export const META_LINE_MIN_HOLD_MS = 30_000;
 
 // Payloads predating #102 default `activity_since` to the Unix epoch; anything
 // implausibly old is treated as "never observed" rather than a huge duration.
@@ -43,14 +42,3 @@ export function activityColorSlug(state: ActivityState | string): string {
       return "idle";
   }
 }
-
-/** Line 2 renders only when at least one contract trigger holds. */
-export function showsMetaLine(s: Session, now: number = Date.now()): boolean {
-  const held = activityHeldMs(s.activity_since, now);
-  return (
-    (held !== null && held >= META_LINE_MIN_HOLD_MS) ||
-    sessionBlockers(s) !== null ||
-    s.status === "Dead" ||
-    s.activity === "Error"
-  );
-}

web/src/catalog.test.ts

@@ -105,6 +105,38 @@ describe("blocked-work indicator (#83)", () => {
   });
 });
 
+describe("agent-reported detail (#112)", () => {
+  const ago = (ms: number): string => new Date(Date.now() - ms).toISOString();
+
+  it("renders the reported detail right after the duration on line 2", () => {
+    const s = session({
+      id: "aaaaaaaa-0000-0000-0000-000000000020",
+      status: "Dead",
+      activity: "Error",
+      activity_since: ago(90_000),
+      activity_detail: "cargo build failed",
+    });
+    const el = renderSidebar(storeWith([s])).el;
+    const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
+    expect(line2?.querySelector(".activity-detail")?.textContent).toBe("cargo build failed");
+    const order = [...line2!.children].map((c) => c.className);
+    expect(order.indexOf("activity-detail")).toBeGreaterThan(order.indexOf("activity-duration"));
+    expect(order.indexOf("activity-detail")).toBeLessThan(
+      order.findIndex((c) => c.startsWith("card-flag")),
+    );
+  });
+
+  it("omits the detail when no report is in force", () => {
+    const s = session({
+      id: "aaaaaaaa-0000-0000-0000-000000000021",
+      activity: "Active",
+      activity_since: ago(90_000),
+    });
+    const el = renderSidebar(storeWith([s])).el;
+    expect(rowFor(el, s.id)?.querySelector(".activity-detail")).toBeNull();
+  });
+});
+
 describe("session cards (#107)", () => {
   const ago = (ms: number): string => new Date(Date.now() - ms).toISOString();
 
@@ -118,14 +150,18 @@ describe("session cards (#107)", () => {
     expect(line1?.querySelector(".leaf-actions")).toBe(line1?.lastElementChild);
   });
 
-  it("stays a single line while freshly active", () => {
+  it("always renders line 2 for a freshly spawned session", () => {
     const s = session({
       id: "aaaaaaaa-0000-0000-0000-000000000011",
       activity: "Active",
       activity_since: ago(5_000),
     });
     const el = renderSidebar(storeWith([s])).el;
-    expect(rowFor(el, s.id)?.querySelector(".card-line2")).toBeNull();
+    const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
+    expect(line2).not.toBeNull();
+    expect(line2?.querySelector(".activity-dot")).not.toBeNull();
+    expect(line2?.querySelector(".activity-duration")).toBeNull();
+    expect(line2?.querySelector(".leaf-cmd")?.textContent).toBe("claude");
   });
 
   it("shows dot + floored duration once the state has been held past 30s", () => {
@@ -141,6 +177,16 @@ describe("session cards (#107)", () => {
     expect(line2?.querySelector(".activity-duration")?.textContent).toBe("4m");
   });
 
+  it("renders the command when the session name equals it", () => {
+    const s = session({
+      id: "aaaaaaaa-0000-0000-0000-00000000001b",
+      command: "claude",
+      metadata: { name: "claude" },
+    });
+    const el = renderSidebar(storeWith([s])).el;
+    expect(rowFor(el, s.id)?.querySelector(".card-line2 .leaf-cmd")?.textContent).toBe("claude");
+  });
+
   it("maps each activity state to its contract slug", () => {
     const mk = (id: string, activity: string) =>
       session({

web/src/catalog.ts

@@ -4,7 +4,12 @@ import { HUD_TOGGLE_EVENT, isHudEnabled, toggleHud } from "./debug.js";
 import { CatalogStore } from "./events.js";
 import type { Session } from "./types.js";
 import { abbreviateFolderName, formatInTheWay, sessionBlockers, sessionName } from "./types.js";
-import { activityColorSlug, activityDurationLabel, activityHeldMs, showsMetaLine } from "./activity.js";
+import {
+  activityColorSlug,
+  activityDurationLabel,
+  activityHeldMs,
+  META_LINE_MIN_HOLD_MS,
+} from "./activity.js";
 import type { TreeNode } from "./tree.js";
 import { buildTree } from "./tree.js";
 import { createThemeToggle } from "./theme.js";
@@ -28,27 +33,25 @@ const STATE_WORDS: Record<string, string> = {
 };
 
 function metaLine(s: Session, now: number): string {
-  const name = sessionName(s);
   const dead = s.status === "Dead";
   const blockers = sessionBlockers(s);
   const slug = activityColorSlug(s.activity ?? "Idle");
   const stateWord = STATE_WORDS[slug] ?? STATE_WORDS.idle;
   const held = activityHeldMs(s.activity_since, now);
-  const duration = held !== null ? activityDurationLabel(held) : null;
-  // The directory is the enclosing folder, so only surface the command — and
-  // only when it isn't already what the name shows.
-  const showCmd = s.command !== name;
+  const duration =
+    held !== null && held >= META_LINE_MIN_HOLD_MS ? activityDurationLabel(held) : null;
 
   const fragments = [
     `<span class="activity-dot" role="img" title="${escapeHtml(stateWord)}" aria-label="${escapeHtml(stateWord)}"></span>`,
     duration ? `<span class="activity-duration">${duration}</span>` : "",
+    s.activity_detail
+      ? `<span class="activity-detail">${escapeHtml(s.activity_detail)}</span>`
+      : "",
     blockers
       ? `<span class="card-flag leaf-blocked" title="Kill will be refused unless forced">⚠ ${escapeHtml(formatInTheWay(blockers))}</span>`
       : "",
     dead ? `<span class="card-flag">exited</span>` : "",
-    showCmd
-      ? `<span class="card-flag leaf-cmd" title="${escapeHtml(s.command)}">${escapeHtml(s.command)}</span>`
-      : "",
+    `<span class="card-flag leaf-cmd" title="${escapeHtml(s.command)}">${escapeHtml(s.command)}</span>`,
   ];
   return `<span class="card-line2" data-activity="${slug}">${fragments.join("")}</span>`;
 }
@@ -103,10 +106,7 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     "aria-label",
     `${name}, ${running ? "running" : "exited"}, ${stateWord}`,
   );
-  // docs/SIDEBAR.md line 1: name + top-right actions in the same flow line —
-  // the actions reserve their width, so the name truncates before it can ever
-  // reach them. Line 2 renders only when a contract trigger holds.
-  const showMeta = showsMetaLine(s, now);
+  // docs/SIDEBAR.md: line 1 reserves action width, and line 2 is unconditional.
   row.innerHTML = `
     <span class="card-line1">
       <span class="leaf-name">${escapeHtml(name)}</span>
@@ -115,7 +115,7 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
         <button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${escapeHtml(name)}">✕</button>
       </span>
     </span>
-    ${showMeta ? metaLine(s, now) : ""}
+    ${metaLine(s, now)}
   `;
   const similarBtn = row.querySelector(".leaf-clone") as HTMLButtonElement;
   similarBtn.addEventListener("click", (ev) => {

web/src/styles.css

@@ -736,7 +736,6 @@ textarea {
   display: flex;
   align-items: center;
   gap: var(--sp-2);
-  min-height: 30px;
   margin: 1px var(--sp-2);
   padding: 4px var(--sp-3);
   border-radius: var(--r-1);
@@ -787,12 +786,13 @@ textarea {
   font-weight: 400;
 }
 
-/* #107: session cards per docs/SIDEBAR.md — line 1 (name + top-right actions)
-   always, line 2 (meta) only when it has something to say. */
+/* #120: every session card has two lines, so its row height is stable. */
 .tree-leaf.session-card {
   flex-direction: column;
   align-items: stretch;
   gap: 1px;
+  /* 24px action row + 16px meta row + 1px gap + 8px vertical padding. */
+  height: 49px;
 }
 
 .card-line1 {
@@ -851,16 +851,35 @@ textarea {
   flex: 0 0 auto;
 }
 
-/* Blocked-work / exited / command fragments recede: the ⚠ glyph already
-   signals severity and "exited" dims with the row. */
-.card-flag {
+/* Agent-reported detail (#112): sits after the duration, shrinks with an
+   ellipsis so it never pushes the trailing fragments off the line. */
+.activity-detail {
   color: var(--faint);
+  /* Consume only the space left after the trailing status + command. */
+  flex: 1 1 0;
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+/* Blocked-work / exited / command fragments recede: the ⚠ glyph already
+   signals severity and "exited" dims with the row. */
+.card-flag {
+  color: var(--faint);
+  flex: 0 0 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Status fragments stay intact. The unconditional command is the final
+   truncation target when even the complete trailing set cannot fit. */
+.leaf-cmd {
+  flex: 0 1 auto;
+}
+
 /* Actions live in line 1's flow at its right edge — never overlaid on the
    name (#107). They reserve their width even while hover-faded. */
 .leaf-actions {