feat(maestro): port layout system (tabs, splits, multiview) to React

Closes #249: layoutStore.ts wraps the existing layout.ts tree model
in Zustand, persisting to localStorage on a 400ms debounce and adding
boot reconciliation to prune leaves for sessions no longer live.
MultiView/TabBar/PaneContainer/PaneTitle render tabs, nested splits
with draggable dividers, drag-and-drop tab reordering, and dispatch
each pane to TerminalPane or StructuredPane by session view.

Preview mode (#251) and sidebar drag-to-dock stay out of scope here.

.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:*)"
+    ]
+  }
+}

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",

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,30 +42,62 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use agent_client_protocol::schema::v1::{
-    CancelNotification, ClientCapabilities, ContentBlock, FileSystemCapabilities, Implementation,
-    InitializeRequest, LoadSessionRequest, NewSessionRequest, PromptRequest,
-    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
@@ -78,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)]
@@ -94,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 {
@@ -103,6 +206,7 @@ impl SpawnConfig {
             env,
             handshake_timeout: HANDSHAKE_TIMEOUT,
             load_session: None,
+            adapter: AcpAdapter::ClaudeCode,
         }
     }
 
@@ -111,6 +215,11 @@ 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.
@@ -126,31 +235,39 @@ pub struct PermissionRequest {
 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))
 }
 
@@ -168,9 +285,20 @@ enum Command {
         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>),
@@ -301,6 +429,23 @@ impl AcpSession {
         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) {
@@ -341,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)
@@ -369,18 +516,27 @@ 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);
     let (child_commands_tx, child_commands_rx) = mpsc::unbounded_channel();
-    tokio::spawn(supervise_child(child, pid, child_commands_rx, exit_tx));
+    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();
@@ -389,8 +545,11 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
     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,
@@ -423,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()
@@ -457,12 +617,13 @@ async fn supervise_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, "{ADAPTER_BIN} exited");
+                tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                 let _ = exit_tx.send(status);
                 return;
             }
@@ -476,7 +637,7 @@ async fn supervise_child(
                 Some(ChildCommand::Reap(done)) => match child.try_wait() {
                     Ok(Some(status)) => {
                         let _ = done.send(true);
-                        tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                        tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                         let _ = exit_tx.send(Some(status));
                         return;
                     }
@@ -484,7 +645,7 @@ async fn supervise_child(
                         let _ = done.send(false);
                     }
                     Err(error) => {
-                        tracing::warn!(pid, %error, "could not reap {ADAPTER_BIN}");
+                        tracing::warn!(pid, %error, provider = %adapter, "could not reap ACP adapter");
                         let _ = done.send(false);
                     }
                 },
@@ -494,7 +655,7 @@ async fn supervise_child(
                     // a reused PID.
                     unsafe { libc::kill(pid as libc::pid_t, libc::SIGTERM) };
                     let status = child.wait().await.ok();
-                    tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                    tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                     let _ = exit_tx.send(status);
                     return;
                 }
@@ -513,10 +674,104 @@ 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>,
@@ -534,6 +789,7 @@ async fn run_connection<T>(
     // 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")
@@ -544,7 +800,7 @@ 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!(),
@@ -589,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(());
                     }
@@ -601,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 {
@@ -613,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(());
@@ -625,21 +887,48 @@ 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 {
@@ -689,6 +978,83 @@ async fn run_connection<T>(
                                 }
                             }
                         }
+                        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,
@@ -706,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

@@ -36,6 +36,7 @@ Environment knobs, all optional:
   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
 
@@ -78,6 +79,41 @@ 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):
@@ -139,7 +175,7 @@ for raw in sys.stdin:
         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": {"sessionId": session_id}})
+        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)
@@ -152,8 +188,18 @@ 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"))

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 }
     }
 
@@ -146,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();
@@ -180,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();
@@ -225,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");
@@ -284,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}");
         }
@@ -320,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");
@@ -353,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)
@@ -368,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");
@@ -392,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/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,7 +3,7 @@
 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, SessionView, WorktreeSpec,
@@ -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)
 }
 
@@ -199,6 +228,7 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             ActivityState::Idle => "idle",
             ActivityState::AwaitingInput => "awaiting",
             ActivityState::Error => "error",
+            ActivityState::Starting => "starting",
         };
         // Show the live foreground command alongside the spawn command when
         // the daemon has observed one that differs (NAP-340).
@@ -239,6 +269,62 @@ mod tests {
 
     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(),

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

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

crates/maestro-daemon/src/local_api.rs

@@ -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,13 @@ use maestro_config::SpawnPreset;
 use maestro_protocol::{
     routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch,
     RenameSessionRequest, ReportActivityRequest, SendInputRequest, Session, SetFocusRequest,
-    StructuredApprovalDecision, StructuredEvent, StructuredPromptRequest, PROTOCOL_VERSION,
+    StructuredApprovalDecision, StructuredConfigRequest, StructuredEvent, StructuredPromptRequest,
+    PROTOCOL_VERSION,
 };
 use serde::Deserialize;
 use uuid::Uuid;
 
-use crate::session::{QueueAcpPrompt, SessionError, SessionManager};
+use crate::session::{QueueAcpPrompt, SessionError, SessionManager, SetAcpConfig};
 use crate::sidecar::EventCursor;
 
 #[derive(Debug, Clone)]
@@ -69,7 +71,12 @@ pub fn router(state: LocalApiState) -> Router {
         .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),
@@ -173,7 +180,7 @@ fn dir_error_status(code: &str) -> StatusCode {
 fn session_error_status(code: &str) -> StatusCode {
     match code {
         "not_found" => StatusCode::NOT_FOUND,
-        "invalid_env" => StatusCode::BAD_REQUEST,
+        "invalid_env" | "bad_request" => StatusCode::BAD_REQUEST,
         // A guard refusal is the daemon doing its job, not a failure (#79).
         "kill_guarded" => StatusCode::CONFLICT,
         // The session outlived its pane: nothing to type into, and nothing
@@ -430,13 +437,55 @@ async fn structured_replay(
     }
 }
 
+#[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) => StatusCode::NO_CONTENT.into_response(),
+        Ok(QueueAcpPrompt::Queued) | Ok(QueueAcpPrompt::Pending) => {
+            StatusCode::NO_CONTENT.into_response()
+        }
         Ok(QueueAcpPrompt::InFlight) => error_response(
             StatusCode::CONFLICT,
             "turn_in_flight",
@@ -472,6 +521,37 @@ async fn structured_cancel(State(s): State<LocalApiState>, Path(id): Path<Uuid>)
     }
 }
 
+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)>,

crates/maestro-daemon/src/projection.rs

@@ -2,6 +2,7 @@
 
 use std::collections::{HashMap, HashSet};
 
+use chrono::{DateTime, Utc};
 use maestro_acp::schema::{ContentChunk, SessionNotification, SessionUpdate, ToolCall};
 use maestro_protocol::{
     ActivityState, ReducedState, TranscriptDelta, TranscriptRow, TranscriptRowKind,
@@ -37,9 +38,12 @@ pub struct Projection {
     pending_tool_updates: HashMap<String, Vec<maestro_acp::schema::ToolCallUpdateFields>>,
     state: ReducedState,
     active_turn: Option<u64>,
+    active_turn_started_at: Option<DateTime<Utc>>,
+    active_turn_context_tokens: Option<u64>,
     turn_failed: bool,
     next_turn: u64,
     turn_tool_calls: HashSet<String>,
+    anonymous_content_row: Option<(String, String)>,
 }
 
 impl Projection {
@@ -60,6 +64,7 @@ impl Projection {
             SessionUpdate::ToolCall(tool) => self.tool_call(tool),
             SessionUpdate::ToolCallUpdate(update) => self.tool_update(update),
             SessionUpdate::Plan(plan) => {
+                self.anonymous_content_row = None;
                 let data = to_value(plan);
                 self.state.plan = Some(data.clone());
                 Some(self.replace("plan".into(), TranscriptRowKind::Plan, data))
@@ -77,16 +82,20 @@ impl Projection {
             SessionUpdate::ConfigOptionUpdate(options) => {
                 let value = to_value(options);
                 self.state.model = model_from_options(&value).or_else(|| self.state.model.clone());
+                self.state.config_options = Some(value);
                 None
             }
             // ACP deliberately adds notification variants over time. Known but
             // non-transcript updates become a generic notice instead of being
             // dropped or forcing clients to understand ACP's enum.
-            _ => Some(self.append(
-                format!("notice:{seq}"),
-                TranscriptRowKind::Notice,
-                to_value(&notification.update),
-            )),
+            _ => {
+                self.anonymous_content_row = None;
+                Some(self.append(
+                    format!("notice:{seq}"),
+                    TranscriptRowKind::Notice,
+                    to_value(&notification.update),
+                ))
+            }
         };
         ProjectionUpdate {
             transcript,
@@ -122,12 +131,19 @@ impl Projection {
 
     /// Start a prompt turn and return its monotonically increasing token.
     pub fn begin_turn(&mut self) -> (u64, ProjectionUpdate) {
+        self.anonymous_content_row = None;
         self.next_turn += 1;
         let turn = self.next_turn;
         self.active_turn = Some(turn);
+        let started_at = Utc::now();
+        let started_context_tokens = usage_tokens(self.state.usage.as_ref());
+        self.active_turn_started_at = Some(started_at);
+        self.active_turn_context_tokens = started_context_tokens;
         self.turn_failed = false;
         self.state.turn.responding = true;
         self.state.turn.thinking = true;
+        self.state.turn.started_at = Some(started_at);
+        self.state.turn.started_context_tokens = started_context_tokens;
         self.turn_tool_calls.clear();
         self.state.turn.active_tool_calls.clear();
         (
@@ -156,10 +172,44 @@ impl Projection {
         self.turn_failed = lifecycle == TurnLifecycle::Failure;
         self.state.turn.responding = false;
         self.state.turn.thinking = false;
+        let finished_at = Utc::now();
+        let started_at = self.active_turn_started_at.take();
+        let started_context_tokens = self.active_turn_context_tokens.take();
+        self.state.turn.started_at = None;
+        self.state.turn.started_context_tokens = None;
         self.turn_tool_calls.clear();
         self.state.turn.active_tool_calls.clear();
+        let context_tokens = usage_tokens(self.state.usage.as_ref());
+        let context_delta = context_tokens
+            .zip(started_context_tokens)
+            .map(|(end, start)| i128::from(end) - i128::from(start));
+        let elapsed_ms = started_at.map_or(0, |started| {
+            finished_at
+                .signed_duration_since(started)
+                .num_milliseconds()
+                .max(0)
+        });
+        let outcome = match lifecycle {
+            TurnLifecycle::Finish => "completed",
+            TurnLifecycle::Cancel => "cancelled",
+            TurnLifecycle::Failure => "failed",
+            TurnLifecycle::Begin => unreachable!(),
+        };
+        let row = self.append(
+            format!("turn_meta:{}", uuid::Uuid::new_v4()),
+            TranscriptRowKind::Notice,
+            serde_json::json!({
+                "maestroTurnMeta": {
+                    "elapsedMs": elapsed_ms,
+                    "contextTokens": context_tokens,
+                    "contextDelta": context_delta,
+                    "outcome": outcome,
+                    "model": self.state.model,
+                }
+            }),
+        );
         Some(ProjectionUpdate {
-            transcript: None,
+            transcript: Some(row),
             state: self.state(),
         })
     }
@@ -186,7 +236,8 @@ impl Projection {
         }
     }
 
-    pub fn restore_approval(&mut self, row: TranscriptRow) -> ProjectionUpdate {
+    pub fn restore_row(&mut self, row: TranscriptRow) -> ProjectionUpdate {
+        self.anonymous_content_row = None;
         let transcript = if !self.row_index.contains_key(&row.id) {
             self.row_index.insert(row.id.clone(), self.rows.len());
             self.rows.push(row.clone());
@@ -245,12 +296,32 @@ impl Projection {
         kind: TranscriptRowKind,
         prefix: &str,
     ) -> Option<TranscriptDelta> {
-        let id = chunk
-            .message_id
-            .as_ref()
-            .map(|id| format!("{prefix}:{id}"))
-            .unwrap_or_else(|| format!("{prefix}:{seq}"));
         let data = to_value(chunk);
+        let id = if let Some(message_id) = chunk.message_id.as_ref() {
+            self.anonymous_content_row = None;
+            format!("{prefix}:{message_id}")
+        } else {
+            let text = data.pointer("/content/text").and_then(Value::as_str);
+            let previous = self
+                .anonymous_content_row
+                .as_ref()
+                .filter(|(previous_prefix, _)| previous_prefix == prefix)
+                .map(|(_, id)| id.clone());
+            if text.is_some_and(|text| !text.is_empty()) {
+                if let Some(id) = previous {
+                    let index = *self
+                        .row_index
+                        .get(&id)
+                        .expect("anonymous content row remains addressable");
+                    let row = &mut self.rows[index];
+                    append_text(&mut row.data, &data);
+                    return Some(TranscriptDelta::Patch { row: row.clone() });
+                }
+            }
+            let id = format!("{prefix}:{seq}");
+            self.anonymous_content_row = text.map(|_| (prefix.to_owned(), id.clone()));
+            id
+        };
         if let Some(index) = self.row_index.get(&id).copied() {
             let row = &mut self.rows[index];
             append_text(&mut row.data, &data);
@@ -260,6 +331,7 @@ impl Projection {
     }
 
     fn tool_call(&mut self, tool: &ToolCall) -> Option<TranscriptDelta> {
+        self.anonymous_content_row = None;
         let id = format!("tool:{}", tool.tool_call_id);
         let tool_id = tool.tool_call_id.to_string();
         let mut canonical = tool.clone();
@@ -290,6 +362,7 @@ impl Projection {
         &mut self,
         update: &maestro_acp::schema::ToolCallUpdate,
     ) -> Option<TranscriptDelta> {
+        self.anonymous_content_row = None;
         let tool_id = update.tool_call_id.to_string();
         let Some(tool) = self.tools.get_mut(&tool_id) else {
             self.pending_tool_updates
@@ -383,6 +456,10 @@ impl Projection {
     }
 }
 
+fn usage_tokens(usage: Option<&Value>) -> Option<u64> {
+    usage?.get("used")?.as_u64()
+}
+
 fn to_value(value: &impl serde::Serialize) -> Value {
     serde_json::to_value(value).expect("ACP schema values serialize")
 }
@@ -426,7 +503,7 @@ fn model_from_options(value: &Value) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use maestro_acp::schema::SessionNotification;
-    use maestro_protocol::{TranscriptDelta, TranscriptRowKind};
+    use maestro_protocol::{TranscriptDelta, TranscriptRow, TranscriptRowKind};
 
     use super::{Projection, TurnLifecycle};
 
@@ -496,6 +573,137 @@ mod tests {
         );
     }
 
+    #[test]
+    fn projects_the_codex_adapter_fixture_without_provider_specific_rows() {
+        let fixture = include_str!("../tests/fixtures/codex-acp-session.jsonl");
+        let events = fixture
+            .lines()
+            .map(serde_json::from_str::<SessionNotification>)
+            .collect::<Result<Vec<_>, _>>()
+            .expect("Codex ACP fixture follows the supported schema");
+        let mut projection = Projection::default();
+
+        for (seq, event) in events.iter().enumerate() {
+            projection.apply((seq + 1) as u64, event);
+        }
+
+        let rows = projection.snapshot(events.len() as u64).rows;
+        assert_eq!(
+            rows.iter().map(|row| row.kind).collect::<Vec<_>>(),
+            [
+                TranscriptRowKind::User,
+                TranscriptRowKind::AgentThought,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::ToolDiff,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::Plan,
+                TranscriptRowKind::Notice,
+                TranscriptRowKind::Notice,
+                TranscriptRowKind::AgentText,
+            ]
+        );
+        assert_eq!(rows[2].data["rawInput"]["command"], "rg TODO");
+        assert_eq!(rows[2].data["rawOutput"]["exit_code"], 0);
+        assert_eq!(rows[4].data["_meta"]["is_mcp_tool_call"], true);
+        assert_eq!(rows[5].data["rawInput"]["query"], "Agent Client Protocol");
+        assert_eq!(
+            rows[7].data["content"][0]["content"]["mimeType"],
+            "image/png"
+        );
+
+        let state = projection.state();
+        assert_eq!(state.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(state.mode.as_deref(), Some("agent"));
+        assert_eq!(state.usage.as_ref().unwrap()["used"], 1200);
+        assert_eq!(state.context.as_ref().unwrap()["size"], 258400);
+        assert_eq!(
+            state.config_options.as_ref().unwrap()["configOptions"][2]["currentValue"],
+            "high"
+        );
+    }
+
+    #[test]
+    fn coalesces_anonymous_stream_chunks_without_joining_turns() {
+        let mut projection = Projection::default();
+        let (first_turn, _) = projection.begin_turn();
+        for (seq, text) in [(1, ""), (2, "p"), (3, "ong")] {
+            projection.apply(
+                seq,
+                &event(serde_json::json!({
+                    "sessionUpdate": "agent_message_chunk",
+                    "content": {"type": "text", "text": text},
+                })),
+            );
+        }
+        projection.turn_lifecycle(TurnLifecycle::Finish, first_turn);
+        projection.begin_turn();
+        projection.apply(
+            4,
+            &event(serde_json::json!({
+                "sessionUpdate": "agent_message_chunk",
+                "content": {"type": "text", "text": "next"},
+            })),
+        );
+
+        let rows = projection.snapshot(4).rows;
+        assert_eq!(rows.len(), 3);
+        assert_eq!(rows[0].data.pointer("/content/text").unwrap(), "pong");
+        assert!(rows[1].data.get("maestroTurnMeta").is_some());
+        assert_eq!(rows[2].data.pointer("/content/text").unwrap(), "next");
+    }
+
+    #[test]
+    fn anonymous_empty_chunk_delimits_turns_during_replay() {
+        let mut projection = Projection::default();
+        for (seq, text) in [(1, ""), (2, "visible"), (3, ""), (4, "p"), (5, "ong")] {
+            projection.apply(
+                seq,
+                &event(serde_json::json!({
+                    "sessionUpdate": "agent_message_chunk",
+                    "content": {"type": "text", "text": text},
+                })),
+            );
+        }
+
+        let rows = projection.snapshot(5).rows;
+        assert_eq!(rows.len(), 2);
+        assert_eq!(rows[0].data.pointer("/content/text").unwrap(), "visible");
+        assert_eq!(rows[1].data.pointer("/content/text").unwrap(), "pong");
+    }
+
+    #[test]
+    fn restored_user_prompt_delimits_anonymous_agent_rows() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate": "agent_message_chunk",
+                "content": {"type": "text", "text": "before"},
+            })),
+        );
+        projection.restore_row(TranscriptRow {
+            id: "user:prompt".into(),
+            kind: TranscriptRowKind::User,
+            data: serde_json::json!({"content": {"type": "text", "text": "next"}}),
+        });
+        projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate": "agent_message_chunk",
+                "content": {"type": "text", "text": "after"},
+            })),
+        );
+
+        let rows = projection.snapshot(2).rows;
+        assert_eq!(rows.len(), 3);
+        assert_eq!(rows[0].data.pointer("/content/text").unwrap(), "before");
+        assert_eq!(rows[1].kind, TranscriptRowKind::User);
+        assert_eq!(rows[2].data.pointer("/content/text").unwrap(), "after");
+    }
+
     #[test]
     fn tool_update_patches_the_original_stable_row() {
         let mut projection = Projection::default();
@@ -614,6 +822,10 @@ mod tests {
         assert_eq!(state.context.as_ref().unwrap()["size"], 200);
         assert_eq!(state.mode.as_deref(), Some("plan"));
         assert_eq!(state.model.as_deref(), Some("opus"));
+        assert_eq!(
+            state.config_options.as_ref().unwrap()["configOptions"][0]["currentValue"],
+            "opus"
+        );
         assert_eq!(
             state.plan.as_ref().unwrap()["entries"],
             serde_json::json!([])
@@ -685,6 +897,38 @@ mod tests {
         }
     }
 
+    #[test]
+    fn completed_turn_keeps_duration_and_context_delta_in_transcript() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate":"usage_update", "used":10_000, "size":200_000
+            })),
+        );
+        let (turn, begun) = projection.begin_turn();
+        assert!(begun.state.turn.started_at.is_some());
+        assert_eq!(begun.state.turn.started_context_tokens, Some(10_000));
+        projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate":"usage_update", "used":12_500, "size":200_000
+            })),
+        );
+
+        let finished = projection
+            .turn_lifecycle(TurnLifecycle::Finish, turn)
+            .expect("active turn finishes");
+        let TranscriptDelta::Append { row } = finished.transcript.unwrap() else {
+            panic!("turn footer");
+        };
+        assert_eq!(row.kind, TranscriptRowKind::Notice);
+        assert_eq!(row.data["maestroTurnMeta"]["contextDelta"], 2_500);
+        assert_eq!(row.data["maestroTurnMeta"]["contextTokens"], 12_500);
+        assert_eq!(row.data["maestroTurnMeta"]["outcome"], "completed");
+        assert!(finished.state.turn.started_at.is_none());
+    }
+
     fn terminal_turn_drops_unfinished_tools(
         terminal: TurnLifecycle,
         unfinished_id: &str,
@@ -703,7 +947,9 @@ mod tests {
 
         projection.turn_lifecycle(terminal, turn);
         assert!(projection.state().turn.active_tool_calls.is_empty());
-        assert_eq!(projection.snapshot(1).rows.len(), 1);
+        let rows = projection.snapshot(1).rows;
+        assert_eq!(rows.len(), 2);
+        assert!(rows[1].data.get("maestroTurnMeta").is_some());
 
         projection.begin_turn();
         projection.apply(
@@ -829,7 +1075,7 @@ mod tests {
             panic!("approval row")
         };
         let mut recovered = Projection::default();
-        let update = recovered.restore_approval(row.clone());
+        let update = recovered.restore_row(row.clone());
         assert_eq!(
             update.transcript,
             Some(TranscriptDelta::Append { row: row.clone() })

crates/maestro-daemon/src/session.rs

@@ -6,20 +6,18 @@
 //! handler interact with tmux.
 
 use std::collections::{HashMap, HashSet};
-use std::future::Future;
 use std::path::PathBuf;
-use std::pin::Pin;
 use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
 use std::sync::{Arc, Weak};
-use std::task::{Context, Poll};
 use std::time::Duration;
 
 use chrono::Utc;
-use maestro_acp::{AcpSession, PermissionRequest, SpawnConfig};
+use maestro_acp::{AcpAdapter, AcpSession, PermissionRequest, SpawnConfig};
+use maestro_protocol::display::command_tool;
 use maestro_protocol::{
     ActivityState, CatalogEvent, CreateSessionRequest, ErrorInfo, NameSource, Session,
-    SessionStatus, SessionView, StructuredReplayEvent, TranscriptDelta, WorktreeSpec, NAME_KEY,
-    NAME_SOURCE_KEY,
+    SessionStatus, SessionView, StructuredReplayEvent, TranscriptDelta, TranscriptRow,
+    TranscriptRowKind, WorktreeSpec, NAME_KEY, NAME_SOURCE_KEY,
 };
 use tokio::sync::{broadcast, oneshot, watch, Mutex, Notify};
 use uuid::Uuid;
@@ -59,6 +57,16 @@ pub const DEFAULT_BLOCKED_WORK_INTERVAL: Duration = Duration::from_secs(15);
 /// actually go.
 const SUBMIT_DELAY: Duration = Duration::from_millis(150);
 
+fn structured_adapter(command: &str) -> Result<AcpAdapter, String> {
+    match command_tool(command) {
+        Some("claude") => Ok(AcpAdapter::ClaudeCode),
+        Some("codex") => Ok(AcpAdapter::Codex),
+        _ => Err(format!(
+            "structured view supports Claude Code or Codex commands; cannot select an ACP adapter for {command:?}"
+        )),
+    }
+}
+
 /// Per-session daemon-local bookkeeping that complements the public `Session`.
 #[derive(Debug)]
 pub struct SessionRecord {
@@ -111,6 +119,12 @@ pub struct SessionRecord {
     /// Completion signal for the task draining ACP notifications into the
     /// event log. Shutdown waits for it before returning.
     acp_event_pump: Option<watch::Receiver<bool>>,
+    /// When `true`, the permission pump auto-responds `AllowAlways` to every
+    /// ACP permission request without surfacing it to clients.
+    pub auto_approve: bool,
+    /// A prompt submitted while the adapter was still booting (`Starting`).
+    /// The background handshake task drains this on success.
+    pub pending_prompt: Option<String>,
 }
 
 impl SessionRecord {
@@ -120,6 +134,13 @@ impl SessionRecord {
             && self.acp.is_some()
             && self.acp_events.is_some()
     }
+
+    /// The session is structured and still booting its adapter.
+    fn is_starting_structured(&self) -> bool {
+        self.session.view == SessionView::Structured
+            && self.session.activity == ActivityState::Starting
+            && self.acp.is_none()
+    }
 }
 
 #[derive(Debug)]
@@ -194,6 +215,8 @@ pub enum SessionError {
     NotTerminal(Uuid),
     #[error("daemon is shutting down")]
     ShuttingDown,
+    #[error("bad request: {0}")]
+    BadRequest(String),
     /// The kill was refused (#79): the session's worktree holds unsaved work.
     /// Nothing happened — the session keeps running and the tree is untouched,
     /// so it stays the operator's handle on their own unfinished work.
@@ -213,11 +236,22 @@ pub enum BeginAcpTurn {
 #[derive(Debug)]
 pub enum QueueAcpPrompt {
     Queued,
+    /// The adapter is still booting; the prompt is held until it is ready.
+    Pending,
     InFlight,
     Unavailable,
     Failed(String),
 }
 
+/// Result of changing a live structured session option.
+#[derive(Debug)]
+pub enum SetAcpConfig {
+    Updated,
+    InvalidValue,
+    Unavailable,
+    Failed(String),
+}
+
 impl SessionError {
     pub fn to_error_info(&self) -> ErrorInfo {
         let code = match self {
@@ -230,6 +264,7 @@ impl SessionError {
             SessionError::NotRunning(_) => "not_running",
             SessionError::NotTerminal(_) => "not_terminal",
             SessionError::ShuttingDown => "shutting_down",
+            SessionError::BadRequest(_) => "bad_request",
             SessionError::KillGuarded(_) => "kill_guarded",
         };
         let unsaved_work = match self {
@@ -297,18 +332,6 @@ struct StructuredLifecycle {
 }
 
 impl StructuredLifecycle {
-    fn admit<'a>(
-        &'a self,
-        shutting_down: &AtomicBool,
-    ) -> Result<StructuredCreate<'a>, SessionError> {
-        let _gate = self.gate.lock().expect("structured lifecycle gate");
-        if shutting_down.load(Ordering::Acquire) {
-            return Err(SessionError::ShuttingDown);
-        }
-        self.in_flight.fetch_add(1, Ordering::AcqRel);
-        Ok(StructuredCreate { lifecycle: self })
-    }
-
     async fn wait_until_settled(&self) {
         loop {
             let settled = self.settled.notified();
@@ -320,30 +343,18 @@ impl StructuredLifecycle {
     }
 }
 
-struct StructuredCreate<'a> {
-    lifecycle: &'a StructuredLifecycle,
-}
-
-impl Drop for StructuredCreate<'_> {
-    fn drop(&mut self) {
-        if self.lifecycle.in_flight.fetch_sub(1, Ordering::AcqRel) == 1 {
-            self.lifecycle.settled.notify_one();
-        }
-    }
-}
-
-struct AdmittedStructuredCreate<'a> {
-    create: Pin<Box<dyn Future<Output = Result<Session, SessionError>> + Send + 'a>>,
-    /// Field order matters: dropping a cancelled create rolls back its inner
-    /// future before this permit releases shutdown's in-flight barrier.
-    _permit: StructuredCreate<'a>,
-}
-
-impl Future for AdmittedStructuredCreate<'_> {
-    type Output = Result<Session, SessionError>;
-
-    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        self.create.as_mut().poll(cx)
+/// Release the structured-lifecycle in-flight counter that `create` acquires
+/// before spawning the background ACP handshake task. Called when the task
+/// finishes (success or failure) or when `create_inner` fails before the task
+/// is spawned.
+fn drop_structured_lifecycle_permit(inner: &Inner) {
+    if inner
+        .structured_lifecycle
+        .in_flight
+        .fetch_sub(1, Ordering::AcqRel)
+        == 1
+    {
+        inner.structured_lifecycle.settled.notify_one();
     }
 }
 
@@ -584,6 +595,36 @@ impl SessionManager {
         Ok(Some(replay))
     }
 
+    /// Store attachment bytes for a live structured session.
+    pub async fn store_acp_attachment(
+        &self,
+        id: Uuid,
+        name: &str,
+        bytes: &[u8],
+    ) -> Result<Option<std::path::PathBuf>, SessionError> {
+        {
+            let sessions = self.inner.sessions.lock().await;
+            let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+            if !record.is_live_structured() {
+                return Ok(None);
+            }
+        }
+        let dir = self.inner.sidecar.dir().join(format!("{id}.attachments"));
+        tokio::fs::create_dir_all(&dir).await?;
+        let dir = tokio::fs::canonicalize(dir).await?;
+        let path = dir.join(format!("{}-{name}", Uuid::new_v4()));
+        let mut file = tokio::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o600)
+            .open(&path)
+            .await?;
+        use tokio::io::AsyncWriteExt;
+        file.write_all(bytes).await?;
+        file.sync_all().await?;
+        Ok(Some(path))
+    }
+
     /// Subscribe to the two projections of a structured session's ACP log.
     ///
     /// The transcript snapshot and whole reduced state are folded once by the
@@ -607,7 +648,9 @@ impl SessionManager {
         let stream = {
             let sessions = self.inner.sessions.lock().await;
             let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
-            if !record.is_live_structured() {
+            // Allow connecting while the adapter is still booting
+            // (`Starting`) — the event stream exists, it is just empty.
+            if !record.is_live_structured() && !record.is_starting_structured() {
                 return Ok(None);
             }
             let Some(stream) = &record.acp_events else {
@@ -648,6 +691,7 @@ impl SessionManager {
         let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) else {
             return Ok(false);
         };
+        let projected = persist_turn_update(&mut stream, projected);
         let _ = stream.projected_live.send(projected);
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
@@ -691,8 +735,14 @@ impl SessionManager {
         text: String,
     ) -> Result<QueueAcpPrompt, SessionError> {
         let (acp, stream) = {
-            let sessions = self.inner.sessions.lock().await;
-            let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+            let mut sessions = self.inner.sessions.lock().await;
+            let record = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
+            // While the adapter is booting, stash the prompt for the
+            // background handshake task to drain on success.
+            if record.is_starting_structured() {
+                record.pending_prompt = Some(text);
+                return Ok(QueueAcpPrompt::Pending);
+            }
             if !record.is_live_structured() {
                 return Ok(QueueAcpPrompt::Unavailable);
             }
@@ -719,6 +769,27 @@ impl SessionManager {
                     if stream.projection.turn_active() {
                         return Ok(QueueAcpPrompt::InFlight);
                     }
+                    let row = TranscriptRow {
+                        id: format!("user:{}", Uuid::new_v4()),
+                        kind: TranscriptRowKind::User,
+                        data: serde_json::json!({
+                            "content": {"type": "text", "text": text},
+                        }),
+                    };
+                    let event = PersistedEvent::User { row: row.clone() };
+                    let seq = match stream.log.append(&event) {
+                        Ok(seq) => seq,
+                        Err(error) => {
+                            if matches!(error, AppendError::Fatal { .. }) {
+                                stream.dispatch.failed = true;
+                            }
+                            return Ok(QueueAcpPrompt::Failed(error.to_string()));
+                        }
+                    };
+                    let logged = LoggedEvent { seq, event };
+                    let projected = stream.projection.restore_row(row);
+                    let _ = stream.live.send(logged);
+                    let _ = stream.projected_live.send(projected);
                     let (turn, update) = stream.projection.begin_turn();
                     let _ = stream.projected_live.send(update);
                     match acp.prompt(text.clone(), turn) {
@@ -734,6 +805,10 @@ impl SessionManager {
                             });
                             drop(stream);
                             sync_structured_activity(&self.inner, id).await;
+                            #[cfg(feature = "haiku-autoname")]
+                            if let Ok(true) = self.claim_autoname(id).await {
+                                crate::autoname::spawn_naming(self.clone(), id, text);
+                            }
                             return Ok(QueueAcpPrompt::Queued);
                         }
                         Err(message) => {
@@ -744,6 +819,7 @@ impl SessionManager {
                                 .expect(
                                     "newly claimed turn remains current while stream is locked",
                                 );
+                            let projected = persist_turn_update(&mut stream, projected);
                             let _ = stream.projected_live.send(projected);
                             drop(stream);
                             sync_structured_activity(&self.inner, id).await;
@@ -789,6 +865,7 @@ impl SessionManager {
         }
         cancel_pending_approvals(&mut stream);
         if let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) {
+            let projected = persist_turn_update(&mut stream, projected);
             let _ = stream.projected_live.send(projected);
         }
         drop(stream);
@@ -829,6 +906,48 @@ impl SessionManager {
         }
     }
 
+    /// Change one option on a live ACP session and wait for the agent to
+    /// acknowledge it. The adapter's returned option set is projected by the
+    /// normal event pump before this request completes.
+    pub async fn set_acp_config(
+        &self,
+        id: Uuid,
+        config_id: String,
+        value: serde_json::Value,
+    ) -> Result<SetAcpConfig, SessionError> {
+        let (acp, stream) = {
+            let sessions = self.inner.sessions.lock().await;
+            let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+            if !record.is_live_structured() {
+                return Ok(SetAcpConfig::Unavailable);
+            }
+            (record.acp.clone(), record.acp_events.clone())
+        };
+        let (Some(acp), Some(stream)) = (acp, stream) else {
+            return Ok(SetAcpConfig::Unavailable);
+        };
+        let value = match value {
+            serde_json::Value::String(value) => {
+                maestro_acp::schema::SessionConfigOptionValue::value_id(value)
+            }
+            serde_json::Value::Bool(value) => {
+                maestro_acp::schema::SessionConfigOptionValue::boolean(value)
+            }
+            _ => return Ok(SetAcpConfig::InvalidValue),
+        };
+        let operation = stream.lock().await.operation.clone();
+        let _operation = operation.lock().await;
+        let done = match acp.set_config(config_id, value) {
+            Ok(done) => done,
+            Err(message) => return Ok(SetAcpConfig::Failed(message)),
+        };
+        match done.await {
+            Ok(Ok(())) => Ok(SetAcpConfig::Updated),
+            Ok(Err(message)) => Ok(SetAcpConfig::Failed(message)),
+            Err(_) => Ok(SetAcpConfig::Failed("ACP connection is closed".into())),
+        }
+    }
+
     /// Cancel an ACP turn and immediately clear its client-facing lifecycle.
     pub async fn cancel_acp_turn(&self, id: Uuid) -> Result<bool, SessionError> {
         let (acp, stream) = {
@@ -863,6 +982,7 @@ impl SessionManager {
             .projection
             .turn_lifecycle(TurnLifecycle::Cancel, turn)
             .expect("active turn remains current while stream is locked");
+        let projected = persist_turn_update(&mut stream, projected);
         let _ = stream.projected_live.send(projected);
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
@@ -1097,17 +1217,42 @@ impl SessionManager {
     }
 
     /// Spawn a new session. On success returns the freshly-created `Session`.
+    ///
+    /// For structured sessions, the ACP handshake runs in a background task
+    /// after the session is registered — the HTTP caller gets an instant
+    /// response with `activity: Starting`. The `StructuredLifecycle` gate is
+    /// held across the background task so `shutdown()` waits for it.
     pub async fn create(&self, req: CreateSessionRequest) -> Result<Session, SessionError> {
         if req.view == SessionView::Structured {
-            let permit = self
+            // Acquire the lifecycle gate synchronously (rejects if shutting
+            // down). The background handshake task calls
+            // `drop_structured_lifecycle_permit` when it finishes; we must
+            // not use the RAII `StructuredCreate` because it would drop at
+            // the end of `create_inner`, before the handshake completes.
+            let _gate = self
                 .inner
                 .structured_lifecycle
-                .admit(&self.inner.shutting_down)?;
-            return AdmittedStructuredCreate {
-                create: Box::pin(self.create_inner(req)),
-                _permit: permit,
+                .gate
+                .lock()
+                .expect("structured lifecycle gate");
+            if self.inner.shutting_down.load(Ordering::Acquire) {
+                return Err(SessionError::ShuttingDown);
             }
-            .await;
+            self.inner
+                .structured_lifecycle
+                .in_flight
+                .fetch_add(1, Ordering::AcqRel);
+            drop(_gate);
+
+            return match self.create_inner(req).await {
+                Ok(session) => Ok(session),
+                Err(e) => {
+                    // create_inner failed before spawning the background
+                    // task, so release the permit here.
+                    drop_structured_lifecycle_permit(&self.inner);
+                    Err(e)
+                }
+            };
         }
         self.create_inner(req).await
     }
@@ -1169,27 +1314,38 @@ impl SessionManager {
         {
             session_env.insert("MAESTRO_URL".into(), url);
         }
-        // A structured session (#134) gets no tmux pane: the agent is a
-        // child of the daemon, driven over ACP. An adapter that cannot come
-        // up still yields a session — Dead, with the reason on it — so the
-        // operator sees what to fix instead of a silently missing session.
-        let (acp, acp_failure) = match req.view {
+        // ── Structured path: validate adapter, open event log, register
+        // the session immediately with `Starting`, then handshake in the
+        // background so the HTTP caller gets an instant response.
+        //
+        // ── Terminal path: unchanged — tmux spawn is fast enough to stay
+        // synchronous.
+        // Structured: validate adapter, open event log eagerly. Terminal:
+        // spawn the tmux pane synchronously (it is fast).
+        let structured_spawn = match req.view {
             SessionView::Structured => {
-                match maestro_acp::spawn(SpawnConfig::new(
-                    &effective_cwd,
-                    session_env
-                        .iter()
-                        .map(|(k, v)| (k.clone(), v.clone()))
-                        .collect(),
-                ))
-                .await
-                {
-                    Ok(acp) => (Some(Arc::new(acp)), None),
-                    Err(e) => {
-                        tracing::warn!(%id, error = %e, "structured session: adapter failed to start");
-                        (None, Some(e.to_string()))
+                // Fail fast on an unsupported command before touching disk.
+                let adapter = structured_adapter(&req.command).map_err(SessionError::BadRequest)?;
+                // Open the event log eagerly so the structured WS can
+                // connect before the adapter is up.
+                let acp_events = match self.inner.sidecar.open_events(id) {
+                    Ok(log) => {
+                        let (tx, _) = broadcast::channel(EVENTS_CAPACITY);
+                        let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY);
+                        Arc::new(Mutex::new(AcpEventStream {
+                            log,
+                            live: tx,
+                            projection: Projection::default(),
+                            projected_live: projected_tx,
+                            pending_approvals: HashMap::new(),
+                            operation: Arc::new(Mutex::new(())),
+                            dispatch: AcpDispatchState::default(),
+                            activity_sequence: 0,
+                        }))
                     }
-                }
+                    Err(e) => return Err(SessionError::Sidecar(e)),
+                };
+                Some((adapter, acp_events))
             }
             SessionView::Terminal => {
                 let spawned = {
@@ -1204,53 +1360,10 @@ impl SessionManager {
                 if let Err(e) = spawned {
                     return Err(SessionError::Tmux(e));
                 }
-                (None, None)
+                None
             }
         };
 
-        let acp_events = if let Some(acp) = &acp {
-            let persisted =
-                match self
-                    .inner
-                    .sidecar
-                    .read_events(id, EventCursor::Since(0), usize::MAX)
-                {
-                    Ok(events) => events,
-                    Err(error) => {
-                        acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                            .await;
-                        return Err(SessionError::Sidecar(error));
-                    }
-                };
-            match self.inner.sidecar.open_events(id) {
-                Ok(log) => {
-                    let (tx, _) = broadcast::channel(EVENTS_CAPACITY);
-                    let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY);
-                    let mut projection = Projection::default();
-                    for event in &persisted {
-                        apply_persisted_event(&mut projection, event);
-                    }
-                    Some(Arc::new(Mutex::new(AcpEventStream {
-                        log,
-                        live: tx,
-                        projection,
-                        projected_live: projected_tx,
-                        pending_approvals: HashMap::new(),
-                        operation: Arc::new(Mutex::new(())),
-                        dispatch: AcpDispatchState::default(),
-                        activity_sequence: 0,
-                    })))
-                }
-                Err(e) => {
-                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                        .await;
-                    return Err(SessionError::Sidecar(e));
-                }
-            }
-        } else {
-            None
-        };
-
         // Capture spawn-history inputs before `req` is partially moved into
         // `session`. `history_cwd` is the *chosen* working dir (the request
         // `cwd`), not a generated worktree checkout path — that's what the
@@ -1260,10 +1373,13 @@ impl SessionManager {
         resolve_name(&mut metadata);
         let worktree_branch = req.worktree.as_ref().map(|w| w.branch.clone());
 
+        let is_structured = structured_spawn.is_some();
+        let events_arc = structured_spawn.as_ref().map(|(_, e)| e.clone());
+
         let session = Session {
             id,
-            cwd: effective_cwd,
-            command: req.command,
+            cwd: effective_cwd.clone(),
+            command: req.command.clone(),
             env: req.env,
             metadata,
             worktree: worktree_path.as_ref().zip(worktree_base_repo.as_ref()).map(
@@ -1272,67 +1388,41 @@ impl SessionManager {
                     base_repo: base_repo.clone(),
                 },
             ),
-            status: if acp_failure.is_some() {
-                SessionStatus::Dead
-            } else {
-                SessionStatus::Running
-            },
+            status: SessionStatus::Running,
             created_at: Utc::now(),
-            // A terminal spawn begins active until its watcher sees otherwise;
-            // a structured spawn has no turn yet and begins idle.
             foreground: None,
-            activity: match (req.view, acp_failure.is_some()) {
-                (_, true) => ActivityState::Error,
-                (SessionView::Structured, false) => ActivityState::Idle,
-                (SessionView::Terminal, false) => ActivityState::Active,
+            activity: if is_structured {
+                ActivityState::Starting
+            } else {
+                ActivityState::Active
             },
-            activity_detail: acp_failure,
+            activity_detail: None,
             last_activity_at: Utc::now(),
             activity_since: chrono::Utc::now(),
-
             current_cwd: None,
-            // The watcher fills this in on its first blocked-work pass; a
-            // fresh tree has nothing in the way anyway.
             blocked_work: None,
             last_focused_at: None,
-            acp_session_id: acp.as_ref().map(|a| a.session_id().to_string()),
+            acp_session_id: None,
             view: req.view,
         };
 
         if let Err(e) = self.inner.sidecar.write(&session) {
-            // The process already started; end it so no ghost survives a
-            // failed sidecar write, then unwind the FIFO + worktree.
-            match &acp {
-                Some(acp) => {
-                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                        .await
-                }
-                None => {
-                    let tmux = self.inner.tmux.clone();
-                    let _ = tmux_blocking(move || tmux.kill_session(id)).await;
-                }
+            if !is_structured {
+                let tmux = self.inner.tmux.clone();
+                let _ = tmux_blocking(move || tmux.kill_session(id)).await;
             }
             return Err(SessionError::Sidecar(e));
         }
 
-        let event_pump = acp
-            .as_ref()
-            .zip(acp_events.as_ref())
-            .map(|(acp, events)| (acp.clone(), events.clone()));
         {
             let mut sessions = self.inner.sessions.lock().await;
-            let event_pump = event_pump.map(|(acp, events)| {
-                let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
-                start_acp_permission_pump(&self.inner, id, &acp, events);
-                done
-            });
             sessions.insert(
                 id,
                 SessionRecord {
                     session: session.clone(),
                     fifo_path,
-                    worktree_path,
-                    worktree_base_repo,
+                    worktree_path: worktree_path.clone(),
+                    worktree_base_repo: worktree_base_repo.clone(),
                     bridge,
                     reported_activity: None,
                     settled: false,
@@ -1340,10 +1430,12 @@ impl SessionManager {
                     naming: false,
                     focused_since: None,
                     awaiting_suppressed: false,
-                    acp,
-                    acp_events,
+                    acp: None,
+                    acp_events: events_arc,
                     structured_activity_watermark: None,
-                    acp_event_pump: event_pump,
+                    acp_event_pump: None,
+                    auto_approve: req.auto_approve,
+                    pending_prompt: None,
                 },
             );
         }
@@ -1372,6 +1464,78 @@ impl SessionManager {
         }
 
         pending.commit();
+
+        // ── Background ACP handshake for structured sessions ──
+        //
+        // The session is registered and visible to clients. The adapter
+        // spawn + handshake runs in a background task; on completion it
+        // fills in `acp`, starts the event/permission pumps, and
+        // transitions activity from `Starting` to `Idle` (or to `Error`
+        // on failure). The `StructuredLifecycle` permit is held until the
+        // task finishes so `shutdown()` waits for it.
+        if let Some((adapter, events)) = structured_spawn {
+            let inner = self.inner.clone();
+            let env: HashMap<String, String> = session_env
+                .iter()
+                .map(|(k, v)| (k.clone(), v.clone()))
+                .collect();
+            let cwd = effective_cwd;
+            let auto_approve = req.auto_approve;
+            tokio::spawn(async move {
+                let result = maestro_acp::spawn(SpawnConfig::new(&cwd, env).adapter(adapter)).await;
+
+                match result {
+                    Ok(acp_session) => {
+                        let acp = Arc::new(acp_session);
+                        let done = start_acp_event_pump(&inner, id, &acp, events.clone());
+                        start_acp_permission_pump(&inner, id, &acp, events.clone(), auto_approve);
+                        // Drain any prompt submitted while Starting.
+                        let pending_prompt = {
+                            let mut sessions = inner.sessions.lock().await;
+                            let Some(record) = sessions.get_mut(&id) else {
+                                // Session was killed while we were booting.
+                                acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+                                    .await;
+                                drop_structured_lifecycle_permit(&inner);
+                                return;
+                            };
+                            record.acp = Some(acp.clone());
+                            record.acp_event_pump = Some(done);
+                            record.session.acp_session_id = Some(acp.session_id().to_string());
+                            record.session.activity = ActivityState::Idle;
+                            record.session.activity_since = Utc::now();
+                            let _ = inner.sidecar.write(&record.session);
+                            let _ = inner.events.send(CatalogEvent::SessionUpdated {
+                                session: record.session.clone(),
+                            });
+                            record.pending_prompt.take()
+                        };
+                        if let Some(prompt) = pending_prompt {
+                            let manager = SessionManager {
+                                inner: inner.clone(),
+                            };
+                            let _ = manager.queue_acp_prompt(id, prompt).await;
+                        }
+                    }
+                    Err(e) => {
+                        tracing::warn!(%id, error = %e, "structured session: adapter failed to start");
+                        let mut sessions = inner.sessions.lock().await;
+                        if let Some(record) = sessions.get_mut(&id) {
+                            record.session.status = SessionStatus::Dead;
+                            record.session.activity = ActivityState::Error;
+                            record.session.activity_detail = Some(e.to_string());
+                            record.session.activity_since = Utc::now();
+                            let _ = inner.sidecar.write(&record.session);
+                            let _ = inner.events.send(CatalogEvent::SessionUpdated {
+                                session: record.session.clone(),
+                            });
+                        }
+                    }
+                }
+                drop_structured_lifecycle_permit(&inner);
+            });
+        }
+
         Ok(session)
     }
 
@@ -1556,6 +1720,8 @@ impl SessionManager {
                     acp_events: None,
                     structured_activity_watermark: None,
                     acp_event_pump: None,
+                    auto_approve: false,
+                    pending_prompt: None,
                 },
             );
             let _ = self
@@ -1598,23 +1764,30 @@ impl SessionManager {
 
             let (acp, failure) = if recoverable {
                 match session.acp_session_id.clone() {
-                    Some(acp_session_id) => {
-                        let config = SpawnConfig::new(
-                            &session.cwd,
-                            session_env
-                                .iter()
-                                .map(|(key, value)| (key.clone(), value.clone()))
-                                .collect(),
-                        )
-                        .load_session(acp_session_id);
-                        match maestro_acp::spawn(config).await {
-                            Ok(acp) => (Some(Arc::new(acp)), None),
-                            Err(error) => {
-                                tracing::warn!(%id, %error, "structured session: adapter failed to resume");
-                                (None, Some(error.to_string()))
+                    Some(acp_session_id) => match structured_adapter(&session.command) {
+                        Err(error) => {
+                            tracing::warn!(%id, %error, "structured session: unsupported command during recovery");
+                            (None, Some(error))
+                        }
+                        Ok(adapter) => {
+                            let config = SpawnConfig::new(
+                                &session.cwd,
+                                session_env
+                                    .iter()
+                                    .map(|(key, value)| (key.clone(), value.clone()))
+                                    .collect(),
+                            )
+                            .load_session(acp_session_id)
+                            .adapter(adapter);
+                            match maestro_acp::spawn(config).await {
+                                Ok(acp) => (Some(Arc::new(acp)), None),
+                                Err(error) => {
+                                    tracing::warn!(%id, %error, "structured session: adapter failed to resume");
+                                    (None, Some(error.to_string()))
+                                }
                             }
                         }
-                    }
+                    },
                     None => (
                         None,
                         Some("structured session has no stored ACP session id".into()),
@@ -1726,11 +1899,15 @@ impl SessionManager {
                     acp_events,
                     structured_activity_watermark: None,
                     acp_event_pump: None,
+                    // Recovery cannot know the original preset's flag; the
+                    // operator re-enables it by restarting with the preset.
+                    auto_approve: false,
+                    pending_prompt: None,
                 },
             );
             if let Some((acp, events)) = event_pump {
                 let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
-                start_acp_permission_pump(&self.inner, id, &acp, events);
+                start_acp_permission_pump(&self.inner, id, &acp, events, false);
                 if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
                     record.acp_event_pump = Some(done);
                 }
@@ -2118,10 +2295,33 @@ fn start_acp_event_pump(
 fn apply_persisted_event(projection: &mut Projection, event: &LoggedEvent) -> ProjectionUpdate {
     match &event.event {
         PersistedEvent::Notification(notification) => projection.apply(event.seq, notification),
-        PersistedEvent::Approval { row } => projection.restore_approval(row.clone()),
+        PersistedEvent::User { row }
+        | PersistedEvent::Approval { row }
+        | PersistedEvent::Turn { row } => projection.restore_row(row.clone()),
     }
 }
 
+fn persist_turn_update(
+    stream: &mut AcpEventStream,
+    mut update: ProjectionUpdate,
+) -> ProjectionUpdate {
+    let Some(TranscriptDelta::Append { row }) = update.transcript.as_ref() else {
+        return update;
+    };
+    let event = PersistedEvent::Turn { row: row.clone() };
+    match stream.log.append(&event) {
+        Ok(seq) => {
+            let _ = stream.live.send(LoggedEvent { seq, event });
+        }
+        Err(error) => {
+            tracing::error!(%error, "turn metadata history append failed");
+            stream.projection.rollback_row(&row.id);
+            update.transcript = None;
+        }
+    }
+    update
+}
+
 async fn sync_structured_activity(inner: &Arc<Inner>, id: Uuid) {
     let events = {
         let sessions = inner.sessions.lock().await;
@@ -2162,6 +2362,11 @@ async fn apply_structured_activity(
     if record.session.view != SessionView::Structured {
         return;
     }
+    // While the adapter is still booting, the background handshake task
+    // owns the activity state — the activity pass must not overwrite it.
+    if record.session.activity == ActivityState::Starting {
+        return;
+    }
     let current_events = record.acp_events.as_ref();
     match (expected_events, current_events) {
         (Some((expected, sequence)), Some(current)) if Arc::ptr_eq(expected, current) => {
@@ -2206,6 +2411,7 @@ fn start_acp_permission_pump(
     id: Uuid,
     acp: &Arc<AcpSession>,
     events: Arc<Mutex<AcpEventStream>>,
+    auto_approve: bool,
 ) {
     let Some(mut requests) = acp.take_permission_requests() else {
         return;
@@ -2219,6 +2425,12 @@ fn start_acp_permission_pump(
             response,
         }) = requests.recv().await
         {
+            if auto_approve {
+                let outcome =
+                    permission_outcome(ApprovalDecision::AllowForSession, &request.options);
+                let _ = response.send(outcome);
+                continue;
+            }
             let mut events = events.lock().await;
             if events.projection.active_turn() != Some(turn) {
                 let _ = response.send(maestro_acp::schema::RequestPermissionOutcome::Cancelled);
@@ -2420,6 +2632,12 @@ async fn run_liveness_pass(inner: &Arc<Inner>) {
         let mut tmux_backed = Vec::new();
         let mut acp_backed = Vec::new();
         for (id, record) in running {
+            if record.is_starting_structured() {
+                // The adapter hasn't finished its handshake yet — no ACP
+                // handle and no tmux pane. Skip; the background task owns
+                // this session's lifecycle until the handshake settles.
+                continue;
+            }
             match &record.acp {
                 Some(acp) => acp_backed.push((*id, acp.clone())),
                 None => tmux_backed.push(*id),
@@ -2870,15 +3088,18 @@ mod tests {
     use std::task::Poll;
     use std::time::Duration;
 
-    use maestro_acp::schema::{
-        PermissionOption, PermissionOptionKind, RequestPermissionOutcome, RequestPermissionRequest,
-        ToolCallUpdate, ToolCallUpdateFields,
+    use maestro_acp::{
+        schema::{
+            PermissionOption, PermissionOptionKind, RequestPermissionOutcome,
+            RequestPermissionRequest, ToolCallUpdate, ToolCallUpdateFields,
+        },
+        AcpAdapter,
     };
     use maestro_protocol::{ActivityState, CatalogEvent, CreateSessionRequest, SessionView};
 
     use super::{
         apply_structured_activity, cancel_pending_approvals, permission_outcome,
-        record_permission_request, run_structured_activity_pass,
+        record_permission_request, run_structured_activity_pass, structured_adapter,
         sync_structured_activity_from_stream, AcpDispatchState, AcpEventStream, ApprovalDecision,
         RecordOutcome, SessionManager,
     };
@@ -2902,6 +3123,17 @@ mod tests {
         )
     }
 
+    #[test]
+    fn structured_adapter_uses_the_shared_command_resolution() {
+        assert_eq!(structured_adapter("claude"), Ok(AcpAdapter::ClaudeCode));
+        assert_eq!(
+            structured_adapter("sudo -u agent -- /opt/bin/codex"),
+            Ok(AcpAdapter::Codex)
+        );
+        assert!(structured_adapter("opencode").is_err());
+        assert!(structured_adapter("claude && codex").is_err());
+    }
+
     fn stream(log: EventLog) -> AcpEventStream {
         let (live, _live_rx) = tokio::sync::broadcast::channel(16);
         let (projected_live, _projected_rx) = tokio::sync::broadcast::channel(16);
@@ -2925,6 +3157,7 @@ mod tests {
             env: std::collections::HashMap::new(),
             metadata: std::collections::HashMap::new(),
             worktree: None,
+            auto_approve: false,
         }
     }
 

crates/maestro-daemon/src/sidecar.rs

@@ -263,9 +263,15 @@ pub struct LoggedEvent {
 #[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>),
 }

crates/maestro-daemon/tests/acp.rs

@@ -11,7 +11,7 @@ use std::time::{Duration, Instant};
 
 use common::{init_bare_repo, init_repo, push_all_to_origin, wait_for_async, DaemonFixture};
 use maestro_acp::schema::{ContentBlock, SessionUpdate};
-use maestro_acp::{ADAPTER_BIN, INSTALL_COMMAND};
+use maestro_acp::{AcpAdapter, ADAPTER_BIN};
 use maestro_daemon::projection::TurnLifecycle;
 use maestro_daemon::sidecar::{EventCursor, SidecarStore};
 use maestro_daemon::worktree::WorktreeManager;
@@ -38,6 +38,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 }
     }
 
@@ -96,13 +97,22 @@ fn event_text(event: &maestro_daemon::sidecar::LoggedEvent) -> &str {
 }
 
 fn structured(cwd: &Path, env: HashMap<String, String>) -> CreateSessionRequest {
+    structured_command(cwd, env, "claude")
+}
+
+fn structured_command(
+    cwd: &Path,
+    env: HashMap<String, String>,
+    command: &str,
+) -> CreateSessionRequest {
     CreateSessionRequest {
         view: SessionView::Structured,
         cwd: cwd.to_path_buf(),
-        command: "claude".into(),
+        command: command.into(),
         env,
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     }
 }
 
@@ -120,6 +130,25 @@ async fn wait_for_exit(pid: u32) {
     assert!(!pid_alive(pid), "pid {pid} still alive");
 }
 
+/// Wait for a session's background ACP handshake to complete (activity
+/// transitions out of `Starting`). Returns the refreshed session.
+async fn wait_for_ready(manager: &SessionManager, id: uuid::Uuid) -> maestro_protocol::Session {
+    let deadline = Instant::now() + Duration::from_secs(10);
+    loop {
+        let session = manager
+            .snapshot()
+            .await
+            .into_iter()
+            .find(|s| s.id == id)
+            .expect("session exists");
+        if session.activity != ActivityState::Starting {
+            return session;
+        }
+        assert!(Instant::now() < deadline, "handshake timed out");
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+}
+
 #[tokio::test]
 async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let fx = DaemonFixture::new();
@@ -128,14 +157,22 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(
+            cwd.path(),
+            env,
+            "codex --dangerously-bypass-approvals-and-sandbox",
+        ))
         .await
         .expect("create");
 
-    assert_eq!(session.view, SessionView::Structured);
-    assert_eq!(session.status, SessionStatus::Running);
+    assert_eq!(created.view, SessionView::Structured);
+    assert_eq!(created.status, SessionStatus::Running);
+    assert_eq!(created.activity, ActivityState::Starting);
+    assert!(created.acp_session_id.is_none());
+
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.activity, ActivityState::Idle);
     let acp_id = session.acp_session_id.clone().expect("acp session id");
     assert!(acp_id.starts_with("fake-"), "{acp_id}");
@@ -150,7 +187,7 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
         "{log}"
     );
     assert!(
-        log.contains(&format!("env MAESTRO_SESSION_ID={}", session.id)),
+        log.contains(&format!("env MAESTRO_SESSION_ID={}", created.id)),
         "{log}"
     );
 
@@ -215,9 +252,10 @@ async fn structured_activity_tracks_turn_completion_and_failure() {
     env.insert("FAKE_ACP_PROMPT_FAIL_ONCE".into(), "1".into());
     let session = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .unwrap();
+    let session = wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -281,11 +319,12 @@ async fn projection_snapshot_and_live_stream_share_one_fold() {
     let fx = DaemonFixture::new();
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let session = fx
+    let created = fx
         .manager
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
 
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -349,12 +388,76 @@ async fn projection_snapshot_and_live_stream_share_one_fold() {
         .await
         .expect("finish lifecycle broadcast")
         .expect("projection broadcast");
-    assert_eq!(finish.transcript, None);
+    let Some(TranscriptDelta::Append { row }) = finish.transcript else {
+        panic!("finish should append durable turn metadata");
+    };
+    assert_eq!(row.kind, TranscriptRowKind::Notice);
+    assert_eq!(row.data["maestroTurnMeta"]["outcome"], "completed");
     assert_eq!(finish.state.turn, Default::default());
 
+    let recovered = fx
+        .manager
+        .read_acp_projection_replay(session.id, EventCursor::Since(0), 10)
+        .await
+        .expect("turn replay")
+        .expect("structured session");
+    assert!(recovered.iter().any(|event| {
+        matches!(
+            &event.transcript,
+            Some(TranscriptDelta::Append { row })
+                if row.data["maestroTurnMeta"]["outcome"] == "completed"
+        )
+    }));
+
     fx.manager.kill(session.id, false).await.expect("kill");
 }
 
+#[tokio::test]
+async fn queued_prompt_is_a_durable_user_transcript_row() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = fx
+        .manager
+        .create(structured(cwd.path(), fake.env()))
+        .await
+        .expect("create");
+    let session = wait_for_ready(&fx.manager, session.id).await;
+
+    assert!(matches!(
+        fx.manager
+            .queue_acp_prompt(session.id, "show my prompt".into())
+            .await
+            .expect("queue prompt"),
+        maestro_daemon::session::QueueAcpPrompt::Queued
+    ));
+
+    let (snapshot, _, _) = fx
+        .manager
+        .subscribe_acp_projection(session.id, EventCursor::Since(0))
+        .await
+        .expect("projection subscription")
+        .expect("structured session");
+    let user = snapshot
+        .rows
+        .iter()
+        .find(|row| row.kind == TranscriptRowKind::User)
+        .expect("user prompt row");
+    assert_eq!(user.data["content"]["text"], "show my prompt");
+
+    let persisted = fx
+        .manager
+        .read_acp_events(session.id, EventCursor::Since(0), 100)
+        .expect("event replay");
+    assert!(persisted.iter().any(|event| matches!(
+        &event.event,
+        maestro_daemon::sidecar::PersistedEvent::User { row }
+            if row.data["content"]["text"] == "show my prompt"
+    )));
+
+    fx.manager.kill(session.id, false).await.unwrap();
+}
+
 #[tokio::test]
 async fn stale_turn_completion_cannot_end_the_next_turn() {
     let fx = DaemonFixture::new();
@@ -365,6 +468,7 @@ async fn stale_turn_completion_cannot_end_the_next_turn() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     let maestro_daemon::session::BeginAcpTurn::Started(_, first) =
         fx.manager.begin_acp_turn(session.id).await.unwrap()
@@ -408,6 +512,7 @@ async fn cancelled_prompt_that_never_settles_fails_the_session() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -446,6 +551,7 @@ async fn cancellation_settlement_allows_the_next_prompt_permission() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
@@ -505,11 +611,12 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_LOAD_REPLAY".into(), "2".into());
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
     let acp_id = session.acp_session_id.clone().expect("acp id");
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -621,7 +728,7 @@ async fn shutdown_preserves_a_pristine_structured_worktree_for_recovery() {
         .create(CreateSessionRequest {
             view: SessionView::Structured,
             cwd: repo.path().to_path_buf(),
-            command: "claude".into(),
+            command: "codex".into(),
             env: fake.env(),
             metadata: HashMap::new(),
             worktree: Some(WorktreeSpec {
@@ -629,10 +736,12 @@ async fn shutdown_preserves_a_pristine_structured_worktree_for_recovery() {
                 branch: branch.into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
     assert_eq!(session.cwd, worktree);
+    wait_for_ready(&fx.manager, session.id).await;
     push_all_to_origin(repo.path(), origin.path());
 
     fx.manager.shutdown().await;
@@ -681,6 +790,7 @@ async fn failed_recovery_cleans_its_fifo() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let old_pid = fake.pid();
     fx.manager.shutdown().await;
     wait_for_exit(old_pid).await;
@@ -714,28 +824,56 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
         empty.path().to_string_lossy().into_owned(),
     )]);
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
-        .expect("a failed session, not an error");
+        .expect("create registers a Starting session");
+    assert_eq!(created.activity, ActivityState::Starting);
 
+    // The background handshake fails because the adapter binary is missing.
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.status, SessionStatus::Dead);
     assert_eq!(session.activity, ActivityState::Error);
     let detail = session.activity_detail.clone().expect("actionable detail");
-    assert!(detail.contains(ADAPTER_BIN), "{detail}");
-    assert!(detail.contains(INSTALL_COMMAND), "{detail}");
+    assert!(detail.contains(AcpAdapter::Codex.binary()), "{detail}");
+    assert!(
+        detail.contains(AcpAdapter::Codex.install_command()),
+        "{detail}"
+    );
     assert_eq!(session.acp_session_id, None);
 
     // It is a real session: listed, on disk, and dismissable like any other
     // dead one.
-    assert!(fx.manager.has(session.id).await);
+    assert!(fx.manager.has(created.id).await);
     assert!(fx
         .sidecar_dir()
-        .join(format!("{}.json", session.id))
+        .join(format!("{}.json", created.id))
         .exists());
-    fx.manager.kill(session.id, false).await.expect("dismiss");
-    assert!(!fx.manager.has(session.id).await);
+    fx.manager.kill(created.id, false).await.expect("dismiss");
+    assert!(!fx.manager.has(created.id).await);
+}
+
+#[tokio::test]
+async fn unsupported_structured_command_fails_without_launching_claude() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+
+    let err = fx
+        .manager
+        .create(structured_command(cwd.path(), fake.env(), "opencode"))
+        .await
+        .expect_err("unsupported command is rejected at request validation");
+
+    assert!(
+        matches!(err, maestro_daemon::SessionError::BadRequest(ref msg) if msg.contains("Claude Code or Codex")),
+        "{err:?}"
+    );
+    assert!(
+        fake.log().is_empty(),
+        "unsupported command launched an adapter"
+    );
 }
 
 #[tokio::test]
@@ -750,6 +888,7 @@ async fn kill_sends_cancel_then_sigterm_and_removes_the_sidecar() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     assert!(pid_alive(pid));
 
@@ -792,6 +931,8 @@ async fn shutdown_reaps_every_adapter_child() {
         .create(structured(cwd.path(), b.env()))
         .await
         .expect("create b");
+    wait_for_ready(&fx.manager, sa.id).await;
+    wait_for_ready(&fx.manager, sb.id).await;
     let (pa, pb) = (a.pid(), b.pid());
     assert!(pid_alive(pa) && pid_alive(pb));
 
@@ -826,10 +967,13 @@ async fn dismissal_during_shutdown_does_not_restore_recovery_artifacts() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
-    fx.manager
+    let blocker_session = fx
+        .manager
         .create(structured(cwd.path(), blocker.env()))
         .await
         .expect("create blocker");
+    wait_for_ready(&fx.manager, session.id).await;
+    wait_for_ready(&fx.manager, blocker_session.id).await;
 
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
@@ -881,6 +1025,7 @@ async fn shutdown_does_not_recover_an_adapter_that_already_exited() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_exit(fake.pid()).await;
 
     fx.manager.shutdown().await;
@@ -914,23 +1059,31 @@ async fn shutdown_waits_for_structured_creation_and_rejects_new_creates() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_DELAY_SESSION_NEW_MS".into(), "500".into());
 
-    let create_cwd = cwd.path().to_path_buf();
-    let manager = fx.manager.clone();
-    let create = tokio::spawn(async move { manager.create(structured(&create_cwd, env)).await });
+    // create() returns immediately; the handshake runs in the background
+    // and holds a lifecycle permit.
+    let session = fx
+        .manager
+        .create(structured(cwd.path(), env))
+        .await
+        .expect("create");
+
+    // Wait until the adapter has received session/new (handshake in progress).
     wait_for_async(Duration::from_secs(5), || async {
         fake.log().contains("recv session/new")
     })
     .await;
 
+    // Shutdown must wait for the in-flight background handshake.
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
     tokio::time::sleep(Duration::from_millis(50)).await;
     assert!(
         !shutdown.is_finished(),
-        "shutdown returned before create finished"
+        "shutdown returned before handshake finished"
     );
 
-    let session = create.await.expect("create task").expect("create");
+    // The handshake completes in the background (500ms delay).
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     shutdown.await.expect("shutdown task");
 
@@ -963,27 +1116,37 @@ async fn structured_handshakes_run_independently() {
         gate.to_string_lossy().into_owned(),
     );
 
-    let first_cwd = cwd.path().to_path_buf();
-    let manager = fx.manager.clone();
-    let first =
-        tokio::spawn(async move { manager.create(structured(&first_cwd, blocked_env)).await });
-    wait_for_async(Duration::from_secs(5), || async {
-        blocked.log().contains("recv session/new")
-    })
-    .await;
+    // Both create() calls return immediately with Starting; the first
+    // adapter's handshake is gated while the second runs freely.
+    let first = fx
+        .manager
+        .create(structured(cwd.path(), blocked_env))
+        .await
+        .expect("first create");
+    let second = fx
+        .manager
+        .create(structured(cwd.path(), ready.env()))
+        .await
+        .expect("second create");
 
-    let second = tokio::time::timeout(
-        Duration::from_secs(5),
-        fx.manager.create(structured(cwd.path(), ready.env())),
-    )
-    .await
-    .expect("second handshake was blocked by the first")
-    .expect("second create");
-    assert_eq!(second.status, SessionStatus::Running);
-    assert!(!first.is_finished(), "the gate must still block the first");
+    // The second handshake completes independently of the first.
+    let second_ready = wait_for_ready(&fx.manager, second.id).await;
+    assert_eq!(second_ready.activity, ActivityState::Idle);
+
+    // The first handshake is still blocked.
+    let first_snap = fx
+        .manager
+        .snapshot()
+        .await
+        .into_iter()
+        .find(|s| s.id == first.id)
+        .unwrap();
+    assert_eq!(first_snap.activity, ActivityState::Starting);
 
     std::fs::write(&gate, b"release").unwrap();
-    let first = first.await.expect("first task").expect("first create");
+    let first_ready = wait_for_ready(&fx.manager, first.id).await;
+    assert_eq!(first_ready.activity, ActivityState::Idle);
+
     fx.manager.kill(first.id, false).await.expect("kill first");
     fx.manager
         .kill(second.id, false)
@@ -1011,16 +1174,18 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
         gate_b.to_string_lossy().into_owned(),
     );
 
-    let create_a = {
-        let manager = fx.manager.clone();
-        let cwd = cwd.path().to_path_buf();
-        tokio::spawn(async move { manager.create(structured(&cwd, env_a)).await })
-    };
-    let create_b = {
-        let manager = fx.manager.clone();
-        let cwd = cwd.path().to_path_buf();
-        tokio::spawn(async move { manager.create(structured(&cwd, env_b)).await })
-    };
+    // Both create() calls return immediately; the background handshake
+    // tasks hold lifecycle permits and are blocked on their gates.
+    let session_a = fx
+        .manager
+        .create(structured(cwd.path(), env_a))
+        .await
+        .expect("create a");
+    let session_b = fx
+        .manager
+        .create(structured(cwd.path(), env_b))
+        .await
+        .expect("create b");
     wait_for_async(Duration::from_secs(5), || async {
         a.log().contains("recv session/new") && b.log().contains("recv session/new")
     })
@@ -1040,14 +1205,14 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
     assert!(!shutdown.is_finished());
 
     std::fs::write(&gate_a, b"release").unwrap();
-    let session_a = create_a.await.expect("create a task").expect("create a");
+    wait_for_ready(&fx.manager, session_a.id).await;
     assert!(
         !shutdown.is_finished(),
         "shutdown ignored the second create"
     );
 
     std::fs::write(&gate_b, b"release").unwrap();
-    let session_b = create_b.await.expect("create b task").expect("create b");
+    wait_for_ready(&fx.manager, session_b.id).await;
     shutdown.await.expect("shutdown task");
 
     wait_for_exit(a.pid()).await;
@@ -1063,7 +1228,7 @@ async fn shutdown_waits_for_every_admitted_structured_create() {
 }
 
 #[tokio::test]
-async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
+async fn killing_a_starting_session_rolls_back_and_settles_admission() {
     let fx = DaemonFixture::new();
     let fake = Fake::new();
     let repo = TempDir::new().unwrap();
@@ -1086,42 +1251,33 @@ async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
             branch: "cancelled-create".into(),
             create_branch: true,
         }),
+        auto_approve: false,
     };
 
-    let create = {
-        let manager = fx.manager.clone();
-        tokio::spawn(async move { manager.create(request).await })
-    };
+    // create() returns immediately with Starting; the handshake is gated.
+    let session = fx.manager.create(request).await.expect("create");
+    assert_eq!(session.activity, ActivityState::Starting);
     wait_for_async(Duration::from_secs(5), || async {
         fake.log().contains("recv session/new")
     })
     .await;
-    let id = fake
-        .log()
-        .lines()
-        .find_map(|line| line.strip_prefix("env MAESTRO_SESSION_ID="))
-        .and_then(|id| uuid::Uuid::parse_str(id).ok())
-        .expect("session id in adapter log");
     let pid = fake.pid();
 
-    create.abort();
-    let shutdown = {
-        let manager = fx.manager.clone();
-        tokio::spawn(async move { manager.shutdown().await })
-    };
-    assert!(create.await.unwrap_err().is_cancelled());
-    tokio::time::timeout(Duration::from_secs(5), shutdown)
+    // Kill the session while its handshake is still in progress.
+    // force=true because the worktree has an unpushed branch commit.
+    fx.manager.kill(session.id, true).await.expect("kill");
+
+    // Release the gate so the background task can finish and settle.
+    std::fs::write(&gate, b"release").unwrap();
+
+    // Shutdown must not hang — the lifecycle permit is settled.
+    tokio::time::timeout(Duration::from_secs(5), fx.manager.shutdown())
         .await
-        .expect("cancelled admission kept shutdown waiting")
-        .expect("shutdown task");
+        .expect("shutdown hung on a settled permit");
+
     wait_for_exit(pid).await;
-    wait_for_async(Duration::from_secs(5), || async {
-        !fx.fifo_dir().join(format!("{id}.fifo")).exists()
-            && !repo.path().join("cancelled-create").exists()
-    })
-    .await;
     assert!(fx.manager.snapshot().await.is_empty());
-    let id = id.to_string();
+    let id = session.id.to_string();
     assert!(
         std::fs::read_dir(fx.sidecar_dir())
             .into_iter()
@@ -1131,7 +1287,7 @@ async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
                 .file_name()
                 .to_string_lossy()
                 .starts_with(&id)),
-        "cancelled create left a sidecar artifact"
+        "killed Starting session left a sidecar artifact"
     );
 }
 
@@ -1148,6 +1304,7 @@ async fn shutdown_drains_final_notifications_to_the_log() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
             .read_acp_events(session.id, EventCursor::Since(0), 10)
@@ -1178,6 +1335,7 @@ async fn adapter_exit_marks_the_session_dead_and_keeps_it_listed() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     fx.manager.start_liveness_watcher(Duration::from_millis(50));
 
     // The agent dies out from under the daemon: the liveness pass, not tmux,

crates/maestro-daemon/tests/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

@@ -154,7 +154,8 @@ async fn structured_session(h: &Harness, fake: &FakeAcp) -> Uuid {
 }
 
 async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>) -> Uuid {
-    h.manager
+    let id = h
+        .manager
         .create(CreateSessionRequest {
             view: SessionView::Structured,
             cwd: "/tmp".into(),
@@ -162,10 +163,13 @@ async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>)
             env,
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
-        .id
+        .id;
+    wait_for_session_activity(h, id, ActivityState::Idle).await;
+    id
 }
 
 async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
@@ -234,6 +238,60 @@ async fn structured_ws_sends_snapshot_then_live_projection() {
     );
 }
 
+#[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;
@@ -493,6 +551,7 @@ async fn structured_prompt_rejects_unknown_and_unavailable_sessions() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -626,6 +685,7 @@ async fn structured_replay_rejects_unknown_terminal_and_dead_sessions() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -768,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"))
@@ -942,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(
@@ -957,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]
@@ -985,6 +1057,7 @@ async fn patch_session_renames_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1028,6 +1101,7 @@ async fn post_focus_stamps_last_focused_at() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1062,6 +1136,7 @@ async fn delete_owned_session_kills_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1084,6 +1159,7 @@ async fn spawn_via_manager(h: &Harness) -> Uuid {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
@@ -1198,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();
@@ -1251,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();
@@ -1281,6 +1359,7 @@ async fn attach_ws_streams_pty_bytes() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1383,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");
@@ -1428,6 +1508,12 @@ async fn events_ws_streams_structured_activity_without_hook_overrides() {
     let maestro_protocol::CatalogEvent::SessionAdded { session } = next_event(&mut ws).await else {
         panic!("expected structured SessionAdded")
     };
+    assert_eq!(session.activity, ActivityState::Starting);
+    // The background handshake completes and sends SessionUpdated → Idle.
+    let maestro_protocol::CatalogEvent::SessionUpdated { session } = next_event(&mut ws).await
+    else {
+        panic!("expected SessionUpdated after handshake")
+    };
     assert_eq!(session.activity, ActivityState::Idle);
 
     let client = reqwest::Client::new();
@@ -1495,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/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/tests/e2e.rs

@@ -33,6 +33,7 @@ fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     }
 }
 
@@ -111,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,
     }
 }
 
@@ -206,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");
@@ -260,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");
@@ -319,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
@@ -383,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();
@@ -399,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")
@@ -431,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
@@ -823,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");
@@ -872,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,
     }
 }
 
@@ -1064,6 +1075,7 @@ async fn sigterm_stops_structured_child_before_events_ws_drains() {
             env: fake.env.clone(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("spawn structured session");

crates/maestro-protocol/src/display.rs

@@ -226,6 +226,15 @@ pub fn command_tool(command: &str) -> Option<&'static str> {
         .map(|(_, tool)| *tool)
 }
 
+/// 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).
@@ -1064,4 +1073,14 @@ mod tests {
         assert_eq!(tokenize("\"FOO=1\" claude").unwrap()[0].plain_eq, None);
         assert_eq!(tokenize("FOO\\=1 claude").unwrap()[0].plain_eq, None);
     }
+
+    #[test]
+    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
@@ -175,6 +175,10 @@ pub enum ActivityState {
     AwaitingInput,
     /// An agent reported a failure, or a structured session/turn failed.
     Error,
+    /// The ACP adapter is booting; the session is registered but cannot accept
+    /// prompts yet. Older clients that do not know this variant degrade it to
+    /// `Idle` via the lenient deserializer — acceptable.
+    Starting,
 }
 
 impl<'de> Deserialize<'de> for ActivityState {
@@ -187,6 +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,
         })
@@ -225,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"],
         )),
     }
 }
@@ -383,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.
@@ -522,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
@@ -824,6 +839,15 @@ pub struct TurnState {
     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.
@@ -846,6 +870,8 @@ pub struct ReducedState {
     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.
@@ -871,6 +897,13 @@ 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")]
@@ -1233,6 +1266,7 @@ mod tests {
                 create_branch: true,
             }),
             view: SessionView::Terminal,
+            auto_approve: false,
         };
         assert_eq!(req, round_trip(&req));
     }

crates/maestro-protocol/src/routes.rs

@@ -86,11 +86,21 @@ 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}")
@@ -108,7 +118,9 @@ pub mod patterns {
     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";
 }
 

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/src/app.rs

@@ -11,6 +11,7 @@
 //! `dispatch` / the overlay routing.
 
 use std::collections::{HashMap, HashSet};
+use std::io::Write;
 use std::path::PathBuf;
 use std::time::Duration;
 
@@ -54,6 +55,36 @@ 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,
@@ -340,6 +371,10 @@ 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);
@@ -423,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>) {
@@ -1905,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;
@@ -3009,6 +3105,7 @@ mod tests {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         };
         app.submit_spawn(req).await;
 
@@ -3053,17 +3150,20 @@ mod tests {
         let request = |view| CreateSessionRequest {
             view,
             cwd: std::path::PathBuf::from("/srv/work"),
-            command: "claude".into(),
+            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;

crates/maestro-tui/src/draft.rs

@@ -41,7 +41,7 @@ use std::time::{Duration, Instant};
 
 use chrono::{DateTime, Utc};
 use maestro_config::{builtin_presets, custom_preset};
-use maestro_protocol::display::{abbreviate_dir, command_tool};
+use maestro_protocol::display::{abbreviate_dir, supports_structured_view};
 use maestro_protocol::{
     BranchInfo, CreateSessionRequest, Project, SessionView, SpawnPreset, WorktreeSpec,
 };
@@ -91,7 +91,7 @@ pub enum DraftField {
     /// 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 only.
+    /// ACP-backed transcript instead of a terminal. Claude Code or Codex.
     StructuredToggle,
     /// Worktree on/off for this session (#65). Enter / Space toggles.
     WorktreeToggle,
@@ -255,9 +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. Off by default and supported only
-    /// when the resolved command is Claude Code.
+    /// 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>,
@@ -298,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,
@@ -319,6 +324,7 @@ impl Default for DraftPane {
             worktree_enabled: true,
             advanced_collapsed: true,
             structured_view: false,
+            structured_view_touched: false,
             base_repo: None,
             probed_cwd: None,
             probe_seq: 0,
@@ -337,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
     }
 }
 
@@ -356,7 +366,7 @@ impl DraftPane {
             .position(|p| !p.command.is_empty())
             .unwrap_or(0);
         self.apply_seed_command();
-        self.clear_unsupported_structured_view();
+        self.sync_structured_view();
     }
 
     /// Land a seeded command on the tile that runs it: its own preset when the
@@ -673,18 +683,24 @@ impl DraftPane {
     }
 
     fn supports_structured_view(&self) -> bool {
-        command_tool(self.command()) == Some("claude")
+        supports_structured_view(self.command())
     }
 
-    fn clear_unsupported_structured_view(&mut self) {
+    /// 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;
         }
     }
 
@@ -718,6 +734,10 @@ 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: if self.structured_view && self.supports_structured_view() {
                 SessionView::Structured
@@ -729,6 +749,7 @@ impl DraftPane {
             env: Default::default(),
             metadata,
             worktree,
+            auto_approve,
         })
     }
 
@@ -827,7 +848,7 @@ impl DraftPane {
         }
         self.selected_preset =
             ((self.selected_preset as i32) + delta).rem_euclid(len as i32) as usize;
-        self.clear_unsupported_structured_view();
+        self.sync_structured_view();
     }
 
     /// Step-one boxes surviving the type-to-filter, in display order. A
@@ -1130,7 +1151,7 @@ impl DraftPane {
                     DraftField::Preset | DraftField::Submit => {}
                     DraftField::CustomCommand => {
                         self.custom_command.handle_key(other);
-                        self.clear_unsupported_structured_view();
+                        self.sync_structured_view();
                     }
                     // Typing filters the list; the highlight resets to the top
                     // so a narrowed search always starts at its best match.
@@ -1776,6 +1797,7 @@ mod tests {
             id: "aider".into(),
             label: "Aider".into(),
             command: "aider".into(),
+            auto_approve: false,
         }]);
         assert_eq!(
             draft.command(),
@@ -1798,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");
@@ -1822,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");
@@ -1888,18 +1913,42 @@ mod tests {
     }
 
     #[test]
-    fn structured_view_is_default_off_and_only_visible_for_claude_code() {
+    fn structured_view_is_default_on_and_visible_for_supported_agents() {
         let mut draft = DraftPane {
             advanced_collapsed: false,
             ..DraftPane::default()
         };
-        assert!(!draft.structured_view);
+        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("[ ] structured view"), "{rendered}");
+        assert!(rendered.contains("[x] structured view"), "{rendered}");
 
-        draft.toggle_structured_view();
-        assert!(draft.structured_view);
+        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!(
@@ -1928,9 +1977,9 @@ mod tests {
 
     /// 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, so the toggle stays
-    /// offered and the request carries `Structured`; an unrelated program
-    /// does not.
+    /// 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)] = &[
@@ -1952,6 +2001,16 @@ mod tests {
             ("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),
@@ -1973,16 +2032,16 @@ mod tests {
             };
             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:?}"
             );
-            draft.toggle_structured_view();
             assert_eq!(
                 draft.structured_view, supported,
-                "toggle takes effect for {command:?}"
+                "default selection for {command:?}"
             );
             let view = draft.build_request().unwrap().view;
             assert_eq!(
@@ -1994,12 +2053,18 @@ mod tests {
                 },
                 "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
-    /// through a wrapper still offers structured view.
+    /// Code or Codex through a wrapper still offers structured view.
     #[test]
     fn structured_view_follows_command_resolution_for_presets() {
         let mut draft = DraftPane {
@@ -2013,21 +2078,34 @@ mod tests {
                 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));
-        draft.toggle_structured_view();
         assert!(draft.structured_view);
         assert_eq!(draft.build_request().unwrap().view, SessionView::Structured);
 
-        // Switching to a preset that does not resolve to Claude clears the
+        // 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");
@@ -2036,11 +2114,50 @@ mod tests {
         assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
     }
 
-    /// Editing the custom-command text away from Claude clears an armed
+    /// 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_claude() {
+    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,
@@ -2049,22 +2166,22 @@ mod tests {
             ..DraftPane::default()
         };
         draft.selected_preset = draft.presets.len() - 1;
-        draft.custom_command = crate::text_input::TextInput::with_value("claude");
-        draft.toggle_structured_view();
+        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(), "claude -p");
-        assert!(draft.structured_view, "still Claude, selection survives");
+        assert_eq!(draft.command(), "codex -p");
+        assert!(draft.structured_view, "still Codex, selection survives");
 
-        for _ in 0.."claude -p".chars().count() {
+        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 claude clears the stale selection"
+            "editing the program away from Codex clears the stale selection"
         );
         assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
     }

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

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

crates/maestro-tui/src/sidebar.rs

@@ -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_pane.rs

@@ -308,11 +308,12 @@ fn fallback_after_removal(
 
 fn build_lines(state: &StructuredState, width: usize) -> Vec<VisualLine> {
     let mut out = Vec::new();
-    for row in &state.rows {
+    for (index, row) in state.rows.iter().enumerate() {
         if row.kind == TranscriptRowKind::Plan {
             continue;
         }
         let row_width = width.saturating_sub(1).max(1);
+        let start = out.len();
         match row.kind {
             TranscriptRowKind::User => push_wrapped(
                 &mut out,
@@ -356,10 +357,53 @@ fn build_lines(state: &StructuredState, width: usize) -> Vec<VisualLine> {
             ),
             TranscriptRowKind::Plan => {}
         }
+        if out.len() > start
+            && state.rows[index + 1..]
+                .iter()
+                .any(|next| next.kind != TranscriptRowKind::Plan)
+        {
+            // A blank surface line is the vertical padding that keeps adjacent
+            // transcript blocks readable at a glance.
+            out.push(VisualLine {
+                text: String::new(),
+                row_id: None,
+                rail: false,
+                tone: Tone::Normal,
+            });
+        }
     }
     out
 }
 
+/// Text supplied to the terminal clipboard when a transcript block is
+/// clicked. It preserves the full tool detail rather than its compact preview.
+pub fn copy_text(row: &TranscriptRow) -> String {
+    match row.kind {
+        TranscriptRowKind::User
+        | TranscriptRowKind::AgentText
+        | TranscriptRowKind::AgentThought => content_text(row),
+        TranscriptRowKind::ToolCall | TranscriptRowKind::ToolDiff => {
+            let (name, argument) = tool_title(row);
+            let mut lines = vec![if argument.is_empty() {
+                name
+            } else {
+                format!("{name}  {argument}")
+            }];
+            lines.extend(tool_content_lines(row, None));
+            lines.join("\n")
+        }
+        TranscriptRowKind::Approval => row
+            .data
+            .get("toolCall")
+            .and_then(|tool| tool.get("title"))
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or("permission requested")
+            .into(),
+        TranscriptRowKind::Notice => "[notice]".into(),
+        TranscriptRowKind::Plan => String::new(),
+    }
+}
+
 fn push_wrapped(
     out: &mut Vec<VisualLine>,
     row: &TranscriptRow,
@@ -1000,6 +1044,39 @@ mod tests {
         );
     }
 
+    #[test]
+    fn transcript_blocks_have_a_padding_line_between_them() {
+        let mut state = StructuredState::default();
+        state.rows = vec![
+            row(
+                "one",
+                TranscriptRowKind::User,
+                json!({"content":{"type":"text","text":"first"}}),
+            ),
+            row(
+                "two",
+                TranscriptRowKind::AgentText,
+                json!({"content":{"type":"text","text":"second"}}),
+            ),
+        ];
+
+        let lines = build_lines(&state, 80);
+        assert_eq!(lines.len(), 3);
+        assert_eq!(lines[1].text, "");
+        assert!(lines[1].row_id.is_none());
+    }
+
+    #[test]
+    fn copying_a_tool_keeps_its_full_detail() {
+        let tool = row(
+            "t",
+            TranscriptRowKind::ToolCall,
+            json!({"title":"Bash(cargo test)","content":[{"type":"content","content":{"type":"text","text":"all green"}}]}),
+        );
+
+        assert_eq!(copy_text(&tool), "Bash  cargo test\nall green");
+    }
+
     #[test]
     fn tool_is_compact_until_selected_row_expands() {
         let mut state = StructuredState::default();
@@ -1420,7 +1497,7 @@ mod tests {
         let mut state = StructuredState::default();
         state.follow_selection = false;
         numbered_rows(&mut state, 20);
-        state.scroll = 10;
+        state.scroll = 20;
 
         let before = render_transcript_lines(&pane, &mut state, 30, 5);
         assert!(before[0].contains("line 10"), "{before:?}");
@@ -1439,7 +1516,7 @@ mod tests {
         let mut state = StructuredState::default();
         state.follow_selection = false;
         numbered_rows(&mut state, 20);
-        state.scroll = 10;
+        state.scroll = 20;
 
         let before = render_transcript_lines(&pane, &mut state, 30, 5);
         assert!(before[0].contains("line 10"), "{before:?}");
@@ -1459,7 +1536,7 @@ mod tests {
         let mut state = StructuredState::default();
         state.follow_selection = false;
         numbered_rows(&mut state, 20);
-        state.scroll = 10;
+        state.scroll = 20;
 
         let before = render_transcript_lines(&pane, &mut state, 30, 5);
         assert!(before[0].contains("line 10"), "{before:?}");
@@ -1478,7 +1555,7 @@ mod tests {
         let mut state = StructuredState::default();
         state.follow_selection = false;
         numbered_rows(&mut state, 20);
-        state.scroll = 10;
+        state.scroll = 20;
 
         let before = render_transcript_lines(&pane, &mut state, 30, 5);
         assert!(before[0].contains("line 10"), "{before:?}");
@@ -1497,7 +1574,7 @@ mod tests {
         let mut state = StructuredState::default();
         state.follow_selection = false;
         numbered_rows(&mut state, 20);
-        state.scroll = 10;
+        state.scroll = 20;
 
         render_transcript_lines(&pane, &mut state, 30, 5);
         // Simulate a `TranscriptDelta::Patch` on a collapsed tool row above the

crates/maestro-tui/src/structured_task.rs

@@ -199,6 +199,18 @@ impl StructuredState {
         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;
@@ -657,6 +669,25 @@ mod tests {
         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();

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

@@ -195,25 +195,28 @@ 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. A daemon restart ends an in-flight structured turn, but preserves its
 worktree, session record, and event-log transcript. The replacement daemon

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`          |
 

docs/STRUCTURED-VIEW.md

@@ -16,10 +16,10 @@ does not exist yet, and nothing here describes it.
 
 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 adapter process, `claude-code-acp`, is the
-ACP **agent** — it wraps Claude Code's own SDK and translates the model's
-tool calls into ACP `session/update` notifications instead of drawing them to
-a pane. `crates/maestro-acp` owns the daemon's side of that connection;
+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.
 
@@ -35,32 +35,44 @@ 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
 
-`ADAPTER_BIN` (`claude-code-acp`) is resolved by walking `PATH` — the
-session's own `PATH` env var if the spawn request set one, the daemon's
-otherwise — and taking the first executable file named `claude-code-acp` on
-it. Install it once per host:
+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.
 
-```sh
-npm install -g --prefix ~/.local @zed-industries/claude-code-acp
-```
+| 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. |
 
-That is `maestro_acp::INSTALL_COMMAND`, and it is not just documentation: it
-is baked into `AcpError::AdapterMissing`'s message. When the adapter cannot
-be found, spawn still creates the session — **Dead**, with that install
-command as its `activity_detail` — so the sidebar names the fix instead of
-the session silently never appearing (see `docs/INSTALL.md` for the full
-install writeup, including the systemd `PATH` caveat). The adapter also needs
-a logged-in Claude Code (`claude /login`); a missing login surfaces the same
-way, via the adapter's own stderr tail in the failure message.
+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 a node process and the Claude Code SDK behind it, 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.
+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
 
@@ -69,17 +81,17 @@ declares, deliberately, almost nothing:
 
 | Capability | Declared | Why |
 | --- | --- | --- |
-| `fs.readTextFile` | `false` | The adapter uses Claude Code's own Read tool instead of asking the daemon to read a file on its behalf — the same tool a terminal-view Claude Code session uses. |
-| `fs.writeTextFile` | `false` | Same reasoning, for Write. |
-| `terminal` | `false` | The adapter runs Claude Code's own Bash tool rather than asking the daemon to open a terminal for it. |
+| `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 `claude-code-acp` has
-never asked for it, not because it was weighed and refused.
+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.
@@ -96,6 +108,14 @@ 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
@@ -106,14 +126,14 @@ crate.
 
 | Kind | Carries | Row identity |
 | --- | --- | --- |
-| `User` | An echoed `user_message_chunk` — the prompt text as ACP saw it. | `user:<message_id>`, or `user:<seq>` when the chunk carries no id. |
-| `AgentText` | An `agent_message_chunk` — the agent's visible reply, streamed. | `agent:<message_id>` / `agent:<seq>`. Later chunks for the same id are appended into `data.content.text` in place, not appended as new rows. |
-| `AgentThought` | An `agent_thought_chunk` — the model's reasoning stream. | `thought:<message_id>` / `thought:<seq>`, coalesced the same way as `AgentText`. |
+| `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. | `notice:<seq>`. |
+| `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
@@ -147,7 +167,10 @@ choices, not daemon ones.
   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` are derived, not renderer-computed).
+  `.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.
@@ -164,9 +187,29 @@ choices, not daemon ones.
 - 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 entirely and render the current plan in a separate
-  plan rail (web) / status line (TUI) instead.
-- How `responding` vs. `thinking` are distinguished visually, if at all.
+  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.
@@ -197,8 +240,9 @@ every row, once appended, is only ever patched or left alone.
 
 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 an `Approval` row share a cursor
-sequence with raw ACP JSON without pretending to be ACP traffic). Two ways to
+`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
@@ -247,7 +291,7 @@ pending decision, entirely on the daemon side:
 - **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_approval`)
+  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
@@ -281,6 +325,26 @@ pending decision, entirely on the daemon side:
 
 ## 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
@@ -289,9 +353,15 @@ 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."
 
-- A prompt claims the turn and dispatches it to ACP as one operation. While a
+- 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 — one active turn per session, never a hidden queue of prompts.
+  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
@@ -315,8 +385,8 @@ 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": "approval", "row": …}` envelope for a
-  daemon-generated row. Both share the same 1-based line-position cursor. A
+  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

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

@@ -12,6 +12,7 @@ import type {
   RecentDirs,
   Session,
   StructuredApprovalDecision,
+  StructuredConfigRequest,
   StructuredPromptRequest,
   Uuid,
 } from "./types.js";
@@ -93,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
@@ -168,6 +184,15 @@ export async function sendStructuredPrompt(id: Uuid, prompt: string): Promise<vo
   );
 }
 
+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(

web/src/attach.ts

@@ -64,6 +64,7 @@ export function createAttachConnection(
     <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;
@@ -323,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;
@@ -342,6 +346,7 @@ export function createAttachConnection(
   };
 
   function connect(): void {
+    awaitingReplay = true;
     ws = new WebSocket(attachWsUrl(sessionId));
     ws.binaryType = "arraybuffer";
 
@@ -362,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();
+          });
+        });
       }
     };
 
@@ -463,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/layout/MultiView.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { leaves } from "../../layout.js";
+import { createLayoutStore } from "../../stores/layoutStore.js";
+import type { Session } from "../../types.js";
+import { MultiView } from "./MultiView.js";
+
+vi.mock("../terminal/TerminalPane.js", () => ({
+  TerminalPane: ({ sessionId }: { sessionId: string }) => <div data-testid={`terminal-${sessionId}`} />,
+}));
+
+vi.mock("../structured/StructuredPane.js", () => ({
+  StructuredPane: ({ sessionId }: { sessionId: string }) => <div data-testid={`structured-${sessionId}`} />,
+}));
+
+afterEach(cleanup);
+
+function store() {
+  return createLayoutStore({
+    load: () => null,
+    save: vi.fn(),
+    scheduler: { setTimer: () => 1, clearTimer: () => {} },
+  });
+}
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/n",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  } as Session;
+}
+
+describe("MultiView", () => {
+  it("shows the empty state when the active tab has no panes", () => {
+    const s = store();
+    render(<MultiView store={s} />);
+    expect(screen.getByText(/No session open/)).toBeTruthy();
+  });
+
+  it("renders a pane per leaf, dispatching to the terminal or structured body", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    s.getState().openSessionBeside("s2");
+    const sessions = new Map([
+      ["s1", session("s1")],
+      ["s2", session("s2", { view: "Structured" })],
+    ]);
+    render(<MultiView store={s} sessions={sessions} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+    expect(screen.getByTestId("structured-s2")).toBeTruthy();
+  });
+
+  it("split right adds a second pane to the tree", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    fireEvent.click(screen.getByTitle("Split right"));
+    expect(screen.getAllByText("Empty pane")).toHaveLength(1);
+  });
+
+  it("close pane removes it", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    const leafId = leaves(s.getState().layout.tabs[0].root)[0].id;
+    s.getState().splitFocused(leafId, "row"); // adds an empty leaf beside s1
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    // splitFocused(after: true) puts the fresh empty leaf second — close it.
+    fireEvent.click(screen.getAllByTitle("Close pane")[1]);
+    expect(screen.queryByText("Empty pane")).toBeNull();
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+  });
+
+  it("prunes a leaf whose session no longer exists, once the live set is known", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    s.getState().openSessionBeside("dead");
+    render(<MultiView store={s} sessions={new Map([["s1", session("s1")]])} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+    expect(screen.queryByTestId("terminal-dead")).toBeNull();
+  });
+
+  it("does not touch the layout while the live set is still unknown", () => {
+    const s = store();
+    s.getState().openSession("s1");
+    render(<MultiView store={s} />);
+    expect(screen.getByTestId("terminal-s1")).toBeTruthy();
+  });
+});

web/src/components/layout/MultiView.tsx

@@ -0,0 +1,203 @@
+// React port of multiview.ts's tab + split tree (issue #249). Preview mode
+// (docs/PREVIEW.md) is issue #251; sidebar drag-to-dock and the mobile
+// single-pane collapse stay with whichever issue wires this into the shell
+// (#253) — this renders the tree itself: tabs, nested splits, pane chrome.
+
+import type { ReactNode } from "react";
+import { useEffect, useRef } from "react";
+import { useStore } from "zustand";
+
+import { activeTab, type Dir, type Node } from "../../layout.js";
+import type { LayoutStore, LayoutStoreApi } from "../../stores/layoutStore.js";
+import type { Session, Uuid } from "../../types.js";
+import { PaneContainer } from "./PaneContainer.js";
+import { PaneTitle } from "./PaneTitle.js";
+import { TabBar } from "./TabBar.js";
+
+export interface MultiViewProps {
+  store: LayoutStoreApi;
+  /** Live sessions, keyed by id — drives pane titles and (once known) boot
+   *  reconciliation. Passing `undefined` defers reconciliation. */
+  sessions?: ReadonlyMap<Uuid, Session>;
+  onDisconnect?: (sessionId: Uuid) => void;
+  emptyState?: ReactNode;
+}
+
+export function MultiView({ store, sessions, onDisconnect, emptyState }: MultiViewProps) {
+  const layout = useStore(store, (s: LayoutStore) => s.layout);
+  const tab = activeTab(layout);
+
+  const reconciledRef = useRef(false);
+  useEffect(() => {
+    if (reconciledRef.current || !sessions) return;
+    reconciledRef.current = true;
+    store.getState().reconcile(new Set(sessions.keys()));
+  }, [sessions, store]);
+
+  return (
+    <div className="mv flex h-full min-h-0 flex-col">
+      <TabBar store={store} />
+      <div className="mv-canvas min-h-0 flex-1">
+        {tab.root ? (
+          <SplitNode node={tab.root} tab={tab} store={store} sessions={sessions} onDisconnect={onDisconnect} />
+        ) : (
+          (emptyState ?? (
+            <div className="mv-empty flex h-full items-center justify-center p-sp-4 text-fs-13 text-faint">
+              No session open — pick one from the sidebar, or spawn a new one.
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface TreeProps {
+  tab: { id: string; focusedLeafId: string | null };
+  store: LayoutStoreApi;
+  sessions?: ReadonlyMap<Uuid, Session>;
+  onDisconnect?: (sessionId: Uuid) => void;
+}
+
+function SplitNode({ node, ...rest }: TreeProps & { node: Node }) {
+  if (node.kind === "leaf") {
+    return <Pane leaf={node} isFocused={rest.tab.focusedLeafId === node.id} {...rest} />;
+  }
+  return <SplitContainer node={node} {...rest} />;
+}
+
+function SplitContainer({ node, ...rest }: TreeProps & { node: Extract<Node, { kind: "split" }> }) {
+  const slotA = useRef<HTMLDivElement | null>(null);
+  const slotB = useRef<HTMLDivElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  const onDividerPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    const divider = e.currentTarget;
+    const container = containerRef.current;
+    if (!container) return;
+    divider.setPointerCapture(e.pointerId);
+    const rect = container.getBoundingClientRect();
+    const move = (ev: PointerEvent) => {
+      const frac =
+        node.dir === "row" ? (ev.clientX - rect.left) / rect.width : (ev.clientY - rect.top) / rect.height;
+      node.ratio = Math.max(0.1, Math.min(0.9, frac));
+      if (slotA.current) slotA.current.style.flexGrow = String(node.ratio);
+      if (slotB.current) slotB.current.style.flexGrow = String(1 - node.ratio);
+    };
+    const up = (ev: PointerEvent) => {
+      try {
+        divider.releasePointerCapture(ev.pointerId);
+      } catch {
+        // already released
+      }
+      divider.removeEventListener("pointermove", move);
+      divider.removeEventListener("pointerup", up);
+      rest.store.getState().commitLayout();
+    };
+    divider.addEventListener("pointermove", move);
+    divider.addEventListener("pointerup", up);
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      className={`mv-split flex h-full min-h-0 w-full ${node.dir === "row" ? "flex-row" : "flex-col"}`}
+    >
+      <div ref={slotA} className="mv-slot min-h-0 min-w-0" style={{ flex: `${node.ratio} 1 0` }}>
+        <SplitNode node={node.a} {...rest} />
+      </div>
+      <div
+        className={
+          "mv-divider flex-none bg-border-strong hover:bg-accent " +
+          (node.dir === "row" ? "w-[3px] cursor-col-resize" : "h-[3px] cursor-row-resize")
+        }
+        onPointerDown={onDividerPointerDown}
+      />
+      <div ref={slotB} className="mv-slot min-h-0 min-w-0" style={{ flex: `${1 - node.ratio} 1 0` }}>
+        <SplitNode node={node.b} {...rest} />
+      </div>
+    </div>
+  );
+}
+
+function Pane({
+  leaf,
+  isFocused,
+  store,
+  sessions,
+  onDisconnect,
+}: TreeProps & { leaf: Extract<Node, { kind: "leaf" }>; isFocused: boolean }) {
+  const session = leaf.sessionId ? sessions?.get(leaf.sessionId) : undefined;
+  const splitFocused = (dir: Dir) => store.getState().splitFocused(leaf.id, dir);
+
+  return (
+    <div
+      className={
+        "mv-pane flex h-full min-h-0 min-w-0 flex-col border " +
+        (isFocused ? "border-accent" : "border-border-strong")
+      }
+      data-leaf-id={leaf.id}
+      data-session-id={leaf.sessionId ?? undefined}
+      onPointerDownCapture={() => store.getState().focusLeaf(leaf.id)}
+    >
+      <div className="mv-pane-header flex items-center justify-between gap-sp-2 border-b border-border-strong bg-surface px-sp-2 py-sp-1 text-fs-12">
+        {leaf.sessionId ? (
+          <PaneTitle sessionId={leaf.sessionId} session={session} />
+        ) : (
+          <span className="text-faint">Empty pane</span>
+        )}
+        <div className="mv-pane-tools flex items-center gap-sp-1">
+          {leaf.sessionId && onDisconnect && (
+            <button
+              type="button"
+              className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+              title="Disconnect"
+              onClick={() => onDisconnect(leaf.sessionId!)}
+            >
+              ⏻
+            </button>
+          )}
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Split right"
+            onClick={() => splitFocused("row")}
+          >
+            ▥
+          </button>
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Split down"
+            onClick={() => splitFocused("col")}
+          >
+            ▤
+          </button>
+          <button
+            type="button"
+            className="mv-tool rounded-r-1 px-sp-1 text-faint hover:bg-surface-3 hover:text-ink"
+            title="Close pane"
+            onClick={() => store.getState().closePane(leaf.id)}
+          >
+            ✕
+          </button>
+        </div>
+      </div>
+      <div className="mv-pane-host min-h-0 flex-1">
+        {leaf.sessionId ? (
+          <PaneContainer
+            sessionId={leaf.sessionId}
+            session={session}
+            focus={isFocused}
+            onClosed={() => store.getState().closeSession(leaf.sessionId!)}
+          />
+        ) : (
+          <div className="mv-pane-empty flex h-full items-center justify-center p-sp-4 text-fs-13 text-faint">
+            Empty pane — pick a session from the sidebar, or spawn one.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

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

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

web/src/components/layout/PaneContainer.tsx

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

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

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

web/src/components/layout/PaneTitle.tsx

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

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

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

web/src/components/layout/TabBar.tsx

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

web/src/components/sidebar/ActivityRail.tsx

@@ -0,0 +1,47 @@
+// docs/SIDEBAR.md: a 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/structured/ApprovalView.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ApprovalView } from "./ApprovalView.js";
+
+afterEach(cleanup);
+
+const ALL_OPTIONS = [
+  { optionId: "a1", name: "Allow once", kind: "allow_once" as const },
+  { optionId: "a2", name: "Allow always", kind: "allow_always" as const },
+  { optionId: "r1", name: "Reject", kind: "reject_once" as const },
+];
+
+function buttons(): string[] {
+  return [...document.querySelectorAll(".st-approval-acts button")].map((b) => b.textContent ?? "");
+}
+
+describe("ApprovalView", () => {
+  it("asks the operator with the three decisions the daemon exposes", () => {
+    render(
+      <ApprovalView
+        request={{ toolCall: { title: "Write(a.ts)", locations: [{ path: "/repo/a.ts" }] }, options: ALL_OPTIONS }}
+        pending
+        onDecide={() => Promise.resolve()}
+      />,
+    );
+    expect(buttons()).toEqual(["Allow once", "Allow for session", "Deny"]);
+    expect(screen.getByText("Write(a.ts)")).toBeTruthy();
+    expect(screen.getByText("/repo/a.ts")).toBeTruthy();
+  });
+
+  it("submits the decision the operator picked", async () => {
+    const onDecide = vi.fn().mockResolvedValue(undefined);
+    render(<ApprovalView request={{ options: ALL_OPTIONS }} pending onDecide={onDecide} />);
+    fireEvent.click(screen.getByText("Deny"));
+    await waitFor(() => expect(onDecide).toHaveBeenCalledWith("deny"));
+  });
+
+  it("disables every button once one is pressed, so a decision is sent once", () => {
+    render(<ApprovalView request={{ options: ALL_OPTIONS }} pending onDecide={() => new Promise(() => {})} />);
+    fireEvent.click(screen.getByText("Allow once"));
+    const all = [...document.querySelectorAll<HTMLButtonElement>(".st-approval-acts button")];
+    expect(all.every((b) => b.disabled)).toBe(true);
+  });
+
+  it("restores the controls when the decision failed and this approval is still pending", async () => {
+    const onDecide = vi.fn().mockRejectedValue(new Error("nope"));
+    render(<ApprovalView request={{ options: ALL_OPTIONS }} pending onDecide={onDecide} />);
+    fireEvent.click(screen.getByText("Allow once"));
+    await waitFor(() => {
+      const all = [...document.querySelectorAll<HTMLButtonElement>(".st-approval-acts button")];
+      expect(all.every((b) => !b.disabled)).toBe(true);
+    });
+  });
+
+  it("offers no button for a decision the request cannot back", () => {
+    render(
+      <ApprovalView
+        request={{ options: [{ optionId: "a1", name: "Allow once", kind: "allow_once" }] }}
+        pending
+        onDecide={() => Promise.resolve()}
+      />,
+    );
+    expect(buttons()).toEqual(["Allow once"]);
+  });
+
+  it("says so when the request offers no decision at all", () => {
+    render(<ApprovalView request={{ options: [] }} pending onDecide={() => Promise.resolve()} />);
+    expect(screen.getByText("no decision offered")).toBeTruthy();
+  });
+
+  it("renders a resolved approval as a one-liner, with no controls", () => {
+    render(
+      <ApprovalView
+        request={{ toolCall: { title: "Write(a.ts)" }, options: ALL_OPTIONS }}
+        pending={false}
+        onDecide={() => Promise.resolve()}
+      />,
+    );
+    expect(screen.getByText("Write(a.ts) — approved")).toBeTruthy();
+    expect(document.querySelector(".st-approval-acts")).toBeNull();
+  });
+});

web/src/components/structured/ApprovalView.tsx

@@ -0,0 +1,80 @@
+// An `Approval` row. The daemon exposes exactly three decisions
+// (docs/STRUCTURED-VIEW.md) and mints the nonce; this only solicits one of
+// them. A decision the request offers no matching ACP option for is not shown
+// — its button would "allow" something that silently resolves `Cancelled`.
+
+import { useState } from "react";
+
+import type { AcpPermissionOption, AcpToolCallLike, StructuredApprovalDecision } from "../../types.js";
+import { offeredDecisions, toolKindLabel } from "./model.js";
+
+const SPECS: [StructuredApprovalDecision, string, string][] = [
+  ["allow_once", "Allow once", "primary"],
+  ["allow_for_session", "Allow for session", ""],
+  ["deny", "Deny", "deny"],
+];
+
+export interface ApprovalViewProps {
+  /** The `RequestPermissionRequest` the row carries — serialized without its
+   *  nonce, which never leaves the daemon's live wire. */
+  request: { toolCall?: AcpToolCallLike; options?: AcpPermissionOption[] };
+  /** Whether this is the one live approval. A restored/answered row is not. */
+  pending: boolean;
+  /** Resolves once the decision reached the daemon; rejects only while this
+   *  approval is still the pending one, so the buttons can come back. */
+  onDecide: (decision: StructuredApprovalDecision) => Promise<void>;
+}
+
+export function ApprovalView({ request, pending, onDecide }: ApprovalViewProps) {
+  const [busy, setBusy] = useState(false);
+  const toolCall = request.toolCall ?? {};
+  const what = toolCall.title ?? toolKindLabel(toolCall.kind);
+
+  // Resolved approvals render as a compact one-liner inside a tool group (or
+  // are dropped entirely when standalone — see model.ts's transcriptItems).
+  if (!pending) {
+    return <div className="st-row st-row-approval st-approval-compact">{`${what} — approved`}</div>;
+  }
+
+  const offered = offeredDecisions(request.options ?? []);
+  const path = toolCall.locations?.[0]?.path;
+
+  const decide = (decision: StructuredApprovalDecision) => {
+    setBusy(true);
+    onDecide(decision).catch(() => {
+      // Rejects only while this approval is still pending — restore the
+      // controls so the operator can retry. The error itself is surfaced by
+      // the pane's banner.
+      setBusy(false);
+    });
+  };
+
+  return (
+    <div className="st-row st-row-approval">
+      <div className="st-approval">
+        <div className="st-approval-title">
+          <span aria-hidden="true">⚠</span> permission requested
+        </div>
+        <div className="st-approval-what">{what}</div>
+        {path && <div className="st-approval-path">{path}</div>}
+        {offered.length > 0 ? (
+          <div className="st-approval-acts">
+            {SPECS.filter(([decision]) => offered.includes(decision)).map(([decision, label, cls]) => (
+              <button
+                key={decision}
+                type="button"
+                className={cls ? `act ${cls}` : "act"}
+                disabled={busy}
+                onClick={() => decide(decision)}
+              >
+                {label}
+              </button>
+            ))}
+          </div>
+        ) : (
+          <div className="st-approval-resolved">no decision offered</div>
+        )}
+      </div>
+    </div>
+  );
+}

web/src/components/structured/Composer.tsx

@@ -0,0 +1,391 @@
+// The composer: draft, attachments, `/` command autocomplete off the live
+// `available_commands_update` notices, the session-settings menu, and the
+// send/cancel pair. Sending is the pane's job — this only hands it a draft and
+// the files that go with it.
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type ClipboardEvent,
+  type DragEvent,
+  type FormEvent,
+  type KeyboardEvent,
+} from "react";
+
+import type { AcpSessionConfigChoice, AcpSessionConfigOption } from "../../types.js";
+import {
+  applyCommand,
+  commandTokenAt,
+  filterCommands,
+  orderConfigOptions,
+  type AvailableCommand,
+} from "./model.js";
+
+/** Per-message ceilings the daemon enforces on uploads
+ *  (docs/STRUCTURED-VIEW.md, "Prompt and cancel"). */
+export const MAX_ATTACHMENTS = 10;
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+/** Pasted text at or above either bound becomes a `.txt` attachment instead of
+ *  going inline. */
+const PASTE_TO_FILE_CHARS = 4_000;
+const PASTE_TO_FILE_LINES = 40;
+
+export interface ComposerProps {
+  /** Files chosen but not yet sent. Owned by the pane so a failed send can put
+   *  them back. */
+  attachments: File[];
+  onAttachmentsChange(files: File[]): void;
+  commands: AvailableCommand[];
+  configOptions: AcpSessionConfigOption[];
+  /** A turn is in flight — the cancel control replaces nothing, it appears
+   *  beside send (a queued message is still allowed). */
+  turnActive: boolean;
+  /** An upload/POST is in flight: the attachment controls are frozen. */
+  uploading: boolean;
+  configBusy: boolean;
+  /** Restored into the box when a send fails. */
+  draft: string;
+  onDraftChange(draft: string): void;
+  onSubmit(text: string, attachments: File[]): void;
+  onCancel(): void;
+  onConfigChange(option: AcpSessionConfigOption, value: string | boolean): void;
+  onError(message: string): void;
+  menuId: string;
+}
+
+function configChoices(option: AcpSessionConfigOption): AcpSessionConfigChoice[] {
+  return (option.options ?? []).flatMap((choice) => ("options" in choice ? choice.options : [choice]));
+}
+
+function currentConfigLabel(option: AcpSessionConfigOption): string {
+  if (typeof option.currentValue === "boolean") return option.currentValue ? "On" : "Off";
+  return configChoices(option).find((choice) => choice.value === option.currentValue)?.name
+    ?? String(option.currentValue);
+}
+
+export function Composer({
+  attachments,
+  onAttachmentsChange,
+  commands,
+  configOptions,
+  turnActive,
+  uploading,
+  configBusy,
+  draft,
+  onDraftChange,
+  onSubmit,
+  onCancel,
+  onConfigChange,
+  onError,
+  menuId,
+}: ComposerProps) {
+  const inputRef = useRef<HTMLTextAreaElement | null>(null);
+  const fileRef = useRef<HTMLInputElement | null>(null);
+  const configRef = useRef<HTMLDivElement | null>(null);
+  const [caret, setCaret] = useState(0);
+  const [activeCommand, setActiveCommand] = useState(0);
+  const [configOpen, setConfigOpen] = useState(false);
+  /** Escape closes the menu until the draft or caret moves again. */
+  const [menuDismissed, setMenuDismissed] = useState(false);
+  const pasteCount = useRef(0);
+
+  // Grow with the draft, up to the CSS max-height; past that it scrolls.
+  useLayoutEffect(() => {
+    const input = inputRef.current;
+    if (!input) return;
+    input.style.height = "auto";
+    input.style.overflowY = "hidden";
+    input.style.height = `${Math.min(input.scrollHeight, 160)}px`;
+    if (input.scrollHeight > 160) input.style.overflowY = "auto";
+  }, [draft]);
+
+  useEffect(() => {
+    if (!configOpen) return;
+    const onPointerDown = (event: PointerEvent) => {
+      if (!configRef.current?.contains(event.target as Node)) setConfigOpen(false);
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [configOpen]);
+
+  const token = commandTokenAt(draft, caret, caret);
+  const matches = token && commands.length > 0 ? filterCommands(commands, token.query) : [];
+  const menuOpen = matches.length > 0 && !menuDismissed;
+  const activeIndex = menuOpen ? Math.min(Math.max(activeCommand, 0), matches.length - 1) : -1;
+
+  const addFiles = useCallback(
+    (files: File[]) => {
+      if (uploading) return;
+      const next = [...attachments];
+      for (const file of files) {
+        if (file.size > MAX_ATTACHMENT_BYTES) {
+          onError(`${file.name} exceeds 20 MiB. Choose a smaller file.`);
+        } else if (next.length >= MAX_ATTACHMENTS) {
+          onError(`Attach up to ${MAX_ATTACHMENTS} files per message.`);
+        } else {
+          next.push(file);
+        }
+      }
+      onAttachmentsChange(next);
+    },
+    [attachments, onAttachmentsChange, onError, uploading],
+  );
+
+  const syncCaret = () => {
+    setMenuDismissed(false);
+    setCaret(inputRef.current?.selectionStart ?? 0);
+  };
+
+  const chooseCommand = (command: AvailableCommand) => {
+    const input = inputRef.current;
+    if (!input) return;
+    const current = commandTokenAt(draft, input.selectionStart, input.selectionEnd);
+    if (!current) return;
+    const applied = applyCommand(draft, current, command.name);
+    onDraftChange(applied.value);
+    setActiveCommand(0);
+    // The caret has to move after React has written the new value.
+    requestAnimationFrame(() => {
+      input.focus();
+      input.setSelectionRange(applied.cursor, applied.cursor);
+      setCaret(applied.cursor);
+    });
+  };
+
+  const submit = () => {
+    if ((!draft.trim() && attachments.length === 0) || uploading) return;
+    onSubmit(draft, attachments);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (menuOpen) {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        const direction = event.key === "ArrowDown" ? 1 : -1;
+        setActiveCommand((index) => (index + direction + matches.length) % matches.length);
+        return;
+      }
+      if ((event.key === "Enter" && !event.shiftKey) || event.key === "Tab") {
+        event.preventDefault();
+        chooseCommand(matches[activeIndex]);
+        return;
+      }
+      if (event.key === "Escape") {
+        event.preventDefault();
+        setMenuDismissed(true);
+        return;
+      }
+    }
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  };
+
+  const onPaste = (event: ClipboardEvent<HTMLTextAreaElement>) => {
+    const clipboard = event.clipboardData;
+    if (!clipboard || uploading) return;
+    if (clipboard.files.length) {
+      event.preventDefault();
+      addFiles(Array.from(clipboard.files));
+      return;
+    }
+    const text = clipboard.getData("text/plain");
+    if (text.length < PASTE_TO_FILE_CHARS && text.split("\n").length < PASTE_TO_FILE_LINES) return;
+    // No slot for it, or too big to upload: leave it inline rather than
+    // dropping it on the floor.
+    if (attachments.length >= MAX_ATTACHMENTS || new Blob([text]).size > MAX_ATTACHMENT_BYTES) return;
+    event.preventDefault();
+    addFiles([new File([text], `pasted-${++pasteCount.current}.txt`, { type: "text/plain" })]);
+  };
+
+  const ordered = orderConfigOptions(configOptions);
+  const summary = ordered.map((option) => `${option.name}: ${currentConfigLabel(option)}`).join("\n");
+
+  return (
+    <form
+      className="structured-composer"
+      onSubmit={(event: FormEvent) => {
+        event.preventDefault();
+        submit();
+      }}
+      onDragOver={(event: DragEvent) => {
+        if (event.dataTransfer?.types.includes("Files")) event.preventDefault();
+      }}
+      onDrop={(event: DragEvent) => {
+        if (!event.dataTransfer?.files.length) return;
+        event.preventDefault();
+        addFiles(Array.from(event.dataTransfer.files));
+      }}
+    >
+      <button
+        type="button"
+        className="structured-attach"
+        aria-label="Attach files"
+        title="Attach files (up to 20 MiB each)"
+        disabled={uploading}
+        onClick={() => fileRef.current?.click()}
+      >
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" aria-hidden="true">
+          <path d="m8 12 7-7a3 3 0 0 1 4 4L9 19a5 5 0 0 1-7-7L12 2M5 14l9-9" />
+        </svg>
+      </button>
+      <input
+        ref={fileRef}
+        className="structured-file-input"
+        type="file"
+        multiple
+        hidden
+        disabled={uploading}
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          addFiles(Array.from(event.target.files ?? []));
+          event.target.value = "";
+        }}
+      />
+      <div className="structured-input-wrap">
+        <div className="structured-attachments" aria-label="Attachments" aria-live="polite" hidden={attachments.length === 0}>
+          {attachments.map((file, index) => (
+            <span key={`${file.name}-${index}`} className="structured-attachment">
+              <span title={`${file.name} (${file.size.toLocaleString()} bytes)`}>{file.name}</span>
+              <button
+                type="button"
+                aria-label={`Remove ${file.name}`}
+                disabled={uploading}
+                onClick={() => onAttachmentsChange(attachments.filter((_, i) => i !== index))}
+              >
+                ×
+              </button>
+            </span>
+          ))}
+        </div>
+        <div id={menuId} className="structured-command-menu" role="listbox" hidden={!menuOpen}>
+          {matches.map((command, index) => (
+            <div
+              key={command.name}
+              id={`${menuId}-option-${index}`}
+              className="structured-command-option"
+              role="option"
+              aria-selected={index === activeIndex}
+              onPointerDown={(event) => event.preventDefault()}
+              onClick={() => chooseCommand(command)}
+            >
+              <div className="structured-command-title">
+                <span className="structured-command-name">{`/${command.name}`}</span>
+                <span className="structured-command-hint">{command.input?.hint ?? ""}</span>
+              </div>
+              <div className="structured-command-description">
+                {command.description.replace(/\s+/g, " ").trim()}
+              </div>
+            </div>
+          ))}
+        </div>
+        <textarea
+          ref={inputRef}
+          className="structured-input"
+          rows={1}
+          placeholder="Reply, or / for commands…"
+          autoComplete="off"
+          aria-autocomplete="list"
+          aria-expanded={menuOpen}
+          aria-controls={menuId}
+          aria-activedescendant={activeIndex >= 0 ? `${menuId}-option-${activeIndex}` : undefined}
+          value={draft}
+          onChange={(event) => {
+            onDraftChange(event.target.value);
+            setActiveCommand(0);
+            setMenuDismissed(false);
+            setCaret(event.target.selectionStart ?? event.target.value.length);
+          }}
+          onClick={syncCaret}
+          onSelect={syncCaret}
+          onKeyUp={(event) => {
+            if (["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) syncCaret();
+          }}
+          onKeyDown={onKeyDown}
+          onPaste={onPaste}
+        />
+      </div>
+      <div className="structured-config" ref={configRef} hidden={ordered.length === 0}>
+        <button
+          type="button"
+          className="structured-config-trigger"
+          aria-haspopup="true"
+          aria-expanded={configOpen}
+          aria-label={`Session settings. ${summary.replaceAll("\n", ". ")}`}
+          title={summary}
+          disabled={configBusy}
+          onClick={() => setConfigOpen((open) => !open)}
+        >
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M4 7h10M18 7h2M4 17h2M10 17h10M14 4v6M6 14v6" />
+          </svg>
+        </button>
+        <div
+          className="structured-config-menu"
+          role="group"
+          aria-label="Session settings"
+          hidden={!configOpen}
+          onKeyDown={(event) => {
+            if (event.key !== "Escape") return;
+            setConfigOpen(false);
+            configRef.current?.querySelector<HTMLButtonElement>(".structured-config-trigger")?.focus();
+          }}
+        >
+          {ordered.map((option) => (
+            <label key={option.id} className="structured-config-row" title={option.description ?? undefined}>
+              <span className="structured-config-name">{option.name}</span>
+              {option.type === "select" ? (
+                <select
+                  className="structured-config-select"
+                  disabled={configBusy}
+                  value={String(option.currentValue)}
+                  onChange={(event) => onConfigChange(option, event.target.value)}
+                >
+                  {configChoices(option).map((choice) => (
+                    <option key={choice.value} value={choice.value} title={choice.description ?? ""}>
+                      {choice.name}
+                    </option>
+                  ))}
+                </select>
+              ) : option.type === "boolean" ? (
+                <input
+                  type="checkbox"
+                  className="structured-config-toggle"
+                  disabled={configBusy}
+                  checked={option.currentValue === true}
+                  onChange={(event) => onConfigChange(option, event.target.checked)}
+                />
+              ) : null}
+            </label>
+          ))}
+        </div>
+      </div>
+      <button type="submit" className="structured-send">
+        <span>Send</span>
+        <svg viewBox="0 0 20 20" aria-hidden="true">
+          <path d="m7 5 5 5-5 5M12 10H3" />
+        </svg>
+      </button>
+      {turnActive && (
+        <button
+          type="button"
+          className="structured-cancel"
+          aria-label="Cancel turn"
+          title="Cancel turn"
+          onClick={onCancel}
+        >
+          <svg className="structured-cancel-spinner" viewBox="0 0 24 24" aria-hidden="true">
+            <circle cx="12" cy="12" r="10" fill="none" stroke="currentColor" strokeWidth="2" strokeDasharray="50 14" strokeLinecap="round" />
+          </svg>
+          <svg className="structured-cancel-stop" viewBox="0 0 24 24" aria-hidden="true">
+            <rect x="6" y="6" width="12" height="12" rx="2" fill="currentColor" />
+          </svg>
+        </button>
+      )}
+    </form>
+  );
+}

web/src/components/structured/Copyable.tsx

@@ -0,0 +1,101 @@
+// docs/STRUCTURED-VIEW.md: the web client's user, agent, thought, tool-detail
+// and notice text blocks copy their complete source text when clicked or
+// keyboard-activated. The visible node is whatever it wraps; this only adds
+// the affordance and the "copied"/"error" state the CSS reads.
+
+import { useCallback, useEffect, useRef, useState, type ElementType, type ReactNode } from "react";
+
+async function writeClipboard(text: string): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return;
+  } catch {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.style.position = "fixed";
+    textarea.style.opacity = "0";
+    document.body.appendChild(textarea);
+    textarea.select();
+    const copied = document.execCommand?.("copy") ?? false;
+    textarea.remove();
+    if (!copied) throw new Error("clipboard unavailable");
+  }
+}
+
+export interface CopyableProps {
+  /** The complete source text — not whatever the DOM happens to show. */
+  text: string;
+  /** Names the thing in the "Copy …" label ("message", "diff", "path", …). */
+  label: string;
+  as?: ElementType;
+  className?: string;
+  title?: string;
+  children?: ReactNode;
+  /** Extra attributes the row builders set (`data-row-id`, `lang`, …). */
+  [key: string]: unknown;
+}
+
+/** Wrapping a node in a copy affordance. Empty `text` renders the node plain —
+ *  a control that copies nothing is worse than no control. */
+export function Copyable({
+  text,
+  label,
+  as: Tag = "div",
+  className,
+  children,
+  ...rest
+}: CopyableProps) {
+  const [copyState, setCopyState] = useState<"copied" | "error" | null>(null);
+  const timer = useRef<number | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current !== null) window.clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(() => {
+    void writeClipboard(text).then(
+      () => {
+        setCopyState("copied");
+        if (timer.current !== null) window.clearTimeout(timer.current);
+        timer.current = window.setTimeout(() => setCopyState(null), 1200);
+      },
+      () => setCopyState("error"),
+    );
+  }, [text]);
+
+  if (!text) {
+    return (
+      <Tag className={className} {...rest}>
+        {children}
+      </Tag>
+    );
+  }
+
+  const ariaLabel = copyState === "copied" ? `${label} copied` : `Copy ${label}`;
+  return (
+    <Tag
+      className={className ? `${className} st-copyable` : "st-copyable"}
+      tabIndex={0}
+      role="button"
+      aria-label={ariaLabel}
+      title={`Copy ${label}`}
+      data-copy-state={copyState ?? undefined}
+      onClick={(event: React.MouseEvent) => {
+        // A link inside the block is a link, not a copy target.
+        if ((event.target as Element | null)?.closest("a")) return;
+        copy();
+      }}
+      onKeyDown={(event: React.KeyboardEvent) => {
+        if (event.key !== "Enter" && event.key !== " ") return;
+        event.preventDefault();
+        copy();
+      }}
+      {...rest}
+    >
+      {children}
+    </Tag>
+  );
+}

web/src/components/structured/DiffView.test.tsx

@@ -0,0 +1,50 @@
+// @vitest-environment happy-dom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { DiffView } from "./DiffView.js";
+import { toolDiffMeta } from "./model.js";
+
+afterEach(cleanup);
+
+function lines(kind: string): string[] {
+  return [...document.querySelectorAll(`.st-ln-${kind}`)].map((el) => el.textContent ?? "");
+}
+
+describe("DiffView", () => {
+  it("marks insertions and deletions with their column prefixes", () => {
+    render(<DiffView diff={{ path: "src/a.ts", oldText: "one\ntwo\n", newText: "one\nTWO\nthree\n" }} />);
+    expect(lines("del")).toEqual(["- two"]);
+    expect(lines("add")).toEqual(["+ TWO", "+ three"]);
+    expect(lines("ctx")).toEqual(["  one"]);
+    expect(screen.getByText("src/a.ts")).toBeTruthy();
+  });
+
+  it("carries the +added −removed counts the tool head shows", () => {
+    render(<DiffView diff={{ path: "a.ts", oldText: "one\ntwo\n", newText: "one\nTWO\nthree\n" }} />);
+    const body = document.querySelector<HTMLElement>(".st-diff")!;
+    expect(body.dataset.added).toBe("2");
+    expect(body.dataset.removed).toBe("1");
+    expect(toolDiffMeta([{ type: "diff", path: "a.ts", oldText: "one\ntwo\n", newText: "one\nTWO\nthree\n" }]))
+      .toBe("+2 −1");
+  });
+
+  it("renders every line of a new file as added", () => {
+    render(<DiffView diff={{ path: "new.ts", newText: "alpha\nbeta\n" }} />);
+    expect(lines("add")).toEqual(["+ alpha", "+ beta"]);
+    expect(lines("del")).toEqual([]);
+  });
+
+  it("collapses a long unchanged run to a hunk summary", () => {
+    const filler = Array.from({ length: 20 }, (_, i) => `line ${i}`).join("\n");
+    render(<DiffView diff={{ path: "a.ts", oldText: `head\n${filler}\n`, newText: `HEAD\n${filler}\n` }} />);
+    expect(lines("hunk")).toEqual(["⋯ 17 unchanged lines ⋯"]);
+  });
+
+  it("copies the whole diff, prefixes included", () => {
+    render(<DiffView diff={{ path: "a.ts", oldText: "one\n", newText: "two\n" }} />);
+    const body = document.querySelector<HTMLElement>(".st-diff")!;
+    expect(body.getAttribute("aria-label")).toBe("Copy diff");
+    expect(body.textContent).toBe("- one+ two");
+  });
+});

web/src/components/structured/DiffView.tsx

@@ -0,0 +1,56 @@
+// A `Diff` content block, rendered as coloured hunks. ACP hands over whole
+// `oldText`/`newText`, so the lines and their `+added −removed` counts are
+// computed here (structuredDiff.ts) rather than parsed out of a patch.
+
+import { useMemo } from "react";
+
+import { computeDiffLines, diffStats, type DiffLine } from "../../structuredDiff.js";
+import type { AcpDiff } from "../../types.js";
+import { Copyable } from "./Copyable.js";
+
+/** Column prefix by line kind. A `hunk` summary and an `eof` marker are their
+ *  own complete text, so neither takes one. */
+const PREFIX: Record<DiffLine["kind"], string> = {
+  add: "+ ",
+  del: "- ",
+  ctx: "  ",
+  hunk: "",
+  eof: "",
+};
+
+export function diffLineText(line: DiffLine): string {
+  return PREFIX[line.kind] + line.text;
+}
+
+export interface DiffViewProps {
+  diff: AcpDiff;
+}
+
+export function DiffView({ diff }: DiffViewProps) {
+  const lines = useMemo(() => computeDiffLines(diff.oldText, diff.newText), [diff.oldText, diff.newText]);
+  const stats = useMemo(() => diffStats(lines), [lines]);
+  const plain = useMemo(() => lines.map(diffLineText).join("\n"), [lines]);
+
+  return (
+    <div className="st-diff-block">
+      <Copyable className="st-diff-path" text={diff.path} label="path" title={diff.path}>
+        {diff.path}
+      </Copyable>
+      <Copyable
+        className="st-diff"
+        text={plain}
+        label="diff"
+        data-added={stats.added}
+        data-removed={stats.removed}
+      >
+        <pre>
+          {lines.map((line, index) => (
+            <span key={index} className={`st-ln st-ln-${line.kind}`}>
+              {diffLineText(line)}
+            </span>
+          ))}
+        </pre>
+      </Copyable>
+    </div>
+  );
+}

web/src/components/structured/StructuredPane.test.tsx

@@ -0,0 +1,403 @@
+// @vitest-environment happy-dom
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../api.js", async () => {
+  const actual = await vi.importActual<typeof import("../../api.js")>("../../api.js");
+  return {
+    ...actual,
+    sendStructuredPrompt: vi.fn().mockResolvedValue(undefined),
+    uploadStructuredFile: vi.fn().mockResolvedValue({ path: "/uploads/pasted.txt" }),
+    cancelStructuredTurn: vi.fn().mockResolvedValue(undefined),
+    resolveStructuredApproval: vi.fn().mockResolvedValue(undefined),
+    setStructuredConfig: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+import {
+  cancelStructuredTurn,
+  resolveStructuredApproval,
+  sendStructuredPrompt,
+  uploadStructuredFile,
+} from "../../api.js";
+import { INITIAL_RECONNECT_MS } from "../../reconnect.js";
+import type { ReducedState, StructuredEvent, TranscriptRow } from "../../types.js";
+import { StructuredPane } from "./StructuredPane.js";
+
+/** Just enough of a WebSocket for the pane to drive (mirrors structured.test.ts's
+ *  own fake, which the pre-React connection used). */
+class FakeSocket {
+  onopen: (() => void) | null = null;
+  onmessage: ((ev: { data: string }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null = null;
+  closed = false;
+
+  open(): void {
+    act(() => this.onopen?.());
+  }
+  emit(event: StructuredEvent): void {
+    act(() => this.onmessage?.({ data: JSON.stringify(event) }));
+  }
+  drop(code = 1006, reason = ""): void {
+    act(() => this.onclose?.({ code, reason }));
+  }
+  close(): void {
+    this.closed = true;
+  }
+}
+
+const idle: ReducedState = { turn: { responding: false, thinking: false, active_tool_calls: [] } };
+const busy: ReducedState = { turn: { responding: true, thinking: false, active_tool_calls: [] } };
+
+function row(id: string, kind: TranscriptRow["kind"], data: unknown = {}): TranscriptRow {
+  return { id, kind, data };
+}
+
+function chunk(id: string, kind: "user" | "agent_text" | "agent_thought", text: string): TranscriptRow {
+  return row(id, kind, { content: { type: "text", text } });
+}
+
+const APPROVAL_REQUEST = {
+  toolCall: { title: "Write(secrets.txt)", kind: "edit", locations: [{ path: "/repo/secrets.txt" }] },
+  options: [
+    { optionId: "a1", name: "Allow once", kind: "allow_once" },
+    { optionId: "a2", name: "Allow always", kind: "allow_always" },
+    { optionId: "r1", name: "Reject", kind: "reject_once" },
+  ],
+};
+
+function mount(): { socket: FakeSocket; sockets: FakeSocket[] } {
+  const sockets: FakeSocket[] = [];
+  render(
+    <StructuredPane
+      sessionId="s1"
+      socketFactory={() => {
+        const socket = new FakeSocket();
+        sockets.push(socket);
+        return socket as unknown as WebSocket;
+      }}
+    />,
+  );
+  sockets[0].open();
+  return { socket: sockets[0], sockets };
+}
+
+function snapshot(socket: FakeSocket, rows: TranscriptRow[], state: ReducedState = idle): void {
+  socket.emit({ type: "transcript_snapshot", snapshot: { cursor: rows.length, rows } });
+  socket.emit({ type: "reduced_state", state });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("the eight row kinds", () => {
+  it("renders user, agent, thought, tool, diff, approval and notice rows; never a plan", () => {
+    const { socket } = mount();
+    snapshot(
+      socket,
+      [
+        chunk("user:1", "user", "please edit it"),
+        chunk("agent:1", "agent_text", "**bold** answer"),
+        chunk("thought:1", "agent_thought", "considering"),
+        row("tool:1", "tool_call", { title: "Read(src/main.ts)", kind: "read", status: "completed" }),
+        row("tool:2", "tool_diff", {
+          title: "Edit(a.ts)",
+          kind: "edit",
+          status: "completed",
+          content: [{ type: "diff", path: "a.ts", oldText: "one\n", newText: "one\ntwo\n" }],
+        }),
+        row("approval:1", "approval", APPROVAL_REQUEST),
+        row("plan", "plan", { entries: [{ content: "step", priority: "high", status: "pending" }] }),
+        row("notice:1", "notice", { sessionUpdate: "mystery_update" }),
+      ],
+      { ...idle, pending_approval: { nonce: "nonce-1", request: APPROVAL_REQUEST as never } },
+    );
+
+    expect(screen.getByText("please edit it")).toBeTruthy();
+    expect(document.querySelector(".st-row-agent strong")?.textContent).toBe("bold");
+    expect(document.querySelector(".st-row-thought")?.textContent).toContain("considering");
+    expect(screen.getByText("src/main.ts")).toBeTruthy();
+    // The diff row's head carries the line counts, not a fabricated duration.
+    expect(document.querySelector('[data-row-id="tool:2"] .st-tool-meta')?.textContent).toBe("+1 −0");
+    expect(screen.getByText("permission requested")).toBeTruthy();
+    expect(screen.getByText("[notice]")).toBeTruthy();
+    expect(document.querySelector('[data-row-id="plan"]')).toBeNull();
+  });
+
+  it("omits the state-only notices it consumes for `/` autocomplete", () => {
+    const { socket } = mount();
+    snapshot(socket, [
+      row("notice:1", "notice", {
+        sessionUpdate: "available_commands_update",
+        availableCommands: [{ name: "compact", description: "Compact the conversation" }],
+      }),
+      row("notice:2", "notice", { sessionUpdate: "session_info_update" }),
+    ]);
+    expect(screen.queryByText("[notice]")).toBeNull();
+
+    // …and offers them in the composer instead.
+    const input = document.querySelector<HTMLTextAreaElement>(".structured-input")!;
+    fireEvent.change(input, { target: { value: "/comp" } });
+    expect(screen.getByText("/compact")).toBeTruthy();
+  });
+
+  it("renders a completed turn's footer inline, and retires it once the next turn starts", () => {
+    const { socket } = mount();
+    const footer = row("turn_meta:1", "notice", {
+      maestroTurnMeta: { elapsedMs: 65_000, outcome: "completed", model: "sonnet", contextDelta: 1200 },
+    });
+    snapshot(socket, [chunk("user:1", "user", "go"), footer]);
+    expect(screen.getByText("1m 5s · +1.2k context tokens · sonnet")).toBeTruthy();
+
+    socket.emit({
+      type: "projection_update",
+      transcript: { type: "append", row: chunk("user:2", "user", "again") },
+      state: idle,
+    });
+    expect(screen.queryByText(/1m 5s/)).toBeNull();
+  });
+});
+
+describe("tool rows and activity groups", () => {
+  it("collapses two or more tools in a turn into one group, opened on click", () => {
+    const { socket } = mount();
+    snapshot(socket, [
+      chunk("user:1", "user", "go"),
+      row("tool:1", "tool_call", { title: "Read(a.ts)", kind: "read", status: "completed" }),
+      chunk("agent:1", "agent_text", "still working"),
+      row("tool:2", "tool_call", { title: "Read(b.ts)", kind: "read", status: "completed" }),
+      chunk("agent:2", "agent_text", "the answer"),
+    ]);
+
+    const head = screen.getByText("2 tool calls").closest("button")!;
+    expect(head.getAttribute("aria-expanded")).toBe("false");
+    // The final answer stays outside the group; the intermediate text is in it.
+    expect(document.querySelector(".st-tool-group")!.contains(screen.getByText("the answer"))).toBe(false);
+    expect(document.querySelector(".st-tool-group")!.contains(screen.getByText("still working"))).toBe(true);
+
+    fireEvent.click(head);
+    expect(head.getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("discloses a tool's output only once its head is opened", () => {
+    const { socket } = mount();
+    snapshot(socket, [
+      row("tool:1", "tool_call", {
+        title: "Execute(ls)",
+        kind: "execute",
+        status: "completed",
+        content: [{ type: "content", content: { type: "text", text: "a.ts\nb.ts" } }],
+        rawInput: { command: "ls" },
+        rawOutput: { exit_code: 0 },
+      }),
+    ]);
+    expect(document.querySelector(".st-tool-text")).toBeNull();
+
+    fireEvent.click(document.querySelector<HTMLButtonElement>(".st-tool-head")!);
+    expect(document.querySelector(".st-tool-text")?.textContent).toBe("a.ts\nb.ts");
+    expect(screen.getByText("Exit code")).toBeTruthy();
+    expect(document.querySelector(".st-tool-exit-ok")?.textContent).toBe("0");
+  });
+
+  it("patches a tool row in place rather than appending a second one", () => {
+    const { socket } = mount();
+    snapshot(socket, [row("tool:1", "tool_call", { title: "Read(a.ts)", kind: "read", status: "in_progress" })]);
+    expect(document.querySelector(".st-tool-meta")?.textContent).toBe("running");
+
+    socket.emit({
+      type: "projection_update",
+      transcript: {
+        type: "patch",
+        row: row("tool:1", "tool_call", { title: "Read(a.ts)", kind: "read", status: "completed" }),
+      },
+      state: idle,
+    });
+    expect(document.querySelectorAll('[data-row-id="tool:1"]')).toHaveLength(1);
+    expect(document.querySelector(".st-tool-meta")).toBeNull();
+  });
+});
+
+describe("approvals", () => {
+  it("answers with the live nonce, offering only the decisions the request backs", async () => {
+    const { socket } = mount();
+    snapshot(socket, [row("approval:1", "approval", APPROVAL_REQUEST)], {
+      ...idle,
+      pending_approval: { nonce: "nonce-1", request: APPROVAL_REQUEST as never },
+    });
+
+    expect(screen.getByText("/repo/secrets.txt")).toBeTruthy();
+    fireEvent.click(screen.getByText("Allow for session"));
+    await waitFor(() =>
+      expect(resolveStructuredApproval).toHaveBeenCalledWith("s1", "nonce-1", "allow_for_session"),
+    );
+  });
+
+  it("hides a decision the request offers no ACP option for", () => {
+    const { socket } = mount();
+    const request = { toolCall: { title: "Read(a.ts)" }, options: [{ optionId: "r", name: "No", kind: "reject_once" }] };
+    snapshot(socket, [row("approval:1", "approval", request)], {
+      ...idle,
+      pending_approval: { nonce: "nonce-2", request: request as never },
+    });
+    expect(screen.getByText("Deny")).toBeTruthy();
+    expect(screen.queryByText("Allow once")).toBeNull();
+  });
+
+  it("treats only the newest approval as pending, and hides resolved standalone ones", () => {
+    const { socket } = mount();
+    snapshot(
+      socket,
+      [row("approval:1", "approval", APPROVAL_REQUEST), row("approval:2", "approval", APPROVAL_REQUEST)],
+      { ...idle, pending_approval: { nonce: "nonce-3", request: APPROVAL_REQUEST as never } },
+    );
+    expect(screen.getAllByText("permission requested")).toHaveLength(1);
+    expect(screen.queryByText(/approved/)).toBeNull();
+  });
+
+  it("drops the controls once the approval is no longer pending", () => {
+    const { socket } = mount();
+    snapshot(socket, [row("approval:1", "approval", APPROVAL_REQUEST)], {
+      ...idle,
+      pending_approval: { nonce: "nonce-4", request: APPROVAL_REQUEST as never },
+    });
+    expect(screen.getByText("Allow once")).toBeTruthy();
+
+    socket.emit({ type: "reduced_state", state: idle });
+    expect(screen.queryByText("Allow once")).toBeNull();
+  });
+});
+
+describe("prompt and cancel", () => {
+  it("sends a draft, clearing the composer", async () => {
+    const { socket } = mount();
+    snapshot(socket, []);
+    const input = document.querySelector<HTMLTextAreaElement>(".structured-input")!;
+    fireEvent.change(input, { target: { value: "do the thing" } });
+    fireEvent.submit(document.querySelector("form.structured-composer")!);
+
+    await waitFor(() => expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "do the thing"));
+    expect(input.value).toBe("");
+  });
+
+  it("uploads attachments and names them in the prompt", async () => {
+    const { socket } = mount();
+    snapshot(socket, []);
+    const file = new File(["hello"], "notes.txt", { type: "text/plain" });
+    fireEvent.change(document.querySelector<HTMLInputElement>(".structured-file-input")!, {
+      target: { files: [file] },
+    });
+    expect(screen.getByText("notes.txt")).toBeTruthy();
+
+    fireEvent.change(document.querySelector<HTMLTextAreaElement>(".structured-input")!, {
+      target: { value: "read this" },
+    });
+    fireEvent.submit(document.querySelector("form.structured-composer")!);
+
+    await waitFor(() => expect(uploadStructuredFile).toHaveBeenCalled());
+    await waitFor(() =>
+      expect(sendStructuredPrompt).toHaveBeenCalledWith(
+        "s1",
+        'read this\n\nAttached file "notes.txt": "/uploads/pasted.txt"',
+      ),
+    );
+  });
+
+  it("queues a second message while a turn is in flight, and sends it when the turn ends", async () => {
+    const { socket } = mount();
+    snapshot(socket, [], busy);
+    fireEvent.change(document.querySelector<HTMLTextAreaElement>(".structured-input")!, {
+      target: { value: "next up" },
+    });
+    fireEvent.submit(document.querySelector("form.structured-composer")!);
+
+    expect(sendStructuredPrompt).not.toHaveBeenCalled();
+    expect(document.querySelector(".st-row-queued")?.textContent).toBe("next up");
+
+    socket.emit({ type: "reduced_state", state: idle });
+    await waitFor(() => expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "next up"));
+  });
+
+  it("hands a failed send's draft back to the operator", async () => {
+    vi.mocked(sendStructuredPrompt).mockRejectedValueOnce(new Error("boom"));
+    const { socket } = mount();
+    snapshot(socket, []);
+    const input = document.querySelector<HTMLTextAreaElement>(".structured-input")!;
+    fireEvent.change(input, { target: { value: "keep me" } });
+    fireEvent.submit(document.querySelector("form.structured-composer")!);
+
+    await waitFor(() => expect(document.querySelector(".structured-error")?.textContent).toContain("boom"));
+    expect(input.value).toBe("keep me");
+  });
+
+  it("shows the cancel control only while a turn is live", () => {
+    const { socket } = mount();
+    snapshot(socket, []);
+    expect(document.querySelector(".structured-cancel")).toBeNull();
+
+    socket.emit({ type: "reduced_state", state: busy });
+    fireEvent.click(document.querySelector<HTMLButtonElement>(".structured-cancel")!);
+    expect(cancelStructuredTurn).toHaveBeenCalledWith("s1");
+  });
+
+  it("reports live turn activity above the composer", () => {
+    const { socket } = mount();
+    snapshot(socket, [], {
+      turn: {
+        responding: true,
+        thinking: false,
+        active_tool_calls: ["t1", "t2"],
+        started_at: new Date(Date.now() - 5_000).toISOString(),
+      },
+      usage: { used: 12_000, size: 200_000 },
+    });
+    const activity = document.querySelector<HTMLElement>(".structured-activity")!;
+    expect(activity.hidden).toBe(false);
+    expect(activity.textContent).toContain("Running 2 tools");
+    expect(activity.textContent).toContain("12k context / 200k context");
+  });
+});
+
+describe("the socket", () => {
+  it("replaces the transcript wholesale on every snapshot, never merging", async () => {
+    const { socket, sockets } = mount();
+    snapshot(socket, [chunk("user:1", "user", "first")]);
+    socket.drop(1006);
+
+    // The retry is on reconnect.ts's backoff schedule, not immediate.
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, INITIAL_RECONNECT_MS + 20));
+    });
+    const replacement = sockets[1];
+    expect(replacement).toBeDefined();
+    replacement.open();
+    snapshot(replacement, [chunk("user:2", "user", "second")]);
+    expect(screen.queryByText("first")).toBeNull();
+    expect(screen.getByText("second")).toBeTruthy();
+  });
+
+  it("reports a daemon rejection instead of retrying it", () => {
+    const status = vi.fn();
+    const sockets: FakeSocket[] = [];
+    render(
+      <StructuredPane
+        sessionId="s1"
+        onStatusChange={status}
+        socketFactory={() => {
+          const socket = new FakeSocket();
+          sockets.push(socket);
+          return socket as unknown as WebSocket;
+        }}
+      />,
+    );
+    sockets[0].open();
+    sockets[0].drop(4004, "not a structured session");
+    expect(sockets).toHaveLength(1);
+    expect(status).toHaveBeenCalledWith("error", "not a structured session");
+  });
+});

web/src/components/structured/StructuredPane.tsx

@@ -0,0 +1,400 @@
+// React port of structured.ts (#246): a live structured session — the
+// transcript from `WS /api/structured/:id`, the composer that drives
+// `.../prompt` and `.../cancel`, and the approval controls that answer
+// `.../approvals/:nonce`. docs/STRUCTURED-VIEW.md is the contract.
+//
+// Like TerminalPane, the pane draws the body only: pane chrome (title,
+// disconnect, sessions drawer) belongs to whatever composes it, which reads
+// the connection state through `onStatusChange`.
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import {
+  cancelStructuredTurn,
+  resolveStructuredApproval,
+  sendStructuredPrompt,
+  setStructuredConfig,
+  uploadStructuredFile,
+} from "../../api.js";
+import { formatContextTokens, formatElapsed } from "../../structuredRender.js";
+import type {
+  AcpSessionConfigOption,
+  StructuredApprovalDecision,
+  TranscriptRow as Row,
+  Uuid,
+} from "../../types.js";
+import { Composer } from "./Composer.js";
+import {
+  commandsFromTranscript,
+  pendingApprovalRowId as pendingApprovalRowIdOf,
+  transcriptItems,
+  turnIsActive,
+} from "./model.js";
+import { ToolGroup } from "./ToolGroup.js";
+import { TranscriptRow } from "./TranscriptRow.js";
+import { useStructuredSession, type StructuredStatus, type StructuredSocketFactory } from "./useStructuredSession.js";
+import "./structured.css";
+
+/** Within this much of the bottom, wheel and touch imprecision should still
+ *  count as following. */
+const FOLLOW_BOTTOM_THRESHOLD_PX = 64;
+
+interface QueuedPrompt {
+  text: string;
+  attachments: File[];
+}
+
+export interface StructuredPaneProps {
+  sessionId: Uuid;
+  /** Grabs the composer once mounted. A sidebar preview passes `false`. */
+  focus?: boolean;
+  shouldReconnect?: (code: number) => boolean;
+  onClosed?: () => void;
+  onStatusChange?: (status: StructuredStatus, detail?: string) => void;
+  /** Test seam: drive the socket without a daemon. */
+  socketFactory?: StructuredSocketFactory;
+  className?: string;
+}
+
+export interface StructuredPaneHandle {
+  /** Put the keyboard in the composer — the structured pane's terminal. */
+  focusComposer(): void;
+}
+
+export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPaneProps>(function StructuredPane(
+  { sessionId, focus = true, shouldReconnect, onClosed, onStatusChange, socketFactory, className },
+  ref,
+) {
+  const session = useStructuredSession(sessionId, { shouldReconnect, onClosed, socketFactory });
+  const { rows, state, status, detail, socketGeneration } = session;
+
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const composerRef = useRef<HTMLDivElement | null>(null);
+  const followingBottom = useRef(true);
+
+  const [expandedRows, setExpandedRows] = useState<ReadonlySet<string>>(new Set());
+  const [expandedGroups, setExpandedGroups] = useState<ReadonlySet<string>>(new Set());
+  const [draft, setDraft] = useState("");
+  const [attachments, setAttachments] = useState<File[]>([]);
+  const [queue, setQueue] = useState<QueuedPrompt[]>([]);
+  const [uploading, setUploading] = useState(false);
+  const [configBusy, setConfigBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [now, setNow] = useState(() => Date.now());
+  /** Server path → object URL, so a user row can preview an image it uploaded. */
+  const imageUrls = useRef(new Map<string, string>());
+
+  // Submission bookkeeping, ported from structured.ts: a prompt is "sending"
+  // from the POST until the projection shows the turn it claimed, and an
+  // acceptance that straddles a reconnect forces one more reconnect so the
+  // snapshot cannot predate the 204.
+  const submission = useRef(0);
+  const accepted = useRef<{ generation: number; socketGeneration: number } | null>(null);
+  const optimisticStart = useRef<number | null>(null);
+  const promptPending = useRef(false);
+  const [awaitingBegin, setAwaitingBegin] = useState<number | null>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      focusComposer: () => composerRef.current?.querySelector<HTMLTextAreaElement>(".structured-input")?.focus(),
+    }),
+    [],
+  );
+
+  useEffect(() => {
+    onStatusChange?.(status, detail ?? undefined);
+  }, [status, detail, onStatusChange]);
+
+  useEffect(() => {
+    if (!focus) return;
+    composerRef.current?.querySelector<HTMLTextAreaElement>(".structured-input")?.focus();
+  }, [focus]);
+
+  const urls = imageUrls.current;
+  useEffect(
+    () => () => {
+      for (const url of urls.values()) URL.revokeObjectURL(url);
+      urls.clear();
+    },
+    [urls],
+  );
+
+  const turnActive = turnIsActive(state);
+  const pendingRowId = useMemo(() => pendingApprovalRowIdOf(rows, state), [rows, state]);
+  const items = useMemo(
+    () => transcriptItems(rows, pendingRowId, turnActive),
+    [rows, pendingRowId, turnActive],
+  );
+  const commands = useMemo(() => commandsFromTranscript(rows), [rows]);
+  const configOptions: AcpSessionConfigOption[] = state.config_options?.configOptions ?? [];
+
+  const active = turnActive || awaitingBegin !== null;
+
+  // Stop saying "Sending" once the turn the submission was waiting for has
+  // begun — or, when it was accepted but a replacement socket has
+  // re-snapshotted since, once that newer snapshot has landed. Without the
+  // second case a prompt accepted across a reconnect would say "Sending"
+  // forever.
+  useEffect(() => {
+    if (turnActive) {
+      setAwaitingBegin(null);
+    } else if (
+      awaitingBegin !== null &&
+      accepted.current?.generation === awaitingBegin &&
+      socketGeneration > accepted.current.socketGeneration
+    ) {
+      setAwaitingBegin(null);
+    }
+  }, [turnActive, awaitingBegin, socketGeneration]);
+
+  useEffect(() => {
+    if (!active) optimisticStart.current = null;
+  }, [active]);
+
+  // Keep the pane pinned to the newest row unless the operator scrolled away.
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (!el || !followingBottom.current) return;
+    el.scrollTop = Math.max(0, el.scrollHeight - el.clientHeight);
+  }, [items, active, queue]);
+
+  useEffect(() => {
+    if (!active) return;
+    const timer = window.setInterval(() => setNow(Date.now()), 1_000);
+    return () => window.clearInterval(timer);
+  }, [active]);
+
+  const onScroll = () => {
+    const el = scrollRef.current;
+    if (!el) return;
+    followingBottom.current = el.scrollHeight - el.clientHeight - el.scrollTop <= FOLLOW_BOTTOM_THRESHOLD_PX;
+  };
+
+  const decide = useCallback(
+    async (rowId: string, decision: StructuredApprovalDecision): Promise<void> => {
+      const nonce = state.pending_approval?.nonce;
+      // Already resolved elsewhere between the click and here. A stale nonce
+      // is a no-op, not an error (docs/STRUCTURED-VIEW.md: any nonce answers
+      // 204), and the row's buttons are already gone — resolve quietly.
+      if (!nonce || rowId !== pendingRowId) return;
+      try {
+        await resolveStructuredApproval(sessionId, nonce, decision);
+      } catch (e: unknown) {
+        // Propagate — so the row re-enables its buttons — only while this is
+        // still the pending approval. If it moved on in flight, reviving the
+        // buttons would revive a decision that no longer applies.
+        setError(String(e));
+        throw e;
+      }
+    },
+    [sessionId, state.pending_approval?.nonce, pendingRowId],
+  );
+
+  const dispatchPrompt = useCallback(
+    (text: string, files: File[]) => {
+      const generation = ++submission.current;
+      const submissionSocket = socketGeneration;
+      setAwaitingBegin(generation);
+      optimisticStart.current = Date.now();
+      accepted.current = null;
+      promptPending.current = true;
+      setUploading(files.length > 0);
+      setDraft("");
+      setError(null);
+
+      const send = async () => {
+        const references: string[] = [];
+        for (const file of files) {
+          const { path } = await uploadStructuredFile(sessionId, file);
+          if (file.type.startsWith("image/")) imageUrls.current.set(path, URL.createObjectURL(file));
+          references.push(`Attached file ${JSON.stringify(file.name)}: ${JSON.stringify(path)}`);
+        }
+        await sendStructuredPrompt(sessionId, [text, ...references].filter(Boolean).join("\n\n"));
+      };
+
+      void send().then(
+        () => {
+          promptPending.current = false;
+          if (generation !== submission.current) return;
+          setUploading(false);
+          setAttachments((current) => (current === files ? [] : current));
+          accepted.current = { generation, socketGeneration };
+          // A replacement socket may have captured idle before the POST
+          // claimed the prompt. Reconnect so its snapshot cannot predate the
+          // 204.
+          if (socketGeneration > submissionSocket) session.reconnect();
+        },
+        (e: unknown) => {
+          promptPending.current = false;
+          if (generation !== submission.current) return;
+          setAwaitingBegin((current) => (current === generation ? null : current));
+          optimisticStart.current = null;
+          setUploading(false);
+          // The draft and its attachments are the operator's work — a failed
+          // send hands both back rather than eating them.
+          setAttachments((current) => (current.length === 0 ? files : current));
+          setDraft((current) => (current === "" ? text : current));
+          setError(String(e));
+        },
+      );
+    },
+    [sessionId, socketGeneration, session],
+  );
+
+  // A queued message goes out as soon as the projected turn is idle — the
+  // daemon answers a second prompt `409 turn_in_flight`, so the queue is
+  // client-local (docs/STRUCTURED-VIEW.md).
+  useEffect(() => {
+    if (active || promptPending.current || queue.length === 0) return;
+    const [next, ...rest] = queue;
+    setQueue(rest);
+    dispatchPrompt(next.text, next.attachments);
+  }, [active, queue, dispatchPrompt]);
+
+  const submit = (text: string, files: File[]) => {
+    if (active || queue.length > 0) {
+      setQueue((current) => [...current, { text, attachments: files }]);
+      setAttachments([]);
+      setDraft("");
+      setError(null);
+      return;
+    }
+    dispatchPrompt(text, files);
+  };
+
+  const cancel = () => {
+    setError(null);
+    cancelStructuredTurn(sessionId).catch((e: unknown) => setError(String(e)));
+  };
+
+  const changeConfig = (option: AcpSessionConfigOption, value: string | boolean) => {
+    setConfigBusy(true);
+    setError(null);
+    setStructuredConfig(sessionId, { config_id: option.id, value })
+      .catch((e: unknown) =>
+        setError(e instanceof Error ? e.message : "Could not change the session setting"),
+      )
+      .finally(() => setConfigBusy(false));
+  };
+
+  const elapsedMs = () => {
+    const authoritative = state.turn.started_at ? Date.parse(state.turn.started_at) : Number.NaN;
+    const startedAt = Number.isFinite(authoritative) ? authoritative : optimisticStart.current;
+    return startedAt === null ? 0 : Math.max(0, now - startedAt);
+  };
+
+  const activityLabel = () => {
+    const tools = state.turn.active_tool_calls.length;
+    const label = awaitingBegin !== null
+      ? "Sending"
+      : state.turn.thinking
+        ? "Thinking"
+        : tools > 0
+          ? `Running ${tools} ${tools === 1 ? "tool" : "tools"}`
+          : "Responding";
+    const parts = [label, formatElapsed(elapsedMs())];
+    if (typeof state.usage?.used === "number") {
+      const usage = formatContextTokens(state.usage.used);
+      parts.push(
+        typeof state.usage.size === "number" ? `${usage} / ${formatContextTokens(state.usage.size)}` : usage,
+      );
+    }
+    return parts.join(" · ");
+  };
+
+  const setRowExpanded = (id: string, expanded: boolean) =>
+    setExpandedRows((current) => {
+      const next = new Set(current);
+      if (expanded) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+
+  const setGroupExpanded = (id: string, expanded: boolean) =>
+    setExpandedGroups((current) => {
+      const next = new Set(current);
+      if (expanded) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+
+  const renderRow = (row: Row) => (
+    <TranscriptRow
+      key={row.id}
+      row={row}
+      pendingApproval={row.id === pendingRowId}
+      onDecide={(decision) => decide(row.id, decision)}
+      expanded={expandedRows.has(row.id)}
+      onExpandedChange={(expanded) => setRowExpanded(row.id, expanded)}
+      imageUrls={imageUrls.current}
+    />
+  );
+
+  return (
+    <div className={className ? `structured-pane ${className}` : "structured-pane"}>
+      <div className="structured-body">
+        <div className="structured-main">
+          <div className="structured-scroll" ref={scrollRef} onScroll={onScroll}>
+            <div className="structured-rows">
+              {items.map((item) =>
+                item.type === "row" ? (
+                  renderRow(item.row)
+                ) : (
+                  <ToolGroup
+                    key={item.id}
+                    id={item.id}
+                    toolCount={item.group.toolCount}
+                    expanded={expandedGroups.has(item.id)}
+                    onExpandedChange={(expanded) => setGroupExpanded(item.id, expanded)}
+                  >
+                    {item.group.rows.map(renderRow)}
+                  </ToolGroup>
+                ),
+              )}
+              {queue.map((queued, index) => (
+                <div key={`queued-${index}`} className="st-row st-row-queued">
+                  <div className="st-body">
+                    <div className="st-user-text">{queued.text}</div>
+                  </div>
+                </div>
+              ))}
+            </div>
+            <div className="structured-activity" role="status" aria-live="polite" hidden={!active}>
+              <span className="structured-activity-pulse" aria-hidden="true" />
+              <span className="structured-activity-text">{active ? activityLabel() : ""}</span>
+            </div>
+          </div>
+          {error !== null && <div className="structured-error">{error}</div>}
+          <div ref={composerRef}>
+            <Composer
+              attachments={attachments}
+              onAttachmentsChange={setAttachments}
+              commands={commands}
+              configOptions={configOptions}
+              turnActive={active}
+              uploading={uploading}
+              configBusy={configBusy}
+              draft={draft}
+              onDraftChange={setDraft}
+              onSubmit={submit}
+              onCancel={cancel}
+              onConfigChange={changeConfig}
+              onError={setError}
+              menuId={`structured-command-menu-${sessionId}`}
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+});

web/src/components/structured/ToolGroup.tsx

@@ -0,0 +1,43 @@
+// A turn's collapsed activity block: two or more tool rows after the same
+// `User` row, plus the narration absorbed between them. The header counts tool
+// rows only (docs/STRUCTURED-VIEW.md); opening it reveals tools and text in
+// chronological order.
+
+import type { ReactNode } from "react";
+
+export interface ToolGroupProps {
+  id: string;
+  toolCount: number;
+  expanded: boolean;
+  onExpandedChange(expanded: boolean): void;
+  children: ReactNode;
+}
+
+export function ToolGroup({ id, toolCount, expanded, onExpandedChange, children }: ToolGroupProps) {
+  return (
+    <div className="st-tool-group" data-tool-group-id={id}>
+      <button
+        type="button"
+        className="st-tool-group-head"
+        aria-expanded={expanded}
+        onClick={() => onExpandedChange(!expanded)}
+      >
+        <span className="st-tool-group-glyph" aria-hidden="true">
+          ›
+        </span>
+        <span className="st-tool-group-title">{`${toolCount} tool calls`}</span>
+      </button>
+      <div
+        className={
+          expanded ? "st-tool-group-body st-disclosure is-expanded" : "st-tool-group-body st-disclosure"
+        }
+        aria-hidden={!expanded}
+        inert={!expanded}
+      >
+        <div className="st-disclosure-clip">
+          <div className="st-disclosure-inner">{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}

web/src/components/structured/ToolIcon.tsx

@@ -0,0 +1,35 @@
+// The glyph column of a tool row's head. Recognition is narrow on purpose: an
+// unrecognised or absent `ToolKind` gets the generic bullet, never a blank
+// column and never a mark that stands for the wrong kind of work.
+
+import type { AcpToolKind } from "../../types.js";
+
+/** Glyph shown in a tool row's head, by `ToolKind`. */
+const KIND_GLYPH: Record<string, string> = {
+  read: "≡",
+  edit: "±",
+  delete: "✕",
+  move: "→",
+  search: "⌕",
+  execute: "$",
+  think: "…",
+  fetch: "⇣",
+  switch_mode: "⇄",
+};
+
+export function toolGlyph(kind: string | undefined): string {
+  return (kind && KIND_GLYPH[kind]) || "•";
+}
+
+export interface ToolIconProps {
+  kind: AcpToolKind | string | undefined;
+  className?: string;
+}
+
+export function ToolIcon({ kind, className = "st-tool-glyph" }: ToolIconProps) {
+  return (
+    <span className={className} aria-hidden="true">
+      {toolGlyph(kind)}
+    </span>
+  );
+}

web/src/components/structured/TranscriptRow.tsx

@@ -0,0 +1,387 @@
+// One transcript row, by kind. docs/STRUCTURED-VIEW.md fixes the eight kinds
+// and leaves every rendering decision here: markdown for AgentText, an inline
+// italic stream for AgentThought, a tool card for ToolCall/ToolDiff, a diff
+// view for ToolDiff's content, an approval card for Approval, and an opaque
+// collapsed line for a Notice nobody has taught the client about. `Plan` is
+// deliberately not drawn — the web client has no plan rail.
+
+import { useEffect, useRef, type ReactNode } from "react";
+
+import { renderInlineMarkdown, renderMarkdown, formatElapsed } from "../../structuredRender.js";
+import type {
+  AcpContentBlock,
+  AcpPermissionOption,
+  AcpToolCallContent,
+  AcpToolCallLike,
+  StructuredApprovalDecision,
+  TranscriptRow as Row,
+  TurnMeta,
+} from "../../types.js";
+import { ApprovalView } from "./ApprovalView.js";
+import { Copyable } from "./Copyable.js";
+import { DiffView } from "./DiffView.js";
+import {
+  contentBlockText,
+  isStateOnlyNotice,
+  splitToolTitle,
+  statusMeta,
+  toolDiffMeta,
+  turnMeta,
+} from "./model.js";
+import { safeMediaSource, toolPayload } from "./toolPayload.js";
+import { ToolIcon } from "./ToolIcon.js";
+
+// ---------------------------------------------------------------------------
+// content rows: user / agent / thought
+// ---------------------------------------------------------------------------
+
+/** Model-authored markdown, sanitized by structuredRender.ts before it enters
+ *  the DOM. Tables get their own scroller and links open out of the app. */
+function Prose({ html }: { html: string }) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    const container = ref.current;
+    if (!container) return;
+    for (const table of Array.from(container.querySelectorAll("table"))) {
+      if (table.parentElement?.classList.contains("st-markdown-table-wrap")) continue;
+      const scroller = document.createElement("div");
+      scroller.className = "st-markdown-table-wrap";
+      table.replaceWith(scroller);
+      scroller.appendChild(table);
+    }
+    for (const link of container.querySelectorAll("a")) {
+      link.target = "_blank";
+      link.rel = "noopener noreferrer";
+    }
+  }, [html]);
+  return <div ref={ref} className="st-body" dangerouslySetInnerHTML={{ __html: html }} />;
+}
+
+export interface ContentRowProps {
+  row: Row;
+  variant: "user" | "agent" | "thought";
+  /** Object URLs for images this prompt uploaded, keyed by the server path the
+   *  row's text names. */
+  imageUrls?: Map<string, string>;
+}
+
+/** `Attached file "name": "path"` references the composer appends on send. */
+const ATTACHED_FILE_RE = /Attached file "(?:[^"\\]|\\.)*": "((?:[^"\\]|\\.)*)"/g;
+
+function attachedImages(text: string, imageUrls: Map<string, string>): string[] {
+  const urls: string[] = [];
+  ATTACHED_FILE_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = ATTACHED_FILE_RE.exec(text)) !== null) {
+    let serverPath: string;
+    try {
+      serverPath = JSON.parse(`"${match[1]}"`) as string;
+    } catch {
+      continue;
+    }
+    const url = imageUrls.get(serverPath);
+    if (url) urls.push(url);
+  }
+  return urls;
+}
+
+export function ContentRow({ row, variant, imageUrls }: ContentRowProps) {
+  const data = row.data as { content?: AcpContentBlock } | undefined;
+  const text = contentBlockText(data?.content);
+  const displayText = variant === "thought" ? text.trim() : text;
+  const label = variant === "user" ? "message" : variant === "agent" ? "response" : "thought";
+
+  let body: ReactNode;
+  if (variant === "user") {
+    const images = imageUrls && imageUrls.size > 0 ? attachedImages(displayText, imageUrls) : [];
+    // With previews in hand the path references are noise — the image is the
+    // attachment. Without them the text is all the operator has, so it stays.
+    const shown =
+      images.length > 0
+        ? displayText.replace(/\n\nAttached file "[^"]*": "[^"]*"/g, "").trim()
+        : displayText;
+    body = (
+      <div className="st-body">
+        {shown && <div className="st-user-text">{shown}</div>}
+        {images.map((src) => (
+          <img key={src} className="st-user-image" src={src} alt="Uploaded image" loading="lazy" />
+        ))}
+      </div>
+    );
+  } else if (variant === "agent") {
+    body = <Prose html={renderMarkdown(displayText)} />;
+  } else {
+    body = <div className="st-body" dangerouslySetInnerHTML={{ __html: renderInlineMarkdown(displayText) }} />;
+  }
+
+  return (
+    <Copyable className={`st-row st-row-${variant}`} text={displayText} label={label} data-row-id={row.id}>
+      {body}
+    </Copyable>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// tool rows
+// ---------------------------------------------------------------------------
+
+function ToolDetailBlock({ label, text }: { label: string; text: string }) {
+  return (
+    <div className="st-tool-detail">
+      <div className="st-tool-detail-label">{label}</div>
+      <Copyable as="pre" text={text} label={label.toLowerCase()}>
+        {text}
+      </Copyable>
+    </div>
+  );
+}
+
+function ContentBlockView({ block }: { block: AcpContentBlock }) {
+  if (block.type === "text") {
+    if (!block.text) return null;
+    return (
+      <Copyable className="st-tool-text" text={block.text} label="output">
+        {block.text}
+      </Copyable>
+    );
+  }
+  if (block.type === "image") {
+    const source = safeMediaSource(block.mimeType, block.data, "image");
+    if (source) return <img className="st-tool-image" src={source} alt="Tool output" loading="lazy" />;
+    return <ToolDetailBlock label="Image" text={block.uri ?? block.mimeType ?? "Unavailable"} />;
+  }
+  if (block.type === "audio") {
+    const source = safeMediaSource(block.mimeType, block.data, "audio");
+    if (source) return <audio className="st-tool-audio" controls src={source} />;
+    return <ToolDetailBlock label="Audio" text={block.mimeType ?? "Unavailable"} />;
+  }
+  if (block.type === "resource_link") {
+    return (
+      <div className="st-tool-resource">
+        <span className="st-tool-resource-name">{block.title ?? block.name ?? "Resource"}</span>
+        {block.uri && (
+          <Copyable as="code" className="st-tool-resource-uri" text={block.uri} label="resource URI">
+            {block.uri}
+          </Copyable>
+        )}
+        {block.description && <span className="st-tool-resource-description">{block.description}</span>}
+      </div>
+    );
+  }
+  const resource = block.resource;
+  if (typeof resource?.text === "string") {
+    return (
+      <ToolDetailBlock label={resource.uri ? `Resource · ${resource.uri}` : "Resource"} text={resource.text} />
+    );
+  }
+  const printed = resource === undefined ? "" : JSON.stringify(resource, null, 2);
+  return printed ? <ToolDetailBlock label="Resource" text={printed} /> : null;
+}
+
+function ToolBody({ tool, content }: { tool: AcpToolCallLike; content: AcpToolCallContent[] }) {
+  const payload = toolPayload(tool, content);
+  const hasRaw = payload.raw.input !== null || payload.raw.output !== null;
+  return (
+    <>
+      {content.map((block, index) => {
+        if (block.type === "content") return <ContentBlockView key={index} block={block.content} />;
+        if (block.type === "diff") return <DiffView key={index} diff={block} />;
+        return (
+          <div key={index} className="st-tool-terminal">
+            {block.terminalId ? `Terminal · ${block.terminalId}` : "Embedded terminal"}
+          </div>
+        );
+      })}
+      {payload.details.map((detail, index) => (
+        <ToolDetailBlock key={`${detail.label}-${index}`} label={detail.label} text={detail.text} />
+      ))}
+      {payload.exitCode !== null && (
+        <div className="st-tool-fact">
+          <span className="st-tool-fact-label">Exit code</span>
+          <code className={payload.exitCode === 0 ? "st-tool-exit-ok" : "st-tool-exit-failed"}>
+            {payload.exitCode}
+          </code>
+        </div>
+      )}
+      {hasRaw && (
+        <details className="st-tool-raw">
+          <summary>Raw JSON</summary>
+          <div className="st-tool-raw-body">
+            {payload.raw.input !== null && <ToolDetailBlock label="Input" text={payload.raw.input} />}
+            {payload.raw.output !== null && <ToolDetailBlock label="Output" text={payload.raw.output} />}
+          </div>
+        </details>
+      )}
+    </>
+  );
+}
+
+/** True when a tool call has anything at all to disclose — a head with nothing
+ *  behind it stays a plain line rather than an empty disclosure. */
+function hasToolBody(tool: AcpToolCallLike, content: AcpToolCallContent[]): boolean {
+  if (content.length > 0) return true;
+  const payload = toolPayload(tool, content);
+  return payload.details.length > 0 || payload.exitCode !== null || payload.raw.input !== null || payload.raw.output !== null;
+}
+
+export interface ToolRowProps {
+  row: Row;
+  expanded: boolean;
+  onExpandedChange(expanded: boolean): void;
+}
+
+export function ToolRow({ row, expanded, onExpandedChange }: ToolRowProps) {
+  const tool = (row.data ?? {}) as AcpToolCallLike;
+  const content = tool.content ?? [];
+  const hasDiff = content.some((c) => c.type === "diff");
+  const { label, arg } = splitToolTitle(tool.title, tool.name, tool.kind);
+  const meta = statusMeta(tool.status, hasDiff);
+  const metaParts: string[] = [];
+  if (hasDiff) metaParts.push(toolDiffMeta(content));
+  if (meta) metaParts.push(meta.text);
+  const disclosable = hasToolBody(tool, content);
+  const open = expanded && disclosable;
+
+  return (
+    <div className="st-row st-row-tool" data-row-id={row.id}>
+      <div className="st-tool">
+        <button
+          type="button"
+          className="st-tool-head"
+          aria-expanded={open}
+          onClick={() => disclosable && onExpandedChange(!open)}
+        >
+          <ToolIcon kind={tool.kind} />
+          <span className="st-tool-name">{label}</span>
+          <span className="st-tool-arg" title={arg}>
+            {arg}
+          </span>
+          {metaParts.length > 0 && (
+            <span className={meta ? `st-tool-meta st-tool-meta-${meta.kind}` : "st-tool-meta"}>
+              {metaParts.join(" · ")}
+            </span>
+          )}
+        </button>
+        {disclosable && (
+          <div
+            className={open ? "st-tool-out st-disclosure is-expanded" : "st-tool-out st-disclosure"}
+            aria-hidden={!open}
+            inert={!open}
+          >
+            <div className="st-disclosure-clip">
+              <div className="st-disclosure-inner">
+                {/* Built only once opened: a long transcript would otherwise
+                    render every tool's whole output up front. */}
+                {open && <ToolBody tool={tool} content={content} />}
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// notices and turn footers
+// ---------------------------------------------------------------------------
+
+function compactNumber(value: number): string {
+  if (Math.abs(value) < 1_000) return String(value);
+  if (Math.abs(value) < 1_000_000) return `${(value / 1_000).toFixed(value % 1_000 === 0 ? 0 : 1)}k`;
+  return `${(value / 1_000_000).toFixed(value % 1_000_000 === 0 ? 0 : 1)}m`;
+}
+
+export function TurnMetaRow({ meta }: { meta: TurnMeta }) {
+  const parts = [formatElapsed(meta.elapsedMs)];
+  if (typeof meta.contextDelta === "number") {
+    const sign = meta.contextDelta > 0 ? "+" : "";
+    parts.push(`${sign}${compactNumber(meta.contextDelta)} context tokens`);
+  } else if (typeof meta.contextTokens === "number") {
+    parts.push(`${compactNumber(meta.contextTokens)} context`);
+  }
+  if (meta.model) parts.push(meta.model);
+  if (meta.outcome !== "completed") parts.push(meta.outcome);
+  const text = parts.join(" · ");
+  return (
+    <Copyable
+      className={`st-turn-meta st-turn-meta-${meta.outcome}`}
+      text={text}
+      label="turn details"
+      aria-label={`Turn ${meta.outcome}`}
+    >
+      <span className="st-turn-meta-dot" aria-hidden="true" />
+      <span>{text}</span>
+    </Copyable>
+  );
+}
+
+/** The floor presentation docs/STRUCTURED-VIEW.md allows for a `Notice` the
+ *  client has nothing better to do with: an opaque, collapsed line. */
+export function NoticeRow({ row }: { row: Row }) {
+  const text = `[${row.kind}]`;
+  return (
+    <Copyable className="st-row st-row-notice" text={text} label="notice" data-row-id={row.id}>
+      <div className="st-body">{text}</div>
+    </Copyable>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+
+export interface TranscriptRowProps {
+  row: Row;
+  /** This row is the one live approval (docs/STRUCTURED-VIEW.md's nonce
+   *  rules). Every other approval row is history. */
+  pendingApproval?: boolean;
+  onDecide?: (decision: StructuredApprovalDecision) => Promise<void>;
+  expanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  imageUrls?: Map<string, string>;
+}
+
+/** One transcript row, or `null` for the rows the web client omits (`plan`,
+ *  and the state-only notices it consumes for `/` autocomplete). */
+export function TranscriptRow({
+  row,
+  pendingApproval = false,
+  onDecide,
+  expanded = false,
+  onExpandedChange,
+  imageUrls,
+}: TranscriptRowProps) {
+  switch (row.kind) {
+    case "user":
+      return <ContentRow row={row} variant="user" imageUrls={imageUrls} />;
+    case "agent_text":
+      return <ContentRow row={row} variant="agent" />;
+    case "agent_thought":
+      return <ContentRow row={row} variant="thought" />;
+    case "tool_call":
+    case "tool_diff":
+      return (
+        <ToolRow row={row} expanded={expanded} onExpandedChange={(next) => onExpandedChange?.(next)} />
+      );
+    case "approval": {
+      const request = (row.data ?? {}) as { toolCall?: AcpToolCallLike; options?: AcpPermissionOption[] };
+      return (
+        <ApprovalView
+          request={request}
+          pending={pendingApproval}
+          onDecide={onDecide ?? (() => Promise.resolve())}
+        />
+      );
+    }
+    case "plan":
+      return null;
+    case "notice": {
+      if (isStateOnlyNotice(row)) return null;
+      const meta = turnMeta(row);
+      return meta ? <TurnMetaRow meta={meta} /> : <NoticeRow row={row} />;
+    }
+    default:
+      return <NoticeRow row={row} />;
+  }
+}

web/src/components/structured/index.ts

@@ -0,0 +1,13 @@
+export { StructuredPane, type StructuredPaneHandle, type StructuredPaneProps } from "./StructuredPane.js";
+export { TranscriptRow, type TranscriptRowProps } from "./TranscriptRow.js";
+export { DiffView, type DiffViewProps } from "./DiffView.js";
+export { ApprovalView, type ApprovalViewProps } from "./ApprovalView.js";
+export { ToolGroup, type ToolGroupProps } from "./ToolGroup.js";
+export { ToolIcon, toolGlyph, type ToolIconProps } from "./ToolIcon.js";
+export { Composer, type ComposerProps } from "./Composer.js";
+export {
+  useStructuredSession,
+  type StructuredSession,
+  type StructuredSocketFactory,
+  type StructuredStatus,
+} from "./useStructuredSession.js";

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

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+
+import type { ReducedState, TranscriptRow } from "../../types.js";
+import {
+  activityGroupsByTurn,
+  applyCommand,
+  commandsFromTranscript,
+  commandTokenAt,
+  contentBlockText,
+  filterCommands,
+  isStateOnlyNotice,
+  offeredDecisions,
+  orderConfigOptions,
+  pendingApprovalRowId,
+  splitToolTitle,
+  statusMeta,
+  toolDiffMeta,
+  toolKindLabel,
+  transcriptItems,
+  turnMeta,
+} from "./model.js";
+
+function row(id: string, kind: TranscriptRow["kind"], data: unknown = {}): TranscriptRow {
+  return { id, kind, data };
+}
+
+function tool(id: string): TranscriptRow {
+  return row(id, "tool_call", { title: `Read(${id})`, status: "completed" });
+}
+
+function text(id: string, kind: "user" | "agent_text" | "agent_thought", body: string): TranscriptRow {
+  return row(id, kind, { content: { type: "text", text: body } });
+}
+
+const idle: ReducedState = { turn: { responding: false, thinking: false, active_tool_calls: [] } };
+
+describe("row taxonomy", () => {
+  it("splits an adapter's Name(argument) title, and falls back to the kind", () => {
+    expect(splitToolTitle("Read(src/main.ts)", null, "read")).toEqual({ label: "Read", arg: "src/main.ts" });
+    expect(splitToolTitle("something opaque", null, "search")).toEqual({
+      label: "Search",
+      arg: "something opaque",
+    });
+    expect(splitToolTitle(undefined, null, undefined)).toEqual({ label: "Tool", arg: "" });
+  });
+
+  it("labels an unknown tool kind rather than leaving it blank", () => {
+    expect(toolKindLabel("execute")).toBe("Execute");
+    expect(toolKindLabel("no_such_kind")).toBe("Tool");
+    expect(toolKindLabel(undefined)).toBe("Tool");
+  });
+
+  it("names non-text content blocks instead of dropping them", () => {
+    expect(contentBlockText({ type: "text", text: "hi" })).toBe("hi");
+    expect(contentBlockText({ type: "image" })).toBe("[image]");
+    expect(contentBlockText({ type: "resource_link", name: "spec.md" })).toBe("[resource: spec.md]");
+    expect(contentBlockText(undefined)).toBe("");
+  });
+
+  it("counts a tool call's diff lines", () => {
+    expect(toolDiffMeta([{ type: "diff", path: "a.ts", oldText: "one\ntwo\n", newText: "one\nTWO\nthree\n" }]))
+      .toBe("+2 −1");
+    expect(toolDiffMeta([])).toBe("+0 −0");
+  });
+
+  it("shows a status only while it is worth showing", () => {
+    expect(statusMeta("in_progress", false)).toEqual({ text: "running", kind: "running" });
+    expect(statusMeta("failed", true)).toEqual({ text: "failed", kind: "failed" });
+    expect(statusMeta("pending", true)).toBeNull(); // the diff counts already say it
+    expect(statusMeta("completed", false)).toBeNull();
+  });
+});
+
+describe("notices", () => {
+  it("reads a maestroTurnMeta footer, and only a well-formed one", () => {
+    const meta = { elapsedMs: 4200, outcome: "completed", model: "sonnet" };
+    expect(turnMeta(row("n1", "notice", { maestroTurnMeta: meta }))).toEqual(meta);
+    expect(turnMeta(row("n2", "notice", { maestroTurnMeta: { outcome: "completed" } }))).toBeNull();
+    expect(turnMeta(row("n3", "notice", { sessionUpdate: "session_info_update" }))).toBeNull();
+  });
+
+  it("marks the state-only notices the client consumes rather than shows", () => {
+    expect(isStateOnlyNotice(row("n1", "notice", { sessionUpdate: "available_commands_update" }))).toBe(true);
+    expect(isStateOnlyNotice(row("n2", "notice", { sessionUpdate: "session_info_update" }))).toBe(true);
+    expect(isStateOnlyNotice(row("n3", "notice", { sessionUpdate: "something_else" }))).toBe(false);
+  });
+});
+
+describe("approvals", () => {
+  it("offers only decisions the request actually backs", () => {
+    expect(
+      offeredDecisions([
+        { optionId: "a", name: "Allow once", kind: "allow_once" },
+        { optionId: "r", name: "Reject", kind: "reject_once" },
+      ]),
+    ).toEqual(["allow_once", "deny"]);
+    expect(offeredDecisions([{ optionId: "a", name: "Always", kind: "allow_always" }])).toEqual([
+      "allow_for_session",
+    ]);
+    expect(offeredDecisions([])).toEqual([]);
+  });
+
+  it("points a live pending approval at the newest approval row", () => {
+    const rows = [row("approval:1", "approval"), tool("tool:1"), row("approval:2", "approval")];
+    const pending: ReducedState = {
+      ...idle,
+      pending_approval: { nonce: "n", request: {} as never },
+    };
+    expect(pendingApprovalRowId(rows, pending)).toBe("approval:2");
+    expect(pendingApprovalRowId(rows, idle)).toBeNull();
+  });
+});
+
+describe("activity grouping", () => {
+  it("groups a turn's tools once there are two of them", () => {
+    const rows = [text("user:1", "user", "go"), tool("tool:1"), tool("tool:2")];
+    const groups = activityGroupsByTurn(rows, null, false);
+    expect([...groups.keys()]).toEqual(["turn:user:1"]);
+    expect(groups.get("turn:user:1")).toMatchObject({ toolCount: 2 });
+  });
+
+  it("leaves a single tool call standalone", () => {
+    const rows = [text("user:1", "user", "go"), tool("tool:1")];
+    expect(activityGroupsByTurn(rows, null, false).size).toBe(0);
+  });
+
+  it("absorbs intermediate narration but keeps the final answer outside", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      text("agent:1", "agent_text", "working"),
+      tool("tool:2"),
+      text("agent:2", "agent_text", "done"),
+    ];
+    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
+    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "agent:1", "tool:2"]);
+    expect(group.toolCount).toBe(2);
+  });
+
+  it("keeps the newest thought outside while the turn is still live", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      tool("tool:2"),
+      text("thought:1", "agent_thought", "hmm"),
+      text("thought:2", "agent_thought", "aha"),
+    ];
+    const live = activityGroupsByTurn(rows, null, true).get("turn:user:1")!;
+    expect(live.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1"]);
+    const ended = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
+    expect(ended.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1", "thought:2"]);
+  });
+
+  it("absorbs a resolved approval, never the pending one", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      row("approval:1", "approval"),
+      tool("tool:2"),
+      row("approval:2", "approval"),
+      tool("tool:3"),
+    ];
+    const group = activityGroupsByTurn(rows, "approval:2", false).get("turn:user:1")!;
+    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "approval:1", "tool:2", "tool:3"]);
+  });
+});
+
+describe("transcript render list", () => {
+  it("renders a group once, at its first member's position", () => {
+    const rows = [text("user:1", "user", "go"), tool("tool:1"), tool("tool:2"), text("agent:1", "agent_text", "done")];
+    const items = transcriptItems(rows, null, false);
+    expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual([
+      "user:1",
+      "turn:user:1",
+      "agent:1",
+    ]);
+  });
+
+  it("omits plan rows, state-only notices and standalone resolved approvals", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      row("plan", "plan", { entries: [] }),
+      row("notice:1", "notice", { sessionUpdate: "available_commands_update", availableCommands: [] }),
+      row("approval:1", "approval"),
+      text("agent:1", "agent_text", "done"),
+    ];
+    const items = transcriptItems(rows, null, false);
+    expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual(["user:1", "agent:1"]);
+  });
+
+  it("keeps a turn footer only while it is the final item", () => {
+    const footer = row("turn_meta:1", "notice", { maestroTurnMeta: { elapsedMs: 10, outcome: "completed" } });
+    expect(transcriptItems([text("user:1", "user", "go"), footer], null, false)).toHaveLength(2);
+    const later = [text("user:1", "user", "go"), footer, text("user:2", "user", "again")];
+    expect(transcriptItems(later, null, false).map((i) => (i.type === "row" ? i.row.id : i.id))).toEqual([
+      "user:1",
+      "user:2",
+    ]);
+  });
+});
+
+describe("composer commands", () => {
+  const notice = row("notice:9", "notice", {
+    sessionUpdate: "available_commands_update",
+    availableCommands: [
+      { name: "compact", description: "Compact  the\n conversation" },
+      { name: "cost", description: "Show cost", input: { hint: "[period]" } },
+      { name: 42 },
+    ],
+  });
+
+  it("takes the newest available_commands_update, skipping malformed entries", () => {
+    const stale = row("notice:1", "notice", {
+      sessionUpdate: "available_commands_update",
+      availableCommands: [{ name: "old", description: "gone" }],
+    });
+    expect(commandsFromTranscript([stale, notice]).map((c) => c.name)).toEqual(["compact", "cost"]);
+    expect(commandsFromTranscript([])).toEqual([]);
+  });
+
+  it("only matches a /token under the caret", () => {
+    expect(commandTokenAt("/comp", 5, 5)).toEqual({ start: 0, end: 5, query: "comp" });
+    expect(commandTokenAt("hello /co there", 9, 9)).toEqual({ start: 6, end: 9, query: "co" });
+    expect(commandTokenAt("no slash", 3, 3)).toBeNull();
+    expect(commandTokenAt("/comp", 2, 5)).toBeNull(); // a selection is not a caret
+  });
+
+  it("ranks prefix matches ahead of substring matches", () => {
+    const commands = commandsFromTranscript([notice]);
+    expect(filterCommands(commands, "co").map((c) => c.name)).toEqual(["compact", "cost"]);
+    expect(filterCommands(commands, "act").map((c) => c.name)).toEqual(["compact"]);
+  });
+
+  it("replaces only the token under the caret", () => {
+    const token = commandTokenAt("say /co now", 7, 7)!;
+    expect(applyCommand("say /co now", token, "compact")).toEqual({ value: "say /compact now", cursor: 13 });
+    const trailing = commandTokenAt("/co", 3, 3)!;
+    expect(applyCommand("/co", trailing, "compact")).toEqual({ value: "/compact ", cursor: 9 });
+  });
+});
+
+describe("session config", () => {
+  it("orders the menu by category, unknown categories last", () => {
+    const options = [
+      { id: "d", category: null },
+      { id: "b", category: "thought_level" },
+      { id: "a", category: "model" },
+      { id: "c", category: "mode" },
+    ];
+    expect(orderConfigOptions(options).map((o) => o.id)).toEqual(["a", "b", "c", "d"]);
+  });
+});

web/src/components/structured/model.ts

@@ -0,0 +1,369 @@
+// Pure transcript logic for the structured pane (#246) — the decisions
+// docs/STRUCTURED-VIEW.md leaves to a client, kept out of the components so
+// they can be tested without a DOM or a socket. Ported from structured.ts's
+// private helpers and the parts of structuredRender.ts that were data, not
+// markup.
+
+import type {
+  AcpContentBlock,
+  AcpPermissionOption,
+  AcpToolCallContent,
+  ReducedState,
+  StructuredApprovalDecision,
+  TranscriptRow,
+  TranscriptRowKind,
+  TurnMeta,
+} from "../../types.js";
+import { computeDiffLines, diffStats } from "../../structuredDiff.js";
+
+/** Human label behind a `ToolKind`. An unrecognised/absent kind is "Tool" —
+ *  never a blank label. */
+const KIND_LABEL: Record<string, string> = {
+  read: "Read",
+  edit: "Edit",
+  delete: "Delete",
+  move: "Move",
+  search: "Search",
+  execute: "Execute",
+  think: "Think",
+  fetch: "Fetch",
+  switch_mode: "Switch mode",
+};
+
+export function toolKindLabel(kind: string | undefined): string {
+  return (kind && KIND_LABEL[kind]) || "Tool";
+}
+
+/** Split a title into `{label, arg}` when it follows the adapter's own
+ *  `Name(argument)` convention; otherwise the whole title is the arg and the
+ *  tool's `kind` supplies a generic label. Never guesses at a shape the data
+ *  doesn't actually show. */
+export function splitToolTitle(
+  title: string | undefined,
+  name: string | null | undefined,
+  kind: string | undefined,
+): { label: string; arg: string } {
+  const label = name ?? toolKindLabel(kind);
+  if (!title) return { label, arg: "" };
+  const m = /^(\S+)\(([\s\S]*)\)$/.exec(title);
+  if (m) return { label: name ?? m[1], arg: m[2] };
+  return { label, arg: title };
+}
+
+/** Content-block text, or a labelled placeholder for anything that isn't
+ *  text — never dropped silently, never fabricated. */
+export function contentBlockText(block: AcpContentBlock | undefined): string {
+  if (!block) return "";
+  switch (block.type) {
+    case "text":
+      return block.text;
+    case "image":
+      return "[image]";
+    case "audio":
+      return "[audio]";
+    case "resource_link":
+      return `[resource: ${block.name ?? block.uri ?? "linked"}]`;
+    case "resource":
+      return "[resource]";
+    default:
+      return "";
+  }
+}
+
+/** `+added −removed` across every diff block in a tool call's content — real
+ *  derived data, never a fabricated duration. */
+export function toolDiffMeta(content: AcpToolCallContent[]): string {
+  let added = 0;
+  let removed = 0;
+  for (const block of content) {
+    if (block.type !== "diff") continue;
+    const stats = diffStats(computeDiffLines(block.oldText, block.newText));
+    added += stats.added;
+    removed += stats.removed;
+  }
+  return `+${added} −${removed}`;
+}
+
+export function statusMeta(
+  status: string | undefined,
+  hasDiff: boolean,
+): { text: string; kind: string } | null {
+  if (status === "in_progress") return { text: "running", kind: "running" };
+  if (status === "failed") return { text: "failed", kind: "failed" };
+  if (status === "pending" && !hasDiff) return { text: "pending", kind: "pending" };
+  return null;
+}
+
+/** The `maestroTurnMeta` footer a `Notice` row carries when it is a completed,
+ *  cancelled or failed turn's durable footer — `null` for every other notice. */
+export function turnMeta(row: TranscriptRow): TurnMeta | null {
+  if (row.kind !== "notice" || !row.data || typeof row.data !== "object") return null;
+  const value = (row.data as { maestroTurnMeta?: unknown }).maestroTurnMeta;
+  if (!value || typeof value !== "object") return null;
+  const meta = value as Partial<TurnMeta>;
+  if (typeof meta.elapsedMs !== "number" || typeof meta.outcome !== "string") return null;
+  return meta as TurnMeta;
+}
+
+/** Notices the web client consumes as state and omits from the visible
+ *  transcript (docs/STRUCTURED-VIEW.md, "A client decides"). */
+export function isStateOnlyNotice(row: TranscriptRow): boolean {
+  if (row.kind !== "notice" || !row.data || typeof row.data !== "object") return false;
+  const update = (row.data as { sessionUpdate?: string }).sessionUpdate;
+  return update === "available_commands_update" || update === "session_info_update";
+}
+
+/** Which decisions a permission request actually backs, by the
+ *  `PermissionOptionKind` values it offers (docs/STRUCTURED-VIEW.md's
+ *  "Decision mapping"). A decision with no matching option resolves
+ *  `Cancelled` server-side regardless of what the client sent — offering its
+ *  button would let the operator "allow" something that silently no-ops. */
+export function offeredDecisions(options: AcpPermissionOption[]): StructuredApprovalDecision[] {
+  const kinds = new Set(options.map((o) => o.kind));
+  const decisions: StructuredApprovalDecision[] = [];
+  if (kinds.has("allow_once")) decisions.push("allow_once");
+  if (kinds.has("allow_always")) decisions.push("allow_for_session");
+  if (kinds.has("reject_once") || kinds.has("reject_always")) decisions.push("deny");
+  return decisions;
+}
+
+/** The row id a live `pending_approval` names: the newest `Approval` row.
+ *  Only one approval is ever live (docs/STRUCTURED-VIEW.md, "One live
+ *  approval at a time"), so the last one is the pending one. */
+export function pendingApprovalRowId(rows: TranscriptRow[], state: ReducedState): string | null {
+  return state.pending_approval ? lastRowIdOfKind(rows, "approval") : null;
+}
+
+export function lastRowIdOfKind(rows: TranscriptRow[], kind: TranscriptRowKind): string | null {
+  for (let i = rows.length - 1; i >= 0; i--) if (rows[i].kind === kind) return rows[i].id;
+  return null;
+}
+
+export function turnIsActive(state: ReducedState): boolean {
+  return state.turn.responding || state.turn.thinking;
+}
+
+export interface ActivityGroup {
+  /** Header label count — tool rows only, never absorbed text. */
+  toolCount: number;
+  /** Tools plus absorbed intermediate text/approvals, in transcript order. */
+  rows: TranscriptRow[];
+}
+
+/**
+ * Group tool rows (and intermediate agent text / resolved approvals between
+ * them) by turn. An agent_text/agent_thought row is "intermediate" when a tool
+ * row follows it in the same turn — it gets absorbed into the group so the
+ * collapsed block preserves chronological order. Resolved approval rows (not
+ * the currently pending one) are absorbed the same way. The *last* agent text
+ * with no subsequent tool stays standalone (the prominent final answer).
+ *
+ * Returns groups keyed by `turn:<userId>`.
+ */
+export function activityGroupsByTurn(
+  rows: TranscriptRow[],
+  pendingApprovalId: string | null,
+  turnActive: boolean,
+): Map<string, ActivityGroup> {
+  // First: count tools per turn to know which turns qualify for grouping.
+  const toolCounts = new Map<string, number>();
+  let turnId = "before-first-message";
+  for (const row of rows) {
+    if (row.kind === "user") turnId = row.id;
+    if (row.kind !== "tool_call" && row.kind !== "tool_diff") continue;
+    const gid = `turn:${turnId}`;
+    toolCounts.set(gid, (toolCounts.get(gid) ?? 0) + 1);
+  }
+  // Second: build groups with interleaved text for turns with 2+ tools.
+  const groups = new Map<string, ActivityGroup>();
+  turnId = "before-first-message";
+  // Pending rows that might be intermediate (not yet confirmed by a following
+  // tool). If no tool follows, they stay standalone.
+  let pending: TranscriptRow[] = [];
+  let currentGid = `turn:${turnId}`;
+  for (const row of rows) {
+    if (row.kind === "user") {
+      turnId = row.id;
+      currentGid = `turn:${turnId}`;
+      pending = [];
+      continue;
+    }
+    const count = toolCounts.get(currentGid) ?? 0;
+    if (count < 2) continue;
+    const isIntermediateText = row.kind === "agent_text" || row.kind === "agent_thought";
+    const isResolvedApproval = row.kind === "approval" && row.id !== pendingApprovalId;
+    if (isIntermediateText || isResolvedApproval) {
+      pending.push(row);
+      continue;
+    }
+    if (row.kind === "tool_call" || row.kind === "tool_diff") {
+      const group = groups.get(currentGid) ?? { toolCount: count, rows: [] };
+      // Flush any pending rows — a tool follows, so they're intermediate.
+      group.rows.push(...pending);
+      pending = [];
+      group.rows.push(row);
+      groups.set(currentGid, group);
+    }
+  }
+  // A final agent text is the answer, so it stays outside. Thought rows are
+  // working commentary, though: when a turn already has a disclosure they
+  // belong with its activity even if the next tool call has not arrived yet.
+  // While the turn is still live the most recent one stays outside as visible
+  // narration (docs/STRUCTURED-VIEW.md), and is absorbed when the turn ends.
+  const lastGroup = groups.get(currentGid);
+  if (lastGroup && pending.length > 0 && pending.every((row) => row.kind === "agent_thought")) {
+    const absorb = turnActive ? pending.slice(0, -1) : pending;
+    lastGroup.rows.push(...absorb);
+  }
+
+  return groups;
+}
+
+/** One entry of the flattened render list: either a standalone row or a whole
+ *  activity group. */
+export type TranscriptItem =
+  | { type: "row"; row: TranscriptRow }
+  | { type: "group"; id: string; group: ActivityGroup };
+
+/**
+ * The transcript in render order: rows, with each turn's tool activity folded
+ * into a single group item where one exists. Resolved approvals not absorbed
+ * into a group are dropped — the tool row itself already identifies the
+ * action. `plan` rows and state-only notices are dropped too (both clients
+ * omit `Plan` from the transcript). A turn footer only survives as the final
+ * item, so old footers stop reading like transcript content.
+ */
+export function transcriptItems(
+  rows: TranscriptRow[],
+  pendingApprovalId: string | null,
+  turnActive: boolean,
+): TranscriptItem[] {
+  const groups = activityGroupsByTurn(rows, pendingApprovalId, turnActive);
+  const grouped = new Set<string>();
+  for (const group of groups.values()) for (const row of group.rows) grouped.add(row.id);
+
+  const items: TranscriptItem[] = [];
+  let turnId = "before-first-message";
+  const emitted = new Set<string>();
+  for (const row of rows) {
+    if (row.kind === "user") turnId = row.id;
+    const groupId = `turn:${turnId}`;
+    const group = groups.get(groupId);
+    if (group && grouped.has(row.id)) {
+      // The group renders once, at its first member's position.
+      if (!emitted.has(groupId)) {
+        emitted.add(groupId);
+        items.push({ type: "group", id: groupId, group });
+      }
+      continue;
+    }
+    if (row.kind === "plan") continue;
+    if (row.kind === "notice" && isStateOnlyNotice(row)) continue;
+    // A resolved approval outside a group adds nothing the tool row does not
+    // already say. A pending one always renders.
+    if (row.kind === "approval" && row.id !== pendingApprovalId) continue;
+    items.push({ type: "row", row });
+  }
+
+  return items.filter(
+    (item, index) =>
+      !(item.type === "row" && turnMeta(item.row) !== null) || index === items.length - 1,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// composer: `/` command autocomplete off `available_commands_update` notices
+// ---------------------------------------------------------------------------
+
+export interface AvailableCommand {
+  name: string;
+  description: string;
+  input?: { hint?: string };
+}
+
+/** The live command list is whatever the most recent
+ *  `available_commands_update` notice carries (docs/STRUCTURED-VIEW.md). */
+export function commandsFromTranscript(rows: TranscriptRow[]): AvailableCommand[] {
+  for (let i = rows.length - 1; i >= 0; i--) {
+    if (rows[i].kind !== "notice") continue;
+    const data = rows[i].data as { sessionUpdate?: string; availableCommands?: unknown[] } | undefined;
+    if (data?.sessionUpdate !== "available_commands_update") continue;
+    return (data.availableCommands ?? []).flatMap((value) => {
+      if (!value || typeof value !== "object") return [];
+      const command = value as Partial<AvailableCommand>;
+      if (typeof command.name !== "string" || typeof command.description !== "string") return [];
+      return [{ name: command.name, description: command.description, input: command.input }];
+    });
+  }
+  return [];
+}
+
+export interface CommandToken {
+  start: number;
+  end: number;
+  query: string;
+}
+
+/** The whitespace-delimited token under the caret, when it is a `/command`
+ *  being typed. Completing one replaces only that token. */
+export function commandTokenAt(
+  value: string,
+  selectionStart: number,
+  selectionEnd: number,
+): CommandToken | null {
+  if (selectionStart !== selectionEnd) return null;
+  let start = selectionStart;
+  while (start > 0 && !/\s/.test(value[start - 1])) start--;
+  let end = selectionStart;
+  while (end < value.length && !/\s/.test(value[end])) end++;
+  const match = /^\/([^\s/]*)$/.exec(value.slice(start, selectionStart));
+  return match ? { start, end, query: match[1].toLocaleLowerCase() } : null;
+}
+
+/** Substring match, prefix matches first, then alphabetical. */
+export function filterCommands(commands: AvailableCommand[], query: string): AvailableCommand[] {
+  return commands
+    .filter((command) => command.name.toLocaleLowerCase().includes(query))
+    .sort((a, b) => {
+      const aStarts = a.name.toLocaleLowerCase().startsWith(query);
+      const bStarts = b.name.toLocaleLowerCase().startsWith(query);
+      return aStarts === bStarts ? a.name.localeCompare(b.name) : aStarts ? -1 : 1;
+    });
+}
+
+/** Replace the token under the caret with `/name`, returning the new draft and
+ *  where the caret lands. A trailing space is added only when the completion
+ *  ends the draft. */
+export function applyCommand(
+  value: string,
+  token: CommandToken,
+  name: string,
+): { value: string; cursor: number } {
+  const before = value.slice(0, token.start);
+  const after = value.slice(token.end);
+  let replacement = `/${name}`;
+  let cursor = before.length + replacement.length;
+  if (after.length === 0) {
+    replacement += " ";
+    cursor++;
+  } else if (/^[ \t]/.test(after)) {
+    cursor++;
+  }
+  return { value: before + replacement + after, cursor };
+}
+
+// ---------------------------------------------------------------------------
+// session config menu
+// ---------------------------------------------------------------------------
+
+/** Category order the config menu sorts by; anything else lands after. */
+const CONFIG_CATEGORY_ORDER = ["model", "thought_level", "mode", "model_config"];
+
+export function orderConfigOptions<T extends { category?: string | null }>(options: T[]): T[] {
+  return [...options].sort((a, b) => {
+    const rank = (category?: string | null) => CONFIG_CATEGORY_ORDER.indexOf(category ?? "");
+    const aRank = rank(a.category);
+    const bRank = rank(b.category);
+    return (aRank < 0 ? 99 : aRank) - (bRank < 0 ? 99 : bRank);
+  });
+}