Merge remote-tracking branch 'origin/main' into timbre-2

Structured sessions spawned with auto_approve lost the flag on daemon
restart because it lived only in the in-memory SessionRecord. Add it to
the Session struct (sidecar JSON) so recovery reads it back instead of
hardcoding false.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/settings.local.json

@@ -1,17 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git fetch:*)",
-      "Bash(git merge:*)",
-      "Bash(npx tsc:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm install:*)",
-      "Bash(./node_modules/.bin/tsc:*)",
-      "Bash(npm test:*)",
-      "Bash(cargo check:*)",
-      "Bash(cargo clippy:*)"
-    ]
-  }
-}

.gitea/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+  cancel-in-progress: true
 
 env:
   CARGO_TERM_COLOR: always

.gitignore

@@ -15,3 +15,6 @@ worktrees/
 
 # `nix run .#dev` scratch state (tmux socket)
 /.dev/
+
+# Per-machine Claude Code tool permissions
+.claude/settings.local.json

crates/maestro-cli/src/cli.rs

@@ -41,8 +41,8 @@ pub enum Command {
     Attach(AttachArgs),
     /// Kill a session by ID.
     Kill(KillArgs),
-    /// Type text into a running session, as if it had been typed on an
-    /// attached terminal.
+    /// Send text to a running session. Terminal sessions receive raw
+    /// keystrokes; structured sessions receive an ACP prompt.
     Send(SendArgs),
     /// Install or update the agent activity hook (#106).
     Hooks(HooksArgs),
@@ -133,7 +133,7 @@ pub struct KillArgs {
     /// Session ID to kill.
     pub session_id: Uuid,
     /// End the session even when its worktree holds unsaved work (#81). The
-    /// worktree is left on disk — never removed.
+    /// worktree is removed along with the session.
     #[arg(long)]
     pub force: bool,
 }

crates/maestro-cli/src/sessions.rs

@@ -130,9 +130,12 @@ pub fn resolve_session(sessions: &[Session], needle: &str) -> Result<uuid::Uuid,
 /// `maestro send`. Answers with the session that was typed into, so the
 /// caller can name it once the daemon has accepted the text.
 ///
-/// A bare ID skips the catalog fetch; anything else needs the list to match
-/// against. Text comes from the arguments, or from stdin when there is none —
-/// the shape a heredoc or a pipe wants.
+/// Terminal sessions get raw keystrokes via `send_input`; structured sessions
+/// get an ACP prompt via `send_structured_prompt` (`--no-enter` is ignored
+/// there — ACP prompts are always complete messages).
+///
+/// Text comes from the arguments, or from stdin when there is none — the
+/// shape a heredoc or a pipe wants.
 #[allow(clippy::result_large_err)]
 pub async fn run_send(
     client: &DaemonClient,
@@ -155,19 +158,28 @@ pub async fn run_send(
         return Err(CliError::NothingToSend);
     }
 
-    let id = match uuid::Uuid::parse_str(args.session.trim()) {
-        Ok(id) => id,
-        Err(_) => {
-            let sessions = client.list_sessions().await?;
-            resolve_session(&sessions, &args.session)?
-        }
-    };
+    // We always need the session list: even a bare UUID needs the view field
+    // to decide which endpoint to hit.
+    let sessions = client.list_sessions().await?;
+    let id = resolve_session(&sessions, &args.session)?;
+    let view = sessions
+        .iter()
+        .find(|s| s.id == id)
+        .map(|s| s.view)
+        .unwrap_or(SessionView::Terminal);
 
-    let req = SendInputRequest {
-        text,
-        submit: !args.no_enter,
-    };
-    client.send_input(id, &req).await?;
+    match view {
+        SessionView::Structured => {
+            client.send_structured_prompt(id, &text).await?;
+        }
+        SessionView::Terminal => {
+            let req = SendInputRequest {
+                text,
+                submit: !args.no_enter,
+            };
+            client.send_input(id, &req).await?;
+        }
+    }
     Ok(id)
 }
 
@@ -216,6 +228,7 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             ActivityState::Idle => "idle",
             ActivityState::AwaitingInput => "awaiting",
             ActivityState::Error => "error",
+            ActivityState::Starting => "starting",
         };
         // Show the live foreground command alongside the spawn command when
         // the daemon has observed one that differs (NAP-340).
@@ -332,6 +345,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-cli/tests/against_mock_daemon.rs

@@ -2,7 +2,7 @@
 //! was unit-tested, but nothing exercised the client, the error decoding, or
 //! the unreachable-daemon path without compiling and forking a real daemon.
 
-use maestro_protocol::{DaemonClient, DaemonInfo};
+use maestro_protocol::{DaemonClient, DaemonInfo, SessionView};
 use maestro_testing::{session, MockDaemon};
 use uuid::Uuid;
 
@@ -202,6 +202,35 @@ async fn send_resolves_a_session_by_name() {
     assert_eq!(sent, id);
 }
 
+/// A structured session routes through the ACP prompt endpoint, not the
+/// terminal input one — `--no-enter` is irrelevant (ACP prompts are
+/// complete messages).
+#[tokio::test]
+async fn send_to_structured_session_uses_acp_prompt() {
+    let mock = MockDaemon::start().await;
+    let id = Uuid::from_u128(13);
+    let mut s = session(id, "/tmp", "claude");
+    s.view = SessionView::Structured;
+    mock.add_session(s);
+
+    let args = maestro_cli::cli::SendArgs {
+        session: id.to_string(),
+        text: vec!["fix".into(), "the".into(), "tests".into()],
+        no_enter: false,
+    };
+    let sent = maestro_cli::sessions::run_send(&mock.client(), &args, &mut std::io::empty())
+        .await
+        .expect("send");
+
+    assert_eq!(sent, id);
+    // Terminal input must stay empty — the message went through ACP.
+    assert!(mock.inputs().is_empty());
+    let prompts = mock.structured_prompts();
+    assert_eq!(prompts.len(), 1);
+    assert_eq!(prompts[0].0, id);
+    assert_eq!(prompts[0].1.prompt, "fix the tests");
+}
+
 #[tokio::test]
 async fn send_to_an_unknown_session_fails_without_typing_anything() {
     let mock = MockDaemon::start().await;

crates/maestro-daemon/src/gitroot.rs

@@ -80,13 +80,22 @@ mod tests {
     }
 
     #[test]
-    fn non_repo_dir_is_none() {
-        // A temp dir with no `.git` anywhere up the chain. Use the temp root so
-        // the walk can't accidentally hit a real repo above the test's cwd.
+    fn non_repo_dir_does_not_find_root_inside_fixture() {
+        // The fixture has no `.git`, so `find_root` must not return a path
+        // inside it. On hosts where an ancestor of the temp dir *is* a repo
+        // (e.g. `/tmp` lives inside a checkout), the function legitimately
+        // returns that ancestor — the test only asserts the fixture itself
+        // was not mistaken for a repo.
         let tmp = tempfile::tempdir().unwrap();
         let sub = tmp.path().join("plain/dir");
         fs::create_dir_all(&sub).unwrap();
-        assert_eq!(find_root(&sub), None);
+        match find_root(&sub) {
+            None => {} // expected on most hosts
+            Some(root) => assert!(
+                !root.starts_with(tmp.path()),
+                "found .git inside the fixture at {root:?}, but none was created"
+            ),
+        }
     }
 
     #[test]

crates/maestro-daemon/src/local_api.rs

@@ -180,7 +180,7 @@ fn dir_error_status(code: &str) -> StatusCode {
 fn session_error_status(code: &str) -> StatusCode {
     match code {
         "not_found" => StatusCode::NOT_FOUND,
-        "invalid_env" => StatusCode::BAD_REQUEST,
+        "invalid_env" | "bad_request" => StatusCode::BAD_REQUEST,
         // A guard refusal is the daemon doing its job, not a failure (#79).
         "kill_guarded" => StatusCode::CONFLICT,
         // The session outlived its pane: nothing to type into, and nothing
@@ -483,7 +483,9 @@ async fn structured_prompt(
     Json(body): Json<StructuredPromptRequest>,
 ) -> Response {
     match s.manager.queue_acp_prompt(id, body.prompt).await {
-        Ok(QueueAcpPrompt::Queued) => StatusCode::NO_CONTENT.into_response(),
+        Ok(QueueAcpPrompt::Queued) | Ok(QueueAcpPrompt::Pending) => {
+            StatusCode::NO_CONTENT.into_response()
+        }
         Ok(QueueAcpPrompt::InFlight) => error_response(
             StatusCode::CONFLICT,
             "turn_in_flight",

crates/maestro-daemon/src/session.rs

@@ -6,12 +6,9 @@
 //! handler interact with tmux.
 
 use std::collections::{HashMap, HashSet};
-use std::future::Future;
 use std::path::PathBuf;
-use std::pin::Pin;
 use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
 use std::sync::{Arc, Weak};
-use std::task::{Context, Poll};
 use std::time::Duration;
 
 use chrono::Utc;
@@ -125,6 +122,9 @@ pub struct SessionRecord {
     /// When `true`, the permission pump auto-responds `AllowAlways` to every
     /// ACP permission request without surfacing it to clients.
     pub auto_approve: bool,
+    /// A prompt submitted while the adapter was still booting (`Starting`).
+    /// The background handshake task drains this on success.
+    pub pending_prompt: Option<String>,
 }
 
 impl SessionRecord {
@@ -134,6 +134,13 @@ impl SessionRecord {
             && self.acp.is_some()
             && self.acp_events.is_some()
     }
+
+    /// The session is structured and still booting its adapter.
+    fn is_starting_structured(&self) -> bool {
+        self.session.view == SessionView::Structured
+            && self.session.activity == ActivityState::Starting
+            && self.acp.is_none()
+    }
 }
 
 #[derive(Debug)]
@@ -208,6 +215,8 @@ pub enum SessionError {
     NotTerminal(Uuid),
     #[error("daemon is shutting down")]
     ShuttingDown,
+    #[error("bad request: {0}")]
+    BadRequest(String),
     /// The kill was refused (#79): the session's worktree holds unsaved work.
     /// Nothing happened — the session keeps running and the tree is untouched,
     /// so it stays the operator's handle on their own unfinished work.
@@ -227,6 +236,8 @@ pub enum BeginAcpTurn {
 #[derive(Debug)]
 pub enum QueueAcpPrompt {
     Queued,
+    /// The adapter is still booting; the prompt is held until it is ready.
+    Pending,
     InFlight,
     Unavailable,
     Failed(String),
@@ -253,6 +264,7 @@ impl SessionError {
             SessionError::NotRunning(_) => "not_running",
             SessionError::NotTerminal(_) => "not_terminal",
             SessionError::ShuttingDown => "shutting_down",
+            SessionError::BadRequest(_) => "bad_request",
             SessionError::KillGuarded(_) => "kill_guarded",
         };
         let unsaved_work = match self {
@@ -320,18 +332,6 @@ struct StructuredLifecycle {
 }
 
 impl StructuredLifecycle {
-    fn admit<'a>(
-        &'a self,
-        shutting_down: &AtomicBool,
-    ) -> Result<StructuredCreate<'a>, SessionError> {
-        let _gate = self.gate.lock().expect("structured lifecycle gate");
-        if shutting_down.load(Ordering::Acquire) {
-            return Err(SessionError::ShuttingDown);
-        }
-        self.in_flight.fetch_add(1, Ordering::AcqRel);
-        Ok(StructuredCreate { lifecycle: self })
-    }
-
     async fn wait_until_settled(&self) {
         loop {
             let settled = self.settled.notified();
@@ -343,30 +343,18 @@ impl StructuredLifecycle {
     }
 }
 
-struct StructuredCreate<'a> {
-    lifecycle: &'a StructuredLifecycle,
-}
-
-impl Drop for StructuredCreate<'_> {
-    fn drop(&mut self) {
-        if self.lifecycle.in_flight.fetch_sub(1, Ordering::AcqRel) == 1 {
-            self.lifecycle.settled.notify_one();
-        }
-    }
-}
-
-struct AdmittedStructuredCreate<'a> {
-    create: Pin<Box<dyn Future<Output = Result<Session, SessionError>> + Send + 'a>>,
-    /// Field order matters: dropping a cancelled create rolls back its inner
-    /// future before this permit releases shutdown's in-flight barrier.
-    _permit: StructuredCreate<'a>,
-}
-
-impl Future for AdmittedStructuredCreate<'_> {
-    type Output = Result<Session, SessionError>;
-
-    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        self.create.as_mut().poll(cx)
+/// Release the structured-lifecycle in-flight counter that `create` acquires
+/// before spawning the background ACP handshake task. Called when the task
+/// finishes (success or failure) or when `create_inner` fails before the task
+/// is spawned.
+fn drop_structured_lifecycle_permit(inner: &Inner) {
+    if inner
+        .structured_lifecycle
+        .in_flight
+        .fetch_sub(1, Ordering::AcqRel)
+        == 1
+    {
+        inner.structured_lifecycle.settled.notify_one();
     }
 }
 
@@ -660,7 +648,9 @@ impl SessionManager {
         let stream = {
             let sessions = self.inner.sessions.lock().await;
             let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
-            if !record.is_live_structured() {
+            // Allow connecting while the adapter is still booting
+            // (`Starting`) — the event stream exists, it is just empty.
+            if !record.is_live_structured() && !record.is_starting_structured() {
                 return Ok(None);
             }
             let Some(stream) = &record.acp_events else {
@@ -745,8 +735,14 @@ impl SessionManager {
         text: String,
     ) -> Result<QueueAcpPrompt, SessionError> {
         let (acp, stream) = {
-            let sessions = self.inner.sessions.lock().await;
-            let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+            let mut sessions = self.inner.sessions.lock().await;
+            let record = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
+            // While the adapter is booting, stash the prompt for the
+            // background handshake task to drain on success.
+            if record.is_starting_structured() {
+                record.pending_prompt = Some(text);
+                return Ok(QueueAcpPrompt::Pending);
+            }
             if !record.is_live_structured() {
                 return Ok(QueueAcpPrompt::Unavailable);
             }
@@ -809,6 +805,10 @@ impl SessionManager {
                             });
                             drop(stream);
                             sync_structured_activity(&self.inner, id).await;
+                            #[cfg(feature = "haiku-autoname")]
+                            if let Ok(true) = self.claim_autoname(id).await {
+                                crate::autoname::spawn_naming(self.clone(), id, text);
+                            }
                             return Ok(QueueAcpPrompt::Queued);
                         }
                         Err(message) => {
@@ -1217,17 +1217,42 @@ impl SessionManager {
     }
 
     /// Spawn a new session. On success returns the freshly-created `Session`.
+    ///
+    /// For structured sessions, the ACP handshake runs in a background task
+    /// after the session is registered — the HTTP caller gets an instant
+    /// response with `activity: Starting`. The `StructuredLifecycle` gate is
+    /// held across the background task so `shutdown()` waits for it.
     pub async fn create(&self, req: CreateSessionRequest) -> Result<Session, SessionError> {
         if req.view == SessionView::Structured {
-            let permit = self
+            // Acquire the lifecycle gate synchronously (rejects if shutting
+            // down). The background handshake task calls
+            // `drop_structured_lifecycle_permit` when it finishes; we must
+            // not use the RAII `StructuredCreate` because it would drop at
+            // the end of `create_inner`, before the handshake completes.
+            let _gate = self
                 .inner
                 .structured_lifecycle
-                .admit(&self.inner.shutting_down)?;
-            return AdmittedStructuredCreate {
-                create: Box::pin(self.create_inner(req)),
-                _permit: permit,
+                .gate
+                .lock()
+                .expect("structured lifecycle gate");
+            if self.inner.shutting_down.load(Ordering::Acquire) {
+                return Err(SessionError::ShuttingDown);
             }
-            .await;
+            self.inner
+                .structured_lifecycle
+                .in_flight
+                .fetch_add(1, Ordering::AcqRel);
+            drop(_gate);
+
+            return match self.create_inner(req).await {
+                Ok(session) => Ok(session),
+                Err(e) => {
+                    // create_inner failed before spawning the background
+                    // task, so release the permit here.
+                    drop_structured_lifecycle_permit(&self.inner);
+                    Err(e)
+                }
+            };
         }
         self.create_inner(req).await
     }
@@ -1289,32 +1314,39 @@ impl SessionManager {
         {
             session_env.insert("MAESTRO_URL".into(), url);
         }
-        // A structured session (#134) gets no tmux pane: the agent is a
-        // child of the daemon, driven over ACP. An adapter that cannot come
-        // up still yields a session — Dead, with the reason on it — so the
-        // operator sees what to fix instead of a silently missing session.
-        let (acp, acp_failure) = match req.view {
-            SessionView::Structured => match structured_adapter(&req.command) {
-                Err(error) => (None, Some(error)),
-                Ok(adapter) => match maestro_acp::spawn(
-                    SpawnConfig::new(
-                        &effective_cwd,
-                        session_env
-                            .iter()
-                            .map(|(k, v)| (k.clone(), v.clone()))
-                            .collect(),
-                    )
-                    .adapter(adapter),
-                )
-                .await
-                {
-                    Ok(acp) => (Some(Arc::new(acp)), None),
-                    Err(e) => {
-                        tracing::warn!(%id, error = %e, "structured session: adapter failed to start");
-                        (None, Some(e.to_string()))
+        // ── Structured path: validate adapter, open event log, register
+        // the session immediately with `Starting`, then handshake in the
+        // background so the HTTP caller gets an instant response.
+        //
+        // ── Terminal path: unchanged — tmux spawn is fast enough to stay
+        // synchronous.
+        // Structured: validate adapter, open event log eagerly. Terminal:
+        // spawn the tmux pane synchronously (it is fast).
+        let structured_spawn = match req.view {
+            SessionView::Structured => {
+                // Fail fast on an unsupported command before touching disk.
+                let adapter = structured_adapter(&req.command).map_err(SessionError::BadRequest)?;
+                // Open the event log eagerly so the structured WS can
+                // connect before the adapter is up.
+                let acp_events = match self.inner.sidecar.open_events(id) {
+                    Ok(log) => {
+                        let (tx, _) = broadcast::channel(EVENTS_CAPACITY);
+                        let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY);
+                        Arc::new(Mutex::new(AcpEventStream {
+                            log,
+                            live: tx,
+                            projection: Projection::default(),
+                            projected_live: projected_tx,
+                            pending_approvals: HashMap::new(),
+                            operation: Arc::new(Mutex::new(())),
+                            dispatch: AcpDispatchState::default(),
+                            activity_sequence: 0,
+                        }))
                     }
-                },
-            },
+                    Err(e) => return Err(SessionError::Sidecar(e)),
+                };
+                Some((adapter, acp_events))
+            }
             SessionView::Terminal => {
                 let spawned = {
                     let tmux = self.inner.tmux.clone();
@@ -1328,53 +1360,10 @@ impl SessionManager {
                 if let Err(e) = spawned {
                     return Err(SessionError::Tmux(e));
                 }
-                (None, None)
+                None
             }
         };
 
-        let acp_events = if let Some(acp) = &acp {
-            let persisted =
-                match self
-                    .inner
-                    .sidecar
-                    .read_events(id, EventCursor::Since(0), usize::MAX)
-                {
-                    Ok(events) => events,
-                    Err(error) => {
-                        acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                            .await;
-                        return Err(SessionError::Sidecar(error));
-                    }
-                };
-            match self.inner.sidecar.open_events(id) {
-                Ok(log) => {
-                    let (tx, _) = broadcast::channel(EVENTS_CAPACITY);
-                    let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY);
-                    let mut projection = Projection::default();
-                    for event in &persisted {
-                        apply_persisted_event(&mut projection, event);
-                    }
-                    Some(Arc::new(Mutex::new(AcpEventStream {
-                        log,
-                        live: tx,
-                        projection,
-                        projected_live: projected_tx,
-                        pending_approvals: HashMap::new(),
-                        operation: Arc::new(Mutex::new(())),
-                        dispatch: AcpDispatchState::default(),
-                        activity_sequence: 0,
-                    })))
-                }
-                Err(e) => {
-                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                        .await;
-                    return Err(SessionError::Sidecar(e));
-                }
-            }
-        } else {
-            None
-        };
-
         // Capture spawn-history inputs before `req` is partially moved into
         // `session`. `history_cwd` is the *chosen* working dir (the request
         // `cwd`), not a generated worktree checkout path — that's what the
@@ -1384,10 +1373,13 @@ impl SessionManager {
         resolve_name(&mut metadata);
         let worktree_branch = req.worktree.as_ref().map(|w| w.branch.clone());
 
+        let is_structured = structured_spawn.is_some();
+        let events_arc = structured_spawn.as_ref().map(|(_, e)| e.clone());
+
         let session = Session {
             id,
-            cwd: effective_cwd,
-            command: req.command,
+            cwd: effective_cwd.clone(),
+            command: req.command.clone(),
             env: req.env,
             metadata,
             worktree: worktree_path.as_ref().zip(worktree_base_repo.as_ref()).map(
@@ -1396,67 +1388,42 @@ impl SessionManager {
                     base_repo: base_repo.clone(),
                 },
             ),
-            status: if acp_failure.is_some() {
-                SessionStatus::Dead
-            } else {
-                SessionStatus::Running
-            },
+            status: SessionStatus::Running,
             created_at: Utc::now(),
-            // A terminal spawn begins active until its watcher sees otherwise;
-            // a structured spawn has no turn yet and begins idle.
             foreground: None,
-            activity: match (req.view, acp_failure.is_some()) {
-                (_, true) => ActivityState::Error,
-                (SessionView::Structured, false) => ActivityState::Idle,
-                (SessionView::Terminal, false) => ActivityState::Active,
+            activity: if is_structured {
+                ActivityState::Starting
+            } else {
+                ActivityState::Active
             },
-            activity_detail: acp_failure,
+            activity_detail: None,
             last_activity_at: Utc::now(),
             activity_since: chrono::Utc::now(),
-
             current_cwd: None,
-            // The watcher fills this in on its first blocked-work pass; a
-            // fresh tree has nothing in the way anyway.
             blocked_work: None,
             last_focused_at: None,
-            acp_session_id: acp.as_ref().map(|a| a.session_id().to_string()),
+            acp_session_id: None,
             view: req.view,
+            auto_approve: req.auto_approve,
         };
 
         if let Err(e) = self.inner.sidecar.write(&session) {
-            // The process already started; end it so no ghost survives a
-            // failed sidecar write, then unwind the FIFO + worktree.
-            match &acp {
-                Some(acp) => {
-                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                        .await
-                }
-                None => {
-                    let tmux = self.inner.tmux.clone();
-                    let _ = tmux_blocking(move || tmux.kill_session(id)).await;
-                }
+            if !is_structured {
+                let tmux = self.inner.tmux.clone();
+                let _ = tmux_blocking(move || tmux.kill_session(id)).await;
             }
             return Err(SessionError::Sidecar(e));
         }
 
-        let event_pump = acp
-            .as_ref()
-            .zip(acp_events.as_ref())
-            .map(|(acp, events)| (acp.clone(), events.clone()));
         {
             let mut sessions = self.inner.sessions.lock().await;
-            let event_pump = event_pump.map(|(acp, events)| {
-                let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
-                start_acp_permission_pump(&self.inner, id, &acp, events, req.auto_approve);
-                done
-            });
             sessions.insert(
                 id,
                 SessionRecord {
                     session: session.clone(),
                     fifo_path,
-                    worktree_path,
-                    worktree_base_repo,
+                    worktree_path: worktree_path.clone(),
+                    worktree_base_repo: worktree_base_repo.clone(),
                     bridge,
                     reported_activity: None,
                     settled: false,
@@ -1464,11 +1431,12 @@ impl SessionManager {
                     naming: false,
                     focused_since: None,
                     awaiting_suppressed: false,
-                    acp,
-                    acp_events,
+                    acp: None,
+                    acp_events: events_arc,
                     structured_activity_watermark: None,
-                    acp_event_pump: event_pump,
+                    acp_event_pump: None,
                     auto_approve: req.auto_approve,
+                    pending_prompt: None,
                 },
             );
         }
@@ -1497,6 +1465,78 @@ impl SessionManager {
         }
 
         pending.commit();
+
+        // ── Background ACP handshake for structured sessions ──
+        //
+        // The session is registered and visible to clients. The adapter
+        // spawn + handshake runs in a background task; on completion it
+        // fills in `acp`, starts the event/permission pumps, and
+        // transitions activity from `Starting` to `Idle` (or to `Error`
+        // on failure). The `StructuredLifecycle` permit is held until the
+        // task finishes so `shutdown()` waits for it.
+        if let Some((adapter, events)) = structured_spawn {
+            let inner = self.inner.clone();
+            let env: HashMap<String, String> = session_env
+                .iter()
+                .map(|(k, v)| (k.clone(), v.clone()))
+                .collect();
+            let cwd = effective_cwd;
+            let auto_approve = req.auto_approve;
+            tokio::spawn(async move {
+                let result = maestro_acp::spawn(SpawnConfig::new(&cwd, env).adapter(adapter)).await;
+
+                match result {
+                    Ok(acp_session) => {
+                        let acp = Arc::new(acp_session);
+                        let done = start_acp_event_pump(&inner, id, &acp, events.clone());
+                        start_acp_permission_pump(&inner, id, &acp, events.clone(), auto_approve);
+                        // Drain any prompt submitted while Starting.
+                        let pending_prompt = {
+                            let mut sessions = inner.sessions.lock().await;
+                            let Some(record) = sessions.get_mut(&id) else {
+                                // Session was killed while we were booting.
+                                acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+                                    .await;
+                                drop_structured_lifecycle_permit(&inner);
+                                return;
+                            };
+                            record.acp = Some(acp.clone());
+                            record.acp_event_pump = Some(done);
+                            record.session.acp_session_id = Some(acp.session_id().to_string());
+                            record.session.activity = ActivityState::Idle;
+                            record.session.activity_since = Utc::now();
+                            let _ = inner.sidecar.write(&record.session);
+                            let _ = inner.events.send(CatalogEvent::SessionUpdated {
+                                session: record.session.clone(),
+                            });
+                            record.pending_prompt.take()
+                        };
+                        if let Some(prompt) = pending_prompt {
+                            let manager = SessionManager {
+                                inner: inner.clone(),
+                            };
+                            let _ = manager.queue_acp_prompt(id, prompt).await;
+                        }
+                    }
+                    Err(e) => {
+                        tracing::warn!(%id, error = %e, "structured session: adapter failed to start");
+                        let mut sessions = inner.sessions.lock().await;
+                        if let Some(record) = sessions.get_mut(&id) {
+                            record.session.status = SessionStatus::Dead;
+                            record.session.activity = ActivityState::Error;
+                            record.session.activity_detail = Some(e.to_string());
+                            record.session.activity_since = Utc::now();
+                            let _ = inner.sidecar.write(&record.session);
+                            let _ = inner.events.send(CatalogEvent::SessionUpdated {
+                                session: record.session.clone(),
+                            });
+                        }
+                    }
+                }
+                drop_structured_lifecycle_permit(&inner);
+            });
+        }
+
         Ok(session)
     }
 
@@ -1506,15 +1546,10 @@ impl SessionManager {
     /// uncommitted tracked changes, untracked non-ignored files, or commits
     /// reachable from no remote-tracking ref. Nothing is killed and nothing
     /// is removed; the error names what blocked it and how much of it there
-    /// is. The session stays as the operator's handle on their own unfinished
-    /// work, so ending a session that still matters becomes a deliberate
-    /// `--force`, which leaves the tree alone rather than destroying it
-    /// (WORKTREES.md).
+    /// is.
     ///
-    /// With `force` (#81) the refusal — and nothing else — is overridden:
-    /// the session ends and the guarded worktree is left on disk, never
-    /// removed. A tree whose guard is clear never needed the override; force
-    /// removes it as usual.
+    /// With `force` (#81) the refusal is overridden: the session ends and
+    /// the worktree is removed, even when it holds unsaved work.
     ///
     /// This is also how an already-dead session is dismissed. tmux is only
     /// asked to kill something it still has — calling `kill-session` on a
@@ -1549,7 +1584,7 @@ impl SessionManager {
             sessions.remove(&id)
         };
         let record = removed.ok_or(SessionError::NotFound(id))?;
-        cleanup_record(&self.inner, id, record, alive, guarded).await;
+        cleanup_record(&self.inner, id, record, alive).await;
         Ok(())
     }
 
@@ -1644,6 +1679,7 @@ impl SessionManager {
                     // Unknown on adoption without a sidecar; matches every
                     // other field's forward-compat default.
                     view: maestro_protocol::SessionView::Terminal,
+                    auto_approve: false,
                 },
             };
             let fifo_path = self.inner.fifo_dir.join(format!("{id}.fifo"));
@@ -1681,7 +1717,8 @@ impl SessionManager {
                     acp_events: None,
                     structured_activity_watermark: None,
                     acp_event_pump: None,
-                    auto_approve: false,
+                    auto_approve: session.auto_approve,
+                    pending_prompt: None,
                 },
             );
             let _ = self
@@ -1859,14 +1896,13 @@ impl SessionManager {
                     acp_events,
                     structured_activity_watermark: None,
                     acp_event_pump: None,
-                    // Recovery cannot know the original preset's flag; the
-                    // operator re-enables it by restarting with the preset.
-                    auto_approve: false,
+                    auto_approve: session.auto_approve,
+                    pending_prompt: None,
                 },
             );
             if let Some((acp, events)) = event_pump {
                 let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
-                start_acp_permission_pump(&self.inner, id, &acp, events, false);
+                start_acp_permission_pump(&self.inner, id, &acp, events, session.auto_approve);
                 if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
                     record.acp_event_pump = Some(done);
                 }
@@ -2321,6 +2357,11 @@ async fn apply_structured_activity(
     if record.session.view != SessionView::Structured {
         return;
     }
+    // While the adapter is still booting, the background handshake task
+    // owns the activity state — the activity pass must not overwrite it.
+    if record.session.activity == ActivityState::Starting {
+        return;
+    }
     let current_events = record.acp_events.as_ref();
     match (expected_events, current_events) {
         (Some((expected, sequence)), Some(current)) if Arc::ptr_eq(expected, current) => {
@@ -2586,6 +2627,12 @@ async fn run_liveness_pass(inner: &Arc<Inner>) {
         let mut tmux_backed = Vec::new();
         let mut acp_backed = Vec::new();
         for (id, record) in running {
+            if record.is_starting_structured() {
+                // The adapter hasn't finished its handshake yet — no ACP
+                // handle and no tmux pane. Skip; the background task owns
+                // this session's lifecycle until the handshake settles.
+                continue;
+            }
             match &record.acp {
                 Some(acp) => acp_backed.push((*id, acp.clone())),
                 None => tmux_backed.push(*id),
@@ -2864,17 +2911,16 @@ async fn mark_session_dead_with_worktree_settlement(
                 // Release anyone attached; the scrollback survives for a later
                 // attach.
                 record.bridge.seal();
-                let session = record.session.clone();
                 let worktree = record
                     .worktree_base_repo
                     .clone()
                     .zip(record.worktree_path.clone());
-                Some((session, worktree))
+                Some(worktree)
             }
             _ => None,
         }
     };
-    let Some((mut session, worktree)) = flipped else {
+    let Some(worktree) = flipped else {
         return false;
     };
     let stream = inner
@@ -2891,9 +2937,6 @@ async fn mark_session_dead_with_worktree_settlement(
     if settle_worktree {
         if let Some(wt) = &worktree {
             if settle_worktree_on_exit(inner, id, wt).await {
-                // The tree is settled (removed); a stale "in the way" would
-                // describe something the session no longer holds.
-                session.blocked_work = None;
                 let mut sessions = inner.sessions.lock().await;
                 if let Some(record) = sessions.get_mut(&id) {
                     record.session.worktree = None;
@@ -2905,13 +2948,17 @@ async fn mark_session_dead_with_worktree_settlement(
         }
     }
     // Settle has now been applied or refused either way (#115): from here on
-    // its outcomes are safe to observe.
-    {
+    // its outcomes are safe to observe. Re-read the session from the record
+    // so the sidecar write includes any updates (e.g. a haiku rename) that
+    // landed between the initial clone and now.
+    let session = {
         let mut sessions = inner.sessions.lock().await;
-        if let Some(record) = sessions.get_mut(&id) {
-            record.settled = true;
-        }
-    }
+        let Some(record) = sessions.get_mut(&id) else {
+            return false;
+        };
+        record.settled = true;
+        record.session.clone()
+    };
 
     let _ = inner.sidecar.write(&session);
     let _ = inner.events.send(CatalogEvent::SessionUpdated { session });
@@ -2920,8 +2967,8 @@ async fn mark_session_dead_with_worktree_settlement(
 
 /// Apply the exit rule (#82) to a vanished session's worktree: probe what
 /// would be lost through the kill's own predicate, then remove a pristine
-/// tree. Anything holding unsaved work is left exactly where it is — the
-/// same thing a forced kill does with a guarded tree (#81).
+/// tree. Anything holding unsaved work is left on disk — there is no
+/// operator confirmation on the natural-exit path.
 ///
 /// Returns whether the worktree was fully accounted for. When it wasn't,
 /// nothing was destroyed and the caller keeps the reference on the record.
@@ -2976,17 +3023,7 @@ async fn settle_worktree_on_exit(
 /// gone from the authoritative in-memory map, so a stray FIFO or sidecar can't
 /// resurrect it. `kill_tmux` is `true` for an explicit kill and `false` for the
 /// liveness reaper (tmux already lost the session).
-///
-/// `keep_worktree` is `true` for a forced kill (#81) over a guarded tree: the
-/// session ends but the worktree is left on disk, so only the removal is
-/// skipped.
-async fn cleanup_record(
-    inner: &Arc<Inner>,
-    id: Uuid,
-    record: SessionRecord,
-    kill_tmux: bool,
-    keep_worktree: bool,
-) {
+async fn cleanup_record(inner: &Arc<Inner>, id: Uuid, record: SessionRecord, kill_tmux: bool) {
     if kill_tmux {
         let tmux = inner.tmux.clone();
         let _ = tmux_blocking(move || tmux.kill_session(id)).await;
@@ -3007,17 +3044,7 @@ async fn cleanup_record(
         tracing::warn!(error = ?e, %id, "cleanup: failed to delete sidecar");
     }
     if let (Some(base), Some(path)) = (&record.worktree_base_repo, &record.worktree_path) {
-        if keep_worktree {
-            tracing::info!(
-                %id,
-                path = %path.display(),
-                "forced kill: worktree left on disk"
-            );
-        } else if let Err(e) = inner.worktree_mgr.remove(base, path) {
-            // The kill already passed the unsaved-work guard (#79), so this
-            // removal is unconditional; the manager's own nested-worktree
-            // refusal is all that can still leave a tree on disk, and it
-            // says where.
+        if let Err(e) = inner.worktree_mgr.remove(base, path) {
             tracing::warn!(
                 %id,
                 path = %path.display(),

crates/maestro-daemon/tests/acp.rs

@@ -130,6 +130,25 @@ async fn wait_for_exit(pid: u32) {
     assert!(!pid_alive(pid), "pid {pid} still alive");
 }
 
+/// Wait for a session's background ACP handshake to complete (activity
+/// transitions out of `Starting`). Returns the refreshed session.
+async fn wait_for_ready(manager: &SessionManager, id: uuid::Uuid) -> maestro_protocol::Session {
+    let deadline = Instant::now() + Duration::from_secs(10);
+    loop {
+        let session = manager
+            .snapshot()
+            .await
+            .into_iter()
+            .find(|s| s.id == id)
+            .expect("session exists");
+        if session.activity != ActivityState::Starting {
+            return session;
+        }
+        assert!(Instant::now() < deadline, "handshake timed out");
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+}
+
 #[tokio::test]
 async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let fx = DaemonFixture::new();
@@ -138,7 +157,7 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
 
-    let session = fx
+    let created = fx
         .manager
         .create(structured_command(
             cwd.path(),
@@ -148,8 +167,12 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
         .await
         .expect("create");
 
-    assert_eq!(session.view, SessionView::Structured);
-    assert_eq!(session.status, SessionStatus::Running);
+    assert_eq!(created.view, SessionView::Structured);
+    assert_eq!(created.status, SessionStatus::Running);
+    assert_eq!(created.activity, ActivityState::Starting);
+    assert!(created.acp_session_id.is_none());
+
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.activity, ActivityState::Idle);
     let acp_id = session.acp_session_id.clone().expect("acp session id");
     assert!(acp_id.starts_with("fake-"), "{acp_id}");
@@ -164,7 +187,7 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
         "{log}"
     );
     assert!(
-        log.contains(&format!("env MAESTRO_SESSION_ID={}", session.id)),
+        log.contains(&format!("env MAESTRO_SESSION_ID={}", created.id)),
         "{log}"
     );
 
@@ -232,6 +255,7 @@ async fn structured_activity_tracks_turn_completion_and_failure() {
         .create(structured_command(cwd.path(), env, "codex"))
         .await
         .unwrap();
+    let session = wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -295,11 +319,12 @@ async fn projection_snapshot_and_live_stream_share_one_fold() {
     let fx = DaemonFixture::new();
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let session = fx
+    let created = fx
         .manager
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
 
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -397,6 +422,7 @@ async fn queued_prompt_is_a_durable_user_transcript_row() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -442,6 +468,7 @@ async fn stale_turn_completion_cannot_end_the_next_turn() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     let maestro_daemon::session::BeginAcpTurn::Started(_, first) =
         fx.manager.begin_acp_turn(session.id).await.unwrap()
@@ -485,6 +512,7 @@ async fn cancelled_prompt_that_never_settles_fails_the_session() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -523,6 +551,7 @@ async fn cancellation_settlement_allows_the_next_prompt_permission() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -582,11 +611,12 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_LOAD_REPLAY".into(), "2".into());
 
-    let session = fx
+    let created = fx
         .manager
         .create(structured_command(cwd.path(), env, "codex"))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
     let acp_id = session.acp_session_id.clone().expect("acp id");
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -711,6 +741,7 @@ async fn shutdown_preserves_a_pristine_structured_worktree_for_recovery() {
         .await
         .expect("create");
     assert_eq!(session.cwd, worktree);
+    wait_for_ready(&fx.manager, session.id).await;
     push_all_to_origin(repo.path(), origin.path());
 
     fx.manager.shutdown().await;
@@ -759,6 +790,7 @@ async fn failed_recovery_cleans_its_fifo() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let old_pid = fake.pid();
     fx.manager.shutdown().await;
     wait_for_exit(old_pid).await;
@@ -792,12 +824,15 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
         empty.path().to_string_lossy().into_owned(),
     )]);
 
-    let session = fx
+    let created = fx
         .manager
         .create(structured_command(cwd.path(), env, "codex"))
         .await
-        .expect("a failed session, not an error");
+        .expect("create registers a Starting session");
+    assert_eq!(created.activity, ActivityState::Starting);
 
+    // The background handshake fails because the adapter binary is missing.
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.status, SessionStatus::Dead);
     assert_eq!(session.activity, ActivityState::Error);
     let detail = session.activity_detail.clone().expect("actionable detail");
@@ -810,13 +845,13 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
 
     // It is a real session: listed, on disk, and dismissable like any other
     // dead one.
-    assert!(fx.manager.has(session.id).await);
+    assert!(fx.manager.has(created.id).await);
     assert!(fx
         .sidecar_dir()
-        .join(format!("{}.json", session.id))
+        .join(format!("{}.json", created.id))
         .exists());
-    fx.manager.kill(session.id, false).await.expect("dismiss");
-    assert!(!fx.manager.has(session.id).await);
+    fx.manager.kill(created.id, false).await.expect("dismiss");
+    assert!(!fx.manager.has(created.id).await);
 }
 
 #[tokio::test]
@@ -825,20 +860,20 @@ async fn unsupported_structured_command_fails_without_launching_claude() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
 
-    let session = fx
+    let err = fx
         .manager
         .create(structured_command(cwd.path(), fake.env(), "opencode"))
         .await
-        .expect("failed structured session is persisted");
+        .expect_err("unsupported command is rejected at request validation");
 
-    assert_eq!(session.status, SessionStatus::Dead);
-    let detail = session.activity_detail.expect("selection error");
-    assert!(detail.contains("Claude Code or Codex"), "{detail}");
+    assert!(
+        matches!(err, maestro_daemon::SessionError::BadRequest(ref msg) if msg.contains("Claude Code or Codex")),
+        "{err:?}"
+    );
     assert!(
         fake.log().is_empty(),
         "unsupported command launched an adapter"
     );
-    fx.manager.kill(session.id, false).await.expect("dismiss");
 }
 
 #[tokio::test]
@@ -853,6 +888,7 @@ async fn kill_sends_cancel_then_sigterm_and_removes_the_sidecar() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     assert!(pid_alive(pid));
 
@@ -895,6 +931,8 @@ async fn shutdown_reaps_every_adapter_child() {
         .create(structured(cwd.path(), b.env()))
         .await
         .expect("create b");
+    wait_for_ready(&fx.manager, sa.id).await;
+    wait_for_ready(&fx.manager, sb.id).await;
     let (pa, pb) = (a.pid(), b.pid());
     assert!(pid_alive(pa) && pid_alive(pb));
 
@@ -929,10 +967,13 @@ async fn dismissal_during_shutdown_does_not_restore_recovery_artifacts() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
-    fx.manager
+    let blocker_session = fx
+        .manager
         .create(structured(cwd.path(), blocker.env()))
         .await
         .expect("create blocker");
+    wait_for_ready(&fx.manager, session.id).await;
+    wait_for_ready(&fx.manager, blocker_session.id).await;
 
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
@@ -984,6 +1025,7 @@ async fn shutdown_does_not_recover_an_adapter_that_already_exited() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_exit(fake.pid()).await;
 
     fx.manager.shutdown().await;
@@ -1017,23 +1059,31 @@ async fn shutdown_waits_for_structured_creation_and_rejects_new_creates() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_DELAY_SESSION_NEW_MS".into(), "500".into());
 
-    let create_cwd = cwd.path().to_path_buf();
-    let manager = fx.manager.clone();
-    let create = tokio::spawn(async move { manager.create(structured(&create_cwd, env)).await });
+    // create() returns immediately; the handshake runs in the background
+    // and holds a lifecycle permit.
+    let session = fx
+        .manager
+        .create(structured(cwd.path(), env))
+        .await
+        .expect("create");
+
+    // Wait until the adapter has received session/new (handshake in progress).
     wait_for_async(Duration::from_secs(5), || async {
         fake.log().contains("recv session/new")
     })
     .await;
 
+    // Shutdown must wait for the in-flight background handshake.
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
     tokio::time::sleep(Duration::from_millis(50)).await;
     assert!(
         !shutdown.is_finished(),
-        "shutdown returned before create finished"
+        "shutdown returned before handshake finished"
     );
 
-    let session = create.await.expect("create task").expect("create");
+    // The handshake completes in the background (500ms delay).
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     shutdown.await.expect("shutdown task");
 
@@ -1066,27 +1116,37 @@ async fn structured_handshakes_run_independently() {
         gate.to_string_lossy().into_owned(),
     );
 
-    let first_cwd = cwd.path().to_path_buf();
-    let manager = fx.manager.clone();
-    let first =
-        tokio::spawn(async move { manager.create(structured(&first_cwd, blocked_env)).await });
-    wait_for_async(Duration::from_secs(5), || async {
-        blocked.log().contains("recv session/new")
-    })
-    .await;
+    // Both create() calls return immediately with Starting; the first
+    // adapter's handshake is gated while the second runs freely.
+    let first = fx
+        .manager
+        .create(structured(cwd.path(), blocked_env))
+        .await
+        .expect("first create");
+    let second = fx
+        .manager
+        .create(structured(cwd.path(), ready.env()))
+        .await
+        .expect("second create");
 
-    let second = tokio::time::timeout(
-        Duration::from_secs(5),
-        fx.manager.create(structured(cwd.path(), ready.env())),
-    )
-    .await
-    .expect("second handshake was blocked by the first")
-    .expect("second create");
-    assert_eq!(second.status, SessionStatus::Running);
-    assert!(!first.is_finished(), "the gate must still block the first");
+    // The second handshake completes independently of the first.
+    let second_ready = wait_for_ready(&fx.manager, second.id).await;
+    assert_eq!(second_ready.activity, ActivityState::Idle);
+
+    // The first handshake is still blocked.
+    let first_snap = fx
+        .manager
+        .snapshot()
+        .await
+        .into_iter()
+        .find(|s| s.id == first.id)
+        .unwrap();
+    assert_eq!(first_snap.activity, ActivityState::Starting);
 
     std::fs::write(&gate, b"release").unwrap();
-    let first = first.await.expect("first task").expect("first create");
+    let first_ready = wait_for_ready(&fx.manager, first.id).await;
+    assert_eq!(first_ready.activity, ActivityState::Idle);
+
     fx.manager.kill(first.id, false).await.expect("kill first");
     fx.manager
         .kill(second.id, false)
@@ -1114,16 +1174,18 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
         gate_b.to_string_lossy().into_owned(),
     );
 
-    let create_a = {
-        let manager = fx.manager.clone();
-        let cwd = cwd.path().to_path_buf();
-        tokio::spawn(async move { manager.create(structured(&cwd, env_a)).await })
-    };
-    let create_b = {
-        let manager = fx.manager.clone();
-        let cwd = cwd.path().to_path_buf();
-        tokio::spawn(async move { manager.create(structured(&cwd, env_b)).await })
-    };
+    // Both create() calls return immediately; the background handshake
+    // tasks hold lifecycle permits and are blocked on their gates.
+    let session_a = fx
+        .manager
+        .create(structured(cwd.path(), env_a))
+        .await
+        .expect("create a");
+    let session_b = fx
+        .manager
+        .create(structured(cwd.path(), env_b))
+        .await
+        .expect("create b");
     wait_for_async(Duration::from_secs(5), || async {
         a.log().contains("recv session/new") && b.log().contains("recv session/new")
     })
@@ -1143,14 +1205,14 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
     assert!(!shutdown.is_finished());
 
     std::fs::write(&gate_a, b"release").unwrap();
-    let session_a = create_a.await.expect("create a task").expect("create a");
+    wait_for_ready(&fx.manager, session_a.id).await;
     assert!(
         !shutdown.is_finished(),
         "shutdown ignored the second create"
     );
 
     std::fs::write(&gate_b, b"release").unwrap();
-    let session_b = create_b.await.expect("create b task").expect("create b");
+    wait_for_ready(&fx.manager, session_b.id).await;
     shutdown.await.expect("shutdown task");
 
     wait_for_exit(a.pid()).await;
@@ -1166,7 +1228,7 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
 }
 
 #[tokio::test]
-async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
+async fn killing_a_starting_session_rolls_back_and_settles_admission() {
     let fx = DaemonFixture::new();
     let fake = Fake::new();
     let repo = TempDir::new().unwrap();
@@ -1192,40 +1254,30 @@ async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
         auto_approve: false,
     };
 
-    let create = {
-        let manager = fx.manager.clone();
-        tokio::spawn(async move { manager.create(request).await })
-    };
+    // create() returns immediately with Starting; the handshake is gated.
+    let session = fx.manager.create(request).await.expect("create");
+    assert_eq!(session.activity, ActivityState::Starting);
     wait_for_async(Duration::from_secs(5), || async {
         fake.log().contains("recv session/new")
     })
     .await;
-    let id = fake
-        .log()
-        .lines()
-        .find_map(|line| line.strip_prefix("env MAESTRO_SESSION_ID="))
-        .and_then(|id| uuid::Uuid::parse_str(id).ok())
-        .expect("session id in adapter log");
     let pid = fake.pid();
 
-    create.abort();
-    let shutdown = {
-        let manager = fx.manager.clone();
-        tokio::spawn(async move { manager.shutdown().await })
-    };
-    assert!(create.await.unwrap_err().is_cancelled());
-    tokio::time::timeout(Duration::from_secs(5), shutdown)
+    // Kill the session while its handshake is still in progress.
+    // force=true because the worktree has an unpushed branch commit.
+    fx.manager.kill(session.id, true).await.expect("kill");
+
+    // Release the gate so the background task can finish and settle.
+    std::fs::write(&gate, b"release").unwrap();
+
+    // Shutdown must not hang — the lifecycle permit is settled.
+    tokio::time::timeout(Duration::from_secs(5), fx.manager.shutdown())
         .await
-        .expect("cancelled admission kept shutdown waiting")
-        .expect("shutdown task");
+        .expect("shutdown hung on a settled permit");
+
     wait_for_exit(pid).await;
-    wait_for_async(Duration::from_secs(5), || async {
-        !fx.fifo_dir().join(format!("{id}.fifo")).exists()
-            && !repo.path().join("cancelled-create").exists()
-    })
-    .await;
     assert!(fx.manager.snapshot().await.is_empty());
-    let id = id.to_string();
+    let id = session.id.to_string();
     assert!(
         std::fs::read_dir(fx.sidecar_dir())
             .into_iter()
@@ -1235,7 +1287,7 @@ async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
                 .file_name()
                 .to_string_lossy()
                 .starts_with(&id)),
-        "cancelled create left a sidecar artifact"
+        "killed Starting session left a sidecar artifact"
     );
 }
 
@@ -1252,6 +1304,7 @@ async fn shutdown_drains_final_notifications_to_the_log() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
             .read_acp_events(session.id, EventCursor::Since(0), 10)
@@ -1282,6 +1335,7 @@ async fn adapter_exit_marks_the_session_dead_and_keeps_it_listed() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     fx.manager.start_liveness_watcher(Duration::from_millis(50));
 
     // The agent dies out from under the daemon: the liveness pass, not tmux,

crates/maestro-daemon/tests/autoname.rs

@@ -11,14 +11,14 @@ use common::TmuxFixture;
 use maestro_daemon::sidecar::SidecarStore;
 use maestro_daemon::worktree::WorktreeManager;
 use maestro_daemon::SessionManager;
-use maestro_protocol::{display, CatalogEvent, CreateSessionRequest, NameSource};
+use maestro_protocol::{display, CatalogEvent, CreateSessionRequest, NameSource, SessionStatus};
 use tempfile::TempDir;
 use uuid::Uuid;
 
 struct Fixture {
     manager: SessionManager,
     sidecar: SidecarStore,
-    _tmux: TmuxFixture,
+    tmux: TmuxFixture,
     _state_dir: TempDir,
 }
 
@@ -35,7 +35,7 @@ fn fixture() -> Fixture {
     Fixture {
         manager,
         sidecar,
-        _tmux: tmux,
+        tmux,
         _state_dir: state_dir,
     }
 }
@@ -171,3 +171,37 @@ async fn a_blank_name_changes_nothing() {
     let live = fx.sidecar.read(id).unwrap().unwrap();
     assert_eq!(display::name_source(&live), NameSource::Generated);
 }
+
+/// A session that dies naturally (liveness watcher marks it dead) must not
+/// overwrite a haiku rename that landed before the death. Regression test for
+/// the stale-clone sidecar write in `mark_session_dead`.
+#[tokio::test]
+async fn session_death_preserves_the_haiku_name() {
+    let fx = fixture();
+    let id = spawn(&fx.manager, None).await;
+
+    fx.manager.claim_autoname(id).await.unwrap();
+    fx.manager.apply_autoname(id, "haiku-name").await.unwrap();
+
+    // Verify the sidecar has Haiku before the session dies.
+    let before = fx.sidecar.read(id).unwrap().unwrap();
+    assert_eq!(display::name_source(&before), NameSource::Haiku);
+
+    // Kill the tmux session directly so the liveness watcher picks it up.
+    fx.tmux.tmux.kill_session(id).expect("kill tmux directly");
+    fx.manager
+        .start_liveness_watcher(std::time::Duration::from_millis(25));
+
+    common::wait_for_async(std::time::Duration::from_secs(3), || async {
+        fx.manager.status(id).await == Some(SessionStatus::Dead)
+    })
+    .await;
+
+    let after = fx.sidecar.read(id).unwrap().unwrap();
+    assert_eq!(
+        display::name_source(&after),
+        NameSource::Haiku,
+        "mark_session_dead must not overwrite a haiku rename in the sidecar"
+    );
+    assert_eq!(display::custom_name(&after), Some("haiku-name"));
+}

crates/maestro-daemon/tests/embedded_bundle.rs

@@ -13,14 +13,14 @@ async fn embedded_index_is_real_spa_not_placeholder() {
     let html = String::from_utf8(body.to_vec()).unwrap();
 
     assert!(
-        html.contains(r#"id="app""#),
+        html.contains(r#"id="root""#),
         "served index is missing the SPA mount point; got:\n{html}"
     );
     assert!(
         !html.contains("maestro is running"),
         "served index is the placeholder, not the built bundle"
     );
-    // Stronger signal than `id="app"` (which appears in both source and built
+    // Stronger signal than `id="root"` (which appears in both source and built
     // HTML): the vite build rewrites the entry to a hashed `/assets/index-<hash>`
     // bundle, whereas the un-built source references `/src/main.ts`. This catches
     // both an empty/placeholder embed and the staleness case.

crates/maestro-daemon/tests/local_api.rs

@@ -154,7 +154,8 @@ async fn structured_session(h: &Harness, fake: &FakeAcp) -> Uuid {
 }
 
 async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>) -> Uuid {
-    h.manager
+    let id = h
+        .manager
         .create(CreateSessionRequest {
             view: SessionView::Structured,
             cwd: "/tmp".into(),
@@ -166,7 +167,9 @@ async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>)
         })
         .await
         .unwrap()
-        .id
+        .id;
+    wait_for_session_activity(h, id, ActivityState::Idle).await;
+    id
 }
 
 async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
@@ -1000,7 +1003,9 @@ async fn names_honors_count_and_caps_it() {
 #[tokio::test]
 async fn gitroot_probes_path() {
     // #26: resolves the query against the daemon home dir and walks up for a
-    // `.git`. A `/tmp`-rooted temp dir is not in a repo, so the root is null.
+    // `.git`. The tempdir itself has no `.git`, so the result must either be
+    // null (no repo anywhere above) or — in sandboxed environments where /tmp
+    // itself sits inside a repo — a path strictly above the tempdir.
     let h = spawn("naps-laptop").await;
     let tmp = tempfile::tempdir().unwrap();
     let resp: serde_json::Value = reqwest::get(url(
@@ -1015,7 +1020,16 @@ async fn gitroot_probes_path() {
     .json()
     .await
     .unwrap();
-    assert!(resp.get("root").is_none() || resp["root"].is_null());
+    // On hosts where an ancestor of the temp dir is a repo (e.g. `/tmp`
+    // inside a checkout), the root legitimately points there. The test only
+    // asserts no root was found *inside* the temp dir.
+    match resp.get("root").and_then(|v| v.as_str()) {
+        None => {}
+        Some(root) => assert!(
+            !root.starts_with(tmp.path().to_string_lossy().as_ref()),
+            "found a repo root inside the fixture at {root:?}"
+        ),
+    }
 }
 
 #[tokio::test]
@@ -1494,6 +1508,12 @@ async fn events_ws_streams_structured_activity_without_hook_overrides() {
     let maestro_protocol::CatalogEvent::SessionAdded { session } = next_event(&mut ws).await else {
         panic!("expected structured SessionAdded")
     };
+    assert_eq!(session.activity, ActivityState::Starting);
+    // The background handshake completes and sends SessionUpdated → Idle.
+    let maestro_protocol::CatalogEvent::SessionUpdated { session } = next_event(&mut ws).await
+    else {
+        panic!("expected SessionUpdated after handshake")
+    };
     assert_eq!(session.activity, ActivityState::Idle);
 
     let client = reqwest::Client::new();

crates/maestro-daemon/tests/sidecar.rs

@@ -34,6 +34,7 @@ fn sample(id: Uuid) -> Session {
         last_focused_at: None,
         acp_session_id: None,
         view: SessionView::Terminal,
+        auto_approve: false,
     }
 }
 

crates/maestro-daemon/tests/web_ui.rs

@@ -59,7 +59,7 @@ async fn root_serves_the_spa_shell() {
             .map(|v| v.starts_with("text/html")),
         Some(true)
     );
-    assert!(resp.text().await.unwrap().contains(r#"id="app""#));
+    assert!(resp.text().await.unwrap().contains(r#"id="root""#));
 }
 
 #[tokio::test]
@@ -69,7 +69,7 @@ async fn client_side_route_falls_back_to_the_shell() {
         .await
         .unwrap();
     assert_eq!(resp.status(), 200);
-    assert!(resp.text().await.unwrap().contains(r#"id="app""#));
+    assert!(resp.text().await.unwrap().contains(r#"id="root""#));
 }
 
 /// An unmatched API path must 404 rather than fall through to the SPA shell:

crates/maestro-e2e/tests/e2e.rs

@@ -777,7 +777,7 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
         other => panic!("expected a kill_guarded refusal, got {other:?}"),
     }
 
-    // Force overrides the refusal and nothing else: session gone, tree kept.
+    // Force overrides the refusal: session gone, tree removed.
     client.kill_session_forced(s.id).await.expect("forced kill");
 
     assert!(
@@ -789,12 +789,12 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
             .any(|x| x.id == s.id),
         "the forced kill ends the session"
     );
-    assert!(wt.is_dir(), "a guarded worktree must stay on disk");
+    assert!(!wt.is_dir(), "a forced kill removes the worktree");
     assert!(
-        git_worktree_list(base.path())
+        !git_worktree_list(base.path())
             .iter()
             .any(|l| l.contains("feature/local")),
-        "the kept tree stays registered in git"
+        "the removed tree is unregistered from git"
     );
 }
 

crates/maestro-protocol/src/display.rs

@@ -744,6 +744,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-protocol/src/lib.rs

@@ -132,6 +132,12 @@ pub struct Session {
     /// the two are minted by different processes with different lifetimes.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub acp_session_id: Option<String>,
+    /// When `true` the daemon auto-approves every ACP permission request for
+    /// this session instead of surfacing them to the client. Set at spawn time
+    /// from the preset or the `CreateSessionRequest`; persisted so it survives
+    /// a daemon restart.
+    #[serde(default)]
+    pub auto_approve: bool,
 }
 
 /// A session's process shape (#133): a plain terminal, or a structured agent
@@ -175,6 +181,10 @@ pub enum ActivityState {
     AwaitingInput,
     /// An agent reported a failure, or a structured session/turn failed.
     Error,
+    /// The ACP adapter is booting; the session is registered but cannot accept
+    /// prompts yet. Older clients that do not know this variant degrade it to
+    /// `Idle` via the lenient deserializer — acceptable.
+    Starting,
 }
 
 impl<'de> Deserialize<'de> for ActivityState {
@@ -187,6 +197,7 @@ impl<'de> Deserialize<'de> for ActivityState {
             "Active" => Self::Active,
             "AwaitingInput" => Self::AwaitingInput,
             "Error" => Self::Error,
+            "Starting" => Self::Starting,
             // Known or not, any other spelling degrades to the neutral default
             _ => Self::Idle,
         })
@@ -225,9 +236,10 @@ where
         "Idle" => Ok(ActivityState::Idle),
         "AwaitingInput" => Ok(ActivityState::AwaitingInput),
         "Error" => Ok(ActivityState::Error),
+        "Starting" => Ok(ActivityState::Starting),
         other => Err(D::Error::unknown_variant(
             other,
-            &["Active", "Idle", "AwaitingInput", "Error"],
+            &["Active", "Idle", "AwaitingInput", "Error", "Starting"],
         )),
     }
 }
@@ -1048,6 +1060,7 @@ mod tests {
             last_focused_at: None,
             view: SessionView::Terminal,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-testing/src/lib.rs

@@ -22,7 +22,8 @@ use chrono::Utc;
 use futures_util::{SinkExt, StreamExt};
 use maestro_protocol::{
     routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonClient, DaemonInfo, DirListing,
-    GitRoot, RecentDirs, SendInputRequest, Session, SessionStatus, PROTOCOL_VERSION,
+    GitRoot, RecentDirs, SendInputRequest, Session, SessionStatus, StructuredPromptRequest,
+    PROTOCOL_VERSION,
 };
 use tokio::net::TcpListener;
 use tokio::sync::{broadcast, oneshot};
@@ -49,6 +50,7 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
         blocked_work: None,
         last_focused_at: None,
         acp_session_id: None,
+        auto_approve: false,
     }
 }
 
@@ -60,6 +62,8 @@ struct Inner {
     forced_error: Option<(u16, ApiError)>,
     /// Everything `POST /api/sessions/:id/input` was asked to type, in order.
     inputs: Vec<(Uuid, SendInputRequest)>,
+    /// Every ACP prompt sent to a structured session, in order.
+    structured_prompts: Vec<(Uuid, StructuredPromptRequest)>,
 }
 
 #[derive(Clone)]
@@ -92,6 +96,7 @@ impl MockDaemon {
             .route(routes::SESSIONS, get(list_sessions).post(create_session))
             .route(routes::patterns::SESSION, delete(kill_session))
             .route(routes::patterns::SESSION_INPUT, post(send_input))
+            .route(routes::patterns::STRUCTURED_PROMPT, post(structured_prompt))
             .route(routes::INFO, get(daemon_info))
             .route(routes::DIRS, get(list_dir))
             .route(routes::RECENT_DIRS, get(recent_dirs))
@@ -178,6 +183,16 @@ impl MockDaemon {
         self.state.inner.lock().expect("poisoned").inputs.clone()
     }
 
+    /// Every ACP prompt this daemon received, oldest first.
+    pub fn structured_prompts(&self) -> Vec<(Uuid, StructuredPromptRequest)> {
+        self.state
+            .inner
+            .lock()
+            .expect("poisoned")
+            .structured_prompts
+            .clone()
+    }
+
     pub fn session_count(&self) -> usize {
         self.state.inner.lock().expect("poisoned").sessions.len()
     }
@@ -266,6 +281,26 @@ async fn send_input(
     StatusCode::NO_CONTENT.into_response()
 }
 
+async fn structured_prompt(
+    State(s): State<AppState>,
+    Path(id): Path<Uuid>,
+    Json(req): Json<StructuredPromptRequest>,
+) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let mut guard = s.inner.lock().expect("poisoned");
+    if !guard.sessions.iter().any(|x| x.id == id) {
+        return (
+            StatusCode::NOT_FOUND,
+            Json(ApiError::new("not_found", "no such session on this daemon")),
+        )
+            .into_response();
+    }
+    guard.structured_prompts.push((id, req));
+    StatusCode::NO_CONTENT.into_response()
+}
+
 async fn daemon_info(State(s): State<AppState>) -> Response {
     if let Some(r) = forced(&s) {
         return r;

crates/maestro-tui/src/app.rs

@@ -2216,6 +2216,7 @@ mod tests {
                     blocked_work: None,
                     last_focused_at: None,
                     acp_session_id: None,
+                    auto_approve: false,
                 })
                 .collect(),
         });
@@ -2399,6 +2400,7 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
             }],
         });
         app.dispatch(Action::SidebarNext);
@@ -2428,6 +2430,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 
@@ -3590,6 +3593,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: focused,
             acp_session_id: None,
+            auto_approve: false,
         };
         let older = Utc::now() - chrono::Duration::seconds(60);
         app.catalog.apply_event(CatalogEvent::Snapshot {
@@ -3870,6 +3874,7 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
             }],
         });
         app.dispatch(Action::KillHighlighted);
@@ -3907,6 +3912,7 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
             }],
         });
     }

crates/maestro-tui/src/catalog.rs

@@ -225,6 +225,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-tui/src/command_bar.rs

@@ -811,6 +811,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-tui/src/palette.rs

@@ -82,7 +82,7 @@ impl Surface {
     pub fn activity(&self, state: ActivityState) -> Color {
         match state {
             ActivityState::Active => self.active,
-            ActivityState::Idle => self.idle,
+            ActivityState::Idle | ActivityState::Starting => self.idle,
             ActivityState::AwaitingInput => self.awaiting,
             ActivityState::Error => self.error,
         }
@@ -928,9 +928,10 @@ pub fn contrast_ratio(a: Color, b: Color) -> Option<f64> {
 mod tests {
     use super::*;
 
-    const STATES: [ActivityState; 4] = [
+    const STATES: [ActivityState; 5] = [
         ActivityState::Active,
         ActivityState::Idle,
+        ActivityState::Starting,
         ActivityState::AwaitingInput,
         ActivityState::Error,
     ];

crates/maestro-tui/src/sidebar.rs

@@ -502,6 +502,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         }
     }
 
@@ -979,6 +980,7 @@ mod tests {
         for state in [
             ActivityState::Active,
             ActivityState::Idle,
+            ActivityState::Starting,
             ActivityState::AwaitingInput,
             ActivityState::Error,
         ] {
@@ -1009,6 +1011,7 @@ mod tests {
         for state in [
             ActivityState::Active,
             ActivityState::Idle,
+            ActivityState::Starting,
             ActivityState::AwaitingInput,
             ActivityState::Error,
         ] {
@@ -1270,6 +1273,7 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
         };
         let sb = Sidebar {
             sessions: vec![s],

docs/SIDEBAR.md

@@ -70,7 +70,7 @@ command. `<duration>` follows in the rail's colour when shown. There is no
 state word and no second badge: the rail exists so the state is still legible
 when a row is dimmed or the terminal renders the duration in the default fg.
 
-In the **web client** the rail is a 5px bar pinned to the row's own left
+In the **web client** the rail is a 7px bar pinned to the row's own left
 edge, square corners, spanning the full card height edge to edge — it
 shifts outward with nesting depth along with the row's own padding, since
 it is positioned relative to the row. It carries motion only for states that
@@ -160,6 +160,7 @@ The state word is never spelled out — the colour carries it.
 | ---------------- | --------- | ---------------- |
 | `Active`         | `--live`  | `active`         |
 | `Idle`           | `--muted` | `idle`           |
+| `Starting`       | `--muted` | `idle`           |
 | `AwaitingInput`  | `--warn`  | `awaiting`       |
 | `Error`          | `--danger`| `error`          |
 

docs/STRUCTURED-VIEW.md

@@ -189,14 +189,17 @@ choices, not daemon ones.
   presentation for `Notice`. `Plan` is the exception: both clients omit it
   from the transcript; the TUI may show the current plan in its status line,
   while the web client deliberately has no stats or plan rail.
-- The web client groups two or more tool rows after the same `User` row into
-  one collapsed turn activity block. `AgentText` and `AgentThought` rows that
-  appear *between* tool rows in the same turn are absorbed into the group
-  (intermediate narration); the last `AgentText` with no subsequent tool stays
-  outside as the prominent final answer. The header still reads
-  "N tool calls" (counting only tool rows). Opening the group reveals tools
-  and intermediate text in chronological order, with the text rendered in a
-  subdued style.
+- The web client groups each contiguous run of two or more tool rows into a
+  collapsed activity block. An `AgentText` or `AgentThought` row between
+  tools splits them into separate groups, so the timeline reads
+  text → group → text → group rather than lumping every tool in a turn into
+  one box. Text and thought rows stay outside groups as standalone transcript
+  items — the operator sees all reasoning without expanding. Resolved
+  approval rows between tools within a run are absorbed into the group. The
+  collapsed header reads "N tool calls · Label 'arg'" where the label and
+  argument come from the last tool row's `splitToolTitle` — the operator
+  sees which command is current at a glance. Opening the group reveals tool
+  rows in chronological order.
 - The web client's user, agent, thought, tool-detail, and notice text blocks
   copy their complete source text when clicked or keyboard-activated.
 - The web client consumes `available_commands_update` notices as the live

docs/WORKTREES.md

@@ -75,27 +75,17 @@ The point of refusing rather than cleaning up is that the session stays as the
 operator's handle on their own unfinished work. A session that is killed while
 its worktree still matters leaves a directory nobody is looking at.
 
-A consequence, accepted deliberately: a feature branch almost always has unpushed
-commits, so `--force` is the ordinary way to end a session, not an exception.
-That is only safe because force never removes what blocked.
-
 ### `--force`
 
-`--force` overrides the refusal and nothing else. It ends the session and
-**leaves the worktree on disk**, untouched. Force never removes a tree that
-would have blocked. A tree whose guard is clear never needed the override, so a
-forced kill removes it as usual — force changes what happens to blocked work,
-not ordinary cleanup.
+`--force` overrides the refusal and **removes the worktree**, even when it holds
+unsaved work. The operator sees the breakdown in the confirmation prompt and
+decides; once confirmed, the tree is gone.
 
 In the web client the kill button sends the unforced `DELETE` straight away —
 there is no pre-confirmation, because the daemon is the one that decides. Only
 the refusal raises a prompt, and that prompt names what is in the way and offers
 "Force kill", which repeats the request with `force=true`.
 
-Ending a session and destroying its work are two separate acts. Maestro only
-performs the first one. Removing a tree it left behind is the operator's own
-`git worktree remove`, chosen while looking at exactly what would be lost.
-
 ### Exiting on its own
 
 A session that ends by itself — the command finished, the operator typed `exit` —
@@ -113,17 +103,12 @@ once. A removed tree drops off the record, so dismissing the session afterwards
 does not refuse: there is no guard left to trip.
 
 A tree that was left alone stays attached to the dead record, where dismissing it
-later goes through `--force`, which leaves it on disk too. The same holds when
-the probe itself fails: nothing is destroyed.
+later goes through `--force`, which removes it. The same holds when the probe
+itself fails: nothing is destroyed.
 
-## Nothing is removed on the operator's behalf
+## Trees left behind by natural exit
 
-There is no store of worktrees the daemon is holding, no list endpoint, and no
-reclaim command. A tree left behind by a forced kill or a dirty exit is an
-ordinary git worktree on disk; `git worktree list` finds it and
-`git worktree remove` removes it.
-
-That is deliberate. A tracked list of trees pending deletion is a second place
-the truth can live, and it goes stale the moment somebody removes a directory by
-hand. Git already knows which worktrees exist, and removing one is not a
-decision Maestro is better placed to make.
+A forced kill always removes the worktree. A natural exit with unsaved work
+leaves the tree on disk — there is no operator confirmation in that path. Those
+trees are ordinary git worktrees; `git worktree list` finds them and
+`git worktree remove` removes them.

flake.nix

@@ -148,7 +148,7 @@
             pnpmDeps = (pkgs.fetchPnpmDeps.override { pnpm = pkgs.pnpm_10; }) {
               inherit (finalAttrs) pname version src;
               fetcherVersion = 3;
-              hash = "sha256-AzF/rrhqbvl613hNsC18YSylBSVxtatg7fEiUEF1u2o=";
+              hash = "sha256-FEWOAtSFvOWHeCNR0RK8JQ/ssW31qmShu1YD2GuqioQ=";
             };
 
             buildPhase = ''

web/index.html

@@ -23,7 +23,7 @@
     <meta name="apple-mobile-web-app-title" content="maestro" />
   </head>
   <body>
-    <div id="app"></div>
-    <script type="module" src="/src/main.ts"></script>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
   </body>
 </html>

web/package.json

@@ -17,12 +17,22 @@
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-webgl": "^0.19.0",
     "@xterm/xterm": "^5.5.0",
-    "marked": "^18.0.11"
+    "marked": "^18.0.11",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
   },
   "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@vitejs/plugin-react": "^4.7.0",
     "happy-dom": "^20.11.6",
+    "tailwindcss": "^4.3.3",
     "typescript": "^5.6.3",
     "vite": "^5.4.10",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "zustand": "^5.0.15"
   }
 }

web/src/App.tsx

@@ -0,0 +1,449 @@
+// The app shell (#253): everything main.ts used to wire by hand, as one React
+// tree. The stores are the state — a catalog store fed by the events socket, a
+// layout store holding the tab/split tree — and the hash route is a deep link
+// into the latter.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStore } from "zustand";
+
+import "@fontsource/jetbrains-mono/400.css";
+import "@fontsource/jetbrains-mono/500.css";
+import "@fontsource/jetbrains-mono/600.css";
+import "@fontsource/jetbrains-mono/700.css";
+
+import { createSession, fetchNames, getDaemonInfo, gitRoot, projects as fetchProjects } from "./api.js";
+import {
+  CommandSet,
+  DEFAULT_LEADER,
+  controlByte,
+  defineCommands,
+  isBarTypingTarget,
+} from "./commands.js";
+import { ThemeProvider } from "./contexts/ThemeContext.js";
+import { CommandBar, SPAWN_DIRECTORY_EVENT, useCommandBar } from "./components/commandBar/index.js";
+import { DaemonLink, createDaemonLinkStore } from "./components/daemon/DaemonLink.js";
+import { RestartOverlay } from "./components/daemon/RestartOverlay.js";
+import { HelpOverlay } from "./components/dialogs/index.js";
+import { useViewport } from "./components/hooks/useViewport.js";
+import { Drawer } from "./components/layout/Drawer.js";
+import { MultiView, type MultiViewHandle } from "./components/layout/MultiView.js";
+import { Sidebar } from "./components/sidebar/index.js";
+import {
+  SpawnModal,
+  spawnSimilarProjectSeed,
+  spawnSimilarSeed,
+  useFastForward,
+  type SpawnFormProps,
+} from "./components/spawn/index.js";
+import { buildFastForwardRequest, fastForwardSeed, resolveFastForward } from "./fastForward.js";
+import { useHashRouter } from "./hooks/useHashRouter.js";
+import { usePreview } from "./hooks/usePreview.js";
+import { activeTab, findLeaf, openSessions } from "./layout.js";
+import { createCatalogStore, type CatalogStore } from "./stores/catalogStore.js";
+import { createLayoutStore, type LayoutStore } from "./stores/layoutStore.js";
+import type { Project, Session, SpawnPreset, Uuid } from "./types.js";
+import {
+  FOCUS_PANE_EVENT,
+  OPEN_SPAWN_EVENT,
+  SESSION_SELECT_EVENT,
+  SPAWN_SIMILAR_EVENT,
+  requestOpenSpawn,
+  requestToggleDrawer,
+} from "./uiEvents.js";
+
+type SpawnSeed = SpawnFormProps["seed"];
+
+/** Open modal state: `seed` is what the form starts from (undefined for a
+ *  plain spawn), `newTab` where the created session lands. */
+interface SpawnState {
+  seed: SpawnSeed;
+  newTab: boolean;
+}
+
+export function App() {
+  return (
+    <ThemeProvider>
+      <Shell />
+    </ThemeProvider>
+  );
+}
+
+function Shell() {
+  useViewport();
+
+  // One instance each, for the life of the page.
+  const catalogStore = useMemo(() => createCatalogStore(), []);
+  const layoutStore = useMemo(() => createLayoutStore(), []);
+  const linkStore = useMemo(() => createDaemonLinkStore(), []);
+
+  const sessions = useStore(catalogStore, (s: CatalogStore) => s.sessions);
+  const connected = useStore(catalogStore, (s: CatalogStore) => s.connected);
+  const loaded = useStore(catalogStore, (s: CatalogStore) => s.loaded);
+  const layout = useStore(layoutStore, (s: LayoutStore) => s.layout);
+
+  const [homeDir, setHomeDir] = useState<string | undefined>(undefined);
+  const [leader, setLeader] = useState(DEFAULT_LEADER);
+  const [spawn, setSpawn] = useState<SpawnState | null>(null);
+
+  const { route, navigate } = useHashRouter();
+  const { preview, previewedSessionId, commit: commitPreview, end: endPreview } = usePreview({
+    store: layoutStore,
+  });
+
+  useEffect(() => {
+    catalogStore.getState().start();
+    return () => catalogStore.getState().stop();
+  }, [catalogStore]);
+
+  // The daemon's home dir abbreviates cwds to `~/…`; its leader rebinds the
+  // chords hanging off it (#159), so the `?` overlay and the command bar show
+  // the configured chord rather than the default. Absolute paths and the
+  // default leader are fine fallbacks.
+  useEffect(() => {
+    void getDaemonInfo()
+      .then((info) => {
+        setHomeDir(info.home_dir);
+        if (info.leader) setLeader(info.leader);
+      })
+      .catch(() => {});
+  }, []);
+
+  // Installed mobile browsers suspend timers and WebSockets in the background.
+  // Replacing the socket on return avoids leaving the restart overlay up after
+  // a transient lost connection has already recovered.
+  useEffect(() => {
+    const recover = () => {
+      if (document.visibilityState !== "visible") return;
+      void linkStore.getState().probe();
+      catalogStore.getState().reconnect();
+    };
+    document.addEventListener("visibilitychange", recover);
+    window.addEventListener("pageshow", recover);
+    window.addEventListener("online", recover);
+    return () => {
+      document.removeEventListener("visibilitychange", recover);
+      window.removeEventListener("pageshow", recover);
+      window.removeEventListener("online", recover);
+    };
+  }, [catalogStore, linkStore]);
+
+  // The catalog is the authority on which sessions exist: a pane for a session
+  // that is no longer listed gets closed here, rather than waiting on its own
+  // socket to notice. Only once a list has actually landed — before that,
+  // "not listed" means "not known yet" and would close every restored pane.
+  useEffect(() => {
+    if (!loaded) return;
+    for (const id of openSessions(layout)) {
+      if (!sessions.has(id)) layoutStore.getState().closeSession(id);
+    }
+  }, [loaded, sessions, layout, layoutStore]);
+
+  const tab = activeTab(layout);
+  const focusedSessionId =
+    (tab.focusedLeafId && findLeaf(tab.root, tab.focusedLeafId)?.sessionId) || null;
+  const focusedSession = focusedSessionId ? sessions.get(focusedSessionId) : undefined;
+
+  /** Open/focus a session, settling any preview of it in place. Shared by the
+   *  hash router and the sidebar's click-driven path (#133), which can't rely
+   *  on `hashchange` alone — a split or drag can move focus without the hash
+   *  changing, leaving a click back onto that row silently ignored. */
+  const focusSession = useCallback(
+    (sessionId: Uuid) => {
+      // `commit` cancels a pending preview and opens the session; the layout
+      // store settles a matching preview in place rather than moving it twice.
+      commitPreview(sessionId);
+      navigate({ kind: "attach", sessionId });
+    },
+    [commitPreview, navigate],
+  );
+
+  // A deep link (`#/attach/:id`) opens the session it names. Only the route
+  // *changing* does this: focusing a pane rewrites the hash, and re-opening
+  // from that would fight the layout the operator just arranged.
+  const lastRouteRef = useRef<string | null>(null);
+  useEffect(() => {
+    const key = route.kind === "attach" ? route.sessionId : "catalog";
+    if (lastRouteRef.current === key) return;
+    lastRouteRef.current = key;
+    if (route.kind === "attach") layoutStore.getState().openSession(route.sessionId);
+  }, [route, layoutStore]);
+
+  /** Show a freshly spawned session: it gets its own pane rather than evicting
+   *  whatever the operator was reading. */
+  const mountSpawned = useCallback(
+    (session: Session, opts?: { newTab?: boolean }) => {
+      layoutStore.getState().openSessionBeside(session.id, opts);
+      navigate({ kind: "attach", sessionId: session.id });
+    },
+    [layoutStore, navigate],
+  );
+
+  const openSpawn = useCallback(
+    (seed: SpawnSeed, newTab: boolean) => {
+      endPreview();
+      setSpawn({ seed, newTab });
+    },
+    [endPreview],
+  );
+
+  /** The plain spawn: the session you were last on preselects its project, so
+   *  `n` then Enter spawns another session there without touching the picker.
+   *  It lands in a new tab, not a split of the pane you were reading (#100). */
+  const openPlainSpawn = useCallback(() => {
+    openSpawn(focusedSession ? spawnSimilarProjectSeed(focusedSession) : undefined, true);
+  }, [focusedSession, openSpawn]);
+
+  /** The focused session's project — its base repo for a worktree session, its
+   *  cwd otherwise (the rule spawnSimilarProjectSeed uses). */
+  const focusedProjectCwd = focusedSession
+    ? (focusedSession.worktree?.base_repo ?? focusedSession.cwd)
+    : undefined;
+
+  const fastForward = useFastForward({
+    focusedCwd: focusedProjectCwd,
+    onSpawned: (session) => mountSpawned(session),
+    onFallback: (seed) => openSpawn(seed, false),
+  });
+
+  const bar = useCommandBar({ onOpen: endPreview });
+
+  useEffect(() => {
+    const onOpenSpawnEvent = () => openPlainSpawn();
+    const onSpawnSimilar = (e: Event) => {
+      const s = (e as CustomEvent<Session>).detail;
+      if (s) openSpawn(spawnSimilarSeed(s), false);
+    };
+    const onSessionSelect = (e: Event) => focusSession((e as CustomEvent<Uuid>).detail);
+    document.addEventListener(OPEN_SPAWN_EVENT, onOpenSpawnEvent);
+    document.addEventListener(SPAWN_SIMILAR_EVENT, onSpawnSimilar);
+    document.addEventListener(SESSION_SELECT_EVENT, onSessionSelect);
+    return () => {
+      document.removeEventListener(OPEN_SPAWN_EVENT, onOpenSpawnEvent);
+      document.removeEventListener(SPAWN_SIMILAR_EVENT, onSpawnSimilar);
+      document.removeEventListener(SESSION_SELECT_EVENT, onSessionSelect);
+    };
+  }, [openPlainSpawn, openSpawn, focusSession]);
+
+  // Enter on a `~` row in the command bar (docs/COMMAND-BAR.md): the same
+  // fast-forward spawn, aimed at the chosen directory instead of the most
+  // recent project.
+  useEffect(() => {
+    const onSpawnDirectory = (e: Event) => {
+      void spawnInDirectory((e as CustomEvent<string>).detail, mountSpawned, (seed) =>
+        openSpawn(seed, false),
+      );
+    };
+    document.addEventListener(SPAWN_DIRECTORY_EVENT, onSpawnDirectory);
+    return () => document.removeEventListener(SPAWN_DIRECTORY_EVENT, onSpawnDirectory);
+  }, [mountSpawned, openSpawn]);
+
+  // Tab in the session list hands the keyboard to the pane; leader-h hands it
+  // back the other way. Handing it to a previewed pane is choosing it: the
+  // preview settles rather than snapping back when the list blurs.
+  const sidebarRef = useRef<HTMLDivElement>(null);
+  const viewRef = useRef<MultiViewHandle>(null);
+  const focusPane = useCallback(() => {
+    if (previewedSessionId) commitPreview(previewedSessionId);
+    viewRef.current?.focusPane();
+  }, [previewedSessionId, commitPreview]);
+
+  useEffect(() => {
+    document.addEventListener(FOCUS_PANE_EVENT, focusPane);
+    return () => document.removeEventListener(FOCUS_PANE_EVENT, focusPane);
+  }, [focusPane]);
+
+  // The global half of the command registry (#148). `n` opens the spawn modal
+  // and `N` fast-forwards a spawn (#67); both are plain keys, so the set's own
+  // `isTypingTarget` keeps them out of form fields and the terminal's hidden
+  // textarea. Leader-h moves the keyboard between the list and the pane — a
+  // chord, because an attached terminal owns every plain keystroke
+  // (docs/COMMAND-BAR.md).
+  useEffect(() => {
+    if (bar.open || spawn) return;
+    const spawnKeys = new CommandSet(
+      defineCommands({
+        "spawn.open": openPlainSpawn,
+        "spawn.fastForward": () => void fastForward(),
+      }),
+    );
+    const focusKeys = new CommandSet(
+      defineCommands(
+        {
+          "focus.toggle": () => {
+            if (sidebarRef.current?.contains(document.activeElement)) {
+              focusPane();
+            } else {
+              // No-op on desktop; on mobile the list is off-canvas until the
+              // drawer opens, so the focus has somewhere to land.
+              requestToggleDrawer();
+              sidebarRef.current?.querySelector<HTMLElement>("[tabindex]")?.focus();
+            }
+          },
+          // The escape hatch: binding ctrl-k takes readline's
+          // kill-to-end-of-line away from every pane, and leader ctrl-k gives
+          // it back as the literal 0x0B byte (docs/COMMAND-BAR.md).
+          "pane.literalCtrlK": () => viewRef.current?.sendInput("\x0b"),
+          // The leader pressed twice, tmux-style: one literal leader byte,
+          // built from the leader itself so a rebound one sends its own (#158).
+          "pane.literalLeader": () => viewRef.current?.sendInput(controlByte(leader)),
+        },
+        leader,
+      ),
+      { leader },
+    );
+    const onKeydown = (e: KeyboardEvent) => {
+      if (focusKeys.handle(e)) return;
+      if (isBarTypingTarget(e.target)) return;
+      spawnKeys.handle(e);
+    };
+    window.addEventListener("keydown", onKeydown, true);
+    return () => window.removeEventListener("keydown", onKeydown, true);
+  }, [bar.open, spawn, openPlainSpawn, fastForward, focusPane, leader]);
+
+  const openIds = useMemo(() => openSessions(layout), [layout]);
+  const barSessions = useMemo(() => [...sessions.values()], [sessions]);
+
+  return (
+    <>
+      <Drawer
+        sidebar={
+          <div ref={sidebarRef} className="contents">
+          <Sidebar
+            store={catalogStore}
+            homeDir={homeDir}
+            activeId={focusedSessionId}
+            openIds={openIds}
+            previewId={previewedSessionId}
+            linkStore={linkStore}
+            onSelect={(id) => focusSession(id)}
+            onPreview={preview}
+            onSpawn={openPlainSpawn}
+            onSpawnDefaults={() => void fastForward()}
+            onSpawnSimilar={(s) => openSpawn(spawnSimilarSeed(s), false)}
+            onFocusPane={focusPane}
+          />
+          </div>
+        }
+      >
+        <MultiView
+          ref={viewRef}
+          store={layoutStore}
+          // Undefined until the first list lands: MultiView's boot
+          // reconciliation prunes against it, and an empty map would take
+          // every restored pane with it.
+          sessions={loaded ? sessions : undefined}
+          onDisconnect={(id) => layoutStore.getState().closeSession(id)}
+          emptyState={<Welcome onSpawn={requestOpenSpawn} />}
+        />
+      </Drawer>
+
+      <DaemonLink store={linkStore} connected={connected} />
+      <RestartOverlay store={linkStore} />
+      <HelpOverlay />
+
+      {bar.open && (
+        <CommandBar
+          sessions={barSessions}
+          homeDir={homeDir}
+          onOpenSession={(id) => {
+            bar.closeBar();
+            focusSession(id);
+          }}
+          onClose={bar.closeBar}
+        />
+      )}
+
+      {spawn && (
+        <SpawnModal
+          seed={spawn.seed}
+          onSuccess={(session) => mountSpawned(session, { newTab: spawn.newTab })}
+          onClose={() => setSpawn(null)}
+        />
+      )}
+    </>
+  );
+}
+
+async function spawnPresets(): Promise<SpawnPreset[]> {
+  try {
+    const info = await getDaemonInfo();
+    if (info.presets?.length) return info.presets;
+  } catch {
+    // keep fallbacks
+  }
+  const { FALLBACK_PRESETS } = await import("./components/spawn/model.js");
+  return FALLBACK_PRESETS;
+}
+
+/** A directory the project scan never saw stands in as its own project; one
+ *  outside any repo spawns without a worktree, since there is no repo to cut a
+ *  branch from. Anything still unresolved opens the pre-filled form. */
+async function spawnInDirectory(
+  path: string,
+  onSpawned: (session: Session) => void,
+  onFallback: (seed: SpawnSeed) => void,
+): Promise<void> {
+  const [discovered, handle] = await Promise.all([
+    fetchProjects().catch(() => [] as Project[]),
+    fetchNames(1)
+      .then((batch) => batch.names[0])
+      .catch(() => undefined),
+  ]);
+  const presets = await spawnPresets();
+  const known = discovered.find((p) => p.path === path);
+  const project: Project = known ?? { path, name: path.split("/").filter(Boolean).pop() ?? path };
+  const resolved = resolveFastForward([project], presets, handle, path);
+  const req = buildFastForwardRequest(resolved);
+  if (req) {
+    const inRepo =
+      known !== undefined ||
+      (await gitRoot(path)
+        .then((r) => !!r.root)
+        .catch(() => false));
+    if (!inRepo) delete req.worktree;
+    try {
+      onSpawned(await createSession(req));
+      return;
+    } catch {
+      // A failed POST degrades to the pre-filled form, never a dead row.
+    }
+  }
+  onFallback(fastForwardSeed(resolved));
+}
+
+/** The content pane with nothing open. The ☰ is mobile-only: with no pane
+ *  there is no pane header to carry it, so the drawer would be swipe-only. */
+function Welcome({ onSpawn }: { onSpawn(): void }) {
+  return (
+    <div className="empty content-welcome">
+      <div className="empty-glyph" aria-hidden="true">
+        ⌘
+      </div>
+      <div className="empty-title">No session open</div>
+      <p className="empty-hint">
+        Pick a session from the list, or start a new one. Open sessions keep streaming in the
+        background — switching back is instant.
+      </p>
+      <p className="empty-hint">
+        Press <kbd>?</kbd> for keyboard shortcuts.
+      </p>
+      <div className="empty-actions">
+        <button
+          type="button"
+          className="btn btn-ghost welcome-sessions"
+          onClick={() => requestToggleDrawer()}
+        >
+          ☰ Sessions
+        </button>
+        <button
+          type="button"
+          className="btn btn-primary"
+          title="Draft pane: n — fast-forward spawn: N"
+          onClick={onSpawn}
+        >
+          + Spawn session
+        </button>
+      </div>
+    </div>
+  );
+}

web/src/attach.ts

@@ -1,659 +0,0 @@
-import { FitAddon } from "@xterm/addon-fit";
-import { WebglAddon } from "@xterm/addon-webgl";
-import { Terminal } from "@xterm/xterm";
-import "@xterm/xterm/css/xterm.css";
-
-import { attachWsUrl } from "./routes.js";
-import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "./reconnect.js";
-import { applyModsToChar, cursorSeq, tildeSeq } from "./keys.js";
-import { requestToggleDrawer } from "./drawer.js";
-import { paneTitleAttr, paneTitleHtml, type AttachInfo } from "./paneTitle.js";
-import type { PaneConnection } from "./pane.js";
-import type { ClientControl, Uuid } from "./types.js";
-import { WebglPolicy } from "./webglRenderer.js";
-
-export type { AttachInfo } from "./paneTitle.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.
- *
- * The connection is **decoupled from the UI**: it owns a long-lived WS that
- * keeps streaming PTY output into the terminal buffer whether or not the view
- * is currently mounted. The shell moves `el` between the visible content pane
- * and a hidden cache; `onMount`/`onUnmount` only adjust focus + sizing, never
- * the connection. Only `dispose()` (eviction, an explicit disconnect, or the
- * session ending) tears the socket down — so switching away and back is
- * instant, with scrollback already in place.
- */
-export interface AttachConnection extends PaneConnection {}
-
-export interface AttachOptions {
-  /** Invoked when the user clicks the view's explicit "disconnect" control. */
-  onRequestClose?: (sessionId: Uuid) => void;
-  /** Invoked when the socket closes on its own — the session ended or the link
-   *  dropped — but NOT on an intentional `dispose()` (eviction / user close). The
-   *  shell uses this to auto-close the pane rather than leave a dead one. */
-  onClosed?: (sessionId: Uuid) => void;
-  /** Asked on every close: should the socket be retried? The shell answers
-   *  from the catalog — see `shouldRetryClose`. */
-  shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
-}
-
-export function createAttachConnection(
-  sessionId: Uuid,
-  opts: AttachOptions = {},
-  info?: AttachInfo,
-): AttachConnection {
-  const el = document.createElement("div");
-  el.className = "attach";
-  // Useful identity over a bare UUID: name · command. The full id stays in the
-  // tooltip for when you really need it.
-  const titleHtml = paneTitleHtml(sessionId, info);
-  const titleAttr = paneTitleAttr(sessionId, info);
-  el.innerHTML = `
-    <header class="attach-header">
-      <button type="button" class="btn btn-ghost btn-icon sessions-btn" aria-label="Show sessions" title="Show sessions">☰</button>
-      <span class="attach-title" title="${titleAttr}">${titleHtml}</span>
-      <span class="attach-state" data-state="connecting">connecting…</span>
-      <button class="btn btn-ghost btn-icon disconnect" type="button" aria-label="Disconnect" title="Disconnect this session">⏻</button>
-    </header>
-    <div class="attach-body"></div>
-  `;
-
-  const titleEl = el.querySelector(".attach-title") as HTMLSpanElement;
-  const body = el.querySelector(".attach-body") as HTMLDivElement;
-  const stateEl = el.querySelector(".attach-state") as HTMLSpanElement;
-  const disconnectBtn = el.querySelector(".disconnect") as HTMLButtonElement;
-
-  const keybar = buildKeyBar((data) => sendInput(data));
-  el.appendChild(keybar.el);
-
-  const setState = (s: string, kind: "connecting" | "open" | "closed" | "error") => {
-    stateEl.textContent = s;
-    stateEl.dataset.state = kind;
-  };
-
-  // Mobile-only (CSS hides it on desktop, where the sidebar is always in view):
-  // the session list is an off-canvas drawer and this is what opens it.
-  (el.querySelector(".sessions-btn") as HTMLElement).addEventListener("click", () =>
-    requestToggleDrawer(),
-  );
-
-  disconnectBtn.addEventListener("click", () => {
-    opts.onRequestClose?.(sessionId);
-  });
-
-  const term = new Terminal({
-    cursorBlink: true,
-    fontFamily:
-      '"JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    fontSize: 13,
-    convertEol: false,
-    theme: {
-      // The terminal stays dark in both app themes (convention); colors are
-      // tuned to the maestro palette — signal-green cursor, slate background.
-      background: "#121419",
-      foreground: "#e6e8ec",
-      cursor: "#5fe3a1",
-      cursorAccent: "#121419",
-      selectionBackground: "#2b6b4f",
-    },
-    scrollback: 5000,
-    allowProposedApi: true,
-  });
-  const fit = new FitAddon();
-  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;
-    }
-  }
-
-  // Touch scrolling: xterm's built-in touch handling is jittery (drags crawl a
-  // line at a time and stall), so map finger drags ourselves. Two routes:
-  //   • normal buffer  → term.scrollLines walks the scrollback.
-  //   • mouse-tracking apps (tmux, Claude Code on the alt screen) → synthesize
-  //     wheel events so xterm encodes them as mouse-wheel reports the app reads,
-  //     scrolling *its* content (the only scroll that exists on the alt screen).
-  //   • alt screen with no mouse tracking → nothing to do; the app owns input.
-  // `touch-action: none` (CSS) keeps the browser from cancelling the custom
-  // gesture stream; only the terminal surface opts out of native page panning.
-  // Listeners MUST sit on `.xterm`, not `.xterm-viewport`: `.xterm-screen` is a
-  // later sibling of the viewport, so it paints over it and takes every touch.
-  {
-    const root = term.element as HTMLElement | undefined;
-    const screen = el.querySelector(".xterm-screen") as HTMLElement | null;
-    const cellH = () => {
-      const core = (term as unknown as {
-        _core?: { _renderService?: { dimensions?: { css?: { cell?: { height: number } } } } };
-      })._core;
-      return core?._renderService?.dimensions?.css?.cell?.height || 16;
-    };
-    if (root) {
-      let lastY = 0;
-      let lastX = 0;
-      let remainder = 0;
-      root.addEventListener(
-        "touchstart",
-        (e) => {
-          if (e.touches.length !== 1) return;
-          lastY = e.touches[0].clientY;
-          lastX = e.touches[0].clientX;
-          remainder = 0;
-        },
-        { passive: true },
-      );
-      root.addEventListener(
-        "touchmove",
-        (e) => {
-          if (e.touches.length !== 1) return;
-          const ch = cellH();
-          const y = e.touches[0].clientY;
-          const px = lastY - y + remainder; // finger up → scroll toward newer
-          lastY = y;
-          const lines = Math.trunc(px / ch);
-          remainder = px - lines * ch;
-          if (lines === 0) return;
-          // term.modes.mouseTrackingMode is "none" unless the app turned mouse
-          // reporting on — that's the signal to forward instead of scrollback.
-          const mouseTracked = term.modes.mouseTrackingMode !== "none";
-          if (mouseTracked && screen) {
-            // One wheel event per crossed cell, dispatched at the touch point so
-            // xterm computes valid cell coords for the mouse report.
-            const dir = lines > 0 ? 1 : -1;
-            for (let i = 0; i < Math.abs(lines); i++) {
-              screen.dispatchEvent(
-                new WheelEvent("wheel", {
-                  deltaY: dir * ch,
-                  deltaMode: 0,
-                  clientX: lastX,
-                  clientY: y,
-                  bubbles: true,
-                  cancelable: true,
-                }),
-              );
-            }
-            e.preventDefault();
-          } else if (term.buffer.active.type !== "alternate") {
-            term.scrollLines(lines);
-            e.preventDefault();
-          }
-        },
-        { passive: false },
-      );
-    }
-  }
-
-  // Mobile: the special-key bar is only useful while the soft keyboard is up,
-  // so reveal it only when the terminal's hidden textarea is focused (CSS still
-  // gates it to coarse pointers). Tapping a keycap keeps focus via pointerdown
-  // preventDefault, so the bar stays put during use. Re-fit on the toggle since
-  // showing/hiding the bar changes the terminal's available height.
-  const ta = term.textarea;
-  if (ta) {
-    ta.addEventListener("focus", () => {
-      keybar.el.classList.add("keybar-active");
-      requestAnimationFrame(tryFit);
-    });
-    ta.addEventListener("blur", () => {
-      keybar.el.classList.remove("keybar-active");
-      requestAnimationFrame(tryFit);
-    });
-  }
-
-  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
-  // stops ~1–2 columns short of the edge. Same math, minus that subtraction.
-  const tryFit = () => {
-    if (!mounted) return; // parked views have no meaningful size to fit to
-    try {
-      const el2 = term.element;
-      const parent = el2?.parentElement;
-      const core = (term as unknown as {
-        _core?: { _renderService?: { dimensions?: { css?: { cell?: { width: number; height: number } } } } };
-      })._core;
-      const cell = core?._renderService?.dimensions?.css?.cell;
-      if (!el2 || !parent || !cell || !cell.width || !cell.height) {
-        fit.fit(); // fall back if internals aren't ready yet
-        return;
-      }
-      // Measure the viewport's real inner width (clientWidth excludes any
-      // scrollbar), not the container's — so columns always fit inside the
-      // viewport whether or not xterm reserves a scrollbar. Falls back to the
-      // padded container box before the viewport exists.
-      const vp = el2.querySelector(".xterm-viewport") as HTMLElement | null;
-      let availW: number;
-      let availH: number;
-      if (vp && vp.clientWidth > 0) {
-        availW = vp.clientWidth;
-        availH = vp.clientHeight;
-      } else {
-        const ps = getComputedStyle(parent);
-        const ts = getComputedStyle(el2);
-        availW =
-          parseInt(ps.width) -
-          (parseInt(ts.paddingLeft) + parseInt(ts.paddingRight) || 0);
-        availH =
-          parseInt(ps.height) -
-          (parseInt(ts.paddingTop) + parseInt(ts.paddingBottom) || 0);
-      }
-      const cols = Math.max(2, Math.floor(availW / cell.width));
-      const rows = Math.max(1, Math.floor(availH / cell.height));
-      if (cols !== term.cols || rows !== term.rows) term.resize(cols, rows);
-    } catch {
-      try {
-        fit.fit();
-      } catch {
-        // ignore — fit fails if the container is detached or zero-sized
-      }
-    }
-  };
-
-  let ws: WebSocket;
-  let reconnectMs = INITIAL_RECONNECT_MS;
-  let reconnectTimer: number | null = null;
-  // Snapshot replay starts at row zero, which can leave Codex at its oldest line.
-  // Follow it once per socket; later scrolling remains under the operator's control.
-  let awaitingReplay = true;
-
-  const sendControl = (msg: ClientControl) => {
-    if (ws.readyState !== WebSocket.OPEN) return;
-    ws.send(JSON.stringify(msg));
-  };
-
-  /** PTY input: raw bytes out as a binary frame. Shared by keystrokes and the
-   *  mobile key bar so both flow through the same path. */
-  const sendInput = (data: string) => {
-    if (ws.readyState !== WebSocket.OPEN) return;
-    ws.send(new TextEncoder().encode(data));
-  };
-
-  const onResize = () => {
-    tryFit();
-    sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
-  };
-
-  function connect(): void {
-    awaitingReplay = true;
-    ws = new WebSocket(attachWsUrl(sessionId));
-    ws.binaryType = "arraybuffer";
-
-    ws.onopen = () => {
-      reconnectMs = INITIAL_RECONNECT_MS;
-      setState("connected", "open");
-      sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
-      if (mounted && focusOnMount) term.focus();
-    };
-
-    ws.onmessage = (ev) => {
-      if (typeof ev.data === "string") {
-        try {
-          JSON.parse(ev.data) as ClientControl;
-        } catch {
-          // ignore unknown control frames
-        }
-        return;
-      }
-      if (ev.data instanceof ArrayBuffer) {
-        const replay = awaitingReplay;
-        awaitingReplay = false;
-        term.write(new Uint8Array(ev.data), () => {
-          if (replay) term.scrollToBottom();
-        });
-      } else if (ev.data instanceof Blob) {
-        // Some browsers may default to Blob despite binaryType="arraybuffer".
-        void ev.data.arrayBuffer().then((b) => {
-          const replay = awaitingReplay;
-          awaitingReplay = false;
-          term.write(new Uint8Array(b), () => {
-            if (replay) term.scrollToBottom();
-          });
-        });
-      }
-    };
-
-    ws.onerror = () => {
-      setState("error", "error");
-    };
-
-    ws.onclose = (ev) => {
-      // The web proxy relays a daemon rejection (unknown session) as an
-      // application close code (4000+) carrying a human reason. Show it in the
-      // pane — both the header and the terminal body — and KEEP the pane up so
-      // the user can read why, instead of letting it flash and vanish (#39).
-      const reason = ev.reason?.trim();
-      if (ev.code >= 4000 && reason && !disposed) {
-        setState(reason, "error");
-        term.write(`\r\n\x1b[31m⚠ cannot attach: ${reason}\x1b[0m\r\n`);
-        return;
-      }
-      // An intentional dispose has already set `disposed`; eviction and user
-      // close handle their own pane teardown.
-      if (disposed) return;
-
-      if (opts.shouldReconnect?.(sessionId, ev.code)) {
-        const delay = Math.min(reconnectMs, MAX_RECONNECT_MS);
-        setState("reconnecting…", "connecting");
-        reconnectTimer = window.setTimeout(() => {
-          reconnectTimer = null;
-          reconnectMs = Math.min(reconnectMs * 2, MAX_RECONNECT_MS);
-          connect();
-        }, delay);
-        return;
-      }
-
-      setState(`closed (${ev.code})`, "closed");
-      opts.onClosed?.(sessionId);
-    };
-  }
-
-  connect();
-
-  // PTY input: every keystroke goes out as a binary frame. A pending key-bar
-  // Ctrl modifier (mobile) folds into the next typed character here.
-  const dataDisp = term.onData((data) => {
-    sendInput(keybar.consume(data));
-  });
-  const resizeDisp = term.onResize(({ cols, rows }) => {
-    sendControl({ type: "Resize", cols, rows });
-  });
-  // xterm has no built-in copy-on-select; mirror the selection to the
-  // clipboard ourselves (best-effort — insecure contexts lack the API).
-  const selectionDisp = term.onSelectionChange(() => {
-    const text = term.getSelection();
-    if (text) void navigator.clipboard?.writeText(text).catch(() => {});
-  });
-
-  window.addEventListener("resize", onResize);
-  const visual = window.visualViewport ?? null;
-  visual?.addEventListener("resize", onResize);
-
-  // FitAddon only recomputes on the events we call it from — a window resize
-  // misses container-driven changes (sidebar drag, mobile layout settling,
-  // orientation, late font load). Observe the body directly so columns always
-  // match the real rendered width and the terminal fills edge to edge.
-  const ro = new ResizeObserver(() => tryFit());
-  ro.observe(body);
-  // Re-fit once the monospace font is actually loaded — cell width changes when
-  // the fallback is swapped out, which otherwise leaves stale columns.
-  document.fonts?.ready?.then(() => tryFit()).catch(() => {});
-
-  let disposed = false;
-
-  return {
-    sessionId,
-    el,
-    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 (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();
-    },
-    // The closure above: the same bytes-out path keystrokes and the mobile key
-    // bar already take.
-    sendInput,
-    updateInfo(next: AttachInfo) {
-      titleEl.innerHTML = paneTitleHtml(sessionId, next);
-      titleEl.title = paneTitleAttr(sessionId, next);
-    },
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      if (reconnectTimer !== null) {
-        window.clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
-      ro.disconnect();
-      window.removeEventListener("resize", onResize);
-      visual?.removeEventListener("resize", onResize);
-      dataDisp.dispose();
-      resizeDisp.dispose();
-      selectionDisp.dispose();
-      releaseWebgl();
-      try {
-        ws.close();
-      } catch {
-        // ignore
-      }
-      term.dispose();
-      el.remove();
-    },
-  };
-}
-
-/**
- * One key in the mobile key bar.
- * - `mod` is a sticky one-shot modifier toggle (Ctrl / Alt).
- * - `cursor` is a cursor/navigation key, identified by its CSI final byte, so a
- *   pending modifier can promote it to the `\x1b[1;<n><final>` form.
- * - `tilde` is a `~`-terminated navigation key (PgUp/PgDn), identified by its
- *   CSI parameter, whose modified form is `\x1b[<code>;<n>~`.
- * - `char` is a literal character (the symbols the soft keyboard buries behind
- *   a page switch), folded through a pending modifier like typed input.
- * - `seq` is a plain key (Esc, Tab) sent verbatim.
- */
-type KeyDef =
-  | { label: string; mod: Modifier }
-  | { label: string; cursor: CursorFinal }
-  | { label: string; tilde: number }
-  | { label: string; char: string }
-  | { label: string; seq: string };
-
-type Modifier = "ctrl" | "alt";
-/** CSI final bytes: arrows A–D, Home `H`, End `F`. */
-type CursorFinal = "A" | "B" | "C" | "D" | "H" | "F";
-
-/**
- * The keys the mobile soft keyboard hides, ordered to flow row-major into an
- * 8-column / 2-row grid (#7):
- *
- *     Esc  Tab  Home  ↑   End  PgUp  -  /
- *     Ctrl Alt   ←    ↓    →   PgDn  |  ~
- *
- * — Esc/Tab + the Ctrl/Alt sticky modifiers on the left, the cursor keys as a
- * real-keyboard inverted-T in the middle with Home/End filling its top corners,
- * then the paging pair and the shell symbols that cost a soft-keyboard page
- * switch to reach. Narrower screens scroll the bar sideways rather than
- * shrinking the caps below a thumb's width.
- */
-const KEY_DEFS: KeyDef[] = [
-  { label: "Esc", seq: "\x1b" },
-  { label: "Tab", seq: "\t" },
-  { label: "Home", cursor: "H" },
-  { label: "↑", cursor: "A" },
-  { label: "End", cursor: "F" },
-  { label: "PgUp", tilde: 5 },
-  { label: "-", char: "-" },
-  { label: "/", char: "/" },
-  { label: "Ctrl", mod: "ctrl" },
-  { label: "Alt", mod: "alt" },
-  { label: "←", cursor: "D" },
-  { label: "↓", cursor: "B" },
-  { label: "→", cursor: "C" },
-  { label: "PgDn", tilde: 6 },
-  { label: "|", char: "|" },
-  { label: "~", char: "~" },
-];
-
-/**
- * Fold a single character into its control code: letters and `@[\]^_` map to
- * 0x00–0x1f, space → NUL, `?` → DEL. Anything else is returned unchanged.
- */
-interface KeyBar {
-  readonly el: HTMLElement;
-  /** Fold pending modifiers into typed input (soft keyboard), consuming them. */
-  consume(data: string): string;
-}
-
-/**
- * Build the Termux-style special-key bar. Hidden by default; CSS reveals it on
- * coarse-pointer (touch) devices. `send` delivers bytes to the PTY.
- *
- * Ctrl and Alt are one-shot sticky modifiers: arm them and the very next key —
- * tapped here or typed on the soft keyboard — carries the modifier, then they
- * disarm. Taps `preventDefault` on pointerdown so the terminal keeps focus and
- * the keyboard stays open.
- */
-function buildKeyBar(send: (data: string) => void): KeyBar {
-  const el = document.createElement("div");
-  el.className = "attach-keybar";
-  el.setAttribute("role", "toolbar");
-  el.setAttribute("aria-label", "Special keys");
-
-  const armed: Record<Modifier, boolean> = { ctrl: false, alt: false };
-  const modBtns: Partial<Record<Modifier, HTMLButtonElement>> = {};
-
-  const setMod = (mod: Modifier, on: boolean) => {
-    armed[mod] = on;
-    modBtns[mod]?.setAttribute("aria-pressed", String(on));
-  };
-  const clearMods = () => {
-    setMod("ctrl", false);
-    setMod("alt", false);
-  };
-
-  for (const def of KEY_DEFS) {
-    const btn = document.createElement("button");
-    btn.type = "button";
-    btn.className = "keycap";
-    btn.textContent = def.label;
-
-    if ("mod" in def) {
-      btn.classList.add("keycap-mod");
-      btn.setAttribute("aria-pressed", "false");
-      btn.setAttribute("aria-label", `${def.label} modifier`);
-      modBtns[def.mod] = btn;
-      btn.addEventListener("click", () => setMod(def.mod, !armed[def.mod]));
-    } else if ("cursor" in def) {
-      btn.addEventListener("click", () => {
-        send(cursorSeq(def.cursor, armed.ctrl, armed.alt));
-        clearMods();
-      });
-    } else if ("tilde" in def) {
-      btn.addEventListener("click", () => {
-        send(tildeSeq(def.tilde, armed.ctrl, armed.alt));
-        clearMods();
-      });
-    } else if ("char" in def) {
-      btn.addEventListener("click", () => {
-        send(applyModsToChar(def.char, armed.ctrl, armed.alt));
-        clearMods();
-      });
-    } else {
-      btn.addEventListener("click", () => {
-        send(def.seq);
-        clearMods();
-      });
-    }
-
-    // Keep the terminal focused (soft keyboard up) — don't let the tap steal it.
-    // preventDefault suppresses the native `:active` style, so flash an explicit
-    // press animation here for tactile feedback.
-    btn.addEventListener("pointerdown", (e) => {
-      e.preventDefault();
-      btn.classList.remove("is-pressed");
-      void btn.offsetWidth; // restart the animation if re-tapped mid-flash
-      btn.classList.add("is-pressed");
-    });
-    btn.addEventListener("animationend", () => btn.classList.remove("is-pressed"));
-    el.appendChild(btn);
-  }
-
-  return {
-    el,
-    consume(data: string): string {
-      if ((armed.ctrl || armed.alt) && data.length === 1) {
-        const out = applyModsToChar(data, armed.ctrl, armed.alt);
-        clearMods();
-        return out;
-      }
-      return data;
-    },
-  };
-}

web/src/barActions.test.ts

@@ -1,139 +0,0 @@
-// @vitest-environment happy-dom
-//
-// The sidebar's half of the command bar's action page (#151): the bar picks
-// kill or rename and raises the flow the card already has, so what the page
-// runs is what the ✕ button and the `r` key run.
-import { afterEach, beforeAll, describe, expect, it } from "vitest";
-
-import { KILL_SESSION_EVENT, RENAME_SESSION_EVENT, 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: () => {} },
-  });
-});
-
-let mounted: { el: HTMLElement; dispose: () => void } | null = null;
-
-afterEach(() => {
-  document.querySelector(".kill-dialog")?.remove();
-  mounted?.dispose();
-  mounted = null;
-  document.body.replaceChildren();
-});
-
-function session(overrides: Partial<Session> = {}): Session {
-  return {
-    id: "aaaaaaaa-0000-0000-0000-0000000000ff",
-    cwd: "/home/naps/tea/maestro",
-    command: "claude",
-    env: {},
-    metadata: { name: "amber-falcon" },
-    status: "Running",
-    created_at: "2026-08-24T10:00:00Z",
-    ...overrides,
-  };
-}
-
-function storeWith(sessions: Session[]): CatalogStore {
-  const state = { sessions: new Map(sessions.map((s) => [s.id, s])) };
-  return {
-    snapshot: () => state,
-    subscribe: (fn: CatalogListener) => {
-      fn(state);
-      return () => {};
-    },
-  } as unknown as CatalogStore;
-}
-
-function mount(s: Session): HTMLElement {
-  const handle = renderSidebar(storeWith([s]));
-  mounted = handle;
-  document.body.appendChild(handle.el);
-  return handle.el;
-}
-
-function raise(name: string, s: Session): void {
-  document.dispatchEvent(new CustomEvent(name, { detail: s }));
-}
-
-/** Let the kill chain's awaits (fetch, its json body) settle. */
-async function flush(): Promise<void> {
-  for (let i = 0; i < 8; i++) await Promise.resolve();
-}
-
-describe("kill from the action page", () => {
-  it("goes through the same confirmation the sidebar raises (#160)", async () => {
-    const calls: string[] = [];
-    window.fetch = ((url: string, init?: RequestInit) => {
-      calls.push(`${init?.method ?? "GET"} ${url}`);
-      return Promise.resolve(new Response(null, { status: 204 }));
-    }) as typeof fetch;
-    const s = session();
-    mount(s);
-    raise(KILL_SESSION_EVENT, s);
-    await flush();
-    expect(document.querySelector(".kill-dialog")?.getAttribute("aria-label")).toBe(
-      "Kill amber-falcon",
-    );
-    expect(calls.filter((c) => c.startsWith("DELETE"))).toHaveLength(0);
-    document.querySelector<HTMLButtonElement>(".kill-dialog-kill")?.click();
-    await flush();
-    expect(calls).toContain(`DELETE /api/sessions/${s.id}`);
-    expect(document.querySelector(".kill-dialog")).toBeNull();
-  });
-
-  it("raises the existing confirm-and-blockers dialog on a guarded refusal", async () => {
-    window.fetch = ((url: string) => {
-      if (String(url).includes("force=true")) {
-        return Promise.resolve(new Response(null, { status: 204 }));
-      }
-      return Promise.resolve(
-        new Response(
-          JSON.stringify({
-            error: {
-              code: "kill_guarded",
-              message: "worktree has unsaved work",
-              unsaved_work: { untracked_files: 1 },
-            },
-          }),
-          { status: 409, headers: { "content-type": "application/json" } },
-        ),
-      );
-    }) as typeof fetch;
-    const s = session({ blocked_work: { untracked_files: 1 } });
-    mount(s);
-    raise(KILL_SESSION_EVENT, s);
-    await flush();
-    document.querySelector<HTMLButtonElement>(".kill-dialog-kill")?.click();
-    await flush();
-    const dialog = document.querySelector(".kill-dialog");
-    expect(dialog?.getAttribute("aria-label")).toBe("Kill amber-falcon");
-    expect(dialog?.textContent).toContain("1 untracked file");
-  });
-});
-
-describe("rename from the action page", () => {
-  it("expands the folder hiding the card, since the prompt lives in the card", () => {
-    window.fetch = (() => Promise.reject(new Error("offline"))) as typeof fetch;
-    const s = session();
-    const el = mount(s);
-    const folder = el.querySelector<HTMLElement>(".tree-folder-header");
-    folder?.click();
-    expect(el.querySelector(`[data-session-id="${s.id}"]`)).toBeNull();
-    raise(RENAME_SESSION_EVENT, s);
-    expect(el.querySelector<HTMLInputElement>(".leaf-rename")?.value).toBe("amber-falcon");
-  });
-
-  it("raises the card's own prompt, pre-filled with the session's name", () => {
-    window.fetch = (() => Promise.reject(new Error("offline"))) as typeof fetch;
-    const s = session();
-    const el = mount(s);
-    raise(RENAME_SESSION_EVENT, s);
-    const input = el.querySelector<HTMLInputElement>(".leaf-rename");
-    expect(input?.value).toBe("amber-falcon");
-    expect(input?.getAttribute("aria-label")).toBe("Rename amber-falcon");
-  });
-});

web/src/catalog.test.ts

@@ -1,440 +0,0 @@
-// @vitest-environment happy-dom
-import { afterEach, beforeAll, describe, expect, it } from "vitest";
-
-import { renderSidebar } from "./catalog.js";
-import type { CatalogListener, CatalogStore } from "./events.js";
-import type { InTheWay, Session } from "./types.js";
-
-// happy-dom runs without a backing store; renderSidebar reads the persisted
-// sidebar width on mount.
-beforeAll(() => {
-  Object.defineProperty(window, "localStorage", {
-    value: { getItem: () => null, setItem: () => {} },
-  });
-  // No daemon here; renderSidebar treats a failed info fetch as "absolute
-  // paths are a fine fallback".
-  window.fetch = () => Promise.reject(new Error("offline"));
-});
-
-afterEach(() => {
-  document.querySelector(".kill-dialog")?.remove();
-});
-
-function session(overrides: Partial<Session>): Session {
-  return {
-    id: "11111111-2222-3333-4444-555555555555",
-    cwd: "/home/naps/tea/maestro",
-    command: "claude",
-    env: {},
-    metadata: {},
-    status: "Running",
-    created_at: "2026-08-24T10:00:00Z",
-    ...overrides,
-  };
-}
-
-function storeWith(sessions: Session[]): CatalogStore {
-  const state = { sessions: new Map(sessions.map((s) => [s.id, s])) };
-  return {
-    snapshot: () => state,
-    // Like the real store, deliver an immediate snapshot so the sidebar
-    // renders its rows during construction.
-    subscribe: (fn: CatalogListener) => {
-      fn(state);
-      return () => {};
-    },
-  } as unknown as CatalogStore;
-}
-
-function rowFor(el: HTMLElement, id: string): HTMLElement | null {
-  return el.querySelector<HTMLElement>(`[data-session-id="${id}"]`);
-}
-
-/** Let the kill chain's awaits (fetch, its json body) settle. */
-async function flush(): Promise<void> {
-  for (let i = 0; i < 8; i++) await Promise.resolve();
-}
-
-describe("blocked-work indicator (#83)", () => {
-  it("marks the row of a blocked session in diff notation", () => {
-    const blocked = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000001",
-      blocked_work: {
-        uncommitted_files: 3,
-        unpushed_commits: 2,
-        insertions: 124,
-        deletions: 18,
-      },
-    });
-    const el = renderSidebar(storeWith([blocked])).el;
-    const badge = rowFor(el, blocked.id)?.querySelector(".leaf-blocked");
-    expect(badge?.textContent).toBe("+124-18↑2");
-    // The spelled-out breakdown survives in the tooltip.
-    expect(badge?.getAttribute("title")).toContain(
-      "3 uncommitted files, 2 unpushed commits",
-    );
-  });
-
-  it("falls back to the file count when tracked changes carry no lines", () => {
-    const blocked = session({
-      id: "aaaaaaaa-0000-0000-0000-00000000001a",
-      blocked_work: { uncommitted_files: 2, untracked_files: 1 },
-    });
-    const el = renderSidebar(storeWith([blocked])).el;
-    const badge = rowFor(el, blocked.id)?.querySelector(".leaf-blocked");
-    expect(badge?.textContent).toBe("~2?1");
-  });
-
-  it("does not mark clear or unprobed sessions", () => {
-    const clear = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000002",
-      blocked_work: {} as InTheWay,
-    });
-    const unprobed = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000003",
-    });
-    const el = renderSidebar(storeWith([clear, unprobed])).el;
-    expect(rowFor(el, clear.id)?.querySelector(".leaf-blocked")).toBeNull();
-    expect(rowFor(el, unprobed.id)?.querySelector(".leaf-blocked")).toBeNull();
-  });
-
-  it("confirms before an unguarded kill (#160)", async () => {
-    const calls: string[] = [];
-    window.fetch = ((url: string, init?: RequestInit) => {
-      calls.push(`${init?.method ?? "GET"} ${url}`);
-      return Promise.resolve(new Response(null, { status: 204 }));
-    }) as typeof fetch;
-    const plain = session({ id: "aaaaaaaa-0000-0000-0000-000000000005" });
-    const el = renderSidebar(storeWith([plain])).el;
-    rowFor(el, plain.id)?.querySelector<HTMLButtonElement>(".leaf-kill")?.click();
-    await flush();
-    const dialog = document.querySelector(".kill-dialog");
-    expect(dialog?.getAttribute("aria-label")).toBe("Kill claude");
-    expect(calls.filter((c) => c.startsWith("DELETE"))).toHaveLength(0);
-    dialog?.querySelector<HTMLButtonElement>(".kill-dialog-kill")?.click();
-    await flush();
-    expect(calls).toContain(`DELETE /api/sessions/${plain.id}`);
-    expect(document.querySelector(".kill-dialog")).toBeNull();
-  });
-
-  it("kills nothing when the confirmation is cancelled (#160)", async () => {
-    const calls: string[] = [];
-    window.fetch = ((url: string, init?: RequestInit) => {
-      calls.push(`${init?.method ?? "GET"} ${url}`);
-      return Promise.resolve(new Response(null, { status: 204 }));
-    }) as typeof fetch;
-    const plain = session({ id: "aaaaaaaa-0000-0000-0000-000000000007" });
-    const el = renderSidebar(storeWith([plain])).el;
-    rowFor(el, plain.id)?.querySelector<HTMLButtonElement>(".leaf-kill")?.click();
-    await flush();
-    document.querySelector<HTMLButtonElement>(".kill-dialog-cancel")?.click();
-    await flush();
-    expect(document.querySelector(".kill-dialog")).toBeNull();
-    expect(calls.filter((c) => c.startsWith("DELETE"))).toHaveLength(0);
-  });
-
-  it("names the blockers in the confirmation, before the daemon refuses (#160)", async () => {
-    window.fetch = (() => Promise.reject(new Error("never called"))) as typeof fetch;
-    const blocked = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000008",
-      blocked_work: { untracked_files: 1 },
-    });
-    const el = renderSidebar(storeWith([blocked])).el;
-    rowFor(el, blocked.id)?.querySelector<HTMLButtonElement>(".leaf-kill")?.click();
-    await flush();
-    const dialog = document.querySelector(".kill-dialog");
-    expect(dialog?.textContent).toContain("1 untracked file");
-    expect(dialog?.textContent).toContain("refused unless it is forced");
-  });
-
-  it("offers the override when the daemon refuses a guarded kill", async () => {
-    const calls: string[] = [];
-    window.fetch = ((url: string, init?: RequestInit) => {
-      calls.push(`${init?.method ?? "GET"} ${url}`);
-      if (url.includes("force=true")) return Promise.resolve(new Response(null, { status: 204 }));
-      return Promise.resolve(
-        new Response(
-          JSON.stringify({
-            error: {
-              code: "kill_guarded",
-              message: "worktree has unsaved work",
-              unsaved_work: { untracked_files: 1 },
-            },
-          }),
-          { status: 409, headers: { "content-type": "application/json" } },
-        ),
-      );
-    }) as typeof fetch;
-    const blocked = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000004",
-      command: "bash",
-      blocked_work: { untracked_files: 1 },
-    });
-    const el = renderSidebar(storeWith([blocked])).el;
-    rowFor(el, blocked.id)?.querySelector<HTMLButtonElement>(".leaf-kill")?.click();
-    await flush();
-    document.querySelector<HTMLButtonElement>(".kill-dialog-kill")?.click();
-    await flush();
-    const dialog = document.querySelector(".kill-dialog");
-    expect(dialog?.textContent).toContain("1 untracked file");
-    dialog?.querySelector<HTMLButtonElement>(".kill-dialog-force")?.click();
-    await flush();
-    expect(calls).toContain(`DELETE /api/sessions/${blocked.id}?force=true`);
-    expect(document.querySelector(".kill-dialog")).toBeNull();
-  });
-
-  it("closes the override prompt without killing on cancel", async () => {
-    const calls: string[] = [];
-    window.fetch = ((url: string, init?: RequestInit) => {
-      calls.push(`${init?.method ?? "GET"} ${url}`);
-      return Promise.resolve(
-        new Response(
-          JSON.stringify({
-            error: { code: "kill_guarded", message: "worktree has unsaved work" },
-          }),
-          { status: 409, headers: { "content-type": "application/json" } },
-        ),
-      );
-    }) as typeof fetch;
-    const blocked = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000006",
-      blocked_work: { unpushed_commits: 2 },
-    });
-    const el = renderSidebar(storeWith([blocked])).el;
-    rowFor(el, blocked.id)?.querySelector<HTMLButtonElement>(".leaf-kill")?.click();
-    await flush();
-    document.querySelector<HTMLButtonElement>(".kill-dialog-kill")?.click();
-    await flush();
-    document.querySelector<HTMLButtonElement>(".kill-dialog-cancel")?.click();
-    expect(document.querySelector(".kill-dialog")).toBeNull();
-    expect(calls.filter((c) => c.includes("force=true"))).toHaveLength(0);
-  });
-});
-
-describe("agent-reported detail (#112)", () => {
-  const ago = (ms: number): string => new Date(Date.now() - ms).toISOString();
-
-  it("renders the reported detail right after the duration on line 2", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000020",
-      status: "Dead",
-      activity: "Error",
-      activity_since: ago(90_000),
-      activity_detail: "cargo build failed",
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
-    expect(line2?.querySelector(".activity-detail")?.textContent).toBe("cargo build failed");
-    const order = [...line2!.children].map((c) => c.className);
-    expect(order.indexOf("activity-detail")).toBeGreaterThan(order.indexOf("activity-duration"));
-    expect(order.indexOf("activity-detail")).toBeLessThan(
-      order.findIndex((c) => c.startsWith("card-flag")),
-    );
-  });
-
-  it("omits the detail when no report is in force", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000021",
-      activity: "Active",
-      activity_since: ago(90_000),
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    expect(rowFor(el, s.id)?.querySelector(".activity-detail")).toBeNull();
-  });
-});
-
-describe("session cards (#107)", () => {
-  const ago = (ms: number): string => new Date(Date.now() - ms).toISOString();
-
-  it("keeps the name and the actions in the same flow line, actions reserving their width", () => {
-    const s = session({ id: "aaaaaaaa-0000-0000-0000-000000000010" });
-    const el = renderSidebar(storeWith([s])).el;
-    const line1 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line1");
-    expect(line1).not.toBeNull();
-    // Same flex line ⇒ the name truncates before it can ever reach the buttons.
-    expect(line1?.querySelector(".leaf-name")).not.toBeNull();
-    expect(line1?.querySelector(".leaf-actions")).toBe(line1?.lastElementChild);
-  });
-
-  it("always renders line 2 for a freshly spawned session", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000011",
-      activity: "Active",
-      activity_since: ago(5_000),
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const row = rowFor(el, s.id);
-    const line2 = row?.querySelector<HTMLElement>(".card-line2");
-    expect(line2).not.toBeNull();
-    expect(row?.querySelector(".activity-rail")).not.toBeNull();
-    expect(line2?.querySelector(".activity-duration")).toBeNull();
-    expect(line2?.querySelector(".leaf-cmd")).not.toBeNull();
-  });
-
-  it("shows dot + floored duration once the state has been held past 30s", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000012",
-      activity: "Active",
-      activity_since: ago(4 * 60_000 + 30_000),
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const row = rowFor(el, s.id);
-    const line2 = row?.querySelector<HTMLElement>(".card-line2");
-    expect(line2?.dataset.activity).toBe("active");
-    expect(row?.querySelector(".activity-rail")).not.toBeNull();
-    expect(line2?.querySelector(".activity-duration")?.textContent).toBe("4m");
-  });
-
-  it("dims a name the daemon generated, until it settles (#131)", () => {
-    const generated = session({
-      id: "aaaaaaaa-0000-0000-0000-0000000000a1",
-      metadata: { name: "amber-falcon", name_source: "Generated" },
-    });
-    const haiku = session({
-      id: "aaaaaaaa-0000-0000-0000-0000000000a2",
-      metadata: { name: "sidebar-rail", name_source: "Haiku" },
-    });
-    const chosen = session({
-      id: "aaaaaaaa-0000-0000-0000-0000000000a3",
-      metadata: { name: "my-session", name_source: "User" },
-    });
-    // Named before `name_source` existed: settled, never dimmed.
-    const legacy = session({
-      id: "aaaaaaaa-0000-0000-0000-0000000000a4",
-      metadata: { name: "older-session" },
-    });
-
-    const el = renderSidebar(storeWith([generated, haiku, chosen, legacy])).el;
-    const provisional = (s: Session) =>
-      rowFor(el, s.id)?.querySelector(".leaf-name")?.classList.contains("is-provisional");
-    expect(provisional(generated)).toBe(true);
-    expect(provisional(haiku)).toBe(false);
-    expect(provisional(chosen)).toBe(false);
-    expect(provisional(legacy)).toBe(false);
-  });
-
-  it("renders the command as its tool icon when the tool is known", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-00000000001b",
-      command: "claude",
-      metadata: { name: "claude" },
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const cmd = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2 .leaf-cmd");
-    expect(cmd?.querySelector(".tool-icon")?.getAttribute("data-tool")).toBe("claude");
-    expect(cmd?.getAttribute("title")).toBe("claude");
-    // The icon said it all: no text left over.
-    expect(cmd?.querySelector(".leaf-cmd-rest")).toBeNull();
-  });
-
-  it("drops the command's arguments, keeping them in the tooltip", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-00000000001c",
-      command: "claude --dangerously-skip-permissions",
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const cmd = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2 .leaf-cmd");
-    expect(cmd?.querySelector(".tool-icon")?.getAttribute("data-tool")).toBe("claude");
-    expect(cmd?.querySelector(".leaf-cmd-rest")).toBeNull();
-    expect(cmd?.getAttribute("title")).toBe("claude --dangerously-skip-permissions");
-  });
-
-  it("keeps an unknown command as plain text", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-00000000001d",
-      command: "hx src/main.rs",
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const cmd = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2 .leaf-cmd");
-    expect(cmd?.querySelector(".tool-icon")).toBeNull();
-    expect(cmd?.querySelector(".leaf-cmd-rest")?.textContent).toBe("hx");
-    expect(cmd?.getAttribute("title")).toBe("hx src/main.rs");
-  });
-
-  it("maps each activity state to its contract slug", () => {
-    const mk = (id: string, activity: string) =>
-      session({
-        id,
-        activity: activity as Session["activity"],
-        status: "Running",
-        activity_since: ago(90_000),
-      });
-    const idle = mk("aaaaaaaa-0000-0000-0000-000000000013", "Idle");
-    const wait = mk("aaaaaaaa-0000-0000-0000-000000000014", "AwaitingInput");
-    const error = mk("aaaaaaaa-0000-0000-0000-000000000015", "Error");
-    const el = renderSidebar(storeWith([idle, wait, error])).el;
-    expect(rowFor(el, idle.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
-      "idle",
-    );
-    expect(rowFor(el, wait.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
-      "awaiting-input",
-    );
-    expect(rowFor(el, error.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
-      "error",
-    );
-  });
-
-  it("treats an unknown activity variant as idle instead of failing to render", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000016",
-      activity: "Teleported" as Session["activity"],
-      activity_since: ago(120_000),
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const line2 = rowFor(el, s.id)?.querySelector(".card-line2");
-    expect(line2?.getAttribute("data-activity")).toBe("idle");
-    expect(line2?.querySelector(".activity-duration")?.textContent).toBe("2m");
-  });
-
-  it("moves blocked work onto line 2 as diff notation", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000017",
-      blocked_work: {
-        uncommitted_files: 3,
-        unpushed_commits: 2,
-        insertions: 124,
-        deletions: 18,
-      },
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
-    expect(line2?.textContent).toContain("+124");
-    expect(line2?.textContent).toContain("-18");
-    // Line 1 carries no badges.
-    expect(rowFor(el, s.id)?.querySelector(".leaf-badge")).toBeNull();
-  });
-
-  it("shows exited on line 2 for dead sessions", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000018",
-      status: "Dead",
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
-    expect(line2?.textContent).toContain("exited");
-  });
-
-  it("carries the state word only in tooltips and aria labels, never as text", () => {
-    const s = session({
-      id: "aaaaaaaa-0000-0000-0000-000000000019",
-      command: "claude",
-      metadata: { name: "worker" },
-      activity: "AwaitingInput",
-      activity_since: ago(90_000),
-    });
-    const el = renderSidebar(storeWith([s])).el;
-    const row = rowFor(el, s.id) as HTMLElement;
-    const rail = row.querySelector<HTMLElement>(".activity-rail");
-    expect(rail?.getAttribute("title")).toContain("Awaiting input");
-    expect(rail?.getAttribute("aria-label")).toContain("Awaiting input");
-    expect(row.textContent).not.toMatch(/awaiting.?input/i);
-  });
-
-  it("keeps the attach navigation and depth indentation", () => {
-    const s = session({ id: "aaaaaaaa-0000-0000-0000-00000000001a" });
-    const el = renderSidebar(storeWith([s])).el;
-    const row = rowFor(el, s.id) as HTMLAnchorElement;
-    expect(row.getAttribute("href")).toBe("#/attach/aaaaaaaa-0000-0000-0000-00000000001a");
-    expect(row.style.paddingLeft).toMatch(/^\d+(\.\d+)?px$/);
-  });
-});

web/src/catalog.ts

@@ -1,872 +0,0 @@
-import { escapeHtml } from "./html.js";
-import { ApiRequestError, getDaemonInfo, killSession, renameSession } from "./api.js";
-import { openForceKillDialog, openKillConfirmDialog } from "./killDialog.js";
-import { openContextMenu } from "./contextMenu.js";
-import { toggleHelp } from "./help.js";
-import { CommandSet, defineCommands } from "./commands.js";
-import { CatalogStore } from "./events.js";
-import type { InTheWay, Session } from "./types.js";
-import {
-  abbreviateCwd,
-  abbreviateFolderName,
-  blockerStats,
-  customSessionName,
-  formatInTheWay,
-  MAX_SESSION_NAME_LEN,
-  normalizeSessionName,
-  sessionBlockers,
-  isProvisionalName,
-  sessionName,
-  sessionTreePath,
-} from "./types.js";
-import { splitCommand, toolIconSvg } from "./toolIcon.js";
-import {
-  activityColorSlug,
-  activityDurationLabel,
-  activityHeldMs,
-  META_LINE_MIN_HOLD_MS,
-} from "./activity.js";
-import type { TreeNode } from "./tree.js";
-import { buildTree } from "./tree.js";
-import { createPaletteSelect, createThemeToggle } from "./theme.js";
-import type { DaemonLink } from "./daemonLink.js";
-import { createStatusIndicator } from "./statusIndicator.js";
-
-/** Ask the shell to open the spawn modal. Handled in main.ts, where the
- *  multi-view controller lives; dispatched from every Spawn affordance. */
-export const OPEN_SPAWN_EVENT = "catalog-open-spawn";
-export function requestOpenSpawn(): void {
-  document.dispatchEvent(new CustomEvent(OPEN_SPAWN_EVENT));
-}
-
-/** Ask the shell to open the command bar with an empty query. Dispatched by
- *  the sidebar's search field, which is the touch entry point to the bar
- *  (#157, docs/COMMAND-BAR.md "Touch entry"): there is no `ctrl-k` on a phone.
- *  Handled in main.ts, which owns the session snapshot the bar needs. */
-export const OPEN_COMMAND_BAR_EVENT = "catalog-open-command-bar";
-export function requestOpenCommandBar(): void {
-  document.dispatchEvent(new CustomEvent(OPEN_COMMAND_BAR_EVENT));
-}
-
-/** Ask the shell to hand the keyboard back to the focused pane's terminal —
- *  what Tab in the sidebar list does. Handled in main.ts, which owns the
- *  connection pool. */
-export const FOCUS_PANE_EVENT = "catalog-focus-pane";
-
-/** Ask the shell to open the spawn modal seeded from an existing session
- *  ("Spawn similar"). Detail is the session being cloned. */
-export const SPAWN_SIMILAR_EVENT = "catalog-spawn-similar";
-
-/** Ask the sidebar to kill a session — the command bar's action page picking
- *  `kill` (#151). Detail is the session. Handled here, so the kill goes
- *  through the same confirm-and-blockers flow the card's ✕ does
- *  (`docs/WORKTREES.md`); the bar never reimplements it. */
-export const KILL_SESSION_EVENT = "catalog-kill-session";
-
-/** Ask the sidebar to rename a session — the command bar's action page picking
- *  `rename` (#151). Detail is the session. The prompt is the card's own inline
- *  field, pre-filled with the session's name (`docs/SIDEBAR.md`). */
-export const RENAME_SESSION_EVENT = "catalog-rename-session";
-
-/** A session row was clicked (issue #133). The row's `href` drives normal
- *  hash navigation, but a split/drag can move focus without ever touching
- *  `location.hash` — so a click back onto a session whose hash still
- *  matches fires no `hashchange` and the app never hears about it. This
- *  event is the click-driven path that doesn't depend on the hash actually
- *  changing. */
-export const SESSION_SELECT_EVENT = "catalog-session-select";
-
-/** The rows a keyboard walk stops on, in visual (document) order. Expanded
- *  folder headers are skipped: a directory is not something to focus, and the
- *  cards under it are one row away anyway. A *collapsed* folder still counts —
- *  its header is the only row it has, so skipping it would leave the folder
- *  unreachable. Same rule as the TUI sidebar. */
-const NAV_SELECTOR = '.tree-leaf, .tree-folder-header[aria-expanded="false"]';
-
-const collapsed = new Set<string>();
-
-/** Session whose card is currently being renamed inline (#125). The tree
- * re-renders on every catalog delta, and an activity update arriving mid-edit
- * would otherwise replace the field the user is typing into. */
-let renamingId: string | null = null;
-
-// docs/SIDEBAR.md: the state word is never rendered — the rail's colour
-// carries it. It survives only in tooltips/aria labels so meaning is not
-// colour-only.
-const STATE_WORDS: Record<string, string> = {
-  active: "Active",
-  idle: "Idle",
-  "awaiting-input": "Awaiting input",
-  error: "Error",
-};
-
-/** docs/SIDEBAR.md: the activity rail is pinned to the row's own left edge,
- * full height. The row's own padding (`renderNode`) shifts outward with
- * nesting depth, carrying the rail with it. */
-function activityRailMarkup(slug: string, stateWord: string): string {
-  return `<span class="activity-rail" data-activity="${slug}" role="img" title="${escapeHtml(stateWord)}" aria-label="${escapeHtml(stateWord)}"></span>`;
-}
-
-function metaLine(s: Session, now: number): string {
-  const dead = s.status === "Dead";
-  const blockers = sessionBlockers(s);
-  const slug = activityColorSlug(s.activity ?? "Idle");
-  const held = activityHeldMs(s.activity_since, now);
-  const duration =
-    held !== null && held >= META_LINE_MIN_HOLD_MS ? activityDurationLabel(held) : null;
-
-  const fragments = [
-    duration ? `<span class="activity-duration">${duration}</span>` : "",
-    s.activity_detail
-      ? `<span class="activity-detail">${escapeHtml(s.activity_detail)}</span>`
-      : "",
-    commandFragment(s.command),
-    blockers ? blockedFragment(blockers) : "",
-    dead ? `<span class="card-flag">exited</span>` : "",
-  ];
-  return `<span class="card-line2" data-activity="${slug}">${fragments.join("")}</span>`;
-}
-
-/** docs/SIDEBAR.md: blocked work renders as diff notation — `+124 -18 ?3 ↑2`
- * — with the spelled-out breakdown kept in the tooltip. */
-function blockedFragment(blockers: InTheWay): string {
-  const stats = blockerStats(blockers)
-    .map((st) => `<span class="blocked-stat" data-stat="${st.kind}">${escapeHtml(st.text)}</span>`)
-    .join("");
-  const title = `Kill will be refused unless forced — ${formatInTheWay(blockers)}`;
-  return `<span class="card-flag leaf-blocked" title="${escapeHtml(title)}">${stats}</span>`;
-}
-
-/** docs/SIDEBAR.md: the card names the program only — arguments never reach
- * the card. The program becomes its tool icon when we have a mark for it, and
- * stays as its bare name when we do not. The full command line, arguments and
- * all, stays in the tooltip either way. */
-function commandFragment(command: string): string {
-  const { tool, program } = splitCommand(command);
-  const icon = tool ? toolIconSvg(tool) : null;
-  const text = icon ? "" : program;
-  return `<span class="card-flag leaf-cmd" title="${escapeHtml(command)}">${icon ?? ""}${text ? `<span class="leaf-cmd-rest">${escapeHtml(text)}</span>` : ""}</span>`;
-}
-
-function renderNode(node: TreeNode, depth: number): HTMLElement {
-  if (node.kind === "folder") {
-    const wrap = document.createElement("div");
-    wrap.className = "tree-folder";
-
-    if (node.name) {
-      const header = document.createElement("button");
-      header.type = "button";
-      header.className = "tree-folder-header";
-      header.style.paddingLeft = `${depth * 16}px`;
-      const isCollapsed = collapsed.has(node.path);
-      header.setAttribute("aria-expanded", String(!isCollapsed));
-      header.dataset.navKey = `folder:${node.path}`;
-      // Single down-chevron; CSS rotates it -90° (→ right) when collapsed, so the
-      // glyph and the rotation never fight each other.
-      // A deep path (`~/git.naps.pt/naps62/maestro`) collapses its leading
-      // segments to initials (`~/g/n/maestro`) so the dir name stays readable in
-      // a narrow sidebar; the full path lives in the tooltip.
-      header.innerHTML = `<span class="chevron">▾</span><span class="folder-name" title="${escapeHtml(node.name)}">${abbreviateFolderName(node.name)}</span>`;
-      header.addEventListener("click", () => {
-        if (collapsed.has(node.path)) collapsed.delete(node.path);
-        else collapsed.add(node.path);
-        // re-render handled by caller observing the store; trigger a refresh:
-        document.dispatchEvent(new CustomEvent("catalog-rerender"));
-      });
-      wrap.appendChild(header);
-      if (isCollapsed) return wrap;
-    }
-
-    for (const child of node.children) {
-      wrap.appendChild(renderNode(child, node.name ? depth + 1 : depth));
-    }
-    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");
-  row.className = "tree-leaf session-card";
-  row.href = `#/attach/${encodeURIComponent(s.id)}`;
-  row.style.paddingLeft = `${depth * 16 + 8}px`;
-  row.dataset.sessionId = s.id;
-  row.dataset.navKey = `session:${s.id}`;
-  const running = s.status === "Running";
-  row.dataset.status = running ? "running" : "dead";
-  const name = sessionName(s);
-  const slug = activityColorSlug(s.activity ?? "Idle");
-  const stateWord = STATE_WORDS[slug] ?? STATE_WORDS.idle;
-  row.setAttribute(
-    "aria-label",
-    `${name}, ${running ? "running" : "exited"}, ${stateWord}`,
-  );
-  // docs/SIDEBAR.md: line 1 reserves action width, and line 2 is unconditional.
-  row.innerHTML = `
-    ${activityRailMarkup(slug, stateWord)}
-    <span class="card-line1">
-      <span class="leaf-name${isProvisionalName(s) ? " is-provisional" : ""}">${escapeHtml(name)}</span>
-      <span class="leaf-actions">
-        <button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>
-        <button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${escapeHtml(name)}">✕</button>
-      </span>
-    </span>
-    ${metaLine(s, now)}
-  `;
-  const similarBtn = row.querySelector(".leaf-clone") as HTMLButtonElement;
-  similarBtn.addEventListener("click", (ev) => {
-    ev.preventDefault();
-    ev.stopPropagation();
-    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();
-    requestKill(cur, sessionName(cur));
-  });
-  row.addEventListener("click", () => {
-    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, cur) },
-      {
-        label: "Spawn similar",
-        onSelect: () =>
-          document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur })),
-      },
-      {
-        label: "Kill session",
-        danger: true,
-        onSelect: () => requestKill(cur, sessionName(cur)),
-      },
-    ]);
-  });
-  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 behind a confirmation (#160): a kill is destructive and unattended
- * agents live in these sessions, so the web asks first, the way the TUI always
- * has. The daemon decides the rest — it refuses a kill over a worktree holding
- * unsaved work, and that refusal needs a prompt the confirmation cannot give,
- * a forced kill. Anything else surfaces in the dialog that asked.
- */
-function requestKill(s: Session, name: string): void {
-  openKillConfirmDialog({
-    name,
-    blockers: sessionBlockers(s),
-    onKill: async () => {
-      try {
-        await killSession(s.id);
-      } catch (e) {
-        if (e instanceof ApiRequestError && e.code === "kill_guarded") {
-          openForceKillDialog({
-            name,
-            blockers: e.unsavedWork ?? sessionBlockers(s),
-            reason: e.detail,
-            onForce: () => killSession(s.id, true),
-          });
-          return;
-        }
-        throw e;
-      }
-    },
-  });
-}
-
-/**
- * Swap the card's name for a text field (#125). Enter commits, Escape and
- * blur cancel. An emptied field clears the name, so the card falls back to
- * the command — the same rule the spawn form's blank name field follows.
- */
-function beginRename(row: HTMLElement, s: Session): void {
-  const nameEl = row.querySelector<HTMLElement>(".leaf-name");
-  if (!nameEl) return;
-  const input = document.createElement("input");
-  input.type = "text";
-  input.className = "leaf-name leaf-rename";
-  input.value = customSessionName(s) ?? "";
-  input.maxLength = MAX_SESSION_NAME_LEN;
-  input.setAttribute("aria-label", `Rename ${sessionName(s)}`);
-  // The card is an <a>, and the tree starts a drag on pointerdown: without
-  // these, clicking into the field navigates away or begins dragging the row.
-  for (const type of ["click", "pointerdown", "dblclick"]) {
-    input.addEventListener(type, (ev) => {
-      ev.preventDefault();
-      ev.stopPropagation();
-      input.focus();
-    });
-  }
-
-  renamingId = s.id;
-  let settled = false;
-  const finish = () => {
-    if (settled) return false;
-    settled = true;
-    renamingId = null;
-    document.dispatchEvent(new CustomEvent("catalog-rerender"));
-    return true;
-  };
-
-  input.addEventListener("keydown", (ev) => {
-    if (ev.key === "Enter") {
-      ev.preventDefault();
-      // Normalised here so what is sent is what the daemon will store.
-      const name = normalizeSessionName(input.value);
-      if (!finish()) return;
-      void renameSession(s.id, name).catch((e: Error) => {
-        alert(`Failed to rename: ${e.message}`);
-      });
-    } else if (ev.key === "Escape") {
-      ev.preventDefault();
-      finish();
-    }
-  });
-  input.addEventListener("blur", () => finish());
-
-  nameEl.replaceWith(input);
-  input.focus();
-  input.select();
-}
-
-// The tree has one empty state: no sessions at all. The old "No matches" one
-// belonged to the inline substring filter, which the command bar replaced
-// (#157) — the bar's own no-results state took over with it.
-function renderEmpty(onSpawn: () => void): HTMLElement {
-  const el = document.createElement("div");
-  el.className = "empty";
-  el.innerHTML = `
-    <div class="empty-glyph" aria-hidden="true">+</div>
-    <div class="empty-title">No sessions yet</div>
-    <p class="empty-hint">Start your first session — it'll show up here.</p>
-    <div class="empty-actions"></div>`;
-  const spawn = document.createElement("button");
-  spawn.type = "button";
-  spawn.className = "btn btn-primary";
-  spawn.textContent = "+ Spawn session";
-  spawn.addEventListener("click", onSpawn);
-  (el.querySelector(".empty-actions") as HTMLElement).appendChild(spawn);
-  return el;
-}
-
-/** Two-tier sidebar highlight state (issue #33): which sessions are open in some
- *  pane (quiet), and which one is focused (loud). */
-export interface SidebarHighlights {
-  open: Set<string>;
-  focused: string | null;
-}
-
-/** Live handle to the persistent sidebar (built once, survives navigation). */
-export interface SidebarHandle {
-  /** The `<aside>` element to mount into the shell. */
-  el: HTMLElement;
-  /** Highlight the row for `id` (or clear it with `null`) as the focused session.
-   *  Back-compat shim over {@link setHighlights}. */
-  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. */
-  hasListFocus(): boolean;
-  /** Tear down the store subscription + listeners. */
-  dispose(): void;
-}
-
-/**
- * Build the persistent session sidebar: brand, search, spawn, theme toggle, a
- * live session status line, and the folder-grouped session tree. Unlike
- * the old full-screen catalog this is mounted once by the shell and stays put
- * while the content pane swaps between sessions — so the store subscription and
- * scroll position survive navigation. The active session is highlighted.
- */
-export interface SidebarOptions {
-  /** Pointerdown on a session row — the multi-view controller decides drag vs
-   *  tap (issue #32). Tap falls through to the row's normal click (open). */
-  onLeafDrag?: (sessionId: string, e: PointerEvent) => void;
-  /** 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 {
-  const el = document.createElement("aside");
-  el.className = "sidebar";
-
-  // The daemon's home dir abbreviates cwds to `~/…`. Fetched once; the tree
-  // renders with absolute paths until it lands.
-  let homeDir: string | undefined;
-
-  // The field never holds a query: it is the touch entry point to the command
-  // bar (#157), so it is `readonly` — a tap opens the bar instead of raising an
-  // on-screen keyboard over a field nothing is typed into.
-  const searchHeader = document.createElement("header");
-  searchHeader.className = "sidebar-search";
-  searchHeader.innerHTML = `
-    <input
-      type="search"
-      class="search"
-      readonly
-      placeholder="Search sessions…"
-      aria-label="Search sessions"
-      autocomplete="off"
-      autocorrect="off"
-      autocapitalize="off"
-      spellcheck="false"
-    />
-  `;
-  el.appendChild(searchHeader);
-
-  const treeHost = document.createElement("div");
-  treeHost.className = "tree";
-  el.appendChild(treeHost);
-
-  // App-level actions (help, theme, spawn) live pinned to the sidebar's foot
-  // rather than the sidebar's own scrolling content, so they stay reachable
-  // regardless of tree scroll position.
-  const footer = document.createElement("div");
-  footer.className = "sidebar-footer";
-  const helpBtn = document.createElement("button");
-  helpBtn.type = "button";
-  helpBtn.className = "btn btn-ghost btn-icon help-btn";
-  helpBtn.textContent = "?";
-  helpBtn.title = "Keyboard shortcuts (?)";
-  helpBtn.setAttribute("aria-label", "Keyboard shortcuts");
-  helpBtn.addEventListener("click", () => toggleHelp());
-  footer.appendChild(helpBtn);
-  footer.appendChild(createThemeToggle());
-  footer.appendChild(createPaletteSelect());
-  // DEV-only shortcut to the standalone design kit (?kit). Lets you reach it by
-  // clicking inside a proxied preview (e.g. crit live) that has no address bar.
-  if (import.meta.env.DEV) {
-    const kit = document.createElement("a");
-    kit.className = "btn btn-ghost";
-    kit.href = "?kit";
-    kit.textContent = "kit";
-    kit.title = "Open the design kit (DEV)";
-    footer.appendChild(kit);
-  }
-  // Daemon status sits beside the spawn button: colour for the link state,
-  // hover for the release the daemon is running.
-  const status = opts.link ? createStatusIndicator(opts.link) : null;
-  if (status) footer.appendChild(status.el);
-  const spawnBtn = document.createElement("button");
-  spawnBtn.type = "button";
-  spawnBtn.className = "btn btn-primary spawn-btn";
-  spawnBtn.textContent = "+ Spawn";
-  // The keyboard pair sits right here in the tooltip (#67).
-  spawnBtn.title = "Spawn form: n — fast-forward spawn: N";
-  spawnBtn.addEventListener("click", () => requestOpenSpawn());
-  footer.appendChild(spawnBtn);
-  el.appendChild(footer);
-
-  // Drag a session row into the canvas (issue #32). Delegated so it survives
-  // tree re-renders; the controller handles drag-vs-tap (tap still navigates).
-  treeHost.addEventListener("pointerdown", (e) => {
-    if (e.button !== 0 || !opts.onLeafDrag) return;
-    const leaf = (e.target as HTMLElement).closest<HTMLElement>(".tree-leaf");
-    const id = leaf?.dataset.sessionId;
-    if (id) opts.onLeafDrag(id, e);
-  });
-  // The rows are <a> elements, so the browser's native link drag-and-drop would
-  // otherwise hijack pointermove and our live drop-zone preview wouldn't show
-  // until release. Suppress it so the pointer-based drag runs from the start.
-  treeHost.addEventListener("dragstart", (e) => {
-    if ((e.target as HTMLElement).closest(".tree-leaf")) e.preventDefault();
-  });
-
-  // Drag-to-resize handle on the sidebar's right edge. Persists the chosen
-  // width as a :root CSS var the shell grid reads; clamped to a sane range.
-  const SIDEBAR_W_KEY = "maestro-sidebar-w";
-  const storedW = localStorage.getItem(SIDEBAR_W_KEY);
-  if (storedW) document.documentElement.style.setProperty("--sidebar-w", storedW);
-  const handle = document.createElement("div");
-  handle.className = "sidebar-resize";
-  handle.setAttribute("aria-hidden", "true");
-  el.appendChild(handle);
-  let dragStartX = 0;
-  let dragStartW = 0;
-  let dragging = false;
-  handle.addEventListener("pointerdown", (e) => {
-    dragging = true;
-    dragStartX = e.clientX;
-    dragStartW = el.getBoundingClientRect().width;
-    handle.setPointerCapture(e.pointerId);
-    document.body.style.userSelect = "none";
-    e.preventDefault();
-  });
-  handle.addEventListener("pointermove", (e) => {
-    if (!dragging) return;
-    const w = Math.max(200, Math.min(560, dragStartW + (e.clientX - dragStartX)));
-    document.documentElement.style.setProperty("--sidebar-w", `${w}px`);
-  });
-  const endDrag = (e: PointerEvent) => {
-    if (!dragging) return;
-    dragging = false;
-    try {
-      handle.releasePointerCapture(e.pointerId);
-    } catch {
-      // pointer may already be released
-    }
-    document.body.style.userSelect = "";
-    const cur = document.documentElement.style.getPropertyValue("--sidebar-w");
-    if (cur) localStorage.setItem(SIDEBAR_W_KEY, cur);
-  };
-  handle.addEventListener("pointerup", endDrag);
-  handle.addEventListener("pointercancel", endDrag);
-
-  // Touch entry (#157): the field is a button that looks like a field. It
-  // never holds a query — focusing or tapping it hands the keyboard straight
-  // to the bar's own input, which is also why it blurs first: leaving the
-  // focus here would make the bar impossible to close without reopening it.
-  const search = searchHeader.querySelector(".search") as HTMLInputElement;
-  const openBar = () => {
-    search.value = "";
-    search.blur();
-    requestOpenCommandBar();
-  };
-  search.addEventListener("focus", openBar);
-  // A tap can land without a focus event (iOS Safari on a blurred field), so
-  // the pointer path opens the bar too; the blur above keeps the two from
-  // stacking two overlays.
-  search.addEventListener("pointerdown", (e) => {
-    e.preventDefault();
-    openBar();
-  });
-
-  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;
-      if (!id) continue;
-      const focused = highlights.focused === id;
-      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);
-    }
-  };
-
-  // ---- keyboard navigation ----
-  // The walk reads the rendered DOM rather than a parallel model, so it can
-  // never disagree with what is on screen. Rows carry a `data-nav-key`
-  // (`session:<id>` / `folder:<path>`) that survives a re-render.
-  let navKey: string | null = null;
-
-  const navRows = (): HTMLElement[] => [
-    ...treeHost.querySelectorAll<HTMLElement>(NAV_SELECTOR),
-  ];
-
-  const rowFor = (key: string | null): HTMLElement | undefined =>
-    key === null ? undefined : navRows().find((r) => r.dataset.navKey === key);
-
-  const applyNav = () => {
-    const rows = navRows();
-    // A row that went away (session killed, folder collapsed) drops the
-    // highlight rather than leaving it pointing at nothing.
-    if (navKey !== null && !rows.some((r) => r.dataset.navKey === navKey)) navKey = null;
-    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;
-    const cur = rows.findIndex((r) => r.dataset.navKey === navKey);
-    // Nothing highlighted: start one off the end we are walking from, so the
-    // first step lands on the first (or last) row.
-    const from = cur === -1 ? (delta > 0 ? -1 : 0) : cur;
-    const next = rows[(((from + delta) % rows.length) + rows.length) % rows.length];
-    navKey = next.dataset.navKey ?? null;
-    applyNav();
-    next.scrollIntoView({ block: "nearest" });
-    opts.onPreview?.(sessionOf(navKey));
-  };
-
-  /** Enter: open the highlighted session, or expand the highlighted folder. */
-  const activateNav = () => {
-    const row = rowFor(navKey);
-    if (!row) return;
-    if (row.classList.contains("tree-leaf")) {
-      row.click();
-      return;
-    }
-    // Expanding replaces the folder's header in the walk with the rows it was
-    // hiding, so land on the first of them instead of losing the highlight.
-    const key = navKey;
-    row.click();
-    const header = [...treeHost.querySelectorAll<HTMLElement>(".tree-folder-header")].find(
-      (h) => h.dataset.navKey === key,
-    );
-    const revealed = header?.parentElement
-      ? [...header.parentElement.querySelectorAll<HTMLElement>(NAV_SELECTOR)][0]
-      : undefined;
-    navKey = revealed?.dataset.navKey ?? null;
-    applyNav();
-  };
-
-  // Pointer hover previews only while Ctrl is held — plain hover was too
-  // disruptive when sweeping the sidebar. Keyboard walk (j/k) still previews
-  // unconditionally via applyNav.
-  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" || !e.ctrlKey) 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();
-  };
-
-  // The session list's half of the command registry (#148). One set per
-  // sidebar, so a second sidebar (tests, hot reload) drives its own rows; the
-  // labels and chords still come from the one registry.
-  const listKeys = new CommandSet(
-    defineCommands({
-      "list.next": () => moveNav(1),
-      "list.prev": () => moveNav(-1),
-      "list.activate": () => activateNav(),
-      "list.toggleFolder": () => toggleHighlightedFolder(),
-      "list.rename": () => {
-        const hit = highlightedSession();
-        if (hit) beginRename(hit.row, hit.session);
-      },
-      "list.kill": () => {
-        const hit = highlightedSession();
-        if (hit) requestKill(hit.session, sessionName(hit.session));
-      },
-      "list.focusPane": () => document.dispatchEvent(new CustomEvent(FOCUS_PANE_EVENT)),
-    }),
-  );
-
-  // The inline rename field lives inside a row and owns its own keys; the set's
-  // plain-key rule keeps this walk out of it.
-  treeHost.addEventListener("keydown", (e) => listKeys.handle(e));
-
-  /** 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);
-    const signature = sessions.length === 0 ? "EMPTY" : 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(renderEmpty(() => requestOpenSpawn()));
-      return;
-    }
-    if (tree.kind === "folder") {
-      for (const child of tree.children) treeHost.appendChild(renderNode(child, 0));
-    }
-    applyHighlights();
-    applyNav();
-  };
-
-  void getDaemonInfo()
-    .then((info) => {
-      homeDir = info.home_dir;
-      refresh();
-    })
-    .catch(() => {
-      /* absolute paths are a fine fallback */
-    });
-
-  // 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);
-
-  // The command bar's action page (#151) picks an action and hands it here:
-  // both flows are the ones the card already has, reached by session rather
-  // than by row.
-  const killHandler = (ev: Event) => {
-    const s = (ev as CustomEvent<Session>).detail;
-    requestKill(s, sessionName(s));
-  };
-  const renameHandler = (ev: Event) => {
-    const s = (ev as CustomEvent<Session>).detail;
-    const row = rowForSession(s);
-    if (row) beginRename(row, s);
-  };
-  document.addEventListener(KILL_SESSION_EVENT, killHandler);
-  document.addEventListener(RENAME_SESSION_EVENT, renameHandler);
-
-  /** The card a session is rendered as, expanding whatever folder hides it
-   *  first: the rename prompt lives inside the card, so a collapsed folder
-   *  would otherwise swallow the request. */
-  function rowForSession(s: Session): HTMLElement | null {
-    const find = () => treeHost.querySelector<HTMLElement>(`.tree-leaf[data-session-id="${s.id}"]`);
-    const found = find();
-    if (found) return found;
-    // Folder paths are the abbreviated directory's segments joined back up
-    // (see buildTree), so the session's own path is normalised the same way
-    // before it is compared against them.
-    const cwd = sessionTreePath(s);
-    const path = (cwd ? abbreviateCwd(cwd, homeDir) : "").split("/").filter(Boolean).join("/");
-    for (const folder of [...collapsed]) {
-      if (path === folder || path.startsWith(`${folder}/`)) collapsed.delete(folder);
-    }
-    rerenderHandler();
-    return find();
-  }
-
-  // "Spawn similar" (#28) is dispatched here and handled in main.ts, where the
-  // multi-view controller can seed the spawn modal with the session's dir/command.
-
-  const unsubscribe = store.subscribe(refresh);
-
-  // Contract granularity: re-render at least every 30s while visible so the
-  // duration cutover points land within one tick.
-  const clock = setInterval(() => {
-    if (document.visibilityState !== "visible") return;
-    refresh();
-  }, 30_000);
-
-  return {
-    el,
-    setActive(id: string | null) {
-      highlights = {
-        open: id ? new Set([id]) : new Set(),
-        focused: id,
-      };
-      applyHighlights();
-    },
-    setHighlights(h: SidebarHighlights) {
-      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.
-      const preferred = highlights.focused ? `session:${highlights.focused}` : null;
-      const start = rowFor(preferred) ?? rowFor(navKey) ?? navRows()[0];
-      navKey = start?.dataset.navKey ?? null;
-      applyNav();
-      treeHost.focus();
-      start?.scrollIntoView({ block: "nearest" });
-    },
-    hasListFocus() {
-      return treeHost.contains(document.activeElement);
-    },
-    dispose() {
-      clearInterval(clock);
-      status?.dispose();
-      // An unfinished rename would otherwise leave every later sidebar
-      // refusing to refresh.
-      renamingId = null;
-      document.removeEventListener("catalog-rerender", rerenderHandler);
-      document.removeEventListener(KILL_SESSION_EVENT, killHandler);
-      document.removeEventListener(RENAME_SESSION_EVENT, renameHandler);
-      unsubscribe();
-    },
-  };
-}

web/src/catalogPatch.test.ts

@@ -1,105 +0,0 @@
-// @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/commandBar.test.ts

@@ -1,723 +0,0 @@
-// @vitest-environment happy-dom
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import {
-  KILL_SESSION_EVENT,
-  RENAME_SESSION_EVENT,
-  SESSION_SELECT_EVENT,
-  SPAWN_SIMILAR_EVENT,
-} from "./catalog.js";
-import {
-  barGroups,
-  barRows,
-  closeCommandBar,
-  commandBarCandidates,
-  dedupeCommands,
-  directoryBarCandidates,
-  directoryCandidate,
-  isCommandBarOpen,
-  openCommandBar,
-  orderSessionsForBar,
-  parseBarQuery,
-  sessionBarCandidates,
-  sessionActionCandidates,
-  sessionCandidate,
-  SPAWN_DIRECTORY_EVENT,
-} from "./commandBar.js";
-import { COMMAND_SPECS, type Command } from "./commands.js";
-import type { Session } from "./types.js";
-
-function session(id: string, over: Partial<Session> = {}): Session {
-  return {
-    id,
-    cwd: "/home/me/dev/api",
-    command: "bash",
-    env: {},
-    metadata: { name: id },
-    status: "Running",
-    created_at: "2026-01-01T00:00:00Z",
-    ...over,
-  };
-}
-
-afterEach(() => {
-  closeCommandBar();
-  document.body.replaceChildren();
-});
-
-function press(key: string, init: KeyboardEventInit = {}): void {
-  const input = document.querySelector(".cmdbar-input") as HTMLInputElement;
-  input.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, ...init }));
-}
-
-function type(value: string): void {
-  const input = document.querySelector(".cmdbar-input") as HTMLInputElement;
-  input.value = value;
-  input.dispatchEvent(new Event("input", { bubbles: true }));
-}
-
-function rowNames(): string[] {
-  return [...document.querySelectorAll(".cmdbar-row-name")].map((r) => r.textContent ?? "");
-}
-
-function activeName(): string | undefined {
-  return document.querySelector(".cmdbar-row.is-active .cmdbar-row-name")?.textContent ?? undefined;
-}
-
-describe("empty-query ordering", () => {
-  it("sorts most recently focused first", () => {
-    const older = session("older", { last_focused_at: "2026-01-01T10:00:00Z" });
-    const newer = session("newer", { last_focused_at: "2026-01-01T11:00:00Z" });
-    expect(orderSessionsForBar([older, newer]).map((s) => s.id)).toEqual(["newer", "older"]);
-  });
-
-  it("sorts a never-focused session after every focused one, newest created first", () => {
-    const focused = session("focused", {
-      last_focused_at: "2020-01-01T00:00:00Z",
-      created_at: "2020-01-01T00:00:00Z",
-    });
-    const oldFresh = session("old-fresh", { created_at: "2026-01-01T00:00:00Z" });
-    const newFresh = session("new-fresh", { created_at: "2026-06-01T00:00:00Z" });
-    expect(orderSessionsForBar([oldFresh, newFresh, focused]).map((s) => s.id)).toEqual([
-      "focused",
-      "new-fresh",
-      "old-fresh",
-    ]);
-  });
-
-  it("sorts dead sessions after live ones regardless of recency", () => {
-    const deadRecent = session("dead", {
-      status: "Dead",
-      last_focused_at: "2026-06-01T00:00:00Z",
-    });
-    const liveStale = session("live", { last_focused_at: "2020-01-01T00:00:00Z" });
-    const liveNever = session("never");
-    expect(orderSessionsForBar([deadRecent, liveNever, liveStale]).map((s) => s.id)).toEqual([
-      "live",
-      "never",
-      "dead",
-    ]);
-  });
-
-  it("treats a null last_focused_at as never focused", () => {
-    const nulled = session("nulled", { last_focused_at: null });
-    const stamped = session("stamped", { last_focused_at: "2020-01-01T00:00:00Z" });
-    expect(orderSessionsForBar([nulled, stamped]).map((s) => s.id)).toEqual(["stamped", "nulled"]);
-  });
-});
-
-describe("session candidates", () => {
-  it("carries the candidate table's fields, with the directory abbreviated", () => {
-    const s = session("api", {
-      metadata: { name: "api" },
-      command: "claude --resume",
-      current_cwd: "/home/me/dev/api",
-    });
-    expect(sessionCandidate(s, "/home/me")).toEqual({
-      kind: "session",
-      session: s,
-      fields: {
-        name: "api",
-        directory: "~/dev/api",
-        command: "claude --resume",
-        tool: "claude",
-      },
-    });
-  });
-
-  it("leaves the tool out when the program has no mark, and groups a worktree by its repo", () => {
-    const s = session("edit", {
-      metadata: {},
-      command: "hx src/",
-      worktree: { path: "/home/me/dev/api/wt/x", base_repo: "/home/me/dev/api" },
-    });
-    const candidate = sessionCandidate(s, "/home/me");
-    expect(candidate.fields.tool).toBeUndefined();
-    expect(candidate.fields.directory).toBe("~/dev/api");
-    // No `metadata.name`: the sidebar's fallback is the command line.
-    expect(candidate.fields.name).toBe("hx src/");
-  });
-
-  it("builds candidates in the empty-query order", () => {
-    const a = session("a", { last_focused_at: "2026-01-01T10:00:00Z" });
-    const b = session("b", { last_focused_at: "2026-01-01T11:00:00Z" });
-    expect(sessionBarCandidates([a, b]).map((c) => c.session.id)).toEqual(["b", "a"]);
-  });
-});
-
-describe("rows and grouping", () => {
-  it("an empty query keeps every session in input order", () => {
-    const candidates = sessionBarCandidates([session("a"), session("b")]);
-    expect(barRows("", candidates).map((r) => r.candidate.session.id)).toEqual(["a", "b"]);
-  });
-
-  it("groups by kind without reordering the ranking", () => {
-    const candidates = sessionBarCandidates([
-      session("worker", { metadata: { name: "worker" }, current_cwd: "/home/me/dev/api" }),
-      session("api", { metadata: { name: "api" }, current_cwd: "/home/me/dev/web" }),
-    ]);
-    const rows = barRows("api", candidates);
-    const groups = barGroups(rows);
-    expect(groups).toHaveLength(1);
-    expect(groups[0].title).toBe("Sessions");
-    expect(groups[0].results.map((r) => r.candidate.session.id)).toEqual(
-      rows.map((r) => r.candidate.session.id),
-    );
-    // F6: the name beats the directory, and the directory match highlights
-    // inside the directory.
-    expect(groups[0].results[0].candidate.session.id).toBe("api");
-    expect(groups[0].results[1].field).toBe("directory");
-  });
-});
-
-describe("the overlay", () => {
-  const sessions = [
-    session("api", {
-      metadata: { name: "api" },
-      current_cwd: "/home/me/dev/api",
-      last_focused_at: "2026-01-01T11:00:00Z",
-    }),
-    session("worker", {
-      metadata: { name: "worker" },
-      current_cwd: "/home/me/dev/worker",
-      last_focused_at: "2026-01-01T10:00:00Z",
-    }),
-    session("notes", { metadata: { name: "notes" }, current_cwd: "/home/me/notes" }),
-  ];
-
-  // Sessions only: the mixed list's command half is the sigil describe's
-  // business, and the registry is whatever another test file happened to bind.
-  function open(over: Parameters<typeof openCommandBar>[0] | null = null) {
-    return openCommandBar(
-      over ?? { sessions, homeDir: "/home/me", commands: [], onOpenSession: () => {} },
-    );
-  }
-
-  it("is a registry command, so the help overlay lists it", () => {
-    const spec = COMMAND_SPECS.find((s) => s.id === "bar.open");
-    expect(spec?.keys).toEqual(["ctrl-k"]);
-    expect(spec?.scope).toBe("global");
-  });
-
-  it("lists sessions by recency under a kind header on an empty query", () => {
-    open();
-    expect([...document.querySelectorAll(".cmdbar-group-title")].map((h) => h.textContent)).toEqual([
-      "Sessions",
-    ]);
-    expect(rowNames()).toEqual(["api", "worker", "notes"]);
-    expect(activeName()).toBe("api");
-  });
-
-  it("opening twice leaves one overlay", () => {
-    open();
-    open();
-    expect(document.querySelectorAll(".cmdbar-overlay")).toHaveLength(1);
-    expect(isCommandBarOpen()).toBe(true);
-  });
-
-  it("ranks a typed query through the matcher and highlights the matched range", () => {
-    open();
-    type("wor");
-    expect(rowNames()).toEqual(["worker"]);
-    const marks = [...document.querySelectorAll(".cmdbar-row-name mark")].map((m) => m.textContent);
-    expect(marks).toEqual(["wor"]);
-  });
-
-  it("highlights inside the directory when that is the field that matched", () => {
-    open();
-    type("notes");
-    const row = document.querySelector(".cmdbar-row") as HTMLElement;
-    expect(row.dataset.sessionId).toBe("notes");
-    type("dev/wor");
-    expect(rowNames()).toEqual(["worker"]);
-    expect(
-      [...document.querySelectorAll(".cmdbar-row-meta mark")].map((m) => m.textContent).join(""),
-    ).toBe("dev/wor");
-  });
-
-  it("renders a no-results state rather than an empty list", () => {
-    open();
-    type("zzz");
-    expect(rowNames()).toEqual([]);
-    expect(document.querySelector(".cmdbar-empty")?.textContent).toBe("No matches");
-  });
-
-  it("moves the highlight with the arrows and ctrl-p/ctrl-n, without wrapping", () => {
-    open();
-    press("ArrowUp");
-    expect(activeName()).toBe("api");
-    press("ArrowDown");
-    expect(activeName()).toBe("worker");
-    press("n", { ctrlKey: true });
-    expect(activeName()).toBe("notes");
-    press("ArrowDown");
-    expect(activeName()).toBe("notes");
-    press("p", { ctrlKey: true });
-    expect(activeName()).toBe("worker");
-  });
-
-  it("puts the highlight back on the best row whenever the query changes", () => {
-    open();
-    press("ArrowDown");
-    expect(activeName()).toBe("worker");
-    type("o");
-    expect(activeName()).toBe(document.querySelector(".cmdbar-row-name")?.textContent);
-  });
-
-  it("opens the highlighted session through the shared open path on Enter", () => {
-    const seen: string[] = [];
-    const listener = (e: Event) => seen.push((e as CustomEvent<string>).detail);
-    document.addEventListener(SESSION_SELECT_EVENT, listener);
-    openCommandBar({ sessions, homeDir: "/home/me", commands: [] });
-    press("ArrowDown");
-    press("Enter");
-    document.removeEventListener(SESSION_SELECT_EVENT, listener);
-    expect(seen).toEqual(["worker"]);
-    expect(isCommandBarOpen()).toBe(false);
-  });
-
-  it("Enter on an empty result list does nothing", () => {
-    const onOpenSession = vi.fn();
-    open({ sessions, homeDir: "/home/me", commands: [], onOpenSession });
-    type("zzz");
-    press("Enter");
-    expect(onOpenSession).not.toHaveBeenCalled();
-    expect(isCommandBarOpen()).toBe(true);
-  });
-
-  it("closes on Escape and on a press outside the panel", () => {
-    open();
-    press("Escape");
-    expect(isCommandBarOpen()).toBe(false);
-
-    open();
-    (document.querySelector(".cmdbar-overlay") as HTMLElement).dispatchEvent(
-      new MouseEvent("mousedown", { bubbles: true }),
-    );
-    expect(isCommandBarOpen()).toBe(false);
-  });
-
-  it("stays open for a press inside the panel", () => {
-    open();
-    (document.querySelector(".cmdbar-panel") as HTMLElement).dispatchEvent(
-      new MouseEvent("mousedown", { bubbles: true }),
-    );
-    expect(isCommandBarOpen()).toBe(true);
-  });
-
-  it("returns the keyboard to whatever held it when it opened", () => {
-    const before = document.createElement("button");
-    document.body.appendChild(before);
-    before.focus();
-    open();
-    expect(document.activeElement).toBe(document.querySelector(".cmdbar-input"));
-    press("Escape");
-    expect(document.activeElement).toBe(before);
-  });
-
-  it("clicking a row opens that session", () => {
-    const onOpenSession = vi.fn();
-    open({ sessions, homeDir: "/home/me", commands: [], onOpenSession });
-    (document.querySelectorAll(".cmdbar-row")[1] as HTMLElement).click();
-    expect(onOpenSession).toHaveBeenCalledWith("worker");
-    expect(isCommandBarOpen()).toBe(false);
-  });
-});
-
-// ---- the sigils (#150) ----
-
-function command(id: string, label: string, keys: string[], run = () => {}): Command {
-  return { id, label, group: "Test", keys, scope: "global", run };
-}
-
-const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
-
-function rowKeys(): string[][] {
-  return [...document.querySelectorAll(".cmdbar-row-keys")].map((el) =>
-    [...el.querySelectorAll("kbd")].map((k) => k.textContent ?? ""),
-  );
-}
-
-describe("parsing the query line", () => {
-  it("reads a sigil only in first position", () => {
-    expect(parseBarQuery(">kill")).toEqual({ sigil: ">", query: "kill" });
-    expect(parseBarQuery("~/dev")).toEqual({ sigil: "~", query: "/dev" });
-    expect(parseBarQuery("")).toEqual({ sigil: null, query: "" });
-    expect(parseBarQuery("api")).toEqual({ sigil: null, query: "api" });
-  });
-
-  it("leaves a sigil character elsewhere in the query literal", () => {
-    expect(parseBarQuery("api>x")).toEqual({ sigil: null, query: "api>x" });
-    // The case that matters: the second `~` of a directory query reaches the
-    // matcher.
-    expect(parseBarQuery("~~/dev")).toEqual({ sigil: "~", query: "~/dev" });
-  });
-
-  it("returns to the mixed list when the sigil is backspaced away", () => {
-    expect(parseBarQuery(">").sigil).toBe(">");
-    expect(parseBarQuery("").sigil).toBeNull();
-  });
-});
-
-describe("command candidates", () => {
-  it("dedupes by action, not by chord", () => {
-    const run = () => {};
-    const kill = command("a.kill", "Kill the session", ["x"], run);
-    const alias = command("b.kill", "Kill the session", ["ctrl-x"], run);
-    const other = command("c.rename", "Rename the session", ["r"]);
-    expect(dedupeCommands([kill, alias, other]).map((c) => c.id)).toEqual(["a.kill", "c.rename"]);
-  });
-
-  it("matches on the label only, and keeps the chord for display", () => {
-    const candidates = commandBarCandidates([command("a", "Open the spawn form", ["ctrl-k"])]);
-    expect(candidates[0].fields).toEqual({ label: "Open the spawn form" });
-    expect(candidates[0].command.keys).toEqual(["ctrl-k"]);
-  });
-});
-
-describe("directory candidates", () => {
-  it("abbreviates the path it shows and keeps the one it spawns in", () => {
-    const c = directoryCandidate("/home/me/dev/api", "/home/me");
-    expect(c).toEqual({ kind: "directory", path: "/home/me/dev/api", fields: { path: "~/dev/api" } });
-  });
-
-  it("expands a typed `~` and dedupes by the directory spawned in", () => {
-    const paths = ["~/dev/api", "/home/me/dev/api", "/tmp/scratch"];
-    expect(directoryBarCandidates(paths, "/home/me").map((c) => c.path)).toEqual([
-      "/home/me/dev/api",
-      "/tmp/scratch",
-    ]);
-  });
-});
-
-describe("the sigils in the overlay", () => {
-  const sessions = [session("api", { metadata: { name: "api" }, current_cwd: "/home/me/dev/api" })];
-  const ran: string[] = [];
-  const commands = [
-    command("spawn.open", "Open the spawn form", ["n"], () => ran.push("spawn.open")),
-    command("list.kill", "Kill the highlighted session", ["x"], () => ran.push("list.kill")),
-  ];
-
-  afterEach(() => {
-    ran.length = 0;
-  });
-
-  function open(over: Partial<Parameters<typeof openCommandBar>[0]> = {}) {
-    return openCommandBar({
-      sessions,
-      homeDir: "/home/me",
-      commands,
-      onOpenSession: () => {},
-      loadDirectories: async () => [],
-      listDirEntries: async () => [],
-      onSpawnDirectory: () => {},
-      ...over,
-    });
-  }
-
-  it("lists every command in registry order under `>`, with its chord and no header", () => {
-    open();
-    type(">");
-    expect(rowNames()).toEqual(["Open the spawn form", "Kill the highlighted session"]);
-    expect(rowKeys()).toEqual([["n"], ["x"]]);
-    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
-  });
-
-  it("matches a command on its label and never on its chord", () => {
-    open();
-    type(">kill");
-    expect(rowNames()).toEqual(["Kill the highlighted session"]);
-    // `n` and `x` are chords, not label text: querying one finds nothing that
-    // the label does not also justify.
-    type(">ctrlx");
-    expect(rowNames()).toEqual([]);
-  });
-
-  it("runs the highlighted command on Enter", () => {
-    open();
-    type(">kill");
-    press("Enter");
-    expect(ran).toEqual(["list.kill"]);
-    expect(isCommandBarOpen()).toBe(false);
-  });
-
-  it("keeps the list mixed with no sigil, and returns to it when the sigil goes", () => {
-    open();
-    type("s");
-    expect([...document.querySelectorAll(".cmdbar-group-title")].map((h) => h.textContent)).toEqual([
-      "Sessions",
-      "Commands",
-    ]);
-    type(">spawn");
-    expect(rowNames()).toEqual(["Open the spawn form"]);
-    // Backspacing the sigil away is ordinary editing.
-    type("spawn");
-    expect(rowNames()).toContain("Open the spawn form");
-    type("");
-    expect(rowNames()).toEqual(["api"]);
-  });
-
-  it("lists recent dirs then projects under `~`", async () => {
-    open({ loadDirectories: async () => ["/home/me/dev/api", "/srv/www"] });
-    type("~");
-    await flush();
-    expect(rowNames()).toEqual(["~/dev/api", "/srv/www"]);
-    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
-  });
-
-  it("fills the list in from /api/dirs as a path is typed", async () => {
-    const asked: string[] = [];
-    open({
-      loadDirectories: async () => ["/home/me/notes"],
-      listDirEntries: async (dir) => {
-        asked.push(dir);
-        return ["maestro", "api"];
-      },
-    });
-    // The second `~` is a literal query character and reaches the matcher.
-    type("~~/dev/mae");
-    await flush();
-    expect(asked).toEqual(["~/dev/"]);
-    expect(rowNames()).toEqual(["~/dev/maestro"]);
-  });
-
-  it("spawns in the highlighted directory on Enter", async () => {
-    const spawned: string[] = [];
-    open({
-      loadDirectories: async () => ["~/dev/api"],
-      onSpawnDirectory: (path) => spawned.push(path),
-    });
-    type("~api");
-    await flush();
-    press("Enter");
-    expect(spawned).toEqual(["/home/me/dev/api"]);
-    expect(isCommandBarOpen()).toBe(false);
-  });
-
-  it("raises the spawn event when the caller supplies no handler", async () => {
-    const seen: string[] = [];
-    const listener = (e: Event) => seen.push((e as CustomEvent<string>).detail);
-    document.addEventListener(SPAWN_DIRECTORY_EVENT, listener);
-    openCommandBar({
-      sessions,
-      homeDir: "/home/me",
-      commands,
-      onOpenSession: () => {},
-      loadDirectories: async () => ["/home/me/dev/api"],
-      listDirEntries: async () => [],
-    });
-    type("~");
-    await flush();
-    press("Enter");
-    document.removeEventListener(SPAWN_DIRECTORY_EVENT, listener);
-    expect(seen).toEqual(["/home/me/dev/api"]);
-  });
-});
-
-describe("the focus round-trip over a pane (#152)", () => {
-  function terminalTextarea(): HTMLTextAreaElement {
-    const ta = document.createElement("textarea");
-    ta.className = "xterm-helper-textarea";
-    document.body.appendChild(ta);
-    return ta;
-  }
-
-  it("hands the keyboard back to the terminal that had it", () => {
-    const ta = terminalTextarea();
-    ta.focus();
-    openCommandBar({ sessions: [], commands: [] });
-    expect(document.activeElement).toBe(document.querySelector(".cmdbar-input"));
-    press("Escape");
-    expect(document.activeElement).toBe(ta);
-  });
-
-  it("reports no focus change to the daemon, opening or closing", () => {
-    const fetchMock = vi.fn(() => Promise.resolve(new Response(null, { status: 204 })));
-    vi.stubGlobal("fetch", fetchMock);
-    try {
-      const ta = terminalTextarea();
-      ta.focus();
-      openCommandBar({ sessions: [], commands: [] });
-      press("Escape");
-      const focusCalls = fetchMock.mock.calls.filter(([url]: unknown[]) =>
-        String(url).includes("/focus"),
-      );
-      expect(focusCalls).toEqual([]);
-    } finally {
-      vi.unstubAllGlobals();
-    }
-  });
-});
-
-describe("the session action page (#151)", () => {
-  const sessions = [
-    session("api", {
-      metadata: { name: "api" },
-      current_cwd: "/home/me/dev/api",
-      last_focused_at: "2026-01-01T11:00:00Z",
-    }),
-    session("worker", {
-      metadata: { name: "worker" },
-      current_cwd: "/home/me/dev/worker",
-      last_focused_at: "2026-01-01T10:00:00Z",
-    }),
-  ];
-
-  function open(over: Partial<Parameters<typeof openCommandBar>[0]> = {}) {
-    return openCommandBar({
-      sessions,
-      homeDir: "/home/me",
-      commands: [],
-      onOpenSession: () => {},
-      ...over,
-    });
-  }
-
-  function headerText(): string | undefined {
-    return document.querySelector(".cmdbar-page-header")?.textContent ?? undefined;
-  }
-
-  it("lists kill, rename and spawn similar for the highlighted session", () => {
-    open();
-    press("Tab");
-    expect(rowNames()).toEqual(["Kill session", "Rename session", "Spawn similar"]);
-    expect(activeName()).toBe("Kill session");
-  });
-
-  it("names the session being acted on", () => {
-    open();
-    press("ArrowDown");
-    press("Tab");
-    expect(headerText()).toContain("worker");
-  });
-
-  it("drops the kind headers, since the page is one kind", () => {
-    open();
-    press("Tab");
-    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
-  });
-
-  it("stays fuzzy-searchable over the three actions", () => {
-    open();
-    press("Tab");
-    type("ren");
-    expect(rowNames()).toEqual(["Rename session"]);
-    type("spwn");
-    expect(rowNames()).toEqual(["Spawn similar"]);
-    type("zzz");
-    expect(document.querySelector(".cmdbar-empty")?.textContent).toBe("No matches");
-  });
-
-  it("does nothing on a command row", () => {
-    openCommandBar({
-      sessions,
-      homeDir: "/home/me",
-      commands: [{ ...COMMAND_SPECS[0], run: () => {} } as Command],
-      onOpenSession: () => {},
-    });
-    type(">");
-    const before = rowNames();
-    press("Tab");
-    expect(rowNames()).toEqual(before);
-    expect(headerText()).toBeUndefined();
-  });
-
-  it("does nothing on a directory row", async () => {
-    open({ loadDirectories: () => Promise.resolve(["/home/me/dev/api"]) });
-    type("~");
-    await Promise.resolve();
-    press("Tab");
-    expect(rowNames()).toEqual(["~/dev/api"]);
-    expect(headerText()).toBeUndefined();
-  });
-
-  it("returns to the result list on Escape, with the previous query intact", () => {
-    open();
-    type("wor");
-    press("Tab");
-    expect(headerText()).toContain("worker");
-    press("Escape");
-    expect(isCommandBarOpen()).toBe(true);
-    expect(headerText()).toBeUndefined();
-    expect((document.querySelector(".cmdbar-input") as HTMLInputElement).value).toBe("wor");
-    expect(rowNames()).toEqual(["worker"]);
-  });
-
-  it("returns to the result list on backspace at an empty query", () => {
-    open();
-    type("wor");
-    press("Tab");
-    type("");
-    press("Backspace");
-    expect(headerText()).toBeUndefined();
-    expect((document.querySelector(".cmdbar-input") as HTMLInputElement).value).toBe("wor");
-    expect(rowNames()).toEqual(["worker"]);
-  });
-
-  it("keeps backspace ordinary while the page's query has text", () => {
-    open();
-    press("Tab");
-    type("ren");
-    press("Backspace");
-    expect(headerText()).toContain("api");
-    expect(rowNames()).toEqual(["Rename session"]);
-  });
-
-  it("closes the bar when the page's Escape has already been used", () => {
-    open();
-    press("Tab");
-    press("Escape");
-    press("Escape");
-    expect(isCommandBarOpen()).toBe(false);
-  });
-
-  it("raises kill, rename and spawn similar with the session, closing the bar", () => {
-    const seen: string[] = [];
-    for (const [hook, key] of [
-      ["onKillSession", "Kill session"],
-      ["onRenameSession", "Rename session"],
-      ["onSpawnSimilar", "Spawn similar"],
-    ] as const) {
-      open({ [hook]: (s: Session) => seen.push(`${hook}:${s.id}`) });
-      type("wor");
-      press("Tab");
-      type(key);
-      press("Enter");
-      expect(isCommandBarOpen()).toBe(false);
-    }
-    expect(seen).toEqual([
-      "onKillSession:worker",
-      "onRenameSession:worker",
-      "onSpawnSimilar:worker",
-    ]);
-  });
-
-  it("hands each action to the flow it already has, by default", () => {
-    const seen: string[] = [];
-    const listeners: Array<[string, EventListener]> = [
-      [KILL_SESSION_EVENT, (e) => seen.push(`kill:${(e as CustomEvent<Session>).detail.id}`)],
-      [RENAME_SESSION_EVENT, (e) => seen.push(`rename:${(e as CustomEvent<Session>).detail.id}`)],
-      [SPAWN_SIMILAR_EVENT, (e) => seen.push(`similar:${(e as CustomEvent<Session>).detail.id}`)],
-    ];
-    for (const [name, fn] of listeners) document.addEventListener(name, fn);
-    try {
-      for (const action of ["Kill session", "Rename session", "Spawn similar"]) {
-        open();
-        press("Tab");
-        type(action);
-        press("Enter");
-      }
-    } finally {
-      for (const [name, fn] of listeners) document.removeEventListener(name, fn);
-    }
-    expect(seen).toEqual(["kill:api", "rename:api", "similar:api"]);
-  });
-
-  it("offers no action beyond the three", () => {
-    expect(sessionActionCandidates().map((c) => c.action.id)).toEqual([
-      "kill",
-      "rename",
-      "spawn-similar",
-    ]);
-  });
-});

web/src/commandBar.ts

@@ -1,809 +0,0 @@
-// The `ctrl-k` command bar (docs/COMMAND-BAR.md): a query line over a result
-// list, opened from the sidebar, closed with Escape.
-//
-// Three kinds live here: sessions and commands, ranked together by default,
-// and directories, which need the `~` sigil. `tab` on a session drills into
-// its action page (#151), which is the same overlay over three actions.
-
-import { listDir, projects as fetchProjects, recentDirs } from "./api.js";
-import {
-  KILL_SESSION_EVENT,
-  RENAME_SESSION_EVENT,
-  SESSION_SELECT_EVENT,
-  SPAWN_SIMILAR_EVENT,
-} from "./catalog.js";
-import { keyCaps, publishedCommands, type Command } from "./commands.js";
-import {
-  matchAndRank,
-  type CandidateKind,
-  type CommandCandidate,
-  type DirectoryCandidate,
-  type MatchRange,
-  type MatchResult,
-  type SessionCandidate,
-} from "./matcher.js";
-import { splitPath } from "./paths.js";
-import { splitCommand } from "./toolIcon.js";
-import { abbreviateCwd, sessionName, sessionTreePath, type Session } from "./types.js";
-
-/** A matcher candidate that remembers what it came from, so a result can be
- *  acted on without a second lookup. The extra property is invisible to the
- *  matcher, which only ever reads `kind` and `fields`. */
-export type SessionBarCandidate = SessionCandidate & { session: Session };
-export type CommandBarCandidate = CommandCandidate & { command: Command };
-/** `fields.path` is the abbreviated path the operator reads and the matcher
- *  ranks; `path` is the one a spawn is made in. */
-export type DirectoryBarCandidate = DirectoryCandidate & { path: string };
-
-/** One row of a session's action page. It is a `command` to the matcher — a
- *  single `label` field, ranked exactly like a registry command — and carries
- *  the action it stands for instead of a registry entry. */
-export type ActionBarCandidate = CommandCandidate & { action: SessionAction };
-
-export type BarCandidate =
-  SessionBarCandidate | CommandBarCandidate | ActionBarCandidate | DirectoryBarCandidate;
-export type BarResult = MatchResult<BarCandidate>;
-
-/** Raised when Enter lands on a directory row. The bar picks the directory; the
- *  shell owns the spawn, which is the same fast-forward path `N` takes. */
-export const SPAWN_DIRECTORY_EVENT = "cmdbar-spawn-directory";
-
-/** One kind's slice of the ranked list, in rank order. */
-export interface BarGroup<C extends BarCandidate = BarCandidate> {
-  kind: CandidateKind;
-  title: string;
-  results: MatchResult<C>[];
-}
-
-const KIND_TITLES: Record<CandidateKind, string> = {
-  session: "Sessions",
-  command: "Commands",
-  directory: "Directories",
-};
-
-// ---- the sigils ----
-
-export type BarSigil = ">" | "~";
-
-export interface BarQuery {
-  /** The sigil in force, or null for the mixed list. */
-  sigil: BarSigil | null;
-  /** What the matcher sees: everything after a sigil, or the whole query. */
-  query: string;
-}
-
-/** Split a raw query line into its sigil and the query proper.
- *
- *  A sigil is only a sigil in first position: `>` or `~` anywhere else is a
- *  literal query character, which is what a directory query with a second `~`
- *  in it depends on. Backspacing past a sigil needs no special case either —
- *  the first character goes and the query is a mixed one again. */
-export function parseBarQuery(raw: string): BarQuery {
-  const first = raw[0];
-  if (first === ">" || first === "~") return { sigil: first, query: raw.slice(1) };
-  return { sigil: null, query: raw };
-}
-
-// ---- the session action page ----
-
-/** The actions a session's action page offers, and no others: the bar picks
- *  one and hands off to the flow that already implements it
- *  (docs/COMMAND-BAR.md, "Drill-in"). */
-export type SessionActionId = "kill" | "rename" | "spawn-similar";
-
-export interface SessionAction {
-  id: SessionActionId;
-  label: string;
-}
-
-export const SESSION_ACTIONS: readonly SessionAction[] = [
-  { id: "kill", label: "Kill session" },
-  { id: "rename", label: "Rename session" },
-  { id: "spawn-similar", label: "Spawn similar" },
-];
-
-/** The action page's candidates, in the order above — which is the order an
- *  empty query lists them in, since the matcher keeps input order. */
-export function sessionActionCandidates(): ActionBarCandidate[] {
-  return SESSION_ACTIONS.map((action) => ({
-    kind: "command",
-    action,
-    fields: { label: action.label },
-  }));
-}
-
-/** Narrow a `command` candidate to an action row. Both share the matcher's
- *  `command` kind, so what separates them is what they carry. */
-export function isActionCandidate(candidate: BarCandidate): candidate is ActionBarCandidate {
-  return candidate.kind === "command" && "action" in candidate;
-}
-
-// ---- candidates ----
-
-function focusedAt(s: Session): number | null {
-  const stamp = s.last_focused_at;
-  if (typeof stamp !== "string" || stamp === "") return null;
-  const ms = Date.parse(stamp);
-  return Number.isNaN(ms) ? null : ms;
-}
-
-function createdAt(s: Session): number {
-  const ms = Date.parse(s.created_at ?? "");
-  return Number.isNaN(ms) ? 0 : ms;
-}
-
-/** The empty-query order (docs/COMMAND-BAR.md, "Empty query"): most recently
- *  focused first; a session that has never been focused sorts after every
- *  session that has, most recently created first among those; and a dead
- *  session sorts after every live one regardless of recency, because a session
- *  you cannot attach to is not where you just were.
- *
- *  This is also the input order for a non-empty query, which is what the
- *  matcher's last tie-break preserves. */
-export function orderSessionsForBar(sessions: readonly Session[]): Session[] {
-  return [...sessions].sort((a, b) => {
-    const deadA = a.status === "Dead" ? 1 : 0;
-    const deadB = b.status === "Dead" ? 1 : 0;
-    if (deadA !== deadB) return deadA - deadB;
-
-    const focusA = focusedAt(a);
-    const focusB = focusedAt(b);
-    if ((focusA === null) !== (focusB === null)) return focusA === null ? 1 : -1;
-    if (focusA !== null && focusB !== null && focusA !== focusB) return focusB - focusA;
-
-    return createdAt(b) - createdAt(a);
-  });
-}
-
-/** Build one session's candidate: the fields docs/COMMAND-BAR.md's candidate
- *  table names, with the directory abbreviated the way the sidebar shows it. */
-export function sessionCandidate(s: Session, homeDir?: string): SessionBarCandidate {
-  const treePath = sessionTreePath(s);
-  const directory = treePath ? abbreviateCwd(treePath, homeDir) : undefined;
-  const tool = splitCommand(s.command).tool ?? undefined;
-  return {
-    kind: "session",
-    session: s,
-    fields: {
-      name: sessionName(s),
-      ...(directory ? { directory } : {}),
-      ...(s.command ? { command: s.command } : {}),
-      ...(tool ? { tool } : {}),
-    },
-  };
-}
-
-/** Every session as a candidate, in the empty-query order. */
-export function sessionBarCandidates(
-  sessions: readonly Session[],
-  homeDir?: string,
-): SessionBarCandidate[] {
-  return orderSessionsForBar(sessions).map((s) => sessionCandidate(s, homeDir));
-}
-
-/** Drop the commands that would list twice. Several chords can be bound to one
- *  action — the registry already carries its aliases on one entry, but nothing
- *  stops two entries running the same handler, and listed naively that is two
- *  identical rows. The dedupe is by **action**, never by chord: the chord is
- *  displayed, so a command with two of them is still one row. */
-export function dedupeCommands(commands: readonly Command[]): Command[] {
-  const seenRun = new Set<Command["run"]>();
-  const seenLabel = new Set<string>();
-  const kept: Command[] = [];
-  for (const command of commands) {
-    if (seenRun.has(command.run) || seenLabel.has(command.label)) continue;
-    seenRun.add(command.run);
-    seenLabel.add(command.label);
-    kept.push(command);
-  }
-  return kept;
-}
-
-/** Every bound command as a candidate, in registry order. Only the label is a
- *  field: the chord is displayed beside the row, never matched, because
- *  matching it would make `>` results depend on a user's rebinds. */
-export function commandBarCandidates(commands: readonly Command[]): CommandBarCandidate[] {
-  return dedupeCommands(commands).map((command) => ({
-    kind: "command",
-    command,
-    fields: { label: command.label },
-  }));
-}
-
-/** `~/dev/api` back to `/home/me/dev/api` — the inverse of `abbreviateCwd`, for
- *  a path the operator typed or `/api/dirs` completed. */
-export function expandHome(path: string, homeDir?: string): string {
-  if (!homeDir) return path;
-  if (path === "~") return homeDir;
-  return path.startsWith("~/") ? `${homeDir}${path.slice(1)}` : path;
-}
-
-export function directoryCandidate(path: string, homeDir?: string): DirectoryBarCandidate {
-  const absolute = expandHome(path, homeDir);
-  return { kind: "directory", path: absolute, fields: { path: abbreviateCwd(absolute, homeDir) } };
-}
-
-/** Candidates for `~`, deduped by the directory they spawn in and keeping the
- *  first mention of each — recent dirs (newest first) ahead of the project
- *  list, which is the empty-query order the contract asks for. */
-export function directoryBarCandidates(
-  paths: readonly string[],
-  homeDir?: string,
-): DirectoryBarCandidate[] {
-  const seen = new Set<string>();
-  const out: DirectoryBarCandidate[] = [];
-  for (const path of paths) {
-    if (path === "") continue;
-    const candidate = directoryCandidate(path, homeDir);
-    if (seen.has(candidate.path)) continue;
-    seen.add(candidate.path);
-    out.push(candidate);
-  }
-  return out;
-}
-
-/** The directory list the bar starts from: what the spawn form already knows —
- *  `GET /api/recent-dirs` and the project list — either alone if the other
- *  fails. */
-export async function loadBarDirectories(): Promise<string[]> {
-  const [recents, discovered] = await Promise.all([
-    recentDirs()
-      .then((r) => r.dirs.map((d) => d.cwd))
-      .catch(() => [] as string[]),
-    fetchProjects()
-      .then((list) => list.map((p) => p.path))
-      .catch(() => [] as string[]),
-  ]);
-  return [...recents, ...discovered];
-}
-
-// ---- grouping ----
-
-/** Bucket a ranked list by kind for rendering. Grouping is a rendering of the
- *  ranking, never a reordering of it: a group holds its matches in rank order,
- *  and groups appear in the order their best-scoring member does — so the first
- *  row under the first header is the globally best result. */
-export function barGroups<C extends BarCandidate>(
-  results: readonly MatchResult<C>[],
-): BarGroup<C>[] {
-  const groups: BarGroup<C>[] = [];
-  for (const result of results) {
-    const kind = result.candidate.kind;
-    let group = groups.find((g) => g.kind === kind);
-    if (!group) {
-      group = { kind, title: KIND_TITLES[kind], results: [] };
-      groups.push(group);
-    }
-    group.results.push(result);
-  }
-  return groups;
-}
-
-/** The rows a query produces, flat and in rank order — what the highlight walks
- *  and what Enter acts on. Headers are labels, not rows, so they are never in
- *  this list. */
-export function barRows<C extends BarCandidate>(
-  query: string,
-  candidates: readonly C[],
-): MatchResult<C>[] {
-  return matchAndRank(query, candidates);
-}
-
-// ---- rendering ----
-
-/** Text with its matched ranges wrapped in `<mark>`. Ranges come from the
- *  matcher as `[start, end)` character pairs over the field that won. */
-export function renderHighlighted(text: string, ranges: readonly MatchRange[]): DocumentFragment {
-  const frag = document.createDocumentFragment();
-  let cursor = 0;
-  for (const [start, end] of ranges) {
-    if (start > cursor) frag.append(text.slice(cursor, start));
-    const mark = document.createElement("mark");
-    mark.className = "cmdbar-hit";
-    mark.textContent = text.slice(start, end);
-    frag.append(mark);
-    cursor = end;
-  }
-  if (cursor < text.length) frag.append(text.slice(cursor));
-  return frag;
-}
-
-/** The name line of a row: the session's name, the command's label, or the
- *  directory's path. */
-function rowName(candidate: BarCandidate): string {
-  switch (candidate.kind) {
-    case "session":
-      return candidate.fields.name;
-    case "command":
-      return candidate.fields.label;
-    case "directory":
-      return candidate.fields.path;
-  }
-}
-
-/** The secondary line under a session row: the field the match was found in
- *  when that was not the name, so a session found through its directory says
- *  so. Only sessions have one — a command shows keycaps instead, and a
- *  directory's path is already the name. */
-function metaText(result: BarResult): string | undefined {
-  if (result.candidate.kind !== "session") return undefined;
-  const fields = result.candidate.fields;
-  switch (result.field) {
-    case "directory":
-      return fields.directory;
-    case "command":
-      return fields.command;
-    case "tool":
-      return fields.tool;
-    default:
-      return fields.directory;
-  }
-}
-
-function renderRow(result: BarResult, index: number): HTMLElement {
-  const candidate = result.candidate;
-  const row = document.createElement("div");
-  row.className = "cmdbar-row";
-  row.setAttribute("role", "option");
-  row.id = `cmdbar-row-${index}`;
-  row.dataset.index = String(index);
-  row.dataset.kind = candidate.kind;
-  if (candidate.kind === "session") {
-    row.dataset.sessionId = candidate.session.id;
-    if (candidate.session.status === "Dead") row.classList.add("is-dead");
-  } else if (isActionCandidate(candidate)) {
-    row.dataset.actionId = candidate.action.id;
-  } else if (candidate.kind === "command") {
-    row.dataset.commandId = candidate.command.id;
-  } else {
-    row.dataset.path = candidate.path;
-  }
-
-  const name = document.createElement("span");
-  name.className = "cmdbar-row-name";
-  const nameText = rowName(candidate);
-  const nameMatched =
-    result.field === "name" || result.field === "label" || result.field === "path";
-  name.append(nameMatched ? renderHighlighted(nameText, result.ranges) : nameText);
-  row.appendChild(name);
-
-  // The chord is teaching material, not a match target: it is rendered from
-  // the live registry entry and never fed to the matcher.
-  if (candidate.kind === "command" && !isActionCandidate(candidate)) {
-    const keys = document.createElement("span");
-    keys.className = "cmdbar-row-keys";
-    for (const cap of keyCaps(candidate.command.keys[0])) {
-      const kbd = document.createElement("kbd");
-      kbd.textContent = cap;
-      keys.appendChild(kbd);
-    }
-    row.appendChild(keys);
-    return row;
-  }
-
-  const meta = metaText(result);
-  if (meta) {
-    const el = document.createElement("span");
-    el.className = "cmdbar-row-meta";
-    const highlighted = result.field !== undefined && result.field !== "name";
-    el.append(highlighted ? renderHighlighted(meta, result.ranges) : meta);
-    row.appendChild(el);
-  }
-  return row;
-}
-
-const PLACEHOLDERS: Record<"mixed" | BarSigil, string> = {
-  mixed: "Go to a session…",
-  ">": "Run a command…",
-  "~": "Spawn in a directory…",
-};
-
-// ---- the overlay ----
-
-export interface CommandBarOptions {
-  /** Sessions to build candidates from, as the store has them right now. */
-  sessions: readonly Session[];
-  /** The daemon's home dir, for the directory field's `~/…` abbreviation. */
-  homeDir?: string;
-  /** Open the highlighted session. Defaults to the shared open path — the
-   *  sidebar's click event — which is what the contract requires; tests pass
-   *  their own. */
-  onOpenSession?: (sessionId: string) => void;
-  /** The command registry to list under `>`. Defaults to every bound command,
-   *  in registry order. */
-  commands?: readonly Command[];
-  /** The directory list behind `~`, fetched once on first use. */
-  loadDirectories?: () => Promise<string[]>;
-  /** One directory's subdirectories, for filling the list in as a path is
-   *  typed. Defaults to `GET /api/dirs`. */
-  listDirEntries?: (dir: string) => Promise<string[]>;
-  /** Spawn a session in the highlighted directory. Defaults to raising
-   *  `SPAWN_DIRECTORY_EVENT`, which the shell turns into a fast-forward
-   *  spawn. */
-  onSpawnDirectory?: (path: string) => void;
-  /** The action page's three actions (#151). Each defaults to raising the
-   *  event the flow that already implements it listens on — the sidebar's
-   *  confirm-and-blockers kill, its inline rename prompt, the spawn form
-   *  seeded from the session. The bar picks the action and nothing more. */
-  onKillSession?: (session: Session) => void;
-  onRenameSession?: (session: Session) => void;
-  onSpawnSimilar?: (session: Session) => void;
-}
-
-interface OpenBar {
-  el: HTMLElement;
-  dispose: () => void;
-}
-
-let current: OpenBar | null = null;
-
-export function isCommandBarOpen(): boolean {
-  return current !== null;
-}
-
-export function closeCommandBar(): void {
-  current?.dispose();
-}
-
-/** Mount the bar. Opening while one is up replaces it, so a stray second call
- *  can never stack two overlays. */
-export function openCommandBar(opts: CommandBarOptions): HTMLElement {
-  closeCommandBar();
-
-  // Closing returns the keyboard to whatever held it when the bar opened: a
-  // round trip through the bar never silently moves focus.
-  const previouslyFocused = document.activeElement as HTMLElement | null;
-  const openSession =
-    opts.onOpenSession ??
-    ((id: string) => document.dispatchEvent(new CustomEvent(SESSION_SELECT_EVENT, { detail: id })));
-  const spawnDirectory =
-    opts.onSpawnDirectory ??
-    ((path: string) =>
-      document.dispatchEvent(new CustomEvent(SPAWN_DIRECTORY_EVENT, { detail: path })));
-  const sessionEvent =
-    (name: string) =>
-    (session: Session): void => {
-      document.dispatchEvent(new CustomEvent(name, { detail: session }));
-    };
-  const killSession = opts.onKillSession ?? sessionEvent(KILL_SESSION_EVENT);
-  const renameSession = opts.onRenameSession ?? sessionEvent(RENAME_SESSION_EVENT);
-  const spawnSimilar = opts.onSpawnSimilar ?? sessionEvent(SPAWN_SIMILAR_EVENT);
-  const loadDirectories = opts.loadDirectories ?? loadBarDirectories;
-  const listEntries =
-    opts.listDirEntries ?? ((dir: string) => listDir(dir).then((listing) => listing.entries));
-
-  const sessionCandidates: SessionBarCandidate[] = sessionBarCandidates(
-    opts.sessions,
-    opts.homeDir,
-  );
-  const commandCandidates: CommandBarCandidate[] = commandBarCandidates(
-    opts.commands ?? publishedCommands(),
-  );
-
-  const el = document.createElement("div");
-  el.className = "cmdbar-overlay";
-  el.setAttribute("role", "dialog");
-  el.setAttribute("aria-modal", "true");
-  el.setAttribute("aria-label", "Command bar");
-
-  const panel = document.createElement("div");
-  panel.className = "cmdbar-panel";
-
-  const input = document.createElement("input");
-  input.type = "text";
-  input.className = "cmdbar-input";
-  input.setAttribute("role", "combobox");
-  input.setAttribute("aria-expanded", "true");
-  input.setAttribute("aria-controls", "cmdbar-results");
-  input.setAttribute("aria-label", "Search sessions, commands and directories");
-  input.setAttribute("autocomplete", "off");
-  input.spellcheck = false;
-  input.placeholder = PLACEHOLDERS.mixed;
-
-  const results = document.createElement("div");
-  results.className = "cmdbar-results";
-  results.id = "cmdbar-results";
-  results.setAttribute("role", "listbox");
-
-  panel.append(input, results);
-  el.appendChild(panel);
-  document.body.appendChild(el);
-
-  let rows: BarResult[] = [];
-  let highlighted = 0;
-
-  // The action page (#151). `page` is the session being acted on, `stashed`
-  // the result-list query it was drilled into from — backing out restores it,
-  // so the round trip costs the operator nothing.
-  let page: Session | null = null;
-  let stashed = "";
-  let header: HTMLElement | null = null;
-
-  // `~`'s candidates: the recents-and-projects list, fetched once, plus
-  // whatever `/api/dirs` has filled in for the directory being typed.
-  let directories: DirectoryBarCandidate[] = [];
-  let directoriesRequested = false;
-  let probed: DirectoryBarCandidate[] = [];
-  let probedDir: string | null = null;
-  const listings = new Map<string, string[]>();
-
-  function alive(): boolean {
-    return current?.el === el;
-  }
-
-  /** Fetch the recents-and-projects list the first time `~` is used. */
-  function ensureDirectories(): void {
-    if (directoriesRequested) return;
-    directoriesRequested = true;
-    loadDirectories()
-      .then((paths) => {
-        directories = directoryBarCandidates(paths, opts.homeDir);
-        if (alive()) render();
-      })
-      .catch(() => {
-        /* no directories is a shorter list, not an error state */
-      });
-  }
-
-  /** Fill the list in from `GET /api/dirs` once the query looks like a path:
-   *  the directory it names is listed and its children join the candidates, so
-   *  `~` reaches a directory that was never spawned in. */
-  function probeDirectories(query: string): void {
-    const { dir } = splitPath(query);
-    if (dir === "") {
-      probed = [];
-      probedDir = null;
-      return;
-    }
-    if (dir === probedDir) return;
-    probedDir = dir;
-    const cached = listings.get(dir);
-    if (cached) {
-      probed = directoryBarCandidates(
-        cached.map((entry) => `${dir}${entry}`),
-        opts.homeDir,
-      );
-      return;
-    }
-    probed = [];
-    listEntries(dir)
-      .then((entries) => {
-        listings.set(dir, entries);
-        if (!alive() || probedDir !== dir) return;
-        probed = directoryBarCandidates(
-          entries.map((entry) => `${dir}${entry}`),
-          opts.homeDir,
-        );
-        render();
-      })
-      .catch(() => {
-        /* an unreadable directory contributes nothing */
-      });
-  }
-
-  /** What the matcher sees for the query line as it stands. With no sigil the
-   *  list is mixed — sessions and commands together — except on an empty query,
-   *  where the bar is a session switcher. */
-  function candidatesFor(parsed: BarQuery): BarCandidate[] {
-    if (page) return sessionActionCandidates();
-    switch (parsed.sigil) {
-      case ">":
-        return [...commandCandidates];
-      case "~": {
-        ensureDirectories();
-        probeDirectories(parsed.query);
-        const seen = new Set<string>();
-        return [...directories, ...probed].filter((c) =>
-          seen.has(c.path) ? false : (seen.add(c.path), true),
-        );
-      }
-      default:
-        return parsed.query === ""
-          ? [...sessionCandidates]
-          : [...sessionCandidates, ...commandCandidates];
-    }
-  }
-
-  function paintHighlight(): void {
-    for (const row of results.querySelectorAll<HTMLElement>(".cmdbar-row")) {
-      const active = Number(row.dataset.index) === highlighted;
-      row.classList.toggle("is-active", active);
-      row.setAttribute("aria-selected", active ? "true" : "false");
-      if (active) {
-        row.scrollIntoView({ block: "nearest" });
-        input.setAttribute("aria-activedescendant", row.id);
-      }
-    }
-    if (rows.length === 0) input.removeAttribute("aria-activedescendant");
-  }
-
-  /** The line naming the session being acted on, so the target is never
-   *  ambiguous. Present only while the action page is up. */
-  function paintHeader(): void {
-    header?.remove();
-    header = null;
-    if (!page) return;
-    header = document.createElement("div");
-    header.className = "cmdbar-page-header";
-    header.setAttribute("role", "presentation");
-    header.textContent = `Actions for "${sessionName(page)}"`;
-    panel.insertBefore(header, results);
-  }
-
-  function render(): void {
-    // On the action page the query line is over the three actions, so there is
-    // no sigil to read: `>` and `~` are ordinary characters there.
-    const parsed = page ? { sigil: null, query: input.value } : parseBarQuery(input.value);
-    input.placeholder = page
-      ? `Act on ${sessionName(page)}…`
-      : PLACEHOLDERS[parsed.sigil ?? "mixed"];
-    paintHeader();
-    rows = barRows(parsed.query, candidatesFor(parsed));
-    // The highlight starts on the globally best row every time the list
-    // changes: an old index would point at a different result.
-    highlighted = 0;
-    results.replaceChildren();
-
-    if (rows.length === 0) {
-      const empty = document.createElement("div");
-      empty.className = "cmdbar-empty";
-      empty.textContent = "No matches";
-      results.appendChild(empty);
-      paintHighlight();
-      return;
-    }
-
-    let index = 0;
-    for (const group of barGroups(rows)) {
-      // While a sigil is in force there is one kind, so the header is
-      // dropped — and the action page is one kind too.
-      if (parsed.sigil === null && !page) {
-        const header = document.createElement("div");
-        header.className = "cmdbar-group-title";
-        header.setAttribute("role", "presentation");
-        header.textContent = group.title;
-        results.appendChild(header);
-      }
-      for (const result of group.results) {
-        const at = index;
-        const row = renderRow(result, at);
-        row.addEventListener("click", () => activate(at));
-        results.appendChild(row);
-        index += 1;
-      }
-    }
-    paintHighlight();
-  }
-
-  /** The highlight does not wrap: it stops at the first and last row. */
-  function move(delta: number): void {
-    if (rows.length === 0) return;
-    highlighted = Math.min(rows.length - 1, Math.max(0, highlighted + delta));
-    paintHighlight();
-  }
-
-  /** `tab`: drill into the highlighted session's action page. No effect on any
-   *  other kind, and none on the page itself, which has no session rows. */
-  function drillIn(): void {
-    const candidate = rows[highlighted]?.candidate;
-    if (page || candidate?.kind !== "session") return;
-    page = candidate.session;
-    stashed = input.value;
-    input.value = "";
-    render();
-  }
-
-  /** Escape, or backspace at an empty query: back to the result list with the
-   *  query the drill-in was made from. */
-  function leavePage(): void {
-    page = null;
-    input.value = stashed;
-    stashed = "";
-    render();
-  }
-
-  function runAction(action: SessionAction, session: Session): void {
-    close();
-    switch (action.id) {
-      case "kill":
-        killSession(session);
-        return;
-      case "rename":
-        renameSession(session);
-        return;
-      case "spawn-similar":
-        spawnSimilar(session);
-        return;
-    }
-  }
-
-  function activate(index: number): void {
-    const result = rows[index];
-    if (!result) return;
-    const candidate = result.candidate;
-    if (isActionCandidate(candidate)) {
-      // The page cannot be up without a session to act on.
-      if (page) runAction(candidate.action, page);
-      return;
-    }
-    close();
-    switch (candidate.kind) {
-      case "session":
-        openSession(candidate.session.id);
-        return;
-      case "command":
-        candidate.command.run();
-        return;
-      case "directory":
-        spawnDirectory(candidate.path);
-        return;
-    }
-  }
-
-  function onKeydown(e: KeyboardEvent): void {
-    switch (e.key) {
-      case "Escape":
-        e.preventDefault();
-        // On an action page Escape is one level up, not the way out.
-        if (page) leavePage();
-        else close();
-        return;
-      case "Tab":
-        e.preventDefault();
-        drillIn();
-        return;
-      case "Backspace":
-        // Ordinary editing, except at an empty query on the action page.
-        if (page && input.value === "") {
-          e.preventDefault();
-          leavePage();
-        }
-        return;
-      case "Enter":
-        e.preventDefault();
-        activate(highlighted);
-        return;
-      case "ArrowDown":
-        e.preventDefault();
-        move(1);
-        return;
-      case "ArrowUp":
-        e.preventDefault();
-        move(-1);
-        return;
-      case "n":
-        if (e.ctrlKey) {
-          e.preventDefault();
-          move(1);
-        }
-        return;
-      case "p":
-        if (e.ctrlKey) {
-          e.preventDefault();
-          move(-1);
-        }
-        return;
-    }
-  }
-
-  function close(): void {
-    if (current?.el !== el) return;
-    current = null;
-    el.remove();
-    // Restoring focus is what makes the bar a view over the app rather than a
-    // place in it; a detached node cannot take it.
-    if (previouslyFocused?.isConnected) previouslyFocused.focus();
-  }
-
-  input.addEventListener("keydown", onKeydown);
-  input.addEventListener("input", render);
-  // A press on the scrim closes; one inside the panel is left alone.
-  el.addEventListener("mousedown", (ev) => {
-    if (!panel.contains(ev.target as Node)) close();
-  });
-
-  current = { el, dispose: close };
-  render();
-  input.focus();
-  return el;
-}

web/src/components/commandBar/ActionPage.tsx

@@ -0,0 +1,34 @@
+// A session's action page (docs/COMMAND-BAR.md, "Drill-in"): the same overlay
+// over kill, rename and spawn similar, still fuzzy searchable. The page names
+// the session it acts on, so the target is never ambiguous.
+
+import { sessionName, type Session } from "../../types.js";
+import { ResultList } from "./ResultList.js";
+import type { BarGroup } from "./model.js";
+
+export interface ActionPageProps {
+  session: Session;
+  /** The three actions, ranked by the query line — one kind, so no headers. */
+  groups: BarGroup[];
+  highlighted: number;
+  onActivate(index: number): void;
+}
+
+export function ActionPage({ session, groups, highlighted, onActivate }: ActionPageProps) {
+  return (
+    <>
+      <div
+        role="presentation"
+        className="cmdbar-page-header border-b border-border px-sp-3 py-sp-1 text-fs-11 text-muted"
+      >
+        {`Actions for "${sessionName(session)}"`}
+      </div>
+      <ResultList
+        groups={groups}
+        showHeaders={false}
+        highlighted={highlighted}
+        onActivate={onActivate}
+      />
+    </>
+  );
+}

web/src/components/commandBar/CommandBar.test.tsx

@@ -0,0 +1,407 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  KILL_SESSION_EVENT,
+  RENAME_SESSION_EVENT,
+  SESSION_SELECT_EVENT,
+  SPAWN_SIMILAR_EVENT,
+} from "../../uiEvents.js";
+import { COMMAND_SPECS, type Command } from "../../commands.js";
+import type { Session } from "../../types.js";
+import { CommandBar, SPAWN_DIRECTORY_EVENT, type CommandBarProps } from "./CommandBar.js";
+
+vi.mock("../../api.js", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  listDir: vi.fn(async () => ({ path: "", entries: [] })),
+  projects: vi.fn(async () => []),
+  recentDirs: vi.fn(async () => ({ dirs: [] })),
+}));
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/me/dev/api",
+    command: "bash",
+    env: {},
+    metadata: { name: id },
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+function command(over: Partial<Command> = {}): Command {
+  return {
+    id: "cmd",
+    label: "A command",
+    group: "Test",
+    keys: ["a"],
+    scope: "global",
+    run: () => {},
+    ...over,
+  };
+}
+
+const sessions = [
+  session("api", { current_cwd: "/home/me/dev/api", last_focused_at: "2026-01-01T11:00:00Z" }),
+  session("worker", {
+    current_cwd: "/home/me/dev/worker",
+    last_focused_at: "2026-01-01T10:00:00Z",
+  }),
+  session("notes", { current_cwd: "/home/me/notes" }),
+];
+
+function open(over: Partial<CommandBarProps> = {}) {
+  return render(
+    <CommandBar
+      sessions={sessions}
+      homeDir="/home/me"
+      commands={[]}
+      onOpenSession={() => {}}
+      onClose={() => {}}
+      {...over}
+    />,
+  );
+}
+
+function input(): HTMLInputElement {
+  return screen.getByRole("combobox") as HTMLInputElement;
+}
+
+function type(value: string): void {
+  fireEvent.change(input(), { target: { value } });
+}
+
+function press(key: string, init: Record<string, unknown> = {}): void {
+  fireEvent.keyDown(input(), { key, ...init });
+}
+
+function rowNames(): string[] {
+  return [...document.querySelectorAll(".cmdbar-row-name")].map((r) => r.textContent ?? "");
+}
+
+function activeName(): string | undefined {
+  return document.querySelector(".cmdbar-row.is-active .cmdbar-row-name")?.textContent ?? undefined;
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("the overlay", () => {
+  it("is a registry command, so the help overlay lists it", () => {
+    const spec = COMMAND_SPECS.find((s) => s.id === "bar.open");
+    expect(spec?.keys).toEqual(["ctrl-k"]);
+    expect(spec?.scope).toBe("global");
+  });
+
+  it("lists sessions by recency under a kind header on an empty query", () => {
+    open();
+    expect([...document.querySelectorAll(".cmdbar-group-title")].map((h) => h.textContent)).toEqual([
+      "Sessions",
+    ]);
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+    expect(activeName()).toBe("api");
+  });
+
+  it("ranks a typed query through the matcher and highlights the matched range", () => {
+    open();
+    type("wor");
+    expect(rowNames()).toEqual(["worker"]);
+    expect([...document.querySelectorAll(".cmdbar-row-name mark")].map((m) => m.textContent)).toEqual(
+      ["wor"],
+    );
+  });
+
+  it("highlights inside the directory when that is the field that matched", () => {
+    open();
+    type("dev/wor");
+    expect(rowNames()).toEqual(["worker"]);
+    expect(
+      [...document.querySelectorAll(".cmdbar-row-meta mark")].map((m) => m.textContent).join(""),
+    ).toBe("dev/wor");
+  });
+
+  it("renders a no-results state rather than an empty list", () => {
+    open();
+    type("zzz");
+    expect(rowNames()).toEqual([]);
+    expect(screen.getByText("No matches")).toBeDefined();
+  });
+
+  it("moves the highlight with the arrows and ctrl-p/ctrl-n, without wrapping", () => {
+    open();
+    press("ArrowUp");
+    expect(activeName()).toBe("api");
+    press("ArrowDown");
+    expect(activeName()).toBe("worker");
+    press("n", { ctrlKey: true });
+    expect(activeName()).toBe("notes");
+    press("ArrowDown");
+    expect(activeName()).toBe("notes");
+    press("p", { ctrlKey: true });
+    expect(activeName()).toBe("worker");
+  });
+
+  it("puts the highlight back on the best row whenever the query changes", () => {
+    open();
+    press("ArrowDown");
+    expect(activeName()).toBe("worker");
+    type("o");
+    expect(activeName()).toBe(rowNames()[0]);
+  });
+
+  it("opens the highlighted session through the caller's open path on Enter", () => {
+    const onOpenSession = vi.fn();
+    const onClose = vi.fn();
+    open({ onOpenSession, onClose });
+    press("ArrowDown");
+    press("Enter");
+    expect(onOpenSession).toHaveBeenCalledWith("worker");
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("raises the shared select event when the caller supplies no handler", () => {
+    const listener = vi.fn();
+    document.addEventListener(SESSION_SELECT_EVENT, listener);
+    open({ onOpenSession: undefined });
+    press("Enter");
+    document.removeEventListener(SESSION_SELECT_EVENT, listener);
+    expect((listener.mock.calls[0][0] as CustomEvent).detail).toBe("api");
+  });
+
+  it("Enter on an empty result list does nothing", () => {
+    const onOpenSession = vi.fn();
+    const onClose = vi.fn();
+    open({ onOpenSession, onClose });
+    type("zzz");
+    press("Enter");
+    expect(onOpenSession).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes on Escape and on a press outside the panel", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    press("Escape");
+    expect(onClose).toHaveBeenCalledTimes(1);
+    fireEvent.mouseDown(document.querySelector(".cmdbar-overlay") as HTMLElement);
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it("stays open for a press inside the panel", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    fireEvent.mouseDown(document.querySelector(".cmdbar-panel") as HTMLElement);
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("returns the keyboard to whatever held it when it opened", () => {
+    const before = document.createElement("input");
+    document.body.appendChild(before);
+    before.focus();
+    const view = open();
+    expect(document.activeElement).toBe(input());
+    view.unmount();
+    expect(document.activeElement).toBe(before);
+    before.remove();
+  });
+
+  it("clicking a row opens that session", () => {
+    const onOpenSession = vi.fn();
+    open({ onOpenSession });
+    fireEvent.click(document.querySelectorAll(".cmdbar-row")[1]);
+    expect(onOpenSession).toHaveBeenCalledWith("worker");
+  });
+});
+
+describe("the sigils", () => {
+  const commands = [
+    command({ id: "help.toggle", label: "Show help", keys: ["?"] }),
+    command({ id: "spawn.open", label: "Open the spawn form", keys: ["n"], run: vi.fn() }),
+  ];
+
+  it("lists every command in registry order under `>`, with its chord and no header", () => {
+    open({ commands });
+    type(">");
+    expect(rowNames()).toEqual(["Show help", "Open the spawn form"]);
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+    expect([...document.querySelectorAll(".cmdbar-row-keys kbd")].map((k) => k.textContent)).toEqual(
+      ["?", "n"],
+    );
+  });
+
+  it("matches a command on its label and never on its chord", () => {
+    open({ commands });
+    type(">help");
+    expect(rowNames()).toEqual(["Show help"]);
+    type(">?");
+    expect(rowNames()).toEqual([]);
+  });
+
+  it("runs the highlighted command on Enter", () => {
+    const run = vi.fn();
+    open({ commands: [command({ label: "Run me", run })] });
+    type(">run");
+    press("Enter");
+    expect(run).toHaveBeenCalled();
+  });
+
+  it("keeps the list mixed with no sigil, and returns to it when the sigil goes", () => {
+    open({ commands });
+    type(">show");
+    expect(rowNames()).toEqual(["Show help"]);
+    type("");
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+  });
+
+  it("lists recent dirs then projects under `~`", async () => {
+    open({ loadDirectories: async () => ["/home/me/dev/api", "/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["~/dev/api", "/srv/x"]));
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+  });
+
+  it("fills the list in from /api/dirs as a path is typed", async () => {
+    const listDirEntries = vi.fn(async () => ["maestro", "api"]);
+    open({ loadDirectories: async () => ["/home/me/notes"], listDirEntries });
+    // The second `~` is a literal query character and reaches the matcher.
+    type("~~/dev/mae");
+    await waitFor(() => expect(rowNames()).toEqual(["~/dev/maestro"]));
+    expect(listDirEntries).toHaveBeenCalledWith("~/dev/");
+  });
+
+  it("spawns in the highlighted directory on Enter", async () => {
+    const onSpawnDirectory = vi.fn();
+    open({ loadDirectories: async () => ["/srv/x"], onSpawnDirectory });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Enter");
+    expect(onSpawnDirectory).toHaveBeenCalledWith("/srv/x");
+  });
+
+  it("raises the spawn event when the caller supplies no handler", async () => {
+    const listener = vi.fn();
+    document.addEventListener(SPAWN_DIRECTORY_EVENT, listener);
+    open({ loadDirectories: async () => ["/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Enter");
+    document.removeEventListener(SPAWN_DIRECTORY_EVENT, listener);
+    expect((listener.mock.calls[0][0] as CustomEvent).detail).toBe("/srv/x");
+  });
+});
+
+describe("the session action page", () => {
+  function drill(over: Partial<CommandBarProps> = {}) {
+    const view = open(over);
+    press("Tab");
+    return view;
+  }
+
+  it("lists kill, rename and spawn similar for the highlighted session", () => {
+    drill();
+    expect(rowNames()).toEqual(["Kill session", "Rename session", "Spawn similar"]);
+  });
+
+  it("names the session being acted on", () => {
+    drill();
+    expect(screen.getByText('Actions for "api"')).toBeDefined();
+  });
+
+  it("drops the kind headers, since the page is one kind", () => {
+    drill();
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+  });
+
+  it("stays fuzzy-searchable over the three actions", () => {
+    drill();
+    type("ren");
+    expect(rowNames()).toEqual(["Rename session"]);
+  });
+
+  it("does nothing on a command row", () => {
+    open({ commands: [command({ label: "Show help" })] });
+    type(">show");
+    press("Tab");
+    expect(rowNames()).toEqual(["Show help"]);
+  });
+
+  it("does nothing on a directory row", async () => {
+    open({ loadDirectories: async () => ["/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Tab");
+    expect(rowNames()).toEqual(["/srv/x"]);
+  });
+
+  it("returns to the result list on Escape, with the previous query intact", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    type("wor");
+    press("Tab");
+    expect(rowNames()).toEqual(["Kill session", "Rename session", "Spawn similar"]);
+    press("Escape");
+    expect(onClose).not.toHaveBeenCalled();
+    expect(input().value).toBe("wor");
+    expect(rowNames()).toEqual(["worker"]);
+  });
+
+  it("returns to the result list on backspace at an empty query", () => {
+    drill();
+    fireEvent.keyDown(input(), { key: "Backspace" });
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+  });
+
+  it("keeps backspace ordinary while the page's query has text", () => {
+    drill();
+    type("ren");
+    fireEvent.keyDown(input(), { key: "Backspace" });
+    expect(rowNames()).toEqual(["Rename session"]);
+  });
+
+  it("closes the bar when the page's Escape has already been used", () => {
+    const onClose = vi.fn();
+    drill({ onClose });
+    press("Escape");
+    press("Escape");
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("raises kill, rename and spawn similar with the session, closing the bar", () => {
+    for (const [query, key] of [
+      ["kill", "onKillSession"],
+      ["rename", "onRenameSession"],
+      ["spawn", "onSpawnSimilar"],
+    ] as const) {
+      const handler = vi.fn();
+      const onClose = vi.fn();
+      drill({ [key]: handler, onClose });
+      type(query);
+      press("Enter");
+      expect(handler).toHaveBeenCalledWith(expect.objectContaining({ id: "api" }));
+      expect(onClose).toHaveBeenCalled();
+      cleanup();
+    }
+  });
+
+  it("hands each action to the flow it already has, by default", () => {
+    for (const [query, event] of [
+      ["kill", KILL_SESSION_EVENT],
+      ["rename", RENAME_SESSION_EVENT],
+      ["spawn", SPAWN_SIMILAR_EVENT],
+    ] as const) {
+      const listener = vi.fn();
+      document.addEventListener(event, listener);
+      drill();
+      type(query);
+      press("Enter");
+      document.removeEventListener(event, listener);
+      expect((listener.mock.calls[0][0] as CustomEvent).detail.id).toBe("api");
+      cleanup();
+    }
+  });
+});

web/src/components/commandBar/CommandBar.tsx

@@ -0,0 +1,379 @@
+// The `ctrl-k` command bar (docs/COMMAND-BAR.md): a query line over a result
+// list. Sessions and commands rank together by default; `>` narrows to
+// commands, `~` to directories. `tab` on a session drills into its action page.
+//
+// The bar picks an action and hands off — it never reimplements one. Each
+// handler defaults to the event the flow that already implements it listens
+// on, so the React bar and the legacy shell raise the same flows.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+import {
+  KILL_SESSION_EVENT,
+  RENAME_SESSION_EVENT,
+  SESSION_SELECT_EVENT,
+  SPAWN_SIMILAR_EVENT,
+} from "../../uiEvents.js";
+import { publishedCommands, type Command } from "../../commands.js";
+import { sessionName, type Session } from "../../types.js";
+import { ActionPage } from "./ActionPage.js";
+import { ResultList } from "./ResultList.js";
+import {
+  barGroups,
+  barRows,
+  commandBarCandidates,
+  dirEntryPaths,
+  directoryBarCandidates,
+  isActionCandidate,
+  listDirEntries as defaultListDirEntries,
+  loadBarDirectories,
+  parseBarQuery,
+  probeDir,
+  sessionActionCandidates,
+  sessionBarCandidates,
+  PLACEHOLDERS,
+  type BarCandidate,
+  type BarResult,
+  type DirectoryBarCandidate,
+  type SessionAction,
+} from "./model.js";
+
+/** Raised when Enter lands on a directory row and no handler was given. The
+ *  bar picks the directory; the shell owns the spawn, which is the same
+ *  fast-forward path `N` takes. */
+export const SPAWN_DIRECTORY_EVENT = "cmdbar-spawn-directory";
+
+export interface CommandBarProps {
+  /** Sessions to build candidates from, as the store has them right now. */
+  sessions: readonly Session[];
+  /** The daemon's home dir, for the directory field's `~/…` abbreviation. */
+  homeDir?: string;
+  /** The command registry to list under `>`. Defaults to every bound command,
+   * in registry order. */
+  commands?: readonly Command[];
+  /** The directory list behind `~`, fetched once on first use. */
+  loadDirectories?: () => Promise<string[]>;
+  /** One directory's subdirectories, for filling the list in as a path is
+   * typed. Defaults to `GET /api/dirs`. */
+  listDirEntries?: (dir: string) => Promise<string[]>;
+  onOpenSession?(sessionId: string): void;
+  onSpawnDirectory?(path: string): void;
+  onKillSession?(session: Session): void;
+  onRenameSession?(session: Session): void;
+  onSpawnSimilar?(session: Session): void;
+  /** Closing returns the keyboard to whatever held it when the bar opened. */
+  onClose(): void;
+}
+
+function raise(name: string, detail: unknown): void {
+  document.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+export function CommandBar(props: CommandBarProps) {
+  const {
+    sessions,
+    homeDir,
+    commands,
+    loadDirectories = loadBarDirectories,
+    listDirEntries = defaultListDirEntries,
+    onClose,
+  } = props;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  const [raw, setRaw] = useState("");
+  const [highlighted, setHighlighted] = useState(0);
+  // The action page: `page` is the session being acted on, `stashed` the
+  // result-list query it was drilled into from — backing out restores it, so
+  // the round trip costs the operator nothing.
+  const [page, setPage] = useState<Session | null>(null);
+  const [stashed, setStashed] = useState("");
+
+  // `~`'s candidates: the recents-and-projects list, fetched once, plus
+  // whatever `/api/dirs` has filled in for the directory being typed.
+  const [directories, setDirectories] = useState<DirectoryBarCandidate[]>([]);
+  const [probed, setProbed] = useState<DirectoryBarCandidate[]>([]);
+  const requestedRef = useRef(false);
+  const listingsRef = useRef(new Map<string, string[]>());
+
+  // On the action page the query line is over the three actions, so there is
+  // no sigil to read: `>` and `~` are ordinary characters there.
+  const parsed = useMemo(() => (page ? { sigil: null, query: raw } : parseBarQuery(raw)), [page, raw]);
+
+  const sessionCandidates = useMemo(
+    () => sessionBarCandidates(sessions, homeDir),
+    [sessions, homeDir],
+  );
+  const commandCandidates = useMemo(
+    () => commandBarCandidates(commands ?? publishedCommands()),
+    [commands],
+  );
+
+  // Closing returns the keyboard to whatever held it when the bar opened: a
+  // round trip through the bar never silently moves focus.
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    inputRef.current?.focus();
+    return () => {
+      if (previouslyFocused?.isConnected) previouslyFocused.focus();
+    };
+  }, []);
+
+  // The recents-and-projects list, the first time `~` is used. No directories
+  // is a shorter list, not an error state.
+  useEffect(() => {
+    if (parsed.sigil !== "~" || requestedRef.current) return;
+    requestedRef.current = true;
+    let live = true;
+    loadDirectories()
+      .then((paths) => {
+        if (live) setDirectories(directoryBarCandidates(paths, homeDir));
+      })
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, [parsed.sigil, loadDirectories, homeDir]);
+
+  // Fill the list in from `GET /api/dirs` once the query looks like a path: the
+  // directory it names is listed and its children join the candidates, so `~`
+  // reaches a directory that was never spawned in.
+  const dir = parsed.sigil === "~" ? probeDir(parsed.query) : "";
+  useEffect(() => {
+    if (dir === "") {
+      setProbed([]);
+      return;
+    }
+    const cached = listingsRef.current.get(dir);
+    if (cached) {
+      setProbed(directoryBarCandidates(dirEntryPaths(dir, cached), homeDir));
+      return;
+    }
+    let live = true;
+    setProbed([]);
+    listDirEntries(dir)
+      .then((entries) => {
+        listingsRef.current.set(dir, entries);
+        if (live) setProbed(directoryBarCandidates(dirEntryPaths(dir, entries), homeDir));
+      })
+      .catch(() => {
+        /* an unreadable directory contributes nothing */
+      });
+    return () => {
+      live = false;
+    };
+  }, [dir, listDirEntries, homeDir]);
+
+  /** What the matcher sees for the query line as it stands. With no sigil the
+   *  list is mixed — sessions and commands together — except on an empty query,
+   *  where the bar is a session switcher. */
+  const candidates: BarCandidate[] = useMemo(() => {
+    if (page) return sessionActionCandidates();
+    switch (parsed.sigil) {
+      case ">":
+        return [...commandCandidates];
+      case "~": {
+        const seen = new Set<string>();
+        return [...directories, ...probed].filter((c) =>
+          seen.has(c.path) ? false : (seen.add(c.path), true),
+        );
+      }
+      default:
+        return parsed.query === ""
+          ? [...sessionCandidates]
+          : [...sessionCandidates, ...commandCandidates];
+    }
+  }, [page, parsed.sigil, parsed.query, sessionCandidates, commandCandidates, directories, probed]);
+
+  const groups = useMemo(
+    () => barGroups(barRows(parsed.query, candidates)),
+    [parsed.query, candidates],
+  );
+  // Grouping is a rendering of the ranking, so the flattened groups are the
+  // rows in the order they appear — which is the order the highlight walks and
+  // Enter acts on.
+  const rows: BarResult[] = useMemo(() => groups.flatMap((g) => g.results), [groups]);
+
+  // The highlight starts on the globally best row every time the list changes:
+  // an old index would point at a different result.
+  useEffect(() => {
+    setHighlighted(0);
+  }, [rows]);
+
+  /** The highlight does not wrap: it stops at the first and last row. */
+  const move = useCallback(
+    (delta: number) => {
+      setHighlighted((at) => Math.min(rows.length - 1, Math.max(0, at + delta)));
+    },
+    [rows.length],
+  );
+
+  const runAction = useCallback(
+    (action: SessionAction, session: Session) => {
+      onClose();
+      switch (action.id) {
+        case "kill":
+          (props.onKillSession ?? ((s: Session) => raise(KILL_SESSION_EVENT, s)))(session);
+          return;
+        case "rename":
+          (props.onRenameSession ?? ((s: Session) => raise(RENAME_SESSION_EVENT, s)))(session);
+          return;
+        case "spawn-similar":
+          (props.onSpawnSimilar ?? ((s: Session) => raise(SPAWN_SIMILAR_EVENT, s)))(session);
+          return;
+      }
+    },
+    [onClose, props.onKillSession, props.onRenameSession, props.onSpawnSimilar],
+  );
+
+  const activate = useCallback(
+    (index: number) => {
+      const result = rows[index];
+      if (!result) return;
+      const candidate = result.candidate;
+      if (isActionCandidate(candidate)) {
+        // The page cannot be up without a session to act on.
+        if (page) runAction(candidate.action, page);
+        return;
+      }
+      onClose();
+      switch (candidate.kind) {
+        case "session":
+          (props.onOpenSession ?? ((id: string) => raise(SESSION_SELECT_EVENT, id)))(
+            candidate.session.id,
+          );
+          return;
+        case "command":
+          candidate.command.run();
+          return;
+        case "directory":
+          (props.onSpawnDirectory ?? ((p: string) => raise(SPAWN_DIRECTORY_EVENT, p)))(
+            candidate.path,
+          );
+          return;
+      }
+    },
+    [rows, page, runAction, onClose, props.onOpenSession, props.onSpawnDirectory],
+  );
+
+  /** `tab`: drill into the highlighted session's action page. No effect on any
+   *  other kind, and none on the page itself, which has no session rows. */
+  const drillIn = useCallback(() => {
+    const candidate = rows[highlighted]?.candidate;
+    if (page || candidate?.kind !== "session") return;
+    setPage(candidate.session);
+    setStashed(raw);
+    setRaw("");
+  }, [rows, highlighted, page, raw]);
+
+  /** Escape, or backspace at an empty query: back to the result list with the
+   *  query the drill-in was made from. */
+  const leavePage = useCallback(() => {
+    setPage(null);
+    setRaw(stashed);
+    setStashed("");
+  }, [stashed]);
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    switch (e.key) {
+      case "Escape":
+        e.preventDefault();
+        // On an action page Escape is one level up, not the way out.
+        if (page) leavePage();
+        else onClose();
+        return;
+      case "Tab":
+        e.preventDefault();
+        drillIn();
+        return;
+      case "Backspace":
+        // Ordinary editing, except at an empty query on the action page.
+        if (page && raw === "") {
+          e.preventDefault();
+          leavePage();
+        }
+        return;
+      case "Enter":
+        e.preventDefault();
+        activate(highlighted);
+        return;
+      case "ArrowDown":
+        e.preventDefault();
+        move(1);
+        return;
+      case "ArrowUp":
+        e.preventDefault();
+        move(-1);
+        return;
+      case "n":
+        if (e.ctrlKey) {
+          e.preventDefault();
+          move(1);
+        }
+        return;
+      case "p":
+        if (e.ctrlKey) {
+          e.preventDefault();
+          move(-1);
+        }
+        return;
+    }
+  };
+
+  const activeRowId = rows.length > 0 ? `cmdbar-row-${highlighted}` : undefined;
+
+  return createPortal(
+    <div
+      className="cmdbar-overlay fixed inset-0 z-modal flex items-start justify-center bg-bg/70 pt-[12vh] backdrop-blur-sm max-[600px]:items-end max-[600px]:pt-0"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command bar"
+      onMouseDown={(e) => {
+        // A press on the scrim closes; one inside the panel is left alone.
+        if (!panelRef.current?.contains(e.target as Node)) onClose();
+      }}
+    >
+      <div
+        ref={panelRef}
+        className="cmdbar-panel flex w-full max-w-[560px] flex-col overflow-hidden rounded-r-3 border border-border bg-surface shadow-2 max-[600px]:max-w-none max-[600px]:rounded-b-none"
+      >
+        <input
+          ref={inputRef}
+          type="text"
+          role="combobox"
+          aria-expanded="true"
+          aria-controls="cmdbar-results"
+          aria-label="Search sessions, commands and directories"
+          aria-activedescendant={activeRowId}
+          autoComplete="off"
+          spellCheck={false}
+          className="cmdbar-input w-full border-b border-border bg-transparent px-sp-3 py-sp-2 text-fs-15 text-ink outline-none"
+          placeholder={page ? `Act on ${sessionName(page)}…` : PLACEHOLDERS[parsed.sigil ?? "mixed"]}
+          value={raw}
+          onChange={(e) => setRaw(e.currentTarget.value)}
+          onKeyDown={onKeyDown}
+        />
+        {page ? (
+          <ActionPage
+            session={page}
+            groups={groups}
+            highlighted={highlighted}
+            onActivate={activate}
+          />
+        ) : (
+          <ResultList
+            groups={groups}
+            // While a sigil is in force there is one kind, so the header is
+            // dropped.
+            showHeaders={parsed.sigil === null}
+            highlighted={highlighted}
+            onActivate={activate}
+          />
+        )}
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/commandBar/ResultList.tsx

@@ -0,0 +1,171 @@
+// The bar's result list: kind headers over rank-ordered rows
+// (docs/COMMAND-BAR.md, "Structure"). Headers are labels, never rows — the
+// highlight walks the rows alone, in the order they are rendered.
+
+import { useEffect, useRef } from "react";
+
+import { keyCaps } from "../../commands.js";
+import {
+  highlightSegments,
+  isActionCandidate,
+  metaText,
+  rowName,
+  type BarGroup,
+  type BarResult,
+} from "./model.js";
+
+export interface ResultListProps {
+  groups: BarGroup[];
+  /** Dropped while a sigil is in force or on the action page: one kind needs
+   * no header. */
+  showHeaders: boolean;
+  /** Index into the flattened rows, in the order they render. */
+  highlighted: number;
+  onActivate(index: number): void;
+}
+
+function Highlighted({ text, ranges }: { text: string; ranges: BarResult["ranges"] }) {
+  return (
+    <>
+      {highlightSegments(text, ranges).map((segment, i) =>
+        segment.hit ? (
+          <mark key={i} className="cmdbar-hit bg-transparent font-semibold text-accent">
+            {segment.text}
+          </mark>
+        ) : (
+          <span key={i}>{segment.text}</span>
+        ),
+      )}
+    </>
+  );
+}
+
+function Row({
+  result,
+  index,
+  active,
+  onActivate,
+}: {
+  result: BarResult;
+  index: number;
+  active: boolean;
+  onActivate(index: number): void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const candidate = result.candidate;
+
+  useEffect(() => {
+    if (active) ref.current?.scrollIntoView({ block: "nearest" });
+  }, [active]);
+
+  const name = rowName(candidate);
+  const nameMatched =
+    result.field === "name" || result.field === "label" || result.field === "path";
+  const meta = metaText(result);
+  const dead = candidate.kind === "session" && candidate.session.status === "Dead";
+  const chord =
+    candidate.kind === "command" && !isActionCandidate(candidate)
+      ? candidate.command.keys[0]
+      : undefined;
+
+  return (
+    <div
+      ref={ref}
+      role="option"
+      id={`cmdbar-row-${index}`}
+      aria-selected={active}
+      data-index={index}
+      data-kind={candidate.kind}
+      data-session-id={candidate.kind === "session" ? candidate.session.id : undefined}
+      data-action-id={isActionCandidate(candidate) ? candidate.action.id : undefined}
+      data-command-id={
+        candidate.kind === "command" && !isActionCandidate(candidate)
+          ? candidate.command.id
+          : undefined
+      }
+      data-path={candidate.kind === "directory" ? candidate.path : undefined}
+      className={[
+        "cmdbar-row flex cursor-pointer items-baseline gap-sp-2 rounded-r-1 px-sp-3 py-sp-1 text-fs-13",
+        active ? "is-active bg-surface-2 text-ink" : "text-ink",
+        dead ? "is-dead opacity-60" : "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      onClick={() => onActivate(index)}
+    >
+      <span className="cmdbar-row-name truncate">
+        {nameMatched ? <Highlighted text={name} ranges={result.ranges} /> : name}
+      </span>
+      {chord !== undefined ? (
+        <span className="cmdbar-row-keys ml-auto flex gap-1">
+          {keyCaps(chord).map((cap, i) => (
+            <kbd
+              key={i}
+              className="rounded-r-1 border border-border px-1 text-fs-11 text-muted"
+            >
+              {cap}
+            </kbd>
+          ))}
+        </span>
+      ) : meta ? (
+        <span className="cmdbar-row-meta ml-auto truncate text-fs-11 text-muted">
+          {result.field !== undefined && result.field !== "name" ? (
+            <Highlighted text={meta} ranges={result.ranges} />
+          ) : (
+            meta
+          )}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+export function ResultList({ groups, showHeaders, highlighted, onActivate }: ResultListProps) {
+  if (groups.length === 0) {
+    return (
+      <div
+        id="cmdbar-results"
+        role="listbox"
+        aria-label="Results"
+        className="cmdbar-results max-h-[50vh] overflow-auto p-sp-1"
+      >
+        <div className="cmdbar-empty px-sp-3 py-sp-2 text-fs-12 text-muted">No matches</div>
+      </div>
+    );
+  }
+
+  let index = 0;
+  return (
+    <div
+      id="cmdbar-results"
+      role="listbox"
+      aria-label="Results"
+      className="cmdbar-results max-h-[50vh] overflow-auto p-sp-1"
+    >
+      {groups.map((group) => (
+        <div key={group.kind}>
+          {showHeaders ? (
+            <div
+              role="presentation"
+              className="cmdbar-group-title px-sp-3 pt-sp-2 pb-1 text-fs-11 uppercase tracking-wide text-muted"
+            >
+              {group.title}
+            </div>
+          ) : null}
+          {group.results.map((result) => {
+            const at = index++;
+            return (
+              <Row
+                key={at}
+                result={result}
+                index={at}
+                active={at === highlighted}
+                onActivate={onActivate}
+              />
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}

web/src/components/commandBar/index.ts

@@ -0,0 +1,5 @@
+export { CommandBar, SPAWN_DIRECTORY_EVENT, type CommandBarProps } from "./CommandBar.js";
+export { ResultList, type ResultListProps } from "./ResultList.js";
+export { ActionPage, type ActionPageProps } from "./ActionPage.js";
+export { useCommandBar, type CommandBarControls, type UseCommandBarOptions } from "./useCommandBar.js";
+export * from "./model.js";

web/src/components/commandBar/model.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+
+import type { Command } from "../../commands.js";
+import type { Session } from "../../types.js";
+import {
+  barGroups,
+  barRows,
+  commandBarCandidates,
+  dedupeCommands,
+  directoryBarCandidates,
+  directoryCandidate,
+  highlightSegments,
+  orderSessionsForBar,
+  parseBarQuery,
+  sessionActionCandidates,
+  sessionBarCandidates,
+  sessionCandidate,
+} from "./model.js";
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/me/dev/api",
+    command: "bash",
+    env: {},
+    metadata: { name: id },
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+function command(over: Partial<Command> = {}): Command {
+  return {
+    id: "a",
+    label: "A command",
+    group: "Test",
+    keys: ["a"],
+    scope: "global",
+    run: () => {},
+    ...over,
+  };
+}
+
+describe("empty-query ordering", () => {
+  it("sorts most recently focused first", () => {
+    const older = session("older", { last_focused_at: "2026-01-01T10:00:00Z" });
+    const newer = session("newer", { last_focused_at: "2026-01-01T11:00:00Z" });
+    expect(orderSessionsForBar([older, newer]).map((s) => s.id)).toEqual(["newer", "older"]);
+  });
+
+  it("sorts a never-focused session after every focused one, newest created first", () => {
+    const focused = session("focused", { last_focused_at: "2026-01-01T09:00:00Z" });
+    const old = session("old", { created_at: "2026-01-01T00:00:00Z" });
+    const fresh = session("fresh", { created_at: "2026-01-02T00:00:00Z" });
+    expect(orderSessionsForBar([old, fresh, focused]).map((s) => s.id)).toEqual([
+      "focused",
+      "fresh",
+      "old",
+    ]);
+  });
+
+  it("sorts dead sessions after live ones regardless of recency", () => {
+    const dead = session("dead", { status: "Dead", last_focused_at: "2026-01-01T12:00:00Z" });
+    const live = session("live", { last_focused_at: "2026-01-01T10:00:00Z" });
+    expect(orderSessionsForBar([dead, live]).map((s) => s.id)).toEqual(["live", "dead"]);
+  });
+
+  it("treats an empty last_focused_at as never focused", () => {
+    const blank = session("blank", { last_focused_at: "" });
+    const focused = session("focused", { last_focused_at: "2026-01-01T10:00:00Z" });
+    expect(orderSessionsForBar([blank, focused]).map((s) => s.id)).toEqual(["focused", "blank"]);
+  });
+});
+
+describe("session candidates", () => {
+  it("carries the candidate table's fields, with the directory abbreviated", () => {
+    const s = session("api", {
+      metadata: { name: "api" },
+      current_cwd: "/home/me/dev/api",
+      command: "claude --resume",
+    });
+    expect(sessionCandidate(s, "/home/me").fields).toEqual({
+      name: "api",
+      directory: "~/dev/api",
+      command: "claude --resume",
+      tool: "claude",
+    });
+  });
+
+  it("leaves the tool out when the program has no mark, and groups a worktree by its repo", () => {
+    const s = session("edit", {
+      metadata: {},
+      command: "hx src/",
+      worktree: { path: "/home/me/dev/api/wt/x", base_repo: "/home/me/dev/api" },
+    });
+    const candidate = sessionCandidate(s, "/home/me");
+    expect(candidate.fields.tool).toBeUndefined();
+    expect(candidate.fields.directory).toBe("~/dev/api");
+    // No `metadata.name`: the sidebar's fallback is the command line.
+    expect(candidate.fields.name).toBe("hx src/");
+  });
+
+  it("builds candidates in the empty-query order", () => {
+    const a = session("a", { last_focused_at: "2026-01-01T10:00:00Z" });
+    const b = session("b", { last_focused_at: "2026-01-01T11:00:00Z" });
+    expect(sessionBarCandidates([a, b]).map((c) => c.session.id)).toEqual(["b", "a"]);
+  });
+});
+
+describe("rows and grouping", () => {
+  it("an empty query keeps every candidate in input order", () => {
+    const candidates = sessionBarCandidates([session("a"), session("b")]);
+    expect(barRows("", candidates).map((r) => r.score)).toEqual([0, 0]);
+  });
+
+  it("groups by kind without reordering the ranking", () => {
+    const rows = barRows("kill", [
+      ...sessionBarCandidates([session("killer-app", { metadata: { name: "killer-app" } })]),
+      ...commandBarCandidates([command({ label: "Kill selected session" })]),
+    ]);
+    const groups = barGroups(rows);
+    expect(groups.map((g) => g.title)).toEqual(["Sessions", "Commands"]);
+    expect(groups.flatMap((g) => g.results)).toEqual(rows);
+  });
+});
+
+describe("parsing the query line", () => {
+  it("reads a sigil only in first position", () => {
+    expect(parseBarQuery(">help")).toEqual({ sigil: ">", query: "help" });
+    expect(parseBarQuery("~dev")).toEqual({ sigil: "~", query: "dev" });
+  });
+
+  it("leaves a sigil character elsewhere in the query literal", () => {
+    expect(parseBarQuery("~dev/~scratch")).toEqual({ sigil: "~", query: "dev/~scratch" });
+    expect(parseBarQuery("a>b")).toEqual({ sigil: null, query: "a>b" });
+  });
+
+  it("returns to the mixed list when the sigil is backspaced away", () => {
+    expect(parseBarQuery("")).toEqual({ sigil: null, query: "" });
+  });
+});
+
+describe("command candidates", () => {
+  it("dedupes by action, not by chord", () => {
+    const run = () => {};
+    const cmds = [
+      command({ id: "one", label: "Do it", keys: ["j"], run }),
+      command({ id: "two", label: "Do it", keys: ["down"], run }),
+    ];
+    expect(commandBarCandidates(cmds)).toHaveLength(1);
+    expect(dedupeCommands(cmds)).toHaveLength(1);
+  });
+
+  it("matches on the label only, never on the chord", () => {
+    const candidates = commandBarCandidates([command({ label: "Show help", keys: ["ctrl-q"] })]);
+    expect(barRows("ctrlq", candidates)).toEqual([]);
+    expect(barRows("show", candidates)).toHaveLength(1);
+  });
+});
+
+describe("directory candidates", () => {
+  it("abbreviates the path it shows and keeps the one it spawns in", () => {
+    const candidate = directoryCandidate("/home/me/dev/api", "/home/me");
+    expect(candidate.fields.path).toBe("~/dev/api");
+    expect(candidate.path).toBe("/home/me/dev/api");
+  });
+
+  it("expands a typed `~` and dedupes by the directory spawned in", () => {
+    const candidates = directoryBarCandidates(
+      ["~/dev/api", "/home/me/dev/api", "", "/srv/x"],
+      "/home/me",
+    );
+    expect(candidates.map((c) => c.path)).toEqual(["/home/me/dev/api", "/srv/x"]);
+  });
+});
+
+describe("the action page's candidates", () => {
+  it("offers no action beyond the three", () => {
+    expect(sessionActionCandidates().map((c) => c.action.id)).toEqual([
+      "kill",
+      "rename",
+      "spawn-similar",
+    ]);
+  });
+});
+
+describe("highlight segments", () => {
+  it("splits the text on the matcher's ranges", () => {
+    expect(highlightSegments("web-search", [[0, 1], [4, 5]])).toEqual([
+      { text: "w", hit: true },
+      { text: "eb-", hit: false },
+      { text: "s", hit: true },
+      { text: "earch", hit: false },
+    ]);
+  });
+});

web/src/components/commandBar/model.ts

@@ -0,0 +1,366 @@
+// The command bar's pure model (docs/COMMAND-BAR.md), lifted from
+// ../../commandBar.ts for the React port (#247): what a candidate is, the
+// order an empty query lists them in, how a query line splits into a sigil and
+// a query, and how a ranked list groups for rendering.
+//
+// Nothing here touches the DOM or the network apart from `loadBarDirectories`,
+// which is the one place the `~` list comes from.
+
+import { listDir, projects as fetchProjects, recentDirs } from "../../api.js";
+import type { Command } from "../../commands.js";
+import { splitPath } from "../../paths.js";
+import { splitCommand } from "../../toolIcon.js";
+import { abbreviateCwd, sessionName, sessionTreePath, type Session } from "../../types.js";
+import {
+  matchAndRank,
+  type CandidateKind,
+  type CommandCandidate,
+  type DirectoryCandidate,
+  type MatchRange,
+  type MatchResult,
+  type SessionCandidate,
+} from "../../utils/matcher.js";
+
+/** A matcher candidate that remembers what it came from, so a result can be
+ *  acted on without a second lookup. The extra property is invisible to the
+ *  matcher, which only ever reads `kind` and `fields`. */
+export type SessionBarCandidate = SessionCandidate & { session: Session };
+export type CommandBarCandidate = CommandCandidate & { command: Command };
+/** `fields.path` is the abbreviated path the operator reads and the matcher
+ *  ranks; `path` is the one a spawn is made in. */
+export type DirectoryBarCandidate = DirectoryCandidate & { path: string };
+
+/** One row of a session's action page. It is a `command` to the matcher — a
+ *  single `label` field, ranked exactly like a registry command — and carries
+ *  the action it stands for instead of a registry entry. */
+export type ActionBarCandidate = CommandCandidate & { action: SessionAction };
+
+export type BarCandidate =
+  | SessionBarCandidate
+  | CommandBarCandidate
+  | ActionBarCandidate
+  | DirectoryBarCandidate;
+export type BarResult = MatchResult<BarCandidate>;
+
+/** One kind's slice of the ranked list, in rank order. */
+export interface BarGroup<C extends BarCandidate = BarCandidate> {
+  kind: CandidateKind;
+  title: string;
+  results: MatchResult<C>[];
+}
+
+const KIND_TITLES: Record<CandidateKind, string> = {
+  session: "Sessions",
+  command: "Commands",
+  directory: "Directories",
+};
+
+// ---- the sigils ----
+
+export type BarSigil = ">" | "~";
+
+export interface BarQuery {
+  /** The sigil in force, or null for the mixed list. */
+  sigil: BarSigil | null;
+  /** What the matcher sees: everything after a sigil, or the whole query. */
+  query: string;
+}
+
+export const PLACEHOLDERS: Record<"mixed" | BarSigil, string> = {
+  mixed: "Go to a session…",
+  ">": "Run a command…",
+  "~": "Spawn in a directory…",
+};
+
+/** Split a raw query line into its sigil and the query proper.
+ *
+ *  A sigil is only a sigil in first position: `>` or `~` anywhere else is a
+ *  literal query character, which is what a directory query with a second `~`
+ *  in it depends on. Backspacing past a sigil needs no special case either —
+ *  the first character goes and the query is a mixed one again. */
+export function parseBarQuery(raw: string): BarQuery {
+  const first = raw[0];
+  if (first === ">" || first === "~") return { sigil: first, query: raw.slice(1) };
+  return { sigil: null, query: raw };
+}
+
+// ---- the session action page ----
+
+/** The actions a session's action page offers, and no others: the bar picks
+ *  one and hands off to the flow that already implements it
+ *  (docs/COMMAND-BAR.md, "Drill-in"). */
+export type SessionActionId = "kill" | "rename" | "spawn-similar";
+
+export interface SessionAction {
+  id: SessionActionId;
+  label: string;
+}
+
+export const SESSION_ACTIONS: readonly SessionAction[] = [
+  { id: "kill", label: "Kill session" },
+  { id: "rename", label: "Rename session" },
+  { id: "spawn-similar", label: "Spawn similar" },
+];
+
+/** The action page's candidates, in the order above — which is the order an
+ *  empty query lists them in, since the matcher keeps input order. */
+export function sessionActionCandidates(): ActionBarCandidate[] {
+  return SESSION_ACTIONS.map((action) => ({
+    kind: "command",
+    action,
+    fields: { label: action.label },
+  }));
+}
+
+/** Narrow a `command` candidate to an action row. Both share the matcher's
+ *  `command` kind, so what separates them is what they carry. */
+export function isActionCandidate(candidate: BarCandidate): candidate is ActionBarCandidate {
+  return candidate.kind === "command" && "action" in candidate;
+}
+
+// ---- candidates ----
+
+function focusedAt(s: Session): number | null {
+  const stamp = s.last_focused_at;
+  if (typeof stamp !== "string" || stamp === "") return null;
+  const ms = Date.parse(stamp);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+function createdAt(s: Session): number {
+  const ms = Date.parse(s.created_at ?? "");
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+/** The empty-query order (docs/COMMAND-BAR.md, "Empty query"): most recently
+ *  focused first; a session that has never been focused sorts after every
+ *  session that has, most recently created first among those; and a dead
+ *  session sorts after every live one regardless of recency, because a session
+ *  you cannot attach to is not where you just were.
+ *
+ *  This is also the input order for a non-empty query, which is what the
+ *  matcher's last tie-break preserves. */
+export function orderSessionsForBar(sessions: readonly Session[]): Session[] {
+  return [...sessions].sort((a, b) => {
+    const deadA = a.status === "Dead" ? 1 : 0;
+    const deadB = b.status === "Dead" ? 1 : 0;
+    if (deadA !== deadB) return deadA - deadB;
+
+    const focusA = focusedAt(a);
+    const focusB = focusedAt(b);
+    if ((focusA === null) !== (focusB === null)) return focusA === null ? 1 : -1;
+    if (focusA !== null && focusB !== null && focusA !== focusB) return focusB - focusA;
+
+    return createdAt(b) - createdAt(a);
+  });
+}
+
+/** Build one session's candidate: the fields docs/COMMAND-BAR.md's candidate
+ *  table names, with the directory abbreviated the way the sidebar shows it. */
+export function sessionCandidate(s: Session, homeDir?: string): SessionBarCandidate {
+  const treePath = sessionTreePath(s);
+  const directory = treePath ? abbreviateCwd(treePath, homeDir) : undefined;
+  const tool = splitCommand(s.command).tool ?? undefined;
+  return {
+    kind: "session",
+    session: s,
+    fields: {
+      name: sessionName(s),
+      ...(directory ? { directory } : {}),
+      ...(s.command ? { command: s.command } : {}),
+      ...(tool ? { tool } : {}),
+    },
+  };
+}
+
+/** Every session as a candidate, in the empty-query order. */
+export function sessionBarCandidates(
+  sessions: readonly Session[],
+  homeDir?: string,
+): SessionBarCandidate[] {
+  return orderSessionsForBar(sessions).map((s) => sessionCandidate(s, homeDir));
+}
+
+/** Drop the commands that would list twice. Several chords can be bound to one
+ *  action — the registry already carries its aliases on one entry, but nothing
+ *  stops two entries running the same handler, and listed naively that is two
+ *  identical rows. The dedupe is by **action**, never by chord: the chord is
+ *  displayed, so a command with two of them is still one row. */
+export function dedupeCommands(commands: readonly Command[]): Command[] {
+  const seenRun = new Set<Command["run"]>();
+  const seenLabel = new Set<string>();
+  const kept: Command[] = [];
+  for (const command of commands) {
+    if (seenRun.has(command.run) || seenLabel.has(command.label)) continue;
+    seenRun.add(command.run);
+    seenLabel.add(command.label);
+    kept.push(command);
+  }
+  return kept;
+}
+
+/** Every bound command as a candidate, in registry order. Only the label is a
+ *  field: the chord is displayed beside the row, never matched, because
+ *  matching it would make `>` results depend on a user's rebinds. */
+export function commandBarCandidates(commands: readonly Command[]): CommandBarCandidate[] {
+  return dedupeCommands(commands).map((command) => ({
+    kind: "command",
+    command,
+    fields: { label: command.label },
+  }));
+}
+
+/** `~/dev/api` back to `/home/me/dev/api` — the inverse of `abbreviateCwd`, for
+ *  a path the operator typed or `/api/dirs` completed. */
+export function expandHome(path: string, homeDir?: string): string {
+  if (!homeDir) return path;
+  if (path === "~") return homeDir;
+  return path.startsWith("~/") ? `${homeDir}${path.slice(1)}` : path;
+}
+
+export function directoryCandidate(path: string, homeDir?: string): DirectoryBarCandidate {
+  const absolute = expandHome(path, homeDir);
+  return { kind: "directory", path: absolute, fields: { path: abbreviateCwd(absolute, homeDir) } };
+}
+
+/** Candidates for `~`, deduped by the directory they spawn in and keeping the
+ *  first mention of each — recent dirs (newest first) ahead of the project
+ *  list, which is the empty-query order the contract asks for. */
+export function directoryBarCandidates(
+  paths: readonly string[],
+  homeDir?: string,
+): DirectoryBarCandidate[] {
+  const seen = new Set<string>();
+  const out: DirectoryBarCandidate[] = [];
+  for (const path of paths) {
+    if (path === "") continue;
+    const candidate = directoryCandidate(path, homeDir);
+    if (seen.has(candidate.path)) continue;
+    seen.add(candidate.path);
+    out.push(candidate);
+  }
+  return out;
+}
+
+/** The directory list the bar starts from: what the spawn form already knows —
+ *  `GET /api/recent-dirs` and the project list — either alone if the other
+ *  fails. */
+export async function loadBarDirectories(): Promise<string[]> {
+  const [recents, discovered] = await Promise.all([
+    recentDirs()
+      .then((r) => r.dirs.map((d) => d.cwd))
+      .catch(() => [] as string[]),
+    fetchProjects()
+      .then((list) => list.map((p) => p.path))
+      .catch(() => [] as string[]),
+  ]);
+  return [...recents, ...discovered];
+}
+
+/** One directory's children as candidate paths, for filling the `~` list in as
+ *  a path is typed. The directory being listed comes from the query itself. */
+export function dirEntryPaths(dir: string, entries: readonly string[]): string[] {
+  return entries.map((entry) => `${dir}${entry}`);
+}
+
+/** The directory a `~` query names, or `""` when it names none yet. */
+export function probeDir(query: string): string {
+  return splitPath(query).dir;
+}
+
+/** `GET /api/dirs`, in the shape the bar wants it. */
+export function listDirEntries(dir: string): Promise<string[]> {
+  return listDir(dir).then((listing) => listing.entries);
+}
+
+// ---- grouping ----
+
+/** Bucket a ranked list by kind for rendering. Grouping is a rendering of the
+ *  ranking, never a reordering of it: a group holds its matches in rank order,
+ *  and groups appear in the order their best-scoring member does — so the first
+ *  row under the first header is the globally best result. */
+export function barGroups<C extends BarCandidate>(
+  results: readonly MatchResult<C>[],
+): BarGroup<C>[] {
+  const groups: BarGroup<C>[] = [];
+  for (const result of results) {
+    const kind = result.candidate.kind;
+    let group = groups.find((g) => g.kind === kind);
+    if (!group) {
+      group = { kind, title: KIND_TITLES[kind], results: [] };
+      groups.push(group);
+    }
+    group.results.push(result);
+  }
+  return groups;
+}
+
+/** The rows a query produces, flat and in rank order — what the highlight walks
+ *  and what Enter acts on. Headers are labels, not rows, so they are never in
+ *  this list. */
+export function barRows<C extends BarCandidate>(
+  query: string,
+  candidates: readonly C[],
+): MatchResult<C>[] {
+  return matchAndRank(query, candidates);
+}
+
+// ---- row text ----
+
+/** The name line of a row: the session's name, the command's label, or the
+ *  directory's path. */
+export function rowName(candidate: BarCandidate): string {
+  switch (candidate.kind) {
+    case "session":
+      return candidate.fields.name;
+    case "command":
+      return candidate.fields.label;
+    case "directory":
+      return candidate.fields.path;
+  }
+}
+
+/** The secondary line under a session row: the field the match was found in
+ *  when that was not the name, so a session found through its directory says
+ *  so. Only sessions have one — a command shows keycaps instead, and a
+ *  directory's path is already the name. */
+export function metaText(result: BarResult): string | undefined {
+  if (result.candidate.kind !== "session") return undefined;
+  const fields = result.candidate.fields;
+  switch (result.field) {
+    case "directory":
+      return fields.directory;
+    case "command":
+      return fields.command;
+    case "tool":
+      return fields.tool;
+    default:
+      return fields.directory;
+  }
+}
+
+/** One run of a row's text, flagged when the matcher matched inside it. The
+ *  React rendering of `renderHighlighted`: ranges come from the matcher as
+ *  `[start, end)` character pairs over the field that won. */
+export interface HighlightSegment {
+  text: string;
+  hit: boolean;
+}
+
+export function highlightSegments(
+  text: string,
+  ranges: readonly MatchRange[],
+): HighlightSegment[] {
+  const out: HighlightSegment[] = [];
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    if (start > cursor) out.push({ text: text.slice(cursor, start), hit: false });
+    out.push({ text: text.slice(start, end), hit: true });
+    cursor = end;
+  }
+  if (cursor < text.length) out.push({ text: text.slice(cursor), hit: false });
+  return out;
+}
+
+export { sessionName };
+export type { CandidateKind, MatchRange, MatchResult };

web/src/components/commandBar/useCommandBar.test.tsx

@@ -0,0 +1,76 @@
+// @vitest-environment happy-dom
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { OPEN_COMMAND_BAR_EVENT } from "../../uiEvents.js";
+import { useCommandBar, type UseCommandBarOptions } from "./useCommandBar.js";
+
+let controls: ReturnType<typeof useCommandBar>;
+
+function Probe(opts: UseCommandBarOptions) {
+  controls = useCommandBar(opts);
+  return <div>{controls.open ? "open" : "closed"}</div>;
+}
+
+function ctrlK(target: EventTarget = window): void {
+  act(() => {
+    target.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "k", ctrlKey: true, bubbles: true, cancelable: true }),
+    );
+  });
+}
+
+afterEach(cleanup);
+
+describe("useCommandBar", () => {
+  it("opens on ctrl-k, from the capture phase so an attached xterm never sees it", () => {
+    const view = render(<Probe />);
+    ctrlK();
+    expect(view.container.textContent).toBe("open");
+  });
+
+  it("stays deaf while the bar is already up — its own input owns the keys", () => {
+    const onOpen = vi.fn();
+    render(<Probe onOpen={onOpen} />);
+    ctrlK();
+    ctrlK();
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves a form field's own Ctrl-K alone", () => {
+    const field = document.createElement("input");
+    document.body.appendChild(field);
+    const view = render(<Probe />);
+    ctrlK(field);
+    expect(view.container.textContent).toBe("closed");
+    field.remove();
+  });
+
+  it("opens from the sidebar's search field, the touch entry point", () => {
+    const view = render(<Probe />);
+    act(() => {
+      document.dispatchEvent(new CustomEvent(OPEN_COMMAND_BAR_EVENT));
+    });
+    expect(view.container.textContent).toBe("open");
+  });
+
+  it("runs the caller's hook before opening, so a preview is discarded first", () => {
+    const onOpen = vi.fn();
+    render(<Probe onOpen={onOpen} />);
+    ctrlK();
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes on demand", () => {
+    const view = render(<Probe />);
+    ctrlK();
+    act(() => controls.closeBar());
+    expect(view.container.textContent).toBe("closed");
+  });
+
+  it("binds nothing while disabled — another overlay owns the keyboard", () => {
+    const view = render(<Probe enabled={false} />);
+    ctrlK();
+    expect(view.container.textContent).toBe("closed");
+  });
+});

web/src/components/commandBar/useCommandBar.ts

@@ -0,0 +1,65 @@
+// Opening and closing the bar (docs/COMMAND-BAR.md, "Opening"). `ctrl-k` is a
+// registry command like any other, so the `?` overlay lists it without a
+// second list; the touch entry point — the sidebar's search field — raises
+// `OPEN_COMMAND_BAR_EVENT` and lands on the same open.
+
+import { useCallback, useEffect, useState } from "react";
+
+import { OPEN_COMMAND_BAR_EVENT } from "../../uiEvents.js";
+import { CommandSet, defineCommands, isBarTypingTarget } from "../../commands.js";
+
+export interface UseCommandBarOptions {
+  /** Run before the bar opens — the shell discards a preview here, since the
+   * bar is not previewed into (docs/PREVIEW.md). */
+  onOpen?(): void;
+  /** Off while another overlay owns the keyboard (the restart overlay, the
+   * help dialog). Defaults to on. */
+  enabled?: boolean;
+}
+
+export interface CommandBarControls {
+  open: boolean;
+  openBar(): void;
+  closeBar(): void;
+}
+
+export function useCommandBar(opts: UseCommandBarOptions = {}): CommandBarControls {
+  const { onOpen, enabled = true } = opts;
+  const [open, setOpen] = useState(false);
+
+  const openBar = useCallback(() => {
+    onOpen?.();
+    setOpen(true);
+  }, [onOpen]);
+
+  const closeBar = useCallback(() => setOpen(false), []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const keys = new CommandSet(defineCommands({ "bar.open": openBar }));
+
+    // Capture phase: an attached xterm swallows every keystroke it is given, so
+    // the bar's binding has to be seen ahead of the terminal.
+    const onKeydown = (e: KeyboardEvent) => {
+      // The bar owns the keyboard while it is up; its own input handles the keys.
+      if (open) return;
+      // The pane's hidden textarea is not a typing target for the bar: ctrl-k
+      // is seen ahead of xterm and opens the bar. A real form field — the spawn
+      // form's inputs — keeps its own Ctrl+K.
+      if (isBarTypingTarget(e.target)) return;
+      keys.handle(e);
+    };
+    const onTouchEntry = () => {
+      if (!open) openBar();
+    };
+
+    window.addEventListener("keydown", onKeydown, true);
+    document.addEventListener(OPEN_COMMAND_BAR_EVENT, onTouchEntry);
+    return () => {
+      window.removeEventListener("keydown", onKeydown, true);
+      document.removeEventListener(OPEN_COMMAND_BAR_EVENT, onTouchEntry);
+    };
+  }, [enabled, open, openBar]);
+
+  return { open, openBar, closeBar };
+}

web/src/components/common/ContextMenu.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ContextMenu } from "./ContextMenu.js";
+
+afterEach(() => {
+  cleanup();
+});
+
+function labels(): string[] {
+  return [...document.querySelectorAll(".context-menu-item")].map((b) => b.textContent ?? "");
+}
+
+describe("ContextMenu (#125)", () => {
+  it("renders one item per entry, in order", () => {
+    render(
+      <ContextMenu
+        x={10}
+        y={20}
+        items={[
+          { label: "Rename…", onSelect: () => {} },
+          { label: "Kill session", onSelect: () => {}, danger: true },
+        ]}
+        onClose={vi.fn()}
+      />,
+    );
+    expect(labels()).toEqual(["Rename…", "Kill session"]);
+    expect(document.querySelector(".context-menu-item.is-danger")?.textContent).toBe("Kill session");
+  });
+
+  it("runs the selected entry and closes", () => {
+    const chosen = vi.fn();
+    const onClose = vi.fn();
+    render(<ContextMenu x={0} y={0} items={[{ label: "Rename…", onSelect: chosen }]} onClose={onClose} />);
+    fireEvent.click(screen.getByRole("menuitem"));
+    expect(chosen).toHaveBeenCalledOnce();
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("closes on Escape and on a press outside it", () => {
+    const onClose = vi.fn();
+    render(<ContextMenu x={0} y={0} items={[{ label: "Rename…", onSelect: () => {} }]} onClose={onClose} />);
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    fireEvent(document.body, new Event("pointerdown", { bubbles: true }));
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it("stays open for a press inside itself", () => {
+    const onClose = vi.fn();
+    render(<ContextMenu x={0} y={0} items={[{ label: "Rename…", onSelect: () => {} }]} onClose={onClose} />);
+    const menu = document.querySelector(".context-menu") as HTMLElement;
+    fireEvent(menu, new Event("pointerdown", { bubbles: true }));
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes on scroll and on resize", () => {
+    const onClose = vi.fn();
+    render(<ContextMenu x={0} y={0} items={[{ label: "Rename…", onSelect: () => {} }]} onClose={onClose} />);
+    fireEvent.scroll(window);
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    fireEvent.resize(window);
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+});

web/src/components/common/ContextMenu.tsx

@@ -0,0 +1,86 @@
+// React port of ../../contextMenu.ts (#125), the general-purpose version —
+// unlike the sidebar's own menu, this one also closes on scroll/resize, since
+// a menu anchored to coordinates goes stale the moment the page moves under it.
+
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+export interface ContextMenuItem {
+  label: string;
+  onSelect(): void;
+  /** Renders the entry in the destructive style. */
+  danger?: boolean;
+}
+
+export interface ContextMenuProps {
+  x: number;
+  y: number;
+  items: ContextMenuItem[];
+  onClose(): void;
+}
+
+export function ContextMenu({ x, y, items, onClose }: ContextMenuProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [pos, setPos] = useState({ left: x, top: y });
+
+  // Nudge back inside the viewport once the menu has a measurable size.
+  useLayoutEffect(() => {
+    const rect = ref.current?.getBoundingClientRect();
+    if (!rect) return;
+    const maxX = window.innerWidth - rect.width;
+    const maxY = window.innerHeight - rect.height;
+    setPos({ left: Math.max(0, Math.min(x, maxX)), top: Math.max(0, Math.min(y, maxY)) });
+  }, [x, y]);
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    const onPointerDown = (e: Event) => {
+      if (!ref.current?.contains(e.target as Node)) onClose();
+    };
+    document.addEventListener("keydown", onKeyDown, true);
+    window.addEventListener("pointerdown", onPointerDown, true);
+    window.addEventListener("scroll", onClose, true);
+    window.addEventListener("resize", onClose);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown, true);
+      window.removeEventListener("pointerdown", onPointerDown, true);
+      window.removeEventListener("scroll", onClose, true);
+      window.removeEventListener("resize", onClose);
+    };
+  }, [onClose]);
+
+  useEffect(() => {
+    (ref.current?.firstElementChild as HTMLElement | null)?.focus();
+  }, []);
+
+  return createPortal(
+    <div
+      ref={ref}
+      role="menu"
+      className="context-menu fixed z-modal min-w-[160px] rounded-r-2 border border-border-strong bg-surface py-sp-1 shadow-2"
+      style={{ left: pos.left, top: pos.top }}
+    >
+      {items.map((item) => (
+        <button
+          key={item.label}
+          type="button"
+          role="menuitem"
+          className={`context-menu-item block w-full px-sp-3 py-sp-1 text-left text-fs-12 hover:bg-surface-2 ${
+            item.danger ? "is-danger text-danger" : "text-ink"
+          }`}
+          onClick={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            onClose();
+            item.onSelect();
+          }}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>,
+    document.body,
+  );
+}

web/src/components/common/index.ts

@@ -0,0 +1 @@
+export { ContextMenu, type ContextMenuItem, type ContextMenuProps } from "./ContextMenu.js";

web/src/components/daemon/DaemonLink.test.ts

@@ -1,8 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 
-import { DaemonLink, compareIdentity, formatRelease } from "./daemonLink.js";
-import type { Scheduler } from "./events.js";
-import type { DaemonInfo } from "./types.js";
+import { GRACE_MS, POLL_MS, compareIdentity, createDaemonLinkStore, formatRelease, type Scheduler } from "./DaemonLink.js";
+import type { DaemonInfo } from "../../types.js";
 
 function info(commit: string, instance: string, date = "2026-09-02T14:03:11+01:00"): DaemonInfo {
   return {
@@ -14,14 +13,18 @@ function info(commit: string, instance: string, date = "2026-09-02T14:03:11+01:0
   };
 }
 
-/** Scheduler whose timers only fire when the test says so. */
-function manual(): Scheduler & { run(): void; pending(): number } {
+/** Scheduler whose timers only fire when the test says so, recording the
+ *  delay each was scheduled with. */
+function manual(): Scheduler & { run(): void; pending(): number; delays: number[] } {
   let next = 1;
   const timers = new Map<number, () => void>();
+  const delays: number[] = [];
   return {
-    setTimer(fn) {
+    delays,
+    setTimer(fn, ms) {
       const h = next++;
       timers.set(h, fn);
+      delays.push(ms);
       return h;
     },
     clearTimer(h) {
@@ -73,21 +76,22 @@ describe("formatRelease", () => {
   });
 });
 
-describe("DaemonLink", () => {
-  it("starts online once the first probe lands", async () => {
-    const link = new DaemonLink({
+describe("daemon link store", () => {
+  it("starts in the connecting state until the first probe lands", async () => {
+    const store = createDaemonLinkStore({
       fetchInfo: async () => info("aaa", "i1"),
       scheduler: manual(),
       reload: () => {},
     });
-    await link.start();
-    expect(link.status().state).toBe("online");
-    expect(link.status().build?.commit).toBe("aaa");
+    expect(store.getState().state).toBe("connecting");
+    await store.getState().probe();
+    expect(store.getState().state).toBe("online");
+    expect(store.getState().build?.commit).toBe("aaa");
   });
 
   it("holds the modal back during the grace period, then blocks", async () => {
     const sched = manual();
-    const link = new DaemonLink({
+    const store = createDaemonLinkStore({
       fetchInfo: async () => {
         throw new Error("down");
       },
@@ -95,19 +99,19 @@ describe("DaemonLink", () => {
       reload: () => {},
       graceMs: 1000,
     });
-    link.noteDisconnected();
+    store.getState().noteDisconnected();
     // Still inside the grace window: the dot goes amber, nothing blocks.
-    expect(link.status().state).toBe("reconnecting");
+    expect(store.getState().state).toBe("reconnecting");
     sched.run();
     await Promise.resolve();
-    expect(link.status().state).toBe("down");
+    expect(store.getState().state).toBe("down");
   });
 
   it("unlocks without reloading when the same build comes back", async () => {
     const sched = manual();
     const reload = vi.fn();
     let reply: DaemonInfo | null = info("aaa", "i1");
-    const link = new DaemonLink({
+    const store = createDaemonLinkStore({
       fetchInfo: async () => {
         if (!reply) throw new Error("down");
         return reply;
@@ -115,70 +119,45 @@ describe("DaemonLink", () => {
       scheduler: sched,
       reload,
     });
-    await link.start();
+    await store.getState().probe();
 
     reply = null;
-    link.noteDisconnected();
+    store.getState().noteDisconnected();
     sched.run(); // grace expires → blocked, poll scheduled
     await Promise.resolve();
-    expect(link.status().state).toBe("down");
+    expect(store.getState().state).toBe("down");
 
     // Same commit, new process: a restart, not an upgrade — the page stays.
     reply = info("aaa", "i2");
-    await link.probe();
+    await store.getState().probe();
     expect(reload).not.toHaveBeenCalled();
-    expect(link.status().state).toBe("online");
-  });
-
-  it("rechecks immediately when the browser returns from the background", async () => {
-    const sched = manual();
-    let reply: DaemonInfo | null = info("aaa", "i1");
-    const link = new DaemonLink({
-      fetchInfo: async () => {
-        if (!reply) throw new Error("down");
-        return reply;
-      },
-      scheduler: sched,
-      reload: () => {},
-    });
-    await link.start();
-
-    reply = null;
-    link.noteDisconnected();
-    sched.run();
-    await Promise.resolve();
-    expect(link.status().state).toBe("down");
-
-    reply = info("aaa", "i1");
-    link.recover();
-    await Promise.resolve();
-    expect(link.status().state).toBe("online");
+    expect(store.getState().state).toBe("online");
   });
 
   it("reloads the page when the daemon comes back on a new commit", async () => {
     const sched = manual();
     const reload = vi.fn();
     let reply = info("aaa", "i1");
-    const link = new DaemonLink({
+    const store = createDaemonLinkStore({
       fetchInfo: async () => reply,
       scheduler: sched,
       reload,
     });
-    await link.start();
+    await store.getState().probe();
 
-    link.noteDisconnected();
+    store.getState().noteDisconnected();
     reply = info("bbb", "i2");
-    await link.probe();
+    await store.getState().probe();
     expect(reload).toHaveBeenCalledTimes(1);
     // Left blocked deliberately: the reload is what ends this page's life, and
     // flashing an unlocked UI in between would let the user act on stale code.
-    expect(link.status().state).toBe("updating");
+    expect(store.getState().state).toBe("updating");
   });
 
   it("keeps polling on a scheduled cadence while the daemon is unreachable", async () => {
     const sched = manual();
     let attempts = 0;
-    const link = new DaemonLink({
+    const store = createDaemonLinkStore({
       fetchInfo: async () => {
         attempts += 1;
         throw new Error("down");
@@ -186,7 +165,7 @@ describe("DaemonLink", () => {
       scheduler: sched,
       reload: () => {},
     });
-    link.noteDisconnected();
+    store.getState().noteDisconnected();
     sched.run(); // grace → first poll
     await Promise.resolve();
     await Promise.resolve();
@@ -196,23 +175,41 @@ describe("DaemonLink", () => {
     await Promise.resolve();
     await Promise.resolve();
     expect(attempts).toBeGreaterThan(first);
-    link.stop();
+    store.getState().stop();
   });
 
   it("notifies subscribers on every state change", async () => {
     const sched = manual();
     const seen: string[] = [];
-    const link = new DaemonLink({
+    const store = createDaemonLinkStore({
       fetchInfo: async () => info("aaa", "i1"),
       scheduler: sched,
       reload: () => {},
     });
-    link.subscribe((s) => seen.push(s.state));
-    await link.start();
-    link.noteDisconnected();
+    store.subscribe((s) => seen.push(s.state));
+    await store.getState().probe();
+    store.getState().noteDisconnected();
     sched.run();
     await Promise.resolve();
     expect(seen).toContain("reconnecting");
-    expect(seen[0]).toBe("connecting");
+  });
+
+  it("schedules the grace timer and poll at the documented defaults", async () => {
+    const sched = manual();
+    const store = createDaemonLinkStore({
+      fetchInfo: async () => {
+        throw new Error("down");
+      },
+      scheduler: sched,
+      reload: () => {},
+    });
+    expect(GRACE_MS).toBe(1200);
+    expect(POLL_MS).toBe(700);
+    store.getState().noteDisconnected();
+    expect(sched.delays).toEqual([GRACE_MS]);
+    sched.run(); // grace fires → schedules the first poll
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(sched.delays).toEqual([GRACE_MS, POLL_MS]);
   });
 });

web/src/components/daemon/DaemonLink.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment happy-dom
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createDaemonLinkStore } from "./DaemonLink.js";
+import { DaemonLink } from "./DaemonLink.js";
+
+afterEach(() => cleanup());
+
+describe("DaemonLink", () => {
+  it("probes once on mount, regardless of the initial connected value", async () => {
+    const fetchInfo = vi.fn().mockResolvedValue({ hostname: "h", version: "1", presets: [] });
+    const store = createDaemonLinkStore({ fetchInfo, scheduler: { setTimer: () => 0, clearTimer: () => {} } });
+    render(<DaemonLink store={store} connected={false} />);
+    await Promise.resolve();
+    expect(fetchInfo).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not treat the initial connected value as a transition", async () => {
+    const store = createDaemonLinkStore({
+      fetchInfo: async () => ({ hostname: "h", version: "1", presets: [] }),
+      scheduler: { setTimer: () => 0, clearTimer: () => {} },
+    });
+    render(<DaemonLink store={store} connected={true} />);
+    await Promise.resolve();
+    // Only the mount probe ran — no extra noteConnected() probe on top of it.
+    expect(store.getState().state).toBe("online");
+  });
+
+  it("forwards a later connected drop to noteDisconnected", async () => {
+    const store = createDaemonLinkStore({
+      fetchInfo: async () => ({ hostname: "h", version: "1", presets: [] }),
+      scheduler: { setTimer: () => 0, clearTimer: () => {} },
+    });
+    const { rerender } = render(<DaemonLink store={store} connected={true} />);
+    await Promise.resolve();
+    expect(store.getState().state).toBe("online");
+
+    rerender(<DaemonLink store={store} connected={false} />);
+    expect(store.getState().state).toBe("reconnecting");
+  });
+
+  it("forwards a later connected recovery to noteConnected", async () => {
+    const fetchInfo = vi.fn().mockResolvedValue({ hostname: "h", version: "1", presets: [] });
+    const store = createDaemonLinkStore({ fetchInfo, scheduler: { setTimer: () => 0, clearTimer: () => {} } });
+    const { rerender } = render(<DaemonLink store={store} connected={true} />);
+    await Promise.resolve();
+    expect(store.getState().state).toBe("online");
+
+    // The socket dropped: noteDisconnected() moves off "online" so the coming
+    // recovery isn't a no-op.
+    rerender(<DaemonLink store={store} connected={false} />);
+    expect(store.getState().state).toBe("reconnecting");
+    fetchInfo.mockClear();
+
+    rerender(<DaemonLink store={store} connected={true} />);
+    await Promise.resolve();
+    expect(fetchInfo).toHaveBeenCalledTimes(1);
+    expect(store.getState().state).toBe("online");
+  });
+
+  it("stops the store's polling on unmount", () => {
+    const store = createDaemonLinkStore({
+      fetchInfo: async () => ({ hostname: "h", version: "1", presets: [] }),
+    });
+    const stop = vi.spyOn(store.getState(), "stop");
+    const { unmount } = render(<DaemonLink store={store} connected={false} />);
+    unmount();
+    expect(stop).toHaveBeenCalledTimes(1);
+  });
+});

web/src/components/daemon/DaemonLink.tsx

@@ -0,0 +1,234 @@
+// React port of ../../daemonLink.ts. The link to the daemon behind this page:
+// is it up, and which release is it? `RestartOverlay` (./RestartOverlay.tsx)
+// renders what this reports. See docs/RESTART.md for the restart contract.
+
+import { useEffect, useRef } from "react";
+import { create } from "zustand";
+
+import { getDaemonInfo } from "../../api.js";
+import type { BuildInfo, DaemonInfo } from "../../types.js";
+
+/**
+ * - `connecting` — first probe hasn't landed yet.
+ * - `online` — the daemon answered and is the same process, or a resolved new one.
+ * - `reconnecting` — the socket dropped, but within the grace window; a blip
+ *   shouldn't throw a modal in the user's face.
+ * - `down` — unreachable past the grace window: the overlay blocks the UI and
+ *   the poll runs until it answers.
+ * - `updating` — it answered on a different commit; the page is reloading and
+ *   stays blocked until it does.
+ */
+export type LinkState = "connecting" | "online" | "reconnecting" | "down" | "updating";
+
+/** What happened between two `/api/info` replies. */
+export type RestartKind = "same" | "restarted" | "upgraded";
+
+/** How long a dropped socket may stay dropped before the UI blocks. Long enough
+ *  to ride out a wifi hiccup, short enough that a real restart is visible. */
+export const GRACE_MS = 1200;
+/** Cadence of the `/api/info` poll while the daemon is unreachable. */
+export const POLL_MS = 700;
+
+/**
+ * Compare two daemon replies.
+ *
+ * The commit decides first: a different one means new code, which for a browser
+ * means new assets. The per-process `instance` catches the rest — a restart of
+ * the same build, which needs no reload. A daemon built outside a git checkout
+ * reports an empty commit, so an empty-vs-empty pair never counts as an
+ * upgrade; the instance still reports the restart.
+ */
+export function compareIdentity(before: DaemonInfo, after: DaemonInfo): RestartKind {
+  const a = before.build?.commit ?? "";
+  const b = after.build?.commit ?? "";
+  if (a && b && a !== b) return "upgraded";
+  if (before.instance && after.instance && before.instance !== after.instance) return "restarted";
+  return "same";
+}
+
+/** One line naming a release: `f89be4a716c7 · 2026-09-02`, with `(dirty)` when
+ *  the build carried uncommitted changes. Empty builds say so rather than
+ *  rendering a blank tooltip. */
+export function formatRelease(build: BuildInfo | undefined): string {
+  if (!build?.commit) return "unknown release";
+  const day = build.commit_date ? build.commit_date.slice(0, 10) : "";
+  const parts = [build.commit];
+  if (day) parts.push(`· ${day}`);
+  if (build.dirty) parts.push("(dirty)");
+  return parts.join(" ");
+}
+
+/** Schedules a probe/grace timer; returns a handle `clearTimer` understands. */
+export interface Scheduler {
+  setTimer(fn: () => void, ms: number): number;
+  clearTimer(handle: number): void;
+}
+
+const browserScheduler: Scheduler = {
+  setTimer: (fn, ms) => window.setTimeout(fn, ms),
+  clearTimer: (h) => window.clearTimeout(h),
+};
+
+export interface DaemonLinkState {
+  state: LinkState;
+  /** The release the daemon last reported. Undefined until the first probe,
+   *  and on a daemon too old to carry one. */
+  build?: BuildInfo;
+  /** Hostname the daemon reports, for the indicator's tooltip. */
+  hostname?: string;
+  /** How many probes have failed in the current outage — the overlay counts
+   *  attempts so a long restart doesn't look frozen. */
+  attempts: number;
+}
+
+export interface DaemonLinkActions {
+  /** One `/api/info` round-trip. Resolves `true` when the daemon answered. */
+  probe(): Promise<boolean>;
+  /** The events socket dropped. Starts the grace timer and the poll. */
+  noteDisconnected(): void;
+  /** The events socket came back. It carries no identity of its own, so the
+   *  state only clears once a probe confirms *which* daemon answered — a
+   *  reconnect to an upgraded daemon must reload, not resume. */
+  noteConnected(): void;
+  /** Stop polling. */
+  stop(): void;
+}
+
+export type DaemonLinkStore = DaemonLinkState & DaemonLinkActions;
+
+export interface DaemonLinkOptions {
+  /** Injectable for tests; defaults to `GET /api/info`. */
+  fetchInfo?: () => Promise<DaemonInfo>;
+  scheduler?: Scheduler;
+  /** What an upgrade does. Injectable so tests don't navigate. */
+  reload?: () => void;
+  graceMs?: number;
+  pollMs?: number;
+}
+
+/** Builds an isolated daemon-link store — same shape as
+ *  {@link ../../stores/catalogStore.js!createCatalogStore}: both a React hook
+ *  and a plain object (`getState`/`subscribe`), so it drives the overlay
+ *  whether or not React is the one calling `noteConnected`/`noteDisconnected`. */
+export function createDaemonLinkStore(opts: DaemonLinkOptions = {}) {
+  const fetchInfo = opts.fetchInfo ?? getDaemonInfo;
+  const scheduler = opts.scheduler ?? browserScheduler;
+  const reload = opts.reload ?? (() => window.location.reload());
+  const graceMs = opts.graceMs ?? GRACE_MS;
+  const pollMs = opts.pollMs ?? POLL_MS;
+
+  let identity: DaemonInfo | null = null;
+  let graceTimer: number | null = null;
+  let pollTimer: number | null = null;
+
+  return create<DaemonLinkStore>((set, get) => {
+    function clearTimers(): void {
+      if (graceTimer !== null) {
+        scheduler.clearTimer(graceTimer);
+        graceTimer = null;
+      }
+      if (pollTimer !== null) {
+        scheduler.clearTimer(pollTimer);
+        pollTimer = null;
+      }
+    }
+
+    async function probe(): Promise<boolean> {
+      let info: DaemonInfo;
+      try {
+        info = await fetchInfo();
+      } catch {
+        set((s) => ({ attempts: s.attempts + 1 }));
+        return false;
+      }
+      const before = identity;
+      identity = info;
+      if (before && compareIdentity(before, info) === "upgraded") {
+        // Stay blocked through the reload: an unlocked frame here would let the
+        // user drive new server code from the bundle it just replaced.
+        set({ state: "updating", build: info.build, hostname: info.hostname });
+        reload();
+        return true;
+      }
+      clearTimers();
+      set({ state: "online", build: info.build, hostname: info.hostname, attempts: 0 });
+      return true;
+    }
+
+    async function poll(): Promise<void> {
+      const state = get().state;
+      if (state === "online" || state === "updating") return;
+      const ok = await probe();
+      if (ok || pollTimer !== null) return;
+      pollTimer = scheduler.setTimer(() => {
+        pollTimer = null;
+        void poll();
+      }, pollMs);
+    }
+
+    return {
+      state: "connecting",
+      build: undefined,
+      hostname: undefined,
+      attempts: 0,
+
+      probe,
+
+      noteDisconnected() {
+        const state = get().state;
+        if (state === "down" || state === "updating") return;
+        set({ state: "reconnecting", attempts: 0 });
+        if (graceTimer === null) {
+          graceTimer = scheduler.setTimer(() => {
+            graceTimer = null;
+            if (get().state === "reconnecting") set({ state: "down" });
+            void poll();
+          }, graceMs);
+        }
+      },
+
+      noteConnected() {
+        const state = get().state;
+        if (state === "online" || state === "updating") return;
+        void probe();
+      },
+
+      stop: clearTimers,
+    };
+  });
+}
+
+export type DaemonLinkStoreApi = ReturnType<typeof createDaemonLinkStore>;
+
+export interface DaemonLinkProps {
+  /** The link store this instance drives — `RestartOverlay` (and, later, the
+   *  sidebar's status indicator) read the same one. */
+  store: DaemonLinkStoreApi;
+  /** The catalog store's `connected` field (docs/RESTART.md): the events
+   *  socket dying is the earliest signal a restart happened, ahead of any
+   *  poll. Pass `useStore(catalogStore, (s) => s.connected)`. */
+  connected: boolean;
+}
+
+/**
+ * Renders nothing — the controller that wires a `DaemonLinkStore` to the
+ * catalog's socket state. Mount once near the app root; `RestartOverlay`
+ * reads the store it drives.
+ */
+export function DaemonLink({ store, connected }: DaemonLinkProps): null {
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      void store.getState().probe();
+      return;
+    }
+    if (connected) store.getState().noteConnected();
+    else store.getState().noteDisconnected();
+  }, [store, connected]);
+
+  useEffect(() => () => store.getState().stop(), [store]);
+
+  return null;
+}

web/src/components/daemon/RestartOverlay.test.tsx

@@ -0,0 +1,78 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createDaemonLinkStore, type DaemonLinkStoreApi } from "./DaemonLink.js";
+import { RestartOverlay } from "./RestartOverlay.js";
+
+afterEach(() => cleanup());
+
+function storeAt(state: "connecting" | "online" | "reconnecting" | "down" | "updating"): DaemonLinkStoreApi {
+  const store = createDaemonLinkStore({ scheduler: { setTimer: () => 0, clearTimer: () => {} } });
+  store.setState({ state });
+  return store;
+}
+
+describe("RestartOverlay", () => {
+  it("renders nothing while connecting, online, or reconnecting", () => {
+    for (const state of ["connecting", "online", "reconnecting"] as const) {
+      const { unmount } = render(<RestartOverlay store={storeAt(state)} />);
+      expect(screen.queryByRole("alertdialog")).toBeNull();
+      unmount();
+    }
+  });
+
+  it("blocks with a restarting message when down", () => {
+    render(<RestartOverlay store={storeAt("down")} />);
+    const dialog = screen.getByRole("alertdialog");
+    expect(dialog.textContent).toContain("Maestro is restarting");
+    expect(dialog.textContent).toContain("Waiting for the daemon to come back…");
+  });
+
+  it("counts attempts once more than one probe has failed", () => {
+    const store = storeAt("down");
+    store.setState({ attempts: 3 });
+    render(<RestartOverlay store={store} />);
+    expect(screen.getByRole("alertdialog").textContent).toContain("(3 attempts)");
+  });
+
+  it("says it is reloading when updating", () => {
+    render(<RestartOverlay store={storeAt("updating")} />);
+    const dialog = screen.getByRole("alertdialog");
+    expect(dialog.textContent).toContain("Maestro was updated");
+    expect(dialog.textContent).toContain("Reloading this page onto the new release…");
+  });
+
+  it("names the release from the store's build", () => {
+    const store = storeAt("down");
+    store.setState({ build: { commit: "f89be4a", commit_date: "2026-09-02T00:00:00Z", dirty: false } });
+    render(<RestartOverlay store={store} />);
+    expect(screen.getByRole("alertdialog").textContent).toContain("f89be4a · 2026-09-02");
+  });
+
+  it("clears the moment the store reports the link is back", () => {
+    const store = storeAt("down");
+    const { rerender } = render(<RestartOverlay store={store} />);
+    expect(screen.queryByRole("alertdialog")).not.toBeNull();
+    store.setState({ state: "online" });
+    rerender(<RestartOverlay store={store} />);
+    expect(screen.queryByRole("alertdialog")).toBeNull();
+  });
+
+  it("swallows keyboard shortcuts while blocking, but not once cleared", () => {
+    const store = storeAt("down");
+    const handler = vi.fn();
+    window.addEventListener("keydown", handler);
+    const { rerender } = render(<RestartOverlay store={store} />);
+
+    fireEvent.keyDown(window, { key: "n" });
+    expect(handler).not.toHaveBeenCalled();
+
+    store.setState({ state: "online" });
+    rerender(<RestartOverlay store={store} />);
+    fireEvent.keyDown(window, { key: "n" });
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    window.removeEventListener("keydown", handler);
+  });
+});

web/src/components/daemon/RestartOverlay.tsx

@@ -0,0 +1,62 @@
+// React port of ../../restartOverlay.ts. Blocking overlay for a daemon that
+// went away — see docs/RESTART.md.
+//
+// Rendered while the link is `down` or `updating`, gone the moment it is
+// back. It owns no polling of its own: `DaemonLink` polls, this only renders
+// what the store reports.
+
+import { useEffect } from "react";
+import { useStore } from "zustand";
+
+import { formatRelease, type DaemonLinkStoreApi } from "./DaemonLink.js";
+
+export interface RestartOverlayProps {
+  /** The same store a sibling `DaemonLink` drives. */
+  store: DaemonLinkStoreApi;
+}
+
+/** The poll runs while this is up; saying how many tries have gone by is what
+ *  separates "still restarting" from "wedged" for someone staring at it. */
+function attemptText(attempts: number): string {
+  if (attempts <= 1) return "Waiting for the daemon to come back…";
+  return `Waiting for the daemon to come back… (${attempts} attempts)`;
+}
+
+function swallow(e: KeyboardEvent): void {
+  e.stopImmediatePropagation();
+}
+
+export function RestartOverlay({ store }: RestartOverlayProps) {
+  const state = useStore(store, (s) => s.state);
+  const build = useStore(store, (s) => s.build);
+  const attempts = useStore(store, (s) => s.attempts);
+
+  const blocking = state === "down" || state === "updating";
+
+  // The app's shortcuts live on `window`, so hiding the UI behind a backdrop
+  // does not stop them: `n` would still open a spawn form against a daemon
+  // that is not there. Swallow keys in the capture phase until the link is
+  // back, without `preventDefault` so the browser's own chords still work.
+  useEffect(() => {
+    if (!blocking) return;
+    window.addEventListener("keydown", swallow, true);
+    return () => window.removeEventListener("keydown", swallow, true);
+  }, [blocking]);
+
+  if (!blocking) return null;
+
+  const updating = state === "updating";
+
+  return (
+    <div className="modal-backdrop restart-backdrop">
+      <div className="modal restart-modal" role="alertdialog" aria-modal="true" aria-labelledby="restart-title">
+        <div className="restart-spinner" aria-hidden="true" />
+        <h2 id="restart-title">{updating ? "Maestro was updated" : "Maestro is restarting"}</h2>
+        <p className="restart-detail">
+          {updating ? "Reloading this page onto the new release…" : attemptText(attempts)}
+        </p>
+        <p className="restart-release">{formatRelease(build)}</p>
+      </div>
+    </div>
+  );
+}

web/src/components/dialogs/HelpOverlay.test.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { keyCaps } from "../../commands.js";
+import { groupedCommands } from "./model.js";
+import { HelpOverlay } from "./HelpOverlay.js";
+
+afterEach(() => {
+  cleanup();
+});
+
+function press(key: string, init: KeyboardEventInit = {}): void {
+  fireEvent.keyDown(window, { key, ...init });
+}
+
+describe("HelpOverlay", () => {
+  it("opens on ? and closes on a second ?", () => {
+    render(<HelpOverlay />);
+    expect(screen.queryByRole("dialog")).toBeNull();
+    press("?", { shiftKey: true });
+    expect(screen.queryByRole("dialog")).not.toBeNull();
+    press("?", { shiftKey: true });
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("ignores ? while typing and when a non-shift modifier is held", () => {
+    render(<HelpOverlay />);
+    const input = document.createElement("input");
+    document.body.appendChild(input);
+    fireEvent.keyDown(input, { key: "?", shiftKey: true });
+    expect(screen.queryByRole("dialog")).toBeNull();
+
+    press("?", { ctrlKey: true });
+    expect(screen.queryByRole("dialog")).toBeNull();
+    input.remove();
+  });
+
+  it("closes on Escape, on the close button, and on a click outside the panel", () => {
+    render(<HelpOverlay />);
+
+    press("?", { shiftKey: true });
+    press("Escape");
+    expect(screen.queryByRole("dialog")).toBeNull();
+
+    press("?", { shiftKey: true });
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(screen.queryByRole("dialog")).toBeNull();
+
+    press("?", { shiftKey: true });
+    fireEvent.click(screen.getByRole("dialog"));
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("stays open for a click inside the panel", () => {
+    render(<HelpOverlay />);
+    press("?", { shiftKey: true });
+    fireEvent.click(document.querySelector(".help-panel") as HTMLElement);
+    expect(screen.queryByRole("dialog")).not.toBeNull();
+  });
+
+  it("renders exactly the commands the registry has bound, grouped", () => {
+    render(<HelpOverlay />);
+    press("?", { shiftKey: true });
+
+    const groups = groupedCommands();
+    expect([...document.querySelectorAll(".help-group-title")].map((h) => h.textContent)).toEqual(
+      groups.map((g) => g.title),
+    );
+    expect(
+      [...document.querySelectorAll<HTMLElement>(".help-row")].map((r) => r.dataset.commandId),
+    ).toEqual(groups.flatMap((g) => g.items.map((c) => c.id)));
+    expect([...document.querySelectorAll(".help-desc")].map((d) => d.textContent)).toEqual(
+      groups.flatMap((g) => g.items.map((c) => c.label)),
+    );
+    expect(
+      [...document.querySelectorAll(".help-row")].map((r) =>
+        [...r.querySelectorAll("kbd")].map((k) => k.textContent).join(" "),
+      ),
+    ).toEqual(groups.flatMap((g) => g.items.map((c) => keyCaps(c.keys[0]).join(" "))));
+  });
+});

web/src/components/dialogs/HelpOverlay.tsx

@@ -0,0 +1,84 @@
+// React port of ../../help.ts: the `?` overlay renders the command registry
+// (commands.ts) directly — the same list that dispatches the keys — so a
+// binding can never be documented as one thing and do another.
+
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+import { CommandSet, defineCommands, keyCaps } from "../../commands.js";
+import { TOGGLE_HELP_EVENT } from "../../uiEvents.js";
+import { groupedCommands } from "./model.js";
+
+export function HelpOverlay() {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const helpKeys = new CommandSet(defineCommands({ "help.toggle": () => setOpen((o) => !o) }));
+    const overlayKeys = new CommandSet(defineCommands({ "help.close": () => setOpen(false) }));
+    const onKeydown = (e: KeyboardEvent) => {
+      if (open && overlayKeys.handle(e)) return;
+      helpKeys.handle(e);
+    };
+    const onToggle = () => setOpen((o) => !o);
+    window.addEventListener("keydown", onKeydown);
+    document.addEventListener(TOGGLE_HELP_EVENT, onToggle);
+    return () => {
+      window.removeEventListener("keydown", onKeydown);
+      document.removeEventListener(TOGGLE_HELP_EVENT, onToggle);
+    };
+  }, [open]);
+
+  if (!open) return null;
+
+  const close = () => setOpen(false);
+
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Keyboard shortcuts"
+      className="help-overlay fixed inset-0 z-modal flex items-center justify-center bg-bg/70"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) close();
+      }}
+    >
+      <div className="help-panel max-h-[80vh] w-full max-w-[560px] overflow-auto rounded-r-3 border border-border bg-surface p-sp-4 shadow-2">
+        <header className="help-head flex items-center justify-between">
+          <h2 className="help-title m-0 text-fs-15 font-semibold text-ink">Keyboard shortcuts</h2>
+          <button
+            type="button"
+            aria-label="Close"
+            className="help-close rounded-r-1 px-sp-2 py-1 text-fs-15 text-muted hover:text-ink"
+            onClick={close}
+          >
+            ✕
+          </button>
+        </header>
+        {groupedCommands().map((group) => (
+          <section key={group.title} className="help-group mt-sp-3">
+            <h3 className="help-group-title text-fs-12 font-semibold text-muted">{group.title}</h3>
+            <dl className="help-list mt-sp-1">
+              {group.items.map((cmd) => (
+                <div
+                  key={cmd.id}
+                  className="help-row flex items-center justify-between gap-sp-3 py-sp-1"
+                  data-command-id={cmd.id}
+                >
+                  <dt className="help-keys m-0 flex gap-sp-1">
+                    {keyCaps(cmd.keys[0]).map((cap, i) => (
+                      <kbd key={i} className="rounded-r-1 border border-border px-sp-1 text-fs-11">
+                        {cap}
+                      </kbd>
+                    ))}
+                  </dt>
+                  <dd className="help-desc m-0 text-fs-12 text-ink">{cmd.label}</dd>
+                </div>
+              ))}
+            </dl>
+          </section>
+        ))}
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/dialogs/KillDialog.test.tsx

@@ -0,0 +1,103 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { KillDialog } from "./KillDialog.js";
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("KillDialog", () => {
+  it("focuses the kill button, so Enter confirms", () => {
+    render(<KillDialog name="alpha" blockers={null} onConfirm={() => Promise.resolve()} onCancel={vi.fn()} />);
+    expect(document.activeElement).toBe(screen.getByRole("button", { name: "Kill" }));
+  });
+
+  it("focuses the force button too", () => {
+    render(
+      <KillDialog
+        name="alpha"
+        blockers={null}
+        force
+        reason="worktree is dirty."
+        onConfirm={() => Promise.resolve()}
+        onCancel={vi.fn()}
+      />,
+    );
+    expect(document.activeElement).toBe(screen.getByRole("button", { name: "Force kill" }));
+  });
+
+  it("names the blockers in the confirm body", () => {
+    render(
+      <KillDialog
+        name="alpha"
+        blockers={{ uncommitted_files: 2, untracked_files: 0, unpushed_commits: 0 }}
+        onConfirm={() => Promise.resolve()}
+        onCancel={vi.fn()}
+      />,
+    );
+    expect(screen.getByText(/will be refused unless it is forced/)).not.toBeNull();
+  });
+
+  it("cancels on Cancel, on Escape and on a backdrop click", () => {
+    const onCancel = vi.fn();
+    const first = render(<KillDialog name="alpha" blockers={null} onConfirm={() => Promise.resolve()} onCancel={onCancel} />);
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    first.unmount();
+
+    const second = render(<KillDialog name="alpha" blockers={null} onConfirm={() => Promise.resolve()} onCancel={onCancel} />);
+    fireEvent.keyDown(screen.getByRole("dialog"), { key: "Escape" });
+    expect(onCancel).toHaveBeenCalledTimes(2);
+    second.unmount();
+
+    render(<KillDialog name="alpha" blockers={null} onConfirm={() => Promise.resolve()} onCancel={onCancel} />);
+    fireEvent.click(screen.getByRole("dialog"));
+    expect(onCancel).toHaveBeenCalledTimes(3);
+  });
+
+  it("disables the button while pending and shows a rejection inline, so the press can be retried", async () => {
+    let reject: (e: Error) => void = () => {};
+    const onConfirm = vi.fn(() => new Promise<void>((_, r) => (reject = r)));
+    render(<KillDialog name="alpha" blockers={null} onConfirm={onConfirm} onCancel={vi.fn()} />);
+
+    const kill = screen.getByRole("button", { name: "Kill" }) as HTMLButtonElement;
+    fireEvent.click(kill);
+    expect(onConfirm).toHaveBeenCalledOnce();
+    expect(kill.disabled).toBe(true);
+
+    reject(new Error("daemon unreachable"));
+    await waitFor(() => expect(kill.disabled).toBe(false));
+    expect(screen.getByText("Failed to kill: daemon unreachable")).not.toBeNull();
+  });
+
+  it("resets pending when force changes, so the force button is clickable", async () => {
+    // Simulate the Sidebar flow: onConfirm resolves (parent switches to
+    // force mode via rerender), but pending was set to true before the call.
+    const onConfirm = vi.fn(() => Promise.resolve());
+    const { rerender } = render(
+      <KillDialog name="alpha" blockers={null} onConfirm={onConfirm} onCancel={vi.fn()} />,
+    );
+
+    const kill = screen.getByRole("button", { name: "Kill" }) as HTMLButtonElement;
+    fireEvent.click(kill);
+    expect(kill.disabled).toBe(true);
+
+    // Parent re-renders with force=true (the daemon refused the unforced kill).
+    await waitFor(() => expect(onConfirm).toHaveBeenCalledOnce());
+    rerender(
+      <KillDialog
+        name="alpha"
+        blockers={{ uncommitted_files: 1, untracked_files: 0, unpushed_commits: 0 }}
+        force
+        reason="worktree is dirty"
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    const forceBtn = screen.getByRole("button", { name: "Force kill" }) as HTMLButtonElement;
+    expect(forceBtn.disabled).toBe(false);
+  });
+});

web/src/components/dialogs/KillDialog.tsx

@@ -0,0 +1,100 @@
+// React port of ../../killDialog.ts: the two kill prompts (#81, #160). The
+// daemon refuses an unforced kill over a worktree holding unsaved work; the
+// same component in `force` mode is the override that follows that refusal.
+
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+import { formatInTheWay, type InTheWay } from "../../types.js";
+
+export interface KillDialogProps {
+  /** Session name, as the sidebar shows it. */
+  name: string;
+  /** What the card last saw in the way, when anything was. */
+  blockers: InTheWay | null;
+  /** Set once the daemon has refused an unforced kill: this pass forces it,
+   *  and `reason` carries the daemon's refusal message. */
+  force?: boolean;
+  /** Message from the daemon's refusal, shown when there are no blockers to
+   *  spell out. */
+  reason?: string;
+  /** Run the kill (or the forced kill). A rejection is rendered inline, and
+   *  the dialog stays open so the press can be retried. */
+  onConfirm(): Promise<void>;
+  onCancel(): void;
+}
+
+export function KillDialog(props: KillDialogProps) {
+  const { name, blockers, force, reason, onConfirm, onCancel } = props;
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // The acting button takes the focus in both modes: the operator already
+  // asked for the kill, so Enter confirms it.
+  useEffect(() => confirmRef.current?.focus(), []);
+
+  // When the dialog transitions from normal → force mode, the previous
+  // onConfirm resolved without error (it mutated parent state and returned),
+  // so `pending` is still true.  Reset it so the force button is clickable.
+  useEffect(() => setPending(false), [force]);
+
+  const handleConfirm = () => {
+    setPending(true);
+    setError(null);
+    void onConfirm().catch((e: unknown) => {
+      setPending(false);
+      setError(`Failed to kill: ${(e as Error).message}`);
+    });
+  };
+
+  const body = blockers
+    ? force
+      ? `Its worktree still has ${formatInTheWay(blockers)}. Forcing the kill removes the session and leaves the worktree on disk.`
+      : `Its worktree still has ${formatInTheWay(blockers)}. The kill will be refused unless it is forced.`
+    : force
+      ? `${reason ?? ""} Forcing the kill removes the session and leaves the worktree on disk.`
+      : "The session and everything running in it go away. Its worktree stays on disk.";
+
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={`Kill ${name}`}
+      className="kill-dialog fixed inset-0 z-modal flex items-center justify-center bg-bg/70"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onCancel();
+      }}
+      onKeyDown={(e) => {
+        if (e.key === "Escape") onCancel();
+      }}
+    >
+      <div className="kill-dialog-panel min-w-[280px] max-w-[420px] rounded-r-2 border border-border-strong bg-surface p-sp-4 shadow-2">
+        <h2 className="kill-dialog-title m-0 text-fs-15 font-semibold text-ink">Kill &quot;{name}&quot;?</h2>
+        <p className="kill-dialog-body mt-sp-2 text-fs-13 text-ink">{body}</p>
+        {error && <p className="kill-dialog-error mt-sp-2 text-fs-12 text-danger">{error}</p>}
+        <div className="kill-dialog-actions mt-sp-3 flex justify-end gap-sp-2">
+          <button
+            type="button"
+            className="kill-dialog-cancel rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-12 text-ink"
+            onClick={onCancel}
+          >
+            Cancel
+          </button>
+          <button
+            ref={confirmRef}
+            type="button"
+            disabled={pending}
+            className={`rounded-r-1 bg-danger px-sp-3 py-sp-1 text-fs-12 text-accent-ink disabled:opacity-60 ${
+              force ? "kill-dialog-force" : "kill-dialog-kill"
+            }`}
+            onClick={handleConfirm}
+          >
+            {force ? "Force kill" : "Kill"}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/dialogs/index.ts

@@ -0,0 +1,3 @@
+export { KillDialog, type KillDialogProps } from "./KillDialog.js";
+export { HelpOverlay } from "./HelpOverlay.js";
+export { groupedCommands } from "./model.js";

web/src/components/dialogs/model.ts

@@ -0,0 +1,20 @@
+// Command-registry grouping for the help overlay. Moved out of help.ts (whose
+// imperative DOM overlay #253 deleted) so HelpOverlay.tsx renders the same
+// grouping the vanilla overlay did.
+
+import { publishedCommands, type Command } from "../../commands.js";
+
+/** Published commands bucketed by `group`, in registry order — the order the
+ *  overlay lists them in. */
+export function groupedCommands(): { title: string; items: Command[] }[] {
+  const groups: { title: string; items: Command[] }[] = [];
+  for (const cmd of publishedCommands()) {
+    let group = groups.find((g) => g.title === cmd.group);
+    if (!group) {
+      group = { title: cmd.group, items: [] };
+      groups.push(group);
+    }
+    group.items.push(cmd);
+  }
+  return groups;
+}

web/src/components/hooks/useViewport.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useViewport } from "./useViewport.js";
+
+function Probe() {
+  useViewport();
+  return null;
+}
+
+class FakeVisualViewport {
+  height = 800;
+  offsetTop = 0;
+  private listeners: Record<string, Array<() => void>> = { resize: [], scroll: [] };
+
+  addEventListener(type: string, cb: () => void): void {
+    this.listeners[type].push(cb);
+  }
+  removeEventListener(type: string, cb: () => void): void {
+    this.listeners[type] = this.listeners[type].filter((l) => l !== cb);
+  }
+  fire(type: "resize" | "scroll"): void {
+    for (const l of this.listeners[type]) l();
+  }
+}
+
+let vv: FakeVisualViewport;
+
+beforeEach(() => {
+  vv = new FakeVisualViewport();
+  vi.stubGlobal("visualViewport", vv);
+  vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+    cb(0);
+    return 0;
+  });
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  document.documentElement.className = "";
+  document.documentElement.removeAttribute("style");
+});
+
+describe("useViewport", () => {
+  it("mirrors the visual viewport's height and offset onto CSS custom properties", () => {
+    vv.height = 640;
+    vv.offsetTop = 12;
+    render(<Probe />);
+    const root = document.documentElement.style;
+    expect(root.getPropertyValue("--app-vh")).toBe("640px");
+    expect(root.getPropertyValue("--app-top")).toBe("12px");
+  });
+
+  it("no-ops when visualViewport is unavailable", () => {
+    vi.stubGlobal("visualViewport", undefined);
+    expect(() => render(<Probe />)).not.toThrow();
+    expect(document.documentElement.style.getPropertyValue("--app-vh")).toBe("");
+  });
+
+  it("marks kb-open once an editable shrinks the viewport well past the baseline", () => {
+    render(<Probe />);
+    const input = document.createElement("input");
+    document.body.appendChild(input);
+    input.focus();
+
+    vv.height = 800 - 200;
+    vv.fire("resize");
+    expect(document.documentElement.classList.contains("kb-open")).toBe(true);
+
+    input.blur();
+    vv.height = 800;
+    vv.fire("resize");
+    expect(document.documentElement.classList.contains("kb-open")).toBe(false);
+    input.remove();
+  });
+});

web/src/components/hooks/useViewport.ts

@@ -0,0 +1,51 @@
+// React port of ../../viewport.ts. Binds the app shell's height and position
+// to the *visual* viewport rather than the layout one, so a pinned bottom bar
+// (the attach view's special-key bar, NAP-342) lands above an open on-screen
+// keyboard instead of behind it. See viewport.ts for the full mechanism.
+
+import { useEffect } from "react";
+
+const KB_OPEN_THRESHOLD = 150;
+
+export function useViewport(): void {
+  useEffect(() => {
+    const vv = window.visualViewport;
+    if (!vv) return;
+
+    const root = document.documentElement;
+    let raf = 0;
+    let baseline = vv.height;
+
+    const isEditing = () => {
+      const a = document.activeElement as HTMLElement | null;
+      if (!a) return false;
+      return a.tagName === "TEXTAREA" || a.tagName === "INPUT" || a.isContentEditable;
+    };
+
+    const sync = () => {
+      raf = 0;
+      root.style.setProperty("--app-vh", `${Math.round(vv.height)}px`);
+      root.style.setProperty("--app-top", `${Math.round(vv.offsetTop)}px`);
+
+      // Nothing focused ⇒ keyboard can't be open ⇒ this height is the baseline.
+      const editing = isEditing();
+      if (!editing) baseline = vv.height;
+      const kbOpen = editing && baseline - vv.height > KB_OPEN_THRESHOLD;
+      root.classList.toggle("kb-open", kbOpen);
+    };
+    const schedule = () => {
+      if (raf) return;
+      raf = requestAnimationFrame(sync);
+    };
+
+    vv.addEventListener("resize", schedule);
+    vv.addEventListener("scroll", schedule);
+    sync();
+
+    return () => {
+      vv.removeEventListener("resize", schedule);
+      vv.removeEventListener("scroll", schedule);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, []);
+}

web/src/components/kit/DesignKit.tsx

@@ -0,0 +1,382 @@
+// Dev-only design kit (#254), React port of the deleted kit.ts + kit.css.
+// Specimen page for the Tailwind token mapping (tailwind.config.ts ->
+// src/styles.css) so the visual system can be reviewed as a whole. Loads on
+// `?kit` (see index.tsx) and never ships to a production bundle.
+
+import { useState, type ReactNode } from "react";
+
+import { ActivityRail, STATE_WORDS } from "../sidebar/ActivityRail.js";
+import { SessionCard, type SessionCardProps } from "../sidebar/SessionCard.js";
+import { PaneTitle } from "../layout/PaneTitle.js";
+import { PALETTES, useTheme, type Palette } from "../../contexts/ThemeContext.js";
+import type { Session } from "../../types.js";
+
+/** The accent each palette lands on, read from styles.css — shown so all six
+ * are comparable at a glance without switching the live one one at a time. */
+const PALETTE_ACCENT: Record<Palette, string> = {
+  graphite: "oklch(0.92 0.005 256)",
+  "ice-cyan": "oklch(0.85 0.115 205)",
+  periwinkle: "oklch(0.75 0.125 275)",
+  "amber-phosphor": "oklch(0.85 0.16 85)",
+  ember: "oklch(0.78 0.16 40)",
+  orchid: "oklch(0.78 0.13 320)",
+};
+
+const COLOR_TOKENS = [
+  "--bg",
+  "--bg-grid",
+  "--surface",
+  "--surface-2",
+  "--surface-3",
+  "--border",
+  "--border-strong",
+  "--ink",
+  "--muted",
+  "--faint",
+  "--accent",
+  "--accent-strong",
+  "--accent-ink",
+  "--accent-tint",
+  "--accent-fill",
+  "--live",
+  "--danger",
+  "--danger-tint",
+  "--warn",
+  "--term-bg",
+] as const;
+
+// Tailwind's content scanner needs each utility to appear as a literal,
+// contiguous string in source — a template-built `w-${token}` is invisible
+// to it, so every scale below pairs the token label with its whole class name.
+const SPACING_TOKENS = [
+  { token: "sp-1", widthClass: "w-sp-1" },
+  { token: "sp-2", widthClass: "w-sp-2" },
+  { token: "sp-3", widthClass: "w-sp-3" },
+  { token: "sp-4", widthClass: "w-sp-4" },
+  { token: "sp-5", widthClass: "w-sp-5" },
+  { token: "sp-6", widthClass: "w-sp-6" },
+  { token: "sp-8", widthClass: "w-sp-8" },
+] as const;
+const RADIUS_TOKENS = [
+  { token: "r-1", radiusClass: "rounded-r-1" },
+  { token: "r-2", radiusClass: "rounded-r-2" },
+  { token: "r-3", radiusClass: "rounded-r-3" },
+  { token: "r-pill", radiusClass: "rounded-r-pill" },
+] as const;
+const FONT_SIZE_TOKENS = [
+  { token: "fs-11", sizeClass: "text-fs-11" },
+  { token: "fs-12", sizeClass: "text-fs-12" },
+  { token: "fs-13", sizeClass: "text-fs-13" },
+  { token: "fs-14", sizeClass: "text-fs-14" },
+  { token: "fs-15", sizeClass: "text-fs-15" },
+  { token: "fs-17", sizeClass: "text-fs-17" },
+  { token: "fs-20", sizeClass: "text-fs-20" },
+] as const;
+const Z_INDEX_TOKENS = [
+  { name: "z-sticky", value: 10 },
+  { name: "z-backdrop", value: 40 },
+  { name: "z-modal", value: 50 },
+  { name: "z-toast", value: 60 },
+] as const;
+
+function Section({
+  title,
+  note,
+  children,
+}: {
+  title: string;
+  note?: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="border-t border-border py-sp-6 first:border-t-0 first:pt-0">
+      <h2 className="text-fs-17 font-semibold text-ink">{title}</h2>
+      {note && <p className="mt-sp-1 max-w-[70ch] text-fs-12 text-muted">{note}</p>}
+      <div className="mt-sp-4 flex flex-wrap gap-sp-4">{children}</div>
+    </section>
+  );
+}
+
+function Specimen({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex flex-col items-start gap-sp-2">
+      <div className="flex min-h-[48px] items-center rounded-r-2 border border-border bg-surface p-sp-3">
+        {children}
+      </div>
+      <span className="font-mono text-fs-11 text-faint">{label}</span>
+    </div>
+  );
+}
+
+function fakeSession(overrides: Partial<Session>): Session {
+  return {
+    id: "00000000-0000-0000-0000-000000000000",
+    cwd: "/home/dev/maestro",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: new Date().toISOString(),
+    activity_since: new Date(Date.now() - 4 * 60_000).toISOString(),
+    ...overrides,
+  };
+}
+
+const NOOP_CARD_HANDLERS: Omit<SessionCardProps, "session" | "depth" | "now" | "highlighted" | "active" | "open" | "previewing" | "renaming"> = {
+  onSelect: () => {},
+  onOpenMenu: () => {},
+  onSpawnSimilar: () => {},
+  onKill: () => {},
+  onRenameCommit: () => {},
+  onRenameCancel: () => {},
+};
+
+const CARD_SPECIMENS: Array<{ label: string; props: Omit<SessionCardProps, keyof typeof NOOP_CARD_HANDLERS> }> = [
+  {
+    label: "idle",
+    props: {
+      session: fakeSession({ command: "bash" }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: false,
+      open: false,
+      previewing: false,
+      renaming: false,
+    },
+  },
+  {
+    label: "active, focused",
+    props: {
+      session: fakeSession({ activity: "Active", command: "vite dev" }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: true,
+      open: true,
+      previewing: false,
+      renaming: false,
+    },
+  },
+  {
+    label: "awaiting-input",
+    props: {
+      session: fakeSession({ activity: "AwaitingInput", activity_since: new Date(Date.now() - 12_000).toISOString() }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: false,
+      open: false,
+      previewing: false,
+      renaming: false,
+    },
+  },
+  {
+    label: "error",
+    props: {
+      session: fakeSession({ activity: "Error", activity_detail: "tests failing", activity_since: new Date(Date.now() - 7_200_000).toISOString() }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: false,
+      open: false,
+      previewing: false,
+      renaming: false,
+    },
+  },
+  {
+    label: "previewing",
+    props: {
+      session: fakeSession({ command: "opencode" }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: false,
+      open: false,
+      previewing: true,
+      renaming: false,
+    },
+  },
+  {
+    label: "exited",
+    props: {
+      session: fakeSession({ status: "Dead", command: "btop" }),
+      depth: 0,
+      now: Date.now(),
+      highlighted: false,
+      active: false,
+      open: false,
+      previewing: false,
+      renaming: false,
+    },
+  },
+];
+
+const ACTIVITY_STATES = Object.keys(STATE_WORDS) as Array<keyof typeof STATE_WORDS>;
+
+export function DesignKit() {
+  const { theme, palette, toggleTheme, setPalette } = useTheme();
+  // "open" is deliberately display:none in the real app (.mv-pane's rule,
+  // styles.css) — a streaming pane already shows it's connected — so start on
+  // a state the kit page can actually show.
+  const [attachState, setAttachState] = useState<"connecting" | "open" | "closed">("connecting");
+
+  return (
+    // #root is a fixed-height, overflow-hidden flex column (main.css) built for
+    // the app shell's own internal scrolling — this page needs its own scroll
+    // container to match, or everything past the first viewport is clipped.
+    <div className="h-full overflow-y-auto bg-bg text-ink">
+      <header className="flex items-center justify-between border-b border-border px-sp-4 py-sp-3">
+        <h1 className="text-fs-20 font-semibold">
+          maestro<span className="text-accent">_</span> · design kit
+        </h1>
+        <div className="flex items-center gap-sp-2">
+          <button type="button" className="btn btn-ghost" onClick={toggleTheme}>
+            {theme === "dark" ? "☀ light" : "☾ dark"}
+          </button>
+        </div>
+      </header>
+
+      <main className="mx-auto max-w-5xl px-sp-4 py-sp-4">
+        <Section
+          title="Colour palettes"
+          note="6 palettes, picked via data-palette on <html> through ThemeContext. Switching one recolours every token below live."
+        >
+          {PALETTES.map((p) => (
+            <button
+              key={p}
+              type="button"
+              onClick={() => setPalette(p)}
+              className={`flex flex-col items-center gap-sp-1 rounded-r-2 border p-sp-2 ${
+                p === palette ? "border-accent" : "border-border"
+              }`}
+            >
+              <span
+                className="h-sp-6 w-sp-8 rounded-r-1"
+                style={{ background: PALETTE_ACCENT[p] }}
+              />
+              <span className="font-mono text-fs-11 text-muted">{p}</span>
+            </button>
+          ))}
+        </Section>
+
+        <Section title="Colour tokens" note="Current palette + theme, applied through var(--token).">
+          {COLOR_TOKENS.map((t) => (
+            <div key={t} className="flex flex-col items-start gap-sp-1">
+              <div
+                className="h-sp-8 w-sp-8 rounded-r-2 border border-border"
+                style={{ background: `var(${t})` }}
+              />
+              <span className="font-mono text-fs-11 text-faint">{t}</span>
+            </div>
+          ))}
+        </Section>
+
+        <Section title="Typography" note="fontSize -> var(--fs-N), from tailwind.config.ts.">
+          {FONT_SIZE_TOKENS.map(({ token, sizeClass }) => (
+            <Specimen key={token} label={token}>
+              <span className={`font-mono ${sizeClass}`}>Sessions</span>
+            </Specimen>
+          ))}
+        </Section>
+
+        <Section title="Spacing scale" note="spacing -> var(--sp-N).">
+          {SPACING_TOKENS.map(({ token, widthClass }) => (
+            <div key={token} className="flex flex-col items-start gap-sp-1">
+              <div className={`h-sp-3 bg-accent ${widthClass}`} />
+              <span className="font-mono text-fs-11 text-faint">{token}</span>
+            </div>
+          ))}
+        </Section>
+
+        <Section title="Border radii" note="borderRadius -> var(--r-N).">
+          {RADIUS_TOKENS.map(({ token, radiusClass }) => (
+            <div key={token} className="flex flex-col items-start gap-sp-1">
+              <div className={`h-sp-6 w-sp-8 border-2 border-accent ${radiusClass}`} />
+              <span className="font-mono text-fs-11 text-faint">{token}</span>
+            </div>
+          ))}
+        </Section>
+
+        <Section title="Z-index scale" note="zIndex -> var(--z-*).">
+          {Z_INDEX_TOKENS.map((z) => (
+            <div key={z.name} className="flex items-baseline gap-sp-2 font-mono text-fs-12">
+              <span className="text-muted">{z.name}</span>
+              <span className="text-ink">{z.value}</span>
+            </div>
+          ))}
+        </Section>
+
+        <Section title="Buttons" note="Terminal-native bracket chrome — .btn / .btn-primary / .btn-ghost / .btn-icon / .btn-danger.">
+          <Specimen label="btn">
+            <button type="button" className="btn">Cancel</button>
+          </Specimen>
+          <Specimen label="btn-primary">
+            <button type="button" className="btn btn-primary">+ Spawn</button>
+          </Specimen>
+          <Specimen label="btn-ghost">
+            <button type="button" className="btn btn-ghost">Dismiss</button>
+          </Specimen>
+          <Specimen label="btn-icon">
+            <button type="button" className="btn btn-icon">✕</button>
+          </Specimen>
+          <Specimen label="btn-danger">
+            <button type="button" className="btn btn-danger">Kill</button>
+          </Specimen>
+          <Specimen label="btn:disabled">
+            <button type="button" className="btn btn-primary" disabled>+ Spawn</button>
+          </Specimen>
+        </Section>
+
+        <Section title="Activity rail" note="ActivityRail.tsx — one state per session card, colour-coded and never colour-only (title/aria-label carry the word).">
+          {ACTIVITY_STATES.map((slug) => (
+            <Specimen key={slug} label={`${slug} · ${STATE_WORDS[slug]}`}>
+              <div className="relative h-[32px] w-[24px] overflow-hidden rounded-r-1 bg-surface-2">
+                <ActivityRail activity={slug} />
+              </div>
+            </Specimen>
+          ))}
+        </Section>
+
+        <Section title="Session cards" note="SessionCard.tsx, docs/SIDEBAR.md states.">
+          <div className="w-full max-w-sm divide-y divide-border rounded-r-2 border border-border bg-surface-2">
+            {CARD_SPECIMENS.map(({ label, props }) => (
+              <div key={label} className="relative">
+                <SessionCard {...props} {...NOOP_CARD_HANDLERS} />
+              </div>
+            ))}
+          </div>
+        </Section>
+
+        <Section title="Terminal chrome" note="attach-header + attach-body, as worn by TerminalPane/StructuredPane.">
+          <div className="w-full max-w-lg overflow-hidden rounded-r-2 border border-border">
+            <div className="attach-header">
+              <PaneTitle
+                sessionId="11111111-2222-3333-4444-555555555555"
+                session={fakeSession({ command: "claude" })}
+              />
+              <span className="flex-1" />
+              <button
+                type="button"
+                className="attach-state"
+                data-state={attachState}
+                onClick={() =>
+                  setAttachState((s) => (s === "open" ? "connecting" : s === "connecting" ? "closed" : "open"))
+                }
+                title="Click to cycle"
+              >
+                {attachState}
+              </button>
+              <button type="button" className="btn btn-icon disconnect" title="Disconnect">
+                ⏻
+              </button>
+            </div>
+            <div className="attach-body h-[120px] items-start">
+              <span className="font-mono text-fs-13 text-muted">$ pnpm test</span>
+            </div>
+          </div>
+        </Section>
+      </main>
+    </div>
+  );
+}

web/src/components/layout/Drawer.test.tsx

@@ -0,0 +1,154 @@
+// @vitest-environment happy-dom
+import { act, cleanup, fireEvent, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT } from "../../uiEvents.js";
+import { TOGGLE_DRAWER_EVENT } from "../../uiEvents.js";
+import { Drawer } from "./Drawer.js";
+
+/** Force the mobile media query on, whatever happy-dom's viewport says
+ *  (mirrors ../layout/MultiView's own `forceMobile` in multiview.test.ts). */
+function forceMobile(matches: boolean): void {
+  vi.spyOn(window, "matchMedia").mockImplementation(
+    (query: string) =>
+      ({
+        matches: query.includes("859") && matches,
+        media: query,
+        onchange: null,
+        addEventListener() {},
+        removeEventListener() {},
+        addListener() {},
+        removeListener() {},
+        dispatchEvent: () => false,
+      }) as unknown as MediaQueryList,
+  );
+}
+
+function shell(): HTMLElement {
+  return document.querySelector(".app-shell") as HTMLElement;
+}
+
+function touch(type: "touchstart" | "touchend", x: number, y: number): void {
+  const touches = [{ clientX: x, clientY: y }];
+  const event = new Event(type, { bubbles: true }) as unknown as {
+    touches: typeof touches;
+    changedTouches: typeof touches;
+  };
+  event.touches = touches;
+  event.changedTouches = touches;
+  act(() => {
+    document.dispatchEvent(event as unknown as Event);
+  });
+}
+
+beforeEach(() => forceMobile(true));
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function openViaToggle(): void {
+  act(() => {
+    document.dispatchEvent(new CustomEvent(TOGGLE_DRAWER_EVENT));
+  });
+}
+
+describe("Drawer (#35)", () => {
+  it("toggles open on the toggle event, off on desktop by class alone", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+    openViaToggle();
+    expect(shell().classList.contains("drawer-open")).toBe(true);
+  });
+
+  it("closes when a session row is tapped", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    openViaToggle();
+    fireEvent.click(document.querySelector(".tree-leaf") as HTMLElement);
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("closes when a spawn is requested", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    openViaToggle();
+    act(() => {
+      document.dispatchEvent(new CustomEvent(OPEN_SPAWN_EVENT));
+    });
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("closes when spawn similar is requested", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    openViaToggle();
+    act(() => {
+      document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: {} }));
+    });
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("closes on a backdrop click", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    openViaToggle();
+    fireEvent.click(document.querySelector(".mv-backdrop") as HTMLElement);
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("opens on a rightward swipe and closes on a leftward one, only on mobile", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    touch("touchstart", 0, 100);
+    touch("touchend", 100, 100);
+    expect(shell().classList.contains("drawer-open")).toBe(true);
+
+    touch("touchstart", 100, 100);
+    touch("touchend", 0, 100);
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("ignores swipes on desktop", () => {
+    forceMobile(false);
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    touch("touchstart", 0, 100);
+    touch("touchend", 100, 100);
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
+  it("ignores a mostly-vertical or too-short gesture", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    touch("touchstart", 0, 0);
+    touch("touchend", 10, 100);
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+});

web/src/components/layout/Drawer.tsx

@@ -0,0 +1,92 @@
+// React port of ../../drawer.ts (#35): the mobile off-canvas sidebar. On
+// desktop the `drawer-open` class is inert — CSS gates the drawer styling to
+// narrow viewports (styles.css, `.app-shell`).
+//
+// Anything that puts a new view in the content area must close the drawer, or
+// it renders behind the sidebar and the tap reads as a dead button — this
+// listens for the same TOGGLE_DRAWER_EVENT/OPEN_SPAWN_EVENT/SPAWN_SIMILAR_EVENT
+// the rest of the shell already raises, so it needs no wiring from callers.
+
+import type { ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import { OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT, TOGGLE_DRAWER_EVENT } from "../../uiEvents.js";
+
+export interface DrawerProps {
+  sidebar: ReactNode;
+  children: ReactNode;
+  className?: string;
+}
+
+export function Drawer({ sidebar, children, className }: DrawerProps) {
+  const [open, setOpen] = useState(false);
+  const sidebarRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const onToggle = () => setOpen((o) => !o);
+    const onClose = () => setOpen(false);
+    document.addEventListener(TOGGLE_DRAWER_EVENT, onToggle);
+    document.addEventListener(OPEN_SPAWN_EVENT, onClose);
+    document.addEventListener(SPAWN_SIMILAR_EVENT, onClose);
+    return () => {
+      document.removeEventListener(TOGGLE_DRAWER_EVENT, onToggle);
+      document.removeEventListener(OPEN_SPAWN_EVENT, onClose);
+      document.removeEventListener(SPAWN_SIMILAR_EVENT, onClose);
+    };
+  }, []);
+
+  // Horizontal swipes drive the drawer (right opens, left closes) rather than
+  // the browser's back/forward navigation. Only a clearly horizontal gesture
+  // past a threshold counts, so vertical terminal scrolling (which owns its
+  // own touch handler) is untouched.
+  useEffect(() => {
+    const mobileMq = window.matchMedia("(max-width: 859px)");
+    let sx = 0;
+    let sy = 0;
+    let tracking = false;
+
+    const onTouchStart = (e: TouchEvent) => {
+      tracking = mobileMq.matches && e.touches.length === 1;
+      if (tracking) {
+        sx = e.touches[0].clientX;
+        sy = e.touches[0].clientY;
+      }
+    };
+    const onTouchEnd = (e: TouchEvent) => {
+      if (!tracking) return;
+      tracking = false;
+      const t = e.changedTouches[0];
+      const dx = t.clientX - sx;
+      const dy = t.clientY - sy;
+      if (Math.abs(dx) < 60 || Math.abs(dx) < Math.abs(dy) * 1.5) return;
+      setOpen((o) => {
+        if (dx > 0 && !o) return true;
+        if (dx < 0 && o) return false;
+        return o;
+      });
+    };
+
+    document.addEventListener("touchstart", onTouchStart, { passive: true });
+    document.addEventListener("touchend", onTouchEnd, { passive: true });
+    return () => {
+      document.removeEventListener("touchstart", onTouchStart);
+      document.removeEventListener("touchend", onTouchEnd);
+    };
+  }, []);
+
+  return (
+    <div className={`app-shell flex h-full min-h-0 ${open ? "drawer-open" : ""} ${className ?? ""}`}>
+      <div
+        ref={sidebarRef}
+        className="sidebar flex h-full min-h-0 flex-col bg-surface"
+        onClick={(e) => {
+          if ((e.target as HTMLElement).closest(".tree-leaf")) setOpen(false);
+        }}
+      >
+        {sidebar}
+      </div>
+      <section className="content min-h-0 flex-1">{children}</section>
+      <div className="mv-backdrop" onClick={() => setOpen(false)} />
+    </div>
+  );
+}

web/src/components/layout/MultiView.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { leaves } from "../../layout.js";
+import { createLayoutStore } from "../../stores/layoutStore.js";
+import type { Session } from "../../types.js";
+import { MultiView } from "./MultiView.js";
+
+vi.mock("../terminal/TerminalPane.js", () => ({
+  TerminalPane: ({ sessionId }: { sessionId: string }) => <div data-testid={`terminal-${sessionId}`} />,
+}));
+
+vi.mock("../structured/StructuredPane.js", () => ({
+  StructuredPane: ({ sessionId }: { sessionId: string }) => <div data-testid={`structured-${sessionId}`} />,
+}));
+
+afterEach(cleanup);
+
+function store() {
+  return createLayoutStore({
+    load: () => null,
+    save: vi.fn(),
+    scheduler: { setTimer: () => 1, clearTimer: () => {} },
+  });
+}
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/n",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  } as Session;
+}
+
+describe("MultiView", () => {
+  it("shows the empty state when the active tab has no panes", () => {
+    const s = store();
+    render(<MultiView store={s} />);
+    expect(screen.getByText(/No session open/)).toBeTruthy();
+  });
+
+  it("renders a pane per leaf, dispatching to the terminal or structured body", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    s.getState().openSessionBeside("s2");
+    const sessions = new Map([
+      ["s1", session("s1")],
+      ["s2", session("s2", { view: "Structured" })],
+    ]);
+    render(<MultiView store={s} sessions={sessions} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+    expect(screen.getByTestId("structured-s2")).toBeTruthy();
+  });
+
+  it("split right adds a second pane to the tree", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    fireEvent.click(screen.getByTitle("Split right"));
+    expect(screen.getAllByText("Empty pane")).toHaveLength(1);
+  });
+
+  it("close pane removes it", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    const leafId = leaves(s.getState().layout.tabs[0].root)[0].id;
+    s.getState().splitFocused(leafId, "row"); // adds an empty leaf beside s1
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    // splitFocused(after: true) puts the fresh empty leaf second — close it.
+    fireEvent.click(screen.getAllByTitle("Close pane")[1]);
+    expect(screen.queryByText("Empty pane")).toBeNull();
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+  });
+
+  it("prunes a leaf whose session no longer exists, once the live set is known", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    s.getState().openSessionBeside("dead");
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+    expect(screen.queryByTestId("terminal-dead")).toBeNull();
+  });
+
+  it("does not touch the layout while the live set is still unknown", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    render(<MultiView store={s} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+  });
+
+  describe("preview mode (docs/PREVIEW.md)", () => {
+    it("shows a session no pane holds in a throwaway tab, marked as a preview", () => {
+      const s = store();
+      s.getState().openSession("s1");
+      render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+
+      act(() => s.getState().previewSession("s9"));
+      // s1's own tab is still in the strip — the preview never touched it.
+      expect(screen.getByText("Tab 1 · 1")).toBeTruthy();
+      const pane = document.querySelector('[data-session-id="s9"]');
+      expect(pane).toBeTruthy();
+      expect(pane!.classList.contains("is-preview")).toBe(true);
+      expect(screen.getByText("preview")).toBeTruthy();
+    });
+
+    it("puts the layout back byte for byte once the preview ends", () => {
+      const s = store();
+      s.getState().openSession("s1");
+      render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+      const before = JSON.stringify(s.getState().layout);
+
+      act(() => s.getState().previewSession("s9"));
+      act(() => s.getState().previewSession(null));
+
+      expect(JSON.stringify(s.getState().layout)).toBe(before);
+      expect(screen.queryByText("preview")).toBeNull();
+    });
+
+    it("does not grab the keyboard while previewing", () => {
+      const s = store();
+      s.getState().openSession("s1");
+      render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+
+      act(() => s.getState().previewSession("s9"));
+      const pane = document.querySelector('[data-session-id="s9"]') as HTMLElement;
+      expect(pane.querySelector('[data-testid="terminal-s9"]')).toBeTruthy();
+      // TerminalPane's `focus` prop is verified by TerminalPane's own tests;
+      // here the preview must never end up as the active-tab's accent pane.
+      expect(pane.className).not.toContain("border-accent");
+    });
+
+    it("clicking into a previewed pane commits it: no more preview, nothing moves a second time", () => {
+      const s = store();
+      s.getState().openSession("s1");
+      render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+
+      act(() => s.getState().previewSession("s9"));
+      const pane = document.querySelector('[data-session-id="s9"]') as HTMLElement;
+      fireEvent.pointerDown(pane);
+
+      expect(s.getState().preview).toBeNull();
+      expect(screen.queryByText("preview")).toBeNull();
+      expect(leaves(s.getState().layout.tabs[1].root).map((l) => l.sessionId)).toEqual(["s9"]);
+    });
+  });
+});

web/src/components/layout/MultiView.tsx

@@ -0,0 +1,269 @@
+// React port of multiview.ts's tab + split tree (issue #249) plus its preview
+// mode (issue #251, docs/PREVIEW.md). Sidebar drag-to-dock and the mobile
+// single-pane collapse stay with whichever issue wires this into the shell
+// (#253) — this renders the tree itself: tabs, nested splits, pane chrome.
+
+import type { ReactNode } from "react";
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { useStore } from "zustand";
+
+import { activeTab, type Dir, type Node } from "../../layout.js";
+import { usePreview } from "../../hooks/usePreview.js";
+import type { LayoutStore, LayoutStoreApi } from "../../stores/layoutStore.js";
+import type { Session, Uuid } from "../../types.js";
+import { PaneContainer, type PaneContainerHandle } from "./PaneContainer.js";
+import { PaneTitle } from "./PaneTitle.js";
+import { TabBar } from "./TabBar.js";
+
+/** Reaching the focused pane from outside the tree — what the shell's
+ *  leader chords need (focus.toggle, the literal-byte escape hatches). */
+export interface MultiViewHandle {
+  /** Hand the keyboard to the focused pane's terminal (or composer). */
+  focusPane(): void;
+  /** Type into the focused pane. A structured pane has no PTY and ignores it. */
+  sendInput(data: string): void;
+}
+
+export interface MultiViewProps {
+  store: LayoutStoreApi;
+  /** Live sessions, keyed by id — drives pane titles and (once known) boot
+   *  reconciliation. Passing `undefined` defers reconciliation. */
+  sessions?: ReadonlyMap<Uuid, Session>;
+  onDisconnect?: (sessionId: Uuid) => void;
+  emptyState?: ReactNode;
+}
+
+export const MultiView = forwardRef<MultiViewHandle, MultiViewProps>(function MultiView(
+  { store, sessions, onDisconnect, emptyState },
+  ref,
+) {
+  const layout = useStore(store, (s: LayoutStore) => s.layout);
+  const tab = activeTab(layout);
+
+  // Live pane handles, keyed by leaf. Read at call time (not render time) so
+  // the chords always reach whatever is focused right now.
+  const panes = useRef(new Map<string, PaneContainerHandle>()).current;
+  const focusedLeafRef = useRef<string | null>(null);
+  focusedLeafRef.current = tab.focusedLeafId;
+  useImperativeHandle(
+    ref,
+    () => ({
+      focusPane: () => panes.get(focusedLeafRef.current ?? "")?.focusTerminal(),
+      sendInput: (data: string) => panes.get(focusedLeafRef.current ?? "")?.sendInput(data),
+    }),
+    [panes],
+  );
+  const { previewedSessionId, commit: commitPreview } = usePreview({ store });
+  const isPreviewing = previewedSessionId !== null;
+
+  const reconciledRef = useRef(false);
+  useEffect(() => {
+    if (reconciledRef.current || !sessions) return;
+    reconciledRef.current = true;
+    store.getState().reconcile(new Set(sessions.keys()));
+  }, [sessions, store]);
+
+  return (
+    <div className="mv flex h-full min-h-0 flex-col">
+      <TabBar store={store} />
+      <div className="mv-canvas relative min-h-0 flex-1">
+        {tab.root ? (
+          <SplitNode
+            node={tab.root}
+            tab={tab}
+            panes={panes}
+            store={store}
+            sessions={sessions}
+            onDisconnect={onDisconnect}
+            previewedSessionId={previewedSessionId}
+            commitPreview={commitPreview}
+          />
+        ) : (
+          (emptyState ?? (
+            <div className="mv-empty flex h-full items-center justify-center p-sp-4 text-fs-13 text-faint">
+              No session open — pick one from the sidebar, or spawn a new one.
+            </div>
+          ))
+        )}
+        {isPreviewing && (
+          <>
+            <div className="mv-preview-ring pointer-events-none absolute inset-0 rounded-r-2 border border-dashed border-preview-ring" />
+            <div className="mv-preview-chip pointer-events-none absolute right-sp-2 top-sp-2 z-sticky rounded-r-pill bg-preview px-sp-2 py-[2px] text-fs-11 text-preview-ink">
+              preview
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+});
+
+interface TreeProps {
+  tab: { id: string; focusedLeafId: string | null };
+  /** Pane handles by leaf id — each `Pane` registers and unregisters its own. */
+  panes: Map<string, PaneContainerHandle>;
+  store: LayoutStoreApi;
+  sessions?: ReadonlyMap<Uuid, Session>;
+  onDisconnect?: (sessionId: Uuid) => void;
+  previewedSessionId: Uuid | null;
+  commitPreview: (sessionId: Uuid) => void;
+}
+
+function SplitNode({ node, ...rest }: TreeProps & { node: Node }) {
+  if (node.kind === "leaf") {
+    return <Pane leaf={node} isFocused={rest.tab.focusedLeafId === node.id} {...rest} />;
+  }
+  return <SplitContainer node={node} {...rest} />;
+}
+
+function SplitContainer({ node, ...rest }: TreeProps & { node: Extract<Node, { kind: "split" }> }) {
+  const slotA = useRef<HTMLDivElement | null>(null);
+  const slotB = useRef<HTMLDivElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  const onDividerPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    const divider = e.currentTarget;
+    const container = containerRef.current;
+    if (!container) return;
+    divider.setPointerCapture(e.pointerId);
+    const rect = container.getBoundingClientRect();
+    const move = (ev: PointerEvent) => {
+      const frac =
+        node.dir === "row" ? (ev.clientX - rect.left) / rect.width : (ev.clientY - rect.top) / rect.height;
+      node.ratio = Math.max(0.1, Math.min(0.9, frac));
+      if (slotA.current) slotA.current.style.flexGrow = String(node.ratio);
+      if (slotB.current) slotB.current.style.flexGrow = String(1 - node.ratio);
+    };
+    const up = (ev: PointerEvent) => {
+      try {
+        divider.releasePointerCapture(ev.pointerId);
+      } catch {
+        // already released
+      }
+      divider.removeEventListener("pointermove", move);
+      divider.removeEventListener("pointerup", up);
+      rest.store.getState().commitLayout();
+    };
+    divider.addEventListener("pointermove", move);
+    divider.addEventListener("pointerup", up);
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      className={`mv-split flex h-full min-h-0 w-full ${node.dir === "row" ? "flex-row" : "flex-col"}`}
+    >
+      <div ref={slotA} className="mv-slot min-h-0 min-w-0" style={{ flex: `${node.ratio} 1 0` }}>
+        <SplitNode node={node.a} {...rest} />
+      </div>
+      <div
+        className={
+          "mv-divider flex-none bg-border-strong hover:bg-accent " +
+          (node.dir === "row" ? "w-[3px] cursor-col-resize" : "h-[3px] cursor-row-resize")
+        }
+        onPointerDown={onDividerPointerDown}
+      />
+      <div ref={slotB} className="mv-slot min-h-0 min-w-0" style={{ flex: `${1 - node.ratio} 1 0` }}>
+        <SplitNode node={node.b} {...rest} />
+      </div>
+    </div>
+  );
+}
+
+function Pane({
+  leaf,
+  isFocused,
+  panes,
+  store,
+  sessions,
+  onDisconnect,
+  previewedSessionId,
+  commitPreview,
+}: TreeProps & { leaf: Extract<Node, { kind: "leaf" }>; isFocused: boolean }) {
+  const session = leaf.sessionId ? sessions?.get(leaf.sessionId) : undefined;
+  const isPreview = leaf.sessionId !== null && leaf.sessionId === previewedSessionId;
+  const splitFocused = (dir: Dir) => store.getState().splitFocused(leaf.id, dir);
+
+  return (
+    <div
+      className={
+        "mv-pane flex h-full min-h-0 min-w-0 flex-col" +
+        (isFocused ? " is-focused" : "") +
+        (isPreview ? " is-preview" : "")
+      }
+      data-leaf-id={leaf.id}
+      data-session-id={leaf.sessionId ?? undefined}
+      onPointerDownCapture={() => {
+        // Clicking into a previewed pane is the operator choosing it
+        // (docs/PREVIEW.md).
+        if (isPreview) commitPreview(leaf.sessionId!);
+        store.getState().focusLeaf(leaf.id);
+      }}
+    >
+      <div
+        className="mv-pane-header attach-header flex items-center justify-between gap-sp-2 border-b border-border-strong px-sp-2 py-sp-1 text-fs-12"
+      >
+        {leaf.sessionId ? (
+          <PaneTitle sessionId={leaf.sessionId} session={session} />
+        ) : (
+          <span className="text-faint">Empty pane</span>
+        )}
+        <div className="mv-pane-tools flex items-center gap-sp-1">
+          {leaf.sessionId && onDisconnect && (
+            <button
+              type="button"
+              className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+              title="Disconnect"
+              onClick={() => onDisconnect(leaf.sessionId!)}
+            >
+              ⏻
+            </button>
+          )}
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Split right"
+            onClick={() => splitFocused("row")}
+          >
+            ▥
+          </button>
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Split down"
+            onClick={() => splitFocused("col")}
+          >
+            ▤
+          </button>
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Close pane"
+            onClick={() => store.getState().closePane(leaf.id)}
+          >
+            ✕
+          </button>
+        </div>
+      </div>
+      <div className="mv-pane-host min-h-0 flex-1">
+        {leaf.sessionId ? (
+          <PaneContainer
+            ref={(handle) => {
+              if (handle) panes.set(leaf.id, handle);
+              else panes.delete(leaf.id);
+            }}
+            sessionId={leaf.sessionId}
+            session={session}
+            focus={isFocused && previewedSessionId === null}
+            onClosed={() => store.getState().closeSession(leaf.sessionId!)}
+          />
+        ) : (
+          <div className="mv-pane-empty flex h-full items-center justify-center p-sp-4 text-fs-13 text-faint">
+            Empty pane — pick a session from the sidebar, or spawn one.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

web/src/components/layout/PaneContainer.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment happy-dom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { Session } from "../../types.js";
+import { PaneContainer } from "./PaneContainer.js";
+
+vi.mock("../terminal/TerminalPane.js", () => ({
+  TerminalPane: ({ sessionId, focus }: { sessionId: string; focus?: boolean }) => (
+    <div data-testid="terminal-pane" data-session-id={sessionId} data-focus={String(focus)} />
+  ),
+}));
+
+vi.mock("../structured/StructuredPane.js", () => ({
+  StructuredPane: ({ sessionId, focus }: { sessionId: string; focus?: boolean }) => (
+    <div data-testid="structured-pane" data-session-id={sessionId} data-focus={String(focus)} />
+  ),
+}));
+
+afterEach(cleanup);
+
+function session(over: Partial<Session> = {}): Session {
+  return {
+    id: "s1",
+    cwd: "/home/n",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  } as Session;
+}
+
+describe("PaneContainer", () => {
+  it("renders TerminalPane when the session has no view (defaults to Terminal)", () => {
+    render(<PaneContainer sessionId="s1" session={session()} />);
+    expect(screen.getByTestId("terminal-pane")).toBeTruthy();
+    expect(screen.queryByTestId("structured-pane")).toBeNull();
+  });
+
+  it("renders TerminalPane when the session isn't known yet", () => {
+    render(<PaneContainer sessionId="s1" />);
+    expect(screen.getByTestId("terminal-pane")).toBeTruthy();
+  });
+
+  it("renders StructuredPane for a Structured session", () => {
+    render(<PaneContainer sessionId="s1" session={session({ view: "Structured" })} focus={false} />);
+    const pane = screen.getByTestId("structured-pane");
+    expect(pane.dataset.sessionId).toBe("s1");
+    expect(pane.dataset.focus).toBe("false");
+    expect(screen.queryByTestId("terminal-pane")).toBeNull();
+  });
+});

web/src/components/layout/PaneContainer.tsx

@@ -0,0 +1,49 @@
+// Dispatches a leaf's session to the right body — TerminalPane for a PTY
+// session, StructuredPane for an ACP one (session.view, #133/#140/#249).
+
+import { forwardRef, useImperativeHandle, useRef } from "react";
+
+import type { Session, Uuid } from "../../types.js";
+import { StructuredPane, type StructuredPaneHandle } from "../structured/StructuredPane.js";
+import { TerminalPane, type TerminalPaneHandle } from "../terminal/TerminalPane.js";
+
+export interface PaneContainerHandle {
+  focusTerminal(): void;
+  /** No-op for a structured pane — it has no PTY (pane.ts's PaneConnection contract). */
+  sendInput(data: string): void;
+}
+
+export interface PaneContainerProps {
+  sessionId: Uuid;
+  session?: Session;
+  /** Grabs the keyboard once connected. A sidebar preview passes `false`. */
+  focus?: boolean;
+  onClosed?: () => void;
+  className?: string;
+}
+
+export const PaneContainer = forwardRef<PaneContainerHandle, PaneContainerProps>(function PaneContainer(
+  { sessionId, session, focus, onClosed, className },
+  ref,
+) {
+  const terminalRef = useRef<TerminalPaneHandle>(null);
+  const structuredRef = useRef<StructuredPaneHandle>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      focusTerminal: () => {
+        terminalRef.current?.focusTerminal();
+        structuredRef.current?.focusComposer();
+      },
+      sendInput: (data: string) => terminalRef.current?.sendInput(data),
+    }),
+    [],
+  );
+
+  return session?.view === "Structured" ? (
+    <StructuredPane ref={structuredRef} sessionId={sessionId} focus={focus} onClosed={onClosed} className={className} />
+  ) : (
+    <TerminalPane ref={terminalRef} sessionId={sessionId} focus={focus} onClosed={onClosed} className={className} />
+  );
+});

web/src/components/layout/PaneTitle.test.tsx

@@ -0,0 +1,48 @@
+// @vitest-environment happy-dom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { Session } from "../../types.js";
+import { PaneTitle } from "./PaneTitle.js";
+
+afterEach(cleanup);
+
+function session(over: Partial<Session> = {}): Session {
+  return {
+    id: "s1",
+    cwd: "/home/n",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  } as Session;
+}
+
+describe("PaneTitle", () => {
+  it("falls back to a short session id when the session isn't known yet", () => {
+    render(<PaneTitle sessionId="abcdef12-3456-7890-abcd-ef1234567890" />);
+    expect(screen.getByText(/abcdef12/)).toBeTruthy();
+  });
+
+  it("shows the name alone when the command matches it", () => {
+    render(<PaneTitle sessionId="s1" session={session({ command: "claude", metadata: { name: "claude" } })} />);
+    expect(screen.getByText("claude")).toBeTruthy();
+    expect(document.querySelector(".at-cmd")).toBeNull();
+  });
+
+  it("shows the command alongside a custom name", () => {
+    render(
+      <PaneTitle sessionId="s1" session={session({ command: "hx src/main.rs", metadata: { name: "editor" } })} />,
+    );
+    expect(screen.getByText("editor")).toBeTruthy();
+    expect(document.querySelector(".at-cmd")).not.toBeNull();
+  });
+
+  it("never injects markup from a session name", () => {
+    render(<PaneTitle sessionId="s1" session={session({ metadata: { name: "<img onerror=x>" } })} />);
+    expect(document.querySelector("img")).toBeNull();
+    expect(screen.getByText("<img onerror=x>")).toBeTruthy();
+  });
+});

web/src/components/layout/PaneTitle.tsx

@@ -0,0 +1,39 @@
+// React port of paneTitle.ts: a pane header's session identity — the name,
+// then the command as its tool mark when recognised, same as the sidebar
+// card's own CommandFragment (SessionCard.tsx). JSX escapes text nodes, so
+// unlike the vanilla string-builder this needs no manual HTML escaping.
+
+import { splitCommand, toolIconSvg } from "../../toolIcon.js";
+import { sessionName, type Session, type Uuid } from "../../types.js";
+
+export interface PaneTitleProps {
+  sessionId: Uuid;
+  session?: Session;
+  className?: string;
+}
+
+export function PaneTitle({ sessionId, session, className }: PaneTitleProps) {
+  if (!session) {
+    return (
+      <span className={className ?? "attach-title"} title={sessionId}>
+        session <span className="sid">{sessionId.slice(0, 8)}</span>
+      </span>
+    );
+  }
+
+  const name = sessionName(session);
+  const showCommand = Boolean(session.command) && session.command !== name;
+  const { tool, program } = splitCommand(session.command);
+  const icon = tool ? toolIconSvg(tool) : null;
+
+  return (
+    <span className={className ?? "attach-title"} title={`${name} · ${session.command}  (${sessionId})`}>
+      <span className="at-name">{name}</span>
+      {showCommand && (
+        <span className="at-cmd">
+          {icon ? <span className="contents" dangerouslySetInnerHTML={{ __html: icon }} /> : <span>{program}</span>}
+        </span>
+      )}
+    </span>
+  );
+}

web/src/components/layout/TabBar.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createLayoutStore } from "../../stores/layoutStore.js";
+import { TabBar } from "./TabBar.js";
+
+afterEach(cleanup);
+
+function store() {
+  return createLayoutStore({
+    load: () => null,
+    save: vi.fn(),
+    scheduler: { setTimer: () => 1, clearTimer: () => {} },
+  });
+}
+
+function dataTransfer() {
+  const data = new Map<string, string>();
+  return {
+    setData: (type: string, value: string) => data.set(type, value),
+    getData: (type: string) => data.get(type) ?? "",
+    effectAllowed: "",
+  };
+}
+
+describe("TabBar", () => {
+  it("renders one tab per layout tab, marking the active one", () => {
+    const s = store();
+    s.getState().addTab();
+    render(<TabBar store={s} />);
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(2);
+    expect(tabs[1].getAttribute("aria-selected")).toBe("true");
+    expect(tabs[0].getAttribute("aria-selected")).toBe("false");
+  });
+
+  it("shows the open-session count next to a tab's title", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    render(<TabBar store={s} />);
+    expect(screen.getByText(/· 1/)).toBeTruthy();
+  });
+
+  it("clicking a tab selects it", () => {
+    const s = store();
+    s.getState().addTab();
+    const [first] = s.getState().layout.tabs;
+    render(<TabBar store={s} />);
+    fireEvent.click(screen.getAllByRole("tab")[0]);
+    expect(s.getState().layout.activeTabId).toBe(first.id);
+  });
+
+  it("the + button adds a tab", () => {
+    const s = store();
+    render(<TabBar store={s} />);
+    fireEvent.click(screen.getByTitle("New tab"));
+    expect(s.getState().layout.tabs).toHaveLength(2);
+  });
+
+  it("hides the close control on the last remaining tab", () => {
+    const s = store();
+    render(<TabBar store={s} />);
+    expect(screen.queryByTitle("Close tab")).toBeNull();
+  });
+
+  it("closing a tab removes it", () => {
+    const s = store();
+    s.getState().addTab();
+    render(<TabBar store={s} />);
+    fireEvent.click(screen.getAllByTitle("Close tab")[0]);
+    expect(s.getState().layout.tabs).toHaveLength(1);
+  });
+
+  it("dragging a tab onto another reorders them", () => {
+    const s = store();
+    s.getState().addTab();
+    s.getState().addTab();
+    const [a, b, c] = s.getState().layout.tabs;
+    render(<TabBar store={s} />);
+    const tabs = screen.getAllByRole("tab");
+    const dt = dataTransfer();
+    fireEvent.dragStart(tabs[0], { dataTransfer: dt });
+    fireEvent.dragOver(tabs[2], { dataTransfer: dt });
+    fireEvent.drop(tabs[2], { dataTransfer: dt });
+    expect(s.getState().layout.tabs.map((t) => t.id)).toEqual([b.id, c.id, a.id]);
+  });
+});

web/src/components/layout/TabBar.tsx

@@ -0,0 +1,102 @@
+// The tab strip above the canvas (issue #249): click to switch, drag to
+// reorder, a close ✕ per tab (hidden on the last one), a trailing + to add.
+
+import { useState } from "react";
+import { useStore } from "zustand";
+
+import { leaves } from "../../layout.js";
+import type { LayoutStore, LayoutStoreApi } from "../../stores/layoutStore.js";
+
+export interface TabBarProps {
+  store: LayoutStoreApi;
+}
+
+export function TabBar({ store }: TabBarProps) {
+  const layout = useStore(store, (s: LayoutStore) => s.layout);
+  const previewTempTabId = useStore(store, (s: LayoutStore) => s.preview?.tempTabId ?? null);
+  const [draggingId, setDraggingId] = useState<string | null>(null);
+  const [overId, setOverId] = useState<string | null>(null);
+
+  return (
+    <div className="mv-tabs flex items-center gap-sp-1 overflow-x-auto border-b border-border-strong bg-surface px-sp-2 text-fs-12" role="tablist">
+      {layout.tabs.map((tab) => {
+        const count = leaves(tab.root).filter((l) => l.sessionId).length;
+        const isActive = tab.id === layout.activeTabId;
+        const isDropTarget = overId === tab.id && draggingId !== null && draggingId !== tab.id;
+        // A preview's throwaway tab is not a place to go — it goes on its
+        // own the moment the preview ends (docs/PREVIEW.md).
+        const isPreviewTab = tab.id === previewTempTabId;
+        return (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={isActive}
+            draggable
+            data-tab-id={tab.id}
+            className={
+              "mv-tab flex items-center gap-sp-1 rounded-t-r-1 px-sp-2 py-sp-1 " +
+              (isPreviewTab
+                ? "border border-dashed border-preview-ring italic text-preview"
+                : isActive
+                  ? "bg-surface-2 text-ink"
+                  : "text-faint hover:text-ink") +
+              (isDropTarget ? " outline outline-2 outline-accent" : "")
+            }
+            onDragStart={(e) => {
+              setDraggingId(tab.id);
+              e.dataTransfer.setData("text/plain", tab.id);
+              e.dataTransfer.effectAllowed = "move";
+            }}
+            onDragOver={(e) => {
+              if (!draggingId || draggingId === tab.id) return;
+              e.preventDefault();
+              setOverId(tab.id);
+            }}
+            onDragLeave={() => setOverId((current) => (current === tab.id ? null : current))}
+            onDrop={(e) => {
+              e.preventDefault();
+              const fromId = e.dataTransfer.getData("text/plain") || draggingId;
+              setDraggingId(null);
+              setOverId(null);
+              if (fromId && fromId !== tab.id) store.getState().reorderTab(fromId, tab.id);
+            }}
+            onDragEnd={() => {
+              setDraggingId(null);
+              setOverId(null);
+            }}
+            onClick={() => {
+              if (isPreviewTab) return;
+              store.getState().selectTab(tab.id);
+            }}
+          >
+            <span>
+              {tab.title}
+              {count ? ` · ${count}` : ""}
+            </span>
+            {layout.tabs.length > 1 && !isPreviewTab && (
+              <span
+                className="mv-tab-close text-faint hover:text-ink"
+                title="Close tab"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  store.getState().closeTab(tab.id);
+                }}
+              >
+                ✕
+              </span>
+            )}
+          </button>
+        );
+      })}
+      <button
+        type="button"
+        className="mv-tab-add px-sp-2 py-sp-1 text-muted hover:text-ink"
+        title="New tab"
+        onClick={() => store.getState().addTab()}
+      >
+        +
+      </button>
+    </div>
+  );
+}

web/src/components/sidebar/ActivityRail.tsx

@@ -0,0 +1,47 @@
+// docs/SIDEBAR.md: a 7px bar pinned to the row's own left edge, square
+// corners, full card height. It paints for every card, Idle included, and it
+// carries the accessible name of the state so status is never colour-only.
+
+import { activityColorSlug } from "../../activity.js";
+import type { ActivityState } from "../../types.js";
+
+export const STATE_WORDS: Record<string, string> = {
+  active: "Active",
+  idle: "Idle",
+  "awaiting-input": "Awaiting input",
+  error: "Error",
+};
+
+/** Rail fill per state, and the motion the state earns. */
+const RAIL_CLASS: Record<string, string> = {
+  active: "bg-live",
+  idle: "bg-border-strong",
+  "awaiting-input": "bg-warn rail-blink",
+  error: "bg-danger rail-flash",
+};
+
+/** Duration text inherits the rail's colour (docs/SIDEBAR.md). */
+export const DURATION_CLASS: Record<string, string> = {
+  active: "text-live",
+  idle: "text-muted",
+  "awaiting-input": "text-warn",
+  error: "text-danger",
+};
+
+export function stateWordFor(activity: ActivityState | string | undefined): string {
+  return STATE_WORDS[activityColorSlug(activity ?? "Idle")] ?? STATE_WORDS.idle;
+}
+
+export function ActivityRail({ activity }: { activity: ActivityState | string | undefined }) {
+  const slug = activityColorSlug(activity ?? "Idle");
+  const word = STATE_WORDS[slug] ?? STATE_WORDS.idle;
+  return (
+    <span
+      className={`absolute left-0 top-0 bottom-0 w-[7px] ${RAIL_CLASS[slug] ?? RAIL_CLASS.idle}`}
+      data-activity={slug}
+      role="img"
+      title={word}
+      aria-label={word}
+    />
+  );
+}

web/src/components/sidebar/FolderNode.tsx

@@ -0,0 +1,51 @@
+// A collapsible directory in the sidebar tree. Only a *collapsed* header is a
+// keyboard-walk stop (docs/SIDEBAR.md); an expanded one is decoration in front
+// of the cards it holds, so it carries no highlight of its own.
+
+import type { ReactNode } from "react";
+
+import { splitFolderLabel } from "./model.js";
+
+export interface FolderNodeProps {
+  name: string;
+  path: string;
+  depth: number;
+  collapsed: boolean;
+  highlighted: boolean;
+  onToggle(): void;
+  children: ReactNode;
+}
+
+export function FolderNode(props: FolderNodeProps) {
+  const { stem, last } = splitFolderLabel(props.name);
+  return (
+    <div className="tree-folder">
+      <button
+        type="button"
+        className={`tree-folder-header flex w-full items-center gap-sp-1 py-[2px] text-fs-11 text-muted ${
+          props.highlighted ? "ring-1 ring-accent-ring" : ""
+        }`}
+        style={{ paddingLeft: props.depth * 16 }}
+        aria-expanded={!props.collapsed}
+        data-nav-key={`folder:${props.path}`}
+        data-highlighted={props.highlighted ? "true" : undefined}
+        title={props.name}
+        onClick={props.onToggle}
+      >
+        {/* One glyph, rotated when collapsed, so the mark and the rotation
+            never disagree about which way the folder points. */}
+        <span
+          aria-hidden="true"
+          className={`inline-block transition-transform ${props.collapsed ? "-rotate-90" : ""}`}
+        >
+          ▾
+        </span>
+        <span className="truncate">
+          {stem && <span className="text-faint">{stem}/</span>}
+          {last}
+        </span>
+      </button>
+      {!props.collapsed && props.children}
+    </div>
+  );
+}

web/src/components/sidebar/SessionCard.tsx

@@ -0,0 +1,267 @@
+// docs/SIDEBAR.md: a session card is always two lines — the name, then the
+// adaptive meta line — with the activity rail in the gutter beside them.
+
+import { useEffect, useRef, type MouseEvent } from "react";
+
+import {
+  activityDurationLabel,
+  activityHeldMs,
+  META_LINE_MIN_HOLD_MS,
+} from "../../activity.js";
+import { splitCommand, toolIconSvg } from "../../toolIcon.js";
+import type { InTheWay, Session } from "../../types.js";
+import {
+  blockerStats,
+  customSessionName,
+  formatInTheWay,
+  isProvisionalName,
+  MAX_SESSION_NAME_LEN,
+  normalizeSessionName,
+  sessionBlockers,
+  sessionName,
+} from "../../types.js";
+import { ActivityRail, DURATION_CLASS, stateWordFor } from "./ActivityRail.js";
+import { activityColorSlug } from "../../activity.js";
+
+export interface SessionCardProps {
+  session: Session;
+  /** Nesting depth; the row's padding (and so the rail) shifts outward with it. */
+  depth: number;
+  /** Clock the duration is measured against — the sidebar ticks it. */
+  now: number;
+  highlighted: boolean;
+  /** Showing in the focused pane. */
+  active: boolean;
+  /** Open in some pane, not the focused one. */
+  open: boolean;
+  previewing: boolean;
+  renaming: boolean;
+  onSelect(): void;
+  onOpenMenu(x: number, y: number): void;
+  onSpawnSimilar(): void;
+  onKill(): void;
+  onRenameCommit(name: string): void;
+  onRenameCancel(): void;
+}
+
+/** The fill ladder from docs/SIDEBAR.md "Which row is filled" — the CSS
+ * cascade in styles.css carries the actual fills via `.is-active`, `.is-open`,
+ * `.is-previewing` (all inside `:where()` so source order is the precedence).
+ * We just apply the right class names here. */
+function rowClasses(p: SessionCardProps): string {
+  const cls: string[] = [];
+  if (p.active) cls.push("is-active");
+  if (p.open) cls.push("is-open");
+  if (p.previewing) cls.push("is-previewing");
+  if (p.highlighted) cls.push("is-highlighted");
+  return cls.join(" ");
+}
+
+export function SessionCard(props: SessionCardProps) {
+  const { session: s, depth, now, renaming } = props;
+  const name = sessionName(s);
+  const running = s.status === "Running";
+  const word = stateWordFor(s.activity);
+
+  return (
+    <a
+      className={`session-card tree-leaf no-underline ${rowClasses(props)} ${
+        running ? "" : "opacity-60"
+      }`}
+      href={`#/attach/${encodeURIComponent(s.id)}`}
+      style={{ paddingLeft: depth * 16 + 8 }}
+      data-session-id={s.id}
+      data-nav-key={`session:${s.id}`}
+      data-status={running ? "running" : "dead"}
+      data-highlighted={props.highlighted ? "true" : undefined}
+      aria-label={`${name}, ${running ? "running" : "exited"}, ${word}`}
+      onClick={(e) => {
+        if (renaming) return;
+        e.preventDefault();
+        props.onSelect();
+      }}
+      onContextMenu={(e: MouseEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        props.onOpenMenu(e.clientX, e.clientY);
+      }}
+    >
+      <ActivityRail activity={s.activity} />
+      <span className="card-line1">
+        {renaming ? (
+          <RenameField
+            session={s}
+            onCommit={props.onRenameCommit}
+            onCancel={props.onRenameCancel}
+          />
+        ) : (
+          <span
+            className={`leaf-name min-w-0 flex-1 truncate text-fs-13 ${
+              isProvisionalName(s) ? "text-muted" : "text-ink"
+            }`}
+          >
+            {name}
+          </span>
+        )}
+        <span className="leaf-actions">
+          <button
+            type="button"
+            className="leaf-act leaf-clone"
+            title="Spawn similar"
+            aria-label={`Spawn similar to ${name}`}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              props.onSpawnSimilar();
+            }}
+          >
+            ⧉
+          </button>
+          <button
+            type="button"
+            className="leaf-act leaf-kill"
+            title="Kill session"
+            aria-label={`Kill ${name}`}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              props.onKill();
+            }}
+          >
+            ✕
+          </button>
+        </span>
+      </span>
+      <MetaLine session={s} now={now} />
+    </a>
+  );
+}
+
+/** Line 2, left to right: `[duration] [detail] command [diff stat | exited]`.
+ * The line itself is unconditional; only its fragments are adaptive. */
+export function MetaLine({ session: s, now }: { session: Session; now: number }) {
+  const slug = activityColorSlug(s.activity ?? "Idle");
+  const held = activityHeldMs(s.activity_since, now);
+  const duration =
+    held !== null && held >= META_LINE_MIN_HOLD_MS ? activityDurationLabel(held) : null;
+  const blockers = sessionBlockers(s);
+
+  return (
+    <span
+      className="card-line2 flex min-w-0 items-center gap-sp-2 text-fs-11"
+      data-activity={slug}
+    >
+      {duration && (
+        <span className={`activity-duration flex-none ${DURATION_CLASS[slug] ?? "text-muted"}`}>
+          {duration}
+        </span>
+      )}
+      {s.activity_detail && (
+        <span className="activity-detail min-w-0 flex-1 truncate text-faint">
+          {s.activity_detail}
+        </span>
+      )}
+      <CommandFragment command={s.command} />
+      {blockers && <BlockedFragment blockers={blockers} />}
+      {s.status === "Dead" && <span className="flex-none text-faint">exited</span>}
+    </span>
+  );
+}
+
+/** docs/SIDEBAR.md: the card names the program only, as its tool mark when we
+ * have one. The full command line stays in the tooltip either way. */
+function CommandFragment({ command }: { command: string }) {
+  const { tool, program } = splitCommand(command);
+  const icon = tool ? toolIconSvg(tool) : null;
+  return (
+    <span
+      className="leaf-cmd flex min-w-0 flex-none items-center gap-[4px] truncate text-faint"
+      title={command}
+    >
+      {icon ? (
+        <span className="contents" dangerouslySetInnerHTML={{ __html: icon }} />
+      ) : (
+        <span className="truncate">{program}</span>
+      )}
+    </span>
+  );
+}
+
+/** Blocked work in diff notation — `+124 -18 ?3 ↑2`. Only `+` and `-` take
+ * colour; the spelled-out breakdown survives as the tooltip. */
+function BlockedFragment({ blockers }: { blockers: InTheWay }) {
+  const stats = blockerStats(blockers);
+  return (
+    <span
+      className="leaf-blocked flex flex-none items-center gap-[4px] text-faint"
+      title={`Kill will be refused unless forced — ${formatInTheWay(blockers)}`}
+    >
+      {stats.map((st) => (
+        <span
+          key={st.kind}
+          data-stat={st.kind}
+          className={
+            st.kind === "add" ? "text-live" : st.kind === "del" ? "text-danger" : "text-muted"
+          }
+        >
+          {st.text}
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/** Inline rename (#125): Enter commits, Escape and blur cancel, an emptied
+ * field clears the name so the command fallback resumes. It starts from the
+ * session's own name, never from the command it falls back to. */
+function RenameField({
+  session: s,
+  onCommit,
+  onCancel,
+}: {
+  session: Session;
+  onCommit(name: string): void;
+  onCancel(): void;
+}) {
+  const ref = useRef<HTMLInputElement>(null);
+  const settled = useRef(false);
+
+  useEffect(() => {
+    ref.current?.focus();
+    ref.current?.select();
+  }, []);
+
+  return (
+    <input
+      ref={ref}
+      type="text"
+      className="leaf-rename min-w-0 flex-1 bg-surface-2 text-fs-13 text-ink"
+      defaultValue={customSessionName(s) ?? ""}
+      maxLength={MAX_SESSION_NAME_LEN}
+      aria-label={`Rename ${sessionName(s)}`}
+      // The card is an <a> the tree also drags from: without these, clicking
+      // into the field navigates away or starts a drag.
+      onClick={(e) => e.stopPropagation()}
+      onPointerDown={(e) => e.stopPropagation()}
+      onKeyDown={(e) => {
+        e.stopPropagation();
+        if (e.key === "Enter") {
+          e.preventDefault();
+          if (settled.current) return;
+          settled.current = true;
+          onCommit(normalizeSessionName(e.currentTarget.value));
+        } else if (e.key === "Escape") {
+          e.preventDefault();
+          if (settled.current) return;
+          settled.current = true;
+          onCancel();
+        }
+      }}
+      onBlur={() => {
+        if (settled.current) return;
+        settled.current = true;
+        onCancel();
+      }}
+    />
+  );
+}

web/src/components/sidebar/Sidebar.test.tsx

@@ -0,0 +1,241 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ThemeProvider } from "../../contexts/ThemeContext.js";
+import type { Session } from "../../types.js";
+import { Sidebar } from "./Sidebar.js";
+
+/** Wrap children in ThemeProvider so useTheme works in the footer. */
+function Wrapper({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/n/alpha",
+    command: "hx src/",
+    env: {},
+    metadata: { name: id },
+    status: "Running",
+    created_at: "2026-08-24T10:00:00Z",
+    ...over,
+  } as Session;
+}
+
+/** The card element for a session, by the `data-session-id` the row carries. */
+function card(id: string): HTMLElement {
+  const el = document.querySelector<HTMLElement>(`[data-session-id="${id}"]`);
+  if (!el) throw new Error(`no card for ${id}`);
+  return el;
+}
+
+function tree(): HTMLElement {
+  return document.querySelector<HTMLElement>(".tree")!;
+}
+
+describe("SessionCard layout", () => {
+  it("renders two lines: the name, then a meta line naming the program", () => {
+    render(<Wrapper><Sidebar sessions={[session("alpha")]} /></Wrapper>);
+
+    const row = card("alpha");
+    expect(row.textContent).toContain("alpha");
+    const meta = row.querySelector(".card-line2")!;
+    // The program only — never its arguments.
+    expect(meta.textContent).toContain("hx");
+    expect(meta.textContent).not.toContain("src/");
+  });
+
+  it("shows no duration under the 30s hold, and one above it", () => {
+    const now = Date.parse("2026-08-24T10:00:00Z");
+    vi.setSystemTime(now);
+    const fresh = session("fresh", { activity: "Active", activity_since: "2026-08-24T09:59:50Z" });
+    const held = session("held", { activity: "Active", activity_since: "2026-08-24T09:56:00Z" });
+
+    render(<Wrapper><Sidebar sessions={[fresh, held]} /></Wrapper>);
+
+    expect(card("fresh").querySelector(".activity-duration")).toBeNull();
+    expect(card("held").querySelector(".activity-duration")!.textContent).toBe("4m");
+  });
+
+  it("paints a rail for every state, blinking on AwaitingInput and flashing on Error", () => {
+    render(
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("idle"),
+            session("await", { activity: "AwaitingInput" }),
+            session("err", { activity: "Error" }),
+          ]}
+        />
+      </Wrapper>,
+    );
+
+    const rail = (id: string) => card(id).querySelector<HTMLElement>("[data-activity]")!;
+    expect(rail("idle").dataset.activity).toBe("idle");
+    expect(rail("idle").className).not.toContain("rail-");
+    expect(rail("await").className).toContain("rail-blink");
+    expect(rail("err").className).toContain("rail-flash");
+    // Status never rests on colour alone.
+    expect(rail("await").getAttribute("aria-label")).toBe("Awaiting input");
+  });
+
+  it("renders blocked work as diff notation with the spelled-out tooltip", () => {
+    render(
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("alpha", {
+              blocked_work: { uncommitted_files: 2, insertions: 124, deletions: 18, untracked_files: 3 },
+            }),
+          ]}
+        />
+      </Wrapper>,
+    );
+
+    const blocked = card("alpha").querySelector<HTMLElement>(".leaf-blocked")!;
+    expect(blocked.textContent).toBe("+124-18?3");
+    expect(blocked.title).toContain("2 uncommitted files");
+  });
+
+  it("dims a provisional name and leaves a settled one alone", () => {
+    render(
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("gen", { metadata: { name: "gen", name_source: "Generated" } }),
+            session("user", { metadata: { name: "user", name_source: "User" } }),
+          ]}
+        />
+      </Wrapper>,
+    );
+
+    expect(card("gen").querySelector(".text-muted")).not.toBeNull();
+    expect(card("user").textContent).toContain("user");
+  });
+});
+
+describe("keyboard walk", () => {
+  const two = [session("a", { cwd: "/one" }), session("b", { cwd: "/two" })];
+
+  it("j and k step the highlight through the cards", () => {
+    render(<Wrapper><Sidebar sessions={two} /></Wrapper>);
+
+    fireEvent.keyDown(tree(), { key: "j" });
+    expect(card("a").dataset.highlighted).toBe("true");
+    fireEvent.keyDown(tree(), { key: "j" });
+    expect(card("b").dataset.highlighted).toBe("true");
+    fireEvent.keyDown(tree(), { key: "k" });
+    expect(card("a").dataset.highlighted).toBe("true");
+  });
+
+  it("stops on a collapsed folder header and Enter expands onto its first card", () => {
+    render(<Wrapper><Sidebar sessions={two} /></Wrapper>);
+
+    const header = document.querySelector<HTMLElement>('[data-nav-key="folder:one"]')!;
+    fireEvent.click(header);
+    expect(header.getAttribute("aria-expanded")).toBe("false");
+
+    fireEvent.keyDown(tree(), { key: "j" });
+    expect(
+      document.querySelector<HTMLElement>('[data-nav-key="folder:one"]')!.dataset.highlighted,
+    ).toBe("true");
+
+    fireEvent.keyDown(tree(), { key: "Enter" });
+    expect(card("a").dataset.highlighted).toBe("true");
+  });
+
+  it("Enter on a card opens it, and Tab hands the keyboard to the pane", () => {
+    const onSelect = vi.fn();
+    const onFocusPane = vi.fn();
+    render(<Wrapper><Sidebar sessions={two} onSelect={onSelect} onFocusPane={onFocusPane} /></Wrapper>);
+
+    fireEvent.keyDown(tree(), { key: "j" });
+    fireEvent.keyDown(tree(), { key: "Enter" });
+    expect(onSelect).toHaveBeenCalledWith("a");
+
+    fireEvent.keyDown(tree(), { key: "Tab" });
+    expect(onFocusPane).toHaveBeenCalled();
+  });
+
+  it("previews the session the walk lands on", () => {
+    const onPreview = vi.fn();
+    render(<Wrapper><Sidebar sessions={two} onPreview={onPreview} /></Wrapper>);
+
+    fireEvent.keyDown(tree(), { key: "j" });
+    expect(onPreview).toHaveBeenCalledWith("a");
+  });
+
+  it("x asks to kill the highlighted session and r renames it", () => {
+    const onKill = vi.fn();
+    render(<Wrapper><Sidebar sessions={two} onKill={onKill} /></Wrapper>);
+
+    fireEvent.keyDown(tree(), { key: "j" });
+    fireEvent.keyDown(tree(), { key: "x" });
+    expect(onKill).toHaveBeenCalledWith(expect.objectContaining({ id: "a" }));
+
+    fireEvent.keyDown(tree(), { key: "r" });
+    expect(card("a").querySelector(".leaf-rename")).not.toBeNull();
+  });
+});
+
+describe("context menu", () => {
+  it("offers rename, spawn similar and kill", () => {
+    const onSpawnSimilar = vi.fn();
+    const onKill = vi.fn();
+    render(
+      <Wrapper>
+        <Sidebar sessions={[session("alpha")]} onSpawnSimilar={onSpawnSimilar} onKill={onKill} />
+      </Wrapper>,
+    );
+
+    fireEvent.contextMenu(card("alpha"));
+    const labels = [...document.querySelectorAll('[role="menuitem"]')].map((n) => n.textContent);
+    expect(labels).toEqual(["Rename…", "Spawn similar", "Kill session"]);
+
+    fireEvent.click(screen.getByText("Spawn similar"));
+    expect(onSpawnSimilar).toHaveBeenCalledWith(expect.objectContaining({ id: "alpha" }));
+  });
+
+  it("renames in place: Enter commits the field, Escape cancels", () => {
+    const onRename = vi.fn();
+    render(<Wrapper><Sidebar sessions={[session("alpha")]} onRename={onRename} /></Wrapper>);
+
+    fireEvent.contextMenu(card("alpha"));
+    fireEvent.click(screen.getByText("Rename…"));
+
+    const input = card("alpha").querySelector<HTMLInputElement>(".leaf-rename")!;
+    expect(input.value).toBe("alpha");
+    fireEvent.change(input, { target: { value: "  renamed  " } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onRename).toHaveBeenCalledWith("alpha", "renamed");
+    expect(card("alpha").querySelector(".leaf-rename")).toBeNull();
+  });
+});
+
+describe("search", () => {
+  it("filters the tree down to matching sessions", () => {
+    render(<Wrapper><Sidebar sessions={[session("alpha"), session("beta", { cwd: "/home/n/beta" })]} /></Wrapper>);
+
+    fireEvent.change(screen.getByLabelText("Search sessions"), { target: { value: "beta" } });
+
+    expect(document.querySelector('[data-session-id="alpha"]')).toBeNull();
+    expect(document.querySelector('[data-session-id="beta"]')).not.toBeNull();
+  });
+});
+
+describe("empty state", () => {
+  it("offers a spawn when there are no sessions at all", () => {
+    const onSpawn = vi.fn();
+    render(<Wrapper><Sidebar sessions={[]} onSpawn={onSpawn} /></Wrapper>);
+
+    fireEvent.click(screen.getByText("+ Spawn session"));
+    expect(onSpawn).toHaveBeenCalled();
+  });
+});

web/src/components/sidebar/Sidebar.tsx

@@ -0,0 +1,488 @@
+// React port of the sidebar tree (catalog.ts). The contract it renders is
+// docs/SIDEBAR.md: two-line cards behind an activity rail, folder-grouped by
+// repository, walked with j/k.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStore } from "zustand";
+
+import { ApiRequestError, killSession, renameSession } from "../../api.js";
+import type { CatalogStore, CatalogStoreApi } from "../../stores/catalogStore.js";
+import type { InTheWay, Session } from "../../types.js";
+import { sessionBlockers, sessionName } from "../../types.js";
+import { buildTree, type TreeNode } from "../../tree.js";
+import { KILL_SESSION_EVENT, RENAME_SESSION_EVENT, requestToggleHelp } from "../../uiEvents.js";
+import { ContextMenu, type ContextMenuItem } from "../common/ContextMenu.js";
+import type { DaemonLinkStoreApi, DaemonLinkState } from "../daemon/DaemonLink.js";
+import { formatRelease } from "../daemon/DaemonLink.js";
+import { useTheme, PALETTES, type Palette } from "../../contexts/ThemeContext.js";
+import { FolderNode } from "./FolderNode.js";
+import { KillDialog } from "../dialogs/KillDialog.js";
+import { SessionCard } from "./SessionCard.js";
+import { SidebarSearch } from "./SidebarSearch.js";
+import { filterSessions, firstRowUnder, navRows, sessionKey } from "./model.js";
+import { useNow } from "./useNow.js";
+import "./sidebar.css";
+
+export interface SidebarProps {
+  /** Live catalog. Either this or `sessions` supplies the tree. */
+  store?: CatalogStoreApi;
+  /** Static session list — what tests and the design kit render from. */
+  sessions?: Session[];
+  /** The daemon's home dir, so cwds abbreviate to `~/…`. */
+  homeDir?: string;
+  /** Showing in the focused pane. */
+  activeId?: string | null;
+  /** Open in some pane, focused one included. */
+  openIds?: ReadonlySet<string>;
+  /** Previewing (docs/PREVIEW.md) — a view, never durable state. */
+  previewId?: string | null;
+  onSelect?(id: string): void;
+  /** The highlight moved onto a session, or off every session. */
+  onPreview?(id: string | null): void;
+  onSpawnSimilar?(session: Session): void;
+  onSpawn?(): void;
+  /** Fast-forward spawn (`N`). */
+  onSpawnDefaults?(): void;
+  /** Tab: hand the keyboard back to the pane. */
+  onFocusPane?(): void;
+  onHelp?(): void;
+  /** The daemon-link store, for the status indicator in the footer. */
+  linkStore?: DaemonLinkStoreApi;
+  /** Overrides the built-in `DELETE /api/sessions/:id` flow (tests, kit). */
+  onKill?(session: Session): void;
+  /** Overrides the built-in `PATCH /api/sessions/:id` (tests, kit). */
+  onRename?(id: string, name: string): void;
+}
+
+interface MenuState {
+  x: number;
+  y: number;
+  session: Session;
+}
+
+interface KillState {
+  session: Session;
+  blockers: InTheWay | null;
+  force: boolean;
+  /** The daemon's refusal message, once an unforced kill has been refused. */
+  reason?: string;
+}
+
+export function Sidebar(props: SidebarProps) {
+  const sessions = useSessions(props);
+  const now = useNow();
+
+  const [query, setQuery] = useState("");
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set<string>());
+  const [navKey, setNavKey] = useState<string | null>(null);
+  const [renamingId, setRenamingId] = useState<string | null>(null);
+  const [menu, setMenu] = useState<MenuState | null>(null);
+  const [kill, setKill] = useState<KillState | null>(null);
+  const treeRef = useRef<HTMLDivElement>(null);
+
+  const tree = useMemo(
+    () => buildTree(filterSessions(sessions, query), props.homeDir),
+    [sessions, query, props.homeDir],
+  );
+  const rows = useMemo(() => navRows(tree, collapsed), [tree, collapsed]);
+
+  // A row that went away — session killed, folder collapsed over it — drops
+  // the highlight rather than leaving it pointing at nothing.
+  useEffect(() => {
+    if (navKey !== null && !rows.some((r) => r.key === navKey)) setNavKey(null);
+  }, [rows, navKey]);
+
+  const preview = props.onPreview;
+  const previewOf = useCallback(
+    (key: string | null) => {
+      preview?.(key?.startsWith("session:") ? key.slice("session:".length) : null);
+    },
+    [preview],
+  );
+
+  const moveNav = useCallback(
+    (delta: number) => {
+      if (rows.length === 0) return;
+      const cur = rows.findIndex((r) => r.key === navKey);
+      // Nothing highlighted: start one off the end being walked from, so the
+      // first step lands on the first (or last) row.
+      const from = cur === -1 ? (delta > 0 ? -1 : 0) : cur;
+      const next = rows[(((from + delta) % rows.length) + rows.length) % rows.length];
+      setNavKey(next.key);
+      previewOf(next.key);
+    },
+    [rows, navKey, previewOf],
+  );
+
+  const toggleFolder = useCallback((path: string) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
+  }, []);
+
+  /** Enter: open the highlighted session, or expand the highlighted folder and
+   * land on the first row it was hiding. */
+  const activateNav = useCallback(() => {
+    const row = rows.find((r) => r.key === navKey);
+    if (!row) return;
+    if (row.kind === "session") {
+      props.onSelect?.(row.id);
+      return;
+    }
+    const expanded = new Set(collapsed);
+    expanded.delete(row.path);
+    setCollapsed(expanded);
+    const revealed = firstRowUnder(tree, expanded, row.path);
+    setNavKey(revealed?.key ?? null);
+  }, [rows, navKey, collapsed, tree, props]);
+
+  const beginKill = useCallback(
+    (s: Session) => {
+      if (props.onKill) {
+        props.onKill(s);
+        return;
+      }
+      setKill({ session: s, blockers: sessionBlockers(s), force: false });
+    },
+    [props],
+  );
+
+  const commitRename = useCallback(
+    (id: string, name: string) => {
+      setRenamingId(null);
+      if (props.onRename) props.onRename(id, name);
+      else void renameSession(id, name).catch(() => {});
+    },
+    [props],
+  );
+
+  /** The session behind the highlighted row, when the highlight is on a card. */
+  const highlightedSession = useCallback((): Session | undefined => {
+    const row = rows.find((r) => r.key === navKey);
+    if (row?.kind !== "session") return undefined;
+    return sessions.find((s) => s.id === row.id);
+  }, [rows, navKey, sessions]);
+
+  // The command bar's action page raises these rather than reimplementing
+  // either flow (docs/COMMAND-BAR.md): a kill from the bar goes through the
+  // same confirm-and-blockers dialog the card's ✕ does, and a rename from the
+  // bar opens the card's own inline field.
+  useEffect(() => {
+    const onKillRequest = (e: Event) => {
+      const s = (e as CustomEvent<Session>).detail;
+      if (s) beginKill(s);
+    };
+    const onRenameRequest = (e: Event) => {
+      const s = (e as CustomEvent<Session>).detail;
+      if (s) setRenamingId(s.id);
+    };
+    document.addEventListener(KILL_SESSION_EVENT, onKillRequest);
+    document.addEventListener(RENAME_SESSION_EVENT, onRenameRequest);
+    return () => {
+      document.removeEventListener(KILL_SESSION_EVENT, onKillRequest);
+      document.removeEventListener(RENAME_SESSION_EVENT, onRenameRequest);
+    };
+  }, [beginKill]);
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    // The inline rename field owns its own keys; the walk stays out of it.
+    if (e.target instanceof HTMLInputElement) return;
+    switch (e.key) {
+      case "j":
+      case "ArrowDown":
+        e.preventDefault();
+        moveNav(1);
+        return;
+      case "k":
+      case "ArrowUp":
+        e.preventDefault();
+        moveNav(-1);
+        return;
+      case "Enter":
+        e.preventDefault();
+        activateNav();
+        return;
+      case "Tab":
+        e.preventDefault();
+        props.onFocusPane?.();
+        return;
+      case "c": {
+        const row = rows.find((r) => r.key === navKey);
+        if (row?.kind !== "folder") return;
+        e.preventDefault();
+        toggleFolder(row.path);
+        return;
+      }
+      case "r": {
+        const s = highlightedSession();
+        if (!s) return;
+        e.preventDefault();
+        setRenamingId(s.id);
+        return;
+      }
+      case "x": {
+        const s = highlightedSession();
+        if (!s) return;
+        e.preventDefault();
+        beginKill(s);
+        return;
+      }
+      case "n":
+        e.preventDefault();
+        props.onSpawn?.();
+        return;
+      case "N":
+        e.preventDefault();
+        props.onSpawnDefaults?.();
+        return;
+      case "?":
+        e.preventDefault();
+        props.onHelp?.();
+        return;
+    }
+  };
+
+  const menuItems = (s: Session): ContextMenuItem[] => [
+    { label: "Rename…", onSelect: () => setRenamingId(s.id) },
+    { label: "Spawn similar", onSelect: () => props.onSpawnSimilar?.(s) },
+    { label: "Kill session", danger: true, onSelect: () => beginKill(s) },
+  ];
+
+  const renderNode = (node: TreeNode, depth: number): React.ReactNode => {
+    if (node.kind === "leaf") {
+      const s = node.session;
+      return (
+        <SessionCard
+          key={s.id}
+          session={s}
+          depth={depth}
+          now={now}
+          highlighted={navKey === sessionKey(s.id)}
+          active={props.activeId === s.id}
+          open={(props.openIds?.has(s.id) ?? false) && props.activeId !== s.id}
+          previewing={props.previewId === s.id && props.activeId !== s.id}
+          renaming={renamingId === s.id}
+          onSelect={() => props.onSelect?.(s.id)}
+          onOpenMenu={(x, y) => setMenu({ x, y, session: s })}
+          onSpawnSimilar={() => props.onSpawnSimilar?.(s)}
+          onKill={() => beginKill(s)}
+          onRenameCommit={(name) => commitRename(s.id, name)}
+          onRenameCancel={() => setRenamingId(null)}
+        />
+      );
+    }
+    if (!node.name) {
+      return node.children.map((c) => renderNode(c, depth));
+    }
+    return (
+      <FolderNode
+        key={node.path}
+        name={node.name}
+        path={node.path}
+        depth={depth}
+        collapsed={collapsed.has(node.path)}
+        highlighted={navKey === `folder:${node.path}`}
+        onToggle={() => toggleFolder(node.path)}
+      >
+        {node.children.map((c) => renderNode(c, depth + 1))}
+      </FolderNode>
+    );
+  };
+
+  return (
+    <aside className="sidebar flex h-full min-h-0 flex-col bg-surface">
+      <SidebarSearch
+        value={query}
+        onChange={setQuery}
+        onDismiss={() => treeRef.current?.focus()}
+      />
+      <div
+        ref={treeRef}
+        className="tree min-h-0 flex-1 overflow-y-auto outline-none"
+        tabIndex={-1}
+        role="tree"
+        aria-label="Sessions"
+        onKeyDown={onKeyDown}
+        // The keyboard walk's preview belongs to the list holding the
+        // keyboard: once it doesn't, the pane goes back to what was opened.
+        onBlur={() => preview?.(null)}
+      >
+        {sessions.length === 0 ? (
+          <EmptyState onSpawn={() => props.onSpawn?.()} />
+        ) : (
+          renderNode(tree, 0)
+        )}
+      </div>
+      {menu && (
+        <ContextMenu
+          x={menu.x}
+          y={menu.y}
+          items={menuItems(menu.session)}
+          onClose={() => setMenu(null)}
+        />
+      )}
+      {kill && (
+        <KillDialog
+          name={sessionName(kill.session)}
+          blockers={kill.blockers}
+          force={kill.force}
+          reason={kill.reason}
+          onCancel={() => setKill(null)}
+          onConfirm={async () => {
+            const { session: s, force } = kill;
+            try {
+              await killSession(s.id, force);
+              setKill(null);
+            } catch (e: unknown) {
+              // The daemon refuses an unforced kill over a worktree holding
+              // unsaved work; that refusal needs its own prompt
+              // (docs/WORKTREES.md).
+              if (e instanceof ApiRequestError && e.code === "kill_guarded") {
+                setKill({
+                  session: s,
+                  blockers: e.unsavedWork ?? sessionBlockers(s),
+                  force: true,
+                  reason: e.message,
+                });
+                return;
+              }
+              throw e;
+            }
+          }}
+        />
+      )}
+      <SidebarFooter
+        onSpawn={() => props.onSpawn?.()}
+        linkStore={props.linkStore}
+      />
+    </aside>
+  );
+}
+
+/** The tree's one empty state: no sessions at all. */
+function EmptyState({ onSpawn }: { onSpawn(): void }) {
+  return (
+    <div className="empty flex flex-col items-center gap-sp-2 p-sp-6 text-center">
+      <div aria-hidden="true" className="text-fs-20 text-faint">
+        +
+      </div>
+      <div className="text-fs-13 text-ink">No sessions yet</div>
+      <p className="text-fs-12 text-muted">Start your first session — it'll show up here.</p>
+      <button
+        type="button"
+        className="rounded-r-1 bg-accent px-sp-3 py-sp-1 text-fs-12 text-accent-ink"
+        onClick={onSpawn}
+      >
+        + Spawn session
+      </button>
+    </div>
+  );
+}
+
+/** Sessions from the store when one is wired, else the static prop. */
+function useSessions(props: SidebarProps): Session[] {
+  const fromStore = useStore(
+    // `useStore` needs a store every render; the no-store case is served by a
+    // stable empty stand-in whose result is thrown away below.
+    props.store ?? EMPTY_STORE,
+    (s: CatalogStore) => s.sessions,
+  );
+  return useMemo(
+    () => (props.store ? [...fromStore.values()] : (props.sessions ?? [])),
+    [props.store, props.sessions, fromStore],
+  );
+}
+
+// One frozen state object, not a fresh one per call: `useStore` reads the
+// snapshot on every render and a new Map each time would never settle.
+const EMPTY_STATE = { sessions: new Map<string, Session>() };
+const EMPTY_STORE = {
+  getState: () => EMPTY_STATE,
+  getInitialState: () => EMPTY_STATE,
+  setState: () => {},
+  subscribe: () => () => {},
+} as unknown as CatalogStoreApi;
+
+// ---------------------------------------------------------------------------
+// Sidebar footer: help, theme toggle, palette picker, status dot, spawn.
+// Mirrors the vanilla catalog.ts footer that the React migration dropped.
+// ---------------------------------------------------------------------------
+
+function SidebarFooter({
+  onSpawn,
+  linkStore,
+}: {
+  onSpawn(): void;
+  linkStore?: DaemonLinkStoreApi;
+}) {
+  const { theme, toggleTheme, palette, setPalette } = useTheme();
+
+  return (
+    <div className="sidebar-footer">
+      <button
+        type="button"
+        className="btn btn-ghost btn-icon help-btn"
+        title="Keyboard shortcuts (?)"
+        aria-label="Keyboard shortcuts"
+        onClick={requestToggleHelp}
+      >
+        ?
+      </button>
+      <button
+        type="button"
+        className="btn btn-ghost btn-icon"
+        title={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
+        aria-label={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
+        onClick={toggleTheme}
+      >
+        {theme === "dark" ? "☀" : "☾"}
+      </button>
+      <select
+        className="palette-select"
+        value={palette}
+        aria-label="Colour palette"
+        onChange={(e) => setPalette(e.currentTarget.value as Palette)}
+      >
+        {PALETTES.map((p) => (
+          <option key={p} value={p}>
+            {p}
+          </option>
+        ))}
+      </select>
+      {linkStore && <StatusDot store={linkStore} />}
+      <button
+        type="button"
+        className="btn btn-primary spawn-btn"
+        title="Spawn form: n — fast-forward spawn: N"
+        onClick={onSpawn}
+      >
+        + Spawn
+      </button>
+    </div>
+  );
+}
+
+/** Daemon status indicator: a coloured dot whose tooltip names the release. */
+function StatusDot({ store }: { store: DaemonLinkStoreApi }) {
+  const state = useStore(store, (s: DaemonLinkState) => s.state);
+  const build = useStore(store, (s: DaemonLinkState) => s.build);
+  const hostname = useStore(store, (s: DaemonLinkState) => s.hostname);
+
+  return (
+    <button
+      type="button"
+      className="status-chip btn btn-ghost btn-icon"
+      data-state={state}
+      aria-label={`Daemon ${state}`}
+    >
+      <span className="status-dot" />
+      <span className="status-tip">
+        <span>{hostname ?? "maestro"}</span>
+        <span className="text-faint">{formatRelease(build)}</span>
+      </span>
+    </button>
+  );
+}

web/src/components/sidebar/SidebarSearch.tsx

@@ -0,0 +1,34 @@
+// The sidebar's search field: a substring filter over the tree (name, command
+// and cwd). Escape clears it and hands the keyboard back to the list.
+
+export interface SidebarSearchProps {
+  value: string;
+  onChange(value: string): void;
+  /** Escape on an already-empty field — the list wants the keyboard back. */
+  onDismiss?(): void;
+}
+
+export function SidebarSearch({ value, onChange, onDismiss }: SidebarSearchProps) {
+  return (
+    <header className="sidebar-search p-sp-2">
+      <input
+        type="search"
+        className="search w-full rounded-r-1 border border-border bg-surface-2 px-sp-2 py-sp-1 text-fs-12 text-ink"
+        placeholder="Search sessions…"
+        aria-label="Search sessions"
+        autoComplete="off"
+        autoCorrect="off"
+        autoCapitalize="off"
+        spellCheck={false}
+        value={value}
+        onChange={(e) => onChange(e.currentTarget.value)}
+        onKeyDown={(e) => {
+          if (e.key !== "Escape") return;
+          e.preventDefault();
+          if (value) onChange("");
+          else onDismiss?.();
+        }}
+      />
+    </header>
+  );
+}

web/src/components/sidebar/index.ts

@@ -0,0 +1,7 @@
+export { Sidebar, type SidebarProps } from "./Sidebar.js";
+export { SessionCard, type SessionCardProps } from "./SessionCard.js";
+export { FolderNode, type FolderNodeProps } from "./FolderNode.js";
+export { SidebarSearch, type SidebarSearchProps } from "./SidebarSearch.js";
+export { ActivityRail } from "./ActivityRail.js";
+export { ContextMenu, type ContextMenuItem } from "../common/ContextMenu.js";
+export * from "./model.js";

web/src/components/sidebar/model.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import { buildTree } from "../../tree.js";
+import type { Session } from "../../types.js";
+import { filterSessions, firstRowUnder, navRows, splitFolderLabel } from "./model.js";
+
+function session(id: string, cwd: string, command = "claude"): Session {
+  return {
+    id,
+    cwd,
+    command,
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-08-24T10:00:00Z",
+  } as Session;
+}
+
+describe("navRows", () => {
+  const tree = buildTree([session("a", "/one"), session("b", "/two")], undefined);
+
+  it("stops on every card and skips expanded folder headers", () => {
+    expect(navRows(tree, new Set()).map((r) => r.key)).toEqual(["session:a", "session:b"]);
+  });
+
+  it("stops on a collapsed folder header instead of the cards it hides", () => {
+    expect(navRows(tree, new Set(["one"])).map((r) => r.key)).toEqual([
+      "folder:one",
+      "session:b",
+    ]);
+  });
+
+  it("names the first row an expanded folder reveals", () => {
+    expect(firstRowUnder(tree, new Set(), "one")?.key).toBe("session:a");
+  });
+});
+
+describe("splitFolderLabel", () => {
+  it("keeps a shallow path whole", () => {
+    expect(splitFolderLabel("~/maestro")).toEqual({ stem: null, last: "~/maestro" });
+  });
+
+  it("initials the leading segments of a deep path", () => {
+    expect(splitFolderLabel("~/git.naps.pt/naps62/maestro")).toEqual({
+      stem: "~/g/n",
+      last: "maestro",
+    });
+  });
+});
+
+describe("filterSessions", () => {
+  const all = [session("a", "/home/n/alpha", "claude"), session("b", "/home/n/beta", "bash")];
+
+  it("returns everything for a blank query", () => {
+    expect(filterSessions(all, "  ")).toHaveLength(2);
+  });
+
+  it("matches the cwd and the command, case-insensitively", () => {
+    expect(filterSessions(all, "ALPHA").map((s) => s.id)).toEqual(["a"]);
+    expect(filterSessions(all, "bash").map((s) => s.id)).toEqual(["b"]);
+  });
+});

web/src/components/sidebar/model.ts

@@ -0,0 +1,90 @@
+// Pure model helpers behind the React sidebar. Kept out of the components so
+// the walk order and the folder label can be tested without a DOM.
+
+import type { Session } from "../../types.js";
+import { sessionCwd, sessionName } from "../../types.js";
+import type { TreeNode } from "../../tree.js";
+
+/** A row the keyboard walk can land on (docs/SIDEBAR.md "Keyboard walk"):
+ * every session card, and a folder header only while it is collapsed. */
+export type NavRow =
+  | { key: string; kind: "folder"; path: string }
+  | { key: string; kind: "session"; id: string };
+
+export function folderKey(path: string): string {
+  return `folder:${path}`;
+}
+
+export function sessionKey(id: string): string {
+  return `session:${id}`;
+}
+
+/** The walkable rows in visual order. An expanded folder contributes nothing
+ * itself — its cards are one row away — while a collapsed one is the only row
+ * it has, so skipping it would leave the folder unreachable. */
+export function navRows(root: TreeNode, collapsed: ReadonlySet<string>): NavRow[] {
+  const out: NavRow[] = [];
+  const walk = (node: TreeNode): void => {
+    if (node.kind === "leaf") {
+      out.push({ key: sessionKey(node.session.id), kind: "session", id: node.session.id });
+      return;
+    }
+    if (node.name && collapsed.has(node.path)) {
+      out.push({ key: folderKey(node.path), kind: "folder", path: node.path });
+      return;
+    }
+    for (const child of node.children) walk(child);
+  };
+  for (const child of root.kind === "folder" ? root.children : [root]) walk(child);
+  return out;
+}
+
+/** The first walkable row inside `path`, i.e. where the highlight lands when
+ * Enter expands that folder. */
+export function firstRowUnder(
+  root: TreeNode,
+  collapsed: ReadonlySet<string>,
+  path: string,
+): NavRow | undefined {
+  const found = findFolder(root, path);
+  if (!found) return undefined;
+  return navRows({ ...found, name: "" }, collapsed)[0];
+}
+
+function findFolder(node: TreeNode, path: string): Extract<TreeNode, { kind: "folder" }> | null {
+  if (node.kind === "leaf") return null;
+  if (node.path === path && node.name) return node;
+  for (const child of node.children) {
+    const hit = findFolder(child, path);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Structured form of `abbreviateFolderName`: a deep path shows its leading
+ * segments as initials so the tail stays readable in a narrow sidebar. */
+export function splitFolderLabel(name: string): { stem: string | null; last: string } {
+  const parts = name.split("/");
+  if (parts.length <= 2) return { stem: null, last: name };
+  const last = parts[parts.length - 1];
+  const stem = parts
+    .slice(0, -1)
+    .map((p) => (p === "~" ? "~" : (Array.from(p)[0] ?? "")))
+    .join("/");
+  return { stem, last };
+}
+
+/** Case-insensitive substring filter over a session's name, command and cwd —
+ * what the sidebar's own search field narrows the tree with. */
+export function filterSessions(sessions: Session[], query: string): Session[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return sessions;
+  return sessions.filter((s) => {
+    const cwd = sessionCwd(s) ?? "";
+    return (
+      sessionName(s).toLowerCase().includes(q) ||
+      s.command.toLowerCase().includes(q) ||
+      cwd.toLowerCase().includes(q)
+    );
+  });
+}

web/src/components/sidebar/sidebar.css

@@ -0,0 +1,49 @@
+/* Motion for the activity rail (docs/SIDEBAR.md): a hard blink while
+   AwaitingInput, a fast flash while Error. Active and Idle are solid and
+   still — colour alone is the signal. Kept as real CSS rather than Tailwind
+   utilities because both need @keyframes of their own. */
+
+@keyframes maestro-rail-blink {
+  0%,
+  50% {
+    opacity: 1;
+  }
+  50.01%,
+  100% {
+    opacity: 0;
+  }
+}
+
+@keyframes maestro-rail-flash {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  15% {
+    opacity: 0.25;
+  }
+  30% {
+    opacity: 1;
+  }
+  45% {
+    opacity: 0.25;
+  }
+  60% {
+    opacity: 1;
+  }
+}
+
+.rail-blink {
+  animation: maestro-rail-blink 1.2s steps(1) infinite;
+}
+
+.rail-flash {
+  animation: maestro-rail-flash 1.4s ease-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rail-blink,
+  .rail-flash {
+    animation: none;
+  }
+}

web/src/components/sidebar/useNow.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from "react";
+
+/** A clock that ticks at least every `intervalMs` while the page is visible.
+ * docs/SIDEBAR.md asks for a re-render at least every 30s so the duration's
+ * cutover points land within one tick. */
+export function useNow(intervalMs = 30_000): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => {
+      if (document.visibilityState !== "visible") return;
+      setNow(Date.now());
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [intervalMs]);
+  return now;
+}

web/src/components/spawn/BranchPicker.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { BranchInfo } from "../../types.js";
+import { BranchPicker, type BranchPickerProps } from "./BranchPicker.js";
+
+afterEach(cleanup);
+
+function props(over: Partial<BranchPickerProps> = {}): BranchPickerProps {
+  return {
+    enabled: true,
+    onToggleEnabled: vi.fn(),
+    hint: null,
+    baseRepo: "/repo",
+    mode: "new",
+    onModeChange: vi.fn(),
+    newBranch: "",
+    onNewBranchChange: vi.fn(),
+    branches: undefined,
+    existingBranch: "",
+    onExistingBranchChange: vi.fn(),
+    ...over,
+  };
+}
+
+describe("BranchPicker", () => {
+  it("shows the hint instead of the body while unresolved", () => {
+    render(<BranchPicker {...props({ hint: "Choose a working directory first." })} />);
+    expect(screen.getByText("Choose a working directory first.")).not.toBeNull();
+    expect(screen.queryByText("New branch name")).toBeNull();
+  });
+
+  it("shows the new-branch field by default and the repo line once resolved", () => {
+    render(<BranchPicker {...props()} />);
+    expect(screen.getByText("repo: /repo")).not.toBeNull();
+    expect(screen.getByPlaceholderText("feat/foo")).not.toBeNull();
+    expect(screen.queryByText("Pick a branch")).toBeNull();
+  });
+
+  it("switches to the existing-branch select and reports the mode change", () => {
+    const onModeChange = vi.fn();
+    render(<BranchPicker {...props({ onModeChange })} />);
+
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+
+    expect(onModeChange).toHaveBeenCalledWith("existing");
+  });
+
+  it("disables a branch already held by another worktree, and the main checkout's HEAD", () => {
+    const branches: BranchInfo[] = [
+      { name: "main", is_head: true },
+      { name: "feat/a", is_head: false, worktree: "/repos/a" },
+      { name: "feat/b", is_head: false },
+    ];
+    render(<BranchPicker {...props({ mode: "existing", branches })} />);
+
+    const main = screen.getByRole("option", { name: /main — held by the main checkout/ }) as HTMLOptionElement;
+    const a = screen.getByRole("option", { name: /feat\/a — held by \/repos\/a/ }) as HTMLOptionElement;
+    const b = screen.getByRole("option", { name: "feat/b" }) as HTMLOptionElement;
+    expect(main.disabled).toBe(true);
+    expect(a.disabled).toBe(true);
+    expect(b.disabled).toBe(false);
+  });
+
+  it("shows a placeholder option when no local branches were found", () => {
+    render(<BranchPicker {...props({ mode: "existing", branches: [] })} />);
+    expect(screen.getByText("No local branches found.")).not.toBeNull();
+  });
+
+  it("toggles the worktree checkbox", () => {
+    const onToggleEnabled = vi.fn();
+    render(<BranchPicker {...props({ onToggleEnabled })} />);
+
+    fireEvent.click(screen.getByLabelText("Create git worktree"));
+
+    expect(onToggleEnabled).toHaveBeenCalledWith(false);
+  });
+});

web/src/components/spawn/BranchPicker.tsx

@@ -0,0 +1,119 @@
+// The spawn form's worktree section (#61): create-worktree toggle, then
+// (once a base repo is known) new-branch-vs-existing-branch, mirroring
+// spawnForm.ts's `.adv-group`/`.wt-body`/`.wt-mode` markup.
+
+import type { BranchInfo } from "../../types.js";
+import type { WorktreeBranchMode } from "./model.js";
+
+export interface BranchPickerProps {
+  enabled: boolean;
+  onToggleEnabled(enabled: boolean): void;
+  /** Status line shown in place of the body — "Checking…", "not a repo",
+   * "choose a directory first". `null` once the body itself can render. */
+  hint: string | null;
+  /** The repo a worktree would branch from, once resolved. */
+  baseRepo: string | null;
+  mode: WorktreeBranchMode;
+  onModeChange(mode: WorktreeBranchMode): void;
+  newBranch: string;
+  onNewBranchChange(value: string): void;
+  /** This cwd's local branches, or `undefined` while unknown/not yet loaded. */
+  branches: BranchInfo[] | undefined;
+  existingBranch: string;
+  onExistingBranchChange(value: string): void;
+}
+
+export function BranchPicker(props: BranchPickerProps) {
+  return (
+    <div
+      className={`flex flex-col gap-sp-3 border-l-2 pl-sp-3 ${
+        props.enabled ? "border-accent" : "border-border"
+      }`}
+    >
+      <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+        <input
+          type="checkbox"
+          data-role="toggle"
+          className="size-[18px] accent-accent"
+          checked={props.enabled}
+          onChange={(e) => props.onToggleEnabled(e.currentTarget.checked)}
+        />
+        Create git worktree
+      </label>
+
+      {props.hint && <p className="m-0 text-fs-12 text-muted">{props.hint}</p>}
+
+      {props.enabled && !props.hint && (
+        <div className="flex flex-col gap-sp-3">
+          {props.baseRepo && (
+            <p className="m-0 font-mono text-fs-12 text-muted">repo: {props.baseRepo}</p>
+          )}
+          <div role="radiogroup" aria-label="Branch source" className="flex gap-sp-4">
+            <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+              <input
+                type="radio"
+                name="worktree_branch_mode"
+                checked={props.mode === "new"}
+                onChange={() => props.onModeChange("new")}
+              />
+              New branch
+            </label>
+            <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+              <input
+                type="radio"
+                name="worktree_branch_mode"
+                checked={props.mode === "existing"}
+                onChange={() => props.onModeChange("existing")}
+              />
+              Existing branch
+            </label>
+          </div>
+
+          {props.mode === "new" ? (
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              New branch name
+              <input
+                name="worktree_branch"
+                type="text"
+                autoComplete="off"
+                placeholder="feat/foo"
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2 font-mono text-fs-15 text-ink"
+                value={props.newBranch}
+                onChange={(e) => props.onNewBranchChange(e.currentTarget.value)}
+              />
+            </label>
+          ) : (
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              Pick a branch
+              <select
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2 font-mono text-fs-15 text-ink"
+                value={props.existingBranch}
+                onChange={(e) => props.onExistingBranchChange(e.currentTarget.value)}
+              >
+                {branchOptions(props.branches)}
+              </select>
+            </label>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function branchOptions(branches: BranchInfo[] | undefined) {
+  if (!branches || branches.length === 0) {
+    return <option value="">No local branches found.</option>;
+  }
+  return branches.map((b) => {
+    // A branch already checked out anywhere stays visible but unpickable —
+    // git refuses a second checkout. That includes the main checkout's own
+    // HEAD, which is commonly `main` and would otherwise be the default pick,
+    // making every existing-branch spawn fail (#54 review).
+    const held = b.worktree ?? (b.is_head ? "the main checkout" : null);
+    return (
+      <option key={b.name} value={b.name} disabled={held !== null} title={held ?? ""}>
+        {held ? `${b.name} — held by ${held}` : b.name}
+      </option>
+    );
+  });
+}

web/src/components/spawn/DirAutocomplete.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DirAutocomplete } from "./DirAutocomplete.js";
+
+vi.mock("../../api.js", () => ({
+  listDir: vi.fn(),
+}));
+
+import { listDir } from "../../api.js";
+
+const mockListDir = vi.mocked(listDir);
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+function Harness({ initial = "" }: { initial?: string }) {
+  const [value, setValue] = useState(initial);
+  return <DirAutocomplete value={value} onChange={setValue} placeholder="cwd" />;
+}
+
+// `fireEvent.focus`/`.blur` dispatch the event without moving the browser's
+// real focus, so `document.activeElement` (which the dropdown's fetch guards
+// against) never changes — calling the DOM method directly does both.
+function focus(el: HTMLElement): void {
+  act(() => el.focus());
+}
+function blur(el: HTMLElement): void {
+  act(() => el.blur());
+}
+
+describe("DirAutocomplete", () => {
+  it("lists entries matching the trailing segment on focus", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha", "beta"] });
+    render(<Harness initial="/home/n/al" />);
+
+    focus(screen.getByPlaceholderText("cwd"));
+
+    expect(await screen.findByRole("option", { name: "alpha/" })).not.toBeNull();
+    expect(screen.queryByRole("option", { name: "beta/" })).toBeNull();
+  });
+
+  it("Tab commits the highlighted entry and does not close the field", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    render(<Harness initial="/home/n/a" />);
+    const input = screen.getByPlaceholderText("cwd") as HTMLInputElement;
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "Tab" });
+
+    expect(input.value).toBe("/home/n/alpha/");
+  });
+
+  it("arrows move the highlight and Enter accepts it without submitting", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha", "beta"] });
+    render(<Harness initial="/home/n/" />);
+    const input = screen.getByPlaceholderText("cwd") as HTMLInputElement;
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "ArrowDown" });
+    const notPrevented = fireEvent.keyDown(input, { key: "Enter" });
+
+    expect(input.value).toBe("/home/n/beta/");
+    expect(notPrevented).toBe(false); // preventDefault called -> event "processed"
+  });
+
+  it("Escape closes the dropdown and stops the key from bubbling", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    const onKeyDown = vi.fn();
+    render(
+      <div onKeyDown={onKeyDown}>
+        <Harness initial="/home/n/a" />
+      </div>,
+    );
+    const input = screen.getByPlaceholderText("cwd");
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "Escape" });
+
+    await waitFor(() => expect(screen.queryByRole("option")).toBeNull());
+    expect(onKeyDown).not.toHaveBeenCalled();
+  });
+
+  it("does not reopen on refocus until the operator types again", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    render(<Harness initial="/home/n/a" />);
+    const input = screen.getByPlaceholderText("cwd");
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+    fireEvent.keyDown(input, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("option")).toBeNull());
+
+    blur(input);
+    focus(input);
+
+    await new Promise((r) => setTimeout(r, 10));
+    expect(screen.queryByRole("option")).toBeNull();
+
+    fireEvent.change(input, { target: { value: "/home/n/al" } });
+    expect(await screen.findByRole("option", { name: "alpha/" })).not.toBeNull();
+  });
+});

web/src/components/spawn/DirAutocomplete.tsx

@@ -0,0 +1,256 @@
+// React port of ../../dirAutocomplete.ts: shell-style directory autocomplete
+// on a path <input>. Lists one directory at a time over `GET /api/dirs`,
+// caches per directory, and filters the trailing path segment locally.
+//
+// Keyboard model mirrors `cd dir/sub<tab>`:
+//   Tab    commit the highlighted entry and let focus move on; with nothing
+//          highlighted, plain tab navigation
+//   ↑/↓    move the highlight
+//   Enter  accept the highlighted entry (and suppress form submit); with
+//          nothing highlighted, bubble to the form unprevented
+//   Esc    close the dropdown, refocus the input, and stop the key from
+//          bubbling — so dismissing the popup can't also close a parent modal
+//
+// Once dismissed (Esc or blur) the popup stays closed until the operator
+// types again — refocusing alone doesn't reopen it.
+
+import { useCallback, useEffect, useRef, useState, type InputHTMLAttributes, type Ref } from "react";
+import { createPortal } from "react-dom";
+
+import { listDir } from "../../api.js";
+import { splitPath } from "../../paths.js";
+
+/** Most entries rendered at once — a long list is unhelpful and slow. */
+const MAX_VISIBLE = 60;
+/** Debounce before a network fetch when the input crosses into a new directory. */
+const FETCH_DEBOUNCE_MS = 90;
+
+export interface DirAutocompleteProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange"> {
+  value: string;
+  onChange(value: string): void;
+  /** Access to the underlying `<input>` — e.g. to focus/select it. */
+  inputRef?: Ref<HTMLInputElement>;
+}
+
+function assignRef(ref: Ref<HTMLInputElement> | undefined, el: HTMLInputElement | null): void {
+  if (!ref) return;
+  if (typeof ref === "function") ref(el);
+  else (ref as { current: HTMLInputElement | null }).current = el;
+}
+
+export function DirAutocomplete({ value, onChange, inputRef, ...inputProps }: DirAutocompleteProps) {
+  const localRef = useRef<HTMLInputElement | null>(null);
+  const cache = useRef(new Map<string, string[]>());
+  const fetchSeq = useRef(0);
+  const debounceTimer = useRef<number | undefined>(undefined);
+  const dismissedRef = useRef(false);
+
+  const [filtered, setFiltered] = useState<string[]>([]);
+  const [highlight, setHighlight] = useState(-1);
+  const [open, setOpen] = useState(false);
+  const [rect, setRect] = useState<{ left: number; top: number; width: number } | null>(null);
+
+  const setInputRef = useCallback(
+    (el: HTMLInputElement | null) => {
+      localRef.current = el;
+      assignRef(inputRef, el);
+    },
+    [inputRef],
+  );
+
+  const reposition = useCallback(() => {
+    const el = localRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    setRect({ left: r.left, top: r.bottom + 4, width: r.width });
+  }, []);
+
+  const close = useCallback(() => {
+    setOpen(false);
+    setFiltered([]);
+    setHighlight(-1);
+  }, []);
+
+  const dismiss = useCallback(() => {
+    dismissedRef.current = true;
+    close();
+  }, [close]);
+
+  const applyFilter = useCallback(
+    (entries: string[], prefix: string) => {
+      // A fetch can outlive the dismissal it was meant to serve (Tab-commit
+      // re-arms a refresh, then blur dismisses 120ms later). Showing it now
+      // would anchor a dropdown under an unfocused input nothing closes.
+      if (dismissedRef.current || document.activeElement !== localRef.current) {
+        close();
+        return;
+      }
+      const lower = prefix.toLowerCase();
+      const next = entries.filter((e) => e.toLowerCase().startsWith(lower));
+      setFiltered(next);
+      setHighlight(next.length > 0 ? 0 : -1);
+      if (next.length === 0) {
+        close();
+        return;
+      }
+      setOpen(true);
+      reposition();
+    },
+    [close, reposition],
+  );
+
+  const refresh = useCallback(
+    (raw: string) => {
+      const { dir, prefix } = splitPath(raw);
+      const cached = cache.current.get(dir);
+      if (cached) {
+        applyFilter(cached, prefix);
+        return;
+      }
+      const seq = ++fetchSeq.current;
+      listDir(dir)
+        .then((listing) => {
+          cache.current.set(dir, listing.entries);
+          if (seq !== fetchSeq.current) return; // a newer fetch superseded this one
+          const cur = splitPath(localRef.current?.value ?? raw);
+          if (cur.dir === dir) applyFilter(listing.entries, cur.prefix);
+        })
+        .catch(() => {
+          if (seq === fetchSeq.current) close();
+        });
+    },
+    [applyFilter, close],
+  );
+
+  const scheduleRefresh = useCallback(
+    (raw: string) => {
+      window.clearTimeout(debounceTimer.current);
+      debounceTimer.current = window.setTimeout(() => refresh(raw), FETCH_DEBOUNCE_MS);
+    },
+    [refresh],
+  );
+
+  /** Complete `name` as the next path segment and append `/` so the child
+   * directory's listing loads on the next interaction — the drill-in
+   * gesture. Unlike `accept`, doesn't steal focus: Tab uses this to commit
+   * and move to the next field in one gesture. */
+  const commit = useCallback(
+    (name: string) => {
+      const { dir } = splitPath(value);
+      onChange(`${dir}${name}/`);
+    },
+    [value, onChange],
+  );
+
+  const accept = useCallback(
+    (name: string) => {
+      commit(name);
+      localRef.current?.focus();
+    },
+    [commit],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    return () => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    };
+  }, [open, reposition]);
+
+  useEffect(() => () => window.clearTimeout(debounceTimer.current), []);
+
+  return (
+    <>
+      <input
+        {...inputProps}
+        ref={setInputRef}
+        value={value}
+        autoComplete="off"
+        role="combobox"
+        aria-expanded={open}
+        aria-autocomplete="list"
+        onChange={(e) => {
+          dismissedRef.current = false;
+          const next = e.currentTarget.value;
+          onChange(next);
+          scheduleRefresh(next);
+        }}
+        onFocus={(e) => {
+          inputProps.onFocus?.(e);
+          if (dismissedRef.current) return;
+          refresh(value);
+        }}
+        onBlur={(e) => {
+          inputProps.onBlur?.(e);
+          // Delay so a dropdown mousedown can complete first.
+          window.setTimeout(dismiss, 120);
+        }}
+        onKeyDown={(e) => {
+          inputProps.onKeyDown?.(e);
+          if (e.defaultPrevented) return;
+          if (e.key === "Escape") {
+            if (open) {
+              e.preventDefault();
+              e.stopPropagation();
+              dismiss();
+              localRef.current?.focus();
+            }
+            return;
+          }
+          if (e.key === "Tab") {
+            if (!open || highlight < 0 || highlight >= filtered.length) return; // plain tab navigation
+            commit(filtered[highlight]); // no preventDefault — focus moves to the next field
+            return;
+          }
+          if (!open) return;
+          if (e.key === "ArrowDown") {
+            e.preventDefault();
+            setHighlight((h) => Math.min(h + 1, filtered.length - 1));
+          } else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            setHighlight((h) => Math.max(h - 1, 0));
+          } else if (e.key === "Enter" && highlight >= 0 && highlight < filtered.length) {
+            e.preventDefault(); // accept the entry instead of submitting the form
+            accept(filtered[highlight]);
+          }
+        }}
+      />
+      {open &&
+        rect &&
+        createPortal(
+          <ul
+            role="listbox"
+            className="dir-ac fixed z-modal max-h-[240px] overflow-y-auto rounded-r-2 border border-border-strong bg-surface py-sp-1 font-mono shadow-2"
+            style={{ left: rect.left, top: rect.top, width: rect.width }}
+          >
+            {filtered.slice(0, MAX_VISIBLE).map((name, i) => (
+              <li
+                key={name}
+                role="option"
+                aria-selected={i === highlight}
+                className={`cursor-pointer truncate px-sp-3 py-1 text-fs-12 text-ink ${
+                  i === highlight ? "bg-accent-tint" : ""
+                }`}
+                onMouseDown={(e) => {
+                  e.preventDefault(); // accept before the input's blur fires
+                  accept(name);
+                }}
+              >
+                {name}/
+              </li>
+            ))}
+            {filtered.length > MAX_VISIBLE && (
+              <li className="px-sp-3 py-1 text-fs-11 text-faint">
+                +{filtered.length - MAX_VISIBLE} more — keep typing to narrow
+              </li>
+            )}
+          </ul>,
+          document.body,
+        )}
+    </>
+  );
+}

web/src/components/spawn/SpawnForm.test.tsx

@@ -0,0 +1,383 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { BranchInfo, DaemonInfo, Project, Session, SpawnPreset } from "../../types.js";
+import { SpawnForm } from "./SpawnForm.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchBranches: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  gitRoot: vi.fn(),
+  listDir: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import {
+  createSession,
+  fetchBranches,
+  fetchNames,
+  getDaemonInfo,
+  gitRoot,
+  listDir,
+  projects as fetchProjects,
+} from "../../api.js";
+
+const mockCreateSession = vi.mocked(createSession);
+const mockFetchBranches = vi.mocked(fetchBranches);
+const mockFetchNames = vi.mocked(fetchNames);
+const mockGetDaemonInfo = vi.mocked(getDaemonInfo);
+const mockGitRoot = vi.mocked(gitRoot);
+const mockListDir = vi.mocked(listDir);
+const mockFetchProjects = vi.mocked(fetchProjects);
+
+const presets: SpawnPreset[] = [
+  { id: "claude", label: "Claude", command: "claude" },
+  { id: "opencode", label: "opencode", command: "opencode" },
+  { id: "zsh", label: "Shell", command: "zsh" },
+  { id: "custom", label: "Custom…", command: "" },
+];
+
+function info(over: Partial<DaemonInfo> = {}): DaemonInfo {
+  return { hostname: "h", version: "1", home_dir: "/home/n", presets, ...over };
+}
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", last_activity: new Date().toISOString(), ...over };
+}
+
+function session(over: Partial<Session> = {}): Session {
+  return {
+    id: "s1",
+    cwd: "/repos/p",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+/** Defaults every test starts from: one known project, no branches, a fresh
+ * generated handle. Individual tests override what they care about. */
+function stub(over: { projects?: Project[]; info?: DaemonInfo; names?: string[]; branches?: BranchInfo[] } = {}) {
+  mockGetDaemonInfo.mockResolvedValue(over.info ?? info());
+  mockFetchProjects.mockResolvedValue(over.projects ?? [project()]);
+  mockFetchNames.mockResolvedValue({ names: over.names ?? ["amber-fox"] });
+  mockFetchBranches.mockResolvedValue(over.branches ?? []);
+  mockGitRoot.mockResolvedValue({});
+  mockListDir.mockResolvedValue({ path: "", entries: [] });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+async function settle() {
+  await waitFor(() => expect(screen.queryByText("Loading projects…")).toBeNull());
+}
+
+/** Everything worktree/name/structured-related lives behind the "Advanced"
+ * disclosure, collapsed by default (#93) — mirrors the vanilla form exactly. */
+function openAdvanced() {
+  fireEvent.click(screen.getByRole("button", { name: /Advanced/ }));
+}
+
+describe("SpawnForm harness picker", () => {
+  it("selects the first non-custom preset by default and reveals the custom input on Custom…", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByRole("button", { name: /^Claude/ }).className).toContain("border-accent");
+    fireEvent.click(screen.getByRole("button", { name: "Custom…" }));
+
+    expect(screen.getByPlaceholderText("bash -l").hidden).toBe(false);
+  });
+
+  it("resolves a seeded command to its matching preset", async () => {
+    stub();
+    render(<SpawnForm seed={{ command: "opencode" }} onSuccess={vi.fn()} />);
+    await settle();
+
+    const opencode = screen.getByRole("button", { name: /opencode/ });
+    expect(opencode.className).toContain("border-accent");
+  });
+
+  it("drops an unmatched seeded command into the custom field", async () => {
+    stub();
+    render(<SpawnForm seed={{ command: "hx src/" }} onSuccess={vi.fn()} />);
+    await settle();
+
+    const raw = screen.getByPlaceholderText("bash -l") as HTMLInputElement;
+    expect(raw.hidden).toBe(false);
+    expect(raw.value).toBe("hx src/");
+  });
+});
+
+describe("SpawnForm project picker", () => {
+  it("lists discovered projects and reveals the worktree step on pick", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" }), project({ path: "/repos/b", name: "b" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    expect(screen.queryByText("Worktree")).toBeNull();
+    fireEvent.click(screen.getByText("a"));
+
+    expect(screen.getByText("Worktree")).not.toBeNull();
+    expect(screen.getByText("+ new").closest("button")?.getAttribute("data-active")).toBe("true");
+  });
+
+  it("filters the project grid by name", async () => {
+    stub({ projects: [project({ path: "/repos/alpha", name: "alpha" }), project({ path: "/repos/beta", name: "beta" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    fireEvent.change(screen.getByPlaceholderText("Filter projects…"), { target: { value: "alp" } });
+
+    expect(screen.getByText("alpha")).not.toBeNull();
+    expect(screen.queryByText("beta")).toBeNull();
+  });
+
+  it("falls back to the raw directory input when no projects are discovered", async () => {
+    stub({ projects: [] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    expect((screen.getByPlaceholderText("/home/user/project") as HTMLInputElement).value).toBe("/home/n");
+  });
+
+  it("Other directory… clears the picker and opens the raw input", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+    expect(screen.getByText("a").closest("button")?.getAttribute("data-active")).toBe("true");
+
+    fireEvent.click(screen.getByText("Other directory…"));
+
+    expect(screen.getByText("a").closest("button")?.getAttribute("data-active")).toBeNull();
+    expect((screen.getByPlaceholderText("/home/user/project") as HTMLInputElement).value).toBe("/repos/a");
+  });
+});
+
+describe("SpawnForm worktree defaults", () => {
+  it("defaults the toggle on for a picked project and infers the repo without a gitroot probe", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    fireEvent.click(screen.getByText("a"));
+
+    expect(screen.getByText("repo: /repos/a")).not.toBeNull();
+    expect(mockGitRoot).not.toHaveBeenCalled();
+  });
+
+  it("defaults the toggle off for a project that is itself a worktree (#91)", async () => {
+    stub({
+      projects: [
+        project({ path: "/repos/main", name: "main" }),
+        project({ path: "/repos/wt", name: "wt", is_worktree: true, base_repo: "/repos/main" }),
+      ],
+    });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    fireEvent.click(screen.getByText("main"));
+    fireEvent.click(screen.getByText("wt"));
+
+    expect((screen.getByLabelText("Create git worktree") as HTMLInputElement).checked).toBe(false);
+  });
+
+  it("still probes gitroot for a free-text directory", async () => {
+    stub();
+    mockGitRoot.mockResolvedValue({ root: "/repos/found" });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("Other directory…"));
+
+    fireEvent.change(screen.getByPlaceholderText("/home/user/project"), {
+      target: { value: "/repos/found/sub" },
+    });
+
+    await waitFor(() => expect(mockGitRoot).toHaveBeenCalledWith("/repos/found/sub"));
+    expect(await screen.findByText("repo: /repos/found")).not.toBeNull();
+  });
+
+  it("populates existing branches, disabling the one held by another worktree", async () => {
+    stub({
+      projects: [project({ path: "/repos/a", name: "a" })],
+      branches: [
+        { name: "main", is_head: true },
+        { name: "feat/x", is_head: false, worktree: "/repos/other" },
+        { name: "feat/y", is_head: false },
+      ],
+    });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+
+    const y = await screen.findByRole("option", { name: "feat/y" });
+    expect((y as HTMLOptionElement).disabled).toBe(false);
+    expect((screen.getByRole("option", { name: /main — held by the main checkout/ }) as HTMLOptionElement).disabled).toBe(
+      true,
+    );
+  });
+
+  it("submits the first pickable branch when the operator never opens the select", async () => {
+    stub({
+      projects: [project({ path: "/repos/a", name: "a" })],
+      branches: [
+        { name: "main", is_head: true },
+        { name: "feat/y", is_head: false },
+      ],
+    });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+    await screen.findByRole("option", { name: "feat/y" });
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ worktree: expect.objectContaining({ branch: "feat/y", create_branch: false }) }),
+    );
+  });
+});
+
+describe("SpawnForm structured view", () => {
+  it("defaults on for a resolved Claude Code command and off for an unsupported one", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    expect((screen.getByLabelText("Structured view") as HTMLInputElement).checked).toBe(true);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Shell/ }));
+
+    expect(screen.queryByLabelText("Structured view")).toBeNull();
+  });
+
+  it("keeps an unchecked box unchecked across a command change between two supported tools", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByLabelText("Structured view"));
+
+    fireEvent.click(screen.getByRole("button", { name: /opencode/ }));
+    fireEvent.click(screen.getByRole("button", { name: /^Claude/ }));
+
+    expect((screen.getByLabelText("Structured view") as HTMLInputElement).checked).toBe(false);
+  });
+});
+
+describe("SpawnForm submit", () => {
+  it("builds and posts the request, reporting the created session", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    const created = session();
+    mockCreateSession.mockResolvedValue(created);
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith(created));
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd: "/repos/a", command: "claude" }),
+    );
+  });
+
+  it("shows the daemon's rejection and leaves the form open", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    mockCreateSession.mockRejectedValue(new Error("cwd is not a directory"));
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    expect(await screen.findByText("cwd is not a directory")).not.toBeNull();
+  });
+
+  it("rejects an existing-branch worktree with nothing picked", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })], branches: [] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+    await screen.findByText("No local branches found.");
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    expect(await screen.findByText("Pick an existing branch.")).not.toBeNull();
+    expect(mockCreateSession).not.toHaveBeenCalled();
+  });
+});
+
+describe("SpawnForm Enter-to-submit (#97)", () => {
+  it("submits from the session name field", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+    openAdvanced();
+
+    fireEvent.keyDown(screen.getByPlaceholderText("named after your first prompt"), { key: "Enter" });
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+  });
+
+  it("first Enter picks a not-yet-active project box, the second submits", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" }), project({ path: "/repos/b", name: "b" })] });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+
+    const boxB = screen.getByText("b").closest("button")!;
+    fireEvent.keyDown(boxB, { key: "Enter" });
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(boxB.getAttribute("data-active")).toBe("true");
+
+    fireEvent.keyDown(boxB, { key: "Enter" });
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+  });
+
+  it("toggles the worktree checkbox on Enter instead of submitting", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    const checkbox = screen.getByLabelText("Create git worktree") as HTMLInputElement;
+    expect(checkbox.checked).toBe(true);
+
+    fireEvent.keyDown(checkbox, { key: "Enter" });
+
+    expect(checkbox.checked).toBe(false);
+    expect(mockCreateSession).not.toHaveBeenCalled();
+  });
+});

web/src/components/spawn/SpawnForm.tsx

@@ -0,0 +1,857 @@
+// React port of ../../spawnForm.ts: the spawn form itself — preset tiles,
+// two-step project picker, name, structured-view checkbox, worktree. Mounted
+// inside SpawnModal.
+//
+// Working-directory picker (#95), unchanged from the vanilla form:
+//  1. Step one is one box per repository (name, then its parent directory).
+//     A worktree is a box only when its main checkout is missing from the
+//     scan.
+//  2. The filter keeps a repository when the query matches it or any of its
+//     worktrees.
+//  3. Picking a box reveals step two: "+ new", then that repository's
+//     worktrees newest-first. "Other directory…" clears both steps.
+//  4. "+ new" is the default selection — except on a box that is itself a
+//     linked worktree, which defaults to that worktree.
+//  5. "+ new" means create: cwd is the repository, create-worktree on. An
+//     existing worktree means run in it: cwd is that worktree, create-worktree
+//     off (the daemon never adopts, docs/WORKTREES.md).
+//  6. Neither step probes /api/gitroot; only the free-text hatch does.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  createSession,
+  fetchBranches,
+  fetchNames,
+  getDaemonInfo,
+  gitRoot,
+  projects as fetchProjects,
+} from "../../api.js";
+import { parentDir } from "../../paths.js";
+import {
+  filterProjects,
+  groupProjects,
+  isStale,
+  sortProjects,
+  type ProjectGroup,
+} from "../../projectList.js";
+import {
+  buildSpawnRequest,
+  FALLBACK_PRESETS,
+  supportsStructuredView,
+  type SpawnFormSeed,
+  type SpawnFormValues,
+  type WorktreeBranchMode,
+} from "./model.js";
+import { splitCommand, toolIconSvg, TOOL_LABELS } from "../../toolIcon.js";
+import { abbreviateCwd } from "../../types.js";
+import type { BranchInfo, Project, Session, SpawnPreset } from "../../types.js";
+import { BranchPicker } from "./BranchPicker.js";
+import { DirAutocomplete } from "./DirAutocomplete.js";
+
+/** Quiet period after raw-path typing before `/api/gitroot` fires (#74). Must
+ * stay equal to `GITROOT_PROBE_DEBOUNCE_MS` in crates/maestro-tui/src/draft.rs
+ * and to ../../spawnForm.ts's own constant, so every client debounces alike. */
+const GITROOT_PROBE_DEBOUNCE_MS = 250;
+
+/** "new" (create a worktree) or the path of an existing worktree to run in. */
+type WorktreeChoice = "new" | string;
+
+type BaseRepoResolution =
+  | { kind: "disabled" }
+  | { kind: "no-cwd" }
+  | { kind: "found"; repo: string }
+  | { kind: "probe" };
+
+function resolveBaseRepoFor(cwd: string, wtEnabled: boolean, discovered: Project[]): BaseRepoResolution {
+  if (!wtEnabled) return { kind: "disabled" };
+  if (!cwd) return { kind: "no-cwd" };
+  const project = discovered.find((p) => p.path === cwd);
+  if (project) return { kind: "found", repo: project.base_repo ?? project.path };
+  return { kind: "probe" };
+}
+
+/** Every worktree of a group, including the group's own box when the scan
+ * found no main checkout to nest it under. */
+function worktreesOf(group: ProjectGroup): Project[] {
+  return [group.main, ...group.worktrees].filter((p) => p.is_worktree);
+}
+
+/** Resolve a preset id to a tool icon id — the preset's command is the source
+ * of truth, the same way the sidebar derives one. The "Custom…" preset (empty
+ * command) has no tool to show. */
+function presetToolId(p: SpawnPreset): string | null {
+  if (!p.command) return null;
+  return splitCommand(p.command).tool;
+}
+
+function harnessIcon(toolId: string): string | null {
+  const small = toolIconSvg(toolId);
+  if (!small) return null;
+  // toolIconSvg renders at 13x13 (viewBox 0 0 16 16) for the sidebar; the
+  // harness card wants the same mark at 24x24 so it breathes.
+  return small.replace(/width="13"/g, 'width="24"').replace(/height="13"/g, 'height="24"');
+}
+
+function pickerButtonClass(active: boolean): string {
+  return `flex min-h-[32px] items-baseline justify-between gap-sp-3 rounded-r-2 border px-sp-3 py-1.5 text-left font-mono ${
+    active ? "border-accent bg-accent-tint" : "border-border bg-surface-2 hover:border-border-strong"
+  }`;
+}
+
+export interface SpawnFormProps {
+  seed?: SpawnFormSeed;
+  /** Fired whenever any value changes, once the form's initial seed settles. */
+  onChange?(values: SpawnFormValues): void;
+  onSuccess(session: Session): void;
+  /** When true, hides the built-in submit button (the modal provides its own). */
+  externalSubmit?: boolean;
+}
+
+export function SpawnForm({ seed, onChange, onSuccess, externalSubmit }: SpawnFormProps) {
+  const prefill = useRef(seed ?? {}).current;
+
+  const formRef = useRef<HTMLFormElement>(null);
+  const filterInputRef = useRef<HTMLInputElement>(null);
+  const customCommandRef = useRef<HTMLInputElement>(null);
+  const rawCwdRef = useRef<HTMLInputElement>(null);
+  const destroyedRef = useRef(false);
+  useEffect(() => () => {
+    destroyedRef.current = true;
+  }, []);
+
+  // ---- harness / command -------------------------------------------------
+  const [homeDir, setHomeDir] = useState("");
+  const [infoLoading, setInfoLoading] = useState(true);
+  const [presets, setPresets] = useState<SpawnPreset[]>(FALLBACK_PRESETS);
+  const [selectedPresetId, setSelectedPresetId] = useState("");
+  const [command, setCommand] = useState("");
+  const [customCommand, setCustomCommand] = useState("");
+  const [commandTouched, setCommandTouched] = useState(false);
+  const [structuredView, setStructuredView] = useState(false);
+  const [structuredTouched, setStructuredTouched] = useState(false);
+
+  const activePreset = useMemo(() => presets.find((p) => p.id === selectedPresetId), [presets, selectedPresetId]);
+  const isCustomSelected = !activePreset || activePreset.command === "";
+
+  useEffect(() => {
+    if (commandTouched && isCustomSelected) customCommandRef.current?.focus();
+  }, [isCustomSelected, commandTouched]);
+
+  useEffect(() => {
+    let cancelled = false;
+    getDaemonInfo()
+      .then((info) => {
+        if (cancelled) return;
+        setHomeDir(info.home_dir ?? "");
+        if (info.presets?.length) setPresets(info.presets);
+      })
+      .catch(() => {
+        // keep fallbacks
+      })
+      .finally(() => {
+        if (!cancelled) setInfoLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Pick a sensible starting command whenever the preset list changes and the
+  // operator hasn't touched it yet: a seed's command (matched to a preset, or
+  // dropped into custom), else the first non-custom preset.
+  useEffect(() => {
+    if (commandTouched) return;
+    const wanted = prefill.command;
+    if (wanted) {
+      const match = presets.find((p) => p.command === wanted && p.command !== "");
+      if (match) {
+        setSelectedPresetId(match.id);
+        setCommand(match.command);
+        return;
+      }
+      const custom = presets.find((p) => p.command === "");
+      setCustomCommand(wanted);
+      setSelectedPresetId(custom ? custom.id : "custom");
+      setCommand(wanted);
+      return;
+    }
+    const first = presets.find((p) => p.command !== "");
+    if (first) {
+      setSelectedPresetId(first.id);
+      setCommand(first.command);
+    }
+    // prefill is captured once at construction, not a reactive dependency.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [presets, commandTouched]);
+
+  const structuredSupported = useMemo(() => supportsStructuredView(command), [command]);
+  useEffect(() => {
+    if (!structuredSupported) setStructuredView(false);
+    else if (!structuredTouched) setStructuredView(true);
+  }, [structuredSupported, structuredTouched]);
+
+  // ---- project picker ------------------------------------------------------
+  const [discovered, setDiscovered] = useState<Project[]>([]);
+  const [projectsLoading, setProjectsLoading] = useState(true);
+  const [filterQuery, setFilterQuery] = useState("");
+  const [cwd, setCwd] = useState("");
+  const [cwdRawVisible, setCwdRawVisible] = useState(false);
+  const [rawFocusToken, setRawFocusToken] = useState(0);
+  const [selectedGroupPath, setSelectedGroupPath] = useState<string | null>(null);
+  const [worktreeChoice, setWorktreeChoice] = useState<WorktreeChoice>("new");
+
+  const groups = useMemo(() => groupProjects(sortProjects(discovered, new Date())), [discovered]);
+  const visibleGroups = useMemo(
+    () => groups.filter((g) => filterProjects([g.main, ...g.worktrees], filterQuery).length > 0),
+    [groups, filterQuery],
+  );
+  const selectedGroup = useMemo(
+    () => groups.find((g) => g.main.path === selectedGroupPath) ?? null,
+    [groups, selectedGroupPath],
+  );
+
+
+  useEffect(() => {
+    let cancelled = false;
+    fetchProjects()
+      .then((list) => {
+        if (!cancelled) setDiscovered(list);
+      })
+      .catch(() => {
+        if (!cancelled) setDiscovered([]);
+      })
+      .finally(() => {
+        if (!cancelled) setProjectsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // ---- worktree (branch-only; base_repo inferred via scan or /gitroot) ----
+  const [wtEnabled, setWtEnabled] = useState(prefill.worktreeEnabled ?? true);
+  const [inferredBaseRepo, setInferredBaseRepo] = useState<string | null>(null);
+  const [wtHint, setWtHint] = useState<string | null>(null);
+  const [name, setName] = useState(prefill.name ?? "");
+  const [branchEdited, setBranchEdited] = useState(Boolean(prefill.worktreeBranchEdited));
+  const [branchMode, setBranchMode] = useState<WorktreeBranchMode>(prefill.worktreeBranchMode ?? "new");
+  const [newBranch, setNewBranch] = useState(prefill.worktreeBranch ?? "");
+  const [existingBranch, setExistingBranch] = useState("");
+  const [branchCache, setBranchCache] = useState<{ cwd: string; branches: BranchInfo[] } | null>(null);
+
+  const [advancedCollapsed, setAdvancedCollapsed] = useState(true);
+  const [error, setError] = useState("");
+  const [, setSubmitting] = useState(false);
+  const [ready, setReady] = useState(false);
+
+  const probeTokenRef = useRef(0);
+  const probeTimerRef = useRef<number | undefined>(undefined);
+
+  const applyBaseRepoResolution = useCallback((res: BaseRepoResolution) => {
+    switch (res.kind) {
+      case "disabled":
+        setInferredBaseRepo(null);
+        setWtHint(null);
+        return;
+      case "no-cwd":
+        setInferredBaseRepo(null);
+        setWtHint("Choose a working directory first.");
+        return;
+      case "found":
+        setInferredBaseRepo(res.repo);
+        setWtHint(null);
+        setBranchCache(null);
+        setExistingBranch("");
+        return;
+      case "probe":
+        return; // caller schedules the probe
+    }
+  }, []);
+
+  const probeGitRoot = useCallback(async (path: string) => {
+    const token = ++probeTokenRef.current;
+    if (!path) {
+      setInferredBaseRepo(null);
+      setWtHint("Choose a working directory first.");
+      return;
+    }
+    setWtHint("Checking for a git repository…");
+    let root: string | undefined;
+    try {
+      root = (await gitRoot(path)).root;
+    } catch {
+      root = undefined;
+    }
+    if (token !== probeTokenRef.current || destroyedRef.current) return; // a newer probe superseded us
+    if (root) {
+      setInferredBaseRepo(root);
+      setWtHint(null);
+      setBranchCache(null);
+      setExistingBranch("");
+    } else {
+      setInferredBaseRepo(null);
+      // Publish the untick too, or a later submit fails with an inferred repo
+      // that no longer matches an unticked box.
+      setWtEnabled(false);
+      setWtHint("Not inside a git repository — pick a dir in a repo to use a worktree.");
+    }
+  }, []);
+
+  const scheduleGitRootProbe = useCallback(
+    (path: string) => {
+      window.clearTimeout(probeTimerRef.current);
+      probeTimerRef.current = window.setTimeout(() => {
+        probeTimerRef.current = undefined;
+        void probeGitRoot(path);
+      }, GITROOT_PROBE_DEBOUNCE_MS);
+    },
+    [probeGitRoot],
+  );
+  useEffect(() => () => window.clearTimeout(probeTimerRef.current), []);
+
+  // Seed the form once the initial project scan and daemon info have both
+  // settled — mirrors createSpawnForm's `loadProjects()`. Computed from local
+  // values rather than reading state back, since the setState calls below
+  // won't have committed yet within this same effect.
+  const seededRef = useRef(false);
+  useEffect(() => {
+    if (infoLoading || projectsLoading || seededRef.current) return;
+    seededRef.current = true;
+
+    const seedCwd = prefill.cwd ?? null;
+    let finalCwd = "";
+    let finalCwdRawVisible = false;
+    let finalGroupPath: string | null = null;
+    let finalChoice: WorktreeChoice = "new";
+
+    const restore = (path: string): boolean => {
+      for (const group of groups) {
+        const wt = worktreesOf(group).find((p) => p.path === path);
+        const choice: WorktreeChoice | null = wt ? wt.path : group.main.path === path ? "new" : null;
+        if (choice === null) continue;
+        finalGroupPath = group.main.path;
+        finalChoice = choice;
+        return true;
+      }
+      return false;
+    };
+
+    if (seedCwd) {
+      if (prefill.cwdRawVisible === false) {
+        finalCwd = seedCwd;
+        if (!restore(seedCwd)) finalCwdRawVisible = true;
+      } else {
+        finalCwd = seedCwd;
+        finalCwdRawVisible = true;
+      }
+    } else if (discovered.length === 0) {
+      finalCwd = homeDir;
+      finalCwdRawVisible = true;
+    }
+
+    setCwd(finalCwd);
+    setCwdRawVisible(finalCwdRawVisible);
+    setSelectedGroupPath(finalGroupPath);
+    setWorktreeChoice(finalChoice);
+
+    const res = resolveBaseRepoFor(finalCwd, wtEnabled, discovered);
+    applyBaseRepoResolution(res);
+    if (res.kind === "probe") scheduleGitRootProbe(finalCwd);
+
+    setReady(true);
+    // groups/wtEnabled/discovered/homeDir are read for this one settle pass;
+    // re-running on their later changes would re-seed a form the operator
+    // has since edited.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [infoLoading, projectsLoading]);
+
+  // ---- name (also seeds the worktree branch) ------------------------------
+  const skipInitialBranchSync = useRef(Boolean(prefill.worktreeBranch));
+  useEffect(() => {
+    // One-time construction seeding, mirroring spawnForm.ts precedence: an
+    // explicit seed wins outright; otherwise the prefilled name; otherwise a
+    // freshly generated handle (#53).
+    if (prefill.worktreeBranch) return;
+    if (!branchEdited && branchMode === "new" && prefill.name) return; // handled below, mount-only
+    if (!branchEdited && branchMode === "new") {
+      void fetchNames(1)
+        .then((batch) => {
+          const handle = batch.names[0];
+          if (destroyedRef.current || !handle) return;
+          setNewBranch((cur) => cur || handle);
+        })
+        .catch(() => {
+          // the operator types their own branch
+        });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (!skipInitialBranchSync.current && !branchEdited && branchMode === "new" && name) {
+      setNewBranch(name);
+    }
+    skipInitialBranchSync.current = false;
+    // A cleared name leaves the branch on its last value; only `name` changes
+    // (typed or the mount-time prefill) drive this sync.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [name]);
+
+  // ---- existing-branch picker (#61): fetch once per cwd -------------------
+  useEffect(() => {
+    if (branchMode !== "existing" || !cwd || !inferredBaseRepo) return;
+    if (branchCache?.cwd === cwd) return;
+    let cancelled = false;
+    const target = cwd;
+    fetchBranches(target)
+      .then((branches) => {
+        if (cancelled || destroyedRef.current) return;
+        setBranchCache({ cwd: target, branches });
+      })
+      .catch(() => {
+        // the picker just stays empty; "new" mode still works
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [branchMode, cwd, inferredBaseRepo, branchCache]);
+
+  const branchesForCwd = branchCache?.cwd === cwd ? branchCache.branches : undefined;
+
+  // A native <select> defaults its displayed (and reported) value to the
+  // first enabled option once nothing is explicitly selected. Derived at
+  // render/submit time rather than synced via an effect, so there is no
+  // window where the control shows one branch while state still holds "".
+  const effectiveExistingBranch =
+    existingBranch || branchesForCwd?.find((b) => !b.worktree && !b.is_head)?.name || "";
+
+  // ---- emit (#observability parity with spawnForm.ts's onChange) ---------
+  useEffect(() => {
+    if (!ready) return;
+    onChange?.({
+      command,
+      cwd,
+      name,
+      structuredView,
+      autoApprove: activePreset?.auto_approve ?? false,
+      worktreeEnabled: wtEnabled,
+      worktreeBranch: branchMode === "existing" ? effectiveExistingBranch : newBranch,
+      worktreeBranchEdited: branchEdited,
+      worktreeBranchMode: branchMode,
+      cwdRawVisible,
+    });
+  }, [
+    ready,
+    command,
+    cwd,
+    name,
+    structuredView,
+    activePreset,
+    wtEnabled,
+    branchMode,
+    effectiveExistingBranch,
+    newBranch,
+    branchEdited,
+    cwdRawVisible,
+    onChange,
+  ]);
+
+  // ---- handlers -------------------------------------------------------------
+  const selectPreset = useCallback(
+    (id: string) => {
+      setCommandTouched(true);
+      setSelectedPresetId(id);
+      const preset = presets.find((p) => p.id === id);
+      if (!preset || preset.command === "") setCommand(customCommand.trim());
+      else setCommand(preset.command);
+    },
+    [presets, customCommand],
+  );
+
+  const clearProjectSelection = useCallback(() => {
+    setSelectedGroupPath(null);
+    setWorktreeChoice("new");
+  }, []);
+
+  const showRawCwd = useCallback(
+    (prefillValue?: string, focus = true) => {
+      setCwdRawVisible(true);
+      if (prefillValue != null) setCwd(prefillValue);
+      clearProjectSelection();
+      if (focus) setRawFocusToken((t) => t + 1);
+    },
+    [clearProjectSelection],
+  );
+
+  useEffect(() => {
+    if (rawFocusToken === 0) return;
+    rawCwdRef.current?.focus();
+    rawCwdRef.current?.select();
+  }, [rawFocusToken]);
+
+  const applyWorktreeChoice = useCallback(
+    (group: ProjectGroup, choice: WorktreeChoice) => {
+      const target = choice === "new" ? group.main : worktreesOf(group).find((p) => p.path === choice);
+      if (!target) return;
+      setWorktreeChoice(choice);
+      setCwd(target.path);
+      setBranchCache(null);
+      setExistingBranch("");
+      if (choice === "new") {
+        setWtEnabled(true);
+        applyBaseRepoResolution({ kind: "found", repo: group.main.base_repo ?? group.main.path });
+      } else {
+        setWtEnabled(false);
+        applyBaseRepoResolution({ kind: "disabled" });
+      }
+    },
+    [applyBaseRepoResolution],
+  );
+
+  const selectProject = useCallback(
+    (group: ProjectGroup) => {
+      setSelectedGroupPath(group.main.path);
+      setCwdRawVisible(false);
+      // Rule 4: a box that is itself a linked worktree defaults to running there.
+      applyWorktreeChoice(group, group.main.is_worktree ? group.main.path : "new");
+    },
+    [applyWorktreeChoice],
+  );
+
+  const onWtEnabledChange = useCallback(
+    (next: boolean) => {
+      setWtEnabled(next);
+      const res = resolveBaseRepoFor(cwd, next, discovered);
+      applyBaseRepoResolution(res);
+      if (res.kind === "probe") scheduleGitRootProbe(cwd);
+    },
+    [cwd, discovered, applyBaseRepoResolution, scheduleGitRootProbe],
+  );
+
+  const onRawCwdChange = useCallback(
+    (v: string) => {
+      setCwd(v);
+      setBranchCache(null);
+      setExistingBranch("");
+      if (wtEnabled) scheduleGitRootProbe(v);
+    },
+    [wtEnabled, scheduleGitRootProbe],
+  );
+
+  const onSubmit = useCallback(
+    async (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      setError("");
+      const values: SpawnFormValues = {
+        command,
+        cwd,
+        name,
+        structuredView,
+        autoApprove: activePreset?.auto_approve ?? false,
+        worktreeEnabled: wtEnabled,
+        worktreeBranch: branchMode === "existing" ? effectiveExistingBranch : newBranch,
+        worktreeBranchEdited: branchEdited,
+        worktreeBranchMode: branchMode,
+      };
+      const built = buildSpawnRequest(values, inferredBaseRepo);
+      if ("error" in built) {
+        setError(built.error);
+        return;
+      }
+      setSubmitting(true);
+      try {
+        const session = await createSession(built.req);
+        onSuccess(session);
+      } catch (err) {
+        setError((err as Error).message);
+        setSubmitting(false);
+      }
+    },
+    [
+      command,
+      cwd,
+      name,
+      structuredView,
+      activePreset,
+      wtEnabled,
+      branchMode,
+      effectiveExistingBranch,
+      newBranch,
+      branchEdited,
+      inferredBaseRepo,
+      onSuccess,
+    ],
+  );
+
+  // ---- Enter submits from anywhere (#97) ------------------------------------
+  const onFormKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLFormElement>) => {
+      if (e.key !== "Enter" || e.defaultPrevented) return;
+      const target = e.target as HTMLElement;
+
+      if (target.dataset.role === "toggle") {
+        e.preventDefault();
+        (target as HTMLInputElement).click();
+        return;
+      }
+
+      if (target instanceof HTMLButtonElement && target.dataset.picker) {
+        e.preventDefault();
+        if (target.dataset.active === "true") {
+          formRef.current?.requestSubmit();
+        } else {
+          target.click();
+        }
+        return;
+      }
+
+      e.preventDefault();
+      if (target === filterInputRef.current) {
+        // Resolve the filter to a project only when the current pick isn't
+        // one of the matches: a filter typed past it means the operator
+        // moved on, while a pick that still matches keeps its worktree choice.
+        const stillMatches =
+          selectedGroup != null && visibleGroups.some((g) => g.main.path === selectedGroup.main.path);
+        if (!stillMatches && visibleGroups[0]) selectProject(visibleGroups[0]);
+      }
+      formRef.current?.requestSubmit();
+    },
+    [selectedGroup, visibleGroups, selectProject],
+  );
+
+  return (
+    <form
+      id="spawn-form"
+      ref={formRef}
+      onSubmit={onSubmit}
+      onKeyDown={onFormKeyDown}
+      className="mx-auto flex w-full max-w-[60ch] flex-col gap-sp-2 overflow-auto p-sp-3"
+    >
+      <div className="flex flex-col gap-sp-2">
+        <span className="text-fs-13 text-ink">Harness</span>
+        <div className="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-sp-2">
+          {presets.map((p) => {
+            const isCustom = p.command === "";
+            const toolId = presetToolId(p);
+            const icon = isCustom ? null : toolId ? harnessIcon(toolId) : harnessIcon("shell");
+            const label = TOOL_LABELS[toolId ?? ""] ?? p.label;
+            const active = p.id === selectedPresetId;
+            return (
+              <button
+                key={p.id}
+                type="button"
+                className={`flex flex-col items-center gap-sp-2 rounded-r-2 border px-sp-2 py-sp-3 text-center ${
+                  active
+                    ? "border-accent bg-accent-tint"
+                    : isCustom
+                      ? "border-dashed border-border text-muted"
+                      : "border-border bg-surface-2 hover:border-border-strong"
+                }`}
+                onClick={() => selectPreset(p.id)}
+              >
+                <span
+                  className={`flex h-8 w-8 items-center justify-center ${active ? "text-ink" : "text-muted"}`}
+                  aria-hidden={icon ? undefined : true}
+                  dangerouslySetInnerHTML={icon ? { __html: icon } : undefined}
+                >
+                  {icon ? undefined : "…"}
+                </span>
+                <span className="max-w-full truncate text-fs-13 font-semibold">
+                  {isCustom ? "Custom…" : label}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+        <input
+          ref={customCommandRef}
+          className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+          name="command_raw"
+          type="text"
+          hidden={!isCustomSelected}
+          placeholder="bash -l"
+          autoComplete="off"
+          value={customCommand}
+          onChange={(e) => {
+            const v = e.currentTarget.value;
+            setCustomCommand(v);
+            if (isCustomSelected) {
+              setCommandTouched(true);
+              setCommand(v.trim());
+            }
+          }}
+        />
+      </div>
+
+      <div className="flex flex-col gap-sp-2">
+        <span className="text-fs-13 text-ink">Project</span>
+        <input
+          ref={filterInputRef}
+          className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+          type="text"
+          placeholder="Filter projects…"
+          autoComplete="off"
+          value={filterQuery}
+          onChange={(e) => setFilterQuery(e.currentTarget.value)}
+        />
+        {!ready ? (
+          <p className="m-0 px-sp-3 py-1.5 text-fs-13 text-faint">Loading projects…</p>
+        ) : (
+          <div className="grid max-h-[300px] grid-cols-2 gap-sp-2 overflow-y-auto p-px">
+            {visibleGroups.map((group) => {
+              const active = selectedGroup?.main.path === group.main.path;
+              return (
+                <button
+                  key={group.main.path}
+                  type="button"
+                  data-picker="project"
+                  data-active={active || undefined}
+                  className={`flex min-w-0 flex-col gap-0.5 rounded-r-2 border px-sp-3 py-sp-2 text-left ${
+                    active ? "border-accent bg-accent-tint" : "border-border bg-surface-2 hover:border-border-strong"
+                  } ${isStale(group.main, new Date()) ? "opacity-55" : ""}`}
+                  onClick={() => selectProject(group)}
+                >
+                  <span className="truncate text-fs-13 font-semibold text-ink">{group.main.name}</span>
+                  <span className="break-words font-mono text-fs-12 text-muted">
+                    {abbreviateCwd(parentDir(group.main.path), homeDir)}
+                  </span>
+                </button>
+              );
+            })}
+            {discovered.length > 0 && visibleGroups.length === 0 && (
+              <p className="col-span-2 m-0 px-sp-3 py-1.5 text-fs-13 text-faint">No projects match.</p>
+            )}
+          </div>
+        )}
+        <button
+          type="button"
+          className="self-start bg-transparent px-0 py-1 text-fs-13 italic text-muted hover:text-ink"
+          onClick={() => showRawCwd(cwd || homeDir)}
+        >
+          Other directory…
+        </button>
+        {cwdRawVisible && (
+          <DirAutocomplete
+            inputRef={rawCwdRef}
+            className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+            name="cwd_raw"
+            type="text"
+            placeholder="/home/user/project"
+            value={cwd}
+            onChange={onRawCwdChange}
+          />
+        )}
+      </div>
+
+      <div className="flex flex-col border-t border-border pt-sp-2">
+        <button
+          type="button"
+          className="flex w-full items-center gap-sp-1 py-sp-2 text-left text-fs-11 text-muted"
+          aria-expanded={!advancedCollapsed}
+          onClick={() => setAdvancedCollapsed((c) => !c)}
+        >
+          <span className={`inline-block transition-transform ${advancedCollapsed ? "-rotate-90" : ""}`}>▾</span>
+          <span className="font-semibold">Advanced</span>
+          <span className="ml-auto text-fs-12 text-muted">{wtEnabled ? "creates a worktree" : "no worktree"}</span>
+        </button>
+        {!advancedCollapsed && (
+          <div className="flex flex-col gap-sp-3 py-sp-2">
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              Session name
+              <input
+                name="name"
+                type="text"
+                autoComplete="off"
+                placeholder="named after your first prompt"
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+                value={name}
+                onChange={(e) => setName(e.currentTarget.value)}
+              />
+            </label>
+
+            {structuredSupported && (
+              <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+                <input
+                  type="checkbox"
+                  data-role="toggle"
+                  className="size-[18px] accent-accent"
+                  checked={structuredView}
+                  onChange={(e) => {
+                    setStructuredTouched(true);
+                    setStructuredView(e.currentTarget.checked);
+                  }}
+                />
+                Structured view
+              </label>
+            )}
+
+            {selectedGroup && (
+              <div className="flex flex-col gap-sp-2">
+                <span className="text-fs-13 text-ink">Worktree</span>
+                <div className="flex max-h-[200px] flex-col gap-sp-1 overflow-y-auto">
+                  <button
+                    type="button"
+                    data-picker="worktree"
+                    data-active={worktreeChoice === "new" || undefined}
+                    className={pickerButtonClass(worktreeChoice === "new")}
+                    onClick={() => applyWorktreeChoice(selectedGroup, "new")}
+                  >
+                    <span className="text-fs-13 font-semibold text-accent">+ new</span>
+                    <span className="text-right text-fs-12 text-muted">
+                      new worktree of {selectedGroup.main.name}
+                    </span>
+                  </button>
+                  {worktreesOf(selectedGroup).map((wt) => (
+                    <button
+                      key={wt.path}
+                      type="button"
+                      data-picker="worktree"
+                      data-active={worktreeChoice === wt.path || undefined}
+                      className={pickerButtonClass(worktreeChoice === wt.path)}
+                      onClick={() => applyWorktreeChoice(selectedGroup, wt.path)}
+                    >
+                      <span className="text-fs-13 font-semibold text-ink">{wt.name}</span>
+                      <span className="text-right text-fs-12 text-muted">{wt.path}</span>
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            <BranchPicker
+              enabled={wtEnabled}
+              onToggleEnabled={onWtEnabledChange}
+              hint={wtHint}
+              baseRepo={inferredBaseRepo}
+              mode={branchMode}
+              onModeChange={setBranchMode}
+              newBranch={newBranch}
+              onNewBranchChange={(v) => {
+                setBranchEdited(true);
+                setNewBranch(v);
+              }}
+              branches={branchesForCwd}
+              existingBranch={effectiveExistingBranch}
+              onExistingBranchChange={setExistingBranch}
+            />
+          </div>
+        )}
+      </div>
+
+      <p role="alert" aria-live="polite" className={`m-0 text-fs-13 text-danger ${error ? "rounded-r-2 bg-danger-tint px-sp-3 py-sp-2" : "min-h-[1.2em]"}`}>
+        {error}
+      </p>
+      {!externalSubmit && (
+        <div className="flex justify-end">
+          <button
+            type="submit"
+            className="btn btn-primary rounded-r-1 px-sp-4 py-sp-1 text-fs-13 font-semibold"
+          >
+            Spawn
+          </button>
+        </div>
+      )}
+    </form>
+  );
+}

web/src/components/spawn/SpawnModal.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { DaemonInfo, Project, Session } from "../../types.js";
+import { SpawnModal } from "./SpawnModal.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchBranches: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  gitRoot: vi.fn(),
+  listDir: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import { createSession, fetchNames, getDaemonInfo, listDir, projects as fetchProjects } from "../../api.js";
+
+function info(): DaemonInfo {
+  return { hostname: "h", version: "1", home_dir: "/home/n", presets: [{ id: "claude", label: "Claude", command: "claude" }] };
+}
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", ...over };
+}
+
+beforeEach(() => {
+  vi.mocked(getDaemonInfo).mockResolvedValue(info());
+  vi.mocked(fetchProjects).mockResolvedValue([project()]);
+  vi.mocked(fetchNames).mockResolvedValue({ names: ["amber-fox"] });
+  vi.mocked(listDir).mockResolvedValue({ path: "", entries: [] });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+async function settle() {
+  await waitFor(() => expect(screen.queryByText("Loading projects…")).toBeNull());
+}
+
+describe("SpawnModal", () => {
+  it("mounts the spawn form inside a dialog", async () => {
+    render(<SpawnModal onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByRole("dialog")).not.toBeNull();
+    expect(screen.getByRole("button", { name: "Spawn" })).not.toBeNull();
+  });
+
+  it("titles a seeded open as a clone", async () => {
+    render(<SpawnModal seed={{ command: "claude" }} onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByText("Spawn similar")).not.toBeNull();
+  });
+
+  it("titles a plain open as a new session", async () => {
+    render(<SpawnModal onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByText("Spawn session")).not.toBeNull();
+  });
+
+  it("closes on Escape, on Cancel and on a backdrop click", async () => {
+    const onClose = vi.fn();
+    const { unmount } = render(<SpawnModal onSuccess={vi.fn()} onClose={onClose} />);
+    await settle();
+
+    fireEvent.keyDown(screen.getByRole("dialog"), { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onClose).toHaveBeenCalledTimes(2);
+    unmount();
+
+    render(<SpawnModal onSuccess={vi.fn()} onClose={onClose} />);
+    await settle();
+    fireEvent.click(document.querySelector(".modal-backdrop")!);
+    expect(onClose).toHaveBeenCalledTimes(3);
+  });
+
+  it("closes before handing the created session to its caller", async () => {
+    const created: Session = {
+      id: "s1",
+      cwd: "/repos/p",
+      command: "claude",
+      env: {},
+      metadata: {},
+      status: "Running",
+      created_at: "2026-01-01T00:00:00Z",
+    };
+    vi.mocked(createSession).mockResolvedValue(created);
+    const calls: string[] = [];
+    const onClose = vi.fn(() => calls.push("close"));
+    const onSuccess = vi.fn(() => calls.push("success"));
+    render(<SpawnModal onSuccess={onSuccess} onClose={onClose} />);
+    await settle();
+    fireEvent.click(screen.getByText("p"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith(created));
+    expect(calls).toEqual(["close", "success"]);
+  });
+});

web/src/components/spawn/SpawnModal.tsx

@@ -0,0 +1,89 @@
+// React port of ../../spawnModal.ts: dialog chrome around SpawnForm. Escape,
+// the ✕ and a click on the backdrop all close it; SpawnForm's own DirAutocomplete
+// swallows Escape first, so dismissing a dropdown never also discards the form.
+
+import { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+
+import type { Session } from "../../types.js";
+import { SpawnForm, type SpawnFormProps } from "./SpawnForm.js";
+
+export interface SpawnModalProps {
+  seed?: SpawnFormProps["seed"];
+  /** Called with the created session after a successful submit — the modal
+   * has already closed by then, so the caller decides where it lands. */
+  onSuccess(session: Session): void;
+  onClose(): void;
+}
+
+export function SpawnModal({ seed, onSuccess, onClose }: SpawnModalProps) {
+  const filterInputRef = useRef<HTMLInputElement>(null);
+
+  const handleSuccess = (session: Session) => {
+    onClose();
+    onSuccess(session);
+  };
+
+  // The project filter owns the keyboard on open: typing narrows the list and
+  // Tab from here reaches the harness tiles, matching the TUI's draft pane.
+  useEffect(() => {
+    const host = filterInputRef.current;
+    host?.querySelector<HTMLInputElement>("input[placeholder='Filter projects…']")?.focus();
+  }, []);
+
+  return createPortal(
+    <div
+      className="modal-backdrop fixed inset-0 z-modal flex items-center justify-center bg-bg/70 backdrop-blur-sm"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="spawn-title"
+        className="flex max-h-[92vh] w-full max-w-[560px] flex-col rounded-r-3 border border-border bg-surface shadow-2"
+        onKeyDown={(e) => {
+          if (e.key === "Escape" && !e.defaultPrevented) {
+            e.preventDefault();
+            onClose();
+          }
+        }}
+      >
+        <header className="flex items-center justify-between border-b border-border p-sp-3">
+          <h2 id="spawn-title" className="m-0 text-fs-15 font-semibold text-ink">
+            {seed ? "Spawn similar" : "Spawn session"}
+          </h2>
+          <button
+            type="button"
+            aria-label="Close"
+            className="rounded-r-1 px-sp-2 py-1 text-fs-15 text-muted hover:text-ink"
+            onClick={onClose}
+          >
+            ✕
+          </button>
+        </header>
+        <div ref={filterInputRef} className="min-h-0 flex-1 overflow-auto">
+          <SpawnForm seed={seed} onSuccess={handleSuccess} externalSubmit />
+        </div>
+        <div className="flex justify-end gap-sp-2 border-t border-border p-sp-3">
+          <button
+            type="button"
+            className="rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-13 text-ink"
+            onClick={onClose}
+          >
+            Cancel
+          </button>
+          <button
+            type="submit"
+            form="spawn-form"
+            className="btn btn-primary rounded-r-1 px-sp-4 py-sp-1 text-fs-13 font-semibold"
+          >
+            Spawn
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/spawn/index.ts

@@ -0,0 +1,8 @@
+export { SpawnModal, type SpawnModalProps } from "./SpawnModal.js";
+export { SpawnForm, type SpawnFormProps } from "./SpawnForm.js";
+export { DirAutocomplete, type DirAutocompleteProps } from "./DirAutocomplete.js";
+export { BranchPicker, type BranchPickerProps } from "./BranchPicker.js";
+export { useFastForward, type UseFastForwardOptions } from "./useFastForward.js";
+// spawnSimilar.ts is pure seed-building logic with no DOM dependency — reused
+// as-is rather than re-implemented for React (#248).
+export { spawnSimilarSeed, spawnSimilarProjectSeed } from "./spawnSimilar.js";

web/src/components/spawn/model.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { buildSpawnRequest, type SpawnFormValues } from "./spawnForm.js";
+import { buildSpawnRequest, type SpawnFormValues } from "./model.js";
 
 const base: SpawnFormValues = {
   command: "claude",

web/src/components/spawn/model.ts

@@ -0,0 +1,104 @@
+// Pure spawn-form model, kept when spawnForm.ts's imperative DOM form was
+// deleted (#253): the value/seed shapes, the request builder, and the preset
+// fallback. SpawnForm.tsx and useFastForward.ts render from these.
+
+import { splitCommand } from "../../toolIcon.js";
+import type { CreateSessionRequest, SpawnPreset } from "../../types.js";
+
+export const STRUCTURED_VIEW_TOOLS = new Set(["claude", "codex"]);
+
+export function supportsStructuredView(command: string): boolean {
+  const tool = splitCommand(command).tool;
+  return tool !== null && STRUCTURED_VIEW_TOOLS.has(tool);
+}
+
+/** Where a worktree's branch comes from: freshly created (default) or picked
+ * from the repository's existing branches (#61). */
+export type WorktreeBranchMode = "new" | "existing";
+
+/** Seed values for the spawn form — used by "Spawn similar" to open the modal
+ * with the same cwd, command, and name as an existing session, and by the
+ * fast-forward fallback to pre-fill whatever it did resolve. */
+export interface SpawnFormSeed {
+  command?: string;
+  cwd?: string;
+  name?: string;
+  worktreeEnabled?: boolean;
+  worktreeBranch?: string;
+  /** Whether the operator typed the branch themselves, rather than it having
+   *  been auto-synced from the session name. Carried separately because the
+   *  value alone cannot distinguish the two. */
+  worktreeBranchEdited?: boolean;
+  worktreeBranchMode?: WorktreeBranchMode;
+  cwdRawVisible?: boolean;
+}
+
+/** The form's current values, reported on every change. */
+export interface SpawnFormValues {
+  command: string;
+  cwd: string;
+  name: string;
+  structuredView: boolean;
+  autoApprove: boolean;
+  worktreeEnabled: boolean;
+  worktreeBranch: string;
+  worktreeBranchEdited: boolean;
+  /** "new" creates the branch; "existing" checks out a picked one (#61). */
+  worktreeBranchMode: WorktreeBranchMode;
+  /** Whether the cwd lives in the raw text input (vs a picked recent row). */
+  cwdRawVisible?: boolean;
+}
+
+export function buildSpawnRequest(
+  values: SpawnFormValues,
+  baseRepo: string | null,
+): { req: CreateSessionRequest } | { error: string } {
+  if (!values.cwd) return { error: "Pick a working directory." };
+  if (!values.command) return { error: "Pick a command (or fill the custom command)." };
+
+  const metadata: Record<string, unknown> = {};
+  const name = values.name.trim();
+  if (name) metadata.name = name;
+
+  const req: CreateSessionRequest = {
+    cwd: values.cwd,
+    command: values.command,
+    metadata,
+  };
+
+  if (values.structuredView && supportsStructuredView(values.command)) {
+    req.view = "Structured";
+  }
+
+  if (values.autoApprove) {
+    req.auto_approve = true;
+  }
+
+  if (values.worktreeEnabled) {
+    const mode = values.worktreeBranchMode ?? "new";
+    const branch = values.worktreeBranch.trim();
+    if (!baseRepo) return { error: "Worktree needs a directory inside a git repository." };
+    if (!branch) {
+      return { error: mode === "existing" ? "Pick an existing branch." : "Worktree requires a branch name." };
+    }
+    req.worktree = {
+      base_repo: baseRepo,
+      branch,
+      // Existing-mode picks must check out as-is; the daemon creates
+      // anything else with `worktree add -b` (#56/#61).
+      create_branch: mode !== "existing",
+    };
+  }
+
+  return { req };
+}
+
+/** Built-ins used when the daemon's `/api/info` presets can't be fetched
+ * (older daemon, transient error). Mirrors `maestro_config::builtin_presets`.
+ * Exported for the fast-forward spawn's preset fallback (#67). */
+export const FALLBACK_PRESETS: SpawnPreset[] = [
+  { id: "claude", label: "Claude", command: "claude" },
+  { id: "opencode", label: "opencode", command: "opencode" },
+  { id: "zsh", label: "Shell", command: "zsh" },
+  { id: "custom", label: "Custom…", command: "" },
+];

web/src/components/spawn/spawnSimilar.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { spawnSimilarProjectSeed, spawnSimilarSeed } from "./spawnSimilar.js";
-import type { Session } from "./types.js";
+import type { Session } from "../../types.js";
 
 function session(overrides: Partial<Session> = {}): Session {
   return {

web/src/components/spawn/spawnSimilar.ts

@@ -1,8 +1,8 @@
 // "Spawn similar" (#28): the seed a cloned session hands to the spawn modal.
 // Pure — the caller owns opening the dialog.
 
-import type { SpawnFormSeed } from "./spawnForm.js";
-import type { Session } from "./types.js";
+import type { SpawnFormSeed } from "./model.js";
+import type { Session } from "../../types.js";
 
 /** Clone a session into form values: same project, same command, same
  *  worktree decision, fresh name.

web/src/components/spawn/useFastForward.test.ts

@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { Project, Session, SpawnPreset } from "../../types.js";
+import { useFastForward } from "./useFastForward.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import { createSession, fetchNames, getDaemonInfo, projects as fetchProjects } from "../../api.js";
+
+const mockCreateSession = vi.mocked(createSession);
+const mockFetchNames = vi.mocked(fetchNames);
+const mockGetDaemonInfo = vi.mocked(getDaemonInfo);
+const mockFetchProjects = vi.mocked(fetchProjects);
+
+const presets: SpawnPreset[] = [{ id: "claude", label: "Claude", command: "claude" }];
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", base_repo: "/repos/p", last_command: "claude", ...over };
+}
+
+function session(): Session {
+  return {
+    id: "s1",
+    cwd: "/repos/p",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+  };
+}
+
+afterEach(() => vi.clearAllMocks());
+
+describe("useFastForward", () => {
+  it("spawns immediately once every default resolves", async () => {
+    mockFetchProjects.mockResolvedValue([project()]);
+    mockFetchNames.mockResolvedValue({ names: ["amber-fox"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    const created = session();
+    mockCreateSession.mockResolvedValue(created);
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cwd: "/repos/p",
+        command: "claude",
+        worktree: { base_repo: "/repos/p", branch: "amber-fox", create_branch: true },
+      }),
+    );
+    expect(onSpawned).toHaveBeenCalledWith(created);
+    expect(onFallback).not.toHaveBeenCalled();
+  });
+
+  it("falls back to a pre-filled seed when the daemon rejects the spawn", async () => {
+    mockFetchProjects.mockResolvedValue([project()]);
+    mockFetchNames.mockResolvedValue({ names: ["amber-fox"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    mockCreateSession.mockRejectedValue(new Error("boom"));
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(onSpawned).not.toHaveBeenCalled();
+    expect(onFallback).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd: "/repos/p", command: "claude", worktreeBranch: "amber-fox" }),
+    );
+  });
+
+  it("falls back when nothing is known yet (no projects, no handle)", async () => {
+    mockFetchProjects.mockResolvedValue([]);
+    mockFetchNames.mockRejectedValue(new Error("exhausted"));
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(mockCreateSession).not.toHaveBeenCalled();
+    expect(onFallback).toHaveBeenCalledWith(expect.objectContaining({ cwd: "" }));
+  });
+
+  it("prefers the focused session's project over the freshest one", async () => {
+    mockFetchProjects.mockResolvedValue([
+      project({ path: "/repos/fresh", name: "fresh" }),
+      project({ path: "/repos/current", name: "current", last_activity: "2020-01-01T00:00:00Z" }),
+    ]);
+    mockFetchNames.mockResolvedValue({ names: ["h"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    mockCreateSession.mockResolvedValue(session());
+    const onSpawned = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFastForward({ focusedCwd: "/repos/current", onSpawned, onFallback: vi.fn() }),
+    );
+    await act(() => result.current());
+
+    expect(mockCreateSession).toHaveBeenCalledWith(expect.objectContaining({ cwd: "/repos/current" }));
+  });
+});