feat(maestro): wire sidebar drawer into MainActivity

ModalNavigationDrawer opened by a hamburger button in the top bar,
holding SidebarContent bound to the app's DaemonLink.catalog.

.gitea/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+  cancel-in-progress: true
 
 env:
   CARGO_TERM_COLOR: always

.gitignore

@@ -15,3 +15,6 @@ worktrees/
 
 # `nix run .#dev` scratch state (tmux socket)
 /.dev/
+
+# Per-machine Claude Code tool permissions
+.claude/settings.local.json

Cargo.lock

@@ -1467,6 +1467,7 @@ dependencies = [
  "maestro-cli",
  "maestro-daemon",
  "maestro-tui",
+ "tempfile",
  "tokio",
  "tracing-subscriber",
 ]
@@ -1477,6 +1478,7 @@ version = "0.1.0"
 dependencies = [
  "agent-client-protocol",
  "libc",
+ "serde",
  "serde_json",
  "tempfile",
  "thiserror 1.0.69",

android/.gitignore

@@ -0,0 +1,11 @@
+*.iml
+.gradle/
+/local.properties
+/.idea/
+.DS_Store
+/build/
+/captures/
+.externalNativeBuild/
+.cxx/
+*.apk
+*.aab

android/app/build.gradle.kts

@@ -0,0 +1,82 @@
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.kotlin.serialization)
+}
+
+android {
+    namespace = "pt.naps.maestro"
+    compileSdk = 34
+
+    defaultConfig {
+        applicationId = "pt.naps.maestro"
+        minSdk = 26
+        targetSdk = 34
+        versionCode = 1
+        versionName = "0.1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    signingConfigs {
+        getByName("debug") {
+            storeFile = file("debug.keystore")
+            storePassword = "android"
+            keyAlias = "androiddebugkey"
+            keyPassword = "android"
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+        debug {
+            signingConfig = signingConfigs.getByName("debug")
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    buildFeatures {
+        compose = true
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.process)
+    implementation(libs.androidx.activity.compose)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.ui)
+    implementation(libs.androidx.ui.graphics)
+    implementation(libs.androidx.ui.tooling.preview)
+    implementation(libs.androidx.material3)
+    implementation(libs.androidx.navigation.compose)
+    implementation(libs.okhttp)
+    implementation(libs.kotlinx.serialization.json)
+    implementation(libs.kotlinx.coroutines.android)
+
+    testImplementation(libs.junit)
+
+    androidTestImplementation(libs.androidx.test.ext.junit)
+    androidTestImplementation(libs.androidx.espresso.core)
+    androidTestImplementation(platform(libs.androidx.compose.bom))
+    androidTestImplementation(libs.androidx.ui.test.junit4)
+
+    debugImplementation(libs.androidx.ui.tooling)
+    debugImplementation(libs.androidx.ui.test.manifest)
+}

android/app/proguard-rules.pro

@@ -0,0 +1,6 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.kts.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html

android/app/src/androidTest/java/pt/naps/maestro/MainActivityTest.kt

@@ -0,0 +1,19 @@
+package pt.naps.maestro
+
+import androidx.compose.ui.test.junit4.createAndroidComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class MainActivityTest {
+    @get:Rule
+    val composeTestRule = createAndroidComposeRule<MainActivity>()
+
+    @Test
+    fun placeholderScreen_showsAppName() {
+        composeTestRule.onNodeWithText("Maestro").assertExists()
+    }
+}

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher"
+        android:supportsRtl="true"
+        android:usesCleartextTraffic="true"
+        android:theme="@style/Theme.Maestro">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Maestro">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

android/app/src/main/java/pt/naps/maestro/MainActivity.kt

@@ -0,0 +1,121 @@
+package pt.naps.maestro
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.DrawerValue
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalDrawerSheet
+import androidx.compose.material3.ModalNavigationDrawer
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.rememberDrawerState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.tooling.preview.Preview
+import androidx.compose.ui.unit.dp
+import kotlinx.coroutines.launch
+import pt.naps.maestro.connection.DaemonLink
+import pt.naps.maestro.connection.DaemonPrefs
+import pt.naps.maestro.connection.LinkState
+import pt.naps.maestro.ui.sidebar.SidebarContent
+import pt.naps.maestro.ui.theme.MaestroTheme
+
+class MainActivity : ComponentActivity() {
+    private lateinit var daemonLink: DaemonLink
+
+    @OptIn(ExperimentalMaterial3Api::class)
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+
+        val prefs = DaemonPrefs(applicationContext)
+        intent?.getStringExtra(DaemonPrefs.EXTRA_DAEMON_URL)?.let { prefs.setBaseUrl(it) }
+        daemonLink = DaemonLink(applicationContext, prefs).also { it.start() }
+
+        setContent {
+            MaestroTheme {
+                val linkState by daemonLink.state.collectAsState()
+                val drawerState = rememberDrawerState(DrawerValue.Closed)
+                val scope = rememberCoroutineScope()
+
+                ModalNavigationDrawer(
+                    drawerState = drawerState,
+                    drawerContent = {
+                        ModalDrawerSheet(modifier = Modifier.width(320.dp)) {
+                            SidebarContent(
+                                catalogStore = daemonLink.catalog,
+                                onOpenSession = { scope.launch { drawerState.close() } },
+                            )
+                        }
+                    },
+                ) {
+                    Scaffold(
+                        modifier = Modifier.fillMaxSize(),
+                        topBar = {
+                            TopAppBar(
+                                title = { Text("Maestro") },
+                                navigationIcon = {
+                                    IconButton(onClick = { scope.launch { drawerState.open() } }) {
+                                        Text("☰")
+                                    }
+                                },
+                            )
+                        },
+                    ) { innerPadding ->
+                        PlaceholderScreen(modifier = Modifier.padding(innerPadding), linkState = linkState)
+                    }
+                }
+            }
+        }
+    }
+
+    override fun onDestroy() {
+        daemonLink.close()
+        super.onDestroy()
+    }
+}
+
+@Composable
+fun PlaceholderScreen(modifier: Modifier = Modifier, linkState: LinkState = LinkState.CONNECTING) {
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .padding(24.dp),
+        verticalArrangement = Arrangement.Center,
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        Text(
+            text = "Maestro",
+            style = MaterialTheme.typography.bodyLarge,
+        )
+        Text(
+            text = stringResource(id = R.string.placeholder_message),
+        )
+        Text(
+            text = "Daemon: ${linkState.name.lowercase()}",
+        )
+    }
+}
+
+@Preview(showBackground = true)
+@Composable
+private fun PlaceholderScreenPreview() {
+    MaestroTheme {
+        PlaceholderScreen()
+    }
+}

android/app/src/main/java/pt/naps/maestro/api/MaestroApiException.kt

@@ -0,0 +1,21 @@
+package pt.naps.maestro.api
+
+import pt.naps.maestro.data.InTheWay
+
+/** A `/api` failure with the daemon's own error envelope kept intact, so a
+ * caller can branch on [code] and render [unsavedWork] — the kill guard —
+ * rather than re-parsing [detail]. Mirrors the web client's
+ * `ApiRequestError`. */
+class MaestroApiException(
+    val status: Int,
+    val code: String,
+    val detail: String,
+    val unsavedWork: InTheWay? = null,
+) : Exception(buildMessage(status, code, detail)) {
+    private companion object {
+        fun buildMessage(status: Int, code: String, detail: String): String {
+            val info = if (code.isNotEmpty()) "$code: $detail" else detail
+            return if (info.isNotEmpty()) "$status — $info" else "$status"
+        }
+    }
+}

android/app/src/main/java/pt/naps/maestro/api/MaestroClient.kt

@@ -0,0 +1,252 @@
+package pt.naps.maestro.api
+
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import pt.naps.maestro.data.ApiError
+import pt.naps.maestro.data.BranchInfo
+import pt.naps.maestro.data.CreateSessionRequest
+import pt.naps.maestro.data.DaemonInfo
+import pt.naps.maestro.data.DirListing
+import pt.naps.maestro.data.GitRoot
+import pt.naps.maestro.data.NameBatch
+import pt.naps.maestro.data.Project
+import pt.naps.maestro.data.RecentDirs
+import pt.naps.maestro.data.RenameSessionRequest
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.SetFocusRequest
+import pt.naps.maestro.data.StructuredAttachmentResponse
+import pt.naps.maestro.data.StructuredApprovalDecision
+import pt.naps.maestro.data.StructuredConfigRequest
+import pt.naps.maestro.data.StructuredPromptRequest
+import pt.naps.maestro.data.Uuid
+import java.io.IOException
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+private val JSON_MEDIA_TYPE = "application/json; charset=utf-8".toMediaType()
+private val OCTET_STREAM_MEDIA_TYPE = "application/octet-stream".toMediaType()
+
+/**
+ * Typed client for the daemon's `/api` surface (REST half). Mirrors
+ * `maestro_protocol::client::DaemonClient` / `web/src/api.ts`.
+ *
+ * There is no authentication layer: reaching the daemon's bind address is
+ * the authorization, same trust model as tmux itself.
+ */
+class MaestroClient(
+    private val baseUrl: String,
+    private val httpClient: OkHttpClient = OkHttpClient(),
+) {
+    private val json = Json {
+        ignoreUnknownKeys = true
+        isLenient = true
+    }
+
+    suspend fun listSessions(): List<Session> = get(Routes.SESSIONS)
+
+    suspend fun createSession(request: CreateSessionRequest): Session =
+        post(Routes.SESSIONS, request)
+
+    /** `PATCH /api/sessions/:id`: rename a live session. An empty [name]
+     * clears the custom one, so the card falls back to the command. */
+    suspend fun renameSession(id: Uuid, name: String): Session =
+        patch(Routes.session(id), RenameSessionRequest(name))
+
+    /** `DELETE /api/sessions/:id`. With [force], the daemon overrides the
+     * kill refusal over a worktree holding unsaved work and leaves that
+     * worktree on disk. */
+    suspend fun killSession(id: Uuid, force: Boolean = false) {
+        val query = if (force) listOf(Routes.FORCE_QUERY to "true") else emptyList()
+        executeNoContent(newRequest("DELETE", Routes.session(id), query = query))
+    }
+
+    /** `POST /api/sessions/:id/focus`: report whether this client's pane is
+     * the one currently showing [id] — not merely highlighted in a
+     * sidebar. */
+    suspend fun setSessionFocus(id: Uuid, focused: Boolean) {
+        executeNoContent(
+            newRequest(
+                "POST",
+                Routes.sessionFocus(id),
+                body = json.encodeToString(SetFocusRequest(focused)),
+            ),
+        )
+    }
+
+    /** `GET /api/dirs?path=`: one directory's immediate subdirectories.
+     * [path] may be empty, `~`, relative, or absolute — the daemon resolves
+     * it against its home dir. */
+    suspend fun listDir(path: String): DirListing =
+        get(Routes.DIRS, listOf(Routes.PATH_QUERY to path))
+
+    /** `GET /api/info`: identity + spawn presets of the connected daemon. */
+    suspend fun getDaemonInfo(): DaemonInfo = get(Routes.INFO)
+
+    /** `GET /api/recent-dirs`: recently-used working dirs, newest-first and
+     * deduped by dir. */
+    suspend fun recentDirs(): RecentDirs = get(Routes.RECENT_DIRS)
+
+    /** `GET /api/projects`: every discovered git repository/worktree,
+     * newest-activity-first. */
+    suspend fun listProjects(): List<Project> = get(Routes.PROJECTS)
+
+    /** `GET /api/gitroot?path=`: the enclosing git repo of [path]; absent
+     * when [path] isn't inside a repo. */
+    suspend fun gitRoot(path: String): GitRoot =
+        get(Routes.GITROOT, listOf(Routes.PATH_QUERY to path))
+
+    /** `GET /api/names?count=`: a batch of fresh session handles. */
+    suspend fun fetchNames(count: Int): NameBatch =
+        get(Routes.NAMES, listOf(Routes.COUNT_QUERY to count.toString()))
+
+    /** `GET /api/branches?path=`: one repository's local branches, with
+     * worktree occupancy. */
+    suspend fun listBranches(path: String): List<BranchInfo> =
+        get(Routes.BRANCHES, listOf(Routes.PATH_QUERY to path))
+
+    /** Send a prompt to a structured session's ACP turn. `409
+     * turn_in_flight` when one is already active. */
+    suspend fun sendStructuredPrompt(id: Uuid, prompt: String) {
+        executeNoContent(
+            newRequest(
+                "POST",
+                Routes.structuredPrompt(id),
+                body = json.encodeToString(StructuredPromptRequest(prompt)),
+            ),
+        )
+    }
+
+    /** Upload a file attachment for a structured session's next prompt. */
+    suspend fun uploadStructuredAttachment(
+        id: Uuid,
+        fileName: String,
+        contents: ByteArray,
+    ): StructuredAttachmentResponse {
+        val url = Routes.httpUrl(baseUrl, Routes.structuredAttachment(id)).toHttpUrl()
+            .newBuilder()
+            .addQueryParameter("name", fileName)
+            .build()
+        val request = Request.Builder()
+            .url(url)
+            .post(contents.toRequestBody(OCTET_STREAM_MEDIA_TYPE))
+            .build()
+        return decode(execute(request))
+    }
+
+    /** Cancel a structured session's active ACP turn. */
+    suspend fun cancelStructuredTurn(id: Uuid) {
+        executeNoContent(newRequest("POST", Routes.structuredCancel(id)))
+    }
+
+    /** Change one option advertised by a live ACP session. */
+    suspend fun setStructuredConfig(id: Uuid, configId: String, value: JsonElement) {
+        executeNoContent(
+            newRequest(
+                "POST",
+                Routes.structuredConfig(id),
+                body = json.encodeToString(StructuredConfigRequest(configId, value)),
+            ),
+        )
+    }
+
+    /** Answer a pending ACP permission request. Always resolves once the
+     * session itself is a live structured session — a nonce that is unknown
+     * or already consumed still answers success. */
+    suspend fun resolveStructuredApproval(
+        id: Uuid,
+        nonce: String,
+        decision: StructuredApprovalDecision,
+    ) {
+        executeNoContent(
+            newRequest(
+                "POST",
+                Routes.structuredApproval(id, nonce),
+                body = json.encodeToString(decision),
+            ),
+        )
+    }
+
+    // -- plumbing ------------------------------------------------------
+
+    private suspend inline fun <reified T> get(
+        path: String,
+        query: List<Pair<String, String>> = emptyList(),
+    ): T = decode(execute(newRequest("GET", path, query = query)))
+
+    private suspend inline fun <reified B, reified T> post(path: String, body: B): T =
+        decode(execute(newRequest("POST", path, body = json.encodeToString(body))))
+
+    private suspend inline fun <reified B, reified T> patch(path: String, body: B): T =
+        decode(execute(newRequest("PATCH", path, body = json.encodeToString(body))))
+
+    private fun newRequest(
+        method: String,
+        path: String,
+        query: List<Pair<String, String>> = emptyList(),
+        body: String? = null,
+    ): Request {
+        val urlBuilder = Routes.httpUrl(baseUrl, path).toHttpUrl().newBuilder()
+        for ((key, value) in query) urlBuilder.addQueryParameter(key, value)
+        // OkHttp refuses a null body on POST/PUT/PATCH even when the daemon
+        // expects none (e.g. the structured-turn cancel) — an empty body
+        // satisfies it without implying a JSON payload.
+        val requestBody = when {
+            body != null -> body.toRequestBody(JSON_MEDIA_TYPE)
+            method == "POST" || method == "PUT" || method == "PATCH" -> ByteArray(0).toRequestBody(null)
+            else -> null
+        }
+        return Request.Builder()
+            .url(urlBuilder.build())
+            .method(method, requestBody)
+            .build()
+    }
+
+    private suspend fun execute(request: Request): Response =
+        suspendCancellableCoroutine { cont ->
+            val call = httpClient.newCall(request)
+            cont.invokeOnCancellation { call.cancel() }
+            call.enqueue(
+                object : Callback {
+                    override fun onFailure(call: Call, e: IOException) {
+                        if (!cont.isCancelled) cont.resumeWithException(e)
+                    }
+
+                    override fun onResponse(call: Call, response: Response) {
+                        cont.resume(response)
+                    }
+                },
+            )
+        }
+
+    private suspend fun executeNoContent(request: Request) {
+        execute(request).use { if (!it.isSuccessful) throw toApiException(it) }
+    }
+
+    private inline fun <reified T> decode(response: Response): T =
+        response.use {
+            if (!it.isSuccessful) throw toApiException(it)
+            json.decodeFromString<T>(it.body?.string().orEmpty())
+        }
+
+    private fun toApiException(response: Response): MaestroApiException {
+        val text = response.body?.string().orEmpty()
+        val info = runCatching { json.decodeFromString<ApiError>(text) }.getOrNull()?.error
+        return MaestroApiException(
+            status = response.code,
+            code = info?.code ?: "",
+            detail = info?.message ?: text,
+            unsavedWork = info?.unsaved_work,
+        )
+    }
+}

android/app/src/main/java/pt/naps/maestro/api/MaestroWebSocket.kt

@@ -0,0 +1,175 @@
+package pt.naps.maestro.api
+
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.receiveAsFlow
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.WebSocket
+import okhttp3.WebSocketListener
+import okio.ByteString
+import pt.naps.maestro.data.CatalogEvent
+import pt.naps.maestro.data.ClientControl
+import pt.naps.maestro.data.StructuredEvent
+import pt.naps.maestro.data.Uuid
+
+private val wsJson = Json {
+    ignoreUnknownKeys = true
+    isLenient = true
+}
+
+/** One frame received on `WS /api/attach/:id`: raw PTY bytes, or a decoded
+ * [ClientControl] text message. */
+sealed class AttachFrame {
+    data class Pty(val bytes: ByteArray) : AttachFrame()
+    data class Control(val message: ClientControl) : AttachFrame()
+}
+
+/** A live `WS /api/attach/:id` connection. PTY bytes travel in binary frames
+ * both directions; control messages ([ClientControl]) travel in text
+ * frames. */
+class AttachConnection internal constructor(
+    private val socket: WebSocket,
+    val frames: Flow<AttachFrame>,
+) {
+    /** Type raw bytes into the session's pane, as if typed on an attached
+     * terminal. */
+    fun sendInput(bytes: ByteArray) {
+        socket.send(ByteString.of(*bytes))
+    }
+
+    fun resize(cols: Int, rows: Int) {
+        sendControl(ClientControl.Resize(cols, rows))
+    }
+
+    fun ping() {
+        sendControl(ClientControl.Ping)
+    }
+
+    private fun sendControl(message: ClientControl) {
+        socket.send(wsJson.encodeToString(message))
+    }
+
+    fun close() {
+        socket.close(1000, null)
+    }
+}
+
+/** A live `WS /api/structured/:id` connection: transcript/state snapshots
+ * and live deltas for one structured session. */
+class StructuredConnection internal constructor(
+    private val socket: WebSocket,
+    val events: Flow<StructuredEvent>,
+) {
+    fun close() {
+        socket.close(1000, null)
+    }
+}
+
+/** A live `WS /api/events` connection: catalog snapshot + session deltas. */
+class EventsConnection internal constructor(
+    private val socket: WebSocket,
+    val events: Flow<CatalogEvent>,
+) {
+    fun close() {
+        socket.close(1000, null)
+    }
+}
+
+/**
+ * WebSocket half of the daemon's `/api` surface. Mirrors the `*_url`
+ * helpers in `crates/maestro-protocol/src/routes.rs`.
+ *
+ * Each `connect*` call opens the socket immediately and returns a handle
+ * whose `Flow` starts buffering frames right away — a slow collector never
+ * misses a frame, it only sees it later. Call `close()` on the returned
+ * connection when done; there is no automatic reconnect.
+ */
+class MaestroWebSocket(
+    private val baseUrl: String,
+    private val httpClient: OkHttpClient = OkHttpClient(),
+) {
+    /** `WS /api/events`: catalog snapshot + session deltas. */
+    fun connectEvents(): EventsConnection {
+        val channel = Channel<CatalogEvent>(Channel.BUFFERED)
+        val socket = open(
+            Routes.eventsWsUrl(baseUrl),
+            object : WebSocketListener() {
+                override fun onMessage(webSocket: WebSocket, text: String) {
+                    runCatching { wsJson.decodeFromString<CatalogEvent>(text) }
+                        .onSuccess { channel.trySend(it) }
+                }
+
+                override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                    channel.close(t)
+                }
+
+                override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                    channel.close()
+                }
+            },
+        )
+        return EventsConnection(socket, channel.receiveAsFlow())
+    }
+
+    /** `WS /api/attach/:id`: raw PTY bytes both directions, control messages
+     * as text JSON. */
+    fun connectAttach(id: Uuid): AttachConnection {
+        val channel = Channel<AttachFrame>(Channel.BUFFERED)
+        val socket = open(
+            Routes.attachWsUrl(baseUrl, id),
+            object : WebSocketListener() {
+                override fun onMessage(webSocket: WebSocket, text: String) {
+                    runCatching { wsJson.decodeFromString<ClientControl>(text) }
+                        .onSuccess { channel.trySend(AttachFrame.Control(it)) }
+                }
+
+                override fun onMessage(webSocket: WebSocket, bytes: ByteString) {
+                    channel.trySend(AttachFrame.Pty(bytes.toByteArray()))
+                }
+
+                override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                    channel.close(t)
+                }
+
+                override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                    channel.close()
+                }
+            },
+        )
+        return AttachConnection(socket, channel.receiveAsFlow())
+    }
+
+    /** `WS /api/structured/:id`: transcript/state snapshots and live deltas
+     * for one structured session. */
+    fun connectStructured(id: Uuid): StructuredConnection {
+        val channel = Channel<StructuredEvent>(Channel.BUFFERED)
+        val socket = open(
+            Routes.structuredWsUrl(baseUrl, id),
+            object : WebSocketListener() {
+                override fun onMessage(webSocket: WebSocket, text: String) {
+                    runCatching { wsJson.decodeFromString<StructuredEvent>(text) }
+                        .onSuccess { channel.trySend(it) }
+                }
+
+                override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                    channel.close(t)
+                }
+
+                override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                    channel.close()
+                }
+            },
+        )
+        return StructuredConnection(socket, channel.receiveAsFlow())
+    }
+
+    private fun open(url: String, listener: WebSocketListener): WebSocket {
+        val request = Request.Builder().url(url).build()
+        return httpClient.newWebSocket(request, listener)
+    }
+}

android/app/src/main/java/pt/naps/maestro/api/Routes.kt

@@ -0,0 +1,84 @@
+package pt.naps.maestro.api
+
+import pt.naps.maestro.data.Uuid
+
+/** The daemon's `/api` surface: paths, and the scheme swap needed to reach
+ * the WebSocket endpoints. Mirrors `maestro-protocol::routes` /
+ * `web/src/routes.ts`. */
+object Routes {
+    const val API_PREFIX = "/api"
+
+    const val SESSIONS = "/api/sessions"
+    const val INFO = "/api/info"
+    const val DIRS = "/api/dirs"
+    const val RECENT_DIRS = "/api/recent-dirs"
+    const val PROJECTS = "/api/projects"
+    const val GITROOT = "/api/gitroot"
+    const val NAMES = "/api/names"
+    const val BRANCHES = "/api/branches"
+    const val EVENTS = "/api/events"
+
+    /** Name of the query parameter [DIRS], [GITROOT] and [BRANCHES] take. */
+    const val PATH_QUERY = "path"
+
+    /** Name of the query parameter `DELETE /api/sessions/:id` takes:
+     * `force=true` overrides the kill refusal over a guarded worktree. */
+    const val FORCE_QUERY = "force"
+
+    /** Name of the query parameter [NAMES] takes. */
+    const val COUNT_QUERY = "count"
+
+    fun session(id: Uuid): String = "$SESSIONS/$id"
+
+    fun sessionFocus(id: Uuid): String = "${session(id)}/focus"
+
+    fun attach(id: Uuid): String = "$API_PREFIX/attach/$id"
+
+    /** `WS /api/structured/:id` — transcript/state snapshots and live
+     * deltas. */
+    fun structured(id: Uuid): String = "$API_PREFIX/structured/$id"
+
+    /** `POST /api/sessions/:id/structured/prompt` — send an ACP prompt. */
+    fun structuredPrompt(id: Uuid): String = "${session(id)}/structured/prompt"
+
+    fun structuredAttachment(id: Uuid): String = "${session(id)}/structured/attachments"
+
+    /** `POST /api/sessions/:id/structured/cancel` — cancel an ACP turn. */
+    fun structuredCancel(id: Uuid): String = "${session(id)}/structured/cancel"
+
+    /** `POST /api/sessions/:id/structured/config` — change an ACP session
+     * option. */
+    fun structuredConfig(id: Uuid): String = "${session(id)}/structured/config"
+
+    /** `POST /api/sessions/:id/structured/approvals/:nonce` — answer a
+     * permission request. */
+    fun structuredApproval(id: Uuid, nonce: String): String =
+        "${session(id)}/structured/approvals/$nonce"
+
+    /** Strip a trailing slash so `{base}{path}` never doubles up. */
+    fun normalizeBase(base: String): String = base.trimEnd('/')
+
+    /** Join a daemon base URL and one of this object's paths. */
+    fun httpUrl(base: String, path: String): String = "${normalizeBase(base)}$path"
+
+    /** Swap an HTTP base URL for its WebSocket equivalent: `http://` becomes
+     * `ws://`, `https://` becomes `wss://`; a base already `ws(s)://` passes
+     * through. */
+    fun wsBase(httpBase: String): String {
+        val base = normalizeBase(httpBase)
+        return when {
+            base.startsWith("https://") -> "wss://${base.removePrefix("https://")}"
+            base.startsWith("http://") -> "ws://${base.removePrefix("http://")}"
+            base.startsWith("wss://") || base.startsWith("ws://") -> base
+            else -> throw IllegalArgumentException(
+                "daemon url has no supported scheme (want http/https/ws/wss): $httpBase",
+            )
+        }
+    }
+
+    fun eventsWsUrl(base: String): String = "${wsBase(base)}$EVENTS"
+
+    fun attachWsUrl(base: String, id: Uuid): String = "${wsBase(base)}${attach(id)}"
+
+    fun structuredWsUrl(base: String, id: Uuid): String = "${wsBase(base)}${structured(id)}"
+}

android/app/src/main/java/pt/naps/maestro/connection/Backoff.kt

@@ -0,0 +1,32 @@
+package pt.naps.maestro.connection
+
+/**
+ * Exponential backoff for daemon reconnect attempts: doubles from
+ * [initialMs] up to [maxMs], then holds. A phone's radio swinging between
+ * wifi and cellular (or losing signal outright) is a bigger, longer-lived
+ * change than the LAN blips the web/TUI clients ride out with a flat poll,
+ * so this backs off instead of hammering the daemon while nothing changed.
+ */
+class Backoff(
+    private val initialMs: Long = INITIAL_MS,
+    private val maxMs: Long = MAX_MS,
+) {
+    private var currentMs = initialMs
+
+    /** Delay before the next attempt; advances the sequence for the one after. */
+    fun nextDelayMs(): Long {
+        val delay = currentMs
+        currentMs = (currentMs * 2).coerceAtMost(maxMs)
+        return delay
+    }
+
+    /** Back to [initialMs] after a successful connection. */
+    fun reset() {
+        currentMs = initialMs
+    }
+
+    companion object {
+        const val INITIAL_MS = 500L
+        const val MAX_MS = 10_000L
+    }
+}

android/app/src/main/java/pt/naps/maestro/connection/CatalogStore.kt

@@ -0,0 +1,49 @@
+package pt.naps.maestro.connection
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import pt.naps.maestro.data.CatalogEvent
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.Uuid
+
+/**
+ * Session catalog folded from `WS /api/events`. A [CatalogEvent.Snapshot]
+ * replaces the map outright; deltas mutate one entry.
+ */
+class CatalogStore {
+    private val _sessions = MutableStateFlow<Map<Uuid, Session>>(emptyMap())
+    val sessions: StateFlow<Map<Uuid, Session>> = _sessions.asStateFlow()
+
+    /** Applies one event. Returns the skip count for [CatalogEvent.Lagged] —
+     * the caller re-fetches a full snapshot over REST and calls [replace],
+     * mirroring how the web client reacts to a dropped broadcast frame. */
+    fun apply(event: CatalogEvent): Long? =
+        when (event) {
+            is CatalogEvent.Snapshot -> {
+                _sessions.value = event.sessions.associateBy { it.id }
+                null
+            }
+            is CatalogEvent.SessionAdded -> {
+                _sessions.value = _sessions.value + (event.session.id to event.session)
+                null
+            }
+            is CatalogEvent.SessionUpdated -> {
+                _sessions.value = _sessions.value + (event.session.id to event.session)
+                null
+            }
+            is CatalogEvent.SessionRemoved -> {
+                _sessions.value = _sessions.value - event.id
+                null
+            }
+            is CatalogEvent.Lagged -> event.skipped
+        }
+
+    fun replace(sessions: List<Session>) {
+        _sessions.value = sessions.associateBy { it.id }
+    }
+
+    fun clear() {
+        _sessions.value = emptyMap()
+    }
+}

android/app/src/main/java/pt/naps/maestro/connection/ConnectivityObserver.kt

@@ -0,0 +1,51 @@
+package pt.naps.maestro.connection
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.net.NetworkRequest
+
+/**
+ * Notifies [onAvailable] whenever a usable network appears — including the
+ * wifi/cellular handoff, which Android reports as one network disappearing
+ * and another becoming available rather than a single "changed" event.
+ * [DaemonLink] treats every call as "worth reconnecting for" rather than
+ * inspecting which network it is.
+ */
+class ConnectivityObserver(
+    context: Context,
+    private val onAvailable: () -> Unit,
+) {
+    private val connectivityManager =
+        context.applicationContext.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+
+    private val callback = object : ConnectivityManager.NetworkCallback() {
+        override fun onAvailable(network: Network) = onAvailable.invoke()
+
+        override fun onCapabilitiesChanged(network: Network, networkCapabilities: NetworkCapabilities) {
+            if (networkCapabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
+                networkCapabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+            ) {
+                onAvailable.invoke()
+            }
+        }
+    }
+
+    private var registered = false
+
+    fun start() {
+        if (registered) return
+        val request = NetworkRequest.Builder()
+            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            .build()
+        connectivityManager.registerNetworkCallback(request, callback)
+        registered = true
+    }
+
+    fun stop() {
+        if (!registered) return
+        runCatching { connectivityManager.unregisterNetworkCallback(callback) }
+        registered = false
+    }
+}

android/app/src/main/java/pt/naps/maestro/connection/DaemonIdentity.kt

@@ -0,0 +1,37 @@
+package pt.naps.maestro.connection
+
+import pt.naps.maestro.data.BuildInfo
+import pt.naps.maestro.data.DaemonInfo
+
+/** What happened between two `/api/info` replies. */
+enum class RestartKind { SAME, RESTARTED, UPGRADED }
+
+/**
+ * Compare two daemon replies. Mirrors `compareIdentity` in
+ * `web/src/components/daemon/DaemonLink.tsx` / `compare_identity` in
+ * `crates/maestro-tui/src/daemon_link.rs`.
+ *
+ * The commit decides first: a different one is new server code. `instance`
+ * catches everything else — a restart of the same build — and is the only
+ * signal for a daemon built outside a git checkout, where the commit is
+ * always empty and an empty-vs-empty pair must never read as an upgrade.
+ */
+fun compareIdentity(before: DaemonInfo, after: DaemonInfo): RestartKind {
+    val a = before.build.commit
+    val b = after.build.commit
+    if (a.isNotEmpty() && b.isNotEmpty() && a != b) return RestartKind.UPGRADED
+    if (before.instance.isNotEmpty() && after.instance.isNotEmpty() && before.instance != after.instance) {
+        return RestartKind.RESTARTED
+    }
+    return RestartKind.SAME
+}
+
+/** One line naming a release: `f89be4a716c7 · 2026-09-02`, `(dirty)` when the
+ * build carried uncommitted changes. Mirrors `formatRelease` / `format_release`. */
+fun formatRelease(build: BuildInfo): String {
+    if (build.commit.isEmpty()) return "unknown release"
+    val parts = mutableListOf(build.commit)
+    if (build.commit_date.length >= 10) parts.add("· ${build.commit_date.take(10)}")
+    if (build.dirty) parts.add("(dirty)")
+    return parts.joinToString(" ")
+}

android/app/src/main/java/pt/naps/maestro/connection/DaemonLink.kt

@@ -0,0 +1,287 @@
+package pt.naps.maestro.connection
+
+import android.content.Context
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import okhttp3.OkHttpClient
+import pt.naps.maestro.api.EventsConnection
+import pt.naps.maestro.api.MaestroClient
+import pt.naps.maestro.api.MaestroWebSocket
+import pt.naps.maestro.data.BuildInfo
+import pt.naps.maestro.data.DaemonInfo
+
+/** How long a dropped link stays [LinkState.RECONNECTING] before flipping to
+ * [LinkState.DOWN] — long enough to ride out a blip, short enough that a real
+ * outage shows up. Mirrors the grace window in `docs/RESTART.md`. */
+private const val GRACE_MS = 1_200L
+
+/**
+ * Owns the connection to one daemon for the app's whole life: liveness,
+ * identity, and the session catalog. A Kotlin port of the state machine in
+ * `web/src/components/daemon/DaemonLink.tsx` / `crates/maestro-tui/src/daemon_link.rs`
+ * — see `docs/RESTART.md` for the contract both mirror — with exponential
+ * [Backoff] standing in for their flat poll, since a phone's network changes
+ * are bigger and longer-lived than the LAN blips those clients ride out.
+ *
+ * Everything that can change the link — a probe landing, the events socket
+ * dropping, the app resuming, the network coming back, a new daemon URL —
+ * goes through one [signals] channel consumed by one coroutine, so state
+ * transitions never race each other.
+ */
+class DaemonLink(
+    context: Context,
+    private val prefs: DaemonPrefs,
+    private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.IO),
+    private val httpClient: OkHttpClient = OkHttpClient(),
+) : DefaultLifecycleObserver {
+    private val appContext = context.applicationContext
+
+    private val _state = MutableStateFlow(LinkState.CONNECTING)
+    val state: StateFlow<LinkState> = _state.asStateFlow()
+
+    private val _build = MutableStateFlow<BuildInfo?>(null)
+    val build: StateFlow<BuildInfo?> = _build.asStateFlow()
+
+    private val _attempts = MutableStateFlow(0)
+    val attempts: StateFlow<Int> = _attempts.asStateFlow()
+
+    val catalog = CatalogStore()
+
+    private val backoff = Backoff()
+    private val signals = Channel<Signal>(Channel.UNLIMITED)
+    private val connectivity = ConnectivityObserver(appContext) { signals.trySend(Signal.NetworkAvailable) }
+
+    private var generation = 0
+    private var currentBaseUrl: String = prefs.baseUrl.value
+    private var client = MaestroClient(currentBaseUrl, httpClient)
+    private var socket = MaestroWebSocket(currentBaseUrl, httpClient)
+    private var identity: DaemonInfo? = null
+
+    private var eventsJob: Job? = null
+    private var eventsConnection: EventsConnection? = null
+    private var retryJob: Job? = null
+    private var graceJob: Job? = null
+    private var loopJob: Job? = null
+    private var started = false
+
+    private sealed class Signal {
+        object Start : Signal()
+        object Resume : Signal()
+        object NetworkAvailable : Signal()
+        object SocketDropped : Signal()
+        data class BaseUrlChanged(val url: String) : Signal()
+        data class ProbeResult(val generation: Int, val info: DaemonInfo?) : Signal()
+        data class Lagged(val skipped: Long) : Signal()
+    }
+
+    /** Starts the link: subscribes to process lifecycle and connectivity, and
+     * kicks off the first probe. Call once. */
+    fun start() {
+        if (started) return
+        started = true
+        loopJob = scope.launch { runLoop() }
+        connectivity.start()
+        scope.launch(Dispatchers.Main.immediate) {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(this@DaemonLink)
+        }
+        scope.launch {
+            prefs.baseUrl.collect { url ->
+                if (url != currentBaseUrl) signals.trySend(Signal.BaseUrlChanged(url))
+            }
+        }
+        signals.trySend(Signal.Start)
+    }
+
+    /** Tears everything down. Only needed by tests and by an owner that is
+     * itself going away for good (this link is meant to outlive an Activity). */
+    fun close() {
+        connectivity.stop()
+        cancelRetry()
+        cancelGrace()
+        closeEvents()
+        loopJob?.cancel()
+        signals.close()
+        scope.launch(Dispatchers.Main.immediate) {
+            runCatching { ProcessLifecycleOwner.get().lifecycle.removeObserver(this@DaemonLink) }
+        }
+    }
+
+    override fun onStart(owner: LifecycleOwner) {
+        signals.trySend(Signal.Resume)
+    }
+
+    private suspend fun runLoop() {
+        for (signal in signals) {
+            when (signal) {
+                is Signal.Start -> probeNow()
+                is Signal.Resume -> {
+                    probeNow()
+                    ensureEventsConnected()
+                }
+                is Signal.NetworkAvailable -> {
+                    cancelRetry()
+                    probeNow()
+                }
+                is Signal.SocketDropped -> handleSocketDropped()
+                is Signal.BaseUrlChanged -> handleBaseUrlChanged(signal.url)
+                is Signal.ProbeResult -> {
+                    if (signal.generation == generation) handleProbeResult(signal.info)
+                }
+                is Signal.Lagged -> handleLagged()
+            }
+        }
+    }
+
+    private fun probeNow() {
+        val gen = generation
+        val currentClient = client
+        scope.launch {
+            val info = runCatching { currentClient.getDaemonInfo() }.getOrNull()
+            signals.trySend(Signal.ProbeResult(gen, info))
+        }
+    }
+
+    private fun handleProbeResult(info: DaemonInfo?) {
+        if (info == null) {
+            onProbeFailed()
+            return
+        }
+        val before = identity
+        identity = info
+        _build.value = info.build
+        if (before != null && compareIdentity(before, info) == RestartKind.UPGRADED) {
+            _state.value = LinkState.UPDATING
+            fullReconnect()
+            return
+        }
+        backoff.reset()
+        cancelRetry()
+        cancelGrace()
+        _attempts.value = 0
+        _state.value = LinkState.ONLINE
+        ensureEventsConnected()
+    }
+
+    private fun onProbeFailed() {
+        _attempts.value += 1
+        if (_state.value != LinkState.DOWN && _state.value != LinkState.UPDATING) {
+            _state.value = LinkState.RECONNECTING
+            armGrace()
+        }
+        scheduleRetry()
+    }
+
+    private fun armGrace() {
+        if (graceJob?.isActive == true) return
+        graceJob = scope.launch {
+            delay(GRACE_MS)
+            if (_state.value == LinkState.RECONNECTING) _state.value = LinkState.DOWN
+        }
+    }
+
+    private fun cancelGrace() {
+        graceJob?.cancel()
+        graceJob = null
+    }
+
+    private fun scheduleRetry() {
+        if (retryJob?.isActive == true) return
+        val delayMs = backoff.nextDelayMs()
+        retryJob = scope.launch {
+            delay(delayMs)
+            retryJob = null
+            probeNow()
+        }
+    }
+
+    private fun cancelRetry() {
+        retryJob?.cancel()
+        retryJob = null
+        backoff.reset()
+    }
+
+    /** A build-stamp change: drop the events socket and the catalog it fed,
+     * then probe again shortly. The re-probe sees the same identity it just
+     * recorded, so it resolves straight to [LinkState.ONLINE] and reopens
+     * the socket — this *is* the full reconnect. */
+    private fun fullReconnect() {
+        closeEvents()
+        catalog.clear()
+        backoff.reset()
+        scope.launch {
+            delay(200)
+            probeNow()
+        }
+    }
+
+    private fun handleSocketDropped() {
+        if (_state.value == LinkState.DOWN || _state.value == LinkState.UPDATING) return
+        _state.value = LinkState.RECONNECTING
+        armGrace()
+        probeNow()
+    }
+
+    private fun handleBaseUrlChanged(url: String) {
+        currentBaseUrl = url
+        generation += 1
+        client = MaestroClient(url, httpClient)
+        socket = MaestroWebSocket(url, httpClient)
+        identity = null
+        _build.value = null
+        _attempts.value = 0
+        backoff.reset()
+        cancelRetry()
+        cancelGrace()
+        closeEvents()
+        catalog.clear()
+        _state.value = LinkState.CONNECTING
+        probeNow()
+    }
+
+    /** The broadcast channel dropped frames: re-fetch the full list over REST
+     * rather than trusting the map to still be complete. */
+    private fun handleLagged() {
+        val currentClient = client
+        scope.launch {
+            runCatching { currentClient.listSessions() }.onSuccess { catalog.replace(it) }
+        }
+    }
+
+    private fun ensureEventsConnected() {
+        if (eventsJob?.isActive == true) return
+        val connection = socket.connectEvents()
+        eventsConnection = connection
+        eventsJob = scope.launch {
+            try {
+                connection.events.collect { event ->
+                    val skipped = catalog.apply(event)
+                    if (skipped != null) signals.trySend(Signal.Lagged(skipped))
+                }
+                signals.trySend(Signal.SocketDropped)
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                signals.trySend(Signal.SocketDropped)
+            }
+        }
+    }
+
+    private fun closeEvents() {
+        eventsJob?.cancel()
+        eventsJob = null
+        eventsConnection?.close()
+        eventsConnection = null
+    }
+}

android/app/src/main/java/pt/naps/maestro/connection/DaemonPrefs.kt

@@ -0,0 +1,40 @@
+package pt.naps.maestro.connection
+
+import android.content.Context
+import androidx.core.content.edit
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Where the daemon base URL lives between launches. A settings screen and
+ * the [EXTRA_DAEMON_URL] intent extra both write through here; [DaemonLink]
+ * reads [baseUrl] and reconnects on change.
+ */
+class DaemonPrefs(context: Context) {
+    private val prefs = context.applicationContext.getSharedPreferences(FILE, Context.MODE_PRIVATE)
+
+    private val _baseUrl =
+        MutableStateFlow(prefs.getString(KEY_BASE_URL, DEFAULT_BASE_URL) ?: DEFAULT_BASE_URL)
+    val baseUrl: StateFlow<String> = _baseUrl.asStateFlow()
+
+    fun setBaseUrl(url: String) {
+        val trimmed = url.trim()
+        if (trimmed.isEmpty() || trimmed == _baseUrl.value) return
+        prefs.edit { putString(KEY_BASE_URL, trimmed) }
+        _baseUrl.value = trimmed
+    }
+
+    companion object {
+        private const val FILE = "daemon_prefs"
+        private const val KEY_BASE_URL = "base_url"
+
+        /** Shown until the user points the app at their own daemon. */
+        const val DEFAULT_BASE_URL = "http://192.168.1.x:7070"
+
+        /** Intent extra a launcher may set to point this launch at a specific
+         * daemon without going through settings. Persisted on read, so it
+         * sticks after the launch that carried it. */
+        const val EXTRA_DAEMON_URL = "pt.naps.maestro.EXTRA_DAEMON_URL"
+    }
+}

android/app/src/main/java/pt/naps/maestro/connection/LinkState.kt

@@ -0,0 +1,14 @@
+package pt.naps.maestro.connection
+
+/**
+ * Connection lifecycle to the daemon. Mirrors the states in
+ * `web/src/components/daemon/DaemonLink.tsx` / `crates/maestro-tui/src/daemon_link.rs`
+ * (see `docs/RESTART.md`), plus [UPDATING] for a build-stamp change.
+ *
+ * - [CONNECTING] — first probe hasn't landed yet.
+ * - [ONLINE] — the daemon answered and identity is settled.
+ * - [RECONNECTING] — the link dropped, still inside the grace window.
+ * - [DOWN] — unreachable past the grace window; the restart overlay blocks.
+ * - [UPDATING] — the daemon answered on a different commit; reconnecting fresh.
+ */
+enum class LinkState { CONNECTING, ONLINE, RECONNECTING, DOWN, UPDATING }

android/app/src/main/java/pt/naps/maestro/data/ActivityState.kt

@@ -0,0 +1,43 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.descriptors.PrimitiveKind
+import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+
+/**
+ * Session activity, orthogonal to [SessionStatus]. Mirrors
+ * `maestro_protocol::ActivityState`.
+ *
+ * Deserializes leniently: an unknown variant from a newer daemon decodes as
+ * [Idle] instead of failing the whole [Session].
+ */
+@Serializable(with = ActivityStateSerializer::class)
+enum class ActivityState {
+    Active,
+    Idle,
+    AwaitingInput,
+    Error,
+    Starting,
+}
+
+object ActivityStateSerializer : KSerializer<ActivityState> {
+    override val descriptor: SerialDescriptor =
+        PrimitiveSerialDescriptor("ActivityState", PrimitiveKind.STRING)
+
+    override fun serialize(encoder: Encoder, value: ActivityState) {
+        encoder.encodeString(value.name)
+    }
+
+    override fun deserialize(decoder: Decoder): ActivityState =
+        when (decoder.decodeString()) {
+            "Active" -> ActivityState.Active
+            "AwaitingInput" -> ActivityState.AwaitingInput
+            "Error" -> ActivityState.Error
+            "Starting" -> ActivityState.Starting
+            else -> ActivityState.Idle
+        }
+}

android/app/src/main/java/pt/naps/maestro/data/ApiError.kt

@@ -0,0 +1,19 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** Structured failure body inside an [ApiError] envelope. Mirrors
+ * `maestro_protocol::ErrorInfo`. */
+@Serializable
+data class ErrorInfo(
+    val code: String,
+    val message: String,
+    /** Set only by the kill guard: what blocked an unforced
+     * `DELETE /api/sessions/:id`. */
+    val unsaved_work: InTheWay? = null,
+)
+
+/** The envelope every `/api` failure is wrapped in: `{"error": {...}}`.
+ * Mirrors `maestro_protocol::ApiError`. */
+@Serializable
+data class ApiError(val error: ErrorInfo)

android/app/src/main/java/pt/naps/maestro/data/BranchInfo.kt

@@ -0,0 +1,17 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** One local branch of a repository, from `GET /api/branches`. A client
+ * disables the entry when [is_head] is set or [worktree] is present — git
+ * refuses to check the same branch out in two worktrees at once. Mirrors
+ * `maestro_protocol::BranchInfo`. */
+@Serializable
+data class BranchInfo(
+    /** Short branch name (`main`, `feature/foo`). */
+    val name: String,
+    /** Whether this branch is the main checkout's current HEAD. */
+    val is_head: Boolean,
+    /** Toplevel path of the linked worktree holding this branch, if any. */
+    val worktree: String? = null,
+)

android/app/src/main/java/pt/naps/maestro/data/CatalogEvent.kt

@@ -0,0 +1,37 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Messages the daemon broadcasts to clients over `WS /api/events`. Mirrors
+ * `maestro_protocol::CatalogEvent`; tagged by a `type` field.
+ *
+ * A subscriber receives a single [Snapshot] immediately on connect, then a
+ * stream of deltas as sessions are created, updated, and killed. Skipped
+ * events (broadcast channel lag) surface as [Lagged].
+ */
+@Serializable
+sealed class CatalogEvent {
+    @Serializable
+    @SerialName("Snapshot")
+    data class Snapshot(val sessions: List<Session>) : CatalogEvent()
+
+    @Serializable
+    @SerialName("SessionAdded")
+    data class SessionAdded(val session: Session) : CatalogEvent()
+
+    @Serializable
+    @SerialName("SessionRemoved")
+    data class SessionRemoved(val id: Uuid) : CatalogEvent()
+
+    @Serializable
+    @SerialName("SessionUpdated")
+    data class SessionUpdated(val session: Session) : CatalogEvent()
+
+    /** Server-issued notification that the broadcast queue dropped frames.
+     * Clients should re-fetch a full snapshot. */
+    @Serializable
+    @SerialName("Lagged")
+    data class Lagged(val skipped: Long) : CatalogEvent()
+}

android/app/src/main/java/pt/naps/maestro/data/ClientControl.kt

@@ -0,0 +1,30 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/** Text-frame control messages on a `WS /api/attach/:id` connection. PTY
+ * bytes travel in binary frames and are not modeled here. Mirrors
+ * `maestro_protocol::ClientControl`; tagged by a `type` field. */
+@Serializable
+sealed class ClientControl {
+    @Serializable
+    @SerialName("Resize")
+    data class Resize(val cols: Int, val rows: Int) : ClientControl()
+
+    @Serializable
+    @SerialName("Ping")
+    object Ping : ClientControl()
+
+    @Serializable
+    @SerialName("Pong")
+    object Pong : ClientControl()
+
+    @Serializable
+    @SerialName("Error")
+    data class Error(
+        val code: String,
+        val message: String,
+        val unsaved_work: InTheWay? = null,
+    ) : ClientControl()
+}

android/app/src/main/java/pt/naps/maestro/data/DaemonInfo.kt

@@ -0,0 +1,41 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** `GET /api/info` — the daemon's identity plus its spawn presets. Mirrors
+ * `maestro_protocol::DaemonInfo`. */
+@Serializable
+data class DaemonInfo(
+    val hostname: String = "",
+    /** The protocol version the daemon implements. */
+    val version: String = "",
+    /** Home dir of the user the daemon runs as; empty for older daemons. */
+    val home_dir: String = "",
+    val presets: List<SpawnPreset> = emptyList(),
+    val build: BuildInfo = BuildInfo(),
+    /** Identity of the daemon *process*, regenerated on every start — a
+     * changed value across a reconnect means the daemon restarted. */
+    val instance: String = "",
+    /** Canonical leader key the operator configured (`[tui].leader`), so a
+     * client binds the same chord the TUI does. Empty means "use your
+     * default". */
+    val leader: String = "",
+)
+
+/** A spawn-form command preset advertised by the daemon. */
+@Serializable
+data class SpawnPreset(
+    val id: String,
+    val label: String,
+    val command: String,
+    val auto_approve: Boolean = false,
+)
+
+/** Build provenance of the running daemon. Every field is empty when the
+ * binary was built outside a git checkout. */
+@Serializable
+data class BuildInfo(
+    val commit: String = "",
+    val commit_date: String = "",
+    val dirty: Boolean = false,
+)

android/app/src/main/java/pt/naps/maestro/data/Dirs.kt

@@ -0,0 +1,33 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** `GET /api/dirs?path=` — one directory's immediate subdirectories. Mirrors
+ * `maestro_protocol::DirListing`. */
+@Serializable
+data class DirListing(
+    /** Resolved absolute directory that was listed (after ~/relative
+     * expansion). */
+    val path: String,
+    /** Immediate subdirectory names, sorted case-insensitively. */
+    val entries: List<String> = emptyList(),
+    /** True when the listing was capped server-side. */
+    val truncated: Boolean = false,
+)
+
+/** One deduplicated recent working dir for the spawn form's recents picker.
+ * Mirrors `maestro_protocol::RecentDir`. */
+@Serializable
+data class RecentDir(
+    val cwd: String,
+    val last_command: String,
+    val last_used: IsoTimestamp,
+)
+
+/** `GET /api/recent-dirs` — the daemon's recent working dirs, newest-first
+ * and deduped by `cwd`. */
+@Serializable
+data class RecentDirs(
+    val dirs: List<RecentDir> = emptyList(),
+    val truncated: Boolean = false,
+)

android/app/src/main/java/pt/naps/maestro/data/GitRoot.kt

@@ -0,0 +1,9 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** `GET /api/gitroot?path=` — the enclosing repo toplevel of a path, or
+ * `null` when the path isn't inside a repo. Mirrors
+ * `maestro_protocol::GitRoot`. */
+@Serializable
+data class GitRoot(val root: String? = null)

android/app/src/main/java/pt/naps/maestro/data/Ids.kt

@@ -0,0 +1,7 @@
+package pt.naps.maestro.data
+
+/** A session id. Mirrors `uuid::Uuid` on the wire — a plain UUID string. */
+typealias Uuid = String
+
+/** An RFC 3339 timestamp, as the daemon serializes `chrono::DateTime<Utc>`. */
+typealias IsoTimestamp = String

android/app/src/main/java/pt/naps/maestro/data/InTheWay.kt

@@ -0,0 +1,17 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** What currently blocks an unforced kill of a session's worktree,
+ * recomputed by the daemon on every read. Mirrors
+ * `maestro_protocol::InTheWay`. */
+@Serializable
+data class InTheWay(
+    val uncommitted_files: Int = 0,
+    val untracked_files: Int = 0,
+    val unpushed_commits: Int = 0,
+    /** Lines added across the tracked changes, staged and unstaged together. */
+    val insertions: Int = 0,
+    /** Lines removed across the same tracked changes. */
+    val deletions: Int = 0,
+)

android/app/src/main/java/pt/naps/maestro/data/NameBatch.kt

@@ -0,0 +1,8 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** `GET /api/names?count=N` — a batch of fresh session handles. Mirrors
+ * `maestro_protocol::NameBatch`. */
+@Serializable
+data class NameBatch(val names: List<String>)

android/app/src/main/java/pt/naps/maestro/data/NameSource.kt

@@ -0,0 +1,40 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.descriptors.PrimitiveKind
+import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+
+/**
+ * Where a session's stored name (`metadata["name"]`) came from. Mirrors
+ * `maestro_protocol::NameSource`.
+ *
+ * Deserializes leniently: an unknown spelling decodes as [User], the settled
+ * variant — a name wrongly painted as settled is only a missed dimming; one
+ * wrongly painted as provisional invites overwriting a name a person chose.
+ */
+@Serializable(with = NameSourceSerializer::class)
+enum class NameSource {
+    User,
+    Generated,
+    Haiku,
+}
+
+object NameSourceSerializer : KSerializer<NameSource> {
+    override val descriptor: SerialDescriptor =
+        PrimitiveSerialDescriptor("NameSource", PrimitiveKind.STRING)
+
+    override fun serialize(encoder: Encoder, value: NameSource) {
+        encoder.encodeString(value.name)
+    }
+
+    override fun deserialize(decoder: Decoder): NameSource =
+        when (decoder.decodeString()) {
+            "Generated" -> NameSource.Generated
+            "Haiku" -> NameSource.Haiku
+            else -> NameSource.User
+        }
+}

android/app/src/main/java/pt/naps/maestro/data/Project.kt

@@ -0,0 +1,21 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+
+/** One discovered git repository (or linked worktree) for `GET
+ * /api/projects`. Mirrors `maestro_protocol::Project`. */
+@Serializable
+data class Project(
+    /** Absolute path of the repository/worktree toplevel. */
+    val path: String,
+    /** Basename of [path]. */
+    val name: String,
+    val is_worktree: Boolean = false,
+    /** The main checkout this worktree belongs to; `null` on plain repos. */
+    val base_repo: String? = null,
+    /** Later of the repo's git HEAD mtime and the newest spawn-history use of
+     * any directory inside it; `null` when neither is known. */
+    val last_activity: IsoTimestamp? = null,
+    /** Command last spawned in this project, from spawn history. */
+    val last_command: String? = null,
+)

android/app/src/main/java/pt/naps/maestro/data/Session.kt

@@ -0,0 +1,71 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/** Default for [Session.last_activity_at] / [Session.activity_since] when an
+ * older payload omits them — mirrors the daemon's Unix-epoch default. */
+const val EPOCH: IsoTimestamp = "1970-01-01T00:00:00Z"
+
+/** A live or recently-dead tmux session managed by the daemon. Mirrors
+ * `maestro_protocol::Session`. */
+@Serializable
+data class Session(
+    val id: Uuid,
+    val cwd: String,
+    val command: String,
+    val env: Map<String, String> = emptyMap(),
+    val metadata: Map<String, JsonElement> = emptyMap(),
+    /** The worktree this session owns, when it was spawned with one. */
+    val worktree: SessionWorktree? = null,
+    val status: SessionStatus,
+    val created_at: IsoTimestamp,
+    /** Current foreground command in the pane (e.g. `claude`, `bash`), as the
+     * daemon's activity watcher observed it. `null` until observed. */
+    val foreground: String? = null,
+    /** Inferred activity dimension, orthogonal to [status]. */
+    val activity: ActivityState = ActivityState.Idle,
+    /** Short human string an agent reported alongside its activity — e.g. why
+     * it is in [ActivityState.Error]. `null` unless an agent reported one. */
+    val activity_detail: String? = null,
+    val last_activity_at: IsoTimestamp = EPOCH,
+    val activity_since: IsoTimestamp = EPOCH,
+    /** The pane's *current* working directory, distinct from [cwd] (the spawn
+     * dir). `null` until first observed. */
+    val current_cwd: String? = null,
+    /** What currently blocks an unforced kill of this session, as the
+     * daemon's watcher last probed it. `null` while clear or not yet probed. */
+    val blocked_work: InTheWay? = null,
+    /** When this session last became the pane a client was showing. `null`
+     * until the session has been focused at least once. */
+    val last_focused_at: IsoTimestamp? = null,
+    /** Terminal (PTY bytes) or structured (ACP rows). Fixed at spawn and
+     * immutable for the session's life. */
+    val view: SessionView = SessionView.Terminal,
+    /** The ACP session id the selected provider adapter returned from
+     * `session/new`. Only a [SessionView.Structured] session whose handshake
+     * succeeded has one. */
+    val acp_session_id: String? = null,
+    /** When `true`, the daemon auto-approves every ACP permission request for
+     * this session instead of surfacing them to the client. */
+    val auto_approve: Boolean = false,
+    /** Prompts queued on the daemon while a turn was in flight or the adapter
+     * was still booting. */
+    val queued_prompts: List<String> = emptyList(),
+)
+
+@Serializable
+enum class SessionStatus { Running, Dead }
+
+/** A session's process shape: mirrors `maestro_protocol::SessionView`.
+ * `Terminal` is the default. */
+@Serializable
+enum class SessionView { Terminal, Structured }
+
+/** A session's daemon-created worktree. `base_repo` is the repository's main
+ * checkout, which is what the session tree groups by. */
+@Serializable
+data class SessionWorktree(
+    val path: String,
+    val base_repo: String,
+)

android/app/src/main/java/pt/naps/maestro/data/SessionRequests.kt

@@ -0,0 +1,43 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/** `POST /api/sessions` body. Mirrors
+ * `maestro_protocol::CreateSessionRequest`. */
+@Serializable
+data class CreateSessionRequest(
+    val cwd: String,
+    val command: String,
+    val env: Map<String, String> = emptyMap(),
+    val metadata: Map<String, JsonElement> = emptyMap(),
+    val worktree: WorktreeSpec? = null,
+    /** The process shape to spawn. Defaults to a `Terminal` session. */
+    val view: SessionView = SessionView.Terminal,
+    /** When `true`, the daemon auto-approves every ACP permission request for
+     * this structured session. */
+    val auto_approve: Boolean = false,
+)
+
+/** Optional worktree request attached to a [CreateSessionRequest]. Mirrors
+ * `maestro_protocol::WorktreeSpec`. */
+@Serializable
+data class WorktreeSpec(
+    val base_repo: String,
+    val branch: String,
+    /** When `false`, [branch] already exists and is checked out as-is.
+     * Defaults to `true` (create a new branch). */
+    val create_branch: Boolean = true,
+)
+
+/** `PATCH /api/sessions/:id` body: rename a live session. An empty [name]
+ * clears the custom one, so the card falls back to the command. Mirrors
+ * `maestro_protocol::RenameSessionRequest`. */
+@Serializable
+data class RenameSessionRequest(val name: String)
+
+/** `POST /api/sessions/:id/focus` body: a client reports whether its pane is
+ * the one currently showing this session. Mirrors
+ * `maestro_protocol::SetFocusRequest`. */
+@Serializable
+data class SetFocusRequest(val focused: Boolean)

android/app/src/main/java/pt/naps/maestro/data/Structured.kt

@@ -0,0 +1,136 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/** The semantic shape of a [TranscriptRow]. Mirrors
+ * `maestro_protocol::TranscriptRowKind`, snake_case on the wire. */
+@Serializable
+enum class TranscriptRowKind {
+    @SerialName("user") User,
+    @SerialName("agent_text") AgentText,
+    @SerialName("agent_thought") AgentThought,
+    @SerialName("tool_call") ToolCall,
+    @SerialName("tool_diff") ToolDiff,
+    @SerialName("approval") Approval,
+    @SerialName("plan") Plan,
+    @SerialName("notice") Notice,
+}
+
+/** One client-neutral item in a structured session transcript. [data]
+ * preserves the ACP payload verbatim without committing to an ACP
+ * dependency. Mirrors `maestro_protocol::TranscriptRow`. */
+@Serializable
+data class TranscriptRow(
+    /** Stable within one session, so later deltas can address this row. */
+    val id: String,
+    val kind: TranscriptRowKind,
+    val data: JsonElement,
+)
+
+/** The complete transcript at a durable event-log position — a structured
+ * session's first `WS /api/structured/:id` message. Mirrors
+ * `maestro_protocol::TranscriptSnapshot`. */
+@Serializable
+data class TranscriptSnapshot(
+    val cursor: Long,
+    val rows: List<TranscriptRow> = emptyList(),
+)
+
+/** A change to one transcript row, addressed by [id]. Mirrors
+ * `maestro_protocol::TranscriptDelta`; tagged by a snake_case `type` field. */
+@Serializable
+sealed class TranscriptDelta {
+    @Serializable
+    @SerialName("append")
+    data class Append(val row: TranscriptRow) : TranscriptDelta()
+
+    @Serializable
+    @SerialName("patch")
+    data class Patch(val row: TranscriptRow) : TranscriptDelta()
+
+    @Serializable
+    @SerialName("remove")
+    data class Remove(val id: String) : TranscriptDelta()
+}
+
+/** Per-turn indicators derived from the ACP stream — read verbatim, never
+ * re-derived client-side. Mirrors `maestro_protocol::TurnState`. */
+@Serializable
+data class TurnState(
+    val responding: Boolean = false,
+    val thinking: Boolean = false,
+    val active_tool_calls: List<String> = emptyList(),
+    /** Wall-clock start of the active prompt, so a reconnecting client keeps
+     * one continuous elapsed-time display instead of restarting at zero. */
+    val started_at: IsoTimestamp? = null,
+    val started_context_tokens: Long? = null,
+)
+
+/**
+ * A whole-session view derived from ACP notifications. Mirrors
+ * `maestro_protocol::ReducedState`.
+ *
+ * [pending_approval], [plan], [usage], [context] and [config_options] carry
+ * opaque ACP JSON — their shape is ACP's, not covered by this crate's own
+ * compatibility guarantee, so they are kept as [JsonElement] rather than
+ * modeled strongly.
+ */
+@Serializable
+data class ReducedState(
+    val turn: TurnState = TurnState(),
+    val pending_approval: JsonElement? = null,
+    val plan: JsonElement? = null,
+    val usage: JsonElement? = null,
+    val context: JsonElement? = null,
+    val model: String? = null,
+    val mode: String? = null,
+    val config_options: JsonElement? = null,
+    /** Prompts queued on the daemon while a turn is in flight. */
+    val queued_prompts: List<String> = emptyList(),
+)
+
+/** Server messages on `WS /api/structured/:id`. Mirrors
+ * `maestro_protocol::StructuredEvent`; tagged by a snake_case `type` field. */
+@Serializable
+sealed class StructuredEvent {
+    @Serializable
+    @SerialName("transcript_snapshot")
+    data class TranscriptSnapshotEvent(val snapshot: TranscriptSnapshot) : StructuredEvent()
+
+    @Serializable
+    @SerialName("reduced_state")
+    data class ReducedStateEvent(val state: ReducedState) : StructuredEvent()
+
+    @Serializable
+    @SerialName("projection_update")
+    data class ProjectionUpdate(
+        val transcript: TranscriptDelta? = null,
+        val state: ReducedState,
+    ) : StructuredEvent()
+}
+
+/** `POST /api/sessions/:id/structured/prompt` body. */
+@Serializable
+data class StructuredPromptRequest(val prompt: String)
+
+/** `POST /api/sessions/:id/structured/config` body: change one option
+ * advertised by a live ACP session. */
+@Serializable
+data class StructuredConfigRequest(val config_id: String, val value: JsonElement)
+
+/** Operator decision for a pending ACP permission request
+ * (`POST /api/sessions/:id/structured/approvals/:nonce` body) — a bare JSON
+ * string on the wire, not `{decision: ...}`. Mirrors
+ * `maestro_protocol::StructuredApprovalDecision`. */
+@Serializable
+enum class StructuredApprovalDecision {
+    @SerialName("allow_once") AllowOnce,
+    @SerialName("allow_for_session") AllowForSession,
+    @SerialName("deny") Deny,
+}
+
+/** Response of `POST /api/sessions/:id/structured/attachments`. */
+@Serializable
+data class StructuredAttachmentResponse(val path: String)

android/app/src/main/java/pt/naps/maestro/ui/sidebar/ActivityRail.kt

@@ -0,0 +1,91 @@
+package pt.naps.maestro.ui.sidebar
+
+import androidx.compose.animation.animateColorAsState
+import androidx.compose.animation.core.InfiniteTransition
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxHeight
+import androidx.compose.foundation.layout.width
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+import pt.naps.maestro.data.ActivityState
+
+/** docs/SIDEBAR.md: the rail's width in the web client. Android mirrors it in
+ * density-independent pixels rather than raw pixels. */
+val ACTIVITY_RAIL_WIDTH = 7.dp
+
+private val RAIL_ACTIVE = Color(0xFF3DDC84)
+private val RAIL_IDLE = Color(0xFF9AA0A6)
+private val RAIL_AWAITING = Color(0xFFF5A623)
+private val RAIL_ERROR = Color(0xFFE5484D)
+
+/** Colour per activity state (docs/SIDEBAR.md's colour table): `Starting`
+ * shares `Idle`'s colour, and an unrecognised state degrades to `Idle` so
+ * rendering never fails (Precedence). */
+fun activityColor(activity: ActivityState): Color =
+    when (activity) {
+        ActivityState.Active -> RAIL_ACTIVE
+        ActivityState.AwaitingInput -> RAIL_AWAITING
+        ActivityState.Error -> RAIL_ERROR
+        ActivityState.Idle, ActivityState.Starting -> RAIL_IDLE
+    }
+
+/** The accessible name the rail carries, since colour is never the only
+ * signal (docs/SIDEBAR.md). */
+fun activityStateWord(activity: ActivityState): String =
+    when (activity) {
+        ActivityState.Active -> "Active"
+        ActivityState.Idle -> "Idle"
+        ActivityState.Starting -> "Starting"
+        ActivityState.AwaitingInput -> "Awaiting input"
+        ActivityState.Error -> "Error"
+    }
+
+/** A held bar that pulses its alpha between 1 and [minAlpha] every
+ * [periodMs] — the blink/flash motion `AwaitingInput`/`Error` earn. */
+@Composable
+private fun InfiniteTransition.pulsingAlpha(minAlpha: Float, periodMs: Int): Float {
+    val alpha by animateFloat(
+        initialValue = 1f,
+        targetValue = minAlpha,
+        animationSpec = infiniteRepeatable(
+            animation = tween(durationMillis = periodMs, easing = LinearEasing),
+            repeatMode = RepeatMode.Reverse,
+        ),
+        label = "activity-rail-alpha",
+    )
+    return alpha
+}
+
+/** The card's rail: a coloured bar in the gutter, full card height. It paints
+ * for every card, `Idle` included, and carries motion only for states that
+ * need attention — a hard blink for `AwaitingInput`, a fast flash for
+ * `Error`. `Active` and `Idle` stay solid; colour alone is their signal. */
+@Composable
+fun ActivityRail(activity: ActivityState, modifier: Modifier = Modifier) {
+    val color by animateColorAsState(targetValue = activityColor(activity), label = "activity-rail-color")
+    val infinite = rememberInfiniteTransition(label = "activity-rail-motion")
+    val alpha = when (activity) {
+        ActivityState.AwaitingInput -> infinite.pulsingAlpha(minAlpha = 0.35f, periodMs = 600)
+        ActivityState.Error -> infinite.pulsingAlpha(minAlpha = 0.25f, periodMs = 220)
+        else -> 1f
+    }
+    Box(
+        modifier = modifier
+            .fillMaxHeight()
+            .width(ACTIVITY_RAIL_WIDTH)
+            .semantics { contentDescription = activityStateWord(activity) }
+            .background(color.copy(alpha = alpha)),
+    )
+}

android/app/src/main/java/pt/naps/maestro/ui/sidebar/FolderNode.kt

@@ -0,0 +1,58 @@
+package pt.naps.maestro.ui.sidebar
+
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+
+/** docs/SIDEBAR.md: a collapsible directory in the sidebar tree. An expanded
+ * folder's cards are one row away, so it carries no highlight of its own —
+ * only a collapsed header is ever a keyboard-walk stop, but that distinction
+ * belongs to the caller driving the walk, not this composable. */
+@Composable
+fun FolderNode(
+    label: String,
+    collapsed: Boolean,
+    onToggle: () -> Unit,
+    modifier: Modifier = Modifier,
+    depthPadding: Int = 0,
+    content: @Composable () -> Unit,
+) {
+    Column(modifier = modifier) {
+        Row(
+            modifier = Modifier
+                .fillMaxWidth()
+                .clickable(onClick = onToggle)
+                .padding(start = depthPadding.dp, top = 6.dp, bottom = 6.dp, end = 8.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Text(
+                text = if (collapsed) "▸" else "▾",
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            Spacer(Modifier.width(6.dp))
+            Text(
+                text = label,
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+        }
+        AnimatedVisibility(visible = !collapsed) {
+            Column { content() }
+        }
+    }
+}

android/app/src/main/java/pt/naps/maestro/ui/sidebar/SessionCard.kt

@@ -0,0 +1,242 @@
+package pt.naps.maestro.ui.sidebar
+
+import androidx.compose.foundation.ExperimentalFoundationApi
+import androidx.compose.foundation.combinedClickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.ImeAction
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import pt.naps.maestro.data.InTheWay
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.SessionStatus
+
+/** docs/SIDEBAR.md: a card is always two lines behind an activity rail —
+ * line 1 the name, line 2 the adaptive meta line. Long-press opens a context
+ * menu (Rename / Kill / Spawn similar); the daemon confirms rename and kill
+ * only through the callbacks the caller supplies. */
+@OptIn(ExperimentalFoundationApi::class)
+@Composable
+fun SessionCard(
+    session: Session,
+    nowMs: Long,
+    modifier: Modifier = Modifier,
+    depthPadding: Int = 0,
+    onOpen: (Session) -> Unit = {},
+    onRename: (Session, String) -> Unit = { _, _ -> },
+    onKill: (Session) -> Unit = {},
+    onSpawnSimilar: (Session) -> Unit = {},
+) {
+    var menuExpanded by remember { mutableStateOf(false) }
+    var renaming by remember { mutableStateOf(false) }
+    var confirmingKill by remember { mutableStateOf(false) }
+
+    val running = session.status == SessionStatus.Running
+    val name = sessionName(session)
+    val muted = isProvisionalName(session)
+
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .combinedClickable(
+                onClick = { onOpen(session) },
+                onLongClick = { menuExpanded = true },
+            )
+            .padding(start = (8 + depthPadding).dp, end = 8.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        ActivityRail(activity = session.activity, modifier = Modifier.height(36.dp))
+        Spacer(Modifier.width(8.dp))
+        Column(modifier = Modifier.fillMaxWidth()) {
+            Text(
+                text = name,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                color = when {
+                    !running -> MaterialTheme.colorScheme.onSurfaceVariant
+                    muted -> MaterialTheme.colorScheme.onSurfaceVariant
+                    else -> MaterialTheme.colorScheme.onSurface
+                },
+                style = MaterialTheme.typography.bodyMedium,
+            )
+            MetaLine(session = session, nowMs = nowMs)
+        }
+    }
+
+    DropdownMenu(expanded = menuExpanded, onDismissRequest = { menuExpanded = false }) {
+        DropdownMenuItem(
+            text = { Text("Rename") },
+            onClick = {
+                menuExpanded = false
+                renaming = true
+            },
+        )
+        DropdownMenuItem(
+            text = { Text("Spawn similar") },
+            onClick = {
+                menuExpanded = false
+                onSpawnSimilar(session)
+            },
+        )
+        DropdownMenuItem(
+            text = { Text("Kill") },
+            onClick = {
+                menuExpanded = false
+                confirmingKill = true
+            },
+        )
+    }
+
+    if (renaming) {
+        RenameDialog(
+            initial = customSessionName(session) ?: "",
+            onCommit = {
+                renaming = false
+                onRename(session, it)
+            },
+            onCancel = { renaming = false },
+        )
+    }
+
+    if (confirmingKill) {
+        KillConfirmDialog(
+            session = session,
+            onConfirm = {
+                confirmingKill = false
+                onKill(session)
+            },
+            onCancel = { confirmingKill = false },
+        )
+    }
+}
+
+/** Line 2, left to right: `[duration] [detail] command [diff stat | exited]`
+ * — the line itself is unconditional, only its fragments are adaptive. */
+@Composable
+fun MetaLine(session: Session, nowMs: Long, modifier: Modifier = Modifier) {
+    val heldMs = activityHeldMs(session.activity_since, nowMs)
+    val duration = if (heldMs != null && heldMs >= META_LINE_MIN_HOLD_MS) {
+        activityDurationLabel(heldMs)
+    } else {
+        null
+    }
+    val blockers = sessionBlockers(session)
+
+    Row(modifier = modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+        if (duration != null) {
+            Text(
+                text = duration,
+                color = activityColor(session.activity),
+                style = MaterialTheme.typography.labelSmall,
+            )
+            Spacer(Modifier.width(6.dp))
+        }
+        if (session.activity_detail != null) {
+            Text(
+                text = session.activity_detail,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                style = MaterialTheme.typography.labelSmall,
+                modifier = Modifier.weight(1f, fill = false),
+            )
+            Spacer(Modifier.width(6.dp))
+        }
+        Text(
+            text = programName(session.command),
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            style = MaterialTheme.typography.labelSmall,
+        )
+        if (blockers != null) {
+            Spacer(Modifier.width(6.dp))
+            BlockedFragment(blockers)
+        }
+        if (session.status == SessionStatus.Dead) {
+            Spacer(Modifier.width(6.dp))
+            Text(
+                text = "exited",
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                style = MaterialTheme.typography.labelSmall,
+            )
+        }
+    }
+}
+
+@Composable
+private fun BlockedFragment(blockers: InTheWay) {
+    Row(verticalAlignment = Alignment.CenterVertically) {
+        blockerStats(blockers).forEachIndexed { index, stat ->
+            if (index > 0) Spacer(Modifier.width(4.dp))
+            Text(
+                text = stat.text,
+                style = MaterialTheme.typography.labelSmall,
+                color = when (stat.kind) {
+                    "add" -> MaterialTheme.colorScheme.primary
+                    "del" -> MaterialTheme.colorScheme.error
+                    else -> MaterialTheme.colorScheme.onSurfaceVariant
+                },
+            )
+        }
+    }
+}
+
+@Composable
+private fun RenameDialog(initial: String, onCommit: (String) -> Unit, onCancel: () -> Unit) {
+    var text by remember { mutableStateOf(initial) }
+    AlertDialog(
+        onDismissRequest = onCancel,
+        title = { Text("Rename session") },
+        text = {
+            OutlinedTextField(
+                value = text,
+                onValueChange = { text = it },
+                singleLine = true,
+                keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
+            )
+        },
+        confirmButton = { TextButton(onClick = { onCommit(text.trim()) }) { Text("Rename") } },
+        dismissButton = { TextButton(onClick = onCancel) { Text("Cancel") } },
+    )
+}
+
+@Composable
+private fun KillConfirmDialog(session: Session, onConfirm: () -> Unit, onCancel: () -> Unit) {
+    val blockers = sessionBlockers(session)
+    AlertDialog(
+        onDismissRequest = onCancel,
+        title = { Text("Kill “${sessionName(session)}”?") },
+        text = {
+            Text(
+                if (blockers != null) {
+                    "This worktree has unsaved work: ${formatInTheWay(blockers)}. Killing may be refused unless forced."
+                } else {
+                    "This ends the session's process. This can't be undone."
+                },
+            )
+        },
+        confirmButton = { TextButton(onClick = onConfirm) { Text("Kill") } },
+        dismissButton = { TextButton(onClick = onCancel) { Text("Cancel") } },
+    )
+}

android/app/src/main/java/pt/naps/maestro/ui/sidebar/SessionFormatting.kt

@@ -0,0 +1,161 @@
+package pt.naps.maestro.ui.sidebar
+
+import java.time.Instant
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.jsonPrimitive
+import pt.naps.maestro.data.InTheWay
+import pt.naps.maestro.data.NameSource
+import pt.naps.maestro.data.Session
+
+/** docs/SIDEBAR.md: a state held shorter than this has no duration fragment. */
+const val META_LINE_MIN_HOLD_MS: Long = 30_000L
+
+/** Payloads predating #102 default `activity_since` to the Unix epoch;
+ * anything implausibly old is "never observed" rather than a huge duration. */
+private val PLAUSIBLE_EPOCH_MS = Instant.parse("2010-01-01T00:00:00Z").toEpochMilli()
+
+/** Milliseconds held in the current activity state, or `null` when `since` is
+ * missing/unparsable/implausible. Mirrors the web's `activityHeldMs`. */
+fun activityHeldMs(since: String?, nowMs: Long): Long? {
+    if (since.isNullOrEmpty()) return null
+    val t = runCatching { Instant.parse(since).toEpochMilli() }.getOrNull() ?: return null
+    if (t < PLAUSIBLE_EPOCH_MS) return null
+    return (nowMs - t).coerceAtLeast(0L)
+}
+
+/** `<60s` whole seconds, `<60m` whole minutes, else whole hours — floored
+ * everywhere so the counter never shows a duration the state hasn't reached. */
+fun activityDurationLabel(heldMs: Long): String {
+    val seconds = heldMs / 1000
+    if (seconds < 60) return "${seconds}s"
+    val minutes = seconds / 60
+    if (minutes < 60) return "${minutes}m"
+    return "${minutes / 60}h"
+}
+
+/** The session's own name (#125), without the command fallback: `null` for a
+ * session that was never given one. */
+fun customSessionName(session: Session): String? {
+    val element = session.metadata["name"] ?: return null
+    val primitive = element as? JsonPrimitive ?: return null
+    if (!primitive.isString) return null
+    return primitive.content.takeIf { it.isNotEmpty() }
+}
+
+/** Line 1's name: `metadata.name` if present, else the command line. */
+fun sessionName(session: Session): String = customSessionName(session) ?: session.command
+
+/** Where the session's name came from (#131), read leniently: anything
+ * unrecognised — including a session named before the field existed — reads
+ * as [NameSource.User], so an existing name is never dimmed or overwritten. */
+fun sessionNameSource(session: Session): NameSource {
+    val element = session.metadata["name_source"] as? JsonPrimitive ?: return NameSource.User
+    return when (element.jsonPrimitive.content) {
+        "Generated" -> NameSource.Generated
+        "Haiku" -> NameSource.Haiku
+        else -> NameSource.User
+    }
+}
+
+/** Whether line 1 renders the name muted (#131): a handle the daemon
+ * generated at spawn and may still replace with one derived from the first
+ * prompt. */
+fun isProvisionalName(session: Session): Boolean =
+    customSessionName(session) != null && sessionNameSource(session) == NameSource.Generated
+
+/** One fragment of the compact blocked-work stat (docs/SIDEBAR.md). `kind`
+ * picks the colour; `text` is what the card prints. */
+data class BlockerStat(val kind: String, val text: String)
+
+/** #83: this session's blocked-work breakdown when something actually blocks
+ * an unforced kill; `null` while clear or not yet probed. */
+fun sessionBlockers(session: Session): InTheWay? {
+    val w = session.blocked_work ?: return null
+    val blocked = w.uncommitted_files > 0 || w.untracked_files > 0 || w.unpushed_commits > 0
+    return if (blocked) w else null
+}
+
+/** The blocked-work breakdown as diff notation: `+124 -18 ?3 ↑2`. A tree whose
+ * only tracked change carries no line delta falls back to the file count
+ * (`~2`) rather than claiming `+0 -0`. */
+fun blockerStats(w: InTheWay): List<BlockerStat> {
+    val stats = mutableListOf<BlockerStat>()
+    if (w.insertions > 0 || w.deletions > 0) {
+        if (w.insertions > 0) stats += BlockerStat("add", "+${w.insertions}")
+        if (w.deletions > 0) stats += BlockerStat("del", "-${w.deletions}")
+    } else if (w.uncommitted_files > 0) {
+        stats += BlockerStat("files", "~${w.uncommitted_files}")
+    }
+    if (w.untracked_files > 0) stats += BlockerStat("untracked", "?${w.untracked_files}")
+    if (w.unpushed_commits > 0) stats += BlockerStat("unpushed", "↑${w.unpushed_commits}")
+    return stats
+}
+
+/** The spelled-out phrasing shared by the kill refusal and every client's
+ * tooltip, so no two describe the same tree differently. */
+fun formatInTheWay(w: InTheWay): String {
+    val parts = mutableListOf<String>()
+    fun push(n: Int, unit: String) {
+        if (n <= 0) return
+        parts += if (n == 1) "1 $unit" else "$n ${unit}s"
+    }
+    push(w.uncommitted_files, "uncommitted file")
+    push(w.untracked_files, "untracked file")
+    push(w.unpushed_commits, "unpushed commit")
+    return if (parts.isNotEmpty()) parts.joinToString(", ") else "no unsaved work"
+}
+
+private val ENV_ASSIGNMENT = Regex("^[A-Za-z_][A-Za-z0-9_]*=.*$")
+private val PLAIN_WRAPPERS = setOf("sudo", "env")
+private val DLX_CAPABLE = setOf("pnpm", "yarn")
+
+/** The program a command line runs — never its arguments (docs/SIDEBAR.md).
+ * Looks through leading `FOO=bar` assignments, `sudo`/`env` wrappers (and
+ * their own flags), and JS-toolchain launchers (`npx`, `bunx`, `pnpm`/`yarn
+ * dlx`), then basenames what is left. A command that is nothing but wrappers
+ * is returned as written rather than as an empty string. */
+fun programName(command: String): String {
+    val trimmed = command.trim()
+    val words = trimmed.split(Regex("\\s+")).filter { it.isNotEmpty() }
+    if (words.isEmpty()) return trimmed
+
+    var i = 0
+    while (i < words.size && ENV_ASSIGNMENT.matches(words[i])) i++
+    while (i < words.size && words[i] in PLAIN_WRAPPERS) {
+        i++
+        while (i < words.size && (ENV_ASSIGNMENT.matches(words[i]) || words[i].startsWith("-"))) i++
+    }
+    if (i >= words.size) return basename(words.last())
+
+    when {
+        words[i] in DLX_CAPABLE && words.getOrNull(i + 1) == "dlx" -> i += 2
+        words[i] == "npx" || words[i] == "bunx" -> i += 1
+        words[i] == "bun" && words.getOrNull(i + 1) == "x" -> i += 2
+    }
+    val program = words.getOrNull(i) ?: return basename(words.last())
+    return basename(program)
+}
+
+private fun basename(path: String): String = path.substringAfterLast('/')
+
+/** Sessions are grouped by the repository they belong to (#265): a
+ * worktree's `base_repo`, or the session's own `cwd` when it owns none. */
+fun sessionGroupKey(session: Session): String = session.worktree?.base_repo ?: session.cwd
+
+/** One folder in the sidebar tree: a repo/cwd group and the sessions in it,
+ * sorted by name. */
+data class SessionGroup(val key: String, val label: String, val sessions: List<Session>)
+
+/** Group sessions by [sessionGroupKey], each group sorted by name and the
+ * groups themselves sorted by label. */
+fun groupSessions(sessions: Collection<Session>): List<SessionGroup> =
+    sessions
+        .groupBy(::sessionGroupKey)
+        .map { (key, members) ->
+            SessionGroup(
+                key = key,
+                label = key.trimEnd('/').substringAfterLast('/').ifEmpty { key },
+                sessions = members.sortedBy { sessionName(it).lowercase() },
+            )
+        }
+        .sortedBy { it.label.lowercase() }

android/app/src/main/java/pt/naps/maestro/ui/sidebar/SidebarContent.kt

@@ -0,0 +1,123 @@
+package pt.naps.maestro.ui.sidebar
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import kotlinx.coroutines.delay
+import pt.naps.maestro.connection.CatalogStore
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.Uuid
+
+/** A clock that advances at least once every 30s (docs/SIDEBAR.md), ticked
+ * faster than that so a duration's cutover lands within one visible frame. */
+@Composable
+fun rememberTickingNowMs(periodMs: Long = 5_000L): Long {
+    var now by remember { mutableStateOf(System.currentTimeMillis()) }
+    LaunchedEffect(periodMs) {
+        while (true) {
+            delay(periodMs)
+            now = System.currentTimeMillis()
+        }
+    }
+    return now
+}
+
+/** Assembles the full sidebar from the [CatalogStore] built in #264: sessions
+ * grouped into collapsible folders by repository, each rendered as a
+ * two-line [SessionCard] behind its [ActivityRail]. */
+@Composable
+fun SidebarContent(
+    catalogStore: CatalogStore,
+    onOpenSession: (Session) -> Unit,
+    modifier: Modifier = Modifier,
+    onRenameSession: (Uuid, String) -> Unit = { _, _ -> },
+    onKillSession: (Uuid) -> Unit = {},
+    onSpawnSimilar: (Session) -> Unit = {},
+) {
+    val sessions by catalogStore.sessions.collectAsState()
+    SidebarContent(
+        sessions = sessions.values.toList(),
+        onOpenSession = onOpenSession,
+        modifier = modifier,
+        onRenameSession = onRenameSession,
+        onKillSession = onKillSession,
+        onSpawnSimilar = onSpawnSimilar,
+    )
+}
+
+/** Same as the [CatalogStore]-driven overload, but takes the session list
+ * directly — the shape used by tests and previews. */
+@Composable
+fun SidebarContent(
+    sessions: List<Session>,
+    onOpenSession: (Session) -> Unit,
+    modifier: Modifier = Modifier,
+    onRenameSession: (Uuid, String) -> Unit = { _, _ -> },
+    onKillSession: (Uuid) -> Unit = {},
+    onSpawnSimilar: (Session) -> Unit = {},
+) {
+    val nowMs = rememberTickingNowMs()
+    val groups = remember(sessions) { groupSessions(sessions) }
+    val collapsed = remember { mutableStateMapOf<String, Boolean>() }
+
+    Column(modifier = modifier.fillMaxSize()) {
+        Text(
+            text = "Sessions",
+            style = MaterialTheme.typography.titleMedium,
+            modifier = Modifier.padding(16.dp),
+        )
+        if (groups.isEmpty()) {
+            Box(modifier = Modifier.fillMaxSize().padding(16.dp)) {
+                Text(
+                    text = "No sessions",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+            return
+        }
+        LazyColumn(modifier = Modifier.fillMaxSize()) {
+            for (group in groups) {
+                val isCollapsed = collapsed[group.key] == true
+                item(key = "folder:${group.key}") {
+                    FolderNode(
+                        label = group.label,
+                        collapsed = isCollapsed,
+                        onToggle = { collapsed[group.key] = !isCollapsed },
+                        depthPadding = 8,
+                    ) {
+                        Column {
+                            for (session in group.sessions) {
+                                SessionCard(
+                                    session = session,
+                                    nowMs = nowMs,
+                                    depthPadding = 16,
+                                    onOpen = onOpenSession,
+                                    onRename = { s, name -> onRenameSession(s.id, name) },
+                                    onKill = { s -> onKillSession(s.id) },
+                                    onSpawnSimilar = onSpawnSimilar,
+                                )
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

android/app/src/main/java/pt/naps/maestro/ui/theme/Color.kt

@@ -0,0 +1,11 @@
+package pt.naps.maestro.ui.theme
+
+import androidx.compose.ui.graphics.Color
+
+val Purple80 = Color(0xFFD0BCFF)
+val PurpleGrey80 = Color(0xFFCCC2DC)
+val Pink80 = Color(0xFFEFB8C8)
+
+val Purple40 = Color(0xFF6650a4)
+val PurpleGrey40 = Color(0xFF625b71)
+val Pink40 = Color(0xFF7D5260)

android/app/src/main/java/pt/naps/maestro/ui/theme/Theme.kt

@@ -0,0 +1,46 @@
+package pt.naps.maestro.ui.theme
+
+import android.os.Build
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.dynamicDarkColorScheme
+import androidx.compose.material3.dynamicLightColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.platform.LocalContext
+
+private val DarkColorScheme = darkColorScheme(
+    primary = Purple80,
+    secondary = PurpleGrey80,
+    tertiary = Pink80,
+)
+
+private val LightColorScheme = lightColorScheme(
+    primary = Purple40,
+    secondary = PurpleGrey40,
+    tertiary = Pink40,
+)
+
+@Composable
+fun MaestroTheme(
+    darkTheme: Boolean = true,
+    dynamicColor: Boolean = false,
+    content: @Composable () -> Unit,
+) {
+    val useDarkTheme = darkTheme || isSystemInDarkTheme()
+    val colorScheme = when {
+        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
+            val context = LocalContext.current
+            if (useDarkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
+        }
+        useDarkTheme -> DarkColorScheme
+        else -> LightColorScheme
+    }
+
+    MaterialTheme(
+        colorScheme = colorScheme,
+        typography = Typography,
+        content = content,
+    )
+}

android/app/src/main/java/pt/naps/maestro/ui/theme/Type.kt

@@ -0,0 +1,17 @@
+package pt.naps.maestro.ui.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+val Typography = Typography(
+    bodyLarge = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 16.sp,
+        lineHeight = 24.sp,
+        letterSpacing = 0.5.sp,
+    ),
+)

android/app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#1B1B1B"
+        android:pathData="M0,0h108v108h-108z" />
+</vector>

android/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#D0BCFF"
+        android:pathData="M54,24L74,84L64,84L54,52L44,84L34,84Z" />
+</vector>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

android/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<resources>
+    <string name="app_name">Maestro</string>
+    <string name="placeholder_message">Maestro is not connected to a daemon yet.</string>
+</resources>

android/app/src/main/res/values/themes.xml

@@ -0,0 +1,6 @@
+<resources xmlns:tools="http://schemas.android.com/tools">
+    <style name="Theme.Maestro" parent="android:Theme.Material.NoActionBar">
+        <item name="android:statusBarColor" tools:targetApi="21">@android:color/black</item>
+        <item name="android:windowBackground">@android:color/black</item>
+    </style>
+</resources>

android/app/src/test/java/pt/naps/maestro/ExampleUnitTest.kt

@@ -0,0 +1,11 @@
+package pt.naps.maestro
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class ExampleUnitTest {
+    @Test
+    fun addition_isCorrect() {
+        assertEquals(4, 2 + 2)
+    }
+}

android/app/src/test/java/pt/naps/maestro/connection/BackoffTest.kt

@@ -0,0 +1,21 @@
+package pt.naps.maestro.connection
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class BackoffTest {
+    @Test
+    fun `doubles from 500ms and caps at 10s`() {
+        val backoff = Backoff(initialMs = 500L, maxMs = 10_000L)
+        val delays = List(8) { backoff.nextDelayMs() }
+        assertEquals(listOf(500L, 1000L, 2000L, 4000L, 8000L, 10_000L, 10_000L, 10_000L), delays)
+    }
+
+    @Test
+    fun `reset returns to the initial delay`() {
+        val backoff = Backoff(initialMs = 500L, maxMs = 10_000L)
+        repeat(4) { backoff.nextDelayMs() }
+        backoff.reset()
+        assertEquals(500L, backoff.nextDelayMs())
+    }
+}

android/app/src/test/java/pt/naps/maestro/connection/CatalogStoreTest.kt

@@ -0,0 +1,60 @@
+package pt.naps.maestro.connection
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import pt.naps.maestro.data.CatalogEvent
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.SessionStatus
+
+class CatalogStoreTest {
+    private fun session(id: String) = Session(
+        id = id,
+        cwd = "/tmp",
+        command = "bash",
+        status = SessionStatus.Running,
+        created_at = "2026-05-24T12:00:00Z",
+    )
+
+    @Test
+    fun `snapshot replaces the map keyed by id`() {
+        val store = CatalogStore()
+        store.apply(CatalogEvent.Snapshot(listOf(session("a"), session("b"))))
+        assertEquals(setOf("a", "b"), store.sessions.value.keys)
+    }
+
+    @Test
+    fun `added and updated upsert one entry`() {
+        val store = CatalogStore()
+        store.apply(CatalogEvent.Snapshot(emptyList()))
+        store.apply(CatalogEvent.SessionAdded(session("a")))
+        assertEquals(1, store.sessions.value.size)
+
+        val renamed = session("a").copy(command = "zsh")
+        store.apply(CatalogEvent.SessionUpdated(renamed))
+        assertEquals("zsh", store.sessions.value.getValue("a").command)
+    }
+
+    @Test
+    fun `removed drops the entry`() {
+        val store = CatalogStore()
+        store.apply(CatalogEvent.Snapshot(listOf(session("a"), session("b"))))
+        store.apply(CatalogEvent.SessionRemoved("a"))
+        assertEquals(setOf("b"), store.sessions.value.keys)
+    }
+
+    @Test
+    fun `lagged reports the skip count without touching the map`() {
+        val store = CatalogStore()
+        store.apply(CatalogEvent.Snapshot(listOf(session("a"))))
+        val skipped = store.apply(CatalogEvent.Lagged(3))
+        assertEquals(3L, skipped)
+        assertEquals(setOf("a"), store.sessions.value.keys)
+    }
+
+    @Test
+    fun `non-lagged events report no skip`() {
+        val store = CatalogStore()
+        assertNull(store.apply(CatalogEvent.Snapshot(emptyList())))
+    }
+}

android/app/src/test/java/pt/naps/maestro/connection/DaemonIdentityTest.kt

@@ -0,0 +1,55 @@
+package pt.naps.maestro.connection
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import pt.naps.maestro.data.BuildInfo
+import pt.naps.maestro.data.DaemonInfo
+
+class DaemonIdentityTest {
+    private fun info(commit: String = "", instance: String = "") =
+        DaemonInfo(build = BuildInfo(commit = commit), instance = instance)
+
+    @Test
+    fun `same commit and instance is Same`() {
+        val a = info(commit = "abc123", instance = "i1")
+        assertEquals(RestartKind.SAME, compareIdentity(a, a.copy()))
+    }
+
+    @Test
+    fun `different commit is Upgraded`() {
+        val before = info(commit = "abc123", instance = "i1")
+        val after = info(commit = "def456", instance = "i2")
+        assertEquals(RestartKind.UPGRADED, compareIdentity(before, after))
+    }
+
+    @Test
+    fun `same commit but different instance is Restarted`() {
+        val before = info(commit = "abc123", instance = "i1")
+        val after = info(commit = "abc123", instance = "i2")
+        assertEquals(RestartKind.RESTARTED, compareIdentity(before, after))
+    }
+
+    @Test
+    fun `empty commits on both sides never read as an upgrade`() {
+        val before = info(commit = "", instance = "i1")
+        val after = info(commit = "", instance = "i2")
+        assertEquals(RestartKind.RESTARTED, compareIdentity(before, after))
+    }
+
+    @Test
+    fun `format release names the commit and short date`() {
+        val build = BuildInfo(commit = "f89be4a716c7", commit_date = "2026-09-02T10:00:00Z", dirty = false)
+        assertEquals("f89be4a716c7 · 2026-09-02", formatRelease(build))
+    }
+
+    @Test
+    fun `dirty build is flagged`() {
+        val build = BuildInfo(commit = "f89be4a716c7", commit_date = "2026-09-02T10:00:00Z", dirty = true)
+        assertEquals("f89be4a716c7 · 2026-09-02 (dirty)", formatRelease(build))
+    }
+
+    @Test
+    fun `empty commit is unknown release`() {
+        assertEquals("unknown release", formatRelease(BuildInfo()))
+    }
+}

android/app/src/test/java/pt/naps/maestro/data/WireSerializationTest.kt

@@ -0,0 +1,114 @@
+package pt.naps.maestro.data
+
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/** Wire-format checks against fixtures mirrored from
+ * `crates/maestro-protocol/src/lib.rs`'s own test suite, so a Kotlin type
+ * that drifts from the Rust source of truth fails here first. */
+class WireSerializationTest {
+    private val json = Json { ignoreUnknownKeys = true; isLenient = true }
+
+    private fun legacySessionJson(extra: String = "") = """
+        {"id":"00000000-0000-0000-0000-000000000001","cwd":"/tmp","command":"bash",
+         "status":"Running","created_at":"2026-05-24T12:00:00Z"$extra}
+    """.trimIndent()
+
+    @Test
+    fun `legacy session payload defaults new fields`() {
+        val s = json.decodeFromString<Session>(legacySessionJson())
+        assertEquals(ActivityState.Idle, s.activity)
+        assertEquals(SessionView.Terminal, s.view)
+        assertNull(s.foreground)
+        assertNull(s.blocked_work)
+        assertEquals(EPOCH, s.last_activity_at)
+    }
+
+    @Test
+    fun `unknown activity state degrades to Idle`() {
+        val s = json.decodeFromString<Session>(legacySessionJson(""","activity":"QuantumEntangled""""))
+        assertEquals(ActivityState.Idle, s.activity)
+    }
+
+    @Test
+    fun `unknown name source degrades to User`() {
+        assertEquals(NameSource.User, json.decodeFromString<NameSource>("\"Rolled\""))
+        assertEquals(NameSource.Haiku, json.decodeFromString<NameSource>("\"Haiku\""))
+    }
+
+    @Test
+    fun `catalog event tags by type`() {
+        assertEquals(
+            """{"type":"Lagged","skipped":3}""",
+            json.encodeToString<CatalogEvent>(CatalogEvent.Lagged(3)),
+        )
+        val removed = CatalogEvent.SessionRemoved("00000000-0000-0000-0000-000000000001")
+        assertEquals(removed, json.decodeFromString<CatalogEvent>(json.encodeToString<CatalogEvent>(removed)))
+    }
+
+    @Test
+    fun `client control tags by type`() {
+        assertEquals(
+            """{"type":"Resize","cols":120,"rows":40}""",
+            json.encodeToString<ClientControl>(ClientControl.Resize(120, 40)),
+        )
+        assertEquals(ClientControl.Ping, json.decodeFromString<ClientControl>("""{"type":"Ping"}"""))
+    }
+
+    @Test
+    fun `structured approval decision is a bare string`() {
+        assertEquals(
+            StructuredApprovalDecision.AllowOnce,
+            json.decodeFromString<StructuredApprovalDecision>("\"allow_once\""),
+        )
+        assertEquals(
+            "\"allow_for_session\"",
+            json.encodeToString(StructuredApprovalDecision.AllowForSession),
+        )
+    }
+
+    @Test
+    fun `structured event tags snake_case`() {
+        val event = json.decodeFromString<StructuredEvent>(
+            """{"type":"transcript_snapshot","snapshot":{"cursor":7,"rows":[]}}""",
+        )
+        assertTrue(event is StructuredEvent.TranscriptSnapshotEvent)
+        assertEquals(7L, (event as StructuredEvent.TranscriptSnapshotEvent).snapshot.cursor)
+    }
+
+    @Test
+    fun `transcript delta tags snake_case and round trips`() {
+        val row = TranscriptRow(
+            id = "tool:read-1",
+            kind = TranscriptRowKind.ToolCall,
+            data = json.parseToJsonElement("""{"name":"vendor.read"}"""),
+        )
+        val patch = TranscriptDelta.Patch(row)
+        val encoded = json.encodeToString<TranscriptDelta>(patch)
+        assertTrue(encoded.startsWith("""{"type":"patch","row":"""))
+        assertEquals(patch, json.decodeFromString<TranscriptDelta>(encoded))
+        assertEquals("\"agent_thought\"", json.encodeToString(TranscriptRowKind.AgentThought))
+    }
+
+    @Test
+    fun `rename request encodes plainly`() {
+        assertEquals(
+            """{"name":"amber-falcon"}""",
+            json.encodeToString(RenameSessionRequest("amber-falcon")),
+        )
+    }
+
+    @Test
+    fun `api error decodes nested unsaved work with defaults`() {
+        val apiError = json.decodeFromString<ApiError>(
+            """{"error":{"code":"unsaved_work","message":"nope","unsaved_work":{"uncommitted_files":3}}}""",
+        )
+        assertEquals(3, apiError.error.unsaved_work?.uncommitted_files)
+        assertEquals(0, apiError.error.unsaved_work?.unpushed_commits)
+    }
+}

android/app/src/test/java/pt/naps/maestro/ui/sidebar/SessionFormattingTest.kt

@@ -0,0 +1,190 @@
+package pt.naps.maestro.ui.sidebar
+
+import kotlinx.serialization.json.JsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import pt.naps.maestro.data.InTheWay
+import pt.naps.maestro.data.Session
+import pt.naps.maestro.data.SessionStatus
+import pt.naps.maestro.data.SessionWorktree
+
+private fun session(
+    command: String = "claude",
+    cwd: String = "/home/user/project",
+    metadata: Map<String, JsonPrimitive> = emptyMap(),
+    worktree: SessionWorktree? = null,
+    blockedWork: InTheWay? = null,
+    activitySince: String = "1970-01-01T00:00:00Z",
+) = Session(
+    id = "s1",
+    cwd = cwd,
+    command = command,
+    metadata = metadata,
+    worktree = worktree,
+    status = SessionStatus.Running,
+    created_at = "2026-01-01T00:00:00Z",
+    blocked_work = blockedWork,
+    activity_since = activitySince,
+)
+
+class DurationFormattingTest {
+    @Test
+    fun `floors seconds under a minute`() {
+        assertEquals("30s", activityDurationLabel(30_000))
+        assertEquals("59s", activityDurationLabel(59_999))
+    }
+
+    @Test
+    fun `floors minutes under an hour`() {
+        assertEquals("4m", activityDurationLabel(4 * 60_000 + 59_000))
+    }
+
+    @Test
+    fun `floors hours with no days unit`() {
+        assertEquals("2h", activityDurationLabel(2 * 3_600_000 + 59 * 60_000))
+    }
+
+    @Test
+    fun `held ms is null for missing or implausible since`() {
+        assertNull(activityHeldMs(null, 1_000))
+        assertNull(activityHeldMs("", 1_000))
+        assertNull(activityHeldMs("1970-01-01T00:00:00Z", 1_000))
+        assertNull(activityHeldMs("not-a-timestamp", 1_000))
+    }
+
+    @Test
+    fun `held ms is the gap to now for a plausible timestamp`() {
+        val since = "2026-01-01T00:00:00Z"
+        val nowMs = java.time.Instant.parse("2026-01-01T00:00:31Z").toEpochMilli()
+        assertEquals(31_000L, activityHeldMs(since, nowMs))
+    }
+}
+
+class SessionNameTest {
+    @Test
+    fun `falls back to the command when no name is set`() {
+        assertEquals("claude --resume", sessionName(session(command = "claude --resume")))
+    }
+
+    @Test
+    fun `uses the custom name when set`() {
+        val s = session(metadata = mapOf("name" to JsonPrimitive("api-work")))
+        assertEquals("api-work", sessionName(s))
+    }
+
+    @Test
+    fun `an empty stored name is treated as unset`() {
+        val s = session(metadata = mapOf("name" to JsonPrimitive("")))
+        assertNull(customSessionName(s))
+    }
+
+    @Test
+    fun `generated name is provisional, user and haiku are not`() {
+        val generated = session(
+            metadata = mapOf(
+                "name" to JsonPrimitive("brave-otter"),
+                "name_source" to JsonPrimitive("Generated"),
+            ),
+        )
+        val user = session(
+            metadata = mapOf(
+                "name" to JsonPrimitive("api-work"),
+                "name_source" to JsonPrimitive("User"),
+            ),
+        )
+        val unknownSource = session(
+            metadata = mapOf(
+                "name" to JsonPrimitive("api-work"),
+                "name_source" to JsonPrimitive("something-new"),
+            ),
+        )
+        assertTrue(isProvisionalName(generated))
+        assertFalse(isProvisionalName(user))
+        assertFalse(isProvisionalName(unknownSource))
+    }
+}
+
+class BlockerStatsTest {
+    @Test
+    fun `renders insertions and deletions in diff notation`() {
+        val w = InTheWay(uncommitted_files = 2, untracked_files = 3, unpushed_commits = 2, insertions = 124, deletions = 18)
+        val stats = blockerStats(w).associate { it.kind to it.text }
+        assertEquals("+124", stats["add"])
+        assertEquals("-18", stats["del"])
+        assertEquals("?3", stats["untracked"])
+        assertEquals("↑2", stats["unpushed"])
+        assertNull(stats["files"])
+    }
+
+    @Test
+    fun `falls back to a file count when a tracked change carries no line delta`() {
+        val w = InTheWay(uncommitted_files = 2, insertions = 0, deletions = 0)
+        val stats = blockerStats(w)
+        assertEquals(listOf(BlockerStat("files", "~2")), stats)
+    }
+
+    @Test
+    fun `session blockers are null when nothing blocks a kill`() {
+        assertNull(sessionBlockers(session(blockedWork = null)))
+        assertNull(sessionBlockers(session(blockedWork = InTheWay())))
+    }
+
+    @Test
+    fun `format in the way spells out zero as no unsaved work`() {
+        assertEquals("no unsaved work", formatInTheWay(InTheWay()))
+        assertEquals("1 uncommitted file, 2 untracked files", formatInTheWay(InTheWay(uncommitted_files = 1, untracked_files = 2)))
+    }
+}
+
+class ProgramNameTest {
+    @Test
+    fun `drops arguments and basenames the path`() {
+        assertEquals("claude", programName("/usr/local/bin/claude -p hi"))
+        assertEquals("claude", programName("claude --dangerously-skip-permissions"))
+    }
+
+    @Test
+    fun `looks through leading env assignments`() {
+        assertEquals("claude", programName("FOO=bar BAZ=qux claude --resume"))
+    }
+
+    @Test
+    fun `looks through sudo and env wrappers with their own flags`() {
+        assertEquals("claude", programName("sudo claude"))
+        assertEquals("claude", programName("env -i FOO=bar claude"))
+    }
+
+    @Test
+    fun `looks through js-toolchain launchers`() {
+        assertEquals("claude-code", programName("npx claude-code"))
+        assertEquals("claude", programName("pnpm dlx claude"))
+        assertEquals("claude", programName("bunx claude"))
+    }
+
+    @Test
+    fun `a command that is nothing but wrappers is shown as written`() {
+        assertEquals("sudo", programName("sudo"))
+    }
+}
+
+class GroupingTest {
+    @Test
+    fun `groups by worktree base_repo when present`() {
+        val a = session(cwd = "/wt/a", worktree = SessionWorktree(path = "/wt/a", base_repo = "/home/user/maestro"))
+        val b = session(cwd = "/wt/b", worktree = SessionWorktree(path = "/wt/b", base_repo = "/home/user/maestro"))
+        val groups = groupSessions(listOf(a, b))
+        assertEquals(1, groups.size)
+        assertEquals("maestro", groups.single().label)
+        assertEquals(2, groups.single().sessions.size)
+    }
+
+    @Test
+    fun `falls back to cwd with no worktree`() {
+        val a = session(cwd = "/home/user/scratch")
+        val groups = groupSessions(listOf(a))
+        assertEquals("scratch", groups.single().label)
+    }
+}

android/build.gradle.kts

@@ -0,0 +1,6 @@
+plugins {
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.kotlin.android) apply false
+    alias(libs.plugins.kotlin.compose) apply false
+    alias(libs.plugins.kotlin.serialization) apply false
+}

android/gradle.properties

@@ -0,0 +1,4 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+org.gradle.parallel=true
+android.useAndroidX=true
+kotlin.code.style=official

android/gradle/libs.versions.toml

@@ -0,0 +1,38 @@
+[versions]
+agp = "8.5.2"
+kotlin = "2.0.21"
+coreKtx = "1.13.1"
+lifecycleRuntimeKtx = "2.8.6"
+activityCompose = "1.9.2"
+composeBom = "2024.09.03"
+navigationCompose = "2.8.2"
+okhttp = "4.12.0"
+kotlinxSerializationJson = "1.7.3"
+kotlinxCoroutines = "1.9.0"
+
+[libraries]
+androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
+androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
+androidx-lifecycle-process = { group = "androidx.lifecycle", name = "lifecycle-process", version.ref = "lifecycleRuntimeKtx" }
+androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
+androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
+androidx-ui = { group = "androidx.compose.ui", name = "ui" }
+androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
+androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
+androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
+androidx-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
+androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
+androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }
+okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
+kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
+kotlinx-coroutines-android = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-android", version.ref = "kotlinxCoroutines" }
+junit = { group = "junit", name = "junit", version = "4.13.2" }
+androidx-test-ext-junit = { group = "androidx.test.ext", name = "junit", version = "1.2.1" }
+androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version = "3.6.1" }
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "agp" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

android/gradlew

@@ -0,0 +1,237 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       issues, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated via the Gradle "wrapper" task
+#       (see https://docs.gradle.org/current/userguide/gradle_wrapper.html)
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH="$APP_HOME/gradle/wrapper/gradle-wrapper.jar"
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                             # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}                # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                        #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+# Collect all arguments for the java command;
+#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments that
+#     shell script including quotes and variable substitutions, so put them in
+#     double quotes to make sure that they get re-expanded; and
+#   * put everything else in single quotes, so that it's not re-expanded.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-A-Za-z0-9_+.]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

android/gradlew.bat

@@ -0,0 +1,89 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" -Dorg.gradle.appname=%APP_BASE_NAME% -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

android/settings.gradle.kts

@@ -0,0 +1,19 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "Maestro"
+
+include(":app")

crates/maestro-acp/Cargo.toml

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

crates/maestro-acp/src/lib.rs

@@ -1,5 +1,5 @@
-//! ACP client role for the daemon (#134): one `claude-code-acp` child per
-//! structured session.
+//! ACP client role for the daemon: one provider adapter child per structured
+//! session.
 //!
 //! The daemon is the client; the adapter is the agent. [`spawn`] starts the
 //! adapter as a child process with stdio pipes, in the session's `cwd` with
@@ -9,10 +9,10 @@
 //!
 //! **The handshake declares almost nothing.** `initialize` reports
 //! `fs.readTextFile`, `fs.writeTextFile` and `terminal` as `false`, so the
-//! adapter uses Claude Code's own Read / Write / Bash instead of asking the
-//! daemon to act on its behalf — exactly what already happens in the
-//! terminal view. `session/request_permission` is the one client method that
-//! gets a real implementation, in #139; here it is a stub that declines.
+//! adapter uses the provider's own file and command tools instead of asking
+//! the daemon to act on its behalf — exactly what already happens in the
+//! terminal view. `session/request_permission` is the one client method with
+//! a real implementation.
 //!
 //! Every `session/update` notification the adapter sends lands on an
 //! unbounded channel the session owns ([`AcpSession::take_updates`]). Nothing
@@ -42,30 +42,80 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use agent_client_protocol::schema::v1::{
-    CancelNotification, ClientCapabilities, ContentBlock, FileSystemCapabilities, Implementation,
-    InitializeRequest, LoadSessionRequest, NewSessionRequest, PromptRequest,
-    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse, SessionId,
-    SessionNotification,
+    CancelNotification, ClientCapabilities, ConfigOptionUpdate, ContentBlock, CurrentModeUpdate,
+    FileSystemCapabilities, Implementation, InitializeRequest, PromptRequest,
+    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
+    SessionConfigKind, SessionConfigOption, SessionConfigOptionCategory, SessionConfigOptionValue,
+    SessionConfigSelectOption, SessionId, SessionModeState, SessionNotification, SessionUpdate,
+    SetSessionConfigOptionRequest, SetSessionModeRequest,
 };
 use agent_client_protocol::schema::ProtocolVersion;
-use agent_client_protocol::{ByteStreams, Client};
+use agent_client_protocol::{ByteStreams, Client, JsonRpcRequest, JsonRpcResponse};
+use serde::{Deserialize, Serialize};
 use tokio::io::AsyncBufReadExt;
 use tokio::sync::{mpsc, oneshot, watch};
 use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 
 pub use agent_client_protocol::schema::v1 as schema;
 
-/// The adapter binary, resolved on `PATH`.
-pub const ADAPTER_BIN: &str = "claude-code-acp";
+/// Item on the updates channel.  Notifications and turn-done markers share
+/// the same FIFO so the event pump processes every notification for a turn
+/// before seeing its done signal.
+#[derive(Debug)]
+pub enum AcpUpdate {
+    /// A raw `session/update` notification from the adapter.
+    Notification(Box<SessionNotification>),
+    /// The prompt response for `turn` arrived.  All notifications for this
+    /// turn precede this marker on the wire, and therefore in this channel.
+    /// The event pump must fire `done` after persisting every preceding
+    /// notification.
+    TurnDone {
+        turn: u64,
+        result: Result<(), String>,
+        done: oneshot::Sender<Result<(), String>>,
+    },
+}
 
-/// 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.
+/// ACP adapter selected from the structured session's resolved command.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AcpAdapter {
+    ClaudeCode,
+    Codex,
+}
+
+impl AcpAdapter {
+    pub const fn binary(self) -> &'static str {
+        match self {
+            Self::ClaudeCode => "claude-code-acp",
+            Self::Codex => "codex-acp",
+        }
+    }
+
+    pub const fn install_command(self) -> &'static str {
+        match self {
+            Self::ClaudeCode => "npm install -g --prefix ~/.local @zed-industries/claude-code-acp",
+            Self::Codex => "npm install -g --prefix ~/.local @agentclientprotocol/codex-acp",
+        }
+    }
+}
+
+impl std::fmt::Display for AcpAdapter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Self::ClaudeCode => "Claude Code",
+            Self::Codex => "Codex",
+        })
+    }
+}
+
+/// Compatibility aliases for Claude Code callers.
+pub const ADAPTER_BIN: &str = "claude-code-acp";
 pub const INSTALL_COMMAND: &str =
     "npm install -g --prefix ~/.local @zed-industries/claude-code-acp";
 
 /// How long `initialize` + `session/new` may take before the spawn is
-/// declared failed. The real adapter boots a node process and the Claude
-/// Code SDK behind it; a slow machine takes seconds, never a minute.
+/// declared failed. The real adapters boot a node process and their provider
+/// client behind it; a slow machine takes seconds, never a minute.
 pub const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(60);
 
 /// How long [`AcpSession::terminate`] waits after `session/cancel` before
@@ -78,6 +128,75 @@ pub const TERM_GRACE: Duration = Duration::from_secs(2);
 
 /// Bytes of the child's stderr kept for the failure message.
 const STDERR_TAIL_BYTES: usize = 4096;
+const LEGACY_MODEL_CONFIG_ID: &str = "__maestro_legacy_model";
+const LEGACY_MODE_CONFIG_ID: &str = "__maestro_legacy_mode";
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/new", response = ExtendedNewSessionResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedNewSessionRequest {
+    cwd: PathBuf,
+    mcp_servers: Vec<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedNewSessionResponse {
+    session_id: SessionId,
+    #[serde(default)]
+    modes: Option<SessionModeState>,
+    #[serde(default)]
+    config_options: Option<Vec<SessionConfigOption>>,
+    #[serde(default)]
+    models: Option<LegacyModelState>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/load", response = ExtendedLoadSessionResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedLoadSessionRequest {
+    session_id: SessionId,
+    cwd: PathBuf,
+    mcp_servers: Vec<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[serde(rename_all = "camelCase")]
+struct ExtendedLoadSessionResponse {
+    #[serde(default)]
+    modes: Option<SessionModeState>,
+    #[serde(default)]
+    config_options: Option<Vec<SessionConfigOption>>,
+    #[serde(default)]
+    models: Option<LegacyModelState>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyModelState {
+    current_model_id: String,
+    available_models: Vec<LegacyModel>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyModel {
+    model_id: String,
+    name: String,
+    #[serde(default)]
+    description: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "session/set_model", response = LegacySetModelResponse)]
+#[serde(rename_all = "camelCase")]
+struct LegacySetModelRequest {
+    session_id: SessionId,
+    model_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+struct LegacySetModelResponse {}
 
 /// What [`spawn`] needs to start one adapter.
 #[derive(Debug, Clone)]
@@ -94,6 +213,8 @@ pub struct SpawnConfig {
     /// instead of opening a fresh one. The adapter must advertise
     /// `loadSession`; the handshake fails otherwise.
     pub load_session: Option<String>,
+    /// The provider-specific adapter to launch.
+    pub adapter: AcpAdapter,
 }
 
 impl SpawnConfig {
@@ -103,6 +224,7 @@ impl SpawnConfig {
             env,
             handshake_timeout: HANDSHAKE_TIMEOUT,
             load_session: None,
+            adapter: AcpAdapter::ClaudeCode,
         }
     }
 
@@ -111,6 +233,11 @@ impl SpawnConfig {
         self.load_session = Some(session_id.into());
         self
     }
+
+    pub fn adapter(mut self, adapter: AcpAdapter) -> Self {
+        self.adapter = adapter;
+        self
+    }
 }
 
 /// A blocked ACP permission request delivered to the daemon.
@@ -126,31 +253,39 @@ pub struct PermissionRequest {
 pub enum AcpError {
     /// The adapter is not on `PATH`. The message names the install command
     /// so the failed session is actionable rather than silently dead.
-    #[error("{ADAPTER_BIN} not found on PATH; install it with: {INSTALL_COMMAND}")]
-    AdapterMissing,
-    #[error("failed to start {ADAPTER_BIN}: {0}")]
-    Spawn(#[source] std::io::Error),
+    #[error("{adapter} ACP adapter ({bin}) not found on PATH; install it with: {install_command}", bin = adapter.binary(), install_command = adapter.install_command())]
+    AdapterMissing { adapter: AcpAdapter },
+    #[error("failed to start {adapter} ACP adapter ({bin}): {source}", bin = adapter.binary())]
+    Spawn {
+        adapter: AcpAdapter,
+        #[source]
+        source: std::io::Error,
+    },
     /// The adapter answered the handshake with an error.
     #[error("ACP handshake failed: {0}")]
     Handshake(String),
     /// The adapter went away before the handshake finished. Carries the
     /// tail of its stderr, which is where a missing Claude login shows up.
-    #[error("{ADAPTER_BIN} exited during the ACP handshake ({status}){stderr}")]
-    ExitedEarly { status: String, stderr: String },
+    #[error("{adapter} ACP adapter ({bin}) exited during the ACP handshake ({status}){stderr}", bin = adapter.binary())]
+    ExitedEarly {
+        adapter: AcpAdapter,
+        status: String,
+        stderr: String,
+    },
     #[error("ACP handshake timed out after {0:?}")]
     HandshakeTimeout(Duration),
 }
 
 /// Resolve [`ADAPTER_BIN`] against the `PATH` the child would run with: the
 /// session env's `PATH` when it sets one, the daemon's own otherwise.
-pub fn resolve_adapter(env: &HashMap<String, String>) -> Option<PathBuf> {
+pub fn resolve_adapter(adapter: AcpAdapter, env: &HashMap<String, String>) -> Option<PathBuf> {
     let path: OsString = match env.get("PATH") {
         Some(p) => OsString::from(p),
         None => std::env::var_os("PATH")?,
     };
     std::env::split_paths(&path)
         .filter(|dir| !dir.as_os_str().is_empty())
-        .map(|dir| dir.join(ADAPTER_BIN))
+        .map(|dir| dir.join(adapter.binary()))
         .find(|candidate| is_executable(candidate))
 }
 
@@ -168,9 +303,20 @@ enum Command {
         turn: u64,
         done: oneshot::Sender<Result<(), String>>,
     },
+    SetConfig {
+        config_id: String,
+        value: SessionConfigOptionValue,
+        done: oneshot::Sender<Result<(), String>>,
+    },
     Close,
 }
 
+struct ConnectionConfig {
+    cwd: PathBuf,
+    load_session: Option<String>,
+    adapter: AcpAdapter,
+}
+
 enum ChildCommand {
     Signal(libc::c_int),
     Reap(oneshot::Sender<bool>),
@@ -226,7 +372,7 @@ pub struct AcpSession {
     pid: u32,
     commands: mpsc::UnboundedSender<Command>,
     child_commands: mpsc::UnboundedSender<ChildCommand>,
-    updates: Mutex<Option<mpsc::UnboundedReceiver<SessionNotification>>>,
+    updates: Mutex<Option<mpsc::UnboundedReceiver<AcpUpdate>>>,
     permission_requests: Mutex<Option<mpsc::UnboundedReceiver<PermissionRequest>>>,
     exit: watch::Receiver<Option<ExitStatus>>,
 }
@@ -265,9 +411,9 @@ impl AcpSession {
         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>> {
+    /// The stream of updates (notifications + turn-done markers), handed out
+    /// once.  Items that arrived before the take are still queued.
+    pub fn take_updates(&self) -> Option<mpsc::UnboundedReceiver<AcpUpdate>> {
         self.updates.lock().expect("updates mutex").take()
     }
 
@@ -301,6 +447,23 @@ impl AcpSession {
         Ok(done_rx)
     }
 
+    /// Change one option advertised by the ACP agent.
+    pub fn set_config(
+        &self,
+        config_id: String,
+        value: SessionConfigOptionValue,
+    ) -> Result<oneshot::Receiver<Result<(), String>>, String> {
+        let (done_tx, done_rx) = oneshot::channel();
+        self.commands
+            .send(Command::SetConfig {
+                config_id,
+                value,
+                done: done_tx,
+            })
+            .map_err(|_| "ACP connection is closed".to_string())?;
+        Ok(done_rx)
+    }
+
     /// End the child: `session/cancel`, wait `cancel_grace`, `SIGTERM`, wait
     /// `term_grace`, `SIGKILL`. Returns once the child has been reaped.
     pub async fn terminate(&self, cancel_grace: Duration, term_grace: Duration) {
@@ -341,7 +504,9 @@ impl Drop for AcpSession {
 /// Fails without a running child: on any error the process is already
 /// signalled, so a failed session never leaves a stray adapter behind.
 pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
-    let adapter = resolve_adapter(&config.env).ok_or(AcpError::AdapterMissing)?;
+    let provider = config.adapter;
+    let adapter = resolve_adapter(provider, &config.env)
+        .ok_or(AcpError::AdapterMissing { adapter: provider })?;
 
     let mut cmd = tokio::process::Command::new(&adapter);
     cmd.current_dir(&config.cwd)
@@ -369,18 +534,27 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
             });
         }
     }
-    let mut child = cmd.spawn().map_err(AcpError::Spawn)?;
+    let mut child = cmd.spawn().map_err(|source| AcpError::Spawn {
+        adapter: provider,
+        source,
+    })?;
     let pid = child.id().expect("child pid is known before wait");
     let stdin = child.stdin.take().expect("piped stdin");
     let stdout = child.stdout.take().expect("piped stdout");
     let stderr = child.stderr.take().expect("piped stderr");
 
     let stderr_tail = Arc::new(Mutex::new(VecDeque::<u8>::new()));
-    tokio::spawn(drain_stderr(stderr, pid, stderr_tail.clone()));
+    tokio::spawn(drain_stderr(stderr, pid, stderr_tail.clone(), provider));
 
     let (exit_tx, exit_rx) = watch::channel(None);
     let (child_commands_tx, child_commands_rx) = mpsc::unbounded_channel();
-    tokio::spawn(supervise_child(child, pid, child_commands_rx, exit_tx));
+    tokio::spawn(supervise_child(
+        child,
+        pid,
+        child_commands_rx,
+        exit_tx,
+        provider,
+    ));
 
     let (updates_tx, updates_rx) = mpsc::unbounded_channel();
     let (permission_tx, permission_rx) = mpsc::unbounded_channel();
@@ -389,8 +563,11 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
     let transport = ByteStreams::new(stdin.compat_write(), stdout.compat());
     tokio::spawn(run_connection(
         transport,
-        config.cwd.clone(),
-        config.load_session.clone(),
+        ConnectionConfig {
+            cwd: config.cwd.clone(),
+            load_session: config.load_session.clone(),
+            adapter: provider,
+        },
         updates_tx,
         permission_tx,
         commands_rx,
@@ -423,6 +600,7 @@ pub async fn spawn(config: SpawnConfig) -> Result<AcpSession, AcpError> {
                     .to_string()
             };
             AcpError::ExitedEarly {
+                adapter: provider,
                 status: status.map_or_else(|| "unknown status".into(), |s| s.to_string()),
                 stderr: if stderr.is_empty() {
                     String::new()
@@ -457,12 +635,13 @@ async fn supervise_child(
     pid: u32,
     mut commands: mpsc::UnboundedReceiver<ChildCommand>,
     exit_tx: watch::Sender<Option<ExitStatus>>,
+    adapter: AcpAdapter,
 ) {
     loop {
         tokio::select! {
             status = child.wait() => {
                 let status = status.ok();
-                tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                 let _ = exit_tx.send(status);
                 return;
             }
@@ -476,7 +655,7 @@ async fn supervise_child(
                 Some(ChildCommand::Reap(done)) => match child.try_wait() {
                     Ok(Some(status)) => {
                         let _ = done.send(true);
-                        tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                        tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                         let _ = exit_tx.send(Some(status));
                         return;
                     }
@@ -484,7 +663,7 @@ async fn supervise_child(
                         let _ = done.send(false);
                     }
                     Err(error) => {
-                        tracing::warn!(pid, %error, "could not reap {ADAPTER_BIN}");
+                        tracing::warn!(pid, %error, provider = %adapter, "could not reap ACP adapter");
                         let _ = done.send(false);
                     }
                 },
@@ -494,7 +673,7 @@ async fn supervise_child(
                     // a reused PID.
                     unsafe { libc::kill(pid as libc::pid_t, libc::SIGTERM) };
                     let status = child.wait().await.ok();
-                    tracing::debug!(pid, ?status, "{ADAPTER_BIN} exited");
+                    tracing::debug!(pid, ?status, provider = %adapter, "ACP adapter exited");
                     let _ = exit_tx.send(status);
                     return;
                 }
@@ -513,11 +692,105 @@ fn client_capabilities() -> ClientCapabilities {
         .terminal(false)
 }
 
+fn advertised_config_options(
+    mut options: Vec<SessionConfigOption>,
+    modes: Option<&SessionModeState>,
+    models: Option<&LegacyModelState>,
+) -> Vec<SessionConfigOption> {
+    let has_model = options
+        .iter()
+        .any(|option| matches!(option.category, Some(SessionConfigOptionCategory::Model)));
+    let has_mode = options
+        .iter()
+        .any(|option| matches!(option.category, Some(SessionConfigOptionCategory::Mode)));
+    if let Some(models) = models.filter(|_| !has_model) {
+        let mut choices = models
+            .available_models
+            .iter()
+            .map(|model| {
+                let mut option =
+                    SessionConfigSelectOption::new(model.model_id.clone(), &model.name);
+                if model.model_id == "default" {
+                    option.name = "Opus (default)".into();
+                }
+                option.description.clone_from(&model.description);
+                option
+            })
+            .collect::<Vec<_>>();
+        if !models
+            .available_models
+            .iter()
+            .any(|model| model.model_id == "fable")
+        {
+            choices.push(SessionConfigSelectOption::new("fable", "Fable"));
+        }
+        options.push(
+            SessionConfigOption::select(
+                LEGACY_MODEL_CONFIG_ID,
+                "Model",
+                models.current_model_id.clone(),
+                choices,
+            )
+            .category(SessionConfigOptionCategory::Model),
+        );
+    }
+    if let Some(modes) = modes.filter(|_| !has_mode) {
+        let choices = modes
+            .available_modes
+            .iter()
+            .map(|mode| {
+                let mut option = SessionConfigSelectOption::new(mode.id.0.clone(), &mode.name);
+                option.description.clone_from(&mode.description);
+                option
+            })
+            .collect::<Vec<_>>();
+        options.push(
+            SessionConfigOption::select(
+                LEGACY_MODE_CONFIG_ID,
+                "Mode",
+                modes.current_mode_id.0.clone(),
+                choices,
+            )
+            .category(SessionConfigOptionCategory::Mode),
+        );
+    }
+    options
+}
+
+fn replace_config_value(
+    options: &Arc<Mutex<Vec<SessionConfigOption>>>,
+    config_id: &str,
+    value: &SessionConfigOptionValue,
+) -> Vec<SessionConfigOption> {
+    let mut options = options.lock().expect("config options");
+    if let Some(option) = options
+        .iter_mut()
+        .find(|option| option.id.0.as_ref() == config_id)
+    {
+        match (&mut option.kind, value) {
+            (SessionConfigKind::Select(select), SessionConfigOptionValue::ValueId { value }) => {
+                select.current_value = value.clone();
+            }
+            (SessionConfigKind::Boolean(boolean), SessionConfigOptionValue::Boolean { value }) => {
+                boolean.current_value = *value;
+            }
+            _ => {}
+        }
+    }
+    options.clone()
+}
+
+fn config_notification(session_id: &str, options: Vec<SessionConfigOption>) -> SessionNotification {
+    SessionNotification::new(
+        SessionId::new(session_id),
+        SessionUpdate::ConfigOptionUpdate(ConfigOptionUpdate::new(options)),
+    )
+}
+
 async fn run_connection<T>(
     transport: T,
-    cwd: PathBuf,
-    load_session: Option<String>,
-    updates_tx: mpsc::UnboundedSender<SessionNotification>,
+    config: ConnectionConfig,
+    updates_tx: mpsc::UnboundedSender<AcpUpdate>,
     permission_requests: mpsc::UnboundedSender<PermissionRequest>,
     mut commands_rx: mpsc::UnboundedReceiver<Command>,
     ready_tx: oneshot::Sender<Result<String, ReadyError>>,
@@ -534,6 +807,7 @@ async fn run_connection<T>(
     // until a cancelled prompt settles, so this active turn is unambiguous.
     let permission_turn = Arc::new(Mutex::new(PermissionTurnState::default()));
     let permission_turn_seen = permission_turn.clone();
+    let received_updates = updates_tx.clone();
     let result = Client
         .builder()
         .name("maestro")
@@ -544,7 +818,7 @@ async fn run_connection<T>(
                     return Ok(());
                 }
                 // A dropped receiver only means nobody wants updates any more.
-                let _ = updates_tx.send(notification);
+                let _ = received_updates.send(AcpUpdate::Notification(Box::new(notification)));
                 Ok(())
             },
             agent_client_protocol::on_receive_notification!(),
@@ -589,11 +863,13 @@ async fn run_connection<T>(
                     return Ok(());
                 }
             };
-            let session_id = match load_session {
+            let (session_id, modes, initial_options, models) = match config.load_session {
                 Some(existing) => {
                     if !initialized.agent_capabilities.load_session {
                         let _ = ready_tx.send(Err(ReadyError::Handshake(format!(
-                            "{ADAPTER_BIN} does not advertise loadSession; cannot resume session {existing}"
+                            "{} ACP adapter ({}) does not advertise loadSession; cannot resume session {existing}",
+                            config.adapter,
+                            config.adapter.binary()
                         ))));
                         return Ok(());
                     }
@@ -601,7 +877,11 @@ async fn run_connection<T>(
                     let (loaded_tx, loaded_rx) = oneshot::channel();
                     let replaying_done = replaying.clone();
                     if let Err(e) = cx
-                        .send_request(LoadSessionRequest::new(existing.clone(), cwd))
+                        .send_request(ExtendedLoadSessionRequest {
+                            session_id: SessionId::new(existing.as_str()),
+                            cwd: config.cwd,
+                            mcp_servers: vec![],
+                        })
                         .on_receiving_result(move |result| {
                             replaying_done.store(false, Ordering::SeqCst);
                             async move {
@@ -613,8 +893,8 @@ async fn run_connection<T>(
                         let _ = ready_tx.send(Err(ready_error(e)));
                         return Ok(());
                     }
-                    match loaded_rx.await {
-                        Ok(Ok(_)) => {}
+                    let loaded = match loaded_rx.await {
+                        Ok(Ok(loaded)) => loaded,
                         Ok(Err(e)) => {
                             let _ = ready_tx.send(Err(ready_error(e)));
                             return Ok(());
@@ -625,21 +905,48 @@ async fn run_connection<T>(
                             )));
                             return Ok(());
                         }
-                    }
-                    existing
+                    };
+                    (existing, loaded.modes, loaded.config_options.unwrap_or_default(), loaded.models)
                 }
                 None => match cx
-                    .send_request(NewSessionRequest::new(cwd))
+                    .send_request(ExtendedNewSessionRequest {
+                        cwd: config.cwd,
+                        mcp_servers: vec![],
+                    })
                     .block_task()
                     .await
                 {
-                    Ok(created) => created.session_id.0.to_string(),
+                    Ok(created) => (
+                        created.session_id.0.to_string(),
+                        created.modes,
+                        created.config_options.unwrap_or_default(),
+                        created.models,
+                    ),
                     Err(e) => {
                         let _ = ready_tx.send(Err(ready_error(e)));
                         return Ok(());
                     }
                 },
             };
+            let config_options = Arc::new(Mutex::new(advertised_config_options(
+                initial_options,
+                modes.as_ref(),
+                models.as_ref(),
+            )));
+            if let Some(modes) = &modes {
+                let _ = updates_tx.send(AcpUpdate::Notification(Box::new(SessionNotification::new(
+                    SessionId::new(session_id.as_str()),
+                    SessionUpdate::CurrentModeUpdate(CurrentModeUpdate::new(
+                        modes.current_mode_id.clone(),
+                    )),
+                ))));
+            }
+            if !config_options.lock().expect("config options").is_empty() {
+                let _ = updates_tx.send(AcpUpdate::Notification(Box::new(config_notification(
+                    &session_id,
+                    config_options.lock().expect("config options").clone(),
+                ))));
+            }
             let _ = ready_tx.send(Ok(session_id.clone()));
 
             loop {
@@ -666,16 +973,23 @@ async fn run_connection<T>(
                             let done = Arc::new(Mutex::new(Some(done)));
                             let callback_done = done.clone();
                             let callback_turn = permission_turn.clone();
+                            let callback_updates = updates_tx.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();
+                                let callback_updates = callback_updates.clone();
                                 async move {
                                     callback_turn
                                         .lock()
                                         .expect("permission turn state")
                                         .finish(turn);
+                                    // Route through the same channel as notifications so the
+                                    // event pump sees this after every chunk for the turn.
+                                    let result = result.map(|_| ()).map_err(|e| e.to_string());
                                     if let Some(done) = callback_done.lock().expect("prompt sender").take() {
-                                        let _ = done.send(result.map(|_| ()).map_err(|e| e.to_string()));
+                                        if callback_updates.send(AcpUpdate::TurnDone { turn, result, done }).is_err() {
+                                            // Channel closed — nowhere left to signal.
+                                        }
                                     }
                                     Ok(())
                                 }
@@ -689,6 +1003,83 @@ async fn run_connection<T>(
                                 }
                             }
                         }
+                        Some(Command::SetConfig { config_id, value, done }) => {
+                            let done = Arc::new(Mutex::new(Some(done)));
+                            let callback_done = done.clone();
+                            let callback_options = config_options.clone();
+                            let callback_updates = updates_tx.clone();
+                            let callback_session = session_id.clone();
+                            let callback_config_id = config_id.clone();
+                            let callback_value = value.clone();
+                            let sent = if config_id == LEGACY_MODEL_CONFIG_ID {
+                                let Some(model_id) = value.as_value_id() else {
+                                    let _ = done.lock().expect("config sender").take()
+                                        .map(|done| done.send(Err("model must be a string value".into())));
+                                    continue;
+                                };
+                                cx.send_request(LegacySetModelRequest {
+                                    session_id: SessionId::new(session_id.as_str()),
+                                    model_id: model_id.0.to_string(),
+                                }).on_receiving_result(move |result| async move {
+                                    if result.is_ok() {
+                                        let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
+                                        let _ = callback_updates.send(AcpUpdate::Notification(Box::new(config_notification(&callback_session, options))));
+                                    }
+                                    if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                    }
+                                    Ok(())
+                                })
+                            } else if config_id == LEGACY_MODE_CONFIG_ID {
+                                let Some(mode_id) = value.as_value_id() else {
+                                    let _ = done.lock().expect("config sender").take()
+                                        .map(|done| done.send(Err("mode must be a string value".into())));
+                                    continue;
+                                };
+                                cx.send_request(SetSessionModeRequest::new(
+                                    SessionId::new(session_id.as_str()),
+                                    mode_id.0.to_string(),
+                                )).on_receiving_result(move |result| async move {
+                                    if result.is_ok() {
+                                        let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
+                                        let _ = callback_updates.send(AcpUpdate::Notification(Box::new(config_notification(&callback_session, options))));
+                                        let _ = callback_updates.send(AcpUpdate::Notification(Box::new(SessionNotification::new(
+                                            SessionId::new(callback_session.as_str()),
+                                            SessionUpdate::CurrentModeUpdate(CurrentModeUpdate::new(
+                                                callback_value.as_value_id().expect("checked mode value").0.clone(),
+                                            )),
+                                        ))));
+                                    }
+                                    if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                        let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                    }
+                                    Ok(())
+                                })
+                            } else {
+                                cx.send_request(SetSessionConfigOptionRequest::new(
+                                    SessionId::new(session_id.as_str()),
+                                    config_id,
+                                    value,
+                                ))
+                                    .on_receiving_result(move |result| async move {
+                                        if let Ok(response) = &result {
+                                            let mut current = callback_options.lock().expect("config options");
+                                            current.retain(|option| option.id.0.as_ref().starts_with("__maestro_legacy_"));
+                                            current.extend(response.config_options.clone());
+                                            let _ = callback_updates.send(AcpUpdate::Notification(Box::new(config_notification(&callback_session, current.clone()))));
+                                        }
+                                        if let Some(done) = callback_done.lock().expect("config sender").take() {
+                                            let _ = done.send(result.map(|_| ()).map_err(|error| error.to_string()));
+                                        }
+                                        Ok(())
+                                    })
+                            };
+                            if let Err(error) = sent {
+                                if let Some(done) = done.lock().expect("config sender").take() {
+                                    let _ = done.send(Err(error.to_string()));
+                                }
+                            }
+                        }
                         Some(Command::Close) | None => break,
                     },
                     _ = cx.incoming_closed() => break,
@@ -706,10 +1097,11 @@ async fn drain_stderr(
     stderr: tokio::process::ChildStderr,
     pid: u32,
     tail: Arc<Mutex<VecDeque<u8>>>,
+    adapter: AcpAdapter,
 ) {
     let mut lines = tokio::io::BufReader::new(stderr).lines();
     while let Ok(Some(line)) = lines.next_line().await {
-        tracing::debug!(pid, "{ADAPTER_BIN}: {line}");
+        tracing::debug!(pid, provider = %adapter, "ACP adapter: {line}");
         let mut tail = tail.lock().expect("stderr tail");
         tail.extend(line.as_bytes());
         tail.push_back(b'\n');

crates/maestro-acp/tests/fake_acp_agent.py

@@ -19,6 +19,8 @@ Environment knobs, all optional:
   FAKE_ACP_INIT_FAIL=1    answer `initialize` with a JSON-RPC error
   FAKE_ACP_DELAY_SESSION_NEW_MS=n  wait n milliseconds before answering
                              `session/new`
+  FAKE_ACP_SESSION_NEW_GATE=path  wait for `path` to exist before answering
+                             `session/new`
   FAKE_ACP_EXIT_AFTER_NEW=1  exit 0 right after answering `session/new`
   FAKE_ACP_EXIT_ON_CANCEL=1  exit 0 on `session/cancel` (default: keep running
                              so the SIGTERM path is exercised)
@@ -34,6 +36,7 @@ Environment knobs, all optional:
   FAKE_ACP_PROMPT_FAIL=1  answer every `session/prompt` with a JSON-RPC error
   FAKE_ACP_PROMPT_FAIL_ONCE=1  answer only the first `session/prompt` with a
                              JSON-RPC error
+  FAKE_ACP_SETTINGS=1      advertise legacy model/mode and modern effort options
   FAKE_ACP_PERMISSION_AFTER_CANCEL=1  defer the first prompt's permission
                              callback until a later prompt
 
@@ -76,6 +79,41 @@ prompt_failures = 0
 pending_prompt_id = None
 pending_permission_id = None
 delayed_permission = False
+current_model = "opus"
+current_mode = "default"
+current_effort = "high"
+
+
+def settings_response(include_session=False):
+    result = {}
+    if include_session:
+        result["sessionId"] = session_id
+    if os.environ.get("FAKE_ACP_SETTINGS") == "1":
+        result.update({
+            "models": {
+                "currentModelId": current_model,
+                "availableModels": [
+                    {"modelId": "opus", "name": "Opus"},
+                    {"modelId": "sonnet", "name": "Sonnet"},
+                ],
+            },
+            "modes": {
+                "currentModeId": current_mode,
+                "availableModes": [
+                    {"id": "default", "name": "Default"},
+                    {"id": "plan", "name": "Plan"},
+                ],
+            },
+            "configOptions": [{
+                "id": "effort", "name": "Effort", "category": "thought_level",
+                "type": "select", "currentValue": current_effort,
+                "options": [
+                    {"value": "low", "name": "Low"},
+                    {"value": "high", "name": "High"},
+                ],
+            }],
+        })
+    return result
 
 
 def chunk(text):
@@ -133,8 +171,11 @@ for raw in sys.stdin:
             "authMethods": [],
         }})
     elif method == "session/new":
+        gate = os.environ.get("FAKE_ACP_SESSION_NEW_GATE")
+        while gate and not os.path.exists(gate):
+            time.sleep(0.01)
         time.sleep(int(os.environ.get("FAKE_ACP_DELAY_SESSION_NEW_MS", "0")) / 1000)
-        send({"jsonrpc": "2.0", "id": rid, "result": {"sessionId": session_id}})
+        send({"jsonrpc": "2.0", "id": rid, "result": settings_response(True)})
         send(chunk("hello from fake"))
         if os.environ.get("FAKE_ACP_EXIT_AFTER_NEW") == "1":
             sys.exit(0)
@@ -147,8 +188,18 @@ for raw in sys.stdin:
             continue
         for i in range(int(os.environ.get("FAKE_ACP_LOAD_REPLAY", "0"))):
             send(chunk(f"replayed {i + 1}"))
-        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+        send({"jsonrpc": "2.0", "id": rid, "result": settings_response()})
         send(chunk("hello after load"))
+    elif method == "session/set_model":
+        current_model = params.get("modelId")
+        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+    elif method == "session/set_mode":
+        current_mode = params.get("modeId")
+        send({"jsonrpc": "2.0", "id": rid, "result": {}})
+    elif method == "session/set_config_option":
+        current_effort = params.get("value")
+        send({"jsonrpc": "2.0", "id": rid, "result": {
+            "configOptions": settings_response()["configOptions"]}})
     elif method == "session/cancel":
         if os.environ.get("FAKE_ACP_EMIT_ON_CANCEL") == "1":
             send(chunk("final on cancel"))

crates/maestro-acp/tests/spawn.rs

@@ -1,12 +1,12 @@
 //! `maestro-acp` against the fake adapter in `tests/fake_acp_agent.py`, plus
-//! one ignored test against the real `claude-code-acp`.
+//! ignored smoke tests against each maintained adapter.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
 
 use maestro_acp::schema::{ContentBlock, SessionUpdate};
-use maestro_acp::{AcpError, SpawnConfig, ADAPTER_BIN, INSTALL_COMMAND};
+use maestro_acp::{AcpAdapter, AcpError, SpawnConfig, ADAPTER_BIN, INSTALL_COMMAND};
 use tempfile::TempDir;
 
 fn fake_agent() -> PathBuf {
@@ -25,6 +25,7 @@ impl Fake {
         let bin = dir.path().join("bin");
         std::fs::create_dir_all(&bin).unwrap();
         std::fs::copy(fake_agent(), bin.join(ADAPTER_BIN)).unwrap();
+        std::fs::copy(fake_agent(), bin.join(AcpAdapter::Codex.binary())).unwrap();
         Self { dir }
     }
 
@@ -146,12 +147,38 @@ async fn missing_adapter_names_the_install_command() {
     let err = maestro_acp::spawn(SpawnConfig::new(cwd.path(), env))
         .await
         .expect_err("no adapter on PATH");
-    assert!(matches!(err, AcpError::AdapterMissing));
+    assert!(matches!(
+        err,
+        AcpError::AdapterMissing {
+            adapter: AcpAdapter::ClaudeCode
+        }
+    ));
     let msg = err.to_string();
     assert!(msg.contains(ADAPTER_BIN), "{msg}");
     assert!(msg.contains(INSTALL_COMMAND), "{msg}");
 }
 
+#[test]
+fn codex_adapter_has_its_own_binary_and_install_guidance() {
+    assert_eq!(AcpAdapter::Codex.binary(), "codex-acp");
+    assert!(AcpAdapter::Codex
+        .install_command()
+        .contains("@agentclientprotocol/codex-acp"));
+}
+
+#[tokio::test]
+async fn spawn_selects_the_codex_adapter() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = maestro_acp::spawn(fake.config(cwd.path()).adapter(AcpAdapter::Codex))
+        .await
+        .expect("spawn Codex adapter");
+    assert!(fake.log().contains("recv session/new"));
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
 #[tokio::test]
 async fn session_updates_reach_the_taken_receiver() {
     let fake = Fake::new();
@@ -166,6 +193,9 @@ async fn session_updates_reach_the_taken_receiver() {
         .await
         .expect("update within 5s")
         .expect("channel open");
+    let maestro_acp::AcpUpdate::Notification(first) = first else {
+        panic!("expected Notification");
+    };
     assert_eq!(first.session_id.0.as_ref(), session.session_id());
     match first.update {
         SessionUpdate::AgentMessageChunk(chunk) => match chunk.content {
@@ -180,11 +210,71 @@ async fn session_updates_reach_the_taken_receiver() {
         .await;
 }
 
+#[tokio::test]
+async fn advertised_settings_are_normalized_and_mutable() {
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let mut config = fake.config(cwd.path());
+    config.env.insert("FAKE_ACP_SETTINGS".into(), "1".into());
+    let session = maestro_acp::spawn(config).await.expect("spawn");
+    let mut updates = session.take_updates().expect("updates");
+
+    let initial = loop {
+        let update = tokio::time::timeout(Duration::from_secs(5), updates.recv())
+            .await
+            .expect("settings update")
+            .expect("channel open");
+        let maestro_acp::AcpUpdate::Notification(n) = update else {
+            continue;
+        };
+        if let SessionUpdate::ConfigOptionUpdate(options) = n.update {
+            break options.config_options;
+        }
+    };
+    assert_eq!(initial.len(), 3);
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "effort"));
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "__maestro_legacy_model"));
+    assert!(initial
+        .iter()
+        .any(|option| option.id.0.as_ref() == "__maestro_legacy_mode"));
+    let model = initial
+        .iter()
+        .find(|option| option.id.0.as_ref() == "__maestro_legacy_model")
+        .expect("legacy model option");
+    let model = serde_json::to_value(model).unwrap();
+    assert_eq!(model["options"][0]["name"], "Opus");
+    assert!(model["options"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .any(|option| option["value"] == "fable"));
+
+    let changed = session
+        .set_config(
+            "__maestro_legacy_model".into(),
+            maestro_acp::schema::SessionConfigOptionValue::value_id("sonnet"),
+        )
+        .expect("queue model change");
+    changed
+        .await
+        .expect("response delivered")
+        .expect("model changed");
+    fake.wait_for_log("recv session/set_model").await;
+
+    session
+        .terminate(Duration::from_millis(100), Duration::from_secs(2))
+        .await;
+}
+
 #[tokio::test]
 async fn terminate_sends_cancel_then_sigterm() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let session = maestro_acp::spawn(fake.config(cwd.path()))
+    let session = maestro_acp::spawn(fake.config(cwd.path()).adapter(AcpAdapter::Codex))
         .await
         .expect("spawn");
     let pid = session.pid();
@@ -225,7 +315,7 @@ async fn terminate_is_satisfied_by_an_exit_on_cancel() {
 async fn handshake_error_fails_the_spawn_and_reaps_the_child() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path());
+    let mut config = fake.config(cwd.path()).adapter(AcpAdapter::Codex);
     config.env.insert("FAKE_ACP_INIT_FAIL".into(), "1".into());
 
     let err = maestro_acp::spawn(config).await.expect_err("init fails");
@@ -284,7 +374,7 @@ async fn child_exit_before_handshake_reports_exited_early() {
 
     let err = maestro_acp::spawn(config).await.expect_err("child died");
     match &err {
-        AcpError::ExitedEarly { status, stderr } => {
+        AcpError::ExitedEarly { status, stderr, .. } => {
             assert!(status.contains('3'), "{status}");
             assert!(stderr.contains("not logged in"), "{stderr}");
         }
@@ -306,7 +396,10 @@ async fn drop_terminates_and_reaps_the_child() {
     fake.wait_for_exit().await;
 }
 
-fn chunk_text(n: &maestro_acp::schema::SessionNotification) -> String {
+fn chunk_text(update: &maestro_acp::AcpUpdate) -> String {
+    let maestro_acp::AcpUpdate::Notification(n) = update else {
+        panic!("expected Notification, got {update:?}");
+    };
     match &n.update {
         SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
             ContentBlock::Text(t) => t.text.clone(),
@@ -320,7 +413,10 @@ fn chunk_text(n: &maestro_acp::schema::SessionNotification) -> String {
 async fn load_session_resumes_the_stored_id_and_drops_the_replay() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_LOAD_REPLAY".into(), "3".into());
 
     let session = maestro_acp::spawn(config).await.expect("spawn");
@@ -353,7 +449,10 @@ async fn load_session_resumes_the_stored_id_and_drops_the_replay() {
 async fn load_session_requires_the_load_capability() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_NO_LOAD".into(), "1".into());
 
     let err = maestro_acp::spawn(config)
@@ -368,7 +467,10 @@ async fn load_session_requires_the_load_capability() {
 async fn load_session_error_fails_the_spawn() {
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let mut config = fake.config(cwd.path()).load_session("fake-old");
+    let mut config = fake
+        .config(cwd.path())
+        .adapter(AcpAdapter::Codex)
+        .load_session("fake-old");
     config.env.insert("FAKE_ACP_LOAD_FAIL".into(), "1".into());
 
     let err = maestro_acp::spawn(config).await.expect_err("load fails");
@@ -392,3 +494,21 @@ async fn real_adapter_handshake() {
         .await;
     assert!(session.has_exited());
 }
+
+/// End to end against the maintained Codex adapter. It needs a locally
+/// authenticated Codex CLI, so CI runs it only when explicitly requested.
+#[tokio::test]
+#[ignore]
+async fn real_codex_adapter_handshake() {
+    let cwd = TempDir::new().unwrap();
+    let session =
+        maestro_acp::spawn(SpawnConfig::new(cwd.path(), HashMap::new()).adapter(AcpAdapter::Codex))
+            .await
+            .expect("real codex-acp handshake");
+    assert!(!session.session_id().is_empty());
+    assert!(pid_alive(session.pid()));
+    session
+        .terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+        .await;
+    assert!(session.has_exited());
+}

crates/maestro-cli/src/attach.rs

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

crates/maestro-cli/src/cli.rs

@@ -41,8 +41,8 @@ pub enum Command {
     Attach(AttachArgs),
     /// Kill a session by ID.
     Kill(KillArgs),
-    /// Type text into a running session, as if it had been typed on an
-    /// attached terminal.
+    /// Send text to a running session. Terminal sessions receive raw
+    /// keystrokes; structured sessions receive an ACP prompt.
     Send(SendArgs),
     /// Install or update the agent activity hook (#106).
     Hooks(HooksArgs),
@@ -92,6 +92,14 @@ pub struct SpawnArgs {
     /// there.
     #[arg(long)]
     pub existing_branch: bool,
+    /// Run a Claude Code or Codex session in a plain terminal instead of the
+    /// structured (ACP) view it otherwise gets by default.
+    #[arg(long, conflicts_with = "structured")]
+    pub terminal: bool,
+    /// Ask for the structured (ACP) view explicitly. Only Claude Code and
+    /// Codex commands have an adapter; the daemon refuses anything else.
+    #[arg(long)]
+    pub structured: bool,
     /// After spawning, attach immediately.
     #[arg(long, short = 'a')]
     pub attach: bool,
@@ -125,7 +133,7 @@ pub struct KillArgs {
     /// Session ID to kill.
     pub session_id: Uuid,
     /// End the session even when its worktree holds unsaved work (#81). The
-    /// worktree is left on disk — never removed.
+    /// worktree is removed along with the session.
     #[arg(long)]
     pub force: bool,
 }

crates/maestro-cli/src/sessions.rs

@@ -3,10 +3,10 @@
 use std::collections::HashMap;
 use std::io::Write;
 
-use maestro_protocol::display::abbreviate_dir;
+use maestro_protocol::display::{abbreviate_dir, supports_structured_view};
 use maestro_protocol::{
     ActivityState, ClientError, CreateSessionRequest, DaemonClient, DaemonInfo, SendInputRequest,
-    Session, SessionStatus, WorktreeSpec,
+    Session, SessionStatus, SessionView, WorktreeSpec,
 };
 use serde_json::Value;
 
@@ -51,16 +51,33 @@ pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session
     };
 
     let body = CreateSessionRequest {
-        view: Default::default(),
+        view: spawn_view(&args),
         cwd: args.cwd.clone(),
         command: args.command.clone(),
         env,
         metadata,
         worktree,
+        auto_approve: false,
     };
     client.create_session(&body).await
 }
 
+/// The view a `maestro spawn` asks for: structured whenever the command
+/// resolves to an agent with an ACP adapter, since that is the richer session
+/// and the one both other clients now default to. `--terminal` opts out;
+/// `--structured` forces the request through even for a command this side
+/// does not recognise, leaving the refusal to the daemon.
+fn spawn_view(args: &SpawnArgs) -> SessionView {
+    if args.terminal {
+        return SessionView::Terminal;
+    }
+    if args.structured || supports_structured_view(&args.command) {
+        SessionView::Structured
+    } else {
+        SessionView::Terminal
+    }
+}
+
 /// `maestro kill`. A forced kill (#81) retains the guarded worktree instead
 /// of removing it; the outcome names what was kept so dispatch can say where
 /// the work went.
@@ -113,9 +130,12 @@ pub fn resolve_session(sessions: &[Session], needle: &str) -> Result<uuid::Uuid,
 /// `maestro send`. Answers with the session that was typed into, so the
 /// caller can name it once the daemon has accepted the text.
 ///
-/// A bare ID skips the catalog fetch; anything else needs the list to match
-/// against. Text comes from the arguments, or from stdin when there is none —
-/// the shape a heredoc or a pipe wants.
+/// Terminal sessions get raw keystrokes via `send_input`; structured sessions
+/// get an ACP prompt via `send_structured_prompt` (`--no-enter` is ignored
+/// there — ACP prompts are always complete messages).
+///
+/// Text comes from the arguments, or from stdin when there is none — the
+/// shape a heredoc or a pipe wants.
 #[allow(clippy::result_large_err)]
 pub async fn run_send(
     client: &DaemonClient,
@@ -138,19 +158,28 @@ pub async fn run_send(
         return Err(CliError::NothingToSend);
     }
 
-    let id = match uuid::Uuid::parse_str(args.session.trim()) {
-        Ok(id) => id,
-        Err(_) => {
-            let sessions = client.list_sessions().await?;
-            resolve_session(&sessions, &args.session)?
-        }
-    };
+    // We always need the session list: even a bare UUID needs the view field
+    // to decide which endpoint to hit.
+    let sessions = client.list_sessions().await?;
+    let id = resolve_session(&sessions, &args.session)?;
+    let view = sessions
+        .iter()
+        .find(|s| s.id == id)
+        .map(|s| s.view)
+        .unwrap_or(SessionView::Terminal);
 
-    let req = SendInputRequest {
-        text,
-        submit: !args.no_enter,
-    };
-    client.send_input(id, &req).await?;
+    match view {
+        SessionView::Structured => {
+            client.send_structured_prompt(id, &text).await?;
+        }
+        SessionView::Terminal => {
+            let req = SendInputRequest {
+                text,
+                submit: !args.no_enter,
+            };
+            client.send_input(id, &req).await?;
+        }
+    }
     Ok(id)
 }
 
@@ -179,8 +208,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
     }
     writeln!(
         out,
-        "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {}",
-        "ID", "STATUS", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
+        "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {}",
+        "ID", "STATUS", "VIEW", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
     )
     .ok();
     for s in sorted {
@@ -190,11 +219,16 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             SessionStatus::Running => "running",
             SessionStatus::Dead => "dead",
         };
+        let view = match s.view {
+            SessionView::Terminal => "terminal",
+            SessionView::Structured => "structured",
+        };
         let activity = match s.activity {
             ActivityState::Active => "active",
             ActivityState::Idle => "idle",
             ActivityState::AwaitingInput => "awaiting",
             ActivityState::Error => "error",
+            ActivityState::Starting => "starting",
         };
         // Show the live foreground command alongside the spawn command when
         // the daemon has observed one that differs (NAP-340).
@@ -207,8 +241,8 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
         let blocked = blocked_label(s);
         writeln!(
             out,
-            "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {blocked}",
-            s.id, status, activity, dir, command
+            "  {:<36}  {:<8}  {:<10}  {:<9}  {:<28}  {:<40}  {blocked}",
+            s.id, status, view, activity, dir, command
         )
         .ok();
     }
@@ -230,11 +264,67 @@ mod tests {
     use std::path::PathBuf;
 
     use chrono::{TimeZone, Utc};
-    use maestro_protocol::{ActivityState, Session, SessionStatus};
+    use maestro_protocol::{ActivityState, Session, SessionStatus, SessionView};
     use uuid::Uuid;
 
     use super::DaemonInfo;
 
+    use clap::Parser;
+
+    use crate::cli::{Cli, Command};
+
+    fn spawn_args(extra: &[&str]) -> crate::cli::SpawnArgs {
+        let mut argv = vec!["maestro", "spawn", "--cwd", "/tmp", "--command"];
+        argv.extend_from_slice(extra);
+        let cli = Cli::try_parse_from(argv).expect("parses");
+        let Command::Spawn(args) = cli.command else {
+            panic!("expected spawn")
+        };
+        args
+    }
+
+    /// The CLI follows the two interactive clients: a command with an ACP
+    /// adapter spawns structured unless `--terminal` says otherwise, and
+    /// `--structured` still forces the request for a command this side does
+    /// not recognise.
+    #[test]
+    fn spawn_defaults_to_structured_for_supported_agents() {
+        use super::spawn_view;
+        assert_eq!(
+            spawn_view(&spawn_args(&["claude"])),
+            SessionView::Structured
+        );
+        assert_eq!(
+            spawn_view(&spawn_args(&["npx codex exec"])),
+            SessionView::Structured
+        );
+        assert_eq!(spawn_view(&spawn_args(&["bash"])), SessionView::Terminal);
+        assert_eq!(
+            spawn_view(&spawn_args(&["claude", "--terminal"])),
+            SessionView::Terminal
+        );
+        assert_eq!(
+            spawn_view(&spawn_args(&["opencode", "--structured"])),
+            SessionView::Structured
+        );
+    }
+
+    #[test]
+    fn spawn_refuses_both_view_flags_at_once() {
+        let err = Cli::try_parse_from([
+            "maestro",
+            "spawn",
+            "--cwd",
+            "/tmp",
+            "--command",
+            "claude",
+            "--structured",
+            "--terminal",
+        ])
+        .unwrap_err();
+        assert!(err.to_string().contains("--terminal"), "{err}");
+    }
+
     fn session(cwd: &str, command: &str, id: u128) -> Session {
         Session {
             view: Default::default(),
@@ -255,6 +345,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 
@@ -286,6 +378,22 @@ mod tests {
         assert!(s.contains("idle"), "{s}");
     }
 
+    #[test]
+    fn table_exposes_terminal_and_structured_views() {
+        let terminal = session("/tmp", "bash", 1);
+        let mut structured = session("/tmp", "claude", 2);
+        structured.view = SessionView::Structured;
+
+        let mut buf = Vec::new();
+        super::print_session_table(&mut buf, &[terminal, structured], &info(""));
+        let out = String::from_utf8(buf).unwrap();
+        let lines: Vec<&str> = out.lines().collect();
+        let header = lines.iter().position(|line| line.contains("VIEW")).unwrap();
+
+        assert!(lines[header + 1].contains("terminal"), "{out}");
+        assert!(lines[header + 2].contains("structured"), "{out}");
+    }
+
     #[test]
     fn live_cwd_overrides_spawn_dir_in_table() {
         let mut s = session("/home/naps/maestro", "bash", 1);

crates/maestro-cli/tests/against_mock_daemon.rs

@@ -2,7 +2,7 @@
 //! was unit-tested, but nothing exercised the client, the error decoding, or
 //! the unreachable-daemon path without compiling and forking a real daemon.
 
-use maestro_protocol::{DaemonClient, DaemonInfo};
+use maestro_protocol::{DaemonClient, DaemonInfo, SessionView};
 use maestro_testing::{session, MockDaemon};
 use uuid::Uuid;
 
@@ -28,6 +28,7 @@ async fn info_carries_version_and_presets() {
             id: "claude".into(),
             label: "Claude".into(),
             command: "claude".into(),
+            auto_approve: false,
         }],
         ..Default::default()
     });
@@ -97,6 +98,7 @@ async fn spawn_round_trips_through_the_daemon() {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -200,6 +202,35 @@ async fn send_resolves_a_session_by_name() {
     assert_eq!(sent, id);
 }
 
+/// A structured session routes through the ACP prompt endpoint, not the
+/// terminal input one — `--no-enter` is irrelevant (ACP prompts are
+/// complete messages).
+#[tokio::test]
+async fn send_to_structured_session_uses_acp_prompt() {
+    let mock = MockDaemon::start().await;
+    let id = Uuid::from_u128(13);
+    let mut s = session(id, "/tmp", "claude");
+    s.view = SessionView::Structured;
+    mock.add_session(s);
+
+    let args = maestro_cli::cli::SendArgs {
+        session: id.to_string(),
+        text: vec!["fix".into(), "the".into(), "tests".into()],
+        no_enter: false,
+    };
+    let sent = maestro_cli::sessions::run_send(&mock.client(), &args, &mut std::io::empty())
+        .await
+        .expect("send");
+
+    assert_eq!(sent, id);
+    // Terminal input must stay empty — the message went through ACP.
+    assert!(mock.inputs().is_empty());
+    let prompts = mock.structured_prompts();
+    assert_eq!(prompts.len(), 1);
+    assert_eq!(prompts[0].0, id);
+    assert_eq!(prompts[0].1.prompt, "fix the tests");
+}
+
 #[tokio::test]
 async fn send_to_an_unknown_session_fails_without_typing_anything() {
     let mock = MockDaemon::start().await;

crates/maestro-config/src/lib.rs

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

crates/maestro-daemon/src/gitroot.rs

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

crates/maestro-daemon/src/local_api.rs

@@ -12,7 +12,8 @@
 
 use std::sync::Arc;
 
-use axum::extract::{Path, Query, State};
+use axum::body::Bytes;
+use axum::extract::{DefaultBodyLimit, Path, Query, State};
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
 use axum::routing::{any, delete, get, post};
@@ -21,12 +22,13 @@ use maestro_config::SpawnPreset;
 use maestro_protocol::{
     routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch,
     RenameSessionRequest, ReportActivityRequest, SendInputRequest, Session, SetFocusRequest,
-    StructuredApprovalDecision, StructuredEvent, StructuredPromptRequest, PROTOCOL_VERSION,
+    StructuredApprovalDecision, StructuredConfigRequest, StructuredEvent, StructuredPromptRequest,
+    PROTOCOL_VERSION,
 };
 use serde::Deserialize;
 use uuid::Uuid;
 
-use crate::session::{QueueAcpPrompt, SessionManager};
+use crate::session::{QueueAcpPrompt, SessionError, SessionManager, SetAcpConfig};
 use crate::sidecar::EventCursor;
 
 #[derive(Debug, Clone)]
@@ -69,7 +71,12 @@ pub fn router(state: LocalApiState) -> Router {
         .route(routes::patterns::STRUCTURED, any(structured_ws))
         .route(routes::patterns::STRUCTURED_REPLAY, get(structured_replay))
         .route(routes::patterns::STRUCTURED_PROMPT, post(structured_prompt))
+        .route(
+            routes::patterns::STRUCTURED_ATTACHMENT,
+            post(structured_attachment).layer(DefaultBodyLimit::max(20 * 1024 * 1024)),
+        )
         .route(routes::patterns::STRUCTURED_CANCEL, post(structured_cancel))
+        .route(routes::patterns::STRUCTURED_CONFIG, post(structured_config))
         .route(
             routes::patterns::STRUCTURED_APPROVAL,
             post(structured_approval),
@@ -173,12 +180,13 @@ fn dir_error_status(code: &str) -> StatusCode {
 fn session_error_status(code: &str) -> StatusCode {
     match code {
         "not_found" => StatusCode::NOT_FOUND,
-        "invalid_env" => StatusCode::BAD_REQUEST,
+        "invalid_env" | "bad_request" => StatusCode::BAD_REQUEST,
         // A guard refusal is the daemon doing its job, not a failure (#79).
         "kill_guarded" => StatusCode::CONFLICT,
         // The session outlived its pane: nothing to type into, and nothing
         // the daemon can do about it.
         "not_running" => StatusCode::CONFLICT,
+        "not_terminal" => StatusCode::CONFLICT,
         "shutting_down" => StatusCode::SERVICE_UNAVAILABLE,
         _ => StatusCode::BAD_GATEWAY,
     }
@@ -429,17 +437,58 @@ async fn structured_replay(
     }
 }
 
+#[derive(Deserialize)]
+struct AttachmentQuery {
+    name: String,
+}
+
+async fn structured_attachment(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Query(query): Query<AttachmentQuery>,
+    bytes: Bytes,
+) -> Response {
+    let name = query.name;
+    if name.is_empty()
+        || name.len() > 180
+        || name == "."
+        || name == ".."
+        || name
+            .chars()
+            .any(|c| c.is_control() || c == '/' || c == '\\')
+    {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "invalid_filename",
+            "use a filename without directory separators, up to 180 bytes",
+        );
+    }
+    match s.manager.store_acp_attachment(id, &name, &bytes).await {
+        Ok(Some(path)) => Json(serde_json::json!({ "path": path })).into_response(),
+        Ok(None) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
 async fn structured_prompt(
     State(s): State<LocalApiState>,
     Path(id): Path<Uuid>,
     Json(body): Json<StructuredPromptRequest>,
 ) -> Response {
-    match s.manager.queue_acp_prompt(id, body.prompt).await {
-        Ok(QueueAcpPrompt::Queued) => StatusCode::NO_CONTENT.into_response(),
-        Ok(QueueAcpPrompt::InFlight) => error_response(
-            StatusCode::CONFLICT,
-            "turn_in_flight",
-            "the structured session already has an active turn",
+    match s.manager.queue_acp_prompt(id, body.prompt, None).await {
+        Ok(QueueAcpPrompt::Dispatched) => StatusCode::NO_CONTENT.into_response(),
+        Ok(QueueAcpPrompt::Queued) => StatusCode::ACCEPTED.into_response(),
+        Ok(QueueAcpPrompt::Full) => error_response(
+            StatusCode::TOO_MANY_REQUESTS,
+            "queue_full",
+            "the prompt queue has reached its capacity",
         ),
         Ok(QueueAcpPrompt::Unavailable) => error_response(
             StatusCode::CONFLICT,
@@ -471,6 +520,37 @@ async fn structured_cancel(State(s): State<LocalApiState>, Path(id): Path<Uuid>)
     }
 }
 
+async fn structured_config(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<StructuredConfigRequest>,
+) -> Response {
+    match s
+        .manager
+        .set_acp_config(id, body.config_id, body.value)
+        .await
+    {
+        Ok(SetAcpConfig::Updated) => StatusCode::NO_CONTENT.into_response(),
+        Ok(SetAcpConfig::InvalidValue) => error_response(
+            StatusCode::BAD_REQUEST,
+            "invalid_config_value",
+            "configuration values must be strings or booleans",
+        ),
+        Ok(SetAcpConfig::Unavailable) => error_response(
+            StatusCode::CONFLICT,
+            "not_structured",
+            "session is not a live structured session",
+        ),
+        Ok(SetAcpConfig::Failed(message)) => {
+            error_response(StatusCode::BAD_GATEWAY, "acp_config_failed", &message)
+        }
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(session_error_status(&info.code), &info.code, &info.message)
+        }
+    }
+}
+
 async fn structured_approval(
     State(s): State<LocalApiState>,
     Path((id, nonce)): Path<(Uuid, String)>,
@@ -534,12 +614,23 @@ async fn attach_ws(
     State(s): State<LocalApiState>,
     ws: axum::extract::WebSocketUpgrade,
 ) -> Result<Response, Response> {
-    let Some((replay, rx)) = s.manager.subscribe_pty_with_replay(id).await else {
-        return Err(error_response(
-            StatusCode::NOT_FOUND,
-            "unknown_session",
-            "no such session on this daemon",
-        ));
+    let (replay, rx) = match s.manager.subscribe_pty_with_replay(id).await {
+        Ok(subscription) => subscription,
+        Err(SessionError::NotFound(_)) => {
+            return Err(error_response(
+                StatusCode::NOT_FOUND,
+                "unknown_session",
+                "no such session on this daemon",
+            ));
+        }
+        Err(error) => {
+            let info = error.to_error_info();
+            return Err(error_response(
+                session_error_status(&info.code),
+                &info.code,
+                &info.message,
+            ));
+        }
     };
     let manager = s.manager.clone();
     Ok(ws.on_upgrade(move |socket| async move {

crates/maestro-daemon/src/projection.rs

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

crates/maestro-daemon/src/sidecar.rs

@@ -263,9 +263,15 @@ pub struct LoggedEvent {
 #[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
 #[serde(tag = "maestroEvent", rename_all = "snake_case")]
 pub enum PersistedEvent {
+    User {
+        row: TranscriptRow,
+    },
     Approval {
         row: TranscriptRow,
     },
+    Turn {
+        row: TranscriptRow,
+    },
     #[serde(skip)]
     Notification(Box<SessionNotification>),
 }

crates/maestro-daemon/tests/acp.rs

@@ -11,7 +11,7 @@ use std::time::{Duration, Instant};
 
 use common::{init_bare_repo, init_repo, push_all_to_origin, wait_for_async, DaemonFixture};
 use maestro_acp::schema::{ContentBlock, SessionUpdate};
-use maestro_acp::{ADAPTER_BIN, INSTALL_COMMAND};
+use maestro_acp::{AcpAdapter, ADAPTER_BIN};
 use maestro_daemon::projection::TurnLifecycle;
 use maestro_daemon::sidecar::{EventCursor, SidecarStore};
 use maestro_daemon::worktree::WorktreeManager;
@@ -38,6 +38,7 @@ impl Fake {
         let bin = dir.path().join("bin");
         std::fs::create_dir_all(&bin).unwrap();
         std::fs::copy(fake_agent(), bin.join(ADAPTER_BIN)).unwrap();
+        std::fs::copy(fake_agent(), bin.join(AcpAdapter::Codex.binary())).unwrap();
         Self { dir }
     }
 
@@ -83,26 +84,47 @@ impl Fake {
 }
 
 fn event_text(event: &maestro_daemon::sidecar::LoggedEvent) -> &str {
-    let maestro_daemon::sidecar::PersistedEvent::Notification(notification) = &event.event else {
-        panic!("unexpected daemon event")
-    };
-    match &notification.update {
-        SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
-            ContentBlock::Text(text) => &text.text,
-            other => panic!("unexpected content {other:?}"),
-        },
-        other => panic!("unexpected update {other:?}"),
+    match &event.event {
+        maestro_daemon::sidecar::PersistedEvent::Notification(notification) => {
+            match &notification.update {
+                SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
+                    ContentBlock::Text(text) => &text.text,
+                    other => panic!("unexpected content {other:?}"),
+                },
+                other => panic!("unexpected update {other:?}"),
+            }
+        }
+        maestro_daemon::sidecar::PersistedEvent::User { row } => row
+            .data
+            .pointer("/content/text")
+            .and_then(serde_json::Value::as_str)
+            .expect("user row text"),
+        maestro_daemon::sidecar::PersistedEvent::Turn { row } => row
+            .data
+            .pointer("/maestroTurnMeta/outcome")
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or("[turn]"),
+        maestro_daemon::sidecar::PersistedEvent::Approval { .. } => "[approval]",
     }
 }
 
 fn structured(cwd: &Path, env: HashMap<String, String>) -> CreateSessionRequest {
+    structured_command(cwd, env, "claude")
+}
+
+fn structured_command(
+    cwd: &Path,
+    env: HashMap<String, String>,
+    command: &str,
+) -> CreateSessionRequest {
     CreateSessionRequest {
         view: SessionView::Structured,
         cwd: cwd.to_path_buf(),
-        command: "claude".into(),
+        command: command.into(),
         env,
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     }
 }
 
@@ -120,6 +142,25 @@ async fn wait_for_exit(pid: u32) {
     assert!(!pid_alive(pid), "pid {pid} still alive");
 }
 
+/// Wait for a session's background ACP handshake to complete (activity
+/// transitions out of `Starting`). Returns the refreshed session.
+async fn wait_for_ready(manager: &SessionManager, id: uuid::Uuid) -> maestro_protocol::Session {
+    let deadline = Instant::now() + Duration::from_secs(10);
+    loop {
+        let session = manager
+            .snapshot()
+            .await
+            .into_iter()
+            .find(|s| s.id == id)
+            .expect("session exists");
+        if session.activity != ActivityState::Starting {
+            return session;
+        }
+        assert!(Instant::now() < deadline, "handshake timed out");
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+}
+
 #[tokio::test]
 async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let fx = DaemonFixture::new();
@@ -128,14 +169,22 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(
+            cwd.path(),
+            env,
+            "codex --dangerously-bypass-approvals-and-sandbox",
+        ))
         .await
         .expect("create");
 
-    assert_eq!(session.view, SessionView::Structured);
-    assert_eq!(session.status, SessionStatus::Running);
+    assert_eq!(created.view, SessionView::Structured);
+    assert_eq!(created.status, SessionStatus::Running);
+    assert_eq!(created.activity, ActivityState::Starting);
+    assert!(created.acp_session_id.is_none());
+
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.activity, ActivityState::Idle);
     let acp_id = session.acp_session_id.clone().expect("acp session id");
     assert!(acp_id.starts_with("fake-"), "{acp_id}");
@@ -150,7 +199,7 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
         "{log}"
     );
     assert!(
-        log.contains(&format!("env MAESTRO_SESSION_ID={}", session.id)),
+        log.contains(&format!("env MAESTRO_SESSION_ID={}", created.id)),
         "{log}"
     );
 
@@ -215,16 +264,17 @@ async fn structured_activity_tracks_turn_completion_and_failure() {
     env.insert("FAKE_ACP_PROMPT_FAIL_ONCE".into(), "1".into());
     let session = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .unwrap();
+    let session = wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "fail".into())
+            .queue_acp_prompt(session.id, "fail".into(), None)
             .await
             .unwrap(),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
     assert_eq!(
         fx.manager
@@ -248,10 +298,10 @@ async fn structured_activity_tracks_turn_completion_and_failure() {
 
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "succeed".into())
+            .queue_acp_prompt(session.id, "succeed".into(), None)
             .await
             .unwrap(),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
     assert_eq!(
         fx.manager
@@ -281,11 +331,12 @@ async fn projection_snapshot_and_live_stream_share_one_fold() {
     let fx = DaemonFixture::new();
     let fake = Fake::new();
     let cwd = TempDir::new().unwrap();
-    let session = fx
+    let created = fx
         .manager
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
 
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -349,12 +400,76 @@ async fn projection_snapshot_and_live_stream_share_one_fold() {
         .await
         .expect("finish lifecycle broadcast")
         .expect("projection broadcast");
-    assert_eq!(finish.transcript, None);
+    let Some(TranscriptDelta::Append { row }) = finish.transcript else {
+        panic!("finish should append durable turn metadata");
+    };
+    assert_eq!(row.kind, TranscriptRowKind::Notice);
+    assert_eq!(row.data["maestroTurnMeta"]["outcome"], "completed");
     assert_eq!(finish.state.turn, Default::default());
 
+    let recovered = fx
+        .manager
+        .read_acp_projection_replay(session.id, EventCursor::Since(0), 10)
+        .await
+        .expect("turn replay")
+        .expect("structured session");
+    assert!(recovered.iter().any(|event| {
+        matches!(
+            &event.transcript,
+            Some(TranscriptDelta::Append { row })
+                if row.data["maestroTurnMeta"]["outcome"] == "completed"
+        )
+    }));
+
     fx.manager.kill(session.id, false).await.expect("kill");
 }
 
+#[tokio::test]
+async fn queued_prompt_is_a_durable_user_transcript_row() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let session = fx
+        .manager
+        .create(structured(cwd.path(), fake.env()))
+        .await
+        .expect("create");
+    let session = wait_for_ready(&fx.manager, session.id).await;
+
+    assert!(matches!(
+        fx.manager
+            .queue_acp_prompt(session.id, "show my prompt".into(), None)
+            .await
+            .expect("queue prompt"),
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
+    ));
+
+    let (snapshot, _, _) = fx
+        .manager
+        .subscribe_acp_projection(session.id, EventCursor::Since(0))
+        .await
+        .expect("projection subscription")
+        .expect("structured session");
+    let user = snapshot
+        .rows
+        .iter()
+        .find(|row| row.kind == TranscriptRowKind::User)
+        .expect("user prompt row");
+    assert_eq!(user.data["content"]["text"], "show my prompt");
+
+    let persisted = fx
+        .manager
+        .read_acp_events(session.id, EventCursor::Since(0), 100)
+        .expect("event replay");
+    assert!(persisted.iter().any(|event| matches!(
+        &event.event,
+        maestro_daemon::sidecar::PersistedEvent::User { row }
+            if row.data["content"]["text"] == "show my prompt"
+    )));
+
+    fx.manager.kill(session.id, false).await.unwrap();
+}
+
 #[tokio::test]
 async fn stale_turn_completion_cannot_end_the_next_turn() {
     let fx = DaemonFixture::new();
@@ -365,6 +480,7 @@ async fn stale_turn_completion_cannot_end_the_next_turn() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     let maestro_daemon::session::BeginAcpTurn::Started(_, first) =
         fx.manager.begin_acp_turn(session.id).await.unwrap()
@@ -408,18 +524,19 @@ async fn cancelled_prompt_that_never_settles_fails_the_session() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "first".into())
+            .queue_acp_prompt(session.id, "first".into(), None)
             .await
             .unwrap(),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
     assert!(fx.manager.cancel_acp_turn(session.id).await.unwrap());
     let second = fx
         .manager
-        .queue_acp_prompt(session.id, "second".into())
+        .queue_acp_prompt(session.id, "second".into(), None)
         .await
         .unwrap();
     assert!(
@@ -446,21 +563,22 @@ async fn cancellation_settlement_allows_the_next_prompt_permission() {
         .create(structured(cwd.path(), env))
         .await
         .unwrap();
+    wait_for_ready(&fx.manager, session.id).await;
 
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "first".into())
+            .queue_acp_prompt(session.id, "first".into(), None)
             .await
             .unwrap(),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
     assert!(fx.manager.cancel_acp_turn(session.id).await.unwrap());
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "second".into())
+            .queue_acp_prompt(session.id, "second".into(), None)
             .await
             .unwrap(),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
 
     let nonce = tokio::time::timeout(Duration::from_secs(2), async {
@@ -505,11 +623,12 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_LOAD_REPLAY".into(), "2".into());
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
         .expect("create");
+    let session = wait_for_ready(&fx.manager, created.id).await;
     let acp_id = session.acp_session_id.clone().expect("acp id");
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
@@ -548,25 +667,18 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
         revived.status(session.id).await,
         Some(SessionStatus::Running)
     );
-    assert_eq!(
-        revived
-            .snapshot()
-            .await
-            .into_iter()
-            .find(|candidate| candidate.id == session.id)
-            .unwrap()
-            .activity,
-        ActivityState::Idle
-    );
     let log = fake.log();
     assert!(
         log.contains(&format!("recv session/load sessionId={acp_id}")),
         "{log}"
     );
+    // Recovery adds: a continue-prompt User row, the adapter's post-load
+    // notification, and a turn-completed footer — 5 events total before the
+    // next manual tick.
     wait_for_async(Duration::from_secs(5), || async {
         revived
             .read_acp_events(session.id, EventCursor::Since(0), 10)
-            .is_ok_and(|events| events.len() == 3)
+            .is_ok_and(|events| events.len() == 5)
     })
     .await;
 
@@ -575,7 +687,7 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
         .await
         .expect("replay read")
         .expect("recovered event subscription");
-    assert_eq!(replay.len(), 3);
+    assert_eq!(replay.len(), 5);
     assert!(live.try_recv().is_err(), "replay duplicated onto live");
     let new_pid = fake.pid();
     assert_ne!(new_pid, old_pid);
@@ -586,16 +698,23 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
         .await
         .expect("live event after recovery")
         .expect("broadcast open");
-    assert_eq!(event.seq, 4);
+    assert_eq!(event.seq, 6);
     assert_eq!(event_text(&event), "tick 1");
 
     let stored = revived
         .read_acp_events(session.id, EventCursor::Since(0), 10)
         .expect("recovered log");
-    assert_eq!(stored.len(), 4, "session/load replay must not be appended");
+    assert_eq!(stored.len(), 6, "session/load replay must not be appended");
     assert_eq!(
         stored.iter().map(event_text).collect::<Vec<_>>(),
-        ["hello from fake", "tick 1", "hello after load", "tick 1"]
+        [
+            "hello from fake",
+            "tick 1",
+            "The daemon restarted. Continue where you left off.",
+            "hello after load",
+            "completed",
+            "tick 1",
+        ]
     );
 
     revived.kill(session.id, false).await.expect("kill");
@@ -621,7 +740,7 @@ async fn shutdown_preserves_a_pristine_structured_worktree_for_recovery() {
         .create(CreateSessionRequest {
             view: SessionView::Structured,
             cwd: repo.path().to_path_buf(),
-            command: "claude".into(),
+            command: "codex".into(),
             env: fake.env(),
             metadata: HashMap::new(),
             worktree: Some(WorktreeSpec {
@@ -629,10 +748,12 @@ async fn shutdown_preserves_a_pristine_structured_worktree_for_recovery() {
                 branch: branch.into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .expect("create");
     assert_eq!(session.cwd, worktree);
+    wait_for_ready(&fx.manager, session.id).await;
     push_all_to_origin(repo.path(), origin.path());
 
     fx.manager.shutdown().await;
@@ -681,6 +802,7 @@ async fn failed_recovery_cleans_its_fifo() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let old_pid = fake.pid();
     fx.manager.shutdown().await;
     wait_for_exit(old_pid).await;
@@ -714,28 +836,56 @@ async fn missing_adapter_yields_a_failed_session_naming_the_install_command() {
         empty.path().to_string_lossy().into_owned(),
     )]);
 
-    let session = fx
+    let created = fx
         .manager
-        .create(structured(cwd.path(), env))
+        .create(structured_command(cwd.path(), env, "codex"))
         .await
-        .expect("a failed session, not an error");
+        .expect("create registers a Starting session");
+    assert_eq!(created.activity, ActivityState::Starting);
 
+    // The background handshake fails because the adapter binary is missing.
+    let session = wait_for_ready(&fx.manager, created.id).await;
     assert_eq!(session.status, SessionStatus::Dead);
     assert_eq!(session.activity, ActivityState::Error);
     let detail = session.activity_detail.clone().expect("actionable detail");
-    assert!(detail.contains(ADAPTER_BIN), "{detail}");
-    assert!(detail.contains(INSTALL_COMMAND), "{detail}");
+    assert!(detail.contains(AcpAdapter::Codex.binary()), "{detail}");
+    assert!(
+        detail.contains(AcpAdapter::Codex.install_command()),
+        "{detail}"
+    );
     assert_eq!(session.acp_session_id, None);
 
     // It is a real session: listed, on disk, and dismissable like any other
     // dead one.
-    assert!(fx.manager.has(session.id).await);
+    assert!(fx.manager.has(created.id).await);
     assert!(fx
         .sidecar_dir()
-        .join(format!("{}.json", session.id))
+        .join(format!("{}.json", created.id))
         .exists());
-    fx.manager.kill(session.id, false).await.expect("dismiss");
-    assert!(!fx.manager.has(session.id).await);
+    fx.manager.kill(created.id, false).await.expect("dismiss");
+    assert!(!fx.manager.has(created.id).await);
+}
+
+#[tokio::test]
+async fn unsupported_structured_command_fails_without_launching_claude() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let cwd = TempDir::new().unwrap();
+
+    let err = fx
+        .manager
+        .create(structured_command(cwd.path(), fake.env(), "opencode"))
+        .await
+        .expect_err("unsupported command is rejected at request validation");
+
+    assert!(
+        matches!(err, maestro_daemon::SessionError::BadRequest(ref msg) if msg.contains("Claude Code or Codex")),
+        "{err:?}"
+    );
+    assert!(
+        fake.log().is_empty(),
+        "unsupported command launched an adapter"
+    );
 }
 
 #[tokio::test]
@@ -750,6 +900,7 @@ async fn kill_sends_cancel_then_sigterm_and_removes_the_sidecar() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     assert!(pid_alive(pid));
 
@@ -792,6 +943,8 @@ async fn shutdown_reaps_every_adapter_child() {
         .create(structured(cwd.path(), b.env()))
         .await
         .expect("create b");
+    wait_for_ready(&fx.manager, sa.id).await;
+    wait_for_ready(&fx.manager, sb.id).await;
     let (pa, pb) = (a.pid(), b.pid());
     assert!(pid_alive(pa) && pid_alive(pb));
 
@@ -826,10 +979,13 @@ async fn dismissal_during_shutdown_does_not_restore_recovery_artifacts() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
-    fx.manager
+    let blocker_session = fx
+        .manager
         .create(structured(cwd.path(), blocker.env()))
         .await
         .expect("create blocker");
+    wait_for_ready(&fx.manager, session.id).await;
+    wait_for_ready(&fx.manager, blocker_session.id).await;
 
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
@@ -881,6 +1037,7 @@ async fn shutdown_does_not_recover_an_adapter_that_already_exited() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_exit(fake.pid()).await;
 
     fx.manager.shutdown().await;
@@ -914,23 +1071,31 @@ async fn shutdown_waits_for_structured_creation_and_rejects_new_creates() {
     let mut env = fake.env();
     env.insert("FAKE_ACP_DELAY_SESSION_NEW_MS".into(), "500".into());
 
-    let create_cwd = cwd.path().to_path_buf();
-    let manager = fx.manager.clone();
-    let create = tokio::spawn(async move { manager.create(structured(&create_cwd, env)).await });
+    // create() returns immediately; the handshake runs in the background
+    // and holds a lifecycle permit.
+    let session = fx
+        .manager
+        .create(structured(cwd.path(), env))
+        .await
+        .expect("create");
+
+    // Wait until the adapter has received session/new (handshake in progress).
     wait_for_async(Duration::from_secs(5), || async {
         fake.log().contains("recv session/new")
     })
     .await;
 
+    // Shutdown must wait for the in-flight background handshake.
     let manager = fx.manager.clone();
     let shutdown = tokio::spawn(async move { manager.shutdown().await });
     tokio::time::sleep(Duration::from_millis(50)).await;
     assert!(
         !shutdown.is_finished(),
-        "shutdown returned before create finished"
+        "shutdown returned before handshake finished"
     );
 
-    let session = create.await.expect("create task").expect("create");
+    // The handshake completes in the background (500ms delay).
+    wait_for_ready(&fx.manager, session.id).await;
     let pid = fake.pid();
     shutdown.await.expect("shutdown task");
 
@@ -950,6 +1115,194 @@ async fn shutdown_waits_for_structured_creation_and_rejects_new_creates() {
     assert_eq!(fake.log().matches("signal SIGTERM").count(), 1);
 }
 
+#[tokio::test]
+async fn structured_handshakes_run_independently() {
+    let fx = DaemonFixture::new();
+    let blocked = Fake::new();
+    let ready = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let gate = cwd.path().join("release-first");
+    let mut blocked_env = blocked.env();
+    blocked_env.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate.to_string_lossy().into_owned(),
+    );
+
+    // Both create() calls return immediately with Starting; the first
+    // adapter's handshake is gated while the second runs freely.
+    let first = fx
+        .manager
+        .create(structured(cwd.path(), blocked_env))
+        .await
+        .expect("first create");
+    let second = fx
+        .manager
+        .create(structured(cwd.path(), ready.env()))
+        .await
+        .expect("second create");
+
+    // The second handshake completes independently of the first.
+    let second_ready = wait_for_ready(&fx.manager, second.id).await;
+    assert_eq!(second_ready.activity, ActivityState::Idle);
+
+    // The first handshake is still blocked.
+    let first_snap = fx
+        .manager
+        .snapshot()
+        .await
+        .into_iter()
+        .find(|s| s.id == first.id)
+        .unwrap();
+    assert_eq!(first_snap.activity, ActivityState::Starting);
+
+    std::fs::write(&gate, b"release").unwrap();
+    let first_ready = wait_for_ready(&fx.manager, first.id).await;
+    assert_eq!(first_ready.activity, ActivityState::Idle);
+
+    fx.manager.kill(first.id, false).await.expect("kill first");
+    fx.manager
+        .kill(second.id, false)
+        .await
+        .expect("kill second");
+}
+
+#[tokio::test]
+async fn shutdown_waits_for_every_admitted_structured_create() {
+    let fx = DaemonFixture::new();
+    let a = Fake::new();
+    let b = Fake::new();
+    let late = Fake::new();
+    let cwd = TempDir::new().unwrap();
+    let gate_a = cwd.path().join("release-a");
+    let gate_b = cwd.path().join("release-b");
+    let mut env_a = a.env();
+    let mut env_b = b.env();
+    env_a.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate_a.to_string_lossy().into_owned(),
+    );
+    env_b.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate_b.to_string_lossy().into_owned(),
+    );
+
+    // Both create() calls return immediately; the background handshake
+    // tasks hold lifecycle permits and are blocked on their gates.
+    let session_a = fx
+        .manager
+        .create(structured(cwd.path(), env_a))
+        .await
+        .expect("create a");
+    let session_b = fx
+        .manager
+        .create(structured(cwd.path(), env_b))
+        .await
+        .expect("create b");
+    wait_for_async(Duration::from_secs(5), || async {
+        a.log().contains("recv session/new") && b.log().contains("recv session/new")
+    })
+    .await;
+
+    let shutdown = {
+        let manager = fx.manager.clone();
+        tokio::spawn(async move { manager.shutdown().await })
+    };
+    wait_for_async(Duration::from_secs(5), || async {
+        matches!(
+            fx.manager.create(structured(cwd.path(), late.env())).await,
+            Err(maestro_daemon::SessionError::ShuttingDown)
+        )
+    })
+    .await;
+    assert!(!shutdown.is_finished());
+
+    std::fs::write(&gate_a, b"release").unwrap();
+    wait_for_ready(&fx.manager, session_a.id).await;
+    assert!(
+        !shutdown.is_finished(),
+        "shutdown ignored the second create"
+    );
+
+    std::fs::write(&gate_b, b"release").unwrap();
+    wait_for_ready(&fx.manager, session_b.id).await;
+    shutdown.await.expect("shutdown task");
+
+    wait_for_exit(a.pid()).await;
+    wait_for_exit(b.pid()).await;
+    assert_eq!(
+        fx.manager.status(session_a.id).await,
+        Some(SessionStatus::Dead)
+    );
+    assert_eq!(
+        fx.manager.status(session_b.id).await,
+        Some(SessionStatus::Dead)
+    );
+}
+
+#[tokio::test]
+async fn killing_a_starting_session_rolls_back_and_settles_admission() {
+    let fx = DaemonFixture::new();
+    let fake = Fake::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let gate = repo.path().join("release-create");
+    let mut env = fake.env();
+    env.insert("FAKE_ACP_ECHO_ENV".into(), "MAESTRO_SESSION_ID".into());
+    env.insert(
+        "FAKE_ACP_SESSION_NEW_GATE".into(),
+        gate.to_string_lossy().into_owned(),
+    );
+    let request = CreateSessionRequest {
+        view: SessionView::Structured,
+        cwd: repo.path().to_path_buf(),
+        command: "claude".into(),
+        env,
+        metadata: HashMap::new(),
+        worktree: Some(WorktreeSpec {
+            base_repo: repo.path().to_path_buf(),
+            branch: "cancelled-create".into(),
+            create_branch: true,
+        }),
+        auto_approve: false,
+    };
+
+    // create() returns immediately with Starting; the handshake is gated.
+    let session = fx.manager.create(request).await.expect("create");
+    assert_eq!(session.activity, ActivityState::Starting);
+    wait_for_async(Duration::from_secs(5), || async {
+        fake.log().contains("recv session/new")
+    })
+    .await;
+    let pid = fake.pid();
+
+    // Kill the session while its handshake is still in progress.
+    // force=true because the worktree has an unpushed branch commit.
+    fx.manager.kill(session.id, true).await.expect("kill");
+
+    // Release the gate so the background task can finish and settle.
+    std::fs::write(&gate, b"release").unwrap();
+
+    // Shutdown must not hang — the lifecycle permit is settled.
+    tokio::time::timeout(Duration::from_secs(5), fx.manager.shutdown())
+        .await
+        .expect("shutdown hung on a settled permit");
+
+    wait_for_exit(pid).await;
+    assert!(fx.manager.snapshot().await.is_empty());
+    let id = session.id.to_string();
+    assert!(
+        std::fs::read_dir(fx.sidecar_dir())
+            .into_iter()
+            .flatten()
+            .all(|entry| !entry
+                .unwrap()
+                .file_name()
+                .to_string_lossy()
+                .starts_with(&id)),
+        "killed Starting session left a sidecar artifact"
+    );
+}
+
 #[tokio::test]
 async fn shutdown_drains_final_notifications_to_the_log() {
     let fx = DaemonFixture::new();
@@ -963,6 +1316,7 @@ async fn shutdown_drains_final_notifications_to_the_log() {
         .create(structured(cwd.path(), env))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     wait_for_async(Duration::from_secs(5), || async {
         fx.manager
             .read_acp_events(session.id, EventCursor::Since(0), 10)
@@ -993,6 +1347,7 @@ async fn adapter_exit_marks_the_session_dead_and_keeps_it_listed() {
         .create(structured(cwd.path(), fake.env()))
         .await
         .expect("create");
+    wait_for_ready(&fx.manager, session.id).await;
     fx.manager.start_liveness_watcher(Duration::from_millis(50));
 
     // The agent dies out from under the daemon: the liveness pass, not tmux,

crates/maestro-daemon/tests/activity_report.rs

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

crates/maestro-daemon/tests/attach.rs

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

crates/maestro-daemon/tests/autoname.rs

@@ -11,14 +11,14 @@ use common::TmuxFixture;
 use maestro_daemon::sidecar::SidecarStore;
 use maestro_daemon::worktree::WorktreeManager;
 use maestro_daemon::SessionManager;
-use maestro_protocol::{display, CatalogEvent, CreateSessionRequest, NameSource};
+use maestro_protocol::{display, CatalogEvent, CreateSessionRequest, NameSource, SessionStatus};
 use tempfile::TempDir;
 use uuid::Uuid;
 
 struct Fixture {
     manager: SessionManager,
     sidecar: SidecarStore,
-    _tmux: TmuxFixture,
+    tmux: TmuxFixture,
     _state_dir: TempDir,
 }
 
@@ -35,7 +35,7 @@ fn fixture() -> Fixture {
     Fixture {
         manager,
         sidecar,
-        _tmux: tmux,
+        tmux,
         _state_dir: state_dir,
     }
 }
@@ -56,6 +56,7 @@ async fn spawn(manager: &SessionManager, name: Option<&str>) -> Uuid {
             env: Default::default(),
             metadata,
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
@@ -170,3 +171,37 @@ async fn a_blank_name_changes_nothing() {
     let live = fx.sidecar.read(id).unwrap().unwrap();
     assert_eq!(display::name_source(&live), NameSource::Generated);
 }
+
+/// A session that dies naturally (liveness watcher marks it dead) must not
+/// overwrite a haiku rename that landed before the death. Regression test for
+/// the stale-clone sidecar write in `mark_session_dead`.
+#[tokio::test]
+async fn session_death_preserves_the_haiku_name() {
+    let fx = fixture();
+    let id = spawn(&fx.manager, None).await;
+
+    fx.manager.claim_autoname(id).await.unwrap();
+    fx.manager.apply_autoname(id, "haiku-name").await.unwrap();
+
+    // Verify the sidecar has Haiku before the session dies.
+    let before = fx.sidecar.read(id).unwrap().unwrap();
+    assert_eq!(display::name_source(&before), NameSource::Haiku);
+
+    // Kill the tmux session directly so the liveness watcher picks it up.
+    fx.tmux.tmux.kill_session(id).expect("kill tmux directly");
+    fx.manager
+        .start_liveness_watcher(std::time::Duration::from_millis(25));
+
+    common::wait_for_async(std::time::Duration::from_secs(3), || async {
+        fx.manager.status(id).await == Some(SessionStatus::Dead)
+    })
+    .await;
+
+    let after = fx.sidecar.read(id).unwrap().unwrap();
+    assert_eq!(
+        display::name_source(&after),
+        NameSource::Haiku,
+        "mark_session_dead must not overwrite a haiku rename in the sidecar"
+    );
+    assert_eq!(display::custom_name(&after), Some("haiku-name"));
+}

crates/maestro-daemon/tests/blocked_work_cost.rs

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

crates/maestro-daemon/tests/embedded_bundle.rs

@@ -13,14 +13,14 @@ async fn embedded_index_is_real_spa_not_placeholder() {
     let html = String::from_utf8(body.to_vec()).unwrap();
 
     assert!(
-        html.contains(r#"id="app""#),
+        html.contains(r#"id="root""#),
         "served index is missing the SPA mount point; got:\n{html}"
     );
     assert!(
         !html.contains("maestro is running"),
         "served index is the placeholder, not the built bundle"
     );
-    // Stronger signal than `id="app"` (which appears in both source and built
+    // Stronger signal than `id="root"` (which appears in both source and built
     // HTML): the vite build rewrites the entry to a hashed `/assets/index-<hash>`
     // bundle, whereas the un-built source references `/src/main.ts`. This catches
     // both an empty/placeholder embed and the staleness case.

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

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

crates/maestro-daemon/tests/local_api.rs

@@ -154,7 +154,8 @@ async fn structured_session(h: &Harness, fake: &FakeAcp) -> Uuid {
 }
 
 async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>) -> Uuid {
-    h.manager
+    let id = h
+        .manager
         .create(CreateSessionRequest {
             view: SessionView::Structured,
             cwd: "/tmp".into(),
@@ -162,10 +163,13 @@ async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>)
             env,
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
-        .id
+        .id;
+    wait_for_session_activity(h, id, ActivityState::Idle).await;
+    id
 }
 
 async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
@@ -235,7 +239,61 @@ async fn structured_ws_sends_snapshot_then_live_projection() {
 }
 
 #[tokio::test]
-async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it() {
+async fn structured_attachments_preserve_bytes_and_reject_paths() {
+    let h = spawn("attachments").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+    let client = reqwest::Client::new();
+    let endpoint = url(
+        h.addr,
+        &format!("/api/sessions/{id}/structured/attachments"),
+    );
+    let bytes = vec![0, 255, 10, 13];
+    let response = client
+        .post(&endpoint)
+        .query(&[("name", "sample.bin")])
+        .body(bytes.clone())
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 200);
+    let body: serde_json::Value = response.json().await.unwrap();
+    let path = body["path"].as_str().unwrap();
+    assert!(Path::new(path).is_absolute());
+    assert_eq!(std::fs::read(path).unwrap(), bytes);
+    for name in ["../escape", "a/b", "a\\b", "..", ""] {
+        let response = client
+            .post(&endpoint)
+            .query(&[("name", name)])
+            .body("text")
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(response.status(), 400, "{name}");
+    }
+    let response = client
+        .post(&endpoint)
+        .query(&[("name", "large.bin")])
+        .body(vec![0; 20 * 1024 * 1024 + 1])
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 413);
+    let response = client
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{}/structured/attachments", Uuid::new_v4()),
+        ))
+        .query(&[("name", "file.txt")])
+        .body("text")
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), 404);
+}
+
+#[tokio::test]
+async fn structured_prompt_queues_during_active_turn_and_cancel_clears_it() {
     let h = spawn("naps-laptop").await;
     let fake = FakeAcp::new();
     let mut env = fake.env();
@@ -252,6 +310,7 @@ async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it(
         .await
         .unwrap();
     assert_eq!(first.status(), reqwest::StatusCode::NO_CONTENT);
+    // A second prompt while a turn is active is accepted into the queue.
     let second = client
         .post(url(
             h.addr,
@@ -261,9 +320,7 @@ async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it(
         .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");
+    assert_eq!(second.status(), reqwest::StatusCode::ACCEPTED);
 
     let cancel = client
         .post(url(
@@ -274,16 +331,8 @@ async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it(
         .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);
+    // After cancel + settlement, the queued "second" prompt drains. Wait for
+    // both the first and the drained prompt to reach ACP.
     tokio::time::timeout(Duration::from_secs(2), async {
         loop {
             if fake.log().matches("recv session/prompt").count() == 2 {
@@ -293,7 +342,7 @@ async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it(
         }
     })
     .await
-    .expect("both prompt commands reach ACP");
+    .expect("first and drained queued prompt both reach ACP");
     let log = fake.log();
     let first_prompt = log.find("recv session/prompt").unwrap();
     let cancel = log.find("recv session/cancel").unwrap();
@@ -493,6 +542,7 @@ async fn structured_prompt_rejects_unknown_and_unavailable_sessions() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -626,6 +676,7 @@ async fn structured_replay_rejects_unknown_terminal_and_dead_sessions() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -768,6 +819,7 @@ async fn list_sessions_starts_empty_and_reflects_creates() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     };
     let created: Session = reqwest::Client::new()
         .post(url(h.addr, "/api/sessions"))
@@ -942,7 +994,9 @@ async fn names_honors_count_and_caps_it() {
 #[tokio::test]
 async fn gitroot_probes_path() {
     // #26: resolves the query against the daemon home dir and walks up for a
-    // `.git`. A `/tmp`-rooted temp dir is not in a repo, so the root is null.
+    // `.git`. The tempdir itself has no `.git`, so the result must either be
+    // null (no repo anywhere above) or — in sandboxed environments where /tmp
+    // itself sits inside a repo — a path strictly above the tempdir.
     let h = spawn("naps-laptop").await;
     let tmp = tempfile::tempdir().unwrap();
     let resp: serde_json::Value = reqwest::get(url(
@@ -957,7 +1011,16 @@ async fn gitroot_probes_path() {
     .json()
     .await
     .unwrap();
-    assert!(resp.get("root").is_none() || resp["root"].is_null());
+    // On hosts where an ancestor of the temp dir is a repo (e.g. `/tmp`
+    // inside a checkout), the root legitimately points there. The test only
+    // asserts no root was found *inside* the temp dir.
+    match resp.get("root").and_then(|v| v.as_str()) {
+        None => {}
+        Some(root) => assert!(
+            !root.starts_with(tmp.path().to_string_lossy().as_ref()),
+            "found a repo root inside the fixture at {root:?}"
+        ),
+    }
 }
 
 #[tokio::test]
@@ -985,6 +1048,7 @@ async fn patch_session_renames_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1028,6 +1092,7 @@ async fn post_focus_stamps_last_focused_at() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1062,6 +1127,7 @@ async fn delete_owned_session_kills_it() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1084,6 +1150,7 @@ async fn spawn_via_manager(h: &Harness) -> Uuid {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap()
@@ -1198,6 +1265,7 @@ async fn delete_a_session_whose_worktree_holds_unsaved_work_returns_409_with_the
                 branch: "feat/guarded".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1251,6 +1319,7 @@ async fn delete_with_force_ends_the_session_and_keeps_the_worktree() {
                 branch: "feat/guarded".into(),
                 create_branch: true,
             }),
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1281,6 +1350,7 @@ async fn attach_ws_streams_pty_bytes() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .unwrap();
@@ -1311,6 +1381,39 @@ async fn attach_ws_streams_pty_bytes() {
     assert!(saw_hello, "PTY did not echo through the attach WS");
 }
 
+#[tokio::test]
+async fn pty_routes_reject_structured_sessions_as_not_terminal() {
+    let h = spawn("naps-laptop").await;
+    let fake = FakeAcp::new();
+    let id = structured_session(&h, &fake).await;
+
+    let response = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/input")))
+        .json(&maestro_protocol::SendInputRequest {
+            text: "ignored".into(),
+            submit: false,
+        })
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let error: ApiError = response.json().await.unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+
+    let error = connect_async(ws_url(h.addr, &format!("/api/attach/{id}")))
+        .await
+        .expect_err("structured session must not upgrade to a PTY socket");
+    let tokio_tungstenite::tungstenite::Error::Http(response) = error else {
+        panic!("expected an HTTP handshake rejection, got {error}");
+    };
+    assert_eq!(response.status(), reqwest::StatusCode::CONFLICT);
+    let body = response.body().as_deref().expect("ApiError response body");
+    let error: ApiError = serde_json::from_slice(body).unwrap();
+    assert_eq!(error.error.code, "not_terminal");
+    assert_eq!(error.error.message, "session is not a terminal session");
+}
+
 #[tokio::test]
 async fn attach_ws_for_unknown_session_returns_404() {
     let h = spawn("naps-laptop").await;
@@ -1350,6 +1453,7 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");
@@ -1395,6 +1499,12 @@ async fn events_ws_streams_structured_activity_without_hook_overrides() {
     let maestro_protocol::CatalogEvent::SessionAdded { session } = next_event(&mut ws).await else {
         panic!("expected structured SessionAdded")
     };
+    assert_eq!(session.activity, ActivityState::Starting);
+    // The background handshake completes and sends SessionUpdated → Idle.
+    let maestro_protocol::CatalogEvent::SessionUpdated { session } = next_event(&mut ws).await
+    else {
+        panic!("expected SessionUpdated after handshake")
+    };
     assert_eq!(session.activity, ActivityState::Idle);
 
     let client = reqwest::Client::new();
@@ -1462,6 +1572,7 @@ async fn every_events_subscriber_gets_its_own_snapshot() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("create");

crates/maestro-daemon/tests/rename.rs

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

crates/maestro-daemon/tests/session_decisions.rs

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

crates/maestro-daemon/tests/session_manager.rs

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

crates/maestro-daemon/tests/sidecar.rs

@@ -34,6 +34,8 @@ fn sample(id: Uuid) -> Session {
         last_focused_at: None,
         acp_session_id: None,
         view: SessionView::Terminal,
+        auto_approve: false,
+        queued_prompts: Vec::new(),
     }
 }
 

crates/maestro-daemon/tests/web_ui.rs

@@ -59,7 +59,7 @@ async fn root_serves_the_spa_shell() {
             .map(|v| v.starts_with("text/html")),
         Some(true)
     );
-    assert!(resp.text().await.unwrap().contains(r#"id="app""#));
+    assert!(resp.text().await.unwrap().contains(r#"id="root""#));
 }
 
 #[tokio::test]
@@ -69,7 +69,7 @@ async fn client_side_route_falls_back_to_the_shell() {
         .await
         .unwrap();
     assert_eq!(resp.status(), 200);
-    assert!(resp.text().await.unwrap().contains(r#"id="app""#));
+    assert!(resp.text().await.unwrap().contains(r#"id="root""#));
 }
 
 /// An unmatched API path must 404 rather than fall through to the SPA shell:

crates/maestro-daemon/tests/worktree.rs

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

crates/maestro-e2e/tests/e2e.rs

@@ -33,6 +33,7 @@ fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: None,
+        auto_approve: false,
     }
 }
 
@@ -111,6 +112,7 @@ fn worktree_req(base: &std::path::Path, branch: &str, create_branch: bool) -> Cr
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base, branch, create_branch)),
+        auto_approve: false,
     }
 }
 
@@ -206,6 +208,7 @@ async fn kill_removes_clean_worktree() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/e2e", true)),
+        auto_approve: false,
     };
 
     let s = client.spawn_session(&req).await.expect("spawn worktree");
@@ -260,6 +263,7 @@ async fn kill_refuses_worktree_with_uncommitted_changes() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/unsaved", true)),
+        auto_approve: false,
     };
 
     let s = client.spawn_session(&req).await.expect("spawn worktree");
@@ -319,6 +323,7 @@ async fn spawn_on_existing_branch_checks_it_out() {
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(base.path(), "feature/existing", false)),
+        auto_approve: false,
     };
 
     let s = client
@@ -383,13 +388,11 @@ async fn spawn_new_branch_creates_worktree_and_runs_in_it() {
     client.kill_session(s.id).await.expect("kill");
 }
 
-/// #66: a second spawn onto an *existing* branch that already has a worktree
-/// is rejected with a structured worktree error; the first worktree stays
-/// intact. (A second `create_branch: true` spawn is a different case: 49ab7e9
-/// suffixes the new branch name instead, see
-/// `colliding_branch_name_gets_suffixed_too`.)
+/// #66/#77: a second spawn onto the same branch used to be rejected outright;
+/// since the branch-collision suffixing landed, it succeeds instead — the
+/// second worktree lands on `<branch>-2` and the first stays untouched.
 #[tokio::test(flavor = "multi_thread")]
-async fn second_spawn_on_same_branch_is_rejected() {
+async fn second_spawn_on_same_branch_gets_suffixed() {
     let (_daemon, client) = bring_up().await;
 
     let base = TempDir::new().unwrap();
@@ -399,28 +402,33 @@ async fn second_spawn_on_same_branch_is_rejected() {
         .spawn_session(&worktree_req(base.path(), "feature/dup", true))
         .await
         .expect("first spawn");
-    let dup = client
-        .spawn_session(&worktree_req(base.path(), "feature/dup", false))
-        .await;
-    match dup {
-        Err(maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. })) => {
-            assert_eq!(
-                info.code, "worktree_failed",
-                "expected worktree error: {info:?}"
-            );
-        }
-        other => panic!("expected rejection for duplicate branch, got {other:?}"),
-    }
+    let second = client
+        .spawn_session(&worktree_req(base.path(), "feature/dup", true))
+        .await
+        .expect("second spawn suffixes instead of rejecting");
 
-    // Exactly one registration, one directory, still usable.
-    // Count branch records only: the worktree path now contains the branch
-    // name too (`worktrees/feature/dup`), so a substring match over every line
-    // would count the same tree twice.
-    let holders = git_worktree_list(base.path())
-        .iter()
-        .filter(|w| w.as_str() == "branch refs/heads/feature/dup")
-        .count();
-    assert_eq!(holders, 1, "duplicate spawn must not register another tree");
+    let suffixed = base.path().join("worktrees").join("feature").join("dup-2");
+    assert_eq!(
+        second.cwd, suffixed,
+        "second worktree must land on the suffixed path"
+    );
+    assert!(suffixed.is_dir());
+
+    // Both registrations exist: the original branch, untouched, and the
+    // suffixed one the second spawn created.
+    let registrations = git_worktree_list(base.path());
+    assert!(
+        registrations
+            .iter()
+            .any(|l| l.as_str() == "branch refs/heads/feature/dup"),
+        "original branch must stay registered: {registrations:?}"
+    );
+    assert!(
+        registrations
+            .iter()
+            .any(|l| l.as_str() == "branch refs/heads/feature/dup-2"),
+        "suffixed branch must be registered too: {registrations:?}"
+    );
     assert!(
         base.path()
             .join("worktrees")
@@ -431,7 +439,8 @@ async fn second_spawn_on_same_branch_is_rejected() {
     );
 
     let _origin = throwaway_origin(base.path());
-    client.kill_session(first.id).await.expect("kill");
+    client.kill_session(first.id).await.expect("kill first");
+    client.kill_session(second.id).await.expect("kill second");
 }
 
 /// #66/#56: when the client picks a *linked worktree* as base_repo, placement
@@ -768,7 +777,7 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
         other => panic!("expected a kill_guarded refusal, got {other:?}"),
     }
 
-    // Force overrides the refusal and nothing else: session gone, tree kept.
+    // Force overrides the refusal: session gone, tree removed.
     client.kill_session_forced(s.id).await.expect("forced kill");
 
     assert!(
@@ -780,12 +789,12 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
             .any(|x| x.id == s.id),
         "the forced kill ends the session"
     );
-    assert!(wt.is_dir(), "a guarded worktree must stay on disk");
+    assert!(!wt.is_dir(), "a forced kill removes the worktree");
     assert!(
-        git_worktree_list(base.path())
+        !git_worktree_list(base.path())
             .iter()
             .any(|l| l.contains("feature/local")),
-        "the kept tree stays registered in git"
+        "the removed tree is unregistered from git"
     );
 }
 
@@ -823,6 +832,7 @@ async fn natural_exit_settles_dirty_and_pristine_worktrees_differently() {
             env: HashMap::new(),
             metadata: HashMap::new(),
             worktree: Some(worktree_spec(dirty_repo.path(), "feature/messy", true)),
+            auto_approve: false,
         })
         .await
         .expect("spawn dirty");
@@ -872,6 +882,7 @@ fn create_req_cmd(cwd: &std::path::Path, command: &str, branch: &str) -> CreateS
         env: HashMap::new(),
         metadata: HashMap::new(),
         worktree: Some(worktree_spec(cwd, branch, true)),
+        auto_approve: false,
     }
 }
 
@@ -1064,6 +1075,7 @@ async fn sigterm_stops_structured_child_before_events_ws_drains() {
             env: fake.env.clone(),
             metadata: HashMap::new(),
             worktree: None,
+            auto_approve: false,
         })
         .await
         .expect("spawn structured session");

crates/maestro-protocol/src/display.rs

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

crates/maestro-protocol/src/lib.rs

@@ -123,7 +123,7 @@ pub struct Session {
     /// daemon that predates the field keeps working untouched.
     #[serde(default)]
     pub view: SessionView,
-    /// The ACP session id the `claude-code-acp` adapter handed back from
+    /// The ACP session id the selected provider adapter handed back from
     /// `session/new` (#134). Only a [`SessionView::Structured`] session has
     /// one, and only once its handshake succeeded; a later respawn passes it
     /// to `session/load` so the conversation continues (#135). Distinct from
@@ -132,6 +132,16 @@ pub struct Session {
     /// the two are minted by different processes with different lifetimes.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub acp_session_id: Option<String>,
+    /// When `true` the daemon auto-approves every ACP permission request for
+    /// this session instead of surfacing them to the client. Set at spawn time
+    /// from the preset or the `CreateSessionRequest`; persisted so it survives
+    /// a daemon restart.
+    #[serde(default)]
+    pub auto_approve: bool,
+    /// Prompts queued on the daemon while a turn was in flight or the adapter
+    /// was still booting. Persisted so the queue survives a daemon restart.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub queued_prompts: Vec<String>,
 }
 
 /// A session's process shape (#133): a plain terminal, or a structured agent
@@ -175,6 +185,10 @@ pub enum ActivityState {
     AwaitingInput,
     /// An agent reported a failure, or a structured session/turn failed.
     Error,
+    /// The ACP adapter is booting; the session is registered but cannot accept
+    /// prompts yet. Older clients that do not know this variant degrade it to
+    /// `Idle` via the lenient deserializer — acceptable.
+    Starting,
 }
 
 impl<'de> Deserialize<'de> for ActivityState {
@@ -187,6 +201,7 @@ impl<'de> Deserialize<'de> for ActivityState {
             "Active" => Self::Active,
             "AwaitingInput" => Self::AwaitingInput,
             "Error" => Self::Error,
+            "Starting" => Self::Starting,
             // Known or not, any other spelling degrades to the neutral default
             _ => Self::Idle,
         })
@@ -225,9 +240,10 @@ where
         "Idle" => Ok(ActivityState::Idle),
         "AwaitingInput" => Ok(ActivityState::AwaitingInput),
         "Error" => Ok(ActivityState::Error),
+        "Starting" => Ok(ActivityState::Starting),
         other => Err(D::Error::unknown_variant(
             other,
-            &["Active", "Idle", "AwaitingInput", "Error"],
+            &["Active", "Idle", "AwaitingInput", "Error", "Starting"],
         )),
     }
 }
@@ -383,6 +399,10 @@ pub struct CreateSessionRequest {
     /// untouched.
     #[serde(default)]
     pub view: SessionView,
+    /// When `true`, the daemon auto-approves every ACP permission request
+    /// for this structured session.
+    #[serde(default)]
+    pub auto_approve: bool,
 }
 
 /// Result of `GET /api/dirs`: the immediate subdirectories of one directory.
@@ -522,6 +542,11 @@ pub struct SpawnPreset {
     pub id: String,
     pub label: String,
     pub command: String,
+    /// When `true`, the daemon auto-approves every ACP permission request
+    /// for structured sessions spawned from this preset instead of surfacing
+    /// them to the client.
+    #[serde(default)]
+    pub auto_approve: bool,
 }
 
 /// Build provenance of the running daemon: the commit it was compiled
@@ -824,6 +849,15 @@ pub struct TurnState {
     pub thinking: bool,
     #[serde(default)]
     pub active_tool_calls: Vec<String>,
+    /// Wall-clock start of the active prompt. This lets reconnecting clients
+    /// keep one continuous elapsed-time display instead of restarting at zero.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_at: Option<DateTime<Utc>>,
+    /// Context-window usage when the active prompt began. ACP exposes context
+    /// occupancy, not provider billing-token accounting, so clients must label
+    /// deltas as context tokens rather than tokens billed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_context_tokens: Option<u64>,
 }
 
 /// A whole-session view derived from ACP notifications.
@@ -846,6 +880,12 @@ pub struct ReducedState {
     pub model: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config_options: Option<Value>,
+    /// Prompts queued on the daemon while a turn is in flight. Drained as
+    /// a single concatenated prompt when the current turn completes.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub queued_prompts: Vec<String>,
 }
 
 /// Server messages sent over a structured-session WebSocket.
@@ -871,6 +911,13 @@ pub struct StructuredPromptRequest {
     pub prompt: String,
 }
 
+/// HTTP body for `POST /api/sessions/:id/structured/config`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct StructuredConfigRequest {
+    pub config_id: String,
+    pub value: Value,
+}
+
 /// Operator decision for a pending ACP permission request.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -1021,6 +1068,8 @@ mod tests {
             last_focused_at: None,
             view: SessionView::Terminal,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 
@@ -1233,6 +1282,7 @@ mod tests {
                 create_branch: true,
             }),
             view: SessionView::Terminal,
+            auto_approve: false,
         };
         assert_eq!(req, round_trip(&req));
     }

crates/maestro-protocol/src/routes.rs

@@ -86,11 +86,21 @@ pub fn structured_prompt(id: Uuid) -> String {
     format!("{SESSIONS}/{id}/structured/prompt")
 }
 
+/// `POST /api/sessions/:id/structured/attachments` — upload a file.
+pub fn structured_attachment(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/attachments")
+}
+
 /// `POST /api/sessions/:id/structured/cancel` — cancel an ACP turn.
 pub fn structured_cancel(id: Uuid) -> String {
     format!("{SESSIONS}/{id}/structured/cancel")
 }
 
+/// `POST /api/sessions/:id/structured/config` — change an ACP session option.
+pub fn structured_config(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/structured/config")
+}
+
 /// `POST /api/sessions/:id/structured/approvals/:nonce` — answer ACP permission.
 pub fn structured_approval(id: Uuid, nonce: &str) -> String {
     format!("{SESSIONS}/{id}/structured/approvals/{nonce}")
@@ -108,7 +118,9 @@ pub mod patterns {
     pub const STRUCTURED: &str = "/api/structured/:id";
     pub const STRUCTURED_REPLAY: &str = "/api/sessions/:id/structured/replay";
     pub const STRUCTURED_PROMPT: &str = "/api/sessions/:id/structured/prompt";
+    pub const STRUCTURED_ATTACHMENT: &str = "/api/sessions/:id/structured/attachments";
     pub const STRUCTURED_CANCEL: &str = "/api/sessions/:id/structured/cancel";
+    pub const STRUCTURED_CONFIG: &str = "/api/sessions/:id/structured/config";
     pub const STRUCTURED_APPROVAL: &str = "/api/sessions/:id/structured/approvals/:nonce";
 }
 

crates/maestro-testing/src/lib.rs

@@ -22,7 +22,8 @@ use chrono::Utc;
 use futures_util::{SinkExt, StreamExt};
 use maestro_protocol::{
     routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonClient, DaemonInfo, DirListing,
-    GitRoot, RecentDirs, SendInputRequest, Session, SessionStatus, PROTOCOL_VERSION,
+    GitRoot, RecentDirs, SendInputRequest, Session, SessionStatus, StructuredPromptRequest,
+    PROTOCOL_VERSION,
 };
 use tokio::net::TcpListener;
 use tokio::sync::{broadcast, oneshot};
@@ -49,6 +50,8 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
         blocked_work: None,
         last_focused_at: None,
         acp_session_id: None,
+        auto_approve: false,
+        queued_prompts: Vec::new(),
     }
 }
 
@@ -60,6 +63,8 @@ struct Inner {
     forced_error: Option<(u16, ApiError)>,
     /// Everything `POST /api/sessions/:id/input` was asked to type, in order.
     inputs: Vec<(Uuid, SendInputRequest)>,
+    /// Every ACP prompt sent to a structured session, in order.
+    structured_prompts: Vec<(Uuid, StructuredPromptRequest)>,
 }
 
 #[derive(Clone)]
@@ -92,6 +97,7 @@ impl MockDaemon {
             .route(routes::SESSIONS, get(list_sessions).post(create_session))
             .route(routes::patterns::SESSION, delete(kill_session))
             .route(routes::patterns::SESSION_INPUT, post(send_input))
+            .route(routes::patterns::STRUCTURED_PROMPT, post(structured_prompt))
             .route(routes::INFO, get(daemon_info))
             .route(routes::DIRS, get(list_dir))
             .route(routes::RECENT_DIRS, get(recent_dirs))
@@ -178,6 +184,16 @@ impl MockDaemon {
         self.state.inner.lock().expect("poisoned").inputs.clone()
     }
 
+    /// Every ACP prompt this daemon received, oldest first.
+    pub fn structured_prompts(&self) -> Vec<(Uuid, StructuredPromptRequest)> {
+        self.state
+            .inner
+            .lock()
+            .expect("poisoned")
+            .structured_prompts
+            .clone()
+    }
+
     pub fn session_count(&self) -> usize {
         self.state.inner.lock().expect("poisoned").sessions.len()
     }
@@ -266,6 +282,26 @@ async fn send_input(
     StatusCode::NO_CONTENT.into_response()
 }
 
+async fn structured_prompt(
+    State(s): State<AppState>,
+    Path(id): Path<Uuid>,
+    Json(req): Json<StructuredPromptRequest>,
+) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let mut guard = s.inner.lock().expect("poisoned");
+    if !guard.sessions.iter().any(|x| x.id == id) {
+        return (
+            StatusCode::NOT_FOUND,
+            Json(ApiError::new("not_found", "no such session on this daemon")),
+        )
+            .into_response();
+    }
+    guard.structured_prompts.push((id, req));
+    StatusCode::NO_CONTENT.into_response()
+}
+
 async fn daemon_info(State(s): State<AppState>) -> Response {
     if let Some(r) = forced(&s) {
         return r;

crates/maestro-tui/src/app.rs

@@ -11,6 +11,7 @@
 //! `dispatch` / the overlay routing.
 
 use std::collections::{HashMap, HashSet};
+use std::io::Write;
 use std::path::PathBuf;
 use std::time::Duration;
 
@@ -54,6 +55,36 @@ enum OverlayDecision {
     Pass,
 }
 
+fn copy_to_terminal_clipboard(text: &str) -> std::io::Result<()> {
+    let encoded = base64_encode(text.as_bytes());
+    let mut output = std::io::stdout();
+    write!(output, "\x1b]52;c;{encoded}\x07")?;
+    output.flush()
+}
+
+fn base64_encode(bytes: &[u8]) -> String {
+    const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut output = String::with_capacity(bytes.len().div_ceil(3) * 4);
+    for chunk in bytes.chunks(3) {
+        let bits = (u32::from(chunk[0]) << 16)
+            | (u32::from(*chunk.get(1).unwrap_or(&0)) << 8)
+            | u32::from(*chunk.get(2).unwrap_or(&0));
+        output.push(TABLE[((bits >> 18) & 0x3f) as usize] as char);
+        output.push(TABLE[((bits >> 12) & 0x3f) as usize] as char);
+        output.push(if chunk.len() > 1 {
+            TABLE[((bits >> 6) & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+        output.push(if chunk.len() > 2 {
+            TABLE[(bits & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+    }
+    output
+}
+
 pub struct App {
     cfg: TuiConfig,
     home_dir: String,
@@ -340,6 +371,10 @@ impl App {
             return Ok(false);
         }
 
+        if self.handle_structured_mouse(&key) {
+            return Ok(false);
+        }
+
         if let Some(effects) = self.handle_structured_key(&key) {
             self.perform(effects).await;
             return Ok(false);
@@ -423,6 +458,61 @@ impl App {
         true
     }
 
+    /// Transcript blocks are pointer targets: click selects the whole block,
+    /// gives it the selection surface, and copies its complete text.
+    fn handle_structured_mouse(&mut self, key: &InputKey) -> bool {
+        let InputKey::Mouse {
+            kind,
+            region: Region::Pane,
+            row,
+            ..
+        } = key
+        else {
+            return false;
+        };
+        if !matches!(kind, MouseKind::Click | MouseKind::Hover) {
+            return false;
+        }
+        let Some(sid) = self.state.active_session() else {
+            return false;
+        };
+        let Some(handle) = self.structured.get(&sid) else {
+            return false;
+        };
+        let Some(pane) = self.region.pane else {
+            return false;
+        };
+        let offset = usize::from(row.saturating_sub(pane.y));
+        let transcript_height = pane.height.saturating_sub(pane.height.min(3));
+        if offset >= usize::from(transcript_height) {
+            return true;
+        }
+        let mut state = handle.state.lock().expect("structured state mutex");
+        let rendered_line = state.scroll.saturating_add(offset);
+        if !state.select_rendered_line(rendered_line) {
+            return true;
+        }
+        let Some(id) = state.selected.as_deref() else {
+            return true;
+        };
+        let Some(transcript) = state.rows.iter().find(|item| item.id == id) else {
+            return true;
+        };
+        if *kind == MouseKind::Hover {
+            return true;
+        }
+        let text = crate::structured_pane::copy_text(transcript);
+        drop(state);
+        if text.is_empty() {
+            return true;
+        }
+        match copy_to_terminal_clipboard(&text) {
+            Ok(()) => self.state.toast("copied transcript block"),
+            Err(error) => self.state.toast(format!("copy failed: {error}")),
+        }
+        true
+    }
+
     /// Carry out what `dispatch` decided. The only place in `App` that talks to
     /// the daemon.
     async fn perform(&mut self, effects: Vec<Effect>) {
@@ -1905,6 +1995,12 @@ async fn fetch_branches(
 #[cfg(test)]
 mod tests {
     use super::*;
+
+    #[test]
+    fn clipboard_payload_uses_standard_base64() {
+        assert_eq!(base64_encode(b"hello"), "aGVsbG8=");
+        assert_eq!(base64_encode("✓".as_bytes()), "4pyT");
+    }
     use crate::action::Action;
     use crate::draft::DraftField;
     use crate::keymap::Mode;
@@ -2120,6 +2216,8 @@ mod tests {
                     blocked_work: None,
                     last_focused_at: None,
                     acp_session_id: None,
+                    auto_approve: false,
+                    queued_prompts: Vec::new(),
                 })
                 .collect(),
         });
@@ -2303,6 +2401,8 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
+                queued_prompts: Vec::new(),
             }],
         });
         app.dispatch(Action::SidebarNext);
@@ -2332,6 +2432,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 
@@ -3009,6 +3111,7 @@ mod tests {
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         };
         app.submit_spawn(req).await;
 
@@ -3053,17 +3156,20 @@ mod tests {
         let request = |view| CreateSessionRequest {
             view,
             cwd: std::path::PathBuf::from("/srv/work"),
-            command: "claude".into(),
+            command: "codex".into(),
             env: Default::default(),
             metadata: Default::default(),
             worktree: None,
+            auto_approve: false,
         };
 
         let structured_id = Uuid::from_u128(188);
+        app.state.mode = Mode::Insert;
         app.submit_spawn(request(SessionView::Structured)).await;
         assert!(app.catalog.snapshot().sessions.is_empty());
         assert!(app.structured.contains_key(&structured_id));
         assert!(app.emulators.get(structured_id).is_none());
+        assert_eq!(app.state.mode, Mode::Normal);
 
         let terminal_id = Uuid::from_u128(187);
         app.submit_spawn(request(SessionView::Terminal)).await;
@@ -3490,6 +3596,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: focused,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         };
         let older = Utc::now() - chrono::Duration::seconds(60);
         app.catalog.apply_event(CatalogEvent::Snapshot {
@@ -3770,6 +3878,8 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
+                queued_prompts: Vec::new(),
             }],
         });
         app.dispatch(Action::KillHighlighted);
@@ -3807,6 +3917,8 @@ mod tests {
                 blocked_work: None,
                 last_focused_at: None,
                 acp_session_id: None,
+                auto_approve: false,
+                queued_prompts: Vec::new(),
             }],
         });
     }

crates/maestro-tui/src/catalog.rs

@@ -225,6 +225,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }