fix(maestro): keep accent fill when previewing active row

Hovering the session already in the pane put the preview tint over its accent fill, so the row that is on screen looked unpicked. Tier 5 now skips `.is-active`.

CLAUDE.md

@@ -36,10 +36,16 @@ optional.
 
 ## Where the work is
 
-Linear project **Maestro** under team **Naps62**.
+Gitea issues on [`naps62/maestro`](https://git.naps.pt/naps62/maestro), grouped
+into milestones.
 
-`.claude/linear.json` wires `/yolo` and `/work` to this project — they pick from
-"available now" (status backlog/pending, not blocked).
+`.claude/linear.json` (legacy filename, `tracker: gitea`) wires `/yolo` and
+`/work` to that tracker — they pick from open, unassigned issues whose
+dependencies are all closed. `/blitz <milestone>` sweeps a whole milestone.
+
+Labels carry one value per axis: `area/*`, `type/*`, `difficulty/*`.
+`difficulty` drives model selection downstream, so it tracks the shape of the
+work, not its size.
 
 ## Repo layout
 
@@ -72,11 +78,20 @@ before changing anything that creates or removes one.
 sidebars — line layout, activity colours, duration format, state precedence.
 Read it before changing sidebar rendering.
 
+`docs/PREVIEW.md` is the contract for what the content pane shows while the
+operator moves the sidebar highlight — what a preview may touch, what ends it,
+what commits it. Read it before changing sidebar-driven navigation.
+
 `docs/RESTART.md` is the contract for what clients do when the daemon restarts
 or is upgraded under them — the build stamp on `/api/info`, the status
 indicator's states, the blocking overlay, grace and poll timings. Read it
 before changing reconnect behaviour on either client.
 
+`docs/COMMAND-BAR.md` is the contract for the `ctrl-k` command bar in both
+clients — how it opens, the sigils, the key model, the match-and-rank algorithm
+the two matchers must agree on, and the fixture table they are tested against.
+Read it before changing either bar or either matcher.
+
 `nix run .#dev` (or `just dev`) brings up the whole local stack under
 process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
 daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only

crates/maestro-daemon/src/activity.rs

@@ -69,7 +69,7 @@ pub fn decide(idle_for: Duration, awaiting_input: bool) -> ActivityState {
 /// How long a session's pane must be continuously focused (a client's pane,
 /// not a sidebar highlight) before an `AwaitingInput` glow clears: the
 /// operator has looked, so the rail stops asking for attention.
-pub const FOCUS_CLEAR_HOLD: Duration = Duration::from_secs(5);
+pub const FOCUS_CLEAR_HOLD: Duration = Duration::from_secs(1);
 
 /// Downgrade `raw` from `AwaitingInput` to `Idle` once the pane has been
 /// focused for at least [`FOCUS_CLEAR_HOLD`].
@@ -161,7 +161,7 @@ mod tests {
     fn awaiting_input_glows_until_focus_hold_is_reached() {
         let now = std::time::Instant::now();
         let mut suppressed = false;
-        let since = now - (FOCUS_CLEAR_HOLD - Duration::from_secs(1));
+        let since = now - (FOCUS_CLEAR_HOLD - Duration::from_millis(200));
         assert_eq!(
             apply_focus_suppression(
                 ActivityState::AwaitingInput,

crates/maestro-tui/src/app.rs

@@ -11,7 +11,6 @@
 //! `dispatch` / the overlay routing.
 
 use std::collections::{HashMap, HashSet};
-use std::io::Stdout;
 use std::path::PathBuf;
 use std::time::Duration;
 
@@ -19,7 +18,6 @@ use chrono::Utc;
 use crossterm::event::{Event as CtEvent, EventStream};
 use futures_util::StreamExt;
 use maestro_protocol::{routes, BranchInfo, CreateSessionRequest, DaemonClient, NameBatch};
-use ratatui::backend::CrosstermBackend;
 use ratatui::Terminal;
 use uuid::Uuid;
 
@@ -89,8 +87,56 @@ pub struct App {
     /// that can move `Focus::Pane` (attach, tab switch, sidebar toggle,
     /// mouse) is covered without each one remembering to report it.
     focused_session: Option<Uuid>,
+    /// A sidebar highlight waiting for the pane's minimum gap before it
+    /// becomes a preview (`docs/PREVIEW.md`). Walking the list with `j` held
+    /// down must not open an attach per row it passes over.
+    pending_preview: Option<(Uuid, std::time::Instant)>,
+    /// When the pane last swapped what it previews. `None` until the first
+    /// one, which is why a highlight landing on a still sidebar shows at once.
+    last_preview_at: Option<std::time::Instant>,
+    /// Sessions attached only because they were previewed, oldest first. Kept
+    /// connected past the preview so stepping back onto a row is instant, and
+    /// bounded so a long walk doesn't leave a socket per session behind.
+    preview_lru: Vec<Uuid>,
+    /// Fingerprint of the last frame drawn. The loop compares a freshly
+    /// computed key against this and skips the repaint when they match — an
+    /// idle TUI used to emit a full diff 30 times a second forever, which over
+    /// a remote terminal is constant traffic for no change on screen.
+    last_frame: Option<FrameKey>,
+    /// When that frame went out, for the periodic refresh below.
+    last_drawn_at: std::time::Instant,
+    /// Bumped by every path that mutates `AppState` outside the catalog and
+    /// the attached pane: keys, mouse, draft results, link transitions. Those
+    /// mutations are too diffuse to fingerprint individually, so the loop
+    /// treats "an input was processed" as "assume the frame is stale".
+    epoch: u64,
 }
 
+/// Everything a frame is built from that is cheap to sample every tick.
+/// Equal keys mean an identical frame, so the repaint can be skipped.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct FrameKey {
+    catalog: u64,
+    epoch: u64,
+    /// Active pane's session, its screen revision, and its link state.
+    pane: Option<(Uuid, u64, crate::session_task::SessionState)>,
+    area: ratatui::layout::Size,
+}
+
+/// Session cards carry a duration that advances on its own (`docs/SIDEBAR.md`),
+/// so a frame is never allowed to stand for longer than this even when nothing
+/// else changed.
+const CLOCK_REFRESH: Duration = Duration::from_secs(1);
+
+/// Shortest gap between two pane swaps (`docs/PREVIEW.md`). The first
+/// highlight to land shows at once; this only bounds how often the pane may
+/// follow after that, so a fast walk down the list attaches to the row it
+/// started on and the row it stopped on rather than every row between.
+const PREVIEW_GAP: Duration = Duration::from_millis(120);
+
+/// How many preview-only attaches to keep connected behind the current one.
+const PREVIEW_BUDGET: usize = 3;
+
 impl std::fmt::Debug for App {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("App")
@@ -170,13 +216,19 @@ impl App {
             last_sent_size: HashMap::new(),
             clicks: ClickTracker::default(),
             focused_session: None,
+            pending_preview: None,
+            last_preview_at: None,
+            preview_lru: Vec::new(),
+            last_frame: None,
+            last_drawn_at: std::time::Instant::now(),
+            epoch: 0,
         }
     }
 
     /// Drive the loop until the user quits. Consumes self.
-    pub async fn run(
+    pub async fn run<B: ratatui::backend::Backend>(
         mut self,
-        terminal: &mut Terminal<CrosstermBackend<Stdout>>,
+        terminal: &mut Terminal<B>,
     ) -> Result<(), TuiError> {
         if let Ok(info) = self.daemon.daemon_info().await {
             self.home_dir = info.home_dir;
@@ -184,7 +236,7 @@ impl App {
         let mut events = EventStream::new();
         loop {
             self.sync_focus().await;
-            self.redraw(terminal)?;
+            self.redraw_if_stale(terminal)?;
 
             tokio::select! {
                 Some(Ok(ev)) = events.next() => {
@@ -193,17 +245,24 @@ impl App {
                     }
                 }
                 Some(update) = self.draft_rx.recv() => {
+                    self.epoch = self.epoch.wrapping_add(1);
                     self.apply_draft_update(update).await;
                 }
                 _ = self.catalog.changed() => {
-                    // Render on next loop iteration.
+                    // Picked up by the frame key's catalog version.
                 }
                 _ = self.link.changed() => {
                     // The status indicator and the restart overlay both read
-                    // the link; redraw on the next loop iteration.
+                    // the link; neither is fingerprinted, so mark stale.
+                    self.epoch = self.epoch.wrapping_add(1);
                 }
                 _ = tokio::time::sleep(Duration::from_millis(33)) => {
-                    let effects = self.poll_due_probes_at(std::time::Instant::now());
+                    let now = std::time::Instant::now();
+                    let mut effects = self.poll_due_probes_at(now);
+                    effects.extend(self.poll_due_preview_at(now));
+                    if !effects.is_empty() {
+                        self.epoch = self.epoch.wrapping_add(1);
+                    }
                     self.perform(effects).await;
                 }
             }
@@ -217,6 +276,10 @@ impl App {
             return Ok(false);
         };
         let key = self.clicks.promote(key, std::time::Instant::now());
+        // Any key can move the cursor, open an overlay or edit a text buffer.
+        // Rather than fingerprint each of those, treat a processed input as
+        // proof the frame is stale.
+        self.epoch = self.epoch.wrapping_add(1);
 
         // The daemon is gone: everything a key could do goes through it, so
         // only the quit binding still resolves until it answers again.
@@ -253,16 +316,26 @@ impl App {
         match self.chord.feed(&key, &known) {
             ChordResult::Pending => Ok(false),
             ChordResult::Resolved(canon) => {
-                if let Some(act) = self.cfg.keymap.resolve(self.state.mode, &canon) {
-                    if matches!(act, Action::Quit) {
-                        return Ok(true);
+                let act = self.cfg.keymap.resolve(self.state.mode, &canon);
+                if matches!(act, Some(Action::Quit)) {
+                    return Ok(true);
+                }
+                let pty_owns_keys =
+                    self.state.mode == Mode::Insert && matches!(self.state.focus, Focus::Pane);
+                match act {
+                    // `Noop` suppresses a binding, and a key with no binding in
+                    // Insert mode is the session's — so a key bound to `Noop`
+                    // reaches the pty too. That is the escape hatch for taking
+                    // a default binding back.
+                    Some(Action::Noop) | None if pty_owns_keys => {
+                        let effects = self.forward_to_session(&key).into_iter().collect();
+                        self.perform(effects).await;
                     }
-                    let effects = self.dispatch(act);
-                    self.perform(effects).await;
-                } else if self.state.mode == Mode::Insert && matches!(self.state.focus, Focus::Pane)
-                {
-                    let effects = self.forward_to_session(&key).into_iter().collect();
-                    self.perform(effects).await;
+                    Some(act) => {
+                        let effects = self.dispatch(act);
+                        self.perform(effects).await;
+                    }
+                    None => {}
                 }
                 Ok(false)
             }
@@ -294,6 +367,7 @@ impl App {
                 self.state.sidebar_highlight = Some(SidebarItem::Session(id));
             }
         }
+        self.refresh_preview();
         true
     }
 
@@ -415,8 +489,15 @@ impl App {
                         if let Some(previous) = self.state.active_session() {
                             self.release_session(previous);
                         }
-                        effects.push(Effect::Attach(sid));
+                        // A previewed session is already attached: committing
+                        // to it keeps that stream rather than reopening one.
+                        if self.emulators.get(sid).is_none() {
+                            effects.push(Effect::Attach(sid));
+                        }
                     }
+                    // It is the pane's own session now, not a loan from the
+                    // preview budget.
+                    self.preview_lru.retain(|s| *s != sid);
                     self.state.attach_to_focused(sid);
                 }
             }
@@ -443,9 +524,96 @@ impl App {
                 }
             }
         }
+        // Every action can move the highlight or the focus, and the preview is
+        // a function of both (`docs/PREVIEW.md`).
+        self.refresh_preview();
         effects
     }
 
+    /// Recompute what the pane should be previewing. A session highlighted in
+    /// the sidebar is previewed as soon as [`PREVIEW_GAP`] has passed since the
+    /// last swap — immediately, for a highlight landing on a still list.
+    /// Anything else — a group row, the pane holding the keyboard, or the
+    /// highlight already sitting on the attached session — clears at once.
+    fn refresh_preview(&mut self) {
+        let wanted = match (self.state.focus, &self.state.sidebar_highlight) {
+            (Focus::Sidebar, Some(SidebarItem::Session(sid))) => Some(*sid),
+            _ => None,
+        };
+        match wanted {
+            Some(sid) if self.state.active_session() != Some(sid) => {
+                if self.state.preview != Some(sid) {
+                    let now = std::time::Instant::now();
+                    let due = match self.last_preview_at {
+                        Some(last) if now < last + PREVIEW_GAP => last + PREVIEW_GAP,
+                        _ => now,
+                    };
+                    self.pending_preview = Some((sid, due));
+                }
+            }
+            _ => {
+                self.pending_preview = None;
+                self.clear_preview();
+            }
+        }
+    }
+
+    /// The pane is free to follow: show the highlighted session, attaching it
+    /// if nothing already is.
+    fn poll_due_preview_at(&mut self, now: std::time::Instant) -> Vec<Effect> {
+        let Some((sid, due)) = self.pending_preview else {
+            return Vec::new();
+        };
+        if now < due {
+            return Vec::new();
+        }
+        self.pending_preview = None;
+        if self.state.preview == Some(sid) {
+            return Vec::new();
+        }
+        self.last_preview_at = Some(now);
+        self.state.preview = Some(sid);
+        // Set outside the input path, so nothing else marks the frame stale.
+        self.epoch = self.epoch.wrapping_add(1);
+        let fresh = self.emulators.get(sid).is_none();
+        if fresh {
+            self.preview_lru.retain(|s| *s != sid);
+            self.preview_lru.push(sid);
+        }
+        self.trim_preview_budget();
+        if fresh {
+            vec![Effect::Attach(sid)]
+        } else {
+            Vec::new()
+        }
+    }
+
+    fn clear_preview(&mut self) {
+        if self.state.preview.take().is_some() {
+            self.epoch = self.epoch.wrapping_add(1);
+        }
+        self.trim_preview_budget();
+    }
+
+    /// Drop preview-only attaches past the budget. What a tab holds, and what
+    /// is on screen right now, are never candidates.
+    fn trim_preview_budget(&mut self) {
+        while self.preview_lru.len() > PREVIEW_BUDGET {
+            let held: HashSet<Uuid> = self
+                .state
+                .tabs
+                .iter()
+                .filter_map(crate::state::Tab::session)
+                .chain(self.state.preview)
+                .collect();
+            let Some(pos) = self.preview_lru.iter().position(|sid| !held.contains(sid)) else {
+                break;
+            };
+            let victim = self.preview_lru.remove(pos);
+            self.release_session(victim);
+        }
+    }
+
     /// Open a stream for `sid` if one isn't already running.
     fn attach(&mut self, sid: Uuid) {
         if self.emulators.get(sid).is_some() {
@@ -959,9 +1127,46 @@ impl App {
         self.focused_session = wanted;
     }
 
-    fn redraw(
+    /// Sample everything a frame depends on. Cheap: two atomic loads, an
+    /// `RwLock` read of a `u64`, and the backend's size.
+    fn frame_key(&self, area: ratatui::layout::Size) -> FrameKey {
+        let pane = self.state.displayed_session().and_then(|sid| {
+            self.emulators
+                .get(sid)
+                .map(|h| (sid, h.revision(), h.state()))
+        });
+        FrameKey {
+            catalog: self.catalog.version(),
+            epoch: self.epoch,
+            pane,
+            area,
+        }
+    }
+
+    /// Repaint only when the frame key moved, or the clock refresh is due.
+    fn redraw_if_stale<B: ratatui::backend::Backend>(
         &mut self,
-        terminal: &mut Terminal<CrosstermBackend<Stdout>>,
+        terminal: &mut Terminal<B>,
+    ) -> Result<(), TuiError> {
+        // Polled rather than driven off `Event::Resize`: `Terminal::draw`'s own
+        // autoresize only runs on a draw, and a skipped draw must still notice
+        // the terminal changed shape.
+        let area = terminal
+            .size()
+            .map_err(|e| TuiError::Terminal(e.to_string()))?;
+        let key = self.frame_key(area);
+        if self.last_frame == Some(key) && self.last_drawn_at.elapsed() < CLOCK_REFRESH {
+            return Ok(());
+        }
+        self.redraw(terminal)?;
+        self.last_frame = Some(key);
+        self.last_drawn_at = std::time::Instant::now();
+        Ok(())
+    }
+
+    fn redraw<B: ratatui::backend::Backend>(
+        &mut self,
+        terminal: &mut Terminal<B>,
     ) -> Result<(), TuiError> {
         let snap = self.catalog.snapshot();
         let attached: HashSet<Uuid> = self
@@ -974,22 +1179,36 @@ 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 active_sid = self.state.active_session();
-        let pane = active_sid.and_then(|sid| {
+        let shown_sid = self.state.displayed_session();
+        let previewing = self.state.preview.is_some();
+        let pane = shown_sid.and_then(|sid| {
             self.emulators.get(sid).map(|h| Pane {
                 screen: h.screen.clone(),
                 status: PaneStatus::from(h.state()),
-                focused: matches!(self.state.focus, Focus::Pane),
+                // A preview never owns the keyboard, so it never draws a
+                // cursor either (`docs/PREVIEW.md`).
+                focused: matches!(self.state.focus, Focus::Pane) && !previewing,
             })
         });
-        let pane_title = match active_sid {
-            Some(sid) => snap
-                .sessions
-                .iter()
-                .find(|session| session.id == sid)
-                .map(crate::sidebar::name_for)
-                .unwrap_or_else(|| "session".into()),
+        let pane_title = match shown_sid {
+            Some(sid) => {
+                let name = snap
+                    .sessions
+                    .iter()
+                    .find(|session| session.id == sid)
+                    .map(crate::sidebar::name_for)
+                    .unwrap_or_else(|| "session".into());
+                if previewing {
+                    format!("{name}  ·  preview")
+                } else {
+                    name
+                }
+            }
             None => "session".into(),
         };
 
@@ -1017,7 +1236,7 @@ impl App {
         // Resize propagation: record the active pane's rect, recompute the
         // per-dimension min for every attached session, send Resize when
         // changed.
-        if let (Some(sid), Some(rect)) = (active_sid, self.region.pane) {
+        if let (Some(sid), Some(rect)) = (shown_sid, self.region.pane) {
             self.emulators.resize_tracker_mut().set_pane_size(
                 sid,
                 "active",
@@ -1054,6 +1273,7 @@ fn visible_sidebar_order(
         sessions: snap.sessions.clone(),
         highlight: None,
         attached: HashSet::new(),
+        pane_session: None,
     }
     .rendered_items_with_collapsed(collapsed)
 }
@@ -1257,6 +1477,100 @@ mod tests {
         )
     }
 
+    /// Counts how many times the loop actually repainted, by watching the
+    /// `TestBackend` buffer's generation via `draw` calls.
+    fn drew(app: &mut App, terminal: &mut Terminal<ratatui::backend::TestBackend>) -> bool {
+        let before = app.last_drawn_at;
+        app.redraw_if_stale(terminal).unwrap();
+        app.last_drawn_at != before
+    }
+
+    #[test]
+    fn unchanged_frame_is_not_repainted() {
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+
+        assert!(drew(&mut app, &mut terminal), "first frame must paint");
+        assert!(
+            !drew(&mut app, &mut terminal),
+            "nothing changed; the repaint should be skipped"
+        );
+    }
+
+    #[test]
+    fn a_processed_key_makes_the_frame_stale() {
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+        drew(&mut app, &mut terminal);
+
+        app.epoch = app.epoch.wrapping_add(1);
+        assert!(drew(&mut app, &mut terminal));
+    }
+
+    #[test]
+    fn a_catalog_event_makes_the_frame_stale() {
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+        drew(&mut app, &mut terminal);
+
+        app.catalog
+            .apply_event(maestro_protocol::CatalogEvent::Snapshot {
+                sessions: Vec::new(),
+            });
+        assert!(drew(&mut app, &mut terminal));
+    }
+
+    #[test]
+    fn a_resize_makes_the_frame_stale() {
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+        drew(&mut app, &mut terminal);
+
+        terminal.backend_mut().resize(120, 40);
+        assert!(drew(&mut app, &mut terminal));
+    }
+
+    #[test]
+    fn pane_output_makes_the_frame_stale() {
+        use crate::session_task::{SessionHandle, SessionState};
+        use std::sync::atomic::{AtomicU64, AtomicU8};
+        use std::sync::{Arc, Mutex};
+
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+
+        let sid = Uuid::from_u128(7);
+        let revision = Arc::new(AtomicU64::new(0));
+        app.emulators.insert(
+            sid,
+            SessionHandle {
+                tx: tokio::sync::mpsc::channel(1).0,
+                screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
+                state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+                revision: revision.clone(),
+            },
+        );
+        app.state.attach_to_focused(sid);
+        drew(&mut app, &mut terminal);
+        assert!(!drew(&mut app, &mut terminal), "idle pane must not repaint");
+
+        revision.fetch_add(1, std::sync::atomic::Ordering::Release);
+        assert!(drew(&mut app, &mut terminal), "new PTY bytes must repaint");
+    }
+
+    #[test]
+    fn a_stale_clock_repaints_even_with_no_events() {
+        let mut app = make_app();
+        let mut terminal = Terminal::new(ratatui::backend::TestBackend::new(80, 24)).unwrap();
+        drew(&mut app, &mut terminal);
+        assert!(!drew(&mut app, &mut terminal));
+
+        // Session cards show an advancing duration, so a frame may not stand
+        // for longer than CLOCK_REFRESH regardless of the key.
+        app.last_drawn_at = std::time::Instant::now() - CLOCK_REFRESH;
+        assert!(drew(&mut app, &mut terminal));
+    }
+
     #[test]
     fn enter_insert_then_leave() {
         let mut app = make_app();
@@ -1332,6 +1646,188 @@ mod tests {
         assert_eq!(app.state.overlay(), Some(&OverlayKind::Spawn));
     }
 
+    /// Seed the catalog with `ids` as sessions in one directory.
+    fn app_with_sessions(ids: &[Uuid]) -> App {
+        use chrono::Utc;
+        use maestro_protocol::{CatalogEvent, Session, SessionStatus};
+        let app = make_app();
+        app.catalog.apply_event(CatalogEvent::Snapshot {
+            sessions: ids
+                .iter()
+                .map(|id| Session {
+                    id: *id,
+                    command: "bash".into(),
+                    cwd: std::path::PathBuf::from("/"),
+                    env: Default::default(),
+                    metadata: Default::default(),
+                    worktree: None,
+                    status: SessionStatus::Running,
+                    created_at: Utc::now(),
+                    foreground: None,
+                    activity: Default::default(),
+                    activity_detail: None,
+                    last_activity_at: Utc::now(),
+                    activity_since: chrono::Utc::now(),
+                    current_cwd: None,
+                    blocked_work: None,
+                })
+                .collect(),
+        });
+        app
+    }
+
+    fn fake_handle() -> crate::session_task::SessionHandle {
+        use crate::session_task::{SessionHandle, SessionState};
+        use std::sync::atomic::{AtomicU64, AtomicU8};
+        use std::sync::{Arc, Mutex};
+        SessionHandle {
+            tx: tokio::sync::mpsc::channel(1).0,
+            screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
+            state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: Arc::new(AtomicU64::new(0)),
+        }
+    }
+
+    fn after_gap() -> std::time::Instant {
+        std::time::Instant::now() + PREVIEW_GAP + Duration::from_millis(1)
+    }
+
+    /// docs/PREVIEW.md: the highlight shows a session in the pane without the
+    /// tab taking it on.
+    #[test]
+    fn highlighting_a_session_previews_it_without_waiting() {
+        let a = Uuid::from_u128(1);
+        let mut app = app_with_sessions(&[a]);
+        app.dispatch(Action::SidebarNext);
+
+        // The list was still, so the pane follows on the next poll — no gap to
+        // wait out first (docs/PREVIEW.md).
+        assert_eq!(
+            app.poll_due_preview_at(std::time::Instant::now()),
+            vec![Effect::Attach(a)]
+        );
+        assert_eq!(app.state.preview, Some(a));
+        assert_eq!(app.state.displayed_session(), Some(a));
+        // The tab is untouched — the preview is a view, not a layout change.
+        assert_eq!(app.state.active_tab().session(), None);
+    }
+
+    /// The gap only bounds the *second* swap, so a burst costs two mounts.
+    #[test]
+    fn a_second_move_inside_the_gap_waits_for_it() {
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let mut app = app_with_sessions(&[a, b]);
+
+        app.dispatch(Action::SidebarNext);
+        let now = std::time::Instant::now();
+        assert_eq!(app.poll_due_preview_at(now), vec![Effect::Attach(a)]);
+
+        app.dispatch(Action::SidebarNext);
+        assert_eq!(app.poll_due_preview_at(now), vec![]);
+        assert_eq!(app.state.preview, Some(a));
+
+        assert_eq!(
+            app.poll_due_preview_at(after_gap()),
+            vec![Effect::Attach(b)]
+        );
+        assert_eq!(app.state.preview, Some(b));
+    }
+
+    /// A fast walk down the list attaches to where it stopped, not to every
+    /// row it crossed.
+    #[test]
+    fn walking_past_rows_only_previews_the_one_it_lands_on() {
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let mut app = app_with_sessions(&[a, b]);
+        app.dispatch(Action::SidebarNext);
+        app.dispatch(Action::SidebarNext);
+
+        let effects = app.poll_due_preview_at(after_gap());
+        assert_eq!(effects, vec![Effect::Attach(b)]);
+        assert_eq!(app.state.preview, Some(b));
+    }
+
+    /// The pane's own session is not something to preview.
+    #[test]
+    fn highlighting_the_attached_session_clears_the_preview() {
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let mut app = app_with_sessions(&[a, b]);
+        app.state.attach_to_focused(a);
+        app.state.focus = Focus::Sidebar;
+
+        app.state.sidebar_highlight = Some(SidebarItem::Session(b));
+        app.refresh_preview();
+        app.poll_due_preview_at(after_gap());
+        assert_eq!(app.state.preview, Some(b));
+
+        app.state.sidebar_highlight = Some(SidebarItem::Session(a));
+        app.refresh_preview();
+        assert_eq!(app.state.preview, None);
+        assert_eq!(app.state.displayed_session(), Some(a));
+    }
+
+    /// Moving off every session — onto a group row, or into the pane — puts
+    /// back what the tab was showing.
+    #[test]
+    fn leaving_the_session_rows_ends_the_preview() {
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let mut app = app_with_sessions(&[a, b]);
+        app.state.attach_to_focused(a);
+        app.state.focus = Focus::Sidebar;
+        app.state.sidebar_highlight = Some(SidebarItem::Session(b));
+        app.refresh_preview();
+        app.poll_due_preview_at(after_gap());
+
+        app.dispatch(Action::FocusPane(crate::action::Direction::Right));
+        assert_eq!(app.state.preview, None);
+        assert_eq!(app.state.displayed_session(), Some(a));
+    }
+
+    /// Committing keeps the stream the preview already opened.
+    #[test]
+    fn attaching_to_a_previewed_session_reuses_its_stream() {
+        let a = Uuid::from_u128(1);
+        let mut app = app_with_sessions(&[a]);
+        app.dispatch(Action::SidebarNext);
+        app.poll_due_preview_at(after_gap());
+        // Stand in for the attach the effect would have opened.
+        app.emulators.insert(a, fake_handle());
+
+        let effects = app.dispatch(Action::AttachHighlighted);
+        assert_eq!(effects, vec![]);
+        assert_eq!(app.state.active_tab().session(), Some(a));
+        assert_eq!(app.state.preview, None);
+        // No longer on loan from the preview budget.
+        assert!(!app.preview_lru.contains(&a));
+    }
+
+    /// Preview-only attaches are kept for a step back, but bounded.
+    #[test]
+    fn preview_attaches_are_dropped_past_the_budget() {
+        let ids: Vec<Uuid> = (1..=(PREVIEW_BUDGET as u128 + 2))
+            .map(Uuid::from_u128)
+            .collect();
+        let mut app = app_with_sessions(&ids);
+        // Each row is previewed in its own gap window, so all of them land.
+        let mut clock = std::time::Instant::now();
+        for id in &ids {
+            app.state.sidebar_highlight = Some(SidebarItem::Session(*id));
+            app.refresh_preview();
+            clock += PREVIEW_GAP + Duration::from_millis(1);
+            app.poll_due_preview_at(clock);
+            app.emulators.insert(*id, fake_handle());
+        }
+
+        assert_eq!(app.preview_lru.len(), PREVIEW_BUDGET);
+        // The oldest rows previewed are gone; the newest are still warm.
+        assert!(app.emulators.get(ids[0]).is_none());
+        assert!(app.emulators.get(*ids.last().unwrap()).is_some());
+    }
+
     /// Seed the catalog with one session and highlight it.
     fn app_with_highlighted_session(sid: Uuid) -> App {
         use chrono::Utc;
@@ -2076,6 +2572,78 @@ mod tests {
         assert!(app.forward_to_session(&InputKey::Enter).is_none());
     }
 
+    /// Drive one key event through an app in Insert mode with a session
+    /// attached, and report the bytes that reached that session.
+    async fn bytes_sent_for(section: &TuiSection, ev: CtEvent) -> Option<Vec<u8>> {
+        use crate::session_task::{SessionHandle, SessionState};
+        use std::sync::atomic::{AtomicU64, AtomicU8};
+        use std::sync::{Arc, Mutex};
+        use tokio::sync::mpsc;
+
+        let sid = Uuid::from_u128(41);
+        let mut app = App::new(
+            TuiConfig::load(section).unwrap(),
+            CatalogStore::default(),
+            DaemonClient::new("http://127.0.0.1:7070"),
+            DaemonLink::default(),
+        );
+        let (tx, mut rx) = mpsc::channel(4);
+        app.emulators.insert(
+            sid,
+            SessionHandle {
+                tx,
+                screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
+                state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+                revision: Arc::new(AtomicU64::new(0)),
+            },
+        );
+        app.state.attach_to_focused(sid);
+        app.state.mode = Mode::Insert;
+        app.state.focus = Focus::Pane;
+        app.handle_event(ev).await.unwrap();
+        match rx.try_recv() {
+            Ok(SessionInput::Bytes(bytes)) => Some(bytes),
+            _ => None,
+        }
+    }
+
+    fn key_event(code: crossterm::event::KeyCode, mods: crossterm::event::KeyModifiers) -> CtEvent {
+        CtEvent::Key(crossterm::event::KeyEvent::new(code, mods))
+    }
+
+    /// Escape belongs to the session: full-screen apps (vim, Claude Code) read
+    /// it constantly, so no Insert-mode default may swallow it. The leader is
+    /// the way back to the sidebar.
+    #[tokio::test]
+    async fn escape_reaches_the_attached_session() {
+        let sent = bytes_sent_for(
+            &TuiSection::default(),
+            key_event(
+                crossterm::event::KeyCode::Esc,
+                crossterm::event::KeyModifiers::NONE,
+            ),
+        )
+        .await;
+        assert_eq!(sent, Some(vec![0x1b]));
+    }
+
+    /// `Noop` suppresses a binding, and in Insert mode a key with no binding is
+    /// the session's — so binding a key to `Noop` hands it to the pty.
+    #[tokio::test]
+    async fn a_noop_insert_binding_forwards_the_key_to_the_session() {
+        let mut section = TuiSection::default();
+        section.keymap_insert.insert("ctrl-a".into(), "Noop".into());
+        let sent = bytes_sent_for(
+            &section,
+            key_event(
+                crossterm::event::KeyCode::Char('a'),
+                crossterm::event::KeyModifiers::CONTROL,
+            ),
+        )
+        .await;
+        assert_eq!(sent, Some(vec![0x01]));
+    }
+
     #[test]
     fn pane_scrollback_moves_and_user_input_returns_to_live_output() {
         use crate::session_task::{SessionHandle, SessionState};
@@ -2091,6 +2659,7 @@ mod tests {
             tx: mpsc::channel(1).0,
             screen: Arc::clone(&screen),
             state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: Arc::new(std::sync::atomic::AtomicU64::new(0)),
         };
         let mut app = make_app();
         app.state.active_tab_mut().pane = Some(sid);

crates/maestro-tui/src/catalog.rs

@@ -87,6 +87,16 @@ impl CatalogStore {
     }
 
     /// Cheap O(sessions) read of current state.
+    /// The version counter alone, without cloning the session list. The render
+    /// loop reads this every tick to decide whether the sidebar is stale.
+    pub fn version(&self) -> u64 {
+        self.inner
+            .state
+            .read()
+            .expect("catalog rwlock poisoned")
+            .version
+    }
+
     pub fn snapshot(&self) -> CatalogSnapshot {
         let s = self.inner.state.read().expect("catalog rwlock poisoned");
         let mut sessions: Vec<Session> = s.sessions.values().cloned().collect();

crates/maestro-tui/src/config.rs

@@ -52,10 +52,11 @@ const DEFAULT_NORMAL: &[(&str, &str)] = &[
     // because Normal mode only exists while the sidebar is focused, so
     // nothing forwards it to a pty.
     ("tab", "AttachHighlighted"),
-    ("s", "OpenSpawnModal"),
-    // Fast-forward spawn (#67): the spawn key's neighbour does the same
+    // `n`/`N`, the same pair the web client binds.
+    ("n", "OpenSpawnModal"),
+    // Fast-forward spawn (#67): the spawn key's shifted twin does the same
     // thing with every default resolved and no form.
-    ("S", "FastForwardSpawn"),
+    ("N", "FastForwardSpawn"),
     ("x", "KillHighlighted"),
     ("r", "RenameHighlighted"),
     // Focus
@@ -74,10 +75,13 @@ const DEFAULT_NORMAL: &[(&str, &str)] = &[
     ("mouse:dblclick(sidebar-row)", "AttachHighlighted"),
 ];
 
-/// Default Insert-mode bindings. The leader (`LeaveInsert`) is inserted
-/// dynamically by [`TuiConfig::load`] so rebinding it rebinds its Insert
-/// escape automatically; `esc` is a second, fixed way back to the sidebar.
-const DEFAULT_INSERT: &[(&str, &str)] = &[("esc", "LeaveInsert")];
+/// Default Insert-mode bindings — deliberately empty. Every key typed in
+/// Insert mode belongs to the session, `esc` included: full-screen apps read
+/// it constantly, so binding it here would make it unreachable. The only way
+/// back to the sidebar is the leader (`LeaveInsert`), which
+/// [`TuiConfig::load`] inserts dynamically so rebinding the leader rebinds
+/// the Insert escape with it.
+const DEFAULT_INSERT: &[(&str, &str)] = &[];
 
 impl TuiConfig {
     /// Build a runtime config from a [`TuiSection`] (typically the `tui`
@@ -220,18 +224,18 @@ mod tests {
             Some(Action::AttachHighlighted),
         );
         assert_eq!(
-            cfg.keymap.resolve(Mode::Normal, "s"),
+            cfg.keymap.resolve(Mode::Normal, "n"),
             Some(Action::OpenSpawnModal),
         );
         assert_eq!(
-            cfg.keymap.resolve(Mode::Normal, "S"),
+            cfg.keymap.resolve(Mode::Normal, "N"),
             Some(Action::FastForwardSpawn),
         );
     }
 
     /// AoE-style defaults (#shortcuts): `q` and `tab` are bare because Normal
     /// mode only exists while the sidebar is focused, so neither can leak
-    /// into a pty; `esc` is a second way out of Insert alongside the leader.
+    /// into a pty; `esc` stays unbound in Insert so it reaches the session.
     #[test]
     fn aoe_style_defaults_are_bound() {
         let cfg = TuiConfig::load(&TuiSection::default()).unwrap();
@@ -240,10 +244,7 @@ mod tests {
             cfg.keymap.resolve(Mode::Normal, "tab"),
             Some(Action::AttachHighlighted),
         );
-        assert_eq!(
-            cfg.keymap.resolve(Mode::Insert, "esc"),
-            Some(Action::LeaveInsert),
-        );
+        assert_eq!(cfg.keymap.resolve(Mode::Insert, "esc"), None);
     }
 
     #[test]
@@ -311,18 +312,18 @@ mod tests {
         assert!(s.contains("ctrl-glorb"), "diagnostic: {s}");
     }
 
-    /// Regression for #70: the previous canonical form of a real Shift+S
-    /// keypress was `"shift-S"`, which the default `"S"` binding never
+    /// Regression for #70: the previous canonical form of a real Shift+N
+    /// keypress was `"shift-N"`, which the default `"N"` binding never
     /// matched. Drive the actual crossterm event, not the binding string,
     /// so the dead-key bug can't come back unnoticed.
     #[test]
-    fn real_shift_s_keypress_resolves_to_fast_forward_spawn() {
+    fn real_shift_n_keypress_resolves_to_fast_forward_spawn() {
         use crossterm::event::{Event as CtEvent, KeyCode, KeyEvent, KeyModifiers};
 
         use crate::input::{canonicalise, Region};
 
         let cfg = TuiConfig::load(&TuiSection::default()).unwrap();
-        let ev = CtEvent::Key(KeyEvent::new(KeyCode::Char('S'), KeyModifiers::SHIFT));
+        let ev = CtEvent::Key(KeyEvent::new(KeyCode::Char('N'), KeyModifiers::SHIFT));
         let key = canonicalise(&ev, |_, _| Region::Unknown).expect("key event canonicalises");
 
         assert_eq!(

crates/maestro-tui/src/emulators.rs

@@ -168,6 +168,7 @@ mod tests {
             tx: mpsc::channel(1).0,
             screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
             state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: Arc::new(std::sync::atomic::AtomicU64::new(0)),
         };
         emulators.insert(id, handle);
         assert!(emulators.get(id).is_some());

crates/maestro-tui/src/input.rs

@@ -597,7 +597,8 @@ mod tests {
     /// so a real Shift+S delivers `Char { c: 'S', shift: true }`. Its
     /// canonical form must be the bare `"S"` a keymap binds, not `"shift-S"` —
     /// the uppercase letter already says "shifted"; a redundant prefix would
-    /// make the default `S` binding unreachable from the keyboard (#70).
+    /// make every uppercase binding (the default `N`) unreachable from the
+    /// keyboard (#70).
     #[test]
     fn shift_flag_is_redundant_for_an_already_uppercase_char() {
         let k = InputKey::Char {

crates/maestro-tui/src/lib.rs

@@ -24,6 +24,7 @@ pub mod state;
 pub mod terminal;
 pub mod text_input;
 
+use std::io::BufWriter;
 use std::path::PathBuf;
 use std::time::Duration;
 
@@ -121,13 +122,23 @@ pub async fn run(cfg: RunConfig) -> Result<(), TuiError> {
     let _guard = terminal::TerminalGuard::enter().map_err(|e| match e {
         terminal::TerminalError::Io(io) => TuiError::Terminal(io.to_string()),
     })?;
-    let backend = CrosstermBackend::new(std::io::stdout());
+    // Buffered: ratatui issues one `write!` per cell run — thousands per
+    // frame — and an unbuffered `Stdout` takes the global stdout lock on every
+    // one of them. A single BufWriter collapses a frame into one flush.
+    let backend = CrosstermBackend::new(BufWriter::with_capacity(
+        FRAME_BUFFER_BYTES,
+        std::io::stdout(),
+    ));
     let mut terminal = Terminal::new(backend).map_err(|e| TuiError::Terminal(e.to_string()))?;
 
     let app = App::new(tui_cfg, catalog, daemon, link);
     app.run(&mut terminal).await
 }
 
+/// One full 200x50 repaint is ~5 KB of escape sequences; 64 KB leaves room for
+/// a large terminal without ever flushing mid-frame.
+const FRAME_BUFFER_BYTES: usize = 64 * 1024;
+
 /// Startup probe budget, applied to connect *and* the whole request: the user is
 /// staring at a terminal, so an unreachable daemon must fail in under a second.
 const HEALTH_TIMEOUT: Duration = Duration::from_millis(500);

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/session_task.rs

@@ -14,7 +14,7 @@
 //!   parser is **not** reset on reconnect — the last-known frame stays
 //!   visible until new bytes arrive, so the user doesn't see a blank.
 
-use std::sync::atomic::{AtomicU8, Ordering};
+use std::sync::atomic::{AtomicU64, AtomicU8, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
@@ -56,11 +56,15 @@ pub enum SessionState {
 ///   here.
 /// - `state` — `Arc<AtomicU8>`: live status of the WS, queryable without
 ///   holding the screen lock.
+/// - `revision` — `Arc<AtomicU64>`: bumped every time the parser's screen is
+///   mutated. The render loop compares it against the last drawn frame's so an
+///   idle pane costs a `load` instead of a repaint.
 #[derive(Clone)]
 pub struct SessionHandle {
     pub tx: mpsc::Sender<SessionInput>,
     pub screen: Arc<Mutex<vt100::Parser>>,
     pub(crate) state: Arc<AtomicU8>,
+    pub(crate) revision: Arc<AtomicU64>,
 }
 
 impl std::fmt::Debug for SessionHandle {
@@ -81,6 +85,12 @@ impl SessionHandle {
         }
     }
 
+    /// Monotonic counter of screen mutations. Only equality across two reads
+    /// is meaningful — the loop uses it to decide whether a frame is stale.
+    pub fn revision(&self) -> u64 {
+        self.revision.load(Ordering::Acquire)
+    }
+
     /// Stop the underlying task. Used when the pane closes and the user has
     /// no other tabs pointing at this session.
     pub fn end(&self) {
@@ -109,9 +119,11 @@ impl SessionTask {
         let (tx, mut rx) = mpsc::channel::<SessionInput>(64);
         let parser = Arc::new(Mutex::new(vt100::Parser::new(rows, cols, SCROLLBACK_ROWS)));
         let state = Arc::new(AtomicU8::new(SessionState::Connecting as u8));
+        let revision = Arc::new(AtomicU64::new(0));
 
         let parser_bg = parser.clone();
         let state_bg = state.clone();
+        let revision_bg = revision.clone();
 
         tokio::spawn(async move {
             let url = ws_url;
@@ -151,6 +163,7 @@ impl SessionTask {
                                 }
                                 SessionInput::Resize { cols, rows } => {
                                     parser_bg.lock().expect("vt100 parser mutex").set_size(rows, cols);
+                                    revision_bg.fetch_add(1, Ordering::Release);
                                     let frame = serde_json::to_string(&ClientControl::Resize {
                                         cols,
                                         rows,
@@ -166,6 +179,7 @@ impl SessionTask {
                             match frame {
                                 Some(Ok(Message::Binary(bytes))) => {
                                     parser_bg.lock().expect("vt100 parser mutex").process(&bytes);
+                                    revision_bg.fetch_add(1, Ordering::Release);
                                 }
                                 Some(Ok(Message::Text(text))) => {
                                     // Ping/Pong control frames travel as text JSON. Reply to Ping.
@@ -202,6 +216,7 @@ impl SessionTask {
             tx,
             screen: parser,
             state,
+            revision,
         }
     }
 }
@@ -228,6 +243,7 @@ mod tests {
             tx: mpsc::channel(1).0,
             screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
             state: Arc::new(AtomicU8::new(SessionState::Connecting as u8)),
+            revision: Arc::new(AtomicU64::new(0)),
         };
         assert_eq!(h.state(), SessionState::Connecting);
     }
@@ -238,8 +254,26 @@ mod tests {
             tx: mpsc::channel(1).0,
             screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
             state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: Arc::new(AtomicU64::new(0)),
         };
         h.end();
         assert_eq!(h.state(), SessionState::Ended);
     }
+
+    #[test]
+    fn revision_starts_at_zero_and_tracks_screen_mutations() {
+        let revision = Arc::new(AtomicU64::new(0));
+        let h = SessionHandle {
+            tx: mpsc::channel(1).0,
+            screen: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
+            state: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: revision.clone(),
+        };
+        assert_eq!(h.revision(), 0);
+
+        // Stands in for the WS pump: process bytes, then bump.
+        h.screen.lock().unwrap().process(b"hello");
+        revision.fetch_add(1, Ordering::Release);
+        assert_eq!(h.revision(), 1);
+    }
 }

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,
@@ -520,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!(
@@ -544,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"));
@@ -555,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());
@@ -566,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();
@@ -590,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]);
@@ -620,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"));
@@ -635,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");
@@ -645,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");
@@ -653,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);
@@ -681,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));
 
@@ -727,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();
@@ -759,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();
@@ -785,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");
@@ -816,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();
@@ -855,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)
@@ -883,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| {
@@ -922,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();
@@ -941,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]);
@@ -969,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();
@@ -998,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();
@@ -1025,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();
@@ -1053,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();
@@ -1086,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!(
@@ -1128,6 +1269,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let rendered = render_to_string(&draw(&sb, 28, 6));
         assert!(
@@ -1143,6 +1285,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 40, 6));
         assert!(
@@ -1164,6 +1307,7 @@ mod tests {
             sessions: vec![s],
             highlight: None,
             attached: Default::default(),
+            pane_session: None,
         };
         let all = rows(&draw(&sb, 9, 6));
         assert!(
@@ -1190,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]);
@@ -1214,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]);
@@ -1235,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 {
@@ -1260,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);
@@ -1295,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)
@@ -1314,6 +1463,7 @@ mod tests {
                 sessions: vec![session_named(1, "claude")],
                 highlight: None,
                 attached: Default::default(),
+                pane_session: None,
             },
             28,
             8,
@@ -1334,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;
@@ -1352,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"));
@@ -1369,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");
@@ -1388,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");

crates/maestro-tui/src/state.rs

@@ -63,6 +63,11 @@ pub struct AppState {
     pub mode: Mode,
     pub sidebar_visible: bool,
     pub sidebar_highlight: Option<SidebarItem>,
+    /// The session the pane is *previewing* (`docs/PREVIEW.md`): shown because
+    /// the sidebar highlight is on it, not because a tab holds it. It never
+    /// enters `tabs`, is never reported to the daemon as focused, and is
+    /// dropped the moment the highlight moves on.
+    pub preview: Option<Uuid>,
     /// Group paths whose cards are hidden. This is UI state rather than
     /// catalog state, so it survives every catalog redraw.
     pub collapsed_sidebar_groups: HashSet<PathBuf>,
@@ -91,6 +96,7 @@ impl AppState {
             mode: Mode::Normal,
             sidebar_visible: true,
             sidebar_highlight: None,
+            preview: None,
             collapsed_sidebar_groups: HashSet::new(),
             overlay: None,
         }
@@ -126,6 +132,9 @@ impl AppState {
     /// drop straight into Insert mode so keystrokes go to the session
     /// without an extra `i` press. The leader returns to Normal.
     pub fn attach_to_focused(&mut self, session_id: Uuid) {
+        // Committing to what was previewed: the pane owns it now, so the
+        // preview has nothing left to say.
+        self.preview = None;
         self.active_tab_mut().pane = Some(session_id);
         self.focus = Focus::Pane;
         self.mode = Mode::Insert;
@@ -150,6 +159,13 @@ impl AppState {
         self.active_tab().session()
     }
 
+    /// What the pane actually draws: the preview when one is up, otherwise the
+    /// active tab's session. A preview covers the pane without replacing it,
+    /// so ending one gives back exactly what was there (`docs/PREVIEW.md`).
+    pub fn displayed_session(&self) -> Option<Uuid> {
+        self.preview.or_else(|| self.active_session())
+    }
+
     /// Move the sidebar highlight one step through the rendered item
     /// sequence, in the direction of `delta` (positive = down), landing only
     /// on items `is_stop` accepts. Only the sign of `delta` matters. Wraps.

docs/COMMAND-BAR.md

@@ -0,0 +1,479 @@
+# COMMAND-BAR.md — the command bar contract
+
+One rule for the `ctrl-k` command bar in both clients, so the web bar and the
+TUI bar open the same way, rank the same results in the same order, and act on
+the same keys. Read this before changing either. Both clients implement exactly
+what is written here; if the behaviour needs to change, change it here first.
+
+The bar is one surface with three jobs: **go to a session**, **run a command**,
+**spawn into a directory**. It is not a new place to configure anything and it
+does not own any action — it chooses one and hands off to the flow that already
+implements it.
+
+## Opening
+
+`ctrl-k` opens the bar from anywhere:
+
+| Client | From | Notes |
+| --- | --- | --- |
+| TUI | Normal mode | Sidebar has the keyboard. |
+| TUI | Insert mode | The pane has the keyboard; the bar still opens. |
+| Web | Sidebar focused | Ordinary global binding. |
+| Web | Terminal focused | Intercepted before xterm sees it. |
+
+It is a **keymap entry like any other**, not a hard-wired key. In the TUI it is
+bound in both `DEFAULT_NORMAL` and `DEFAULT_INSERT` and is rebindable through
+`[tui.keymap.*]`; because the help overlay builds its lines from the live
+keymap, it appears there without a second list to maintain. In the web it is an
+entry in the command registry, so the `?` overlay lists it for the same reason.
+
+An attached xterm swallows every keystroke it is given, so the web binding is
+handled in the **capture phase**, ahead of the terminal — the same way the
+restart overlay swallows the app's shortcuts (`docs/RESTART.md`).
+
+### Escape hatch — sending a literal Ctrl-K
+
+Binding `ctrl-k` takes readline's kill-to-end-of-line away from every pane. The
+leader gives it back: **leader then `ctrl-k`** — `ctrl-a ctrl-k` by default —
+sends the literal `0x0B` byte to the focused pane and does not open the bar.
+
+The TUI already has a leader (`ctrl-a`, `[tui].leader`), and this chord goes
+through the existing chord resolution, so rebinding the leader rebinds the
+escape hatch with it — exactly as the leader's Insert-mode escape already
+works. **The web gains a leader for this**, defaulting to `ctrl-a` and
+mirroring the TUI's. `ctrl-a` is select-all in a browser; the web
+`preventDefault`s it, since selecting all of a terminal pane does nothing
+useful.
+
+Only Ctrl-K gets an escape hatch. No other control character is intercepted, so
+none of them needs one.
+
+### Focus round-trip
+
+Closing the bar returns the keyboard to whatever held it when the bar opened,
+the terminal included. A round trip through the bar never silently moves focus,
+and never counts as a focus change for the daemon: opening the bar does not
+report the pane unfocused, and closing it does not report a new focus. The bar
+is a view over the app, not a place in it.
+
+Opening the bar while a session is previewed (`docs/PREVIEW.md`) discards the
+preview first, like any other real change; the bar is not previewed into.
+
+## Structure
+
+The bar is a query line over a result list. By default the list is **flat and
+mixed** — sessions and commands ranked together — and rendered under **kind
+headers**: a header row naming the kind, then that kind's results.
+
+Grouping is a rendering of the ranking, never a reordering of it:
+
+- Results are ranked as one list by the algorithm below.
+- A kind's group holds its matches in that rank order.
+- **Groups are ordered by their best-scoring member.** The first row under the
+  first header is therefore the globally best result, and the highlight starts
+  on it.
+
+Two sigils, typed as the **first character** of the query, narrow the list to
+one kind:
+
+| Sigil | Kind | Candidates | Enter |
+| --- | --- | --- | --- |
+| `>` | commands | Every entry in the client's command registry — the web registry from the `?` overlay, the TUI's live `(chord, Action)` keymap for the current mode. | Runs the command. |
+| `~` | directories | Recent dirs (`GET /api/recent-dirs`) and the project list the spawn form already uses, with `GET /api/dirs` filling in as a path is typed. | Spawns a session there with every default resolved. |
+
+While a sigil is in force there is one kind, so the kind header is dropped. A
+command row shows its **key chord** beside its label, so the bar teaches the
+keymap instead of replacing it. A `~` spawn takes the same fast-forward path as
+`N` / `FastForwardSpawn`: an unresolvable default opens the pre-filled spawn
+form rather than failing silently.
+
+**Backspacing past a sigil returns to the mixed list.** The sigil is one
+character of the query like any other — deleting it is not a special key, it is
+the query becoming empty again.
+
+The sigil is only a sigil in first position. `>` or `~` typed anywhere else is
+a literal query character (a directory query is where a `~` is most likely to
+be typed twice, and the second one must reach the matcher).
+
+## Empty query
+
+With no sigil and an empty query the bar lists **sessions only, most recently
+focused first**, so `ctrl-k enter` is "back to where I just was". Commands and
+directories need a sigil or a query to appear; an empty bar is a session
+switcher.
+
+**Recency comes from the daemon**, not from client state — the same order in
+every client, on every device, including one that just loaded the page. The
+daemon stamps a last-focused time per session and ships it on the session like
+any other field (#145). Both of the ways focus moves stamp the same field: a
+client opening `/api/attach/:id`, and a client reporting focus explicitly at
+`POST /api/sessions/:id/focus` when it refocuses a pane that is already open.
+
+**A session that has never been focused sorts after every session that has**,
+and among those, most recently created first. Dead sessions sort after live
+ones regardless of recency: a session you cannot attach to is not where you
+just were.
+
+Under `>` an empty query lists every command in registry order. Under `~` it
+lists recent dirs, most recent first, then the project list.
+
+## Keys
+
+| Key | Action |
+| --- | --- |
+| `enter` | Open the highlighted result — attach the session, run the command, spawn into the directory. |
+| `tab` | Drill into the highlighted **session**'s action page. No effect on any other kind. |
+| `esc` | At the top level, close the bar. On an action page, return to the result list. |
+| `backspace` | Ordinary editing; at an empty query on an action page, return to the result list. |
+| `up` / `down` | Move the highlight. |
+| `ctrl-p` / `ctrl-n` | Move the highlight. |
+
+The highlight does not wrap: it stops at the first and last row. Kind headers
+are never landed on — they are labels, not rows.
+
+Enter on a session goes through the **same open path** the sidebar's click and
+the hash router already share, so a bar attach can never leave the layout in a
+state a click could not produce.
+
+### Drill-in — the session action page
+
+`tab` on a highlighted session opens that session's action page inside the same
+overlay: **kill**, **rename**, **spawn similar**. The page is still fuzzy
+searchable — the query line keeps working, now over those actions.
+
+- The overlay names the session being acted on, so the target is never
+  ambiguous.
+- Escape, or backspace at an empty query, returns to the result list **with the
+  previous query intact**. Drilling in and backing out is free.
+- Each action raises the flow it already has: kill goes through the existing
+  confirm-and-blockers dialog (`docs/WORKTREES.md`), rename through the
+  existing prompt pre-filled with the session's own name
+  (`docs/SIDEBAR.md`), spawn similar through the spawn form seeded from the
+  session's directory and command. The bar picks the action; it never
+  reimplements one.
+
+No actions beyond those three, and no action across more than one session.
+
+## Touch entry
+
+On the web, **tapping or focusing the sidebar's search field opens the bar**
+with an empty query. There is no `ctrl-k` on a phone and the product is
+mobile-first, so the field the operator already reaches for is the entry point.
+
+This **replaces** the sidebar's inline substring filter — one search affordance
+in the header, not two beside each other. The tree's "No matches" empty state
+belonged to that filter and goes with it; the bar's own no-results state takes
+over (see the fixture `F4`).
+
+At phone width the bar follows the bottom-sheet treatment the spawn modal
+already uses below 600px. Visuals otherwise come from `DESIGN.md`'s existing
+overlay tokens — the bar is the same family of surface as the spawn modal and
+the help overlay, not a new one.
+
+## What a candidate is
+
+The matcher is a pure function: `(query, candidates) → ranked subset with
+matched ranges`. It knows nothing about sessions, panes or the network. A
+candidate is a **kind** plus a set of **named text fields**, each with a fixed
+weight.
+
+| Kind | Field | Weight | Text |
+| --- | --- | --- | --- |
+| session | `name` | `0` | The name as the sidebar shows it: `metadata.name` if set, else the command line (`docs/SIDEBAR.md`'s fallback). |
+| session | `directory` | `-24` | The directory the sidebar groups it under, abbreviated: `~/dev/api`, not `/home/me/dev/api`. |
+| session | `command` | `-32` | The full command line, arguments included. |
+| session | `tool` | `-40` | The tool id the card's icon stands for (`claude`, `codex`, `opencode`, …), absent when the program is not one we have a mark for. |
+| command | `label` | `0` | The plain-language label — the web registry's label, the TUI's `Action::help_label`. |
+| directory | `path` | `0` | The path as displayed, abbreviated the same way. |
+
+A command's **key chord is displayed, not matched**. It is there to teach the
+keymap; matching it would make `>` results depend on a user's rebinds, and the
+two clients do not share a keymap.
+
+A candidate **matches** if at least one of its fields matches. Its score is the
+**best** `field score + field weight` across its fields, and the matched ranges
+it returns are those of that winning field — so a session found through its
+directory highlights inside the directory, not inside its name.
+
+## Match and rank
+
+Two independent implementations (#146 in TypeScript, #147 in Rust) must produce
+the same order for the same input. Everything below is exact.
+
+### Normalization
+
+- **Query**: lowercase, then remove every whitespace character. The result is
+  the *normalized query*. If it is empty, see "Empty query" below.
+- **Field text**: matched against its lowercased form. Bonuses are computed
+  against the **original** text, because case is a signal (`camelCase`) that
+  lowercasing destroys.
+- **Compact form** of a string: lowercase with whitespace removed. Used only
+  for the exact and prefix tests.
+
+Lowercasing is per-character simple lowercase (`char::to_lowercase` /
+`String.prototype.toLowerCase`). Positions are **character** positions —
+Unicode scalar values in Rust, UTF-16 code units in TypeScript, which agree for
+every character these fields realistically hold; ranges are returned in the
+host language's own unit, since they exist to slice that language's string.
+
+### What a match is
+
+Case-insensitive **subsequence**: every character of the normalized query
+appears in the lowercased field text, in order, not necessarily adjacent. A
+field with no such embedding does not match.
+
+### Word boundaries
+
+A matched character at position `p` earns exactly one character bonus, taking
+the first rule that applies:
+
+| Rule | Bonus |
+| --- | --- |
+| `p == 0` — first character of the field | `+18` |
+| The character before it is a **separator**: `/` `\` `-` `_` `.` `:` or a space | `+16` |
+| It is uppercase and the character before it is lowercase (a camelCase hump) | `+12` |
+| It is a digit and the character before it is not | `+12` |
+| Otherwise | `0` |
+
+That is one rule for both shapes the doc has to cover. In a **path**, `/` is a
+separator, so the first character of every segment is a word start: `foo` in
+`~/dev/foobar` starts a segment and outscores `foo` in `~/src/myfoo`, which
+starts nothing. In a **session name**, `-`, `_`, `.` and spaces do the same
+work, so `ws` reaches `web-search` more cheaply than `websearch`.
+
+### Score
+
+Let the query characters be matched at positions `p₀ < p₁ < … < pₘ₋₁`, and let
+`p₋₁ = -1`. For each matched character `i`, with `gap = pᵢ - pᵢ₋₁ - 1`:
+
+```
+contribution(i) = 16                      // every matched character
+                + bonus(pᵢ)               // the table above
+                + (gap == 0 ? +8          // adjacent to the previous match
+                            : -min(gap, 12))
+```
+
+`gap` for `i = 0` is the number of characters skipped before the first match, so
+a match that starts late is penalised exactly like an internal gap, and the cap
+is the same one.
+
+The **field score** is the sum of the contributions, plus at most one whole-field
+adjustment:
+
+- compact field text **equals** the normalized query → `+64`
+- else compact field text **starts with** the normalized query → `+32`
+
+Length is deliberately not in the score — it is a tie-break, so a long field
+never loses to a short one that matched worse.
+
+### Which embedding
+
+A query can sit in a field many ways. The one that counts is the
+**highest-scoring** embedding; among embeddings that score the same, the
+**leftmost** — compare position vectors element by element, smaller wins.
+
+Greedy leftmost-first matching is not sufficient and must not be used: in
+`maestro-tui`, `mtu` greedily takes `m₀ a₁ …` and never reaches `tui`. Both
+implementations use the obvious dynamic program over
+`(query index, text position)`, carrying the best score and its position
+vector, since the gap term depends only on the previous matched position.
+
+The whole-field adjustment is constant for a `(query, field)` pair, so adding it
+after the dynamic program cannot change which embedding wins.
+
+### Ordering
+
+Sort by score, highest first. Equal scores break in this order:
+
+1. **Kind** — `session`, then `command`, then `directory`.
+2. **Length of the matched field text**, shorter first.
+3. **The matched field text**, ascending, compared by code point, case
+   sensitive.
+4. **Input order.** The sort is stable, so candidates the caller ordered
+   deliberately — sessions most recently focused first, commands in registry
+   order — keep that order when nothing else separates them.
+
+Kind leads because that is the ruling the ambiguous cases need: a session named
+`kill` and the `kill` command that score alike put the session first, because
+the operator who typed a session's name meant the session.
+
+### Empty query
+
+A normalized query that is empty **matches every candidate**, each with score
+`0` and no ranges, in input order. The bar's own rules decide what is in the
+candidate list at that point (sessions only at the top level); the matcher does
+not filter by kind.
+
+## Fixtures
+
+These are the contract. Both matchers are tested against exactly these cases;
+the prose above is the explanation of why they come out this way.
+
+Candidates are written as `kind(fields)`; unlisted fields are absent.
+`session(name, dir, command, tool)`. Scores are shown for diagnosis — **the
+order is what is being asserted**, and an implementation that ranks correctly
+with different absolute numbers has still failed, because the numbers are how
+the next fixture stays predictable.
+
+### F1 — empty query keeps input order
+
+```
+query:      ""
+candidates: session("kill", "~/dev/api", "bash")
+            session("killer-app", "~/dev/killer-app", "claude --resume", "claude")
+            command("Kill selected session")
+expected:   session("kill")           score 0
+            session("killer-app")     score 0
+            command("Kill selected session")  score 0
+```
+
+Every candidate matches, in the order given. No ranges.
+
+### F2 — a session named `kill` against the `kill` command
+
+```
+query:      "kill"
+candidates: (as F1)
+expected:   session("kill")                   178   name
+            session("killer-app")             146   name
+            command("Kill selected session")  146   label
+```
+
+`kill` wins on the exact bonus. The other two **tie at 146** — both are a
+contiguous prefix match — and the kind tie-break puts the session first.
+
+### F3 — a fragment matching mid-segment inside a path
+
+```
+query:      "foo"
+candidates: directory("~/dev/foobar")
+            directory("~/src/myfoo")
+            directory("~/foo")
+expected:   directory("~/foo")         78   ranges [2,3,4]
+            directory("~/dev/foobar")  74   ranges [6,7,8]
+            directory("~/src/myfoo")   56   ranges [8,9,10]
+```
+
+The first two start a path segment; the third is mid-segment and loses by the
+whole boundary bonus. `~/foo` beats `~/dev/foobar` only because less was
+skipped before the match.
+
+### F4 — a query matching nothing
+
+```
+query:      "zzz"
+candidates: session("kill", "~/dev/api", "bash")
+            command("Kill selected session")
+expected:   (empty)
+```
+
+The matcher returns an empty list, never a list of zero-scored candidates. The
+bar renders its no-results state.
+
+### F5 — a non-contiguous subsequence
+
+```
+query:      "mtu"
+candidates: session("maestro-tui")
+            session("maestro-daemon")
+            session("mtui-scratch")
+expected:   session("mtui-scratch")  122   ranges [0,1,2]
+            session("maestro-tui")    91   ranges [0,8,9]
+```
+
+`maestro-daemon` has no `u` after its `t` and does not match. `maestro-tui`
+does, across a gap — which greedy matching would miss entirely.
+
+### F6 — a name beats a directory
+
+```
+query:      "api"
+candidates: session("api", "~/dev/web", "bash")
+            session("worker", "~/dev/api", "bash")
+expected:   session("api")     154   name
+            session("worker")   50   directory
+```
+
+The second session is found through its directory, and highlights there.
+
+### F7 — case-insensitive, tie broken by length
+
+```
+query:      "api"
+candidates: session("API-Gateway")
+            session("apiary")
+expected:   session("apiary")       122   name
+            session("API-Gateway")  122   name
+```
+
+Both are prefix matches and score identically. Same kind, so length decides:
+6 characters before 11. Input order does not save `API-Gateway`.
+
+### F8 — the tool field
+
+```
+query:      "claude"
+candidates: session("nameless", "~/dev/x", "claude --resume", "claude")
+            session("clay", "~/dev/y", "bash")
+expected:   session("nameless")  186   tool
+```
+
+`clay` has no `claude` subsequence anywhere and drops out. `nameless` matches
+its `tool` exactly (`+64`, weight `-40`, giving 186) which beats the prefix
+match on its `command` field (`+32`, weight `-32`, giving 162).
+
+### F9 — a word boundary inside a session name
+
+```
+query:      "ws"
+candidates: session("websearch")
+            session("web-search")
+expected:   session("web-search")  71   ranges [0,4]
+            session("websearch")   56   ranges [0,3]
+```
+
+The `s` after `-` earns the boundary bonus; the `s` inside `websearch` earns
+nothing.
+
+### F10 — command labels
+
+```
+query:      "se"
+candidates: command("Kill selected session")
+            command("Create a session")
+            command("Show help")
+expected:   command("Show help")             53   ranges [0,6]
+            command("Kill selected session") 51   ranges [5,6]
+            command("Create a session")      47   ranges [9,10]
+```
+
+`Show help` starts at position 0; the other two start at a word boundary but
+later, and pay for the skipped characters.
+
+### F11 — a query against session directories
+
+```
+query:      "dev"
+candidates: session("api", "~/dev/api", "bash")
+            session("notes", "~/documents/dev-notes", "nvim")
+            session("scratch", "~/srv/devops", "bash")
+expected:   session("api")      54   directory, ranges [2,3,4]
+            session("scratch")  50   directory, ranges [6,7,8]
+            session("notes")    44   directory, ranges [12,13,14]
+```
+
+All three start a path segment. They separate purely on how much was skipped
+first, and `notes` hits the `-12` gap cap.
+
+### F12 — exact beats prefix
+
+```
+query:      "quit"
+candidates: command("Quit Maestro")
+            command("Quit")
+expected:   command("Quit")           178   label
+            command("Quit Maestro")   146   label
+```
+
+The 32-point difference between the exact and prefix adjustments is the whole
+gap; nothing else about the two matches differs.

docs/INSTALL.md

@@ -141,7 +141,8 @@ chord_timeout_ms = 1000      # how long to hold a partial chord like `ctrl-w`
 
 [tui.keymap.normal]
 "i"            = "EnterInsert"
-"s"            = "OpenSpawnModal"
+"n"            = "OpenSpawnModal"
+"N"            = "FastForwardSpawn"
 "x"            = "KillHighlighted"
 "r"            = "RenameHighlighted"
 "?"            = "ShowHelp"

docs/PREVIEW.md

@@ -0,0 +1,102 @@
+# PREVIEW.md — the sidebar preview contract
+
+One rule for what the content pane shows while the operator is only moving
+around the sidebar, so the web client and the TUI behave the same. Read this
+before changing either. If the behaviour needs to change, change it here first.
+
+## The rule
+
+Highlighting a session in the sidebar shows that session in the content pane,
+as if it were focused, **without focusing it and without changing the layout**.
+Moving the highlight elsewhere puts back exactly what was on screen before.
+
+A preview is a view, not a state. Nothing about it is durable:
+
+- The layout is byte-for-byte identical before the preview and after it ends.
+- Nothing is persisted while a preview is up (the web client's layout is saved
+  to `localStorage`; a preview never reaches it).
+- The daemon is never told the previewed pane is focused, so a preview never
+  clears a session's `AwaitingInput` glow (`docs/SIDEBAR.md`).
+- The keyboard stays in the sidebar: the previewed terminal is on screen but
+  does not take focus, so the next `j`/`k` still walks the list.
+
+## Where the preview is shown
+
+| The previewed session is… | What happens |
+|---|---|
+| Already in a pane, in the active tab | That pane comes forward (its tab's focus moves to it). |
+| Already in a pane, in another tab | That tab is brought forward. The active tab is restored when the preview ends. |
+| Not in any pane | A throwaway tab carries it. It is removed when the preview ends. |
+
+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.
+- The highlight leaves every session (a folder row, or the list losing the
+  keyboard, or the pointer leaving the list): the previous view comes back.
+- Any real layout change (split, close, new tab, tab switch, drag): the preview
+  is discarded first, so a throwaway tab is never baked into the arrangement.
+
+## What commits a preview
+
+Choosing the previewed session — clicking or pressing Enter on its row,
+clicking into its pane, or handing the keyboard to the pane (web: `Tab` from
+the list; TUI: the attach binding) — keeps exactly what is on screen. A
+throwaway tab becomes a real one; a focus move inside an existing tab stands.
+Nothing moves a second time on commit.
+
+## Timing
+
+**A preview is never delayed.** Landing on a row — by pointer or by `j`/`k` —
+shows it on the next frame, and so does leaving every row. There is no
+settling period in front of the first preview, because that period would sit
+in front of the one preview the operator actually meant.
+
+What is bounded is how *often* the pane may swap: at most once per 120 ms.
+A burst inside one window — `j` held down, or the pointer sweeping the length
+of the sidebar — shows the row it started on, then the row it ended on, and
+none of the rows in between. So a walk costs a couple of pane mounts rather
+than one per row, without the operator ever waiting on one.
+
+The highlight itself is not bounded by any of this: the row lights up on the
+same frame as the input, whatever the pane behind it is doing.
+
+Touch has no hover, and a tap already opens a session, so touch never previews.
+
+## Cost
+
+A previewed session that no pane holds needs a live attach. Both clients keep
+it connected after the preview ends — the web client parks it in the connection
+pool's LRU, the TUI keeps its emulator until it falls out of the preview
+budget — so stepping back onto a row is instant rather than re-fetching
+scrollback.

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
@@ -234,7 +266,7 @@ the agent, and answering 204 would hide it.
 
 A session's pane — the pane a client's own attach view is showing, never a
 sidebar highlight — clears its `AwaitingInput` glow once it has been
-**continuously focused for 5 seconds**: the operator has looked, so the rail
+**continuously focused for 1 second**: the operator has looked, so the rail
 stops asking for attention and the card reads as `Idle` instead. This is a
 real state change, not a client-side paint-over — the daemon computes it, so
 every client watching the session (web, TUI, a second pane on the same
@@ -274,3 +306,21 @@ than jumping to the end of the list.
 The web client needs a chord to reach the list at all (`Ctrl+Shift+H`, and the
 same chord back): an attached terminal owns every plain keystroke. The TUI uses
 `ctrl-w h`.
+
+Everything else is the same key on both clients:
+
+| key     | action                                      |
+|---------|---------------------------------------------|
+| `j`/`k` | move the highlight (arrows too)             |
+| `Enter` | open the session, or expand the folder      |
+| `Tab`   | hand the keyboard to the pane               |
+| `c`     | collapse or expand the highlighted folder   |
+| `r`     | rename the highlighted session              |
+| `x`     | kill the highlighted session                |
+| `n`     | open the spawn form                         |
+| `N`     | spawn with every default resolved           |
+| `?`     | show the shortcut overlay                   |
+
+The TUI binds these through its keymap, so a user can rebind any of them; the
+web client's are fixed. A binding added to one client belongs in this table and
+in both help overlays.

flake.nix

@@ -148,7 +148,7 @@
             pnpmDeps = (pkgs.fetchPnpmDeps.override { pnpm = pkgs.pnpm_10; }) {
               inherit (finalAttrs) pname version src;
               fetcherVersion = 3;
-              hash = "sha256-AvIrpXipbcp7hRujh/L4UAc6tAJOxe67P/iji6L/oL0=";
+              hash = "sha256-hOqiAbnjKsoQnV8lgto5HspDsLIb+48sNLkShIjCZPQ=";
             };
 
             buildPhase = ''
@@ -218,8 +218,8 @@
             settings = {
               # `nix run .#dev` works from a bare shell, not only from inside
               # `nix develop`, so the toolchain is put on PATH here rather than
-              # inherited. `/usr/bin:/bin` stays last for anything else a
-              # spawned session reaches for.
+              # inherited. This covers the build and Vite; the daemon widens it
+              # further for the sessions it spawns (see `daemon.command`).
               environment = [
                 "PATH=${lib.makeBinPath devTools}:/usr/bin:/bin"
                 # Not :7070: that is the daemon's own default, and the dev
@@ -241,7 +241,17 @@
                   # `environment`. A tmux socket of its own keeps dev sessions
                   # out of — and safe from — the tmux server belonging to
                   # whatever daemon the developer actually runs.
+                  #
+                  # A spawned session inherits the daemon's PATH, and the
+                  # toolchain PATH above holds build tools only — on NixOS the
+                  # trailing `/usr/bin:/bin` is all but empty, so every session
+                  # opened from the dev UI came up unable to find `claude`,
+                  # `zsh` or anything else the developer actually has. Append
+                  # the usual user profile directories so dev sessions behave
+                  # like real ones. Resolved by the shell at run time; the ones
+                  # that do not exist on a given host cost nothing.
                   command = ''
+                    PATH="$PATH:$HOME/.nix-profile/bin:/etc/profiles/per-user/$(id -un)/bin:/run/current-system/sw/bin:/usr/local/bin" \
                     MAESTRO_DAEMON_TMUX_TMPDIR="$PWD/.dev/tmux" \
                     RUST_LOG="''${RUST_LOG:-maestro=debug,info}" \
                       target/debug/maestro daemon

web/package.json

@@ -15,6 +15,7 @@
   "dependencies": {
     "@fontsource/jetbrains-mono": "^5.3.0",
     "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-webgl": "^0.19.0",
     "@xterm/xterm": "^5.5.0"
   },
   "devDependencies": {

web/pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       '@xterm/addon-fit':
         specifier: ^0.10.0
         version: 0.10.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-webgl':
+        specifier: ^0.19.0
+        version: 0.19.0
       '@xterm/xterm':
         specifier: ^5.5.0
         version: 5.5.0
@@ -348,6 +351,9 @@ packages:
     peerDependencies:
       '@xterm/xterm': ^5.0.0
 
+  '@xterm/addon-webgl@0.19.0':
+    resolution: {integrity: sha512-b3fMOsyLVuCeNJWxolACEUED0vm7qC0cy4wRvf3oURSzDTYVQiGPhTnhWZwIHdvC48Y+oLhvYXnY4XDXPoJo6A==}
+
   '@xterm/xterm@5.5.0':
     resolution: {integrity: sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==}
 
@@ -772,6 +778,8 @@ snapshots:
     dependencies:
       '@xterm/xterm': 5.5.0
 
+  '@xterm/addon-webgl@0.19.0': {}
+
   '@xterm/xterm@5.5.0': {}
 
   assertion-error@2.0.1: {}

web/src/attach.ts

@@ -1,4 +1,5 @@
 import { FitAddon } from "@xterm/addon-fit";
+import { WebglAddon } from "@xterm/addon-webgl";
 import { Terminal } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
 
@@ -10,6 +11,11 @@ import { applyModsToChar, cursorSeq, tildeSeq } from "./keys.js";
 import { requestToggleDrawer } from "./drawer.js";
 import { splitCommand, toolIconSvg } from "./toolIcon.js";
 import type { ClientControl, Uuid } from "./types.js";
+import { WebglPolicy } from "./webglRenderer.js";
+
+/** One budget for the whole page — see webglRenderer.ts for why contexts are
+ *  rationed rather than handed to every connection. */
+const webglPolicy = new WebglPolicy();
 
 /**
  * A single live attach: an xterm terminal bound to the daemon's attach WebSocket.
@@ -26,8 +32,10 @@ export interface AttachConnection {
   readonly sessionId: Uuid;
   /** The `.attach` element (header + terminal body) to mount into a pane. */
   readonly el: HTMLElement;
-  /** Becomes the visible view: fit to the pane, focus, sync size. */
-  onMount(): void;
+  /** Becomes the visible view: fit to the pane, focus, sync size.
+   *  `focus: false` mounts without taking the keyboard — what a sidebar
+   *  preview needs, so j/k keeps working while the pane is on screen. */
+  onMount(opts?: { focus?: boolean }): void;
   /** Parked into the cache: keep streaming, just stop driving focus/resize. */
   onUnmount(): void;
   /** Put the keyboard back into this terminal — what leaving the sidebar does. */
@@ -135,6 +143,72 @@ export function createAttachConnection(
   term.loadAddon(fit);
   term.open(body);
 
+  // GPU rendering is scoped to the mounted view, not the connection: acquired
+  // in onMount, released in onUnmount. See webglRenderer.ts.
+  let webgl: WebglAddon | null = null;
+  let dprMedia: MediaQueryList | null = null;
+
+  // The glyph atlas is rasterised for one device pixel ratio. Dragging the
+  // window to a display with a different one (or an Android browser-zoom
+  // change) leaves every cell blurry until the atlas is rebuilt.
+  const onDprChange = () => {
+    try {
+      term.clearTextureAtlas();
+    } catch {
+      // ignore — nothing to rebuild if the renderer already went away
+    }
+    watchDpr();
+  };
+
+  function watchDpr(): void {
+    dprMedia?.removeEventListener("change", onDprChange);
+    dprMedia = null;
+    try {
+      dprMedia = window.matchMedia?.(`(resolution: ${window.devicePixelRatio}dppx)`) ?? null;
+      dprMedia?.addEventListener("change", onDprChange);
+    } catch {
+      // ignore — a browser without `resolution` media queries just keeps the
+      // atlas it has, which is the pre-WebGL behaviour anyway
+    }
+  }
+
+  function releaseWebgl(): void {
+    dprMedia?.removeEventListener("change", onDprChange);
+    dprMedia = null;
+    if (!webgl) return;
+    const addon = webgl;
+    webgl = null;
+    try {
+      addon.dispose(); // xterm falls back to the DOM renderer
+    } catch {
+      // ignore — a lost context can throw on the way out
+    }
+  }
+
+  function acquireWebgl(): void {
+    if (webgl || disposed || !webglPolicy.enabled()) return;
+    try {
+      const addon = new WebglAddon();
+      // Context loss is routine on Android — backgrounding the tab is enough.
+      // Drop back to the DOM renderer, then retry only while the shared budget
+      // allows and this view is still the one on screen.
+      addon.onContextLoss(() => {
+        webglPolicy.noteContextLoss();
+        releaseWebgl();
+        if (mounted) acquireWebgl();
+      });
+      term.loadAddon(addon);
+      webgl = addon;
+      watchDpr();
+    } catch {
+      // Context creation failed outright (no GPU, or the browser is already at
+      // its context cap). Count it like a loss so we stop asking, and stay on
+      // the DOM renderer.
+      webglPolicy.noteContextLoss();
+      webgl = null;
+    }
+  }
+
   // 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.
   term.attachCustomKeyEventHandler((e) => {
@@ -237,6 +311,10 @@ export function createAttachConnection(
   }
 
   let mounted = false;
+  // A previewed pane is visible but must not steal the keyboard from the
+  // sidebar, so mounting can opt out of the focus grab (and out of the one
+  // the socket does when it finishes connecting).
+  let focusOnMount = true;
   // We compute the fit ourselves instead of FitAddon.fit(): the addon subtracts
   // a scrollbar width that xterm reports as `offsetWidth - scrollArea || 15`,
   // so with the scrollbar hidden it falls back to a phantom 15px and the grid
@@ -315,7 +393,7 @@ export function createAttachConnection(
       reconnectMs = INITIAL_RECONNECT_MS;
       setState("connected", "open");
       sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
-      if (mounted) term.focus();
+      if (mounted && focusOnMount) term.focus();
     };
 
     ws.onmessage = (ev) => {
@@ -400,17 +478,22 @@ export function createAttachConnection(
   return {
     sessionId,
     el,
-    onMount() {
+    onMount(mountOpts?: { focus?: boolean }) {
       mounted = true;
+      focusOnMount = mountOpts?.focus !== false;
+      acquireWebgl();
       // Defer a tick so the element has its content-pane dimensions before fit.
       requestAnimationFrame(() => {
         tryFit();
         sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
-        if (ws.readyState === WebSocket.OPEN) term.focus();
+        if (focusOnMount && ws.readyState === WebSocket.OPEN) term.focus();
       });
     },
     onUnmount() {
       mounted = false;
+      // Parked views hand their GPU context back: the browser's cap is small
+      // (smaller still on Android) and MAX_PARKED connections outlive the pane.
+      releaseWebgl();
     },
     focusTerminal() {
       term.focus();
@@ -427,6 +510,7 @@ export function createAttachConnection(
       visual?.removeEventListener("resize", onResize);
       dataDisp.dispose();
       resizeDisp.dispose();
+      releaseWebgl();
       try {
         ws.close();
       } catch {

web/src/catalog.ts

@@ -164,6 +164,10 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     return wrap;
   }
 
+  // The row outlives the snapshot it was built from: a refresh that changes
+  // nothing structural patches it in place rather than replacing it, so the
+  // handlers below have to read the current session, not the one captured here.
+  let cur = node.session;
   const s = node.session;
   const now = Date.now();
   const row = document.createElement("a");
@@ -197,33 +201,74 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
   similarBtn.addEventListener("click", (ev) => {
     ev.preventDefault();
     ev.stopPropagation();
-    document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: s }));
+    document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur }));
   });
   const killBtn = row.querySelector(".leaf-kill") as HTMLButtonElement;
   killBtn.addEventListener("click", (ev) => {
     ev.preventDefault();
     ev.stopPropagation();
-    void requestKill(s, name);
+    void requestKill(cur, sessionName(cur));
   });
   row.addEventListener("click", () => {
-    document.dispatchEvent(new CustomEvent(SESSION_SELECT_EVENT, { detail: s.id }));
+    document.dispatchEvent(new CustomEvent(SESSION_SELECT_EVENT, { detail: cur.id }));
   });
   row.addEventListener("contextmenu", (ev) => {
     ev.preventDefault();
     ev.stopPropagation();
     openContextMenu(ev.clientX, ev.clientY, [
-      { label: "Rename…", onSelect: () => beginRename(row, s) },
+      { label: "Rename…", onSelect: () => beginRename(row, cur) },
       {
         label: "Spawn similar",
         onSelect: () =>
-          document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: s })),
+          document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur })),
+      },
+      {
+        label: "Kill session",
+        danger: true,
+        onSelect: () => void requestKill(cur, sessionName(cur)),
       },
-      { label: "Kill session", danger: true, onSelect: () => void requestKill(s, name) },
     ]);
   });
+  leafPatches.set(row, (next) => {
+    cur = next;
+    const nextSlug = activityColorSlug(next.activity ?? "Idle");
+    const nextWord = STATE_WORDS[nextSlug] ?? STATE_WORDS.idle;
+    row.setAttribute(
+      "aria-label",
+      `${sessionName(next)}, ${next.status === "Running" ? "running" : "exited"}, ${nextWord}`,
+    );
+    const rail = row.querySelector(".activity-rail");
+    if (rail) rail.outerHTML = activityRailMarkup(nextSlug, nextWord);
+    const meta = row.querySelector(".card-line2");
+    if (meta) meta.outerHTML = metaLine(next, Date.now());
+  });
   return row;
 }
 
+/** Refresh a standing card from a newer snapshot of its session, keeping the
+ *  element (and so the pointer's `:hover`) exactly where it is. Registered by
+ *  `renderNode`; only the bits `treeSignature` leaves out are rewritten. */
+const leafPatches = new WeakMap<HTMLElement, (s: Session) => void>();
+
+/**
+ * Everything about the tree that a patch cannot fix up.
+ *
+ * The daemon re-sends a session on every activity, foreground or cwd shift —
+ * a couple of times a minute per live session — and rebuilding the sidebar for
+ * each one drops `:hover` from the row under the pointer. Refreshes whose
+ * signature is unchanged are patched into the standing rows instead; anything
+ * that moves, renames, appears or dies changes the signature and rebuilds.
+ */
+function treeSignature(node: TreeNode): string {
+  if (node.kind === "folder") {
+    const head = `F:${node.name}:${node.path}:${collapsed.has(node.path)}`;
+    if (node.name && collapsed.has(node.path)) return head;
+    return `${head}(${node.children.map(treeSignature).join(",")})`;
+  }
+  const s = node.session;
+  return `L:${s.id}:${sessionName(s)}:${s.status}:${isProvisionalName(s)}`;
+}
+
 /**
  * Kill on the first click (#81): the daemon is the one that decides whether a
  * session may go, and it refuses over a worktree holding unsaved work. Only
@@ -342,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. */
@@ -364,6 +412,11 @@ export interface SidebarOptions {
   /** Daemon link behind the footer's status dot. Omitted in tests and in the
    *  design kit, which render the sidebar without a daemon. */
   link?: DaemonLink;
+  /** The highlight moved onto a session, or off every session (`null`): the
+   *  shell shows it in the content pane without opening it (docs/PREVIEW.md).
+   *  `source` is there so a mouse sweep can be debounced differently from a
+   *  keyboard step. */
+  onPreview?: (sessionId: string | null) => void;
 }
 
 export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): SidebarHandle {
@@ -496,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;
@@ -504,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);
     }
   };
 
@@ -528,6 +586,9 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     for (const r of rows) r.classList.toggle("is-highlighted", r.dataset.navKey === navKey);
   };
 
+  const sessionOf = (key: string | null): string | null =>
+    key?.startsWith("session:") ? key.slice("session:".length) : null;
+
   const moveNav = (delta: number) => {
     const rows = navRows();
     if (rows.length === 0) return;
@@ -539,6 +600,7 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     navKey = next.dataset.navKey ?? null;
     applyNav();
     next.scrollIntoView({ block: "nearest" });
+    opts.onPreview?.(sessionOf(navKey));
   };
 
   /** Enter: open the highlighted session, or expand the highlighted folder. */
@@ -563,9 +625,50 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     applyNav();
   };
 
+  // Hover previews the row under the pointer (docs/PREVIEW.md). Touch is left
+  // out: there is no hover there, and a tap already opens the session.
+  let hovered: string | null = null;
+  const setHovered = (id: string | null) => {
+    if (hovered === id) return;
+    hovered = id;
+    opts.onPreview?.(id);
+  };
+  treeHost.addEventListener("pointerover", (e) => {
+    if (e.pointerType === "touch") return;
+    const row = (e.target as HTMLElement | null)?.closest<HTMLElement>(".tree-leaf");
+    setHovered(row?.dataset.sessionId ?? null);
+  });
+  treeHost.addEventListener("pointerleave", (e) => {
+    if (e.pointerType === "touch") return;
+    setHovered(null);
+  });
+
   // Focusable as a unit: the walk moves a highlight, not DOM focus, so the
   // keyboard stays here while j/k runs.
   treeHost.tabIndex = -1;
+  // The keyboard walk's preview belongs to the list having the keyboard: once
+  // it doesn't, the content pane goes back to what the operator actually opened.
+  treeHost.addEventListener("blur", () => opts.onPreview?.(null));
+
+  /** The session behind the highlighted row, if the highlight is on a card. */
+  const highlightedSession = (): { row: HTMLElement; session: Session } | undefined => {
+    const row = rowFor(navKey);
+    const id = row?.dataset.sessionId;
+    if (!row || !id) return undefined;
+    const session = store.snapshot().sessions.get(id);
+    return session ? { row, session } : undefined;
+  };
+
+  /** `c`: collapse or expand the highlighted folder, the TUI's
+   *  `ToggleSidebarGroup`. Clicking the header is what toggles it; on a card
+   *  the key does nothing rather than toggling some other folder. */
+  const toggleHighlightedFolder = () => {
+    const row = rowFor(navKey);
+    if (!row || !row.classList.contains("tree-folder-header")) return;
+    row.click();
+    applyNav();
+  };
+
   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.
@@ -574,16 +677,35 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     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 return;
+    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;
+
   const refresh = () => {
     // Rebuilding the tree now would blow away the field being typed into.
     if (renamingId !== null) return;
     const state = store.snapshot();
     const sessions = [...state.sessions.values()];
     const tree = buildTree(sessions, homeDir, filter);
+    const signature = sessions.length === 0 ? `EMPTY:${filter.trim()}` : treeSignature(tree);
+    if (signature === renderedSignature) {
+      for (const row of treeHost.querySelectorAll<HTMLElement>(".tree-leaf")) {
+        const s = row.dataset.sessionId ? state.sessions.get(row.dataset.sessionId) : undefined;
+        if (s) leafPatches.get(row)?.(s);
+      }
+      return;
+    }
+    renderedSignature = signature;
     treeHost.replaceChildren();
     if (sessions.length === 0) {
       treeHost.appendChild(
@@ -607,7 +729,13 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
       /* absolute paths are a fine fallback */
     });
 
-  const rerenderHandler = () => refresh();
+  // Dispatched when something outside the store changed what the tree should
+  // look like — a folder collapsed, a rename ended — none of which the store
+  // snapshot can show, so the signature check has to be bypassed.
+  const rerenderHandler = () => {
+    renderedSignature = null;
+    refresh();
+  };
   document.addEventListener("catalog-rerender", rerenderHandler);
 
   // "Spawn similar" (#28) is dispatched here and handled in main.ts, where the
@@ -635,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/catalogPatch.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment happy-dom
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { renderSidebar } from "./catalog.js";
+import type { CatalogListener, CatalogStore } from "./events.js";
+import type { Session } from "./types.js";
+
+beforeAll(() => {
+  Object.defineProperty(window, "localStorage", {
+    value: { getItem: () => null, setItem: () => {} },
+  });
+  window.fetch = () => Promise.reject(new Error("offline"));
+});
+
+const ID = "11111111-2222-3333-4444-555555555555";
+
+function session(overrides: Partial<Session> = {}): Session {
+  return {
+    id: ID,
+    cwd: "/home/naps/tea/maestro",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-08-24T10:00:00Z",
+    ...overrides,
+  };
+}
+
+/** A store whose updates actually reach subscribers, unlike the one-shot
+ *  harness in catalog.test.ts. */
+function liveStore(initial: Session[]) {
+  const state = { sessions: new Map(initial.map((s) => [s.id, s])) };
+  const listeners = new Set<CatalogListener>();
+  const store = {
+    snapshot: () => state,
+    subscribe: (fn: CatalogListener) => {
+      listeners.add(fn);
+      fn(state);
+      return () => listeners.delete(fn);
+    },
+  } as unknown as CatalogStore;
+  const push = (sessions: Session[]) => {
+    state.sessions = new Map(sessions.map((s) => [s.id, s]));
+    for (const fn of listeners) fn(state);
+  };
+  return { store, push };
+}
+
+const rowOf = (el: HTMLElement) => el.querySelector<HTMLElement>(".tree-leaf")!;
+
+describe("sidebar refresh keeps rows in place (docs/SIDEBAR.md)", () => {
+  it("patches an activity change into the standing row instead of rebuilding it", () => {
+    const { store, push } = liveStore([session({ activity: "Idle" })]);
+    const { el } = renderSidebar(store, {});
+    const before = rowOf(el);
+
+    push([session({ activity: "AwaitingInput" })]);
+
+    // Same element: a rebuild under the pointer would drop `:hover` and restart
+    // the row's transitions, which is the flicker this avoids.
+    expect(rowOf(el)).toBe(before);
+    // …and the card still tells the truth about the session.
+    expect(before.querySelector(".activity-rail")?.getAttribute("data-activity")).toBe(
+      "awaiting-input",
+    );
+    expect(before.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
+      "awaiting-input",
+    );
+    expect(before.getAttribute("aria-label")).toContain("Awaiting input");
+  });
+
+  it("rebuilds when the row set changes", () => {
+    const { store, push } = liveStore([session()]);
+    const { el } = renderSidebar(store, {});
+    const before = rowOf(el);
+
+    push([session(), session({ id: "99999999-2222-3333-4444-555555555555", command: "bash" })]);
+
+    expect(el.querySelectorAll(".tree-leaf")).toHaveLength(2);
+    expect(rowOf(el)).not.toBe(before);
+  });
+
+  it("rebuilds when a session dies", () => {
+    const { store, push } = liveStore([session()]);
+    const { el } = renderSidebar(store, {});
+    const before = rowOf(el);
+
+    push([session({ status: "Dead" })]);
+
+    expect(rowOf(el)).not.toBe(before);
+    expect(rowOf(el).dataset.status).toBe("dead");
+  });
+
+  it("rebuilds when a session is renamed", () => {
+    const { store, push } = liveStore([session()]);
+    const { el } = renderSidebar(store, {});
+    const before = rowOf(el);
+
+    push([session({ metadata: { name: "harmony" } })]);
+
+    expect(rowOf(el)).not.toBe(before);
+    expect(rowOf(el).querySelector(".leaf-name")?.textContent).toBe("harmony");
+  });
+});

web/src/connections.ts

@@ -74,7 +74,7 @@ export class ConnectionPool {
    * Ensure `id` is live and shown inside `pane`, reusing its connection if one
    * exists (refreshing LRU recency). Does not touch other mounted panes.
    */
-  mount(id: Uuid, pane: HTMLElement, info?: AttachInfo): void {
+  mount(id: Uuid, pane: HTMLElement, info?: AttachInfo, opts?: { focus?: boolean }): void {
     let conn = this.cache.get(id);
     if (conn) {
       this.cache.delete(id);
@@ -93,9 +93,9 @@ export class ConnectionPool {
     }
     if (conn.el.parentElement !== pane) {
       pane.replaceChildren(conn.el);
-      conn.onMount();
+      conn.onMount(opts);
     } else if (!this.mounted.has(id)) {
-      conn.onMount();
+      conn.onMount(opts);
     }
     this.mounted.add(id);
     this.evict();
@@ -114,13 +114,17 @@ export class ConnectionPool {
   /**
    * Reconcile the visible set to exactly `entries` (in render order): park any
    * mounted session not listed, mount/refresh each listed one in its pane.
+   * `focus: false` shows the panes without taking the keyboard (preview).
    */
-  setVisible(entries: { id: Uuid; pane: HTMLElement; info?: AttachInfo }[]): void {
+  setVisible(
+    entries: { id: Uuid; pane: HTMLElement; info?: AttachInfo }[],
+    opts?: { focus?: boolean },
+  ): void {
     const next = new Set(entries.map((e) => e.id));
     for (const id of [...this.mounted]) {
       if (!next.has(id)) this.unmount(id);
     }
-    for (const e of entries) this.mount(e.id, e.pane, e.info);
+    for (const e of entries) this.mount(e.id, e.pane, e.info, opts);
   }
 
   /** Also tells the daemon which pane is focused (docs/SIDEBAR.md's

web/src/help.ts

@@ -31,6 +31,9 @@ export const SHORTCUTS: ShortcutGroup[] = [
       { 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" },
     ],

web/src/kit.ts

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

web/src/main.ts

@@ -29,6 +29,7 @@ import { mountHud, type Hud } from "./hud.js";
 import { emptyLayout, type Layout, openSessions } from "./layout.js";
 import { createMultiView, type MultiView } from "./multiview.js";
 import { loadLayout, saveLayout } from "./persistence.js";
+import { createPreviewSchedule } from "./previewSchedule.js";
 import {
   FOCUS_PANE_EVENT,
   FOCUS_SIDEBAR_EVENT,
@@ -104,9 +105,20 @@ shellEl.dataset.route = "catalog";
 // after the welcome renderer). The hook only fires on user interaction, by which
 // point `mv` is assigned.
 let mv: MultiView;
+
+// Preview timing (docs/PREVIEW.md): the first move shows at once, and a burst
+// — j held down, or the pointer sweeping the whole list — is coalesced so it
+// costs a couple of pane mounts instead of one per row walked.
+const schedulePreview = createPreviewSchedule((sessionId) => {
+  ensureMultiView();
+  mv?.previewSession(sessionId);
+  updateShellRoute();
+});
+
 const sidebar = renderSidebar(store, {
   onLeafDrag: (id, e) => mv?.beginSessionDrag(id, e),
   link,
+  onPreview: schedulePreview,
 });
 const content = document.createElement("section");
 content.className = "content";
@@ -184,7 +196,9 @@ function infoFor(sessionId: string) {
 
 /** Drive the shell's responsive layout off whether any pane is open. */
 function updateShellRoute(): void {
-  const hasPanes = openSessions(layout).size > 0;
+  // A preview is not an open pane (docs/PREVIEW.md), so the mobile shell does
+  // not swap the list out for a terminal on the way past a row.
+  const hasPanes = (mv?.openSessions() ?? openSessions(layout)).size > 0;
   shellEl.dataset.route = hasPanes ? "attach" : "catalog";
 }
 
@@ -244,11 +258,18 @@ mv = createMultiView({
   onLayoutChange: scheduleSave,
 });
 let contentShowsMv = false;
-function showMultiView(): void {
+/** Put the multi-view in the content pane, without rendering it. A preview
+ *  renders once, on its own terms (`docs/PREVIEW.md`); a render here would
+ *  first re-mount the pane it is about to replace, and that mount takes the
+ *  keyboard away from the list being walked. */
+function ensureMultiView(): void {
   if (!contentShowsMv) {
     content.replaceChildren(mv.el);
     contentShowsMv = true;
   }
+}
+function showMultiView(): void {
+  ensureMultiView();
   mv.render();
   updateShellRoute();
 }
@@ -375,7 +396,13 @@ window.addEventListener("keydown", (e) => {
 
 // Tab in the session list hands the keyboard to the pane; Escape in the pane
 // hands it back — the pair the TUI gets from `tab` and `esc`.
-document.addEventListener(FOCUS_PANE_EVENT, () => pool.focusTerminal());
+document.addEventListener(FOCUS_PANE_EVENT, () => {
+  // Handing the keyboard to a previewed pane is choosing it: the preview stops
+  // being provisional rather than snapping back the moment the list blurs.
+  const previewed = mv.previewedSessionId();
+  if (previewed) focusSession(previewed);
+  pool.focusTerminal();
+});
 document.addEventListener(FOCUS_SIDEBAR_EVENT, () => {
   drawer.open(); // no-op on desktop; on mobile the list is off-canvas
   sidebar.focusList();
@@ -386,6 +413,7 @@ document.addEventListener(FOCUS_SIDEBAR_EVENT, () => {
  *  on `hashchange` alone — a split or drag can move focus without the hash
  *  changing, leaving a click back onto that session's row silently ignored. */
 function focusSession(sessionId: string): void {
+  schedulePreview.cancel();
   showMultiView();
   mv.openSession(sessionId);
   updateShellRoute();

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

@@ -11,6 +11,7 @@ import {
   addTab,
   closeTab,
   findLeaf,
+  freshId,
   type Dir,
   type Layout,
   leaves,
@@ -19,6 +20,7 @@ import {
   openSessions,
   removeLeaf,
   splitLeaf,
+  type Tab,
 } from "./layout.js";
 import type { AttachInfo } from "./attach.js";
 
@@ -57,11 +59,22 @@ export interface MultiView {
   /** Rebuild the view from the current layout. */
   render: () => void;
   focusedSessionId: () => string | null;
+  /** Show `sessionId` in the content pane without committing to it
+   *  (docs/PREVIEW.md): the tab holding it is brought forward, or a throwaway
+   *  tab carries it. `null` puts back whatever was on screen before. */
+  previewSession: (sessionId: string | null) => void;
+  /** The session being previewed, or null. */
+  previewedSessionId: () => string | null;
 }
 
 export function createMultiView(opts: MultiViewOptions): MultiView {
   const { pool, layout, sidebar, infoFor, onDisconnect, renderWelcome } = opts;
-  const persist = () => opts.onLayoutChange?.();
+  // A preview must never reach localStorage: it is undone the moment the
+  // highlight moves on, and the layout it would save is not the operator's.
+  const persist = () => {
+    if (preview) return;
+    opts.onLayoutChange?.();
+  };
 
   const el = document.createElement("div");
   el.className = "mv";
@@ -83,8 +96,119 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     render();
   });
 
+  // ---- preview (docs/PREVIEW.md) ----
+  // A preview is a temporary *view* change, never a layout change: it records
+  // exactly what it moved so ending it puts the layout back byte for byte, and
+  // it neither persists nor reports pane focus to the daemon while it is up.
+  interface Preview {
+    sessionId: string;
+    /** Tab that was active before the preview. */
+    prevActiveTabId: string;
+    /** Focused leaf to restore, when the preview stole focus in a real tab. */
+    prevFocus: { tabId: string; leafId: string | null } | null;
+    /** Throwaway tab built for a session that no pane was showing. */
+    tempTabId: string | null;
+  }
+  let preview: Preview | null = null;
+  /// Set while a preview-driven render runs: ending a preview re-mounts the
+  /// pane that was there, and that mount must not pull the keyboard out of the
+  /// sidebar the operator is still walking.
+  let quietRender = false;
+
+  /** Render without any mount taking the keyboard. */
+  function renderQuietly(): void {
+    quietRender = true;
+    try {
+      render();
+    } finally {
+      quietRender = false;
+    }
+  }
+
+  const isTempTab = (tabId: string) => preview?.tempTabId === tabId;
+
+  /** Undo the preview's moves. Mutates only — the caller renders. */
+  function restorePreview(): boolean {
+    const p = preview;
+    if (!p) return false;
+    preview = null;
+    if (p.tempTabId) {
+      const i = layout.tabs.findIndex((t) => t.id === p.tempTabId);
+      if (i >= 0) layout.tabs.splice(i, 1);
+    } else if (p.prevFocus) {
+      const t = layout.tabs.find((x) => x.id === p.prevFocus!.tabId);
+      if (t) t.focusedLeafId = p.prevFocus.leafId;
+    }
+    layout.activeTabId = layout.tabs.some((t) => t.id === p.prevActiveTabId)
+      ? p.prevActiveTabId
+      : layout.tabs[0].id;
+    return true;
+  }
+
+  /** Keep what the preview is showing: its throwaway tab becomes a real one,
+   *  and the focus it moved stands. Returns true when `sessionId` was the
+   *  session being previewed; any other preview is simply discarded. */
+  function settlePreview(sessionId: string): boolean {
+    const p = preview;
+    if (!p) return false;
+    if (p.sessionId !== sessionId) {
+      restorePreview();
+      return false;
+    }
+    preview = null;
+    if (p.tempTabId) {
+      const t = layout.tabs.find((x) => x.id === p.tempTabId);
+      if (t) t.title = `Tab ${layout.tabs.length}`;
+    }
+    return true;
+  }
+
+  function previewSession(sessionId: string | null): void {
+    if (preview?.sessionId === sessionId) return;
+    if (sessionId === null) {
+      if (restorePreview()) renderQuietly();
+      return;
+    }
+    restorePreview();
+    const prevActiveTabId = layout.activeTabId;
+    const loc = locateSession(layout, sessionId);
+    if (loc) {
+      preview = {
+        sessionId,
+        prevActiveTabId,
+        prevFocus: { tabId: loc.tab.id, leafId: loc.tab.focusedLeafId },
+        tempTabId: null,
+      };
+      layout.activeTabId = loc.tab.id;
+      loc.tab.focusedLeafId = loc.leaf.id;
+    } else {
+      // Not on screen anywhere: a throwaway tab carries it, so no existing
+      // pane is evicted and nothing the operator arranged moves.
+      const tab: Tab = { id: freshId("t"), title: "Preview", root: null, focusedLeafId: null };
+      tab.focusedLeafId = splitLeaf(tab, "", sessionId, "row", true);
+      layout.tabs.push(tab);
+      layout.activeTabId = tab.id;
+      preview = { sessionId, prevActiveTabId, prevFocus: null, tempTabId: tab.id };
+    }
+    renderQuietly();
+  }
+
+  /** Any user action that changes the layout for real ends the preview first,
+   *  so it never bakes a throwaway tab into the arrangement. */
+  function dropPreview(): void {
+    restorePreview();
+  }
+
   // ---- highlight helpers ----
 
+  /** Sessions the operator actually has open — the preview's throwaway tab
+   *  does not count, or hovering the sidebar would flip the shell's route. */
+  function realOpenSessions(): Set<string> {
+    const out = openSessions(layout);
+    if (preview?.tempTabId) out.delete(preview.sessionId);
+    return out;
+  }
+
   function focusedLeafSession(): string | null {
     const tab = activeTab(layout);
     const fl = tab.focusedLeafId ? findLeaf(tab.root, tab.focusedLeafId) : null;
@@ -97,12 +221,23 @@ 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,
+      );
     }
-    pool.setFocus(focusedLeafSession());
+    // A preview is not a focused pane: reporting it would clear the session's
+    // `AwaitingInput` glow just because the operator scrolled past it.
+    if (!preview) pool.setFocus(focusedLeafSession());
     sidebar.setHighlights({
-      open: openSessions(layout),
+      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 {
@@ -168,6 +303,11 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     pane.addEventListener(
       "pointerdown",
       (e) => {
+        // Clicking into a previewed pane is the operator choosing it.
+        if (preview && leaf.sessionId === preview.sessionId) {
+          settlePreview(leaf.sessionId);
+          persist();
+        }
         focusLeaf(leaf.id);
         // Drag a pane by its title bar (desktop only — no docking on mobile).
         if (isMobile) return;
@@ -252,24 +392,31 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     for (const t of layout.tabs) {
       const tab = document.createElement("button");
       tab.type = "button";
-      tab.className = "mv-tab" + (t.id === layout.activeTabId ? " is-active" : "");
+      tab.className =
+        "mv-tab" +
+        (t.id === layout.activeTabId ? " is-active" : "") +
+        (isTempTab(t.id) ? " is-preview" : "");
       const n = leaves(t.root).filter((l) => l.sessionId).length;
       const label = document.createElement("span");
       label.textContent = t.title + (n ? ` · ${n}` : "");
       tab.appendChild(label);
       tab.addEventListener("click", () => {
+        if (isTempTab(t.id)) return; // a preview tab is not a place to go
+        dropPreview();
         if (layout.activeTabId !== t.id) {
           layout.activeTabId = t.id;
-          render();
         }
+        render();
       });
-      if (layout.tabs.length > 1) {
+      // A preview tab is not the operator's to close: it goes on its own.
+      if (layout.tabs.length > 1 && !isTempTab(t.id)) {
         const close = document.createElement("span");
         close.className = "mv-tab-close";
         close.textContent = "✕";
         close.title = "Close tab";
         close.addEventListener("click", (e) => {
           e.stopPropagation();
+          dropPreview();
           closeTab(layout, t.id);
           render();
         });
@@ -283,6 +430,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     add.textContent = "+";
     add.title = "New tab";
     add.addEventListener("click", () => {
+      dropPreview();
       addTab(layout);
       render();
     });
@@ -292,12 +440,14 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
   // ---- mutations ----
 
   function splitFocused(leafId: string, dir: Dir): void {
+    dropPreview();
     const tab = activeTab(layout);
     tab.focusedLeafId = splitLeaf(tab, leafId, null, dir, true);
     render();
   }
 
   function closePane(leafId: string): void {
+    dropPreview();
     const tab = activeTab(layout);
     removeLeaf(tab, leafId);
     if (tab.focusedLeafId === leafId) {
@@ -307,6 +457,12 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
   }
 
   function openSession(sessionId: string): void {
+    // Opening what is already previewed keeps exactly what is on screen: the
+    // throwaway tab becomes a real one instead of the session moving again.
+    if (settlePreview(sessionId)) {
+      render();
+      return;
+    }
     const loc = locateSession(layout, sessionId);
     if (loc) {
       layout.activeTabId = loc.tab.id;
@@ -337,6 +493,11 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
   /// (#67 review). `newTab` opens its own tab instead of halving whatever the
   /// operator was reading (#100) — what the Spawn button asks for.
   function openSessionBeside(sessionId: string, placement?: { newTab?: boolean }): void {
+    if (settlePreview(sessionId)) {
+      render();
+      opts.onOpenSessionsChange?.();
+      return;
+    }
     const loc = locateSession(layout, sessionId);
     if (loc) {
       layout.activeTabId = loc.tab.id;
@@ -384,13 +545,20 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     // A lone tab has nothing to switch between, so the bar is only a strip of
     // chrome; CSS hides it until a second tab exists. Spawning still opens its
     // own tab (#100), which brings the bar back with the "+" button on it.
-    el.classList.toggle("mv-solo-tab", layout.tabs.length === 1);
+    // The preview's throwaway tab must not make the bar appear and vanish as
+    // the highlight moves, so it does not count towards "one tab only".
+    el.classList.toggle(
+      "mv-solo-tab",
+      layout.tabs.filter((t) => !isTempTab(t.id)).length === 1,
+    );
+    el.classList.toggle("mv-previewing", preview !== null);
 
     if (!tab.root) {
       pool.setVisible([]);
-      pool.setFocus(null);
+      if (!preview) pool.setFocus(null);
       canvas.appendChild(renderWelcome());
-      sidebar.setHighlights({ open: openSessions(layout), focused: null });
+      sidebar.setHighlights({ open: realOpenSessions(), focused: null });
+      sidebar.setPreview(preview?.sessionId ?? null);
       persist();
       return;
     }
@@ -408,7 +576,12 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
 
     const hosts: { id: string; host: HTMLElement; info?: AttachInfo }[] = [];
     canvas.appendChild(buildTree(tab.root, hosts));
-    pool.setVisible(hosts.map((h) => ({ id: h.id, pane: h.host, info: h.info })));
+    // A preview keeps the keyboard in the sidebar: mounting must not focus the
+    // terminal, or j/k would stop walking the list after the first step.
+    pool.setVisible(
+      hosts.map((h) => ({ id: h.id, pane: h.host, info: h.info })),
+      { focus: !preview && !quietRender },
+    );
     syncFocus();
     persist();
   }
@@ -425,18 +598,22 @@ 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);
 
     // Only the focused leaf's session is live on mobile; the rest park.
     pool.setVisible(
       focused.sessionId ? [{ id: focused.sessionId, pane: pane.host, info: infoFor(focused.sessionId) }] : [],
+      { focus: !preview && !quietRender },
     );
-    pool.setFocus(focused.sessionId ?? null);
-    sidebar.setHighlights({ open: openSessions(layout), focused: focused.sessionId ?? null });
+    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 {
+    dropPreview();
     const loc = locateSession(layout, sessionId);
     if (!loc) return;
     removeLeaf(loc.tab, loc.leaf.id);
@@ -628,6 +805,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
   }
 
   function beginSessionDrag(sessionId: string, e: PointerEvent): void {
+    dropPreview();
     runDrag({ kind: "session", sessionId }, e, { deferred: true });
   }
 
@@ -636,9 +814,11 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     openSession,
     openSessionBeside,
     closeSession,
-    openSessions: () => openSessions(layout),
+    openSessions: realOpenSessions,
     beginSessionDrag,
     render,
     focusedSessionId: focusedLeafSession,
+    previewSession,
+    previewedSessionId: () => preview?.sessionId ?? null,
   };
 }

web/src/preview.test.ts

@@ -0,0 +1,242 @@
+// @vitest-environment happy-dom
+// Sidebar preview (docs/PREVIEW.md): highlighting a session shows it in the
+// content pane without changing the layout the operator built.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { addTab, emptyLayout, type Layout, splitLeaf } from "./layout.js";
+import { serializeLayout } from "./persistence.js";
+import { createMultiView, type MultiView } from "./multiview.js";
+import type { ConnectionPool } from "./connections.js";
+import type { SidebarHandle } from "./catalog.js";
+
+function stubFetch(): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      const body = url.includes("/api/info")
+        ? { hostname: "h", version: "0", home_dir: "/home/user", presets: [] }
+        : undefined;
+      return new Response(JSON.stringify(body), { status: 200 });
+    }),
+  );
+}
+
+interface Spy {
+  pool: ConnectionPool;
+  visible: () => string[];
+  focusCalls: (string | null)[];
+  mountedWithFocus: (boolean | undefined)[];
+}
+
+function fakePool(): Spy {
+  let visible: string[] = [];
+  const focusCalls: (string | null)[] = [];
+  const mountedWithFocus: (boolean | undefined)[] = [];
+  const pool = {
+    setVisible(entries: { id: string }[], opts?: { focus?: boolean }) {
+      visible = entries.map((e) => e.id);
+      mountedWithFocus.push(opts?.focus);
+    },
+    setFocus(id: string | null) {
+      focusCalls.push(id);
+    },
+  } as unknown as ConnectionPool;
+  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;
+    },
+    dispose() {},
+  };
+}
+
+function makeMv(layout: Layout, pool: ConnectionPool, onLayoutChange?: () => void): MultiView {
+  const mv = createMultiView({
+    pool,
+    layout,
+    sidebar: fakeSidebar(),
+    infoFor: () => ({ name: "sess", command: "bash" }),
+    onDisconnect: () => {},
+    renderWelcome: () => document.createElement("div"),
+    onLayoutChange,
+  });
+  document.body.appendChild(mv.el);
+  mv.render();
+  return mv;
+}
+
+/** Tab 1 holds `s1`; tab 2 holds `s2` and is the active one. */
+function twoTabs(): Layout {
+  const layout = emptyLayout();
+  const first = layout.tabs[0];
+  first.focusedLeafId = splitLeaf(first, "", "s1", "row", true);
+  const second = addTab(layout);
+  second.focusedLeafId = splitLeaf(second, "", "s2", "row", true);
+  layout.activeTabId = second.id;
+  return layout;
+}
+
+describe("sidebar preview", () => {
+  beforeEach(() => {
+    stubFetch();
+    document.body.replaceChildren();
+    previewRow.id = null;
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("brings a session's own tab forward, then puts the layout back", () => {
+    const layout = twoTabs();
+    const before = serializeLayout(layout);
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+
+    mv.previewSession("s1");
+    expect(spy.visible()).toEqual(["s1"]);
+    expect(mv.previewedSessionId()).toBe("s1");
+
+    mv.previewSession(null);
+    expect(spy.visible()).toEqual(["s2"]);
+    expect(mv.previewedSessionId()).toBeNull();
+    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);
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+
+    mv.previewSession("s9");
+    expect(spy.visible()).toEqual(["s9"]);
+    expect(layout.tabs).toHaveLength(3);
+    // The throwaway tab is not something the operator has open.
+    expect(mv.openSessions().has("s9")).toBe(false);
+
+    mv.previewSession(null);
+    expect(layout.tabs).toHaveLength(2);
+    expect(serializeLayout(layout)).toEqual(before);
+  });
+
+  it("stepping between previews leaves only the newest one on screen", () => {
+    const layout = twoTabs();
+    const before = serializeLayout(layout);
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+
+    mv.previewSession("s9");
+    mv.previewSession("s1");
+    mv.previewSession("s8");
+    expect(spy.visible()).toEqual(["s8"]);
+    expect(layout.tabs).toHaveLength(3);
+
+    mv.previewSession(null);
+    expect(serializeLayout(layout)).toEqual(before);
+  });
+
+  it("opening what is previewed keeps it: the throwaway tab becomes real", () => {
+    const layout = twoTabs();
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+
+    mv.previewSession("s9");
+    mv.openSession("s9");
+
+    expect(mv.previewedSessionId()).toBeNull();
+    expect(layout.tabs).toHaveLength(3);
+    expect(mv.openSessions().has("s9")).toBe(true);
+    expect(spy.visible()).toEqual(["s9"]);
+    // Nothing the operator had open was evicted to make room.
+    expect(mv.openSessions().has("s2")).toBe(true);
+  });
+
+  it("never persists, and saves again once the preview is settled", () => {
+    const layout = twoTabs();
+    const spy = fakePool();
+    const saves = vi.fn();
+    const mv = makeMv(layout, spy.pool, saves);
+    saves.mockClear();
+
+    mv.previewSession("s9");
+    expect(saves).not.toHaveBeenCalled();
+
+    mv.previewSession(null);
+    expect(saves).toHaveBeenCalled();
+  });
+
+  it("never reports a previewed pane as focused to the daemon", () => {
+    const layout = twoTabs();
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+    spy.focusCalls.length = 0;
+
+    mv.previewSession("s1");
+    mv.previewSession("s9");
+    expect(spy.focusCalls).toEqual([]);
+
+    mv.previewSession(null);
+    expect(spy.focusCalls).toEqual(["s2"]);
+  });
+
+  it("mounts a preview without taking the keyboard", () => {
+    const layout = twoTabs();
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+    spy.mountedWithFocus.length = 0;
+
+    mv.previewSession("s1");
+    expect(spy.mountedWithFocus).toEqual([false]);
+
+    mv.openSession("s1");
+    expect(spy.mountedWithFocus.at(-1)).toBe(true);
+  });
+
+  it("keeps the tab bar hidden while a lone tab is previewing", () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "s1", "row", true);
+    const spy = fakePool();
+    const mv = makeMv(layout, spy.pool);
+    expect(mv.el.classList.contains("mv-solo-tab")).toBe(true);
+
+    mv.previewSession("s9");
+    expect(mv.el.classList.contains("mv-solo-tab")).toBe(true);
+    expect(mv.el.classList.contains("mv-previewing")).toBe(true);
+
+    mv.previewSession(null);
+    expect(mv.el.classList.contains("mv-previewing")).toBe(false);
+  });
+});

web/src/previewSchedule.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+
+import { createPreviewSchedule, PREVIEW_MIN_GAP_MS } from "./previewSchedule.js";
+
+/** Hand-driven clock + timer queue, so the schedule is asserted without waiting. */
+function harness() {
+  let now = 1_000;
+  const timers = new Map<number, { at: number; fn: () => void }>();
+  let nextHandle = 1;
+  const emitted: (string | null)[] = [];
+
+  const schedule = createPreviewSchedule((id) => emitted.push(id), {
+    now: () => now,
+    setTimer: (fn, ms) => {
+      const h = nextHandle++;
+      timers.set(h, { at: now + ms, fn });
+      return h;
+    },
+    clearTimer: (h) => {
+      timers.delete(h);
+    },
+  });
+
+  /** Advance the clock, firing any timer that comes due. */
+  const advance = (ms: number) => {
+    now += ms;
+    for (const [h, t] of [...timers]) {
+      if (t.at <= now) {
+        timers.delete(h);
+        t.fn();
+      }
+    }
+  };
+
+  return { schedule, emitted, advance };
+}
+
+describe("preview schedule", () => {
+  it("shows the first preview immediately", () => {
+    const { schedule, emitted } = harness();
+    schedule("s1");
+    expect(emitted).toEqual(["s1"]);
+  });
+
+  it("coalesces a burst into one trailing preview", () => {
+    const { schedule, emitted, advance } = harness();
+    // A pointer sweep across the list, or j held down: every row in between
+    // is walked well inside one gap.
+    schedule("s1");
+    schedule("s2");
+    schedule("s3");
+    expect(emitted).toEqual(["s1"]);
+    advance(PREVIEW_MIN_GAP_MS);
+    expect(emitted).toEqual(["s1", "s3"]);
+  });
+
+  it("shows the next preview immediately once the gap has passed", () => {
+    const { schedule, emitted, advance } = harness();
+    schedule("s1");
+    advance(PREVIEW_MIN_GAP_MS);
+    schedule("s2");
+    expect(emitted).toEqual(["s1", "s2"]);
+  });
+
+  it("drops a superseded trailing preview rather than replaying it", () => {
+    const { schedule, emitted, advance } = harness();
+    schedule("s1");
+    schedule("s2");
+    schedule("s1"); // back where we started inside the same gap
+    advance(PREVIEW_MIN_GAP_MS);
+    // s1 is already on screen, so the trailing edge has nothing to do.
+    expect(emitted).toEqual(["s1"]);
+  });
+
+  it("clears through the same gap, so leaving and re-entering does not blink", () => {
+    const { schedule, emitted, advance } = harness();
+    schedule("s1");
+    schedule(null); // pointer crosses the gap between two rows
+    schedule("s2");
+    advance(PREVIEW_MIN_GAP_MS);
+    expect(emitted).toEqual(["s1", "s2"]);
+  });
+
+  it("cancel drops a pending trailing preview", () => {
+    const { schedule, emitted, advance } = harness();
+    schedule("s1");
+    schedule("s2");
+    schedule.cancel();
+    advance(PREVIEW_MIN_GAP_MS);
+    expect(emitted).toEqual(["s1"]);
+  });
+});

web/src/previewSchedule.ts

@@ -0,0 +1,87 @@
+/**
+ * When the content pane follows the sidebar highlight (docs/PREVIEW.md).
+ *
+ * The highlight itself is never scheduled — that is a class on a row and lands
+ * on the same frame as the input. This governs only the pane swap behind it,
+ * which mounts a terminal and, for a session the connection pool isn't already
+ * holding, opens an attach socket the daemon answers with a `tmux capture-pane`.
+ *
+ * A plain debounce would put that cost in front of every preview, including the
+ * one preview the operator actually meant. Instead the first move shows at once
+ * and the rest of a burst is coalesced: walking a list with `j` held down, or
+ * sweeping the pointer from the top of the sidebar to the bottom, costs one
+ * preview at the start and one at the row you stopped on, not one per row.
+ */
+
+/** Shortest gap between two pane swaps. Long enough that a fast walk mounts a
+ *  couple of terminals rather than one per row; short enough that a deliberate
+ *  second move never waits on it. */
+export const PREVIEW_MIN_GAP_MS = 120;
+
+export interface PreviewScheduleDeps {
+  now?: () => number;
+  setTimer?: (fn: () => void, ms: number) => number;
+  clearTimer?: (handle: number) => void;
+  /** Override the gap; tests and callers otherwise take {@link PREVIEW_MIN_GAP_MS}. */
+  minGapMs?: number;
+}
+
+export interface PreviewSchedule {
+  (sessionId: string | null): void;
+  /** Drop a pending trailing preview without showing it. */
+  cancel(): void;
+}
+
+/**
+ * Wrap `show` so it fires on the leading edge and at most once per gap.
+ *
+ * `show` is called with the session to preview, or `null` to put back whatever
+ * the operator actually opened.
+ */
+export function createPreviewSchedule(
+  show: (sessionId: string | null) => void,
+  deps: PreviewScheduleDeps = {},
+): PreviewSchedule {
+  const now = deps.now ?? (() => Date.now());
+  const setTimer = deps.setTimer ?? ((fn, ms) => window.setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => window.clearTimeout(h));
+  const minGap = deps.minGapMs ?? PREVIEW_MIN_GAP_MS;
+
+  let lastShownAt = Number.NEGATIVE_INFINITY;
+  let shown: string | null | undefined;
+  let pendingTimer: number | undefined;
+  let pendingId: string | null = null;
+
+  const emit = (id: string | null) => {
+    // Nothing to do when the burst ended on the view already up: re-showing it
+    // would tear down and re-mount the pane for no visible change.
+    if (shown === id) return;
+    shown = id;
+    lastShownAt = now();
+    show(id);
+  };
+
+  const cancelPending = () => {
+    if (pendingTimer === undefined) return;
+    clearTimer(pendingTimer);
+    pendingTimer = undefined;
+  };
+
+  const schedule = ((sessionId: string | null) => {
+    pendingId = sessionId;
+    const waited = now() - lastShownAt;
+    if (waited >= minGap) {
+      cancelPending();
+      emit(sessionId);
+      return;
+    }
+    if (pendingTimer !== undefined) return; // already waiting; `pendingId` wins
+    pendingTimer = setTimer(() => {
+      pendingTimer = undefined;
+      emit(pendingId);
+    }, minGap - waited);
+  }) as PreviewSchedule;
+
+  schedule.cancel = cancelPending;
+  return schedule;
+}

web/src/sidebarNav.test.ts

@@ -39,8 +39,11 @@ const A = "aaaaaaaa-0000-0000-0000-00000000000a";
 const B = "aaaaaaaa-0000-0000-0000-00000000000b";
 
 /** Two sessions in sibling directories: two folder headers, two cards. */
-function twoFolders(): { el: HTMLElement; handle: ReturnType<typeof renderSidebar> } {
-  const handle = renderSidebar(storeWith([session(A, "/one"), session(B, "/two")]));
+function twoFolders(opts: Parameters<typeof renderSidebar>[1] = {}): {
+  el: HTMLElement;
+  handle: ReturnType<typeof renderSidebar>;
+} {
+  const handle = renderSidebar(storeWith([session(A, "/one"), session(B, "/two")]), opts);
   // Mounted: `focusList` moves real DOM focus, which needs a live document.
   document.body.replaceChildren(handle.el);
   return { el: handle.el, handle };
@@ -117,6 +120,43 @@ describe("sidebar keyboard navigation", () => {
     expect(asked).toBe(1);
   });
 
+  it("c collapses and expands the highlighted folder", () => {
+    const { el } = twoFolders();
+    const header = el.querySelectorAll<HTMLElement>(".tree-folder-header")[0];
+    header.click(); // collapse /one, so the walk stops on its header
+
+    press(tree(el), "j");
+    expect(highlighted(el)).toBe("folder:one");
+    press(tree(el), "c");
+    // Expanded: the card it was hiding is back in the walk.
+    expect(el.querySelector(`[data-nav-key="session:${A}"]`)).not.toBeNull();
+  });
+
+  it("r renames the highlighted session in place", () => {
+    const { el } = twoFolders();
+    press(tree(el), "j");
+    press(tree(el), "r");
+    const field = el.querySelector<HTMLInputElement>(".leaf-rename");
+    expect(field).not.toBeNull();
+    // Escape settles the rename, so the module-level "a row is being renamed"
+    // flag doesn't leak into the next test.
+    field!.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+  });
+
+  it("x kills the highlighted session", async () => {
+    const { el } = twoFolders();
+    const killed: string[] = [];
+    window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+      killed.push(`${init?.method ?? "GET"} ${String(input)}`);
+      return Promise.resolve(new Response(null, { status: 204 }));
+    }) as typeof window.fetch;
+
+    press(tree(el), "j");
+    press(tree(el), "x");
+    await Promise.resolve();
+    expect(killed.some((r) => r.startsWith("DELETE") && r.includes(A))).toBe(true);
+  });
+
   it("leaves the keyboard alone while a row is being renamed", () => {
     const { el } = twoFolders();
     press(tree(el), "j");
@@ -126,3 +166,40 @@ describe("sidebar keyboard navigation", () => {
     expect(highlighted(el)).toBe(`session:${A}`);
   });
 });
+
+describe("sidebar preview requests (docs/PREVIEW.md)", () => {
+  it("asks for a preview on every keyboard step, and for none once the list blurs", () => {
+    const seen: (string | null)[] = [];
+    const { el } = twoFolders({ onPreview: (id) => seen.push(id) });
+
+    press(tree(el), "j");
+    press(tree(el), "j");
+    expect(seen).toEqual([A, B]);
+
+    tree(el).dispatchEvent(new FocusEvent("blur"));
+    expect(seen.at(-1)).toBe(null);
+  });
+
+  it("asks for a preview of the hovered card, and clears it on the way out", () => {
+    const seen: (string | null)[] = [];
+    const { el } = twoFolders({ onPreview: (id) => seen.push(id) });
+    const card = el.querySelectorAll<HTMLElement>(".tree-leaf")[0];
+
+    card.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, pointerType: "mouse" }));
+    expect(seen).toEqual([A]);
+    // Moving within the same card is not a new preview.
+    card.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, pointerType: "mouse" }));
+    expect(seen).toHaveLength(1);
+
+    tree(el).dispatchEvent(new PointerEvent("pointerleave", { pointerType: "mouse" }));
+    expect(seen.at(-1)).toBe(null);
+  });
+
+  it("ignores touch, where a tap already opens the session", () => {
+    const seen: (string | null)[] = [];
+    const { el } = twoFolders({ onPreview: (id) => seen.push(id) });
+    const card = el.querySelectorAll<HTMLElement>(".tree-leaf")[0];
+    card.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, pointerType: "touch" }));
+    expect(seen).toEqual([]);
+  });
+});

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"],
@@ -1064,7 +1093,6 @@ textarea {
   cursor: pointer;
   font-family: var(--font-mono);
   font-size: var(--fs-12);
-  transition: color var(--dur-fast) var(--ease-out);
 }
 
 .tree-folder-header:hover {
@@ -1076,9 +1104,9 @@ textarea {
   text-align: center;
   color: var(--faint);
   font-size: var(--fs-11);
-  transition:
-    transform var(--dur) var(--ease-out),
-    color var(--dur-fast) var(--ease-out);
+  /* The rotation is the collapse animation and stays; the hover colour is
+     immediate, like the row's own hover. */
+  transition: transform var(--dur) var(--ease-out);
 }
 
 .tree-folder-header[aria-expanded="false"] .chevron {
@@ -1115,33 +1143,42 @@ textarea {
   border-radius: var(--r-1);
   color: var(--ink);
   position: relative;
-  transition:
-    background var(--dur-fast) var(--ease-out),
-    box-shadow var(--dur-fast) var(--ease-out);
+  /* 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);
 }
@@ -1150,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"] {
@@ -2883,6 +2931,42 @@ input.leaf-rename:focus {
   color: var(--ink);
 }
 
+/* Preview (docs/PREVIEW.md): the content pane is showing a session the
+   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 {
+  content: "preview";
+  position: absolute;
+  top: var(--sp-2);
+  right: var(--sp-3);
+  z-index: var(--z-sticky);
+  padding: 1px var(--sp-2);
+  border-radius: var(--r-1);
+  font: 500 var(--fs-11) / 1.5 var(--font-mono);
+  letter-spacing: 0.04em;
+  color: var(--preview-ink);
+  background: var(--preview);
+  opacity: 0.85;
+  pointer-events: none;
+}
+.mv.mv-previewing .mv-canvas::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  border: 1px dashed var(--preview-ring);
+  border-radius: var(--r-1);
+  z-index: var(--z-sticky);
+}
+
 /* canvas + welcome */
 .mv-canvas {
   position: relative;
@@ -2996,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;
@@ -3085,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.

web/src/webglRenderer.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { MAX_CONTEXT_LOSSES, WebglPolicy } from "./webglRenderer.js";
+
+describe("WebglPolicy", () => {
+  it("is enabled when the browser supports WebGL2", () => {
+    expect(new WebglPolicy(() => true).enabled()).toBe(true);
+  });
+
+  it("is disabled when the browser has no WebGL2", () => {
+    expect(new WebglPolicy(() => false).enabled()).toBe(false);
+  });
+
+  it("probes only once, however often it is asked", () => {
+    const probe = vi.fn(() => true);
+    const policy = new WebglPolicy(probe);
+    policy.enabled();
+    policy.enabled();
+    policy.enabled();
+    expect(probe).toHaveBeenCalledTimes(1);
+  });
+
+  it("tolerates a loss below the budget — a backgrounded tab is ordinary", () => {
+    const policy = new WebglPolicy(() => true);
+    policy.noteContextLoss();
+    expect(policy.enabled()).toBe(true);
+  });
+
+  it("gives up for good once losses reach the budget", () => {
+    const policy = new WebglPolicy(() => true);
+    for (let i = 0; i < MAX_CONTEXT_LOSSES; i++) policy.noteContextLoss();
+    expect(policy.enabled()).toBe(false);
+    expect(policy.contextLosses()).toBe(MAX_CONTEXT_LOSSES);
+  });
+
+  it("stays disabled past the budget, and never bothers probing", () => {
+    const probe = vi.fn(() => true);
+    const policy = new WebglPolicy(probe);
+    for (let i = 0; i < MAX_CONTEXT_LOSSES + 3; i++) policy.noteContextLoss();
+    expect(policy.enabled()).toBe(false);
+    expect(probe).not.toHaveBeenCalled();
+  });
+
+  it("treats a throwing probe as unsupported", () => {
+    const policy = new WebglPolicy(() => {
+      throw new Error("no gl for you");
+    });
+    expect(() => policy.enabled()).not.toThrow();
+    expect(policy.enabled()).toBe(false);
+  });
+
+  it("reports no WebGL2 under the test DOM, which has no GPU", () => {
+    expect(new WebglPolicy().enabled()).toBe(false);
+  });
+});

web/src/webglRenderer.ts

@@ -0,0 +1,73 @@
+// WebGL renderer policy for attached terminals. Split out of attach.ts so it
+// can be tested without a DOM or an xterm instance (same reasoning as
+// reconnect.ts).
+//
+// xterm's default renderer builds DOM nodes per cell, which is CPU-bound —
+// exactly the wrong bottleneck on a phone, where a full-screen repaint from an
+// agent dumping output visibly stutters. The WebGL addon moves glyph drawing to
+// a GPU texture atlas instead.
+//
+// The cost is that a WebGL context is a scarce, revocable resource:
+//
+//   * Browsers cap live contexts (~16 on desktop Chrome, fewer on Android) and
+//     silently kill the oldest past the cap. `ConnectionPool` keeps MAX_PARKED
+//     parked connections alive on top of the mounted ones, so handing every
+//     connection its own context would blow that budget on its own and bring a
+//     parked terminal back blank.
+//   * Android drops contexts as routine housekeeping — backgrounding the tab,
+//     locking the screen, memory pressure.
+//
+// So the context follows the *view*, not the connection: acquired on mount,
+// released on park. Losses count against a shared budget, because a device that
+// keeps dropping contexts is telling us it cannot sustain one.
+
+/** Context losses tolerated before the page gives up and stays on the DOM
+ *  renderer. One loss is ordinary (a tab switch); repeated losses mean the
+ *  device is thrashing, and re-acquiring only makes it worse. */
+export const MAX_CONTEXT_LOSSES = 2;
+
+/** Can this browser hand out a WebGL2 context at all? */
+export function probeWebgl2(): boolean {
+  return document.createElement("canvas").getContext("webgl2") !== null;
+}
+
+/**
+ * Whether an attached terminal should try the WebGL renderer right now.
+ *
+ * Shared by every connection on the page: the context budget and the "this
+ * device cannot cope" signal are both global, not per-terminal.
+ */
+export class WebglPolicy {
+  private supported: boolean | null = null;
+  private losses = 0;
+
+  constructor(private readonly probe: () => boolean = probeWebgl2) {}
+
+  /** True while WebGL is both available and still worth attempting. The probe
+   *  runs at most once — support does not change under us, and creating
+   *  throwaway contexts to re-ask would itself consume the budget. */
+  enabled(): boolean {
+    if (this.losses >= MAX_CONTEXT_LOSSES) return false;
+    if (this.supported === null) {
+      try {
+        this.supported = this.probe();
+      } catch {
+        // A browser that throws rather than returning null has no usable
+        // context either way.
+        this.supported = false;
+      }
+    }
+    return this.supported;
+  }
+
+  /** Record a lost context. Past the budget, `enabled()` stays false for the
+   *  life of the page. */
+  noteContextLoss(): void {
+    this.losses += 1;
+  }
+
+  /** Losses recorded so far — for the debug HUD and tests. */
+  contextLosses(): number {
+    return this.losses;
+  }
+}