fix(maestro): reject structured PTY access

ConnectionPool.reconcileViews re-focused a repaired connection whenever
focusedId named it, but a same-tab sidebar preview moves the keyboard
into the sidebar without ever calling setFocus (multiview.ts's
syncFocus skips it while previewing) — so focusedId keeps naming the
pane the operator was in before the preview, even though the DOM
doesn't agree. Replacing that pane's connection during exactly that
window called onMount({focus:true}) and yanked the keyboard back out
of the sidebar mid-navigation.

Capture existing.el.contains(document.activeElement) before dispose()/
el.remove() detach it (afterward the browser has already moved
activeElement to <body>, too late to tell), and require both that and
focusedId===id to re-focus. document.body and a null activeElement
both naturally fail .contains(), so "nothing focused" and "focus
elsewhere" both correctly skip.

Regression tests: 3 new (real-focus requirement, same-tab preview
race, descendant focus, body-as-unfocused) — 498 tests total.

Cargo.lock

@@ -1644,6 +1644,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-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

@@ -26,7 +26,7 @@ use maestro_protocol::{
 use serde::Deserialize;
 use uuid::Uuid;
 
-use crate::session::{QueueAcpPrompt, SessionManager};
+use crate::session::{QueueAcpPrompt, SessionError, SessionManager};
 use crate::sidecar::EventCursor;
 
 #[derive(Debug, Clone)]
@@ -179,6 +179,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,
     }
@@ -534,12 +535,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

@@ -223,6 +223,21 @@ impl Projection {
         })
     }
 
+    /// Undo an `append`ed row that a caller decides never happened — used
+    /// when persisting the row's own event fails (#184), so a snapshot taken
+    /// after the failure cannot show a row durable replay would never
+    /// reproduce. Only ever called for a row that was just appended and
+    /// never patched, so removing it by id fully reverses `append`.
+    pub fn rollback_row(&mut self, id: &str) {
+        let Some(index) = self.row_index.remove(id) else {
+            return;
+        };
+        self.rows.remove(index);
+        for (shifted_index, row) in self.rows.iter().enumerate().skip(index) {
+            self.row_index.insert(row.id.clone(), shifted_index);
+        }
+    }
+
     fn content(
         &mut self,
         seq: u64,
@@ -423,6 +438,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();
@@ -725,6 +750,74 @@ mod tests {
         assert_eq!(projection.snapshot(0).rows, vec![row]);
     }
 
+    #[test]
+    fn rollback_row_removes_only_that_row_and_keeps_others_addressable() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate": "user_message_chunk",
+                "messageId": "m1",
+                "content": {"type": "text", "text": "hi"},
+            })),
+        );
+        let TranscriptDelta::Append { row } = projection
+            .request_approval("nonce".into(), serde_json::json!({"tool": "bash"}))
+            .transcript
+            .unwrap()
+        else {
+            panic!("approval row")
+        };
+        // A row after the one being rolled back, so removing the approval
+        // (index 1) shifts this one from index 2 down to index 1 — proving
+        // `row_index` gets reindexed, not just `rows`.
+        projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate": "user_message_chunk",
+                "messageId": "m2",
+                "content": {"type": "text", "text": "hey"},
+            })),
+        );
+        assert_eq!(projection.snapshot(0).rows.len(), 3);
+
+        projection.rollback_row(&row.id);
+
+        assert_eq!(projection.snapshot(0).rows.len(), 2);
+        assert_eq!(projection.snapshot(0).rows[0].kind, TranscriptRowKind::User);
+        assert_eq!(projection.snapshot(0).rows[1].kind, TranscriptRowKind::User);
+
+        // The shifted row must still be independently patchable at its new
+        // index.
+        let update = projection.apply(
+            3,
+            &event(serde_json::json!({
+                "sessionUpdate": "user_message_chunk",
+                "messageId": "m2",
+                "content": {"type": "text", "text": " there"},
+            })),
+        );
+        let TranscriptDelta::Patch { row } = update.transcript.unwrap() else {
+            panic!("patched row")
+        };
+        assert_eq!(row.data.pointer("/content/text").unwrap(), "hey there");
+        assert_eq!(projection.snapshot(0).rows.len(), 2);
+    }
+
+    #[test]
+    fn rollback_row_is_a_no_op_for_an_unknown_id() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate": "user_message_chunk",
+                "content": {"type": "text", "text": "hi"},
+            })),
+        );
+        projection.rollback_row("approval:does-not-exist");
+        assert_eq!(projection.snapshot(0).rows.len(), 1);
+    }
+
     #[test]
     fn recovered_approval_is_historical_not_pending() {
         let mut live = Projection::default();

crates/maestro-daemon/src/session.rs

@@ -25,7 +25,7 @@ use crate::panes::Panes;
 use crate::projection::{Projection, ProjectionUpdate, TurnLifecycle};
 use crate::pty::{pipe_pane_command, PtyBridge};
 use crate::sidecar::{
-    EventCursor, EventLog, LoggedEvent, PersistedEvent, SidecarError, SidecarStore,
+    AppendError, EventCursor, EventLog, LoggedEvent, PersistedEvent, SidecarError, SidecarStore,
 };
 use crate::spawn_history::{RecentDir, SpawnHistory, SpawnHistoryRecord};
 use crate::tmux::TmuxError;
@@ -169,6 +169,8 @@ pub enum SessionError {
     /// a stray keystroke on an attach socket, which is dropped.
     #[error("session is no longer running: {0}")]
     NotRunning(Uuid),
+    #[error("session is not a terminal session")]
+    NotTerminal(Uuid),
     #[error("daemon is shutting down")]
     ShuttingDown,
     /// The kill was refused (#79): the session's worktree holds unsaved work.
@@ -205,6 +207,7 @@ impl SessionError {
             SessionError::NotFound(_) => "not_found",
             SessionError::InvalidEnv(_) => "invalid_env",
             SessionError::NotRunning(_) => "not_running",
+            SessionError::NotTerminal(_) => "not_terminal",
             SessionError::ShuttingDown => "shutting_down",
             SessionError::KillGuarded(_) => "kill_guarded",
         };
@@ -879,11 +882,17 @@ impl SessionManager {
         }
     }
 
-    /// Subscribe to a session's PTY broadcast. `None` if the session is
-    /// unknown to this daemon.
-    pub async fn subscribe_pty(&self, id: Uuid) -> Option<broadcast::Receiver<Vec<u8>>> {
+    /// Subscribe to a terminal session's PTY broadcast.
+    pub async fn subscribe_pty(
+        &self,
+        id: Uuid,
+    ) -> Result<broadcast::Receiver<Vec<u8>>, SessionError> {
         let sessions = self.inner.sessions.lock().await;
-        sessions.get(&id).map(|r| r.bridge.subscribe())
+        let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+        if record.session.view != SessionView::Terminal {
+            return Err(SessionError::NotTerminal(id));
+        }
+        Ok(record.bridge.subscribe())
     }
 
     /// Subscribe to a session's PTY broadcast and return the replay buffer
@@ -897,11 +906,14 @@ impl SessionManager {
     pub async fn subscribe_pty_with_replay(
         &self,
         id: Uuid,
-    ) -> Option<(Vec<u8>, broadcast::Receiver<Vec<u8>>)> {
+    ) -> Result<(Vec<u8>, broadcast::Receiver<Vec<u8>>), SessionError> {
         let tmux = self.inner.tmux.clone();
         let (result, updated) = {
             let mut sessions = self.inner.sessions.lock().await;
-            let rec = sessions.get_mut(&id)?;
+            let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
+            if rec.session.view != SessionView::Terminal {
+                return Err(SessionError::NotTerminal(id));
+            }
             rec.session.last_focused_at = Some(Utc::now());
             let updated = rec.session.clone();
             // For a live session, tmux's own screen beats the byte tail: the
@@ -932,7 +944,7 @@ impl SessionManager {
             .inner
             .events
             .send(CatalogEvent::SessionUpdated { session: updated });
-        Some(result)
+        Ok(result)
     }
 
     pub async fn has(&self, id: Uuid) -> bool {
@@ -945,6 +957,15 @@ impl SessionManager {
         sessions.get(&id).map(|r| r.session.status)
     }
 
+    async fn terminal_status(&self, id: Uuid) -> Result<SessionStatus, SessionError> {
+        let sessions = self.inner.sessions.lock().await;
+        let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
+        if record.session.view != SessionView::Terminal {
+            return Err(SessionError::NotTerminal(id));
+        }
+        Ok(record.session.status)
+    }
+
     /// Whether the natural-exit settle step (#82) has finished for this
     /// session: `Some(true)` once applied or refused, `Some(false)` while
     /// still pending, `None` if the session is unknown. `Dead` is observable
@@ -1626,10 +1647,9 @@ impl SessionManager {
     /// its pane is gone, so this is a no-op rather than a tmux failure the
     /// client would have to interpret.
     pub async fn send_keys(&self, id: Uuid, bytes: &[u8]) -> Result<(), SessionError> {
-        match self.status(id).await {
-            None => return Err(SessionError::NotFound(id)),
-            Some(SessionStatus::Dead) => return Ok(()),
-            Some(SessionStatus::Running) => {}
+        match self.terminal_status(id).await? {
+            SessionStatus::Dead => return Ok(()),
+            SessionStatus::Running => {}
         }
         let tmux = self.inner.tmux.clone();
         let bytes = bytes.to_vec();
@@ -1645,10 +1665,9 @@ impl SessionManager {
     /// asked for text to land somewhere, and a silent success would let a
     /// script believe an agent had been told something it never heard.
     pub async fn send_input(&self, id: Uuid, text: &str, submit: bool) -> Result<(), SessionError> {
-        match self.status(id).await {
-            None => return Err(SessionError::NotFound(id)),
-            Some(SessionStatus::Dead) => return Err(SessionError::NotRunning(id)),
-            Some(SessionStatus::Running) => {}
+        match self.terminal_status(id).await? {
+            SessionStatus::Dead => return Err(SessionError::NotRunning(id)),
+            SessionStatus::Running => {}
         }
         let tmux = self.inner.tmux.clone();
         let bytes = text.as_bytes().to_vec();
@@ -1668,10 +1687,9 @@ impl SessionManager {
     /// Resize a session's window. No-op for a dead session, as with
     /// [`Self::send_keys`].
     pub async fn resize(&self, id: Uuid, cols: u16, rows: u16) -> Result<(), SessionError> {
-        match self.status(id).await {
-            None => return Err(SessionError::NotFound(id)),
-            Some(SessionStatus::Dead) => return Ok(()),
-            Some(SessionStatus::Running) => {}
+        match self.terminal_status(id).await? {
+            SessionStatus::Dead => return Ok(()),
+            SessionStatus::Running => {}
         }
         let tmux = self.inner.tmux.clone();
         tmux_blocking(move || tmux.resize_window(id, cols, rows))
@@ -1703,6 +1721,7 @@ impl SessionManager {
         cols: u16,
         rows: u16,
     ) -> Result<(), SessionError> {
+        self.terminal_status(id).await?;
         let target = self
             .inner
             .viewports
@@ -2003,6 +2022,41 @@ fn apply_persisted_event(projection: &mut Projection, event: &LoggedEvent) -> Pr
 }
 
 async fn sync_structured_activity(inner: &Arc<Inner>, id: Uuid) {
+    let events = {
+        let sessions = inner.sessions.lock().await;
+        let Some(record) = sessions.get(&id) else {
+            return;
+        };
+        if record.session.view != SessionView::Structured {
+            return;
+        }
+        record.acp_events.clone()
+    };
+
+    match events {
+        Some(events) => sync_structured_activity_from_stream(inner, id, events).await,
+        None => apply_structured_activity(inner, id, None, ActivityState::Error).await,
+    }
+}
+
+async fn sync_structured_activity_from_stream(
+    inner: &Arc<Inner>,
+    id: Uuid,
+    events: Arc<Mutex<AcpEventStream>>,
+) {
+    let event_stream = events.lock().await;
+    let raw = event_stream.projection.activity();
+    // Stream state must stay fixed until its catalog transition is applied;
+    // every other path releases `sessions` before awaiting this stream lock.
+    apply_structured_activity(inner, id, Some(&events), raw).await;
+}
+
+async fn apply_structured_activity(
+    inner: &Arc<Inner>,
+    id: Uuid,
+    expected_events: Option<&Arc<Mutex<AcpEventStream>>>,
+    raw: ActivityState,
+) {
     let updated = {
         let mut sessions = inner.sessions.lock().await;
         let Some(record) = sessions.get_mut(&id) else {
@@ -2011,12 +2065,19 @@ async fn sync_structured_activity(inner: &Arc<Inner>, id: Uuid) {
         if record.session.view != SessionView::Structured {
             return;
         }
+        let current_events = record.acp_events.as_ref();
+        let stream_matches = match (expected_events, current_events) {
+            (Some(expected), Some(current)) => Arc::ptr_eq(expected, current),
+            (None, None) => true,
+            _ => false,
+        };
+        if !stream_matches {
+            return;
+        }
         let raw = if record.session.status == SessionStatus::Dead {
             ActivityState::Error
-        } else if let Some(events) = &record.acp_events {
-            events.lock().await.projection.activity()
         } else {
-            ActivityState::Error
+            raw
         };
         let activity = crate::activity::apply_focus_suppression(
             raw,
@@ -2047,6 +2108,7 @@ fn start_acp_permission_pump(
         return;
     };
     let weak_inner = Arc::downgrade(inner);
+    let weak_acp = Arc::downgrade(acp);
     tokio::spawn(async move {
         while let Some(PermissionRequest {
             turn,
@@ -2059,41 +2121,23 @@ fn start_acp_permission_pump(
                 let _ = response.send(maestro_acp::schema::RequestPermissionOutcome::Cancelled);
                 continue;
             }
-            let nonce = Uuid::new_v4().to_string();
-            let data = match serde_json::to_value(&request) {
-                Ok(value) => value,
-                Err(_) => {
-                    let _ = response.send(maestro_acp::schema::RequestPermissionOutcome::Cancelled);
-                    continue;
-                }
-            };
-            // ACP requests serialize through its connection. Keep the newest
-            // one authoritative if an adapter nonetheless overlaps them.
-            cancel_pending_approvals(&mut events);
-            events.pending_approvals.insert(
-                nonce.clone(),
-                PendingApproval {
-                    response,
-                    options: request.options,
-                },
-            );
-            let update = events.projection.request_approval(nonce, data);
-            if let Some(TranscriptDelta::Append { row }) = &update.transcript {
-                let event = PersistedEvent::Approval { row: row.clone() };
-                if let Err(error) = events.log.append(&event) {
-                    tracing::error!(%error, "approval history append failed");
-                    cancel_pending_approvals(&mut events);
-                    drop(events);
-                    if let Some(inner) = weak_inner.upgrade() {
-                        sync_structured_activity(&inner, id).await;
-                    }
-                    continue;
-                }
-                let seq = events.log.last_seq();
-                let _ = events.live.send(LoggedEvent { seq, event });
+            let outcome = record_permission_request(&mut events, request, response);
+            let fatal = matches!(outcome, RecordOutcome::Fatal);
+            if let RecordOutcome::Live(update) = outcome {
+                let _ = events.projected_live.send(*update);
             }
-            let _ = events.projected_live.send(update);
             drop(events);
+            if fatal {
+                tracing::error!(%id, "approval history append rollback did not restore consistency");
+                if let Some(acp) = weak_acp.upgrade() {
+                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+                        .await;
+                }
+                if let Some(inner) = weak_inner.upgrade() {
+                    mark_session_dead(&inner, id).await;
+                }
+                break;
+            }
             if let Some(inner) = weak_inner.upgrade() {
                 sync_structured_activity(&inner, id).await;
             }
@@ -2101,6 +2145,71 @@ fn start_acp_permission_pump(
     });
 }
 
+/// What became of one [`record_permission_request`] call.
+enum RecordOutcome {
+    /// Persisted; broadcast this live.
+    Live(Box<ProjectionUpdate>),
+    /// Not persisted, but the log rolled back cleanly: the approval was
+    /// cancelled and the session lives on.
+    Dropped,
+    /// Not persisted, and the rollback did not restore a consistent log.
+    /// The caller must treat the session as dead rather than keep appending
+    /// to an `EventLog` whose `last_seq` may no longer match its file.
+    Fatal,
+}
+
+/// Install `request` as the pending approval — cancelling whatever was
+/// already pending, so the newest request wins (#139) — and persist its
+/// transcript row before it is exposed live. On append failure the row is
+/// rolled back from the projection so a later `TranscriptSnapshot` cannot
+/// show a row durable replay could never reproduce (#184); the ACP callback
+/// still resolves `Cancelled`, exactly as any other cancelled approval does.
+fn record_permission_request(
+    events: &mut AcpEventStream,
+    request: maestro_acp::schema::RequestPermissionRequest,
+    response: oneshot::Sender<maestro_acp::schema::RequestPermissionOutcome>,
+) -> RecordOutcome {
+    let nonce = Uuid::new_v4().to_string();
+    let data = match serde_json::to_value(&request) {
+        Ok(value) => value,
+        Err(_) => {
+            let _ = response.send(maestro_acp::schema::RequestPermissionOutcome::Cancelled);
+            return RecordOutcome::Dropped;
+        }
+    };
+    cancel_pending_approvals(events);
+    events.pending_approvals.insert(
+        nonce.clone(),
+        PendingApproval {
+            response,
+            options: request.options,
+        },
+    );
+    let update = events.projection.request_approval(nonce, data);
+    let Some(TranscriptDelta::Append { row }) = &update.transcript else {
+        return RecordOutcome::Live(Box::new(update));
+    };
+    let event = PersistedEvent::Approval { row: row.clone() };
+    match events.log.append(&event) {
+        Ok(seq) => {
+            let _ = events.live.send(LoggedEvent { seq, event });
+            RecordOutcome::Live(Box::new(update))
+        }
+        Err(AppendError::Failed(error)) => {
+            tracing::error!(%error, "approval history append failed");
+            events.projection.rollback_row(&row.id);
+            cancel_pending_approvals(events);
+            RecordOutcome::Dropped
+        }
+        Err(fatal @ AppendError::Fatal { .. }) => {
+            tracing::error!(error = %fatal, "approval history append failed unrecoverably");
+            events.projection.rollback_row(&row.id);
+            cancel_pending_approvals(events);
+            RecordOutcome::Fatal
+        }
+    }
+}
+
 fn cancel_pending_approvals(events: &mut AcpEventStream) {
     for (_, pending) in events.pending_approvals.drain() {
         let _ = pending
@@ -2653,13 +2762,370 @@ async fn cleanup_record(
 
 #[cfg(test)]
 mod tests {
-    use super::{permission_outcome, ApprovalDecision};
-    use maestro_acp::schema::{PermissionOption, PermissionOptionKind, RequestPermissionOutcome};
+    use std::fs::File;
+    use std::sync::Arc;
+    use std::task::Poll;
+    use std::time::Duration;
+
+    use maestro_acp::schema::{
+        PermissionOption, PermissionOptionKind, RequestPermissionOutcome, RequestPermissionRequest,
+        ToolCallUpdate, ToolCallUpdateFields,
+    };
+    use maestro_protocol::{ActivityState, CreateSessionRequest, SessionView};
+
+    use super::{
+        cancel_pending_approvals, permission_outcome, record_permission_request,
+        run_structured_activity_pass, sync_structured_activity_from_stream, AcpDispatchState,
+        AcpEventStream, ApprovalDecision, RecordOutcome, SessionManager,
+    };
+    use crate::activity::FOCUS_CLEAR_HOLD;
+    use crate::panes::FakePanes;
+    use crate::projection::Projection;
+    use crate::sidecar::{
+        EventCursor, EventLog, FaultyLogSink, PersistedEvent, SharedBuf, SidecarStore,
+    };
+    use crate::worktree::WorktreeManager;
 
     fn option(id: &str, kind: PermissionOptionKind) -> PermissionOption {
         PermissionOption::new(id.to_owned(), id, kind)
     }
 
+    fn permission_request() -> RequestPermissionRequest {
+        RequestPermissionRequest::new(
+            "acp-session",
+            ToolCallUpdate::new("tool-1", ToolCallUpdateFields::new()),
+            vec![option("allow-once", PermissionOptionKind::AllowOnce)],
+        )
+    }
+
+    fn stream(log: EventLog) -> AcpEventStream {
+        let (live, _live_rx) = tokio::sync::broadcast::channel(16);
+        let (projected_live, _projected_rx) = tokio::sync::broadcast::channel(16);
+        AcpEventStream {
+            log,
+            live,
+            projection: Projection::default(),
+            projected_live,
+            pending_approvals: std::collections::HashMap::new(),
+            operation: std::sync::Arc::new(tokio::sync::Mutex::new(())),
+            dispatch: AcpDispatchState::default(),
+        }
+    }
+
+    fn terminal_request(cwd: &std::path::Path) -> CreateSessionRequest {
+        CreateSessionRequest {
+            view: SessionView::Terminal,
+            cwd: cwd.to_path_buf(),
+            command: "sh".into(),
+            env: std::collections::HashMap::new(),
+            metadata: std::collections::HashMap::new(),
+            worktree: None,
+        }
+    }
+
+    async fn manager_with_structured_stream() -> (
+        tempfile::TempDir,
+        SessionManager,
+        Arc<FakePanes>,
+        uuid::Uuid,
+        Arc<tokio::sync::Mutex<AcpEventStream>>,
+        uuid::Uuid,
+    ) {
+        let state = tempfile::tempdir().unwrap();
+        let panes = Arc::new(FakePanes::new());
+        let manager = SessionManager::new(
+            panes.clone(),
+            SidecarStore::new(state.path().join("sessions")),
+            WorktreeManager::new(None),
+            state.path().join("fifos"),
+        );
+        let structured = manager
+            .create(terminal_request(state.path()))
+            .await
+            .expect("create structured fixture");
+        let terminal = manager
+            .create(terminal_request(state.path()))
+            .await
+            .expect("create unrelated terminal");
+        let events = Arc::new(tokio::sync::Mutex::new(stream(
+            manager
+                .inner
+                .sidecar
+                .open_events(structured.id)
+                .expect("open event log"),
+        )));
+        {
+            let mut event_stream = events.lock().await;
+            event_stream.projection.begin_turn();
+            event_stream
+                .projection
+                .request_approval("nonce".into(), serde_json::json!({}));
+        }
+        {
+            let mut sessions = manager.inner.sessions.lock().await;
+            let record = sessions.get_mut(&structured.id).unwrap();
+            record.session.view = SessionView::Structured;
+            record.session.activity = ActivityState::AwaitingInput;
+            record.focused_since = Some(std::time::Instant::now() - FOCUS_CLEAR_HOLD);
+            record.acp_events = Some(events.clone());
+        }
+        (state, manager, panes, structured.id, events, terminal.id)
+    }
+
+    #[tokio::test]
+    async fn blocked_structured_activity_read_does_not_block_the_catalog() {
+        let (state, manager, _panes, structured_id, events, terminal_id) =
+            manager_with_structured_stream().await;
+        let held_stream = events.lock().await;
+        let activity_pass = run_structured_activity_pass(&manager.inner);
+        tokio::pin!(activity_pass);
+        assert!(matches!(
+            futures_util::poll!(activity_pass.as_mut()),
+            Poll::Pending
+        ));
+
+        tokio::time::timeout(Duration::from_secs(1), manager.snapshot())
+            .await
+            .expect("catalog snapshot blocked behind another session's event stream");
+        tokio::time::timeout(
+            Duration::from_secs(1),
+            manager.send_keys(terminal_id, b"responsive"),
+        )
+        .await
+        .expect("terminal input blocked behind another session's event stream")
+        .expect("terminal input");
+        let created = tokio::time::timeout(
+            Duration::from_secs(1),
+            manager.create(terminal_request(state.path())),
+        )
+        .await
+        .expect("session create blocked behind another session's event stream")
+        .expect("create unrelated session");
+        tokio::time::timeout(Duration::from_secs(1), manager.kill(created.id, false))
+            .await
+            .expect("session kill blocked behind another session's event stream")
+            .expect("kill unrelated session");
+
+        drop(held_stream);
+        tokio::time::timeout(Duration::from_secs(1), activity_pass)
+            .await
+            .expect("activity pass did not resume");
+        let structured = manager
+            .snapshot()
+            .await
+            .into_iter()
+            .find(|session| session.id == structured_id)
+            .unwrap();
+        assert_eq!(structured.activity, ActivityState::Idle);
+    }
+
+    #[tokio::test]
+    async fn structured_sessions_reject_every_pty_operation_before_panes() {
+        let (_state, manager, panes, structured_id, _events, terminal_id) =
+            manager_with_structured_stream().await;
+        let before = panes.calls();
+
+        assert!(matches!(
+            manager.subscribe_pty(structured_id).await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+        assert!(matches!(
+            manager.subscribe_pty_with_replay(structured_id).await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+        assert!(matches!(
+            manager.send_keys(structured_id, b"ignored").await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+        assert!(matches!(
+            manager.send_input(structured_id, "ignored", false).await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+        assert!(matches!(
+            manager.resize(structured_id, 80, 24).await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+        assert!(matches!(
+            manager
+                .set_viewport(structured_id, manager.attach_viewport(), 80, 24)
+                .await,
+            Err(super::SessionError::NotTerminal(id)) if id == structured_id
+        ));
+
+        let after = panes.calls();
+        assert_eq!(after, before, "structured PTY operations touched panes");
+
+        manager
+            .send_input(terminal_id, "works", false)
+            .await
+            .expect("terminal input remains available");
+        manager
+            .resize(terminal_id, 100, 30)
+            .await
+            .expect("terminal resize remains available");
+    }
+
+    #[tokio::test]
+    async fn delayed_activity_from_a_replaced_stream_is_discarded() {
+        let (_state, manager, _panes, structured_id, old_events, _terminal_id) =
+            manager_with_structured_stream().await;
+        let replacement = Arc::new(tokio::sync::Mutex::new(stream(
+            manager
+                .inner
+                .sidecar
+                .open_events(uuid::Uuid::new_v4())
+                .expect("open replacement event log"),
+        )));
+        let mut sessions = manager.inner.sessions.lock().await;
+        let sync =
+            sync_structured_activity_from_stream(&manager.inner, structured_id, old_events.clone());
+        tokio::pin!(sync);
+        assert!(matches!(futures_util::poll!(sync.as_mut()), Poll::Pending));
+        let record = sessions.get_mut(&structured_id).unwrap();
+        record.acp_events = Some(replacement.clone());
+        record.session.activity = ActivityState::Error;
+        drop(sessions);
+
+        tokio::time::timeout(Duration::from_secs(1), sync)
+            .await
+            .expect("stale activity sync did not finish");
+        let sessions = manager.inner.sessions.lock().await;
+        let record = sessions.get(&structured_id).unwrap();
+        assert_eq!(record.session.activity, ActivityState::Error);
+        assert!(Arc::ptr_eq(
+            record.acp_events.as_ref().unwrap(),
+            &replacement
+        ));
+    }
+
+    /// A handle that can never append *or* roll back: opened read-only, so
+    /// both `write_all` and the rollback `truncate` fail with the OS's own
+    /// error (`ftruncate` requires a writable fd too) instead of a
+    /// hand-rolled one. A genuinely dead fd like this is exactly the case
+    /// where consistency cannot be promised, so it must come back fatal.
+    fn unwritable_log(path: &std::path::Path, last_seq: u64) -> EventLog {
+        EventLog::for_test(File::open(path).expect("open read-only handle"), last_seq)
+    }
+
+    #[tokio::test]
+    async fn failed_approval_append_with_no_usable_rollback_is_fatal_and_leaves_no_phantom_row() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = SidecarStore::new(dir.path());
+        let id = uuid::Uuid::new_v4();
+        // Create the log file for real so a read-only handle onto it exists,
+        // then swap in the broken handle: the write is what must fail, not
+        // the open.
+        drop(store.open_events(id).unwrap());
+        let mut events = stream(unwritable_log(&store.events_path_for(id), 0));
+
+        let (response_tx, response_rx) = tokio::sync::oneshot::channel();
+        let outcome = record_permission_request(&mut events, permission_request(), response_tx);
+
+        assert!(
+            matches!(outcome, RecordOutcome::Fatal),
+            "a write failure whose rollback also fails must be reported fatal, not dropped"
+        );
+        assert!(
+            events.pending_approvals.is_empty(),
+            "the failed nonce must not linger as pending"
+        );
+        assert_eq!(
+            response_rx.await.unwrap(),
+            RequestPermissionOutcome::Cancelled,
+            "ACP must see the withdrawn-request outcome, not a hang"
+        );
+
+        let state = events.projection.state();
+        assert!(
+            state.pending_approval.is_none(),
+            "reduced state must not advertise a pending approval that never persisted"
+        );
+        assert!(
+            events.projection.snapshot(0).rows.is_empty(),
+            "the live projection must not carry a row durable replay cannot reproduce"
+        );
+
+        // Durable replay of the untouched real log must agree with the live
+        // projection: nothing happened.
+        let replayed = store
+            .read_events(id, EventCursor::Since(0), 100)
+            .expect("replay");
+        assert!(
+            replayed.is_empty(),
+            "durable replay must not diverge from the rolled-back live projection"
+        );
+        assert_eq!(
+            events.log.last_seq(),
+            0,
+            "cursor must stay put on a failed append"
+        );
+    }
+
+    #[tokio::test]
+    async fn approval_after_a_failed_one_persists_and_replays_cleanly() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = SidecarStore::new(dir.path());
+        let id = uuid::Uuid::new_v4();
+
+        // A fault that fails the write once and then behaves like a healthy
+        // sink — the same `EventLog` instance must recover, unlike a handle
+        // swapped in from a healthy disk, which production never does
+        // (#184).
+        let buf = SharedBuf::default();
+        let sink = FaultyLogSink {
+            buf: buf.clone(),
+            fail_write_after: Some(0),
+            ..Default::default()
+        };
+        let mut events = stream(EventLog::for_test(sink, 0));
+
+        let (first_tx, first_rx) = tokio::sync::oneshot::channel();
+        assert!(matches!(
+            record_permission_request(&mut events, permission_request(), first_tx),
+            RecordOutcome::Dropped
+        ));
+        assert_eq!(first_rx.await.unwrap(), RequestPermissionOutcome::Cancelled);
+        assert_eq!(
+            events.log.last_seq(),
+            0,
+            "the failed attempt must not have advanced the cursor"
+        );
+
+        // Same instance, no swap: the sink is healthy again, so the next
+        // request over the same connection must not be poisoned by the
+        // earlier failure (concurrent/ordering audit for #184).
+        let (second_tx, _second_rx) = tokio::sync::oneshot::channel();
+        let outcome = record_permission_request(&mut events, permission_request(), second_tx);
+
+        assert!(
+            matches!(outcome, RecordOutcome::Live(_)),
+            "a healthy append must be exposed live"
+        );
+        assert_eq!(events.pending_approvals.len(), 1);
+        let rows = events.projection.snapshot(0).rows;
+        assert_eq!(rows.len(), 1, "no phantom row survives from the failure");
+
+        // Durable replay via the real read path, over the bytes the same
+        // instance actually wrote.
+        std::fs::create_dir_all(store.dir()).unwrap();
+        std::fs::write(store.events_path_for(id), buf.snapshot()).unwrap();
+        let replayed = store
+            .read_events(id, EventCursor::Since(0), 100)
+            .expect("replay");
+        assert_eq!(replayed.len(), 1, "the failed attempt left no line behind");
+        let PersistedEvent::Approval { row } = &replayed[0].event else {
+            panic!("approval event")
+        };
+        assert_eq!(
+            row.id, rows[0].id,
+            "live and durable must agree on identity"
+        );
+        assert_eq!(replayed[0].seq, events.log.last_seq());
+
+        cancel_pending_approvals(&mut events);
+        assert!(events.pending_approvals.is_empty());
+    }
+
     fn selected_id(outcome: RequestPermissionOutcome) -> Option<String> {
         match outcome {
             RequestPermissionOutcome::Selected(selected) => Some(selected.option_id.to_string()),

crates/maestro-daemon/src/sidecar.rs

@@ -112,7 +112,7 @@ impl SidecarStore {
         }
         file.seek(SeekFrom::End(0))?;
         Ok(EventLog {
-            file,
+            file: Box::new(file),
             last_seq: lines,
         })
     }
@@ -296,15 +296,82 @@ impl From<&PersistedEvent> for PersistedEvent {
     }
 }
 
+/// What an [`EventLog`] appends onto: something seekable by length and
+/// truncatable back to one, so a failed append can be rolled off the end
+/// again. A real [`File`] in production; an in-memory fault double in tests
+/// (#184) — the same [`EventLog::append`] rollback logic runs over both, so
+/// the behavior under test is the production behavior, not a stand-in for
+/// it.
+pub(crate) trait LogSink: Write + Send {
+    fn len(&mut self) -> std::io::Result<u64>;
+    fn truncate(&mut self, len: u64) -> std::io::Result<()>;
+}
+
+impl LogSink for File {
+    fn len(&mut self) -> std::io::Result<u64> {
+        Ok(self.metadata()?.len())
+    }
+
+    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
+        self.set_len(len)
+    }
+}
+
+/// Outcome of a failed [`EventLog::append`].
+#[derive(Debug, thiserror::Error)]
+pub enum AppendError {
+    /// The write or flush failed, but the log was rolled back to exactly the
+    /// byte it was at before the call: `last_seq` and the file agree, and
+    /// this same [`EventLog`] is safe to keep appending to. The event itself
+    /// was never persisted or broadcast.
+    #[error("event append failed, rolled back cleanly: {0}")]
+    Failed(#[source] SidecarError),
+    /// The append failed *and* the rollback did not restore the log to its
+    /// prior length, so the file's line count and `last_seq` may now
+    /// disagree. The caller must not append to this [`EventLog`] again —
+    /// treat the session as dead rather than promise consistency it cannot
+    /// keep.
+    #[error("event append failed ({cause}) and rollback did not restore consistency ({rollback})")]
+    Fatal {
+        cause: SidecarError,
+        rollback: SidecarError,
+    },
+}
+
+impl From<SidecarError> for AppendError {
+    fn from(error: SidecarError) -> Self {
+        AppendError::Failed(error)
+    }
+}
+
 /// An open, append-only handle on one session's event log. Obtained from
 /// [`SidecarStore::open_events`]; held for the session's lifetime.
-#[derive(Debug)]
 pub struct EventLog {
-    file: File,
+    file: Box<dyn LogSink>,
     last_seq: u64,
 }
 
+impl std::fmt::Debug for EventLog {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EventLog")
+            .field("last_seq", &self.last_seq)
+            .finish_non_exhaustive()
+    }
+}
+
 impl EventLog {
+    /// Wrap an arbitrary sink as an [`EventLog`], for tests that need to
+    /// inject a deterministic append failure (#184) — a partial write, a
+    /// flush that fails after the bytes are already down, or a rollback that
+    /// cannot itself complete.
+    #[cfg(test)]
+    pub(crate) fn for_test(file: impl LogSink + 'static, last_seq: u64) -> Self {
+        Self {
+            file: Box::new(file),
+            last_seq,
+        }
+    }
+
     /// The seq of the last line, `0` for an empty log.
     pub fn last_seq(&self) -> u64 {
         self.last_seq
@@ -314,16 +381,262 @@ impl EventLog {
     /// handed to the kernel in a single write before this returns, so a
     /// caller that broadcasts afterwards never announces an event the log
     /// would not replay — short of the machine losing power.
-    pub fn append(&mut self, event: impl Into<PersistedEvent>) -> Result<u64, SidecarError> {
+    ///
+    /// A `write_all` that errors partway can leave an unterminated prefix on
+    /// disk; a `flush` that errors after a *complete* `write_all` leaves
+    /// ambiguity about whether that full, well-formed line should count —
+    /// counting it would silently shift every later seq by one, since
+    /// `last_seq` was never bumped for it. Both cases are rolled back to the
+    /// exact pre-append length before returning, so `last_seq` and the file
+    /// never disagree and the same [`EventLog`] can be appended to again
+    /// immediately. If the rollback itself fails, the log's consistency can
+    /// no longer be promised and [`AppendError::Fatal`] is returned instead.
+    pub fn append(&mut self, event: impl Into<PersistedEvent>) -> Result<u64, AppendError> {
         let event = event.into();
         let mut line = match &event {
-            PersistedEvent::Notification(notification) => serde_json::to_vec(notification)?,
-            _ => serde_json::to_vec(&event)?,
+            PersistedEvent::Notification(notification) => serde_json::to_vec(notification)
+                .map_err(|e| AppendError::from(SidecarError::from(e)))?,
+            _ => {
+                serde_json::to_vec(&event).map_err(|e| AppendError::from(SidecarError::from(e)))?
+            }
         };
         line.push(b'\n');
-        self.file.write_all(&line)?;
-        self.file.flush()?;
+
+        let pre_len = self
+            .file
+            .len()
+            .map_err(|e| AppendError::from(SidecarError::from(e)))?;
+
+        if let Err(cause) = self.file.write_all(&line) {
+            return Err(self.rollback_after(pre_len, cause));
+        }
+        if let Err(cause) = self.file.flush() {
+            return Err(self.rollback_after(pre_len, cause));
+        }
+
         self.last_seq += 1;
         Ok(self.last_seq)
     }
+
+    fn rollback_after(&mut self, pre_len: u64, cause: std::io::Error) -> AppendError {
+        match self.file.truncate(pre_len) {
+            Ok(()) => AppendError::Failed(SidecarError::Io(cause)),
+            Err(rollback) => AppendError::Fatal {
+                cause: SidecarError::Io(cause),
+                rollback: SidecarError::Io(rollback),
+            },
+        }
+    }
+}
+
+/// Bytes shared between a [`FaultyLogSink`] moved into an [`EventLog`] and
+/// the test that planted it, so the test can inspect what actually ended up
+/// on the "disk" after a fault without reaching into `EventLog`'s private
+/// `file` field.
+#[cfg(test)]
+#[derive(Clone, Default)]
+pub(crate) struct SharedBuf(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
+
+#[cfg(test)]
+impl SharedBuf {
+    pub(crate) fn snapshot(&self) -> Vec<u8> {
+        self.0.lock().unwrap().clone()
+    }
+}
+
+/// An in-memory [`LogSink`] double that injects one deterministic fault — a
+/// short write, a flush that fails after a full write, or a rollback that
+/// cannot itself complete — then behaves like a healthy sink from then on.
+/// Lets a test prove the *same* [`EventLog`] recovers, rather than one with a
+/// handle swapped in from a healthy disk, which production never does
+/// (#184).
+#[cfg(test)]
+#[derive(Default)]
+pub(crate) struct FaultyLogSink {
+    pub(crate) buf: SharedBuf,
+    /// Accept this many bytes on the next `write` call, then fail the
+    /// *following* call — a short write followed by an error, exactly what
+    /// `write_all` sees from a real fd that dies mid-line. `Write::write`
+    /// must not report an error on a call that made partial progress, so
+    /// the fault is delivered one call later, via `pending_write_error`.
+    pub(crate) fail_write_after: Option<usize>,
+    pub(crate) pending_write_error: bool,
+    pub(crate) fail_flush_once: bool,
+    pub(crate) fail_truncate: bool,
+}
+
+#[cfg(test)]
+impl Write for FaultyLogSink {
+    fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
+        if self.pending_write_error {
+            self.pending_write_error = false;
+            return Err(std::io::Error::other("fault: write failed mid-line"));
+        }
+        if let Some(allowed) = self.fail_write_after.take() {
+            let allowed = allowed.min(data.len());
+            if allowed == 0 {
+                // No progress was made, so it's fine to report the error
+                // from this same call.
+                return Err(std::io::Error::other("fault: write failed mid-line"));
+            }
+            self.buf
+                .0
+                .lock()
+                .unwrap()
+                .extend_from_slice(&data[..allowed]);
+            self.pending_write_error = true;
+            return Ok(allowed);
+        }
+        self.buf.0.lock().unwrap().extend_from_slice(data);
+        Ok(data.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        if self.fail_flush_once {
+            self.fail_flush_once = false;
+            return Err(std::io::Error::other(
+                "fault: flush failed after a full write",
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+impl LogSink for FaultyLogSink {
+    fn len(&mut self) -> std::io::Result<u64> {
+        Ok(self.buf.0.lock().unwrap().len() as u64)
+    }
+
+    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
+        if self.fail_truncate {
+            return Err(std::io::Error::other("fault: rollback truncate failed"));
+        }
+        self.buf.0.lock().unwrap().truncate(len as usize);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_event(id: &str) -> PersistedEvent {
+        PersistedEvent::Approval {
+            row: TranscriptRow {
+                id: id.to_owned(),
+                kind: maestro_protocol::TranscriptRowKind::Approval,
+                data: serde_json::json!({"tool": "bash"}),
+            },
+        }
+    }
+
+    /// Replays `bytes` as a real on-disk log via the production read path,
+    /// so "live and durable agree" is checked with the same code a
+    /// reconnecting client would hit, not a hand-rolled line splitter.
+    fn replay(bytes: &[u8]) -> Vec<LoggedEvent> {
+        let dir = tempfile::tempdir().unwrap();
+        let store = SidecarStore::new(dir.path());
+        let id = Uuid::new_v4();
+        std::fs::create_dir_all(store.dir()).unwrap();
+        std::fs::write(store.events_path_for(id), bytes).unwrap();
+        store.read_events(id, EventCursor::Since(0), 100).unwrap()
+    }
+
+    #[test]
+    fn append_rolls_back_a_partial_write_and_the_same_instance_recovers() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf: buf.clone(),
+            fail_write_after: Some(5),
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(
+            matches!(err, AppendError::Failed(_)),
+            "a repairable rollback must not be reported fatal"
+        );
+        assert_eq!(log.last_seq(), 0, "cursor must stay put on a failed append");
+        assert!(
+            buf.snapshot().is_empty(),
+            "the partial prefix a failed write_all leaves behind must be truncated away"
+        );
+
+        let seq = log
+            .append(sample_event("r1"))
+            .expect("the same instance must be able to append again after a clean rollback");
+        assert_eq!(seq, 1);
+        assert_eq!(log.last_seq(), 1);
+
+        let bytes = buf.snapshot();
+        assert_eq!(
+            bytes.iter().filter(|&&b| b == b'\n').count(),
+            1,
+            "exactly one well-formed line, not a partial prefix glued to the recovered append"
+        );
+
+        let replayed = replay(&bytes);
+        assert_eq!(replayed.len(), 1);
+        assert_eq!(replayed[0].seq, log.last_seq());
+        let PersistedEvent::Approval { row } = &replayed[0].event else {
+            panic!("approval event");
+        };
+        assert_eq!(row.id, "r1");
+    }
+
+    #[test]
+    fn append_rolls_back_when_flush_fails_after_a_full_write() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf: buf.clone(),
+            fail_flush_once: true,
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(matches!(err, AppendError::Failed(_)));
+        assert_eq!(log.last_seq(), 0);
+        assert!(
+            buf.snapshot().is_empty(),
+            "a full-but-unflushed line must not survive uncounted by last_seq — it would \
+             silently shift every later seq by one"
+        );
+
+        let seq = log
+            .append(sample_event("r1"))
+            .expect("the same instance must recover once flush stops failing");
+        assert_eq!(seq, 1);
+
+        let bytes = buf.snapshot();
+        let replayed = replay(&bytes);
+        assert_eq!(replayed.len(), 1);
+        assert_eq!(replayed[0].seq, log.last_seq());
+    }
+
+    #[test]
+    fn append_reports_fatal_when_rollback_cannot_restore_consistency() {
+        let buf = SharedBuf::default();
+        let writer = FaultyLogSink {
+            buf,
+            fail_write_after: Some(3),
+            fail_truncate: true,
+            ..Default::default()
+        };
+        let mut log = EventLog::for_test(writer, 0);
+
+        let err = log.append(sample_event("r1")).unwrap_err();
+        assert!(
+            matches!(err, AppendError::Fatal { .. }),
+            "an unrepairable rollback must be surfaced as fatal, never silently treated as \
+             a clean recoverable failure"
+        );
+        assert_eq!(
+            log.last_seq(),
+            0,
+            "a fatal append must not advance the cursor either"
+        );
+    }
 }

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

@@ -159,6 +159,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 +213,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,45 @@ 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);
+    }
+
     #[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,735 @@
+//! 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,
+    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,
+            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

@@ -113,13 +113,25 @@ crate.
 | `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. | `notice:<seq>`. |
 
-`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,
@@ -139,8 +151,11 @@ choices, not daemon ones.
 - 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.
 
@@ -302,7 +317,14 @@ directory: the sidecar itself (`<id>.json`), plus two next to it:
   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.
+  what follows. An append that fails *while the daemon is running* — a
+  `write_all` that errors after only a prefix reached disk, or a `flush` that
+  errors after a complete write — is rolled back to the exact byte length the
+  file was at before the call, so `last_seq` and the file's line count never
+  disagree and the same log handle can be appended to again immediately (#184).
+  If that rollback itself cannot restore the prior length, the append is
+  fatal: the log's consistency can no longer be promised, so the caller kills
+  the session instead of appending to it again.
 - **`<id>.recover`** — an empty marker file. Its only meaning is "the daemon
   that wrote this shut down gracefully while this session was running, and
   the next daemon may attempt to resume it." It is consumed (deleted) the
@@ -314,9 +336,15 @@ persistence consequences:
 
 1. **The adapter exits, or a notification append to the event log fails,
    while the daemon keeps running.** (An approval-row append failure is
-   narrower: it cancels the pending approval and lets the session continue,
-   without marking it dead.) `mark_session_dead` applies the same
-   natural-exit worktree rule
+   narrower: as long as the log rolled back cleanly, it only cancels the
+   pending approval and rolls the unpersisted `Approval` row back out of the
+   live transcript, without marking the session dead — a snapshot taken after
+   the failure must never show a row durable replay could not reproduce
+   (#184). If the rollback itself did not restore the log's prior length,
+   this narrower path does not apply either: the session is marked dead the
+   same as any other append failure, since the log can no longer promise
+   `last_seq` matches its file.)
+   `mark_session_dead` applies the same natural-exit worktree rule
    as a terminal session's own pane exiting (`docs/WORKTREES.md`): a pristine
    worktree is removed, one holding unsaved work is left on disk. No recovery
    marker is written. This death is permanent — a later daemon restart's

web/src/api.ts

@@ -11,6 +11,8 @@ import type {
   Projects,
   RecentDirs,
   Session,
+  StructuredApprovalDecision,
+  StructuredPromptRequest,
   Uuid,
 } from "./types.js";
 
@@ -152,4 +154,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/main.ts

@@ -172,6 +172,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 +210,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,27 @@ 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/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 +76,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.test.ts

@@ -0,0 +1,844 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./api.js", async () => {
+  const actual = await vi.importActual<typeof import("./api.js")>("./api.js");
+  return {
+    ...actual,
+    sendStructuredPrompt: vi.fn().mockResolvedValue(undefined),
+    cancelStructuredTurn: vi.fn().mockResolvedValue(undefined),
+    resolveStructuredApproval: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+import { cancelStructuredTurn, resolveStructuredApproval, sendStructuredPrompt } from "./api.js";
+import { TOGGLE_DRAWER_EVENT } from "./drawer.js";
+import { CatalogStore } from "./events.js";
+import { createStructuredConnection, type StructuredSocketFactory } from "./structured.js";
+import type { ReducedState, Session, StructuredEvent, TranscriptRow } from "./types.js";
+
+/** Just enough of a WebSocket for the connection to drive (mirrors
+ *  events.test.ts's FakeSocket, adapted for JSON structured events). */
+class FakeSocket {
+  onopen: (() => void) | null = null;
+  onmessage: ((ev: { data: string }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null = null;
+  closed = false;
+
+  open(): void {
+    this.onopen?.();
+  }
+  emit(event: StructuredEvent): void {
+    this.onmessage?.({ data: JSON.stringify(event) });
+  }
+  drop(code = 1006, reason = ""): void {
+    this.onclose?.({ code, reason });
+  }
+  close(): void {
+    this.closed = true;
+  }
+}
+
+function row(id: string, kind: TranscriptRow["kind"], data: unknown): TranscriptRow {
+  return { id, kind, data };
+}
+
+const idleState: ReducedState = { turn: { responding: false, thinking: false, active_tool_calls: [] } };
+
+const allApprovalOptions = [
+  { optionId: "a1", name: "Allow once", kind: "allow_once" as const },
+  { optionId: "a2", name: "Allow always", kind: "allow_always" as const },
+  { optionId: "r1", name: "Reject once", kind: "reject_once" as const },
+];
+
+function mount(opts: {
+  sockets: FakeSocket[];
+  shouldReconnect?: (id: string, code: number) => boolean;
+  store?: CatalogStore;
+}) {
+  let i = 0;
+  const factory: StructuredSocketFactory = () => opts.sockets[i++] as unknown as WebSocket;
+  const conn = createStructuredConnection(
+    "s1",
+    { shouldReconnect: opts.shouldReconnect },
+    { name: "s1", command: "claude", view: "Structured" },
+    opts.store,
+    factory,
+  );
+  document.body.appendChild(conn.el);
+  return conn;
+}
+
+describe("structured connection: data flow", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("renders every row from the initial snapshot", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: {
+        cursor: 2,
+        rows: [
+          row("user:1", "user", { content: { type: "text", text: "hello" } }),
+          row("agent:1", "agent_text", { content: { type: "text", text: "hi there" } }),
+        ],
+      },
+    });
+    ws.emit({ type: "reduced_state", state: idleState });
+    expect(conn.el.textContent).toContain("hello");
+    expect(conn.el.textContent).toContain("hi there");
+    conn.dispose();
+  });
+
+  it("appends and patches rows via projection_update without duplicating them", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    ws.emit({
+      type: "projection_update",
+      transcript: { type: "append", row: row("agent:1", "agent_text", { content: { type: "text", text: "partial" } }) },
+      state: idleState,
+    });
+    ws.emit({
+      type: "projection_update",
+      transcript: { type: "patch", row: row("agent:1", "agent_text", { content: { type: "text", text: "partial done" } }) },
+      state: idleState,
+    });
+    const rows = conn.el.querySelectorAll(".st-row-agent");
+    expect(rows).toHaveLength(1);
+    expect(conn.el.textContent).toContain("partial done");
+    expect(conn.el.textContent).not.toContain("partial\n"); // the un-patched text is gone, not appended beside it
+    conn.dispose();
+  });
+
+  it("keeps an expanded running tool open without emitting a click when patched", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: {
+        cursor: 1,
+        rows: [
+          row("tool:1", "tool_call", {
+            title: "Bash(pnpm test)",
+            status: "in_progress",
+            content: [{ type: "content", content: { type: "text", text: "starting" } }],
+          }),
+        ],
+      },
+    });
+    ws.emit({ type: "reduced_state", state: idleState });
+
+    const originalHead = conn.el.querySelector<HTMLButtonElement>(".st-tool-head")!;
+    originalHead.click();
+    expect(originalHead.getAttribute("aria-expanded")).toBe("true");
+    const clickListener = vi.fn();
+    window.addEventListener("click", clickListener, { capture: true, once: true });
+
+    ws.emit({
+      type: "projection_update",
+      transcript: {
+        type: "patch",
+        row: row("tool:1", "tool_call", {
+          title: "Bash(pnpm test)",
+          status: "in_progress",
+          content: [{ type: "content", content: { type: "text", text: "still running" } }],
+        }),
+      },
+      state: idleState,
+    });
+
+    expect(clickListener).not.toHaveBeenCalled();
+    window.removeEventListener("click", clickListener, true);
+    const patchedHead = conn.el.querySelector<HTMLButtonElement>(".st-tool-head")!;
+    expect(patchedHead).not.toBe(originalHead);
+    expect(patchedHead.getAttribute("aria-expanded")).toBe("true");
+    expect(conn.el.querySelector<HTMLElement>(".st-tool-out")!.hidden).toBe(false);
+    expect(conn.el.textContent).toContain("still running");
+    conn.dispose();
+  });
+
+  it("restores focus to a patched tool header with the same stable row id", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: {
+        cursor: 1,
+        rows: [row("tool:1", "tool_call", { title: "Read(file.ts)", status: "in_progress" })],
+      },
+    });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const originalHead = conn.el.querySelector<HTMLButtonElement>(".st-tool-head")!;
+    originalHead.focus();
+    expect(document.activeElement).toBe(originalHead);
+
+    ws.emit({
+      type: "projection_update",
+      transcript: {
+        type: "patch",
+        row: row("tool:1", "tool_call", { title: "Read(file.ts)", status: "completed" }),
+      },
+      state: idleState,
+    });
+
+    const patchedHead = conn.el.querySelector<HTMLButtonElement>(".st-tool-head")!;
+    expect(patchedHead).not.toBe(originalHead);
+    expect(document.activeElement).toBe(patchedHead);
+    conn.dispose();
+  });
+
+  it("does not move unrelated focus when a tool row is patched", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: {
+        cursor: 1,
+        rows: [row("tool:1", "tool_call", { title: "Read(file.ts)", status: "in_progress" })],
+      },
+    });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector<HTMLTextAreaElement>(".structured-input")!;
+    input.focus();
+
+    ws.emit({
+      type: "projection_update",
+      transcript: {
+        type: "patch",
+        row: row("tool:1", "tool_call", { title: "Read(file.ts)", status: "completed" }),
+      },
+      state: idleState,
+    });
+
+    expect(document.activeElement).toBe(input);
+    conn.dispose();
+  });
+});
+
+describe("structured connection: turn/composer gating", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("disables the composer while a turn is active and re-enables when idle", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    const cancel = conn.el.querySelector(".structured-cancel") as HTMLButtonElement;
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    expect(input.disabled).toBe(true);
+    expect(cancel.hidden).toBe(false);
+    ws.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(false);
+    expect(cancel.hidden).toBe(true);
+    conn.dispose();
+  });
+
+  it("sends a prompt on Enter, clears the draft, and restores it on failure", async () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "do the thing";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "do the thing");
+    expect(input.value).toBe("");
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    ws.emit({ type: "reduced_state", state: idleState });
+
+    vi.mocked(sendStructuredPrompt).mockRejectedValueOnce(new Error("boom"));
+    input.value = "retry me";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(input.value).toBe("retry me");
+    expect(conn.el.textContent).toContain("boom");
+    conn.dispose();
+  });
+
+  it("disables immediately and dispatches only once before begin-turn is projected", () => {
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(() => new Promise(() => {}));
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    const send = conn.el.querySelector(".structured-send") as HTMLButtonElement;
+    const form = conn.el.querySelector(".structured-composer") as HTMLFormElement;
+    input.value = "only once";
+
+    form.dispatchEvent(new SubmitEvent("submit", { bubbles: true, cancelable: true }));
+    form.dispatchEvent(new SubmitEvent("submit", { bubbles: true, cancelable: true }));
+
+    expect(input.disabled).toBe(true);
+    expect(send.disabled).toBe(true);
+    expect(sendStructuredPrompt).toHaveBeenCalledTimes(1);
+    expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "only once");
+    conn.dispose();
+  });
+
+  it("does not overwrite a newer operator draft when the matching request fails", async () => {
+    let reject!: (error: unknown) => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((_, rejectPromise) => { reject = rejectPromise; }),
+    );
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "first prompt";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    input.value = "newer draft";
+
+    reject(new Error("late failure"));
+    await Promise.resolve().then(() => Promise.resolve());
+
+    expect(input.value).toBe("newer draft");
+    expect(conn.el.textContent).toContain("late failure");
+    conn.dispose();
+  });
+
+  it("ignores an older failure after a newer submission generation starts", async () => {
+    let rejectFirst!: (error: unknown) => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((_, rejectPromise) => { rejectFirst = rejectPromise; }),
+    );
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "first prompt";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    input.value = "second prompt";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    rejectFirst(new Error("stale failure"));
+    await Promise.resolve().then(() => Promise.resolve());
+
+    expect(sendStructuredPrompt).toHaveBeenCalledTimes(2);
+    expect(input.value).toBe("");
+    expect(input.disabled).toBe(true);
+    expect(conn.el.textContent).not.toContain("stale failure");
+    conn.dispose();
+  });
+
+  it("ignores a submission failure after disposal", async () => {
+    let reject!: (error: unknown) => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((_, rejectPromise) => { reject = rejectPromise; }),
+    );
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "do not restore";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    conn.dispose();
+    input.value = "detached draft";
+    reject(new Error("late failure"));
+    await Promise.resolve().then(() => Promise.resolve());
+
+    expect(input.value).toBe("detached draft");
+    expect(conn.el.querySelector(".structured-error")).toBeNull();
+  });
+
+  it("cancels the active turn via the cancel button", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: true, active_tool_calls: [] } } });
+    (conn.el.querySelector(".structured-cancel") as HTMLButtonElement).click();
+    expect(cancelStructuredTurn).toHaveBeenCalledWith("s1");
+    conn.dispose();
+  });
+});
+
+describe("structured connection: approvals", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("shows decision buttons only for the currently pending approval, and answers with its nonce", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({
+      type: "projection_update",
+      transcript: {
+        type: "append",
+        row: row("approval:1", "approval", { toolCall: { title: "Write x" }, options: allApprovalOptions }),
+      },
+      state: { ...idleState, pending_approval: { nonce: "n1", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    const buttons = conn.el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    expect(buttons).toHaveLength(3);
+    buttons[1].click(); // "Allow for session"
+    expect(resolveStructuredApproval).toHaveBeenCalledWith("s1", "n1", "allow_for_session");
+    conn.dispose();
+  });
+
+  it("removes the buttons once the approval resolves, even with no accompanying transcript delta", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: { cursor: 0, rows: [row("approval:1", "approval", { toolCall: { title: "Write x" }, options: allApprovalOptions })] },
+    });
+    ws.emit({
+      type: "reduced_state",
+      state: { ...idleState, pending_approval: { nonce: "n1", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    expect(conn.el.querySelectorAll(".st-approval-acts button")).toHaveLength(3);
+    // Resolved on another client: state clears with no transcript delta at all.
+    ws.emit({ type: "reduced_state", state: idleState });
+    expect(conn.el.querySelector(".st-approval-acts")).toBeNull();
+    expect(conn.el.querySelector(".st-approval-resolved")).not.toBeNull();
+    conn.dispose();
+  });
+
+  it("does not act on a stale click after the approval already moved on", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: { cursor: 0, rows: [row("approval:1", "approval", { toolCall: {}, options: allApprovalOptions })] },
+    });
+    ws.emit({
+      type: "reduced_state",
+      state: { ...idleState, pending_approval: { nonce: "n1", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    const buttons = conn.el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    // Approval is superseded before the click is handled (buttons already
+    // disabled by the click handler is not the path under test here — this
+    // simulates the row having already flipped to "answered" underneath it).
+    ws.emit({ type: "reduced_state", state: idleState });
+    buttons[0].dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(resolveStructuredApproval).not.toHaveBeenCalled();
+    conn.dispose();
+  });
+
+  it("restores the buttons and surfaces an error when the POST rejects while still pending", async () => {
+    vi.mocked(resolveStructuredApproval).mockRejectedValueOnce(new Error("network down"));
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: { cursor: 0, rows: [row("approval:1", "approval", { toolCall: {}, options: allApprovalOptions })] },
+    });
+    ws.emit({
+      type: "reduced_state",
+      state: { ...idleState, pending_approval: { nonce: "n1", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    const buttons = conn.el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    buttons[0].click();
+    expect(buttons[0].disabled).toBe(true);
+    await Promise.resolve().then(() => Promise.resolve()).then(() => Promise.resolve());
+    expect(buttons[0].disabled).toBe(false);
+    expect(buttons[1].disabled).toBe(false);
+    expect(conn.el.textContent).toContain("network down");
+    conn.dispose();
+  });
+
+  it("does not resurrect buttons or show an error for a decision the approval already moved past", async () => {
+    let reject!: (e: unknown) => void;
+    vi.mocked(resolveStructuredApproval).mockImplementationOnce(
+      () => new Promise((_, r) => { reject = r; }),
+    );
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({
+      type: "transcript_snapshot",
+      snapshot: { cursor: 0, rows: [row("approval:1", "approval", { toolCall: {}, options: allApprovalOptions })] },
+    });
+    ws.emit({
+      type: "reduced_state",
+      state: { ...idleState, pending_approval: { nonce: "n1", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    const buttons = conn.el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    buttons[0].click();
+    expect(resolveStructuredApproval).toHaveBeenCalledWith("s1", "n1", "allow_once");
+
+    // Superseded by a new approval before the in-flight POST settles.
+    ws.emit({
+      type: "projection_update",
+      transcript: { type: "append", row: row("approval:2", "approval", { toolCall: {}, options: allApprovalOptions }) },
+      state: { ...idleState, pending_approval: { nonce: "n2", request: { sessionId: "s1", toolCall: {}, options: allApprovalOptions } } },
+    });
+    reject(new Error("too late"));
+    await Promise.resolve().then(() => Promise.resolve()).then(() => Promise.resolve());
+
+    expect(conn.el.textContent).not.toContain("too late");
+    const newButtons = conn.el.querySelectorAll<HTMLButtonElement>(".st-approval-acts button");
+    expect(newButtons).toHaveLength(3);
+    expect(newButtons[0].disabled).toBe(false);
+    conn.dispose();
+  });
+});
+
+describe("structured connection: reconnection/error/loading", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => vi.useRealTimers());
+
+  it("shows connecting, then connected, then reconnecting with backoff, and rebuilds from the fresh snapshot", () => {
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const conn = mount({ sockets: [first, second], shouldReconnect: () => true });
+    const state = () => (conn.el.querySelector(".attach-state") as HTMLElement).dataset.state;
+    expect(state()).toBe("connecting");
+
+    first.open();
+    expect(state()).toBe("open");
+    first.emit({
+      type: "transcript_snapshot",
+      snapshot: { cursor: 0, rows: [row("user:1", "user", { content: { type: "text", text: "before" } })] },
+    });
+    expect(conn.el.textContent).toContain("before");
+
+    first.drop(1006, "");
+    expect(state()).toBe("connecting"); // "reconnecting…"
+    vi.advanceTimersByTime(1000);
+
+    second.open();
+    expect(state()).toBe("open");
+    second.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    expect(conn.el.textContent).not.toContain("before"); // rebuilt wholesale, not merged
+    conn.dispose();
+  });
+
+  it("keeps a local submission gated across a reconnect until begin-turn arrives", () => {
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(() => new Promise(() => {}));
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const conn = mount({ sockets: [first, second], shouldReconnect: () => true });
+    first.open();
+    first.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    first.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "survive reconnect";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    first.drop();
+    vi.advanceTimersByTime(1000);
+    second.open();
+    second.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    second.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(true);
+
+    second.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    second.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(false);
+    conn.dispose();
+  });
+
+  it("releases an accepted submission from a post-acceptance idle snapshot", async () => {
+    vi.mocked(sendStructuredPrompt).mockResolvedValueOnce(undefined);
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const conn = mount({ sockets: [first, second], shouldReconnect: () => true });
+    first.open();
+    first.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    first.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "finishes while disconnected";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    await Promise.resolve().then(() => Promise.resolve());
+
+    first.drop();
+    vi.advanceTimersByTime(1000);
+    second.open();
+    second.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    second.emit({ type: "reduced_state", state: idleState });
+
+    expect(input.disabled).toBe(false);
+    conn.dispose();
+  });
+
+  it("does not release from reconnect idle cached before submission acceptance", async () => {
+    let accept!: () => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((resolve) => { accept = resolve; }),
+    );
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const third = new FakeSocket();
+    const conn = mount({ sockets: [first, second, third], shouldReconnect: () => true });
+    first.open();
+    first.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    first.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "accepted after reconnect";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    first.drop();
+    vi.advanceTimersByTime(1000);
+    second.open();
+    second.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    second.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(true);
+
+    accept();
+    await Promise.resolve().then(() => Promise.resolve());
+
+    expect(input.disabled).toBe(true);
+    expect(second.closed).toBe(true);
+
+    third.open();
+    third.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    third.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(false);
+    conn.dispose();
+  });
+
+  it("cancels pending backoff when acceptance forces reconciliation", async () => {
+    let accept!: () => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((resolve) => { accept = resolve; }),
+    );
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const reconciliation = new FakeSocket();
+    const duplicate = new FakeSocket();
+    const conn = mount({
+      sockets: [first, second, reconciliation, duplicate],
+      shouldReconnect: () => true,
+    });
+    first.open();
+    first.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "accepted during backoff";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    first.drop();
+    vi.advanceTimersByTime(1000);
+    second.drop();
+    accept();
+    await Promise.resolve().then(() => Promise.resolve());
+
+    expect(reconciliation.onopen).not.toBeNull();
+    vi.advanceTimersByTime(60_000);
+    expect(duplicate.onopen).toBeNull();
+
+    reconciliation.open();
+    reconciliation.emit({ type: "reduced_state", state: idleState });
+    expect(input.disabled).toBe(false);
+    conn.dispose();
+    expect(reconciliation.closed).toBe(true);
+  });
+
+  it("does not reconcile when submission acceptance arrives after disposal", async () => {
+    let accept!: () => void;
+    vi.mocked(sendStructuredPrompt).mockImplementationOnce(
+      () => new Promise((resolve) => { accept = resolve; }),
+    );
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    const late = new FakeSocket();
+    const conn = mount({ sockets: [first, second, late], shouldReconnect: () => true });
+    first.open();
+    first.emit({ type: "reduced_state", state: idleState });
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    input.value = "accepted after disposal";
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+
+    first.drop();
+    vi.advanceTimersByTime(1000);
+    second.open();
+    second.emit({ type: "reduced_state", state: idleState });
+    conn.dispose();
+    accept();
+    await Promise.resolve().then(() => Promise.resolve());
+    vi.advanceTimersByTime(60_000);
+
+    expect(second.closed).toBe(true);
+    expect(late.onopen).toBeNull();
+  });
+
+  it("reports a daemon rejection reason and does not schedule a retry", () => {
+    const only = new FakeSocket();
+    const conn = mount({ sockets: [only], shouldReconnect: () => true });
+    only.open();
+    only.drop(4004, "session is not a live structured session");
+    const stateEl = conn.el.querySelector(".attach-state") as HTMLElement;
+    expect(stateEl.dataset.state).toBe("error");
+    expect(stateEl.textContent).toBe("session is not a live structured session");
+    vi.advanceTimersByTime(60_000);
+    // No second socket was ever asked for — only one factory call happened.
+    conn.dispose();
+  });
+});
+
+describe("structured connection: pane lifecycle", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("sendInput is a no-op — there is no PTY behind a structured session", () => {
+    const conn = mount({ sockets: [new FakeSocket()] });
+    expect(() => conn.sendInput("\x0b")).not.toThrow();
+    conn.dispose();
+  });
+
+  it("carries the same off-canvas sessions button as the terminal attach header", () => {
+    const conn = mount({ sockets: [new FakeSocket()] });
+    const btn = conn.el.querySelector(".sessions-btn") as HTMLButtonElement;
+    expect(btn).not.toBeNull();
+    expect(btn.getAttribute("aria-label")).toBe("Show sessions");
+    expect(btn.type).toBe("button");
+
+    let toggled = 0;
+    const onToggle = () => toggled++;
+    document.addEventListener(TOGGLE_DRAWER_EVENT, onToggle);
+    btn.click();
+    document.removeEventListener(TOGGLE_DRAWER_EVENT, onToggle);
+    expect(toggled).toBe(1);
+    conn.dispose();
+  });
+
+  it("focusTerminal focuses the composer only when it is enabled", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: { turn: { responding: true, thinking: false, active_tool_calls: [] } } });
+    conn.focusTerminal();
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    expect(document.activeElement).not.toBe(input);
+    ws.emit({ type: "reduced_state", state: idleState });
+    conn.focusTerminal();
+    expect(document.activeElement).toBe(input);
+    conn.dispose();
+  });
+
+  it("dispose closes the socket and unsubscribes from the store", () => {
+    const store = new CatalogStore({ socket: () => new FakeSocket() as unknown as WebSocket });
+    const unsubscribe = vi.spyOn(store, "subscribe");
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws], store });
+    expect(unsubscribe).toHaveBeenCalled();
+    conn.dispose();
+    expect(ws.closed).toBe(true);
+  });
+
+  it("reflects live worktree/blocked-work data from the store in the rail", () => {
+    const catalogWs = new FakeSocket();
+    const store = new CatalogStore({ socket: () => catalogWs as unknown as WebSocket });
+    store.start();
+    const session: Session = {
+      id: "s1",
+      cwd: "/repo",
+      command: "claude",
+      env: {},
+      metadata: {},
+      status: "Running",
+      created_at: "2026-01-01T00:00:00Z",
+      worktree: { path: "/repo/worktrees/feat/x", base_repo: "/repo" },
+      blocked_work: { uncommitted_files: 1, untracked_files: 0, unpushed_commits: 2 },
+    };
+    catalogWs.emit({ type: "Snapshot", sessions: [session] } as never);
+
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws], store });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+    expect(conn.el.textContent).toContain("feat/x");
+    conn.dispose();
+  });
+});
+
+describe("structured connection: deferred mount focus", () => {
+  let frames: FrameRequestCallback[];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    frames = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      frames.push(cb);
+      return frames.length;
+    });
+  });
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  function runFrames(): void {
+    const pending = frames;
+    frames = [];
+    for (const cb of pending) cb(0);
+  }
+
+  it("does not focus the composer if the pane was parked before its deferred frame ran", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+
+    conn.onMount({ focus: true });
+    conn.onUnmount(); // parked again before the frame below runs
+    runFrames();
+
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    expect(document.activeElement).not.toBe(input);
+    conn.dispose();
+  });
+
+  it("does not focus the composer if it was re-mounted into a different pane before the stale frame ran", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+
+    conn.onMount({ focus: true }); // stale frame #1
+    conn.onUnmount();
+    conn.onMount({ focus: false }); // the pane that actually won focus, without it
+    runFrames(); // both frames fire; only the latest should have any say
+
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    expect(document.activeElement).not.toBe(input);
+    conn.dispose();
+  });
+
+  it("still focuses normally when nothing raced the frame", () => {
+    const ws = new FakeSocket();
+    const conn = mount({ sockets: [ws] });
+    ws.open();
+    ws.emit({ type: "transcript_snapshot", snapshot: { cursor: 0, rows: [] } });
+    ws.emit({ type: "reduced_state", state: idleState });
+
+    conn.onMount({ focus: true });
+    runFrames();
+
+    const input = conn.el.querySelector(".structured-input") as HTMLTextAreaElement;
+    expect(document.activeElement).toBe(input);
+    conn.dispose();
+  });
+});

web/src/structured.ts

@@ -0,0 +1,488 @@
+// A single live structured session: a transcript + rail 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,
+  structuredWsUrl,
+} from "./api.js";
+import { requestToggleDrawer } from "./drawer.js";
+import type { CatalogState, 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 { buildTranscriptRow, renderRail } from "./structuredRender.js";
+import type {
+  AcpPlan,
+  AcpUsage,
+  ReducedState,
+  Session,
+  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: [],
+});
+
+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="st-pills"></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-scroll">
+        <div class="structured-rows"></div>
+        <form class="structured-composer">
+          <textarea class="structured-input" rows="1" placeholder="Reply, or / for commands…"></textarea>
+          <button type="submit" class="btn btn-primary structured-send">Send</button>
+          <button type="button" class="btn structured-cancel" hidden>Cancel turn</button>
+        </form>
+      </div>
+      <aside class="structured-rail"></aside>
+    </div>
+  `;
+
+  const stateEl = el.querySelector(".attach-state") as HTMLSpanElement;
+  const pillsEl = el.querySelector(".st-pills") as HTMLSpanElement;
+  const disconnectBtn = el.querySelector(".disconnect") as HTMLButtonElement;
+  const rowsEl = el.querySelector(".structured-rows") as HTMLDivElement;
+  const railEl = el.querySelector(".structured-rail") as HTMLElement;
+  const bodyEl = el.querySelector(".structured-body") as HTMLElement;
+  const composerForm = el.querySelector(".structured-composer") as HTMLFormElement;
+  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>();
+  let state: ReducedState = { turn: idleTurn() };
+  let pendingApprovalRowId: string | null = null;
+  let latestSession: Session | undefined = store?.snapshot().sessions.get(sessionId);
+  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;
+
+  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 mountRow(row: TranscriptRow): void {
+    const el = buildTranscriptRow(row, approvalStateFor(row));
+    rowEls.set(row.id, el);
+    rowsEl.appendChild(el);
+  }
+
+  function remountRow(row: TranscriptRow): void {
+    const old = rowEls.get(row.id);
+    const oldToolHead = old?.querySelector<HTMLButtonElement>(".st-tool-head") ?? null;
+    const wasExpanded = oldToolHead?.getAttribute("aria-expanded") === "true";
+    const restoreFocus = document.activeElement === oldToolHead;
+    const el = buildTranscriptRow(row, approvalStateFor(row), wasExpanded);
+    rowEls.set(row.id, el);
+    if (old) old.replaceWith(el);
+    else rowsEl.appendChild(el);
+    const newToolHead = el.querySelector<HTMLButtonElement>(".st-tool-head");
+    if (restoreFocus) newToolHead?.focus();
+  }
+
+  function applySnapshot(snapshot: { rows: TranscriptRow[] }): void {
+    rows = [...snapshot.rows];
+    rowIndex.clear();
+    rows.forEach((row, i) => rowIndex.set(row.id, i));
+    rowEls.clear();
+    rowsEl.replaceChildren();
+    for (const row of rows) mountRow(row);
+  }
+
+  function applyDelta(delta: TranscriptDelta | null | undefined): void {
+    if (!delta) return;
+    if (delta.type === "append") {
+      rowIndex.set(delta.row.id, rows.length);
+      rows.push(delta.row);
+      mountRow(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);
+        mountRow(delta.row);
+      } else {
+        rows[i] = delta.row;
+        remountRow(delta.row);
+      }
+    } else {
+      const i = rowIndex.get(delta.id);
+      if (i === undefined) return;
+      rows.splice(i, 1);
+      rowIndex.clear();
+      rows.forEach((row, idx) => rowIndex.set(row.id, idx));
+      rowEls.get(delta.id)?.remove();
+      rowEls.delete(delta.id);
+    }
+  }
+
+  function toolRowCount(): number {
+    return rows.reduce((n, r) => n + (r.kind === "tool_call" || r.kind === "tool_diff" ? 1 : 0), 0);
+  }
+
+  function renderPills(): void {
+    const parts: string[] = [];
+    if (state.model) parts.push(state.model);
+    if (state.mode) parts.push(state.mode);
+    pillsEl.textContent = parts.join(" · ");
+  }
+
+  function renderRailNow(): void {
+    renderRail(railEl, {
+      plan: (state.plan ?? null) as AcpPlan | null,
+      turn: state.turn,
+      toolRowCount: toolRowCount(),
+      usage: (state.usage ?? null) as AcpUsage | null,
+      session: latestSession,
+    });
+  }
+
+  function renderComposerState(): void {
+    const active = state.turn.responding || state.turn.thinking || awaitingBeginGeneration !== null;
+    input.disabled = active;
+    sendBtn.disabled = active;
+    cancelBtn.hidden = !state.turn.responding && !state.turn.thinking;
+  }
+
+  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) {
+      const prev = pendingApprovalRowId;
+      pendingApprovalRowId = newPendingId;
+      if (prev !== null && rowIndex.has(prev)) remountRow(rows[rowIndex.get(prev)!]);
+      if (newPendingId !== null) remountRow(rows[rowIndex.get(newPendingId)!]);
+    }
+    renderPills();
+    renderRailNow();
+    renderComposerState();
+  }
+
+  // ---- 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 autoResize(): void {
+    input.style.height = "auto";
+    input.style.height = `${Math.min(input.scrollHeight, 160)}px`;
+  }
+  input.addEventListener("input", autoResize);
+  input.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      composerForm.requestSubmit();
+    }
+  });
+  composerForm.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const text = input.value;
+    if (!text.trim() || input.disabled) return;
+    const generation = ++submissionGeneration;
+    const submissionSocketGeneration = socketGeneration;
+    awaitingBeginGeneration = generation;
+    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));
+    });
+  });
+
+  // ---- narrow-pane rail collapse (a split pane, not just the viewport) ----
+  const NARROW_BREAKPOINT = 560;
+  const resizeObserver = new ResizeObserver((entries) => {
+    const width = entries[0]?.contentRect.width ?? bodyEl.clientWidth;
+    bodyEl.classList.toggle("st-narrow", width < NARROW_BREAKPOINT);
+  });
+  resizeObserver.observe(bodyEl);
+
+  // ---- live worktree/git-status rail data ----
+  const unsubscribeStore = store?.subscribe((catalog: CatalogState) => {
+    if (disposed) return;
+    latestSession = catalog.sessions.get(sessionId);
+    renderRailNow();
+  });
+
+  // ---- 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;
+
+  return {
+    sessionId,
+    el,
+    onMount(mountOpts?: { focus?: boolean }) {
+      const focusOnMount = mountOpts?.focus !== false;
+      const token = ++mountToken;
+      requestAnimationFrame(() => {
+        if (disposed || token !== mountToken) return; // parked/remounted since this was scheduled
+        if (focusOnMount && !input.disabled) input.focus();
+      });
+    },
+    onUnmount() {
+      mountToken++;
+    },
+    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;
+      mountToken++;
+      cancelReconnect();
+      resizeObserver.disconnect();
+      unsubscribeStore?.();
+      closeCurrentSocket();
+      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,379 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  branchFromWorktreePath,
+  buildTranscriptRow,
+  renderInlineMarkdown,
+  renderRail,
+} from "./structuredRender.js";
+import type { Session, TranscriptRow } from "./types.js";
+
+function row(kind: TranscriptRow["kind"], data: unknown, id = "r1"): TranscriptRow {
+  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>");
+    // 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);
+  });
+});
+
+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("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");
+  });
+});
+
+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")!.className).toBe("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 a plan or notice row without crashing", () => {
+    expect(() => buildTranscriptRow(row("notice", { sessionUpdate: "future" }))).not.toThrow();
+    expect(() => buildTranscriptRow(row("plan", { entries: [] }))).not.toThrow();
+  });
+});
+
+describe("branchFromWorktreePath", () => {
+  it("takes everything after the last /worktrees/ segment", () => {
+    expect(branchFromWorktreePath("/home/n/tea/maestro/worktrees/acp-bridge")).toBe("acp-bridge");
+  });
+
+  it("keeps slashes in a branch name that contains them", () => {
+    expect(branchFromWorktreePath("/repo/worktrees/feature/login")).toBe("feature/login");
+  });
+
+  it("falls back to the basename when there is no /worktrees/ marker", () => {
+    expect(branchFromWorktreePath("/some/other/path")).toBe("path");
+  });
+});
+
+function session(overrides: Partial<Session> = {}): Session {
+  return {
+    id: "s1",
+    cwd: "/repo",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+describe("renderRail", () => {
+  it("omits every section that has nothing to show", () => {
+    const el = document.createElement("div");
+    renderRail(el, {
+      plan: null,
+      turn: { responding: false, thinking: false, active_tool_calls: [] },
+      toolRowCount: 0,
+      usage: null,
+      session: session(),
+    });
+    // Turn always renders (it has a state and a count); the rest are absent.
+    expect(el.querySelectorAll("h3")).toHaveLength(1);
+    expect(el.querySelector("h3")!.textContent).toBe("Turn");
+  });
+
+  it("renders the plan with status marks", () => {
+    const el = document.createElement("div");
+    renderRail(el, {
+      plan: {
+        entries: [
+          { content: "done thing", priority: "high", status: "completed" },
+          { content: "now thing", priority: "high", status: "in_progress" },
+          { content: "later thing", priority: "low", status: "pending" },
+        ],
+      },
+      turn: { responding: false, thinking: false, active_tool_calls: [] },
+      toolRowCount: 0,
+      usage: null,
+      session: session(),
+    });
+    const items = el.querySelectorAll(".st-plan li");
+    expect(items).toHaveLength(3);
+    expect(items[0].className).toBe("st-plan-done");
+    expect(items[1].className).toBe("st-plan-now");
+    expect(items[2].className).toBe("st-plan-todo");
+  });
+
+  it("renders context usage and a meter proportional to used/size", () => {
+    const el = document.createElement("div");
+    renderRail(el, {
+      plan: null,
+      turn: { responding: true, thinking: false, active_tool_calls: ["a"] },
+      toolRowCount: 3,
+      usage: { used: 50_000, size: 200_000 },
+      session: session(),
+    });
+    expect(el.querySelector(".st-meter i")!.getAttribute("style")).toContain("25%");
+  });
+
+  it("renders the worktree section only when the session has one", () => {
+    const el = document.createElement("div");
+    renderRail(el, {
+      plan: null,
+      turn: { responding: false, thinking: false, active_tool_calls: [] },
+      toolRowCount: 0,
+      usage: null,
+      session: session({
+        worktree: { path: "/repo/worktrees/feat/x", base_repo: "/repo" },
+        blocked_work: { uncommitted_files: 2, untracked_files: 1, unpushed_commits: 3 },
+      }),
+    });
+    const headers = [...el.querySelectorAll("h3")].map((h) => h.textContent);
+    expect(headers).toContain("Worktree");
+    const rows = [...el.querySelectorAll(".st-kv-row")].map((r) => r.textContent);
+    expect(rows.some((t) => t?.includes("feat/x"))).toBe(true);
+    expect(rows.some((t) => t?.includes("3"))).toBe(true); // ahead
+    expect(rows.some((t) => t?.includes("dirty") && t.includes("3"))).toBe(true); // 2+1
+  });
+});

web/src/structuredRender.ts

@@ -0,0 +1,526 @@
+// 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 { computeDiffLines, diffStats } from "./structuredDiff.js";
+import type {
+  AcpContentBlock,
+  AcpPermissionOption,
+  AcpPlan,
+  AcpToolCallContent,
+  AcpToolCallLike,
+  AcpUsage,
+  InTheWay,
+  Session,
+  StructuredApprovalDecision,
+  TranscriptRow,
+} 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 "";
+  }
+}
+
+/** A tiny, dependency-free inline renderer: `**bold**`, `*italic*`, and
+ *  `` `code` `` become real markup; everything else stays escaped plain
+ *  text. No block-level markdown (lists, headings) — agent prose is
+ *  paragraphs, not documents. */
+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>");
+}
+
+function renderProse(container: HTMLElement, text: string): void {
+  const paragraphs = text.split(/\n{2,}/);
+  for (const para of paragraphs) {
+    if (!para) continue;
+    const p = document.createElement("p");
+    p.innerHTML = renderInlineMarkdown(para);
+    container.appendChild(p);
+  }
+  if (container.children.length === 0) container.textContent = "";
+}
+
+// ---------------------------------------------------------------------------
+// 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 who = el("div", "st-who");
+    who.textContent = "You";
+    body.appendChild(who);
+    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);
+  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;
+  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);
+  wrap.appendChild(scroller);
+  return wrap;
+}
+
+/** `+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): 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 texts = content
+      .filter((c): c is Extract<AcpToolCallContent, { type: "content" }> => c.type === "content")
+      .map((c) => contentBlockText(c.content))
+      .filter(Boolean);
+    if (texts.length > 0) {
+      const textPanel = el("div", "st-tool-text");
+      textPanel.textContent = texts.join("\n");
+      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");
+  });
+  setExpanded(expanded);
+
+  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);
+  return wrap;
+}
+
+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. `approval` is consulted only for an
+ *  `approval` row; pass it whenever the row might be that kind. */
+export function buildTranscriptRow(
+  row: TranscriptRow,
+  approval?: ApprovalRowState,
+  toolExpanded = false,
+): HTMLElement {
+  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);
+      break;
+    case "approval":
+      built = buildApprovalRow(row, approval ?? { pending: false, onDecide: () => Promise.resolve() });
+      break;
+    default:
+      built = buildPlainRow(row);
+      break;
+  }
+  built.dataset.rowId = row.id;
+  return built;
+}
+
+// ---------------------------------------------------------------------------
+// rail
+// ---------------------------------------------------------------------------
+
+const PLAN_MARK: Record<string, string> = { completed: "✓", in_progress: "▸", pending: "·" };
+const PLAN_CLASS: Record<string, string> = { completed: "done", in_progress: "now", pending: "todo" };
+
+function renderPlanSection(plan: AcpPlan | null | undefined): HTMLElement | null {
+  if (!plan || plan.entries.length === 0) return null;
+  const section = el("div", "st-rail-section");
+  const h = document.createElement("h3");
+  h.textContent = "Plan";
+  section.appendChild(h);
+  const list = document.createElement("ul");
+  list.className = "st-plan";
+  for (const entry of plan.entries) {
+    const li = document.createElement("li");
+    li.className = `st-plan-${PLAN_CLASS[entry.status] ?? "todo"}`;
+    li.setAttribute("aria-label", `${entry.status.replace("_", " ")}: ${entry.content}`);
+    const mark = el("span", "st-plan-mark");
+    mark.textContent = PLAN_MARK[entry.status] ?? "·";
+    mark.setAttribute("aria-hidden", "true");
+    const text = document.createElement("span");
+    text.textContent = entry.content;
+    li.append(mark, text);
+    list.appendChild(li);
+  }
+  section.appendChild(list);
+  return section;
+}
+
+function kv(label: string, value: string): HTMLElement {
+  const row = el("div", "st-kv-row");
+  const k = el("span", "st-kv-k");
+  k.textContent = label;
+  const v = el("span", "st-kv-v");
+  v.textContent = value;
+  row.append(k, v);
+  return row;
+}
+
+function renderTurnSection(
+  turn: { responding: boolean; thinking: boolean; active_tool_calls: string[] },
+  toolRowCount: number,
+  usage: AcpUsage | null | undefined,
+): HTMLElement {
+  const section = el("div", "st-rail-section");
+  const h = document.createElement("h3");
+  h.textContent = "Turn";
+  section.appendChild(h);
+  const box = el("div", "st-kv");
+  const activity = turn.thinking ? "thinking" : turn.responding ? "responding" : "idle";
+  box.appendChild(kv("state", activity));
+  box.appendChild(kv("active tools", String(turn.active_tool_calls.length)));
+  box.appendChild(kv("tool calls", String(toolRowCount)));
+  if (usage?.cost) box.appendChild(kv("cost", `$${usage.cost.amount.toFixed(2)}`));
+  section.appendChild(box);
+  return section;
+}
+
+function renderContextSection(usage: AcpUsage | null | undefined): HTMLElement | null {
+  if (!usage) return null;
+  const section = el("div", "st-rail-section");
+  const h = document.createElement("h3");
+  h.textContent = "Context";
+  section.appendChild(h);
+  const box = el("div", "st-kv");
+  box.appendChild(kv("used", formatTokenCount(usage.used)));
+  box.appendChild(kv("window", formatTokenCount(usage.size)));
+  section.appendChild(box);
+  const meter = el("div", "st-meter");
+  const fill = el("i");
+  const pct = usage.size > 0 ? Math.min(100, (usage.used / usage.size) * 100) : 0;
+  fill.style.width = `${pct}%`;
+  meter.appendChild(fill);
+  section.appendChild(meter);
+  return section;
+}
+
+function formatTokenCount(n: number): string {
+  return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+}
+
+/** `SessionWorktree.path` is `<repo>/worktrees/<branch>` (docs/WORKTREES.md);
+ *  the branch is not carried anywhere else on the wire, so derive it here. */
+export function branchFromWorktreePath(path: string): string {
+  const marker = "/worktrees/";
+  const i = path.indexOf(marker);
+  if (i >= 0) return path.slice(i + marker.length);
+  return path.split("/").filter(Boolean).pop() ?? path;
+}
+
+function renderWorktreeSection(session: Session | undefined): HTMLElement | null {
+  const worktree = session?.worktree;
+  if (!worktree) return null;
+  const section = el("div", "st-rail-section");
+  const h = document.createElement("h3");
+  h.textContent = "Worktree";
+  section.appendChild(h);
+  const box = el("div", "st-kv");
+  box.appendChild(kv("branch", branchFromWorktreePath(worktree.path)));
+  const blocked: InTheWay | null | undefined = session?.blocked_work;
+  box.appendChild(kv("ahead", String(blocked?.unpushed_commits ?? 0)));
+  const dirty = (blocked?.uncommitted_files ?? 0) + (blocked?.untracked_files ?? 0);
+  box.appendChild(kv("dirty", String(dirty)));
+  section.appendChild(box);
+  return section;
+}
+
+export interface RailContext {
+  plan: AcpPlan | null | undefined;
+  turn: { responding: boolean; thinking: boolean; active_tool_calls: string[] };
+  toolRowCount: number;
+  usage: AcpUsage | null | undefined;
+  session: Session | undefined;
+}
+
+/** Rebuild the rail wholesale from the latest state — rails are small, so a
+ *  full rebuild per update is simpler and cheap enough that no incremental
+ *  patching is worth the complexity. */
+export function renderRail(container: HTMLElement, ctx: RailContext): void {
+  const sections = [
+    renderPlanSection(ctx.plan),
+    renderTurnSection(ctx.turn, ctx.toolRowCount, ctx.usage),
+    renderContextSection(ctx.usage),
+    renderWorktreeSection(ctx.session),
+  ].filter((s): s is HTMLElement => s !== null);
+  container.replaceChildren(...sections);
+}

web/src/styles.css

@@ -2165,6 +2165,510 @@ 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 column + rail grid
+   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). */
+
+.st-pills {
+  font-size: var(--fs-11);
+  color: var(--muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.structured-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 232px;
+}
+
+.structured-body.st-narrow {
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: minmax(0, 1fr) auto;
+}
+
+.structured-body.st-narrow .structured-rail {
+  border-left: 0;
+  border-top: 1px solid var(--border);
+  max-height: 40%;
+}
+
+.structured-scroll {
+  min-width: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.structured-rows {
+  padding: var(--sp-3) var(--sp-3) 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-3);
+  min-width: 0;
+}
+
+.structured-rail {
+  border-left: 1px solid var(--border);
+  background: var(--surface-2);
+  padding: var(--sp-3);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-5);
+  min-width: 0;
+  overflow-y: auto;
+}
+
+.structured-rail h3 {
+  margin: 0 0 var(--sp-2);
+  font-size: var(--fs-11);
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--faint);
+  font-weight: 500;
+}
+
+.st-plan {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+}
+
+.st-plan li {
+  display: flex;
+  gap: var(--sp-2);
+  font-size: var(--fs-12);
+  line-height: 1.4;
+}
+
+.st-plan-mark {
+  flex: 0 0 auto;
+  width: 12px;
+  text-align: center;
+}
+
+.st-plan-done {
+  color: var(--faint);
+}
+
+.st-plan-now {
+  color: var(--ink);
+}
+
+.st-plan-now .st-plan-mark,
+.st-plan-done .st-plan-mark {
+  color: var(--live);
+}
+
+.st-plan-todo {
+  color: var(--muted);
+}
+
+.st-plan-todo .st-plan-mark {
+  color: var(--border-strong);
+}
+
+.st-kv {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+  font-size: var(--fs-12);
+}
+
+.st-kv-row {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--sp-2);
+}
+
+.st-kv-k {
+  color: var(--faint);
+}
+
+.st-kv-v {
+  color: var(--ink);
+  font-variant-numeric: tabular-nums;
+}
+
+.st-meter {
+  height: 4px;
+  background: var(--surface-3);
+  border-radius: var(--r-1);
+  overflow: hidden;
+  margin-top: var(--sp-2);
+}
+
+.st-meter i {
+  display: block;
+  height: 100%;
+  background: var(--live);
+}
+
+/* every transcript row carries its own layout; none of them are cards */
+.st-row {
+  display: flex;
+  gap: var(--sp-3);
+  min-width: 0;
+}
+
+.st-body {
+  min-width: 0;
+}
+
+/* user turn: the only tinted block besides the approval — an accent rail,
+   never a full border, so it still reads lighter than the approval card. */
+.st-row-user {
+  border-left: 2px solid var(--accent);
+  background: var(--surface-2);
+  padding: var(--sp-3);
+}
+
+.st-who {
+  font-size: var(--fs-11);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--faint);
+  margin-bottom: var(--sp-1);
+}
+
+.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 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);
+}
+
+/* tool rows: bordered, compact, deliberately not lifted */
+.st-tool {
+  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-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-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-left-width: 3px;
+  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);
+}
+
+/* composer: sticky at the bottom of the scrolling transcript column */
+.structured-composer {
+  position: sticky;
+  bottom: 0;
+  margin-top: var(--sp-3);
+  padding: var(--sp-3);
+  border-top: 1px solid var(--border);
+  background: var(--surface);
+  display: flex;
+  align-items: flex-end;
+  gap: var(--sp-2);
+}
+
+.structured-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  max-height: 160px;
+  resize: none;
+  padding: var(--sp-2) var(--sp-3);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--r-2);
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--font-mono);
+  font-size: var(--fs-13);
+}
+
+.structured-input:focus {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px var(--accent-tint);
+}
+
+.structured-input:disabled {
+  color: var(--faint);
+  background: var(--surface-2);
+}
+
+/* `.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-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 {
+    transition-duration: 0.01ms;
+  }
+}
+
 /* ---------- modal ---------- */
 
 .modal-backdrop {

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,189 @@ 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[];
+}
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** `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;
+}
+
+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