fix(maestro): arbitrate pane size across clients

Every attached client pushed its own dimensions straight to
`tmux resize-window`, so two clients of different sizes resized the
shared window past each other on every report — 198 resizes in 90
seconds on a four-session daemon. Each flip repaints a full-screen agent
at a new height and orphans the rows it drew at the old one, leaving a
stale input box the operator types into and reads as a stuck pane.

The window now goes to the smallest attached client per axis, tmux's own
rule for multiple clients, and only when that size actually changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

crates/maestro-cli/src/sessions.rs

@@ -251,7 +251,6 @@ mod tests {
             activity_since: chrono::Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 

crates/maestro-daemon/src/attach.rs

@@ -26,11 +26,17 @@ pub(crate) async fn serve(
 ) -> Result<(), axum::Error> {
     let (mut sink, mut stream) = socket.split();
 
+    // This client's claim on the shared window size. Registered up front and
+    // released on every exit below, so a socket that dies mid-session stops
+    // constraining the size for the clients still attached.
+    let viewport = manager.attach_viewport();
+
     // NAP-229: send buffered scrollback up-front so the client sees the last
     // screenful immediately instead of a blank terminal. The replay lock the
     // bridge held during snapshot+subscribe guarantees no byte appears both
     // here and on the live receiver, and none is dropped at the seam.
     if !replay.is_empty() && sink.send(Message::Binary(replay)).await.is_err() {
+        manager.release_viewport(id, viewport).await;
         return Ok(());
     }
 
@@ -70,7 +76,7 @@ pub(crate) async fn serve(
                     if let Ok(ctrl) = serde_json::from_str::<ClientControl>(&text) {
                         match ctrl {
                             ClientControl::Resize { cols, rows } => {
-                                let _ = manager.resize(id, cols, rows).await;
+                                let _ = manager.set_viewport(id, viewport, cols, rows).await;
                             }
                             ClientControl::Ping => {
                                 let pong = serde_json::to_string(&ClientControl::Pong)
@@ -88,6 +94,8 @@ pub(crate) async fn serve(
         }
     }
 
+    manager.release_viewport(id, viewport).await;
+
     if session_ended {
         let _ = sink.send(Message::Close(None)).await;
     }

crates/maestro-daemon/src/lib.rs

@@ -30,6 +30,7 @@ pub mod spawn_history;
 #[cfg(feature = "web")]
 pub mod static_bundle;
 pub mod tmux;
+pub mod viewport;
 pub mod worktree;
 pub mod worktree_probe;
 

crates/maestro-daemon/src/session.rs

@@ -7,6 +7,7 @@
 
 use std::collections::{HashMap, HashSet};
 use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -23,6 +24,7 @@ use crate::pty::{pipe_pane_command, PtyBridge};
 use crate::sidecar::{SidecarError, SidecarStore};
 use crate::spawn_history::{RecentDir, SpawnHistory, SpawnHistoryRecord};
 use crate::tmux::TmuxError;
+use crate::viewport::{ViewportId, Viewports};
 use crate::worktree::{WorktreeError, WorktreeManager};
 
 /// Capacity of the session-events broadcast channel. A subscriber that falls
@@ -166,6 +168,14 @@ struct Inner {
     report_ttl: Duration,
     sessions: Mutex<HashMap<Uuid, SessionRecord>>,
     events: broadcast::Sender<CatalogEvent>,
+    /// Sizes reported by the clients attached to each session, and what tmux
+    /// was last told. See [`crate::viewport`] for why the window is not simply
+    /// set to whatever arrived most recently.
+    viewports: Mutex<Viewports>,
+    /// Hands out [`ViewportId`]s. Monotonic for the daemon's lifetime, so a
+    /// client that reconnects never collides with the registration its
+    /// previous socket has not finished releasing.
+    next_viewport: AtomicU64,
 }
 
 impl SessionManager {
@@ -206,6 +216,8 @@ impl SessionManager {
                 report_ttl: crate::activity::REPORT_TTL,
                 sessions: Mutex::new(HashMap::new()),
                 events,
+                viewports: Mutex::new(Viewports::new()),
+                next_viewport: AtomicU64::new(0),
             }),
         }
     }
@@ -285,50 +297,33 @@ impl SessionManager {
     /// Subscribe to a session's PTY broadcast and return the replay buffer
     /// (NAP-229). Callers send the buffer before pumping the live receiver
     /// so freshly-attached clients see the last screenful immediately.
-    ///
-    /// Opening an attach is focusing (#145): it stamps
-    /// [`Session::last_focused_at`], the same field `set_focused` stamps, so
-    /// a client that only ever attaches sorts identically to one that
-    /// reports focus explicitly.
     pub async fn subscribe_pty_with_replay(
         &self,
         id: Uuid,
     ) -> Option<(Vec<u8>, broadcast::Receiver<Vec<u8>>)> {
         let tmux = self.inner.tmux.clone();
-        let (result, updated) = {
-            let mut sessions = self.inner.sessions.lock().await;
-            let rec = sessions.get_mut(&id)?;
-            rec.session.last_focused_at = Some(Utc::now());
-            let updated = rec.session.clone();
-            // For a live session, tmux's own screen beats the byte tail: the
-            // tail starts mid-stream, so a full-screen program (an agent TUI)
-            // replayed from it renders as garbage until something forces a
-            // repaint. A dead session has no pane left to capture, so it
-            // keeps the byte tail.
-            let alive = rec.session.status == SessionStatus::Running;
-            // The capture shells out to tmux while the replay lock is held,
-            // which parks the reader for the length of one tmux round-trip.
-            // That only happens on attach, and the alternative is a seam in
-            // the stream.
-            let result = rec.bridge.subscribe_with_snapshot(|| {
-                if !alive {
-                    return None;
+        let sessions = self.inner.sessions.lock().await;
+        let rec = sessions.get(&id)?;
+        // For a live session, tmux's own screen beats the byte tail: the tail
+        // starts mid-stream, so a full-screen program (an agent TUI) replayed
+        // from it renders as garbage until something forces a repaint. A dead
+        // session has no pane left to capture, so it keeps the byte tail.
+        let alive = rec.session.status == SessionStatus::Running;
+        // The capture shells out to tmux while the replay lock is held, which
+        // parks the reader for the length of one tmux round-trip. That only
+        // happens on attach, and the alternative is a seam in the stream.
+        Some(rec.bridge.subscribe_with_snapshot(|| {
+            if !alive {
+                return None;
+            }
+            match tmux.capture_pane(id) {
+                Ok(snapshot) => snapshot,
+                Err(e) => {
+                    tracing::warn!(error = ?e, %id, "capture-pane failed; replaying raw bytes");
+                    None
                 }
-                match tmux.capture_pane(id) {
-                    Ok(snapshot) => snapshot,
-                    Err(e) => {
-                        tracing::warn!(error = ?e, %id, "capture-pane failed; replaying raw bytes");
-                        None
-                    }
-                }
-            });
-            (result, updated)
-        };
-        let _ = self
-            .inner
-            .events
-            .send(CatalogEvent::SessionUpdated { session: updated });
-        Some(result)
+            }
+        }))
     }
 
     pub async fn has(&self, id: Uuid) -> bool {
@@ -465,7 +460,6 @@ impl SessionManager {
             // The watcher fills this in on its first blocked-work pass; a
             // fresh tree has nothing in the way anyway.
             blocked_work: None,
-            last_focused_at: None,
         };
 
         if let Err(e) = self.inner.sidecar.write(&session) {
@@ -670,7 +664,6 @@ impl SessionManager {
 
                     current_cwd: None,
                     blocked_work: None,
-                    last_focused_at: None,
                 },
             };
             let fifo_path = self.inner.fifo_dir.join(format!("{id}.fifo"));
@@ -770,6 +763,52 @@ impl SessionManager {
             .map_err(SessionError::Tmux)
     }
 
+    /// Register a client that is about to start reporting its display size,
+    /// and hand back the handle it reports under.
+    ///
+    /// Cheap and infallible: the session it will report against is not
+    /// consulted until the first [`Self::set_viewport`].
+    pub fn attach_viewport(&self) -> ViewportId {
+        self.inner.next_viewport.fetch_add(1, Ordering::Relaxed)
+    }
+
+    /// A client reported the size it can display.
+    ///
+    /// The shared tmux window is resized only when the size arbitrated across
+    /// every attached client actually changes — see [`crate::viewport`]. Two
+    /// clients of different sizes used to resize the window past each other on
+    /// every report, which leaves a full-screen agent repainting into rows it
+    /// never clears and looking, to the operator, like a pane that has stopped
+    /// accepting input.
+    pub async fn set_viewport(
+        &self,
+        id: Uuid,
+        viewport: ViewportId,
+        cols: u16,
+        rows: u16,
+    ) -> Result<(), SessionError> {
+        let target = self
+            .inner
+            .viewports
+            .lock()
+            .await
+            .set(id, viewport, cols, rows);
+        match target {
+            Some((cols, rows)) => self.resize(id, cols, rows).await,
+            None => Ok(()),
+        }
+    }
+
+    /// Drop a detached client's claim on the window size, resizing to what the
+    /// clients still attached can display. Errors are the caller's to ignore:
+    /// a socket closing because its session died has nothing left to resize.
+    pub async fn release_viewport(&self, id: Uuid, viewport: ViewportId) {
+        let target = self.inner.viewports.lock().await.release(id, viewport);
+        if let Some((cols, rows)) = target {
+            let _ = self.resize(id, cols, rows).await;
+        }
+    }
+
     /// Rename a session (#125): set `metadata.name`, or clear it when the
     /// requested name is blank so the session falls back to its command.
     ///
@@ -857,26 +896,11 @@ impl SessionManager {
     /// Record whether a client's pane is currently showing `id`. Read by the
     /// activity pass's next tick to decide whether an `AwaitingInput` glow
     /// has been looked at long enough to clear (`apply_focus_suppression`).
-    /// Gaining focus also stamps [`Session::last_focused_at`] (#145) — losing
-    /// it does not, since the command bar's ordering cares about the last
-    /// time the operator arrived, not when they left. An unknown session is
-    /// [`SessionError::NotFound`].
+    /// An unknown session is [`SessionError::NotFound`].
     pub async fn set_focused(&self, id: Uuid, focused: bool) -> Result<(), SessionError> {
-        let updated = {
-            let mut sessions = self.inner.sessions.lock().await;
-            let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
-            rec.focused_since = focused.then(std::time::Instant::now);
-            if focused {
-                rec.session.last_focused_at = Some(Utc::now());
-            }
-            focused.then(|| rec.session.clone())
-        };
-        if let Some(session) = updated {
-            let _ = self
-                .inner
-                .events
-                .send(CatalogEvent::SessionUpdated { session });
-        }
+        let mut sessions = self.inner.sessions.lock().await;
+        let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
+        rec.focused_since = focused.then(std::time::Instant::now);
         Ok(())
     }
 }

crates/maestro-daemon/src/viewport.rs

@@ -0,0 +1,186 @@
+//! What size the shared tmux window should be, given every client watching it.
+//!
+//! A tmux window has one size, but a session can have several clients attached
+//! at once — two browser panes, a browser and the TUI. Each reports the size
+//! *it* can display, and applying whichever arrived last makes the window
+//! flip-flop. Every flip forces a full-screen application (Claude Code, vim) to
+//! repaint at a new height, and the rows it drew at the old height are never
+//! cleared: the operator ends up looking at a stale input box, types into a
+//! box that is not where the screen says it is, and concludes the pane is
+//! stuck.
+//!
+//! So the window is sized to the smallest attached client on each axis — the
+//! same rule tmux uses for its own multiple clients, and the only size every
+//! client can render without truncation. The size last handed to tmux is
+//! remembered, so a report that changes nothing costs no `tmux` fork at all.
+
+use std::collections::HashMap;
+
+use uuid::Uuid;
+
+/// One attached client within a session. Allocated by
+/// [`crate::session::SessionManager`] and opaque to everything else.
+pub type ViewportId = u64;
+
+/// Per-session client sizes, and what tmux was last told.
+#[derive(Debug, Default)]
+pub struct Viewports {
+    clients: HashMap<Uuid, HashMap<ViewportId, (u16, u16)>>,
+    applied: HashMap<Uuid, (u16, u16)>,
+}
+
+impl Viewports {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Record what `viewport` can display. Returns the size tmux must be set
+    /// to, or `None` when the window already has it.
+    pub fn set(
+        &mut self,
+        session: Uuid,
+        viewport: ViewportId,
+        cols: u16,
+        rows: u16,
+    ) -> Option<(u16, u16)> {
+        self.clients
+            .entry(session)
+            .or_default()
+            .insert(viewport, (cols, rows));
+        self.settle(session)
+    }
+
+    /// Drop a client that has detached. Returns the size tmux must be set to
+    /// now that it no longer constrains the window.
+    ///
+    /// The last client leaving settles nothing: the window keeps the size it
+    /// has rather than snapping to some remembered default no one is watching.
+    pub fn release(&mut self, session: Uuid, viewport: ViewportId) -> Option<(u16, u16)> {
+        let clients = self.clients.get_mut(&session)?;
+        clients.remove(&viewport);
+        if clients.is_empty() {
+            self.clients.remove(&session);
+            self.applied.remove(&session);
+            return None;
+        }
+        self.settle(session)
+    }
+
+    /// The smallest size every attached client can render, but only when it
+    /// differs from what tmux was last told.
+    ///
+    /// A zero on either axis is a client that cannot display anything yet — a
+    /// pane still laying out, a hidden tab — and must not drag the shared
+    /// window down with it, so it is held but left out of the arbitration.
+    fn settle(&mut self, session: Uuid) -> Option<(u16, u16)> {
+        let clients = self.clients.get(&session)?;
+        let mut cols = u16::MAX;
+        let mut rows = u16::MAX;
+        for &(c, r) in clients.values() {
+            if c == 0 || r == 0 {
+                continue;
+            }
+            cols = cols.min(c);
+            rows = rows.min(r);
+        }
+        if cols == u16::MAX || rows == u16::MAX {
+            return None;
+        }
+        let target = (cols, rows);
+        if self.applied.get(&session) == Some(&target) {
+            return None;
+        }
+        self.applied.insert(session, target);
+        Some(target)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_first_report_settles_the_window() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        assert_eq!(v.set(s, 1, 80, 24), Some((80, 24)));
+    }
+
+    #[test]
+    fn a_report_that_changes_nothing_costs_no_resize() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        v.set(s, 1, 80, 24);
+        assert_eq!(v.set(s, 1, 80, 24), None);
+        assert_eq!(v.set(s, 1, 80, 24), None);
+    }
+
+    /// The bug this module exists for: two clients of different sizes used to
+    /// resize the window past each other on every report.
+    #[test]
+    fn two_clients_settle_on_the_smaller_instead_of_fighting() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        assert_eq!(v.set(s, 1, 53, 46), Some((53, 46)));
+        assert_eq!(v.set(s, 2, 53, 20), Some((53, 20)));
+        // Whatever order they re-report in, the answer stays the smaller one.
+        assert_eq!(v.set(s, 1, 53, 46), None);
+        assert_eq!(v.set(s, 2, 53, 20), None);
+        assert_eq!(v.set(s, 1, 53, 46), None);
+    }
+
+    #[test]
+    fn each_axis_is_arbitrated_on_its_own() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        v.set(s, 1, 200, 20);
+        assert_eq!(v.set(s, 2, 53, 46), Some((53, 20)));
+    }
+
+    #[test]
+    fn a_zero_sized_client_does_not_shrink_the_window() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        assert_eq!(v.set(s, 1, 80, 24), Some((80, 24)));
+        assert_eq!(v.set(s, 2, 0, 0), None);
+        assert_eq!(v.set(s, 2, 0, 30), None);
+    }
+
+    #[test]
+    fn releasing_the_small_client_gives_the_window_back() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        v.set(s, 1, 80, 46);
+        v.set(s, 2, 80, 20);
+        assert_eq!(v.release(s, 2), Some((80, 46)));
+    }
+
+    #[test]
+    fn releasing_the_last_client_settles_nothing() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        v.set(s, 1, 80, 24);
+        assert_eq!(v.release(s, 1), None);
+        // ...and the session is forgotten, so a fresh attach settles again.
+        assert_eq!(v.set(s, 2, 80, 24), Some((80, 24)));
+    }
+
+    #[test]
+    fn releasing_an_unknown_viewport_is_harmless() {
+        let mut v = Viewports::new();
+        let s = Uuid::new_v4();
+        assert_eq!(v.release(s, 7), None);
+        v.set(s, 1, 80, 24);
+        assert_eq!(v.release(s, 7), None);
+    }
+
+    #[test]
+    fn sessions_do_not_arbitrate_against_each_other() {
+        let mut v = Viewports::new();
+        let a = Uuid::new_v4();
+        let b = Uuid::new_v4();
+        assert_eq!(v.set(a, 1, 80, 24), Some((80, 24)));
+        assert_eq!(v.set(b, 2, 53, 20), Some((53, 20)));
+        assert_eq!(v.set(a, 1, 80, 24), None);
+    }
+}

crates/maestro-daemon/tests/local_api.rs

@@ -383,41 +383,6 @@ async fn patch_unknown_session_returns_404() {
     assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
 }
 
-/// #145: `POST /.../focus` with `focused: true` over HTTP stamps
-/// `last_focused_at`, observable on the next `GET /api/sessions`.
-#[tokio::test]
-async fn post_focus_stamps_last_focused_at() {
-    let h = spawn("naps-laptop").await;
-    let session = h
-        .manager
-        .create(CreateSessionRequest {
-            cwd: "/tmp".into(),
-            command: "sleep 60".into(),
-            env: HashMap::new(),
-            metadata: HashMap::new(),
-            worktree: None,
-        })
-        .await
-        .unwrap();
-    assert_eq!(session.last_focused_at, None);
-
-    let resp = reqwest::Client::new()
-        .post(url(h.addr, &format!("/api/sessions/{}/focus", session.id)))
-        .json(&serde_json::json!({ "focused": true }))
-        .send()
-        .await
-        .unwrap();
-    assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
-
-    let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
-        .await
-        .unwrap()
-        .json()
-        .await
-        .unwrap();
-    assert!(sessions[0].last_focused_at.is_some());
-}
-
 #[tokio::test]
 async fn delete_owned_session_kills_it() {
     let h = spawn("naps-laptop").await;

crates/maestro-daemon/tests/session_decisions.rs

@@ -555,3 +555,63 @@ async fn spawn_overrides_client_supplied_maestro_variables() {
         Some(&"http://127.0.0.1:7070".to_string())
     );
 }
+
+/// Two clients attached to one session used to resize the shared window past
+/// each other on every report they made. Every flip repaints a full-screen
+/// agent at a new height and orphans the rows it drew at the old one, which
+/// reads to the operator as a pane that has stopped taking input.
+#[tokio::test]
+async fn clients_of_different_sizes_do_not_resize_the_window_past_each_other() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+    let web = fx.manager.attach_viewport();
+    let tui = fx.manager.attach_viewport();
+
+    fx.manager.set_viewport(s.id, web, 53, 46).await.unwrap();
+    fx.manager.set_viewport(s.id, tui, 53, 20).await.unwrap();
+    // Both keep reporting, as a browser's ResizeObserver and the TUI's own
+    // redraw loop do. Neither report changes the arbitrated size.
+    for _ in 0..5 {
+        fx.manager.set_viewport(s.id, web, 53, 46).await.unwrap();
+        fx.manager.set_viewport(s.id, tui, 53, 20).await.unwrap();
+    }
+
+    let resizes: Vec<_> = fx
+        .fake
+        .calls()
+        .into_iter()
+        .filter_map(|c| match c {
+            Call::ResizeWindow { cols, rows, .. } => Some((cols, rows)),
+            _ => None,
+        })
+        .collect();
+    assert_eq!(
+        resizes,
+        vec![(53, 46), (53, 20)],
+        "the window was resized more than the arbitrated size actually changed"
+    );
+}
+
+/// The smaller client leaving hands the window back to the one still attached.
+#[tokio::test]
+async fn releasing_a_client_resizes_to_what_is_left() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+    let web = fx.manager.attach_viewport();
+    let tui = fx.manager.attach_viewport();
+    fx.manager.set_viewport(s.id, web, 80, 46).await.unwrap();
+    fx.manager.set_viewport(s.id, tui, 80, 20).await.unwrap();
+
+    fx.manager.release_viewport(s.id, tui).await;
+
+    let resizes: Vec<_> = fx
+        .fake
+        .calls()
+        .into_iter()
+        .filter_map(|c| match c {
+            Call::ResizeWindow { cols, rows, .. } => Some((cols, rows)),
+            _ => None,
+        })
+        .collect();
+    assert_eq!(resizes, vec![(80, 46), (80, 20), (80, 46)]);
+}

crates/maestro-daemon/tests/session_manager.rs

@@ -1091,109 +1091,3 @@ async fn spawned_sessions_export_maestro_session_id_and_url() {
 
     fx.manager.kill(s.id, false).await.expect("kill");
 }
-
-/// docs/COMMAND-BAR.md, empty-query ordering: a session that has never been
-/// focused carries no `last_focused_at` at all, which is what lets a client
-/// sort it after every session that has one (#145).
-#[tokio::test]
-async fn a_freshly_created_session_has_never_been_focused() {
-    let fx = DaemonFixture::new();
-    let cwd = TempDir::new().unwrap();
-
-    let s = fx
-        .manager
-        .create(CreateSessionRequest {
-            cwd: cwd.path().to_path_buf(),
-            command: "sleep 30".into(),
-            env: HashMap::new(),
-            metadata: HashMap::new(),
-            worktree: None,
-        })
-        .await
-        .expect("create");
-
-    assert_eq!(s.last_focused_at, None);
-    assert_eq!(fx.manager.snapshot().await[0].last_focused_at, None);
-}
-
-/// #145: `POST /.../focus` reporting `focused: true` stamps
-/// `last_focused_at` and announces it on the event stream; reporting
-/// `focused: false` (losing focus) leaves the stamp alone, since the bar
-/// orders by when the operator last arrived, not when they left.
-#[tokio::test]
-async fn set_focused_true_stamps_last_focused_at() {
-    let fx = DaemonFixture::new();
-    let cwd = TempDir::new().unwrap();
-
-    let s = fx
-        .manager
-        .create(CreateSessionRequest {
-            cwd: cwd.path().to_path_buf(),
-            command: "sleep 30".into(),
-            env: HashMap::new(),
-            metadata: HashMap::new(),
-            worktree: None,
-        })
-        .await
-        .expect("create");
-
-    let mut events = fx.manager.events();
-    let before = chrono::Utc::now();
-    fx.manager.set_focused(s.id, true).await.expect("focus");
-
-    let updated = fx.manager.snapshot().await[0].clone();
-    let stamp = updated.last_focused_at.expect("stamped on focus");
-    assert!(stamp >= before);
-
-    let mut saw_update = false;
-    while let Ok(event) = tokio::time::timeout(Duration::from_millis(200), events.recv()).await {
-        if let Ok(CatalogEvent::SessionUpdated { session }) = event {
-            if session.id == s.id && session.last_focused_at == Some(stamp) {
-                saw_update = true;
-                break;
-            }
-        }
-    }
-    assert!(saw_update, "expected a SessionUpdated carrying the stamp");
-
-    fx.manager.set_focused(s.id, false).await.expect("unfocus");
-    let after_unfocus = fx.manager.snapshot().await[0].clone();
-    assert_eq!(
-        after_unfocus.last_focused_at,
-        Some(stamp),
-        "losing focus must not clear the last-focused stamp"
-    );
-}
-
-/// #145: opening `/api/attach/:id` is focusing too — it must stamp the same
-/// field `set_focused` does, so a client that only ever attaches sorts
-/// identically to one that reports focus explicitly.
-#[tokio::test]
-async fn attaching_stamps_last_focused_at() {
-    let fx = DaemonFixture::new();
-    let cwd = TempDir::new().unwrap();
-
-    let s = fx
-        .manager
-        .create(CreateSessionRequest {
-            cwd: cwd.path().to_path_buf(),
-            command: "sleep 30".into(),
-            env: HashMap::new(),
-            metadata: HashMap::new(),
-            worktree: None,
-        })
-        .await
-        .expect("create");
-    assert_eq!(s.last_focused_at, None);
-
-    let before = chrono::Utc::now();
-    let (_replay, _rx) = fx
-        .manager
-        .subscribe_pty_with_replay(s.id)
-        .await
-        .expect("known session");
-
-    let updated = fx.manager.snapshot().await[0].clone();
-    let stamp = updated.last_focused_at.expect("attach stamps focus");
-    assert!(stamp >= before);
-}

crates/maestro-daemon/tests/sidecar.rs

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

crates/maestro-protocol/src/display.rs

@@ -248,7 +248,6 @@ mod tests {
             activity_since: Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 

crates/maestro-protocol/src/lib.rs

@@ -108,14 +108,6 @@ pub struct Session {
     /// from daemons that predate the field stay forward-compatible.
     #[serde(default)]
     pub blocked_work: Option<InTheWay>,
-    /// Wall-clock time this session last became the pane a client was
-    /// showing (#145) — stamped by both `POST /.../focus` and opening
-    /// `/api/attach/:id`, since either one is the operator moving there.
-    /// `None` until the session has been focused at least once, which is
-    /// also how the command bar's empty-query ordering (`docs/COMMAND-BAR.md`)
-    /// sorts a never-focused session after every session that has one.
-    #[serde(default)]
-    pub last_focused_at: Option<DateTime<Utc>>,
 }
 
 /// Default for [`Session::last_activity_at`] when an older payload omits it.
@@ -855,7 +847,6 @@ mod tests {
                 .with_timezone(&Utc),
             current_cwd: Some(PathBuf::from("/home/naps62/projects/maestro/crates")),
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 
@@ -905,28 +896,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn last_focused_at_defaults_to_none_on_legacy_payload() {
-        // Pre-#145 payload omits the field; `None` means never-focused.
-        let json = serde_json::json!({
-            "id": Uuid::from_u128(1),
-            "cwd": "/tmp",
-            "command": "bash",
-            "status": "Running",
-            "created_at": "2026-05-24T12:00:00Z"
-        });
-        let s: Session = serde_json::from_value(json).unwrap();
-        assert_eq!(s.last_focused_at, None);
-
-        let mut focused = sample_session();
-        focused.last_focused_at = Some(
-            DateTime::parse_from_rfc3339("2026-05-24T12:06:00Z")
-                .unwrap()
-                .with_timezone(&Utc),
-        );
-        assert_eq!(focused, round_trip(&focused));
-    }
-
     #[test]
     fn activity_since_defaults_to_epoch_on_legacy_payload() {
         // A daemon predating #102 omits `activity_since`; it must deserialize

crates/maestro-testing/src/lib.rs

@@ -46,7 +46,6 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
         activity_since: chrono::Utc::now(),
         current_cwd: None,
         blocked_work: None,
-        last_focused_at: None,
     }
 }
 

crates/maestro-tui/src/app.rs

@@ -1179,6 +1179,10 @@ impl App {
             sessions: snap.sessions.clone(),
             highlight: self.state.sidebar_highlight.clone(),
             attached,
+            // The active tab's session, not the displayed one: a preview is
+            // shown in the pane but never becomes what the operator picked,
+            // so it must not move this fill (`docs/PREVIEW.md`).
+            pane_session: self.state.active_session(),
         };
         let shown_sid = self.state.displayed_session();
         let previewing = self.state.preview.is_some();
@@ -1269,6 +1273,7 @@ fn visible_sidebar_order(
         sessions: snap.sessions.clone(),
         highlight: None,
         attached: HashSet::new(),
+        pane_session: None,
     }
     .rendered_items_with_collapsed(collapsed)
 }
@@ -1665,7 +1670,6 @@ mod tests {
                     activity_since: chrono::Utc::now(),
                     current_cwd: None,
                     blocked_work: None,
-                    last_focused_at: None,
                 })
                 .collect(),
         });
@@ -1846,7 +1850,6 @@ mod tests {
                 activity_since: chrono::Utc::now(),
                 current_cwd: None,
                 blocked_work: None,
-                last_focused_at: None,
             }],
         });
         app.dispatch(Action::SidebarNext);
@@ -1873,7 +1876,6 @@ mod tests {
             activity_since: Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 
@@ -2735,7 +2737,6 @@ mod tests {
 
                 current_cwd: None,
                 blocked_work: None,
-                last_focused_at: None,
             }],
         });
         app.dispatch(Action::KillHighlighted);
@@ -2770,7 +2771,6 @@ mod tests {
                 activity_since: Utc::now(),
                 current_cwd: None,
                 blocked_work: None,
-                last_focused_at: None,
             }],
         });
     }

crates/maestro-tui/src/catalog.rs

@@ -222,7 +222,6 @@ mod tests {
             activity_since: chrono::Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 

crates/maestro-tui/src/palette.rs

@@ -813,6 +813,21 @@ impl Palette {
         }
     }
 
+    /// Background for the card whose session the pane is showing
+    /// (`docs/SIDEBAR.md`). It sits partway from the card surface to the
+    /// selection surface, so the sidebar reads as one ladder: unfilled, half
+    /// filled for the session in the pane, fully filled under the cursor.
+    ///
+    /// Blended rather than added as a third `Surface` — a new surface means
+    /// eight more colours hand-picked seventeen times — which is also why it
+    /// borrows the *selection* surface's foregrounds: those are the ones
+    /// already picked for a filled row. A preset whose colours the terminal
+    /// owns (`ansi`) has nothing to blend, so it keeps the card background and
+    /// says "in the pane" with the filled glyph alone.
+    pub fn pane_row_bg(&self) -> Color {
+        mix(self.card.bg, self.selection.bg, 0.55)
+    }
+
     /// Border style for a panel, by whether it holds focus.
     pub fn border_style(&self, focused: bool) -> Style {
         if focused {
@@ -873,6 +888,16 @@ pub fn active() -> Palette {
     *active_slot().read().expect("active palette lock poisoned")
 }
 
+/// Blend `amount` of `to` into `from`, in plain sRGB. Both must be RGB, or
+/// there is nothing to blend and `from` comes back unchanged.
+fn mix(from: Color, to: Color, amount: f64) -> Color {
+    let (Color::Rgb(fr, fg, fb), Color::Rgb(tr, tg, tb)) = (from, to) else {
+        return from;
+    };
+    let lerp = |a: u8, b: u8| (a as f64 + (b as f64 - a as f64) * amount).round() as u8;
+    Color::Rgb(lerp(fr, tr), lerp(fg, tg), lerp(fb, tb))
+}
+
 /// 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.
@@ -937,6 +962,43 @@ mod tests {
         }
     }
 
+    /// The pane row is the middle rung: a visible fill against the card, still
+    /// a different surface from the cursor's, and carrying the selection
+    /// surface's foregrounds, which it borrows rather than shipping its own.
+    #[test]
+    fn the_pane_row_is_a_rung_between_the_card_and_the_selection() {
+        for (preset, p) in rgb_presets() {
+            let bg = p.pane_row_bg();
+            let from_card = contrast_ratio(p.card.bg, bg)
+                .unwrap_or_else(|| panic!("{preset}.pane_row_bg must be RGB"));
+            assert!(
+                from_card >= 1.15,
+                "{preset}: pane row {from_card:.2} from the card background is not a visible fill"
+            );
+            let from_selection =
+                contrast_ratio(p.selection.bg, bg).expect("selection.bg must be RGB");
+            assert!(
+                from_selection >= 1.15,
+                "{preset}: pane row {from_selection:.2} from the cursor's fill —                  the highlight would vanish on the session already in the pane"
+            );
+            for (role, color) in p.selection.roles() {
+                let ratio = contrast_ratio(bg, color).expect("selection role must be RGB");
+                let floor = if role == "dim" { 3.0 } else { 4.5 };
+                assert!(
+                    ratio >= floor,
+                    "{preset}.selection.{role} on the pane row is {ratio:.2}, below {floor}"
+                );
+            }
+        }
+    }
+
+    /// A preset the terminal themes has nothing to blend from.
+    #[test]
+    fn ansi_keeps_the_card_background_for_the_pane_row() {
+        let p = Palette::ANSI;
+        assert_eq!(p.pane_row_bg(), p.card.bg);
+    }
+
     #[test]
     fn every_preset_supplies_every_role() {
         for (name, p) in Palette::presets() {

crates/maestro-tui/src/render.rs

@@ -415,6 +415,7 @@ mod tests {
             sessions: Vec::new(),
             highlight: None,
             attached: HashSet::new(),
+            pane_session: None,
         };
         let help = HelpOverlay { lines: Vec::new() };
         let state = AppState::new();
@@ -511,6 +512,7 @@ mod tests {
             sessions: Vec::new(),
             highlight: None,
             attached: HashSet::new(),
+            pane_session: None,
         };
         let help = HelpOverlay { lines: Vec::new() };
         let inputs = RenderInputs {
@@ -561,6 +563,7 @@ mod tests {
             sessions: Vec::new(),
             highlight: None,
             attached: HashSet::new(),
+            pane_session: None,
         };
         let help = HelpOverlay { lines: Vec::new() };
         let draw_map = |focus| {
@@ -601,6 +604,7 @@ mod tests {
             sessions: Vec::new(),
             highlight: None,
             attached: HashSet::new(),
+            pane_session: None,
         };
         let help = HelpOverlay { lines: Vec::new() };
         let render = |focus| {

crates/maestro-tui/src/sidebar.rs

@@ -37,14 +37,39 @@ const META_INDENT: &str = "    ";
 /// both card rows, replacing the old inline dot glyph on the meta line.
 const RAIL: &str = "▌";
 
-/// Cards use the selection surface only while the sidebar owns focus. An
+/// Which fill a session card wears (docs/SIDEBAR.md). The cursor's fill wins
+/// on its own row: a highlight that lands on the session already in the pane
+/// still has to be visible.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum CardFill {
+    /// An ordinary card, on the card surface.
+    None,
+    /// The session the pane is showing.
+    Pane,
+    /// Under the cursor, with the sidebar holding the keyboard.
+    Cursor,
+}
+
+impl CardFill {
+    /// Both filled tiers carry the selection surface's foregrounds — those are
+    /// the colours picked for a filled row, and a colour chosen for the card
+    /// background is not legible on one.
+    fn filled(self) -> bool {
+        self != CardFill::None
+    }
+}
+
+/// Cards take the cursor's fill 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 {
+fn card_base(fill: CardFill, focused: bool) -> Style {
     let palette = palette::active();
-    let mut style = palette.surface(highlighted && focused).text_style();
-    if focused && !highlighted {
-        style = style.bg(palette.sidebar_focus_bg);
+    let mut style = palette.surface(fill.filled()).text_style();
+    match fill {
+        CardFill::Cursor => {}
+        CardFill::Pane => style = style.bg(palette.pane_row_bg()),
+        CardFill::None if focused => style = style.bg(palette.sidebar_focus_bg),
+        CardFill::None => {}
     }
     style
 }
@@ -55,6 +80,9 @@ pub struct Sidebar {
     pub sessions: Vec<Session>,
     pub highlight: Option<SidebarItem>,
     pub attached: HashSet<Uuid>,
+    /// The session the active tab's pane is showing. It wears a fill of its
+    /// own, so "in the pane" is not carried by the ● glyph alone.
+    pub pane_session: Option<Uuid>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -113,8 +141,7 @@ impl Sidebar {
             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);
+                    let base = card_base(self.card_fill(s, focused), 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)));
@@ -226,6 +253,18 @@ impl Sidebar {
         pad_to_width(spans, width, base)
     }
 
+    /// Which fill this session's card wears. The cursor wins on its own row,
+    /// so a highlight parked on the session already in the pane stays visible.
+    fn card_fill(&self, s: &Session, focused: bool) -> CardFill {
+        if focused && self.highlight == Some(SidebarItem::Session(s.id)) {
+            CardFill::Cursor
+        } else if self.pane_session == Some(s.id) {
+            CardFill::Pane
+        } else {
+            CardFill::None
+        }
+    }
+
     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, _) => "✗",
@@ -233,12 +272,13 @@ impl Sidebar {
             (SessionStatus::Running, false) => "○",
         };
         let highlighted = self.highlight == Some(SidebarItem::Session(s.id));
-        let base = card_base(highlighted, focused);
+        let fill = self.card_fill(s, focused);
+        let base = card_base(fill, focused);
         let prefix = 1 + INDENT.chars().count() + 2;
         let name_budget = width.saturating_sub(prefix);
 
         let edge = highlighted && !focused;
-        let rail_style = base.fg(activity_color(s.activity, highlighted, focused));
+        let rail_style = base.fg(activity_color(s.activity, fill));
         let mut spans: Vec<Span<'static>> = vec![
             Span::styled(RAIL, rail_style),
             Span::styled(
@@ -257,7 +297,7 @@ impl Sidebar {
         let name_style = if maestro_protocol::display::is_provisional_name(s) {
             base.patch(
                 palette::active()
-                    .surface(highlighted && focused)
+                    .surface(fill.filled())
                     .muted_style()
                     .bg(base.bg.unwrap_or(palette::active().chrome_bg)),
             )
@@ -283,11 +323,11 @@ impl Sidebar {
         let blocked = s.blocked_work.filter(|b| !b.is_clear());
         let dead = s.status == SessionStatus::Dead;
         let highlighted = self.highlight == Some(SidebarItem::Session(s.id));
-        let base = card_base(highlighted, focused);
-        let rail_style =
-            base.patch(Style::default().fg(activity_color(s.activity, highlighted, focused)));
+        let fill = self.card_fill(s, focused);
+        let base = card_base(fill, focused);
+        let rail_style = base.patch(Style::default().fg(activity_color(s.activity, fill)));
         let muted = palette::active()
-            .surface(highlighted && focused)
+            .surface(fill.filled())
             .muted_style()
             .bg(base.bg.unwrap_or(palette::active().chrome_bg));
         let edge = highlighted && !focused;
@@ -308,7 +348,7 @@ impl Sidebar {
         let mut tail: Vec<Span<'static>> = Vec::new();
         if let Some(b) = blocked {
             let palette = palette::active();
-            let surface = palette.surface(highlighted && focused);
+            let surface = palette.surface(fill.filled());
             for (kind, text) in b.stats() {
                 let style = match kind {
                     StatKind::Added => muted.fg(surface.active),
@@ -352,10 +392,8 @@ impl Sidebar {
 /// 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)
+fn activity_color(state: ActivityState, fill: CardFill) -> Color {
+    palette::active().surface(fill.filled()).activity(state)
 }
 
 /// docs/SIDEBAR.md duration format — floored whole seconds / minutes / hours,
@@ -461,7 +499,6 @@ mod tests {
             activity_since: Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         }
     }
 
@@ -521,6 +558,7 @@ mod tests {
             sessions: vec![session_named(1, "claude"), session_named(2, "bash")],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let rendered = render_to_string(&draw(&sb, 28, 12));
         assert!(
@@ -545,6 +583,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         })
         .groups(&HashSet::new());
         assert_eq!(groups[0].key, PathBuf::from("/home/u/repos/maestro"));
@@ -556,6 +595,7 @@ mod tests {
             sessions: Vec::new(),
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         assert!(sidebar.groups(&HashSet::new()).is_empty());
         assert!(sidebar.rendered_items().is_empty());
@@ -567,6 +607,7 @@ mod tests {
             sessions: vec![session_named(1, "claude"), session_named(2, "bash")],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let key = PathBuf::from("/tmp");
         let mut collapsed = HashSet::new();
@@ -591,6 +632,7 @@ mod tests {
             sessions: vec![session],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let key = PathBuf::from("/very/long/project/path/extraordinarily-long-project-name");
         let collapsed = HashSet::from([key]);
@@ -621,6 +663,7 @@ mod tests {
             sessions: vec![session_named(1, "claude")],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sidebar, 40, 8));
         assert!(all[1].contains("/tmp"));
@@ -636,6 +679,7 @@ mod tests {
             sessions: vec![session_named(1, "claude")],
             highlight: None,
             attached: [sid].into_iter().collect(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 6));
         let line = row_containing(&all, "claude");
@@ -646,6 +690,87 @@ mod tests {
         );
     }
 
+    /// Whether any cell in the buffer is painted on `bg`.
+    fn any_cell_on(buf: &Buffer, bg: Color) -> bool {
+        (0..buf.area.height)
+            .any(|y| (0..buf.area.width).any(|x| buf[(x, y)].style().bg == Some(bg)))
+    }
+
+    /// docs/SIDEBAR.md: the session the pane is showing wears a fill, so it is
+    /// not the ● glyph alone carrying "this is the one on screen".
+    #[test]
+    fn the_session_in_the_pane_wears_the_pane_fill() {
+        let sid = Uuid::from_u128(1);
+        let p = palette::active();
+        let sb = Sidebar {
+            sessions: vec![session_named(1, "claude")],
+            highlight: None,
+            attached: [sid].into_iter().collect(),
+            pane_session: Some(sid),
+        };
+        assert!(any_cell_on(&draw(&sb, 28, 6), p.pane_row_bg()));
+
+        let none = Sidebar {
+            pane_session: None,
+            ..sb
+        };
+        assert!(!any_cell_on(&draw(&none, 28, 6), p.pane_row_bg()));
+    }
+
+    /// The cursor's fill wins on its own row: a highlight that lands on the
+    /// session already in the pane has to stay visible.
+    #[test]
+    fn the_cursor_outranks_the_pane_fill_on_its_own_row() {
+        let sid = Uuid::from_u128(1);
+        let p = palette::active();
+        let sb = Sidebar {
+            sessions: vec![session_named(1, "claude")],
+            highlight: Some(SidebarItem::Session(sid)),
+            attached: [sid].into_iter().collect(),
+            pane_session: Some(sid),
+        };
+        let buf = draw_with_focus(&sb, 28, 6, true);
+        assert!(any_cell_on(&buf, p.selection.bg), "cursor fill is missing");
+        assert!(
+            !any_cell_on(&buf, p.pane_row_bg()),
+            "the pane fill is showing through the cursor's own row"
+        );
+    }
+
+    /// A card the pane is showing is a filled row, so it takes the selection
+    /// surface's foregrounds — a colour picked for the card background is not
+    /// legible on a fill.
+    #[test]
+    fn the_pane_row_carries_selection_foregrounds() {
+        let sid = Uuid::from_u128(1);
+        let p = palette::active();
+        let mut sess = session_named(1, "claude");
+        sess.activity = ActivityState::AwaitingInput;
+        let sb = Sidebar {
+            sessions: vec![sess],
+            highlight: None,
+            attached: [sid].into_iter().collect(),
+            pane_session: Some(sid),
+        };
+        let buf = draw(&sb, 28, 6);
+        let on_pane_row = |fg: Color| {
+            (0..buf.area.height).any(|y| {
+                (0..buf.area.width).any(|x| {
+                    let st = buf[(x, y)].style();
+                    st.bg == Some(p.pane_row_bg()) && st.fg == Some(fg)
+                })
+            })
+        };
+        assert!(
+            on_pane_row(p.selection.activity(ActivityState::AwaitingInput)),
+            "the rail must carry the state in the filled surface's colours"
+        );
+        assert!(
+            !on_pane_row(p.card.activity(ActivityState::AwaitingInput)),
+            "a card surface colour is painted onto the pane fill"
+        );
+    }
+
     #[test]
     fn dead_session_uses_cross_glyph() {
         let mut sess = session_named(1, "claude");
@@ -654,6 +779,7 @@ mod tests {
             sessions: vec![sess],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 28, 6);
         let all = rows(&buf);
@@ -682,6 +808,7 @@ mod tests {
             sessions: vec![blocked, clear, unprobed],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 44, 10));
 
@@ -728,6 +855,7 @@ mod tests {
             sessions: vec![generated, settled],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 44, 8);
         let palette = palette::active();
@@ -760,6 +888,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 44, 8);
         let palette = palette::active();
@@ -786,6 +915,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         assert_eq!(content(&all[0]), "sessions");
@@ -817,6 +947,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -856,6 +987,7 @@ mod tests {
                 sessions: vec![s],
                 highlight: None,
                 attached: Default::default(),
+                pane_session: None,
             };
             let buf = draw(&sb, 28, 8);
             let found = (0..buf.area.height)
@@ -884,6 +1016,7 @@ mod tests {
                 sessions: vec![s],
                 highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
                 attached: Default::default(),
+                pane_session: None,
             };
             let buf = draw(&sb, 28, 8);
             let on_selection = |fg: Color| {
@@ -923,6 +1056,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -942,6 +1076,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 60, 6));
         let meta = content(&all[3]);
@@ -970,6 +1105,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -999,6 +1135,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 40, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -1026,6 +1163,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 40, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -1054,6 +1192,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 42, 8));
         let idx = all.iter().position(|l| l.contains("claude")).unwrap();
@@ -1087,6 +1226,7 @@ mod tests {
             sessions: vec![legacy],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let rendered = render_to_string(&draw(&sb, 40, 8));
         assert!(
@@ -1124,12 +1264,12 @@ mod tests {
             activity_since: Utc::now(),
             current_cwd: None,
             blocked_work: None,
-            last_focused_at: None,
         };
         let sb = Sidebar {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let rendered = render_to_string(&draw(&sb, 28, 6));
         assert!(
@@ -1145,6 +1285,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 40, 6));
         assert!(
@@ -1166,6 +1307,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 9, 6));
         assert!(
@@ -1192,6 +1334,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 29, 6));
         assert!(all[3].contains("~1"), "{:?}", all[3]);
@@ -1216,6 +1359,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 40, 6));
         assert!(all[3].contains("~1"), "{:?}", all[3]);
@@ -1237,6 +1381,7 @@ mod tests {
             sessions: vec![highlighted],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 28, 8);
         for y in 0..buf.area.height {
@@ -1262,6 +1407,7 @@ mod tests {
             sessions: vec![one, two],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 28, 8);
         let all = rows(&buf);
@@ -1297,6 +1443,7 @@ mod tests {
             sessions: vec![session_named(1, "claude")],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw_with_focus(&sb, 28, 8, false);
         let y = (0..buf.area.height)
@@ -1316,6 +1463,7 @@ mod tests {
                 sessions: vec![session_named(1, "claude")],
                 highlight: None,
                 attached: Default::default(),
+                pane_session: None,
             },
             28,
             8,
@@ -1336,6 +1484,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let buf = draw(&sb, 28, 8);
         let y = buf.content.iter().position(|c| c.symbol() == "c").unwrap() as u16 / buf.area.width;
@@ -1354,6 +1503,7 @@ mod tests {
             sessions: vec![session_named(1, "claude")],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let line = content(row_containing(&all, "claude"));
@@ -1371,6 +1521,7 @@ mod tests {
             sessions: vec![one, two],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let line = row_containing(&all, "bash");
@@ -1390,6 +1541,7 @@ mod tests {
             sessions: vec![s],
             highlight: Some(SidebarItem::Session(Uuid::from_u128(1))),
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 28, 8));
         let line = row_containing(&all, "an-unreasonably");

docs/PREVIEW.md

@@ -32,6 +32,33 @@ The throwaway tab never counts as an open session: the tab bar does not appear
 because of it, the mobile shell does not switch away from the session list for
 it, and the sidebar does not mark the session as open.
 
+## How a preview reads
+
+A preview is provisional, so it never wears the accent — the accent is what
+says "this is the one you picked". It has a hue of its own, and every surface
+involved in the preview carries that same hue, so the pane and the row it came
+from read as one thing rather than two unrelated highlights.
+
+Web client (`--preview` and friends in `web/src/styles.css`):
+
+| Surface | While previewing |
+|---|---|
+| The previewed pane's titlebar | Tinted in the preview hue, at full strength, in place of the focused pane's accent tint. |
+| The canvas | A `preview` chip, top right, and a dashed inset ring. |
+| A throwaway tab | Dashed border, italic label. |
+| The sidebar row being previewed | Filled with the preview hue, over whatever open state the row already had — but the row of the session already showing in the pane keeps its accent fill, since previewing it changes nothing on screen. |
+| A hovered sidebar row, and the keyboard cursor on a session | A lighter wash of the same hue, because both are what previews a row. |
+
+Rows say it with fill, not with an edge — see the tier ladder in
+`docs/SIDEBAR.md`, which previewing sits at the bottom of. The dashed edges
+belong to the pane: the canvas ring and the throwaway tab.
+
+The hue is a palette token, not a fixed colour: a palette whose accent already
+sits on it moves it (`--preview-h`), so "previewing" and "picked" never collide.
+
+The TUI marks a preview in text only — the title bar reads `<name>  ·  preview`
+— and has no preview colour role yet.
+
 ## What ends a preview
 
 - The highlight moves to another session — that session is previewed instead.

docs/SIDEBAR.md

@@ -177,6 +177,38 @@ 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.
 
+## Which row is filled
+
+Both clients say every one of these with a **background fill**, never an edge.
+A row is usually several of them at once, so they form a ladder: the tier
+furthest down wins the paint.
+
+| Tier | Web | TUI |
+|---|---|---|
+| Alive | 6% accent wash | — (the rail carries it) |
+| Under the pointer or the keyboard walk | preview hue, light | selection surface, while the sidebar holds the keyboard |
+| Open in some pane, not the focused one | 6% accent wash (`.is-open`) | — (the `●` glyph carries it) |
+| Showing in the pane | `--accent-fill` | `pane_row_bg()` — partway from the card surface to the selection surface |
+| Previewing (`docs/PREVIEW.md`), unless that row is the one showing in the pane | `--preview-tint` | — (no preview colour role yet) |
+
+The web ladder is written as one ordered run of equal-specificity rules in
+`styles.css`, every qualifier inside `:where()`, so the order they appear in
+*is* the precedence. Add a tier where it belongs in that run, never by piling
+on another class to out-weigh the rule above it.
+
+The TUI's two filled tiers both carry the **selection** surface's foregrounds,
+since those are the colours picked for a filled row. `pane_row_bg()` is
+blended from the two surfaces rather than shipped as a third one — a third
+surface would mean eight more colours hand-picked seventeen times — and the
+palette tests assert it stays a visible step from both. The cursor's fill wins
+on its own row, so a highlight parked on the session already in the pane is
+still visible.
+
+The one edge left in either list is the TUI's `▏` marker, which stands in for
+the cursor's fill while the pane holds the keyboard, and the web's ring on a
+highlighted **folder** row — a folder previews nothing, so it has no fill to
+step up to.
+
 The duration text inherits its state's colour; the exited and command
 fragments use the surface's `muted` role, as do the diff stat's `~`, `?` and
 `↑` fragments. Only `+` and `-` step outside the surface's muted role, and they

web/src/attach.ts

@@ -5,7 +5,6 @@ import "@xterm/xterm/css/xterm.css";
 
 import { attachWsUrl } from "./routes.js";
 import { FOCUS_SIDEBAR_EVENT } from "./catalog.js";
-import { CommandSet, defineCommands } from "./commands.js";
 import { escapeHtml } from "./html.js";
 import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "./reconnect.js";
 import { applyModsToChar, cursorSeq, tildeSeq } from "./keys.js";
@@ -14,15 +13,6 @@ import { splitCommand, toolIconSvg } from "./toolIcon.js";
 import type { ClientControl, Uuid } from "./types.js";
 import { WebglPolicy } from "./webglRenderer.js";
 
-// The pane's half of the command registry (#148): plain Escape hands the
-// keyboard back to the session list, the pair to the list's Tab.
-const paneKeys = new CommandSet(
-  defineCommands({
-    "pane.focusList": () => document.dispatchEvent(new CustomEvent(FOCUS_SIDEBAR_EVENT)),
-  }),
-  { preventDefault: false },
-);
-
 /** One budget for the whole page — see webglRenderer.ts for why contexts are
  *  rationed rather than handed to every connection. */
 const webglPolicy = new WebglPolicy();
@@ -66,6 +56,8 @@ export interface AttachOptions {
   shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
 }
 
+
+
 /** What the header shows about the session (name / command). Optional — falls
  * back to a short session id when the session isn't known yet. */
 export interface AttachInfo {
@@ -218,12 +210,12 @@ export function createAttachConnection(
   }
 
   // Plain Escape hands the keyboard back to the session list instead of the
-  // shell/app. `false` tells xterm to skip its own handling of this event —
-  // which is also why the set doesn't `preventDefault`: swallowing here is
-  // xterm's return value, not the browser's.
+  // shell/app. `false` tells xterm to skip its own handling of this event.
   term.attachCustomKeyEventHandler((e) => {
-    if (e.type !== "keydown") return true;
-    return !paneKeys.handle(e);
+    if (e.type !== "keydown" || e.key !== "Escape") return true;
+    if (e.ctrlKey || e.altKey || e.metaKey || e.shiftKey) return true;
+    document.dispatchEvent(new CustomEvent(FOCUS_SIDEBAR_EVENT));
+    return false;
   });
 
   // Touch scrolling: xterm's built-in touch handling is jittery (drags crawl a

web/src/catalog.ts

@@ -2,8 +2,7 @@ import { escapeHtml } from "./html.js";
 import { ApiRequestError, getDaemonInfo, killSession, renameSession } from "./api.js";
 import { openForceKillDialog } from "./killDialog.js";
 import { openContextMenu } from "./contextMenu.js";
-import { toggleHelp } from "./help.js";
-import { CommandSet, defineCommands } from "./commands.js";
+import { isTypingTarget, toggleHelp } from "./help.js";
 import { CatalogStore } from "./events.js";
 import type { InTheWay, Session } from "./types.js";
 import {
@@ -388,6 +387,9 @@ export interface SidebarHandle {
   setActive(id: string | null): void;
   /** Apply the full open/focused highlight state. */
   setHighlights(h: SidebarHighlights): void;
+  /** Mark the row the content pane is previewing (docs/PREVIEW.md), or clear it
+   *  with `null`. A preview is a view, not state, so this only paints. */
+  setPreview(sessionId: string | null): void;
   /** Hand the keyboard to the session list, highlighting a row to walk from. */
   focusList(): void;
   /** Whether the session list currently holds DOM focus. */
@@ -547,6 +549,10 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
   });
 
   let highlights: SidebarHighlights = { open: new Set(), focused: null };
+  // The previewed row is painted alongside the open/focused tiers so a
+  // re-render can't drop it, but it is never part of `highlights`: a preview
+  // is a view, and nothing about it is durable (docs/PREVIEW.md).
+  let previewing: string | null = null;
   const applyHighlights = () => {
     for (const n of treeHost.querySelectorAll<HTMLElement>(".tree-leaf")) {
       const id = n.dataset.sessionId;
@@ -555,6 +561,7 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
       const open = highlights.open.has(id);
       n.classList.toggle("is-active", focused);
       n.classList.toggle("is-open", open && !focused);
+      n.classList.toggle("is-previewing", previewing === id);
     }
   };
 
@@ -662,30 +669,24 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     applyNav();
   };
 
-  // The session list's half of the command registry (#148). One set per
-  // sidebar, so a second sidebar (tests, hot reload) drives its own rows; the
-  // labels and chords still come from the one registry.
-  const listKeys = new CommandSet(
-    defineCommands({
-      "list.next": () => moveNav(1),
-      "list.prev": () => moveNav(-1),
-      "list.activate": () => activateNav(),
-      "list.toggleFolder": () => toggleHighlightedFolder(),
-      "list.rename": () => {
-        const hit = highlightedSession();
-        if (hit) beginRename(hit.row, hit.session);
-      },
-      "list.kill": () => {
-        const hit = highlightedSession();
-        if (hit) void requestKill(hit.session, sessionName(hit.session));
-      },
-      "list.focusPane": () => document.dispatchEvent(new CustomEvent(FOCUS_PANE_EVENT)),
-    }),
-  );
-
-  // The inline rename field lives inside a row and owns its own keys; the set's
-  // plain-key rule keeps this walk out of it.
-  treeHost.addEventListener("keydown", (e) => listKeys.handle(e));
+  treeHost.addEventListener("keydown", (e) => {
+    if (e.ctrlKey || e.altKey || e.metaKey) return;
+    // The inline rename field lives inside a row and owns its own keys.
+    if (isTypingTarget(e.target)) return;
+    if (e.key === "j" || e.key === "ArrowDown") moveNav(1);
+    else if (e.key === "k" || e.key === "ArrowUp") moveNav(-1);
+    else if (e.key === "Enter") activateNav();
+    else if (e.key === "Tab") document.dispatchEvent(new CustomEvent(FOCUS_PANE_EVENT));
+    else if (e.key === "c") toggleHighlightedFolder();
+    else if (e.key === "x") {
+      const hit = highlightedSession();
+      if (hit) void requestKill(hit.session, sessionName(hit.session));
+    } else if (e.key === "r") {
+      const hit = highlightedSession();
+      if (hit) beginRename(hit.row, hit.session);
+    } else return;
+    e.preventDefault();
+  });
 
   /** Signature of what is currently on screen — see `treeSignature`. */
   let renderedSignature: string | null = null;
@@ -762,6 +763,10 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
       highlights = h;
       applyHighlights();
     },
+    setPreview(sessionId: string | null) {
+      previewing = sessionId;
+      applyHighlights();
+    },
     focusList() {
       // Start from the session on screen — that is where the user's attention
       // already is — falling back to the standing highlight, then the top row.

web/src/commands.test.ts

@@ -1,236 +0,0 @@
-// @vitest-environment happy-dom
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  COMMAND_SPECS,
-  CommandSet,
-  DEFAULT_LEADER,
-  canonicalizeKey,
-  defineCommands,
-  isTypingTarget,
-  keyCaps,
-  publishedCommands,
-} from "./commands.js";
-
-function key(k: string, init: KeyboardEventInit = {}): KeyboardEvent {
-  return new KeyboardEvent("keydown", { key: k, cancelable: true, ...init });
-}
-
-function el(html: string): HTMLElement {
-  const d = document.createElement("div");
-  d.innerHTML = html;
-  return d.firstElementChild as HTMLElement;
-}
-
-/** Dispatch on a target, so `isTypingTarget` sees something other than null. */
-function pressOn(set: CommandSet, target: HTMLElement, k: string, init?: KeyboardEventInit): boolean {
-  const e = key(k, init);
-  Object.defineProperty(e, "target", { value: target });
-  return set.handle(e);
-}
-
-describe("command specs", () => {
-  it("has a unique id and at least one chord per command", () => {
-    const ids = COMMAND_SPECS.map((s) => s.id);
-    expect(new Set(ids).size).toBe(ids.length);
-    for (const spec of COMMAND_SPECS) {
-      expect(spec.keys.length).toBeGreaterThan(0);
-      expect(spec.label.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("binds each chord once within a scope", () => {
-    const seen = new Set<string>();
-    for (const spec of COMMAND_SPECS) {
-      for (const k of spec.keys) {
-        const slot = `${spec.scope}:${k}`;
-        expect(seen.has(slot)).toBe(false);
-        seen.add(slot);
-      }
-    }
-  });
-
-  it("rejects a handler for an id that isn't in the registry", () => {
-    expect(() => defineCommands({ "nope.missing": () => {} })).toThrow(/unknown command id/);
-  });
-
-  it("carries every spec field onto the defined command", () => {
-    const [cmd] = defineCommands({ "spawn.open": () => {} });
-    expect(cmd).toMatchObject({ id: "spawn.open", keys: ["n"], scope: "global" });
-  });
-});
-
-describe("canonicalizeKey", () => {
-  it("spells keys the way the TUI's InputKey::canonical does", () => {
-    expect(canonicalizeKey(key("n"))).toBe("n");
-    expect(canonicalizeKey(key("N", { shiftKey: true }))).toBe("N");
-    expect(canonicalizeKey(key("?", { shiftKey: true }))).toBe("?");
-    expect(canonicalizeKey(key("a", { ctrlKey: true }))).toBe("ctrl-a");
-    expect(canonicalizeKey(key("Escape"))).toBe("esc");
-    expect(canonicalizeKey(key("Enter"))).toBe("enter");
-    expect(canonicalizeKey(key("Tab"))).toBe("tab");
-    expect(canonicalizeKey(key("Tab", { shiftKey: true }))).toBe("backtab");
-    expect(canonicalizeKey(key("ArrowDown"))).toBe("down");
-  });
-
-  it("folds a modified letter to lower case with an explicit shift-", () => {
-    expect(canonicalizeKey(key("H", { ctrlKey: true, shiftKey: true }))).toBe("ctrl-shift-h");
-    expect(canonicalizeKey(key("h", { ctrlKey: true, shiftKey: true }))).toBe("ctrl-shift-h");
-  });
-
-  it("has no canonical form for a modifier pressed alone", () => {
-    expect(canonicalizeKey(key("Control", { ctrlKey: true }))).toBeNull();
-    expect(canonicalizeKey(key("Shift", { shiftKey: true }))).toBeNull();
-  });
-});
-
-describe("keyCaps", () => {
-  it("renders one cap per modifier and key", () => {
-    expect(keyCaps("ctrl-shift-h")).toEqual(["Ctrl", "Shift", "H"]);
-    expect(keyCaps("enter")).toEqual(["Enter"]);
-    expect(keyCaps("j")).toEqual(["j"]);
-    expect(keyCaps("N")).toEqual(["N"]);
-    expect(keyCaps("?")).toEqual(["?"]);
-    expect(keyCaps("ctrl-a ctrl-k")).toEqual(["Ctrl", "A", "then", "Ctrl", "K"]);
-  });
-});
-
-describe("CommandSet", () => {
-  it("runs the command bound to a chord, and swallows the browser default", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "spawn.open": run }));
-    const e = key("n");
-    expect(set.handle(e)).toBe(true);
-    expect(run).toHaveBeenCalledTimes(1);
-    expect(e.defaultPrevented).toBe(true);
-  });
-
-  it("leaves an unbound key alone", () => {
-    const set = new CommandSet(defineCommands({ "spawn.open": vi.fn() }));
-    const e = key("q");
-    expect(set.handle(e)).toBe(false);
-    expect(e.defaultPrevented).toBe(false);
-  });
-
-  it("treats a modified key as a different binding", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "spawn.open": run }));
-    expect(set.handle(key("n", { ctrlKey: true }))).toBe(false);
-    expect(set.handle(key("n", { metaKey: true }))).toBe(false);
-    expect(run).not.toHaveBeenCalled();
-  });
-
-  it("runs every alias of a command", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "list.next": run }));
-    set.handle(key("j"));
-    set.handle(key("ArrowDown"));
-    expect(run).toHaveBeenCalledTimes(2);
-  });
-
-  it("keeps plain keys deaf inside a form field, and chorded ones live", () => {
-    const plain = vi.fn();
-    const chorded = vi.fn();
-    const set = new CommandSet(
-      defineCommands({ "spawn.open": plain, "focus.toggle": chorded }),
-    );
-    const input = el("<input>");
-    expect(pressOn(set, input, "n")).toBe(false);
-    expect(plain).not.toHaveBeenCalled();
-    expect(pressOn(set, input, "H", { ctrlKey: true, shiftKey: true })).toBe(true);
-    expect(chorded).toHaveBeenCalledTimes(1);
-  });
-
-  it("keeps pane commands live inside the terminal's textarea", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "pane.focusList": run }), {
-      preventDefault: false,
-    });
-    const textarea = el('<textarea class="xterm-helper-textarea"></textarea>');
-    const e = key("Escape");
-    Object.defineProperty(e, "target", { value: textarea });
-    expect(set.handle(e)).toBe(true);
-    expect(run).toHaveBeenCalledTimes(1);
-    // xterm is told to swallow by the return value, not by the browser default.
-    expect(e.defaultPrevented).toBe(false);
-  });
-});
-
-describe("the leader", () => {
-  it("defaults to the TUI's ctrl-a", () => {
-    expect(DEFAULT_LEADER).toBe("ctrl-a");
-  });
-
-  it("holds the leader as a partial chord instead of selecting the page", () => {
-    const set = new CommandSet(defineCommands({ "spawn.open": vi.fn() }), {
-      leader: DEFAULT_LEADER,
-    });
-    const e = key("a", { ctrlKey: true });
-    expect(set.handle(e)).toBe(true);
-    expect(e.defaultPrevented).toBe(true);
-  });
-
-  it("swallows the key after the leader rather than running its plain binding", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "spawn.open": run }), {
-      leader: DEFAULT_LEADER,
-    });
-    set.handle(key("a", { ctrlKey: true }));
-    expect(set.handle(key("n"))).toBe(true);
-    expect(run).not.toHaveBeenCalled();
-    // The next key is an ordinary one again.
-    set.handle(key("n"));
-    expect(run).toHaveBeenCalledTimes(1);
-  });
-
-  it("forgets a held leader once the chord timeout passes", () => {
-    const run = vi.fn();
-    let now = 0;
-    const set = new CommandSet(defineCommands({ "spawn.open": run }), {
-      leader: DEFAULT_LEADER,
-      chordTimeoutMs: 1000,
-      now: () => now,
-    });
-    set.handle(key("a", { ctrlKey: true }));
-    now = 1500;
-    set.handle(key("n"));
-    expect(run).toHaveBeenCalledTimes(1);
-  });
-
-  it("leaves select-all alone in a real form field", () => {
-    const set = new CommandSet(defineCommands({ "spawn.open": vi.fn() }), {
-      leader: DEFAULT_LEADER,
-    });
-    const input = el("<input>");
-    const e = key("a", { ctrlKey: true });
-    Object.defineProperty(e, "target", { value: input });
-    expect(set.handle(e)).toBe(false);
-    expect(e.defaultPrevented).toBe(false);
-  });
-});
-
-describe("publishing", () => {
-  it("lists a constructed set's commands, replacing an id rather than doubling it", () => {
-    new CommandSet(defineCommands({ "list.kill": () => {} }));
-    new CommandSet(defineCommands({ "list.kill": () => {} }));
-    const ids = publishedCommands().map((c) => c.id);
-    expect(ids.filter((id) => id === "list.kill")).toEqual(["list.kill"]);
-  });
-
-  it("keeps published commands in registry order", () => {
-    const order = COMMAND_SPECS.map((s) => s.id);
-    const ids = publishedCommands().map((c) => c.id);
-    expect(ids).toEqual(order.filter((id) => ids.includes(id)));
-  });
-});
-
-describe("isTypingTarget", () => {
-  it("is true for form fields and editable nodes, false otherwise", () => {
-    expect(isTypingTarget(el("<input>"))).toBe(true);
-    expect(isTypingTarget(el("<textarea></textarea>"))).toBe(true);
-    expect(isTypingTarget(el("<select></select>"))).toBe(true);
-    expect(isTypingTarget(el('<div contenteditable="true"></div>'))).toBe(true);
-    expect(isTypingTarget(el("<button></button>"))).toBe(false);
-    expect(isTypingTarget(null)).toBe(false);
-  });
-});

web/src/commands.ts

@@ -1,386 +0,0 @@
-// The web client's command registry (#148). One entry per command — a stable
-// id, a plain-language label, the key chord it answers to, and a `run()` — so
-// there is exactly one list of what the client can do. The `?` overlay renders
-// from it (`help.ts`), and every keybinding is dispatched through it; a command
-// added here is bound and documented in the same edit.
-//
-// Keys are canonical strings, the same spelling the TUI's `InputKey::canonical`
-// produces (`ctrl-shift-h`, `enter`, `esc`, `n`, `N`) and chords are those
-// joined by a space (`ctrl-a ctrl-k`). Matching the TUI's spelling is what lets
-// docs/COMMAND-BAR.md describe one key model for both clients.
-
-/** Where a command's keys are listened for. `global` is the window, `list` the
- *  sidebar's session tree, `pane` the attached terminal, `overlay` the help
- *  dialog while it is up. */
-export type CommandScope = "global" | "list" | "pane" | "overlay";
-
-export interface CommandSpec {
-  /** Stable identifier. Never rendered; safe to bind config and tests to. */
-  id: string;
-  /** Plain-language label — what the `?` overlay and (later) the command bar
-   *  show. */
-  label: string;
-  /** Help-overlay section. Groups render in the order they first appear here. */
-  group: string;
-  /** Canonical chords that run it. The first is the one shown to the operator;
-   *  the rest are aliases (`j` and `down`). */
-  keys: string[];
-  scope: CommandScope;
-}
-
-export interface Command extends CommandSpec {
-  run: () => void;
-}
-
-/** Every command the web client has. The single list this issue exists to
- *  create: labels, chords and grouping live here and nowhere else. */
-export const COMMAND_SPECS: readonly CommandSpec[] = [
-  {
-    id: "spawn.open",
-    label: "Open the spawn form",
-    group: "Sessions",
-    keys: ["n"],
-    scope: "global",
-  },
-  {
-    id: "spawn.fastForward",
-    label: "Spawn a session with every default resolved",
-    group: "Sessions",
-    keys: ["N"],
-    scope: "global",
-  },
-  {
-    id: "focus.toggle",
-    label: "Move the keyboard between the session list and the pane",
-    group: "Session list",
-    keys: ["ctrl-shift-h"],
-    scope: "global",
-  },
-  {
-    id: "list.next",
-    label: "Highlight the next session",
-    group: "Session list",
-    keys: ["j", "down"],
-    scope: "list",
-  },
-  {
-    id: "list.prev",
-    label: "Highlight the previous session",
-    group: "Session list",
-    keys: ["k", "up"],
-    scope: "list",
-  },
-  {
-    id: "list.activate",
-    label: "Open the highlighted session, or expand a folder",
-    group: "Session list",
-    keys: ["enter"],
-    scope: "list",
-  },
-  {
-    id: "list.toggleFolder",
-    label: "Collapse or expand the highlighted folder",
-    group: "Session list",
-    keys: ["c"],
-    scope: "list",
-  },
-  {
-    id: "list.rename",
-    label: "Rename the highlighted session",
-    group: "Session list",
-    keys: ["r"],
-    scope: "list",
-  },
-  {
-    id: "list.kill",
-    label: "Kill the highlighted session",
-    group: "Session list",
-    keys: ["x"],
-    scope: "list",
-  },
-  {
-    id: "list.focusPane",
-    label: "Send the keyboard to the pane",
-    group: "Session list",
-    keys: ["tab"],
-    scope: "list",
-  },
-  {
-    id: "pane.focusList",
-    label: "Hand the keyboard back to the session list, from the pane",
-    group: "Session list",
-    keys: ["esc"],
-    scope: "pane",
-  },
-  {
-    id: "help.toggle",
-    label: "Show or hide this help",
-    group: "Help",
-    keys: ["?"],
-    scope: "global",
-  },
-  {
-    id: "help.close",
-    label: "Close the help overlay or an open menu",
-    group: "Help",
-    keys: ["esc"],
-    scope: "overlay",
-  },
-  {
-    id: "debug.toggleHud",
-    label: "Toggle the debug HUD",
-    group: "Debug",
-    keys: ["ctrl-shift-d"],
-    scope: "global",
-  },
-];
-
-const SPEC_BY_ID = new Map(COMMAND_SPECS.map((s) => [s.id, s]));
-
-/** Attach handlers to specs, by id. Throws on an unknown id, so a typo is a
- *  test failure rather than a key that silently does nothing. */
-export function defineCommands(handlers: Record<string, () => void>): Command[] {
-  return Object.entries(handlers).map(([id, run]) => {
-    const spec = SPEC_BY_ID.get(id);
-    if (!spec) throw new Error(`unknown command id: ${id}`);
-    return { ...spec, run };
-  });
-}
-
-// ---- what the help overlay renders ----
-
-const published = new Map<string, Command>();
-
-/** Record commands as bound. Re-registering an id replaces it, so a second
- *  sidebar (tests, hot reload) doesn't duplicate rows in the overlay. */
-export function publishCommands(cmds: Command[]): void {
-  for (const c of cmds) published.set(c.id, c);
-}
-
-/** Every bound command, in `COMMAND_SPECS` order. */
-export function publishedCommands(): Command[] {
-  return COMMAND_SPECS.map((s) => published.get(s.id)).filter((c): c is Command => c !== undefined);
-}
-
-// ---- key canonicalisation ----
-
-const NAMED: Record<string, string> = {
-  Escape: "esc",
-  Enter: "enter",
-  Tab: "tab",
-  Backspace: "backspace",
-  ArrowUp: "up",
-  ArrowDown: "down",
-  ArrowLeft: "left",
-  ArrowRight: "right",
-  Home: "home",
-  End: "end",
-  PageUp: "pageup",
-  PageDown: "pagedown",
-  Delete: "delete",
-  " ": "space",
-};
-
-/** The canonical string for one keydown. Mirrors the TUI's
- *  `InputKey::canonical`: modifier prefixes in ctrl/alt/shift order, then the
- *  key. A shifted character already spells itself (`N`, `?`), so `shift-` is
- *  only written when another modifier is present and the char was folded to
- *  lower case. */
-export function canonicalizeKey(e: KeyboardEvent): string | null {
-  if (!e.key) return null;
-  // Modifier keys pressed alone are never a binding.
-  if (e.key === "Control" || e.key === "Alt" || e.key === "Shift" || e.key === "Meta") return null;
-  const named = NAMED[e.key];
-  if (named === "tab" && e.shiftKey) return "backtab";
-  let out = "";
-  if (e.ctrlKey) out += "ctrl-";
-  if (e.altKey) out += "alt-";
-  if (e.metaKey) out += "meta-";
-  if (named) {
-    if (e.shiftKey) out += "shift-";
-    return out + named;
-  }
-  if (e.key.length === 1) {
-    if (out === "") return e.key;
-    if (e.shiftKey) out += "shift-";
-    return out + e.key.toLowerCase();
-  }
-  if (e.shiftKey) out += "shift-";
-  return out + e.key.toLowerCase();
-}
-
-const MOD_PREFIX = /^(ctrl|alt|meta|shift)-/;
-
-/** True when a chord carries a modifier or more than one key. Plain single-key
- *  chords are the ones that stay deaf inside form fields. */
-function isChorded(chord: string): boolean {
-  return chord.includes(" ") || MOD_PREFIX.test(chord);
-}
-
-/** True when the event target swallows plain keystrokes — a form field, or the
- *  hidden textarea xterm types into. Every plain single-key binding is deaf in
- *  the same places. */
-export function isTypingTarget(target: EventTarget | null): boolean {
-  const el = target as HTMLElement | null;
-  if (!el || typeof el.tagName !== "string") return false;
-  return (
-    el.tagName === "INPUT" ||
-    el.tagName === "TEXTAREA" ||
-    el.tagName === "SELECT" ||
-    el.isContentEditable
-  );
-}
-
-/** xterm's offscreen textarea. It is a typing target like any other, but it is
- *  also where the leader has to work — a pane is exactly where the operator
- *  needs the escape hatch (docs/COMMAND-BAR.md). */
-function isTerminalTextarea(target: EventTarget | null): boolean {
-  const el = target as HTMLElement | null;
-  return !!el && typeof el.className === "string" && el.classList?.contains("xterm-helper-textarea");
-}
-
-// ---- display ----
-
-const CAPS: Record<string, string> = {
-  ctrl: "Ctrl",
-  alt: "Alt",
-  meta: "Meta",
-  shift: "Shift",
-  esc: "Esc",
-  enter: "Enter",
-  tab: "Tab",
-  backtab: "Shift Tab",
-  backspace: "Backspace",
-  up: "Up",
-  down: "Down",
-  left: "Left",
-  right: "Right",
-  home: "Home",
-  end: "End",
-  pageup: "PgUp",
-  pagedown: "PgDn",
-  delete: "Del",
-  space: "Space",
-};
-
-/** Keycaps for a chord, left to right: `ctrl-shift-h` → Ctrl, Shift, H. A
- *  multi-key chord separates its keys with a `then` cap. */
-export function keyCaps(chord: string): string[] {
-  const caps: string[] = [];
-  for (const [i, key] of chord.split(" ").entries()) {
-    if (i > 0) caps.push("then");
-    const parts = key.split("-");
-    // A bare `-` key splits into two empties; treat it as the key itself.
-    if (parts.every((p) => p === "")) {
-      caps.push("-");
-      continue;
-    }
-    const last = parts.pop() as string;
-    const mods = parts.filter((p) => p !== "");
-    for (const m of mods) caps.push(CAPS[m] ?? m);
-    caps.push(CAPS[last] ?? (mods.length > 0 && last.length === 1 ? last.toUpperCase() : last));
-  }
-  return caps;
-}
-
-// ---- dispatch ----
-
-/** Default leader, mirroring the TUI's `[tui].leader`. `ctrl-a` is select-all
- *  in a browser, so a set that owns the leader `preventDefault`s it. */
-export const DEFAULT_LEADER = "ctrl-a";
-
-/** How long a partial chord waits for its next key — the TUI's
- *  `chord_timeout_ms` default. */
-export const DEFAULT_CHORD_TIMEOUT_MS = 1000;
-
-export interface CommandSetOptions {
-  /** Canonical leader key. A set given one holds every leader press as a
-   *  pending chord, whether or not anything is bound behind it yet. */
-  leader?: string | null;
-  chordTimeoutMs?: number;
-  /** Call `preventDefault()` on a handled key. Off for the terminal's own key
-   *  handler, which swallows by returning `false` to xterm instead. */
-  preventDefault?: boolean;
-  /** Clock, for tests. */
-  now?: () => number;
-}
-
-/** A group of commands listening on one surface. Resolves a keydown to a
- *  command the way the TUI's `ChordState` does: hold while the sequence is a
- *  strict prefix of some binding, otherwise resolve and dispatch. */
-export class CommandSet {
-  private readonly byChord = new Map<string, Command>();
-  private readonly leader: string | null;
-  private readonly timeout: number;
-  private readonly preventDefault: boolean;
-  private readonly now: () => number;
-  private held: string[] = [];
-  private lastPress = 0;
-
-  constructor(
-    readonly commands: Command[],
-    opts: CommandSetOptions = {},
-  ) {
-    for (const c of commands) for (const k of c.keys) this.byChord.set(k, c);
-    this.leader = opts.leader ?? null;
-    this.timeout = opts.chordTimeoutMs ?? DEFAULT_CHORD_TIMEOUT_MS;
-    this.preventDefault = opts.preventDefault ?? true;
-    this.now = opts.now ?? (() => Date.now());
-    publishCommands(commands);
-  }
-
-  /** Whether any binding starts with `candidate` and continues. */
-  private isPrefix(candidate: string): boolean {
-    const marker = `${candidate} `;
-    for (const chord of this.byChord.keys()) if (chord.startsWith(marker)) return true;
-    return false;
-  }
-
-  /** Feed one keydown. Returns true when the key was consumed — dispatched, or
-   *  held as a partial chord. */
-  handle(e: KeyboardEvent): boolean {
-    const key = canonicalizeKey(e);
-    if (key === null) return false;
-    if (this.held.length > 0 && this.now() - this.lastPress > this.timeout) this.held = [];
-    const candidate = this.held.length > 0 ? `${this.held.join(" ")} ${key}` : key;
-    this.lastPress = this.now();
-
-    // The leader is a prefix by construction, so it stops being select-all
-    // before anything is bound behind it (#149 binds the first chord).
-    if (this.leader !== null && this.held.length === 0 && key === this.leader) {
-      if (isTypingTarget(e.target) && !isTerminalTextarea(e.target)) return false;
-      this.held = [key];
-      if (this.preventDefault) e.preventDefault();
-      return true;
-    }
-
-    if (this.isPrefix(candidate)) {
-      this.held.push(key);
-      if (this.preventDefault) e.preventDefault();
-      return true;
-    }
-
-    const wasChord = this.held.length > 0;
-    this.held = [];
-    const cmd = this.byChord.get(candidate);
-    if (!cmd) {
-      // A chord that resolved to nothing is still consumed: the leader took
-      // the key, so it must not also fall through to a plain binding.
-      return wasChord;
-    }
-    // Plain single-key bindings are deaf where typing happens; chorded ones are
-    // not, and neither are the pane's and the overlay's, which are only fed
-    // from the surface that owns them.
-    if (
-      !isChorded(candidate) &&
-      cmd.scope !== "pane" &&
-      cmd.scope !== "overlay" &&
-      isTypingTarget(e.target)
-    ) {
-      return false;
-    }
-    if (this.preventDefault) e.preventDefault();
-    cmd.run();
-    return true;
-  }
-}

web/src/debug.ts

@@ -2,8 +2,6 @@
 // survives reloads, flipped by a keybind (Ctrl+Shift+D), and force-enabled by
 // `?hud` in dev. A `maestro-hud-toggle` event lets the HUD re-render on change.
 
-import { CommandSet, defineCommands } from "./commands.js";
-
 const STORAGE_KEY = "maestro:hud";
 export const HUD_TOGGLE_EVENT = "maestro-hud-toggle";
 
@@ -33,9 +31,12 @@ export function toggleHud(): void {
   setHudEnabled(!isHudEnabled());
 }
 
-const hudKeys = new CommandSet(defineCommands({ "debug.toggleHud": () => toggleHud() }));
-
 /** Global keybind: Ctrl+Shift+D toggles the debug HUD. */
 export function installHudKeybind(): void {
-  window.addEventListener("keydown", (e) => hudKeys.handle(e));
+  window.addEventListener("keydown", (e) => {
+    if (e.ctrlKey && e.shiftKey && (e.key === "D" || e.key === "d")) {
+      e.preventDefault();
+      toggleHud();
+    }
+  });
 }

web/src/help.test.ts

@@ -1,8 +1,14 @@
 // @vitest-environment happy-dom
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { keyCaps, publishedCommands } from "./commands.js";
-import { closeHelp, groupedCommands, installHelpKeybind, isHelpOpen, openHelp } from "./help.js";
+import {
+  SHORTCUTS,
+  closeHelp,
+  installHelpKeybind,
+  isHelpOpen,
+  isTypingTarget,
+  openHelp,
+} from "./help.js";
 
 beforeEach(() => {
   installHelpKeybind();
@@ -24,24 +30,14 @@ function rows(): string[] {
 }
 
 describe("help overlay", () => {
-  it("renders exactly the commands the registry has bound, grouped", () => {
+  it("renders every registered shortcut, grouped", () => {
     openHelp();
-    const groups = groupedCommands();
-    expect([...document.querySelectorAll(".help-group-title")].map((h) => h.textContent)).toEqual(
-      groups.map((g) => g.title),
+    const groups = [...document.querySelectorAll(".help-group-title")].map((h) => h.textContent);
+    expect(groups).toEqual(SHORTCUTS.map((g) => g.title));
+    expect(rows()).toEqual(SHORTCUTS.flatMap((g) => g.items.map((s) => s.keys.join(" "))));
+    expect(document.querySelectorAll(".help-desc")).toHaveLength(
+      SHORTCUTS.reduce((n, g) => n + g.items.length, 0),
     );
-    expect(rows()).toEqual(
-      groups.flatMap((g) => g.items.map((c) => keyCaps(c.keys[0]).join(" "))),
-    );
-    expect([...document.querySelectorAll(".help-desc")].map((d) => d.textContent)).toEqual(
-      groups.flatMap((g) => g.items.map((c) => c.label)),
-    );
-  });
-
-  it("names each row by its command id, so a row can't drift from its command", () => {
-    openHelp();
-    expect([...document.querySelectorAll<HTMLElement>(".help-row")].map((r) => r.dataset.commandId))
-      .toEqual(publishedCommands().map((c) => c.id));
   });
 
   it("opens on ? and closes on a second ?", () => {
@@ -98,3 +94,19 @@ describe("help overlay", () => {
     expect(document.querySelectorAll(".help-overlay")).toHaveLength(1);
   });
 });
+
+describe("isTypingTarget", () => {
+  it("is true for form fields and editable nodes, false otherwise", () => {
+    const el = (html: string) => {
+      const d = document.createElement("div");
+      d.innerHTML = html;
+      return d.firstElementChild as HTMLElement;
+    };
+    expect(isTypingTarget(el("<input>"))).toBe(true);
+    expect(isTypingTarget(el("<textarea></textarea>"))).toBe(true);
+    expect(isTypingTarget(el("<select></select>"))).toBe(true);
+    expect(isTypingTarget(el('<div contenteditable="true"></div>'))).toBe(true);
+    expect(isTypingTarget(el("<button></button>"))).toBe(false);
+    expect(isTypingTarget(null)).toBe(false);
+  });
+});

web/src/help.ts

@@ -1,15 +1,69 @@
 /** Keyboard-shortcut overlay (`?`), the web counterpart of the TUI's help
- *  overlay. It renders the command registry (`commands.ts`) — the same list
- *  that dispatches the keys — so a binding can never be documented as one
- *  thing and do another. */
+ *  overlay. One registry drives both the rendering and what we claim is bound,
+ *  so a binding added to `main.ts` without an entry here reads as missing. */
 
-import {
-  CommandSet,
-  defineCommands,
-  keyCaps,
-  publishedCommands,
-  type Command,
-} from "./commands.js";
+export interface Shortcut {
+  /** Keycaps, rendered left to right as separate <kbd>. */
+  keys: string[];
+  description: string;
+}
+
+export interface ShortcutGroup {
+  title: string;
+  items: Shortcut[];
+}
+
+export const SHORTCUTS: ShortcutGroup[] = [
+  {
+    title: "Sessions",
+    items: [
+      { keys: ["n"], description: "Open the spawn form" },
+      { keys: ["N"], description: "Spawn a session with every default resolved" },
+    ],
+  },
+  {
+    title: "Session list",
+    items: [
+      {
+        keys: ["Ctrl", "Shift", "H"],
+        description: "Move the keyboard between the session list and the pane",
+      },
+      { keys: ["j"], description: "Highlight the next session" },
+      { keys: ["k"], description: "Highlight the previous session" },
+      { keys: ["Enter"], description: "Open the highlighted session, or expand a folder" },
+      { keys: ["c"], description: "Collapse or expand the highlighted folder" },
+      { keys: ["r"], description: "Rename the highlighted session" },
+      { keys: ["x"], description: "Kill the highlighted session" },
+      { keys: ["Tab"], description: "Send the keyboard to the pane" },
+      { keys: ["Esc"], description: "Hand the keyboard back to the session list, from the pane" },
+    ],
+  },
+  {
+    title: "Help",
+    items: [
+      { keys: ["?"], description: "Show or hide this help" },
+      { keys: ["Esc"], description: "Close the help overlay or an open menu" },
+    ],
+  },
+  {
+    title: "Debug",
+    items: [{ keys: ["Ctrl", "Shift", "D"], description: "Toggle the debug HUD" }],
+  },
+];
+
+/** True when the event target swallows plain keystrokes — a form field, or the
+ *  hidden textarea xterm types into. Shared with `main.ts` so every global
+ *  single-key binding is deaf in the same places. */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el || typeof el.tagName !== "string") return false;
+  return (
+    el.tagName === "INPUT" ||
+    el.tagName === "TEXTAREA" ||
+    el.tagName === "SELECT" ||
+    el.isContentEditable
+  );
+}
 
 let open: { el: HTMLElement; dispose: () => void } | null = null;
 
@@ -54,7 +108,7 @@ export function openHelp(): HTMLElement {
   head.append(title, close);
   panel.appendChild(head);
 
-  for (const group of groupedCommands()) {
+  for (const group of SHORTCUTS) {
     const section = document.createElement("section");
     section.className = "help-group";
     const heading = document.createElement("h3");
@@ -62,20 +116,19 @@ export function openHelp(): HTMLElement {
     heading.textContent = group.title;
     const list = document.createElement("dl");
     list.className = "help-list";
-    for (const cmd of group.items) {
+    for (const item of group.items) {
       const row = document.createElement("div");
       row.className = "help-row";
-      row.dataset.commandId = cmd.id;
       const keys = document.createElement("dt");
       keys.className = "help-keys";
-      for (const key of keyCaps(cmd.keys[0])) {
+      for (const key of item.keys) {
         const cap = document.createElement("kbd");
         cap.textContent = key;
         keys.appendChild(cap);
       }
       const desc = document.createElement("dd");
       desc.className = "help-desc";
-      desc.textContent = cmd.label;
+      desc.textContent = item.description;
       row.append(keys, desc);
       list.appendChild(row);
     }
@@ -100,26 +153,6 @@ export function openHelp(): HTMLElement {
   return el;
 }
 
-/** The registry's commands, in registry order, bucketed into the help
- *  overlay's sections. Groups appear in the order their first command does. */
-export function groupedCommands(): { title: string; items: Command[] }[] {
-  const groups: { title: string; items: Command[] }[] = [];
-  for (const cmd of publishedCommands()) {
-    let group = groups.find((g) => g.title === cmd.group);
-    if (!group) {
-      group = { title: cmd.group, items: [] };
-      groups.push(group);
-    }
-    group.items.push(cmd);
-  }
-  return groups;
-}
-
-// The overlay's own two commands. `help.close` is `overlay`-scoped: it is only
-// fed keys while the dialog is up.
-const helpKeys = new CommandSet(defineCommands({ "help.toggle": () => toggleHelp() }));
-const overlayKeys = new CommandSet(defineCommands({ "help.close": () => closeHelp() }));
-
 let installed = false;
 
 /** Global keybind: `?` toggles the overlay, Escape closes it. Idempotent, so a
@@ -128,7 +161,16 @@ export function installHelpKeybind(): void {
   if (installed) return;
   installed = true;
   window.addEventListener("keydown", (e) => {
-    if (open && overlayKeys.handle(e)) return;
-    helpKeys.handle(e);
+    if (e.key === "Escape" && open) {
+      e.preventDefault();
+      closeHelp();
+      return;
+    }
+    // Shift is how `?` is typed on most layouts; the others would be a
+    // different binding entirely.
+    if (e.key !== "?" || e.ctrlKey || e.altKey || e.metaKey) return;
+    if (isTypingTarget(e.target)) return;
+    e.preventDefault();
+    toggleHelp();
   });
 }

web/src/kit.ts

@@ -129,6 +129,7 @@ export function renderKit(): HTMLElement {
       "--muted",
       "--faint",
       "--accent",
+      "--preview",
       "--danger",
       "--warn",
     ];

web/src/main.ts

@@ -6,8 +6,7 @@ import { renderSidebar } from "./catalog.js";
 import { ConnectionPool } from "./connections.js";
 import { installDrawer, installDrawerSwipe, requestToggleDrawer } from "./drawer.js";
 import { installHudKeybind } from "./debug.js";
-import { installHelpKeybind, isHelpOpen } from "./help.js";
-import { CommandSet, DEFAULT_LEADER, defineCommands } from "./commands.js";
+import { installHelpKeybind, isHelpOpen, isTypingTarget } from "./help.js";
 import { DaemonLink } from "./daemonLink.js";
 import { CatalogStore } from "./events.js";
 import { installRestartOverlay } from "./restartOverlay.js";
@@ -362,48 +361,37 @@ async function requestFastForward(): Promise<void> {
   });
 }
 
-// The global half of the command registry (#148). Two sets, because they
-// differ in one thing: the help overlay owns the keyboard while it is up, so
-// the plain keys go deaf behind it while the focus chord does not — an
-// attached terminal must never be able to trap the focus keys.
-//
-// `n` opens the spawn modal, `N` fast-forwards a spawn (#67). Both are plain
-// keys, so `isTypingTarget` keeps them out of form fields and the terminal's
-// hidden textarea.
-const spawnKeys = new CommandSet(
-  defineCommands({
-    "spawn.open": () => requestOpenSpawn(),
-    "spawn.fastForward": () => void requestFastForward(),
-  }),
-);
+// Keyboard pair (#67): `n` opens the spawn modal, `N` fast-forwards a spawn.
+// Ignored while typing anywhere (form fields, the terminal's hidden
+// textarea, search) so an attached session's keys are never hijacked.
+document.addEventListener("keydown", (e) => {
+  if (e.ctrlKey || e.altKey || e.metaKey) return;
+  if (isTypingTarget(e.target)) return;
+  // The help overlay owns the keyboard while it is up.
+  if (isHelpOpen()) return;
+  if (e.key === "n") {
+    e.preventDefault();
+    requestOpenSpawn();
+  } else if (e.key === "N") {
+    e.preventDefault();
+    void requestFastForward();
+  }
+});
 
 // Ctrl+Shift+H moves the keyboard between the session list and the pane, the
 // web counterpart of the TUI's `ctrl-w h`. It has to be a chord: an attached
 // terminal owns every plain keystroke, so nothing unmodified could ever get
 // the focus back out of it.
-//
-// This set also owns the leader (`ctrl-a`, the TUI's default): it holds the
-// key as a partial chord and takes select-all off it, so the escape hatch
-// docs/COMMAND-BAR.md describes has somewhere to land (#149).
-const focusKeys = new CommandSet(
-  defineCommands({
-    "focus.toggle": () => {
-      if (sidebar.hasListFocus()) {
-        pool.focusTerminal();
-      } else {
-        drawer.open(); // no-op on desktop; on mobile the list is off-canvas
-        sidebar.focusList();
-      }
-    },
-  }),
-  { leader: DEFAULT_LEADER },
-);
-
 window.addEventListener("keydown", (e) => {
-  if (focusKeys.handle(e)) return;
-  // The help overlay owns the keyboard while it is up.
-  if (isHelpOpen()) return;
-  spawnKeys.handle(e);
+  if (!e.ctrlKey || !e.shiftKey || e.altKey || e.metaKey) return;
+  if (e.key !== "H" && e.key !== "h") return;
+  e.preventDefault();
+  if (sidebar.hasListFocus()) {
+    pool.focusTerminal();
+  } else {
+    drawer.open(); // no-op on desktop; on mobile the list is off-canvas
+    sidebar.focusList();
+  }
 });
 
 // Tab in the session list hands the keyboard to the pane; Escape in the pane

web/src/matcher.test.ts

@@ -1,201 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  matchAndRank,
-  type CommandCandidate,
-  type DirectoryCandidate,
-  type MatchCandidate,
-  type MatchResult,
-  type SessionCandidate,
-} from "./matcher.js";
-
-function session(
-  name: string,
-  directory?: string,
-  command?: string,
-  tool?: string,
-): SessionCandidate {
-  return { kind: "session", fields: { name, directory, command, tool } };
-}
-
-function command(label: string): CommandCandidate {
-  return { kind: "command", fields: { label } };
-}
-
-function directory(path: string): DirectoryCandidate {
-  return { kind: "directory", fields: { path } };
-}
-
-function label(result: MatchResult): string {
-  switch (result.candidate.kind) {
-    case "session":
-      return `session:${result.candidate.fields.name}`;
-    case "command":
-      return `command:${result.candidate.fields.label}`;
-    case "directory":
-      return `directory:${result.candidate.fields.path}`;
-  }
-}
-
-function positions(result: MatchResult): number[] {
-  return result.ranges.flatMap(([start, end]) =>
-    Array.from({ length: end - start }, (_, offset) => start + offset),
-  );
-}
-
-function expectResults(
-  query: string,
-  candidates: MatchCandidate[],
-  expected: Array<[label: string, score: number, field?: string, positions?: number[]]>,
-): void {
-  const results = matchAndRank(query, candidates);
-
-  expect(results.map((result) => [label(result), result.score])).toEqual(
-    expected.map(([candidateLabel, score]) => [candidateLabel, score]),
-  );
-  expect(results.map((result) => result.field)).toEqual(
-    expected.map(([, , field]) => field),
-  );
-  expect(results.map(positions)).toEqual(expected.map(([, , , matched]) => matched ?? []));
-}
-
-describe("matchAndRank fixtures", () => {
-  it("F1: an empty query keeps input order", () => {
-    expectResults(
-      "",
-      [
-        session("kill", "~/dev/api", "bash"),
-        session("killer-app", "~/dev/killer-app", "claude --resume", "claude"),
-        command("Kill selected session"),
-      ],
-      [
-        ["session:kill", 0],
-        ["session:killer-app", 0],
-        ["command:Kill selected session", 0],
-      ],
-    );
-  });
-
-  it("F2: an exact session name beats a prefix and kind breaks a tie", () => {
-    expectResults(
-      "kill",
-      [
-        session("kill", "~/dev/api", "bash"),
-        session("killer-app", "~/dev/killer-app", "claude --resume", "claude"),
-        command("Kill selected session"),
-      ],
-      [
-        ["session:kill", 178, "name", [0, 1, 2, 3]],
-        ["session:killer-app", 146, "name", [0, 1, 2, 3]],
-        ["command:Kill selected session", 146, "label", [0, 1, 2, 3]],
-      ],
-    );
-  });
-
-  it("F3: path segment boundaries beat mid-segment matches", () => {
-    expectResults(
-      "foo",
-      [directory("~/dev/foobar"), directory("~/src/myfoo"), directory("~/foo")],
-      [
-        ["directory:~/foo", 78, "path", [2, 3, 4]],
-        ["directory:~/dev/foobar", 74, "path", [6, 7, 8]],
-        ["directory:~/src/myfoo", 56, "path", [8, 9, 10]],
-      ],
-    );
-  });
-
-  it("F4: a query matching nothing returns no candidates", () => {
-    expectResults("zzz", [session("kill", "~/dev/api", "bash"), command("Kill selected session")], []);
-  });
-
-  it("F5: the highest-scoring embedding can differ from the greedy embedding", () => {
-    expectResults(
-      "mtu",
-      [session("maestro-tui"), session("maestro-daemon"), session("mtui-scratch")],
-      [
-        ["session:mtui-scratch", 122, "name", [0, 1, 2]],
-        ["session:maestro-tui", 91, "name", [0, 8, 9]],
-      ],
-    );
-  });
-
-  it("F6: a name beats a weighted directory match", () => {
-    expectResults(
-      "api",
-      [session("api", "~/dev/web", "bash"), session("worker", "~/dev/api", "bash")],
-      [
-        ["session:api", 154, "name", [0, 1, 2]],
-        ["session:worker", 50, "directory", [6, 7, 8]],
-      ],
-    );
-  });
-
-  it("F7: matching is case-insensitive and field length breaks a tie", () => {
-    expectResults(
-      "api",
-      [session("API-Gateway"), session("apiary")],
-      [
-        ["session:apiary", 122, "name", [0, 1, 2]],
-        ["session:API-Gateway", 122, "name", [0, 1, 2]],
-      ],
-    );
-  });
-
-  it("F8: the exact tool field beats the command field", () => {
-    expectResults(
-      "claude",
-      [session("nameless", "~/dev/x", "claude --resume", "claude"), session("clay", "~/dev/y", "bash")],
-      [["session:nameless", 186, "tool", [0, 1, 2, 3, 4, 5]]],
-    );
-  });
-
-  it("F9: a separator earns a word-boundary bonus", () => {
-    expectResults(
-      "ws",
-      [session("websearch"), session("web-search")],
-      [
-        ["session:web-search", 71, "name", [0, 4]],
-        ["session:websearch", 56, "name", [0, 3]],
-      ],
-    );
-  });
-
-  it("F10: command labels rank by boundary and initial gap", () => {
-    expectResults(
-      "se",
-      [command("Kill selected session"), command("Create a session"), command("Show help")],
-      [
-        ["command:Show help", 53, "label", [0, 6]],
-        ["command:Kill selected session", 51, "label", [5, 6]],
-        ["command:Create a session", 47, "label", [9, 10]],
-      ],
-    );
-  });
-
-  it("F11: directory matches separate on their initial gap", () => {
-    expectResults(
-      "dev",
-      [
-        session("api", "~/dev/api", "bash"),
-        session("notes", "~/documents/dev-notes", "nvim"),
-        session("scratch", "~/srv/devops", "bash"),
-      ],
-      [
-        ["session:api", 54, "directory", [2, 3, 4]],
-        ["session:scratch", 50, "directory", [6, 7, 8]],
-        ["session:notes", 44, "directory", [12, 13, 14]],
-      ],
-    );
-  });
-
-  it("F12: an exact field beats a prefix", () => {
-    expectResults(
-      "quit",
-      [command("Quit Maestro"), command("Quit")],
-      [
-        ["command:Quit", 178, "label", [0, 1, 2, 3]],
-        ["command:Quit Maestro", 146, "label", [0, 1, 2, 3]],
-      ],
-    );
-  });
-});

web/src/matcher.ts

@@ -1,224 +0,0 @@
-export type CandidateKind = "session" | "command" | "directory";
-
-export interface SessionCandidate {
-  kind: "session";
-  fields: {
-    name: string;
-    directory?: string;
-    command?: string;
-    tool?: string;
-  };
-}
-
-export interface CommandCandidate {
-  kind: "command";
-  fields: { label: string };
-}
-
-export interface DirectoryCandidate {
-  kind: "directory";
-  fields: { path: string };
-}
-
-export type MatchCandidate = SessionCandidate | CommandCandidate | DirectoryCandidate;
-export type MatchFieldName = "name" | "directory" | "command" | "tool" | "label" | "path";
-export type MatchRange = readonly [start: number, end: number];
-
-export interface MatchResult<C extends MatchCandidate = MatchCandidate> {
-  candidate: C;
-  score: number;
-  field: MatchFieldName | undefined;
-  ranges: MatchRange[];
-}
-
-interface Field {
-  name: MatchFieldName;
-  text: string;
-  weight: number;
-}
-
-interface Embedding {
-  score: number;
-  positions: number[];
-}
-
-interface RankedResult<C extends MatchCandidate> extends MatchResult<C> {
-  matchedText: string;
-  inputIndex: number;
-}
-
-const KIND_ORDER: Record<CandidateKind, number> = {
-  session: 0,
-  command: 1,
-  directory: 2,
-};
-
-function fields(candidate: MatchCandidate): Field[] {
-  switch (candidate.kind) {
-    case "session": {
-      const values: Array<[MatchFieldName, string | undefined, number]> = [
-        ["name", candidate.fields.name, 0],
-        ["directory", candidate.fields.directory, -24],
-        ["command", candidate.fields.command, -32],
-        ["tool", candidate.fields.tool, -40],
-      ];
-      return values.flatMap(([name, text, weight]) =>
-        text === undefined ? [] : [{ name, text, weight }],
-      );
-    }
-    case "command":
-      return [{ name: "label", text: candidate.fields.label, weight: 0 }];
-    case "directory":
-      return [{ name: "path", text: candidate.fields.path, weight: 0 }];
-  }
-}
-
-function normalizeQuery(query: string): string {
-  return query.toLowerCase().replace(/\s/g, "");
-}
-
-function boundaryBonus(text: string, position: number): number {
-  if (position === 0) return 18;
-
-  const previous = text[position - 1];
-  if ("/\\-_ .:".includes(previous)) return 16;
-
-  const current = text[position];
-  const isUppercase = current !== current.toLowerCase() && current === current.toUpperCase();
-  const previousIsLowercase =
-    previous !== previous.toUpperCase() && previous === previous.toLowerCase();
-  if (isUppercase && previousIsLowercase) return 12;
-
-  const isDigit = current >= "0" && current <= "9";
-  const previousIsDigit = previous >= "0" && previous <= "9";
-  if (isDigit && !previousIsDigit) return 12;
-
-  return 0;
-}
-
-function contribution(text: string, position: number, previousPosition: number): number {
-  const gap = position - previousPosition - 1;
-  return 16 + boundaryBonus(text, position) + (gap === 0 ? 8 : -Math.min(gap, 12));
-}
-
-function isBetterEmbedding(candidate: Embedding, incumbent: Embedding | undefined): boolean {
-  if (!incumbent || candidate.score !== incumbent.score) {
-    return !incumbent || candidate.score > incumbent.score;
-  }
-  for (let index = 0; index < candidate.positions.length; index++) {
-    if (candidate.positions[index] !== incumbent.positions[index]) {
-      return candidate.positions[index] < incumbent.positions[index];
-    }
-  }
-  return false;
-}
-
-function bestEmbedding(query: string, text: string): Embedding | undefined {
-  const lowerText = text.toLowerCase();
-  let previousStates = new Map<number, Embedding>();
-
-  for (let queryIndex = 0; queryIndex < query.length; queryIndex++) {
-    const states = new Map<number, Embedding>();
-    for (let position = 0; position < lowerText.length; position++) {
-      if (lowerText[position] !== query[queryIndex]) continue;
-
-      if (queryIndex === 0) {
-        states.set(position, {
-          score: contribution(text, position, -1),
-          positions: [position],
-        });
-        continue;
-      }
-
-      for (const [previousPosition, previous] of previousStates) {
-        if (previousPosition >= position) continue;
-        const candidate = {
-          score: previous.score + contribution(text, position, previousPosition),
-          positions: [...previous.positions, position],
-        };
-        if (isBetterEmbedding(candidate, states.get(position))) states.set(position, candidate);
-      }
-    }
-    if (states.size === 0) return undefined;
-    previousStates = states;
-  }
-
-  let best: Embedding | undefined;
-  for (const embedding of previousStates.values()) {
-    if (isBetterEmbedding(embedding, best)) best = embedding;
-  }
-  return best;
-}
-
-function toRanges(positions: number[]): MatchRange[] {
-  const ranges: MatchRange[] = [];
-  for (const position of positions) {
-    const previous = ranges[ranges.length - 1];
-    if (previous && previous[1] === position) {
-      ranges[ranges.length - 1] = [previous[0], position + 1];
-    } else {
-      ranges.push([position, position + 1]);
-    }
-  }
-  return ranges;
-}
-
-function compareByCodePoint(left: string, right: string): number {
-  const leftPoints = Array.from(left, (character) => character.codePointAt(0)!);
-  const rightPoints = Array.from(right, (character) => character.codePointAt(0)!);
-  const length = Math.min(leftPoints.length, rightPoints.length);
-  for (let index = 0; index < length; index++) {
-    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
-  }
-  return leftPoints.length - rightPoints.length;
-}
-
-export function matchAndRank<C extends MatchCandidate>(
-  query: string,
-  candidates: readonly C[],
-): MatchResult<C>[] {
-  const normalizedQuery = normalizeQuery(query);
-  if (normalizedQuery === "") {
-    return candidates.map((candidate) => ({ candidate, score: 0, field: undefined, ranges: [] }));
-  }
-
-  const results: RankedResult<C>[] = [];
-  candidates.forEach((candidate, inputIndex) => {
-    let best:
-      | { field: Field; score: number; positions: number[] }
-      | undefined;
-
-    for (const field of fields(candidate)) {
-      const embedding = bestEmbedding(normalizedQuery, field.text);
-      if (!embedding) continue;
-
-      const compactText = field.text.toLowerCase().replace(/\s/g, "");
-      const adjustment =
-        compactText === normalizedQuery ? 64 : compactText.startsWith(normalizedQuery) ? 32 : 0;
-      const score = embedding.score + adjustment + field.weight;
-      if (!best || score > best.score) best = { field, score, positions: embedding.positions };
-    }
-
-    if (best) {
-      results.push({
-        candidate,
-        score: best.score,
-        field: best.field.name,
-        ranges: toRanges(best.positions),
-        matchedText: best.field.text,
-        inputIndex,
-      });
-    }
-  });
-
-  results.sort(
-    (left, right) =>
-      right.score - left.score ||
-      KIND_ORDER[left.candidate.kind] - KIND_ORDER[right.candidate.kind] ||
-      left.matchedText.length - right.matchedText.length ||
-      compareByCodePoint(left.matchedText, right.matchedText) ||
-      left.inputIndex - right.inputIndex,
-  );
-
-  return results.map(({ candidate, score, field, ranges }) => ({ candidate, score, field, ranges }));
-}

web/src/multiview.test.ts

@@ -36,6 +36,7 @@ function fakeSidebar(): SidebarHandle {
     el: document.createElement("aside"),
     setActive() {},
     setHighlights() {},
+    setPreview() {},
     focusList() {},
     hasListFocus() {
       return false;

web/src/multiview.ts

@@ -221,6 +221,12 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     const tab = activeTab(layout);
     for (const pane of canvas.querySelectorAll<HTMLElement>(".mv-pane")) {
       pane.classList.toggle("is-focused", pane.dataset.leafId === tab.focusedLeafId);
+      // The previewed pane's titlebar wears the preview colour instead of the
+      // accent tint a focused pane gets (docs/PREVIEW.md).
+      pane.classList.toggle(
+        "is-preview",
+        preview !== null && pane.dataset.sessionId === preview.sessionId,
+      );
     }
     // A preview is not a focused pane: reporting it would clear the session's
     // `AwaitingInput` glow just because the operator scrolled past it.
@@ -229,6 +235,9 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
       open: realOpenSessions(),
       focused: focusedLeafSession(),
     });
+    // The row the preview came from wears the same colour, so the sidebar and
+    // the pane read as one thing rather than two unrelated highlights.
+    sidebar.setPreview(preview?.sessionId ?? null);
   }
 
   function focusLeaf(leafId: string): void {
@@ -549,6 +558,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
       if (!preview) pool.setFocus(null);
       canvas.appendChild(renderWelcome());
       sidebar.setHighlights({ open: realOpenSessions(), focused: null });
+      sidebar.setPreview(preview?.sessionId ?? null);
       persist();
       return;
     }
@@ -588,6 +598,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
 
     const pane = buildPane(focused);
     pane.el.classList.add("is-focused"); // the only pane — never dimmed
+    if (preview && focused.sessionId === preview.sessionId) pane.el.classList.add("is-preview");
     wrap.appendChild(pane.el);
     canvas.appendChild(wrap);
 
@@ -598,6 +609,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     );
     if (!preview) pool.setFocus(focused.sessionId ?? null);
     sidebar.setHighlights({ open: realOpenSessions(), focused: focused.sessionId ?? null });
+    sidebar.setPreview(preview?.sessionId ?? null);
   }
 
   function closeSession(sessionId: string): void {

web/src/preview.test.ts

@@ -45,11 +45,17 @@ function fakePool(): Spy {
   return { pool, visible: () => visible, focusCalls, mountedWithFocus };
 }
 
+/** Last value the controller pushed to `SidebarHandle.setPreview`. */
+const previewRow: { id: string | null } = { id: null };
+
 function fakeSidebar(): SidebarHandle {
   return {
     el: document.createElement("aside"),
     setActive() {},
     setHighlights() {},
+    setPreview(id: string | null) {
+      previewRow.id = id;
+    },
     focusList() {},
     hasListFocus() {
       return false;
@@ -88,6 +94,7 @@ describe("sidebar preview", () => {
   beforeEach(() => {
     stubFetch();
     document.body.replaceChildren();
+    previewRow.id = null;
   });
 
   afterEach(() => {
@@ -110,6 +117,23 @@ describe("sidebar preview", () => {
     expect(serializeLayout(layout)).toEqual(before);
   });
 
+  it("marks the previewed pane and its sidebar row, and unmarks them after", () => {
+    const layout = twoTabs();
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+
+    mv.previewSession("s1");
+    expect(previewRow.id).toBe("s1");
+    expect(mv.el.querySelectorAll(".mv-pane.is-preview")).toHaveLength(1);
+    expect(
+      (mv.el.querySelector(".mv-pane.is-preview") as HTMLElement).dataset.sessionId,
+    ).toBe("s1");
+
+    mv.previewSession(null);
+    expect(previewRow.id).toBeNull();
+    expect(mv.el.querySelectorAll(".mv-pane.is-preview")).toHaveLength(0);
+  });
+
   it("shows a session no pane holds in a throwaway tab that leaves no trace", () => {
     const layout = twoTabs();
     const before = serializeLayout(layout);

web/src/styles.css

@@ -87,6 +87,30 @@
   --accent-tint: oklch(0.92 0.005 256 / 0.1);
   --accent-ring: oklch(0.92 0.005 256 / 0.5);
 
+  /* preview (docs/PREVIEW.md): a provisional view needs a colour that is not
+     the accent, because the accent is what says "this is the one you picked".
+     Defined once, off a single hue variable, so a palette whose accent already
+     sits on that hue can move it (see periwinkle/orchid below); `light-dark()`
+     keeps the light pair here instead of in all eighteen theme blocks. */
+  --preview-h: 305;
+  --preview: light-dark(
+    oklch(0.55 0.16 var(--preview-h)),
+    oklch(0.78 0.14 var(--preview-h))
+  );
+  --preview-ink: light-dark(
+    oklch(0.99 0.005 var(--preview-h)),
+    oklch(0.19 0.045 var(--preview-h))
+  );
+  /* Opaque, not a wash: session rows read as fills, and a fill has to land on
+     the same colour whatever tier the row was already painted. `--accent-fill`
+     is the same recipe on the accent, so the two tiers differ by hue alone. */
+  --preview-tint: color-mix(in oklab, var(--preview) 30%, var(--surface-2));
+  --accent-fill: color-mix(in oklab, var(--accent) 30%, var(--surface-2));
+  --preview-ring: light-dark(
+    oklch(0.55 0.16 var(--preview-h) / 0.5),
+    oklch(0.78 0.14 var(--preview-h) / 0.6)
+  );
+
   --live: oklch(0.84 0.17 152);
   --live-glow: oklch(0.84 0.17 152 / 0.55);
 
@@ -256,6 +280,9 @@
   --accent-ink: oklch(0.18 0.04 278);
   --accent-tint: oklch(0.75 0.125 275 / 0.14);
   --accent-ring: oklch(0.75 0.125 275 / 0.55);
+  /* This accent is already violet, so preview moves to cyan to stay legible
+     as "not the accent". Set once here: the light blocks below don't touch it. */
+  --preview-h: 195;
   --term-bg: oklch(0.155 0.018 278);
 }
 :root[data-palette="periwinkle"][data-theme="light"],
@@ -437,6 +464,8 @@
   --accent-ink: oklch(0.22 0.05 310);
   --accent-tint: oklch(0.78 0.13 310 / 0.14);
   --accent-ring: oklch(0.78 0.13 310 / 0.55);
+  /* Same collision as periwinkle: an orchid accent needs a non-purple preview. */
+  --preview-h: 195;
   --term-bg: oklch(0.155 0.014 305);
 }
 :root[data-palette="orchid"][data-theme="light"],
@@ -1114,35 +1143,42 @@ textarea {
   border-radius: var(--r-1);
   color: var(--ink);
   position: relative;
-  /* No transition on `background`: it is what hover paints, and easing it puts
-     a visible delay between the pointer landing on a row and the row admitting
-     it. The ring (`.is-highlighted`, `.is-active`) still eases — that one
-     follows a keyboard walk, not the pointer. */
+  /* No transition on `background`: it is what hover, the keyboard cursor and
+     the preview all paint, and easing it puts a visible delay between the input
+     landing on a row and the row admitting it. `.is-active`'s ring still eases
+     — being open in a pane is a state, not a response to the pointer. */
   transition: box-shadow var(--dur-fast) var(--ease-out);
 }
 
-/* "Alive" reads as a faint wash on the row itself — no per-row status icon. */
-.tree-leaf[data-status="running"] {
+/* Session-row tiers (docs/SIDEBAR.md). A row is usually several of these at
+   once, so every qualifier below sits in `:where()`: each rule is worth the
+   same specificity and the ladder is decided purely by the order they appear
+   in, latest wins. Add a tier where it belongs in that order, not by piling on
+   another class to out-weigh the rule above it. Each tier paints a background
+   and nothing else — the list says all of this with fill, never an edge. */
+
+/* 1. Alive. A faint wash on the row itself — no per-row status icon. */
+.tree-leaf:where([data-status="running"]) {
   background: color-mix(in oklab, var(--accent) 6%, transparent);
 }
 
-.tree-leaf:hover {
-  background: var(--surface-2);
+/* 2. Under the pointer, or under the keyboard walk. Both are what previews a
+   row (docs/PREVIEW.md), so both read in the preview hue — never the accent,
+   which belongs to the row actually open. */
+.tree-leaf:where(:hover, .is-highlighted) {
+  background: color-mix(in oklab, var(--preview) 12%, var(--surface-2));
 }
 
-.tree-leaf[data-status="running"]:hover {
-  background: color-mix(in oklab, var(--accent) 13%, var(--surface-2));
+.tree-leaf:where([data-status="running"]):where(:hover, .is-highlighted) {
+  background: color-mix(in oklab, var(--preview) 18%, var(--surface-2));
 }
 
-.tree-leaf:focus-visible {
+.tree-leaf:where(:focus-visible) {
   outline: none;
   background: color-mix(in oklab, var(--accent) 16%, var(--surface-2));
 }
 
-/* Where the keyboard walk (j/k) is standing. Distinct from `.is-active`: this
-   is a cursor, not a statement about what is mounted, so it reads as a ring
-   rather than a fill and the two can sit on the same row. */
-.tree-leaf.is-highlighted,
+/* A folder row previews nothing, so its cursor stays a ring. */
 .tree-folder-header.is-highlighted {
   box-shadow: inset 0 0 0 2px var(--accent-ring);
 }
@@ -1151,17 +1187,28 @@ textarea {
   outline: none;
 }
 
-/* The session currently mounted in the content pane. */
-.tree-leaf.is-active,
-.tree-leaf.is-active[data-status="running"] {
-  background: var(--accent-tint);
-  box-shadow: inset 0 0 0 1px var(--accent-ring);
+/* 3. Open in some pane, but not the focused one (issue #33). */
+.tree-leaf:where(.is-open) {
+  background: color-mix(in oklab, var(--accent) 6%, transparent);
+}
+
+/* 4. The session currently mounted in the content pane. */
+.tree-leaf:where(.is-active) {
+  background: var(--accent-fill);
 }
 
 .tree-leaf.is-active .leaf-name {
   color: var(--ink);
 }
 
+/* 5. The row the content pane is previewing right now. Last, so previewing a
+   session that is already open still reads as provisional — except the session
+   already mounted in the pane (tier 4). Previewing that one changes nothing on
+   screen, so its accent stays put instead of blinking out under the pointer. */
+.tree-leaf:where(.is-previewing):where(:not(.is-active)) {
+  background: var(--preview-tint);
+}
+
 /* Exited sessions recede: dimmed name + an "exited" badge carry status, so it's
    never the running tint's absence alone doing the work. */
 .tree-leaf[data-status="dead"] {
@@ -2885,10 +2932,14 @@ input.leaf-rename:focus {
 }
 
 /* Preview (docs/PREVIEW.md): the content pane is showing a session the
-   operator only highlighted, so it reads as provisional — a dashed tab and a
-   dashed inset ring on the canvas — and reverts when the highlight moves. */
+   operator only highlighted, so it reads as provisional — the preview hue on
+   the pane's titlebar, a dashed tab, a dashed inset ring on the canvas — and
+   reverts when the highlight moves. The hue is deliberately not the accent:
+   the accent means "this is what you picked", which a preview is not. */
 .mv-tab.is-preview {
   border-style: dashed;
+  border-color: var(--preview-ring);
+  color: var(--preview);
   font-style: italic;
 }
 .mv.mv-previewing .mv-canvas::before {
@@ -2901,8 +2952,8 @@ input.leaf-rename:focus {
   border-radius: var(--r-1);
   font: 500 var(--fs-11) / 1.5 var(--font-mono);
   letter-spacing: 0.04em;
-  color: var(--accent-ink);
-  background: var(--accent);
+  color: var(--preview-ink);
+  background: var(--preview);
   opacity: 0.85;
   pointer-events: none;
 }
@@ -2911,7 +2962,7 @@ input.leaf-rename:focus {
   position: absolute;
   inset: 0;
   pointer-events: none;
-  border: 1px dashed var(--accent-ring);
+  border: 1px dashed var(--preview-ring);
   border-radius: var(--r-1);
   z-index: var(--z-sticky);
 }
@@ -3029,6 +3080,15 @@ input.leaf-rename:focus {
 .mv-pane:not(.is-focused) .attach-header {
   opacity: 0.7;
 }
+/* The previewed pane's titlebar carries the preview hue, so the chip is not the
+   only thing saying the pane is provisional — and so it is never mistaken for
+   the accent tint of the pane the operator actually focused. It keeps full
+   strength even though a preview never takes focus. */
+.mv-pane.is-preview .attach-header,
+.mv-pane.is-preview.is-focused .attach-header {
+  background: color-mix(in oklab, var(--preview) 34%, var(--surface));
+  opacity: 1;
+}
 /* A pane with no session yet: a quiet hint rather than blank terminal black. */
 .mv-pane-empty {
   flex: 1;
@@ -3118,13 +3178,6 @@ input.leaf-rename:focus {
   border-radius: var(--r-1);
 }
 
-/* sidebar two-tier highlight (issue #33).
-   .is-active = focused pane (loud, from existing rule); .is-open = open
-   elsewhere (quiet). */
-.tree-leaf.is-open {
-  background: color-mix(in oklab, var(--accent) 6%, transparent);
-}
-
 /* =========================================================================
    multi-view mobile (#35): below 860px only the focused pane is shown — no tab
    bar, no pane switcher; the sidebar drawer (☰) is the navigation.