Merge branch 'feat/w80-voice-failed-status-judgment' into android

fix(w80): 让「画不画语音形态」只剩「键在且 status 不是 failed」两条判据
后端 M57-M59 预告（devdocs/02 第 1255/1260 行我们的答复）：`voice` 键在不再等于「这是一段能播的声音」。合成降级 / 入站转写失败的行 `status = "failed"`，正文是一句话， `fallbackReason` 里给出降级原因——按老判据会被画成一个点下去必然播不了的语音气泡。判据拆成两问，各自落在一处（domain/chat/VoiceMessage.kt）： - `hasVoice` = `voice` 键存在 —— 「这条**来自**一段声音」； - `isPlayableVoice` = `status != "failed"` —— 认不出的 status 一律当可播（fail-open：多画一枚语音形态最坏是点了播不出来，有既有失败文案兜着；反方向会把真有副本的语音静默吞成纯文字，用户再也点不到）； - `isVoiceMessage` = 两者相与 —— 「画不画语音形态」。 failed 行改画「正文 + 一行灰色小标」：`voiceFallbackNote` 给固定前半句 + 服务端 `fallbackReason` **原样**（不猜闭集、不做映射——取值集合后端尚未定稿；缺席/空白时退化成固定那一句，不白屏）。新组件 `VoiceFallbackNote` 用 footnote2 + onSurfaceVariantSummary，与语音形态旁边那几句脚注同一档。 `isContentlessUserMessage` 挂 `hasVoice` 而**不**是 `isVoiceMessage`：failed 行虽没有语音形态，但有正文和那行小标，同样不是「什么都没有」——判错了屏幕上会多一句假的「内容没有被传过来」。`messageTimeCarrier` 同理按 `hasVoice` 挑落脚点。 DTO 上补第八个键 `fallbackReason`（只在 failed 时有，`explicitNulls = false` 时不写出），所以转写成功的行键集仍是原来七个。验证：`assembleDebug` + `testDebugUnitTest` 全绿，142 个测试文件 / 1766 个用例 / 0 失败（基线 1755，新增 11 条；VoiceMessageTest 20、VoiceDtoTest 13、WsEventPersistedVoiceTest 7）。
2026-10-27 21:33:01 +08:00 · 2026-10-27 21:22:28 +08:00 · 2026-10-27 00:30:44 +08:00 · 2026-10-27 00:21:20 +08:00 · 2026-10-26 23:59:21 +08:00 · 2026-10-26 23:58:41 +08:00
193 changed files with 32340 additions and 3509 deletions
@@ -10,3 +10,9 @@ local.properties
 captures/
 .externalNativeBuild/
 .cxx/
+# 主人从手机丢进仓库根当素材用的图（例如换图标用的原图）——只用不存，绝不进仓库
+/IMG_*.png
+# 开发文档 —— **主人 2026-10-07 明确指令：整个文件夹禁止进入远程仓库**。
+# 它只在本机磁盘上（前后端协同留言板、进度交接、设计拆解都在里面），靠磁盘本身交接。
+# 凭据同样绝不写进去（那类东西在 dev-secrets.local.md）。
+devdocs/
@@ -1,6 +1,40 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">

+    <!--
+        「后台保持连接」用到的三个权限（设置页那个开关，默认关）：
+
+        - FOREGROUND_SERVICE：起前台服务本身。
+        - FOREGROUND_SERVICE_DATA_SYNC：前台服务的类型权限（API 34+ 与 android:foregroundServiceType
+          配合）。选 dataSync 是因为这条服务保的是一条**长连接**——保持与后端的实时同步，
+          既不是 mediaPlayback 也不是 location，声明成别的类型才是说谎。
+        - POST_NOTIFICATIONS：前台服务必须有一条通知，而 minSdk 33 ⇒ 它恒是运行时权限。
+          用户拒绝时开关**打不开**（判据见 core.keepalive.shouldKeepAliveRun），本端不偷偷跑。
+    -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <!--
+        「用户按住麦克风说话」用的麦克风权限（契约 v0.96 §3.15 ①）。
+
+        它是**运行时权限**（minSdk 33 ⇒ 恒是）：本端只在用户**第一次点麦克风**时申请，
+        被拒之后不再重复申请（Android 不会二次弹框，重复申请等于点了没反应），
+        改由真机设置页授权——文案见 `ui.chat.VOICE_PERMISSION_DENIED_MESSAGE`。
+        没有这个权限时录音机直接起不来，本端如实说一句，绝不假装在录。
+    -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+
+    <!--
+        联网权限**显式**声明，不靠任何传递依赖。
+
+        事实（W52K 跑 `:app:processReleaseMainManifest` 核过）：本端一直能联网，是靠
+        `com.squareup.okhttp3:okhttp-android:5.5.0` 的清单把 `INTERNET` 合并进来的；而 debug 那边
+        AGP 也注入同一份 ⇒ **本地怎么试都看不出来**。一旦换掉/排除那个依赖，release 会**静默失去**
+        网络权限（不报错、只是所有请求都失败）。显式写在这里，从此与第三方清单无关。
+    -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
    <application
        android:name=".app.CyreneApplication"
        android:allowBackup="false"
@@ -65,6 +99,21 @@
                android:resource="@xml/file_paths" />
        </provider>

+        <!--
+            「后台保持连接」的前台服务（设置页开关控制，默认关）。
+
+            exported="false"：它没有任何对外接口（onBind 返回 null），只由本进程 start/stop。
+
+            foregroundServiceType="dataSync"：这条服务的职责是让进程活着，从而让那条**进程级共享**
+            的实时连接（AppContainer.chatSocket）不被 Android 12+ 的 cached 进程冻结掐断——
+            语义上就是「后台数据同步」。它不自己去建立 / 关闭任何连接，连接的主人是
+            SessionsViewModel（见 KeepAliveService 的类注释）。
+        -->
+        <service
+            android:name=".core.keepalive.KeepAliveService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+
    </application>

 </manifest>
@@ -3,20 +3,28 @@ package top.yeij.cyrene.app
 import android.content.Context
 import top.yeij.cyrene.core.auth.AuthManager
 import top.yeij.cyrene.core.auth.SessionStore
+import top.yeij.cyrene.core.notify.AppPresence
+import top.yeij.cyrene.core.notify.ProactiveNotifier
+import top.yeij.cyrene.core.notify.postProactiveNotification
 import top.yeij.cyrene.core.prefs.AppSettings
 import top.yeij.cyrene.core.prefs.EnumPreferences
 import top.yeij.cyrene.core.prefs.SessionPreferences
+import top.yeij.cyrene.core.session.ChatSessionSlots
+import top.yeij.cyrene.core.session.GoneSessions
 import top.yeij.cyrene.data.api.AdminApi
 import top.yeij.cyrene.data.api.ApiClientFactory
 import top.yeij.cyrene.data.api.ChatApi
 import top.yeij.cyrene.data.api.DocumentsApi
+import top.yeij.cyrene.data.api.MediaApi
 import top.yeij.cyrene.data.api.MetaApi
 import top.yeij.cyrene.data.api.PersonaApi
 import top.yeij.cyrene.data.api.SessionsApi
 import top.yeij.cyrene.data.api.UploadApi
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
 import top.yeij.cyrene.data.repository.AdminRepository
 import top.yeij.cyrene.data.repository.ChatRepository
 import top.yeij.cyrene.data.repository.DocumentRepository
+import top.yeij.cyrene.data.repository.MediaRepository
 import top.yeij.cyrene.data.repository.MessageRepository
 import top.yeij.cyrene.data.repository.MetaRepository
 import top.yeij.cyrene.data.repository.PersonaRepository
@@ -36,6 +44,60 @@ class AppContainer(context: Context) {
    val appSettings: AppSettings = AppSettings(context.applicationContext)
    val authManager: AuthManager = AuthManager(sessionStore)

+    /**
+     * 本端已知「服务端没有这个会话」的那几个 id（**进程级**，与 [chatSocket] 同一层）。
+     *
+     * 跨两个 VM 的唯一共享面：写它的是 `SessionsViewModel`（本端唯一的删除入口），读它的是
+     * **每一个还活着的** `ChatViewModel`（它们在 [chatSessionSlots] 没回收之前都活着、都订阅着
+     * 那条共享连接）。它拦下的是那一轮注定 `404 session_not_found` 的补拉 —— 理由与
+     * 「为什么不持久化」见 [GoneSessions] 的类注释。
+     */
+    val goneSessions: GoneSessions = GoneSessions()
+
+    /**
+     * 「App 在不在前台」「聊天页显示着哪个会话」（**进程级**，与 [chatSocket] / [goneSessions]
+     * 同一层）：写它的是 `MainActivity`（`onStart` / `onStop`）与 `ChatScreen`（组合进出），
+     * 读它的是 [proactiveNotifier]。为什么不引 `ProcessLifecycleOwner` 见 [AppPresence] 的类注释。
+     */
+    val appPresence: AppPresence = AppPresence()
+
+    /** 「点通知进来要看主会话」那笔待落地的意图（写：`MainActivity`，消费：`ChatHomeScreen`）。 */
+    val proactiveTapIntake: ProactiveTapIntake = ProactiveTapIntake()
+
+    /**
+     * 「她主动说的话」的通知通路（W53N）：判据、去重与落地都在里面，Android 那一步从这里注入。
+     *
+     * 它**不订阅任何东西**（帧由 [proactiveFrameIntake] 喂进来），因此与连接的所有权完全无关
+     * ——本端那条共享连接的生死仍然只在登录态那一处表达。
+     */
+    val proactiveNotifier: ProactiveNotifier = ProactiveNotifier(
+        presence = appPresence,
+        post = { text, notificationId ->
+            // 「免打扰」**每次现读**（`AppSettings.current` 是那份热副本）：开关一改，下一条通知就
+            // 换一条渠道，不必重启 App。为什么不能在这里挂起读一次、以及那个毫秒级窗口是怎么回事，
+            // 都写在 `AppSettings.current` 的 KDoc 里。
+            postProactiveNotification(
+                context = appContext,
+                text = text,
+                notificationId = notificationId,
+                quiet = appSettings.current.value.proactiveQuiet,
+            )
+        },
+    )
+
+    /**
+     * 会话槽位账本（**进程级**）：本端为一个账号留着的聊天状态，一格一份 `ViewModelStore`。
+     *
+     * 它把 S4 那笔技术债收在一处：`ChatViewModel` 是按会话建的，此前访问过多少个会话就有多少份
+     * 常驻内存（消息列表含内联 base64 图片）与多少份对共享连接的订阅；现在最多留
+     * [top.yeij.cyrene.core.session.CHAT_SESSION_SLOT_KEEP] 格，超出的按「最后一次成为当前会话」
+     * 从旧到新交出去（判据是纯函数 `core.session.chatSessionEvictions`）。
+     *
+     * 与 [goneSessions] 同一层、同一批读者（写它的是 `ChatScreen` 与 `SessionsViewModel`）。
+     * 主会话 id 在这里注入，是为了让 `core.session` 那两层不认识 `ui.chat` 的那个常量。
+     */
+    val chatSessionSlots: ChatSessionSlots = ChatSessionSlots(SessionSummaryDto.MAIN_SESSION_ID)
+
    private var cachedBaseUrl: String? = null
    private var cachedSessionsApi: SessionsApi? = null

@@ -136,6 +198,34 @@ class AppContainer(context: Context) {

    val documentRepository: DocumentRepository get() = DocumentRepository(documentsApi)

+    private var cachedMediaApi: MediaApi? = null
+    private var cachedMediaBaseUrl: String? = null
+
+    /**
+     * 语音副本端点（`GET /api/v1/media/{name}`，契约 §1.2 **U19**）；与 [documentsApi] **同一套门**：
+     * `owner|admin` **必须 Bearer**（与图片读侧「名字即凭据」刻意相反 —— 语音是私密内容）。
+     *
+     * 同样与 [chatApi] 同源（同一 baseUrl、同一 token/401 处理）：`voice.url` 是**服务端相对路径**，
+     * 只有落在**同一台后端**上才取得到那份副本。
+     */
+    val mediaApi: MediaApi
+        get() {
+            val baseUrl = authManager.currentBaseUrl
+            val cached = cachedMediaApi
+            if (cached != null && cachedMediaBaseUrl == baseUrl) return cached
+            val created = ApiClientFactory.create(
+                baseUrl = baseUrl,
+                service = MediaApi::class.java,
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
+            )
+            cachedMediaBaseUrl = baseUrl
+            cachedMediaApi = created
+            return created
+        }
+
+    val mediaRepository: MediaRepository get() = MediaRepository(mediaApi)
+
    private var cachedAdminApi: AdminApi? = null
    private var cachedAdminBaseUrl: String? = null

@@ -202,10 +292,57 @@ class AppContainer(context: Context) {

    val personaRepository: PersonaRepository get() = PersonaRepository(personaApi)

-    fun createChatSocket(): ChatSocket = ChatSocket(
-        baseUrlProvider = { authManager.currentBaseUrl },
-        tokenProvider = authManager::currentToken,
-        onAuthRecover = authManager::recoverSocketAuth,
-        onAuthFailed = authManager::onSessionExpired,
+    /**
+     * 进程内**唯一**的实时通道连接（`GET /ws/chat`）：所有需要收下行帧的 ViewModel 共用这一条。
+     *
+     * ## 为什么可以共享（不是「省点资源」，是**逐帧等价**）
+     * 服务端是**广播**：下行帧发给**每一条**已认证连接、**不按会话订阅**（见 [ChatSocket] 类注释
+     * 「会话归属」）。于是改前「N 条连接，每条都收到全部帧 ⇒ 每个 VM 都收到全部帧 ⇒ 各 VM 靠
+     * [top.yeij.cyrene.data.ws.WsEvent.isForSession] 收敛到自己的会话」与改后「一条连接收到全部帧
+     * ⇒ **每个 VM 仍然收到全部帧**」是**同一个语义**：帧集合逐帧相同，过滤与事件分支一个字都不用改。
+     * 这次变的只是「连接有几条」，不是「帧怎么走」。
+     *
+     * ## 为什么必须唯一
+     * 每个 `ChatSocket` 都自带一个 `OkHttpClient`（各自的连接池 / ping / 重连循环）。改前
+     * `ChatViewModel`（**每个会话一个 VM**）、[top.yeij.cyrene.ui.sessions.SessionsViewModel]、
+     * [top.yeij.cyrene.ui.admin.AdminViewModel] 各自建了一条（`ChatViewModel.start()`、
+     * 两个 VM 的 init）⇒ 访问 N 个会话 = N+2 条连接、N+2 个 `OkHttpClient`。现在这里就是唯一的
+     * 持有者（`by lazy`，只此一份），调用方只订阅 [ChatSocket.events] / [ChatSocket.state]。
+     *
+     * **每个会话那个 VM 常驻的那一半**（S4）由 [chatSessionSlots] 收：本端最多留
+     * [top.yeij.cyrene.core.session.CHAT_SESSION_SLOT_KEEP] 格，多出来的整格交出去。这一条与
+     * 本段说的是**两件事**：连接只有一条，而订阅它的 VM 有几格 —— 前者与本类同一层，后者在账本里。
+     *
+     * ## 开与关只有一个主人
+     * [top.yeij.cyrene.ui.sessions.SessionsViewModel] 的登录态订阅：`LoggedIn → connect()`、
+     * `LoggedOut → close()`（为什么是它，见那个类的 KDoc）。`connect()` 幂等，baseUrl / token 都是
+     * 每次重连现读 ⇒ 登出重登、换账号**不需要**重建本实例。**任何 ViewModel 都不许关它**——
+     * 细节与理由写在 [ChatSocket.close]。
+     */
+    val chatSocket: ChatSocket by lazy {
+        ChatSocket(
+            baseUrlProvider = { authManager.currentBaseUrl },
+            tokenProvider = authManager::currentToken,
+            onAuthRecover = authManager::recoverSocketAuth,
+            onAuthFailed = authManager::onSessionExpired,
+        )
+    }
+
+    /**
+     * 「她主动说的话 ⇒ 弹通知」那条通路在**帧这一层的消费点**（W57，**进程级**）：把 [chatSocket]
+     * 上那两种帧交给 [proactiveNotifier]。构造即订阅，此后与进程同寿（没有 start / stop 的理由
+     * 见 [ProactiveFrameIntake] 的类注释）。
+     *
+     * 改前这份订阅挂在 `SessionsViewModel` 的 `viewModelScope` 上（它随 Activity 一起结束），于是
+     * 「从最近任务划掉 App、进程还被 `KeepAliveService` 撑着」那一档：帧到了 [chatSocket]、
+     * 一个订阅者都没有，而 `events` 是 `replay = 0` 的 `SharedFlow` ⇒ 当场丢掉，通知永远不弹。
+     *
+     * 声明在这里（类的末尾）有一个顺序上的理由：它要同时用到 [proactiveNotifier] 与 [chatSocket]，
+     * 而 [chatSocket] 是本类最后声明的那个（Kotlin 按声明顺序初始化）。读 [ChatSocket.events] 会把
+     * 那条连接对象提前建出来——本容器与它同时诞生、同时活着，这一步没有任何代价。
+     */
+    val proactiveFrameIntake: ProactiveFrameIntake = ProactiveFrameIntake(
+        events = chatSocket.events,
+        notifier = proactiveNotifier,
    )
 }
@@ -5,8 +5,14 @@ import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.platform.LocalContext
 import kotlinx.coroutines.launch
 import top.yeij.cyrene.core.auth.SessionState
+import top.yeij.cyrene.core.keepalive.KeepAliveAction
+import top.yeij.cyrene.core.keepalive.KeepAliveService
+import top.yeij.cyrene.core.keepalive.keepAliveAction
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+import top.yeij.cyrene.core.prefs.LocalAppPrefs
 import top.yeij.cyrene.ui.chat.ChatHomeScreen
 import top.yeij.cyrene.ui.common.LoadingScreen
 import top.yeij.cyrene.ui.login.LoginScreen
@@ -14,12 +20,44 @@ import top.yeij.cyrene.ui.login.LoginScreen
@Composable
 fun CyreneApp(container: AppContainer) {
    val state by container.authManager.state.collectAsState()
+    val prefs = LocalAppPrefs.current
+    val context = LocalContext.current
    val scope = rememberCoroutineScope()

    LaunchedEffect(Unit) {
        container.authManager.bootstrap()
    }

+    /*
+     * 后台保持连接：**全 App 唯一一处**决定那条前台服务的起停。
+     *
+     * 这里是合适的位置，因为它是「开关（App 偏好）与登录态碰头」的最小汇合点：偏好由
+     * CyreneRoot 读出来经 LocalAppPrefs 下发，登录态本来就订阅在本函数里。判据本身是纯函数
+     * （core.keepalive.keepAliveAction），两种状态各自变化都会把这一次重跑一遍，于是
+     * 「启动时开关开着且已登录 ⇒ 服务在跑」「登出 ⇒ 停」「开关关掉 ⇒ 停」都不用另外写路径。
+     *
+     * 权限每次**现读**（不缓存在 remember 里）：会话自举完成那一刻读到的就是当下的真实授权，
+     * 而授权变化只有两条路——本端刚申请完（设置页那次写入会连带把这里重跑一遍）、或用户在系统
+     * 设置里改过（下次启动必然重跑）。
+     */
+    // ⚠️ key 里必须有「回到前台」这一位（W53S 登记的那一格）：通知权限是**现读**的，而用户在系统
+    // 设置里授权后回到 App 时，只有这个状态会变 —— 少了它，UI 会说「已开」而服务其实没起。
+    val appInForeground by container.appPresence.appInForegroundFlow.collectAsState()
+    LaunchedEffect(prefs.keepAliveEnabled, state, appInForeground) {
+        when (
+            keepAliveAction(
+                enabled = prefs.keepAliveEnabled,
+                sessionKnown = state !is SessionState.Unknown,
+                loggedIn = state is SessionState.LoggedIn,
+                notificationsAllowed = context.notificationsAllowed(),
+            )
+        ) {
+            KeepAliveAction.Start -> KeepAliveService.start(context)
+            KeepAliveAction.Stop -> KeepAliveService.stop(context)
+            KeepAliveAction.Leave -> Unit
+        }
+    }
+
    when (state) {
        SessionState.Unknown -> LoadingScreen()
        SessionState.LoggedOut -> LoginScreen(container)
@@ -7,6 +7,9 @@ import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge

 class MainActivity : ComponentActivity() {
+
+    private val container: AppContainer get() = (application as CyreneApplication).container
+
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)
@@ -17,22 +20,47 @@ class MainActivity : ComponentActivity() {
        // intent 再送一遍，照单全收就会把同一条分享发第二次。重建带 savedInstanceState，
        // 冷启动不带——这就是判据。
        if (savedInstanceState == null) {
-            intent?.let { ShareIntake.accept(this, it) }
+            intent?.let {
+                ShareIntake.accept(this, it)
+                // 点她那条通知冷启动进来：记一笔「要看主会话」（见 ProactiveTapIntake）。
+                // 与分享同一个判据：重建时系统会把同一个 intent 再送一遍，那时不能重复记账
+                // （重复没有害处，但「冷启动才接」这条纪律只有一处，别在两处各写一半）。
+                container.proactiveTapIntake.accept(it)
+            }
        }
-        val container = (application as CyreneApplication).container
        setContent {
            CyreneRoot(container)
        }
    }

+    /**
+     * 本 App 只有**一个** Activity（`singleTop`），所以它的 start / stop 就是「App 有没有在被看」
+     * ——这是「她主动说的话该不该弹通知」的两半之一（见 `core.notify.shouldNotifyProactive`）。
+     *
+     * 报的是**实例**而不是一个布尔量：旋转 / 系统深浅色切换会让新实例的 `onStart` 先于旧实例的
+     * `onStop`，布尔量在那一刻必然被记成「后台」，于是用户正看着聊天页她却弹一条通知出来。
+     * 集合由 [AppPresence] 自己持有，这里只报自己。
+     */
+    override fun onStart() {
+        super.onStart()
+        container.appPresence.onActivityStarted(this)
+    }
+
+    override fun onStop() {
+        container.appPresence.onActivityStopped(this)
+        super.onStop()
+    }
+
    /**
     * 热启动（`launchMode="singleTop"`）：App 已经开着时系统不再新建实例，只回调这里。
-     * 不接这一路的话，「从浏览器分享 → 回到已经开着的 Cyrene」会一点反应都没有。
+     * 不接这一路的话，「从浏览器分享 → 回到已经开着的 Cyrene」会一点反应都没有，而
+     * 「点她的通知 → 回到已经开着的 Cyrene（可能停在设置页）」同理。
     */
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        // 让 getIntent() 与新到的 intent 一致（系统不会自己更新它），否则后续读到的还是旧的那个。
        setIntent(intent)
        ShareIntake.accept(this, intent)
+        container.proactiveTapIntake.accept(intent)
    }
 }
@@ -0,0 +1,136 @@
+package top.yeij.cyrene.app
+
+import android.util.Log
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.BuildConfig
+import top.yeij.cyrene.core.notify.ProactiveNotifier
+import top.yeij.cyrene.data.ws.WsEvent
+
+private const val LOG_TAG = "ProactiveFrameIntake"
+
+/** 一帧「她主动说的话」剥出来的东西：[ProactiveNotifier.onProactiveFrame] 的四个入参 + 会话归属。 */
+internal data class ProactiveFrame(
+    val sessionId: String?,
+    val id: String?,
+    val messageId: String?,
+    val timestamp: String?,
+    val content: String,
+)
+
+/**
+ * 这一帧算不算「她主动说的话」，以及那四个入参各取帧上的哪个键——**纯函数**（离线可穷举）。
+ *
+ * 只有两种帧是她主动说的话，它们对应服务端两条路（见 [ProactiveNotifier]）：
+ * 1. [WsEvent.ProactiveMessage]（实时帧 `proactive_message`）——`id` 取落库行键 `data.id`，`messageId`
+ *    取 IM 侧消息号，两者**不是同一个 id**（见那个事件的 KDoc）；
+ * 2. [WsEvent.MessagePersisted] **且** `proactive == true`（IM 桥那条路补发的落库帧）——这一档只有
+ *    落库行的键（`message.id`），另外两个键帧上就没有，所以恒给 `null`，一个字都不许编。
+ *
+ * 其余帧一律 `null`：普通落库广播、流式增量、别的事件都不是「她主动找我说话」。判据错在这一层的
+ * 两个方向都很难在真机上发现——要么她开口了却什么都不弹（要等下一次主动消息才看得见），要么普通
+ * 消息也弹（每一次她正常回话都响）。
+ */
+internal fun proactiveFrameOf(event: WsEvent): ProactiveFrame? = when (event) {
+    is WsEvent.ProactiveMessage -> ProactiveFrame(
+        sessionId = event.sessionId,
+        id = event.id,
+        messageId = event.messageId,
+        timestamp = event.timestamp,
+        content = event.content,
+    )
+
+    is WsEvent.MessagePersisted -> {
+        if (!event.proactive) {
+            // 普通落库广播（她回话、别的端发的消息都走这一帧）：主人只批了 proactive 这一档。
+            null
+        } else {
+            ProactiveFrame(
+                sessionId = event.sessionId,
+                id = event.message?.id,
+                messageId = null,
+                timestamp = null,
+                content = event.message?.content.orEmpty(),
+            )
+        }
+    }
+
+    else -> null
+}
+
+/**
+ * 「她主动说的话 ⇒ 弹系统通知」那条通路的**帧消费点**（W57，**进程级**）。
+ *
+ * ## 为什么必须提到这一层（改前那一档是坏的）
+ * 这条通路的判据与去重一直是对的，错的是**订阅挂在哪**。改前它是 `SessionsViewModel` 里那句
+ * `viewModelScope.launch { socket.events.collect(::onEvent) }`。连接倒是进程级的——划掉 Activity
+ * 之后它照样连着、照样在收帧——但 `viewModelScope` 随 Activity 一起结束，而 `ChatSocket.events`
+ * 是 `replay = 0` 的 `SharedFlow`：**没有订阅者的 `tryEmit` 就是当场丢掉**（它不替将来的订阅者
+ * 留任何东西）。于是「从最近任务把 App 划掉、进程还被前台服务撑着」那一档，她的话进了连接、
+ * 然后没了。
+ *
+ * 本类因此只做一件事：**在进程级订那份帧流**，把 [proactiveFrameOf] 认出的帧交给 [ProactiveNotifier]。
+ * 它不建连接、不关连接、不认识登录态——连接的所有权一个字节都没动，仍然只在登录态那一处表达
+ * （`SessionsViewModel` 的 `LoggedIn → connect()` / `LoggedOut → close()`）。
+ *
+ * ## 为什么没有 start() / stop()
+ * 它的生命周期**就是进程**：`AppContainer` 在 `Application.onCreate` 里构造它，此后一直活着。
+ * 刻意不提供 `stop()` 正是这次要修的那个 bug——**唯一会想到去调 stop 的调用方（某个 ViewModel）
+ * 会随 Activity 一起死**，那等于把这条通路又绑回 Activity 上；留一个可以被忘掉调用的 `start()`
+ * 也只是多一种坏法（忘调 = 通知整个哑掉，且没有任何报错）。
+ *
+ * 它不需要停：帧只有连接活着才可能到，而连接在登出（含令牌失效那条经 `onAuthFailed` 的路径）时
+ * 由登录态关掉。「登出期间收不到帧」这件事由**连接**保证，不靠这里取消订阅。去重账本也**刻意不**
+ * 在这里清：它是 `ProactiveNotifier` 里的进程级账本，而换了账号之后同一条消息再推一次，仍是
+ * 同一个人的同一句话，不该弹第二遍。
+ *
+ * ## 它现在是这条通路上唯一的帧消费点
+ * 改前 `SessionsViewModel` 里那两处转交已经删掉（留两处就等于靠去重去替一次重复消费擦屁股，
+ * 而且「谁在喂通知」会有两个答案）。所以这条订阅一旦死掉，通知就**整个**哑掉——兜底见 [deliver]。
+ *
+ * @param events 进程内唯一那条连接的帧流（`ChatSocket.events`）。
+ * @param notifier 判据 + 去重 + 落地那一处。本类只喂帧，不替它判断任何事（那两个入参是它自己的
+ *   事实与动作，见它的 KDoc）。
+ * @param dispatcher 收集用的调度器；单测传 `Dispatchers.Unconfined`，让帧在同一次 `emit` 里走完。
+ */
+class ProactiveFrameIntake(
+    events: SharedFlow<WsEvent>,
+    private val notifier: ProactiveNotifier,
+    dispatcher: CoroutineDispatcher = Dispatchers.Default,
+) {
+
+    /**
+     * 订阅本身那个 scope：私有，没有第二个人拿得到它，也就没有人能取消这条订阅——本类的全部意义
+     * 就在这里。`SupervisorJob` 只为 [deliver] 那条兜底留余地。
+     */
+    private val scope = CoroutineScope(SupervisorJob() + dispatcher)
+
+    /** 构造即订阅（理由见类注释：启动时刻只有一个，留个能忘调的 `start()` 只会多一种坏法）。 */
+    init {
+        scope.launch { events.collect { event -> proactiveFrameOf(event)?.let(::deliver) } }
+    }
+
+    private fun deliver(frame: ProactiveFrame) {
+        try {
+            notifier.onProactiveFrame(
+                sessionId = frame.sessionId,
+                id = frame.id,
+                messageId = frame.messageId,
+                timestamp = frame.timestamp,
+                content = frame.content,
+            )
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Throwable) {
+            // 落地那一步（建渠道 / notify）万一抛，**这条订阅必须活下来**：它是进程级那唯一一处、
+            // 不会再被重建，而不接住的话异常会打到线程的未捕获处理器（Android 上就是进程当场挂）。
+            // 代价封顶在「这一条通知没弹」——去重账本已经把它记下了，不会为了补它再弹一次。
+            if (BuildConfig.DEBUG) Log.d(LOG_TAG, "这条主动消息的通知没能落地", e)
+        }
+    }
+}
@@ -0,0 +1,56 @@
+package top.yeij.cyrene.app
+
+import android.content.Intent
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import top.yeij.cyrene.core.notify.EXTRA_PROACTIVE_OPEN_MAIN_SESSION
+
+/**
+ * 「点她那条通知进来 ⇒ 要看主会话」这条**待落地的意图**（W53N）。
+ *
+ * ## 为什么它必须活在进程里，而不是直接在那次 Intent 里做完
+ * 通知可能在**任何**时刻被点：App 还没起来（冷启动）、已经开着但停在设置页、甚至还没登录。
+ * 而真正能「切到主会话」的只有一处——`ChatHomeScreen` 里那个 `SessionsViewModel`（`select()`），
+ * 它要被组合出来才存在，登录态没定时**根本没有**。所以这里只记一笔「用户要求看主会话」，
+ * 由 `ChatHomeScreen` 在能落地的那一刻取走（与 `ShareIntake` 同一种做法：待落地的意图活在
+ * Compose 与 ViewModel 之外，消费方自己挑时机认领）。
+ *
+ * ## 为什么是 StateFlow 而不是一个布尔
+ * 消费方（`ChatHomeScreen`）在 App 已经开着的时候**已经在组合里**：一个普通布尔量被改成 true
+ * 不会叫醒它，那一次点击就会静默丢掉（用户点了通知，进来还停在设置页）。`StateFlow` 一改值就能
+ * 让订着它的那段组合重跑判据。
+ *
+ * ## 不清理会怎样
+ * 没人消费时它一直是 true（例如点了通知但登录失败）——代价是「重登之后落在主会话」。
+ * 主会话本来就是默认落点（`resolveActiveSession` 在会话没了时也收敛到它），所以这里**刻意不**
+ * 在登出时清掉：留一个不会做错事的意图，好过为了干净而多一条「谁负责清它」的路径。
+ */
+class ProactiveTapIntake {
+
+    private val _openMainSession = MutableStateFlow(false)
+
+    /** 是否有一笔待落地的「切到主会话」。消费方拿到 true 后必须调 [consume]。 */
+    val openMainSession: StateFlow<Boolean> = _openMainSession.asStateFlow()
+
+    /**
+     * 从一次启动 / 热启动的 Intent 里认领这条意图（`MainActivity` 的两条入口都走这里）。
+     *
+     * 判据是这个 extra 的**字面量 true**：别的 Intent（分享、桌面图标）里它缺席，什么都不做。
+     */
+    fun accept(intent: Intent?) {
+        if (intent?.getBooleanExtra(EXTRA_PROACTIVE_OPEN_MAIN_SESSION, false) == true) {
+            requestMainSession()
+        }
+    }
+
+    /** 记下「用户要求看主会话」（与 `accept` 分开，是为了这一半能脱离 Android 单测）。 */
+    fun requestMainSession() {
+        _openMainSession.value = true
+    }
+
+    /** 取走这笔意图（只有真正落地了「切到主会话 + 回到聊天页」的那一次才调）。 */
+    fun consume() {
+        _openMainSession.value = false
+    }
+}
@@ -8,8 +8,11 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
 import kotlinx.coroutines.flow.StateFlow
 import top.yeij.cyrene.domain.chat.DocumentAttachments
+import top.yeij.cyrene.domain.chat.DocumentDelivery
+import top.yeij.cyrene.domain.chat.DraftDocument
 import top.yeij.cyrene.domain.share.PendingShareHolder
 import top.yeij.cyrene.domain.share.ShareRules
 import top.yeij.cyrene.domain.share.SharedContent
@@ -45,12 +48,23 @@ import java.util.UUID
 * 猜错等于替用户把一个合规文件变成一次失败；代价是「图片但 provider 没报 MIME」会落到文档路、
 * 被服务端按 `415` 拒（有如实文案）。画廊 / 相机 / MediaStore 都会报图片那一类，风险面很小。
 *
+ * ## 四个 extra 为什么都读「原始值」
+ * `EXTRA_TEXT` / `EXTRA_SUBJECT` / `EXTRA_TITLE` / `EXTRA_STREAM` 一律用 [Intent.rawExtra] 取原始值，
+ * 再由本文件按**形态**分派（[shareStreamExtrasOf] / [shareTextExtrasOf]）。两个理由：逐类型的
+ * `getXxxExtra` 遇到别的形态只会往 logcat 打一句 `ClassCastException` 再把值扔掉（那正是「分享点下去
+ * 什么都没发生」的来处），而本端还要知道「这个 extra 里**到底有没有躺着值**」——那件事纯函数看不到，
+ * 只能由这里如实报进去（两个 `present` 参数）。
+ *
+ * ⚠️ **正文的回落链起点也在这里**：`EXTRA_TEXT` 读不出东西时，`EXTRA_SUBJECT` → `EXTRA_TITLE` 依次
+ * 顶上（[ShareRules.extract]），来源记进 `SharedContent.textSource`。三个都空 / 都读不出来时，这一次
+ * 分享照样要往下走（走「读不进来」那条如实告知），**绝不静默**。
+ *
 * ## 清理
 * 缓存副本只对**产生它的那个进程**有意义（持有者在内存里，进程没了就没人认领），所以
 * 进程启动时整目录删一次（[reset]）。运行期间不做细粒度回收：那些文件在发送失败被回滚到
 * 输入框之后**仍然要用**（用户可能过一会儿才点发送），提前删掉就会让预览变空图。
- * 目录因此以「一次进程生命周期内的分享份数」为界（图片 4 + 文件 5，见 [ShareRules]），
- * 另有系统的 cache 回收兜底。
+ * 目录因此以「一次进程生命周期内的分享份数」为界（图片 4 + 文件 5，另加 [stageTextAsDocument]
+ * 为超长正文落下的那一份 `.txt`），另有系统的 cache 回收兜底。
 */
 object ShareIntake {

@@ -87,20 +101,42 @@ object ShareIntake {
     */
    fun accept(context: Context, intent: Intent) {
        val appContext = context.applicationContext
+        // 四个 extra 一律读**原始值**、按**形态**分派（见 [shareStreamExtrasOf] / [shareTextExtrasOf]）：
+        // 挨个 getXxxExtra 去问的话，遇到别的形态只会拿到一行 `ClassCastException` 加一个 `null`
+        // ——那正是「分享进来什么都没发生」的来处。读不出形态时本端既不猜、也不闭嘴（见下面两个
+        // `present`）：那照样是一次「带着内容迹象却什么都没读进来」。
+        val rawStream = intent.rawExtra(Intent.EXTRA_STREAM)
+        val streamExtras = shareStreamExtrasOf(rawStream)
+        val textExtras = shareTextExtrasOf(
+            text = intent.rawExtra(Intent.EXTRA_TEXT),
+            subject = intent.rawExtra(Intent.EXTRA_SUBJECT),
+            title = intent.rawExtra(Intent.EXTRA_TITLE),
+        )
        val extracted = ShareRules.extract(
            action = intent.action,
-            text = intent.getCharSequenceExtra(Intent.EXTRA_TEXT),
-            stream = intent.streamUri(),
-            streams = intent.streamUris(),
+            // 正文走回落链：EXTRA_TEXT → EXTRA_SUBJECT → EXTRA_TITLE（有些发送方不填 EXTRA_TEXT，
+            // 内容只在后两个里；只读第一个会让那次分享整条静默）。来源记在 `textSource` 里。
+            text = textExtras.text,
+            subject = textExtras.subject,
+            title = textExtras.title,
+            // 单值 / 列表两个字段都喂进去（本端不再按 action 猜该读哪个，见 [ShareRules.extract]）。
+            stream = streamExtras.uriForms.firstOrNull(),
+            streams = streamExtras.uriForms,
+            streamStrings = streamExtras.stringForms,
+            // 「里面躺着值」这件事只有这里知道（纯函数看不到原始值）：形态认不出的那种也算带着内容，
+            // 否则「分享点下去什么都没发生」会从那条缝里回来。
+            streamPresent = rawStream != null,
+            textPresent = textExtras.present,
            clipUris = intent.clipUris(),
            // 分流就发生在这一处：读不到类型（null）也按文档路走，见类 KDoc。
            mimeOf = { uri ->
                runCatching { context.contentResolver.getType(Uri.parse(uri)) }.getOrNull()
            },
        )
-        // 没有任何文本、也没有任何待落地的 URI ⇒ 这条分享里什么都没有（丢件计数在提取期恒为 0；
-        // 保留原来那条防御性判断，只是把「文件」那一档一并算上）。
-        if (extracted.isEmpty && extracted.droppedImages == 0 && extracted.droppedDocuments == 0) return
+        // 没什么值得往下走的就到此为止（判据是 [SharedContent.worthDelivering]：有可落地的内容，
+        // 或者有丢件 / 读不进来要对用户说清的事）。整条分享里什么都没有时静默是对的；而
+        // 「带着内容迹象却一条都没读进来」必须继续往下走——那条告知在下游 `shareNoticeFor` 里等它。
+        if (!extracted.worthDelivering) return

        scope.launch {
            val dir = shareDir(appContext).apply { mkdirs() }
@@ -125,13 +161,63 @@ object ShareIntake {
    /**
     * 取走一条待落地内容（原子出队，只有取到它的那个调用方会去发）；队列为空回 `null`。
     *
-     * 出队是**唯一的认领方式**：消费它的地方会被重建（重组 / 切会话 / Activity 重建），
-     * 所以「已经发过了」这件事不能记在消费方身上（见 [PendingShareHolder]）。
+     * 出队是**唯一的认领方式**，而它在这里是原子的：两个消费者同时来也只会各拿各的一条
+     * （判据见 [PendingShareHolder.take]）。而「**已经认领过了**」这件事此后记在认领它的那一格上
+     * ——`ChatViewModel` 的 [top.yeij.cyrene.ui.chat.ChatUiState.shareConfirm]。那一格活在
+     * `AppContainer` 那一层（`core.session.ChatSessionSlots` 的 `ViewModelStore`），比组合与
+     * Activity 都活得久，所以转屏 / 深浅色切换重建之后**不会再取第二遍**，也不会把队列里下一条顶掉：
+     * 认领的闸门在 `ChatViewModel.claimSharedContent` 里，且在调用本函数**之前**。
     */
    fun take(): SharedContent? = holder.take()

    private fun shareDir(context: Context): File = File(context.cacheDir, DIR_NAME)

+    /**
+     * 把一段**分享进来的超长正文**落成 cache 里的 `.txt`，返回可当附件用的待发文档；写不进去回 `null`。
+     *
+     * ## 为什么走本对象
+     * 落成附件的那份字节必须有个**本端的本地地址**才能进既有发送链（芯片要显示它、上传要按 URI
+     * 现读字节、发送失败回滚后用户还可能要点开看）：`DraftDocument` 只带引用不带字节。而写进
+     * 「分享缓存」这个目录、跟着同一条清理规则（进程启动整目录删一次）是最省事也最一致的做法——
+     * 与外部分享进来的文件**同一处落地、同一条生命周期**，不另造一个没人回收的目录。
+     * 本函数只负责「落盘 + 报一个可用的引用」，**不判断**要不要转（那是
+     * [DocumentDelivery.planSharedText] 的事）。
+     *
+     * 文件名用 [ShareRules.documentCacheFileName] 生成（**只由本端 token 与序号拼路径**，
+     * 外部字符串一个字符都进不了文件名），但对**服务端**报的名字是
+     * [DocumentDelivery.TEXT_DOCUMENT_FILE_NAME] ——服务端只取扩展名（白名单里的 `.txt`），
+     * 其余部分会被内容寻址丢弃。
+     *
+     * @return 待发文档（含 `file://` 地址、显示名与**真实字节数**）；任何一步失败都回 `null`，
+     *   由调用方按「内容一字不丢」的原则退回内联正文（见 `ChatViewModel.sendShared`）。
+     */
+    suspend fun stageTextAsDocument(context: Context, text: String): DraftDocument? = withContext(Dispatchers.IO) {
+        val staged = runCatching { DocumentDelivery.textAsFile(text) }.getOrNull() ?: return@withContext null
+        val dir = shareDir(context.applicationContext).apply { mkdirs() }
+        val target = File(
+            dir,
+            ShareRules.documentCacheFileName(UUID.randomUUID().toString(), 0, staged.fileName),
+        )
+        try {
+            target.writeBytes(staged.bytes)
+            val size = target.length()
+            if (size > 0L) {
+                DraftDocument(
+                    uri = Uri.fromFile(target).toString(),
+                    displayName = staged.fileName,
+                    sizeBytes = size,
+                )
+            } else {
+                target.delete()
+                null
+            }
+        } catch (_: Exception) {
+            // 半截文件不能留下：它会被当成一份真附件去读，报出的错会指向错的地方。
+            target.delete()
+            null
+        }
+    }
+
    /**
     * 把一份非图片分享文件的字节拷进 cache，返回**本端自己的** `file://` 地址 + 显示名 + 真实字节数；
     * 失败回 `null`。
@@ -215,15 +301,136 @@ object ShareIntake {
        }
    }

-    private fun Intent.streamUri(): String? =
-        getParcelableExtra(Intent.EXTRA_STREAM, Uri::class.java)?.toString()
+    /**
+     * 一个 extra 的**原始值**（四个 extra 共用），取不到回 `null`。
+     *
+     * ## 为什么读原始值而不是 `getXxxExtra`
+     * `Bundle.get` 在 API 33 起被打上废弃：它绕过类型安全。这里要的正是「绕过类型安全」——要判的
+     * 就是「这个值到底是什么形态」。逐类型的 `getXxxExtra` 遇到别的形态只会往 logcat 打一句
+     * `ClassCastException` 再把值扔掉（`String[]` 形态的 `EXTRA_STREAM` 就是这么静默丢掉的），而那
+     * 正是「分享点下去什么都没发生」的来处。形态分派见 [shareStreamExtrasOf] / [shareTextExtrasOf]。
+     *
+     * ## 为什么要 `runCatching`
+     * `Bundle.get` 第一件事是 `unparcel()`，它会解析别的进程给的字节：里面有个解析不出来的
+     * `Parcelable` 时它抛 `BadParcelableException`（核对过 AOSP 的 `android/os/BaseBundle.java`：
+     * defuse 关着时**直接抛出**，开着时也还要看 `Flags.deprecateBundleDefuse()` 那个 flag）。那是
+     * `RuntimeException`，从 `accept` 冒出去就是 `onCreate` 里的一次崩溃。
+     *
+     * ⚠️ 与它相对的是「类型不符」那种：`Bundle.getCharSequence` 自己 `catch` 了 `ClassCastException`
+     * 并回 `null`（同一个 AOSP 文件），所以那一档**不会**抛异常——但也**读不到值**，于是它只能靠
+     * 本函数给出的原始值被记成「里面躺着值」（见 [ShareTextExtras.present]），不会被静默当成
+     * 「什么都没分享」。两件事一起挡住：畸形 bundle 不当崩，读不出来的值不当没发生。
+     */
+    @Suppress("DEPRECATION")
+    private fun Intent.rawExtra(key: String): Any? = runCatching { extras?.get(key) }.getOrNull()

-    private fun Intent.streamUris(): List<String> =
-        getParcelableArrayListExtra(Intent.EXTRA_STREAM, Uri::class.java).orEmpty().map { it.toString() }
-
-    /** `ClipData` 里的 URI（部分 App 只填它）；纯文本条目的 URI 为空，天然被过滤掉。 */
-    private fun Intent.clipUris(): List<String> {
+    /**
+     * `ClipData` 各条目的 URI（部分 App 只填它）；纯文本条目的 URI 是 `null`。
+     *
+     * 这里刻意**保留**没有 URI 的条目（用 `null` 占位）而不是就地滤掉：条目本身就是「这次分享带着
+     * 内容」的证据——只有纯文本条目时本端一个字节都读不到（本端不读 `ClipData` 里的文本），那种
+     * 情形必须能说出口，见 [SharedContent.contentUnreadable]。
+     */
+    private fun Intent.clipUris(): List<String?> {
        val clip = clipData ?: return emptyList()
-        return (0 until clip.itemCount).mapNotNull { clip.getItemAt(it).uri?.toString() }
+        return (0 until clip.itemCount).map { clip.getItemAt(it).uri?.toString() }
    }
 }
+
+/**
+ * `EXTRA_STREAM` 一条**原始值** ⇒ 里面能读出来的地址，按形态分成两组。
+ *
+ * ## 为什么读原始值而不是挨个 `getXxxExtra` 去问
+ * `EXTRA_STREAM` 在真实世界里有三种形态：规范推荐的 `Uri`（多选时 `ArrayList<Uri>`）、`String[]`、
+ * `ArrayList<String>`。后两种（历史遗留 / 跨平台壳应用常见）此前**完全认不出**：`getParcelableExtra`
+ * 对 `String[]` 只会往 logcat 打一句
+ * `ClassCastException: Cannot cast [Ljava.lang.String; to android.net.Uri` 然后回 `null`，
+ * `getParcelableArrayListExtra` 同理——于是整次分享「什么都没发生」，连一句告知都没有。读原始值再按
+ * 类型分派是一次判完三种形态，顺带也不再往 logcat 里丢那两行噪声（`Bundle.get` 不做类型检查，
+ * 正是这里需要的；`getXxxExtra` 那一套是查完再 cast，查不中就把值扔了）。
+ *
+ * ## 形态决定信任级别
+ * - [uriForms]：`Uri`，以及数组 / 列表里的 `Uri`。对方是把 URI **对象**写进去的，这是规范路径；
+ *   本端维持既有口径不动（不看 scheme）。
+ * - [stringForms]：`String` / `CharSequence` 及其数组 / 列表。这是本端新开的一条读入口，所以开得窄
+ *   ——能不能用由 [ShareRules.stringStreamUri] 逐条判（只认 `content://`）。
+ *
+ * 认不出形态的原始值（别的 `Parcelable` / 数字 / 映射……）**不猜**：两边都不收。
+ */
+internal data class ShareStreamExtras(
+    val uriForms: List<String>,
+    val stringForms: List<String>,
+)
+
+/** 见 [ShareStreamExtras]：把 `EXTRA_STREAM` 的原始值按形态摊平成两组地址（纯逻辑，可单测）。 */
+internal fun shareStreamExtrasOf(raw: Any?): ShareStreamExtras {
+    val uriForms = mutableListOf<String>()
+    val stringForms = mutableListOf<String>()
+
+    fun collect(value: Any?) {
+        when (value) {
+            null -> Unit
+            is Uri -> uriForms += value.toString()
+            // 含 String。`Spanned` 之类也走这一条：它照样要过 scheme 白名单，不是「因为它是
+            // CharSequence 就信」。
+            is CharSequence -> stringForms += value.toString()
+            is Array<*> -> value.forEach { collect(it) }
+            is Iterable<*> -> value.forEach { collect(it) }
+            else -> Unit
+        }
+    }
+    collect(raw)
+
+    return ShareStreamExtras(uriForms = uriForms, stringForms = stringForms)
+}
+
+/**
+ * `EXTRA_TEXT` / `EXTRA_SUBJECT` / `EXTRA_TITLE` 三个**原始值** ⇒ 能当正文用的那几段。
+ *
+ * ## 为什么也读原始值（而不是 `getCharSequenceExtra` 挨个问）
+ * 两个理由，第一个是「读得回来」，第二个是「读不回来也要知道有东西」：
+ *
+ * 1. `getCharSequenceExtra` 只回「读到 / 没读到」，而本端要按**形态**分派：值可能是 `String`、
+ *    `Spanned`（富文本分享的常态）、`SpannedString`……它们都是 `CharSequence`，但按 `String` 读就
+ *    直接是 `null`（那正是「分享进来什么都没发生」的来处之一）。这里用 `as?` 一次判完：是
+ *    `CharSequence` 就收下，不是就当没有——**不猜、也不抛**。
+ * 2. 「三个里**有没有躺着值**」这件事纯函数看不到（它只收到几个 `CharSequence?`），而
+ *    「有值、只是本端一段都读不出来」与「用户什么都没分享」是**两件事**：前者必须能说出口，
+ *    否则那三种 extra 一起落空就是一次静默。所以 [present] 由这里如实报进去
+ *    （见 [ShareRules.extract] 的 `textPresent`）。
+ *
+ * ## 它抛不抛异常（核对过 AOSP 源码，`sources/android-36.1/android/os/BaseBundle.java`）
+ * - **类型不符不抛**：`Bundle.getCharSequence` 自己 `catch` 了 `ClassCastException`（`unparcel()` 之后
+ *   直接 `(CharSequence) o`，失败就 `typeWarning` 记一句 log 再回 `null`）⇒ 所以
+ *   `intent.getCharSequenceExtra(...)` 不会因为「值不是 CharSequence」把 App 打崩，它只是**读不到**。
+ *   那一档在这里落成 [present] 为真、[text] 为 `null`：既不崩、也不再静默。
+ * - **畸形 bundle 会抛**：它内部的 `unparcel()` 在别的进程给的 bundle 解析不出来时抛
+ *   `BadParcelableException`（`RuntimeException`）。那一路由 [Intent.rawExtra] 的 `runCatching` 挡住
+ *   ——读不到就当没有，**绝不让异常从 `accept` 冒出去**（那会是 `onCreate` 里的一次崩溃）。
+ */
+internal data class ShareTextExtras(
+    /** `EXTRA_TEXT` 读出来的那一段（读不回来是 `null`；空白**原样留着**，由纯函数判它算不算正文）。 */
+    val text: String?,
+    /** `EXTRA_SUBJECT` 读出来的那一段。 */
+    val subject: String?,
+    /** `EXTRA_TITLE` 读出来的那一段。 */
+    val title: String?,
+    /**
+     * 三个 extra 里**至少一个躺着原始值**——含**读不出类型**的那一种，也含**只是一段空白**的那一种。
+     *
+     * 空白也算，是刻意的：它说的是「对方**给了**这个字段」，与「这个字段里有没有可用的正文」是两件
+     * 事。而 `EXTRA_STREAM` 那边早就是这个口径（原始值只要非 null 就算 `streamPresent`），两个 extra
+     * 用同一条判据，才不会出现「流的空值会说话、文本的空值却闭嘴」这种要靠运气才发现的差别。
+     */
+    val present: Boolean,
+)
+
+/** 见 [ShareTextExtras]：把三个文本 extra 的原始值读成能当正文用的那几段（纯逻辑，可单测）。 */
+internal fun shareTextExtrasOf(text: Any?, subject: Any?, title: Any?): ShareTextExtras = ShareTextExtras(
+    text = (text as? CharSequence)?.toString(),
+    subject = (subject as? CharSequence)?.toString(),
+    title = (title as? CharSequence)?.toString(),
+    // 读不出类型（`42`、别种 `Parcelable`……）也算「里面躺着值」：本端不猜它是什么意思，但不该因此
+    // 把整次分享当成「什么都没发生」。`null`（连值都没有）才是真的没有。
+    present = text != null || subject != null || title != null,
+)
@@ -0,0 +1,82 @@
+package top.yeij.cyrene.core.keepalive
+
+/**
+ * 「后台保持连接」该不该跑（**纯函数**，UI 与测试共用）。
+ *
+ * 判据单独拎出来的理由与先例一致（`ui.sessions.silentRefreshStep`、`ui.chat.reconnectPull`）：
+ * 起服务那半边要 `Context`、要系统 API，在 JVM 单测里起不来；而「什么时候该跑」只有几个布尔，
+ * 能穷举、能断言。糊进 UI 之后就再也说不清「登出之后到底还会不会留着一条前台服务」——
+ * 那恰恰是这个功能最容易被写错的一半。
+ *
+ * 三个条件缺一不可，每一个都有自己的理由：
+ * - [enabled]：用户的选择，**默认关**。没打开就什么都不该常驻。
+ * - [loggedIn]：实时连接是登录态的产物（`SessionsViewModel` 在登出时关掉那条共享连接）。
+ *   没有连接还留一条前台服务，就只剩「白占一条通知 + 一点电」。
+ * - [notificationsAllowed]：`POST_NOTIFICATIONS` 被拒时前台服务**照样能跑**（系统不再拦它），
+ *   但那就等于**背着用户常驻一个不可见的进程**。本功能卖的就是「我明说我在跑」，
+ *   偷偷跑比不跑更糟——所以权限被拒判「不该跑」，由设置页那行字如实说出来。
+ *
+ * minSdk 33 ⇒ `POST_NOTIFICATIONS` 恒是运行时权限，不存在「低版本不用问」的那一档。
+ */
+internal fun shouldKeepAliveRun(
+    enabled: Boolean,
+    loggedIn: Boolean,
+    notificationsAllowed: Boolean,
+): Boolean = enabled && loggedIn && notificationsAllowed
+
+/** 这一刻该对那条前台服务做什么（[keepAliveAction] 的取值）。 */
+internal enum class KeepAliveAction {
+    /** 该在跑：起服务。重复起是安全的，见 [keepAliveAction]。 */
+    Start,
+
+    /** 不该在跑：停服务。对一条没在跑的服务喊停同样是安全的。 */
+    Stop,
+
+    /** 什么都不做：**此刻还不该有主张**（登录态未定，见 [keepAliveAction]）。 */
+    Leave,
+}
+
+/**
+ * 这一刻该对那条前台服务做什么（**纯函数**，判据本体是 [shouldKeepAliveRun]）。
+ *
+ * ## 为什么不只回一个布尔
+ * 只回「该不该跑」的话，调用方每次都得转成一次 `start` 或 `stop`，而**启动自举那一段**
+ * （`SessionState.Unknown`）两种都不该做：冷启动时进程里根本没有服务，但**热启动**（Activity
+ * 重建、进程还活着）时上一次那条还好端端跑着，此时若按「还没登录 ⇒ 停」收掉它，用户会看到
+ * 「通知消失 → 自举完成 → 通知又回来」这一闪，而中间那段（App 刚被切到后台时）进程正好没有任何
+ * 保护。所以那一档是 [KeepAliveAction.Leave]。
+ *
+ * ## 为什么**不**看一眼「现在跑着没有」
+ * 那样能省掉几回重复调用，但代价是引入一份会漂移的进程内状态：系统完全可能**在进程还活着的前提下**
+ * 把服务收掉而不走 `onDestroy`（比如用户在系统的「正在运行的应用」里按停），于是那份「跑着」的记忆
+ * 停在 true，下一轮判据就会「Leave」——**该起的时候一声不响地没起**，而这正是本功能最不能出的错。
+ * 重复调用则没有任何代价：`startForegroundService` 打到一条已经在跑的服务上只是刷新同一条
+ * （同 id、静默渠道的）通知，`stopService` 打到没在跑的服务上是空操作。
+ *
+ * @param enabled 设置页那个开关（持久化在 `AppPrefs.keepAliveEnabled`）。
+ * @param sessionKnown 登录态**已经定了**（`Unknown` 之外的一切）。
+ * @param loggedIn 现在处于登录态。
+ * @param notificationsAllowed `POST_NOTIFICATIONS` 已授权。
+ */
+internal fun keepAliveAction(
+    enabled: Boolean,
+    sessionKnown: Boolean,
+    loggedIn: Boolean,
+    notificationsAllowed: Boolean,
+): KeepAliveAction = when {
+    // 开关关着：没有第二种解释，收掉。**不等登录态**——用户刚表达过「不要」，用不着等自举。
+    !enabled -> KeepAliveAction.Stop
+
+    // 登录态未定（启动自举的那一段）：这时谁都说不准该不该跑，别动。
+    !sessionKnown -> KeepAliveAction.Leave
+
+    // 明确登出：连接都没了，留着没意义。开关本身不动（`AppSettings` 是 App 级的、不随登出清空，
+    // 下次登录仍按用户当初的选择来）。这里读的是**登录态**而不是「用没用上连接」——本服务不碰连接
+    // （见 [KeepAliveService]），它对连接的了解就只有「现在有没有一个登录着的用户」这一件事。
+    !loggedIn -> KeepAliveAction.Stop
+
+    // 到这儿只剩「开关开着 + 已登录」这一种情形，跑不跑由通知权限说话。
+    shouldKeepAliveRun(enabled, loggedIn, notificationsAllowed) -> KeepAliveAction.Start
+
+    else -> KeepAliveAction.Stop
+}
@@ -0,0 +1,162 @@
+package top.yeij.cyrene.core.keepalive
+
+import android.Manifest
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.content.pm.ServiceInfo
+import android.os.IBinder
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.ServiceCompat
+import androidx.core.content.ContextCompat
+import top.yeij.cyrene.BuildConfig
+import top.yeij.cyrene.app.MainActivity
+
+/** 通知渠道 id。恒定不变：改了它等于换一条渠道，用户对旧渠道做的静音设置会失效。 */
+internal const val KEEP_ALIVE_CHANNEL_ID = "keep_alive"
+
+/**
+ * 渠道重要级。**只许是 LOW / MIN**（[NotificationManager.IMPORTANCE_LOW] = 不响铃、不震动、
+ * 不弹横幅）：这是「保活」不是「提醒」，用户没要求被叫住。
+ *
+ * 注意重要级是**渠道创建时定死的**：应用后改不了（只有用户能改），所以这个值必须是最终值。
+ */
+internal const val KEEP_ALIVE_CHANNEL_IMPORTANCE = NotificationManager.IMPORTANCE_LOW
+
+/** 通知 id。常驻的那一条始终用它，重复起服务只更新不叠加。 */
+internal const val KEEP_ALIVE_NOTIFICATION_ID = 1
+
+private const val LOG_TAG = "KeepAliveService"
+
+/**
+ * `POST_NOTIFICATIONS` 授没授（minSdk 33 ⇒ 它恒是运行时权限）。
+ *
+ * 它既是 [shouldKeepAliveRun] 的入参，也是设置页那行字要说的事，所以两边共用这一处口径。
+ */
+internal fun Context.notificationsAllowed(): Boolean =
+    ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
+        PackageManager.PERMISSION_GRANTED
+
+/**
+ * 「后台保持连接」的前台服务。
+ *
+ * ## 它的职责只有一条：让进程活着
+ * 实时连接是**进程级共享**的那一条（`AppContainer.chatSocket`），所有权在 `SessionsViewModel`
+ * ——登录连、登出关。所以本服务**绝不**去 `connect()` / `close()` 它，也**不订阅任何帧**：
+ * 换了它的死活不等于换了连接的死活，两者各有各的主人。
+ *
+ * 它要挡的是 Android 12+ 对 cached 进程的冻结：进程一旦被冻，那条连接的读写就不再被调度，
+ * 久了连接就断（消息不丢，服务端会落库，回前台靠 history + `after` 补洞恢复，但那就不是
+ * 「保持连接」了）。前台服务把本进程从 cached 那一档里抬出来，这件事就到此为止。
+ *
+ * ## 起停只有一个主人
+ * [keepAliveAction] 判、`CyreneApp` 那个 `LaunchedEffect` 执行（全 App 唯一一处）：
+ * 谁都不许自己在别处 start / stop 它，否则「登出后还留着一条服务」这类不一致没有一处说得清。
+ *
+ * ## 它被系统杀掉怎么办
+ * [onStartCommand] 回 `START_STICKY`：被内存压力回收后系统会重建它。用户主动关开关走的是
+ * [stop]，那是显式停止，粘性不会把它拉回来。
+ */
+class KeepAliveService : Service() {
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        createChannel()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        ServiceCompat.startForeground(
+            this,
+            KEEP_ALIVE_NOTIFICATION_ID,
+            buildNotification(),
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+        )
+        return START_STICKY
+    }
+
+    /**
+     * Android 15（API 35）起，`dataSync` 型前台服务在 24 小时内累计跑满 6 小时，系统会回调这里，
+     * 并给几秒钟让应用自己收手——**不接管就会 ANR 崩掉整个 App**（本端 targetSdk 37，躲不掉）。
+     *
+     * 所以这里照办：`stopSelf` 收掉自己，进程回到普通后台状态。刻意**不绕**这条限制
+     * （绕它要么换前台服务类型、要么加心跳，都超出这个功能的边界）。代价如实说：同一台设备
+     * 24 小时内累计只能保活 6 小时；额度用完之后能不能再起、什么时候能再起由系统说了算，
+     * 本端不替它猜（这条限制的真机表现留给验收）。
+     */
+    override fun onTimeout(startId: Int, fgsType: Int) {
+        stopSelf(startId)
+    }
+
+    /**
+     * 常驻通知。文案**刻意克制**：它只是为了让「我在后台跑着」这件事在系统里是可见的
+     * （前台服务必须有一条通知，这是本功能对用户的代价，设置页那行字把它写明了）。
+     *
+     * `setSilent` + `setOngoing` + `setOnlyAlertOnce` + 渠道 LOW：不响、不震、不亮屏、划不掉。
+     * `setOnlyAlertOnce` 是给**重复起服务**留的（判据不看「现在跑着没有」，见 [keepAliveAction]）：
+     * 第二次 `startForegroundService` 打到同一条通知上时，用户那边必须**一点动静都没有**。
+     */
+    private fun buildNotification(): Notification {
+        // 点一下回到 App：一条点不动的常驻通知会让人以为卡住了。
+        val open = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, MainActivity::class.java),
+            PendingIntent.FLAG_IMMUTABLE,
+        )
+        return NotificationCompat.Builder(this, KEEP_ALIVE_CHANNEL_ID)
+            .setSmallIcon(android.R.drawable.stat_notify_sync)
+            .setContentTitle("保持与昔涟的连接")
+            .setContentText("Cyrene 正在后台维持与昔涟的连接")
+            .setContentIntent(open)
+            .setOngoing(true)
+            .setSilent(true)
+            .setOnlyAlertOnce(true)
+            .setShowWhen(false)
+            .setCategory(NotificationCompat.CATEGORY_SERVICE)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .build()
+    }
+
+    private fun createChannel() {
+        val channel = NotificationChannel(
+            KEEP_ALIVE_CHANNEL_ID,
+            "后台保持连接",
+            KEEP_ALIVE_CHANNEL_IMPORTANCE,
+        ).apply {
+            description = "开启「后台保持连接」期间常驻的通知：让系统不要冻结 Cyrene 的进程"
+            setShowBadge(false)
+            setSound(null, null)
+            enableVibration(false)
+        }
+        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
+    }
+
+    companion object {
+
+        fun start(context: Context) {
+            // Android 12+ 对「从后台起前台服务」是受限的，系统直接抛异常；这里吞掉它，理由有两条：
+            // ① 这个失败用户既看不懂也无从处置，而把异常放出去就是一次崩溃——崩溃比「这次没起成」
+            //    严重得多；
+            // ② 状态是自愈的：下一个判据触发点（开关 / 登录态变化、下次启动）会再试一次，
+            //    而这次没起成除了「进程暂时少一层保护」之外不留任何后遗症。
+            runCatching { ContextCompat.startForegroundService(context, intent(context)) }
+                .onFailure {
+                    if (BuildConfig.DEBUG) Log.d(LOG_TAG, "系统拒绝了这次前台服务启动", it)
+                }
+        }
+
+        fun stop(context: Context) {
+            context.stopService(intent(context))
+        }
+
+        private fun intent(context: Context): Intent = Intent(context, KeepAliveService::class.java)
+    }
+}
@@ -0,0 +1,92 @@
+package top.yeij.cyrene.core.notify
+
+import java.util.Collections
+import java.util.concurrent.ConcurrentHashMap
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * 进程级的两个「我此刻在哪儿」的事实（W53N）：**App 在不在前台**、**聊天页正显示哪个会话**。
+ *
+ * ## 为什么是这一层，而不是 ProcessLifecycleOwner
+ * 本仓没有 `lifecycle-process` 依赖，而为一个「要不要弹通知」的判断新增依赖不值当（主人明令不加）。
+ * 既有的 `MainActivity` 生命周期已经足够说清第一件事——本应用只有**一个** Activity
+ * （`singleTop`），它的 `onStart` / `onStop` 就是「App 有没有在被看」。第二件事由 `ChatScreen`
+ * 的组合报告（组合在 = 那一页在屏幕上，见 [onChatSurface]）。两条都在手写 DI 容器
+ * （`app.AppContainer`）那一层汇合——与那条共享连接、`goneSessions` 那几件进程级事实同一层。
+ *
+ * ## 为什么前台用「活着的 Activity 集合」而不是一个布尔
+ * 配置变更（旋转 / 系统深浅色切换）时，**新实例的 `onStart` 会先于旧实例的 `onStop`**：
+ * 一个布尔量在那里必然被旧实例的 `onStop` 记成「后台」，于是用户正看着聊天页，她一句话却弹出
+ * 通知来。按实例登记就没有这个方向性问题——新实例先加进来、旧实例后移出去，集合始终非空。
+ * 集合按 `ConcurrentHashMap` 语义（`Activity` 不重写 `equals` ⇒ 就是**同一实例**），
+ * 且读写可能不在同一线程上（她的话那条通路是在**进程级订阅自己的调度器**上读它的，见
+ * `ProactiveFrameIntake`），所以用并发容器而不是普通 `MutableSet`。
+ *
+ * ## 它**不是**「App 有没有活着」
+ * 后台保活（前台服务）让进程活着、连接继续收帧，而本类在这里恒报「不在前台」——那正是通知要
+ * 出现的那一档。两者是两件事，别把它们揉在一起。
+ */
+class AppPresence {
+
+    private val startedActivities: MutableSet<Any> =
+        Collections.newSetFromMap(ConcurrentHashMap<Any, Boolean>())
+
+    /**
+     * 聊天页此刻显示着的会话 id；`null` = 聊天页不在屏幕上（设置页 / 管理页 / 未登录 / 已销毁）。
+     *
+     * 由 [onChatSurface] 写、通知判据读。**刻意不带「前台」的含义**：App 退到后台时这段组合在
+     * Android 上并不会被销毁，这个值会原样留着——前台那一半由 [appInForeground] 单独表达，
+     * 两个事实的合取才是「这条消息此刻会不会正好被用户看到」（见 [shouldNotifyProactive]）。
+     */
+    @Volatile
+    var chatSurfaceSessionId: String? = null
+        private set
+
+    /** App 是否正在被看（有任何一个 Activity 处在 started 之后、stopped 之前）。 */
+    val appInForeground: Boolean
+        get() = startedActivities.isNotEmpty()
+
+    private val _appInForeground = MutableStateFlow(false)
+
+    /**
+     * [appInForeground] 的**可订阅**形态（W53S 登记的那一格要它）。
+     *
+     * 为什么需要第二条出口：`CyreneApp` 那个「起 / 停前台服务」的 `LaunchedEffect` 的 key 里没有
+     * 通知权限，于是**用户在系统设置里授权后回到 App** 时它不会重跑 —— UI 已经显示「已开」，
+     * 服务却没起。权限本身必须**现读**（不该缓存成状态），能当 key 的是「刚好会在这件事发生时变化」
+     * 的信号：**回到前台**（从系统设置返回必经 `onStart`）。所以这里把「在不在前台」补成一条流。
+     * 判据本身仍然只读 [appInForeground] 那个布尔——两条出口算的是**同一份事实**（同一个集合）。
+     */
+    val appInForegroundFlow: StateFlow<Boolean> = _appInForeground.asStateFlow()
+
+    /** 一个 Activity 进入「可见」这一档（`onStart`）。 */
+    fun onActivityStarted(owner: Any) {
+        startedActivities.add(owner)
+        _appInForeground.value = appInForeground
+    }
+
+    /**
+     * 一个 Activity 离开「可见」这一档（`onStop`）。
+     *
+     * 只移除**报上来的那一个实例**：照抄成「一停就整集合清空」会把正在起的新实例一起算掉
+     * （那条路径见类注释里的配置变更）。
+     */
+    fun onActivityStopped(owner: Any) {
+        startedActivities.remove(owner)
+        _appInForeground.value = appInForeground
+    }
+
+    /** 聊天页刚显示（或刚换成）[sessionId]；`null` = 它离开了屏幕。 */
+    fun onChatSurface(sessionId: String?) {
+        chatSurfaceSessionId = sessionId
+    }
+
+    /**
+     * 聊天页此刻显示的是不是 [sessionId] 这个会话（等值比较，不是前缀：`web` ≠ `web:xxx`）。
+     * `sessionId` 为空白时恒假——「没显示任何会话」不等于「显示了一个空 id 的会话」。
+     */
+    fun isShowingChatSurface(sessionId: String): Boolean =
+        sessionId.isNotBlank() && chatSurfaceSessionId == sessionId
+}
@@ -0,0 +1,277 @@
+package top.yeij.cyrene.core.notify
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import top.yeij.cyrene.app.MainActivity
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+
+/**
+ * 「她主动说的话」那条通知的渠道 id —— **弹横幅**的那一条（[PROACTIVE_IMPORTANCE]）。
+ *
+ * ⚠️ **这里是 `proactive_v2`，不是最初的 `proactive`**：渠道的**重要级一旦创建就改不了**
+ * （Android 的设计 —— 只有用户能改，App 改不动）。2026-10-07 主人明确要求「要横幅」，而把重要级
+ * 从 DEFAULT 提到 HIGH **对已经建过旧渠道的设备不生效** ⇒ 只能换一个新 id，让系统按新重要级
+ * 重新建一条。旧渠道由 [ensureProactiveChannel] 顺手删掉（它的重要级改不动，留着只会让系统设置里
+ * 多一条永远不再出现的条目）。
+ *
+ * **刻意与保活那条分成两个渠道**：保活那条是 LOW（不响不震、用户没要求被叫住），这一条是
+ * [PROACTIVE_IMPORTANCE]。两者混在一条渠道里，就只能在「保活开始响铃」与「她的话不响铃」之间
+ * 二选一——那正是「一个渠道只能是其中一件事」的由来。
+ *
+ * 与 [QUIET_PROACTIVE_CHANNEL_ID] **也是两条**，理由与上面那条一模一样：横幅由渠道重要级决定，
+ * 而重要级建完就改不了 ⇒ 设置页那个「免打扰」开关**不可能**靠运行时改设置实现，只能按开关选一条
+ * 渠道发（见 [proactiveChannelId]）。
+ */
+internal const val PROACTIVE_CHANNEL_ID = "proactive_v2"
+
+/**
+ * 「她主动说的话」在**免打扰**下走的那条渠道 id：重要级是 [QUIET_PROACTIVE_IMPORTANCE]
+ * （有提示音、通知栏有条目、**不弹横幅**）。
+ *
+ * 为「免打扰」单独建**第二条**渠道，是因为**重要级建完就改不了**（理由见 [PROACTIVE_CHANNEL_ID]）
+ * ——想「只关横幅」就只有换渠道这一条路。
+ *
+ * ⚠️ 刻意**不用** `setSilent(true)`：那是**完全静音**（连提示音都没），而用户要的语义是
+ * 「只在通知栏提示，别在屏幕顶部弹横幅」——两者之间差着一个提示音，不是同一件事。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_ID = "proactive_quiet"
+
+/**
+ * 上一个渠道 id（[PROACTIVE_CHANNEL_ID] 的前身）。**只在建渠道时用于删除**：它的重要级是
+ * DEFAULT 且改不动，留着毫无用处。
+ */
+internal const val LEGACY_PROACTIVE_CHANNEL_ID = "proactive"
+
+/**
+ * 弹横幅那条渠道的重要级：**`HIGH`**（屏幕顶部弹横幅 + 提示音）。
+ *
+ * 这一条**是**来提醒人的 —— 她主动找我说话的那一刻，我显然不在跟她聊天（App 不在前台），
+ * 正是最需要在屏幕顶部弹一下的场景。DEFAULT 只会响一声、安静躺在通知栏里，很容易错过
+ * （主人 2026-10-07 的原话：「我在其他 APP 时没看到横幅」）。
+ *
+ * 想安静的用户可以在系统设置里单独把这条渠道调低、或关掉它的横幅 —— 那是用户的权利，
+ * 不是我们对他的默认；应用内的那条捷径是设置页的「免打扰」，它把通知改发到
+ * [QUIET_PROACTIVE_CHANNEL_ID]。
+ *
+ * ⚠️ 与保活那条同理：重要级在**建渠道**时定死，应用之后改不了（只有用户能改）⇒ **改这个常量
+ * 对已建过渠道的设备不生效**，必须同时换 [PROACTIVE_CHANNEL_ID]。`ProactiveNotificationShapeTest`
+ * 把这两个值钉住。
+ */
+internal const val PROACTIVE_IMPORTANCE = NotificationManager.IMPORTANCE_HIGH
+
+/**
+ * 免打扰那条渠道的重要级：**`DEFAULT`**（提示音 + 通知栏条目，**没有横幅**）。
+ *
+ * `HIGH`(4) 才是屏幕顶部弹横幅的门槛，所以 DEFAULT 正是「她的话照旧说、只是不盖住我正在做的事」
+ * 那一档。
+ *
+ * ⚠️ 与上面那条同理：**改这个常量必须同时换 [QUIET_PROACTIVE_CHANNEL_ID]**，否则对已经建过它的
+ * 设备一个字节都不生效。这个方向（往安静改）出错时用户的感受只是「开关按了没反应」——不会有任何
+ * 报错，所以这条纪律只能靠常量与测试钉住。
+ */
+internal const val QUIET_PROACTIVE_IMPORTANCE = NotificationManager.IMPORTANCE_DEFAULT
+
+/** 通知标题：**是谁在说话**。正文是她的原话（见 [ProactiveNotifier]）。 */
+internal const val PROACTIVE_NOTIFICATION_TITLE = "昔涟"
+
+/**
+ * 渠道名（系统设置的渠道列表里那一行）。与通知标题分开是为了让它说清**这条渠道是什么**，
+ * 而不是重复一遍说话人的名字。
+ */
+internal const val PROACTIVE_CHANNEL_NAME = "她主动说的话"
+
+/**
+ * 免打扰那条渠道的渠道名。**必须一眼看出与 [PROACTIVE_CHANNEL_NAME] 的区别**：系统设置的渠道列表
+ * 里这两行会并排出现，用户就是靠这一行判断「哪条会弹横幅」的——同名的话两条渠道就白分了
+ * （他只能点进去、一条条试着看）。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_NAME = "她主动说的话（免打扰：只在通知栏）"
+
+/** 弹横幅那条渠道的描述（点进渠道详情才看得到）。 */
+internal const val PROACTIVE_CHANNEL_DESCRIPTION = "她主动找你说话时的通知"
+
+/**
+ * 免打扰那条渠道的描述。把「不弹横幅」与「还有提示音」都说清：用户点进来想知道的是**它到底静到
+ * 什么程度**，而「免打扰」四个字很容易被读成「完全没有声音」——那是另一件事（也正是用户会去系统
+ * 设置里翻、翻完还是不确定的那一件事）。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_DESCRIPTION =
+    "她主动找你说话时的通知（只在通知栏提示、不弹横幅；仍有提示音）"
+
+/**
+ * 一条 proactive 渠道的完整定义：**id / 渠道名 / 重要级 / 描述一次给全**。
+ *
+ * 为什么要打包成一个值：这四样必须**成对地**跟着「免打扰」这个布尔走（换了 id 却没换重要级 =
+ * 开关没生效；换了重要级却没换 id = 对老设备没生效）。散成四个各自 `if (quiet)` 就是四份口径，
+ * 而它们分叉时的症状全都是「用户按了开关，什么都没变」——最难被发现的那种坏法。
+ */
+internal data class ProactiveChannelSpec(
+    val id: String,
+    val name: String,
+    val importance: Int,
+    val description: String,
+)
+
+/**
+ * 「免打扰」→ 这一次该用哪条渠道 —— **纯函数**（不含任何 Android 调用，两档可穷举）。
+ *
+ * @param quiet 设置页那个「免打扰」开关**当下的值**（`false` = 都弹，也是默认）。
+ */
+internal fun proactiveChannelSpec(quiet: Boolean): ProactiveChannelSpec = if (quiet) {
+    ProactiveChannelSpec(
+        id = QUIET_PROACTIVE_CHANNEL_ID,
+        name = QUIET_PROACTIVE_CHANNEL_NAME,
+        importance = QUIET_PROACTIVE_IMPORTANCE,
+        description = QUIET_PROACTIVE_CHANNEL_DESCRIPTION,
+    )
+} else {
+    ProactiveChannelSpec(
+        id = PROACTIVE_CHANNEL_ID,
+        name = PROACTIVE_CHANNEL_NAME,
+        importance = PROACTIVE_IMPORTANCE,
+        description = PROACTIVE_CHANNEL_DESCRIPTION,
+    )
+}
+
+/**
+ * 发通知那一刻用哪条渠道 id —— **纯函数**，就是「同一个开关、两条渠道」这件事的全部落地形状。
+ *
+ * 单独再露一层是因为调用方要的正好只是这个 id（`NotificationCompat.Builder(context, ???)`），
+ * 而测试要问的也只是这一个问题：「开关两档各发去哪条」。
+ */
+internal fun proactiveChannelId(quiet: Boolean): String = proactiveChannelSpec(quiet).id
+
+/**
+ * 点通知进来时那个「切到主会话」的 Intent extra。
+ *
+ * 它是本端**手写布尔路由**里的一次「带意图的冷启动 / 热启动」：`MainActivity` 读它 →
+ * `ProactiveTapIntake` 记一笔 → `ChatHomeScreen` 落成一次 `select(主会话)`。刻意**不引导航库**
+ * （本项目没有导航库，路由就是 `ChatHomeScreen` 里那几个布尔量）。
+ */
+internal const val EXTRA_PROACTIVE_OPEN_MAIN_SESSION = "top.yeij.cyrene.extra.PROACTIVE_OPEN_MAIN_SESSION"
+
+/**
+ * 弹一条「她主动说的话」的通知。
+ *
+ * 只做四件事：按 [quiet] 选渠道、建渠道（惰性，第一次真要用时才建）、拼通知、`notify`。**判据、
+ * 去重与 id 的派生都不在这里**（那是 [ProactiveNotifier] 与 [proactiveNotificationId] 的事）
+ * ——本函数被调用就意味着「这一次确实该弹，且这条消息的号已经定好了」，它只负责把号用在通知上。
+ *
+ * ## 为什么 id 是入参而不是这里恒定一个
+ * 同 id 的 `notify` 是**替换**：恒用一个号就等于「后来的覆盖先来的」——她连说几句，用户只看到
+ * 最后一句。入参那个号由 [proactiveNotificationId] 按消息派生（输入就是去重键），于是同一句
+ * 无论到几次都落在同一条通知上，而不同的句子各占一条。
+ *
+ * ## 免打扰只换渠道，别的一个字节都不动
+ * [quiet] 为真时整条通知除了「发去哪条渠道 / 7.x 的优先级」以外**逐字节不变**：同一个标题、同一
+ * 段正文、同一个通知号、同一次点击行为。用户要的是「别在我正做事的时候盖住屏幕」，不是「别让我
+ * 知道」——所以什么都不该少，只是她的话安静地躺在通知栏里。
+ *
+ * ## 没授通知权限时什么都不做
+ * `minSdk 33` ⇒ `POST_NOTIFICATIONS` 恒是运行时权限，而系统在未授权时**静默丢弃**通知。与其发一条
+ * 必然无声无息的东西，不如在这里就收手（判据复用保活那处 [notificationsAllowed]，全 App 只有
+ * 一份「授没授」的口径）。用户之后在设置页授权、或直接开通了保活那个开关，下一句话就能弹出来
+ * ——本函数每次都**现读**权限，不缓存。
+ *
+ * ## 小图标用的是平台资源
+ * 工程里没有为通知准备单色小图标（`@mipmap/ic_launcher` 是彩色的，拿它当通知小图标在通知栏上
+ * 会显示成一块白斑）。所以用平台自带的 `stat_notify_chat`——与保活那条用 `stat_notify_sync` 是
+ * 同一个做法。要换成本应用的图标时，只需换下面这一行。
+ *
+ * @param notificationId 这条消息的通知 id，同时也是它点击用的 request code（两者必须一起动：
+ *   只换 id 不换 request code，点后到的那条通知会串到先到那条的 `PendingIntent` 上）。
+ * @param quiet 「免打扰」开关**当下的值**：`true` ⇒ 发到 [QUIET_PROACTIVE_CHANNEL_ID]（有提示音、
+ *   不弹横幅）；`false` ⇒ 发到 [PROACTIVE_CHANNEL_ID]（弹横幅）。**刻意不给默认值**：调用方忘写
+ *   这一位时症状是「开关按了没反应」，那种坏法没有任何报错——让编译器拦住它。
+ *   值由调用方每次**现读**（见 `AppContainer` 里 `post` 那个 lambda），所以开关一改不必重启 App，
+ *   下一条通知就走新渠道。
+ */
+internal fun postProactiveNotification(
+    context: Context,
+    text: String,
+    notificationId: Int,
+    quiet: Boolean,
+) {
+    if (!context.notificationsAllowed()) return
+
+    // 选渠道与建渠道用的是**同一个** spec：两处各自 `if (quiet)` 就会有一条渠道永远建不出来，
+    // 而它的症状是「开了免打扰之后她再也不通知我了」（Android 8+ 对不存在的渠道是静默丢弃）。
+    val channel = proactiveChannelSpec(quiet)
+    ensureProactiveChannel(context, channel)
+
+    // request code 随消息走（`proactiveNotificationId` 的下界远高于保活那条用的 `0`，所以不会
+    // 撞上它）：两个 Intent 都是「启动 MainActivity」、没有 action / data / categories ⇒
+    // `Intent.filterEquals` 判它们**相等**，而 `PendingIntent` 的相等判据里**不含 extras**。
+    // 同 request code 时系统直接复用**先建的那一个**，后建这枚的 extra 会被悄悄丢掉。
+    val openApp = PendingIntent.getActivity(
+        context,
+        notificationId,
+        Intent(context, MainActivity::class.java).putExtra(EXTRA_PROACTIVE_OPEN_MAIN_SESSION, true),
+        PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+    )
+
+    val notification = NotificationCompat.Builder(context, channel.id)
+        .setSmallIcon(android.R.drawable.stat_notify_chat)
+        .setContentTitle(PROACTIVE_NOTIFICATION_TITLE)
+        .setContentText(text)
+        // 展开态显示完整正文（`setContentText` 那一行放不下 120 字，而截断只解决「过长」，
+        // 解决不了「一行的宽度」）。
+        .setStyle(NotificationCompat.BigTextStyle().bigText(text))
+        .setContentIntent(openApp)
+        // 点掉即消失：这条通知说的是一次刚发生的事，用户点开就等于看到了。
+        .setAutoCancel(true)
+        .setCategory(NotificationCompat.CATEGORY_MESSAGE)
+        // 横幅：Android 8+ 由**渠道重要级**决定（上面那条 spec 选出来的那条渠道），这一句管的是
+        // 7.x 及更早（那边还没有渠道，优先级就是全部）。两处必须同向——免打扰那一档在这里也得
+        // 降回 DEFAULT，否则老设备上「开着免打扰却照样弹横幅」。
+        .setPriority(if (quiet) NotificationCompat.PRIORITY_DEFAULT else NotificationCompat.PRIORITY_HIGH)
+        .build()
+
+    // 一事一条：号随消息走。撞号会发生，代价与改前一样是「后来的把先来的替换掉」，
+    // 理由与概率写在 `proactiveNotificationId` 的 KDoc 里。
+    NotificationManagerCompat.from(context).notify(notificationId, notification)
+}
+
+/**
+ * 建（或更新）**这一次要用的那一条**渠道。惰性创建：一个从没收到过她主动消息的用户，系统设置的
+ * 渠道列表里不会平白多出一条「她的话」。
+ *
+ * ## 为什么只建「这一次要用的那一条」，而不是两条都建
+ * 「免打扰」决定的是**下一条**通知发去哪条渠道，而渠道只需要在 `notify` 之前存在。两条都建的话，
+ * 一个从没开过免打扰、将来也不打算开的用户，系统设置里会平白多出一条他从没见过的「她主动说的话
+ * （免打扰：只在通知栏）」——那是我们替他做的选择，也算脏数据。所以这里只 ensure 被选中的那一条。
+ *
+ * ⚠️ 但**必须在 `notify` 之前** ensure：Android 8+ 上目标渠道不存在时，那条通知是被系统**静默
+ * 丢弃**的（不报错、不打日志、只是什么都没有）。这正是「只建一条」这个省法的代价 —— 它靠
+ * [postProactiveNotification] 里「选渠道」与「建渠道」用的是**同一个** [ProactiveChannelSpec]
+ * 兜住（两处各自 `if (quiet)` 就会有一条渠道永远建不出来，而症状是「开了免打扰之后她再也不
+ * 通知我了」——用户只会以为是她不说话了）。
+ *
+ * ## 另一条渠道**不删**
+ * 它是「这一次没选」，不是「以后不再用」：用户来回切开关时，他在系统设置里对另一条调过的横幅 /
+ * 静音设置得留着（删掉 = 把他的选择一起删掉，还得重新建一条空白的）。唯一会删的是
+ * [LEGACY_PROACTIVE_CHANNEL_ID] —— 那条 id 本端**再也不会发**，而它的重要级又改不动，留着只会
+ * 在系统设置里多一条永远不再出现的条目（用户可能在那儿调半天、却发现怎么调都没变化）。
+ *
+ * 重复调用是幂等的（同 id ⇒ 更新那条渠道，不会建出第二条）。**注意重要级只在第一次创建时生效**
+ * ——它已经在 [PROACTIVE_IMPORTANCE] / [QUIET_PROACTIVE_IMPORTANCE] 上定死（渠道名与描述此后仍
+ * 可以改，重要级改不了）。
+ *
+ * @param spec 这一次要用的那条渠道（由 [proactiveChannelSpec] 按「免打扰」开关选出来）。
+ */
+private fun ensureProactiveChannel(context: Context, spec: ProactiveChannelSpec) {
+    val channel = NotificationChannel(spec.id, spec.name, spec.importance).apply {
+        description = spec.description
+        setShowBadge(true)
+    }
+    val manager = context.getSystemService(NotificationManager::class.java)
+    manager.createNotificationChannel(channel)
+    // 旧的 DEFAULT 渠道删掉：重要级改不动，留着只会在系统设置里多一条永远不再出现的条目
+    // （用户可能在那儿调半天、却发现怎么调都没变化）。删一条不存在的渠道是幂等的。
+    manager.deleteNotificationChannel(LEGACY_PROACTIVE_CHANNEL_ID)
+}
@@ -0,0 +1,107 @@
+package top.yeij.cyrene.core.notify
+
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
+
+/**
+ * 一帧「她主动说的话」进到本类之后**发生了什么**（纯判定的结果，可单测）。
+ *
+ * 分成五档而不是一个布尔，是为了让「为什么这次没弹」在日志与测试里都能一眼看穿：这五条各自
+ * 对应一个完全不同的理由，而在通知这一档上，「没弹」与「弹了」一样需要说得清。
+ */
+enum class ProactiveNotifyOutcome {
+
+    /** 弹了。 */
+    Posted,
+
+    /** 用户正看着主会话（前台 ∧ 聊天页显示主会话）：她的话就出现在他眼前，不打扰。 */
+    SeenOnScreen,
+
+    /** 同一条已经到达过（实时帧与落库帧两条路，或服务端重推）。 */
+    Duplicate,
+
+    /** 帧里没有可显示的正文（坏帧 / 落库失败的空帧）。 */
+    NothingToSay,
+
+    /**
+     * 不属主会话。她主动说的话落的是主会话（服务端 `history.MainSessionID`）；帧上若明说了别的
+     * 会话，那不是这件事，绝不弹（宁可漏，也不要把别处的消息说成是她在找我说话）。
+     */
+    OtherSession,
+}
+
+/**
+ * 「她主动说的话」的通路（W53N）：**判据 + 去重 + 落地**收在一处，Android 那一步由 [post] 注入。
+ *
+ * ## 谁把帧喂进来（W57 起）
+ * 后端两条路（实时帧 `proactive_message`、落库帧 `message_persisted{proactive:true}`）在客户端
+ * 汇于一处：**进程级**的帧消费点 `app.ProactiveFrameIntake` 订着那条共享连接，把这两种帧折成下面
+ * [onProactiveFrame] 的四个入参喂过来（同一条消息无论走哪条路、到几次，都只经过这一处）。
+ * 本类因此只是一个**纯逻辑 + 一个回调**，不订阅任何东西、不碰连接、不认识 Android——测试里传个
+ * 假的 [post] 就能把它整条驱动起来。
+ *
+ * ## 它绝不碰连接
+ * 连接的所有权在登录态（`SessionsViewModel` 那处 `LoggedIn → connect()`）。本类只在帧**已经到达
+ * 之后**做判断——帧没到就没有任何事发生，它不会去重连、不会去补拉、不会去订阅。
+ *
+ * ## 一次帧到这里的顺序（每一步的顺序都有理由）
+ * 1. [ProactiveNotifyOutcome.OtherSession]：不是主会话，连账本都不必碰；
+ * 2. [ProactiveNotifyOutcome.NothingToSay]：先看有没有可显示的字。**这一步不记账**——同一句话的
+ *    另一条路上正文可能是齐的（实时帧空、落库帧有字的形状漂移），记了就会把那条能弹的挡成重复；
+ * 3. [ProactiveNotifyOutcome.Duplicate]：记账与查重。**先记账再判「会不会被看到」**，因为「用户
+ *    正看着」那一次也算这条已经到达：他当场看过了，另一条路再补一帧时不该为一句**看过的话**弹
+ *    通知（他这会儿可能已经切走了）；
+ * 4. [ProactiveNotifyOutcome.SeenOnScreen] / [ProactiveNotifyOutcome.Posted]：最后才问时机。
+ *
+ * @param presence 「App 在不在前台 / 聊天页显示着谁」，由 `MainActivity` 与 `ChatScreen` 报告。
+ * @param post 真正的落地动作（Android 那边是建渠道 + `notify`）。第二个入参是**这条消息派生出来的
+ *   通知 id**（见 [proactiveNotificationId]）：落地侧必须用它，别再恒用一个号——恒用一个号时
+ *   `notify` 是替换，她连说几句就只剩最后一句。测试传一个记录用的假实现即可。
+ * @param mainSessionId 主会话 id。默认取 [SessionSummaryDto.MAIN_SESSION_ID]，测试可换。
+ */
+class ProactiveNotifier(
+    private val presence: AppPresence,
+    private val post: (text: String, notificationId: Int) -> Unit,
+    private val mainSessionId: String = SessionSummaryDto.MAIN_SESSION_ID,
+    private val recent: RecentProactiveNotices = RecentProactiveNotices(),
+) {
+
+    /**
+     * 一帧到了（实时帧与落库帧**共用**这一处，所以同一条消息无论到几次都只弹一次）。
+     *
+     * @param sessionId 帧上的会话归属；`null` / 空白 = 帧壳没给（实时帧就是这样：服务端构造它时
+     *   不设 `sessionId`）⇒ 按「无法判定」放行，由 [mainSessionId] 那条事实兜住归属。
+     * @param id 落库行 id（实时帧的 `data.id` / 落库帧的 `message.id`）——两条路的公共键。
+     * @param messageId IM 侧消息号（实时帧才有；落库失败那一档它是最后的服务端键）。
+     * @param timestamp 服务端给的时间**字面量**（只作去重兜底，排序与本类无关）。
+     * @param content 她的原话（原始文本，标记由 [proactiveNotificationText] 剥）。
+     */
+    fun onProactiveFrame(
+        sessionId: String?,
+        id: String?,
+        messageId: String?,
+        timestamp: String?,
+        content: String,
+    ): ProactiveNotifyOutcome {
+        if (!sessionId.isNullOrBlank() && sessionId != mainSessionId) {
+            return ProactiveNotifyOutcome.OtherSession
+        }
+
+        val text = proactiveNotificationText(content) ?: return ProactiveNotifyOutcome.NothingToSay
+
+        val key = proactiveNotifyKey(id, messageId, timestamp, text)
+        val firstArrival = recent.markIfNew(key)
+        if (!firstArrival) return ProactiveNotifyOutcome.Duplicate
+
+        // 判据只回答「弹不弹」，「用户会不会正好看到」是它的反面——别在接线层另写一遍这个取反
+        // （两份口径早晚会分叉，而这里分叉的代价是「她的话在用户眼前弹出来」）。
+        val seenOnScreen = !shouldNotifyProactive(
+            appInForeground = presence.appInForeground,
+            viewingTargetSession = presence.isShowingChatSurface(mainSessionId),
+        )
+        if (seenOnScreen) return ProactiveNotifyOutcome.SeenOnScreen
+
+        // id 与去重键同源，正是为了让「同一条 ⇒ 同一个号」与「同一条 ⇒ 只弹一次」永远不会分叉。
+        post(text, proactiveNotificationId(key))
+        return ProactiveNotifyOutcome.Posted
+    }
+}
@@ -0,0 +1,192 @@
+package top.yeij.cyrene.core.notify
+
+import kotlin.math.absoluteValue
+import top.yeij.cyrene.domain.parse.parse
+
+/**
+ * 「她主动说的话」该不该弹一条系统通知 —— 纯函数（W53N）。
+ *
+ * 主人对时机的原话是「**App 不在前台，或者不在聊天页**」。写成一个判据（而不是直接写成
+ * `!viewing`）是为了让两个事实**各自**可见、可穷举、可测试：它们是两个方向完全不同的东西，
+ * 合成一行以后「为什么这一档不弹」就再也说不清了。
+ *
+ * 语义（**判断标准只有一条：这条消息此刻会不会正好被用户看到**）：
+ *
+ * | [appInForeground] | [viewingTargetSession] | 结论 | 场景 |
+ * |---|---|---|---|
+ * | true | true | **不弹** | 用户正看着主会话，她的话就出现在他眼前 |
+ * | true | false | 弹 | 用户在看设置页 / 别的会话（甚至另一个会话的聊天页） |
+ * | false | false | 弹 | App 退到后台 / 熄屏（进程被保活着，帧还在到） |
+ * | false | true | 弹 | **Android 上真实存在**：Activity `onStop` 之后组合并没有销毁，
+ * 聊天页仍「显示」着主会话。此时的用户根本看不见它，所以照弹 |
+ *
+ * 最后一行是「两个事实不许互相顶替」的那一半：只看聊天页显示着谁，就会在 App 退到后台以后
+ * 静默漏掉**所有**她的话。
+ *
+ * @param appInForeground 此刻有没有 Activity 在「可见」这一档（见 [AppPresence.appInForeground]）。
+ * @param viewingTargetSession 聊天页此刻显示的是不是**她说这句话的那个会话**。注意它**不含**
+ *   「前台」的含义（见 [AppPresence.chatSurfaceSessionId]）——它只说「屏幕上摆着哪一页」。
+ */
+fun shouldNotifyProactive(
+    appInForeground: Boolean,
+    viewingTargetSession: Boolean,
+): Boolean = !(appInForeground && viewingTargetSession)
+
+/**
+ * 通知正文的长度上限（字符）。超出的部分截断加 `…`。
+ *
+ * 取值理由：通知在折叠态只显示一行（约 20~30 字），展开态（`BigTextStyle`）能显示四五行。
+ * 这个上限是**展开态**的预算——正文不砍到一行那么短（那样会看不出她在说什么），但也不许整屏
+ * 铺开。真正的长文在聊天页里一字不少。
+ */
+const val PROACTIVE_NOTIFICATION_MAX_CHARS = 120
+
+/**
+ * 去重账本的容量。同一条她的话最多两条路会到（实时帧 + 落库帧），容量只需要覆盖「最近一小段」；
+ * 取 64 是给「她连说几句 + 两条路交错」留的余量，同时**有界**——进程活一整天也不会涨。
+ */
+const val RECENT_PROACTIVE_CAPACITY = 64
+
+/**
+ * 最近**已经到达过**的 proactive 消息的键（进程级、容量有限、先进先出淘汰）。
+ *
+ * ## 为什么必须有它
+ * 同一条消息会走**两条**路到本端：实时帧 `proactive_message`（带**落库行** `id`）与落库帧
+ * `message_persisted{proactive:true}`（带 `message.id`，同一个值）。不去重就是同一条消息弹两次。
+ *
+ * ## 为什么记的是「到达过」而不是「弹过」
+ * 因为「用户正看着主会话」那一次也要记：他当场看过这条了，随后另一条路再补一帧时**不该**为一句
+ * 已经看过的话弹通知（他这会儿可能已经切到别的会话了）。两个方向都要求同一件事：**先到的那一次
+ * 说了算**。判据见 [ProactiveNotifier.onProactiveFrame]。
+ *
+ * 有界：超过容量按插入顺序丢掉最老的（`LinkedHashSet` 的迭代顺序就是插入顺序）。
+ * 只活在本进程里，不持久化——重启之后最多重复弹一条「刚刚到达过、还没被看过」的话，那比
+ * 为一个通知判据在磁盘上留一份状态诚实得多。
+ */
+class RecentProactiveNotices(private val capacity: Int = RECENT_PROACTIVE_CAPACITY) {
+
+    private val seen = LinkedHashSet<String>()
+
+    /**
+     * 记下这个键，并回「它是不是**第一次**来」。返回 false = 这条已经到达过，调用方必须闭嘴。
+     *
+     * 空键恒回 false（「没有键」不是一个可去重的身份，绝不把它当成一条新消息的凭据）。
+     */
+    @Synchronized
+    fun markIfNew(key: String): Boolean {
+        if (key.isBlank()) return false
+        if (!seen.add(key)) return false
+        while (seen.size > capacity.coerceAtLeast(1)) {
+            val oldest = seen.firstOrNull() ?: break
+            seen.remove(oldest)
+        }
+        return true
+    }
+
+    /** 账本里现有多少个键（测试与诊断用）。 */
+    @Synchronized
+    fun size(): Int = seen.size
+}
+
+/**
+ * 一条 proactive 消息的去重键（纯函数）。
+ *
+ * 按**服务端给的 id 优先级**取，最后才退到正文：
+ * 1. 落库行 id（实时帧的 `data.id` / 落库帧的 `message.id`）——两条路**唯一的公共键**，
+ *    也是服务端唯一保证「同一条消息同一个值」的键；
+ * 2. IM 侧消息号（只有实时帧有：落库失败那一档它仍然在，`id` 缺席）；
+ * 3. 时间字面量（同上，最后的服务端键）；
+ * 4. [fallback]（调用方传**正文**）——服务端一个键都没给时的兜底。
+ *
+ * 第 4 条是刻意的取舍：它会让「没有 id、正文又一个字不差」的两条消息被并成一条（少弹一次），
+ * 而反过来（不兜底 ⇒ 无键可查 ⇒ 每来一帧都弹）会把服务端重推的同一条话弹成两条。**少弹**
+ * 是这两边更轻的那一侧——通知只是提醒，话本身在聊天页里一条都不少。
+ */
+fun proactiveNotifyKey(
+    id: String?,
+    messageId: String?,
+    timestamp: String?,
+    fallback: String,
+): String = listOf(id, messageId, timestamp)
+    .firstOrNull { !it.isNullOrBlank() }
+    ?: fallback
+
+/**
+ * 派生 id 的取值**下界**（见 [proactiveNotificationId]）。
+ *
+ * 通知 id 与 `PendingIntent` 的 request code 都是**全 App 共用**的命名空间，而它们现有的占用者
+ * （保活那条常驻通知 `KEEP_ALIVE_NOTIFICATION_ID` = 1、它点击用的 request code = 0）全在低位。
+ * 从远高于它们的地方起步，「派生 id 不撞既有 id」就是**结构性**成立的，不是靠「碰巧没撞上」。
+ */
+private const val PROACTIVE_NOTIFICATION_ID_FLOOR = 1_000
+
+/**
+ * 派生 id 的取值**宽度**（见 [proactiveNotificationId]）。
+ *
+ * 取这么宽是为了让 id 空间尽量大（撞号的概率随宽度下降），同时**贴着 `Int.MAX_VALUE` 留出下界的
+ * 位置**：「下界 + 宽度」一旦越过 `Int.MAX_VALUE`，末尾的 `.toInt()` 就会折回负数。
+ */
+private const val PROACTIVE_NOTIFICATION_ID_SPAN = 2_000_000_000
+
+/**
+ * 一条 proactive 消息对应的**通知 id（同时也是它点击用的 request code）**——纯函数，由去重键
+ * [proactiveNotifyKey] 的输出派生。这就是「一事一条」的全部落地形状（W54A）。
+ *
+ * ## 为什么必须与去重键同源
+ * 改前所有她的话共用一个固定 id，而 `notify` 遇同 id 是**替换**：她连说几句，用户只看到最后
+ * 一句，前面那几句在他拿起手机之前就已经没了。按消息派生要回答的第一个问题是「凭什么是同一条」
+ * ——那正是 [proactiveNotifyKey] 已经回答过的（实时帧与落库帧共用它）。**两处口径必须永远同源**：
+ * 去重说「这是同一条」、派生说「这是同一条 ⇒ 同一个号」；分成两套，就会出现「认得出是同一条、
+ * 却排出两条 id」的形状漂移。
+ *
+ * ## 它会撞号，后果如实说
+ * `String.hashCode()` 只有 32 位，再折进 [PROACTIVE_NOTIFICATION_ID_SPAN] 这一段 ⇒ **不同消息
+ * 派生出同一个 id 是会发生的**（约 2×10⁹ 的空间，按生日问题算，通知栏里装几十条时概率可忽略）。
+ * 撞上的后果与改前**一模一样**：后来那条替换先来那条，用户少看见一条提醒。这是刻意接受的那一侧
+ * ——通知只是「她找你了」这一下，她的话本身在主会话里一条不少；反过来要绝对不撞，就得在服务端
+ * 唯一号之外再维护一套映射并持久化它，代价比「极少数情况下少一条提醒」大得多。
+ *
+ * ## 两个坑都在这里堵上
+ * 1. **号必须为正**：通知 id 是一个有符号 `int`，而这个命名空间里正数是纪律（本仓保活那条常驻通知
+ *    是 1；平台对前台服务的 id 更直接写明「must not be 0」）。而 `hashCode()` 可以是负的、甚至
+ *    正好是 `Int.MIN_VALUE`——后者连 `abs` 都兜不住（在 int 域里 `abs(Int.MIN_VALUE)` 仍是它自己）。
+ *    所以这里**先展宽到 `Long` 再取绝对值**：`Int.MIN_VALUE.toLong()` = 2147483648，取绝对值是安全
+ *    的，再折进 [PROACTIVE_NOTIFICATION_ID_SPAN] 后落在正区间。
+ * 2. **不撞既有 id**：见 [PROACTIVE_NOTIFICATION_ID_FLOOR]。
+ */
+internal fun proactiveNotificationId(key: String): Int {
+    val magnitude = key.hashCode().toLong().absoluteValue
+    return (PROACTIVE_NOTIFICATION_ID_FLOOR + magnitude % PROACTIVE_NOTIFICATION_ID_SPAN).toInt()
+}
+
+/**
+ * 通知正文：她的原话，**剥掉标记、折成一行、过长截断**；没有可显示的字时回 `null`。
+ *
+ * ## 为什么不直接发原始 `content`
+ * 她的内容里带 `<p>` / `<action>` / `<narration>` 标记（服务端原样落库），直接放进通知会把标签
+ * 露给用户（本仓在会话列表那一行上早就踩过同一件事，见 `ui.sessions.toPreviewText`）。
+ * 这里**复用权威解析器** [parse] 而不是再写一份剥标签的正则：同一件事有两份口径早晚会分叉，
+ * 而分叉的那一侧就是通知里露标签的那一侧。解析出的全部片段按原顺序拼回（旁白/动作也留着——
+ * 那也是她说的话），片段之间补空格，免得「正文紧贴旁白」时两侧的字粘成一个词。
+ *
+ * 截断按 UTF-16 码元走，但**不劈开代理对**（emoji 这类字符由两个码元组成，劈开会显示成半个
+ * 乱码方块）：末尾正好落在高代理项上时整体后退一位。
+ */
+fun proactiveNotificationText(
+    content: String,
+    maxChars: Int = PROACTIVE_NOTIFICATION_MAX_CHARS,
+): String? {
+    val flat = parse(content)
+        .joinToString(" ") { bubble -> bubble.parts.joinToString(" ") { part -> part.text } }
+        .replace(WHITESPACE_RE, " ")
+        .trim()
+    if (flat.isEmpty()) return null
+    // maxChars <= 0 = 「不截断」（调用方明确要全文）；其余情况只在真的超长时才动手。
+    if (maxChars <= 0 || flat.length <= maxChars) return flat
+
+    var end = maxChars
+    if (Character.isHighSurrogate(flat[end - 1])) end -= 1
+    return flat.substring(0, end).trimEnd() + "…"
+}
+
+private val WHITESPACE_RE = Regex("\\s+")
@@ -8,36 +8,93 @@ import androidx.datastore.preferences.core.booleanPreferencesKey
 import androidx.datastore.preferences.core.edit
 import androidx.datastore.preferences.core.stringPreferencesKey
 import androidx.datastore.preferences.preferencesDataStore
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn

 private val Context.appDataStore: DataStore<Preferences> by preferencesDataStore("cyrene_app")

 enum class ThemeMode { System, Light, Dark }

 /**
- * 她正忙时按发送的行为（协同项 A2，契约 v0.56 §3.1 的 `interrupt.scope`）。
+ * 她忙时发消息的行为（协同项 A2，契约 v0.56 §3.1 的 `interrupt.scope`；忙时并行规范 §2.2 的
+ * `chat.parallel`）。
 *
- * @property wireScope 上行 `interrupt` 帧的 `scope` 取值；`null` = **整键省略**
- *   （服务端视同 `"all"`，与加入 `scope` 之前那条帧逐字节相同）。
+ * 类型名与落盘键（`interrupt_mode`）都是**历史名字**：第三档「并行」接上来之后它管的不再只是打断，
+ * 但改类型名 / 键名 / 既有档位的 `name` 都会让已存偏好读不出来并**静默回落**默认档——所以三个名字
+ * 一个都不动（见 [toInterruptMode] 与 `InterruptModeTest` 的「落盘名稳定」那几条）。
+ *
+ * 一档同时表达**两个上行声明**：[wireScope] 与 [wireParallel]。三档各占一种组合——打断占前者、
+ * 并行占后者、追加队列两个都不占，**没有任何一档同时给两个**。
+ *
+ * @property wireScope 上行 `interrupt` 帧的 `scope` 取值；`null` = **不发打断帧**。注意它不是
+ *   「发一条省略 scope 的帧」——那在服务端是 `"all"`（连待处理队列一起清），是完全不同的语义。
+ * @property wireParallel 这条 `chat` 要不要声明 `parallel:true`；`false` = **一个字节都不带**。
 */
-enum class InterruptMode(val wireScope: String?) {
+enum class InterruptMode(val wireScope: String?, val wireParallel: Boolean) {

    /**
-     * 追加队列（默认）：忙时只把消息排进队列，不打断在跑回合。
+     * 追加队列（默认）：忙时只把消息排进队列，不打断也不并行。
     *
-     * 该模式**不发** `interrupt`；一旦因别的触发点要发，就用省略 `scope` 的旧形状
-     * （服务端 = `all`：取消在跑回合 + 清空待处理队列）——这是与旧版逐字节兼容的那一档。
+     * 该模式**两个声明都不发**（`interruptScopeForSend` 恒为「不发」、`parallelForSend` 恒为
+     * `false`）：默认档的线上请求与本偏好存在之前**逐字节相同**。
     */
-    AppendQueue(null),
+    AppendQueue(wireScope = null, wireParallel = false),

    /**
     * 打断：只取消在跑回合、**保留**待处理队列（`scope:"current"`）。
     * 队列里的消息按编排器正常续跑规则继续执行，一条都不丢。
     */
-    Interrupt("current"),
+    Interrupt(wireScope = "current", wireParallel = false),
+
+    /**
+     * 并行：忙时**不打断**在跑的那一路，本条**另起一路**同时处理（`chat.parallel=true`）；
+     * 服务端并发额度满时**不报错**，这一条落回排队。
+     *
+     * [wireScope] 为 `null` 不是因为「这一档没什么要发的东西」（它当然要发东西，发的是
+     * `chat.parallel`），而是因为**并行与打断互斥**：这一档**绝不允许**产生 `interrupt` 帧——
+     * 一产生就等于先把要并行的那一路砍掉。
+     *
+     * 代价：两路各算一遍 ⇒ 峰值算力 / token 近翻倍（主人 2026-10-05 裁决 4：不分摊、优先性能），
+     * 所以设置页这一栏的 summary 把这句代价明说出来。
+     */
+    Parallel(wireScope = null, wireParallel = true),
 }

+/**
+ * 落盘字符串 → 档位（`AppSettings` 的 `interrupt_mode` 键读取口；抽成顶层函数是为了能单测——
+ * `AppSettings` 本体要 Android + DataStore，单测里起不来）。
+ *
+ * 缺省 / 旧版本遗留的未知值一律解成默认档（追加队列），绝不悄悄换成更激进的档位。
+ */
+fun String?.toInterruptMode(): InterruptMode = when (this) {
+    InterruptMode.Interrupt.name -> InterruptMode.Interrupt
+    InterruptMode.Parallel.name -> InterruptMode.Parallel
+    else -> InterruptMode.AppendQueue
+}
+
+/**
+ * 「免打扰」（[AppPrefs.proactiveQuiet]）没有落盘值时的取值 —— **`false` = 都弹**（横幅 + 提示音
+ * + 通知栏条目）。老安装、或从没碰过这个开关的用户走的都是它。
+ *
+ * 两条路必须落在**同一个**值上：[AppPrefs] 那个数据类的默认参数（进程刚起来、还没读到盘时用），
+ * 与 [toProactiveQuiet]（盘上没有这个键时用）。分叉的症状是「开关显示关着、行为却是安静的」
+ * ——一个默认就安静的 App 会让人以为通知坏了。
+ */
+internal const val PROACTIVE_QUIET_DEFAULT = false
+
+/**
+ * 落盘布尔 → 免打扰开关（`AppSettings` 的 `proactive_quiet` 键读取口；抽成顶层函数是为了能单测
+ * ——`AppSettings` 本体要 Android + DataStore，单测里起不来）。缺省 / 盘上没有这个键
+ * ⇒ [PROACTIVE_QUIET_DEFAULT]。
+ */
+internal fun Boolean?.toProactiveQuiet(): Boolean = this ?: PROACTIVE_QUIET_DEFAULT
+
 /**
 * App 级偏好（非机密）。
 *
@@ -45,12 +102,20 @@ enum class InterruptMode(val wireScope: String?) {
 * @param showNarration 是否显示 `<action>` / `<narration>` 旁白
 * @param thinkingExpanded 思维链卡片默认是否展开
 * @param interruptMode 她正忙时按发送的行为（默认追加队列）
+ * @param keepAliveEnabled 后台保持连接（常驻一条前台服务，**默认关**；判据见
+ *   `core.keepalive.shouldKeepAliveRun`）
+ * @param proactiveQuiet 免打扰：她主动找你说话**只在通知栏提示，不在屏幕顶部弹横幅**（**默认
+ *   `false` = 都弹**）。⚠️ 它的语义**不是静音**：提示音与通知栏条目照旧，只是不盖住用户正在做的
+ *   事。落地形状是**换一条渠道**（见 `core.notify.proactiveChannelId`）——横幅由渠道重要级决定，
+ *   而重要级建完就改不了，所以只能两条渠道切着用
 */
 data class AppPrefs(
    val themeMode: ThemeMode = ThemeMode.System,
    val showNarration: Boolean = true,
    val thinkingExpanded: Boolean = true,
    val interruptMode: InterruptMode = InterruptMode.AppendQueue,
+    val keepAliveEnabled: Boolean = false,
+    val proactiveQuiet: Boolean = false,
 )

 /** 全局注入 App 偏好，供聊天渲染等深层组件读取。 */
@@ -60,15 +125,45 @@ class AppSettings(context: Context) {

    private val store: DataStore<Preferences> = context.applicationContext.appDataStore

+    /**
+     * 与 `AppSettings` 同寿的收集 scope —— 也就是**与进程同寿**（`AppContainer` 在
+     * `Application.onCreate` 里建它）。刻意**不取消**：[current] 的下一个读者可以是任何时刻的
+     * 任何一次通知落地，没有比进程结束更晚的时刻需要它。
+     */
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+
    val data: Flow<AppPrefs> = store.data.map { prefs ->
        AppPrefs(
            themeMode = prefs[KEY_THEME_MODE].toThemeMode(),
            showNarration = prefs[KEY_SHOW_NARRATION] ?: true,
            thinkingExpanded = prefs[KEY_THINKING_EXPANDED] ?: true,
            interruptMode = prefs[KEY_INTERRUPT_MODE].toInterruptMode(),
+            keepAliveEnabled = prefs[KEY_KEEP_ALIVE] ?: false,
+            proactiveQuiet = prefs[KEY_PROACTIVE_QUIET].toProactiveQuiet(),
        )
    }

+    /**
+     * [data] 的**热副本**：进程里任何地方都读得到「当下是什么偏好」。
+     *
+     * ## 为什么需要它
+     * 发通知那一刻**没有挂起上下文**：帧的落地是一次同步回调（`ProactiveNotifier.post` 不是
+     * `suspend`，也不该是——它是连接那条已建立的流水线上的最后一跳），而 DataStore 的读取是挂起
+     * 的。所以只能由这里常驻订阅、把最近一次读数摆在一个同步读得到的地方（`StateFlow.value`）。
+     *
+     * ## 为什么是 `Eagerly`
+     * 它的读者（发通知那条路）随时可能来，而「等有人订阅了再开始读」意味着第一次落地时读到的是
+     * 初始值。`Eagerly` 让这一次读盘在设置对象构造时就发生 —— 与 UI 那边（`CyreneRoot` /
+     * `SettingsScreen` 各自 `collectAsState`）读的是同一份上游数据，没有多出一次磁盘 IO 的量级。
+     *
+     * ⚠️ 它有一个**毫秒级**的不准确窗口：进程刚起来、第一次读盘还没回来时，[StateFlow.value] 是
+     * [AppPrefs] 的默认值（免打扰 = false ⇒ 弹横幅）。要撞上它，得在「本对象构造完 → DataStore
+     * 第一次读完」之间就有一条她的主动消息走完建连、认证、收帧（`ProactiveFrameIntake`）——
+     * 实际上到不了那么快。**代价封顶是「开了免打扰的用户在冷启动瞬间多看到一次横幅」**，
+     * 而不是丢通知。
+     */
+    val current: StateFlow<AppPrefs> = data.stateIn(scope, SharingStarted.Eagerly, AppPrefs())
+
    suspend fun setThemeMode(mode: ThemeMode) {
        store.edit { it[KEY_THEME_MODE] = mode.name }
    }
@@ -85,22 +180,31 @@ class AppSettings(context: Context) {
        store.edit { it[KEY_INTERRUPT_MODE] = mode.name }
    }

+    suspend fun setKeepAliveEnabled(enabled: Boolean) {
+        store.edit { it[KEY_KEEP_ALIVE] = enabled }
+    }
+
+    /**
+     * 写「免打扰」。**写这一处就够了**：发通知那条路每次现读 [current]（见它的 KDoc），所以这里
+     * 一落盘、DataStore 一发出新值，**下一条**通知就走新渠道——不必重启 App，也不必在这里再去
+     * 通知谁。
+     */
+    suspend fun setProactiveQuiet(enabled: Boolean) {
+        store.edit { it[KEY_PROACTIVE_QUIET] = enabled }
+    }
+
    private fun String?.toThemeMode(): ThemeMode = when (this) {
        ThemeMode.Light.name -> ThemeMode.Light
        ThemeMode.Dark.name -> ThemeMode.Dark
        else -> ThemeMode.System
    }

-    /** 缺省 / 旧版本遗留的未知值一律解成默认档（追加队列），绝不悄悄换成更激进的档位。 */
-    private fun String?.toInterruptMode(): InterruptMode = when (this) {
-        InterruptMode.Interrupt.name -> InterruptMode.Interrupt
-        else -> InterruptMode.AppendQueue
-    }
-
    private companion object {
        val KEY_THEME_MODE = stringPreferencesKey("theme_mode")
        val KEY_SHOW_NARRATION = booleanPreferencesKey("show_narration")
        val KEY_THINKING_EXPANDED = booleanPreferencesKey("thinking_expanded")
        val KEY_INTERRUPT_MODE = stringPreferencesKey("interrupt_mode")
+        val KEY_KEEP_ALIVE = booleanPreferencesKey("keep_alive_enabled")
+        val KEY_PROACTIVE_QUIET = booleanPreferencesKey("proactive_quiet")
    }
 }
@@ -20,7 +20,7 @@ private val Context.sessionDataStore: DataStore<Preferences> by preferencesDataS
 *
 * @param snapshot 上次成功拉取的会话列表；服务端不可用时用它先渲染
 * @param snapshotAt 快照时间（用于「同步于 N 分钟前」）
- * @param fingerprint `baseUrl + username`；换服务器/账号后快照作废
+ * @param fingerprint [accountFingerprint]：换服务器/账号后快照作废
 * @param activeSessionId 上次停留的会话
 */
 data class SessionPrefs(
@@ -35,6 +35,20 @@ data class SessionPrefs(
        snapshot.takeIf { this.fingerprint == fingerprint }.orEmpty()
 }

+/**
+ * 账号指纹（纯函数）：`baseUrl + username`。回答的是「**这份本地状态属于哪个环境**」。
+ *
+ * 抽成一个函数的理由是**全仓只能有一份口径**：这类判据一旦各拼一套字符串，差一个分隔符
+ * 就会在某个闸门上漏过去——而漏过去的后果是把别的服务器/账号的内容摆到屏幕上。
+ * 现在的两个消费者是 [SessionPrefs.snapshotFor]（会话快照作不作废）与聊天页的 VM key
+ * （`chatViewModelKey`：那个 VM 是不是本环境的）。改口径就是改**两者**，不要就地另拼。
+ *
+ * 取用户名而不是角色：角色是同一个人在服务端被授的权限，账号身份由**服务器地址 + 用户名**
+ * 共同确定；要让指纹对不上，只能是换了服务器或换了账号，那两件事都该让本地状态作废。
+ */
+internal fun accountFingerprint(baseUrl: String, username: String?): String =
+    "$baseUrl|${username.orEmpty()}"
+
 class SessionPreferences(context: Context) {

    private val json = ApiClientFactory.json
@@ -0,0 +1,100 @@
+package top.yeij.cyrene.core.session
+
+/**
+ * 本端**同时**为一个账号留几个会话槽位（N=3，[chatSessionEvictions] 的默认 `keep`）。
+ *
+ * 为什么是 3（**主人拍板的口径**）：它要在「切回去时那几屏东西还在」与「不留着一堆没人再看的
+ * 消息列表」之间取一个数。驱动这个数的是**内存**——每个槽位留着一整页已落库消息（次级会话里可能
+ * 是内联 base64 图片），而 S4 登记的正是「访问过的会话一个都不回收」。不跟着会话数走的理由也在
+ * 这里：它是内存上限，不是「用户可能有多少会话」。
+ */
+const val CHAT_SESSION_SLOT_KEEP = 3
+
+/**
+ * 一格槽位在**被判定那一刻**的样子（[chatSessionEvictions] 的入参，**纯值**）。
+ *
+ * 三项都由调用方现读现喂，判据自己不看 VM、不读表、不碰时钟（先例：`ui.sessions.silentRefreshStep`
+ * 只回结论，账本与时钟都由调用方喂）——所以它在 JVM 上可以穷举。
+ *
+ * @param key 槽位的稳定标识（`账号指纹|会话 id`）。它就是**结论的载体**：判据只把它原样列出来，
+ *   「拿这个 key 去哪里找槽位」是调用方的事。
+ * @param sessionId 会话 id。**它和 [key] 不是同一件事**：key 里还带着账号指纹（换账号之后同一个
+ *   会话 id 是另一格），而这一位只回答一个问题——**它是不是主会话**（主会话永不回收，见
+ *   [chatSessionEvictions] 第 1 条）。两样都留着是刻意的：把「主会话」这件事换个说法搬出判据，
+ *   它就再也钉不住了（那是本任务的红线之一）。
+ * @param lastUsedAt **最后一次成为当前会话**的时刻（毫秒）。「最近」的口径就是它，理由见
+ *   [chatSessionEvictions]。`0` = 建出来还没打开过（组合被丢弃时留下的空槽位）。
+ * @param holdsUnsentWork 这一格里还有**本端唯一一份**的内容（没发出去的草稿 / 没上路的发送）。
+ *   它必须一路传到这里，是因为「回收」是一条**回不来**的动作：判据要在动手之前就能拦下
+ *   「把用户还没发出去的字一起收掉」——那比「多留一格」严重得多（红线：不许静默丢内容）。
+ */
+internal data class ChatSessionUsage(
+    val key: String,
+    val sessionId: String,
+    val lastUsedAt: Long,
+    val holdsUnsentWork: Boolean,
+)
+
+/**
+ * 这一刻该交出去哪几格（**纯函数**，[ChatSessionSlots] 与测试共用）。返回**要回收的槽位 key**，
+ * 最该走的在最前（最旧的最先）；没有要回收的就返回空表。
+ *
+ * ## 「最近」的口径：最后一次**成为当前会话**的时刻
+ * 三选一里选的它，理由是另外两个都答不对这个问题：
+ * - 「最后一次收到这个会话的帧」**不是用户的活动**：共享连接上别的会话的帧一直在来（服务端不按
+ *   会话订阅），一条后台广播就能把一个用户根本没再打开过的会话顶成「最近」。
+ * - 「最后一次有新消息」同理，而且是**别人**的活动（她在次级会话里说一句，本端就要为它留一格）。
+ * - 「最后一次成为当前会话」才是「用户切回去时希望看到什么」这件事本身：槽位存在的意义就是
+ *   那一屏不用重新加载，而**用户看得见哪个会话**只有这一个时刻能表达。
+ *
+ * 它由 `ChatScreen` 在**组合到某个会话时**写入（那正是「它成了当前会话」这一刻），所以判据这边
+ * 只需要比大小，不需要任何时钟：谁的时刻新，谁就留下。同一毫秒并列时按**账本里的先后**退回
+ * （[usages] 的顺序 = 槽位被建出来的顺序，见 [ChatSessionSlots]），也就是「谁先建谁先走」。
+ *
+ * ## 判据与优先级（自上而下，先命中先返回）
+ * 1. **主会话永不回收**：它是抽屉与主流程的锚——用户随时会退回它，而它那一格正是「一进 App
+ *    就有东西看」的来处。这一条**不看** `keep`，也不占「最近」的名额：主会话就是主会话，
+ *    不看它多久没被打开过。
+ * 2. **屏幕上那一格永不回收**（`key == [currentKey]`）：它的 VM 一死，屏幕上那一段就再也不会更新
+ *    （帧收不到、`viewModelScope` 已经取消 ⇒ 连发送都会静默不发），要等下一次重组才会自己修回来
+ *    —— 那是「回收」绝不能带来的一种状态。这一条与主会话同属「按身份豁免」，与时刻无关
+ *    （[currentKey] 那一格通常本来就是最新的，但不靠这件事成立）。
+ * 3. **还有没交代完的事的槽位不回收**（[ChatSessionUsage.holdsUnsentWork]）：那些内容只在本端
+ *    这一份（草稿、排队等连接的发送），回收掉就**回不来**了。这一条压过 `keep` 的语义——
+ *    它宁可让本端多留一格，也不做一件不可逆的事。
+ * 4. 其余按 [ChatSessionUsage.lastUsedAt] 从新到旧留 `keep` 格，**连上面三条占住的一起算**：
+ *    `keep` 是「本端同时保留几格」这个内存目标，所以被豁免的那些**占名额**——不然「最多 3 格」
+ *    在豁免生效时会变成 3 + 豁免数，那个数就没有上限了。（真实使用里豁免的那些几乎总是
+ *    「刚刚还在用的」，本来就在最近 3 个里，这条只在极端情况下才真的挤掉谁。）
+ *
+ * 判据里除了这些入参什么都不看，才能穷举、才能在 JVM 上单测（先例：`ui.chat.reconnectPull`、
+ * `ui.sessions.silentRefreshStep`）。
+ *
+ * ## ⚠️ 它**只**回答「交出去哪几格」
+ * 「交出去」具体是什么动作（清掉那份 `ViewModelStore`、于是这一格的 VM 随 `onCleared` 一起走）
+ * 是调用方的事，而且**必须**是那份 store 自己的 `clear()`：连接是全 App 共享的那一条，它的生死
+ * 只由登录态表达（主人是 `SessionsViewModel`），回收一格**绝不能**碰它——回收一格的状态与
+ * 「别人的流、别人的未读」是两件事，这条判据里连一个字节的连接概念都没有。
+ *
+ * @param usages 账本里的全部槽位（顺序有意义，见「同一毫秒并列」那一句）。
+ * @param mainSessionId 主会话的 id（由装配处注入，判据不认识那个常量本身）。
+ * @param currentKey **此刻屏幕上**那一格的 key（[ChatSessionSlots] 刚记完账的那一格）。
+ * @param keep 本端**同时**保留几格（含主会话、屏幕上那一格与「还有没交代完的事」的那些），
+ *   默认 [CHAT_SESSION_SLOT_KEEP]。
+ */
+internal fun chatSessionEvictions(
+    usages: List<ChatSessionUsage>,
+    mainSessionId: String,
+    currentKey: String,
+    keep: Int = CHAT_SESSION_SLOT_KEEP,
+): List<String> {
+    val reclaimable = usages
+        .filter {
+            it.sessionId != mainSessionId && it.key != currentKey && !it.holdsUnsentWork
+        }
+        .sortedBy { it.lastUsedAt }
+    val budget = keep - (usages.size - reclaimable.size)
+    val surplus = reclaimable.size - budget
+    if (surplus <= 0) return emptyList()
+    return reclaimable.take(surplus).map { it.key }
+}
@@ -0,0 +1,184 @@
+package top.yeij.cyrene.core.session
+
+import androidx.lifecycle.ViewModelStore
+import androidx.lifecycle.ViewModelStoreOwner
+
+/**
+ * 本端留着的**会话槽位**（`账号指纹|会话 id` → 那一格的聊天状态）。S4 的解药。
+ *
+ * ## 它回答的是哪一个问题
+ * `ChatViewModel` 是**按会话**建的（`sessionId` 是构造参数），于是「切走 / 删会话都不回收」意味着
+ * 访问过 N 个会话就常驻 N 份消息列表（含内联 base64 图片）、N 份对共享连接的订阅、以及**每次重连
+ * 各自一轮** `after` 补拉。这里就是那个「N」的闸门：**一格一个 `ViewModelStore`**，超出的按
+ * [chatSessionEvictions] 的结论交出整格。
+ *
+ * ## 为什么一格一个 `ViewModelStore`（而不是给 key 加一代号）
+ * 回收的本体动作是「让那一格的 VM 真正死掉」：`ViewModelStore.clear()` 会走 `ViewModel.onCleared()`
+ * 并取消 `viewModelScope`——于是**订阅、补拉、正在飞的那些请求一起停下**。此前每一格都塞在
+ * Activity 级那个 store 里，而它**只有整体 `clear()`**，没有「按 key 交出一格」的入口：那种情况下
+ * 只能让 key 换一代、把旧实例**留在 store 里**（它照样活着、照样收帧——那正是 S4 的另一半没修掉
+ * 的样子）。一格一份 store 之后，`clear()` 的粒度就正好是「这一格」。
+ *
+ * ## 回收**不碰**共享连接
+ * 连接是全 App 唯一的那一条（`AppContainer.chatSocket`），它的生死只由登录态表达
+ * （主人是 `SessionsViewModel`）。本类碰的只有「自己那一格的 store」：掐掉的是这一格的订阅，
+ * 别的会话的流、别的会话的未读、以及那条连接本身一个字节都不动。
+ *
+ * ## 谁碰它、什么时候（全部在主线程上）
+ * - **`ChatScreen`**：组合到某个会话时 [slotFor] 取（或建）槽位——VM 必须有地方建，而槽位就是
+ *   那一格的存放处，所以这一步没法挪到组合之后；组合完成之后 [onOpened] 记账 + 回收。
+ * - **`SessionsViewModel`**：本端**唯一**的删除入口，删成功后 [reclaim]（那一格跟着会话一起走）；
+ *   登出 / 换账号时 [clear]（与快照 / 已读游标 / [GoneSessions] 同一档：换代之后本端什么都不知道）。
+ * - 三者都在主线程上（组合、`viewModelScope` 的默认派发器），所以账本本身不加锁——它的每一个
+ *   读写点都在同一个线程上。
+ *
+ * ## 为什么不持久化
+ * 槽位里装的是**进程内存里的状态**（消息列表、草稿、流式缓冲），它没有可以落盘的形式，而它的
+ * 内容全部另有来源（服务端的 `GET /messages` 那一页 + 服务端的幂等键）。重启之后本端重新拉，
+ * 与 [GoneSessions] 「不持久化」是同一个理由。
+ */
+class ChatSessionSlots(private val mainSessionId: String) {
+
+    /**
+     * 账本。用 `LinkedHashMap` 只为一件事：**同一毫秒并列**时 [chatSessionEvictions] 的稳定排序会
+     * 退回这个插入顺序（先建出来的先走）。除此之外顺序不表达任何东西——「谁最近」一律看
+     * [ChatSessionSlot] 里的 `lastUsedAt`。
+     */
+    private val slots = linkedMapOf<String, ChatSessionSlot>()
+
+    /**
+     * 取这个会话的槽位（没有就建一个）。**组合期间**调用。
+     *
+     * 它**不记账**：谁最近用过由 [onOpened] 写。所以就算这一段组合被丢弃（组合没走完），留下的也
+     * 只是一个 `lastUsedAt` 还是 `0` 的空槽位，下一次回收就会把它扫掉（它必然是最旧的那一格）。
+     */
+    fun slotFor(account: String, sessionId: String): ChatSessionSlot =
+        slots.getOrPut(keyOf(account, sessionId)) { ChatSessionSlot(sessionId) }
+
+    /**
+     * 这个会话**刚刚成为当前会话**：记下它是「最近」的那一格，然后按 [chatSessionEvictions] 回收。
+     *
+     * 记账与回收在同一处，是因为回收的判据就是这份账本本身（先例：`ui.sessions.silentRefreshStep`
+     * 把「该做什么」与「账本走成什么样」一起回）：拆开就会给出「判了却忘了推进账本」的机会，
+     * 而那正好会让最该留下的那一格被当成最旧的收掉。同一处也才拿得到那个 key —— 判据要
+     * **按身份**豁免的就是刚记完账这一格（`chatSessionEvictions` 的 `currentKey`）。
+     *
+     * @param holdsUnsentWork 现读的一格真相（见 [ChatSessionUsage.holdsUnsentWork]）。收的是一个
+     *   **探针**而不是一个布尔快照，是因为回收发生在**别的**会话被打开的那一刻 —— 而那一刻正是
+     *   用户可能刚在前一个会话里打了草稿、还没切走的时候。快照会把它读成「干净」，把没发出去的
+     *   字一起回收掉（那是一条回不来的动作）。
+     */
+    fun onOpened(
+        account: String,
+        sessionId: String,
+        holdsUnsentWork: () -> Boolean,
+        nowMillis: Long,
+    ) {
+        val key = keyOf(account, sessionId)
+        slotFor(account, sessionId).opened(holdsUnsentWork, nowMillis)
+        sweep(currentKey = key)
+    }
+
+    /**
+     * 定点回收一格（删会话）：把那份 store 交出去，那个 VM 随 `onCleared` 一起走，本类不再引用它。
+     *
+     * 与 [GoneSessions] 的关系：那是「本端已知它没了」这件事的**第一半**（让还活着的 VM 别再去发
+     * 注定 404 的补拉），这里是**第二半**（那一格本来就该跟着会话一起消失）。两半分开写在两处，
+     * 是因为它们回答的问题不同——一个答「还值不值得发请求」，一个答「还留不留这一格状态」，
+     * 而后者要动 VM 的生命周期，不该被前者拽住（`ui.chat.reconnectPull` 只读前者）。
+     */
+    fun reclaim(account: String, sessionId: String) {
+        slots.remove(keyOf(account, sessionId))?.clear()
+    }
+
+    /**
+     * 换账号 / 登出：本端**一格都不留**。
+     *
+     * 与快照 / 已读游标 / [GoneSessions] 是同一档纪律（`SessionsViewModel` 的登出分支一处清完）：
+     * 槽位里的东西全部属于**上一个环境**，留着只会在下一次登录后变成一份没人认领的常驻内存
+     * （而它带着的那个 VM 还在订阅连接、还会在重连时补拉）。这一条也顺带把 [ChatSessionSlot] 的
+     * 那条「主会话永不回收」的例外收干净：换账号时连主会话那一格也不留。
+     *
+     * 代价说清楚：登出（含令牌失效那条路径）之后**本端未发出的草稿会跟着没了**。这与既有口径一致
+     * ——登出时快照、已读游标、已删会话的结论都是当场清掉的（那些也都没落盘）。
+     */
+    fun clear() {
+        slots.values.forEach { it.clear() }
+        slots.clear()
+    }
+
+    /**
+     * 按 [chatSessionEvictions] 的结论交出超出的那几格（「最近」的口径见那个函数的 KDoc）。
+     *
+     * @param currentKey 刚记完账、此刻在屏幕上那一格的 key（它按身份豁免，见判据第 2 条）。
+     */
+    private fun sweep(currentKey: String) {
+        val usages = slots.map { (key, slot) -> slot.usage(key) }
+        chatSessionEvictions(usages, mainSessionId, currentKey)
+            .forEach { key -> slots.remove(key)?.clear() }
+    }
+
+    /** 与聊天页的 VM key 无关：这是**槽位**的身份，账号指纹在里面是为了换账号时天然分格。 */
+    private fun keyOf(account: String, sessionId: String): String = "$account|$sessionId"
+}
+
+/**
+ * 一个会话的槽位：**它自己的那份 `ViewModelStore`**，外加这项回收策略要的两个记账位。
+ *
+ * 装在这里的 VM 由 `ChatScreen` 经它取出（`viewModel(viewModelStoreOwner = 槽位, key = <账号指纹|会话 id>)`）：
+ * key 仍然是 `chatViewModelKey` 那一份口径，只是现在**配着一份按会话分的 store** 用。
+ *
+ * 它**不持有** VM 的类型：本类只知道「怎么把这一格交出去」（[clear]）与「它还有没有没交代完的事」
+ * （[opened] 收下的那个探针）。这样 `core.session` 不必认识 `ui.chat` 的任何类型，而两件事
+ * ——「槽位怎么算最近」与「VM 里哪一位算没交代完」——各自待在自己那一层。
+ */
+class ChatSessionSlot internal constructor(
+    /** 本槽位的会话 id（槽位身份的一半：账号指纹在 [ChatSessionSlots] 的账本 key 里）。 */
+    val sessionId: String,
+) : ViewModelStoreOwner {
+
+    private val store = ViewModelStore()
+
+    override val viewModelStore: ViewModelStore
+        get() = store
+
+    /**
+     * 最后一次成为当前会话的时刻（毫秒）；`0` = 建出来还没打开过。**只增不改**。
+     *
+     * 由 `ChatSessionSlots.onOpened` 写（那里是「它成了当前会话」的唯一表达处），本类不自己读时钟。
+     * 不进 [usage] 以外的任何地方——「最近」的判据只认它，而判据只吃 [ChatSessionUsage]。
+     */
+    private var lastUsedAt: Long = 0L
+
+    /**
+     * 这一格里「还有没有没交代完的事」的**现读**探针（见 [ChatSessionSlot.opened] 的说明）。
+     * 默认恒 `false`：还没打开过的一格当然没有。
+     */
+    private var holdsUnsentWork: () -> Boolean = { false }
+
+    /** 这一格成了当前会话：记下该问谁「还有没有没交代完的事」，并更新「最近」这一位。 */
+    internal fun opened(holdsUnsentWork: () -> Boolean, nowMillis: Long) {
+        this.holdsUnsentWork = holdsUnsentWork
+        lastUsedAt = nowMillis
+    }
+
+    /** 交给判据的样子（判据不认识本类，见 [ChatSessionUsage]）。 */
+    internal fun usage(key: String): ChatSessionUsage = ChatSessionUsage(
+        key = key,
+        sessionId = sessionId,
+        lastUsedAt = lastUsedAt,
+        holdsUnsentWork = holdsUnsentWork(),
+    )
+
+    /**
+     * 交出这一格：`ViewModelStore.clear()` ⇒ 那一格的 `ViewModel.onCleared()` + `viewModelScope`
+     * 取消（订阅、补拉、在飞的请求一起停），随后**松开探针**。
+     *
+     * 松开探针不能省：它捕获着那个 VM（否则就成了一份「已经交出去、却还被人拎着」的引用，
+     * 那一格的消息列表会跟着这条引用活到进程结束——正是本类要断掉的那根线）。
+     */
+    internal fun clear() {
+        store.clear()
+        holdsUnsentWork = { false }
+    }
+}
@@ -0,0 +1,53 @@
+package top.yeij.cyrene.core.session
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.update
+
+/**
+ * 本端**已经知道服务端没有这个会话**的那几个会话 id（进程级、只在内存里、只增不减）。
+ *
+ * ## 它回答的是哪一个问题
+ * 「这个 id 还值不值得我发一次请求」。`ChatViewModel` 是按会话建的，本端**同时**留着其中几格
+ * （W52A 起是 `ChatSessionSlots` 的 N 格），它们都订阅同一条共享连接 ⇒ **每次重连各自会去补拉
+ * 一轮**。会话在本端被删掉之后，那个 VM 自己并不知道（它没有别的渠道知道），于是**每一个**重连
+ * 都发一次注定 `404 session_not_found` 的补拉，404 被静默吞掉（S7 登记的那一条）。
+ *
+ * 补拉**事前**就能判掉它，靠的就是这里：删除是**本端自己做的**，那一刻就已经知道结果了，
+ * 没有任何理由等下一条请求回来才「发现」。于是这一位把「已知不存在」从「一次注定失败的往返」
+ * 提前成「一次本地查询」——**不是**「重连时少拉一点」的省流量优化，而是不让一个注定失败的请求
+ * 上路（它会占一条连接、写一行日志、并把 `sessionGone` 变成一个只能靠 404 才置得起来的位）。
+ *
+ * W52A 又给这件事加了一半：删会话时那一格**当场就被回收**（`ChatSessionSlots.reclaim`），所以
+ * 大多数情况下这里拦的已经是一个不会再发生的补拉。它仍然留着，因为两件事回答的不是一个问题
+ * ——这一位答「还值不值得发请求」，槽位答「还留不留这一格状态」，而**本端删掉一个会话**与
+ * **那个会话在别处被删掉**（只能靠 404 发现）是两条不同的路，后者压根不经过这里。
+ *
+ * ## 为什么是进程级、为什么**不**持久化
+ * - 进程级（挂在 `AppContainer` 上，与那条共享连接同一层）：写它的是 `SessionsViewModel`
+ *   （本端唯一的删除入口），读它的是**别的** VM —— 两个 VM 之间没有别的共享面。
+ * - **不持久化**：它只是「这一趟进程里已经知道的事」。重启之后本端的会话列表会重新从服务端拉
+ *   （[top.yeij.cyrene.core.prefs.SessionPreferences] 那份快照本来就会整体替换），「这个会话还在不在」
+ *   以那一次服务端答复为准；把 id 落盘只会让一份陈旧记忆挡掉重启后的第一次拉取。
+ * - **换账号要清**（[clear]）：id 是服务端铸的，理论上不会跨账号撞车，但这一位说的是「本端
+ *   已经知道」，而换账号之后本端**什么都不知道** —— 留着上个环境的结论，是那种「差一个分隔符
+ *   就漏过去」的同一类错误（先例：`accountFingerprint` 的注释）。同一处也清聊天页的槽位
+ *   （`ChatSessionSlots.clear`），两件事属同一档纪律。
+ */
+class GoneSessions {
+
+    private val ids = MutableStateFlow<Set<String>>(emptySet())
+
+    /** 记下「服务端已经没有这个会话了」。空串当无效值丢掉（那不是任何会话的 id）。 */
+    fun mark(sessionId: String) {
+        if (sessionId.isBlank()) return
+        ids.update { it + sessionId }
+    }
+
+    /** 本端是否**已经知道**它没了。只回答「知道不知道」，不回答「在不在」——不知道的一律 `false`。 */
+    fun contains(sessionId: String): Boolean = sessionId in ids.value
+
+    /** 换账号 / 登出：本端重新回到「什么都不知道」。 */
+    fun clear() {
+        ids.value = emptySet()
+    }
+}
@@ -15,6 +15,32 @@ import retrofit2.Retrofit
 import retrofit2.converter.kotlinx.serialization.asConverterFactory
 import java.util.concurrent.TimeUnit

+/**
+ * **连接超时**（毫秒）：解析 DNS + 建立 TCP 连接（以及 TLS 握手）这一段的预算，**全端共用这一个值**。
+ *
+ * ## 为什么从 10 秒缩到 2.5 秒（W45）
+ * 它就是「**完全无网时快速进队列**」这条性质的唯一依据。W41 把这条性质寄托在一个 2.5 秒的探针上
+ * （W41 那个探针 client 的 `callTimeout`），而那个探针**从不复用连接池**、每次都要现做一次冷握手
+ * ——于是真机上出现了「探了，但请求一个字节都没写出去」，而它与「压根没探」在外部完全同形，推断
+ * 不出是哪一档。W45 删掉探测、改成**直接试 REST** 之后，这条性质改由**连接超时**承担：连不上就在 2.5 秒
+ * 内失败，消息进队列（内容一个字节都不丢，重发仍是同一个 `clientMsgId`）。
+ *
+ * 取值 2.5 秒：正常网络下一次 TCP 握手是毫秒到几十毫秒量级（局域网、ZeroTier / Tailscale 也远达
+ * 不到秒级），2.5 秒是「人开始觉得卡」之前的量级，也与 W41 那 2.5 秒的探针预算**对齐**——换成直接
+ * 试 REST 之后，「无网时用户最多等多久」因此没有变长。**绝不许**再回到 10 秒：那会让每一条离线
+ * 消息的用户都白等十倍的时间，换来的只是「极端慢网下多一次成功的机会」。
+ *
+ * ## 它不管什么
+ * 「连上了但服务端一直不回话」（半死的代理、接住连接却不回应）不是它的事——那是读 / 写超时
+ * （[READ_TIMEOUT_SECONDS]）与回落那一次投递自己的整通上限
+ * （[top.yeij.cyrene.ui.chat.REST_FALLBACK_TIMEOUT_MILLIS]）的事。两个闸各管一段，合起来才是
+ * 「没网时用户最多等多久」。
+ */
+const val CONNECT_TIMEOUT_MILLIS = 2_500L
+
+/** 读 / 写超时（秒）：真请求（长文本、内联图片、文档字节）的耐心，与 [CONNECT_TIMEOUT_MILLIS] 分开。 */
+private const val READ_TIMEOUT_SECONDS = 60L
+
 object ApiClientFactory {

    val json: Json = Json {
@@ -30,7 +56,20 @@ object ApiClientFactory {
        unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
    ): CyreneApi = create(baseUrl, CyreneApi::class.java, tokenProvider, unauthorizedPolicy)

-    /** 通用入口：按需构建任意 Retrofit service。 */
+    /**
+     * 通用入口：按需构建任意 Retrofit service。
+     *
+     * 超时**只有两个值**，都由文件顶上的常量解释：连接 [CONNECT_TIMEOUT_MILLIS]（短，保证「完全
+     * 无网时快速失败」）、读 / 写 [READ_TIMEOUT_SECONDS]（长，真请求的耐心）。**刻意不设
+     * `callTimeout`**：那会把文档字节下载与图片上传一并框住，而它们本来就是长请求；哪一次投递需要
+     * 整通上限，就写在哪一次投递的调用点上（例：回落那一次的
+     * [top.yeij.cyrene.ui.chat.REST_FALLBACK_TIMEOUT_MILLIS]）。
+     *
+     * DEBUG 下挂 BASIC 日志（`logcat -s OkHttp`）：`-->` 打在 `chain.proceed()` **之前**，所以
+     * 「这条请求有没有发出去」与「死在连接还是死在回执」当场可分——回落那条路下一轮要靠它取证。
+     * 不动 `Authorization`（BASIC 根本不打印任何头），级别**绝不许**再往上调：`/auth/refresh` 与
+     * `/auth/logout` 把 refresh token 放在请求体里。
+     */
    fun <T : Any> create(
        baseUrl: String,
        service: Class<T>,
@@ -38,9 +77,11 @@ object ApiClientFactory {
        unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
    ): T {
        val client = OkHttpClient.Builder()
-            .connectTimeout(10, TimeUnit.SECONDS)
-            .readTimeout(60, TimeUnit.SECONDS)
-            .writeTimeout(60, TimeUnit.SECONDS)
+            // 连接这一段刻意短（理由见 [CONNECT_TIMEOUT_MILLIS]）：它是「无网时消息快速进队列」的
+            // 唯一依据，所以它**不含**任何整通上限的意味。
+            .connectTimeout(CONNECT_TIMEOUT_MILLIS, TimeUnit.MILLISECONDS)
+            .readTimeout(READ_TIMEOUT_SECONDS, TimeUnit.SECONDS)
+            .writeTimeout(READ_TIMEOUT_SECONDS, TimeUnit.SECONDS)
            .addInterceptor(AuthInterceptor(tokenProvider, unauthorizedPolicy))
            .apply {
                if (BuildConfig.DEBUG) {
@@ -0,0 +1,41 @@
+package top.yeij.cyrene.data.api
+
+import okhttp3.ResponseBody
+import retrofit2.Response
+import retrofit2.http.GET
+import retrofit2.http.Streaming
+import retrofit2.http.Url
+
+/**
+ * 语音副本的字节读取（契约 **v0.79 已实现**，api-client.md §1.2 **U19**
+ * `GET /api/v1/media/{name}`）。
+ *
+ * ## 鉴权：**必须** Bearer `owner|admin`
+ * 与 `GET /api/v1/documents/{name}` 同一套门，与图片读侧「128-bit 名即凭据」**刻意相反**
+ * ——语音是私密内容，那个 URL 不能直接贴进 `<audio src>`。Bearer 不在本接口上做任何事：
+ * [ApiClientFactory.create] 按 **OkHttpClient** 挂 `AuthInterceptor`，只要本接口的实例是从
+ * 那里建的（`AppContainer.mediaApi` 的写法），请求就自带令牌、并享受 401 单飞续期。
+ *
+ * ## 为什么参数是一整条 URL 而不是 `@Path name`
+ * 契约把相对路径 `/api/v1/media/<name>` 定成**服务端唯一的派生字段**（`voice.url`），并明写
+ * 客户端**绝不自己拼路径**。所以调用方把**服务端给的那条路径接到当前服务器地址上**
+ * （纯函数 `domain.chat.voiceMediaUrl`）再传进来——本接口一个字都不拼，只发出去。
+ *
+ * @see MediaRepository
+ */
+interface MediaApi {
+
+    /**
+     * 取一条语音副本的字节。
+     *
+     * 响应**不是信封**（就是音频本身），所以返回 [ResponseBody] 由仓库层读字节并负责关闭。
+     * [Streaming] 让 Retrofit 不把响应体一次性读进内存。
+     *
+     * ⚠️ 服务端的 `416`（`Range` 不可满足）是**标准库直写**的 `text/plain` + `Content-Range`，
+     * **不套** `{"error":{…}}`（契约 §0.3 / §4.5）——本端不发 `Range`、也不拿 `error.code`
+     * 去解析它，`ApiErrorMapper` 对这种非信封响应的处理是「说不出就不编」。
+     */
+    @Streaming
+    @GET
+    suspend fun download(@Url url: String): Response<ResponseBody>
+}
@@ -0,0 +1,67 @@
+package top.yeij.cyrene.data.api
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import okhttp3.ResponseBody
+import retrofit2.Response
+import retrofit2.http.Body
+import retrofit2.http.POST
+import retrofit2.http.Streaming
+
+/**
+ * 一段待朗读的文本（`POST /api/v1/audio/speech` 的请求体，api-client.md §1.2 U6 / 行 126）。
+ *
+ * ## 只有两个字段，是**刻意的**
+ * 契约给了五个键 `{text, voice?, format?, instruction?, sessionId?}`，但其中三个在本端**不生效**：
+ * - `voice`：接受但不生效 —— 发音人**不由它决定**；
+ * - `format`：不生效 —— 产物恒为 WAV（响应也明说「别照抄 `Content-Type`」，见 [SpeechApi]）；
+ * - `instruction`：只影响表达方式，本端当前的产品口径里没有「怎么说」这一档输入。
+ *
+ * 发一个服务端会忽略的键，只会让排查时多一条**看起来有含义、实际没有**的字段。所以这里只发
+ * 真正起作用的那两个 —— 尤其是 [sessionId]：发音人由它**那条会话的生效人格**解析
+ * （会话绑定人格 → 全局默认人格 → 都没有就取服务端配置的 default），**省略它不等于没有角色**。
+ *
+ * [sessionId] 为 `null` 时字段**整个缺席**（`ApiClientFactory.json` 的 `explicitNulls = false`），
+ * 而不是发一个 `"sessionId": null`。
+ */
+@Serializable
+data class SpeechRequestDto(
+    @SerialName("text") val text: String,
+    @SerialName("sessionId") val sessionId: String? = null,
+)
+
+/**
+ * 语音合成（契约 **v0.96 增量 / v0.97 补写**，api-client.md §1.2 **U6** `POST /api/v1/audio/speech`）。
+ *
+ * ## 鉴权：owner-only，双凭据门
+ * `Authorization: Bearer <owner JWT>` **或** `X-API-Key`，两个分支在服务端落到同一个
+ * `authorize(RoleOwner)`。本端只走前者（主人 2026-10-26 拍板：不设 API Key 输入框），令牌由
+ * [ApiClientFactory.create] 挂在 OkHttpClient 上的 `AuthInterceptor` 自动注入，本接口不碰它。
+ * 无 / 无效凭据 → `401`，错误体是 §4.1 那个 `{error:{code,message}}` 信封。
+ *
+ * ## 响应**不是信封**
+ * 成功是 `200` + **原始音频字节**（与 [MediaApi] 同一个形状），所以返回 [ResponseBody] 由上层
+ * 读字节并负责关闭，[Streaming] 让它不一次性读进内存。
+ *
+ * ⚠️ **产物恒为 WAV，按字节嗅探判定，不要照抄 `Content-Type`** —— 那条头的实际值不在契约里
+ * 承诺（§4.1 行 561 的同句旁注就是这个意思）。嗅探在 [top.yeij.cyrene.data.voice.SpeechClient]。
+ *
+ * 失败时的错误码（全部是 `{error:{code}}` 信封）：
+ * `400`（空 text）、`500 voice_unavailable`（未接语音）、`500 tts_failed`、
+ * `500 tts_persona_unmapped`（人格没有发音人映射）、`500 tts_no_character`（连生效人格都没有）、
+ * `500 tts_empty`（拿到的是静默空音频，同时响应头带 `X-Voice-Provider: silent`）。
+ *
+ * @see top.yeij.cyrene.data.voice.SpeechClient
+ */
+interface SpeechApi {
+
+    /**
+     * 把 [body] 合成为一段 WAV 字节。
+     *
+     * 路径**不带前导 `/`**（与 [ChatApi] 一致）：Retrofit 的 `baseUrl` 已含 `/` 结尾，
+     * 带前导 `/` 会把它当成根路径、把部署在子路径下的服务端地址整段丢掉。
+     */
+    @Streaming
+    @POST("api/v1/audio/speech")
+    suspend fun speech(@Body body: SpeechRequestDto): Response<ResponseBody>
+}
@@ -46,6 +46,16 @@ data class ChatRequest(
     * WS `chat` 帧的 4096 字节读上限仍在，且上行帧里没有承载附件的余地。
     */
    val documents: List<DocumentRefDto> = emptyList(),
+    /**
+     * **请求把本条作为独立一路处理**（忙时并行规范 §2.2，REST 与 WS `chat` **同形**）。
+     *
+     * `null` = **整键省略**（`encodeDefaults = false`），与加入该字段之前**逐字节相同**：
+     * 用户把设置页那栏「她忙时发消息」选成「**并行**」**且会话正忙**时才给 `true`（判据是纯函数
+     * `parallelForSend`；另外两档、以及空闲时都不带这个键）。
+     * 服务端照准与否都不报错——额度满时落回排队并回 `202 {queued:true}`（伴一条
+     * `pending_ack{reason:"parallel_limit"}`），已被在飞路 steer 吃进时回 `200 {stream:true}`。
+     */
+    val parallel: Boolean? = null,
 )

 /**
@@ -8,6 +8,10 @@ import kotlinx.serialization.Serializable
 *
 * 它同时是 WS 握手 `history` 回放与 `message_persisted` 的载荷消息类型
 * （服务端三处共用同一个 `historyMessage`），所以 [documents] 的解析一处覆盖三条路。
+ *
+ * [voice] 从契约 v0.97（后端 M44 `fb55769`）起也**不再是例外**：REST 四路、握手 `history` 回放、
+ * `message_persisted` / `channel_persisted` 落库帧**都填它**，第一条帧就带
+ * （前提与理由写在 [voice] 的 KDoc 里）。
 */
@Serializable
 data class HistoryMessageDto(
@@ -43,6 +47,54 @@ data class HistoryMessageDto(
     */
    val documents: List<DocumentRefDto> = emptyList(),
    val createdAt: Long,
+    /**
+     * 产出 / 吃进这条消息的那一路的回合标识（忙时并行规范 §2.7，**纯增量**）。
+     *
+     * 语义按角色分（规范 §2.7 明写）：
+     * - **user 行** = 吃进它 / 起它的那一路的 `turnId`（被 steer 吃进的行 = 吃进它的那一轮）；
+     * - **assistant 行** = 产出它的那一路的 `turnId`。
+     *
+     * 于是重连后能把「回复 ↔ 提问」精确配对，两条并行回复也天然分属两个 `turnId`（分桶有据），
+     * **不必靠时间戳猜**（历史顺序的真源是 `(created_at, rowid)` = **完成先后**，
+     * 不承诺与提问相邻）。
+     *
+     * **旧行整键省略**（不是空串，规范 §2.7 末条）⇒ [null] 时客户端回落既有的「按顺序渲染」，
+     * 与加入这一列之前逐字相同。四处同源：`message_persisted` / `GET /messages` / 握手 `history`
+     * 回放 / `channel_persisted`（本端不消费最后一条）。
+     */
+    val turnId: String? = null,
+    /**
+     * 这条消息的语音元数据（契约 v0.67 登记、**v0.79 已实现**，形状见 [VoiceDto]）；
+     * **非语音消息整键缺席** —— 所以缺席与 `null` 是同一件事。
+     *
+     * ## 判据是**两个**问题，别再合成一个
+     * - 「这条**来自**一段声音吗」= 这个键在不在（`domain.chat.hasVoice`）；
+     * - 「要不要画语音形态」= 键在 **且** `status != "failed"`（`domain.chat.isVoiceMessage`）。
+     *   后端 M57-M59 的出站合成降级行（`{source:"tts", status:"failed", fallbackReason}`）与入站的
+     *   转写失败行都是**键在、但没有可播的语音**：正文照常按文字渲染，另加一行灰色小标
+     *   （`domain.chat.voiceFallbackNote`），**不画**语音形态。按旧的单条判据（键在即语音）它们会
+     *   被画成一个点下去必然播不了的气泡。
+     *
+     * ## 覆盖率（契约 v0.97）：**全部读面都带**，第一条帧就带
+     * `GET /sessions/{id}/messages`、`GET /admin/channels/messages`、
+     * `GET /admin/channels/{platform}/messages`、`PATCH /messages/{id}` 的响应与
+     * `message_edited` 广播帧，**外加** WS 握手 `history` 回放与 `message_persisted` /
+     * `channel_persisted` 落库帧——后三处由后端 M44（`fb55769`）修好：落库顺序改为
+     * **INSERT → 写 `voice` 列 → notify**，于是语音消息的**第一条**落库帧就带 `voice`
+     * （v0.79 时期「落库那一刻还拿不到、等下一次拉取自动升级」的说法**已作废**）。
+     *
+     * 所以本端**没有任何**「实时帧先按普通文本显示、稍后升级成语音气泡」的兜底：
+     * `voice` 在就按 `status` 分流，不在就不是语音。**不要为它加重试 / 轮询 / 延迟判定**。
+     *
+     * ⚠️ 两条实现前提（服务端口径，未来改动**别破坏它**）：① `voice` 列写入必须先于 notify；
+     * ② 帧内 `voice` 是**发出那一刻的即时列读**（每帧多一次查询，亚毫秒）。任一被改回
+     * 「先 notify 再写列」，本端判据立刻退回 v0.79 的行为——而本端**刻意不再为它留兼容分支**。
+     *
+     * ⚠️ 列被外部改坏（非法 JSON / 越出闭集）时服务端**让字段缺席**（记一条不带正文的 WARN），
+     * 于是这种情况在本端与「不是语音」同形——契约的 `voice` 没有「读不出」这一态，缺席是唯一
+     * 诚实的表达（与 [documents] 回一条 `unreadable` 不同）。
+     */
+    val voice: VoiceDto? = null,
 )

 /**
@@ -0,0 +1,86 @@
+package top.yeij.cyrene.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * 一条消息的**语音元数据**（契约 **v0.67 登记、v0.79 已实现（切片 L45）**，
+ * `Cyrene_v2/Docs/api-client.md` §4.4「`voice` 语义」与 §1.2 U19）。
+ *
+ * ## 🎤 判据 = 本键存在 **且** `status != "failed"`
+ * `voice` 是 [HistoryMessageDto] 上的**指针**：非语音消息**整键缺席**（不是 `{}`，也不是 `null`）。
+ * 客户端**只认这个键**，**绝不**从 `content` 正文里认媒体类型——QQ 语音正文里那个 `[语音]`
+ * 占位标记自 v0.67 起**不再下发**，而正文里**也可能**出现用户自己打出的 `[语音]` 字样。
+ *
+ * 键在只说明「这条来自一段声音」；要不要画语音形态还看 `status`（见下）。
+ * 判据落在一处：`domain.chat.isVoiceMessage`（`domain.chat.hasVoice` 答的是前半个问题）。
+ *
+ * ## 三态 `status`（闭集）
+ * `transcribed`（正文即转写文本；出站方向 = 合成成功）/ `empty`（转写成功但没识别出文字）/
+ * `failed`（**没有可播的语音**——入站没拿到转写文本，出站是合成降级回文字）。客户端**按 `status`
+ * 分支，绝不按正文文案分支**；设计上刻意不下发 `failed` 的机器可读细分（未配置 / 鉴权 / 欠费 /
+ * 限流 / 超时 / 格式不支持 / 无字节一律只进服务端日志），所以本端**不猜**细分。
+ *
+ * ## `fallbackReason` 只在 `failed` 时有
+ * 出站方向（`source = "tts"`）合成降级时，服务端在这个键里给出降级原因；本端**原样**小字展示
+ * （`domain.chat.voiceFallbackNote`），**不猜闭集**——取值集合后端尚未定稿，见那个函数的 KDoc。
+ *
+ * ## `name` / `mime` / `size` / `url` 四者同生共死
+ * 有音频副本时四个键全在，**无副本时全缺席**（服务端保证不会出现 `url` 指着一个不存在的 `name`）。
+ * 反过来说：**四个键没凑齐就不要画播放控件**——不能给一个点下去必然失败的按钮。
+ * 判据落在一处：`domain.chat.voiceAudio`。一个真实的无副本例子是微信（`weixin-ilink`）：
+ * 平台自带转写就**不白下载那份音频**，于是 `source` 是 `platform` 而四个键全缺席
+ * （**只有 🎤 标记**，不可回放）。
+ *
+ * ## `durationMs` 只有渠道如实给出时才有
+ * 服务端「读不出来就省略键，**绝不估算**」。本端同理：**缺席就不显示时长**
+ * （不拿 size / 码率反算，也不显示 `0:00` 冒充）。所以它是可空的，且 `<= 0` 一并当缺席
+ * （见 `domain.chat.voiceDurationLabel`）。
+ *
+ * ## `url` 是**服务端相对路径**，客户端绝不自己拼
+ * 取值形如 `/api/v1/media/<name>`，由服务端一处拼出（**唯一派生字段**）。
+ * 客户端要取字节时把它接到**当前服务器地址**后面（`domain.chat.voiceMediaUrl`）——
+ * 与图片那条「保留 path、替换 host」同一取向，但这里服务端给的就是相对路径，不需要换 host。
+ */
+@Serializable
+data class VoiceDto(
+    /**
+     * `"asr"`（服务端语音识别所得，含云端）/ `"platform"`（渠道平台自带转写，微信 iLink 的
+     * `voice_item.text`）/ `"tts"`（我们自己合成的出站语音，后端 M57-M59）。
+     * 见 `domain.chat.VoiceSource`。**开放取值**：认不出的原样保留。
+     *
+     * 接收侧**不按 `source` 分支**：合成成功的那条与入站语音同形（`status = transcribed` +
+     * 四键副本），走同一条渲染路径。
+     */
+    val source: String = "",
+    /**
+     * `"transcribed"` / `"empty"` / `"failed"`（闭集三态，见 `domain.chat.VoiceStatus`）。
+     *
+     * 默认空串而非某个态，是因为**认不出就不要装认识**：显示层对「不是 `empty`」的所有取值
+     * （含服务端将来新增的态）一视同仁地不额外说话（见 `domain.chat.voiceNote`）。
+     *
+     * ⚠️ 只有 `"failed"` 是**没有可播的语音**的那一态（`domain.chat.isPlayableVoice`）；认不出的
+     * 取值一律当可播（fail-open，理由写在那个函数的 KDoc 里）。
+     */
+    val status: String = "",
+    /** 音频副本的存储名（内容寻址，`<32hex>.<ext>`）；**无副本 ⇒ 键缺席**。 */
+    val name: String? = null,
+    /** 副本的 MIME（按存储名扩展名映射）。与 [name] / [size] / [url] 同生共死。 */
+    val mime: String? = null,
+    /** 副本的字节数。与 [name] / [mime] / [url] 同生共死；**不用它反算时长**。 */
+    val size: Long? = null,
+    /** 时长（毫秒）。**只有渠道如实给出时才有**；缺席 = 本端不显示时长。 */
+    val durationMs: Int? = null,
+    /**
+     * 合成降级的原因（后端 M57-M59 预告，`devdocs/02` 已登记；契约 **v0.98 的正式回执尚未到**）。
+     *
+     * 只在 `status == "failed"` 时有意义，其余状态下服务端不会下发（`omitempty`）；入站转写失败
+     * 也不带它——入站的失败原因由正文那行诚实提示承载。
+     *
+     * 本端**原样**小字展示（`domain.chat.voiceFallbackNote`），**不猜闭集、不做映射**：取值集合
+     * 后端还没定（`tts_timeout` 之类是我们看到的预告示例，不是契约）。缺席 / 空白时那一行小标
+     * 退化成固定的一句（`VOICE_FALLBACK_NOTE`），不白屏。
+     */
+    val fallbackReason: String? = null,
+    /** 副本的服务端相对路径（`/api/v1/media/<name>`）。**不要自己拼这条路**，也不要当绝对地址用。 */
+    val url: String? = null,
+)
@@ -16,7 +16,8 @@ import kotlinx.coroutines.withContext
 * 三条读取出口共用同一个端点，只是给的查询参数不同：
 * - [loadPage] / [loadLatest]：`before` 往回翻（服务端**倒序**返回）；
 * - [search]：`q` 会话内搜索（也是倒序）；
- * - [loadAfter]：`after` 往前追（服务端**升序**返回，契约 §1 行 6）。
+ * - [loadAfter]：`after` 往前追（服务端**升序**返回，契约 §1 行 6）；[loadIncrement] 是它在
+ *   `after` 方向上的翻页版（一直追到尾巴，追不到就如实说 `complete = false`）。
 *
 * 三者都统一转成**升序**的 [PagedMessages] 再交出去。去重 / 合并请用 [mergeMessages]。
 */
@@ -87,7 +88,9 @@ class MessageRepository(
     * `createdAt`（[PagedMessages.newestCreatedAt]），不是最旧的。
     *
     * 同毫秒并列且条数超过 `limit` 时，纯 `createdAt` 游标推不动（契约 §A5 明说的已知边界）——
-     * 调用方按 `id` 去重、并在游标没前进时停下来，不在这里兜。
+     * 落在页边界上的那一毫秒里剩下的行**再也追不回来**，因为服务端只给严格 `>`。调用方按 `id`
+     * 去重，并且**不能把满页之后的一页（空页、不满页都一样）当作追到了尾巴**：要翻页又要把边界
+     * 说清楚，用 [loadIncrement]，不要自己拿这一页凑。
     */
    suspend fun loadAfter(
        sessionId: String,
@@ -100,6 +103,87 @@ class MessageRepository(
            .map { raw -> toPagedMessages(raw, pageSize) }
    }

+    /**
+     * **增量追尾**（W77）：从 [after] 起把某会话的新消息一直翻到尾巴，最多 [maxPages] 页。
+     *
+     * 与裸的 [loadAfter] 的差别只有一件：**它负责把「还没翻完」这件事如实说出来**。
+     *
+     * ## 什么时候只能说 `complete = false`
+     * 游标是本页**最新**一条的 `createdAt`，而服务端只给 `created_at > after`（**严格**大于：
+     * `list_after.go` 的 `ListAfter` 与 `devtools/fake-backend` 两处一致）。于是**落在页边界上被
+     * 劈开的那一毫秒**里的行永远追不回来——它们的 `createdAt` 恰好等于游标，再问一次也问不到
+     * （契约 §A5 的已知边界：纯 `createdAt` 游标没有毫秒内的次序）。
+     *
+     * 要紧的是**切点**：只有当服务端的 `LIMIT` 在某一毫秒中间切过一刀，才会留下追不回来的尾巴。
+     * 客户端看不见那一刀落在哪儿，只知道自己**拿过满页**就等于「发生过一次切点」。所以这里只有一条
+     * 不变式，下面几档都是它的推论：
+     *
+     * > `complete = true` **当且仅当整个追尾从未拿过满页**。
+     *
+     * - **第一页就是空页 ⇒ `true`**：一条新消息都没有，没有可少给的；
+     * - **第一页就不满 ⇒ `true`**：`LIMIT` 没切到任何东西，`> cursor` 的行全在这一页里；
+     * - **拿过整页之后，下一页是空页 ⇒ `false`**：那次空页分不出「干净的尾巴」与「空页底下还压着
+     *   同一毫秒的几条」；
+     * - **拿过整页之后，下一页不满 ⇒ 也是 `false`**：不满只说明「`> cursor` 的行就这么多了」，对
+     *   切点那一毫秒还有没有行**一无所知**。例如积压 `m1@500 m2@500 m3@500 m4@600`、页宽 2：
+     *   第一页给 `m1 m2`（切点正好劈开 500 那一毫秒），第二页 `after=500` 只给 `m4@600`、不满页，
+     *   而 `m3@500` 既不 `> 500`、也就永远拿不到；
+     * - **翻满 [maxPages] ⇒ `false`**。
+     *
+     * 代价：积压一到页宽（默认 50 条）就回落整表。这与「翻满 [maxPages] ⇒ 回落」同类——那时增量
+     * 已经取回 ≥50 行，多问一次整表是边际成本，也正合 [MAX_INCREMENT_PAGES] 那句「积压多到增量不再
+     * 便宜」。主路径（几条新消息、第一页就不满）不受影响。
+     *
+     * 这里**不猜**、也不悄悄少给几条：说不完整，调用方还能去问唯一权威。
+     *
+     * 不传 `platform`：未读面上的口径是服务端 `count(created_at > read_at)`（`unreadCountQuery`，
+     * 不带平台过滤），按平台过滤会让本地数出来的条数**与服务端的 `unreadCount` 不同源**。
+     *
+     * @param after 本端**已见**的最大 `createdAt`（毫秒）；服务端返回严格新于它的消息，升序。
+     * @param maxPages 最多翻几页（默认 [MAX_INCREMENT_PAGES]）。用尽即 `complete = false`：
+     *   一次静默刷新不该为了补一个角标翻十几页。
+     */
+    suspend fun loadIncrement(
+        sessionId: String,
+        after: Long,
+        pageSize: Int = DEFAULT_PAGE_SIZE,
+        maxPages: Int = MAX_INCREMENT_PAGES,
+        platform: String? = null,
+    ): Result<MessageIncrement> = withContext(dispatcher) {
+        val size = pageSize.coerceIn(1, MAX_PAGE_SIZE)
+        val byId = LinkedHashMap<String, HistoryMessageDto>()
+        var cursor = after
+        // 只要翻到过一整页，就说明服务端的 LIMIT 切过一刀，那一刀可能劈开了一毫秒（见 KDoc）。
+        // 此后无论下一页是空页还是不满页，都说不出「追到了尾巴」。
+        var chasedFullPage = false
+
+        fun done(at: Long, complete: Boolean) = Result.success(
+            MessageIncrement(messages = byId.values.sortedWith(MessageOrder), cursor = at, complete = complete),
+        )
+
+        var page = 0
+        while (page < maxPages.coerceAtLeast(1)) {
+            page++
+            val raw = apiCall { api.listMessages(sessionId, size, before = null, platform = platform, after = cursor) }
+                .getOrElse { return@withContext Result.failure(it) }
+            val paged = toPagedMessages(raw, size)
+            // 空页有两种含义，客户端分不出来：第一页就空 = 真的没有新的；拿过一整页之后空 = 可能还有
+            // 同一毫秒的几条卡在游标上（服务端只给严格大于）。后者只能说「没追完」。
+            if (paged.messages.isEmpty()) {
+                return@withContext done(cursor, complete = !chasedFullPage)
+            }
+            // 去重只是防御：严格 `>` 下相邻两页不可能重叠（下一页只要 > 本页最新那条）。
+            paged.messages.forEach { byId[it.id] = it }
+            val newest = paged.newestCreatedAt ?: return@withContext done(cursor, complete = false)
+            // 不满页只说明「> cursor 的行就这么多了」，对切点那一毫秒一无所知 —— 与空页档同一个洞，
+            // 同样是拿过整页之后就不作数。
+            if (!paged.hasMore) return@withContext done(newest, complete = !chasedFullPage)
+            cursor = newest
+            chasedFullPage = true
+        }
+        done(cursor, complete = false)
+    }
+
    /**
     * 编辑单条消息（D3，契约 §1 行 6a）：`PATCH /api/v1/messages/{id}`，成功返回**服务端更新后的
     * 完整消息 DTO**。
@@ -152,6 +236,15 @@ class MessageRepository(
        /** 搜索结果一页的条数：命中项要一条条读，比历史分页小一些更好翻。 */
        const val DEFAULT_SEARCH_PAGE_SIZE = 30

+        /**
+         * [loadIncrement] 一次最多翻几页（500 条）。
+         *
+         * 这个上限只为一件事存在：一次**后台**的顺手对齐不该翻十几页。越过它就说明积压已经多到
+         * 「增量」不再便宜，那时整表（`GET /sessions` 一次拿回权威的 `unreadCount` 与预览）
+         * 反而更划算——调用方据此回落，见 `SessionsViewModel.flushPendingIncrements`。
+         */
+        const val MAX_INCREMENT_PAGES = 10
+
        private val EMPTY_PAGE = PagedMessages(
            messages = emptyList(),
            hasMore = false,
@@ -190,3 +283,18 @@ private fun toPagedMessages(
        newestCreatedAt = ascending.lastOrNull()?.createdAt,
    )
 }
+
+/**
+ * [MessageRepository.loadIncrement] 的结论：升序增量消息 + 推进后的游标 + 有没有真的追到尾巴。
+ *
+ * [complete] 为 `false` 时 [messages] 仍是**已拿到的全部**（不丢），但调用方不能把它当成
+ * 「这之后就没有了」——未读面上那种情况要回落到整表，见 `SessionsViewModel.flushPendingIncrements`。
+ *
+ * 放在这里而不是 `PagedMessages.kt`：`PagedMessages` 是纯分页形状（一页的元数据），
+ * 这个类型是 [MessageRepository] 翻页循环的产物，跟着它的生产者走。
+ */
+data class MessageIncrement(
+    val messages: List<HistoryMessageDto>,
+    val cursor: Long,
+    val complete: Boolean,
+)
@@ -0,0 +1,164 @@
+package top.yeij.cyrene.data.repository
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiErrorMapper
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.MediaApi
+import top.yeij.cyrene.domain.chat.DocumentAttachments
+import top.yeij.cyrene.domain.chat.VoiceAudio
+import top.yeij.cyrene.domain.chat.readBounded
+import top.yeij.cyrene.domain.chat.voiceMediaUrl
+import java.io.File
+
+/** 本端一次读得下、也放得动的语音副本上限，超过就如实说「放不了」（见 [VoiceTooLargeException]）。 */
+class VoiceTooLargeException : Exception("voice copy too large")
+
+/** 服务端只给了相对路径，而本端目前拿不到一个能接上去的服务器地址（未登录 / 地址为空）。 */
+class VoiceUrlUnavailableException : Exception("voice media url unavailable")
+
+/**
+ * 语音副本的取字节层（`GET /api/v1/media/{name}` 的第一个调用方）。
+ *
+ * 与 [DocumentRepository] 同一个形状：响应不是信封（就是音频本身），所以不用 `apiCall`——
+ * 成功即读字节，失败才走 [ApiErrorMapper]（`404 media_not_found` / `401`）。
+ * `@Streaming` 的响应体必须由调用方关闭，[okhttp3.ResponseBody.use] 在这里收口。
+ *
+ * [url] 由调用方拼好（服务端给的**相对路径** + 当前服务器地址，纯函数
+ * [voiceMediaUrl]）：本层**不自己拼路径**——契约把那条路径定成服务端唯一的派生字段。
+ * 因此这里也不做形态校验：拼不出可信地址的调用方根本不会走到这里（[VoiceStore] 先判）。
+ */
+class MediaRepository(
+    private val api: MediaApi,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    /**
+     * 取回一条语音副本的字节。
+     *
+     * 读到超过 [MAX_VOICE_BYTES] 就判 [VoiceTooLargeException]：语音副本本就不该大，
+     * 而「一次读进内存」这条路上必须有一把尺子（与文档 / 图片同一个做法）。
+     * **0 字节不算成功**——那会让下一次播放「读缓存命中」一份什么都没有的文件。
+     */
+    suspend fun download(url: String): Result<ByteArray> = withContext(dispatcher) {
+        try {
+            val response = api.download(url)
+            val body = response.body()
+            when {
+                response.isSuccessful && body != null -> body.use { stream ->
+                    val bytes = readBounded(stream.byteStream(), MAX_VOICE_BYTES)
+                    when {
+                        bytes == null -> Result.failure(VoiceTooLargeException())
+                        bytes.isEmpty() -> Result.failure(
+                            CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                        )
+
+                        else -> Result.success(bytes)
+                    }
+                }
+
+                // 2xx 却没有响应体：与 apiCall 同一口径，判解析失败而不是「拿到了空文件」。
+                response.isSuccessful -> Result.failure(
+                    CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                )
+
+                else -> Result.failure(
+                    CyreneException(ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string())),
+                )
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
+        }
+    }
+
+    private companion object {
+        /**
+         * 上限取附件那一把尺子（20 MB）：语音副本远小于它，而这里要防的只是「一次读进内存」
+         * 这条路上没有上界。**不新造一个数字**——多一个自定义上限就多一处会漂移的口径。
+         */
+        val MAX_VOICE_BYTES: Long = DocumentAttachments.MAX_FILE_BYTES
+    }
+}
+
+/**
+ * 语音副本的「取字节 + 落盘缓存」层（播放前那一步的**唯一**取数入口）。
+ *
+ * ## 缓存：`<cacheDir>/media/`，复用 [DocumentCache] 的三条规则
+ * - **名字规则 / 命中判定 / 原子落盘**全部复用 [DocumentCache]（同一条 `isSafeName`、
+ *   `isHit`（非空才算命中）、`write`（先写 `.part` 再改名））——只在缓存根下换一个目录名。
+ * - **特意不落进 `documents/`**：那个目录是 `FileProvider`（`res/xml/file_paths.xml`）**唯一**
+ *   暴露出去的根，「用其它应用打开 / 保存到下载目录」两条出口都从它取文件。语音本片只做
+ *   收 / 放，不提供「交给别的 App」这条出口，所以**不把暴露面扩大一个字节**。
+ * - 目录名是 `media`，与 `voice.url` 里的 `/api/v1/media/` 同源，便于排查时对得上号。
+ *
+ * ## 为什么缓存（而不是每次现下）
+ * 服务端副本是**内容寻址**的（名字由内容决定）+ `Cache-Control: private, max-age=86400,
+ * immutable` ⇒ 同一个名字的字节永不改变，「文件在且非空」就是永远有效的命中。重复播放因此
+ * **一个请求都不发**，离线也能重听刚听过的那条。代价是缓存目录里多占几十 KB~几百 KB 一份，
+ * 而它在 `cacheDir` 下：系统需要空间时可以回收，本端被回收之后下次播放重新下载（**不是**错误）。
+ *
+ * ## 它不做什么
+ * 不拼路径（[voiceMediaUrl] 在调用前判，拿不到可信地址就直接失败）、不做形态校验、不猜 MIME、
+ * **不拿 `size` 反算时长**（时长只认服务端给的 `durationMs`）。
+ */
+class VoiceStore(
+    /**
+     * 取一条副本的字节（未命中缓存时调一次）。
+     *
+     * 收成一个 lambda 而不是直接收 [MediaRepository]：本类因此可以在单测里用临时目录 + 假下载器
+     * 跑完，不必造一个 HTTP 替身（与 [ImageCacheStore] 的 `download` 参数同一手法）。
+     * 生产路径上它就是 `container.mediaRepository::download`。
+     */
+    private val download: suspend (String) -> Result<ByteArray>,
+    private val cacheDir: File,
+    private val baseUrlProvider: () -> String,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    /**
+     * 取这条语音的字节并确保它已落进缓存；返回**可直接交给 `MediaPlayer` 的那份文件**。
+     *
+     * 顺序是刻意的：**先拼地址、再查缓存**。地址拼不出来（未登录 / 地址为空）就如实失败，
+     * 绝不因为「本地碰巧缓存过」而放行——那会让一条本端根本没有服务器归属的语音照旧能放，
+     * 而调用方拿不到任何异常信号。
+     */
+    suspend fun load(audio: VoiceAudio): Result<File> = withContext(dispatcher) {
+        val url = voiceMediaUrl(audio.url, baseUrlProvider())
+            ?: return@withContext Result.failure(VoiceUrlUnavailableException())
+        // ⚠️ 刻意**不用** `DocumentCache.fileFor`：那个函数的缓存根写死成 `documents/`
+        // （FileProvider 那一层），传别的目录进去会拼成 `<cacheDir>/media/documents/<name>`。
+        // 这里只用它的**名字判据**，路径自己拼。
+        if (!DocumentCache.isSafeName(audio.name)) {
+            // 名字不安全 = 服务端给了一个本端不敢拼路径的名字；判解析失败，绝不退回别的名字。
+            return@withContext Result.failure(
+                CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+            )
+        }
+        val file = File(directory(cacheDir), audio.name)
+        if (DocumentCache.isHit(file)) return@withContext Result.success(file)
+
+        val bytes = download(url).getOrElse { return@withContext Result.failure(it) }
+        try {
+            DocumentCache.write(file, bytes)
+            Result.success(file)
+        } catch (_: Exception) {
+            // 写不进去时把可能的残留清掉，再如实报「缓存不可用」——**绝不**退回「把字节直接喂给
+            // 播放器」那条路：那需要另一条落盘位置，而缓存目录写不进去时多半写得进的地方也没有。
+            file.delete()
+            Result.failure(DocumentCacheUnavailableException())
+        }
+    }
+
+    companion object {
+        /** 缓存根下的目录名（与 `voice.url` 里的 `/api/v1/media/` 同源，便于对号）。 */
+        const val DIRECTORY_NAME: String = "media"
+
+        /** 语音副本的缓存目录：`<cacheDir>/media`。 */
+        fun directory(cacheDir: File): File = File(cacheDir, DIRECTORY_NAME)
+    }
+}
@@ -0,0 +1,219 @@
+package top.yeij.cyrene.data.voice
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import top.yeij.cyrene.core.auth.NoUnauthorizedPolicy
+import top.yeij.cyrene.core.auth.UnauthorizedPolicy
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.data.api.ApiErrorMapper
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.SpeechApi
+import top.yeij.cyrene.data.api.SpeechRequestDto
+import top.yeij.cyrene.data.repository.DocumentCache
+import top.yeij.cyrene.data.repository.DocumentCacheUnavailableException
+import top.yeij.cyrene.data.repository.VoiceStore
+import top.yeij.cyrene.domain.chat.DocumentAttachments
+import top.yeij.cyrene.domain.chat.readBounded
+import java.io.File
+import java.security.MessageDigest
+
+/** 服务端回的字节**不是**一段 WAV（200 却回了 JSON 信封 / HTML 错误页 / 别的东西）。 */
+class SpeechNotAudioException : Exception("speech response is not wav")
+
+/**
+ * 一次 TTS 请求的**字节嗅探**：真的是 RIFF/WAVE 吗？
+ *
+ * 契约（api-client.md §4.1 行 561 的旁注、§1.2 U6）只说「产物恒为 WAV」，**没有**承诺
+ * `Content-Type` 是什么，并明写「不要照抄 `Content-Type`」。所以判据只能落在字节上：
+ * 头 4 字节 `RIFF` + 偏移 8 起的 4 字节 `WAVE`（RIFF 容器里夹一段 `fmt ` 那种标准布局）。
+ *
+ * 为什么要判：`MediaPlayer` 拿到非音频字节时抛的是它自己那套 `setDataSource` 异常，
+ * 与本端「取字节失败」的语义完全不同；而 200 回 JSON 信封恰恰是**最可能**的一种
+ * 「网关/反代把错误包了一层」的形态 —— 提前拦在这里，失败就被如实归到「解析失败」那一档，
+ * 而不是在播放器里炸成一个没人认识的东西。
+ */
+fun isWavBytes(bytes: ByteArray): Boolean =
+    bytes.size >= WAV_HEADER_BYTES &&
+        bytes[0] == 'R'.code.toByte() &&
+        bytes[1] == 'I'.code.toByte() &&
+        bytes[2] == 'F'.code.toByte() &&
+        bytes[3] == 'F'.code.toByte() &&
+        bytes[8] == 'W'.code.toByte() &&
+        bytes[9] == 'A'.code.toByte() &&
+        bytes[10] == 'V'.code.toByte() &&
+        bytes[11] == 'E'.code.toByte()
+
+/** RIFF 头里本端要看的那几个字节都在前 12 个之内。 */
+private const val WAV_HEADER_BYTES = 12
+
+/** 本端一次读得下、也放得动的合成音频上限（与语音副本同一把尺子：附件上限 20 MB）。 */
+private val MAX_SPEECH_BYTES: Long = DocumentAttachments.MAX_FILE_BYTES
+
+/**
+ * 「把一段文字念出来」的取字节层（`POST /api/v1/audio/speech` 的唯一调用方，契约 api-client.md
+ * §1.2 **U6**，v0.96 增量 + v0.97 补写）。
+ *
+ * ## 凭据：只走 Bearer，不设 API Key
+ * 服务端是 owner-only 的**双凭据门**（Bearer owner JWT **或** `X-API-Key`，两个分支落到同一个
+ * `authorize(RoleOwner)`）。本端只走前者：令牌由 [ApiClientFactory.create] 挂在 OkHttpClient 上的
+ * `AuthInterceptor` 注入，并顺带享受「带令牌仍 401 ⇒ 单飞续期并重试一次」。
+ * 主人 2026-10-26 拍板**不加 API Key 输入框** —— 那会多一份要保管、要轮换、要泄漏的凭据，
+ * 而本端本来就已经有 owner 会话。
+ *
+ * ## 发音人从哪来：`sessionId`，不是 `voice`
+ * 契约里 `voice` **接受但不生效**、`format` **不生效**。真正决定发音人的是 `sessionId` 那条会话的
+ * **生效人格**（会话绑定 → 全局默认 → 服务端配置的 default）。所以 [speak] 一定要拿到当前会话 id
+ * ——**省略它不等于没有角色**，只是让服务端退到全局默认。
+ *
+ * ## 缓存：`<cacheDir>/media/tts_<hash>.wav`，同一段文字一个请求都不发第二次
+ * 名字按 **(baseUrl, sessionId, text)** 内容寻址（sha256 前 32 位十六进制），复用 [DocumentCache] 的
+ * 三条规则（`isSafeName` / `isHit` / 原子 `write`），目录复用 [VoiceStore.directory]（`media/`，
+ * 与 `voice.url` 的 `/api/v1/media/` 同源，排查时对得上号；且它**不在** FileProvider 暴露的
+ * `documents/` 根下，不扩大暴露面一个字节）。
+ *
+ * `baseUrl` 进哈希是 P2-2 的修法：换一台服务器后，同一个 `(sessionId, text)` 在那边可能是**另一个
+ * 声音**（人格映射 / 发音人 / 合成实现都是那台服务器的），命中上一台合成的那份 WAV 就是念错人。
+ *
+ * ⚠️ 与语音副本的缓存**有一处关键差别**：副本的名字由服务端按内容决定 ⇒ 命中永不失效；而这里的
+ * 名字由**请求参数**决定，服务端换了发音人 / 换了合成实现之后，同一段文字应该能念出不一样的声音。
+ * 因此这里把 `tts_` 前缀留成「本端合成缓存」的标记，命中判定仍用 [DocumentCache.isHit]
+ * （非空才算）——它是 `cacheDir` 下的东西，系统随时可回收，被回收之后下次朗读重新请求，
+ * **不是**错误。
+ *
+ * ## 错误怎么分类
+ * 非 2xx 一律走 [ApiErrorMapper]（`401` ⇒ [CyreneError.Unauthorized]，其余 ⇒
+ * [CyreneError.Server] 且**保留服务端那句 `code`**——`tts_persona_unmapped` /
+ * `tts_no_character` 这两档的文案完全不同，折成一句话就说不清了）。
+ * 分类成「柔和提示」还是「明确降级」是纯函数的事，在
+ * [top.yeij.cyrene.domain.chat.ttsFailureOf] 里，本类不做产品判断。
+ *
+ * @param baseUrlProvider 每次现读服务器地址（换服务器 ⇒ 客户端重建，与 `AppContainer` 同一纪律）。
+ * @param apiFactory 按 baseUrl 造 [SpeechApi]；收成 lambda 是为了单测能塞一个直连本地 HTTP 替身的
+ *   实例，而不必造一整套依赖注入。
+ */
+class SpeechClient(
+    private val baseUrlProvider: () -> String,
+    private val tokenProvider: () -> String? = { null },
+    private val unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
+    private val cacheDir: File,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+    private val apiFactory: (String) -> SpeechApi = { baseUrl ->
+        ApiClientFactory.create(
+            baseUrl,
+            SpeechApi::class.java,
+            tokenProvider,
+            unauthorizedPolicy,
+        )
+    },
+) {
+
+    /** 按 baseUrl 缓存 Retrofit 实例（换地址才重建），与 `AppContainer.mediaApi` 同一手法。 */
+    private var cachedApi: SpeechApi? = null
+    private var cachedBaseUrl: String? = null
+
+    private fun api(): SpeechApi {
+        val baseUrl = baseUrlProvider()
+        val cached = cachedApi
+        if (cached != null && cachedBaseUrl == baseUrl) return cached
+        return apiFactory(baseUrl).also {
+            cachedApi = it
+            cachedBaseUrl = baseUrl
+        }
+    }
+
+    /**
+     * 把 [text] 合成成一段 WAV 并落盘，返回**可直接交给 `MediaPlayer`** 的那份文件。
+     *
+     * [sessionId] 是当前会话 id：它决定发音人（见类 KDoc）。传 `null` 表示「本端不知道是哪个会话」，
+     * 服务端会退到全局默认人格 —— 调用方**不要**为了让字段好看而编一个 id 出来。
+     */
+    suspend fun speak(text: String, sessionId: String?): Result<File> = withContext(dispatcher) {
+        val trimmed = text.trim()
+        if (trimmed.isEmpty()) {
+            // 服务端对空 text 回 `400`；本端连请求都不发（省一次往返，也省一次无意义的失败）。
+            return@withContext Result.failure(
+                CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+            )
+        }
+        val file = File(VoiceStore.directory(cacheDir), cacheName(trimmed, sessionId, baseUrlProvider()))
+        if (DocumentCache.isHit(file)) return@withContext Result.success(file)
+
+        try {
+            val response = api().speech(SpeechRequestDto(text = trimmed, sessionId = sessionId))
+            val body = response.body()
+            when {
+                response.isSuccessful && body != null -> body.use { stream ->
+                    val bytes = readBounded(stream.byteStream(), MAX_SPEECH_BYTES)
+                    when {
+                        // 超过上限：本端一次读不下（合成音频远小于它，走到这里说明对面不对劲）。
+                        bytes == null -> Result.failure(SpeechNotAudioException())
+                        // 0 字节：与 MediaRepository 同一口径，判解析失败而不是「拿到一段静音」。
+                        bytes.isEmpty() -> Result.failure(
+                            CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                        )
+                        // 200 却不是 WAV：**绝不**把 JSON / HTML 喂给 MediaPlayer（见 isWavBytes）。
+                        !isWavBytes(bytes) -> Result.failure(SpeechNotAudioException())
+                        else -> cache(file, bytes)
+                    }
+                }
+
+                // 2xx 却没有响应体：与 apiCall 同一口径。
+                response.isSuccessful -> Result.failure(
+                    CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                )
+
+                else -> Result.failure(
+                    CyreneException(
+                        ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string()),
+                    ),
+                )
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
+        }
+    }
+
+    private fun cache(file: File, bytes: ByteArray): Result<File> = try {
+        DocumentCache.write(file, bytes)
+        Result.success(file)
+    } catch (_: Exception) {
+        // 写不进去时把可能的残留清掉，再如实报「缓存不可用」——绝不退回「把字节留在内存里等播放器
+        // 读」那条路：MediaPlayer 只吃路径，而缓存目录写不进去时多半写得进的地方也没有。
+        file.delete()
+        Result.failure(DocumentCacheUnavailableException())
+    }
+
+    private companion object {
+        /** 合成缓存的名字前缀：与语音副本（服务端内容寻址名）在同一目录里区分开。 */
+        const val NAME_PREFIX = "tts_"
+
+        /** sha256 前 32 位十六进制，与服务端存储名 / [DocumentCache.localName] 同一长度。 */
+        const val NAME_HEX_LENGTH = 32
+
+        /**
+         * 缓存名 = `tts_<sha256(baseUrl \n sessionId \n text)[:32]>.wav`。
+         *
+         * 带上 `sessionId` 是**必须的**：发音人由会话的生效人格决定，不同会话的同一段文字
+         * 可能是两个声音。带上 `baseUrl` 同样是必须的：换一台服务器（同一个会话 id、同一段文字）
+         * 命中的会是**上一台服务器**合成的那份 WAV —— 那一台上的人格映射 / 发音人 / 合成实现
+         * 可能完全不同，播出来是别人的声音。缓存是 `cacheDir` 下的东西、系统随时可回收，
+         * 换地址后重新请求一次的代价远小于「念错了声音却看不出为什么」。
+         *
+         * 地址先 `trimEnd('/')` 归一：`http://a/` 与 `http://a` 是同一台服务器，不该分成两份缓存。
+         * `\n` 做分隔符，免得 `(a, "bc")` 与 `(ab, "c")` 撞成同一个名字。
+         */
+        fun cacheName(text: String, sessionId: String?, baseUrl: String): String {
+            val digest = MessageDigest.getInstance("SHA-256")
+                .digest(
+                    "${baseUrl.trimEnd('/')}\n${sessionId.orEmpty()}\n$text".toByteArray(Charsets.UTF_8),
+                )
+            val hex = digest.joinToString("") { "%02x".format(it) }.take(NAME_HEX_LENGTH)
+            return NAME_PREFIX + hex + ".wav"
+        }
+    }
+}
@@ -0,0 +1,219 @@
+package top.yeij.cyrene.data.voice
+
+import android.annotation.SuppressLint
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import java.io.ByteArrayOutputStream
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.domain.chat.VoiceClip
+
+/** 录音机的两个可见态（界面只认这两个）。 */
+sealed interface VoiceRecorderState {
+
+    /** 没在录。 */
+    data object Idle : VoiceRecorderState
+
+    /**
+     * 正在录。
+     *
+     * [elapsedMs] 由**已收到的字节数**反算（[VoiceClip.durationMillisOf]），不是另起一个计时器——
+     * 两个时钟一定会漂，而屏幕上那个数字必须与最终发出去的音频长度一致。
+     *
+     * [reachedLimit] = 已经录满 [VoiceClip.MAX_RECORDING_MILLIS]，此后的字节被**丢弃**（不是
+     * 悄悄截断已经收到的部分）。UI 看到它应当立刻收尾发送，见本类注释。
+     */
+    data class Recording(val elapsedMs: Int, val reachedLimit: Boolean) : VoiceRecorderState
+}
+
+/**
+ * 麦克风录音机：`AudioRecord` 收 PCM → 交给 [VoiceClip] 封 WAV（本类不碰封装，见那里的 KDoc）。
+ *
+ * ## 为什么自己持有一个作用域，而不复用调用方的 `rememberCoroutineScope`
+ * 读循环必须活到 [stop] 真的收尾：调用方的组合一旦被丢弃（转屏 / 退到后台那一刻重建），
+ * 挂在它上面的协程会被取消，而 USB/内置麦克风已经交给系统的那一块缓冲就再也取不回来——
+ * 用户按下停止却拿到一个缺尾的片段。所以读循环跑在这个类自己的 `SupervisorJob + IO` 上，
+ * 由 [release] 明确收掉。
+ *
+ * ## 满了不自动发送，只置位
+ * 到 [VoiceClip.MAX_RECORDING_MILLIS] 时把 [VoiceRecorderState.Recording.reachedLimit] 置真、
+ * 继续把多余的字节丢掉。**发送时机由 UI 决定**（它要先把「正在录」那一行换回输入栏，再交给
+ * VM）：本类不知道 VM 也不发帧，这条边界让它在单测里不必造一个 VM。
+ *
+ * ## 权限
+ * 调用方必须先拿到 `RECORD_AUDIO`（运行时权限）。本类**不申请**也不检查：`AudioRecord`
+ * 在没权限时会抛 `SecurityException`，[start] 把它连同「设备不支持 / 初始化失败」一起收敛成
+ * `false`，由 UI 按「这台设备现在开不了麦克风」说一句，**绝不静默**。
+ */
+class VoiceRecorder(
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    private val scope = CoroutineScope(SupervisorJob() + dispatcher)
+
+    private val _state = MutableStateFlow<VoiceRecorderState>(VoiceRecorderState.Idle)
+
+    /** 当前录音状态（界面据此显示「录音中 0:07」）。 */
+    val state: StateFlow<VoiceRecorderState> = _state.asStateFlow()
+
+    private var record: AudioRecord? = null
+
+    /** 收集到的 PCM；只有 [start] 建、[stop]/[cancel] 取走或丢掉。 */
+    private var collected: ByteArrayOutputStream? = null
+
+    private var reader: Job? = null
+
+    /**
+     * 录音代次：每次 [start] 自增。
+     *
+     * 只服务一件事：读循环的 `finally` 里**只在还属于这一代**时才把状态收回 [VoiceRecorderState.Idle]。
+     * 少了它，「取消 → 立刻重录」的窄窗口里，上一轮的收尾会把新那一轮的「录音中」抹成「没在录」，
+     * 而麦克风其实还在收字节——界面上什么都不显示，用户以为自己没在录。
+     */
+    private var generation = 0
+
+    @Volatile
+    private var collecting = false
+
+    /**
+     * 开始录音。
+     *
+     * @return `false` = 这台设备现在起不了麦克风（没有权限 / 设备被占用 / 不支持的采样参数）。
+     *   调用方必须**如实告知**（不得假装在录）。
+     */
+    @SuppressLint("MissingPermission")
+    fun start(): Boolean {
+        if (collecting) return false
+        val minBuffer = AudioRecord.getMinBufferSize(SAMPLE_RATE_HZ, CHANNEL_MASK, ENCODING)
+        if (minBuffer <= 0) return false
+        val recorder = runCatching {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(
+                    AudioFormat.Builder()
+                        .setEncoding(ENCODING)
+                        .setSampleRate(SAMPLE_RATE_HZ)
+                        .setChannelMask(CHANNEL_MASK)
+                        .build(),
+                )
+                // 缓冲给到最小值的两倍：读循环偶尔晚一拍时不至于立刻丢帧。
+                .setBufferSizeInBytes(minBuffer * 2)
+                .build()
+        }.getOrNull() ?: return false
+        if (recorder.state != AudioRecord.STATE_INITIALIZED) {
+            runCatching { recorder.release() }
+            return false
+        }
+        val started = runCatching { recorder.startRecording() }.isSuccess
+        if (!started) {
+            runCatching { recorder.release() }
+            return false
+        }
+        record = recorder
+        val sink = ByteArrayOutputStream(INITIAL_PCM_BYTES)
+        collected = sink
+        collecting = true
+        val current = ++generation
+        _state.value = VoiceRecorderState.Recording(elapsedMs = 0, reachedLimit = false)
+        reader = scope.launch { readLoop(recorder, sink, current) }
+        return true
+    }
+
+    /**
+     * 停止并交出这一段 PCM；`null` = 没有可发的字节（没在录 / 读失败 / 全被丢弃）。
+     *
+     * `suspend` 是刻意的：必须等读循环真的收尾（[reader] 的 `join`）才去读那份缓冲，
+     * 否则最后一块还没写进去就被取走——用户会听到句尾少一截。
+     */
+    suspend fun stop(): ByteArray? {
+        if (!collecting) return null
+        collecting = false
+        reader?.join()
+        reader = null
+        releaseRecorder()
+        _state.value = VoiceRecorderState.Idle
+        val sink = collected ?: return null
+        collected = null
+        return sink.toByteArray().takeIf { it.isNotEmpty() }
+    }
+
+    /** 取消：丢掉已经收到的字节，一个都不发（用户点了「取消」）。 */
+    fun cancel() {
+        collecting = false
+        reader?.cancel()
+        reader = null
+        releaseRecorder()
+        collected = null
+        _state.value = VoiceRecorderState.Idle
+    }
+
+    /** 组合被丢弃时调（等价于 [cancel]：一段没发出去的录音不该在后台继续占着麦克风）。 */
+    fun release() = cancel()
+
+    /**
+     * 读循环：一块一块收进 [sink]，顺手更新已录时长；满了之后**丢字节但不打断录音**
+     * （见类注释「满了不自动发送」）。
+     *
+     * 读出错（`read < 0`）就结束这一次录音：硬件被抢走、设备被拔出都会走到这里，此时
+     * 已经收到的部分仍然有效（[stop] 照常交出它们）。
+     *
+     * @param generation 启动时那一代的编号：收尾只在自己还是「当前这一代」时才改状态。
+     */
+    private suspend fun readLoop(recorder: AudioRecord, sink: ByteArrayOutputStream, generation: Int) {
+        val buffer = ByteArray(READ_BYTES)
+        try {
+            while (collecting) {
+                val read = recorder.read(buffer, 0, buffer.size)
+                if (read < 0) break
+                if (read == 0) continue
+                val used = sink.size()
+                if (used < VoiceClip.MAX_PCM_BYTES) {
+                    sink.write(buffer, 0, minOf(read, VoiceClip.MAX_PCM_BYTES - used))
+                }
+                val elapsed = VoiceClip.durationMillisOf(minOf(sink.size(), VoiceClip.MAX_PCM_BYTES))
+                _state.value = VoiceRecorderState.Recording(
+                    elapsedMs = elapsed,
+                    reachedLimit = elapsed >= VoiceClip.MAX_RECORDING_MILLIS,
+                )
+            }
+        } finally {
+            // 读循环自己结束（出错 / 被取消）时也要把状态收回 Idle，否则界面会永远停在「录音中」。
+            // 只在自己还是当前这一代时才收：否则「取消 → 立刻重录」的窄窗口里，上一轮的收尾
+            // 会把新一轮的「录音中」擦掉。
+            if (generation == this.generation && _state.value is VoiceRecorderState.Recording) {
+                _state.value = VoiceRecorderState.Idle
+            }
+        }
+    }
+
+    /** 把 `AudioRecord` 拆干净（`stop` 在没起录时抛 `IllegalStateException`，所以都包在 `runCatching` 里）。 */
+    private fun releaseRecorder() {
+        val current = record ?: return
+        record = null
+        runCatching { current.stop() }
+        runCatching { current.release() }
+    }
+
+    private companion object {
+        val SAMPLE_RATE_HZ: Int = VoiceClip.SAMPLE_RATE_HZ
+        const val ENCODING: Int = AudioFormat.ENCODING_PCM_16BIT
+        const val CHANNEL_MASK: Int = AudioFormat.CHANNEL_IN_MONO
+
+        /**
+         * 一次读多少字节：`2048` = 16 kHz 下单声道 16-bit 的 64 ms（1024 帧）。
+         * 比这更小则更新频率过高（每秒几十次状态写），更大则「停止」那一刻的延迟可感。
+         */
+        const val READ_BYTES: Int = 2048
+
+        /** 初始缓冲按 10 秒预分配（够大多数语音，长的那条会自己扩容）。 */
+        val INITIAL_PCM_BYTES: Int = VoiceClip.pcmBytesFor(10_000)
+    }
+}
@@ -2,6 +2,7 @@ package top.yeij.cyrene.data.ws

 import top.yeij.cyrene.core.auth.AuthRecovery
 import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.domain.chat.parallelWireValue
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.CoroutineScope
@@ -32,13 +33,11 @@ import kotlin.random.Random
 * Cyrene 实时通道客户端（`GET /ws/chat?token=<JWT>`，api-reference §6）。
 *
 * ## 用法
+ * 进程内只有**一个**实例，由 `AppContainer.chatSocket` 持有；上层要收帧就取它，**不要自己 new**
+ * （见下面「它不是某个屏幕的私有连接」）：
 * ```
- * val socket = ChatSocket(baseUrlProvider = { cfg.baseUrl }, tokenProvider = { auth.token },
- *                         onAuthFailed = { auth.logout() })
- * socket.connect()
- * // 收集 socket.events，观察 socket.state
- * socket.sendChat(sessionId = "web", text = "你好", deviceId = deviceId)
- * socket.close()
+ * val socket = container.chatSocket
+ * // 收集 socket.events，观察 socket.state；发送用 socket.sendChat / socket.sendInterrupt
 * ```
 *
 * ## 会话归属
@@ -46,6 +45,20 @@ import kotlin.random.Random
 * （见 [WsEvent.sessionId]），不补值。服务端广播**不按会话订阅**：同一条连接会收到**所有**
 * 会话的帧，因此收集 [events] 的上层**必须**按 [WsEvent.isForSession] 收敛到自己的会话。
 *
+ * ## 它不是某个屏幕的私有连接：谁都不许关它
+ * 本实例是**进程级共享**的一条连接——所有需要收帧的 ViewModel 订阅的是同一份 [events] / [state]。
+ * 之所以能共享，正是靠上面那条广播语义：「一条连接收到全部帧」与「N 条连接各收全部帧」对上层是
+ * **同一个语义**，每个 VM 收到的帧集合逐帧相同，所以共享改的只是「连接有几条」（连带每个连接
+ * 各带一个 `OkHttpClient` 的成本），不是「帧怎么走」——各 VM 的会话过滤逻辑**一个字都不用动**。
+ *
+ * 由此推出两条硬约束：
+ * 1. **[close] 只归应用级的那条登出 / 会话失效路径**（目前唯一调用点：`SessionsViewModel` 的
+ *    登录态订阅，见 `AppContainer.chatSocket`）。任何 ViewModel 在 `onCleared` 里关它、页面退出时
+ *    关它，都会把**别的屏幕**一起掐断——切会话会掐掉抽屉未读与管理页三帧，关管理页会掐掉主会话的
+ *    流式。连接的生命周期是**进程 + 登录态**，不是屏幕。
+ * 2. **[events] 的 `replay` 恒为 0**（理由见那里的 KDoc）：共享之后，新建的 VM 会立刻订阅同一份流，
+ *    replay > 0 就等于把**历史**下行帧投给一个新来的订阅者。
+ *
 * ## 心跳与重连
 * - OkHttp `pingInterval` 30s（服务端 ping 周期 54s / pong 等待 60s，客户端 30s 足够）。
 * - 服务端**没有 resume / 补发**：重连成功后由上层用新连接的 `history` 帧 + REST 补差去重。
@@ -75,6 +88,16 @@ class ChatSocket(
    /** 连接状态机；见 [WsState]。 */
    val state: StateFlow<WsState> = _state.asStateFlow()

+    /**
+     * 诊断用：此刻底层连接对象还在不在（`webSocket != null`）。
+     *
+     * 只读、不改变任何行为，也**不是**产品逻辑的输入（`send` 判的是 [state] 与这个对象本身）。
+     * 它存在只为一件事：让「这一帧为什么没走 WS」在 logcat 里可读——[state] 与它**可能不一致**
+     * （状态还是 `Connected` 而对象已经被 `finally` 清空、或者反过来），而那个不一致正是
+     * `WsSendOutcome.Failed` 与 `Queued` 的分水岭。tag 见 `ChatViewModel.SEND_ROUTE_LOG_TAG`。
+     */
+    val hasLiveSocket: Boolean get() = webSocket != null
+
    private val _events = MutableSharedFlow<WsEvent>(
        replay = 0,
        extraBufferCapacity = EVENT_BUFFER,
@@ -84,7 +107,10 @@ class ChatSocket(
    /**
     * 下行事件流。
     *
-     * `replay = 0`：重放旧 delta 会让新订阅者重复渲染，会话状态应由 `history` / REST 重建。
+     * **`replay` 恒为 0，这条不是调优而是必需**：重放旧 delta 会让新订阅者重复渲染，会话状态应由
+     * `history` / REST 重建；而连接**进程内共享**之后，新建的 VM（切到一个没访问过的会话）会**立刻**
+     * 订阅同一份流——replay > 0 等于把历史帧投给它，轻则重复渲染，重则会话串台。
+     *
     * `extraBufferCapacity = 512 + DROP_OLDEST`：发送方是 OkHttp 读线程，不能阻塞；溢出时丢最旧的
     * 增量帧（服务端发送缓冲 32 本就会丢帧，`stream_end` / `history` 仍可兜底）。
     */
@@ -114,7 +140,12 @@ class ChatSocket(

    private var scope: CoroutineScope? = null

-    /** 开始连接（幂等：已在连接 / 重连中时忽略）。 */
+    /**
+     * 开始连接。**幂等**：已经在连接 / 重连中（[wantConnection] 已置位）时直接返回。
+     *
+     * 因为幂等，任何一个 VM 都可以在需要时调它做兜底；但**决定它该不该在**的只有登录态那条路径
+     * （见类注释的硬约束 1），本方法只负责「接上」。
+     */
    fun connect() {
        if (wantConnection) return
        wantConnection = true
@@ -123,7 +154,14 @@ class ChatSocket(
        sessionJob = ensureScope().launch { runConnectionLoop() }
    }

-    /** 主动断开并停掉重连；之后可再次 [connect]。 */
+    /**
+     * 主动断开并停掉重连；之后可再次 [connect]。
+     *
+     * ⚠️ 本实例是**进程级共享连接**，不是某个屏幕的私有连接：**只有应用级的登出 / 会话失效路径可以
+     * 调它**（目前唯一调用点：`SessionsViewModel` 的登录态订阅）。ViewModel 的 `onCleared`、
+     * 页面退出、切会话都**不许**调——那会把别的屏幕正在用的连接一起掐断。理由见类注释
+     * 「它不是某个屏幕的私有连接：谁都不许关它」。
+     */
    fun close() {
        wantConnection = false
        val socket = webSocket
@@ -139,19 +177,28 @@ class ChatSocket(
    /**
     * 发送 `chat`（api-reference §6.3）。
     * @param clientMsgId 幂等键（契约 v0.56 §3.13）；重复到达服务端回 `chat_duplicate`，不落库。
-     * @return 未连接或写失败返回 `false`（本层不做离线队列，由上层标红重试）。
+     * @param parallel 要不要声明 `parallel:true`（忙时并行规范 §2.2）——**默认 `false` = 一个字节
+     *   都不带该键**，线上帧与加入本参数之前**逐字节相同**。调用方只有一处：`ChatViewModel.deliver`，
+     *   它按 App 偏好（`InterruptMode`）与「会话是否正忙」算出来（判据是纯函数 `parallelForSend`）。
+     * @return 未连接或写失败返回 `false`（本层不做离线队列；上层按**这一刻的连接状态**分档处置：
+     *   未就绪 ⇒ 记住这条、连接恢复后按序补发，连接就绪却仍发不出去 ⇒ 回滚 + 诚实文案——
+     *   判据是 `ChatViewModel.deliver` 里的纯函数 `wsSendOutcome`）。
     */
    fun sendChat(
        sessionId: String?,
        text: String,
        deviceId: String?,
        clientMsgId: String? = null,
+        parallel: Boolean = false,
    ): Boolean = send(
        WsOutbound.Chat(
            text = text,
            sessionId = sessionId,
            deviceId = deviceId,
            clientMsgId = clientMsgId,
+            // 直接传 `false` 会序列化成 `"parallel":false`（`WsOutbound.Chat` 只在 `null` 时省略该键），
+            // 那不是「未声明」而是**显式否认**——默认两档必须逐字节不变 ⇒ 只有 true 才带上该键。
+            parallel = parallelWireValue(parallel),
        ),
    )

@@ -162,12 +209,51 @@ class ChatSocket(
     *   与加入 `scope` 之前**逐字节相同**）；`"current"` = 只取消在跑回合、保留待处理队列。
     *   其它取值原样发出，服务端**定向**回 `error{bad_request}` 且不打断任何会话（本层不预判取值域）。
     *
-     * **今天没有任何调用方**：聊天的「打断」触发点属聊天区那一轮，本 API 先把传输面备好——
-     * 调用方从 App 偏好（`InterruptMode`）取 `scope` 后传进来即可。
+     * **调用方有两处，两处都只发 `"current"`**（本端从不发 `all`，见 `devdocs/02` 的 A2 补记）：
+     * 1. `ChatViewModel.interruptRunningTurn()`——它在一条消息真的要走上去**之前**按 App 偏好
+     *    （`InterruptMode`）决定要不要先打断，且**只在会话正忙时**发（判据是纯函数
+     *    `interruptScopeForSend`）。默认档「追加队列」与「并行」这一档都恒不发（后者的 `wireScope`
+     *    就是 `null`：并行与打断互斥），所以本方法只服务「打断」这一档。
+     * 2. `SessionsViewModel.stopGenerating(sessionId)`——抽屉里那一行的「停止」（W52B）：它是一个
+     *    **独立的动作**（不读偏好），停的是**指定会话**正在跑的那一轮。`WsOutbound.Interrupt`
+     *    本来就带 `sessionId`，所以「停某一个会话」这条既有出口表达得了，不需要新帧。
+     *
+     * 返回 false 只有一种原因（WS 未连接）：两处调用方都**静默**，理由见各自的 KDoc。
     */
    fun sendInterrupt(sessionId: String, scope: String? = null): Boolean =
        send(WsOutbound.Interrupt(sessionId = sessionId, scope = scope))

+    /**
+     * 发送 `voice_input`（契约 v0.96 §3.15）：一段 base64 音频 + 格式，走与 `chat` 同一条出站通道。
+     *
+     * ## 为什么没有「离线队列」
+     * 文本那条有补发队列（内容只是一小段字符串，留着不贵）；语音的 audio 是**几 MB 的 base64**
+     * 内联在帧里，队列化它等于把这段内存钉在待发状态里，而重连之后服务端到底要不要它、要哪一段
+     * 又都是用户该重新决定的事。所以本层与 [sendChat] 一样：**发不出去就回 `false`**，由
+     * `ChatViewModel` 把这段留在内存里、让用户按「重发」（复用同一个 `clientMsgId`）。
+     *
+     * @param audio base64（单行，`Base64.NO_WRAP`）。
+     * @param format 契约白名单 `wav|mp3|ogg` 之一；本端恒 `"wav"`。
+     * @param deviceId 与 `chat` 帧同一份来源标识。
+     * @param clientMsgId 幂等键：同一段语音重发**必须复用**（否则服务端会把同一句话说两遍）。
+     * @return 未连接 / 写失败返回 `false`。
+     */
+    fun sendVoiceInput(
+        sessionId: String?,
+        audio: String,
+        format: String,
+        deviceId: String?,
+        clientMsgId: String?,
+    ): Boolean = send(
+        WsOutbound.VoiceInput(
+            audio = audio,
+            format = format,
+            sessionId = sessionId,
+            deviceId = deviceId,
+            clientMsgId = clientMsgId,
+        ),
+    )
+
    private fun send(outbound: WsOutbound): Boolean {
        if (_state.value != WsState.Connected) return false
        val socket = webSocket ?: return false
@@ -190,10 +190,19 @@ sealed class WsEvent {
        override val type: String get() = "tool_execution.update"
    }

-    /** 工具执行**完成或失败**（契约 v0.50）：`phase:"error"` 即失败。 */
+    /**
+     * 工具执行**完成或失败**（契约 v0.50）：`phase:"error"` 即失败。
+     *
+     * [resultSummary] 是**执行结果摘要**（新契约切片，与回看面 `toolCalls[].resultSummary` 同一份预算：
+     * 已经脱敏、已经截断 ≤500 字符的成品，本端只展示）。它的语义是**缺席即「不知道」**：
+     * 只有这一轮的执行结果**真的拿到了**才在场，失败 / 取消 / 超时 / 未落图时后端**整个键省略**
+     * （且承诺不用空串顶位）。所以 `null` 与 `""` 在本端都读作**不知道**——绝不解成「没有输出」，
+     * 因为那是替服务端下一个它没下的结论。当前服务端**尚未部署**该键 ⇒ 真机上它恒缺席。
+     */
    data class ToolExecutionEnd(
        val tool: String,
        val phase: String,
+        val resultSummary: String? = null,
        val id: String? = null,
        override val turnId: String? = null,
        override val seq: Long? = null,
@@ -227,12 +236,93 @@ sealed class WsEvent {
        override val type: String get() = "stream_end"
    }

+    /**
+     * **新帧 `turn_begin`**（忙时并行规范 §2.4）：编排器**每次启动一路**时发一次，
+     * 把「服务端刚起的这一路 ↔ 它归属的用户消息 id」钉死。
+     *
+     * 客户端靠它（而不是靠猜）做三件事：① 按 `messageIds` 把那些气泡置为**灰态**（④）；
+     * ② 建立「消息 ↔ 回合」绑定，好在收口时用该 `turnId` 的 `turn.end` 配对；③ 按 `turnId` 分桶。
+     *
+     * [kind] ∈ `"turn"` \| `"parallel"`：服务端**实际**如何起这条路（新回合 / 续跑 = `"turn"`，
+     * 声明并行且照准 = `"parallel"`）。规范 §2.4 说状态机不必依赖它，本端照办：[messageIds] 仍是
+     * 六态的唯一判据。但**「这一路是不是并行路」只有它说了算**——[leg] 是**会话内第几条路**
+     * （服务端对每条新路都自增，普通串行回合照样占号），拿它当并行的证据会挂出并不存在的
+     * 「并行路 N」。所以本端把它带进绑定（`TurnBinding.parallel`），只喂给路小标那一处；
+     * 缺席（老服务端整键不给）时为空串 ⇒ 认不出来 ⇒ 不挂角标。
+     *
+     * [leg] 是该路的会话内序号（1 基，`1` = 第一路），注意它**不是**「并行组里的第几路」。
+     * 小标文案取它，但是否挂标取 [kind]。
+     * [activeTurns] 是**本次启动后**该会话的在途路数。
+     *
+     * 帧壳的 `sessionId` 是权威归属（`data` 内不重复，规范 §2.4）；本端仍按既有口径
+     * 「`data` 有值就优先，否则用帧壳」解析，两边都不给时按「无法判定」放行（见 [isForSession]）。
+     *
+     * **帧壳 `turnId` 是这一路的唯一权威标识**（规范附录明写：它必须与该路全部流帧同值）。
+     * 它缺席（`null`）时本端**不做任何绑定**——没有 key 的绑定永远收不了口，那不是绑定，
+     * 是一个永远灰着的气泡；此时整帧只消费 [activeTurns]，其余部分与今天一致。
+     */
+    data class TurnBegin(
+        override val sessionId: String,
+        val kind: String = "",
+        val messageIds: List<String> = emptyList(),
+        val leg: Int = 0,
+        val activeTurns: Int = 0,
+        override val turnId: String? = null,
+        override val seq: Long? = null,
+    ) : WsEvent() {
+        override val type: String get() = "turn_begin"
+    }
+
+    /**
+     * **`turn.end`**：一路的**整轮**结束（覆盖最终答案 / 工具循环终止 / 预算耗尽 / 出错四种出口）。
+     *
+     * 它是灰态（④）收口的**唯一权威事件**（规范 §1.2）：拿帧壳的 [turnId] 与消息绑定的 `turnId`
+     * 比对，相等即收口。规范特意说明为什么不能用正文到齐来收口——一轮里有多个正文段（`message.end`
+     * 只结束**一段**），只有 `turn.end` 结束**整轮**。
+     *
+     * 它由 loop 发出、经网关的流式广播路径下发（`broadcastStream` 会给它打上 `sessionId` + `turnId`），
+     * 因此**一直存在于线上**，只是本端此前把它当未知帧丢掉了（`type` 不在 `when` 里 ⇒ `parse` 回
+     * `null`）。补上它的解析不改变任何既有行为（此前没有任何消费者）。
+     */
+    data class TurnEnd(
+        override val sessionId: String? = null,
+        override val turnId: String? = null,
+        override val seq: Long? = null,
+    ) : WsEvent() {
+        override val type: String get() = "turn.end"
+    }
+
+    /**
+     * `steer_ack`：这条消息**已被本回合吃进**（已从 pending 移除、尚未被正面回答）⇒ 灰态（④）。
+     *
+     * 契约 v0.57 起 [messageId] / [atStep] 就在，**一字未变**；忙时并行规范 §2.5 **只新增帧壳
+     * `turnId`**——并行下它是**必需**字段：没有它就不知道这条消息被**哪一路**吃进，灰态无法与
+     * 正确的 `turn.end` 配对（这正是「两路并行」相对「单路」多出来的唯一一件事）。
+     *
+     * 帧壳 `turnId` 缺席时本端**不消费这一帧**（老服务端就是这样）——那样绑出来的绑定永远收不了口，
+     * 宁可保持今天的样子（什么都不发生），也不留下一个永远灰着的气泡。
+     */
+    data class SteerAck(
+        override val sessionId: String,
+        val messageId: String,
+        val atStep: Int,
+        override val turnId: String? = null,
+        override val seq: Long? = null,
+    ) : WsEvent() {
+        override val type: String get() = "steer_ack"
+    }
+
    /** 会话进入忙碌态。`mode` ∈ `idle` / `thinking` / `executing` / `subagent`。 */
    data class SessionBusy(
        override val sessionId: String,
        val mode: String,
        override val turnId: String? = null,
        override val seq: Long? = null,
+        /**
+         * 该帧发出时的**在途路数**（忙时并行规范 §1.5 / §2.6，**纯增量**）。
+         * `null` = 服务端没给这个键（v0.65 之前）⇒ 客户端**不动**任何计数，行为与今天逐字相同。
+         */
+        val activeTurns: Int? = null,
    ) : WsEvent() {
        override val type: String get() = "session_busy"
    }
@@ -244,6 +334,12 @@ sealed class WsEvent {
        val queueDepth: Int,
        override val turnId: String? = null,
        override val seq: Long? = null,
+        /**
+         * 入队的原因码（忙时并行规范 §2.6，**纯增量**）。已知取值 `"parallel_limit"`
+         * （声明了并行但额度已满、已落回排队）。其它情况**整键缺席**（`null`）——
+         * 服务端明写「绝不伪造」，所以这里也**绝不**给它一个默认值。
+         */
+        val reason: String? = null,
    ) : WsEvent() {
        override val type: String get() = "pending_ack"
    }
@@ -255,27 +351,52 @@ sealed class WsEvent {
        val queueDepth: Int,
        override val turnId: String? = null,
        override val seq: Long? = null,
+        /** 见 [SessionBusy.activeTurns]（忙时并行规范 §2.6）。 */
+        val activeTurns: Int? = null,
    ) : WsEvent() {
        override val type: String get() = "pending_drain"
    }

-    /** 会话回到空闲、队列清空。 */
+    /**
+     * 会话回到空闲、队列清空。
+     *
+     * ⚠️ **时点在并行时收紧**（规范 §1.5）：它现在只在**所有在途路都收尾**且 pending 空时才发；
+     * 单路时与今天逐字相同。所以「`session_idle` 到了 = 这个会话真的闲了」这条既有推论仍然成立，
+     * 客户端**不必**改任何既有逻辑。
+     */
    data class SessionIdle(
        override val sessionId: String,
        val mode: String,
        override val turnId: String? = null,
        override val seq: Long? = null,
+        /** 见 [SessionBusy.activeTurns]（忙时并行规范 §2.6）。 */
+        val activeTurns: Int? = null,
    ) : WsEvent() {
        override val type: String get() = "session_idle"
    }

-    /** 用户打断：当前任务取消、pending 清空，`dropped` 为丢弃条数。 */
+    /**
+     * 用户打断：当前任务取消。
+     *
+     * [dropped] **只在我们发了 `scope:"all"` 时才可能非零**（那档会清空待处理队列，`dropped` = 被清掉的
+     * 条数，且 [mode] 为 `idle`）；**本端从不发 `all`** —— 「追加队列」档一个 `interrupt` 都不发，
+     * 「打断」档发的是 `scope:"current"`（只取消在跑回合、**保留**待处理队列）⇒ 在客户端的全部现实路径里
+     * [dropped] **恒为 0**（契约 v0.56 明文）。所以「已打断，丢弃 N 条」那句话在本端是**不可达**的，
+     * 别照着它去实现一个用不上的计数（见 `devdocs/03` §4 的同一条更正）。
+     */
    data class SessionInterrupted(
        override val sessionId: String,
        val mode: String,
        val dropped: Int,
        override val turnId: String? = null,
        override val seq: Long? = null,
+        /** 见 [SessionBusy.activeTurns]（忙时并行规范 §2.6）。 */
+        val activeTurns: Int? = null,
+        /**
+         * 本次**真的取消了几路**（忙时并行规范 §2.6，**纯增量**）。
+         * 单路时它只会是 `0` 或 `1`；`null` = 服务端没给这个键。
+         */
+        val cancelledTurns: Int? = null,
    ) : WsEvent() {
        override val type: String get() = "session_interrupted"
    }
@@ -347,9 +468,21 @@ sealed class WsEvent {
        override val type: String get() = "session_read"
    }

-    /** 主会话（`web` / `web:<uuid>`）消息落库后广播。 */
+    /**
+     * 主会话（`web` / `web:<uuid>`）消息落库后广播。
+     *
+     * [proactive] = **这句话是她主动说的**（v0.72 起，服务端走 IM 桥那条路由时会补发这一帧，
+     * 并在帧上打这个判据）。它此前被本端**丢掉**了：`data` 只解 `message`，而生产 `Json` 是
+     * `ignoreUnknownKeys = true` ⇒ 这个键既没被解、也不会报错，于是「她主动说的话走了落库这条路」
+     * 这件事在客户端**完全不可见**（W53N 的通知判据正是靠它）。
+     *
+     * 判据的两种落点都接受（见 [parse]）：`data.proactive` 与帧壳顶层的 `proactive` 取**或**。
+     * 契约只说「帧顶带它」，没说清是帧壳还是载荷，而**猜错就是整个功能静默失效**——所以两处都读。
+     * 缺席（`false`）= 普通消息，绝不弹通知（主人只批了 proactive 这一档）。
+     */
    data class MessagePersisted(
        val message: HistoryMessageDto?,
+        val proactive: Boolean = false,
        override val turnId: String? = null,
        override val seq: Long? = null,
        override val sessionId: String? = null,
@@ -467,12 +600,30 @@ sealed class WsEvent {
        override val type: String get() = "observability_log"
    }

-    /** 语音合成回复（定向回请求连接）。 */
+    /**
+     * 语音合成回复（契约 v0.96 §3.15）：`{audio, format, text, reply, sessionId, deviceId?, provider?}`。
+     *
+     * ## 会话归属**只在 `data` 里**
+     * 契约明写这帧的帧壳**没有** `sessionId`（与其它结构化流帧不同），会话 id 在载荷上。
+     * 所以解析层用既有口径 [`resolveSessionId`] 把它提到 [sessionId] 上：帧壳有就用帧壳，
+     * 否则用 `data` 里那一份。少了这一步，`isForSession` 会把帧**放行给每一个会话的 VM**
+     * （空值 = 无法判定），于是切到别的会话时也会响一段本属于别的会话的语音。
+     *
+     * ## 只定向回发起 `voice_input` 的那条连接、断线不补投
+     * 这是契约的明确边界，不是缺口：本端**不**为它做任何「重连后拉取」的补救（历史靠 REST，
+     * 音频只在这一次连接里存在）。所以这一帧只有「当场播放 / 当场显示」这一种用途。
+     *
+     * [text] 是**转写**（那段音频被识别成什么），[reply] 是**她说的话**——两者的取舍见
+     * `domain.chat.voiceReplyText`。[provider] 是降级信号（`silent` = 这一轮没有真音频），
+     * 判据见 `domain.chat.voiceOutputHasAudio`。
+     */
    data class VoiceOutput(
        val audio: String?,
        val format: String?,
        val text: String?,
        val reply: String?,
+        val deviceId: String? = null,
+        val provider: String? = null,
        override val turnId: String? = null,
        override val seq: Long? = null,
        override val sessionId: String? = null,
@@ -480,7 +631,21 @@ sealed class WsEvent {
        override val type: String get() = "voice_output"
    }

-    /** 自主主动推送（仅 owner/admin 连接收到）。 */
+    /**
+     * 自主主动推送（仅 owner/admin 连接收到）。
+     *
+     * v0.72 起她主动说的话**同时是主会话历史里的真消息**（`web` / `assistant` / `turn_id` 空），
+     * 载荷因此多带两个键：[id] / [createdAt] = 那条**落库行**的权威 id 与时间戳。
+     * 它与 [messageId]（IM 侧的消息号）是**两个不同的 id**，拿后者当去重键永远对不上历史行。
+     * 落库失败时这两个键**一起缺席**——那是「这条只有实时帧、没有历史行」的唯一标志，
+     * 消费方据此退化（见 [top.yeij.cyrene.ui.chat.proactiveIngestFor]）。
+     *
+     * [timestamp] 是服务端侧这条统一消息**自身**的时间。线上是 Go `time.Time` ⇒ **RFC3339 字符串**
+     * （数字形状也容忍）；它只作诊断，排序与去重一律用 [createdAt]（Unix 毫秒）。
+     *
+     * ⚠️ 帧壳**不带** `sessionId`（服务端构造这一帧时没设它，且该键是 `omitempty`）——所以
+     * [isForSession] 会把这帧**放行给每一个会话的 VM**，归属只能由消费方自己钉死（它属于主会话）。
+     */
    data class ProactiveMessage(
        val platform: String?,
        val channelId: String?,
@@ -488,8 +653,10 @@ sealed class WsEvent {
        val content: String,
        val contentType: String?,
        val sender: String?,
-        val timestamp: Long?,
+        val timestamp: String?,
        val messageId: String?,
+        val id: String? = null,
+        val createdAt: Long? = null,
        override val turnId: String? = null,
        override val seq: Long? = null,
        override val sessionId: String? = null,
@@ -539,7 +706,16 @@ sealed class WsEvent {
            val seq = root["seq"].asStringOrNull()?.toLongOrNull()
            val sessionId = root["sessionId"].asStringOrNull()
            val data = root["data"]?.takeIf { it !is JsonNull }
-            return runCatching { dispatch(type, turnId, seq, sessionId, data) }.getOrNull()
+            val event = runCatching { dispatch(type, turnId, seq, sessionId, data) }.getOrNull()
+                ?: return null
+            // 帧顶那一位 `proactive`（见 [MessagePersisted]）。这一层只对落库帧有意义，载荷里的那一份
+            // 由 [PersistedData] 解出来，两边**取或**：契约写的是「帧顶带它」而没说是帧壳还是载荷，
+            // 而猜错的方向是「功能静默失效」，所以两处都认。
+            return if (event is MessagePersisted && root.frameProactive()) {
+                event.copy(proactive = true)
+            } else {
+                event
+            }
        }

        private fun dispatch(
@@ -611,10 +787,14 @@ sealed class WsEvent {
            "tool_execution.update" -> decode<ToolExecutionData>(data)
                .let { ToolExecutionUpdate(it.tool, it.phase, it.delta, it.id, turnId, seq, sessionId) }
            "tool_execution.end" -> decode<ToolExecutionData>(data)
-                .let { ToolExecutionEnd(it.tool, it.phase, it.id, turnId, seq, sessionId) }
+                .let { ToolExecutionEnd(it.tool, it.phase, it.resultSummary, it.id, turnId, seq, sessionId) }
            "stream_chunk" -> StreamChunk(decode<StreamChunkData>(data).delta, turnId, seq, sessionId)
            "stream_end" -> decode<StreamEndData>(data)
                .let { StreamEnd(it.stopReason, it.steps, it.error, turnId, seq, sessionId) }
+            // `turn.end` 的载荷是**空的**（后端 `streamEventData` 里 `StreamKindTurnEnd` 直接返回
+            // `nil`），全部信息都在帧壳上（`sessionId` + `turnId`）——所以这里不 decode payload，
+            // 也**不**因为 `data` 缺席而把它当坏帧（那正是「灰态收不了口」的成因）。
+            "turn.end" -> TurnEnd(sessionId, turnId, seq)
            else -> null
        }

@@ -626,15 +806,63 @@ sealed class WsEvent {
            data: JsonElement?,
        ): WsEvent? = when (type) {
            "session_busy" -> decode<SessionModeData>(data)
-                .let { SessionBusy(resolveSessionId(sessionId, it.sessionId), it.mode, turnId, seq) }
+                .let {
+                    SessionBusy(
+                        resolveSessionId(sessionId, it.sessionId), it.mode, turnId, seq, it.activeTurns,
+                    )
+                }
            "pending_ack" -> decode<PendingData>(data)
-                .let { PendingAck(resolveSessionId(sessionId, it.sessionId), it.mode, it.queueDepth, turnId, seq) }
+                .let {
+                    PendingAck(
+                        resolveSessionId(sessionId, it.sessionId), it.mode, it.queueDepth, turnId, seq, it.reason,
+                    )
+                }
            "pending_drain" -> decode<PendingData>(data)
-                .let { PendingDrain(resolveSessionId(sessionId, it.sessionId), it.mode, it.queueDepth, turnId, seq) }
+                .let {
+                    PendingDrain(
+                        resolveSessionId(sessionId, it.sessionId), it.mode, it.queueDepth, turnId, seq, it.activeTurns,
+                    )
+                }
            "session_idle" -> decode<SessionModeData>(data)
-                .let { SessionIdle(resolveSessionId(sessionId, it.sessionId), it.mode, turnId, seq) }
+                .let {
+                    SessionIdle(
+                        resolveSessionId(sessionId, it.sessionId), it.mode, turnId, seq, it.activeTurns,
+                    )
+                }
            "session_interrupted" -> decode<InterruptedData>(data)
-                .let { SessionInterrupted(resolveSessionId(sessionId, it.sessionId), it.mode, it.dropped, turnId, seq) }
+                .let {
+                    SessionInterrupted(
+                        resolveSessionId(sessionId, it.sessionId),
+                        it.mode,
+                        it.dropped,
+                        turnId,
+                        seq,
+                        it.activeTurns,
+                        it.cancelledTurns,
+                    )
+                }
+            // 新帧 `turn_begin`（忙时并行规范 §2.4）：帧壳带 sessionId + turnId，载荷给
+            // kind / messageIds / leg / activeTurns（**不含** sessionId）。
+            "turn_begin" -> decode<TurnBeginData>(data)
+                .let {
+                    TurnBegin(
+                        resolveSessionId(sessionId, it.sessionId),
+                        it.kind,
+                        it.messageIds.filter(String::isNotBlank),
+                        it.leg,
+                        it.activeTurns,
+                        turnId,
+                        seq,
+                    )
+                }
+            // `steer_ack`（v0.57 形状 + 忙时并行规范 §2.5 的帧壳 turnId）：载荷只有
+            // messageId / atStep；会话归属两边都可能有（取有值者）。
+            "steer_ack" -> decode<SteerAckData>(data)
+                .let {
+                    SteerAck(
+                        resolveSessionId(sessionId, it.sessionId), it.messageId, it.atStep, turnId, seq,
+                    )
+                }
            "pending_full" -> decode<PendingFullData>(data).let {
                PendingFull(
                    resolveSessionId(sessionId, it.sessionId),
@@ -660,8 +888,15 @@ sealed class WsEvent {
            // 已读游标（D4 §3.9）：会话归属只在帧壳上（data 只有 readAt）。
            "session_read" -> decode<SessionReadData>(data)
                .let { SessionRead(resolveSessionId(sessionId, ""), it.readAt, turnId, seq) }
-            "message_persisted" -> decode<PersistedData>(data)
-                .let { MessagePersisted(it.message, turnId, seq, sessionId ?: it.message?.sessionId) }
+            "message_persisted" -> decode<PersistedData>(data).let {
+                MessagePersisted(
+                    message = it.message,
+                    proactive = it.proactive.asTrue(),
+                    turnId = turnId,
+                    seq = seq,
+                    sessionId = sessionId ?: it.message?.sessionId,
+                )
+            }
            "channel_persisted" -> decode<PersistedData>(data)
                .let { ChannelPersisted(it.message, turnId, seq, sessionId ?: it.message?.sessionId) }
            // 消息编辑（D3 §3.8）：`data` **就是**编辑后的完整消息 DTO——**没有** `message`
@@ -673,12 +908,27 @@ sealed class WsEvent {
            // 消息删除（D3 §3.8）：载荷只有 id，会话归属**只在帧壳**上（缺席时上层按全局唯一 id 兜底）。
            "message_deleted" -> decode<DeletedData>(data)
                .let { MessageDeleted(it.id, turnId, seq, sessionId) }
-            "voice_output" -> decode<VoiceOutputData>(data)
-                .let { VoiceOutput(it.audio, it.format, it.text, it.reply, turnId, seq, sessionId) }
+            "voice_output" -> decode<VoiceOutputData>(data).let {
+                VoiceOutput(
+                    audio = it.audio,
+                    format = it.format,
+                    text = it.text,
+                    reply = it.reply,
+                    deviceId = it.deviceId,
+                    provider = it.provider,
+                    turnId = turnId,
+                    seq = seq,
+                    // 帧壳**没有** sessionId（契约 v0.96），归属在 data 里 ⇒ 走既有口径提到帧上。
+                    sessionId = resolveSessionId(sessionId, it.sessionId),
+                )
+            }
+            // 她主动说的话（v0.72）。帧壳**没有** `sessionId`（服务端不设），与会话归属有关的一切
+            // 都在载荷里（落库行 id / 时间戳）+ 消费方自己钉「主会话」这条事实，见 [ProactiveMessage]。
            "proactive_message" -> decode<ProactiveData>(data).let {
                ProactiveMessage(
                    it.platform, it.channelId, it.channelType, it.content, it.contentType,
-                    it.sender, it.timestamp, it.messageId, turnId, seq, sessionId,
+                    it.sender, it.timestamp.asStringOrNull(), it.messageId, it.id, it.createdAt,
+                    turnId, seq, sessionId,
                )
            }
            // 定向错误帧（含队列满的伴生帧）：编码是开放集合，原样带上，未知码不做语义处置。
@@ -739,6 +989,22 @@ private fun JsonElement?.asStringOrNull(): String? {
    return primitive.content
 }

+/**
+ * 帧壳顶层的 `proactive` 是否为真。
+ *
+ * 只认**字面量** `true`（布尔或字符串 `"true"`），其余（键缺席、`false`、`JsonNull`、数字、对象）
+ * 一律按假——这个键的方向必须偏「不打扰」：判错成真会给一条普通消息弹出通知，而主人只批了
+ * proactive 那一档；判错成假的最多是她主动说的话没弹通知（不打扰人，也不撒谎）。
+ */
+private fun JsonObject.frameProactive(): Boolean = this["proactive"].asTrue()
+
+/**
+ * `proactive` 那个键的**宽容**读法（只认字面 `true`；`JsonNull` / 别的形状一律假）。
+ * 帧壳与载荷两处共用这一份口径，免得同一个键在两处各判一次、各自漂移。
+ */
+private fun JsonElement?.asTrue(): Boolean =
+    (this as? JsonPrimitive)?.content?.toBooleanStrictOrNull() == true
+
@Serializable
 private data class IndexData(val index: Int = 0)

@@ -756,6 +1022,10 @@ private data class ToolCallData(val id: String = "", val index: Int = 0, val del
 * `id` 在 provider 未给时**整个键省略**，`delta` 只在 `update` 且非空时出现。
 * 刻意**不复用** [ToolCallData]：那是 `tool_call.*` 的形状，真的有 `index`；这三帧没有，
 * 也没有 `streamId`（它们不属于某一次模型流）。
+ *
+ * [resultSummary] 只由 `.end` 携带（后端在新契约切片里只补了 `.end`）。它放在这份共用载荷上
+ * 是因为三帧形状同源、共用一个 DTO；`.start` / `.update` 即便被塞了这个键也**不读**
+ * （它们的领域事件上根本没有这个字段），所以契约没变宽——变宽的只是「多一个键不再算坏帧」。
 */
@Serializable
 private data class ToolExecutionData(
@@ -763,6 +1033,7 @@ private data class ToolExecutionData(
    val phase: String = "",
    val id: String? = null,
    val delta: String = "",
+    val resultSummary: String? = null,
 )

@Serializable
@@ -779,13 +1050,55 @@ private data class StreamEndData(
 )

@Serializable
-private data class SessionModeData(val sessionId: String = "", val mode: String = "")
+private data class SessionModeData(
+    val sessionId: String = "",
+    val mode: String = "",
+    /**
+     * `session_busy` / `session_idle` 的**可选**在途路数（忙时并行规范 §2.6）。
+     * `null` = 服务端没给这个键（v0.65 之前）——**不是 0**：0 是「确实没有在途路」，
+     * 缺席是「不知道」，两者绝不能互相顶替（拿缺席当 0 会把并行两路误报成空闲）。
+     */
+    val activeTurns: Int? = null,
+)

@Serializable
-private data class PendingData(val sessionId: String = "", val mode: String = "", val queueDepth: Int = 0)
+private data class PendingData(
+    val sessionId: String = "",
+    val mode: String = "",
+    val queueDepth: Int = 0,
+    /** 见 [WsEvent.SessionBusy.activeTurns]（`pending_ack` / `pending_drain` 各带一份）。 */
+    val activeTurns: Int? = null,
+    /** 入队原因码（规范 §2.6，目前只有 `"parallel_limit"`）；缺席 = `null`，绝不伪造。 */
+    val reason: String? = null,
+)

@Serializable
-private data class InterruptedData(val sessionId: String = "", val mode: String = "", val dropped: Int = 0)
+private data class InterruptedData(
+    val sessionId: String = "",
+    val mode: String = "",
+    val dropped: Int = 0,
+    val activeTurns: Int? = null,
+    val cancelledTurns: Int? = null,
+)
+
+/**
+ * `turn_begin` 载荷（忙时并行规范 §2.4）：`{kind, messageIds, leg, activeTurns}`。
+ *
+ * `sessionId` 在规范里**不出现在载荷中**（只在帧壳）；这里仍留一个可选键并让它优先——与
+ * [WsEvent.resolveSessionId] 对其它帧的既有口径一致（帧壳缺席时服务端若给了，用它比丢掉好）。
+ */
+@Serializable
+private data class TurnBeginData(
+    val sessionId: String = "",
+    val kind: String = "",
+    val messageIds: List<String> = emptyList(),
+    val leg: Int = 0,
+    val activeTurns: Int = 0,
+)
+
+/** `steer_ack` 载荷（v0.57 一字未变）：`{messageId, atStep}`；`sessionId` 由帧壳给。 */
+@Serializable
+private data class SteerAckData(val sessionId: String = "", val messageId: String = "", val atStep: Int = 0)

 /**
 * `pending_full` 载荷：`{sessionId, mode, max, clientMsgId?, messageId?}`。前三个键来自加入
@@ -812,8 +1125,24 @@ private data class ChatDuplicateData(
@Serializable
 private data class SessionReadData(val readAt: Long = 0L)

+/**
+ * `message_persisted` / `channel_persisted` 载荷：`{message:{…}}`。
+ *
+ * [proactive] 是「这句话是她主动说的」（见 [WsEvent.MessagePersisted]）。它此前**不在**这里，
+ * 于是被 `ignoreUnknownKeys = true` 静静吃掉——这正是 W53N 要修的那一条：判据键读不回来，
+ * 「她主动说的话」在客户端就只剩 `proactive_message` 那一条路可见。
+ *
+ * ⚠️ 声明成 [JsonElement] 而不是 `Boolean` 是**修一类能把整帧弄没的解码缺陷**（同
+ * [ProactiveData.timestamp] 那条教训）：契约没说这个键的类型，而线上只要给的是 `"true"` 这种
+ * 字符串形状，`Boolean` 解码就会抛、被 `parse` 的 `runCatching` 吞成 `null` ⇒ **整帧消失**，
+ * 连普通消息的落库广播都跟着受影响。收成元素之后按字面量读（见 [asTrue]），一个判据键从此
+ * 不可能让一整类帧消失。
+ */
@Serializable
-private data class PersistedData(val message: HistoryMessageDto? = null)
+private data class PersistedData(
+    val message: HistoryMessageDto? = null,
+    val proactive: JsonElement? = null,
+)

 /**
 * `message_deleted` 载荷（§3.8）：`{id}`。缺键 / 空串解成空 `id`，上层据此整帧跳过
@@ -830,14 +1159,34 @@ private data class TracePushData(val spans: List<AdminTraceSpanDto> = emptyList(
@Serializable
 private data class LogPushData(val entries: List<AdminLogEntryDto> = emptyList())

+/**
+ * `voice_output` 载荷（契约 v0.96 §3.15）：`{audio, format, text, reply, sessionId, deviceId?, provider?}`。
+ *
+ * `sessionId` 在这里**不是可选的**（契约「帧壳没有 sessionId（在 data 里）」），但解成缺省空串
+ * 并交给 [WsEvent.resolveSessionId]：坏帧（真没给）时宁可退化成「无法判定」（放行、由消费方
+ * 兜底），也不把整帧按坏帧丢掉——丢了就是「她回了语音但屏幕上什么都没有」。
+ */
@Serializable
 private data class VoiceOutputData(
    val audio: String? = null,
    val format: String? = null,
    val text: String? = null,
    val reply: String? = null,
+    val sessionId: String = "",
+    val deviceId: String? = null,
+    val provider: String? = null,
 )

+/**
+ * `proactive_message` 载荷（v0.72；字段名对着服务端 `gateway.proactivePayload`）。
+ *
+ * [timestamp] 声明成 [JsonElement] 而不是 `Long` 是**修一个把整帧弄没的解码缺陷**：
+ * 服务端那是 Go `time.Time`，线上是 RFC3339 **字符串**，而本端此前按 `Long?` 解 ⇒ 解码抛异常、
+ * 被 `parse` 的 `runCatching` 吞成 `null`，帧**在成形之前就没了**（`onEvent` 连 `else` 都到不了）。
+ * 收成元素之后按字面量取（数字形状也照样读出它），一个只作诊断的键从此不可能让整帧消失。
+ *
+ * [id] / [createdAt] 是落库行的权威 id 与时间戳，落库失败时**一起缺席**。
+ */
@Serializable
 private data class ProactiveData(
    val platform: String? = null,
@@ -846,8 +1195,10 @@ private data class ProactiveData(
    val content: String = "",
    val contentType: String? = null,
    val sender: String? = null,
-    val timestamp: Long? = null,
+    val timestamp: JsonElement? = null,
    val messageId: String? = null,
+    val id: String? = null,
+    val createdAt: Long? = null,
 )

 /**
@@ -1,6 +1,7 @@
 package top.yeij.cyrene.data.ws

 import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonObject
 import kotlinx.serialization.json.put

@@ -32,7 +33,7 @@ sealed interface WsOutbound {
        data()?.let { put("data", it) }
    }.toString()

-    /** `chat`：`{sessionId?, text, image?, deviceId?, clientMsgId?}`；text+image 至少一项。 */
+    /** `chat`：`{sessionId?, text, image?, deviceId?, clientMsgId?, parallel?}`；text+image 至少一项。 */
    data class Chat(
        val text: String,
        val sessionId: String? = null,
@@ -43,6 +44,17 @@ sealed interface WsOutbound {
         * 重复到达服务端回下行帧 `chat_duplicate`、**不落库、不起回合**。省略 = 老行为逐字不变。
         */
        val clientMsgId: String? = null,
+        /**
+         * **请求把本条作为独立一路处理**（忙时并行规范 §2.2，**纯增量**）。
+         *
+         * `null`（默认）= **整键省略**：行为与加入该字段之前**逐字相同**（忙时落回排队 + 回合内 steer）。
+         * 用户把「她忙时发消息」那栏选成「并行」**且会话正忙**时才给 `true`（判据是纯函数
+         * `parallelForSend`；另外两档与空闲时都不带这个键——线上取值由 `parallelWireValue` 翻）。
+         *
+         * 服务端**照准也不报错**（额度满 ⇒ 落回排队并回 `pending_ack{reason:"parallel_limit"}`；
+         * 已被在飞路 steer 吃进 ⇒ 回 `steer_ack`），所以这个字段永远不该引来一个错误帧。
+         */
+        val parallel: Boolean? = null,
        override val reqId: String? = null,
    ) : WsOutbound {
        override val type: String get() = "chat"
@@ -53,10 +65,13 @@ sealed interface WsOutbound {
            image?.let { put("image", it) }
            deviceId?.let { put("deviceId", it) }
            clientMsgId?.let { put("clientMsgId", it) }
+            // 布尔字面量走 JsonPrimitive：`put(key, Boolean)` 的重载在不同 kotlinx 版本里形态不一，
+            // 显式构造不会有歧义，也保证 `null` 时**整键省略**（与后端 `omitempty` 同义）。
+            parallel?.let { put("parallel", JsonPrimitive(it)) }
        }
    }

-    /** `interrupt`：`{sessionId, scope?}`。命中空闲会话为 no-op。 */
+    /** `interrupt`：`{sessionId, scope?, turnId?}`。命中空闲会话为 no-op。 */
    data class Interrupt(
        val sessionId: String,
        /**
@@ -67,6 +82,18 @@ sealed interface WsOutbound {
         * 不做取值校验、不静默回退成默认（服务端的开放取值域由服务端裁决）。
         */
        val scope: String? = null,
+        /**
+         * 只取消**这一路**（忙时并行规范 §2.3，**纯增量**）。
+         *
+         * 含义按 [scope] 分（规范的表）：`"current"` + 给了 `turnId` ⇒ **只停该路**，其余路与 pending
+         * 不受影响；`"current"` + 省略 ⇒ 取消**全部在途路**、保留 pending（现状语义的自然推广）；
+         * 省略 / `""` / `"all"` ⇒ 忽略本字段（取消全部 + 清 pending）。
+         *
+         * `null` = **整键省略** ⇒ 与加入该字段之前**逐字节相同**。本端今天同样一个字节都不发它：
+         * 唯一的调用点（`ChatViewModel` 的「她正忙时按发送」偏好）走的正是「取消全部在途路」那一档，
+         * 不需要按路精确停（规范未决问题 12 的建议默认：默认目标 = 全部在途路）。
+         */
+        val turnId: String? = null,
        override val reqId: String? = null,
    ) : WsOutbound {
        override val type: String get() = "interrupt"
@@ -74,15 +101,30 @@ sealed interface WsOutbound {
        override fun data(): JsonElement = buildJsonObject {
            put("sessionId", sessionId)
            scope?.let { put("scope", it) }
+            turnId?.let { put("turnId", it) }
        }
    }

-    /** `voice_input`：`{audio?, format?, text?, sessionId?}`。 */
+    /**
+     * `voice_input`：`{audio?, format?, text?, sessionId?, deviceId?, clientMsgId?}`（契约 v0.96 §3.15）。
+     *
+     * 五个键里 [audio] / [format] 是我们**总要给**的（一段 WAV 的 base64 + `"wav"`，见
+     * `domain.chat.VoiceClip`）；[text] 只有本端**自己做过转写**时才给（给了服务端就跳过 STT），
+     * 本端不做本地转写 ⇒ 恒省略。
+     *
+     * [clientMsgId] 与 `chat` 帧**同形同语义**：同一个非空值服务端只承认第一条，重复到达回
+     * `chat_duplicate`、不再落库不再起回合。所以「这一段没发出去、用户点重发」必须**复用**
+     * 同一个键（见 `domain.chat.voiceClientMsgIdFor`），换新键就是让服务端把同一句话再答一遍。
+     *
+     * [deviceId] 的取值与 `chat` 帧同一份（`ChatViewModel.DEVICE_ID`）：服务端据此标记来源。
+     */
    data class VoiceInput(
        val audio: String? = null,
        val format: String? = null,
        val text: String? = null,
        val sessionId: String? = null,
+        val deviceId: String? = null,
+        val clientMsgId: String? = null,
        override val reqId: String? = null,
    ) : WsOutbound {
        override val type: String get() = "voice_input"
@@ -92,6 +134,8 @@ sealed interface WsOutbound {
            format?.let { put("format", it) }
            text?.let { put("text", it) }
            sessionId?.let { put("sessionId", it) }
+            deviceId?.let { put("deviceId", it) }
+            clientMsgId?.let { put("clientMsgId", it) }
        }
    }

@@ -20,6 +20,16 @@ enum class WsState {
    /** 连接断开，正在按退避策略等待重连。 */
    Reconnecting,

-    /** 不可恢复（握手 401 / 缺少 token 或地址），不会自动重连。 */
+    /**
+     * 不可恢复（握手 401 / 缺少 token 或地址），不会自动重连。
+     *
+     * ⚠️ **握手拿到「非 101 且非 401」的响应不属于这一档**：那种失败（例如中间设备/代理直接回
+     * `503`、`502`，或握手被打断）在 [ChatSocket.isAuthFailure] 里判不出鉴权失败 ⇒ 走
+     * [Reconnecting] 按退避**继续重连**。判据只认 `response.code == 401`（拿不到 response 时再退化
+     * 成消息文本里含 `401`），所以「代理回 503」时 socket 的真值是 [Reconnecting]，不是 [Offline]。
+     * 这一条在发送阶梯上很要命：它决定了「WS 未就绪」时**要不要**去试一次 REST
+     * （[top.yeij.cyrene.ui.chat.sendRouteFor] 只在真 [Offline] 上判进队列、不试；W41 起如此，
+     * W45 起同一条判据仍然成立，只是那一步从「探一次健康端点」换成了「直接试 REST」）。
+     */
    Offline,
 }
@@ -89,6 +89,3 @@ fun canReceiveObservabilityFrames(role: AdminRole): Boolean =
 * 而不是散在各处 `if` 里靠人记。
 */
 fun canReadObservabilityLogHistory(role: AdminRole): Boolean = canAccess(role, AdminPage.Overview)
-
-/** 当前角色可用的页，顺序与 [AdminPage] 声明一致。 */
-fun availablePages(role: AdminRole): List<AdminPage> = AdminPage.entries.filter { canAccess(role, it) }
@@ -130,7 +130,8 @@ data class ConclusionParagraph(val parts: List<ContentPart>)
 *
 * 该字段承载的是**与聊天消息同一套 Web 端 markup**（真实样本里有连写的空 `<p></p>`、
 * `<action>` 等），所以这里**不新增任何 markup 规则**，一律委托 [parse]：
- * 一个 `<p>` 块 = 一段，旁白/动作块依聊天页的归属规则挂在该段内，畸形标签按普通文本回落。
+ * 一个 `<p>` 块 = 一段，旁白/动作块依聊天页的归属规则挂在该段内，畸形标签由 [parse] 兜底
+ * （落单的段落标签剥掉，其余按普通文本回落）。
 * 空段（`<p></p>` 连写产生的空白）不产出模型项——否则界面上会出现成片空行。
 * 段内片段顺序取**渲染顺序**：`head` → 正文 → `tail`（与聊天页气泡上/下方旁白的排布一致）。
 * `null` / 纯空白输入返回空列表。
@@ -29,9 +29,16 @@ object ChatImageBudget {
    /** `data:` URI 前缀（`data:image/jpeg;base64,`）的字符余量，与服务端同一取值。 */
    const val PREFIX_ALLOWANCE_CHARS = 64

-    /** 服务端 `image` 字符串长度上限（= base64 膨胀 4/3 + 前缀余量）。 */
-    const val SERVER_MAX_CHARS =
-        ((SERVER_MAX_DECODED_BYTES + 2) / 3) * 4 + PREFIX_ALLOWANCE_CHARS
+    /** [byteCount] 字节 base64 编码后的字符数（每 3 字节 → 4 字符，末组补满）。 */
+    fun base64Chars(byteCount: Int): Int = ((byteCount + 2) / 3) * 4
+
+    /**
+     * 服务端 `image` 字符串长度上限（= [base64Chars] 的 4/3 膨胀 + 前缀余量）。
+     *
+     * 刻意复用 [base64Chars] 而不是把公式再内联写一遍：公式只留一处。代价是它只能是 `val`
+     * ——`const val` 不允许调用函数；取值在对象初始化时算出，与内联写法一致。
+     */
+    val SERVER_MAX_CHARS: Int = base64Chars(SERVER_MAX_DECODED_BYTES) + PREFIX_ALLOWANCE_CHARS

    /** 本端目标：重编码后的**字节**上限，远低于服务端硬顶（见类注释）。 */
    const val MAX_DECODED_BYTES = 1 * 1024 * 1024
@@ -42,9 +49,6 @@ object ChatImageBudget {
     */
    const val MAX_DIMENSION_PX = 1280

-    /** [byteCount] 字节 base64 编码后的字符数（每 3 字节 → 4 字符，末组补满）。 */
-    fun base64Chars(byteCount: Int): Int = ((byteCount + 2) / 3) * 4
-
    /** 字符串长度是否在服务端上限内（入口层同一判据：`<=` 才算通过）。 */
    fun withinServerLimit(dataUriChars: Int): Boolean = dataUriChars <= SERVER_MAX_CHARS

@@ -4,7 +4,7 @@ import java.io.ByteArrayOutputStream
 import java.io.InputStream

 /**
- * 一份**已选好、还没发出去**的待发附件（与 `ChatUiState.draftImage` 平行的概念）。
+ * 一份**已选好、还没发出去**的待发附件（与 `ChatUiState.draftImages` 平行的概念）。
 *
 * 与 [DocumentFile] 的分工：[DocumentFile] 是「发送那一刻的字节」——上传需要它；
 * 本类型是「还没发送的引用」——输入栏上方的芯片要显示它，而**绝不能**把最多 5×20 MiB
@@ -49,6 +49,33 @@ enum class DocumentRejection {
    TooManyAttachments,
 }

+/**
+ * 「**从别的 App 分享进来**的长正文」该怎么送（纯函数，见 [DocumentDelivery.planSharedText]）。
+ *
+ * 只用于分享那条路。用户自己在输入框里打的字**永远**是 [Inline]——「不做长正文自动转文件」是
+ * 已拍板的产品定案（`devdocs/05` 的「三条待拍板项的定案」第 3 条），本枚举不改变它一个字。
+ */
+enum class SharedTextPlan {
+
+    /** 正文照正文发（没到 [DocumentDelivery.TEXT_AS_DOCUMENT_RUNE_LIMIT]，或附件位不够，见下一档）。 */
+    Inline,
+
+    /**
+     * 正文落成一份 `.txt` 附件：上传 `POST /api/v1/documents` 之后随 `chat.documents` 发，
+     * **正文那一栏留空**。
+     */
+    AsDocument,
+
+    /**
+     * 正文长到该走文件，但**附件位已经被分享进来的文件占满** ⇒ 只能按正文发。
+     *
+     * 调用方**必须**如实告知（分享那条路从不静默改形态）。取这一档而不是「把 .txt 塞进去、
+     * 挤掉一个用户真的分享进来的文件」：那些文件是用户**明确**要发的东西，正文换形态是**为了
+     * 少占篇幅**的便利——为了便利牺牲用户指名要发的内容，是不划算的交换。
+     */
+    InlineAttachmentsFull,
+}
+
 /**
 * 「该不该走文件」的判定与 `chat.documents` 载荷构造（纯函数，VM 与测试共用）。
 *
@@ -160,6 +187,29 @@ object DocumentDelivery {
    fun textAsFile(text: String, fileName: String = TEXT_DOCUMENT_FILE_NAME): DocumentFile =
        DocumentFile(fileName = fileName, bytes = text.toByteArray(Charsets.UTF_8))

+    /**
+     * **分享路径**专用：这一轮的正文该怎么送（[SharedTextPlan]）。
+     *
+     * 为什么分享这条路要转、而输入框那条不转（两件事**不是**同一件）：
+     * 分享进来的长正文往往是**别的平台把卡片/文章摊平之后的一整段字**（主人原话：「有的时候部分平台
+     * 发送到非官方支持卡片的平台会将卡片内容转化为比较长的字符」）——它不是用户抱着键盘敲出来的
+     * 一句话，而是一份**搬运进来的内容**，以文本消息发出去会把会话拉得很长。用户自己打的字则相反：
+     * 那是他要说的话，悄悄换成附件只会让它在历史里搜不到、气泡变成一枚芯片（`devdocs/05` 的定案）。
+     *
+     * 判据两步，都只有纯值输入：
+     * 1. 正文没到 [textNeedsFile] ⇒ [SharedTextPlan.Inline]；
+     * 2. 到了、但附件位已经满（[MAX_ATTACHMENTS_PER_TURN]）⇒ [SharedTextPlan.InlineAttachmentsFull]
+     *    （**如实告知**由调用方负责）；否则 ⇒ [SharedTextPlan.AsDocument]。
+     *
+     * @param text 分享进来的正文（调用方已 trim）。
+     * @param attachmentCount 这一轮**已经**要挂的附件份数（分享进来的文件，不含 .txt 本身）。
+     */
+    fun planSharedText(text: String, attachmentCount: Int): SharedTextPlan = when {
+        !textNeedsFile(text) -> SharedTextPlan.Inline
+        attachmentCount >= MAX_ATTACHMENTS_PER_TURN -> SharedTextPlan.InlineAttachmentsFull
+        else -> SharedTextPlan.AsDocument
+    }
+
    /**
     * 由**已上传**的服务端存储名构造 `chat.documents` 载荷。
     *
@@ -0,0 +1,113 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 「保留 path、替换 host」：把历史图片里**绑死在上传那一刻的 host 上**的绝对地址，换到当前 baseUrl。
+ *
+ * ## 它修的是什么（`devdocs/02` 的 `F6①` + 回执十三 §2）
+ * `POST /api/v1/upload` 的 `url` 由服务端按**请求时**的 `r.Host`（+ `X-Forwarded-Proto` / TLS）
+ * 拼成绝对地址，并且**原样落库**（读侧不重写）。于是换一个服务器地址（自部署换机器、`adb reverse`
+ * 换个端口、域名从 IP 换成域名）之后，旧消息里的图片地址指向的还是**当时那个 host**，本端也就取不回
+ * 那些图。
+ *
+ * 后端确认「读取侧三条路」里**只有主模型直收图**（`multimodal=true`）会真的去 GET 那串绝对 URL，
+ * 并明确认可本端自己做这一层：「你可以先在客户端做『保留 path、替换 host』」。本对象的形态就是
+ * 那句原话的逐字落地：**只换 host，不碰 path**。
+ *
+ * ## 保守到什么程度（不认识的一律原样返回）
+ * 只认这一种形态，其余**一个字符都不改**：
+ *
+ * ```
+ * http(s)://<任意 host[:port]>/api/v1/files/<name>
+ * ```
+ *
+ * 具体判据（全部满足才替换，否则原样返回）：
+ * - 以 `http://` 或 `https://` 开头（大小写不敏感）；**其它一切**都不是这一层的事——`data:` 内联图、
+ *   `content://` / `file://` 本地引用、相对路径、裸文件名，全都原样返回，不做任何猜测
+ *   （与 [ImageSource.of] 的同一条纪律：形态不认识的，交给它原来那条路）；
+ * - 路径**恰好**是 `/api/v1/files/` 再加**一段**名字：名字非空、不含 `/`、不含 `%`、不含 `?` / `#`，
+ *   也不是 `.` / `..`。多一段、带查询串或片段、带百分号编码的，都判为「不是我们认识的那个地址」
+ *   ——第三方 CDN 的图与别人签过名的 URL 因此一个都不会被改；
+ * - [baseUrl] 本身能解出 `scheme://authority`（空串、没有 host 的都解不出，于是原样返回）。
+ *
+ * 替换后用的是 **baseUrl 的 scheme + authority**（所以 `http` → `https`、端口变更都跟着走），
+ * **不用** baseUrl 里的路径：服务端自己拼这条地址时只取 `r.Host`，读侧 `GET /api/v1/files/{name}`
+ * 也挂在根路径上，所以部署形态本来就没有路径前缀这一说。
+ *
+ * ## 逆作用：指向不同数据时会 404，那是**诚实的失败**
+ * 如果两个 host **指向的不是同一份存储**（换的是另一台机器、数据没迁过去），替换之后取到的就是
+ * `404`。这仍然比现状好：不替换的话，那个地址**永远**取不回（而且是「连不上/超时」这种更含糊的
+ * 失败），替换之后至少是一个说得清的结果，而图片那条路本来就会把失败如实报出来（见
+ * [imageLoadFailureMessage]）。**绝不**因此退回「不替换」——那等于把「换地址后旧图还能看」这件事
+ * 彻底放弃。这条取舍是刻意的：宁可诚实地失败，也不要安静地永远失败。
+ *
+ * ## 不做的事
+ * 不改落库数据、不改上传、不碰 `documents`，也**不**在这一层做任何 IO：它只在渲染前过一遍字符串。
+ * 纯函数，可单测（`ImageHostRebaseTest`）。
+ */
+object ImageHostRebase {
+
+    /** 服务端上传产物的读侧路径（`api-client` §1 行 3：`GET /api/v1/files/{name}`）。 */
+    private const val FILES_PREFIX = "/api/v1/files/"
+
+    private const val HTTP_SCHEME = "http://"
+    private const val HTTPS_SCHEME = "https://"
+
+    /**
+     * 把 [raw] 里同源的图片地址换到 [baseUrl] 的 host 上；不认识的形态原样返回（判据见类型 KDoc）。
+     *
+     * 幂等：已经指向当前 host 的地址走完也逐字节不变。
+     *
+     * @param raw 历史消息里那份 `image` 字符串（或任何要交给渲染的图片地址）。
+     * @param baseUrl 当前服务器地址（`AuthManager.currentBaseUrl`）；空串 = 不替换。
+     */
+    fun apply(raw: String, baseUrl: String): String {
+        // 1. raw 必须是 http(s) 绝对地址，且能切出 authority 与 path。
+        val rest = raw.absoluteRest() ?: return raw
+        val slash = rest.indexOf('/')
+        if (slash <= 0) return raw
+        // 2. 路径必须是「恰好一段文件名的 /api/v1/files/…」。
+        if (!isSameOriginFilePath(rest.substring(slash))) return raw
+        // 3. baseUrl 必须能给出 scheme://authority。
+        val origin = originOf(baseUrl) ?: return raw
+        return origin + rest.substring(slash)
+    }
+
+    /**
+     * `http(s)://` 之后的部分（`<authority>/<path>`）；不是 http(s) 绝对地址就回 `null`。
+     *
+     * 大小写不敏感，但**原样保留**后面那段：本函数只判断、不重写。
+     */
+    private fun String.absoluteRest(): String? = when {
+        startsWith(HTTP_SCHEME, ignoreCase = true) -> substring(HTTP_SCHEME.length)
+        startsWith(HTTPS_SCHEME, ignoreCase = true) -> substring(HTTPS_SCHEME.length)
+        else -> null
+    }
+
+    /**
+     * `path` 是不是「恰好 `/api/v1/files/<一段名字>`」。
+     *
+     * 判据取最小容忍度，理由与 [ImageNames.fromServerUrl] 的同一条：这个字符串来自**别人给的**历史
+     * 数据，凡是看不懂的形态就不该被我们改写（改写它等于替用户的图片猜一个新地址）。
+     */
+    private fun isSameOriginFilePath(path: String): Boolean {
+        if (!path.startsWith(FILES_PREFIX)) return false
+        val name = path.removePrefix(FILES_PREFIX)
+        if (name.isEmpty() || name == "." || name == "..") return false
+        if (name.any { it == '/' || it == '\\' || it == '%' || it == '?' || it == '#' || it == '\u0000' }) {
+            return false
+        }
+        return name.isNotBlank()
+    }
+
+    /** `scheme://authority`；解不出来回 `null`（空串 / 没有 host / 不是 http(s) 都是解不出来）。 */
+    private fun originOf(baseUrl: String): String? {
+        val rest = baseUrl.absoluteRest() ?: return null
+        // authority 在第一个 `/`、`?`、`#` 之前结束（正常 baseUrl 只有尾部那个 `/`；
+        // 多出来的那两样不该被当成 host 的一部分）。
+        val end = rest.indexOfFirst { it == '/' || it == '?' || it == '#' }.let { if (it < 0) rest.length else it }
+        val authority = rest.substring(0, end)
+        if (authority.isBlank()) return null
+        val scheme = baseUrl.take(baseUrl.length - rest.length)
+        return scheme + authority
+    }
+}
@@ -0,0 +1,76 @@
+package top.yeij.cyrene.domain.chat
+
+import top.yeij.cyrene.core.prefs.InterruptMode
+
+/**
+ * 「她忙时发消息」这一档偏好在上行的**两个声明**（纯函数，VM 与测试共用）：
+ * 协同项 A2 的 `interrupt.scope`（[interruptScopeForSend]）与忙时并行规范 §2.2 的
+ * `chat.parallel`（[parallelForSend] / [parallelWireValue]）。
+ *
+ * 文件名沿用了先有的那个（`InterruptScope`）：并行那一半接上来时，两者是**同一个判据的两个方向**
+ * （打断 vs 不打断），放在同一处比拆成两个文件更容易看出它们互斥。
+ */
+
+/**
+ * 发这条消息**之前**要不要先发一条 `interrupt`：返回要发的作用域，`null` = 一个字节都不发
+ * （纯函数，VM 与测试共用）。
+ *
+ * ## 四条判据（协同 A2 的客户端半边，契约 v0.56 §3.1）
+ *
+ * 1. [InterruptMode.AppendQueue]（**默认档**）⇒ 恒为 `null`，线上请求与接入本函数之前**逐字节相同**。
+ *    这是最重要的一条：默认档不许有任何行为变化。
+ * 2. [InterruptMode.Interrupt]（`wireScope = "current"`）**且会话正忙** ⇒ `"current"`：
+ *    只取消在跑回合、**保留待处理队列**（队列里的消息按编排器正常续跑，一条都不丢）。
+ * 3. [InterruptMode.Interrupt] 但会话**空闲** ⇒ `null`：命中空闲会话在服务端是 no-op，白发一条帧
+ *    只是多一次往返，还会在 logcat 里制造「这里打断过」的假象。
+ * 4. [InterruptMode.Parallel] ⇒ **恒为 `null`**（它的 `wireScope` 就是 `null`）：并行与打断互斥，
+ *    并行档先打断就恰好砍掉它要并行的那一路。这一条不是「这一档没得发」，而是**结构性保证**——
+ *    谓词只读 `wireScope`，并行档不可能发出打断帧。
+ *
+ * 判据里**没有**「队列有多深」这一项，见下。
+ *
+ * ## 「正忙」由谁判
+ * 只认**服务端给的** `session_busy{mode}`（调用方传 `ChatUiState.busyMode != null`）。
+ * **不用 `queueDepth`**：队列深度非零不等于有回合在跑（`pending_ack` / `pending_drain` 这类帧也会动它），
+ * 拿它当判据就会在空闲会话上乱发打断帧。
+ *
+ * @param busy 这条消息要发出去的那一刻，该会话是否有回合在跑。
+ */
+fun interruptScopeForSend(mode: InterruptMode, busy: Boolean): String? =
+    if (busy) mode.wireScope else null
+
+/**
+ * 发这条消息时要不要声明 `parallel:true`（忙时并行规范 §2.2，[interruptScopeForSend] 的兄弟）。
+ *
+ * ## 三条判据
+ *
+ * 1. [InterruptMode.Parallel] **且会话正忙** ⇒ `true`：不打断在跑的那一路，让本条**另起一路**
+ *    同时处理（服务端额度满时不报错，这一条落回排队）。
+ * 2. 另外两档 ⇒ **恒为 `false`**：`parallel` 是纯增量键，省略它线上请求与接入本判据之前**逐字节相同**
+ *    （[InterruptMode.AppendQueue] 与 [InterruptMode.Interrupt] 的 `wireParallel` 都是 `false`）。
+ * 3. 并行的同时**绝不打断**：两件事是一对互斥语义（打断 = 先砍掉她正在说的这一句，并行 = 不打断、
+ *    另起一路），所以 [InterruptMode.Parallel] 的 `wireScope` 是 `null` ⇒ 它在
+ *    [interruptScopeForSend] 里恒为「不发」。反过来，另外两档的 `wireParallel` 是 `false` ⇒
+ *    它们永远不带 `parallel` 键。「绝不既打断又并行」不是约定，是这两处属性取值本身
+ *    （`ParallelForSendTest` 把它钉成穷举断言）。
+ *
+ * ## 为什么空闲时不声明
+ * 规范 §2.2 只说 `parallel:true` 是「**请求**把本条作为独立一路处理」，**没写**空闲时要不要照发。
+ * 空闲时这一条**本来就是它自己的回合**，声明并行与不声明在服务端是同一件事；而多带一个键就多一处
+ * 线上形状差异。于是本端取**与 [interruptScopeForSend] 同一个判据**（忙才声明）——最小惊讶：
+ * 空闲时三档**逐字节**完全相同，切档不会改变一条普通发送的任何字节。
+ *
+ * @param busy 这条消息要发出去的那一刻，该会话是否有回合在跑（与 [interruptScopeForSend] 同一个来源）。
+ */
+fun parallelForSend(mode: InterruptMode, busy: Boolean): Boolean = busy && mode.wireParallel
+
+/**
+ * 把 [parallelForSend] 的结论翻成帧 / DTO 那个可选字段的取值：`false` ⇒ `null`（**整键省略**）。
+ *
+ * 为什么必须翻一道：`WsOutbound.Chat.parallel` 与 `ChatRequest.parallel` 的默认值都是 `null`，
+ * 而「省略」与「显式 `false`」在服务端**不是一回事**（前者 = 未声明，后者 = 明确不要并行）；
+ * kotlinx 的 `encodeDefaults = false` 只省略「等于默认值」的字段 ⇒ 把 `false` 直接传下去，会在
+ * **每一条**请求上多出一个 `"parallel":false` 键，默认档就不再逐字节不变了。两个发送层共用这一个
+ * 转换点，免得哪天有人在其中一处「顺手」把布尔原样传下去。
+ */
+fun parallelWireValue(declare: Boolean): Boolean? = if (declare) true else null
@@ -40,12 +40,21 @@ data class EditableMessage(
 )

 /**
- * 已知标签的容差，与 [parse] 逐字对齐（只认解析器真正认识的那几个标签）：
- * `<p>`（可带属性）/ `</p>` / `<action>` / `</action>` / `<narration>` / `</narration>`。
+ * 已知标签的容差，与 [parse] 逐字对齐（只认解析器会**改掉**的那几个标签——行内标签不在其中，
+ * 见下）：`<p>`（可带属性）/ `</p>` / `<action>` / `</action>` / `<narration>` / `</narration>`。
 *
 * 绝不能「见到一个 `<` 就当标记」：用户打的 `1 < 2`、`<div>`、`<3`、`a<b` 都是普通文本，
 * 判成标记就会顺手把它们当标签吃掉——那才是真正的静默丢东西。大小写同样照解析器来：
 * `parse` 只认小写的 `<p>` / `<action>` / `<narration>`，所以 `<P>` 在这里也是普通文本。
+ *
+ * **行内标签（`<b>` / `<code>` …）故意不在**这份容差里：它们是渲染用的标记，但编辑框
+ * 编辑的是**源码本身**，而 `parts`（这一份的来源）是**逐字原文**——所以 `日落 <b>18:35</b>` 在
+ * 编辑框里连 `<b>` 一起显示、也一起保存，这里一个字符都不动它。
+ *
+ * **`<br>` 同理**（契约 v0.89 更正后它是**气泡分隔符**、不是行内标签）：只含 `<br>` 的消息在这份
+ * 容差里仍是纯文本 ⇒ 编辑框里逐字恒等（`<br>` 原样显示、原样保存）；只有原文**另有**已知标记时
+ * 才走剥标记那条路，那时 `<br>` 与 `<p>` / `</p>` 一样被换成它本来就在表示的**空行分隔**
+ * （保存后渲染结果不变，且弹层已经明说标记会被替换）。
 */
 private val KNOWN_TAG_RE = Regex(
    "<p(\\s[^>]*)?>|</p>|<\\s*(action|narration)\\s*>|</\\s*(action|narration)\\s*>",
@@ -0,0 +1,331 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 忙时并行回合（多路）的客户端模型：**分桶、六态、灰态收口**三件纯逻辑。
+ *
+ * 规格来源：`Cyrene_v2/DevDocs/_specs/忙时并行-规范草案.md`（§1 行为规范 / §2 接口规范 / §4 主人裁决）。
+ * 本文件**只有纯数据与纯函数**：不碰协程、不碰 Android、不碰网络，所以三层逻辑都能直接单测。
+ * 消费方是 `ChatViewModel`（接线）与 `ChatScreen` / `MessageBubble`（渲染）。
+ *
+ * ## 为什么要分桶
+ * 两路并行时，同一 `sessionId` 下**两个不同 `turnId`** 的 `message.delta` / `thinking.delta` /
+ * `tool_call.*` 会**交错到达**。若照老代码那样「一律累加到当前那一个流式气泡」，两条回复会被糊成
+ * 一条（规范 §1.4 明写这一点）。所以落桶键是 `(sessionId, turnId)` 两级（规范 §1.7 第 1 条）。
+ *
+ * ## 字段缺失必须能降级（本文件的头号纪律）
+ * `turnId` 在真后端 v0.36 起就打在**每个结构化流帧**的帧壳上，但本文件**不假设**它一定在：
+ * 帧壳没给（`null` / 空白）时，帧落回**本会话最近见过的那条路**（[turnBucketOf] 的 `sessionTurnId`），
+ * 一条都还没见过时落进**匿名桶**（`turnId == ""`）。于是「所有帧都不带 `turnId`」时全部帧落进
+ * **同一个桶**——也就是**今天那一个流式气泡**，行为逐字相同。
+ * 同理 `turn_begin` / `steer_ack` 不来时，六态里只会出现 ①②③⑤，灰态（④）根本不会进入。
+ * `kind` 不来时（老服务端）也只是**不挂并行路角标**——[isParallelLegKind] 认不出来就说不并行，
+ * 绝不拿 `leg` 去替它撑门面。
+ */
+
+/** 「路序号未知」：`steer_ack` 只给 `turnId`、不给 `leg`（规范 §2.5 的载荷只有 messageId / atStep）。 */
+const val UNKNOWN_LEG: Int = 0
+
+/**
+ * `turn_begin.kind` 里表示「忙时另起的一路」的取值（规范 §2.4）。
+ *
+ * 另一个取值 `"turn"` 表示「新回合 / 续跑」——也就是**普通串行回合**，它不在这里单列常量：
+ * 本端只认得出 `"parallel"` 这一个，其余一切取值（含 `"turn"`）都按「不是并行」处理
+ * （见 [isParallelLegKind] 的 KDoc）。
+ */
+private const val PARALLEL_LEG_KIND = "parallel"
+
+/**
+ * 流式分桶键：`sessionId` → `turnId` 两级（规范 §1.4 / §1.7 第 1 条）。
+ *
+ * [turnId] 为空串 = **匿名桶**：帧壳没给 `turnId`、且本会话还没见过任何 `turnId` 时的落点。
+ * 它是「老的单路行为」在分桶模型里的等价物——所有匿名帧落在这同一个桶里，与今天逐字相同。
+ */
+data class TurnBucket(val sessionId: String, val turnId: String) {
+
+    /** 是否匿名桶（帧壳没给 `turnId`）。 */
+    val isAnonymous: Boolean get() = turnId.isEmpty()
+
+    override fun toString(): String = if (isAnonymous) "$sessionId/*" else "$sessionId/$turnId"
+}
+
+/**
+ * 帧该落哪个桶（纯函数）。
+ *
+ * 优先级：**帧壳给的 `turnId`** > **本会话最近见过的 `turnId`** > **匿名桶**。
+ *
+ * 第二条是「字段缺失 ⇒ 行为与今天逐字相同」那条硬要求的落地处：帧壳没给 `turnId` 时，帧跟着
+ * 本会话当前那一路走——老代码里它本来就会落进那**唯一**一个流式气泡。因此
+ * `turnBucketOf("web", null, null)` 恒等于匿名桶，全部帧都落在一处，与分桶之前完全一致。
+ *
+ * @param frameTurnId 帧壳上的 `turnId`（可能 `null` / 空白）。
+ * @param sessionTurnId 本会话最近一次见到的**非空** `turnId`（由调用方记住并喂进来）。
+ */
+fun turnBucketOf(sessionId: String, frameTurnId: String?, sessionTurnId: String?): TurnBucket =
+    TurnBucket(sessionId, frameTurnId.orNullIfBlank() ?: sessionTurnId.orNullIfBlank() ?: "")
+
+/**
+ * **收口帧**（`stream_end` / `turn.end` / 落库的助手行）该落哪个桶（纯函数）。
+ *
+ * 与 [turnBucketOf] 的区别只有一条、但很要紧：**收口帧不许新开桶**。
+ *
+ * 理由是实证的：老代码里 `stream_end` 无论带着哪个 `turnId`，都会把**唯一**那个流式气泡收口
+ * （`active = false`）。若照 [turnBucketOf] 给一个认不出来的 `turnId` 开新桶，那个新桶收口、
+ * **真正在跑的那个桶永远收不了口**——光标一直转、`stream_end` 这一帧等于白给。
+ * 所以这里的顺序是：
+ *
+ * 1. 帧壳的 `turnId` 认得出来（在 [existing] 里）⇒ 就是它；
+ * 2. 否则本会话最近见过的 `turnId` 认得出来 ⇒ 用它；
+ * 3. 否则 [existing] 里还有桶 ⇒ 用**最近更新的那一个**（单路场景下它就是正确的那一个）；
+ * 4. 一个桶都没有 ⇒ 匿名桶（也不新开，调用方据此可以对「没有在跑的路」整帧跳过）。
+ *
+ * @param existing 当前**已经存在**的桶的 `turnId` 列表，**顺序即更新时间**（最后的最近）。
+ */
+fun closingBucketOf(
+    sessionId: String,
+    frameTurnId: String?,
+    sessionTurnId: String?,
+    existing: List<String>,
+): TurnBucket {
+    val frame = frameTurnId.orNullIfBlank()
+    val session = sessionTurnId.orNullIfBlank()
+    val target = when {
+        frame != null && existing.contains(frame) -> frame
+        session != null && existing.contains(session) -> session
+        existing.isEmpty() -> ""
+        else -> existing.last()
+    }
+    return TurnBucket(sessionId, target)
+}
+
+/**
+ * 一条消息在「忙时并行」语义下可能处的**六态**（规范 §1.1）。
+ *
+ * 名字逐字对齐规范表格里的态名，避免两套叫法：
+ * - [Sending] ① 发送中（本地乐观气泡）；
+ * - [Sent] ② 已送达（正常气泡，还没进任何一路）；
+ * - [Queued] ③ 排队中（气泡角标「排队中」**浅灰**——规范 §1.3 明写：**`queued` 不是灰态**，
+ *   `pending_ack` 不许渲染成灰态，`queued` 只靠 `turn_begin` **直接换态**）；
+ * - [Answering] ④ 已受理·回答中（**灰态「已读、未答」**）；
+ * - [Answered] ⑤ 已答（终态）；
+ * - [Rejected] ⑥ 被拒（终态，用户可手动重发）。
+ */
+enum class TurnPhase { Sending, Sent, Queued, Answering, Answered, Rejected }
+
+/**
+ * 六态判定（纯函数，规范 §1.1 的表格逐行对照）。
+ *
+ * 判据只有四个，且**顺序即证据强度**（与 `queueFullOutcome` 同一条纪律）：
+ * 1. [rejected] = 收到过明确拒绝（定向 `error{chat_busy}` / 广播 `pending_full`）⇒ ⑥。
+ *    它压过一切：这条消息**根本没进去**，不许再拿「有没有被接手」去描述它；
+ * 2. [binding] 非空且**未收口** ⇒ ④ 灰态（`turn_begin` 的 `messageIds` 含它，或 `steer_ack` 绑上它）；
+ * 3. [binding] 非空且**已收口** ⇒ ⑤；
+ * 4. [binding] 为空且是本地乐观气泡 ⇒ [queued] ? ③ : ①；
+ * 5. [binding] 为空且已落库 ⇒ [queued] ? ③ : ②。
+ *
+ * 第 4/5 条里 [queued] 与非 [queued] 分开，是因为服务端的 `pending_ack` **不带消息身份**
+ * （规范 §1.1 ③ 的进入条件明写「现状帧，形状不变」）——客户端只能按「这条我发出去之后收到了入队
+ * 回执」来认，认不出来时为 [Sent] / [Sending]（今天的样子），**绝不瞎猜成排队**。
+ *
+ * @param local 这条是不是**本地乐观气泡**（还没落库）。
+ * @param binding 这条消息被哪一路接手（`null` = 没被任何一路接手）。
+ * @param queued 收到过「它进队列」的回执（`pending_ack` / REST `202 queued`）。
+ * @param rejected 收到过明确的拒绝。
+ */
+fun turnPhaseOf(
+    local: Boolean,
+    binding: TurnBinding?,
+    queued: Boolean,
+    rejected: Boolean,
+): TurnPhase = when {
+    rejected -> TurnPhase.Rejected
+    binding != null && !binding.closed -> TurnPhase.Answering
+    binding != null -> TurnPhase.Answered
+    local -> if (queued) TurnPhase.Queued else TurnPhase.Sending
+    queued -> TurnPhase.Queued
+    else -> TurnPhase.Sent
+}
+
+/**
+ * 灰态（④）**收口判据**（纯函数，规范 §1.2）。
+ *
+ * 规范给的是**唯一口径**：收口事件 = 该消息所属回合的 `turn.end`，用 `turn.end` **帧壳的 `turnId`**
+ * 与这条消息绑定的 `turnId` 比对，**相等即收口**；此外该 `turnId` 的助手 `message_persisted`
+ * 同样收口（两者顺序不定，任一到即收口）。
+ *
+ * 所以这里就一件事：两个 id **都非空且相等**。任一为空 ⇒ `false`（**不许**用「都为空所以相等」
+ * 收口——那会让「没有 turnId 的老客户端 / 老服务端」上的消息被随便一帧误收口）。
+ *
+ * @param boundTurnId 这条消息绑定的 `turnId`。
+ * @param closingTurnId 收口帧带来的 `turnId`（`turn.end` 帧壳 / 助手落库行的 `turnId`）。
+ */
+fun closesAnswering(boundTurnId: String?, closingTurnId: String?): Boolean {
+    val bound = boundTurnId.orNullIfBlank() ?: return false
+    val closing = closingTurnId.orNullIfBlank() ?: return false
+    return bound == closing
+}
+
+/**
+ * 消息 ↔ 回合的绑定：**一路**（规范 §2.4 的 `turn_begin` 说的是「编排器每次启动一路发一次」）。
+ *
+ * 它由两件事建立：`turn_begin`（一次给全 `messageIds` / `leg` / `activeTurns` / `kind`）与 `steer_ack`
+ * （只补「某条消息被哪一路吃进」，没有 `leg`）。
+ * 只在 `turnId` **非空**时才会被建立——`turnId` 是这张表的键，也是收口的唯一凭据（见
+ * [closesAnswering]）；没有它建出来的绑定永远收不了口，那不是绑定，是一个永远灰着的气泡。
+ *
+ * ## [leg] 与 [parallel] 是两件事（这张表最容易被读错的一处）
+ * [leg] 只是**会话内第几条路**：服务端 `beginLegLocked` 对**每一条新路**都自增 `legSeq`，普通串行
+ * 回合照样占号——会话里第二条普通消息的 `leg` 就是 2。所以 `leg >= 2` **完全不等于**并行，拿它当
+ * 并行的证据会挂出并不存在的「并行路 N」。
+ * 真正说明「这一路是忙时另起的一路」的只有 `turn_begin.kind`，落到 [parallel]（见 [isParallelLegKind]）。
+ */
+data class TurnBinding(
+    /** 这一路的权威回合标识（与该路全部流帧的 `turnId` 同值）。 */
+    val turnId: String,
+    /** 该路的会话内序号（[UNKNOWN_LEG] = `steer_ack` 建的表，服务端没告诉序号）。 */
+    val leg: Int = UNKNOWN_LEG,
+    /** 归属这一路的**用户消息 id**（`turn_begin.messageIds` / `steer_ack.messageId`）。 */
+    val messageIds: List<String> = emptyList(),
+    /** 服务端最近一次报的该会话在途路数（`turn_begin.activeTurns`；0 = 没报过）。 */
+    val activeTurns: Int = 0,
+    /** 这一路是不是**真并行路**（服务端 `turn_begin.kind == "parallel"`，见 [isParallelLegKind]）。 */
+    val parallel: Boolean = false,
+    /** 该路是否已收口（`turn.end` / 同 `turnId` 的助手落库行）。 */
+    val closed: Boolean = false,
+)
+
+/** 这条消息被哪一路接手；`null` = 没被任何一路接手（也是「按顺序渲染」那档的老行为）。 */
+fun List<TurnBinding>.bindingOfMessage(messageId: String): TurnBinding? =
+    firstOrNull { binding -> messageId.isNotBlank() && binding.messageIds.contains(messageId) }
+
+/**
+ * `turn_begin.kind` ⇒ 「这一路是不是并行路」（纯函数，规范 §2.4）。
+ *
+ * 只有**逐字等于** `"parallel"` 才算并行：`"turn"`（新回合 / 续跑）不算，缺席 / 空串 / 大小写不同 /
+ * 以后新增的其它取值也一律不算。两侧空白按缺席的写法一并容忍（与 `parallelLimitNoticeFor` 认
+ * `pending_ack.reason` 同一条口径），大小写**不**容忍——认不出来就是认不出来。
+ *
+ * **为什么认不出来就算「不是并行」**：`kind` 是服务端后加的键，本端必须能在**老服务端**（整键不给）
+ * 上跑，而 [TurnBinding.leg] 又**根本不足以**当判据（它是会话内第几条路，串行回合照样占号）。
+ * 两件事叠起来只剩一个如实的答案：认不出来就说「不知道」，而「不知道」在界面上等于**不挂角标**
+ * ——宁可少挂一枚，也不能挂一枚声称存在并不存在的并行的标。
+ */
+fun isParallelLegKind(kind: String?): Boolean = kind?.trim() == PARALLEL_LEG_KIND
+
+/**
+ * 收下一条 `turn_begin`（纯函数，返回新表）。
+ *
+ * 同 [TurnBinding.turnId] 已存在时**合并**而不是新增：`messageIds` 取并集（保持原顺序在前），
+ * `leg` / `activeTurns` 用新报的值，**`closed` 保持原值**——一次重复到达的 `turn_begin` 不该把一条
+ * 已经收口的路「重新打开」（那会让气泡回到灰态并且再也等不到第二次收口）。
+ * 表里没有它时按**追加**处理：两路的顺序就是它们被启动的顺序。
+ *
+ * ## [TurnBinding.parallel] 的合并规则：一个只说真话的**单调**事实
+ * 新建时它 = [kind] 是不是 `"parallel"`（见 [isParallelLegKind]，认不出来 ⇒ `false`）；
+ * 已存在时取**或**（`old.parallel || 本帧是并行`）——**一旦为 true 就永远是 true**。
+ *
+ * 三条理由：
+ * 1. 「这一路是被并行起出来的」是**既成事实**：服务端同一条路的 `kind` 由创建那一刻的标志决定、
+ *    之后不可变，所以重复帧本不该各说各话；真各说各话时以「说过 parallel」为准——它不会凭一个
+ *    **更弱**（认不出 `kind`）的重复帧把已确立的并行抹掉，而并行只会多挂一枚有据可依的角标；
+ * 2. 与 [TurnBinding.closed] 同一条纪律：**单调的既成事实不许被后到的帧翻回去**；
+ * 3. 现实里真有「先弱后强」的顺序：[withSteeredMessage] 可能先按 `steer_ack` 建一条占位表
+ *    （那时没有 `kind`，只能是 `false`），随后那一路自己的 `turn_begin` 才是唯一能把它标成并行的地方。
+ *
+ * [kind] 缺席（默认空串）= 老服务端 / 老形状的帧 ⇒ 这一路永远 `false` ⇒ 不挂角标，与今天可解释地
+ * 一致（少一枚角标，但没有多说一句假话）。
+ */
+fun List<TurnBinding>.withTurnBegin(
+    turnId: String,
+    leg: Int,
+    messageIds: List<String>,
+    activeTurns: Int,
+    kind: String = "",
+): List<TurnBinding> {
+    val key = turnId.orNullIfBlank() ?: return this
+    val parallel = isParallelLegKind(kind)
+    val index = indexOfFirst { it.turnId == key }
+    if (index < 0) {
+        return this + TurnBinding(
+            turnId = key,
+            leg = leg,
+            messageIds = messageIds.filter(String::isNotBlank),
+            activeTurns = activeTurns,
+            parallel = parallel,
+        )
+    }
+    val old = this[index]
+    val merged = old.copy(
+        leg = leg.takeIf { it > UNKNOWN_LEG } ?: old.leg,
+        messageIds = (old.messageIds + messageIds.filter(String::isNotBlank)).distinct(),
+        activeTurns = activeTurns.coerceAtLeast(0),
+        parallel = old.parallel || parallel,
+    )
+    return toMutableList().also { it[index] = merged }
+}
+
+/**
+ * 收下一条 `steer_ack`（纯函数，返回新表）：把 [messageId] 绑到 [turnId] 这一路上——这就是
+ * 「这条消息被在飞的那一轮吃进去了，它进灰态」的凭据（规范 §2.5）。
+ *
+ * 该 `turnId` 还没有表项时**建一个只有这一条消息的表**（`steer_ack` 不给 `leg` / `activeTurns`，
+ * 所以那两项留 [UNKNOWN_LEG] / 0）。`turnId` 或 `messageId` 空白 ⇒ **原样返回**：
+ * 绑不出东西来（见 [TurnBinding] 的 KDoc）。
+ */
+fun List<TurnBinding>.withSteeredMessage(turnId: String, messageId: String): List<TurnBinding> {
+    val key = turnId.orNullIfBlank() ?: return this
+    val message = messageId.orNullIfBlank() ?: return this
+    val index = indexOfFirst { it.turnId == key }
+    if (index < 0) return this + TurnBinding(key, UNKNOWN_LEG, listOf(message))
+    val old = this[index]
+    if (old.messageIds.contains(message)) return this
+    return toMutableList().also { it[index] = old.copy(messageIds = old.messageIds + message) }
+}
+
+/**
+ * 收口（纯函数，返回新表）：把 [closingTurnId] 那一路上所有消息的绑定标记为 `closed`。
+ *
+ * 判据就是 [closesAnswering]（两个 id 都非空且相等），因此一个空白 / 认不出来的 `closingTurnId`
+ * **一条都不收口**——这正是老服务端（没有 `turnId`）上的行为：什么都不发生。
+ * 没有命中任何一条时**原样返回同一个实例**（Compose 的稳定性与测试里的 `assertSame` 靠它）。
+ */
+fun List<TurnBinding>.closingTurn(closingTurnId: String?): List<TurnBinding> {
+    var changed = false
+    val next = map { binding ->
+        if (!binding.closed && closesAnswering(binding.turnId, closingTurnId)) {
+            changed = true
+            binding.copy(closed = true)
+        } else {
+            binding
+        }
+    }
+    return if (changed) next else this
+}
+
+/**
+ * 把**全部**在途路收口（纯函数）：`session_idle` 的规范语义是「所有在途路都已收尾且 pending 空」
+ * （规范 §1.5），所以那一帧到达时**不可能**还有没收口的路——本函数就是这条语义的兜底落地。
+ * 它是兜底而不是主路径：主路径仍是各自 `turnId` 的 `turn.end`（规范 §1.2）。
+ */
+fun List<TurnBinding>.allClosed(): List<TurnBinding> {
+    if (none { !it.closed }) return this
+    return map { if (it.closed) it else it.copy(closed = true) }
+}
+
+/**
+ * 路标文案（规范 §1.4 A 的「小标」）：**真的是并行路**且 `leg >= 2` 时才成句，其余返回 `null`。
+ *
+ * 两个条件各挡一类错误，缺一不可：
+ * - [parallel] 为 `false` ⇒ **恒不挂**，哪怕 `leg` 是 2、3、99。`leg` 是**会话内第几条路**
+ *   （服务端对每条新路都自增，普通串行回合照样占号），拿它当并行的证据就是**对用户说谎**：
+ *   会话里第二条普通消息会凭空冒出一枚「并行路 2」，而那一刻一条并行都没有。是不是并行路
+ *   只有 `turn_begin.kind`（⇒ [TurnBinding.parallel]）说了算；
+ * - [leg] 小于 2（含 [UNKNOWN_LEG]）⇒ 不挂：单路是今天的常态（`parallel:true` 是客户端显式声明
+ *   才有的能力，规范 §0 的默认行为一条），给唯一一路也挂个「并行路 1」等于给每条回复都加一个新的
+ *   视觉噪音，却什么都说明不了。所以「有没有小标」本身就精确表达「这里是不是真的有多路」。
+ *   `leg` 未知同理不挂——不能把「不知道第几路」说成「第 0 路」。
+ */
+fun legBadgeOf(leg: Int, parallel: Boolean): String? =
+    if (parallel && leg >= 2) "并行路 $leg" else null
+
+/** 空白串等同于缺席（服务端是「整键缺席」，但真给空串时按同一件事处理，与既有各纯函数一致）。 */
+private fun String?.orNullIfBlank(): String? = this?.takeIf { it.isNotBlank() }
@@ -0,0 +1,207 @@
+package top.yeij.cyrene.domain.chat
+
+import java.util.Locale
+
+/**
+ * 预览内容**下方**那一行灰色小字的组装（纯函数，逐档穷举单测在 `PreviewMetadataTest`）。
+ *
+ * ## 这一行是什么，不是什么
+ * 它只放**关于这份文件本身**的格式事实：有多少行、按什么口径解码、多大、多少像素、什么时候拍的。
+ * 它**不是**状态栏、也不是错误提示——「读不到 / 打开失败 / 保存失败」各有自己的去处（芯片行、
+ * 正文区那句人话、弹层下方那行告知），混进来会让这一行读起来像出了什么事。
+ *
+ * ## 纪律：拿不到的项就不出现
+ * 每一项都在**有证据时才产出**，没有证据就整项缺席——**不留占位符、不写「未知」、不写 `--`**。
+ * 一屏小字里堆三个「未知」换不来任何信息，却会让人以为本端查过了。三档证据强度各自成条：
+ * - **字节**（本端真的持有那一份）：行数、像素、EXIF 拍摄日期、文件体积；
+ * - **服务端结论**（DTO 里的字段）：注入字符数、注入是否被截断、嗅探所得的 mime；
+ * - **本端口径**（本端自己做了什么）：`UTF-8` 只是**本端解码口径**，不是文件的真实编码（见下）。
+ *
+ * ## 「编码」为什么敢写 UTF-8（且只敢这么写）
+ * 客户端**拿不到文件的真实编码**：磁盘上那份字节是按什么字符集写的，没有任何字段说过，本端也没有
+ * 可靠的方式判定（猜 GBK / Shift-JIS 就是在编）。能确定的只有一件事：正文区那段文字是
+ * [DocumentPreview.slice] 用 `String(bytes, Charsets.UTF_8)` 解出来的——所以这一项写的是
+ * **「本端解码口径」**，即「你正在读的这段文字是怎么来的」。**表述里必须带这个限定语**：
+ * 裸写一个「UTF-8」会被读成「这份文件是 UTF-8 编码的」，那是本端不知道的事。
+ *
+ * ## 与芯片行重合的两处：一处保留、一处省略
+ * 预览弹层顶部那枚芯片已经写着「类型 · 体积 · 字数 · 状态 · 注入已截断」（[DocumentChipModel.detail]），
+ * 因此这一行刻意**不重复**：
+ * - **省略**「体积」与「服务端状态」：[DocumentChips.sizeLabel] / [DocumentChips.statusLabel] 那两个
+ *   数字/词与芯片行**逐字相同**、且没有口径可补，再写一遍只是噪音（图片那一路没有芯片行，所以
+ *   体积在 [imageItems] 里是要显示的）；
+ * - **保留**「字符数」并补上口径：芯片只写「8,000 字」，读者无法知道那是**服务端注入上下文**的
+ *   字数还是这份文件的字数——这正是一句会把人带偏的话，补上「（服务端注入口径）」才算说清。
+ *
+ * ## 本端的截断为什么不在这里再说一遍
+ * [PreviewSlice.truncated]（本端只预览了前 256 KB / 5,000 行）已经让 [PreviewSlice.notice] 在**正文
+ * 上方**明说了，本行不再重复同一件事；而**服务端**的「注入被预算截断」是另一件事（[DocumentRefDto.truncated]，
+ * 正文照样进了上下文），它没有别的去处，所以在 [textItems] 里单列一条。
+ */
+object PreviewMetadata {
+
+    /** 这一行各项之间的分隔符。 */
+    const val ITEM_SEPARATOR: String = " · "
+
+    /** 把各项拼成能直接交给 `Text` 的那一行；空列表拼成空串（调用方据此不画这一行）。 */
+    fun join(items: List<String>): String = items.joinToString(ITEM_SEPARATOR)
+
+    /**
+     * 文本类预览的那几项：行数 · 字符数（带口径）· 解码口径 · 服务端的截断标记。
+     *
+     * @param slice 正文区的切段结果（[DocumentPreview.slice] 的产物）。
+     * @param serverCharsLabel 服务端下发的注入字符数**已格式化**的那一份
+     *   （`documents[].chars` → [DocumentChips.charsLabel]，如 `"8,000 字"`）；`null` = 服务端没报
+     *   （`chars` 整键缺席，契约 v0.59 §1.2），此时改报本端预览内容的字数。
+     * @param contextTruncated 服务端是否报告了「注入被预算截断」（`documents[].truncated`）。
+     *   ⚠️ 与 [PreviewSlice.truncated]（**本端**预览截断）是两件事，见本对象 KDoc。
+     */
+    fun textItems(
+        slice: PreviewSlice,
+        serverCharsLabel: String?,
+        contextTruncated: Boolean,
+    ): List<String> = buildList {
+        add(linesItem(slice))
+        add(charsItem(slice.text, serverCharsLabel))
+        // 本端解码口径：正文就是 String(bytes, UTF_8) 的产物，说得出、也只在说这一件事。
+        add(DECODED_AS_UTF8)
+        if (contextTruncated) add(TRUNCATED_FOR_CONTEXT)
+    }
+
+    /**
+     * 非文本类（PDF 这类二进制）的那几项：只有服务端**字节嗅探**所得的 mime。
+     *
+     * 体积与状态刻意不在这里（芯片行已经写着，见本对象 KDoc）；服务端说「读不到」时下发的
+     * **原因原话**也不在这里——它已经被 [DocumentPreviewGate.plan] 送进正文区那句人话里**原样显示**，
+     * 这里是同一屏的第二个位置，重复一遍只会让那句话看着像两条不同的消息。
+     *
+     * @param serverMime DTO 的 `mime`（服务端嗅探所得基类型）；本地待发附件**没有**这个结论
+     *   （还没上传过），传 `null` —— 这一项因此缺席，**不由本端按扩展名补一个**。
+     */
+    fun fileItems(serverMime: String?): List<String> =
+        listOfNotNull(serverMime?.trim()?.takeIf { it.isNotEmpty() })
+
+    /**
+     * 图片的那几项：格式（mime）· 分辨率 · 体积 · 拍摄日期。
+     *
+     * 图片这一路没有附件芯片行，所以体积在这里是要显示的。每一项都可能在拿不到时缺席：
+     * 格式（嗅探与平台声明都判不出来时）、分辨率（本端解不出边界时）、拍摄日期（EXIF 里没有
+     * `DateTimeOriginal`，或那个值不是能认的日期时）——见各自的参数说明。
+     *
+     * @param mime 交给别的应用的类型（[ImageOpenTypes.openType] 的产物）。⚠️ 退化到「图片通配」
+     *   时**必须传 `null`**：`image/` 通配（[ImageOpenTypes.ANY_IMAGE]）不是格式，写出来等于给了一个什么都没说的答案。
+     * @param width / @param height 本端按 `inJustDecodeBounds` 读到的像素；任一侧 ≤ 0 / 缺席即整项不出现。
+     * @param sizeBytes 本端实际持有的字节数；[UNKNOWN_BYTES] 即整项不出现。
+     * @param capturedAt EXIF `DateTimeOriginal` 的**原始字符串**（`yyyy:MM:dd HH:mm:ss`，
+     *   没有时区、按本地墙钟读，见 [formatExifDateTime]）。
+     */
+    fun imageItems(
+        mime: String?,
+        width: Int? = null,
+        height: Int? = null,
+        sizeBytes: Long = UNKNOWN_BYTES,
+        capturedAt: String? = null,
+    ): List<String> = buildList {
+        mime?.trim()?.takeIf { it.isNotEmpty() }?.let { add(it) }
+        if (width != null && height != null && width > 0 && height > 0) add("$width × $height")
+        DocumentChips.sizeLabel(sizeBytes).takeIf { it.isNotEmpty() }?.let { add(it) }
+        formatExifDateTime(capturedAt)?.let { add(CAPTURED_AT_PREFIX + it) }
+    }
+
+    /**
+     * EXIF 的拍摄时间 → 人能读的样子（`"2019:07:04 20:31:05"` → `"拍摄于 2019年7月4日 20:31"`）；
+     * 认不出就回 `null`（宁可不显示，也不显示一个错的日期）。
+     *
+     * ## 两个必须说清的取舍
+     * 1. **没有时区**。EXIF 的 `DateTimeOriginal` 是纯墙钟字符串（`yyyy:MM:dd HH:mm:ss`），规范里
+     *    根本没有偏移量字段。所以这里**不做任何时区换算**，按字面数字当日历时间读——把它当 UTC
+     *    再转本地，只会让一个原本正确的日期凭空错几个小时。
+     * 2. **严格到不近人情**。只有逐位对上 `yyyy:MM:dd HH:mm:ss`（19 个字符、分隔符固定）且各段落在
+     *    合法范围内才认。相机的「值未写入」占位符 `"0000:00:00 00:00:00"` 因此落在月份 0 上被判非法
+     *    ——这是对的，它本来就表示「不知道」。宽松解析（补零、猜分隔符）换来的是**看起来正常的错日期**，
+     *    比不显示糟得多。
+     *
+     * 秒刻意丢掉：这一行是给人看的摘要，分钟已经足够定位（同秒的两张图对用户没有区别）。
+     */
+    fun formatExifDateTime(raw: String?): String? {
+        val value = raw?.trim().orEmpty()
+        val groups = EXIF_DATE_TIME.matchEntire(value) ?: return null
+        // 正则已保证每段都是纯数字，`toInt()` 在这里不会抛。
+        val (year, month, day, hour, minute, second) = groups.destructured
+        val y = year.toInt()
+        val mo = month.toInt()
+        val d = day.toInt()
+        val h = hour.toInt()
+        val mi = minute.toInt()
+        val s = second.toInt()
+        if (y < MIN_YEAR) return null
+        if (mo !in 1..12) return null
+        if (d !in 1..31) return null
+        if (h !in 0..23) return null
+        if (mi !in 0..59) return null
+        // 60 是闰秒，相机会写出来，不该判成坏日期。
+        if (s !in 0..60) return null
+        return String.format(Locale.ROOT, "%d年%d月%d日 %02d:%02d", y, mo, d, h, mi)
+    }
+
+    /**
+     * 行数那一项。
+     *
+     * 显示量按 [DocumentPreview.lineCount] **从正文本身重算**（不是取 [PreviewSlice.shownLines]）：
+     * 这一行的标题就是「你看到的这段有多少行」，重算让它与正文永远自洽。被本端截断时补上全文行数
+     * （[PreviewSlice.totalLines] 是按整份字节数出来的，本端确实持有那份字节）——只说「显示 N 行」
+     * 会让人以为文件就这么长。
+     */
+    private fun linesItem(slice: PreviewSlice): String {
+        val shown = grouped(DocumentPreview.lineCount(slice.text))
+        return if (slice.truncated) {
+            "显示 $shown 行 / 共 ${grouped(slice.totalLines)} 行"
+        } else {
+            "$shown 行"
+        }
+    }
+
+    /** 字符数一项：服务端报了就报它那句（补口径），没报才用本端的计数（另一句口径）。 */
+    private fun charsItem(text: String, serverCharsLabel: String?): String =
+        if (serverCharsLabel != null) {
+            serverCharsLabel + SERVER_CHARS_SCOPE
+        } else {
+            grouped(codePointCount(text)) + " 字" + LOCAL_CHARS_SCOPE
+        }
+
+    /**
+     * 「字」数按 **Unicode 码点**算（`codePointCount`）：一个 emoji / 一个汉字都算一个字。
+     * 直接取 `String.length` 会把 BMP 之外的字符算成两个（UTF-16 代理对），与「字数」这个说法不符。
+     */
+    private fun codePointCount(text: String): Int =
+        text.codePointCount(0, text.length)
+
+    /** 千分位分组（只用于计数，纯展示）。 */
+    private fun grouped(value: Int): String = String.format(Locale.ROOT, "%,d", value)
+
+    // —— 每一项的措辞都收在这里，测试锚的也是这几句 ——
+
+    /** 本端解码口径。**限定语不许省**：省了就成了对文件真实编码的断言（见本对象 KDoc）。 */
+    const val DECODED_AS_UTF8: String = "UTF-8（本端解码口径）"
+
+    /** 服务端 `chars` 的口径：那是**注入上下文**的字数，不是这份文件的字数。 */
+    const val SERVER_CHARS_SCOPE: String = "（服务端注入口径）"
+
+    /** 本端自己数出来的字数口径：只数了预览内容（截断时就不是全文）。 */
+    const val LOCAL_CHARS_SCOPE: String = "（本端预览内容）"
+
+    /** 服务端的 `truncated`：注入被预算截断，**正文照样进了上下文**（与「读不到」是两件事）。 */
+    const val TRUNCATED_FOR_CONTEXT: String = "正文被截断（进上下文的部分）"
+
+    /** 拍摄日期前缀：一个光秃秃的日期在这一行里会被当成「文件修改时间」之类的东西。 */
+    const val CAPTURED_AT_PREFIX: String = "拍摄于 "
+
+    /** 字节数拿不到时的占位：交给 [DocumentChips.sizeLabel]，它会回空串（于是整项不出现）。 */
+    const val UNKNOWN_BYTES: Long = -1L
+
+    private const val MIN_YEAR = 1
+
+    /** EXIF 规范里的日期时间形状；只认这一种，见 [formatExifDateTime]。 */
+    private val EXIF_DATE_TIME =
+        Regex("""(\d{4}):(\d{2}):(\d{2}) (\d{2}):(\d{2}):(\d{2})""")
+}
@@ -0,0 +1,238 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 一段**要发出去的语音**：录音参数、WAV 封装、体积闸门与幂等键（纯函数，可穷举单测）。
+ *
+ * ## 为什么自己封 WAV，而不是用 `MediaRecorder`
+ * 契约 v0.96 给 `voice_input.format` 的白名单是 **`wav|mp3|ogg`**，而 Android `MediaRecorder`
+ * 的默认产物是 **`m4a/aac`**——**不在白名单里**。要用它就得另接一个编码器把 aac 转成 mp3/ogg，
+ * 那是新依赖（项目纪律：加依赖先问）。而 `AudioRecord` 给的 PCM + 一个 44 字节的 RIFF 头
+ * 就是 WAV：**零依赖、零转码、逐字节可预期**，也能在单测里把头的每个字段钉死。
+ *
+ * ## 采样参数：16 kHz / 单声道 / 16-bit
+ * - **采样率 16 kHz**：语音识别的行业口径就是 16 kHz（电话带宽 8 kHz 会把擦音削掉，44.1 kHz
+ *   对 STT 没有任何增益）。同一句话的字节数因此只有 44.1 kHz 的 **36%**——这一条在本端格外重要，
+ *   因为 `voice_input.audio` 是**内联 base64**（4/3 膨胀）走一条 WS 文本帧。
+ * - **单声道**：麦克风阵列的立体声对 STT 只有副作用（两路几乎相同，白背一倍体积）。
+ * - **16-bit**：`AudioRecord` 的原生 PCM 编码（`ENCODING_PCM_16BIT`），不做压缩——压缩要依赖。
+ *
+ * 由此得出一个**只有一条**的换算：`1 ms = 32 字节`，`1 s = 32 000 字节`。
+ *
+ * ## 体积闸门（为什么是 5 MiB）
+ * 契约 v0.96 的 `voice_input` **没写** `audio` 的体积上限（`chat.image` 写了：解码后 5 MiB /
+ * 字符串 6990572 字符）。本端按**已知最严的那一档**设计，也就是 [MAX_AUDIO_BYTES] =
+ * `ChatImageBudget.SERVER_MAX_DECODED_BYTES`（5 MiB，解码后）——同一个部署对「内联 base64 字段」
+ * 已经明确接受的量级，voice 没有理由比它更宽。超限**明确拒绝**（[VOICE_TOO_LARGE_MESSAGE]），
+ * 绝不静默截断：截断后的音频在服务端听来就是「话说到一半断了」。
+ *
+ * 60 秒的录满长度（[MAX_RECORDING_MILLIS]）只用到这条闸门的 **36%**（1 920 044 字节），所以
+ * 正常路径永远撞不到它——它是**第二道**闸（硬件偶尔会多给几块缓冲，谁也说不准），不是主判据。
+ *
+ * ## 时长下限
+ * 按下就松手的误触会得到几十毫秒的音频：那不是「说话」，送给服务端只会换来一次空转写。
+ * 不足 [MIN_RECORDING_MILLIS] 的录音在**本端**就被挡下并说明（[VOICE_TOO_SHORT_MESSAGE]）。
+ */
+object VoiceClip {
+
+    /** 采样率（Hz）。16 kHz = STT 的行业口径，见类注释。 */
+    const val SAMPLE_RATE_HZ: Int = 16_000
+
+    /** 声道数：单声道（立体声对 STT 无益，只翻倍体积）。 */
+    const val CHANNEL_COUNT: Int = 1
+
+    /** 位深：`AudioRecord` 的原生 16-bit PCM。 */
+    const val BITS_PER_SAMPLE: Int = 16
+
+    /** 每采样的字节数。 */
+    const val BYTES_PER_SAMPLE: Int = BITS_PER_SAMPLE / 8
+
+    /** RIFF/WAVE 的 PCM 头长度：`RIFF`(4) + size(4) + `WAVE`(4) + `fmt `(16+8) + `data`(8)。 */
+    const val HEADER_BYTES: Int = 44
+
+    /** 上行 `format` 的取值。契约白名单 `wav|mp3|ogg` 里我们**只产出**这一个。 */
+    const val FORMAT: String = "wav"
+
+    /** 每秒的 PCM 字节数（= [SAMPLE_RATE_HZ] × [CHANNEL_COUNT] × [BYTES_PER_SAMPLE]）。 */
+    val BYTES_PER_SECOND: Int = SAMPLE_RATE_HZ * CHANNEL_COUNT * BYTES_PER_SAMPLE
+
+    /**
+     * 一段语音（**含头**）的字节上限：与 `chat.image` 解码后同一条线，见类注释。
+     * 刻意**引用**那个常量而不是再写一遍 `5 * 1024 * 1024`：上限只留一处，改的时候不会漂。
+     */
+    const val MAX_AUDIO_BYTES: Int = ChatImageBudget.SERVER_MAX_DECODED_BYTES
+
+    /**
+     * 一次录音的**最长**时长（毫秒）。60 秒取自 IM 的通行口径（微信 / QQ 都是这个量级），
+     * 也对得上服务端 STT 的现实：再长的语音转写质量与等待都不划算。
+     *
+     * 到点由录音机自己置「满了」标记（见 `VoiceRecorder`），UI 随即收尾发送——
+     * 不是悄悄截断，用户看到的是「到 60 秒了，这段发出去」。
+     */
+    const val MAX_RECORDING_MILLIS: Int = 60_000
+
+    /** 短于这个时长的录音**不送**（按下就松手的误触），见类注释。 */
+    const val MIN_RECORDING_MILLIS: Int = 1_000
+
+    /** 60 秒对应的 PCM 字节数（录音机据此封顶，不在读循环里另算一遍公式）。 */
+    val MAX_PCM_BYTES: Int = pcmBytesFor(MAX_RECORDING_MILLIS)
+
+    /** 这段 PCM 加上 WAV 头之后的**总**字节数。 */
+    fun totalBytesFor(pcmBytes: Int): Int = if (pcmBytes <= 0) 0 else HEADER_BYTES + pcmBytes
+
+    /** 时长 → PCM 字节数（向下取整；`<= 0` 的时长回 0）。 */
+    fun pcmBytesFor(durationMillis: Int): Int =
+        if (durationMillis <= 0) 0 else (durationMillis.toLong() * BYTES_PER_SECOND / 1000L).toInt()
+
+    /** PCM 字节数 → 时长（毫秒，向下取整）。 */
+    fun durationMillisOf(pcmBytes: Int): Int =
+        if (pcmBytes <= 0) 0 else (pcmBytes.toLong() * 1000L / BYTES_PER_SECOND).toInt()
+
+    /** 总字节数是否在 [MAX_AUDIO_BYTES] 以内（**等于**算通过：`<=`，与 `withinServerLimit` 同口径）。 */
+    fun withinLimit(totalBytes: Int): Boolean = totalBytes <= MAX_AUDIO_BYTES
+
+    /**
+     * WAV 头（44 字节，PCM / 单块 / 无扩展）。
+     *
+     * 逐字段按 RIFF 规范写：`RIFF` + 文件长 - 8 + `WAVE` + `fmt `(16 字节，PCM=1) + 声道 /
+     * 采样率 / 字节率 / 块对齐 / 位深 + `data` + 数据长。全部**小端**。
+     */
+    fun wavHeader(pcmBytes: Int): ByteArray {
+        val data = ByteArray(HEADER_BYTES)
+        putAscii(data, 0, "RIFF")
+        putIntLe(data, 4, HEADER_BYTES - 8 + pcmBytes)
+        putAscii(data, 8, "WAVE")
+        putAscii(data, 12, "fmt ")
+        putIntLe(data, 16, 16)
+        putShortLe(data, 20, AUDIO_FORMAT_PCM)
+        putShortLe(data, 22, CHANNEL_COUNT)
+        putIntLe(data, 24, SAMPLE_RATE_HZ)
+        putIntLe(data, 28, BYTES_PER_SECOND)
+        putShortLe(data, 32, CHANNEL_COUNT * BYTES_PER_SAMPLE)
+        putShortLe(data, 34, BITS_PER_SAMPLE)
+        putAscii(data, 36, "data")
+        putIntLe(data, 40, pcmBytes)
+        return data
+    }
+
+    /** 头 + PCM = 一个可直接交给任何 `WAV` 解码器的字节数组。 */
+    fun toWav(pcm: ByteArray): ByteArray {
+        val header = wavHeader(pcm.size)
+        val out = ByteArray(HEADER_BYTES + pcm.size)
+        header.copyInto(out, 0)
+        pcm.copyInto(out, HEADER_BYTES)
+        return out
+    }
+
+    /**
+     * 这段 PCM 该不该发、发出去长什么样（**唯一**的准入判据，录音机与 VM 共用）。
+     *
+     * 判序是刻意的：**空 → 超限 → 太短 → 可发**。
+     * - 空：一个字节都没有（设备没给 / 权限刚被撤），连「太短」都谈不上；
+     * - 超限：长度或字节数已经越线，绝不能发（哪怕时长看起来正常——硬件也可能给出异常长的一块）；
+     * - 太短：见 [MIN_RECORDING_MILLIS]。
+     */
+    fun plan(pcm: ByteArray): VoiceClipPlan {
+        if (pcm.isEmpty()) return VoiceClipPlan.Empty
+        val total = totalBytesFor(pcm.size)
+        if (!withinLimit(total)) return VoiceClipPlan.TooLarge(total)
+        val duration = durationMillisOf(pcm.size)
+        if (duration < MIN_RECORDING_MILLIS) return VoiceClipPlan.TooShort(duration)
+        return VoiceClipPlan.Ready(toWav(pcm), duration)
+    }
+
+    /** RIFF 的 `audioFormat`：1 = PCM（整数）。 */
+    private const val AUDIO_FORMAT_PCM: Int = 1
+
+    private fun putAscii(target: ByteArray, offset: Int, text: String) {
+        for (index in text.indices) target[offset + index] = text[index].code.toByte()
+    }
+
+    private fun putIntLe(target: ByteArray, offset: Int, value: Int) {
+        target[offset] = (value and 0xFF).toByte()
+        target[offset + 1] = ((value ushr 8) and 0xFF).toByte()
+        target[offset + 2] = ((value ushr 16) and 0xFF).toByte()
+        target[offset + 3] = ((value ushr 24) and 0xFF).toByte()
+    }
+
+    private fun putShortLe(target: ByteArray, offset: Int, value: Int) {
+        target[offset] = (value and 0xFF).toByte()
+        target[offset + 1] = ((value ushr 8) and 0xFF).toByte()
+    }
+}
+
+/** [VoiceClip.plan] 的四档结论。 */
+sealed interface VoiceClipPlan {
+
+    /** 一段**可以发**的语音：已经封好 WAV，[durationMs] 是它的实际时长。 */
+    class Ready(val wav: ByteArray, val durationMs: Int) : VoiceClipPlan
+
+    /** 一个字节都没录到。 */
+    data object Empty : VoiceClipPlan
+
+    /** 短于 [VoiceClip.MIN_RECORDING_MILLIS]（按下就松手那种误触）。 */
+    data class TooShort(val durationMs: Int) : VoiceClipPlan
+
+    /** 总字节数超过 [VoiceClip.MAX_AUDIO_BYTES]。 */
+    data class TooLarge(val totalBytes: Int) : VoiceClipPlan
+}
+
+/** 空录音的如实告知（**不是错误**：什么都没发生，用户重来一次即可）。 */
+const val VOICE_EMPTY_MESSAGE: String = "没有录到声音，再按一次试试"
+
+/** 太短的如实告知。 */
+const val VOICE_TOO_SHORT_MESSAGE: String = "录得太短了，说满一秒再发"
+
+/**
+ * 超限的如实告知。刻意说「没发出去」：那句话必须与事实上一致（这条一个字节都没上行），
+ * 也不能把责任推给用户（他确实就说了那么久，是本端的闸门挡下的）。
+ */
+const val VOICE_TOO_LARGE_MESSAGE: String = "这段语音太长，本机没有发出去"
+
+/** 这一条被本端挡下时该说的那句话；`null` = 可以发（纯函数）。 */
+fun voiceClipRejection(plan: VoiceClipPlan): String? = when (plan) {
+    is VoiceClipPlan.Ready -> null
+    VoiceClipPlan.Empty -> VOICE_EMPTY_MESSAGE
+    is VoiceClipPlan.TooShort -> VOICE_TOO_SHORT_MESSAGE
+    is VoiceClipPlan.TooLarge -> VOICE_TOO_LARGE_MESSAGE
+}
+
+/**
+ * 录音中 / 待重发那一段的时长文案（纯函数）：`m:ss`，**从 0:00 起就有值**。
+ *
+ * 与接收侧的 [voiceDurationLabel] 差一条：那个对「不足一秒」回 `null`（服务端没给准数时宁可
+ * 不显示），而这里显示的是**本端自己正在数的时间**——0:00 是事实，不是冒充。
+ * 负数按 0 处理（时钟回拨 / 调用方算错时也不出现 `-1:-1`）。
+ */
+fun voiceElapsedLabel(elapsedMs: Int): String {
+    val totalSeconds = elapsedMs.coerceAtLeast(0) / 1000
+    return "${totalSeconds / 60}:${(totalSeconds % 60).toString().padStart(2, '0')}"
+}
+
+/** 语音消息的幂等键前缀：与文本那条（`local-`）/ 分享那条（`share-`）同一手法，见 [voiceClientMsgIdFor]。 */
+const val VOICE_CLIENT_MSG_ID_PREFIX: String = "voice-"
+
+/**
+ * 一条**录好、还没发出去**的语音在本端的记账（只有小字段，audio 不在这里）。
+ *
+ * `clientMsgId` 是契约 v0.96 §3.15 的幂等键：同一个非空值服务端**只承认第一条**，重复到达回
+ * `chat_duplicate`、不落库不起回合。所以「重发这一段」必须**复用**它（[voiceClientMsgIdFor]），
+ * 换了新键就是让服务端把同一句话再答一遍。
+ *
+ * `audio`（base64）刻意**不进** [top.yeij.cyrene.ui.chat.ChatUiState]：那是一格会被反复 `copy`
+ * 并逐字段比较的状态（流式期间每秒几十次），几 MB 的字符串放进去等于每次比较都扫一遍它。
+ * 字节留在 VM 自己那个字段上（生命周期与 VM 相同，转屏不丢）。
+ */
+data class VoiceDraftInfo(
+    val clientMsgId: String,
+    val durationMs: Int,
+    val totalBytes: Int,
+)
+
+/**
+ * 这一段该用哪个幂等键（纯函数）：
+ * - [draft] 非空 = **重发刚才没发出去的那一段** ⇒ 原样复用它当时的键（契约要求）；
+ * - [draft] 为空 = 一段**新**录音 ⇒ 现铸一个：前缀 + [mint] 给的随机串（随机而不是自增，
+ *   理由与文本那条相同：服务端的判重窗口是整个会话历史）。
+ */
+fun voiceClientMsgIdFor(draft: VoiceDraftInfo?, mint: () -> String): String =
+    draft?.clientMsgId ?: "$VOICE_CLIENT_MSG_ID_PREFIX${mint()}"
@@ -0,0 +1,311 @@
+package top.yeij.cyrene.domain.chat
+
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.data.repository.DocumentCacheUnavailableException
+import top.yeij.cyrene.data.repository.VoiceTooLargeException
+import top.yeij.cyrene.data.repository.VoiceUrlUnavailableException
+
+/**
+ * `voice.source` 的闭集（契约 §4.4）：`asr` = 服务端（含云端）语音识别所得；
+ * `platform` = 渠道平台自带转写（微信 iLink 的 `voice_item.text`）；
+ * `tts` = **我们自己合成的出站语音**（她的 `speak` 工具产出的那一段，后端 M57-M59 新增）。
+ *
+ * 三个取值在**接收侧**没有分叉：合成成功的那条与入站语音同形（`status = transcribed` + 四键
+ * 副本齐全），照同一条路渲染；合成降级的那条是 `status = failed`（见 [VoiceStatus.FAILED]）。
+ */
+object VoiceSource {
+
+    const val ASR: String = "asr"
+
+    const val PLATFORM: String = "platform"
+
+    const val TTS: String = "tts"
+}
+
+/**
+ * `voice.status` 的闭集（契约 §4.4，**三态**）。
+ *
+ * 与 [DocumentStatus] 同一条纪律：**只认闭集里的取值，认不出的不猜**——但两者收尾的方式不同。
+ * 文档的未知 `status` 要**原样显示**（那是给用户看的结论），语音的未知 `status` 只是
+ * 「本端不多说一句话」（正文由服务端给，见 [voiceNote]）。
+ */
+object VoiceStatus {
+
+    /** 正文**就是**转写文本（出站方向 = 合成成功、有副本可播）。 */
+    const val TRANSCRIBED: String = "transcribed"
+
+    /** 转写成功但**没识别出文字** ⇒ 正文多半是空的，本端补一句（[VOICE_EMPTY_NOTE]）。 */
+    const val EMPTY: String = "empty"
+
+    /**
+     * 这一条**没有可播的语音**，正文是一句话（见 [isPlayableVoice]）。
+     *
+     * 两个方向同形、语义统一（后端 M57-M59 预告，契约 v0.98 待正式回执）：
+     * - **入站**：没拿到转写文本 ⇒ 正文是服务端给的那行中文诚实提示；
+     * - **出站**：她本想用语音、合成降级回文字 ⇒ 正文是普通文字，另带 `fallbackReason`
+     *   （见 [voiceFallbackNote]）。
+     *
+     * 入站方向设计上**刻意不下发**失败细分（未配置 / 鉴权 / 欠费 / 限流 / 超时 / 格式不支持 /
+     * 无字节一律只进服务端日志），所以本端**一个细分都不许猜**，也不替服务端改写那句话。
+     */
+    const val FAILED: String = "failed"
+}
+
+/**
+ * 「转写成功但没识别出文字」时本端补的那一句。
+ *
+ * 为什么这句是**本端的**而不是服务端的原话：这一态的语义由契约定义（§4.4 的三态之一），而
+ * `empty` 的正文按定义就是空的——不补一句的话，一条「微信语音、没有音频副本、也没转出文字」
+ * 的消息在屏幕上**只剩一个「语音」标签**，看的人无从知道发生了什么。这不是替服务端改文案
+ * （那句话说的是**这一态的语义**，不是失败原因），也**不覆盖**任何正文。
+ */
+const val VOICE_EMPTY_NOTE: String = "没有识别出文字"
+
+/**
+ * `status == "failed"` 的那一行**灰色小标**的固定前半句（后面可能跟服务端给的 `fallbackReason`）。
+ *
+ * 为什么要有这一行：这一态的消息 `voice` 键**在**、但**没有可播的语音**（见 [isPlayableVoice]），
+ * 所以屏幕上不会有语音形态。少了这一行，一条「她本想发语音、合成降级成文字」的消息与一条普通文字
+ * 消息**逐像素相同**——看的人无从知道这条本来是一段声音。它只说本端能确定的那件事（这条没有可播的
+ * 声音），**不解释原因**（原因归服务端，见 [voiceFallbackNote] 里那段原话）。
+ *
+ * ⚠️ 措辞要同时站得住两个方向（入站转写失败 / 出站合成降级），所以**不写**「转写失败」也**不写**
+ * 「合成失败」：本端分不清，也不该替服务端选一个说法。
+ */
+const val VOICE_FALLBACK_NOTE: String = "这条语音没有可播放的声音"
+
+/**
+ * 解码 / 播放阶段失败（`MediaPlayer` 报错或起播抛异常）时的文案。
+ *
+ * 与取字节失败（[voicePlaybackFailureMessage]）分开：两者要用户做的事不一样——字节没拿到是
+ * 「网络 / 过期 / 服务端没有这份副本」，可以再点一次；这一段是「字节在手上，本机解不开」
+ * （格式不支持、文件损坏），再点一次多半还是同样的结果。
+ */
+const val VOICE_UNPLAYABLE_MESSAGE: String = "这段语音本机播不了"
+
+/**
+ * 一条语音的**可播放副本**：四个键（`name` / `mime` / `size` / `url`）齐全时才构造得出来。
+ *
+ * 存在的理由是把「能不能播」这件事**收成一个类型**，而不是让 UI / 播放器各自去测四个 `!= null`：
+ * 拿到 [VoiceAudio] 就等于「有副本、可以画播放控件、可以发请求」；拿不到就**一个播放控件都不画**
+ * （不能给一个点下去必然失败的按钮）。
+ *
+ * @property durationMs 从 [VoiceDto] 原样带过来；`null` = 服务端没给，**不显示时长**。
+ */
+data class VoiceAudio(
+    val name: String,
+    val mime: String,
+    val size: Long,
+    val url: String,
+    val durationMs: Int? = null,
+)
+
+/**
+ * `voice` 键在不在（纯函数）—— 「这条消息**来自**一条语音」。
+ *
+ * 这是契约 §4.4 给的**唯一**来源判据：非语音消息整键缺席（不是 `{}` 也不是 `null`），
+ * `content` 里有没有 `[语音]` 这类字样与本判据无关（QQ 的占位标记自 v0.67 起不再下发，
+ * 别人也可以自己打出一模一样的字）。
+ *
+ * ⚠️ 它与「要不要画语音气泡」**不是同一件事**了：合成降级 / 转写失败的那些行 `voice` 键照样在，
+ * 但**没有可播的语音**（见 [isPlayableVoice]）。判「是不是语音消息」用本函数，判「画不画语音
+ * 形态」用 [isVoiceMessage]——两个问题分开问，混用会让降级行被画成一个必然播不了的气泡。
+ */
+fun hasVoice(message: HistoryMessageDto): Boolean = message.voice != null
+
+/**
+ * 这条语音**有没有可播的语音形态**（纯函数）：除了 `voice` 键要在，`status` 还不能是 `failed`。
+ *
+ * ## 为什么判据是「不是 `failed`」而不是「是 `transcribed` / `empty`」
+ * 后端 M57-M59 预告（契约 v0.98 待正式回执）只点名了 `failed` 这一态**明确没有可播的语音**：
+ * 入站是没拿到转写文本、出站是合成降级回文字，两个方向的正文都是一句话而不是一段语音。
+ *
+ * 反过来，认不出的 `status` **一律当可播**（fail-open）。理由是这个方向错得便宜、另一个方向错得
+ * 贵：后端将来若新增一个成功态（比如 `transcribed` 之外的 `truncated`），fail-open 只是多画一枚
+ * 语音形态（最坏是点了播不出来，有既有的失败文案兜着）；fail-closed 则会把一条**真的有副本**的
+ * 语音静默吞成纯文字，用户再也点不到那段声音——而且没有任何界面提示说明为什么。所以这里只把
+ * 契约明确说过「没有语音」的那一态排除掉，其余交给「四键齐全才画播放控件」（[voiceAudio]）。
+ */
+fun isPlayableVoice(voice: VoiceDto): Boolean = voice.status != VoiceStatus.FAILED
+
+/**
+ * 🎤 **要不要画语音形态的判据** = `voice` 键存在 **且** `status != "failed"`（契约 §4.4 +
+ * 后端 M57-M59 预告）。
+ *
+ * 只有这两个条件，而且**永远只有这两个**：
+ * - `voice` 键缺席 ⇒ 不是语音消息（[hasVoice]）；
+ * - `status == "failed"` ⇒ 这条**没有可播的语音**（入站转写失败 / 出站合成降级），正文照常按文字
+ *   渲染，另加一行灰色小标（[voiceFallbackNote]）——**不**画语音形态，因为画出来就是一个必然
+ *   播不了的控件。
+ *
+ * 入站语音（`asr` / `platform`）与合成成功的出站语音（`tts`）走的是**同一条**路：判据只看
+ * `status`，不看 `source`。
+ */
+fun isVoiceMessage(message: HistoryMessageDto): Boolean {
+    val voice = message.voice ?: return false
+    return isPlayableVoice(voice)
+}
+
+/**
+ * 这条语音的**可播放副本**；四个键没凑齐（或名字 / MIME / URL 是空白）就回 `null`。
+ *
+ * 服务端保证「四者同生共死」，本端仍然逐项检查：**这条判据的下游是「给不给播放控件」**，
+ * 而契约里那份保证一旦被某个部署打破，唯一的后果就是用户点到一个必然失败的按钮
+ * ——宁可少画一个控件，也不要画一个假的。
+ *
+ * `size` 只要求在（**不要求 > 0**）：契约说它恒在，本端也不拿它推导别的任何东西
+ * （尤其**不反算时长**，见 [voiceDurationLabel]）。
+ */
+fun voiceAudio(voice: VoiceDto?): VoiceAudio? {
+    if (voice == null) return null
+    val name = voice.name?.takeIf { it.isNotBlank() } ?: return null
+    val mime = voice.mime?.takeIf { it.isNotBlank() } ?: return null
+    val url = voice.url?.takeIf { it.isNotBlank() } ?: return null
+    val size = voice.size ?: return null
+    return VoiceAudio(name = name, mime = mime, size = size, url = url, durationMs = voice.durationMs)
+}
+
+/**
+ * 时长文案（纯函数）：`m:ss`（如 `0:03` / `1:05`）。
+ *
+ * **缺席就不显示**是契约的硬要求（服务端「读不出来就省略键，绝不估算」，本端同理）：
+ * - `null` ⇒ 回 `null`（调用方因此**一个字符都不画**，更不会出现 `0:00` 那种冒充）；
+ * - `<= 0` ⇒ 也回 `null`：`0` 毫秒的语音不存在，把服务端的一个异常取值显示成 `0:00`
+ *   就是拿一个编出来的数字冒充事实；
+ * - **不足一秒**（`1..999`）⇒ 也回 `null`：`m:ss` 只能把它显示成 `0:00`，而 `0:00` 与
+ *   「没有时长」在屏幕上是同一个样子——与其显示一个看起来像没读到的时间，不如什么都不显示
+ *   （渠道也不会真的发这种语音）；
+ * - 不设上限：语音消息不会长到需要小时制，超过 99 分钟就照实显示 `124:03`（**不折算**成
+ *   「2:04:03」——那是另一种自己发明的表达）。
+ */
+fun voiceDurationLabel(durationMs: Int?): String? {
+    if (durationMs == null || durationMs < 1_000) return null
+    val totalSeconds = durationMs / 1000
+    val minutes = totalSeconds / 60
+    val seconds = totalSeconds % 60
+    return "$minutes:${seconds.toString().padStart(2, '0')}"
+}
+
+/**
+ * 语音形态**之外**还要多说的一句话；不需要多说就回 `null`（纯函数）。
+ *
+ * 只对 `status == "empty"` 且**正文为空**时成立：
+ * - `transcribed`：正文**就是**转写文本，多说一句都是噪声（所以什么都不补）；
+ * - `empty` 而正文非空：正文本身就是要说的话，此时再说「没有识别出文字」会**自相矛盾**
+ *   （这一形状按契约不该出现，但真出现了也不该让屏幕上出现两句互相顶嘴的话）；
+ * - 未知 `status`（含空串）：**不猜**，只显示正文。
+ *
+ * ⚠️ `failed` 那一态**不走这里**（它连语音形态都不画）：正文由服务端给，本端另加一行小标
+ * （[voiceFallbackNote]）。本函数仍对 `failed` 回 `null`，因为「语音形态旁边多说一句」这个位置
+ * 对那一态根本不存在。
+ */
+fun voiceNote(status: String, content: String): String? =
+    if (status == VoiceStatus.EMPTY && content.isBlank()) VOICE_EMPTY_NOTE else null
+
+/**
+ * `status == "failed"` 时那行灰色小标该写什么；别的状态回 `null`（纯函数）。
+ *
+ * 两段拼成一句话：**固定前半句**（[VOICE_FALLBACK_NOTE]，说的是本端能确定的事实）+ 服务端给的
+ * `fallbackReason`（**一个字符都不改**，原样放进括号里）。
+ *
+ * ## 为什么原样放、不做映射
+ * `fallbackReason` 的取值集合**后端还没定**（`devdocs/02` 里我们已经问了「是闭集还是自由文本」，
+ * 尚未答复；契约 v0.98 的正式回执也还没到）。在有答案之前，本端**不猜**它是不是闭集、更不替它
+ * 编一套友好文案：认不出的取值被映射成一句话，比原样显示更难排查——用户报「显示成『语音超时』」
+ * 时，我们连服务端到底给了什么都不知道。原样显示，最坏是屏幕上出现一个 `tts_timeout` 这样的词，
+ * 而它**正是**我们和后端对账时要的那个字符串。
+ *
+ * ## `fallbackReason` 缺席时
+ * 只有固定前半句。这一档同时是**空正文 + `failed`** 的兜底：这一态的消息正文按契约应当非空
+ * （服务端那行诚实提示 / 降级后的原文本），但本端**不靠**这条保证——真收到一条空正文的 `failed`
+ * 行时，屏幕上至少还有这行小标，而不是一个**什么都没有**的空白（那正是空气泡那种最糟的呈现）。
+ */
+fun voiceFallbackNote(voice: VoiceDto?): String? {
+    if (voice == null || voice.status != VoiceStatus.FAILED) return null
+    val reason = voice.fallbackReason?.takeIf { it.isNotBlank() } ?: return VOICE_FALLBACK_NOTE
+    return "$VOICE_FALLBACK_NOTE（$reason）"
+}
+
+/**
+ * 把服务端给的**相对路径** [url] 接到当前服务器地址 [baseUrl] 上（纯函数）。
+ *
+ * 契约明写 `url` 是唯一的派生字段（`/api/v1/media/<name>`），**客户端绝不自己拼路径**——所以
+ * 本函数只做「保留 path、换成当前 host」这一件事，与 [ImageHostRebase] 同一取向
+ * （图片那条要换的是**别人给过的绝对地址**里的 host，这里要接的是**服务端给的相对路径**）。
+ *
+ * 判据取最小容忍度，任何一条不满足就回 `null`（调用方据此如实报「暂时播不了」，**绝不**
+ * 退回「自己拼一条 `/api/v1/media/<name>`」——那正是契约禁止的那件事）：
+ * - [url] 必须以 `/api/v1/media/` 开头，且后面**恰好**是一段名字：非空、不是 `.` / `..`、
+ *   不含 `/` `\` `%` `?` `#` 与 NUL；
+ * - [baseUrl] 必须能解出 `scheme://authority`（空串 / 没有 host 都解不出）。
+ *
+ * 用的是 [baseUrl] 的 scheme + authority（所以 `http → https`、端口变更都跟着走），**不用**
+ * baseUrl 里的路径：这条地址挂在根路径上，部署形态本来就没有路径前缀这一说。
+ */
+fun voiceMediaUrl(url: String, baseUrl: String): String? {
+    val name = url.removePrefix(MEDIA_PREFIX)
+    if (!url.startsWith(MEDIA_PREFIX) || !isSafeMediaName(name)) return null
+    val origin = originOf(baseUrl) ?: return null
+    return origin + url
+}
+
+/**
+ * 取字节失败时的文案（纯函数，可单测）。
+ *
+ * 与 `documentLoadFailureMessage` / `imageLoadFailureMessage` 同一纪律：服务端能说清的用它的
+ * 原话，本端能分类的分开说，**绝不把失败渲染成「静音」**——一条点了没反应的语音消息在用户眼里
+ * 与「坏了」没有区别。
+ *
+ * 三档本地失败分开写，因为它们要用户做的事不一样：地址拼不出来 = 本端环境不对（重新登录 / 换
+ * 服务器）；太大 = 这条本端处理不了；缓存写不进去 = 本端的问题，重试多半还是这样。
+ */
+fun voicePlaybackFailureMessage(e: Throwable): String = when (e) {
+    is VoiceUrlUnavailableException -> "当前服务器地址不可用，暂时播不了这条语音"
+    is VoiceTooLargeException -> "这条语音太大，本机放不了"
+    is DocumentCacheUnavailableException -> "本地缓存不可用，暂时播不了这条语音"
+    is CyreneException -> when {
+        // ⚠️ 刻意**不**走 `toDocumentFailure()`：那个映射只认文档那四个码（`document_not_found`），
+        // `media_not_found` 在它眼里是「未知码」⇒ 会把「服务端上已经没有这条语音了」说成
+        // 「语音加载失败，media not found」。这一档本端说得准，就说得准一点。
+        e.error.isMediaNotFound() -> "服务端上已经没有这条语音了"
+        else -> "语音加载失败，" + e.error.userMessage
+    }
+
+    else -> "语音加载失败，请稍后重试"
+}
+
+/** 服务端对「名字非法 / 穿越 / 不存在」统一回这一个码（U19：**不区分**，不给探测面）。 */
+private const val MEDIA_NOT_FOUND_CODE = "media_not_found"
+
+private fun CyreneError.isMediaNotFound(): Boolean =
+    this is CyreneError.Server && code == MEDIA_NOT_FOUND_CODE
+
+/** 服务端相对路径的前缀（契约 §1.2 U19）。 */
+private const val MEDIA_PREFIX = "/api/v1/media/"
+
+/**
+ * 媒体名是不是「恰好一段」：不许有分隔符、百分号编码、查询串，也不许是 `.` / `..`。
+ *
+ * 与 `ImageHostRebase` 的同名判据同一条理由：这个字符串来自**别人给的**数据，
+ * 看不懂的形态就不该被我们拼进一条请求地址。
+ */
+private fun isSafeMediaName(name: String): Boolean {
+    if (name.isEmpty() || name == "." || name == "..") return false
+    return name.none { it == '/' || it == '\\' || it == '%' || it == '?' || it == '#' || it == '\u0000' }
+}
+
+/** `scheme://authority`；解不出来回 `null`（空串 / 没有 host / 不是 http(s) 都是解不出来）。 */
+private fun originOf(baseUrl: String): String? {
+    val rest = when {
+        baseUrl.startsWith("http://", ignoreCase = true) -> baseUrl.substring("http://".length)
+        baseUrl.startsWith("https://", ignoreCase = true) -> baseUrl.substring("https://".length)
+        else -> return null
+    }
+    val end = rest.indexOfFirst { it == '/' || it == '?' || it == '#' }.let { if (it < 0) rest.length else it }
+    val authority = rest.substring(0, end)
+    if (authority.isBlank()) return null
+    return baseUrl.take(baseUrl.length - rest.length) + authority
+}
@@ -0,0 +1,93 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * `voice_output` 的**判据**（纯函数，可穷举单测）：契约 v0.96 §3.15 下行帧。
+ *
+ * 帧形状（后端 `回执三十六`）：
+ * ```json
+ * { "type": "voice_output",
+ *   "data": { "audio": "<base64>", "format": "wav", "text": "...", "reply": "她的话",
+ *             "sessionId": "web", "deviceId?": "...", "provider?": "silent|emotiontts|..." } }
+ * ```
+ *
+ * ## `text` 与 `reply` 是两个东西（本端怎么用）
+ * - **[text]**：这一轮**转写出来的话**——也就是我们那段音频被识别成什么。它与
+ *   `voice_input.text`（「已自行转写则跳过 STT」）同一个键名、同一个语义，只是方向相反。
+ * - **[reply]**：**她说的话**（音频念的就是它），也就是用户真正要听/要看的那一句。
+ *
+ * 于是「屏幕上该显示哪一句」的答案是 [voiceReplyText]：**`reply` 优先**，它缺席时才退到 `text`
+ * （宁可显示转写也不显示空白），两者都缺席就什么都不显示（绝不编一句）。
+ *
+ * ## `provider` 是**降级信号**，不是装饰
+ * `provider == "silent"` = 这一轮**没有真音频**（`audio` 空，但 `text` / `reply` 有）。
+ * 契约明写「UI 别把它画成播放器」——画了就是一个点下去必然失败的按钮（与接收侧
+ * `voiceAudio` 的「四个键不齐就不画播放控件」同一条纪律）。
+ *
+ * 除此之外 `audio` 空白也按「没有音频」处理（[voiceOutputHasAudio]）：契约说 silent 时
+ * `audio` 为空，反过来「空 audio + 没给 provider」也绝不能画出一个播放器。
+ *
+ * ## 它与 `voice` 键那条（接收侧放别人发来的语音）**互不相干**
+ * 见 [isVoiceMessage]/[voiceAudio]：那是消息 DTO 的历史副本，这里是**本端刚发出去的那一段**的
+ * 实时应答——两者不共用判据，共用只会把两套字段口径搅在一起。
+ */
+
+/** `provider` 里那个**降级档**的取值（契约 v0.96）。 */
+object VoiceProvider {
+
+    /** 这一轮**没有真音频**（`audio` 空、`text`/`reply` 有）。 */
+    const val SILENT: String = "silent"
+}
+
+/**
+ * 这一帧是不是「没有真音频」那一档（纯函数）。
+ *
+ * 只认字面 `silent`（忽略首尾空白与大小写：它是机器可读码，不是文案）。未知取值一律**不当**
+ * silent——那是另一个 provider，`audio` 在不在由 [voiceOutputHasAudio] 按字节判，不靠猜。
+ */
+fun isSilentVoiceProvider(provider: String?): Boolean =
+    provider?.trim().equals(VoiceProvider.SILENT, ignoreCase = true)
+
+/**
+ * 这一轮**有没有真音频**（纯函数）：`provider != silent` **且** `audio` 非空白。
+ *
+ * 两个条件都不许省：silent 档的 `audio` 契约上就是空的（万一真给了也不算数，因为服务端已经
+ * 明说这一轮没发音），而非 silent 档的 `audio` 也可能因为编码失败缺席。
+ */
+fun voiceOutputHasAudio(audio: String?, provider: String?): Boolean =
+    !isSilentVoiceProvider(provider) && !audio.isNullOrBlank()
+
+/**
+ * 屏幕上该显示的那一句（纯函数，见文件头「`text` 与 `reply` 是两个东西」）。
+ * `reply` 非空白 ⇒ 它；否则 `text` 非空白 ⇒ 它；都没有 ⇒ `null`（一个字符都不显示）。
+ */
+fun voiceReplyText(reply: String?, text: String?): String? =
+    reply?.takeIf { it.isNotBlank() } ?: text?.takeIf { it.isNotBlank() }
+
+/**
+ * 这张卡片下面要补的那一句（纯函数：不需要补时回 `null`）。
+ *
+ * 两档**都要解释，但说的不是同一件事**：
+ * - [silent]：**服务端**这一轮没有真音频（`provider == "silent"`）⇒「她只回了文字」。不解释的话，
+ *   用户按着麦克风说话、回来的却是一段文字，分不清「她选择只回文字」与「播放器坏了」。
+ * - 有音频却没落地（[hasAudioFile] 为假）：那是**本端**解码 / 写缓存失败 ⇒ 说「这段语音本机没
+ *   准备好」，绝不把本机的故障说成「她只回了文字」（那是替服务端下了一个它没下的结论）。
+ */
+fun voiceReplyNote(silent: Boolean, hasAudioFile: Boolean): String? = when {
+    silent -> VOICE_SILENT_NOTE
+    !hasAudioFile -> VOICE_REPLY_LOCAL_UNAVAILABLE_NOTE
+    else -> null
+}
+
+/**
+ * 「这一轮没有音频」的说明。刻意说清是**服务端**这一轮没给音频（`provider` 的降级信号），
+ * 而不是「本机播不了」——后者会把人引向「换个播放器」这种无用的动作。
+ */
+const val VOICE_SILENT_NOTE: String = "这一轮她只回了文字，没有语音"
+
+/**
+ * 「音频有、但本机没准备好」的说明（解码 / 写缓存失败）。
+ *
+ * 与 [VOICE_SILENT_NOTE] 分开是必须的：这一档的真相是**本端**的问题，而文字照样在
+ * （[voiceReplyText] 已经把它取出来了），所以用户至少还能读到她说的话。
+ */
+const val VOICE_REPLY_LOCAL_UNAVAILABLE_NOTE: String = "这段语音本机没能准备好，先看文字"
@@ -0,0 +1,121 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 语音播放的**状态**（纯数据，可单测）。
+ *
+ * ## 为什么要有它，而不是让每个气泡各自 `remember { mutableStateOf(false) }`
+ * 同一时刻**只能有一条语音在响**（一台设备一个喇叭，两条语音叠着放一定是 bug），而
+ * 「哪一条在响」是**跨气泡**的事实：用户点了另一条，前一条必须停下来并释放解码器。
+ * 于是这份状态由**一条播放通道**持有，气泡只是它的视图。四个态刻意只有四个：
+ *
+ * - [Idle]：什么都没在放（也是「停下来之后」唯一的终点）；
+ * - [Loading]：字节在取（首次播放要先下载；第二次起走本地缓存，一闪而过）；
+ * - [Playing]：真的在响（`MediaPlayer` 已经 `start()` 过，还没走完 / 还没被停）；
+ * - [Failed]：**这一次尝试**没成功，[Failed.message] 是给用户看的那句话。
+ *
+ * [Failed] 携带的是**这条消息**的失败（不是全局横幅）：用户点的是这一条，出问题的是这一条。
+ * 它**不粘**：再点一次就从 [Loading] 重新开始（见 [pressed]）。
+ *
+ * ## 每条转换都带 `messageId`，因为回调会迟到
+ * `MediaPlayer` 的回调（prepared / completion / error）与取字节的协程都可能**在用户已经改主意
+ * 之后**才到达。所以每一次转换都要**比对目标**：过期的回调**一个都不许**改状态
+ * （[prepared] / [failed] / [finished] 的同一条纪律）。这不是防御性编程的洁癖——
+ * 少了它就会出现「播放器已经换了、界面还显示上一条在响」。
+ */
+sealed interface VoicePlaybackState {
+
+    /** 没有被这条通道占着的消息（初始态，也是停 / 出错 / 放完之后的终点）。 */
+    data object Idle : VoicePlaybackState
+
+    /** 正在取这一条的字节（下载 / 读缓存）。 */
+    data class Loading(val messageId: String) : VoicePlaybackState
+
+    /** 这一条正在响。 */
+    data class Playing(val messageId: String) : VoicePlaybackState
+
+    /** 这一条的上一次尝试没成；[message] 是给用户看的那句话（见 `voicePlaybackFailureMessage`）。 */
+    data class Failed(val messageId: String, val message: String) : VoicePlaybackState
+}
+
+/**
+ * 这条消息此刻正被这条播放通道占着吗（[VoicePlaybackState.Loading] 或
+ * [VoicePlaybackState.Playing]）。
+ *
+ * [VoicePlaybackState.Failed]**不算**：它表示这条已经不在放，用户再点一下就是「重试」。
+ */
+fun VoicePlaybackState.isActiveFor(messageId: String): Boolean = when (this) {
+    is VoicePlaybackState.Loading -> this.messageId == messageId
+    is VoicePlaybackState.Playing -> this.messageId == messageId
+    else -> false
+}
+
+/** 这条消息**正在响**吗（只认 [VoicePlaybackState.Playing]，加载中不算）。 */
+fun VoicePlaybackState.isPlayingFor(messageId: String): Boolean =
+    this is VoicePlaybackState.Playing && messageId == this.messageId
+
+/**
+ * 这条消息**正在取字节**吗（只认 [VoicePlaybackState.Loading]）。
+ *
+ * 与 [isPlayingFor] 分开是必须的：「正在加载」与「正在响」对用户是两件事，界面上那句
+ * 「加载中…」只能在**真的在加载**时出现——混着用会让一条 30 秒的语音在整段播放期间都写着
+ * 「加载中…」。
+ */
+fun VoicePlaybackState.isLoadingFor(messageId: String): Boolean =
+    this is VoicePlaybackState.Loading && messageId == this.messageId
+
+/**
+ * 这条消息上一次尝试失败时那句提示；不是它 / 没失败过就回 `null`（气泡据此决定画不画那一行）。
+ */
+fun VoicePlaybackState.failureOf(messageId: String): String? =
+    (this as? VoicePlaybackState.Failed)?.takeIf { it.messageId == messageId }?.message
+
+/**
+ * 用户点了这条消息的播放 / 暂停。
+ *
+ * - 点的是**正在放 / 正在加载的那一条** ⇒ 回 [VoicePlaybackState.Idle]（= 停，调用方据此停下
+ *   并释放；「再点一下取消」对加载中同样成立——用户不该被一个慢下载困住）；
+ * - 点的是别的（或上一次失败的）那一条 ⇒ 换成它的 [VoicePlaybackState.Loading]。
+ *
+ * 有一条**调用方职责**不在状态里：进入 [VoicePlaybackState.Loading] 之前必须把上一条真的停掉
+ * （见 `ui.chat.VoicePlayer.toggle`）。纯函数只说「状态应该变成什么」。
+ */
+fun VoicePlaybackState.pressed(messageId: String): VoicePlaybackState =
+    if (isActiveFor(messageId)) VoicePlaybackState.Idle else VoicePlaybackState.Loading(messageId)
+
+/**
+ * 字节到手、`MediaPlayer` 已经 `start()` 过：`Loading(同一条)` ⇒ `Playing(同一条)`。
+ *
+ * 目标不对（用户已经点了别的 / 点了停）或当前不是 `Loading` 时**原样返回**——迟到的回调不许
+ * 把界面从「另一条在响」拽回来。
+ */
+fun VoicePlaybackState.prepared(messageId: String): VoicePlaybackState =
+    if (this is VoicePlaybackState.Loading && this.messageId == messageId) {
+        VoicePlaybackState.Playing(messageId)
+    } else {
+        this
+    }
+
+/**
+ * 取字节 / 起播失败：`Loading(同一条)` ⇒ `Failed(同一条, message)`；其余情况原样返回。
+ *
+ * 只从 [VoicePlaybackState.Loading] 出发是刻意的：**正在响的那一条**不会被一个迟到的失败
+ * 回调说成失败（`Playing` 阶段的解码错误走 [finished] 那条路，由播放器自己先停下再报）。
+ */
+fun VoicePlaybackState.failed(messageId: String, message: String): VoicePlaybackState =
+    if (this is VoicePlaybackState.Loading && this.messageId == messageId) {
+        VoicePlaybackState.Failed(messageId, message)
+    } else {
+        this
+    }
+
+/** 放完了：`Playing(同一条)` ⇒ [VoicePlaybackState.Idle]（播完就回初始外观，不留痕迹）。 */
+fun VoicePlaybackState.finished(messageId: String): VoicePlaybackState =
+    if (isPlayingFor(messageId)) VoicePlaybackState.Idle else this
+
+/**
+ * 停下来（用户点了停 / 换了另一条 / 离开会话 / 组件销毁）⇒ [VoicePlaybackState.Idle]。
+ *
+ * **任何态都收**，包括 [VoicePlaybackState.Failed]：失败那句话的生命周期与这一次尝试绑定，
+ * 换了目标或页面重进就不该再挂着。
+ */
+val VoicePlaybackState.silenced: VoicePlaybackState get() = VoicePlaybackState.Idle
@@ -0,0 +1,167 @@
+package top.yeij.cyrene.domain.chat
+
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.parse.ParsedBubble
+import top.yeij.cyrene.domain.parse.parse
+
+/**
+ * 「把这条消息念出来」这条路上，**本端要说的那几句话**，以及失败该分到哪一档。
+ *
+ * 这个文件里全是纯函数 / 常量，没有 Android、没有网络、没有状态：单测直接调（见
+ * `VoiceSpeakTest`）。真正的取字节在 `data.voice.SpeechClient`，播放复用 `ui.chat.VoicePlayer`。
+ */
+
+/**
+ * 从一条消息解析出来的气泡里抽出**要念的那段纯文本**。
+ *
+ * ## 为什么只念 `body`
+ * [ParsedBubble] 把一条气泡拆成三段：`head`（说话人抬头）、`body`（正文）、`tail`（旁白 / 动作）。
+ * 念出来时**只念正文**：
+ * - `head` 是「昔涟：」这种抬头，念出来像在念字幕；
+ * - `tail` 里的旁白（`*她笑了笑*`）与动作（`[动作]`）是**舞台指示**，语音合成念它只会变成一串
+ *   莫名其妙的字面量。
+ *
+ * ## 为什么按 `\n` 拼、且空就回 `null`
+ * 一条消息可能被切成多个气泡（连续说两段）；`\n` 让合成的停顿落在段落之间，比空格自然。
+ * 全都为空（纯附件消息、纯旁白消息、或者解析完什么都不剩）时回 `null` —— 调用方据此**不显示**
+ * 朗读入口，而不是让用户点一个必然拿到 `400` 的按钮。
+ *
+ * 取完 `trim`：首尾空白会变成合成音频开头 / 结尾的静音，没有任何用处。
+ */
+fun ttsTextOf(bubbles: List<ParsedBubble>): String? =
+    bubbles.asSequence()
+        .map { it.body }
+        .filter { it.isNotBlank() }
+        .joinToString("\n")
+        .trim()
+        .takeIf { it.isNotEmpty() }
+
+/**
+ * 一条消息（`content` + `mode`）里**要念的那段文本**；`null` = 没有可念的正文。
+ *
+ * 这是「这条消息能不能朗读」的**唯一判据**：`ChatViewModel.speak` 用它决定发不发请求，
+ * `MessageBubble` 用它决定画不画那枚图标。两处必须是同一个答案 —— 画了却发不出去、或者能发
+ * 却不给入口，都是 bug。
+ *
+ * ## 为什么要看 `mode`
+ * `chat`（或缺席）是「按 markup 切气泡的聊天式渲染」；其余 mode 下气泡里放的是**原文**，
+ * 一条 markup 都不解析（`MessageBubble` 就是这么画的）。朗读要念的显然也是**用户看到的那段字**：
+ * - 聊天式 ⇒ 走 [ttsTextOf] 剥掉抬头 / 旁白；
+ * - 其余 ⇒ 原文原样，只 `trim`。
+ *
+ * 判据本身与 `MessageBubble` 里那句 `isChat` 一字不差，刻意留在这里一份：多写一份就会出现
+ * 「界面按一种切法、朗读按另一种切法」的分叉。
+ */
+fun ttsTextOf(message: HistoryMessageDto): String? =
+    if (message.mode.isNullOrBlank() || message.mode == "chat") {
+        ttsTextOf(parse(message.content).filterNot { it.isEmpty })
+    } else {
+        message.content.trim().takeIf { it.isNotEmpty() }
+    }
+
+/**
+ * 一次朗读失败该归到哪一档 —— 判据只看**服务端到底说了什么**，不看 HTTP 码的表面。
+ *
+ * ## 为什么分两档
+ * 这两档对用户的意思完全不同，混成一句就等于什么都没说：
+ * - [Soft]：**这会儿**没读出来（网络断了、令牌过期、网关抽风）。过一会儿再点是**有意义**的，
+ *   所以文案只陈述事实、不诱导、也不吓人；
+ * - [Unconfigured]：**配置**上就没这条路的。服务端明说了是哪种缺（`tts_persona_unmapped`
+ *   没有发音人映射 / `tts_no_character` 连生效人格都没有），重试**永远不会**成功 —— 所以文案要说
+ *   清「缺什么」，并且**不提重试**（提了就是在骗人点）。
+ */
+sealed interface TtsFailure {
+
+    /** 要说给用户的那一句话。 */
+    val message: String
+
+    /** 再点一次**可能**有用吗？（[Unconfigured] 恒 `false`：重试永远不会成功。） */
+    val retryable: Boolean
+
+    /** 这会儿没读出来：不解释原因（本端确实不知道是哪一段断了），也不诱导重试。 */
+    data object Soft : TtsFailure {
+        override val message: String = TTS_SOFT_FAILURE_MESSAGE
+        override val retryable: Boolean = true
+    }
+
+    /**
+     * 服务端明说了配置缺一块。[code] 就是服务端那个错误码（原样留着，排查时对得上号）。
+     */
+    data class Unconfigured(val code: String) : TtsFailure {
+        override val message: String = when (code) {
+            TTS_CODE_PERSONA_UNMAPPED -> TTS_PERSONA_UNMAPPED_MESSAGE
+            TTS_CODE_NO_CHARACTER -> TTS_NO_CHARACTER_MESSAGE
+            // 兜底：服务端回了一个本端还不认识的「配置缺失」类错误码。不猜它的意思，
+            // 但也不装作是临时故障——它毕竟带着一个明确的 code。
+            else -> TTS_UNCONFIGURED_MESSAGE
+        }
+        override val retryable: Boolean = false
+    }
+}
+
+/**
+ * 把一次朗读的异常分到 [TtsFailure] 两档里。
+ *
+ * 只有「服务端明确回了一个**配置缺失**类的 `code`」才进 [TtsFailure.Unconfigured]；其余一切
+ * ——网络失败、解析失败、401（令牌过期，续期后还能用）、`voice_unavailable` / `tts_failed` /
+ * `tts_empty`（对面这会儿不行，不是本端的配置问题）——都进 [TtsFailure.Soft]。
+ *
+ * `tts_empty`（静默空音频）刻意归到柔和档：那是**这一次**合成出来的东西不能用，换个时间再试
+ * 完全可能成功，说成「配置没配好」就是错的。
+ */
+fun ttsFailureOf(error: Throwable): TtsFailure {
+    val cause = (error as? CyreneException)?.error ?: return TtsFailure.Soft
+    return when (cause) {
+        is CyreneError.Server -> when (cause.code) {
+            TTS_CODE_PERSONA_UNMAPPED,
+            TTS_CODE_NO_CHARACTER,
+            -> TtsFailure.Unconfigured(cause.code)
+
+            else -> TtsFailure.Soft
+        }
+
+        is CyreneError.Unauthorized -> TtsFailure.Soft
+        is CyreneError.Local -> TtsFailure.Soft
+    }
+}
+
+/**
+ * 朗读在某一条播放通道上的**键**：`tts:<messageId>`。
+ *
+ * 播放通道只有一条（`ui.chat.VoicePlayer` 的那个实例，与语音副本共用），所以键必须与语音副本
+ * （键 = `voice` 的 `messageId`）分得开：前缀就是那道分界线。同一条消息的朗读与它的语音副本
+ * 因此**互斥**（点其中一个会停掉另一个）——这是对的，同一时刻只该有一个声音。
+ */
+fun ttsClipIdOf(messageId: String): String = TTS_CLIP_PREFIX + messageId
+
+/** 朗读入口那枚图标的读屏名字（也是设备验收时 `uiautomator` 的 `content-desc`）。 */
+const val TTS_SPEAK_DESCRIPTION: String = "朗读这条消息"
+
+/** 正在朗读时那枚图标的读屏名字（点它 = 停）。 */
+const val TTS_STOP_DESCRIPTION: String = "停止朗读"
+
+/** 正在取合成音频时那枚图标的读屏名字。 */
+const val TTS_LOADING_DESCRIPTION: String = "正在准备朗读"
+
+/** 柔和档：这会儿没读出来。**不说原因**（本端确实不知道断在哪一段），也不提重试。 */
+const val TTS_SOFT_FAILURE_MESSAGE: String = "这会儿没能把这段读出来"
+
+/** `tts_persona_unmapped`：人格有，但这个人格没有配发音人。 */
+const val TTS_PERSONA_UNMAPPED_MESSAGE: String = "这个角色还没配好发音人"
+
+/** `tts_no_character`：连生效人格都没有（会话没绑定、也没有全局默认人格）。 */
+const val TTS_NO_CHARACTER_MESSAGE: String = "这个会话还没有配好发音人"
+
+/** 服务端回了配置缺失类错误码、但本端还不认识那一个时的兜底文案。 */
+const val TTS_UNCONFIGURED_MESSAGE: String = "这个角色还没有配好朗读的发音人"
+
+/** 朗读播放通道的键前缀（与语音副本的键 `messageId` 区分开）。 */
+const val TTS_CLIP_PREFIX: String = "tts:"
+
+/** 服务端错误码：人格没有发音人映射。 */
+const val TTS_CODE_PERSONA_UNMAPPED: String = "tts_persona_unmapped"
+
+/** 服务端错误码：连生效人格都没有。 */
+const val TTS_CODE_NO_CHARACTER: String = "tts_no_character"
@@ -14,15 +14,48 @@ import kotlin.math.min
 *   - `<p>…</p>`：每个完整块 = 一条独立气泡；无完整 `<p>` 时回退按空行 `\n\s*\n` 切分；
 *     单个 `\n` 是句内换行，绝不切分。未闭合的 `<p>` 不构成块，按普通文本处理（流式下会先缓存）。
 *     `<p>` 之外的非空白正文不会被丢弃：并入相邻气泡（若只是旁白/空白则依附之，否则自成一气泡）。
+ *   - `<br>`（`<br>` / `<br/>` / `</br>` 三种写法等价，大小写不敏感，属性不解析）：**与 `<p>` 同级
+ *     的气泡/消息分隔符**（契约 v0.89 的更正：`回执三十一`「对消息内的 `<br>` 始终处理为多条消息
+ *     隔断」）。它**不是行内标签**：`<p>甲<br>乙</p>` ⇒ 两条气泡，`甲<br>乙`（无 `<p>`）⇒ 同样两条；
+ *     中间的空气泡照旧丢弃（`<p>甲<br><br>乙</p>` ⇒ `甲`、`乙`）。切分在 [tokenize] 的**段/块这一层**
+ *     完成（[appendRegion]），所以行内解析层（`InlineMarkup`）几乎看不见它。
+ *     ⚠️ `回执三十三 §三②` 把「**始终**分隔」收紧了：**只有普通文本层的 `<br>` 才分隔**——
+ *     `<code>` / `<action>` / `<narration>` **内部**的不分隔（[appendRegion] 的保护区，
+ *     口径与理由写在它和 [protectedSpans] 的 KDoc 里）。
 *   - `<action>…</action>` / `<narration>…</narration>`：旁白/动作，不独立成气泡，依附气泡：
 *     首部连续块 → 挂气泡上方（head）；尾部连续块 → 挂下方（tail）；夹在正文中间的块 → 上提到 head。
+ *     注记内部**不做行内渲染**（既有口径），所以里面的 `<br>` 与 `<b>` 一样只是字面文本。
 *   - 漂移兼容：全角 `＊…＊`（无关键词时要求去空白后 ≤40 字符且不含换行 → action）；
 *     半角 `*…*` 仅当以 动作/旁白/内心/神态/轻声 开头才算旁白，否则保持普通文本（不吞 Markdown 强调）。
 *     关键词 旁白/内心 → narration，其余 → action。
- *   - 未闭合/畸形的标签一律回落为普通文本，绝不抛异常。
+ *   - 行内标签（`InlineMarkup.kt`，契约 v0.89）：`<b>`/`<strong>`、`<i>`/`<em>`、`<code>`、`<u>`
+ *     （**六项**标签名——`u` 由 `回执三十三 §一` 加回、`s` 仍不在内），成对才认、**标签名大小写不敏感**、
+ *     **属性一律不解析**（`<b class=x>` 就是粗体）、白名单外按纯文本原样显示、
+ *     **结构不平衡（未闭合 / 落单闭标签 / 交错）⇒ 该气泡的正文整段降级为原文**
+ *     （口径与理由见 `parseInlineMarkup`）。
+ *     它在**段落与 `<br>` 都定稿之后**才做（[toBubble] 里对最终正文做一次，**逐气泡各自一份**），
+ *     所以既不参与、也改不动上面的分段与归属。渲染文本落 `body` + `runs`，而片段 `parts` 仍是
+ *     逐字原文——编辑框、搜索片段、通知文案读的都是 `parts`，那些地方一个字都不许改。
+ *   - 落单标签容错：服务端确实会产出不配对的段落标签（实测形态 `<p><p>正文</p>`：多一个 `<p>`、
+ *     只有一个 `</p>`），块外也可能出现孤立的旁白标签。这类标签一律**剥掉**，绝不落进正文——
+ *     它们本就是服务端产出的标记、不是她说的话；渲染成正文等于往气泡里塞一串用户既看不懂、
+ *     也改不掉的字符，而剥掉只是少显示几个本就不该出现的字符，正文一个字都不动。
+ *     这只是客户端的容错，不代表服务端这样发是对的。
+ *     判据（[stripLooseTags]）分两种情形：消息里**已有完整块**时，段落结构已被完整块定死，块内
+ *     块外多出来的每个 `<p>` / `</p>`、以及块外孤立的旁白标签，都是冗余噪声，一律剥掉（块内的
+ *     落单旁白标签例外，见最后一条）；消息里**一个完整块都没有**时，按上一条整段回落字面文本，
+ *     只再剥两类连「被截断的结构」都算不上的东西：落单的 `</p>`，与后面什么都没有的空开标签。
+ *     只认「确定是标签」的形状：`<p>` / `<p 属性>` / `</p>` / `<action>` 等。`1 < 2`、`<3`、
+ *     `a<b`、`<p2>`、`<P>`（词表只有小写，与 `MessageEditText` 同一口径）、`<p`（残缺，没有 `>`）
+ *     都原样保留——见到 `<` 就吃，才是真正会丢字的那种错。
+ *   - 未闭合/畸形的其余标签一律回落为普通文本，绝不抛异常。块内没配对的 `<action>` / `</action>`
+ *     也保持字面文本，这是既有契约（`unclosedActionFallsBackToText` / `strayClosingTagStaysText`）。
 *
 * `ParsedBubble` 结构（每条气泡渲染一个）：
- *   - `body`  ：气泡正文（仅 Text 部分按原顺序拼接后 trim），已剔除全部旁白/动作块；
+ *   - `body`  ：气泡正文的**渲染文本**（仅 Text 部分按原顺序拼接后 trim，再消费掉行内标签：
+ *     白名单标签字符已去掉，白名单外与属性照旧逐字留着），已剔除全部旁白/动作块；
+ *     整段只有标记没有字、或行内标签**结构不平衡**时回落/降级为字面原文；
+ *   - `runs`  ：`body` 的行内样式切分（非空时拼起来就是 `body`；空列表 = 按字面画）；
 *   - `parts` ：该气泡按原始顺序解析出的全部片段（Text / Action / Narration），供下钻使用；
 *   - `head`  ：要渲染在气泡上方的旁白/动作块（首部块 + 中间块「上提」）；
 *   - `tail`  ：要渲染在气泡下方的旁白/动作块（尾部连续块）。
@@ -34,9 +67,28 @@ import kotlin.math.min
 *     因此 `finish() == parse(全部 delta 拼接)` 恒成立（逐字符/任意切分均一致）。
 *   - 未确定片段从以下最早位置开始整体扣留，不产出半截结果：
 *       1) 未闭合的 `<action>` / `<narration>` / `<p>` 开标签（从该开标签起扣留）；
- *       2) 尾部残缺标签（如 `<act`、`</act`、`<p`），仅当它可能继续补全为合法标签时才扣留；
+ *          行内开标签同样入栈扣留（词表见 [INLINE_TAG_NAMES]，判据见 [parseInlineTag]）：不扣的话
+ *          中间态会把 `<b>` 当字面吐上屏（`日落 <b>18`）、等 `</b>` 到了又被吃掉，屏幕上已经显示过的
+ *          两个字就改口了。**大小写与属性也走同一份判据**（v0.89）：`<B class=x>` 在扣留侧同样是
+ *          开标签，否则 `日落 <B class=x>18` 会先按字面吐上屏、收口时再变成粗体。
+ *          `<br>` 是分隔符、不成对，**不入栈**（入了就永远弹不出来）；它只在残缺（`<br`、`<br/`、
+ *          `</br`）时按词表扣留（[isPotentialTagPrefix] → [couldBeTagName]），完整的 `<br>` 直接放行
+ *          ——分隔符一出现，前缀就已经可解析了。
+ *          **保护区内的 `<br` 另外还有一道**：`<code>` / `<action>` / `<narration>` 的开标签本来就在
+ *          栈里，所以整个作用域（连同里面还没写完的 `<br`）一起被扣到闭合为止，残缺的 `<br` 不会
+ *          在半截作用域里先露一次脸（由 `streamingWithholdsPartialLineBreakInsideProtectedScopes` 钉着）。
+ *       2) 尾部残缺标签（如 `<act`、`</act`、`<p`、`<B`、`<br`），仅当它可能继续补全为合法标签时才扣留；
 *       3) 最近一个完整标签之后（自由文本区）的孤立全角 `＊`；
 *       4) 自由文本区中可能开启关键词半角星号（如 `*动`）的孤立 `*`。
+ *   - 落单标签的剥离**不需要**额外的扣留规则，这是「剥标签与扣留共用同一组标签正则」的直接结果：
+ *     扣留点取「第一个没闭合的开标签」，而落在前缀里的每个 `<p>` / `<action>` 开标签必定在
+ *     **同一个前缀内**配到闭合标签（否则它就是那个没闭合的，扣留点会落在它前面）。所以
+ *     「这个标签是不是落单的」在它被产出的那一刻就已经定死，中间态剥掉、收口时也不用再改口。
+ *   - 反过来放宽扣留是不行的：把重复的 `<p><p>` 当「外层冗余」让前缀继续推进，`<p>甲<p>乙`
+ *     就会在中间态把 `<p>甲` 当字面文本吐上屏，等 `</p>` 到了又变成 `甲乙`——字会跳。
+ *     剥标签与扣留的标签词表因此必须逐字一致（共用 OPEN_P_TAG_RE / CLOSE_P_TAG_RE /
+ *     OPEN_ROLE_TAG_RE / CLOSE_ROLE_TAG_RE，无大小写、无词表扩展），两边一旦分叉，
+ *     就会出现「中间态当正文、收口时又剥掉」的跳动。
 *   - 标签残缺判断只影响「何时产出」，不影响最终结果；扣留期间不会抛异常。
 *   - 本类无副作用、非线程安全，调用方保证单线程喂入即可。
 */
@@ -61,6 +113,16 @@ data class ParsedBubble(
    val parts: List<ContentPart>,
    val head: List<ContentPart>,
    val tail: List<ContentPart>,
+    /**
+     * `body` 的行内样式切分（`<b>` / `<i>` / `<code>` / `<u>`，见 [parseInlineMarkup]）：非空时
+     * 拼起来**就是** [body]。空列表 = 这段正文按字面画——**绝大多数消息都走这一档**（没有标签、
+     * 或者结构不平衡被整段降级、或者整段只有标记没有字）。
+     *
+     * 有默认值，是因为只有 [toBubble] 才该填它：其余构造点要么本来就该按字面画（`plainBubble`、
+     * 分享预览的兜底 `sharePreviewBlocks`），要么是测试里的手搓气泡。这也让「加一个字段」不必
+     * 惊动任何一个既有调用方。
+     */
+    val runs: List<InlineRun> = emptyList(),
 ) {
    val isEmpty: Boolean
        get() = body.isEmpty() && head.isEmpty() && tail.isEmpty()
@@ -91,12 +153,43 @@ private val BLANK_LINE_RE = Regex("\\n\\s*\\n")
 /** 无关键词的全角星块超过此长度即视为普通文本（对齐 Web `STAR_SHORT_RUNES`）。 */
 private const val FULL_STAR_MAX_LEN = 40

-private val TAG_NAMES = listOf("action", "narration", "p")
+/**
+ * 段落/旁白标签名（**只有小写**，与 `MessageEditText` 同一口径）：流式边界判定 [isPotentialTagPrefix]
+ * 补全残缺标签时用；[stripLooseTags] 判「是不是标签」用的是下面那组同词表的正则，两边必须同源。
+ *
+ * `<br>` 不在这个名单里：它是分隔符、且**大小写不敏感**（见 [BR_TAG_RE]），判据单独走
+ * [couldBeLineBreakNamePrefix]，否则 `<BR` 会被漏扣、中间态把 `<BR` 当正文吐上屏。
+ */
+private val STRUCTURE_TAG_NAMES = listOf("action", "narration", "p")
 private val OPEN_ROLE_TAG_RE = Regex("^<\\s*(action|narration)\\s*>$")
 private val CLOSE_ROLE_TAG_RE = Regex("^</\\s*(action|narration)\\s*>$")
 private val OPEN_P_TAG_RE = Regex("^<p(\\s[^>]*)?>$")
 private val CLOSE_P_TAG_RE = Regex("^</p>$")

+/** `<br>` 分隔符的标签名（[BR_TAG_RE] 与流式扣留侧共用，别在两处各写一遍）。 */
+private const val LINE_BREAK_TAG_NAME = "br"
+
+/**
+ * `<br>` **分隔符**（契约 v0.89 更正：`<br>` 不是行内标签，而是与 `<p>` 同级的「气泡/消息分隔符」）。
+ *
+ * 认下来的形状：`<br>` / `<br/>` / `<br />` / `</br>` / `<br class=x>` …——
+ *   - **三种写法等价**，前导 `/` 与自闭合 `/` 都照收（HTML5 口径，契约写死）；
+ *   - **大小写不敏感**（`<BR>` / `<Br>` 同样算）：v0.89 那句「标签名大小写不敏感」把 `br` 一起罩住了，
+ *     且后端 IM 出站 `channelbridge/sanitize.go` 的正则本来就是 `(?is)`（`回执三十` 的原话）；
+ *   - **属性不解析**（`<br class=x>` 照样分隔），但名字后面必须紧跟 `>`、空白或 `/`：
+ *     `<br2>` / `<boolean>` / `<br-x>` 因此**不是**分隔符，只是普通文本（这一条是「字符一个不丢」的闸门）。
+ *
+ * ⚠️ 已知边界：它**不看外层标签的属性结构**——所以写成 `<b title="<br>">甲</b>` 这种「属性里带 `<br>`」的
+ * 文本会被切开（`回执三十三 §三③` 登记为两端口径相同、不修）。`<p …>` 开标签是唯一例外，因为它在更早
+ * 一层就被 [P_BLOCK_RE] 整体吃掉了，属性里的 `<br>` 根本走不到这里。真实产出里没有这种形状
+ * （属性本身就不是产出侧的东西）。
+ *
+ * ⚠️ 它只认**普通文本层**的那些：`<code>` / `<action>` / `<narration>` **内部**的 `<br>` 由
+ * [appendRegion] 按保护区跳过（`回执三十三 §三②`）——所以 `findAll` 的结果**不再是**「所有分隔点」，
+ * 用它时要么走 [appendRegion]（会跳保护区），要么自己判一遍（别处没第二个消费者）。
+ */
+private val BR_TAG_RE = Regex("<\\s*/?\\s*${LINE_BREAK_TAG_NAME}(\\s[^<>]*|/\\s*)?>", RegexOption.IGNORE_CASE)
+
 /** 一次性解析：把一条消息的原始文本拆成若干独立气泡（含旁白依附关系）。 */
 fun parse(raw: String): List<ParsedBubble> {
    if (raw.isEmpty()) return emptyList()
@@ -144,29 +237,339 @@ private sealed interface Tok {
    object Break : Tok
 }

-/** 先切 `<p>` 块（决定气泡边界），再在每个文本区做旁白/星号解析。 */
+/**
+ * 先切 `<p>` 块（决定气泡边界），再按区剥落单标签与切 `<br>` 分隔符，最后在每个文本区做旁白/星号解析。
+ */
 private fun tokenize(raw: String): List<Tok> {
-    val pMatches = P_BLOCK_RE.findAll(raw).toList()
+    // 完整块必然以 `</p>` 收尾，所以最后一个 `</p>` 之后不可能再有块：切掉尾巴再让正则去扫。不切的话，
+    // 每个 `<p` 候选点都会带着懒惰的 `([\s\S]*?)</p>` 一路回溯到串尾——正文里 N 个落单标签时
+    // 这里就是 O(N²)：实测 20000 个要 8.2 秒（同一输入下 `stripLooseTags` 那边还要 23 秒，见
+    // [ContentAfterQuery]）。切掉后同一输入 1 毫秒内出结果，且匹配结果逐字不变（每个匹配都整体落在
+    // 被切下的前缀里，正则的尝试顺序也没变）。
+    val lastClose = raw.lastIndexOf("</p>")
+    val pMatches =
+        if (lastClose < 0) {
+            emptyList()
+        } else {
+            P_BLOCK_RE.findAll(raw.substring(0, lastClose + "</p>".length)).toList()
+        }
    val out = ArrayList<Tok>()
    if (pMatches.isEmpty()) {
-        appendAnnotations(raw, out, splitBlankLines = true)
+        // 一条完整块都没有：`<p>` 及其后内容按既有契约整段回落字面文本，`<action>` 这类旁白标签
+        // 落单时同理（`MessageEditTextTest.没闭合的 action 同样原样留着`）。此处只剥掉连「被截断的
+        // 结构」都算不上的东西：落单的 `</p>`，与后面什么都没有的空开标签。判据见 [stripLooseTags]。
+        appendRegion(raw, out, markupMode = false, stripStrayRoleTags = false, splitBlankLines = true)
        return out
    }
    var last = 0
    for (m in pMatches) {
        val lead = raw.substring(last, m.range.first)
-        if (lead.isNotEmpty()) appendAnnotations(lead, out, splitBlankLines = false)
+        if (lead.isNotEmpty()) {
+            appendRegion(lead, out, markupMode = true, stripStrayRoleTags = true, splitBlankLines = false)
+        }
        out.add(Tok.Break)
        val inner = m.groupValues[2]
-        if (inner.isNotEmpty()) appendAnnotations(inner, out, splitBlankLines = false)
+        if (inner.isNotEmpty()) {
+            // 块内只剥 `<p>` 族：`<action>` / `</action>` 落单时保留字面文本，是既有契约
+            // （unclosedActionFallsBackToText / strayClosingTagStaysText 钉住的行为）。
+            appendRegion(inner, out, markupMode = true, stripStrayRoleTags = false, splitBlankLines = false)
+        }
        out.add(Tok.Break)
        last = m.range.last + 1
    }
    val trail = raw.substring(last)
-    if (trail.isNotEmpty()) appendAnnotations(trail, out, splitBlankLines = false)
+    if (trail.isNotEmpty()) {
+        appendRegion(trail, out, markupMode = true, stripStrayRoleTags = true, splitBlankLines = false)
+    }
    return out
 }

+/**
+ * 解析一个文本区：先剥落单标签（[stripLooseTags]，`markupMode` / `stripStrayRoleTags` 由调用方给），
+ * 再按 `<br>` 分隔符切成若干段，每段各自做旁白/星号解析（[appendAnnotations]），段与段之间补一个
+ * [Tok.Break]（气泡边界）。
+ *
+ * **为什么 `<br>` 在这一层切**：契约 v0.89 的更正把 `<br>` 定成**与 `<p>` 同级的分隔符**
+ * （`回执三十一`「对消息内的 `<br>` 始终处理为多条消息隔断」）。它既然与 `<p>` 同级，就该与 `<p>`
+ * 走**同一套机制、同一个粒度**：产生 [Tok.Break]、由 `buildBubbles` 分组、空气泡照旧丢弃。
+ * 行内层（`InlineMarkup`）因此几乎看不见 `<br>` —— 那里只剩六个白名单标签（唯一例外见下面的保护区：
+ * `<code>` 内部的那个 `<br>` 会随正文交到行内层，在那里按「内容」字面显示）。
+ *
+ * **顺序：先切分、再逐段各自做行内解析**（`<b>甲<br>乙</b>` ⇒ 两段各按「不平衡 ⇒ 不渲染」处理，
+ * 两段都回落原文）。理由：
+ *   1. 「与 `<p>` 同级」这句话本身就规定了层序——分隔符先于行内解析，行内解析永远只看到**一段**；
+ *      跨过分隔符的标签在结构上不可能成立（一个气泡 = 一条消息，IM 出站也是先按气泡切开再剥标签，
+ *      后端 `sanitize.go` 的「成对平衡 ⇒ 剥标签留文本 / 不平衡 ⇒ 原样保留」同样是在**单条消息内**
+ *      判平衡的）⇒ 两端对同一段文本的结论天然一致；
+ *   2. 反过来（先整体行内解析、再按 `<br>` 切）会让「渲染文本」与「气泡」互相依赖：`<b>甲<br>乙</b>`
+ *      会先变成一个粗体片段再被切开，切点落在片段内部，`body` / `runs` 的一致性（`runs` 拼起来
+ *      **就是** `body`）当场就没了；
+ *   3. 实现上也最省：行内那层一个字节都不用改（它本来就逐气泡跑一次）。
+ *
+ * 剥标签**先于**切分（判据逐字不变）：[stripLooseTags] 里「这个落单 `<p>` 后面还有没有正文」看的是
+ * 整段原文，`<br>` 在那里只是一个普通字符，所以同一输入下它的判定与 W68 完全相同。
+ *
+ * ## 保护区：`<code>` 与角色注记**内部**的 `<br>` 不分隔（`回执三十三 §三②`）
+ * `回执三十一` 说的是「**始终**分隔」，`回执三十三` 把它收紧了：**只有普通文本层的 `<br>` 才分隔**。
+ * 后端给的两条理由在我们这边一字不差地同样成立，所以照改：
+ *   1. **会漏注记正文**：`<action>她<br>点点头</action>` 若切成两段，就成了「她」「点点头」**两条消息**
+ *      ——注记本来是不该当正文露出来的那一层，切开等于把它摆到台面上（后端原话：「那等于把注记正文
+ *      发给了对方」）；
+ *   2. **`<code>` 会被切坏**：它是**成对**元素，从中间切开必然两半都不平衡，按「不平衡 ⇒ 不渲染」的
+ *      硬口径**整段降级为字面量**，用户直接看到裸标签。
+ *
+ * 实现：先扫出保护区区间（[protectedSpans]），切分时**跳过**落在区间里的 `<br>`（它留在原文里，随该
+ * 作用域自己的语义走）。扫的是**已经剥过落单标签**的那一份文本，与切分用的是同一个对象。
+ *
+ * ### 作用域内部算什么语义（我们定的口径）：**普通字符、逐字原样**（不换行、也不消掉）
+ *   - `<code>`：这是它**既有的**口径——「里面连白名单标签也按内容处理」，`<code><b>甲</b></code>`
+ *     显示字面的 `<b>甲</b>`（`codeContentIsNotParsed` 钉着）。`<br>` 在这一层本来不是标签，用不着
+ *     另立规矩；`<code>` 也正好是「想原样显示尖括号怎么办」的现成答案。
+ *   - `<action>` / `<narration>`：**必须是字面**。注记那一行画的是 `parts` 里的原文
+ *     （`MessageBubble.AnnotationLine` 直接 `parts.joinToString`），而 `parts` = **逐字原文**是红线
+ *     ——换成 `\n` 或删掉，就是在静默改用户内容（编辑框、搜索、通知读的都是它）。顺带也就与既有
+ *     口径对齐：`<action>笑<b>了</b></action>` 里的 `<b>` 同样是字面（`narrationTextIsLeftExactlyAsWritten`）。
+ *   - 两个作用域取**同一条**规矩：它们是同一件事（`<br>` 落在作用域内部），各给一种读法才是真的
+ *     「各端各说各话」。
+ *   - 为什么不把它当换行（`<code>甲<br>乙</code>` ⇒ `甲\n乙`）：那必须在一处破例——要么在这里改掉
+ *     片段文本（`parts` 当场不再是原文），要么在行内层给 `<br>` 单开一条「代码里它算换行」的规则
+ *     （W68 刚把「`<br>` → `\n`」从行内层整体删掉，而且那会让**同两个字符**在 `<code>` 与 `<action>`
+ *     里各是一种意思）。两条都不值当，所以不做。
+ *
+ * ### 未闭合的作用域：**不算作用域**，里面的 `<br>` 照旧分隔
+ * 判据只看「**成对**」，且与各自的消费侧同一把尺子：`<code>` 要找到它的 `</code>`（大小写不敏感、
+ * 可带属性——行内层就这么认），`<action>` / `<narration>` 要找到**同名**闭合（只认小写、不带属性
+ * ——`ROLE_RE` 就这么认）。找不到闭合的开标签不是作用域，于是 `<code>甲<br>乙` 照旧切成两条。
+ *   - 理由一：**消费侧本来就不认它**。未闭合的 `<code>` 在行内层不是作用域（整段降级为原文），
+ *     未闭合的 `<action>` 在 `ROLE_RE` 那里也配不出旁白。去保护一个**消费侧根本不认**的作用域，
+ *     等于让「切分层」与「消费层」对同一段文本有两种结构判断——正是本项目一路在防的那种分叉
+ *     （W68/W69 的教训：消费侧与扣留侧的词表必须同源）。
+ *   - 理由二：**爆炸半径**。若把「未闭合 ⇒ 保护到这一段文本结尾」也算上，一个漏掉 `</code>` 的笔误
+ *     就会把**后面所有** `<br>` 一起吞掉、把本该分开的多条消息并成一条。「一个畸形标签改变整段的
+ *     分段」比「照旧分隔」坏得多。
+ *   - 两种读法都不渲染、都不丢字（未闭合那一档本来就是「不平衡 ⇒ 原样显示」），差别只在气泡怎么切；
+ *     我们选与消费侧一致的那种。
+ *   - **两支各算各的**（[protectedSpans] 用两个独立状态）：`<code>` 与角色注记各自配对，因为那本来
+ *     就是两个消费侧各自的尺子——行内层在 `<code>` 里只认自己的闭合、别的一律当内容；`ROLE_RE`
+ *     则完全不看 `<code>`（它在代码里照样配对）。所以「某一支没闭合」只影响**那一支**：
+ *     `<code>甲<action>她<br>点点头</action>乙` 里那个**已经配对好**的 `<action>` 照样保护它的
+ *     `<br>`（不产生区间的只是没闭合的 `<code>` 那一支）。
+ */
+private fun appendRegion(
+    text: String,
+    out: MutableList<Tok>,
+    markupMode: Boolean,
+    stripStrayRoleTags: Boolean,
+    splitBlankLines: Boolean,
+) {
+    val stripped = stripLooseTags(text, markupMode, stripStrayRoleTags)
+    // 保护区只在「这一区里真有作用域」时才扫：绝大多数消息连 `<` 都没有（一个字节都不多花）。
+    val protected = if (stripped.indexOf('<') < 0) emptyList() else protectedSpans(stripped)
+    var last = 0
+    var span = 0
+    for (m in BR_TAG_RE.findAll(stripped)) {
+        val at = m.range.first
+        // 区间按起点升序，跟着 `<br>` 的推进往前走一个游标就够（不回头、不重扫）。
+        while (span < protected.size && protected[span].last < at) span++
+        if (span < protected.size && at in protected[span]) continue
+        val piece = stripped.substring(last, at)
+        if (piece.isNotEmpty()) appendAnnotations(piece, out, splitBlankLines)
+        out.add(Tok.Break)
+        last = m.range.last + 1
+    }
+    val tail = stripped.substring(last)
+    if (tail.isNotEmpty()) appendAnnotations(tail, out, splitBlankLines)
+}
+
+/**
+ * 扫出这一区里**已配对**的保护区区间（左闭右开，按**起点**升序）：`<code>…</code>` 与
+ * `<action>…</action>` / `<narration>…</narration>`——[appendRegion] 据此跳过落在里面的 `<br>`
+ * （口径与理由写在它的 KDoc 里）。
+ *
+ * 一趟线性扫描，判据全部借现成的尺子：「哪儿是一个标签」用行内层的 [inlineTagEnd]；`code` 用
+ * 行内层的 [openInlineTagName] / [closeInlineTagName]（大小写不敏感、可带属性）；角色注记用
+ * [openNoteTagName] / [closeNoteTagName]（与 `ROLE_RE` 同口径：只认小写、不带属性、找**同名**闭合）。
+ *
+ * **两支各自独立配对**，因为那本来就是两个消费侧各自的尺子：`<code>` 那一支只认自己的开/闭
+ * （里面别的标签都是内容，与行内层一致）；角色那一支同理（与 `ROLE_RE` 的非贪婪配对一致——它
+ * 在 `<code>` 里照样配对，两边各算各的）。任一支没闭合 ⇒ **那一支**不产生区间。
+ *
+ * `indexOf('<')` + 逐段推进的扫描区间互不重叠（见 [inlineTagEnd]），每个 `<br>` 的判定是两个游标
+ * 各走一次，因此整体仍是 O(n)：成串的尖括号或成串的作用域都不会让它退回 O(N²)。
+ */
+private fun protectedSpans(text: String): List<IntRange> {
+    val codeSpans = ArrayList<IntRange>(2)
+    val noteSpans = ArrayList<IntRange>(2)
+    var openCode = -1
+    var openNoteName: String? = null
+    var openNote = -1
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是标签：往后挪**一个字符**（与 `claimTags` 同一把尺子，
+            // 不能跳到某个「下一个 `>`」——那会把中间真正的标签一起跳过）。
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        val end = gt + 1
+        if (openCode < 0) {
+            if (openInlineTagName(tag) == CODE) openCode = lt
+        } else if (closeInlineTagName(tag) == CODE) {
+            codeSpans.add(openCode until end)
+            openCode = -1
+        }
+        val noteOpen = if (openNoteName == null) openNoteTagName(tag) else null
+        if (noteOpen != null) {
+            openNoteName = noteOpen
+            openNote = lt
+        } else if (openNoteName != null && closeNoteTagName(tag) == openNoteName) {
+            noteSpans.add(openNote until end)
+            openNoteName = null
+        }
+        i = end
+    }
+    // 两支各自升序，合起来也按**起点**升序——[appendRegion] 的包含判定（「第一个右端 ≥ 这个 `<br>`
+    // 的区间」）以「按起点升序」为前提。合并后两支的区间可能相互嵌套（`<code>` 套注记、注记套
+    // `<code>`），那不影响判定：嵌套的那些都在同一个升序序列里。
+    return when {
+        noteSpans.isEmpty() -> codeSpans
+        codeSpans.isEmpty() -> noteSpans
+        else -> (codeSpans + noteSpans).sortedBy { it.first }
+    }
+}
+
+/** 角色注记的**开**标签名（只认小写的 `action` / `narration`、不带属性——与 `ROLE_RE` 同口径）。 */
+private fun openNoteTagName(tag: String): String? = OPEN_ROLE_TAG_RE.find(tag)?.groupValues?.get(1)
+
+/** 角色注记的**闭**标签名（同上；配对要求**同名**，与 `ROLE_RE` 的 `</\s*\1\s*>` 一致）。 */
+private fun closeNoteTagName(tag: String): String? = CLOSE_ROLE_TAG_RE.find(tag)?.groupValues?.get(1)
+
+/**
+ * 剥掉「落单标签」，其余字符逐字保留（返回原对象：没剥到东西时不做新分配）。
+ *
+ * [markupMode] = 这条消息里**已有完整 `<p>…</p>` 块**，段落结构已被完整块定死，于是块内/块外
+ * 多出来的每一个 `<p>` / `</p>` 都是冗余噪声，一律剥掉。
+ * 没有完整块时（`parse` 会整段回落字面文本，见 `unclosedParagraphStaysLiteralText`；编辑框也靠
+ * 这条保证不静默改字，见 `MessageEditTextTest.没闭合的 p 不抛异常`）只再剥两类不可能是正文的东西：
+ * 落单的 `</p>`，以及后面什么都没有的**空**开标签——它们连「被截断的段落」都算不上。
+ *
+ * [stripStrayRoleTags] 只对**块外**文本区为 true：那里的 `<action>` / `</action>` 若没被 [ROLE_RE]
+ * 认领（即没配成对），就是落单标签，剥掉。已配对的必须留给 [ROLE_RE] 解析成 Action/Narration，
+ * 提前剥掉等于把旁白降级为正文（`textOutsideParagraphsIsPreserved` 钉住的行为）。
+ */
+private fun stripLooseTags(text: String, markupMode: Boolean, stripStrayRoleTags: Boolean): String {
+    if (text.indexOf('<') < 0) return text
+    val roleRanges = if (stripStrayRoleTags) ROLE_RE.findAll(text).map { it.range }.toList() else emptyList()
+    // 「这个落单 `<p>` 后面还有没有正文」按位置记表：正文里 N 个落单标签，现扫是 O(N²)（见
+    // [ContentAfterQuery] 的 KDoc）。常规消息（没有落单 `<p>` 开标签）一次都不建表。
+    val contentAfter = ContentAfterQuery(text)
+    val out = StringBuilder(text.length)
+    var last = 0
+    var i = 0
+    while (i < text.length) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = text.indexOf('>', lt)
+        if (gt < 0) break
+        val tag = text.substring(lt, gt + 1)
+        val drop = when {
+            OPEN_P_TAG_RE.matches(tag) -> markupMode || !contentAfter.hasContentAfter(gt + 1)
+            CLOSE_P_TAG_RE.matches(tag) -> true
+            !stripStrayRoleTags -> false
+            roleRanges.any { lt in it } -> false
+            else -> OPEN_ROLE_TAG_RE.matches(tag) || CLOSE_ROLE_TAG_RE.matches(tag)
+        }
+        if (drop) {
+            out.append(text, last, lt)
+            last = gt + 1
+            i = last
+        } else {
+            i = lt + 1
+        }
+    }
+    if (last == 0) return text
+    out.append(text, last, text.length)
+    return out.toString()
+}
+
+/**
+ * [stripLooseTags] 判落单 `<p>` 用的「[from] 之后还有没有正文」查询：空白跳过，`<p>` / `</p>`
+ * 整段跳过，其余字符（别的标签、落单的 `<`）一律算有正文——跳过空白与后续 `<p>` 族标签后仍非空
+ * 即为有。判据与原实现逐字一致，只多了记忆化。
+ *
+ * **为什么要记忆化**：这条判据原本每次查询都一路现扫到串尾，而 [stripLooseTags] 对**每一个**
+ * 落单 `<p>` 都要问一次，正文里 N 个落单标签就是 O(N²)——20000 个落单 `<p>` 的输入实测这条判据
+ * 要 23 秒（同一次 `parse` 合计 31 秒），而 `parse` 跑在主线程上（`ui/chat/MessageBubble.kt` 的
+ * `remember`），用户粘一段 HTML 残骸就能把界面卡死十几秒。
+ *
+ * **为什么可以只算一次**：答案只取决于**位置**——同一个位置再问一次，走的一定是同一条链、到的
+ * 一定是同一个终点。所以走链时把沿途每个位置的答案落表，之后 O(1) 命中；每个位置至多被算一次，
+ * N 个落单标签整体就是线性的（同一输入实测这条判据从 23 秒降到毫秒级）。
+ *
+ * **为什么不改变语义**：判定用的就是原来那段扫描本身（[next] 逐分支对应原循环），没有另立一套
+ * 「什么算 `<p>` 标签」的判据——仍是同一组 [OPEN_P_TAG_RE] / [CLOSE_P_TAG_RE]。落表的答案是同一条
+ * 扫描推出来的，因此与逐次现扫逐字相同；连「起点落在标签内部」这种查询也一致（原扫描看到的是
+ * 标签里的字符、判有正文，[next] 在这里同样返回 null）。
+ *
+ * 惰性：没遇到落单 `<p>` 开标签的常规消息一次也不建表，一个字节都不多花。
+ */
+private class ContentAfterQuery(private val text: String) {
+    /** 每个位置的答案：`0` = 还没算、[NOISE_ONLY] = 后面只剩空白与 `<p>` 族标签、[HAS_CONTENT] = 有正文。 */
+    private val answers: ByteArray by lazy(LazyThreadSafetyMode.NONE) {
+        ByteArray(text.length + 1).also { it[text.length] = NOISE_ONLY }
+    }
+
+    /** 本次走链途经的位置，用来把 [answers] 一次落表。 */
+    private val path: IntArray by lazy(LazyThreadSafetyMode.NONE) { IntArray(text.length) }
+
+    /** 与原先「每次现扫到串尾」的判定逐字等价。 */
+    fun hasContentAfter(from: Int): Boolean {
+        var walked = 0
+        var i = from
+        while (true) {
+            val known = answers[i]
+            if (known != UNKNOWN) return finish(walked, known)
+            path[walked++] = i
+            val step = next(i)
+            if (step == null) return finish(walked, HAS_CONTENT)
+            i = step
+        }
+    }
+
+    /** 把这次走链途经的位置一次落表：它们与起点走的是同一条链，答案必然相同。 */
+    private fun finish(walked: Int, answer: Byte): Boolean {
+        for (k in 0 until walked) answers[path[k]] = answer
+        return answer == HAS_CONTENT
+    }
+
+    /**
+     * 原扫描的一步：空白 → 下一位；`<p>` 族标签 → 标签之后；其余（别的标签、落单的 `<`）→ `null`，
+     * 即「有正文」，扫描到此为止。走到 `text.length` 时由 [answers] 里预置的答案收口。
+     */
+    private fun next(i: Int): Int? {
+        val c = text[i]
+        if (c.isWhitespace()) return i + 1
+        if (c == '<') {
+            val gt = text.indexOf('>', i)
+            if (gt >= 0) {
+                val tag = text.substring(i, gt + 1)
+                if (OPEN_P_TAG_RE.matches(tag) || CLOSE_P_TAG_RE.matches(tag)) return gt + 1
+            }
+        }
+        return null
+    }
+
+    private companion object {
+        const val UNKNOWN: Byte = 0
+        const val NOISE_ONLY: Byte = 1
+        const val HAS_CONTENT: Byte = 2
+    }
+}
+
 /** 在文本区内按左到右顺序切出 Text / Action / Narration。 */
 private fun appendAnnotations(text: String, out: MutableList<Tok>, splitBlankLines: Boolean) {
    var last = 0
@@ -307,9 +710,21 @@ private fun toBubble(tokens: List<Tok>): ParsedBubble? {
            tail.add(part)
        }
    }
-    val bodyText = body.toString().trim()
+    // 行内标签在**段落与 `<br>` 都定稿之后**才消费（就在这一行，且是**逐气泡各自一份**）：上面那套
+    // 分段与归属一个字都不动，分段判据因此完全看不见行内标签（`<br>` 已经在 [appendRegion] 那层
+    // 变成气泡边界了）。runs 为空 = 这段正文按字面画（没有可渲染的行内标签、或行内标签结构不平衡
+    // 被整段降级），一个字都不会变。
+    val rawBody = body.toString().trim()
+    val runs = parseInlineMarkup(rawBody)
+    val bodyText = if (runs.isEmpty()) rawBody else runs.joinToString("") { it.text }
    if (bodyText.isEmpty() && head.isEmpty() && tail.isEmpty()) return null
-    return ParsedBubble(body = bodyText, parts = parts.toList(), head = head.toList(), tail = tail.toList())
+    return ParsedBubble(
+        body = bodyText,
+        parts = parts.toList(),
+        head = head.toList(),
+        tail = tail.toList(),
+        runs = runs,
+    )
 }

 // ---------------------------------------------------------------------------
@@ -354,28 +769,62 @@ private fun stablePrefixEnd(buf: String): Int {

 private fun openTagName(tag: String): String? {
    OPEN_ROLE_TAG_RE.find(tag)?.let { return it.groupValues[1] }
-    return if (OPEN_P_TAG_RE.matches(tag)) "p" else null
+    if (OPEN_P_TAG_RE.matches(tag)) return "p"
+    // 行内开标签也入栈（`<B class=x>` 这类形态由 [parseInlineTag] 判，与解析侧同源）。
+    // `<br>` 是自闭合的，**不入栈**（入了就永远弹不出来，扣留点会永久停在它前面，后面的话再也
+    // 显示不出来）——[openInlineTagName] 对 `<br>` / `<br/>` / `</br>` 一律返回 null。
+    return openInlineTagName(tag)
 }

 private fun closeTagName(tag: String): String? {
    CLOSE_ROLE_TAG_RE.find(tag)?.let { return it.groupValues[1] }
-    return if (CLOSE_P_TAG_RE.matches(tag)) "p" else null
+    if (CLOSE_P_TAG_RE.matches(tag)) return "p"
+    return closeInlineTagName(tag)
 }

-/** 尾部 `<…` 是否仍可能补全为合法标签（否则它只是普通文本里的 `<`）。 */
+/**
+ * 尾部 `<…` 是否仍可能补全为合法标签（否则它只是普通文本里的 `<`）。
+ *
+ * 词表分两半，每一半都与**自己的消费侧**同源，两条口径都在这里逐字对齐：
+ *   - 段落/旁白只认小写（`<P>` / `<Action>` 原样显示，既有契约）——名字里出现大写就与它无关；
+ *   - 行内标签与 `<br>` 分隔符**大小写不敏感**（契约 v0.89，[parseInlineTag] / [BR_TAG_RE]）
+ *     ——`<B` 与 `<b`、`<BR` 与 `<br` 一样要扣留。
+ * 少扣了就是「中间态把标签当正文吐上屏、收口时才吃掉」，屏幕上显示过的字会改口。
+ * 名字之后是空白或 `/` 都算「还可能补全」（属性 / 自闭合，v0.89 允许带属性，所以 `<b class=x>`
+ * 与 `<br/` 这两个中间态也必须扣住）；其它字符说明它压根不是标签（`<boolean>`、`<b2`）。
+ */
 private fun isPotentialTagPrefix(buf: String, lt: Int): Boolean {
    var j = lt + 1
    if (j < buf.length && buf[j] == '/') j++
    while (j < buf.length && buf[j].isWhitespace()) j++
    val nameStart = j
-    while (j < buf.length && buf[j] in 'a'..'z') j++
+    while (j < buf.length && isTagNameLetter(buf[j])) j++
    val name = buf.substring(nameStart, j)
-    if (j >= buf.length) return name.isEmpty() || TAG_NAMES.any { it.startsWith(name) }
-    if (name.isEmpty()) return false
-    if (!buf[j].isWhitespace()) return false
-    return TAG_NAMES.any { it.startsWith(name) }
+    if (name.isEmpty()) return j >= buf.length
+    if (!couldBeTagName(name)) return false
+    if (j >= buf.length) return true
+    return buf[j].isWhitespace() || buf[j] == '/'
 }

+/**
+ * [name] 是否可能是某个已知标签名的前缀；三半各按自己的大小写口径（见 [isPotentialTagPrefix]）：
+ * 段落/旁白小写、`<br>` 与行内标签大小写不敏感。
+ */
+private fun couldBeTagName(name: String): Boolean {
+    if (name.all { it in 'a'..'z' } && STRUCTURE_TAG_NAMES.any { it.startsWith(name) }) return true
+    val lower = name.lowercase()
+    if (couldBeLineBreakNamePrefix(lower)) return true
+    return couldBeInlineTagNamePrefix(lower)
+}
+
+/**
+ * [name]（已小写）是否可能是 `<br>` 分隔符的标签名前缀——`<br` / `</br` / `<BR` 这种残缺形态要不要
+ * 扣留由它说了算。判据与 [BR_TAG_RE] 同口径（大小写不敏感的 `br`）：两边一分叉，
+ * `甲<br` 会先把字面 `<br` 吐上屏，等 `>` 到了再变成两条气泡。
+ */
+private fun couldBeLineBreakNamePrefix(name: String): Boolean =
+    name.isNotEmpty() && LINE_BREAK_TAG_NAME.startsWith(name)
+
 /** 自由文本区内孤立的全角 `＊`（计数为奇）从最后一个起扣留。 */
 private fun withholdDanglingFullStar(buf: String, from: Int, cut: Int): Int {
    var count = 0
@@ -0,0 +1,461 @@
+package top.yeij.cyrene.domain.parse
+
+/*
+ * InlineMarkup —— 气泡正文里「一小撮行内标签」的解析（纯 Kotlin，无 Android / Compose 依赖）。
+ *
+ * 口径 = 后端 2026-10-07 定下的**契约 v0.89** 及其同日更正（跨端必须逐字一致，否则同一个 `<b>`
+ * 在她那台设备上粗、在这台上不粗）。四条硬口径：
+ *   1. 白名单 = `b` / `strong` · `i` / `em` · `code` · `u`（**成对**，六项标签名）；标签名**大小写不敏感**；
+ *   2. **属性一律不解析**：`<b class=x onclick=y>` 只取标签名，属性整段丢掉、绝不落成任何视图属性；
+ *   3. **白名单外一律按纯文本原样显示**：`<script>` 显示成字面量，字符一个不丢；
+ *   4. **结构不平衡 ⇒ 整段降级为原文**（未闭合 / 落单闭标签 / 交错）——粗粒度是有意的，换来
+ *      「字符一个不丢」可以被逐字断言。
+ * 样式映射：`b`/`strong` → 粗体，`i`/`em` → 斜体，`code` → 等宽 + 轻微底色（且**里面的标签不解析**），
+ * `u` → 下划线。`s` **不在白名单里**：它按第 3 条逐字原样显示（见下）。
+ *
+ * ## `br` 不在这里（契约同日更正）
+ * `回执三十一`：「对消息内的 `<br>` **始终处理为多条消息隔断**」⇒ `<br>` **不是行内标签**，而是与
+ * `<p>` 同级的**气泡/消息分隔符**，切分在 [tokenize](ChatContentParser.kt) 的段/块那一层
+ * （`ChatContentParser.appendRegion`）完成，`<br>` / `<br/>` / `</br>` 三种写法等价。
+ * 这一层因此**只认成对标签**：`<br>` 到了这里只是几个普通字符，与 `<br2>`、`<boolean>` 同类。
+ * 它**真的会**走到这里，只是只有一条路：`<code>` 作用域内部——分隔符切分层有一个**保护区**
+ * （`ChatContentParser.protectedSpans`，`回执三十三 §三②`），落在 `<code>` / `<action>` / `<narration>`
+ * 内部的 `<br>` 不分隔，于是 `<code>` 里的那个 `<br>` 会随正文一起交到这一层，在代码作用域里按
+ * 「内容」处理（字面显示，与 `<code><b>甲</b></code>` 里的 `<b>` 同一规矩）。
+ *
+ * ## 白名单六项（`u` 加回、`s` 不做）
+ * `回执三十` 先把白名单收窄到五项、撤掉 `u`/`s`（理由是「多支持 = 制造跨端不一致」），但
+ * `回执三十三 §一` 更正：**那份「收窄到五项」是后端的疏漏**——主人随后裁定下划线保留、后端把 `u`
+ * 加回了契约（`1107b2a`）与 IM 出站（`74c9f2d`），只是**忘了发回执登记**。最终白名单 = **六项**：
+ * `b` / `strong` / `i` / `em` / `code` / **`u`**，`u` 在这里渲染成下划线。
+ * **`s` 仍不在内**（逐字原样）——「多支持反而制造跨端不一致」这条理由对它依然成立：Web 不渲染它。
+ *
+ * ## 为什么是「整段降级」而不是「只降级那一处」
+ * W67 那版是**局部**降级：`甲<b>粗</b>乙<b>没闭合` 里 `粗` 照旧加粗，只有后面那半个 `<b>` 留着字面。
+ * 契约把「结构不平衡」定成**整段不渲染**：一处不平衡，这一整段就一个标签都不认、原文逐字显示。
+ * 代价是「好好的一对 `<b>` 会被邻居的落单标签连累」，换来的是**可以逐字断言**的粗粒度：
+ * 「渲染文本 == 原文」或者「渲染文本 == 原文消费掉全部配对标签」，只有这两种形状，没有中间态
+ * （局部降级那种「一半认、一半留」在跨端对齐时最容易各说各话）。见 [parseInlineMarkup]。
+ *
+ * ## 「整段」是哪一段（我们采用的口径 + 理由）
+ * **整段 = 该气泡的正文**，也就是 [toBubble](ChatContentParser.kt) 里 `body.toString().trim()`
+ * 出来的那一段（`ParsedBubble.body` 对应的文本，通常正好是一个 `<p>…</p>` 块的正文，也可能是
+ * 块外文本并入相邻气泡后的那一份）。不是整条消息，也不是单个 `<p>` 块：
+ *   - **不是整条消息**：一条消息可以有多个分隔（`<p>` / `<br>`）= 多条气泡，一个气泡里写坏了一个
+ *     标签，不该把**别的**气泡一起按字面画出来——那既不是契约想说的「这一段」，也会让「她写坏了
+ *     一个标签」这种局部事故看起来像整条消息都坏了。
+ *   - **不是单个 `<p>` 块**（虽然大多数时候两者重合）：本端渲染的**最小单位就是气泡**，
+ *     `body` / `runs` 也都是按气泡算的。降级粒度与渲染粒度取同一个，实现上才有一条清晰的边界
+ *     （`toBubble` 一次调用 = 一次判定），断言也才写得出「这条气泡是原文、那条气泡照常渲染」。
+ *   - 后端已认可这一点（`回执三十`：「契约只承诺『不平衡 ⇒ 不渲染、字符一个不丢』，**具体粒度算
+ *     实现细节**」）。
+ *   - 因为切分（`<p>` / `<br>`）**先于**行内解析，跨分隔符的标签天然分属两段：
+ *     `<b>甲<br>乙</b>` ⇒ 两段各不平衡 ⇒ 两段都回落原文。
+ *
+ * ## 为什么不改 `parts`，只在 `ParsedBubble` 上加一个字段
+ * `ContentPart.Text` 的 `text` 必须保持**逐字原文**：编辑框（`MessageEditText.visibleTextOf`）、
+ * 搜索片段（`SessionSearchModel.plainSearchText`）、通知文案（`ProactiveNotify`）读的都是 `parts`，
+ * 在那里把标签改掉就是**静默改用户内容**。所以行内解析不改片段，只在 `toBubble` 里对**已经定稿的
+ * 正文**算一次，结果落在 `ParsedBubble.runs`；`body` 变成正文的**渲染文本**（白名单标签已消费），
+ * 而 `parts` 仍是原文——两侧各拿自己该拿的那一份。
+ *
+ * ## 与段落解析的分工（为什么不在 `tokenize` 里做）
+ * 行内解析发生在**段落/分隔符边界已经定稿之后**（`toBubble` 里，对最终 `body` 做一次）：`<p>` 与
+ * `<br>` 分气泡、空行回落、旁白归属、落单标签剥离全部照旧，行内标签既不参与、也改不动它们。
+ * 这也让 W63 在 `tokenize` 里去掉的两处 O(N²) 一行都不受影响：这里是对最终正文的一趟线性扫描。
+ *
+ * ## 大小写不敏感（v0.89）与「扣留侧必须一起改」
+ * `<B>` / `<STRONG>` 都认——但**消费侧与流式扣留侧（[ChatContentParser.stablePrefixEnd]）
+ * 必须同源**，否则两边分叉：`<B` 这种残缺形态若只在消费侧认，中间态就会把它当正文吐上屏、等 `</B>`
+ * 到了再吃掉，**屏幕上已经显示过的字就改口了**。所以标签名的字母判据（[isTagNameLetter]）与
+ * 「这个名字还可能补全吗」（[couldBeInlineTagNamePrefix]，以及 `ChatContentParser.isPotentialTagPrefix`
+ * 里的 `couldBeTagName`）都收在**这一份文件**里，两边引用同一份名单。
+ * 段落/旁白标签（`<p>` / `<action>` / `<narration>`）仍然**只认小写**：这是既有契约
+ * （`plainAngleBracketsAreNeverEaten` 钉着 `<P>` 原样、`MessageEditText` 同一口径），
+ * 且契约明确「`<action>`/`<narration>` 的既有行为逐字未改」。
+ *
+ * ## 明确不做（逐条理由）
+ * 1. **块级（`<p>` 之外的 `<div>` / `<h1>` / 列表…）不做**：契约写死「段落仍走 `<p>`」。
+ * 2. **`<a href>` 不做**：它不是一个样式，是一个**点击行为**（要唤浏览器），必须配一套安全策略
+ *    （只认 http/https、不许 `intent://` / `javascript:` 之类）。契约把它划成独立安全面，实测 0 命中。
+ * 3. **Markdown 的 `*` / `_` 一律不做**：星号这个字形在本项目**已经被占走了**——`ROLE_RE` 把全角
+ *    `＊…＊` 与半角 `*(动作|旁白|内心|神态|轻声)…*` 判成旁白/动作（`＊笑＊` 是动作，不是斜体），
+ *    既有测试钉着这条语义。再给同两个星号一个「斜体」的说法，同一条消息就有两种读法，还要先猜
+ *    哪一种是她的本意——那是改既有语义，不是加渲染。
+ * 4. **`#` 标题 / `- ` 列表 / 表格 / ``` 围栏 / `[链接](url)` / `~~删除~~` 一律不做**：真后端最近
+ *    100 条实测 0 命中；而且这些是**行级**规则，会把「正文里真有一行以 `- ` 开头」这种普通文本
+ *    改写成别的东西——0 命中 + 有改写风险 = 不做。
+ * 5. **HTML 实体（`&lt;` `&amp;` `&nbsp;` …）不做**：实测 0 命中；实体是一张**开放的清单**
+ *    （`&#39;` / `&#x27;` / 各种命名实体……），做一半比不做更糟——会出现「`&amp;` 解了、`&#x27;`
+ *    却原样显示」这种谁也说不清的口径。想在正文里显示尖括号，今天有 `<code>` 这一档。
+ * 6. **`<script>` / `<style>` 之类只会「原样显示」，绝不会被当 HTML 注入**：渲染侧是
+ *    `AnnotatedString` + `SpanStyle`（结构化），正文从来没有、也不会走任何 HTML 解析/注入路径。
+ *
+ * 契约与边界口径见 [parseInlineMarkup]。
+ */
+
+/**
+ * 一段行内样式，可叠加（`<b><i>粗斜</i></b>` 同时是粗与斜）。
+ *
+ * 只有这四种：换行不是样式——`<br>` 是气泡分隔符（切在 `ChatContentParser.tokenize` 那一层），
+ * 它只会在 `<code>` 作用域内部作为**内容**走到这里（按文件头那条口径字面显示），永远不成样式。
+ */
+enum class InlineStyle {
+    Bold,
+    Italic,
+    Code,
+
+    /** `<u>`：下划线（渲染成 `TextDecoration.Underline`）。`s` 不在白名单里，所以没有对应项。 */
+    Underline,
+}
+
+/**
+ * 正文里**样式一致的一段连续文本**：片段按顺序拼起来就是渲染文本，样式区间由「起始下标 + 长度」
+ * 就地累加得到（第 n 段的区间 = 前面各段长度之和 until 加上自己）。
+ *
+ * 相邻且样式相同的片段由 [parseInlineMarkup] 合并，所以同一段文本只有一种片段形状——
+ * 断言起来就是在断言「哪段字是什么样式」。
+ */
+data class InlineRun(val text: String, val styles: Set<InlineStyle>)
+
+/**
+ * `<code>` 的标签名（解析里要单独判它：里面的标签不再解析）。
+ * `internal` 是因为 `ChatContentParser.protectedSpans` 也要判它（保护区扫描），
+ * 名字只写这一处、两边不许各写一遍。
+ */
+internal const val CODE = "code"
+
+/**
+ * 成对标签的名字（契约 v0.89 最终版的**六项**，见文件头）：`strong` / `em` 是 `b` / `i` 的同义写法，
+ * `u` 是 `回执三十三 §一` 加回来的下划线。
+ * 只写这一处，[parseInlineTag] 与 [couldBeInlineTagNamePrefix] 都由它推出来。
+ * `br` 不在这里（它是分隔符，见文件头）；`s` 也不在（逐字原样）。
+ */
+private val PAIRED_TAG_NAMES = listOf("b", "strong", "i", "em", CODE, "u")
+
+/**
+ * 行内标签词表。**流式扣留侧（`ChatContentParser.stablePrefixEnd`）与这里必须同源**：
+ * 同一份名单既判「这是个行内标签」（消费侧），也判「这个标签名会不会继续补全」（扣留侧）。
+ * 两边一分叉，中间态就会把标签当正文吐上屏、收口时才吃掉——屏幕上已经显示过的那几个字就改口了。
+ */
+internal val INLINE_TAG_NAMES = PAIRED_TAG_NAMES
+
+/**
+ * 白名单行内标签认下来的两种形态。**认不出来的（白名单外、形状不对）一律返回 null**，
+ * 由调用方当普通文本原样显示（契约第 3 条：字符一个不丢）。
+ */
+internal sealed interface InlineTag {
+    val name: String
+
+    /** 成对的开标签（`<b>`、`<STRONG>`、`<b class=x onclick=y>`…）：要入栈等它的闭合。 */
+    data class Open(override val name: String) : InlineTag
+
+    /** 成对的闭标签（`</b>`、`</EM>`…）。 */
+    data class Close(override val name: String) : InlineTag
+}
+
+/** 标签名里允许出现的字母：ASCII 大小写，消费侧与扣留侧共用这一把尺子。 */
+internal fun isTagNameLetter(c: Char): Boolean = c in 'a'..'z' || c in 'A'..'Z'
+
+/**
+ * 把一段 `<…>` 文本判成白名单行内标签（不是则 null）。**一处判据，两个消费者**：解析侧用它认标签，
+ * 流式扣留侧用它算「这个开标签要不要入栈扣留」——同源才不会分叉。
+ *
+ * 认下来的形状（`<` 与名字之间可以有空白，与既有 `</\s*(action|narration)\s*>` 同一口径）：
+ *   - 名字 = ASCII 字母串，**大小写不敏感**，落成小写后必须在 [INLINE_TAG_NAMES] 里；
+ *   - 名字之后紧跟的必须是 `>`、空白或 `/`——`<boolean>` / `<br2>` / `<b-x>` 因此都不是标签
+ *     （否则 `b` 会把一大票以 b 开头的普通单词吃成粗体），这是「字符一个不丢」的第一道闸门；
+ *   - 再往后到 `>` 之间的一切（属性、`/`、空白）**整段丢掉**：契约第 2 条，只取标签名。
+ *     丢掉的只是白名单标签自己那对尖括号里的东西，正文一个字符都不动。
+ *
+ * `<br>` 在这里返回 null（它不再是行内标签，是气泡分隔符）——所以它落到「白名单外」那条路：
+ * 它只是几个普通字符。真实链路上**只有一条路**能把它送到这一层：`<code>` 作用域内部
+ * （分隔符切分层的保护区不分隔它，见 [appendRegion] 与 `ChatContentParser.protectedSpans`）。
+ */
+internal fun parseInlineTag(tag: String): InlineTag? {
+    val end = tag.length - 1
+    if (end < 2 || tag[0] != '<' || tag[end] != '>') return null
+    var i = 1
+    val closing = tag[i] == '/'
+    if (closing) i++
+    while (i < end && tag[i].isWhitespace()) i++
+    val nameStart = i
+    while (i < end && isTagNameLetter(tag[i])) i++
+    if (i == nameStart) return null
+    val name = tag.substring(nameStart, i).lowercase()
+    if (i < end && !tag[i].isWhitespace() && tag[i] != '/') return null
+    if (name !in PAIRED_TAG_NAMES) return null
+    return if (closing) InlineTag.Close(name) else InlineTag.Open(name)
+}
+
+/** 开标签名（不是行内开标签则 null）。 */
+internal fun openInlineTagName(tag: String): String? =
+    (parseInlineTag(tag) as? InlineTag.Open)?.name
+
+/** 闭标签名（不是行内闭标签则 null）。 */
+internal fun closeInlineTagName(tag: String): String? =
+    (parseInlineTag(tag) as? InlineTag.Close)?.name
+
+/**
+ * [name]（已小写）是否可能是某个行内标签名的**前缀**——流式扣留侧判「残缺的 `<b` 还可能补全吗」
+ * 用它。大小写不敏感与 [parseInlineTag] 一致，名单也是同一份。
+ */
+internal fun couldBeInlineTagNamePrefix(name: String): Boolean =
+    INLINE_TAG_NAMES.any { it.startsWith(name) }
+
+/** 标签名 → 样式；`strong` / `em` 落到与 `b` / `i` 同一个样式上。 */
+internal fun inlineStyleOf(name: String): InlineStyle = when (name) {
+    "i", "em" -> InlineStyle.Italic
+    CODE -> InlineStyle.Code
+    "u" -> InlineStyle.Underline
+    else -> InlineStyle.Bold
+}
+
+/**
+ * 把一段**已经定稿的正文文本**解析成行内片段（纯函数）。
+ *
+ * 契约（都由单测钉着）：
+ * 1. **返回空列表 = 这段文本按字面渲染**（正文一个字符都不动）。三种情形都落在这里：
+ *    没有可渲染的行内标签、**结构不平衡**（契约第 4 条，整段降级）、以及整段只有标记没有字。
+ *    这是绝大多数消息的路径（实测 100 条里只有 2 条带 `<b>`），也是 `plainBubble` 那条路。
+ * 2. 返回非空 ⇒ 片段拼起来**就是**渲染文本：白名单标签已被消费，且两端空白已去（见下）。
+ *    **除此之外逐字等于原文**——白名单外的标签（`<script>`）、属性、`<code>` 里的内容全都原样在
+ *    片段里。
+ * 3. **绝不把一段非空正文渲染成空**：整段只有标记没有字（`<b></b>`）时回落成第 1 条，
+ *    把标记原样显示——宁可让她的话里多几个尖括号，也不能给出一条空白气泡。
+ *
+ * ## 口径一：配成对且正确嵌套，否则**整段**降级为原文（契约第 4 条）
+ * 判定只看白名单标签的结构（白名单外的尖括号一律是普通字符，不参与判定）：
+ *   - **未闭合的开标签**（`<b>没有闭合`、`日落 <b>18:35`）、**落单的闭标签**（`没有闭合</b>`、
+ *     只有 `</b>`）、**交错**（`<b>甲<i>乙</b>丙</i>`：`</b>` 关不掉栈顶的 `i`）——三者任一出现，
+ *     这一整段**一个标签都不认**、原文逐字显示。
+ *   - 代价与收益都写清：`甲<b>粗</b>乙<b>没闭合` 里的 `粗` 也不再加粗（粗粒度），
+ *     换来的是渲染文本与原文之间只有两种关系（相等 / 消费掉全部配对标签），跨端可以逐字对齐。
+ *   - 判据只有这一条，不发明「宽容关闭」（`</b>` 顺手把里面没关的 `<i>` 也关掉）、也不按行/按句
+ *     局部生效：那种写法每端都能自圆其说，合起来就是跨端不一致。
+ *   - **跨分隔符的标签各自算**：`<b>甲<br>乙</b>` 里的 `<br>` 在更早一层就把气泡切开了，
+ *     到这里是两段文本（`<b>甲` 与 `乙</b>`），各自不平衡 ⇒ 各自回落原文。层序与理由见
+ *     `ChatContentParser.appendRegion` 的 KDoc。
+ *
+ * ## 口径二：`<code>` 里不再解析（与契约第 3 条一致，不是例外）
+ * `<code><b>甲</b></code>` 显示字面的 `<b>甲</b>`（等宽 + 底色），`<code>1 < 2 && a<b</code>`
+ * 原样显示。它与契约第 3 条（白名单外按纯文本显示）**不冲突、方向一致**，但**不是同一条规则**：
+ *   - 第 3 条管的是**白名单外的标签名**（`<script>`、`<div>`）——它们从来不是「标签」；
+ *   - `<code>` 是一条**作用域**规则：在白名单标签 `<code>` 内部，连白名单标签也按内容处理。
+ *     `code` 表达的是「这段是代码」，代码里的 `<b>` 就是四个字符——这是 W67 就定下的口径，
+ *     契约没有就「`<code>` 内部」单独措辞，我们**保留原行为**（换 HTML 那种「元素照常嵌套解析」的
+ *     语义，改动只是删掉 [claimTags] 里的跳过分支，等后端确权再动）；
+ *   - 两者的结果都落在同一条硬口径上：**字符一个不丢**。`<code>` 也正好是「想原样显示尖括号
+ *     怎么办」的现成答案。
+ * 内部的东西**不参与结构判定**：`<code><b>甲</code>` 里的 `<b>` 不算未闭合（它只是内容），
+ * 所以不会因为它把整段拖成字面——判定与显示用的都是同一套「里面不算标签」的口径。
+ * 代价是代码里的 `<b>` 不生效（实测 0 命中，也不存在「代码里也要粗体」这个需求）。
+ *
+ * ## 为什么两端空白要去掉
+ * 被标签让出来的空白（`<b> 甲 </b>` 里那两个字）留着的唯一效果是「气泡里看起来多了两个空格」，
+ * 而正文两端的空白本来就被去掉了（`toBubble` 里那句 `body.trim()`）。这一步只吃空白——一个可见
+ * 字符都不会掉；它同时兜住契约第 3 条：整段只有空白（`<b> </b>`）时回落字面，绝不给出一条
+ * 看起来空白的怪气泡。
+ *
+ * 复杂度 O(n)：两趟线性扫描（每个 `<` 只看一扇「到 `>` 或下一个 `<` 为止」的窗，绝不
+ * `indexOf('>')` 一路找配对）；正文里没有 `<` 时连集合都不建，一次就返回。
+ */
+fun parseInlineMarkup(text: String): List<InlineRun> {
+    if (text.indexOf('<') < 0) return emptyList()
+    // 结构不平衡 ⇒ 整段降级为原文（消费侧返回空列表 = 调用方按字面渲染）。
+    val claimed = claimTags(text) ?: return emptyList()
+    if (!claimed.any) return emptyList()
+    // 整段被吃空（`<b></b>` 这类只有标记没有字的形状）⇒ 回落字面路径，见契约第 3 条。
+    return runsOf(text, claimed).trimEdges().takeIf { it.isNotEmpty() } ?: emptyList()
+}
+
+/** 一趟扫下来的「哪些标签被认领」：开/闭标签的起始下标。 */
+private class ClaimedTags {
+    val openStarts = HashSet<Int>()
+    val closeStarts = HashSet<Int>()
+
+    val any: Boolean
+        get() = openStarts.isNotEmpty() || closeStarts.isNotEmpty()
+}
+
+/**
+ * 第一趟：扫出配成对且正确嵌套的那些标签（起始下标落在 [ClaimedTags] 的两个集合里）。
+ *
+ * 返回 **null = 结构不平衡**（未闭合 / 落单闭标签 / 交错），调用方据此整段降级为原文。
+ * 因为不平衡时整段都不认，所以有返回值时**每一个**白名单成对标签都是配好的（闭标签只关得掉栈顶
+ * 那个同名开标签，严格嵌套）。
+ *
+ * 白名单外的尖括号**完全不参与判定**：它们是普通字符（契约第 1、3 条），既不入栈、也不会因为
+ * 「没闭合」把整段拖成字面——`甲<b>粗</b><script>` 里粗体照常生效，`<script` 原样显示。
+ *
+ * `<code>` 开着的期间**整段跳过**：里面的标签一个都不认、也不算结构（见 [parseInlineMarkup] 的
+ * 口径二）。因为跳过的是「认不认」，所以 `<code>` 自己那一对仍照常被认领。
+ */
+private fun claimTags(text: String): ClaimedTags? {
+    val claimed = ClaimedTags()
+    val open = ArrayList<Pair<String, Int>>()
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是行内标签：往后挪**一个字符**再找。不能跳到某个「下一个 `>`」——
+            // 那会连同中间真正的标签一起跳过（`1 < 2 <b>甲</b>` 里的 `<b>` 就是这么丢的）。
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        val parsed = parseInlineTag(tag)
+        if (open.lastOrNull()?.first == CODE) {
+            // `<code>` 里的一切都是它的内容：`<b>` 是四个字符，也都不算结构（所以里面那个「未闭合的
+            // `<b>`」不会把整段拖成字面）。只有闭合它的 `</code>` 例外。
+            if (parsed == InlineTag.Close(CODE)) {
+                claimed.openStarts.add(open.removeAt(open.lastIndex).second)
+                claimed.closeStarts.add(lt)
+            }
+        } else {
+            when (parsed) {
+                is InlineTag.Open -> open.add(parsed.name to lt)
+                is InlineTag.Close ->
+                    // 落单的闭标签（栈空）、或交错（`</b>` 关不掉栈顶的 `i`）⇒ 整段降级。
+                    if (open.lastOrNull()?.first != parsed.name) return null
+                    else {
+                        claimed.openStarts.add(open.removeAt(open.lastIndex).second)
+                        claimed.closeStarts.add(lt)
+                    }
+
+                null -> Unit
+            }
+        }
+        i = gt + 1
+    }
+    // 还有开标签没配到闭合 ⇒ 整段降级。
+    if (open.isNotEmpty()) return null
+    return claimed
+}
+
+/**
+ * [lt] 处这个 `<` 起头的**行内**标签在哪结束（不是行内标签则 -1）。
+ *
+ * 一路走到 `>` 或**下一个 `<`** 为止：契约要求「属性一律不解析」，标签多长因此不再有上界
+ * （`<b class="…" onclick="…">` 可以很长），W67 那版「只看一扇定宽窗」的做法行不通了。
+ * 仍然刻意**不用** `indexOf('>', lt)` 一路找过去：正文里 N 个落单的 `<` 时那是 O(N²)
+ * （W63 在同一片区域刚踩过这个坑），而且它还会把中间真正的标签一起跳过。
+ * 逐段推进仍是线性的：每次从 `lt + 1` 扫到「下一个 `<`」或串尾，这些区间互不重叠。
+ *
+ * `internal` 是因为**标签边界只该有一把尺子**：分隔符切分层扫 `<br>` 保护区
+ * （`ChatContentParser.protectedSpans`）时也用它，两边若各写一套，「哪儿是一个标签」就会分叉。
+ */
+internal fun inlineTagEnd(text: String, lt: Int): Int {
+    var i = lt + 1
+    while (i < text.length) {
+        when (text[i]) {
+            '>' -> return i
+            '<' -> return -1
+        }
+        i++
+    }
+    return -1
+}
+
+/**
+ * 第二趟：把文本切成片段——被认领的标签消费掉（开/闭标签不入字），其余**逐字**进片段
+ * （白名单外的标签、`<code>` 里的内容、没有被认领的整段标记，都在这里原样吐回）。
+ * 因为第一趟只收严格嵌套的配对，这里的栈与它逐字对应，不会弹错人。
+ */
+private fun runsOf(text: String, claimed: ClaimedTags): List<InlineRun> {
+    val runs = ArrayList<InlineRun>()
+    val piece = StringBuilder()
+    val open = ArrayList<String>()
+    var styles = emptySet<InlineStyle>()
+
+    fun flush() {
+        if (piece.isEmpty()) return
+        val text0 = piece.toString()
+        piece.setLength(0)
+        val last = runs.lastOrNull()
+        if (last != null && last.styles == styles) {
+            runs[runs.lastIndex] = last.copy(text = last.text + text0)
+        } else {
+            runs.add(InlineRun(text0, styles))
+        }
+    }
+
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) {
+            piece.append(text, i, text.length)
+            break
+        }
+        if (lt > i) piece.append(text, i, lt)
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是行内标签（`1 < 2` 里那个 `<`、残缺的 `<b`、属性里带 `<` 的…）：
+            // 把这个字符原样收下、从下一个字符继续。**必须与第一趟用同一把尺子**——这里若改用
+            // `indexOf('>', lt)` 找标签边界，第一趟认下的那对标签就会在这里被当成一个字面整段吞掉
+            // （`1 < 2 <b>甲</b>`）。
+            piece.append('<')
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        when {
+            claimed.openStarts.contains(lt) -> {
+                flush()
+                open.add(openInlineTagName(tag) ?: closeInlineTagName(tag).orEmpty())
+                styles = stylesOf(open)
+            }
+
+            claimed.closeStarts.contains(lt) -> {
+                flush()
+                open.removeAt(open.lastIndex)
+                styles = stylesOf(open)
+            }
+
+            else -> piece.append(tag)
+        }
+        i = gt + 1
+    }
+    flush()
+    return runs
+}
+
+private fun stylesOf(open: List<String>): Set<InlineStyle> =
+    if (open.isEmpty()) emptySet() else open.mapTo(LinkedHashSet(), ::inlineStyleOf)
+
+/** 去掉渲染文本两端的空白，并同步裁掉因此变空的片段——只吃空白，一个可见字符都不会掉。 */
+private fun List<InlineRun>.trimEdges(): List<InlineRun> {
+    var head = 0
+    for (run in this) {
+        val leading = run.text.takeWhile { it.isWhitespace() }.length
+        head += leading
+        if (leading < run.text.length) break
+    }
+    var tail = 0
+    for (i in indices.reversed()) {
+        val trailing = this[i].text.takeLastWhile { it.isWhitespace() }.length
+        tail += trailing
+        if (trailing < this[i].text.length) break
+    }
+    val total = sumOf { it.text.length }
+    val from = minOf(head, total)
+    val to = total - minOf(tail, total - from)
+    return cut(from, to)
+}
+
+/** 按字符下标从两端裁掉（只用于裁空白，所以裁点必然落在片段边界或空白中间）。 */
+private fun List<InlineRun>.cut(from: Int, to: Int): List<InlineRun> {
+    if (from == 0 && to == sumOf { it.text.length }) return this
+    val out = ArrayList<InlineRun>(size)
+    var pos = 0
+    for (run in this) {
+        val start = pos
+        pos += run.text.length
+        val head = maxOf(start, from)
+        val end = minOf(pos, to)
+        if (head < end) out.add(run.copy(text = run.text.substring(head - start, end - start)))
+    }
+    return out
+}
@@ -9,9 +9,30 @@ package top.yeij.cyrene.domain.share
 *
 * 丢件计数按**两条路分开记**（图片 / 文档），因为「本端的接收上限」与「对方给的东西读不到」
 * 是两句不同的话，而图片与文档的上限也不是同一个数。分享进来的内容**不许静默少发**。
+ *
+ * 还有第三件要说的：[contentUnreadable]——对方给了东西、本端**连地址都没认下来**。它连丢件计数
+ * 都留不下（本端一条都没接收），所以单独一格；否则「分享点下去什么都不发生」正是它造成的。
+ *
+ * 正文那一格也多带一件要看的东西：[textSource]——这一段是从 `EXTRA_TEXT` 来的，还是从
+ * `EXTRA_SUBJECT` / `EXTRA_TITLE` **回落**来的。有些发送方根本不填 `EXTRA_TEXT`，本端为此把取正文
+ * 改成一条回落链（[ShareRules.extract]）；而回落来的正文与真正文长得一模一样，用户只能靠这一格分辨。
 */
 data class SharedContent(
+    /**
+     * 这次分享的正文（两侧空白已去掉；全空白算没有正文，见 [ShareRules.extract]）。
+     *
+     * 它可能是从 `EXTRA_SUBJECT` / `EXTRA_TITLE` **回落**来的（有些发送方根本不填 `EXTRA_TEXT`），
+     * 来源记在 [textSource] 里：回落来的那一段与真正文长得一模一样，用户只能靠那一格分辨。
+     */
    val text: String = "",
+    /**
+     * 正文是从哪个 extra 拿到的（默认 [ShareTextSource.Text] = 正文本来就是正文）。
+     *
+     * ⚠️ 它**不参与发送的内容**：这条消息发出去的正文只有 [text] 本身。它的唯一去处是**本端渲染层**
+     * 的那一句如实小字（见 `shareTextOriginNotice`）——回落来的正文必须能让用户察觉，否则「预览里只有
+     * 一句话」会被读成「对方发来的就是这句正文」。
+     */
+    val textSource: ShareTextSource = ShareTextSource.Text,
    val images: List<String> = emptyList(),
    /**
     * 非图片的分享文件。MIME 以 `image/` 开头者走 [images]，其余一律走这一条
@@ -27,6 +48,17 @@ data class SharedContent(
    val truncatedDocuments: Int = 0,
    /** 已接收但**拷贝失败**的文件条数。 */
    val failedDocuments: Int = 0,
+    /**
+     * 这次分享**带着内容迹象**（三个文本 extra 里躺着值、或 `EXTRA_STREAM` 有值、或 `ClipData`
+     * 有条目），却一条可用内容都没提取出来。
+     *
+     * 与 [failedImages] / [failedDocuments] **不是**同一件事：那两个说的是「本端已经认下来的地址
+     * 读不到」（对方给的东西本端拿不动），这里说的是「本端连可用的内容都没认下来」（多为发送方把
+     * `EXTRA_STREAM` 塞成了本端认不出的形态、用本端不读的 scheme，或把正文放在本端认不出的地方）。
+     * 它是**唯一**一种既没有内容、也没有丢件计数的失败形态，所以要单独记一格，否则结局就是
+     * 「用户点了分享、界面毫无反应」。
+     */
+    val contentUnreadable: Boolean = false,
 ) {
    /** 没能落地的总条数。 */
    val droppedImages: Int get() = truncatedImages + failedImages
@@ -36,6 +68,47 @@ data class SharedContent(

    /** 没有任何可发送的内容（此时只剩下丢件计数需要告知）。 */
    val isEmpty: Boolean get() = text.isBlank() && images.isEmpty() && documents.isEmpty()
+
+    /**
+     * 这条分享值不值得继续走：有可落地的内容，或有要对用户说清的事（丢件计数 / 读不进来）。
+     *
+     * 判据只此一处：`ShareIntake.accept` 用它决定要不要往下接，`shareNoticeFor` 用它守卫「什么都没有
+     * 的分享一个字都不说」那条边界——两处必须同一条，否则会出现「接了却不说」或「说了却没接」。
+     * 整条分享里什么都没有（三个文本 extra 都没有值、`EXTRA_STREAM` 也没有值、`ClipData` 也没有条目）
+     * 时它是 `false`：那次分享确实无话可说，静默才是对的。而「有值、只是本端一段都读不出来」（含
+     * 空白与类型不符）**不**属于「什么都没有」：它由调用方以 `textPresent` 如实报进来，正是
+     * [contentUnreadable] 那一格要接的。
+     */
+    val worthDelivering: Boolean
+        get() = !isEmpty || droppedImages > 0 || droppedDocuments > 0 || contentUnreadable
+}
+
+/**
+ * 这次分享的正文**是从哪个 extra 拿到的**。
+ *
+ * ## 为什么要把来源留下来
+ * 真实世界里有些发送方不填 `EXTRA_TEXT`：内容在 `EXTRA_SUBJECT`（少数在 `EXTRA_TITLE`）里。本端
+ * 此前只读 `EXTRA_TEXT`，那条分享因此**整条静默**——用户点了分享，界面毫无反应、也没有一句解释
+ * （正是本项目最忌讳的那种失败）。所以取正文改成一条**回落链**（[ShareRules.extract]）。
+ *
+ * 但「这段字其实只是对方给的标题」必须能让用户分辨：预览里只有一句话时，他会以为对方发来的就是这句
+ * 正文。于是一并记下**来源**，由渲染层如实标一句（`shareTextOriginNotice`）——那句话只出现在界面上，
+ * **绝不**进正文（来源标记不许拼进用户正文是项目红线，见 [ShareRules] 的「为什么正文一个字都不加」）。
+ *
+ * ## 为什么分成三档而不是一个布尔
+ * 三档是**如实登记**对方把内容放在哪个字段里：排查时「这条是从 SUBJECT 还是 TITLE 来的」是要看得见
+ * 的事实，而这两种形态在真实发送方里的出现频率差得很远（SUBJECT 常见、TITLE 罕见）。但两者对用户
+ * 说的是同一句话——标题与主题在用户眼里本来就是同一件事。
+ */
+enum class ShareTextSource {
+    /** `EXTRA_TEXT`：规范路径，也是唯一一条「正文本来就是正文」的路。 */
+    Text,
+
+    /** 从 `EXTRA_SUBJECT` 回落的（对方没给 `EXTRA_TEXT`，或给的是一段空白）。 */
+    Subject,
+
+    /** 从 `EXTRA_TITLE` 回落的。 */
+    Title,
 }

 /**
@@ -85,10 +158,30 @@ fun classifySharedStream(mime: String?): SharedStreamKind {
 * [ACTION_SEND] 收文本 + 一个 URI（图片或文件）；[ACTION_SEND_MULTIPLE] 本端只声明了图片那一类，
 * 所以多选一条实际只可能是图片。URI 走哪条路由 [classifySharedStream] 按 MIME 判。
 *
+ * ## 字符串形态的 `EXTRA_STREAM`（本模块补上的兼容读取）
+ * 真实世界里 `EXTRA_STREAM` 有三种形态：规范推荐的 `Uri`（多选时 `ArrayList<Uri>`）、`String[]`、
+ * `ArrayList<String>`。后两种本模块此前**完全认不出**：`getParcelableExtra` 遇到 `String[]` 只往
+ * logcat 打一句 `ClassCastException`、然后回 `null`，`getParcelableArrayListExtra` 同理，于是整次
+ * 分享**静默落空**——用户点了分享，后端零请求、库里零新增、界面连一句话都没有。历史遗留的发送方与
+ * 跨平台壳应用确实在用这两种形态，所以一并收下。形态分派在 `app/ShareIntake.kt` 的
+ * `shareStreamExtrasOf`（那一步要读 `Intent` 的原始值），这里只管「拿到一串字符串之后怎么用」。
+ *
+ * ⚠️ **字符串形态只认 `content://`**（判据见 [stringStreamUri]）：那是本端**新开**的一条读入口，
+ * 松不得。被拒的条目**逐条跳过**——一次分享里有几条坏的，不该把整次分享废掉。
+ *
+ * ## 正文的回落链（本模块补上的另一条兼容读取）
+ * 真实世界里有发送方**不填** `EXTRA_TEXT`：内容只在 `EXTRA_SUBJECT`（少数在 `EXTRA_TITLE`）里。
+ * 本端此前只读 `EXTRA_TEXT`，那样一次分享因此**整条静默**——用户点了分享，界面毫无反应、也没有一句
+ * 解释。所以取正文改成 `EXTRA_TEXT` → `EXTRA_SUBJECT` → `EXTRA_TITLE` 的**回落链**（[extract]），
+ * 来源记在 [SharedContent.textSource] 里，由渲染层如实标一句（见 [ShareTextSource]）。
+ *
 * ## 为什么正文一个字都不加
 * **绝不**往用户正文里拼「[用户分享]」之类的来源标记：来源标识走后端的独立 `RoleSystem`
 * 来源消息 + 结构化 `SenderName`（`02/F4` / `design/11 §10`），人类可见的标记只能放在本端
 * 渲染层。把标记拼进正文 = 让用户正文冒充系统指令，是项目红线。分享进来的正文**原样**发出。
+ *
+ * 回落来的正文（从 `EXTRA_SUBJECT` / `EXTRA_TITLE` 取到的那一段）同样**原样**发出：来源提示是界面
+ * 上的一句小字，**不是**正文的一部分——所以面板里那段预览与真正发出去的那条消息逐字相同。
 */
 object ShareRules {

@@ -116,19 +209,99 @@ object ShareRules {
     */
    const val MAX_DOCUMENTS = 5

+    /**
+     * 图片超限的那一句（**纯函数**）：**分享入口与图片选择入口共用同一句**，所以它只有一个出处。
+     *
+     * 两个入口的上限本来就是同一个数（[MAX_IMAGES]）⇒ 告知也必须是同一句：各写一句，迟早会出现
+     * 「分享说只发前 4 张、选图说只发前 4 张（措辞不同）」这种同一件事的两种说法。
+     *
+     * ## 措辞**入口中性**（主人 2026-10-06 拍板）
+     * W42 把图片按钮改成多选之后，这一句不止在分享那条路上出现——图片入口里根本没有「分享」
+     * 这件事。原句以「**分享的**图片」开头，那是一句只对其中一条路成立的限定（在图片入口里读着
+     * 像在说别人的事），所以句子不再指认动作的来处：只说三件两条路都成立的事实——**有上限**
+     * （[MAX_IMAGES] 张）、**超出的没发**、**发出去的是前 N 张**。也刻意不写「失败」「错误」：
+     * 被上限截掉不是一次错误，是上限本身。
+     *
+     * @param kept 这次真正发出去的张数（`SharedContent.images` 的长度 / `ImageSendPlan.imagesToSend` 的长度）
+     * @param dropped 被上限截掉的张数；0 ⇒ `null`（一张没少就没什么要说的，说话才是噪声）
+     */
+    fun truncatedImagesNotice(kept: Int, dropped: Int): String? =
+        if (dropped > 0) "一次最多 $MAX_IMAGES 张，超出的没发，只发送前 $kept 张" else null
+
+    /**
+     * 一次「批量投递」里，第 [index] 条要不要声明「她忙时发消息」那个偏好（`interrupt` / `parallel`）。
+     *
+     * ## 两个事实合起来只剩两种答案
+     * - **分享一次都不声明**（[fromShare]）：分享是「一次把东西倒进去」，N 张图就是 N 条消息；对每张
+     *   图各声明一次，第 2 条就会把第 1 条刚起的回合打掉——**批量动作自相残杀**。这是本端自己的判断
+     *   （后端口径 `02` F4：他们那边不需要做任何事）。
+     * - **手打那条只声明第一条**（`index == 0`）：一次发送切出来的第 2 条起若也声明，同样是在打断
+     *   自己刚起的上一轮。声明的是「这一次投递要怎样对待正在进行的回合」，一次发送只该有**一个**
+     *   这样的意思。
+     *
+     * 于是答案只有 `false`（分享，恒成立）与「只有第 0 条成立」（手打）两种形态。
+     *
+     * ## 为什么提成一个纯函数
+     * 这条边界原先散在 `ChatViewModel` 里（`applySendPreference && index == 0`，分享那条入口另传
+     * `false`）：两处各是半个判据、**一处都单测不到**，而「分享多图绝不互相打断」正是 W76 要一直
+     * 成立的那条边界（见 `05` 的多图自相打断一节）。合并成一处判据之后，入口与投递口用的必须是
+     * 同一条——与 `hasSendableContent`（`ui/chat/SendQueue.kt`）的情形完全一样。口径也与
+     * [truncatedImagesNotice] 一致：两条入口共用的规则，只有一个出处。
+     *
+     * @param fromShare 这条（这一批）是不是分享进来的
+     * @param index 在这次发送切出的消息里的位置（0 = 第一条）
+     */
+    fun declaresSendPreference(fromShare: Boolean, index: Int): Boolean = !fromShare && index == 0
+
    /**
     * 从分享 Intent 的原始字段提取内容。
     *
-     * URI 的取值顺序是 `EXTRA_STREAM` → `ClipData`：前者是契约路径，后者是兜底——确实有
-     * App（尤其旧版本）只填 `ClipData` 而不填 `EXTRA_STREAM`，只认前者会让分享静默落空。
-     * 两者都有时**只取前者**，不会把同一张图数两遍。
+     * ## 正文的回落链：`EXTRA_TEXT` → `EXTRA_SUBJECT` → `EXTRA_TITLE`
+     * 取**第一个非空白**的那一段当正文（口径与原先只读 `text` 时**完全一致**：两侧去空白、全空白算
+     * 没有）；来源记在 [SharedContent.textSource] 里，好让渲染层如实说一句（见 [ShareTextSource]）。
+     *
+     * 为什么要有这条链：真实世界里有些发送方**不填** `EXTRA_TEXT`，内容只在 `EXTRA_SUBJECT`
+     * （少数在 `EXTRA_TITLE`）里。此前只读 `EXTRA_TEXT` ⇒ 那样一次分享**整条静默**——用户点了分享，
+     * 界面毫无反应，后端零请求，也没有一句解释。前后两种口径的对外差别只有一个：**`EXTRA_TEXT`
+     * 非空时回落链一定不生效**（它是第一站），所以既有情形的结果一个字都没变。
+     *
+     * ## 三个文本 extra 都没换来正文时**不许闭嘴**
+     * 只要三个里**任意一个躺着原始值**（哪怕是一段空白、哪怕类型读不出来），这一次就不是「用户什么都
+     * 没分享」，而是「本端什么都没读出来」——[SharedContent.contentUnreadable] 如实告知，绝不静默。
+     * 「里面躺着值」这件事只有调用方知道（纯函数看不到原始值），所以由 [textPresent] 报进来，与
+     * [streamPresent] 同一个形态。
+     *
+     * ## 优先顺序与去重（一次分享里多种来源并存时）
+     * 顺序 = `EXTRA_STREAM` 的规范形态（[stream] 在前、[streams] 在后）→ 字符串兼容形态（保持原顺序）
+     * → `ClipData`（只在前两者一条都没认下时兜底）。同一个地址串被两处各给一次时**只留先到的那一条**：
+     * 先 trim、去空、去重，再按 MIME 分流、再各自套上限——重复项既不该把真图挤到上限之外，也不该
+     * 被算成「截掉了 N 条」。**先来的先算**这条在字符串形态上尤其要紧：发送方给的顺序就是它给的顺序。
+     *
+     * `ClipData` 只在 `EXTRA_STREAM` 一条都没认下时才用（既有口径）：两者都有时只取前者，不会把同一张
+     * 图数两遍。
     *
     * @param action `Intent.action`；只认 [ACTION_SEND] / [ACTION_SEND_MULTIPLE]
     * @param text `EXTRA_TEXT`——按 `CharSequence` 收，因为它常常是 `Spanned`（带样式的
-     *   HTML 富文本），读成 `String` 会直接拿到 `null`
-     * @param stream `EXTRA_STREAM`（[ACTION_SEND] 的单条 URI 字符串）
-     * @param streams `EXTRA_STREAM`（[ACTION_SEND_MULTIPLE] 的 URI 列表）
-     * @param clipUris `ClipData` 各条目的 URI；文本类条目没有 URI，会被自动忽略
+     *   HTML 富文本），读成 `String` 会直接拿到 `null`。**回落链的第一站**
+     * @param subject `EXTRA_SUBJECT`——第二站。发送方「对象 / 标题」那个字段，正是有些 App 拿来放
+     *   正文的地方（`EXTRA_TEXT` 一个值都没有）
+     * @param title `EXTRA_TITLE`——第三站（少见，但真实发送方里确实有）
+     * @param stream `EXTRA_STREAM` 的单值形态（[ACTION_SEND] 那个只放一条的字段）
+     * @param streams `EXTRA_STREAM` 的列表形态（[ACTION_SEND_MULTIPLE] 的字段）
+     * @param streamStrings `EXTRA_STREAM` 的**字符串兼容形态**（`String` / `String[]` /
+     *   `ArrayList<String>` 摊平后的值，形态分派在 `app/ShareIntake.kt`）。这一档每条都要过
+     *   [stringStreamUri] 的白名单，被拒的**逐条跳过**；调用方给的是原样值（还没过滤），
+     *   所以「有值但一条都不能用」这件事这里看得见——它就是 [SharedContent.contentUnreadable]
+     *   要说的那种情形。
+     * @param streamPresent `EXTRA_STREAM` 里确实躺着**原始值**——由调用方读了原始值判出来（本函数
+     *   看不到那个值），含本端**认不出形态**的那种。它只有一个用处：形态认不出时本端既不猜、也不该
+     *   因此闭嘴，那照样是一次「带着内容迹象却什么都没读进来」。
+     * @param textPresent 三个文本 extra（[text] / [subject] / [title]）里**至少一个躺着原始值**——
+     *   同样由读了原始值的调用方判出来，含**读不出类型**与**只是一段空白**的那两种（`textPresent`
+     *   与 [streamPresent] 一样是「原料里有」「认下来的内容里没有」，用后者判会把「有值但读不出来」
+     *   误当成「什么都没分享」）。正文一旦读出来（哪怕是从标题回落的）它就不起作用了。
+     * @param clipUris `ClipData` 各条目的 URI，纯文本条目是 `null`（本端**不读** `ClipData` 里的
+     *   文本，所以「只有纯文本条目」等同于「读不进来」，用来判 [SharedContent.contentUnreadable]）
     * @param mimeOf 取一条 URI 的 MIME（Android 侧就是 `ContentResolver.getType`）。本函数是
     *   **纯函数**，所以类型判定由调用方注入；默认「拿不到类型」⇒ 按文档路走
     *   （见 [classifySharedStream]，默认值就是「不猜」）。
@@ -136,26 +309,44 @@ object ShareRules {
    fun extract(
        action: String?,
        text: CharSequence? = null,
+        subject: CharSequence? = null,
+        title: CharSequence? = null,
        stream: String? = null,
        streams: List<String>? = null,
-        clipUris: List<String> = emptyList(),
+        streamStrings: List<String> = emptyList(),
+        streamPresent: Boolean = false,
+        textPresent: Boolean = false,
+        clipUris: List<String?> = emptyList(),
        mimeOf: (String) -> String? = { null },
    ): SharedContent {
        val recognized = action == ACTION_SEND || action == ACTION_SEND_MULTIPLE
        if (!recognized) return SharedContent()

-        val body = text?.toString().orEmpty().trim()
-
-        val primary = when (action) {
-            ACTION_SEND -> listOfNotNull(stream)
-            else -> streams.orEmpty()
+        // 回落链（见 KDoc）：三段一起按同一个口径归一（`toString` → 两侧 trim → 非空才算有），
+        // 取先到的那个**非空白**值。`EXTRA_TEXT` 非空时它一定赢 ⇒ 既有情形逐字不变。
+        val picked = listOf(
+            ShareTextSource.Text to text,
+            ShareTextSource.Subject to subject,
+            ShareTextSource.Title to title,
+        ).firstNotNullOfOrNull { (source, value) ->
+            value?.toString()?.trim()?.takeIf(String::isNotEmpty)?.let { source to it }
        }
-        // 空串条目（有的 App 会塞占位）与重复条目都要去掉：不然「4 张图」里可能只剩 2 张真图，
-        // 而截断计数还会把占位算成一张。
-        val unique = primary.ifEmpty { clipUris }
+        val body = picked?.second.orEmpty()
+        val textSource = picked?.first ?: ShareTextSource.Text
+
+        // 两个字段一并收：单值 / 列表是历史形态（当年靠 getParcelableExtra 与
+        // getParcelableArrayListExtra 两个读法分开取，才不得不按 action 二选一），
+        // 本端现在只关心「有哪些地址」，重复的由下面的 distinct 收掉。
+        val uriForms = listOfNotNull(stream) + streams.orEmpty()
+        val primary = (uriForms + streamStrings.mapNotNull(::stringStreamUri))
            .map(String::trim)
            .filter(String::isNotEmpty)
            .distinct()
+        // 空串条目（有的 App 会塞占位）与重复条目都要去掉：不然「4 张图」里可能只剩 2 张真图，
+        // 而截断计数还会把占位算成一张。
+        val unique = primary.ifEmpty {
+            clipUris.filterNotNull().map(String::trim).filter(String::isNotEmpty).distinct()
+        }

        val images = mutableListOf<String>()
        val documents = mutableListOf<String>()
@@ -166,17 +357,72 @@ object ShareRules {
            }
        }

+        // 「带着内容迹象」的判据取的是**原料**（三个文本 extra 里躺着的原始值 / EXTRA_STREAM 里躺着的
+        // 原始值 / ClipData 的条目数），不是「认下来的内容」——「有值但一条都认不出」正是要说的那种
+        // 情形，用后者判反倒会把它当成「什么都没分享」而闭嘴。
+        val hadStreamValue = streamPresent ||
+            !stream.isNullOrBlank() ||
+            streams.orEmpty().any(String::isNotBlank) ||
+            streamStrings.any(String::isNotBlank)
+
        return SharedContent(
            text = body,
+            textSource = textSource,
            images = images.take(MAX_IMAGES),
            // 提取阶段还不知道显示名与大小（要 ContentResolver），先放原样 URI；
            // ShareIntake 拷进 cache 后再换成 file:// + 显示名 + 真实字节数。
            documents = documents.take(MAX_DOCUMENTS).map { SharedDocument(uri = it) },
            truncatedImages = (images.size - MAX_IMAGES).coerceAtLeast(0),
            truncatedDocuments = (documents.size - MAX_DOCUMENTS).coerceAtLeast(0),
+            contentUnreadable = unique.isEmpty() && body.isEmpty() &&
+                (hadStreamValue || textPresent || clipUris.isNotEmpty()),
        )
    }

+    /**
+     * 字符串形态的一条候选地址 ⇒ 可用的地址（trim 之后），不可用回 `null`。
+     *
+     * ## 为什么字符串形态只认 `content://`（安全纪律）
+     * 字符串形态是本端**新开**的一条读入口：送进来的只是一段文本，没有任何框架级的担保（`Uri` /
+     * `ArrayList<Uri>` 那两个形态至少是对方用 URI **对象**写进去的，而 `EXTRA_STREAM` 里的字符串
+     * 往往是从别处转发来的——网页给的、壳应用拼的）。所以这条入口开得窄：
+     *
+     * - `content://` ⇒ 收下。这是 AOSP 推荐的形态，读权限随这次分享由框架授予。
+     * - `file://` ⇒ **拒**。那等于让发送方替本端指定一个本地路径、由本端拿**自己的**权限去读它
+     *   （本应用私有目录也在其中），而分享的语义是「用户选中的东西」，不是「别人给的任意路径」。
+     *   何况 Android 13 起跨应用读外部存储的 `file://` 基本已不通，收下来多半也只是变成一次失败。
+     * - `http(s)://` ⇒ **拒**。那是网络地址不是本地字节源：收下它等于让第三方的一行文本指定一个 URL、
+     *   由本应用代它去取，而那条取法在本端没有任何既有的授权 / 体积 / 超时约束。
+     * - 其余（`javascript:` / `intent:` / 自定义 scheme / 没有 scheme 的裸路径 / 空串）⇒ **拒**。
+     *
+     * 被拒的条目由调用方逐条跳过（见 [extract]）：一次分享里有几条坏的，不该把整次分享废掉；
+     * 一条可用地址都没剩下时由 [SharedContent.contentUnreadable] 如实告知。
+     *
+     * 判 scheme 用的是 RFC 3986 的形态（首字符字母，其后字母 / 数字 / `+` `-` `.`），与 `Uri.parse`
+     * 认 scheme 的口径一致；本函数是纯的（`domain/share` 不碰 Android 类型）。
+     */
+    fun stringStreamUri(raw: String): String? {
+        val trimmed = raw.trim()
+        val scheme = schemeOf(trimmed) ?: return null
+        return trimmed.takeIf { scheme.equals(CONTENT_SCHEME, ignoreCase = true) }
+    }
+
+    /** 本端唯一收下的 scheme（理由见 [stringStreamUri]）。 */
+    private const val CONTENT_SCHEME = "content"
+
+    /** 一条地址的 scheme（按 RFC 3986 的形态判，大小写不敏感地在调用方比）；没有 scheme 回 `null`。 */
+    private fun schemeOf(raw: String): String? {
+        val colon = raw.indexOf(':')
+        if (colon <= 0) return null
+        val head = raw.substring(0, colon)
+        val first = head[0]
+        if (first !in 'a'..'z' && first !in 'A'..'Z') return null
+        val usable = head.drop(1).all {
+            it in 'a'..'z' || it in 'A'..'Z' || it in '0'..'9' || it == '+' || it == '-' || it == '.'
+        }
+        return head.takeIf { usable }
+    }
+
    /**
     * 落盘文件名：**只由本端生成**的 [token] 与序号 [index] 拼成，扩展名取自 MIME 白名单
     * （不在表里就回落 `.img`——真正的类型由字节嗅探裁决，不靠扩展名）。
@@ -75,14 +75,18 @@ data class AdminOverviewData(
 * 但它**读得到**日志历史（[canReadObservabilityLogHistory]），所以概览页上它照样看得到
 * 「最近日志」，只是那份列表不增长——这不是错误也不是空态。
 *
- * ## 为什么本类自己开一条 WS 连接
- * `observability_*` 三帧在 WS 上，而 `AppContainer` 只提供 `createChatSocket()`
- * （**每次调用新建**，没有进程级共享连接），`ChatSocket` / 聊天侧却都在别的改动范围里。
- * 要在这里收帧，唯一不改别人的办法就是自持一条连接——与 `SessionsViewModel` 同一做法，
- * 也**同一笔已知技术债**（「每 VM 一条 socket」，收敛方向是「一条应用级共享 socket +
- * 按会话路由」，见 `devdocs/05`；那个重构不在本模块内）。
+ * ## WS 连接：全 App 共享一条，本类**不持有**它
+ * `observability_*` 三帧在 WS 上，而 WS 是**进程内共享**的那一条（`AppContainer.chatSocket`；
+ * 为什么可以共享见那里的 KDoc——服务端广播 ⇒ 各 VM 各收全部帧 ⇒ 过滤逻辑一个字都不用改）。
+ * 本类只订阅它，**不再自己开一条**。
+ *
+ * **本类任何路径都不 connect / close 它**：
+ * - 该不该连着由**登录态**决定，主人是 `SessionsViewModel`（它一进登录态就存在，且活在 Activity 级
+ *   `ViewModelStore` 里）；本类只在**某个屏幕**出现时才创建，让它插一手就会把「关掉管理页」
+ *   变成「关掉全 App 的连接」；
+ * - `viewer` 也不会因此断连：这三帧服务端本就 fail-closed，本类又用 [canReceiveObservabilityFrames]
+ *   逐帧再挡一次（见 [onEvent]），所以「连接在不在」与「本类收不收到」无关。
 *
- * 生命周期：登录且角色够档时连接、登出（或角色降档）断开、VM 销毁断开（[onCleared]）。
 * 本类只关心这三个帧类型，收不到也不会让功能失效——REST 会兜住。
 */
 class AdminViewModel(private val container: AppContainer) : ViewModel() {
@@ -99,8 +103,11 @@ class AdminViewModel(private val container: AppContainer) : ViewModel() {
    private val _backthink = MutableStateFlow(AdminUiState<List<AdminBackthinkItemDto>>())
    val backthink: StateFlow<AdminUiState<List<AdminBackthinkItemDto>>> = _backthink.asStateFlow()

-    /** 本 VM 自持的那条推送连接；见类注释。 */
-    private val socket: ChatSocket = container.createChatSocket()
+    /**
+     * 全 App 共享的那条推送连接：本类只订阅它，**不连接也不关闭**（理由见类注释——
+     * 它的主人是「登录态」那条路径，不是某个屏幕）。
+     */
+    private val socket: ChatSocket = container.chatSocket

    init {
        viewModelScope.launch {
@@ -108,22 +115,20 @@ class AdminViewModel(private val container: AppContainer) : ViewModel() {
                when (auth) {
                    SessionState.Unknown -> Unit

-                    // 登出：断开连接并丢掉日志基线（`null` = 没有基线 ⇒ 区块立刻整段收起），
-                    // 不留下一个换账号后还挂着上个账号数据的列表。
+                    // 登出：只丢掉日志基线（`null` = 没有基线 ⇒ 区块立刻整段收起），不留下一个换账号后
+                    // 还挂着上个账号数据的列表。**不碰连接**——那是登录态那条路径的事（见类注释），
+                    // 这时主会话的流式与抽屉的未读都还挂着它。
                    SessionState.LoggedOut -> {
-                        socket.close()
                        _overview.update { state ->
                            state.copy(data = state.data?.copy(logs = null))
                        }
                    }

-                    // 连接只在「登录 + 角色够档」时建立：viewer 收不到这三帧（服务端 fail-closed），
-                    // 也就没有必要开一条连接去等。角色可能随重登变化，所以这里两个分支都要显式写。
-                    is SessionState.LoggedIn -> if (canReceiveObservabilityFrames(AdminRole.of(auth.role))) {
-                        socket.connect()
-                    } else {
-                        socket.close()
-                    }
+                    // 登录：**什么都不做**。连接该不该在由登录态决定（主人是 `SessionsViewModel`）；
+                    // `viewer` 也不再因此断开——它收不到这三帧是服务端 fail-closed，本类另有
+                    // [canReceiveObservabilityFrames] 逐帧再挡一次（见 [onEvent]），断开连接并不能
+                    // 多挡掉什么，却会掐掉别的屏幕。
+                    is SessionState.LoggedIn -> Unit
                }
            }
        }
@@ -131,8 +136,12 @@ class AdminViewModel(private val container: AppContainer) : ViewModel() {
        viewModelScope.launch { reloadOnConnect() }
    }

+    /**
+     * **刻意不关连接**：`socket` 是**全 App 共享**的那一条，而本 VM 只随「离开管理页 / Activity 结束」
+     * 被销毁——在 `onCleared` 里 close 会把主会话的流式与抽屉的未读一起掐断。
+     * 断开只由**登录态**表达（见类注释）。
+     */
    override fun onCleared() {
-        socket.close()
        super.onCleared()
    }

@@ -13,6 +13,7 @@ import androidx.lifecycle.viewmodel.initializer
 import androidx.lifecycle.viewmodel.viewModelFactory
 import kotlinx.coroutines.delay
 import top.yeij.cyrene.app.AppContainer
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
 import top.yeij.cyrene.ui.admin.AdminHomeScreen
 import top.yeij.cyrene.ui.common.MiuixDrawer
 import top.yeij.cyrene.ui.sessions.SessionDrawerContent
@@ -27,8 +28,10 @@ private const val SESSION_GONE_NOTICE_MILLIS = 8_000L
 * 会话在别处被删掉时那句如实告知。
 *
 * 它必须由**这一层**持有，不能挂在 `ChatViewModel` 上：`onSessionGone` 一被调用，
- * `activeSessionId` 就会被收敛回主会话，那个会话的 VM 连同它的状态**立刻被销毁**，
- * 挂在上面的横幅一个字都来不及显示（真机实测过）。这一层的 `remember` 活得比它久。
+ * `activeSessionId` 就会被收敛回主会话，ChatScreen 的槽位（与 VM key 里的会话 id）随之变化 ——
+ * 于是**承载横幅的那段组合被销毁重建**；而那个 VM 这会儿正被交出去（本端删除那条路走
+ * `SessionsViewModel.deleteSession` 里的 `ChatSessionSlots.reclaim`，别处删除这条走 404 收敛），
+ * 挂在它状态上的横幅连这一帧都活不过。这一层的 `remember` 活得比它久。
 */
 private const val SESSION_GONE_MESSAGE = "这个会话在服务端已经不存在了（可能已在别处删除），已切回主会话"

@@ -52,7 +55,7 @@ fun ChatHomeScreen(
    var showAbout by remember { mutableStateOf(false) }

    // 当前会话在别处被删掉时那句告知（见 [SESSION_GONE_MESSAGE]）。放在这一层是因为承载它的
-    // 会话 VM 会在切回主会话的瞬间被销毁。
+    // 那段组合（ChatScreen）会在切回主会话的瞬间被销毁重建，而这里的 remember 活得比它久。
    var sessionNotice by remember { mutableStateOf<String?>(null) }

    LaunchedEffect(sessionNotice) {
@@ -62,6 +65,22 @@ fun ChatHomeScreen(
        }
    }

+    // 「点她那条通知进来 ⇒ 看主会话」（W53N）。意图活在进程里（通知可能在 App 还没起来、甚至还没
+    // 登录时就被点，见 ProactiveTapIntake），这里只负责把它落地成用户能看见的两件事：
+    // 回到聊天页、并切到主会话。走的是用户点抽屉里那一行的同一条路（select），不另造机制。
+    val pendingProactiveTap by container.proactiveTapIntake.openMainSession.collectAsState()
+    LaunchedEffect(pendingProactiveTap) {
+        if (!pendingProactiveTap) return@LaunchedEffect
+        container.proactiveTapIntake.consume()
+        // 通知说的是「她刚在主会话里说话」，所以落点必须是**那一页**：设置页 / 管理页 / 关于 /
+        // 抽屉还开着的话，用户点进来看到的仍是它们，这条通知就等于没兑现。
+        drawerOpen = false
+        showAbout = false
+        showSettings = false
+        showAdmin = false
+        sessionsViewModel.select(SessionSummaryDto.MAIN_SESSION_ID)
+    }
+
    BackHandler(enabled = showAdmin) { showAdmin = false }
    // 「关于」嵌在设置页里，所以两个条件必须**互斥**：在关于页时设置页的处理器关掉，
    // 返回才只退一层（关于 → 设置），不会一步跳回聊天。
@@ -100,15 +119,23 @@ fun ChatHomeScreen(
                        // 静默是为了不闪「同步中…」——屏幕上本来就有内容。
                        sessionsViewModel.refresh(silent = true)
                    },
-                    onLogout = onLogout,
                    // 当前会话在别处被删了（`404 session_not_found`）⇒ 先立起那句如实告知，再重拉列表：
                    // `refresh` 里面会把「指向已删会话」的 activeSessionId 收敛回主会话
-                    // （`resolveActiveSession`），抽屉里那条也跟着消失。所以这里不需要自己判「该切到哪儿」。
+                    // （`resolveActiveSession`），抽屉里那条也跟着消失。
                    //
-                    // 顺序很重要：告知必须**先**立起来再刷新——刷新会让本层的 ChatScreen 换 key、
-                    // 把那个会话的 VM 销毁掉，晚一步就什么都看不到了。
+                    // 顺序很重要：告知必须**先**立起来再刷新——刷新会让本层的 ChatScreen 换 key，
+                    // 那段组合连同挂在 VM 状态上的东西一起被丢弃重建，晚一步就什么都看不到了。
+                    //
+                    // ⚠️ 但**不能只靠 `refresh` 把用户送回去**：它只在**拉成功**时才做回落
+                    // （`resolveActiveSession`，且列表为空时刻意不回落；`.onFailure` 那条更是什么都不动）。
+                    // 于是「网络正不稳 / 服务端正好抖一下」时，屏幕上那句「已切回主会话」就成了一句
+                    // 做不到的话——用户被留在一个已经没了的会话上，没有任何出路。这正是这个告知
+                    // 想要修掉的那一幕，所以这里**先在本端收敛**（`select` 是用户点抽屉里那一行走的
+                    // **同一条**路，不另造机制），`refresh` 退回它本来的职责：与服务端对齐、把抽屉
+                    // 里那条去掉。副作用与用户手点主会话进入时逐字相同（就地清未读 + 推进游标）。
                    onSessionGone = {
                        sessionNotice = SESSION_GONE_MESSAGE
+                        sessionsViewModel.select(SessionSummaryDto.MAIN_SESSION_ID)
                        sessionsViewModel.refresh(silent = true)
                    },
                    sessionNotice = sessionNotice,
@@ -125,6 +152,7 @@ fun ChatHomeScreen(
                    onDelete = { sessionsViewModel.deleteSession(it.id) },
                    onTogglePin = { sessionsViewModel.setPinned(it.id, !it.pinned) },
                    onRename = { sessionId, title -> sessionsViewModel.renameSession(sessionId, title) },
+                    onStopGenerating = { sessionsViewModel.stopGenerating(it.id) },
                    onOpenIot = { /* P2：IoT 页面 */ },
                    onOpenAdmin = {
                        drawerOpen = false
@@ -134,6 +162,7 @@ fun ChatHomeScreen(
                        drawerOpen = false
                        showSettings = true
                    },
+                    onDismissError = sessionsViewModel::dismissError,
                )
            },
        )
@@ -22,7 +22,9 @@ import androidx.compose.ui.window.Dialog
 import top.yeij.cyrene.data.repository.CachedDocument
 import top.yeij.cyrene.domain.chat.DocumentPreview
 import top.yeij.cyrene.domain.chat.DocumentPreviewPlan
+import top.yeij.cyrene.domain.chat.DocumentSource
 import top.yeij.cyrene.domain.chat.DocumentTarget
+import top.yeij.cyrene.domain.chat.PreviewMetadata
 import top.yeij.cyrene.domain.chat.PreviewSlice
 import top.yeij.cyrene.ui.common.PreferenceCard
 import top.yukonga.miuix.kmp.basic.BasicComponent
@@ -85,6 +87,15 @@ data class DocumentPreviewNotice(val message: String, val error: Boolean = false
 * [PreviewSlice.notice] 非空时在正文上方明写「只显示前 N」并指路另外两条出口——**绝不静默
 * 截断**：用户看到一段像是完整的正文却其实是前 256 KB，是最容易被误读的一种失败。
 *
+ * ## 正文下方那一行元数据
+ * 正文（非文本时是那句人话）**下方**还有一行灰色小字，写的是「这份文件是什么」的格式事实：
+ * 文本给行数 / 字符数（带口径）/ 解码口径 / 服务端的截断标记，非文本给服务端嗅探所得的 mime。
+ * 组装全在纯函数 [PreviewMetadata] 里（**「为什么某一项不显示」也写在那里**），这里只取证据、画一行。
+ *
+ * 它与上方那枚芯片刻意**不重复**：体积与服务端状态芯片上已经写着（同一个数字、同一个词，再写
+ * 一遍只是噪音）；字符数虽然也在芯片上，但芯片那个「8,000 字」没说清是谁的口径——本行补上
+ * 「（服务端注入口径）」，这才不算一句会把用户带偏的话。
+ *
 * @param target 被点开的那一枚芯片（来源判定见 [DocumentTarget.of]，弹层不自己判断）。
 * @param plan 正文区能不能按文本渲染（[DocumentTarget.previewPlan] 的产物，弹层不自己判断）。
 * @param notice 「用其它应用打开 / 保存」这一步的如实告知（没有 App 能开、保存成功或失败）；
@@ -135,22 +146,25 @@ fun DocumentPreviewDialog(
                    TextButton("重试", onClick = onRetry)
                }

-                is DocumentPreviewState.Ready -> when (plan) {
-                    DocumentPreviewPlan.Text -> {
-                        state.slice.notice?.let { text ->
-                            Text(
-                                text = text,
-                                style = MiuixTheme.textStyles.footnote2,
-                                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
-                                modifier = Modifier.padding(bottom = 8.dp),
-                            )
+                is DocumentPreviewState.Ready -> {
+                    when (plan) {
+                        DocumentPreviewPlan.Text -> {
+                            state.slice.notice?.let { text ->
+                                Text(
+                                    text = text,
+                                    style = MiuixTheme.textStyles.footnote2,
+                                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                                    modifier = Modifier.padding(bottom = 8.dp),
+                                )
+                            }
+                            PreviewBody(state.slice)
                        }
-                        PreviewBody(state.slice)
-                    }

-                    // 非文本：**正文区留空**，只留那句人话。字节其实已经取回来了（两条出口要用），
-                    // 只是本端不会渲染它——把 PDF 的字节按 UTF-8 显示出来就是一屏乱码。
-                    is DocumentPreviewPlan.NotText -> PreviewHint(plan.message)
+                        // 非文本：**正文区留空**，只留那句人话。字节其实已经取回来了（两条出口要用），
+                        // 只是本端不会渲染它——把 PDF 的字节按 UTF-8 显示出来就是一屏乱码。
+                        is DocumentPreviewPlan.NotText -> PreviewHint(plan.message)
+                    }
+                    PreviewMetadataLine(state = state, plan = plan, target = target)
                }
            }

@@ -199,6 +213,50 @@ fun DocumentPreviewDialog(
    }
 }

+/**
+ * 正文**下方**那一行灰色小字：关于这份文件的格式元数据（[PreviewMetadata] 的产物）。
+ *
+ * 组装全在纯函数里（逐档穷举单测），这里只做两件事：**取证据**、**画一行**。
+ * 取证据的两处来源都不许在 UI 层临场发挥：
+ * - 服务端那两件事实（注入字数 / 注入是否被截断）从[芯片模型][DocumentChipModel]里取——
+ *   它就是 DTO 那几字段的唯一换算落点（[DocumentChips.of]）；
+ * - 嗅探所得的 mime 只从 [DocumentSource.Server.mime] 取。本地待发附件**没有**这个结论
+ *   （那时还没上传过），所以它这一项缺席——**不拿扩展名编一个**（`DocumentTarget.openType()`
+ *   对本地来源回的是 `application/octet-stream` 这个兜底值，拿它当「类型」会是本端编的话）。
+ *
+ * 拼出来是空串时**整行不画**（一项证据都没有就没有这一行），绝不留一个空行或一排「未知」。
+ */
+@Composable
+private fun PreviewMetadataLine(
+    state: DocumentPreviewState.Ready,
+    plan: DocumentPreviewPlan,
+    target: DocumentTarget,
+) {
+    val items = remember(state.slice, plan, target) {
+        when (plan) {
+            // 文本：行数 / 字符数（带口径）/ 解码口径 / 服务端的截断标记。
+            // `truncatedLabel` 非空 ⟺ DTO 的 `truncated == true`（见 DocumentChipModel）。
+            DocumentPreviewPlan.Text -> PreviewMetadata.textItems(
+                slice = state.slice,
+                serverCharsLabel = target.chips.charsLabel,
+                contextTruncated = target.chips.truncatedLabel != null,
+            )
+
+            // 非文本：只有服务端嗅探所得的 mime（体积与状态已在上面那枚芯片里）。
+            is DocumentPreviewPlan.NotText ->
+                PreviewMetadata.fileItems((target.source as? DocumentSource.Server)?.mime)
+        }
+    }
+    val line = PreviewMetadata.join(items)
+    if (line.isEmpty()) return
+    Spacer(Modifier.height(10.dp))
+    Text(
+        text = line,
+        style = MiuixTheme.textStyles.footnote2,
+        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+    )
+}
+
 /** 正文区：按行分块、逐块可选中，块数上限由 [DocumentPreviewLimits] 保证。 */
@Composable
 private fun PreviewBody(slice: PreviewSlice) {
@@ -54,6 +54,7 @@ import top.yeij.cyrene.domain.chat.ImageOpenTypes
 import top.yeij.cyrene.domain.chat.ImageSize
 import top.yeij.cyrene.domain.chat.ImageSource
 import top.yeij.cyrene.domain.chat.ImageZoom
+import top.yeij.cyrene.domain.chat.PreviewMetadata
 import top.yeij.cyrene.domain.chat.ZoomPan
 import top.yeij.cyrene.domain.chat.imageLoadFailureMessage
 import top.yeij.cyrene.ui.common.PreferenceCard
@@ -145,6 +146,28 @@ fun ImagePreviewDialog(
        )
    }

+    // 预览内容下方那一行元数据要用的事实：像素与 EXIF 拍摄日期都得先读字节，所以放到 IO 上算。
+    // 键是**那一份缓存**：换一张图（或重试拿回新的字节）才重算，重组不会。
+    val facts by produceState(
+        initialValue = PreviewImageFacts(),
+        key1 = (state as? ImagePreviewState.Ready)?.cached,
+    ) {
+        val cached = (state as? ImagePreviewState.Ready)?.cached ?: return@produceState
+        value = withContext(Dispatchers.IO) { readPreviewImageFacts(cached.bytes) }
+    }
+    val ready = state as? ImagePreviewState.Ready
+    val metadata = PreviewMetadata.join(
+        PreviewMetadata.imageItems(
+            // 「图片通配」不是格式：嗅探与平台声明都判不出来时这一项就缺席，
+            // **不拿 `image/*` 冒充一个答案**。
+            mime = ready?.openType?.takeIf { it != ImageOpenTypes.ANY_IMAGE },
+            width = facts.width,
+            height = facts.height,
+            sizeBytes = ready?.cached?.bytes?.size?.toLong() ?: PreviewMetadata.UNKNOWN_BYTES,
+            capturedAt = facts.capturedAt,
+        ),
+    )
+
    // 保存到下载目录：与附件那条路同一取舍——MIME 恒 */*，落盘的是缓存里那一份**原始字节**
    // （不是重新编码过的位图，JPEG 存下来还是 JPEG）。
    val createDocument = rememberLauncherForActivityResult(
@@ -237,7 +260,8 @@ fun ImagePreviewDialog(
                }

                ExitPane(
-                    ready = state as? ImagePreviewState.Ready,
+                    ready = ready,
+                    metadata = metadata,
                    notice = notice,
                    note = nameNoteFor(source),
                    onOpen = { openElsewhere() },
@@ -344,12 +368,16 @@ private fun ZoomableImage(file: File, onUndecodable: () -> Unit) {
 /**
 * 底部那一列出口（与附件弹层同一形态）。
 *
+ * 最上面那一行是**预览内容下方**的格式元数据（[PreviewMetadata] 的产物，可能是空串——
+ * 那就整行不画，绝不留一个空行或一排「未知」）；再下面是 [notice]（刚才那个动作的结果）。
+ *
 * 字节还没到位（[ImagePreviewState.Loading] / [ImagePreviewState.Failed]）时两条出口**不给点**：
 * 点了也只能失败，不如让它们明摆着还没准备好。但**关闭**任何时候都在（右上角那个按钮）。
 */
@Composable
 private fun ExitPane(
    ready: ImagePreviewState.Ready?,
+    metadata: String,
    notice: DocumentPreviewNotice?,
    note: String,
    onOpen: () -> Unit,
@@ -360,6 +388,14 @@ private fun ExitPane(
            .fillMaxWidth()
            .padding(top = 10.dp, bottom = 12.dp),
    ) {
+        if (metadata.isNotEmpty()) {
+            Text(
+                text = metadata,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                modifier = Modifier.padding(horizontal = EXIT_TEXT_MARGIN, vertical = 2.dp),
+            )
+        }
        notice?.let { line ->
            Text(
                text = line.message,
@@ -0,0 +1,70 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.domain.chat.DraftDocument
+import top.yeij.cyrene.domain.share.ShareRules
+
+/**
+ * 一次发送切出来的一条消息（[imageSendPlan] 的元素）。
+ *
+ * [imageUri] 是这条消息要带的那张图（契约里 `chat.image` 是**单图字段**）；[documents] 是这条
+ * 消息要带的非图片附件（`chat.documents` 是数组，但一次只挂在一条消息上）。
+ */
+data class PlannedMessage(
+    val text: String,
+    val imageUri: String?,
+    val documents: List<DraftDocument>,
+)
+
+/** 一次发送的切分结果（[imageSendPlan] 的返回值）。 */
+data class ImageSendPlan(
+    /** 要投递的消息，顺序 = 用户选图的顺序。**至少一条**：没有图时它就是承载正文与附件的那条。 */
+    val messages: List<PlannedMessage>,
+    /** 超过 [ShareRules.MAX_IMAGES] 而**不会**发出去的张数（0 = 一张没少）。 */
+    val truncatedImages: Int,
+) {
+    /** 这次真正会发出去的图片（顺序不变）。超限告知里说的「前 N 张」，N 就是它的长度。 */
+    val imagesToSend: List<String> get() = messages.mapNotNull { it.imageUri }
+}
+
+/**
+ * 「一次发送（正文 + N 张图 + 若干附件）要切成几条消息、每条带什么、超限几张」——**纯函数**，
+ * 与 Android 无关、可单测（见 `ImageSendPlanTest`）。
+ *
+ * ## 为什么 N 张图 = N 条消息
+ * 契约里 `chat.image` 是**单图字段**：一次上行只能带一张。所以多选进来的 N 张只能落成 N 条消息，
+ * 顺序 = 用户选图的顺序，而**第一条**带上正文与全部附件——正文是用户打的这一段字、附件是挂在
+ * 这条消息上的数组，两者本来就只该出现一次。第二条起每条只有一张图、正文为空：空正文的那几条
+ * 不会凭空替用户多说一个字。
+ *
+ * ## 上限只在这里判一次
+ * 上限 [ShareRules.MAX_IMAGES] 与分享路径用**同一个数**（4）：两条路都是「一次最多接住几张图」。
+ * 多出来的张数由 [ImageSendPlan.truncatedImages] 如实报出来，调用方据此说一句
+ * （文案 [ShareRules.truncatedImagesNotice]）——**绝不静默截断**。
+ *
+ * ## N = 0 为什么也回一条
+ * 没有图时这一次发送仍然是一条普通消息（正文 + 附件），它是同一条规则的空形态。把「有没有东西
+ * 可发」留给 [hasSendableContent] 判，这里只回答「要切几条、每条带什么」——两个判据各管一件事，
+ * 谁也不替谁下结论。空串 / 重复项由调用方在入口处清掉（草稿与分享两条入口本来就各自清了）。
+ */
+fun imageSendPlan(
+    text: String,
+    images: List<String>,
+    documents: List<DraftDocument>,
+): ImageSendPlan {
+    val kept = images.take(ShareRules.MAX_IMAGES)
+    val messages = if (kept.isEmpty()) {
+        listOf(PlannedMessage(text = text, imageUri = null, documents = documents))
+    } else {
+        kept.mapIndexed { index, uri ->
+            PlannedMessage(
+                text = if (index == 0) text else "",
+                imageUri = uri,
+                documents = if (index == 0) documents else emptyList(),
+            )
+        }
+    }
+    return ImageSendPlan(
+        messages = messages,
+        truncatedImages = images.size - kept.size,
+    )
+}
@@ -0,0 +1,43 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.repository.canDeleteMessage
+import top.yeij.cyrene.data.repository.canEditMessage
+
+/**
+ * 这条消息在**服务端**有没有对应的一行（纯函数）。
+ *
+ * 判据只有一条：`id` 带不带 [PROACTIVE_LOCAL_ID_PREFIX]。那个前缀是本端给**降级气泡**
+ * （`proactive_message` 落库失败那一档，见 [ProactiveIngest.Bubble]）自铸的，服务端的 id
+ * 永远不会长这样（[proactiveIngestFor] 的 KDoc 说明了它是怎么来的）。
+ *
+ * 为什么这件事要单独成判据：一条消息「在服务端存在」是**打服务端那类动作的前提**。
+ * 拿一个服务端没见过的 id 去 `PATCH` / `DELETE`，最好的结果是 404，其余是一句用户看不懂的报错——
+ * 而这一切仅仅因为他长按了一下一条屏幕上看起来很正常的消息。
+ *
+ * **空 `id` 不在本判据的处理范围内**（今天的行为逐字不变）：那属于「形状漂移」的坏帧，
+ * 是另一件事，不在本轮收口的范围里。
+ */
+fun isServerBackedMessage(message: HistoryMessageDto): Boolean =
+    !message.id.startsWith(PROACTIVE_LOCAL_ID_PREFIX)
+
+/**
+ * 这条消息**能不能编辑**——在角色口径（[canEditMessage]）之上再叠一道「它在服务端存在吗」。
+ *
+ * 两道合起来才是界面与 VM 该用的判据：角色那一道回答「产品上允不允许改她说过的话」，
+ * 本判据回答「这一趟请求有没有意义」。任一道不成立都是**入口不出现**（fail-closed）。
+ *
+ * **只有会打服务端的动作走这里**：气泡里的文本选择 / 复制是纯本端的事
+ * （`SelectionContainer`，与动作菜单是两条独立的路），不归这两个函数管，也不该被它们挡住。
+ */
+fun canEditMessageOnServer(message: HistoryMessageDto): Boolean =
+    isServerBackedMessage(message) && canEditMessage(message)
+
+/**
+ * 这条消息**能不能删除**——在角色口径（[canDeleteMessage]）之上再叠一道「它在服务端存在吗」。
+ *
+ * 降级气泡恰恰是个必须被挡住的例子：它是 `assistant` 行 ⇒ [canDeleteMessage] 会说「能删」，
+ * 但服务端根本没有这一行，删它只会用本地 id 打出一趟注定失败的请求（见 [isServerBackedMessage]）。
+ */
+fun canDeleteMessageOnServer(message: HistoryMessageDto): Boolean =
+    isServerBackedMessage(message) && canDeleteMessage(message)
@@ -3,6 +3,49 @@ package top.yeij.cyrene.ui.chat
 import top.yeij.cyrene.data.api.dto.HistoryMessageDto
 import top.yeij.cyrene.domain.enums.EnumCatalog

+/**
+ * 手打消息的幂等键前缀：本端铸出来的键形如 `local-<uuid>`。
+ *
+ * 铸键处与判据处共用这一个常量（[ChatViewModel] 铸、[isSharedClientMsgId] 判），改一处即两处同步。
+ */
+const val LOCAL_CLIENT_MSG_ID_PREFIX = "local-"
+
+/**
+ * 分享进来的消息的幂等键前缀：`share-<uuid>`。
+ *
+ * 加前缀**不破坏唯一性**——后面那截仍是随机 UUID，而 `clientMsgId` 本来就只要求「同一会话内非空且唯一」
+ * （契约 v0.56 §3.13），前缀只是把「这条是怎么进来的」顺带写进了这个已经存在的字段。
+ */
+const val SHARE_CLIENT_MSG_ID_PREFIX = "share-"
+
+/**
+ * 一串 `clientMsgId` 是不是分享进来的那条。
+ *
+ * 判据**只有前缀**这一个来源：`clientMsgId` 由服务端**原样回填**（见 `HistoryMessageDto.clientMsgId`），
+ * 于是「怎么进来的」这件事能从幂等键上读回来，不必往用户正文里拼任何标记——正文里加标记是
+ * 与后端定过的红线（`ShareRules` 的「为什么正文一个字都不加」/ `02` 的 F4）。
+ *
+ * 边界取值（都按「宁可少画一枚角标，也不冒充事实」定）：
+ * - `null` / 空串 / 纯空白 ⇒ false：没有键就是没有证据，不猜；
+ * - `local-…`（手打的那条路）⇒ false；
+ * - 恰好 `"share-"`（前缀后面没有尾巴）⇒ **false**：本端铸键永远是 `share-<uuid>`，
+ *   尾巴为空的键不可能是本端铸出来的，给它画角标等于替一条来路不明的消息声明「这是你分享的」；
+ * - 大小写敏感、不做 trim：键是机器生成的字面量、服务端原样回填，不是给人读的输入。
+ */
+fun isSharedClientMsgId(clientMsgId: String?): Boolean =
+    clientMsgId?.startsWith(SHARE_CLIENT_MSG_ID_PREFIX) == true &&
+        clientMsgId.removePrefix(SHARE_CLIENT_MSG_ID_PREFIX).isNotBlank()
+
+/**
+ * 这条消息是不是本端「分享进来」的那条（气泡角标的判据，前缀规则见 [isSharedClientMsgId]）。
+ *
+ * 在判据之上多一道 role 闸：这枚角标说的是「**你**把外面的东西分享给了她」，只有用户侧的气泡才可能
+ * 成立。助手那一边不会有这种键，但闸摆在这里更好——万一日后有一行的 role 与键对不上，
+ * 宁可少画一枚角标，也不要在她的气泡上写「用户分享」。
+ */
+fun isSharedMessage(message: HistoryMessageDto): Boolean =
+    message.role == "user" && isSharedClientMsgId(message.clientMsgId)
+
 /**
 * 来源角标（S1.3）：每条消息默认显示来源。
 * - 主人发的 → 「来自 X」（从哪一端发出）
@@ -0,0 +1,74 @@
+package top.yeij.cyrene.ui.chat
+
+import android.graphics.BitmapFactory
+import android.media.ExifInterface
+import java.io.ByteArrayInputStream
+
+/**
+ * 从本端持有的那份字节里**现读**出来的图片事实：像素与拍摄日期。读不到的就是 `null`。
+ *
+ * ## 为什么这一层不在 `domain/` 里
+ * [PreviewMetadata][top.yeij.cyrene.domain.chat.PreviewMetadata] 是纯函数（JVM 单测里逐档穷举），
+ * 而这里调的两个都是 Android 平台类（`android.graphics.BitmapFactory` / `android.media.ExifInterface`），
+ * 在 JVM 单测里是**抛异常的 stub**。所以切口落在这里：读平台 → 得到两个可能为 `null` 的数 →
+ * 交给纯函数组装成那一行。判断「显示什么」的逻辑一个字都不在平台类里，测试因此能覆盖全部档位。
+ *
+ * ## 分辨率为什么用 `inJustDecodeBounds`
+ * 为了一行小字把 20 MiB 的大图解成位图是不可接受的（内存 + 主线程耗时）。`inJustDecodeBounds`
+ * 只读文件头，`outWidth` / `outHeight` 就是答案，`decodeByteArray` 返回 `null` 是有意的。
+ *
+ * ## EXIF 用的是**系统 API**，不引新依赖
+ * `android.media.ExifInterface`（`InputStream` 构造自 API 24 起可用，本工程 `minSdk = 33`）。
+ * 它认不出的容器（PNG / GIF / WebP / BMP 这些没有标准 EXIF 的格式）只会让 `getAttribute` 回
+ * `null`——**那正是「拿不到就整项不缺席」要的答案**，不是错误。⚠️ 它**只读 JPEG 与 RAW**，
+ * 所以「所有图片都有拍摄日期」是错的预期，能报出来的基本只有相机/相册里的 JPEG。
+ *
+ * ## 日期为什么不在这里格式化
+ * EXIF 的 `DateTimeOriginal` 是**没有时区**的墙钟字符串（`yyyy:MM:dd HH:mm:ss`），本层**原样**
+ * 交给 [PreviewMetadata.formatExifDateTime][top.yeij.cyrene.domain.chat.PreviewMetadata.formatExifDateTime]
+ * 去严格校验与格式化——那一步是纯函数，能逐档单测，也能把「不做时区换算」这条取舍写在明面上。
+ */
+data class PreviewImageFacts(
+    val width: Int? = null,
+    val height: Int? = null,
+    /** EXIF `DateTimeOriginal` 的原始字符串；缺席即 `null`。 */
+    val capturedAt: String? = null,
+)
+
+/**
+ * 读出这两个事实。**任何一步失败都只是少一项**（`runCatching`）：这一行是锦上添花，
+ * 它自己绝不许成为「图片打不开」的原因。
+ *
+ * 只从**已经在内存里**的那份字节读（[top.yeij.cyrene.data.repository.CachedDocument.bytes]，
+ * 预览与两条出口用的都是它），不再碰盘、不再联网。
+ */
+fun readPreviewImageFacts(bytes: ByteArray): PreviewImageFacts {
+    val bounds = readBounds(bytes)
+    return PreviewImageFacts(
+        width = bounds?.first,
+        height = bounds?.second,
+        capturedAt = readCapturedAt(bytes),
+    )
+}
+
+/**
+ * 文件头里的像素：任一侧 ≤ 0（解不出来 / 不是图片）就是 `null`。
+ *
+ * 与 `ZoomableImage` 里 Coil 报上来的那个尺寸是两回事：那个是**解码后**的位图尺寸，要等图片
+ * 真的解出来才有；这里是**打开弹层时立刻**就有（只看文件头）。两者一致是常态，不一致时以这里
+ * 为准——它描述的是文件本身。
+ */
+private fun readBounds(bytes: ByteArray): Pair<Int, Int>? = runCatching {
+    val options = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)
+    val width = options.outWidth
+    val height = options.outHeight
+    if (width > 0 && height > 0) width to height else null
+}.getOrNull()
+
+/** EXIF 的 `DateTimeOriginal`；没有这个标签 / 不是 EXIF / 读不动，一律 `null`。 */
+private fun readCapturedAt(bytes: ByteArray): String? = runCatching {
+    ByteArrayInputStream(bytes).use { stream ->
+        ExifInterface(stream).getAttribute(ExifInterface.TAG_DATETIME_ORIGINAL)
+    }
+}.getOrNull()?.trim()?.takeIf { it.isNotEmpty() }
@@ -0,0 +1,121 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.ws.WsEvent
+
+/**
+ * 一帧 `proactive_message`（她主动说的话）**该怎么进本端**（纯函数 [proactiveIngestFor] 的结果）。
+ *
+ * 独立成一个类型而不是「返回一条 `HistoryMessageDto?`」，是因为两条并入路**外观相同、真相不同**：
+ * [Persisted] 那条是服务端历史里的行（按 id upsert，刷新后仍在），[Bubble] 那条只活在本端内存里。
+ * 上层要能对它们做不同的说明，测试也要能分别钉住。
+ */
+sealed interface ProactiveIngest {
+
+    /**
+     * **不并入本 VM**：这一帧不是给这个会话的（见 [proactiveIngestFor] 的归属判据），
+     * 或帧里没有任何可显示的东西。
+     */
+    data object Skip : ProactiveIngest
+
+    /**
+     * **并入一条已落库的 assistant 行**（帧带落库行的权威 id）。
+     *
+     * 这就是 v0.72 之后她这句话的真相：它既是实时帧，也是主会话历史里的一行。走 [Persisted]
+     * 而不是画一个气泡，客户端才有「刷新 / 重开 / 切会话拉历史之后她的话还在」这条性质——
+     * 而重复也**不会**发生：并入走的是以 [HistoryMessageDto.id] 为键的 upsert
+     * （`mergeMessages`），同一条（实时帧 + 握手回放 + 分页）无论到几次都只有一行。
+     */
+    data class Persisted(val message: HistoryMessageDto) : ProactiveIngest
+
+    /**
+     * **降级路径**：帧**不带** `id`（服务端那一步落库失败了，它自己就说了「这条没有历史行」）
+     * ⇒ 画一条只活在本端内存里的气泡，也好过什么都不显示。
+     *
+     * ⚠️ 它的代价必须说清：这条气泡**不在**服务端历史里，所以**刷新 / 重开 App / 切走再回来
+     * 都不会再有它**（那些时刻显示的是服务端的历史，而服务端没有这一行）。这是「如实显示一条
+     * 可能留不住的记录」而不是「假装它已落库」——正因如此它才与 [Persisted] 分开。
+     */
+    data class Bubble(val message: HistoryMessageDto) : ProactiveIngest
+}
+
+/**
+ * 本端给降级气泡铸的 id 前缀。
+ *
+ * 一眼可辨（日志 / 截图上能认出这是本地行，不是服务端 id），也**永不**与服务端的 id 撞。
+ */
+internal const val PROACTIVE_LOCAL_ID_PREFIX = "proactive-local:"
+
+/**
+ * 一帧 `proactive_message` 该不该并进 [sessionId] 这个 VM、以什么身份并入（纯函数，判据可单测）。
+ *
+ * ## 1. 归属：**只进主会话**（这一步不能省）
+ * 这一帧的帧壳**不带** `sessionId`（服务端构造时没设它，且 `ws_hub.go` 那个键是 `omitempty`），
+ * 而 [top.yeij.cyrene.data.ws.isForSession] 对空 `sessionId` 的口径是**放行**（空 = 无法判定，
+ * 不是「不属于本会话」）⇒ 同一批帧会投给**每一个**活着的 `ChatViewModel`。归属因此只能在这里
+ * 自己钉死：她主动说的话落的是**主会话**（服务端 `history.MainSessionID` = 客户端的
+ * [MAIN_SESSION_ID]）。不钉就会**在每个次级会话里都冒出一条她的话**——比「看不到」更糟。
+ *
+ * 比较是**等值**、不是前缀：主会话 `web` 与次级会话 `web:xxx` 是两个会话。
+ *
+ * ## 2. 身份：有 `id` 就是已落库行，没有就是本地气泡
+ * 服务端**先落库、再发帧**，并把落库行的 `id` / `createdAt` 放进载荷；落库失败时这两个键
+ * 一起缺席。所以 `id` 的有无就是「这条在历史里存不存在」的判据，不需要别的猜测。
+ *
+ * ## 3. `createdAt` 的退化
+ * `id` 在、`createdAt` 却缺席或非正数（形状漂移）时用 [nowMillis]：帧是刚刚到的，按「现在」
+ * 排在最末就是它该在的位置；而服务端那一行是真的存在，下一次拉历史会用同一 id 把它连同真正的
+ * 时间戳一起覆盖回来（`mergeMessages` 的 incoming 胜出）。
+ *
+ * ## 4. 无 `id` 且无正文 ⇒ [ProactiveIngest.Skip]
+ * 这种帧里没有任何可显示的东西（落库失败的空帧），画一条空气泡只会让人以为出了别的事。
+ *
+ * 时钟与本地 id 都由调用方喂（判据自己不读表、不自铸随机数），所以这里可单测、可复现。
+ */
+fun proactiveIngestFor(
+    event: WsEvent.ProactiveMessage,
+    sessionId: String,
+    nowMillis: Long,
+): ProactiveIngest {
+    if (sessionId != MAIN_SESSION_ID) return ProactiveIngest.Skip
+
+    val content = event.content
+    val id = event.id?.takeIf { it.isNotBlank() }
+    val createdAt = event.createdAt?.takeIf { it > 0 }
+
+    if (id != null) {
+        return ProactiveIngest.Persisted(
+            HistoryMessageDto(
+                id = id,
+                sessionId = MAIN_SESSION_ID,
+                role = ASSISTANT_ROLE,
+                content = content,
+                platform = event.platform?.takeIf { it.isNotBlank() },
+                createdAt = createdAt ?: nowMillis,
+            ),
+        )
+    }
+
+    if (content.isBlank()) return ProactiveIngest.Skip
+
+    // 本地 id 用**帧里已有的稳定键**（IM 侧的消息号，其次是它的时间字面量）而不是随机数：
+    // 同一个键第二次到达就是一次 upsert（仍只有一条），而且日志 / 截图上能追回它是哪一帧来的。
+    // 随机 id 做不到这两件事——同样的帧再投一次（服务端重推 / 客户端重放）就会多出一个一模一样的气泡。
+    val localKey = event.messageId?.takeIf { it.isNotBlank() }
+        ?: event.timestamp?.takeIf { it.isNotBlank() }
+        ?: nowMillis.toString()
+
+    return ProactiveIngest.Bubble(
+        HistoryMessageDto(
+            id = PROACTIVE_LOCAL_ID_PREFIX + localKey,
+            sessionId = MAIN_SESSION_ID,
+            role = ASSISTANT_ROLE,
+            content = content,
+            platform = event.platform?.takeIf { it.isNotBlank() },
+            createdAt = createdAt ?: nowMillis,
+        ),
+    )
+}
+
+/** 她主动说的话恒是 assistant（服务端 `persistProactiveToMain` 定死）。 */
+private const val ASSISTANT_ROLE = "assistant"
@@ -0,0 +1,88 @@
+package top.yeij.cyrene.ui.chat
+
+/**
+ * 本会话的**首屏**（`GET /messages` 最新一页，[ChatViewModel.start] 那一次）走到哪儿了。
+ *
+ * 它存在的唯一理由是让「重连时要不要再拉一次首屏」这件事**判得出来**，而这里必须能分辨
+ * **三个**状态、不能只用一个「有没有数据」的位：
+ *
+ * - [Loading]：首屏那次**还在飞**。这一刻再发一次同样的请求就是白拉一次，更要紧的是它会把
+ *   「首屏还没回来」这件事伪造成「首屏失败了」——而那正好是 W49 / S3 那条窄窗口的时序，
+ *   **本轮一个字节都不改**（见 [reconnectPull] 第 3 条）。
+ * - [Loaded]：成功过。哪怕服务端真的**就是**没有消息（`hasMore=false`、列表空），也是成功过——
+ *   所以「空会话」不该被读成「没拉到」（这正是「用有没有数据当判据」会踩的坑：每个空次级会话
+ *   都会在每次重连被整表重拉一次，而那正是 S4/S7 这一类问题的来源）。
+ * - [Failed]：确实没拿到（离线冷启动、超时、服务端错）。**只有这一档**才值得在连接恢复时补。
+ */
+internal enum class FirstPageState {
+    Loading,
+    Loaded,
+    Failed,
+}
+
+/** 连接恢复那一刻这一轮该做什么（[reconnectPull] 的取值）。 */
+internal enum class ReconnectPull {
+
+    /**
+     * 既有行为，一字未动：用掉线那一刻记下的 [ChatViewModel.gapCursor] 做一次 `after` 正向增量。
+     */
+    Forward,
+
+    /**
+     * **本轮新增**：本端首屏从来没成功过，而这是**次级会话** —— 拉一次最新一页。
+     *
+     * 它补的就是 S2 登记的那个洞：进次级会话时 WS 未连（冷启动离线）⇒ 首屏那次 REST 也失败
+     * ⇒ 此后连接恢复**没有任何人补拉**，屏幕长期空着「还没有消息」，直到用户手动切走再回来。
+     */
+    FirstPage,
+
+    /** 什么都不做。 */
+    Nothing,
+}
+
+/**
+ * 连接刚刚恢复（`WsState.Connected`）时这一轮该做什么（**纯函数**，VM 与测试共用）。
+ *
+ * ## 为什么次级会话需要它，而主会话不需要
+ * 主会话有**两条**安全网：握手回放 `history`（最近 50 条，服务端固定回放主会话，
+ * `ws_hub_conn.go` 写死 `replayHistory(MainSessionID)`）与 `after` 正向增量。次级会话**只有后者**
+ * ——`history` 帧里根本没有它的消息（`isForSession` 会把它们整帧滤掉）。于是「首屏没拿到 +
+ * 之后连接恢复」这个组合下，主会话被回放兜住，次级会话什么都没有。
+ *
+ * ⚠️ 所以这里的修法**不是**照抄主会话那条（给次级会话要 `history` 是改服务端的契约面），而是走
+ * **本项目自己那条 REST 补拉**：连接恢复时，如果本端首屏从来没成功过，就自己去拉一次最新一页。
+ *
+ * ## 判据与优先级（自上而下，先命中先返回）
+ * 1. [sessionKnownGone] ⇒ [ReconnectPull.Nothing]。**注定 404 的补拉一个都不发**（S7 ①）：
+ *    这一位由两个来源合成——本端自己删过它（`GoneSessions`），或已经有了 `404 session_not_found`
+ *    的结论（[ChatUiState.sessionGone]）。前者让「每次重连一次注定失败的往返」变成零次；后者让
+ *    「发现之后还在反复撞」收敛成**恰好一次**。
+ * 2. `gapCursor != null` ⇒ [ReconnectPull.Forward]：既有行为，**一个字都不改**。有一个断线窗口
+ *    要补时，`after` 就是对的（它比首屏更精确：只补那个洞）。也正因为这一档在前面，
+ *    「本轮新增的那条路」只在今天**什么都不做**的那一刻才会走。
+ * 3. 首屏 [FirstPageState.Failed] **且**不是主会话 ⇒ [ReconnectPull.FirstPage]。
+ *    - **Failed 才算**：`Loading` 时刻再拉一次会与首屏那次抢跑（并且会把 S3 那条「history 帧一到就
+ *      `loading=false`」的时序改掉）；`Loaded` 之后再拉就是「每次重连整表重拉」，正是 S4/S7 的成因。
+ *    - **主会话除外**：它由握手 `history` 兜住（见上），在这里再补一条 REST 只会变成**第二套**
+ *      补口径——两套判据迟早分叉，而分叉的那一侧就是漏出去的那一侧。主会话的兜底行为因此
+ *      **逐字不变**。
+ * 4. 其余 ⇒ [ReconnectPull.Nothing]。
+ *
+ * 判据里除了这四样什么都不看（读不到 VM 状态、不读表），才能穷举、才能在 JVM 上单测
+ * （先例：`ui.sessions.silentRefreshStep`、`ui.chat.shareLanding`）。
+ *
+ * @param sessionId 本 VM 的会话（比较是**等值**：主会话 `web` 与次级 `web:xxx` 是两个会话）。
+ * @param gapCursor 掉线那一刻记下的 `after` 游标；`null` = 没有需要补的洞。
+ * @param sessionKnownGone 本端已知「服务端没有这个会话了」——本地删过，或者已经 404 过。
+ */
+internal fun reconnectPull(
+    sessionId: String,
+    firstPage: FirstPageState,
+    gapCursor: Long?,
+    sessionKnownGone: Boolean,
+): ReconnectPull = when {
+    sessionKnownGone -> ReconnectPull.Nothing
+    gapCursor != null -> ReconnectPull.Forward
+    firstPage == FirstPageState.Failed && sessionId != MAIN_SESSION_ID -> ReconnectPull.FirstPage
+    else -> ReconnectPull.Nothing
+}
@@ -0,0 +1,134 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.ws.WsState
+import top.yeij.cyrene.domain.chat.allClosed
+
+/**
+ * **连接重建**（不是第一次接上）时把本端的「进行中」一次性收口。
+ *
+ * ## 它修的是什么（主人 2026-10-06 报的现场）
+ * 后端卡在半路（回合在跑、或工具在跑）时被**重启**：那一轮在服务端**已经不存在了**，
+ * 所以本端**永远不会**再收到它的任何收口帧（`turn.end` / `stream_end` / 助手落库行）。
+ * 而本端「进行中」的每一条闸都只认**帧**：
+ *
+ * - 灰态（④「已读，正在回答…」）的唯一闸是 [top.yeij.cyrene.domain.chat.TurnBinding.closed]，
+ *   它只由 `turn.end` / 同 `turnId` 的助手落库行驱动（`ChatViewModel.onEvent`）；
+ * - 「思考中…」/「执行 X…」的唯一闸是流式路自己的 `thinkingActive` / `active` / 工具卡的 `phase`
+ *   （收口只发生在 `stream_end` / 助手落库行）；
+ * - 底栏那句「正在思考…」的唯一闸是 `session_busy` / `session_idle` 报的 [ChatUiState.busyMode]。
+ *
+ * 三条路都断在「没有帧」上 ⇒ **没有任何一条会自己收口**，界面于是永久停在那一格：气泡一直灰着、
+ * 卡片一直转、底栏一直说她在思考。三条里今天唯一被兜住的是 `session_idle` / `session_interrupted`
+ * 那两帧（`allClosed()` 的两个既有调用点）——而**后端重启时它们永远不会到**（说这话的进程已经没了）。
+ *
+ * 还有一处**不显眼但很要命**的连带：那条永远 `active` 的流式路永远是消息列表的**末项**
+ * （[ChatUiState.items] 的最后一项，`reverseLayout` 下就是**屏幕最下方**），而 `ChatScreen` 的
+ * 「跟随底部」判的正是 `items.lastOrNull()?.key`（`ChatScreen.kt:508`）——末项不再变化 ⇒
+ * **此后新到的消息不再把列表滚到底**，于是「最新一条」永远停在那一张转着的卡上。用户看到的就是
+ * 「拉不到新消息」（消息其实进得来，是屏幕不再跟着它走）。
+ *
+ * 收口之后这张卡变成**惰性**的（不再转、不再声称在思考）：它仍留在列表里（正文一个字都不删，
+ * 见下面「不许碰的东西」），直到它自己那一路的落库行到达、或**下一轮** `message.start` 把它当作
+ * 「已结束的路」丢掉（`TurnStreams.beginLeg`）——那时末项恢复推进，跟随底部也就回来了。
+ * 这条残留如实登记：收口**不**替这张卡删内容，所以它自己要等一个后续事件才消失。
+ *
+ * ## 触发时机：只做「连接重建」（(a)），**不做静默超时**（(b)）
+ * 判据落在 [isReconnect] 上，也就是 `WsState` **非 Connected → Connected** 的那一跳。三条理由：
+ * 1. **确定性**：后端重启必然重建连接，而重建连接**必然**让 `WsState` 走一遍 `Reconnecting →
+ *    Connected`（`ChatSocket.runConnectionLoop`）。这条判据是**事件驱动**的，不需要时间常量；
+ * 2. **可验证**：假后端 `POST /__control/ws-close`（或直接重启进程）就能复现，设备上判据是
+ *    「一条已在飞的回合 + 一次真踢」，不依赖「等多久」这种主观量；
+ * 3. **与既有纪律一致**：本项目自 W38 起就定死「状态驱动，不按时间轮」（见
+ *    `ChatViewModel.retryFirstPage` 的 KDoc），(b) 会在同一张表上引入第二个口径。
+ *
+ * (b)（某一路 N 秒没有任何帧就认为它结束了）**刻意没做**，代价与风险如实记在这里，留主人拍板：
+ * - 它要多一个**时间常量**，而那个数只能拍：太小会把「正常但慢」的回合（长思维链、长工具执行、
+ *   服务端排队）误杀成已结束，太大则回到「卡住很久」的老样子；
+ * - 它能在**连接没断**时兜底（后端进程活着但编排器死锁、或帧被中间设备悄悄丢掉），而 (a) 兜不住
+ *   这一档；但这一档今天**没有现场证据**（主人报的是「重启后端」，那是 (a)），按「先修有证据的」
+ *   不动它；
+ * - 两者叠加不会互相破坏（都是幂等收口），真要做时**先做 (a)、再把它当第二级**即可。
+ *
+ * ## 「第一次连接」不算重建
+ * 冷启动的 `Idle → Connecting → Connected` 必须**一个字节都不收口**，两条路都会踩到：
+ * - **刚进会话的 VM**：它订阅时连接可能**已经是** Connected，于是它看到的第一次 Connected 与
+ *   `history` / `turn_begin` / `steer_ack` 那一批首帧**几乎同时**到达（帧走 `socket.events`、
+ *   状态走 `socket.state`，两条流各自投递）。这时候本端手里可能**已经有**一条正当地灰着的气泡
+ *   （另一台设备起的那一轮），把它当成重建收口就是**在用户刚打开会话的瞬间**凭空把那一轮说成已答；
+ * - **冷启动**：`Idle → Connecting → Connected` 是每一个会话的第一跳，与「后端重启过」毫无关系。
+ *
+ * 所以判据必须是「**曾经**到过 Connected 之后又回到 Connected」，而不是「这一次是不是 Connected」。
+ */
+internal fun isReconnect(previous: WsState, current: WsState, everConnected: Boolean): Boolean {
+    // 不是「接上了」，谈不上重建（Connecting / Reconnecting / Offline / Idle 都不收口）。
+    if (current != WsState.Connected) return false
+    // 本 VM 见过 Connected ⇒ 这一次接上必然是**接回来**。这一条是主判据，而且**不受状态流合流影响**
+    // （理由与「为什么是一位记忆而不是看上一跳」见 `ChatViewModel.everConnected` 的 KDoc）。
+    if (everConnected) return true
+    // 没记过账时的第二证据：上一跳是**重连退避**（`ChatSocket.runConnectionLoop` 只在断开之后写
+    // `Reconnecting`；首次握手走的是 `Connecting`）。这一档只在一处是真的：**本 VM 是在离线期间
+    // 建起来的**（进次级会话时连接就是断的）⇒ 它自己的第一次 Connected 确实发生在一次重建之后。
+    // 它手里那时**什么都没有**（没有 turn / 没有流式路 / 没有 busyMode），所以 [settledAfterReconnect]
+    // 对它是恒等变换——判在这里不会误伤任何东西，反过来说也不必为它加第二条口径。
+    return previous == WsState.Reconnecting
+}
+
+/**
+ * 连接重建时把本端「进行中」的五个面一次性收口（纯函数，VM 与测试共用）。
+ *
+ * 收口的是**服务端那一轮留下来的本端投影**，一件一件说清它为什么该收：
+ * - [ChatUiState.busyMode]：「正在思考…」是**服务端报的**事实（`session_busy`）。旧连接没了，
+ *   这个事实就**不可知**了；继续显示它等于替服务端保证一件已经问不到的事；
+ * - [ChatUiState.activeTurns]：同上（「并行 N 路」）；归 `0` = 「不知道」，正是
+ *   [ChatUiState.activeTurns] 文档里那个「不知道」的取值；
+ * - [ChatUiState.queueDepth]：「已排队 N 条」也是服务端队列的事实，与 `session_idle` / 被打断
+ *   那两处的处置**逐字一致**（那两处也是 `busyMode = null, queueDepth = 0` + 全部收口）；
+ * - [ChatUiState.turns] ⇒ `allClosed()`：未收口的绑定全部标 `closed`（气泡 ④ → ⑤）；
+ * - [ChatUiState.streams] ⇒ `allFinished()`：每一路停止生长（思维链不再「思考中」、工具卡不再
+ *   「执行 X…」），**正文一个字都不删**。
+ *
+ * ## 收口之后**不许**碰的东西（可降级；也是本函数的红线）
+ * [ChatUiState.messages] / [ChatUiState.pending] / [ChatUiState.queuedKeys] /
+ * [ChatUiState.queuedForConnection] / 草稿与附件 / [ChatUiState.error] / [ChatUiState.sessionGone]
+ * **一律原样**：收口只改「进行中的外观」，**不删消息、不整表重拉、不给用户多加一条横幅**。
+ * 绑定表本身也**不删**（只标 `closed`）——并行路角标（`legBadgeForMessage`）靠它，删了等于事后
+ * 篡改历史。于是写死一条纪律：**收口是可降级的**，最坏的结果只是「少灰一会儿」。
+ *
+ * ## 「闪动」：收口会不会被随后到达的帧翻回进行中（如实回答）
+ * - 灰态**不会**：[top.yeij.cyrene.domain.chat.TurnBinding.closed] 是**单调**的既成事实
+ *   （`withTurnBegin` 合并时也**保持原值**，见那里第 2 条），所以「已答」之后不会退回「回答中」。
+ * - 流式卡片**会**：那一帧正文/思维链真的又来了，`withLeg` 就会把它重新变成 `active` /
+ *   `thinkingActive` —— 这是**如实**的（它确实又在生成了），而且是**自愈**的：正文不会因为
+ *   本端收过一次口而丢字（收口不删内容，后续 delta 照旧追加到同一路）。
+ * - `busyMode` **会**：服务端下一次 `session_busy` 一到就恢复。
+ *
+ * 也就是说：**代价落在「服务端那一轮其实还活着」（只是连接抖动过）这一档**——本端会提前一点点
+ * 把气泡显示成已答。这个代价是刻意选的，因为它比另一个方向小得多：今天的行为（永远灰着、
+ * 卡片永远转、底栏永远说她在思考、跟随底部永远失效）是**永久坏掉**，且用户唯一的出路是退出重进。
+ *
+ * ## 一条如实登记的行为变化
+ * 清掉 [ChatUiState.busyMode] 会**连带**改变下一次发送的声明：`ChatViewModel.emitAndDeliver` 用
+ * `busyMode != null` 算 `interruptScopeForSend` / `parallelForSend`（`ChatViewModel.kt:1793`）。
+ * 于是「她忙时发消息」偏好选「打断」的那一档，在重建后的**第一次**发送不再先发 `interrupt`。
+ * 如实说：连接重建之后本端**确实不知道**那一轮还在不在，而不打断的后果（这一条被服务端排在后面
+ * 或并行处理）比对着一个已经不存在的回合发 `interrupt` 小得多。服务端下一次报 `session_busy`
+ * 就恢复原样。
+ */
+internal fun ChatUiState.settledAfterReconnect(): ChatUiState {
+    val closedTurns = turns.allClosed()
+    val finishedStreams = streams.allFinished()
+    // 没有任何「进行中」可收时返回**同一个实例**：每次「接回来」都会调它一次，而无变化时制造新
+    // 实例会让 StateFlow 白白发一轮（也让测试里的 `assertSame` 失去意义）。
+    if (closedTurns === turns && finishedStreams === streams &&
+        busyMode == null && activeTurns == 0 && queueDepth == 0
+    ) {
+        return this
+    }
+    return copy(
+        busyMode = null,
+        activeTurns = 0,
+        queueDepth = 0,
+        turns = closedTurns,
+        streams = finishedStreams,
+    )
+}
@@ -0,0 +1,314 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.repository.ChatAck
+import top.yeij.cyrene.data.ws.WsState
+
+/**
+ * 回落 REST 那一次投递的**整通上限**（毫秒）——`POST /api/v1/chat` 从发出到拿到回执，连接、写、
+ * 读全算在内。
+ *
+ * ## 一个 client、两个超时（W45）
+ * 它和 client 上的 [top.yeij.cyrene.data.api.CONNECT_TIMEOUT_MILLIS] 是**两个分开的闸**，管的是
+ * 两件不同的事：
+ * - **连接超时（2.5 秒，挂在 client 上）**管「连不上」：完全无网、死网、对端不在听时 2.5 秒内
+ *   失败 ⇒ 进队列。它是「无网快速进队列」这条性质的**全部**依据；
+ * - **本值（10 秒，挂在这一次投递上）**管「连上了但一直不回话」：半死的代理、接住连接却不回应
+ *   的服务端，到点按网络类失败处理 ⇒ 进队列。
+ *
+ * 本值是 W41 就写在纸上的那一个，**不许拉长**：它直接是用户按完发送键之后的干等时间上界。正常
+ * 网络下这一次本该毫秒级拿到回执（「服务端收下了」的判据见 [restAttemptLanding]），10 秒是
+ * 「回得慢」与「这条路已经死了」之间的分界。
+ *
+ * ## 为什么它不写成 client 的 `callTimeout`
+ * 这个 client 是**共用**的：长文本、内联图片那两条本来就该走 REST 的路用的是同一个
+ * （[ChatViewModel.sendViaRest]）。client 级 `callTimeout` 会把它们一并框住——一条慢但合法的
+ * 请求会被判成失败，那是给一条本轮不打算碰的路引入新失败面。放在调用点则「哪一次投递有整通上限」
+ * 是显式的，就写在 [ChatViewModel.sendViaRestFallback] 那一行上。
+ *
+ * 超时**不当作「服务端拒绝」**：那条消息可能已经被服务端收下（只是回执没回来）⇒ 按网络类失败
+ * 处理 ⇒ 进队列，重发时仍用同一个 `clientMsgId`，服务端按 `(session_id, client_msg_id)` 判重后
+ * 回 `chat_duplicate` / `{duplicate:true}`，不会落成第二条消息。
+ */
+const val REST_FALLBACK_TIMEOUT_MILLIS = 10_000L
+
+/**
+ * 一条消息这一刻该怎么走（[sendRouteFor] 的取值）。
+ *
+ * 与 [top.yeij.cyrene.domain.chat.SendChannel] **不是一回事**，两者正交、同时存在：
+ * - [top.yeij.cyrene.domain.chat.SendChannel] 判的是「**这条内容**该走哪条上行通道」——静态的、
+ *   只看文本字节数 / 有没有图片 / 有没有附件，与网络状况无关（[top.yeij.cyrene.domain.chat.ChatSendRouting]）；
+ * - 本枚举判的是「**这一刻这个动作**该怎么做」——动态的、只看「帧交出去了没有」与连接状态。
+ *
+ * 阶梯的**第一步**永远是 `SendChannel` 那次判定（有图 / 有附件的消息根本进不到下面这两档，
+ * 它们本来就是 REST）；本枚举只在「内容是短文本、本该走 WS」那条路上生效。
+ */
+enum class SendRoute {
+    /** 帧已经交给 socket（或连接就绪、就该走 WS）：照今天的样子继续等回执。 */
+    Ws,
+
+    /**
+     * WS 没把帧交出去、而连接不是 [WsState.Offline] ⇒ **直接试 REST** 把这条发出去
+     * （短文本也走 REST：`POST /api/v1/chat` 从第一天起收的就是同一种消息）。
+     *
+     * 这里**没有任何探测**（W45 删掉了 W41 那道 `GET /api/v1/health`）：真正的 REST 请求本身就
+     * 是最直接的检验——试成了这条还顺手发出去了，试败了才进队列。理由见 [sendRouteFor]。
+     */
+    Rest,
+
+    /** 连接是 [WsState.Offline] ⇒ **不试 REST**，直接进补发队列等连接。 */
+    Queue,
+}
+
+/**
+ * [sendRouteFor] 那条判据**依据的是哪一条**（[sendRouteDecisionFor] 的取值，W46）。
+ *
+ * 为什么把「原因」也变成返回值：结果只有三档，而「为什么是这一档」在真机上是**看不见的**。W45
+ * 那轮回归就卡在这儿——界面上那条消息进了队列（`queuedForConnection`）、网络侧一条请求都没有，
+ * 而「零请求 + 进队列」在判据里只可能来自 [SendRoute.Queue]；可顶栏同时显示「重连中…」。事后只看
+ * 结果与顶栏，两种可能（判据读到 [WsState.Offline] vs 判据读了另一个值）**在外同形**。于是这一行
+ * 日志把依据本身也打出来（tag 见 `ChatViewModel.SEND_ROUTE_LOG_TAG`），矛盾就能当场分辨。
+ *
+ * 三档**与 [sendRouteFor] 的三条规则一一对应**，没有第四种可能：它是那条 `when` 的分支标识，
+ * 不是另算一遍的近似值（[sendRouteFor] 就是本函数的 `.route`）。
+ */
+enum class SendRouteReason {
+    /** 规则 1：`wsDispatched` ⇒ 帧已经交给 socket，连接状态不参与判断。 */
+    FrameDispatched,
+
+    /** 规则 2：连接是 [WsState.Offline]（会话已知是死的）⇒ 进队列，**一个请求都不发**。 */
+    ConnectionOffline,
+
+    /** 规则 3：其余未就绪档（[WsState.Idle] / [WsState.Connecting] / [WsState.Reconnecting]）⇒ 直接试 REST。 */
+    ConnectionNotReady,
+}
+
+/**
+ * 一次路由判定的**结果 + 依据**（[sendRouteDecisionFor] 的取值）。
+ *
+ * 两者必须同出一次：分开问两次会把「判据看到的事实」与「结论」割开，而那正是排查时最容易错的地方。
+ */
+data class SendRouteDecision(val route: SendRoute, val reason: SendRouteReason)
+
+/**
+ * 同 [sendRouteFor]，但把「依据」一并带出来（[SendRouteReason]，W46 可观测性）。
+ *
+ * 判据、优先级、行为**逐字未改**：下面这个 `when` 就是 [sendRouteFor] 原来那一个，只是每一支把
+ * 自己标了出来。[sendRouteFor] 现在读它的 [SendRouteDecision.route]，所以两处不可能分叉。
+ */
+fun sendRouteDecisionFor(wsDispatched: Boolean, connection: WsState): SendRouteDecision = when {
+    wsDispatched -> SendRouteDecision(SendRoute.Ws, SendRouteReason.FrameDispatched)
+    connection == WsState.Offline -> SendRouteDecision(SendRoute.Queue, SendRouteReason.ConnectionOffline)
+    else -> SendRouteDecision(SendRoute.Rest, SendRouteReason.ConnectionNotReady)
+}
+
+/**
+ * 回落 REST 宣告失败之后的落点（[restFailureLanding] 的取值）。
+ */
+enum class RestFailureLanding {
+    /** 这一条**还没上过路**（服务端没给过任何裁决）⇒ 进队列，连接一好就补发。 */
+    Queue,
+
+    /** 服务端**给过裁决**（拒绝 / 未授权 / 协议对不上）⇒ 走今天那条回滚 + 文案。 */
+    Rollback,
+}
+
+/**
+ * 「这条 `chat` 帧交出去了没有 + 这一刻的连接状态」⇒ 该走哪条路（**纯函数**，VM 与测试共用）。
+ *
+ * 判据里**没有任何探测输入**（W45）：路由只看这两个事实，`GET /api/v1/health` 那一层连同它的
+ * 客户端、独立超时预算与失败面一起删掉了。
+ *
+ * ## 为什么是「直接试 REST」（W45 主人的定案）
+ * W41 的阶梯是「WS 未就绪 ⇒ **先探 `GET /api/v1/health`** ⇒ 通才回落 REST」。真机回归
+ * （`devtools/ws-block-proxy/ws_block_proxy.py` 只掐 `/ws/chat`、HTTP 全放行）发现消息**进了队列而不是回落
+ * REST**；而 `ProbeClientTest` 证明那条链在 JVM 上是通的，`Unreachable` 生在**连接之前**，三种
+ * 成因（建 client 抛 / 连上但一个字没写 / ConnectException）**在外同形** ⇒ 那一轮无法定论。
+ *
+ * 结论是**不该有探测**：探测只是「能不能连上」的**替身**，而真正的 REST 请求本身就是最直接的
+ * 检验——试成了消息还顺手发出去了，试败了进队列（内容一个字节不丢，重发仍是同一个
+ * `clientMsgId`）。探测唯一省下的是「完全无网时少发一个注定失败的请求」，代价却是一个独立
+ * client、一套独立超时预算和一整套新的失败面；而那个探针 client **从不复用连接池**，每次都要现做
+ * 一次冷握手，预算还比主链路紧 4 倍（2.5 秒整通 vs 10 秒连接）——今天这个 bug 的形态就长在
+ * 这上面。
+ *
+ * 直接试也**不会**把「无网快速进队列」弄丢：那一条靠的是 client 上的短连接超时
+ * （[top.yeij.cyrene.data.api.CONNECT_TIMEOUT_MILLIS]，2.5 秒），不是探针。
+ *
+ * ## 判据与优先级
+ * 1. `wsDispatched == true` ⇒ [SendRoute.Ws]。帧已经交给 socket，连接状态**不再参与**判断
+ *    （`sendChat` 判的就是自己的状态）。**成功路径零改动**：不打标记、不说告知、不写任何状态。
+ * 2. 连接是 [WsState.Offline] ⇒ [SendRoute.Queue]。这一档的语义是「握手 401 且续期也失败」
+ *    （终态、不会自动重连），也就是说**会话已知是死的**；这时候去试 REST 只会拿到 401 并落到
+ *    「回滚 + 一句会误导人的鉴权错误」，把 W40 那句「已排队不会丢」换成更差的结果。**保留 W41
+ *    这个决定**：它当时的理由（健康端点不鉴权、必然回 200，于是判成「通」）随探测一起消失了，
+ *    但结论换到直接试这边**一字不用改**——不鉴权的探针回 200 是「假通」，带令牌的 chat 端点回
+ *    401 是**真不通**，两条路都指向同一件事：这一档不该发。
+ * 3. 其余三档未就绪（[WsState.Idle] / [WsState.Connecting] / [WsState.Reconnecting]）
+ *    ⇒ [SendRoute.Rest]：**直接试 REST**，不等任何探测。
+ *
+ * 判据只认 `Connected` **一个值**（不是「不等于 Offline」之类的近似）——连接状态的另外四档
+ * 都意味着帧没有被交给任何服务端。
+ *
+ * 本函数只回三个结果；**「为什么是这一档」在 [sendRouteDecisionFor]**（W46 加的可观测性，判据本身
+ * 一字未动）：真机上看不见「判据读到的是哪个值」，而那正是排查「发送为什么进了队列」时唯一要分的
+ * 东西。
+ */
+fun sendRouteFor(
+    wsDispatched: Boolean,
+    connection: WsState,
+): SendRoute = sendRouteDecisionFor(wsDispatched, connection).route
+
+/**
+ * 这份回执照的是「**服务端已经收下这条**」（受理起回合 / 忙时续接排队 / 早就收过这条幂等键）。
+ *
+ * 只有这一族才算了结：被拒的那三种（队列满 / 接不住 / 明确拒绝）不算——那条消息没有上路，走
+ * [ChatAck] 那六支里的回滚 + 文案。用 `when` 穷举而不是 `!=` 某个值：回执面将来多一档时，
+ * 这里必须有人做决定。
+ *
+ * 它是[直接试 REST][restAttemptLanding] 那一步「**收下了没有**」的**唯一**判据。W45 把它从
+ * `ChatViewModel` 的私有方法搬到这里：这条判据决定了一条消息会不会进补发队列（收下了就不该进），
+ * 不该只活在 VM 里、只被组合着一个界面才测得到。
+ */
+fun ChatAck.isAccepted(): Boolean = when (this) {
+    ChatAck.Accepted, is ChatAck.Queued, is ChatAck.Duplicate -> true
+    ChatAck.QueueFull, is ChatAck.Unavailable, is ChatAck.Rejected -> false
+}
+
+/**
+ * 一次「直接试 REST」的落点（[restAttemptLanding] 的取值）。
+ *
+ * 四档**穷举**「服务端有没有收下 / 有没有给过裁决」这两个问题的组合，每一档对应一个明确的处置，
+ * 没有「默认继承前一档」的余地。判据决定的是**一条消息的去向**（进队列还是回滚），所以两档的
+ * 代价不对称：误判成 [Accepted] 会让一条没上路的消息凭空消失，误判成 [Unsent] 只是多补发一次
+ * （幂等键兜住，不落第二条）——拿不准一律往 [Unsent] 倒。
+ */
+sealed interface RestAttemptLanding {
+    /**
+     * **完成**：服务端收下了这条，[ack] 是它的回执（原样交给既有那六支）。
+     *
+     * 这一档**不进队列**：收下了还排队会白补发一次（幂等键虽然兜得住，但那是浪费，而且会让界面上
+     * 那句「排队中 · 还没连上」变成假话）。
+     */
+    data class Accepted(val ack: ChatAck) : RestAttemptLanding
+
+    /** **进队列**：这条还没上路（分档见 [restAttemptLanding]），等连接一好按同一个键补发。 */
+    data object Unsent : RestAttemptLanding
+
+    /** **回滚**：服务端给过裁决（拒绝），回滚与文案都在既有那六支里（[ack] 原样交给它们）。 */
+    data class Refused(val ack: ChatAck) : RestAttemptLanding
+
+    /** **回滚**：本端异常（401 / 配置类 / 映射不出来的服务端错误），用 [error] 自己的文案。 */
+    data class Errored(val error: CyreneError) : RestAttemptLanding
+}
+
+/**
+ * 这一次「直接试 REST」的产物 ⇒ 落点（**纯函数**，VM 与测试共用）。
+ *
+ * ## 怎么判定「服务端收下了」（不需要等整轮生成完）
+ * `POST /api/v1/chat` 在 `stream:true` 下的回执**不是**内容流，而是一个小 JSON：服务端把这一轮
+ * 交给编排器之后就写回执返回（`Cyrene_v2/internal/services/gateway/chat_stream_dispatch.go:201`
+ * 的 `writeChatStreamAck`：`200 {"stream":true}` / `202 {stream:true,queued:true}` /
+ * `200 {duplicate:true}` / `409 chat_busy` / `503 chat_dispatch_failed`），真正的回合跑在它自己
+ * 派生的 goroutine 上（同文件 `submitChatStream` 的注释：「streamChat 同步返回提交判定，因此这里
+ * 不会阻塞在模型调用上」）。内容帧只走**已连接的 WS**（见 [ChatViewModel.sendViaRestFallback] 的
+ * 「回复为什么收不到、又怎么补回来」一段）。
+ *
+ * 所以本端要判的只是「**回执到了没有、它说的是不是收下了**」：[ChatRepository] 拿到 HTTP 响应并
+ * 把那个小 JSON 解析成 [ChatAck] 就算到了（`ChatApi.sendChat` 返回的是
+ * `Response<ApiEnvelope<ChatAckDto>>`，Retrofit 读完这一小段 body 即返回），**不用**等任何生成。
+ * 也就是说这次调用等的是「**服务端收下了**」这个事实，不是那一轮的产出。
+ *
+ * @param attempt `withTimeoutOrNull(REST_FALLBACK_TIMEOUT_MILLIS) { chatRepository.send(request) }`
+ *   的**原样**产物：`null` = 整通上限到点（本端没等到任何回执）；`Result.success` = 服务端回了
+ *   回执（受理与拒绝都在里面，靠 [ChatAck.isAccepted] 分开）；`Result.failure` = 本端异常
+ *   （网络 / 配置 / 401）。
+ *
+ * ## 判据与优先级
+ * 1. `null`（整通上限到点）⇒ [RestAttemptLanding.Unsent]。本端**没等到任何裁决**：那条消息可能
+ *    已经被服务端收下（只是回执没回来），也可能压根没到——本端分不出来，而**分不出来就往队列
+ *    倒**（fail-closed）。重发还是同一个 `clientMsgId`，服务端若其实已经收下，只会回
+ *    `duplicate`（不会落成第二条）。
+ * 2. `Result.success` 且 [ChatAck.isAccepted] ⇒ [RestAttemptLanding.Accepted]：**服务端收下了**，
+ *    就是发出去了，**不进队列**。
+ * 3. `Result.success` 且不被受理 ⇒ [RestAttemptLanding.Refused]：服务端**给过裁决**（`409` 队列满 /
+ *    `500` 接不住 / `503` 派发失败 / `400` 别的明确拒绝）⇒ 走今天那条回滚 + 文案，绝不偷偷重发。
+ * 4. `Result.failure` ⇒ 交给 [restFailureLanding]（**W41 那套口径一字未改**）：网络族
+ *    （`NoNetwork` / `Dns` / `Timeout` / `ConnectFailed`）与「异常映射不出来」⇒
+ *    [RestAttemptLanding.Unsent]；服务端裁决类（[CyreneError.Server] / [CyreneError.Unauthorized]）
+ *    与配置族（`Tls` / `CleartextBlocked` / `InvalidUrl` / `Parse` / `Unknown`）⇒
+ *    [RestAttemptLanding.Errored]。
+ *
+ * ## fail-closed 落在哪里
+ * 只有第 2 条不进队列，而它要求**回执明确说了「收下了」**。其余每一档不是进队列就是回滚——
+ * 没有任何一条会因为「说不定通了」把一条没上路的消息当成发出去了，也没有任何一条会因为
+ * 「反正会重试」把服务端的裁决吞掉。
+ */
+fun restAttemptLanding(attempt: Result<ChatAck>?): RestAttemptLanding = when {
+    attempt == null -> RestAttemptLanding.Unsent
+
+    attempt.isSuccess -> {
+        val ack = attempt.getOrThrow()
+        if (ack.isAccepted()) RestAttemptLanding.Accepted(ack) else RestAttemptLanding.Refused(ack)
+    }
+
+    // 异常不是 CyreneException（映射不出来）= 本端说不清服务端有没有收下 ⇒ 与网络族同一档。
+    else -> when (val error = (attempt.exceptionOrNull() as? CyreneException)?.error) {
+        null -> RestAttemptLanding.Unsent
+
+        else -> when (restFailureLanding(error)) {
+            RestFailureLanding.Queue -> RestAttemptLanding.Unsent
+            RestFailureLanding.Rollback -> RestAttemptLanding.Errored(error)
+        }
+    }
+}
+
+/**
+ * 回落 REST 失败之后该去哪（**纯函数**）：进队列，还是走今天那条回滚 + 文案。
+ *
+ * ## 为什么网络类失败进队列是安全的（主人 2026-10-05）
+ * 重发用的还是**同一个** `clientMsgId`（就是那条乐观气泡的 `localId`，
+ * [QueuedSend.localId]），而服务端按 `(session_id, client_msg_id)` 唯一索引仲裁：重复到达只回
+ * `chat_duplicate`（WS）/ `{duplicate:true}`（REST），**不会再落库、不会再起一个回合**（契约 v0.56
+ * §3.13）。所以「超时了但服务端其实收下了」这种最难判的情况不需要本端猜：进队列、以后重发一次，
+ * 服务端自己会把重复吃掉。这也是「网络类失败可以自动补发」的**全部**依据——没有幂等键，这里只能
+ * 回滚。
+ *
+ * ## 分档
+ * - `null` ⇒ [RestFailureLanding.Queue]。`null` 的语义是「本端**没等到任何回执**」（自己设的
+ *   [REST_FALLBACK_TIMEOUT_MILLIS] 到点了，或抛了一个映射不出来的异常）：服务端没给过裁决，
+ *   这条就是「还没上路」，与网络类失败同一档。
+ * - [CyreneError.Local] 里的网络族（[CyreneError.LocalKind.NoNetwork] / [CyreneError.LocalKind.Dns] /
+ *   [CyreneError.LocalKind.Timeout] / [CyreneError.LocalKind.ConnectFailed]）⇒
+ *   [RestFailureLanding.Queue]：请求根本没被服务端读到，等一下多半会好。
+ * - 其余一切 ⇒ [RestFailureLanding.Rollback]：
+ *   - [CyreneError.Server] / [CyreneError.Unauthorized]：服务端**回了话**，那就是它的裁决（拒绝 /
+ *     令牌失效）。盲目重发换不来不同结果，而且把「服务端拒绝」说成「还没连上」是假话；
+ *   - [CyreneError.Local] 里的配置与协议族（`Tls` / `CleartextBlocked` / `InvalidUrl` / `Parse` /
+ *     `Unknown`）：**等下去不会变好**，它们要的是用户改设置或换地址，回滚时那句 `userMessage`
+ *     正是他需要看到的东西。这几档在回落这条路上本来就极少出现——完全无网时 client 上的短连接
+ *     超时（[top.yeij.cyrene.data.api.CONNECT_TIMEOUT_MILLIS]）先就把它拦下了。
+ *
+ * 用 `when` 穷举：错误模型将来多一档时，这里必须有人做决定，编不出档位就不该静默继承前一档。
+ */
+fun restFailureLanding(error: CyreneError?): RestFailureLanding = when (error) {
+    null -> RestFailureLanding.Queue
+
+    is CyreneError.Local -> when (error.kind) {
+        CyreneError.LocalKind.NoNetwork,
+        CyreneError.LocalKind.Dns,
+        CyreneError.LocalKind.Timeout,
+        CyreneError.LocalKind.ConnectFailed,
+        -> RestFailureLanding.Queue
+
+        CyreneError.LocalKind.Tls,
+        CyreneError.LocalKind.CleartextBlocked,
+        CyreneError.LocalKind.InvalidUrl,
+        CyreneError.LocalKind.Parse,
+        CyreneError.LocalKind.Unknown,
+        -> RestFailureLanding.Rollback
+    }
+
+    is CyreneError.Server, is CyreneError.Unauthorized -> RestFailureLanding.Rollback
+}
@@ -0,0 +1,266 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.ws.WsState
+import top.yeij.cyrene.domain.chat.ChatSendRouting
+import top.yeij.cyrene.domain.chat.DraftDocument
+import top.yeij.cyrene.domain.chat.SendChannel
+
+/**
+ * 「没连上、还没发出去」的一条待发消息（[ChatUiState.queuedForConnection] 的元素）。
+ *
+ * 队列里只放两样东西：那条乐观气泡的 `localId`（= 上行幂等键 `clientMsgId`）与投递那一刻定下的
+ * 并行声明。正文 / 图片 / 附件**不在这里再存一份**——它们已经在 [ChatUiState.pending] 那条气泡上，
+ * 补发时从那里现取（[ChatUiState.nextQueuedSend]）。同一件事只留一个存放处：队列里再存一份正文，
+ * 就多了一个会跟气泡分叉的真相源。
+ *
+ * [parallel] 是**投递那一刻**按「她忙时发消息」偏好算出来的
+ * （[top.yeij.cyrene.domain.chat.parallelForSend]），补发照它发出、**不重读偏好**：补发的是同一条
+ * 消息的**同一次投递**，排队途中用户切档不该让这条变成另一种投递，而重读还会让「这条消息的投递
+ * 参数」随重连的时刻漂移。
+ */
+data class QueuedSend(
+    /**
+     * 乐观气泡的 `localId`，同时就是**上行幂等键** `clientMsgId`：补发**复用同一个键**，
+     * 绝不铸第二个（契约 v0.56 §3.13，服务端按它判重、重复到达不会落成第二条消息）。
+     */
+    val localId: String,
+    /** 并行声明：只有 `true` 才会在帧上带 `parallel` 键（[top.yeij.cyrene.domain.chat.parallelWireValue]）。 */
+    val parallel: Boolean,
+)
+
+/**
+ * 这次发送**有没有东西可发**（**纯函数**，输入栏的 `send()` 与投递口 `emitAndDeliver` 共用同一次判定）。
+ *
+ * 三样里任意一样在就算有：正文（按 `isNotBlank`——调用方喂进来的本来就是 trim 过的，
+ * 空白串与空串是同一件事）、图片、附件。三样都没有 ⇒ **什么都不发生**：不上屏乐观气泡、
+ * 不进补发队列、不发任何帧、也不说一句话（用户按了个空发送键，没什么可说的）。
+ *
+ * 为什么把它从两处 `if` 里提出来做成一个函数：这条边界此前写在两个地方（输入栏的 `send()` 与
+ * 投递口的 `emitAndDeliver`），两处写法一致但**没有一处能单测**——而「空输入不该发生任何事」正是
+ * 一条要一直成立的边界。合成一个判据之后，入口与投递口用的**必须是同一条**：否则会出现
+ * 「入口认为有内容、投递口认为没有」（或反过来）这种分叉。
+ */
+fun hasSendableContent(
+    text: String,
+    imageUri: String?,
+    documents: List<DraftDocument>,
+): Boolean = text.isNotBlank() || imageUri != null || documents.isNotEmpty()
+
+/** 一次 WS 投递的结论（[wsSendOutcome] 的取值）。 */
+enum class WsSendOutcome {
+    /** 帧已经交给 socket（`sendChat` 回 `true`）：照今天的样子继续等回执，这里什么都不做。 */
+    Dispatched,
+
+    /**
+     * 未就绪 ⇒ 这条**不是失败**。W41 起它不再直接等于「进队列」：调用方（`ChatViewModel.sendThroughLadder`）
+     * 接着往下判一次——**直接试 REST** 把这条发出去（W45 起不再先探连通性，理由见
+     * [top.yeij.cyrene.ui.chat.sendRouteFor]），[WsState.Offline] 那一档与试不成的情况才留在待发态、
+     * 等连接恢复后按发送顺序补发。无论哪一种，**都不回滚、不报错误横幅**。
+     */
+    Queued,
+
+    /** 没发出去，而这一刻连接**就绪** ⇒ 真失败：走今天那条回滚 + 文案。 */
+    Failed,
+}
+
+/**
+ * 「`sendChat` 的回值 + 这一刻的连接状态」⇒ 这条消息该怎么处置（**纯函数**，VM 与测试共用）。
+ *
+ * ## 为什么主人要的是队列而不是回滚（2026-10-05 裁决）
+ * W39 之前，`deliver` 在拿到 `sent == false` 时一律 `rollback(...)`：气泡摘掉、正文退回输入栏，
+ * 而全链路没有自动重发 ⇒ 用户看到的是一句「这条没发出去，请稍后手动重试」。断网 / 弱网下那句话
+ * 把「网络还没好」说成了一次要用户负责的失败，而内容还得他自己看着输入栏再发一遍。主人的裁决是
+ * **未连接就进队列**：不报错、内容不丢、连接恢复后自动补发。W38 给「分享落地」做的正是同一件事
+ * （[ShareLanding]：等连接就绪才取走、恢复后自动补发）——这里沿用同一套语义，只是对象从
+ * 「分享进来的内容」换成了「输入栏发出的这条」，所以两处的措辞与纪律也刻意保持一致。
+ *
+ * ## 判据与优先级
+ * 1. `sent == true` ⇒ [WsSendOutcome.Dispatched]。帧已经交给 socket，连接状态那一格不再参与判断
+ *    （`sendChat` 判的就是它自己的状态）。**成功路径一个字都没动**：不打标记、不说告知、不写任何
+ *    状态——回执（`pending_ack` / REST ack）、落库（`message_persisted`）、队列满（`pending_full`）
+ *    各有各的路。
+ * 2. `sent == false` 且连接**就绪**（[WsState.Connected]）⇒ [WsSendOutcome.Failed]。连接是好的，
+ *    那 `false` 只可能来自另外两种成因（`webSocket` 对象已空 / 已被 cancel，或 `toJson()` / `send()`
+ *    抛了异常），这时候「发送失败」是事实 ⇒ 走 [SEND_FAILED_MESSAGE] 那条既有回滚。
+ * 3. 其余四档（[WsState.Idle] / [WsState.Connecting] / [WsState.Reconnecting] / [WsState.Offline]）
+ *    ⇒ [WsSendOutcome.Queued]。`ChatSocket.send` 的**第一行**就按连接状态挡掉，帧连序列化都没做、
+ *    服务端一个字节都收不到 ⇒ 这不是「发送失败」，是**还没上路**：既不回滚，也不进 `error` 横幅。
+ *    （W41 起这一档由 `sendThroughLadder` 接着往下判：能直接试 REST 发就发，发不了才真进队列。
+ *    本函数只回答「帧交出去了没有、连接是不是好的」，不掺那一次尝试——它要发请求，不能是纯函数。）
+ *
+ * ## 为什么 Offline 也进队列（而不像告知那样另分一档）
+ * 主人的原话是「未连接就进队列」，四档一视同仁：[WsState.Offline] 只是**不会自己变好**，
+ * 内容仍然一个字节没发出去、也一个字都不会丢；两档的差别只在**告知措辞**
+ * （[queuedSendNoticeFor]：这一档说的是「重新登录 / 检查服务器地址」，而不是一个永远等不到的
+ * 「连上后自动发出」）。队列照旧留着：用户重新登录 / 修好地址之后连接一旦就绪，它与其余三档
+ * 一样按序补发。
+ *
+ * 判据只认 `Connected` **一个值**（不是「不等于 `Offline`」之类的近似）——见第 3 条：连接状态的
+ * 另外四档都意味着帧没有被交给任何服务端。
+ */
+fun wsSendOutcome(sent: Boolean, connection: WsState): WsSendOutcome = when {
+    sent -> WsSendOutcome.Dispatched
+    connection == WsState.Connected -> WsSendOutcome.Failed
+    else -> WsSendOutcome.Queued
+}
+
+/**
+ * 记下「这条没发出去、留在本端等连接」（**纯函数**，返回新状态）。
+ *
+ * 队列是**有序**的：新条目追加在末尾，顺序就是**用户发送的先后顺序**，补发照这个顺序走
+ * （[ChatUiState.nextQueuedSend] 只看队头）。调用点只有一处（`deliver` 的「未就绪」分支），
+ * 一条消息只会走到那里一次，所以不需要额外的去重表。
+ */
+fun ChatUiState.withQueuedSend(localId: String, parallel: Boolean): ChatUiState =
+    copy(queuedForConnection = queuedForConnection + QueuedSend(localId, parallel))
+
+/**
+ * 出队（**纯函数**）。出队**恰好一次**正是「同一条不会被补发两次」的结构性保证：补发的每一步都
+ * 只看队头，而队头只在这次投递有了结论（发出去了 / 真失败 / 气泡已经不在）之后才被摘掉
+ * （见 [ChatUiState.nextQueuedSend] 与 `ChatViewModel.flushQueuedSends`）。
+ *
+ * 键不在队列里时**原样返回同一个实例**（Compose 的 key 稳定性靠它）：回滚、收编、落库归一路过
+ * 这里时，队列通常本来就是空的。
+ */
+fun ChatUiState.withoutQueuedSend(localId: String): ChatUiState =
+    if (queuedForConnection.none { it.localId == localId }) {
+        this
+    } else {
+        copy(queuedForConnection = queuedForConnection.filterNot { it.localId == localId })
+    }
+
+/** 这条待发气泡是不是「还没连上、留在本端等连接」的那一类（判据 = 它在补发队列里）。 */
+fun ChatUiState.isAwaitingConnection(localId: String?): Boolean =
+    !localId.isNullOrBlank() && queuedForConnection.any { it.localId == localId }
+
+/** 补发的下一步（[ChatUiState.nextQueuedSend] 的取值）。 */
+sealed interface QueuedSendStep {
+    /** 就发这条：键仍是 [localId]（幂等键，不铸第二个），正文从那条气泡上现取。 */
+    data class Send(val localId: String, val text: String, val parallel: Boolean) : QueuedSendStep
+
+    /** 气泡已经以别的路径了结（回滚 / 落库归一 / 收编都会把它带走）⇒ **只出队、不发**。 */
+    data class Drop(val localId: String) : QueuedSendStep
+
+    /** 这条补发不了（带着图片或附件）⇒ 走今天那条失败路径：回滚 + 文案，内容一条不丢。 */
+    data class Failed(val localId: String) : QueuedSendStep
+
+    /** 队列空：没什么要补的。 */
+    data object Idle : QueuedSendStep
+}
+
+/**
+ * 补发的**下一步**（纯函数，VM 与测试共用）：只看队头，**不出队**。
+ *
+ * 出队由调用方在这条有了结论之后做（[ChatUiState.withoutQueuedSend]），于是「重复触发 ⇒ 不重复
+ * 补发」落在结构上，而不是落在某一次调用的运气上：
+ * - 同一批消息被**多次触发**（连接抖动、重组、重连之后立刻又断）时，每一步拿到的都是同一个键、
+ *   同一段正文——触发器重复**不会**产生第二次出队；
+ * - 出队之后再看，队头就是**下一条**，顺序因此严格等于入队顺序（用户发送的先后顺序）；
+ * - 就算某一帧真的被重复交出去（本端判据失效、进程被杀前重放之类），服务端仍按同一个
+ *   `clientMsgId` 判重（`chat_duplicate`，契约 v0.56 §3.13）⇒ 不会落成第二条消息。
+ *   两道保证各管一头：**出队**管本端不重发，`clientMsgId` 管服务端不落第二条。
+ *
+ * 两种边界也要说清：
+ * - 队头的键在 [ChatUiState.pending] 里找不到 ⇒ [QueuedSendStep.Drop]：气泡已经以别的路径了结
+ *   （回滚把它退回了输入栏、落库归一把它换成了权威消息），这时候再补发就是凭空多出一条。
+ * - 气泡在、但它不是**纯文本**（带图 / 带附件）⇒ [QueuedSendStep.Failed]：WS 那条路只走纯文本
+ *   （有图 / 有附件一律 REST，见 [ChatSendRouting.channelFor]），只发正文会把图与附件**静默丢掉**。
+ *   今天不可能出现（能进队列的仍然只有「本该走 WS 的短文本」那几条——W41 也没有放宽这一条：
+ *   回落 REST 失败时进队列的同样是短文本，有图 / 有附件的那几条走的是另一条分支、压根不进这层阶梯），
+ *   这道闸是给将来路由变化留的：真出现了宁可回滚、让用户自己看见并重发，也不要发出一条缺了图的消息。
+ */
+fun ChatUiState.nextQueuedSend(): QueuedSendStep {
+    val head = queuedForConnection.firstOrNull() ?: return QueuedSendStep.Idle
+    val item = pending.firstOrNull { it.localId == head.localId }
+        ?: return QueuedSendStep.Drop(head.localId)
+    val channel = ChatSendRouting.channelFor(
+        text = item.text,
+        hasImage = !item.imageUri.isNullOrBlank(),
+        hasDocuments = item.documents.isNotEmpty(),
+    )
+    return if (channel == SendChannel.Ws) {
+        QueuedSendStep.Send(head.localId, item.text, head.parallel)
+    } else {
+        QueuedSendStep.Failed(head.localId)
+    }
+}
+
+/**
+ * 这一刻的未就绪该说哪句话（**纯函数**；`null` = 这一刻没什么要说的）。
+ *
+ * 两档**只有措辞不同**：都只在「这条刚进了补发队列」时说一次（判据与不刷屏的记账在
+ * `ChatViewModel.queueForConnection`），队列、补发时机、出队规则一个字都没改。
+ *
+ * - [WsState.Offline] ⇒ [SEND_QUEUED_OFFLINE_NOTICE]：这一档**不会自动重连**，对用户说「连上后
+ *   自动发出」等的是一个**永远不会到来**的连接——那是拿一句不会兑现的承诺糊住一个需要他动手的
+ *   状况（W39 给分享落地定过同一条规矩，见 [SHARE_OFFLINE_NOTICE]）。所以这一档说的是他**能做的
+ *   事**：重新登录（会话过期的路）或检查服务器地址（配置不对的路）。
+ * - [WsState.Connected] ⇒ `null`：那一刻「排队等连接」这件事根本不成立——连接就绪时要么发出去
+ *   要么走真失败那条路（见 [wsSendOutcome]），没有第三档。
+ * - 其余三档（[WsState.Idle] / [WsState.Connecting] / [WsState.Reconnecting]）⇒ [SEND_QUEUED_NOTICE]：
+ *   只是还没连上，连上就会自动发出。
+ *
+ * 用 `when` 穷举，而不是「不是 Offline 就用另一句」：连接状态将来多一档时，这里必须有人做决定
+ * （编不出文案就不该静默继承前一句）。
+ */
+fun queuedSendNoticeFor(connection: WsState): String? = when (connection) {
+    WsState.Offline -> SEND_QUEUED_OFFLINE_NOTICE
+    WsState.Connected -> null
+    WsState.Idle, WsState.Connecting, WsState.Reconnecting -> SEND_QUEUED_NOTICE
+}
+
+/**
+ * 同一条（或同一批）补发反复失败多少次之后**不再多说**（主人 2026-10-06 定案：多次重试失败就静默）。
+ *
+ * 取 3 的理由（**不许**取 1 或 2——那等于根本没告知）：
+ * - 第 1 次失败就是「刚进队列」那一刻，那一句必须说：它是「已经排上队了、不用重打一遍」的全部
+ *   信息量所在；
+ * - 第 2、3 次仍允许开口：连接抖动之后这条又没能上路，用户确实需要重新知道「还是没连上」，
+ *   而不是以为早就发出去了；
+ * - 到第 3 次仍未成功，这条（批）已经明显处在「反复失败」里了，再说一遍只是把同一件事刷第二遍
+ *   ——从此停下告知，静静地等（等的那件事没变：连接一好就自动补发）。
+ *
+ * 静默**不等于丢弃**：这个数只回答「还说不说」，一个字都不动补发队列本身——W38/W40/W41 那条
+ * 「内容一个字节都不丢」的硬要求照旧成立。
+ */
+const val QUEUED_RESEND_SILENCE_THRESHOLD = 3
+
+/**
+ * 这一刻「这条（批）排队等连接」还该不该再说一句（**纯函数**，`false` = 静默）。
+ *
+ * ## 判据与优先级（两个条件同时成立才说）
+ * 1. **静默闸优先**：[failedResends] 达到 [QUEUED_RESEND_SILENCE_THRESHOLD] ⇒ `false`，与
+ *    [toldThisRound] 是什么无关。这是主人 2026-10-06 的定案：反复重试都失败时停止刷屏。
+ * 2. 轮内去重：[toldThisRound] 为真 ⇒ `false`（一轮「队列从空到空」只说一次，连续发几条离线
+ *    消息不会每按一次发送就弹一遍——W40 既有的记账，一字不改）。
+ * 3. 其余（这一轮还没说过、失败次数还没到阈值）⇒ `true`。
+ *
+ * [failedResends] 是**这条（批）已经失败过的补发次数**，只把「补发没能上路、内容仍留在队列里」
+ * 那种失败计进来（见 `ChatViewModel.drainQueuedSends`）：它是唯一会**反复发生**的一种；已被服务端
+ * 裁决 / 已回滚的那两类是一次性了结（内容退回输入栏并给了明确原因），不在这条线上。
+ *
+ * 计数归零由调用方在做，判据是 [queuedResendFailuresAfterDelivery]（**按事故复位**，主人
+ * 2026-10-06 裁决）：一次成功的补发清零，队列**排空**（这一批了结）同样清零。
+ */
+fun queuedSendNoticeAllowed(toldThisRound: Boolean, failedResends: Int): Boolean =
+    !toldThisRound && failedResends < QUEUED_RESEND_SILENCE_THRESHOLD
+
+/**
+ * 一次出队 / 回滚之后，「这一批已经失败过几次」该记成多少（**纯函数**，VM 与测试共用）。
+ *
+ * ## 为什么按事故复位，而不是只在成功时清零（主人 2026-10-06 裁决）
+ * 「事故」= 一次「队列从空到非空、再回到空」，与 [queuedSendNoticeAllowed] 的 `toldThisRound`
+ * 同一个口径。**事故只要结束就复位，不要求它是靠一次成功的补发结束的**：W43 的旧口径只在补发
+ * 成功时清零，于是当一段坏网络的队列**以回滚 / 被收编收场**（一次都没发出去）时，静默计数会一直
+ * 挂在那里 ⇒ 之后连接恢复、再断一次、用户又发消息时，那句话永远说不出口。那不是「少点噪音」，
+ * 是把解释**永久关掉**。
+ *
+ * 三种结束方式都是了结，都该复位：
+ * - [sent] = 这一次补发真的上路了（`WsSendOutcome.Dispatched`）⇒ `0`；
+ * - [drained] = 队列已经空了 ⇒ `0`（回滚把内容退回输入栏、被收编把气泡换成权威消息，都是了结）；
+ * - 其余（队列还有货、这一次又没成功）⇒ 原值：**同一个事故里**的静默照旧生效，不刷屏的规矩不变。
+ *
+ * 它只算「还说不说」，**从不**碰队列内容：静默从来不是丢弃。
+ */
+fun queuedResendFailuresAfterDelivery(failures: Int, sent: Boolean, drained: Boolean): Int =
+    if (sent || drained) 0 else failures
@@ -48,8 +48,10 @@ data class SessionSearchUiState(
 * 会话内搜索的小 ViewModel：**只属于聊天页的搜索态**，与 [ChatViewModel] 完全不相干——
 * 搜索不改变消息窗、不碰 WS、不发消息，所以它不该住进那个正在被另一个模块改动的 VM 里。
 *
- * 作用域由调用方决定（`viewModel(key = "session-search:<id>")`），因此每个会话各有一份，
- * 切回来时上一次的查询与结果还在。取数一律走既有的 `MessageRepository`。
+ * 作用域由调用方决定（`viewModel(key = "session-search:<账号指纹>|<id>")`），因此每个会话各有一份、
+ * 切回来时上一次的查询与结果还在；而**换账号/换服务器后指纹变了 ⇒ 取到的是新实例**，
+ * 面板里不会残留上一个环境的命中（那些命中就是别的服务器的消息正文）。
+ * 取数一律走既有的 `MessageRepository`。
 *
 * 并发：`generation` 是「谁的结果才算数」的代际号。搜索是**用户连打两次回车**就会并发的地方，
 * 加上翻页与首批可以同时存在，没有代际号就会出现「先发的慢请求后到，把新关键词的结果顶掉」。
@@ -0,0 +1,51 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.domain.share.SharedContent
+
+/**
+ * 「一份**已经取走**、正等着用户确认的分享」，外加用户此刻补的那句描述。
+ *
+ * ## 为什么它必须活在 VM 里，而不是一格 `remember`
+ * 这份内容**已经**从待发队列里出队了（[top.yeij.cyrene.app.ShareIntake.take] 是原子出队、
+ * **没有归还路径**），而它此前只挂在一格 `remember(sessionId)` 上——那格状态属于**那一次组合**。
+ * Activity 因转屏 / 深浅色切换重建时组合整份丢掉：那份分享既不在队列里（已经出队）、也不在界面上
+ * （那格状态没了），**静默消失**——用户什么都没看到，也没有任何提示。所以它待在
+ * [ChatUiState.shareConfirm] 里：VM 由 `AppContainer` 那一层持有（`core.session.ChatSessionSlots`
+ * 的 `ViewModelStore`），比组合与 Activity 都活得久。
+ *
+ * 正文（[share]）与描述（[caption]）**绑在同一个值里**是刻意的：描述说的是「你要补的那一句话」，
+ * 它只对这一次确认有意义——分成两格迟早会出现「描述换了一份、正文还是上一份」。
+ *
+ * [caption] 初值**恒为空**：面板上半是这次分享进来的东西，下半才是用户要附加的话，预填一次就会在
+ * 面板里把同一句话排两遍（W53X 的第一版正是这么错的，见 `ShareConfirmPanel` 的 KDoc）。
+ */
+data class ShareConfirmDraft(
+    val share: SharedContent,
+    val caption: String = "",
+)
+
+/**
+ * 「手上这一份 + 去待发队列认领一次」⇒ 面板这一刻该拿着哪一份（**纯函数**，可单测）。
+ *
+ * ## 它回答的是**不可逆那一步该不该走**
+ * [take] 就是 `ShareIntake.take()`（**不可逆**），所以「什么时候允许调它」是这里唯一的正事：
+ * **手上已经有东西时一个字节都不动**——连队列里新来的那条也不碰，它原地等着，面板上此刻摆的
+ * 仍是用户正在看的那一份，不会被后来的一条顶掉。这就是「同一份分享只被取走一次」的落点：
+ * Activity 重建之后新的一帧会再问一次同样的问题，而那时 [holding] 里已经装着那份内容
+ * （它活在 VM 的状态里，活过了重建）⇒ 不会再 [take] 第二次。
+ *
+ * ## 为什么不是「取完之后再拿结果比一比」
+ * 不能靠「第二次 [take] 拿到 null 就当没发生过」兜底：第二次跑起来拿到的要么是 null（白跑一趟），
+ * 要么是**队列里的下一条**——后者会把用户正看着的那份顶掉，那是一次静默丢失。所以闸门必须在
+ * [take] **之前**，而不是在它之后回滚。
+ *
+ * @param holding 这一刻面板手上那一份（[ChatUiState.shareConfirm]）；null = 手上没东西。
+ * @param take 去待发队列认领一条（`ShareIntake.take()`）：**只在 [holding] 为 null 时被调用**，
+ *   且最多一次。返回 null（队列为空）时本函数也回 null——不造一个「什么都没有的面板」。
+ * @return 面板该拿着的那一份：手上原有的**原样**返回（连实例都不换——`ShareConfirmPanel` 用它做
+ *   `remember` 的键，换一份等值的新对象会让预览白重建一次）；手上没有时就是刚认领的那一条。
+ */
+internal fun shareConfirmClaim(
+    holding: ShareConfirmDraft?,
+    take: () -> SharedContent?,
+): ShareConfirmDraft? = holding ?: take()?.let { ShareConfirmDraft(share = it) }
@@ -0,0 +1,757 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.SideEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.layout.onSizeChanged
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.text.TextLayoutResult
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import coil3.compose.AsyncImage
+import top.yeij.cyrene.domain.chat.DocumentChips
+import top.yeij.cyrene.domain.chat.DraftDocument
+import top.yeij.cyrene.domain.parse.ContentPart
+import top.yeij.cyrene.domain.parse.ParsedBubble
+import top.yeij.cyrene.domain.parse.parse
+import top.yeij.cyrene.domain.share.SharedContent
+import top.yeij.cyrene.domain.share.SharedDocument
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.basic.TextField
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+import top.yukonga.miuix.kmp.window.WindowDialog
+
+/**
+ * 「这次分享进来的内容」的确认面板（主人 2026-10-06 拍板：**像其他 IM 一样，先确认再发**）。
+ *
+ * ## 它补上的那一步
+ * 在这之前，分享进来的内容一到连接就绪就被 `ChatViewModel.sendShared` 直接发了出去
+ * （见 `ChatScreen` 里那段落地的 effect），用户**没有任何确认机会**：一张图、一份文件、
+ * 一段从浏览器带来的链接，点完分享就已经在对话里了。面板把这一步补上——**只有点「发送」才真的发**，
+ * 「取消」则本次分享作废（不发送、也不塞回待发队列：那会让「用户刚刚作废的那一份」与「又来了
+ * 新分享」混成同一件事，见 [top.yeij.cyrene.domain.share.PendingShareHolder]）。
+ *
+ * ## 取走只发生一次，面板只负责显示
+ * 这份 [share] **已经**从待发队列里被 `ShareIntake.take()` 取走了（原子出队、没有归还路径），
+ * 它现在活在 `ChatScreen` 的 Compose 状态里。所以本文件里的东西全是**无状态**的：面板不取内容、
+ * 不记账、也不判断「该不该弹」——那些判据与记账都在调用方，这里只把拿到的那一份画出来。
+ *
+ * ## 为什么用 Miuix 的 `WindowDialog`
+ * 项目里其余四个弹层（编辑 / 删除 / 附件预览 / 图片预览）用的是 Compose 的 `androidx.compose.ui.window.Dialog`
+ * + Miuix 内容，因为它当年在 Miuix 里找不到可用的弹层控件。Miuix 0.9.3 其实自带两族（**没有**旧版本的
+ * `extra.*` 包，别照那个去猜 import）：`top.yukonga.miuix.kmp.window.*`（`WindowDialog` /
+ * `WindowBottomSheet`，真正的弹窗）与 `top.yukonga.miuix.kmp.overlay.*`（`OverlayDialog` /
+ * `OverlayBottomSheet`，在当前组合里当一层浮层）。
+ *
+ * 本面板用 **window 族**，两个理由：
+ *
+ * 1. **overlay 族在调用点上是走不通的**（不是偏好，是硬约束）：`OverlayDialog` 靠
+ *    `MiuixPopupUtils.DialogLayout` 把自己登记进 `LocalDialogStates` / `LocalRootDialogStates`，
+ *    而这两个 `staticCompositionLocalOf` **只有 Miuix 的 `Scaffold` 会 provide**（`basic/Scaffold.kt`）。
+ *    本面板的调用点在 `ChatScreen` 里那个 `Scaffold` 的**外面**（与附件预览 / 编辑 / 删除那三个弹层
+ *    同一处），拿不到宿主——而它的默认值是一个没人读的空列表，于是**不报错、也不显示**：
+ *    分享进来会变成「什么都没发生」，正是本项目最忌讳的那种静默失败。（同批的 W53S 用的是
+ *    `OverlayDialog`，因为那个确认框就长在设置页的 `Scaffold` 里——两处调用点的处境不同。）
+ * 2. 它与既有那四个弹层是**同一个形态**：独立窗口、自带遮罩、点面板外或按返回键即取消
+ *    （`onDismissRequest`，这里接的正是「取消」）。这里要的只是一次确认，不需要底部面板那套
+ *    可拖拽的手势。
+ *
+ * ## 预览与输入框的分工（W53X3 更正：输入框是「用户附加的描述」，**不是**正文的复刻）
+ * 上半是**预览**：这次分享进来的东西本身——图片缩略图 / 文件芯片 / **分享自带的正文**。那才是这次
+ * 要发出去的内容，留着它用户才知道「她将收到的是什么」。
+ * 下半是**输入框**：**你**要附加的描述，初值**恒为空**（`caption` 由调用方给空串），空框时显示
+ * 占位符 [SHARE_CONFIRM_CAPTION_PLACEHOLDER]（与输入栏那句「和昔涟说点什么…」同一个写法）。
+ * 发送时真正发出去的正文由 [shareConfirmBody] 拼：分享正文（若有）+ 用户描述（若有），两段都在时
+ * **空行分隔**，只有一段就只用那一段。
+ *
+ * ⚠️ 这里曾经把两件事搞成一件（W53X 的第一版）：输入框被预填成分享进来的正文，在真机上就渲染成
+ * 「同一句话排两遍」——预览的「分享的文字」块一遍、输入框里又一遍，而输入框里那句还看着像一段
+ * 只读展示。错在「这次要发什么」与「你想补一句什么」本来是两件事：前者归预览，后者才归这个输入框。
+ */
+@Composable
+fun ShareConfirmPanel(
+    share: SharedContent,
+    caption: String,
+    onCaptionChange: (String) -> Unit,
+    onSend: () -> Unit,
+    onCancel: () -> Unit,
+) {
+    val preview = remember(share) { shareConfirmPreview(share) }
+
+    // `show = true` 恒成立：这个面板只在有内容可确认时被调用方组合出来（`shareConfirm?.let { … }`），
+    // 关掉它靠的是调用方把那格状态清空（取消 / 发送后的清理都在那边）。
+    WindowDialog(
+        show = true,
+        title = SHARE_CONFIRM_TITLE,
+        onDismissRequest = onCancel,
+    ) {
+        Column(modifier = Modifier.fillMaxWidth()) {
+            if (!preview.isEmpty) {
+                ShareConfirmPreviews(preview)
+                Spacer(Modifier.height(12.dp))
+            }
+            TextField(
+                value = caption,
+                onValueChange = onCaptionChange,
+                modifier = Modifier.fillMaxWidth(),
+                label = SHARE_CONFIRM_CAPTION_PLACEHOLDER,
+                useLabelAsPlaceholder = true,
+                maxLines = 4,
+            )
+            Spacer(Modifier.height(20.dp))
+            Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.End) {
+                // 「取消」放在「发送」之前（与编辑 / 删除那两个弹层同一个排法）：右端永远是那枚
+                // **会真的改动东西**的键。
+                TextButton("取消", onClick = onCancel)
+                Spacer(Modifier.width(8.dp))
+                TextButton(
+                    text = "发送",
+                    onClick = onSend,
+                    // 什么都没有可发时这枚键不该可点：「发送」发出去的那段正文就是 [shareConfirmBody]
+                    // 拼出来的那一段，而 `sendShared` 在「正文空白 + 没有图片 + 没有文件」时会**原地
+                    // 返回**（一次发送都不会发生）。判据是纯函数 [shareConfirmCanSend]，与那条早退同源。
+                    enabled = shareConfirmCanSend(share, caption),
+                )
+            }
+        }
+    }
+}
+
+/**
+ * 这次分享**该展示成哪几样东西**（纯数据，UI 照着渲染）。
+ *
+ * 与 [SharedContent] 不是同一个东西：[SharedContent] 是「用户分享了哪些字段」（还带着丢件计数、
+ * 超限计数这些**告知**用的账），本类型只保留**看得见的那几样**。混用一个类型的话，渲染层迟早会去
+ * 读那些计数字段并顺手显示出来，而它们该说的话由 `shareNoticeFor` 统一成句（它是唯一一处出处）。
+ */
+data class ShareConfirmPreview(
+    /** 要显示的图片（本端 cache 里的 `file://` 地址，顺序即发送顺序）。 */
+    val images: List<String>,
+    /** 要显示的文件（显示名 + 体积由既有的 `DocumentChipRow` 负责换算）。 */
+    val documents: List<SharedDocument>,
+    /** 要显示的正文；空白已归一成空串。 */
+    val text: String,
+) {
+    /** 这份分享带不带正文（空串与「全空白」都算不带——只显示一行空气不是预览）。 */
+    val hasText: Boolean get() = text.isNotEmpty()
+
+    /** 三样都没有 = 这次分享**没有可预览的内容**（此时预览区整块不出现）。 */
+    val isEmpty: Boolean get() = images.isEmpty() && documents.isEmpty() && !hasText
+}
+
+/**
+ * 把一份分享折算成要显示的那几样（**纯函数**，可单测）。
+ *
+ * 两处过滤是**空的也算没有**：一条空地址画出来就是一个空白缩略图（用户会以为图坏了），
+ * 一段全空白的正文占着一行什么也不说。正文两侧的空白一并去掉，与
+ * [top.yeij.cyrene.domain.share.ShareRules.extract] 取正文那一处同一个口径。
+ *
+ * 顺序原样保留：多张图的顺序**就是发送顺序**（第一条消息带第一张，见 `imageSendPlan`），
+ * 预览里换一个顺序就是在替用户改他要发的东西。
+ */
+fun shareConfirmPreview(share: SharedContent): ShareConfirmPreview = ShareConfirmPreview(
+    images = share.images.filter(String::isNotBlank),
+    documents = share.documents.filter { it.uri.isNotBlank() },
+    text = share.text.trim(),
+)
+
+/**
+ * 点「发送」时**真正发出去的那段正文**（**纯函数**，可单测）：分享自带的正文 + 用户附加的描述。
+ *
+ * 三段穷举（这也是它可测的全部形状）：
+ * - 两段都有 ⇒ `分享正文` + [SHARE_CONFIRM_BODY_SEPARATOR] + `用户描述`（**空行**分隔：两段话挨在
+ *   一起时读者分不清哪句是谁说的；空行是「这是两段」的最小表达，也让正文里本来换行的人不受影响）；
+ * - 只有一段 ⇒ 就是那一段（**不补分隔符**：给一段话收个尾是凭空多出来的东西）；
+ * - 都空 ⇒ 空串（此时能发的只剩图片 / 文件，正文那一栏本来就该空着）。
+ *
+ * **内容一字不丢**是红线，这一条覆盖三件事：
+ * 1. 分享正文按 [shareConfirmPreview] 的口径两侧去空白 —— 与 `ShareRules.extract` 取正文、
+ *    以及 `sendShared` 开头 `share.text.trim()` 是**同一个**口径，所以「这里非空」≙「那边发得出去」；
+ * 2. 用户描述同样只去两侧空白，**中间一个字不动**（用户自己换的行是他打的，不是我们排版的地方）；
+ * 3. 一律**不加**来源标记 —— 不拼「[用户分享]」、不加引号、不套模板。来源标识走后端的独立
+ *    `RoleSystem` 来源消息 + 结构化 `SenderName`（`02/F4` / `design/11 §10`）；把标记拼进正文
+ *    = 让用户正文冒充系统指令，那是项目红线。
+ *
+ * 顺序是「分享正文在前、用户描述在后」：先有「她收到的那份东西」，再有「你补的那句话」——反过来的
+ * 话，用户想给一条链接加注释就得先读注释再读链接，而他要注释的正是那条链接。
+ */
+fun shareConfirmBody(share: SharedContent, caption: String): String {
+    val shared = shareConfirmPreview(share).text
+    val own = caption.trim()
+    return when {
+        shared.isEmpty() -> own
+        own.isEmpty() -> shared
+        else -> shared + SHARE_CONFIRM_BODY_SEPARATOR + own
+    }
+}
+
+/**
+ * 两段正文之间的分隔（见 [shareConfirmBody]）：**一个空行**（`\n\n`），不是空格、也不是一行 `——`。
+ *
+ * 只在**两段都在**时出现：`\n\n` 是任何聊天客户端都认的「两段」写法，而多出来的装饰性分隔行
+ * （`---`、`· · ·`）会被对面当成内容读进去。
+ */
+const val SHARE_CONFIRM_BODY_SEPARATOR = "\n\n"
+
+/**
+ * 面板里那枚「发送」该不该可点（**纯函数**，可单测）。
+ *
+ * 判据与 `ChatViewModel.sendShared` 开头那条早退**是同一条**：那边算的是
+ * `share.text.trim()`（也就是本端 [shareConfirmBody] 会拼进去的那一段）非空、或图片非空、或文件非空；
+ * 三样都空时它原地 `return`——一次发送都不会发生。此时把键画成可点的，用户按下去只会看到面板关掉、
+ * 什么也没发生，而他会以为自己少发了一条。所以这里回 `false`。
+ *
+ * 正文那一支直接问 [shareConfirmBody]（**同一个**出处，不是另写一遍 `text + caption` 的非空判断）：
+ * 两条各写各的判据迟早会分叉，那时按钮会在「真发得出去」的时候变灰，或者反过来。
+ *
+ * ⚠️ 三样里**任意一样非空就可发**：纯图片 / 纯文件的回合服务端**支持**（契约：`text` / `image` /
+ * `documents` 任一项非空即可），本端也照旧只发得出去的那几样，不因为「没写文字」而拦下它。
+ */
+fun shareConfirmCanSend(share: SharedContent, caption: String): Boolean {
+    val preview = shareConfirmPreview(share)
+    return shareConfirmBody(share, caption).isNotEmpty() ||
+        preview.images.isNotEmpty() ||
+        preview.documents.isNotEmpty()
+}
+
+/** 面板标题（与顶栏那句「与昔涟」同一称呼）。 */
+const val SHARE_CONFIRM_TITLE = "发送给昔涟"
+
+/**
+ * 输入框的占位符（`useLabelAsPlaceholder`：**只在框里没字时**显示）。
+ *
+ * 与输入栏那句「和昔涟说点什么…」同一个写法、同一个语气：它说的是**你**要补一句什么。
+ * 框里的字是用户自己打的、默认没有（初值恒为空）——所以这句占位符是常态而不是罕见档。
+ */
+const val SHARE_CONFIRM_CAPTION_PLACEHOLDER = "加一句描述…"
+
+/**
+ * 预览区（图片 / 文件 / 正文）。
+ *
+ * ## 高度上限与内部滚动
+ * Miuix 那两族弹层的 `content` **不是 `ColumnScope`**（是普通的 `@Composable () -> Unit`），
+ * 所以这里用不了 `Modifier.weight(1f)`（那是 `ColumnScope` 的扩展）——预览区没法「占剩下的高度」。
+ * 极端的一次分享（4 张图 + 5 份文件 + 一段长正文，键盘还弹着）会把这一个面板顶得很高，
+ * 而面板在手机上贴着屏幕底（`BottomCenter`）：超出的部分会把下面的输入框与两枚按钮挤出屏幕。
+ * 所以预览区自己带一个高度上限 + 内部滚动：内容少时它按内容高（上限不生效），内容多时它滚动、
+ * 输入框与按钮原地不动。上限按状态取（[sharePreviewMaxHeight]）：收起态
+ * [SHARE_PREVIEW_MAX_HEIGHT]、用户展开后 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]。
+ *
+ * ## 正文走**与气泡同一套解析**（W65），所以这一窗里排的是「气泡块」而不是一段原样的字
+ * 正文不是原样铺进去的：它先过 [top.yeij.cyrene.domain.parse.parse]——与 `MessageBubble` 里那条
+ * 完全同一个函数、同一个口径（[sharePreviewBlocks] 只是给结果加了一道兜底）。于是在这里看到的就是
+ * 发出去之后气泡里的样子：每个 `<p>…</p>`（无标签时按空行分段）是**一个独立的块**，
+ * `<action>` / `<narration>`（以及星号那几种写法）不当正文、而是**灰斜体小字**的旁白块，标签本身
+ * 一个字符都不显示。
+ *
+ * 这一层修掉的是 W61 审查发现的一处「所见非所发」：预览此前把正文 `trim` 之后原样显示、**不过解析
+ * 器**，而发送后的气泡过解析器——分享一段 `"<p><p>正文</p>"` 进来，**预览里是一串标签、气泡里只剩
+ * 「正文」**。用户按发送之前看到的不是他将要发出的东西。
+ *
+ * ## 正文给三行，但三行之外是「滚」不是「省略号」
+ * 预览只是「分享进来的是什么」的一眼，而用户要的是按一下发送：把一段几万字的正文整个铺开，这个面板
+ * 就成了一个阅读器。所以正文那一窗**恒为三行高**（[SHARE_PREVIEW_TEXT_LINES]），面板不随正文长短
+ * 变化。
+ *
+ * 但三行之外**不再收成省略号**（W54D 主人拍板改掉了 W53X 的老行为）：W53X3 之后**面板里再没有第二
+ * 个地方放着这段正文**——输入框是「用户附加的描述」（初值恒为空），不再是正文的可编辑副本。于是截断
+ * 成省略号就等于「按发送之前读不到要发的那段正文」，而用户点这颗「发送」要确认的恰恰是它。所以这一窗
+ * 内部可滚（[ShareConfirmBody]）：**面板的高度一分不涨，正文滚着读完**。
+ *
+ * ## 三行读不下时，再给一次「展开」
+ * 三行窗 + 内部滚动管的是「读得到」，但一次只看得见三行；主人要的是**也能一次多看几行**
+ * （W56 拍板：滚动与展开**两个都要**）。所以这一窗**装不下**里面那几块时（判据是
+ * [sharePreviewTextOverflowsWindow]：量出来的内容自然高度比窗口高，正好放满不给）卡片右上一枚
+ * 「展开」把这一窗放到 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，再点「收起」回到三行。装得下时这一枚
+ * **不出现**——短正文上摆一枚点了没反应的「展开」比没有更糟。
+ *
+ * 「读不到尾」这条红线在两种状态下都守：收起态窗内滚，展开态由外层这一层滚（正文那一层不再设上限，
+ * 见 [ShareConfirmBody] 的「展开态为什么干脆不留这一层上限」）。
+ */
+@Composable
+private fun ShareConfirmPreviews(preview: ShareConfirmPreview) {
+    // 展开是用户对**这一段正文**的选择，键在 `preview.text` 上：换一份分享就回到默认的收起，同一份
+    // 分享里重组（写描述、列表刷新…）保持用户选过的样子。
+    //
+    // ⚠️ 转屏（Activity 重建）会回到收起：跨转屏要活下来就得进 `ChatUiState`——W54C 给「已取走的
+    // 分享」与描述走的就是那条路，而那是 `ChatScreen` / `ChatViewModel` 的地盘（本批不许碰）。
+    // `rememberSaveable` 是本仓一次都没用过的新写法，而且弹层窗口有没有带上 saveable registry 没在
+    // 真机上验过，不在这里试——如实留给主人定。
+    var textExpanded by remember(preview.text) { mutableStateOf(false) }
+
+    Column(
+        modifier = Modifier
+            .fillMaxWidth()
+            .heightIn(max = sharePreviewMaxHeight(textExpanded))
+            .verticalScroll(rememberScrollState()),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        if (preview.images.isNotEmpty()) {
+            // 与输入栏上方那排待发图片预览同一形态（同样 64dp、同样的圆角与间距），只是**没有**
+            // 逐张移除的叉：反悔的粒度是整份分享（「取消」），这里不另开一条「只丢掉其中一张」的路
+            // ——那条路要么改动待发队列、要么改动已取走的那一份，两种都会被「又来了新分享」搅浑。
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.spacedBy(6.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                preview.images.forEach { uri ->
+                    AsyncImage(
+                        model = uri,
+                        contentDescription = "这次分享的图片",
+                        modifier = Modifier
+                            .size(64.dp)
+                            .clip(RoundedCornerShape(10.dp)),
+                    )
+                }
+            }
+        }
+        if (preview.documents.isNotEmpty()) {
+            // 文件芯片就是气泡里那一排（显示名 + 体积），一枚都不藏：上限 5 份会占两到三行。
+            DocumentChipRow(chips = preview.documents.map { DocumentChips.of(it.toDraftDocument()) })
+        }
+        if (preview.hasText) {
+            // 「装不装得下」只有排完才知道（折行位置由字号与系统的大字体缩放决定，块数与旁白行数更是
+            // 解析出来的），所以它由正文那一窗量出来之后回调上来，标签这一行凭它决定要不要给出控件。
+            var bodyOverflows by remember(preview.text) { mutableStateOf(false) }
+            Column(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(12.dp))
+                    .background(MiuixTheme.colorScheme.surfaceContainer)
+                    .padding(10.dp),
+            ) {
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Text(
+                        text = "分享的文字",
+                        style = MiuixTheme.textStyles.footnote2,
+                        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                        // 标签是这一行唯一的权重子项，`fill = false` 让这五个字只占自己需要的宽度；
+                        // 真正保证展开控件不被挤掉的是 Row 的测量顺序——**非权重子项（控件与它前面
+                        // 的间距）先量**，权重只分配剩下的空间（同 `SessionDrawerContent` 里那一行）。
+                        modifier = Modifier.weight(1f, fill = false),
+                    )
+                    if (bodyOverflows) {
+                        // 控件挂在**标签这一行**，不挂在正文末尾：展开后正文可能有好几屏，末尾那枚
+                        // 「收起」就成了要滚到底才找得到的东西。
+                        Spacer(Modifier.width(8.dp))
+                        ShareConfirmExpandToggle(
+                            expanded = textExpanded,
+                            onToggle = { textExpanded = !textExpanded },
+                        )
+                    }
+                }
+                ShareConfirmBody(
+                    text = preview.text,
+                    expanded = textExpanded,
+                    onOverflowChange = { bodyOverflows = it },
+                )
+            }
+        }
+    }
+}
+
+/**
+ * 「展开 / 收起」那一枚（见 [ShareConfirmPreviews]）。
+ *
+ * 为什么是两个字而不是箭头图标：基础图标那一套（`MiuixIcons.Basic.*`）里没有展开 / 收起这一类字形
+ * （只有 `Close` / `Search` / `SearchCleanup` / `Sidebar` / `Check` / `ArrowRight` / `ArrowUpDown`
+ * 七枚），而这两句话本身就说清了点下去会怎样。另一处折叠入口——`AdminOverviewScreen` 的路径组头
+ * ——用的是扩展图标里的 `ChevronForward` 加旋转，那是列表行里的形态；这里是一张阅读用的卡片，
+ * 一句话更省地方，也更好认。
+ *
+ * 用 `Text` + `clickable` 而不是 `TextButton`：后者自带按钮高度，会把这一行（以及整块预览）撑高
+ * 一截——同 `MessageBubble` 里那枚「更多」的取舍。
+ */
+@Composable
+private fun ShareConfirmExpandToggle(expanded: Boolean, onToggle: () -> Unit) {
+    Text(
+        text = if (expanded) SHARE_PREVIEW_COLLAPSE_LABEL else SHARE_PREVIEW_EXPAND_LABEL,
+        style = MiuixTheme.textStyles.footnote2,
+        color = MiuixTheme.colorScheme.primary,
+        modifier = Modifier
+            .clip(RoundedCornerShape(8.dp))
+            .clickable(onClick = onToggle)
+            // 内边距写在 `clickable` **后面**：命中的就是这块带内边距的区域——只包住字身的触点太小。
+            .padding(horizontal = 6.dp, vertical = 2.dp),
+    )
+}
+
+/** 相邻两个气泡块之间的间距（见 [ShareConfirmBody]）。块与块靠这一层间距分开，不靠气泡底色。 */
+private val SHARE_PREVIEW_BLOCK_GAP = 6.dp
+
+/** 一个块里旁白行与正文行之间的间距（气泡里那两行也挨得很近，与 `AnnotationLine` 的 2dp 同源）。 */
+private val SHARE_PREVIEW_LINE_GAP = 2.dp
+
+/**
+ * 正文那一窗：**高度恒为三行、再长就在这一窗里滚**（W54D 主人拍板，见 [ShareConfirmPreviews]）；
+ * 用户点了「展开」之后这一窗撤掉自己的上限，全部内容交给外层预览区那一层滚（W56）。
+ *
+ * 里面排的**不是一段原样的字**，而是 [sharePreviewBlocks] 给出的那几个「气泡块」（W65 起走与
+ * `MessageBubble` 同一个 [parse]）。每个块自己排旁白行与正文行，块与块之间留
+ * [SHARE_PREVIEW_BLOCK_GAP]。
+ *
+ * ## 为什么量行高，而不是写一个 dp 常量
+ * 这个上限必须**正好三行**：矮了会在字身上切一刀（滚动停在一个被切开的字形上），高了就等于把「三行」
+ * 这个上限悄悄放宽。而三行有多高没法提前写出来——Miuix 的 `footnote1` 只给了 13sp 的字号，
+ * `lineHeight` 是 `Unspecified`，行高由系统字体的 ascent/descent 决定、随「大字体」设置一起缩放。
+ * 一个 dp 常量在默认字号档上勉强对得上，到了大字号档就会矮一大截（行数不足三行、末行被切）。
+ * 所以这里改为**量**：任一排版结果都能给出「一行多高」（`getLineBottom(0) - getLineTop(0)`），
+ * 窗口高度 = 它 × [SHARE_PREVIEW_TEXT_LINES]（[sharePreviewWindowHeight]）。
+ *
+ * **为什么不再取「第三行的底边」**（那是 W65 之前的量法）：那时这一窗里只有一个 `Text`，
+ * `getLineBottom(2)` 就是那一个文本的三行底。现在里面是**多个块**，每块还有自己的旁白行与间距——
+ * 在任何一个块上取「第三行」都不再是这个窗口的第三行。行高则是唯一一个跨块也成立、且与块数无关的
+ * 量：窗口恒为「三行字高」，块与旁白占掉多少就从这三行里吃掉多少（这正是它的语义）。
+ *
+ * ## 「装不下」是**量**出来的，不是**数**出来的（W65 换掉的判据）
+ * W65 之前这里数的是**一个 `Text` 的行数**（`lineCount > 3`）。多块之后行数不再是一个数得出来的量：
+ * 旁白行与块间距都占高度，却不属于任何一块的「行数」；字号缩放与折行位置也全落在行数之外。按行数算，
+ * 两块各三行加起来是 6、窗口只装得下 3 行——这条能对，但「一块三行 + 一条旁白 + 一层间距」这种更常见
+ * 的形状就数不准了，而这恰是解析之后最常见的形状。
+ *
+ * 所以现在比的是**高度**：内容排下来的自然高度 vs 这一窗的高度（[sharePreviewTextOverflowsWindow]）。
+ * 两个量都是排完才知道的：
+ * - 窗口高由上面的行高乘三给出；
+ * - 自然高由 [androidx.compose.ui.layout.onSizeChanged] 读到——它挂在 `verticalScroll` **里面**，
+ *   而 `verticalScroll` 给子项的是无界高度，所以读到的是内容的**自然高度**（不受这一窗上限影响的那
+ *   一个，收起态与展开态读到的是同一个数）。
+ *
+ * 「自然高度 > 窗口高度」就是「窗里还有东西没露出来」，正是那枚「展开」承诺的事；旁白、块间距、折行、
+ * 系统大字体缩放全被算在同一把尺子上——它可自证的地方在于：两边都是这一帧真实排出来的像素，没有一处
+ * 是我们估的行数或猜的 dp。
+ *
+ * ⚠️ 这个比较在**组合期**算完、由 [SideEffect] 报上去，**不**在排版回调里算：两个量都来自排版回调，
+ * 而在回调里读到的是**上一帧**组合里的值（`contentHeight` 与 `cap` 都不在本帧的组合里），在那里直接比
+ * 会永远差一帧——首帧报一次「不超窗」之后就再也不会报，长正文上那枚「展开」永远不出现。组合期读到的
+ * 一定是最新的一帧，代价只是一次幂等的重复上报（[SideEffect] 每次组合都跑，值没变就是空写）。
+ *
+ * ## ⚠️ 这一层绝不能拿到 [Dp.Infinity]（W58 修的崩溃）
+ * `heightIn(max = Dp.Infinity)` 等于**不施加约束**，而 `verticalScroll` 一旦在**无界高度**下被测量，
+ * Compose 的 `checkScrollableContainerConstraints` 会**直接抛 `IllegalStateException` 把 App 打崩**
+ * （真机复现：分享进来、面板刚打开就闪退，栈是 `ScrollNode.measure` ← `SizeNode.measure` ← `DialogLayout`）。
+ *
+ * 所以这一层的高度上限**只经 [shareConfirmWindowCap] 一个出口**，它给出的**恒是一个有限值**；
+ * 而「这一层干脆不设上限」只发生在展开态——那时它连 `verticalScroll` 一起去掉（见下一节），
+ * 于是「无界高度 + 滚动」这个组合在两种状态下都不成立：
+ * - **首帧**（还没量到）用 [SHARE_PREVIEW_MAX_HEIGHT] 兜底 —— 有限，且正好是收起态外层预览区的上限；
+ * - **展开态**整层不设上限，但**外层**预览区此时换成 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，那仍是一层
+ *   有限的约束在管事（不是「没有约束」）。
+ *
+ * 上限只写一次（`cap` 还是 `null` 时才改），所以不会来回跳：拿到上限后重新排版，块的内容、宽度
+ * 与样式都没变，行高与首帧一致，量出来的值也一样。展开 / 收起切换**也不会改写它**——`cap` 记的
+ * 恒是收起态那一窗的高度（这一窗的折行只由宽度决定，两种状态下排出来的行高一样）。
+ *
+ * ## 展开态为什么干脆不留这一层上限
+ * 展开之后正文可能几屏长。若在这一窗上再设一个上限，就成了「窗外滚 + 窗内滚」两层都要滚的手势
+ * （手指先被内层吃掉、内层滚到底才轮到外层），而两层的上界还互相牵制——最容易出的错就是「明明展开
+ * 了、还剩半截读不到」。所以展开态**只留外层那一层**：预览区的上限抬到
+ * [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，整段正文摊在里面，一层滚到底，读不读得到尾只取决于那一层。
+ * 代价是展开后不能「只滚正文、图片与文件钉着不动」——那要把两层滚动接起来，这个面板不值这个复杂度。
+ *
+ * ## 首帧的那次回流：留着，且确认它看不见
+ * 上限是**首帧之后**才量到的，所以长正文会先按 fallback（[SHARE_PREVIEW_MAX_HEIGHT]）排一次，
+ * 下一帧才收到三行。真机上**看不见**跳动，三条理由：
+ * 1. 首帧那一下撑不动任何别的东西——正文块是预览区里的**最后一个**元素（图片、文件都在它上面），
+ *    而预览区自己还有一层独立的上限在管可视高度：下面没有东西被它顶下去，上面那两样的位置一分
+ *    不动，可视的像素与量完之后**一样**（那些像素由 `heightIn` 的裁剪决定，裁剪高度不变）。
+ * 2. 展开态本来就没有这一层上限，不存在「量完再回落」；而展开 / 收起是用户主动的一次布局变化，
+ *    那一帧的尺寸变化是它的**目的**，不是回流。真正多出来的是展开控件本身——它要到第二帧才出现
+ *    （自然高度是排完才知道的），但这一枚也顶不动东西：标签行里那两句话用的是同一个 `footnote2`，
+ *    行高不变。
+ * 3. 首帧那一次比出来的是「自然高度 vs 150dp 兜底」而不是「vs 三行」：那一帧的结论**可能是错的**
+ *    （一段四五行的正文在 150dp 下看着「装得下」），但它在下一帧就被纠正，而这一枚控件本来就要到
+ *    第二帧才可能摆上——所以这条错判永远看不见。
+ *
+ * 另一条路是在组合期用 `rememberTextMeasurer` 把上限量出来，好让控件从首帧就摆上：那要先知道宽度
+ * （得外包一层 `BoxWithConstraints`），还要自己复现字号、字体缩放与字体回退，等于把排版做两遍——
+ * 为一个看不见的跳动换掉结构不划算，所以不做。
+ *
+ * ## 两层滚动怎么分工
+ * 收起态：这一窗自己滚（正文读完），外层 [ShareConfirmPreviews] 也滚（图片 + 文件芯片 + 这一块
+ * 合起来的高度上限）。手指停在正文上时先滚正文、滚到底再把余量交给外层——`verticalScroll` 本来
+ * 就走嵌套滚动，不用额外接线。
+ *
+ * ⚠️ **展开态必须把这一层整个去掉（上限 + 滚动一起），只留外层那一层滚。** 只去掉上限是不够的 ——
+ * 外层 [ShareConfirmPreviews] 自己就是一个 `verticalScroll`，它给内容的是**无界高度**；这一层若
+ * 留着 `verticalScroll`，那个 scroll 就会在无界高度下被测量 ⇒ 抛同一个
+ * `IllegalStateException`（W58 真机在「点展开」的那一下崩了第二次，就是这么来的）。
+ * 展开后读不读得到尾，只取决于外层那一层。
+ */
+@Composable
+private fun ShareConfirmBody(
+    text: String,
+    expanded: Boolean,
+    onOverflowChange: (Boolean) -> Unit,
+) {
+    val density = LocalDensity.current
+    val blocks = remember(text) { sharePreviewBlocks(text) }
+    // `null` = 还没量到。**不要**拿 [Dp.Infinity] 当这个哨兵值（见 KDoc 里那次崩溃）。
+    var cap by remember(text) { mutableStateOf<Dp?>(null) }
+    // 内容排下来的**自然高度**（见 KDoc：量在 `verticalScroll` 里面，拿到的是不受上限影响的那一个）。
+    var contentHeight by remember(text) { mutableStateOf(0) }
+    // 无条件 `remember`，避免在分支里建状态；滚动位置由这一窗自己的生命周期管。
+    val scroll = rememberScrollState()
+
+    val window = if (expanded) {
+        // 展开态：上限与滚动**一起**去掉（见 KDoc）。内容自然撑开，交给外层预览区那一层滚。
+        Modifier
+    } else {
+        Modifier
+            .heightIn(max = shareConfirmWindowCap(cap))
+            .verticalScroll(scroll)
+    }
+
+    // 一行有多高：正文行与旁白行同为 `footnote1`，所以第一个排完的文本就能给（不限是哪一块的哪一行）。
+    // 量到一次就定死——`cap` 只在这一个分支里被写、且只从 `null` 变成一个值，不会来回跳。
+    val measureLine: (TextLayoutResult) -> Unit = { layout ->
+        if (cap == null && layout.lineCount > 0) {
+            val line = layout.getLineBottom(0) - layout.getLineTop(0)
+            // 0 或负数（还没排稳）不记：150dp 的兜底比一扇零高的窗好（同 [shareConfirmWindowCap] 的取向）。
+            if (line > 0) cap = sharePreviewWindowHeight(with(density) { line.toDp() })
+        }
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxWidth()
+            .then(window)
+            .onSizeChanged { contentHeight = it.height },
+        verticalArrangement = Arrangement.spacedBy(SHARE_PREVIEW_BLOCK_GAP),
+    ) {
+        blocks.forEach { block -> ShareConfirmBlock(block, measureLine) }
+    }
+
+    // 见 KDoc：在组合期算完、由 SideEffect 报上去（两个量在排版回调里读到的是上一帧的值）。
+    val overflows = sharePreviewTextOverflowsWindow(
+        contentHeightPx = contentHeight,
+        windowHeightPx = with(density) { shareConfirmWindowCap(cap).roundToPx() },
+    )
+    SideEffect { onOverflowChange(overflows) }
+}
+
+/**
+ * 预览里的**一个气泡块**：上依附的旁白 + 正文 + 下依附的旁白。
+ *
+ * 这个顺序就是 `MessageBubble` 里那个 `Bubble` 的顺序（`head` → 正文 → `tail`），用的也是同一个
+ * [parse] 给出的同一批块——「预览里长这样」与「发出去之后长那样」因此是**同一套判据**的两次渲染。
+ *
+ * 块与块之间只留一层间距（外层 [ShareConfirmBody] 的 `spacedBy`），**不画气泡底色**：这一栏是面板里
+ * 的一张卡片（`surfaceContainer` 底），而气泡底色在聊天里表示「谁说的」——用户那条是 `primary` 色、
+ * 她那侧是灰。在确认面板里复刻一层假气泡底色会让人以为这里已经是聊天记录；而且那层内边距要从三行窗
+ * 里再吃掉近一行，正是 W54D 之后最不该动的那点可见正文。
+ */
+@Composable
+private fun ShareConfirmBlock(block: ParsedBubble, onTextLayout: (TextLayoutResult) -> Unit) {
+    Column(
+        modifier = Modifier.fillMaxWidth(),
+        verticalArrangement = Arrangement.spacedBy(SHARE_PREVIEW_LINE_GAP),
+    ) {
+        ShareConfirmAnnotation(block.head, onTextLayout)
+        if (block.body.isNotEmpty()) {
+            Text(
+                text = block.body,
+                style = MiuixTheme.textStyles.footnote1,
+                onTextLayout = onTextLayout,
+            )
+        }
+        ShareConfirmAnnotation(block.tail, onTextLayout)
+    }
+}
+
+/**
+ * 预览里的旁白行：**灰斜体小字**——与气泡里那行（`MessageBubble` 的 `AnnotationLine`）同一个形态、
+ * 同一种拼法（多个片段用一个空格连起来），字全是 [parse] 给的那几个 `ContentPart` 的原文。
+ *
+ * ⚠️ 这里**不**读 `LocalAppPrefs.showNarration`（气泡那行会读）。那个偏好管的是**聊天记录里**要不要
+ * 显示旁白，而这块面板回答的是「她将收到的是什么」：按那个偏好把旁白藏起来，就等于让用户在按下发送
+ * 之前看不到这次要发出去的一部分内容——而 W61 审查发现的那处「预览里是标签、气泡里只剩正文」，错的
+ * 正是同一件事（看到的不是要发的）。要改成与气泡一样随时可以，但那是主人拍板的事，不在这里顺手做。
+ */
+@Composable
+private fun ShareConfirmAnnotation(parts: List<ContentPart>, onTextLayout: (TextLayoutResult) -> Unit) {
+    val text = parts.joinToString(" ") { it.text }.trim()
+    if (text.isEmpty()) return
+    Text(
+        text = text,
+        style = MiuixTheme.textStyles.footnote1,
+        fontStyle = FontStyle.Italic,
+        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+        onTextLayout = onTextLayout,
+    )
+}
+
+/**
+ * **收起态**那一窗的高度上限（**纯函数**，可单测）。
+ *
+ * 量到过就用量的，还没量到就用 [SHARE_PREVIEW_MAX_HEIGHT] 兜底 —— 兜底必须是**有限值**，因为
+ * `heightIn` 与 `verticalScroll` 就在同一串 modifier 上。
+ *
+ * 展开态**不走这里**：那一态连 `verticalScroll` 一起去掉（只留外层预览区那一层滚），没有「上限」
+ * 这个维度可给 —— 见 [ShareConfirmBody] 的 KDoc。
+ *
+ * ⚠️ 返回值**永远是一个有限值** —— `heightIn(max = Dp.Infinity)` 等于不施加约束，而
+ * `verticalScroll` 在无界高度下被测量时 Compose 会直接抛 `IllegalStateException` 把 App 打崩
+ * （W58 真机崩过两次：一次是初值用了 `Dp.Infinity`，一次是展开态只去掉了上限）。这条不变量有单测钉着。
+ *
+ * 所以非有限的那几个取值（[Dp.Infinity] 与 [Dp.Unspecified]，后者是 `NaN`）**与「还没量到」同等对待**，
+ * 一律回落 [SHARE_PREVIEW_MAX_HEIGHT]：这条 KDoc 写的是一条**判据**，而不该只是对调用方的请求——本函数
+ * 是这一层唯一的出口，它自己要能保证「给出去的上限总是有限」。今天唯一的调用方传的是 `null` 或
+ * [sharePreviewWindowHeight] 的结果（正数 × 三，恒有限），所以这一道守卫不改变任何现状；它挡的是
+ * **下一次**有人顺手把 `Dp.Infinity` 当「不设上限」传进来（那正是 W58 第一次崩溃的形状）。
+ */
+internal fun shareConfirmWindowCap(measured: Dp?): Dp =
+    measured?.takeIf { it.value.isFinite() } ?: SHARE_PREVIEW_MAX_HEIGHT
+
+/** 预览区在**收起态**的高度上限（见 [ShareConfirmPreviews]：超出的部分靠内部滚动看）。 */
+internal val SHARE_PREVIEW_MAX_HEIGHT = 150.dp
+
+/**
+ * 预览区在**展开态**的高度上限（用户点了「展开」之后，见 [ShareConfirmPreviews]）。
+ *
+ * 为什么要抬：展开是**用户自己的一个动作**，要的就是「一次多看几行」。上限不动的话这一窗永远只有
+ * 三行高，点开等于没点——正文那一窗顶到 [SHARE_PREVIEW_MAX_HEIGHT] 也只是把三行换成十来行里的一
+ * 小截。所以展开态必须真的给回高度。
+ *
+ * 为什么是 240dp 而不是更大：这个上限管的是**整个预览区**，而它下面还压着描述输入框（最多 4 行）
+ * 与两枚按钮，面板又贴着屏幕底（`BottomCenter`）、键盘一弹可用高度只剩半屏上下。150 → 240 在默认
+ * 字号档上把正文窗从三行抬到十行左右（`footnote1` 13sp，行高由系统字体决定、随机型与大字体设置一起
+ * 变），加上标题 / 输入框 / 按钮之后整块仍在半屏出头；再往上（例如给到整屏的六成）先被顶掉的会是
+ * 两枚按钮。
+ *
+ * ⚠️ 这个数**没有在真机上量过**，是按上面那笔账取的保守值，观感由主人验收。要调只改这一处：
+ * 预览区那一层的高度上限取的就是 [sharePreviewMaxHeight] 这一个出口。
+ */
+internal val SHARE_PREVIEW_EXPANDED_MAX_HEIGHT = 240.dp
+
+/**
+ * 预览里正文那一窗给几行（W54D 起**不再截断**，超出的部分在窗内滚动，见 [ShareConfirmBody]）。
+ *
+ * 它同时是窗口高度那笔账里唯一的数：窗口高 = **量到的行高** × 这个数（[sharePreviewWindowHeight]）。
+ *
+ * `internal` 是为了让 `ShareConfirmTest` 能把这个数钉成字面量：面板的滚动行为单测够不着（本模块没有
+ * Compose UI 测试的依赖），能钉住的只有「这一窗是三行」这条判据本身。
+ */
+internal const val SHARE_PREVIEW_TEXT_LINES = 3
+
+/**
+ * 展开控件上那两句话：点它就在这两句之间切换。
+ *
+ * 两句都必须是**动作**（「展开」/「收起」），不能是「更多」/「更少」——后者说的是内容有多少，读的人
+ * 不知道点下去会发生什么。
+ */
+internal const val SHARE_PREVIEW_EXPAND_LABEL = "展开"
+internal const val SHARE_PREVIEW_COLLAPSE_LABEL = "收起"
+
+/**
+ * 三行窗口有多高（**纯函数**，可单测）：量到的一行高度 × [SHARE_PREVIEW_TEXT_LINES]。
+ *
+ * 行高只能是**量**出来的（见 [ShareConfirmBody] 的「为什么量行高，而不是写一个 dp 常量」），所以这里
+ * 只做乘法、不掺任何 dp 常量：大字体档下量到的行高更大，窗口就跟着更高，「三行」始终是三行。把这个数
+ * 留在唯一一处，改它只改 [SHARE_PREVIEW_TEXT_LINES]。
+ */
+internal fun sharePreviewWindowHeight(lineHeight: Dp): Dp =
+    lineHeight * SHARE_PREVIEW_TEXT_LINES
+
+/**
+ * 预览正文区该渲染成哪几块（**纯函数**，可单测）——**走的就是气泡那一套解析**（W65 起）。
+ *
+ * 用的是 `MessageBubble` 里那同**一个** [parse]，连兜底都是同一条：解析结果为空（或全是被丢掉的空块）
+ * 时回落到「整段原样显示」的那一块，与那边 `parsed.ifEmpty { listOf(plainBubble(content)) }` 逐字同义。
+ * 所以「预览里看不到那一串标签」不是本函数自己剥出来的，而是 [parse] 的既有语义（落单标签一律剥掉、
+ * 完整块切气泡、旁白另成一类）——这里一个字符都不改写、也不另写一套「去标签」。
+ *
+ * **兜底不是可选项**：`parse` 对某些输入会回空列表（纯空白是既有的一档，落单标签被剥光是另一档，
+ * 见 `ShareTextPipelineTest` 里的 `<p><p>` 那几条），而面板的 [ShareConfirmPreview.hasText] 只管
+ * 「正文非空白」，管不到解析结果。少了这条兜底，用户就会在一块**空白**前面按发送——而正文这一栏是他按
+ * 发送之前唯一能核对的东西。
+ *
+ * 正文在这里**不再 trim**：两侧空白早在 [shareConfirmPreview] 那一站去过一次（`share.text.trim()`，
+ * 与 `sendShared` 开头同一个口径），这里再来一次只会多一个说法不一的出处。
+ */
+internal fun sharePreviewBlocks(text: String): List<ParsedBubble> =
+    parse(text).filterNot { it.isEmpty }.ifEmpty {
+        listOf(ParsedBubble(body = text, parts = emptyList(), head = emptyList(), tail = emptyList()))
+    }
+
+/**
+ * 这一窗**装不下**里面的内容吗（**纯函数**，可单测）——也就是「要不要给出展开控件」。
+ *
+ * ## 判据是**高度**，不是行数（W65 换掉的）
+ * W65 之前这里数的是**一个 `Text` 的行数**（`lineCount > SHARE_PREVIEW_TEXT_LINES`）。正文改走解析
+ * 之后这一窗里是**多个块**，每块还各自带旁白行与块间距，于是行数不再是一个覆盖得住窗口的量：
+ *
+ * - 旁白行与块间距都占高度，却谁也不属于哪一块的「行数」；
+ * - 折行位置、字号与系统大字体缩放都落在行数之外：「两个块各占两行、中间一层间距」这种最常见的形状，
+ *   按行数只能说「4 > 3」，说不出它到底差多少，也说不出一块内部的折行吃掉了第二块的位置；
+ * - 反过来也漏：「一块两行 + 一条两行的旁白」数出来是 4 行，但它真正超出的高度取决于那两层间距与
+ *   旁白自己的行高——行数这个量从头到尾没有把它们算进去。
+ *
+ * 所以比的是**两边真实排出来的像素**：内容自然高度（由挂在 `verticalScroll` 里面的
+ * [androidx.compose.ui.layout.onSizeChanged] 读到，见 [ShareConfirmBody]）vs 这一窗的高度
+ * （[sharePreviewWindowHeight] 那个口径：量到的行高 × 三）。「自然高度 > 窗口高度」**就是**「窗里还有
+ * 东西没露出来」，正是那枚「展开」承诺的事。它可自证的地方在于：两个量都是这一帧真实排出来的像素，
+ * 没有任何一处是我们估的行数或猜的 dp。
+ *
+ * 也不是 `hasVisualOverflow`：裁剪落在这一窗外面那层 `Column` 的 `heightIn(max = cap)` 上，而每个
+ * `Text` 自己的排版宽度是满宽、高度不受限（`verticalScroll` 给子项的就是无上限约束），所以它们永远报
+ * 「没有溢出」——拿它当判据会把控件在最长的那种正文上漏掉。
+ *
+ * ## 边界与首帧
+ * 严格大于：**正好一样高**就是整段都在窗里（窗口底下一条不多），此时给一枚「展开」是点了没有反应的
+ * 假控件。
+ *
+ * 任何一边还没量到（`0`）都回 `false`：首帧摆上一枚点了没有反应的「展开」比晚一帧出现更糟。
+ */
+internal fun sharePreviewTextOverflowsWindow(contentHeightPx: Int, windowHeightPx: Int): Boolean =
+    contentHeightPx > 0 && windowHeightPx > 0 && contentHeightPx > windowHeightPx
+
+/**
+ * 预览区当前该给多高（**纯函数**，可单测）：收起态 [SHARE_PREVIEW_MAX_HEIGHT]、展开态
+ * [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]。
+ *
+ * 把「哪个状态用哪个上限」收在这一处，调用点（[ShareConfirmPreviews]）只读结论：单测钉住的就是这条
+ * 判据本身——两个状态与两个上限的对应关系要是被改反了（例如展开反而变矮），会在这里被抓住。
+ */
+internal fun sharePreviewMaxHeight(expanded: Boolean): Dp =
+    if (expanded) SHARE_PREVIEW_EXPANDED_MAX_HEIGHT else SHARE_PREVIEW_MAX_HEIGHT
+
+/**
+ * 分享进来的一份文件 ⇒ 待发附件。
+ *
+ * `ChatViewModel.sendShared` 里也有同一段三字段的搬运（那边是发给上传链的），**不抽公共**是刻意的：
+ * 抽出来就要动那两个文件（一个是别的并行改动正在碰的 `ChatScreen` 附近，一个是发送路径），
+ * 而这一处只是给芯片显示用的**只读**形态——真正的发送仍然只经过 `sendShared` 那一条，
+ * 两条路各有各的用处。第三次复制出现时再抽（本项目对重复的硬规矩是三次起抽）。
+ */
+private fun SharedDocument.toDraftDocument(): DraftDocument = DraftDocument(
+    uri = uri,
+    displayName = displayName,
+    sizeBytes = sizeBytes,
+)
@@ -0,0 +1,109 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.ws.WsState
+
+/** 「分享进来的内容」这一刻该做什么（[shareLanding] 的取值）。 */
+enum class ShareLanding {
+    /** 没有待发内容：什么都不做（任何连接状态下都一样）。 */
+    Nothing,
+
+    /** 还没连上，继续等：**既不取走也不发送**，内容原封不动留在待发队列里。 */
+    KeepWaiting,
+
+    /** 等到该说一句的时候了：说一次「还没连上、连上后自动发出」（柔和通道，不是错误横幅）。 */
+    TellWaiting,
+
+    /**
+     * 等到该说一句的时候了，而这一刻的未就绪是**不可恢复**的那一档（[WsState.Offline]）：
+     * 说一次 [SHARE_OFFLINE_NOTICE]——说清「需要重新登录或检查服务器地址」，**不**说
+     * 「连上后自动发出」（那句话在 `Offline` 上永远不会到来）。
+     */
+    TellOffline,
+
+    /** 连接就绪：取走一条并交给确认面板（点「发送」才真的发出去）。 */
+    Send,
+}
+
+/**
+ * 分享落地时机的判据（纯函数，UI 与测试共用）。
+ *
+ * ## 为什么取走必须晚于「连接就绪」
+ * 短文本走 WS `chat` 帧，而**分享冷启动必然赶上握手还没完成**：`ChatSocket` 未就绪时
+ * `sendChat` 回 `false`，`ChatViewModel.deliver` 随即 `rollback(localId, "发送失败，请重试")`。
+ * 2026-10-05 11:56 实机取证：客户端在 `GET /ws/chat status=200`（握手成功）前后的窗口里投递分享，
+ * 得到「发送失败，请重试」+ 正文退回输入栏，而**后端零请求**（`POST /api/v1/chat` 一条都没有，
+ * 也没有任何 `error` 帧）——那条横幅把「一次都没尝试发出去」说成了「发送失败」。
+ *
+ * 更糟的是它会**吃掉重试资格**：[top.yeij.cyrene.domain.share.PendingShareHolder.take] 是原子出队、
+ * **没有归还路径**。失败之后内容既不在待发队列里、也不在服务端，只剩回滚进输入栏的那一份
+ * （多图分享里除了第一张，其余几条连输入栏都回不去）。所以在连接就绪之前**一个字节都别动**：
+ * 不 `take()`、不 `sendShared`、不产生任何 error 横幅——**超时绝不等于发送失败**。
+ *
+ * ## 判据与优先级
+ * 1. **没有待发内容** ⇒ [ShareLanding.Nothing]：任何连接状态下都不做事、也不说话。
+ * 2. **[WsState.Connected]** ⇒ [ShareLanding.Send]：取走一条并交给确认面板（点「发送」才真的发）。
+ *    它**压过**后面每一条——连接一到就该认领，哪怕此前已经等够久、那句「等连上会自动发」也说过了。
+ *    返回值是**单值动作**，所以「认领」与「告知」在类型上就不可能同时发生（不会既取了又报怨还没连上）。
+ * 3. 未就绪且**还没等够久**（`waitedLong = false`）⇒ [ShareLanding.KeepWaiting]：继续等，什么都不说
+ *    （刚分享进来就弹一句「还没连上」是噪声，握手正常也就几百毫秒）。
+ * 4. 未就绪、已等够久、且**还没说过** ⇒ 说一次。说哪一句由连接状态分**两档**：可恢复的那三档
+ *    （[WsState.Idle] / [WsState.Connecting] / [WsState.Reconnecting]）是 [ShareLanding.TellWaiting]，
+ *    不可恢复的 [WsState.Offline] 是 [ShareLanding.TellOffline]（哪句配哪档见 [shareWaitingNotice]）。
+ *    两档**只有措辞不同**：第 3、5 条对它们一模一样（等够久才说、同一轮只说一次），取走与发送的时机
+ *    一个字都没改。
+ * 5. 未就绪、已等够久、且**已经说过** ⇒ [ShareLanding.KeepWaiting]：同一轮等待只说一次。
+ *    这一步不是可有可无的：连接在 `Connecting` 与 `Reconnecting` 之间抖动会让调用方反复问到
+ *    同一个问题，没有这一条就是反复弹同一句话。
+ *
+ * ## 为什么 `Offline` 要单独一档
+ * [WsState.Offline] 是**终态**：握手 401 且续不上、或缺少 token / 服务器地址，它**不会自动重连**。
+ * 对它说「连上后自动发出」，用户等的是一个**永远不会到来**的连接——那是拿一句不会兑现的承诺糊住
+ * 一个需要他动手的状况，比不说更糟。这一档仍要告知（内容确实一个字节都没发出去，用户得知道，
+ * 否则会以为东西丢了、重新分享一遍），但要说他**能做的事**：重新登录或检查服务器地址。
+ * 这里没有发明任何新的状态语义：`Offline` 是 [WsState] 自己的一档，`ChatScreen` 的 `connectionLabel`
+ * 早就把它在界面上单独念成「离线」，也正是那一档的分野（会不会自己重连）。
+ *
+ * ## 「等够久」与「说过了」为什么不在这里判
+ * 判据本身**看不出时间与历史**——那样它才是一个能穷举、能在 JVM 上单测的函数（见 `ShareLandingTest`），
+ * 而不是又一份会随重组漂移的 Compose 状态。两个事实由调用方各自记账（`ChatScreen` 里那两个
+ * `remember`），且**它们的生命周期也不一样**：「说过了」在连接抖动时不归零（不刷屏），
+ * 而「等够久」的计时只看「队列里有没有东西」与「连上了没有」这两个事实。
+ *
+ * @param hasPending 待发队列里有没有内容。只看一眼的判据是 `ShareIntake.pending`（StateFlow），
+ *   **绝不是 `take()`**——那是出队。
+ * @param connection 这一刻的 WS 连接状态。
+ * @param waitedLong 这一轮等待是否已经等够久（够久才值得说那句话）。
+ * @param alreadyTold 这一轮等待是否已经告知过（同一轮只说一次）。
+ */
+fun shareLanding(
+    hasPending: Boolean,
+    connection: WsState,
+    waitedLong: Boolean,
+    alreadyTold: Boolean,
+): ShareLanding = when {
+    !hasPending -> ShareLanding.Nothing
+    connection == WsState.Connected -> ShareLanding.Send
+    !waitedLong -> ShareLanding.KeepWaiting
+    alreadyTold -> ShareLanding.KeepWaiting
+    // 只有 Offline 这一档不会自己回来（见上面「为什么 Offline 要单独一档」）。
+    connection == WsState.Offline -> ShareLanding.TellOffline
+    else -> ShareLanding.TellWaiting
+}
+
+/**
+ * 告知这一档该说的那句话（**纯函数**；`null` = 这一刻什么都不该说）。
+ *
+ * 把「哪个动作配哪句话」也做成可单测的，是因为两条告知**唯一**的差别就是措辞，而搞混它们的代价
+ * 并不对称：对 `Offline` 说「连上后自动发出」是承诺一件不会发生的事（那句文案永远不会兑现），
+ * 对 `Connecting` / `Reconnecting` 说「重新登录」则是把一次几百毫秒的握手说成了故障。
+ * 两句话各自写在 `ChatScreen` 的 [SHARE_NOT_CONNECTED_NOTICE] / [SHARE_OFFLINE_NOTICE] 旁边，
+ * 这里只做映射——于是「哪档说哪句」不需要组合一个界面就能测（见 `ShareLandingTest`）。
+ *
+ * [ShareLanding.Send] / [ShareLanding.Nothing] / [ShareLanding.KeepWaiting] 都回 `null`：
+ * 它们不是告知档（要么发送、要么什么都不说）。
+ */
+fun shareWaitingNotice(landing: ShareLanding): String? = when (landing) {
+    ShareLanding.TellWaiting -> SHARE_NOT_CONNECTED_NOTICE
+    ShareLanding.TellOffline -> SHARE_OFFLINE_NOTICE
+    ShareLanding.Nothing, ShareLanding.KeepWaiting, ShareLanding.Send -> null
+}
@@ -0,0 +1,43 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.domain.share.ShareTextSource
+import top.yeij.cyrene.domain.share.SharedContent
+
+/**
+ * 「这段正文是从对方给的**分享标题**回落来的」——面板上那句如实的小字（**纯函数**，可单测）。
+ *
+ * ## 它补的是哪一处
+ * 取正文的回落链（[top.yeij.cyrene.domain.share.ShareRules.extract]：`EXTRA_TEXT` →
+ * `EXTRA_SUBJECT` → `EXTRA_TITLE`）让「对方只给了标题」的那次分享**不再静默**——用户可以确认、可以
+ * 取消。但回落来的那一段与真正文**长得一模一样**：预览里只有一句话时，用户会以为对方发来的就是这句
+ * 正文，其实本端只拿到了标题。所以这里给出一句**只出现在界面上**的说明。
+ *
+ * ## 红线：它绝不进正文
+ * 这句话是**本端渲染层**的信息，一个字都不许拼进将要发送的那段正文（`shareConfirmBody` 拼的是分享
+ * 正文 + 用户描述，与这里无关）：把来源标记拼进正文 = 让用户正文冒充系统指令，是项目红线
+ * （见 `ShareRules` 的「为什么正文一个字都不加」）。所以这条消息的内容**永远只是正文本身**，
+ * 预览里那段字与发出去的那条消息逐字相同。
+ *
+ * ## 为什么 `Subject` 与 `Title` 共用一句
+ * 两档在**数据**上分得很清（[ShareTextSource]，排查时要看得见对方把内容塞进了哪个字段），但对用户说
+ * 的是同一件事：标题与主题在他眼里没有区别。各写一句只会多出一处迟早会走样的措辞。
+ *
+ * ## 不说「正文」的那一档为什么回 `null`
+ * [ShareTextSource.Text] 是规范路径（正文本来就是正文）：一切照旧，**一个字都不说**——正常落地时
+ * 说话才是噪声（与 `shareNoticeFor` 的静默边界同一条纪律）。
+ *
+ * @return 该说的那句话；没有要说的（正文来自 `EXTRA_TEXT`）回 `null`。
+ */
+fun shareTextOriginNotice(share: SharedContent): String? = when (share.textSource) {
+    ShareTextSource.Text -> null
+    ShareTextSource.Subject, ShareTextSource.Title -> SHARE_TEXT_FROM_TITLE_NOTICE
+}
+
+/**
+ * 那句话说出口的样子。
+ *
+ * 两件事要在同一句里说清：**它是什么**（对方给的分享标题）与**缺了什么**（对方没有提供正文）——
+ * 只说前一半，用户仍会以为这句话就是对方发来的正文；只说后一半，他不知道预览里那行字是从哪冒出来的。
+ * 刻意**不说**「失败」「错误」：这一次分享的内容一个字节都没丢，只是它本来就只有标题。
+ */
+const val SHARE_TEXT_FROM_TITLE_NOTICE = "这段文字来自对方的分享标题（对方没有提供正文）"
@@ -88,10 +88,13 @@ fun ToolCard(
                FoldCardLabel("参数")
                FoldCardBody(tool.arguments)
            }
-            if (tool.output.isNotBlank()) {
+            // 结果区是否出现**完全**由 [toolResultTextOf] 决定：`null` 就整块不画（连标签和
+            // 上方那道 Spacer 都不画），于是「摘要缺席」时这一屏与后端补这个键之前**逐字节相同**。
+            val result = toolResultTextOf(tool)
+            if (result != null) {
                Spacer(Modifier.height(6.dp))
                FoldCardLabel("结果")
-                FoldCardBody(tool.output)
+                FoldCardBody(result)
            }
        }
    }
@@ -0,0 +1,238 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.chat.TurnBucket
+import top.yeij.cyrene.domain.chat.TurnPhase
+import top.yeij.cyrene.domain.chat.bindingOfMessage
+import top.yeij.cyrene.domain.chat.legBadgeOf
+import top.yeij.cyrene.domain.chat.turnPhaseOf
+import top.yeij.cyrene.domain.parse.ParsedBubble
+
+/**
+ * 流式气泡的**两级分桶**（规范 §1.4 / §1.7 第 1 条）在整个 UI 层的那一半。
+ *
+ * 这一层只回答两个问题，且都做成纯函数（`ChatViewModel` 与测试共用，渲染层也直接读它）：
+ * 1. **一帧该改哪一路的流式气泡**（[withLeg] / [beginLeg] / [finishingLeg] / [withoutLeg]）；
+ * 2. **一条消息现在处在六态里的哪一态**（[ChatUiState.phaseOf]）。
+ *
+ * 老代码里只有一个 `streaming: StreamingState?`，所有 `message.delta` 都往那一个气泡上堆——
+ * 两路并行时两条回复会被糊成一条。这里的每条 [StreamingLeg] 各带自己的 [TurnBucket]，
+ * 于是「同一会话、不同 turnId」的增量天然分开。
+ *
+ * ## 单路时为什么逐字不变
+ * 桶按 `turnId` 分，而真后端每个回合的 `turnId` 都是**新建的随机值**（网关 `newTurnID()`）——
+ * 单路时任何时刻**只有一个**活着的桶，等价于「只有那一个气泡」；帧壳没给 `turnId` 时全部帧落进
+ * 匿名桶（[top.yeij.cyrene.domain.chat.turnBucketOf]），同样是**只有一个**桶。所以本文件对
+ * 「服务端 v0.65 之前」的每一个现实路径都只是把原来那一个气泡换了个容器。
+ */
+
+/**
+ * 一路正在生长的助手回复。
+ *
+ * [bucket] 是它的身份（`sessionId` + `turnId`），[state] 就是老代码里那个 `StreamingState`——
+ * 思维链 / 工具卡 / 正文段一个字都没改，只是现在**一路一份**。
+ */
+data class StreamingLeg(val bucket: TurnBucket, val state: StreamingState)
+
+/** 取某一路（没有则 `null`）。 */
+fun List<StreamingLeg>.leg(bucket: TurnBucket): StreamingLeg? = firstOrNull { it.bucket == bucket }
+
+/**
+ * 改某一路：**有则改、无则新建并追加到末尾**（顺序即两路的启动顺序，界面上先起的在上）。
+ *
+ * 新建时以 [StreamingState] 的默认值为起点，所以「一路的第一帧」与老代码里
+ * `state.streaming ?: StreamingState()` 是同一条线。
+ */
+fun List<StreamingLeg>.withLeg(
+    bucket: TurnBucket,
+    block: (StreamingState) -> StreamingState,
+): List<StreamingLeg> {
+    val index = indexOfFirst { it.bucket == bucket }
+    if (index < 0) return this + StreamingLeg(bucket, block(StreamingState()))
+    return toMutableList().also { it[index] = it[index].copy(state = block(it[index].state)) }
+}
+
+/**
+ * 新一轮开始（`message.start` 且 `index == 0`）该对桶表做什么——**等价于老代码的
+ * `freshTurnIfFinished()` + 新解析器**那两步里的状态那一半：
+ *
+ * 1. **丢掉其它已经结束的路**：老代码在「上一轮已 `active = false`」时会把它整个清成新的
+ *    `StreamingState()`（内容已被 `message_persisted` 取代，留着就是重影）。按路分桶之后，
+ *    「已经结束」要按**路**判：[StreamingState.active] 为 `false` 的路丢掉，
+ *    **还在跑的另一路一个字节都不动**——那正是并行两路各自独立生长所要求的。
+ * 2. **这一路如果是「已结束」状态被重新用到**（同一 `turnId` 又开了新的正文段）⇒ 重置成空态，
+ *    与老代码同一条线；仍然 `active` 的路保持思维链 / 工具卡，只换正文（老代码也是如此）。
+ *
+ * 这一路还不在表里时**原样返回**：新的桶由紧接着的 [withLeg] 建（不在这里凭空塞一个空态进去，
+ * 那会让「收到过收口帧但没收到过任何正文帧」的坏时序多出一个看不见的空气泡）。
+ */
+fun List<StreamingLeg>.beginLeg(bucket: TurnBucket): List<StreamingLeg> {
+    val kept = filter { it.bucket == bucket || it.state.active }
+    if (kept.none { it.bucket == bucket }) return kept
+    return kept.map {
+        if (it.bucket == bucket && !it.state.active) it.copy(state = StreamingState()) else it
+    }
+}
+
+/**
+ * 收口一路（`stream_end` 之类）：把这一路标成「不再生长」。
+ *
+ * [bubbles] 是收口那一刻的正文段（解析器 `finish()` 的结果）；**`null` = 这一路手上没有解析器**
+ * （例如这一轮一帧正文都没到、或只到了工具帧），此时保留它已有的正文段，只收口那几个标志位——
+ * 「没有新正文」不该被写成「正文是空的」（那会把已经显示出来的字擦掉）。
+ *
+ * **这一路不在表里时什么都不做**（`this` 原样返回）——收口帧不许**新开**一路（见
+ * [top.yeij.cyrene.domain.chat.closingBucketOf]）。老代码在这里会顺手创建一个空的
+ * `StreamingState(active = false)`，那在界面上是一个不渲染任何东西、却会占一个列表项的幽灵；
+ * 不创建它，用户看得到的每一个像素都与今天相同。
+ */
+fun List<StreamingLeg>.finishingLeg(
+    bucket: TurnBucket,
+    bubbles: List<ParsedBubble>?,
+): List<StreamingLeg> {
+    val index = indexOfFirst { it.bucket == bucket }
+    if (index < 0) return this
+    return toMutableList().also {
+        val state = it[index].state
+        it[index] = it[index].copy(
+            state = state.copy(
+                bubbles = bubbles ?: state.bubbles,
+                thinkingActive = false,
+                active = false,
+            ),
+        )
+    }
+}
+
+/** 丢掉一路（它的助手回复已经落库，流式临时气泡该让位了）。 */
+fun List<StreamingLeg>.withoutLeg(bucket: TurnBucket): List<StreamingLeg> =
+    if (none { it.bucket == bucket }) this else filterNot { it.bucket == bucket }
+
+/**
+ * **连接重建时收口每一路**（纯函数，[top.yeij.cyrene.ui.chat.settledAfterReconnect] 用它）。
+ *
+ * 与 [finishingLeg] 的关系：同一件事（这一路不再生长、思维链与工具卡不再声称自己在跑），
+ * 区别只在**触发点**——[finishingLeg] 是「收到了这一路的 `stream_end`」，这里没有那一帧，
+ * 是「连接重建了，而服务端那一轮在旧连接上，永远不会再有后续帧」（判据见
+ * [top.yeij.cyrene.ui.chat.isReconnect]，理由见它那一份 KDoc）。
+ *
+ * 两条纪律：
+ * 1. **正文与思维链一个字都不删**——用户可能正读到一半，而这已经不是服务端能再给一次的东西；
+ * 2. **没有任何可显示内容的那一路整条丢掉**：`active = true` 而什么都不画时，[StreamingBubble]
+ *    会画一个只有光标的空气泡，收口它等于把它变成一个**一个像素都不画、却仍占一个列表项**
+ *    （也因此占着「最新一项」这个位置）的幽灵——那种路丢掉是本函数的**唯一**删除动作，
+ *    而它删的是「本来就没有的东西」。
+ *
+ * 无变化时返回**同一个实例**（与 [finishingLeg] / `withoutLeg` 同一条纪律）。
+ */
+fun List<StreamingLeg>.allFinished(): List<StreamingLeg> {
+    val next = mapNotNull { it.finishedLeg() }
+    return if (next == this) this else next
+}
+
+/**
+ * 这一路**收口后**的样子；收口之后**什么都画不出来**时返回 `null`（整路丢掉，见 [allFinished]）。
+ *
+ * 三件事与 [finishingLeg] 逐字同义：不再 `active`（光标停、兜底路径不再当它是新回合）、
+ * 思维链不再 `thinkingActive`（标题从「思考中…」变回「思维链」），外加工具卡也一起收口
+ * （[settledAfterReconnect]，标题从「执行 X…」变回「工具调用 · X」）。
+ *
+ * ⚠️ `bubbles` / `thinking` / 工具卡的参数与输出**一个都没动**：这是「不再声称在跑」，
+ * 不是「清空这一路」。
+ */
+private fun StreamingLeg.finishedLeg(): StreamingLeg? {
+    val settled = state.copy(
+        active = false,
+        thinkingActive = false,
+        tools = state.tools.settledAfterReconnect(),
+    )
+    val anythingToShow =
+        settled.bubbles.isNotEmpty() || settled.thinking.isNotBlank() || settled.tools.isNotEmpty()
+    return if (anythingToShow) copy(state = settled) else null
+}
+
+/**
+ * 这条**已落库**消息处在哪一态（六态判定，规范 §1.1）。
+ *
+ * 三个输入都取自状态本身：绑定的路（[ChatUiState.turns]）、有没有排队的回执
+ * （[ChatUiState.queuedKeys]，按服务端 `messageId` 或本地幂等键 `clientMsgId` 两种写法各查一次——
+ * 队列回执是**先**到还是 `message_persisted` **先**到并不确定）。
+ *
+ * `rejected` 恒 `false` 是刻意的、也是如实的：本端被拒（`pending_full` / 定向 `chat_busy`）的处置是
+ * **摘掉乐观气泡 + 横幅如实告知 + 正文还给输入栏**（既有定案，见 `rollbackPending`），
+ * 那条消息根本不在消息列表里，**没有一个气泡可以挂红标**。
+ * 六态判定保留 `Rejected` 档（规范 §1.1 ⑥）并由单测直接覆盖，只是本端的现实路径走的是回滚那一支。
+ */
+fun ChatUiState.phaseOf(message: HistoryMessageDto): TurnPhase = turnPhaseOf(
+    local = false,
+    binding = turns.bindingOfMessage(message.id),
+    queued = isQueuedMarked(message.id) || isQueuedMarked(message.clientMsgId),
+    rejected = false,
+)
+
+/**
+ * 这条**乐观气泡**处在哪一态（六态判定）。
+ *
+ * 乐观气泡还没有服务端 id，所以绑定的路**永远查不到**（`turn_begin` 的 `messageIds` 是服务端 id）
+ * ——它要么是 ① 发送中，要么是 ③ 排队中。这正是规范 §1.1 里 ① / ③ 的那两种视觉：
+ * 半透明「发送中…」与浅灰「排队中」。
+ *
+ * ## ③ 的两个来源（W40 起）
+ * 「排队」这件事在本端有**两个来源**，都算 ③，但**来源不同、要看得出区别**：
+ * 1. 收到过**服务端**的入队回执（[ChatUiState.queuedKeys]）——她忙，这条已受理、排在别人后面；
+ * 2. **本端**因为没连上把这条留住了（[ChatUiState.queuedForConnection]，主人 2026-10-05 裁决）——
+ *    这条**一个字节都还没上路**，连接恢复后会自动补发。
+ *
+ * 两者的差别由气泡小标在**文案上**说清（`pendingBubbleFooter`：③+等连接 = 「排队中 · 还没连上」），
+ * 而**不新增第七态**：六态模型（规范 §1.1）是 W30 定下的口径，`TurnPhase` 的每一个取值都在
+ * 界面与测试里有明确形状——为「另一种排队」再加一态，等于让所有按六态穷举的地方（渲染、测试、
+ * 并行规范）都跟着改一遍，而它回答的问题（「这条还没送到她手上」）与 ③ 本来就是同一个。
+ */
+fun ChatUiState.phaseOf(item: PendingMessage): TurnPhase = turnPhaseOf(
+    local = true,
+    binding = null,
+    // ③ 的两个来源（见上）：入队回执，或本端因未连接把它留住了。
+    queued = isQueuedMarked(item.localId) || isAwaitingConnection(item.localId),
+    rejected = false,
+)
+
+/**
+ * 这条消息在界面上该挂什么小标（规范 §1.4 A：**真的是并行路**且 `leg >= 2` 才挂「并行 N 路」）。
+ *
+ * 两个方向都要认，因为「同一路的两条消息」有两头：
+ * - **提问侧**（user 行）：靠 `turn_begin.messageIds` / `steer_ack` 建立的**绑定**；
+ * - **回复侧**（assistant 行）：靠历史行上那个**可选** `turnId`（规范 §2.7，v0.65 起才有）。
+ *
+ * 判据交给 [legBadgeOf]：它同时看这一路的 `parallel`（只看 `turn_begin.kind`）与 `leg`，
+ * 所以普通串行回合的 `leg = 2 / 3 / …` **挂不出标**——那是会话内第几条路，不是「并行路」。
+ *
+ * 老服务端上两条都查不到（没有 `turn_begin`，历史行的 `turnId` 整键省略）⇒ 恒 `null` ⇒
+ * 一个标都不挂，与今天逐字相同。
+ */
+fun ChatUiState.legBadgeForMessage(message: HistoryMessageDto): String? {
+    turns.bindingOfMessage(message.id)?.let { return legBadgeOf(it.leg, it.parallel) }
+    val producedBy = message.turnId?.takeIf { it.isNotBlank() } ?: return null
+    return turns.firstOrNull { it.turnId == producedBy }?.let { legBadgeOf(it.leg, it.parallel) }
+}
+
+/** 这一路的小标（按 `turnId` 查；`null` = 不是并行路 / 一路 / 序号未知，几种都不挂标）。 */
+fun ChatUiState.legBadgeForTurn(turnId: String): String? =
+    turns.firstOrNull { it.turnId == turnId }?.let { legBadgeOf(it.leg, it.parallel) }
+
+/**
+ * 从某一路跳到**它归属的那条提问**：返回聊天列表（`reverseLayout`）里的项下标；
+ * `null` = 定位不了（这条提问不在已加载的窗口里、或这一路没有绑到任何消息）。
+ *
+ * 下标算法与服务端搜索的定位**同一套**（[planSearchJump]）：`items` 的顺序是
+ * 「已落库消息 → 待发气泡 → 流式路」，所以「懒列表下标 = items.size - 1 - 升序下标」对已落库
+ * 消息恒成立。规范 §1.4 A 把「点小标跳到对应提问」列为推荐形态——它就是这条。
+ */
+fun ChatUiState.jumpIndexForTurn(turnId: String): Int? {
+    val binding = turns.firstOrNull { it.turnId == turnId } ?: return null
+    val index = messages.indexOfFirst { binding.messageIds.contains(it.id) }
+    if (index < 0) return null
+    return (items.size - 1 - index).coerceAtLeast(0)
+}
+
+private fun ChatUiState.isQueuedMarked(key: String?): Boolean =
+    !key.isNullOrBlank() && queuedKeys.contains(key)
@@ -0,0 +1,219 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failureOf
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.isLoadingFor
+import top.yeij.cyrene.domain.chat.voiceAudio
+import top.yeij.cyrene.domain.chat.voiceDurationLabel
+import top.yukonga.miuix.kmp.basic.Icon
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.icon.MiuixIcons
+import top.yukonga.miuix.kmp.icon.extended.Pause
+import top.yukonga.miuix.kmp.icon.extended.Play
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 语音形态里那枚「这是个语音」的字样。它说的是**媒体类型**（判据 = 这条画的是语音形态，
+ * 见 `isVoiceMessage`），不是内容。
+ */
+const val VOICE_LABEL: String = "语音"
+
+/** 加载中那一句（与 [VOICE_LABEL] 同一行，替换掉时长那一格）。 */
+private const val VOICE_LOADING_LABEL = "加载中…"
+
+/** 播放控件那枚图标的读屏名字 —— 同时也是设备验收时 `uiautomator` 拿来定位它的 `content-desc`。 */
+const val VOICE_PLAY_DESCRIPTION: String = "播放语音"
+
+/** 正在放 / 加载中时那枚图标的读屏名字（点它 = 停）。 */
+const val VOICE_STOP_DESCRIPTION: String = "停止播放语音"
+
+/** 图标尺寸：与消息角标那枚「⋯」同一档，整条语音形态因此不比一条角标高多少。 */
+private val VOICE_ICON_SIZE = 18.dp
+
+/**
+ * 一条语音消息在**转写文本之外**的那个「语音」形态：`[播放/暂停] 语音 · 时长`。
+ *
+ * ## 画什么由三条契约判据决定（都在这一个函数里，不散落）
+ * - **🎤 判据 = `voice` 键存在 **且** `status != "failed"`**：本组件只有在这条消息要画语音形态时
+ *   才会被调用（调用点在 [MessageBubble]，判据是 `isVoiceMessage`），所以这里既不认识正文里有
+ *   没有 `[语音]` 字样、也不认识 `status`——`failed` 那一态（没有可播的声音）根本不走这条路，
+ *   它由 `VoiceFallbackNote` 单独画一行灰色小标；
+ * - **无副本 ⇒ 不画播放控件**（[voiceAudio] 回 `null`）：四个键（`name`/`mime`/`size`/`url`）
+ *   没凑齐时只留「语音」这一格 —— 不能给一个点下去必然失败的按钮。时长若服务端给了照样显示
+ *   （时长与副本**无关**）；
+ * - **缺席就不显示时长**（[voiceDurationLabel] 回 `null`）：绝不显示 `0:00` 冒充，也不拿
+ *   `size` 反算。
+ *
+ * ## 三处文案各自归谁
+ * - **正文**（转写 / 服务端的诚实提示）由 [MessageBubble] 照常渲染，本组件一个字符都不改、
+ *   也不隐藏它；
+ * - [note]（`status = empty` 且正文为空时那句「没有识别出文字」）由调用方用纯函数
+ *   `voiceNote` 算好传进来 —— 本组件不判 `status`；
+ * - [playback] 里这条消息的失败提示（[failureOf]）**只在失败时出现一行**，颜色用
+ *   `colorScheme.error`：可见但不夸张（不弹窗、不占整行、不挡住正文）。
+ *
+ * ## 图标从哪来（查过 AAR，不是猜的）
+ * `miuix-icons-android:0.9.3` 的 **basic** 包只有 7 枚（`Close` / `Search` / `SearchCleanup` /
+ * `Sidebar` / `Check` / `ArrowRight` / `ArrowUpDown`），**没有播放 / 暂停字形**；但 **extended**
+ * 包里有真的 `Play` / `Pause`（`javap` 确认过 `PlayKt.getPlay(MiuixIcons)`），而本模块本来就在用
+ * extended（`MessageBubble.kt` 的 `MiuixIcons.More`）。所以这里用真的字形，**不**自绘几何图形：
+ * 自绘一个三角形在扫读上并不比官方图标便宜，还要自己承担「像不像播放键」的风险。
+ * 官方文档写 `MiuixIcons.Xxx` 的用法对人不对包，以 AAR 为准 —— 这两枚就是 extended 包里的。
+ *
+ * ## 点哪儿
+ * **整枚可点**（不只是那 18dp 的图标）：读屏与手指都不必瞄准；图标只是「这里能按」的可见凭据
+ * （与 [LegBadge] 「看得出可点」同一条思路）。
+ *
+ * @param note 正文之外要多说的一句（没有就传 `null`）。
+ * @param playback 这条通道的当前状态（由调用方用 [rememberVoicePlayer] 那一个实例驱动）。
+ * @param onToggle 用户点了这枚语音：交给上层真正去取字节 / 放 / 停（本组件不发请求）。
+ */
+@Composable
+fun VoiceMessageRow(
+    voice: VoiceDto,
+    messageId: String,
+    playback: VoicePlaybackState,
+    note: String? = null,
+    alignEnd: Boolean = false,
+    onToggle: () -> Unit = {},
+    modifier: Modifier = Modifier,
+) {
+    val audio = voiceAudio(voice)
+    val active = playback.isActiveFor(messageId)
+    val loading = playback.isLoadingFor(messageId)
+    val failure = playback.failureOf(messageId)
+    val duration = voiceDurationLabel(voice.durationMs)
+
+    Column(
+        modifier = modifier,
+        horizontalAlignment = if (alignEnd) Alignment.End else Alignment.Start,
+        verticalArrangement = Arrangement.spacedBy(2.dp),
+    ) {
+        Row(
+            modifier = Modifier
+                .clip(RoundedCornerShape(12.dp))
+                .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+                .then(
+                    if (audio == null) {
+                        Modifier
+                    } else {
+                        Modifier
+                            .clickable(onClick = onToggle)
+                            // 可点的那一层（整枚）自己报「点它会发生什么」；里面的图标因此只是
+                            // 一笔装饰（`contentDescription = null`），读屏不会读到第二个焦点。
+                            .semantics {
+                                contentDescription = if (active) VOICE_STOP_DESCRIPTION else VOICE_PLAY_DESCRIPTION
+                            }
+                    },
+                )
+                .padding(start = 8.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            if (audio != null) {
+                Icon(
+                    imageVector = if (active) MiuixIcons.Pause else MiuixIcons.Play,
+                    contentDescription = null,
+                    tint = MiuixTheme.colorScheme.primary,
+                    modifier = Modifier
+                        .size(VOICE_ICON_SIZE)
+                        .clip(CircleShape),
+                )
+            }
+            Text(
+                text = VOICE_LABEL,
+                style = MiuixTheme.textStyles.footnote1,
+                color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            )
+            when {
+                // 「现在在干什么」与「点它会怎样」分开说：图标回答后者，这一格回答前者。
+                // ⚠️ 只有**真的在取字节**时才说「加载中…」：`active` 还包含「正在响」，
+                // 拿它当条件会让一条 30 秒的语音整段播放期间都写着「加载中…」。
+                loading -> Text(
+                    text = VOICE_LOADING_LABEL,
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+
+                duration != null -> Text(
+                    text = duration,
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+            }
+        }
+        note?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+            )
+        }
+        failure?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+            )
+        }
+    }
+}
+
+/**
+ * `status == "failed"` 那条消息**没有语音形态**，但要多说的一句话（`voice` 键在、没有可播的声音）。
+ *
+ * ## 为什么这一行必须存在
+ * 这一态的消息正文照常按文字渲染（入站是服务端那行诚实提示，出站是合成降级后的原文本）。少了这一行，
+ * 一条「她本想用语音、合成降级成文字」的消息与一条普通文字消息**逐像素相同**——看的人无从知道这条
+ * 本来是一段声音，也看不出它与别的话有什么不一样。所以这枚小标不是装饰，它是这一态**唯一**的可见
+ * 凭据（[VoiceMessageRow] 在这里根本不画，见 `isVoiceMessage`）。
+ *
+ * ## 样式为什么抄 [VoiceMessageRow] 里 note 那一行
+ * `footnote2` + `onSurfaceVariantSummary`：与语音形态旁边那几句说明（「没有识别出文字」/ 加载中 /
+ * 时长）**同一档**。这三处说的都是「关于这段声音的一句脚注」，同一个外观才让人读成一类东西；
+ * 换成正文那一档字级会被误读成消息内容的一部分，换成 `error` 又会把一次**降级**说成一次**失败**
+ * ——降级本身是服务端做对的一件事（她的话一个字没丢，只是没变成声音）。
+ *
+ * ## 不判 `status`，也不拼文案
+ * [text] 由调用方用纯函数 `voiceFallbackNote` 算好传进来（固定前半句 + 服务端 `fallbackReason` 原样）。
+ * 本组件只负责画：判据与措辞都在 domain 层单测钉着，这里再判一次就多出「两处判据不一致」的可能
+ * ——与 [VoiceMessageRow] 对 `note` 的处理同一条纪律。
+ *
+ * @param text 已经算好的那一整句（本组件不改一个字符）。
+ * @param alignEnd 用户侧（气泡在右）：整行贴右；否则贴左。
+ */
+@Composable
+fun VoiceFallbackNote(
+    text: String,
+    alignEnd: Boolean = false,
+    modifier: Modifier = Modifier,
+) {
+    Column(
+        modifier = modifier,
+        horizontalAlignment = if (alignEnd) Alignment.End else Alignment.Start,
+    ) {
+        Text(
+            text = text,
+            style = MiuixTheme.textStyles.footnote2,
+            color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+        )
+    }
+}
@@ -0,0 +1,349 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+import top.yeij.cyrene.domain.chat.VoiceDraftInfo
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failureOf
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.isLoadingFor
+import top.yeij.cyrene.domain.chat.voiceElapsedLabel
+import top.yeij.cyrene.domain.chat.voiceReplyNote
+import top.yukonga.miuix.kmp.basic.Button
+import top.yukonga.miuix.kmp.basic.Icon
+import top.yukonga.miuix.kmp.basic.IconButton
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.icon.MiuixIcons
+import top.yukonga.miuix.kmp.icon.basic.Close
+import top.yukonga.miuix.kmp.icon.extended.Mic
+import top.yukonga.miuix.kmp.icon.extended.Pause
+import top.yukonga.miuix.kmp.icon.extended.Play
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 输入栏那几个**语音**形态（录音中 / 待重发 / 她的语音回复），以及乐观气泡里那一枚「语音」。
+ *
+ * ## 为什么单独一个文件
+ * 它们四个共用同一套尺寸与配色，而这个文件之外没人需要知道这些细节：`ChatScreen` 只负责接线，
+ * `MessageBubble` 只调用最后一枚。放在一起，改一眼就能看全。
+ *
+ * ## 图标从哪来（查过 AAR，不是猜的）
+ * `miuix-icons-android:0.9.3` 的 **basic** 包只有 7 枚，**没有麦克风**；**extended** 包里有真的
+ * `Mic` / `MicSlash`（`javap` 确认过 `MicKt.getMic(MiuixIcons)`），而本模块本来就在用 extended
+ * （`VoiceBubble.kt` 的 `Play` / `Pause`、`ChatScreen.kt` 的 `File` / `Image`）。
+ *
+ * ## 读屏名字即设备验收的 `content-desc`
+ * 四枚可点控件的 `contentDescription` 都抽成了常量（[VOICE_RECORD_DESCRIPTION] 等）：
+ * `uiautomator dump` 靠它们定位，改文案等于改验收口径，两处一起改。
+ */
+
+/** 「开始录音」那枚麦克风的读屏名字。 */
+const val VOICE_RECORD_DESCRIPTION: String = "按住说话（点按开始录音）"
+
+/** 录音中那枚麦克风（点它 = 结束并发送）。 */
+const val VOICE_RECORD_STOP_DESCRIPTION: String = "结束录音并发送"
+
+/** 录音中的「取消」。 */
+const val VOICE_RECORD_CANCEL_DESCRIPTION: String = "取消这段录音"
+
+/** 待重发那一段的「重发」。 */
+const val VOICE_DRAFT_RETRY_DESCRIPTION: String = "重发这段语音"
+
+/** 待重发那一段的「丢弃」。 */
+const val VOICE_DRAFT_DISCARD_DESCRIPTION: String = "丢弃这段语音"
+
+/** 她的语音回复的播放 / 停止。 */
+const val VOICE_REPLY_PLAY_DESCRIPTION: String = "播放她的语音回复"
+const val VOICE_REPLY_STOP_DESCRIPTION: String = "停止播放她的语音回复"
+
+/** 关掉她的语音回复那一张卡片。 */
+const val VOICE_REPLY_DISMISS_DESCRIPTION: String = "关闭这条语音回复"
+
+/** 乐观气泡里那枚「语音」的字样（与接收侧的 [VOICE_LABEL] 同一个词，不另造）。 */
+const val VOICE_CLIP_LABEL: String = VOICE_LABEL
+
+/**
+ * 麦克风**没授权**时的如实告知。
+ *
+ * 说「到系统设置里允许」而不是再申请一次：本端只在第一次点麦克风时申请（平台规范），
+ * 被拒之后重复申请只会被系统静默挡回（Android 不再弹框），那样用户点十次都毫无反应。
+ */
+const val VOICE_PERMISSION_DENIED_MESSAGE: String =
+    "没有麦克风权限，到系统设置里允许后再试"
+
+/**
+ * 有权限、但麦克风**现在起不来**（被别的应用占用 / 设备不支持这组采样参数）。
+ *
+ * 与 [VOICE_PERMISSION_DENIED_MESSAGE] 分开：那一档用户要去设置页，这一档要等一会或换个应用；
+ * 说成同一句就是把人引向一个解决不了问题的动作。
+ */
+const val VOICE_UNAVAILABLE_MESSAGE: String = "麦克风现在打不开，可能被别的应用占着"
+
+/** 图标尺寸：与接收侧语音形态同一档。 */
+private val VOICE_ICON_SIZE = 18.dp
+
+/** 卡片底色与圆角：与 `VoiceMessageRow` 那一枚同形（同一个产品里的语音长一个样）。 */
+private val VOICE_CARD_SHAPE = RoundedCornerShape(12.dp)
+
+/**
+ * 录音中那一行：`🎤 录音中 · 0:07 [取消] [发送]`。
+ *
+ * 时长由**已收到的字节数**反算（见 `VoiceRecorder`），所以屏幕上这个数字与发出去的音频长度
+ * 严格一致。到 60 秒时 `VoiceRecorder` 会置「满了」标记、由调用方直接收尾——这里不做倒计时：
+ * 一个还在数的计时器在「已经满了」那一刻是假话。
+ *
+ * 两枚按钮分开（不是「点头像就发」那种手势）：录音是一条**有去无回**的动作（这段 bytes 一旦
+ * 发出就落进服务端编排），取消必须和发送一样容易按到。
+ */
+@Composable
+fun VoiceRecordingRow(
+    elapsedMs: Int,
+    onCancel: () -> Unit,
+    onSend: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.error,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "录音中 · ${voiceElapsedLabel(elapsedMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            modifier = Modifier.weight(1f),
+        )
+        IconButton(
+            onClick = onCancel,
+            modifier = Modifier.semantics { contentDescription = VOICE_RECORD_CANCEL_DESCRIPTION },
+        ) {
+            Icon(imageVector = MiuixIcons.Basic.Close, contentDescription = null)
+        }
+        Button(onClick = onSend) { Text("发送") }
+    }
+}
+
+/**
+ * 一段**录好但没发出去**的语音：`🎤 语音 · 0:07 [重发] [丢弃]`。
+ *
+ * 它只在一件事之后出现：`voice_input` 没能上行（连接没就绪 / 写帧失败）。此时那段字节**只在
+ * 内存里**，界面上必须给两条出路——重发（**复用同一个 `clientMsgId`**，服务端据此判重）或丢弃。
+ * 不给「退回到输入栏」那种出路：语音没有可以退回到输入框的形态。
+ */
+@Composable
+fun VoiceDraftRow(
+    draft: VoiceDraftInfo,
+    onRetry: () -> Unit,
+    onDiscard: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.primary,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "$VOICE_CLIP_LABEL · ${voiceElapsedLabel(draft.durationMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            modifier = Modifier.weight(1f),
+        )
+        TextButton(
+            text = "重发",
+            onClick = onRetry,
+            modifier = Modifier.semantics { contentDescription = VOICE_DRAFT_RETRY_DESCRIPTION },
+        )
+        TextButton(
+            text = "丢弃",
+            onClick = onDiscard,
+            modifier = Modifier.semantics { contentDescription = VOICE_DRAFT_DISCARD_DESCRIPTION },
+        )
+    }
+}
+
+/**
+ * 她的语音回复：`[▶] 她的语音回复 · 0:03 [×]` + 她说的话（[VoiceReply.reply]）。
+ *
+ * ## 只有文字那一档
+ * `provider == "silent"`（或这一轮根本没有 audio）时**不画播放控件**，只画文字 + 一句
+ * [voiceSilentNote]（「这一轮她只回了文字，没有语音」）。契约的硬要求是「UI 别把它画成播放器」；
+ * 补那句解释是为了让「她选择只用文字」与「播放器坏了」在屏幕上分得开。
+ *
+ * ## 可播放但播不了
+ * 音频在、本机解码 / 落盘失败时**照样画**播放控件：点了会走到 [failureOf] 那一行如实说
+ * 「播不了」——这比一个看起来什么都没有的控件诚实。
+ */
+@Composable
+fun VoiceReplyRow(
+    reply: VoiceReply,
+    playback: VoicePlaybackState,
+    onTogglePlay: () -> Unit,
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    val active = playback.isActiveFor(reply.id)
+    val loading = playback.isLoadingFor(reply.id)
+    val failure = playback.failureOf(reply.id)
+    val text = reply.reply
+
+    Column(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 4.dp, top = 6.dp, bottom = 6.dp),
+        verticalArrangement = Arrangement.spacedBy(2.dp),
+    ) {
+        Row(
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            if (reply.playable) {
+                // 整枚可点（不只是 18dp 的图标），读屏名字说清「点它会怎样」。
+                Row(
+                    modifier = Modifier
+                        .clip(CircleShape)
+                        .clickable(onClick = onTogglePlay)
+                        .semantics {
+                            contentDescription = if (active) {
+                                VOICE_REPLY_STOP_DESCRIPTION
+                            } else {
+                                VOICE_REPLY_PLAY_DESCRIPTION
+                            }
+                        }
+                        .padding(2.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(6.dp),
+                ) {
+                    Icon(
+                        imageVector = if (active) MiuixIcons.Pause else MiuixIcons.Play,
+                        contentDescription = null,
+                        tint = MiuixTheme.colorScheme.primary,
+                        modifier = Modifier.size(VOICE_ICON_SIZE),
+                    )
+                    Text(
+                        text = "她的语音回复",
+                        style = MiuixTheme.textStyles.footnote1,
+                        color = MiuixTheme.colorScheme.primary,
+                    )
+                }
+            } else {
+                Text(
+                    text = "她的语音回复",
+                    style = MiuixTheme.textStyles.footnote1,
+                    color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+                )
+            }
+            // 「现在在干什么」与「点它会怎样」分开说（与接收侧语音形态同一条纪律）：
+            // 只有真的在取字节时才说「准备中…」，正在响时不冒充加载。
+            if (loading) {
+                Text(
+                    text = "准备中…",
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+            }
+            Row(
+                modifier = Modifier.weight(1f),
+                horizontalArrangement = Arrangement.End,
+            ) {
+                IconButton(
+                    onClick = onDismiss,
+                    modifier = Modifier.semantics { contentDescription = VOICE_REPLY_DISMISS_DESCRIPTION },
+                ) {
+                    Icon(imageVector = MiuixIcons.Basic.Close, contentDescription = null)
+                }
+            }
+        }
+        text?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote1,
+                color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+                modifier = Modifier.padding(start = 2.dp, end = 8.dp),
+            )
+        }
+        // 「只有文字」与「本机没准备好」是两件事，各说各的那句（判据是纯函数）。
+        voiceReplyNote(silent = reply.silent, hasAudioFile = reply.file != null)?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+            )
+        }
+        failure?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+            )
+        }
+    }
+}
+
+/**
+ * 乐观气泡里那一枚「语音」：`🎤 语音 · 0:07`。
+ *
+ * 用户按住说话之后，气泡**立刻**出现（与文本消息的乐观路径同一个 `pending` 列表、同一个回滚），
+ * 只是正文还没到——转写要等服务端。所以这里只画媒体类型与时长，**不画播放控件**：
+ * 本地已经发出去的那段音频不在播放通道里（它已经在服务端了，回放应当走历史消息那条路）。
+ */
+@Composable
+fun VoiceClipLabel(durationMs: Int, modifier: Modifier = Modifier) {
+    Row(
+        modifier = modifier
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 8.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(6.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.primary,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "$VOICE_CLIP_LABEL · ${voiceElapsedLabel(durationMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+        )
+    }
+}
@@ -0,0 +1,230 @@
+package top.yeij.cyrene.ui.chat
+
+import android.media.AudioAttributes
+import android.media.MediaPlayer
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.rememberUpdatedState
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.chat.VOICE_UNPLAYABLE_MESSAGE
+import top.yeij.cyrene.domain.chat.VoiceAudio
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failed
+import top.yeij.cyrene.domain.chat.finished
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.prepared
+import top.yeij.cyrene.domain.chat.pressed
+import top.yeij.cyrene.domain.chat.silenced
+import top.yeij.cyrene.domain.chat.voiceAudio
+import top.yeij.cyrene.domain.chat.voicePlaybackFailureMessage
+import java.io.File
+
+/**
+ * 「同一时刻只有一条语音在响」的那条**播放通道**（接收侧：播放别人发来的语音）。
+ *
+ * ## 用什么放（不引任何新依赖）
+ * 系统 **`android.media.MediaPlayer`**（平台 API，API 1 起就有）。选它而不是 ExoPlayer / Media3：
+ * 项目纪律是加依赖要先问，而这里要的只是「放一段 ogg / wav / mp3 的本地文件」，平台的解码器够用。
+ * 音源是**本地文件**（[load] 的产物）：字节由 `VoiceStore` 取一次、落在 `cacheDir/media/`，
+ * 于是播放本身不联网、不随时间抖动，也**不必**把 Bearer 头塞进播放器（`MediaPlayer` 的头部参数
+ * 不会走 401 续期那条路，那才是真的会出事的地方）。
+ *
+ * ## 生命周期：三处必须停下来并释放（`MediaPlayer` 不 `release()` 会一直占着解码器与音频通路）
+ * 1. **开始播另一条**：[toggle] 在任何新播放之前先 [stop]（旧的那条停下并释放，含正在下载的
+ *    那一次）——所以「一条没放完又点另一条」不会出现两条叠着响；
+ * 2. **离开会话 / 换会话**：调用方用 [rememberVoicePlayer]（它按 `sessionKey` 换实例并在
+ *    `onDispose` 里 [release]），换会话 = 换实例 = 旧的那条立刻停；
+ * 3. **组件销毁**：同上，`onDispose` 是组合被丢弃时唯一可靠的时刻（[release] 幂等，可重复调）。
+ *
+ * ⚠️ **本片没做的两件事（如实）**：
+ * - **不申请音频焦点**（`AudioManager` 那套）：需要 `Context` 与「焦点被抢走」的处理，属于
+ *   「播放器该有的完整行为」，与本期「收得到、放得出来」不是一档。后果是主人自己在放音乐时
+ *   语音会叠在上面；
+ * - **App 退到后台不停播**（要接 `LocalLifecycleOwner` 需要 `lifecycle-runtime-compose`，
+ *   本期不加依赖）。语音都很短，影响面是「切走那一两秒还在响」。
+ *
+ * ## 失败：可见、但不夸张
+ * 两档失败都会进 [VoicePlaybackState.Failed]（气泡据此把按钮变回「未播」并显示**一行**短提示）：
+ * 取字节失败（网络 / 404 / 地址拼不出来，文案来自 [voicePlaybackFailureMessage]）与解码起播失败
+ * （[VOICE_UNPLAYABLE_MESSAGE]）。**绝不静默**——一条点了没反应的语音在用户眼里就是坏的。
+ *
+ * ## 不缓存字节（这一层）
+ * 缓存是 [VoiceStore] 的事（按存储名落 `cacheDir/media/`，命中就不发请求）。本类只负责「拿到
+ * 文件 → 放 → 放完/停 → 释放」，因此它不认识网络，也不认识缓存策略。
+ *
+ * @param scope 驱动的协程作用域（调用方给，通常是组合的 `rememberCoroutineScope`）。
+ * @param load 取这条语音的**本地文件**（未命中缓存时内部会下载并落盘）。
+ */
+class VoicePlayer(
+    private val scope: CoroutineScope,
+    private val load: suspend (VoiceAudio) -> Result<File>,
+) {
+
+    private val _state = MutableStateFlow<VoicePlaybackState>(VoicePlaybackState.Idle)
+
+    /** 这条通道此刻的状态（气泡与按钮都看它）。状态机本身是纯函数，见 `domain.chat.VoicePlayback`。 */
+    val state: StateFlow<VoicePlaybackState> = _state.asStateFlow()
+
+    /** 正在取字节的那次协程；停下 / 换目标时一并取消（用户不该被一个慢下载困住）。 */
+    private var loading: Job? = null
+    /** 当前这一台 `MediaPlayer`（null = 没有）。回调里的身份比对都以它为准。 */
+    private var player: MediaPlayer? = null
+
+    /**
+     * 用户点了这条消息的播放 / 暂停。
+     *
+     * 判据全部走纯函数：拿不到 [VoiceAudio]（**无副本** ⇒ 四个键没凑齐）就**什么都不做**
+     * ——正常路径上那时气泡根本不画播放控件，这里是第二道闸（同一个判据，不在 UI 之外再猜一次）。
+     */
+    fun toggle(message: HistoryMessageDto) {
+        val audio = voiceAudio(message.voice) ?: return
+        val id = message.id
+        // 再点一下 = 停（加载中也算：那表示「别下了」）。
+        if (_state.value.isActiveFor(id)) {
+            stop()
+            return
+        }
+        stop()
+        _state.value = _state.value.pressed(id)
+        loading = scope.launch {
+            load(audio).fold(
+                onSuccess = { file ->
+                    // 这一帧还该不该放：用户可能已经点了停 / 点了别的（状态已不是 Loading(id)）。
+                    if (_state.value.isActiveFor(id)) play(id, file)
+                },
+                onFailure = { error ->
+                    _state.value = _state.value.failed(id, voicePlaybackFailureMessage(error))
+                },
+            )
+        }
+    }
+
+    /**
+     * 放一段**已经在手上**的音频（`voice_output` 那条路：base64 就在帧里，不需要下载）。
+     *
+     * 与 [toggle] 走**同一条通道**、同一套身份比对与释放纪律（同一台喇叭上永远只有一条语音在响），
+     * 差别只有两个：音频不是「按消息取字节」而是由调用方现给（[load]），而且键是
+     * `voice_output` 那一帧自己铸的 [clipId]（它不是历史消息，没有 `messageId` 可用）。
+     *
+     * 同样遵守「再点一下 = 停」：`clipId` 正在放 / 正在载入时，这一下是**停**。
+     *
+     * @param load 取这份本地文件（写缓存 / 解码都在里面，调用方应切到 IO）。
+     */
+    fun toggleClip(clipId: String, load: suspend () -> Result<File>) {
+        if (_state.value.isActiveFor(clipId)) {
+            stop()
+            return
+        }
+        stop()
+        _state.value = _state.value.pressed(clipId)
+        loading = scope.launch {
+            load().fold(
+                onSuccess = { file ->
+                    if (_state.value.isActiveFor(clipId)) play(clipId, file)
+                },
+                onFailure = { error ->
+                    _state.value = _state.value.failed(clipId, voicePlaybackFailureMessage(error))
+                },
+            )
+        }
+    }
+
+    /** 停下来并释放（幂等）：取消取字节、拆掉播放器、状态回 [VoicePlaybackState.Idle]。 */
+    fun stop() {
+        loading?.cancel()
+        loading = null
+        releasePlayer()
+        // ⚠️ `silenced` 而不是「只清 Playing」：失败那句话也要跟着走——换了目标 / 离开页面之后，
+        // 屏幕上不该还挂着上一条的失败。
+        _state.value = _state.value.silenced
+    }
+
+    /** 组件销毁 / 离开会话时调（等价于 [stop]，单列一个名字是为了让调用点的意图看得见）。 */
+    fun release() = stop()
+
+    private fun play(messageId: String, file: File) {
+        val mp = MediaPlayer()
+        player = mp
+        mp.setAudioAttributes(
+            AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                .build(),
+        )
+        mp.setOnPreparedListener { prepared ->
+            // 身份比对：已经换掉 / 已经 release 的那个实例，回调一律不改状态。
+            if (player !== prepared) return@setOnPreparedListener
+            prepared.start()
+            _state.value = _state.value.prepared(messageId)
+        }
+        mp.setOnCompletionListener { done ->
+            if (player !== done) return@setOnCompletionListener
+            releasePlayer()
+            _state.value = _state.value.finished(messageId)
+        }
+        mp.setOnErrorListener { broken, _, _ ->
+            if (player !== broken) return@setOnErrorListener true
+            releasePlayer()
+            _state.value = _state.value.failed(messageId, VOICE_UNPLAYABLE_MESSAGE)
+            // true = 这次错误已经处理（不让它再走 onCompletion，也不弹系统默认处理）。
+            true
+        }
+        try {
+            mp.setDataSource(file.absolutePath)
+            // prepareAsync 而不是 prepare：同步那一版会占着主线程等解码器，异步的失败同样会走到
+            // onError（format 不支持 / 文件损坏 / 已被清空都是这一档）。
+            mp.prepareAsync()
+        } catch (_: Exception) {
+            // setDataSource / prepareAsync 在状态不对、文件读不动时**同步抛**：如实报「播不了」。
+            releasePlayer()
+            _state.value = _state.value.failed(messageId, VOICE_UNPLAYABLE_MESSAGE)
+        }
+    }
+
+    /**
+     * 把当前那台播放器拆干净：先摘掉全部监听（免得 `stop()` / `release()` 触发的回调再改状态），
+     * 再 `stop()`（未 prepare 完时它会抛 `IllegalStateException`，所以包在 `runCatching` 里），
+     * 最后 `release()`。
+     */
+    private fun releasePlayer() {
+        val current = player ?: return
+        player = null
+        current.setOnPreparedListener(null)
+        current.setOnCompletionListener(null)
+        current.setOnErrorListener(null)
+        runCatching { current.stop() }
+        runCatching { current.release() }
+    }
+}
+
+/**
+ * 为**当前这段组合**（通常是一个会话的聊天页）记住一条播放通道，并在它被丢弃时释放。
+ *
+ * 两条纪律写在这里，因为它们是本类唯一的使用方式：
+ * - **[sessionKey] 变了就换一条通道**：换会话 = 换通道 = 上一条立刻停（`remember` 换实例 →
+ *   `DisposableEffect` 的旧 effect 走 `onDispose` → [VoicePlayer.release]）；
+ * - **[load] 变化不重建通道**：它由 `rememberUpdatedState` 顶着（每次重组拿到最新那个 lambda），
+ *   否则重组期间的一次实例更替会把正在放的那条停掉。
+ */
+@Composable
+fun rememberVoicePlayer(
+    sessionKey: Any?,
+    load: suspend (VoiceAudio) -> Result<File>,
+): VoicePlayer {
+    val scope = rememberCoroutineScope()
+    val currentLoad by rememberUpdatedState(load)
+    val player = remember(sessionKey) { VoicePlayer(scope) { audio -> currentLoad(audio) } }
+    DisposableEffect(player) {
+        onDispose { player.release() }
+    }
+    return player
+}
@@ -0,0 +1,49 @@
+package top.yeij.cyrene.ui.chat
+
+import java.io.File
+
+/**
+ * `voice_output` 在界面上的那一份「她的语音回复」（只管**这一条实时应答**，不进历史）。
+ *
+ * ## 为什么它不在消息列表里
+ * 契约 v0.96 §3.15：这一帧**只定向回发起 `voice_input` 的那条连接**、**连接断了不补投**，
+ * 而且回合的正文本来就会经流式 / `message_persisted` 落进消息列表。所以它不是一条消息，
+ * 是「这一次语音回合的音频 + 她说的话」这一次性产物：放在输入栏上方一条卡片里，
+ * 用户随时可以关掉（[ChatViewModel.dismissVoiceReply]），它不参与排序、不占历史。
+ *
+ * ## [hasAudio] 与 [file] 是两件事
+ * - [hasAudio]：**服务端**这一轮给了真音频（`provider != "silent"` 且 `audio` 非空白）。
+ *   为假 ⇒ 界面上**一个播放控件都不画**（画了就是点下去必然失败的按钮）。
+ * - [file]：音频在本机的那份文件。`hasAudio` 为真而它是 `null` = 本机解码 / 落盘失败
+ *   ——这一档**照样画**播放控件（点了会如实报「播不了」），**绝不**把本机的故障说成
+ *   「她这一轮只回了文字」（见 `domain.chat.voiceReplyNote`）。
+ *
+ * @property id 播放通道的键：每条 `voice_output` 现铸一个（它不是历史消息，没有 `messageId`）。
+ * @property reply 她说的那一句（音频念的就是它），见 `domain.chat.voiceReplyText`。
+ * @property transcript 转写（载荷里的 `text`）：那段音频被识别成什么；只作兜底与诊断。
+ * @property format 服务端给的音频格式；本端**不照抄它去解码**（`MediaPlayer` 按文件头嗅探）。
+ */
+data class VoiceReply(
+    val id: String,
+    val reply: String?,
+    val transcript: String?,
+    val format: String?,
+    val provider: String?,
+    val hasAudio: Boolean,
+    val file: File?,
+    /**
+     * 这一条还该不该**自动播放**（默认 true，播过就置假，见 [ChatViewModel.consumeVoiceReplyAutoPlay]）。
+     *
+     * 为什么要这一位：这一帧**只在到达时**有意义（断线不补投），而到达的那一刻用户可能正在别的
+     * 会话 / 别的页面里。若只按「音频落好了就放」来触发，等他切回来时会**突然响一段旧语音**
+     * ——那不是他刚做的事。所以自动播放只认**第一次**落好的那一下，之后靠卡片上的播放键。
+     */
+    val autoPlay: Boolean = true,
+) {
+
+    /** 能不能画「播放」那枚控件：这一轮**有**音频，而且它已经落到本机。 */
+    val playable: Boolean get() = hasAudio && file != null
+
+    /** 这一轮是不是「没有音频」（= `provider == "silent"` 或 `audio` 缺席）。 */
+    val silent: Boolean get() = !hasAudio
+}
@@ -0,0 +1,103 @@
+package top.yeij.cyrene.ui.chat
+
+import java.io.File
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.ttsClipIdOf
+
+/**
+ * 「把这一条念出来」在**本端**的那一份状态（W75，`POST /api/v1/audio/speech`）。
+ *
+ * ## 为什么它住在 VM 的状态里，而不是气泡自己的 `remember`
+ * 一次朗读要经过一段**跨组合重建**的等待（发请求、等字节、落盘）：转屏 / 滚出屏幕再滚回来
+ * 都不该让已经落好的那段音频消失，也不该让「正在准备」这件事凭空重置。所以请求发起、失败分类、
+ * 落盘结果都在 `ChatViewModel.speak` 里，气泡只是这份状态的视图。
+ *
+ * ## 一次只有一个：`ttsClip` 是**单格**
+ * 与 [VoiceReply] 同一取舍：同一时刻用户点的是**一条**消息，多留几条既占内存又没人看。
+ * 用户点了另一条 ⇒ 这一格被新的那条整个替换（旧那条的音频文件留在缓存里，下次点它命中不发请求）。
+ *
+ * ## 播放不在这一格里
+ * 「正在响 / 已经停了」由**唯一的播放通道**（`ui.chat.VoicePlayer` 的 `state`）说，键是
+ * [clipId]（`tts:<messageId>`，见 `domain.chat.ttsClipIdOf`）。这一格只负责「字节有没有到手、
+ * 上一次为什么没到手」。分成两处是必须的：播放器在响的时候这一格可以纹丝不动（它不需要知道
+ * `MediaPlayer` 走到了哪），而用户点了另一条语音副本时，播放通道换键、这一格照旧留着 —— 两件事
+ * 本来就不是一件事。
+ *
+ * @property messageId 这条朗读属于哪条消息（失败文案据此只挂在那一条下面）。
+ * @property clipId 播放通道上的键（`tts:<messageId>`）：与语音副本的键（= 它的 `messageId`）
+ *   分得开，于是「念这一条」与「放这条消息的语音副本」天然互斥（点一个停另一个）。
+ * @property file 合成音频在本机的那份 WAV；`null` = 还没到手（请求在飞，或已经失败了）。
+ * @property failure 上一次没成功时给用户看的那句话（`domain.chat.TtsFailure.message`）；
+ *   `null` = 没失败过 / 还没结果。
+ * @property retryable 再点一次**可能**有用吗（`domain.chat.TtsFailure.retryable`）。为假时图标
+ *   仍然可点 —— 但那是「重来一次」而不是「重试」，文案上不提重试（见 `TtsFailure.Unconfigured`）。
+ * @property autoPlay 这一次结果还该不该**自动起播**（默认 true，起播过就置假，见
+ *   `ChatViewModel.consumeTtsAutoPlay`）。
+ *
+ *   为什么要这一位：请求发出去之后用户可能已经切到别的会话 / 别的页面。若只按「文件到了就放」
+ *   来触发，等他切回来时会**突然响一段刚才点的朗读** —— 那不是他此刻的动作。所以自动起播只认
+ *   **第一次**落好的那一下，之后靠那枚图标。
+ */
+data class TtsClip(
+    val messageId: String,
+    val clipId: String,
+    val file: File?,
+    val failure: String?,
+    val retryable: Boolean,
+    val autoPlay: Boolean = true,
+) {
+
+    /** 请求还在飞（字节没到手、也还没有结论）：界面据此把图标画成「正在准备」。 */
+    val pending: Boolean get() = file == null && failure == null
+}
+
+/**
+ * 用户点了一下那枚朗读图标，**这一下该被当成什么**。
+ *
+ * 只有两档，因为只有两件事会发生：要么「停」，要么「（重新）念」。把它抽成纯函数是因为
+ * 判据跨了三处状态（这一格的 [TtsClip]、那条唯一播放通道的 [VoicePlaybackState]、以及
+ * `ttsClipIdOf` 铸的键），而它们谁都不该在自己的类里替对方下结论。
+ */
+sealed interface TtsSpeakIntent {
+
+    /** 这一条**正在响**，手上也有它的音频 ⇒ 这一下是「停」。 */
+    data object Stop : TtsSpeakIntent
+
+    /** 其余一切（没在响、响的是别的、失败过、缓存已命中想再听一遍）⇒ 交给 VM。 */
+    data object Speak : TtsSpeakIntent
+}
+
+/**
+ * 这一下点击是「停」还是「（重新）念」。
+ *
+ * ## 为什么必须有这条判据：否则「停止朗读」是空操作
+ * 图标在播放中画的是暂停符、读屏名字是 `TTS_STOP_DESCRIPTION`（见 `MessageBubble`），所以
+ * 用户点它时**意思是停**。但播放中 `TtsClip.pending` 是假的（文件早就到手了），于是
+ * `ChatViewModel.beginTtsSpeak` 的防抖放行、整格被换成新的 pending、缓存命中秒回、
+ * 起播 effect 又因为「已经在放同一条」而跳过 `toggleClip` —— 三处各自都「没错」，合起来就是
+ * 点了没反应。判据落在**播放通道**这一处（它是「有没有在响」的唯一真相），才不会有第二处
+ * 各自解释「播放中」是什么意思。
+ *
+ * ## 为什么要 `file != null`
+ * 「正在响」与「音频在手上」是两件事：通道处于 [VoicePlaybackState.Loading] 时它也算 active，
+ * 而那一刻 [TtsClip.file] 可能还是 `null`（字节在 VM 那边取）。那时把点击解释成「停」会停掉
+ * 一次**还没起播**的载入，而用户点它的本意是「念」——所以只有文件确实在手、通道确实在响时才判
+ * [TtsSpeakIntent.Stop]；其余一律 [TtsSpeakIntent.Speak]，由 VM 的 pending 分支去防抖。
+ *
+ * @param playback 那条唯一播放通道此刻的状态（`VoicePlayer.state`）。
+ * @param messageId 被点的那条消息。
+ * @param clip 这一条自己的朗读格（`messageId` 对不上的要当没点过，判据里再核一次）。
+ */
+fun ttsSpeakIntent(
+    playback: VoicePlaybackState,
+    messageId: String,
+    clip: TtsClip?,
+): TtsSpeakIntent {
+    val file = clip?.takeIf { it.messageId == messageId }?.file
+    return if (file != null && playback.isActiveFor(ttsClipIdOf(messageId))) {
+        TtsSpeakIntent.Stop
+    } else {
+        TtsSpeakIntent.Speak
+    }
+}
@@ -0,0 +1,312 @@
+package top.yeij.cyrene.ui.sessions
+
+import top.yeij.cyrene.data.repository.MessageIncrement
+
+/**
+ * 一帧 `message_persisted` 属于哪条路（[persistedRoute] 的取值）。
+ *
+ * 这一帧按下行的**每一个**会话广播（服务端不按会话订阅，见 `ChatSocket`），而收帧的
+ * `SessionsViewModel` 手里是**整个列表**，所以每一帧都要先回答这一个问题。
+ */
+internal enum class PersistedRoute {
+    /**
+     * 就是**当前打开的那个会话**：消息已经显示在屏幕上了，就地推进已读游标即可
+     * （契约 §3.9 的客户端处理建议：看不到它攒出角标）。
+     *
+     * 这条路**不发任何请求去拉列表** —— 「自己正在看的会话」从来不是未读的来源，
+     * 多拉一次列表只会白花两个请求（而抽屉里的未读本来也不会因为这一帧变多）。
+     */
+    ActiveSession,
+
+    /**
+     * **别的**会话落了新消息：它攒未读是正确行为（红点该亮），而本端**数不出这个数**
+     * （`message_persisted` 帧不带 `unreadCount`）⇒ 节流地问服务端要。
+     *
+     * 这正是 W49 修的那一幕：**App 停在主会话时，次级会话来了新消息，抽屉红点不出现**。
+     * 此前帧在这一档直接 `return`，而列表更新的触发点只有抽屉打开 / 新建 / 删除 / init 四处，
+     * 于是红点必须靠用户开一次抽屉才补上。
+     *
+     * 「要」的是什么，W77 换过一次：原来是整表 `GET /sessions`，现在是**这条会话的消息增量**
+     * `GET /messages?after=`（见 [incrementCursors] / [applyIncrement]）；整表退回成「增量给不出
+     * 可信答案」时的回落。判据本身不受影响——这一档该不该被窗口挡住，与问的是哪种口径无关。
+     */
+    InactiveSession,
+}
+
+/**
+ * 这一帧该走哪条路（**纯函数**，VM 与测试共用）。
+ *
+ * 判据只有一句等值——它单独成一个函数，是因为**「激活会话那一档一定不拉列表」是要一直成立的边界**：
+ * 写成一个函数才断言得了（先例：`ui.chat.hasSendableContent`，同样是把「入口与投递口必须用同一条
+ * 判据」这件事拎出来）。`sessionId` 由调用方保证非空白（帧壳里没有会话 id 的坏帧在更外层就整帧跳过了：
+ * 那种帧连「是谁」都不知道，没有一条路可走）。
+ */
+internal fun persistedRoute(sessionId: String, activeSessionId: String): PersistedRoute =
+    if (sessionId == activeSessionId) PersistedRoute.ActiveSession else PersistedRoute.InactiveSession
+
+/**
+ * 静默重拉的节流窗口（毫秒）：**3 秒**。
+ *
+ * 为什么是这个数（三个约束互相顶出来的折中）：
+ * - **要够快**，否则等于没修：那一幕是「App 停在主会话、次级会话来了新消息」，红点必须在用户还盯着
+ *   聊天页的时候就自己出现（今天那一眼只能看见标题栏，看不见抽屉）。3 秒落在「看起来就是刚发生的」
+ *   这个感知里；5 秒往上就开始像「卡了一下才补上」。
+ * - **要够粗**，否则节流没意义：一次静默重拉是**两个**请求（[SessionsViewModel.refresh] 里还跟着
+ *   一次角色目录），而播出方是按**每条消息**推 `message_persisted` 的 —— 有人连发 5 条、或一轮回复
+ *   连续落库几条，都必须在同一个窗口里合并。3 秒能把「一次连发」稳稳收进来（人手连打 5 条约 2~4 秒，
+ *   同一轮落库通常在 1 秒内）；窗口收到 1 秒就会漏成两三次请求。
+ * - **别另立尺子**：3 秒正是本项目已有的「等够久才值得为一次等待开口」的那个量级
+ *   （`ChatScreen.SHARE_WAIT_NOTICE_MILLIS`），沿用同一套体感标尺。
+ *
+ * 它给的是**上限**保证（窗口内最多一次请求），**下限**由补拉那一档给
+ * （[SilentRefreshAction.ScheduleTrailing]：最后一条之后必定还会再拉一次）。两个一起才成立：
+ * 只有上限会把红点停在旧值上，只有下限等于没节流。
+ */
+internal const val SILENT_REFRESH_WINDOW_MILLIS = 3_000L
+
+/**
+ * 一次静默重拉的成因（[silentRefreshStep] 的入参之一）。
+ *
+ * 只分两类，是因为判据**只关心一件事**：这一次该不该被节流窗口挡住。窗口存在的唯一理由是
+ * 「把同一场连发合并成一次请求」，所以要能分辨「这场连发」与「跟连发无关、本来就必须马上对齐」的那类。
+ */
+internal enum class SilentRefreshCause {
+    /**
+     * 非激活会话落了新消息（[PersistedRoute.InactiveSession]）：**必须走窗口** ——
+     * 播出方按每条消息推帧，不节流就是连发几条打几个请求。
+     */
+    InactiveSessionMessage,
+
+    /**
+     * 手里这份列表**换了主人**（账号 / 服务器地址变了，在登录态上报时判出）：**不该被窗口挡住**。
+     *
+     * 窗口等的是「别的会话又攒了多少条」，与「这份列表还是不是当前这个账号的」毫无关系 ——
+     * 被它挡住的话，新身份会拿着一份属于上个身份（或已被清空）的列表过完整个窗口，而这时**根本没有
+     * 任何一场连发值得合并**。
+     *
+     * 会话切换（`SessionsViewModel.select`）在判据上属于同一类，但那条路**刻意不接进来** ——
+     * 理由写在那里：它紧接着就发了一次推进已读游标的请求，重拉会与还没落地的游标抢跑、把刚清掉的
+     * 角标闪回来。
+     */
+    ContextChanged,
+}
+
+/**
+ * 静默重拉的节流账本（**纯值**：[silentRefreshStep] 的入参，也是它的出参）。
+ *
+ * 时钟由调用方喂（[silentRefreshStep] 的 `nowMillis`），这里**不藏** `System.currentTimeMillis()`：
+ * 判据才可单测，也才不用为了「等 3 秒」写 sleep（先例：`domain.chat.RetryKeyMemory`）。
+ *
+ * @param lastPullAt 上一次**真的发出**那次静默重拉的时刻（毫秒）；`null` = 本进程还没拉过。
+ *   只由**这条路径**记账：抽屉打开 / 新建 / 删除 / init 那几处的拉取不写它。刻意不写 —— 那几处是
+ *   用户动作或一次性事件，把它们的时刻算进来只会让本路径**少拉**一次，而少拉正是「红点停在旧值」
+ *   的成因本身。
+ * @param trailingPending 已经排上了一次「窗口到点补拉」。已排上时再来的成因只更新账本、不重复排
+ *   （[SilentRefreshAction.Ignore]）—— 「同一时刻最多一个补拉任务」是补拉不会滚成一串的结构性保证，
+ *   而不是某一次调用的运气。
+ */
+internal data class SilentRefreshThrottle(
+    val lastPullAt: Long? = null,
+    val trailingPending: Boolean = false,
+)
+
+/** 这一刻该做什么（[silentRefreshStep] 的取值）。 */
+internal enum class SilentRefreshAction {
+    /** 现在就拉，窗口从这一刻重新开始。 */
+    PullNow,
+
+    /** 窗口内：**现在不拉**，排一次窗口到点的补拉（trailing），见 [silentRefreshStep] 第 3 条。 */
+    ScheduleTrailing,
+
+    /** 什么都不做：窗口内，且补拉已经排上了 —— 那一次本来就是把窗口里所有成因合起来做掉。 */
+    Ignore,
+}
+
+/**
+ * [silentRefreshStep] 的结论：**该做什么** + **做完之后账本走成什么样**。
+ *
+ * 两半一起回是刻意的（先例：`domain.chat.RetryKeyDecision`）：账本的另一半（窗口起点、有没有补拉）
+ * 由本次判定决定，拆开返回就给了调用方「判了却忘了推进窗口」的机会 —— 那正是节流失效最常见的写法。
+ */
+internal data class SilentRefreshStep(
+    val action: SilentRefreshAction,
+    /** 补拉还要等多久（毫秒）；只有 [SilentRefreshAction.ScheduleTrailing] 有意义，其余恒 `0`。 */
+    val delayMillis: Long,
+    val throttle: SilentRefreshThrottle,
+)
+
+/**
+ * 静默重拉的时机判据（**纯函数**，VM 与测试共用）。
+ *
+ * ## 为什么需要这一层
+ * [PersistedRoute.InactiveSession] 那一档要自己拉一次列表，但**裸着重拉不行**：播出方按每条消息推帧，
+ * 连发 5 条就是 5 个请求。所以有这里。
+ *
+ * ## 判据与优先级（自上而下，先命中先返回）
+ * 1. [SilentRefreshCause.ContextChanged] ⇒ [SilentRefreshAction.PullNow]。**压过窗口**（理由见那个
+ *    枚举值）。这一拉已经把窗口里那条消息要的刷新一并做掉了，所以窗口从这一刻**重开**、不再补一次
+ *    —— 落到第 3 条的话会 3 秒后再白拉一次同样的东西。
+ * 2. 窗口外（`lastPullAt` 为 `null`，或已过去 [SILENT_REFRESH_WINDOW_MILLIS]）⇒
+ *    [SilentRefreshAction.PullNow]，窗口从这一刻重开。
+ * 3. 窗口内、**还没有**排上补拉 ⇒ [SilentRefreshAction.ScheduleTrailing]，等「窗口减去已过去的时间」。
+ *    这一档就是 trailing 语义：**最后一条之后必定还会再拉一次**，红点不会停在旧值上。
+ * 4. 窗口内、补拉**已经排上** ⇒ [SilentRefreshAction.Ignore]：那一次补拉本来就是窗口里所有成因的合并。
+ *
+ * 判据里除了「成因」与「账本」什么都不看（不知道是哪个会话、也读不到 VM 状态），才能穷举、才能在 JVM
+ * 上单测（先例：`ui.chat.shareLanding`）。
+ *
+ * ## 边界口径：正好等于窗口**算窗口已过**（`>=` 而不是 `>`）
+ * 取这一边的理由很具体：补拉的等待时长就是按同一个常量算出来的（`窗口 - 已过去的时间`），它醒来
+ * 那一刻读到的钟通常**正好**是 `lastPullAt + 窗口` —— 判据这边若是 `>`，那一刻会被判成「还在窗口内」，
+ * 补拉就得再排一次（虽然最终仍会拉，但白绕一圈）。另一面也更好断言：测试直接拿
+ * [SILENT_REFRESH_WINDOW_MILLIS] 当「窗口刚过」的边界值，不必发明魔法数。（`RetryKeyMemory` 的边界
+ * 口径选的是**相反**的一侧，理由写在那边；两处不对称是各自的用途不同，不是笔误。）
+ *
+ * @param nowMillis 调用方喂的「现在」（`System.currentTimeMillis()`）。
+ * @param throttle 这份列表的节流账本，见 [SilentRefreshThrottle]。
+ */
+internal fun silentRefreshStep(
+    cause: SilentRefreshCause,
+    nowMillis: Long,
+    throttle: SilentRefreshThrottle,
+): SilentRefreshStep {
+    if (cause == SilentRefreshCause.ContextChanged) {
+        return SilentRefreshStep(SilentRefreshAction.PullNow, 0L, throttleAfterPull(nowMillis))
+    }
+    val lastPullAt = throttle.lastPullAt
+    if (lastPullAt == null || nowMillis - lastPullAt >= SILENT_REFRESH_WINDOW_MILLIS) {
+        return SilentRefreshStep(SilentRefreshAction.PullNow, 0L, throttleAfterPull(nowMillis))
+    }
+    if (!throttle.trailingPending) {
+        return SilentRefreshStep(
+            action = SilentRefreshAction.ScheduleTrailing,
+            delayMillis = SILENT_REFRESH_WINDOW_MILLIS - (nowMillis - lastPullAt),
+            throttle = throttle.copy(trailingPending = true),
+        )
+    }
+    return SilentRefreshStep(SilentRefreshAction.Ignore, 0L, throttle)
+}
+
+/**
+ * 真的拉过一次之后的账本（**纯函数**）：窗口从 [nowMillis] 重开，且不再有补拉 ——
+ * 这一拉已经把窗口里排队的成因一并覆盖，补拉再跑一次就是同一个请求白做一遍。
+ *
+ * 单独成一个函数，是因为**补拉任务到点时也要走这一步**（它照样是「真的拉过一次」，只是发起人不同）；
+ * 两处各写一遍 `SilentRefreshThrottle(lastPullAt = …)` 就多了一个会分叉的真相源。
+ */
+internal fun throttleAfterPull(nowMillis: Long): SilentRefreshThrottle =
+    SilentRefreshThrottle(lastPullAt = nowMillis)
+
+// ---------------------------------------------------------------------------------------------
+// W77：非激活会话的静默刷新，从「整表重拉 GET /sessions」换成「前向增量 GET /messages?after=」
+//
+// 后端明确批了这一换（回执二十八第 3 条：`?after=` 毫秒 `createdAt` 早就在册）。换掉的理由是**量**：
+// 整表一次要回**所有**会话（每条一行预览 + 未读计数），而这里只需要回**真的变了的那一个**会话的新消息。
+// 下面三个纯函数就是这一换的全部判据，放在这里而不是 VM 里，理由与 [silentRefreshStep] 一样：
+// 纯函数才穷举得了、才不用在 JVM 上摆一台假服务器。
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * 某个会话现在该从哪个 `createdAt` 起问增量（纯函数）；`null` = **这一行问不了**。
+ *
+ * 游标就取 [SessionItem.lastMessageAt]——最近一次权威 `GET /sessions` 给的、本端已知最新一条的
+ * `createdAt`——**不另立账本**：
+ * - 服务端的 `after` 是 `created_at > ?`（**严格**大于），而 [SessionItem.lastMessageAt] 正是
+ *   「已经见过的最新一条」⇒ 两边语义天然对齐，多立一个账本只会多一个会漂移的真相源；
+ * - 增量自己会把 [SessionItem.lastMessageAt] 推到新游标（[applyIncrement]），于是账本自洽地滚动，
+ *   不需要第二处推进。
+ *
+ * 两种「问不了」都落到 `null`，它们其实是同一件事——**本端不知道这条会话看到哪儿了**：
+ * - 行不在列表里（会话在别处新建、或本端那份列表还没拉到它）⇒ 没有游标可用；
+ * - 行在但 `lastMessageAt` 为 `null`（本端认为它一条消息都没有，却收到了它的落库广播）⇒
+ *   手里那份列表已经陈旧到不可信。
+ *
+ * 两种都由调用方回落到整表（唯一权威），见 `SessionsViewModel.flushPendingIncrements`。
+ */
+internal fun incrementCursorFor(item: SessionItem?): Long? = item?.lastMessageAt
+
+/**
+ * 一批待问增量的会话 id → 各自的 `after` 游标（纯函数）。
+ *
+ * `null` = **这批里有一个问不了**（[incrementCursorFor] 给了 `null`）⇒ 调用方**整批**回落整表。
+ * 不混着来是刻意的：一半靠增量、一半靠整表，得到的那份列表没有任何一处能说得清「它是什么时刻的」，
+ * 而未读面上最不能出的就是这种「说不清」。
+ *
+ * 返回 `emptyMap` = 这批本来就是空的（没有事要做），**不是**失败。
+ */
+internal fun incrementCursors(
+    sessionIds: Collection<String>,
+    sessions: List<SessionItem>,
+): Map<String, Long>? {
+    if (sessionIds.isEmpty()) return emptyMap()
+    val byId = sessions.associateBy { it.id }
+    val cursors = LinkedHashMap<String, Long>(sessionIds.size)
+    for (id in sessionIds) {
+        cursors[id] = incrementCursorFor(byId[id]) ?: return null
+    }
+    return cursors
+}
+
+/**
+ * 把一次增量折进列表（纯函数）：**只动那一行**，其余原样返回。
+ *
+ * ## 未读数怎么算：先过已读游标，再加
+ * 增量条数**不是**直接往角标上加的，要先按本地已知的已读游标 [readAt]（`readCursors[sessionId]`）筛一遍。
+ * **过滤口径**与服务端同源：`session_read.go` 的 `unreadCountQuery` 是 `count(created_at > read_at)`，
+ * 而 `read_at` 是**账号级单一游标**，可能比本端已知的最新消息还新——用户在这台机器上点开过它
+ * （[SessionsViewModel.select] 推的就是「现在」），随后别的设备又发了消息。那一刻
+ * `(lastMessageAt, readAt]` 之间的消息**服务端算已读**，一律加进角标就会多出来一个红点。所以只数
+ * `createdAt > readAt` 的那几条。
+ *
+ * 已有的 [SessionItem.unreadCount] 直接保留相加是安全的：它来自服务端，而这次增量里的每一条都严格新于
+ * [from]（服务端的 `after` 就是 `created_at > ?`），两者没有交集，不会重复计数。
+ *
+ * ## 已知边界：同源的只是**过滤口径**，基数仍是上次整表的旧值
+ * 相加的底数 [SessionItem.unreadCount] 来自上一次整表刷新，而 `read_at` 是账号级的、会被别的设备改写。
+ * 断线期间他端把某个会话读掉时，那条 `session_read` 帧本地**永久收不到**（断线不补帧），于是底数偏大，
+ * 这一行会一直多算那几条。这是**已接受的边界**，不是漏网：红点本来就只承诺「大概有几条新的」，漂移
+ * 到下一次整表刷新（打开抽屉 / 初始化 / 任何一次回落）就自愈。
+ *
+ * 这里**不**去检测它（例如「[readAt] > [from] ⇒ 底数可疑 ⇒ 回落整表」）：本端刚点开过这个会话时
+ * `readAt` 本来就被推到「现在」、必然大于 `lastMessageAt`，那是最常见的一档；拿它当异常信号会让增量
+ * 路径在正常使用下持续回落整表，而真正的「他端已读」它一样抓不全（断线时帧就丢了）。抓不准的闸门
+ * 不如不装。
+ *
+ * ## 并发的那一份真相
+ * [from] 不是「这次用了什么游标」的装饰：行上的 [SessionItem.lastMessageAt] **已经不等于** [from]，
+ * 就说明在这次请求飞在天上的时候，另一份更权威的结果（一次整表刷新、或另一次增量）已经推进过这一行。
+ * 那些条数已经被别人数过一遍了，再加一次就是重复计数 ⇒ 整行不动。
+ *
+ * 一行都没被改动时返回**同一个列表实例**（与 `applyBusyFrame` 同一习惯）：这条路径跑在后台，
+ * 没有必要为了「什么都没变」让整个抽屉重组一遍。
+ *
+ * @param from 这次请求用的 `after` 游标。
+ * @param readAt 本端已知的已读游标；`null` = 不知道（当作 `0`，即「一条都还没读过」）。
+ * @param increment 升序的增量（`MessageRepository.loadIncrement` 的产物）。
+ */
+internal fun List<SessionItem>.applyIncrement(
+    sessionId: String,
+    from: Long,
+    readAt: Long?,
+    increment: MessageIncrement,
+): List<SessionItem> {
+    if (increment.messages.isEmpty()) return this
+    val floor = readAt ?: 0L
+    val unseen = increment.messages.count { it.createdAt > floor }
+    // 升序 ⇒ 最后一条就是最新的一条（`loadIncrement` 保证这一点）。
+    val preview = increment.messages.last().content.toPreviewText().takeIf { it.isNotBlank() }
+    var touched = false
+    val updated = map { item ->
+        if (item.id != sessionId || item.lastMessageAt != from) {
+            item
+        } else {
+            touched = true
+            item.copy(
+                unreadCount = item.unreadCount + unseen,
+                lastMessage = preview,
+                lastMessageAt = increment.cursor,
+            )
+        }
+    }
+    return if (touched) updated else this
+}
@@ -0,0 +1,88 @@
+package top.yeij.cyrene.ui.sessions
+
+import top.yeij.cyrene.data.ws.WsEvent
+
+/**
+ * 「这个会话正在跑」的本端账本（**纯逻辑**，`SessionsViewModel` 与测试共用）。
+ *
+ * 形状是 `Map<会话 id, 本端见过的、还没收到收尾帧的在途路 id>`。**空集合也是在跑**——
+ * `session_busy` 帧本身通常不带 `turnId`（它走编排器的状态通道），只凭它也知道那个会话忙。
+ *
+ * ## 只有活帧能点亮，而且绝不外推
+ * 唯二的点亮来源是 [WsEvent.SessionBusy]（服务端说它忙）与 [WsEvent.TurnBegin]（服务端刚起了
+ * 一路）：两条都是**连接着的这一刻**推下来的帧。握手**不回放**该状态（S9 登记的那一格），所以
+ * 「本端连上之后还没收到过任何一条这样的帧」= **不知道** ⇒ 抽屉里什么都不显示（宁可没有）。
+ * 也不从别的线索外推——REST 列表不带这个状态，聊天页有没有在转也不带会话归属，
+ * 拿它们当证据就等于把「本端不知道」说成「它闲着」或「它忙着」。
+ *
+ * 把 [WsEvent.TurnBegin] 也算证据，是因为它与 [WsEvent.SessionBusy] **同源**：服务端启动一路时
+ * 两条一起发（一个是状态、一个是这一路的身份）。收到它就等于服务端在那一刻确认「这个会话在跑」，
+ * 不是本端的推断——而它比 `session_busy` 更频繁（每一路都有），所以 `session_busy` 那一帧如果
+ * 因为重连错过，下一路起来时灯还能亮回来。
+ *
+ * ## 收尾：三条帧，方向都是「宁可少显示」
+ * - [WsEvent.SessionIdle]（规范 §1.5：**全部**在途路收尾且 pending 空）⇒ 无条件收掉。
+ * - [WsEvent.SessionInterrupted] ⇒ 只有 `activeTurns` 说没有别的路在跑时才收掉。`scope:"current"`
+ *   只取消在跑的那一路、别的路照跑，无条件收掉就会在并行时显示「已经停了」——那正是 v2 前端审计
+ *   记成「会错」的一条（`Cyrene_v2/DevDocs/audit/前端同步缺口-2026-10-05.md` 的 A7）。
+ *   键缺席（`null`，v0.65 之前的老服务端）⇒ 那一版还没有并行这回事，单路被打断就是真的闲了 ⇒ 收掉。
+ * - [WsEvent.TurnEnd] ⇒ 只收它**认得**的那一路（[WsEvent.TurnBegin] 记下来过），且收掉之后一路不剩
+ *   才灭灯。帧壳 `turnId` 没见过（本端中途才接上、或那一帧的键缺席）就什么都不做：拿别的一路的
+ *   收尾去灭灯，会把还在跑的那一路报成空闲。
+ *
+ * `stream_end` **刻意不参与**：它只结束某一次模型流（一轮里有多个正文段、工具循环里还有多次），
+ * 而 `turn.end` 才结束整轮。按它灭灯就是上面 A7 那类错误的另一个入口。
+ *
+ * 幂等：同一帧重复到达（重连补拉、服务端重复广播）不改变结论。
+ */
+internal fun Map<String, Set<String>>.applyBusyFrame(event: WsEvent): Map<String, Set<String>> {
+    val sessionId = event.sessionId.sessionKey() ?: return this
+    return when (event) {
+        is WsEvent.SessionBusy ->
+            this + (sessionId to this[sessionId].plusTurn(event.turnId.sessionKey()))
+
+        is WsEvent.TurnBegin ->
+            this + (sessionId to this[sessionId].plusTurn(event.turnId.sessionKey()))
+
+        is WsEvent.TurnEnd -> {
+            val turnId = event.turnId.sessionKey()
+            val tracked = this[sessionId].orEmpty()
+            if (turnId == null || turnId !in tracked) {
+                this
+            } else {
+                val left = tracked - turnId
+                if (left.isEmpty()) this - sessionId else this + (sessionId to left)
+            }
+        }
+
+        is WsEvent.SessionIdle -> this - sessionId
+
+        is WsEvent.SessionInterrupted ->
+            if ((event.activeTurns ?: 0) > 0) this else this - sessionId
+
+        else -> this
+    }
+}
+
+/**
+ * 抽屉里那一行「正在跑」的字。
+ *
+ * 与聊天页输入栏下方那一行**逐字相同**（`ChatScreen.busyLabel`）：同一类服务端帧说的是同一件事，
+ * 两处各写一句就会各自漂移。措辞不分 `mode`（`thinking` / `executing` / `subagent`）——聊天页
+ * 也只看「忙不忙」这一个事实，用户要的是「她在干活、可以停」，不是编排细节。
+ */
+internal const val SESSION_BUSY_LABEL = "正在思考…"
+
+/**
+ * 停止入口上的字。用文字而不是图标：`MiuixIcons.Basic.*` 里只有 7 个（`Close` / `Search` / …），
+ * 没有一个读作「停止」，而**猜**一个语义相近的图标（`Pause`？`Remove`？）正是本项目禁止的动作
+ * （先例：`LoginScreen` 的「显示 / 隐藏」也是在 `IconButton` 里放两个字）。
+ */
+internal const val SESSION_STOP_LABEL = "停止"
+
+/** 帧里的 id：空白 = 坏帧（不知道说的是谁）⇒ 整帧不消费，与 `SessionsViewModel.onSessionRead` 同一条口径。 */
+private fun String?.sessionKey(): String? = this?.takeIf { it.isNotBlank() }
+
+/** 把这一路记进去；`turnId` 缺席（帧壳没给）时只维持「在跑」这个事实，不记无法配对的路。 */
+private fun Set<String>?.plusTurn(turnId: String?): Set<String> =
+    if (turnId == null) orEmpty() else orEmpty() + turnId
@@ -40,6 +40,7 @@ import top.yukonga.miuix.kmp.basic.Text
 import top.yukonga.miuix.kmp.basic.TextButton
 import top.yukonga.miuix.kmp.basic.TextField
 import top.yukonga.miuix.kmp.icon.MiuixIcons
+import top.yukonga.miuix.kmp.icon.basic.Close
 import top.yukonga.miuix.kmp.icon.extended.Add
 import top.yukonga.miuix.kmp.icon.extended.Delete
 import top.yukonga.miuix.kmp.icon.extended.Pin
@@ -59,6 +60,11 @@ import top.yukonga.miuix.kmp.theme.MiuixTheme
 * @param onCreate 参数是这次要绑定的角色 id：**null = 「默认角色」**（不绑，跟随全局默认角色）。
 *   类型必须是 `(String?) -> Unit`：调用方传的是 `SessionsViewModel::createSession` 这个方法引用，
 *   两边签名逐字对应。
+ * @param onDismissError 收起列表下方那条错误（[SessionsUiState.error]）。它不会自己消失，
+ *   所以必须有个关闭入口；关掉的只是**本端已经显示的**这一条（边界见 `SessionsViewModel.dismissError`）。
+ * @param onStopGenerating 停掉这个会话正在跑的那一轮（只对 [SessionsUiState.busySessions] 里那些行
+ *   出现）。它落到的出口与「她忙时发消息 = 打断」那一档**是同一个**（见
+ *   `SessionsViewModel.stopGenerating`）。
 */
@Composable
 fun ColumnScope.SessionDrawerContent(
@@ -68,9 +74,11 @@ fun ColumnScope.SessionDrawerContent(
    onDelete: (SessionItem) -> Unit,
    onTogglePin: (SessionItem) -> Unit,
    onRename: (String, String) -> Unit,
+    onStopGenerating: (SessionItem) -> Unit,
    onOpenIot: () -> Unit,
    onOpenAdmin: () -> Unit,
    onOpenSettings: () -> Unit,
+    onDismissError: () -> Unit,
 ) {
    var pendingDelete by remember { mutableStateOf<SessionItem?>(null) }
    var pendingRename by remember { mutableStateOf<SessionItem?>(null) }
@@ -107,22 +115,46 @@ fun ColumnScope.SessionDrawerContent(
                // 角色名在这里回填而不是在 VM 里拼进 SessionItem：这里能拿到角色表（也就能表达
                // 「角色表还没回来」的降级），而且 [personaLabelFor] 是一条可单测的纯函数。
                personaLabel = personaLabelFor(session.personaId, state.personas),
+                // 「谁在跑」是**整个列表**共用的一份（`session_busy` 说的是别的会话时本端也要收下），
+                // 所以它挂在 state 上、按 id 逐行查，而不是塞进 SessionItem（那一份是 REST 快照的
+                // 投影，每次重拉都会被整表替换，塞进去反而要让重拉记得把它带回来）。
+                busy = session.id in state.busySessions,
                active = session.id == state.activeSessionId,
                onClick = { onSelect(session.id) },
                onTogglePin = { onTogglePin(session) },
                onRename = { pendingRename = session },
                onDelete = { pendingDelete = session },
+                onStop = { onStopGenerating(session) },
            )
        }
    }

-    if (state.error != null) {
-        Text(
-            text = state.error.orEmpty(),
-            style = MiuixTheme.textStyles.footnote2,
-            color = MiuixTheme.colorScheme.error,
-            modifier = Modifier.padding(horizontal = 20.dp, vertical = 6.dp),
-        )
+    // 这条错误也不会自己消失，所以右侧给一个关闭入口——样式随它上面那几行：同一份水平内边距、
+    // 同一档 `footnote2`；图标用同文件里置顶/删除那两个 `IconButton` 的同一档灰度。
+    // 关掉的只是本端已经显示的这条，不代表服务端那边没事（边界见 SessionsViewModel.dismissError）。
+    state.error?.let { message ->
+        Row(
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(start = 20.dp, end = 8.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Text(
+                text = message,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+                modifier = Modifier
+                    .weight(1f)
+                    .padding(vertical = 6.dp),
+            )
+            IconButton(onClick = onDismissError) {
+                Icon(
+                    imageVector = MiuixIcons.Basic.Close,
+                    contentDescription = "关闭这条错误提示",
+                    tint = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+            }
+        }
    }

    if (state.fromCache && state.syncedAt > 0) {
@@ -304,16 +336,22 @@ private val PERSONA_LIST_MAX_HEIGHT = 320.dp
 *
 * @param personaLabel 该会话绑定的**角色名**（[personaLabelFor] 的回填；拿不到就不显示）。
 *   它挂在摘要行前面——「这个会话是谁在答话」比最后一条消息更该先被看到。
+ * @param busy 这个会话**本端已知**正在跑（S9）。它多带来两样东西：摘要行下面那行「正在思考…」，
+ *   以及把置顶按钮换成「停止」。判据与收尾规则见 `session_busy` 那一套（`SessionsViewModel`）。
+ *   注意它**不是**「服务端此刻在跑」——握手不回放该状态，没收到过帧的会话就是 `false`（宁可没有）。
+ * @param onStop 停掉正在跑的那一轮（[SessionsViewModel.stopGenerating]）。
 */
@Composable
 private fun SessionRow(
    session: SessionItem,
    personaLabel: String?,
+    busy: Boolean,
    active: Boolean,
    onClick: () -> Unit,
    onTogglePin: () -> Unit,
    onRename: () -> Unit,
    onDelete: () -> Unit,
+    onStop: () -> Unit,
 ) {
    val titleColor = BasicComponentDefaults.titleColor().color
    val summaryColor = BasicComponentDefaults.summaryColor().color
@@ -332,16 +370,30 @@ private fun SessionRow(
                        modifier = Modifier.padding(horizontal = 4.dp),
                    )
                }
-                IconButton(onClick = onTogglePin) {
-                    Icon(
-                        imageVector = if (session.pinned) MiuixIcons.Unpin else MiuixIcons.Pin,
-                        contentDescription = if (session.pinned) "取消置顶" else "置顶",
-                        tint = if (session.pinned) {
-                            MiuixTheme.colorScheme.primary
-                        } else {
-                            MiuixTheme.colorScheme.onSurfaceVariantSummary
-                        },
-                    )
+                // 「停止」与置顶**同一个槽位**，不是并列的两个：上面那段注释算过，`endActions` 的
+                // 硬上限（内部可用宽度的 60%）连现有的三个 40dp 动作都快顶不住，再并一个就会把
+                // 图标挤到裁剪。正在跑的那几行里「停」比「置顶」要紧，而置顶**不丢**：这一轮结束
+                // （灯灭）它立刻回来。
+                if (busy) {
+                    IconButton(onClick = onStop) {
+                        Text(
+                            text = SESSION_STOP_LABEL,
+                            style = MiuixTheme.textStyles.footnote1,
+                            color = MiuixTheme.colorScheme.primary,
+                        )
+                    }
+                } else {
+                    IconButton(onClick = onTogglePin) {
+                        Icon(
+                            imageVector = if (session.pinned) MiuixIcons.Unpin else MiuixIcons.Pin,
+                            contentDescription = if (session.pinned) "取消置顶" else "置顶",
+                            tint = if (session.pinned) {
+                                MiuixTheme.colorScheme.primary
+                            } else {
+                                MiuixTheme.colorScheme.onSurfaceVariantSummary
+                            },
+                        )
+                    }
                }
                if (!session.isMain) {
                    IconButton(onClick = onDelete) {
@@ -393,6 +445,18 @@ private fun SessionRow(
                    overflow = TextOverflow.Ellipsis,
                )
            }
+            // 第三行只给正在跑的会话。**另起一行而不是顶掉摘要**：摘要（最后一条消息）在这一刻
+            // 仍然有用——用户切走之后正是靠它认回「我刚才在哪个会话里说话」——而这一行是整行
+            // 宽度的普通文本，不需要从 `endActions` 或标题列里分走任何一个 dp。
+            if (busy) {
+                Text(
+                    text = SESSION_BUSY_LABEL,
+                    fontSize = MiuixTheme.textStyles.body2.fontSize,
+                    color = MiuixTheme.colorScheme.primary,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+            }
        }
    }
 }
@@ -2,6 +2,8 @@ package top.yeij.cyrene.ui.sessions

 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -10,10 +12,12 @@ import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
 import top.yeij.cyrene.app.AppContainer
 import top.yeij.cyrene.core.auth.SessionState
+import top.yeij.cyrene.core.prefs.accountFingerprint
 import top.yeij.cyrene.data.api.CyreneException
 import top.yeij.cyrene.data.api.dto.SessionSummaryDto
 import top.yeij.cyrene.data.ws.ChatSocket
 import top.yeij.cyrene.data.ws.WsEvent
+import top.yeij.cyrene.data.ws.WsState

 data class SessionItem(
    val id: String,
@@ -24,7 +28,8 @@ data class SessionItem(
    val lastMessage: String?,
    /**
     * 最后一条消息的时间戳（毫秒）；会话还没有消息时为 null。
-     * 只用于已读游标比对（见 [SessionItem.withReadCursor]），不直接显示。
+     * 两处用：已读游标比对（见 [SessionItem.withReadCursor]），以及增量追尾的 `after` 游标
+     * （见 `incrementCursorFor`，由 `applyIncrement` 推进到这次增量的 `cursor`）。不直接显示。
     */
    val lastMessageAt: Long? = null,
    /** 未读条数（服务端 `unreadCount`，D4）；`0` = 无未读、不显示角标。 */
@@ -55,6 +60,13 @@ data class SessionsUiState(
    val personasLoaded: Boolean = false,
    /** 角色目录拉取失败的原因。与会话列表的 [error] 分开：它只影响弹层里那几行，不动列表状态。 */
    val personaError: String? = null,
+    /**
+     * **本端已知正在跑**的会话 id（S9）。空 = 一个都不知道，抽屉里不显示任何「正在生成」。
+     *
+     * 它**不是**「服务端此刻在跑哪些会话」——握手不回放该状态，本端只知道**连上之后**收到过帧的
+     * 那些（判据与收尾规则见 [applyBusyFrame]）。所以它是「宁可没有」的一侧：拿不准就不显示。
+     */
+    val busySessions: Set<String> = emptySet(),
 )

 /**
@@ -69,14 +81,28 @@ data class SessionsUiState(
 * 同时调 `POST /sessions/{id}/read` 把游标推上去（策略详见 [pushReadCursor]）。
 * 反向同步（别的端读了）靠下行 `session_read` 帧。
 *
- * ## 为什么本类自己开一条 WS 连接
- * `session_read` / `message_persisted` 都在 WS 上，而 `AppContainer` 只提供
- * `createChatSocket()`（**每次调用新建**，没有进程级共享连接），`ChatSocket` / `ChatViewModel`
- * 又都在别的改动范围里。要在这里收帧，唯一不改别人的办法就是自持一条连接。
- * 代价如实说：这是本应用**已知遗留问题**（「每 VM 一条 socket、旧 socket 不关」，见
- * `devdocs/05`）之上再加一条——服务端对同一账号的多连接是支持的（多端场景本来如此），
- * 而且本类只关心两个帧类型，收不到也不会让功能失效（`GET /sessions` 会收敛）。
- * 生命周期：登录后连接、登出断开、VM 销毁断开（[onCleared]）。
+ * **非激活会话攒未读**（别人发来、别的设备发来）本端**不自己数**——`message_persisted` 帧不带
+ * `unreadCount`，逐条累加会与编辑 / 删除 / 别端操作漂移。本端做的是**自己去问一次服务端**：
+ * 收到非激活会话的落库广播就**节流地问一次那条会话的消息增量**（[requestSilentRefresh] →
+ * [flushPendingIncrements]，窗口 [SILENT_REFRESH_WINDOW_MILLIS]），于是抽屉的红点**不需要用户先开一次
+ * 抽屉**就会出现（S6，登记见 `devdocs/05-开发进度与交接.md`）。
+ *
+ * 取数走的是 `GET /messages?after=<ms>`（前向增量）而不是整表 `GET /sessions`——W77 换的，理由与回落
+ * 规则都写在 [flushPendingIncrements] 上。整表仍是**唯一权威**，只是不再需要为一条新消息付它的价钱。
+ *
+ * ## WS 连接：全 App 共享一条，而**本类是它唯一的主人**
+ * `session_read` / `message_persisted` 都在 WS 上，这个连接就是**进程内共享**的那一条
+ * （`AppContainer.chatSocket`；为什么可以共享见那里的 KDoc——服务端广播 ⇒ 各 VM 各收全部帧
+ * ⇒ 过滤逻辑一个字都不用改）。本类只订阅它，**不再自己开一条**。
+ *
+ * **开与关只在这里表达一次**：`LoggedIn → connect()`、`LoggedOut → close()`
+ * （[onCleared] 刻意**不关**，理由见那里）。选本类当主人的两条理由：
+ * ① 它由 `ChatHomeScreen` 在**一进登录态**就创建，且活在 Activity 级 `ViewModelStore` 里，存活期
+ *   正好覆盖「登录 → 登出 → 重登」，与共享连接要的那段时间完全重合；
+ * ② `ChatViewModel` / `AdminViewModel` 都只在**某个屏幕**出现时才创建（切会话 / 开管理页），让它们
+ *   当主人就会把「关掉一个屏幕」变成「关掉全 App 的连接」。
+ *
+ * baseUrl / token 都是每次重连现读 ⇒ 登出重登、换账号**不需要**重建实例。
 */
 class SessionsViewModel(private val container: AppContainer) : ViewModel() {

@@ -98,9 +124,52 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
     */
    private val readCursors = mutableMapOf<String, Long>()

-    private val socket: ChatSocket = container.createChatSocket()
+    /** 全 App 共享的那条连接；本类只订阅它，并且**是它唯一的主人**（登录时连、登出时关，见类注释）。 */
+    private val socket: ChatSocket = container.chatSocket
+
+    /**
+     * 静默重拉的节流账本（判据见 [silentRefreshStep]）。只有两条路会写它：非激活会话的落库广播
+     * （[onMessagePersisted]）与身份变化（登录态上报时的 [fingerprint] 比对）。
+     */
+    private var silentRefreshThrottle = SilentRefreshThrottle()
+
+    /**
+     * 排上的那次「窗口到点补拉」（[SilentRefreshAction.ScheduleTrailing]）。
+     * 它保证**最后一条新消息之后还会再拉一次**，红点因此不会停在旧值上；登出时取消
+     * （否则它会带着一个已经没有令牌的身份去发请求）。
+     */
+    private var trailingRefreshJob: Job? = null
+
+    /**
+     * 窗口里攒下的「要问增量的会话 id」（W77）。
+     *
+     * 为什么是一个**集合**而不是一个 id：节流窗口把同一段时间里的落库广播合并成一次拉取，而那几个
+     * 会话**未必是同一个**（主会话说一句、另一个会话也说一句）。只记住最后一条的话，前面那个会话的
+     * 红点就永远不会出现——那正是 W49 修过的同一类病，只是换了个成因。
+     *
+     * 只在 [requestSilentRefresh] / [flushPendingIncrements] 两处写；登出时清空（它属于上一个身份）。
+     */
+    private val pendingIncrements = mutableSetOf<String>()
+
+    /**
+     * 「谁在跑」的账本（S9）：会话 id → 本端见过的、还没收到收尾帧的在途路 id。
+     *
+     * 与 [SessionsUiState.busySessions] 是**同一件事的两面**：这一份带配对用的路 id（`turn.end`
+     * 要靠它才知道收掉的是哪一路），推给界面的那一份只要 id 的集合。两份只在一处一起写
+     * （[onBusyFrame]），不会各自漂移。
+     */
+    private var busyTurns: Map<String, Set<String>> = emptyMap()
+
+    /**
+     * 手里这份列表是**为哪个身份**拉回来的（[fingerprint]）；`null` = 这份列表没有主人
+     * （登出清空之后、换账号还没重拉）。
+     */
+    private var pulledForIdentity: String? = null

    init {
+        // 构造这一刻读到的身份就是 init 里那次 refresh 的身份（指纹只读本地已存的账号与地址，
+        // 是同步的）。先记下它，登录态第一次上报时才不会把「本来就是它拉的」误判成身份变了。
+        pulledForIdentity = fingerprint()
        viewModelScope.launch {
            val fingerprint = fingerprint()
            val cached = prefs.data.first()
@@ -122,6 +191,10 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
        // 登出时把快照一起清掉（先例：EnumCatalogViewModel 在登出时清枚举快照）——
        // 否则换账号后第一帧会闪一份上个账号的会话列表。已读游标同理：它是**账号级**的
        // （服务端单一游标），留着会让新账号的会话被旧账号的游标错误地清成已读。
+        //
+        // 这里同时是**全 App 共享连接唯一的那处开与关**（见类注释）：本 VM 的存活期正好覆盖
+        // 「登录 → 登出 → 重登」，而 `ChatViewModel` / `AdminViewModel` 只在某个屏幕出现时才创建，
+        // 它们不碰连接的生死。
        viewModelScope.launch {
            container.authManager.state.collect { auth ->
                when (auth) {
@@ -129,13 +202,45 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
                        socket.close()
                        readCursors.clear()
                        prefs.clear()
+                        // 「本端已知已删」也一样作废：它说的是**上一个环境**里那些 id 的结论，
+                        // 换账号之后本端什么都不知道（与快照 / 已读游标同一档，见 GoneSessions 的类注释）。
+                        container.goneSessions.clear()
+                        // 聊天页的槽位（W52A）同样一格不留：它们里面是上一个环境的消息列表与草稿，
+                        // 留着就是一份没人认领的常驻内存（而那一格里的 VM 还在订阅连接、还会在重连时
+                        // 补拉）。这一条把 `ChatSessionSlots` 那条「主会话永不回收」的例外也一起收干净
+                        // ——登出连主会话那一格也不留（代价：没发出去的草稿跟着没了，与上面几项同档）。
+                        container.chatSessionSlots.clear()
+                        // 手里这份列表与它的节流账本都属于上一个身份，一起作废：留着账本会让
+                        // 重登后那一次必要的重拉被上一轮的窗口挡住；留着补拉任务会让它带着一个
+                        // 已经没有令牌的身份去发请求（必然 401，还会在抽屉里挂一行错误）。
+                        trailingRefreshJob?.cancel()
+                        trailingRefreshJob = null
+                        silentRefreshThrottle = SilentRefreshThrottle()
+                        // 攒下的会话 id 同理：它们是上一个身份的会话，重登后那些 id 要么不存在、
+                        // 要么属于别人；留着只会让重登后的第一次窗口拿旧 id 去问增量。
+                        pendingIncrements.clear()
+                        pulledForIdentity = null
+                        busyTurns = emptyMap()
                        _state.value = SessionsUiState()
                    }

-                    // 连接只在登录后建立：Socket 的令牌 / 地址都是每次重连现读的，
-                    // connect() 幂等（已连接时直接返回）。本 VM 存活期跨越登出 → 重登，
-                    // 所以「登出断开、重登接上」必须在这里显式表达。
-                    is SessionState.LoggedIn -> socket.connect()
+                    // 连接只在登录后建立：baseUrl / token 都是每次重连现读的（换账号、续期都不需要
+                    // 重建实例），connect() 幂等（已连接时直接返回）。这里订阅的是一份 StateFlow，
+                    // 订阅即收到当前值，所以「重登接上」不需要额外的事件。
+                    is SessionState.LoggedIn -> {
+                        socket.connect()
+                        // 身份换了（重登成另一个账号、或换了服务器地址）：手里这份列表属于上一个
+                        // 身份，必须自己对齐一次。它**不该**被给「别的会话新消息」用的那个窗口挡住
+                        // （见 [SilentRefreshCause.ContextChanged]：那场连发与「列表是谁的」无关）。
+                        //
+                        // 同一个身份重复上报时什么都不做：这里订阅的是一份 StateFlow（订阅即收当前
+                        // 值，续期 / 重连都会再上报一次），每次都拉就成了凭空多出来的请求。
+                        val identity = fingerprint()
+                        if (identity != pulledForIdentity) {
+                            pulledForIdentity = identity
+                            requestSilentRefresh(SilentRefreshCause.ContextChanged)
+                        }
+                    }

                    SessionState.Unknown -> Unit
                }
@@ -143,10 +248,27 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
        }
        // 未读的两个下行来源都在这里收敛；见 [onEvent]。
        viewModelScope.launch { socket.events.collect(::onEvent) }
+        // 「谁在跑」只在**连接着的这段时间**里成立：握手不回放该状态，掉线期间服务端那边起了
+        // 什么、结束了什么，本端一个字节都收不到（S9 登记的那一格）。所以一离开 Connected 就当场
+        // 作废——否则一次「掉线时正好跑完」会让那盏灯**永远**亮着，而它旁边那个「停止」也永远点
+        // 不动（发出去只会撞上服务端对一个空闲会话的 no-op）：那是这个功能唯一会骗到人的地方。
+        // 代价是重连后要等下一路起来灯才回来（可能是这一轮、也可能是下一轮）——宁可没有。
+        viewModelScope.launch {
+            socket.state.collect { ws ->
+                if (ws == WsState.Connected || busyTurns.isEmpty()) return@collect
+                busyTurns = emptyMap()
+                _state.update { it.copy(busySessions = emptySet()) }
+            }
+        }
    }

+    /**
+     * **刻意不关连接**：`socket` 是**全 App 共享**的那一条（`AppContainer.chatSocket`），
+     * 而本 VM 随 Activity 结束就会被销毁——那时别的屏幕（或下一次进入 App）正要接着用它，
+     * 在 `onCleared` 里 close 就是「一个 VM 的死掐断全 App 的帧」。断开只由**登录态**表达
+     * （`LoggedOut` 分支；令牌失效那条路径经 `onAuthFailed` 也收敛到它）。
+     */
    override fun onCleared() {
-        socket.close()
        super.onCleared()
    }

@@ -211,6 +333,137 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
        }
    }

+    /**
+     * 节流地静默对齐一次 —— W49 修的「停在主会话时，次级会话来了新消息，抽屉红点不出现，
+     * 必须开一次抽屉才补上」（S6）。
+     *
+     * 列表此前只在抽屉打开 / 新建 / 删除 / init 四处更新，而 `message_persisted` 只处理
+     * 「正在看的那个会话」—— 别的会话攒未读**没有任何人会去发现**。
+     *
+     * ## 为什么是「问服务端」而不是「本地把未读数加一」
+     * `message_persisted` 帧**不带 `unreadCount`**：本端没有逐条时间线，靠帧自己数出来的数会与编辑 /
+     * 删除 / 别端操作漂移（这正是 [onMessagePersisted] 里那条纪律的由来）。所以这里**一个数都不造**，
+     * 只是把「服务端才是唯一真源」这件事提前做一次。
+     *
+     * ## W77：问的是**那一条会话的增量**，不再是整表
+     * 曾经的落点是 `refresh(silent = true)`（整表 `GET /sessions`），一次要为**所有**会话付一行预览 +
+     * 未读计数的价钱，而真正变了的只有一个会话。现在落到 [flushPendingIncrements]：
+     * `GET /messages?after=<已见最大 createdAt>`，只回那几条新消息。整表仍是唯一权威，但只在
+     * 「增量给不出可信答案」时才请它出场（回落规则写在 [flushPendingIncrements] 上）。
+     *
+     * ## 三条纪律
+     * 1. **节流**（判据 [silentRefreshStep]，窗口 [SILENT_REFRESH_WINDOW_MILLIS]）：一次连发只发一次
+     *    请求；同时保证**最后一条之后还会再拉一次**（trailing），红点不会停在旧值上。
+     * 2. **静默**：不闪「同步中…」——用户根本没开抽屉，不该有任何东西在动。失败时做什么**完全沿用既有
+     *    行为**（挂 [SessionsUiState.error] 那一行，只有打开抽屉才看得见；以及「网络异常，显示 x 分钟前
+     *    的结果」那一句），本方法不另加提示：一次后台的顺手对齐失败，不该比用户自己打开抽屉时的那次
+     *    刷新更吵。
+     * 3. **不抢跑**：不改 `activeSessionId`、不推进已读游标、不碰 [select]。回落那条路（[refresh]）
+     *    内部唯一会动 `activeSessionId` 的地方是 [resolveActiveSession]（当前会话被别处删掉时收敛回
+     *    主会话），那是既有的、正确的收敛，不是重置。
+     *
+     * @param cause 这次为什么要拉；决定它走不走窗口（见 [SilentRefreshCause]）。
+     * @param sessionId 这一帧说的是**哪个**会话；`null` = 没有具体会话（[SilentRefreshCause.ContextChanged]），
+     *   那一档只能走整表。窗口里攒下的 id 由 [pendingIncrements] 记着，因为一次窗口可能合并**几个不同**会话。
+     */
+    private fun requestSilentRefresh(cause: SilentRefreshCause, sessionId: String? = null) {
+        val step = silentRefreshStep(cause, System.currentTimeMillis(), silentRefreshThrottle)
+        silentRefreshThrottle = step.throttle
+        // 没有具体会话时不留 id：那一次整表会把所有会话都对上，攒着的 id 一个也不缺。
+        if (sessionId != null) pendingIncrements += sessionId
+        when (step.action) {
+            // 该拉了。先把**等在半路**的那次补拉撤掉：它要做的就是同一件事，留着会多拉一次。
+            // （只有 ContextChanged 压过窗口时才可能真的取消到一个活着的补拉任务——窗口外那一档
+            // 走到这里时 trailingPending 必为 false，补拉早跑完了。）
+            //
+            // 撤掉补拉**不等于**可以丢掉它攒下的 id：[pendingIncrements] 是独立的一份账本，
+            // 这一趟会把它们一并做掉。
+            SilentRefreshAction.PullNow -> {
+                trailingRefreshJob?.cancel()
+                trailingRefreshJob = null
+                flushPendingIncrements(fullTable = sessionId == null)
+            }
+
+            // 窗口内：排一次补拉。它是「最后一条之后还会再拉一次」的**唯一**保证——没有它，一串
+            // 广播的尾巴会被窗口吃掉，红点就停在旧值上（这正是节流最容易做错的那一半）。
+            //
+            // 到点时**直接拉**，不再回头问一次判据：那一刻读到的钟可能早一两毫秒，再问就会被自己
+            // 刚开的窗口挡回去、只能再排一次；而「窗口已经过去」是补拉自己等出来的事实，直接拉、
+            // 直接开新窗口更诚实，也少一条能自锁的路径。账本仍走纯函数那一份（[throttleAfterPull]），
+            // 免得两处各写一遍、各自漂移。
+            SilentRefreshAction.ScheduleTrailing -> {
+                trailingRefreshJob = viewModelScope.launch {
+                    delay(step.delayMillis)
+                    silentRefreshThrottle = throttleAfterPull(System.currentTimeMillis())
+                    flushPendingIncrements(fullTable = false)
+                }
+            }
+
+            // 窗口内、补拉已经排上：那一次本来就是把窗口里所有成因合起来做掉，这里不必再排。
+            // （但这一帧的会话 id 已经在上面记进 [pendingIncrements] 了 —— 补拉不会漏掉它。）
+            SilentRefreshAction.Ignore -> Unit
+        }
+    }
+
+    /**
+     * 把 [pendingIncrements] 里攒下的会话**逐个问一次消息增量**，问不了就整批回落整表（W77）。
+     *
+     * 这就是 W49 那条「非激活会话落了新消息 ⇒ 整表重拉 `GET /sessions`」的替代品：整表一次要回
+     * **所有**会话（每条一行预览 + 未读计数），而这里只回**真的变了的那一个**会话的新消息。
+     *
+     * ## 回落的三条理由（都落到同一条路：整表）
+     * 1. **问不了增量**：[incrementCursors] 给 `null` —— 行不在列表里，或本端不知道它看到哪儿了；
+     * 2. **追不到尾**：`complete = false` —— 整个追尾里拿过整页（服务端的 `LIMIT` 切过一刀，那一刀
+     *    可能劈开了同一毫秒，而服务端只给严格 `>`，被劈开的尾巴再也追不回来；此后的空页与不满页
+     *    都说不清），或翻满了 `MessageRepository.MAX_INCREMENT_PAGES`。那时增量只覆盖了积压的一部分，
+     *    拿它当「全部」就是把红点做小；
+     * 3. **请求失败**：含会话已在别处被删掉的 `404` —— 那一档要靠整表把这一行从列表里去掉。
+     *
+     * 三条都是「增量给不出可信答案」⇒ 去问唯一权威。**一次批次最多回落一次**：整批共用这一个失败
+     * 出口，否则 N 个会话同时失败就是 N 次整表。
+     *
+     * ## 刻意不做的一件事：不写快照
+     * [refresh] 成功时会 `prefs.saveSnapshot`，这里**不写**。快照的类型是 `List<SessionSummaryDto>`
+     * （整表响应），而增量只回了消息——拿它去拼一份 DTO 列表，缺的字段（`type` / `createdAt` /
+     * `pinned` / `personaId`）只能靠猜，那等于用一个更差的东西覆盖掉一份好快照。代价是冷启动第一帧
+     * 可能显示上一次整表时的未读与预览，紧接着 `init` 里那次 `refresh()` 就会把它修正。
+     *
+     * ## 也不顺带刷角色目录
+     * [refresh] 会捎带 `loadPersonas()`，这条路径不会。角色目录的刷新点是 init / 新建 / 删除 / 抽屉
+     * 打开（那几个都是用户动作或一次性事件），「别的会话来了条消息」从来不是它的刷新时机——此前它只是
+     * 跟着整表搭了便车。W77 把便车取消，角色目录少掉的是几次没人要的请求。
+     *
+     * @param fullTable `true` = 这一趟没有具体会话（或已判明必须整表），直接走 [refresh]。
+     */
+    private fun flushPendingIncrements(fullTable: Boolean) {
+        val targets = pendingIncrements.toList()
+        pendingIncrements.clear()
+        if (fullTable) {
+            refresh(silent = true)
+            return
+        }
+        val cursors = incrementCursors(targets, _state.value.sessions)
+        if (cursors == null) {
+            refresh(silent = true)
+            return
+        }
+        // 空批次 = 没有事要做（不是失败）：不回落、也不发请求。
+        if (cursors.isEmpty()) return
+        viewModelScope.launch {
+            for ((sessionId, from) in cursors) {
+                val increment = container.messageRepository.loadIncrement(sessionId, after = from).getOrNull()
+                if (increment == null || !increment.complete) {
+                    refresh(silent = true)
+                    return@launch
+                }
+                val readAt = readCursors[sessionId]
+                _state.update {
+                    it.copy(sessions = it.sessions.applyIncrement(sessionId, from, readAt, increment))
+                }
+            }
+        }
+    }
+
    /**
     * 切换 / 进入会话。
     *
@@ -221,6 +474,13 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
     *
     * `createSession` / `deleteSession` 也走这里，语义同样成立：那两个动作之后，
     * 屏幕上（即将）显示的就是这个会话。
+     *
+     * **这里刻意不顺手静默重拉**（虽然「切会话」在判据上属于 [SilentRefreshCause.ContextChanged]
+     * 那一类）：本函数紧接着就发了一次推进已读游标（[pushReadCursor]），而**它还没落地**——
+     * 这一刻的 `GET /sessions` 很可能仍按旧游标算出未读，就地清零会被它覆盖成「又有未读」
+     * （本端此时也没有可以遮罩的游标：[readCursors] 只在响应 / 帧到达后才记），用户就会看到
+     * 刚点开的那个会话角标**闪回来**。列表本来也不缺这一拉：抽屉打开时那一次（`ChatHomeScreen`）
+     * 紧接着就到，而它发生在游标之后。
     */
    fun select(sessionId: String) {
        _state.update {
@@ -253,6 +513,20 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
            container.sessionRepository.deleteSession(sessionId)
                .onSuccess {
                    prefs.removeSession(sessionId)
+                    // 本端**现在就知道**这个会话没了：那个会话的 ChatViewModel 还活着、还订阅着
+                    // 共享连接，但它没有别的渠道知道这件事 —— 不记这一笔，它会在**每一次**重连
+                    // 都发一次注定 404 的补拉（S7 登记的那一条：404 被静默吞掉，连一条线索都不留）。
+                    // 记的是「本端已知」而不是「用户界面该怎么表现」：这不是要让谁弹一句告知
+                    // （用户自己删的，他知道），只是让下一次补拉**事前**就判得掉。
+                    container.goneSessions.mark(sessionId)
+                    // 这个会话在本端从此没有行可显示 ⇒ 「谁在跑」里那条也当场作废（留着它只会让
+                    // 账本永远不为空，而它对应的那一行早就不存在了）。
+                    forgetBusy(sessionId)
+                    // 同一件事的另一半（W52A）：把那一格**交出去**。上面那一笔只让「还活着的 VM」
+                    // 别再发补拉，而这一格本来就该跟着会话一起消失 —— 它的消息列表（含内联 base64
+                    // 图片）没有任何理由继续占着内存。两半都在这里，是因为这里是本端**唯一**的删除
+                    // 入口（别处删掉的会话只能靠 404 那一档发现，那一档的收敛在 VM 自己身上）。
+                    container.chatSessionSlots.reclaim(fingerprint(), sessionId)
                    if (_state.value.activeSessionId == sessionId) {
                        select(SessionSummaryDto.MAIN_SESSION_ID)
                    }
@@ -297,6 +571,16 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
        }
    }

+    /**
+     * 收起**本端已经显示出来**的那条错误（抽屉里列表下方那一行）。
+     *
+     * 它清的只是那一行字：**不代表服务端那边的事已经好了**。关掉一次失败的删除 / 重命名 / 同步的
+     * 提示，并不会让那件事成功——重来一次照样会失败、照样会重新挂出这条错误。所以这里刻意
+     * **不动任何重试、也不动错误本身**，也不做自动消失（错误不该自己走掉）。
+     *
+     * 角色目录那条 [SessionsUiState.personaError] 不在这儿：它只属于「新建会话」弹层，
+     * 关弹层就跟着没了。
+     */
    fun dismissError() = _state.update { it.copy(error = null) }

    /**
@@ -306,18 +590,87 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
     * 一个会话」的场景（`ChatViewModel`）用的，而本 VM 持有**整个会话列表**——按 activeSessionId
     * 过滤会把「别的会话被读了」这一帧直接丢掉，正是最该处理的一半。所以改为按帧里的会话 id
     * **逐行定位**（[applyReadCursor]，影响面严格限制在那一行）。
+     *
+     * 「谁在跑」（S9）比未读更早折一遍：[onBusyFrame] 的判据与上面的纪律**同一条**——它认的是
+     * 帧里那个会话 id，不是当前打开的那个（抽屉要回答的正是「别的会话在不在跑」）。这一折**只读**
+     * 帧、不碰下面的分支，所以两条既有路径（W49 的节流静默重拉、[persistedRoute] 的两档）语义
+     * 一个字节都没变。
+     *
+     * **通知不在这里**（W57 起）：她主动说的话那两条路（实时帧 / 带 `proactive` 的落库帧）**曾经**
+     * 在本 VM 的帧订阅里转交给 `core.notify.ProactiveNotifier`，而这份订阅挂在 `viewModelScope` 上
+     * ——从最近任务把 Activity 划掉时它就没了，进程被前台服务保活着也收不到帧。那条通路现在由
+     * **进程级**的消费点喂（`app.ProactiveFrameIntake`，与那条共享连接同一层、同寿），本类**不再
+     * 判断通知的任何一件事**：这里只剩列表自己的两件事（未读、「谁在跑」）。
     */
    private fun onEvent(event: WsEvent) {
+        onBusyFrame(event)
        when (event) {
            // 别处（Web 面板 / 别的设备 / 本端另一次请求）读了：清掉那一行的红点。
            is WsEvent.SessionRead -> onSessionRead(event)
-            // 正在看的会话落了新消息：消息已经显示在屏幕上了，立刻推进游标，
-            // 否则「自己正看着的会话」会攒出一个未读角标（契约 §3.9 的客户端处理建议）。
+            // 落了新消息。哪一个会话都有事做：正在看的那个推进游标（消息已经显示在屏幕上了，
+            // 否则「自己正看着的会话」会攒出一个未读角标，契约 §3.9 的客户端处理建议），
+            // 别的会话则去问一次服务端（红点不该等用户开抽屉才出现）——两半都在 onMessagePersisted。
            is WsEvent.MessagePersisted -> onMessagePersisted(event)
+            // 她主动说的话（v0.72）。服务端**不为这条路补** `message_persisted`（那条只有 IM 路由
+            // 才广播），所以上面那一档永远不会被它触发——不在这里补一句，主会话的红点会停在她
+            // 开口之前，要等用户自己开一次抽屉（那次静默重拉）才补上。
+            is WsEvent.ProactiveMessage -> onProactiveMessage(event)
            else -> Unit
        }
    }

+    /**
+     * 把一帧折进「谁在跑」的账本（判据与收尾规则全在纯函数 [applyBusyFrame] 里），并只在**结论
+     * 真的变了**时推一次状态。
+     *
+     * 「变了才推」不是优化而是必需：这个函数对**每一帧**都会跑一遍，而流式那一串（`message.delta`
+     * / `thinking.delta`）是刷新率级的。无关帧在 [applyBusyFrame] 里原样返回**同一张表**，这里据此
+     * 直接返回，`_state` 因此一帧都不会被这些帧碰到。
+     */
+    private fun onBusyFrame(event: WsEvent) {
+        val next = busyTurns.applyBusyFrame(event)
+        if (next == busyTurns) return
+        busyTurns = next
+        _state.update { it.copy(busySessions = next.keys.toSet()) }
+    }
+
+    /** 本端从此不再（也不该再）关心这个会话在不在跑：它已经被删掉、本端再也没有可显示的那一行。 */
+    private fun forgetBusy(sessionId: String) {
+        if (sessionId !in busyTurns) return
+        busyTurns = busyTurns - sessionId
+        _state.update { it.copy(busySessions = busyTurns.keys.toSet()) }
+    }
+
+    /**
+     * 停掉**某一个会话**正在跑的那一轮（抽屉里那一行「停止」，W52B）。
+     *
+     * 走的是**既有的上行出口** [ChatSocket.sendInterrupt]：`interrupt{sessionId, scope}` 本来就带
+     * 会话归属（`WsOutbound.Interrupt` 的第一个参数就是它），所以「停某一个会话」既有的帧表达得了，
+     * **不需要新造帧**。
+     *
+     * ## 为什么恒发 `scope:"current"`
+     * 不读「她忙时发消息」那一档偏好：用户按的是一个**明确的动作**（停），不是「她忙时我该怎么办」
+     * 那档策略的延续。取值与 `InterruptMode.Interrupt.wireScope` 同一个，两条理由：
+     * 1. **本端从不发 `all`** 是一条既有不变式（`devdocs/02` 的 A2 补记、`devdocs/03` §4），
+     *    `dropped > 0` 那条「已打断，丢弃 N 条」的告知面在本端**不存在**；
+     * 2. `all` 会连**待处理队列**一起清掉，而队列里那些是用户自己敲进去、还没发出去的东西。
+     *    静默丢掉它们比不给这个按钮更坏。
+     *
+     * 于是这个按钮的语义是「**停掉正在跑的这一轮**」：排队中的消息照常会跑、灯随后会再亮起来——
+     * 那是实情，不是没按到。
+     *
+     * ## 刻意不在这里乐观灭灯
+     * 灯由服务端帧驱动（`session_interrupted` / `turn.end` / `session_idle`，见 [applyBusyFrame]）。
+     * 本端自己先灭，就等于替服务端宣布了一件还没发生的事；而帧一到，灯自然就灭了。
+     *
+     * 发不出去（WS 没连着）时**静默**：与 `ChatViewModel.interruptRunningTurn` 同一条纪律
+     * （那里写了三条理由）。而这一刻灯本来也不会亮——连接一断，账本当场作废（见 init 里那条订阅）。
+     */
+    fun stopGenerating(sessionId: String) {
+        if (sessionId.isBlank()) return
+        socket.sendInterrupt(sessionId, STOP_GENERATING_SCOPE)
+    }
+
    private fun onSessionRead(event: WsEvent.SessionRead) {
        if (event.sessionId.isBlank()) return
        recordReadCursor(event.sessionId, event.readAt)
@@ -325,22 +678,77 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
    }

    /**
-     * `message_persisted`：只有**当前打开的那个会话**才推进游标。
+     * `message_persisted` 的两条出路（路由判据 [persistedRoute]）：**当前打开的那个会话**推进游标；
+     * **别的会话**去问一次服务端。
     *
-     * 别的会话攒未读是正确行为（红点本来就该亮），所以这里不碰它们的计数——
-     * 本端只做「看到即已读」，不做「替服务端数未读」（增量计数会与编辑 / 删除 / 别端操作漂移，
-     * 而抽屉每次打开都会静默重拉，以服务端为准）。
+     * 两半共用同一条纪律：**本端哪里都不替服务端数未读**（逐条累加会与编辑 / 删除 / 别端操作漂移）。
+     * 区别只在「那它靠什么显示」：
+     * - [PersistedRoute.ActiveSession] ⇒ 就地清零 + 推进游标（这段一个字没改）；
+     * - [PersistedRoute.InactiveSession] ⇒ **节流地问一次这条会话的消息增量**（[requestSilentRefresh]
+     *   带上 `sessionId` → [flushPendingIncrements] → `MessageRepository.loadIncrement`），未读由
+     *   「增量里越过已读游标的条数」说话（W77；W49 那一档原本整表重拉 `GET /sessions`）。
+     *   这正是 W49 修的那一幕：此前这一档直接 `return`，于是「App 停在主会话、次级会话来了新消息」
+     *   没有任何人会去发现，红点要等用户打开一次抽屉才补上。
+     *
+     * 两档的**载荷要求不同**，是刻意的：推游标要用消息自己的 `createdAt`（缺了就只能什么都不做），
+     * 而「问一次增量」不需要载荷里的任何一个字段 —— **帧壳本身就是全部证据**（服务端只为「某条
+     * 消息已在某会话落库」才推这一帧）。所以非激活那一档**不检查 `event.message`**：真遇上载荷解不出的
+     * 坏帧（契约漂移的典型症状），宁可多问一次服务端，也不要让红点又停在旧值上。
     */
    private fun onMessagePersisted(event: WsEvent.MessagePersisted) {
        val sessionId = event.sessionId?.takeIf { it.isNotBlank() } ?: return
-        if (sessionId != _state.value.activeSessionId) return
-        val message = event.message ?: return
-        // `createdAt` 是服务端时间：用它当 before 比「现在」更精确——只把**这条**及其之前标成
-        // 已读，同时落库的其它消息（时间更晚）仍算未读。缺时间戳时退化成「现在」，语义见 select()。
-        val before = message.createdAt.takeIf { it > 0 }
-        before?.let { recordReadCursor(sessionId, it) }
-        _state.update { it.copy(sessions = it.sessions.markRead(sessionId)) }
-        pushReadCursor(sessionId, before)
+        when (persistedRoute(sessionId, _state.value.activeSessionId)) {
+            // 别的会话：本端数不出它的未读（帧不带 `unreadCount`）⇒ 节流地问一次**这条会话**的消息
+            // 增量，红点于是在用户**没开抽屉**的时候也会出现。这一帧到此为止。
+            PersistedRoute.InactiveSession ->
+                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage, sessionId)
+
+            // 屏幕上就是这个会话：就地清零 + 推进游标，**不发任何请求去拉列表**。
+            // 这里用 `when` 穷举而不是「不满足上面那条就走这段」：路由将来多一档时，
+            // 必须有人在这里做决定（先例：`ui.chat.queuedSendNoticeFor`）。
+            PersistedRoute.ActiveSession -> {
+                val message = event.message ?: return
+                // `createdAt` 是服务端时间：用它当 before 比「现在」更精确——只把**这条**及其之前
+                // 标成已读，同时落库的其它消息（时间更晚）仍算未读。缺时间戳时退化成「现在」，
+                // 语义见 select()。
+                val before = message.createdAt.takeIf { it > 0 }
+                before?.let { recordReadCursor(sessionId, it) }
+                _state.update { it.copy(sessions = it.sessions.markRead(sessionId)) }
+                pushReadCursor(sessionId, before)
+            }
+        }
+    }
+
+    /**
+     * 她主动说的话（v0.72 `proactive_message`）落在**主会话**——所以这一帧在本 VM 里问的是
+     * 「主会话那一行现在有没有未读」，与 [onMessagePersisted] 的两条出路**同一套口径**，
+     * 判据也共用 [persistedRoute]（只是会话 id 由这一帧自己钉：它不带 `sessionId`）。
+     *
+     * 为什么必须在这里补一句：服务端的主动推送 Web 路由只发这一帧，**不补** `message_persisted`
+     * （那条只有 IM 路由会广播），所以 W49 那条「非激活会话落新消息 ⇒ 节流刷新」根本不会被
+     * 触发——抽屉里主会话的红点就停在她开口之前，直到用户自己开一次抽屉。这里复用**同一条**路
+     * （[requestSilentRefresh] + 既有的 [SilentRefreshCause.InactiveSessionMessage]，会话 id 取主会话），
+     * 不新写取数路径，也不动节流判据本身。
+     *
+     * `id` 缺席 = 服务端那一刻**没有落库行** ⇒ 历史里没有这一行，未读面上没有任何东西要更新
+     * （本端也不替服务端数未读）。这一档的可见性由聊天页那条降级气泡负责，不归这里。
+     */
+    private fun onProactiveMessage(event: WsEvent.ProactiveMessage) {
+        if (event.id.isNullOrBlank()) return
+        val sessionId = SessionSummaryDto.MAIN_SESSION_ID
+        when (persistedRoute(sessionId, _state.value.activeSessionId)) {
+            PersistedRoute.InactiveSession ->
+                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage, sessionId)
+
+            // 屏幕上就是主会话：她这句话已经显示在聊天流里（ChatViewModel 那侧并入）⇒ 与
+            // message_persisted 的同一档一样「看到即已读」，免得抽屉为她刚说的话亮一个红点。
+            PersistedRoute.ActiveSession -> {
+                val before = event.createdAt?.takeIf { it > 0 }
+                before?.let { recordReadCursor(sessionId, it) }
+                _state.update { it.copy(sessions = it.sessions.markRead(sessionId)) }
+                pushReadCursor(sessionId, before)
+            }
+        }
    }

    /**
@@ -369,8 +777,9 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
        readCursors[sessionId] = maxOf(readCursors[sessionId] ?: 0L, readAt)
    }

+    /** 与聊天页的 VM key 用**同一份**口径（[accountFingerprint]），不要就地另拼字符串。 */
    private fun fingerprint(): String =
-        "${container.authManager.currentBaseUrl}|${container.sessionStore.load().username.orEmpty()}"
+        accountFingerprint(container.authManager.currentBaseUrl, container.sessionStore.load().username)
 }

 internal fun SessionSummaryDto.toItem(): SessionItem = SessionItem(
@@ -401,6 +810,17 @@ internal fun unreadBadgeText(count: Int): String? = when {
 /** 角标显示的未读上限；超过就显示 `99+`。 */
 internal const val UNREAD_BADGE_MAX = 99

+/**
+ * 「停止」那一帧的 `scope`（见 [SessionsViewModel.stopGenerating]）。
+ *
+ * 取值必须与 `InterruptMode.Interrupt.wireScope` 一致——本端**从不发 `all`** 是一条既有不变式
+ * （`devdocs/02` 的 A2 补记、`devdocs/03` §4），而 `all` 会静默清空待处理队列。
+ * 这里写字面量而不是引用那个枚举：那边的类型是 `String?`（`Parallel` 档就是 `null`），
+ * 直接传下去会让「取值一旦被改坏」退化成「发出一条省略 scope 的帧」= 服务端眼里的 `"all"`，
+ * 而那正是最坏的方向。两处一致由 `SessionBusyTest` 钉住。
+ */
+internal const val STOP_GENERATING_SCOPE = "current"
+
 /** 整表替换（REST 快照）时，把本地已知已读的那些行压回 0 未读；见 `SessionsViewModel.readCursors`。 */
 internal fun List<SessionItem>.withReadCursors(cursors: Map<String, Long>): List<SessionItem> =
    map { item -> cursors[item.id]?.let { readAt -> item.withReadCursor(readAt) } ?: item }
@@ -0,0 +1,205 @@
+package top.yeij.cyrene.ui.settings
+
+import android.Manifest
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.provider.Settings
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.unit.dp
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+import top.yeij.cyrene.core.prefs.AppPrefs
+import top.yeij.cyrene.core.prefs.AppSettings
+import top.yeij.cyrene.ui.common.PreferenceCard
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.preference.SwitchPreference
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 设置页的「后台保持连接」一行。
+ *
+ * ## 为什么单独一个文件
+ * 这一行自带状态与权限流程（授权状态、刚被拒的标记、发起申请、跳系统设置），是这块功能里唯一
+ * 会被改动的地方。`SettingsScreen.kt` 那边只留一行调用：改这里不会碰到别的行，改别的行也不会
+ * 碰到这里。
+ *
+ * ## 它只改一个偏好，**不起停服务**
+ * 起停只有一个主人（`CyreneApp` 里那个 `LaunchedEffect` + `core.keepalive.keepAliveAction`）：
+ * 这里写 `AppPrefs.keepAliveEnabled`，偏好一变，那边自己判、自己动手。两处各自 start / stop
+ * 迟早会打架（iOS/Android 都一样：能表达同一件事的地方只留一处）。
+ *
+ * ## 权限被拒时不假装成功
+ * `POST_NOTIFICATIONS` 是前台服务的**可见性**来源（minSdk 33，它是运行时权限）。被拒时本端
+ * **不打开开关**，并把原因写在开关下面：一个「开着但其实没跑」的开关比一个关着的开关更坏。
+ * 话说到「到系统设置里允许」为止还不够——用户不该自己摸进系统设置去找那一栏，所以那两档下面
+ * 直接给一个按钮，替他跳过去（见 [notificationSettingsFallback]）。
+ *
+ * @param settings 偏好写入口。
+ * @param prefs 当前偏好（开关的显示态）。
+ */
+@Composable
+internal fun KeepAliveRow(settings: AppSettings, prefs: AppPrefs) {
+    val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+
+    // 授权状态在本页内会变的只有两条路：我们刚发起的那次申请，以及我们刚把用户送去系统设置
+    // 又回来。后者靠 [openNotificationSettings] 的结果回调**直接复核**——从系统设置回来那一刻
+    // 才知道用户改成了什么，所以不需要再挂一个生命周期钩子去猜「是不是又回前台了」。
+    //
+    // ⚠️ 复核只纠正**这句话**，不改开关、也不起停服务：服务的起停判据在 `CyreneApp`，
+    // 而它的 `LaunchedEffect` 只认「开关」与「登录态」这两个键（权限是每次现读的入参）。
+    var allowed by remember { mutableStateOf(context.notificationsAllowed()) }
+    var justDenied by remember { mutableStateOf(false) }
+
+    val requestNotification = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        allowed = granted
+        justDenied = !granted
+        if (granted) scope.launch { settings.setKeepAliveEnabled(true) }
+    }
+
+    // 从系统设置回来：无论结果码是什么（那个页面一般回 RESULT_CANCELED），都现读一次真实授权。
+    val openNotificationSettings = rememberLauncherForActivityResult(
+        ActivityResultContracts.StartActivityForResult(),
+    ) {
+        allowed = context.notificationsAllowed()
+        // 刚回来时读到的就是最终答案，那句「刚刚被拒」已经过期了——留着它才是说假话。
+        justDenied = false
+    }
+
+    // 与 [keepAliveSummary] 里那两档**一一对应**：文案叫你「到系统设置里允许」，按钮就带你去
+    // 那里。这样两处不会各说各话（改了文案忘了按钮、或反过来，都会让用户觉得被耍）。
+    //
+    // 类型写全是有意的：`bottomAction` 收的是可空的可组合 lambda，写成 `if (...) null else {...}`
+    // 那种内联形状时要靠推导去猜哪一支是 `@Composable`，显式标出来省得编译器为难。
+    val settingsShortcut: (@Composable () -> Unit)? =
+        if (!allowed && (justDenied || prefs.keepAliveEnabled)) {
+            {
+                TextButton(
+                    text = "去系统设置",
+                    onClick = {
+                        // 先跳正式做法；有的 ROM 把那个页面砍了（`launch` 会抛
+                        // ActivityNotFoundException）⇒ 退到「应用详情页」，那里也有一栏「通知」。
+                        // 两次都失败就等于点了没反应，此时宁可什么都不做，也不让它崩。
+                        val direct = Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS)
+                            .putExtra(Settings.EXTRA_APP_PACKAGE, context.packageName)
+                        val launched = runCatching { openNotificationSettings.launch(direct) }.isSuccess
+                        if (!launched) {
+                            runCatching {
+                                openNotificationSettings.launch(notificationSettingsFallback(context))
+                            }
+                        }
+                    },
+                    modifier = Modifier.fillMaxWidth(),
+                )
+            }
+        } else {
+            null
+        }
+
+    KeepAliveSectionTitle()
+    PreferenceCard {
+        SwitchPreference(
+            title = "后台保持连接",
+            summary = keepAliveSummary(
+                enabled = prefs.keepAliveEnabled,
+                notificationsAllowed = allowed,
+                permissionJustDenied = justDenied,
+            ),
+            checked = prefs.keepAliveEnabled,
+            onCheckedChange = { wanted ->
+                justDenied = false
+                when {
+                    !wanted -> scope.launch { settings.setKeepAliveEnabled(false) }
+                    allowed -> scope.launch { settings.setKeepAliveEnabled(true) }
+                    // 还没授过（或授过又被撤）：按平台规范申请一次，结果由回调说话。
+                    else -> requestNotification.launch(Manifest.permission.POST_NOTIFICATIONS)
+                }
+            },
+            bottomAction = settingsShortcut,
+        )
+    }
+}
+
+/**
+ * 「去系统设置」的兜底去处。
+ *
+ * 首选是 `ACTION_APP_NOTIFICATION_SETTINGS` + `EXTRA_APP_PACKAGE`，那是 API 26 起的正式做法；
+ * 本端 minSdk 33，所以旧版那对 `"app_package"` / `"app_uid"` extra 与 API 24/25 的差异都用不着管。
+ * 剩下的一处差异不是 API 而是**厂商**：这个页面不是每个 ROM 都留着，砍了就退到这里
+ * （应用详情页，多一层才能点到「通知」）。
+ */
+private fun notificationSettingsFallback(context: Context): Intent =
+    Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
+        .setData(Uri.fromParts("package", context.packageName, null))
+
+/**
+ * 分段标题。样式与 `SettingsScreen.SectionTitle` 逐字一致：那边那个是 `private` 的，而这里要
+ * 的只是同一段样式，为此把它的可见性放宽不划算。两处将来若分叉，先动的是这个注释。
+ */
+@Composable
+private fun KeepAliveSectionTitle() {
+    Text(
+        text = "连接",
+        style = MiuixTheme.textStyles.subtitle,
+        color = MiuixTheme.colorScheme.primary,
+        modifier = Modifier.padding(start = 20.dp, top = 20.dp, bottom = 8.dp),
+    )
+}
+
+/**
+ * 开关下面那行字（**纯函数**，测试钉住）。它同时是**代价说明**与**当下真实状态**：
+ * 「关着会怎样」「开着要付出什么」「为什么没打开」——三件事都得说，且顺序上后者优先
+ * （用户刚被拒的那一次是此刻最要紧的信息）。
+ *
+ * 代价**必须自己说出来**，而且是**两份**：
+ * - 用户付的那份：一条常驻通知 + 多耗一点电。不说的代价会变成他某天「莫名其妙多了条通知」
+ *   的意外，那比不开这个功能更伤信任。
+ * - 系统收走的那份：`dataSync` 型前台服务在 targetSdk 37 下，**24 小时内累计最多 6 小时**
+ *   （`KeepAliveService.onTimeout` 到点自己收手，不硬撑到 ANR）。所以「全天候保活」做不到，
+ *   这句话不能只对他一个人藏着——一个以为买了全天候、结果 6 小时后悄悄断开的用户，
+ *   比一个从没开过这个开关的用户更亏。
+ *
+ * 因此「关 / 开」两档都带上了这条上限（[CAP_NOTE]）：关着的人要据此判断值不值得开，
+ * 开着的人要知道自己买到的到底是什么。
+ */
+internal fun keepAliveSummary(
+    enabled: Boolean,
+    notificationsAllowed: Boolean,
+    permissionJustDenied: Boolean,
+): String = when {
+    permissionJustDenied ->
+        "系统通知权限被拒绝，没能打开——前台服务没有通知就等于瞒着你常驻，本端不做这种事。到系统设置里允许 Cyrene 发送通知后再来打开"
+
+    enabled && !notificationsAllowed ->
+        "通知权限现在是关的，服务起不来：到系统设置里允许 Cyrene 发送通知后才会真的生效"
+
+    enabled ->
+        "已开：会常驻一条静默通知（不响铃、不震动），并多耗一点电；换来的是切到后台久了，实时连接也不被系统掐断。$CAP_NOTE"
+
+    else ->
+        "关：切到后台久了，系统可能冻结本进程并断开实时连接；消息不会丢（服务端已落库），回到前台会自动补上。$CAP_NOTE"
+}
+
+/**
+ * 系统给这类前台服务的额度。措辞刻意**不带情绪**：它是一个客观上限，不是遗憾——
+ * 说清了，用户才知道这开关换来的是「更久」而不是「永远」。
+ *
+ * 数字与 [top.yeij.cyrene.core.keepalive.KeepAliveService.onTimeout] 的注释同源（那边是机制，
+ * 这边是用户可见的说法）；改任何一处都得两处一起改。
+ */
+private const val CAP_NOTE = "不过系统对这种服务有上限：24 小时内累计最多 6 小时，用满会被停下"
@@ -8,13 +8,16 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
-import androidx.compose.ui.Alignment
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.launch
@@ -25,15 +28,19 @@ import top.yeij.cyrene.core.prefs.InterruptMode
 import top.yeij.cyrene.core.prefs.ThemeMode
 import top.yeij.cyrene.ui.common.PreferenceCard
 import top.yukonga.miuix.kmp.basic.BasicComponent
+import top.yukonga.miuix.kmp.basic.BasicComponentDefaults
+import top.yukonga.miuix.kmp.basic.ButtonDefaults
 import top.yukonga.miuix.kmp.basic.Icon
 import top.yukonga.miuix.kmp.basic.IconButton
 import top.yukonga.miuix.kmp.basic.Scaffold
 import top.yukonga.miuix.kmp.basic.SmallTopAppBar
 import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
 import top.yukonga.miuix.kmp.icon.MiuixIcons
-import top.yukonga.miuix.kmp.icon.extended.Back
 import top.yukonga.miuix.kmp.icon.extended.ChevronBackward
 import top.yukonga.miuix.kmp.icon.extended.ChevronForward
+import top.yukonga.miuix.kmp.icon.extended.Remove
+import top.yukonga.miuix.kmp.overlay.OverlayDialog
 import top.yukonga.miuix.kmp.preference.SwitchPreference
 import top.yukonga.miuix.kmp.theme.MiuixTheme

@@ -47,6 +54,8 @@ fun SettingsScreen(
    val prefs by container.appSettings.data.collectAsState(initial = AppPrefs())
    val scope = rememberCoroutineScope()
    val settings = container.appSettings
+    // 登出的二次确认。纯 UI 的开关，不进任何 VM：它不表达应用状态，只表达「这一次手指落在哪」。
+    var confirmLogout by remember { mutableStateOf(false) }

    Scaffold(
        topBar = {
@@ -105,6 +114,27 @@ fun SettingsScreen(
                )
            }

+            /*
+             * 「免打扰」单独占一段，不塞进上面那个「聊天」里：它管的是**通知**（屏幕上会不会被
+             * 盖住），与「聊天页怎么渲染」是两件事。下一段「连接」也是同一个道理（那边问的是连接
+             * 会不会断）。
+             *
+             * 写法与「后台保持连接」那一行逐项对齐（`KeepAliveRow.kt`）：`SwitchPreference` 外面
+             * 必须包一层 `PreferenceCard`（Miuix 的 Preference 系列自己没有背景与圆角），副文案
+             * 走一个纯函数（好单测，见 `proactiveQuietSummary`），改开关只写偏好、**不在这里做
+             * 任何通知相关的事**——发通知时自己会现读（见 `AppSettings.current`）。
+             */
+            SectionTitle("通知")
+            PreferenceCard {
+                SwitchPreference(
+                    title = "免打扰",
+                    summary = proactiveQuietSummary(prefs.proactiveQuiet),
+                    checked = prefs.proactiveQuiet,
+                    onCheckedChange = { scope.launch { settings.setProactiveQuiet(it) } },
+                )
+            }
+            Spacer(Modifier.height(8.dp))
+
            SectionTitle("她忙时发消息")
            InterruptMode.entries.forEach { mode ->
                PreferenceCard {
@@ -126,6 +156,8 @@ fun SettingsScreen(
                Spacer(Modifier.height(8.dp))
            }

+            KeepAliveRow(settings = settings, prefs = prefs)
+
            SectionTitle("关于")
            PreferenceCard {
                BasicComponent(
@@ -149,24 +181,66 @@ fun SettingsScreen(
            }

            Spacer(Modifier.height(32.dp))
+            // 图标不能再用 Back（左箭头）——真机上它看着就是「返回」，这条曾经难找得主人翻了半天。
+            // Miuix 没有专门的登出/退出字形（Basic 只有 7 个图标），extended 里最贴切的是 Remove：
+            // 它画的是「箭头离开方框」，语义就是移出/离开。
            PreferenceCard {
-                Row(
-                    modifier = Modifier
-                        .fillMaxWidth()
-                        .padding(vertical = 8.dp),
-                    horizontalArrangement = Arrangement.Center,
-                    verticalAlignment = Alignment.CenterVertically,
-                ) {
-                    IconButton(onClick = onLogout) {
+                BasicComponent(
+                    title = "退出登录",
+                    titleColor = BasicComponentDefaults.titleColor(color = MiuixTheme.colorScheme.error),
+                    startAction = {
                        Icon(
-                            imageVector = MiuixIcons.Back,
-                            contentDescription = "登出",
+                            imageVector = MiuixIcons.Remove,
+                            // 文字已经把这条读出来了，图标再说一遍只会让读屏重复。
+                            contentDescription = null,
                            tint = MiuixTheme.colorScheme.error,
                        )
-                    }
-                }
+                    },
+                    onClick = { confirmLogout = true },
+                )
            }
            Spacer(Modifier.height(32.dp))
+
+            /*
+             * 退出登录的确认框。
+             *
+             * 为什么非要有：这一条是**整行可点**，而它紧挨着上面那条「版本」——两条长得一样、
+             * 只差一行，误触的代价却是一次真登出（`AuthManager.logout` 会吊销服务端 refresh
+             * 并把本机凭据整份清掉，没有「撤销」）。一行可点的危险动作，必须再问一次。
+             *
+             * 用的是 Miuix 自己的 `OverlayDialog`（`top.yukonga.miuix.kmp.overlay`）：它由
+             * 本页 `Scaffold` 自带的 `MiuixPopupHost` 承载，标题 / 说明 / 内容分槽。注意 Miuix
+             * 没有 `extra.*` 包（0.9.x 里对话框就在 `overlay` / `window` 两处），别照旧版本的
+             * import 去猜。
+             *
+             * 三处出口刻意一致：取消按钮、点框外、系统返回键全都只是关掉这个框，一个字都不改；
+             * 只有「退出登录」这一条路通向 [onLogout]——行为链路与加这个框之前一模一样。
+             */
+            OverlayDialog(
+                show = confirmLogout,
+                title = "退出登录？",
+                // 如实说清代价（服务器地址也要重填）：登出后回到登录页，那儿是空的。
+                summary = "退出后本机会清空登录信息（服务器地址也要重填），需要重新登录",
+                onDismissRequest = { confirmLogout = false },
+            ) {
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.End,
+                ) {
+                    TextButton(text = "取消", onClick = { confirmLogout = false })
+                    Spacer(Modifier.width(8.dp))
+                    TextButton(
+                        text = "退出登录",
+                        onClick = {
+                            // 先把框收掉再登出：登出会把整个设置页（连同这个框的 remember）从
+                            // 组合里摘掉，留着它等于把一次「正在关闭」的动画交给一个正在消失的宿主。
+                            confirmLogout = false
+                            onLogout()
+                        },
+                        colors = ButtonDefaults.textButtonColorsPrimary(),
+                    )
+                }
+            }
        }
    }
 }
@@ -190,15 +264,37 @@ private fun ThemeMode.label(): String = when (this) {
 private fun InterruptMode.label(): String = when (this) {
    InterruptMode.AppendQueue -> "追加队列"
    InterruptMode.Interrupt -> "打断"
+    InterruptMode.Parallel -> "并行"
 }

 /**
- * 两档的差别只有一处：**忙时那条排队消息还在不在**。文案必须说清这一点——
- * 一个用户看不懂效果的偏好，比没有这个偏好更糟。
+ * 三档的差别只有一处：**忙时这条新消息与在跑的那一句是什么关系**（排队等着 / 把她打断 / 另起一路）。
+ * 文案必须说清这一点——一个用户看不懂效果的偏好，比没有这个偏好更糟。
+ *
+ * 「并行」那一条还多说半句**代价**（两路各算一遍 ⇒ 多花一份算力与 token）：那是主人 2026-10-05
+ * 裁决里接受了的成本（不分摊、优先性能），不是缺陷，但**用户有权知道**他花的这份钱买到了什么。
 */
 private fun InterruptMode.summary(): String = when (this) {
    InterruptMode.AppendQueue ->
        "她正忙时只把消息排进队列，等她做完当前回复再依次回；不打断（默认）"
    InterruptMode.Interrupt ->
        "她正忙时先打断当前这一句；已排队的消息保留，继续依次回答"
+    InterruptMode.Parallel ->
+        "她正忙时不打断当前这一句，另起一路同时处理这条；两路各算一遍，会多花一份算力与 token"
+}
+
+/**
+ * 「免打扰」开关下面那行字（**纯函数**，测试钉住）。它要说清的只有一件事：
+ * **这不是静音** —— 关掉的是横幅，不是消息、也不是提示音。
+ *
+ * 为什么非说不可：「免打扰」四个字在系统里到处都是，用户对它的第一印象常是「什么都不响」。而这个
+ * 开关实际做的是「她的话照旧响一声、躺在通知栏里，只是不再盖住我正在做的事」——两句话指向的期待
+ * 差得很远，一句不说就等于让用户自己猜（猜错的代价是他以为通知坏了，或以为自己买到了完全静音）。
+ *
+ * 两档都说出**当下会怎么弹**：用户据以决定的就是「现在这样够不够吵」，而只写「开着 = 安静」
+ * 等于让他自己去比较两种安静。
+ */
+internal fun proactiveQuietSummary(enabled: Boolean): String = when {
+    enabled -> "已开：她主动找你说话只在通知栏提示（有提示音），不在屏幕顶部弹横幅"
+    else -> "关（默认）：她主动找你说话会在屏幕顶部弹横幅，同时有提示音与通知栏条目"
 }