docs(maestro): describe the dormant card, pane and ordering

docs/SIDEBAR.md: the dormant card's muted rendering, its resume
action, and its lowest-precedence ordering.
docs/PREVIEW.md: a session that isn't Running never gets a live
attach through the preview path either — its pane reads the same as
its card.

CLAUDE.md

@@ -14,6 +14,7 @@ maestro daemon            tmux wrapper + session API + SPA on 127.0.0.1:7070
   ├── DELETE   /api/sessions/:id    kill
   ├── POST     /api/sessions/:id/input  type text into a session
   ├── POST     /api/sessions/:id/prompt an agent reports its first prompt (#131)
+  ├── POST     /api/sessions/:id/resume respawn a dormant session, same id (#166)
   ├── GET      /api/info            hostname, version, home dir, spawn presets
   ├── GET      /api/dirs            directory listing (spawn autocomplete)
   ├── GET      /api/recent-dirs     spawn history

crates/maestro-daemon/src/lib.rs

@@ -25,6 +25,7 @@ pub mod proc;
 pub mod projects;
 pub mod pty;
 pub mod release;
+pub mod resume;
 pub mod session;
 pub mod sidecar;
 pub mod spawn_history;

crates/maestro-daemon/src/local_api.rs

@@ -52,6 +52,7 @@ pub fn router(state: LocalApiState) -> Router {
         .route(routes::patterns::SESSION_ACTIVITY, post(report_activity))
         .route(routes::patterns::SESSION_INPUT, post(send_input))
         .route(routes::patterns::SESSION_FOCUS, post(set_focus))
+        .route(routes::patterns::SESSION_RESUME, post(resume_session))
         .route(
             routes::patterns::SESSION,
             delete(kill_session).patch(rename_session),
@@ -170,6 +171,9 @@ fn session_error_status(code: &str) -> StatusCode {
         // The session outlived its pane: nothing to type into, and nothing
         // the daemon can do about it.
         "not_running" => StatusCode::CONFLICT,
+        // Resume refusals (#166): the session exists and the request was
+        // well-formed, it just cannot be brought back in this state.
+        "already_running" | "cwd_missing" => StatusCode::CONFLICT,
         _ => StatusCode::BAD_GATEWAY,
     }
 }
@@ -368,6 +372,27 @@ async fn set_focus(
     }
 }
 
+/// `POST /api/sessions/:id/resume` (#166): respawn a session that has no pane
+/// under its own id and sidecar, so its name, `created_at`, env and worktree
+/// ownership survive. Answers with the updated session, which also goes out as
+/// `SessionUpdated` to every events subscriber.
+///
+/// Refused with `409` when the session is already running or its `cwd` is
+/// gone; `404` when there is no such session.
+async fn resume_session(State(s): State<LocalApiState>, Path(id): Path<Uuid>) -> Response {
+    match s.manager.resume(id, &s.presets).await {
+        Ok(session) => (StatusCode::OK, Json(session)).into_response(),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(
+                session_error_status(&info.code),
+                info.code.as_str(),
+                info.message.as_str(),
+            )
+        }
+    }
+}
+
 fn error_response(status: StatusCode, code: &str, message: &str) -> Response {
     (status, Json(ApiError::new(code, message))).into_response()
 }
@@ -410,6 +435,16 @@ async fn attach_ws(
     ws: axum::extract::WebSocketUpgrade,
 ) -> Result<Response, Response> {
     let Some((replay, rx)) = s.manager.subscribe_pty_with_replay(id).await else {
+        // #166: a session the daemon knows but has no bridge for — a dormant
+        // one — is not missing, it is not running. Reporting it as unknown
+        // left the client unable to tell "gone" from "resumable".
+        if s.manager.has(id).await {
+            return Err(error_response(
+                StatusCode::CONFLICT,
+                "not_attachable",
+                "session has no live pane; resume it first",
+            ));
+        }
         return Err(error_response(
             StatusCode::NOT_FOUND,
             "unknown_session",

crates/maestro-daemon/src/resume.rs

@@ -0,0 +1,99 @@
+//! Choosing the command a resumed session comes back on (#166).
+//!
+//! A session records the command it was spawned with. Bringing it back means
+//! running that preset's `resume_command` (#165) instead, so an agent picks up
+//! its old conversation rather than starting a fresh one. Everything else
+//! about the session — id, sidecar, name, `created_at`, env, worktree — is
+//! untouched, so only the command is decided here.
+
+use maestro_protocol::{Session, SpawnPreset};
+
+/// The command to respawn `session` with.
+///
+/// The preset is matched on the command the session was spawned with, which is
+/// what the sidecar holds. A session with no matching preset, a preset with no
+/// `resume_command`, or a `resume_command` needing an agent session id the
+/// session never reported all fall back to the original command: respawning
+/// what the operator asked for is always honest, where a half-filled resume
+/// template is not.
+pub fn resume_command(session: &Session, presets: &[SpawnPreset]) -> String {
+    presets
+        .iter()
+        .find(|p| p.command == session.command)
+        .and_then(|p| p.resume_command_for(session.agent_session_id.as_deref()))
+        .unwrap_or_else(|| session.command.clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    fn presets() -> Vec<SpawnPreset> {
+        vec![
+            SpawnPreset {
+                id: "claude".into(),
+                label: "Claude".into(),
+                command: "claude".into(),
+                resume_command: Some("claude --resume {agent_session}".into()),
+            },
+            SpawnPreset {
+                id: "zsh".into(),
+                label: "Shell".into(),
+                command: "zsh".into(),
+                resume_command: None,
+            },
+        ]
+    }
+
+    fn session(command: &str, agent_session_id: Option<&str>) -> Session {
+        Session {
+            id: uuid::Uuid::new_v4(),
+            cwd: "/tmp".into(),
+            command: command.into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+            status: maestro_protocol::SessionStatus::Dormant,
+            created_at: chrono::Utc::now(),
+            foreground: None,
+            activity: maestro_protocol::ActivityState::Idle,
+            activity_detail: None,
+            last_activity_at: chrono::Utc::now(),
+            activity_since: chrono::Utc::now(),
+            current_cwd: None,
+            blocked_work: None,
+            last_focused_at: None,
+            agent_session_id: agent_session_id.map(str::to_string),
+        }
+    }
+
+    #[test]
+    fn uses_the_matching_presets_resume_command() {
+        assert_eq!(
+            resume_command(&session("claude", Some("conv-7")), &presets()),
+            "claude --resume conv-7"
+        );
+    }
+
+    #[test]
+    fn falls_back_when_the_agent_session_id_is_unknown() {
+        assert_eq!(
+            resume_command(&session("claude", None), &presets()),
+            "claude"
+        );
+    }
+
+    #[test]
+    fn falls_back_for_a_preset_without_a_resume_command() {
+        assert_eq!(resume_command(&session("zsh", None), &presets()), "zsh");
+    }
+
+    #[test]
+    fn falls_back_when_no_preset_matches() {
+        assert_eq!(
+            resume_command(&session("bash --noprofile", Some("conv-7")), &presets()),
+            "bash --noprofile"
+        );
+    }
+}

crates/maestro-daemon/src/session.rs

@@ -112,6 +112,15 @@ pub enum SessionError {
     /// a stray keystroke on an attach socket, which is dropped.
     #[error("session is no longer running: {0}")]
     NotRunning(Uuid),
+    /// A resume (#166) was asked for a session that is already running. There
+    /// is nothing to bring back, and respawning would strand the pane that is
+    /// already there.
+    #[error("session is already running: {0}")]
+    AlreadyRunning(Uuid),
+    /// A resume (#166) was asked for a session whose working directory is
+    /// gone. Nothing can be resumed in a directory that no longer exists.
+    #[error("session working directory no longer exists: {0}")]
+    CwdMissing(PathBuf),
     /// 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.
@@ -130,6 +139,8 @@ impl SessionError {
             SessionError::InvalidEnv(_) => "invalid_env",
             SessionError::NotRunning(_) => "not_running",
             SessionError::KillGuarded(_) => "kill_guarded",
+            SessionError::AlreadyRunning(_) => "already_running",
+            SessionError::CwdMissing(_) => "cwd_missing",
         };
         let unsaved_work = match self {
             SessionError::KillGuarded(b) => Some(*b),
@@ -586,6 +597,112 @@ impl SessionManager {
         Ok(session)
     }
 
+    /// Bring a session that has no pane back to life (#166).
+    ///
+    /// The session comes back under the **same** uuid and the same sidecar, so
+    /// `metadata.name`, `created_at`, `env` and worktree ownership all survive
+    /// — only the tmux session and the PTY bridge are new. That is the whole
+    /// point: spawning a fresh session at the same path instead produces a
+    /// stranger with no worktree to clean up on kill.
+    ///
+    /// The command is [`crate::resume::resume_command`]: the matching preset's
+    /// `resume_command` (#165) with the session's own agent conversation id
+    /// substituted in, falling back to the command the session was spawned
+    /// with. `Session::command` keeps the original either way, so a second
+    /// resume still resolves the same preset.
+    ///
+    /// Refused for a session that is already running, and for one whose `cwd`
+    /// has disappeared — neither is something a respawn could fix.
+    pub async fn resume(
+        &self,
+        id: Uuid,
+        presets: &[maestro_protocol::SpawnPreset],
+    ) -> Result<Session, SessionError> {
+        let mut session = {
+            let sessions = self.inner.sessions.lock().await;
+            let rec = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+            if rec.session.status == SessionStatus::Running {
+                return Err(SessionError::AlreadyRunning(id));
+            }
+            rec.session.clone()
+        };
+        if !session.cwd.exists() {
+            return Err(SessionError::CwdMissing(session.cwd.clone()));
+        }
+        let command = crate::resume::resume_command(&session, presets);
+
+        // Same fifo path as the original spawn: it is derived from the id, and
+        // `mkfifo` tolerates the stale node the previous run left behind.
+        let fifo_path = self.inner.fifo_dir.join(format!("{id}.fifo"));
+        let bridge =
+            PtyBridge::start_with_replay(fifo_path.clone(), self.inner.replay_bytes).await?;
+        let mut session_env = sanitize_env(&session.env)?;
+        session_env.insert("MAESTRO_SESSION_ID".into(), id.to_string());
+        if let Some(url) = self
+            .inner
+            .daemon_url
+            .lock()
+            .expect("daemon_url mutex")
+            .clone()
+        {
+            session_env.insert("MAESTRO_URL".into(), url);
+        }
+        let spawned = {
+            let tmux = self.inner.tmux.clone();
+            let cwd = session.cwd.clone();
+            let command = command.clone();
+            let sink = pipe_pane_command(&fifo_path);
+            tmux_blocking(move || tmux.new_session_piped(id, &cwd, &command, &session_env, &sink))
+                .await
+        };
+        if let Err(e) = spawned {
+            // `bridge` drops here, closing the FIFO reader. Nothing else was
+            // touched, so the session stays exactly as dormant as it was.
+            return Err(SessionError::Tmux(e));
+        }
+
+        session.status = SessionStatus::Running;
+        // A resumed session is producing its initial output again; the
+        // watcher refines this on its next tick, exactly as after a spawn.
+        session.foreground = None;
+        session.activity = ActivityState::Active;
+        session.activity_detail = None;
+        session.last_activity_at = Utc::now();
+        session.activity_since = Utc::now();
+        session.current_cwd = None;
+        session.last_focused_at = None;
+
+        if let Err(e) = self.inner.sidecar.write(&session) {
+            // tmux already spawned; kill it rather than leave a pane the
+            // sidecar does not describe.
+            let tmux = self.inner.tmux.clone();
+            let _ = tmux_blocking(move || tmux.kill_session(id)).await;
+            return Err(SessionError::Sidecar(e));
+        }
+
+        {
+            let mut sessions = self.inner.sessions.lock().await;
+            let Some(rec) = sessions.get_mut(&id) else {
+                // Killed while we were spawning. Undo the pane instead of
+                // leaving one behind with no record of it.
+                let tmux = self.inner.tmux.clone();
+                let _ = tmux_blocking(move || tmux.kill_session(id)).await;
+                return Err(SessionError::NotFound(id));
+            };
+            rec.session = session.clone();
+            rec.fifo_path = fifo_path;
+            rec.bridge = Some(bridge);
+            rec.reported_activity = None;
+            rec.settled = false;
+            rec.focused_since = None;
+            rec.awaiting_suppressed = false;
+        }
+        let _ = self.inner.events.send(CatalogEvent::SessionUpdated {
+            session: session.clone(),
+        });
+        Ok(session)
+    }
+
     /// Best-effort removal of a worktree created earlier in `create` when a
     /// later step fails. No-op when the request had no worktree.
     fn rollback_worktree(&self, base: &Option<PathBuf>, path: &Option<PathBuf>) {

crates/maestro-daemon/tests/attach.rs

@@ -94,6 +94,74 @@ async fn rejects_unknown_session() {
     assert!(format!("{err}").contains("404"));
 }
 
+/// #166: a session the daemon knows but has no bridge for is not unknown, it
+/// is not running. `404 unknown_session` made "gone" and "resumable" look the
+/// same to a client that could have offered a resume.
+#[tokio::test]
+async fn dormant_session_is_not_attachable_rather_than_unknown() {
+    let h = spawn_daemon_ws().await;
+    let cwd = TempDir::new().unwrap();
+    let session = h
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap();
+
+    // The host reboot: tmux is gone, the sidecar is not, and a fresh manager
+    // registers the session dormant.
+    h._fx.tmux.tmux.kill_server().unwrap();
+    let dormant = SessionManager::new(
+        std::sync::Arc::new(h._fx.tmux.tmux.clone()),
+        maestro_daemon::sidecar::SidecarStore::new(h._fx.sidecar_dir()),
+        maestro_daemon::worktree::WorktreeManager::new(None),
+        h._fx.fifo_dir(),
+    );
+    dormant.recover().await.unwrap();
+    let dormant_addr = serve_manager(dormant).await;
+
+    let err = connect_attach(dormant_addr, session.id).await.unwrap_err();
+    let tokio_tungstenite::tungstenite::Error::Http(resp) = err else {
+        panic!("want an HTTP rejection, got {err}");
+    };
+    assert_eq!(resp.status().as_u16(), 409);
+    let body: maestro_protocol::ApiError =
+        serde_json::from_slice(resp.body().as_deref().expect("error body")).unwrap();
+    assert_eq!(body.error.code, "not_attachable");
+
+    // A session that really is unknown still reads as unknown.
+    let err = connect_attach(dormant_addr, Uuid::new_v4())
+        .await
+        .unwrap_err();
+    assert!(format!("{err}").contains("404"));
+}
+
+/// Serve `manager` on its own listener, for tests that need a second daemon
+/// over the same tmux/sidecar state.
+async fn serve_manager(manager: SessionManager) -> SocketAddr {
+    let router = local_api::router(local_api::state_for(
+        manager,
+        "test-host",
+        "/home/test",
+        Vec::new(),
+        std::sync::Arc::new(maestro_daemon::projects::ProjectScanner::disabled()),
+        maestro_config::DEFAULT_LEADER,
+    ));
+    let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+        .await
+        .unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, router).await;
+    });
+    addr
+}
+
 #[tokio::test]
 async fn pty_round_trip_through_real_tmux() {
     let h = spawn_daemon_ws().await;

crates/maestro-daemon/tests/resume.rs

@@ -0,0 +1,359 @@
+//! End-to-end tests for `POST /api/sessions/:id/resume` (#166) and the
+//! manager call behind it, against real tmux.
+//!
+//! The point of resume is that the session comes back under the *same* uuid
+//! and sidecar — name, `created_at`, env and worktree ownership intact — with
+//! only the tmux session and the PTY bridge new.
+
+mod common;
+
+use std::collections::HashMap;
+use std::net::{Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::time::Duration;
+
+use common::{wait_for_async, DaemonFixture};
+use maestro_daemon::{local_api, SessionError, SessionManager};
+use maestro_protocol::{CreateSessionRequest, Session, SessionStatus, SpawnPreset};
+use tempfile::TempDir;
+use tokio::net::TcpListener;
+use tokio::sync::oneshot;
+use uuid::Uuid;
+
+/// A fresh manager over the same tmux server, sidecars and fifos — what the
+/// daemon builds after a restart.
+fn revive(fx: &DaemonFixture) -> SessionManager {
+    SessionManager::new(
+        Arc::new(fx.tmux.tmux.clone()),
+        maestro_daemon::sidecar::SidecarStore::new(fx.sidecar_dir()),
+        maestro_daemon::worktree::WorktreeManager::new(None),
+        fx.fifo_dir(),
+    )
+}
+
+/// Create a session, then simulate the host reboot that leaves it dormant:
+/// the tmux server dies, the sidecar stays, a new manager recovers.
+async fn dormant_session(
+    fx: &DaemonFixture,
+    cwd: &TempDir,
+    command: &str,
+    name: &str,
+) -> (SessionManager, Session) {
+    let mut metadata = HashMap::new();
+    metadata.insert(
+        maestro_protocol::NAME_KEY.to_string(),
+        serde_json::Value::String(name.into()),
+    );
+    let session = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: command.into(),
+            env: HashMap::from([("MAESTRO_TEST_ENV".to_string(), "kept".to_string())]),
+            metadata,
+            worktree: None,
+        })
+        .await
+        .expect("create");
+    fx.tmux.tmux.kill_server().expect("kill tmux server");
+    let revived = revive(fx);
+    revived.recover().await.expect("recover");
+    (revived, session)
+}
+
+fn marker_preset(command: &str, marker_dir: &TempDir) -> Vec<SpawnPreset> {
+    vec![SpawnPreset {
+        id: "agent".into(),
+        label: "Agent".into(),
+        command: command.into(),
+        resume_command: Some(format!(
+            "sh -c 'touch {}/resumed-{{agent_session}}; sleep 30'",
+            marker_dir.path().display()
+        )),
+    }]
+}
+
+/// The keystone: a dormant session comes back running under its own id, with
+/// its name, `created_at`, env and sidecar untouched.
+#[tokio::test]
+async fn resume_brings_a_dormant_session_back_under_the_same_id() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let (manager, original) = dormant_session(&fx, &cwd, "sleep 30", "long-runner").await;
+    assert_eq!(
+        manager.status(original.id).await,
+        Some(SessionStatus::Dormant)
+    );
+
+    let resumed = manager.resume(original.id, &[]).await.expect("resume");
+
+    assert_eq!(resumed.id, original.id, "same uuid");
+    assert_eq!(resumed.status, SessionStatus::Running);
+    assert_eq!(resumed.created_at, original.created_at);
+    assert_eq!(resumed.cwd, original.cwd);
+    assert_eq!(resumed.command, original.command);
+    assert_eq!(resumed.env, original.env);
+    assert_eq!(
+        resumed
+            .metadata
+            .get(maestro_protocol::NAME_KEY)
+            .and_then(|v| v.as_str()),
+        Some("long-runner")
+    );
+
+    // tmux really holds it again, and the sidecar is the same file, updated.
+    let live = fx.tmux.tmux.list_sessions().expect("list");
+    assert_eq!(live, vec![original.id]);
+    let stored = maestro_daemon::sidecar::SidecarStore::new(fx.sidecar_dir())
+        .read(original.id)
+        .expect("read sidecar")
+        .expect("sidecar still there");
+    assert_eq!(stored.status, SessionStatus::Running);
+    assert_eq!(stored.created_at, original.created_at);
+
+    // And it is attachable again, which a dormant session never was.
+    assert!(manager
+        .subscribe_pty_with_replay(original.id)
+        .await
+        .is_some());
+}
+
+/// The worktree the session owns stays the session's, so killing the resumed
+/// session still cleans the tree up.
+#[tokio::test]
+async fn resume_keeps_worktree_ownership() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    common::init_repo(repo.path());
+
+    let session = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(maestro_protocol::WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feature".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    let worktree = session.worktree.clone().expect("worktree");
+
+    fx.tmux.tmux.kill_server().expect("kill tmux server");
+    let manager = revive(&fx);
+    manager.recover().await.expect("recover");
+    let resumed = manager.resume(session.id, &[]).await.expect("resume");
+
+    assert_eq!(resumed.worktree, Some(worktree.clone()));
+    assert_eq!(
+        resumed.cwd, worktree.path,
+        "resumed inside its own worktree"
+    );
+}
+
+/// The command comes from the preset's `resume_command`, with the session's
+/// own agent conversation id (#161) substituted in.
+#[tokio::test]
+async fn resume_runs_the_presets_resume_command() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let markers = TempDir::new().unwrap();
+    let presets = marker_preset("sleep 30", &markers);
+
+    let (manager, session) = dormant_session(&fx, &cwd, "sleep 30", "agentic").await;
+    // The agent reported its conversation id before the reboot, so it is on
+    // the sidecar and the resume template can be filled in.
+    fx.manager
+        .report_activity(
+            session.id,
+            maestro_protocol::ActivityState::Idle,
+            None,
+            Some("conv-42".into()),
+        )
+        .await
+        .ok();
+    // Re-read the sidecar the report updated.
+    let manager = {
+        drop(manager);
+        let m = revive(&fx);
+        m.recover().await.expect("recover");
+        m
+    };
+
+    manager.resume(session.id, &presets).await.expect("resume");
+
+    let marker = markers.path().join("resumed-conv-42");
+    wait_for_async(Duration::from_secs(5), || {
+        let marker = marker.clone();
+        async move { marker.exists() }
+    })
+    .await;
+}
+
+/// A session that is already running has nothing to bring back, and
+/// respawning would strand the pane that is already there.
+#[tokio::test]
+async fn resume_refuses_a_running_session() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let session = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    let err = fx
+        .manager
+        .resume(session.id, &[])
+        .await
+        .expect_err("already running");
+    assert!(matches!(err, SessionError::AlreadyRunning(id) if id == session.id));
+    assert_eq!(err.to_error_info().code, "already_running");
+}
+
+/// Nothing can be resumed in a directory that no longer exists.
+#[tokio::test]
+async fn resume_refuses_when_the_cwd_is_gone() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let (manager, session) = dormant_session(&fx, &cwd, "sleep 30", "homeless").await;
+
+    std::fs::remove_dir_all(cwd.path()).unwrap();
+
+    let err = manager
+        .resume(session.id, &[])
+        .await
+        .expect_err("cwd is gone");
+    assert_eq!(err.to_error_info().code, "cwd_missing");
+    assert_eq!(
+        manager.status(session.id).await,
+        Some(SessionStatus::Dormant),
+        "a refused resume leaves the session exactly as it was"
+    );
+}
+
+#[tokio::test]
+async fn resume_of_an_unknown_session_is_not_found() {
+    let fx = DaemonFixture::new();
+    let err = fx
+        .manager
+        .resume(Uuid::new_v4(), &[])
+        .await
+        .expect_err("unknown");
+    assert_eq!(err.to_error_info().code, "not_found");
+}
+
+// ---------------------------------------------------------------------------
+// HTTP surface
+// ---------------------------------------------------------------------------
+
+struct Harness {
+    addr: SocketAddr,
+    _shutdown: oneshot::Sender<()>,
+}
+
+async fn serve(manager: SessionManager, presets: Vec<SpawnPreset>) -> Harness {
+    let router = local_api::router(local_api::state_for(
+        manager,
+        "test-host",
+        "/home/test",
+        presets,
+        Arc::new(maestro_daemon::projects::ProjectScanner::disabled()),
+        maestro_config::DEFAULT_LEADER,
+    ));
+    let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+        .await
+        .unwrap();
+    let addr = listener.local_addr().unwrap();
+    let (tx, rx) = oneshot::channel::<()>();
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, router)
+            .with_graceful_shutdown(async move {
+                let _ = rx.await;
+            })
+            .await;
+    });
+    Harness {
+        addr,
+        _shutdown: tx,
+    }
+}
+
+#[tokio::test]
+async fn post_resume_returns_the_revived_session() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let (manager, session) = dormant_session(&fx, &cwd, "sleep 30", "web-resumed").await;
+    let h = serve(manager, Vec::new()).await;
+
+    let resp = reqwest::Client::new()
+        .post(format!(
+            "http://{}{}",
+            h.addr,
+            maestro_protocol::routes::session_resume(session.id)
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::OK);
+    let body: Session = resp.json().await.unwrap();
+    assert_eq!(body.id, session.id);
+    assert_eq!(body.status, SessionStatus::Running);
+}
+
+#[tokio::test]
+async fn post_resume_on_a_running_session_is_a_conflict() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let session = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+    let h = serve(fx.manager.clone(), Vec::new()).await;
+
+    let resp = reqwest::Client::new()
+        .post(format!(
+            "http://{}{}",
+            h.addr,
+            maestro_protocol::routes::session_resume(session.id)
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::CONFLICT);
+    let err: maestro_protocol::ApiError = resp.json().await.unwrap();
+    assert_eq!(err.error.code, "already_running");
+}
+
+#[tokio::test]
+async fn post_resume_on_an_unknown_session_is_404() {
+    let fx = DaemonFixture::new();
+    let h = serve(fx.manager.clone(), Vec::new()).await;
+    let resp = reqwest::Client::new()
+        .post(format!(
+            "http://{}{}",
+            h.addr,
+            maestro_protocol::routes::session_resume(Uuid::new_v4())
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
+}

crates/maestro-protocol/src/lib.rs

@@ -536,6 +536,29 @@ pub struct SpawnPreset {
     pub resume_command: Option<String>,
 }
 
+/// Placeholder a preset's `resume_command` may carry for the agent's own
+/// conversation id (#165), substituted from [`Session::agent_session_id`].
+pub const AGENT_SESSION_PLACEHOLDER: &str = "{agent_session}";
+
+impl SpawnPreset {
+    /// The command that resumes a session spawned from this preset, with
+    /// [`AGENT_SESSION_PLACEHOLDER`] filled in from `agent_session`.
+    ///
+    /// `None` when the preset has no `resume_command` — a plain shell has
+    /// nothing to resume — and also when the template asks for an agent
+    /// session id the session never reported: `claude --resume` with an empty
+    /// id resumes nothing, so the caller is better off respawning the original
+    /// command than running a broken one.
+    pub fn resume_command_for(&self, agent_session: Option<&str>) -> Option<String> {
+        let template = self.resume_command.as_deref()?;
+        if !template.contains(AGENT_SESSION_PLACEHOLDER) {
+            return Some(template.to_string());
+        }
+        let id = agent_session.filter(|s| !s.is_empty())?;
+        Some(template.replace(AGENT_SESSION_PLACEHOLDER, id))
+    }
+}
+
 /// Build provenance of the running daemon: the commit it was compiled
 /// from and when that commit was authored.
 ///
@@ -785,6 +808,47 @@ pub enum ClientControl {
 mod tests {
     use super::*;
 
+    fn preset(resume: Option<&str>) -> SpawnPreset {
+        SpawnPreset {
+            id: "claude".into(),
+            label: "Claude".into(),
+            command: "claude".into(),
+            resume_command: resume.map(str::to_string),
+        }
+    }
+
+    #[test]
+    fn resume_command_substitutes_the_agent_session() {
+        let p = preset(Some("claude --resume {agent_session}"));
+        assert_eq!(
+            p.resume_command_for(Some("abc-123")).as_deref(),
+            Some("claude --resume abc-123")
+        );
+    }
+
+    #[test]
+    fn resume_command_without_a_placeholder_ignores_the_agent_session() {
+        let p = preset(Some("opencode --continue"));
+        assert_eq!(
+            p.resume_command_for(None).as_deref(),
+            Some("opencode --continue")
+        );
+    }
+
+    /// A template that wants an id the session never reported would run
+    /// `claude --resume` against nothing; the caller respawns instead.
+    #[test]
+    fn resume_command_is_none_without_the_id_it_asks_for() {
+        let p = preset(Some("claude --resume {agent_session}"));
+        assert!(p.resume_command_for(None).is_none());
+        assert!(p.resume_command_for(Some("")).is_none());
+    }
+
+    #[test]
+    fn a_preset_without_a_resume_command_has_none() {
+        assert!(preset(None).resume_command_for(Some("abc")).is_none());
+    }
+
     #[test]
     fn version_compatibility_is_major_only() {
         assert!(is_compatible(PROTOCOL_VERSION));

crates/maestro-protocol/src/routes.rs

@@ -66,6 +66,12 @@ pub fn session_focus(id: Uuid) -> String {
     format!("{SESSIONS}/{id}/focus")
 }
 
+/// `POST /api/sessions/:id/resume` (#166): respawn a dormant session under its
+/// own id, keeping its sidecar, name, worktree and `created_at`.
+pub fn session_resume(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/resume")
+}
+
 /// `WS /api/attach/:id` — raw PTY bytes.
 pub fn attach(id: Uuid) -> String {
     format!("{API_PREFIX}/attach/{id}")
@@ -79,6 +85,7 @@ pub mod patterns {
     pub const SESSION_INPUT: &str = "/api/sessions/:id/input";
     pub const SESSION_PROMPT: &str = "/api/sessions/:id/prompt";
     pub const SESSION_FOCUS: &str = "/api/sessions/:id/focus";
+    pub const SESSION_RESUME: &str = "/api/sessions/:id/resume";
     pub const ATTACH: &str = "/api/attach/:id";
 }
 
@@ -202,6 +209,10 @@ mod tests {
             session_focus(id()),
             "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/focus"
         );
+        assert_eq!(
+            session_resume(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/resume"
+        );
         assert_eq!(
             attach(id()),
             "/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
@@ -236,6 +247,10 @@ mod tests {
             patterns::SESSION_FOCUS.trim_end_matches(":id/focus"),
             session(id()).trim_end_matches(&id().to_string())
         );
+        assert_eq!(
+            patterns::SESSION_RESUME.trim_end_matches(":id/resume"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
         assert_eq!(
             patterns::ATTACH.trim_end_matches(":id"),
             attach(id()).trim_end_matches(&id().to_string())

docs/PREVIEW.md

@@ -28,6 +28,12 @@ A preview is a view, not a state. Nothing about it is durable:
 | Already in a pane, in another tab | That tab is brought forward. The active tab is restored when the preview ends. |
 | Not in any pane | A throwaway tab carries it. It is removed when the preview ends. |
 
+A session that is not `Running` — a dormant one, most often — never gets a
+live attach here or anywhere else a pane is filled: the daemon has nothing to
+answer a `409 not_attachable` and the socket would just die (WS close 1006).
+Its pane shows the same metadata-and-resume view `docs/SIDEBAR.md` describes
+for its card, honest about the fact that there is nothing to preview yet.
+
 The throwaway tab never counts as an open session: the tab bar does not appear
 because of it, the mobile shell does not switch away from the session list for
 it, and the sidebar does not mark the session as open.

docs/RESTART.md

@@ -79,9 +79,26 @@ to adopt while every session's sidecar is still on disk. Recovery makes a
 second pass over those sidecars and registers each as a `Dormant` session
 (#162) — id, name, cwd, command, worktree and `created_at` intact. A dormant
 session has no pane and no PTY bridge: it cannot be attached to, typed into or
-resized, and neither watcher pass touches it. It is a record of what was
-running, and the only thing left to do with one is dismiss it, which removes
-the sidecar so the next recovery does not bring it back.
+resized, and neither watcher pass touches it.
+
+A dormant session is brought back with `POST /api/sessions/:id/resume` (#166),
+which respawns tmux under the **same** uuid and sidecar — `metadata.name`,
+`created_at`, `env` and worktree ownership all survive, and only the tmux
+session and the PTY bridge are new. The command is the matching spawn preset's
+`resume_command` with `{agent_session}` filled in from the session's own
+`agent_session_id`, so an agent comes back inside its old conversation; a
+session with no matching preset, no `resume_command`, or no reported
+conversation id is respawned on the command it was created with. `Session::command`
+always keeps that original command, so a second resume resolves the same preset.
+Resume is refused with `409` for a session that is already running
+(`already_running`) and for one whose `cwd` has disappeared (`cwd_missing`) —
+neither is something a respawn could fix. The other thing to do with a dormant
+session is dismiss it, which removes the sidecar so the next recovery does not
+bring it back.
+
+Attaching to a session that has no bridge answers `409 not_attachable`, not
+`404 unknown_session`: the session exists, and a client that cannot tell "gone"
+from "not running" cannot offer the resume.
 
 `SessionStatus` is a wire type, so from this build forward it deserializes
 leniently on both clients: a spelling the client does not know reads as `Dead`

docs/SIDEBAR.md

@@ -113,6 +113,33 @@ pane, no scrollback, and nothing to attach to. It is not an exit — nothing was
 observed ending — so the two fragments never both show. The TUI marks the same
 state on line 1 with `◌`, next to `✗` for exited and `●`/`○` for running.
 
+### Dormant cards (#168)
+
+A dormant card is a muted variant of the normal card (the web client's
+`is-dormant` class, the same muted foreground `exited` already uses): name,
+cwd and last-known age render as usual, but the activity rail carries no
+colour, since recovery resets a dormant session's activity to `Idle` and
+there is nothing running to report otherwise.
+
+The row's right-hand actions swap **spawn similar** for **resume** (↻) — there
+is no live state to clone from — and call `POST /api/sessions/:id/resume`
+(#166). **Kill** stays: it is how a dormant session is dismissed, since the
+daemon already treats a kill of a dormant session as removing its sidecar
+rather than anything it needs to be running to do.
+
+A dormant session takes the **lowest precedence in the ordering**: within a
+folder, every live (`Running` or `Dead`) session sorts before every dormant
+one, name notwithstanding, and dormant sessions sort among themselves by name.
+So a reboot that leaves a whole tree dormant never buries the live work a
+session spawns into it.
+
+Selecting a dormant session — by click, by keyboard, or by preview
+(`docs/PREVIEW.md`) — never opens a live attach: the content pane shows the
+same metadata and resume affordance the card does, rather than a terminal
+that would die on the daemon's `409 not_attachable` (WS close 1006). Resuming
+turns the session `Running`; the pane and the card pick that up on their own
+next update, no navigation required.
+
 `<diff stat>` is the blocked-work breakdown (#83) in diff notation, replacing
 the spelled-out `⚠ 3 uncommitted files, 2 unpushed commits`. It renders only
 while something would block an unforced kill, and reads:

web/src/api.ts

@@ -91,6 +91,18 @@ export async function killSession(id: Uuid, force = false): Promise<void> {
   );
 }
 
+/** Respawn a dormant session under its own uuid and sidecar (#166/#168).
+ * Refused with `409` (`already_running` / `cwd_missing`) when there is
+ * nothing a respawn could fix. */
+export async function resumeSession(id: Uuid): Promise<Session> {
+  return jsonOrError(
+    await fetch(routes.sessionResume(id), {
+      method: "POST",
+      credentials: "same-origin",
+    }),
+  );
+}
+
 /** Report whether this client's pane is the one currently showing `id` — not
  * merely highlighted in a sidebar. The daemon uses this to clear an
  * `AwaitingInput` glow once the pane has been looked at long enough

web/src/attach.ts

@@ -65,9 +65,17 @@ export interface AttachOptions {
    *  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;
+  /** Invoked when the handshake itself never completed — no retry was
+   *  attempted (see `shouldReconnect`'s `everOpened`). Unlike `onClosed`, this
+   *  is not "the session is gone": it is at least as likely a dormant
+   *  session's `409 not_attachable` caught mid-status-update (#168 review).
+   *  The shell re-renders rather than tearing the pane's leaf out, so a
+   *  dormant session's resume affordance can take over in place. */
+  onNeverAttached?: (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;
+   *  from the catalog — see `shouldRetryClose`. `everOpened` is false when
+   *  this attempt never reached `open`. */
+  shouldReconnect?: (sessionId: Uuid, code: number, everOpened: boolean) => boolean;
 }
 
 /** What the header shows about the session (name / command). Optional — falls
@@ -379,6 +387,10 @@ export function createAttachConnection(
   let ws: WebSocket;
   let reconnectMs = INITIAL_RECONNECT_MS;
   let reconnectTimer: number | null = null;
+  // #168 review: a fresh attempt that never reaches `open` is a rejected
+  // handshake (dormant/unknown session), not a dropped stream — see
+  // `shouldRetryClose`'s `everOpened` param.
+  let everOpened = false;
 
   const sendControl = (msg: ClientControl) => {
     if (ws.readyState !== WebSocket.OPEN) return;
@@ -402,6 +414,7 @@ export function createAttachConnection(
     ws.binaryType = "arraybuffer";
 
     ws.onopen = () => {
+      everOpened = true;
       reconnectMs = INITIAL_RECONNECT_MS;
       setState("connected", "open");
       sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
@@ -444,7 +457,7 @@ export function createAttachConnection(
       // close handle their own pane teardown.
       if (disposed) return;
 
-      if (opts.shouldReconnect?.(sessionId, ev.code)) {
+      if (opts.shouldReconnect?.(sessionId, ev.code, everOpened)) {
         const delay = Math.min(reconnectMs, MAX_RECONNECT_MS);
         setState("reconnecting…", "connecting");
         reconnectTimer = window.setTimeout(() => {
@@ -455,6 +468,12 @@ export function createAttachConnection(
         return;
       }
 
+      if (!everOpened) {
+        setState("not attached", "closed");
+        opts.onNeverAttached?.(sessionId);
+        return;
+      }
+
       setState(`closed (${ev.code})`, "closed");
       opts.onClosed?.(sessionId);
     };

web/src/catalog.test.ts

@@ -427,6 +427,44 @@ describe("session cards (#107)", () => {
     expect(line2?.textContent).not.toContain("exited");
   });
 
+  // #168: a dormant card is a muted variant with a resume action in place of
+  // "spawn similar", since there is nothing running to clone from live state.
+  it("renders a dormant card muted, with a resume action instead of spawn-similar", async () => {
+    const calls: string[] = [];
+    window.fetch = ((url: string, init?: RequestInit) => {
+      calls.push(`${init?.method ?? "GET"} ${url}`);
+      return Promise.resolve(
+        new Response(JSON.stringify({ id: "aaaaaaaa-0000-0000-0000-000000000120", status: "Running" }), {
+          status: 200,
+        }),
+      );
+    }) as typeof fetch;
+    const s = session({ id: "aaaaaaaa-0000-0000-0000-000000000120", status: "Dormant" });
+    const el = renderSidebar(storeWith([s])).el;
+    const row = rowFor(el, s.id) as HTMLElement;
+    expect(row.classList.contains("is-dormant")).toBe(true);
+    expect(row.querySelector(".leaf-clone")).toBeNull();
+    const resumeBtn = row.querySelector<HTMLButtonElement>(".leaf-resume");
+    expect(resumeBtn).toBeTruthy();
+    resumeBtn?.click();
+    await flush();
+    expect(calls).toContain(`POST /api/sessions/${s.id}/resume`);
+  });
+
+  // #168: a two-way running/dead test made a dormant card lie to screen
+  // readers — the visible flag says dormant, the aria-label said "exited".
+  it("marks a dormant row's status and aria-label distinctly from dead", () => {
+    const s = session({
+      id: "aaaaaaaa-0000-0000-0000-000000000119",
+      status: "Dormant",
+    });
+    const el = renderSidebar(storeWith([s])).el;
+    const row = rowFor(el, s.id) as HTMLElement;
+    expect(row.dataset.status).toBe("dormant");
+    expect(row.getAttribute("aria-label")).toContain("dormant");
+    expect(row.getAttribute("aria-label")).not.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",

web/src/catalog.ts

@@ -1,5 +1,5 @@
 import { escapeHtml } from "./html.js";
-import { ApiRequestError, getDaemonInfo, killSession, renameSession } from "./api.js";
+import { ApiRequestError, getDaemonInfo, killSession, renameSession, resumeSession } from "./api.js";
 import { openForceKillDialog, openKillConfirmDialog } from "./killDialog.js";
 import { openContextMenu } from "./contextMenu.js";
 import { toggleHelp } from "./help.js";
@@ -104,6 +104,21 @@ const STATE_WORDS: Record<string, string> = {
   error: "Error",
 };
 
+// #168: dormancy is not an exit (docs/SIDEBAR.md), so `dataset.status` and
+// the aria-label read the session's own three-way `status` rather than a
+// two-way running/dead test that folded `Dormant` into "dead"/"exited".
+function statusSlug(status: Session["status"]): string {
+  if (status === "Running") return "running";
+  if (status === "Dormant") return "dormant";
+  return "dead";
+}
+
+function statusWord(status: Session["status"]): string {
+  if (status === "Running") return "running";
+  if (status === "Dormant") return "dormant";
+  return "exited";
+}
+
 /** 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. */
@@ -203,33 +218,46 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
   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";
+  row.dataset.status = statusSlug(s.status);
+  // docs/SIDEBAR.md: a dormant card is a muted variant — nothing running
+  // behind it, so it earns no activity colour or spawn-similar affordance.
+  const dormant = s.status === "Dormant";
+  row.classList.toggle("is-dormant", dormant);
   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}`,
-  );
+  row.setAttribute("aria-label", `${name}, ${statusWord(s.status)}, ${stateWord}`);
+  const cloneOrResumeAction = dormant
+    ? `<button class="leaf-act leaf-resume" type="button" title="Resume session" aria-label="Resume ${escapeHtml(name)}">↻</button>`
+    : `<button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>`;
   // 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>
+        ${cloneOrResumeAction}
         <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) => {
+  const similarBtn = row.querySelector<HTMLButtonElement>(".leaf-clone");
+  similarBtn?.addEventListener("click", (ev) => {
     ev.preventDefault();
     ev.stopPropagation();
     document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur }));
   });
+  const resumeBtn = row.querySelector<HTMLButtonElement>(".leaf-resume");
+  resumeBtn?.addEventListener("click", (ev) => {
+    ev.preventDefault();
+    ev.stopPropagation();
+    resumeBtn.disabled = true;
+    void resumeSession(cur.id).catch((e: Error) => {
+      resumeBtn.disabled = false;
+      alert(`Failed to resume: ${e.message}`);
+    });
+  });
   const killBtn = row.querySelector(".leaf-kill") as HTMLButtonElement;
   killBtn.addEventListener("click", (ev) => {
     ev.preventDefault();
@@ -244,11 +272,19 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     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 })),
-      },
+      cur.status === "Dormant"
+        ? {
+            label: "Resume",
+            onSelect: () =>
+              void resumeSession(cur.id).catch((e: Error) =>
+                alert(`Failed to resume: ${e.message}`),
+              ),
+          }
+        : {
+            label: "Spawn similar",
+            onSelect: () =>
+              document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur })),
+          },
       {
         label: "Kill session",
         danger: true,
@@ -260,10 +296,8 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     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}`,
-    );
+    row.dataset.status = statusSlug(next.status);
+    row.setAttribute("aria-label", `${sessionName(next)}, ${statusWord(next.status)}, ${nextWord}`);
     const rail = row.querySelector(".activity-rail");
     if (rail) rail.outerHTML = activityRailMarkup(nextSlug, nextWord);
     const meta = row.querySelector(".card-line2");

web/src/connections.ts

@@ -25,8 +25,13 @@ export interface PoolOptions {
   /** Fired when a connection's socket closes on its own (session ended/dropped),
    *  not via an intentional close/eviction. The embedder closes the pane. */
   onClosed?: (id: Uuid) => void;
+  /** Fired when a connection's handshake never completed and so was never
+   *  retried (see `AttachOptions.onNeverAttached`). Unlike `onClosed`, the
+   *  embedder should not assume the session is gone — a dormant session's
+   *  pane wants its resume affordance, not teardown. */
+  onNeverAttached?: (id: Uuid) => void;
   /** Forwarded to each connection: should a dropped socket be retried? */
-  shouldReconnect?: (id: Uuid, code: number) => boolean;
+  shouldReconnect?: (id: Uuid, code: number, everOpened: boolean) => boolean;
 }
 
 /**
@@ -85,7 +90,9 @@ export class ConnectionPool {
         {
           onRequestClose: (sid) => this.opts.onRequestClose?.(sid),
           onClosed: (sid) => this.opts.onClosed?.(sid),
-          shouldReconnect: (sid, code) => this.opts.shouldReconnect?.(sid, code) ?? false,
+          onNeverAttached: (sid) => this.opts.onNeverAttached?.(sid),
+          shouldReconnect: (sid, code, everOpened) =>
+            this.opts.shouldReconnect?.(sid, code, everOpened) ?? false,
         },
         info,
       );

web/src/main.ts

@@ -19,6 +19,7 @@ import {
   getDaemonInfo,
   gitRoot,
   projects as fetchProjects,
+  resumeSession,
 } from "./api.js";
 import {
   buildFastForwardRequest,
@@ -172,17 +173,42 @@ const pool = new ConnectionPool({
   // pane is never left lying around.
   onRequestClose: (id) => closePane(id),
   onClosed: (id) => closePane(id),
-  shouldReconnect: (id, code) => shouldRetryClose(id, code, store.snapshot().sessions),
+  // #168 review: a handshake that never opened (a dormant session's `409
+  // not_attachable`, most likely) isn't "the session is gone" — drop the dead
+  // connection and re-render so the leaf gets a fresh attempt if the catalog
+  // still says Running, or the resume affordance if it doesn't.
+  onNeverAttached: (id) => {
+    pool.close(id);
+    mv?.render();
+  },
+  shouldReconnect: (id, code, everOpened) =>
+    shouldRetryClose(id, code, store.snapshot().sessions, everOpened),
 });
 
 // Session death used to reach the UI on two uncoordinated channels — the row
 // from the events socket, the pane from `ws.onclose` — so either could happen
 // without the other. The catalog is the authority: a pane for a session that is
 // no longer listed gets closed here.
+//
+// A pane can also be showing the dormant placeholder (or, briefly, a dead
+// socket) rather than a live attach (#168): when an *open* session's
+// Running-ness flips — most commonly a resume completing — the pane and the
+// placeholder need to swap without waiting on an unrelated layout change.
+let lastOpenRunning = new Map<string, boolean>();
 store.subscribe((state) => {
   for (const id of mv?.openSessions() ?? []) {
     if (!state.sessions.has(id)) closePane(id);
   }
+  const open = mv?.openSessions() ?? new Set<string>();
+  const nextRunning = new Map<string, boolean>();
+  let runningChanged = false;
+  for (const id of open) {
+    const running = state.sessions.get(id)?.status === "Running";
+    nextRunning.set(id, running);
+    if (lastOpenRunning.get(id) !== running) runningChanged = true;
+  }
+  lastOpenRunning = nextRunning;
+  if (runningChanged) mv?.render();
 });
 
 function closePane(id: string): void {
@@ -275,6 +301,8 @@ mv = createMultiView({
   // catalog (no sessions) to attach.
   onOpenSessionsChange: updateShellRoute,
   onLayoutChange: scheduleSave,
+  sessionFor: (id) => store.snapshot().sessions.get(id),
+  onResume: (id) => resumeSession(id),
 });
 let contentShowsMv = false;
 /** Put the multi-view in the content pane, without rendering it. A preview

web/src/multiview.test.ts

@@ -45,7 +45,7 @@ function fakeSidebar(): SidebarHandle {
   };
 }
 
-function makeMv(layout: Layout): MultiView {
+function makeMv(layout: Layout, overrides: Partial<Parameters<typeof createMultiView>[0]> = {}): MultiView {
   return createMultiView({
     pool: fakePool(),
     layout,
@@ -53,6 +53,7 @@ function makeMv(layout: Layout): MultiView {
     infoFor: () => ({ name: "sess", command: "bash" }),
     onDisconnect: () => {},
     renderWelcome: () => document.createElement("div"),
+    ...overrides,
   });
 }
 
@@ -87,6 +88,102 @@ describe("multiview empty panes", () => {
   });
 });
 
+// #168 review: highlighting a dormant session used to open a pane and attempt
+// a live attach, which the daemon answers with 404/409 and the socket dies
+// with WS 1006. A dormant leaf must never reach the pool at all — it gets the
+// resume affordance instead.
+describe("multiview dormant gating (#168)", () => {
+  beforeEach(() => {
+    stubFetch();
+    document.body.replaceChildren();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function dormantSession(id: string) {
+    return {
+      id,
+      cwd: "/home/n/work",
+      command: "claude",
+      env: {},
+      metadata: { name: "worker" },
+      status: "Dormant" as const,
+      created_at: "2026-08-24T10:00:00Z",
+    };
+  }
+
+  it("never hands a dormant session's leaf to the pool, and shows a resume affordance", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "d1", "row", true);
+    const setVisible = vi.fn();
+    const pool = { setVisible, setFocus() {} } as unknown as ConnectionPool;
+    const mv = createMultiView({
+      pool,
+      layout,
+      sidebar: fakeSidebar(),
+      infoFor: () => ({ name: "worker", command: "claude" }),
+      onDisconnect: () => {},
+      renderWelcome: () => document.createElement("div"),
+      sessionFor: (id) => (id === "d1" ? dormantSession("d1") : undefined),
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    expect(setVisible).toHaveBeenCalledWith([], expect.anything());
+    const pane = mv.el.querySelector('[data-leaf-id]') as HTMLElement;
+    expect(pane.querySelector(".mv-pane-dormant")).toBeTruthy();
+    expect(pane.textContent).toContain("worker");
+    expect(pane.textContent).toContain("/home/n/work");
+    expect(pane.querySelector(".mv-dormant-resume")).toBeTruthy();
+  });
+
+  it("still attaches a Running session's leaf normally", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "r1", "row", true);
+    const setVisible = vi.fn();
+    const pool = { setVisible, setFocus() {} } as unknown as ConnectionPool;
+    const mv = createMultiView({
+      pool,
+      layout,
+      sidebar: fakeSidebar(),
+      infoFor: () => ({ name: "worker", command: "claude" }),
+      onDisconnect: () => {},
+      renderWelcome: () => document.createElement("div"),
+      sessionFor: (id) => ({ ...dormantSession(id), status: "Running" }),
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    expect(setVisible).toHaveBeenCalledWith(
+      [expect.objectContaining({ id: "r1" })],
+      expect.anything(),
+    );
+  });
+
+  it("clicking resume calls back with the session id", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "d1", "row", true);
+    const onResume = vi.fn().mockResolvedValue(undefined);
+    const mv = makeMv(layout, {
+      sessionFor: (id) => (id === "d1" ? dormantSession("d1") : undefined),
+      onResume,
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    mv.el.querySelector<HTMLButtonElement>(".mv-dormant-resume")?.click();
+    expect(onResume).toHaveBeenCalledWith("d1");
+  });
+});
+
 describe("multiview pane-drag swap", () => {
   beforeEach(() => {
     stubFetch();

web/src/multiview.ts

@@ -6,6 +6,10 @@
 
 import type { SidebarHandle } from "./catalog.js";
 import type { ConnectionPool } from "./connections.js";
+import { activityDurationLabel, activityHeldMs } from "./activity.js";
+import { escapeHtml } from "./html.js";
+import { sessionName } from "./types.js";
+import type { Session } from "./types.js";
 import {
   activeTab,
   addTab,
@@ -34,6 +38,14 @@ export interface MultiViewOptions {
   onDisconnect: (sessionId: string) => void;
   /** Welcome content for an empty tab. */
   renderWelcome: () => HTMLElement;
+  /** The session behind a leaf, when known — used to gate a live attach on
+   *  `status === "Running"` (#168 review) and to fill in the dormant pane's
+   *  resume affordance. A leaf whose session this returns `undefined` for
+   *  (unknown to the caller) attaches as before, so callers that don't wire
+   *  this up see no change in behaviour. */
+  sessionFor?: (sessionId: string) => Session | undefined;
+  /** Resume a dormant session (#166/#168), from its pane's own affordance. */
+  onResume?: (sessionId: string) => Promise<unknown>;
   /** Called when a spawn fills a pane with a new session, so the shell can
    *  re-evaluate its route (sidebar vs attach layout). */
   onOpenSessionsChange?: () => void;
@@ -262,6 +274,44 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     persist();
   }
 
+  // ---- dormant panes (#168 review) ----
+
+  /** The session behind `sessionId` when it is known and not `Running` —
+   *  what gates a leaf away from a live attach and towards the resume
+   *  affordance instead. */
+  function dormantSessionFor(sessionId: string): Session | undefined {
+    const s = opts.sessionFor?.(sessionId);
+    return s && s.status !== "Running" ? s : undefined;
+  }
+
+  /** docs/PREVIEW.md / docs/SIDEBAR.md: what the content pane can honestly
+   *  show for a session with no pane behind it — its metadata and a resume
+   *  affordance, never a live terminal that would just die with WS 1006. */
+  function renderDormantPane(host: HTMLElement, session: Session): void {
+    const heldMs = activityHeldMs(session.last_activity_at ?? session.created_at, Date.now());
+    const age = heldMs !== null ? activityDurationLabel(heldMs) : null;
+    const wrap = document.createElement("div");
+    wrap.className = "mv-pane-dormant";
+    wrap.innerHTML = `
+      <div class="mv-dormant-glyph" aria-hidden="true">◌</div>
+      <div class="mv-dormant-name">${escapeHtml(sessionName(session))}</div>
+      <div class="mv-dormant-cwd" title="${escapeHtml(session.cwd)}">${escapeHtml(session.cwd)}</div>
+      <div class="mv-dormant-detail">dormant${age ? ` for ${escapeHtml(age)}` : ""} — nothing running behind it</div>
+      <button type="button" class="btn btn-primary mv-dormant-resume">Resume</button>
+    `;
+    const btn = wrap.querySelector(".mv-dormant-resume") as HTMLButtonElement;
+    btn.addEventListener("click", () => {
+      btn.disabled = true;
+      btn.textContent = "Resuming…";
+      opts.onResume?.(session.id)?.catch((e: Error) => {
+        btn.disabled = false;
+        btn.textContent = "Resume";
+        alert(`Failed to resume: ${e.message}`);
+      });
+    });
+    host.replaceChildren(wrap);
+  }
+
   // ---- pane + split DOM ----
 
   function buildPane(leaf: Extract<Node, { kind: "leaf" }>): {
@@ -378,7 +428,12 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     if (node.kind === "leaf") {
       const pane = buildPane(node);
       if (node.sessionId) {
-        hosts.push({ id: node.sessionId, host: pane.host, info: infoFor(node.sessionId) });
+        const dormant = dormantSessionFor(node.sessionId);
+        if (dormant) {
+          renderDormantPane(pane.host, dormant);
+        } else {
+          hosts.push({ id: node.sessionId, host: pane.host, info: infoFor(node.sessionId) });
+        }
       }
       return pane.el;
     }
@@ -616,9 +671,13 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     wrap.appendChild(pane.el);
     canvas.appendChild(wrap);
 
+    const dormant = focused.sessionId ? dormantSessionFor(focused.sessionId) : undefined;
+    if (dormant) renderDormantPane(pane.host, dormant);
     // Only the focused leaf's session is live on mobile; the rest park.
     pool.setVisible(
-      focused.sessionId ? [{ id: focused.sessionId, pane: pane.host, info: infoFor(focused.sessionId) }] : [],
+      focused.sessionId && !dormant
+        ? [{ id: focused.sessionId, pane: pane.host, info: infoFor(focused.sessionId) }]
+        : [],
       { focus: !preview && !quietRender },
     );
     if (!preview) pool.setFocus(focused.sessionId ?? null);

web/src/reconnect.test.ts

@@ -47,6 +47,13 @@ describe("shouldRetryClose", () => {
   it("never retries a clean close", () => {
     expect(shouldRetryClose("a", 1000, running)).toBe(false);
   });
+
+  // #168 review: a handshake that never opened is a rejection (e.g. a
+  // dormant session's 409 not_attachable), not a dropped stream. Retrying it
+  // loops forever if the catalog status hasn't caught up yet.
+  it("never retries a socket that never opened, even if the catalog still says running", () => {
+    expect(shouldRetryClose("a", 1006, running, false)).toBe(false);
+  });
 });
 
 describe("backoff bounds", () => {

web/src/reconnect.ts

@@ -26,7 +26,15 @@ export function shouldRetryClose(
   sessionId: Uuid,
   code: number,
   sessions: ReadonlyMap<Uuid, Session>,
+  /** Did this socket ever reach `open`? A handshake that never completed is
+   *  the daemon rejecting the attach (dormant/unknown) rather than a dropped
+   *  stream — retrying it spins in place until the catalog updates, which for
+   *  a dormant session it never will (#168 review). Defaults to `true` so
+   *  existing callers that only track drops of an established link are
+   *  unaffected. */
+  everOpened = true,
 ): boolean {
   if (code >= APPLICATION_CLOSE || code === CLEAN_CLOSE) return false;
+  if (!everOpened) return false;
   return sessions.get(sessionId)?.status === "Running";
 }

web/src/routes.ts

@@ -37,6 +37,12 @@ export function sessionFocus(id: Uuid): string {
   return `${session(id)}/focus`;
 }
 
+/** `POST /api/sessions/:id/resume` (#166/#168): respawn a dormant session
+ * under its own uuid and sidecar. */
+export function sessionResume(id: Uuid): string {
+  return `${session(id)}/resume`;
+}
+
 /** Append the `path` query parameter `DIRS` and `GITROOT` accept. */
 export function withPathQuery(route: string, value: string): string {
   return `${route}?${PATH_QUERY}=${encodeURIComponent(value)}`;

web/src/styles.css

@@ -1210,12 +1210,16 @@ textarea {
 }
 
 /* Exited sessions recede: dimmed name + an "exited" badge carry status, so it's
-   never the running tint's absence alone doing the work. */
-.tree-leaf[data-status="dead"] {
+   never the running tint's absence alone doing the work. A dormant session
+   (#168, docs/SIDEBAR.md) reads the same muted way — it is known, not gone,
+   but there is nothing running behind it either. */
+.tree-leaf[data-status="dead"],
+.tree-leaf.is-dormant {
   color: var(--muted);
 }
 
-.tree-leaf[data-status="dead"] .leaf-name {
+.tree-leaf[data-status="dead"] .leaf-name,
+.tree-leaf.is-dormant .leaf-name {
   color: var(--muted);
   font-weight: 400;
 }
@@ -1754,7 +1758,8 @@ input.leaf-rename:focus {
   }
 }
 
-.leaf-clone:hover {
+.leaf-clone:hover,
+.leaf-resume:hover {
   color: var(--accent);
   background: var(--accent-tint);
   border-color: color-mix(in oklab, var(--accent) 40%, transparent);
@@ -3265,6 +3270,42 @@ input.leaf-rename:focus {
   font-size: var(--fs-13);
 }
 
+/* #168: what a pane shows for a dormant session — its metadata and a resume
+   action, in place of the live terminal there is nothing to attach to. */
+.mv-pane-dormant {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sp-2);
+  padding: var(--sp-4);
+  text-align: center;
+  color: var(--muted);
+}
+.mv-dormant-glyph {
+  font-size: 28px;
+  color: var(--faint);
+}
+.mv-dormant-name {
+  font-size: var(--fs-15);
+  font-weight: 500;
+  color: var(--ink);
+}
+.mv-dormant-cwd {
+  font-size: var(--fs-12);
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.mv-dormant-detail {
+  font-size: var(--fs-12);
+}
+.mv-dormant-resume {
+  margin-top: var(--sp-2);
+}
+
 /* pane tools cluster (disconnect / split / close), top-right corner. The attach
    header's own disconnect button is hidden — ⏻ lives here as the leftmost tool. */
 .mv-pane-tools {

web/src/tree.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { buildTree, mergeLinear, type TreeFolder, type TreeNode } from "./tree.js";
+import { buildTree, compareNodes, mergeLinear, type TreeFolder, type TreeNode } from "./tree.js";
 import type { Session } from "./types.js";
 
 function session(id: string, cwd: string, command = "bash"): Session {
@@ -67,6 +67,42 @@ describe("buildTree", () => {
     expect(root.children[0].kind).toBe("folder");
     expect(root.children[1].kind).toBe("leaf");
   });
+
+  // #168, docs/SIDEBAR.md: a dormant session takes the lowest precedence in
+  // the ordering, so live work always sorts above it, even a name that would
+  // otherwise sort first.
+  it("sorts a dormant session after live ones in the same folder, name notwithstanding", () => {
+    const dormant = { ...session("aaa-dormant", "/home/n/work"), status: "Dormant" } as Session;
+    const live = session("zzz-live", "/home/n/work");
+    const root = buildTree([dormant, live], "/home/n") as TreeFolder;
+    const folder = root.children[0] as TreeFolder;
+    const ids = folder.children.map((c) => (c.kind === "leaf" ? c.session.id : c.name));
+    expect(ids).toEqual(["zzz-live", "aaa-dormant"]);
+  });
+
+  it("still sorts dormant sessions by name against each other", () => {
+    const a = {
+      ...session("a", "/home/n/work"),
+      status: "Dormant",
+      metadata: { name: "a" },
+    } as Session;
+    const b = {
+      ...session("b", "/home/n/work"),
+      status: "Dormant",
+      metadata: { name: "b" },
+    } as Session;
+    const root = buildTree([b, a], "/home/n") as TreeFolder;
+    const folder = root.children[0] as TreeFolder;
+    const ids = folder.children.map((c) => (c.kind === "leaf" ? c.session.id : c.name));
+    expect(ids).toEqual(["a", "b"]);
+  });
+
+  it("exposes the leaf/name precedence directly via compareNodes", () => {
+    const dormant: TreeNode = { kind: "leaf", session: { ...session("a", "/x"), status: "Dormant" } };
+    const live: TreeNode = { kind: "leaf", session: session("b", "/x") };
+    expect(compareNodes(dormant, live)).toBeGreaterThan(0);
+    expect(compareNodes(live, dormant)).toBeLessThan(0);
+  });
 });
 
 describe("mergeLinear", () => {

web/src/tree.ts

@@ -18,8 +18,16 @@ export interface TreeLeaf {
 
 export type TreeNode = TreeFolder | TreeLeaf;
 
+/** docs/SIDEBAR.md: a dormant session takes the lowest precedence in the
+ * ordering, so live work always sorts above it regardless of name. */
+function dormantRank(node: TreeNode): number {
+  return node.kind === "leaf" && node.session.status === "Dormant" ? 1 : 0;
+}
+
 export function compareNodes(a: TreeNode, b: TreeNode): number {
   if (a.kind !== b.kind) return a.kind === "folder" ? -1 : 1;
+  const rank = dormantRank(a) - dormantRank(b);
+  if (rank !== 0) return rank;
   const an = a.kind === "folder" ? a.name : sessionName(a.session);
   const bn = b.kind === "folder" ? b.name : sessionName(b.session);
   return an.localeCompare(bn);