feat(maestro): port spawn dialog to React (#248)

Ports the vanilla spawn form/modal to src/components/spawn/:
SpawnModal, SpawnForm, DirAutocomplete, BranchPicker, and a
useFastForward hook for the one-keystroke spawn. Pure logic modules
(spawnForm.ts's buildSpawnRequest, fastForward.ts, spawnSimilar.ts,
projectList.ts, toolIcon.ts) are reused as-is rather than re-derived.

Exports supportsStructuredView from spawnForm.ts so the React form can
share the structured-view-eligibility check with the vanilla one.

.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "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:*)",
+      "Bash(cargo test:*)"
+    ]
+  }
+}

CLAUDE.md

@@ -92,6 +92,12 @@ clients — how it opens, the sigils, the key model, the match-and-rank algorith
 the two matchers must agree on, and the fixture table they are tested against.
 Read it before changing either bar or either matcher.
 
+`docs/STRUCTURED-VIEW.md` is the contract for a structured session (an agent
+run as a daemon child over ACP instead of in a tmux pane) — the eight
+transcript row kinds, the two projections and their cursor/replay semantics,
+the handshake and declined capabilities, and the approval nonce rules. Read
+it before changing anything that renders a structured session.
+
 `nix run .#dev` (or `just dev`) brings up the whole local stack under
 process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
 daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only

Cargo.lock

@@ -1467,6 +1467,7 @@ dependencies = [
  "maestro-cli",
  "maestro-daemon",
  "maestro-tui",
+ "tempfile",
  "tokio",
  "tracing-subscriber",
 ]
@@ -1477,6 +1478,7 @@ version = "0.1.0"
 dependencies = [
  "agent-client-protocol",
  "libc",
+ "serde",
  "serde_json",
  "tempfile",
  "thiserror 1.0.69",
@@ -1558,6 +1560,7 @@ version = "0.1.0"
 dependencies = [
  "chrono",
  "futures-util",
+ "libc",
  "maestro-protocol",
  "maestro-testing",
  "maestro-tui",
@@ -1643,6 +1646,7 @@ dependencies = [
  "tokio",
  "tokio-tungstenite 0.21.0",
  "tracing",
+ "unicode-width",
  "uuid",
  "vt100",
 ]

Cargo.toml

@@ -10,7 +10,7 @@ repository = "https://git.naps.pt/naps62/maestro"
 publish = false
 
 [workspace.dependencies]
-agent-client-protocol = "2.1"
+agent-client-protocol = { version = "2.1", features = ["unstable_tool_call_name"] }
 axum = { version = "0.7", features = ["ws"] }
 chrono = { version = "0.4", default-features = false, features = ["clock", "serde"] }
 clap = { version = "4.5", features = ["derive", "env"] }
@@ -44,6 +44,7 @@ tokio-util = { version = "0.7", features = ["compat"] }
 toml = "0.8"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+unicode-width = "0.1"
 uuid = { version = "1", features = ["v4", "serde"] }
 ratatui = "0.28"
 vt100 = "0.15"

crates/maestro-acp/Cargo.toml

@@ -5,11 +5,12 @@ edition.workspace = true
 license.workspace = true
 repository.workspace = true
 publish.workspace = true
-description = "ACP client role: one claude-code-acp child per structured session"
+description = "ACP client role: one provider adapter child per structured session"
 
 [dependencies]
 agent-client-protocol.workspace = true
 libc.workspace = true
+serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 tokio.workspace = true

crates/maestro-acp/src/lib.rs

@@ -1,5 +1,5 @@
-//! ACP client role for the daemon (#134): one `claude-code-acp` child per
-//! structured session.
+//! ACP client role for the daemon: one provider adapter child per structured
+//! session.
 //!
 //! The daemon is the client; the adapter is the agent. [`spawn`] starts the
 //! adapter as a child process with stdio pipes, in the session's `cwd` with
@@ -9,10 +9,10 @@
 //!
 //! **The handshake declares almost nothing.** `initialize` reports
 //! `fs.readTextFile`, `fs.writeTextFile` and `terminal` as `false`, so the
-//! adapter uses Claude Code's own Read / Write / Bash instead of asking the
-//! daemon to act on its behalf — exactly what already happens in the
-//! terminal view. `session/request_permission` is the one client method that
-//! gets a real implementation, in #139; here it is a stub that declines.
+//! adapter uses the provider's own file and command tools instead of asking
+//! the daemon to act on its behalf — exactly what already happens in the
+//! terminal view. `session/request_permission` is the one client method with
+//! a real implementation.
 //!
 //! Every `session/update` notification the adapter sends lands on an
 //! unbounded channel the session owns ([`AcpSession::take_updates`]). Nothing
@@ -42,29 +42,62 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use agent_client_protocol::schema::v1::{
-    CancelNotification, ClientCapabilities, FileSystemCapabilities, Implementation,
-    InitializeRequest, LoadSessionRequest, NewSessionRequest, RequestPermissionOutcome,
-    RequestPermissionRequest, RequestPermissionResponse, SessionId, SessionNotification,
+    CancelNotification, ClientCapabilities, ConfigOptionUpdate, ContentBlock, CurrentModeUpdate,
+    FileSystemCapabilities, Implementation, InitializeRequest, PromptRequest,
+    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
+    SessionConfigKind, SessionConfigOption, SessionConfigOptionCategory, SessionConfigOptionValue,
+    SessionConfigSelectOption, SessionId, SessionModeState, SessionNotification, SessionUpdate,
+    SetSessionConfigOptionRequest, SetSessionModeRequest,
 };
 use agent_client_protocol::schema::ProtocolVersion;
-use agent_client_protocol::{ByteStreams, Client};
+use agent_client_protocol::{ByteStreams, Client, JsonRpcRequest, JsonRpcResponse};
+use serde::{Deserialize, Serialize};
 use tokio::io::AsyncBufReadExt;
 use tokio::sync::{mpsc, oneshot, watch};
 use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 
 pub use agent_client_protocol::schema::v1 as schema;
 
-/// The adapter binary, resolved on `PATH`.
-pub const ADAPTER_BIN: &str = "claude-code-acp";
+/// ACP adapter selected from the structured session's resolved command.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AcpAdapter {
+    ClaudeCode,
+    Codex,
+}
 
-/// How to install the adapter when it is missing. Named in the error so an
-/// operator staring at a failed session knows what to run.
+impl AcpAdapter {
+    pub const fn binary(self) -> &'static str {
+        match self {
+            Self::ClaudeCode => "claude-code-acp",
+            Self::Codex => "codex-acp",
+        }
+    }
+
+    pub const fn install_command(self) -> &'static str {
+        match self {
+            Self::ClaudeCode => "npm install -g --prefix ~/.local @zed-industries/claude-code-acp",
+            Self::Codex => "npm install -g --prefix ~/.local @agentclientprotocol/codex-acp",
+        }
+    }
+}
+
+impl std::fmt::Display for AcpAdapter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Self::ClaudeCode => "Claude Code",
+            Self::Codex => "Codex",
+        })
+    }
+}
+
+/// Compatibility aliases for Claude Code callers.
+pub const ADAPTER_BIN: &str = "claude-code-acp";
 pub const INSTALL_COMMAND: &str =
     "npm install -g --prefix ~/.local @zed-industries/claude-code-acp";
 
 /// How long `initialize` + `session/new` may take before the spawn is
-/// declared failed. The real adapter boots a node process and the Claude
-/// Code SDK behind it; a slow machine takes seconds, never a minute.
+/// declared failed. The real adapters boot a node process and their provider
+/// client behind it; a slow machine takes seconds, never a minute.
 pub const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(60);
 
 /// How long [`AcpSession::terminate`] waits after `session/cancel` before
@@ -77,6 +110,75 @@ pub const TERM_GRACE: Duration = Duration::from_secs(2);
 
 /// Bytes of the child's stderr kept for the failure message.
 const STDERR_TAIL_BYTES: usize = 4096;
+const LEGACY_MODEL_CONFIG_ID: &str = "__maestro_legacy_model";
+const LEGACY_MODE_CONFIG_ID: &str = "__maestro_legacy_mode";
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/new", response = ExtendedNewSessionResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedNewSessionRequest {
+    cwd: PathBuf,
+    mcp_servers: Vec<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedNewSessionResponse {
+    session_id: SessionId,
+    #[serde(default)]
+    modes: Option<SessionModeState>,
+    #[serde(default)]
+    config_options: Option<Vec<SessionConfigOption>>,
+    #[serde(default)]
+    models: Option<LegacyModelState>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/load", response = ExtendedLoadSessionResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedLoadSessionRequest {
+    session_id: SessionId,
+    cwd: PathBuf,
+    mcp_servers: Vec<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedLoadSessionResponse {
+    #[serde(default)]
+    modes: Option<SessionModeState>,
+    #[serde(default)]
+    config_options: Option<Vec<SessionConfigOption>>,
+    #[serde(default)]
+    models: Option<LegacyModelState>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyModelState {
+    current_model_id: String,
+    available_models: Vec<LegacyModel>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyModel {
+    model_id: String,
+    name: String,
+    #[serde(default)]
+    description: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/set_model", response = LegacySetModelResponse)]
+#[serde(rename_all = "camelCase")]
+struct LegacySetModelRequest {
+    session_id: SessionId,
+    model_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+struct LegacySetModelResponse {}
 
 /// What [`spawn`] needs to start one adapter.
 #[derive(Debug, Clone)]
@@ -93,6 +195,8 @@ pub struct SpawnConfig {
     /// instead of opening a fresh one. The adapter must advertise
     /// `loadSession`; the handshake fails otherwise.
     pub load_session: Option<String>,
+    /// The provider-specific adapter to launch.
+    pub adapter: AcpAdapter,
 }
 
 impl SpawnConfig {
@@ -102,6 +206,7 @@ impl SpawnConfig {
             env,
             handshake_timeout: HANDSHAKE_TIMEOUT,
             load_session: None,
+            adapter: AcpAdapter::ClaudeCode,
         }
     }
 
@@ -110,37 +215,59 @@ impl SpawnConfig {
         self.load_session = Some(session_id.into());
         self
     }
+
+    pub fn adapter(mut self, adapter: AcpAdapter) -> Self {
+        self.adapter = adapter;
+        self
+    }
+}
+
+/// A blocked ACP permission request delivered to the daemon.
+#[derive(Debug)]
+pub struct PermissionRequest {
+    /// The prompt turn that was active when ACP delivered this callback.
+    pub turn: u64,
+    pub request: RequestPermissionRequest,
+    pub response: oneshot::Sender<RequestPermissionOutcome>,
 }
 
 #[derive(Debug, thiserror::Error)]
 pub enum AcpError {
     /// The adapter is not on `PATH`. The message names the install command
     /// so the failed session is actionable rather than silently dead.
-    #[error("{ADAPTER_BIN} not found on PATH; install it with: {INSTALL_COMMAND}")]
-    AdapterMissing,
-    #[error("failed to start {ADAPTER_BIN}: {0}")]
-    Spawn(#[source] std::io::Error),
+    #[error("{adapter} ACP adapter ({bin}) not found on PATH; install it with: {install_command}", bin = adapter.binary(), install_command = adapter.install_command())]
+    AdapterMissing { adapter: AcpAdapter },
+    #[error("failed to start {adapter} ACP adapter ({bin}): {source}", bin = adapter.binary())]
+    Spawn {
+        adapter: AcpAdapter,
+        #[source]
+        source: std::io::Error,
+    },
     /// The adapter answered the handshake with an error.
     #[error("ACP handshake failed: {0}")]
     Handshake(String),
     /// The adapter went away before the handshake finished. Carries the
     /// tail of its stderr, which is where a missing Claude login shows up.
-    #[error("{ADAPTER_BIN} exited during the ACP handshake ({status}){stderr}")]
-    ExitedEarly { status: String, stderr: String },
+    #[error("{adapter} ACP adapter ({bin}) exited during the ACP handshake ({status}){stderr}", bin = adapter.binary())]
+    ExitedEarly {
+        adapter: AcpAdapter,
+        status: String,
+        stderr: String,
+    },
     #[error("ACP handshake timed out after {0:?}")]
     HandshakeTimeout(Duration),
 }
 
 /// Resolve [`ADAPTER_BIN`] against the `PATH` the child would run with: the
 /// session env's `PATH` when it sets one, the daemon's own otherwise.
-pub fn resolve_adapter(env: &HashMap<String, String>) -> Option<PathBuf> {
+pub fn resolve_adapter(adapter: AcpAdapter, env: &HashMap<String, String>) -> Option<PathBuf> {
     let path: OsString = match env.get("PATH") {
         Some(p) => OsString::from(p),
         None => std::env::var_os("PATH")?,
     };
     std::env::split_paths(&path)
         .filter(|dir| !dir.as_os_str().is_empty())
-        .map(|dir| dir.join(ADAPTER_BIN))
+        .map(|dir| dir.join(adapter.binary()))
         .find(|candidate| is_executable(candidate))
 }
 
@@ -153,9 +280,55 @@ fn is_executable(path: &Path) -> bool {
 
 enum Command {
     Cancel,
+    Prompt {
+        text: String,
+        turn: u64,
+        done: oneshot::Sender<Result<(), String>>,
+    },
+    SetConfig {
+        config_id: String,
+        value: SessionConfigOptionValue,
+        done: oneshot::Sender<Result<(), String>>,
+    },
     Close,
 }
 
+struct ConnectionConfig {
+    cwd: PathBuf,
+    load_session: Option<String>,
+    adapter: AcpAdapter,
+}
+
+enum ChildCommand {
+    Signal(libc::c_int),
+    Reap(oneshot::Sender<bool>),
+}
+
+#[derive(Debug, Default)]
+struct PermissionTurnState {
+    active: Option<u64>,
+}
+
+impl PermissionTurnState {
+    fn begin(&mut self, turn: u64) {
+        self.active = Some(turn);
+    }
+
+    fn cancel_active(&mut self) {
+        self.active = None;
+    }
+
+    fn finish(&mut self, turn: u64) {
+        if self.active == Some(turn) {
+            self.active = None;
+        }
+    }
+
+    fn callback_turn(&self) -> Option<u64> {
+        self.active
+    }
+}
+
 /// Why the handshake did not produce a session id.
 enum ReadyError {
     /// The adapter answered with an error.
@@ -180,7 +353,9 @@ pub struct AcpSession {
     session_id: String,
     pid: u32,
     commands: mpsc::UnboundedSender<Command>,
+    child_commands: mpsc::UnboundedSender<ChildCommand>,
     updates: Mutex<Option<mpsc::UnboundedReceiver<SessionNotification>>>,
+    permission_requests: Mutex<Option<mpsc::UnboundedReceiver<PermissionRequest>>>,
     exit: watch::Receiver<Option<ExitStatus>>,
 }
 
@@ -201,6 +376,18 @@ impl AcpSession {
         self.exit.borrow().is_some()
     }
 
+    /// Reap the child if it has already exited.
+    pub async fn reap_if_exited(&self) -> bool {
+        if self.has_exited() {
+            return true;
+        }
+        let (sent, received) = oneshot::channel();
+        if self.child_commands.send(ChildCommand::Reap(sent)).is_err() {
+            return self.has_exited();
+        }
+        received.await.unwrap_or_else(|_| self.has_exited())
+    }
+
     /// Wait for the child to exit.
     pub async fn wait(&self) -> Option<ExitStatus> {
         wait_exit(&self.exit).await
@@ -212,18 +399,56 @@ impl AcpSession {
         self.updates.lock().expect("updates mutex").take()
     }
 
+    pub fn take_permission_requests(&self) -> Option<mpsc::UnboundedReceiver<PermissionRequest>> {
+        self.permission_requests
+            .lock()
+            .expect("permission requests")
+            .take()
+    }
+
     /// Send `session/cancel`. Fire-and-forget: a closed connection means the
     /// child is already gone, which is the outcome cancel was after.
     pub fn cancel(&self) {
         let _ = self.commands.send(Command::Cancel);
     }
 
+    /// Send a user prompt and receive completion once the agent ends the turn.
+    pub fn prompt(
+        &self,
+        text: String,
+        turn: u64,
+    ) -> Result<oneshot::Receiver<Result<(), String>>, String> {
+        let (done_tx, done_rx) = oneshot::channel();
+        self.commands
+            .send(Command::Prompt {
+                text,
+                turn,
+                done: done_tx,
+            })
+            .map_err(|_| "ACP connection is closed".to_string())?;
+        Ok(done_rx)
+    }
+
+    /// Change one option advertised by the ACP agent.
+    pub fn set_config(
+        &self,
+        config_id: String,
+        value: SessionConfigOptionValue,
+    ) -> Result<oneshot::Receiver<Result<(), String>>, String> {
+        let (done_tx, done_rx) = oneshot::channel();
+        self.commands
+            .send(Command::SetConfig {
+                config_id,
+                value,
+                done: done_tx,
+            })
+            .map_err(|_| "ACP connection is closed".to_string())?;
+        Ok(done_rx)
+    }
+
     /// End the child: `session/cancel`, wait `cancel_grace`, `SIGTERM`, wait
     /// `term_grace`, `SIGKILL`. Returns once the child has been reaped.
     pub async fn terminate(&self, cancel_grace: Duration, term_grace: Duration) {
-        if self.has_exited() {
-            return;
-        }
         self.cancel();
         if tokio::time::timeout(cancel_grace, self.wait())
             .await
@@ -245,16 +470,14 @@ impl AcpSession {
     }
 
     fn signal(&self, sig: libc::c_int) {
-        signal_pid(self.pid, sig);
+        let _ = self.child_commands.send(ChildCommand::Signal(sig));
     }
 }
 
 impl Drop for AcpSession {
     fn drop(&mut self) {
+        self.signal(libc::SIGTERM);
         let _ = self.commands.send(Command::Close);
-        if !self.has_exited() {
-            self.signal(libc::SIGTERM);
-        }
     }
 }
 
@@ -263,7 +486,9 @@ impl Drop for AcpSession {
 /// Fails without a running child: on any error the process is already
 /// signalled, so a failed session never leaves a stray adapter behind.
 pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
-    let adapter = resolve_adapter(&config.env).ok_or(AcpError::AdapterMissing)?;
+    let provider = config.adapter;
+    let adapter = resolve_adapter(provider, &config.env)
+        .ok_or(AcpError::AdapterMissing { adapter: provider })?;
 
     let mut cmd = tokio::process::Command::new(&adapter);
     cmd.current_dir(&config.cwd)
@@ -291,31 +516,42 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
             });
         }
     }
-    let mut child = cmd.spawn().map_err(AcpError::Spawn)?;
+    let mut child = cmd.spawn().map_err(|source| AcpError::Spawn {
+        adapter: provider,
+        source,
+    })?;
     let pid = child.id().expect("child pid is known before wait");
     let stdin = child.stdin.take().expect("piped stdin");
     let stdout = child.stdout.take().expect("piped stdout");
     let stderr = child.stderr.take().expect("piped stderr");
 
     let stderr_tail = Arc::new(Mutex::new(VecDeque::<u8>::new()));
-    tokio::spawn(drain_stderr(stderr, pid, stderr_tail.clone()));
+    tokio::spawn(drain_stderr(stderr, pid, stderr_tail.clone(), provider));
 
     let (exit_tx, exit_rx) = watch::channel(None);
-    tokio::spawn(async move {
-        let status = child.wait().await.ok();
-        tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
-        let _ = exit_tx.send(status);
-    });
+    let (child_commands_tx, child_commands_rx) = mpsc::unbounded_channel();
+    tokio::spawn(supervise_child(
+        child,
+        pid,
+        child_commands_rx,
+        exit_tx,
+        provider,
+    ));
 
     let (updates_tx, updates_rx) = mpsc::unbounded_channel();
+    let (permission_tx, permission_rx) = mpsc::unbounded_channel();
     let (commands_tx, commands_rx) = mpsc::unbounded_channel();
     let (ready_tx, ready_rx) = oneshot::channel();
     let transport = ByteStreams::new(stdin.compat_write(), stdout.compat());
     tokio::spawn(run_connection(
         transport,
-        config.cwd.clone(),
-        config.load_session.clone(),
+        ConnectionConfig {
+            cwd: config.cwd.clone(),
+            load_session: config.load_session.clone(),
+            adapter: provider,
+        },
         updates_tx,
+        permission_tx,
         commands_rx,
         ready_tx,
     ));
@@ -327,7 +563,9 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
                 session_id,
                 pid,
                 commands: commands_tx,
+                child_commands: child_commands_tx,
                 updates: Mutex::new(Some(updates_rx)),
+                permission_requests: Mutex::new(Some(permission_rx)),
                 exit: exit_rx,
             });
         }
@@ -344,6 +582,7 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
                     .to_string()
             };
             AcpError::ExitedEarly {
+                adapter: provider,
                 status: status.map_or_else(|| "unknown status".into(), |s| s.to_string()),
                 stderr: if stderr.is_empty() {
                     String::new()
@@ -356,12 +595,12 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
     };
     // No half-started adapter survives a failed spawn.
     let _ = commands_tx.send(Command::Close);
-    signal_pid(pid, libc::SIGTERM);
+    let _ = child_commands_tx.send(ChildCommand::Signal(libc::SIGTERM));
     if tokio::time::timeout(TERM_GRACE, wait_exit(&exit_rx))
         .await
         .is_err()
     {
-        signal_pid(pid, libc::SIGKILL);
+        let _ = child_commands_tx.send(ChildCommand::Signal(libc::SIGKILL));
         wait_exit(&exit_rx).await;
     }
     Err(failure)
@@ -373,11 +612,55 @@ async fn wait_exit(exit: &watch::Receiver<Option<ExitStatus>>) -> Option<ExitSta
     *status
 }
 
-fn signal_pid(pid: u32, sig: libc::c_int) {
-    // ESRCH just means the child is already gone.
-    // SAFETY: plain syscall on a pid we spawned and have not reaped.
-    unsafe {
-        libc::kill(pid as libc::pid_t, sig);
+async fn supervise_child(
+    mut child: tokio::process::Child,
+    pid: u32,
+    mut commands: mpsc::UnboundedReceiver<ChildCommand>,
+    exit_tx: watch::Sender<Option<ExitStatus>>,
+    adapter: AcpAdapter,
+) {
+    loop {
+        tokio::select! {
+            status = child.wait() => {
+                let status = status.ok();
+                tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
+                let _ = exit_tx.send(status);
+                return;
+            }
+            command = commands.recv() => match command {
+                Some(ChildCommand::Signal(sig)) => {
+                    // This task alone owns `child`. It cannot reap the child
+                    // between receiving this command and sending the signal,
+                    // so its PID cannot be reused in that window.
+                    unsafe { libc::kill(pid as libc::pid_t, sig) };
+                }
+                Some(ChildCommand::Reap(done)) => match child.try_wait() {
+                    Ok(Some(status)) => {
+                        let _ = done.send(true);
+                        tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
+                        let _ = exit_tx.send(Some(status));
+                        return;
+                    }
+                    Ok(None) => {
+                        let _ = done.send(false);
+                    }
+                    Err(error) => {
+                        tracing::warn!(pid, %error, provider = %adapter, "could not reap ACP adapter");
+                        let _ = done.send(false);
+                    }
+                },
+                None => {
+                    // The session vanished without a command receiver. This
+                    // task still owns the unreaped child, so this cannot hit
+                    // a reused PID.
+                    unsafe { libc::kill(pid as libc::pid_t, libc::SIGTERM) };
+                    let status = child.wait().await.ok();
+                    tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
+                    let _ = exit_tx.send(status);
+                    return;
+                }
+            },
+        }
     }
 }
 
@@ -391,11 +674,106 @@ fn client_capabilities() -> ClientCapabilities {
         .terminal(false)
 }
 
+fn advertised_config_options(
+    mut options: Vec<SessionConfigOption>,
+    modes: Option<&SessionModeState>,
+    models: Option<&LegacyModelState>,
+) -> Vec<SessionConfigOption> {
+    let has_model = options
+        .iter()
+        .any(|option| matches!(option.category, Some(SessionConfigOptionCategory::Model)));
+    let has_mode = options
+        .iter()
+        .any(|option| matches!(option.category, Some(SessionConfigOptionCategory::Mode)));
+    if let Some(models) = models.filter(|_| !has_model) {
+        let mut choices = models
+            .available_models
+            .iter()
+            .map(|model| {
+                let mut option =
+                    SessionConfigSelectOption::new(model.model_id.clone(), &model.name);
+                if model.model_id == "default" {
+                    option.name = "Opus (default)".into();
+                }
+                option.description.clone_from(&model.description);
+                option
+            })
+            .collect::<Vec<_>>();
+        if !models
+            .available_models
+            .iter()
+            .any(|model| model.model_id == "fable")
+        {
+            choices.push(SessionConfigSelectOption::new("fable", "Fable"));
+        }
+        options.push(
+            SessionConfigOption::select(
+                LEGACY_MODEL_CONFIG_ID,
+                "Model",
+                models.current_model_id.clone(),
+                choices,
+            )
+            .category(SessionConfigOptionCategory::Model),
+        );
+    }
+    if let Some(modes) = modes.filter(|_| !has_mode) {
+        let choices = modes
+            .available_modes
+            .iter()
+            .map(|mode| {
+                let mut option = SessionConfigSelectOption::new(mode.id.0.clone(), &mode.name);
+                option.description.clone_from(&mode.description);
+                option
+            })
+            .collect::<Vec<_>>();
+        options.push(
+            SessionConfigOption::select(
+                LEGACY_MODE_CONFIG_ID,
+                "Mode",
+                modes.current_mode_id.0.clone(),
+                choices,
+            )
+            .category(SessionConfigOptionCategory::Mode),
+        );
+    }
+    options
+}
+
+fn replace_config_value(
+    options: &Arc<Mutex<Vec<SessionConfigOption>>>,
+    config_id: &str,
+    value: &SessionConfigOptionValue,
+) -> Vec<SessionConfigOption> {
+    let mut options = options.lock().expect("config options");
+    if let Some(option) = options
+        .iter_mut()
+        .find(|option| option.id.0.as_ref() == config_id)
+    {
+        match (&mut option.kind, value) {
+            (SessionConfigKind::Select(select), SessionConfigOptionValue::ValueId { value }) => {
+                select.current_value = value.clone();
+            }
+            (SessionConfigKind::Boolean(boolean), SessionConfigOptionValue::Boolean { value }) => {
+                boolean.current_value = *value;
+            }
+            _ => {}
+        }
+    }
+    options.clone()
+}
+
+fn config_notification(session_id: &str, options: Vec<SessionConfigOption>) -> SessionNotification {
+    SessionNotification::new(
+        SessionId::new(session_id),
+        SessionUpdate::ConfigOptionUpdate(ConfigOptionUpdate::new(options)),
+    )
+}
+
 async fn run_connection<T>(
     transport: T,
-    cwd: PathBuf,
-    load_session: Option<String>,
+    config: ConnectionConfig,
     updates_tx: mpsc::UnboundedSender<SessionNotification>,
+    permission_requests: mpsc::UnboundedSender<PermissionRequest>,
     mut commands_rx: mpsc::UnboundedReceiver<Command>,
     ready_tx: oneshot::Sender<Result<String, ReadyError>>,
 ) where
@@ -407,6 +785,11 @@ async fn run_connection<T>(
     // history the event log already holds (#135).
     let replaying = Arc::new(AtomicBool::new(false));
     let replaying_seen = replaying.clone();
+    // ACP callbacks have no turn id. The daemon never queues a later prompt
+    // until a cancelled prompt settles, so this active turn is unambiguous.
+    let permission_turn = Arc::new(Mutex::new(PermissionTurnState::default()));
+    let permission_turn_seen = permission_turn.clone();
+    let received_updates = updates_tx.clone();
     let result = Client
         .builder()
         .name("maestro")
@@ -417,22 +800,37 @@ async fn run_connection<T>(
                     return Ok(());
                 }
                 // A dropped receiver only means nobody wants updates any more.
-                let _ = updates_tx.send(notification);
+                let _ = received_updates.send(notification);
                 Ok(())
             },
             agent_client_protocol::on_receive_notification!(),
         )
         .on_receive_request(
             async move |request: RequestPermissionRequest, responder, _cx| {
-                // Stub until #139: decline rather than grant something the
-                // operator never saw.
-                tracing::warn!(
-                    session = %request.session_id,
-                    "session/request_permission declined: not implemented yet (#139)"
-                );
-                responder.respond(RequestPermissionResponse::new(
-                    RequestPermissionOutcome::Cancelled,
-                ))
+                let turn = permission_turn_seen
+                    .lock()
+                    .expect("permission turn state")
+                    .callback_turn();
+                let Some(turn) = turn else {
+                    return responder.respond(RequestPermissionResponse::new(
+                        RequestPermissionOutcome::Cancelled,
+                    ));
+                };
+                let (response, received) = oneshot::channel();
+                if permission_requests
+                    .send(PermissionRequest {
+                        turn,
+                        request,
+                        response,
+                    })
+                    .is_err()
+                {
+                    return responder.respond(RequestPermissionResponse::new(
+                        RequestPermissionOutcome::Cancelled,
+                    ));
+                }
+                let outcome = received.await.unwrap_or(RequestPermissionOutcome::Cancelled);
+                responder.respond(RequestPermissionResponse::new(outcome))
             },
             agent_client_protocol::on_receive_request!(),
         )
@@ -447,11 +845,13 @@ async fn run_connection<T>(
                     return Ok(());
                 }
             };
-            let session_id = match load_session {
+            let (session_id, modes, initial_options, models) = match config.load_session {
                 Some(existing) => {
                     if !initialized.agent_capabilities.load_session {
                         let _ = ready_tx.send(Err(ReadyError::Handshake(format!(
-                            "{ADAPTER_BIN} does not advertise loadSession; cannot resume session {existing}"
+                            "{} ACP adapter ({}) does not advertise loadSession; cannot resume session {existing}",
+                            config.adapter,
+                            config.adapter.binary()
                         ))));
                         return Ok(());
                     }
@@ -459,7 +859,11 @@ async fn run_connection<T>(
                     let (loaded_tx, loaded_rx) = oneshot::channel();
                     let replaying_done = replaying.clone();
                     if let Err(e) = cx
-                        .send_request(LoadSessionRequest::new(existing.clone(), cwd))
+                        .send_request(ExtendedLoadSessionRequest {
+                            session_id: SessionId::new(existing.as_str()),
+                            cwd: config.cwd,
+                            mcp_servers: vec![],
+                        })
                         .on_receiving_result(move |result| {
                             replaying_done.store(false, Ordering::SeqCst);
                             async move {
@@ -471,8 +875,8 @@ async fn run_connection<T>(
                         let _ = ready_tx.send(Err(ready_error(e)));
                         return Ok(());
                     }
-                    match loaded_rx.await {
-                        Ok(Ok(_)) => {}
+                    let loaded = match loaded_rx.await {
+                        Ok(Ok(loaded)) => loaded,
                         Ok(Err(e)) => {
                             let _ = ready_tx.send(Err(ready_error(e)));
                             return Ok(());
@@ -483,31 +887,174 @@ async fn run_connection<T>(
                             )));
                             return Ok(());
                         }
-                    }
-                    existing
+                    };
+                    (existing, loaded.modes, loaded.config_options.unwrap_or_default(), loaded.models)
                 }
                 None => match cx
-                    .send_request(NewSessionRequest::new(cwd))
+                    .send_request(ExtendedNewSessionRequest {
+                        cwd: config.cwd,
+                        mcp_servers: vec![],
+                    })
                     .block_task()
                     .await
                 {
-                    Ok(created) => created.session_id.0.to_string(),
+                    Ok(created) => (
+                        created.session_id.0.to_string(),
+                        created.modes,
+                        created.config_options.unwrap_or_default(),
+                        created.models,
+                    ),
                     Err(e) => {
                         let _ = ready_tx.send(Err(ready_error(e)));
                         return Ok(());
                     }
                 },
             };
+            let config_options = Arc::new(Mutex::new(advertised_config_options(
+                initial_options,
+                modes.as_ref(),
+                models.as_ref(),
+            )));
+            if let Some(modes) = &modes {
+                let _ = updates_tx.send(SessionNotification::new(
+                    SessionId::new(session_id.as_str()),
+                    SessionUpdate::CurrentModeUpdate(CurrentModeUpdate::new(
+                        modes.current_mode_id.clone(),
+                    )),
+                ));
+            }
+            if !config_options.lock().expect("config options").is_empty() {
+                let _ = updates_tx.send(config_notification(
+                    &session_id,
+                    config_options.lock().expect("config options").clone(),
+                ));
+            }
             let _ = ready_tx.send(Ok(session_id.clone()));
 
             loop {
                 tokio::select! {
                     cmd = commands_rx.recv() => match cmd {
                         Some(Command::Cancel) => {
+                            permission_turn
+                                .lock()
+                                .expect("permission turn state")
+                                .cancel_active();
                             let _ = cx.send_notification(CancelNotification::new(
                                 SessionId::new(session_id.as_str()),
                             ));
                         }
+                        Some(Command::Prompt { text, turn, done }) => {
+                            permission_turn
+                                .lock()
+                                .expect("permission turn state")
+                                .begin(turn);
+                            let request = PromptRequest::new(
+                                SessionId::new(session_id.as_str()),
+                                vec![ContentBlock::from(text)],
+                            );
+                            let done = Arc::new(Mutex::new(Some(done)));
+                            let callback_done = done.clone();
+                            let callback_turn = permission_turn.clone();
+                            if let Err(error) = cx.send_request(request).on_receiving_result(move |result| {
+                                let callback_done = callback_done.clone();
+                                let callback_turn = callback_turn.clone();
+                                async move {
+                                    callback_turn
+                                        .lock()
+                                        .expect("permission turn state")
+                                        .finish(turn);
+                                    if let Some(done) = callback_done.lock().expect("prompt sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|e| e.to_string()));
+                                    }
+                                    Ok(())
+                                }
+                            }) {
+                                permission_turn
+                                    .lock()
+                                    .expect("permission turn state")
+                                    .finish(turn);
+                                if let Some(done) = done.lock().expect("prompt sender").take() {
+                                    let _ = done.send(Err(error.to_string()));
+                                }
+                            }
+                        }
+                        Some(Command::SetConfig { config_id, value, done }) => {
+                            let done = Arc::new(Mutex::new(Some(done)));
+                            let callback_done = done.clone();
+                            let callback_options = config_options.clone();
+                            let callback_updates = updates_tx.clone();
+                            let callback_session = session_id.clone();
+                            let callback_config_id = config_id.clone();
+                            let callback_value = value.clone();
+                            let sent = if config_id == LEGACY_MODEL_CONFIG_ID {
+                                let Some(model_id) = value.as_value_id() else {
+                                    let _ = done.lock().expect("config sender").take()
+                                        .map(|done| done.send(Err("model must be a string value".into())));
+                                    continue;
+                                };
+                                cx.send_request(LegacySetModelRequest {
+                                    session_id: SessionId::new(session_id.as_str()),
+                                    model_id: model_id.0.to_string(),
+                                }).on_receiving_result(move |result| async move {
+                                    if result.is_ok() {
+                                        let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
+                                        let _ = callback_updates.send(config_notification(&callback_session, options));
+                                    }
+                                    if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                    }
+                                    Ok(())
+                                })
+                            } else if config_id == LEGACY_MODE_CONFIG_ID {
+                                let Some(mode_id) = value.as_value_id() else {
+                                    let _ = done.lock().expect("config sender").take()
+                                        .map(|done| done.send(Err("mode must be a string value".into())));
+                                    continue;
+                                };
+                                cx.send_request(SetSessionModeRequest::new(
+                                    SessionId::new(session_id.as_str()),
+                                    mode_id.0.to_string(),
+                                )).on_receiving_result(move |result| async move {
+                                    if result.is_ok() {
+                                        let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
+                                        let _ = callback_updates.send(config_notification(&callback_session, options));
+                                        let _ = callback_updates.send(SessionNotification::new(
+                                            SessionId::new(callback_session.as_str()),
+                                            SessionUpdate::CurrentModeUpdate(CurrentModeUpdate::new(
+                                                callback_value.as_value_id().expect("checked mode value").0.clone(),
+                                            )),
+                                        ));
+                                    }
+                                    if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                    }
+                                    Ok(())
+                                })
+                            } else {
+                                cx.send_request(SetSessionConfigOptionRequest::new(
+                                    SessionId::new(session_id.as_str()),
+                                    config_id,
+                                    value,
+                                ))
+                                    .on_receiving_result(move |result| async move {
+                                        if let Ok(response) = &result {
+                                            let mut current = callback_options.lock().expect("config options");
+                                            current.retain(|option| option.id.0.as_ref().starts_with("__maestro_legacy_"));
+                                            current.extend(response.config_options.clone());
+                                            let _ = callback_updates.send(config_notification(&callback_session, current.clone()));
+                                        }
+                                        if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                            let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                        }
+                                        Ok(())
+                                    })
+                            };
+                            if let Err(error) = sent {
+                                if let Some(done) = done.lock().expect("config sender").take() {
+                                    let _ = done.send(Err(error.to_string()));
+                                }
+                            }
+                        }
                         Some(Command::Close) | None => break,
                     },
                     _ = cx.incoming_closed() => break,
@@ -525,10 +1072,11 @@ async fn drain_stderr(
     stderr: tokio::process::ChildStderr,
     pid: u32,
     tail: Arc<Mutex<VecDeque<u8>>>,
+    adapter: AcpAdapter,
 ) {
     let mut lines = tokio::io::BufReader::new(stderr).lines();
     while let Ok(Some(line)) = lines.next_line().await {
-        tracing::debug!(pid, "{ADAPTER_BIN}: {line}");
+        tracing::debug!(pid, provider = %adapter, "ACP adapter: {line}");
         let mut tail = tail.lock().expect("stderr tail");
         tail.extend(line.as_bytes());
         tail.push_back(b'\n');

crates/maestro-acp/tests/fake_acp_agent.py

@@ -17,15 +17,28 @@ Environment knobs, all optional:
                             signal SIGTERM
   FAKE_ACP_ECHO_ENV       name of one env var to log at start
   FAKE_ACP_INIT_FAIL=1    answer `initialize` with a JSON-RPC error
+  FAKE_ACP_DELAY_SESSION_NEW_MS=n  wait n milliseconds before answering
+                             `session/new`
+  FAKE_ACP_SESSION_NEW_GATE=path  wait for `path` to exist before answering
+                             `session/new`
   FAKE_ACP_EXIT_AFTER_NEW=1  exit 0 right after answering `session/new`
   FAKE_ACP_EXIT_ON_CANCEL=1  exit 0 on `session/cancel` (default: keep running
                              so the SIGTERM path is exercised)
+  FAKE_ACP_IGNORE_EOF=1      keep running after stdin closes, until signalled
   FAKE_ACP_EMIT_ON_CANCEL=1  emit a final notification before handling cancel
+  FAKE_ACP_CANCEL_SETTLES=1  complete the outstanding prompt on cancel
   FAKE_ACP_NO_LOAD=1      advertise `loadSession: false`
   FAKE_ACP_LOAD_REPLAY=n  on `session/load`, replay n `agent_message_chunk`
                             notifications ("replayed <i>") before answering,
                             the way a real agent streams history back
   FAKE_ACP_LOAD_FAIL=1    answer `session/load` with a JSON-RPC error
+  FAKE_ACP_DELAY_PROMPT_MS=n  wait before answering `session/prompt`
+  FAKE_ACP_PROMPT_FAIL=1  answer every `session/prompt` with a JSON-RPC error
+  FAKE_ACP_PROMPT_FAIL_ONCE=1  answer only the first `session/prompt` with a
+                             JSON-RPC error
+  FAKE_ACP_SETTINGS=1      advertise legacy model/mode and modern effort options
+  FAKE_ACP_PERMISSION_AFTER_CANCEL=1  defer the first prompt's permission
+                             callback until a later prompt
 
 Signals: SIGUSR1 emits one `agent_message_chunk` notification ("tick <n>",
 counting from 1) and logs `emit tick <n>`, so a test can make the agent
@@ -35,6 +48,7 @@ import json
 import os
 import signal
 import sys
+import time
 
 LOG = os.environ.get("FAKE_ACP_LOG")
 
@@ -61,6 +75,45 @@ signal.signal(signal.SIGTERM, on_sigterm)
 
 session_id = f"fake-{os.getpid()}"
 ticks = 0
+prompt_failures = 0
+pending_prompt_id = None
+pending_permission_id = None
+delayed_permission = False
+current_model = "opus"
+current_mode = "default"
+current_effort = "high"
+
+
+def settings_response(include_session=False):
+    result = {}
+    if include_session:
+        result["sessionId"] = session_id
+    if os.environ.get("FAKE_ACP_SETTINGS") == "1":
+        result.update({
+            "models": {
+                "currentModelId": current_model,
+                "availableModels": [
+                    {"modelId": "opus", "name": "Opus"},
+                    {"modelId": "sonnet", "name": "Sonnet"},
+                ],
+            },
+            "modes": {
+                "currentModeId": current_mode,
+                "availableModes": [
+                    {"id": "default", "name": "Default"},
+                    {"id": "plan", "name": "Plan"},
+                ],
+            },
+            "configOptions": [{
+                "id": "effort", "name": "Effort", "category": "thought_level",
+                "type": "select", "currentValue": current_effort,
+                "options": [
+                    {"value": "low", "name": "Low"},
+                    {"value": "high", "name": "High"},
+                ],
+            }],
+        })
+    return result
 
 
 def chunk(text):
@@ -93,6 +146,12 @@ for raw in sys.stdin:
     method = msg.get("method")
     if method is None:
         # A response to something we sent; nothing to do.
+        if msg.get("id") == pending_permission_id:
+            log("permission response " + json.dumps(msg.get("result"), sort_keys=True))
+            send({"jsonrpc": "2.0", "id": pending_prompt_id,
+                  "result": {"stopReason": "end_turn"}})
+            pending_prompt_id = None
+            pending_permission_id = None
         continue
     log(f"recv {method}")
     rid = msg.get("id")
@@ -112,7 +171,11 @@ for raw in sys.stdin:
             "authMethods": [],
         }})
     elif method == "session/new":
-        send({"jsonrpc": "2.0", "id": rid, "result": {"sessionId": session_id}})
+        gate = os.environ.get("FAKE_ACP_SESSION_NEW_GATE")
+        while gate and not os.path.exists(gate):
+            time.sleep(0.01)
+        time.sleep(int(os.environ.get("FAKE_ACP_DELAY_SESSION_NEW_MS", "0")) / 1000)
+        send({"jsonrpc": "2.0", "id": rid, "result": settings_response(True)})
         send(chunk("hello from fake"))
         if os.environ.get("FAKE_ACP_EXIT_AFTER_NEW") == "1":
             sys.exit(0)
@@ -125,13 +188,75 @@ for raw in sys.stdin:
             continue
         for i in range(int(os.environ.get("FAKE_ACP_LOAD_REPLAY", "0"))):
             send(chunk(f"replayed {i + 1}"))
-        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+        send({"jsonrpc": "2.0", "id": rid, "result": settings_response()})
         send(chunk("hello after load"))
+    elif method == "session/set_model":
+        current_model = params.get("modelId")
+        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+    elif method == "session/set_mode":
+        current_mode = params.get("modeId")
+        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+    elif method == "session/set_config_option":
+        current_effort = params.get("value")
+        send({"jsonrpc": "2.0", "id": rid, "result": {
+            "configOptions": settings_response()["configOptions"]}})
     elif method == "session/cancel":
         if os.environ.get("FAKE_ACP_EMIT_ON_CANCEL") == "1":
             send(chunk("final on cancel"))
+        if (os.environ.get("FAKE_ACP_CANCEL_SETTLES") == "1"
+                and pending_prompt_id is not None):
+            send({"jsonrpc": "2.0", "id": pending_prompt_id,
+                  "result": {"stopReason": "cancelled"}})
+            pending_prompt_id = None
+            pending_permission_id = None
         if os.environ.get("FAKE_ACP_EXIT_ON_CANCEL") == "1":
             sys.exit(0)
+    elif method == "session/prompt":
+        if os.environ.get("FAKE_ACP_PERMISSION_AFTER_CANCEL") == "1":
+            if pending_prompt_id is None:
+                pending_prompt_id = rid
+                delayed_permission = True
+                continue
+            if delayed_permission:
+                delayed_permission = False
+                pending_permission_id = "permission-1"
+                send({"jsonrpc": "2.0", "id": pending_permission_id,
+                      "method": "session/request_permission", "params": {
+                          "sessionId": session_id,
+                          "toolCall": {"toolCallId": "tool-1", "fields": {}},
+                          "options": [
+                              {"optionId": "once", "name": "Allow once", "kind": "allow_once"},
+                              {"optionId": "deny", "name": "Deny", "kind": "reject_once"}
+                          ]
+                      }})
+                continue
+        if os.environ.get("FAKE_ACP_REQUEST_PERMISSION") == "1":
+            pending_prompt_id = rid
+            pending_permission_id = "permission-1"
+            send({"jsonrpc": "2.0", "id": pending_permission_id,
+                  "method": "session/request_permission", "params": {
+                      "sessionId": session_id,
+                      "toolCall": {"toolCallId": "tool-1", "fields": {}},
+                      "options": [
+                          {"optionId": "once", "name": "Allow once", "kind": "allow_once"},
+                          {"optionId": "session", "name": "Allow session", "kind": "allow_always"},
+                          {"optionId": "deny", "name": "Deny", "kind": "reject_once"}
+                      ]
+                  }})
+            continue
+        time.sleep(int(os.environ.get("FAKE_ACP_DELAY_PROMPT_MS", "0")) / 1000)
+        fail_once = os.environ.get("FAKE_ACP_PROMPT_FAIL_ONCE") == "1"
+        if os.environ.get("FAKE_ACP_PROMPT_FAIL") == "1" or (fail_once and prompt_failures == 0):
+            prompt_failures += 1
+            send({"jsonrpc": "2.0", "id": rid,
+                  "error": {"code": -32000, "message": "fake prompt failure"}})
+        else:
+            send({"jsonrpc": "2.0", "id": rid,
+                  "result": {"stopReason": "end_turn"}})
     elif rid is not None:
         send({"jsonrpc": "2.0", "id": rid,
               "error": {"code": -32601, "message": f"method not found: {method}"}})
+
+if os.environ.get("FAKE_ACP_IGNORE_EOF") == "1":
+    while True:
+        signal.pause()

crates/maestro-acp/tests/spawn.rs

@@ -1,12 +1,12 @@
 //! `maestro-acp` against the fake adapter in `tests/fake_acp_agent.py`, plus
-//! one ignored test against the real `claude-code-acp`.
+//! ignored smoke tests against each maintained adapter.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
 
 use maestro_acp::schema::{ContentBlock, SessionUpdate};
-use maestro_acp::{AcpError, SpawnConfig, ADAPTER_BIN, INSTALL_COMMAND};
+use maestro_acp::{AcpAdapter, AcpError, SpawnConfig, ADAPTER_BIN, INSTALL_COMMAND};
 use tempfile::TempDir;
 
 fn fake_agent() -> PathBuf {
@@ -25,6 +25,7 @@ impl Fake {
         let bin = dir.path().join("bin");
         std::fs::create_dir_all(&bin).unwrap();
         std::fs::copy(fake_agent(), bin.join(ADAPTER_BIN)).unwrap();
+        std::fs::copy(fake_agent(), bin.join(AcpAdapter::Codex.binary())).unwrap();
         Self { dir }
     }
 
@@ -69,6 +70,24 @@ impl Fake {
         }
         panic!("log never contained {needle:?}:\n{}", self.log());
     }
+
+    fn pid(&self) -> u32 {
+        self.log()
+            .lines()
+            .find_map(|line| line.strip_prefix("start pid="))
+            .and_then(|rest| rest.split(' ').next())
+            .and_then(|pid| pid.parse().ok())
+            .expect("pid in log")
+    }
+
+    async fn wait_for_exit(&self) {
+        let pid = self.pid();
+        let deadline = Instant::now() + Duration::from_secs(5);
+        while pid_alive(pid) && Instant::now() < deadline {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        assert!(!pid_alive(pid), "child {pid} still alive");
+    }
 }
 
 fn pid_alive(pid: u32) -> bool {
@@ -128,12 +147,38 @@ async fn missing_adapter_names_the_install_command() {
     let err = maestro_acp::spawn(SpawnConfig::new(cwd.path(), env))
         .await
         .expect_err("no adapter on PATH");
-    assert!(matches!(err, AcpError::AdapterMissing));
+    assert!(matches!(
+        err,
+        AcpError::AdapterMissing {
+            adapter: AcpAdapter::ClaudeCode
+        }
+    ));
     let msg = err.to_string();
     assert!(msg.contains(ADAPTER_BIN), "{msg}");
     assert!(msg.contains(INSTALL_COMMAND), "{msg}");
 }
 
+#[test]
+fn codex_adapter_has_its_own_binary_and_install_guidance() {
+    assert_eq!(AcpAdapter::Codex.binary(), "codex-acp");
+    assert!(AcpAdapter::Codex
+        .install_command()
+        .contains("@agentclientprotocol/codex-acp"));
+}
+
+#[tokio::test]
+async fn spawn_selects_the_codex_adapter() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = maestro_acp::spawn(fake.config(cwd.path()).adapter(AcpAdapter::Codex))
+        .await
+        .expect("spawn Codex adapter");
+    assert!(fake.log().contains("recv session/new"));
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
 #[tokio::test]
 async fn session_updates_reach_the_taken_receiver() {
     let fake = Fake::new();
@@ -162,11 +207,68 @@ async fn session_updates_reach_the_taken_receiver() {
         .await;
 }
 
+#[tokio::test]
+async fn advertised_settings_are_normalized_and_mutable() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config.env.insert("FAKE_ACP_SETTINGS".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+    let mut updates = session.take_updates().expect("updates");
+
+    let initial = loop {
+        let update = tokio::time::timeout(Duration::from_secs(5), updates.recv())
+            .await
+            .expect("settings update")
+            .expect("channel open");
+        if let SessionUpdate::ConfigOptionUpdate(options) = update.update {
+            break options.config_options;
+        }
+    };
+    assert_eq!(initial.len(), 3);
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "effort"));
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "__maestro_legacy_model"));
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "__maestro_legacy_mode"));
+    let model = initial
+        .iter()
+        .find(|option| option.id.0.as_ref() == "__maestro_legacy_model")
+        .expect("legacy model option");
+    let model = serde_json::to_value(model).unwrap();
+    assert_eq!(model["options"][0]["name"], "Opus");
+    assert!(model["options"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .any(|option| option["value"] == "fable"));
+
+    let changed = session
+        .set_config(
+            "__maestro_legacy_model".into(),
+            maestro_acp::schema::SessionConfigOptionValue::value_id("sonnet"),
+        )
+        .expect("queue model change");
+    changed
+        .await
+        .expect("response delivered")
+        .expect("model changed");
+    fake.wait_for_log("recv session/set_model").await;
+
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
 #[tokio::test]
 async fn terminate_sends_cancel_then_sigterm() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let session = maestro_acp::spawn(fake.config(cwd.path()))
+    let session = maestro_acp::spawn(fake.config(cwd.path()).adapter(AcpAdapter::Codex))
         .await
         .expect("spawn");
     let pid = session.pid();
@@ -207,7 +309,7 @@ async fn terminate_is_satisfied_by_an_exit_on_cancel() {
 async fn handshake_error_fails_the_spawn_and_reaps_the_child() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path());
+    let mut config = fake.config(cwd.path()).adapter(AcpAdapter::Codex);
     config.env.insert("FAKE_ACP_INIT_FAIL".into(), "1".into());
 
     let err = maestro_acp::spawn(config).await.expect_err("init fails");
@@ -266,7 +368,7 @@ async fn child_exit_before_handshake_reports_exited_early() {
 
     let err = maestro_acp::spawn(config).await.expect_err("child died");
     match &err {
-        AcpError::ExitedEarly { status, stderr } => {
+        AcpError::ExitedEarly { status, stderr, .. } => {
             assert!(status.contains('3'), "{status}");
             assert!(stderr.contains("not logged in"), "{stderr}");
         }
@@ -274,6 +376,20 @@ async fn child_exit_before_handshake_reports_exited_early() {
     }
 }
 
+#[tokio::test]
+async fn drop_terminates_and_reaps_the_child() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config.env.insert("FAKE_ACP_IGNORE_EOF".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+
+    drop(session);
+
+    fake.wait_for_log("signal SIGTERM").await;
+    fake.wait_for_exit().await;
+}
+
 fn chunk_text(n: &maestro_acp::schema::SessionNotification) -> String {
     match &n.update {
         SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
@@ -288,7 +404,10 @@ fn chunk_text(n: &maestro_acp::schema::SessionNotification) -> String {
 async fn load_session_resumes_the_stored_id_and_drops_the_replay() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_LOAD_REPLAY".into(), "3".into());
 
     let session = maestro_acp::spawn(config).await.expect("spawn");
@@ -321,7 +440,10 @@ async fn load_session_resumes_the_stored_id_and_drops_the_replay() {
 async fn load_session_requires_the_load_capability() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_NO_LOAD".into(), "1".into());
 
     let err = maestro_acp::spawn(config)
@@ -336,7 +458,10 @@ async fn load_session_requires_the_load_capability() {
 async fn load_session_error_fails_the_spawn() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_LOAD_FAIL".into(), "1".into());
 
     let err = maestro_acp::spawn(config).await.expect_err("load fails");
@@ -360,3 +485,21 @@ async fn real_adapter_handshake() {
         .await;
     assert!(session.has_exited());
 }
+
+/// End to end against the maintained Codex adapter. It needs a locally
+/// authenticated Codex CLI, so CI runs it only when explicitly requested.
+#[tokio::test]
+#[ignore]
+async fn real_codex_adapter_handshake() {
+    let cwd = TempDir::new().unwrap();
+    let session =
+        maestro_acp::spawn(SpawnConfig::new(cwd.path(), HashMap::new()).adapter(AcpAdapter::Codex))
+            .await
+            .expect("real codex-acp handshake");
+    assert!(!session.session_id().is_empty());
+    assert!(pid_alive(session.pid()));
+    session
+        .terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+        .await;
+    assert!(session.has_exited());
+}

crates/maestro-cli/src/attach.rs

@@ -19,6 +19,12 @@ use tokio_tungstenite::tungstenite::Message;
 pub enum AttachError {
     #[error("ws: {0}")]
     WebSocket(#[from] tokio_tungstenite::tungstenite::Error),
+    #[error("daemon returned {status} ({code}): {message}")]
+    Rejected {
+        status: String,
+        code: String,
+        message: String,
+    },
     #[error("io: {0}")]
     Io(#[from] io::Error),
     #[error("termios: {0}")]
@@ -32,6 +38,21 @@ pub enum AttachError {
 }
 
 impl AttachError {
+    fn from_websocket(error: tokio_tungstenite::tungstenite::Error) -> Self {
+        if let tokio_tungstenite::tungstenite::Error::Http(response) = &error {
+            if let Some(body) = response.body().as_deref() {
+                if let Ok(error_body) = serde_json::from_slice::<maestro_protocol::ApiError>(body) {
+                    return Self::Rejected {
+                        status: response.status().to_string(),
+                        code: error_body.error.code,
+                        message: error_body.error.message,
+                    };
+                }
+            }
+        }
+        Self::WebSocket(error)
+    }
+
     /// True when the failure was an inability to reach the WS endpoint at the
     /// transport level (connection refused), as opposed to an HTTP-level
     /// rejection from a daemon that did answer.
@@ -111,7 +132,9 @@ fn current_winsize() -> Option<(u16, u16)> {
 /// byte that exits cleanly without killing the session.
 #[allow(clippy::result_large_err)]
 pub async fn run_attach_url(url: &str, detach_byte: u8) -> Result<(), AttachError> {
-    let (ws, _resp) = tokio_tungstenite::connect_async(url).await?;
+    let (ws, _resp) = tokio_tungstenite::connect_async(url)
+        .await
+        .map_err(AttachError::from_websocket)?;
     let (mut sink, mut stream) = ws.split();
 
     let raw = RawTty::enable()?;
@@ -233,4 +256,25 @@ mod tests {
             Err(AttachError::InvalidDetachKey(_))
         ));
     }
+
+    #[test]
+    fn attach_surfaces_structured_handshake_errors() {
+        let body = serde_json::to_vec(&maestro_protocol::ApiError::new(
+            "not_terminal",
+            "session is not a terminal session",
+        ))
+        .unwrap();
+        let response = tokio_tungstenite::tungstenite::http::Response::builder()
+            .status(409)
+            .body(Some(body))
+            .unwrap();
+
+        let error =
+            AttachError::from_websocket(tokio_tungstenite::tungstenite::Error::Http(response));
+
+        assert_eq!(
+            error.to_string(),
+            "daemon returned 409 Conflict (not_terminal): session is not a terminal session"
+        );
+    }
 }

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),
@@ -92,6 +92,14 @@ pub struct SpawnArgs {
     /// there.
     #[arg(long)]
     pub existing_branch: bool,
+    /// Run a Claude Code or Codex session in a plain terminal instead of the
+    /// structured (ACP) view it otherwise gets by default.
+    #[arg(long, conflicts_with = "structured")]
+    pub terminal: bool,
+    /// Ask for the structured (ACP) view explicitly. Only Claude Code and
+    /// Codex commands have an adapter; the daemon refuses anything else.
+    #[arg(long)]
+    pub structured: bool,
     /// After spawning, attach immediately.
     #[arg(long, short = 'a')]
     pub attach: bool,

crates/maestro-cli/src/sessions.rs

@@ -3,10 +3,10 @@
 use std::collections::HashMap;
 use std::io::Write;
 
-use maestro_protocol::display::abbreviate_dir;
+use maestro_protocol::display::{abbreviate_dir, supports_structured_view};
 use maestro_protocol::{
     ActivityState, ClientError, CreateSessionRequest, DaemonClient, DaemonInfo, SendInputRequest,
-    Session, SessionStatus, WorktreeSpec,
+    Session, SessionStatus, SessionView, WorktreeSpec,
 };
 use serde_json::Value;
 
@@ -51,16 +51,33 @@ pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session
     };
 
     let body = CreateSessionRequest {
-        view: Default::default(),
+        view: spawn_view(&args),
         cwd: args.cwd.clone(),
         command: args.command.clone(),
         env,
         metadata,
         worktree,
+        auto_approve: false,
     };
     client.create_session(&body).await
 }
 
+/// The view a `maestro spawn` asks for: structured whenever the command
+/// resolves to an agent with an ACP adapter, since that is the richer session
+/// and the one both other clients now default to. `--terminal` opts out;
+/// `--structured` forces the request through even for a command this side
+/// does not recognise, leaving the refusal to the daemon.
+fn spawn_view(args: &SpawnArgs) -> SessionView {
+    if args.terminal {
+        return SessionView::Terminal;
+    }
+    if args.structured || supports_structured_view(&args.command) {
+        SessionView::Structured
+    } else {
+        SessionView::Terminal
+    }
+}
+
 /// `maestro kill`. A forced kill (#81) retains the guarded worktree instead
 /// of removing it; the outcome names what was kept so dispatch can say where
 /// the work went.
@@ -113,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,
@@ -138,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)
 }
 
@@ -179,8 +208,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
     }
     writeln!(
         out,
-        "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {}",
-        "ID", "STATUS", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
+        "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {}",
+        "ID", "STATUS", "VIEW", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
     )
     .ok();
     for s in sorted {
@@ -190,11 +219,16 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             SessionStatus::Running => "running",
             SessionStatus::Dead => "dead",
         };
+        let view = match s.view {
+            SessionView::Terminal => "terminal",
+            SessionView::Structured => "structured",
+        };
         let activity = match s.activity {
             ActivityState::Active => "active",
             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).
@@ -207,8 +241,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
         let blocked = blocked_label(s);
         writeln!(
             out,
-            "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {blocked}",
-            s.id, status, activity, dir, command
+            "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {blocked}",
+            s.id, status, view, activity, dir, command
         )
         .ok();
     }
@@ -230,11 +264,67 @@ mod tests {
     use std::path::PathBuf;
 
     use chrono::{TimeZone, Utc};
-    use maestro_protocol::{ActivityState, Session, SessionStatus};
+    use maestro_protocol::{ActivityState, Session, SessionStatus, SessionView};
     use uuid::Uuid;
 
     use super::DaemonInfo;
 
+    use clap::Parser;
+
+    use crate::cli::{Cli, Command};
+
+    fn spawn_args(extra: &[&str]) -> crate::cli::SpawnArgs {
+        let mut argv = vec!["maestro", "spawn", "--cwd", "/tmp", "--command"];
+        argv.extend_from_slice(extra);
+        let cli = Cli::try_parse_from(argv).expect("parses");
+        let Command::Spawn(args) = cli.command else {
+            panic!("expected spawn")
+        };
+        args
+    }
+
+    /// The CLI follows the two interactive clients: a command with an ACP
+    /// adapter spawns structured unless `--terminal` says otherwise, and
+    /// `--structured` still forces the request for a command this side does
+    /// not recognise.
+    #[test]
+    fn spawn_defaults_to_structured_for_supported_agents() {
+        use super::spawn_view;
+        assert_eq!(
+            spawn_view(&spawn_args(&["claude"])),
+            SessionView::Structured
+        );
+        assert_eq!(
+            spawn_view(&spawn_args(&["npx codex exec"])),
+            SessionView::Structured
+        );
+        assert_eq!(spawn_view(&spawn_args(&["bash"])), SessionView::Terminal);
+        assert_eq!(
+            spawn_view(&spawn_args(&["claude", "--terminal"])),
+            SessionView::Terminal
+        );
+        assert_eq!(
+            spawn_view(&spawn_args(&["opencode", "--structured"])),
+            SessionView::Structured
+        );
+    }
+
+    #[test]
+    fn spawn_refuses_both_view_flags_at_once() {
+        let err = Cli::try_parse_from([
+            "maestro",
+            "spawn",
+            "--cwd",
+            "/tmp",
+            "--command",
+            "claude",
+            "--structured",
+            "--terminal",
+        ])
+        .unwrap_err();
+        assert!(err.to_string().contains("--terminal"), "{err}");
+    }
+
     fn session(cwd: &str, command: &str, id: u128) -> Session {
         Session {
             view: Default::default(),
@@ -286,6 +376,22 @@ mod tests {
         assert!(s.contains("idle"), "{s}");
     }
 
+    #[test]
+    fn table_exposes_terminal_and_structured_views() {
+        let terminal = session("/tmp", "bash", 1);
+        let mut structured = session("/tmp", "claude", 2);
+        structured.view = SessionView::Structured;
+
+        let mut buf = Vec::new();
+        super::print_session_table(&mut buf, &[terminal, structured], &info(""));
+        let out = String::from_utf8(buf).unwrap();
+        let lines: Vec<&str> = out.lines().collect();
+        let header = lines.iter().position(|line| line.contains("VIEW")).unwrap();
+
+        assert!(lines[header + 1].contains("terminal"), "{out}");
+        assert!(lines[header + 2].contains("structured"), "{out}");
+    }
+
     #[test]
     fn live_cwd_overrides_spawn_dir_in_table() {
         let mut s = session("/home/naps/maestro", "bash", 1);

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;
 
@@ -28,6 +28,7 @@ async fn info_carries_version_and_presets() {
             id: "claude".into(),
             label: "Claude".into(),
             command: "claude".into(),
+            auto_approve: false,
         }],
         ..Default::default()
     });
@@ -97,6 +98,7 @@ async fn spawn_round_trips_through_the_daemon() {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -200,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-config/src/lib.rs

@@ -313,16 +313,19 @@ pub fn builtin_presets() -> Vec<SpawnPreset> {
             id: "claude".into(),
             label: "Claude".into(),
             command: "claude".into(),
+            auto_approve: false,
         },
         SpawnPreset {
             id: "opencode".into(),
             label: "opencode".into(),
             command: "opencode".into(),
+            auto_approve: false,
         },
         SpawnPreset {
             id: "zsh".into(),
             label: "Shell".into(),
             command: "zsh".into(),
+            auto_approve: false,
         },
     ]
 }
@@ -334,6 +337,7 @@ pub fn custom_preset() -> SpawnPreset {
         id: CUSTOM_PRESET_ID.into(),
         label: "Custom…".into(),
         command: String::new(),
+        auto_approve: false,
     }
 }
 
@@ -515,6 +519,7 @@ auto_install = false
                 id: "fish".into(),
                 label: "fish".into(),
                 command: "fish".into(),
+                auto_approve: false,
             }]),
             ..Default::default()
         };
@@ -551,6 +556,7 @@ auto_install = false
                 id: "  ".into(),
                 label: "x".into(),
                 command: "x".into(),
+                auto_approve: false,
             }]),
             ..Default::default()
         };
@@ -561,6 +567,7 @@ auto_install = false
                 id: "x".into(),
                 label: "x".into(),
                 command: "".into(),
+                auto_approve: false,
             }]),
             ..Default::default()
         };
@@ -578,11 +585,13 @@ auto_install = false
                     id: "a".into(),
                     label: "a".into(),
                     command: "a".into(),
+                    auto_approve: false,
                 },
                 SpawnPreset {
                     id: "a".into(),
                     label: "a2".into(),
                     command: "a2".into(),
+                    auto_approve: false,
                 },
             ]),
             ..Default::default()
@@ -597,6 +606,7 @@ auto_install = false
                 id: "custom".into(),
                 label: "Custom".into(),
                 command: "whatever".into(),
+                auto_approve: false,
             }]),
             ..Default::default()
         };

crates/maestro-daemon/src/activity.rs

@@ -66,6 +66,23 @@ pub fn decide(idle_for: Duration, awaiting_input: bool) -> ActivityState {
     }
 }
 
+/// Derive a structured session's sidebar state from its ACP projection.
+pub fn decide_structured(
+    turn_active: bool,
+    pending_approval: bool,
+    turn_failed: bool,
+) -> ActivityState {
+    if turn_failed {
+        ActivityState::Error
+    } else if pending_approval {
+        ActivityState::AwaitingInput
+    } else if turn_active {
+        ActivityState::Active
+    } else {
+        ActivityState::Idle
+    }
+}
+
 /// How long a session's pane must be continuously focused (a client's pane,
 /// not a sidebar highlight) before an `AwaitingInput` glow clears: the
 /// operator has looked, so the rail stops asking for attention.
@@ -136,6 +153,17 @@ mod tests {
         );
     }
 
+    #[test]
+    fn structured_activity_follows_lifecycle_with_approval_precedence() {
+        assert_eq!(decide_structured(false, false, false), ActivityState::Idle);
+        assert_eq!(decide_structured(true, false, false), ActivityState::Active);
+        assert_eq!(
+            decide_structured(true, true, false),
+            ActivityState::AwaitingInput
+        );
+        assert_eq!(decide_structured(false, false, true), ActivityState::Error);
+    }
+
     #[test]
     fn report_is_in_force_until_exactly_its_expiry() {
         let ttl = Duration::from_secs(300);

crates/maestro-daemon/src/cli.rs

@@ -122,21 +122,23 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     // shutdown, and both must reach the adapter children below (#134). The
     // unit's `KillMode=process` signals only the daemon, so nothing else
     // would end them.
-    let shutdown = async {
+    let shutdown_manager = manager.clone();
+    let shutdown = async move {
         let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
             .expect("install SIGTERM handler");
         tokio::select! {
             _ = tokio::signal::ctrl_c() => tracing::info!("ctrl-c received — shutting down"),
             _ = sigterm.recv() => tracing::info!("SIGTERM received — shutting down"),
         }
+        // Axum waits for upgraded WebSockets to drain. Structured children
+        // must be settled before that wait, while the signal path still owns
+        // the shutdown order (#179).
+        shutdown_manager.shutdown().await;
     };
 
     axum::serve(listener, router)
         .tcp_nodelay(true)
         .with_graceful_shutdown(shutdown)
         .await?;
-    // tmux sessions outlive the daemon by design; structured sessions'
-    // adapter children do not (#134).
-    manager.shutdown().await;
     Ok(())
 }

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

@@ -21,6 +21,7 @@ pub mod hooks;
 pub mod local_api;
 pub mod panes;
 pub mod proc;
+pub mod projection;
 pub mod projects;
 pub mod pty;
 pub mod release;

crates/maestro-daemon/src/local_api.rs

@@ -12,7 +12,8 @@
 
 use std::sync::Arc;
 
-use axum::extract::{Path, Query, State};
+use axum::body::Bytes;
+use axum::extract::{DefaultBodyLimit, Path, Query, State};
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
 use axum::routing::{any, delete, get, post};
@@ -21,12 +22,14 @@ use maestro_config::SpawnPreset;
 use maestro_protocol::{
     routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch,
     RenameSessionRequest, ReportActivityRequest, SendInputRequest, Session, SetFocusRequest,
+    StructuredApprovalDecision, StructuredConfigRequest, StructuredEvent, StructuredPromptRequest,
     PROTOCOL_VERSION,
 };
 use serde::Deserialize;
 use uuid::Uuid;
 
-use crate::session::SessionManager;
+use crate::session::{QueueAcpPrompt, SessionError, SessionManager, SetAcpConfig};
+use crate::sidecar::EventCursor;
 
 #[derive(Debug, Clone)]
 pub struct LocalApiState {
@@ -64,7 +67,20 @@ pub fn router(state: LocalApiState) -> Router {
         .route(routes::NAMES, get(names))
         .route(routes::INFO, get(daemon_info))
         .route(routes::EVENTS, any(events_ws))
-        .route(routes::patterns::ATTACH, any(attach_ws));
+        .route(routes::patterns::ATTACH, any(attach_ws))
+        .route(routes::patterns::STRUCTURED, any(structured_ws))
+        .route(routes::patterns::STRUCTURED_REPLAY, get(structured_replay))
+        .route(routes::patterns::STRUCTURED_PROMPT, post(structured_prompt))
+        .route(
+            routes::patterns::STRUCTURED_ATTACHMENT,
+            post(structured_attachment).layer(DefaultBodyLimit::max(20 * 1024 * 1024)),
+        )
+        .route(routes::patterns::STRUCTURED_CANCEL, post(structured_cancel))
+        .route(routes::patterns::STRUCTURED_CONFIG, post(structured_config))
+        .route(
+            routes::patterns::STRUCTURED_APPROVAL,
+            post(structured_approval),
+        );
     #[cfg(feature = "haiku-autoname")]
     {
         router = router.route(routes::patterns::SESSION_PROMPT, post(session_prompt));
@@ -164,12 +180,14 @@ 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
         // the daemon can do about it.
         "not_running" => StatusCode::CONFLICT,
+        "not_terminal" => StatusCode::CONFLICT,
+        "shutting_down" => StatusCode::SERVICE_UNAVAILABLE,
         _ => StatusCode::BAD_GATEWAY,
     }
 }
@@ -297,11 +315,10 @@ async fn rename_session(
     }
 }
 
-/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
-/// The report holds above the daemon's inference for a TTL, then inference
-/// resumes — an agent that dies mid-run cannot pin its session at `Error`
-/// forever. Unknown session is 404; an unknown state value is rejected by the
-/// JSON decoder (422) rather than coerced. Answers `204 No Content`.
+/// `POST /api/sessions/:id/activity` (#105): an agent reports a terminal
+/// session's state. Structured sessions acknowledge and ignore these reports
+/// because their activity comes from ACP. Unknown session is 404; an unknown
+/// state value is rejected by the JSON decoder (422). Answers `204 No Content`.
 async fn report_activity(
     State(s): State<LocalApiState>,
     Path(id): Path<Uuid>,
@@ -368,6 +385,199 @@ fn error_response(status: StatusCode, code: &str, message: &str) -> Response {
     (status, Json(ApiError::new(code, message))).into_response()
 }
 
+#[derive(Debug, Deserialize)]
+struct ReplayQuery {
+    since: Option<u64>,
+    before: Option<u64>,
+    limit: Option<usize>,
+}
+
+const MAX_STRUCTURED_REPLAY_LIMIT: usize = 500;
+
+async fn structured_replay(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Query(query): Query<ReplayQuery>,
+) -> Response {
+    if query.since.is_some() && query.before.is_some() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "invalid_cursor",
+            "use either since or before, not both",
+        );
+    }
+    let cursor = match query.before {
+        Some(before) => EventCursor::Before(Some(before)),
+        None => EventCursor::Since(query.since.unwrap_or(0)),
+    };
+    match s
+        .manager
+        .read_acp_projection_replay(
+            id,
+            cursor,
+            query
+                .limit
+                .unwrap_or(100)
+                .clamp(1, MAX_STRUCTURED_REPLAY_LIMIT),
+        )
+        .await
+    {
+        Ok(Some(events)) => Json(events).into_response(),
+        // A terminal session, or a structured session whose adapter is no
+        // longer live, cannot provide a coherent replay continuation.
+        Ok(None) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
+#[derive(Deserialize)]
+struct AttachmentQuery {
+    name: String,
+}
+
+async fn structured_attachment(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Query(query): Query<AttachmentQuery>,
+    bytes: Bytes,
+) -> Response {
+    let name = query.name;
+    if name.is_empty()
+        || name.len() > 180
+        || name == "."
+        || name == ".."
+        || name
+            .chars()
+            .any(|c| c.is_control() || c == '/' || c == '\\')
+    {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "invalid_filename",
+            "use a filename without directory separators, up to 180 bytes",
+        );
+    }
+    match s.manager.store_acp_attachment(id, &name, &bytes).await {
+        Ok(Some(path)) => Json(serde_json::json!({ "path": path })).into_response(),
+        Ok(None) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
+async fn structured_prompt(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<StructuredPromptRequest>,
+) -> Response {
+    match s.manager.queue_acp_prompt(id, body.prompt).await {
+        Ok(QueueAcpPrompt::Queued) | Ok(QueueAcpPrompt::Pending) => {
+            StatusCode::NO_CONTENT.into_response()
+        }
+        Ok(QueueAcpPrompt::InFlight) => error_response(
+            StatusCode::CONFLICT,
+            "turn_in_flight",
+            "the structured session already has an active turn",
+        ),
+        Ok(QueueAcpPrompt::Unavailable) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Ok(QueueAcpPrompt::Failed(message)) => {
+            error_response(StatusCode::BAD_GATEWAY, "acp_prompt_failed", &message)
+        }
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
+async fn structured_cancel(State(s): State<LocalApiState>, Path(id): Path<Uuid>) -> Response {
+    match s.manager.cancel_acp_turn(id).await {
+        Ok(true) => StatusCode::NO_CONTENT.into_response(),
+        Ok(false) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
+async fn structured_config(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<StructuredConfigRequest>,
+) -> Response {
+    match s
+        .manager
+        .set_acp_config(id, body.config_id, body.value)
+        .await
+    {
+        Ok(SetAcpConfig::Updated) => StatusCode::NO_CONTENT.into_response(),
+        Ok(SetAcpConfig::InvalidValue) => error_response(
+            StatusCode::BAD_REQUEST,
+            "invalid_config_value",
+            "configuration values must be strings or booleans",
+        ),
+        Ok(SetAcpConfig::Unavailable) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Ok(SetAcpConfig::Failed(message)) => {
+            error_response(StatusCode::BAD_GATEWAY, "acp_config_failed", &message)
+        }
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
+async fn structured_approval(
+    State(s): State<LocalApiState>,
+    Path((id, nonce)): Path<(Uuid, String)>,
+    Json(decision): Json<StructuredApprovalDecision>,
+) -> Response {
+    let decision = match decision {
+        StructuredApprovalDecision::AllowOnce => crate::session::ApprovalDecision::AllowOnce,
+        StructuredApprovalDecision::AllowForSession => {
+            crate::session::ApprovalDecision::AllowForSession
+        }
+        StructuredApprovalDecision::Deny => crate::session::ApprovalDecision::Deny,
+    };
+    match s.manager.resolve_acp_approval(id, &nonce, decision).await {
+        Ok(Some(())) => StatusCode::NO_CONTENT.into_response(),
+        Ok(None) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
 /// Convenience constructor — pulls the bits `LocalApiState` needs from
 /// `DaemonConfig` so callers don't have to assemble it by hand. The project
 /// scanner starts with its cache cold; wire
@@ -405,12 +615,23 @@ async fn attach_ws(
     State(s): State<LocalApiState>,
     ws: axum::extract::WebSocketUpgrade,
 ) -> Result<Response, Response> {
-    let Some((replay, rx)) = s.manager.subscribe_pty_with_replay(id).await else {
-        return Err(error_response(
-            StatusCode::NOT_FOUND,
-            "unknown_session",
-            "no such session on this daemon",
-        ));
+    let (replay, rx) = match s.manager.subscribe_pty_with_replay(id).await {
+        Ok(subscription) => subscription,
+        Err(SessionError::NotFound(_)) => {
+            return Err(error_response(
+                StatusCode::NOT_FOUND,
+                "unknown_session",
+                "no such session on this daemon",
+            ));
+        }
+        Err(error) => {
+            let info = error.to_error_info();
+            return Err(error_response(
+                session_error_status(&info.code),
+                &info.code,
+                &info.message,
+            ));
+        }
     };
     let manager = s.manager.clone();
     Ok(ws.on_upgrade(move |socket| async move {
@@ -418,6 +639,75 @@ async fn attach_ws(
     }))
 }
 
+#[allow(clippy::result_large_err)]
+async fn structured_ws(
+    Path(id): Path<Uuid>,
+    State(s): State<LocalApiState>,
+    ws: axum::extract::WebSocketUpgrade,
+) -> Result<Response, Response> {
+    let Some((snapshot, state, rx)) = s
+        .manager
+        .subscribe_acp_projection(id, EventCursor::Since(0))
+        .await
+        .map_err(|e| {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        })?
+    else {
+        return Err(error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ));
+    };
+    Ok(ws.on_upgrade(move |socket| async move {
+        let _ = pump_structured(socket, snapshot, state, rx).await;
+    }))
+}
+
+async fn pump_structured(
+    socket: axum::extract::ws::WebSocket,
+    snapshot: maestro_protocol::TranscriptSnapshot,
+    state: maestro_protocol::ReducedState,
+    mut rx: tokio::sync::broadcast::Receiver<crate::projection::ProjectionUpdate>,
+) -> Result<(), axum::Error> {
+    use axum::extract::ws::Message;
+    use futures_util::{SinkExt, StreamExt};
+
+    let (mut sink, mut stream) = socket.split();
+    for event in [
+        StructuredEvent::TranscriptSnapshot { snapshot },
+        StructuredEvent::ReducedState { state },
+    ] {
+        if sink
+            .send(Message::Text(
+                serde_json::to_string(&event).expect("structured event encode"),
+            ))
+            .await
+            .is_err()
+        {
+            return Ok(());
+        }
+    }
+    loop {
+        tokio::select! {
+            update = rx.recv() => match update {
+                Ok(update) => {
+                    let event = StructuredEvent::ProjectionUpdate { transcript: update.transcript, state: update.state };
+                    if sink.send(Message::Text(serde_json::to_string(&event).expect("structured event encode"))).await.is_err() { break; }
+                }
+                Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => break,
+                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
+            },
+            frame = stream.next() => match frame {
+                None | Some(Err(_)) | Some(Ok(Message::Close(_))) => break,
+                Some(Ok(_)) => {},
+            },
+        }
+    }
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // WS /api/events — live catalog deltas for browser/TUI subscribers (NAP-248)
 // ---------------------------------------------------------------------------

crates/maestro-daemon/src/sidecar.rs

@@ -7,8 +7,8 @@
 //! advertised but with empty metadata (handled by the caller, not here).
 //!
 //! A structured session (#135) also owns `<id>.events.jsonl` next to its
-//! sidecar: every `session/update` notification its adapter sent, one JSON
-//! object per line, appended before it is broadcast. The log is the source of
+//! sidecar: every `session/update` notification and daemon approval row is one
+//! JSON object, appended before it is broadcast. The log is the source of
 //! truth for the transcript; `seq` is the line's 1-based position, so a
 //! client that holds seq `n` asks for [`EventCursor::Since`]`(n)`. A line
 //! that does not parse — including the partial line a hard kill leaves at
@@ -21,7 +21,7 @@ use std::io::{BufRead, BufReader, Read, Seek, SeekFrom, Write};
 use std::path::{Path, PathBuf};
 
 use maestro_acp::schema::SessionNotification;
-use maestro_protocol::Session;
+use maestro_protocol::{Session, TranscriptRow};
 use uuid::Uuid;
 
 #[derive(Debug, thiserror::Error)]
@@ -56,6 +56,28 @@ impl SidecarStore {
         self.dir.join(format!("{id}.events.jsonl"))
     }
 
+    /// Durable evidence that graceful daemon shutdown ended this structured
+    /// session and the next daemon may resume it.
+    pub fn recovery_path_for(&self, id: Uuid) -> PathBuf {
+        self.dir.join(format!("{id}.recover"))
+    }
+
+    /// Mark `id` as eligible for one structured-session recovery attempt.
+    pub fn mark_for_recovery(&self, id: Uuid) -> Result<(), SidecarError> {
+        std::fs::create_dir_all(&self.dir)?;
+        std::fs::write(self.recovery_path_for(id), [])?;
+        Ok(())
+    }
+
+    /// Consume the graceful-shutdown recovery marker for `id`.
+    pub fn take_recovery_marker(&self, id: Uuid) -> Result<bool, SidecarError> {
+        match std::fs::remove_file(self.recovery_path_for(id)) {
+            Ok(()) => Ok(true),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+            Err(error) => Err(error.into()),
+        }
+    }
+
     /// Open the event log for `id` for appending, creating it (and the
     /// directory) when missing. One handle per live session: the caller
     /// keeps it for the session's lifetime rather than reopening per
@@ -90,7 +112,7 @@ impl SidecarStore {
         }
         file.seek(SeekFrom::End(0))?;
         Ok(EventLog {
-            file,
+            file: Box::new(file),
             last_seq: lines,
         })
     }
@@ -128,10 +150,10 @@ impl SidecarStore {
                 }
                 continue;
             }
-            let Ok(notification) = serde_json::from_slice::<SessionNotification>(&line) else {
+            let Ok(event) = PersistedEvent::decode(&line) else {
                 continue;
             };
-            out.push_back(LoggedEvent { seq, notification });
+            out.push_back(LoggedEvent { seq, event });
             match cursor {
                 EventCursor::Since(_) if out.len() >= limit => break,
                 EventCursor::Before(_) if out.len() > limit => {
@@ -164,10 +186,12 @@ impl SidecarStore {
         }
     }
 
-    /// Delete the sidecar and the event log for `id`. No-op for whichever
-    /// does not exist.
+    /// Delete the sidecar, event log, and recovery marker for `id`. No-op for
+    /// whichever does not exist.
     pub fn delete(&self, id: Uuid) -> Result<(), SidecarError> {
         remove_if_present(&self.events_path_for(id))?;
+        remove_if_present(&self.dir.join(format!("{id}.approvals.jsonl")))?;
+        remove_if_present(&self.recovery_path_for(id))?;
         remove_if_present(&self.path_for(id))
     }
 
@@ -228,18 +252,132 @@ pub enum EventCursor {
 pub struct LoggedEvent {
     /// 1-based line position in the log; the cursor for [`EventCursor`].
     pub seq: u64,
-    pub notification: SessionNotification,
+    pub event: PersistedEvent,
+}
+
+/// A single entry in the structured event history.
+///
+/// ACP notifications retain their original JSON representation, so existing
+/// event logs remain readable. Daemon-generated rows use an envelope so they
+/// can share the same cursor sequence without pretending to be ACP traffic.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(tag = "maestroEvent", rename_all = "snake_case")]
+pub enum PersistedEvent {
+    User {
+        row: TranscriptRow,
+    },
+    Approval {
+        row: TranscriptRow,
+    },
+    Turn {
+        row: TranscriptRow,
+    },
+    #[serde(skip)]
+    Notification(Box<SessionNotification>),
+}
+
+impl PersistedEvent {
+    fn decode(line: &[u8]) -> Result<Self, serde_json::Error> {
+        serde_json::from_slice::<SessionNotification>(line)
+            .map(|notification| Self::Notification(Box::new(notification)))
+            .or_else(|_| serde_json::from_slice(line))
+    }
+}
+
+impl From<SessionNotification> for PersistedEvent {
+    fn from(notification: SessionNotification) -> Self {
+        Self::Notification(Box::new(notification))
+    }
+}
+
+impl From<&SessionNotification> for PersistedEvent {
+    fn from(notification: &SessionNotification) -> Self {
+        Self::Notification(Box::new(notification.clone()))
+    }
+}
+
+impl From<&PersistedEvent> for PersistedEvent {
+    fn from(event: &PersistedEvent) -> Self {
+        event.clone()
+    }
+}
+
+/// What an [`EventLog`] appends onto: something seekable by length and
+/// truncatable back to one, so a failed append can be rolled off the end
+/// again. A real [`File`] in production; an in-memory fault double in tests
+/// (#184) — the same [`EventLog::append`] rollback logic runs over both, so
+/// the behavior under test is the production behavior, not a stand-in for
+/// it.
+pub(crate) trait LogSink: Write + Send {
+    fn len(&mut self) -> std::io::Result<u64>;
+    fn truncate(&mut self, len: u64) -> std::io::Result<()>;
+}
+
+impl LogSink for File {
+    fn len(&mut self) -> std::io::Result<u64> {
+        Ok(self.metadata()?.len())
+    }
+
+    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
+        self.set_len(len)
+    }
+}
+
+/// Outcome of a failed [`EventLog::append`].
+#[derive(Debug, thiserror::Error)]
+pub enum AppendError {
+    /// The write or flush failed, but the log was rolled back to exactly the
+    /// byte it was at before the call: `last_seq` and the file agree, and
+    /// this same [`EventLog`] is safe to keep appending to. The event itself
+    /// was never persisted or broadcast.
+    #[error("event append failed, rolled back cleanly: {0}")]
+    Failed(#[source] SidecarError),
+    /// The append failed *and* the rollback did not restore the log to its
+    /// prior length, so the file's line count and `last_seq` may now
+    /// disagree. The caller must not append to this [`EventLog`] again —
+    /// treat the session as dead rather than promise consistency it cannot
+    /// keep.
+    #[error("event append failed ({cause}) and rollback did not restore consistency ({rollback})")]
+    Fatal {
+        cause: SidecarError,
+        rollback: SidecarError,
+    },
+}
+
+impl From<SidecarError> for AppendError {
+    fn from(error: SidecarError) -> Self {
+        AppendError::Failed(error)
+    }
 }
 
 /// An open, append-only handle on one session's event log. Obtained from
 /// [`SidecarStore::open_events`]; held for the session's lifetime.
-#[derive(Debug)]
 pub struct EventLog {
-    file: File,
+    file: Box<dyn LogSink>,
     last_seq: u64,
 }
 
+impl std::fmt::Debug for EventLog {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EventLog")
+            .field("last_seq", &self.last_seq)
+            .finish_non_exhaustive()
+    }
+}
+
 impl EventLog {
+    /// Wrap an arbitrary sink as an [`EventLog`], for tests that need to
+    /// inject a deterministic append failure (#184) — a partial write, a
+    /// flush that fails after the bytes are already down, or a rollback that
+    /// cannot itself complete.
+    #[cfg(test)]
+    pub(crate) fn for_test(file: impl LogSink + 'static, last_seq: u64) -> Self {
+        Self {
+            file: Box::new(file),
+            last_seq,
+        }
+    }
+
     /// The seq of the last line, `0` for an empty log.
     pub fn last_seq(&self) -> u64 {
         self.last_seq
@@ -249,12 +387,262 @@ impl EventLog {
     /// handed to the kernel in a single write before this returns, so a
     /// caller that broadcasts afterwards never announces an event the log
     /// would not replay — short of the machine losing power.
-    pub fn append(&mut self, notification: &SessionNotification) -> Result<u64, SidecarError> {
-        let mut line = serde_json::to_vec(notification)?;
+    ///
+    /// A `write_all` that errors partway can leave an unterminated prefix on
+    /// disk; a `flush` that errors after a *complete* `write_all` leaves
+    /// ambiguity about whether that full, well-formed line should count —
+    /// counting it would silently shift every later seq by one, since
+    /// `last_seq` was never bumped for it. Both cases are rolled back to the
+    /// exact pre-append length before returning, so `last_seq` and the file
+    /// never disagree and the same [`EventLog`] can be appended to again
+    /// immediately. If the rollback itself fails, the log's consistency can
+    /// no longer be promised and [`AppendError::Fatal`] is returned instead.
+    pub fn append(&mut self, event: impl Into<PersistedEvent>) -> Result<u64, AppendError> {
+        let event = event.into();
+        let mut line = match &event {
+            PersistedEvent::Notification(notification) => serde_json::to_vec(notification)
+                .map_err(|e| AppendError::from(SidecarError::from(e)))?,
+            _ => {
+                serde_json::to_vec(&event).map_err(|e| AppendError::from(SidecarError::from(e)))?
+            }
+        };
         line.push(b'\n');
-        self.file.write_all(&line)?;
-        self.file.flush()?;
+
+        let pre_len = self
+            .file
+            .len()
+            .map_err(|e| AppendError::from(SidecarError::from(e)))?;
+
+        if let Err(cause) = self.file.write_all(&line) {
+            return Err(self.rollback_after(pre_len, cause));
+        }
+        if let Err(cause) = self.file.flush() {
+            return Err(self.rollback_after(pre_len, cause));
+        }
+
         self.last_seq += 1;
         Ok(self.last_seq)
     }
+
+    fn rollback_after(&mut self, pre_len: u64, cause: std::io::Error) -> AppendError {
+        match self.file.truncate(pre_len) {
+            Ok(()) => AppendError::Failed(SidecarError::Io(cause)),
+            Err(rollback) => AppendError::Fatal {
+                cause: SidecarError::Io(cause),
+                rollback: SidecarError::Io(rollback),
+            },
+        }
+    }
+}
+
+/// Bytes shared between a [`FaultyLogSink`] moved into an [`EventLog`] and
+/// the test that planted it, so the test can inspect what actually ended up
+/// on the "disk" after a fault without reaching into `EventLog`'s private
+/// `file` field.
+#[cfg(test)]
+#[derive(Clone, Default)]
+pub(crate) struct SharedBuf(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
+
+#[cfg(test)]
+impl SharedBuf {
+    pub(crate) fn snapshot(&self) -> Vec<u8> {
+        self.0.lock().unwrap().clone()
+    }
+}
+
+/// An in-memory [`LogSink`] double that injects one deterministic fault — a
+/// short write, a flush that fails after a full write, or a rollback that
+/// cannot itself complete — then behaves like a healthy sink from then on.
+/// Lets a test prove the *same* [`EventLog`] recovers, rather than one with a
+/// handle swapped in from a healthy disk, which production never does
+/// (#184).
+#[cfg(test)]
+#[derive(Default)]
+pub(crate) struct FaultyLogSink {
+    pub(crate) buf: SharedBuf,
+    /// Accept this many bytes on the next `write` call, then fail the
+    /// *following* call — a short write followed by an error, exactly what
+    /// `write_all` sees from a real fd that dies mid-line. `Write::write`
+    /// must not report an error on a call that made partial progress, so
+    /// the fault is delivered one call later, via `pending_write_error`.
+    pub(crate) fail_write_after: Option<usize>,
+    pub(crate) pending_write_error: bool,
+    pub(crate) fail_flush_once: bool,
+    pub(crate) fail_truncate: bool,
+}
+
+#[cfg(test)]
+impl Write for FaultyLogSink {
+    fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
+        if self.pending_write_error {
+            self.pending_write_error = false;
+            return Err(std::io::Error::other("fault: write failed mid-line"));
+        }
+        if let Some(allowed) = self.fail_write_after.take() {
+            let allowed = allowed.min(data.len());
+            if allowed == 0 {
+                // No progress was made, so it's fine to report the error
+                // from this same call.
+                return Err(std::io::Error::other("fault: write failed mid-line"));
+            }
+            self.buf
+                .0
+                .lock()
+                .unwrap()
+                .extend_from_slice(&data[..allowed]);
+            self.pending_write_error = true;
+            return Ok(allowed);
+        }
+        self.buf.0.lock().unwrap().extend_from_slice(data);
+        Ok(data.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        if self.fail_flush_once {
+            self.fail_flush_once = false;
+            return Err(std::io::Error::other(
+                "fault: flush failed after a full write",
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+impl LogSink for FaultyLogSink {
+    fn len(&mut self) -> std::io::Result<u64> {
+        Ok(self.buf.0.lock().unwrap().len() as u64)
+    }
+
+    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
+        if self.fail_truncate {
+            return Err(std::io::Error::other("fault: rollback truncate failed"));
+        }
+        self.buf.0.lock().unwrap().truncate(len as usize);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_event(id: &str) -> PersistedEvent {
+        PersistedEvent::Approval {
+            row: TranscriptRow {
+                id: id.to_owned(),
+                kind: maestro_protocol::TranscriptRowKind::Approval,
+                data: serde_json::json!({"tool": "bash"}),
+            },
+        }
+    }
+
+    /// Replays `bytes` as a real on-disk log via the production read path,
+    /// so "live and durable agree" is checked with the same code a
+    /// reconnecting client would hit, not a hand-rolled line splitter.
+    fn replay(bytes: &[u8]) -> Vec<LoggedEvent> {
+        let dir = tempfile::tempdir().unwrap();
+        let store = SidecarStore::new(dir.path());
+        let id = Uuid::new_v4();
+        std::fs::create_dir_all(store.dir()).unwrap();
+        std::fs::write(store.events_path_for(id), bytes).unwrap();
+        store.read_events(id, EventCursor::Since(0), 100).unwrap()
+    }
+
+    #[test]
+    fn append_rolls_back_a_partial_write_and_the_same_instance_recovers() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf: buf.clone(),
+            fail_write_after: Some(5),
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(
+            matches!(err, AppendError::Failed(_)),
+            "a repairable rollback must not be reported fatal"
+        );
+        assert_eq!(log.last_seq(), 0, "cursor must stay put on a failed append");
+        assert!(
+            buf.snapshot().is_empty(),
+            "the partial prefix a failed write_all leaves behind must be truncated away"
+        );
+
+        let seq = log
+            .append(sample_event("r1"))
+            .expect("the same instance must be able to append again after a clean rollback");
+        assert_eq!(seq, 1);
+        assert_eq!(log.last_seq(), 1);
+
+        let bytes = buf.snapshot();
+        assert_eq!(
+            bytes.iter().filter(|&&b| b == b'\n').count(),
+            1,
+            "exactly one well-formed line, not a partial prefix glued to the recovered append"
+        );
+
+        let replayed = replay(&bytes);
+        assert_eq!(replayed.len(), 1);
+        assert_eq!(replayed[0].seq, log.last_seq());
+        let PersistedEvent::Approval { row } = &replayed[0].event else {
+            panic!("approval event");
+        };
+        assert_eq!(row.id, "r1");
+    }
+
+    #[test]
+    fn append_rolls_back_when_flush_fails_after_a_full_write() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf: buf.clone(),
+            fail_flush_once: true,
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(matches!(err, AppendError::Failed(_)));
+        assert_eq!(log.last_seq(), 0);
+        assert!(
+            buf.snapshot().is_empty(),
+            "a full-but-unflushed line must not survive uncounted by last_seq — it would \
+             silently shift every later seq by one"
+        );
+
+        let seq = log
+            .append(sample_event("r1"))
+            .expect("the same instance must recover once flush stops failing");
+        assert_eq!(seq, 1);
+
+        let bytes = buf.snapshot();
+        let replayed = replay(&bytes);
+        assert_eq!(replayed.len(), 1);
+        assert_eq!(replayed[0].seq, log.last_seq());
+    }
+
+    #[test]
+    fn append_reports_fatal_when_rollback_cannot_restore_consistency() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf,
+            fail_write_after: Some(3),
+            fail_truncate: true,
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(
+            matches!(err, AppendError::Fatal { .. }),
+            "an unrepairable rollback must be surfaced as fatal, never silently treated as \
+             a clean recoverable failure"
+        );
+        assert_eq!(
+            log.last_seq(),
+            0,
+            "a fatal append must not advance the cursor either"
+        );
+    }
 }

crates/maestro-daemon/tests/activity_report.rs

@@ -48,6 +48,7 @@ async fn spawn_sleeping(manager: &SessionManager) -> Uuid {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()

crates/maestro-daemon/tests/attach.rs

@@ -81,6 +81,7 @@ async fn create_bash_session(h: &Harness) -> Uuid {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();

crates/maestro-daemon/tests/autoname.rs

@@ -56,6 +56,7 @@ async fn spawn(manager: &SessionManager, name: Option<&str>) -> Uuid {
             env: Default::default(),
             metadata,
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()

crates/maestro-daemon/tests/blocked_work_cost.rs

@@ -29,6 +29,7 @@ fn request(cwd: &std::path::Path, repo: &std::path::Path, branch: &str) -> Creat
             branch: branch.into(),
             create_branch: true,
         }),
+        auto_approve: false,
     }
 }
 

crates/maestro-daemon/tests/fixtures/codex-acp-session.jsonl

@@ -0,0 +1,16 @@
+{"sessionId":"codex-session","update":{"sessionUpdate":"user_message_chunk","messageId":"user-1","content":{"type":"text","text":"Inspect the repository"}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"agent_thought_chunk","messageId":"thought-1","content":{"type":"text","text":"I should inspect the files first."}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"command-1","kind":"execute","title":"rg TODO","status":"in_progress","rawInput":{"command":"rg TODO","cwd":"/workspace"}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call_update","toolCallId":"command-1","status":"completed","rawOutput":{"formatted_output":"src/lib.rs: TODO","exit_code":0}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"change-1","kind":"edit","title":"Editing files","status":"completed","content":[{"type":"diff","path":"src/lib.rs","oldText":"old","newText":"new"}]}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"mcp-1","kind":"execute","title":"mcp.github.search","status":"completed","rawInput":{"server":"github","tool":"search","arguments":{"query":"ACP"}},"rawOutput":{"result":"found"},"_meta":{"is_mcp_tool_call":true}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"web-1","kind":"search","title":"Search the web for ACP","status":"completed","rawInput":{"type":"webSearch","query":"Agent Client Protocol"}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"image-view-1","kind":"read","title":"View Image /workspace/diagram.png","status":"completed","content":[{"type":"content","content":{"type":"resource_link","name":"/workspace/diagram.png","uri":"/workspace/diagram.png"}}]}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"tool_call","toolCallId":"image-gen-1","title":"Image generation","status":"completed","content":[{"type":"content","content":{"type":"image","data":"aW1hZ2U=","mimeType":"image/png"}}],"rawOutput":{"path":"/workspace/generated.png"}}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"plan","entries":[{"content":"Implement compatibility fixture","priority":"medium","status":"in_progress"}]}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"usage_update","used":1200,"size":258400}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"current_mode_update","currentModeId":"agent"}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"config_option_update","configOptions":[{"id":"agent-mode","name":"Agent mode","category":"mode","type":"select","currentValue":"agent","options":[{"value":"read-only","name":"Read-only"},{"value":"agent","name":"Agent"}]},{"id":"model","name":"Model","category":"model","type":"select","currentValue":"gpt-5.3-codex","options":[{"value":"gpt-5.3-codex","name":"GPT-5.3-Codex"}]},{"id":"reasoning_effort","name":"Reasoning effort","category":"thought_level","type":"select","currentValue":"high","options":[{"value":"high","name":"High"}]},{"id":"fast-mode","name":"Fast mode","category":"model_config","type":"select","currentValue":"off","options":[{"value":"off","name":"Off"}]}]}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"status","description":"Show session status"}]}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"session_info_update","title":"Codex session"}}
+{"sessionId":"codex-session","update":{"sessionUpdate":"agent_message_chunk","messageId":"assistant-1","content":{"type":"text","text":"Done."}}}

crates/maestro-daemon/tests/local_api.rs

@@ -4,12 +4,17 @@ mod common;
 
 use std::collections::HashMap;
 use std::net::{Ipv4Addr, SocketAddr};
+use std::path::Path;
 use std::time::Duration;
 
 use common::DaemonFixture;
 use futures_util::{SinkExt, StreamExt};
 use maestro_daemon::local_api;
-use maestro_protocol::{ApiError, CreateSessionRequest, Session, WorktreeSpec};
+use maestro_protocol::{
+    ActivityState, ApiError, CreateSessionRequest, Session, SessionStatus, SessionView,
+    WorktreeSpec,
+};
+use tempfile::TempDir;
 use tokio::net::TcpListener;
 use tokio::sync::oneshot;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
@@ -86,6 +91,649 @@ fn ws_url(addr: SocketAddr, path: &str) -> String {
     format!("ws://{addr}{path}")
 }
 
+struct FakeAcp {
+    dir: TempDir,
+}
+
+impl FakeAcp {
+    fn new() -> Self {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = TempDir::new().unwrap();
+        let bin = dir.path().join("bin");
+        std::fs::create_dir_all(&bin).unwrap();
+        let adapter = bin.join("claude-code-acp");
+        std::fs::copy(
+            Path::new(env!("CARGO_MANIFEST_DIR")).join("../maestro-acp/tests/fake_acp_agent.py"),
+            &adapter,
+        )
+        .unwrap();
+        std::fs::set_permissions(&adapter, std::fs::Permissions::from_mode(0o755)).unwrap();
+        Self { dir }
+    }
+
+    fn env(&self) -> HashMap<String, String> {
+        HashMap::from([
+            (
+                "PATH".into(),
+                format!(
+                    "{}:{}",
+                    self.dir.path().join("bin").display(),
+                    std::env::var("PATH").unwrap()
+                ),
+            ),
+            (
+                "FAKE_ACP_LOG".into(),
+                self.dir.path().join("agent.log").display().to_string(),
+            ),
+        ])
+    }
+
+    fn pid(&self) -> u32 {
+        std::fs::read_to_string(self.dir.path().join("agent.log"))
+            .unwrap_or_default()
+            .lines()
+            .filter_map(|line| {
+                line.strip_prefix("start pid=")?
+                    .split(' ')
+                    .next()?
+                    .parse()
+                    .ok()
+            })
+            .next_back()
+            .expect("fake ACP started")
+    }
+
+    fn log(&self) -> String {
+        std::fs::read_to_string(self.dir.path().join("agent.log")).unwrap_or_default()
+    }
+}
+
+async fn structured_session(h: &Harness, fake: &FakeAcp) -> Uuid {
+    structured_session_with_env(h, fake.env()).await
+}
+
+async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>) -> Uuid {
+    let id = h
+        .manager
+        .create(CreateSessionRequest {
+            view: SessionView::Structured,
+            cwd: "/tmp".into(),
+            command: "claude".into(),
+            env,
+            metadata: HashMap::new(),
+            worktree: None,
+            auto_approve: false,
+        })
+        .await
+        .unwrap()
+        .id;
+    wait_for_session_activity(h, id, ActivityState::Idle).await;
+    id
+}
+
+async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if sessions
+                .iter()
+                .find(|session| session.id == id)
+                .is_some_and(|session| session.activity == expected)
+            {
+                return;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap_or_else(|_| panic!("session {id} did not reach {expected:?}"));
+}
+
+#[tokio::test]
+async fn structured_ws_sends_snapshot_then_live_projection() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+
+    let first = ws.next().await.unwrap().unwrap().into_text().unwrap();
+    let second = ws.next().await.unwrap().unwrap().into_text().unwrap();
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&first).unwrap()["type"],
+        "transcript_snapshot"
+    );
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&second).unwrap()["type"],
+        "reduced_state"
+    );
+
+    let response = reqwest::Client::new()
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "hello"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::NO_CONTENT);
+    let live = tokio::time::timeout(Duration::from_secs(1), ws.next())
+        .await
+        .expect("projection update arrives on the subscribed stream")
+        .unwrap()
+        .unwrap()
+        .into_text()
+        .unwrap();
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&live).unwrap()["type"],
+        "projection_update"
+    );
+}
+
+#[tokio::test]
+async fn structured_attachments_preserve_bytes_and_reject_paths() {
+    let h = spawn("attachments").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+    let endpoint = url(
+        h.addr,
+        &format!("/api/sessions/{id}/structured/attachments"),
+    );
+    let bytes = vec![0, 255, 10, 13];
+    let response = client
+        .post(&endpoint)
+        .query(&[("name", "sample.bin")])
+        .body(bytes.clone())
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 200);
+    let body: serde_json::Value = response.json().await.unwrap();
+    let path = body["path"].as_str().unwrap();
+    assert!(Path::new(path).is_absolute());
+    assert_eq!(std::fs::read(path).unwrap(), bytes);
+    for name in ["../escape", "a/b", "a\\b", "..", ""] {
+        let response = client
+            .post(&endpoint)
+            .query(&[("name", name)])
+            .body("text")
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(response.status(), 400, "{name}");
+    }
+    let response = client
+        .post(&endpoint)
+        .query(&[("name", "large.bin")])
+        .body(vec![0; 20 * 1024 * 1024 + 1])
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 413);
+    let response = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/attachments", Uuid::new_v4()),
+        ))
+        .query(&[("name", "file.txt")])
+        .body("text")
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 404);
+}
+
+#[tokio::test]
+async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "200".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let first = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "first"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(first.status(), reqwest::StatusCode::NO_CONTENT);
+    let second = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "second"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(second.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = second.json().await.unwrap();
+    assert_eq!(error.error.code, "turn_in_flight");
+
+    let cancel = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/cancel"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(cancel.status(), reqwest::StatusCode::NO_CONTENT);
+    let next = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "next"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(next.status(), reqwest::StatusCode::NO_CONTENT);
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if fake.log().matches("recv session/prompt").count() == 2 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("both prompt commands reach ACP");
+    let log = fake.log();
+    let first_prompt = log.find("recv session/prompt").unwrap();
+    let cancel = log.find("recv session/cancel").unwrap();
+    let second_prompt = log.rfind("recv session/prompt").unwrap();
+    assert!(first_prompt < cancel && cancel < second_prompt, "{log}");
+}
+
+#[tokio::test]
+async fn structured_approval_is_secret_single_use_and_race_safe() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_REQUEST_PERMISSION".into(), "1".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+    ws.next().await.unwrap().unwrap();
+    ws.next().await.unwrap().unwrap();
+    assert_eq!(
+        client
+            .post(url(
+                h.addr,
+                &format!("/api/sessions/{id}/structured/prompt")
+            ))
+            .json(&serde_json::json!({"prompt":"needs permission"}))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NO_CONTENT
+    );
+
+    let nonce = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let event: serde_json::Value =
+                serde_json::from_str(&ws.next().await.unwrap().unwrap().into_text().unwrap())
+                    .unwrap();
+            if let Some(nonce) = event["state"]["pending_approval"]["nonce"].as_str() {
+                assert_eq!(event["transcript"]["row"]["kind"], "approval");
+                assert!(event["transcript"]["row"]["data"].get("nonce").is_none());
+                break nonce.to_owned();
+            }
+        }
+    })
+    .await
+    .unwrap();
+    wait_for_session_activity(&h, id, ActivityState::AwaitingInput).await;
+    assert!(
+        !fake.log().contains(&nonce),
+        "daemon nonce leaked to ACP agent"
+    );
+
+    let path = format!("/api/sessions/{id}/structured/approvals/{nonce}");
+    let (a, b) = tokio::join!(
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("allow_once"))
+            .send(),
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("deny"))
+            .send(),
+    );
+    assert_eq!(a.unwrap().status(), reqwest::StatusCode::NO_CONTENT);
+    assert_eq!(b.unwrap().status(), reqwest::StatusCode::NO_CONTENT);
+    assert_eq!(
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("deny"))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NO_CONTENT
+    );
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if fake.log().contains("permission response") {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    let log = fake.log();
+    assert!(
+        log.contains("\"optionId\": \"once\"") || log.contains("\"optionId\": \"deny\""),
+        "{log}"
+    );
+    tokio::time::timeout(Duration::from_secs(1), async {
+        loop {
+            let event: serde_json::Value =
+                serde_json::from_str(&ws.next().await.unwrap().unwrap().into_text().unwrap())
+                    .unwrap();
+            if event["state"]["pending_approval"].is_null() {
+                break;
+            }
+        }
+    })
+    .await
+    .expect("resolved approval clears the reduced state");
+    wait_for_session_activity(&h, id, ActivityState::Idle).await;
+    assert_eq!(
+        client
+            .post(url(
+                h.addr,
+                &format!(
+                    "/api/sessions/{}/structured/approvals/{nonce}",
+                    Uuid::new_v4()
+                )
+            ))
+            .json(&serde_json::json!("deny"))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NOT_FOUND
+    );
+}
+
+#[tokio::test]
+async fn structured_prompt_failure_clears_the_turn() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_PROMPT_FAIL_ONCE".into(), "1".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let path = format!("/api/sessions/{id}/structured/prompt");
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+    ws.next().await.unwrap().unwrap();
+    ws.next().await.unwrap().unwrap();
+    let first = client
+        .post(url(h.addr, &path))
+        .json(&serde_json::json!({"prompt":"fails"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(first.status(), reqwest::StatusCode::NO_CONTENT);
+    let mut saw_active_turn = false;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while let Some(Ok(message)) = ws.next().await {
+            let event: serde_json::Value =
+                serde_json::from_str(&message.into_text().unwrap()).unwrap();
+            let turn = &event["state"]["turn"];
+            if turn["responding"] == true {
+                saw_active_turn = true;
+            }
+            if saw_active_turn && turn["responding"] == false && turn["thinking"] == false {
+                return;
+            }
+        }
+        panic!("structured websocket closed before the failed turn cleared");
+    })
+    .await
+    .expect("failed turn clears promptly");
+    wait_for_session_activity(&h, id, ActivityState::Error).await;
+    let second = client
+        .post(url(h.addr, &path))
+        .json(&serde_json::json!({"prompt":"available"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(second.status(), reqwest::StatusCode::NO_CONTENT);
+    assert!(second.bytes().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn structured_prompt_rejects_unknown_and_unavailable_sessions() {
+    let h = spawn("naps-laptop").await;
+    let client = reqwest::Client::new();
+    let prompt = |id| {
+        client
+            .post(url(
+                h.addr,
+                &format!("/api/sessions/{id}/structured/prompt"),
+            ))
+            .json(&serde_json::json!({"prompt": "hello"}))
+    };
+
+    let unknown = prompt(Uuid::new_v4()).send().await.unwrap();
+    assert_eq!(unknown.status(), reqwest::StatusCode::NOT_FOUND);
+    let error: ApiError = unknown.json().await.unwrap();
+    assert_eq!(error.error.code, "not_found");
+
+    let terminal = h
+        .manager
+        .create(CreateSessionRequest {
+            view: SessionView::Terminal,
+            cwd: "/tmp".into(),
+            command: "sh".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+            auto_approve: false,
+        })
+        .await
+        .unwrap();
+    let non_structured = prompt(terminal.id).send().await.unwrap();
+    assert_eq!(non_structured.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = non_structured.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+
+    let fake = FakeAcp::new();
+    let dead = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(dead).await, Some(SessionStatus::Dead));
+    let unavailable = prompt(dead).send().await.unwrap();
+    assert_eq!(unavailable.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = unavailable.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+}
+
+#[tokio::test]
+async fn structured_replay_honors_cursors_and_limit() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+
+    let events: Vec<serde_json::Value> = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let events: Vec<serde_json::Value> = client
+                .get(url(
+                    h.addr,
+                    &format!("/api/sessions/{id}/structured/replay?since=0&limit=1"),
+                ))
+                .send()
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if !events.is_empty() {
+                return events;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(events.len(), 1);
+    assert_eq!(events[0]["cursor"], 1);
+    assert!(events[0].get("notification").is_none());
+
+    let invalid = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/replay?since=0&before=2"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(invalid.status(), reqwest::StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn structured_replay_pages_projected_events_in_cursor_order() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+    unsafe { libc::kill(fake.pid() as libc::pid_t, libc::SIGUSR1) };
+    let events: Vec<serde_json::Value> = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let events: Vec<serde_json::Value> = client
+                .get(url(
+                    h.addr,
+                    &format!("/api/sessions/{id}/structured/replay?before=99&limit=2"),
+                ))
+                .send()
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if events.len() == 2 {
+                return events;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(
+        events
+            .iter()
+            .map(|event| event["cursor"].as_u64().unwrap())
+            .collect::<Vec<_>>(),
+        vec![1, 2]
+    );
+    let boundary: Vec<serde_json::Value> = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/replay?before=2&limit=10"),
+        ))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(boundary.len(), 1);
+    assert_eq!(boundary[0]["cursor"], 1);
+}
+
+#[tokio::test]
+async fn structured_replay_rejects_unknown_terminal_and_dead_sessions() {
+    let h = spawn("naps-laptop").await;
+    let client = reqwest::Client::new();
+    let unknown = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/replay", Uuid::new_v4()),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(unknown.status(), reqwest::StatusCode::NOT_FOUND);
+    let terminal = h
+        .manager
+        .create(CreateSessionRequest {
+            view: SessionView::Terminal,
+            cwd: "/tmp".into(),
+            command: "sh".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+            auto_approve: false,
+        })
+        .await
+        .unwrap();
+    let response = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/replay", terminal.id),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+
+    let fake = FakeAcp::new();
+    let dead = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(dead).await, Some(SessionStatus::Dead));
+    let response = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{dead}/structured/replay"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = response.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+}
+
+#[tokio::test]
+async fn structured_ws_rejects_a_dead_session() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(id).await, Some(SessionStatus::Dead));
+
+    let err = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .expect_err("dead structured session must not upgrade");
+    let message = err.to_string();
+    assert!(
+        message.contains("409") || message.to_lowercase().contains("conflict"),
+        "{message}"
+    );
+}
+
 #[tokio::test]
 async fn info_returns_daemon_identity() {
     let h = spawn("naps-laptop").await;
@@ -180,6 +828,7 @@ async fn list_sessions_starts_empty_and_reflects_creates() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     };
     let created: Session = reqwest::Client::new()
         .post(url(h.addr, "/api/sessions"))
@@ -354,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(
@@ -369,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]
@@ -397,6 +1057,7 @@ async fn patch_session_renames_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -440,6 +1101,7 @@ async fn post_focus_stamps_last_focused_at() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -474,6 +1136,7 @@ async fn delete_owned_session_kills_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -496,6 +1159,7 @@ async fn spawn_via_manager(h: &Harness) -> Uuid {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
@@ -610,6 +1274,7 @@ async fn delete_a_session_whose_worktree_holds_unsaved_work_returns_409_with_the
                 branch: "feat/guarded".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -663,6 +1328,7 @@ async fn delete_with_force_ends_the_session_and_keeps_the_worktree() {
                 branch: "feat/guarded".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -693,6 +1359,7 @@ async fn attach_ws_streams_pty_bytes() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -723,6 +1390,39 @@ async fn attach_ws_streams_pty_bytes() {
     assert!(saw_hello, "PTY did not echo through the attach WS");
 }
 
+#[tokio::test]
+async fn pty_routes_reject_structured_sessions_as_not_terminal() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+
+    let response = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/input")))
+        .json(&maestro_protocol::SendInputRequest {
+            text: "ignored".into(),
+            submit: false,
+        })
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = response.json().await.unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+
+    let error = connect_async(ws_url(h.addr, &format!("/api/attach/{id}")))
+        .await
+        .expect_err("structured session must not upgrade to a PTY socket");
+    let tokio_tungstenite::tungstenite::Error::Http(response) = error else {
+        panic!("expected an HTTP handshake rejection, got {error}");
+    };
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let body = response.body().as_deref().expect("ApiError response body");
+    let error: ApiError = serde_json::from_slice(body).unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+}
+
 #[tokio::test]
 async fn attach_ws_for_unknown_session_returns_404() {
     let h = spawn("naps-laptop").await;
@@ -762,6 +1462,7 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -789,6 +1490,79 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
     }
 }
 
+#[tokio::test]
+async fn events_ws_streams_structured_activity_without_hook_overrides() {
+    let h = spawn("konishi").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "500".into());
+    let (mut ws, _) = connect_async(ws_url(h.addr, "/api/events"))
+        .await
+        .expect("events ws");
+    assert!(matches!(
+        next_event(&mut ws).await,
+        maestro_protocol::CatalogEvent::Snapshot { .. }
+    ));
+
+    let id = structured_session_with_env(&h, env).await;
+    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();
+    let prompt = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "hello"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(prompt.status(), reqwest::StatusCode::NO_CONTENT);
+    let report = client
+        .post(url(h.addr, &format!("/api/sessions/{id}/activity")))
+        .json(&serde_json::json!({"state": "Error"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(report.status(), reqwest::StatusCode::NO_CONTENT);
+    wait_for_session_activity(&h, id, ActivityState::Active).await;
+
+    let mut activities = Vec::new();
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if let maestro_protocol::CatalogEvent::SessionUpdated { session } =
+                next_event(&mut ws).await
+            {
+                activities.push(session.activity);
+                if session.activity == ActivityState::Idle {
+                    return;
+                }
+            }
+        }
+    })
+    .await
+    .expect("structured turn returns to idle");
+    assert!(
+        activities.contains(&ActivityState::Active),
+        "{activities:?}"
+    );
+    assert!(
+        !activities.contains(&ActivityState::Error),
+        "{activities:?}"
+    );
+
+    h.manager.kill(id, false).await.unwrap();
+}
+
 /// Each subscriber has its own lag domain now that the publisher task is gone:
 /// two clients connected at different times both get their own Snapshot.
 #[tokio::test]
@@ -807,6 +1581,7 @@ async fn every_events_subscriber_gets_its_own_snapshot() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");

crates/maestro-daemon/tests/rename.rs

@@ -57,6 +57,7 @@ async fn spawn_named(manager: &SessionManager, name: Option<&str>) -> Uuid {
             env: Default::default(),
             metadata,
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()

crates/maestro-daemon/tests/session_decisions.rs

@@ -70,6 +70,7 @@ impl Fx {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         }
     }
 }

crates/maestro-daemon/tests/session_manager.rs

@@ -28,6 +28,7 @@ async fn create_then_kill_round_trip() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -70,6 +71,7 @@ async fn create_appends_to_spawn_history() {
             env: HashMap::new(),
             metadata: HashMap::from([("name".into(), serde_json::json!("neon-drifter"))]),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -100,6 +102,7 @@ async fn create_without_history_logs_nothing() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -123,6 +126,7 @@ async fn recover_adopts_existing_tmux_sessions() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -166,6 +170,7 @@ async fn create_captures_initial_output_in_replay_buffer() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -215,6 +220,7 @@ async fn attach_replay_is_the_current_screen_not_the_byte_tail() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -273,6 +279,7 @@ async fn attach_replay_carries_the_panes_mouse_modes() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -324,6 +331,7 @@ async fn recover_re_pipes_pane_so_output_reaches_subscribers() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -387,6 +395,7 @@ async fn pty_broadcast_delivers_bytes_to_subscribers() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -438,6 +447,7 @@ async fn liveness_watcher_marks_dead_sessions_and_keeps_them_until_dismissed() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -508,6 +518,7 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
                 branch: "feat/indicator".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -601,6 +612,7 @@ async fn kill_removes_worktree_even_when_spec_says_keep() {
                 branch: "feat/keep".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -639,6 +651,7 @@ async fn killing_refuses_a_worktree_with_unsaved_work_and_keeps_the_session() {
                 branch: "feat/guarded".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -703,6 +716,7 @@ async fn killing_refuses_until_the_branch_is_pushed() {
                 branch: "feat/pushed".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -753,6 +767,7 @@ async fn force_killing_a_guarded_worktree_leaves_it_on_disk() {
                 branch: "feat/forced".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -799,6 +814,7 @@ async fn force_on_a_clear_worktree_removes_it_as_usual() {
                 branch: "feat/clear".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -840,6 +856,7 @@ async fn killing_an_ignored_only_worktree_succeeds() {
                 branch: "feat/rusty".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -882,6 +899,7 @@ async fn natural_exit_of_a_guarded_worktree_leaves_it_on_disk() {
                 branch: "feat/exited".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -944,6 +962,7 @@ async fn natural_exit_of_a_pristine_worktree_removes_it() {
                 branch: "feat/clean".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1001,6 +1020,7 @@ async fn liveness_watcher_leaves_running_sessions_alone() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1040,6 +1060,7 @@ async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
                 branch: "feat/one".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create first");
@@ -1058,6 +1079,7 @@ async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
                 branch: "feat/two".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create second");
@@ -1093,6 +1115,7 @@ async fn spawned_sessions_export_maestro_session_id_and_url() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1132,6 +1155,7 @@ async fn a_freshly_created_session_has_never_been_focused() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1158,6 +1182,7 @@ async fn set_focused_true_stamps_last_focused_at() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1207,6 +1232,7 @@ async fn attaching_stamps_last_focused_at() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");

crates/maestro-daemon/tests/sidecar.rs

@@ -6,8 +6,8 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 
 use chrono::{DateTime, Utc};
-use maestro_daemon::sidecar::SidecarStore;
-use maestro_protocol::{Session, SessionStatus, SessionView};
+use maestro_daemon::sidecar::{PersistedEvent, SidecarStore};
+use maestro_protocol::{Session, SessionStatus, SessionView, TranscriptRow, TranscriptRowKind};
 use serde_json::Value;
 use tempfile::TempDir;
 use uuid::Uuid;
@@ -68,15 +68,30 @@ fn delete_removes_file_and_is_idempotent() {
     let s = sample(id);
 
     store.write(&s).unwrap();
+    store.mark_for_recovery(id).unwrap();
     assert!(store.path_for(id).exists());
+    assert!(store.recovery_path_for(id).exists());
 
     store.delete(id).unwrap();
     assert!(!store.path_for(id).exists());
+    assert!(!store.recovery_path_for(id).exists());
 
     // second delete is a no-op
     store.delete(id).unwrap();
 }
 
+#[test]
+fn recovery_marker_is_consumed_once() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+
+    assert!(!store.take_recovery_marker(id).unwrap());
+    store.mark_for_recovery(id).unwrap();
+    assert!(store.take_recovery_marker(id).unwrap());
+    assert!(!store.take_recovery_marker(id).unwrap());
+}
+
 #[test]
 fn load_all_recovers_every_sidecar_and_skips_garbage() {
     let dir = TempDir::new().unwrap();
@@ -171,6 +186,13 @@ fn text_of(n: &SessionNotification) -> &str {
     }
 }
 
+fn event_text(event: &maestro_daemon::sidecar::LoggedEvent) -> &str {
+    let maestro_daemon::sidecar::PersistedEvent::Notification(notification) = &event.event else {
+        panic!("expected ACP notification")
+    };
+    text_of(notification)
+}
+
 #[test]
 fn append_assigns_line_position_as_seq_and_reads_back() {
     let dir = TempDir::new().unwrap();
@@ -179,9 +201,9 @@ fn append_assigns_line_position_as_seq_and_reads_back() {
 
     let mut log = store.open_events(id).expect("open");
     assert_eq!(log.last_seq(), 0);
-    assert_eq!(log.append(&note("a")).unwrap(), 1);
-    assert_eq!(log.append(&note("b")).unwrap(), 2);
-    assert_eq!(log.append(&note("c")).unwrap(), 3);
+    assert_eq!(log.append(note("a")).unwrap(), 1);
+    assert_eq!(log.append(note("b")).unwrap(), 2);
+    assert_eq!(log.append(note("c")).unwrap(), 3);
     assert_eq!(log.last_seq(), 3);
 
     let path = store.events_path_for(id);
@@ -196,9 +218,7 @@ fn append_assigns_line_position_as_seq_and_reads_back() {
     let all = store.read_events(id, EventCursor::Since(0), 100).unwrap();
     assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 2, 3]);
     assert_eq!(
-        all.iter()
-            .map(|e| text_of(&e.notification))
-            .collect::<Vec<_>>(),
+        all.iter().map(event_text).collect::<Vec<_>>(),
         vec!["a", "b", "c"]
     );
 }
@@ -210,7 +230,7 @@ fn since_reads_forward_and_before_reads_backward_with_limit() {
     let id = Uuid::new_v4();
     let mut log = store.open_events(id).unwrap();
     for i in 1..=6 {
-        log.append(&note(&format!("n{i}"))).unwrap();
+        log.append(note(&format!("n{i}"))).unwrap();
     }
 
     // `since` is exclusive: what a client that already holds seq 2 needs.
@@ -263,7 +283,7 @@ fn malformed_lines_are_skipped_but_keep_their_seq() {
     let store = SidecarStore::new(dir.path());
     let id = Uuid::new_v4();
     let mut log = store.open_events(id).unwrap();
-    log.append(&note("first")).unwrap();
+    log.append(note("first")).unwrap();
     drop(log);
 
     // Garbage in the middle and a line that is JSON but not a notification.
@@ -274,11 +294,11 @@ fn malformed_lines_are_skipped_but_keep_their_seq() {
     std::fs::write(&path, raw).unwrap();
     let mut log = store.open_events(id).unwrap();
     assert_eq!(log.last_seq(), 3);
-    assert_eq!(log.append(&note("fourth")).unwrap(), 4);
+    assert_eq!(log.append(note("fourth")).unwrap(), 4);
 
     let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
     assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 4]);
-    assert_eq!(text_of(&all[1].notification), "fourth");
+    assert_eq!(event_text(&all[1]), "fourth");
 }
 
 #[test]
@@ -288,7 +308,7 @@ fn truncated_last_line_still_opens_and_the_next_append_starts_a_fresh_line() {
     let store = SidecarStore::new(dir.path());
     let id = Uuid::new_v4();
     let mut log = store.open_events(id).unwrap();
-    log.append(&note("whole")).unwrap();
+    log.append(note("whole")).unwrap();
     drop(log);
 
     let path = store.events_path_for(id);
@@ -304,10 +324,10 @@ fn truncated_last_line_still_opens_and_the_next_append_starts_a_fresh_line() {
     // glue onto it; the partial keeps a seq of its own.
     let mut log = store.open_events(id).unwrap();
     assert_eq!(log.last_seq(), 2);
-    assert_eq!(log.append(&note("after")).unwrap(), 3);
+    assert_eq!(log.append(note("after")).unwrap(), 3);
     let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
     assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 3]);
-    assert_eq!(text_of(&all[1].notification), "after");
+    assert_eq!(event_text(&all[1]), "after");
     let raw = std::fs::read_to_string(&path).unwrap();
     assert_eq!(raw.lines().count(), 3, "{raw}");
 }
@@ -319,8 +339,10 @@ fn delete_removes_the_event_log_and_load_all_ignores_it() {
     let id = Uuid::new_v4();
     store.write(&sample(id)).unwrap();
     let mut log = store.open_events(id).unwrap();
-    log.append(&note("x")).unwrap();
+    log.append(note("x")).unwrap();
     drop(log);
+    let legacy_approvals = dir.path().join(format!("{id}.approvals.jsonl"));
+    std::fs::write(&legacy_approvals, b"obsolete").unwrap();
     assert!(store.events_path_for(id).exists());
 
     let loaded = store.load_all().unwrap();
@@ -329,6 +351,47 @@ fn delete_removes_the_event_log_and_load_all_ignores_it() {
     store.delete(id).unwrap();
     assert!(!store.path_for(id).exists());
     assert!(!store.events_path_for(id).exists());
+    assert!(!legacy_approvals.exists());
     // Idempotent with the log already gone.
     store.delete(id).unwrap();
 }
+
+#[test]
+fn approval_rows_share_event_cursors_with_legacy_acp_lines() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let legacy = serde_json::to_vec(&note("before")).unwrap();
+    std::fs::create_dir_all(dir.path()).unwrap();
+    std::fs::write(store.events_path_for(id), [legacy, b"\n".to_vec()].concat()).unwrap();
+
+    let mut log = store.open_events(id).unwrap();
+    assert_eq!(
+        log.append(PersistedEvent::Approval {
+            row: TranscriptRow {
+                id: "approval:secret".into(),
+                kind: TranscriptRowKind::Approval,
+                data: serde_json::json!({"tool": "bash"}),
+            },
+        })
+        .unwrap(),
+        2
+    );
+    assert_eq!(log.append(note("after")).unwrap(), 3);
+
+    let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
+    assert_eq!(
+        all.iter().map(|event| event.seq).collect::<Vec<_>>(),
+        [1, 2, 3]
+    );
+    assert!(matches!(all[1].event, PersistedEvent::Approval { .. }));
+    assert_eq!(event_text(&all[0]), "before");
+    assert_eq!(event_text(&all[2]), "after");
+
+    let since = store.read_events(id, EventCursor::Since(1), 1).unwrap();
+    assert_eq!(since[0].seq, 2);
+    let before = store
+        .read_events(id, EventCursor::Before(Some(3)), 1)
+        .unwrap();
+    assert_eq!(before[0].seq, 2);
+}

crates/maestro-daemon/tests/worktree.rs

@@ -405,15 +405,17 @@ fn run_git(dir: &std::path::Path, args: &[&str]) {
     );
 }
 
-/// 49ab7e9: a new-branch add onto a name that already exists suffixes the
-/// branch (and so the directory) instead of failing, per docs/WORKTREES.md.
+/// `git worktree add -b` alone fails outright when the branch already exists,
+/// even with the target directory free — a random handle commonly collides
+/// with one an earlier, already-removed worktree left behind. `add_new`
+/// sidesteps it on the branch name itself instead of erroring (#77).
 #[test]
-fn add_new_suffixes_when_branch_already_exists() {
+fn add_new_suffixes_branch_name_on_branch_collision() {
     let repo_dir = TempDir::new().unwrap();
     let repo = repo_dir.path().to_path_buf();
     init_repo(&repo);
 
-    // pre-create the branch
+    // pre-create the branch, unused by any worktree.
     let status = Command::new("git")
         .arg("-C")
         .arg(&repo)
@@ -425,9 +427,17 @@ fn add_new_suffixes_when_branch_already_exists() {
     let wt_root = TempDir::new().unwrap();
     let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let path = mgr.add_new(&repo, "feat/dup").unwrap();
+    let path = mgr
+        .add_new(&repo, "feat/dup")
+        .expect("sidesteps the branch collision");
     assert!(path.ends_with("feat/dup-2"), "{}", path.display());
-    assert!(path.is_dir());
+    assert!(path.exists());
+
+    // The pre-existing branch is untouched; the new worktree checked out the
+    // suffixed one instead of erroring or adopting `feat/dup`.
+    let branches = worktree_branches(&repo);
+    assert!(branches.contains(&"feat/dup-2".to_string()), "{branches:?}");
+    assert!(!branches.contains(&"feat/dup".to_string()), "{branches:?}");
 }
 
 /// The project picker lists linked worktrees as pickable rows, so `base_repo`

crates/maestro-e2e/Cargo.toml

@@ -13,6 +13,7 @@ path = "src/lib.rs"
 [dependencies]
 chrono.workspace = true
 futures-util.workspace = true
+libc.workspace = true
 maestro-protocol = { workspace = true, features = ["client"] }
 maestro-testing.workspace = true
 serde.workspace = true

crates/maestro-e2e/src/daemon.rs

@@ -87,6 +87,14 @@ impl Daemon {
         }
     }
 
+    /// Send the daemon the same SIGTERM systemd uses, without waiting for its
+    /// graceful HTTP shutdown to finish.
+    pub fn send_sigterm(&self) {
+        let child = self.child.as_ref().expect("daemon is running");
+        let result = unsafe { libc::kill(child.id() as libc::pid_t, libc::SIGTERM) };
+        assert_eq!(result, 0, "send SIGTERM to daemon");
+    }
+
     /// Re-spawn the daemon on the same port + state. The previous tmux
     /// server (under `TMUX_TMPDIR`) is left running so `recover()` can adopt
     /// its sessions.

crates/maestro-e2e/tests/e2e.rs

@@ -15,7 +15,7 @@ use std::time::{Duration, Instant};
 use futures_util::{SinkExt, StreamExt};
 use maestro_e2e::util::wait_for_async;
 use maestro_e2e::{Daemon, TestClient};
-use maestro_protocol::{CreateSessionRequest, WorktreeSpec};
+use maestro_protocol::{CreateSessionRequest, SessionStatus, SessionView, WorktreeSpec};
 use tempfile::TempDir;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
@@ -33,9 +33,65 @@ fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     }
 }
 
+struct FakeAcp {
+    _dir: TempDir,
+    env: HashMap<String, String>,
+}
+
+fn fake_acp(log: &std::path::Path) -> FakeAcp {
+    let dir = tempfile::tempdir().expect("fake adapter dir");
+    let adapter = dir.path().join("claude-code-acp");
+    std::fs::copy(
+        concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../maestro-acp/tests/fake_acp_agent.py"
+        ),
+        &adapter,
+    )
+    .expect("copy fake adapter");
+    let mut permissions = std::fs::metadata(&adapter)
+        .expect("adapter metadata")
+        .permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        permissions.set_mode(0o755);
+    }
+    std::fs::set_permissions(&adapter, permissions).expect("make fake adapter executable");
+    let env = HashMap::from([
+        (
+            "PATH".into(),
+            format!(
+                "{}:{}",
+                dir.path().display(),
+                std::env::var("PATH").unwrap_or_default()
+            ),
+        ),
+        ("FAKE_ACP_LOG".into(), log.to_string_lossy().into_owned()),
+    ]);
+    FakeAcp { _dir: dir, env }
+}
+
+fn fake_acp_pid(log: &std::path::Path) -> Option<u32> {
+    std::fs::read_to_string(log).ok()?.lines().find_map(|line| {
+        line.strip_prefix("start pid=")?
+            .split(' ')
+            .next()?
+            .parse()
+            .ok()
+    })
+}
+
+fn pid_alive(pid: u32) -> bool {
+    std::fs::read_to_string(format!("/proc/{pid}/stat"))
+        .map(|stat| !stat.contains(") Z "))
+        .unwrap_or(false)
+}
+
 /// A worktree spec built through its wire shape. The daemon and clients ship
 /// together (#87 dropped `cleanup_on_kill` from the struct), so the JSON
 /// object carries only the fields the lifecycle actually honours.
@@ -56,6 +112,7 @@ fn worktree_req(base: &std::path::Path, branch: &str, create_branch: bool) -> Cr
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base, branch, create_branch)),
+        auto_approve: false,
     }
 }
 
@@ -151,6 +208,7 @@ async fn kill_removes_clean_worktree() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/e2e", true)),
+        auto_approve: false,
     };
 
     let s = client.spawn_session(&req).await.expect("spawn worktree");
@@ -205,6 +263,7 @@ async fn kill_refuses_worktree_with_uncommitted_changes() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/unsaved", true)),
+        auto_approve: false,
     };
 
     let s = client.spawn_session(&req).await.expect("spawn worktree");
@@ -264,6 +323,7 @@ async fn spawn_on_existing_branch_checks_it_out() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/existing", false)),
+        auto_approve: false,
     };
 
     let s = client
@@ -328,13 +388,11 @@ async fn spawn_new_branch_creates_worktree_and_runs_in_it() {
     client.kill_session(s.id).await.expect("kill");
 }
 
-/// #66: a second spawn onto an *existing* branch that already has a worktree
-/// is rejected with a structured worktree error; the first worktree stays
-/// intact. (A second `create_branch: true` spawn is a different case: 49ab7e9
-/// suffixes the new branch name instead, see
-/// `colliding_branch_name_gets_suffixed_too`.)
+/// #66/#77: a second spawn onto the same branch used to be rejected outright;
+/// since the branch-collision suffixing landed, it succeeds instead — the
+/// second worktree lands on `<branch>-2` and the first stays untouched.
 #[tokio::test(flavor = "multi_thread")]
-async fn second_spawn_on_same_branch_is_rejected() {
+async fn second_spawn_on_same_branch_gets_suffixed() {
     let (_daemon, client) = bring_up().await;
 
     let base = TempDir::new().unwrap();
@@ -344,28 +402,33 @@ async fn second_spawn_on_same_branch_is_rejected() {
         .spawn_session(&worktree_req(base.path(), "feature/dup", true))
         .await
         .expect("first spawn");
-    let dup = client
-        .spawn_session(&worktree_req(base.path(), "feature/dup", false))
-        .await;
-    match dup {
-        Err(maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. })) => {
-            assert_eq!(
-                info.code, "worktree_failed",
-                "expected worktree error: {info:?}"
-            );
-        }
-        other => panic!("expected rejection for duplicate branch, got {other:?}"),
-    }
+    let second = client
+        .spawn_session(&worktree_req(base.path(), "feature/dup", true))
+        .await
+        .expect("second spawn suffixes instead of rejecting");
 
-    // Exactly one registration, one directory, still usable.
-    // Count branch records only: the worktree path now contains the branch
-    // name too (`worktrees/feature/dup`), so a substring match over every line
-    // would count the same tree twice.
-    let holders = git_worktree_list(base.path())
-        .iter()
-        .filter(|w| w.as_str() == "branch refs/heads/feature/dup")
-        .count();
-    assert_eq!(holders, 1, "duplicate spawn must not register another tree");
+    let suffixed = base.path().join("worktrees").join("feature").join("dup-2");
+    assert_eq!(
+        second.cwd, suffixed,
+        "second worktree must land on the suffixed path"
+    );
+    assert!(suffixed.is_dir());
+
+    // Both registrations exist: the original branch, untouched, and the
+    // suffixed one the second spawn created.
+    let registrations = git_worktree_list(base.path());
+    assert!(
+        registrations
+            .iter()
+            .any(|l| l.as_str() == "branch refs/heads/feature/dup"),
+        "original branch must stay registered: {registrations:?}"
+    );
+    assert!(
+        registrations
+            .iter()
+            .any(|l| l.as_str() == "branch refs/heads/feature/dup-2"),
+        "suffixed branch must be registered too: {registrations:?}"
+    );
     assert!(
         base.path()
             .join("worktrees")
@@ -376,7 +439,8 @@ async fn second_spawn_on_same_branch_is_rejected() {
     );
 
     let _origin = throwaway_origin(base.path());
-    client.kill_session(first.id).await.expect("kill");
+    client.kill_session(first.id).await.expect("kill first");
+    client.kill_session(second.id).await.expect("kill second");
 }
 
 /// #66/#56: when the client picks a *linked worktree* as base_repo, placement
@@ -768,6 +832,7 @@ async fn natural_exit_settles_dirty_and_pristine_worktrees_differently() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: Some(worktree_spec(dirty_repo.path(), "feature/messy", true)),
+            auto_approve: false,
         })
         .await
         .expect("spawn dirty");
@@ -817,6 +882,7 @@ fn create_req_cmd(cwd: &std::path::Path, command: &str, branch: &str) -> CreateS
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(cwd, branch, true)),
+        auto_approve: false,
     }
 }
 
@@ -995,6 +1061,67 @@ async fn daemon_restart_recovers_session() {
     client.kill_session(s.id).await.expect("kill");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn sigterm_stops_structured_child_before_events_ws_drains() {
+    let (mut daemon, client) = bring_up().await;
+    let cwd = TempDir::new().unwrap();
+    let log = cwd.path().join("fake-acp.log");
+    let fake = fake_acp(&log);
+    let session = client
+        .spawn_session(&CreateSessionRequest {
+            view: SessionView::Structured,
+            cwd: cwd.path().to_path_buf(),
+            command: "claude".into(),
+            env: fake.env.clone(),
+            metadata: HashMap::new(),
+            worktree: None,
+            auto_approve: false,
+        })
+        .await
+        .expect("spawn structured session");
+    let ws_url = daemon.client().events_url().expect("events URL");
+    let (_events_ws, _) = tokio_tungstenite::connect_async(ws_url)
+        .await
+        .expect("events WS handshake");
+    wait_for_async("fake ACP starts", Duration::from_secs(5), || {
+        let log = log.clone();
+        async move { fake_acp_pid(&log).is_some() }
+    })
+    .await;
+    let pid = fake_acp_pid(&log).expect("fake ACP pid");
+
+    daemon.send_sigterm();
+
+    wait_for_async(
+        "fake ACP exits after SIGTERM",
+        Duration::from_secs(5),
+        || async { !pid_alive(pid) },
+    )
+    .await;
+    let sidecar_path = daemon
+        .state_dir()
+        .join("sessions")
+        .join(format!("{}.json", session.id));
+    wait_for_async(
+        "dead structured session sidecar",
+        Duration::from_secs(5),
+        || {
+            let sidecar_path = sidecar_path.clone();
+            async move {
+                std::fs::read(&sidecar_path)
+                    .ok()
+                    .and_then(|json| {
+                        serde_json::from_slice::<maestro_protocol::Session>(&json).ok()
+                    })
+                    .is_some_and(|saved| saved.status == SessionStatus::Dead)
+            }
+        },
+    )
+    .await;
+
+    daemon.stop();
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn concurrent_spawns_each_get_unique_ids() {
     let (_daemon, client) = bring_up().await;

crates/maestro-protocol/src/client.rs

@@ -17,7 +17,7 @@ use crate::routes::{self, UrlError};
 use crate::{
     ApiError, BranchInfo, CreateSessionRequest, DaemonInfo, DirListing, ErrorInfo, GitRoot,
     Project, RecentDirs, RenameSessionRequest, ReportActivityRequest, SendInputRequest, Session,
-    SetFocusRequest,
+    SetFocusRequest, StructuredApprovalDecision, StructuredPromptRequest,
 };
 
 /// Time budget for establishing a TCP connection to the daemon.
@@ -105,6 +105,11 @@ impl DaemonClient {
         Ok(routes::attach_url(&self.base, id)?)
     }
 
+    /// `WS /api/structured/:id` URL for this daemon.
+    pub fn structured_url(&self, id: Uuid) -> Result<String, ClientError> {
+        Ok(routes::structured_url(&self.base, id)?)
+    }
+
     // -- typed calls --------------------------------------------------------
 
     pub async fn list_sessions(&self) -> Result<Vec<Session>, ClientError> {
@@ -179,6 +184,57 @@ impl DaemonClient {
         Ok(())
     }
 
+    /// Send one prompt to a structured session. The daemon rejects a second
+    /// prompt while the preceding ACP turn is still active.
+    pub async fn send_structured_prompt(&self, id: Uuid, prompt: &str) -> Result<(), ClientError> {
+        let req = StructuredPromptRequest {
+            prompt: prompt.to_string(),
+        };
+        let resp = self
+            .send(
+                Method::POST,
+                &routes::structured_prompt(id),
+                &[],
+                Some(&req),
+            )
+            .await?;
+        check(resp).await?;
+        Ok(())
+    }
+
+    /// Cancel the structured session's active ACP turn.
+    pub async fn cancel_structured_turn(&self, id: Uuid) -> Result<(), ClientError> {
+        let resp = self
+            .send(
+                Method::POST,
+                &routes::structured_cancel(id),
+                &[],
+                None::<&()>,
+            )
+            .await?;
+        check(resp).await?;
+        Ok(())
+    }
+
+    /// Resolve the currently pending structured-session permission request.
+    pub async fn resolve_structured_approval(
+        &self,
+        id: Uuid,
+        nonce: &str,
+        decision: StructuredApprovalDecision,
+    ) -> Result<(), ClientError> {
+        let resp = self
+            .send(
+                Method::POST,
+                &routes::structured_approval(id, nonce),
+                &[],
+                Some(&decision),
+            )
+            .await?;
+        check(resp).await?;
+        Ok(())
+    }
+
     pub async fn daemon_info(&self) -> Result<DaemonInfo, ClientError> {
         self.get(routes::INFO, &[]).await
     }

crates/maestro-protocol/src/display.rs

@@ -166,45 +166,32 @@ pub fn merge_linear<T>(folder: TreeFolder<T>) -> TreeFolder<T> {
     cur
 }
 
-/// Command wrappers that run another program: the program is what follows.
-const WRAPPERS: [&str; 8] = [
-    "sudo", "env", "npx", "bunx", "uvx", "pnpm", "yarn", "command",
-];
-
 /// The program a command line runs, basenamed and stripped of its arguments —
 /// what a session card shows per `docs/SIDEBAR.md`, which names the program
 /// and never its flags. Leading `FOO=bar` assignments and wrappers (`sudo`,
-/// `npx`, `pnpm dlx`, …) are looked through. Mirrors the web's `splitCommand`.
+/// `npx`, `pnpm dlx`, …) are looked through, and quoting/escaping is honoured
+/// (never evaluated — no `$var`/`` `cmd` ``/`$(cmd)` expansion). A command a
+/// shell would need real grammar for (pipelines, `&&`/`;`, redirections,
+/// substitution, an unterminated quote) falls back to the naive first word
+/// rather than guessing through it (#199). Mirrors the web's `splitCommand`.
 pub fn command_program(command: &str) -> String {
-    let words: Vec<&str> = command.split_whitespace().collect();
-    let mut i = 0;
-    while i < words.len() {
-        let word = words[i];
-        if is_env_assignment(word) {
-            i += 1;
-            continue;
-        }
-        let wrapper = basename(word).to_lowercase();
-        if WRAPPERS.contains(&wrapper.as_str()) {
-            i += 1;
-            if (wrapper == "pnpm" || wrapper == "yarn") && words.get(i) == Some(&"dlx") {
-                i += 1;
-            }
-            continue;
-        }
-        break;
-    }
-    match words.get(i) {
-        Some(word) => basename(word).to_string(),
-        // Nothing but wrappers and assignments: say what was there rather than
-        // rendering an empty fragment.
-        None => command.trim().to_string(),
+    match resolve(command) {
+        Some(r) => match r.words.get(r.program_index) {
+            Some(word) => basename(word).to_string(),
+            // Nothing but wrappers and assignments: say what was there
+            // rather than rendering an empty fragment.
+            None => command.trim().to_string(),
+        },
+        None => legacy_first_word(command),
     }
 }
 
 /// Program name (already basenamed and lowercased) -> the tool id its mark
 /// stands for. Mirrors the web's `BY_PROGRAM` in `web/src/toolIcon.ts`;
 /// recognition is deliberately narrow, so an unrecognised program has no tool.
+/// `claude-code-acp` — the daemon's actual structured-session child — is
+/// deliberately absent: the daemon launches it directly and ignores
+/// `req.command`, so it is never itself a valid user-facing launch form.
 const BY_PROGRAM: [(&str, &str); 17] = [
     ("claude", "claude"),
     ("claude-code", "claude"),
@@ -226,29 +213,500 @@ const BY_PROGRAM: [(&str, &str); 17] = [
 ];
 
 /// The tool id a command line's icon stands for (`claude`, `codex`,
-/// `opencode`, ...), or `None` when the program is not one we have a mark for.
-/// The command bar matches this field (`docs/COMMAND-BAR.md`), so it must name
-/// the same tools the web's `splitCommand().tool` does.
+/// `opencode`, ...), or `None` when the program is not one we have a mark for
+/// — including a command line [`resolve`] would only guess at. The command
+/// bar matches this field (`docs/COMMAND-BAR.md`), so it must name the same
+/// tools the web's `splitCommand().tool` does.
 pub fn command_tool(command: &str) -> Option<&'static str> {
-    let program = command_program(command).to_lowercase();
+    let r = resolve(command)?;
+    let program = basename(r.words.get(r.program_index)?).to_lowercase();
     BY_PROGRAM
         .iter()
         .find(|(name, _)| *name == program)
         .map(|(_, tool)| *tool)
 }
 
-/// `FOO=bar`, the shell's own prefix for one command's environment.
-fn is_env_assignment(word: &str) -> bool {
-    let mut chars = word.chars();
+/// Whether a command line resolves to an agent Maestro can run as a
+/// structured (ACP) session — Claude Code or Codex, the two adapters
+/// `docs/STRUCTURED-VIEW.md` lists. Every client gates its structured-view
+/// control on this, and the daemon rejects a `Structured` request for
+/// anything else, so the answer has to come from one place.
+pub fn supports_structured_view(command: &str) -> bool {
+    matches!(command_tool(command), Some("claude" | "codex"))
+}
+
+/// [`resolve`]'s outcome: the tokenized command line, and the index within it
+/// of the word that is the actual program (past every assignment/wrapper it
+/// resolved through).
+struct Resolution {
+    words: Vec<String>,
+    program_index: usize,
+}
+
+/// Tokenize `command` and walk past leading `FOO=bar` assignments and known
+/// wrapper forms (interleaved in any order/count) to find the program. An
+/// assignment run is only consumed at the very start of the line or right
+/// after a wrapper whose own semantics accept one there ([`Wrapper::accepts_assignment`]) —
+/// `command FOO=1 claude` and `nohup FOO=1 claude` stop at `FOO=1` rather than
+/// skipping to `claude`, since `command`/`nohup` just exec their next argument
+/// as the program, they don't setenv from an assignment-shaped one (#199).
+/// `None` when [`tokenize`] can't safely make sense of the line at all.
+fn resolve(command: &str) -> Option<Resolution> {
+    let words = tokenize(command)?;
+    let refs: Vec<&str> = words.iter().map(|w| w.text.as_str()).collect();
+    let mut i = 0;
+    let mut assignment_allowed = true;
+    loop {
+        if assignment_allowed {
+            while matches!(words.get(i), Some(word) if is_env_assignment(word)) {
+                i += 1;
+            }
+        }
+        let Some(word) = words.get(i) else { break };
+        let wrapper = basename(&word.text).to_lowercase();
+        let Some(w) = wrapper_resolver(&wrapper) else {
+            break;
+        };
+        match (w.resolve)(&refs, i) {
+            Some(next) if next > i => {
+                i = next;
+                assignment_allowed = w.accepts_assignment;
+            }
+            // Not a form of the wrapper we recognise (an unknown option, or
+            // — for `pnpm`/`yarn`/`bun` — no `dlx`/`x` subcommand behind it):
+            // the wrapper word itself is the program, not a launcher.
+            _ => break,
+        }
+    }
+    Some(Resolution {
+        words: words.into_iter().map(|w| w.text).collect(),
+        program_index: i,
+    })
+}
+
+/// The naive "first whitespace word, basenamed" reading used only when
+/// [`tokenize`] rejects the line outright — still something sane to show,
+/// never a wrapper/tool match to act on.
+fn legacy_first_word(command: &str) -> String {
+    match command.split_whitespace().next() {
+        Some(word) => basename(word).to_string(),
+        None => command.trim().to_string(),
+    }
+}
+
+/// One token from [`tokenize`]: its dequoted text, and — when both the name
+/// and `=` were entirely unquoted/unescaped in the source — the byte length
+/// of the name. Quoting or escaping either (`"FOO"=1`, `F\OO=1`, `FOO\=1`)
+/// makes the word an executable named `FOO=1`; quoting/escaping only the value
+/// preserves the assignment, matching Bash's assignment-word grammar (#199).
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Word {
+    text: String,
+    plain_eq: Option<usize>,
+}
+
+/// Word-split `command` the way a shell would (honouring `'…'`, `"…"` and
+/// `\` quoting/escaping — POSIX quote *removal*, not evaluation) and return
+/// `None` the moment it needs real shell grammar this resolver doesn't
+/// attempt: a pipeline/list operator (`|`, `&`, `;`, `<`, `>`), a subshell or
+/// substitution (`(`, `)`, `` ` ``, `$(`), an unescaped newline (a command
+/// separator, like `;` — #199), or an unterminated quote/escape. Never
+/// expands `$var`/`` `cmd` ``/`$(cmd)` — a bare `$` is kept literal. A
+/// backslash immediately before a newline, quoted or not, is a line
+/// continuation: removed entirely rather than embedding the newline or
+/// ending the word (#199).
+fn tokenize(command: &str) -> Option<Vec<Word>> {
+    let mut words = Vec::new();
+    let mut current = String::new();
+    let mut has_current = false;
+    let mut plain_eq: Option<usize> = None;
+    let mut assignment_name_is_plain = true;
+    let mut chars = command.chars().peekable();
+
+    while let Some(c) = chars.next() {
+        match c {
+            ' ' | '\t' | '\r' => {
+                if has_current {
+                    words.push(Word {
+                        text: std::mem::take(&mut current),
+                        plain_eq: plain_eq.take(),
+                    });
+                    has_current = false;
+                    assignment_name_is_plain = true;
+                }
+            }
+            '\n' => return None,
+            '|' | '&' | ';' | '<' | '>' | '(' | ')' | '`' => return None,
+            '$' if chars.peek() == Some(&'(') => return None,
+            '\'' => {
+                has_current = true;
+                if plain_eq.is_none() {
+                    assignment_name_is_plain = false;
+                }
+                loop {
+                    match chars.next() {
+                        Some('\'') => break,
+                        Some(c2) => current.push(c2),
+                        None => return None, // unterminated single quote
+                    }
+                }
+            }
+            '"' => {
+                has_current = true;
+                if plain_eq.is_none() {
+                    assignment_name_is_plain = false;
+                }
+                loop {
+                    match chars.next() {
+                        Some('"') => break,
+                        Some('\\') => match chars.next() {
+                            Some(c2 @ ('"' | '\\' | '$' | '`')) => current.push(c2),
+                            Some('\n') => {} // line continuation, removed entirely
+                            Some(c2) => {
+                                current.push('\\');
+                                current.push(c2);
+                            }
+                            None => return None, // trailing backslash
+                        },
+                        Some(c2) => current.push(c2),
+                        None => return None, // unterminated double quote
+                    }
+                }
+            }
+            '\\' => match chars.next() {
+                Some('\n') => {} // line continuation, removed entirely
+                Some(c2) => {
+                    has_current = true;
+                    if plain_eq.is_none() {
+                        assignment_name_is_plain = false;
+                    }
+                    current.push(c2);
+                }
+                None => return None, // trailing backslash
+            },
+            other => {
+                has_current = true;
+                if other == '=' && plain_eq.is_none() && assignment_name_is_plain {
+                    plain_eq = Some(current.len());
+                }
+                current.push(other);
+            }
+        }
+    }
+    if has_current {
+        words.push(Word {
+            text: current,
+            plain_eq,
+        });
+    }
+    Some(words)
+}
+
+/// A wrapper's known `-`/`--` options: which take no value, and which
+/// consume either a following word or a `--flag=value` as theirs. A
+/// `-`-prefixed word this table doesn't know halts resolution rather than
+/// guessing past it (#199) — callers read that as [`OptionTable::consume`]
+/// returning `None`.
+struct OptionTable {
+    flags: &'static [&'static str],
+    valued: &'static [&'static str],
+    /// Whether this wrapper's short options may be combined (`-iv`) or take
+    /// an attached value (`-uroot`), the way real getopt-based tools do
+    /// (#199). JS-toolchain wrappers (`npx`, `pnpm`, `yarn`, bun's `x`/
+    /// `dlx`) don't get this — guessing at bundling they don't actually
+    /// support would resolve through options they'd reject outright.
+    bundles_short_options: bool,
+}
+
+impl OptionTable {
+    /// Consume this table's options starting at `words[i]`, returning the
+    /// index just past them (which may equal `i` if there are none) — or
+    /// `None` on an option this table doesn't recognise, or a valued option
+    /// missing its operand.
+    fn consume(&self, words: &[&str], mut i: usize) -> Option<usize> {
+        loop {
+            let Some(&word) = words.get(i) else {
+                return Some(i);
+            };
+            if word == "--" {
+                return Some(i + 1);
+            }
+            if word == "-" || !word.starts_with('-') {
+                return Some(i);
+            }
+            if let Some((flag, value)) = word.split_once('=') {
+                return if self.valued.contains(&flag) && !value.is_empty() {
+                    i += 1;
+                    continue;
+                } else {
+                    None
+                };
+            }
+            if self.flags.contains(&word) {
+                i += 1;
+                continue;
+            }
+            if self.valued.contains(&word) {
+                let value = words.get(i + 1)?;
+                if value.is_empty() || value.starts_with('-') {
+                    return None;
+                }
+                i += 2;
+                continue;
+            }
+            if self.bundles_short_options
+                && !word.starts_with("--")
+                && word.len() > 2
+                && self.matches_short_cluster(word)
+            {
+                i += 1;
+                continue;
+            }
+            return None;
+        }
+    }
+
+    /// `-iv` (bundled boolean short flags) or `-uroot` (a valued short
+    /// option with its value attached) — getopt's traditional short-option
+    /// forms. `false` the moment a character isn't a short option this
+    /// table knows, or a valued one ends the word with no attached value
+    /// left to be its operand (#199: rejected rather than guessed to come
+    /// from the next word instead).
+    fn matches_short_cluster(&self, word: &str) -> bool {
+        if !word.is_ascii() {
+            return false;
+        }
+        let bytes = word.as_bytes();
+        let mut buf = [b'-', 0];
+        let mut idx = 1;
+        while idx < bytes.len() {
+            buf[1] = bytes[idx];
+            let short = std::str::from_utf8(&buf).expect("ascii buffer");
+            if self.flags.contains(&short) {
+                idx += 1;
+                continue;
+            }
+            if self.valued.contains(&short) {
+                return idx + 1 < bytes.len();
+            }
+            return false;
+        }
+        true
+    }
+}
+
+const NO_OPTIONS: OptionTable = OptionTable {
+    flags: &[],
+    valued: &[],
+    bundles_short_options: false,
+};
+
+const ENV_OPTS: OptionTable = OptionTable {
+    flags: &[
+        "-i",
+        "--ignore-environment",
+        "-0",
+        "--null",
+        "-v",
+        "--debug",
+    ],
+    valued: &["-u", "--unset", "-C", "--chdir"],
+    bundles_short_options: true,
+};
+
+const SUDO_OPTS: OptionTable = OptionTable {
+    flags: &[
+        "-i",
+        "--login",
+        "-n",
+        "--non-interactive",
+        "-E",
+        "--preserve-env",
+        "-H",
+        "--set-home",
+        "-A",
+        "--askpass",
+        "-b",
+        "--background",
+        "-k",
+        "--reset-timestamp",
+        "-K",
+        "--remove-timestamp",
+        "-S",
+        "--stdin",
+    ],
+    valued: &["-u", "--user", "-g", "--group"],
+    bundles_short_options: true,
+};
+
+/// `-v`/`-V` only print what would run — they never execute it — so
+/// resolving through them would claim a program runs that `command` never
+/// launches (#199). Only `-p`, which still executes normally, is safe to
+/// look through.
+const COMMAND_BUILTIN_OPTS: OptionTable = OptionTable {
+    flags: &["-p"],
+    valued: &[],
+    bundles_short_options: true,
+};
+
+/// The bash *keyword* `time` only ever parses `-p` (POSIX output format);
+/// `-o`/`-v`/`-a`/`-f`/`--verbose`/... belong to the external GNU
+/// `/usr/bin/time`, a different program a bare `time` word doesn't
+/// necessarily name. Assuming them here would be guessing which `time`
+/// resolves (#199).
+fn resolve_time(words: &[&str], i: usize) -> Option<usize> {
+    let mut next = i + 1;
+    if words.get(next) == Some(&"-p") {
+        next += 1;
+    }
+    if words.get(next) == Some(&"--") {
+        next += 1;
+    }
+    match words.get(next) {
+        Some(word) if word.starts_with('-') => None,
+        _ => Some(next),
+    }
+}
+
+/// `-c`/`--call` embeds a whole shell command string rather than naming the
+/// program positionally — resolving past it would mean guessing at a
+/// program buried inside that string, so it's left unrecognised and
+/// resolution stops at `npx` (#199).
+const NPX_OPTS: OptionTable = OptionTable {
+    flags: &["-y", "--yes", "--no", "-q", "--quiet", "--ignore-existing"],
+    valued: &["-p", "--package", "--shell"],
+    bundles_short_options: false,
+};
+
+const PNPM_OPTS: OptionTable = OptionTable {
+    flags: &[
+        "--silent",
+        "-s",
+        "--stream",
+        "--aggregate-output",
+        "--no-progress",
+    ],
+    // `--package`/`--package=value` is documented in this pre-`dlx`
+    // position (`pnpm --package=x dlx y`), alongside the identical flag
+    // `dlx` itself also accepts (`PNPM_DLX_OPTS`).
+    valued: &["-C", "--dir", "--filter", "--package"],
+    bundles_short_options: false,
+};
+
+const YARN_OPTS: OptionTable = OptionTable {
+    flags: &["--silent", "-s", "--no-progress", "--non-interactive"],
+    valued: &["--cwd"],
+    bundles_short_options: false,
+};
+
+const PNPM_DLX_OPTS: OptionTable = OptionTable {
+    flags: &["-s", "--silent"],
+    valued: &["--package"],
+    bundles_short_options: false,
+};
+
+const YARN_DLX_OPTS: OptionTable = OptionTable {
+    flags: &["-q", "--quiet"],
+    valued: &["-p", "--package"],
+    bundles_short_options: false,
+};
+
+const BUN_X_OPTS: OptionTable = OptionTable {
+    flags: &["--bun", "--no-install", "--verbose", "--silent"],
+    valued: &["-p", "--package"],
+    bundles_short_options: false,
+};
+
+/// A resolver for one wrapper form: given the tokenized command and the
+/// index of the wrapper word itself, the index of the word after it (past
+/// its options and any subcommand it requires), or `None` if this occurrence
+/// isn't a form we resolve through.
+type WrapperResolver = fn(&[&str], usize) -> Option<usize>;
+
+/// One recognised wrapper form: how to walk past it, and whether an
+/// assignment word is a valid follow-on once it's been walked past.
+struct Wrapper {
+    resolve: WrapperResolver,
+    /// `true` only for wrappers that themselves interpret a following
+    /// `FOO=bar` as an environment assignment for the command they launch
+    /// (`env`, `sudo`), or a shell keyword that restarts the assignment-prefix
+    /// grammar for a brand new simple command (`time`). Every other wrapper
+    /// here is a plain executable that execs its next argument as the
+    /// program outright — an assignment-shaped one names a program literally
+    /// called `FOO=1`, not an env var (#199).
+    accepts_assignment: bool,
+}
+
+fn wrapper_resolver(name: &str) -> Option<Wrapper> {
+    let (resolve, accepts_assignment): (WrapperResolver, bool) = match name {
+        "env" => (|words, i| ENV_OPTS.consume(words, i + 1), true),
+        "sudo" => (|words, i| SUDO_OPTS.consume(words, i + 1), true),
+        "command" => (|words, i| COMMAND_BUILTIN_OPTS.consume(words, i + 1), false),
+        "nohup" => (|words, i| NO_OPTIONS.consume(words, i + 1), false),
+        "time" => (resolve_time, true),
+        "npx" => (|words, i| NPX_OPTS.consume(words, i + 1), false),
+        "pnpm" => (
+            |words, i| resolve_dlx(&PNPM_OPTS, &PNPM_DLX_OPTS, words, i),
+            false,
+        ),
+        "yarn" => (
+            |words, i| resolve_dlx(&YARN_OPTS, &YARN_DLX_OPTS, words, i),
+            false,
+        ),
+        "bun" => (resolve_bun, false),
+        "bunx" => (|words, i| BUN_X_OPTS.consume(words, i + 1), false),
+        "uvx" => (|_words, i| Some(i + 1), false),
+        _ => return None,
+    };
+    Some(Wrapper {
+        resolve,
+        accepts_assignment,
+    })
+}
+
+/// `pnpm`/`yarn` only look through to the package behind an explicit `dlx`
+/// — without it, the next word is a `package.json` script name, not a
+/// package to run (#199: `pnpm claude` is not `pnpm dlx claude`). `dlx`
+/// itself takes launcher-specific options too, consumed before the executable.
+fn resolve_dlx(
+    opts: &OptionTable,
+    dlx_opts: &OptionTable,
+    words: &[&str],
+    i: usize,
+) -> Option<usize> {
+    let j = opts.consume(words, i + 1)?;
+    if words.get(j) != Some(&"dlx") {
+        return None;
+    }
+    dlx_opts.consume(words, j + 1)
+}
+
+/// `bun x <pkg>` is bun's `dlx`/`npx` equivalent; `bun run <script>` is not
+/// (the same package-script ambiguity as bare `pnpm`/`yarn`), so only an `x`
+/// subcommand is looked through. `--bun` (`BUN_X_OPTS`) may follow it before
+/// the executable.
+fn resolve_bun(words: &[&str], i: usize) -> Option<usize> {
+    if words.get(i + 1) != Some(&"x") {
+        return None;
+    }
+    BUN_X_OPTS.consume(words, i + 2)
+}
+
+/// `FOO=bar`, the shell's own prefix for one command's environment —
+/// recognised only when the `=` came from plain, unquoted/unescaped source
+/// text (#199): `"FOO=1"` and `FOO\=1` name a program called `FOO=1`, not
+/// an assignment.
+fn is_env_assignment(word: &Word) -> bool {
+    let Some(eq) = word.plain_eq else {
+        return false;
+    };
+    let name = &word.text[..eq];
+    let mut chars = name.chars();
     match chars.next() {
         Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
         _ => return false,
     }
-    let rest: String = chars.collect();
-    match rest.split_once('=') {
-        Some((name, _)) => name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
-        None => false,
-    }
+    chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
 }
 
 fn basename(word: &str) -> &str {
@@ -497,38 +955,132 @@ mod tests {
             "claude"
         );
         assert_eq!(command_program("  zsh   -l  "), "zsh");
-        assert_eq!(command_program("hx src/main.rs"), "hx");
+    }
+
+    /// The #199 resolver contract: every case in the shared parity fixture,
+    /// asserted identically here and by `web/src/toolIcon.test.ts`, so a
+    /// resolver regression in either language fails its own suite.
+    #[test]
+    fn resolves_the_shared_command_resolution_fixture() {
+        #[derive(serde::Deserialize)]
+        struct Case {
+            command: String,
+            program: String,
+            tool: Option<String>,
+        }
+        #[derive(serde::Deserialize)]
+        struct Fixture {
+            cases: Vec<Case>,
+        }
+        let raw = include_str!("../../../fixtures/command-resolution.json");
+        let fixture: Fixture = serde_json::from_str(raw).expect("valid fixture JSON");
+        assert!(!fixture.cases.is_empty());
+        for case in &fixture.cases {
+            assert_eq!(
+                command_program(&case.command),
+                case.program,
+                "program for {:?}",
+                case.command
+            );
+            assert_eq!(
+                command_tool(&case.command),
+                case.tool.as_deref(),
+                "tool for {:?}",
+                case.command
+            );
+        }
+    }
+
+    fn word(text: &str) -> Word {
+        Word {
+            text: text.into(),
+            plain_eq: None,
+        }
+    }
+
+    /// Shell-aware tokenization (#199): quoting/escaping is honoured, never
+    /// evaluated — no `$var`/`` `cmd` ``/`$(cmd)` expansion is attempted.
+    #[test]
+    fn tokenize_handles_quotes_and_escapes_without_expanding_anything() {
+        assert_eq!(
+            tokenize("claude --resume"),
+            Some(vec![word("claude"), word("--resume")])
+        );
+        assert_eq!(
+            tokenize("\"/opt/my agent/claude\" --resume"),
+            Some(vec![word("/opt/my agent/claude"), word("--resume")])
+        );
+        assert_eq!(
+            tokenize("FOO=\"bar baz\" claude"),
+            Some(vec![
+                Word {
+                    text: "FOO=bar baz".into(),
+                    plain_eq: Some(3),
+                },
+                word("claude"),
+            ])
+        );
+        assert_eq!(
+            tokenize("claude --name=$HOME"),
+            Some(vec![
+                word("claude"),
+                Word {
+                    text: "--name=$HOME".into(),
+                    plain_eq: Some(6),
+                },
+            ]),
+            "a bare $ is kept literal, never expanded"
+        );
+    }
+
+    /// Real shell grammar this resolver doesn't attempt — pipelines, list
+    /// operators, subshells/substitution, an unescaped newline, an
+    /// unterminated quote — is rejected outright rather than guessed
+    /// through (#199).
+    #[test]
+    fn tokenize_rejects_ambiguous_shell_grammar() {
+        for command in [
+            "claude | tee log.txt",
+            "claude; echo done",
+            "claude && echo done",
+            "echo hi $(claude)",
+            "claude \"unterminated",
+            "claude 'unterminated",
+            "claude \\",
+            "claude\nclaude-code", // an unescaped newline separates commands, like `;`
+        ] {
+            assert_eq!(tokenize(command), None, "{command:?}");
+        }
+    }
+
+    /// A backslash immediately before a newline is a line continuation:
+    /// removed entirely, joining what it split rather than embedding a
+    /// literal newline or ending the command (#199).
+    #[test]
+    fn tokenize_treats_backslash_newline_as_a_continuation() {
+        assert_eq!(
+            tokenize("clau\\\nde --resume"),
+            Some(vec![word("claude"), word("--resume")])
+        );
+    }
+
+    /// Only a plain, unquoted/unescaped `=` marks an assignment boundary —
+    /// quoting or escaping the `=` itself disqualifies the word, even
+    /// though the dequoted text looks identical (#199).
+    #[test]
+    fn tokenize_only_marks_plain_unquoted_equals_signs_as_assignments() {
+        assert_eq!(tokenize("FOO=1 claude").unwrap()[0].plain_eq, Some(3));
+        assert_eq!(tokenize("\"FOO=1\" claude").unwrap()[0].plain_eq, None);
+        assert_eq!(tokenize("FOO\\=1 claude").unwrap()[0].plain_eq, None);
     }
 
     #[test]
-    fn command_program_looks_through_paths_env_and_wrappers() {
-        assert_eq!(command_program("/usr/local/bin/claude -p hi"), "claude");
-        assert_eq!(command_program("FOO=1 BAR=2 claude"), "claude");
-        assert_eq!(command_program("npx opencode"), "opencode");
-        assert_eq!(command_program("pnpm dlx opencode run"), "opencode");
-    }
-
-    #[test]
-    fn command_program_keeps_a_line_that_is_only_wrappers() {
-        assert_eq!(command_program("sudo"), "sudo");
-        assert_eq!(command_program(""), "");
-    }
-
-    /// The command bar's `tool` field (docs/COMMAND-BAR.md) names the same
-    /// tools the web's `splitCommand().tool` does.
-    #[test]
-    fn command_tool_names_the_mark_the_card_shows() {
-        assert_eq!(command_tool("claude --resume"), Some("claude"));
-        assert_eq!(command_tool("npx opencode"), Some("opencode"));
-        assert_eq!(command_tool("/bin/zsh -l"), Some("shell"));
-        assert_eq!(command_tool("CLAUDE"), Some("claude"));
-    }
-
-    /// Narrow on purpose: an unrecognised program has no mark, so the
-    /// candidate has no `tool` field to match rather than a wrong one.
-    #[test]
-    fn command_tool_is_absent_for_an_unrecognised_program() {
-        assert_eq!(command_tool("hx src/main.rs"), None);
-        assert_eq!(command_tool(""), None);
+    fn structured_view_support_follows_the_resolved_program() {
+        assert!(supports_structured_view("claude --resume"));
+        assert!(supports_structured_view("FOO=1 /usr/local/bin/codex exec"));
+        assert!(supports_structured_view("npx claude-code"));
+        assert!(!supports_structured_view("opencode"));
+        assert!(!supports_structured_view("bash -l"));
+        assert!(!supports_structured_view("claude-code-acp"));
     }
 }

crates/maestro-protocol/src/lib.rs

@@ -123,7 +123,7 @@ pub struct Session {
     /// daemon that predates the field keeps working untouched.
     #[serde(default)]
     pub view: SessionView,
-    /// The ACP session id the `claude-code-acp` adapter handed back from
+    /// The ACP session id the selected provider adapter handed back from
     /// `session/new` (#134). Only a [`SessionView::Structured`] session has
     /// one, and only once its handshake succeeded; a later respawn passes it
     /// to `session/load` so the conversation continues (#135). Distinct from
@@ -156,9 +156,9 @@ pub enum SessionStatus {
     Dead,
 }
 
-/// Inferred session activity, orthogonal to [`SessionStatus`] (NAP-340). The
-/// daemon derives this from tmux pane state, PTY quiescence, and `/proc`
-/// inspection — never by parsing the terminal byte stream.
+/// Session activity, orthogonal to [`SessionStatus`] (NAP-340). Terminal
+/// sessions use pane/process inference and agent reports; structured sessions
+/// use their ACP turn lifecycle (docs/SIDEBAR.md).
 ///
 /// Deserializes leniently (#110, SIDEBAR.md Precedence): an unknown variant
 /// from a newer daemon becomes [`ActivityState::Idle`] instead of failing the
@@ -166,16 +166,19 @@ pub enum SessionStatus {
 /// forgiven.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Default)]
 pub enum ActivityState {
-    /// Producing output, or the foreground process is busy.
+    /// Producing output, the foreground process is busy, or an ACP turn is active.
     Active,
     /// Foreground process alive but quiescent. The forward-compatible default.
     #[default]
     Idle,
-    /// Blocked on a `read()` from the pty — waiting on the user.
+    /// Blocked on terminal input or waiting for an ACP approval.
     AwaitingInput,
-    /// The agent running in the session reported a failure (#102). Never
-    /// inferred by the daemon; only set when an agent reports it (#105).
+    /// 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 {
@@ -188,6 +191,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,
         })
@@ -226,9 +230,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"],
         )),
     }
 }
@@ -384,6 +389,10 @@ pub struct CreateSessionRequest {
     /// untouched.
     #[serde(default)]
     pub view: SessionView,
+    /// When `true`, the daemon auto-approves every ACP permission request
+    /// for this structured session.
+    #[serde(default)]
+    pub auto_approve: bool,
 }
 
 /// Result of `GET /api/dirs`: the immediate subdirectories of one directory.
@@ -523,6 +532,11 @@ pub struct SpawnPreset {
     pub id: String,
     pub label: String,
     pub command: String,
+    /// When `true`, the daemon auto-approves every ACP permission request
+    /// for structured sessions spawned from this preset instead of surfacing
+    /// them to the client.
+    #[serde(default)]
+    pub auto_approve: bool,
 }
 
 /// Build provenance of the running daemon: the commit it was compiled
@@ -755,6 +769,150 @@ pub enum CatalogEvent {
     },
 }
 
+// ---------------------------------------------------------------------------
+// Structured-session projections
+// ---------------------------------------------------------------------------
+
+/// One client-neutral item in a structured session transcript.
+///
+/// `data` preserves the ACP payload without committing clients to an ACP
+/// dependency. Rendering choices, including markdown and tool-card treatment,
+/// stay with the client.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptRow {
+    /// Stable within one session, so later deltas can address this row.
+    pub id: String,
+    pub kind: TranscriptRowKind,
+    pub data: Value,
+}
+
+/// The semantic shape of a [`TranscriptRow`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TranscriptRowKind {
+    User,
+    AgentText,
+    AgentThought,
+    ToolCall,
+    ToolDiff,
+    Approval,
+    Plan,
+    Notice,
+}
+
+/// A complete transcript at a durable event-log position.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptSnapshot {
+    pub cursor: u64,
+    #[serde(default)]
+    pub rows: Vec<TranscriptRow>,
+}
+
+/// One durable, client-neutral replay step from a structured session.
+///
+/// Results are ordered by increasing `cursor`. `since` returns the first
+/// matching steps; `before` returns the final matching steps, still increasing.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct StructuredReplayEvent {
+    /// Durable ACP-log position represented by this projected step.
+    pub cursor: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transcript: Option<TranscriptDelta>,
+    pub state: ReducedState,
+}
+
+/// A change to a transcript row.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum TranscriptDelta {
+    Append { row: TranscriptRow },
+    Patch { row: TranscriptRow },
+    Remove { id: String },
+}
+
+/// Per-turn indicators derived from the ACP stream.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TurnState {
+    #[serde(default)]
+    pub responding: bool,
+    #[serde(default)]
+    pub thinking: bool,
+    #[serde(default)]
+    pub active_tool_calls: Vec<String>,
+    /// Wall-clock start of the active prompt. This lets reconnecting clients
+    /// keep one continuous elapsed-time display instead of restarting at zero.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_at: Option<DateTime<Utc>>,
+    /// Context-window usage when the active prompt began. ACP exposes context
+    /// occupancy, not provider billing-token accounting, so clients must label
+    /// deltas as context tokens rather than tokens billed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_context_tokens: Option<u64>,
+}
+
+/// A whole-session view derived from ACP notifications.
+///
+/// Values whose shape ACP owns are carried as JSON so this wire protocol stays
+/// forward-compatible when ACP adds fields or variants.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ReducedState {
+    #[serde(default)]
+    pub turn: TurnState,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pending_approval: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub plan: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub usage: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub context: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config_options: Option<Value>,
+}
+
+/// Server messages sent over a structured-session WebSocket.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum StructuredEvent {
+    TranscriptSnapshot {
+        snapshot: TranscriptSnapshot,
+    },
+    ReducedState {
+        state: ReducedState,
+    },
+    ProjectionUpdate {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        transcript: Option<TranscriptDelta>,
+        state: ReducedState,
+    },
+}
+
+/// HTTP body for `POST /api/sessions/:id/structured/prompt`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct StructuredPromptRequest {
+    pub prompt: String,
+}
+
+/// HTTP body for `POST /api/sessions/:id/structured/config`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct StructuredConfigRequest {
+    pub config_id: String,
+    pub value: Value,
+}
+
+/// Operator decision for a pending ACP permission request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StructuredApprovalDecision {
+    AllowOnce,
+    AllowForSession,
+    Deny,
+}
+
 // ---------------------------------------------------------------------------
 // Client ↔ Daemon control messages (text frames on the attach WS)
 // ---------------------------------------------------------------------------
@@ -1108,6 +1266,7 @@ mod tests {
                 create_branch: true,
             }),
             view: SessionView::Terminal,
+            auto_approve: false,
         };
         assert_eq!(req, round_trip(&req));
     }
@@ -1144,6 +1303,31 @@ mod tests {
         assert_eq!(structured, round_trip(&structured));
     }
 
+    #[test]
+    fn structured_projection_types_round_trip_and_default() {
+        let row = TranscriptRow {
+            id: "tool:read-1".into(),
+            kind: TranscriptRowKind::ToolCall,
+            data: serde_json::json!({"name": "vendor.read", "title": "Read"}),
+        };
+        let snapshot = TranscriptSnapshot {
+            cursor: 7,
+            rows: vec![row.clone()],
+        };
+        assert_eq!(snapshot, round_trip(&snapshot));
+        assert_eq!(
+            TranscriptDelta::Patch { row: row.clone() },
+            round_trip(&TranscriptDelta::Patch { row })
+        );
+
+        let state: ReducedState = serde_json::from_value(serde_json::json!({})).unwrap();
+        assert_eq!(state, ReducedState::default());
+        assert_eq!(
+            serde_json::to_value(TranscriptRowKind::AgentThought).unwrap(),
+            serde_json::json!("agent_thought")
+        );
+    }
+
     #[test]
     fn acp_session_id_defaults_to_none_and_round_trips() {
         // A payload from before #134 carries no `acp_session_id`; it must

crates/maestro-protocol/src/routes.rs

@@ -71,6 +71,41 @@ pub fn attach(id: Uuid) -> String {
     format!("{API_PREFIX}/attach/{id}")
 }
 
+/// `WS /api/structured/:id` — transcript/state snapshots and live deltas.
+pub fn structured(id: Uuid) -> String {
+    format!("{API_PREFIX}/structured/{id}")
+}
+
+/// `GET /api/sessions/:id/structured/replay` — cursor-bounded ACP history.
+pub fn structured_replay(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/replay")
+}
+
+/// `POST /api/sessions/:id/structured/prompt` — send an ACP prompt.
+pub fn structured_prompt(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/prompt")
+}
+
+/// `POST /api/sessions/:id/structured/attachments` — upload a file.
+pub fn structured_attachment(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/attachments")
+}
+
+/// `POST /api/sessions/:id/structured/cancel` — cancel an ACP turn.
+pub fn structured_cancel(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/cancel")
+}
+
+/// `POST /api/sessions/:id/structured/config` — change an ACP session option.
+pub fn structured_config(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/config")
+}
+
+/// `POST /api/sessions/:id/structured/approvals/:nonce` — answer ACP permission.
+pub fn structured_approval(id: Uuid, nonce: &str) -> String {
+    format!("{SESSIONS}/{id}/structured/approvals/{nonce}")
+}
+
 /// Axum-style patterns for the two parameterised routes, so the server
 /// registers the same paths [`session`] and [`attach`] build.
 pub mod patterns {
@@ -80,6 +115,13 @@ pub mod patterns {
     pub const SESSION_PROMPT: &str = "/api/sessions/:id/prompt";
     pub const SESSION_FOCUS: &str = "/api/sessions/:id/focus";
     pub const ATTACH: &str = "/api/attach/:id";
+    pub const STRUCTURED: &str = "/api/structured/:id";
+    pub const STRUCTURED_REPLAY: &str = "/api/sessions/:id/structured/replay";
+    pub const STRUCTURED_PROMPT: &str = "/api/sessions/:id/structured/prompt";
+    pub const STRUCTURED_ATTACHMENT: &str = "/api/sessions/:id/structured/attachments";
+    pub const STRUCTURED_CANCEL: &str = "/api/sessions/:id/structured/cancel";
+    pub const STRUCTURED_CONFIG: &str = "/api/sessions/:id/structured/config";
+    pub const STRUCTURED_APPROVAL: &str = "/api/sessions/:id/structured/approvals/:nonce";
 }
 
 /// A daemon base URL that could not be turned into a WebSocket base.
@@ -129,6 +171,11 @@ pub fn attach_url(http_base: &str, id: Uuid) -> Result<String, UrlError> {
     Ok(format!("{}{}", ws_base(http_base)?, attach(id)))
 }
 
+/// Full `WS /api/structured/:id` URL for a daemon reachable at `http_base`.
+pub fn structured_url(http_base: &str, id: Uuid) -> Result<String, UrlError> {
+    Ok(format!("{}{}", ws_base(http_base)?, structured(id)))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -178,6 +225,10 @@ mod tests {
             events_url("http://host:7070/").unwrap(),
             "ws://host:7070/api/events"
         );
+        assert_eq!(
+            structured_url("http://host:7070/", id()).unwrap(),
+            "ws://host:7070/api/structured/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
     }
 
     #[test]
@@ -206,6 +257,22 @@ mod tests {
             attach(id()),
             "/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
         );
+        assert_eq!(
+            structured(id()),
+            "/api/structured/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
+        assert_eq!(
+            structured_replay(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/replay"
+        );
+        assert_eq!(
+            structured_prompt(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/prompt"
+        );
+        assert_eq!(
+            structured_cancel(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/cancel"
+        );
         assert_eq!(
             attach_url("https://laptop.lan:7070", id()).unwrap(),
             "wss://laptop.lan:7070/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
@@ -240,6 +307,22 @@ mod tests {
             patterns::ATTACH.trim_end_matches(":id"),
             attach(id()).trim_end_matches(&id().to_string())
         );
+        assert_eq!(
+            patterns::STRUCTURED.trim_end_matches(":id"),
+            structured(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_REPLAY.trim_end_matches(":id/structured/replay"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_PROMPT.trim_end_matches(":id/structured/prompt"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_CANCEL.trim_end_matches(":id/structured/cancel"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
     }
 
     #[test]
@@ -258,5 +341,9 @@ mod tests {
             assert!(path.starts_with(API_PREFIX), "{path} escapes {API_PREFIX}");
         }
         assert!(attach(id()).starts_with(API_PREFIX));
+        assert!(structured(id()).starts_with(API_PREFIX));
+        assert!(structured_replay(id()).starts_with(API_PREFIX));
+        assert!(structured_prompt(id()).starts_with(API_PREFIX));
+        assert!(structured_cancel(id()).starts_with(API_PREFIX));
     }
 }

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};
@@ -60,6 +61,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 +95,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 +182,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 +280,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/Cargo.toml

@@ -21,6 +21,7 @@ thiserror.workspace = true
 tokio = { workspace = true, features = ["sync", "time", "macros", "rt"] }
 tokio-tungstenite.workspace = true
 tracing.workspace = true
+unicode-width.workspace = true
 uuid.workspace = true
 vt100.workspace = true
 

crates/maestro-tui/src/app.rs

@@ -11,13 +11,17 @@
 //! `dispatch` / the overlay routing.
 
 use std::collections::{HashMap, HashSet};
+use std::io::Write;
 use std::path::PathBuf;
 use std::time::Duration;
 
 use chrono::Utc;
 use crossterm::event::{Event as CtEvent, EventStream};
 use futures_util::StreamExt;
-use maestro_protocol::{routes, BranchInfo, CreateSessionRequest, DaemonClient, NameBatch};
+use maestro_protocol::{
+    routes, BranchInfo, CreateSessionRequest, DaemonClient, NameBatch, SessionView,
+    StructuredApprovalDecision,
+};
 use ratatui::Terminal;
 use uuid::Uuid;
 
@@ -38,6 +42,8 @@ use crate::render::{draw, RegionMap, RenderInputs};
 use crate::session_task::{SessionInput, SessionTask};
 use crate::sidebar::Sidebar;
 use crate::state::{AppState, Focus, OverlayKind, SidebarItem};
+use crate::structured_pane::StructuredPane;
+use crate::structured_task::{StructuredHandle, StructuredTask};
 use crate::text_input::TextInput;
 use crate::TuiError;
 
@@ -49,11 +55,42 @@ enum OverlayDecision {
     Pass,
 }
 
+fn copy_to_terminal_clipboard(text: &str) -> std::io::Result<()> {
+    let encoded = base64_encode(text.as_bytes());
+    let mut output = std::io::stdout();
+    write!(output, "\x1b]52;c;{encoded}\x07")?;
+    output.flush()
+}
+
+fn base64_encode(bytes: &[u8]) -> String {
+    const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut output = String::with_capacity(bytes.len().div_ceil(3) * 4);
+    for chunk in bytes.chunks(3) {
+        let bits = (u32::from(chunk[0]) << 16)
+            | (u32::from(*chunk.get(1).unwrap_or(&0)) << 8)
+            | u32::from(*chunk.get(2).unwrap_or(&0));
+        output.push(TABLE[((bits >> 18) & 0x3f) as usize] as char);
+        output.push(TABLE[((bits >> 12) & 0x3f) as usize] as char);
+        output.push(if chunk.len() > 1 {
+            TABLE[((bits >> 6) & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+        output.push(if chunk.len() > 2 {
+            TABLE[(bits & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+    }
+    output
+}
+
 pub struct App {
     cfg: TuiConfig,
     home_dir: String,
     catalog: CatalogStore,
     emulators: SessionEmulators,
+    structured: HashMap<Uuid, StructuredHandle>,
     state: AppState,
     help: HelpOverlay,
     chord: ChordState,
@@ -163,6 +200,18 @@ pub enum Effect {
         id: Uuid,
         bytes: Vec<u8>,
     },
+    StructuredPrompt {
+        id: Uuid,
+        prompt: String,
+    },
+    StructuredCancel {
+        id: Uuid,
+    },
+    StructuredApproval {
+        id: Uuid,
+        nonce: String,
+        decision: StructuredApprovalDecision,
+    },
     /// Fetch presets / projects / names for a freshly opened form (#64).
     LoadDraft,
     /// Fast-forward spawn (#67): resolve every default from the daemon and
@@ -214,6 +263,7 @@ impl App {
             home_dir: std::env::var("HOME").unwrap_or_default(),
             catalog,
             emulators: SessionEmulators::default(),
+            structured: HashMap::new(),
             state: AppState::new(),
             draft: None,
             help,
@@ -321,6 +371,15 @@ impl App {
             return Ok(false);
         }
 
+        if self.handle_structured_mouse(&key) {
+            return Ok(false);
+        }
+
+        if let Some(effects) = self.handle_structured_key(&key) {
+            self.perform(effects).await;
+            return Ok(false);
+        }
+
         if let Some(effect) = self.handle_pane_scroll(&key) {
             self.perform(effect.into_iter().collect()).await;
             return Ok(false);
@@ -399,6 +458,61 @@ impl App {
         true
     }
 
+    /// Transcript blocks are pointer targets: click selects the whole block,
+    /// gives it the selection surface, and copies its complete text.
+    fn handle_structured_mouse(&mut self, key: &InputKey) -> bool {
+        let InputKey::Mouse {
+            kind,
+            region: Region::Pane,
+            row,
+            ..
+        } = key
+        else {
+            return false;
+        };
+        if !matches!(kind, MouseKind::Click | MouseKind::Hover) {
+            return false;
+        }
+        let Some(sid) = self.state.active_session() else {
+            return false;
+        };
+        let Some(handle) = self.structured.get(&sid) else {
+            return false;
+        };
+        let Some(pane) = self.region.pane else {
+            return false;
+        };
+        let offset = usize::from(row.saturating_sub(pane.y));
+        let transcript_height = pane.height.saturating_sub(pane.height.min(3));
+        if offset >= usize::from(transcript_height) {
+            return true;
+        }
+        let mut state = handle.state.lock().expect("structured state mutex");
+        let rendered_line = state.scroll.saturating_add(offset);
+        if !state.select_rendered_line(rendered_line) {
+            return true;
+        }
+        let Some(id) = state.selected.as_deref() else {
+            return true;
+        };
+        let Some(transcript) = state.rows.iter().find(|item| item.id == id) else {
+            return true;
+        };
+        if *kind == MouseKind::Hover {
+            return true;
+        }
+        let text = crate::structured_pane::copy_text(transcript);
+        drop(state);
+        if text.is_empty() {
+            return true;
+        }
+        match copy_to_terminal_clipboard(&text) {
+            Ok(()) => self.state.toast("copied transcript block"),
+            Err(error) => self.state.toast(format!("copy failed: {error}")),
+        }
+        true
+    }
+
     /// Carry out what `dispatch` decided. The only place in `App` that talks to
     /// the daemon.
     async fn perform(&mut self, effects: Vec<Effect>) {
@@ -419,6 +533,44 @@ impl App {
                         let _ = handle.tx.send(SessionInput::Bytes(bytes)).await;
                     }
                 }
+                Effect::StructuredPrompt { id, prompt } => {
+                    if let Err(error) = self.daemon.send_structured_prompt(id, &prompt).await {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle
+                                .state
+                                .lock()
+                                .expect("structured state mutex")
+                                .prompt_failed(prompt, error.to_string());
+                        }
+                    }
+                }
+                Effect::StructuredCancel { id } => {
+                    if let Err(error) = self.daemon.cancel_structured_turn(id).await {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle.state.lock().expect("structured state mutex").error =
+                                Some(error.to_string());
+                        }
+                    }
+                }
+                Effect::StructuredApproval {
+                    id,
+                    nonce,
+                    decision,
+                } => {
+                    if let Err(error) = self
+                        .daemon
+                        .resolve_structured_approval(id, &nonce, decision)
+                        .await
+                    {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle
+                                .state
+                                .lock()
+                                .expect("structured state mutex")
+                                .approval_failed(&nonce, error.to_string());
+                        }
+                    }
+                }
             }
         }
     }
@@ -563,13 +715,13 @@ impl App {
             Action::OpenCommandBar => effects.extend(self.open_command_bar()),
             // Escape hatch (#156): the literal byte, not the bar.
             Action::SendLiteralCtrlK => {
-                effects.extend(self.forward_to_session(&InputKey::ctrl_char('k')));
+                effects.extend(self.forward_literal_to_terminal(&InputKey::ctrl_char('k')));
             }
             // Escape hatch (#158): the leader's own byte, built from the
             // configured leader rather than a hardcoded key.
             Action::SendLiteralLeader => {
                 let leader = self.cfg.leader.clone();
-                effects.extend(self.forward_to_session(&leader));
+                effects.extend(self.forward_literal_to_terminal(&leader));
             }
             Action::OpenSpawnModal => {
                 self.open_spawn_modal();
@@ -587,7 +739,7 @@ impl App {
                         }
                         // A previewed session is already attached: committing
                         // to it keeps that stream rather than reopening one.
-                        if self.emulators.get(sid).is_none() {
+                        if !self.is_attached(sid) {
                             effects.push(Effect::Attach(sid));
                         }
                     }
@@ -595,6 +747,9 @@ impl App {
                     // preview budget.
                     self.preview_lru.retain(|s| *s != sid);
                     self.state.attach_to_focused(sid);
+                    if self.session_view(sid) == SessionView::Structured {
+                        self.state.mode = Mode::Normal;
+                    }
                 }
             }
             Action::KillHighlighted => {
@@ -663,7 +818,7 @@ impl App {
         self.state.preview = Some(sid);
         // Set outside the input path, so nothing else marks the frame stale.
         self.epoch = self.epoch.wrapping_add(1);
-        let fresh = self.emulators.get(sid).is_none();
+        let fresh = !self.is_attached(sid);
         if fresh {
             self.preview_lru.retain(|s| *s != sid);
             self.preview_lru.push(sid);
@@ -732,15 +887,27 @@ impl App {
 
     /// Open a stream for `sid` if one isn't already running.
     fn attach(&mut self, sid: Uuid) {
-        if self.emulators.get(sid).is_some() {
+        self.attach_with_view(sid, self.session_view(sid));
+    }
+
+    fn attach_with_view(&mut self, sid: Uuid, view: SessionView) {
+        if self.is_attached(sid) {
             return;
         }
-        match self.daemon.attach_url(sid) {
-            Ok(ws_url) => {
-                let handle = SessionTask::spawn(ws_url, 24, 80);
-                self.emulators.insert(sid, handle);
-            }
-            Err(e) => self.state.toast(format!("attach failed: {e}")),
+        match view {
+            SessionView::Terminal => match self.daemon.attach_url(sid) {
+                Ok(ws_url) => {
+                    let handle = SessionTask::spawn(ws_url, 24, 80);
+                    self.emulators.insert(sid, handle);
+                }
+                Err(e) => self.state.toast(format!("attach failed: {e}")),
+            },
+            SessionView::Structured => match self.daemon.structured_url(sid) {
+                Ok(ws_url) => {
+                    self.structured.insert(sid, StructuredTask::spawn(ws_url));
+                }
+                Err(e) => self.state.toast(format!("attach failed: {e}")),
+            },
         }
     }
 
@@ -748,9 +915,26 @@ impl App {
     /// dropping its vt100 parser.
     fn release_session(&mut self, sid: Uuid) {
         self.emulators.remove(sid);
+        if let Some(handle) = self.structured.remove(&sid) {
+            handle.end();
+        }
         self.last_sent_size.remove(&sid);
     }
 
+    fn session_view(&self, sid: Uuid) -> SessionView {
+        self.catalog
+            .snapshot()
+            .sessions
+            .iter()
+            .find(|session| session.id == sid)
+            .map(|session| session.view)
+            .unwrap_or_default()
+    }
+
+    fn is_attached(&self, sid: Uuid) -> bool {
+        self.emulators.get(sid).is_some() || self.structured.contains_key(&sid)
+    }
+
     /// Return the session under the sidebar highlight, falling back to the
     /// first listed session so the user can attach without arrowing first.
     fn pick_sidebar_target(&self) -> Option<Uuid> {
@@ -817,6 +1001,16 @@ impl App {
     /// attached to send it to.
     fn forward_to_session(&mut self, key: &InputKey) -> Option<Effect> {
         let sid = self.state.active_session()?;
+        if let Some(handle) = self.structured.get(&sid) {
+            let mut state = handle.state.lock().expect("structured state mutex");
+            if matches!(key, InputKey::Enter) {
+                return state
+                    .begin_prompt()
+                    .map(|prompt| Effect::StructuredPrompt { id: sid, prompt });
+            }
+            state.edit_composer(key);
+            return None;
+        }
         let handle = self.emulators.get(sid)?;
         let bytes = encode_key(key)?;
         handle
@@ -827,6 +1021,86 @@ impl App {
         Some(Effect::Forward { id: sid, bytes })
     }
 
+    fn forward_literal_to_terminal(&mut self, key: &InputKey) -> Option<Effect> {
+        let sid = self.state.active_session()?;
+        if self.session_view(sid) == SessionView::Structured {
+            return None;
+        }
+        self.forward_to_session(key)
+    }
+
+    fn handle_structured_key(&mut self, key: &InputKey) -> Option<Vec<Effect>> {
+        if self.state.focus != Focus::Pane || self.state.preview.is_some() {
+            return None;
+        }
+        let sid = self.state.active_session()?;
+        let handle = self.structured.get(&sid)?;
+        let mut state = handle.state.lock().expect("structured state mutex");
+        if self.state.mode == Mode::Insert {
+            if matches!(key, InputKey::Esc) && state.turn_active() {
+                return Some(vec![Effect::StructuredCancel { id: sid }]);
+            }
+            return None;
+        }
+        let effects = match key {
+            InputKey::Char {
+                c: 'j',
+                ctrl: false,
+                alt: false,
+                ..
+            }
+            | InputKey::Down => {
+                state.select(1);
+                Vec::new()
+            }
+            InputKey::Char {
+                c: 'k',
+                ctrl: false,
+                alt: false,
+                ..
+            }
+            | InputKey::Up => {
+                state.select(-1);
+                Vec::new()
+            }
+            InputKey::Enter => {
+                state.toggle_selected();
+                Vec::new()
+            }
+            InputKey::Esc => {
+                if state.turn_active() {
+                    vec![Effect::StructuredCancel { id: sid }]
+                } else {
+                    Vec::new()
+                }
+            }
+            InputKey::Char {
+                c: key @ ('a' | 'A' | 'd'),
+                ctrl: false,
+                alt: false,
+                ..
+            } => state
+                .approval_decision(*key)
+                .map(|(nonce, decision)| Effect::StructuredApproval {
+                    id: sid,
+                    nonce,
+                    decision,
+                })
+                .into_iter()
+                .collect(),
+            InputKey::PageUp => {
+                state.scroll_by(self.pane_page_rows() as isize);
+                Vec::new()
+            }
+            InputKey::PageDown => {
+                state.scroll_by(-(self.pane_page_rows() as isize));
+                Vec::new()
+            }
+            _ => return None,
+        };
+        Some(effects)
+    }
+
     fn pane_page_rows(&self) -> usize {
         self.region
             .pane
@@ -839,6 +1113,14 @@ impl App {
         let Some(sid) = self.state.active_session() else {
             return;
         };
+        if let Some(handle) = self.structured.get(&sid) {
+            handle
+                .state
+                .lock()
+                .expect("structured state mutex")
+                .scroll_by(rows);
+            return;
+        }
         let Some(handle) = self.emulators.get(sid) else {
             return;
         };
@@ -872,6 +1154,14 @@ impl App {
             _ => return None,
         };
         let sid = self.state.active_session()?;
+        if let Some(handle) = self.structured.get(&sid) {
+            handle
+                .state
+                .lock()
+                .expect("structured state mutex")
+                .scroll_by(lines);
+            return Some(None);
+        }
         let handle = self.emulators.get(sid)?;
         let pane = self.region.pane?;
         let parser = handle.screen.lock().expect("vt100 parser mutex");
@@ -1294,7 +1584,10 @@ impl App {
                 }
                 self.draft = None;
                 self.state.complete_spawn(sid);
-                self.attach(sid);
+                if session.view == SessionView::Structured {
+                    self.state.mode = Mode::Normal;
+                }
+                self.attach_with_view(sid, session.view);
             }
             Err(e) => {
                 // A failed POST belongs in the form it came from (#64), not a
@@ -1355,6 +1648,11 @@ impl App {
             self.emulators
                 .get(sid)
                 .map(|h| (sid, h.revision(), h.state()))
+                .or_else(|| {
+                    self.structured
+                        .get(&sid)
+                        .map(|h| (sid, h.revision(), h.connection()))
+                })
         });
         FrameKey {
             catalog: self.catalog.version(),
@@ -1416,6 +1714,17 @@ impl App {
                 focused: matches!(self.state.focus, Focus::Pane) && !previewing,
             })
         });
+        let structured_pane = shown_sid.and_then(|sid| {
+            let handle = self.structured.get(&sid)?;
+            let session = snap.sessions.iter().find(|session| session.id == sid)?;
+            Some(StructuredPane {
+                handle: handle.clone(),
+                focused: matches!(self.state.focus, Focus::Pane) && !previewing,
+                mode: self.state.mode,
+                session_status: session.status,
+                activity_detail: session.activity_detail.clone(),
+            })
+        });
         let pane_title = match shown_sid {
             Some(sid) => {
                 let name = snap
@@ -1439,6 +1748,7 @@ impl App {
             home_dir: &self.home_dir,
             pane_title: &pane_title,
             pane: pane.as_ref(),
+            structured_pane: structured_pane.as_ref(),
             state: &self.state,
             draft: self.draft.as_ref(),
             help: &self.help,
@@ -1685,6 +1995,12 @@ async fn fetch_branches(
 #[cfg(test)]
 mod tests {
     use super::*;
+
+    #[test]
+    fn clipboard_payload_uses_standard_base64() {
+        assert_eq!(base64_encode(b"hello"), "aGVsbG8=");
+        assert_eq!(base64_encode("✓".as_bytes()), "4pyT");
+    }
     use crate::action::Action;
     use crate::draft::DraftField;
     use crate::keymap::Mode;
@@ -2789,6 +3105,7 @@ mod tests {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         };
         app.submit_spawn(req).await;
 
@@ -2805,6 +3122,56 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn create_response_selects_transport_before_catalog_event() {
+        use axum::routing::post;
+        use axum::Json;
+
+        async fn spawn_session(
+            Json(req): Json<CreateSessionRequest>,
+        ) -> Json<maestro_protocol::Session> {
+            let id = match req.view {
+                SessionView::Terminal => Uuid::from_u128(187),
+                SessionView::Structured => Uuid::from_u128(188),
+            };
+            let mut session = test_session(id, req.cwd.to_str().unwrap());
+            session.view = req.view;
+            session.command = req.command;
+            Json(session)
+        }
+
+        let router =
+            axum::Router::new().route(maestro_protocol::routes::SESSIONS, post(spawn_session));
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let base = format!("http://{}", listener.local_addr().unwrap());
+        tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });
+
+        let mut app = make_app_at(&base);
+        let request = |view| CreateSessionRequest {
+            view,
+            cwd: std::path::PathBuf::from("/srv/work"),
+            command: "codex".into(),
+            env: Default::default(),
+            metadata: Default::default(),
+            worktree: None,
+            auto_approve: false,
+        };
+
+        let structured_id = Uuid::from_u128(188);
+        app.state.mode = Mode::Insert;
+        app.submit_spawn(request(SessionView::Structured)).await;
+        assert!(app.catalog.snapshot().sessions.is_empty());
+        assert!(app.structured.contains_key(&structured_id));
+        assert!(app.emulators.get(structured_id).is_none());
+        assert_eq!(app.state.mode, Mode::Normal);
+
+        let terminal_id = Uuid::from_u128(187);
+        app.submit_spawn(request(SessionView::Terminal)).await;
+        assert!(app.catalog.snapshot().sessions.is_empty());
+        assert!(app.emulators.get(terminal_id).is_some());
+        assert!(!app.structured.contains_key(&terminal_id));
+    }
+
     /// The full data load against a live daemon stub: presets replace the
     /// built-ins, projects land sorted, and the first generated name seeds
     /// the field.
@@ -3697,4 +4064,112 @@ mod tests {
         assert!(app.command_bar.is_none());
         assert!(app.state.overlay().is_none());
     }
+
+    fn structured_app(sid: Uuid) -> App {
+        let mut app = app_with_highlighted_session(sid);
+        let mut session = app.catalog.snapshot().sessions[0].clone();
+        session.view = SessionView::Structured;
+        app.catalog
+            .apply_event(maestro_protocol::CatalogEvent::SessionUpdated { session });
+        app.structured.insert(
+            sid,
+            StructuredHandle::test_handle(crate::structured_task::StructuredState::default()),
+        );
+        app.state.attach_to_focused(sid);
+        app
+    }
+
+    #[tokio::test]
+    async fn session_view_selects_the_structured_connection_and_cleanup_stops_it() {
+        let sid = Uuid::from_u128(141);
+        let mut app = app_with_highlighted_session(sid);
+        let mut session = app.catalog.snapshot().sessions[0].clone();
+        session.view = SessionView::Structured;
+        app.catalog
+            .apply_event(maestro_protocol::CatalogEvent::SessionUpdated { session });
+
+        app.attach(sid);
+        assert!(app.structured.contains_key(&sid));
+        assert!(app.emulators.get(sid).is_none());
+        let handle = app.structured.get(&sid).unwrap().clone();
+        app.release_session(sid);
+        assert_eq!(
+            handle.connection(),
+            crate::session_task::SessionState::Ended
+        );
+    }
+
+    #[test]
+    fn structured_normal_mode_routes_navigation_expansion_and_approval_by_row() {
+        use maestro_protocol::{ReducedState, TranscriptRow, TranscriptRowKind};
+        use serde_json::json;
+
+        let sid = Uuid::from_u128(141);
+        let mut app = structured_app(sid);
+        app.dispatch(Action::AttachHighlighted);
+        assert_eq!(app.state.focus, Focus::Pane);
+        assert_eq!(app.state.mode, Mode::Normal);
+        let handle = app.structured.get(&sid).unwrap().clone();
+        {
+            let mut state = handle.state.lock().unwrap();
+            state.rows = vec![
+                TranscriptRow {
+                    id: "text".into(),
+                    kind: TranscriptRowKind::AgentText,
+                    data: json!({"content":{"type":"text","text":"hello"}}),
+                },
+                TranscriptRow {
+                    id: "approval".into(),
+                    kind: TranscriptRowKind::Approval,
+                    data: json!({"options":[{"kind":"allow_once"}]}),
+                },
+            ];
+            state.selected = Some("text".into());
+            state.reduced = ReducedState {
+                pending_approval: Some(json!({"nonce":"n"})),
+                ..ReducedState::default()
+            };
+        }
+
+        assert_eq!(
+            app.handle_structured_key(&InputKey::char('j')),
+            Some(vec![])
+        );
+        assert_eq!(
+            app.handle_structured_key(&InputKey::char('a')),
+            Some(vec![Effect::StructuredApproval {
+                id: sid,
+                nonce: "n".into(),
+                decision: StructuredApprovalDecision::AllowOnce,
+            }])
+        );
+        assert_eq!(
+            handle.state.lock().unwrap().selected.as_deref(),
+            Some("approval")
+        );
+    }
+
+    #[test]
+    fn structured_insert_mode_edits_submits_and_cancels_without_pty_bytes() {
+        let sid = Uuid::from_u128(141);
+        let mut app = structured_app(sid);
+        assert!(app.emulators.get(sid).is_none());
+        app.forward_to_session(&InputKey::char('h'));
+        app.forward_to_session(&InputKey::char('i'));
+        assert_eq!(
+            app.forward_to_session(&InputKey::Enter),
+            Some(Effect::StructuredPrompt {
+                id: sid,
+                prompt: "hi".into(),
+            })
+        );
+        assert_eq!(
+            app.handle_structured_key(&InputKey::Esc),
+            Some(vec![Effect::StructuredCancel { id: sid }])
+        );
+        assert_eq!(
+            app.forward_literal_to_terminal(&app.cfg.leader.clone()),
+            None
+        );
+    }
 }

crates/maestro-tui/src/draft.rs

@@ -41,8 +41,10 @@ use std::time::{Duration, Instant};
 
 use chrono::{DateTime, Utc};
 use maestro_config::{builtin_presets, custom_preset};
-use maestro_protocol::display::abbreviate_dir;
-use maestro_protocol::{BranchInfo, CreateSessionRequest, Project, SpawnPreset, WorktreeSpec};
+use maestro_protocol::display::{abbreviate_dir, supports_structured_view};
+use maestro_protocol::{
+    BranchInfo, CreateSessionRequest, Project, SessionView, SpawnPreset, WorktreeSpec,
+};
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
@@ -86,9 +88,11 @@ pub enum DraftField {
     /// apply immediately, mirroring the web form's per-click choice.
     WorktreeChoice,
     Name,
-    /// Disclosure collapsing the worktree/branch controls below (#93).
+    /// Disclosure collapsing the optional view and worktree controls below.
     /// Closed by default; Enter / Space toggles.
     Advanced,
+    /// ACP-backed transcript instead of a terminal. Claude Code or Codex.
+    StructuredToggle,
     /// Worktree on/off for this session (#65). Enter / Space toggles.
     WorktreeToggle,
     /// New-vs-existing branch source; Left / Right switches.
@@ -251,6 +255,14 @@ pub struct DraftPane {
     /// "Advanced options" disclosure (#93). Closed by default — most spawns
     /// take the default target.
     pub advanced_collapsed: bool,
+    /// ACP-backed structured transcript. Supported only when the resolved
+    /// command is Claude Code or Codex, and on by default whenever it is —
+    /// until the operator works the toggle themselves.
+    pub structured_view: bool,
+    /// Set once the operator toggles structured view by hand. From then on a
+    /// command change never re-enables what they turned off, the same guard
+    /// `name_touched` gives the name field.
+    pub structured_view_touched: bool,
     /// Enclosing repository of the chosen target — from the project scan for
     /// picked rows, `/api/gitroot` for raw paths. `None` until known.
     pub base_repo: Option<PathBuf>,
@@ -291,7 +303,7 @@ impl Default for DraftPane {
         // while its data loads, and stay usable when the daemon reports none.
         let mut presets = builtin_presets();
         presets.push(custom_preset());
-        Self {
+        let mut draft = Self {
             id: NEXT_DRAFT_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
             presets,
             selected_preset: 0,
@@ -311,6 +323,8 @@ impl Default for DraftPane {
             name_touched: false,
             worktree_enabled: true,
             advanced_collapsed: true,
+            structured_view: false,
+            structured_view_touched: false,
             base_repo: None,
             probed_cwd: None,
             probe_seq: 0,
@@ -329,7 +343,11 @@ impl Default for DraftPane {
             // straight away, and Tab from here reaches the command tiles.
             focused_field: DraftField::DirPicker,
             home_dir: String::new(),
-        }
+        };
+        // The built-in tile the form opens on decides whether structured view
+        // starts ticked, exactly as a later preset list would.
+        draft.sync_structured_view();
+        draft
     }
 }
 
@@ -348,6 +366,7 @@ impl DraftPane {
             .position(|p| !p.command.is_empty())
             .unwrap_or(0);
         self.apply_seed_command();
+        self.sync_structured_view();
     }
 
     /// Land a seeded command on the tile that runs it: its own preset when the
@@ -663,6 +682,28 @@ impl DraftPane {
         }
     }
 
+    fn supports_structured_view(&self) -> bool {
+        supports_structured_view(self.command())
+    }
+
+    /// Re-resolve the toggle after the command changed: an unsupported
+    /// command forces it off, a supported one turns it back on unless the
+    /// operator has already made the choice themselves.
+    fn sync_structured_view(&mut self) {
+        if !self.supports_structured_view() {
+            self.structured_view = false;
+        } else if !self.structured_view_touched {
+            self.structured_view = true;
+        }
+    }
+
+    pub fn toggle_structured_view(&mut self) {
+        if self.supports_structured_view() {
+            self.structured_view = !self.structured_view;
+            self.structured_view_touched = true;
+        }
+    }
+
     /// The chosen working directory: a picked project row, else the raw path
     /// input when it holds something.
     pub fn cwd(&self) -> Option<PathBuf> {
@@ -693,13 +734,22 @@ impl DraftPane {
             );
         }
         let worktree = self.build_worktree()?;
+        let auto_approve = self
+            .presets
+            .get(self.selected_preset)
+            .is_some_and(|p| p.auto_approve);
         Ok(CreateSessionRequest {
-            view: Default::default(),
+            view: if self.structured_view && self.supports_structured_view() {
+                SessionView::Structured
+            } else {
+                SessionView::Terminal
+            },
             cwd,
             command: command.to_string(),
             env: Default::default(),
             metadata,
             worktree,
+            auto_approve,
         })
     }
 
@@ -754,6 +804,9 @@ impl DraftPane {
         order.push(DraftField::Name);
         order.push(DraftField::Advanced);
         if !self.advanced_collapsed {
+            if self.supports_structured_view() {
+                order.push(DraftField::StructuredToggle);
+            }
             if !self.cwd_raw_visible && self.selected_group_key.is_some() {
                 order.push(DraftField::WorktreeChoice);
             }
@@ -795,6 +848,7 @@ impl DraftPane {
         }
         self.selected_preset =
             ((self.selected_preset as i32) + delta).rem_euclid(len as i32) as usize;
+        self.sync_structured_view();
     }
 
     /// Step-one boxes surviving the type-to-filter, in display order. A
@@ -1001,9 +1055,9 @@ impl DraftPane {
             // Two fields keep their own Enter instead: `DirPicker`, whose
             // highlighted row isn't the picked one until a first Enter chooses
             // it (the next Enter, now that it's active, falls through to
-            // submit); and the disclosure/toggle pair (`Advanced`,
-            // `WorktreeToggle`), which activate on Enter like a button rather
-            // than submitting, same as the web form's own `<button>` controls.
+            // submit); and the disclosure/checkbox fields, which activate on
+            // Enter like buttons rather than submitting, matching the web
+            // form controls.
             InputKey::Enter if self.focused_field == DraftField::DirPicker => {
                 let is_other_row = self.selection() >= self.visible_groups().len();
                 let choose_only =
@@ -1023,6 +1077,10 @@ impl DraftPane {
                 self.toggle_worktree();
                 DraftInputResult::Consumed
             }
+            InputKey::Enter if self.focused_field == DraftField::StructuredToggle => {
+                self.toggle_structured_view();
+                DraftInputResult::Consumed
+            }
             InputKey::Enter => DraftInputResult::Submit,
             InputKey::Char {
                 c: ' ',
@@ -1040,6 +1098,14 @@ impl DraftPane {
                 self.toggle_worktree();
                 DraftInputResult::Consumed
             }
+            InputKey::Char {
+                c: ' ',
+                ctrl: false,
+                ..
+            } if self.focused_field == DraftField::StructuredToggle => {
+                self.toggle_structured_view();
+                DraftInputResult::Consumed
+            }
             InputKey::Up if self.focused_field == DraftField::DirPicker => {
                 self.move_selection(-1);
                 DraftInputResult::Consumed
@@ -1083,7 +1149,10 @@ impl DraftPane {
             other => {
                 match self.focused_field {
                     DraftField::Preset | DraftField::Submit => {}
-                    DraftField::CustomCommand => self.custom_command.handle_key(other),
+                    DraftField::CustomCommand => {
+                        self.custom_command.handle_key(other);
+                        self.sync_structured_view();
+                    }
                     // Typing filters the list; the highlight resets to the top
                     // so a narrowed search always starts at its best match.
                     DraftField::DirPicker => {
@@ -1121,9 +1190,9 @@ impl DraftPane {
 
         let show_custom = self.is_custom();
         let show_raw = self.cwd_raw_visible;
-        // The worktree choice step, the worktree toggle and its body all stay
-        // behind the "Advanced options" disclosure (#93): collapsed hides
-        // them, regardless of what they'd otherwise show.
+        let show_structured = !self.advanced_collapsed && self.supports_structured_view();
+        // Optional view and worktree controls stay behind the "Advanced
+        // options" disclosure (#93), regardless of what they'd otherwise show.
         let show_wt_toggle = !self.advanced_collapsed;
         let show_wt_body = show_wt_toggle && self.worktree_body_visible();
         let show_wt_choice =
@@ -1142,6 +1211,7 @@ impl DraftPane {
         let fixed: u16 = 3 /* tiles + dir + name */ + 1 /* advanced header */ + 1 /* spawn */
             + u16::from(show_custom)
             + u16::from(show_raw)
+            + u16::from(show_structured)
             + u16::from(show_wt_toggle)
             + u16::from(show_wt_choice) * wt_choice_capacity
             + u16::from(show_wt_body) * (1 + if self.branch_mode == WorktreeBranchMode::New { 1 } else { branch_rows })
@@ -1161,6 +1231,9 @@ impl DraftPane {
         }
         constraints.push(Constraint::Length(1)); // name
         constraints.push(Constraint::Length(1)); // advanced header
+        if show_structured {
+            constraints.push(Constraint::Length(1));
+        }
         if show_wt_choice {
             constraints.push(Constraint::Length(wt_choice_capacity));
         }
@@ -1359,6 +1432,24 @@ impl DraftPane {
             advanced_row,
         );
 
+        if show_structured {
+            let row = next_row();
+            f.render_widget(
+                Paragraph::new(Line::from(vec![
+                    Span::raw(format!("{:<GUTTER$}", "view:")),
+                    Span::styled(
+                        if self.structured_view {
+                            "[x] structured view"
+                        } else {
+                            "[ ] structured view"
+                        },
+                        field_style(DraftField::StructuredToggle),
+                    ),
+                ])),
+                row,
+            );
+        }
+
         if show_wt_choice {
             // Step two (#96 rule 3): "+ new" first, then the repository's
             // worktrees newest-first.
@@ -1706,6 +1797,7 @@ mod tests {
             id: "aider".into(),
             label: "Aider".into(),
             command: "aider".into(),
+            auto_approve: false,
         }]);
         assert_eq!(
             draft.command(),
@@ -1728,11 +1820,13 @@ mod tests {
                 id: "claude".into(),
                 label: "Claude".into(),
                 command: "claude".into(),
+                auto_approve: false,
             },
             SpawnPreset {
                 id: "aider".into(),
                 label: "Aider".into(),
                 command: "aider".into(),
+                auto_approve: false,
             },
         ]);
         assert_eq!(draft.command(), "aider");
@@ -1752,6 +1846,7 @@ mod tests {
             id: "claude".into(),
             label: "Claude".into(),
             command: "claude".into(),
+            auto_approve: false,
         }]);
         assert!(draft.is_custom());
         assert_eq!(draft.command(), "bash -l");
@@ -1817,6 +1912,280 @@ mod tests {
         assert_eq!(req.cwd, PathBuf::from("/srv/work"));
     }
 
+    #[test]
+    fn structured_view_is_default_on_and_visible_for_supported_agents() {
+        let mut draft = DraftPane {
+            advanced_collapsed: false,
+            ..DraftPane::default()
+        };
+        draft.set_presets(vec![
+            SpawnPreset {
+                id: "claude".into(),
+                label: "Claude".into(),
+                command: "claude".into(),
+                auto_approve: false,
+            },
+            SpawnPreset {
+                id: "codex".into(),
+                label: "Codex".into(),
+                command: "codex".into(),
+                auto_approve: false,
+            },
+            SpawnPreset {
+                id: "opencode".into(),
+                label: "OpenCode".into(),
+                command: "opencode".into(),
+                auto_approve: false,
+            },
+        ]);
+        assert!(draft.structured_view, "on by default for a supported agent");
+        assert!(draft.field_order().contains(&DraftField::StructuredToggle));
+        let rendered = render_to_string(100, 24, |f| draft.render(f, f.area(), true));
+        assert!(rendered.contains("[x] structured view"), "{rendered}");
+
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "codex");
+        assert!(
+            draft.structured_view,
+            "Codex keeps the structured selection"
+        );
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "opencode");
+        assert!(
+            !draft.structured_view,
+            "a hidden value must not stay checked"
+        );
+        assert!(!draft.field_order().contains(&DraftField::StructuredToggle));
+        let rendered = render_to_string(100, 24, |f| draft.render(f, f.area(), true));
+        assert!(!rendered.contains("structured view"), "{rendered}");
+    }
+
+    #[test]
+    fn structured_view_request_is_guarded_against_a_stale_command() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            structured_view: true,
+            ..DraftPane::default()
+        };
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Structured);
+
+        draft.selected_preset = 1;
+        assert_eq!(draft.command(), "opencode");
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
+    /// A custom command typed into the free-text field, run through the same
+    /// resolver the daemon/web gate uses (`command_tool`, #199): a path, an
+    /// env prefix, or a wrapper still resolves to Claude Code or Codex, so
+    /// the toggle stays offered and the request carries `Structured`; an
+    /// unrelated program does not.
+    #[test]
+    fn structured_view_follows_command_resolution_for_custom_commands() {
+        let cases: &[(&str, bool)] = &[
+            ("claude", true),
+            ("claude --resume", true),
+            ("CLAUDE", true),
+            ("/usr/local/bin/claude -p hi", true),
+            ("./bin/claude", true),
+            ("FOO=1 BAR=2 claude", true),
+            ("npx claude-code", true),
+            ("npx --yes claude-code", true),
+            ("sudo claude", true),
+            ("sudo -u root claude", true),
+            ("env -i claude", true),
+            ("nohup claude", true),
+            ("time claude", true),
+            ("command claude", true),
+            ("pnpm --silent dlx claude-code", true),
+            ("yarn --silent dlx claude-code", true),
+            ("bun x claude-code", true),
+            ("\"/opt/my agent/claude\" --resume", true),
+            ("codex", true),
+            ("codex --full-auto", true),
+            ("CODEX=1 codex", true),
+            ("/usr/local/bin/codex exec", true),
+            ("npx codex", true),
+            ("sudo -u root codex", true),
+            ("env -i codex", true),
+            ("command codex", true),
+            ("pnpm --silent dlx codex", true),
+            ("\"/opt/my agent/codex\" exec", true),
+            ("bash", false),
+            ("opencode", false),
+            ("/usr/local/bin/bash -l", false),
+            // A package-manager wrapper without `dlx`/`x` runs a
+            // `package.json` script, not the package (#199) — must not be
+            // mistaken for a Claude launch.
+            ("pnpm claude", false),
+            ("yarn claude", false),
+            // The daemon's structured-session child, never a valid
+            // user-facing launch form (#199).
+            ("claude-code-acp", false),
+        ];
+        for &(command, supported) in cases {
+            let mut draft = DraftPane {
+                picked_cwd: Some(PathBuf::from("/srv/work")),
+                worktree_enabled: false,
+                advanced_collapsed: false,
+                ..DraftPane::default()
+            };
+            draft.selected_preset = draft.presets.len() - 1;
+            draft.custom_command = crate::text_input::TextInput::with_value(command);
+            draft.sync_structured_view();
+
+            assert_eq!(
+                draft.field_order().contains(&DraftField::StructuredToggle),
+                supported,
+                "toggle visibility for {command:?}"
+            );
+            assert_eq!(
+                draft.structured_view, supported,
+                "default selection for {command:?}"
+            );
+            let view = draft.build_request().unwrap().view;
+            assert_eq!(
+                view,
+                if supported {
+                    SessionView::Structured
+                } else {
+                    SessionView::Terminal
+                },
+                "request view for {command:?}"
+            );
+
+            draft.toggle_structured_view();
+            assert!(
+                !draft.structured_view,
+                "the toggle turns the default off for {command:?}"
+            );
+        }
+    }
+
+    /// A configured preset (the spawn-form "alias" for a command) is gated
+    /// the same way as free text: a preset whose command resolves to Claude
+    /// Code or Codex through a wrapper still offers structured view.
+    #[test]
+    fn structured_view_follows_command_resolution_for_presets() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            advanced_collapsed: false,
+            ..DraftPane::default()
+        };
+        draft.set_presets(vec![
+            SpawnPreset {
+                id: "claude-wrapped".into(),
+                label: "Claude (npx)".into(),
+                command: "npx claude-code --resume".into(),
+                auto_approve: false,
+            },
+            SpawnPreset {
+                id: "codex-wrapped".into(),
+                label: "Codex (npx)".into(),
+                command: "npx codex exec".into(),
+                auto_approve: false,
+            },
+            SpawnPreset {
+                id: "aider".into(),
+                label: "Aider".into(),
+                command: "aider".into(),
+                auto_approve: false,
+            },
+        ]);
+
+        assert_eq!(draft.command(), "npx claude-code --resume");
+        assert!(draft.field_order().contains(&DraftField::StructuredToggle));
+        assert!(draft.structured_view);
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Structured);
+
+        // Switching between supported presets preserves the selection.
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "npx codex exec");
+        assert!(draft.structured_view);
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Structured);
+
+        // Switching to a preset that does not resolve to an ACP agent clears the
+        // stale selection instead of letting an invalid request through.
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "aider");
+        assert!(!draft.structured_view, "stale selection must clear");
+        assert!(!draft.field_order().contains(&DraftField::StructuredToggle));
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
+    /// The default only applies until the operator has an opinion: once they
+    /// untick the box, moving between supported commands leaves it unticked
+    /// instead of turning it back on under them.
+    #[test]
+    fn an_unticked_structured_view_survives_a_command_change() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            advanced_collapsed: false,
+            ..DraftPane::default()
+        };
+        draft.set_presets(vec![
+            SpawnPreset {
+                id: "claude".into(),
+                label: "Claude".into(),
+                command: "claude".into(),
+                auto_approve: false,
+            },
+            SpawnPreset {
+                id: "codex".into(),
+                label: "Codex".into(),
+                command: "codex".into(),
+                auto_approve: false,
+            },
+        ]);
+        assert!(draft.structured_view);
+
+        draft.toggle_structured_view();
+        assert!(!draft.structured_view);
+
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "codex");
+        assert!(
+            !draft.structured_view,
+            "the operator's choice outranks the default"
+        );
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
+    /// Editing the custom-command text away from a supported agent clears an armed
+    /// selection immediately, matching the preset-switch case above — an
+    /// invalid `Structured` request can never reach `build_request`.
+    #[test]
+    fn structured_view_clears_when_custom_command_edited_away_from_supported_agent() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            advanced_collapsed: false,
+            focused_field: DraftField::CustomCommand,
+            ..DraftPane::default()
+        };
+        draft.selected_preset = draft.presets.len() - 1;
+        draft.custom_command = crate::text_input::TextInput::with_value("codex");
+        draft.sync_structured_view();
+        assert!(draft.structured_view);
+
+        typed(&mut draft, " -p");
+        assert_eq!(draft.command(), "codex -p");
+        assert!(draft.structured_view, "still Codex, selection survives");
+
+        for _ in 0.."codex -p".chars().count() {
+            draft.on_input(&InputKey::Backspace);
+        }
+        typed(&mut draft, "bash");
+        assert_eq!(draft.command(), "bash");
+        assert!(
+            !draft.structured_view,
+            "editing the program away from Codex clears the stale selection"
+        );
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
     #[test]
     fn projects_render_sorted_with_stale_dimmed_and_other_directory_last() {
         let mut draft = DraftPane {

crates/maestro-tui/src/fast_forward.rs

@@ -121,6 +121,7 @@ impl FastForwardDefaults {
                 branch: handle.to_string(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
     }
 
@@ -184,6 +185,7 @@ mod tests {
             id: id.into(),
             label: id.into(),
             command: command.into(),
+            auto_approve: false,
         }
     }
 

crates/maestro-tui/src/input.rs

@@ -55,6 +55,7 @@ pub enum MouseKind {
     Click,
     DblClick,
     Drag,
+    Hover,
     ScrollUp,
     ScrollDown,
 }
@@ -148,6 +149,7 @@ impl InputKey {
                     MouseKind::Click => "click",
                     MouseKind::DblClick => "dblclick",
                     MouseKind::Drag => "drag",
+                    MouseKind::Hover => "hover",
                     MouseKind::ScrollUp => "scrollup",
                     MouseKind::ScrollDown => "scrolldown",
                 };
@@ -178,6 +180,7 @@ impl InputKey {
                 "click" => MouseKind::Click,
                 "dblclick" => MouseKind::DblClick,
                 "drag" => MouseKind::Drag,
+                "hover" => MouseKind::Hover,
                 "scrollup" => MouseKind::ScrollUp,
                 "scrolldown" => MouseKind::ScrollDown,
                 other => return Err(InputParseError::UnknownMouseKind(other.into())),
@@ -297,6 +300,7 @@ where
             let mk = match kind {
                 MouseEventKind::Down(MouseButton::Left) => MouseKind::Click,
                 MouseEventKind::Drag(MouseButton::Left) => MouseKind::Drag,
+                MouseEventKind::Moved => MouseKind::Hover,
                 MouseEventKind::ScrollUp => MouseKind::ScrollUp,
                 MouseEventKind::ScrollDown => MouseKind::ScrollDown,
                 _ => return None,
@@ -681,6 +685,9 @@ mod tests {
         let s = "mouse:dblclick(sidebar-row)";
         let k = InputKey::parse(s).unwrap();
         assert_eq!(k.canonical(), s);
+        let s = "mouse:hover(pane)";
+        let k = InputKey::parse(s).unwrap();
+        assert_eq!(k.canonical(), s);
     }
 
     #[test]

crates/maestro-tui/src/lib.rs

@@ -23,6 +23,8 @@ pub mod render;
 pub mod session_task;
 pub mod sidebar;
 pub mod state;
+pub mod structured_pane;
+pub mod structured_task;
 pub mod terminal;
 pub mod text_input;
 

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

@@ -18,6 +18,7 @@ use crate::palette;
 use crate::pane::Pane;
 use crate::sidebar::Sidebar;
 use crate::state::{AppState, Focus, OverlayKind, SidebarItem};
+use crate::structured_pane::StructuredPane;
 
 /// Tagged regions for mouse hit-testing. The input router resolves a mouse
 /// coordinate to one of these via [`RegionMap::region_at`].
@@ -80,6 +81,7 @@ pub struct RenderInputs<'a> {
     pub home_dir: &'a str,
     pub pane_title: &'a str,
     pub pane: Option<&'a Pane>,
+    pub structured_pane: Option<&'a StructuredPane>,
     /// The spawn form behind [`OverlayKind::Spawn`], when one is up.
     pub draft: Option<&'a crate::draft::DraftPane>,
     pub state: &'a AppState,
@@ -147,14 +149,22 @@ pub fn draw(f: &mut Frame, inputs: RenderInputs<'_>) -> RegionMap {
     render_title_bar(f, title_area, inputs.pane_title, pane_focused);
     if let Some(p) = inputs.pane {
         p.render(f, pane_area);
+    } else if let Some(p) = inputs.structured_pane {
+        p.render(f, pane_area);
     }
     // `RegionMap::pane` is also the PTY resize source. The title bar is
-    // chrome; every remaining cell belongs to the emulator.
+    // chrome; every remaining cell belongs to the active session pane.
     map.pane = Some(pane_area);
 
     // Status bar — always visible, never eclipsed by overlays so the user can
     // always see the current mode + key hints.
-    render_status_bar(f, status_area, inputs.state, inputs.link);
+    render_status_bar(
+        f,
+        status_area,
+        inputs.state,
+        inputs.link,
+        inputs.structured_pane.is_some(),
+    );
 
     match inputs.state.overlay() {
         Some(OverlayKind::Spawn) => {
@@ -253,7 +263,13 @@ fn render_title_bar(f: &mut Frame, area: Rect, title: &str, focused: bool) {
 /// Render the always-visible status bar at the bottom of the frame. Surfaces
 /// mode + focused panel + the most useful key hints so the user is never
 /// guessing what state they're in.
-fn render_status_bar(f: &mut Frame, area: Rect, state: &AppState, link: &LinkStatus) {
+fn render_status_bar(
+    f: &mut Frame,
+    area: Rect,
+    state: &AppState,
+    link: &LinkStatus,
+    structured: bool,
+) {
     // The daemon indicator is pinned right and sized to its own text, so a
     // narrow terminal truncates the key hints rather than the release.
     let label = link_label(link);
@@ -271,9 +287,13 @@ fn render_status_bar(f: &mut Frame, area: Rect, state: &AppState, link: &LinkSta
         Focus::Sidebar => "sidebar",
         Focus::Pane => "pane",
     };
-    let hint = match state.mode {
-        Mode::Normal => "j/k: nav  •  enter: attach  •  s: spawn  •  ?: help  •  ^Wq: quit",
-        Mode::Insert => "^a: return to sidebar",
+    let hint = match (structured && state.focus == Focus::Pane, state.mode) {
+        (true, Mode::Normal) => "j/k: rows  •  enter: expand  •  i: compose  •  esc: cancel",
+        (true, Mode::Insert) => "enter: send  •  esc: cancel  •  ^a: sidebar",
+        (false, Mode::Normal) => {
+            "j/k: nav  •  enter: attach  •  s: spawn  •  ?: help  •  ^Wq: quit"
+        }
+        (false, Mode::Insert) => "^a: return to sidebar",
     };
     let mode_style = palette::active().mode_style(state.mode == Mode::Insert);
     let line = ratatui::text::Line::from(vec![
@@ -435,6 +455,7 @@ mod tests {
             home_dir: "",
             pane_title: "session",
             pane: None,
+            structured_pane: None,
             draft: None,
             state: &state,
             help: &help,
@@ -532,6 +553,7 @@ mod tests {
             home_dir: "",
             pane_title: "session",
             pane: None,
+            structured_pane: None,
             draft: Some(&draft),
             state: &state,
             help: &help,
@@ -587,6 +609,7 @@ mod tests {
                 home_dir: "",
                 pane_title: "session",
                 pane: None,
+                structured_pane: None,
                 draft: None,
                 state: &state,
                 help: &help,
@@ -629,6 +652,7 @@ mod tests {
                 home_dir: "",
                 pane_title: "session",
                 pane: None,
+                structured_pane: None,
                 draft: None,
                 state: &state,
                 help: &help,

crates/maestro-tui/src/session_task.rs

@@ -221,7 +221,7 @@ impl SessionTask {
     }
 }
 
-fn jitter(base: Duration) -> Duration {
+pub(crate) fn jitter(base: Duration) -> Duration {
     let ms = base.as_millis() as u64;
     let now_nanos = std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)

crates/maestro-tui/src/sidebar.rs

@@ -979,6 +979,7 @@ mod tests {
         for state in [
             ActivityState::Active,
             ActivityState::Idle,
+            ActivityState::Starting,
             ActivityState::AwaitingInput,
             ActivityState::Error,
         ] {
@@ -1009,6 +1010,7 @@ mod tests {
         for state in [
             ActivityState::Active,
             ActivityState::Idle,
+            ActivityState::Starting,
             ActivityState::AwaitingInput,
             ActivityState::Error,
         ] {

crates/maestro-tui/src/structured_task.rs

@@ -0,0 +1,773 @@
+//! Live projection state for one structured session.
+
+use std::collections::HashSet;
+use std::sync::atomic::{AtomicU64, AtomicU8, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use futures_util::StreamExt;
+use maestro_protocol::{
+    ReducedState, StructuredApprovalDecision, StructuredEvent, TranscriptDelta, TranscriptRow,
+    TranscriptRowKind,
+};
+use tokio::sync::watch;
+use tokio_tungstenite::tungstenite::{Error as WsError, Message};
+
+use crate::input::InputKey;
+use crate::session_task::SessionState;
+use crate::text_input::TextInput;
+
+/// Renderer and input state built directly from the daemon's two projections.
+#[derive(Debug, Clone)]
+pub struct StructuredState {
+    pub rows: Vec<TranscriptRow>,
+    pub reduced: ReducedState,
+    pub selected: Option<String>,
+    pub expanded: HashSet<String>,
+    pub scroll: usize,
+    /// Row id per rendered line from the last render pass, parallel to that
+    /// pass's `lines`. Lets the next render translate `scroll` — a raw index
+    /// into that now-stale layout — back into a row identity before mapping
+    /// it onto the freshly rebuilt layout, so growth/shrinkage above the
+    /// viewport shifts indices without shifting what's on screen.
+    pub(crate) line_rows: Vec<Option<String>>,
+    pub follow_selection: bool,
+    pub composer: TextInput,
+    pub error: Option<String>,
+    submitting: bool,
+    submission_generation: u64,
+    reconcile_submission_on_snapshot: Option<u64>,
+    approval_submitting: bool,
+}
+
+impl Default for StructuredState {
+    fn default() -> Self {
+        Self {
+            rows: Vec::new(),
+            reduced: ReducedState::default(),
+            selected: None,
+            expanded: HashSet::new(),
+            scroll: 0,
+            line_rows: Vec::new(),
+            follow_selection: true,
+            composer: TextInput::default(),
+            error: None,
+            submitting: false,
+            submission_generation: 0,
+            reconcile_submission_on_snapshot: None,
+            approval_submitting: false,
+        }
+    }
+}
+
+impl StructuredState {
+    pub fn apply(&mut self, event: StructuredEvent) {
+        match event {
+            StructuredEvent::TranscriptSnapshot { snapshot } => {
+                let selected = self.selected.clone();
+                self.rows = snapshot.rows;
+                self.selected = selected
+                    .filter(|id| self.rows.iter().any(|row| &row.id == id))
+                    .or_else(|| {
+                        self.rows
+                            .iter()
+                            .rev()
+                            .find(|row| row.kind != TranscriptRowKind::Plan)
+                            .map(|row| row.id.clone())
+                    });
+                self.expanded
+                    .retain(|id| self.rows.iter().any(|row| &row.id == id));
+            }
+            StructuredEvent::ReducedState { state } => {
+                let reconcile_submission = self
+                    .reconcile_submission_on_snapshot
+                    .take()
+                    .is_some_and(|generation| {
+                        self.submitting && generation == self.submission_generation
+                    });
+                self.apply_reduced(state, reconcile_submission);
+            }
+            StructuredEvent::ProjectionUpdate { transcript, state } => {
+                if let Some(delta) = transcript {
+                    self.apply_delta(delta);
+                }
+                self.apply_reduced(state, false);
+            }
+        }
+    }
+
+    fn apply_delta(&mut self, delta: TranscriptDelta) {
+        match delta {
+            TranscriptDelta::Append { row } => {
+                let followed_tail = self.follow_selection
+                    && self.selected.as_ref().is_some_and(|id| {
+                        self.rows
+                            .iter()
+                            .rev()
+                            .find(|old| old.kind != TranscriptRowKind::Plan)
+                            .is_some_and(|old| &old.id == id)
+                    });
+                if let Some(index) = self.rows.iter().position(|old| old.id == row.id) {
+                    self.rows[index] = row.clone();
+                } else {
+                    self.rows.push(row.clone());
+                }
+                if row.kind != TranscriptRowKind::Plan && (self.selected.is_none() || followed_tail)
+                {
+                    self.selected = Some(row.id);
+                }
+            }
+            TranscriptDelta::Patch { row } => {
+                if let Some(index) = self.rows.iter().position(|old| old.id == row.id) {
+                    self.rows[index] = row.clone();
+                } else {
+                    self.rows.push(row.clone());
+                }
+            }
+            TranscriptDelta::Remove { id } => {
+                let removed = self.rows.iter().position(|row| row.id == id);
+                self.rows.retain(|row| row.id != id);
+                self.expanded.remove(&id);
+                if self.selected.as_deref() == Some(&id) {
+                    self.selected = removed.and_then(|index| {
+                        let split = index.min(self.rows.len());
+                        self.rows[split..]
+                            .iter()
+                            .find(|row| row.kind != TranscriptRowKind::Plan)
+                            .or_else(|| {
+                                self.rows[..split]
+                                    .iter()
+                                    .rev()
+                                    .find(|row| row.kind != TranscriptRowKind::Plan)
+                            })
+                            .map(|row| row.id.clone())
+                    });
+                }
+            }
+        }
+    }
+
+    fn apply_reduced(&mut self, state: ReducedState, reconcile_submission: bool) {
+        let previous_nonce = self.pending_nonce().map(str::to_owned);
+        if reconcile_submission || state.turn.responding || state.turn.thinking {
+            self.submitting = false;
+        }
+        self.reduced = state;
+        let next_nonce = self.pending_nonce().map(str::to_owned);
+        if next_nonce != previous_nonce {
+            self.approval_submitting = false;
+            if next_nonce.is_some() {
+                self.selected = self
+                    .rows
+                    .iter()
+                    .rev()
+                    .find(|row| row.kind == TranscriptRowKind::Approval)
+                    .map(|row| row.id.clone());
+                self.follow_selection = true;
+            }
+        }
+    }
+
+    fn prepare_snapshot_reconciliation(&mut self) {
+        self.reconcile_submission_on_snapshot =
+            self.submitting.then_some(self.submission_generation);
+    }
+
+    pub fn select(&mut self, delta: isize) {
+        let selectable: Vec<&TranscriptRow> = self
+            .rows
+            .iter()
+            .filter(|row| row.kind != TranscriptRowKind::Plan)
+            .collect();
+        if selectable.is_empty() {
+            self.selected = None;
+            return;
+        }
+        let current = self
+            .selected
+            .as_ref()
+            .and_then(|id| selectable.iter().position(|row| &row.id == id))
+            .unwrap_or(selectable.len() - 1);
+        let next = if delta >= 0 {
+            current
+                .saturating_add(delta as usize)
+                .min(selectable.len() - 1)
+        } else {
+            current.saturating_sub(delta.unsigned_abs())
+        };
+        self.selected = Some(selectable[next].id.clone());
+        self.follow_selection = true;
+    }
+
+    /// Select the transcript block under a rendered transcript line. Pointer
+    /// input uses the same row identity map as scroll reconciliation, so a
+    /// wrapped block behaves as one target.
+    pub fn select_rendered_line(&mut self, line: usize) -> bool {
+        let Some(id) = self.line_rows.get(line).and_then(Clone::clone) else {
+            return false;
+        };
+        self.selected = Some(id);
+        self.follow_selection = false;
+        true
+    }
+
+    pub fn toggle_selected(&mut self) {
+        let Some(id) = self.selected.clone() else {
+            return;
+        };
+        let expandable = self.rows.iter().any(|row| {
+            row.id == id
+                && matches!(
+                    row.kind,
+                    TranscriptRowKind::ToolCall | TranscriptRowKind::ToolDiff
+                )
+        });
+        if !expandable {
+            return;
+        }
+        if !self.expanded.insert(id.clone()) {
+            self.expanded.remove(&id);
+        }
+        self.follow_selection = true;
+    }
+
+    pub fn scroll_by(&mut self, lines: isize) {
+        self.scroll = if lines >= 0 {
+            self.scroll.saturating_sub(lines as usize)
+        } else {
+            self.scroll.saturating_add(lines.unsigned_abs())
+        };
+        self.follow_selection = false;
+    }
+
+    pub fn edit_composer(&mut self, key: &InputKey) {
+        if !self.turn_active() {
+            self.composer.handle_key(key);
+            self.error = None;
+        }
+    }
+
+    pub fn begin_prompt(&mut self) -> Option<String> {
+        if self.turn_active() || self.composer.value().trim().is_empty() {
+            return None;
+        }
+        let prompt = self.composer.value().to_string();
+        self.composer = TextInput::default();
+        self.submission_generation = self.submission_generation.wrapping_add(1);
+        self.submitting = true;
+        self.error = None;
+        Some(prompt)
+    }
+
+    pub fn prompt_failed(&mut self, prompt: String, error: String) {
+        if self.composer.value().is_empty() {
+            self.composer = TextInput::with_value(prompt);
+        }
+        self.submitting = false;
+        self.error = Some(error);
+    }
+
+    pub fn turn_active(&self) -> bool {
+        self.submitting || self.reduced.turn.responding || self.reduced.turn.thinking
+    }
+
+    pub fn pending_nonce(&self) -> Option<&str> {
+        self.reduced
+            .pending_approval
+            .as_ref()?
+            .get("nonce")?
+            .as_str()
+    }
+
+    pub fn approval_decision(&mut self, key: char) -> Option<(String, StructuredApprovalDecision)> {
+        if self.approval_submitting {
+            return None;
+        }
+        let selected = self.selected.as_deref()?;
+        let pending_row = self
+            .rows
+            .iter()
+            .rev()
+            .find(|row| row.kind == TranscriptRowKind::Approval)?;
+        if pending_row.id != selected {
+            return None;
+        }
+        let decision = match key {
+            'a' => StructuredApprovalDecision::AllowOnce,
+            'A' => StructuredApprovalDecision::AllowForSession,
+            'd' => StructuredApprovalDecision::Deny,
+            _ => return None,
+        };
+        let offered = offered_decisions(&pending_row.data);
+        if !offered.contains(&decision) {
+            return None;
+        }
+        let nonce = self.pending_nonce()?.to_string();
+        self.approval_submitting = true;
+        self.error = None;
+        Some((nonce, decision))
+    }
+
+    pub fn approval_failed(&mut self, nonce: &str, error: String) {
+        if self.pending_nonce() != Some(nonce) {
+            return;
+        }
+        self.approval_submitting = false;
+        self.error = Some(error);
+    }
+}
+
+pub fn offered_decisions(data: &serde_json::Value) -> Vec<StructuredApprovalDecision> {
+    let mut out = Vec::new();
+    for kind in data
+        .get("options")
+        .and_then(serde_json::Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(|option| option.get("kind").and_then(serde_json::Value::as_str))
+    {
+        match kind {
+            "allow_once" if !out.contains(&StructuredApprovalDecision::AllowOnce) => {
+                out.push(StructuredApprovalDecision::AllowOnce)
+            }
+            "allow_always" if !out.contains(&StructuredApprovalDecision::AllowForSession) => {
+                out.push(StructuredApprovalDecision::AllowForSession)
+            }
+            "reject_once" | "reject_always" if !out.contains(&StructuredApprovalDecision::Deny) => {
+                out.push(StructuredApprovalDecision::Deny)
+            }
+            _ => {}
+        }
+    }
+    out
+}
+
+/// Cheap shared handle for a structured projection connection.
+#[derive(Clone)]
+pub struct StructuredHandle {
+    pub state: Arc<Mutex<StructuredState>>,
+    connection: Arc<AtomicU8>,
+    revision: Arc<AtomicU64>,
+    stop: watch::Sender<bool>,
+}
+
+impl std::fmt::Debug for StructuredHandle {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StructuredHandle")
+            .field("connection", &self.connection())
+            .field("revision", &self.revision())
+            .finish_non_exhaustive()
+    }
+}
+
+impl StructuredHandle {
+    pub fn connection(&self) -> SessionState {
+        match self.connection.load(Ordering::Acquire) {
+            0 => SessionState::Connecting,
+            1 => SessionState::Live,
+            2 => SessionState::Reconnecting,
+            _ => SessionState::Ended,
+        }
+    }
+
+    pub fn revision(&self) -> u64 {
+        self.revision.load(Ordering::Acquire)
+    }
+
+    pub fn end(&self) {
+        self.connection
+            .store(SessionState::Ended as u8, Ordering::Release);
+        let _ = self.stop.send(true);
+    }
+
+    #[cfg(test)]
+    pub(crate) fn test_handle(state: StructuredState) -> Self {
+        let (stop, _) = watch::channel(false);
+        Self {
+            state: Arc::new(Mutex::new(state)),
+            connection: Arc::new(AtomicU8::new(SessionState::Live as u8)),
+            revision: Arc::new(AtomicU64::new(0)),
+            stop,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct StructuredTask;
+
+impl StructuredTask {
+    pub fn spawn(ws_url: String) -> StructuredHandle {
+        let state = Arc::new(Mutex::new(StructuredState::default()));
+        let connection = Arc::new(AtomicU8::new(SessionState::Connecting as u8));
+        let revision = Arc::new(AtomicU64::new(0));
+        let (stop, mut stopped) = watch::channel(false);
+        let handle = StructuredHandle {
+            state: state.clone(),
+            connection: connection.clone(),
+            revision: revision.clone(),
+            stop,
+        };
+
+        tokio::spawn(async move {
+            let mut backoff = Duration::from_secs(1);
+            loop {
+                if *stopped.borrow() {
+                    return;
+                }
+                state
+                    .lock()
+                    .expect("structured state mutex")
+                    .prepare_snapshot_reconciliation();
+                connection.store(SessionState::Connecting as u8, Ordering::Release);
+                let connected = tokio::select! {
+                    result = tokio_tungstenite::connect_async(&ws_url) => result,
+                    _ = stopped.changed() => return,
+                };
+                let (mut ws, _) = match connected {
+                    Ok(value) => value,
+                    Err(error) => {
+                        if terminal_handshake_error(&error) {
+                            state.lock().expect("structured state mutex").error =
+                                Some(format!("cannot open structured session: {error}"));
+                            connection.store(SessionState::Ended as u8, Ordering::Release);
+                            revision.fetch_add(1, Ordering::Release);
+                            return;
+                        }
+                        connection.store(SessionState::Reconnecting as u8, Ordering::Release);
+                        revision.fetch_add(1, Ordering::Release);
+                        tokio::select! {
+                            _ = tokio::time::sleep(super::session_task::jitter(backoff)) => {},
+                            _ = stopped.changed() => return,
+                        }
+                        backoff = backoff.saturating_mul(2).min(Duration::from_secs(30));
+                        continue;
+                    }
+                };
+                backoff = Duration::from_secs(1);
+                connection.store(SessionState::Live as u8, Ordering::Release);
+                revision.fetch_add(1, Ordering::Release);
+
+                loop {
+                    let frame = tokio::select! {
+                        frame = ws.next() => frame,
+                        _ = stopped.changed() => return,
+                    };
+                    match frame {
+                        Some(Ok(Message::Text(text))) => {
+                            if let Ok(event) = serde_json::from_str::<StructuredEvent>(&text) {
+                                state.lock().expect("structured state mutex").apply(event);
+                                revision.fetch_add(1, Ordering::Release);
+                            }
+                        }
+                        Some(Ok(Message::Close(_))) | None | Some(Err(_)) => break,
+                        _ => {}
+                    }
+                }
+                connection.store(SessionState::Reconnecting as u8, Ordering::Release);
+                revision.fetch_add(1, Ordering::Release);
+                tokio::select! {
+                    _ = tokio::time::sleep(super::session_task::jitter(backoff)) => {},
+                    _ = stopped.changed() => return,
+                }
+                backoff = backoff.saturating_mul(2).min(Duration::from_secs(30));
+            }
+        });
+        handle
+    }
+}
+
+fn terminal_handshake_error(error: &WsError) -> bool {
+    matches!(error, WsError::Http(response) if response.status().is_client_error())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use maestro_protocol::{TranscriptSnapshot, TurnState};
+    use serde_json::json;
+
+    fn row(id: &str, kind: TranscriptRowKind, data: serde_json::Value) -> TranscriptRow {
+        TranscriptRow {
+            id: id.into(),
+            kind,
+            data,
+        }
+    }
+
+    #[test]
+    fn snapshots_replace_and_deltas_address_rows_by_id() {
+        let mut state = StructuredState::default();
+        state.apply(StructuredEvent::TranscriptSnapshot {
+            snapshot: TranscriptSnapshot {
+                cursor: 2,
+                rows: vec![row("a", TranscriptRowKind::AgentText, json!({}))],
+            },
+        });
+        state.apply(StructuredEvent::ProjectionUpdate {
+            transcript: Some(TranscriptDelta::Patch {
+                row: row("a", TranscriptRowKind::AgentText, json!({"n": 2})),
+            }),
+            state: ReducedState::default(),
+        });
+        state.apply(StructuredEvent::ProjectionUpdate {
+            transcript: Some(TranscriptDelta::Append {
+                row: row("b", TranscriptRowKind::Notice, json!({})),
+            }),
+            state: ReducedState::default(),
+        });
+        assert_eq!(state.rows.len(), 2);
+        assert_eq!(state.rows[0].data["n"], 2);
+
+        state.apply(StructuredEvent::TranscriptSnapshot {
+            snapshot: TranscriptSnapshot {
+                cursor: 5,
+                rows: vec![row("b", TranscriptRowKind::Notice, json!({"fresh": true}))],
+            },
+        });
+        assert_eq!(state.rows.len(), 1);
+        assert_eq!(state.rows[0].data["fresh"], true);
+    }
+
+    #[test]
+    fn selection_survives_patch_and_moves_after_remove() {
+        let mut state = StructuredState {
+            rows: vec![
+                row("a", TranscriptRowKind::Notice, json!({})),
+                row("b", TranscriptRowKind::ToolCall, json!({})),
+                row("plan", TranscriptRowKind::Plan, json!({})),
+            ],
+            selected: Some("a".into()),
+            ..StructuredState::default()
+        };
+        state.select(1);
+        assert_eq!(state.selected.as_deref(), Some("b"));
+        state.toggle_selected();
+        assert!(state.expanded.contains("b"));
+        state.apply_delta(TranscriptDelta::Remove { id: "b".into() });
+        assert_eq!(state.selected.as_deref(), Some("a"));
+
+        state.apply_delta(TranscriptDelta::Remove { id: "a".into() });
+        assert_eq!(
+            state.selected, None,
+            "collapsed plan rows are not selectable"
+        );
+    }
+
+    #[test]
+    fn approval_keys_only_offer_server_backed_decisions() {
+        let mut state = StructuredState::default();
+        state.rows.push(row(
+            "approval:1",
+            TranscriptRowKind::Approval,
+            json!({"options":[
+                {"kind":"allow_once"}, {"kind":"reject_always"}
+            ]}),
+        ));
+        state.selected = Some("approval:1".into());
+        state.reduced.pending_approval = Some(json!({"nonce":"secret"}));
+        assert_eq!(
+            state.approval_decision('A'),
+            None,
+            "allow-for-session was not offered"
+        );
+        assert_eq!(
+            state.approval_decision('a'),
+            Some(("secret".into(), StructuredApprovalDecision::AllowOnce))
+        );
+    }
+
+    #[test]
+    fn resolved_approval_ignores_its_late_failure() {
+        let mut state = StructuredState::default();
+        state.rows.push(row(
+            "approval:1",
+            TranscriptRowKind::Approval,
+            json!({"options":[{"kind":"allow_once"}]}),
+        ));
+        state.selected = Some("approval:1".into());
+        state.reduced.pending_approval = Some(json!({"nonce":"old"}));
+        assert!(state.approval_decision('a').is_some());
+
+        state.apply(StructuredEvent::ProjectionUpdate {
+            transcript: None,
+            state: ReducedState::default(),
+        });
+        state.approval_failed("old", "response lost".into());
+
+        assert_eq!(state.error, None);
+        assert!(!state.approval_submitting);
+    }
+
+    #[test]
+    fn superseded_approval_ignores_its_late_failure() {
+        let mut state = StructuredState::default();
+        state.rows.push(row(
+            "approval:1",
+            TranscriptRowKind::Approval,
+            json!({"options":[{"kind":"allow_once"}]}),
+        ));
+        state.selected = Some("approval:1".into());
+        state.reduced.pending_approval = Some(json!({"nonce":"old"}));
+        assert!(state.approval_decision('a').is_some());
+
+        state.rows.push(row(
+            "approval:2",
+            TranscriptRowKind::Approval,
+            json!({"options":[{"kind":"allow_once"}]}),
+        ));
+        state.apply(StructuredEvent::ProjectionUpdate {
+            transcript: None,
+            state: ReducedState {
+                pending_approval: Some(json!({"nonce":"new"})),
+                ..ReducedState::default()
+            },
+        });
+        assert_eq!(
+            state.approval_decision('a'),
+            Some(("new".into(), StructuredApprovalDecision::AllowOnce))
+        );
+
+        state.approval_failed("old", "response lost".into());
+
+        assert_eq!(state.error, None);
+        assert!(state.approval_submitting);
+    }
+
+    #[test]
+    fn matching_approval_surfaces_its_failure() {
+        let mut state = StructuredState::default();
+        state.rows.push(row(
+            "approval:1",
+            TranscriptRowKind::Approval,
+            json!({"options":[{"kind":"allow_once"}]}),
+        ));
+        state.selected = Some("approval:1".into());
+        state.reduced.pending_approval = Some(json!({"nonce":"current"}));
+        assert!(state.approval_decision('a').is_some());
+
+        state.approval_failed("current", "request failed".into());
+
+        assert_eq!(state.error.as_deref(), Some("request failed"));
+        assert!(!state.approval_submitting);
+    }
+
+    #[test]
+    fn composer_is_gated_by_the_projected_turn_lifecycle() {
+        let mut state = StructuredState::default();
+        state.edit_composer(&InputKey::char('h'));
+        state.edit_composer(&InputKey::char('i'));
+        assert_eq!(state.begin_prompt().as_deref(), Some("hi"));
+        assert!(state.turn_active());
+        state.prompt_failed("hi".into(), "nope".into());
+        assert_eq!(state.composer.value(), "hi");
+
+        state.reduced.turn = TurnState {
+            responding: true,
+            ..TurnState::default()
+        };
+        state.edit_composer(&InputKey::char('x'));
+        assert_eq!(state.composer.value(), "hi");
+    }
+
+    #[test]
+    fn selecting_a_rendered_line_selects_its_whole_block() {
+        let mut state = StructuredState {
+            line_rows: vec![
+                Some("one".into()),
+                Some("one".into()),
+                None,
+                Some("two".into()),
+            ],
+            ..Default::default()
+        };
+
+        assert!(state.select_rendered_line(1));
+        assert_eq!(state.selected.as_deref(), Some("one"));
+        assert!(!state.follow_selection);
+        assert!(!state.select_rendered_line(2));
+        assert_eq!(state.selected.as_deref(), Some("one"));
+    }
+
+    #[test]
+    fn authoritative_idle_snapshot_reconciles_a_wholly_missed_turn() {
+        let mut state = StructuredState::default();
+        state.edit_composer(&InputKey::char('h'));
+        state.edit_composer(&InputKey::char('i'));
+        assert_eq!(state.begin_prompt().as_deref(), Some("hi"));
+
+        state.apply(StructuredEvent::ProjectionUpdate {
+            transcript: None,
+            state: ReducedState::default(),
+        });
+        assert!(
+            state.turn_active(),
+            "an ordinary idle update must not reopen the composer before turn begin"
+        );
+
+        state.prepare_snapshot_reconciliation();
+        state.apply(StructuredEvent::TranscriptSnapshot {
+            snapshot: TranscriptSnapshot {
+                cursor: 0,
+                rows: Vec::new(),
+            },
+        });
+        state.apply(StructuredEvent::ReducedState {
+            state: ReducedState::default(),
+        });
+        assert!(
+            !state.turn_active(),
+            "a reconnect snapshot must settle a submission whose whole turn was missed"
+        );
+    }
+
+    #[test]
+    fn stale_handshake_state_does_not_settle_a_new_submission() {
+        let mut state = StructuredState::default();
+        state.prepare_snapshot_reconciliation();
+        state.apply(StructuredEvent::TranscriptSnapshot {
+            snapshot: TranscriptSnapshot {
+                cursor: 0,
+                rows: Vec::new(),
+            },
+        });
+
+        state.edit_composer(&InputKey::char('h'));
+        state.edit_composer(&InputKey::char('i'));
+        assert_eq!(state.begin_prompt().as_deref(), Some("hi"));
+        state.apply(StructuredEvent::ReducedState {
+            state: ReducedState::default(),
+        });
+
+        assert!(
+            state.turn_active(),
+            "state captured before this submission must not reopen the composer"
+        );
+    }
+
+    #[test]
+    fn failed_submission_reconciliation_does_not_settle_its_successor() {
+        let mut state = StructuredState::default();
+        state.edit_composer(&InputKey::char('a'));
+        assert_eq!(state.begin_prompt().as_deref(), Some("a"));
+        state.prepare_snapshot_reconciliation();
+
+        state.prompt_failed("a".into(), "nope".into());
+        state.composer = TextInput::with_value("b");
+        assert_eq!(state.begin_prompt().as_deref(), Some("b"));
+
+        state.apply(StructuredEvent::TranscriptSnapshot {
+            snapshot: TranscriptSnapshot {
+                cursor: 0,
+                rows: Vec::new(),
+            },
+        });
+        state.apply(StructuredEvent::ReducedState {
+            state: ReducedState::default(),
+        });
+
+        assert!(
+            state.turn_active(),
+            "a reconnect for the failed submission must not settle its successor"
+        );
+    }
+}

crates/maestro-tui/tests/structured_http.rs

@@ -0,0 +1,79 @@
+//! The TUI's structured actions use the shared typed daemon client; assert the
+//! exact route and bare approval decision body at the HTTP boundary.
+
+use std::sync::{Arc, Mutex};
+
+use axum::extract::{Path, State};
+use axum::routing::post;
+use axum::{Json, Router};
+use maestro_protocol::{DaemonClient, StructuredApprovalDecision, StructuredPromptRequest};
+use uuid::Uuid;
+
+#[derive(Debug, Default)]
+struct Seen {
+    prompt: Option<String>,
+    cancelled: bool,
+    approval: Option<(String, StructuredApprovalDecision)>,
+}
+
+type Shared = Arc<Mutex<Seen>>;
+
+async fn prompt(
+    State(seen): State<Shared>,
+    Path(_id): Path<Uuid>,
+    Json(body): Json<StructuredPromptRequest>,
+) {
+    seen.lock().unwrap().prompt = Some(body.prompt);
+}
+
+async fn cancel(State(seen): State<Shared>, Path(_id): Path<Uuid>) {
+    seen.lock().unwrap().cancelled = true;
+}
+
+async fn approval(
+    State(seen): State<Shared>,
+    Path((_id, nonce)): Path<(Uuid, String)>,
+    Json(decision): Json<StructuredApprovalDecision>,
+) {
+    seen.lock().unwrap().approval = Some((nonce, decision));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn prompt_cancel_and_approval_use_structured_api_contract() {
+    let seen = Shared::default();
+    let app = Router::new()
+        .route("/api/sessions/:id/structured/prompt", post(prompt))
+        .route("/api/sessions/:id/structured/cancel", post(cancel))
+        .route(
+            "/api/sessions/:id/structured/approvals/:nonce",
+            post(approval),
+        )
+        .with_state(seen.clone());
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+    let client = DaemonClient::new(format!("http://{addr}"));
+    let id = Uuid::from_u128(141);
+    client.send_structured_prompt(id, "ship it").await.unwrap();
+    client.cancel_structured_turn(id).await.unwrap();
+    client
+        .resolve_structured_approval(
+            id,
+            "one-use-nonce",
+            StructuredApprovalDecision::AllowForSession,
+        )
+        .await
+        .unwrap();
+
+    let seen = seen.lock().unwrap();
+    assert_eq!(seen.prompt.as_deref(), Some("ship it"));
+    assert!(seen.cancelled);
+    assert_eq!(
+        seen.approval,
+        Some((
+            "one-use-nonce".into(),
+            StructuredApprovalDecision::AllowForSession
+        ))
+    );
+}

crates/maestro-tui/tests/structured_task_ws.rs

@@ -0,0 +1,107 @@
+//! Projection socket coverage: snapshots replace state on reconnect and live
+//! deltas patch rows without client-side event folding.
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use axum::extract::ws::{Message, WebSocketUpgrade};
+use axum::extract::State;
+use axum::response::Response;
+use axum::routing::any;
+use axum::Router;
+use maestro_protocol::{
+    ReducedState, StructuredEvent, TranscriptDelta, TranscriptRow, TranscriptRowKind,
+    TranscriptSnapshot,
+};
+use maestro_tui::session_task::SessionState;
+use maestro_tui::structured_task::StructuredTask;
+use serde_json::json;
+
+async fn structured_handler(
+    State(connects): State<Arc<AtomicUsize>>,
+    ws: WebSocketUpgrade,
+) -> Response {
+    ws.on_upgrade(move |mut socket| async move {
+        let attempt = connects.fetch_add(1, Ordering::SeqCst);
+        let snapshot = if attempt == 0 {
+            TranscriptSnapshot {
+                cursor: 1,
+                rows: vec![row("old", json!({"content":{"type":"text","text":"old"}}))],
+            }
+        } else {
+            TranscriptSnapshot {
+                cursor: 3,
+                rows: vec![row("live", json!({"content":{"type":"text","text":"one"}}))],
+            }
+        };
+        send(
+            &mut socket,
+            StructuredEvent::TranscriptSnapshot { snapshot },
+        )
+        .await;
+        if attempt == 0 {
+            let _ = socket.close().await;
+            return;
+        }
+        send(
+            &mut socket,
+            StructuredEvent::ProjectionUpdate {
+                transcript: Some(TranscriptDelta::Patch {
+                    row: row("live", json!({"content":{"type":"text","text":"two"}})),
+                }),
+                state: ReducedState {
+                    model: Some("test-model".into()),
+                    ..ReducedState::default()
+                },
+            },
+        )
+        .await;
+        tokio::time::sleep(Duration::from_secs(3)).await;
+    })
+}
+
+fn row(id: &str, data: serde_json::Value) -> TranscriptRow {
+    TranscriptRow {
+        id: id.into(),
+        kind: TranscriptRowKind::AgentText,
+        data,
+    }
+}
+
+async fn send(socket: &mut axum::extract::ws::WebSocket, event: StructuredEvent) {
+    socket
+        .send(Message::Text(serde_json::to_string(&event).unwrap()))
+        .await
+        .unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn reconnect_snapshot_replaces_then_delta_patches_projection() {
+    let connects = Arc::new(AtomicUsize::new(0));
+    let app = Router::new()
+        .route("/api/structured/x", any(structured_handler))
+        .with_state(connects.clone());
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+    let handle = StructuredTask::spawn(format!("ws://{addr}/api/structured/x"));
+    for _ in 0..250 {
+        tokio::time::sleep(Duration::from_millis(10)).await;
+        let state = handle.state.lock().unwrap().clone();
+        if state.reduced.model.as_deref() == Some("test-model") {
+            assert_eq!(state.rows.len(), 1);
+            assert_eq!(state.rows[0].id, "live");
+            assert_eq!(state.rows[0].data["content"]["text"], "two");
+            assert!(connects.load(Ordering::SeqCst) >= 2);
+            handle.end();
+            assert_eq!(handle.connection(), SessionState::Ended);
+            return;
+        }
+    }
+    panic!(
+        "structured projection never reached reconnect delta; connection={:?}",
+        handle.connection()
+    );
+}

crates/maestro/Cargo.toml

@@ -29,3 +29,6 @@ tracing-subscriber.workspace = true
 maestro-cli = { path = "../maestro-cli", optional = true, default-features = false }
 maestro-daemon = { path = "../maestro-daemon", optional = true, default-features = false }
 maestro-tui = { path = "../maestro-tui", optional = true }
+
+[dev-dependencies]
+tempfile.workspace = true

crates/maestro/tests/subcommand_routing.rs

@@ -0,0 +1,102 @@
+//! Process-level routing for the umbrella `maestro` binary (#10): each
+//! enabled top-level subcommand must reach its own crate's runtime dispatch,
+//! not just parse successfully.
+//!
+//! A malformed `--config` file makes every crate's dispatch fail identically
+//! at config load, before any subcommand touches tmux, the network, or a
+//! terminal. That lets the assertions tell "clap parsed it but the handler
+//! never ran" (a usage error, exit 2) apart from "it dispatched into the real
+//! crate" (a `toml decode` runtime error via `main`'s `maestro: {e}` printer,
+//! exit 1).
+//!
+//! The absence tests below only compile when the matching feature is off, so
+//! they run under CI's per-feature-subset matrix (`--no-default-features
+//! --features cli|daemon|tui`) rather than the default all-features build.
+
+use std::io::Write;
+use std::path::PathBuf;
+use std::process::{Command, Output};
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_maestro"))
+}
+
+fn bad_config() -> tempfile::NamedTempFile {
+    let mut f = tempfile::NamedTempFile::new().expect("create temp config file");
+    write!(f, "this is not valid toml {{{{{{").expect("write temp config");
+    f
+}
+
+fn run(args: &[&str]) -> Output {
+    Command::new(bin())
+        .args(args)
+        .output()
+        .unwrap_or_else(|e| panic!("spawn `maestro {args:?}`: {e}"))
+}
+
+/// Real dispatch happened: exit 1, `main`'s `"maestro: {e}"` prefix, and the
+/// config crate's error surfacing through — never clap's own usage-error
+/// page, which would mean the subcommand never reached its handler.
+fn assert_dispatched(out: &Output) {
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert_eq!(out.status.code(), Some(1), "stderr:\n{stderr}");
+    assert!(stderr.starts_with("maestro: "), "stderr:\n{stderr}");
+    assert!(stderr.contains("toml decode"), "stderr:\n{stderr}");
+    assert!(!stderr.contains("Usage:"), "stderr:\n{stderr}");
+}
+
+/// Never reached a handler: clap rejected the subcommand outright because the
+/// feature that defines it is off. Only used by the `not(feature = "...")`
+/// tests below, which themselves only exist in a single-feature build.
+#[cfg(not(all(feature = "cli", feature = "daemon", feature = "tui")))]
+fn assert_unrecognized(out: &Output, name: &str) {
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert_eq!(out.status.code(), Some(2), "stderr:\n{stderr}");
+    assert!(
+        stderr.contains("unrecognized subcommand"),
+        "stderr:\n{stderr}"
+    );
+    assert!(stderr.contains(name), "stderr:\n{stderr}");
+}
+
+#[cfg(feature = "cli")]
+#[test]
+fn list_dispatches_into_maestro_cli() {
+    let cfg = bad_config();
+    let out = run(&["list", "--config", cfg.path().to_str().unwrap()]);
+    assert_dispatched(&out);
+}
+
+#[cfg(not(feature = "cli"))]
+#[test]
+fn list_is_unrecognized_without_cli_feature() {
+    assert_unrecognized(&run(&["list"]), "list");
+}
+
+#[cfg(feature = "daemon")]
+#[test]
+fn daemon_dispatches_into_maestro_daemon() {
+    let cfg = bad_config();
+    let out = run(&["daemon", "--config", cfg.path().to_str().unwrap()]);
+    assert_dispatched(&out);
+}
+
+#[cfg(not(feature = "daemon"))]
+#[test]
+fn daemon_is_unrecognized_without_daemon_feature() {
+    assert_unrecognized(&run(&["daemon"]), "daemon");
+}
+
+#[cfg(feature = "tui")]
+#[test]
+fn tui_dispatches_into_maestro_tui() {
+    let cfg = bad_config();
+    let out = run(&["tui", "--config", cfg.path().to_str().unwrap()]);
+    assert_dispatched(&out);
+}
+
+#[cfg(not(feature = "tui"))]
+#[test]
+fn tui_is_unrecognized_without_tui_feature() {
+    assert_unrecognized(&run(&["tui"]), "tui");
+}

docs/INSTALL.md

@@ -18,10 +18,14 @@ wizard, and cleans up — only the unified `maestro` binary ends up persisted in
 
 **Updating is the same command.** Re-running `./install.sh` detects an existing
 systemd unit, refreshes it, and runs `systemctl --user restart maestro` instead
-of `start`. No `--update` flag needed. **The restart keeps your sessions:** the unit sets
+of `start`. No `--update` flag needed. **The restart keeps your terminal sessions:** the unit sets
 `KillMode=process`, so systemd signals only the daemon — the tmux server (and
-every session) survives, and the new daemon re-adopts them on start. A unit
-written before this default lacks the line; re-run `./install.sh` to refresh it.
+every tmux-backed session) survives, and the new daemon re-adopts them on
+start. Structured sessions (an agent run as a daemon child over ACP) are not
+tmux panes, so shutdown ends their active turn; the transcript survives and
+the next daemon attempts one resume (`docs/RESTART.md#structured-sessions`). A
+unit written before this default lacks the line; re-run `./install.sh` to
+refresh it.
 
 Inside the script, `cargo install --git https://git.naps.pt/naps62/maestro …`
 uses your already-configured git credentials for this host (HTTPS helper or
@@ -94,7 +98,10 @@ running a local daemon, for a host that only talks to another machine's.
 
 The daemon unit carries the same `KillMode=process` as the wizard-written one,
 so `systemctl --user restart maestro-daemon` leaves the tmux server and every
-session alive.
+terminal session alive. Structured sessions end their active turn on
+shutdown and resume once on the next daemon: ACP state comes back via
+`session/load`, while the event log only replays Maestro's own transcript
+projection (`docs/RESTART.md#structured-sessions`).
 
 ## Thin builds for single-role hosts
 
@@ -188,28 +195,36 @@ An unknown name is rejected as an `[tui].theme` configuration error.
 The full action vocabulary is the `Action` enum in
 `crates/maestro-tui/src/action.rs`.
 
-## Structured sessions: `claude-code-acp`
+## Structured sessions: ACP adapters
 
-A session spawned with `view: Structured` (#134) runs Claude Code as a child
+A session spawned with `view: Structured` runs Claude Code or Codex as a child
 of the daemon over the Agent Client Protocol instead of in a tmux pane. The
-daemon resolves the adapter binary, `claude-code-acp`, on its `PATH` at spawn
-time. Install it once per host:
+resolved session command selects the adapter binary, which must be on the
+session's `PATH` when the spawn request sets one, or the daemon's `PATH`
+otherwise. Install the adapter for each provider you use:
 
 ```sh
 npm install -g --prefix ~/.local @zed-industries/claude-code-acp
+npm install -g --prefix ~/.local @agentclientprotocol/codex-acp
 ```
 
-That puts `claude-code-acp` in `~/.local/bin`, which must be on the daemon's
-`PATH` (a systemd user unit does not read your shell profile; set
+That puts `claude-code-acp` and `codex-acp` in `~/.local/bin`, which must be on
+the applicable `PATH` (a systemd user unit does not read your shell profile; set
 `Environment=PATH=…` in the unit or install somewhere already on it). The
-adapter needs a logged-in Claude Code (`claude /login`).
+Claude adapter needs a logged-in Claude Code (`claude /login`); Codex uses the
+Codex CLI's or adapter's configured authentication.
 
 When the adapter is missing the spawn still creates the session, marked dead
-with the install command above as its activity detail, so the sidebar says
-what to run. The adapter is a child of the daemon: it ends with a `DELETE
+with the provider-specific install command as its activity detail, so clients
+say what to run. The adapter is a child of the daemon: it ends with a `DELETE
 /api/sessions/:id` (`session/cancel`, then `SIGTERM`) and with the daemon
-itself. Terminal sessions keep surviving restarts through tmux; structured
-ones do not yet.
+itself. A daemon restart ends an in-flight structured turn, but preserves its
+worktree, session record, and event-log transcript. The replacement daemon
+starts a new adapter, resumes it with `session/load`, and replays the
+transcript. Terminal sessions keep surviving restarts through tmux. See
+`docs/STRUCTURED-VIEW.md` for the full contract — row kinds, projections, the
+handshake, and the approval and recovery rules — and `docs/RESTART.md` for
+what a client observes across the restart.
 
 ## The browser UI
 

docs/RESTART.md

@@ -2,10 +2,16 @@
 
 Maestro is upgraded in place: the operator reinstalls the binary and systemd
 restarts the daemon under every browser tab and TUI that is attached to it.
-tmux keeps the sessions alive across that (see `docs/INSTALL.md`), but clients
-lose their sockets. This document is the contract for what a client does about
-it — what the daemon publishes, how a client tells a restart from a blip, and
-what the user sees while it happens.
+tmux keeps **terminal** sessions alive across that (see `docs/INSTALL.md`),
+but clients lose their sockets either way. This document is the contract for
+what a client does about it — what the daemon publishes, how a client tells a
+restart from a blip, and what the user sees while it happens.
+
+A **structured** session (`docs/STRUCTURED-VIEW.md`) has no tmux pane behind
+it to survive on: its agent is a child of the daemon process itself, so a
+restart takes it down with the daemon. See
+[Structured sessions](#structured-sessions) below for exactly what that
+costs and what it doesn't.
 
 ## What the daemon publishes
 
@@ -68,6 +74,35 @@ resolves, so a blocked client is never a trapped one. It clears itself the
 moment a probe succeeds — there is no "retry" button, because the client is
 already retrying.
 
+## Structured sessions
+
+Everything above describes a **client's** view of a restart, and it holds for
+a structured session exactly as written — the same three verdicts, the same
+status indicator, the same overlay. What differs is what survives on the
+**daemon** side, because a structured session's agent is a daemon child, not
+a tmux pane:
+
+- A restart **ends the active turn**. There is no adapter process left to
+  finish it, and no tmux pane keeping it alive underneath.
+- The **transcript survives**, in the per-session event log
+  (`docs/STRUCTURED-VIEW.md#persistence-recovery-and-dead-sessions`) — a
+  graceful shutdown marks the session for one resume attempt. Recovery is
+  two separate operations, not one: the next daemon calls `session/load` so
+  the adapter restores its own ACP session, but whatever history the
+  adapter emits during that call is discarded, not replayed into anything —
+  the daemon already has that history on disk. Separately, the daemon
+  rebuilds its own projection by folding the persisted event log back
+  through it. An ungraceful death (a crash, `kill -9`) leaves no resume
+  marker, and the session stays dead permanently.
+- **Pending approvals and their nonces do not survive.** Both live only in
+  the old daemon's memory; any ACP permission request still mid-flight when
+  the daemon exits is answered `Cancelled` on the way down, and a resumed
+  session starts with no pending approval at all.
+
+`docs/STRUCTURED-VIEW.md` is the full contract for all of this — the event
+log's shape, the recovery marker, and exactly which kind of session death is
+resumable.
+
 ## Timing
 
 - **Grace window** — 1200 ms between the socket dropping and the overlay

docs/SIDEBAR.md

@@ -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`          |
 
@@ -231,7 +232,24 @@ cutover points land within one tick.
 
 ## Precedence
 
-An agent-reported `ActivityState` (#105) overrides the daemon's inference for
+### Activity source by session kind
+
+The daemon supplies one `activity` field to both clients, but its source depends
+on the session kind:
+
+| Session kind | Source |
+|---|---|
+| Terminal | The existing agent-report override and five-minute TTL, falling back to PTY quiescence, foreground process and `/proc` input-block inference. |
+| Structured | ACP state directly: a pending approval is `AwaitingInput`; otherwise an in-flight turn is `Active`; no turn is `Idle`. A failed turn or dead structured session is `Error`, and the next turn clears a failed-turn error. |
+
+Structured sessions never enter the terminal inference path and ignore activity
+reports inherited through agent hooks. They have no PTY whose output or blocked
+read could describe their state. This is a second source, not a replacement for
+the terminal source.
+
+### Terminal report override
+
+For terminal sessions, an agent-reported `ActivityState` (#105) overrides the daemon's inference for
 **five minutes** (the TTL is fixed by the daemon; re-reporting extends it).
 When the TTL expires, inference resumes and the session's reported detail —
 if any — clears with the report. Clients never blend the two: whichever source
@@ -281,10 +299,10 @@ session is genuinely `Active` again — new work, not merely a refocus. Only
 after that fresh `Active` cycle does the *next* `AwaitingInput` glow again.
 Unfocusing and refocusing alone never re-arms it.
 
-This applies uniformly to `AwaitingInput` from either source — the daemon's
-own inference or an agent's report (#105) — since the rail draws them
-identically. It does not touch `Error`; that state's own TTL (below) is
-unrelated and unaffected by focus.
+This applies uniformly to `AwaitingInput` from terminal inference, an agent
+report (#105), or a structured session's pending approval, since the rail draws
+them identically. It does not touch `Error`; terminal reports keep their TTL,
+while a structured failed-turn error clears when the next turn starts.
 
 Each client reports its own pane's focus with `POST /api/sessions/:id/focus`
 (`{"focused": bool}`) whenever the pane it is showing changes — on attach, on

docs/STRUCTURED-VIEW.md

@@ -0,0 +1,459 @@
+# STRUCTURED-VIEW.md — the structured session contract
+
+The contract for a structured session (`view: Structured`, #133): an agent run
+as a daemon child over the Agent Client Protocol (ACP) instead of in a tmux
+pane. Alongside `docs/WORKTREES.md`, `docs/SIDEBAR.md` and `docs/RESTART.md`,
+read this before changing anything that renders a structured session — both
+the web and TUI renderers are written against it.
+
+It covers the eight transcript row kinds, what the daemon decides versus what
+a client decides, the two projections and their delta/cursor semantics, the
+ACP handshake and the capabilities it declines, the adapter's install
+command, and the approval nonce rules. **Non-goal: the detached runner.** It
+does not exist yet, and nothing here describes it.
+
+## What a structured session is
+
+A terminal session's agent runs inside a tmux pane; a structured session's
+agent runs as a subprocess of the daemon itself, speaking ACP over stdio. The
+daemon is the ACP **client**; the provider adapter process is the ACP
+**agent**. It translates the provider's events into ACP `session/update`
+notifications instead of drawing them to a pane. `crates/maestro-acp` owns the
+daemon's side of that connection;
+`crates/maestro-daemon/src/projection.rs` folds what it receives into the two
+projections below.
+
+The child is a real child of the daemon process: same process group, and on
+Linux marked with `PR_SET_PDEATHSIG` so it dies with the daemon even if the
+daemon exits without cleaning up; other platforms have no such signal and
+depend on an orderly shutdown/drop to terminate it. The ordinary path on
+every platform is `AcpSession::terminate` (`session/cancel`, a short grace,
+`SIGTERM`, then `SIGKILL`), called from both `DELETE /api/sessions/:id` and
+daemon shutdown.
+`docs/WORKTREES.md`'s kill-guard rule — an unforced kill refused while the
+session's worktree holds unsaved work — applies to a structured session
+exactly as it does to a terminal one; only what gets terminated differs (an
+ACP handle instead of a tmux pane).
+
+## Choosing the view
+
+`view` is fixed at spawn and never changes. Every client picks it the same
+way, from the resolved command alone
+(`maestro_protocol::display::supports_structured_view`): a command that
+resolves to Claude Code or Codex spawns **Structured** by default, anything
+else spawns **Terminal**. The operator can override the default — the web and
+TUI spawn forms show the checkbox ticked and let it be unticked, and
+`maestro spawn` takes `--terminal` (or `--structured`, which sends the request
+even for a command the CLI does not recognise and lets the daemon refuse it).
+Once the operator works the toggle, a later command change never re-ticks it
+under them; it can still be forced off when the new command has no adapter.
+
+The daemon is the last word: a `Structured` request for a command with no
+adapter is refused there, whichever client sent it.
+
+## The adapter
+
+The resolved structured command selects a provider adapter. Its binary is
+resolved by walking the session's `PATH` when the spawn request sets one, or
+the daemon's `PATH` otherwise, and taking the first executable with that name.
+
+| Command | Adapter binary | Install command | Provider detail |
+| --- | --- | --- | --- |
+| `claude` | `claude-code-acp` | `npm install -g --prefix ~/.local @zed-industries/claude-code-acp` | Needs a logged-in Claude Code. |
+| `codex` | `codex-acp` | `npm install -g --prefix ~/.local @agentclientprotocol/codex-acp` | Uses Codex CLI or adapter-configured authentication; it advertises model, reasoning-effort, agent-mode, and optional fast-mode configuration. |
+
+The selected install command is baked into `AcpError::AdapterMissing`. When an
+adapter cannot be found, spawn still creates a **Dead** session with that
+command as `activity_detail` (see `docs/INSTALL.md` for the systemd `PATH`
+caveat). Provider authentication failures surface through the adapter's stderr
+tail in the same field.
+
+The handshake is bounded by `HANDSHAKE_TIMEOUT` (60s) — long enough for a
+slow machine to boot an adapter and its provider process, never long enough
+to hang a spawn indefinitely. Any handshake failure — missing adapter, early
+exit, a protocol error, or the timeout — leaves no orphaned process: `spawn`
+closes and reaps the child itself before returning the error.
+
+## The ACP handshake
+
+`initialize` is where the daemon states what kind of client it is. It
+declares, deliberately, almost nothing:
+
+| Capability | Declared | Why |
+| --- | --- | --- |
+| `fs.readTextFile` | `false` | Providers read the session workspace through their own tool surface. |
+| `fs.writeTextFile` | `false` | Providers write the session workspace through their own tool surface. |
+| `terminal` | `false` | Providers run commands through their own tool surface. |
+
+Declining all three keeps the daemon out of the file/terminal surface
+entirely — the adapter already has direct access to the session's `cwd`, and
+routing every read, write, and shell command through the daemon would only
+add a hop with no new capability. Every other capability namespace ACP
+defines (session extensions, auth, elicitation) is simply left at its
+default; the daemon does not advertise support because neither supported
+adapter needs it, not because it was weighed and refused.
+
+The one client method that *is* implemented for real is
+`session/request_permission` (#139) — see [Approvals](#approvals) below.
+Before #139 it was a stub that declined every request; that stub is gone now
+that a live implementation exists.
+
+`session/new` opens a fresh ACP session on every ordinary spawn. A respawn
+after a daemon restart instead sets `SpawnConfig::load_session(id)` and runs
+`session/load` with the ACP session id the original handshake returned
+(`Session::acp_session_id` on the wire) — the adapter must advertise
+`agent_capabilities.load_session`, or the handshake fails outright naming
+that. Whatever history the adapter streams back while `session/load` is in
+flight is dropped on arrival, deliberately: the daemon's own event log
+already holds that history, and forwarding it too would duplicate every row
+in the projections below.
+
+Codex and Claude differ in what they emit, not in this lifecycle. Codex maps
+shell commands, file changes, MCP calls, web search, image generation/view,
+reasoning, plans, and token usage into standard ACP chunks and tool calls;
+those fold into the same eight rows. Codex's `available_commands_update` and
+`session_info_update`, like equivalent Claude updates, remain opaque
+`Notice` rows. Its `session/load` capability is required for daemon recovery
+just as it is for Claude.
+
+## The eight transcript row kinds
+
+`TranscriptRowKind` (`maestro-protocol`) is the alphabet a structured
+transcript is written in. Every row has a stable `id` (so later deltas can
+address it), a `kind`, and a `data: Value` that preserves the underlying ACP
+payload — clients depend on ACP's *shape* without depending on ACP as a
+crate.
+
+| Kind | Carries | Row identity |
+| --- | --- | --- |
+| `User` | The prompt accepted by Maestro's structured prompt endpoint, persisted before ACP dispatch. An adapter `user_message_chunk` is also supported for imported ACP history. | `user:<uuid>` for a daemon-recorded prompt; `user:<message_id>` or `user:<seq>` for an ACP chunk. |
+| `AgentText` | An `agent_message_chunk` — the agent's visible reply, streamed. | `agent:<message_id>`, or `agent:<seq>` from the first chunk when no id is supplied. Later chunks for the same id—or consecutive anonymous text chunks—are appended into `data.content.text` in place. An empty anonymous chunk starts a fresh row, matching the turn marker emitted by adapters that omit message ids. |
+| `AgentThought` | An `agent_thought_chunk` — the model's reasoning stream. | `thought:<message_id>` / first anonymous `thought:<seq>`, coalesced the same way as `AgentText`. |
+| `ToolCall` | A `tool_call` / `tool_call_update` pair whose content carries no diff. | `tool:<tool_call_id>` — one row for the call's whole life; updates patch it in place, they never create a second row. |
+| `ToolDiff` | The same tool-call machinery, when the tool's content includes a `Diff` block. | Same `tool:<tool_call_id>` identity as `ToolCall`; the *kind* flips between the two as the tool's own content changes, not the row. |
+| `Approval` | A daemon-originated permission request (`RequestPermissionRequest`), serialized without its nonce. | `approval:<uuid>` — minted fresh per request, unrelated to the ACP request's own id. |
+| `Plan` | A `plan` update — the agent's current step list. | The fixed id `"plan"`. Each new plan **replaces** the row wholesale; entries are not diffed against the previous plan. |
+| `Notice` | The raw JSON of any `session/update` variant the ACP dependency already decodes but the projection does not special-case. Maestro also uses a tagged `maestroTurnMeta` notice as the durable footer for a completed, cancelled, or failed turn. | `notice:<seq>` for ACP updates; `turn_meta:<uuid>` for a turn footer. |
+
+`Notice` covers known-but-unspecialized `SessionUpdate` variants: ones the
+`agent-client-protocol` dependency's schema already deserializes (it
+currently folds `available_commands_update` and `session_info_update`
+there) but the projection's `match` doesn't fold into one of the other
+seven kinds. It is not a wire-level forward-compatibility seam:
+`SessionUpdate` is an internally-tagged enum with no unknown-variant
+fallback, so a `session/update` whose `sessionUpdate` tag this build's
+dependency has never heard of — including a variant gated behind an
+unstable ACP feature this build doesn't enable, which is compiled out of
+the enum entirely — fails to deserialize before the projection ever runs,
+rather than becoming a `Notice`. A genuinely new ACP variant needs the
+`agent-client-protocol` dependency upgraded (and, typically, the projection's
+`match` taught about it) before it can appear on this transcript at all — see
+`projection.rs`'s test asserting that an unrecognised `sessionUpdate` tag is a
+deserialization error, not a `Notice`. A client that does not know what to do
+with a `Notice` can still render it as an opaque, collapsed line — that
+remains a reasonable floor, not a client bug.
+
+Rendering is entirely a client concern. The projection's job stops at
+folding ACP into these eight shapes; markdown formatting, diff rendering,
+tool-card treatment, and how a `Notice` is presented are all renderer
+choices, not daemon ones.
+
+## Daemon decisions vs. client decisions
+
+**The daemon decides:**
+
+- Which ACP `session/update` becomes which row kind, and under what id — the
+  fold in `projection.rs` is the one place this logic lives, so the web and
+  TUI renderers can never disagree about it.
+- Turn lifecycle: when a turn begins, and whether an ACP response, a cancel,
+  or a failure ends it (`TurnState.responding` / `.thinking` /
+  `.active_tool_calls` / `.started_at` are derived, not renderer-computed).
+  Ending a turn appends a durable `maestroTurnMeta` footer with its elapsed
+  time, outcome, model, and context-window usage/delta. ACP does not expose
+  provider billing-token counts, so these are explicitly context tokens.
+- Approval nonce minting, secrecy, and the single-active-approval rule (see
+  below) — a client never sees an ACP permission request before the daemon
+  has already turned it into an `Approval` row and a nonce.
+- What happens to an ACP update variant the dependency decodes but nobody has
+  taught the projection to special-case (falls back to `Notice` rather than
+  erroring). A variant the dependency itself can't decode is a deserialization
+  error, not a `Notice` — see [The eight transcript row
+  kinds](#the-eight-transcript-row-kinds).
+- Persistence and replay: what is written to the event log, in what order,
+  and how a restart resumes it.
+
+**A client decides:**
+
+- How each row kind is drawn — markdown for `AgentText`/`AgentThought`, a
+  diff view for `ToolDiff`, a tool card for `ToolCall`, and a floor
+  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. While a turn is still active
+  (responding or thinking), the most recent intermediate `AgentText` or
+  `AgentThought` in the group is kept outside as visible narration — replaced
+  by the next text row when one arrives, and absorbed into the group when the
+  turn ends. 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'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
+  source for composer `/` autocomplete at any whitespace-delimited token under
+  the caret. Completing a command replaces only that token. The client omits
+  those state-only notices, along with `session_info_update`, from the visible
+  transcript.
+- How live `responding`, `thinking`, tool activity, elapsed time, and context
+  usage are drawn. The web client keeps these in a compact strip above the
+  composer and renders each durable turn footer inline with the transcript.
+- How the operator is asked to resolve an `Approval` row — the daemon only
+  exposes the three-way decision (`AllowOnce` / `AllowForSession` / `Deny`),
+  never the UI that solicits it.
+- Scrolling, collapsing, and every other presentation-only behaviour.
+
+## The two projections
+
+`Projection` (daemon-only) is folded once from the durable ACP stream and
+exposes two independent views, both defined in `maestro-protocol`:
+
+- **`TranscriptSnapshot { cursor, rows }`** — the complete ordered list of
+  transcript rows built so far, plus the log position (`cursor`) it reflects.
+  It is intentionally always the *whole* transcript, not a windowed one: a
+  tool row patched much later must still find its original entry.
+- **`ReducedState`** — one whole-session snapshot folded over every event
+  seen: `turn` (the per-turn indicators above), `pending_approval`, `plan`,
+  `usage`/`context`, `model`, and `mode`. Like `TranscriptSnapshot`, it is
+  always full-history, never a delta — a client that only wants "is a turn
+  active right now" never has to replay anything to answer that.
+
+Changes to the transcript travel as `TranscriptDelta`, tagged `type`:
+`Append { row }` (a new row), `Patch { row }` (an existing row, addressed by
+`id`, replaced wholesale), and `Remove { id }`. `Remove` is defined on the
+wire for forward compatibility; nothing in the current projection emits it —
+every row, once appended, is only ever patched or left alone.
+
+### Cursor and replay semantics
+
+The event log's own line position is the cursor: 1-based, shared by ACP
+notifications and daemon-generated rows alike (`sidecar.rs`'s
+`PersistedEvent` envelope is what lets `User` and `Approval` rows share a cursor
+sequence with raw ACP JSON without pretending to be ACP traffic; the envelope
+also carries durable `Turn` footers). Two ways to
+read it:
+
+- **`WS /api/structured/:id`** — on connect, sends a `TranscriptSnapshot` and
+  a `ReducedState` covering the whole log as it stands, then streams
+  `ProjectionUpdate { transcript, state }` for everything that happens next.
+  There is no client-supplied resume cursor on this socket: every connection
+  gets the full snapshot, not a gap-filled continuation, so a client never
+  needs the replay endpoint just to obtain the current transcript. Use
+  replay instead for cursor-bounded pagination through the durable log —
+  history from before this connection, fetched a page at a time.
+- **`GET /api/sessions/:id/structured/replay`** — cursor-bounded pagination
+  over the durable log, returning one `StructuredReplayEvent` (`cursor`,
+  `transcript`, `state`) per matching line. `?since=<n>` returns the first
+  page after `n` (`since=0` selects from the beginning, i.e. the first
+  page); a client pages forward from there using the cursor of the last
+  event returned. `?before=<n>` returns the page immediately before `n`,
+  still in ascending order — passing both is a `400`. `?limit` defaults to
+  100 and is clamped to 500. Each call re-folds
+  the entire log from scratch to compute the state at every returned cursor,
+  so a page reflects exactly the *durable* state at its cursor, not an
+  approximation of it — at the cost of redoing the whole fold per request.
+  That durable state is not always identical to what a live client saw at
+  that moment, though: turn lifecycle transitions are broadcast live without
+  a durable event backing them (see [Prompt and cancel](#prompt-and-cancel-bounded-liveness)),
+  and a restored `Approval` row carries no pending nonce, because the nonce
+  never reached disk (see [Approvals](#approvals)) — replay is exact and
+  reconstructible, not a perfect record of everything the live view showed.
+  A session that is not a live structured session (terminal, or a dead
+  adapter) answers `409 not_structured` from either route rather than a
+  coherent-looking but stale reply.
+
+## Approvals
+
+An ACP `session/request_permission` callback becomes an `Approval` row plus a
+pending decision, entirely on the daemon side:
+
+- **Generation.** The daemon mints the nonce itself — a fresh
+  `Uuid::new_v4()` string per request — rather than using anything ACP's own
+  request carries. ACP permission callbacks have no request id of their own
+  that would double as one.
+- **Live-only placement.** The nonce lives in exactly one place: the
+  in-memory `pending_approvals` map keyed by nonce, and its mirror in
+  `ReducedState.pending_approval.nonce` on the live wire. It is never part of
+  the `Approval` row's `data` — the row is `RequestPermissionRequest`
+  serialized *without* the nonce.
+- **Secrecy from the agent and from durable history.** The adapter itself
+  never learns the nonce — it is a daemon-to-client secret, never sent back
+  over the ACP connection. It is likewise never written to the event log:
+  restoring an `Approval` row from disk (`Projection::restore_row`)
+  produces a historical row with no `pending_approval` in state, because the
+  nonce that would make it "pending" never made it to disk in the first
+  place. A restart therefore cannot resume a pending approval — see
+  [Persistence](#persistence-recovery-and-dead-sessions).
+- **One live approval at a time.** A new permission request mints its own
+  nonce, then cancels whatever was already pending (`cancel_pending_approvals`)
+  before installing itself as the new pending approval — ACP serializes
+  requests through one connection, so this only ever fires if an adapter
+  nonetheless overlaps two. Either way, the prior pending request is
+  cancelled/cleared before the new one is installed, so the newest request
+  wins.
+- **Single-use and duplicate resolution.**
+  `POST /api/sessions/:id/structured/approvals/:nonce` **always answers
+  `204`** for a known, live structured session — whether the nonce is the
+  one currently pending, one already consumed by an earlier answer, or one
+  that never existed. Only an unknown or non-structured *session* answers
+  otherwise (`404` / `409`). This is deliberate: two clients racing to answer the same
+  approval must not turn a harmless duplicate click into a client-visible
+  error. Whichever `POST` reaches the daemon first removes the nonce from
+  `pending_approvals` and is the one whose decision actually reaches the
+  adapter; every later `POST` for that nonce is a no-op `204`.
+- **Cancellation vs. denial.** A turn cancel or a session shutdown resolves
+  any pending approval with ACP's `Cancelled` outcome, not a `Deny` decision
+  — the adapter should read those as "the operation was withdrawn," not "the
+  operator refused it."
+- **Decision mapping.** `AllowOnce` and `AllowForSession` select the ACP
+  option of kind `AllowOnce` / `AllowAlways` from the request's own option
+  list. `Deny` prefers a one-shot refusal (`RejectOnce`) and falls back to a
+  permanent one (`RejectAlways`) only when that is the sole rejection option
+  offered; if neither is present, it answers `Cancelled`.
+
+## Prompt and cancel: bounded liveness
+
+The web composer accepts up to ten files through its attachment picker, file
+drop, or clipboard. Pasted text of at least 4,000 characters or 40 lines becomes
+a UTF-8 `.txt` attachment. Shorter pastes stay in the composer. Attachments can
+be removed before sending; failed sends retain the draft and attachments.
+Pastes also stay inline when all ten attachment slots are occupied or the text
+exceeds the 20 MiB file limit.
+
+On send, `POST /api/sessions/:id/structured/attachments?name=<filename>` uploads
+each file as raw bytes (20 MiB maximum) and returns its absolute `path`.
+Only live structured sessions accept uploads. Filenames are limited to 180
+bytes and cannot contain directory separators or control characters. Files get unique names and private
+file permissions in `<id>.attachments` beside the session sidecar. They persist
+across daemon restarts; removing a composer chip does not delete uploaded data.
+There is currently no automatic attachment cleanup.
+
+The prompt includes each filename and host path so the adapter can read it
+through its own file tools, including images when the provider supports them.
+These references are persisted in the ordinary user transcript row. Attachment
+bytes are not embedded in ACP messages or transcript history.
+
+`POST /api/sessions/:id/structured/prompt` and `.../cancel` are serialized
+against each other through one per-session `operation` lock
+(`AcpEventStream::operation`), because ACP permission callbacks carry no
+per-request id — the daemon's own notion of "the active turn" is the only
+thing a callback can be attributed to, so at most one turn may ever be
+in flight, and a cancelled turn must fully settle before the next prompt is
+allowed to claim the daemon's idea of "the active turn."
+
+- Web clients may collect a visible FIFO of operator messages while a turn is
+  active. They submit each queued message only after the projected turn becomes
+  idle; the queue is client-local and unsent messages do not survive a reload.
+- A submitted prompt is appended as a durable `User` row before it claims the turn and
+  dispatches to ACP, so the transcript never depends on an adapter echoing the
+  operator's input. If that append fails, the prompt is not dispatched. While a
+  turn is active, a second prompt gets `409 turn_in_flight` rather than
+  queuing in the daemon — one active turn per session, never a hidden
+  server-side queue of prompts.
+- Cancel sends `session/cancel`, clears any pending approval as `Cancelled`,
+  and ends the turn's client-visible lifecycle immediately. If the cancelled
+  turn was still *dispatched* to ACP (waiting on its response), the daemon
+  cannot simply forget it: ACP has not confirmed the cancel yet, and a new
+  prompt claiming "the active turn" while the old one is still outstanding
+  would make the next permission callback ambiguous between the two.
+- So a cancelled-but-still-dispatched turn must **settle within
+  `CANCEL_GRACE` (500ms)** — either ACP acknowledges the prompt (however it
+  resolves) or that grace period runs out. If it settles in time, the next
+  prompt proceeds normally. If it does not, the daemon does not guess: it
+  marks the whole structured session dead (`fail_cancelled_acp_turn`) rather
+  than risk a callback resolving against the wrong turn. This is the bounded
+  half of "bounded liveness" — a structured session's prompt/cancel dance
+  either resolves promptly or the session is declared unusable, never left
+  in an indefinite ambiguous state.
+
+## Persistence, recovery, and dead sessions
+
+A structured session's durable state is three files in the sidecar
+directory: the sidecar itself (`<id>.json`), plus two next to it:
+
+- **`<id>.events.jsonl`** — the unified event log. Each line is either a raw
+  ACP `SessionNotification` (kept in its original JSON so old logs stay
+  readable) or a `{"maestroEvent": "user"|"approval", "row": …}` envelope
+  for a daemon-generated row. Both share the same 1-based line-position cursor. A
+  line a hard kill left half-written is terminated before the next append, so
+  it keeps its position and is skipped as malformed rather than corrupting
+  what follows. An append that fails *while the daemon is running* — a
+  `write_all` that errors after only a prefix reached disk, or a `flush` that
+  errors after a complete write — is rolled back to the exact byte length the
+  file was at before the call, so `last_seq` and the file's line count never
+  disagree and the same log handle can be appended to again immediately (#184).
+  If that rollback itself cannot restore the prior length, the append is
+  fatal: the log's consistency can no longer be promised, so the caller kills
+  the session instead of appending to it again.
+- **`<id>.recover`** — an empty marker file. Its only meaning is "the daemon
+  that wrote this shut down gracefully while this session was running, and
+  the next daemon may attempt to resume it." It is consumed (deleted) the
+  moment a recovery attempt reads it — one recovery attempt per graceful
+  shutdown, never a standing flag.
+
+Three ways a structured session ends up `Dead`, each with different
+persistence consequences:
+
+1. **The adapter exits, or a notification append to the event log fails,
+   while the daemon keeps running.** (An approval-row append failure is
+   narrower: as long as the log rolled back cleanly, it only cancels the
+   pending approval and rolls the unpersisted `Approval` row back out of the
+   live transcript, without marking the session dead — a snapshot taken after
+   the failure must never show a row durable replay could not reproduce
+   (#184). If the rollback itself did not restore the log's prior length,
+   this narrower path does not apply either: the session is marked dead the
+   same as any other append failure, since the log can no longer promise
+   `last_seq` matches its file.)
+   `mark_session_dead` applies the same natural-exit worktree rule
+   as a terminal session's own pane exiting (`docs/WORKTREES.md`): a pristine
+   worktree is removed, one holding unsaved work is left on disk. No recovery
+   marker is written. This death is permanent — a later daemon restart's
+   `recover()` finds the sidecar, sees no marker, and leaves the session
+   `Dead` without attempting to resume it.
+2. **A cancelled turn fails to settle within `CANCEL_GRACE`.** Same
+   consequence as (1): the session is marked dead through the same path, no
+   marker, no future resumption.
+3. **Graceful daemon shutdown**, while the session was still `Running`.
+   `mark_session_dead_after_shutdown` marks the session dead **without**
+   applying the worktree exit rule — the tree is kept exactly as it is,
+   pristine or not, because there is nothing "natural" about this exit — and
+   writes the `.recover` marker. The sidecar on disk therefore says `Dead`,
+   but is eligible for resumption.
+
+Recovery, on the next daemon's `recover()`: for every `Structured` sidecar
+not already adopted, the marker is consumed. When one was present and the
+sidecar carries a stored `acp_session_id`, the daemon spawns a fresh adapter
+with `SpawnConfig::load_session(acp_session_id)`, replays the
+entire durable event log into a new `Projection` (rebuilding the transcript
+and reduced state exactly as they were, with any restored `Approval` row
+landing as history — never as a re-armed pending approval, since its nonce
+never reached disk), and only then reopens the log for further appends. What
+the adapter streams back while its own `session/load` is in flight is
+discarded rather than appended, so the replayed history is not duplicated
+(see [The ACP handshake](#the-acp-handshake)). Success flips the session back
+to `Running`/`Idle`; failure (no stored `acp_session_id`, or the handshake
+itself failing) leaves it `Dead` with the failure reason as
+`activity_detail` — the same "tell the operator what to fix" pattern as a
+missing adapter binary.
+
+Pending approvals and their nonces never survive any of this. They live only
+in the in-memory `pending_approvals` map and the live `ReducedState`, both
+gone the instant the daemon that held them exits. Whatever ACP permission
+request was mid-flight when the old daemon died was already answered
+`Cancelled` on that daemon's own shutdown path, so a resumed session always
+starts with no pending approval.
+
+See `docs/RESTART.md` for what a *client* observes across a daemon restart,
+now that structured sessions exist alongside terminal ones.

fixtures/command-resolution.json

@@ -0,0 +1,120 @@
+{
+  "_description": "the parity fixture for #199's command resolver — every case here is asserted identically by crates/maestro-protocol/src/display.rs (command_program/command_tool) and web/src/toolIcon.ts (splitCommand). `program` is the resolved, basenamed program; `tool` is the icon id it maps to, or null when unrecognised/ambiguous.",
+  "cases": [
+    { "command": "claude", "program": "claude", "tool": "claude" },
+    { "command": "claude --resume", "program": "claude", "tool": "claude" },
+    { "command": "CLAUDE", "program": "CLAUDE", "tool": "claude" },
+    { "command": "/usr/local/bin/claude -p hi", "program": "claude", "tool": "claude" },
+    { "command": "./bin/claude", "program": "claude", "tool": "claude" },
+    { "command": "FOO=1 BAR=2 claude", "program": "claude", "tool": "claude" },
+    { "command": "FOO=\"bar baz\" claude", "program": "claude", "tool": "claude" },
+    { "command": "FOO='bar baz' claude", "program": "claude", "tool": "claude" },
+    { "command": "FOO=bar\\ baz claude", "program": "claude", "tool": "claude" },
+    { "command": "'/usr/local/bin/claude'", "program": "claude", "tool": "claude" },
+    { "command": "\"/opt/my agent/claude\" --resume", "program": "claude", "tool": "claude" },
+    { "command": "env -i claude", "program": "claude", "tool": "claude" },
+    { "command": "env --ignore-environment claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo -u root claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo --user=root claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo -- claude --resume", "program": "claude", "tool": "claude" },
+    { "command": "nohup claude", "program": "claude", "tool": "claude" },
+    { "command": "time claude", "program": "claude", "tool": "claude" },
+    { "command": "time -p claude", "program": "claude", "tool": "claude" },
+    { "command": "time -- claude", "program": "claude", "tool": "claude" },
+    { "command": "time -p -- claude", "program": "claude", "tool": "claude" },
+    { "command": "time -pp claude", "program": "time", "tool": null },
+    { "command": "time -p -p claude", "program": "time", "tool": null },
+    { "command": "time -o /tmp/t.log claude", "program": "time", "tool": null },
+    { "command": "command claude", "program": "claude", "tool": "claude" },
+    { "command": "command -v claude", "program": "command", "tool": null },
+    { "command": "command -V claude", "program": "command", "tool": null },
+    { "command": "npx --yes claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "npx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm --silent dlx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm -C ./pkg dlx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm dlx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm dlx -s claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm dlx --silent claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn --silent dlx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn dlx -q claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn dlx --quiet claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun x claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bunx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "uvx claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun x --bun claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bunx --bun claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun x -p @anthropic-ai/claude-code claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bunx --package @anthropic-ai/claude-code claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun x --package=@anthropic-ai/claude-code claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bunx --no-install claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun x --verbose claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bunx --silent claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "bun --bun x claude-code", "program": "bun", "tool": null },
+    { "command": "pnpm dlx --package foo claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm dlx --package=foo claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "pnpm dlx --package= claude-code", "program": "pnpm", "tool": null },
+    { "command": "pnpm dlx --package", "program": "pnpm", "tool": null },
+    { "command": "pnpm dlx -c \"claude-code\"", "program": "pnpm", "tool": null },
+    { "command": "pnpm --package=typescript dlx tsc", "program": "tsc", "tool": null },
+    { "command": "pnpm dlx --unknown-flag claude-code", "program": "pnpm", "tool": null },
+    { "command": "yarn dlx --package foo claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn dlx --package=foo claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn dlx -p foo claude-code", "program": "claude-code", "tool": "claude" },
+    { "command": "yarn dlx --package= claude-code", "program": "yarn", "tool": null },
+    { "command": "yarn dlx -p", "program": "yarn", "tool": null },
+    { "command": "yarn dlx -p --quiet claude-code", "program": "yarn", "tool": null },
+    { "command": "bunx --package= claude-code", "program": "bunx", "tool": null },
+    { "command": "bunx --package", "program": "bunx", "tool": null },
+    { "command": "bun x -p --silent claude-code", "program": "bun", "tool": null },
+    { "command": "sudo env -i claude", "program": "claude", "tool": "claude" },
+    { "command": "FOO=1 sudo BAR=2 claude", "program": "claude", "tool": "claude" },
+    { "command": "env -iv claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo -nE claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo -uroot claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo -u", "program": "sudo", "tool": null },
+    { "command": "env --unset= claude", "program": "env", "tool": null },
+    { "command": "sudo --user= claude", "program": "sudo", "tool": null },
+    { "command": "sudo --user \"\" claude", "program": "sudo", "tool": null },
+    { "command": "sudo -nu claude", "program": "sudo", "tool": null },
+    { "command": "env -S 'python3 -u' script.py", "program": "env", "tool": null },
+    { "command": "npx -c \"claude --version\"", "program": "npx", "tool": null },
+    { "command": "npx --call \"claude --version\"", "program": "npx", "tool": null },
+    { "command": "command FOO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "nohup FOO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "npx FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "pnpm dlx FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "yarn dlx FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "bun x FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "bunx FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "uvx FOO=1 claude-code", "program": "FOO=1", "tool": null },
+    { "command": "sudo time FOO=1 claude", "program": "claude", "tool": "claude" },
+    { "command": "nohup env FOO=1 claude", "program": "claude", "tool": "claude" },
+    { "command": "sudo command FOO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "command nohup FOO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "time command FOO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "\"FOO=1\" claude", "program": "FOO=1", "tool": null },
+    { "command": "FOO\\=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "F\"O\"O=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "F\\OO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "\"FOO\"=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "F\"\"OO=1 claude", "program": "FOO=1", "tool": null },
+    { "command": "claude\nclaude-code", "program": "claude", "tool": null },
+    { "command": "clau\\\nde --resume", "program": "claude", "tool": "claude" },
+    { "command": "npx opencode", "program": "opencode", "tool": "opencode" },
+    { "command": "pnpm dlx opencode run", "program": "opencode", "tool": "opencode" },
+    { "command": "pnpm claude", "program": "pnpm", "tool": null },
+    { "command": "yarn claude", "program": "yarn", "tool": null },
+    { "command": "claude-code-acp", "program": "claude-code-acp", "tool": null },
+    { "command": "hx src/main.rs", "program": "hx", "tool": null },
+    { "command": "bash", "program": "bash", "tool": "shell" },
+    { "command": "opencode", "program": "opencode", "tool": "opencode" },
+    { "command": "sudo", "program": "sudo", "tool": null },
+    { "command": "", "program": "", "tool": null },
+    { "command": "npx --unknown-flag claude-code", "program": "npx", "tool": null },
+    { "command": "claude | tee log.txt", "program": "claude", "tool": null },
+    { "command": "claude; echo done", "program": "claude;", "tool": null },
+    { "command": "claude && echo done", "program": "claude", "tool": null },
+    { "command": "echo hi $(claude)", "program": "echo", "tool": null },
+    { "command": "claude \"unterminated", "program": "claude", "tool": null }
+  ]
+}

flake.nix

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

web/index.html

@@ -24,6 +24,7 @@
   </head>
   <body>
     <div id="app"></div>
+    <div id="root"></div>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

web/package-lock.json

@@ -11,7 +11,8 @@
         "@fontsource/jetbrains-mono": "^5.3.0",
         "@xterm/addon-fit": "^0.10.0",
         "@xterm/addon-webgl": "^0.19.0",
-        "@xterm/xterm": "^5.5.0"
+        "@xterm/xterm": "^5.5.0",
+        "marked": "^18.0.11"
       },
       "devDependencies": {
         "happy-dom": "^20.11.6",
@@ -1222,6 +1223,18 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
+    "node_modules/marked": {
+      "version": "18.0.11",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-18.0.11.tgz",
+      "integrity": "sha512-HnslJfsZkRPBDJRHvVtAaWlZHEpSu7u8LgQuJCELjRKuWR+hpq4A7sLq3p8HaI9ypVoXDXxV34CsQJEe1+J5Aw==",
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",

web/package.json

@@ -6,7 +6,7 @@
   "packageManager": "pnpm@9.15.4",
   "scripts": {
     "dev": "vite",
-    "build": "tsc -b && vite build",
+    "build": "tsc -b tsconfig.build.json && vite build",
     "preview": "vite preview",
     "typecheck": "tsc -b --noEmit",
     "test": "vitest run",
@@ -16,12 +16,23 @@
     "@fontsource/jetbrains-mono": "^5.3.0",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-webgl": "^0.19.0",
-    "@xterm/xterm": "^5.5.0"
+    "@xterm/xterm": "^5.5.0",
+    "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,9 @@
+import { ThemeProvider } from "./contexts/ThemeContext";
+
+export function App() {
+  return (
+    <ThemeProvider>
+      <div id="react-root" />
+    </ThemeProvider>
+  );
+}

web/src/api.ts

@@ -11,6 +11,9 @@ import type {
   Projects,
   RecentDirs,
   Session,
+  StructuredApprovalDecision,
+  StructuredConfigRequest,
+  StructuredPromptRequest,
   Uuid,
 } from "./types.js";
 
@@ -91,6 +94,21 @@ export async function killSession(id: Uuid, force = false): Promise<void> {
   );
 }
 
+/** Change one option advertised by a live ACP session. */
+export async function setStructuredConfig(
+  id: Uuid,
+  req: StructuredConfigRequest,
+): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredConfig(id), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(req),
+    }),
+  );
+}
+
 /** 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
@@ -152,4 +170,53 @@ export async function fetchBranches(path: string): Promise<Branches> {
   return jsonOrError(await fetch(url, { credentials: "same-origin" }));
 }
 
-export { eventsWsUrl } from "./routes.js";
+/** Send a prompt to a structured session's ACP turn (#138). `409
+ * turn_in_flight` when one is already active — the caller reflects that from
+ * `ReducedState.turn` instead of racing this call. */
+export async function sendStructuredPrompt(id: Uuid, prompt: string): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredPrompt(id), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ prompt } satisfies StructuredPromptRequest),
+    }),
+  );
+}
+
+export async function uploadStructuredFile(id: Uuid, file: File): Promise<{ path: string }> {
+  return jsonOrError(await fetch(`${routes.structuredAttachment(id)}?name=${encodeURIComponent(file.name)}`, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "content-type": "application/octet-stream" },
+    body: file,
+  }));
+}
+
+/** Cancel a structured session's active ACP turn (#138). */
+export async function cancelStructuredTurn(id: Uuid): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredCancel(id), { method: "POST", credentials: "same-origin" }),
+  );
+}
+
+/** Answer a pending ACP permission request (#139). Always resolves once the
+ * session itself is a live structured session — a nonce that is unknown or
+ * already consumed still answers `204` (docs/STRUCTURED-VIEW.md), so two
+ * clients racing the same approval never see this reject. */
+export async function resolveStructuredApproval(
+  id: Uuid,
+  nonce: string,
+  decision: StructuredApprovalDecision,
+): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredApproval(id, nonce), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(decision),
+    }),
+  );
+}
+
+export { eventsWsUrl, structuredWsUrl } from "./routes.js";

web/src/attach.ts

@@ -4,14 +4,16 @@ import { Terminal } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
 
 import { attachWsUrl } from "./routes.js";
-import { escapeHtml } from "./html.js";
 import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "./reconnect.js";
 import { applyModsToChar, cursorSeq, tildeSeq } from "./keys.js";
 import { requestToggleDrawer } from "./drawer.js";
-import { splitCommand, toolIconSvg } from "./toolIcon.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();
@@ -27,25 +29,7 @@ const webglPolicy = new WebglPolicy();
  * session ending) tears the socket down — so switching away and back is
  * instant, with scrollback already in place.
  */
-export interface AttachConnection {
-  readonly sessionId: Uuid;
-  /** The `.attach` element (header + terminal body) to mount into a pane. */
-  readonly el: HTMLElement;
-  /** Becomes the visible view: fit to the pane, focus, sync size.
-   *  `focus: false` mounts without taking the keyboard — what a sidebar
-   *  preview needs, so j/k keeps working while the pane is on screen. */
-  onMount(opts?: { focus?: boolean }): void;
-  /** Parked into the cache: keep streaming, just stop driving focus/resize. */
-  onUnmount(): void;
-  /** Put the keyboard back into this terminal — what leaving the sidebar does. */
-  focusTerminal(): void;
-  /** Type raw bytes straight into the PTY, bypassing the terminal's own key
-   *  handling — the leader's literal Ctrl-K escape hatch
-   *  (docs/COMMAND-BAR.md). */
-  sendInput(data: string): void;
-  /** Fully disconnect: close the WS, dispose the terminal, remove the element. */
-  dispose(): void;
-}
+export interface AttachConnection extends PaneConnection {}
 
 export interface AttachOptions {
   /** Invoked when the user clicks the view's explicit "disconnect" control. */
@@ -59,23 +43,6 @@ export interface AttachOptions {
   shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
 }
 
-/** What the header shows about the session (name / command). Optional — falls
- * back to a short session id when the session isn't known yet. */
-export interface AttachInfo {
-  name: string;
-  command: string;
-}
-
-/** Header echoes the sidebar: the program becomes its tool icon when we have a
- * mark for it and stays as its bare name when we do not. Arguments are
- * dropped, as on the card. */
-function commandFragment(command: string): string {
-  const { tool, program } = splitCommand(command);
-  const icon = tool ? toolIconSvg(tool) : null;
-  const text = icon ? "" : program;
-  return `<span class="at-cmd">${icon ?? ""}${text ? escapeHtml(text) : ""}</span>`;
-}
-
 export function createAttachConnection(
   sessionId: Uuid,
   opts: AttachOptions = {},
@@ -85,21 +52,19 @@ export function createAttachConnection(
   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 = info
-    ? `<span class="at-name">${escapeHtml(info.name)}</span>` +
-      (info.command && info.command !== info.name ? commandFragment(info.command) : "")
-    : `session <span class="sid">${escapeHtml(sessionId.slice(0, 8))}</span>`;
-  const titleAttr = info ? `${info.name} · ${info.command}  (${sessionId})` : sessionId;
+  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="${escapeHtml(titleAttr)}">${titleHtml}</span>
+      <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;
@@ -359,6 +324,9 @@ export function createAttachConnection(
   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;
@@ -378,6 +346,7 @@ export function createAttachConnection(
   };
 
   function connect(): void {
+    awaitingReplay = true;
     ws = new WebSocket(attachWsUrl(sessionId));
     ws.binaryType = "arraybuffer";
 
@@ -398,10 +367,20 @@ export function createAttachConnection(
         return;
       }
       if (ev.data instanceof ArrayBuffer) {
-        term.write(new Uint8Array(ev.data));
+        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".
-        ev.data.arrayBuffer().then((b) => term.write(new Uint8Array(b)));
+        void ev.data.arrayBuffer().then((b) => {
+          const replay = awaitingReplay;
+          awaitingReplay = false;
+          term.write(new Uint8Array(b), () => {
+            if (replay) term.scrollToBottom();
+          });
+        });
       }
     };
 
@@ -499,6 +478,10 @@ export function createAttachConnection(
     // 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;

web/src/catalog.ts

@@ -663,8 +663,9 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     applyNav();
   };
 
-  // Hover previews the row under the pointer (docs/PREVIEW.md). Touch is left
-  // out: there is no hover there, and a tap already opens the session.
+  // 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;
@@ -672,7 +673,7 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
     opts.onPreview?.(id);
   };
   treeHost.addEventListener("pointerover", (e) => {
-    if (e.pointerType === "touch") return;
+    if (e.pointerType === "touch" || !e.ctrlKey) return;
     const row = (e.target as HTMLElement | null)?.closest<HTMLElement>(".tree-leaf");
     setHovered(row?.dataset.sessionId ?? null);
   });

web/src/components/sidebar/ActivityRail.tsx

@@ -0,0 +1,47 @@
+// docs/SIDEBAR.md: a 5px 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-[5px] ${RAIL_CLASS[slug] ?? RAIL_CLASS.idle}`}
+      data-activity={slug}
+      role="img"
+      title={word}
+      aria-label={word}
+    />
+  );
+}

web/src/components/sidebar/ContextMenu.tsx

@@ -0,0 +1,64 @@
+// Right-click menu on a session card (docs/SIDEBAR.md): rename, spawn similar,
+// kill. Rendered into <body> so a scrolling sidebar cannot clip it.
+
+import { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+
+export interface ContextMenuItem {
+  label: string;
+  danger?: boolean;
+  onSelect(): void;
+}
+
+export interface ContextMenuProps {
+  x: number;
+  y: number;
+  items: ContextMenuItem[];
+  onClose(): void;
+}
+
+export function ContextMenu({ x, y, items, onClose }: ContextMenuProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    const onDown = (e: Event) => {
+      if (!ref.current?.contains(e.target as Node)) onClose();
+    };
+    document.addEventListener("keydown", onKey);
+    document.addEventListener("pointerdown", onDown, true);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.removeEventListener("pointerdown", onDown, true);
+    };
+  }, [onClose]);
+
+  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: x, top: y }}
+    >
+      {items.map((item) => (
+        <button
+          key={item.label}
+          type="button"
+          role="menuitem"
+          className={`block w-full px-sp-3 py-sp-1 text-left text-fs-12 hover:bg-surface-2 ${
+            item.danger ? "text-danger" : "text-ink"
+          }`}
+          onClick={() => {
+            onClose();
+            item.onSelect();
+          }}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>,
+    document.body,
+  );
+}

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/KillConfirm.tsx

@@ -0,0 +1,63 @@
+// docs/SIDEBAR.md "Killing a session": every kill confirms first, and the
+// confirmation names what the card last saw in the way — the daemon refuses an
+// unforced kill over such a tree, and saying so beforehand is cheaper than the
+// refusal. Cancel holds the focus so a stray Enter kills nothing.
+
+import { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+
+import type { InTheWay } from "../../types.js";
+import { formatInTheWay } from "../../types.js";
+
+export interface KillConfirmProps {
+  name: string;
+  blockers: InTheWay | null;
+  /** Set when the daemon already refused an unforced kill: this pass forces. */
+  force?: boolean;
+  onConfirm(): void;
+  onCancel(): void;
+}
+
+export function KillConfirm(props: KillConfirmProps) {
+  const cancel = useRef<HTMLButtonElement>(null);
+  useEffect(() => cancel.current?.focus(), []);
+
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={props.force ? "Force kill session" : "Kill session"}
+      className="kill-confirm fixed inset-0 z-modal flex items-center justify-center bg-bg/70"
+      onKeyDown={(e) => {
+        if (e.key === "Escape") props.onCancel();
+      }}
+    >
+      <div className="min-w-[280px] rounded-r-2 border border-border-strong bg-surface p-sp-4 shadow-2">
+        <p className="text-fs-13 text-ink">
+          {props.force ? "Force kill" : "Kill"} <strong>{props.name}</strong>?
+        </p>
+        {props.blockers && (
+          <p className="mt-sp-2 text-fs-12 text-warn">{formatInTheWay(props.blockers)}</p>
+        )}
+        <div className="mt-sp-3 flex justify-end gap-sp-2">
+          <button
+            ref={cancel}
+            type="button"
+            className="rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-12 text-ink"
+            onClick={props.onCancel}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            className="rounded-r-1 bg-danger px-sp-3 py-sp-1 text-fs-12 text-accent-ink"
+            onClick={props.onConfirm}
+          >
+            {props.force ? "Force kill" : "Kill"}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/sidebar/SessionCard.tsx

@@ -0,0 +1,264 @@
+// 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", furthest down
+ * wins. Written as one ordered run so the precedence is the order it reads in. */
+function rowFill(p: SessionCardProps): string {
+  if (p.active) return "bg-accent-fill";
+  if (p.previewing) return "bg-preview-tint";
+  if (p.open) return "bg-accent/[0.06]";
+  if (p.highlighted) return "bg-preview-tint";
+  return "";
+}
+
+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 relative flex flex-col gap-[1px] py-sp-1 pr-sp-2 no-underline ${rowFill(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="flex min-w-0 items-center gap-sp-2">
+        {renaming ? (
+          <RenameField
+            session={s}
+            onCommit={props.onRenameCommit}
+            onCancel={props.onRenameCancel}
+          />
+        ) : (
+          <span
+            className={`min-w-0 flex-1 truncate text-fs-13 ${
+              isProvisionalName(s) ? "text-muted" : "text-ink"
+            }`}
+          >
+            {name}
+          </span>
+        )}
+        <span className="flex flex-none items-center gap-[2px]">
+          <button
+            type="button"
+            className="leaf-clone text-faint hover:text-ink"
+            title="Spawn similar"
+            aria-label={`Spawn similar to ${name}`}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              props.onSpawnSimilar();
+            }}
+          >
+            ⧉
+          </button>
+          <button
+            type="button"
+            className="leaf-kill text-faint hover:text-danger"
+            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,227 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { Session } from "../../types.js";
+import { Sidebar } from "./Sidebar.js";
+
+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(<Sidebar sessions={[session("alpha")]} />);
+
+    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(<Sidebar sessions={[fresh, held]} />);
+
+    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(
+      <Sidebar
+        sessions={[
+          session("idle"),
+          session("await", { activity: "AwaitingInput" }),
+          session("err", { activity: "Error" }),
+        ]}
+      />,
+    );
+
+    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(
+      <Sidebar
+        sessions={[
+          session("alpha", {
+            blocked_work: { uncommitted_files: 2, insertions: 124, deletions: 18, untracked_files: 3 },
+          }),
+        ]}
+      />,
+    );
+
+    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(
+      <Sidebar
+        sessions={[
+          session("gen", { metadata: { name: "gen", name_source: "Generated" } }),
+          session("user", { metadata: { name: "user", name_source: "User" } }),
+        ]}
+      />,
+    );
+
+    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(<Sidebar sessions={two} />);
+
+    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(<Sidebar sessions={two} />);
+
+    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(<Sidebar sessions={two} onSelect={onSelect} onFocusPane={onFocusPane} />);
+
+    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(<Sidebar sessions={two} onPreview={onPreview} />);
+
+    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(<Sidebar sessions={two} onKill={onKill} />);
+
+    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(
+      <Sidebar sessions={[session("alpha")]} onSpawnSimilar={onSpawnSimilar} onKill={onKill} />,
+    );
+
+    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(<Sidebar sessions={[session("alpha")]} onRename={onRename} />);
+
+    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(<Sidebar sessions={[session("alpha"), session("beta", { cwd: "/home/n/beta" })]} />);
+
+    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(<Sidebar sessions={[]} onSpawn={onSpawn} />);
+
+    fireEvent.click(screen.getByText("+ Spawn session"));
+    expect(onSpawn).toHaveBeenCalled();
+  });
+});

web/src/components/sidebar/Sidebar.tsx

@@ -0,0 +1,368 @@
+// 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 { ContextMenu, type ContextMenuItem } from "./ContextMenu.js";
+import { FolderNode } from "./FolderNode.js";
+import { KillConfirm } from "./KillConfirm.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;
+  /** 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;
+}
+
+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]);
+
+  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 && (
+        <KillConfirm
+          name={sessionName(kill.session)}
+          blockers={kill.blockers}
+          force={kill.force}
+          onCancel={() => setKill(null)}
+          onConfirm={() => {
+            const { session: s, force } = kill;
+            setKill(null);
+            void killSession(s.id, force).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,
+                });
+              }
+            });
+          }}
+        />
+      )}
+    </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;

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,8 @@
+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 "./ContextMenu.js";
+export { KillConfirm } from "./KillConfirm.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 "../../spawnForm.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,853 @@
+// 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 "../../spawnForm.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;
+}
+
+export function SpawnForm({ seed, onChange, onSuccess }: 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 [submitting, 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
+      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>
+      <div className="flex justify-end">
+        <button
+          type="submit"
+          disabled={submitting}
+          className="rounded-r-1 bg-accent px-sp-4 py-sp-2 text-fs-13 font-semibold text-accent-ink disabled:opacity-60"
+        >
+          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,82 @@
+// 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} />
+        </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-12 text-ink"
+            onClick={onClose}
+          >
+            Cancel
+          </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/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" }));
+  });
+});

web/src/components/spawn/useFastForward.ts

@@ -0,0 +1,57 @@
+// React port of main.ts's `requestFastForward` (#67): one keystroke, every
+// spawn default resolved — most recent project (or the one the operator is
+// on), its last command, a fresh generated branch handle, worktree on with a
+// new branch. A failed POST, or any missing default, falls back to the same
+// pre-filled form `onFallback` opens, rather than a dead keystroke.
+
+import { useCallback } from "react";
+
+import { createSession, fetchNames, getDaemonInfo, projects as fetchProjects } from "../../api.js";
+import { buildFastForwardRequest, fastForwardSeed, resolveFastForward } from "../../fastForward.js";
+import { FALLBACK_PRESETS, type SpawnFormSeed } from "../../spawnForm.js";
+import type { Project, Session, SpawnPreset } from "../../types.js";
+
+export interface UseFastForwardOptions {
+  /** The project of the session the operator is currently on, if any — its
+   * base repo for a worktree session, else its cwd. Same rule the plain
+   * spawn modal's seed uses, so `N` lands where the operator currently is. */
+  focusedCwd?: string;
+  onSpawned(session: Session): void;
+  onFallback(seed: SpawnFormSeed): void;
+}
+
+async function resolvePresets(): Promise<SpawnPreset[]> {
+  try {
+    const info = await getDaemonInfo();
+    if (info.presets?.length) return info.presets;
+  } catch {
+    // keep fallbacks
+  }
+  return FALLBACK_PRESETS;
+}
+
+/** Returns a function to call on the fast-forward keystroke. */
+export function useFastForward(opts: UseFastForwardOptions): () => Promise<void> {
+  const { focusedCwd, onSpawned, onFallback } = opts;
+
+  return useCallback(async () => {
+    const [discovered, handle] = await Promise.all([
+      fetchProjects().catch(() => [] as Project[]),
+      fetchNames(1)
+        .then((batch) => batch.names[0])
+        .catch(() => undefined),
+    ]);
+    const presets = await resolvePresets();
+    const resolved = resolveFastForward(discovered, presets, handle, focusedCwd);
+    const req = buildFastForwardRequest(resolved);
+    if (req) {
+      try {
+        onSpawned(await createSession(req));
+        return;
+      } catch {
+        // degrades to the pre-filled form below, never a silent dead key
+      }
+    }
+    onFallback(fastForwardSeed(resolved));
+  }, [focusedCwd, onSpawned, onFallback]);
+}

web/src/components/terminal/KeyBar.tsx

@@ -0,0 +1,134 @@
+// React port of ../../attach.ts's `buildKeyBar` — the Termux-style special-key
+// bar for the soft keyboard (Esc/Tab/Ctrl/Alt/cursor keys/symbols it hides
+// behind a page switch). Ctrl/Alt are one-shot sticky modifiers: arming one
+// folds into the very next key, tapped here or typed on the soft keyboard,
+// then disarms.
+import { useCallback, useRef, useState } from "react";
+
+import { applyModsToChar, cursorSeq, tildeSeq } from "../../keys.js";
+
+type Modifier = "ctrl" | "alt";
+/** CSI final bytes: arrows A-D, Home `H`, End `F`. */
+type CursorFinal = "A" | "B" | "C" | "D" | "H" | "F";
+
+type KeyDef =
+  | { label: string; mod: Modifier }
+  | { label: string; cursor: CursorFinal }
+  | { label: string; tilde: number }
+  | { label: string; char: string }
+  | { label: string; seq: string };
+
+/**
+ * Row-major into an 8-column / 2-row grid (#7):
+ *
+ *     Esc  Tab  Home  ↑   End  PgUp  -  /
+ *     Ctrl Alt   ←    ↓    →   PgDn  |  ~
+ */
+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: "~" },
+];
+
+/**
+ * Pending Ctrl/Alt state plus `consume`, which folds them into a soft-keyboard
+ * character before it reaches the PTY — used by the terminal's own `onData`
+ * handler, not by this component's own button clicks.
+ */
+export function useKeyBarModifiers() {
+  const armedRef = useRef<{ ctrl: boolean; alt: boolean }>({ ctrl: false, alt: false });
+  const [, setTick] = useState(0);
+  const rerender = useCallback(() => setTick((n) => n + 1), []);
+
+  const setMod = useCallback(
+    (mod: Modifier, on: boolean) => {
+      armedRef.current[mod] = on;
+      rerender();
+    },
+    [rerender],
+  );
+
+  const clearMods = useCallback(() => {
+    if (!armedRef.current.ctrl && !armedRef.current.alt) return;
+    armedRef.current = { ctrl: false, alt: false };
+    rerender();
+  }, [rerender]);
+
+  const consume = useCallback((data: string): string => {
+    const { ctrl, alt } = armedRef.current;
+    if ((ctrl || alt) && data.length === 1) {
+      const out = applyModsToChar(data, ctrl, alt);
+      armedRef.current = { ctrl: false, alt: false };
+      return out;
+    }
+    return data;
+  }, []);
+
+  return { armed: armedRef.current, setMod, clearMods, consume };
+}
+
+export interface KeyBarProps {
+  armed: { ctrl: boolean; alt: boolean };
+  onToggleMod(mod: Modifier): void;
+  onClearMods(): void;
+  onSend(data: string): void;
+}
+
+export function KeyBar({ armed, onToggleMod, onClearMods, onSend }: KeyBarProps) {
+  return (
+    <div
+      role="toolbar"
+      aria-label="Special keys"
+      className="flex flex-wrap gap-1 border-t border-white/10 bg-black/20 p-1"
+    >
+      {KEY_DEFS.map((def) => {
+        if ("mod" in def) {
+          return (
+            <button
+              key={def.label}
+              type="button"
+              aria-pressed={armed[def.mod]}
+              aria-label={`${def.label} modifier`}
+              className="min-w-8 rounded px-2 py-1 text-xs aria-pressed:bg-emerald-500/40"
+              onClick={() => onToggleMod(def.mod)}
+            >
+              {def.label}
+            </button>
+          );
+        }
+        const bytes = () => {
+          if ("cursor" in def) return cursorSeq(def.cursor, armed.ctrl, armed.alt);
+          if ("tilde" in def) return tildeSeq(def.tilde, armed.ctrl, armed.alt);
+          if ("char" in def) return applyModsToChar(def.char, armed.ctrl, armed.alt);
+          return def.seq;
+        };
+        return (
+          <button
+            key={def.label}
+            type="button"
+            className="min-w-8 rounded px-2 py-1 text-xs"
+            onClick={() => {
+              onSend(bytes());
+              onClearMods();
+            }}
+          >
+            {def.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

web/src/components/terminal/TerminalPane.test.tsx

@@ -0,0 +1,363 @@
+// @vitest-environment happy-dom
+import { cleanup, render } from "@testing-library/react";
+import { createRef } from "react";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "../../reconnect.js";
+import { attachWsUrl } from "../../routes.js";
+import type { ClientControl } from "../../types.js";
+
+class FakeTerminal {
+  static instances: FakeTerminal[] = [];
+  cols = 80;
+  rows = 24;
+  element: HTMLElement | undefined = undefined;
+  textarea: HTMLTextAreaElement | null = null;
+  disposed = false;
+  focus = vi.fn();
+  private dataCb: ((d: string) => void) | null = null;
+
+  constructor(public opts: unknown) {
+    FakeTerminal.instances.push(this);
+  }
+  loadAddon(): void {}
+  open(container: HTMLElement): void {
+    container.appendChild(document.createElement("div"));
+  }
+  onData(cb: (d: string) => void) {
+    this.dataCb = cb;
+    return { dispose: vi.fn() };
+  }
+  emitData(d: string): void {
+    this.dataCb?.(d);
+  }
+  onResize() {
+    return { dispose: vi.fn() };
+  }
+  onSelectionChange() {
+    return { dispose: vi.fn() };
+  }
+  write(_data: Uint8Array, cb?: () => void): void {
+    cb?.();
+  }
+  scrollToBottom(): void {}
+  resize(cols: number, rows: number): void {
+    this.cols = cols;
+    this.rows = rows;
+  }
+  clearTextureAtlas(): void {}
+  getSelection(): string {
+    return "";
+  }
+  dispose(): void {
+    this.disposed = true;
+  }
+}
+
+class FakeFitAddon {
+  fit = vi.fn();
+}
+
+class FakeWebglAddon {
+  static instances: FakeWebglAddon[] = [];
+  disposed = false;
+  private lossCb: (() => void) | null = null;
+  constructor() {
+    FakeWebglAddon.instances.push(this);
+  }
+  onContextLoss(cb: () => void): void {
+    this.lossCb = cb;
+  }
+  triggerLoss(): void {
+    this.lossCb?.();
+  }
+  dispose(): void {
+    this.disposed = true;
+  }
+}
+
+const policyEnabled = vi.fn(() => true);
+const policyNoteLoss = vi.fn();
+
+vi.mock("@xterm/xterm", () => ({ Terminal: FakeTerminal }));
+vi.mock("@xterm/addon-fit", () => ({ FitAddon: FakeFitAddon }));
+vi.mock("@xterm/addon-webgl", () => ({ WebglAddon: FakeWebglAddon }));
+vi.mock("../../webglRenderer.js", () => ({
+  WebglPolicy: vi.fn().mockImplementation(() => ({
+    enabled: policyEnabled,
+    noteContextLoss: policyNoteLoss,
+  })),
+}));
+
+class FakeWebSocket {
+  static OPEN = 1;
+  static CONNECTING = 0;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static instances: FakeWebSocket[] = [];
+  readyState = FakeWebSocket.CONNECTING;
+  binaryType = "";
+  sent: (string | ArrayBufferView)[] = [];
+  onopen: (() => void) | null = null;
+  onmessage: ((ev: { data: unknown }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null = null;
+
+  constructor(public url: string) {
+    FakeWebSocket.instances.push(this);
+  }
+  send(data: string | ArrayBufferView): void {
+    this.sent.push(data);
+  }
+  close(): void {
+    this.readyState = FakeWebSocket.CLOSED;
+  }
+  open(): void {
+    this.readyState = FakeWebSocket.OPEN;
+    this.onopen?.();
+  }
+  drop(code = 1006, reason = ""): void {
+    this.readyState = FakeWebSocket.CLOSED;
+    this.onclose?.({ code, reason });
+  }
+  lastControl(): ClientControl {
+    return JSON.parse(this.sent.at(-1) as string) as ClientControl;
+  }
+}
+
+beforeAll(() => {
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe(): void {}
+      disconnect(): void {}
+      unobserve(): void {}
+    },
+  );
+});
+
+beforeEach(() => {
+  FakeTerminal.instances = [];
+  FakeWebglAddon.instances = [];
+  FakeWebSocket.instances = [];
+  policyEnabled.mockReturnValue(true);
+  policyEnabled.mockClear();
+  policyNoteLoss.mockClear();
+  vi.stubGlobal("WebSocket", FakeWebSocket);
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+// Imported after the mocks above so it picks up the mocked xterm/webgl modules.
+const { TerminalPane } = await import("./TerminalPane.js");
+
+describe("TerminalPane lifecycle", () => {
+  it("opens an xterm terminal and connects to the session's attach socket on mount", () => {
+    render(<TerminalPane sessionId="s1" />);
+
+    expect(FakeTerminal.instances).toHaveLength(1);
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    expect(FakeWebSocket.instances[0].url).toBe(attachWsUrl("s1"));
+  });
+
+  it("sends the terminal size once the socket opens", () => {
+    render(<TerminalPane sessionId="s1" />);
+    const sock = FakeWebSocket.instances[0];
+
+    sock.open();
+
+    expect(sock.lastControl()).toEqual({ type: "Resize", cols: 80, rows: 24 });
+  });
+
+  it("disposes the terminal and closes the socket on unmount", () => {
+    const { unmount } = render(<TerminalPane sessionId="s1" />);
+    const term = FakeTerminal.instances[0];
+    const sock = FakeWebSocket.instances[0];
+
+    unmount();
+
+    expect(term.disposed).toBe(true);
+    expect(sock.readyState).toBe(FakeWebSocket.CLOSED);
+  });
+
+  it("reconnects to a fresh socket for a new sessionId", () => {
+    const { rerender } = render(<TerminalPane sessionId="s1" />);
+    rerender(<TerminalPane sessionId="s2" />);
+
+    expect(FakeWebSocket.instances).toHaveLength(2);
+    expect(FakeWebSocket.instances[1].url).toBe(attachWsUrl("s2"));
+    expect(FakeTerminal.instances[0].disposed).toBe(true);
+  });
+});
+
+describe("TerminalPane reconnect backoff", () => {
+  it("retries a dropped socket, doubling the delay from 500ms up to a 10s cap", () => {
+    vi.useFakeTimers();
+    render(<TerminalPane sessionId="s1" />);
+
+    const drop = () => FakeWebSocket.instances.at(-1)!.drop(1006, "");
+    const expectStillWaiting = (ms: number, countBefore: number) => {
+      vi.advanceTimersByTime(ms - 1);
+      expect(FakeWebSocket.instances).toHaveLength(countBefore);
+      vi.advanceTimersByTime(1);
+      expect(FakeWebSocket.instances).toHaveLength(countBefore + 1);
+    };
+
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    drop();
+    expectStillWaiting(INITIAL_RECONNECT_MS, 1); // 500ms -> #2
+    drop();
+    expectStillWaiting(INITIAL_RECONNECT_MS * 2, 2); // 1000ms -> #3
+    drop();
+    expectStillWaiting(INITIAL_RECONNECT_MS * 4, 3); // 2000ms -> #4
+    drop();
+    expectStillWaiting(INITIAL_RECONNECT_MS * 8, 4); // 4000ms -> #5
+    drop();
+    expectStillWaiting(INITIAL_RECONNECT_MS * 16, 5); // 8000ms -> #6
+    drop();
+    expectStillWaiting(MAX_RECONNECT_MS, 6); // capped at 10s -> #7
+    drop();
+    expectStillWaiting(MAX_RECONNECT_MS, 7); // stays capped -> #8
+  });
+
+  it("resets the backoff once a reconnected socket opens", () => {
+    vi.useFakeTimers();
+    render(<TerminalPane sessionId="s1" />);
+
+    FakeWebSocket.instances[0].drop(1006, "");
+    vi.advanceTimersByTime(INITIAL_RECONNECT_MS);
+    FakeWebSocket.instances[1].open();
+    FakeWebSocket.instances[1].drop(1006, "");
+
+    vi.advanceTimersByTime(INITIAL_RECONNECT_MS - 1);
+    expect(FakeWebSocket.instances).toHaveLength(2);
+    vi.advanceTimersByTime(1);
+    expect(FakeWebSocket.instances).toHaveLength(3);
+  });
+
+  it("does not retry a clean close, and reports it closed", () => {
+    vi.useFakeTimers();
+    const onClosed = vi.fn();
+    render(<TerminalPane sessionId="s1" onClosed={onClosed} />);
+
+    FakeWebSocket.instances[0].drop(1000, "");
+    vi.advanceTimersByTime(MAX_RECONNECT_MS * 2);
+
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    expect(onClosed).toHaveBeenCalledOnce();
+  });
+
+  it("does not retry an application-level rejection, and writes it into the terminal", () => {
+    vi.useFakeTimers();
+    const onClosed = vi.fn();
+    render(<TerminalPane sessionId="s1" onClosed={onClosed} />);
+    const term = FakeTerminal.instances[0];
+    const writeSpy = vi.spyOn(term, "write");
+
+    FakeWebSocket.instances[0].drop(4004, "unknown session");
+    vi.advanceTimersByTime(MAX_RECONNECT_MS * 2);
+
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    expect(onClosed).not.toHaveBeenCalled();
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining("unknown session"));
+  });
+
+  it("honors a caller-supplied shouldReconnect policy", () => {
+    vi.useFakeTimers();
+    const onClosed = vi.fn();
+    render(<TerminalPane sessionId="s1" shouldReconnect={() => false} onClosed={onClosed} />);
+
+    FakeWebSocket.instances[0].drop(1006, "");
+    vi.advanceTimersByTime(MAX_RECONNECT_MS * 2);
+
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    expect(onClosed).toHaveBeenCalledOnce();
+  });
+});
+
+describe("TerminalPane WebGL context budget", () => {
+  it("acquires a WebGL context on mount, shared policy allowing", () => {
+    render(<TerminalPane sessionId="s1" />);
+
+    expect(policyEnabled).toHaveBeenCalled();
+    expect(FakeWebglAddon.instances).toHaveLength(1);
+  });
+
+  it("never creates a context once the shared budget is exhausted", () => {
+    policyEnabled.mockReturnValue(false);
+    render(<TerminalPane sessionId="s1" />);
+
+    expect(FakeWebglAddon.instances).toHaveLength(0);
+  });
+
+  it("releases its context on unmount, handing the budget back", () => {
+    const { unmount } = render(<TerminalPane sessionId="s1" />);
+    const addon = FakeWebglAddon.instances[0];
+
+    unmount();
+
+    expect(addon.disposed).toBe(true);
+  });
+
+  it("counts a context loss and re-acquires while still mounted", () => {
+    render(<TerminalPane sessionId="s1" />);
+    const first = FakeWebglAddon.instances[0];
+
+    first.triggerLoss();
+
+    expect(policyNoteLoss).toHaveBeenCalledOnce();
+    expect(first.disposed).toBe(true);
+    expect(FakeWebglAddon.instances).toHaveLength(2);
+  });
+
+  it("does not re-acquire a lost context once the budget is spent", () => {
+    render(<TerminalPane sessionId="s1" />);
+    const first = FakeWebglAddon.instances[0];
+    policyEnabled.mockReturnValue(false);
+
+    first.triggerLoss();
+
+    expect(FakeWebglAddon.instances).toHaveLength(1);
+  });
+});
+
+describe("TerminalPane imperative handle", () => {
+  it("sendInput writes bytes to the PTY only once the socket is open", () => {
+    const ref = createRef<import("./TerminalPane.js").TerminalPaneHandle>();
+    render(<TerminalPane sessionId="s1" ref={ref} />);
+    const sock = FakeWebSocket.instances[0];
+
+    ref.current!.sendInput("nope");
+    expect(sock.sent).toHaveLength(0);
+
+    sock.open();
+    sock.sent.length = 0; // drop the resize control frame from open()
+    ref.current!.sendInput("hi");
+
+    expect(sock.sent).toHaveLength(1);
+    expect(new TextDecoder().decode(sock.sent[0] as Uint8Array)).toBe("hi");
+  });
+
+  it("focusTerminal focuses the underlying xterm instance", () => {
+    const ref = createRef<import("./TerminalPane.js").TerminalPaneHandle>();
+    render(<TerminalPane sessionId="s1" ref={ref} />);
+
+    ref.current!.focusTerminal();
+
+    expect(FakeTerminal.instances[0].focus).toHaveBeenCalledOnce();
+  });
+
+  it("routes typed keystrokes through to the socket", () => {
+    render(<TerminalPane sessionId="s1" />);
+    const sock = FakeWebSocket.instances[0];
+    sock.open();
+    sock.sent.length = 0;
+
+    FakeTerminal.instances[0].emitData("q");
+
+    expect(new TextDecoder().decode(sock.sent[0] as Uint8Array)).toBe("q");
+  });
+});

web/src/components/terminal/TerminalPane.tsx

@@ -0,0 +1,362 @@
+// React port of ../../attach.ts: an xterm terminal bound to the daemon's
+// attach WebSocket, plus ../../webglRenderer.ts's shared GPU-context budget
+// and ../../reconnect.ts's backoff schedule. Pane chrome (title, disconnect
+// button, sessions drawer) stays out of scope here — this is the thin
+// ref-based xterm wrapper the issue asked for; a header composes around it.
+import { FitAddon } from "@xterm/addon-fit";
+import { WebglAddon } from "@xterm/addon-webgl";
+import { Terminal } from "@xterm/xterm";
+import "@xterm/xterm/css/xterm.css";
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
+
+import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "../../reconnect.js";
+import { attachWsUrl } from "../../routes.js";
+import type { ClientControl, Uuid } from "../../types.js";
+import { WebglPolicy } from "../../webglRenderer.js";
+import { KeyBar, useKeyBarModifiers } from "./KeyBar.js";
+
+/** One budget for the whole page — every mounted `TerminalPane` shares it, the
+ *  same reasoning as attach.ts's own module-level policy. */
+const webglPolicy = new WebglPolicy();
+
+export type TerminalStatus = "connecting" | "open" | "reconnecting" | "closed" | "error";
+
+/** Application-defined close codes (daemon rejection) and the clean-close
+ *  code — retrying either would only loop. Mirrors reconnect.ts's
+ *  `shouldRetryClose`, minus the catalog lookup a standalone pane doesn't have. */
+function defaultShouldReconnect(code: number): boolean {
+  return code < 4000 && code !== 1000;
+}
+
+export interface TerminalPaneProps {
+  sessionId: Uuid;
+  /** Grabs the keyboard once the socket opens. A sidebar preview passes `false`. */
+  focus?: boolean;
+  /** Asked on every close: should the socket be retried? */
+  shouldReconnect?: (code: number) => boolean;
+  /** The socket closed for good (retry declined, or the daemon rejected the
+   *  session) — not called on an ordinary unmount. */
+  onClosed?: () => void;
+  /** Connection status changes, for a header/status badge to render. */
+  onStatusChange?: (status: TerminalStatus, detail?: string) => void;
+  className?: string;
+}
+
+export interface TerminalPaneHandle {
+  focusTerminal(): void;
+  sendInput(data: string): void;
+}
+
+export const TerminalPane = forwardRef<TerminalPaneHandle, TerminalPaneProps>(
+  function TerminalPane(
+    { sessionId, focus = true, shouldReconnect = defaultShouldReconnect, onClosed, onStatusChange, className },
+    ref,
+  ) {
+    const bodyRef = useRef<HTMLDivElement | null>(null);
+    const sendInputRef = useRef<(data: string) => void>(() => {});
+    const focusTerminalRef = useRef<() => void>(() => {});
+    const keyBar = useKeyBarModifiers();
+    const [keybarActive, setKeybarActive] = useState(false);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        focusTerminal: () => focusTerminalRef.current(),
+        sendInput: (data: string) => sendInputRef.current(data),
+      }),
+      [],
+    );
+
+    useEffect(() => {
+      const body = bodyRef.current;
+      if (!body) return;
+
+      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: {
+          background: "#121419",
+          foreground: "#e6e8ec",
+          cursor: "#5fe3a1",
+          cursorAccent: "#121419",
+          selectionBackground: "#2b6b4f",
+        },
+        scrollback: 5000,
+        allowProposedApi: true,
+      });
+      const fit = new FitAddon();
+      term.loadAddon(fit);
+      term.open(body);
+
+      let webgl: WebglAddon | null = null;
+      let dprMedia: MediaQueryList | null = null;
+
+      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
+        }
+      }
+
+      function releaseWebgl(): void {
+        dprMedia?.removeEventListener("change", onDprChange);
+        dprMedia = null;
+        if (!webgl) return;
+        const addon = webgl;
+        webgl = null;
+        try {
+          addon.dispose();
+        } 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();
+          addon.onContextLoss(() => {
+            webglPolicy.noteContextLoss();
+            releaseWebgl();
+            if (mounted) acquireWebgl();
+          });
+          term.loadAddon(addon);
+          webgl = addon;
+          watchDpr();
+        } catch {
+          webglPolicy.noteContextLoss();
+          webgl = null;
+        }
+      }
+
+      let mounted = false;
+      const tryFit = () => {
+        if (!mounted) return;
+        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();
+            return;
+          }
+          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;
+      let awaitingReplay = true;
+      let disposed = false;
+
+      const sendControl = (msg: ClientControl) => {
+        if (ws.readyState !== WebSocket.OPEN) return;
+        ws.send(JSON.stringify(msg));
+      };
+
+      const sendInput = (data: string) => {
+        if (ws.readyState !== WebSocket.OPEN) return;
+        ws.send(new TextEncoder().encode(data));
+      };
+      sendInputRef.current = sendInput;
+      focusTerminalRef.current = () => term.focus();
+
+      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;
+          onStatusChange?.("open");
+          sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
+          if (mounted && focus) 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) {
+            void ev.data.arrayBuffer().then((b) => {
+              const replay = awaitingReplay;
+              awaitingReplay = false;
+              term.write(new Uint8Array(b), () => {
+                if (replay) term.scrollToBottom();
+              });
+            });
+          }
+        };
+
+        ws.onerror = () => {
+          onStatusChange?.("error");
+        };
+
+        ws.onclose = (ev) => {
+          const reason = ev.reason?.trim();
+          if (ev.code >= 4000 && reason && !disposed) {
+            onStatusChange?.("error", reason);
+            term.write(`\r\n\x1b[31m⚠ cannot attach: ${reason}\x1b[0m\r\n`);
+            return;
+          }
+          if (disposed) return;
+
+          if (shouldReconnect(ev.code)) {
+            const delay = Math.min(reconnectMs, MAX_RECONNECT_MS);
+            onStatusChange?.("reconnecting");
+            reconnectTimer = window.setTimeout(() => {
+              reconnectTimer = null;
+              reconnectMs = Math.min(reconnectMs * 2, MAX_RECONNECT_MS);
+              connect();
+            }, delay);
+            return;
+          }
+
+          onStatusChange?.("closed", String(ev.code));
+          onClosed?.();
+        };
+      }
+
+      onStatusChange?.("connecting");
+      connect();
+
+      const dataDisp = term.onData((data) => {
+        sendInput(keyBar.consume(data));
+      });
+      const resizeDisp = term.onResize(({ cols, rows }) => {
+        sendControl({ type: "Resize", cols, rows });
+      });
+      const selectionDisp = term.onSelectionChange(() => {
+        const text = term.getSelection();
+        if (text) void navigator.clipboard?.writeText(text).catch(() => {});
+      });
+
+      const ta = term.textarea;
+      const onTaFocus = () => {
+        setKeybarActive(true);
+        requestAnimationFrame(tryFit);
+      };
+      const onTaBlur = () => {
+        setKeybarActive(false);
+        requestAnimationFrame(tryFit);
+      };
+      ta?.addEventListener("focus", onTaFocus);
+      ta?.addEventListener("blur", onTaBlur);
+
+      window.addEventListener("resize", onResize);
+      const visual = window.visualViewport ?? null;
+      visual?.addEventListener("resize", onResize);
+
+      const ro = new ResizeObserver(() => tryFit());
+      ro.observe(body);
+      document.fonts?.ready?.then(() => tryFit()).catch(() => {});
+
+      mounted = true;
+      acquireWebgl();
+      requestAnimationFrame(() => {
+        tryFit();
+        sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
+        if (focus && ws.readyState === WebSocket.OPEN) term.focus();
+      });
+
+      return () => {
+        disposed = true;
+        mounted = false;
+        if (reconnectTimer !== null) {
+          window.clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+        }
+        ro.disconnect();
+        window.removeEventListener("resize", onResize);
+        visual?.removeEventListener("resize", onResize);
+        ta?.removeEventListener("focus", onTaFocus);
+        ta?.removeEventListener("blur", onTaBlur);
+        dataDisp.dispose();
+        resizeDisp.dispose();
+        selectionDisp.dispose();
+        releaseWebgl();
+        try {
+          ws.close();
+        } catch {
+          // ignore
+        }
+        term.dispose();
+      };
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- reconnecting
+      // a session change is a fresh connection, not a prop-driven re-render
+    }, [sessionId]);
+
+    return (
+      <div className={className ? `flex h-full flex-col ${className}` : "flex h-full flex-col"}>
+        <div ref={bodyRef} className="min-h-0 flex-1" />
+        {keybarActive && (
+          <KeyBar
+            armed={keyBar.armed}
+            onToggleMod={(mod) => keyBar.setMod(mod, !keyBar.armed[mod])}
+            onClearMods={keyBar.clearMods}
+            onSend={(data) => sendInputRef.current(data)}
+          />
+        )}
+      </div>
+    );
+  },
+);

web/src/connections.test.ts

@@ -2,28 +2,84 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { ConnectionPool } from "./connections.js";
+import { CatalogStore } from "./events.js";
+import type { Session } from "./types.js";
 
 // The pane's own bytes-out path, stubbed: the escape hatch only needs to know
 // the pool reaches the focused connection with them.
 const sent: { id: string; data: string }[] = [];
-vi.mock("./attach.js", () => ({
-  createAttachConnection: (id: string) => ({
+const disposed: string[] = [];
+const mounts: { id: string; focus: boolean | undefined }[] = [];
+function fakeConn(kind: string, id: string) {
+  const el = document.createElement("div");
+  el.tabIndex = -1; // focusable via .focus(), like a real input/terminal
+  el.dataset.kind = kind;
+  el.dataset.session = id;
+  return {
     sessionId: id,
-    el: document.createElement("div"),
-    onMount() {},
+    kind,
+    el,
+    onMount(opts?: { focus?: boolean }) {
+      mounts.push({ id, focus: opts?.focus });
+    },
     onUnmount() {},
     focusTerminal() {},
     sendInput(data: string) {
       sent.push({ id, data });
     },
-    dispose() {},
-  }),
+    updateInfo() {},
+    dispose() {
+      disposed.push(`${kind}:${id}`);
+    },
+  };
+}
+vi.mock("./attach.js", () => ({
+  createAttachConnection: (id: string) => fakeConn("attach", id),
+}));
+vi.mock("./structured.js", () => ({
+  createStructuredConnection: (id: string) => fakeConn("structured", id),
 }));
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  sent.length = 0;
+  disposed.length = 0;
+  mounts.length = 0;
 });
 
+/** Minimal fixture for the `CatalogState` a `CatalogStore` broadcasts. */
+function session(id: string, view?: "Terminal" | "Structured"): Session {
+  return {
+    id,
+    cwd: "/repo",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    view,
+  };
+}
+
+/** A `CatalogStore` an id can be pushed into on demand, mirroring
+ *  events.test.ts's own injectable-socket pattern. */
+class FakeCatalogSocket {
+  onmessage: ((ev: { data: string }) => void) | null = null;
+  onopen: (() => void) | null = null;
+  onclose: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  close(): void {}
+  push(sessions: Session[]): void {
+    this.onmessage?.({ data: JSON.stringify({ type: "Snapshot", sessions }) });
+  }
+}
+function fakeStore(): { store: CatalogStore; socket: FakeCatalogSocket } {
+  const socket = new FakeCatalogSocket();
+  const store = new CatalogStore({ socket: () => socket as unknown as WebSocket });
+  store.start();
+  return { store, socket };
+}
+
 const A = "aaaaaaaa-0000-0000-0000-0000000000ff";
 const B = "bbbbbbbb-0000-0000-0000-0000000000ff";
 
@@ -125,3 +181,203 @@ describe("ConnectionPool.sendToFocused", () => {
     expect(sent).toEqual([]);
   });
 });
+
+// A deep link or restored layout can `mount()` a session before the catalog
+// snapshot names its view — the daemon defaults an absent `view` to
+// `"Terminal"`, but so does an *unknown* session, and only one of those is
+// actually resolved (#140 review).
+describe("ConnectionPool: view resolution races", () => {
+  it("replaces a wrongly-typed connection once the catalog resolves it, without waiting for another mount()", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+
+    pool.mount(A, pane); // no info: deep-link-before-snapshot race
+    expect(disposed).toEqual([]);
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    // The fresh connection landed in the same pane nothing re-mounted it into.
+    expect(pane.children).toHaveLength(1);
+  });
+
+  it("also repairs a wrongly-typed connection that is parked, not mounted, without evicting its other parked siblings", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const hidden = document.body.lastElementChild as HTMLElement; // this pool's own cache
+    pool.mount(A, document.createElement("div"));
+    pool.mount(B, document.createElement("div"));
+    pool.unmount(A);
+    pool.unmount(B);
+    disposed.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    // B's own element is still parked — A's repair didn't wipe its siblings
+    // out of the shared hidden cache.
+    expect(hidden.querySelector(`[data-session="${B}"]`)).not.toBeNull();
+    expect((hidden.querySelector(`[data-session="${A}"]`) as HTMLElement | null)?.dataset.kind).toBe("structured");
+  });
+
+  it("does not replace a connection whose resolved view already matches", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    pool.mount(A, pane, { name: "a", command: "claude", view: "Structured" });
+    disposed.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual([]);
+  });
+
+  it("does not downgrade an already-resolved connection when a later mount() call has no info", () => {
+    mockFetch();
+    const pool = new ConnectionPool();
+    const pane = document.createElement("div");
+    pool.mount(A, pane, { name: "a", command: "claude", view: "Structured" });
+    disposed.length = 0;
+
+    pool.mount(A, pane); // e.g. a re-render before the catalog answers again
+
+    expect(disposed).toEqual([]);
+  });
+
+  it("does not treat a session missing from the catalog as Terminal and churn a live connection", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    pool.mount(A, pane, { name: "a", command: "claude", view: "Structured" });
+    disposed.length = 0;
+
+    // `A` is absent from this snapshot — main.ts's own subscription handles
+    // closing the pane; the pool must not race it by "fixing" the view first.
+    socket.push([session(B, "Terminal")]);
+
+    expect(disposed).toEqual([]);
+  });
+
+  it("re-focuses the fresh connection when the keyboard was actually inside the replaced pane", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    document.body.appendChild(pane);
+    pool.mount(A, pane);
+    pool.setFocus(A);
+    (pane.firstElementChild as HTMLElement).focus();
+    expect(document.activeElement).toBe(pane.firstElementChild);
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    expect(mounts).toEqual([{ id: A, focus: true }]);
+    pane.remove();
+  });
+
+  it("does not steal focus from a same-tab sidebar preview even though focusedId still names the previous pane", () => {
+    // docs/PREVIEW.md: previewing a session already open in the current tab
+    // moves the keyboard into the sidebar without ever calling setFocus, so
+    // `focusedId` keeps naming the pane the operator was in before — but the
+    // DOM disagrees, and the DOM is what must decide.
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    document.body.appendChild(pane);
+    pool.mount(A, pane);
+    pool.setFocus(A);
+    (pane.firstElementChild as HTMLElement).focus();
+
+    const sidebarInput = document.createElement("input");
+    document.body.appendChild(sidebarInput);
+    sidebarInput.focus();
+    expect(document.activeElement).toBe(sidebarInput);
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    expect(mounts).toEqual([{ id: A, focus: false }]);
+    pane.remove();
+    sidebarInput.remove();
+  });
+
+  it("counts focus on a descendant of the pane's element, not just the element itself", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    document.body.appendChild(pane);
+    pool.mount(A, pane);
+    pool.setFocus(A);
+    const textarea = document.createElement("textarea");
+    (pane.firstElementChild as HTMLElement).appendChild(textarea);
+    textarea.focus();
+    expect(document.activeElement).toBe(textarea);
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(mounts).toEqual([{ id: A, focus: true }]);
+    pane.remove();
+  });
+
+  it("treats document.body (nothing meaningfully focused) as no active descendant", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    document.body.appendChild(pane);
+    pool.mount(A, pane);
+    pool.setFocus(A);
+    (document.activeElement as HTMLElement | null)?.blur();
+    expect(document.activeElement).toBe(document.body);
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(mounts).toEqual([{ id: A, focus: false }]);
+    pane.remove();
+  });
+
+  it("does not steal focus for a merely-visible pane that was never actually focused", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const paneA = document.createElement("div");
+    const paneB = document.createElement("div");
+    pool.mount(A, paneA);
+    pool.mount(B, paneB);
+    pool.setFocus(B); // B is the real keyboard focus; A is only visible
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    expect(mounts).toEqual([{ id: A, focus: false }]);
+  });
+
+  it("does not focus a parked (unmounted) connection it repairs", () => {
+    mockFetch();
+    const { store, socket } = fakeStore();
+    const pool = new ConnectionPool({ store });
+    const pane = document.createElement("div");
+    pool.mount(A, pane);
+    pool.setFocus(A);
+    pool.unmount(A); // parked — no longer visible, `focusedId` still names it
+    mounts.length = 0;
+
+    socket.push([session(A, "Structured")]);
+
+    expect(disposed).toEqual(["attach:" + A]);
+    expect(mounts).toEqual([]); // parked repair calls onUnmount, never onMount
+  });
+});

web/src/connections.ts

@@ -1,10 +1,10 @@
-import {
-  createAttachConnection,
-  type AttachConnection,
-  type AttachInfo,
-} from "./attach.js";
+import { createAttachConnection } from "./attach.js";
+import type { AttachInfo } from "./paneTitle.js";
+import type { PaneConnection } from "./pane.js";
+import { createStructuredConnection } from "./structured.js";
 import { setSessionFocus } from "./api.js";
-import type { Uuid } from "./types.js";
+import type { CatalogState, CatalogStore } from "./events.js";
+import { sessionName, type SessionView, type Uuid } from "./types.js";
 
 /**
  * How many *parked* (off-screen but still-connected) sessions to keep warm
@@ -16,6 +16,15 @@ import type { Uuid } from "./types.js";
  */
 const MAX_PARKED = 6;
 
+/** A session's view defaults to `"Terminal"` wherever it isn't carried —
+ *  matching the wire default (`SessionView`'s `#[default]`, types.ts). Only
+ *  meaningful once the session itself is known; an altogether-unknown
+ *  session (no `AttachInfo`/`Session` at all) is a distinct, un-resolved
+ *  state callers must check for separately, not "Terminal". */
+function resolveView(view: SessionView | undefined): SessionView {
+  return view ?? "Terminal";
+}
+
 export interface PoolOptions {
   /** Fired when the focused session changes (drives sidebar highlight + HUD). */
   onFocusChange?: (id: Uuid | null) => void;
@@ -27,6 +36,9 @@ export interface PoolOptions {
   onClosed?: (id: Uuid) => void;
   /** Forwarded to each connection: should a dropped socket be retried? */
   shouldReconnect?: (id: Uuid, code: number) => boolean;
+  /** Threaded through to a structured connection so its rail can read live
+   *  worktree/git-status data (#140). Terminal connections don't need it. */
+  store?: CatalogStore;
 }
 
 /**
@@ -40,12 +52,19 @@ export interface PoolOptions {
  */
 export class ConnectionPool {
   /** All live connections. Insertion order doubles as LRU: oldest first. */
-  private readonly cache = new Map<Uuid, AttachConnection>();
+  private readonly cache = new Map<Uuid, PaneConnection>();
+  /** The view each cached connection was actually created for — a deep link
+   *  or a restored layout can `mount()` a session before the catalog
+   *  snapshot names its view, defaulting it to `"Terminal"`; this is what
+   *  lets a later reconciliation notice the resolved view disagrees (#140
+   *  review). */
+  private readonly connViews = new Map<Uuid, SessionView>();
   /** Sessions currently mounted into a visible pane (never evicted). */
   private readonly mounted = new Set<Uuid>();
   private readonly hidden: HTMLElement;
   private focusedId: Uuid | null = null;
   private readonly opts: PoolOptions;
+  private readonly unsubscribeStore?: () => void;
 
   constructor(opts: PoolOptions = {}) {
     this.opts = opts;
@@ -54,6 +73,11 @@ export class ConnectionPool {
     this.hidden.className = "conn-cache";
     this.hidden.setAttribute("aria-hidden", "true");
     document.body.appendChild(this.hidden);
+    // A session `mount()`ed before its catalog entry exists gets a
+    // `"Terminal"` connection by default; once the snapshot actually names
+    // the view, fix any connection that guessed wrong — nothing else
+    // re-`mount()`s an already-open pane just because the catalog updated.
+    this.unsubscribeStore = opts.store?.subscribe((state) => this.reconcileViews(state));
   }
 
   /** The focused session, or null when nothing is focused (welcome pane). */
@@ -77,18 +101,19 @@ export class ConnectionPool {
   mount(id: Uuid, pane: HTMLElement, info?: AttachInfo, opts?: { focus?: boolean }): void {
     let conn = this.cache.get(id);
     if (conn) {
-      this.cache.delete(id);
-      this.cache.set(id, conn);
+      // `info === undefined` means "session not known yet", not "Terminal" —
+      // never downgrade a resolved connection just because a later caller
+      // couldn't resolve the session. Only a *resolved* view that disagrees
+      // with what this connection was built for forces a replace.
+      if (info !== undefined && resolveView(info.view) !== this.connViews.get(id)) {
+        conn = this.replace(id, info);
+      } else {
+        this.cache.delete(id);
+        this.cache.set(id, conn); // LRU refresh
+        if (info) conn.updateInfo(info);
+      }
     } else {
-      conn = createAttachConnection(
-        id,
-        {
-          onRequestClose: (sid) => this.opts.onRequestClose?.(sid),
-          onClosed: (sid) => this.opts.onClosed?.(sid),
-          shouldReconnect: (sid, code) => this.opts.shouldReconnect?.(sid, code) ?? false,
-        },
-        info,
-      );
+      conn = this.create(id, info);
       this.cache.set(id, conn);
     }
     if (conn.el.parentElement !== pane) {
@@ -101,6 +126,71 @@ export class ConnectionPool {
     this.evict();
   }
 
+  private create(id: Uuid, info?: AttachInfo): PaneConnection {
+    const view = resolveView(info?.view);
+    this.connViews.set(id, view);
+    const connOpts = {
+      onRequestClose: (sid: Uuid) => this.opts.onRequestClose?.(sid),
+      onClosed: (sid: Uuid) => this.opts.onClosed?.(sid),
+      shouldReconnect: (sid: Uuid, code: number) => this.opts.shouldReconnect?.(sid, code) ?? false,
+    };
+    return view === "Structured"
+      ? createStructuredConnection(id, connOpts, info, this.opts.store)
+      : createAttachConnection(id, connOpts, info);
+  }
+
+  /** Dispose whatever is cached for `id` and cache a freshly created
+   *  connection in its place. Does not touch the DOM or `mounted` — callers
+   *  place the new element themselves. */
+  private replace(id: Uuid, info?: AttachInfo): PaneConnection {
+    this.cache.get(id)?.dispose();
+    const fresh = this.create(id, info);
+    this.cache.set(id, fresh);
+    return fresh;
+  }
+
+  /** Proactively fix any cached connection whose view no longer matches the
+   *  catalog — the only path that repairs a pane nothing will `mount()`
+   *  again on its own (parked, or mounted but not currently being
+   *  re-rendered by anything else). A session absent from `state` (not yet
+   *  known, or removed) is left alone — that's `main.ts`'s
+   *  `closePane`/eviction concern, not a view mismatch. */
+  private reconcileViews(state: CatalogState): void {
+    for (const id of [...this.cache.keys()]) {
+      const session = state.sessions.get(id);
+      if (session === undefined || resolveView(session.view) === this.connViews.get(id)) continue;
+      const existing = this.cache.get(id)!;
+      const parent = existing.el.parentElement;
+      const wasMounted = this.mounted.has(id);
+      // Capture before anything below touches the DOM: dispose()/el.remove()
+      // detach `existing.el`, and once a focused descendant is detached the
+      // browser moves `document.activeElement` to `<body>` — too late to
+      // tell whether the keyboard was actually in this pane.
+      const hadDomFocus = existing.el.contains(document.activeElement);
+      const info: AttachInfo = { name: sessionName(session), command: session.command, view: session.view };
+      const fresh = this.replace(id, info);
+      existing.el.remove(); // don't rely on dispose() to clear the DOM
+      if (parent && parent !== this.hidden) {
+        parent.replaceChildren(fresh.el);
+      } else {
+        // Parked: `this.hidden` holds every parked connection's element as
+        // siblings — append, never replaceChildren, or they'd all vanish.
+        this.hidden.appendChild(fresh.el);
+      }
+      if (wasMounted) {
+        // `focusedId` names the session the pool was last told to focus —
+        // but a same-tab sidebar preview moves the keyboard into the
+        // sidebar without clearing it (multiview.ts skips `setFocus` while
+        // previewing), so `focusedId` alone can point at a pane the
+        // keyboard already left. Only re-focus when the DOM agrees it
+        // never did.
+        fresh.onMount({ focus: this.focusedId === id && hadDomFocus });
+      } else {
+        fresh.onUnmount();
+      }
+    }
+  }
+
   /** Park `id` back into the hidden cache (still connected) and stop showing it. */
   unmount(id: Uuid): void {
     if (!this.mounted.delete(id)) return;
@@ -177,13 +267,16 @@ export class ConnectionPool {
     if (!conn) return;
     conn.dispose();
     this.cache.delete(id);
+    this.connViews.delete(id);
     this.mounted.delete(id);
     if (this.focusedId === id) this.setFocus(null);
   }
 
   dispose(): void {
+    this.unsubscribeStore?.();
     for (const conn of this.cache.values()) conn.dispose();
     this.cache.clear();
+    this.connViews.clear();
     this.mounted.clear();
     this.hidden.remove();
   }