feat(maestro): wire DaemonLink into MainActivity, allow cleartext traffic

Reads the EXTRA_DAEMON_URL intent extra, starts DaemonLink, and shows its
LinkState in the placeholder screen so the connection indicator has
something to bind to. usesCleartextTraffic is required for the daemon's
plain-HTTP LAN endpoint; ACCESS_NETWORK_STATE is required for
ConnectivityManager.registerNetworkCallback.

.claude/settings.local.json

@@ -1,18 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git fetch:*)",
-      "Bash(git merge:*)",
-      "Bash(npx tsc:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm install:*)",
-      "Bash(./node_modules/.bin/tsc:*)",
-      "Bash(npm test:*)",
-      "Bash(cargo check:*)",
-      "Bash(cargo clippy:*)",
-      "Bash(cargo test:*)"
-    ]
-  }
-}

.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

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,82 @@
+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.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+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 pt.naps.maestro.connection.DaemonLink
+import pt.naps.maestro.connection.DaemonPrefs
+import pt.naps.maestro.connection.LinkState
+import pt.naps.maestro.ui.theme.MaestroTheme
+
+class MainActivity : ComponentActivity() {
+    private lateinit var daemonLink: DaemonLink
+
+    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()
+                Scaffold(modifier = Modifier.fillMaxSize()) { 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/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/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/src/lib.rs

@@ -58,6 +58,24 @@ use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 
 pub use agent_client_protocol::schema::v1 as schema;
 
+/// 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>>,
+    },
+}
+
 /// ACP adapter selected from the structured session's resolved command.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AcpAdapter {
@@ -354,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>>,
 }
@@ -393,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()
     }
 
@@ -772,7 +790,7 @@ fn config_notification(session_id: &str, options: Vec<SessionConfigOption>) -> S
 async fn run_connection<T>(
     transport: T,
     config: ConnectionConfig,
-    updates_tx: mpsc::UnboundedSender<SessionNotification>,
+    updates_tx: mpsc::UnboundedSender<AcpUpdate>,
     permission_requests: mpsc::UnboundedSender<PermissionRequest>,
     mut commands_rx: mpsc::UnboundedReceiver<Command>,
     ready_tx: oneshot::Sender<Result<String, ReadyError>>,
@@ -800,7 +818,7 @@ async fn run_connection<T>(
                     return Ok(());
                 }
                 // A dropped receiver only means nobody wants updates any more.
-                let _ = received_updates.send(notification);
+                let _ = received_updates.send(AcpUpdate::Notification(Box::new(notification)));
                 Ok(())
             },
             agent_client_protocol::on_receive_notification!(),
@@ -916,18 +934,18 @@ async fn run_connection<T>(
                 models.as_ref(),
             )));
             if let Some(modes) = &modes {
-                let _ = updates_tx.send(SessionNotification::new(
+                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(config_notification(
+                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()));
 
@@ -955,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(())
                                 }
@@ -998,7 +1023,7 @@ async fn run_connection<T>(
                                 }).on_receiving_result(move |result| async move {
                                     if result.is_ok() {
                                         let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
-                                        let _ = callback_updates.send(config_notification(&callback_session, options));
+                                        let _ = callback_updates.send(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()));
@@ -1017,13 +1042,13 @@ async fn run_connection<T>(
                                 )).on_receiving_result(move |result| async move {
                                     if result.is_ok() {
                                         let options = replace_config_value(&callback_options, &callback_config_id, &callback_value);
-                                        let _ = callback_updates.send(config_notification(&callback_session, options));
-                                        let _ = callback_updates.send(SessionNotification::new(
+                                        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()));
@@ -1041,7 +1066,7 @@ async fn run_connection<T>(
                                             let mut current = callback_options.lock().expect("config options");
                                             current.retain(|option| option.id.0.as_ref().starts_with("__maestro_legacy_"));
                                             current.extend(response.config_options.clone());
-                                            let _ = callback_updates.send(config_notification(&callback_session, current.clone()));
+                                            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()));

crates/maestro-acp/tests/spawn.rs

@@ -193,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 {
@@ -221,7 +224,10 @@ async fn advertised_settings_are_normalized_and_mutable() {
             .await
             .expect("settings update")
             .expect("channel open");
-        if let SessionUpdate::ConfigOptionUpdate(options) = update.update {
+        let maestro_acp::AcpUpdate::Notification(n) = update else {
+            continue;
+        };
+        if let SessionUpdate::ConfigOptionUpdate(options) = n.update {
             break options.config_options;
         }
     };
@@ -390,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(),

crates/maestro-cli/src/cli.rs

@@ -133,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

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

crates/maestro-daemon/src/local_api.rs

@@ -482,14 +482,13 @@ async fn structured_prompt(
     Path(id): Path<Uuid>,
     Json(body): Json<StructuredPromptRequest>,
 ) -> Response {
-    match s.manager.queue_acp_prompt(id, body.prompt).await {
-        Ok(QueueAcpPrompt::Queued) | Ok(QueueAcpPrompt::Pending) => {
-            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,

crates/maestro-daemon/src/session.rs

@@ -5,7 +5,7 @@
 //! single point through which the API handlers and the per-session WS
 //! handler interact with tmux.
 
-use std::collections::{HashMap, HashSet};
+use std::collections::{HashMap, HashSet, VecDeque};
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
 use std::sync::{Arc, Weak};
@@ -15,8 +15,8 @@ use chrono::Utc;
 use maestro_acp::{AcpAdapter, AcpSession, PermissionRequest, SpawnConfig};
 use maestro_protocol::display::command_tool;
 use maestro_protocol::{
-    ActivityState, CatalogEvent, CreateSessionRequest, ErrorInfo, NameSource, Session,
-    SessionStatus, SessionView, StructuredReplayEvent, TranscriptDelta, TranscriptRow,
+    ActivityState, CatalogEvent, CreateSessionRequest, ErrorInfo, NameSource, ReducedState,
+    Session, SessionStatus, SessionView, StructuredReplayEvent, TranscriptDelta, TranscriptRow,
     TranscriptRowKind, WorktreeSpec, NAME_KEY, NAME_SOURCE_KEY,
 };
 use tokio::sync::{broadcast, oneshot, watch, Mutex, Notify};
@@ -122,9 +122,6 @@ pub struct SessionRecord {
     /// When `true`, the permission pump auto-responds `AllowAlways` to every
     /// ACP permission request without surfacing it to clients.
     pub auto_approve: bool,
-    /// A prompt submitted while the adapter was still booting (`Starting`).
-    /// The background handshake task drains this on success.
-    pub pending_prompt: Option<String>,
 }
 
 impl SessionRecord {
@@ -149,6 +146,9 @@ struct StructuredActivityWatermark {
     sequence: u64,
 }
 
+/// Maximum number of prompts that can be queued while a turn is in flight.
+const PROMPT_QUEUE_CAP: usize = 20;
+
 #[derive(Debug)]
 struct AcpEventStream {
     log: EventLog,
@@ -160,6 +160,10 @@ struct AcpEventStream {
     /// claimed: it is queued onto ACP before another operation can proceed.
     operation: Arc<Mutex<()>>,
     dispatch: AcpDispatchState,
+    /// Server-side FIFO of prompts accepted while a turn was in flight or the
+    /// adapter was still booting. Drained as a single concatenated prompt when
+    /// the current turn completes. Persisted to the session sidecar.
+    prompt_queue: VecDeque<String>,
     activity_sequence: u64,
 }
 
@@ -168,6 +172,23 @@ impl AcpEventStream {
         self.activity_sequence += 1;
         (self.activity_sequence, self.projection.activity())
     }
+
+    /// The reduced state with the prompt queue overlaid. Every broadcast and
+    /// snapshot should use this instead of `projection.state()` directly so
+    /// clients always see the current queue.
+    fn state_with_queue(&self) -> ReducedState {
+        let mut state = self.projection.state();
+        state.queued_prompts = self.prompt_queue.iter().cloned().collect();
+        state
+    }
+
+    /// Broadcast a projection update with the prompt queue overlaid into the
+    /// state. Every `projected_live.send` should go through this so clients
+    /// never see a stale queue.
+    fn broadcast(&self, mut update: ProjectionUpdate) {
+        update.state.queued_prompts = self.prompt_queue.iter().cloned().collect();
+        let _ = self.projected_live.send(update);
+    }
 }
 
 #[derive(Debug, Default)]
@@ -235,11 +256,14 @@ pub enum BeginAcpTurn {
 /// Result of serializing a projected turn claim with its ACP prompt enqueue.
 #[derive(Debug)]
 pub enum QueueAcpPrompt {
+    /// The prompt was dispatched to ACP immediately (no turn was in flight).
+    Dispatched,
+    /// The prompt was accepted into the server-side queue and will be
+    /// dispatched when the current turn completes.
     Queued,
-    /// The adapter is still booting; the prompt is held until it is ready.
-    Pending,
-    InFlight,
     Unavailable,
+    /// The prompt queue has reached its capacity.
+    Full,
     Failed(String),
 }
 
@@ -662,7 +686,7 @@ impl SessionManager {
         let live = stream.projected_live.subscribe();
         Ok(Some((
             stream.projection.snapshot(stream.log.last_seq()),
-            stream.projection.state(),
+            stream.state_with_queue(),
             live,
         )))
     }
@@ -692,7 +716,7 @@ impl SessionManager {
             return Ok(false);
         };
         let projected = persist_turn_update(&mut stream, projected);
-        let _ = stream.projected_live.send(projected);
+        stream.broadcast(projected);
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
         Ok(true)
@@ -717,7 +741,7 @@ impl SessionManager {
             return Ok(BeginAcpTurn::InFlight);
         }
         let (turn, update) = stream.projection.begin_turn();
-        let _ = stream.projected_live.send(update);
+        stream.broadcast(update);
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
         Ok(BeginAcpTurn::Started(acp, turn))
@@ -733,15 +757,31 @@ impl SessionManager {
         &self,
         id: Uuid,
         text: String,
+        row_metadata: Option<serde_json::Value>,
     ) -> Result<QueueAcpPrompt, SessionError> {
         let (acp, stream) = {
-            let mut sessions = self.inner.sessions.lock().await;
-            let record = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
-            // While the adapter is booting, stash the prompt for the
-            // background handshake task to drain on success.
+            let sessions = self.inner.sessions.lock().await;
+            let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?;
             if record.is_starting_structured() {
-                record.pending_prompt = Some(text);
-                return Ok(QueueAcpPrompt::Pending);
+                // Adapter still booting — queue the prompt for drain on boot
+                // success. The AcpEventStream exists, just no ACP handle yet.
+                let stream = record
+                    .acp_events
+                    .clone()
+                    .expect("structured session has events at Starting");
+                let mut stream = stream.lock().await;
+                if stream.prompt_queue.len() >= PROMPT_QUEUE_CAP {
+                    return Ok(QueueAcpPrompt::Full);
+                }
+                stream.prompt_queue.push_back(text);
+                let update = ProjectionUpdate {
+                    transcript: None,
+                    state: stream.projection.state(),
+                };
+                stream.broadcast(update);
+                drop(stream);
+                self.persist_prompt_queue(id).await;
+                return Ok(QueueAcpPrompt::Queued);
             }
             if !record.is_live_structured() {
                 return Ok(QueueAcpPrompt::Unavailable);
@@ -762,19 +802,51 @@ impl SessionManager {
                 }
                 if let Some(turn) = stream.dispatch.queued_turn {
                     if stream.dispatch.cancelled_turn != Some(turn) {
-                        return Ok(QueueAcpPrompt::InFlight);
+                        // Turn is in flight — queue instead of rejecting.
+                        if stream.prompt_queue.len() >= PROMPT_QUEUE_CAP {
+                            return Ok(QueueAcpPrompt::Full);
+                        }
+                        stream.prompt_queue.push_back(text);
+                        let update = ProjectionUpdate {
+                            transcript: None,
+                            state: stream.projection.state(),
+                        };
+                        stream.broadcast(update);
+                        drop(stream);
+                        self.persist_prompt_queue(id).await;
+                        return Ok(QueueAcpPrompt::Queued);
                     }
                     Some((turn, stream.dispatch.settled.clone()))
                 } else {
                     if stream.projection.turn_active() {
-                        return Ok(QueueAcpPrompt::InFlight);
+                        // Projection says active but dispatch says idle —
+                        // queue rather than rejecting.
+                        if stream.prompt_queue.len() >= PROMPT_QUEUE_CAP {
+                            return Ok(QueueAcpPrompt::Full);
+                        }
+                        stream.prompt_queue.push_back(text);
+                        let update = ProjectionUpdate {
+                            transcript: None,
+                            state: stream.projection.state(),
+                        };
+                        stream.broadcast(update);
+                        drop(stream);
+                        self.persist_prompt_queue(id).await;
+                        return Ok(QueueAcpPrompt::Queued);
+                    }
+                    let mut data = serde_json::json!({
+                        "content": {"type": "text", "text": text},
+                    });
+                    if let Some(extra) = &row_metadata {
+                        if let (Some(base), Some(extra)) = (data.as_object_mut(), extra.as_object())
+                        {
+                            base.extend(extra.iter().map(|(k, v)| (k.clone(), v.clone())));
+                        }
                     }
                     let row = TranscriptRow {
                         id: format!("user:{}", Uuid::new_v4()),
                         kind: TranscriptRowKind::User,
-                        data: serde_json::json!({
-                            "content": {"type": "text", "text": text},
-                        }),
+                        data,
                     };
                     let event = PersistedEvent::User { row: row.clone() };
                     let seq = match stream.log.append(&event) {
@@ -789,9 +861,9 @@ impl SessionManager {
                     let logged = LoggedEvent { seq, event };
                     let projected = stream.projection.restore_row(row);
                     let _ = stream.live.send(logged);
-                    let _ = stream.projected_live.send(projected);
+                    stream.broadcast(projected);
                     let (turn, update) = stream.projection.begin_turn();
-                    let _ = stream.projected_live.send(update);
+                    stream.broadcast(update);
                     match acp.prompt(text.clone(), turn) {
                         Ok(done) => {
                             stream.dispatch.queued_turn = Some(turn);
@@ -809,7 +881,7 @@ impl SessionManager {
                             if let Ok(true) = self.claim_autoname(id).await {
                                 crate::autoname::spawn_naming(self.clone(), id, text);
                             }
-                            return Ok(QueueAcpPrompt::Queued);
+                            return Ok(QueueAcpPrompt::Dispatched);
                         }
                         Err(message) => {
                             cancel_pending_approvals(&mut stream);
@@ -820,7 +892,7 @@ impl SessionManager {
                                     "newly claimed turn remains current while stream is locked",
                                 );
                             let projected = persist_turn_update(&mut stream, projected);
-                            let _ = stream.projected_live.send(projected);
+                            stream.broadcast(projected);
                             drop(stream);
                             sync_structured_activity(&self.inner, id).await;
                             return Ok(QueueAcpPrompt::Failed(message));
@@ -840,6 +912,27 @@ impl SessionManager {
         }
     }
 
+    /// Persist the current prompt queue to the session sidecar.
+    async fn persist_prompt_queue(&self, id: Uuid) {
+        let stream_arc = {
+            let sessions = self.inner.sessions.lock().await;
+            sessions.get(&id).and_then(|r| r.acp_events.clone())
+        };
+        let Some(stream_arc) = stream_arc else { return };
+        let queue: Vec<String> = stream_arc
+            .lock()
+            .await
+            .prompt_queue
+            .iter()
+            .cloned()
+            .collect();
+        let mut sessions = self.inner.sessions.lock().await;
+        if let Some(record) = sessions.get_mut(&id) {
+            record.session.queued_prompts = queue;
+            let _ = self.inner.sidecar.write(&record.session);
+        }
+    }
+
     async fn finish_queued_acp_turn(&self, id: Uuid, turn: u64, lifecycle: TurnLifecycle) {
         let stream = self
             .inner
@@ -860,16 +953,33 @@ impl SessionManager {
             stream.dispatch.cancelled_turn = None;
         }
         stream.dispatch.settled.notify_waiters();
-        if stream.projection.active_turn() != Some(turn) {
-            return;
-        }
-        cancel_pending_approvals(&mut stream);
-        if let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) {
-            let projected = persist_turn_update(&mut stream, projected);
-            let _ = stream.projected_live.send(projected);
+        if stream.projection.active_turn() == Some(turn) {
+            cancel_pending_approvals(&mut stream);
+            if let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) {
+                let projected = persist_turn_update(&mut stream, projected);
+                stream.broadcast(projected);
+            }
         }
+        // Drain the prompt queue: concatenate all queued prompts into a single
+        // prompt and dispatch as the next turn.  This must run even when the
+        // projection already ended the turn (e.g. cancel settled via the event
+        // stream before this function ran).
+        let queued_text = if stream.prompt_queue.is_empty() {
+            None
+        } else {
+            let texts: Vec<String> = stream.prompt_queue.drain(..).collect();
+            Some(texts.join("\n\n"))
+        };
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
+        if let Some(text) = queued_text {
+            self.persist_prompt_queue(id).await;
+            // Cannot call queue_acp_prompt here (async cycle via the spawn
+            // inside queue_acp_prompt → finish_queued_acp_turn → here).
+            // Spawn an independent task instead.
+            let manager = self.clone();
+            drain_prompt_queue(manager, id, text);
+        }
     }
 
     async fn fail_cancelled_acp_turn(
@@ -983,7 +1093,7 @@ impl SessionManager {
             .turn_lifecycle(TurnLifecycle::Cancel, turn)
             .expect("active turn remains current while stream is locked");
         let projected = persist_turn_update(&mut stream, projected);
-        let _ = stream.projected_live.send(projected);
+        stream.broadcast(projected);
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
         if let Some(turn) = cancelled_queued_turn {
@@ -1032,7 +1142,7 @@ impl SessionManager {
         let outcome = permission_outcome(decision, &pending.options);
         let _ = pending.response.send(outcome);
         if let Some(update) = stream.projection.resolve_approval(nonce) {
-            let _ = stream.projected_live.send(update);
+            stream.broadcast(update);
         }
         drop(stream);
         sync_structured_activity(&self.inner, id).await;
@@ -1340,6 +1450,7 @@ impl SessionManager {
                             pending_approvals: HashMap::new(),
                             operation: Arc::new(Mutex::new(())),
                             dispatch: AcpDispatchState::default(),
+                            prompt_queue: VecDeque::new(),
                             activity_sequence: 0,
                         }))
                     }
@@ -1404,6 +1515,8 @@ impl SessionManager {
             last_focused_at: None,
             acp_session_id: None,
             view: req.view,
+            auto_approve: req.auto_approve,
+            queued_prompts: Vec::new(),
         };
 
         if let Err(e) = self.inner.sidecar.write(&session) {
@@ -1435,7 +1548,6 @@ impl SessionManager {
                     structured_activity_watermark: None,
                     acp_event_pump: None,
                     auto_approve: req.auto_approve,
-                    pending_prompt: None,
                 },
             );
         }
@@ -1489,8 +1601,8 @@ impl SessionManager {
                         let acp = Arc::new(acp_session);
                         let done = start_acp_event_pump(&inner, id, &acp, events.clone());
                         start_acp_permission_pump(&inner, id, &acp, events.clone(), auto_approve);
-                        // Drain any prompt submitted while Starting.
-                        let pending_prompt = {
+                        // Drain any prompts queued while the adapter was Starting.
+                        let queued_text = {
                             let mut sessions = inner.sessions.lock().await;
                             let Some(record) = sessions.get_mut(&id) else {
                                 // Session was killed while we were booting.
@@ -1504,17 +1616,30 @@ impl SessionManager {
                             record.session.acp_session_id = Some(acp.session_id().to_string());
                             record.session.activity = ActivityState::Idle;
                             record.session.activity_since = Utc::now();
+                            let queued = if let Some(ref stream) = record.acp_events {
+                                let mut stream = stream.lock().await;
+                                if stream.prompt_queue.is_empty() {
+                                    None
+                                } else {
+                                    let texts: Vec<String> =
+                                        stream.prompt_queue.drain(..).collect();
+                                    Some(texts.join("\n\n"))
+                                }
+                            } else {
+                                None
+                            };
+                            record.session.queued_prompts.clear();
                             let _ = inner.sidecar.write(&record.session);
                             let _ = inner.events.send(CatalogEvent::SessionUpdated {
                                 session: record.session.clone(),
                             });
-                            record.pending_prompt.take()
+                            queued
                         };
-                        if let Some(prompt) = pending_prompt {
+                        if let Some(text) = queued_text {
                             let manager = SessionManager {
                                 inner: inner.clone(),
                             };
-                            let _ = manager.queue_acp_prompt(id, prompt).await;
+                            let _ = manager.queue_acp_prompt(id, text, None).await;
                         }
                     }
                     Err(e) => {
@@ -1545,15 +1670,10 @@ impl SessionManager {
     /// uncommitted tracked changes, untracked non-ignored files, or commits
     /// reachable from no remote-tracking ref. Nothing is killed and nothing
     /// is removed; the error names what blocked it and how much of it there
-    /// is. The session stays as the operator's handle on their own unfinished
-    /// work, so ending a session that still matters becomes a deliberate
-    /// `--force`, which leaves the tree alone rather than destroying it
-    /// (WORKTREES.md).
+    /// is.
     ///
-    /// With `force` (#81) the refusal — and nothing else — is overridden:
-    /// the session ends and the guarded worktree is left on disk, never
-    /// removed. A tree whose guard is clear never needed the override; force
-    /// removes it as usual.
+    /// With `force` (#81) the refusal is overridden: the session ends and
+    /// the worktree is removed, even when it holds unsaved work.
     ///
     /// This is also how an already-dead session is dismissed. tmux is only
     /// asked to kill something it still has — calling `kill-session` on a
@@ -1588,7 +1708,7 @@ impl SessionManager {
             sessions.remove(&id)
         };
         let record = removed.ok_or(SessionError::NotFound(id))?;
-        cleanup_record(&self.inner, id, record, alive, guarded).await;
+        cleanup_record(&self.inner, id, record, alive).await;
         Ok(())
     }
 
@@ -1683,6 +1803,8 @@ impl SessionManager {
                     // Unknown on adoption without a sidecar; matches every
                     // other field's forward-compat default.
                     view: maestro_protocol::SessionView::Terminal,
+                    auto_approve: false,
+                    queued_prompts: Vec::new(),
                 },
             };
             let fifo_path = self.inner.fifo_dir.join(format!("{id}.fifo"));
@@ -1720,8 +1842,7 @@ impl SessionManager {
                     acp_events: None,
                     structured_activity_watermark: None,
                     acp_event_pump: None,
-                    auto_approve: false,
-                    pending_prompt: None,
+                    auto_approve: session.auto_approve,
                 },
             );
             let _ = self
@@ -1849,6 +1970,7 @@ impl SessionManager {
                             pending_approvals: HashMap::new(),
                             operation: Arc::new(Mutex::new(())),
                             dispatch: AcpDispatchState::default(),
+                            prompt_queue: session.queued_prompts.drain(..).collect(),
                             activity_sequence: 0,
                         })))
                     }
@@ -1896,21 +2018,45 @@ impl SessionManager {
                     focused_since: None,
                     awaiting_suppressed: false,
                     acp,
-                    acp_events,
+                    acp_events: acp_events.clone(),
                     structured_activity_watermark: None,
                     acp_event_pump: None,
-                    // Recovery cannot know the original preset's flag; the
-                    // operator re-enables it by restarting with the preset.
-                    auto_approve: false,
-                    pending_prompt: None,
+                    auto_approve: session.auto_approve,
                 },
             );
             if let Some((acp, events)) = event_pump {
                 let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
-                start_acp_permission_pump(&self.inner, id, &acp, events, false);
+                start_acp_permission_pump(&self.inner, id, &acp, events, session.auto_approve);
                 if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
                     record.acp_event_pump = Some(done);
                 }
+                // Drain any prompts that were queued before the daemon
+                // restarted. If none were queued, send a synthetic continue
+                // prompt so the agent resumes autonomously.
+                let queued_text = {
+                    let stream = acp_events
+                        .as_ref()
+                        .expect("recovery with acp implies acp_events");
+                    let mut stream = stream.lock().await;
+                    if stream.prompt_queue.is_empty() {
+                        None
+                    } else {
+                        let texts: Vec<String> = stream.prompt_queue.drain(..).collect();
+                        Some(texts.join("\n\n"))
+                    }
+                };
+                if let Some(text) = queued_text {
+                    self.persist_prompt_queue(id).await;
+                    let _ = self.queue_acp_prompt(id, text, None).await;
+                } else {
+                    let _ = self
+                        .queue_acp_prompt(
+                            id,
+                            "The daemon restarted. Continue where you left off.".into(),
+                            Some(serde_json::json!({"maestro": {"type": "restart_continue"}})),
+                        )
+                        .await;
+                }
             }
             let _ = self
                 .inner
@@ -2257,34 +2403,49 @@ fn start_acp_event_pump(
     let weak_inner = Arc::downgrade(inner);
     let weak_acp = Arc::downgrade(acp);
     tokio::spawn(async move {
-        while let Some(notification) = updates.recv().await {
-            let append_error = {
-                let mut events = events.lock().await;
-                let event = PersistedEvent::Notification(Box::new(notification));
-                match events.log.append(&event) {
-                    Ok(seq) => {
-                        let logged = LoggedEvent {
-                            seq,
-                            event: event.clone(),
-                        };
-                        let projected = apply_persisted_event(&mut events.projection, &logged);
-                        let _ = events.live.send(logged);
-                        let _ = events.projected_live.send(projected);
-                        None
+        while let Some(update) = updates.recv().await {
+            match update {
+                maestro_acp::AcpUpdate::Notification(notification) => {
+                    let append_error = {
+                        let mut events = events.lock().await;
+                        let event = PersistedEvent::Notification(notification);
+                        match events.log.append(&event) {
+                            Ok(seq) => {
+                                let logged = LoggedEvent {
+                                    seq,
+                                    event: event.clone(),
+                                };
+                                let projected =
+                                    apply_persisted_event(&mut events.projection, &logged);
+                                let _ = events.live.send(logged);
+                                events.broadcast(projected);
+                                None
+                            }
+                            Err(error) => Some(error),
+                        }
+                    };
+                    if let Some(error) = append_error {
+                        tracing::error!(%id, %error, "structured event log append failed");
+                        if let Some(acp) = weak_acp.upgrade() {
+                            acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
+                                .await;
+                        }
+                        if let Some(inner) = weak_inner.upgrade() {
+                            mark_session_dead(&inner, id).await;
+                        }
+                        break;
                     }
-                    Err(error) => Some(error),
                 }
-            };
-            if let Some(error) = append_error {
-                tracing::error!(%id, %error, "structured event log append failed");
-                if let Some(acp) = weak_acp.upgrade() {
-                    acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE)
-                        .await;
+                maestro_acp::AcpUpdate::TurnDone {
+                    turn: _,
+                    result,
+                    done,
+                } => {
+                    // Every notification for this turn has been persisted and
+                    // broadcast above.  Signal the done oneshot so
+                    // finish_queued_acp_turn runs with the transcript complete.
+                    let _ = done.send(result);
                 }
-                if let Some(inner) = weak_inner.upgrade() {
-                    mark_session_dead(&inner, id).await;
-                }
-                break;
             }
         }
         let _ = done_tx.send(true);
@@ -2439,7 +2600,7 @@ fn start_acp_permission_pump(
             let outcome = record_permission_request(&mut events, request, response);
             let fatal = matches!(outcome, RecordOutcome::Fatal);
             if let RecordOutcome::Live(update) = outcome {
-                let _ = events.projected_live.send(*update);
+                events.broadcast(*update);
             }
             drop(events);
             if fatal {
@@ -2532,7 +2693,7 @@ fn cancel_pending_approvals(events: &mut AcpEventStream) {
             .send(maestro_acp::schema::RequestPermissionOutcome::Cancelled);
     }
     if let Some(update) = events.projection.clear_approval() {
-        let _ = events.projected_live.send(update);
+        events.broadcast(update);
     }
 }
 
@@ -2882,6 +3043,18 @@ async fn run_blocked_work_pass(inner: &Arc<Inner>) {
 /// Terminal sessions that die naturally do not survive a daemon restart:
 /// [`SessionManager::recover`] adopts only what tmux still holds. Structured
 /// sessions stopped for daemon shutdown retain their sidecars for ACP recovery.
+/// Spawn an independent task to dispatch the next prompt from the drained
+/// queue. Free function with an explicit `Box::pin` future to break the
+/// compiler's async-cycle check: `queue_acp_prompt` → spawn →
+/// `finish_queued_acp_turn` → here → `queue_acp_prompt`.
+fn drain_prompt_queue(manager: SessionManager, id: Uuid, text: String) {
+    let fut: std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>> =
+        Box::pin(async move {
+            let _ = manager.queue_acp_prompt(id, text, None).await;
+        });
+    tokio::spawn(fut);
+}
+
 async fn mark_session_dead(inner: &Arc<Inner>, id: Uuid) {
     if inner.shutting_down.load(Ordering::Acquire) {
         return;
@@ -2935,7 +3108,9 @@ async fn mark_session_dead_with_worktree_settlement(
         .get(&id)
         .and_then(|record| record.acp_events.clone());
     if let Some(stream) = stream {
-        cancel_pending_approvals(&mut *stream.lock().await);
+        let mut stream = stream.lock().await;
+        cancel_pending_approvals(&mut stream);
+        stream.prompt_queue.clear();
     }
     tracing::info!(%id, "session process gone — marking dead");
 
@@ -2962,6 +3137,7 @@ async fn mark_session_dead_with_worktree_settlement(
             return false;
         };
         record.settled = true;
+        record.session.queued_prompts.clear();
         record.session.clone()
     };
 
@@ -2972,8 +3148,8 @@ async fn mark_session_dead_with_worktree_settlement(
 
 /// Apply the exit rule (#82) to a vanished session's worktree: probe what
 /// would be lost through the kill's own predicate, then remove a pristine
-/// tree. Anything holding unsaved work is left exactly where it is — the
-/// same thing a forced kill does with a guarded tree (#81).
+/// tree. Anything holding unsaved work is left on disk — there is no
+/// operator confirmation on the natural-exit path.
 ///
 /// Returns whether the worktree was fully accounted for. When it wasn't,
 /// nothing was destroyed and the caller keeps the reference on the record.
@@ -3028,17 +3204,7 @@ async fn settle_worktree_on_exit(
 /// gone from the authoritative in-memory map, so a stray FIFO or sidecar can't
 /// resurrect it. `kill_tmux` is `true` for an explicit kill and `false` for the
 /// liveness reaper (tmux already lost the session).
-///
-/// `keep_worktree` is `true` for a forced kill (#81) over a guarded tree: the
-/// session ends but the worktree is left on disk, so only the removal is
-/// skipped.
-async fn cleanup_record(
-    inner: &Arc<Inner>,
-    id: Uuid,
-    record: SessionRecord,
-    kill_tmux: bool,
-    keep_worktree: bool,
-) {
+async fn cleanup_record(inner: &Arc<Inner>, id: Uuid, record: SessionRecord, kill_tmux: bool) {
     if kill_tmux {
         let tmux = inner.tmux.clone();
         let _ = tmux_blocking(move || tmux.kill_session(id)).await;
@@ -3059,17 +3225,7 @@ async fn cleanup_record(
         tracing::warn!(error = ?e, %id, "cleanup: failed to delete sidecar");
     }
     if let (Some(base), Some(path)) = (&record.worktree_base_repo, &record.worktree_path) {
-        if keep_worktree {
-            tracing::info!(
-                %id,
-                path = %path.display(),
-                "forced kill: worktree left on disk"
-            );
-        } else if let Err(e) = inner.worktree_mgr.remove(base, path) {
-            // The kill already passed the unsaved-work guard (#79), so this
-            // removal is unconditional; the manager's own nested-worktree
-            // refusal is all that can still leave a tree on disk, and it
-            // says where.
+        if let Err(e) = inner.worktree_mgr.remove(base, path) {
             tracing::warn!(
                 %id,
                 path = %path.display(),
@@ -3145,6 +3301,7 @@ mod tests {
             pending_approvals: std::collections::HashMap::new(),
             operation: std::sync::Arc::new(tokio::sync::Mutex::new(())),
             dispatch: AcpDispatchState::default(),
+            prompt_queue: std::collections::VecDeque::new(),
             activity_sequence: 0,
         }
     }

crates/maestro-daemon/tests/acp.rs

@@ -84,15 +84,27 @@ 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]",
     }
 }
 
@@ -259,10 +271,10 @@ async fn structured_activity_tracks_turn_completion_and_failure() {
 
     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
@@ -286,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
@@ -426,10 +438,10 @@ async fn queued_prompt_is_a_durable_user_transcript_row() {
 
     assert!(matches!(
         fx.manager
-            .queue_acp_prompt(session.id, "show my prompt".into())
+            .queue_acp_prompt(session.id, "show my prompt".into(), None)
             .await
             .expect("queue prompt"),
-        maestro_daemon::session::QueueAcpPrompt::Queued
+        maestro_daemon::session::QueueAcpPrompt::Dispatched
     ));
 
     let (snapshot, _, _) = fx
@@ -516,15 +528,15 @@ async fn cancelled_prompt_that_never_settles_fails_the_session() {
 
     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!(
@@ -555,18 +567,18 @@ async fn cancellation_settlement_allows_the_next_prompt_permission() {
 
     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 {
@@ -655,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;
 
@@ -682,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);
@@ -693,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");

crates/maestro-daemon/tests/local_api.rs

@@ -293,7 +293,7 @@ async fn structured_attachments_preserve_bytes_and_reject_paths() {
 }
 
 #[tokio::test]
-async fn structured_prompt_rejects_a_second_in_flight_turn_and_cancel_clears_it() {
+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();
@@ -310,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,
@@ -319,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(
@@ -332,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 {
@@ -351,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();

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-e2e/tests/e2e.rs

@@ -777,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!(
@@ -789,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"
     );
 }
 

crates/maestro-protocol/src/display.rs

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

crates/maestro-protocol/src/lib.rs

@@ -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
@@ -872,6 +882,10 @@ pub struct ReducedState {
     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.
@@ -1054,6 +1068,8 @@ mod tests {
             last_focused_at: None,
             view: SessionView::Terminal,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 

crates/maestro-testing/src/lib.rs

@@ -50,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(),
     }
 }
 

crates/maestro-tui/src/app.rs

@@ -2216,6 +2216,8 @@ mod tests {
                     blocked_work: None,
                     last_focused_at: None,
                     acp_session_id: None,
+                    auto_approve: false,
+                    queued_prompts: Vec::new(),
                 })
                 .collect(),
         });
@@ -2399,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);
@@ -2428,6 +2432,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 
@@ -3590,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 {
@@ -3870,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);
@@ -3907,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(),
         }
     }
 

crates/maestro-tui/src/command_bar.rs

@@ -811,6 +811,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/sidebar.rs

@@ -502,6 +502,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         }
     }
 
@@ -1272,6 +1274,8 @@ mod tests {
             blocked_work: None,
             last_focused_at: None,
             acp_session_id: None,
+            auto_approve: false,
+            queued_prompts: Vec::new(),
         };
         let sb = Sidebar {
             sessions: vec![s],

docs/SIDEBAR.md

@@ -70,7 +70,7 @@ command. `<duration>` follows in the rail's colour when shown. There is no
 state word and no second badge: the rail exists so the state is still legible
 when a row is dimmed or the terminal renders the duration in the default fg.
 
-In the **web client** the rail is a 5px bar pinned to the row's own left
+In the **web client** the rail is a 7px bar pinned to the row's own left
 edge, square corners, spanning the full card height edge to edge — it
 shifts outward with nesting depth along with the row's own padding, since
 it is positioned relative to the row. It carries motion only for states that

docs/STRUCTURED-VIEW.md

@@ -189,17 +189,17 @@ choices, not daemon ones.
   presentation for `Notice`. `Plan` is the exception: both clients omit it
   from the transcript; the TUI may show the current plan in its status line,
   while the web client deliberately has no stats or plan rail.
-- The web client groups two or more tool rows after the same `User` row into
-  one collapsed turn activity block. `AgentText` and `AgentThought` rows that
-  appear *between* tool rows in the same turn are absorbed into the group
-  (intermediate narration); the last `AgentText` with no subsequent tool stays
-  outside as the prominent final answer. While a turn is still active
-  (responding or thinking), the most recent intermediate `AgentText` or
-  `AgentThought` in the group is kept outside as visible narration — replaced
-  by the next text row when one arrives, and absorbed into the group when the
-  turn ends. The header still reads "N tool calls" (counting only tool rows).
-  Opening the group reveals tools and intermediate text in chronological
-  order, with the text rendered in a subdued style.
+- The web client groups each contiguous run of two or more tool rows into a
+  collapsed activity block. An `AgentText` or `AgentThought` row between
+  tools splits them into separate groups, so the timeline reads
+  text → group → text → group rather than lumping every tool in a turn into
+  one box. Text and thought rows stay outside groups as standalone transcript
+  items — the operator sees all reasoning without expanding. Resolved
+  approval rows between tools within a run are absorbed into the group. The
+  collapsed header reads "N tool calls · Label 'arg'" where the label and
+  argument come from the last tool row's `splitToolTitle` — the operator
+  sees which command is current at a glance. Opening the group reveals tool
+  rows in chronological order.
 - The web client's user, agent, thought, tool-detail, and notice text blocks
   copy their complete source text when clicked or keyboard-activated.
 - The web client consumes `available_commands_update` notices as the live
@@ -353,21 +353,26 @@ thing a callback can be attributed to, so at most one turn may ever be
 in flight, and a cancelled turn must fully settle before the next prompt is
 allowed to claim the daemon's idea of "the active turn."
 
-- Web clients may collect a visible FIFO of operator messages while a turn is
-  active. They submit each queued message only after the projected turn becomes
-  idle; the queue is client-local and unsent messages do not survive a reload.
+- Prompts are accepted at any time: if the session is idle the daemon dispatches
+  immediately (`204`); if a turn is active the prompt is appended to a
+  server-side FIFO (`202 Accepted`, capped at 20 entries, `429` when full).
+  When the active turn completes, all queued prompts are concatenated with
+  `\n\n` and dispatched as the next turn. The queue is persisted in the session
+  sidecar and survives daemon restarts — clients never queue locally.
+  `ReducedState.queued_prompts` contains the current queue so every connected
+  client can render the pending messages.
 - A submitted prompt is appended as a durable `User` row before it claims the turn and
   dispatches to ACP, so the transcript never depends on an adapter echoing the
-  operator's input. If that append fails, the prompt is not dispatched. While a
-  turn is active, a second prompt gets `409 turn_in_flight` rather than
-  queuing in the daemon — one active turn per session, never a hidden
-  server-side queue of prompts.
+  operator's input. If that append fails, the prompt is not dispatched.
 - Cancel sends `session/cancel`, clears any pending approval as `Cancelled`,
-  and ends the turn's client-visible lifecycle immediately. If the cancelled
-  turn was still *dispatched* to ACP (waiting on its response), the daemon
-  cannot simply forget it: ACP has not confirmed the cancel yet, and a new
-  prompt claiming "the active turn" while the old one is still outstanding
-  would make the next permission callback ambiguous between the two.
+  and ends the turn's client-visible lifecycle immediately. The prompt queue
+  is preserved: after the cancelled turn settles, the queued prompts drain as
+  the next turn. If the session dies instead (settlement timeout), the queue
+  is cleared. If the cancelled turn was still *dispatched* to ACP (waiting on
+  its response), the daemon cannot simply forget it: ACP has not confirmed the
+  cancel yet, and a new prompt claiming "the active turn" while the old one is
+  still outstanding would make the next permission callback ambiguous between
+  the two.
 - So a cancelled-but-still-dispatched turn must **settle within
   `CANCEL_GRACE` (500ms)** — either ACP acknowledges the prompt (however it
   resolves) or that grace period runs out. If it settles in time, the next

docs/WORKTREES.md

@@ -75,27 +75,17 @@ The point of refusing rather than cleaning up is that the session stays as the
 operator's handle on their own unfinished work. A session that is killed while
 its worktree still matters leaves a directory nobody is looking at.
 
-A consequence, accepted deliberately: a feature branch almost always has unpushed
-commits, so `--force` is the ordinary way to end a session, not an exception.
-That is only safe because force never removes what blocked.
-
 ### `--force`
 
-`--force` overrides the refusal and nothing else. It ends the session and
-**leaves the worktree on disk**, untouched. Force never removes a tree that
-would have blocked. A tree whose guard is clear never needed the override, so a
-forced kill removes it as usual — force changes what happens to blocked work,
-not ordinary cleanup.
+`--force` overrides the refusal and **removes the worktree**, even when it holds
+unsaved work. The operator sees the breakdown in the confirmation prompt and
+decides; once confirmed, the tree is gone.
 
 In the web client the kill button sends the unforced `DELETE` straight away —
 there is no pre-confirmation, because the daemon is the one that decides. Only
 the refusal raises a prompt, and that prompt names what is in the way and offers
 "Force kill", which repeats the request with `force=true`.
 
-Ending a session and destroying its work are two separate acts. Maestro only
-performs the first one. Removing a tree it left behind is the operator's own
-`git worktree remove`, chosen while looking at exactly what would be lost.
-
 ### Exiting on its own
 
 A session that ends by itself — the command finished, the operator typed `exit` —
@@ -113,17 +103,12 @@ once. A removed tree drops off the record, so dismissing the session afterwards
 does not refuse: there is no guard left to trip.
 
 A tree that was left alone stays attached to the dead record, where dismissing it
-later goes through `--force`, which leaves it on disk too. The same holds when
-the probe itself fails: nothing is destroyed.
+later goes through `--force`, which removes it. The same holds when the probe
+itself fails: nothing is destroyed.
 
-## Nothing is removed on the operator's behalf
+## Trees left behind by natural exit
 
-There is no store of worktrees the daemon is holding, no list endpoint, and no
-reclaim command. A tree left behind by a forced kill or a dirty exit is an
-ordinary git worktree on disk; `git worktree list` finds it and
-`git worktree remove` removes it.
-
-That is deliberate. A tracked list of trees pending deletion is a second place
-the truth can live, and it goes stale the moment somebody removes a directory by
-hand. Git already knows which worktrees exist, and removing one is not a
-decision Maestro is better placed to make.
+A forced kill always removes the worktree. A natural exit with unsaved work
+leaves the tree on disk — there is no operator confirmation in that path. Those
+trees are ordinary git worktrees; `git worktree list` finds them and
+`git worktree remove` removes them.

flake.nix

@@ -148,7 +148,7 @@
             pnpmDeps = (pkgs.fetchPnpmDeps.override { pnpm = pkgs.pnpm_10; }) {
               inherit (finalAttrs) pname version src;
               fetcherVersion = 3;
-              hash = "sha256-AzF/rrhqbvl613hNsC18YSylBSVxtatg7fEiUEF1u2o=";
+              hash = "sha256-FEWOAtSFvOWHeCNR0RK8JQ/ssW31qmShu1YD2GuqioQ=";
             };
 
             buildPhase = ''

web/src/App.tsx

@@ -47,6 +47,7 @@ import {
   OPEN_SPAWN_EVENT,
   SESSION_SELECT_EVENT,
   SPAWN_SIMILAR_EVENT,
+  requestCloseDrawer,
   requestOpenSpawn,
   requestToggleDrawer,
 } from "./uiEvents.js";
@@ -113,15 +114,23 @@ function Shell() {
   // a transient lost connection has already recovered.
   useEffect(() => {
     const recover = () => {
-      if (document.visibilityState !== "visible") return;
       void linkStore.getState().probe();
       catalogStore.getState().reconnect();
     };
-    document.addEventListener("visibilitychange", recover);
+    // visibilitychange fires reliably on tab/app switch; guard it so we don't
+    // probe while the page is being hidden.
+    const onVisibility = () => {
+      if (document.visibilityState !== "visible") return;
+      recover();
+    };
+    // pageshow (bfcache restore) and online (network back) indicate the page
+    // is active — fire unconditionally since visibilityState may lag behind on
+    // some mobile browsers.
+    document.addEventListener("visibilitychange", onVisibility);
     window.addEventListener("pageshow", recover);
     window.addEventListener("online", recover);
     return () => {
-      document.removeEventListener("visibilitychange", recover);
+      document.removeEventListener("visibilitychange", onVisibility);
       window.removeEventListener("pageshow", recover);
       window.removeEventListener("online", recover);
     };
@@ -174,6 +183,7 @@ function Shell() {
     (session: Session, opts?: { newTab?: boolean }) => {
       layoutStore.getState().openSessionBeside(session.id, opts);
       navigate({ kind: "attach", sessionId: session.id });
+      requestCloseDrawer();
     },
     [layoutStore, navigate],
   );
@@ -314,6 +324,7 @@ function Shell() {
             activeId={focusedSessionId}
             openIds={openIds}
             previewId={previewedSessionId}
+            linkStore={linkStore}
             onSelect={(id) => focusSession(id)}
             onPreview={preview}
             onSpawn={openPlainSpawn}

web/src/components/dialogs/HelpOverlay.tsx

@@ -6,6 +6,7 @@ import { useEffect, useState } from "react";
 import { createPortal } from "react-dom";
 
 import { CommandSet, defineCommands, keyCaps } from "../../commands.js";
+import { TOGGLE_HELP_EVENT } from "../../uiEvents.js";
 import { groupedCommands } from "./model.js";
 
 export function HelpOverlay() {
@@ -18,8 +19,13 @@ export function HelpOverlay() {
       if (open && overlayKeys.handle(e)) return;
       helpKeys.handle(e);
     };
+    const onToggle = () => setOpen((o) => !o);
     window.addEventListener("keydown", onKeydown);
-    return () => window.removeEventListener("keydown", onKeydown);
+    document.addEventListener(TOGGLE_HELP_EVENT, onToggle);
+    return () => {
+      window.removeEventListener("keydown", onKeydown);
+      document.removeEventListener(TOGGLE_HELP_EVENT, onToggle);
+    };
   }, [open]);
 
   if (!open) return null;

web/src/components/dialogs/KillDialog.test.tsx

@@ -71,4 +71,33 @@ describe("KillDialog", () => {
     await waitFor(() => expect(kill.disabled).toBe(false));
     expect(screen.getByText("Failed to kill: daemon unreachable")).not.toBeNull();
   });
+
+  it("resets pending when force changes, so the force button is clickable", async () => {
+    // Simulate the Sidebar flow: onConfirm resolves (parent switches to
+    // force mode via rerender), but pending was set to true before the call.
+    const onConfirm = vi.fn(() => Promise.resolve());
+    const { rerender } = render(
+      <KillDialog name="alpha" blockers={null} onConfirm={onConfirm} onCancel={vi.fn()} />,
+    );
+
+    const kill = screen.getByRole("button", { name: "Kill" }) as HTMLButtonElement;
+    fireEvent.click(kill);
+    expect(kill.disabled).toBe(true);
+
+    // Parent re-renders with force=true (the daemon refused the unforced kill).
+    await waitFor(() => expect(onConfirm).toHaveBeenCalledOnce());
+    rerender(
+      <KillDialog
+        name="alpha"
+        blockers={{ uncommitted_files: 1, untracked_files: 0, unpushed_commits: 0 }}
+        force
+        reason="worktree is dirty"
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    const forceBtn = screen.getByRole("button", { name: "Force kill" }) as HTMLButtonElement;
+    expect(forceBtn.disabled).toBe(false);
+  });
 });

web/src/components/dialogs/KillDialog.tsx

@@ -34,6 +34,11 @@ export function KillDialog(props: KillDialogProps) {
   // asked for the kill, so Enter confirms it.
   useEffect(() => confirmRef.current?.focus(), []);
 
+  // When the dialog transitions from normal → force mode, the previous
+  // onConfirm resolved without error (it mutated parent state and returned),
+  // so `pending` is still true.  Reset it so the force button is clickable.
+  useEffect(() => setPending(false), [force]);
+
   const handleConfirm = () => {
     setPending(true);
     setError(null);

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

@@ -2,7 +2,7 @@
 import { act, cleanup, fireEvent, render } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT } from "../../uiEvents.js";
+import { CLOSE_DRAWER_EVENT, OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT } from "../../uiEvents.js";
 import { TOGGLE_DRAWER_EVENT } from "../../uiEvents.js";
 import { Drawer } from "./Drawer.js";
 
@@ -103,6 +103,19 @@ describe("Drawer (#35)", () => {
     expect(shell().classList.contains("drawer-open")).toBe(false);
   });
 
+  it("closes on the close-drawer event (after spawn lands)", () => {
+    render(
+      <Drawer sidebar={<div className="tree-leaf">row</div>}>
+        <div>content</div>
+      </Drawer>,
+    );
+    openViaToggle();
+    act(() => {
+      document.dispatchEvent(new CustomEvent(CLOSE_DRAWER_EVENT));
+    });
+    expect(shell().classList.contains("drawer-open")).toBe(false);
+  });
+
   it("closes on a backdrop click", () => {
     render(
       <Drawer sidebar={<div className="tree-leaf">row</div>}>

web/src/components/layout/Drawer.tsx

@@ -10,7 +10,7 @@
 import type { ReactNode } from "react";
 import { useEffect, useRef, useState } from "react";
 
-import { OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT, TOGGLE_DRAWER_EVENT } from "../../uiEvents.js";
+import { CLOSE_DRAWER_EVENT, OPEN_SPAWN_EVENT, SPAWN_SIMILAR_EVENT, TOGGLE_DRAWER_EVENT } from "../../uiEvents.js";
 
 export interface DrawerProps {
   sidebar: ReactNode;
@@ -28,10 +28,12 @@ export function Drawer({ sidebar, children, className }: DrawerProps) {
     document.addEventListener(TOGGLE_DRAWER_EVENT, onToggle);
     document.addEventListener(OPEN_SPAWN_EVENT, onClose);
     document.addEventListener(SPAWN_SIMILAR_EVENT, onClose);
+    document.addEventListener(CLOSE_DRAWER_EVENT, onClose);
     return () => {
       document.removeEventListener(TOGGLE_DRAWER_EVENT, onToggle);
       document.removeEventListener(OPEN_SPAWN_EVENT, onClose);
       document.removeEventListener(SPAWN_SIMILAR_EVENT, onClose);
+      document.removeEventListener(CLOSE_DRAWER_EVENT, onClose);
     };
   }, []);
 

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

@@ -105,7 +105,7 @@ describe("MultiView", () => {
       expect(screen.getByText("Tab 1 · 1")).toBeTruthy();
       const pane = document.querySelector('[data-session-id="s9"]');
       expect(pane).toBeTruthy();
-      expect(pane!.querySelector(".bg-preview-tint")).toBeTruthy();
+      expect(pane!.classList.contains("is-preview")).toBe(true);
       expect(screen.getByText("preview")).toBeTruthy();
     });
 

web/src/components/layout/MultiView.tsx

@@ -188,8 +188,9 @@ function Pane({
   return (
     <div
       className={
-        "mv-pane flex h-full min-h-0 min-w-0 flex-col border " +
-        (isFocused && !isPreview ? "border-accent" : "border-border-strong")
+        "mv-pane flex h-full min-h-0 min-w-0 flex-col" +
+        (isFocused ? " is-focused" : "") +
+        (isPreview ? " is-preview" : "")
       }
       data-leaf-id={leaf.id}
       data-session-id={leaf.sessionId ?? undefined}
@@ -201,10 +202,7 @@ function Pane({
       }}
     >
       <div
-        className={
-          "mv-pane-header flex items-center justify-between gap-sp-2 border-b border-border-strong px-sp-2 py-sp-1 text-fs-12 " +
-          (isPreview ? "bg-preview-tint text-preview" : "bg-surface")
-        }
+        className="mv-pane-header attach-header flex items-center justify-between gap-sp-2 border-b border-border-strong px-sp-2 py-sp-1 text-fs-12"
       >
         {leaf.sessionId ? (
           <PaneTitle sessionId={leaf.sessionId} session={session} />

web/src/components/layout/PaneTitle.tsx

@@ -15,7 +15,7 @@ export interface PaneTitleProps {
 export function PaneTitle({ sessionId, session, className }: PaneTitleProps) {
   if (!session) {
     return (
-      <span className={className ?? "at-title"} title={sessionId}>
+      <span className={className ?? "attach-title"} title={sessionId}>
         session <span className="sid">{sessionId.slice(0, 8)}</span>
       </span>
     );
@@ -27,7 +27,7 @@ export function PaneTitle({ sessionId, session, className }: PaneTitleProps) {
   const icon = tool ? toolIconSvg(tool) : null;
 
   return (
-    <span className={className ?? "at-title"} title={`${name} · ${session.command}  (${sessionId})`}>
+    <span className={className ?? "attach-title"} title={`${name} · ${session.command}  (${sessionId})`}>
       <span className="at-name">{name}</span>
       {showCommand && (
         <span className="at-cmd">

web/src/components/sidebar/ActivityRail.tsx

@@ -1,4 +1,4 @@
-// docs/SIDEBAR.md: a 5px bar pinned to the row's own left edge, square
+// docs/SIDEBAR.md: a 7px bar pinned to the row's own left edge, square
 // corners, full card height. It paints for every card, Idle included, and it
 // carries the accessible name of the state so status is never colour-only.
 
@@ -37,7 +37,7 @@ export function ActivityRail({ activity }: { activity: ActivityState | string |
   const word = STATE_WORDS[slug] ?? STATE_WORDS.idle;
   return (
     <span
-      className={`absolute left-0 top-0 bottom-0 w-[5px] ${RAIL_CLASS[slug] ?? RAIL_CLASS.idle}`}
+      className={`absolute left-0 top-0 bottom-0 w-[7px] ${RAIL_CLASS[slug] ?? RAIL_CLASS.idle}`}
       data-activity={slug}
       role="img"
       title={word}

web/src/components/sidebar/SessionCard.tsx

@@ -44,14 +44,17 @@ export interface SessionCardProps {
   onRenameCancel(): void;
 }
 
-/** The fill ladder from docs/SIDEBAR.md "Which row is filled", furthest down
- * wins. Written as one ordered run so the precedence is the order it reads in. */
-function rowFill(p: SessionCardProps): string {
-  if (p.active) return "bg-accent-fill";
-  if (p.previewing) return "bg-preview-tint";
-  if (p.open) return "bg-accent/[0.06]";
-  if (p.highlighted) return "bg-preview-tint";
-  return "";
+/** The fill ladder from docs/SIDEBAR.md "Which row is filled" — the CSS
+ * cascade in styles.css carries the actual fills via `.is-active`, `.is-open`,
+ * `.is-previewing` (all inside `:where()` so source order is the precedence).
+ * We just apply the right class names here. */
+function rowClasses(p: SessionCardProps): string {
+  const cls: string[] = [];
+  if (p.active) cls.push("is-active");
+  if (p.open) cls.push("is-open");
+  if (p.previewing) cls.push("is-previewing");
+  if (p.highlighted) cls.push("is-highlighted");
+  return cls.join(" ");
 }
 
 export function SessionCard(props: SessionCardProps) {
@@ -62,7 +65,7 @@ export function SessionCard(props: SessionCardProps) {
 
   return (
     <a
-      className={`session-card tree-leaf relative flex flex-col gap-[1px] py-sp-1 pr-sp-2 no-underline ${rowFill(props)} ${
+      className={`session-card tree-leaf no-underline ${rowClasses(props)} ${
         running ? "" : "opacity-60"
       }`}
       href={`#/attach/${encodeURIComponent(s.id)}`}
@@ -84,7 +87,7 @@ export function SessionCard(props: SessionCardProps) {
       }}
     >
       <ActivityRail activity={s.activity} />
-      <span className="flex min-w-0 items-center gap-sp-2">
+      <span className="card-line1">
         {renaming ? (
           <RenameField
             session={s}
@@ -93,17 +96,17 @@ export function SessionCard(props: SessionCardProps) {
           />
         ) : (
           <span
-            className={`min-w-0 flex-1 truncate text-fs-13 ${
+            className={`leaf-name min-w-0 flex-1 truncate text-fs-13 ${
               isProvisionalName(s) ? "text-muted" : "text-ink"
             }`}
           >
             {name}
           </span>
         )}
-        <span className="flex flex-none items-center gap-[2px]">
+        <span className="leaf-actions">
           <button
             type="button"
-            className="leaf-clone text-faint hover:text-ink"
+            className="leaf-act leaf-clone"
             title="Spawn similar"
             aria-label={`Spawn similar to ${name}`}
             onClick={(e) => {
@@ -116,7 +119,7 @@ export function SessionCard(props: SessionCardProps) {
           </button>
           <button
             type="button"
-            className="leaf-kill text-faint hover:text-danger"
+            className="leaf-act leaf-kill"
             title="Kill session"
             aria-label={`Kill ${name}`}
             onClick={(e) => {

web/src/components/sidebar/Sidebar.test.tsx

@@ -2,9 +2,15 @@
 import { cleanup, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { ThemeProvider } from "../../contexts/ThemeContext.js";
 import type { Session } from "../../types.js";
 import { Sidebar } from "./Sidebar.js";
 
+/** Wrap children in ThemeProvider so useTheme works in the footer. */
+function Wrapper({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
@@ -36,7 +42,7 @@ function tree(): HTMLElement {
 
 describe("SessionCard layout", () => {
   it("renders two lines: the name, then a meta line naming the program", () => {
-    render(<Sidebar sessions={[session("alpha")]} />);
+    render(<Wrapper><Sidebar sessions={[session("alpha")]} /></Wrapper>);
 
     const row = card("alpha");
     expect(row.textContent).toContain("alpha");
@@ -52,7 +58,7 @@ describe("SessionCard layout", () => {
     const fresh = session("fresh", { activity: "Active", activity_since: "2026-08-24T09:59:50Z" });
     const held = session("held", { activity: "Active", activity_since: "2026-08-24T09:56:00Z" });
 
-    render(<Sidebar sessions={[fresh, held]} />);
+    render(<Wrapper><Sidebar sessions={[fresh, held]} /></Wrapper>);
 
     expect(card("fresh").querySelector(".activity-duration")).toBeNull();
     expect(card("held").querySelector(".activity-duration")!.textContent).toBe("4m");
@@ -60,13 +66,15 @@ describe("SessionCard layout", () => {
 
   it("paints a rail for every state, blinking on AwaitingInput and flashing on Error", () => {
     render(
-      <Sidebar
-        sessions={[
-          session("idle"),
-          session("await", { activity: "AwaitingInput" }),
-          session("err", { activity: "Error" }),
-        ]}
-      />,
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("idle"),
+            session("await", { activity: "AwaitingInput" }),
+            session("err", { activity: "Error" }),
+          ]}
+        />
+      </Wrapper>,
     );
 
     const rail = (id: string) => card(id).querySelector<HTMLElement>("[data-activity]")!;
@@ -80,13 +88,15 @@ describe("SessionCard layout", () => {
 
   it("renders blocked work as diff notation with the spelled-out tooltip", () => {
     render(
-      <Sidebar
-        sessions={[
-          session("alpha", {
-            blocked_work: { uncommitted_files: 2, insertions: 124, deletions: 18, untracked_files: 3 },
-          }),
-        ]}
-      />,
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("alpha", {
+              blocked_work: { uncommitted_files: 2, insertions: 124, deletions: 18, untracked_files: 3 },
+            }),
+          ]}
+        />
+      </Wrapper>,
     );
 
     const blocked = card("alpha").querySelector<HTMLElement>(".leaf-blocked")!;
@@ -96,12 +106,14 @@ describe("SessionCard layout", () => {
 
   it("dims a provisional name and leaves a settled one alone", () => {
     render(
-      <Sidebar
-        sessions={[
-          session("gen", { metadata: { name: "gen", name_source: "Generated" } }),
-          session("user", { metadata: { name: "user", name_source: "User" } }),
-        ]}
-      />,
+      <Wrapper>
+        <Sidebar
+          sessions={[
+            session("gen", { metadata: { name: "gen", name_source: "Generated" } }),
+            session("user", { metadata: { name: "user", name_source: "User" } }),
+          ]}
+        />
+      </Wrapper>,
     );
 
     expect(card("gen").querySelector(".text-muted")).not.toBeNull();
@@ -113,7 +125,7 @@ describe("keyboard walk", () => {
   const two = [session("a", { cwd: "/one" }), session("b", { cwd: "/two" })];
 
   it("j and k step the highlight through the cards", () => {
-    render(<Sidebar sessions={two} />);
+    render(<Wrapper><Sidebar sessions={two} /></Wrapper>);
 
     fireEvent.keyDown(tree(), { key: "j" });
     expect(card("a").dataset.highlighted).toBe("true");
@@ -124,7 +136,7 @@ describe("keyboard walk", () => {
   });
 
   it("stops on a collapsed folder header and Enter expands onto its first card", () => {
-    render(<Sidebar sessions={two} />);
+    render(<Wrapper><Sidebar sessions={two} /></Wrapper>);
 
     const header = document.querySelector<HTMLElement>('[data-nav-key="folder:one"]')!;
     fireEvent.click(header);
@@ -142,7 +154,7 @@ describe("keyboard walk", () => {
   it("Enter on a card opens it, and Tab hands the keyboard to the pane", () => {
     const onSelect = vi.fn();
     const onFocusPane = vi.fn();
-    render(<Sidebar sessions={two} onSelect={onSelect} onFocusPane={onFocusPane} />);
+    render(<Wrapper><Sidebar sessions={two} onSelect={onSelect} onFocusPane={onFocusPane} /></Wrapper>);
 
     fireEvent.keyDown(tree(), { key: "j" });
     fireEvent.keyDown(tree(), { key: "Enter" });
@@ -154,7 +166,7 @@ describe("keyboard walk", () => {
 
   it("previews the session the walk lands on", () => {
     const onPreview = vi.fn();
-    render(<Sidebar sessions={two} onPreview={onPreview} />);
+    render(<Wrapper><Sidebar sessions={two} onPreview={onPreview} /></Wrapper>);
 
     fireEvent.keyDown(tree(), { key: "j" });
     expect(onPreview).toHaveBeenCalledWith("a");
@@ -162,7 +174,7 @@ describe("keyboard walk", () => {
 
   it("x asks to kill the highlighted session and r renames it", () => {
     const onKill = vi.fn();
-    render(<Sidebar sessions={two} onKill={onKill} />);
+    render(<Wrapper><Sidebar sessions={two} onKill={onKill} /></Wrapper>);
 
     fireEvent.keyDown(tree(), { key: "j" });
     fireEvent.keyDown(tree(), { key: "x" });
@@ -178,7 +190,9 @@ describe("context menu", () => {
     const onSpawnSimilar = vi.fn();
     const onKill = vi.fn();
     render(
-      <Sidebar sessions={[session("alpha")]} onSpawnSimilar={onSpawnSimilar} onKill={onKill} />,
+      <Wrapper>
+        <Sidebar sessions={[session("alpha")]} onSpawnSimilar={onSpawnSimilar} onKill={onKill} />
+      </Wrapper>,
     );
 
     fireEvent.contextMenu(card("alpha"));
@@ -191,7 +205,7 @@ describe("context menu", () => {
 
   it("renames in place: Enter commits the field, Escape cancels", () => {
     const onRename = vi.fn();
-    render(<Sidebar sessions={[session("alpha")]} onRename={onRename} />);
+    render(<Wrapper><Sidebar sessions={[session("alpha")]} onRename={onRename} /></Wrapper>);
 
     fireEvent.contextMenu(card("alpha"));
     fireEvent.click(screen.getByText("Rename…"));
@@ -207,7 +221,7 @@ describe("context menu", () => {
 
 describe("search", () => {
   it("filters the tree down to matching sessions", () => {
-    render(<Sidebar sessions={[session("alpha"), session("beta", { cwd: "/home/n/beta" })]} />);
+    render(<Wrapper><Sidebar sessions={[session("alpha"), session("beta", { cwd: "/home/n/beta" })]} /></Wrapper>);
 
     fireEvent.change(screen.getByLabelText("Search sessions"), { target: { value: "beta" } });
 
@@ -219,7 +233,7 @@ describe("search", () => {
 describe("empty state", () => {
   it("offers a spawn when there are no sessions at all", () => {
     const onSpawn = vi.fn();
-    render(<Sidebar sessions={[]} onSpawn={onSpawn} />);
+    render(<Wrapper><Sidebar sessions={[]} onSpawn={onSpawn} /></Wrapper>);
 
     fireEvent.click(screen.getByText("+ Spawn session"));
     expect(onSpawn).toHaveBeenCalled();

web/src/components/sidebar/Sidebar.tsx

@@ -10,8 +10,11 @@ import type { CatalogStore, CatalogStoreApi } from "../../stores/catalogStore.js
 import type { InTheWay, Session } from "../../types.js";
 import { sessionBlockers, sessionName } from "../../types.js";
 import { buildTree, type TreeNode } from "../../tree.js";
-import { KILL_SESSION_EVENT, RENAME_SESSION_EVENT } from "../../uiEvents.js";
+import { KILL_SESSION_EVENT, RENAME_SESSION_EVENT, requestToggleHelp } from "../../uiEvents.js";
 import { ContextMenu, type ContextMenuItem } from "../common/ContextMenu.js";
+import type { DaemonLinkStoreApi, DaemonLinkState } from "../daemon/DaemonLink.js";
+import { formatRelease } from "../daemon/DaemonLink.js";
+import { useTheme, PALETTES, type Palette } from "../../contexts/ThemeContext.js";
 import { FolderNode } from "./FolderNode.js";
 import { KillDialog } from "../dialogs/KillDialog.js";
 import { SessionCard } from "./SessionCard.js";
@@ -43,6 +46,8 @@ export interface SidebarProps {
   /** Tab: hand the keyboard back to the pane. */
   onFocusPane?(): void;
   onHelp?(): void;
+  /** The daemon-link store, for the status indicator in the footer. */
+  linkStore?: DaemonLinkStoreApi;
   /** Overrides the built-in `DELETE /api/sessions/:id` flow (tests, kit). */
   onKill?(session: Session): void;
   /** Overrides the built-in `PATCH /api/sessions/:id` (tests, kit). */
@@ -328,10 +333,25 @@ export function Sidebar(props: SidebarProps) {
           onCancel={() => setKill(null)}
           onConfirm={async () => {
             const { session: s, force } = kill;
+            // Close the dialog immediately and optimistically remove the
+            // session from the sidebar so the operator isn't staring at a
+            // spinner while the daemon tears down the tmux session.
+            setKill(null);
+            const store = props.store;
+            if (store) {
+              const next = new Map(store.getState().sessions);
+              next.delete(s.id);
+              store.setState({ sessions: next });
+            }
             try {
               await killSession(s.id, force);
-              setKill(null);
             } catch (e: unknown) {
+              // Restore the session so it reappears in the sidebar.
+              if (store) {
+                const restored = new Map(store.getState().sessions);
+                restored.set(s.id, s);
+                store.setState({ sessions: restored });
+              }
               // The daemon refuses an unforced kill over a worktree holding
               // unsaved work; that refusal needs its own prompt
               // (docs/WORKTREES.md).
@@ -344,11 +364,16 @@ export function Sidebar(props: SidebarProps) {
                 });
                 return;
               }
-              throw e;
+              // Nothing else we can usefully show — the session is back in
+              // the sidebar and the operator can retry.
             }
           }}
         />
       )}
+      <SidebarFooter
+        onSpawn={() => props.onSpawn?.()}
+        linkStore={props.linkStore}
+      />
     </aside>
   );
 }
@@ -396,3 +421,84 @@ const EMPTY_STORE = {
   setState: () => {},
   subscribe: () => () => {},
 } as unknown as CatalogStoreApi;
+
+// ---------------------------------------------------------------------------
+// Sidebar footer: help, theme toggle, palette picker, status dot, spawn.
+// Mirrors the vanilla catalog.ts footer that the React migration dropped.
+// ---------------------------------------------------------------------------
+
+function SidebarFooter({
+  onSpawn,
+  linkStore,
+}: {
+  onSpawn(): void;
+  linkStore?: DaemonLinkStoreApi;
+}) {
+  const { theme, toggleTheme, palette, setPalette } = useTheme();
+
+  return (
+    <div className="sidebar-footer">
+      <button
+        type="button"
+        className="btn btn-ghost btn-icon help-btn"
+        title="Keyboard shortcuts (?)"
+        aria-label="Keyboard shortcuts"
+        onClick={requestToggleHelp}
+      >
+        ?
+      </button>
+      <button
+        type="button"
+        className="btn btn-ghost btn-icon"
+        title={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
+        aria-label={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
+        onClick={toggleTheme}
+      >
+        {theme === "dark" ? "☀" : "☾"}
+      </button>
+      <select
+        className="palette-select"
+        value={palette}
+        aria-label="Colour palette"
+        onChange={(e) => setPalette(e.currentTarget.value as Palette)}
+      >
+        {PALETTES.map((p) => (
+          <option key={p} value={p}>
+            {p}
+          </option>
+        ))}
+      </select>
+      {linkStore && <StatusDot store={linkStore} />}
+      <button
+        type="button"
+        className="btn btn-primary spawn-btn"
+        title="Spawn form: n — fast-forward spawn: N"
+        onClick={onSpawn}
+      >
+        + Spawn
+      </button>
+    </div>
+  );
+}
+
+/** Daemon status indicator: a coloured dot whose tooltip names the release. */
+function StatusDot({ store }: { store: DaemonLinkStoreApi }) {
+  const state = useStore(store, (s: DaemonLinkState) => s.state);
+  const build = useStore(store, (s: DaemonLinkState) => s.build);
+  const hostname = useStore(store, (s: DaemonLinkState) => s.hostname);
+
+  return (
+    <button
+      type="button"
+      className="status-chip btn btn-ghost btn-icon"
+      data-state={state}
+      aria-label={`Daemon ${state}`}
+    >
+      <span className="status-dot" />
+      <span className="status-tip">
+        <span>{hostname ?? "maestro"}</span>
+        <span className="text-faint">{formatRelease(build)}</span>
+      </span>
+    </button>
+  );
+}

web/src/components/spawn/SpawnForm.tsx

@@ -104,9 +104,11 @@ export interface SpawnFormProps {
   /** Fired whenever any value changes, once the form's initial seed settles. */
   onChange?(values: SpawnFormValues): void;
   onSuccess(session: Session): void;
+  /** When true, hides the built-in submit button (the modal provides its own). */
+  externalSubmit?: boolean;
 }
 
-export function SpawnForm({ seed, onChange, onSuccess }: SpawnFormProps) {
+export function SpawnForm({ seed, onChange, onSuccess, externalSubmit }: SpawnFormProps) {
   const prefill = useRef(seed ?? {}).current;
 
   const formRef = useRef<HTMLFormElement>(null);
@@ -240,7 +242,7 @@ export function SpawnForm({ seed, onChange, onSuccess }: SpawnFormProps) {
 
   const [advancedCollapsed, setAdvancedCollapsed] = useState(true);
   const [error, setError] = useState("");
-  const [submitting, setSubmitting] = useState(false);
+  const [, setSubmitting] = useState(false);
   const [ready, setReady] = useState(false);
 
   const probeTokenRef = useRef(0);
@@ -620,6 +622,7 @@ export function SpawnForm({ seed, onChange, onSuccess }: SpawnFormProps) {
 
   return (
     <form
+      id="spawn-form"
       ref={formRef}
       onSubmit={onSubmit}
       onKeyDown={onFormKeyDown}
@@ -839,15 +842,16 @@ export function SpawnForm({ seed, onChange, onSuccess }: SpawnFormProps) {
       <p role="alert" aria-live="polite" className={`m-0 text-fs-13 text-danger ${error ? "rounded-r-2 bg-danger-tint px-sp-3 py-sp-2" : "min-h-[1.2em]"}`}>
         {error}
       </p>
-      <div className="flex justify-end">
-        <button
-          type="submit"
-          disabled={submitting}
-          className="rounded-r-1 bg-accent px-sp-4 py-sp-2 text-fs-13 font-semibold text-accent-ink disabled:opacity-60"
-        >
-          Spawn
-        </button>
-      </div>
+      {!externalSubmit && (
+        <div className="flex justify-end">
+          <button
+            type="submit"
+            className="btn btn-primary rounded-r-1 px-sp-4 py-sp-1 text-fs-13 font-semibold"
+          >
+            Spawn
+          </button>
+        </div>
+      )}
     </form>
   );
 }

web/src/components/spawn/SpawnModal.tsx

@@ -64,16 +64,23 @@ export function SpawnModal({ seed, onSuccess, onClose }: SpawnModalProps) {
           </button>
         </header>
         <div ref={filterInputRef} className="min-h-0 flex-1 overflow-auto">
-          <SpawnForm seed={seed} onSuccess={handleSuccess} />
+          <SpawnForm seed={seed} onSuccess={handleSuccess} externalSubmit />
         </div>
         <div className="flex justify-end gap-sp-2 border-t border-border p-sp-3">
           <button
             type="button"
-            className="rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-12 text-ink"
+            className="rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-13 text-ink"
             onClick={onClose}
           >
             Cancel
           </button>
+          <button
+            type="submit"
+            form="spawn-form"
+            className="btn btn-primary rounded-r-1 px-sp-4 py-sp-1 text-fs-13 font-semibold"
+          >
+            Spawn
+          </button>
         </div>
       </div>
     </div>,

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

@@ -175,7 +175,7 @@ describe("tool rows and activity groups", () => {
       chunk("agent:2", "agent_text", "the answer"),
     ]);
 
-    const head = screen.getByText("2 tool calls").closest("button")!;
+    const head = screen.getByText(/^2 tool calls/).closest("button")!;
     expect(head.getAttribute("aria-expanded")).toBe("false");
     // The final answer stays outside the group; the intermediate text is in it.
     expect(document.querySelector(".st-tool-group")!.contains(screen.getByText("the answer"))).toBe(false);
@@ -308,7 +308,7 @@ describe("prompt and cancel", () => {
     );
   });
 
-  it("queues a second message while a turn is in flight, and sends it when the turn ends", async () => {
+  it("always POSTs a prompt even while a turn is active (server queues it)", async () => {
     const { socket } = mount();
     snapshot(socket, [], busy);
     fireEvent.change(document.querySelector<HTMLTextAreaElement>(".structured-input")!, {
@@ -316,13 +316,19 @@ describe("prompt and cancel", () => {
     });
     fireEvent.submit(document.querySelector("form.structured-composer")!);
 
-    expect(sendStructuredPrompt).not.toHaveBeenCalled();
-    expect(document.querySelector(".st-row-queued")?.textContent).toBe("next up");
-
-    socket.emit({ type: "reduced_state", state: idle });
     await waitFor(() => expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "next up"));
   });
 
+  it("renders server-side queued prompts from state", () => {
+    const { socket } = mount();
+    snapshot(socket, [], { ...busy, queued_prompts: ["first", "second"] });
+
+    const queued = document.querySelectorAll(".st-row-queued");
+    expect(queued).toHaveLength(2);
+    expect(queued[0].textContent).toBe("first");
+    expect(queued[1].textContent).toBe("second");
+  });
+
   it("hands a failed send's draft back to the operator", async () => {
     vi.mocked(sendStructuredPrompt).mockRejectedValueOnce(new Error("boom"));
     const { socket } = mount();

web/src/components/structured/StructuredPane.tsx

@@ -48,11 +48,6 @@ import "./structured.css";
  *  count as following. */
 const FOLLOW_BOTTOM_THRESHOLD_PX = 64;
 
-interface QueuedPrompt {
-  text: string;
-  attachments: File[];
-}
-
 export interface StructuredPaneProps {
   sessionId: Uuid;
   /** Grabs the composer once mounted. A sidebar preview passes `false`. */
@@ -85,7 +80,6 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
   const [expandedGroups, setExpandedGroups] = useState<ReadonlySet<string>>(new Set());
   const [draft, setDraft] = useState("");
   const [attachments, setAttachments] = useState<File[]>([]);
-  const [queue, setQueue] = useState<QueuedPrompt[]>([]);
   const [uploading, setUploading] = useState(false);
   const [configBusy, setConfigBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -100,7 +94,6 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
   const submission = useRef(0);
   const accepted = useRef<{ generation: number; socketGeneration: number } | null>(null);
   const optimisticStart = useRef<number | null>(null);
-  const promptPending = useRef(false);
   const [awaitingBegin, setAwaitingBegin] = useState<number | null>(null);
 
   useImperativeHandle(
@@ -166,7 +159,7 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
     const el = scrollRef.current;
     if (!el || !followingBottom.current) return;
     el.scrollTop = Math.max(0, el.scrollHeight - el.clientHeight);
-  }, [items, active, queue]);
+  }, [items, active, state.queued_prompts]);
 
   useEffect(() => {
     if (!active) return;
@@ -207,7 +200,7 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
       setAwaitingBegin(generation);
       optimisticStart.current = Date.now();
       accepted.current = null;
-      promptPending.current = true;
+
       setUploading(files.length > 0);
       setDraft("");
       setError(null);
@@ -224,7 +217,6 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
 
       void send().then(
         () => {
-          promptPending.current = false;
           if (generation !== submission.current) return;
           setUploading(false);
           setAttachments((current) => (current === files ? [] : current));
@@ -235,7 +227,6 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
           if (socketGeneration > submissionSocket) session.reconnect();
         },
         (e: unknown) => {
-          promptPending.current = false;
           if (generation !== submission.current) return;
           setAwaitingBegin((current) => (current === generation ? null : current));
           optimisticStart.current = null;
@@ -251,24 +242,10 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
     [sessionId, socketGeneration, session],
   );
 
-  // A queued message goes out as soon as the projected turn is idle — the
-  // daemon answers a second prompt `409 turn_in_flight`, so the queue is
-  // client-local (docs/STRUCTURED-VIEW.md).
-  useEffect(() => {
-    if (active || promptPending.current || queue.length === 0) return;
-    const [next, ...rest] = queue;
-    setQueue(rest);
-    dispatchPrompt(next.text, next.attachments);
-  }, [active, queue, dispatchPrompt]);
-
+  // The server accepts prompts at any time: if a turn is active the prompt is
+  // queued server-side and drained when the turn completes.  The client always
+  // POSTs immediately — no local queue.
   const submit = (text: string, files: File[]) => {
-    if (active || queue.length > 0) {
-      setQueue((current) => [...current, { text, attachments: files }]);
-      setAttachments([]);
-      setDraft("");
-      setError(null);
-      return;
-    }
     dispatchPrompt(text, files);
   };
 
@@ -354,6 +331,8 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
                     key={item.id}
                     id={item.id}
                     toolCount={item.group.toolCount}
+                    lastToolLabel={item.group.lastToolLabel}
+                    lastToolArg={item.group.lastToolArg}
                     expanded={expandedGroups.has(item.id)}
                     onExpandedChange={(expanded) => setGroupExpanded(item.id, expanded)}
                   >
@@ -361,10 +340,10 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
                   </ToolGroup>
                 ),
               )}
-              {queue.map((queued, index) => (
+              {(state.queued_prompts ?? []).map((text, index) => (
                 <div key={`queued-${index}`} className="st-row st-row-queued">
                   <div className="st-body">
-                    <div className="st-user-text">{queued.text}</div>
+                    <div className="st-user-text">{text}</div>
                   </div>
                 </div>
               ))}

web/src/components/structured/ToolGroup.tsx

@@ -1,19 +1,27 @@
 // A turn's collapsed activity block: two or more tool rows after the same
 // `User` row, plus the narration absorbed between them. The header counts tool
-// rows only (docs/STRUCTURED-VIEW.md); opening it reveals tools and text in
-// chronological order.
+// rows only (docs/STRUCTURED-VIEW.md) and shows the last/current tool label so
+// the operator sees activity at a glance without expanding. Opening it reveals
+// tools and text in chronological order.
 
 import type { ReactNode } from "react";
 
 export interface ToolGroupProps {
   id: string;
   toolCount: number;
+  /** Label of the last (or running) tool, e.g. "Execute". */
+  lastToolLabel: string;
+  /** Argument of the last tool, e.g. "`git status`". */
+  lastToolArg: string;
   expanded: boolean;
   onExpandedChange(expanded: boolean): void;
   children: ReactNode;
 }
 
-export function ToolGroup({ id, toolCount, expanded, onExpandedChange, children }: ToolGroupProps) {
+export function ToolGroup({ id, toolCount, lastToolLabel, lastToolArg, expanded, onExpandedChange, children }: ToolGroupProps) {
+  const summary = lastToolArg
+    ? `${toolCount} tool calls · ${lastToolLabel} \u2018${lastToolArg}\u2019`
+    : `${toolCount} tool calls`;
   return (
     <div className="st-tool-group" data-tool-group-id={id}>
       <button
@@ -25,7 +33,7 @@ export function ToolGroup({ id, toolCount, expanded, onExpandedChange, children
         <span className="st-tool-group-glyph" aria-hidden="true">
           ›
         </span>
-        <span className="st-tool-group-title">{`${toolCount} tool calls`}</span>
+        <span className="st-tool-group-title">{summary}</span>
       </button>
       <div
         className={

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

@@ -115,8 +115,8 @@ describe("activity grouping", () => {
   it("groups a turn's tools once there are two of them", () => {
     const rows = [text("user:1", "user", "go"), tool("tool:1"), tool("tool:2")];
     const groups = activityGroupsByTurn(rows, null, false);
-    expect([...groups.keys()]).toEqual(["turn:user:1"]);
-    expect(groups.get("turn:user:1")).toMatchObject({ toolCount: 2 });
+    expect([...groups.keys()]).toEqual(["turn:user:1:0"]);
+    expect(groups.get("turn:user:1:0")).toMatchObject({ toolCount: 2 });
   });
 
   it("leaves a single tool call standalone", () => {
@@ -124,7 +124,7 @@ describe("activity grouping", () => {
     expect(activityGroupsByTurn(rows, null, false).size).toBe(0);
   });
 
-  it("absorbs intermediate narration but keeps the final answer outside", () => {
+  it("splits tools into separate runs when text appears between them", () => {
     const rows = [
       text("user:1", "user", "go"),
       tool("tool:1"),
@@ -132,12 +132,26 @@ describe("activity grouping", () => {
       tool("tool:2"),
       text("agent:2", "agent_text", "done"),
     ];
-    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
-    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "agent:1", "tool:2"]);
-    expect(group.toolCount).toBe(2);
+    // Each run has only one tool, so neither qualifies for grouping.
+    expect(activityGroupsByTurn(rows, null, false).size).toBe(0);
   });
 
-  it("keeps the newest thought outside while the turn is still live", () => {
+  it("groups contiguous tools separated by text into distinct groups", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      tool("tool:2"),
+      text("agent:1", "agent_text", "working"),
+      tool("tool:3"),
+      tool("tool:4"),
+    ];
+    const groups = activityGroupsByTurn(rows, null, false);
+    expect([...groups.keys()]).toEqual(["turn:user:1:0", "turn:user:1:1"]);
+    expect(groups.get("turn:user:1:0")!.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2"]);
+    expect(groups.get("turn:user:1:1")!.rows.map((r) => r.id)).toEqual(["tool:3", "tool:4"]);
+  });
+
+  it("keeps thoughts outside the group as standalone items", () => {
     const rows = [
       text("user:1", "user", "go"),
       tool("tool:1"),
@@ -145,10 +159,19 @@ describe("activity grouping", () => {
       text("thought:1", "agent_thought", "hmm"),
       text("thought:2", "agent_thought", "aha"),
     ];
-    const live = activityGroupsByTurn(rows, null, true).get("turn:user:1")!;
-    expect(live.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1"]);
-    const ended = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
-    expect(ended.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1", "thought:2"]);
+    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1:0")!;
+    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2"]);
+  });
+
+  it("tracks the last tool's label and argument for the collapsed header", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      row("tool:1", "tool_call", { title: "Read(src/main.ts)", status: "completed" }),
+      row("tool:2", "tool_call", { title: "Execute(git status)", kind: "execute", status: "completed" }),
+    ];
+    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1:0")!;
+    expect(group.lastToolLabel).toBe("Execute");
+    expect(group.lastToolArg).toBe("git status");
   });
 
   it("absorbs a resolved approval, never the pending one", () => {
@@ -160,7 +183,7 @@ describe("activity grouping", () => {
       row("approval:2", "approval"),
       tool("tool:3"),
     ];
-    const group = activityGroupsByTurn(rows, "approval:2", false).get("turn:user:1")!;
+    const group = activityGroupsByTurn(rows, "approval:2", false).get("turn:user:1:0")!;
     expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "approval:1", "tool:2", "tool:3"]);
   });
 });
@@ -171,11 +194,31 @@ describe("transcript render list", () => {
     const items = transcriptItems(rows, null, false);
     expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual([
       "user:1",
-      "turn:user:1",
+      "turn:user:1:0",
       "agent:1",
     ]);
   });
 
+  it("interleaves groups and text in timeline order", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      tool("tool:2"),
+      text("agent:1", "agent_text", "working"),
+      tool("tool:3"),
+      tool("tool:4"),
+      text("agent:2", "agent_text", "done"),
+    ];
+    const items = transcriptItems(rows, null, false);
+    expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual([
+      "user:1",
+      "turn:user:1:0",
+      "agent:1",
+      "turn:user:1:1",
+      "agent:2",
+    ]);
+  });
+
   it("omits plan rows, state-only notices and standalone resolved approvals", () => {
     const rows = [
       text("user:1", "user", "go"),

web/src/components/structured/model.ts

@@ -144,77 +144,79 @@ export function turnIsActive(state: ReducedState): boolean {
 }
 
 export interface ActivityGroup {
-  /** Header label count — tool rows only, never absorbed text. */
+  /** Header label count — tool rows only. */
   toolCount: number;
-  /** Tools plus absorbed intermediate text/approvals, in transcript order. */
+  /** Tool rows and resolved approvals, in transcript order. Text/thought
+   *  rows stay outside the group as standalone transcript items. */
   rows: TranscriptRow[];
+  /** `splitToolTitle` of the last tool row — the collapsed header shows it. */
+  lastToolLabel: string;
+  lastToolArg: string;
 }
 
 /**
- * Group tool rows (and intermediate agent text / resolved approvals between
- * them) by turn. An agent_text/agent_thought row is "intermediate" when a tool
- * row follows it in the same turn — it gets absorbed into the group so the
- * collapsed block preserves chronological order. Resolved approval rows (not
- * the currently pending one) are absorbed the same way. The *last* agent text
- * with no subsequent tool stays standalone (the prominent final answer).
+ * Group contiguous tool rows (and resolved approvals between them) into
+ * collapsible blocks. An `AgentText` or `AgentThought` row between tools
+ * splits the run — each contiguous stretch of tools becomes its own group,
+ * so the timeline reads text → group → text → group rather than lumping
+ * every tool in a turn into one box.
  *
- * Returns groups keyed by `turn:<userId>`.
+ * A group must contain at least two tools to qualify; a single tool stays
+ * standalone. Returns groups keyed by `turn:<userId>:<seq>`.
  */
 export function activityGroupsByTurn(
   rows: TranscriptRow[],
   pendingApprovalId: string | null,
-  turnActive: boolean,
+  _turnActive: boolean,
 ): Map<string, ActivityGroup> {
-  // First: count tools per turn to know which turns qualify for grouping.
-  const toolCounts = new Map<string, number>();
-  let turnId = "before-first-message";
-  for (const row of rows) {
-    if (row.kind === "user") turnId = row.id;
-    if (row.kind !== "tool_call" && row.kind !== "tool_diff") continue;
-    const gid = `turn:${turnId}`;
-    toolCounts.set(gid, (toolCounts.get(gid) ?? 0) + 1);
-  }
-  // Second: build groups with interleaved text for turns with 2+ tools.
   const groups = new Map<string, ActivityGroup>();
-  turnId = "before-first-message";
-  // Pending rows that might be intermediate (not yet confirmed by a following
-  // tool). If no tool follows, they stay standalone.
-  let pending: TranscriptRow[] = [];
-  let currentGid = `turn:${turnId}`;
+  let turnId = "before-first-message";
+  let runSeq = 0;
+  let runTools: TranscriptRow[] = [];
+  let runPending: TranscriptRow[] = [];
+
+  const flushRun = () => {
+    if (runTools.length >= 2) {
+      const gid = `turn:${turnId}:${runSeq}`;
+      const tool = (runTools[runTools.length - 1].data ?? {}) as { title?: string; name?: string | null; kind?: string };
+      const { label, arg } = splitToolTitle(tool.title, tool.name ?? undefined, tool.kind);
+      groups.set(gid, {
+        toolCount: runTools.length,
+        rows: [...runTools],
+        lastToolLabel: label,
+        lastToolArg: arg,
+      });
+      runSeq++;
+    }
+    runTools = [];
+    runPending = [];
+  };
+
   for (const row of rows) {
     if (row.kind === "user") {
+      flushRun();
       turnId = row.id;
-      currentGid = `turn:${turnId}`;
-      pending = [];
+      runSeq = 0;
+      continue;
+    }
+    // Text and thought rows break the current tool run.
+    if (row.kind === "agent_text" || row.kind === "agent_thought") {
+      flushRun();
       continue;
     }
-    const count = toolCounts.get(currentGid) ?? 0;
-    if (count < 2) continue;
-    const isIntermediateText = row.kind === "agent_text" || row.kind === "agent_thought";
     const isResolvedApproval = row.kind === "approval" && row.id !== pendingApprovalId;
-    if (isIntermediateText || isResolvedApproval) {
-      pending.push(row);
+    if (isResolvedApproval) {
+      runPending.push(row);
       continue;
     }
     if (row.kind === "tool_call" || row.kind === "tool_diff") {
-      const group = groups.get(currentGid) ?? { toolCount: count, rows: [] };
-      // Flush any pending rows — a tool follows, so they're intermediate.
-      group.rows.push(...pending);
-      pending = [];
-      group.rows.push(row);
-      groups.set(currentGid, group);
+      // Flush any pending resolved approvals into the run before this tool.
+      runTools.push(...runPending);
+      runPending = [];
+      runTools.push(row);
     }
   }
-  // A final agent text is the answer, so it stays outside. Thought rows are
-  // working commentary, though: when a turn already has a disclosure they
-  // belong with its activity even if the next tool call has not arrived yet.
-  // While the turn is still live the most recent one stays outside as visible
-  // narration (docs/STRUCTURED-VIEW.md), and is absorbed when the turn ends.
-  const lastGroup = groups.get(currentGid);
-  if (lastGroup && pending.length > 0 && pending.every((row) => row.kind === "agent_thought")) {
-    const absorb = turnActive ? pending.slice(0, -1) : pending;
-    lastGroup.rows.push(...absorb);
-  }
+  flushRun();
 
   return groups;
 }
@@ -226,10 +228,10 @@ export type TranscriptItem =
   | { type: "group"; id: string; group: ActivityGroup };
 
 /**
- * The transcript in render order: rows, with each turn's tool activity folded
- * into a single group item where one exists. Resolved approvals not absorbed
- * into a group are dropped — the tool row itself already identifies the
- * action. `plan` rows and state-only notices are dropped too (both clients
+ * The transcript in render order: rows, with each contiguous tool stretch
+ * folded into a single group item where one exists. Resolved approvals not
+ * absorbed into a group are dropped — the tool row itself already identifies
+ * the action. `plan` rows and state-only notices are dropped too (both clients
  * omit `Plan` from the transcript). A turn footer only survives as the final
  * item, so old footers stop reading like transcript content.
  */
@@ -239,21 +241,19 @@ export function transcriptItems(
   turnActive: boolean,
 ): TranscriptItem[] {
   const groups = activityGroupsByTurn(rows, pendingApprovalId, turnActive);
-  const grouped = new Set<string>();
-  for (const group of groups.values()) for (const row of group.rows) grouped.add(row.id);
+  // Reverse index: row id → group id that contains it.
+  const rowToGroup = new Map<string, string>();
+  for (const [groupId, group] of groups) for (const r of group.rows) rowToGroup.set(r.id, groupId);
 
   const items: TranscriptItem[] = [];
-  let turnId = "before-first-message";
   const emitted = new Set<string>();
   for (const row of rows) {
-    if (row.kind === "user") turnId = row.id;
-    const groupId = `turn:${turnId}`;
-    const group = groups.get(groupId);
-    if (group && grouped.has(row.id)) {
+    const groupId = rowToGroup.get(row.id);
+    if (groupId !== undefined) {
       // The group renders once, at its first member's position.
       if (!emitted.has(groupId)) {
         emitted.add(groupId);
-        items.push({ type: "group", id: groupId, group });
+        items.push({ type: "group", id: groupId, group: groups.get(groupId)! });
       }
       continue;
     }