test(maestro): cover Codex ACP lifecycle

`command FOO=1 claude` and `nohup FOO=1 claude` are invalid shells (they
exec `FOO=1` as the program, exit 127), but the resolver skipped the
assignment unconditionally after any wrapper. Assignment prefixes are
only real at the start of a simple command or after a wrapper that itself
interprets them as env vars (env, sudo) or a keyword that restarts the
assignment grammar (time) — not after command, nohup, or a package
manager's subcommand, which just exec their next argument as the program.

Attach an accepts_assignment flag to each wrapper transition in both the
Rust and TS resolvers and gate the assignment-skip loop on the flag from
the most recently consumed wrapper. Extends the shared fixture with the
two reported cases plus every other wrapper transition and several nested
combinations (sudo+time valid, sudo+command / command+nohup / time+command
invalid, nohup+env valid) to lock the per-wrapper policy in for both
languages.

Cargo.lock

@@ -1477,6 +1477,7 @@ version = "0.1.0"
 dependencies = [
  "agent-client-protocol",
  "libc",
+ "serde",
  "serde_json",
  "tempfile",
  "thiserror 1.0.69",
@@ -1644,6 +1645,7 @@ dependencies = [
  "tokio",
  "tokio-tungstenite 0.21.0",
  "tracing",
+ "unicode-width",
  "uuid",
  "vt100",
 ]

Cargo.toml

@@ -44,6 +44,7 @@ tokio-util = { version = "0.7", features = ["compat"] }
 toml = "0.8"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+unicode-width = "0.1"
 uuid = { version = "1", features = ["v4", "serde"] }
 ratatui = "0.28"
 vt100 = "0.15"

crates/maestro-acp/Cargo.toml

@@ -10,6 +10,7 @@ description = "ACP client role: one claude-code-acp 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

@@ -42,24 +42,56 @@ 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";
 
@@ -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

@@ -19,6 +19,8 @@ Environment knobs, all optional:
   FAKE_ACP_INIT_FAIL=1    answer `initialize` with a JSON-RPC error
   FAKE_ACP_DELAY_SESSION_NEW_MS=n  wait n milliseconds before answering
                              `session/new`
+  FAKE_ACP_SESSION_NEW_GATE=path  wait for `path` to exist before answering
+                             `session/new`
   FAKE_ACP_EXIT_AFTER_NEW=1  exit 0 right after answering `session/new`
   FAKE_ACP_EXIT_ON_CANCEL=1  exit 0 on `session/cancel` (default: keep running
                              so the SIGTERM path is exercised)
@@ -34,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
 
@@ -76,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):
@@ -133,8 +171,11 @@ for raw in sys.stdin:
             "authMethods": [],
         }})
     elif method == "session/new":
+        gate = os.environ.get("FAKE_ACP_SESSION_NEW_GATE")
+        while gate and not os.path.exists(gate):
+            time.sleep(0.01)
         time.sleep(int(os.environ.get("FAKE_ACP_DELAY_SESSION_NEW_MS", "0")) / 1000)
-        send({"jsonrpc": "2.0", "id": rid, "result": {"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)
@@ -147,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/attach.rs

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

crates/maestro-cli/src/sessions.rs

@@ -6,7 +6,7 @@ use std::io::Write;
 use maestro_protocol::display::abbreviate_dir;
 use maestro_protocol::{
     ActivityState, ClientError, CreateSessionRequest, DaemonClient, DaemonInfo, SendInputRequest,
-    Session, SessionStatus, WorktreeSpec,
+    Session, SessionStatus, SessionView, WorktreeSpec,
 };
 use serde_json::Value;
 
@@ -179,8 +179,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
     }
     writeln!(
         out,
-        "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {}",
-        "ID", "STATUS", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
+        "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {}",
+        "ID", "STATUS", "VIEW", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
     )
     .ok();
     for s in sorted {
@@ -190,6 +190,10 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             SessionStatus::Running => "running",
             SessionStatus::Dead => "dead",
         };
+        let view = match s.view {
+            SessionView::Terminal => "terminal",
+            SessionView::Structured => "structured",
+        };
         let activity = match s.activity {
             ActivityState::Active => "active",
             ActivityState::Idle => "idle",
@@ -207,8 +211,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
         let blocked = blocked_label(s);
         writeln!(
             out,
-            "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {blocked}",
-            s.id, status, activity, dir, command
+            "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {blocked}",
+            s.id, status, view, activity, dir, command
         )
         .ok();
     }
@@ -230,7 +234,7 @@ mod tests {
     use std::path::PathBuf;
 
     use chrono::{TimeZone, Utc};
-    use maestro_protocol::{ActivityState, Session, SessionStatus};
+    use maestro_protocol::{ActivityState, Session, SessionStatus, SessionView};
     use uuid::Uuid;
 
     use super::DaemonInfo;
@@ -286,6 +290,22 @@ mod tests {
         assert!(s.contains("idle"), "{s}");
     }
 
+    #[test]
+    fn table_exposes_terminal_and_structured_views() {
+        let terminal = session("/tmp", "bash", 1);
+        let mut structured = session("/tmp", "claude", 2);
+        structured.view = SessionView::Structured;
+
+        let mut buf = Vec::new();
+        super::print_session_table(&mut buf, &[terminal, structured], &info(""));
+        let out = String::from_utf8(buf).unwrap();
+        let lines: Vec<&str> = out.lines().collect();
+        let header = lines.iter().position(|line| line.contains("VIEW")).unwrap();
+
+        assert!(lines[header + 1].contains("terminal"), "{out}");
+        assert!(lines[header + 2].contains("structured"), "{out}");
+    }
+
     #[test]
     fn live_cwd_overrides_spawn_dir_in_table() {
         let mut s = session("/home/naps/maestro", "bash", 1);

crates/maestro-daemon/src/local_api.rs

@@ -21,12 +21,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, SessionManager};
+use crate::session::{QueueAcpPrompt, SessionError, SessionManager, SetAcpConfig};
 use crate::sidecar::EventCursor;
 
 #[derive(Debug, Clone)]
@@ -70,6 +71,7 @@ pub fn router(state: LocalApiState) -> Router {
         .route(routes::patterns::STRUCTURED_REPLAY, get(structured_replay))
         .route(routes::patterns::STRUCTURED_PROMPT, post(structured_prompt))
         .route(routes::patterns::STRUCTURED_CANCEL, post(structured_cancel))
+        .route(routes::patterns::STRUCTURED_CONFIG, post(structured_config))
         .route(
             routes::patterns::STRUCTURED_APPROVAL,
             post(structured_approval),
@@ -179,6 +181,7 @@ fn session_error_status(code: &str) -> StatusCode {
         // The session outlived its pane: nothing to type into, and nothing
         // the daemon can do about it.
         "not_running" => StatusCode::CONFLICT,
+        "not_terminal" => StatusCode::CONFLICT,
         "shutting_down" => StatusCode::SERVICE_UNAVAILABLE,
         _ => StatusCode::BAD_GATEWAY,
     }
@@ -471,6 +474,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)>,
@@ -534,12 +568,23 @@ async fn attach_ws(
     State(s): State<LocalApiState>,
     ws: axum::extract::WebSocketUpgrade,
 ) -> Result<Response, Response> {
-    let Some((replay, rx)) = s.manager.subscribe_pty_with_replay(id).await else {
-        return Err(error_response(
-            StatusCode::NOT_FOUND,
-            "unknown_session",
-            "no such session on this daemon",
-        ));
+    let (replay, rx) = match s.manager.subscribe_pty_with_replay(id).await {
+        Ok(subscription) => subscription,
+        Err(SessionError::NotFound(_)) => {
+            return Err(error_response(
+                StatusCode::NOT_FOUND,
+                "unknown_session",
+                "no such session on this daemon",
+            ));
+        }
+        Err(error) => {
+            let info = error.to_error_info();
+            return Err(error_response(
+                session_error_status(&info.code),
+                &info.code,
+                &info.message,
+            ));
+        }
     };
     let manager = s.manager.clone();
     Ok(ws.on_upgrade(move |socket| async move {

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};
 
@@ -438,6 +515,16 @@ mod tests {
         .unwrap()
     }
 
+    #[test]
+    fn a_session_update_tag_the_acp_dependency_does_not_know_fails_to_deserialize() {
+        // `SessionUpdate` has no unknown-variant fallback, so this never reaches `Projection::apply`.
+        let result: Result<SessionNotification, _> = serde_json::from_value(serde_json::json!({
+            "sessionId": "acp-1",
+            "update": {"sessionUpdate": "some_future_update_variant"},
+        }));
+        assert!(result.is_err());
+    }
+
     #[test]
     fn folds_content_tool_diff_plan_and_notice_rows() {
         let mut projection = Projection::default();
@@ -486,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();
@@ -604,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!([])
@@ -675,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,
@@ -693,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(
@@ -819,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/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,10 +97,18 @@ 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,
@@ -130,7 +139,11 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
 
     let session = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(
+            cwd.path(),
+            env,
+            "codex --dangerously-bypass-approvals-and-sandbox",
+        ))
         .await
         .expect("create");
 
@@ -215,7 +228,7 @@ 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();
 
@@ -349,12 +362,75 @@ 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");
+
+    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();
@@ -507,7 +583,7 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
 
     let session = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .expect("create");
     let acp_id = session.acp_session_id.clone().expect("acp id");
@@ -621,7 +697,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 {
@@ -716,15 +792,18 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
 
     let session = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .expect("a failed session, not an error");
 
     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
@@ -738,6 +817,28 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
     assert!(!fx.manager.has(session.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 session = fx
+        .manager
+        .create(structured_command(cwd.path(), fake.env(), "opencode"))
+        .await
+        .expect("failed structured session is persisted");
+
+    assert_eq!(session.status, SessionStatus::Dead);
+    let detail = session.activity_detail.expect("selection error");
+    assert!(detail.contains("Claude Code or Codex"), "{detail}");
+    assert!(
+        fake.log().is_empty(),
+        "unsupported command launched an adapter"
+    );
+    fx.manager.kill(session.id, false).await.expect("dismiss");
+}
+
 #[tokio::test]
 async fn kill_sends_cancel_then_sigterm_and_removes_the_sidecar() {
     let fx = DaemonFixture::new();
@@ -950,6 +1051,191 @@ async fn shutdown_waits_for_structured_creation_and_rejects_new_creates() {
     assert_eq!(fake.log().matches("signal SIGTERM").count(), 1);
 }
 
+#[tokio::test]
+async fn structured_handshakes_run_independently() {
+    let fx = DaemonFixture::new();
+    let blocked = Fake::new();
+    let ready = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let gate = cwd.path().join("release-first");
+    let mut blocked_env = blocked.env();
+    blocked_env.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        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;
+
+    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");
+
+    std::fs::write(&gate, b"release").unwrap();
+    let first = first.await.expect("first task").expect("first create");
+    fx.manager.kill(first.id, false).await.expect("kill first");
+    fx.manager
+        .kill(second.id, false)
+        .await
+        .expect("kill second");
+}
+
+#[tokio::test]
+async fn shutdown_waits_for_every_admitted_structured_create() {
+    let fx = DaemonFixture::new();
+    let a = Fake::new();
+    let b = Fake::new();
+    let late = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let gate_a = cwd.path().join("release-a");
+    let gate_b = cwd.path().join("release-b");
+    let mut env_a = a.env();
+    let mut env_b = b.env();
+    env_a.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate_a.to_string_lossy().into_owned(),
+    );
+    env_b.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        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 })
+    };
+    wait_for_async(Duration::from_secs(5), || async {
+        a.log().contains("recv session/new") && b.log().contains("recv session/new")
+    })
+    .await;
+
+    let shutdown = {
+        let manager = fx.manager.clone();
+        tokio::spawn(async move { manager.shutdown().await })
+    };
+    wait_for_async(Duration::from_secs(5), || async {
+        matches!(
+            fx.manager.create(structured(cwd.path(), late.env())).await,
+            Err(maestro_daemon::SessionError::ShuttingDown)
+        )
+    })
+    .await;
+    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");
+    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");
+    shutdown.await.expect("shutdown task");
+
+    wait_for_exit(a.pid()).await;
+    wait_for_exit(b.pid()).await;
+    assert_eq!(
+        fx.manager.status(session_a.id).await,
+        Some(SessionStatus::Dead)
+    );
+    assert_eq!(
+        fx.manager.status(session_b.id).await,
+        Some(SessionStatus::Dead)
+    );
+}
+
+#[tokio::test]
+async fn cancelling_a_structured_handshake_rolls_back_and_settles_admission() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let gate = repo.path().join("release-create");
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
+    env.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate.to_string_lossy().into_owned(),
+    );
+    let request = CreateSessionRequest {
+        view: SessionView::Structured,
+        cwd: repo.path().to_path_buf(),
+        command: "claude".into(),
+        env,
+        metadata: HashMap::new(),
+        worktree: Some(WorktreeSpec {
+            base_repo: repo.path().to_path_buf(),
+            branch: "cancelled-create".into(),
+            create_branch: true,
+        }),
+    };
+
+    let create = {
+        let manager = fx.manager.clone();
+        tokio::spawn(async move { manager.create(request).await })
+    };
+    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)
+        .await
+        .expect("cancelled admission kept shutdown waiting")
+        .expect("shutdown task");
+    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();
+    assert!(
+        std::fs::read_dir(fx.sidecar_dir())
+            .into_iter()
+            .flatten()
+            .all(|entry| !entry
+                .unwrap()
+                .file_name()
+                .to_string_lossy()
+                .starts_with(&id)),
+        "cancelled create left a sidecar artifact"
+    );
+}
+
 #[tokio::test]
 async fn shutdown_drains_final_notifications_to_the_log() {
     let fx = DaemonFixture::new();

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

@@ -1311,6 +1311,39 @@ async fn attach_ws_streams_pty_bytes() {
     assert!(saw_hello, "PTY did not echo through the attach WS");
 }
 
+#[tokio::test]
+async fn pty_routes_reject_structured_sessions_as_not_terminal() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+
+    let response = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/input")))
+        .json(&maestro_protocol::SendInputRequest {
+            text: "ignored".into(),
+            submit: false,
+        })
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = response.json().await.unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+
+    let error = connect_async(ws_url(h.addr, &format!("/api/attach/{id}")))
+        .await
+        .expect_err("structured session must not upgrade to a PTY socket");
+    let tokio_tungstenite::tungstenite::Error::Http(response) = error else {
+        panic!("expected an HTTP handshake rejection, got {error}");
+    };
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let body = response.body().as_deref().expect("ApiError response body");
+    let error: ApiError = serde_json::from_slice(body).unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+}
+
 #[tokio::test]
 async fn attach_ws_for_unknown_session_returns_404() {
     let h = spawn("naps-laptop").await;

crates/maestro-protocol/src/client.rs

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

crates/maestro-protocol/src/display.rs

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

crates/maestro-protocol/src/lib.rs

@@ -824,6 +824,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 +855,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 +882,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")]

crates/maestro-protocol/src/routes.rs

@@ -91,6 +91,11 @@ 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}")
@@ -109,6 +114,7 @@ pub mod patterns {
     pub const STRUCTURED_REPLAY: &str = "/api/sessions/:id/structured/replay";
     pub const STRUCTURED_PROMPT: &str = "/api/sessions/:id/structured/prompt";
     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";
 }
 
@@ -159,6 +165,11 @@ pub fn attach_url(http_base: &str, id: Uuid) -> Result<String, UrlError> {
     Ok(format!("{}{}", ws_base(http_base)?, attach(id)))
 }
 
+/// Full `WS /api/structured/:id` URL for a daemon reachable at `http_base`.
+pub fn structured_url(http_base: &str, id: Uuid) -> Result<String, UrlError> {
+    Ok(format!("{}{}", ws_base(http_base)?, structured(id)))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -208,6 +219,10 @@ mod tests {
             events_url("http://host:7070/").unwrap(),
             "ws://host:7070/api/events"
         );
+        assert_eq!(
+            structured_url("http://host:7070/", id()).unwrap(),
+            "ws://host:7070/api/structured/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
     }
 
     #[test]

crates/maestro-tui/Cargo.toml

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

crates/maestro-tui/src/app.rs

@@ -17,7 +17,10 @@ use std::time::Duration;
 use chrono::Utc;
 use crossterm::event::{Event as CtEvent, EventStream};
 use futures_util::StreamExt;
-use maestro_protocol::{routes, BranchInfo, CreateSessionRequest, DaemonClient, NameBatch};
+use maestro_protocol::{
+    routes, BranchInfo, CreateSessionRequest, DaemonClient, NameBatch, SessionView,
+    StructuredApprovalDecision,
+};
 use ratatui::Terminal;
 use uuid::Uuid;
 
@@ -38,6 +41,8 @@ use crate::render::{draw, RegionMap, RenderInputs};
 use crate::session_task::{SessionInput, SessionTask};
 use crate::sidebar::Sidebar;
 use crate::state::{AppState, Focus, OverlayKind, SidebarItem};
+use crate::structured_pane::StructuredPane;
+use crate::structured_task::{StructuredHandle, StructuredTask};
 use crate::text_input::TextInput;
 use crate::TuiError;
 
@@ -54,6 +59,7 @@ pub struct App {
     home_dir: String,
     catalog: CatalogStore,
     emulators: SessionEmulators,
+    structured: HashMap<Uuid, StructuredHandle>,
     state: AppState,
     help: HelpOverlay,
     chord: ChordState,
@@ -163,6 +169,18 @@ pub enum Effect {
         id: Uuid,
         bytes: Vec<u8>,
     },
+    StructuredPrompt {
+        id: Uuid,
+        prompt: String,
+    },
+    StructuredCancel {
+        id: Uuid,
+    },
+    StructuredApproval {
+        id: Uuid,
+        nonce: String,
+        decision: StructuredApprovalDecision,
+    },
     /// Fetch presets / projects / names for a freshly opened form (#64).
     LoadDraft,
     /// Fast-forward spawn (#67): resolve every default from the daemon and
@@ -214,6 +232,7 @@ impl App {
             home_dir: std::env::var("HOME").unwrap_or_default(),
             catalog,
             emulators: SessionEmulators::default(),
+            structured: HashMap::new(),
             state: AppState::new(),
             draft: None,
             help,
@@ -321,6 +340,11 @@ impl App {
             return Ok(false);
         }
 
+        if let Some(effects) = self.handle_structured_key(&key) {
+            self.perform(effects).await;
+            return Ok(false);
+        }
+
         if let Some(effect) = self.handle_pane_scroll(&key) {
             self.perform(effect.into_iter().collect()).await;
             return Ok(false);
@@ -419,6 +443,44 @@ impl App {
                         let _ = handle.tx.send(SessionInput::Bytes(bytes)).await;
                     }
                 }
+                Effect::StructuredPrompt { id, prompt } => {
+                    if let Err(error) = self.daemon.send_structured_prompt(id, &prompt).await {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle
+                                .state
+                                .lock()
+                                .expect("structured state mutex")
+                                .prompt_failed(prompt, error.to_string());
+                        }
+                    }
+                }
+                Effect::StructuredCancel { id } => {
+                    if let Err(error) = self.daemon.cancel_structured_turn(id).await {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle.state.lock().expect("structured state mutex").error =
+                                Some(error.to_string());
+                        }
+                    }
+                }
+                Effect::StructuredApproval {
+                    id,
+                    nonce,
+                    decision,
+                } => {
+                    if let Err(error) = self
+                        .daemon
+                        .resolve_structured_approval(id, &nonce, decision)
+                        .await
+                    {
+                        if let Some(handle) = self.structured.get(&id) {
+                            handle
+                                .state
+                                .lock()
+                                .expect("structured state mutex")
+                                .approval_failed(&nonce, error.to_string());
+                        }
+                    }
+                }
             }
         }
     }
@@ -563,13 +625,13 @@ impl App {
             Action::OpenCommandBar => effects.extend(self.open_command_bar()),
             // Escape hatch (#156): the literal byte, not the bar.
             Action::SendLiteralCtrlK => {
-                effects.extend(self.forward_to_session(&InputKey::ctrl_char('k')));
+                effects.extend(self.forward_literal_to_terminal(&InputKey::ctrl_char('k')));
             }
             // Escape hatch (#158): the leader's own byte, built from the
             // configured leader rather than a hardcoded key.
             Action::SendLiteralLeader => {
                 let leader = self.cfg.leader.clone();
-                effects.extend(self.forward_to_session(&leader));
+                effects.extend(self.forward_literal_to_terminal(&leader));
             }
             Action::OpenSpawnModal => {
                 self.open_spawn_modal();
@@ -587,7 +649,7 @@ impl App {
                         }
                         // A previewed session is already attached: committing
                         // to it keeps that stream rather than reopening one.
-                        if self.emulators.get(sid).is_none() {
+                        if !self.is_attached(sid) {
                             effects.push(Effect::Attach(sid));
                         }
                     }
@@ -595,6 +657,9 @@ impl App {
                     // preview budget.
                     self.preview_lru.retain(|s| *s != sid);
                     self.state.attach_to_focused(sid);
+                    if self.session_view(sid) == SessionView::Structured {
+                        self.state.mode = Mode::Normal;
+                    }
                 }
             }
             Action::KillHighlighted => {
@@ -663,7 +728,7 @@ impl App {
         self.state.preview = Some(sid);
         // Set outside the input path, so nothing else marks the frame stale.
         self.epoch = self.epoch.wrapping_add(1);
-        let fresh = self.emulators.get(sid).is_none();
+        let fresh = !self.is_attached(sid);
         if fresh {
             self.preview_lru.retain(|s| *s != sid);
             self.preview_lru.push(sid);
@@ -732,15 +797,27 @@ impl App {
 
     /// Open a stream for `sid` if one isn't already running.
     fn attach(&mut self, sid: Uuid) {
-        if self.emulators.get(sid).is_some() {
+        self.attach_with_view(sid, self.session_view(sid));
+    }
+
+    fn attach_with_view(&mut self, sid: Uuid, view: SessionView) {
+        if self.is_attached(sid) {
             return;
         }
-        match self.daemon.attach_url(sid) {
-            Ok(ws_url) => {
-                let handle = SessionTask::spawn(ws_url, 24, 80);
-                self.emulators.insert(sid, handle);
-            }
-            Err(e) => self.state.toast(format!("attach failed: {e}")),
+        match view {
+            SessionView::Terminal => match self.daemon.attach_url(sid) {
+                Ok(ws_url) => {
+                    let handle = SessionTask::spawn(ws_url, 24, 80);
+                    self.emulators.insert(sid, handle);
+                }
+                Err(e) => self.state.toast(format!("attach failed: {e}")),
+            },
+            SessionView::Structured => match self.daemon.structured_url(sid) {
+                Ok(ws_url) => {
+                    self.structured.insert(sid, StructuredTask::spawn(ws_url));
+                }
+                Err(e) => self.state.toast(format!("attach failed: {e}")),
+            },
         }
     }
 
@@ -748,9 +825,26 @@ impl App {
     /// dropping its vt100 parser.
     fn release_session(&mut self, sid: Uuid) {
         self.emulators.remove(sid);
+        if let Some(handle) = self.structured.remove(&sid) {
+            handle.end();
+        }
         self.last_sent_size.remove(&sid);
     }
 
+    fn session_view(&self, sid: Uuid) -> SessionView {
+        self.catalog
+            .snapshot()
+            .sessions
+            .iter()
+            .find(|session| session.id == sid)
+            .map(|session| session.view)
+            .unwrap_or_default()
+    }
+
+    fn is_attached(&self, sid: Uuid) -> bool {
+        self.emulators.get(sid).is_some() || self.structured.contains_key(&sid)
+    }
+
     /// Return the session under the sidebar highlight, falling back to the
     /// first listed session so the user can attach without arrowing first.
     fn pick_sidebar_target(&self) -> Option<Uuid> {
@@ -817,6 +911,16 @@ impl App {
     /// attached to send it to.
     fn forward_to_session(&mut self, key: &InputKey) -> Option<Effect> {
         let sid = self.state.active_session()?;
+        if let Some(handle) = self.structured.get(&sid) {
+            let mut state = handle.state.lock().expect("structured state mutex");
+            if matches!(key, InputKey::Enter) {
+                return state
+                    .begin_prompt()
+                    .map(|prompt| Effect::StructuredPrompt { id: sid, prompt });
+            }
+            state.edit_composer(key);
+            return None;
+        }
         let handle = self.emulators.get(sid)?;
         let bytes = encode_key(key)?;
         handle
@@ -827,6 +931,86 @@ impl App {
         Some(Effect::Forward { id: sid, bytes })
     }
 
+    fn forward_literal_to_terminal(&mut self, key: &InputKey) -> Option<Effect> {
+        let sid = self.state.active_session()?;
+        if self.session_view(sid) == SessionView::Structured {
+            return None;
+        }
+        self.forward_to_session(key)
+    }
+
+    fn handle_structured_key(&mut self, key: &InputKey) -> Option<Vec<Effect>> {
+        if self.state.focus != Focus::Pane || self.state.preview.is_some() {
+            return None;
+        }
+        let sid = self.state.active_session()?;
+        let handle = self.structured.get(&sid)?;
+        let mut state = handle.state.lock().expect("structured state mutex");
+        if self.state.mode == Mode::Insert {
+            if matches!(key, InputKey::Esc) && state.turn_active() {
+                return Some(vec![Effect::StructuredCancel { id: sid }]);
+            }
+            return None;
+        }
+        let effects = match key {
+            InputKey::Char {
+                c: 'j',
+                ctrl: false,
+                alt: false,
+                ..
+            }
+            | InputKey::Down => {
+                state.select(1);
+                Vec::new()
+            }
+            InputKey::Char {
+                c: 'k',
+                ctrl: false,
+                alt: false,
+                ..
+            }
+            | InputKey::Up => {
+                state.select(-1);
+                Vec::new()
+            }
+            InputKey::Enter => {
+                state.toggle_selected();
+                Vec::new()
+            }
+            InputKey::Esc => {
+                if state.turn_active() {
+                    vec![Effect::StructuredCancel { id: sid }]
+                } else {
+                    Vec::new()
+                }
+            }
+            InputKey::Char {
+                c: key @ ('a' | 'A' | 'd'),
+                ctrl: false,
+                alt: false,
+                ..
+            } => state
+                .approval_decision(*key)
+                .map(|(nonce, decision)| Effect::StructuredApproval {
+                    id: sid,
+                    nonce,
+                    decision,
+                })
+                .into_iter()
+                .collect(),
+            InputKey::PageUp => {
+                state.scroll_by(self.pane_page_rows() as isize);
+                Vec::new()
+            }
+            InputKey::PageDown => {
+                state.scroll_by(-(self.pane_page_rows() as isize));
+                Vec::new()
+            }
+            _ => return None,
+        };
+        Some(effects)
+    }
+
     fn pane_page_rows(&self) -> usize {
         self.region
             .pane
@@ -839,6 +1023,14 @@ impl App {
         let Some(sid) = self.state.active_session() else {
             return;
         };
+        if let Some(handle) = self.structured.get(&sid) {
+            handle
+                .state
+                .lock()
+                .expect("structured state mutex")
+                .scroll_by(rows);
+            return;
+        }
         let Some(handle) = self.emulators.get(sid) else {
             return;
         };
@@ -872,6 +1064,14 @@ impl App {
             _ => return None,
         };
         let sid = self.state.active_session()?;
+        if let Some(handle) = self.structured.get(&sid) {
+            handle
+                .state
+                .lock()
+                .expect("structured state mutex")
+                .scroll_by(lines);
+            return Some(None);
+        }
         let handle = self.emulators.get(sid)?;
         let pane = self.region.pane?;
         let parser = handle.screen.lock().expect("vt100 parser mutex");
@@ -1294,7 +1494,10 @@ impl App {
                 }
                 self.draft = None;
                 self.state.complete_spawn(sid);
-                self.attach(sid);
+                if session.view == SessionView::Structured {
+                    self.state.mode = Mode::Normal;
+                }
+                self.attach_with_view(sid, session.view);
             }
             Err(e) => {
                 // A failed POST belongs in the form it came from (#64), not a
@@ -1355,6 +1558,11 @@ impl App {
             self.emulators
                 .get(sid)
                 .map(|h| (sid, h.revision(), h.state()))
+                .or_else(|| {
+                    self.structured
+                        .get(&sid)
+                        .map(|h| (sid, h.revision(), h.connection()))
+                })
         });
         FrameKey {
             catalog: self.catalog.version(),
@@ -1416,6 +1624,17 @@ impl App {
                 focused: matches!(self.state.focus, Focus::Pane) && !previewing,
             })
         });
+        let structured_pane = shown_sid.and_then(|sid| {
+            let handle = self.structured.get(&sid)?;
+            let session = snap.sessions.iter().find(|session| session.id == sid)?;
+            Some(StructuredPane {
+                handle: handle.clone(),
+                focused: matches!(self.state.focus, Focus::Pane) && !previewing,
+                mode: self.state.mode,
+                session_status: session.status,
+                activity_detail: session.activity_detail.clone(),
+            })
+        });
         let pane_title = match shown_sid {
             Some(sid) => {
                 let name = snap
@@ -1439,6 +1658,7 @@ impl App {
             home_dir: &self.home_dir,
             pane_title: &pane_title,
             pane: pane.as_ref(),
+            structured_pane: structured_pane.as_ref(),
             state: &self.state,
             draft: self.draft.as_ref(),
             help: &self.help,
@@ -2805,6 +3025,53 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn create_response_selects_transport_before_catalog_event() {
+        use axum::routing::post;
+        use axum::Json;
+
+        async fn spawn_session(
+            Json(req): Json<CreateSessionRequest>,
+        ) -> Json<maestro_protocol::Session> {
+            let id = match req.view {
+                SessionView::Terminal => Uuid::from_u128(187),
+                SessionView::Structured => Uuid::from_u128(188),
+            };
+            let mut session = test_session(id, req.cwd.to_str().unwrap());
+            session.view = req.view;
+            session.command = req.command;
+            Json(session)
+        }
+
+        let router =
+            axum::Router::new().route(maestro_protocol::routes::SESSIONS, post(spawn_session));
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let base = format!("http://{}", listener.local_addr().unwrap());
+        tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });
+
+        let mut app = make_app_at(&base);
+        let request = |view| CreateSessionRequest {
+            view,
+            cwd: std::path::PathBuf::from("/srv/work"),
+            command: "claude".into(),
+            env: Default::default(),
+            metadata: Default::default(),
+            worktree: None,
+        };
+
+        let structured_id = Uuid::from_u128(188);
+        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());
+
+        let terminal_id = Uuid::from_u128(187);
+        app.submit_spawn(request(SessionView::Terminal)).await;
+        assert!(app.catalog.snapshot().sessions.is_empty());
+        assert!(app.emulators.get(terminal_id).is_some());
+        assert!(!app.structured.contains_key(&terminal_id));
+    }
+
     /// The full data load against a live daemon stub: presets replace the
     /// built-ins, projects land sorted, and the first generated name seeds
     /// the field.
@@ -3697,4 +3964,112 @@ mod tests {
         assert!(app.command_bar.is_none());
         assert!(app.state.overlay().is_none());
     }
+
+    fn structured_app(sid: Uuid) -> App {
+        let mut app = app_with_highlighted_session(sid);
+        let mut session = app.catalog.snapshot().sessions[0].clone();
+        session.view = SessionView::Structured;
+        app.catalog
+            .apply_event(maestro_protocol::CatalogEvent::SessionUpdated { session });
+        app.structured.insert(
+            sid,
+            StructuredHandle::test_handle(crate::structured_task::StructuredState::default()),
+        );
+        app.state.attach_to_focused(sid);
+        app
+    }
+
+    #[tokio::test]
+    async fn session_view_selects_the_structured_connection_and_cleanup_stops_it() {
+        let sid = Uuid::from_u128(141);
+        let mut app = app_with_highlighted_session(sid);
+        let mut session = app.catalog.snapshot().sessions[0].clone();
+        session.view = SessionView::Structured;
+        app.catalog
+            .apply_event(maestro_protocol::CatalogEvent::SessionUpdated { session });
+
+        app.attach(sid);
+        assert!(app.structured.contains_key(&sid));
+        assert!(app.emulators.get(sid).is_none());
+        let handle = app.structured.get(&sid).unwrap().clone();
+        app.release_session(sid);
+        assert_eq!(
+            handle.connection(),
+            crate::session_task::SessionState::Ended
+        );
+    }
+
+    #[test]
+    fn structured_normal_mode_routes_navigation_expansion_and_approval_by_row() {
+        use maestro_protocol::{ReducedState, TranscriptRow, TranscriptRowKind};
+        use serde_json::json;
+
+        let sid = Uuid::from_u128(141);
+        let mut app = structured_app(sid);
+        app.dispatch(Action::AttachHighlighted);
+        assert_eq!(app.state.focus, Focus::Pane);
+        assert_eq!(app.state.mode, Mode::Normal);
+        let handle = app.structured.get(&sid).unwrap().clone();
+        {
+            let mut state = handle.state.lock().unwrap();
+            state.rows = vec![
+                TranscriptRow {
+                    id: "text".into(),
+                    kind: TranscriptRowKind::AgentText,
+                    data: json!({"content":{"type":"text","text":"hello"}}),
+                },
+                TranscriptRow {
+                    id: "approval".into(),
+                    kind: TranscriptRowKind::Approval,
+                    data: json!({"options":[{"kind":"allow_once"}]}),
+                },
+            ];
+            state.selected = Some("text".into());
+            state.reduced = ReducedState {
+                pending_approval: Some(json!({"nonce":"n"})),
+                ..ReducedState::default()
+            };
+        }
+
+        assert_eq!(
+            app.handle_structured_key(&InputKey::char('j')),
+            Some(vec![])
+        );
+        assert_eq!(
+            app.handle_structured_key(&InputKey::char('a')),
+            Some(vec![Effect::StructuredApproval {
+                id: sid,
+                nonce: "n".into(),
+                decision: StructuredApprovalDecision::AllowOnce,
+            }])
+        );
+        assert_eq!(
+            handle.state.lock().unwrap().selected.as_deref(),
+            Some("approval")
+        );
+    }
+
+    #[test]
+    fn structured_insert_mode_edits_submits_and_cancels_without_pty_bytes() {
+        let sid = Uuid::from_u128(141);
+        let mut app = structured_app(sid);
+        assert!(app.emulators.get(sid).is_none());
+        app.forward_to_session(&InputKey::char('h'));
+        app.forward_to_session(&InputKey::char('i'));
+        assert_eq!(
+            app.forward_to_session(&InputKey::Enter),
+            Some(Effect::StructuredPrompt {
+                id: sid,
+                prompt: "hi".into(),
+            })
+        );
+        assert_eq!(
+            app.handle_structured_key(&InputKey::Esc),
+            Some(vec![Effect::StructuredCancel { id: sid }])
+        );
+        assert_eq!(
+            app.forward_literal_to_terminal(&app.cfg.leader.clone()),
+            None
+        );
+    }
 }

crates/maestro-tui/src/draft.rs

@@ -41,8 +41,10 @@ use std::time::{Duration, Instant};
 
 use chrono::{DateTime, Utc};
 use maestro_config::{builtin_presets, custom_preset};
-use maestro_protocol::display::abbreviate_dir;
-use maestro_protocol::{BranchInfo, CreateSessionRequest, Project, SpawnPreset, WorktreeSpec};
+use maestro_protocol::display::{abbreviate_dir, command_tool};
+use maestro_protocol::{
+    BranchInfo, CreateSessionRequest, Project, SessionView, SpawnPreset, WorktreeSpec,
+};
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
@@ -86,9 +88,11 @@ pub enum DraftField {
     /// apply immediately, mirroring the web form's per-click choice.
     WorktreeChoice,
     Name,
-    /// Disclosure collapsing the worktree/branch controls below (#93).
+    /// Disclosure collapsing the optional view and worktree controls below.
     /// Closed by default; Enter / Space toggles.
     Advanced,
+    /// ACP-backed transcript instead of a terminal. Claude Code only.
+    StructuredToggle,
     /// Worktree on/off for this session (#65). Enter / Space toggles.
     WorktreeToggle,
     /// New-vs-existing branch source; Left / Right switches.
@@ -251,6 +255,9 @@ 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.
+    pub structured_view: 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>,
@@ -311,6 +318,7 @@ impl Default for DraftPane {
             name_touched: false,
             worktree_enabled: true,
             advanced_collapsed: true,
+            structured_view: false,
             base_repo: None,
             probed_cwd: None,
             probe_seq: 0,
@@ -348,6 +356,7 @@ impl DraftPane {
             .position(|p| !p.command.is_empty())
             .unwrap_or(0);
         self.apply_seed_command();
+        self.clear_unsupported_structured_view();
     }
 
     /// Land a seeded command on the tile that runs it: its own preset when the
@@ -663,6 +672,22 @@ impl DraftPane {
         }
     }
 
+    fn supports_structured_view(&self) -> bool {
+        command_tool(self.command()) == Some("claude")
+    }
+
+    fn clear_unsupported_structured_view(&mut self) {
+        if !self.supports_structured_view() {
+            self.structured_view = false;
+        }
+    }
+
+    pub fn toggle_structured_view(&mut self) {
+        if self.supports_structured_view() {
+            self.structured_view = !self.structured_view;
+        }
+    }
+
     /// The chosen working directory: a picked project row, else the raw path
     /// input when it holds something.
     pub fn cwd(&self) -> Option<PathBuf> {
@@ -694,7 +719,11 @@ impl DraftPane {
         }
         let worktree = self.build_worktree()?;
         Ok(CreateSessionRequest {
-            view: Default::default(),
+            view: if self.structured_view && self.supports_structured_view() {
+                SessionView::Structured
+            } else {
+                SessionView::Terminal
+            },
             cwd,
             command: command.to_string(),
             env: Default::default(),
@@ -754,6 +783,9 @@ impl DraftPane {
         order.push(DraftField::Name);
         order.push(DraftField::Advanced);
         if !self.advanced_collapsed {
+            if self.supports_structured_view() {
+                order.push(DraftField::StructuredToggle);
+            }
             if !self.cwd_raw_visible && self.selected_group_key.is_some() {
                 order.push(DraftField::WorktreeChoice);
             }
@@ -795,6 +827,7 @@ impl DraftPane {
         }
         self.selected_preset =
             ((self.selected_preset as i32) + delta).rem_euclid(len as i32) as usize;
+        self.clear_unsupported_structured_view();
     }
 
     /// Step-one boxes surviving the type-to-filter, in display order. A
@@ -1001,9 +1034,9 @@ impl DraftPane {
             // Two fields keep their own Enter instead: `DirPicker`, whose
             // highlighted row isn't the picked one until a first Enter chooses
             // it (the next Enter, now that it's active, falls through to
-            // submit); and the disclosure/toggle pair (`Advanced`,
-            // `WorktreeToggle`), which activate on Enter like a button rather
-            // than submitting, same as the web form's own `<button>` controls.
+            // submit); and the disclosure/checkbox fields, which activate on
+            // Enter like buttons rather than submitting, matching the web
+            // form controls.
             InputKey::Enter if self.focused_field == DraftField::DirPicker => {
                 let is_other_row = self.selection() >= self.visible_groups().len();
                 let choose_only =
@@ -1023,6 +1056,10 @@ impl DraftPane {
                 self.toggle_worktree();
                 DraftInputResult::Consumed
             }
+            InputKey::Enter if self.focused_field == DraftField::StructuredToggle => {
+                self.toggle_structured_view();
+                DraftInputResult::Consumed
+            }
             InputKey::Enter => DraftInputResult::Submit,
             InputKey::Char {
                 c: ' ',
@@ -1040,6 +1077,14 @@ impl DraftPane {
                 self.toggle_worktree();
                 DraftInputResult::Consumed
             }
+            InputKey::Char {
+                c: ' ',
+                ctrl: false,
+                ..
+            } if self.focused_field == DraftField::StructuredToggle => {
+                self.toggle_structured_view();
+                DraftInputResult::Consumed
+            }
             InputKey::Up if self.focused_field == DraftField::DirPicker => {
                 self.move_selection(-1);
                 DraftInputResult::Consumed
@@ -1083,7 +1128,10 @@ impl DraftPane {
             other => {
                 match self.focused_field {
                     DraftField::Preset | DraftField::Submit => {}
-                    DraftField::CustomCommand => self.custom_command.handle_key(other),
+                    DraftField::CustomCommand => {
+                        self.custom_command.handle_key(other);
+                        self.clear_unsupported_structured_view();
+                    }
                     // Typing filters the list; the highlight resets to the top
                     // so a narrowed search always starts at its best match.
                     DraftField::DirPicker => {
@@ -1121,9 +1169,9 @@ impl DraftPane {
 
         let show_custom = self.is_custom();
         let show_raw = self.cwd_raw_visible;
-        // The worktree choice step, the worktree toggle and its body all stay
-        // behind the "Advanced options" disclosure (#93): collapsed hides
-        // them, regardless of what they'd otherwise show.
+        let show_structured = !self.advanced_collapsed && self.supports_structured_view();
+        // Optional view and worktree controls stay behind the "Advanced
+        // options" disclosure (#93), regardless of what they'd otherwise show.
         let show_wt_toggle = !self.advanced_collapsed;
         let show_wt_body = show_wt_toggle && self.worktree_body_visible();
         let show_wt_choice =
@@ -1142,6 +1190,7 @@ impl DraftPane {
         let fixed: u16 = 3 /* tiles + dir + name */ + 1 /* advanced header */ + 1 /* spawn */
             + u16::from(show_custom)
             + u16::from(show_raw)
+            + u16::from(show_structured)
             + u16::from(show_wt_toggle)
             + u16::from(show_wt_choice) * wt_choice_capacity
             + u16::from(show_wt_body) * (1 + if self.branch_mode == WorktreeBranchMode::New { 1 } else { branch_rows })
@@ -1161,6 +1210,9 @@ impl DraftPane {
         }
         constraints.push(Constraint::Length(1)); // name
         constraints.push(Constraint::Length(1)); // advanced header
+        if show_structured {
+            constraints.push(Constraint::Length(1));
+        }
         if show_wt_choice {
             constraints.push(Constraint::Length(wt_choice_capacity));
         }
@@ -1359,6 +1411,24 @@ impl DraftPane {
             advanced_row,
         );
 
+        if show_structured {
+            let row = next_row();
+            f.render_widget(
+                Paragraph::new(Line::from(vec![
+                    Span::raw(format!("{:<GUTTER$}", "view:")),
+                    Span::styled(
+                        if self.structured_view {
+                            "[x] structured view"
+                        } else {
+                            "[ ] structured view"
+                        },
+                        field_style(DraftField::StructuredToggle),
+                    ),
+                ])),
+                row,
+            );
+        }
+
         if show_wt_choice {
             // Step two (#96 rule 3): "+ new" first, then the repository's
             // worktrees newest-first.
@@ -1817,6 +1887,188 @@ mod tests {
         assert_eq!(req.cwd, PathBuf::from("/srv/work"));
     }
 
+    #[test]
+    fn structured_view_is_default_off_and_only_visible_for_claude_code() {
+        let mut draft = DraftPane {
+            advanced_collapsed: false,
+            ..DraftPane::default()
+        };
+        assert!(!draft.structured_view);
+        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}");
+
+        draft.toggle_structured_view();
+        assert!(draft.structured_view);
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "opencode");
+        assert!(
+            !draft.structured_view,
+            "a hidden value must not stay checked"
+        );
+        assert!(!draft.field_order().contains(&DraftField::StructuredToggle));
+        let rendered = render_to_string(100, 24, |f| draft.render(f, f.area(), true));
+        assert!(!rendered.contains("structured view"), "{rendered}");
+    }
+
+    #[test]
+    fn structured_view_request_is_guarded_against_a_stale_command() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            structured_view: true,
+            ..DraftPane::default()
+        };
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Structured);
+
+        draft.selected_preset = 1;
+        assert_eq!(draft.command(), "opencode");
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
+    /// A custom command typed into the free-text field, run through the same
+    /// resolver the daemon/web gate uses (`command_tool`, #199): a path, an
+    /// env prefix, or a wrapper still resolves to Claude, so the toggle stays
+    /// offered and the request carries `Structured`; an unrelated program
+    /// does not.
+    #[test]
+    fn structured_view_follows_command_resolution_for_custom_commands() {
+        let cases: &[(&str, bool)] = &[
+            ("claude", true),
+            ("claude --resume", true),
+            ("CLAUDE", true),
+            ("/usr/local/bin/claude -p hi", true),
+            ("./bin/claude", true),
+            ("FOO=1 BAR=2 claude", true),
+            ("npx claude-code", true),
+            ("npx --yes claude-code", true),
+            ("sudo claude", true),
+            ("sudo -u root claude", true),
+            ("env -i claude", true),
+            ("nohup claude", true),
+            ("time claude", true),
+            ("command claude", true),
+            ("pnpm --silent dlx claude-code", true),
+            ("yarn --silent dlx claude-code", true),
+            ("bun x claude-code", true),
+            ("\"/opt/my agent/claude\" --resume", true),
+            ("bash", false),
+            ("opencode", false),
+            ("/usr/local/bin/bash -l", false),
+            // A package-manager wrapper without `dlx`/`x` runs a
+            // `package.json` script, not the package (#199) — must not be
+            // mistaken for a Claude launch.
+            ("pnpm claude", false),
+            ("yarn claude", false),
+            // The daemon's structured-session child, never a valid
+            // user-facing launch form (#199).
+            ("claude-code-acp", false),
+        ];
+        for &(command, supported) in cases {
+            let mut draft = DraftPane {
+                picked_cwd: Some(PathBuf::from("/srv/work")),
+                worktree_enabled: false,
+                advanced_collapsed: false,
+                ..DraftPane::default()
+            };
+            draft.selected_preset = draft.presets.len() - 1;
+            draft.custom_command = crate::text_input::TextInput::with_value(command);
+
+            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:?}"
+            );
+            let view = draft.build_request().unwrap().view;
+            assert_eq!(
+                view,
+                if supported {
+                    SessionView::Structured
+                } else {
+                    SessionView::Terminal
+                },
+                "request view 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.
+    #[test]
+    fn structured_view_follows_command_resolution_for_presets() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            advanced_collapsed: false,
+            ..DraftPane::default()
+        };
+        draft.set_presets(vec![
+            SpawnPreset {
+                id: "claude-wrapped".into(),
+                label: "Claude (npx)".into(),
+                command: "npx claude-code --resume".into(),
+            },
+            SpawnPreset {
+                id: "aider".into(),
+                label: "Aider".into(),
+                command: "aider".into(),
+            },
+        ]);
+
+        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
+        // stale selection instead of letting an invalid request through.
+        draft.cycle_preset(1);
+        assert_eq!(draft.command(), "aider");
+        assert!(!draft.structured_view, "stale selection must clear");
+        assert!(!draft.field_order().contains(&DraftField::StructuredToggle));
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
+    /// Editing the custom-command text away from Claude 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() {
+        let mut draft = DraftPane {
+            picked_cwd: Some(PathBuf::from("/srv/work")),
+            worktree_enabled: false,
+            advanced_collapsed: false,
+            focused_field: DraftField::CustomCommand,
+            ..DraftPane::default()
+        };
+        draft.selected_preset = draft.presets.len() - 1;
+        draft.custom_command = crate::text_input::TextInput::with_value("claude");
+        draft.toggle_structured_view();
+        assert!(draft.structured_view);
+
+        typed(&mut draft, " -p");
+        assert_eq!(draft.command(), "claude -p");
+        assert!(draft.structured_view, "still Claude, selection survives");
+
+        for _ in 0.."claude -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"
+        );
+        assert_eq!(draft.build_request().unwrap().view, SessionView::Terminal);
+    }
+
     #[test]
     fn projects_render_sorted_with_stale_dimmed_and_other_directory_last() {
         let mut draft = DraftPane {

crates/maestro-tui/src/lib.rs

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

crates/maestro-tui/src/render.rs

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

crates/maestro-tui/src/session_task.rs

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

crates/maestro-tui/src/structured_task.rs

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

crates/maestro-tui/tests/structured_http.rs

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

crates/maestro-tui/tests/structured_task_ws.rs

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

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.
 
@@ -37,30 +37,26 @@ ACP handle instead of a tmux pane).
 
 ## 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 set on the spawn request), then
+the daemon's `PATH`, 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 +65,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 +92,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,20 +110,32 @@ 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 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` is the projection's forward-compatibility seam: ACP adds
-notification variants over time, and an unrecognised one becomes a generic
-row instead of being silently dropped or making the daemon reject the whole
-stream. A client that does not know what to do with a `Notice` can render it
-as an opaque, collapsed line — that is a reasonable floor, not a client bug.
+`Notice` covers known-but-unspecialized `SessionUpdate` variants: ones the
+`agent-client-protocol` dependency's schema already deserializes (it
+currently folds `available_commands_update` and `session_info_update`
+there) but the projection's `match` doesn't fold into one of the other
+seven kinds. It is not a wire-level forward-compatibility seam:
+`SessionUpdate` is an internally-tagged enum with no unknown-variant
+fallback, so a `session/update` whose `sessionUpdate` tag this build's
+dependency has never heard of — including a variant gated behind an
+unstable ACP feature this build doesn't enable, which is compiled out of
+the enum entirely — fails to deserialize before the projection ever runs,
+rather than becoming a `Notice`. A genuinely new ACP variant needs the
+`agent-client-protocol` dependency upgraded (and, typically, the projection's
+`match` taught about it) before it can appear on this transcript at all — see
+`projection.rs`'s test asserting that an unrecognised `sessionUpdate` tag is a
+deserialization error, not a `Notice`. A client that does not know what to do
+with a `Notice` can still render it as an opaque, collapsed line — that
+remains a reasonable floor, not a client bug.
 
 Rendering is entirely a client concern. The projection's job stops at
 folding ACP into these eight shapes; markdown formatting, diff rendering,
@@ -135,21 +151,42 @@ 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.
-- What happens to an ACP update variant nobody has taught the daemon about
-  yet (falls back to `Notice` rather than erroring).
+- What happens to an ACP update variant the dependency decodes but nobody has
+  taught the projection to special-case (falls back to `Notice` rather than
+  erroring). A variant the dependency itself can't decode is a deserialization
+  error, not a `Notice` — see [The eight transcript row
+  kinds](#the-eight-transcript-row-kinds).
 - Persistence and replay: what is written to the event log, in what order,
   and how a restart resumes it.
 
 **A client decides:**
 
 - How each row kind is drawn — markdown for `AgentText`/`AgentThought`, a
-  diff view for `ToolDiff`, a tool card for `ToolCall`, a checklist for
-  `Plan`, and a floor presentation for `Notice`.
-- How `responding` vs. `thinking` are distinguished visually, if at all.
+  diff view for `ToolDiff`, a tool card for `ToolCall`, and a floor
+  presentation for `Notice`. `Plan` is the exception: both clients omit it
+  from the transcript; the TUI may show the current plan in its status line,
+  while the web client deliberately has no stats or plan rail.
+- The web client groups two or more tool rows after the same `User` row into
+  one collapsed turn activity block. Opening it reveals independently
+  expandable tool calls, including any raw command, input, output, and diff
+  content the adapter supplied.
+- 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.
@@ -180,8 +217,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
@@ -230,7 +268,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
@@ -272,7 +310,9 @@ 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
+- A 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.
 - Cancel sends `session/cancel`, clears any pending approval as `Cancelled`,
@@ -298,8 +338,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

fixtures/command-resolution.json

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

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

@@ -16,7 +16,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",

web/pnpm-lock.yaml

@@ -20,6 +20,9 @@ importers:
       '@xterm/xterm':
         specifier: ^5.5.0
         version: 5.5.0
+      marked:
+        specifier: ^18.0.11
+        version: 18.0.11
     devDependencies:
       happy-dom:
         specifier: ^20.11.6
@@ -424,6 +427,11 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  marked@18.0.11:
+    resolution: {integrity: sha512-HnslJfsZkRPBDJRHvVtAaWlZHEpSu7u8LgQuJCELjRKuWR+hpq4A7sLq3p8HaI9ypVoXDXxV34CsQJEe1+J5Aw==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
@@ -864,6 +872,8 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  marked@18.0.11: {}
+
   ms@2.1.3: {}
 
   nanoid@3.3.12: {}

web/src/api.ts

@@ -11,6 +11,9 @@ import type {
   Projects,
   RecentDirs,
   Session,
+  StructuredApprovalDecision,
+  StructuredConfigRequest,
+  StructuredPromptRequest,
   Uuid,
 } from "./types.js";
 
@@ -91,6 +94,21 @@ export async function killSession(id: Uuid, force = false): Promise<void> {
   );
 }
 
+/** Change one option advertised by a live ACP session. */
+export async function setStructuredConfig(
+  id: Uuid,
+  req: StructuredConfigRequest,
+): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredConfig(id), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(req),
+    }),
+  );
+}
+
 /** Report whether this client's pane is the one currently showing `id` — not
  * merely highlighted in a sidebar. The daemon uses this to clear an
  * `AwaitingInput` glow once the pane has been looked at long enough
@@ -152,4 +170,44 @@ export async function fetchBranches(path: string): Promise<Branches> {
   return jsonOrError(await fetch(url, { credentials: "same-origin" }));
 }
 
-export { eventsWsUrl } from "./routes.js";
+/** Send a prompt to a structured session's ACP turn (#138). `409
+ * turn_in_flight` when one is already active — the caller reflects that from
+ * `ReducedState.turn` instead of racing this call. */
+export async function sendStructuredPrompt(id: Uuid, prompt: string): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredPrompt(id), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ prompt } satisfies StructuredPromptRequest),
+    }),
+  );
+}
+
+/** Cancel a structured session's active ACP turn (#138). */
+export async function cancelStructuredTurn(id: Uuid): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredCancel(id), { method: "POST", credentials: "same-origin" }),
+  );
+}
+
+/** Answer a pending ACP permission request (#139). Always resolves once the
+ * session itself is a live structured session — a nonce that is unknown or
+ * already consumed still answers `204` (docs/STRUCTURED-VIEW.md), so two
+ * clients racing the same approval never see this reject. */
+export async function resolveStructuredApproval(
+  id: Uuid,
+  nonce: string,
+  decision: StructuredApprovalDecision,
+): Promise<void> {
+  await jsonOrError(
+    await fetch(routes.structuredApproval(id, nonce), {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(decision),
+    }),
+  );
+}
+
+export { eventsWsUrl, structuredWsUrl } from "./routes.js";

web/src/attach.ts

@@ -4,14 +4,16 @@ import { Terminal } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
 
 import { attachWsUrl } from "./routes.js";
-import { escapeHtml } from "./html.js";
 import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "./reconnect.js";
 import { applyModsToChar, cursorSeq, tildeSeq } from "./keys.js";
 import { requestToggleDrawer } from "./drawer.js";
-import { splitCommand, toolIconSvg } from "./toolIcon.js";
+import { paneTitleAttr, paneTitleHtml, type AttachInfo } from "./paneTitle.js";
+import type { PaneConnection } from "./pane.js";
 import type { ClientControl, Uuid } from "./types.js";
 import { WebglPolicy } from "./webglRenderer.js";
 
+export type { AttachInfo } from "./paneTitle.js";
+
 /** One budget for the whole page — see webglRenderer.ts for why contexts are
  *  rationed rather than handed to every connection. */
 const webglPolicy = new WebglPolicy();
@@ -27,25 +29,7 @@ const webglPolicy = new WebglPolicy();
  * session ending) tears the socket down — so switching away and back is
  * instant, with scrollback already in place.
  */
-export interface AttachConnection {
-  readonly sessionId: Uuid;
-  /** The `.attach` element (header + terminal body) to mount into a pane. */
-  readonly el: HTMLElement;
-  /** Becomes the visible view: fit to the pane, focus, sync size.
-   *  `focus: false` mounts without taking the keyboard — what a sidebar
-   *  preview needs, so j/k keeps working while the pane is on screen. */
-  onMount(opts?: { focus?: boolean }): void;
-  /** Parked into the cache: keep streaming, just stop driving focus/resize. */
-  onUnmount(): void;
-  /** Put the keyboard back into this terminal — what leaving the sidebar does. */
-  focusTerminal(): void;
-  /** Type raw bytes straight into the PTY, bypassing the terminal's own key
-   *  handling — the leader's literal Ctrl-K escape hatch
-   *  (docs/COMMAND-BAR.md). */
-  sendInput(data: string): void;
-  /** Fully disconnect: close the WS, dispose the terminal, remove the element. */
-  dispose(): void;
-}
+export interface AttachConnection extends PaneConnection {}
 
 export interface AttachOptions {
   /** Invoked when the user clicks the view's explicit "disconnect" control. */
@@ -59,23 +43,6 @@ export interface AttachOptions {
   shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
 }
 
-/** What the header shows about the session (name / command). Optional — falls
- * back to a short session id when the session isn't known yet. */
-export interface AttachInfo {
-  name: string;
-  command: string;
-}
-
-/** Header echoes the sidebar: the program becomes its tool icon when we have a
- * mark for it and stays as its bare name when we do not. Arguments are
- * dropped, as on the card. */
-function commandFragment(command: string): string {
-  const { tool, program } = splitCommand(command);
-  const icon = tool ? toolIconSvg(tool) : null;
-  const text = icon ? "" : program;
-  return `<span class="at-cmd">${icon ?? ""}${text ? escapeHtml(text) : ""}</span>`;
-}
-
 export function createAttachConnection(
   sessionId: Uuid,
   opts: AttachOptions = {},
@@ -85,15 +52,12 @@ export function createAttachConnection(
   el.className = "attach";
   // Useful identity over a bare UUID: name · command. The full id stays in the
   // tooltip for when you really need it.
-  const titleHtml = info
-    ? `<span class="at-name">${escapeHtml(info.name)}</span>` +
-      (info.command && info.command !== info.name ? commandFragment(info.command) : "")
-    : `session <span class="sid">${escapeHtml(sessionId.slice(0, 8))}</span>`;
-  const titleAttr = info ? `${info.name} · ${info.command}  (${sessionId})` : sessionId;
+  const titleHtml = paneTitleHtml(sessionId, info);
+  const titleAttr = paneTitleAttr(sessionId, info);
   el.innerHTML = `
     <header class="attach-header">
       <button type="button" class="btn btn-ghost btn-icon sessions-btn" aria-label="Show sessions" title="Show sessions">☰</button>
-      <span class="attach-title" title="${escapeHtml(titleAttr)}">${titleHtml}</span>
+      <span class="attach-title" title="${titleAttr}">${titleHtml}</span>
       <span class="attach-state" data-state="connecting">connecting…</span>
       <button class="btn btn-ghost btn-icon disconnect" type="button" aria-label="Disconnect" title="Disconnect this session">⏻</button>
     </header>

web/src/connections.test.ts

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

web/src/connections.ts

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

web/src/daemonLink.test.ts

@@ -130,6 +130,31 @@ describe("DaemonLink", () => {
     expect(link.status().state).toBe("online");
   });
 
+  it("rechecks immediately when the browser returns from the background", async () => {
+    const sched = manual();
+    let reply: DaemonInfo | null = info("aaa", "i1");
+    const link = new DaemonLink({
+      fetchInfo: async () => {
+        if (!reply) throw new Error("down");
+        return reply;
+      },
+      scheduler: sched,
+      reload: () => {},
+    });
+    await link.start();
+
+    reply = null;
+    link.noteDisconnected();
+    sched.run();
+    await Promise.resolve();
+    expect(link.status().state).toBe("down");
+
+    reply = info("aaa", "i1");
+    link.recover();
+    await Promise.resolve();
+    expect(link.status().state).toBe("online");
+  });
+
   it("reloads the page when the daemon comes back on a new commit", async () => {
     const sched = manual();
     const reload = vi.fn();

web/src/daemonLink.ts

@@ -148,6 +148,17 @@ export class DaemonLink {
     void this.probe();
   }
 
+  /**
+   * Recheck liveness after the browser resumes from the background. Mobile
+   * browsers may suspend both WebSocket events and timers while a PWA is
+   * hidden, leaving a stale `down` state after the daemon is already back.
+   */
+  recover(): void {
+    if (this.state === "updating") return;
+    this.noteDisconnected();
+    void this.probe();
+  }
+
   /**
    * One `/api/info` round-trip. Resolves `true` when the daemon answered.
    *

web/src/events.test.ts

@@ -132,6 +132,21 @@ describe("CatalogStore reducer", () => {
 });
 
 describe("CatalogStore reconnect", () => {
+  it("replaces a suspended socket immediately", () => {
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const { store } = storeWith([first, second]);
+    store.start();
+
+    store.reconnect();
+
+    expect(first.closed).toBe(true);
+    second.open();
+    // A late close from the old socket is deliberately ignored.
+    first.drop();
+    expect(store.backoff()).toBe(INITIAL_BACKOFF_MS);
+  });
+
   it("doubles the delay per attempt and caps it", () => {
     const sockets = Array.from({ length: 8 }, () => new FakeSocket());
     const { store, scheduler } = storeWith(sockets);

web/src/events.ts

@@ -59,6 +59,23 @@ export class CatalogStore {
     this.connect();
   }
 
+  /** Replace a socket that may have gone stale while the browser was suspended. */
+  reconnect(): void {
+    if (this.reconnectTimer !== null) {
+      this.scheduler.clearTimer(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      // A close event from the superseded socket must not schedule a second
+      // connection alongside the new one.
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.connect();
+  }
+
   /** Current reconnect delay, for tests asserting the backoff schedule. */
   backoff(): number {
     return this.backoffMs;

web/src/main.ts

@@ -107,6 +107,19 @@ void link.start();
 
 store.start();
 
+// Installed mobile browsers suspend timers and WebSockets in the background.
+// Replacing the socket on return avoids leaving the restart overlay up after a
+// transient lost connection has already recovered.
+function recoverFromBackground(): void {
+  if (document.visibilityState !== "visible") return;
+  link.recover();
+  store.reconnect();
+}
+
+document.addEventListener("visibilitychange", recoverFromBackground);
+window.addEventListener("pageshow", recoverFromBackground);
+window.addEventListener("online", recoverFromBackground);
+
 // Dev-only: `?mock` seeds a representative catalog so the UI can be reviewed
 // without a running daemon. Stripped from production builds by Vite.
 if (import.meta.env.DEV && location.search.includes("mock")) {
@@ -172,6 +185,7 @@ const pool = new ConnectionPool({
   onRequestClose: (id) => closePane(id),
   onClosed: (id) => closePane(id),
   shouldReconnect: (id, code) => shouldRetryClose(id, code, store.snapshot().sessions),
+  store,
 });
 
 // Session death used to reach the UI on two uncoordinated channels — the row
@@ -209,7 +223,7 @@ function scheduleSave(): void {
 
 function infoFor(sessionId: string) {
   const s = store.snapshot().sessions.get(sessionId);
-  return s ? { name: sessionName(s), command: s.command } : undefined;
+  return s ? { name: sessionName(s), command: s.command, view: s.view } : undefined;
 }
 
 /** Drive the shell's responsive layout off whether any pane is open. */

web/src/pane.ts

@@ -0,0 +1,26 @@
+// Shared shape a mounted pane connection satisfies, whatever session view is
+// behind it — what ConnectionPool needs to mount/park/dispose a pane without
+// caring whether it holds an xterm attach (attach.ts) or a structured
+// transcript (structured.ts).
+
+import type { Uuid } from "./types.js";
+
+export interface PaneConnection {
+  readonly sessionId: Uuid;
+  /** The element to mount into a pane. */
+  readonly el: HTMLElement;
+  /** Becomes the visible view: fit/focus/sync as the connection needs.
+   *  `focus: false` mounts without taking the keyboard (a sidebar preview). */
+  onMount(opts?: { focus?: boolean }): void;
+  /** Parked into the hidden cache: keep streaming, stop driving focus/sizing. */
+  onUnmount(): void;
+  /** Put the keyboard into this pane's primary input — the terminal for an
+   *  attach connection, the composer for a structured one. */
+  focusTerminal(): void;
+  /** Raw bytes into a PTY, bypassing normal key handling (the leader's
+   *  literal-byte escape hatch, docs/COMMAND-BAR.md). A structured connection
+   *  has no PTY, so this is a no-op there. */
+  sendInput(data: string): void;
+  /** Fully disconnect and remove the element. */
+  dispose(): void;
+}

web/src/paneTitle.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { paneTitleAttr, paneTitleHtml } from "./paneTitle.js";
+
+describe("paneTitleHtml", () => {
+  it("falls back to a short session id when there is no info yet", () => {
+    expect(paneTitleHtml("abcdef12-3456-7890-abcd-ef1234567890")).toContain("abcdef12");
+  });
+
+  it("shows the name alone when command matches it", () => {
+    const html = paneTitleHtml("s1", { name: "claude", command: "claude" });
+    expect(html).toContain("claude");
+    expect(html).not.toContain("at-cmd");
+  });
+
+  it("escapes a name that looks like markup", () => {
+    const html = paneTitleHtml("s1", { name: "<img onerror=x>", command: "claude" });
+    expect(html).not.toContain("<img");
+  });
+});
+
+describe("paneTitleAttr", () => {
+  it("escapes the attribute form too", () => {
+    const attr = paneTitleAttr("s1", { name: '"quoted"', command: "claude" });
+    expect(attr).not.toContain('"quoted"');
+    expect(attr).toContain("&quot;quoted&quot;");
+  });
+});

web/src/paneTitle.ts

@@ -0,0 +1,36 @@
+// Pane header title: name/command echoing the sidebar card, shared by the
+// xterm attach view (attach.ts) and the structured transcript view
+// (structured.ts) so both panes read identically.
+
+import { escapeHtml } from "./html.js";
+import { splitCommand, toolIconSvg } from "./toolIcon.js";
+import type { SessionView, Uuid } from "./types.js";
+
+/** What a pane header shows about its session. Falls back to a short session
+ * id when the session isn't known yet. */
+export interface AttachInfo {
+  name: string;
+  command: string;
+  /** Which connection kind to mount (#140). Absent/`"Terminal"` mounts the
+   * xterm attach; `"Structured"` mounts the transcript view. */
+  view?: SessionView;
+}
+
+function commandFragment(command: string): string {
+  const { tool, program } = splitCommand(command);
+  const icon = tool ? toolIconSvg(tool) : null;
+  const text = icon ? "" : program;
+  return `<span class="at-cmd">${icon ?? ""}${text ? escapeHtml(text) : ""}</span>`;
+}
+
+export function paneTitleHtml(sessionId: Uuid, info?: AttachInfo): string {
+  return info
+    ? `<span class="at-name">${escapeHtml(info.name)}</span>` +
+        (info.command && info.command !== info.name ? commandFragment(info.command) : "")
+    : `session <span class="sid">${escapeHtml(sessionId.slice(0, 8))}</span>`;
+}
+
+/** Attribute-safe (`title="..."`) form of the same identity. */
+export function paneTitleAttr(sessionId: Uuid, info?: AttachInfo): string {
+  return escapeHtml(info ? `${info.name} · ${info.command}  (${sessionId})` : sessionId);
+}

web/src/routes.ts

@@ -37,6 +37,32 @@ export function sessionFocus(id: Uuid): string {
   return `${session(id)}/focus`;
 }
 
+/** `WS /api/structured/:id` — transcript/state snapshots and live deltas. */
+export function structured(id: Uuid): string {
+  return `${API_PREFIX}/structured/${encodeURIComponent(id)}`;
+}
+
+/** `POST /api/sessions/:id/structured/prompt` — send an ACP prompt. */
+export function structuredPrompt(id: Uuid): string {
+  return `${session(id)}/structured/prompt`;
+}
+
+/** `POST /api/sessions/:id/structured/cancel` — cancel an ACP turn. */
+export function structuredCancel(id: Uuid): string {
+  return `${session(id)}/structured/cancel`;
+}
+
+/** `POST /api/sessions/:id/structured/config` — change an ACP session option. */
+export function structuredConfig(id: Uuid): string {
+  return `${session(id)}/structured/config`;
+}
+
+/** `POST /api/sessions/:id/structured/approvals/:nonce` — answer a permission
+ * request. */
+export function structuredApproval(id: Uuid, nonce: string): string {
+  return `${session(id)}/structured/approvals/${encodeURIComponent(nonce)}`;
+}
+
 /** Append the `path` query parameter `DIRS` and `GITROOT` accept. */
 export function withPathQuery(route: string, value: string): string {
   return `${route}?${PATH_QUERY}=${encodeURIComponent(value)}`;
@@ -55,3 +81,7 @@ export function eventsWsUrl(): string {
 export function attachWsUrl(id: Uuid): string {
   return `${wsBase()}${attach(id)}`;
 }
+
+export function structuredWsUrl(id: Uuid): string {
+  return `${wsBase()}${structured(id)}`;
+}

web/src/spawnForm.test.ts

@@ -6,6 +6,7 @@ const base: SpawnFormValues = {
   command: "claude",
   cwd: "/home/user/project",
   name: "amber-fox",
+  structuredView: false,
   worktreeEnabled: false,
   worktreeBranch: "",
   worktreeBranchMode: "new",
@@ -25,6 +26,22 @@ describe("buildSpawnRequest", () => {
     expect(res).toEqual({ req: { cwd: base.cwd, command: base.command, metadata: {} } });
   });
 
+  it("requests structured view only for Claude Code", () => {
+    expect(buildSpawnRequest({ ...base, structuredView: true }, null)).toEqual({
+      req: {
+        cwd: base.cwd,
+        command: "claude",
+        metadata: { name: "amber-fox" },
+        view: "Structured",
+      },
+    });
+    expect(
+      buildSpawnRequest({ ...base, command: "opencode", structuredView: true }, null),
+    ).toEqual({
+      req: { cwd: base.cwd, command: "opencode", metadata: { name: "amber-fox" } },
+    });
+  });
+
   it("attaches a trimmed branch when worktree is enabled, and always cleans up", () => {
     const res = buildSpawnRequest(
       { ...base, worktreeEnabled: true, worktreeBranch: "  feat/foo  " },

web/src/spawnForm.ts

@@ -11,6 +11,7 @@ import { attachDirAutocomplete } from "./dirAutocomplete.js";
 import { parentDir } from "./paths.js";
 import { filterProjects, groupProjects, isStale, sortProjects } from "./projectList.js";
 import type { ProjectGroup } from "./projectList.js";
+import { splitCommand } from "./toolIcon.js";
 import { abbreviateCwd } from "./types.js";
 import type { BranchInfo, CreateSessionRequest, Project, Session, SpawnPreset } from "./types.js";
 
@@ -40,6 +41,7 @@ export interface SpawnFormValues {
   command: string;
   cwd: string;
   name: string;
+  structuredView: boolean;
   worktreeEnabled: boolean;
   worktreeBranch: string;
   worktreeBranchEdited: boolean;
@@ -66,6 +68,10 @@ export function buildSpawnRequest(
     metadata,
   };
 
+  if (values.structuredView && splitCommand(values.command).tool === "claude") {
+    req.view = "Structured";
+  }
+
   if (values.worktreeEnabled) {
     const mode = values.worktreeBranchMode ?? "new";
     const branch = values.worktreeBranch.trim();
@@ -153,6 +159,10 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
         <span class="wt-summary"></span>
       </button>
       <div class="wt-collapsible" hidden>
+        <label class="row-inline structured-view" hidden>
+          <input type="checkbox" name="structured_view" />
+          Structured view
+        </label>
         <div class="field wt-step" hidden>
           <span class="field-label">Worktree</span>
           <div class="picker wt-choices"></div>
@@ -203,6 +213,8 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
   const wtChoices = form.querySelector(".wt-choices") as HTMLElement;
   const cwdRawWrap = form.querySelector(".cwd-raw-wrap") as HTMLElement;
   const cwdRaw = form.querySelector(".cwd-raw") as HTMLInputElement;
+  const structuredWrap = form.querySelector(".structured-view") as HTMLElement;
+  const structuredView = form.querySelector("input[name=structured_view]") as HTMLInputElement;
   const wtEnabled = form.querySelector("input[name=worktree_enabled]") as HTMLInputElement;
   const wtToggle = form.querySelector(".wt-toggle") as HTMLButtonElement;
   const wtCollapsible = form.querySelector(".wt-collapsible") as HTMLElement;
@@ -248,6 +260,7 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
       command,
       cwd,
       name: nameInput.value,
+      structuredView: structuredView.checked,
       worktreeEnabled: wtEnabled.checked,
       worktreeBranch: branchValue(),
       worktreeBranchEdited: branchEdited,
@@ -317,6 +330,7 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
     } else {
       command = preset!.command;
     }
+    updateStructuredAvailability();
     for (const tile of cmdTiles.querySelectorAll(".tile")) {
       tile.classList.toggle("is-active", (tile as HTMLElement).dataset.id === id);
     }
@@ -354,10 +368,19 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
   // operator has already touched (#76).
   let commandTouched = false;
 
+  function updateStructuredAvailability(): void {
+    const supported = splitCommand(command).tool === "claude";
+    structuredWrap.hidden = !supported;
+    if (!supported) structuredView.checked = false;
+  }
+
+  structuredView.addEventListener("change", emit);
+
   cmdRaw.addEventListener("input", () => {
     if (selectedPresetId === "custom" || presets.find((p) => p.id === selectedPresetId)?.command === "") {
       commandTouched = true;
       command = cmdRaw.value.trim();
+      updateStructuredAvailability();
       emit();
     }
   });
@@ -844,10 +867,11 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
     if (e.key !== "Enter" || e.defaultPrevented) return;
     const target = e.target as HTMLElement;
 
-    if (target === wtEnabled) {
+    if (target === wtEnabled || target === structuredView) {
       e.preventDefault();
-      wtEnabled.checked = !wtEnabled.checked;
-      wtEnabled.dispatchEvent(new Event("change"));
+      const checkbox = target as HTMLInputElement;
+      checkbox.checked = !checkbox.checked;
+      checkbox.dispatchEvent(new Event("change"));
       return;
     }
 
@@ -885,6 +909,7 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
         command,
         cwd,
         name: nameInput.value,
+        structuredView: structuredView.checked,
         worktreeEnabled: wtEnabled.checked,
         worktreeBranch: branchValue(),
         worktreeBranchEdited: branchEdited,

web/src/spawnFormStructured.test.ts

@@ -0,0 +1,108 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createSpawnForm, type SpawnFormHandle } from "./spawnForm.js";
+
+function stubApi(): RequestInit[] {
+  const sessionRequests: RequestInit[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.includes("/api/sessions") && init?.method === "POST") {
+        sessionRequests.push(init);
+        return new Response(JSON.stringify({ id: "s1", command: "claude", cwd: "/srv/work" }), {
+          status: 200,
+        });
+      }
+      if (url.includes("/api/info")) {
+        return new Response(
+          JSON.stringify({ hostname: "h", version: "0", home_dir: "/home/user" }),
+          { status: 200 },
+        );
+      }
+      if (url.includes("/api/names")) {
+        return new Response(JSON.stringify({ names: ["amber-fox"] }), { status: 200 });
+      }
+      return new Response(JSON.stringify([]), { status: 200 });
+    }),
+  );
+  return sessionRequests;
+}
+
+describe("spawn form structured view", () => {
+  let handle: SpawnFormHandle | null = null;
+
+  async function drain(): Promise<void> {
+    for (let i = 0; i < 20; i++) await Promise.resolve();
+  }
+
+  afterEach(async () => {
+    handle?.destroy();
+    handle = null;
+    await drain();
+    vi.unstubAllGlobals();
+  });
+
+  it("is default-off and shown only for the resolved Claude Code command", async () => {
+    stubApi();
+    handle = createSpawnForm({ onSuccess() {} });
+    document.body.appendChild(handle.el);
+    await drain();
+
+    const wrap = handle.el.querySelector<HTMLElement>(".structured-view")!;
+    const checkbox = wrap.querySelector<HTMLInputElement>("input")!;
+    const disclosure = handle.el.querySelector<HTMLElement>(".wt-collapsible")!;
+    expect(disclosure.hidden).toBe(true);
+    handle.el.querySelector<HTMLButtonElement>(".wt-toggle")!.click();
+    expect(disclosure.hidden).toBe(false);
+    expect(wrap.hidden).toBe(false);
+    expect(checkbox.checked).toBe(false);
+
+    handle.el.querySelector<HTMLButtonElement>('[data-id="opencode"]')!.click();
+    expect(wrap.hidden).toBe(true);
+
+    handle.el.querySelector<HTMLButtonElement>('[data-id="claude"]')!.click();
+    expect(wrap.hidden).toBe(false);
+  });
+
+  it("clears a checked value when the command changes away from Claude Code", async () => {
+    stubApi();
+    handle = createSpawnForm({ onSuccess() {} });
+    document.body.appendChild(handle.el);
+    await drain();
+
+    const checkbox = handle.el.querySelector<HTMLInputElement>("input[name=structured_view]")!;
+    checkbox.click();
+    expect(checkbox.checked).toBe(true);
+
+    const custom = handle.el.querySelector<HTMLButtonElement>('[data-id="custom"]')!;
+    custom.click();
+    const command = handle.el.querySelector<HTMLInputElement>(".cmd-raw")!;
+    command.value = "opencode";
+    command.dispatchEvent(new Event("input"));
+
+    expect(checkbox.closest<HTMLElement>(".structured-view")!.hidden).toBe(true);
+    expect(checkbox.checked).toBe(false);
+  });
+
+  it("emits Structured in the submitted request when selected", async () => {
+    const requests = stubApi();
+    handle = createSpawnForm({
+      seed: { cwd: "/srv/work", cwdRawVisible: true, worktreeEnabled: false },
+      onSuccess() {},
+    });
+    document.body.appendChild(handle.el);
+    await drain();
+
+    handle.el.querySelector<HTMLInputElement>("input[name=structured_view]")!.click();
+    handle.el.requestSubmit();
+    await drain();
+
+    expect(requests).toHaveLength(1);
+    expect(JSON.parse(String(requests[0].body))).toMatchObject({
+      command: "claude",
+      view: "Structured",
+    });
+  });
+});

web/src/structured.ts

@@ -0,0 +1,957 @@
+// A single live structured session: a transcript bound to the
+// daemon's `WS /api/structured/:id` (#140). Mirrors attach.ts's contract —
+// decoupled from the UI, streaming whether or not mounted, torn down only by
+// `dispose()` — but the wire is JSON rows, not PTY bytes, and every connect
+// (fresh or reconnect) resends the *whole* transcript rather than resuming a
+// cursor (docs/STRUCTURED-VIEW.md), so a snapshot always replaces state
+// wholesale instead of being merged into what came before.
+
+import {
+  cancelStructuredTurn,
+  resolveStructuredApproval,
+  sendStructuredPrompt,
+  setStructuredConfig,
+  structuredWsUrl,
+} from "./api.js";
+import { requestToggleDrawer } from "./drawer.js";
+import type { CatalogStore } from "./events.js";
+import { paneTitleAttr, paneTitleHtml, type AttachInfo } from "./paneTitle.js";
+import type { PaneConnection } from "./pane.js";
+import { INITIAL_RECONNECT_MS, MAX_RECONNECT_MS } from "./reconnect.js";
+import {
+  buildToolGroup,
+  buildTranscriptRow,
+  formatContextTokens,
+  formatElapsed,
+} from "./structuredRender.js";
+import type {
+  AcpSessionConfigChoice,
+  AcpSessionConfigOption,
+  ReducedState,
+  StructuredApprovalDecision,
+  StructuredEvent,
+  TranscriptDelta,
+  TranscriptRow,
+  TranscriptRowKind,
+  Uuid,
+} from "./types.js";
+
+export interface StructuredOptions {
+  onRequestClose?: (sessionId: Uuid) => void;
+  onClosed?: (sessionId: Uuid) => void;
+  shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
+}
+
+/** Injectable so tests can drive the socket without a daemon — the same seam
+ *  `CatalogStore` uses (events.ts). */
+export type StructuredSocketFactory = (sessionId: Uuid) => WebSocket;
+
+const idleTurn = (): ReducedState["turn"] => ({
+  responding: false,
+  thinking: false,
+  active_tool_calls: [],
+});
+
+interface AvailableCommand {
+  name: string;
+  description: string;
+  input?: { hint?: string };
+}
+
+interface CommandToken {
+  start: number;
+  end: number;
+  query: string;
+}
+
+export function createStructuredConnection(
+  sessionId: Uuid,
+  opts: StructuredOptions = {},
+  info?: AttachInfo,
+  _store?: CatalogStore,
+  socketFactory: StructuredSocketFactory = (id) => new WebSocket(structuredWsUrl(id)),
+): PaneConnection {
+  const el = document.createElement("div");
+  el.className = "attach structured";
+  el.innerHTML = `
+    <header class="attach-header">
+      <button type="button" class="btn btn-ghost btn-icon sessions-btn" aria-label="Show sessions" title="Show sessions">☰</button>
+      <span class="attach-title" title="${paneTitleAttr(sessionId, info)}">${paneTitleHtml(sessionId, info)}</span>
+      <span class="attach-state" data-state="connecting">connecting…</span>
+      <button class="btn btn-ghost btn-icon disconnect" type="button" aria-label="Disconnect" title="Disconnect this session">⏻</button>
+    </header>
+    <div class="structured-body">
+      <div class="structured-main">
+        <div class="structured-scroll">
+          <div class="structured-rows"></div>
+        </div>
+        <div class="structured-activity" role="status" aria-live="polite" hidden>
+          <span class="structured-activity-pulse" aria-hidden="true"></span>
+          <span class="structured-activity-text">Thinking</span>
+        </div>
+        <form class="structured-composer">
+          <div class="structured-input-wrap">
+            <div id="structured-command-menu-${sessionId}" class="structured-command-menu"
+              role="listbox" hidden></div>
+            <textarea class="structured-input" rows="1" placeholder="Reply, or / for commands…"
+              autocomplete="off" aria-autocomplete="list" aria-expanded="false"
+              aria-controls="structured-command-menu-${sessionId}"></textarea>
+          </div>
+          <div class="structured-config" hidden>
+            <button type="button" class="structured-config-trigger" aria-haspopup="true"
+              aria-expanded="false" aria-label="Session settings" title="Session settings">
+              <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 7h10M18 7h2M4 17h2M10 17h10M14 4v6M6 14v6"/></svg>
+            </button>
+            <div class="structured-config-menu" role="group" aria-label="Session settings" hidden></div>
+          </div>
+          <button type="submit" class="btn btn-primary 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>
+          <button type="button" class="btn structured-cancel" hidden>Cancel turn</button>
+        </form>
+      </div>
+    </div>
+  `;
+
+  const stateEl = el.querySelector(".attach-state") as HTMLSpanElement;
+  const configEl = el.querySelector(".structured-config") as HTMLDivElement;
+  const configTrigger = el.querySelector(".structured-config-trigger") as HTMLButtonElement;
+  const configMenu = el.querySelector(".structured-config-menu") as HTMLDivElement;
+  const disconnectBtn = el.querySelector(".disconnect") as HTMLButtonElement;
+  const scrollEl = el.querySelector(".structured-scroll") as HTMLDivElement;
+  const rowsEl = el.querySelector(".structured-rows") as HTMLDivElement;
+  const activityEl = el.querySelector(".structured-activity") as HTMLDivElement;
+  const activityText = el.querySelector(".structured-activity-text") as HTMLSpanElement;
+  const composerForm = el.querySelector(".structured-composer") as HTMLFormElement;
+  const commandMenu = el.querySelector(".structured-command-menu") as HTMLDivElement;
+  const input = el.querySelector(".structured-input") as HTMLTextAreaElement;
+  const sendBtn = el.querySelector(".structured-send") as HTMLButtonElement;
+  const cancelBtn = el.querySelector(".structured-cancel") as HTMLButtonElement;
+
+  disconnectBtn.addEventListener("click", () => opts.onRequestClose?.(sessionId));
+  // Mobile-only (CSS hides it on desktop, where the sidebar is always in
+  // view): the session list is an off-canvas drawer and this opens it —
+  // same control attach.ts's terminal header carries.
+  (el.querySelector(".sessions-btn") as HTMLElement).addEventListener("click", () =>
+    requestToggleDrawer(),
+  );
+
+  const setConnState = (text: string, kind: "connecting" | "open" | "closed" | "error") => {
+    stateEl.textContent = text;
+    stateEl.dataset.state = kind;
+  };
+
+  // ---- transcript state: mirrors the daemon's own Projection shape (id ->
+  // index, patched in place) so a Patch never needs to search the array. ----
+  let rows: TranscriptRow[] = [];
+  const rowIndex = new Map<string, number>();
+  const rowEls = new Map<string, HTMLElement>();
+  const expandedRowIds = new Set<string>();
+  const expandedGroupIds = new Set<string>();
+  const groupEls = new Map<string, HTMLElement>();
+  let state: ReducedState = { turn: idleTurn() };
+  let pendingApprovalRowId: string | null = null;
+  let availableCommands: AvailableCommand[] = [];
+  let configBusy = false;
+  let filteredCommands: AvailableCommand[] = [];
+  let activeCommandIndex = -1;
+  let submissionGeneration = 0;
+  let awaitingBeginGeneration: number | null = null;
+  let acceptedSubmission: { generation: number; socketGeneration: number } | null = null;
+  let socketGeneration = 0;
+  let stateSocketGeneration = 0;
+  let disposed = false;
+  let optimisticTurnStartedAt: number | null = null;
+  let activityTimer: number | null = null;
+
+  // Within 64px, wheel and touch imprecision should still count as following.
+  const FOLLOW_BOTTOM_THRESHOLD_PX = 64;
+  let followingBottom = true;
+  let receivedSnapshot = false;
+  let scrollWorkActive = true;
+  let parkedScrollTop: number | null = null;
+  let scrollFrame: number | null = null;
+  let pendingScroll: { top: number; follow: boolean } | null = null;
+
+  function cancelScrollFrame(): void {
+    if (scrollFrame !== null) window.cancelAnimationFrame(scrollFrame);
+    scrollFrame = null;
+    pendingScroll = null;
+  }
+
+  function beginTranscriptLayout(forceBottom = false): void {
+    if (!scrollWorkActive || disposed) return;
+    if (pendingScroll) {
+      if (forceBottom) pendingScroll.follow = true;
+      return;
+    }
+    pendingScroll = {
+      top: scrollEl.scrollTop,
+      follow: forceBottom || followingBottom,
+    };
+  }
+
+  function finishTranscriptLayout(): void {
+    if (!scrollWorkActive || disposed || !pendingScroll || scrollFrame !== null) return;
+    scrollFrame = window.requestAnimationFrame(() => {
+      scrollFrame = null;
+      const pending = pendingScroll;
+      pendingScroll = null;
+      if (!pending || disposed || !scrollWorkActive) return;
+      scrollEl.scrollTop = pending.follow
+        ? Math.max(0, scrollEl.scrollHeight - scrollEl.clientHeight)
+        : pending.top;
+    });
+  }
+
+  function updateTranscriptLayout(update: () => void, forceBottom = false): void {
+    beginTranscriptLayout(forceBottom);
+    update();
+    finishTranscriptLayout();
+  }
+
+  function onTranscriptScroll(): void {
+    const distance = scrollEl.scrollHeight - scrollEl.clientHeight - scrollEl.scrollTop;
+    followingBottom = distance <= FOLLOW_BOTTOM_THRESHOLD_PX;
+    cancelScrollFrame();
+  }
+
+  function onTranscriptClick(event: Event): void {
+    if ((event.target as Element | null)?.closest(".st-tool-head, .st-tool-group-head")) {
+      beginTranscriptLayout();
+    }
+  }
+
+  scrollEl.addEventListener("scroll", onTranscriptScroll);
+  scrollEl.addEventListener("click", onTranscriptClick, true);
+
+  function lastRowIdOfKind(kind: TranscriptRowKind): string | null {
+    for (let i = rows.length - 1; i >= 0; i--) if (rows[i].kind === kind) return rows[i].id;
+    return null;
+  }
+
+  function approvalStateFor(row: TranscriptRow) {
+    if (row.kind !== "approval") return undefined;
+    return {
+      pending: row.id === pendingApprovalRowId,
+      onDecide: (decision: StructuredApprovalDecision) => decide(row.id, decision),
+    };
+  }
+
+  async function decide(rowId: string, decision: StructuredApprovalDecision): Promise<void> {
+    const nonce = state.pending_approval?.nonce;
+    // Already resolved elsewhere between the click and here — the row's
+    // buttons should already be gone, but a stale nonce is a no-op, not an
+    // error (docs/STRUCTURED-VIEW.md: any nonce answers 204). Resolve
+    // quietly: there is nothing for the row to restore.
+    if (!nonce || rowId !== pendingApprovalRowId) return;
+    try {
+      await resolveStructuredApproval(sessionId, nonce, decision);
+    } catch (e: unknown) {
+      // Only propagate the failure — so the row re-enables its buttons — if
+      // this is still the pending approval. If it moved on while the
+      // request was in flight (superseded, cancelled, answered elsewhere),
+      // the state-driven re-render already replaced the row; reviving
+      // buttons on it would be reviving a decision that no longer applies.
+      if (!disposed && rowId === pendingApprovalRowId) {
+        showError(String(e));
+        throw e;
+      }
+    }
+  }
+
+  function buildRowElement(row: TranscriptRow): HTMLElement | null {
+    const el = buildTranscriptRow(
+      row,
+      approvalStateFor(row),
+      expandedRowIds.has(row.id),
+      (expanded) => {
+        if (expanded) expandedRowIds.add(row.id);
+        else expandedRowIds.delete(row.id);
+        finishTranscriptLayout();
+      },
+    );
+    if (!el) return null;
+    if (el.querySelector(".st-tool-head")?.getAttribute("aria-expanded") !== "true") {
+      expandedRowIds.delete(row.id);
+    }
+    return el;
+  }
+
+  function toolGroupsByTurn(): Map<string, TranscriptRow[]> {
+    const groups = new Map<string, TranscriptRow[]>();
+    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 id = `turn:${turnId}`;
+      const group = groups.get(id) ?? [];
+      group.push(row);
+      groups.set(id, group);
+    }
+    return groups;
+  }
+
+  function rebuildTranscript(): void {
+    const active = document.activeElement as HTMLElement | null;
+    const focusedRowId = active?.closest<HTMLElement>("[data-row-id]")?.dataset.rowId;
+    const focusedGroupId = active?.closest<HTMLElement>("[data-tool-group-id]")?.dataset.toolGroupId;
+    const restoreToolFocus = active?.classList.contains("st-tool-head") ?? false;
+    const restoreGroupFocus = active?.classList.contains("st-tool-group-head") ?? false;
+    const groups = toolGroupsByTurn();
+    const groupedRowIds = new Set<string>();
+    const liveGroupIds = new Set([...groups].filter(([, tools]) => tools.length > 1).map(([id]) => id));
+    for (const id of expandedGroupIds) if (!liveGroupIds.has(id)) expandedGroupIds.delete(id);
+
+    rowEls.clear();
+    groupEls.clear();
+    const children: HTMLElement[] = [];
+    let turnId = "before-first-message";
+    for (const row of rows) {
+      if (row.kind === "user") turnId = row.id;
+      const groupId = `turn:${turnId}`;
+      const groupRows = groups.get(groupId) ?? [];
+      if ((row.kind === "tool_call" || row.kind === "tool_diff") && groupRows.length > 1) {
+        if (groupedRowIds.has(row.id)) continue;
+        const toolEls = groupRows.flatMap((toolRow) => {
+          groupedRowIds.add(toolRow.id);
+          const toolEl = buildRowElement(toolRow);
+          if (!toolEl) return [];
+          rowEls.set(toolRow.id, toolEl);
+          return [toolEl];
+        });
+        const groupEl = buildToolGroup(
+          groupId,
+          groupRows,
+          toolEls,
+          expandedGroupIds.has(groupId),
+          (expanded) => {
+            if (expanded) expandedGroupIds.add(groupId);
+            else expandedGroupIds.delete(groupId);
+            finishTranscriptLayout();
+          },
+        );
+        groupEls.set(groupId, groupEl);
+        children.push(groupEl);
+        continue;
+      }
+      const rowEl = buildRowElement(row);
+      if (!rowEl) continue;
+      rowEls.set(row.id, rowEl);
+      children.push(rowEl);
+    }
+    rowsEl.replaceChildren(...children);
+    if (restoreToolFocus && focusedRowId) {
+      rowEls.get(focusedRowId)?.querySelector<HTMLButtonElement>(".st-tool-head")?.focus();
+    } else if (restoreGroupFocus && focusedGroupId) {
+      groupEls.get(focusedGroupId)?.querySelector<HTMLButtonElement>(".st-tool-group-head")?.focus();
+    }
+  }
+
+  function applySnapshot(snapshot: { rows: TranscriptRow[] }): void {
+    const forceBottom = !receivedSnapshot;
+    updateTranscriptLayout(() => {
+      rows = [...snapshot.rows];
+      const expandableIds = new Set(
+        rows.filter((row) => row.kind === "tool_call" || row.kind === "tool_diff").map((row) => row.id),
+      );
+      for (const id of expandedRowIds) if (!expandableIds.has(id)) expandedRowIds.delete(id);
+      rowIndex.clear();
+      rows.forEach((row, i) => rowIndex.set(row.id, i));
+      rebuildTranscript();
+      syncAvailableCommands();
+    }, forceBottom);
+    receivedSnapshot = true;
+  }
+
+  function applyDelta(delta: TranscriptDelta | null | undefined): void {
+    if (!delta) return;
+    updateTranscriptLayout(() => {
+      if (delta.type === "append") {
+        rowIndex.set(delta.row.id, rows.length);
+        rows.push(delta.row);
+      } else if (delta.type === "patch") {
+        const i = rowIndex.get(delta.row.id);
+        if (i === undefined) {
+          rowIndex.set(delta.row.id, rows.length);
+          rows.push(delta.row);
+        } else {
+          rows[i] = delta.row;
+        }
+      } else {
+        const i = rowIndex.get(delta.id);
+        if (i === undefined) return;
+        rows.splice(i, 1);
+        expandedRowIds.delete(delta.id);
+        rowIndex.clear();
+        rows.forEach((row, idx) => rowIndex.set(row.id, idx));
+      }
+      rebuildTranscript();
+      syncAvailableCommands();
+    });
+  }
+
+  function sessionConfigOptions(): AcpSessionConfigOption[] {
+    return state.config_options?.configOptions ?? [];
+  }
+
+  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
+      ?? option.currentValue;
+  }
+
+  async function changeConfig(option: AcpSessionConfigOption, value: string | boolean): Promise<void> {
+    configBusy = true;
+    renderConfig();
+    clearError();
+    try {
+      await setStructuredConfig(sessionId, { config_id: option.id, value });
+    } catch (error) {
+      showError(error instanceof Error ? error.message : "Could not change the session setting");
+    } finally {
+      configBusy = false;
+      renderConfig();
+    }
+  }
+
+  function renderConfig(): void {
+    const options = sessionConfigOptions();
+    configEl.hidden = options.length === 0;
+    if (options.length === 0) {
+      configMenu.hidden = true;
+      configTrigger.setAttribute("aria-expanded", "false");
+      return;
+    }
+    const ordered = [...options].sort((a, b) => {
+      const rank = (category?: string | null) =>
+        ["model", "thought_level", "mode", "model_config"].indexOf(category ?? "");
+      const aRank = rank(a.category);
+      const bRank = rank(b.category);
+      return (aRank < 0 ? 99 : aRank) - (bRank < 0 ? 99 : bRank);
+    });
+    const summary = ordered.map((option) => `${option.name}: ${currentConfigLabel(option)}`).join("\n");
+    configTrigger.title = summary;
+    configTrigger.setAttribute("aria-label", `Session settings. ${summary.replaceAll("\n", ". ")}`);
+    configTrigger.disabled = configBusy;
+    configMenu.replaceChildren();
+    for (const option of ordered) {
+      const row = document.createElement("label");
+      row.className = "structured-config-row";
+      const name = document.createElement("span");
+      name.className = "structured-config-name";
+      name.textContent = option.name;
+      row.append(name);
+      if (option.type === "select") {
+        const select = document.createElement("select");
+        select.className = "structured-config-select";
+        select.disabled = configBusy;
+        for (const choice of configChoices(option)) {
+          const item = document.createElement("option");
+          item.value = choice.value;
+          item.textContent = choice.name;
+          item.title = choice.description ?? "";
+          select.append(item);
+        }
+        select.value = String(option.currentValue);
+        select.addEventListener("change", () => void changeConfig(option, select.value));
+        row.append(select);
+      } else if (option.type === "boolean") {
+        const toggle = document.createElement("input");
+        toggle.type = "checkbox";
+        toggle.className = "structured-config-toggle";
+        toggle.checked = option.currentValue === true;
+        toggle.disabled = configBusy;
+        toggle.addEventListener("change", () => void changeConfig(option, toggle.checked));
+        row.append(toggle);
+      } else {
+        continue;
+      }
+      if (option.description) row.title = option.description;
+      configMenu.append(row);
+    }
+  }
+
+  function renderComposerState(): void {
+    const active = state.turn.responding || state.turn.thinking || awaitingBeginGeneration !== null;
+    const projectedActive = state.turn.responding || state.turn.thinking;
+    input.disabled = active;
+    sendBtn.disabled = active;
+    sendBtn.hidden = projectedActive;
+    cancelBtn.hidden = !projectedActive;
+    if (active) closeCommandMenu();
+    renderActivity();
+  }
+
+  function liveElapsedMs(): number {
+    const authoritative = state.turn.started_at ? Date.parse(state.turn.started_at) : Number.NaN;
+    const startedAt = Number.isFinite(authoritative) ? authoritative : optimisticTurnStartedAt;
+    return startedAt === null ? 0 : Math.max(0, Date.now() - startedAt);
+  }
+
+  function renderActivity(): void {
+    const active = state.turn.responding || state.turn.thinking || awaitingBeginGeneration !== null;
+    activityEl.hidden = !active;
+    if (!active) {
+      optimisticTurnStartedAt = null;
+      if (activityTimer !== null) window.clearInterval(activityTimer);
+      activityTimer = null;
+      return;
+    }
+    const tools = state.turn.active_tool_calls.length;
+    const label = awaitingBeginGeneration !== null
+      ? "Sending"
+      : state.turn.thinking
+        ? "Thinking"
+        : tools > 0
+          ? `Running ${tools} ${tools === 1 ? "tool" : "tools"}`
+          : "Responding";
+    const parts = [label, formatElapsed(liveElapsedMs())];
+    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);
+    }
+    activityText.textContent = parts.join(" · ");
+    if (activityTimer === null) activityTimer = window.setInterval(renderActivity, 1_000);
+  }
+
+  function reconcileAwaitingBegin(): void {
+    if (state.turn.responding || state.turn.thinking) {
+      awaitingBeginGeneration = null;
+    } else if (
+      awaitingBeginGeneration !== null
+      && acceptedSubmission?.generation === awaitingBeginGeneration
+      && stateSocketGeneration > acceptedSubmission.socketGeneration
+    ) {
+      awaitingBeginGeneration = null;
+    }
+  }
+
+  function applyState(next: ReducedState, connectionGeneration: number): void {
+    state = next;
+    stateSocketGeneration = connectionGeneration;
+    reconcileAwaitingBegin();
+    const newPendingId = state.pending_approval ? lastRowIdOfKind("approval") : null;
+    if (newPendingId !== pendingApprovalRowId) {
+      updateTranscriptLayout(() => {
+        const prev = pendingApprovalRowId;
+        pendingApprovalRowId = newPendingId;
+        if (prev !== null || newPendingId !== null) rebuildTranscript();
+      });
+    }
+    renderConfig();
+    renderComposerState();
+  }
+
+  function closeConfigMenu(): void {
+    configMenu.hidden = true;
+    configTrigger.setAttribute("aria-expanded", "false");
+  }
+
+  configTrigger.addEventListener("click", () => {
+    const opening = configMenu.hidden;
+    configMenu.hidden = !opening;
+    configTrigger.setAttribute("aria-expanded", String(opening));
+  });
+  const closeConfigOnOutsidePress = (event: PointerEvent) => {
+    if (!configEl.contains(event.target as Node)) closeConfigMenu();
+  };
+  document.addEventListener("pointerdown", closeConfigOnOutsidePress);
+  configEl.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      closeConfigMenu();
+      configTrigger.focus();
+    }
+  });
+
+  // ---- error banner ----
+  let errorEl: HTMLElement | null = null;
+  function showError(message: string): void {
+    if (!errorEl) {
+      errorEl = document.createElement("div");
+      errorEl.className = "structured-error";
+      composerForm.insertAdjacentElement("beforebegin", errorEl);
+    }
+    errorEl.textContent = message;
+  }
+  function clearError(): void {
+    errorEl?.remove();
+    errorEl = null;
+  }
+
+  // ---- composer ----
+  function commandsFromTranscript(): 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 [];
+  }
+
+  function closeCommandMenu(): void {
+    commandMenu.hidden = true;
+    commandMenu.replaceChildren();
+    filteredCommands = [];
+    activeCommandIndex = -1;
+    input.setAttribute("aria-expanded", "false");
+    input.removeAttribute("aria-activedescendant");
+  }
+
+  function commandTokenAtCursor(): CommandToken | null {
+    const cursor = input.selectionStart;
+    if (cursor !== input.selectionEnd) return null;
+    let start = cursor;
+    while (start > 0 && !/\s/.test(input.value[start - 1])) start--;
+    let end = cursor;
+    while (end < input.value.length && !/\s/.test(input.value[end])) end++;
+    const match = /^\/([^\s/]*)$/.exec(input.value.slice(start, cursor));
+    return match ? { start, end, query: match[1].toLocaleLowerCase() } : null;
+  }
+
+  function chooseCommand(command: AvailableCommand): void {
+    const token = commandTokenAtCursor();
+    if (!token) return;
+    const before = input.value.slice(0, token.start);
+    const after = input.value.slice(token.end);
+    let replacement = `/${command.name}`;
+    let cursor = before.length + replacement.length;
+    if (after.length === 0) {
+      replacement += " ";
+      cursor++;
+    } else if (/^[ \t]/.test(after)) {
+      cursor++;
+    }
+    input.value = before + replacement + after;
+    closeCommandMenu();
+    autoResize();
+    input.focus();
+    input.setSelectionRange(cursor, cursor);
+  }
+
+  function renderCommandMenu(): void {
+    const token = commandTokenAtCursor();
+    if (!token || input.disabled || availableCommands.length === 0) {
+      closeCommandMenu();
+      return;
+    }
+    const { query } = token;
+    filteredCommands = availableCommands
+      .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;
+      });
+    if (filteredCommands.length === 0) {
+      closeCommandMenu();
+      return;
+    }
+    activeCommandIndex = Math.min(Math.max(activeCommandIndex, 0), filteredCommands.length - 1);
+    const options = filteredCommands.map((command, index) => {
+      const option = document.createElement("div");
+      option.id = `${commandMenu.id}-option-${index}`;
+      option.className = "structured-command-option";
+      option.setAttribute("role", "option");
+      option.setAttribute("aria-selected", String(index === activeCommandIndex));
+      const title = document.createElement("div");
+      title.className = "structured-command-title";
+      const name = document.createElement("span");
+      name.className = "structured-command-name";
+      name.textContent = `/${command.name}`;
+      const hint = document.createElement("span");
+      hint.className = "structured-command-hint";
+      hint.textContent = command.input?.hint ?? "";
+      title.append(name, hint);
+      const description = document.createElement("div");
+      description.className = "structured-command-description";
+      description.textContent = command.description.replace(/\s+/g, " ").trim();
+      option.append(title, description);
+      option.addEventListener("pointerdown", (event) => event.preventDefault());
+      option.addEventListener("click", () => chooseCommand(command));
+      return option;
+    });
+    commandMenu.replaceChildren(...options);
+    commandMenu.hidden = false;
+    input.setAttribute("aria-expanded", "true");
+    input.setAttribute("aria-activedescendant", options[activeCommandIndex].id);
+    options[activeCommandIndex].scrollIntoView?.({ block: "nearest" });
+  }
+
+  function syncAvailableCommands(): void {
+    availableCommands = commandsFromTranscript();
+    renderCommandMenu();
+  }
+
+  function autoResize(): void {
+    updateTranscriptLayout(() => {
+      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";
+    });
+  }
+  input.addEventListener("input", () => {
+    autoResize();
+    activeCommandIndex = 0;
+    renderCommandMenu();
+  });
+  input.addEventListener("click", renderCommandMenu);
+  input.addEventListener("select", renderCommandMenu);
+  input.addEventListener("keyup", (event) => {
+    if (["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) renderCommandMenu();
+  });
+  input.addEventListener("keydown", (e) => {
+    if (!commandMenu.hidden) {
+      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+        e.preventDefault();
+        const direction = e.key === "ArrowDown" ? 1 : -1;
+        activeCommandIndex =
+          (activeCommandIndex + direction + filteredCommands.length) % filteredCommands.length;
+        renderCommandMenu();
+        return;
+      }
+      if ((e.key === "Enter" && !e.shiftKey) || e.key === "Tab") {
+        e.preventDefault();
+        chooseCommand(filteredCommands[activeCommandIndex]);
+        return;
+      }
+      if (e.key === "Escape") {
+        e.preventDefault();
+        closeCommandMenu();
+        return;
+      }
+    }
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      composerForm.requestSubmit();
+    }
+  });
+  input.addEventListener("blur", () => {
+    window.setTimeout(() => {
+      if (!commandMenu.contains(document.activeElement)) closeCommandMenu();
+    }, 0);
+  });
+  composerForm.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const text = input.value;
+    if (!text.trim() || input.disabled) return;
+    const generation = ++submissionGeneration;
+    const submissionSocketGeneration = socketGeneration;
+    awaitingBeginGeneration = generation;
+    optimisticTurnStartedAt = Date.now();
+    acceptedSubmission = null;
+    input.value = "";
+    autoResize();
+    clearError();
+    renderComposerState();
+    sendStructuredPrompt(sessionId, text).then(
+      () => {
+        if (
+          disposed
+          || generation !== submissionGeneration
+          || awaitingBeginGeneration !== generation
+        ) return;
+        const acceptanceSocketGeneration = socketGeneration;
+        acceptedSubmission = { generation, socketGeneration: acceptanceSocketGeneration };
+        // A replacement socket may have captured idle before the POST claimed
+        // the prompt. Reconnect again so its snapshot cannot predate the 204.
+        if (acceptanceSocketGeneration > submissionSocketGeneration) reconnectForReconciliation();
+      },
+      (e: unknown) => {
+        if (disposed || generation !== submissionGeneration) return;
+        if (awaitingBeginGeneration === generation) awaitingBeginGeneration = null;
+        if (input.value === "") {
+          input.value = text;
+          autoResize();
+        }
+        showError(String(e));
+        renderComposerState();
+      },
+    );
+  });
+  cancelBtn.addEventListener("click", () => {
+    clearError();
+    cancelStructuredTurn(sessionId).catch((e: unknown) => {
+      if (!disposed) showError(String(e));
+    });
+  });
+
+  // ---- socket lifecycle ----
+  let ws: WebSocket | null = null;
+  let reconnectMs = INITIAL_RECONNECT_MS;
+  let reconnectTimer: number | null = null;
+
+  function cancelReconnect(): void {
+    if (reconnectTimer === null) return;
+    window.clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+
+  function closeCurrentSocket(): void {
+    const socket = ws;
+    ws = null;
+    if (!socket) return;
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+    try {
+      socket.close();
+    } catch {
+      // ignore
+    }
+  }
+
+  function reconnectForReconciliation(): void {
+    if (disposed) return;
+    cancelReconnect();
+    closeCurrentSocket();
+    setConnState("reconnecting…", "connecting");
+    connect();
+  }
+
+  function connect(): void {
+    if (disposed) return;
+    cancelReconnect();
+    closeCurrentSocket();
+    const connectionGeneration = ++socketGeneration;
+    const socket = socketFactory(sessionId);
+    ws = socket;
+    socket.onopen = () => {
+      if (disposed || ws !== socket) return;
+      reconnectMs = INITIAL_RECONNECT_MS;
+      setConnState("connected", "open");
+    };
+    socket.onmessage = (ev) => {
+      if (disposed || ws !== socket) return;
+      if (typeof ev.data !== "string") return;
+      let msg: StructuredEvent;
+      try {
+        msg = JSON.parse(ev.data) as StructuredEvent;
+      } catch {
+        return; // not a structured event we understand
+      }
+      switch (msg.type) {
+        case "transcript_snapshot":
+          applySnapshot(msg.snapshot);
+          break;
+        case "reduced_state":
+          applyState(msg.state, connectionGeneration);
+          break;
+        case "projection_update":
+          applyDelta(msg.transcript);
+          applyState(msg.state, connectionGeneration);
+          break;
+      }
+    };
+    socket.onerror = () => {
+      if (disposed || ws !== socket) return;
+      setConnState("error", "error");
+    };
+    socket.onclose = (ev) => {
+      if (disposed || ws !== socket) return;
+      ws = null;
+      const reason = ev.reason?.trim();
+      if (ev.code >= 4000 && reason) {
+        setConnState(reason, "error");
+        showError(`cannot attach: ${reason}`);
+        return;
+      }
+      if (opts.shouldReconnect?.(sessionId, ev.code)) {
+        const delay = Math.min(reconnectMs, MAX_RECONNECT_MS);
+        setConnState("reconnecting…", "connecting");
+        reconnectTimer = window.setTimeout(() => {
+          reconnectTimer = null;
+          if (disposed) return;
+          reconnectMs = Math.min(reconnectMs * 2, MAX_RECONNECT_MS);
+          connect();
+        }, delay);
+        return;
+      }
+      setConnState(`closed (${ev.code})`, "closed");
+      opts.onClosed?.(sessionId);
+    };
+  }
+  connect();
+
+  // A pane can be parked again before its deferred focus frame fires (a
+  // preview stepped past it, a split closed it) — the frame must not focus a
+  // hidden textarea out from under whatever the operator moved to since.
+  // `mountToken` is bumped on every mount/unmount so a stale frame can tell
+  // it is no longer the most recent one.
+  let mountToken = 0;
+  let focusFrame: number | null = null;
+
+  function cancelFocusFrame(): void {
+    if (focusFrame !== null) window.cancelAnimationFrame(focusFrame);
+    focusFrame = null;
+  }
+
+  return {
+    sessionId,
+    el,
+    onMount(mountOpts?: { focus?: boolean }) {
+      const focusOnMount = mountOpts?.focus !== false;
+      const token = ++mountToken;
+      scrollWorkActive = true;
+      pendingScroll = {
+        top: parkedScrollTop ?? scrollEl.scrollTop,
+        follow: followingBottom,
+      };
+      parkedScrollTop = null;
+      finishTranscriptLayout();
+      cancelFocusFrame();
+      focusFrame = window.requestAnimationFrame(() => {
+        focusFrame = null;
+        if (disposed || token !== mountToken) return; // parked/remounted since this was scheduled
+        if (focusOnMount && !input.disabled) input.focus();
+      });
+    },
+    onUnmount() {
+      mountToken++;
+      parkedScrollTop = pendingScroll?.top ?? scrollEl.scrollTop;
+      scrollWorkActive = false;
+      cancelScrollFrame();
+      cancelFocusFrame();
+    },
+    focusTerminal() {
+      if (!input.disabled) input.focus();
+    },
+    sendInput() {
+      // No PTY behind a structured session — the leader's literal-byte
+      // escape hatch has nothing to do here.
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      if (activityTimer !== null) window.clearInterval(activityTimer);
+      mountToken++;
+      scrollWorkActive = false;
+      cancelScrollFrame();
+      cancelFocusFrame();
+      cancelReconnect();
+      closeCurrentSocket();
+      expandedRowIds.clear();
+      expandedGroupIds.clear();
+      scrollEl.removeEventListener("scroll", onTranscriptScroll);
+      scrollEl.removeEventListener("click", onTranscriptClick, true);
+      document.removeEventListener("pointerdown", closeConfigOnOutsidePress);
+      el.remove();
+    },
+  };
+}

web/src/structuredDiff.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from "vitest";
+
+import { computeDiffLines, diffStats, type DiffLine } from "./structuredDiff.js";
+
+function texts(lines: DiffLine[]): Array<[string, string]> {
+  return lines.map((l) => [l.kind, l.text]);
+}
+
+describe("computeDiffLines", () => {
+  it("renders a brand new file (no oldText) as all additions", () => {
+    const lines = computeDiffLines(null, "a\nb\n");
+    expect(texts(lines)).toEqual([
+      ["add", "a"],
+      ["add", "b"],
+    ]);
+  });
+
+  it("renders a full deletion as all removals", () => {
+    const lines = computeDiffLines("a\nb\n", "");
+    expect(texts(lines)).toEqual([
+      ["del", "a"],
+      ["del", "b"],
+    ]);
+  });
+
+  it("shows a small replace as context around del/add", () => {
+    const lines = computeDiffLines("one\ntwo\nthree\n", "one\ntwx\nthree\n");
+    expect(texts(lines)).toEqual([
+      ["ctx", "one"],
+      ["del", "two"],
+      ["add", "twx"],
+      ["ctx", "three"],
+    ]);
+  });
+
+  it("leaves identical text as pure context, uncollapsed when short", () => {
+    const lines = computeDiffLines("a\nb\nc\n", "a\nb\nc\n");
+    expect(texts(lines)).toEqual([
+      ["ctx", "a"],
+      ["ctx", "b"],
+      ["ctx", "c"],
+    ]);
+  });
+
+  it("handles an insertion without changing surrounding lines", () => {
+    expect(texts(computeDiffLines("a\nc\n", "a\nb\nc\n"))).toEqual([
+      ["ctx", "a"],
+      ["add", "b"],
+      ["ctx", "c"],
+    ]);
+  });
+
+  it("handles a deletion without changing surrounding lines", () => {
+    expect(texts(computeDiffLines("a\nb\nc\n", "a\nc\n"))).toEqual([
+      ["ctx", "a"],
+      ["del", "b"],
+      ["ctx", "c"],
+    ]);
+  });
+
+  it("renders two empty files without invented lines", () => {
+    expect(computeDiffLines("", "")).toEqual([]);
+  });
+
+  it("shows when a final newline is added", () => {
+    expect(texts(computeDiffLines("a", "a\n"))).toEqual([
+      ["del", "a"],
+      ["eof", "\\ No newline at end of file"],
+      ["add", "a"],
+    ]);
+  });
+
+  it("shows when a final newline is removed", () => {
+    expect(texts(computeDiffLines("a\n", "a"))).toEqual([
+      ["del", "a"],
+      ["add", "a"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+  });
+
+  it("marks an unchanged unterminated final context line", () => {
+    expect(texts(computeDiffLines("a\nb\nc", "a\nX\nc"))).toEqual([
+      ["ctx", "a"],
+      ["del", "b"],
+      ["add", "X"],
+      ["ctx", "c"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+  });
+
+  it("marks an unterminated new file only once", () => {
+    const lines = computeDiffLines(null, "a");
+    expect(texts(lines)).toEqual([
+      ["add", "a"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+    expect(lines.filter((line) => line.kind === "eof")).toHaveLength(1);
+  });
+
+  it("collapses a long unchanged interior run, keeping 3 lines of context each side", () => {
+    const common = Array.from({ length: 20 }, (_, i) => `line${i}`);
+    const oldText = [...common.slice(0, 10), "OLD", ...common.slice(10)].join("\n");
+    const newText = [...common.slice(0, 10), "NEW", ...common.slice(10)].join("\n");
+    const lines = computeDiffLines(oldText, newText);
+    // The leading run keeps only its last 3 lines (adjacent to the change),
+    // behind a marker for the rest; the trailing run mirrors that.
+    expect(lines[0].kind).toBe("hunk");
+    expect(lines[1]).toEqual({ kind: "ctx", text: "line7" });
+    expect(lines[2]).toEqual({ kind: "ctx", text: "line8" });
+    expect(lines[3]).toEqual({ kind: "ctx", text: "line9" });
+    expect(lines[4].kind).toBe("del");
+    expect(lines[5].kind).toBe("add");
+    expect(lines[6]).toEqual({ kind: "ctx", text: "line10" });
+    expect(lines.filter((l) => l.kind === "hunk")).toHaveLength(2);
+  });
+
+  it("preserves the EOF marker when a long unterminated trailing run collapses", () => {
+    const trailing = Array.from({ length: 10 }, (_, i) => `t${i}`);
+    const oldText = ["OLD", ...trailing].join("\n");
+    const newText = ["NEW", ...trailing].join("\n");
+
+    expect(texts(computeDiffLines(oldText, newText))).toEqual([
+      ["del", "OLD"],
+      ["add", "NEW"],
+      ["ctx", "t0"],
+      ["ctx", "t1"],
+      ["ctx", "t2"],
+      ["hunk", "⋯ 7 unchanged lines ⋯"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+  });
+
+  it("produces one hunk for the long middle run, none for the short edges", () => {
+    // Edge runs (2 lines) fit within their one-sided 3-line context budget;
+    // only the interior run (10 lines, budgeted 3+3=6) needs to collapse.
+    const middle = Array.from({ length: 10 }, (_, i) => `c${i}`);
+    const oldText = ["lead0", "lead1", "OLD1", ...middle, "OLD2", "trail0", "trail1"].join("\n");
+    const newText = ["lead0", "lead1", "NEW1", ...middle, "NEW2", "trail0", "trail1"].join("\n");
+    const lines = computeDiffLines(oldText, newText);
+    const dels = lines.filter((l) => l.kind === "del").map((l) => l.text);
+    const adds = lines.filter((l) => l.kind === "add").map((l) => l.text);
+    expect(dels).toEqual(["OLD1", "OLD2"]);
+    expect(adds).toEqual(["NEW1", "NEW2"]);
+    expect(lines.filter((l) => l.kind === "hunk")).toHaveLength(1);
+    expect(texts(lines).slice(0, 2)).toEqual([
+      ["ctx", "lead0"],
+      ["ctx", "lead1"],
+    ]);
+    expect(texts(lines).slice(-3)).toEqual([
+      ["ctx", "trail0"],
+      ["ctx", "trail1"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+  });
+
+  it("handles an old file with no trailing newline", () => {
+    const lines = computeDiffLines("a\nb", "a\nb\nc");
+    expect(texts(lines)).toEqual([
+      ["ctx", "a"],
+      ["del", "b"],
+      ["eof", "\\ No newline at end of file"],
+      ["add", "b"],
+      ["add", "c"],
+      ["eof", "\\ No newline at end of file"],
+    ]);
+  });
+
+  it("falls back to a bounded coarse diff for a pathological changed middle", () => {
+    const oldLines = Array.from({ length: 501 }, (_, index) => `line${index}`);
+    const newLines = [...oldLines.slice(1), oldLines[0]];
+    const lines = computeDiffLines(`${oldLines.join("\n")}\n`, `${newLines.join("\n")}\n`);
+    expect(lines).toHaveLength(1_002);
+    expect(lines.slice(0, 501).every((line) => line.kind === "del")).toBe(true);
+    expect(lines.slice(501).every((line) => line.kind === "add")).toBe(true);
+  });
+});
+
+describe("diffStats", () => {
+  it("counts add/del lines, ignoring context and hunk markers", () => {
+    const lines = computeDiffLines("a\nb\nc\n", "a\nx\ny\nc\n");
+    expect(diffStats(lines)).toEqual({ added: 2, removed: 1 });
+  });
+
+  it("is zero for identical text", () => {
+    expect(diffStats(computeDiffLines("same\n", "same\n"))).toEqual({ added: 0, removed: 0 });
+  });
+});

web/src/structuredDiff.ts

@@ -0,0 +1,167 @@
+// Line-level diff for a `ToolDiff` row's `Diff` content block (#140). ACP
+// hands over full `oldText`/`newText`, not a unified-diff patch, so the
+// coloured hunks the design calls for have to be computed here.
+
+export type DiffLineKind = "add" | "del" | "ctx" | "hunk" | "eof";
+
+export interface DiffLine {
+  kind: DiffLineKind;
+  /** The line's text (a `hunk` line is a human summary, not source text). */
+  text: string;
+}
+
+/** Interior unchanged runs longer than this collapse to a summary line
+ *  flanked by this many lines of real context on each side. */
+const CONTEXT = 3;
+
+/** Bounds the O(n·m) LCS table: above this cell count, the changed middle is
+ *  shown as one coarse del-then-add block instead of a fine-grained diff —
+ *  still correct, just not minimal. */
+const LCS_CELL_LIMIT = 250_000;
+
+interface SourceLine {
+  text: string;
+  terminated: boolean;
+}
+
+function splitLines(text: string): SourceLine[] {
+  if (text === "") return [];
+  const parts = text.split("\n");
+  const hasFinalNewline = text.endsWith("\n");
+  if (hasFinalNewline) parts.pop();
+  return parts.map((line, index) => ({
+    text: line,
+    terminated: index < parts.length - 1 || hasFinalNewline,
+  }));
+}
+
+type Op = { kind: "add" | "del" | "ctx"; line: SourceLine };
+
+function sameLine(a: SourceLine, b: SourceLine): boolean {
+  return a.text === b.text && a.terminated === b.terminated;
+}
+
+/** Longest-common-subsequence diff of two line arrays, already trimmed of any
+ *  shared prefix/suffix by the caller. */
+function lcsDiff(a: SourceLine[], b: SourceLine[]): Op[] {
+  const n = a.length;
+  const m = b.length;
+  if (n === 0) return b.map((line) => ({ kind: "add", line }));
+  if (m === 0) return a.map((line) => ({ kind: "del", line }));
+  if (n * m > LCS_CELL_LIMIT) {
+    return [...a.map((line) => ({ kind: "del" as const, line })), ...b.map((line) => ({ kind: "add" as const, line }))];
+  }
+  // dp[i][j] = length of the LCS of a[i:] and b[j:].
+  const columns = m + 1;
+  const dp = new Uint32Array((n + 1) * columns);
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i * columns + j] = sameLine(a[i], b[j])
+        ? dp[(i + 1) * columns + j + 1] + 1
+        : Math.max(dp[(i + 1) * columns + j], dp[i * columns + j + 1]);
+    }
+  }
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (sameLine(a[i], b[j])) {
+      ops.push({ kind: "ctx", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[(i + 1) * columns + j] >= dp[i * columns + j + 1]) {
+      ops.push({ kind: "del", line: a[i] });
+      i++;
+    } else {
+      ops.push({ kind: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ kind: "del", line: a[i++] });
+  while (j < m) ops.push({ kind: "add", line: b[j++] });
+  return ops;
+}
+
+function diffLines(a: SourceLine[], b: SourceLine[]): Op[] {
+  let pre = 0;
+  while (pre < a.length && pre < b.length && sameLine(a[pre], b[pre])) pre++;
+  let suf = 0;
+  while (
+    suf < a.length - pre &&
+    suf < b.length - pre &&
+    sameLine(a[a.length - 1 - suf], b[b.length - 1 - suf])
+  ) {
+    suf++;
+  }
+  const prefixCtx: Op[] = a.slice(0, pre).map((line) => ({ kind: "ctx", line }));
+  const suffixCtx: Op[] = a.slice(a.length - suf).map((line) => ({ kind: "ctx", line }));
+  const middle = lcsDiff(a.slice(pre, a.length - suf), b.slice(pre, b.length - suf));
+  return [...prefixCtx, ...middle, ...suffixCtx];
+}
+
+/** Collapse a long run of unchanged lines to a summary, keeping up to
+ *  {@link CONTEXT} real lines adjacent to each neighbouring change — same
+ *  shape a unified diff gives a reader, without claiming line numbers this
+ *  module never tracked. A run touching the start/end of the whole diff has
+ *  no change to be adjacent to on that side, so it keeps no context there
+ *  (unless it is the *only* run, i.e. nothing changed at all). */
+function hunk(ops: Op[]): DiffLine[] {
+  const out: DiffLine[] = [];
+  const push = (op: Op) => {
+    out.push({ kind: op.kind, text: op.line.text });
+    if (!op.line.terminated) {
+      out.push({ kind: "eof", text: "\\ No newline at end of file" });
+    }
+  };
+  let i = 0;
+  while (i < ops.length) {
+    if (ops[i].kind !== "ctx") {
+      push(ops[i]);
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < ops.length && ops[j].kind === "ctx") j++;
+    const run = ops.slice(i, j);
+    const wholeDiff = i === 0 && j === ops.length;
+    const keepHead = wholeDiff || i > 0 ? CONTEXT : 0;
+    const keepTail = wholeDiff || j < ops.length ? CONTEXT : 0;
+    if (run.length <= keepHead + keepTail) {
+      run.forEach(push);
+    } else {
+      if (keepHead) run.slice(0, keepHead).forEach(push);
+      const collapsed = run.slice(keepHead, run.length - keepTail);
+      out.push({
+        kind: "hunk",
+        text: `⋯ ${collapsed.length} unchanged lines ⋯`,
+      });
+      if (collapsed.some((op) => !op.line.terminated)) {
+        out.push({ kind: "eof", text: "\\ No newline at end of file" });
+      }
+      if (keepTail) run.slice(run.length - keepTail).forEach(push);
+    }
+    i = j;
+  }
+  return out;
+}
+
+/** Coloured, hunked diff lines for a `Diff` content block. `oldText` absent
+ *  (a new file) renders every line of `newText` as added. */
+export function computeDiffLines(oldText: string | null | undefined, newText: string): DiffLine[] {
+  const newLines = splitLines(newText);
+  if (oldText == null) return hunk(newLines.map((line) => ({ kind: "add", line })));
+  const ops = diffLines(splitLines(oldText), newLines);
+  return hunk(ops);
+}
+
+/** `+added -removed` counts straight off the diff — real derived data, not a
+ *  fabricated duration or line count. */
+export function diffStats(lines: DiffLine[]): { added: number; removed: number } {
+  let added = 0;
+  let removed = 0;
+  for (const line of lines) {
+    if (line.kind === "add") added++;
+    else if (line.kind === "del") removed++;
+  }
+  return { added, removed };
+}

web/src/structuredRender.test.ts

@@ -0,0 +1,392 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  buildToolGroup,
+  buildTranscriptRow,
+  renderInlineMarkdown,
+  renderMarkdown,
+} from "./structuredRender.js";
+import type { TranscriptRow } from "./types.js";
+
+function row<K extends TranscriptRow["kind"]>(
+  kind: K,
+  data: unknown,
+  id = "r1",
+): TranscriptRow & { kind: K } {
+  return { id, kind, data };
+}
+
+describe("buildTranscriptRow: user/agent/thought", () => {
+  it("renders a user row with the text content and no markdown", () => {
+    const el = buildTranscriptRow(
+      row("user", { content: { type: "text", text: "hi <b>there</b>" } }),
+    );
+    expect(el.className).toContain("st-row-user");
+    expect(el.textContent).toContain("hi <b>there</b>");
+    expect(el.querySelector(".st-who")).toBeNull();
+    // never actual markup from user input
+    expect(el.querySelector("b")).toBeNull();
+  });
+
+  it("renders agent prose as paragraphs with inline markdown", () => {
+    const el = buildTranscriptRow(
+      row("agent_text", { content: { type: "text", text: "one **two** `three`\n\nfour" } }),
+    );
+    expect(el.className).toContain("st-row-agent");
+    const ps = el.querySelectorAll("p");
+    expect(ps).toHaveLength(2);
+    expect(ps[0].innerHTML).toContain("<strong>two</strong>");
+    expect(ps[0].innerHTML).toContain("<code>three</code>");
+  });
+
+  it("renders a thought row as plain text", () => {
+    const el = buildTranscriptRow(row("agent_thought", { content: { type: "text", text: "hmm" } }));
+    expect(el.className).toContain("st-row-thought");
+    expect(el.textContent).toBe("hmm");
+  });
+
+  it("falls back to a labelled placeholder for non-text content, never crashing", () => {
+    const el = buildTranscriptRow(row("user", { content: { type: "image" } }));
+    expect(el.textContent).toContain("[image]");
+  });
+
+  it("never clips text: a very long user message is not truncated", () => {
+    const long = "x".repeat(5000);
+    const el = buildTranscriptRow(row("user", { content: { type: "text", text: long } }));
+    expect(el.textContent).toContain(long);
+  });
+
+  it("copies message blocks on click and supports keyboard activation", async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", { configurable: true, value: { writeText } });
+    const el = buildTranscriptRow(
+      row("agent_text", { content: { type: "text", text: "copy **this** exactly" } }),
+    );
+    expect(el.getAttribute("role")).toBe("button");
+    el.click();
+    await Promise.resolve();
+    expect(writeText).toHaveBeenCalledWith("copy **this** exactly");
+    el.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    await Promise.resolve();
+    expect(writeText).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("renderInlineMarkdown", () => {
+  it("escapes raw HTML before applying markdown", () => {
+    expect(renderInlineMarkdown("<script>alert(1)</script>")).not.toContain("<script>");
+  });
+
+  it("does not treat a single asterisk pair meant as bold as nested italics", () => {
+    expect(renderInlineMarkdown("**bold**")).toBe("<strong>bold</strong>");
+  });
+});
+
+describe("renderMarkdown", () => {
+  it("renders GFM tables as semantic table markup", () => {
+    const html = renderMarkdown("| Model | State |\n| --- | --- |\n| Opus | ready |");
+    expect(html).toContain("<table>");
+    expect(html).toContain("<th>Model</th>");
+    expect(html).toContain("<td>Opus</td>");
+  });
+
+  it("removes executable HTML and unsafe URLs", () => {
+    const html = renderMarkdown(
+      '<img src=x onerror="alert(1)"><script>alert(2)</script>[bad](javascript:alert(3))',
+    );
+    expect(html).not.toContain("<img");
+    expect(html).not.toContain("<script");
+    expect(html).not.toContain('href="javascript:');
+  });
+});
+
+describe("buildTranscriptRow: tool calls", () => {
+  it("shows glyph, name, argument and no meta for a completed non-diff call", () => {
+    const el = buildTranscriptRow(
+      row("tool_call", {
+        toolCallId: "t1",
+        title: "Read(src/lib.rs)",
+        kind: "read",
+        status: "completed",
+      }),
+    );
+    const head = el.querySelector(".st-tool-head") as HTMLButtonElement;
+    expect(head.querySelector(".st-tool-name")!.textContent).toBe("Read");
+    expect(head.querySelector(".st-tool-arg")!.textContent).toBe("src/lib.rs");
+    expect(head.querySelector(".st-tool-meta")).toBeNull();
+  });
+
+  it("falls back to the kind label and full title when the title has no Name(arg) shape", () => {
+    const el = buildTranscriptRow(row("tool_call", { title: "does something odd", kind: "execute" }));
+    const head = el.querySelector(".st-tool-head")!;
+    expect(head.querySelector(".st-tool-name")!.textContent).toBe("Execute");
+    expect(head.querySelector(".st-tool-arg")!.textContent).toBe("does something odd");
+  });
+
+  it("shows a running badge for an in-progress call", () => {
+    const el = buildTranscriptRow(row("tool_call", { title: "Bash(sleep 1)", status: "in_progress" }));
+    const meta = el.querySelector(".st-tool-meta")!;
+    expect(meta.textContent).toBe("running");
+    expect(meta.className).toContain("st-tool-meta-running");
+  });
+
+  it("shows a failed badge for a failed call", () => {
+    const el = buildTranscriptRow(row("tool_call", { title: "Bash(false)", status: "failed" }));
+    expect(el.querySelector(".st-tool-meta")!.textContent).toBe("failed");
+  });
+
+  it("starts collapsed and expands its text output on click", () => {
+    const el = buildTranscriptRow(
+      row("tool_call", {
+        title: "Grep(x)",
+        status: "completed",
+        content: [{ type: "content", content: { type: "text", text: "match found" } }],
+      }),
+    );
+    const head = el.querySelector(".st-tool-head") as HTMLButtonElement;
+    const out = el.querySelector(".st-tool-out") as HTMLElement;
+    expect(out.hidden).toBe(true);
+    expect(head.getAttribute("aria-expanded")).toBe("false");
+    head.click();
+    expect(out.hidden).toBe(false);
+    expect(head.getAttribute("aria-expanded")).toBe("true");
+    expect(out.textContent).toContain("match found");
+    head.click();
+    expect(out.hidden).toBe(true);
+  });
+
+  it("does not expand when there is nothing to show", () => {
+    const el = buildTranscriptRow(row("tool_call", { title: "Read(x)", status: "completed" }));
+    const head = el.querySelector(".st-tool-head") as HTMLButtonElement;
+    head.click();
+    expect(head.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("shows raw command, input, and output as separately copyable details", () => {
+    const el = buildTranscriptRow(
+      row("tool_call", {
+        title: "Bash(test)",
+        rawInput: { command: "printf ok", timeout_ms: 1000 },
+        rawOutput: { stdout: "ok", exit_code: 0 },
+      }),
+    );
+    (el.querySelector(".st-tool-head") as HTMLButtonElement).click();
+    const labels = [...el.querySelectorAll(".st-tool-detail-label")].map((node) => node.textContent);
+    expect(labels).toEqual(["Command", "Input", "Output"]);
+    expect(el.querySelector(".st-tool-detail pre")!.textContent).toBe("printf ok");
+    expect(el.querySelectorAll(".st-tool-detail pre[role=button]")).toHaveLength(3);
+  });
+});
+
+describe("buildToolGroup", () => {
+  it("starts collapsed, then reveals independently expandable tool calls", () => {
+    const rows = [
+      row("tool_call", { title: "Read(a.ts)", content: [{ type: "content", content: { type: "text", text: "a" } }] }, "t1"),
+      row("tool_call", { title: "Bash(test)", content: [{ type: "content", content: { type: "text", text: "ok" } }] }, "t2"),
+    ];
+    const children = rows.map((tool) => buildTranscriptRow(tool));
+    const onExpanded = vi.fn();
+    const group = buildToolGroup("turn:u1", rows, children, false, onExpanded);
+    const head = group.querySelector<HTMLButtonElement>(".st-tool-group-head")!;
+    const body = group.querySelector<HTMLElement>(".st-tool-group-body")!;
+    expect(head.textContent).toContain("2 tool calls");
+    expect(body.hidden).toBe(true);
+    head.click();
+    expect(body.hidden).toBe(false);
+    expect(onExpanded).toHaveBeenCalledWith(true);
+    const toolHeads = group.querySelectorAll<HTMLButtonElement>(".st-tool-head");
+    toolHeads[1].click();
+    expect(toolHeads[0].getAttribute("aria-expanded")).toBe("false");
+    expect(toolHeads[1].getAttribute("aria-expanded")).toBe("true");
+  });
+});
+
+describe("buildTranscriptRow: tool diffs", () => {
+  it("shows +added -removed derived from the diff, and renders coloured hunks on expand", () => {
+    const el = buildTranscriptRow(
+      row("tool_diff", {
+        title: "Edit(x.rs)",
+        status: "completed",
+        content: [{ type: "diff", path: "/repo/x.rs", oldText: "a\nb\n", newText: "a\nc\n" }],
+      }),
+    );
+    const meta = el.querySelector(".st-tool-meta")!;
+    expect(meta.textContent).toContain("+1");
+    expect(meta.textContent).toContain("−1");
+    (el.querySelector(".st-tool-head") as HTMLButtonElement).click();
+    const diff = el.querySelector(".st-diff") as HTMLElement;
+    expect(diff).not.toBeNull();
+    expect(diff.querySelector(".st-ln-add")!.textContent).toBe("c");
+    expect(diff.querySelector(".st-ln-del")!.textContent).toBe("b");
+  });
+
+  it("gives the diff its own horizontally-scrolling container", () => {
+    const el = buildTranscriptRow(
+      row("tool_diff", {
+        title: "Edit(x.rs)",
+        content: [{ type: "diff", path: "/repo/x.rs", newText: "new file\n" }],
+      }),
+    );
+    (el.querySelector(".st-tool-head") as HTMLButtonElement).click();
+    // jsdom/happy-dom doesn't compute layout CSS, so assert the class the
+    // stylesheet keys `overflow-x: auto` off, not a computed style.
+    expect(el.querySelector(".st-diff")!.classList).toContain("st-diff");
+  });
+
+  it("renders a visible marker for a removed final newline", () => {
+    const el = buildTranscriptRow(
+      row("tool_diff", {
+        title: "Edit(x.rs)",
+        content: [{ type: "diff", path: "/repo/x.rs", oldText: "same\n", newText: "same" }],
+      }),
+    );
+    (el.querySelector(".st-tool-head") as HTMLButtonElement).click();
+    expect(el.querySelector(".st-ln-eof")!.textContent).toBe("\\ No newline at end of file");
+  });
+});
+
+describe("buildTranscriptRow: approval", () => {
+  const approvalRow = (options: Array<{ optionId: string; name: string; kind: string }>) =>
+    row("approval", {
+      sessionId: "s1",
+      toolCall: { toolCallId: "t1", title: "Write outside worktree", locations: [{ path: "/etc/x" }] },
+      options,
+    });
+
+  const allThreeOptions = [
+    { optionId: "a1", name: "Allow once", kind: "allow_once" },
+    { optionId: "a2", name: "Allow always", kind: "allow_always" },
+    { optionId: "r1", name: "Reject once", kind: "reject_once" },
+  ];
+
+  it("shows the three decision buttons only when the request offers all three option kinds", () => {
+    const el = buildTranscriptRow(approvalRow(allThreeOptions), {
+      pending: true,
+      onDecide: () => Promise.resolve(),
+    });
+    const buttons = el.querySelectorAll(".st-approval-acts button");
+    expect(buttons).toHaveLength(3);
+    expect(el.querySelector(".st-approval-path")!.textContent).toBe("/etc/x");
+  });
+
+  it("hides the buttons and shows an answered note once resolved", () => {
+    const el = buildTranscriptRow(approvalRow(allThreeOptions), {
+      pending: false,
+      onDecide: () => Promise.resolve(),
+    });
+    expect(el.querySelector(".st-approval-acts")).toBeNull();
+    expect(el.querySelector(".st-approval-resolved")!.textContent).toBe("answered");
+  });
+
+  it("invokes onDecide with the clicked decision and disables the buttons", () => {
+    const onDecide = vi.fn().mockResolvedValue(undefined);
+    const el = buildTranscriptRow(approvalRow(allThreeOptions), { pending: true, onDecide });
+    const buttons = el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    buttons[2].click();
+    expect(onDecide).toHaveBeenCalledWith("deny");
+    expect(buttons[0].disabled).toBe(true);
+  });
+
+  it("treats a row with no approval state as not pending, defensively", () => {
+    const el = buildTranscriptRow(approvalRow(allThreeOptions));
+    expect(el.querySelector(".st-approval-acts")).toBeNull();
+  });
+
+  it("omits Allow for session when the request offers no allow_always option", () => {
+    const el = buildTranscriptRow(
+      approvalRow([
+        { optionId: "a1", name: "Allow once", kind: "allow_once" },
+        { optionId: "r1", name: "Reject once", kind: "reject_once" },
+      ]),
+      { pending: true, onDecide: () => Promise.resolve() },
+    );
+    const labels = [...el.querySelectorAll(".st-approval-acts button")].map((b) => b.textContent);
+    expect(labels).toEqual(["Allow once", "Deny"]);
+  });
+
+  it("offers Deny for either reject_once or reject_always, never for neither", () => {
+    const rejectAlwaysOnly = buildTranscriptRow(
+      approvalRow([{ optionId: "r2", name: "Reject always", kind: "reject_always" }]),
+      { pending: true, onDecide: () => Promise.resolve() },
+    );
+    expect([...rejectAlwaysOnly.querySelectorAll(".st-approval-acts button")].map((b) => b.textContent)).toEqual([
+      "Deny",
+    ]);
+  });
+
+  it("shows a 'no decision offered' note instead of an empty action row when nothing matches", () => {
+    const el = buildTranscriptRow(approvalRow([{ optionId: "x", name: "Something else", kind: "allow_once" }]), {
+      pending: true,
+      onDecide: () => Promise.resolve(),
+    });
+    // allow_once is offered, so this specific case still shows a button —
+    // use a kind the client doesn't map to any decision at all.
+    expect(el.querySelectorAll(".st-approval-acts button")).toHaveLength(1);
+
+    const none = buildTranscriptRow(approvalRow([]), { pending: true, onDecide: () => Promise.resolve() });
+    expect(none.querySelector(".st-approval-acts")).toBeNull();
+    expect(none.querySelector(".st-approval-resolved")!.textContent).toBe("no decision offered");
+  });
+
+  it("re-enables the buttons when onDecide rejects", async () => {
+    const onDecide = vi.fn().mockRejectedValue(new Error("network down"));
+    const el = buildTranscriptRow(approvalRow(allThreeOptions), { pending: true, onDecide });
+    const buttons = el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    buttons[0].click();
+    expect(buttons[0].disabled).toBe(true);
+    await Promise.resolve().then(() => Promise.resolve());
+    expect(buttons[0].disabled).toBe(false);
+    expect(buttons[1].disabled).toBe(false);
+  });
+
+  it("leaves the buttons disabled when onDecide resolves", async () => {
+    const onDecide = vi.fn().mockResolvedValue(undefined);
+    const el = buildTranscriptRow(approvalRow(allThreeOptions), { pending: true, onDecide });
+    const buttons = el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    buttons[0].click();
+    await Promise.resolve().then(() => Promise.resolve());
+    expect(buttons[0].disabled).toBe(true);
+  });
+});
+
+describe("buildTranscriptRow: notice / unknown kinds", () => {
+  it("renders durable per-turn duration and context usage", () => {
+    const el = buildTranscriptRow(
+      row("notice", {
+        maestroTurnMeta: {
+          elapsedMs: 72_000,
+          contextTokens: 18_400,
+          contextDelta: 2_350,
+          outcome: "completed",
+          model: "opus",
+        },
+      }, "turn:1"),
+    )!;
+
+    expect(el.classList.contains("st-turn-meta")).toBe(true);
+    expect(el.textContent).toContain("1m 12s · +2.4k context tokens · opus");
+    expect(el.getAttribute("aria-label")).toBe("Copy turn details");
+  });
+
+  it("renders notice and unknown row kinds safely", () => {
+    expect(buildTranscriptRow(row("notice", { sessionUpdate: "future" }))?.textContent).toBe(
+      "[notice]",
+    );
+    const unknown = { id: "r1", kind: "future_kind", data: {} } as unknown as TranscriptRow;
+    expect(buildTranscriptRow(unknown)?.textContent).toBe("[future_kind]");
+  });
+
+  it("omits command-catalog and session-info notices used only as UI state", () => {
+    expect(
+      buildTranscriptRow(
+        row("notice", { sessionUpdate: "available_commands_update", availableCommands: [] }),
+      ),
+    ).toBeNull();
+    expect(buildTranscriptRow(row("notice", { sessionUpdate: "session_info_update" }))).toBeNull();
+  });
+
+  it("returns no transcript element for a plan row", () => {
+    expect(buildTranscriptRow(row("plan", { entries: [] }))).toBeNull();
+  });
+});

web/src/structuredRender.ts

@@ -0,0 +1,638 @@
+// Pure per-row and rail DOM builders for the structured transcript (#140).
+// No socket, no daemon calls — structured.ts owns the connection and calls
+// into here with data already in hand, so every rendering decision here is
+// unit-testable without a WebSocket.
+
+import { escapeHtml } from "./html.js";
+import { marked, Renderer } from "marked";
+import { computeDiffLines, diffStats } from "./structuredDiff.js";
+import type {
+  AcpContentBlock,
+  AcpPermissionOption,
+  AcpToolCallContent,
+  AcpToolCallLike,
+  StructuredApprovalDecision,
+  TranscriptRow,
+  TurnMeta,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// row taxonomy
+// ---------------------------------------------------------------------------
+
+/** Glyph shown in a tool row's head, by `ToolKind`. Unrecognised/absent kinds
+ *  fall back to the generic bullet — never a blank glyph column. */
+const KIND_GLYPH: Record<string, string> = {
+  read: "≡",
+  edit: "±",
+  delete: "✕",
+  move: "→",
+  search: "⌕",
+  execute: "$",
+  think: "…",
+  fetch: "⇣",
+  switch_mode: "⇄",
+};
+
+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",
+};
+
+function toolGlyph(kind: string | undefined): string {
+  return (kind && KIND_GLYPH[kind]) || "•";
+}
+
+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. */
+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 };
+}
+
+function el(tag: string, className?: string): HTMLElement {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  return node;
+}
+
+/** Content-block text, or a labelled placeholder for anything that isn't
+ *  text — never dropped silently, never fabricated. */
+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 "";
+  }
+}
+
+/** Small inline renderer retained for compact labels and focused tests. */
+export function renderInlineMarkdown(text: string): string {
+  const escaped = escapeHtml(text);
+  return escaped
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "<em>$1</em>");
+}
+
+/** Render assistant output as GFM, then sanitize the complete result before it
+ * enters the DOM. This gives transcripts proper tables, lists, code blocks and
+ * links without trusting model-authored HTML or URL attributes. */
+export function renderMarkdown(text: string): string {
+  const renderer = new Renderer();
+  renderer.html = ({ text: raw }) => escapeHtml(raw);
+  renderer.image = ({ text: alt }) => escapeHtml(alt ? `[image: ${alt}]` : "[image]");
+  renderer.link = ({ href, title, tokens }) => {
+    const label = renderer.parser.parseInline(tokens);
+    const scheme = /^([a-z][a-z\d+.-]*):/i.exec(href.trim())?.[1]?.toLowerCase();
+    if (scheme && !["http", "https", "mailto"].includes(scheme)) return label;
+    const safeTitle = title ? ` title="${escapeHtml(title)}"` : "";
+    return `<a href="${escapeHtml(href)}"${safeTitle}>${label}</a>`;
+  };
+
+  return marked.parse(text, { async: false, gfm: true, renderer });
+}
+
+function renderProse(container: HTMLElement, text: string): void {
+  container.innerHTML = renderMarkdown(text);
+
+  for (const table of Array.from(container.querySelectorAll("table"))) {
+    const scroller = el("div", "st-markdown-table-wrap");
+    table.replaceWith(scroller);
+    scroller.appendChild(table);
+  }
+
+  for (const link of container.querySelectorAll("a")) {
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+  }
+}
+
+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");
+  }
+}
+
+function makeCopyable(node: HTMLElement, text: string, label: string): void {
+  if (!text) return;
+  node.classList.add("st-copyable");
+  node.tabIndex = 0;
+  node.setAttribute("role", "button");
+  node.setAttribute("aria-label", `Copy ${label}`);
+  node.title = `Copy ${label}`;
+
+  const copy = () => {
+    void writeClipboard(text).then(
+      () => {
+        node.dataset.copyState = "copied";
+        node.setAttribute("aria-label", `${label} copied`);
+        window.setTimeout(() => {
+          delete node.dataset.copyState;
+          node.setAttribute("aria-label", `Copy ${label}`);
+        }, 1200);
+      },
+      () => {
+        node.dataset.copyState = "error";
+      },
+    );
+  };
+  node.addEventListener("click", (event) => {
+    if ((event.target as Element | null)?.closest("a")) return;
+    copy();
+  });
+  node.addEventListener("keydown", (event) => {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+    copy();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// row builders
+// ---------------------------------------------------------------------------
+
+function buildContentRow(row: TranscriptRow, variant: "user" | "agent" | "thought"): HTMLElement {
+  const data = row.data as { content?: AcpContentBlock; messageId?: string } | undefined;
+  const text = contentBlockText(data?.content);
+  const wrap = el("div", `st-row st-row-${variant}`);
+  const body = el("div", "st-body");
+  if (variant === "user") {
+    const line = el("div", "st-user-text");
+    line.textContent = text;
+    body.appendChild(line);
+  } else if (variant === "agent") {
+    renderProse(body, text);
+  } else {
+    body.textContent = text;
+  }
+  wrap.appendChild(body);
+  const label = variant === "user" ? "message" : variant === "agent" ? "response" : "thought";
+  makeCopyable(wrap, text, label);
+  return wrap;
+}
+
+function buildDiffBlock(diff: { path: string; oldText?: string | null; newText: string }): HTMLElement {
+  const wrap = el("div", "st-diff-block");
+  const label = el("div", "st-diff-path");
+  label.textContent = diff.path;
+  label.title = diff.path;
+  makeCopyable(label, diff.path, "path");
+  wrap.appendChild(label);
+  const scroller = el("div", "st-diff");
+  const pre = document.createElement("pre");
+  for (const line of computeDiffLines(diff.oldText, diff.newText)) {
+    const span = document.createElement("span");
+    span.className = `st-ln st-ln-${line.kind}`;
+    span.textContent = line.text;
+    pre.appendChild(span);
+    pre.appendChild(document.createTextNode("\n"));
+  }
+  scroller.appendChild(pre);
+  makeCopyable(scroller, pre.textContent ?? "", "diff");
+  wrap.appendChild(scroller);
+  return wrap;
+}
+
+function printable(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function toolInput(tool: AcpToolCallLike): { command: string | null; input: string | null } {
+  const raw = tool.rawInput;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { command: null, input: printable(raw) };
+  }
+  const record = raw as Record<string, unknown>;
+  const command = typeof record.command === "string" ? record.command : null;
+  if (!command) return { command: null, input: printable(raw) };
+  const rest = Object.fromEntries(Object.entries(record).filter(([key]) => key !== "command"));
+  return { command, input: Object.keys(rest).length > 0 ? printable(rest) : null };
+}
+
+function appendToolDetail(container: HTMLElement, label: string, text: string): void {
+  const detail = el("div", "st-tool-detail");
+  const heading = el("div", "st-tool-detail-label");
+  heading.textContent = label;
+  const value = document.createElement("pre");
+  value.textContent = text;
+  makeCopyable(value, text, label.toLowerCase());
+  detail.append(heading, value);
+  container.appendChild(detail);
+}
+
+/** `+added -removed` across every diff block in a tool call's content —
+ *  real derived data, never a fabricated duration. */
+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}`;
+}
+
+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;
+}
+
+function buildToolRow(
+  row: TranscriptRow,
+  expanded: boolean,
+  onExpandedChange?: (expanded: boolean) => void,
+): HTMLElement {
+  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 wrap = el("div", "st-row st-row-tool");
+  const card = el("div", "st-tool");
+  wrap.appendChild(card);
+
+  const head = document.createElement("button");
+  head.type = "button";
+  head.className = "st-tool-head";
+  head.setAttribute("aria-expanded", "false");
+
+  const glyph = el("span", "st-tool-glyph");
+  glyph.textContent = toolGlyph(tool.kind);
+  glyph.setAttribute("aria-hidden", "true");
+  const name = el("span", "st-tool-name");
+  name.textContent = label;
+  const argEl = el("span", "st-tool-arg");
+  argEl.textContent = arg;
+  argEl.title = arg;
+  head.append(glyph, name, argEl);
+
+  const metaParts: string[] = [];
+  if (hasDiff) metaParts.push(toolDiffMeta(content));
+  const meta = statusMeta(tool.status, hasDiff);
+  if (meta) metaParts.push(meta.text);
+  if (metaParts.length > 0) {
+    const metaEl = el("span", "st-tool-meta");
+    if (meta) metaEl.classList.add(`st-tool-meta-${meta.kind}`);
+    metaEl.textContent = metaParts.join(" · ");
+    head.appendChild(metaEl);
+  }
+  card.appendChild(head);
+
+  const out = el("div", "st-tool-out");
+  out.hidden = true;
+  let outBuilt = false;
+  const buildOut = () => {
+    if (outBuilt) return;
+    outBuilt = true;
+    const { command, input } = toolInput(tool);
+    if (command) appendToolDetail(out, "Command", command);
+    if (input !== null) appendToolDetail(out, "Input", input);
+    const rawOutput = printable(tool.rawOutput);
+    if (rawOutput !== null) appendToolDetail(out, "Output", rawOutput);
+    const texts = content
+      .filter((c): c is Extract<AcpToolCallContent, { type: "content" }> => c.type === "content")
+      .map((c) => contentBlockText(c.content))
+      .filter(Boolean);
+    const contentText = texts.join("\n");
+    if (contentText && contentText !== rawOutput) {
+      const textPanel = el("div", "st-tool-text");
+      textPanel.textContent = contentText;
+      makeCopyable(textPanel, contentText, "output");
+      out.appendChild(textPanel);
+    }
+    for (const block of content) {
+      if (block.type === "diff") out.appendChild(buildDiffBlock(block));
+      if (block.type === "terminal") {
+        const note = el("div", "st-tool-text");
+        note.textContent = "[embedded terminal]";
+        out.appendChild(note);
+      }
+    }
+    if (out.children.length === 0) out.hidden = true;
+  };
+  card.appendChild(out);
+
+  const setExpanded = (nextExpanded: boolean) => {
+    if (nextExpanded) buildOut();
+    if (out.children.length === 0) nextExpanded = false;
+    head.setAttribute("aria-expanded", String(nextExpanded));
+    out.hidden = !nextExpanded;
+  };
+  head.addEventListener("click", () => {
+    setExpanded(head.getAttribute("aria-expanded") !== "true");
+    onExpandedChange?.(head.getAttribute("aria-expanded") === "true");
+  });
+  setExpanded(expanded);
+
+  return wrap;
+}
+
+export function buildToolGroup(
+  id: string,
+  rows: TranscriptRow[],
+  children: HTMLElement[],
+  expanded: boolean,
+  onExpandedChange?: (expanded: boolean) => void,
+): HTMLElement {
+  const wrap = el("div", "st-tool-group");
+  wrap.dataset.toolGroupId = id;
+  const head = document.createElement("button");
+  head.type = "button";
+  head.className = "st-tool-group-head";
+  head.setAttribute("aria-expanded", String(expanded));
+
+  const glyph = el("span", "st-tool-group-glyph");
+  glyph.textContent = "›";
+  glyph.setAttribute("aria-hidden", "true");
+  const title = el("span", "st-tool-group-title");
+  title.textContent = `${rows.length} tool calls`;
+  const names = el("span", "st-tool-group-names");
+  names.textContent = rows
+    .map((row) => {
+      const tool = (row.data ?? {}) as AcpToolCallLike;
+      return splitToolTitle(tool.title, tool.name, tool.kind).label;
+    })
+    .join(" · ");
+  head.append(glyph, title, names);
+
+  const body = el("div", "st-tool-group-body");
+  body.hidden = !expanded;
+  body.append(...children);
+  head.addEventListener("click", () => {
+    expanded = !expanded;
+    head.setAttribute("aria-expanded", String(expanded));
+    body.hidden = !expanded;
+    onExpandedChange?.(expanded);
+  });
+  wrap.append(head, body);
+  return wrap;
+}
+
+function buildPlainRow(row: TranscriptRow): HTMLElement {
+  const wrap = el("div", "st-row st-row-notice");
+  const body = el("div", "st-body");
+  body.textContent = `[${row.kind}]`;
+  wrap.appendChild(body);
+  makeCopyable(wrap, body.textContent, "notice");
+  return wrap;
+}
+
+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 formatElapsed(milliseconds: number): string {
+  const seconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return remainder === 0 ? `${minutes}m` : `${minutes}m ${remainder}s`;
+}
+
+export function formatContextTokens(value: number): string {
+  return `${compactNumber(value)} context`;
+}
+
+function buildTurnMetaRow(meta: TurnMeta): HTMLElement {
+  const wrap = el("div", `st-turn-meta st-turn-meta-${meta.outcome}`);
+  wrap.setAttribute("aria-label", `Turn ${meta.outcome}`);
+  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(formatContextTokens(meta.contextTokens));
+  }
+  if (meta.model) parts.push(meta.model);
+  if (meta.outcome !== "completed") parts.push(meta.outcome);
+  const dot = el("span", "st-turn-meta-dot");
+  dot.setAttribute("aria-hidden", "true");
+  const text = el("span");
+  text.textContent = parts.join(" · ");
+  wrap.append(dot, text);
+  makeCopyable(wrap, text.textContent, "turn details");
+  return wrap;
+}
+
+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;
+}
+
+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";
+}
+
+export interface ApprovalRowState {
+  pending: boolean;
+  /** Resolves once the decision has been submitted; rejects when the POST
+   *  failed and this approval is still the one awaiting a decision, so the
+   *  caller knows to restore its controls. Never rejects for a stale click
+   *  (the approval already moved on) — there is nothing to restore then. */
+  onDecide: (decision: StructuredApprovalDecision) => Promise<void>;
+}
+
+/** 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. */
+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;
+}
+
+function buildApprovalRow(row: TranscriptRow, approval: ApprovalRowState): HTMLElement {
+  const request = (row.data ?? {}) as { toolCall?: AcpToolCallLike; options?: AcpPermissionOption[] };
+  const toolCall = request.toolCall ?? {};
+  const wrap = el("div", "st-row st-row-approval");
+  const card = el("div", "st-approval");
+  wrap.appendChild(card);
+
+  const title = el("div", "st-approval-title");
+  title.innerHTML = `<span aria-hidden="true">⚠</span> permission requested`;
+  card.appendChild(title);
+
+  const what = el("div", "st-approval-what");
+  what.textContent = toolCall.title ?? toolKindLabel(toolCall.kind);
+  card.appendChild(what);
+
+  const path = toolCall.locations?.[0]?.path;
+  if (path) {
+    const pathEl = el("div", "st-approval-path");
+    pathEl.textContent = path;
+    card.appendChild(pathEl);
+  }
+
+  if (approval.pending) {
+    const acts = el("div", "st-approval-acts");
+    const mk = (label: string, decision: StructuredApprovalDecision, cls: string) => {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = cls ? `act ${cls}` : "act";
+      btn.textContent = label;
+      btn.addEventListener("click", () => {
+        const buttons = [...acts.querySelectorAll<HTMLButtonElement>("button")];
+        buttons.forEach((b) => (b.disabled = true));
+        approval.onDecide(decision).catch(() => {
+          // Rejects only when this approval is still pending (see
+          // ApprovalRowState) — restore the controls so the operator can
+          // retry; the error itself is surfaced by the connection.
+          buttons.forEach((b) => (b.disabled = false));
+        });
+      });
+      return btn;
+    };
+    const offered = offeredDecisions(request.options ?? []);
+    const specs: [StructuredApprovalDecision, string, string][] = [
+      ["allow_once", "Allow once", "primary"],
+      ["allow_for_session", "Allow for session", ""],
+      ["deny", "Deny", "deny"],
+    ];
+    for (const [decision, label, cls] of specs) {
+      if (offered.includes(decision)) acts.appendChild(mk(label, decision, cls));
+    }
+    if (acts.children.length > 0) {
+      card.appendChild(acts);
+    } else {
+      const none = el("div", "st-approval-resolved");
+      none.textContent = "no decision offered";
+      card.appendChild(none);
+    }
+  } else {
+    const resolved = el("div", "st-approval-resolved");
+    resolved.textContent = "answered";
+    card.appendChild(resolved);
+  }
+
+  return wrap;
+}
+
+/** Build the DOM for one transcript row, or `null` for state-only plan rows.
+ *  `approval` is consulted only for an `approval` row; tool
+ *  expansion is supplied and reported explicitly. */
+export function buildTranscriptRow(
+  row: TranscriptRow & { kind: "plan" },
+  approval?: ApprovalRowState,
+  toolExpanded?: boolean,
+  onToolExpandedChange?: (expanded: boolean) => void,
+): null;
+export function buildTranscriptRow(
+  row: TranscriptRow & { kind: "notice" },
+  approval?: ApprovalRowState,
+  toolExpanded?: boolean,
+  onToolExpandedChange?: (expanded: boolean) => void,
+): HTMLElement | null;
+export function buildTranscriptRow(
+  row: TranscriptRow & { kind: Exclude<TranscriptRow["kind"], "plan" | "notice"> },
+  approval?: ApprovalRowState,
+  toolExpanded?: boolean,
+  onToolExpandedChange?: (expanded: boolean) => void,
+): HTMLElement;
+export function buildTranscriptRow(
+  row: TranscriptRow,
+  approval?: ApprovalRowState,
+  toolExpanded?: boolean,
+  onToolExpandedChange?: (expanded: boolean) => void,
+): HTMLElement | null;
+export function buildTranscriptRow(
+  row: TranscriptRow,
+  approval?: ApprovalRowState,
+  toolExpanded = false,
+  onToolExpandedChange?: (expanded: boolean) => void,
+): HTMLElement | null {
+  let built: HTMLElement;
+  switch (row.kind) {
+    case "user":
+      built = buildContentRow(row, "user");
+      break;
+    case "agent_text":
+      built = buildContentRow(row, "agent");
+      break;
+    case "agent_thought":
+      built = buildContentRow(row, "thought");
+      break;
+    case "tool_call":
+    case "tool_diff":
+      built = buildToolRow(row, toolExpanded, onToolExpandedChange);
+      break;
+    case "approval":
+      built = buildApprovalRow(row, approval ?? { pending: false, onDecide: () => Promise.resolve() });
+      break;
+    case "plan":
+      return null;
+    case "notice":
+      if (isStateOnlyNotice(row)) return null;
+      built = turnMeta(row) ? buildTurnMetaRow(turnMeta(row)!) : buildPlainRow(row);
+      break;
+    default:
+      built = buildPlainRow(row);
+      break;
+  }
+  built.dataset.rowId = row.id;
+  return built;
+}

web/src/styles.css

@@ -1892,6 +1892,7 @@ input.leaf-rename:focus {
   align-items: center;
   gap: var(--sp-2);
   height: var(--bar-h);
+  flex: 0 0 var(--bar-h);
   padding: 0 var(--sp-2);
   border-bottom: 1px solid var(--border);
   background: var(--surface);
@@ -2165,6 +2166,972 @@ input.leaf-rename:focus {
   border-color: var(--accent-strong);
 }
 
+/* ---------- structured view (#140) ----------
+   `.attach.structured` reuses `.attach`'s flex column, `.attach-header` and
+   `.attach-state` verbatim (attach.ts and structured.ts share paneTitle.ts's
+   header markup) — only the body differs: a transcript and composer instead
+   of an xterm surface. Hierarchy is deliberate: the approval is the
+   only lifted, card-like element on the page; everything else is either a
+   tinted block (user), plain text (agent), or a thin bordered row (tool). */
+
+.structured-config {
+  position: relative;
+  flex: 0 0 40px;
+}
+
+.structured-config-trigger {
+  width: 40px;
+  height: 40px;
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  padding: 0;
+  border: 0;
+  border-radius: var(--r-2);
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+}
+
+.structured-config-trigger svg {
+  width: 18px;
+  height: 18px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.75;
+  stroke-linecap: round;
+}
+
+.structured-config-trigger:hover,
+.structured-config-trigger[aria-expanded="true"] {
+  color: var(--ink);
+  background: var(--surface-3);
+}
+
+.structured-config-trigger:focus-visible,
+.structured-config-select:focus-visible,
+.structured-config-toggle:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.structured-config-menu {
+  position: absolute;
+  z-index: 20;
+  bottom: calc(100% + var(--sp-2));
+  right: 0;
+  width: min(320px, 86vw);
+  padding: var(--sp-2);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--r-2);
+  background: var(--surface);
+  box-shadow: var(--shadow-2);
+}
+
+.structured-config-row {
+  display: grid;
+  grid-template-columns: minmax(80px, 1fr) minmax(0, 1.6fr);
+  align-items: center;
+  gap: var(--sp-3);
+  min-height: 34px;
+  padding: var(--sp-1) var(--sp-2);
+  color: var(--ink);
+  font-size: var(--fs-12);
+}
+
+.structured-config-row + .structured-config-row {
+  border-top: 1px solid var(--border);
+}
+
+.structured-config-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.structured-config-select {
+  min-width: 0;
+  height: 28px;
+  padding: 0 var(--sp-2);
+  border: 1px solid var(--border);
+  border-radius: var(--r-1);
+  background: var(--surface-2);
+  color: var(--ink);
+  font: inherit;
+}
+
+.structured-config-toggle {
+  justify-self: end;
+  width: 17px;
+  height: 17px;
+  accent-color: var(--accent);
+}
+
+.structured-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  display: flex;
+}
+
+.attach.structured,
+.attach.structured .attach-title,
+.structured-input {
+  font-family: var(--font-sans);
+}
+
+.st-row-agent code,
+.st-tool-text,
+.st-tool-detail pre,
+.st-diff,
+.st-approval-path {
+  font-family: var(--font-mono);
+}
+
+.structured-main {
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+}
+
+.structured-scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+  min-width: 0;
+  overflow-y: auto;
+}
+
+.structured-rows {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.structured-activity {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  min-height: 30px;
+  padding: var(--sp-1) var(--sp-3);
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  background: var(--surface-2);
+  font-size: var(--fs-11);
+  font-variant-numeric: tabular-nums;
+}
+
+.structured-activity[hidden] {
+  display: none;
+}
+
+.structured-activity-pulse {
+  position: relative;
+  width: 7px;
+  height: 7px;
+  flex: 0 0 auto;
+  border-radius: 50%;
+  background: var(--live);
+  box-shadow: 0 0 0 0 var(--live-glow);
+  animation: structured-thinking 1.6s ease-out infinite;
+}
+
+@keyframes structured-thinking {
+  50% {
+    box-shadow: 0 0 0 5px transparent;
+  }
+}
+
+/* every transcript row carries its own layout; none of them are cards */
+.st-row {
+  display: flex;
+  gap: var(--sp-3);
+  padding: var(--sp-3);
+  min-width: 0;
+}
+
+.st-body {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* User turns read as compact chat bubbles while the padded row remains the
+   full hover/copy target. */
+.st-row-user {
+  justify-content: flex-end;
+}
+
+.st-row-user .st-body {
+  flex: 0 1 auto;
+  max-width: min(86%, 72ch);
+  padding: var(--sp-2) var(--sp-3);
+  border-radius: var(--r-2);
+  background: var(--surface-3);
+}
+
+.st-row-user:hover {
+  background: var(--surface-2);
+}
+
+.st-user-text {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+/* agent prose: no card, no background — plain text is the point */
+.st-row-agent .st-body p {
+  margin: 0 0 var(--sp-2);
+  overflow-wrap: anywhere;
+}
+
+.st-row-agent .st-body p:last-child {
+  margin-bottom: 0;
+}
+
+.st-row-agent .st-body > :first-child {
+  margin-top: 0;
+}
+
+.st-row-agent .st-body > :last-child {
+  margin-bottom: 0;
+}
+
+.st-row-agent .st-body h1,
+.st-row-agent .st-body h2,
+.st-row-agent .st-body h3,
+.st-row-agent .st-body h4 {
+  margin: var(--sp-4) 0 var(--sp-2);
+  color: var(--ink);
+  font-size: var(--fs-14);
+  line-height: 1.35;
+}
+
+.st-row-agent .st-body ul,
+.st-row-agent .st-body ol {
+  margin: var(--sp-2) 0;
+  padding-left: var(--sp-5);
+}
+
+.st-row-agent .st-body li + li {
+  margin-top: var(--sp-1);
+}
+
+.st-row-agent .st-body pre {
+  margin: var(--sp-2) 0;
+  padding: var(--sp-3);
+  overflow-x: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--r-2);
+  background: var(--surface-2);
+}
+
+.st-row-agent .st-body pre code {
+  padding: 0;
+  border: 0;
+  background: transparent;
+}
+
+.st-row-agent .st-body a {
+  color: var(--ink);
+  text-decoration-color: var(--border-strong);
+  text-underline-offset: 2px;
+}
+
+.st-markdown-table-wrap {
+  max-width: 100%;
+  margin: var(--sp-2) 0;
+  overflow-x: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--r-2);
+}
+
+.st-row-agent table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--fs-12);
+}
+
+.st-row-agent th,
+.st-row-agent td {
+  padding: var(--sp-2) var(--sp-3);
+  border-bottom: 1px solid var(--border);
+  text-align: left;
+  vertical-align: top;
+  white-space: nowrap;
+}
+
+.st-row-agent th {
+  color: var(--ink);
+  background: var(--surface-2);
+  font-weight: 600;
+}
+
+.st-row-agent tr:last-child td {
+  border-bottom: 0;
+}
+
+.st-row-agent code {
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: var(--r-1);
+  padding: 0 3px;
+  font-size: 0.92em;
+}
+
+.st-row-thought {
+  color: var(--faint);
+  font-style: italic;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.st-row-notice {
+  color: var(--faint);
+  font-size: var(--fs-12);
+}
+
+.st-turn-meta {
+  align-self: flex-start;
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  margin: 0 var(--sp-3) var(--sp-2);
+  padding: var(--sp-1) var(--sp-2);
+  border-radius: var(--r-1);
+  color: var(--faint);
+  font-size: var(--fs-11);
+  font-variant-numeric: tabular-nums;
+}
+
+.st-turn-meta:hover {
+  background: var(--surface-2);
+  color: var(--muted);
+}
+
+.st-turn-meta-dot {
+  width: 5px;
+  height: 5px;
+  flex: 0 0 auto;
+  border-radius: 50%;
+  background: var(--live);
+}
+
+.st-turn-meta-cancelled .st-turn-meta-dot {
+  background: var(--warn);
+}
+
+.st-turn-meta-failed .st-turn-meta-dot {
+  background: var(--danger);
+}
+
+.st-copyable {
+  position: relative;
+  border-radius: var(--r-1);
+  cursor: copy;
+  transition: background var(--dur-fast) var(--ease-out);
+}
+
+.st-copyable::after {
+  content: "copy";
+  position: absolute;
+  top: var(--sp-1);
+  right: var(--sp-1);
+  padding: 1px var(--sp-1);
+  border-radius: var(--r-1);
+  background: var(--surface-3);
+  color: var(--faint);
+  font-size: var(--fs-11);
+  font-style: normal;
+  line-height: 1.4;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity var(--dur-fast) var(--ease-out);
+}
+
+.st-copyable:hover,
+.st-copyable:focus-visible {
+  background: var(--surface-2);
+  outline: none;
+}
+
+.st-copyable:hover::after,
+.st-copyable:focus-visible::after,
+.st-copyable[data-copy-state="copied"]::after,
+.st-copyable[data-copy-state="error"]::after {
+  opacity: 1;
+}
+
+.st-copyable[data-copy-state="copied"]::after {
+  content: "copied";
+  color: var(--live);
+}
+
+.st-copyable[data-copy-state="error"]::after {
+  content: "copy failed";
+  color: var(--danger);
+}
+
+/* tool rows: bordered, compact, deliberately not lifted */
+.st-tool {
+  flex: 1 1 auto;
+  border: 1px solid var(--border);
+  border-radius: var(--r-2);
+  min-width: 0;
+}
+
+.st-tool-head {
+  appearance: none;
+  width: 100%;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  padding: var(--sp-2) var(--sp-3);
+  min-width: 0;
+}
+
+.st-tool-head:hover {
+  background: var(--surface-2);
+}
+
+.st-row-tool:hover,
+.st-row-approval:hover {
+  background: var(--surface-2);
+}
+
+.st-tool-glyph {
+  width: 16px;
+  flex: 0 0 auto;
+  text-align: center;
+  color: var(--faint);
+}
+
+.st-tool-name {
+  font-weight: 500;
+  flex: 0 0 auto;
+}
+
+.st-tool-arg {
+  color: var(--muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+  text-align: left;
+}
+
+.st-tool-meta {
+  margin-left: auto;
+  flex: 0 0 auto;
+  font-size: var(--fs-11);
+  color: var(--faint);
+  font-variant-numeric: tabular-nums;
+}
+
+.st-tool-meta-running {
+  color: var(--live);
+}
+
+.st-tool-meta-failed {
+  color: var(--danger);
+}
+
+.st-tool-out {
+  border-top: 1px solid var(--border);
+  padding: var(--sp-2) var(--sp-3);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+}
+
+/* `display: flex` above outranks the UA sheet's `[hidden]` (same pitfall as
+   `.wt-step`/`.raw-wrap`) — restate it explicitly. */
+.st-tool-out[hidden] {
+  display: none;
+}
+
+.st-tool-text {
+  font-size: var(--fs-12);
+  color: var(--muted);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  overflow-x: auto;
+}
+
+.st-tool-detail {
+  min-width: 0;
+}
+
+.st-tool-detail-label {
+  margin-bottom: var(--sp-1);
+  color: var(--faint);
+  font-size: var(--fs-11);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.st-tool-detail pre {
+  margin: 0;
+  padding: var(--sp-2);
+  border: 1px solid var(--border);
+  border-radius: var(--r-1);
+  background: var(--bg);
+  color: var(--muted);
+  font: inherit;
+  font-size: var(--fs-12);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  overflow-x: auto;
+}
+
+.st-tool-group {
+  min-width: 0;
+  border: 1px solid var(--border);
+  border-radius: var(--r-2);
+  background: color-mix(in oklab, var(--surface-2) 55%, transparent);
+  padding: var(--sp-2) var(--sp-3);
+  transition: background var(--dur-fast) var(--ease-out);
+}
+
+.st-tool-group:hover {
+  background: var(--surface-2);
+}
+
+.st-tool-group-head {
+  appearance: none;
+  width: 100%;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  padding: 0;
+  min-width: 0;
+}
+
+.st-tool-group-head:hover {
+  background: var(--surface-2);
+}
+
+.st-tool-group-glyph {
+  color: var(--faint);
+  transition: transform var(--dur-fast) var(--ease-out);
+}
+
+.st-tool-group-head[aria-expanded="true"] .st-tool-group-glyph {
+  transform: rotate(90deg);
+}
+
+.st-tool-group-title {
+  flex: 0 0 auto;
+  font-weight: 500;
+}
+
+.st-tool-group-names {
+  min-width: 0;
+  overflow: hidden;
+  color: var(--muted);
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.st-tool-group-body {
+  padding-top: var(--sp-2);
+  display: flex;
+  flex-direction: column;
+}
+
+.st-tool-group-body > .st-row-tool {
+  padding: var(--sp-1) 0;
+}
+
+.st-tool-group-body[hidden] {
+  display: none;
+}
+
+.st-diff-block {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-1);
+}
+
+.st-diff-path {
+  font-size: var(--fs-11);
+  color: var(--muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* the diff gets its own horizontal scroller, independent of the page */
+.st-diff {
+  font-size: var(--fs-12);
+  overflow-x: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--r-1);
+}
+
+.st-diff pre {
+  margin: 0;
+}
+
+.st-ln {
+  display: block;
+  white-space: pre;
+  padding: 0 var(--sp-3);
+}
+
+.st-ln-add {
+  background: color-mix(in oklab, var(--live) 14%, transparent);
+}
+
+.st-ln-del {
+  background: var(--danger-tint);
+}
+
+.st-ln-ctx {
+  color: var(--muted);
+}
+
+.st-ln-hunk {
+  color: var(--faint);
+  background: var(--surface-2);
+}
+
+.st-ln-eof {
+  color: var(--faint);
+  font-style: italic;
+}
+
+/* the one lifted, card-like element on the surface: the only thing the
+   operator owes a decision on */
+.st-approval {
+  border: 1px solid var(--warn);
+  border-radius: var(--r-2);
+  background: color-mix(in oklab, var(--warn) 12%, var(--surface));
+  box-shadow: var(--shadow-1);
+  padding: var(--sp-3);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+  min-width: 0;
+}
+
+.st-approval-title {
+  color: var(--warn);
+  font-size: var(--fs-11);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+}
+
+.st-approval-what {
+  color: var(--ink);
+}
+
+.st-approval-path {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--r-1);
+  padding: var(--sp-2);
+  font-size: var(--fs-12);
+  overflow-x: auto;
+  white-space: pre;
+}
+
+.st-approval-acts {
+  display: flex;
+  gap: var(--sp-2);
+  flex-wrap: wrap;
+}
+
+.st-approval-resolved {
+  font-size: var(--fs-11);
+  color: var(--faint);
+}
+
+.act {
+  appearance: none;
+  font: inherit;
+  font-size: var(--fs-12);
+  height: 26px;
+  padding: 0 var(--sp-3);
+  border-radius: var(--r-2);
+  border: 1px solid var(--border-strong);
+  background: var(--surface);
+  color: var(--ink);
+  cursor: pointer;
+  transition:
+    transform var(--dur-fast) var(--ease-out),
+    background var(--dur-fast) var(--ease-out);
+}
+
+.act:hover {
+  background: var(--surface-3);
+}
+
+.act:active {
+  transform: translateY(1px);
+}
+
+.act:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.act.primary {
+  background: var(--accent);
+  color: var(--accent-ink);
+  border-color: var(--accent);
+  font-weight: 500;
+}
+
+.act.deny {
+  color: var(--danger);
+  border-color: color-mix(in oklab, var(--danger) 40%, transparent);
+}
+
+.act.deny:hover {
+  background: var(--danger-tint);
+  border-color: var(--danger);
+}
+
+/* The composer is a sibling of the scrolling transcript, not part of it: it
+   stays reachable at the pane edge without changing transcript scroll math. */
+.structured-composer {
+  flex: 0 0 auto;
+  margin: var(--sp-2) var(--sp-3) max(var(--sp-2), env(safe-area-inset-bottom));
+  padding: var(--sp-1);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--r-3);
+  background: var(--surface);
+  display: flex;
+  align-items: flex-end;
+  gap: var(--sp-1);
+  box-shadow:
+    inset 0 1px 0 color-mix(in oklab, var(--ink) 6%, transparent),
+    var(--shadow-1);
+  transition:
+    border-color var(--dur-fast) var(--ease-out),
+    box-shadow var(--dur-fast) var(--ease-out);
+}
+
+.structured-composer:focus-within {
+  border-color: var(--accent);
+  box-shadow:
+    inset 0 1px 0 color-mix(in oklab, var(--ink) 8%, transparent),
+    0 0 0 3px var(--accent-tint),
+    var(--shadow-1);
+}
+
+.structured-input-wrap {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.structured-input {
+  display: block;
+  width: 100%;
+  min-width: 0;
+  max-height: 160px;
+  min-height: 40px;
+  resize: none;
+  overflow-y: hidden;
+  padding: 10px var(--sp-2);
+  border: 0;
+  border-radius: var(--r-2);
+  background: transparent;
+  color: var(--ink);
+  font-size: var(--fs-13);
+  line-height: 20px;
+}
+
+.structured-composer .structured-send,
+.structured-composer .structured-cancel {
+  height: 40px;
+  min-height: 40px;
+  border-radius: var(--r-2);
+  font-family: var(--font-sans);
+}
+
+.structured-composer .structured-send {
+  gap: 6px;
+  padding: 0 var(--sp-3);
+  border-color: var(--accent);
+  background: var(--accent);
+  color: var(--accent-ink);
+  font-weight: 650;
+  box-shadow: inset 0 1px 0 color-mix(in oklab, white 24%, transparent);
+}
+
+.structured-composer .structured-send::before,
+.structured-composer .structured-send::after,
+.structured-composer .structured-cancel::before,
+.structured-composer .structured-cancel::after {
+  content: none;
+}
+
+.structured-composer .structured-send svg {
+  width: 16px;
+  height: 16px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  transition: transform var(--dur-fast) var(--ease-out);
+}
+
+.structured-composer .structured-send:hover {
+  background: var(--accent-strong);
+  border-color: var(--accent-strong);
+  color: var(--accent-ink);
+}
+
+.structured-composer .structured-send:hover svg {
+  transform: translateX(2px);
+}
+
+.structured-composer .structured-cancel {
+  padding: 0 var(--sp-3);
+  border-color: color-mix(in oklab, var(--danger) 35%, var(--border));
+  color: var(--danger);
+}
+
+.structured-composer .structured-cancel:hover {
+  background: var(--danger-tint);
+}
+
+@media (max-width: 520px) {
+  .structured-config-menu {
+    right: calc(-1 * (var(--control-h) + var(--sp-2)));
+  }
+}
+
+.structured-command-menu {
+  position: absolute;
+  z-index: var(--z-sticky);
+  right: 0;
+  bottom: calc(100% + var(--sp-2));
+  left: 0;
+  max-height: min(42vh, 320px);
+  overflow-y: auto;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--r-2);
+  background: var(--surface);
+  box-shadow: var(--shadow-2);
+}
+
+.structured-command-menu[hidden] {
+  display: none;
+}
+
+.structured-command-option {
+  min-height: var(--tap);
+  padding: var(--sp-2) var(--sp-3);
+  border-bottom: 1px solid var(--border);
+  cursor: pointer;
+}
+
+.structured-command-option:last-child {
+  border-bottom: 0;
+}
+
+.structured-command-option:hover,
+.structured-command-option[aria-selected="true"] {
+  background: var(--accent-tint);
+}
+
+.structured-command-title {
+  display: flex;
+  align-items: baseline;
+  gap: var(--sp-2);
+  min-width: 0;
+}
+
+.structured-command-name {
+  flex: 0 0 auto;
+  color: var(--ink);
+  font-weight: 600;
+}
+
+.structured-command-hint,
+.structured-command-description {
+  overflow: hidden;
+  color: var(--muted);
+  font-size: var(--fs-11);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.structured-command-hint {
+  min-width: 0;
+}
+
+.structured-command-description {
+  margin-top: var(--sp-1);
+}
+
+.structured-input:focus {
+  outline: none;
+  box-shadow: none;
+}
+
+.structured-input:disabled {
+  color: var(--faint);
+  background: transparent;
+}
+
+/* `.btn` sets `display: inline-flex`, which outranks the UA sheet's
+   `[hidden]` — restate it explicitly (same pitfall as `.st-tool-out`). */
+.structured-cancel[hidden] {
+  display: none;
+}
+
+.structured-send[hidden] {
+  display: none;
+}
+
+.structured-error {
+  margin: 0 var(--sp-3);
+  padding: var(--sp-2) var(--sp-3);
+  background: var(--danger-tint);
+  color: var(--danger);
+  font-size: var(--fs-12);
+  border-radius: var(--r-2);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .act,
+  .st-copyable,
+  .st-copyable::after,
+  .st-tool-group-glyph {
+    transition-duration: 0.01ms;
+  }
+
+  .structured-activity-pulse {
+    animation: none;
+  }
+}
+
+@media (hover: none) {
+  .st-copyable::after {
+    opacity: 0.7;
+  }
+}
+
 /* ---------- modal ---------- */
 
 .modal-backdrop {

web/src/toolIcon.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
 import { splitCommand, toolIconSvg } from "./toolIcon.js";
+import commandResolutionFixture from "../../fixtures/command-resolution.json";
+
+interface CommandResolutionCase {
+  command: string;
+  program: string;
+  tool: string | null;
+}
 
 describe("tool icons on the command fragment (docs/SIDEBAR.md)", () => {
   it("recognises the agents and shells sessions are spawned with", () => {
@@ -46,6 +53,14 @@ describe("tool icons on the command fragment (docs/SIDEBAR.md)", () => {
     expect(splitCommand("").tool).toBeNull();
   });
 
+  it("resolves every case in the shared command-resolution fixture (#199)", () => {
+    const cases = commandResolutionFixture.cases as CommandResolutionCase[];
+    expect(cases.length).toBeGreaterThan(0);
+    for (const { command, program, tool } of cases) {
+      expect(splitCommand(command), command).toEqual({ tool, program });
+    }
+  });
+
   it("gives every recognised tool a labelled mark", () => {
     for (const tool of ["claude", "codex", "opencode", "gemini", "aider", "cursor", "pi", "shell"]) {
       const svg = toolIconSvg(tool);

web/src/toolIcon.ts

@@ -9,10 +9,11 @@
  * as text, so the fragment never renders a mark that stands for the wrong tool.
  */
 
-/** Command wrappers that run another program: the tool is what follows. */
-const WRAPPERS = new Set(["sudo", "env", "npx", "bunx", "uvx", "pnpm", "yarn", "command"]);
-
-/** Program name (already basenamed and lowercased) → icon id. */
+/** Program name (already basenamed and lowercased) → icon id.
+ *
+ * `claude-code-acp` — the daemon's actual structured-session child — is
+ * deliberately absent: the daemon launches it directly and ignores the
+ * session's command, so it is never itself a valid user-facing launch form. */
 const BY_PROGRAM: Record<string, string> = {
   claude: "claude",
   "claude-code": "claude",
@@ -53,39 +54,443 @@ export interface CommandParts {
   program: string;
 }
 
-/** Split a command line into the tool its icon stands for and the program name.
+/** Split a command line into the tool its icon stands for and the program
+ * name — basenamed and stripped of its arguments. Leading `FOO=bar`
+ * assignments and wrapper forms (`sudo`, `env -i`, `npx`, `pnpm dlx`, …) are
+ * looked through, and quoting/escaping is honoured (never evaluated — no
+ * `$var`/`` `cmd` ``/`$(cmd)` expansion). A command a shell would need real
+ * grammar for (pipelines, `&&`/`;`, redirections, substitution, an
+ * unterminated quote) falls back to the naive first word rather than
+ * guessing through it (#199). Mirrors the Rust `command_program`/
+ * `command_tool` in `crates/maestro-protocol/src/display.rs`.
  *
  * `claude --resume` → `{tool: "claude", program: "claude"}`; an unrecognised
  * `hx src/` keeps `hx` as the program with no tool. */
 export function splitCommand(command: string): CommandParts {
-  const words = command.trim().split(/\s+/).filter(Boolean);
-  let i = 0;
-  // Leading `FOO=bar` assignments and wrappers stand in front of the real
-  // program; `pnpm dlx x` / `yarn dlx x` need one more word skipped.
-  while (i < words.length) {
-    const word = words[i];
-    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
-      i += 1;
-      continue;
-    }
-    const wrapper = basename(word).toLowerCase();
-    if (WRAPPERS.has(wrapper)) {
-      i += 1;
-      if ((wrapper === "pnpm" || wrapper === "yarn") && words[i] === "dlx") i += 1;
-      continue;
-    }
-    break;
+  const words = tokenize(command);
+  if (words === null) {
+    const program = legacyFirstWord(command);
+    return { tool: null, program };
   }
+  const i = programIndex(words);
   if (i >= words.length) return { tool: null, program: command.trim() };
-  const program = basename(words[i]);
+  const program = basename(words[i].text);
   return { tool: BY_PROGRAM[program.toLowerCase()] ?? null, program };
 }
 
+/** The naive "first whitespace word, basenamed" reading used only when
+ * {@link tokenize} rejects the line outright — still something sane to
+ * show, never a wrapper/tool match to act on. */
+function legacyFirstWord(command: string): string {
+  const first = command.trim().split(/\s+/).filter(Boolean)[0];
+  return first === undefined ? command.trim() : basename(first);
+}
+
+/** One token from {@link tokenize}: its dequoted text, and — when both the
+ * name and `=` were entirely unquoted/unescaped in the source — the index of
+ * the name. Quoting or escaping either (`"FOO"=1`, `F\OO=1`, `FOO\=1`)
+ * makes the word an executable named `FOO=1`; quoting/escaping only the value
+ * preserves the assignment, matching Bash's assignment-word grammar (#199). */
+interface Word {
+  text: string;
+  plainEq: number | null;
+}
+
+/** `FOO=bar`, the shell's own prefix for one command's environment —
+ * recognised only when the `=` came from plain, unquoted/unescaped source
+ * text (#199). */
+function isEnvAssignment(word: Word): boolean {
+  if (word.plainEq === null) return false;
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(word.text.slice(0, word.plainEq));
+}
+
+/** Walk `words` past leading `FOO=bar` assignments and known wrapper forms
+ * (interleaved in any order/count) to the index of the actual program. An
+ * assignment run is only consumed at the very start of the line or right
+ * after a wrapper whose own semantics accept one there ({@link Wrapper.acceptsAssignment}) —
+ * `command FOO=1 claude` and `nohup FOO=1 claude` stop at `FOO=1` rather than
+ * skipping to `claude`, since `command`/`nohup` just exec their next argument
+ * as the program, they don't setenv from an assignment-shaped one (#199). */
+function programIndex(words: Word[]): number {
+  const texts = words.map((w) => w.text);
+  let i = 0;
+  let assignmentAllowed = true;
+  for (;;) {
+    if (assignmentAllowed) {
+      while (i < words.length && isEnvAssignment(words[i])) {
+        i += 1;
+      }
+    }
+    if (i >= words.length) break;
+    const wrapper = basename(texts[i]).toLowerCase();
+    const w = WRAPPER_RESOLVERS[wrapper];
+    if (!w) break;
+    const next = w.resolve(texts, i);
+    // Not a form of the wrapper we recognise (an unknown option, or — for
+    // `pnpm`/`yarn`/`bun` — no `dlx`/`x` subcommand behind it): the wrapper
+    // word itself is the program, not a launcher.
+    if (next === null || next <= i) break;
+    i = next;
+    assignmentAllowed = w.acceptsAssignment;
+  }
+  return i;
+}
+
 function basename(word: string): string {
   const cut = word.lastIndexOf("/");
   return cut >= 0 ? word.slice(cut + 1) : word;
 }
 
+/** Word-split `command` the way a shell would (honouring `'…'`, `"…"` and
+ * `\` quoting/escaping — POSIX quote *removal*, not evaluation) and return
+ * `null` the moment it needs real shell grammar this resolver doesn't
+ * attempt: a pipeline/list operator (`|`, `&`, `;`, `<`, `>`), a subshell or
+ * substitution (`(`, `)`, `` ` ``, `$(`), an unescaped newline (a command
+ * separator, like `;` — #199), or an unterminated quote/escape. Never
+ * expands `$var`/`` `cmd` ``/`$(cmd)` — a bare `$` is kept literal. A
+ * backslash immediately before a newline, quoted or not, is a line
+ * continuation: removed entirely rather than embedding the newline or
+ * ending the word (#199). */
+function tokenize(command: string): Word[] | null {
+  const words: Word[] = [];
+  let current = "";
+  let hasCurrent = false;
+  let plainEq: number | null = null;
+  let assignmentNameIsPlain = true;
+  let i = 0;
+  const n = command.length;
+
+  while (i < n) {
+    const c = command[i];
+    if (c === " " || c === "\t" || c === "\r") {
+      if (hasCurrent) {
+        words.push({ text: current, plainEq });
+        current = "";
+        hasCurrent = false;
+        plainEq = null;
+        assignmentNameIsPlain = true;
+      }
+      i += 1;
+    } else if (c === "\n") {
+      return null;
+    } else if ("|&;<>()`".includes(c)) {
+      return null;
+    } else if (c === "$" && command[i + 1] === "(") {
+      return null;
+    } else if (c === "'") {
+      hasCurrent = true;
+      if (plainEq === null) assignmentNameIsPlain = false;
+      i += 1;
+      const close = command.indexOf("'", i);
+      if (close === -1) return null; // unterminated single quote
+      current += command.slice(i, close);
+      i = close + 1;
+    } else if (c === '"') {
+      hasCurrent = true;
+      if (plainEq === null) assignmentNameIsPlain = false;
+      i += 1;
+      for (;;) {
+        if (i >= n) return null; // unterminated double quote
+        const c2 = command[i];
+        if (c2 === '"') {
+          i += 1;
+          break;
+        }
+        if (c2 === "\\") {
+          const escaped = command[i + 1];
+          if (escaped === undefined) return null; // trailing backslash
+          if (escaped === "\n") {
+            i += 2; // line continuation, removed entirely
+            continue;
+          }
+          current += '"\\$`'.includes(escaped) ? escaped : "\\" + escaped;
+          i += 2;
+        } else {
+          current += c2;
+          i += 1;
+        }
+      }
+    } else if (c === "\\") {
+      const escaped = command[i + 1];
+      if (escaped === undefined) return null; // trailing backslash
+      if (escaped === "\n") {
+        i += 2; // line continuation, removed entirely
+        continue;
+      }
+      hasCurrent = true;
+      if (plainEq === null) assignmentNameIsPlain = false;
+      current += escaped;
+      i += 2;
+    } else {
+      hasCurrent = true;
+      if (c === "=" && plainEq === null && assignmentNameIsPlain) {
+        plainEq = current.length;
+      }
+      current += c;
+      i += 1;
+    }
+  }
+  if (hasCurrent) words.push({ text: current, plainEq });
+  return words;
+}
+
+/** A wrapper's known `-`/`--` options: which take no value, and which
+ * consume either a following word or a `--flag=value` as theirs. A
+ * `-`-prefixed word this table doesn't know halts resolution rather than
+ * guessing past it (#199) — callers read that as {@link consumeOptions}
+ * returning `null`. */
+interface OptionTable {
+  flags: Set<string>;
+  valued: Set<string>;
+  /** Whether this wrapper's short options may be combined (`-iv`) or take
+   * an attached value (`-uroot`), the way real getopt-based tools do
+   * (#199). JS-toolchain wrappers (`npx`, `pnpm`, `yarn`, bun's `x`/`dlx`)
+   * don't get this — guessing at bundling they don't actually support
+   * would resolve through options they'd reject outright. */
+  bundlesShortOptions: boolean;
+}
+
+/** `-iv` (bundled boolean short flags) or `-uroot` (a valued short option
+ * with its value attached) — getopt's traditional short-option forms.
+ * `false` the moment a character isn't a short option this table knows, or
+ * a valued one ends the word with no attached value left to be its operand
+ * (#199: rejected rather than guessed to come from the next word instead). */
+function matchesShortCluster(opts: OptionTable, word: string): boolean {
+  let idx = 1;
+  while (idx < word.length) {
+    const short = "-" + word[idx];
+    if (opts.flags.has(short)) {
+      idx += 1;
+      continue;
+    }
+    if (opts.valued.has(short)) {
+      return idx + 1 < word.length;
+    }
+    return false;
+  }
+  return true;
+}
+
+/** Consume `opts`'s options starting at `words[i]`, returning the index just
+ * past them (which may equal `i` if there are none) — or `null` on an
+ * option this table doesn't recognise, or a valued option missing its
+ * operand. */
+function consumeOptions(opts: OptionTable, words: string[], i: number): number | null {
+  for (;;) {
+    const word = words[i];
+    if (word === undefined) return i;
+    if (word === "--") return i + 1;
+    if (word === "-" || !word.startsWith("-")) return i;
+    const eq = word.indexOf("=");
+    if (eq >= 0) {
+      if (opts.valued.has(word.slice(0, eq)) && word.slice(eq + 1).length > 0) {
+        i += 1;
+        continue;
+      }
+      return null;
+    }
+    if (opts.flags.has(word)) {
+      i += 1;
+      continue;
+    }
+    if (opts.valued.has(word)) {
+      const value = words[i + 1];
+      if (value === undefined || value.length === 0 || value.startsWith("-")) return null;
+      i += 2;
+      continue;
+    }
+    if (
+      opts.bundlesShortOptions &&
+      !word.startsWith("--") &&
+      word.length > 2 &&
+      matchesShortCluster(opts, word)
+    ) {
+      i += 1;
+      continue;
+    }
+    return null;
+  }
+}
+
+const NO_OPTIONS: OptionTable = { flags: new Set(), valued: new Set(), bundlesShortOptions: false };
+
+const ENV_OPTS: OptionTable = {
+  flags: new Set(["-i", "--ignore-environment", "-0", "--null", "-v", "--debug"]),
+  valued: new Set(["-u", "--unset", "-C", "--chdir"]),
+  bundlesShortOptions: true,
+};
+
+const SUDO_OPTS: OptionTable = {
+  flags: new Set([
+    "-i",
+    "--login",
+    "-n",
+    "--non-interactive",
+    "-E",
+    "--preserve-env",
+    "-H",
+    "--set-home",
+    "-A",
+    "--askpass",
+    "-b",
+    "--background",
+    "-k",
+    "--reset-timestamp",
+    "-K",
+    "--remove-timestamp",
+    "-S",
+    "--stdin",
+  ]),
+  valued: new Set(["-u", "--user", "-g", "--group"]),
+  bundlesShortOptions: true,
+};
+
+/** `-v`/`-V` only print what would run — they never execute it — so
+ * resolving through them would claim a program runs that `command` never
+ * launches (#199). Only `-p`, which still executes normally, is safe to
+ * look through. */
+const COMMAND_BUILTIN_OPTS: OptionTable = {
+  flags: new Set(["-p"]),
+  valued: new Set(),
+  bundlesShortOptions: true,
+};
+
+/** The bash *keyword* `time` only ever parses `-p` (POSIX output format);
+ * `-o`/`-v`/`-a`/`-f`/`--verbose`/... belong to the external GNU
+ * `/usr/bin/time`, a different program a bare `time` word doesn't
+ * necessarily name. Assuming them here would be guessing which `time`
+ * resolves (#199). */
+function resolveTime(words: string[], i: number): number | null {
+  let next = i + 1;
+  if (words[next] === "-p") next += 1;
+  if (words[next] === "--") next += 1;
+  const command = words[next];
+  return command?.startsWith("-") ? null : next;
+}
+
+/** `-c`/`--call` embeds a whole shell command string rather than naming the
+ * program positionally — resolving past it would mean guessing at a
+ * program buried inside that string, so it's left unrecognised and
+ * resolution stops at `npx` (#199). */
+const NPX_OPTS: OptionTable = {
+  flags: new Set(["-y", "--yes", "--no", "-q", "--quiet", "--ignore-existing"]),
+  valued: new Set(["-p", "--package", "--shell"]),
+  bundlesShortOptions: false,
+};
+
+const PNPM_OPTS: OptionTable = {
+  flags: new Set(["--silent", "-s", "--stream", "--aggregate-output", "--no-progress"]),
+  // `--package`/`--package=value` is documented in this pre-`dlx` position
+  // (`pnpm --package=x dlx y`), alongside the identical flag `dlx` itself
+  // also accepts (`PNPM_DLX_OPTS`).
+  valued: new Set(["-C", "--dir", "--filter", "--package"]),
+  bundlesShortOptions: false,
+};
+
+const YARN_OPTS: OptionTable = {
+  flags: new Set(["--silent", "-s", "--no-progress", "--non-interactive"]),
+  valued: new Set(["--cwd"]),
+  bundlesShortOptions: false,
+};
+
+const PNPM_DLX_OPTS: OptionTable = {
+  flags: new Set(["-s", "--silent"]),
+  valued: new Set(["--package"]),
+  bundlesShortOptions: false,
+};
+
+const YARN_DLX_OPTS: OptionTable = {
+  flags: new Set(["-q", "--quiet"]),
+  valued: new Set(["-p", "--package"]),
+  bundlesShortOptions: false,
+};
+
+const BUN_X_OPTS: OptionTable = {
+  flags: new Set(["--bun", "--no-install", "--verbose", "--silent"]),
+  valued: new Set(["-p", "--package"]),
+  bundlesShortOptions: false,
+};
+
+/** `pnpm`/`yarn` only look through to the package behind an explicit `dlx`
+ * — without it, the next word is a `package.json` script name, not a
+ * package to run (#199: `pnpm claude` is not `pnpm dlx claude`). `dlx`
+ * itself takes launcher-specific options too, consumed before the executable. */
+function resolveDlx(
+  opts: OptionTable,
+  dlxOpts: OptionTable,
+  words: string[],
+  i: number,
+): number | null {
+  const j = consumeOptions(opts, words, i + 1);
+  if (j === null) return null;
+  if (words[j] !== "dlx") return null;
+  return consumeOptions(dlxOpts, words, j + 1);
+}
+
+/** `bun x <pkg>` is bun's `dlx`/`npx` equivalent; `bun run <script>` is not
+ * (the same package-script ambiguity as bare `pnpm`/`yarn`), so only an `x`
+ * subcommand is looked through. `--bun` (`BUN_X_OPTS`) may follow it before
+ * the executable. */
+function resolveBun(words: string[], i: number): number | null {
+  if (words[i + 1] !== "x") return null;
+  return consumeOptions(BUN_X_OPTS, words, i + 2);
+}
+
+/** A resolver for one wrapper form: given the tokenized command and the
+ * index of the wrapper word itself, the index of the word after it (past
+ * its options and any subcommand it requires), or `null` if this occurrence
+ * isn't a form we resolve through. */
+type WrapperResolver = (words: string[], i: number) => number | null;
+
+/** One recognised wrapper form: how to walk past it, and whether an
+ * assignment word is a valid follow-on once it's been walked past. */
+interface Wrapper {
+  resolve: WrapperResolver;
+  /** `true` only for wrappers that themselves interpret a following
+   * `FOO=bar` as an environment assignment for the command they launch
+   * (`env`, `sudo`), or a shell keyword that restarts the assignment-prefix
+   * grammar for a brand new simple command (`time`). Every other wrapper here
+   * is a plain executable that execs its next argument as the program
+   * outright — an assignment-shaped one names a program literally called
+   * `FOO=1`, not an env var (#199). */
+  acceptsAssignment: boolean;
+}
+
+const WRAPPER_RESOLVERS: Record<string, Wrapper> = {
+  env: { resolve: (words, i) => consumeOptions(ENV_OPTS, words, i + 1), acceptsAssignment: true },
+  sudo: {
+    resolve: (words, i) => consumeOptions(SUDO_OPTS, words, i + 1),
+    acceptsAssignment: true,
+  },
+  command: {
+    resolve: (words, i) => consumeOptions(COMMAND_BUILTIN_OPTS, words, i + 1),
+    acceptsAssignment: false,
+  },
+  nohup: {
+    resolve: (words, i) => consumeOptions(NO_OPTIONS, words, i + 1),
+    acceptsAssignment: false,
+  },
+  time: { resolve: resolveTime, acceptsAssignment: true },
+  npx: {
+    resolve: (words, i) => consumeOptions(NPX_OPTS, words, i + 1),
+    acceptsAssignment: false,
+  },
+  pnpm: {
+    resolve: (words, i) => resolveDlx(PNPM_OPTS, PNPM_DLX_OPTS, words, i),
+    acceptsAssignment: false,
+  },
+  yarn: {
+    resolve: (words, i) => resolveDlx(YARN_OPTS, YARN_DLX_OPTS, words, i),
+    acceptsAssignment: false,
+  },
+  bun: { resolve: resolveBun, acceptsAssignment: false },
+  bunx: {
+    resolve: (words, i) => consumeOptions(BUN_X_OPTS, words, i + 1),
+    acceptsAssignment: false,
+  },
+  uvx: { resolve: (_words, i) => i + 1, acceptsAssignment: false },
+};
+
 /** Anthropic's burst: tapered rays around a centre, long ones on the axes. */
 function burst(): string {
   const rays = Array.from({ length: 8 }, (_, k) => {

web/src/types.ts

@@ -60,8 +60,15 @@ export interface Session {
    * `session/new` (#134). Only a `Structured` session whose handshake
    * succeeded has one; a respawn passes it to `session/load` (#135). */
   acp_session_id?: string | null;
+  /** Terminal (PTY bytes) or structured (ACP rows) (#133). Fixed at spawn and
+   * immutable for the session's life. Defaults to `"Terminal"` on the wire, so
+   * absent means terminal. */
+  view?: SessionView;
 }
 
+/** A session's process shape (#133): mirrors `maestro_protocol::SessionView`. */
+export type SessionView = "Terminal" | "Structured";
+
 /** A session's daemon-created worktree (`SessionWorktree` on the wire). */
 export interface SessionWorktree {
   path: string;
@@ -269,6 +276,7 @@ export interface CreateSessionRequest {
   env?: Record<string, string>;
   metadata?: Record<string, unknown>;
   worktree?: WorktreeSpec;
+  view?: SessionView;
 }
 
 export type CatalogEvent =
@@ -367,6 +375,230 @@ export function abbreviateCwd(cwd: string, home?: string): string {
   return cwd;
 }
 
+// ---------------------------------------------------------------------------
+// Structured-session projections (#133/#140). Mirror of
+// `maestro_protocol`'s "Structured-session projections" section. `data`,
+// `ReducedState.plan/usage/context/pending_approval` and every `Acp*` type
+// below are the daemon's opaque ACP payloads (`serde_json::Value` on the
+// wire) — shaped to `claude-code-acp`'s ACP v1 schema, not covered by
+// maestro-protocol's own compatibility guarantee. Treat every field as
+// optional and degrade gracefully rather than trust this shape exactly.
+// ---------------------------------------------------------------------------
+
+/** `maestro_protocol::TranscriptRowKind`, snake_case on the wire. */
+export type TranscriptRowKind =
+  | "user"
+  | "agent_text"
+  | "agent_thought"
+  | "tool_call"
+  | "tool_diff"
+  | "approval"
+  | "plan"
+  | "notice";
+
+/** One row of a structured session's transcript. */
+export interface TranscriptRow {
+  id: string;
+  kind: TranscriptRowKind;
+  data: unknown;
+}
+
+/** The complete transcript at a durable event-log position (`WS
+ * /api/structured/:id`'s first message, and every replay page). */
+export interface TranscriptSnapshot {
+  cursor: number;
+  rows: TranscriptRow[];
+}
+
+/** A change to one transcript row, addressed by `id`. */
+export type TranscriptDelta =
+  | { type: "append"; row: TranscriptRow }
+  | { type: "patch"; row: TranscriptRow }
+  | { type: "remove"; id: string };
+
+/** Per-turn indicators derived from the ACP stream — read verbatim, never
+ * re-derived client-side (docs/STRUCTURED-VIEW.md). */
+export interface TurnState {
+  responding: boolean;
+  thinking: boolean;
+  active_tool_calls: string[];
+  started_at?: string | null;
+  started_context_tokens?: number | null;
+}
+
+/** A whole-session view derived from ACP notifications. `plan`/`usage`/
+ * `context`/`pending_approval` are opaque ACP JSON — see the module note
+ * above. `pending_approval` is `{nonce, request: AcpRequestPermissionRequest}`
+ * while a permission request is live, absent otherwise. */
+export interface ReducedState {
+  turn: TurnState;
+  pending_approval?: { nonce: string; request: AcpRequestPermissionRequest } | null;
+  plan?: AcpPlan | null;
+  usage?: AcpUsage | null;
+  context?: AcpUsage | null;
+  model?: string | null;
+  mode?: string | null;
+  config_options?: { configOptions: AcpSessionConfigOption[] } | null;
+}
+
+/** Server messages on `WS /api/structured/:id`. */
+export type StructuredEvent =
+  | { type: "transcript_snapshot"; snapshot: TranscriptSnapshot }
+  | { type: "reduced_state"; state: ReducedState }
+  | { type: "projection_update"; transcript?: TranscriptDelta | null; state: ReducedState };
+
+/** `POST /api/sessions/:id/structured/prompt` body. */
+export interface StructuredPromptRequest {
+  prompt: string;
+}
+
+export interface StructuredConfigRequest {
+  config_id: string;
+  value: string | boolean;
+}
+
+export interface AcpSessionConfigChoice {
+  value: string;
+  name: string;
+  description?: string | null;
+}
+
+export interface AcpSessionConfigGroup {
+  group: string;
+  name: string;
+  options: AcpSessionConfigChoice[];
+}
+
+export interface AcpSessionConfigOption {
+  id: string;
+  name: string;
+  description?: string | null;
+  category?: string | null;
+  type: "select" | "boolean" | string;
+  currentValue: string | boolean;
+  options?: Array<AcpSessionConfigChoice | AcpSessionConfigGroup>;
+}
+
+/** `POST /api/sessions/:id/structured/approvals/:nonce` body — a bare JSON
+ * string (a bracketless Rust enum), not `{decision: ...}`. */
+export type StructuredApprovalDecision = "allow_once" | "allow_for_session" | "deny";
+
+// ---- ACP v1 payload shapes (agent-client-protocol schema, camelCase) ----
+
+/** `ContentBlock`. Only `text` is common in practice; the rest degrade to a
+ * generic placeholder rather than being dropped silently. */
+export type AcpContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; mimeType?: string }
+  | { type: "audio"; mimeType?: string }
+  | { type: "resource_link"; uri?: string; name?: string }
+  | { type: "resource"; resource?: unknown };
+
+/** `ContentChunk` — the payload of a `User`/`AgentText`/`AgentThought` row. */
+export interface AcpContentChunk {
+  content: AcpContentBlock;
+  messageId?: string | null;
+}
+
+/** `ToolKind`, snake_case on the wire. */
+export type AcpToolKind =
+  | "read"
+  | "edit"
+  | "delete"
+  | "move"
+  | "search"
+  | "execute"
+  | "think"
+  | "fetch"
+  | "switch_mode"
+  | "other";
+
+/** `ToolCallStatus`, snake_case on the wire. */
+export type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+
+/** `Diff` — a file modification. `oldText` absent means a new file. */
+export interface AcpDiff {
+  path: string;
+  oldText?: string | null;
+  newText: string;
+}
+
+/** `ToolCallContent`. */
+export type AcpToolCallContent =
+  | { type: "content"; content: AcpContentBlock }
+  | ({ type: "diff" } & AcpDiff)
+  | { type: "terminal"; terminalId?: string };
+
+export interface AcpToolCallLocation {
+  path: string;
+  line?: number | null;
+}
+
+/** `ToolCall` (a `ToolCall`/`ToolDiff` row's `data`) and, loosely, the
+ * flattened `ToolCallUpdate` an approval's `toolCall` field carries — the
+ * two share every field below, just with different subsets required. */
+export interface AcpToolCallLike {
+  toolCallId?: string;
+  title?: string;
+  /** Unstable ACP capability; absent when the adapter doesn't send one. */
+  name?: string | null;
+  kind?: AcpToolKind;
+  status?: AcpToolCallStatus;
+  content?: AcpToolCallContent[];
+  locations?: AcpToolCallLocation[];
+  rawInput?: unknown;
+  rawOutput?: unknown;
+}
+
+/** `PlanEntryPriority` / `PlanEntryStatus`, snake_case on the wire. */
+export type AcpPlanPriority = "high" | "medium" | "low";
+export type AcpPlanEntryStatus = "pending" | "in_progress" | "completed";
+
+export interface AcpPlanEntry {
+  content: string;
+  priority: AcpPlanPriority;
+  status: AcpPlanEntryStatus;
+}
+
+/** `Plan` — `ReducedState.plan`. */
+export interface AcpPlan {
+  entries: AcpPlanEntry[];
+}
+
+/** `UsageUpdate` — `ReducedState.usage`/`.context` (the daemon folds one
+ * update into both fields). */
+export interface AcpUsage {
+  used: number;
+  size: number;
+  cost?: { amount: number; currency: string } | null;
+}
+
+/** Daemon-owned durable footer appended when one prompt turn settles. ACP
+ * only reports context occupancy, so `contextDelta` is not a billing-token
+ * count and may be negative when the provider compacts the context. */
+export interface TurnMeta {
+  elapsedMs: number;
+  contextTokens?: number | null;
+  contextDelta?: number | null;
+  outcome: "completed" | "cancelled" | "failed" | string;
+  model?: string | null;
+}
+
+export interface AcpPermissionOption {
+  optionId: string;
+  name: string;
+  kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+}
+
+/** `RequestPermissionRequest`, serialized without its nonce (the nonce lives
+ * only in `ReducedState.pending_approval.nonce`) — an `Approval` row's `data`,
+ * and `ReducedState.pending_approval.request`. */
+export interface AcpRequestPermissionRequest {
+  sessionId: string;
+  toolCall: AcpToolCallLike;
+  options: AcpPermissionOption[];
+}
+
 /** `~/git.naps.pt/naps62/maestro` → `~/g/n/maestro`: keep the last segment
  * verbatim, collapse every earlier one to its first character. Two-or-fewer
  * segments are left alone (nothing to gain). Returns escaped HTML with the