fix(diff): preserve collapsed EOF marker

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.

CLAUDE.md

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

Cargo.toml

@@ -10,6 +10,7 @@ repository = "https://git.naps.pt/naps62/maestro"
 publish = false
 
 [workspace.dependencies]
+agent-client-protocol = { version = "2.1", features = ["unstable_tool_call_name"] }
 axum = { version = "0.7", features = ["ws"] }
 chrono = { version = "0.4", default-features = false, features = ["clock", "serde"] }
 clap = { version = "4.5", features = ["derive", "env"] }
@@ -17,6 +18,7 @@ crossterm = { version = "0.28", features = ["event-stream"] }
 dirs = "5"
 futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] }
 libc = "0.2"
+maestro-acp = { path = "crates/maestro-acp" }
 maestro-config = { path = "crates/maestro-config" }
 # `default-features = false` so each consumer opts into `haiku-autoname`
 # through its own feature of the same name (#131); a workspace entry that
@@ -38,9 +40,11 @@ tempfile = "3"
 thiserror = "1"
 tokio = { version = "1", features = ["macros", "rt-multi-thread", "sync", "time", "net", "io-util", "fs", "signal", "process"] }
 tokio-tungstenite = "0.21"
+tokio-util = { version = "0.7", features = ["compat"] }
 toml = "0.8"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+unicode-width = "0.1"
 uuid = { version = "1", features = ["v4", "serde"] }
 ratatui = "0.28"
 vt100 = "0.15"

crates/maestro-acp/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "maestro-acp"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish.workspace = true
+description = "ACP client role: one claude-code-acp child per structured session"
+
+[dependencies]
+agent-client-protocol.workspace = true
+libc.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+tokio-util.workspace = true
+tracing.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true

crates/maestro-acp/src/lib.rs

@@ -0,0 +1,721 @@
+//! ACP client role for the daemon (#134): one `claude-code-acp` child per
+//! structured session.
+//!
+//! The daemon is the client; the adapter is the agent. [`spawn`] starts the
+//! adapter as a child process with stdio pipes, in the session's `cwd` with
+//! the session's env, runs the `initialize` + `session/new` handshake, and
+//! hands back an [`AcpSession`] that owns the connection for the life of the
+//! session.
+//!
+//! **The handshake declares almost nothing.** `initialize` reports
+//! `fs.readTextFile`, `fs.writeTextFile` and `terminal` as `false`, so the
+//! adapter uses Claude Code's own Read / Write / Bash instead of asking the
+//! daemon to act on its behalf — exactly what already happens in the
+//! terminal view. `session/request_permission` is the one client method that
+//! gets a real implementation, in #139; here it is a stub that declines.
+//!
+//! Every `session/update` notification the adapter sends lands on an
+//! unbounded channel the session owns ([`AcpSession::take_updates`]). Nothing
+//! is dropped while nobody reads: #135 takes the receiver and persists each
+//! notification to the per-session event log before broadcasting it.
+//!
+//! A respawn after a daemon restart sets [`SpawnConfig::load_session`] and
+//! the handshake runs `session/load` with the stored id instead of
+//! `session/new`. The history the agent streams back while that request is
+//! in flight is *not* delivered: the daemon's event log already holds it,
+//! and replaying it would double every line.
+//!
+//! The child is a child of the daemon, full stop. It shares the daemon's
+//! process group, is marked to receive `SIGTERM` when the daemon dies
+//! (`PR_SET_PDEATHSIG` on Linux), and [`AcpSession::terminate`] is what both
+//! `DELETE /api/sessions/:id` and daemon shutdown call: `session/cancel`, a
+//! short wait, then `SIGTERM`, then `SIGKILL` as the last resort.
+
+#![deny(missing_debug_implementations)]
+
+use std::collections::{HashMap, VecDeque};
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+use std::process::{ExitStatus, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use agent_client_protocol::schema::v1::{
+    CancelNotification, ClientCapabilities, ContentBlock, FileSystemCapabilities, Implementation,
+    InitializeRequest, LoadSessionRequest, NewSessionRequest, PromptRequest,
+    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse, SessionId,
+    SessionNotification,
+};
+use agent_client_protocol::schema::ProtocolVersion;
+use agent_client_protocol::{ByteStreams, Client};
+use tokio::io::AsyncBufReadExt;
+use tokio::sync::{mpsc, oneshot, watch};
+use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
+
+pub use agent_client_protocol::schema::v1 as schema;
+
+/// The adapter binary, resolved on `PATH`.
+pub const ADAPTER_BIN: &str = "claude-code-acp";
+
+/// How to install the adapter when it is missing. Named in the error so an
+/// operator staring at a failed session knows what to run.
+pub const INSTALL_COMMAND: &str =
+    "npm install -g --prefix ~/.local @zed-industries/claude-code-acp";
+
+/// How long `initialize` + `session/new` may take before the spawn is
+/// declared failed. The real adapter boots a node process and the Claude
+/// Code SDK behind it; a slow machine takes seconds, never a minute.
+pub const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(60);
+
+/// How long [`AcpSession::terminate`] waits after `session/cancel` before
+/// sending `SIGTERM`. Cancel is a courtesy that lets the adapter finish the
+/// turn it is on; the signal is what actually ends it.
+pub const CANCEL_GRACE: Duration = Duration::from_millis(500);
+
+/// How long [`AcpSession::terminate`] waits after `SIGTERM` before `SIGKILL`.
+pub const TERM_GRACE: Duration = Duration::from_secs(2);
+
+/// Bytes of the child's stderr kept for the failure message.
+const STDERR_TAIL_BYTES: usize = 4096;
+
+/// What [`spawn`] needs to start one adapter.
+#[derive(Debug, Clone)]
+pub struct SpawnConfig {
+    /// Working directory of the child and `cwd` of `session/new`.
+    pub cwd: PathBuf,
+    /// Environment laid over the daemon's own for the child. A `PATH` in
+    /// here is also what the adapter is resolved against, since that is the
+    /// `PATH` the child would see.
+    pub env: HashMap<String, String>,
+    /// Upper bound on the handshake; [`HANDSHAKE_TIMEOUT`] by default.
+    pub handshake_timeout: Duration,
+    /// An existing ACP session id to resume with `session/load` (#135)
+    /// instead of opening a fresh one. The adapter must advertise
+    /// `loadSession`; the handshake fails otherwise.
+    pub load_session: Option<String>,
+}
+
+impl SpawnConfig {
+    pub fn new(cwd: impl Into<PathBuf>, env: HashMap<String, String>) -> Self {
+        Self {
+            cwd: cwd.into(),
+            env,
+            handshake_timeout: HANDSHAKE_TIMEOUT,
+            load_session: None,
+        }
+    }
+
+    /// Resume `session_id` with `session/load` instead of `session/new`.
+    pub fn load_session(mut self, session_id: impl Into<String>) -> Self {
+        self.load_session = Some(session_id.into());
+        self
+    }
+}
+
+/// A blocked ACP permission request delivered to the daemon.
+#[derive(Debug)]
+pub struct PermissionRequest {
+    /// The prompt turn that was active when ACP delivered this callback.
+    pub turn: u64,
+    pub request: RequestPermissionRequest,
+    pub response: oneshot::Sender<RequestPermissionOutcome>,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum AcpError {
+    /// The adapter is not on `PATH`. The message names the install command
+    /// so the failed session is actionable rather than silently dead.
+    #[error("{ADAPTER_BIN} not found on PATH; install it with: {INSTALL_COMMAND}")]
+    AdapterMissing,
+    #[error("failed to start {ADAPTER_BIN}: {0}")]
+    Spawn(#[source] std::io::Error),
+    /// The adapter answered the handshake with an error.
+    #[error("ACP handshake failed: {0}")]
+    Handshake(String),
+    /// The adapter went away before the handshake finished. Carries the
+    /// tail of its stderr, which is where a missing Claude login shows up.
+    #[error("{ADAPTER_BIN} exited during the ACP handshake ({status}){stderr}")]
+    ExitedEarly { status: String, stderr: String },
+    #[error("ACP handshake timed out after {0:?}")]
+    HandshakeTimeout(Duration),
+}
+
+/// Resolve [`ADAPTER_BIN`] against the `PATH` the child would run with: the
+/// session env's `PATH` when it sets one, the daemon's own otherwise.
+pub fn resolve_adapter(env: &HashMap<String, String>) -> Option<PathBuf> {
+    let path: OsString = match env.get("PATH") {
+        Some(p) => OsString::from(p),
+        None => std::env::var_os("PATH")?,
+    };
+    std::env::split_paths(&path)
+        .filter(|dir| !dir.as_os_str().is_empty())
+        .map(|dir| dir.join(ADAPTER_BIN))
+        .find(|candidate| is_executable(candidate))
+}
+
+fn is_executable(path: &Path) -> bool {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::metadata(path)
+        .map(|m| m.is_file() && m.permissions().mode() & 0o111 != 0)
+        .unwrap_or(false)
+}
+
+enum Command {
+    Cancel,
+    Prompt {
+        text: String,
+        turn: u64,
+        done: oneshot::Sender<Result<(), String>>,
+    },
+    Close,
+}
+
+enum ChildCommand {
+    Signal(libc::c_int),
+    Reap(oneshot::Sender<bool>),
+}
+
+#[derive(Debug, Default)]
+struct PermissionTurnState {
+    active: Option<u64>,
+}
+
+impl PermissionTurnState {
+    fn begin(&mut self, turn: u64) {
+        self.active = Some(turn);
+    }
+
+    fn cancel_active(&mut self) {
+        self.active = None;
+    }
+
+    fn finish(&mut self, turn: u64) {
+        if self.active == Some(turn) {
+            self.active = None;
+        }
+    }
+
+    fn callback_turn(&self) -> Option<u64> {
+        self.active
+    }
+}
+
+/// Why the handshake did not produce a session id.
+enum ReadyError {
+    /// The adapter answered with an error.
+    Handshake(String),
+    /// The transport closed under the request: the child is gone.
+    Closed,
+}
+
+fn ready_error(e: agent_client_protocol::Error) -> ReadyError {
+    if agent_client_protocol::is_incoming_transport_closed(&e) {
+        ReadyError::Closed
+    } else {
+        ReadyError::Handshake(e.to_string())
+    }
+}
+
+/// A live ACP connection to one adapter child. Dropping it sends `SIGTERM`
+/// if the child is still running; [`AcpSession::terminate`] is the polite
+/// version.
+#[derive(Debug)]
+pub struct AcpSession {
+    session_id: String,
+    pid: u32,
+    commands: mpsc::UnboundedSender<Command>,
+    child_commands: mpsc::UnboundedSender<ChildCommand>,
+    updates: Mutex<Option<mpsc::UnboundedReceiver<SessionNotification>>>,
+    permission_requests: Mutex<Option<mpsc::UnboundedReceiver<PermissionRequest>>>,
+    exit: watch::Receiver<Option<ExitStatus>>,
+}
+
+impl AcpSession {
+    /// The id `session/new` returned. What a respawn passes to
+    /// `session/load` (#135).
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// The adapter's pid.
+    pub fn pid(&self) -> u32 {
+        self.pid
+    }
+
+    /// Whether the child has been reaped.
+    pub fn has_exited(&self) -> bool {
+        self.exit.borrow().is_some()
+    }
+
+    /// Reap the child if it has already exited.
+    pub async fn reap_if_exited(&self) -> bool {
+        if self.has_exited() {
+            return true;
+        }
+        let (sent, received) = oneshot::channel();
+        if self.child_commands.send(ChildCommand::Reap(sent)).is_err() {
+            return self.has_exited();
+        }
+        received.await.unwrap_or_else(|_| self.has_exited())
+    }
+
+    /// Wait for the child to exit.
+    pub async fn wait(&self) -> Option<ExitStatus> {
+        wait_exit(&self.exit).await
+    }
+
+    /// The stream of raw `session/update` notifications, handed out once.
+    /// Notifications that arrived before the take are still queued on it.
+    pub fn take_updates(&self) -> Option<mpsc::UnboundedReceiver<SessionNotification>> {
+        self.updates.lock().expect("updates mutex").take()
+    }
+
+    pub fn take_permission_requests(&self) -> Option<mpsc::UnboundedReceiver<PermissionRequest>> {
+        self.permission_requests
+            .lock()
+            .expect("permission requests")
+            .take()
+    }
+
+    /// Send `session/cancel`. Fire-and-forget: a closed connection means the
+    /// child is already gone, which is the outcome cancel was after.
+    pub fn cancel(&self) {
+        let _ = self.commands.send(Command::Cancel);
+    }
+
+    /// Send a user prompt and receive completion once the agent ends the turn.
+    pub fn prompt(
+        &self,
+        text: String,
+        turn: u64,
+    ) -> Result<oneshot::Receiver<Result<(), String>>, String> {
+        let (done_tx, done_rx) = oneshot::channel();
+        self.commands
+            .send(Command::Prompt {
+                text,
+                turn,
+                done: done_tx,
+            })
+            .map_err(|_| "ACP connection is closed".to_string())?;
+        Ok(done_rx)
+    }
+
+    /// End the child: `session/cancel`, wait `cancel_grace`, `SIGTERM`, wait
+    /// `term_grace`, `SIGKILL`. Returns once the child has been reaped.
+    pub async fn terminate(&self, cancel_grace: Duration, term_grace: Duration) {
+        self.cancel();
+        if tokio::time::timeout(cancel_grace, self.wait())
+            .await
+            .is_ok()
+        {
+            return;
+        }
+        self.signal(libc::SIGTERM);
+        if tokio::time::timeout(term_grace, self.wait()).await.is_ok() {
+            return;
+        }
+        tracing::warn!(
+            pid = self.pid,
+            "{ADAPTER_BIN} ignored SIGTERM; sending SIGKILL"
+        );
+        self.signal(libc::SIGKILL);
+        let _ = self.commands.send(Command::Close);
+        self.wait().await;
+    }
+
+    fn signal(&self, sig: libc::c_int) {
+        let _ = self.child_commands.send(ChildCommand::Signal(sig));
+    }
+}
+
+impl Drop for AcpSession {
+    fn drop(&mut self) {
+        self.signal(libc::SIGTERM);
+        let _ = self.commands.send(Command::Close);
+    }
+}
+
+/// Start the adapter for one session and run the handshake.
+///
+/// Fails without a running child: on any error the process is already
+/// signalled, so a failed session never leaves a stray adapter behind.
+pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
+    let adapter = resolve_adapter(&config.env).ok_or(AcpError::AdapterMissing)?;
+
+    let mut cmd = tokio::process::Command::new(&adapter);
+    cmd.current_dir(&config.cwd)
+        .envs(&config.env)
+        // Claude Code refuses to start when it thinks it is nested inside
+        // another Claude Code session; a daemon launched from one would
+        // otherwise never get a structured session up.
+        .env_remove("CLAUDECODE")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        // If the daemon is dropped without a graceful shutdown the runtime
+        // still tears the task holding this `Child` down, and that kills it.
+        .kill_on_drop(true);
+    #[cfg(target_os = "linux")]
+    {
+        // Same process group as the daemon (no setpgid), and SIGTERM when the
+        // daemon dies however it dies: an agent that outlives its daemon is
+        // exactly the orphan #134 rules out.
+        // SAFETY: prctl is async-signal-safe and touches no shared state.
+        unsafe {
+            cmd.pre_exec(|| {
+                libc::prctl(libc::PR_SET_PDEATHSIG, libc::SIGTERM);
+                Ok(())
+            });
+        }
+    }
+    let mut child = cmd.spawn().map_err(AcpError::Spawn)?;
+    let pid = child.id().expect("child pid is known before wait");
+    let stdin = child.stdin.take().expect("piped stdin");
+    let stdout = child.stdout.take().expect("piped stdout");
+    let stderr = child.stderr.take().expect("piped stderr");
+
+    let stderr_tail = Arc::new(Mutex::new(VecDeque::<u8>::new()));
+    tokio::spawn(drain_stderr(stderr, pid, stderr_tail.clone()));
+
+    let (exit_tx, exit_rx) = watch::channel(None);
+    let (child_commands_tx, child_commands_rx) = mpsc::unbounded_channel();
+    tokio::spawn(supervise_child(child, pid, child_commands_rx, exit_tx));
+
+    let (updates_tx, updates_rx) = mpsc::unbounded_channel();
+    let (permission_tx, permission_rx) = mpsc::unbounded_channel();
+    let (commands_tx, commands_rx) = mpsc::unbounded_channel();
+    let (ready_tx, ready_rx) = oneshot::channel();
+    let transport = ByteStreams::new(stdin.compat_write(), stdout.compat());
+    tokio::spawn(run_connection(
+        transport,
+        config.cwd.clone(),
+        config.load_session.clone(),
+        updates_tx,
+        permission_tx,
+        commands_rx,
+        ready_tx,
+    ));
+
+    let outcome = tokio::time::timeout(config.handshake_timeout, ready_rx).await;
+    let failure = match outcome {
+        Ok(Ok(Ok(session_id))) => {
+            return Ok(AcpSession {
+                session_id,
+                pid,
+                commands: commands_tx,
+                child_commands: child_commands_tx,
+                updates: Mutex::new(Some(updates_rx)),
+                permission_requests: Mutex::new(Some(permission_rx)),
+                exit: exit_rx,
+            });
+        }
+        Ok(Ok(Err(ReadyError::Handshake(message)))) => AcpError::Handshake(message),
+        Ok(Ok(Err(ReadyError::Closed))) | Ok(Err(_)) => {
+            // The connection ended before the handshake did: the child went
+            // away. Reap it so the status is real, then report.
+            let status = wait_exit(&exit_rx).await;
+            let stderr = {
+                let mut tail = stderr_tail.lock().expect("stderr tail");
+                tail.make_contiguous();
+                String::from_utf8_lossy(tail.as_slices().0)
+                    .trim()
+                    .to_string()
+            };
+            AcpError::ExitedEarly {
+                status: status.map_or_else(|| "unknown status".into(), |s| s.to_string()),
+                stderr: if stderr.is_empty() {
+                    String::new()
+                } else {
+                    format!(": {stderr}")
+                },
+            }
+        }
+        Err(_) => AcpError::HandshakeTimeout(config.handshake_timeout),
+    };
+    // No half-started adapter survives a failed spawn.
+    let _ = commands_tx.send(Command::Close);
+    let _ = child_commands_tx.send(ChildCommand::Signal(libc::SIGTERM));
+    if tokio::time::timeout(TERM_GRACE, wait_exit(&exit_rx))
+        .await
+        .is_err()
+    {
+        let _ = child_commands_tx.send(ChildCommand::Signal(libc::SIGKILL));
+        wait_exit(&exit_rx).await;
+    }
+    Err(failure)
+}
+
+async fn wait_exit(exit: &watch::Receiver<Option<ExitStatus>>) -> Option<ExitStatus> {
+    let mut exit = exit.clone();
+    let status = exit.wait_for(|s| s.is_some()).await.ok()?;
+    *status
+}
+
+async fn supervise_child(
+    mut child: tokio::process::Child,
+    pid: u32,
+    mut commands: mpsc::UnboundedReceiver<ChildCommand>,
+    exit_tx: watch::Sender<Option<ExitStatus>>,
+) {
+    loop {
+        tokio::select! {
+            status = child.wait() => {
+                let status = status.ok();
+                tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                let _ = exit_tx.send(status);
+                return;
+            }
+            command = commands.recv() => match command {
+                Some(ChildCommand::Signal(sig)) => {
+                    // This task alone owns `child`. It cannot reap the child
+                    // between receiving this command and sending the signal,
+                    // so its PID cannot be reused in that window.
+                    unsafe { libc::kill(pid as libc::pid_t, sig) };
+                }
+                Some(ChildCommand::Reap(done)) => match child.try_wait() {
+                    Ok(Some(status)) => {
+                        let _ = done.send(true);
+                        tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                        let _ = exit_tx.send(Some(status));
+                        return;
+                    }
+                    Ok(None) => {
+                        let _ = done.send(false);
+                    }
+                    Err(error) => {
+                        tracing::warn!(pid, %error, "could not reap {ADAPTER_BIN}");
+                        let _ = done.send(false);
+                    }
+                },
+                None => {
+                    // The session vanished without a command receiver. This
+                    // task still owns the unreaped child, so this cannot hit
+                    // a reused PID.
+                    unsafe { libc::kill(pid as libc::pid_t, libc::SIGTERM) };
+                    let status = child.wait().await.ok();
+                    tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                    let _ = exit_tx.send(status);
+                    return;
+                }
+            },
+        }
+    }
+}
+
+/// The capabilities the daemon declares: none of the filesystem or terminal
+/// surface, so the adapter falls back to Claude Code's own tools.
+fn client_capabilities() -> ClientCapabilities {
+    ClientCapabilities::new()
+        .fs(FileSystemCapabilities::new()
+            .read_text_file(false)
+            .write_text_file(false))
+        .terminal(false)
+}
+
+async fn run_connection<T>(
+    transport: T,
+    cwd: PathBuf,
+    load_session: Option<String>,
+    updates_tx: mpsc::UnboundedSender<SessionNotification>,
+    permission_requests: mpsc::UnboundedSender<PermissionRequest>,
+    mut commands_rx: mpsc::UnboundedReceiver<Command>,
+    ready_tx: oneshot::Sender<Result<String, ReadyError>>,
+) where
+    T: agent_client_protocol::ConnectTo<Client> + 'static,
+{
+    // Set while `session/load` is in flight. Notification handlers run in
+    // the dispatch loop, in arrival order, so everything the agent streams
+    // before its load response sees the flag up and is dropped: that is the
+    // history the event log already holds (#135).
+    let replaying = Arc::new(AtomicBool::new(false));
+    let replaying_seen = replaying.clone();
+    // ACP callbacks have no turn id. The daemon never queues a later prompt
+    // until a cancelled prompt settles, so this active turn is unambiguous.
+    let permission_turn = Arc::new(Mutex::new(PermissionTurnState::default()));
+    let permission_turn_seen = permission_turn.clone();
+    let result = Client
+        .builder()
+        .name("maestro")
+        .on_receive_notification(
+            async move |notification: SessionNotification, _cx| {
+                if replaying_seen.load(Ordering::SeqCst) {
+                    tracing::trace!("dropping replayed notification during session/load");
+                    return Ok(());
+                }
+                // A dropped receiver only means nobody wants updates any more.
+                let _ = updates_tx.send(notification);
+                Ok(())
+            },
+            agent_client_protocol::on_receive_notification!(),
+        )
+        .on_receive_request(
+            async move |request: RequestPermissionRequest, responder, _cx| {
+                let turn = permission_turn_seen
+                    .lock()
+                    .expect("permission turn state")
+                    .callback_turn();
+                let Some(turn) = turn else {
+                    return responder.respond(RequestPermissionResponse::new(
+                        RequestPermissionOutcome::Cancelled,
+                    ));
+                };
+                let (response, received) = oneshot::channel();
+                if permission_requests
+                    .send(PermissionRequest {
+                        turn,
+                        request,
+                        response,
+                    })
+                    .is_err()
+                {
+                    return responder.respond(RequestPermissionResponse::new(
+                        RequestPermissionOutcome::Cancelled,
+                    ));
+                }
+                let outcome = received.await.unwrap_or(RequestPermissionOutcome::Cancelled);
+                responder.respond(RequestPermissionResponse::new(outcome))
+            },
+            agent_client_protocol::on_receive_request!(),
+        )
+        .connect_with(transport, async move |cx| {
+            let init = InitializeRequest::new(ProtocolVersion::V1)
+                .client_capabilities(client_capabilities())
+                .client_info(Implementation::new("maestro", env!("CARGO_PKG_VERSION")));
+            let initialized = match cx.send_request(init).block_task().await {
+                Ok(r) => r,
+                Err(e) => {
+                    let _ = ready_tx.send(Err(ready_error(e)));
+                    return Ok(());
+                }
+            };
+            let session_id = match load_session {
+                Some(existing) => {
+                    if !initialized.agent_capabilities.load_session {
+                        let _ = ready_tx.send(Err(ReadyError::Handshake(format!(
+                            "{ADAPTER_BIN} does not advertise loadSession; cannot resume session {existing}"
+                        ))));
+                        return Ok(());
+                    }
+                    replaying.store(true, Ordering::SeqCst);
+                    let (loaded_tx, loaded_rx) = oneshot::channel();
+                    let replaying_done = replaying.clone();
+                    if let Err(e) = cx
+                        .send_request(LoadSessionRequest::new(existing.clone(), cwd))
+                        .on_receiving_result(move |result| {
+                            replaying_done.store(false, Ordering::SeqCst);
+                            async move {
+                                let _ = loaded_tx.send(result);
+                                Ok(())
+                            }
+                        })
+                    {
+                        let _ = ready_tx.send(Err(ready_error(e)));
+                        return Ok(());
+                    }
+                    match loaded_rx.await {
+                        Ok(Ok(_)) => {}
+                        Ok(Err(e)) => {
+                            let _ = ready_tx.send(Err(ready_error(e)));
+                            return Ok(());
+                        }
+                        Err(_) => {
+                            let _ = ready_tx.send(Err(ReadyError::Handshake(
+                                "session/load response was not delivered".into(),
+                            )));
+                            return Ok(());
+                        }
+                    }
+                    existing
+                }
+                None => match cx
+                    .send_request(NewSessionRequest::new(cwd))
+                    .block_task()
+                    .await
+                {
+                    Ok(created) => created.session_id.0.to_string(),
+                    Err(e) => {
+                        let _ = ready_tx.send(Err(ready_error(e)));
+                        return Ok(());
+                    }
+                },
+            };
+            let _ = ready_tx.send(Ok(session_id.clone()));
+
+            loop {
+                tokio::select! {
+                    cmd = commands_rx.recv() => match cmd {
+                        Some(Command::Cancel) => {
+                            permission_turn
+                                .lock()
+                                .expect("permission turn state")
+                                .cancel_active();
+                            let _ = cx.send_notification(CancelNotification::new(
+                                SessionId::new(session_id.as_str()),
+                            ));
+                        }
+                        Some(Command::Prompt { text, turn, done }) => {
+                            permission_turn
+                                .lock()
+                                .expect("permission turn state")
+                                .begin(turn);
+                            let request = PromptRequest::new(
+                                SessionId::new(session_id.as_str()),
+                                vec![ContentBlock::from(text)],
+                            );
+                            let done = Arc::new(Mutex::new(Some(done)));
+                            let callback_done = done.clone();
+                            let callback_turn = permission_turn.clone();
+                            if let Err(error) = cx.send_request(request).on_receiving_result(move |result| {
+                                let callback_done = callback_done.clone();
+                                let callback_turn = callback_turn.clone();
+                                async move {
+                                    callback_turn
+                                        .lock()
+                                        .expect("permission turn state")
+                                        .finish(turn);
+                                    if let Some(done) = callback_done.lock().expect("prompt sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|e| e.to_string()));
+                                    }
+                                    Ok(())
+                                }
+                            }) {
+                                permission_turn
+                                    .lock()
+                                    .expect("permission turn state")
+                                    .finish(turn);
+                                if let Some(done) = done.lock().expect("prompt sender").take() {
+                                    let _ = done.send(Err(error.to_string()));
+                                }
+                            }
+                        }
+                        Some(Command::Close) | None => break,
+                    },
+                    _ = cx.incoming_closed() => break,
+                }
+            }
+            Ok(())
+        })
+        .await;
+    if let Err(e) = result {
+        tracing::debug!(error = %e, "ACP connection ended with an error");
+    }
+}
+
+async fn drain_stderr(
+    stderr: tokio::process::ChildStderr,
+    pid: u32,
+    tail: Arc<Mutex<VecDeque<u8>>>,
+) {
+    let mut lines = tokio::io::BufReader::new(stderr).lines();
+    while let Ok(Some(line)) = lines.next_line().await {
+        tracing::debug!(pid, "{ADAPTER_BIN}: {line}");
+        let mut tail = tail.lock().expect("stderr tail");
+        tail.extend(line.as_bytes());
+        tail.push_back(b'\n');
+        while tail.len() > STDERR_TAIL_BYTES {
+            tail.pop_front();
+        }
+        tail.make_contiguous();
+    }
+}

crates/maestro-acp/tests/fake_acp_agent.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""A deterministic stand-in for `claude-code-acp` (#134).
+
+Speaks just enough JSON-RPC over stdio for the daemon's handshake:
+answers `initialize` and `session/new`, logs every method it receives, and
+exits on SIGTERM. Tests point `PATH` at a directory holding this file under
+the adapter's name, so the real adapter (which needs Claude auth and is
+slow) never runs in the deterministic suite.
+
+Environment knobs, all optional:
+
+  FAKE_ACP_LOG            append one line per event to this file:
+                            start pid=<pid> cwd=<cwd>
+                            env <NAME>=<value>       (for FAKE_ACP_ECHO_ENV)
+                            caps <json of clientCapabilities>
+                            recv <method>
+                            signal SIGTERM
+  FAKE_ACP_ECHO_ENV       name of one env var to log at start
+  FAKE_ACP_INIT_FAIL=1    answer `initialize` with a JSON-RPC error
+  FAKE_ACP_DELAY_SESSION_NEW_MS=n  wait n milliseconds before answering
+                             `session/new`
+  FAKE_ACP_EXIT_AFTER_NEW=1  exit 0 right after answering `session/new`
+  FAKE_ACP_EXIT_ON_CANCEL=1  exit 0 on `session/cancel` (default: keep running
+                             so the SIGTERM path is exercised)
+  FAKE_ACP_IGNORE_EOF=1      keep running after stdin closes, until signalled
+  FAKE_ACP_EMIT_ON_CANCEL=1  emit a final notification before handling cancel
+  FAKE_ACP_CANCEL_SETTLES=1  complete the outstanding prompt on cancel
+  FAKE_ACP_NO_LOAD=1      advertise `loadSession: false`
+  FAKE_ACP_LOAD_REPLAY=n  on `session/load`, replay n `agent_message_chunk`
+                            notifications ("replayed <i>") before answering,
+                            the way a real agent streams history back
+  FAKE_ACP_LOAD_FAIL=1    answer `session/load` with a JSON-RPC error
+  FAKE_ACP_DELAY_PROMPT_MS=n  wait before answering `session/prompt`
+  FAKE_ACP_PROMPT_FAIL=1  answer every `session/prompt` with a JSON-RPC error
+  FAKE_ACP_PROMPT_FAIL_ONCE=1  answer only the first `session/prompt` with a
+                             JSON-RPC error
+  FAKE_ACP_PERMISSION_AFTER_CANCEL=1  defer the first prompt's permission
+                             callback until a later prompt
+
+Signals: SIGUSR1 emits one `agent_message_chunk` notification ("tick <n>",
+counting from 1) and logs `emit tick <n>`, so a test can make the agent
+speak on demand (#135).
+"""
+import json
+import os
+import signal
+import sys
+import time
+
+LOG = os.environ.get("FAKE_ACP_LOG")
+
+
+def log(line):
+    if not LOG:
+        return
+    with open(LOG, "a") as f:
+        f.write(line + "\n")
+        f.flush()
+
+
+def send(obj):
+    sys.stdout.write(json.dumps(obj) + "\n")
+    sys.stdout.flush()
+
+
+def on_sigterm(_signum, _frame):
+    log("signal SIGTERM")
+    sys.exit(0)
+
+
+signal.signal(signal.SIGTERM, on_sigterm)
+
+session_id = f"fake-{os.getpid()}"
+ticks = 0
+prompt_failures = 0
+pending_prompt_id = None
+pending_permission_id = None
+delayed_permission = False
+
+
+def chunk(text):
+    return {"jsonrpc": "2.0", "method": "session/update", "params": {
+        "sessionId": session_id,
+        "update": {"sessionUpdate": "agent_message_chunk",
+                   "content": {"type": "text", "text": text}},
+    }}
+
+
+def on_sigusr1(_signum, _frame):
+    global ticks
+    ticks += 1
+    send(chunk(f"tick {ticks}"))
+    log(f"emit tick {ticks}")
+
+
+signal.signal(signal.SIGUSR1, on_sigusr1)
+
+log(f"start pid={os.getpid()} cwd={os.getcwd()}")
+echo = os.environ.get("FAKE_ACP_ECHO_ENV")
+if echo:
+    log(f"env {echo}={os.environ.get(echo, '')}")
+
+for raw in sys.stdin:
+    raw = raw.strip()
+    if not raw:
+        continue
+    msg = json.loads(raw)
+    method = msg.get("method")
+    if method is None:
+        # A response to something we sent; nothing to do.
+        if msg.get("id") == pending_permission_id:
+            log("permission response " + json.dumps(msg.get("result"), sort_keys=True))
+            send({"jsonrpc": "2.0", "id": pending_prompt_id,
+                  "result": {"stopReason": "end_turn"}})
+            pending_prompt_id = None
+            pending_permission_id = None
+        continue
+    log(f"recv {method}")
+    rid = msg.get("id")
+    params = msg.get("params") or {}
+
+    if method == "initialize":
+        log("caps " + json.dumps(params.get("clientCapabilities", {}), sort_keys=True))
+        if os.environ.get("FAKE_ACP_INIT_FAIL") == "1":
+            send({"jsonrpc": "2.0", "id": rid,
+                  "error": {"code": -32000, "message": "fake init failure"}})
+            continue
+        send({"jsonrpc": "2.0", "id": rid, "result": {
+            "protocolVersion": params.get("protocolVersion", 1),
+            "agentCapabilities": {
+                "loadSession": os.environ.get("FAKE_ACP_NO_LOAD") != "1"},
+            "agentInfo": {"name": "fake-acp-agent", "version": "0.0.0"},
+            "authMethods": [],
+        }})
+    elif method == "session/new":
+        time.sleep(int(os.environ.get("FAKE_ACP_DELAY_SESSION_NEW_MS", "0")) / 1000)
+        send({"jsonrpc": "2.0", "id": rid, "result": {"sessionId": session_id}})
+        send(chunk("hello from fake"))
+        if os.environ.get("FAKE_ACP_EXIT_AFTER_NEW") == "1":
+            sys.exit(0)
+    elif method == "session/load":
+        session_id = params.get("sessionId")
+        log(f"recv session/load sessionId={session_id}")
+        if os.environ.get("FAKE_ACP_LOAD_FAIL") == "1":
+            send({"jsonrpc": "2.0", "id": rid,
+                  "error": {"code": -32000, "message": "fake load failure"}})
+            continue
+        for i in range(int(os.environ.get("FAKE_ACP_LOAD_REPLAY", "0"))):
+            send(chunk(f"replayed {i + 1}"))
+        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+        send(chunk("hello after load"))
+    elif method == "session/cancel":
+        if os.environ.get("FAKE_ACP_EMIT_ON_CANCEL") == "1":
+            send(chunk("final on cancel"))
+        if (os.environ.get("FAKE_ACP_CANCEL_SETTLES") == "1"
+                and pending_prompt_id is not None):
+            send({"jsonrpc": "2.0", "id": pending_prompt_id,
+                  "result": {"stopReason": "cancelled"}})
+            pending_prompt_id = None
+            pending_permission_id = None
+        if os.environ.get("FAKE_ACP_EXIT_ON_CANCEL") == "1":
+            sys.exit(0)
+    elif method == "session/prompt":
+        if os.environ.get("FAKE_ACP_PERMISSION_AFTER_CANCEL") == "1":
+            if pending_prompt_id is None:
+                pending_prompt_id = rid
+                delayed_permission = True
+                continue
+            if delayed_permission:
+                delayed_permission = False
+                pending_permission_id = "permission-1"
+                send({"jsonrpc": "2.0", "id": pending_permission_id,
+                      "method": "session/request_permission", "params": {
+                          "sessionId": session_id,
+                          "toolCall": {"toolCallId": "tool-1", "fields": {}},
+                          "options": [
+                              {"optionId": "once", "name": "Allow once", "kind": "allow_once"},
+                              {"optionId": "deny", "name": "Deny", "kind": "reject_once"}
+                          ]
+                      }})
+                continue
+        if os.environ.get("FAKE_ACP_REQUEST_PERMISSION") == "1":
+            pending_prompt_id = rid
+            pending_permission_id = "permission-1"
+            send({"jsonrpc": "2.0", "id": pending_permission_id,
+                  "method": "session/request_permission", "params": {
+                      "sessionId": session_id,
+                      "toolCall": {"toolCallId": "tool-1", "fields": {}},
+                      "options": [
+                          {"optionId": "once", "name": "Allow once", "kind": "allow_once"},
+                          {"optionId": "session", "name": "Allow session", "kind": "allow_always"},
+                          {"optionId": "deny", "name": "Deny", "kind": "reject_once"}
+                      ]
+                  }})
+            continue
+        time.sleep(int(os.environ.get("FAKE_ACP_DELAY_PROMPT_MS", "0")) / 1000)
+        fail_once = os.environ.get("FAKE_ACP_PROMPT_FAIL_ONCE") == "1"
+        if os.environ.get("FAKE_ACP_PROMPT_FAIL") == "1" or (fail_once and prompt_failures == 0):
+            prompt_failures += 1
+            send({"jsonrpc": "2.0", "id": rid,
+                  "error": {"code": -32000, "message": "fake prompt failure"}})
+        else:
+            send({"jsonrpc": "2.0", "id": rid,
+                  "result": {"stopReason": "end_turn"}})
+    elif rid is not None:
+        send({"jsonrpc": "2.0", "id": rid,
+              "error": {"code": -32601, "message": f"method not found: {method}"}})
+
+if os.environ.get("FAKE_ACP_IGNORE_EOF") == "1":
+    while True:
+        signal.pause()

crates/maestro-acp/tests/spawn.rs

@@ -0,0 +1,394 @@
+//! `maestro-acp` against the fake adapter in `tests/fake_acp_agent.py`, plus
+//! one ignored test against the real `claude-code-acp`.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use maestro_acp::schema::{ContentBlock, SessionUpdate};
+use maestro_acp::{AcpError, SpawnConfig, ADAPTER_BIN, INSTALL_COMMAND};
+use tempfile::TempDir;
+
+fn fake_agent() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fake_acp_agent.py")
+}
+
+/// A temp `bin/` holding the fake agent under the adapter's name, plus a
+/// log file the agent appends to. `PATH` for the spawn is just that dir.
+struct Fake {
+    dir: TempDir,
+}
+
+impl Fake {
+    fn new() -> Self {
+        let dir = TempDir::new().unwrap();
+        let bin = dir.path().join("bin");
+        std::fs::create_dir_all(&bin).unwrap();
+        std::fs::copy(fake_agent(), bin.join(ADAPTER_BIN)).unwrap();
+        Self { dir }
+    }
+
+    fn log_path(&self) -> PathBuf {
+        self.dir.path().join("agent.log")
+    }
+
+    fn log(&self) -> String {
+        std::fs::read_to_string(self.log_path()).unwrap_or_default()
+    }
+
+    /// The fake's `bin/` first, so it shadows any real adapter, then the
+    /// process `PATH` so the script's `python3` still resolves.
+    fn env(&self) -> HashMap<String, String> {
+        let path = format!(
+            "{}:{}",
+            self.dir.path().join("bin").display(),
+            std::env::var("PATH").unwrap_or_default()
+        );
+        HashMap::from([
+            ("PATH".to_string(), path),
+            (
+                "FAKE_ACP_LOG".to_string(),
+                self.log_path().to_string_lossy().into_owned(),
+            ),
+        ])
+    }
+
+    fn config(&self, cwd: &Path) -> SpawnConfig {
+        let mut config = SpawnConfig::new(cwd, self.env());
+        config.handshake_timeout = Duration::from_secs(10);
+        config
+    }
+
+    async fn wait_for_log(&self, needle: &str) {
+        let deadline = Instant::now() + Duration::from_secs(5);
+        while Instant::now() < deadline {
+            if self.log().contains(needle) {
+                return;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        panic!("log never contained {needle:?}:\n{}", self.log());
+    }
+
+    fn pid(&self) -> u32 {
+        self.log()
+            .lines()
+            .find_map(|line| line.strip_prefix("start pid="))
+            .and_then(|rest| rest.split(' ').next())
+            .and_then(|pid| pid.parse().ok())
+            .expect("pid in log")
+    }
+
+    async fn wait_for_exit(&self) {
+        let pid = self.pid();
+        let deadline = Instant::now() + Duration::from_secs(5);
+        while pid_alive(pid) && Instant::now() < deadline {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        assert!(!pid_alive(pid), "child {pid} still alive");
+    }
+}
+
+fn pid_alive(pid: u32) -> bool {
+    Path::new(&format!("/proc/{pid}")).exists()
+        && std::fs::read_to_string(format!("/proc/{pid}/stat"))
+            .map(|s| !s.contains(") Z "))
+            .unwrap_or(false)
+}
+
+#[tokio::test]
+async fn spawn_runs_adapter_in_cwd_with_env_and_restrictive_caps() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config
+        .env
+        .insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
+    config
+        .env
+        .insert("MAESTRO_SESSION_ID".into(), "sess-123".into());
+
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+    assert!(session.session_id().starts_with("fake-"));
+    assert!(pid_alive(session.pid()));
+
+    let log = fake.log();
+    let cwd_canon = cwd.path().canonicalize().unwrap();
+    assert!(
+        log.contains(&format!("cwd={}", cwd_canon.display())),
+        "child cwd missing from log:\n{log}"
+    );
+    assert!(log.contains("env MAESTRO_SESSION_ID=sess-123"), "{log}");
+    assert!(log.contains("recv initialize"), "{log}");
+    assert!(log.contains("recv session/new"), "{log}");
+    let caps = log
+        .lines()
+        .find_map(|l| l.strip_prefix("caps "))
+        .expect("caps line");
+    let caps: serde_json::Value = serde_json::from_str(caps).unwrap();
+    assert_eq!(caps["fs"]["readTextFile"], false);
+    assert_eq!(caps["fs"]["writeTextFile"], false);
+    assert_eq!(caps["terminal"], false);
+
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
+#[tokio::test]
+async fn missing_adapter_names_the_install_command() {
+    let empty = TempDir::new().unwrap();
+    let cwd = TempDir::new().unwrap();
+    let env = HashMap::from([(
+        "PATH".to_string(),
+        empty.path().to_string_lossy().into_owned(),
+    )]);
+    let err = maestro_acp::spawn(SpawnConfig::new(cwd.path(), env))
+        .await
+        .expect_err("no adapter on PATH");
+    assert!(matches!(err, AcpError::AdapterMissing));
+    let msg = err.to_string();
+    assert!(msg.contains(ADAPTER_BIN), "{msg}");
+    assert!(msg.contains(INSTALL_COMMAND), "{msg}");
+}
+
+#[tokio::test]
+async fn session_updates_reach_the_taken_receiver() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = maestro_acp::spawn(fake.config(cwd.path()))
+        .await
+        .expect("spawn");
+
+    let mut updates = session.take_updates().expect("first take");
+    assert!(session.take_updates().is_none(), "handed out once");
+    let first = tokio::time::timeout(Duration::from_secs(5), updates.recv())
+        .await
+        .expect("update within 5s")
+        .expect("channel open");
+    assert_eq!(first.session_id.0.as_ref(), session.session_id());
+    match first.update {
+        SessionUpdate::AgentMessageChunk(chunk) => match chunk.content {
+            ContentBlock::Text(t) => assert_eq!(t.text, "hello from fake"),
+            other => panic!("unexpected content {other:?}"),
+        },
+        other => panic!("unexpected update {other:?}"),
+    }
+
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
+#[tokio::test]
+async fn terminate_sends_cancel_then_sigterm() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = maestro_acp::spawn(fake.config(cwd.path()))
+        .await
+        .expect("spawn");
+    let pid = session.pid();
+
+    session
+        .terminate(Duration::from_millis(200), Duration::from_secs(2))
+        .await;
+    assert!(session.has_exited());
+    fake.wait_for_log("signal SIGTERM").await;
+
+    let log = fake.log();
+    let cancel = log.find("recv session/cancel").expect("cancel logged");
+    let term = log.find("signal SIGTERM").expect("SIGTERM logged");
+    assert!(cancel < term, "cancel must precede SIGTERM:\n{log}");
+    assert!(!pid_alive(pid), "child {pid} still alive");
+}
+
+#[tokio::test]
+async fn terminate_is_satisfied_by_an_exit_on_cancel() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config
+        .env
+        .insert("FAKE_ACP_EXIT_ON_CANCEL".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+
+    session
+        .terminate(Duration::from_secs(2), Duration::from_secs(2))
+        .await;
+    assert!(session.has_exited());
+    let log = fake.log();
+    assert!(log.contains("recv session/cancel"), "{log}");
+    assert!(!log.contains("signal SIGTERM"), "cancel was enough:\n{log}");
+}
+
+#[tokio::test]
+async fn handshake_error_fails_the_spawn_and_reaps_the_child() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config.env.insert("FAKE_ACP_INIT_FAIL".into(), "1".into());
+
+    let err = maestro_acp::spawn(config).await.expect_err("init fails");
+    assert!(matches!(err, AcpError::Handshake(_)), "{err}");
+    assert!(err.to_string().contains("fake init failure"), "{err}");
+    // Closing the connection gives the fake EOF on stdin; the SIGTERM that
+    // follows may find it already gone. Either way it must not survive.
+    let pid: u32 = fake
+        .log()
+        .lines()
+        .find_map(|l| l.strip_prefix("start pid="))
+        .and_then(|rest| rest.split(' ').next())
+        .and_then(|p| p.parse().ok())
+        .expect("pid in log");
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while pid_alive(pid) && Instant::now() < deadline {
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+    assert!(!pid_alive(pid), "child {pid} outlived the failed spawn");
+}
+
+#[tokio::test]
+async fn early_exit_is_observed_after_a_successful_handshake() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config
+        .env
+        .insert("FAKE_ACP_EXIT_AFTER_NEW".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+
+    let status = tokio::time::timeout(Duration::from_secs(5), session.wait())
+        .await
+        .expect("exit within 5s")
+        .expect("status");
+    assert!(status.success(), "{status}");
+    assert!(session.has_exited());
+}
+
+#[tokio::test]
+async fn child_exit_before_handshake_reports_exited_early() {
+    // A "adapter" that dies before answering anything.
+    let dir = TempDir::new().unwrap();
+    let bin = dir.path().join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    let script = bin.join(ADAPTER_BIN);
+    std::fs::write(&script, "#!/bin/sh\necho 'not logged in' >&2\nexit 3\n").unwrap();
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+    }
+    let cwd = TempDir::new().unwrap();
+    let env = HashMap::from([("PATH".to_string(), bin.to_string_lossy().into_owned())]);
+    let mut config = SpawnConfig::new(cwd.path(), env);
+    config.handshake_timeout = Duration::from_secs(10);
+
+    let err = maestro_acp::spawn(config).await.expect_err("child died");
+    match &err {
+        AcpError::ExitedEarly { status, stderr } => {
+            assert!(status.contains('3'), "{status}");
+            assert!(stderr.contains("not logged in"), "{stderr}");
+        }
+        other => panic!("unexpected {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn drop_terminates_and_reaps_the_child() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config.env.insert("FAKE_ACP_IGNORE_EOF".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+
+    drop(session);
+
+    fake.wait_for_log("signal SIGTERM").await;
+    fake.wait_for_exit().await;
+}
+
+fn chunk_text(n: &maestro_acp::schema::SessionNotification) -> String {
+    match &n.update {
+        SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
+            ContentBlock::Text(t) => t.text.clone(),
+            other => panic!("unexpected content {other:?}"),
+        },
+        other => panic!("unexpected update {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn load_session_resumes_the_stored_id_and_drops_the_replay() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    config.env.insert("FAKE_ACP_LOAD_REPLAY".into(), "3".into());
+
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+    assert_eq!(session.session_id(), "fake-old");
+    let log = fake.log();
+    assert!(
+        log.contains("recv session/load sessionId=fake-old"),
+        "{log}"
+    );
+    assert!(!log.contains("recv session/new"), "{log}");
+
+    // The three replayed chunks never reach the receiver: the event log
+    // already holds them. The first notification after the response does.
+    let mut updates = session.take_updates().expect("updates");
+    let first = tokio::time::timeout(Duration::from_secs(5), updates.recv())
+        .await
+        .expect("update within 5s")
+        .expect("channel open");
+    assert_eq!(chunk_text(&first), "hello after load");
+    // Nothing queued behind it either.
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert!(updates.try_recv().is_err(), "replay leaked through");
+
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
+#[tokio::test]
+async fn load_session_requires_the_load_capability() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    config.env.insert("FAKE_ACP_NO_LOAD".into(), "1".into());
+
+    let err = maestro_acp::spawn(config)
+        .await
+        .expect_err("no loadSession");
+    assert!(matches!(err, AcpError::Handshake(_)), "{err}");
+    assert!(err.to_string().contains("loadSession"), "{err}");
+    assert!(!fake.log().contains("recv session/load"), "{}", fake.log());
+}
+
+#[tokio::test]
+async fn load_session_error_fails_the_spawn() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    config.env.insert("FAKE_ACP_LOAD_FAIL".into(), "1".into());
+
+    let err = maestro_acp::spawn(config).await.expect_err("load fails");
+    assert!(matches!(err, AcpError::Handshake(_)), "{err}");
+    assert!(err.to_string().contains("fake load failure"), "{err}");
+}
+
+/// End to end against the installed `claude-code-acp`. Needs Claude auth,
+/// takes seconds, so it is opt-in: `cargo test -p maestro-acp -- --ignored`.
+#[tokio::test]
+#[ignore]
+async fn real_adapter_handshake() {
+    let cwd = TempDir::new().unwrap();
+    let session = maestro_acp::spawn(SpawnConfig::new(cwd.path(), HashMap::new()))
+        .await
+        .expect("real claude-code-acp handshake");
+    assert!(!session.session_id().is_empty());
+    assert!(pid_alive(session.pid()));
+    session
+        .terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+        .await;
+    assert!(session.has_exited());
+}

crates/maestro-cli/src/dispatch.rs

@@ -96,20 +96,32 @@ pub async fn dispatch(
 }
 
 /// `maestro hooks install` (#106): write the shipped hook script under the
-/// user's data dir and register it in their Claude Code settings. Idempotent
-/// and foreign-hook-preserving — the guarantees live in [`maestro_hooks`].
+/// user's data dir and register it in every agent's hook file. Idempotent and
+/// foreign-hook-preserving — the guarantees live in [`maestro_hooks`]. One
+/// agent failing is reported and does not stop the others.
 #[allow(clippy::result_large_err)]
 fn run_hooks_install() -> Result<(), CliError> {
     let home = dirs::home_dir().ok_or(CliError::NoHome)?;
-    let changed = maestro_hooks::install_for_home(&home)?;
-    if changed {
-        println!(
-            "installed claude-code activity hook: {} → {}",
-            maestro_hooks::script_path(&home).display(),
-            maestro_hooks::settings_path(&home).display()
-        );
-    } else {
-        println!("claude-code activity hook already up to date");
+    let script = maestro_hooks::script_path(&home);
+    for (target, result) in maestro_hooks::install_for_home(&home) {
+        let agent = target.label();
+        let settings = target.settings_path(&home);
+        match result {
+            Ok(true) => {
+                println!(
+                    "installed {agent} activity hook: {} → {}",
+                    script.display(),
+                    settings.display()
+                );
+                if target == maestro_hooks::Target::Codex {
+                    // Codex will not run a hook it has not been told to
+                    // trust, and that approval is the operator's to give.
+                    println!("  codex will ask you to trust this hook the next time it starts");
+                }
+            }
+            Ok(false) => println!("{agent} activity hook already up to date"),
+            Err(e) => eprintln!("{agent} activity hook not installed: {e}"),
+        }
     }
     Ok(())
 }

crates/maestro-cli/src/sessions.rs

@@ -51,6 +51,7 @@ pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session
     };
 
     let body = CreateSessionRequest {
+        view: Default::default(),
         cwd: args.cwd.clone(),
         command: args.command.clone(),
         env,
@@ -236,6 +237,7 @@ mod tests {
 
     fn session(cwd: &str, command: &str, id: u128) -> Session {
         Session {
+            view: Default::default(),
             id: Uuid::from_u128(id),
             cwd: PathBuf::from(cwd),
             command: command.into(),
@@ -252,6 +254,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 

crates/maestro-cli/tests/against_mock_daemon.rs

@@ -91,6 +91,7 @@ async fn spawn_round_trips_through_the_daemon() {
     let created = mock
         .client()
         .create_session(&maestro_protocol::CreateSessionRequest {
+            view: Default::default(),
             cwd: "/home/mock".into(),
             command: "bash".into(),
             env: Default::default(),

crates/maestro-daemon/Cargo.toml

@@ -28,6 +28,7 @@ dirs.workspace = true
 futures-util.workspace = true
 include_dir = { workspace = true, optional = true }
 libc.workspace = true
+maestro-acp.workspace = true
 mime_guess = { workspace = true, optional = true }
 maestro-config.workspace = true
 maestro-hooks = { workspace = true, default-features = false }
@@ -42,6 +43,7 @@ tracing-subscriber.workspace = true
 uuid.workspace = true
 
 [dev-dependencies]
+libc.workspace = true
 reqwest.workspace = true
 tokio-tungstenite.workspace = true
 urlencoding = "2"

crates/maestro-daemon/src/activity.rs

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

crates/maestro-daemon/src/cli.rs

@@ -51,17 +51,23 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     // First-start hook auto-install (#106). Best-effort, before serving: a
     // session spawned right away should already carry the hook.
     if config.hooks_auto_install {
-        match crate::hooks::auto_install(&config.home_dir) {
-            crate::hooks::AutoInstallOutcome::Installed => {
-                tracing::info!("installed claude-code activity hook (#106)");
+        for (target, outcome) in crate::hooks::auto_install(&config.home_dir) {
+            let agent = target.label();
+            match outcome {
+                crate::hooks::AutoInstallOutcome::Installed => {
+                    tracing::info!(agent, "installed activity hook (#106)");
+                }
+                crate::hooks::AutoInstallOutcome::Upgraded => {
+                    tracing::info!(agent, "updated activity hook to this build (#106)");
+                }
+                crate::hooks::AutoInstallOutcome::Failed => {
+                    tracing::warn!(
+                        agent,
+                        "hooks auto-install failed; run `maestro hooks install` manually"
+                    );
+                }
+                _ => {}
             }
-            crate::hooks::AutoInstallOutcome::Upgraded => {
-                tracing::info!("updated claude-code activity hook to this build (#106)");
-            }
-            crate::hooks::AutoInstallOutcome::Failed => {
-                tracing::warn!("hooks auto-install failed; run `maestro hooks install` manually");
-            }
-            _ => {}
         }
     }
     // No worktree dir to pre-create: without an override the worktrees live
@@ -100,7 +106,7 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     projects.start_background_refresh();
 
     let router = local_api::router(local_api::state_for(
-        manager,
+        manager.clone(),
         config.hostname.clone(),
         config.home_dir.clone(),
         config.spawn_presets.clone(),
@@ -112,9 +118,22 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     let bound = listener.local_addr()?;
     tracing::info!(addr = %bound, "API listening");
 
-    let shutdown = async {
-        let _ = tokio::signal::ctrl_c().await;
-        tracing::info!("ctrl-c received — shutting down");
+    // Ctrl-C at a terminal or SIGTERM from systemd: either one is a
+    // shutdown, and both must reach the adapter children below (#134). The
+    // unit's `KillMode=process` signals only the daemon, so nothing else
+    // would end them.
+    let shutdown_manager = manager.clone();
+    let shutdown = async move {
+        let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .expect("install SIGTERM handler");
+        tokio::select! {
+            _ = tokio::signal::ctrl_c() => tracing::info!("ctrl-c received — shutting down"),
+            _ = sigterm.recv() => tracing::info!("SIGTERM received — shutting down"),
+        }
+        // Axum waits for upgraded WebSockets to drain. Structured children
+        // must be settled before that wait, while the signal path still owns
+        // the shutdown order (#179).
+        shutdown_manager.shutdown().await;
     };
 
     axum::serve(listener, router)

crates/maestro-daemon/src/hooks.rs

@@ -1,37 +1,53 @@
 //! First-start hook auto-install (#106).
 //!
-//! The daemon runs [`auto_install`] once at startup: unless the user's
-//! `~/.claude/settings.json` already carries exactly what this build ships
-//! (and `[hooks].auto_install` hasn't opted out — checked by the caller), the
-//! same installer `maestro hooks install` uses writes it. That covers
-//! upgrades as well as first starts: an install from a maestro that had fewer
-//! events — #131 added `UserPromptSubmit` to a hook #106 had already put in
-//! everyone's settings — is rewritten rather than left half-wired. Best-effort:
-//! a failure is warned about and never blocks startup. The same global hook
-//! serves every Claude Code session on the machine, so nothing here targets
-//! repositories or worktrees.
+//! The daemon runs [`auto_install`] once at startup: for every agent maestro
+//! knows how to hook ([`maestro_hooks::Target`]), unless that agent's hook
+//! file already carries exactly what this build ships (and `[hooks]
+//! .auto_install` hasn't opted out — checked by the caller), the same
+//! installer `maestro hooks install` uses writes it. That covers upgrades as
+//! well as first starts: an install from a maestro that had fewer events —
+//! #131 added `UserPromptSubmit` to a hook #106 had already put in everyone's
+//! settings — is rewritten rather than left half-wired. Best-effort: a
+//! failure is warned about and never blocks startup, and one target failing
+//! does not stop the others. The same global hook serves every session on the
+//! machine, so nothing here targets repositories or worktrees.
 
 use std::path::Path;
 
-/// Install the Claude Code activity hook for `home_dir` unless the current
-/// one is already there or the home dir is unresolvable (`""`). Returns what
-/// happened; an older install being brought up to date is
-/// [`AutoInstallOutcome::Upgraded`], so the log can say so.
-pub fn auto_install(home_dir: &str) -> AutoInstallOutcome {
+use maestro_hooks::Target;
+
+/// Install the activity hook for every [`Target`] under `home_dir`, skipping
+/// any whose install is already current. Returns what happened per target —
+/// an older install being brought up to date is
+/// [`AutoInstallOutcome::Upgraded`], so the log can say so. An unresolvable
+/// home dir (`""`) reports every target as [`AutoInstallOutcome::Skipped`].
+pub fn auto_install(home_dir: &str) -> Vec<(Target, AutoInstallOutcome)> {
+    Target::ALL
+        .iter()
+        .map(|&target| (target, auto_install_target(target, home_dir)))
+        .collect()
+}
+
+fn auto_install_target(target: Target, home_dir: &str) -> AutoInstallOutcome {
     if home_dir.is_empty() {
         return AutoInstallOutcome::Skipped;
     }
-    let settings = maestro_hooks::settings_path(Path::new(home_dir));
-    let script = maestro_hooks::script_path(Path::new(home_dir));
-    if maestro_hooks::is_current(&settings, &script) {
+    let home = Path::new(home_dir);
+    let settings = target.settings_path(home);
+    let script = maestro_hooks::script_path(home);
+    if maestro_hooks::is_current(target, &settings, &script) {
         return AutoInstallOutcome::AlreadyPresent;
     }
     let stale = maestro_hooks::is_installed(&settings);
-    match maestro_hooks::install_for_home(Path::new(home_dir)) {
+    match maestro_hooks::install_target(target, home) {
         Ok(_) if stale => AutoInstallOutcome::Upgraded,
         Ok(_) => AutoInstallOutcome::Installed,
         Err(e) => {
-            tracing::warn!(error = %e, "hooks auto-install failed (non-fatal)");
+            tracing::warn!(
+                target = target.label(),
+                error = %e,
+                "hooks auto-install failed (non-fatal)"
+            );
             AutoInstallOutcome::Failed
         }
     }
@@ -52,15 +68,50 @@ pub enum AutoInstallOutcome {
 mod tests {
     use super::*;
 
+    /// The outcome recorded for one target.
+    fn outcome(outcomes: &[(Target, AutoInstallOutcome)], target: Target) -> AutoInstallOutcome {
+        outcomes
+            .iter()
+            .find(|(t, _)| *t == target)
+            .map(|(_, o)| *o)
+            .expect("every target is reported")
+    }
+
     /// Everything happens under a temp `$HOME`; the developer's own
-    /// `~/.claude/settings.json` is never read or written.
+    /// `~/.claude/settings.json` and `~/.codex/hooks.json` are never read or
+    /// written.
     #[test]
     fn installs_when_settings_carry_no_maestro_hook() {
         let dir = tempfile::tempdir().unwrap();
-        let outcome = auto_install(dir.path().to_str().unwrap());
-        assert_eq!(outcome, AutoInstallOutcome::Installed);
-        let settings = dir.path().join(".claude/settings.json");
-        assert!(maestro_hooks::is_installed(&settings));
+        let outcomes = auto_install(dir.path().to_str().unwrap());
+        for target in Target::ALL {
+            assert_eq!(
+                outcome(&outcomes, target),
+                AutoInstallOutcome::Installed,
+                "{}",
+                target.label()
+            );
+            assert!(maestro_hooks::is_installed(
+                &target.settings_path(dir.path())
+            ));
+        }
+    }
+
+    /// Every agent maestro knows about is hooked, not just Claude Code: a
+    /// codex session reports activity and its first prompt the same way.
+    #[test]
+    fn codex_gets_its_own_hook_file() {
+        let dir = tempfile::tempdir().unwrap();
+        auto_install(dir.path().to_str().unwrap());
+        let hooks = dir.path().join(".codex/hooks.json");
+        let root: serde_json::Value =
+            serde_json::from_str(&std::fs::read_to_string(&hooks).unwrap()).unwrap();
+        let events = root["hooks"].as_object().unwrap();
+        assert!(events.contains_key("PermissionRequest"));
+        assert!(
+            !events.contains_key("Notification"),
+            "codex has no Notification"
+        );
     }
 
     #[test]
@@ -69,14 +120,22 @@ mod tests {
         let home = dir.path().to_str().unwrap();
         auto_install(home);
         // A current install is left exactly as it is.
-        let settings = dir.path().join(".claude/settings.json");
-        let before = std::fs::read_to_string(&settings).unwrap();
-        assert_eq!(auto_install(home), AutoInstallOutcome::AlreadyPresent);
-        assert_eq!(
-            before,
-            std::fs::read_to_string(&settings).unwrap(),
-            "already-installed settings must not be rewritten"
-        );
+        let before: Vec<String> = Target::ALL
+            .iter()
+            .map(|t| std::fs::read_to_string(t.settings_path(dir.path())).unwrap())
+            .collect();
+        let outcomes = auto_install(home);
+        for (i, target) in Target::ALL.iter().enumerate() {
+            assert_eq!(
+                outcome(&outcomes, *target),
+                AutoInstallOutcome::AlreadyPresent
+            );
+            assert_eq!(
+                before[i],
+                std::fs::read_to_string(target.settings_path(dir.path())).unwrap(),
+                "already-installed settings must not be rewritten"
+            );
+        }
     }
 
     /// An install from an older maestro — present, but missing an event this
@@ -87,7 +146,7 @@ mod tests {
         let dir = tempfile::tempdir().unwrap();
         let home = dir.path().to_str().unwrap();
         auto_install(home);
-        let settings = dir.path().join(".claude/settings.json");
+        let settings = Target::ClaudeCode.settings_path(dir.path());
         let script = maestro_hooks::script_path(dir.path());
 
         let mut root: serde_json::Value =
@@ -96,12 +155,23 @@ mod tests {
         std::fs::write(&settings, serde_json::to_string_pretty(&root).unwrap()).unwrap();
         std::fs::write(&script, "#!/bin/sh\nexit 0\n").unwrap();
 
-        assert_eq!(auto_install(home), AutoInstallOutcome::Upgraded);
-        assert!(maestro_hooks::is_current(&settings, &script));
+        let outcomes = auto_install(home);
+        assert_eq!(
+            outcome(&outcomes, Target::ClaudeCode),
+            AutoInstallOutcome::Upgraded
+        );
+        assert!(maestro_hooks::is_current(
+            Target::ClaudeCode,
+            &settings,
+            &script
+        ));
     }
 
     #[test]
     fn unresolvable_home_is_skipped() {
-        assert_eq!(auto_install(""), AutoInstallOutcome::Skipped);
+        let outcomes = auto_install("");
+        for target in Target::ALL {
+            assert_eq!(outcome(&outcomes, target), AutoInstallOutcome::Skipped);
+        }
     }
 }

crates/maestro-daemon/src/lib.rs

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

crates/maestro-daemon/src/local_api.rs

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

crates/maestro-daemon/src/projection.rs

@@ -0,0 +1,860 @@
+//! Fold persisted ACP notifications into client-neutral transcript and state.
+
+use std::collections::{HashMap, HashSet};
+
+use maestro_acp::schema::{ContentChunk, SessionNotification, SessionUpdate, ToolCall};
+use maestro_protocol::{
+    ActivityState, ReducedState, TranscriptDelta, TranscriptRow, TranscriptRowKind,
+    TranscriptSnapshot,
+};
+use serde_json::Value;
+
+/// A transcript delta paired with the state after the same ACP notification.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProjectionUpdate {
+    pub transcript: Option<TranscriptDelta>,
+    pub state: ReducedState,
+}
+
+/// A prompt lifecycle transition supplied by the prompt transport (#138).
+///
+/// ACP notifications do not delimit turns, so replaying them must not infer
+/// an in-flight prompt from an agent chunk.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TurnLifecycle {
+    Begin,
+    Finish,
+    Cancel,
+    Failure,
+}
+
+/// The one-pass ACP fold used for both persisted replay and live events.
+#[derive(Debug, Default)]
+pub struct Projection {
+    rows: Vec<TranscriptRow>,
+    row_index: HashMap<String, usize>,
+    tools: HashMap<String, ToolCall>,
+    pending_tool_updates: HashMap<String, Vec<maestro_acp::schema::ToolCallUpdateFields>>,
+    state: ReducedState,
+    active_turn: Option<u64>,
+    turn_failed: bool,
+    next_turn: u64,
+    turn_tool_calls: HashSet<String>,
+}
+
+impl Projection {
+    /// Fold one durable event and return its client-visible changes.
+    pub fn apply(&mut self, seq: u64, notification: &SessionNotification) -> ProjectionUpdate {
+        let transcript = match &notification.update {
+            SessionUpdate::UserMessageChunk(chunk) => {
+                self.content(seq, chunk, TranscriptRowKind::User, "user")
+            }
+            SessionUpdate::AgentMessageChunk(chunk) => {
+                self.agent_text();
+                self.content(seq, chunk, TranscriptRowKind::AgentText, "agent")
+            }
+            SessionUpdate::AgentThoughtChunk(chunk) => {
+                self.agent_thought();
+                self.content(seq, chunk, TranscriptRowKind::AgentThought, "thought")
+            }
+            SessionUpdate::ToolCall(tool) => self.tool_call(tool),
+            SessionUpdate::ToolCallUpdate(update) => self.tool_update(update),
+            SessionUpdate::Plan(plan) => {
+                let data = to_value(plan);
+                self.state.plan = Some(data.clone());
+                Some(self.replace("plan".into(), TranscriptRowKind::Plan, data))
+            }
+            SessionUpdate::UsageUpdate(usage) => {
+                let value = to_value(usage);
+                self.state.usage = Some(value.clone());
+                self.state.context = Some(value);
+                None
+            }
+            SessionUpdate::CurrentModeUpdate(mode) => {
+                self.state.mode = Some(mode.current_mode_id.to_string());
+                None
+            }
+            SessionUpdate::ConfigOptionUpdate(options) => {
+                let value = to_value(options);
+                self.state.model = model_from_options(&value).or_else(|| self.state.model.clone());
+                None
+            }
+            // ACP deliberately adds notification variants over time. Known but
+            // non-transcript updates become a generic notice instead of being
+            // dropped or forcing clients to understand ACP's enum.
+            _ => Some(self.append(
+                format!("notice:{seq}"),
+                TranscriptRowKind::Notice,
+                to_value(&notification.update),
+            )),
+        };
+        ProjectionUpdate {
+            transcript,
+            state: self.state.clone(),
+        }
+    }
+
+    /// The current transcript at `cursor`.
+    pub fn snapshot(&self, cursor: u64) -> TranscriptSnapshot {
+        TranscriptSnapshot {
+            cursor,
+            rows: self.rows.clone(),
+        }
+    }
+
+    /// The state folded over every event seen so far.
+    pub fn state(&self) -> ReducedState {
+        self.state.clone()
+    }
+
+    pub fn turn_active(&self) -> bool {
+        self.active_turn.is_some()
+    }
+
+    /// Sidebar activity derived from the live turn projection.
+    pub fn activity(&self) -> ActivityState {
+        crate::activity::decide_structured(
+            self.active_turn.is_some(),
+            self.state.pending_approval.is_some(),
+            self.turn_failed,
+        )
+    }
+
+    /// Start a prompt turn and return its monotonically increasing token.
+    pub fn begin_turn(&mut self) -> (u64, ProjectionUpdate) {
+        self.next_turn += 1;
+        let turn = self.next_turn;
+        self.active_turn = Some(turn);
+        self.turn_failed = false;
+        self.state.turn.responding = true;
+        self.state.turn.thinking = true;
+        self.turn_tool_calls.clear();
+        self.state.turn.active_tool_calls.clear();
+        (
+            turn,
+            ProjectionUpdate {
+                transcript: None,
+                state: self.state(),
+            },
+        )
+    }
+
+    /// End `turn` only when it remains the active prompt turn.
+    pub fn turn_lifecycle(
+        &mut self,
+        lifecycle: TurnLifecycle,
+        turn: u64,
+    ) -> Option<ProjectionUpdate> {
+        if !matches!(
+            lifecycle,
+            TurnLifecycle::Finish | TurnLifecycle::Cancel | TurnLifecycle::Failure
+        ) || self.active_turn != Some(turn)
+        {
+            return None;
+        }
+        self.active_turn = None;
+        self.turn_failed = lifecycle == TurnLifecycle::Failure;
+        self.state.turn.responding = false;
+        self.state.turn.thinking = false;
+        self.turn_tool_calls.clear();
+        self.state.turn.active_tool_calls.clear();
+        Some(ProjectionUpdate {
+            transcript: None,
+            state: self.state(),
+        })
+    }
+
+    pub fn active_turn(&self) -> Option<u64> {
+        self.active_turn
+    }
+
+    /// Add a daemon-originated permission row. The nonce belongs only in the
+    /// reduced state, which is the client control surface, never in ACP data.
+    pub fn request_approval(&mut self, nonce: String, request: Value) -> ProjectionUpdate {
+        let row = self.append(
+            format!("approval:{}", uuid::Uuid::new_v4()),
+            TranscriptRowKind::Approval,
+            request.clone(),
+        );
+        self.state.pending_approval = Some(serde_json::json!({
+            "nonce": nonce,
+            "request": request,
+        }));
+        ProjectionUpdate {
+            transcript: Some(row),
+            state: self.state(),
+        }
+    }
+
+    pub fn restore_approval(&mut self, row: TranscriptRow) -> ProjectionUpdate {
+        let transcript = if !self.row_index.contains_key(&row.id) {
+            self.row_index.insert(row.id.clone(), self.rows.len());
+            self.rows.push(row.clone());
+            Some(TranscriptDelta::Append { row })
+        } else {
+            None
+        };
+        ProjectionUpdate {
+            transcript,
+            state: self.state(),
+        }
+    }
+
+    /// Clear an approval only when it is still the one the client answered.
+    pub fn resolve_approval(&mut self, nonce: &str) -> Option<ProjectionUpdate> {
+        let pending = self.state.pending_approval.as_ref()?;
+        if pending.get("nonce").and_then(Value::as_str) != Some(nonce) {
+            return None;
+        }
+        self.state.pending_approval = None;
+        Some(ProjectionUpdate {
+            transcript: None,
+            state: self.state(),
+        })
+    }
+
+    /// Terminal turn paths must not leave a recovered snapshot permanently
+    /// blocked on an ACP request whose transport no longer exists.
+    pub fn clear_approval(&mut self) -> Option<ProjectionUpdate> {
+        self.state.pending_approval.take()?;
+        Some(ProjectionUpdate {
+            transcript: None,
+            state: self.state(),
+        })
+    }
+
+    /// 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,
+        chunk: &ContentChunk,
+        kind: TranscriptRowKind,
+        prefix: &str,
+    ) -> Option<TranscriptDelta> {
+        let id = chunk
+            .message_id
+            .as_ref()
+            .map(|id| format!("{prefix}:{id}"))
+            .unwrap_or_else(|| format!("{prefix}:{seq}"));
+        let data = to_value(chunk);
+        if let Some(index) = self.row_index.get(&id).copied() {
+            let row = &mut self.rows[index];
+            append_text(&mut row.data, &data);
+            return Some(TranscriptDelta::Patch { row: row.clone() });
+        }
+        Some(self.append(id, kind, data))
+    }
+
+    fn tool_call(&mut self, tool: &ToolCall) -> Option<TranscriptDelta> {
+        let id = format!("tool:{}", tool.tool_call_id);
+        let tool_id = tool.tool_call_id.to_string();
+        let mut canonical = tool.clone();
+        if let Some(updates) = self.pending_tool_updates.get(&tool_id) {
+            for fields in updates {
+                canonical.update(fields.clone());
+            }
+        }
+        let kind = if tool_has_diff(tool) {
+            TranscriptRowKind::ToolDiff
+        } else {
+            TranscriptRowKind::ToolCall
+        };
+        self.tools.insert(tool_id, canonical.clone());
+        self.track_tool_call(&canonical);
+        Some(self.replace(
+            id,
+            if tool_has_diff(&canonical) {
+                TranscriptRowKind::ToolDiff
+            } else {
+                kind
+            },
+            to_value(&canonical),
+        ))
+    }
+
+    fn tool_update(
+        &mut self,
+        update: &maestro_acp::schema::ToolCallUpdate,
+    ) -> Option<TranscriptDelta> {
+        let tool_id = update.tool_call_id.to_string();
+        let Some(tool) = self.tools.get_mut(&tool_id) else {
+            self.pending_tool_updates
+                .entry(tool_id)
+                .or_default()
+                .push(update.fields.clone());
+            return None;
+        };
+        tool.update(update.fields.clone());
+        self.pending_tool_updates
+            .entry(tool_id.clone())
+            .or_default()
+            .push(update.fields.clone());
+        let row_id = format!("tool:{tool_id}");
+        let index = *self
+            .row_index
+            .get(&row_id)
+            .expect("a tracked tool call always has a transcript row");
+        let row = {
+            let row = &mut self.rows[index];
+            row.kind = if tool_has_diff(tool) {
+                TranscriptRowKind::ToolDiff
+            } else {
+                TranscriptRowKind::ToolCall
+            };
+            row.data = to_value(tool);
+            row.clone()
+        };
+        self.sync_active_tool(&tool_id);
+        Some(TranscriptDelta::Patch { row })
+    }
+
+    fn append(&mut self, id: String, kind: TranscriptRowKind, data: Value) -> TranscriptDelta {
+        let row = TranscriptRow { id, kind, data };
+        self.row_index.insert(row.id.clone(), self.rows.len());
+        self.rows.push(row.clone());
+        TranscriptDelta::Append { row }
+    }
+
+    fn replace(&mut self, id: String, kind: TranscriptRowKind, data: Value) -> TranscriptDelta {
+        let Some(index) = self.row_index.get(&id).copied() else {
+            return self.append(id, kind, data);
+        };
+        let row = &mut self.rows[index];
+        row.kind = kind;
+        row.data = data;
+        TranscriptDelta::Patch { row: row.clone() }
+    }
+
+    fn agent_text(&mut self) {
+        if self.turn_active() {
+            self.state.turn.responding = true;
+            self.state.turn.thinking = false;
+        }
+    }
+
+    fn agent_thought(&mut self) {
+        if self.turn_active() {
+            self.state.turn.responding = true;
+            self.state.turn.thinking = true;
+        }
+    }
+
+    fn track_tool_call(&mut self, tool: &ToolCall) {
+        if self.turn_active() {
+            self.turn_tool_calls.insert(tool.tool_call_id.to_string());
+            self.sync_active_tool(&tool.tool_call_id.to_string());
+        }
+    }
+
+    fn sync_active_tool(&mut self, tool_id: &str) {
+        if !self.turn_active() || !self.turn_tool_calls.contains(tool_id) {
+            return;
+        }
+        let active = self.tools.get(tool_id).is_some_and(|tool| {
+            matches!(
+                tool.status,
+                maestro_acp::schema::ToolCallStatus::Pending
+                    | maestro_acp::schema::ToolCallStatus::InProgress
+            )
+        });
+        let active_tool_calls = &mut self.state.turn.active_tool_calls;
+        if active {
+            if !active_tool_calls.iter().any(|id| id == tool_id) {
+                active_tool_calls.push(tool_id.to_owned());
+                active_tool_calls.sort();
+            }
+        } else {
+            active_tool_calls.retain(|id| id != tool_id);
+        }
+    }
+}
+
+fn to_value(value: &impl serde::Serialize) -> Value {
+    serde_json::to_value(value).expect("ACP schema values serialize")
+}
+
+fn tool_has_diff(tool: &ToolCall) -> bool {
+    tool.content
+        .iter()
+        .any(|content| matches!(content, maestro_acp::schema::ToolCallContent::Diff(_)))
+}
+
+fn append_text(existing: &mut Value, next: &Value) {
+    let Some(existing_text) = existing.pointer_mut("/content/text") else {
+        *existing = next.clone();
+        return;
+    };
+    let Some(next_text) = next.pointer("/content/text").and_then(Value::as_str) else {
+        *existing = next.clone();
+        return;
+    };
+    if let Some(text) = existing_text.as_str() {
+        *existing_text = Value::String(format!("{text}{next_text}"));
+    } else {
+        *existing = next.clone();
+    }
+}
+
+fn model_from_options(value: &Value) -> Option<String> {
+    value
+        .get("configOptions")?
+        .as_array()?
+        .iter()
+        .find(|option| {
+            option.get("id").and_then(Value::as_str) == Some("model")
+                || option.get("category").and_then(Value::as_str) == Some("model")
+        })?
+        .get("currentValue")?
+        .as_str()
+        .map(str::to_owned)
+}
+
+#[cfg(test)]
+mod tests {
+    use maestro_acp::schema::SessionNotification;
+    use maestro_protocol::{TranscriptDelta, TranscriptRowKind};
+
+    use super::{Projection, TurnLifecycle};
+
+    fn event(value: serde_json::Value) -> SessionNotification {
+        serde_json::from_value(serde_json::json!({
+            "sessionId": "acp-1",
+            "update": value,
+        }))
+        .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();
+        let events = [
+            event(
+                serde_json::json!({"sessionUpdate":"user_message_chunk","content":{"type":"text","text":"hi"}}),
+            ),
+            event(
+                serde_json::json!({"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"hello"}}),
+            ),
+            event(
+                serde_json::json!({"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"think"}}),
+            ),
+            event(
+                serde_json::json!({"sessionUpdate":"tool_call","toolCallId":"read-1","title":"Read","kind":"read"}),
+            ),
+            event(
+                serde_json::json!({"sessionUpdate":"tool_call","toolCallId":"edit-1","title":"Edit","content":[{"type":"diff","path":"x.rs","oldText":"a","newText":"b"}]}),
+            ),
+            event(serde_json::json!({"sessionUpdate":"plan","entries":[]})),
+            event(
+                serde_json::json!({"sessionUpdate":"available_commands_update","availableCommands":[]}),
+            ),
+        ];
+
+        let kinds: Vec<_> = events
+            .iter()
+            .enumerate()
+            .filter_map(|(i, event)| projection.apply((i + 1) as u64, event).transcript)
+            .map(|delta| match delta {
+                TranscriptDelta::Append { row } => row.kind,
+                other => panic!("expected append, got {other:?}"),
+            })
+            .collect();
+        assert_eq!(
+            kinds,
+            [
+                TranscriptRowKind::User,
+                TranscriptRowKind::AgentText,
+                TranscriptRowKind::AgentThought,
+                TranscriptRowKind::ToolCall,
+                TranscriptRowKind::ToolDiff,
+                TranscriptRowKind::Plan,
+                TranscriptRowKind::Notice,
+            ]
+        );
+    }
+
+    #[test]
+    fn tool_update_patches_the_original_stable_row() {
+        let mut projection = Projection::default();
+        let first = projection.apply(
+            4,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":"bash-7", "title":"Run"
+            })),
+        );
+        let updated = projection.apply(
+            5,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call_update", "toolCallId":"bash-7", "status":"completed"
+            })),
+        );
+        let id = match first.transcript.unwrap() {
+            TranscriptDelta::Append { row } => row.id,
+            other => panic!("expected append, got {other:?}"),
+        };
+        match updated.transcript.unwrap() {
+            TranscriptDelta::Patch { row } => {
+                assert_eq!(row.id, id);
+                assert_eq!(row.data["status"], "completed");
+            }
+            other => panic!("expected patch, got {other:?}"),
+        }
+        assert_eq!(projection.snapshot(5).rows.len(), 1);
+    }
+
+    #[test]
+    fn duplicate_tool_calls_patch_one_stable_row() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":"bash-7", "title":"Run"
+            })),
+        );
+        let duplicate = projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":"bash-7", "title":"Run again"
+            })),
+        );
+        match duplicate.transcript.unwrap() {
+            TranscriptDelta::Patch { row } => {
+                assert_eq!(row.id, "tool:bash-7");
+                assert_eq!(row.data["title"], "Run again");
+            }
+            other => panic!("expected patch, got {other:?}"),
+        }
+        assert_eq!(projection.snapshot(2).rows.len(), 1);
+    }
+
+    #[test]
+    fn early_tool_update_is_reconciled_when_the_call_arrives() {
+        let mut projection = Projection::default();
+        let early = projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call_update", "toolCallId":"bash-7", "status":"completed"
+            })),
+        );
+        assert_eq!(early.transcript, None);
+        let call = projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":"bash-7", "title":"Run", "status":"pending"
+            })),
+        );
+        match call.transcript.unwrap() {
+            TranscriptDelta::Append { row } => {
+                assert_eq!(row.id, "tool:bash-7");
+                assert_eq!(row.data["status"], "completed");
+            }
+            other => panic!("expected append, got {other:?}"),
+        }
+        assert!(projection.state().turn.active_tool_calls.is_empty());
+    }
+
+    #[test]
+    fn unknown_tool_stays_generic_and_keeps_its_raw_name() {
+        let mut projection = Projection::default();
+        let update = projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":"custom-1", "title":"Custom",
+                "name":"vendor.custom", "kind":"future_kind"
+            })),
+        );
+        match update.transcript.unwrap() {
+            TranscriptDelta::Append { row } => {
+                assert_eq!(row.kind, TranscriptRowKind::ToolCall);
+                assert_eq!(row.data["name"], "vendor.custom");
+            }
+            other => panic!("expected generic tool row, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn folds_usage_mode_model_and_plan_into_whole_state() {
+        let mut projection = Projection::default();
+        for (seq, update) in [
+            serde_json::json!({"sessionUpdate":"usage_update","used":12,"size":200}),
+            serde_json::json!({"sessionUpdate":"current_mode_update","currentModeId":"plan"}),
+            serde_json::json!({"sessionUpdate":"config_option_update","configOptions":[{"id":"model","name":"Model","category":"model","type":"select","currentValue":"opus","options":[]}]}),
+            serde_json::json!({"sessionUpdate":"plan","entries":[]}),
+        ]
+        .into_iter()
+        .enumerate()
+        {
+            projection.apply((seq + 1) as u64, &event(update));
+        }
+        let state = projection.state();
+        assert_eq!(state.usage.as_ref().unwrap()["used"], 12);
+        assert_eq!(state.context.as_ref().unwrap()["size"], 200);
+        assert_eq!(state.mode.as_deref(), Some("plan"));
+        assert_eq!(state.model.as_deref(), Some("opus"));
+        assert_eq!(
+            state.plan.as_ref().unwrap()["entries"],
+            serde_json::json!([])
+        );
+    }
+
+    #[test]
+    fn plans_replace_one_stable_row_and_state() {
+        let mut projection = Projection::default();
+        let first = projection.apply(
+            1,
+            &event(serde_json::json!({"sessionUpdate":"plan","entries":[{"content":"first","priority":"high","status":"pending"}]})),
+        );
+        assert!(matches!(
+            first.transcript,
+            Some(TranscriptDelta::Append { .. })
+        ));
+        let replacement = projection.apply(
+            2,
+            &event(serde_json::json!({"sessionUpdate":"plan","entries":[{"content":"second","priority":"high","status":"completed"}]})),
+        );
+        match replacement.transcript.unwrap() {
+            TranscriptDelta::Patch { row } => {
+                assert_eq!(row.id, "plan");
+                assert_eq!(row.data["entries"][0]["content"], "second");
+            }
+            other => panic!("expected patch, got {other:?}"),
+        }
+        assert_eq!(projection.snapshot(2).rows.len(), 1);
+        assert_eq!(
+            projection.state().plan.unwrap()["entries"][0]["content"],
+            "second"
+        );
+    }
+
+    #[test]
+    fn turn_lifecycle_gates_chunks_and_normalizes_terminal_states() {
+        let mut projection = Projection::default();
+        projection.apply(
+            1,
+            &event(serde_json::json!({"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"replay"}})),
+        );
+        assert_eq!(projection.state().turn, Default::default());
+
+        let (_, _) = projection.begin_turn();
+        assert!(projection.state().turn.responding);
+        assert!(projection.state().turn.thinking);
+        projection.apply(
+            2,
+            &event(serde_json::json!({"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"think"}})),
+        );
+        assert!(projection.state().turn.thinking);
+        projection.apply(
+            3,
+            &event(serde_json::json!({"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"answer"}})),
+        );
+        assert!(projection.state().turn.responding);
+        assert!(!projection.state().turn.thinking);
+
+        for terminal in [
+            TurnLifecycle::Finish,
+            TurnLifecycle::Cancel,
+            TurnLifecycle::Failure,
+        ] {
+            let (turn, _) = projection.begin_turn();
+            projection.turn_lifecycle(terminal, turn);
+            assert!(!projection.state().turn.responding);
+            assert!(!projection.state().turn.thinking);
+        }
+    }
+
+    fn terminal_turn_drops_unfinished_tools(
+        terminal: TurnLifecycle,
+        unfinished_id: &str,
+        next_id: &str,
+    ) {
+        let mut projection = Projection::default();
+        let (turn, _) = projection.begin_turn();
+        projection.apply(
+            1,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":unfinished_id,
+                "title":"Unfinished", "status":"in_progress"
+            })),
+        );
+        assert_eq!(projection.state().turn.active_tool_calls, [unfinished_id]);
+
+        projection.turn_lifecycle(terminal, turn);
+        assert!(projection.state().turn.active_tool_calls.is_empty());
+        assert_eq!(projection.snapshot(1).rows.len(), 1);
+
+        projection.begin_turn();
+        projection.apply(
+            2,
+            &event(serde_json::json!({
+                "sessionUpdate":"tool_call", "toolCallId":next_id,
+                "title":"Next", "status":"pending"
+            })),
+        );
+        assert_eq!(projection.state().turn.active_tool_calls, [next_id]);
+    }
+
+    #[test]
+    fn cancelled_turn_does_not_reactivate_unfinished_tools() {
+        terminal_turn_drops_unfinished_tools(TurnLifecycle::Cancel, "cancelled-1", "next-1");
+    }
+
+    #[test]
+    fn failed_turn_does_not_reactivate_unfinished_tools() {
+        terminal_turn_drops_unfinished_tools(TurnLifecycle::Failure, "failed-1", "next-1");
+    }
+
+    #[test]
+    fn approval_history_survives_pending_cleanup() {
+        let mut projection = Projection::default();
+        let update =
+            projection.request_approval("secret".into(), serde_json::json!({"tool":"bash"}));
+        let TranscriptDelta::Append { row } = update.transcript.unwrap() else {
+            panic!("approval row")
+        };
+        assert_eq!(row.kind, TranscriptRowKind::Approval);
+        assert!(row.data.get("nonce").is_none());
+        assert!(!row.id.contains("secret"));
+        let persisted =
+            serde_json::to_string(&crate::sidecar::PersistedEvent::Approval { row: row.clone() })
+                .unwrap();
+        assert!(!persisted.contains("secret"));
+        assert_eq!(
+            projection.state().pending_approval.unwrap()["nonce"],
+            "secret"
+        );
+        projection.clear_approval();
+        assert!(projection.state().pending_approval.is_none());
+        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();
+        let TranscriptDelta::Append { row } = live
+            .request_approval("daemon-nonce".into(), serde_json::json!({"tool":"bash"}))
+            .transcript
+            .unwrap()
+        else {
+            panic!("approval row")
+        };
+        let mut recovered = Projection::default();
+        let update = recovered.restore_approval(row.clone());
+        assert_eq!(
+            update.transcript,
+            Some(TranscriptDelta::Append { row: row.clone() })
+        );
+        assert!(update.state.pending_approval.is_none());
+        assert_eq!(recovered.snapshot(0).rows, vec![row]);
+        let replay = serde_json::to_string(&recovered.snapshot(1).rows).unwrap();
+        assert!(!replay.contains("daemon-nonce"));
+    }
+
+    #[test]
+    fn stale_terminal_turn_cannot_clear_newer_approval() {
+        let mut projection = Projection::default();
+        let (first, _) = projection.begin_turn();
+        projection.turn_lifecycle(TurnLifecycle::Cancel, first);
+        let (second, _) = projection.begin_turn();
+        projection.request_approval("second-nonce".into(), serde_json::json!({"tool":"bash"}));
+
+        assert!(projection
+            .turn_lifecycle(TurnLifecycle::Finish, first)
+            .is_none());
+        assert_eq!(projection.active_turn(), Some(second));
+        assert_eq!(
+            projection.state().pending_approval.unwrap()["nonce"],
+            "second-nonce"
+        );
+    }
+}

crates/maestro-daemon/src/sidecar.rs

@@ -5,10 +5,23 @@
 //! original `cwd`, command, env, metadata, etc. Files are deleted on
 //! `KillSession`. Sessions whose sidecar is missing at recovery time are still
 //! advertised but with empty metadata (handled by the caller, not here).
+//!
+//! A structured session (#135) also owns `<id>.events.jsonl` next to its
+//! sidecar: every `session/update` notification and daemon approval row is one
+//! JSON object, appended before it is broadcast. The log is the source of
+//! truth for the transcript; `seq` is the line's 1-based position, so a
+//! client that holds seq `n` asks for [`EventCursor::Since`]`(n)`. A line
+//! that does not parse — including the partial line a hard kill leaves at
+//! the end — keeps its seq and is skipped on read. `delete` removes the log
+//! with the sidecar; `load_all` never reads one as a sidecar.
 
+use std::collections::VecDeque;
+use std::fs::{File, OpenOptions};
+use std::io::{BufRead, BufReader, Read, Seek, SeekFrom, Write};
 use std::path::{Path, PathBuf};
 
-use maestro_protocol::Session;
+use maestro_acp::schema::SessionNotification;
+use maestro_protocol::{Session, TranscriptRow};
 use uuid::Uuid;
 
 #[derive(Debug, thiserror::Error)]
@@ -38,6 +51,120 @@ impl SidecarStore {
         self.dir.join(format!("{id}.json"))
     }
 
+    /// Where the per-session event log lives (#135).
+    pub fn events_path_for(&self, id: Uuid) -> PathBuf {
+        self.dir.join(format!("{id}.events.jsonl"))
+    }
+
+    /// Durable evidence that graceful daemon shutdown ended this structured
+    /// session and the next daemon may resume it.
+    pub fn recovery_path_for(&self, id: Uuid) -> PathBuf {
+        self.dir.join(format!("{id}.recover"))
+    }
+
+    /// Mark `id` as eligible for one structured-session recovery attempt.
+    pub fn mark_for_recovery(&self, id: Uuid) -> Result<(), SidecarError> {
+        std::fs::create_dir_all(&self.dir)?;
+        std::fs::write(self.recovery_path_for(id), [])?;
+        Ok(())
+    }
+
+    /// Consume the graceful-shutdown recovery marker for `id`.
+    pub fn take_recovery_marker(&self, id: Uuid) -> Result<bool, SidecarError> {
+        match std::fs::remove_file(self.recovery_path_for(id)) {
+            Ok(()) => Ok(true),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+            Err(error) => Err(error.into()),
+        }
+    }
+
+    /// Open the event log for `id` for appending, creating it (and the
+    /// directory) when missing. One handle per live session: the caller
+    /// keeps it for the session's lifetime rather than reopening per
+    /// notification.
+    ///
+    /// A log whose last line has no newline — what a hard kill mid-write
+    /// leaves behind — is terminated first, so the next append starts a
+    /// fresh line instead of gluing onto the fragment. The fragment keeps
+    /// the seq of its line and reads as malformed.
+    pub fn open_events(&self, id: Uuid) -> Result<EventLog, SidecarError> {
+        std::fs::create_dir_all(&self.dir)?;
+        let mut file = OpenOptions::new()
+            .create(true)
+            .read(true)
+            .append(true)
+            .open(self.events_path_for(id))?;
+        let mut lines = 0u64;
+        let mut last = None;
+        let mut reader = BufReader::new(&mut file);
+        let mut buf = [0u8; 64 * 1024];
+        loop {
+            let n = reader.read(&mut buf)?;
+            if n == 0 {
+                break;
+            }
+            lines += buf[..n].iter().filter(|&&b| b == b'\n').count() as u64;
+            last = Some(buf[n - 1]);
+        }
+        if last.is_some_and(|b| b != b'\n') {
+            file.write_all(b"\n")?;
+            lines += 1;
+        }
+        file.seek(SeekFrom::End(0))?;
+        Ok(EventLog {
+            file: Box::new(file),
+            last_seq: lines,
+        })
+    }
+
+    /// Read events from the log for `id`, at most `limit`, in ascending seq
+    /// order. A missing log is an empty log. Lines that fail to parse are
+    /// skipped but still consume a seq, so cursors stay stable.
+    pub fn read_events(
+        &self,
+        id: Uuid,
+        cursor: EventCursor,
+        limit: usize,
+    ) -> Result<Vec<LoggedEvent>, SidecarError> {
+        let file = match File::open(self.events_path_for(id)) {
+            Ok(f) => f,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+            Err(e) => return Err(e.into()),
+        };
+        if limit == 0 {
+            return Ok(Vec::new());
+        }
+        let mut out: VecDeque<LoggedEvent> = VecDeque::new();
+        let mut seq = 0u64;
+        for line in BufReader::new(file).split(b'\n') {
+            let line = line?;
+            seq += 1;
+            let keep = match cursor {
+                EventCursor::Since(since) => seq > since,
+                EventCursor::Before(Some(before)) => seq < before,
+                EventCursor::Before(None) => true,
+            };
+            if !keep {
+                if matches!(cursor, EventCursor::Before(Some(_))) {
+                    break;
+                }
+                continue;
+            }
+            let Ok(event) = PersistedEvent::decode(&line) else {
+                continue;
+            };
+            out.push_back(LoggedEvent { seq, event });
+            match cursor {
+                EventCursor::Since(_) if out.len() >= limit => break,
+                EventCursor::Before(_) if out.len() > limit => {
+                    out.pop_front();
+                }
+                _ => {}
+            }
+        }
+        Ok(out.into())
+    }
+
     /// Atomically write `session` to `<dir>/<id>.json`. Creates the directory
     /// if it does not exist.
     pub fn write(&self, session: &Session) -> Result<(), SidecarError> {
@@ -59,13 +186,13 @@ impl SidecarStore {
         }
     }
 
-    /// Delete the sidecar for `id`. No-op if it does not exist.
+    /// Delete the sidecar, event log, and recovery marker for `id`. No-op for
+    /// whichever does not exist.
     pub fn delete(&self, id: Uuid) -> Result<(), SidecarError> {
-        match std::fs::remove_file(self.path_for(id)) {
-            Ok(()) => Ok(()),
-            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
-            Err(e) => Err(e.into()),
-        }
+        remove_if_present(&self.events_path_for(id))?;
+        remove_if_present(&self.dir.join(format!("{id}.approvals.jsonl")))?;
+        remove_if_present(&self.recovery_path_for(id))?;
+        remove_if_present(&self.path_for(id))
     }
 
     /// Read every sidecar JSON in the directory. Files that fail to parse are
@@ -81,6 +208,8 @@ impl SidecarStore {
         for entry in entries {
             let entry = entry?;
             let path = entry.path();
+            // `.events.jsonl` logs (#135) sit in the same directory and are
+            // never sidecars.
             if path.extension().and_then(|s| s.to_str()) != Some("json") {
                 continue;
             }
@@ -95,3 +224,419 @@ impl SidecarStore {
         Ok(out)
     }
 }
+
+fn remove_if_present(path: &Path) -> Result<(), SidecarError> {
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(e.into()),
+    }
+}
+
+/// Which slice of a session's event log to read.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EventCursor {
+    /// Forward: events with `seq` strictly greater than the cursor, the
+    /// first `limit` of them. `Since(0)` is the whole log from the start.
+    /// What a client catching up after a reconnect asks for.
+    Since(u64),
+    /// Backward: events with `seq` strictly less than the cursor, the last
+    /// `limit` of them, still returned in ascending order. `None` means the
+    /// tail of the log, for a first paint. The next page passes the smallest
+    /// seq it received.
+    Before(Option<u64>),
+}
+
+/// One line of a session's event log.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LoggedEvent {
+    /// 1-based line position in the log; the cursor for [`EventCursor`].
+    pub seq: u64,
+    pub event: PersistedEvent,
+}
+
+/// A single entry in the structured event history.
+///
+/// ACP notifications retain their original JSON representation, so existing
+/// event logs remain readable. Daemon-generated rows use an envelope so they
+/// can share the same cursor sequence without pretending to be ACP traffic.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(tag = "maestroEvent", rename_all = "snake_case")]
+pub enum PersistedEvent {
+    Approval {
+        row: TranscriptRow,
+    },
+    #[serde(skip)]
+    Notification(Box<SessionNotification>),
+}
+
+impl PersistedEvent {
+    fn decode(line: &[u8]) -> Result<Self, serde_json::Error> {
+        serde_json::from_slice::<SessionNotification>(line)
+            .map(|notification| Self::Notification(Box::new(notification)))
+            .or_else(|_| serde_json::from_slice(line))
+    }
+}
+
+impl From<SessionNotification> for PersistedEvent {
+    fn from(notification: SessionNotification) -> Self {
+        Self::Notification(Box::new(notification))
+    }
+}
+
+impl From<&SessionNotification> for PersistedEvent {
+    fn from(notification: &SessionNotification) -> Self {
+        Self::Notification(Box::new(notification.clone()))
+    }
+}
+
+impl From<&PersistedEvent> for PersistedEvent {
+    fn from(event: &PersistedEvent) -> Self {
+        event.clone()
+    }
+}
+
+/// What an [`EventLog`] appends onto: something seekable by length and
+/// truncatable back to one, so a failed append can be rolled off the end
+/// again. A real [`File`] in production; an in-memory fault double in tests
+/// (#184) — the same [`EventLog::append`] rollback logic runs over both, so
+/// the behavior under test is the production behavior, not a stand-in for
+/// it.
+pub(crate) trait LogSink: Write + Send {
+    fn len(&mut self) -> std::io::Result<u64>;
+    fn truncate(&mut self, len: u64) -> std::io::Result<()>;
+}
+
+impl LogSink for File {
+    fn len(&mut self) -> std::io::Result<u64> {
+        Ok(self.metadata()?.len())
+    }
+
+    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
+        self.set_len(len)
+    }
+}
+
+/// Outcome of a failed [`EventLog::append`].
+#[derive(Debug, thiserror::Error)]
+pub enum AppendError {
+    /// The write or flush failed, but the log was rolled back to exactly the
+    /// byte it was at before the call: `last_seq` and the file agree, and
+    /// this same [`EventLog`] is safe to keep appending to. The event itself
+    /// was never persisted or broadcast.
+    #[error("event append failed, rolled back cleanly: {0}")]
+    Failed(#[source] SidecarError),
+    /// The append failed *and* the rollback did not restore the log to its
+    /// prior length, so the file's line count and `last_seq` may now
+    /// disagree. The caller must not append to this [`EventLog`] again —
+    /// treat the session as dead rather than promise consistency it cannot
+    /// keep.
+    #[error("event append failed ({cause}) and rollback did not restore consistency ({rollback})")]
+    Fatal {
+        cause: SidecarError,
+        rollback: SidecarError,
+    },
+}
+
+impl From<SidecarError> for AppendError {
+    fn from(error: SidecarError) -> Self {
+        AppendError::Failed(error)
+    }
+}
+
+/// An open, append-only handle on one session's event log. Obtained from
+/// [`SidecarStore::open_events`]; held for the session's lifetime.
+pub struct EventLog {
+    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
+    }
+
+    /// Append one notification as a line and return its seq. The line is
+    /// 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.
+    ///
+    /// A `write_all` that errors partway can leave an unterminated prefix on
+    /// disk; a `flush` that errors after a *complete* `write_all` leaves
+    /// ambiguity about whether that full, well-formed line should count —
+    /// counting it would silently shift every later seq by one, since
+    /// `last_seq` was never bumped for it. Both cases are rolled back to the
+    /// exact pre-append length before returning, so `last_seq` and the file
+    /// never disagree and the same [`EventLog`] can be appended to again
+    /// immediately. If the rollback itself fails, the log's consistency can
+    /// no longer be promised and [`AppendError::Fatal`] is returned instead.
+    pub fn append(&mut self, event: impl Into<PersistedEvent>) -> Result<u64, AppendError> {
+        let event = event.into();
+        let mut line = match &event {
+            PersistedEvent::Notification(notification) => serde_json::to_vec(notification)
+                .map_err(|e| AppendError::from(SidecarError::from(e)))?,
+            _ => {
+                serde_json::to_vec(&event).map_err(|e| AppendError::from(SidecarError::from(e)))?
+            }
+        };
+        line.push(b'\n');
+
+        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/src/worktree.rs

@@ -111,16 +111,33 @@ impl WorktreeManager {
         // Clear registrations whose directory is gone first, so a
         // previously-leaked entry doesn't push this branch to a suffix.
         prune(base_repo)?;
-        // Anything occupying the target — a tree we left behind, one the
-        // operator made, an unrelated directory — is sidestepped with a
-        // numeric suffix on the directory; the branch stays whatever was
-        // requested (#77). The daemon never adopts what it finds.
-        let mut path = self.target_path(base_repo, branch);
-        let mut n = 1;
-        while path.symlink_metadata().is_ok() {
-            n += 1;
-            path = self.target_path_suffixed(base_repo, branch, n);
-        }
+        let (branch, path) = if create_branch {
+            // Worktrees are commonly abandoned without deleting their branch,
+            // so a random handle can collide with one of its own past runs.
+            // Unlike the `add_existing` arm below, the suffix goes on the
+            // branch name itself — the path is derived from it anyway.
+            let mut candidate = branch.to_string();
+            let mut path = self.target_path(base_repo, &candidate);
+            let mut n = 1;
+            while path.symlink_metadata().is_ok() || branch_exists(base_repo, &candidate) {
+                n += 1;
+                candidate = format!("{branch}-{n}");
+                path = self.target_path(base_repo, &candidate);
+            }
+            (candidate, path)
+        } else {
+            // Existing branch: the name must stay exact, so only the
+            // directory — anything occupying it, ours or the operator's — is
+            // sidestepped with a numeric suffix (#77). The daemon never
+            // adopts what it finds.
+            let mut path = self.target_path(base_repo, branch);
+            let mut n = 1;
+            while path.symlink_metadata().is_ok() {
+                n += 1;
+                path = self.target_path_suffixed(base_repo, branch, n);
+            }
+            (branch.to_string(), path)
+        };
         // The parent (`<repo>/worktrees` or the override root) may not exist
         // yet; the target itself must not.
         if let Some(parent) = path.parent() {
@@ -129,10 +146,10 @@ impl WorktreeManager {
         let mut cmd = Command::new("git");
         cmd.arg("-C").arg(base_repo).args(["worktree", "add"]);
         if create_branch {
-            cmd.arg("-b").arg(branch).arg(&path);
+            cmd.arg("-b").arg(&branch).arg(&path);
         } else {
             // Existing branch: `worktree add <path> <branch>` with no `-b`.
-            cmd.arg(&path).arg(branch);
+            cmd.arg(&path).arg(&branch);
         }
         let out = cmd.output()?;
         check(out)?;
@@ -266,6 +283,17 @@ fn branch_relpath(branch: &str) -> Option<PathBuf> {
     Some(candidate.to_path_buf())
 }
 
+/// Whether `refs/heads/<branch>` already exists in `base_repo`.
+fn branch_exists(base_repo: &Path, branch: &str) -> bool {
+    Command::new("git")
+        .arg("-C")
+        .arg(base_repo)
+        .args(["show-ref", "--verify", "--quiet"])
+        .arg(format!("refs/heads/{branch}"))
+        .status()
+        .is_ok_and(|s| s.success())
+}
+
 /// `git -C <base_repo> worktree prune` — drops registrations whose directory
 /// no longer exists.
 fn prune(base_repo: &Path) -> Result<(), WorktreeError> {

crates/maestro-daemon/tests/activity_report.rs

@@ -42,6 +42,7 @@ async fn fixture(ttl: Duration) -> Fixture {
 async fn spawn_sleeping(manager: &SessionManager) -> Uuid {
     manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: Default::default(),

crates/maestro-daemon/tests/attach.rs

@@ -75,6 +75,7 @@ async fn create_bash_session(h: &Harness) -> Uuid {
     let s = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd_path,
             command: "bash --noprofile --norc".into(),
             env: HashMap::new(),

crates/maestro-daemon/tests/autoname.rs

@@ -50,6 +50,7 @@ async fn spawn(manager: &SessionManager, name: Option<&str>) -> Uuid {
     };
     manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: Default::default(),

crates/maestro-daemon/tests/blocked_work_cost.rs

@@ -19,6 +19,7 @@ use tempfile::TempDir;
 
 fn request(cwd: &std::path::Path, repo: &std::path::Path, branch: &str) -> CreateSessionRequest {
     CreateSessionRequest {
+        view: Default::default(),
         cwd: cwd.to_path_buf(),
         command: "sleep 30".into(),
         env: HashMap::new(),

crates/maestro-daemon/tests/local_api.rs

@@ -4,12 +4,17 @@ mod common;
 
 use std::collections::HashMap;
 use std::net::{Ipv4Addr, SocketAddr};
+use std::path::Path;
 use std::time::Duration;
 
 use common::DaemonFixture;
 use futures_util::{SinkExt, StreamExt};
 use maestro_daemon::local_api;
-use maestro_protocol::{ApiError, CreateSessionRequest, Session, WorktreeSpec};
+use maestro_protocol::{
+    ActivityState, ApiError, CreateSessionRequest, Session, SessionStatus, SessionView,
+    WorktreeSpec,
+};
+use tempfile::TempDir;
 use tokio::net::TcpListener;
 use tokio::sync::oneshot;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
@@ -86,6 +91,589 @@ fn ws_url(addr: SocketAddr, path: &str) -> String {
     format!("ws://{addr}{path}")
 }
 
+struct FakeAcp {
+    dir: TempDir,
+}
+
+impl FakeAcp {
+    fn new() -> Self {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = TempDir::new().unwrap();
+        let bin = dir.path().join("bin");
+        std::fs::create_dir_all(&bin).unwrap();
+        let adapter = bin.join("claude-code-acp");
+        std::fs::copy(
+            Path::new(env!("CARGO_MANIFEST_DIR")).join("../maestro-acp/tests/fake_acp_agent.py"),
+            &adapter,
+        )
+        .unwrap();
+        std::fs::set_permissions(&adapter, std::fs::Permissions::from_mode(0o755)).unwrap();
+        Self { dir }
+    }
+
+    fn env(&self) -> HashMap<String, String> {
+        HashMap::from([
+            (
+                "PATH".into(),
+                format!(
+                    "{}:{}",
+                    self.dir.path().join("bin").display(),
+                    std::env::var("PATH").unwrap()
+                ),
+            ),
+            (
+                "FAKE_ACP_LOG".into(),
+                self.dir.path().join("agent.log").display().to_string(),
+            ),
+        ])
+    }
+
+    fn pid(&self) -> u32 {
+        std::fs::read_to_string(self.dir.path().join("agent.log"))
+            .unwrap_or_default()
+            .lines()
+            .filter_map(|line| {
+                line.strip_prefix("start pid=")?
+                    .split(' ')
+                    .next()?
+                    .parse()
+                    .ok()
+            })
+            .next_back()
+            .expect("fake ACP started")
+    }
+
+    fn log(&self) -> String {
+        std::fs::read_to_string(self.dir.path().join("agent.log")).unwrap_or_default()
+    }
+}
+
+async fn structured_session(h: &Harness, fake: &FakeAcp) -> Uuid {
+    structured_session_with_env(h, fake.env()).await
+}
+
+async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>) -> Uuid {
+    h.manager
+        .create(CreateSessionRequest {
+            view: SessionView::Structured,
+            cwd: "/tmp".into(),
+            command: "claude".into(),
+            env,
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap()
+        .id
+}
+
+async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if sessions
+                .iter()
+                .find(|session| session.id == id)
+                .is_some_and(|session| session.activity == expected)
+            {
+                return;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap_or_else(|_| panic!("session {id} did not reach {expected:?}"));
+}
+
+#[tokio::test]
+async fn structured_ws_sends_snapshot_then_live_projection() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+
+    let first = ws.next().await.unwrap().unwrap().into_text().unwrap();
+    let second = ws.next().await.unwrap().unwrap().into_text().unwrap();
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&first).unwrap()["type"],
+        "transcript_snapshot"
+    );
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&second).unwrap()["type"],
+        "reduced_state"
+    );
+
+    let response = reqwest::Client::new()
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "hello"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::NO_CONTENT);
+    let live = tokio::time::timeout(Duration::from_secs(1), ws.next())
+        .await
+        .expect("projection update arrives on the subscribed stream")
+        .unwrap()
+        .unwrap()
+        .into_text()
+        .unwrap();
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(&live).unwrap()["type"],
+        "projection_update"
+    );
+}
+
+#[tokio::test]
+async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "200".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let first = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "first"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(first.status(), reqwest::StatusCode::NO_CONTENT);
+    let second = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "second"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(second.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = second.json().await.unwrap();
+    assert_eq!(error.error.code, "turn_in_flight");
+
+    let cancel = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/cancel"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(cancel.status(), reqwest::StatusCode::NO_CONTENT);
+    let next = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "next"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(next.status(), reqwest::StatusCode::NO_CONTENT);
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if fake.log().matches("recv session/prompt").count() == 2 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("both prompt commands reach ACP");
+    let log = fake.log();
+    let first_prompt = log.find("recv session/prompt").unwrap();
+    let cancel = log.find("recv session/cancel").unwrap();
+    let second_prompt = log.rfind("recv session/prompt").unwrap();
+    assert!(first_prompt < cancel && cancel < second_prompt, "{log}");
+}
+
+#[tokio::test]
+async fn structured_approval_is_secret_single_use_and_race_safe() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_REQUEST_PERMISSION".into(), "1".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+    ws.next().await.unwrap().unwrap();
+    ws.next().await.unwrap().unwrap();
+    assert_eq!(
+        client
+            .post(url(
+                h.addr,
+                &format!("/api/sessions/{id}/structured/prompt")
+            ))
+            .json(&serde_json::json!({"prompt":"needs permission"}))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NO_CONTENT
+    );
+
+    let nonce = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let event: serde_json::Value =
+                serde_json::from_str(&ws.next().await.unwrap().unwrap().into_text().unwrap())
+                    .unwrap();
+            if let Some(nonce) = event["state"]["pending_approval"]["nonce"].as_str() {
+                assert_eq!(event["transcript"]["row"]["kind"], "approval");
+                assert!(event["transcript"]["row"]["data"].get("nonce").is_none());
+                break nonce.to_owned();
+            }
+        }
+    })
+    .await
+    .unwrap();
+    wait_for_session_activity(&h, id, ActivityState::AwaitingInput).await;
+    assert!(
+        !fake.log().contains(&nonce),
+        "daemon nonce leaked to ACP agent"
+    );
+
+    let path = format!("/api/sessions/{id}/structured/approvals/{nonce}");
+    let (a, b) = tokio::join!(
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("allow_once"))
+            .send(),
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("deny"))
+            .send(),
+    );
+    assert_eq!(a.unwrap().status(), reqwest::StatusCode::NO_CONTENT);
+    assert_eq!(b.unwrap().status(), reqwest::StatusCode::NO_CONTENT);
+    assert_eq!(
+        client
+            .post(url(h.addr, &path))
+            .json(&serde_json::json!("deny"))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NO_CONTENT
+    );
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if fake.log().contains("permission response") {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    let log = fake.log();
+    assert!(
+        log.contains("\"optionId\": \"once\"") || log.contains("\"optionId\": \"deny\""),
+        "{log}"
+    );
+    tokio::time::timeout(Duration::from_secs(1), async {
+        loop {
+            let event: serde_json::Value =
+                serde_json::from_str(&ws.next().await.unwrap().unwrap().into_text().unwrap())
+                    .unwrap();
+            if event["state"]["pending_approval"].is_null() {
+                break;
+            }
+        }
+    })
+    .await
+    .expect("resolved approval clears the reduced state");
+    wait_for_session_activity(&h, id, ActivityState::Idle).await;
+    assert_eq!(
+        client
+            .post(url(
+                h.addr,
+                &format!(
+                    "/api/sessions/{}/structured/approvals/{nonce}",
+                    Uuid::new_v4()
+                )
+            ))
+            .json(&serde_json::json!("deny"))
+            .send()
+            .await
+            .unwrap()
+            .status(),
+        reqwest::StatusCode::NOT_FOUND
+    );
+}
+
+#[tokio::test]
+async fn structured_prompt_failure_clears_the_turn() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_PROMPT_FAIL_ONCE".into(), "1".into());
+    let id = structured_session_with_env(&h, env).await;
+    let client = reqwest::Client::new();
+    let path = format!("/api/sessions/{id}/structured/prompt");
+    let (mut ws, _) = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .unwrap();
+    ws.next().await.unwrap().unwrap();
+    ws.next().await.unwrap().unwrap();
+    let first = client
+        .post(url(h.addr, &path))
+        .json(&serde_json::json!({"prompt":"fails"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(first.status(), reqwest::StatusCode::NO_CONTENT);
+    let mut saw_active_turn = false;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while let Some(Ok(message)) = ws.next().await {
+            let event: serde_json::Value =
+                serde_json::from_str(&message.into_text().unwrap()).unwrap();
+            let turn = &event["state"]["turn"];
+            if turn["responding"] == true {
+                saw_active_turn = true;
+            }
+            if saw_active_turn && turn["responding"] == false && turn["thinking"] == false {
+                return;
+            }
+        }
+        panic!("structured websocket closed before the failed turn cleared");
+    })
+    .await
+    .expect("failed turn clears promptly");
+    wait_for_session_activity(&h, id, ActivityState::Error).await;
+    let second = client
+        .post(url(h.addr, &path))
+        .json(&serde_json::json!({"prompt":"available"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(second.status(), reqwest::StatusCode::NO_CONTENT);
+    assert!(second.bytes().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn structured_prompt_rejects_unknown_and_unavailable_sessions() {
+    let h = spawn("naps-laptop").await;
+    let client = reqwest::Client::new();
+    let prompt = |id| {
+        client
+            .post(url(
+                h.addr,
+                &format!("/api/sessions/{id}/structured/prompt"),
+            ))
+            .json(&serde_json::json!({"prompt": "hello"}))
+    };
+
+    let unknown = prompt(Uuid::new_v4()).send().await.unwrap();
+    assert_eq!(unknown.status(), reqwest::StatusCode::NOT_FOUND);
+    let error: ApiError = unknown.json().await.unwrap();
+    assert_eq!(error.error.code, "not_found");
+
+    let terminal = h
+        .manager
+        .create(CreateSessionRequest {
+            view: SessionView::Terminal,
+            cwd: "/tmp".into(),
+            command: "sh".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap();
+    let non_structured = prompt(terminal.id).send().await.unwrap();
+    assert_eq!(non_structured.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = non_structured.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+
+    let fake = FakeAcp::new();
+    let dead = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(dead).await, Some(SessionStatus::Dead));
+    let unavailable = prompt(dead).send().await.unwrap();
+    assert_eq!(unavailable.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = unavailable.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+}
+
+#[tokio::test]
+async fn structured_replay_honors_cursors_and_limit() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+
+    let events: Vec<serde_json::Value> = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let events: Vec<serde_json::Value> = client
+                .get(url(
+                    h.addr,
+                    &format!("/api/sessions/{id}/structured/replay?since=0&limit=1"),
+                ))
+                .send()
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if !events.is_empty() {
+                return events;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(events.len(), 1);
+    assert_eq!(events[0]["cursor"], 1);
+    assert!(events[0].get("notification").is_none());
+
+    let invalid = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/replay?since=0&before=2"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(invalid.status(), reqwest::StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn structured_replay_pages_projected_events_in_cursor_order() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+    unsafe { libc::kill(fake.pid() as libc::pid_t, libc::SIGUSR1) };
+    let events: Vec<serde_json::Value> = tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let events: Vec<serde_json::Value> = client
+                .get(url(
+                    h.addr,
+                    &format!("/api/sessions/{id}/structured/replay?before=99&limit=2"),
+                ))
+                .send()
+                .await
+                .unwrap()
+                .json()
+                .await
+                .unwrap();
+            if events.len() == 2 {
+                return events;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(
+        events
+            .iter()
+            .map(|event| event["cursor"].as_u64().unwrap())
+            .collect::<Vec<_>>(),
+        vec![1, 2]
+    );
+    let boundary: Vec<serde_json::Value> = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/replay?before=2&limit=10"),
+        ))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(boundary.len(), 1);
+    assert_eq!(boundary[0]["cursor"], 1);
+}
+
+#[tokio::test]
+async fn structured_replay_rejects_unknown_terminal_and_dead_sessions() {
+    let h = spawn("naps-laptop").await;
+    let client = reqwest::Client::new();
+    let unknown = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/replay", Uuid::new_v4()),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(unknown.status(), reqwest::StatusCode::NOT_FOUND);
+    let terminal = h
+        .manager
+        .create(CreateSessionRequest {
+            view: SessionView::Terminal,
+            cwd: "/tmp".into(),
+            command: "sh".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap();
+    let response = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/replay", terminal.id),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+
+    let fake = FakeAcp::new();
+    let dead = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(dead).await, Some(SessionStatus::Dead));
+    let response = client
+        .get(url(
+            h.addr,
+            &format!("/api/sessions/{dead}/structured/replay"),
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = response.json().await.unwrap();
+    assert_eq!(error.error.code, "not_structured");
+}
+
+#[tokio::test]
+async fn structured_ws_rejects_a_dead_session() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    h.manager.shutdown().await;
+    assert_eq!(h.manager.status(id).await, Some(SessionStatus::Dead));
+
+    let err = connect_async(ws_url(h.addr, &format!("/api/structured/{id}")))
+        .await
+        .expect_err("dead structured session must not upgrade");
+    let message = err.to_string();
+    assert!(
+        message.contains("409") || message.to_lowercase().contains("conflict"),
+        "{message}"
+    );
+}
+
 #[tokio::test]
 async fn info_returns_daemon_identity() {
     let h = spawn("naps-laptop").await;
@@ -174,6 +762,7 @@ async fn list_sessions_starts_empty_and_reflects_creates() {
     assert!(empty.is_empty());
 
     let req = CreateSessionRequest {
+        view: Default::default(),
         cwd: "/tmp".into(),
         command: "sleep 60".into(),
         env: HashMap::new(),
@@ -390,6 +979,7 @@ async fn patch_session_renames_it() {
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -432,6 +1022,7 @@ async fn post_focus_stamps_last_focused_at() {
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -465,6 +1056,7 @@ async fn delete_owned_session_kills_it() {
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -486,6 +1078,7 @@ async fn delete_owned_session_kills_it() {
 async fn spawn_via_manager(h: &Harness) -> Uuid {
     h.manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -595,6 +1188,7 @@ async fn delete_a_session_whose_worktree_holds_unsaved_work_returns_409_with_the
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -647,6 +1241,7 @@ async fn delete_with_force_ends_the_session_and_keeps_the_worktree() {
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 60".into(),
             env: HashMap::new(),
@@ -680,6 +1275,7 @@ async fn attach_ws_streams_pty_bytes() {
     let session = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "bash --noprofile --norc".into(),
             env: HashMap::new(),
@@ -748,6 +1344,7 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
     let created = h
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -780,6 +1377,73 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
     }
 }
 
+#[tokio::test]
+async fn events_ws_streams_structured_activity_without_hook_overrides() {
+    let h = spawn("konishi").await;
+    let fake = FakeAcp::new();
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "500".into());
+    let (mut ws, _) = connect_async(ws_url(h.addr, "/api/events"))
+        .await
+        .expect("events ws");
+    assert!(matches!(
+        next_event(&mut ws).await,
+        maestro_protocol::CatalogEvent::Snapshot { .. }
+    ));
+
+    let id = structured_session_with_env(&h, env).await;
+    let maestro_protocol::CatalogEvent::SessionAdded { session } = next_event(&mut ws).await else {
+        panic!("expected structured SessionAdded")
+    };
+    assert_eq!(session.activity, ActivityState::Idle);
+
+    let client = reqwest::Client::new();
+    let prompt = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{id}/structured/prompt"),
+        ))
+        .json(&serde_json::json!({"prompt": "hello"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(prompt.status(), reqwest::StatusCode::NO_CONTENT);
+    let report = client
+        .post(url(h.addr, &format!("/api/sessions/{id}/activity")))
+        .json(&serde_json::json!({"state": "Error"}))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(report.status(), reqwest::StatusCode::NO_CONTENT);
+    wait_for_session_activity(&h, id, ActivityState::Active).await;
+
+    let mut activities = Vec::new();
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            if let maestro_protocol::CatalogEvent::SessionUpdated { session } =
+                next_event(&mut ws).await
+            {
+                activities.push(session.activity);
+                if session.activity == ActivityState::Idle {
+                    return;
+                }
+            }
+        }
+    })
+    .await
+    .expect("structured turn returns to idle");
+    assert!(
+        activities.contains(&ActivityState::Active),
+        "{activities:?}"
+    );
+    assert!(
+        !activities.contains(&ActivityState::Error),
+        "{activities:?}"
+    );
+
+    h.manager.kill(id, false).await.unwrap();
+}
+
 /// Each subscriber has its own lag domain now that the publisher task is gone:
 /// two clients connected at different times both get their own Snapshot.
 #[tokio::test]
@@ -792,6 +1456,7 @@ async fn every_events_subscriber_gets_its_own_snapshot() {
 
     h.manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),

crates/maestro-daemon/tests/rename.rs

@@ -51,6 +51,7 @@ async fn spawn_named(manager: &SessionManager, name: Option<&str>) -> Uuid {
     };
     manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: "/tmp".into(),
             command: "sleep 60".into(),
             env: Default::default(),

crates/maestro-daemon/tests/session_decisions.rs

@@ -64,6 +64,7 @@ impl Fx {
 
     fn request(&self, command: &str) -> CreateSessionRequest {
         CreateSessionRequest {
+            view: Default::default(),
             cwd: self.tmp.path().to_path_buf(),
             command: command.into(),
             env: HashMap::new(),

crates/maestro-daemon/tests/session_manager.rs

@@ -22,6 +22,7 @@ async fn create_then_kill_round_trip() {
     let session = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -63,6 +64,7 @@ async fn create_appends_to_spawn_history() {
     let session = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -92,6 +94,7 @@ async fn create_without_history_logs_nothing() {
     let cwd = TempDir::new().unwrap();
     fx.manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -114,6 +117,7 @@ async fn recover_adopts_existing_tmux_sessions() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -153,6 +157,7 @@ async fn create_captures_initial_output_in_replay_buffer() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             // The shell prints the marker before doing anything else and
             // then sleeps so the session stays alive. Before NAP-253 this
@@ -200,6 +205,7 @@ async fn attach_replay_is_the_current_screen_not_the_byte_tail() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+        view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             // Print a line, then switch to the alternate screen the way a
             // full-screen program does on startup. Only the second marker is
@@ -258,6 +264,7 @@ async fn attach_replay_carries_the_panes_mouse_modes() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+        view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             // Alternate screen, then button-event tracking (?1002) with SGR
             // coordinates (?1006) — what tmux and agent TUIs actually request.
@@ -311,6 +318,7 @@ async fn recover_re_pipes_pane_so_output_reaches_subscribers() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "bash --noprofile --norc".into(),
             env: HashMap::new(),
@@ -373,6 +381,7 @@ async fn pty_broadcast_delivers_bytes_to_subscribers() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "bash --noprofile --norc".into(),
             env: HashMap::new(),
@@ -423,6 +432,7 @@ async fn liveness_watcher_marks_dead_sessions_and_keeps_them_until_dismissed() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -488,6 +498,7 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
 
     fx.manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -580,6 +591,7 @@ async fn kill_removes_worktree_even_when_spec_says_keep() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -617,6 +629,7 @@ async fn killing_refuses_a_worktree_with_unsaved_work_and_keeps_the_session() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -680,6 +693,7 @@ async fn killing_refuses_until_the_branch_is_pushed() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -729,6 +743,7 @@ async fn force_killing_a_guarded_worktree_leaves_it_on_disk() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -774,6 +789,7 @@ async fn force_on_a_clear_worktree_removes_it_as_usual() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -814,6 +830,7 @@ async fn killing_an_ignored_only_worktree_succeeds() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -855,6 +872,7 @@ async fn natural_exit_of_a_guarded_worktree_leaves_it_on_disk() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -916,6 +934,7 @@ async fn natural_exit_of_a_pristine_worktree_removes_it() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -976,6 +995,7 @@ async fn liveness_watcher_leaves_running_sessions_alone() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1010,6 +1030,7 @@ async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
     let first = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: repo.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1027,6 +1048,7 @@ async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
     let second = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: inner_worktree.clone(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1065,6 +1087,7 @@ async fn spawned_sessions_export_maestro_session_id_and_url() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1103,6 +1126,7 @@ async fn a_freshly_created_session_has_never_been_focused() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1128,6 +1152,7 @@ async fn set_focused_true_stamps_last_focused_at() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),
@@ -1176,6 +1201,7 @@ async fn attaching_stamps_last_focused_at() {
     let s = fx
         .manager
         .create(CreateSessionRequest {
+            view: Default::default(),
             cwd: cwd.path().to_path_buf(),
             command: "sleep 30".into(),
             env: HashMap::new(),

crates/maestro-daemon/tests/sidecar.rs

@@ -6,8 +6,8 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 
 use chrono::{DateTime, Utc};
-use maestro_daemon::sidecar::SidecarStore;
-use maestro_protocol::{Session, SessionStatus};
+use maestro_daemon::sidecar::{PersistedEvent, SidecarStore};
+use maestro_protocol::{Session, SessionStatus, SessionView, TranscriptRow, TranscriptRowKind};
 use serde_json::Value;
 use tempfile::TempDir;
 use uuid::Uuid;
@@ -32,6 +32,8 @@ fn sample(id: Uuid) -> Session {
         current_cwd: Some(PathBuf::from("/tmp/work/crates")),
         blocked_work: None,
         last_focused_at: None,
+        acp_session_id: None,
+        view: SessionView::Terminal,
     }
 }
 
@@ -66,15 +68,30 @@ fn delete_removes_file_and_is_idempotent() {
     let s = sample(id);
 
     store.write(&s).unwrap();
+    store.mark_for_recovery(id).unwrap();
     assert!(store.path_for(id).exists());
+    assert!(store.recovery_path_for(id).exists());
 
     store.delete(id).unwrap();
     assert!(!store.path_for(id).exists());
+    assert!(!store.recovery_path_for(id).exists());
 
     // second delete is a no-op
     store.delete(id).unwrap();
 }
 
+#[test]
+fn recovery_marker_is_consumed_once() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+
+    assert!(!store.take_recovery_marker(id).unwrap());
+    store.mark_for_recovery(id).unwrap();
+    assert!(store.take_recovery_marker(id).unwrap());
+    assert!(!store.take_recovery_marker(id).unwrap());
+}
+
 #[test]
 fn load_all_recovers_every_sidecar_and_skips_garbage() {
     let dir = TempDir::new().unwrap();
@@ -103,6 +120,37 @@ fn load_all_returns_empty_when_directory_missing() {
     assert!(store.load_all().unwrap().is_empty());
 }
 
+#[test]
+fn sidecar_missing_view_key_reads_as_terminal() {
+    // A pre-#133 sidecar on disk has no `view` field at all.
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+
+    let mut value = serde_json::to_value(sample(id)).unwrap();
+    value.as_object_mut().unwrap().remove("view");
+    std::fs::write(store.path_for(id), serde_json::to_vec(&value).unwrap()).unwrap();
+
+    let loaded = store.read(id).expect("read").expect("present");
+    assert_eq!(loaded.view, SessionView::Terminal);
+}
+
+#[test]
+fn sidecar_structured_view_round_trips() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let mut s = sample(id);
+    s.view = SessionView::Structured;
+
+    store.write(&s).expect("write");
+    let loaded = store.read(id).expect("read");
+    assert_eq!(
+        loaded.as_ref().map(|s| s.view),
+        Some(SessionView::Structured)
+    );
+}
+
 #[test]
 fn write_creates_parent_directory() {
     let dir = TempDir::new().unwrap();
@@ -113,3 +161,237 @@ fn write_creates_parent_directory() {
     assert!(nested.exists());
     assert!(store.path_for(s.id).exists());
 }
+
+// ---- per-session event log (#135) ----
+
+use maestro_acp::schema::{ContentBlock, SessionNotification, SessionUpdate, TextContent};
+use maestro_daemon::sidecar::EventCursor;
+
+fn note(text: &str) -> SessionNotification {
+    SessionNotification::new(
+        "acp-1",
+        SessionUpdate::AgentMessageChunk(maestro_acp::schema::ContentChunk::new(
+            ContentBlock::Text(TextContent::new(text)),
+        )),
+    )
+}
+
+fn text_of(n: &SessionNotification) -> &str {
+    match &n.update {
+        SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
+            ContentBlock::Text(t) => &t.text,
+            other => panic!("unexpected content {other:?}"),
+        },
+        other => panic!("unexpected update {other:?}"),
+    }
+}
+
+fn event_text(event: &maestro_daemon::sidecar::LoggedEvent) -> &str {
+    let maestro_daemon::sidecar::PersistedEvent::Notification(notification) = &event.event else {
+        panic!("expected ACP notification")
+    };
+    text_of(notification)
+}
+
+#[test]
+fn append_assigns_line_position_as_seq_and_reads_back() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+
+    let mut log = store.open_events(id).expect("open");
+    assert_eq!(log.last_seq(), 0);
+    assert_eq!(log.append(note("a")).unwrap(), 1);
+    assert_eq!(log.append(note("b")).unwrap(), 2);
+    assert_eq!(log.append(note("c")).unwrap(), 3);
+    assert_eq!(log.last_seq(), 3);
+
+    let path = store.events_path_for(id);
+    assert!(path.ends_with(format!("{id}.events.jsonl")), "{path:?}");
+    let raw = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(raw.lines().count(), 3, "one object per line:\n{raw}");
+    for line in raw.lines() {
+        let v: Value = serde_json::from_str(line).expect("each line is one JSON object");
+        assert_eq!(v["sessionId"], "acp-1");
+    }
+
+    let all = store.read_events(id, EventCursor::Since(0), 100).unwrap();
+    assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 2, 3]);
+    assert_eq!(
+        all.iter().map(event_text).collect::<Vec<_>>(),
+        vec!["a", "b", "c"]
+    );
+}
+
+#[test]
+fn since_reads_forward_and_before_reads_backward_with_limit() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let mut log = store.open_events(id).unwrap();
+    for i in 1..=6 {
+        log.append(note(&format!("n{i}"))).unwrap();
+    }
+
+    // `since` is exclusive: what a client that already holds seq 2 needs.
+    let fwd = store.read_events(id, EventCursor::Since(2), 3).unwrap();
+    assert_eq!(fwd.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![3, 4, 5]);
+    // Past the end: nothing, not an error.
+    assert!(store
+        .read_events(id, EventCursor::Since(6), 3)
+        .unwrap()
+        .is_empty());
+
+    // `before` is exclusive and pages backward: the `limit` events closest
+    // to the cursor, still in ascending seq order.
+    let back = store
+        .read_events(id, EventCursor::Before(Some(5)), 2)
+        .unwrap();
+    assert_eq!(back.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![3, 4]);
+    // No cursor: the tail of the log, for a first paint.
+    let tail = store.read_events(id, EventCursor::Before(None), 2).unwrap();
+    assert_eq!(tail.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![5, 6]);
+    // Paging past the start runs out cleanly.
+    let start = store
+        .read_events(id, EventCursor::Before(Some(2)), 10)
+        .unwrap();
+    assert_eq!(start.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1]);
+    assert!(store
+        .read_events(id, EventCursor::Before(Some(1)), 10)
+        .unwrap()
+        .is_empty());
+}
+
+#[test]
+fn missing_log_reads_as_empty() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    assert!(store
+        .read_events(id, EventCursor::Since(0), 10)
+        .unwrap()
+        .is_empty());
+    assert!(store
+        .read_events(id, EventCursor::Before(None), 10)
+        .unwrap()
+        .is_empty());
+}
+
+#[test]
+fn malformed_lines_are_skipped_but_keep_their_seq() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let mut log = store.open_events(id).unwrap();
+    log.append(note("first")).unwrap();
+    drop(log);
+
+    // Garbage in the middle and a line that is JSON but not a notification.
+    let path = store.events_path_for(id);
+    let mut raw = std::fs::read_to_string(&path).unwrap();
+    raw.push_str("{not json\n");
+    raw.push_str("{\"unrelated\": true}\n");
+    std::fs::write(&path, raw).unwrap();
+    let mut log = store.open_events(id).unwrap();
+    assert_eq!(log.last_seq(), 3);
+    assert_eq!(log.append(note("fourth")).unwrap(), 4);
+
+    let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
+    assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 4]);
+    assert_eq!(event_text(&all[1]), "fourth");
+}
+
+#[test]
+fn truncated_last_line_still_opens_and_the_next_append_starts_a_fresh_line() {
+    // A hard kill mid-write leaves a partial line with no newline.
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let mut log = store.open_events(id).unwrap();
+    log.append(note("whole")).unwrap();
+    drop(log);
+
+    let path = store.events_path_for(id);
+    let mut raw = std::fs::read(&path).unwrap();
+    raw.extend_from_slice(br#"{"sessionId":"acp-1","update":{"sessionUpd"#);
+    std::fs::write(&path, &raw).unwrap();
+
+    // Reads: the partial line is skipped, nothing else is lost.
+    let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
+    assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1]);
+
+    // Reopening terminates the partial line so the next append does not
+    // glue onto it; the partial keeps a seq of its own.
+    let mut log = store.open_events(id).unwrap();
+    assert_eq!(log.last_seq(), 2);
+    assert_eq!(log.append(note("after")).unwrap(), 3);
+    let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
+    assert_eq!(all.iter().map(|e| e.seq).collect::<Vec<_>>(), vec![1, 3]);
+    assert_eq!(event_text(&all[1]), "after");
+    let raw = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(raw.lines().count(), 3, "{raw}");
+}
+
+#[test]
+fn delete_removes_the_event_log_and_load_all_ignores_it() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    store.write(&sample(id)).unwrap();
+    let mut log = store.open_events(id).unwrap();
+    log.append(note("x")).unwrap();
+    drop(log);
+    let legacy_approvals = dir.path().join(format!("{id}.approvals.jsonl"));
+    std::fs::write(&legacy_approvals, b"obsolete").unwrap();
+    assert!(store.events_path_for(id).exists());
+
+    let loaded = store.load_all().unwrap();
+    assert_eq!(loaded.len(), 1, "the .jsonl must not be read as a sidecar");
+
+    store.delete(id).unwrap();
+    assert!(!store.path_for(id).exists());
+    assert!(!store.events_path_for(id).exists());
+    assert!(!legacy_approvals.exists());
+    // Idempotent with the log already gone.
+    store.delete(id).unwrap();
+}
+
+#[test]
+fn approval_rows_share_event_cursors_with_legacy_acp_lines() {
+    let dir = TempDir::new().unwrap();
+    let store = SidecarStore::new(dir.path());
+    let id = Uuid::new_v4();
+    let legacy = serde_json::to_vec(&note("before")).unwrap();
+    std::fs::create_dir_all(dir.path()).unwrap();
+    std::fs::write(store.events_path_for(id), [legacy, b"\n".to_vec()].concat()).unwrap();
+
+    let mut log = store.open_events(id).unwrap();
+    assert_eq!(
+        log.append(PersistedEvent::Approval {
+            row: TranscriptRow {
+                id: "approval:secret".into(),
+                kind: TranscriptRowKind::Approval,
+                data: serde_json::json!({"tool": "bash"}),
+            },
+        })
+        .unwrap(),
+        2
+    );
+    assert_eq!(log.append(note("after")).unwrap(), 3);
+
+    let all = store.read_events(id, EventCursor::Since(0), 10).unwrap();
+    assert_eq!(
+        all.iter().map(|event| event.seq).collect::<Vec<_>>(),
+        [1, 2, 3]
+    );
+    assert!(matches!(all[1].event, PersistedEvent::Approval { .. }));
+    assert_eq!(event_text(&all[0]), "before");
+    assert_eq!(event_text(&all[2]), "after");
+
+    let since = store.read_events(id, EventCursor::Since(1), 1).unwrap();
+    assert_eq!(since[0].seq, 2);
+    let before = store
+        .read_events(id, EventCursor::Before(Some(3)), 1)
+        .unwrap();
+    assert_eq!(before[0].seq, 2);
+}

crates/maestro-daemon/tests/worktree.rs

@@ -405,8 +405,10 @@ fn run_git(dir: &std::path::Path, args: &[&str]) {
     );
 }
 
+/// 49ab7e9: a new-branch add onto a name that already exists suffixes the
+/// branch (and so the directory) instead of failing, per docs/WORKTREES.md.
 #[test]
-fn add_fails_when_branch_already_exists() {
+fn add_new_suffixes_when_branch_already_exists() {
     let repo_dir = TempDir::new().unwrap();
     let repo = repo_dir.path().to_path_buf();
     init_repo(&repo);
@@ -423,9 +425,9 @@ fn add_fails_when_branch_already_exists() {
     let wt_root = TempDir::new().unwrap();
     let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let err = mgr.add_new(&repo, "feat/dup").unwrap_err();
-    let msg = format!("{err}");
-    assert!(msg.contains("git exited"), "{msg}");
+    let path = mgr.add_new(&repo, "feat/dup").unwrap();
+    assert!(path.ends_with("feat/dup-2"), "{}", path.display());
+    assert!(path.is_dir());
 }
 
 /// The project picker lists linked worktrees as pickable rows, so `base_repo`

crates/maestro-e2e/Cargo.toml

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

crates/maestro-e2e/src/daemon.rs

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

crates/maestro-e2e/tests/e2e.rs

@@ -15,7 +15,7 @@ use std::time::{Duration, Instant};
 use futures_util::{SinkExt, StreamExt};
 use maestro_e2e::util::wait_for_async;
 use maestro_e2e::{Daemon, TestClient};
-use maestro_protocol::{CreateSessionRequest, WorktreeSpec};
+use maestro_protocol::{CreateSessionRequest, SessionStatus, SessionView, WorktreeSpec};
 use tempfile::TempDir;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
@@ -27,6 +27,7 @@ async fn bring_up() -> (Daemon, TestClient) {
 
 fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
     CreateSessionRequest {
+        view: Default::default(),
         cwd: cwd.to_path_buf(),
         command: command.into(),
         env: HashMap::new(),
@@ -35,6 +36,61 @@ fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
     }
 }
 
+struct FakeAcp {
+    _dir: TempDir,
+    env: HashMap<String, String>,
+}
+
+fn fake_acp(log: &std::path::Path) -> FakeAcp {
+    let dir = tempfile::tempdir().expect("fake adapter dir");
+    let adapter = dir.path().join("claude-code-acp");
+    std::fs::copy(
+        concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../maestro-acp/tests/fake_acp_agent.py"
+        ),
+        &adapter,
+    )
+    .expect("copy fake adapter");
+    let mut permissions = std::fs::metadata(&adapter)
+        .expect("adapter metadata")
+        .permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        permissions.set_mode(0o755);
+    }
+    std::fs::set_permissions(&adapter, permissions).expect("make fake adapter executable");
+    let env = HashMap::from([
+        (
+            "PATH".into(),
+            format!(
+                "{}:{}",
+                dir.path().display(),
+                std::env::var("PATH").unwrap_or_default()
+            ),
+        ),
+        ("FAKE_ACP_LOG".into(), log.to_string_lossy().into_owned()),
+    ]);
+    FakeAcp { _dir: dir, env }
+}
+
+fn fake_acp_pid(log: &std::path::Path) -> Option<u32> {
+    std::fs::read_to_string(log).ok()?.lines().find_map(|line| {
+        line.strip_prefix("start pid=")?
+            .split(' ')
+            .next()?
+            .parse()
+            .ok()
+    })
+}
+
+fn pid_alive(pid: u32) -> bool {
+    std::fs::read_to_string(format!("/proc/{pid}/stat"))
+        .map(|stat| !stat.contains(") Z "))
+        .unwrap_or(false)
+}
+
 /// A worktree spec built through its wire shape. The daemon and clients ship
 /// together (#87 dropped `cleanup_on_kill` from the struct), so the JSON
 /// object carries only the fields the lifecycle actually honours.
@@ -49,6 +105,7 @@ fn worktree_spec(base_repo: &std::path::Path, branch: &str, create_branch: bool)
 /// Spawn request carrying a worktree spec against `base`.
 fn worktree_req(base: &std::path::Path, branch: &str, create_branch: bool) -> CreateSessionRequest {
     CreateSessionRequest {
+        view: Default::default(),
         cwd: base.to_path_buf(),
         command: "sleep 30".into(),
         env: HashMap::new(),
@@ -143,6 +200,7 @@ async fn kill_removes_clean_worktree() {
     init_repo(base.path());
 
     let req = CreateSessionRequest {
+        view: Default::default(),
         cwd: base.path().to_path_buf(),
         command: "sleep 30".into(),
         env: HashMap::new(),
@@ -196,6 +254,7 @@ async fn kill_refuses_worktree_with_uncommitted_changes() {
         .join("unsaved");
 
     let req = CreateSessionRequest {
+        view: Default::default(),
         cwd: base.path().to_path_buf(),
         command: "sleep 30".into(),
         env: HashMap::new(),
@@ -254,6 +313,7 @@ async fn spawn_on_existing_branch_checks_it_out() {
     run_git(&["branch", "feature/existing"], base.path());
 
     let req = CreateSessionRequest {
+        view: Default::default(),
         cwd: base.path().to_path_buf(),
         command: "sleep 30".into(),
         env: HashMap::new(),
@@ -323,8 +383,11 @@ async fn spawn_new_branch_creates_worktree_and_runs_in_it() {
     client.kill_session(s.id).await.expect("kill");
 }
 
-/// #66: a second spawn onto a branch that already has a worktree is rejected
-/// with a structured worktree error; the first worktree stays intact.
+/// #66: a second spawn onto an *existing* branch that already has a worktree
+/// is rejected with a structured worktree error; the first worktree stays
+/// intact. (A second `create_branch: true` spawn is a different case: 49ab7e9
+/// suffixes the new branch name instead, see
+/// `colliding_branch_name_gets_suffixed_too`.)
 #[tokio::test(flavor = "multi_thread")]
 async fn second_spawn_on_same_branch_is_rejected() {
     let (_daemon, client) = bring_up().await;
@@ -337,7 +400,7 @@ async fn second_spawn_on_same_branch_is_rejected() {
         .await
         .expect("first spawn");
     let dup = client
-        .spawn_session(&worktree_req(base.path(), "feature/dup", true))
+        .spawn_session(&worktree_req(base.path(), "feature/dup", false))
         .await;
     match dup {
         Err(maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. })) => {
@@ -497,6 +560,57 @@ async fn occupied_path_gets_suffixed_directory_and_both_worktrees_work() {
     );
 }
 
+/// A random handle can reuse the name of a branch left behind by an earlier,
+/// already-removed worktree — `git worktree add -b` refuses outright in that
+/// case, even though the directory is free. The daemon suffixes the branch
+/// itself (not just the directory) and both land on `-2`.
+#[tokio::test(flavor = "multi_thread")]
+async fn colliding_branch_name_gets_suffixed_too() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+
+    // No worktree directory in the way, but the branch already exists.
+    run_git(&["branch", "handle"], base.path());
+
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "handle", true))
+        .await
+        .expect("spawn onto a taken branch name");
+
+    let suffixed = base.path().join("worktrees").join("handle-2");
+    assert_eq!(
+        s.cwd, suffixed,
+        "the directory must follow the suffixed branch name"
+    );
+    assert!(suffixed.is_dir());
+
+    let registrations = git_worktree_list(base.path());
+    assert!(
+        registrations.iter().any(|l| l.contains("handle-2")),
+        "the -2 branch's worktree must be registered: {registrations:?}"
+    );
+
+    let branches = String::from_utf8(
+        std::process::Command::new("git")
+            .arg("-C")
+            .arg(base.path())
+            .args(["branch", "--list"])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        branches.contains("handle-2"),
+        "the branch itself must be named handle-2: {branches}"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+}
+
 /// #77/#88: the target path holds a plain directory the daemon never made and
 /// git has never heard of. The daemon neither adopts it nor errors — it builds
 /// beside it and leaves every byte of it alone.
@@ -703,6 +817,7 @@ async fn natural_exit_settles_dirty_and_pristine_worktrees_differently() {
 
     let _dirty = client
         .spawn_session(&CreateSessionRequest {
+            view: Default::default(),
             cwd: dirty_repo.path().to_path_buf(),
             command: "sh -c 'echo unsaved > scratch.txt'".into(),
             env: HashMap::new(),
@@ -751,6 +866,7 @@ async fn natural_exit_settles_dirty_and_pristine_worktrees_differently() {
 
 fn create_req_cmd(cwd: &std::path::Path, command: &str, branch: &str) -> CreateSessionRequest {
     CreateSessionRequest {
+        view: Default::default(),
         cwd: cwd.to_path_buf(),
         command: command.into(),
         env: HashMap::new(),
@@ -934,6 +1050,66 @@ async fn daemon_restart_recovers_session() {
     client.kill_session(s.id).await.expect("kill");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn sigterm_stops_structured_child_before_events_ws_drains() {
+    let (mut daemon, client) = bring_up().await;
+    let cwd = TempDir::new().unwrap();
+    let log = cwd.path().join("fake-acp.log");
+    let fake = fake_acp(&log);
+    let session = client
+        .spawn_session(&CreateSessionRequest {
+            view: SessionView::Structured,
+            cwd: cwd.path().to_path_buf(),
+            command: "claude".into(),
+            env: fake.env.clone(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("spawn structured session");
+    let ws_url = daemon.client().events_url().expect("events URL");
+    let (_events_ws, _) = tokio_tungstenite::connect_async(ws_url)
+        .await
+        .expect("events WS handshake");
+    wait_for_async("fake ACP starts", Duration::from_secs(5), || {
+        let log = log.clone();
+        async move { fake_acp_pid(&log).is_some() }
+    })
+    .await;
+    let pid = fake_acp_pid(&log).expect("fake ACP pid");
+
+    daemon.send_sigterm();
+
+    wait_for_async(
+        "fake ACP exits after SIGTERM",
+        Duration::from_secs(5),
+        || async { !pid_alive(pid) },
+    )
+    .await;
+    let sidecar_path = daemon
+        .state_dir()
+        .join("sessions")
+        .join(format!("{}.json", session.id));
+    wait_for_async(
+        "dead structured session sidecar",
+        Duration::from_secs(5),
+        || {
+            let sidecar_path = sidecar_path.clone();
+            async move {
+                std::fs::read(&sidecar_path)
+                    .ok()
+                    .and_then(|json| {
+                        serde_json::from_slice::<maestro_protocol::Session>(&json).ok()
+                    })
+                    .is_some_and(|saved| saved.status == SessionStatus::Dead)
+            }
+        },
+    )
+    .await;
+
+    daemon.stop();
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn concurrent_spawns_each_get_unique_ids() {
     let (_daemon, client) = bring_up().await;

crates/maestro-hooks/src/lib.rs

@@ -1,4 +1,4 @@
-//! Claude Code activity hook (#106).
+//! Agent activity hook (#106).
 //!
 //! Two halves, both shared by the `maestro hooks install` CLI subcommand and
 //! the daemon's first-start auto-install:
@@ -6,28 +6,40 @@
 //! * [`HOOK_SCRIPT`] — the hook itself, written to disk at install time. It
 //!   posts an [`ActivityState`](maestro-protocol) to
 //!   `$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity` (#105). The same
-//!   global hook runs in every Claude Code session on the machine, so it exits
+//!   global hook runs in every agent session on the machine, so it exits
 //!   0 and silently when either #103 env var is unset, and it never lets a
 //!   daemon failure escape (short curl timeout, status ignored).
-//! * [`install`] — idempotent registration of that script in
-//!   `~/.claude/settings.json`. Only entries maestro itself wrote (identified
-//!   by [`HOOK_MARKER`]) are touched; every other hook and every other field
-//!   in the file is preserved verbatim.
+//! * [`install`] — idempotent registration of that script in one [`Target`]'s
+//!   hook file. Only entries maestro itself wrote (identified by
+//!   [`HOOK_MARKER`]) are touched; every other hook and every other field in
+//!   the file is preserved verbatim.
+//!
+//! One script serves every [`Target`]: Claude Code and Codex read the same
+//! `{"hooks": {Event: [{"hooks": [{"type": "command", "command": …}]}]}}`
+//! shape and hand the hook the same JSON on stdin. Only the file's location
+//! and the event set differ.
 
 use std::path::Path;
 
 /// Marker substring every maestro-installed hook command carries. The
 /// installer rewrites or removes exactly these entries — nothing else in the
 /// user's settings file.
+///
+/// It still says `claude` although the script now serves every [`Target`]:
+/// the marker is how an install from an older maestro is recognised, and
+/// renaming it would orphan every entry already on disk.
 pub const HOOK_MARKER: &str = "maestro-claude-hook";
 
-/// File name of the installed script (carries [`HOOK_MARKER`]).
+/// File name of the installed script (carries [`HOOK_MARKER`]). One script
+/// for every [`Target`] — see the note on [`HOOK_MARKER`] for the name.
 pub const SCRIPT_FILE_NAME: &str = "maestro-claude-hook.sh";
 
-/// Hook events installed only with the `haiku-autoname` feature (#131).
-/// `UserPromptSubmit` carries the prompt the user just submitted; the script
-/// forwards the whole payload to `/api/sessions/:id/prompt`, which names a
-/// still-provisionally-named session after its first one.
+/// Hook events installed only with the `haiku-autoname` feature (#131), for
+/// every [`Target`] — Claude Code and Codex both spell the event
+/// `UserPromptSubmit` and both put the submitted text in the payload's
+/// `prompt`. The script forwards the whole payload to
+/// `/api/sessions/:id/prompt`, which names a still-provisionally-named
+/// session after its first one.
 #[cfg(feature = "haiku-autoname")]
 pub const PROMPT_EVENTS: [(&str, &str); 1] = [("UserPromptSubmit", "Prompt")];
 
@@ -43,7 +55,7 @@ pub const PROMPT_EVENTS: [(&str, &str); 0] = [];
 /// Claude Code's own name for "the turn ended on an API error"; there is no
 /// failure signal in `Stop` or `SessionEnd` payloads, so those never report
 /// `Error`.
-pub const HOOK_EVENTS: [(&str, &str); 5] = [
+pub const CLAUDE_EVENTS: [(&str, &str); 5] = [
     // Tool starting: the agent is demonstrably producing work, even if the
     // tool itself runs for minutes.
     ("PreToolUse", "Active"),
@@ -58,17 +70,86 @@ pub const HOOK_EVENTS: [(&str, &str); 5] = [
     ("StopFailure", "Error"),
 ];
 
+/// Codex hook event → `ActivityState` spelling posted to the daemon.
+///
+/// Codex's event set is close to Claude Code's but not identical: a pending
+/// approval arrives as `PermissionRequest` rather than `Notification`, and
+/// there is no `StopFailure`, so a codex session never reports `Error`.
+pub const CODEX_EVENTS: [(&str, &str); 4] = [
+    ("PreToolUse", "Active"),
+    ("PostToolUse", "Active"),
+    // Codex is blocked on the operator approving a tool call.
+    ("PermissionRequest", "AwaitingInput"),
+    ("Stop", "AwaitingInput"),
+];
+
+/// An agent whose hook file maestro writes into.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Target {
+    /// `~/.claude/settings.json`.
+    ClaudeCode,
+    /// `~/.codex/hooks.json`. Codex asks the operator to trust a hook it has
+    /// not seen before, so an install here does nothing until they approve it
+    /// once inside codex — maestro never writes that approval itself.
+    Codex,
+}
+
+impl Target {
+    /// Every target an install covers. Both files are written whether or not
+    /// the agent is on the machine: an unused hook file costs nothing, and
+    /// the alternative is a session spawned after the daemon started missing
+    /// the hook because its agent arrived later.
+    pub const ALL: [Target; 2] = [Target::ClaudeCode, Target::Codex];
+
+    /// How the target is named in logs and CLI output.
+    pub fn label(self) -> &'static str {
+        match self {
+            Target::ClaudeCode => "claude-code",
+            Target::Codex => "codex",
+        }
+    }
+
+    /// The file this target's hook entries are registered in, under `home`.
+    pub fn settings_path(self, home: &Path) -> std::path::PathBuf {
+        match self {
+            Target::ClaudeCode => home.join(".claude/settings.json"),
+            Target::Codex => home.join(".codex/hooks.json"),
+        }
+    }
+
+    /// The activity events this target emits.
+    pub fn activity_events(self) -> &'static [(&'static str, &'static str)] {
+        match self {
+            Target::ClaudeCode => &CLAUDE_EVENTS,
+            Target::Codex => &CODEX_EVENTS,
+        }
+    }
+
+    /// Every event installed for this target: its activity events plus, with
+    /// `haiku-autoname` on, the prompt event both agents spell the same way.
+    pub fn events(self) -> impl Iterator<Item = (&'static str, &'static str)> {
+        self.activity_events()
+            .iter()
+            .chain(PROMPT_EVENTS.iter())
+            .copied()
+    }
+}
+
 /// The shipped hook script. POSIX sh so any `/bin/sh` works.
 pub const HOOK_SCRIPT: &str = r#"#!/bin/sh
-# Installed by maestro (#106): report Claude Code activity to its daemon.
-# Exits silently unless running inside a session maestro spawned (#103 env).
+# Installed by maestro (#106): report agent activity to its daemon.
+# One script for every agent maestro installs hooks into; the state to post
+# is chosen by the caller, so the two event sets differ only in what is
+# registered where. Exits silently unless running inside a session maestro
+# spawned (#103 env).
 # Event -> ActivityState mapping:
-#   PreToolUse    -> Active         (tool started; agent is working)
-#   PostToolUse   -> Active         (tool finished)
-#   Notification  -> AwaitingInput  (permission / idle notice)
-#   Stop          -> AwaitingInput  (turn ended; waiting on the user)
-#   StopFailure   -> Error          (turn ended on an API error)
-#   Prompt        -> the payload is forwarded to the prompt route (#131)
+#   PreToolUse         -> Active         (tool started; agent is working)
+#   PostToolUse        -> Active         (tool finished)
+#   Notification       -> AwaitingInput  (claude code: permission / idle)
+#   PermissionRequest  -> AwaitingInput  (codex: waiting on an approval)
+#   Stop               -> AwaitingInput  (turn ended; waiting on the user)
+#   StopFailure        -> Error          (claude code: turn ended on an error)
+#   Prompt             -> the payload is forwarded to the prompt route (#131)
 state="$1"
 [ -n "$MAESTRO_SESSION_ID" ] || exit 0
 [ -n "$MAESTRO_URL" ] || exit 0
@@ -115,34 +196,29 @@ pub fn script_path(home: &Path) -> std::path::PathBuf {
     home.join(".local/share/maestro").join(SCRIPT_FILE_NAME)
 }
 
-/// The user-level Claude Code settings file for a given home directory.
-pub fn settings_path(home: &Path) -> std::path::PathBuf {
-    home.join(".claude/settings.json")
-}
-
-/// Whether `settings_path` already carries a maestro hook (#106). Presence
-/// only: an install from an older release answers `true` even when it is
-/// missing events this build ships — see [`is_current`].
+/// Whether the file at `settings_path` already carries a maestro hook
+/// (#106). Presence only: an install from an older release answers `true`
+/// even when it is missing events this build ships — see [`is_current`].
 pub fn is_installed(settings_path: &Path) -> bool {
     settings_json(settings_path)
         .map(|root| find_maestro_commands(&root).next().is_some())
         .unwrap_or(false)
 }
 
-/// Whether what is on disk is what this build ships: the script at
-/// `script_path` byte-for-byte, and exactly one settings entry per event in
-/// [`HOOK_EVENTS`] and [`PROMPT_EVENTS`], pointing at that script.
+/// Whether what is on disk is what this build ships for `target`: the script
+/// at `script_path` byte-for-byte, and exactly one settings entry per one of
+/// the target's [`Target::events`], pointing at that script.
 ///
-/// This is the upgrade question. A maestro that gains an event — #131 added
-/// `UserPromptSubmit` long after #106 had installed itself — leaves every
-/// existing user with a present but incomplete install, which
-/// [`is_installed`] cannot tell apart from a current one.
-pub fn is_current(settings_path: &Path, script_path: &Path) -> bool {
+/// This is the upgrade question, asked per [`Target`]. A maestro that gains
+/// an event — #131 added `UserPromptSubmit` long after #106 had installed
+/// itself — leaves every existing user with a present but incomplete
+/// install, which [`is_installed`] cannot tell apart from a current one.
+pub fn is_current(target: Target, settings_path: &Path, script_path: &Path) -> bool {
     if std::fs::read_to_string(script_path).ok().as_deref() != Some(HOOK_SCRIPT) {
         return false;
     }
     settings_json(settings_path)
-        .map(|root| maestro_entries(&root) == expected_entries(script_path))
+        .map(|root| maestro_entries(&root) == expected_entries(target, script_path))
         .unwrap_or(false)
 }
 
@@ -173,14 +249,13 @@ fn maestro_entries(root: &serde_json::Value) -> Vec<(String, String)> {
     found
 }
 
-/// What [`install`] writes for `script_path`, in the same shape.
-fn expected_entries(script_path: &Path) -> Vec<(String, String)> {
-    let mut want: Vec<(String, String)> = HOOK_EVENTS
-        .iter()
-        .chain(PROMPT_EVENTS.iter())
+/// What [`install`] writes for `target` and `script_path`, in the same shape.
+fn expected_entries(target: Target, script_path: &Path) -> Vec<(String, String)> {
+    let mut want: Vec<(String, String)> = target
+        .events()
         .map(|(event, state)| {
             (
-                (*event).to_string(),
+                event.to_string(),
                 format!("{} {state}", script_path.display()),
             )
         })
@@ -207,28 +282,40 @@ pub fn write_script(path: &Path) -> Result<(), HooksError> {
     Ok(())
 }
 
-/// Install the full hook setup for `home`: write the script under
-/// `.local/share/maestro/` and register it in `.claude/settings.json`.
+/// Install the full hook setup for one target under `home`: write the script
+/// under `.local/share/maestro/` and register it in the target's hook file.
 /// Idempotent; returns whether anything changed on disk.
-pub fn install_for_home(home: &Path) -> Result<bool, HooksError> {
+pub fn install_target(target: Target, home: &Path) -> Result<bool, HooksError> {
     let script = script_path(home);
-    let settings = settings_path(home);
+    let settings = target.settings_path(home);
     // A script left over from an older release counts as a change even when
     // the settings entries pointing at it are already right.
-    let changed = !is_current(&settings, &script);
+    let changed = !is_current(target, &settings, &script);
     write_script(&script)?;
-    install(&settings, &script)?;
+    install(target, &settings, &script)?;
     Ok(changed)
 }
 
-/// Register the hook command for every event in [`HOOK_EVENTS`] in the
-/// settings file at `settings_path`. Idempotent: existing maestro entries are
-/// updated in place wherever they sit, stale ones removed, duplicates folded;
-/// every non-maestro entry and every unrelated top-level field survives.
+/// Install for every [`Target::ALL`], reporting each one separately. One
+/// target failing — an unwritable file, unparseable JSON — never stops the
+/// others: an agent whose hook could not be written is one agent without
+/// activity reporting, not a failed install.
+pub fn install_for_home(home: &Path) -> Vec<(Target, Result<bool, HooksError>)> {
+    Target::ALL
+        .iter()
+        .map(|&target| (target, install_target(target, home)))
+        .collect()
+}
+
+/// Register the hook command for every one of `target`'s [`Target::events`]
+/// in the settings file at `settings_path`. Idempotent: existing maestro
+/// entries are updated in place wherever they sit, stale ones removed,
+/// duplicates folded; every non-maestro entry and every unrelated top-level
+/// field survives.
 ///
 /// Never inspects or writes anywhere but `settings_path` — callers pass the
 /// user's real home or a temp one in tests, never a repository.
-pub fn install(settings_path: &Path, script_path: &Path) -> Result<(), HooksError> {
+pub fn install(target: Target, settings_path: &Path, script_path: &Path) -> Result<(), HooksError> {
     let mut root = settings_json(settings_path)?;
 
     // Strip every maestro entry wherever it currently sits, so an older
@@ -236,7 +323,7 @@ pub fn install(settings_path: &Path, script_path: &Path) -> Result<(), HooksErro
     strip_maestro_entries(&mut root);
 
     let hooks = ensure_object(&mut root, "hooks");
-    for (event, state) in HOOK_EVENTS.iter().chain(PROMPT_EVENTS.iter()).copied() {
+    for (event, state) in target.events() {
         let groups = ensure_array(hooks, event);
         let mut group = serde_json::Map::new();
         group.insert(

crates/maestro-hooks/src/tests.rs

@@ -1,15 +1,24 @@
 //! Tests for the shipped hook script (run as a real `/bin/sh` subprocess)
 //! and the settings-file installer. Everything happens under a temp `$HOME`;
-//! the developer's own `~/.claude/settings.json` is never touched.
+//! the developer's own `~/.claude/settings.json` and `~/.codex/hooks.json`
+//! are never touched.
 
 use std::io::{Read, Write};
 use std::process::{Command, Stdio};
 
 use super::*;
 
-/// How many commands one install writes: every activity event, plus the
-/// prompt event when `haiku-autoname` is on (#131).
-const INSTALLED_EVENTS: usize = HOOK_EVENTS.len() + PROMPT_EVENTS.len();
+/// How many commands one install writes for a target: its activity events,
+/// plus the prompt event when `haiku-autoname` is on (#131).
+fn installed_events(target: Target) -> usize {
+    target.events().count()
+}
+
+/// The Claude Code hook file under a temp home. Most installer tests only
+/// need one target, and this is the one they were written against.
+fn settings_path(home: &Path) -> std::path::PathBuf {
+    Target::ClaudeCode.settings_path(home)
+}
 
 fn sh(script: &str, args: &[&str], envs: &[(&str, &str)], payload: &[u8]) -> std::process::Output {
     let mut cmd = Command::new("/bin/sh");
@@ -70,7 +79,7 @@ fn owned_envs<'a>(envs: &'a [(&'static str, String)]) -> Vec<(&'static str, &'a
 /// exit 0, no output, stdin drained.
 #[test]
 fn script_exits_silently_without_maestro_env() {
-    for (event, _) in HOOK_EVENTS {
+    for (event, _) in CLAUDE_EVENTS {
         let out = sh(HOOK_SCRIPT, &[event], &[], br#"{"session_id":"x"}"#);
         assert!(out.status.success(), "{event:?}: {:?}", out.stderr);
         assert!(out.stdout.is_empty(), "{event:?}: {:?}", out.stdout);
@@ -103,7 +112,7 @@ fn script_posts_mapped_state_to_the_activity_endpoint() {
 /// Every event maps to the state the contract specifies.
 #[test]
 fn event_state_mapping_matches_the_contract() {
-    let map: std::collections::HashMap<&str, &str> = HOOK_EVENTS.into_iter().collect();
+    let map: std::collections::HashMap<&str, &str> = CLAUDE_EVENTS.into_iter().collect();
     assert_eq!(map["PreToolUse"], "Active");
     assert_eq!(map["PostToolUse"], "Active");
     assert_eq!(map["Notification"], "AwaitingInput");
@@ -203,10 +212,10 @@ fn fresh_install_registers_every_event() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
     write_script(&script_path(home)).unwrap();
-    install(&settings_path(home), &script_path(home)).unwrap();
+    install(Target::ClaudeCode, &settings_path(home), &script_path(home)).unwrap();
 
     let cmds = installed_commands(&settings_path(home));
-    assert_eq!(cmds.len(), INSTALLED_EVENTS);
+    assert_eq!(cmds.len(), installed_events(Target::ClaudeCode));
     let joined = cmds.join("\n");
     assert_eq!(joined.matches("Active").count(), 2);
     assert!(joined.contains("Error"));
@@ -221,15 +230,15 @@ fn fresh_install_registers_every_event() {
 fn install_is_idempotent() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install(&settings_path(home), &script_path(home)).unwrap();
+    install(Target::ClaudeCode, &settings_path(home), &script_path(home)).unwrap();
     let once = std::fs::read_to_string(settings_path(home)).unwrap();
 
-    install(&settings_path(home), &script_path(home)).unwrap();
+    install(Target::ClaudeCode, &settings_path(home), &script_path(home)).unwrap();
     let twice = std::fs::read_to_string(settings_path(home)).unwrap();
     assert_eq!(once, twice);
     assert_eq!(
         installed_commands(&settings_path(home)).len(),
-        INSTALLED_EVENTS
+        installed_events(Target::ClaudeCode)
     );
 }
 
@@ -257,12 +266,12 @@ fn install_updates_an_older_maestro_hook_in_place() {
         .path()
         .join(".local/share/maestro")
         .join(SCRIPT_FILE_NAME);
-    install(&settings, &new_script).unwrap();
+    install(Target::ClaudeCode, &settings, &new_script).unwrap();
 
     let cmds = installed_commands(&settings);
     assert_eq!(
         cmds.len(),
-        INSTALLED_EVENTS,
+        installed_events(Target::ClaudeCode),
         "old entry replaced, not kept: {cmds:?}"
     );
     assert!(!cmds.iter().any(|c| c == old_script));
@@ -298,7 +307,7 @@ fn install_preserves_foreign_hooks_and_removes_stale_maestro_ones() {
         .path()
         .join(".local/share/maestro")
         .join(SCRIPT_FILE_NAME);
-    install(&settings, &new_script).unwrap();
+    install(Target::ClaudeCode, &settings, &new_script).unwrap();
 
     let root: serde_json::Value =
         serde_json::from_str(&std::fs::read_to_string(&settings).unwrap()).unwrap();
@@ -311,7 +320,7 @@ fn install_preserves_foreign_hooks_and_removes_stale_maestro_ones() {
     let cmds = installed_commands(&settings);
     assert_eq!(
         cmds.iter().filter(|c| c.contains(HOOK_MARKER)).count(),
-        INSTALLED_EVENTS,
+        installed_events(Target::ClaudeCode),
         "{cmds:?}"
     );
 }
@@ -321,9 +330,15 @@ fn install_preserves_foreign_hooks_and_removes_stale_maestro_ones() {
 fn is_installed_tracks_reality() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    assert!(!is_installed(&settings_path(home)));
-    install_for_home(home).unwrap();
-    assert!(is_installed(&settings_path(home)));
+    for target in Target::ALL {
+        assert!(!is_installed(&target.settings_path(home)));
+    }
+    for (_, result) in install_for_home(home) {
+        result.unwrap();
+    }
+    for target in Target::ALL {
+        assert!(is_installed(&target.settings_path(home)));
+    }
 }
 
 /// The full home-level install leaves the script executable.
@@ -331,7 +346,9 @@ fn is_installed_tracks_reality() {
 fn install_for_home_writes_an_executable_script() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install_for_home(home).unwrap();
+    for (_, result) in install_for_home(home) {
+        result.unwrap();
+    }
     #[cfg(unix)]
     {
         use std::os::unix::fs::PermissionsExt;
@@ -350,7 +367,7 @@ fn install_for_home_writes_an_executable_script() {
 fn install_registers_the_prompt_event() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install(&settings_path(home), &script_path(home)).unwrap();
+    install(Target::ClaudeCode, &settings_path(home), &script_path(home)).unwrap();
 
     let root: serde_json::Value =
         serde_json::from_str(&std::fs::read_to_string(settings_path(home)).unwrap()).unwrap();
@@ -367,7 +384,7 @@ fn install_registers_the_prompt_event() {
 fn install_registers_no_prompt_event_without_the_feature() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install(&settings_path(home), &script_path(home)).unwrap();
+    install(Target::ClaudeCode, &settings_path(home), &script_path(home)).unwrap();
 
     let root: serde_json::Value =
         serde_json::from_str(&std::fs::read_to_string(settings_path(home)).unwrap()).unwrap();
@@ -436,8 +453,12 @@ fn the_script_posts_a_prompt_payload_unchanged() {
 fn is_current_rejects_an_install_missing_an_event() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install_for_home(home).unwrap();
-    assert!(is_current(&settings_path(home), &script_path(home)));
+    install_target(Target::ClaudeCode, home).unwrap();
+    assert!(is_current(
+        Target::ClaudeCode,
+        &settings_path(home),
+        &script_path(home)
+    ));
 
     // Drop one event, as an older install would have left the file.
     let mut root: serde_json::Value =
@@ -450,7 +471,11 @@ fn is_current_rejects_an_install_missing_an_event() {
     .unwrap();
 
     assert!(is_installed(&settings_path(home)));
-    assert!(!is_current(&settings_path(home), &script_path(home)));
+    assert!(!is_current(
+        Target::ClaudeCode,
+        &settings_path(home),
+        &script_path(home)
+    ));
 }
 
 /// A settings file that is complete but points at a script from an older
@@ -459,9 +484,13 @@ fn is_current_rejects_an_install_missing_an_event() {
 fn is_current_rejects_a_stale_script() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    install_for_home(home).unwrap();
+    install_target(Target::ClaudeCode, home).unwrap();
     std::fs::write(script_path(home), "#!/bin/sh\nexit 0\n").unwrap();
-    assert!(!is_current(&settings_path(home), &script_path(home)));
+    assert!(!is_current(
+        Target::ClaudeCode,
+        &settings_path(home),
+        &script_path(home)
+    ));
 }
 
 /// Nothing installed at all is not current.
@@ -469,18 +498,93 @@ fn is_current_rejects_a_stale_script() {
 fn is_current_rejects_a_missing_install() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    assert!(!is_current(&settings_path(home), &script_path(home)));
+    assert!(!is_current(
+        Target::ClaudeCode,
+        &settings_path(home),
+        &script_path(home)
+    ));
 }
 
-/// `install_for_home` reports a stale script as a change, even when the
+/// `install_target` reports a stale script as a change, even when the
 /// settings entries pointing at it already read correctly.
 #[test]
-fn install_for_home_reports_a_stale_script_as_a_change() {
+fn install_target_reports_a_stale_script_as_a_change() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
-    assert!(install_for_home(home).unwrap());
-    assert!(!install_for_home(home).unwrap());
+    assert!(install_target(Target::ClaudeCode, home).unwrap());
+    assert!(!install_target(Target::ClaudeCode, home).unwrap());
 
     std::fs::write(script_path(home), "#!/bin/sh\nexit 0\n").unwrap();
-    assert!(install_for_home(home).unwrap());
+    assert!(install_target(Target::ClaudeCode, home).unwrap());
+}
+
+/// Codex is hooked in its own file, with its own event set: the two agents
+/// share the script but not the events, so neither file carries the other's
+/// spellings (#131 follow-up — a codex session was never named because
+/// nothing installed its `UserPromptSubmit` hook).
+#[test]
+fn each_target_gets_its_own_file_and_events() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    for (_, result) in install_for_home(home) {
+        result.unwrap();
+    }
+
+    let claude = events_in(&Target::ClaudeCode.settings_path(home));
+    let codex = events_in(&Target::Codex.settings_path(home));
+    assert_eq!(
+        Target::Codex.settings_path(home),
+        home.join(".codex/hooks.json")
+    );
+
+    // Claude Code's failure signal has no codex equivalent, and codex's
+    // approval notice is spelled differently.
+    assert!(claude.contains(&"StopFailure".to_string()));
+    assert!(claude.contains(&"Notification".to_string()));
+    assert!(!codex.contains(&"StopFailure".to_string()));
+    assert!(!codex.contains(&"Notification".to_string()));
+    assert!(codex.contains(&"PermissionRequest".to_string()));
+
+    // Both report work and both report a finished turn.
+    for event in ["PreToolUse", "PostToolUse", "Stop"] {
+        assert!(claude.contains(&event.to_string()), "claude {event}");
+        assert!(codex.contains(&event.to_string()), "codex {event}");
+    }
+
+    assert_eq!(
+        installed_commands(&Target::Codex.settings_path(home)).len(),
+        installed_events(Target::Codex)
+    );
+}
+
+/// #131: a codex session names itself the same way a Claude Code one does —
+/// same event spelling, same script, same `Prompt` argument.
+#[cfg(feature = "haiku-autoname")]
+#[test]
+fn codex_reports_its_first_prompt_too() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    install_target(Target::Codex, home).unwrap();
+
+    let root: serde_json::Value =
+        serde_json::from_str(&std::fs::read_to_string(Target::Codex.settings_path(home)).unwrap())
+            .unwrap();
+    let cmd = root["hooks"]["UserPromptSubmit"][0]["hooks"][0]["command"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    assert!(cmd.ends_with(" Prompt"), "{cmd}");
+    assert!(cmd.contains(SCRIPT_FILE_NAME));
+}
+
+/// Every event name a settings file registers a maestro hook under.
+fn events_in(settings: &Path) -> Vec<String> {
+    serde_json::from_str::<serde_json::Value>(&std::fs::read_to_string(settings).unwrap())
+        .unwrap()
+        .get("hooks")
+        .and_then(|h| h.as_object())
+        .into_iter()
+        .flatten()
+        .map(|(event, _)| event.clone())
+        .collect()
 }

crates/maestro-protocol/src/client.rs

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

crates/maestro-protocol/src/display.rs

@@ -268,6 +268,7 @@ mod tests {
 
     fn session(cwd: &str) -> Session {
         Session {
+            view: Default::default(),
             id: Uuid::from_u128(1),
             cwd: PathBuf::from(cwd),
             command: "bash".into(),
@@ -284,6 +285,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 

crates/maestro-protocol/src/lib.rs

@@ -116,6 +116,33 @@ pub struct Session {
     /// sorts a never-focused session after every session that has one.
     #[serde(default)]
     pub last_focused_at: Option<DateTime<Utc>>,
+    /// Whether this session's process is a plain terminal (PTY bytes through
+    /// tmux) or a structured agent driven over ACP rows (#133). Fixed at
+    /// spawn time and never changes for the life of the session. Defaults to
+    /// `Terminal` on the wire so every existing client and payload from a
+    /// daemon that predates the field keeps working untouched.
+    #[serde(default)]
+    pub view: SessionView,
+    /// The ACP session id the `claude-code-acp` adapter handed back from
+    /// `session/new` (#134). Only a [`SessionView::Structured`] session has
+    /// one, and only once its handshake succeeded; a later respawn passes it
+    /// to `session/load` so the conversation continues (#135). Distinct from
+    /// the hook-reported Claude Code conversation id (#161): that one is what
+    /// `claude --resume` takes, this one is what the ACP adapter takes, and
+    /// the two are minted by different processes with different lifetimes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub acp_session_id: Option<String>,
+}
+
+/// A session's process shape (#133): a plain terminal, or a structured agent
+/// driven over ACP rows. Chosen at spawn and immutable for the session's
+/// life. `Terminal` is the default — every sidecar and `CreateSessionRequest`
+/// written before this field existed meant a terminal session.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub enum SessionView {
+    #[default]
+    Terminal,
+    Structured,
 }
 
 /// Default for [`Session::last_activity_at`] when an older payload omits it.
@@ -129,9 +156,9 @@ pub enum SessionStatus {
     Dead,
 }
 
-/// Inferred session activity, orthogonal to [`SessionStatus`] (NAP-340). The
-/// daemon derives this from tmux pane state, PTY quiescence, and `/proc`
-/// inspection — never by parsing the terminal byte stream.
+/// Session activity, orthogonal to [`SessionStatus`] (NAP-340). Terminal
+/// sessions use pane/process inference and agent reports; structured sessions
+/// use their ACP turn lifecycle (docs/SIDEBAR.md).
 ///
 /// Deserializes leniently (#110, SIDEBAR.md Precedence): an unknown variant
 /// from a newer daemon becomes [`ActivityState::Idle`] instead of failing the
@@ -139,15 +166,14 @@ pub enum SessionStatus {
 /// forgiven.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Default)]
 pub enum ActivityState {
-    /// Producing output, or the foreground process is busy.
+    /// Producing output, the foreground process is busy, or an ACP turn is active.
     Active,
     /// Foreground process alive but quiescent. The forward-compatible default.
     #[default]
     Idle,
-    /// Blocked on a `read()` from the pty — waiting on the user.
+    /// Blocked on terminal input or waiting for an ACP approval.
     AwaitingInput,
-    /// The agent running in the session reported a failure (#102). Never
-    /// inferred by the daemon; only set when an agent reports it (#105).
+    /// An agent reported a failure, or a structured session/turn failed.
     Error,
 }
 
@@ -352,6 +378,11 @@ pub struct CreateSessionRequest {
     pub metadata: HashMap<String, Value>,
     #[serde(default)]
     pub worktree: Option<WorktreeSpec>,
+    /// The process shape to spawn (#133). Defaulted so every existing client
+    /// and `curl` against the API keeps requesting a `Terminal` session
+    /// untouched.
+    #[serde(default)]
+    pub view: SessionView,
 }
 
 /// Result of `GET /api/dirs`: the immediate subdirectories of one directory.
@@ -723,6 +754,132 @@ pub enum CatalogEvent {
     },
 }
 
+// ---------------------------------------------------------------------------
+// Structured-session projections
+// ---------------------------------------------------------------------------
+
+/// One client-neutral item in a structured session transcript.
+///
+/// `data` preserves the ACP payload without committing clients to an ACP
+/// dependency. Rendering choices, including markdown and tool-card treatment,
+/// stay with the client.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptRow {
+    /// Stable within one session, so later deltas can address this row.
+    pub id: String,
+    pub kind: TranscriptRowKind,
+    pub data: Value,
+}
+
+/// The semantic shape of a [`TranscriptRow`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TranscriptRowKind {
+    User,
+    AgentText,
+    AgentThought,
+    ToolCall,
+    ToolDiff,
+    Approval,
+    Plan,
+    Notice,
+}
+
+/// A complete transcript at a durable event-log position.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptSnapshot {
+    pub cursor: u64,
+    #[serde(default)]
+    pub rows: Vec<TranscriptRow>,
+}
+
+/// One durable, client-neutral replay step from a structured session.
+///
+/// Results are ordered by increasing `cursor`. `since` returns the first
+/// matching steps; `before` returns the final matching steps, still increasing.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct StructuredReplayEvent {
+    /// Durable ACP-log position represented by this projected step.
+    pub cursor: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transcript: Option<TranscriptDelta>,
+    pub state: ReducedState,
+}
+
+/// A change to a transcript row.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum TranscriptDelta {
+    Append { row: TranscriptRow },
+    Patch { row: TranscriptRow },
+    Remove { id: String },
+}
+
+/// Per-turn indicators derived from the ACP stream.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TurnState {
+    #[serde(default)]
+    pub responding: bool,
+    #[serde(default)]
+    pub thinking: bool,
+    #[serde(default)]
+    pub active_tool_calls: Vec<String>,
+}
+
+/// A whole-session view derived from ACP notifications.
+///
+/// Values whose shape ACP owns are carried as JSON so this wire protocol stays
+/// forward-compatible when ACP adds fields or variants.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ReducedState {
+    #[serde(default)]
+    pub turn: TurnState,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pending_approval: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub plan: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub usage: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub context: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mode: Option<String>,
+}
+
+/// Server messages sent over a structured-session WebSocket.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum StructuredEvent {
+    TranscriptSnapshot {
+        snapshot: TranscriptSnapshot,
+    },
+    ReducedState {
+        state: ReducedState,
+    },
+    ProjectionUpdate {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        transcript: Option<TranscriptDelta>,
+        state: ReducedState,
+    },
+}
+
+/// HTTP body for `POST /api/sessions/:id/structured/prompt`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct StructuredPromptRequest {
+    pub prompt: String,
+}
+
+/// Operator decision for a pending ACP permission request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StructuredApprovalDecision {
+    AllowOnce,
+    AllowForSession,
+    Deny,
+}
+
 // ---------------------------------------------------------------------------
 // Client ↔ Daemon control messages (text frames on the attach WS)
 // ---------------------------------------------------------------------------
@@ -862,6 +1019,8 @@ mod tests {
             current_cwd: Some(PathBuf::from("/home/naps62/projects/maestro/crates")),
             blocked_work: None,
             last_focused_at: None,
+            view: SessionView::Terminal,
+            acp_session_id: None,
         }
     }
 
@@ -1073,6 +1232,7 @@ mod tests {
                 branch: "feat/foo".into(),
                 create_branch: true,
             }),
+            view: SessionView::Terminal,
         };
         assert_eq!(req, round_trip(&req));
     }
@@ -1087,6 +1247,74 @@ mod tests {
         assert!(req.worktree.is_none());
         assert!(req.env.is_empty());
         assert!(req.metadata.is_empty());
+        assert_eq!(req.view, SessionView::Terminal);
+    }
+
+    #[test]
+    fn session_view_defaults_to_terminal_on_legacy_payload() {
+        // A pre-#133 daemon or client omits `view`; it must deserialize to
+        // `Terminal` rather than failing, and `Structured` round-trips.
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z"
+        });
+        let s: Session = serde_json::from_value(json).unwrap();
+        assert_eq!(s.view, SessionView::Terminal);
+
+        let mut structured = sample_session();
+        structured.view = SessionView::Structured;
+        assert_eq!(structured, round_trip(&structured));
+    }
+
+    #[test]
+    fn structured_projection_types_round_trip_and_default() {
+        let row = TranscriptRow {
+            id: "tool:read-1".into(),
+            kind: TranscriptRowKind::ToolCall,
+            data: serde_json::json!({"name": "vendor.read", "title": "Read"}),
+        };
+        let snapshot = TranscriptSnapshot {
+            cursor: 7,
+            rows: vec![row.clone()],
+        };
+        assert_eq!(snapshot, round_trip(&snapshot));
+        assert_eq!(
+            TranscriptDelta::Patch { row: row.clone() },
+            round_trip(&TranscriptDelta::Patch { row })
+        );
+
+        let state: ReducedState = serde_json::from_value(serde_json::json!({})).unwrap();
+        assert_eq!(state, ReducedState::default());
+        assert_eq!(
+            serde_json::to_value(TranscriptRowKind::AgentThought).unwrap(),
+            serde_json::json!("agent_thought")
+        );
+    }
+
+    #[test]
+    fn acp_session_id_defaults_to_none_and_round_trips() {
+        // A payload from before #134 carries no `acp_session_id`; it must
+        // read as `None`, stay off the wire while unset, and round-trip
+        // once the adapter has handed one back.
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z"
+        });
+        let s: Session = serde_json::from_value(json).unwrap();
+        assert_eq!(s.acp_session_id, None);
+        let serialized = serde_json::to_value(&s).unwrap();
+        assert!(serialized.get("acp_session_id").is_none());
+
+        let mut structured = sample_session();
+        structured.view = SessionView::Structured;
+        structured.acp_session_id = Some("sess_01HZX".into());
+        assert_eq!(structured, round_trip(&structured));
     }
 
     /// A client that predates the new/existing discriminator sends no

crates/maestro-protocol/src/routes.rs

@@ -71,6 +71,31 @@ pub fn attach(id: Uuid) -> String {
     format!("{API_PREFIX}/attach/{id}")
 }
 
+/// `WS /api/structured/:id` — transcript/state snapshots and live deltas.
+pub fn structured(id: Uuid) -> String {
+    format!("{API_PREFIX}/structured/{id}")
+}
+
+/// `GET /api/sessions/:id/structured/replay` — cursor-bounded ACP history.
+pub fn structured_replay(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/replay")
+}
+
+/// `POST /api/sessions/:id/structured/prompt` — send an ACP prompt.
+pub fn structured_prompt(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/prompt")
+}
+
+/// `POST /api/sessions/:id/structured/cancel` — cancel an ACP turn.
+pub fn structured_cancel(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/cancel")
+}
+
+/// `POST /api/sessions/:id/structured/approvals/:nonce` — answer ACP permission.
+pub fn structured_approval(id: Uuid, nonce: &str) -> String {
+    format!("{SESSIONS}/{id}/structured/approvals/{nonce}")
+}
+
 /// Axum-style patterns for the two parameterised routes, so the server
 /// registers the same paths [`session`] and [`attach`] build.
 pub mod patterns {
@@ -80,6 +105,11 @@ pub mod patterns {
     pub const SESSION_PROMPT: &str = "/api/sessions/:id/prompt";
     pub const SESSION_FOCUS: &str = "/api/sessions/:id/focus";
     pub const ATTACH: &str = "/api/attach/:id";
+    pub const STRUCTURED: &str = "/api/structured/:id";
+    pub const STRUCTURED_REPLAY: &str = "/api/sessions/:id/structured/replay";
+    pub const STRUCTURED_PROMPT: &str = "/api/sessions/:id/structured/prompt";
+    pub const STRUCTURED_CANCEL: &str = "/api/sessions/:id/structured/cancel";
+    pub const STRUCTURED_APPROVAL: &str = "/api/sessions/:id/structured/approvals/:nonce";
 }
 
 /// A daemon base URL that could not be turned into a WebSocket base.
@@ -129,6 +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::*;
@@ -178,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]
@@ -206,6 +245,22 @@ mod tests {
             attach(id()),
             "/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
         );
+        assert_eq!(
+            structured(id()),
+            "/api/structured/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
+        assert_eq!(
+            structured_replay(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/replay"
+        );
+        assert_eq!(
+            structured_prompt(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/prompt"
+        );
+        assert_eq!(
+            structured_cancel(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/structured/cancel"
+        );
         assert_eq!(
             attach_url("https://laptop.lan:7070", id()).unwrap(),
             "wss://laptop.lan:7070/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
@@ -240,6 +295,22 @@ mod tests {
             patterns::ATTACH.trim_end_matches(":id"),
             attach(id()).trim_end_matches(&id().to_string())
         );
+        assert_eq!(
+            patterns::STRUCTURED.trim_end_matches(":id"),
+            structured(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_REPLAY.trim_end_matches(":id/structured/replay"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_PROMPT.trim_end_matches(":id/structured/prompt"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::STRUCTURED_CANCEL.trim_end_matches(":id/structured/cancel"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
     }
 
     #[test]
@@ -258,5 +329,9 @@ mod tests {
             assert!(path.starts_with(API_PREFIX), "{path} escapes {API_PREFIX}");
         }
         assert!(attach(id()).starts_with(API_PREFIX));
+        assert!(structured(id()).starts_with(API_PREFIX));
+        assert!(structured_replay(id()).starts_with(API_PREFIX));
+        assert!(structured_prompt(id()).starts_with(API_PREFIX));
+        assert!(structured_cancel(id()).starts_with(API_PREFIX));
     }
 }

crates/maestro-testing/src/lib.rs

@@ -31,6 +31,7 @@ use uuid::Uuid;
 /// Build a plausible `Session` for a test to hand to [`MockDaemon::add_session`].
 pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
     Session {
+        view: Default::default(),
         id,
         cwd: cwd.into(),
         command: command.into(),
@@ -47,6 +48,7 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
         current_cwd: None,
         blocked_work: None,
         last_focused_at: None,
+        acp_session_id: None,
     }
 }
 

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,
@@ -1882,6 +2102,7 @@ mod tests {
             sessions: ids
                 .iter()
                 .map(|id| Session {
+                    view: Default::default(),
                     id: *id,
                     command: "bash".into(),
                     cwd: std::path::PathBuf::from("/"),
@@ -1898,6 +2119,7 @@ mod tests {
                     current_cwd: None,
                     blocked_work: None,
                     last_focused_at: None,
+                    acp_session_id: None,
                 })
                 .collect(),
         });
@@ -2063,6 +2285,7 @@ mod tests {
         let mut app = make_app();
         app.catalog.apply_event(CatalogEvent::Snapshot {
             sessions: vec![Session {
+                view: Default::default(),
                 id: sid,
                 command: "bash".into(),
                 cwd: std::path::PathBuf::from("/"),
@@ -2079,6 +2302,7 @@ mod tests {
                 current_cwd: None,
                 blocked_work: None,
                 last_focused_at: None,
+                acp_session_id: None,
             }],
         });
         app.dispatch(Action::SidebarNext);
@@ -2090,6 +2314,7 @@ mod tests {
         use chrono::Utc;
         use maestro_protocol::{Session, SessionStatus};
         Session {
+            view: Default::default(),
             id: sid,
             command: "bash".into(),
             cwd: cwd.into(),
@@ -2106,6 +2331,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 
@@ -2777,6 +3003,7 @@ mod tests {
         );
         app.dispatch(Action::OpenSpawnModal);
         let req = CreateSessionRequest {
+            view: Default::default(),
             cwd: std::path::PathBuf::from("/srv/work"),
             command: "bash".into(),
             env: Default::default(),
@@ -2798,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.
@@ -3195,6 +3469,7 @@ mod tests {
         use chrono::Utc;
         use maestro_protocol::{CatalogEvent, Session, SessionStatus};
         let make = |n: u128, name: &str, focused: Option<chrono::DateTime<Utc>>| Session {
+            view: Default::default(),
             id: Uuid::from_u128(n),
             command: "bash".into(),
             cwd: std::path::PathBuf::from("/"),
@@ -3214,6 +3489,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: focused,
+            acp_session_id: None,
         };
         let older = Utc::now() - chrono::Duration::seconds(60);
         app.catalog.apply_event(CatalogEvent::Snapshot {
@@ -3475,6 +3751,7 @@ mod tests {
         let sid = Uuid::from_u128(7);
         app.catalog.apply_event(CatalogEvent::Snapshot {
             sessions: vec![Session {
+                view: Default::default(),
                 id: sid,
                 command: "bash".into(),
                 cwd: std::path::PathBuf::from("/"),
@@ -3492,6 +3769,7 @@ mod tests {
                 current_cwd: None,
                 blocked_work: None,
                 last_focused_at: None,
+                acp_session_id: None,
             }],
         });
         app.dispatch(Action::KillHighlighted);
@@ -3511,6 +3789,7 @@ mod tests {
         };
         app.catalog.apply_event(CatalogEvent::Snapshot {
             sessions: vec![Session {
+                view: Default::default(),
                 id: sid,
                 command: "bash".into(),
                 cwd: std::path::PathBuf::from("/"),
@@ -3527,6 +3806,7 @@ mod tests {
                 current_cwd: None,
                 blocked_work: None,
                 last_focused_at: None,
+                acp_session_id: None,
             }],
         });
     }
@@ -3684,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/catalog.rs

@@ -207,6 +207,7 @@ mod tests {
 
     fn session(id: u128, command: &str) -> Session {
         Session {
+            view: Default::default(),
             id: Uuid::from_u128(id),
             command: command.into(),
             cwd: std::path::PathBuf::from("/tmp"),
@@ -223,6 +224,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 

crates/maestro-tui/src/command_bar.rs

@@ -793,6 +793,7 @@ mod tests {
 
     fn session(n: u128, command: &str) -> Session {
         Session {
+            view: Default::default(),
             id: Uuid::from_u128(n),
             cwd: PathBuf::from("/home/me/dev/api"),
             command: command.to_string(),
@@ -809,6 +810,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 

crates/maestro-tui/src/draft.rs

@@ -694,6 +694,7 @@ impl DraftPane {
         }
         let worktree = self.build_worktree()?;
         Ok(CreateSessionRequest {
+            view: Default::default(),
             cwd,
             command: command.to_string(),
             env: Default::default(),

crates/maestro-tui/src/fast_forward.rs

@@ -108,6 +108,7 @@ impl FastForwardDefaults {
             return None;
         }
         Some(CreateSessionRequest {
+            view: Default::default(),
             cwd: project.path.clone(),
             command: command.to_string(),
             env: Default::default(),

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

@@ -484,6 +484,7 @@ mod tests {
         let mut metadata = HashMap::new();
         metadata.insert("name".into(), serde_json::Value::String(name.into()));
         Session {
+            view: Default::default(),
             id: Uuid::from_u128(id),
             command: "bash".into(),
             cwd: std::path::PathBuf::from("/tmp"),
@@ -500,6 +501,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         }
     }
 
@@ -1250,6 +1252,7 @@ mod tests {
     #[test]
     fn falls_back_to_command_when_name_metadata_is_absent() {
         let s = Session {
+            view: Default::default(),
             id: Uuid::from_u128(1),
             command: "vim".into(),
             cwd: std::path::PathBuf::from("/tmp"),
@@ -1266,6 +1269,7 @@ mod tests {
             current_cwd: None,
             blocked_work: None,
             last_focused_at: None,
+            acp_session_id: None,
         };
         let sb = Sidebar {
             sessions: vec![s],

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/INSTALL.md

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

docs/RESTART.md

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

docs/SIDEBAR.md

@@ -231,7 +231,24 @@ cutover points land within one tick.
 
 ## Precedence
 
-An agent-reported `ActivityState` (#105) overrides the daemon's inference for
+### Activity source by session kind
+
+The daemon supplies one `activity` field to both clients, but its source depends
+on the session kind:
+
+| Session kind | Source |
+|---|---|
+| Terminal | The existing agent-report override and five-minute TTL, falling back to PTY quiescence, foreground process and `/proc` input-block inference. |
+| Structured | ACP state directly: a pending approval is `AwaitingInput`; otherwise an in-flight turn is `Active`; no turn is `Idle`. A failed turn or dead structured session is `Error`, and the next turn clears a failed-turn error. |
+
+Structured sessions never enter the terminal inference path and ignore activity
+reports inherited through agent hooks. They have no PTY whose output or blocked
+read could describe their state. This is a second source, not a replacement for
+the terminal source.
+
+### Terminal report override
+
+For terminal sessions, an agent-reported `ActivityState` (#105) overrides the daemon's inference for
 **five minutes** (the TTL is fixed by the daemon; re-reporting extends it).
 When the TTL expires, inference resumes and the session's reported detail —
 if any — clears with the report. Clients never blend the two: whichever source
@@ -250,6 +267,10 @@ Two rulings specific to a reported `Error` (#114):
   process changes do not clear it — only the agent itself may withdraw what
   the agent itself reported. Re-reporting `Error` extends the TTL rather than
   stacking reports.
+- **Only Claude Code reports `Error`.** Codex has no counterpart to
+  `StopFailure` in its hook event set, so a codex turn that ends on an API
+  error reports `AwaitingInput` and its card carries no error mark. A card
+  without the mark means "nothing reported a failure", not "nothing failed".
 
 If a client receives an `ActivityState` variant it does not know, it must not
 fail rendering: treat it as `Idle` (neutral/dim, line-2 rules apply as usual)
@@ -277,10 +298,10 @@ session is genuinely `Active` again — new work, not merely a refocus. Only
 after that fresh `Active` cycle does the *next* `AwaitingInput` glow again.
 Unfocusing and refocusing alone never re-arms it.
 
-This applies uniformly to `AwaitingInput` from either source — the daemon's
-own inference or an agent's report (#105) — since the rail draws them
-identically. It does not touch `Error`; that state's own TTL (below) is
-unrelated and unaffected by focus.
+This applies uniformly to `AwaitingInput` from terminal inference, an agent
+report (#105), or a structured session's pending approval, since the rail draws
+them identically. It does not touch `Error`; terminal reports keep their TTL,
+while a structured failed-turn error clears when the next turn starts.
 
 Each client reports its own pane's focus with `POST /api/sessions/:id/focus`
 (`{"focused": bool}`) whenever the pane it is showing changes — on attach, on
@@ -303,9 +324,10 @@ lands on the first row it was hiding. A highlight parked on a skipped row —
 reachable by clicking a folder header — still steps to its neighbour rather
 than jumping to the end of the list.
 
-The web client needs a chord to reach the list at all (`Ctrl+Shift+H`, and the
-same chord back): an attached terminal owns every plain keystroke. The TUI uses
-`ctrl-w h`.
+The web client needs a chord to reach the list at all (leader-`h` — `Ctrl+A h`
+by default — and the same chord back): an attached terminal owns every plain
+keystroke, and Escape is left to reach the pane's shell/app instead. The TUI
+uses `ctrl-w h`.
 
 Everything else is the same key on both clients:
 

docs/STRUCTURED-VIEW.md

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

docs/WORKTREES.md

@@ -35,10 +35,18 @@ The branch name is used verbatim as a relative path, so `feature/login` becomes
 back to a short hash of the branch.
 
 If that path exists, the daemon appends `-2`, then `-3`, and so on until it finds
-a free one. The suffix names the **directory only**. The branch is whatever was
-requested; a second worktree of the same branch is not what happens here, because
-git refuses to check the same branch out twice and the branch picker already
-marks branches that are checked out elsewhere.
+a free one.
+
+For a *new* branch (`create_branch: true`), the suffix goes on the branch name
+itself, and the directory follows since it is derived from the branch — a
+random handle can otherwise reuse the name of a branch some earlier, already
+removed worktree left behind, and `git worktree add -b` refuses outright even
+though the directory is free.
+
+For an *existing* branch (`create_branch: false`) the name must stay exact, so
+only the directory is suffixed — a second worktree of the same branch is not
+what happens here, because git refuses to check the same branch out twice and
+the branch picker already marks branches that are checked out elsewhere.
 
 ### The `worktree_root` override
 

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,24 +4,15 @@ import { Terminal } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
 
 import { attachWsUrl } from "./routes.js";
-import { FOCUS_SIDEBAR_EVENT } from "./catalog.js";
-import { CommandSet, defineCommands } from "./commands.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";
 
-// The pane's half of the command registry (#148): plain Escape hands the
-// keyboard back to the session list, the pair to the list's Tab.
-const paneKeys = new CommandSet(
-  defineCommands({
-    "pane.focusList": () => document.dispatchEvent(new CustomEvent(FOCUS_SIDEBAR_EVENT)),
-  }),
-  { preventDefault: false },
-);
+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. */
@@ -38,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. */
@@ -70,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 = {},
@@ -96,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>
@@ -221,15 +174,6 @@ export function createAttachConnection(
     }
   }
 
-  // Plain Escape hands the keyboard back to the session list instead of the
-  // shell/app. `false` tells xterm to skip its own handling of this event —
-  // which is also why the set doesn't `preventDefault`: swallowing here is
-  // xterm's return value, not the browser's.
-  term.attachCustomKeyEventHandler((e) => {
-    if (e.type !== "keydown") return true;
-    return !paneKeys.handle(e);
-  });
-
   // Touch scrolling: xterm's built-in touch handling is jittery (drags crawl a
   // line at a time and stall), so map finger drags ourselves. Two routes:
   //   • normal buffer  → term.scrollLines walks the scrollback.
@@ -470,6 +414,12 @@ export function createAttachConnection(
   const resizeDisp = term.onResize(({ cols, rows }) => {
     sendControl({ type: "Resize", cols, rows });
   });
+  // xterm has no built-in copy-on-select; mirror the selection to the
+  // clipboard ourselves (best-effort — insecure contexts lack the API).
+  const selectionDisp = term.onSelectionChange(() => {
+    const text = term.getSelection();
+    if (text) void navigator.clipboard?.writeText(text).catch(() => {});
+  });
 
   window.addEventListener("resize", onResize);
   const visual = window.visualViewport ?? null;
@@ -525,6 +475,7 @@ export function createAttachConnection(
       visual?.removeEventListener("resize", onResize);
       dataDisp.dispose();
       resizeDisp.dispose();
+      selectionDisp.dispose();
       releaseWebgl();
       try {
         ws.close();

web/src/catalog.ts

@@ -53,10 +53,6 @@ export function requestOpenCommandBar(): void {
  *  connection pool. */
 export const FOCUS_PANE_EVENT = "catalog-focus-pane";
 
-/** Ask the shell to hand the keyboard back to the session list — what Escape
- *  does when the pane's terminal is focused. Handled in main.ts. */
-export const FOCUS_SIDEBAR_EVENT = "catalog-focus-sidebar";
-
 /** Ask the shell to open the spawn modal seeded from an existing session
  *  ("Spawn similar"). Detail is the session being cloned. */
 export const SPAWN_SIMILAR_EVENT = "catalog-spawn-similar";

web/src/commands.test.ts

@@ -133,31 +133,28 @@ describe("CommandSet", () => {
     expect(run).toHaveBeenCalledTimes(2);
   });
 
-  it("keeps plain keys deaf inside a form field, and chorded ones live", () => {
+  it("keeps plain keys deaf inside a form field, and leader chords live from the pane", () => {
     const plain = vi.fn();
     const chorded = vi.fn();
     const set = new CommandSet(
-      defineCommands({ "spawn.open": plain, "focus.toggle": chorded }),
+      defineCommands({ "spawn.open": plain, "focus.toggle": chorded }, DEFAULT_LEADER),
+      { leader: DEFAULT_LEADER },
     );
     const input = el("<input>");
     expect(pressOn(set, input, "n")).toBe(false);
     expect(plain).not.toHaveBeenCalled();
-    expect(pressOn(set, input, "H", { ctrlKey: true, shiftKey: true })).toBe(true);
+    // focus.toggle hangs off the leader (#166): a plain, unmodified Escape is
+    // left for the pane's shell/app instead.
+    const terminal = el('<textarea class="xterm-helper-textarea"></textarea>');
+    pressOn(set, terminal, "a", { ctrlKey: true });
+    expect(pressOn(set, terminal, "h")).toBe(true);
     expect(chorded).toHaveBeenCalledTimes(1);
   });
 
-  it("keeps pane commands live inside the terminal's textarea", () => {
-    const run = vi.fn();
-    const set = new CommandSet(defineCommands({ "pane.focusList": run }), {
-      preventDefault: false,
-    });
+  it("leaves a plain Escape for the pane instead of binding it", () => {
+    const set = new CommandSet(defineCommands({ "spawn.open": vi.fn() }));
     const textarea = el('<textarea class="xterm-helper-textarea"></textarea>');
-    const e = key("Escape");
-    Object.defineProperty(e, "target", { value: textarea });
-    expect(set.handle(e)).toBe(true);
-    expect(run).toHaveBeenCalledTimes(1);
-    // xterm is told to swallow by the return value, not by the browser default.
-    expect(e.defaultPrevented).toBe(false);
+    expect(pressOn(set, textarea, "Escape")).toBe(false);
   });
 });
 
@@ -173,6 +170,7 @@ describe("the leader", () => {
     const byId = new Map(commandSpecs("ctrl-b").map((s) => [s.id, s]));
     expect(byId.get("pane.literalCtrlK")?.keys).toEqual(["ctrl-b ctrl-k"]);
     expect(byId.get("pane.literalLeader")?.keys).toEqual(["ctrl-b ctrl-b"]);
+    expect(byId.get("focus.toggle")?.keys).toEqual(["ctrl-b h"]);
     // Commands that do not hang off the leader are untouched.
     expect(byId.get("bar.open")?.keys).toEqual(["ctrl-k"]);
   });

web/src/commands.ts

@@ -93,7 +93,8 @@ const SPECS: readonly SpecSource[] = [
     id: "focus.toggle",
     label: "Move the keyboard between the session list and the pane",
     group: "Session list",
-    keys: ["ctrl-shift-h"],
+    keys: [`${DEFAULT_LEADER} h`],
+    leaderKeys: (leader) => [`${leader} h`],
     scope: "global",
   },
   {
@@ -145,13 +146,6 @@ const SPECS: readonly SpecSource[] = [
     keys: ["tab"],
     scope: "list",
   },
-  {
-    id: "pane.focusList",
-    label: "Hand the keyboard back to the session list, from the pane",
-    group: "Session list",
-    keys: ["esc"],
-    scope: "pane",
-  },
   {
     id: "help.toggle",
     label: "Show or hide this help",

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/killDialog.test.ts

@@ -0,0 +1,33 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  closeForceKillDialog,
+  openForceKillDialog,
+  openKillConfirmDialog,
+} from "./killDialog.js";
+
+describe("kill dialogs", () => {
+  beforeEach(() => {
+    closeForceKillDialog();
+    document.body.innerHTML = "";
+  });
+
+  it("focuses the kill button, so Enter confirms", () => {
+    const el = openKillConfirmDialog({
+      name: "alpha",
+      blockers: null,
+      onKill: () => Promise.resolve(),
+    });
+    expect(document.activeElement).toBe(el.querySelector(".kill-dialog-kill"));
+  });
+
+  it("focuses the force button too", () => {
+    const el = openForceKillDialog({
+      name: "alpha",
+      blockers: null,
+      reason: "worktree is dirty.",
+      onForce: () => Promise.resolve(),
+    });
+    expect(document.activeElement).toBe(el.querySelector(".kill-dialog-force"));
+  });
+});

web/src/killDialog.ts

@@ -132,9 +132,9 @@ function mount(p: KillDialogSpec): HTMLElement {
   };
   window.addEventListener("keydown", onKeydown, true);
   open = { el, onKeydown };
-  // Cancel takes the focus in both prompts: a kill is never one keystroke
-  // away from whatever asked for the dialog.
-  cancel.focus();
+  // The acting button takes the focus in both prompts: the operator already
+  // asked for the kill, so Enter confirms it. Escape and the scrim cancel.
+  confirm.focus();
   return el;
 }
 

web/src/layout.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   emptyLayout,
+  equalizeRatios,
   leaves,
   locateSession,
   openSessions,
@@ -44,6 +45,23 @@ describe("splitLeaf", () => {
   });
 });
 
+describe("equalizeRatios", () => {
+  it("resets nested splits to equal width, not just the newest one", () => {
+    const tab = tabWithOneLeaf("s1");
+    const first = leaves(tab.root)[0].id;
+    splitLeaf(tab, first, "s2", "row", true); // A|B, 0.5/0.5
+    const second = leaves(tab.root)[1].id;
+    splitLeaf(tab, second, "s3", "row", true); // A(0.5) | (B|C, 0.5/0.5) -> B,C at 0.25 each
+
+    equalizeRatios(tab.root);
+
+    const root = tab.root as Extract<typeof tab.root, { kind: "split" }>;
+    expect(root.ratio).toBeCloseTo(1 / 3);
+    const inner = root.b as Extract<typeof root.b, { kind: "split" }>;
+    expect(inner.ratio).toBeCloseTo(1 / 2);
+  });
+});
+
 describe("removeLeaf", () => {
   it("collapses the parent split into the surviving sibling", () => {
     const tab = tabWithOneLeaf("s1");

web/src/layout.ts

@@ -118,6 +118,17 @@ export function removeLeaf(tab: Tab, leafId: string): void {
   tab.root = tab.root ? rec(tab.root) : null;
 }
 
+/** Reset every split ratio under `node` so all leaves get equal width,
+ *  regardless of split direction or nesting order. Returns the leaf count. */
+export function equalizeRatios(node: Node | null): number {
+  if (!node) return 0;
+  if (node.kind === "leaf") return 1;
+  const na = equalizeRatios(node.a);
+  const nb = equalizeRatios(node.b);
+  node.ratio = na / (na + nb);
+  return na + nb;
+}
+
 export function addTab(layout: Layout): Tab {
   const tab: Tab = {
     id: freshId("t"),

web/src/main.ts

@@ -35,7 +35,6 @@ import { loadLayout, saveLayout } from "./persistence.js";
 import { createPreviewSchedule } from "./previewSchedule.js";
 import {
   FOCUS_PANE_EVENT,
-  FOCUS_SIDEBAR_EVENT,
   OPEN_COMMAND_BAR_EVENT,
   OPEN_SPAWN_EVENT,
   SESSION_SELECT_EVENT,
@@ -173,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
@@ -210,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. */
@@ -440,10 +440,11 @@ const spawnKeys = new CommandSet(
   }),
 );
 
-// Ctrl+Shift+H moves the keyboard between the session list and the pane, the
-// web counterpart of the TUI's `ctrl-w h`. It has to be a chord: an attached
-// terminal owns every plain keystroke, so nothing unmodified could ever get
-// the focus back out of it.
+// Leader-h moves the keyboard between the session list and the pane, the web
+// counterpart of the TUI's `ctrl-w h`. It has to be a chord behind the
+// leader: an attached terminal owns every plain keystroke, and Ctrl+Shift+H
+// is already claimed by the browser (history), so nothing unmodified — or
+// modified with a common browser chord — could get the focus back out of it.
 //
 // This set also owns the leader (`[tui].leader`, `ctrl-a` by default, served
 // on `/api/info`): it holds the key as a partial chord and takes select-all off
@@ -528,8 +529,8 @@ window.addEventListener(
 );
 
 
-// Tab in the session list hands the keyboard to the pane; Escape in the pane
-// hands it back — the pair the TUI gets from `tab` and `esc`.
+// Tab in the session list hands the keyboard to the pane; leader-h (focus.toggle,
+// above) hands it back the other way.
 document.addEventListener(FOCUS_PANE_EVENT, () => {
   // Handing the keyboard to a previewed pane is choosing it: the preview stops
   // being provisional rather than snapping back the moment the list blurs.
@@ -537,10 +538,6 @@ document.addEventListener(FOCUS_PANE_EVENT, () => {
   if (previewed) focusSession(previewed);
   pool.focusTerminal();
 });
-document.addEventListener(FOCUS_SIDEBAR_EVENT, () => {
-  drawer.open(); // no-op on desktop; on mobile the list is off-canvas
-  sidebar.focusList();
-});
 
 /** Open/focus a session and reflect it in the shell chrome. Shared by the
  *  hash router and the sidebar's click-driven path (#133), which can't rely

web/src/multiview.ts

@@ -10,6 +10,7 @@ import {
   activeTab,
   addTab,
   closeTab,
+  equalizeRatios,
   findLeaf,
   freshId,
   type Dir,
@@ -457,6 +458,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     dropPreview();
     const tab = activeTab(layout);
     tab.focusedLeafId = splitLeaf(tab, leafId, null, dir, true);
+    equalizeRatios(tab.root);
     render();
   }
 
@@ -542,6 +544,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
       target.sessionId = sessionId;
     } else {
       tab.focusedLeafId = splitLeaf(tab, target.id, sessionId, "row", true);
+      equalizeRatios(tab.root);
     }
     render();
     opts.onOpenSessionsChange?.();
@@ -815,6 +818,7 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     if (source.kind === "pane" && self) removeLeaf(tab, self);
     else if (loc) removeLeaf(loc.tab, loc.leaf.id);
     tab.focusedLeafId = splitLeaf(tab, targetLeafId, sessionId, dir, after);
+    equalizeRatios(tab.root);
     render();
   }
 

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

@@ -56,8 +56,19 @@ export interface Session {
    * how the command bar's empty query sorts a never-focused session after every
    * session that has one (`docs/COMMAND-BAR.md`). */
   last_focused_at?: IsoTimestamp | null;
+  /** The ACP session id the `claude-code-acp` adapter returned from
+   * `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;
@@ -363,6 +374,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