From 49fe691257a862a161030c26cc972923b79fbc38 Mon Sep 17 00:00:00 2001
From: xiaomo <wegi866@gmail.com>
Date: Mon, 1 Jun 2026 15:50:07 +0800
Subject: [PATCH 1/8] feat(workspace): collapsible file tree sidebar (#1720)

Co-authored-by: zhangmo8 <zhangmo8@users.noreply.github.com>
---
 .../components/sidepanel/WorkspacePanel.vue   | 381 ++++++++++++------
 src/renderer/src/i18n/da-DK/chat.json         |   1 +
 src/renderer/src/i18n/de-DE/chat.json         |   1 +
 src/renderer/src/i18n/en-US/chat.json         |   1 +
 src/renderer/src/i18n/es-ES/chat.json         |   1 +
 src/renderer/src/i18n/fa-IR/chat.json         |   1 +
 src/renderer/src/i18n/fr-FR/chat.json         |   1 +
 src/renderer/src/i18n/he-IL/chat.json         |   1 +
 src/renderer/src/i18n/id-ID/chat.json         |   1 +
 src/renderer/src/i18n/it-IT/chat.json         |   1 +
 src/renderer/src/i18n/ja-JP/chat.json         |   1 +
 src/renderer/src/i18n/ko-KR/chat.json         |   1 +
 src/renderer/src/i18n/ms-MY/chat.json         |   1 +
 src/renderer/src/i18n/pl-PL/chat.json         |   1 +
 src/renderer/src/i18n/pt-BR/chat.json         |   1 +
 src/renderer/src/i18n/ru-RU/chat.json         |   1 +
 src/renderer/src/i18n/tr-TR/chat.json         |   1 +
 src/renderer/src/i18n/vi-VN/chat.json         |   1 +
 src/renderer/src/i18n/zh-CN/chat.json         |   1 +
 src/renderer/src/i18n/zh-HK/chat.json         |   1 +
 src/renderer/src/i18n/zh-TW/chat.json         |   1 +
 src/renderer/src/stores/ui/sidepanel.ts       |  34 ++
 22 files changed, 317 insertions(+), 118 deletions(-)

diff --git a/src/renderer/src/components/sidepanel/WorkspacePanel.vue b/src/renderer/src/components/sidepanel/WorkspacePanel.vue
index e230d2555..33466fa8e 100644
--- a/src/renderer/src/components/sidepanel/WorkspacePanel.vue
+++ b/src/renderer/src/components/sidepanel/WorkspacePanel.vue
@@ -1,133 +1,174 @@
 <template>
   <div class="flex h-full min-h-0 min-w-0 flex-1 overflow-hidden">
-    <aside class="flex h-full min-h-0 w-[224px] shrink-0 flex-col border-r bg-muted/20">
-      <div class="flex-1 overflow-auto py-2">
-        <section>
-          <button
-            class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
-            type="button"
-            @click="sidepanelStore.toggleSection(props.sessionId, 'files')"
-          >
-            <Icon icon="lucide:folder-tree" class="h-3.5 w-3.5 text-muted-foreground" />
-            <span class="flex-1 truncate">{{ t('chat.workspace.sections.files') }}</span>
-            <Icon
-              :icon="sessionState.sections.files ? 'lucide:chevron-down' : 'lucide:chevron-right'"
-              class="h-3.5 w-3.5 text-muted-foreground"
-            />
-          </button>
-          <div v-if="sessionState.sections.files" class="pb-2">
-            <div
-              v-if="!props.workspacePath"
-              class="mx-2 rounded-lg border border-dashed border-muted-foreground/30 px-3 py-4 text-center"
-              :class="{ 'border-primary bg-primary/5': isDragging }"
-              @dragenter.prevent="isDragging = true"
-              @dragover.prevent="handleDragOver"
-              @dragleave="handleDragLeave"
-              @drop.prevent="handleDrop"
+    <aside
+      class="workspace-nav relative flex h-full min-h-0 shrink-0 flex-col overflow-hidden border-r bg-muted/20"
+      :class="{ 'workspace-nav--resizing': isNavResizing }"
+      :style="navStyle"
+    >
+      <div class="flex h-full min-h-0 shrink-0 flex-col" :style="{ width: expandedNavWidth }">
+        <button
+          class="flex w-full shrink-0 items-center gap-2 px-3 py-2 text-muted-foreground transition-colors hover:text-foreground"
+          type="button"
+          :title="navCollapsed ? t('chat.workspace.expand') : t('chat.workspace.collapse')"
+          @click="sidepanelStore.toggleNavCollapsed()"
+        >
+          <Icon
+            :icon="navCollapsed ? 'lucide:panel-left-open' : 'lucide:panel-left-close'"
+            class="h-3.5 w-3.5 shrink-0"
+          />
+        </button>
+        <div class="min-h-0 flex-1 overflow-auto pb-2">
+          <section>
+            <button
+              class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
+              type="button"
+              @click="handleSectionClick('files')"
             >
-              <Icon icon="lucide:folder-plus" class="mx-auto mb-2 h-6 w-6 text-muted-foreground" />
-              <p class="mb-2 text-xs font-medium text-foreground">
-                {{ t('chat.workspace.files.noWorkspace.title') }}
-              </p>
-              <p class="mb-3 text-[11px] text-muted-foreground">
-                {{ t('chat.workspace.files.noWorkspace.description') }}
-              </p>
-              <Button variant="outline" size="sm" class="h-7 text-xs" @click="selectFolder">
-                <Icon icon="lucide:folder-open" class="mr-1.5 h-3.5 w-3.5" />
-                {{ t('chat.workspace.files.noWorkspace.button') }}
-              </Button>
-            </div>
-            <div v-else-if="loadingFiles" class="px-3 py-2 text-[11px] text-muted-foreground/70">
-              {{ t('chat.workspace.files.loading') }}
+              <Icon icon="lucide:folder-tree" class="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+              <span v-show="!navCollapsed" class="flex-1 truncate">{{
+                t('chat.workspace.sections.files')
+              }}</span>
+              <Icon
+                v-show="!navCollapsed"
+                :icon="sessionState.sections.files ? 'lucide:chevron-down' : 'lucide:chevron-right'"
+                class="h-3.5 w-3.5 shrink-0 text-muted-foreground"
+              />
+            </button>
+            <div v-if="!navCollapsed && sessionState.sections.files" class="pb-2">
+              <div
+                v-if="!props.workspacePath"
+                class="mx-2 rounded-lg border border-dashed border-muted-foreground/30 px-3 py-4 text-center"
+                :class="{ 'border-primary bg-primary/5': isDragging }"
+                @dragenter.prevent="isDragging = true"
+                @dragover.prevent="handleDragOver"
+                @dragleave="handleDragLeave"
+                @drop.prevent="handleDrop"
+              >
+                <Icon
+                  icon="lucide:folder-plus"
+                  class="mx-auto mb-2 h-6 w-6 text-muted-foreground"
+                />
+                <p class="mb-2 text-xs font-medium text-foreground">
+                  {{ t('chat.workspace.files.noWorkspace.title') }}
+                </p>
+                <p class="mb-3 text-[11px] text-muted-foreground">
+                  {{ t('chat.workspace.files.noWorkspace.description') }}
+                </p>
+                <Button variant="outline" size="sm" class="h-7 text-xs" @click="selectFolder">
+                  <Icon icon="lucide:folder-open" class="mr-1.5 h-3.5 w-3.5" />
+                  {{ t('chat.workspace.files.noWorkspace.button') }}
+                </Button>
+              </div>
+              <div v-else-if="loadingFiles" class="px-3 py-2 text-[11px] text-muted-foreground/70">
+                {{ t('chat.workspace.files.loading') }}
+              </div>
+              <WorkspaceFileNode
+                v-for="node in fileTree"
+                :key="node.path"
+                :node="node"
+                :depth="0"
+                @toggle="toggleNode"
+                @append-path="handleFileSelect"
+                @insert-path="handleInsertFileReference"
+              />
             </div>
-            <WorkspaceFileNode
-              v-for="node in fileTree"
-              :key="node.path"
-              :node="node"
-              :depth="0"
-              @toggle="toggleNode"
-              @append-path="handleFileSelect"
-              @insert-path="handleInsertFileReference"
-            />
-          </div>
-        </section>
-
-        <section v-if="gitState">
-          <button
-            class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
-            type="button"
-            @click="sidepanelStore.toggleSection(props.sessionId, 'git')"
-          >
-            <Icon icon="lucide:git-branch" class="h-3.5 w-3.5 text-muted-foreground" />
-            <span class="flex-1 truncate">{{ t('chat.workspace.sections.git') }}</span>
-            <span class="text-[11px] text-muted-foreground">{{ gitState.changes.length }}</span>
-            <Icon
-              :icon="sessionState.sections.git ? 'lucide:chevron-down' : 'lucide:chevron-right'"
-              class="h-3.5 w-3.5 text-muted-foreground"
-            />
-          </button>
-          <div v-if="sessionState.sections.git" class="pb-2">
+          </section>
+
+          <section v-if="gitState">
             <button
-              v-for="change in gitState.changes"
-              :key="change.path"
-              class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors"
-              :class="
-                sessionState.selectedDiffPath === change.path
-                  ? 'bg-accent text-accent-foreground'
-                  : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
-              "
+              class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
               type="button"
-              @click="handleDiffSelect(change.path)"
+              @click="handleSectionClick('git')"
             >
-              <span class="w-4 shrink-0 text-center font-mono text-[11px]">
-                {{ formatGitFlag(change) }}
-              </span>
-              <span class="min-w-0 flex-1 truncate">{{ change.relativePath }}</span>
+              <Icon icon="lucide:git-branch" class="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+              <span v-show="!navCollapsed" class="flex-1 truncate">{{
+                t('chat.workspace.sections.git')
+              }}</span>
+              <span v-show="!navCollapsed" class="text-[11px] text-muted-foreground">{{
+                gitState.changes.length
+              }}</span>
+              <Icon
+                v-show="!navCollapsed"
+                :icon="sessionState.sections.git ? 'lucide:chevron-down' : 'lucide:chevron-right'"
+                class="h-3.5 w-3.5 shrink-0 text-muted-foreground"
+              />
             </button>
-            <div
-              v-if="gitState.changes.length === 0"
-              class="px-3 py-2 text-[11px] text-muted-foreground/70"
-            >
-              {{ t('chat.workspace.git.clean') }}
+            <div v-if="!navCollapsed && sessionState.sections.git" class="pb-2">
+              <button
+                v-for="change in gitState.changes"
+                :key="change.path"
+                class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors"
+                :class="
+                  sessionState.selectedDiffPath === change.path
+                    ? 'bg-accent text-accent-foreground'
+                    : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
+                "
+                type="button"
+                @click="handleDiffSelect(change.path)"
+              >
+                <span class="w-4 shrink-0 text-center font-mono text-[11px]">
+                  {{ formatGitFlag(change) }}
+                </span>
+                <span class="min-w-0 flex-1 truncate">{{ change.relativePath }}</span>
+              </button>
+              <div
+                v-if="gitState.changes.length === 0"
+                class="px-3 py-2 text-[11px] text-muted-foreground/70"
+              >
+                {{ t('chat.workspace.git.clean') }}
+              </div>
             </div>
-          </div>
-        </section>
-
-        <section v-if="artifactItems.length > 0">
-          <button
-            class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
-            type="button"
-            @click="sidepanelStore.toggleSection(props.sessionId, 'artifacts')"
-          >
-            <Icon icon="lucide:box" class="h-3.5 w-3.5 text-muted-foreground" />
-            <span class="flex-1 truncate">{{ t('chat.workspace.sections.artifacts') }}</span>
-            <span class="text-[11px] text-muted-foreground">{{ artifactItems.length }}</span>
-            <Icon
-              :icon="
-                sessionState.sections.artifacts ? 'lucide:chevron-down' : 'lucide:chevron-right'
-              "
-              class="h-3.5 w-3.5 text-muted-foreground"
-            />
-          </button>
-          <div v-if="sessionState.sections.artifacts" class="pb-2">
+          </section>
+
+          <section v-if="artifactItems.length > 0">
             <button
-              v-for="item in artifactItems"
-              :key="item.key"
-              class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors"
-              :class="
-                isArtifactSelected(item)
-                  ? 'bg-accent text-accent-foreground'
-                  : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
-              "
+              class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs font-medium"
               type="button"
-              @click="handleArtifactSelect(item)"
+              @click="handleSectionClick('artifacts')"
             >
-              <Icon :icon="getArtifactIcon(item.type)" class="h-3.5 w-3.5 shrink-0" />
-              <span class="min-w-0 flex-1 truncate">{{ item.title || item.identifier }}</span>
+              <Icon icon="lucide:box" class="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+              <span v-show="!navCollapsed" class="flex-1 truncate">{{
+                t('chat.workspace.sections.artifacts')
+              }}</span>
+              <span v-show="!navCollapsed" class="text-[11px] text-muted-foreground">{{
+                artifactItems.length
+              }}</span>
+              <Icon
+                v-show="!navCollapsed"
+                :icon="
+                  sessionState.sections.artifacts ? 'lucide:chevron-down' : 'lucide:chevron-right'
+                "
+                class="h-3.5 w-3.5 shrink-0 text-muted-foreground"
+              />
             </button>
-          </div>
-        </section>
+            <div v-if="!navCollapsed && sessionState.sections.artifacts" class="pb-2">
+              <button
+                v-for="item in artifactItems"
+                :key="item.key"
+                class="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors"
+                :class="
+                  isArtifactSelected(item)
+                    ? 'bg-accent text-accent-foreground'
+                    : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
+                "
+                type="button"
+                @click="handleArtifactSelect(item)"
+              >
+                <Icon :icon="getArtifactIcon(item.type)" class="h-3.5 w-3.5 shrink-0" />
+                <span class="min-w-0 flex-1 truncate">{{ item.title || item.identifier }}</span>
+              </button>
+            </div>
+          </section>
+        </div>
       </div>
+
+      <button
+        v-if="!navCollapsed"
+        data-testid="workspace-nav-resize-handle"
+        class="absolute inset-y-0 right-0 z-10 w-1.5 cursor-col-resize"
+        type="button"
+        @mousedown="startNavResize"
+      ></button>
     </aside>
 
     <WorkspaceViewer
@@ -144,7 +185,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, ref, toRef, watch } from 'vue'
+import { computed, onBeforeUnmount, ref, toRef, watch } from 'vue'
 import { Icon } from '@iconify/vue'
 import { Button } from '@shadcn/components/ui/button'
 import { useI18n } from 'vue-i18n'
@@ -159,7 +200,7 @@ import { useArtifactStore } from '@/stores/artifact'
 import { useMessageStore } from '@/stores/ui/message'
 import { useSidepanelStore, type WorkspaceArtifactContext } from '@/stores/ui/sidepanel'
 import { useSessionStore } from '@/stores/ui/session'
-import type { WorkspaceGitFileChange } from '@shared/presenter'
+import type { WorkspaceGitFileChange, WorkspaceNavSection } from '@shared/presenter'
 
 const props = defineProps<{
   sessionId: string
@@ -304,6 +345,91 @@ watch(
   { immediate: true }
 )
 
+// px-3 (12) + icon (14) + px-3 (12) so the leading icons sit centered in the collapsed rail
+const NAV_COLLAPSED_WIDTH = 38
+
+const navCollapsed = computed(() => sidepanelStore.navCollapsed)
+const isNavResizing = ref(false)
+
+const expandedNavWidth = computed(() => `${sidepanelStore.navWidth}px`)
+
+const navStyle = computed(() => ({
+  width: navCollapsed.value ? `${NAV_COLLAPSED_WIDTH}px` : expandedNavWidth.value
+}))
+
+const expandNavToSection = (section: WorkspaceNavSection) => {
+  sidepanelStore.setNavCollapsed(false)
+  const state = sidepanelStore.ensureSessionState(props.sessionId)
+  state.sections[section] = true
+}
+
+const handleSectionClick = (section: WorkspaceNavSection) => {
+  if (navCollapsed.value) {
+    expandNavToSection(section)
+    return
+  }
+  sidepanelStore.toggleSection(props.sessionId, section)
+}
+
+let navResizeCleanup: (() => void) | null = null
+let pendingNavWidth: number | null = null
+let navResizeFrame: number | null = null
+
+const applyPendingNavResize = () => {
+  navResizeFrame = null
+  if (pendingNavWidth === null) {
+    return
+  }
+  sidepanelStore.setNavWidth(pendingNavWidth)
+  pendingNavWidth = null
+}
+
+const stopNavResize = () => {
+  navResizeCleanup?.()
+  navResizeCleanup = null
+  if (navResizeFrame !== null) {
+    window.cancelAnimationFrame(navResizeFrame)
+    navResizeFrame = null
+  }
+  if (pendingNavWidth !== null) {
+    sidepanelStore.setNavWidth(pendingNavWidth)
+    pendingNavWidth = null
+  }
+}
+
+const startNavResize = (event: MouseEvent) => {
+  event.preventDefault()
+  stopNavResize()
+  isNavResizing.value = true
+
+  const startX = event.clientX
+  const startWidth = sidepanelStore.navWidth
+
+  const onMouseMove = (moveEvent: MouseEvent) => {
+    pendingNavWidth = startWidth + (moveEvent.clientX - startX)
+    if (navResizeFrame === null) {
+      navResizeFrame = window.requestAnimationFrame(applyPendingNavResize)
+    }
+  }
+
+  const onMouseUp = () => {
+    isNavResizing.value = false
+    stopNavResize()
+  }
+
+  window.addEventListener('mousemove', onMouseMove, { passive: true })
+  window.addEventListener('mouseup', onMouseUp, { once: true })
+  navResizeCleanup = () => {
+    window.removeEventListener('mousemove', onMouseMove)
+    window.removeEventListener('mouseup', onMouseUp)
+    isNavResizing.value = false
+  }
+}
+
+onBeforeUnmount(() => {
+  stopNavResize()
+})
+
 const handleFileSelect = (filePath: string) => {
   sidepanelStore.selectFile(props.sessionId, filePath, {
     open: false,
@@ -488,3 +614,22 @@ function getDroppedFilePath(file: File): string | null {
   return legacyPath || null
 }
 </script>
+
+<style scoped>
+.workspace-nav {
+  transition-duration: var(--dc-motion-default);
+  transition-property: width;
+  transition-timing-function: var(--dc-ease-out-express);
+  will-change: width;
+}
+
+.workspace-nav--resizing {
+  transition: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .workspace-nav {
+    transition: none;
+  }
+}
+</style>
diff --git a/src/renderer/src/i18n/da-DK/chat.json b/src/renderer/src/i18n/da-DK/chat.json
index 45cdbecce..c9800cecd 100644
--- a/src/renderer/src/i18n/da-DK/chat.json
+++ b/src/renderer/src/i18n/da-DK/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "tæt",
+    "expand": "Udvid",
     "sections": {
       "files": "Filer",
       "git": "Git",
diff --git a/src/renderer/src/i18n/de-DE/chat.json b/src/renderer/src/i18n/de-DE/chat.json
index b22a3b537..62c46e688 100644
--- a/src/renderer/src/i18n/de-DE/chat.json
+++ b/src/renderer/src/i18n/de-DE/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Arbeitsbereich",
     "collapse": "Einklappen",
+    "expand": "Erweitern",
     "sections": {
       "files": "Dateien",
       "git": "Git",
diff --git a/src/renderer/src/i18n/en-US/chat.json b/src/renderer/src/i18n/en-US/chat.json
index 2979d868b..74242831c 100644
--- a/src/renderer/src/i18n/en-US/chat.json
+++ b/src/renderer/src/i18n/en-US/chat.json
@@ -247,6 +247,7 @@
   "workspace": {
     "title": "Workspace",
     "collapse": "Collapse",
+    "expand": "Expand",
     "sections": {
       "files": "Files",
       "git": "Git",
diff --git a/src/renderer/src/i18n/es-ES/chat.json b/src/renderer/src/i18n/es-ES/chat.json
index 651b0e525..ace886bb1 100644
--- a/src/renderer/src/i18n/es-ES/chat.json
+++ b/src/renderer/src/i18n/es-ES/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Espacio de trabajo",
     "collapse": "Contraer",
+    "expand": "Expandir",
     "sections": {
       "files": "Archivos",
       "git": "Git",
diff --git a/src/renderer/src/i18n/fa-IR/chat.json b/src/renderer/src/i18n/fa-IR/chat.json
index 3d5749214..24a47d6aa 100644
--- a/src/renderer/src/i18n/fa-IR/chat.json
+++ b/src/renderer/src/i18n/fa-IR/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "بستن",
+    "expand": "گسترش",
     "sections": {
       "files": "فایل‌ها",
       "git": "Git",
diff --git a/src/renderer/src/i18n/fr-FR/chat.json b/src/renderer/src/i18n/fr-FR/chat.json
index b5ada232f..3ebbf8add 100644
--- a/src/renderer/src/i18n/fr-FR/chat.json
+++ b/src/renderer/src/i18n/fr-FR/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "fermer",
+    "expand": "Développer",
     "sections": {
       "files": "Fichiers",
       "git": "Git",
diff --git a/src/renderer/src/i18n/he-IL/chat.json b/src/renderer/src/i18n/he-IL/chat.json
index 73c5ad36c..130667210 100644
--- a/src/renderer/src/i18n/he-IL/chat.json
+++ b/src/renderer/src/i18n/he-IL/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "לִסְגוֹר",
+    "expand": "הרחב",
     "sections": {
       "files": "קבצים",
       "git": "Git",
diff --git a/src/renderer/src/i18n/id-ID/chat.json b/src/renderer/src/i18n/id-ID/chat.json
index 74ababbe4..ae19ae58e 100644
--- a/src/renderer/src/i18n/id-ID/chat.json
+++ b/src/renderer/src/i18n/id-ID/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "ruang kerja",
     "collapse": "dekat",
+    "expand": "Perluas",
     "sections": {
       "files": "Mengajukan",
       "git": "Git",
diff --git a/src/renderer/src/i18n/it-IT/chat.json b/src/renderer/src/i18n/it-IT/chat.json
index 95bbd1961..5d5e9a61f 100644
--- a/src/renderer/src/i18n/it-IT/chat.json
+++ b/src/renderer/src/i18n/it-IT/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Workspace",
     "collapse": "Comprimi",
+    "expand": "Espandi",
     "sections": {
       "files": "File",
       "git": "Git",
diff --git a/src/renderer/src/i18n/ja-JP/chat.json b/src/renderer/src/i18n/ja-JP/chat.json
index 2c19a2356..e0ccff46b 100644
--- a/src/renderer/src/i18n/ja-JP/chat.json
+++ b/src/renderer/src/i18n/ja-JP/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "近い",
+    "expand": "展開",
     "sections": {
       "files": "ファイル",
       "git": "Git",
diff --git a/src/renderer/src/i18n/ko-KR/chat.json b/src/renderer/src/i18n/ko-KR/chat.json
index 177fb83e3..19cd8f828 100644
--- a/src/renderer/src/i18n/ko-KR/chat.json
+++ b/src/renderer/src/i18n/ko-KR/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "닫다",
+    "expand": "펼치기",
     "sections": {
       "files": "파일",
       "git": "Git",
diff --git a/src/renderer/src/i18n/ms-MY/chat.json b/src/renderer/src/i18n/ms-MY/chat.json
index b87817d00..33f108652 100644
--- a/src/renderer/src/i18n/ms-MY/chat.json
+++ b/src/renderer/src/i18n/ms-MY/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "ruang kerja",
     "collapse": "dekat",
+    "expand": "Kembangkan",
     "sections": {
       "files": "dokumen",
       "git": "Git",
diff --git a/src/renderer/src/i18n/pl-PL/chat.json b/src/renderer/src/i18n/pl-PL/chat.json
index 3c6e17a0d..33b794beb 100644
--- a/src/renderer/src/i18n/pl-PL/chat.json
+++ b/src/renderer/src/i18n/pl-PL/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Obszar roboczy",
     "collapse": "Zwiń",
+    "expand": "Rozwiń",
     "sections": {
       "files": "Pliki",
       "git": "Git",
diff --git a/src/renderer/src/i18n/pt-BR/chat.json b/src/renderer/src/i18n/pt-BR/chat.json
index 469bb3c59..c1a20a26e 100644
--- a/src/renderer/src/i18n/pt-BR/chat.json
+++ b/src/renderer/src/i18n/pt-BR/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "fechar",
+    "expand": "Expandir",
     "sections": {
       "files": "Arquivos",
       "git": "Git",
diff --git a/src/renderer/src/i18n/ru-RU/chat.json b/src/renderer/src/i18n/ru-RU/chat.json
index c2e79ea4b..0c48182d6 100644
--- a/src/renderer/src/i18n/ru-RU/chat.json
+++ b/src/renderer/src/i18n/ru-RU/chat.json
@@ -190,6 +190,7 @@
   },
   "workspace": {
     "collapse": "закрывать",
+    "expand": "Развернуть",
     "sections": {
       "files": "Файлы",
       "git": "Git",
diff --git a/src/renderer/src/i18n/tr-TR/chat.json b/src/renderer/src/i18n/tr-TR/chat.json
index 59133b488..307e4f9b9 100644
--- a/src/renderer/src/i18n/tr-TR/chat.json
+++ b/src/renderer/src/i18n/tr-TR/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Çalışma alanı",
     "collapse": "Yıkılmak",
+    "expand": "Genişlet",
     "sections": {
       "files": "Dosyalar",
       "git": "Git",
diff --git a/src/renderer/src/i18n/vi-VN/chat.json b/src/renderer/src/i18n/vi-VN/chat.json
index fa08650b5..c4323c5ea 100644
--- a/src/renderer/src/i18n/vi-VN/chat.json
+++ b/src/renderer/src/i18n/vi-VN/chat.json
@@ -228,6 +228,7 @@
   "workspace": {
     "title": "Không gian làm việc",
     "collapse": "Thu gọn",
+    "expand": "Mở rộng",
     "sections": {
       "files": "Tập tin",
       "git": "Git",
diff --git a/src/renderer/src/i18n/zh-CN/chat.json b/src/renderer/src/i18n/zh-CN/chat.json
index 51c3b00ba..b50b278f2 100644
--- a/src/renderer/src/i18n/zh-CN/chat.json
+++ b/src/renderer/src/i18n/zh-CN/chat.json
@@ -247,6 +247,7 @@
   "workspace": {
     "title": "工作区",
     "collapse": "收起",
+    "expand": "展开",
     "sections": {
       "files": "文件",
       "git": "Git",
diff --git a/src/renderer/src/i18n/zh-HK/chat.json b/src/renderer/src/i18n/zh-HK/chat.json
index 43a4e1f7c..1e2e6e60c 100644
--- a/src/renderer/src/i18n/zh-HK/chat.json
+++ b/src/renderer/src/i18n/zh-HK/chat.json
@@ -198,6 +198,7 @@
   },
   "workspace": {
     "collapse": "收起",
+    "expand": "展開",
     "sections": {
       "files": "文件",
       "git": "Git",
diff --git a/src/renderer/src/i18n/zh-TW/chat.json b/src/renderer/src/i18n/zh-TW/chat.json
index 9a3f3d927..9d9d81639 100644
--- a/src/renderer/src/i18n/zh-TW/chat.json
+++ b/src/renderer/src/i18n/zh-TW/chat.json
@@ -198,6 +198,7 @@
   },
   "workspace": {
     "collapse": "收起",
+    "expand": "展開",
     "sections": {
       "files": "檔案",
       "git": "Git",
diff --git a/src/renderer/src/stores/ui/sidepanel.ts b/src/renderer/src/stores/ui/sidepanel.ts
index 9ee99b44f..1a7a9619f 100644
--- a/src/renderer/src/stores/ui/sidepanel.ts
+++ b/src/renderer/src/stores/ui/sidepanel.ts
@@ -56,6 +56,35 @@ export const useSidepanelStore = defineStore('sidepanel', () => {
     return clampWidth(Number(width.value))
   })
 
+  const NAV_MIN_WIDTH = 160
+  const NAV_MAX_WIDTH = 360
+  const NAV_DEFAULT_WIDTH = 200
+
+  const clampNavWidth = (nextWidth: number) => {
+    const widthValue = Number(nextWidth)
+    if (!Number.isFinite(widthValue)) {
+      return NAV_DEFAULT_WIDTH
+    }
+    return Math.min(NAV_MAX_WIDTH, Math.max(NAV_MIN_WIDTH, Math.round(widthValue)))
+  }
+
+  const navCollapsed = useStorage('workspace-nav-collapsed', false)
+  const navWidthStorage = useStorage('workspace-nav-width', NAV_DEFAULT_WIDTH)
+
+  const navWidth = computed(() => clampNavWidth(Number(navWidthStorage.value)))
+
+  const setNavWidth = (nextWidth: number) => {
+    navWidthStorage.value = clampNavWidth(nextWidth)
+  }
+
+  const setNavCollapsed = (collapsed: boolean) => {
+    navCollapsed.value = collapsed
+  }
+
+  const toggleNavCollapsed = () => {
+    navCollapsed.value = !navCollapsed.value
+  }
+
   if (typeof window !== 'undefined') {
     const handleResize = () => {
       viewportWidth.value = window.innerWidth
@@ -195,6 +224,11 @@ export const useSidepanelStore = defineStore('sidepanel', () => {
     open,
     activeTab,
     width: normalizedWidth,
+    navCollapsed,
+    navWidth,
+    setNavWidth,
+    setNavCollapsed,
+    toggleNavCollapsed,
     sessionStates,
     ensureSessionState,
     getSessionState,

From abfd6bea82f819ae63b4e4646db63075964ad729 Mon Sep 17 00:00:00 2001
From: xiaomo <wegi866@gmail.com>
Date: Mon, 1 Jun 2026 16:29:32 +0800
Subject: [PATCH 2/8] feat(sidebar): add animated theme toggle button (#1722)

* feat(sidebar): add animated theme toggle button

* perf(theme): suppress transitions during switch

* perf(theme): suppress transitions during switch

---------

Co-authored-by: zhangmo8 <zhangmo8@users.noreply.github.com>
---
 src/renderer/src/App.vue                      | 13 ++-
 src/renderer/src/assets/style.css             |  8 ++
 src/renderer/src/components/WindowSideBar.vue | 93 +++++++++++++++++++
 src/renderer/src/i18n/da-DK/chat.json         |  4 +
 src/renderer/src/i18n/de-DE/chat.json         |  4 +
 src/renderer/src/i18n/en-US/chat.json         |  4 +
 src/renderer/src/i18n/es-ES/chat.json         |  4 +
 src/renderer/src/i18n/fa-IR/chat.json         |  4 +
 src/renderer/src/i18n/fr-FR/chat.json         |  4 +
 src/renderer/src/i18n/he-IL/chat.json         |  4 +
 src/renderer/src/i18n/id-ID/chat.json         |  4 +
 src/renderer/src/i18n/it-IT/chat.json         |  4 +
 src/renderer/src/i18n/ja-JP/chat.json         |  4 +
 src/renderer/src/i18n/ko-KR/chat.json         |  4 +
 src/renderer/src/i18n/ms-MY/chat.json         |  4 +
 src/renderer/src/i18n/pl-PL/chat.json         |  4 +
 src/renderer/src/i18n/pt-BR/chat.json         |  4 +
 src/renderer/src/i18n/ru-RU/chat.json         |  4 +
 src/renderer/src/i18n/tr-TR/chat.json         |  4 +
 src/renderer/src/i18n/vi-VN/chat.json         |  4 +
 src/renderer/src/i18n/zh-CN/chat.json         |  4 +
 src/renderer/src/i18n/zh-HK/chat.json         |  4 +
 src/renderer/src/i18n/zh-TW/chat.json         |  4 +
 src/renderer/src/lib/iconLoader.ts            |  8 +-
 src/renderer/src/lib/icons/line-md-theme.json | 18 ++++
 25 files changed, 217 insertions(+), 3 deletions(-)
 create mode 100644 src/renderer/src/lib/icons/line-md-theme.json

diff --git a/src/renderer/src/App.vue b/src/renderer/src/App.vue
index 01ad7b561..8bbae8853 100644
--- a/src/renderer/src/App.vue
+++ b/src/renderer/src/App.vue
@@ -91,12 +91,23 @@ const syncAppearanceClasses = (themeName: string, fontSizeClass: string) => {
     return
   }
 
-  for (const target of [document.documentElement, document.body]) {
+  const root = document.documentElement
+  // 切换期间临时禁用过渡，让主题瞬时生效，避免大量元素同时跑颜色过渡造成的重绘卡顿
+  root.classList.add('dc-theme-switching')
+
+  for (const target of [root, document.body]) {
     target.classList.remove('light', 'dark', 'system')
     target.classList.add(themeName)
     target.classList.remove('text-xs', 'text-sm', 'text-base', 'text-lg', 'text-xl', 'text-2xl')
     target.classList.add(fontSizeClass)
   }
+
+  // 强制同步重算，使本次类切换在「过渡已禁用」的状态下完成
+  void root.offsetWidth
+  // 下一帧恢复过渡，不影响日常 hover 等交互动画
+  requestAnimationFrame(() => {
+    root.classList.remove('dc-theme-switching')
+  })
 }
 
 watch(
diff --git a/src/renderer/src/assets/style.css b/src/renderer/src/assets/style.css
index ceedebece..8160ad045 100644
--- a/src/renderer/src/assets/style.css
+++ b/src/renderer/src/assets/style.css
@@ -839,6 +839,14 @@
     outline-color: color-mix(in oklab, var(--ring) 50%, transparent);
   }
 
+  /* 主题切换瞬间临时关闭所有过渡，避免上百个元素同时触发颜色过渡导致的重绘卡顿 */
+  .dc-theme-switching,
+  .dc-theme-switching *,
+  .dc-theme-switching *::before,
+  .dc-theme-switching *::after {
+    transition: none !important;
+  }
+
   body {
     color: var(--foreground);
     font-weight: var(--text-weight);
diff --git a/src/renderer/src/components/WindowSideBar.vue b/src/renderer/src/components/WindowSideBar.vue
index 03fac201e..0a8463eb9 100644
--- a/src/renderer/src/components/WindowSideBar.vue
+++ b/src/renderer/src/components/WindowSideBar.vue
@@ -94,6 +94,26 @@
           </TooltipContent>
         </Tooltip>
 
+        <!-- Theme toggle -->
+        <Tooltip>
+          <TooltipTrigger as-child>
+            <Button
+              data-testid="window-sidebar-theme-toggle"
+              class="flex items-center justify-center w-9 h-9 rounded-xl bg-transparent border-none hover:bg-white/30 dark:hover:bg-white/10 shadow-none"
+              @click="themeStore.cycleTheme()"
+            >
+              <span class="theme-icon-wrap">
+                <Transition name="theme-icon">
+                  <Icon :key="themeIcon" :icon="themeIcon" class="theme-icon text-foreground/90" />
+                </Transition>
+              </span>
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="right">
+            {{ t('chat.sidebar.themeToggle') }} · {{ themeModeLabel }}
+          </TooltipContent>
+        </Tooltip>
+
         <!-- Collapse toggle -->
         <Tooltip>
           <TooltipTrigger as-child>
@@ -391,6 +411,7 @@ import AgentAvatar from './icons/AgentAvatar.vue'
 import WindowSideBarSessionItem from './WindowSideBarSessionItem.vue'
 import { useI18n } from 'vue-i18n'
 import { useSidebarStore } from '@/stores/ui/sidebar'
+import { useThemeStore } from '@/stores/theme'
 
 type PinFeedbackMode = 'pinning' | 'unpinning'
 
@@ -419,6 +440,33 @@ const agentStore = useAgentStore()
 const sessionStore = useSessionStore()
 const sidebarStore = useSidebarStore()
 const spotlightStore = useSpotlightStore()
+const themeStore = useThemeStore()
+
+// line-md 过渡图标自带线条流动动画：切到该模式时，线条会绘制/morph 成对应形状
+const themeIcon = computed(() => {
+  switch (themeStore.themeMode) {
+    case 'light':
+      // 线条流动收拢成太阳（光线逐根画出）
+      return 'line-md:moon-to-sunny-outline-transition'
+    case 'dark':
+      // 太阳线条流动 morph 成月亮
+      return 'line-md:sunny-outline-to-moon-transition'
+    default:
+      // 显示器轮廓线条逐段绘制
+      return 'line-md:monitor'
+  }
+})
+
+const themeModeLabel = computed(() => {
+  switch (themeStore.themeMode) {
+    case 'light':
+      return t('chat.sidebar.themeLight')
+    case 'dark':
+      return t('chat.sidebar.themeDark')
+    default:
+      return t('chat.sidebar.themeSystem')
+  }
+})
 
 const fallbackRemoteChannels: RemoteChannelDescriptor[] = [
   {
@@ -1179,10 +1227,55 @@ input {
   margin-left: var(--pin-text-shift) !important;
 }
 
+.theme-icon-wrap {
+  display: grid;
+  place-items: center;
+  width: 1.15rem;
+  height: 1.15rem;
+}
+
+.theme-icon {
+  /* 两个图标堆叠在同一网格单元，自动居中且不占额外空间 */
+  grid-area: 1 / 1;
+  width: 1.15rem;
+  height: 1.15rem;
+  /* 提升到独立合成层，让过渡跑在 GPU 合成线程上，
+     避免被切换主题时的全局重绘阻塞而掉帧 */
+  will-change: transform, opacity;
+}
+
+/* 形态变化交给 line-md 的线条流动动画；这里再叠加一个缩放"弹出"增强存在感 */
+.theme-icon-enter-active {
+  transition:
+    opacity 0.25s ease,
+    transform 0.35s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+.theme-icon-leave-active {
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease;
+}
+
+.theme-icon-enter-from {
+  opacity: 0;
+  transform: scale(0.4);
+}
+
+.theme-icon-leave-to {
+  opacity: 0;
+  transform: scale(0.7);
+}
+
 @media (prefers-reduced-motion: reduce) {
   .window-sidebar-shell,
   .window-sidebar-session-column {
     transition: none;
   }
+
+  .theme-icon-enter-active,
+  .theme-icon-leave-active {
+    transition: none;
+  }
 }
 </style>
diff --git a/src/renderer/src/i18n/da-DK/chat.json b/src/renderer/src/i18n/da-DK/chat.json
index c9800cecd..1ece7678d 100644
--- a/src/renderer/src/i18n/da-DK/chat.json
+++ b/src/renderer/src/i18n/da-DK/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "Alle agenter",
     "expandSidebar": "Udvid sidepanelet",
     "collapseSidebar": "Skjul sidepanelet",
+    "themeToggle": "Skift tema",
+    "themeLight": "Lys",
+    "themeDark": "Mørk",
+    "themeSystem": "System",
     "remoteControlStatus": {
       "disabled": "Fjernstyring er deaktiveret",
       "stopped": "Fjernstyring er stoppet",
diff --git a/src/renderer/src/i18n/de-DE/chat.json b/src/renderer/src/i18n/de-DE/chat.json
index 62c46e688..a584f9d26 100644
--- a/src/renderer/src/i18n/de-DE/chat.json
+++ b/src/renderer/src/i18n/de-DE/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Alle Agents",
     "expandSidebar": "Seitenleiste ausklappen",
     "collapseSidebar": "Seitenleiste einklappen",
+    "themeToggle": "Thema wechseln",
+    "themeLight": "Hell",
+    "themeDark": "Dunkel",
+    "themeSystem": "System",
     "remoteControlDisabled": "Nicht aktiviert",
     "remoteControlStatus": {
       "disabled": "Fernsteuerung deaktiviert",
diff --git a/src/renderer/src/i18n/en-US/chat.json b/src/renderer/src/i18n/en-US/chat.json
index 74242831c..e5ec4b9e1 100644
--- a/src/renderer/src/i18n/en-US/chat.json
+++ b/src/renderer/src/i18n/en-US/chat.json
@@ -346,6 +346,10 @@
     "allAgents": "All Agents",
     "expandSidebar": "Expand sidebar",
     "collapseSidebar": "Collapse sidebar",
+    "themeToggle": "Toggle theme",
+    "themeLight": "Light",
+    "themeDark": "Dark",
+    "themeSystem": "System",
     "remoteControlDisabled": "Disabled",
     "remoteControlStatus": {
       "disabled": "Remote control disabled",
diff --git a/src/renderer/src/i18n/es-ES/chat.json b/src/renderer/src/i18n/es-ES/chat.json
index ace886bb1..10b836f25 100644
--- a/src/renderer/src/i18n/es-ES/chat.json
+++ b/src/renderer/src/i18n/es-ES/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Todos los Agents",
     "expandSidebar": "Expandir barra lateral",
     "collapseSidebar": "Contraer barra lateral",
+    "themeToggle": "Cambiar tema",
+    "themeLight": "Claro",
+    "themeDark": "Oscuro",
+    "themeSystem": "Sistema",
     "remoteControlDisabled": "Desactivado",
     "remoteControlStatus": {
       "disabled": "Control remoto desactivado",
diff --git a/src/renderer/src/i18n/fa-IR/chat.json b/src/renderer/src/i18n/fa-IR/chat.json
index 24a47d6aa..0d9ae4abb 100644
--- a/src/renderer/src/i18n/fa-IR/chat.json
+++ b/src/renderer/src/i18n/fa-IR/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "همه عامل‌ها",
     "expandSidebar": "گسترش نوار کناری",
     "collapseSidebar": "جمع کردن نوار کناری",
+    "themeToggle": "تغییر پوسته",
+    "themeLight": "روشن",
+    "themeDark": "تیره",
+    "themeSystem": "سیستم",
     "remoteControlStatus": {
       "disabled": "کنترل از راه دور غیرفعال است",
       "stopped": "کنترل از راه دور متوقف شده است",
diff --git a/src/renderer/src/i18n/fr-FR/chat.json b/src/renderer/src/i18n/fr-FR/chat.json
index 3ebbf8add..5cd7d1901 100644
--- a/src/renderer/src/i18n/fr-FR/chat.json
+++ b/src/renderer/src/i18n/fr-FR/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "Tous les agents",
     "expandSidebar": "Développer la barre latérale",
     "collapseSidebar": "Réduire la barre latérale",
+    "themeToggle": "Changer de thème",
+    "themeLight": "Clair",
+    "themeDark": "Sombre",
+    "themeSystem": "Système",
     "remoteControlStatus": {
       "disabled": "Contrôle à distance désactivé",
       "stopped": "Contrôle à distance arrêté",
diff --git a/src/renderer/src/i18n/he-IL/chat.json b/src/renderer/src/i18n/he-IL/chat.json
index 130667210..9efdeb00c 100644
--- a/src/renderer/src/i18n/he-IL/chat.json
+++ b/src/renderer/src/i18n/he-IL/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "כל הסוכנים",
     "expandSidebar": "הרחב את הסרגל הצדדי",
     "collapseSidebar": "כווץ את הסרגל הצדדי",
+    "themeToggle": "החלפת ערכת נושא",
+    "themeLight": "בהיר",
+    "themeDark": "כהה",
+    "themeSystem": "מערכת",
     "remoteControlStatus": {
       "disabled": "בקרה מרחוק מושבתת",
       "stopped": "בקרה מרחוק נעצרה",
diff --git a/src/renderer/src/i18n/id-ID/chat.json b/src/renderer/src/i18n/id-ID/chat.json
index ae19ae58e..19c0047bd 100644
--- a/src/renderer/src/i18n/id-ID/chat.json
+++ b/src/renderer/src/i18n/id-ID/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Semua Agent",
     "expandSidebar": "Luaskan bilah sisi",
     "collapseSidebar": "Ciutkan bilah sisi",
+    "themeToggle": "Ganti tema",
+    "themeLight": "Terang",
+    "themeDark": "Gelap",
+    "themeSystem": "Sistem",
     "remoteControlDisabled": "Tidak diaktifkan",
     "remoteControlStatus": {
       "disabled": "Kendali jarak jauh dinonaktifkan",
diff --git a/src/renderer/src/i18n/it-IT/chat.json b/src/renderer/src/i18n/it-IT/chat.json
index 5d5e9a61f..abbc75b6f 100644
--- a/src/renderer/src/i18n/it-IT/chat.json
+++ b/src/renderer/src/i18n/it-IT/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Tutti gli Agents",
     "expandSidebar": "Espandi barra laterale",
     "collapseSidebar": "Comprimi barra laterale",
+    "themeToggle": "Cambia tema",
+    "themeLight": "Chiaro",
+    "themeDark": "Scuro",
+    "themeSystem": "Sistema",
     "remoteControlDisabled": "Non attivo",
     "remoteControlStatus": {
       "disabled": "Controllo remoto disattivato",
diff --git a/src/renderer/src/i18n/ja-JP/chat.json b/src/renderer/src/i18n/ja-JP/chat.json
index e0ccff46b..794321898 100644
--- a/src/renderer/src/i18n/ja-JP/chat.json
+++ b/src/renderer/src/i18n/ja-JP/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "すべてのエージェント",
     "expandSidebar": "サイドバーを展開",
     "collapseSidebar": "サイドバーを折りたたむ",
+    "themeToggle": "テーマを切り替え",
+    "themeLight": "ライト",
+    "themeDark": "ダーク",
+    "themeSystem": "システム",
     "remoteControlStatus": {
       "disabled": "リモート操作は無効です",
       "stopped": "リモート操作は停止しました",
diff --git a/src/renderer/src/i18n/ko-KR/chat.json b/src/renderer/src/i18n/ko-KR/chat.json
index 19cd8f828..87de40f30 100644
--- a/src/renderer/src/i18n/ko-KR/chat.json
+++ b/src/renderer/src/i18n/ko-KR/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "모든 에이전트",
     "expandSidebar": "사이드바 펼치기",
     "collapseSidebar": "사이드바 접기",
+    "themeToggle": "테마 전환",
+    "themeLight": "라이트",
+    "themeDark": "다크",
+    "themeSystem": "시스템",
     "remoteControlStatus": {
       "disabled": "원격 제어가 비활성화됨",
       "stopped": "원격 제어가 중지됨",
diff --git a/src/renderer/src/i18n/ms-MY/chat.json b/src/renderer/src/i18n/ms-MY/chat.json
index 33f108652..b5060753b 100644
--- a/src/renderer/src/i18n/ms-MY/chat.json
+++ b/src/renderer/src/i18n/ms-MY/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Semua Agents",
     "expandSidebar": "Kembangkan bar sisi",
     "collapseSidebar": "Runtuhkan bar sisi",
+    "themeToggle": "Tukar tema",
+    "themeLight": "Cerah",
+    "themeDark": "Gelap",
+    "themeSystem": "Sistem",
     "remoteControlDisabled": "Tidak didayakan",
     "remoteControlStatus": {
       "disabled": "Alat kawalan jauh dilumpuhkan",
diff --git a/src/renderer/src/i18n/pl-PL/chat.json b/src/renderer/src/i18n/pl-PL/chat.json
index 33b794beb..7b5ce3d39 100644
--- a/src/renderer/src/i18n/pl-PL/chat.json
+++ b/src/renderer/src/i18n/pl-PL/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Wszystkie Agents",
     "expandSidebar": "Rozwiń pasek boczny",
     "collapseSidebar": "Zwiń pasek boczny",
+    "themeToggle": "Przełącz motyw",
+    "themeLight": "Jasny",
+    "themeDark": "Ciemny",
+    "themeSystem": "System",
     "remoteControlDisabled": "Niepełnosprawny",
     "remoteControlStatus": {
       "disabled": "Zdalne sterowanie wyłączone",
diff --git a/src/renderer/src/i18n/pt-BR/chat.json b/src/renderer/src/i18n/pt-BR/chat.json
index c1a20a26e..f0ca7ed34 100644
--- a/src/renderer/src/i18n/pt-BR/chat.json
+++ b/src/renderer/src/i18n/pt-BR/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "Todos os agentes",
     "expandSidebar": "Expandir barra lateral",
     "collapseSidebar": "Recolher barra lateral",
+    "themeToggle": "Alternar tema",
+    "themeLight": "Claro",
+    "themeDark": "Escuro",
+    "themeSystem": "Sistema",
     "remoteControlStatus": {
       "disabled": "Controle remoto desativado",
       "stopped": "Controle remoto parado",
diff --git a/src/renderer/src/i18n/ru-RU/chat.json b/src/renderer/src/i18n/ru-RU/chat.json
index 0c48182d6..5fc83ae40 100644
--- a/src/renderer/src/i18n/ru-RU/chat.json
+++ b/src/renderer/src/i18n/ru-RU/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "Все агенты",
     "expandSidebar": "Развернуть боковую панель",
     "collapseSidebar": "Свернуть боковую панель",
+    "themeToggle": "Сменить тему",
+    "themeLight": "Светлая",
+    "themeDark": "Тёмная",
+    "themeSystem": "Системная",
     "remoteControlStatus": {
       "disabled": "Удалённое управление отключено",
       "stopped": "Удалённое управление остановлено",
diff --git a/src/renderer/src/i18n/tr-TR/chat.json b/src/renderer/src/i18n/tr-TR/chat.json
index 307e4f9b9..ae7847fba 100644
--- a/src/renderer/src/i18n/tr-TR/chat.json
+++ b/src/renderer/src/i18n/tr-TR/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Hepsi Agent",
     "expandSidebar": "Kenar çubuğunu genişlet",
     "collapseSidebar": "Kenar çubuğunu daralt",
+    "themeToggle": "Temayı değiştir",
+    "themeLight": "Açık",
+    "themeDark": "Koyu",
+    "themeSystem": "Sistem",
     "remoteControlDisabled": "Engelli",
     "remoteControlStatus": {
       "disabled": "Uzaktan kumanda devre dışı",
diff --git a/src/renderer/src/i18n/vi-VN/chat.json b/src/renderer/src/i18n/vi-VN/chat.json
index c4323c5ea..c614876e1 100644
--- a/src/renderer/src/i18n/vi-VN/chat.json
+++ b/src/renderer/src/i18n/vi-VN/chat.json
@@ -327,6 +327,10 @@
     "allAgents": "Tất cả Agents",
     "expandSidebar": "Mở rộng thanh bên",
     "collapseSidebar": "Thu gọn thanh bên",
+    "themeToggle": "Đổi giao diện",
+    "themeLight": "Sáng",
+    "themeDark": "Tối",
+    "themeSystem": "Hệ thống",
     "remoteControlDisabled": "Đã tắt",
     "remoteControlStatus": {
       "disabled": "Điều khiển từ xa bị vô hiệu hóa",
diff --git a/src/renderer/src/i18n/zh-CN/chat.json b/src/renderer/src/i18n/zh-CN/chat.json
index b50b278f2..b085240c5 100644
--- a/src/renderer/src/i18n/zh-CN/chat.json
+++ b/src/renderer/src/i18n/zh-CN/chat.json
@@ -346,6 +346,10 @@
     "allAgents": "所有 Agents",
     "expandSidebar": "展开侧边栏",
     "collapseSidebar": "收起侧边栏",
+    "themeToggle": "切换主题",
+    "themeLight": "浅色",
+    "themeDark": "深色",
+    "themeSystem": "跟随系统",
     "remoteControlDisabled": "未启用",
     "remoteControlStatus": {
       "disabled": "远程控制已禁用",
diff --git a/src/renderer/src/i18n/zh-HK/chat.json b/src/renderer/src/i18n/zh-HK/chat.json
index 1e2e6e60c..d12e37dd7 100644
--- a/src/renderer/src/i18n/zh-HK/chat.json
+++ b/src/renderer/src/i18n/zh-HK/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "所有 Agents",
     "expandSidebar": "展開側邊欄",
     "collapseSidebar": "收起側邊欄",
+    "themeToggle": "切換主題",
+    "themeLight": "淺色",
+    "themeDark": "深色",
+    "themeSystem": "跟隨系統",
     "remoteControlStatus": {
       "disabled": "遠程控制已停用",
       "stopped": "遠程控制已停止",
diff --git a/src/renderer/src/i18n/zh-TW/chat.json b/src/renderer/src/i18n/zh-TW/chat.json
index 9d9d81639..57f489f6b 100644
--- a/src/renderer/src/i18n/zh-TW/chat.json
+++ b/src/renderer/src/i18n/zh-TW/chat.json
@@ -311,6 +311,10 @@
     "allAgents": "所有 Agents",
     "expandSidebar": "展開側邊欄",
     "collapseSidebar": "收起側邊欄",
+    "themeToggle": "切換主題",
+    "themeLight": "淺色",
+    "themeDark": "深色",
+    "themeSystem": "跟隨系統",
     "remoteControlStatus": {
       "disabled": "遠端控制已停用",
       "stopped": "遠端控制已停止",
diff --git a/src/renderer/src/lib/iconLoader.ts b/src/renderer/src/lib/iconLoader.ts
index 173ad46ae..4908e3412 100644
--- a/src/renderer/src/lib/iconLoader.ts
+++ b/src/renderer/src/lib/iconLoader.ts
@@ -5,6 +5,7 @@
 
 import type lucideIconsType from '@iconify-json/lucide/icons.json'
 import type vscodeIconsType from '@iconify-json/vscode-icons/icons.json'
+import type lineMdThemeIconsType from './icons/line-md-theme.json'
 
 interface IconLoadState {
   isLoading: boolean
@@ -38,12 +39,13 @@ export async function ensureIconsLoaded(): Promise<void> {
   state.loadPromise = (async () => {
     try {
       // 动态导入 icon 数据和 addCollection，延迟加载
-      const [{ addCollection }, lucideIcons, vscodeIcons] = await Promise.all([
+      const [{ addCollection }, lucideIcons, vscodeIcons, lineMdThemeIcons] = await Promise.all([
         import('@iconify/vue').then((m) => ({ addCollection: m.addCollection })),
         import('@iconify-json/lucide/icons.json').then((m) => m.default as typeof lucideIconsType),
         import('@iconify-json/vscode-icons/icons.json').then(
           (m) => m.default as typeof vscodeIconsType
-        )
+        ),
+        import('./icons/line-md-theme.json').then((m) => m.default as typeof lineMdThemeIconsType)
       ])
 
       // 检查 addCollection 是否存在（可能在测试中被mock）
@@ -51,6 +53,8 @@ export async function ensureIconsLoaded(): Promise<void> {
         // 添加到 Iconify 注册表
         addCollection(lucideIcons)
         addCollection(vscodeIcons)
+        // line-md 主题切换图标（自带线条流动过渡动画，离线可用）
+        addCollection(lineMdThemeIcons)
       }
 
       state.isLoaded = true
diff --git a/src/renderer/src/lib/icons/line-md-theme.json b/src/renderer/src/lib/icons/line-md-theme.json
new file mode 100644
index 000000000..aec1b6070
--- /dev/null
+++ b/src/renderer/src/lib/icons/line-md-theme.json
@@ -0,0 +1,18 @@
+{
+  "prefix": "line-md",
+  "lastModified": 1767255360,
+  "aliases": {},
+  "width": 24,
+  "height": 24,
+  "icons": {
+    "sunny-outline-to-moon-transition": {
+      "body": "<defs><mask id=\"SVGHXYFDcmX\"><path fill=\"#fff\" d=\"M12 2c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M12 6c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6Z;M12 2c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path><path d=\"M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10ZM12 4c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6ZM12 8c2.21 0 4 1.79 4 4c0 2.21 -1.79 4 -4 4c-2.21 0 -4 -1.79 -4 -4c0 -2.21 1.79 -4 4 -4Z;M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10ZM12 4c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path></mask><mask id=\"SVGYzLhkdyh\"><path fill=\"#fff\" d=\"M18 -6c6.62 0 12 5.38 12 12c0 6.62 -5.38 12 -12 12c-6.62 0 -12 -5.38 -12 -12c0 -6.62 5.38 -12 12 -12Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M22 -6c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z;M18 -6c6.62 0 12 5.38 12 12c0 6.62 -5.38 12 -12 12c-6.62 0 -12 -5.38 -12 -12c0 -6.62 5.38 -12 12 -12Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path><path d=\"M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10ZM2 12v-20h30v30h-20c5.52 0 10 -4.48 10 -10c0 -5.52 -4.48 -10 -10 -10c-5.52 0 -10 4.48 -10 10Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6ZM6 12v-20h26v26h-20c3.31 0 6 -2.69 6 -6c0 -3.31 -2.69 -6 -6 -6c-3.31 0 -6 2.69 -6 6Z;M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10ZM2 12v-20h30v30h-20c5.52 0 10 -4.48 10 -10c0 -5.52 -4.48 -10 -10 -10c-5.52 0 -10 4.48 -10 10Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path></mask></defs><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 21v1M21 12h1M12 3v-1M3 12h-1M18.5 18.5l0.5 0.5M18.5 5.5l0.5 -0.5M5.5 5.5l-0.5 -0.5M5.5 18.5l-0.5 0.5\"><animate fill=\"freeze\" attributeName=\"opacity\" dur=\"0.68s\" values=\"1;0\"/></path><g fill=\"currentColor\"><path d=\"M0 0h24v24H0z\" mask=\"url(#SVGHXYFDcmX)\"/><path d=\"M0 0h24v24H0z\" mask=\"url(#SVGYzLhkdyh)\"/></g><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M7 6c0 6.08 4.92 11 11 11c0.53 0 1.05 -0.04 1.56 -0.11c-1.61 2.47 -4.39 4.11 -7.56 4.11c-4.97 0 -9 -4.03 -9 -9c0 -3.17 1.64 -5.95 4.11 -7.56c-0.07 0.51 -0.11 1.03 -0.11 1.56Z\" opacity=\"0\"><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"1\"/></path><g fill=\"currentColor\"><path d=\"M15.22 6.03l2.53 -1.94l-3.19 -0.09l-1.06 -3l-1.06 3l-3.19 0.09l2.53 1.94l-0.91 3.06l2.63 -1.81l2.63 1.81l-0.91 -3.06Z\" opacity=\"0\"><animate fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" dur=\"0.68s\" to=\"1\"/></path><path d=\"M19.61 12.25l1.64 -1.25l-2.06 -0.05l-0.69 -1.95l-0.69 1.95l-2.06 0.05l1.64 1.25l-0.59 1.98l1.7 -1.17l1.7 1.17l-0.59 -1.98Z\" opacity=\"0\"><animate fill=\"freeze\" attributeName=\"opacity\" begin=\"1.36s\" dur=\"0.68s\" to=\"1\"/></path></g>"
+    },
+    "moon-to-sunny-outline-transition": {
+      "body": "<defs><mask id=\"SVGUXuaaerw\"><path fill=\"#fff\" d=\"M12 6c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M12 2c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10Z;M12 6c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6Z\"/></path><path d=\"M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10Z;M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path><path d=\"M12 8c2.21 0 4 1.79 4 4c0 2.21 -1.79 4 -4 4c-2.21 0 -4 -1.79 -4 -4c0 -2.21 1.79 -4 4 -4Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M12 4c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z;M12 8c2.21 0 4 1.79 4 4c0 2.21 -1.79 4 -4 4c-2.21 0 -4 -1.79 -4 -4c0 -2.21 1.79 -4 4 -4Z\"/></path></mask><mask id=\"SVGjqg97bFZ\"><path fill=\"#fff\" d=\"M22 -6c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M18 -6c6.62 0 12 5.38 12 12c0 6.62 -5.38 12 -12 12c-6.62 0 -12 -5.38 -12 -12c0 -6.62 5.38 -12 12 -12Z;M22 -6c4.42 0 8 3.58 8 8c0 4.42 -3.58 8 -8 8c-4.42 0 -8 -3.58 -8 -8c0 -4.42 3.58 -8 8 -8Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path><path d=\"M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6ZM6 12v-20h26v26h-20c3.31 0 6 -2.69 6 -6c0 -3.31 -2.69 -6 -6 -6c-3.31 0 -6 2.69 -6 6Z\"><animate fill=\"freeze\" attributeName=\"d\" dur=\"0.68s\" values=\"M18 -4c5.52 0 10 4.48 10 10c0 5.52 -4.48 10 -10 10c-5.52 0 -10 -4.48 -10 -10c0 -5.52 4.48 -10 10 -10ZM2 12v-20h30v30h-20c5.52 0 10 -4.48 10 -10c0 -5.52 -4.48 -10 -10 -10c-5.52 0 -10 4.48 -10 10Z;M22 -4c3.31 0 6 2.69 6 6c0 3.31 -2.69 6 -6 6c-3.31 0 -6 -2.69 -6 -6c0 -3.31 2.69 -6 6 -6ZM6 12v-20h26v26h-20c3.31 0 6 -2.69 6 -6c0 -3.31 -2.69 -6 -6 -6c-3.31 0 -6 2.69 -6 6Z\"/><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"0\"/></path></mask></defs><g fill=\"currentColor\"><path d=\"M0 0h24v24H0z\" mask=\"url(#SVGUXuaaerw)\"/><path d=\"M0 0h24v24H0z\" mask=\"url(#SVGjqg97bFZ)\"/></g><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 21v1M21 12h1M12 3v-1M3 12h-1\" opacity=\"0\"><set fill=\"freeze\" attributeName=\"opacity\" begin=\"0.68s\" to=\"1\"/><animate fill=\"freeze\" attributeName=\"d\" begin=\"0.68s\" dur=\"0.34s\" values=\"M12 19v1M19 12h1M12 5v-1M5 12h-1;M12 21v1M21 12h1M12 3v-1M3 12h-1\"/></path><path d=\"M18.5 18.5l0.5 0.5M18.5 5.5l0.5 -0.5M5.5 5.5l-0.5 -0.5M5.5 18.5l-0.5 0.5\" opacity=\"0\"><set fill=\"freeze\" attributeName=\"opacity\" begin=\"1.02s\" to=\"1\"/><animate fill=\"freeze\" attributeName=\"d\" begin=\"1.02s\" dur=\"0.34s\" values=\"M17 17l0.5 0.5M17 7l0.5 -0.5M7 7l-0.5 -0.5M7 17l-0.5 0.5;M18.5 18.5l0.5 0.5M18.5 5.5l0.5 -0.5M5.5 5.5l-0.5 -0.5M5.5 18.5l-0.5 0.5\"/></path></g>"
+    },
+    "monitor": {
+      "body": "<path fill=\"none\" stroke=\"currentColor\" stroke-dasharray=\"70\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 17h-10v-14h20v14Z\"><animate fill=\"freeze\" attributeName=\"stroke-dashoffset\" dur=\"1.02s\" values=\"70;0\"/></path><path fill=\"currentColor\" d=\"M10 16h4v0h-4Z\"><animate fill=\"freeze\" attributeName=\"d\" begin=\"1.02s\" dur=\"0.34s\" to=\"M10 16h4v6h-4Z\"/></path><path fill=\"none\" stroke=\"currentColor\" stroke-dasharray=\"6\" stroke-dashoffset=\"6\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 21h3M12 21h-3\"><animate fill=\"freeze\" attributeName=\"stroke-dashoffset\" begin=\"1.36s\" dur=\"0.68s\" to=\"0\"/></path>"
+    }
+  }
+}

From 2b02b7c2869d3d9cdcf55127c58151ac746540a8 Mon Sep 17 00:00:00 2001
From: duskzhen <zerob13@gmail.com>
Date: Tue, 2 Jun 2026 14:44:31 +0800
Subject: [PATCH 3/8] feat(acp): harden v1 protocol support (#1724)

* docs(acp): add v1 reliability plan

* feat(acp): harden v1 protocol support

* fix(acp): harden session workdirs

* fix(acp): address pr review notes

* fix(acp): skip warmup for missing workdir

* fix(acp): revalidate debug workdir

* fix(acp): clear stale permission modal

* refactor(acp): simplify stale permission flow
---
 docs/features/acp-v1-reliability/plan.md      | 357 ++++++++++++++
 docs/features/acp-v1-reliability/spec.md      |  93 ++++
 docs/features/acp-v1-reliability/tasks.md     | 149 ++++++
 .../presenter/agentRuntimePresenter/index.ts  |  91 +++-
 .../acp/acpCapabilities.ts                    |  50 ++
 .../acp/acpContentMapper.ts                   |  40 +-
 .../acp/acpMessageFormatter.ts                | 237 ++++++---
 .../acp/acpProcessManager.ts                  | 147 +++++-
 .../acp/acpSessionManager.ts                  | 109 ++++-
 .../acp/acpSessionPersistence.ts              | 334 ++++++++++++-
 .../acp/acpTerminalManager.ts                 |  49 +-
 .../llmProviderPresenter/acp/index.ts         |   7 +-
 .../presenter/llmProviderPresenter/index.ts   |  13 +-
 .../providers/acpProvider.ts                  | 378 ++++++++++++++-
 src/main/presenter/sqlitePresenter/index.ts   |   8 +
 .../sqlitePresenter/tables/acpSessions.ts     |  69 ++-
 .../settings/components/AcpDebugDialog.vue    |  83 +++-
 src/renderer/src/i18n/da-DK/settings.json     |   5 +
 src/renderer/src/i18n/de-DE/settings.json     |   5 +
 src/renderer/src/i18n/en-US/settings.json     |   7 +-
 src/renderer/src/i18n/es-ES/settings.json     |   5 +
 src/renderer/src/i18n/fa-IR/settings.json     |   5 +
 src/renderer/src/i18n/fr-FR/settings.json     |   5 +
 src/renderer/src/i18n/he-IL/settings.json     |   5 +
 src/renderer/src/i18n/id-ID/settings.json     |   5 +
 src/renderer/src/i18n/it-IT/settings.json     |   5 +
 src/renderer/src/i18n/ja-JP/settings.json     |   5 +
 src/renderer/src/i18n/ko-KR/settings.json     |   5 +
 src/renderer/src/i18n/ms-MY/settings.json     |   5 +
 src/renderer/src/i18n/pl-PL/settings.json     |   5 +
 src/renderer/src/i18n/pt-BR/settings.json     |   5 +
 src/renderer/src/i18n/ru-RU/settings.json     |   5 +
 src/renderer/src/i18n/tr-TR/settings.json     |   5 +
 src/renderer/src/i18n/vi-VN/settings.json     |   5 +
 src/renderer/src/i18n/zh-CN/settings.json     |   7 +-
 src/renderer/src/i18n/zh-HK/settings.json     |   5 +
 src/renderer/src/i18n/zh-TW/settings.json     |   5 +
 .../types/presenters/legacy.presenters.d.ts   |   9 +
 test/main/presenter/acpProvider.test.ts       | 400 ++++++++++++++++
 .../agentRuntimePresenter.test.ts             |  58 +++
 .../acp/acpProcessManager.test.ts             |  76 ++-
 .../acp/acpProcessManagerCapabilities.test.ts | 123 +++++
 .../acp/acpTerminalManager.test.ts            |  59 ++-
 .../acpCapabilities.test.ts                   |  54 ++-
 .../acpContentMapper.test.ts                  |  42 ++
 .../acpMessageFormatter.test.ts               | 105 ++++
 .../acpSessionPersistence.test.ts             | 450 ++++++++++++++++++
 .../sqlitePresenter/acpSessions.test.ts       | 103 ++++
 48 files changed, 3588 insertions(+), 209 deletions(-)
 create mode 100644 docs/features/acp-v1-reliability/plan.md
 create mode 100644 docs/features/acp-v1-reliability/spec.md
 create mode 100644 docs/features/acp-v1-reliability/tasks.md
 create mode 100644 test/main/presenter/llmProviderPresenter/acp/acpProcessManagerCapabilities.test.ts
 create mode 100644 test/main/presenter/llmProviderPresenter/acpMessageFormatter.test.ts
 create mode 100644 test/main/presenter/llmProviderPresenter/acpSessionPersistence.test.ts
 create mode 100644 test/main/presenter/sqlitePresenter/acpSessions.test.ts

diff --git a/docs/features/acp-v1-reliability/plan.md b/docs/features/acp-v1-reliability/plan.md
new file mode 100644
index 000000000..9b509f829
--- /dev/null
+++ b/docs/features/acp-v1-reliability/plan.md
@@ -0,0 +1,357 @@
+# ACP v1 Reliability Implementation Plan
+
+## 总体策略
+
+本次不重写 ACP 子系统，而是在现有模块上补齐协议边界和状态闭环：
+
+- `acpProcessManager.ts` 负责 launch、initialize、client method dispatch、capability snapshot、debug log、session update buffer。
+- `acpSessionManager.ts` 负责 `new/load/resume/close/list` 的选择、持久化、listener 注册和 terminal/session cleanup。
+- `acpProvider.ts` 负责 chat turn、debug action、renderer 状态事件和 DeepChat stream event 输出。
+- `acpMessageFormatter.ts`、`acpContentMapper.ts`、`acpTerminalManager.ts`、`acpFsHandler.ts` 分别收口 prompt、update、terminal、fs 规范。
+- shared contracts / presenter types 只增加必要字段，不新增并行的 ACP 框架。
+
+推荐分 5 个可 review 增量落地：capabilities/auth、session lifecycle、prompt/content/update、terminal/fs、UI diagnostics + E2E matrix。
+
+数据所有权原则：DeepChat conversation/message records 是事实源。ACP agent session 是外部 session catalog 和运行时上下文，进入 DeepChat 后必须先形成本地 link，再转换、去重、持久化为 DeepChat 自己的消息和 metadata。
+
+## Runtime Flow
+
+```text
+Registry/Local command
+        |
+        v
+Launch subprocess + JSON-RPC stdio
+        |
+        v
+initialize(protocolVersion, clientCapabilities, clientInfo)
+        |
+        +--> auth required? --> authenticate/logout/debug/UI
+        |
+        v
+resolve DeepChat conversation:
+  existing AcpSessionLink -> resume/load remote context
+  imported remote session -> attach link + optional load import
+  new local conversation -> session/new remote context
+        |
+        v
+bind listener + flush buffered session/update
+        |
+        v
+session/prompt(current user content blocks)
+        |
+        v
+session/update -> mapper -> stream events + state + debug log
+        |
+        v
+cancel/detach/explicit remote close/release terminals/process cleanup
+```
+
+## Data Ownership and Sync Model
+
+DeepChat 不把远端 agent session 当作本地数据库的事实源。远端 session 只提供三类信息：
+
+- catalog：`session/list` 返回的 sessionId、cwd、title、updatedAt、`_meta`。
+- replay：`session/load` 可能重放历史 update，用于导入远端历史。
+- runtime context：`session/resume` 或 `session/new` 后承接新的 prompt turn。
+
+本地用一个 link 记录 DeepChat conversation 与远端 ACP session 的关系：
+
+```typescript
+interface AcpSessionLink {
+  conversationId: string
+  agentId: string
+  canonicalWorkdir: string
+  remoteSessionId: string
+  remoteTitle?: string
+  remoteUpdatedAt?: string
+  lastImportedRemoteUpdatedAt?: string
+  lastImportFingerprint?: string
+  importedMessageFingerprints: string[]
+  syncState: 'cataloged' | 'imported' | 'attached' | 'stale' | 'error'
+}
+```
+
+约束：
+
+- 稳定去重 key 是 `agentId + canonicalWorkdir + remoteSessionId`。
+- `session/list` 只更新 catalog/link metadata，不创建重复 DeepChat conversation。
+- 用户选择导入时，如果 link 已存在，打开/更新已有 DeepChat conversation；如果不存在，创建本地 conversation 并写 link。
+- `session/load` 重放内容先进入 staging buffer；转换为 DeepChat message/block 后，再按 message fingerprint 落库。
+- fingerprint 使用远端 session id、update type、role/channel、规范化 content、tool id、turn boundary 等字段生成；没有足够字段时仍要在同一次 import 内去重。
+- `session_info_update` 只更新 link metadata；本地会话标题只有在“自动标题”状态下才可被建议更新。
+- 本地删除或关闭 conversation 默认只 detach link，不调用远端 `session/close`。
+- 默认只有两种情况写远端 session：用户在已绑定 conversation 中继续发送 prompt；用户显式选择 `Close Remote Session`。
+- 普通 app shutdown、conversation close、process cleanup 只释放本地 handle/listener/terminal，不自动调用远端 `session/close`。
+
+## Protocol 对接设计
+
+### 1. Transports and Registry Launch
+
+- 保持 registry launch spec 为首选：binary > npx > uvx 的现有顺序不变。
+- 在 diagnostics 中显示实际 command、args count、distribution type、registry version、local/global version hint。
+- 每个初始化、认证、list/resume/close probe 都必须带 timeout；timeout 后清理子进程和其子进程树。
+- MCP transport 继续按 `mcpCapabilities` 过滤：`stdio` 默认可用，`http`/`sse` 仅 agent 声明后启用。
+- 对 Claude/Codex 这种可能拉起二级 CLI 的 wrapper，E2E probe 需要固定短超时和 cleanup 审计，避免残留进程。
+
+### 2. Initialization and Capability Snapshot
+
+新增一个轻量 snapshot 类型，挂在现有 process handle 上，不新增独立 manager：
+
+```typescript
+interface AcpCapabilitySnapshot {
+  protocolVersion: number
+  agentInfo?: schema.AgentInfo
+  agentCapabilities?: schema.AgentCapabilities
+  sessionCapabilities?: schema.SessionCapabilities
+  promptCapabilities?: schema.PromptCapabilities
+  authMethods: schema.AuthMethod[]
+  mcpCapabilities?: schema.McpCapabilities
+  supports: {
+    loadSession: boolean
+    sessionList: boolean
+    sessionResume: boolean
+    sessionClose: boolean
+    sessionFork: boolean
+    authLogout: boolean
+  }
+}
+```
+
+- `buildClientCapabilities` 只声明 DeepChat 已真实支持的能力。
+- 首轮实现中，`fs`、`terminal` 继续声明；`auth.terminal` 只能在 terminal auth flow 完成后声明。
+- 初始化失败分三类展示：protocol version mismatch、process exited、timeout。
+- 初始化返回的 `models`、`modes`、`configOptions` 统一走 `normalizeAcpConfigState`，并发布 ready event。
+
+### 3. Authentication and Logout
+
+认证入口分三层：
+
+- Presenter/debug：`authenticate(agentId, methodId, workdir?)`、`logout(agentId, workdir?)`。
+- Settings/diagnostics UI：展示 auth methods，并提供 Authenticate 按钮。
+- Chat flow：遇到 ACP auth required 错误时，停止当前 turn，展示可操作的 auth state。
+
+各 auth method 处理方式：
+
+| Auth type | 对接方式 |
+| --- | --- |
+| `agent` 或默认类型 | 直接调用 `connection.authenticate({ methodId })`，成功后刷新 status；失败保留错误详情 |
+| `env_var` | 在 agent settings 中标出必需 env var；缺失时不启动 prompt；设置后重启 agent 并重新 initialize |
+| `terminal` | 在 DeepChat 控制的 terminal/auth runner 中执行 agent 指定流程；完成后重新 initialize；只有该能力完成后才声明 `auth.terminal=true` |
+
+`logout` 只在 `agentCapabilities.auth.logout` 存在时启用。logout 成功后关闭或失效当前 ACP session handle，避免继续使用旧认证上下文。
+
+### 4. Session Lifecycle and Import
+
+`acpSessionManager` 增加 capability-gated lifecycle：
+
+- `listSessions(agentId, cwd?, cursor?)`：循环读取分页，按 workspace 同步 external catalog。
+- `importSession(agentId, remoteSessionId, cwd)`：创建或复用 DeepChat conversation，写入 `AcpSessionLink`。
+- `resumeSession(agentId, remoteSessionId, cwd)`：仅用于已绑定 conversation 的运行时上下文恢复。
+- `detachSessionLink(conversationId)`：解除本地 link，不写远端。
+- `closeRemoteSession(agentId, remoteSessionId)`：仅用户显式操作或活跃 runtime cleanup 时调用。
+- `loadSession(agentId, remoteSessionId, cwd)`：用于远端历史重放导入。
+- `newSession(agentId, cwd, mcpServers)`：只在新的 DeepChat conversation 需要远端上下文时调用。
+
+本地 conversation 打开后的远端上下文恢复优先级固定为：
+
+```text
+existing AcpSessionLink + supports.sessionResume -> session/resume
+existing AcpSessionLink + supports.loadSession    -> session/load for import/replay, then attach
+no AcpSessionLink                                 -> session/new
+```
+
+清理策略：
+
+- 用户停止当前生成：只调用 `session/cancel`。
+- 用户关闭本地 conversation：默认 detach link，不调用远端 close。
+- 用户显式关闭远端 session：若支持 `session/close`，调用 close；然后 release terminal/listener；最后更新 link state。
+- agent process 异常退出：标记 handle unhealthy，清理 listener/terminal，不删除用户可恢复的 session id。
+- `sessionCapabilities.fork` 先做 debug-only，只有 capability 存在时开放，不进入主聊天流程。
+
+导入策略：
+
+- `session/list` 结果只写 external catalog，不直接生成 messages。
+- `session/load` 重放用于导入历史；导入过程先汇总成 DeepChat turn，再落库。
+- 已导入过的远端 session 再次同步时，先比较 `remoteUpdatedAt` 和 `lastImportedRemoteUpdatedAt`；未变化则跳过。
+- 即使 `updatedAt` 变化，也必须用 message fingerprint 去重，避免重复导入相同 replay 内容。
+- 新 prompt turn 由 DeepChat 产生并持久化；agent response 通过 mapper 转换后追加到同一个本地 conversation。
+
+### 5. Session Update Buffer
+
+当前风险是 `session/new` 返回前后，agent 已经发送 `session/update`，但 DeepChat listener 尚未注册，导致 commands/modes/config 早期状态丢失。
+
+修复方式：
+
+- `dispatchSessionUpdate` 找不到 listener 时，不立即 drop；按 `sessionId` 写入短期 buffer。
+- buffer 带 TTL 和最大条数，例如 30 秒、每 session 100 条，避免异常 agent 无限占内存。
+- `registerSessionListener(sessionId, ...)` 后立即 flush buffer，并保留原始顺序。
+- 如果 TTL 过期仍无 listener，再写 debug warning 并丢弃。
+
+### 6. Prompt Turn and Content Mapping
+
+`acpMessageFormatter` 改成当前 turn only：
+
+- 从 DeepChat messages 中提取最后一个 user message。
+- 不再把完整历史拼成 `USER:`/`ASSISTANT:` 文本。
+- 不再把 temperature、maxTokens 注入 prompt 文本。
+- 若 DeepChat session 有 system prompt，只在本地 conversation 首次绑定远端 runtime 时作为 context text 发送一次。
+- 每个 content block 先判断 agent `promptCapabilities`，不支持则降级。
+
+输入映射策略：
+
+| DeepChat content | ACP content |
+| --- | --- |
+| text | `text` |
+| local/remote URL attachment | `resource_link` |
+| base64 image + image supported | `image` |
+| image unsupported | `resource_link` 或文本 fallback |
+| audio + audio supported | `audio` |
+| audio unsupported | 文本 fallback |
+| embedded file/context + embeddedContext supported | `resource` 或 text context |
+
+输出映射策略：
+
+- `agent_message_chunk` -> text stream + content block。
+- `agent_thought_chunk` -> reasoning stream + reasoning block。
+- image/audio/resource/resource_link 尽量保留结构；UI 暂不支持的类型转可读文本，不丢 debug payload。
+- `usage_update` -> turn metadata + debug log；后续可在状态栏展示。
+- `session_info_update` -> `AcpSessionLink` metadata；自动标题可以更新，用户手工标题不覆盖。
+
+### 7. Tool Calls and Permission
+
+工具调用保持现有 mapper，但修正语义：
+
+- `tool_call` 表示工具生命周期，不默认当作权限请求。
+- 只有 ACP `session/request_permission` 才进入 DeepChat permission overlay。
+- `tool_call_update.content` 中的 `terminal`、`diff`、`content`、`locations`、raw input/output 都保留到 block extra/debug。
+- permission resolver 增加 timeout 默认 outcome，用户取消或窗口关闭时返回 cancelled。
+- remote control 侧沿用现有 permission/question 交互模型。
+
+### 8. File System
+
+`acpFsHandler` 当前方向正确，计划以测试加固为主：
+
+- read/write 继续要求 session workdir 已注册。
+- 路径必须在允许 workspace 内；跨 workspace 写入拒绝。
+- line number 按 1-based 处理。
+- binary file、超大文件、无权限路径给结构化错误。
+- `clientCapabilities.fs` 只有 handler 可用时声明；handler 初始化失败时不声明。
+
+### 9. Terminals
+
+`acpTerminalManager` 需要改协议细节：
+
+- `terminal/create` 用 `params.command` + `params.args` 直接 spawn，不拼接 shell 字符串。
+- Windows 不默认包 `powershell.exe -Command`；只有 agent 明确要求 shell 时，command 本身就是 shell。
+- `params.cwd` 必须 resolve 到允许 workspace 或明确的 fallback；fallback 只能用于无 cwd 的 agent 兼容，并写 warning。
+- `outputByteLimit` 超限时从 buffer 开头裁掉，保留最新输出；裁剪必须在 UTF-8 字符边界。
+- `terminal/output` 返回当前 buffer、`truncated`、`exitStatus`。
+- `kill` 幂等；`release` 释放 PTY 资源但不删除已进入 chat block/debug log 的输出。
+
+### 10. Plan, Modes, Config Options, Slash Commands
+
+- `plan` update 每次替换当前 plan entries，避免重复追加。
+- `current_mode_update` 同步 ChatStatusBar 当前 mode。
+- `session/set_mode` 继续作为 legacy mode 能力；若 agent 用 config options 暴露 mode，UI 统一展示在 config options 区。
+- `config_option_update` 要覆盖 initialize/new/load/resume 后的所有路径。
+- `available_commands_update` 进入 active session state；输入框 slash suggestions 使用该 state。
+- 用户输入 `/command arg` 仍走普通 `session/prompt`，不新增 agent-specific command RPC。
+
+### 11. Extensibility
+
+- 所有 official update type 必须有已知处理或显式 ignored reason。
+- `_meta` 保留在 diagnostics/session metadata 中，不随意解析成业务字段。
+- 自定义 extension method/notification 继续走现有 ext debug action；名称必须保持下划线前缀约束。
+- 未知 custom update 不打断 turn，只进入 debug log。
+
+## Shared Types and IPC Surface
+
+优先扩展已有 shared presenter/debug 类型：
+
+- `AcpDebugActionType` 增加 `authenticate`、`logout`、`sessionList`、`sessionImport`、`sessionResume`、`sessionDetach`、`sessionCloseRemote`、`sessionFork`。
+- 增加 renderer-safe status payload：`authMethods`、`authRequired`、`capabilities`、`externalSessions`、`sessionLinks`、`lastUsage`、`lastSessionInfo`。
+- 新 typed route/client 用于 Settings/diagnostics 查询 ACP status 和执行 auth/session debug action；legacy presenter 只保留兼容。
+- 所有用户可见 label/error 走 `src/renderer/src/i18n`。
+
+## UI/UX
+
+Settings 中 ACP agent 详情页增加一个紧凑 diagnostics 区，不做独立大页面：
+
+```text
+ACP Agent Detail
++--------------------------------------------------+
+| DimCode                              Ready  v1    |
+| Auth: Not required   FS: on  Terminal: on         |
+| Sessions: list/resume/close   Prompt: image       |
++--------------------------------------------------+
+| [Authenticate] [Sync Sessions] [Run Diagnostics] |
++--------------------------------------------------+
+| Workspace sessions                                |
+|  New Session          2026-06-02 10:10 [Import]  |
+|  Refactor Thread      linked            [Open]   |
++--------------------------------------------------+
+| Last update                                        |
+|  available_commands_update: /web, /init           |
++--------------------------------------------------+
+```
+
+ChatStatusBar 保持紧凑：
+
+```text
++--------------------------------------------------+
+| ACP: DimCode | Mode: Agent | Model: MiMo | / cmds |
++--------------------------------------------------+
+```
+
+错误态：
+
+```text
++--------------------------------------------------+
+| ACP auth required: Claude Login                  |
+| [Authenticate] [Open Diagnostics]                |
++--------------------------------------------------+
+```
+
+## Test Strategy
+
+Unit tests:
+
+- capability snapshot parser：完整/缺失/未知字段。
+- initialize client capabilities：auth terminal 声明受实现开关控制。
+- session lifecycle gate：无 capability 不调用；有 capability 调正确 RPC。
+- session import sync：同一 `agentId + workdir + remoteSessionId` 不重复创建 conversation。
+- replay idempotency：重复 `session/load` 不重复落 message/block。
+- update buffer：`session/update` 早到、listener 后到、TTL 过期。
+- prompt formatter：只发送最后 user message；system prompt only once；image/audio/resource fallback。
+- content mapper：usage/session info/tool terminal/diff/plan/mode/config/slash commands。
+- terminal manager：tail truncation、UTF-8 boundary、args 不拼接 shell。
+- fs handler：workspace guard、1-based line、binary/large file error。
+- permission resolver：approve/deny/cancel/timeout。
+
+Integration/manual matrix:
+
+- DimCode：init -> list -> new -> commands -> close -> resume -> prompt。
+- Claude Code ACP：init -> auth required -> authenticate flow -> cleanup。
+- Codex ACP：registry launch spec -> version drift diagnostics -> auth methods。
+- Regression：普通 non-ACP chat、MCP permission、DeepChat internal agent 不受影响。
+
+Quality gates:
+
+```bash
+pnpm run format
+pnpm run i18n
+pnpm run lint
+pnpm run typecheck
+pnpm test -- test/main/presenter/llmProviderPresenter
+pnpm test -- test/main/presenter/acpProvider.test.ts
+```
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+| --- | --- |
+| 不同 ACP wrapper 对 auth method 字段解释不一致 | diagnostics 显示 raw auth method；未知字段保留 `_meta`；只按官方 required 字段做控制流 |
+| Claude/Codex wrapper 拉起子进程后 probe 卡住 | 所有 real-agent probe 必须 timeout + process tree cleanup |
+| resume/load/new 语义混用导致历史重复 | DeepChat conversation 为事实源；远端 replay 先 staging 再 fingerprint 去重；prompt formatter current-turn-only |
+| terminal command 兼容性变化 | 直接 spawn 是协议正确行为；若 agent 要 shell，agent 应把 shell 作为 command |
+| session title 更新覆盖用户标题 | 只更新 ACP metadata；DeepChat 用户手工标题优先 |
diff --git a/docs/features/acp-v1-reliability/spec.md b/docs/features/acp-v1-reliability/spec.md
new file mode 100644
index 000000000..9169e00d2
--- /dev/null
+++ b/docs/features/acp-v1-reliability/spec.md
@@ -0,0 +1,93 @@
+# ACP v1 Reliability Specification
+
+Last reviewed: 2026-06-02
+
+## 背景
+
+DeepChat 已经具备 ACP agent 的基本启动、初始化、`session/new`、`session/load`、`session/prompt`、文件系统、终端、模式、模型和部分 session update 映射能力。但按 ACP v1 官方协议逐项核对后，当前实现仍有几个影响可靠性的缺口：认证流程未产品化，session lifecycle 不完整，部分通知会丢，Prompt 会重复发送历史，Terminal 输出截断方向不符合规范，部分状态更新没有进入 DeepChat 状态层。
+
+本目标是把 DeepChat 的 ACP 能力修到“全功能可靠”的 v1 版本：按 agent 初始化返回的 capability 精准启用功能，能稳定接入 registry agent、本地 DimCode、Claude Code ACP 和 Codex ACP，且所有协议行为都有测试或手工矩阵覆盖。
+
+会话数据事实源以 DeepChat records 为准。远端 ACP agent 返回的 session 是外部资源目录，DeepChat 只做 workspace 维度的导入、同步和绑定；导入后必须转换成 DeepChat 自己的消息格式并持久化。同步不得反复重复导入，也不得把远端 metadata 直接覆盖用户在 DeepChat 内手工维护的会话数据。
+
+## 资料来源
+
+- ACP v1 官方入口：[Overview](https://agentclientprotocol.com/protocol/v1/overview)
+- 关键协议页：[Initialization](https://agentclientprotocol.com/protocol/v1/initialization)、[Authentication](https://agentclientprotocol.com/protocol/v1/authentication)、[Session Setup](https://agentclientprotocol.com/protocol/v1/session-setup)、[Session List](https://agentclientprotocol.com/protocol/v1/session-list)、[Prompt Turn](https://agentclientprotocol.com/protocol/v1/prompt-turn)
+- 客户端能力页：[Content](https://agentclientprotocol.com/protocol/v1/content)、[Tool Calls](https://agentclientprotocol.com/protocol/v1/tool-calls)、[File System](https://agentclientprotocol.com/protocol/v1/file-system)、[Terminals](https://agentclientprotocol.com/protocol/v1/terminals)
+- 状态增强页：[Agent Plan](https://agentclientprotocol.com/protocol/v1/agent-plan)、[Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)、[Session Config Options](https://agentclientprotocol.com/protocol/v1/session-config-options)、[Slash Commands](https://agentclientprotocol.com/protocol/v1/slash-commands)、[Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)、[Transports](https://agentclientprotocol.com/protocol/v1/transports)
+- 本仓库 registry snapshot：`resources/acp-registry/registry.json`
+- 现有 ACP 入口：`src/main/presenter/llmProviderPresenter/acp/*`、`src/main/presenter/llmProviderPresenter/providers/acpProvider.ts`
+
+## 用户故事
+
+- 作为 DeepChat 用户，我可以从 ACP registry 或本地命令启动 agent，并清楚看到该 agent 支持哪些 ACP v1 能力。
+- 作为使用 Claude Code ACP 或 Codex ACP 的用户，我可以在 DeepChat 内完成 agent 暴露的认证流程，而不是只看到失败或需要手工猜测环境变量。
+- 作为使用 DimCode 的用户，我可以按 workspace 看到远端已有 session，把需要的 session 导入或绑定到 DeepChat 会话，并持续收到 slash commands、模式、配置项和标题更新。
+- 作为开发者，我可以通过 ACP diagnostics/debug action 复现每个协议方法，定位 agent、registry、认证、session 或 terminal 问题。
+- 作为 reviewer，我可以用固定测试矩阵判断 ACP 是否符合 v1 协议，而不是只依赖单 agent 的 happy path。
+
+## 成功标准
+
+- `initialize` 会声明 DeepChat 实际支持的 client capabilities，并保存 agent 返回的完整 capabilities、auth methods、agent info。
+- 所有可选协议方法都按 capability gate 调用；没有 capability 时不调用、不误报。
+- `authenticate`、`logout`、`session/list`、`session/resume`、`session/close` 有可复用 presenter/debug 入口。
+- `session/update` 不会因为 listener 注册时序丢失早期通知，尤其是 DimCode 的 `available_commands_update`。
+- `session/prompt` 只发送当前用户 turn，按 prompt capabilities 发送 text/image/audio/resource/resource_link。
+- `terminal/create/output/wait_for_exit/kill/release` 符合 output byte limit 和 command args 语义。
+- `usage_update`、`session_info_update`、plan、mode、config options、slash commands 都能进入 DeepChat 状态或 debug log。
+- DeepChat conversation 是最终持久化事实源；远端 session list/load/resume 只建立或更新 `AcpSessionLink`，不会重复创建同一远端 session 的本地会话。
+- 远端历史消息导入会先转换为 DeepChat message/block 格式，再按稳定 fingerprint 去重持久化。
+- 完成后运行 `pnpm run format`、`pnpm run i18n`、`pnpm run lint`、`pnpm run typecheck` 和 ACP 相关 Vitest。
+
+## 本地 agent 样本
+
+| Agent | Registry/local observation | 需要覆盖的关键路径 |
+| --- | --- | --- |
+| DimCode | registry `dimcode@0.0.75`，本地 `dimcode 0.0.75`；`loadSession=true`；`sessionCapabilities.list/resume/close`；`promptCapabilities.image=true`、`embeddedContext=true`；`mcpCapabilities.http=true`、`sse=false` | `session/list`、`session/new`、早期 `available_commands_update`、`session/close`、`session/resume`、config options、slash commands |
+| Claude Code ACP | registry `@agentclientprotocol/claude-agent-acp@0.39.0`；本地存在 `claude` 和 global `@zed-industries/claude-code-acp@0.11.0`；有 `claude-login` auth method | initialization、auth required、authenticate、process cleanup、HTTP/SSE MCP filtering |
+| Codex ACP | registry `@zed-industries/codex-acp@0.15.0`，global wrapper 观察到旧版本 `0.6.0`；auth methods 包含 ChatGPT/API key 类 | registry 优先、版本漂移诊断、auth methods、no session list fallback |
+| acpx | 本机 PATH 未发现名为 `acpx` 的可执行命令 | 不阻塞本目标；若后续提供准确命令名或路径，加入同一 diagnostics matrix |
+
+## Protocol 覆盖矩阵
+
+| Protocol | ACP v1 期望 | DeepChat 当前状态 | 修复/对接目标 |
+| --- | --- | --- | --- |
+| Transports | ACP 使用 JSON-RPC 2.0；常见 client 以 agent subprocess + stdio 通信；MCP stdio 必须支持，HTTP/SSE 按 agent capability 过滤 | 已有 subprocess/stdout/stderr 连接、registry launch spec、MCP transport filter；需要加强版本漂移和进程树清理 | registry launch spec 仍为首选；global/local 命令只做 fallback/diagnostics；初始化、认证、E2E probe 都有 timeout 和 process tree cleanup |
+| Initialization | Client 调 `initialize`，发送 `protocolVersion`、`clientCapabilities`、`clientInfo`；Agent 返回 `agentCapabilities`、`authMethods`、`agentInfo` | 已发送 `fs`、`terminal`；未声明/实现 auth capability；只解析部分 capability | 解析并保存完整 capability snapshot；不支持协议版本时关闭连接并展示错误；只声明已实现 client capabilities |
+| Authentication | Agent 用 `authMethods` 暴露方法；Client 调 `authenticate({ methodId })`；`logout` 只能在 `agentCapabilities.auth.logout` 存在时调用 | 有 auth method 日志字段，但没有产品化 authenticate/logout 入口 | 增加 authenticate/logout presenter/debug/UI 入口；处理 `agent`、`env_var`、`terminal` 类型；auth required 错误转成可操作状态 |
+| Session Setup: `session/new` | 创建新 session，传 `cwd` 和 MCP servers，返回 `sessionId`，可带初始 modes/models/config options | 已支持；但 listener 通常在返回后注册，早期 update 可能丢 | 新 DeepChat 会话首次使用 ACP agent 时才创建远端 session；返回后写入本地 `AcpSessionLink`；缓冲并 flush 早期 update |
+| Session Setup: `session/load` | 仅 `loadSession=true` 时调用；agent 会重放历史 update，再响应 load 完成 | 已支持并在 load 前注册 listener | 用作远端 session 历史导入/重放；进入 staging buffer，转换为 DeepChat message/block 后按 fingerprint 幂等落库 |
+| Session Setup: `session/resume` | 仅 `sessionCapabilities.resume` 存在时调用；不重放历史，恢复上下文后返回 | 未接入 | 用于已绑定 DeepChat conversation 的继续对话；不把远端 session 当事实源覆盖本地消息 |
+| Session Setup: `session/close` | 仅 `sessionCapabilities.close` 存在时调用；agent 取消该 session 活动并释放资源 | 当前 clearSession 主要 cancel/unbind/clear persistence，没有 close 协议 | 默认本地关闭/删除只 detach link；只有用户显式选择 close remote 时才调用 `session/close` |
+| Session Setup: additional directories | 仅 `sessionCapabilities.additionalDirectories` 存在时发送；必须为绝对路径 | 当前主要使用单 `cwd` | 首版保留单 `cwd`；后续若 workspace 多根目录可从能力 gate 接入，不默认发送 |
+| Session List | 仅 `sessionCapabilities.list` 存在时调用；支持 `cwd` filter、cursor pagination；`session_info_update` 同步标题/更新时间 | 未接入 list；`session_info_update` 被忽略 | 按 workspace 同步远端 session catalog；用 `agentId + canonicalWorkdir + remoteSessionId` 去重；只更新 link metadata，不直接覆盖 DeepChat conversation |
+| Prompt Turn | `session/prompt` 发送当前用户 message 的 ContentBlock[]；`session/cancel` 中断当前 turn；prompt content 必须受 capabilities 限制 | 已 prompt/cancel；formatter 会拼温度、maxTokens 和历史 USER/ASSISTANT 文本，容易重复上下文 | formatter 改为当前 turn only；system prompt 只作为首次 session context；cancel 只针对活跃 turn |
+| Content | Baseline 支持 text/resource_link；image/audio/resource 由 `promptCapabilities` 决定 | 输入侧 image 多数降级为 resource_link；输出侧 image 可转为 image block，audio/resource 偏文本化 | 输入侧按 capability 发送 image/audio/resource/resource_link/text；输出侧保留结构，不能显示的内容给清晰文本 fallback |
+| Tool Calls | Agent 通过 `tool_call`、`tool_call_update` 汇报工具状态、内容、locations、raw input/output；可嵌入 terminal/diff/content | 已映射 tool_call/update，但把部分状态当 permission block；terminal/diff/locations/raw 字段展示不完整 | 保留工具 call 生命周期；补 terminal/diff/location 展示和 raw metadata；不要把普通 tool progress 误标为权限 |
+| Client Permission | Client baseline method `session/request_permission` 用于工具权限确认 | 主进程已有 resolver 分发底座；需要 UI/超时/debug/test 闭环 | 复用现有 DeepChat permission overlay；补 timeout/cancel 默认 outcome；debug log 记录 permission request/result |
+| File System | `fs/read_text_file`、`fs/write_text_file` 只在 client capability 声明后可用；路径绝对；line 为 1-based | 已有 handler，包含 workspace guard、二进制/大小控制 | 保持安全边界；补 1-based、越界、二进制、跨 workspace 写入测试；声明能力与真实 handler 绑定 |
+| Terminals | `terminal/create` 用 `command` + `args` + `env` + `cwd`；`outputByteLimit` 超限时从开头截断，保留最新输出且字符边界有效 | 已有 terminal manager；当前把 command/args 拼进 shell，输出超限时保留开头 | 改为直接 spawn command + args；仅显式 shell 场景使用 shell；输出 buffer 保留尾部；release 后仍允许已渲染内容留在 tool call |
+| Agent Plan | `plan` update 每次发送完整 entries，client 应替换当前 plan | 已映射为 plan block | 保持替换语义，补测试；plan update 不追加成重复计划 |
+| Session Modes | Session 返回 modes；client 可调 `session/set_mode`；agent 可发 `current_mode_update`；官方建议逐步转向 config options | 已支持 mode 初始状态、set mode、mode update | 保持兼容；当 config options 提供 mode 等价项时，UI 优先统一展示 config options，legacy mode 继续可用 |
+| Session Config Options | Session 返回 `configOptions`；client 可设置配置；agent 可发 `config_option_update` | 已有 normalize 和 state update | 补初始化/new/load/resume 全路径同步；debug action 覆盖设置失败和状态回滚 |
+| Slash Commands | Agent 用 `available_commands_update` 发布命令；用户执行时作为普通 prompt 文本如 `/web query` | 已解析 available commands；早期通知可能丢 | 通过 update buffer 保证 commands 到达；UI 输入框命令候选来自 session state；执行仍走普通 prompt |
+| Usage Update | Agent 可发 usage/cost/token 类状态 | 当前 mapper 明确忽略 | 增加 metadata/event/state 映射，至少在 debug 和 turn metadata 可见；后续 UI 可展示 token/cost |
+| Session Info Update | Agent 可发 title、updatedAt、`_meta` 更新 session metadata | 当前 mapper 明确忽略 | 更新 `AcpSessionLink` metadata；只在本地标题仍为自动标题时建议更新，不覆盖用户手工标题 |
+| Extensibility | `_meta` 可携带自定义数据；自定义 method 以前缀 `_` 命名；未知字段应兼容 | 已有 ext debug action 和部分 passthrough；未知 update 多为 warn | 保留 `_meta` 到 debug/state；未知 official update 不崩溃；未知 custom update 记录 diagnostics |
+| Experimental schema fields | SDK 可能出现官网主流程未文档化的字段，例如 `sessionCapabilities.fork` | 未接入 | 只在 capability 存在时提供 debug-only 支持；不作为主 chat flow 前置条件 |
+
+## 非目标
+
+- 不在本目标内实现 ACP v2 或未发布协议。
+- 不为某个单独 agent 写硬编码行为；DimCode、Claude Code ACP、Codex ACP 只作为兼容样本。
+- 不改变非 ACP provider 的现有 prompt、MCP、权限或 terminal 行为。
+- 不默认扩大文件系统权限；ACP fs/terminal 继续受 session workdir 和 DeepChat 安全策略约束。
+- 不做远端 session 的主动批量写入或双向同步；远端 session catalog 是可导入资源，DeepChat conversation 才是本地事实源。
+
+## 约束
+
+- 新 renderer-main 能力优先走 typed route / typed event / renderer API client，不复制新的 `useLegacyPresenter()` 调用模式。
+- 用户可见字符串必须加 i18n。
+- UI 改动需要保持 ChatStatusBar/Settings 现有视觉密度，不做大面积营销式页面。
+- 代码、注释、类型名、commit message 使用英文；面向 reviewer 的 SDD 文档使用中文。
diff --git a/docs/features/acp-v1-reliability/tasks.md b/docs/features/acp-v1-reliability/tasks.md
new file mode 100644
index 000000000..60906abce
--- /dev/null
+++ b/docs/features/acp-v1-reliability/tasks.md
@@ -0,0 +1,149 @@
+# ACP v1 Reliability Tasks
+
+## 0. Review Gate
+
+- [ ] Review `spec.md` protocol coverage matrix with maintainers.
+- [ ] Review `plan.md` runtime flow, UI shape, and test matrix.
+- [ ] Confirm all open questions are resolved before implementation.
+- [ ] Keep this SDD folder active until ACP v1 reliability work is merged or deliberately abandoned.
+
+## 1. Capability and Initialization
+
+- [ ] Add tests for parsing full initialize result: `agentInfo`, `agentCapabilities`, `sessionCapabilities`, `promptCapabilities`, `authMethods`, `mcpCapabilities`.
+- [ ] Extend ACP process handle with a lightweight capability snapshot.
+- [ ] Parse support booleans from snapshot: `loadSession`, `sessionList`, `sessionResume`, `sessionClose`, `sessionFork`, `authLogout`.
+- [ ] Update initialize debug log to include protocol version, client capabilities, agent capabilities, and auth methods.
+- [ ] Ensure `buildClientCapabilities` only declares implemented capabilities.
+- [ ] Add explicit initialize error categories: protocol mismatch, process exit, protocol stream closed, timeout.
+
+## 2. Authentication
+
+- [ ] Extend shared ACP debug action type with `authenticate` and `logout`.
+- [ ] Add presenter/debug route for `authenticate({ agentId, methodId, workdir? })`.
+- [ ] Add presenter/debug route for `logout({ agentId, workdir? })`, gated by `auth.logout`.
+- [ ] Map auth-required failures into renderer-safe ACP status payload.
+- [ ] Implement `agent` auth method by calling `connection.authenticate({ methodId })`.
+- [ ] Implement `env_var` auth UX by surfacing missing env vars in agent settings and requiring restart/reinitialize.
+- [ ] Implement `terminal` auth flow before declaring `clientCapabilities.auth.terminal=true`.
+- [ ] Add auth tests for success, failure, missing method id, unsupported logout, and process cleanup.
+
+## 3. Session Catalog, Import, and Lifecycle
+
+- [ ] Extend shared ACP debug action type with `sessionList`, `sessionImport`, `sessionResume`, `sessionDetach`, `sessionCloseRemote`, and `sessionFork`.
+- [ ] Add `session/list` presenter/debug path with workspace `cwd` filter and cursor pagination.
+- [ ] Add `AcpSessionLink` persistence keyed by `agentId + canonicalWorkdir + remoteSessionId`.
+- [ ] Add external session catalog sync that updates link metadata without creating duplicate DeepChat conversations.
+- [ ] Add import path that creates or reuses a DeepChat conversation for a remote session.
+- [ ] Add `session/load` import path gated by top-level `loadSession`.
+- [ ] Stage replayed remote updates before converting them to DeepChat messages.
+- [ ] Add message/block fingerprinting so repeated imports do not duplicate persisted messages.
+- [ ] Add `session/resume` path gated by `sessionCapabilities.resume` for already linked conversations.
+- [ ] Fix local runtime restore priority: linked `resume` > linked `loadSession` import/replay > `newSession`.
+- [ ] Change local conversation close/delete to detach ACP link by default, without remote writes.
+- [ ] Add explicit remote close path gated by `sessionCapabilities.close`.
+- [ ] Change session cleanup so user stop uses `session/cancel`, while explicit remote close uses `session/close` when available.
+- [ ] Preserve persisted ACP session link after process crash so recoverable agents can resume later.
+- [ ] Add debug-only `session/fork` path gated by capability; do not wire it into normal chat flow yet.
+- [ ] Add DimCode-shaped lifecycle tests: list empty, catalog sync, import, repeated import no duplicate messages, resume, explicit remote close.
+
+## 4. Session Update Routing
+
+- [ ] Add session update buffer keyed by `sessionId`.
+- [ ] Buffer updates that arrive before listener registration.
+- [ ] Flush buffered updates in order when `registerSessionListener` runs.
+- [ ] Apply TTL and max-entry guard to avoid unbounded memory growth.
+- [ ] Record expired buffered updates in ACP debug log.
+- [ ] Add regression test for early `available_commands_update` during `session/new`.
+
+## 5. Prompt Turn and Input Content
+
+- [ ] Replace history-based ACP formatter with current-turn-only formatter.
+- [ ] Remove temperature/maxTokens prompt text injection.
+- [ ] Send DeepChat system prompt only once when a local conversation first binds to ACP runtime.
+- [ ] Add input content mapping for text, image, audio, resource, and resource_link.
+- [ ] Gate image/audio/resource by `promptCapabilities`.
+- [ ] Add fallback behavior for unsupported multimodal content.
+- [ ] Add tests for text-only, image-supported, image-unsupported, audio-supported, embedded context, and system prompt once.
+
+## 6. Session Updates and Output Content
+
+- [ ] Keep `agent_message_chunk` mapped to text stream and content block.
+- [ ] Keep `agent_thought_chunk` mapped to reasoning stream and reasoning block.
+- [ ] Update image/audio/resource/resource_link output handling to preserve structure in metadata/debug.
+- [ ] Map `usage_update` into turn metadata and ACP debug log.
+- [ ] Map `session_info_update` into `AcpSessionLink` metadata.
+- [ ] Ensure session title update does not override user-edited DeepChat titles.
+- [ ] Keep `plan` update replacement semantics.
+- [ ] Add tests for usage, session info, plan replacement, and unsupported output fallback.
+
+## 7. Tool Calls and Permission
+
+- [ ] Stop treating ordinary `tool_call` progress as permission UI.
+- [ ] Route only `session/request_permission` into DeepChat permission overlay.
+- [ ] Preserve tool terminal output, diff path/content, locations, raw input, and raw output in block metadata/debug.
+- [ ] Add permission resolver timeout with cancelled default outcome.
+- [ ] Clear stale ACP permission overlays after interrupted sessions instead of throwing on unknown request ids.
+- [ ] Add tests for approve, deny, cancel, timeout, missing resolver, and tool update rendering.
+
+## 8. File System
+
+- [ ] Keep `fs/read_text_file` and `fs/write_text_file` behind declared client fs capability.
+- [ ] Add tests for registered workdir requirement.
+- [ ] Add tests for 1-based line handling.
+- [ ] Add tests for cross-workspace path rejection.
+- [ ] Add tests for binary read rejection and max-size error.
+- [ ] Verify write path creates only allowed files and returns protocol-shaped errors.
+
+## 9. Terminals
+
+- [ ] Change `terminal/create` to spawn `command` with `args` directly.
+- [ ] Remove default command/args shell string concatenation.
+- [ ] Keep cwd resolution guarded by workspace rules or explicit fallback warning.
+- [ ] Change output buffer truncation to keep latest tail output.
+- [ ] Preserve UTF-8 character boundary after truncation.
+- [ ] Keep `kill` and `release` idempotent.
+- [ ] Add tests for args quoting, tail truncation, multibyte truncation, exit status, kill, release, and missing terminal.
+
+## 10. Modes, Config Options, Slash Commands
+
+- [ ] Ensure initialize, new, load, and resume all publish normalized config state.
+- [ ] Keep `session/set_mode` compatibility for agents still using session modes.
+- [ ] Prefer config options in UI when both legacy mode and config option exist.
+- [ ] Keep `current_mode_update` synchronized with ChatStatusBar.
+- [ ] Keep `config_option_update` synchronized with config state.
+- [ ] Ensure `available_commands_update` populates slash suggestions after update buffer fix.
+- [ ] Skip ACP warmup when the selected workdir is unavailable, while preserving session-start fallback behavior.
+- [ ] Add tests for set mode, set model/config option, current mode update, config option update, and slash command availability.
+
+## 11. Diagnostics UI
+
+- [ ] Add compact ACP diagnostics section in agent settings.
+- [ ] Show protocol version, readiness, auth state, capabilities, launch source, and last error.
+- [ ] Add Authenticate button only when auth methods exist.
+- [ ] Add Sync Sessions button only when `sessionCapabilities.list` exists.
+- [ ] Add Import/Open action for listed remote sessions.
+- [ ] Add Detach action for linked local conversations.
+- [ ] Add Close Remote action only behind explicit user intent and `sessionCapabilities.close`.
+- [ ] Add Run Diagnostics action that executes safe initialize/list capability probes with timeout.
+- [ ] Add i18n keys for all new labels and error messages.
+- [ ] Add renderer tests for ready, auth required, no session list, catalog sync, imported link, duplicate import prevention, and error states.
+
+## 12. Registry and Real-Agent Matrix
+
+- [ ] Verify registry `dimcode@0.0.75` launch spec on Windows.
+- [ ] Verify DimCode lifecycle: initialize, list, catalog sync, import, repeated import no duplication, commands, resume, prompt, explicit remote close.
+- [ ] Verify Claude Code ACP initialize and auth-required path with timeout cleanup.
+- [ ] Verify Codex ACP registry launch and local/global version drift diagnostics.
+- [ ] Record exact command, version, capabilities, and result in ACP debug log or test notes.
+- [ ] Keep `acpx` out of the matrix until an executable path or exact package name is available.
+
+## 13. Final Quality Gates
+
+- [ ] Run `pnpm run format`.
+- [ ] Run `pnpm run i18n`.
+- [ ] Run `pnpm run lint`.
+- [ ] Run `pnpm run typecheck`.
+- [ ] Run ACP main tests under `test/main/presenter/llmProviderPresenter`.
+- [ ] Run `test/main/presenter/acpProvider.test.ts`.
+- [ ] Run renderer tests for diagnostics UI if UI is changed.
+- [ ] Update durable docs or archive this SDD folder after implementation is merged.
diff --git a/src/main/presenter/agentRuntimePresenter/index.ts b/src/main/presenter/agentRuntimePresenter/index.ts
index 6b43db139..d6c56b45b 100644
--- a/src/main/presenter/agentRuntimePresenter/index.ts
+++ b/src/main/presenter/agentRuntimePresenter/index.ts
@@ -202,6 +202,15 @@ type ActiveProviderPermission = {
   resolve: (granted: boolean) => Promise<void>
 }
 
+type ProviderPermissionInteractionInput = {
+  sessionId: string
+  messageId: string
+  toolCallId: string
+  requestId: string
+  permissionType: 'read' | 'write' | 'all' | 'command'
+  granted: boolean
+}
+
 type PersistedSessionGenerationRow = {
   provider_id: string
   model_id: string
@@ -4528,32 +4537,68 @@ export class AgentRuntimePresenter implements IAgentImplementation {
     })
   }
 
-  private async resolveProviderPermissionInteraction(input: {
-    sessionId: string
-    messageId: string
-    toolCallId: string
-    requestId: string
-    permissionType: 'read' | 'write' | 'all' | 'command'
-    granted: boolean
-  }): Promise<void> {
+  private async resolveProviderPermissionInteraction(
+    input: ProviderPermissionInteractionInput
+  ): Promise<void> {
     const active = this.activeProviderPermissions.get(input.requestId)
+    let resolution: { status: 'resolved' } | { status: 'stale'; error: unknown }
 
     try {
-      if (active) {
-        await active.resolve(input.granted)
-      } else {
-        await this.llmProviderPresenter.resolveAgentPermission(input.requestId, input.granted)
-        this.updatePersistedProviderPermissionState(
-          input.messageId,
-          input.toolCallId,
-          input.requestId,
-          input.permissionType,
-          input.granted
-        )
-      }
+      resolution = await this.resolveProviderPermissionSafely(
+        active
+          ? () => active.resolve(input.granted)
+          : () => this.llmProviderPresenter.resolveAgentPermission(input.requestId, input.granted)
+      )
     } finally {
       this.activeProviderPermissions.delete(input.requestId)
     }
+
+    if (active && resolution.status === 'resolved') {
+      return
+    }
+
+    if (resolution.status === 'stale') {
+      console.warn(
+        `[DeepChatAgent] Clearing stale ACP permission request ${input.requestId}:`,
+        resolution.error
+      )
+    }
+
+    this.updatePersistedProviderPermissionState(
+      input.messageId,
+      input.toolCallId,
+      input.requestId,
+      input.permissionType,
+      resolution.status === 'resolved' ? input.granted : false,
+      resolution.status === 'stale' ? 'Permission request expired.' : undefined
+    )
+    this.finishProviderPermissionInteraction(input.sessionId, input.messageId)
+  }
+
+  private async resolveProviderPermissionSafely(
+    task: () => Promise<void>
+  ): Promise<{ status: 'resolved' } | { status: 'stale'; error: unknown }> {
+    try {
+      await task()
+      return { status: 'resolved' }
+    } catch (error) {
+      if (!this.isUnknownAcpPermissionRequestError(error)) {
+        throw error
+      }
+      return { status: 'stale', error }
+    }
+  }
+
+  private isUnknownAcpPermissionRequestError(error: unknown): boolean {
+    const message =
+      error instanceof Error ? error.message : typeof error === 'string' ? error : undefined
+    return Boolean(message?.startsWith('Unknown ACP permission request:'))
+  }
+
+  private finishProviderPermissionInteraction(sessionId: string, messageId: string): void {
+    this.messageStore.updateMessageStatus(messageId, 'sent')
+    this.setSessionStatus(sessionId, 'idle')
+    this.emitMessageRefresh(sessionId, messageId)
   }
 
   private updatePersistedProviderPermissionState(
@@ -4561,7 +4606,8 @@ export class AgentRuntimePresenter implements IAgentImplementation {
     toolCallId: string,
     requestId: string,
     permissionType: 'read' | 'write' | 'all' | 'command',
-    granted: boolean
+    granted: boolean,
+    deniedMessage = 'User denied the request.'
   ): void {
     const message = this.messageStore.getMessage(messageId)
     if (!message || message.role !== 'assistant') {
@@ -4582,6 +4628,9 @@ export class AgentRuntimePresenter implements IAgentImplementation {
     }
 
     this.markPermissionResolved(actionBlock, granted, permissionType)
+    if (!granted) {
+      actionBlock.content = deniedMessage
+    }
     this.messageStore.updateAssistantContent(messageId, blocks)
   }
 
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpCapabilities.ts b/src/main/presenter/llmProviderPresenter/acp/acpCapabilities.ts
index 0aad138c2..b1e44459a 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpCapabilities.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpCapabilities.ts
@@ -3,6 +3,50 @@ import type * as schema from '@agentclientprotocol/sdk/dist/schema/index.js'
 export interface AcpCapabilityOptions {
   enableFs?: boolean
   enableTerminal?: boolean
+  enableTerminalAuth?: boolean
+}
+
+export interface AcpCapabilitySupport {
+  loadSession: boolean
+  sessionList: boolean
+  sessionResume: boolean
+  sessionClose: boolean
+  sessionFork: boolean
+}
+
+export interface AcpCapabilitySnapshot {
+  protocolVersion?: schema.ProtocolVersion
+  agentInfo?: schema.Implementation | null
+  agentCapabilities?: schema.AgentCapabilities
+  sessionCapabilities?: schema.SessionCapabilities
+  promptCapabilities?: schema.PromptCapabilities
+  authMethods: schema.AuthMethod[]
+  mcpCapabilities?: schema.McpCapabilities
+  supports: AcpCapabilitySupport
+}
+
+export function buildCapabilitySnapshot(
+  initializeResult: schema.InitializeResponse
+): AcpCapabilitySnapshot {
+  const agentCapabilities = initializeResult.agentCapabilities
+  const sessionCapabilities = agentCapabilities?.sessionCapabilities
+
+  return {
+    protocolVersion: initializeResult.protocolVersion,
+    agentInfo: initializeResult.agentInfo,
+    agentCapabilities,
+    sessionCapabilities,
+    promptCapabilities: agentCapabilities?.promptCapabilities,
+    authMethods: initializeResult.authMethods ?? [],
+    mcpCapabilities: agentCapabilities?.mcpCapabilities,
+    supports: {
+      loadSession: Boolean(agentCapabilities?.loadSession),
+      sessionList: Boolean(sessionCapabilities?.list),
+      sessionResume: Boolean(sessionCapabilities?.resume),
+      sessionClose: Boolean(sessionCapabilities?.close),
+      sessionFork: Boolean(sessionCapabilities?.fork)
+    }
+  }
 }
 
 /**
@@ -27,5 +71,11 @@ export function buildClientCapabilities(
     caps.terminal = true
   }
 
+  if (options.enableTerminal !== false && options.enableTerminalAuth) {
+    caps.auth = {
+      terminal: true
+    }
+  }
+
   return caps
 }
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpContentMapper.ts b/src/main/presenter/llmProviderPresenter/acp/acpContentMapper.ts
index 6b9abb4ce..241c09f93 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpContentMapper.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpContentMapper.ts
@@ -25,6 +25,19 @@ export interface MappedContent {
   }>
   /** Unified ACP session config state */
   configState?: AcpConfigState
+  /** ACP session metadata update */
+  sessionInfo?: {
+    title?: string | null
+    updatedAt?: string | null
+    meta?: Record<string, unknown> | null
+  }
+  /** ACP session usage/context update */
+  usage?: {
+    used: number
+    size: number
+    cost?: schema.Cost | null
+    meta?: Record<string, unknown> | null
+  }
 }
 
 interface ToolCallState {
@@ -76,8 +89,10 @@ export class AcpContentMapper {
         this.handleConfigOptionUpdate(update, payload)
         break
       case 'session_info_update':
+        this.handleSessionInfoUpdate(update, payload)
+        break
       case 'usage_update':
-        // These updates are useful for stateful clients but do not affect chat rendering.
+        this.handleUsageUpdate(update, payload)
         break
       case 'user_message_chunk':
         // ignore echo
@@ -291,6 +306,29 @@ export class AcpContentMapper {
     })
   }
 
+  private handleSessionInfoUpdate(
+    update: Extract<schema.SessionNotification['update'], { sessionUpdate: 'session_info_update' }>,
+    payload: MappedContent
+  ) {
+    payload.sessionInfo = {
+      title: update.title,
+      updatedAt: update.updatedAt,
+      meta: update._meta ?? null
+    }
+  }
+
+  private handleUsageUpdate(
+    update: Extract<schema.SessionNotification['update'], { sessionUpdate: 'usage_update' }>,
+    payload: MappedContent
+  ) {
+    payload.usage = {
+      used: update.used,
+      size: update.size,
+      cost: update.cost ?? null,
+      meta: update._meta ?? null
+    }
+  }
+
   private formatToolCallContent(
     contents?: schema.ToolCallContent[] | null,
     joiner: string = '\n'
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpMessageFormatter.ts b/src/main/presenter/llmProviderPresenter/acp/acpMessageFormatter.ts
index 976f4b32e..bcebbb967 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpMessageFormatter.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpMessageFormatter.ts
@@ -1,60 +1,73 @@
 import type * as schema from '@agentclientprotocol/sdk/dist/schema/index.js'
-import type { ChatMessage, ModelConfig } from '@shared/presenter'
+import type { ChatMessage } from '@shared/presenter'
 
-interface NormalizedContent {
-  type: 'text' | 'resource_link'
-  value: string
+interface FormatOptions {
+  promptCapabilities?: schema.PromptCapabilities
+  includeSystemPrompt?: boolean
 }
 
+interface FormatResult {
+  blocks: schema.ContentBlock[]
+  includedSystemPrompt: boolean
+}
+
+type NormalizedContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string; uri?: string }
+  | { type: 'audio'; data: string; mimeType: string }
+  | { type: 'resource_link'; uri: string; name?: string; mimeType?: string }
+  | { type: 'resource'; uri: string; text: string; mimeType?: string }
+
+const DATA_URL_PATTERN = /^data:([^;,]+);base64,(.*)$/s
+
 export class AcpMessageFormatter {
-  format(messages: ChatMessage[], modelConfig: ModelConfig): schema.ContentBlock[] {
+  format(messages: ChatMessage[], options: FormatOptions = {}): FormatResult {
     const blocks: schema.ContentBlock[] = []
-    const configLine = this.buildConfigLine(modelConfig)
-    if (configLine) {
-      blocks.push({ type: 'text', text: configLine })
+    const systemPrompt = options.includeSystemPrompt ? this.extractSystemPrompt(messages) : null
+    if (systemPrompt) {
+      blocks.push({
+        type: 'text',
+        text: `System instructions:\n${systemPrompt}`
+      })
     }
 
-    messages.forEach((message) => {
-      const prefix = (message.role || 'unknown').toUpperCase()
-      const normalized = this.normalizeContent(message)
-      if (normalized.length === 0) {
-        blocks.push({ type: 'text', text: `${prefix}:` })
-        return
-      }
-
-      normalized.forEach((item, index) => {
-        if (item.type === 'text') {
-          const label = index === 0 ? `${prefix}: ` : ''
-          blocks.push({ type: 'text', text: `${label}${item.value}` })
-        } else if (item.type === 'resource_link') {
-          blocks.push({ type: 'resource_link', uri: item.value, name: prefix })
-        }
+    const userMessage = this.findLastUserMessage(messages)
+    if (userMessage) {
+      this.normalizeContent(userMessage).forEach((item) => {
+        blocks.push(this.toContentBlock(item, options.promptCapabilities))
       })
+    }
 
-      if (message.tool_calls && message.tool_calls.length > 0) {
-        message.tool_calls.forEach((toolCall) => {
-          blocks.push({
-            type: 'text',
-            text: `${prefix} TOOL CALL ${toolCall.id || ''}: ${toolCall.function?.name || 'unknown'} ${toolCall.function?.arguments || ''}`
-          })
-        })
-      }
+    if (!blocks.length) {
+      blocks.push({ type: 'text', text: '' })
+    }
 
-      if (message.role === 'tool' && typeof message.content === 'string') {
-        blocks.push({
-          type: 'text',
-          text: `TOOL RESPONSE${message.tool_call_id ? ` (${message.tool_call_id})` : ''}: ${message.content}`
-        })
-      }
-    })
+    return {
+      blocks,
+      includedSystemPrompt: Boolean(systemPrompt)
+    }
+  }
 
-    return blocks
+  private findLastUserMessage(messages: ChatMessage[]): ChatMessage | null {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      if (messages[index]?.role === 'user') {
+        return messages[index]
+      }
+    }
+    return null
   }
 
-  private buildConfigLine(modelConfig: ModelConfig): string {
-    const temperature = modelConfig.temperature ?? 0.6
-    const maxTokens = modelConfig.maxTokens ?? modelConfig.maxCompletionTokens ?? 4096
-    return `temperature=${temperature}, maxTokens=${maxTokens}`
+  private extractSystemPrompt(messages: ChatMessage[]): string | null {
+    const systemMessage = messages.find((message) => message.role === 'system')
+    if (!systemMessage) return null
+
+    const text = this.normalizeContent(systemMessage)
+      .filter((item): item is Extract<NormalizedContent, { type: 'text' }> => item.type === 'text')
+      .map((item) => item.text.trim())
+      .filter(Boolean)
+      .join('\n')
+
+    return text || null
   }
 
   private normalizeContent(message: ChatMessage): NormalizedContent[] {
@@ -63,31 +76,129 @@ export class AcpMessageFormatter {
 
     if (typeof content === 'string') {
       if (content.trim().length > 0) {
-        normalized.push({ type: 'text', value: content })
+        normalized.push({ type: 'text', text: content })
+      }
+      return normalized
+    }
+
+    if (!Array.isArray(content)) {
+      return normalized
+    }
+
+    content.forEach((rawPart) => {
+      const part = rawPart as Record<string, unknown>
+      const type = typeof part.type === 'string' ? part.type : undefined
+
+      if ((type === 'text' || type === 'input_text') && typeof part.text === 'string') {
+        normalized.push({ type: 'text', text: part.text })
+        return
       }
-    } else if (Array.isArray(content)) {
-      content.forEach((rawPart) => {
-        const part = rawPart as Record<string, unknown>
-        const type = typeof part.type === 'string' ? part.type : undefined
-
-        if ((type === 'text' || type === 'input_text') && typeof part.text === 'string') {
-          normalized.push({ type: 'text', value: part.text })
-        } else if (type === 'image_url') {
-          const imageUrl = part['image_url'] as { url?: string } | undefined
-          if (imageUrl?.url) {
-            normalized.push({ type: 'resource_link', value: imageUrl.url })
+
+      if (type === 'image_url' || type === 'input_image') {
+        const url = this.extractImageUrl(part)
+        if (!url) return
+        const image = this.parseDataUrl(url)
+        if (image) {
+          normalized.push({ type: 'image', data: image.data, mimeType: image.mimeType, uri: url })
+        } else {
+          normalized.push({ type: 'resource_link', uri: url, name: 'image' })
+        }
+        return
+      }
+
+      if (type === 'input_audio' || type === 'audio') {
+        const data = typeof part.data === 'string' ? part.data : undefined
+        const mimeType =
+          typeof part.mimeType === 'string'
+            ? part.mimeType
+            : typeof part.mime_type === 'string'
+              ? part.mime_type
+              : 'audio/mpeg'
+        if (data) {
+          normalized.push({ type: 'audio', data, mimeType })
+        }
+        return
+      }
+
+      if (type === 'resource_link' && typeof part.uri === 'string') {
+        normalized.push({
+          type: 'resource_link',
+          uri: part.uri,
+          name: typeof part.name === 'string' ? part.name : undefined,
+          mimeType: typeof part.mimeType === 'string' ? part.mimeType : undefined
+        })
+        return
+      }
+
+      if (typeof part.text === 'string') {
+        normalized.push({ type: 'text', text: part.text })
+      }
+    })
+
+    return normalized
+  }
+
+  private extractImageUrl(part: Record<string, unknown>): string | undefined {
+    const imageUrl = part.image_url as { url?: unknown } | undefined
+    const source = part.source as { data?: unknown; url?: unknown } | undefined
+    const candidates = [imageUrl?.url, source?.data, source?.url, part.data, part.url, part.uri]
+    return candidates.find((candidate): candidate is string => {
+      return typeof candidate === 'string' && candidate.trim().length > 0
+    })
+  }
+
+  private toContentBlock(
+    item: NormalizedContent,
+    capabilities?: schema.PromptCapabilities
+  ): schema.ContentBlock {
+    switch (item.type) {
+      case 'text':
+        return { type: 'text', text: item.text }
+      case 'image':
+        if (capabilities?.image) {
+          return {
+            type: 'image',
+            data: item.data,
+            mimeType: item.mimeType,
+            ...(item.uri ? { uri: item.uri } : {})
           }
-        } else if (type === 'input_image') {
-          const imageUrl = part['image_url'] as { url?: string } | undefined
-          if (imageUrl?.url) {
-            normalized.push({ type: 'resource_link', value: imageUrl.url })
+        }
+        return item.uri
+          ? { type: 'resource_link', uri: item.uri, name: 'image', mimeType: item.mimeType }
+          : { type: 'text', text: `[image ${item.mimeType}]` }
+      case 'audio':
+        if (capabilities?.audio) {
+          return { type: 'audio', data: item.data, mimeType: item.mimeType }
+        }
+        return { type: 'text', text: `[audio ${item.mimeType}]` }
+      case 'resource':
+        if (capabilities?.embeddedContext) {
+          return {
+            type: 'resource',
+            resource: {
+              uri: item.uri,
+              text: item.text,
+              ...(item.mimeType ? { mimeType: item.mimeType } : {})
+            }
           }
-        } else if (typeof part.text === 'string') {
-          normalized.push({ type: 'text', value: part.text })
         }
-      })
+        return { type: 'text', text: item.text }
+      case 'resource_link':
+        return {
+          type: 'resource_link',
+          uri: item.uri,
+          name: item.name ?? item.uri,
+          ...(item.mimeType ? { mimeType: item.mimeType } : {})
+        }
     }
+  }
 
-    return normalized
+  private parseDataUrl(value: string): { mimeType: string; data: string } | null {
+    const match = DATA_URL_PATTERN.exec(value)
+    if (!match) return null
+    return {
+      mimeType: match[1],
+      data: match[2]
+    }
   }
 }
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts b/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
index 79ef003d7..cf800fea0 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpProcessManager.ts
@@ -27,7 +27,11 @@ import {
   setPathEntriesOnEnv
 } from '@/lib/agentRuntime/shellEnvHelper'
 import { RuntimeHelper } from '@/lib/runtimeHelper'
-import { buildClientCapabilities } from './acpCapabilities'
+import {
+  buildCapabilitySnapshot,
+  buildClientCapabilities,
+  type AcpCapabilitySnapshot
+} from './acpCapabilities'
 import { AcpFsHandler } from './acpFsHandler'
 import { AcpTerminalManager } from './acpTerminalManager'
 import {
@@ -54,9 +58,17 @@ export interface AcpProcessHandle extends AgentProcessHandle {
   availableModes?: Array<{ id: string; name: string; description: string }>
   currentModeId?: string
   agentCapabilities?: schema.AgentCapabilities
+  agentInfo?: schema.Implementation | null
+  capabilitySnapshot?: AcpCapabilitySnapshot
+  sessionCapabilities?: schema.SessionCapabilities
+  promptCapabilities?: schema.PromptCapabilities
   authMethods?: schema.AuthMethod[]
   mcpCapabilities?: schema.McpCapabilities
   supportsLoadSession?: boolean
+  supportsSessionList?: boolean
+  supportsSessionResume?: boolean
+  supportsSessionClose?: boolean
+  supportsSessionFork?: boolean
   launchSignature: string
 }
 
@@ -105,6 +117,11 @@ interface PermissionResolverEntry {
   resolver: PermissionResolver
 }
 
+interface BufferedSessionUpdate {
+  notification: schema.SessionNotification
+  receivedAt: number
+}
+
 type JsonRpcId = string | number
 type JsonRpcMessageRecord = Record<string, unknown>
 type ProtocolDirection = 'in' | 'out'
@@ -128,13 +145,20 @@ interface ProtocolMessageSummary {
 const MAX_PROTOCOL_LOG_LINE_LENGTH = 4000
 const IMPORTANT_PROTOCOL_METHODS = new Set([
   'initialize',
+  'authenticate',
   'session/new',
   'session/load',
+  'session/list',
+  'session/resume',
+  'session/close',
+  'session/fork',
   'session/prompt',
-  'session/cancel',
-  'authenticate'
+  'session/cancel'
 ])
 
+const SESSION_UPDATE_BUFFER_TTL_MS = 30_000
+const MAX_BUFFERED_SESSION_UPDATES = 100
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 
@@ -182,6 +206,7 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
   private readonly boundHandles = new Map<string, AcpProcessHandle>()
   private readonly pendingHandles = new Map<string, Promise<AcpProcessHandle>>()
   private readonly sessionListeners = new Map<string, SessionListenerEntry>()
+  private readonly bufferedSessionUpdates = new Map<string, BufferedSessionUpdate[]>()
   private readonly permissionResolvers = new Map<string, PermissionResolverEntry>()
   private readonly runtimeHelper = RuntimeHelper.getInstance()
   private readonly terminalManager = new AcpTerminalManager()
@@ -329,9 +354,21 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
    * Resolve workdir to an absolute path, using fallback if not provided.
    */
   private resolveWorkdir(workdir?: string): string {
-    if (workdir && workdir.trim()) {
-      return workdir.trim()
+    const trimmed = workdir?.trim()
+    if (!trimmed) {
+      return this.getFallbackWorkdir()
+    }
+
+    try {
+      if (fs.existsSync(trimmed) && fs.statSync(trimmed).isDirectory()) {
+        return trimmed
+      }
+    } catch (error) {
+      console.warn(`[ACP] workdir "${trimmed}" is not accessible; using fallback workdir.`, error)
+      return this.getFallbackWorkdir()
     }
+
+    console.warn(`[ACP] workdir "${trimmed}" does not exist; using fallback workdir.`)
     return this.getFallbackWorkdir()
   }
 
@@ -677,6 +714,8 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
       this.sessionListeners.set(sessionId, { agentId, handlers: new Set([handler]) })
     }
 
+    this.flushBufferedSessionUpdates(sessionId)
+
     return () => {
       const existingEntry = this.sessionListeners.get(sessionId)
       if (!existingEntry) return
@@ -713,6 +752,7 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
     this.sessionWorkdirs.delete(sessionId)
     this.sessionConversations.delete(sessionId)
     this.fsHandlers.delete(sessionId)
+    this.bufferedSessionUpdates.delete(sessionId)
     // Clean up terminals for this session
     void this.terminalManager.releaseSessionTerminals(sessionId)
   }
@@ -886,8 +926,12 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
         configOptions?: schema.SessionConfigOption[] | null
         models?: schema.SessionModelState | null
         modes?: schema.SessionModeState | null
+        protocolVersion?: schema.ProtocolVersion
+        agentInfo?: schema.Implementation | null
         agentCapabilities?: {
           mcpCapabilities?: schema.McpCapabilities
+          promptCapabilities?: schema.PromptCapabilities
+          sessionCapabilities?: schema.SessionCapabilities
           loadSession?: boolean
         }
         authMethods?: schema.AuthMethod[]
@@ -898,17 +942,23 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
         payload: initResult
       })
 
-      handleSeed.agentCapabilities = resultData.agentCapabilities
-      handleSeed.authMethods = resultData.authMethods
-      if (resultData.agentCapabilities?.mcpCapabilities) {
-        handleSeed.mcpCapabilities = resultData.agentCapabilities.mcpCapabilities
-        console.info('[ACP] MCP capabilities:', resultData.agentCapabilities.mcpCapabilities)
-      }
-      const loadSessionCapability = parseLoadSessionCapability(resultData)
-      if (loadSessionCapability !== undefined) {
-        handleSeed.supportsLoadSession = loadSessionCapability
-        console.info('[ACP] loadSession capability:', handleSeed.supportsLoadSession)
+      const capabilitySnapshot = buildCapabilitySnapshot(initResult)
+      handleSeed.capabilitySnapshot = capabilitySnapshot
+      handleSeed.agentInfo = capabilitySnapshot.agentInfo
+      handleSeed.agentCapabilities = capabilitySnapshot.agentCapabilities
+      handleSeed.sessionCapabilities = capabilitySnapshot.sessionCapabilities
+      handleSeed.promptCapabilities = capabilitySnapshot.promptCapabilities
+      handleSeed.authMethods = capabilitySnapshot.authMethods
+      handleSeed.supportsLoadSession = capabilitySnapshot.supports.loadSession
+      handleSeed.supportsSessionList = capabilitySnapshot.supports.sessionList
+      handleSeed.supportsSessionResume = capabilitySnapshot.supports.sessionResume
+      handleSeed.supportsSessionClose = capabilitySnapshot.supports.sessionClose
+      handleSeed.supportsSessionFork = capabilitySnapshot.supports.sessionFork
+      if (capabilitySnapshot.mcpCapabilities) {
+        handleSeed.mcpCapabilities = capabilitySnapshot.mcpCapabilities
+        console.info('[ACP] MCP capabilities:', capabilitySnapshot.mcpCapabilities)
       }
+      console.info('[ACP] Capability support:', capabilitySnapshot.supports)
 
       if (resultData.sessionId) {
         console.info(`[ACP] Session ID: ${resultData.sessionId}`)
@@ -976,10 +1026,18 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
       configState: handleSeed.configState ?? createEmptyAcpConfigState('legacy'),
       availableModes: handleSeed.availableModes,
       currentModeId: handleSeed.currentModeId,
+      agentInfo: handleSeed.agentInfo,
+      capabilitySnapshot: handleSeed.capabilitySnapshot,
       agentCapabilities: handleSeed.agentCapabilities,
+      sessionCapabilities: handleSeed.sessionCapabilities,
+      promptCapabilities: handleSeed.promptCapabilities,
       authMethods: handleSeed.authMethods,
       mcpCapabilities: handleSeed.mcpCapabilities,
       supportsLoadSession: handleSeed.supportsLoadSession,
+      supportsSessionList: handleSeed.supportsSessionList,
+      supportsSessionResume: handleSeed.supportsSessionResume,
+      supportsSessionClose: handleSeed.supportsSessionClose,
+      supportsSessionFork: handleSeed.supportsSessionFork,
       launchSignature
     }
     readyHandle = handle
@@ -1586,9 +1644,16 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
   private dispatchSessionUpdate(notification: schema.SessionNotification): void {
     const entry = this.sessionListeners.get(notification.sessionId)
     if (!entry) {
-      console.warn(`[ACP] Received session update for unknown session "${notification.sessionId}"`)
+      this.bufferSessionUpdate(notification)
       return
     }
+    this.deliverSessionUpdate(entry, notification)
+  }
+
+  private deliverSessionUpdate(
+    entry: SessionListenerEntry,
+    notification: schema.SessionNotification
+  ): void {
     this.debugLog.append(entry.agentId, {
       kind: 'notification',
       action: 'session/update',
@@ -1605,6 +1670,56 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
     })
   }
 
+  private bufferSessionUpdate(notification: schema.SessionNotification): void {
+    const now = Date.now()
+    this.pruneBufferedSessionUpdates(now)
+    const sessionId = notification.sessionId
+    const existing = this.bufferedSessionUpdates.get(sessionId) ?? []
+    const next = [
+      ...existing,
+      {
+        notification,
+        receivedAt: now
+      }
+    ].slice(-MAX_BUFFERED_SESSION_UPDATES)
+    this.bufferedSessionUpdates.set(sessionId, next)
+    console.warn(
+      `[ACP] Buffered session update for unbound session "${sessionId}" (${next.length} pending)`
+    )
+  }
+
+  private flushBufferedSessionUpdates(sessionId: string): void {
+    const entry = this.sessionListeners.get(sessionId)
+    if (!entry) return
+
+    this.pruneBufferedSessionUpdates()
+    const buffered = this.bufferedSessionUpdates.get(sessionId)
+    if (!buffered?.length) return
+
+    this.bufferedSessionUpdates.delete(sessionId)
+    this.debugLog.append(entry.agentId, {
+      kind: 'lifecycle',
+      action: 'session/update.buffer.flush',
+      sessionId,
+      payload: { count: buffered.length }
+    })
+    buffered.forEach(({ notification }) => this.deliverSessionUpdate(entry, notification))
+  }
+
+  private pruneBufferedSessionUpdates(now = Date.now()): void {
+    for (const [sessionId, updates] of this.bufferedSessionUpdates.entries()) {
+      const fresh = updates.filter(
+        (update) => now - update.receivedAt <= SESSION_UPDATE_BUFFER_TTL_MS
+      )
+      if (fresh.length === updates.length) continue
+      if (fresh.length) {
+        this.bufferedSessionUpdates.set(sessionId, fresh)
+      } else {
+        this.bufferedSessionUpdates.delete(sessionId)
+      }
+    }
+  }
+
   private async dispatchPermissionRequest(
     params: schema.RequestPermissionRequest
   ): Promise<schema.RequestPermissionResponse> {
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpSessionManager.ts b/src/main/presenter/llmProviderPresenter/acp/acpSessionManager.ts
index 7c4986547..06a35bf14 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpSessionManager.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpSessionManager.ts
@@ -33,6 +33,16 @@ interface SessionHooks {
   onPermission: PermissionResolver
 }
 
+type AcpConnectionWithUnstableSessionLifecycle = ClientSideConnectionType & {
+  unstable_resumeSession?: (
+    params: schema.ResumeSessionRequest
+  ) => Promise<schema.ResumeSessionResponse>
+  unstable_closeSession?: (
+    params: schema.CloseSessionRequest
+  ) => Promise<schema.CloseSessionResponse>
+  unstable_forkSession?: (params: schema.ForkSessionRequest) => Promise<schema.ForkSessionResponse>
+}
+
 const summarizeMcpServers = (mcpServers: schema.McpServer[]) =>
   mcpServers.map((server) => {
     const record = server as Record<string, unknown>
@@ -43,7 +53,7 @@ const summarizeMcpServers = (mcpServers: schema.McpServer[]) =>
   })
 
 const summarizeSessionResponse = (
-  response: schema.LoadSessionResponse | schema.NewSessionResponse
+  response: schema.LoadSessionResponse | schema.NewSessionResponse | schema.ResumeSessionResponse
 ) => ({
   sessionId: 'sessionId' in response ? response.sessionId : undefined,
   keys: Object.keys(response as Record<string, unknown>),
@@ -59,6 +69,8 @@ export interface AcpSessionRecord extends AgentSessionState {
   detachHandlers: Array<() => void>
   workdir: string
   configState?: AcpConfigState
+  promptCapabilities?: schema.PromptCapabilities
+  systemPromptSent?: boolean
   availableModes?: Array<{ id: string; name: string; description: string }>
   currentModeId?: string
   availableCommands?: Array<{
@@ -167,12 +179,6 @@ export class AcpSessionManager {
 
     this.processManager.clearSession(session.sessionId)
 
-    try {
-      await session.connection.cancel({ sessionId: session.sessionId })
-    } catch (error) {
-      console.warn(`[ACP] Failed to cancel session ${session.sessionId}:`, error)
-    }
-
     try {
       await this.processManager.unbindProcess(session.agentId, conversationId)
     } catch (error) {
@@ -303,7 +309,8 @@ export class AcpSessionManager {
       workdir,
       configState,
       availableModes,
-      currentModeId
+      currentModeId,
+      promptCapabilities: handle.promptCapabilities
     }
   }
 
@@ -334,6 +341,7 @@ export class AcpSessionManager {
   ): Promise<{
     sessionId: string
     configState: AcpConfigState
+    promptCapabilities?: schema.PromptCapabilities
     availableModes?: Array<{ id: string; name: string; description: string }>
     currentModeId?: string
     detachHandlers?: Array<() => void>
@@ -356,17 +364,95 @@ export class AcpSessionManager {
             currentModeId?: string
           }
         | undefined
-      let sessionResponse: schema.LoadSessionResponse | schema.NewSessionResponse | undefined
+      let sessionResponse:
+        | schema.LoadSessionResponse
+        | schema.NewSessionResponse
+        | schema.ResumeSessionResponse
+        | undefined
 
+      const connection = handle.connection as AcpConnectionWithUnstableSessionLifecycle
+      const canResumeSession = Boolean(
+        handle.supportsSessionResume && connection.unstable_resumeSession
+      )
       const canLoadSession = Boolean(handle.supportsLoadSession)
       console.info(`[ACP] Initializing ACP session for agent ${agent.id}:`, {
         conversationId,
         workdir,
+        canResumeSession,
         canLoadSession,
         persistedSessionId,
         mcpServerCount: mcpServers.length
       })
-      if (canLoadSession && persistedSessionId) {
+      if (canResumeSession && persistedSessionId) {
+        try {
+          const resumeRequestSummary = {
+            cwd: workdir,
+            sessionId: persistedSessionId,
+            mcpServerCount: mcpServers.length,
+            mcpServers: summarizeMcpServers(mcpServers)
+          }
+          console.info(
+            `[ACP] Resuming persisted ACP session ${persistedSessionId} for conversation ${conversationId}`,
+            resumeRequestSummary
+          )
+          this.processManager.appendDebugEvent?.(agent.id, {
+            kind: 'request',
+            action: 'session/resume',
+            sessionId: persistedSessionId,
+            payload: resumeRequestSummary
+          })
+          this.processManager.registerSessionWorkdir(persistedSessionId, workdir, conversationId)
+          detachHandlers = this.attachSessionHooks(agent.id, persistedSessionId, hooks)
+          const resumeResponse = await connection.unstable_resumeSession!({
+            cwd: workdir,
+            mcpServers,
+            sessionId: persistedSessionId
+          })
+          sessionId = persistedSessionId
+          sessionResponse = resumeResponse
+          responseModeState = resumeResponse.modes ?? undefined
+          const resumedConfigState = normalizeAcpConfigState({
+            configOptions: resumeResponse.configOptions,
+            models: resumeResponse.models,
+            modes: resumeResponse.modes
+          })
+          if (hasAcpConfigStateData(resumedConfigState)) {
+            configState = resumedConfigState
+          }
+          console.info(
+            `[ACP] Resumed persisted session ${sessionId} for conversation ${conversationId} (agent ${agent.id})`
+          )
+          this.processManager.appendDebugEvent?.(agent.id, {
+            kind: 'response',
+            action: 'session/resume',
+            sessionId,
+            payload: summarizeSessionResponse(resumeResponse)
+          })
+        } catch (error) {
+          detachHandlers?.forEach((dispose) => {
+            try {
+              dispose()
+            } catch (disposeError) {
+              console.warn('[ACP] Failed to detach resumed session handler:', disposeError)
+            }
+          })
+          detachHandlers = undefined
+          this.processManager.clearSession(persistedSessionId)
+          console.warn(
+            `[ACP] Failed to resume persisted session ${persistedSessionId} for conversation ${conversationId}; trying load/new fallback.`,
+            error
+          )
+          this.processManager.appendDebugEvent?.(agent.id, {
+            kind: 'error',
+            action: 'session/resume',
+            sessionId: persistedSessionId,
+            message: error instanceof Error ? error.message : String(error),
+            payload: error instanceof Error ? { name: error.name, stack: error.stack } : error
+          })
+        }
+      }
+
+      if (!sessionId && canLoadSession && persistedSessionId) {
         try {
           const loadRequestSummary = {
             cwd: workdir,
@@ -529,7 +615,8 @@ export class AcpSessionManager {
         configState,
         availableModes,
         currentModeId,
-        detachHandlers
+        detachHandlers,
+        promptCapabilities: handle.promptCapabilities
       }
     } catch (error) {
       console.error(`[ACP] Failed to initialize session for agent ${agent.id}:`, error)
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpSessionPersistence.ts b/src/main/presenter/llmProviderPresenter/acp/acpSessionPersistence.ts
index 033ae058b..b3301ace5 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpSessionPersistence.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpSessionPersistence.ts
@@ -1,5 +1,8 @@
 import { app } from 'electron'
+import * as fs from 'fs'
+import type * as schema from '@agentclientprotocol/sdk/dist/schema/index.js'
 import type {
+  CONVERSATION_SETTINGS,
   AcpTurnFinishPayload,
   AcpTurnStartPayload,
   AcpSessionEntity,
@@ -7,7 +10,32 @@ import type {
   ISQLitePresenter
 } from '@shared/presenter'
 
+export interface AcpRemoteSessionSyncInput {
+  agentId: string
+  agentName: string
+  providerId: string
+  workdir: string
+  sessions: schema.SessionInfo[]
+}
+
+export interface AcpRemoteSessionSyncItem {
+  sessionId: string
+  conversationId: string
+  status: 'imported' | 'updated' | 'skipped'
+  title?: string | null
+}
+
+export interface AcpRemoteSessionSyncResult {
+  imported: number
+  updated: number
+  skipped: number
+  sessions: AcpRemoteSessionSyncItem[]
+}
+
 export class AcpSessionPersistence {
+  private readonly remoteSessionSyncLocks = new Map<string, Promise<void>>()
+  private readonly metadataMergeLocks = new Map<string, Promise<void>>()
+
   constructor(private readonly sqlitePresenter: ISQLitePresenter) {}
 
   async getSessionData(conversationId: string, agentId: string): Promise<AcpSessionEntity | null> {
@@ -59,12 +87,220 @@ export class AcpSessionPersistence {
     await this.sqlitePresenter.updateAcpSessionStatus(conversationId, agentId, status)
   }
 
+  async mergeMetadata(
+    conversationId: string,
+    agentId: string,
+    metadata: Record<string, unknown>
+  ): Promise<void> {
+    await this.withKeyLock(this.metadataMergeLocks, `${conversationId}::${agentId}`, async () => {
+      const existing = await this.getSessionData(conversationId, agentId)
+      await this.saveSessionData(
+        conversationId,
+        agentId,
+        existing?.sessionId ?? null,
+        existing?.workdir ?? null,
+        existing?.status ?? 'idle',
+        {
+          ...existing?.metadata,
+          ...metadata
+        }
+      )
+    })
+  }
+
+  async syncRemoteSessions(input: AcpRemoteSessionSyncInput): Promise<AcpRemoteSessionSyncResult> {
+    const now = new Date().toISOString()
+    const result: AcpRemoteSessionSyncResult = {
+      imported: 0,
+      updated: 0,
+      skipped: 0,
+      sessions: []
+    }
+
+    for (const remoteSession of input.sessions) {
+      if (!remoteSession.sessionId) {
+        result.skipped += 1
+        result.sessions.push({
+          sessionId: '',
+          conversationId: '',
+          status: 'skipped',
+          title: remoteSession.title
+        })
+        continue
+      }
+
+      const item = await this.withRemoteSessionSyncLock(
+        input.agentId,
+        remoteSession.sessionId,
+        () => this.syncRemoteSession(input, remoteSession, now)
+      )
+
+      result[item.status] += 1
+      result.sessions.push(item)
+    }
+
+    return result
+  }
+
+  private async syncRemoteSession(
+    input: AcpRemoteSessionSyncInput,
+    remoteSession: schema.SessionInfo,
+    syncedAt: string
+  ): Promise<AcpRemoteSessionSyncItem> {
+    const sessionWorkdir = this.resolveRemoteSessionWorkdir(remoteSession, input.workdir)
+    const metadata = this.buildRemoteSessionMetadata(input.agentName, remoteSession, syncedAt)
+    const existing = await this.sqlitePresenter.getAcpSessionByAgentAndSessionId(
+      input.agentId,
+      remoteSession.sessionId
+    )
+
+    if (existing) {
+      return this.updateRemoteSessionLink(
+        input,
+        remoteSession,
+        existing,
+        sessionWorkdir,
+        metadata,
+        syncedAt
+      )
+    }
+
+    const conversationId = await this.sqlitePresenter.createConversation(
+      this.buildRemoteSessionTitle(input.agentName, remoteSession),
+      this.buildConversationSettings(input.providerId, input.agentId, sessionWorkdir)
+    )
+
+    try {
+      await this.saveSessionData(
+        conversationId,
+        input.agentId,
+        remoteSession.sessionId,
+        sessionWorkdir,
+        'idle',
+        {
+          ...metadata,
+          acpSync: {
+            importedAt: syncedAt,
+            lastSyncedAt: syncedAt,
+            source: 'session/list'
+          }
+        }
+      )
+    } catch (error) {
+      const concurrentExisting = await this.sqlitePresenter.getAcpSessionByAgentAndSessionId(
+        input.agentId,
+        remoteSession.sessionId
+      )
+      if (!concurrentExisting) {
+        await this.deleteConversationSilently(conversationId)
+        throw error
+      }
+
+      await this.deleteConversationSilently(conversationId)
+      return this.updateRemoteSessionLink(
+        input,
+        remoteSession,
+        concurrentExisting,
+        sessionWorkdir,
+        metadata,
+        syncedAt
+      )
+    }
+
+    return {
+      sessionId: remoteSession.sessionId,
+      conversationId,
+      status: 'imported',
+      title: remoteSession.title
+    }
+  }
+
+  private async updateRemoteSessionLink(
+    input: AcpRemoteSessionSyncInput,
+    remoteSession: schema.SessionInfo,
+    existing: AcpSessionEntity,
+    syncedWorkdir: string,
+    metadata: Record<string, unknown>,
+    syncedAt: string
+  ): Promise<AcpRemoteSessionSyncItem> {
+    const existingSync = this.getRecord(existing.metadata?.acpSync)
+    const existingWorkdir = this.resolveExistingSessionWorkdir(existing.workdir, syncedWorkdir)
+    await this.saveSessionData(
+      existing.conversationId,
+      input.agentId,
+      remoteSession.sessionId,
+      existingWorkdir,
+      existing.status ?? 'idle',
+      {
+        ...existing.metadata,
+        ...metadata,
+        acpSync: {
+          ...existingSync,
+          lastSyncedAt: syncedAt,
+          source: 'session/list'
+        }
+      }
+    )
+
+    return {
+      sessionId: remoteSession.sessionId,
+      conversationId: existing.conversationId,
+      status: 'updated',
+      title: remoteSession.title
+    }
+  }
+
+  private async withRemoteSessionSyncLock<T>(
+    agentId: string,
+    sessionId: string,
+    task: () => Promise<T>
+  ): Promise<T> {
+    return this.withKeyLock(this.remoteSessionSyncLocks, `${agentId}::${sessionId}`, task)
+  }
+
+  private async withKeyLock<T>(
+    locks: Map<string, Promise<void>>,
+    key: string,
+    task: () => Promise<T>
+  ): Promise<T> {
+    const previous = locks.get(key)
+    let release!: () => void
+    const current = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const next = previous ? previous.catch(() => undefined).then(() => current) : current
+    locks.set(key, next)
+
+    if (previous) {
+      await previous.catch(() => undefined)
+    }
+
+    try {
+      return await task()
+    } finally {
+      release()
+      if (locks.get(key) === next) {
+        locks.delete(key)
+      }
+    }
+  }
+
+  private async deleteConversationSilently(conversationId: string): Promise<void> {
+    try {
+      await this.sqlitePresenter.deleteConversation(conversationId)
+    } catch (error) {
+      console.warn(
+        `[ACP] Failed to delete duplicate imported conversation ${conversationId}:`,
+        error
+      )
+    }
+  }
+
   async deleteSession(conversationId: string, agentId: string): Promise<void> {
     await this.sqlitePresenter.deleteAcpSession(conversationId, agentId)
   }
 
   async clearSession(conversationId: string, agentId: string): Promise<void> {
-    await this.updateSessionId(conversationId, agentId, null)
     await this.updateStatus(conversationId, agentId, 'idle')
   }
 
@@ -82,17 +318,105 @@ export class AcpSessionPersistence {
   }
 
   resolveWorkdir(workdir?: string | null): string {
-    if (workdir && workdir.trim().length > 0) {
-      return workdir
+    if (workdir && this.isWorkdirUsable(workdir)) {
+      return workdir.trim()
     }
     return this.getDefaultWorkdir()
   }
 
+  isWorkdirUsable(workdir?: string | null): boolean {
+    const trimmed = workdir?.trim()
+    if (!trimmed) return false
+
+    try {
+      return Boolean(fs.existsSync(trimmed) && fs.statSync(trimmed).isDirectory())
+    } catch {
+      return false
+    }
+  }
+
   getDefaultWorkdir(): string {
     try {
-      return app.getPath('home')
+      const home = app.getPath('home')
+      if (this.isWorkdirUsable(home)) {
+        return home
+      }
     } catch {
-      return process.env.HOME || process.cwd()
+      // fall through to process fallbacks
+    }
+
+    if (this.isWorkdirUsable(process.env.HOME)) {
+      return process.env.HOME as string
     }
+
+    return process.cwd()
+  }
+
+  private resolveRemoteSessionWorkdir(session: schema.SessionInfo, fallback: string): string {
+    if (this.isWorkdirUsable(session.cwd)) {
+      return session.cwd.trim()
+    }
+    return this.resolveWorkdir(fallback)
+  }
+
+  private resolveExistingSessionWorkdir(
+    existingWorkdir: string | null | undefined,
+    syncedWorkdir: string
+  ): string {
+    const trimmed = existingWorkdir?.trim()
+    if (trimmed && this.isWorkdirUsable(trimmed)) {
+      return trimmed
+    }
+    return syncedWorkdir
+  }
+
+  private buildConversationSettings(
+    providerId: string,
+    agentId: string,
+    workdir: string
+  ): Partial<CONVERSATION_SETTINGS> {
+    return {
+      providerId,
+      modelId: agentId,
+      chatMode: 'acp agent',
+      agentWorkspacePath: workdir,
+      acpWorkdirMap: {
+        [agentId]: workdir
+      }
+    }
+  }
+
+  private buildRemoteSessionTitle(agentName: string, session: schema.SessionInfo): string {
+    const title = session.title?.trim()
+    if (title) return title
+
+    const shortSessionId =
+      session.sessionId.length > 12 ? session.sessionId.slice(0, 12) : session.sessionId
+    return `${agentName} ${shortSessionId}`
+  }
+
+  private buildRemoteSessionMetadata(
+    agentName: string,
+    session: schema.SessionInfo,
+    syncedAt: string
+  ): Record<string, unknown> {
+    return {
+      agentName,
+      remoteSession: {
+        protocol: 'acp',
+        sessionId: session.sessionId,
+        cwd: session.cwd,
+        title: session.title ?? null,
+        updatedAt: session.updatedAt ?? null,
+        meta: session._meta ?? null,
+        syncedAt
+      }
+    }
+  }
+
+  private getRecord(value: unknown): Record<string, unknown> | null {
+    return value && typeof value === 'object' && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null
   }
 }
diff --git a/src/main/presenter/llmProviderPresenter/acp/acpTerminalManager.ts b/src/main/presenter/llmProviderPresenter/acp/acpTerminalManager.ts
index 5fbb8fdae..f9510aa83 100644
--- a/src/main/presenter/llmProviderPresenter/acp/acpTerminalManager.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/acpTerminalManager.ts
@@ -75,19 +75,6 @@ export class AcpTerminalManager {
       }
     )
 
-    // Build command based on platform
-    const platform = process.platform
-    let shell: string
-    let shellArgs: string[]
-
-    if (platform === 'win32') {
-      shell = 'powershell.exe'
-      shellArgs = ['-NoLogo', '-Command', params.command, ...(params.args ?? [])]
-    } else {
-      shell = '/bin/bash'
-      shellArgs = ['-c', [params.command, ...(params.args ?? [])].join(' ')]
-    }
-
     // Build environment from env array
     const env: Record<string, string> = { ...process.env } as Record<string, string>
     if (params.env) {
@@ -96,7 +83,7 @@ export class AcpTerminalManager {
       }
     }
 
-    const ptyProcess = spawn(shell, shellArgs, {
+    const ptyProcess = spawn(params.command, params.args ?? [], {
       name: 'xterm-256color',
       cols: 120,
       rows: 30,
@@ -121,20 +108,10 @@ export class AcpTerminalManager {
     // Collect output
     ptyProcess.onData((data) => {
       if (state.released) return
-
-      const currentBytes = Buffer.byteLength(state.outputBuffer, 'utf-8')
-      const newBytes = Buffer.byteLength(data, 'utf-8')
-
-      if (currentBytes + newBytes <= state.maxOutputBytes) {
-        state.outputBuffer += data
-      } else {
-        // Truncate at UTF-8 boundary
-        const remaining = state.maxOutputBytes - currentBytes
-        if (remaining > 0) {
-          state.outputBuffer += this.truncateAtCharBoundary(data, remaining)
-        }
-        state.truncated = true
-      }
+      const nextBuffer = state.outputBuffer + data
+      state.outputBuffer = this.retainTailAtCharBoundary(nextBuffer, state.maxOutputBytes)
+      state.truncated =
+        state.truncated || Buffer.byteLength(nextBuffer, 'utf-8') > state.maxOutputBytes
     })
 
     // Handle exit
@@ -249,17 +226,17 @@ export class AcpTerminalManager {
     return state
   }
 
-  private truncateAtCharBoundary(str: string, maxBytes: number): string {
+  private retainTailAtCharBoundary(str: string, maxBytes: number): string {
+    if (maxBytes <= 0) return ''
+
     const buf = Buffer.from(str, 'utf-8')
     if (buf.length <= maxBytes) return str
 
-    // Find valid UTF-8 boundary by slicing and checking
-    let truncated = buf.subarray(0, maxBytes)
-    while (truncated.length > 0) {
-      try {
-        return truncated.toString('utf-8')
-      } catch {
-        truncated = truncated.subarray(0, truncated.length - 1)
+    for (let start = buf.length - maxBytes; start < buf.length; start += 1) {
+      const tail = buf.subarray(start)
+      const decoded = tail.toString('utf-8')
+      if (!decoded.startsWith('\uFFFD')) {
+        return decoded
       }
     }
     return ''
diff --git a/src/main/presenter/llmProviderPresenter/acp/index.ts b/src/main/presenter/llmProviderPresenter/acp/index.ts
index 0b42d49d2..1170a048e 100644
--- a/src/main/presenter/llmProviderPresenter/acp/index.ts
+++ b/src/main/presenter/llmProviderPresenter/acp/index.ts
@@ -8,7 +8,12 @@ export {
 } from './acpProcessManager'
 export { AcpSessionManager, type AcpSessionRecord } from './acpSessionManager'
 export { AcpSessionPersistence } from './acpSessionPersistence'
-export { buildClientCapabilities, type AcpCapabilityOptions } from './acpCapabilities'
+export {
+  buildCapabilitySnapshot,
+  buildClientCapabilities,
+  type AcpCapabilityOptions,
+  type AcpCapabilitySnapshot
+} from './acpCapabilities'
 export { AcpMessageFormatter } from './acpMessageFormatter'
 export { AcpContentMapper } from './acpContentMapper'
 export {
diff --git a/src/main/presenter/llmProviderPresenter/index.ts b/src/main/presenter/llmProviderPresenter/index.ts
index b7bab7c04..58e66d342 100644
--- a/src/main/presenter/llmProviderPresenter/index.ts
+++ b/src/main/presenter/llmProviderPresenter/index.ts
@@ -831,7 +831,7 @@ export class LLMProviderPresenter implements ILlmProviderPresenter {
   async getAcpWorkdir(conversationId: string, agentId: string): Promise<AcpWorkdirInfo> {
     const record = await this.acpSessionPersistence.getSessionData(conversationId, agentId)
     const path = this.acpSessionPersistence.resolveWorkdir(record?.workdir)
-    const isCustom = Boolean(record?.workdir && record.workdir.trim().length > 0)
+    const isCustom = this.acpSessionPersistence.isWorkdirUsable(record?.workdir)
     return { path, isCustom }
   }
 
@@ -846,7 +846,16 @@ export class LLMProviderPresenter implements ILlmProviderPresenter {
       return
     }
 
-    const trimmed = workdir?.trim() ? workdir : null
+    const requestedWorkdir = workdir?.trim() ? workdir.trim() : null
+    const trimmed =
+      requestedWorkdir && this.acpSessionPersistence.isWorkdirUsable(requestedWorkdir)
+        ? requestedWorkdir
+        : null
+    if (requestedWorkdir && !trimmed) {
+      console.warn(
+        `[ACP] Ignoring unavailable ACP workdir "${requestedWorkdir}" for conversation ${conversationId} (agent ${agentId}); using default workdir.`
+      )
+    }
     await this.acpSessionPersistence.updateWorkdir(conversationId, agentId, trimmed)
   }
 
diff --git a/src/main/presenter/llmProviderPresenter/providers/acpProvider.ts b/src/main/presenter/llmProviderPresenter/providers/acpProvider.ts
index 6f7f3d043..ae615f845 100644
--- a/src/main/presenter/llmProviderPresenter/providers/acpProvider.ts
+++ b/src/main/presenter/llmProviderPresenter/providers/acpProvider.ts
@@ -1,4 +1,5 @@
 import type * as schema from '@agentclientprotocol/sdk/dist/schema/index.js'
+import type { ClientSideConnection as ClientSideConnectionType } from '@agentclientprotocol/sdk'
 import { BaseLLMProvider, SUMMARY_TITLES_PROMPT } from '../baseProvider'
 import type {
   AcpConfigState,
@@ -54,6 +55,10 @@ type EventQueue = {
   done: () => void
 }
 
+type RunPromptOptions = {
+  onPromptSucceeded?: () => void
+}
+
 type PermissionRequestContext = {
   agent: AcpAgentConfig
   conversationId: string
@@ -98,6 +103,21 @@ type AcpConnectionWithModelSelection = {
   ) => Promise<schema.SetSessionModelResponse>
 }
 
+type AcpConnectionWithDebugLifecycle = ClientSideConnectionType &
+  AcpConnectionWithModelSelection & {
+    authenticate?: (params: schema.AuthenticateRequest) => Promise<schema.AuthenticateResponse>
+    listSessions?: (params: schema.ListSessionsRequest) => Promise<schema.ListSessionsResponse>
+    unstable_resumeSession?: (
+      params: schema.ResumeSessionRequest
+    ) => Promise<schema.ResumeSessionResponse>
+    unstable_closeSession?: (
+      params: schema.CloseSessionRequest
+    ) => Promise<schema.CloseSessionResponse>
+    unstable_forkSession?: (
+      params: schema.ForkSessionRequest
+    ) => Promise<schema.ForkSessionResponse>
+  }
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 
@@ -402,8 +422,18 @@ export class AcpProvider extends BaseLLMProvider {
           )
           this.emitSessionCommandsReady(conversationKey, agent.id, session.availableCommands ?? [])
 
-          const promptBlocks = this.messageFormatter.format(messages, modelConfig)
-          void this.runPrompt(session, promptBlocks, queue, modelConfig)
+          const formattedPrompt = this.messageFormatter.format(messages, {
+            promptCapabilities: session.promptCapabilities,
+            includeSystemPrompt: !session.systemPromptSent
+          })
+          const activeSession = session
+          void this.runPrompt(activeSession, formattedPrompt.blocks, queue, modelConfig, {
+            onPromptSucceeded: formattedPrompt.includedSystemPrompt
+              ? () => {
+                  activeSession.systemPromptSent = true
+                }
+              : undefined
+          })
         }
       }
     } catch (error) {
@@ -440,7 +470,16 @@ export class AcpProvider extends BaseLLMProvider {
     agentId: string,
     workdir: string | null
   ): Promise<void> {
-    const trimmed = workdir?.trim() ? workdir : null
+    const requestedWorkdir = workdir?.trim() ? workdir.trim() : null
+    const trimmed =
+      requestedWorkdir && this.sessionPersistence.isWorkdirUsable(requestedWorkdir)
+        ? requestedWorkdir
+        : null
+    if (requestedWorkdir && !trimmed) {
+      console.warn(
+        `[ACP] Ignoring unavailable ACP workdir "${requestedWorkdir}" for conversation ${conversationId} (agent ${agentId}); using default workdir.`
+      )
+    }
     const existing = await this.sessionPersistence.getSessionData(conversationId, agentId)
     const previous = existing?.workdir ?? null
     await this.sessionPersistence.updateWorkdir(conversationId, agentId, trimmed)
@@ -460,9 +499,16 @@ export class AcpProvider extends BaseLLMProvider {
     agentId: string,
     workdir: string
   ): Promise<void> {
-    const normalizedWorkdir = workdir?.trim()
-    if (!normalizedWorkdir) {
-      throw new Error('[ACP] Workdir is required to prepare ACP session.')
+    const requestedWorkdir = workdir?.trim()
+    const persistedWorkdir =
+      requestedWorkdir && this.sessionPersistence.isWorkdirUsable(requestedWorkdir)
+        ? requestedWorkdir
+        : null
+    const normalizedWorkdir = this.sessionPersistence.resolveWorkdir(persistedWorkdir)
+    if (requestedWorkdir && !persistedWorkdir) {
+      console.warn(
+        `[ACP] Prepare requested unavailable workdir "${requestedWorkdir}" for conversation ${conversationId}; using "${normalizedWorkdir}".`
+      )
     }
 
     const agent = await this.getAgentById(agentId)
@@ -470,7 +516,7 @@ export class AcpProvider extends BaseLLMProvider {
       throw new Error(`[ACP] ACP agent not found: ${agentId}`)
     }
 
-    await this.sessionPersistence.updateWorkdir(conversationId, agent.id, normalizedWorkdir)
+    await this.sessionPersistence.updateWorkdir(conversationId, agent.id, persistedWorkdir)
 
     const session = await this.sessionManager.getOrCreateSession(
       conversationId,
@@ -503,6 +549,14 @@ export class AcpProvider extends BaseLLMProvider {
     const agent = await this.getAgentById(agentId)
     if (!agent) return
 
+    const requestedWorkdir = workdir?.trim()
+    if (requestedWorkdir && !this.sessionPersistence.isWorkdirUsable(requestedWorkdir)) {
+      console.info(
+        `[ACP] Skipping warmup for agent ${agentId}: selected workdir "${requestedWorkdir}" is unavailable.`
+      )
+      return
+    }
+
     try {
       await this.processManager.warmupProcess(agent, workdir)
     } catch (error) {
@@ -563,7 +617,7 @@ export class AcpProvider extends BaseLLMProvider {
       }
       throw error
     }
-    const connection = handle.connection
+    const connection = handle.connection as AcpConnectionWithDebugLifecycle
     const events: AcpDebugEventEntry[] =
       typeof this.processManager.getDebugEvents === 'function'
         ? [...this.processManager.getDebugEvents(agent.id)]
@@ -635,9 +689,51 @@ export class AcpProvider extends BaseLLMProvider {
       )
     }
 
-    const resolveWorkdir = (): string | undefined => {
-      const cwd = request.workdir ?? handle.workdir
-      return cwd?.trim() || undefined
+    const resolveHandleWorkdir = (): string => {
+      const handleWorkdir = handle.workdir?.trim()
+      if (
+        handleWorkdir &&
+        (!this.sessionPersistence ||
+          typeof this.sessionPersistence.isWorkdirUsable !== 'function' ||
+          this.sessionPersistence.isWorkdirUsable(handleWorkdir))
+      ) {
+        return handleWorkdir
+      }
+      const requestedWorkdir = request.workdir?.trim()
+      if (this.sessionPersistence && typeof this.sessionPersistence.resolveWorkdir === 'function') {
+        return this.sessionPersistence.resolveWorkdir(requestedWorkdir)
+      }
+      return requestedWorkdir || process.cwd()
+    }
+
+    const normalizeWorkdir = (workdir?: string | null): string => {
+      const fallback = resolveHandleWorkdir()
+      const trimmed = workdir?.trim()
+      if (!trimmed) {
+        return fallback
+      }
+      if (
+        this.sessionPersistence &&
+        typeof this.sessionPersistence.isWorkdirUsable === 'function' &&
+        !this.sessionPersistence.isWorkdirUsable(trimmed)
+      ) {
+        return fallback
+      }
+      if (this.sessionPersistence && typeof this.sessionPersistence.resolveWorkdir === 'function') {
+        return this.sessionPersistence.resolveWorkdir(trimmed)
+      }
+      return trimmed
+    }
+
+    const resolveWorkdir = (): string => {
+      return resolveHandleWorkdir()
+    }
+
+    const resolvePayloadWorkdir = (workdir: unknown): string | undefined => {
+      if (typeof workdir !== 'string' || !workdir.trim()) {
+        return undefined
+      }
+      return normalizeWorkdir(workdir)
     }
 
     const resolveMcpServers = async (): Promise<schema.McpServer[]> => {
@@ -659,15 +755,41 @@ export class AcpProvider extends BaseLLMProvider {
           })
           break
         }
+        case 'authenticate': {
+          if (!connection.authenticate) {
+            throw new Error('authenticate is not supported by this SDK connection')
+          }
+          const methodId =
+            isPlainObject(request.payload) && typeof request.payload.methodId === 'string'
+              ? request.payload.methodId
+              : undefined
+          if (!methodId) {
+            throw new Error('methodId is required for authenticate')
+          }
+          const body: schema.AuthenticateRequest = { methodId }
+          if (isPlainObject(request.payload?._meta)) {
+            body._meta = request.payload._meta
+          }
+          pushEvent({ kind: 'request', action: 'authenticate', payload: body })
+          const response = await connection.authenticate(body)
+          pushEvent({
+            kind: 'response',
+            action: 'authenticate',
+            sessionId: activeSessionId,
+            payload: response ?? {}
+          })
+          break
+        }
         case 'newSession': {
           const basePayload: schema.NewSessionRequest = {
-            cwd: resolveWorkdir() ?? process.cwd(),
+            cwd: resolveWorkdir(),
             mcpServers: await resolveMcpServers()
           }
           const body = { ...basePayload }
           if (isPlainObject(request.payload)) {
-            if (typeof request.payload.cwd === 'string' && request.payload.cwd.trim()) {
-              body.cwd = request.payload.cwd
+            const payloadWorkdir = resolvePayloadWorkdir(request.payload.cwd)
+            if (payloadWorkdir) {
+              body.cwd = payloadWorkdir
             }
             if (Array.isArray(request.payload.mcpServers)) {
               body.mcpServers = request.payload.mcpServers as schema.McpServer[]
@@ -700,13 +822,14 @@ export class AcpProvider extends BaseLLMProvider {
             throw new Error('Session ID is required for loadSession')
           }
           const body: schema.LoadSessionRequest = {
-            cwd: resolveWorkdir() ?? process.cwd(),
+            cwd: resolveWorkdir(),
             mcpServers: await resolveMcpServers(),
             sessionId: sessionToLoad
           }
           if (payloadOverrides) {
-            if (typeof payloadOverrides.cwd === 'string') {
-              body.cwd = payloadOverrides.cwd
+            const payloadWorkdir = resolvePayloadWorkdir(payloadOverrides.cwd)
+            if (payloadWorkdir) {
+              body.cwd = payloadWorkdir
             }
             if (Array.isArray(payloadOverrides.mcpServers)) {
               body.mcpServers = payloadOverrides.mcpServers as schema.McpServer[]
@@ -733,6 +856,201 @@ export class AcpProvider extends BaseLLMProvider {
           })
           break
         }
+        case 'sessionList': {
+          if (!connection.listSessions) {
+            throw new Error('session/list is not supported by this SDK connection')
+          }
+          if (!handle.supportsSessionList) {
+            throw new Error('Agent did not advertise sessionCapabilities.list')
+          }
+          const payloadOverrides = isPlainObject(request.payload) ? request.payload : undefined
+          const body: schema.ListSessionsRequest = {
+            cwd: resolveWorkdir()
+          }
+          if (payloadOverrides) {
+            const payloadWorkdir = resolvePayloadWorkdir(payloadOverrides.cwd)
+            if (payloadWorkdir) {
+              body.cwd = payloadWorkdir
+            }
+            if (typeof payloadOverrides.cursor === 'string') {
+              body.cursor = payloadOverrides.cursor
+            }
+            if (isPlainObject(payloadOverrides._meta)) {
+              body._meta = payloadOverrides._meta
+            }
+          }
+          const shouldSyncRemoteSessions = Boolean(payloadOverrides?.sync)
+          const allSessions: schema.SessionInfo[] = []
+          let cursor: string | null | undefined = body.cursor
+          do {
+            const pageBody = { ...body, cursor }
+            pushEvent({ kind: 'request', action: 'session/list', payload: pageBody })
+            const response = await connection.listSessions(pageBody)
+            allSessions.push(...response.sessions)
+            cursor = response.nextCursor
+            pushEvent({
+              kind: 'response',
+              action: 'session/list',
+              payload: response
+            })
+          } while (cursor)
+          pushEvent({
+            kind: 'lifecycle',
+            action: 'session/list.complete',
+            payload: { count: allSessions.length }
+          })
+          if (shouldSyncRemoteSessions) {
+            const syncResult = await this.sessionPersistence.syncRemoteSessions({
+              agentId: agent.id,
+              agentName: agent.name,
+              providerId: this.provider.id,
+              workdir: body.cwd ?? resolveWorkdir(),
+              sessions: allSessions
+            })
+            pushEvent({
+              kind: 'lifecycle',
+              action: 'session/list.sync',
+              payload: syncResult
+            })
+          }
+          break
+        }
+        case 'sessionResume': {
+          if (!connection.unstable_resumeSession) {
+            throw new Error('session/resume is not supported by this SDK connection')
+          }
+          if (!handle.supportsSessionResume) {
+            throw new Error('Agent did not advertise sessionCapabilities.resume')
+          }
+          const payloadOverrides = isPlainObject(request.payload) ? request.payload : undefined
+          const sessionToResume =
+            payloadOverrides && typeof payloadOverrides.sessionId === 'string'
+              ? payloadOverrides.sessionId
+              : activeSessionId
+          if (!sessionToResume) {
+            throw new Error('sessionId is required for sessionResume')
+          }
+          const body: schema.ResumeSessionRequest = {
+            cwd: resolveWorkdir(),
+            mcpServers: await resolveMcpServers(),
+            sessionId: sessionToResume
+          }
+          if (payloadOverrides) {
+            const payloadWorkdir = resolvePayloadWorkdir(payloadOverrides.cwd)
+            if (payloadWorkdir) {
+              body.cwd = payloadWorkdir
+            }
+            if (Array.isArray(payloadOverrides.mcpServers)) {
+              body.mcpServers = payloadOverrides.mcpServers as schema.McpServer[]
+            }
+            if (isPlainObject(payloadOverrides._meta)) {
+              body._meta = payloadOverrides._meta
+            }
+          }
+          pushEvent({
+            kind: 'request',
+            action: 'session/resume',
+            sessionId: sessionToResume,
+            payload: body
+          })
+          this.processManager.registerSessionWorkdir(sessionToResume, body.cwd)
+          attachSession(sessionToResume)
+          const response = await connection.unstable_resumeSession(body)
+          activeSessionId = sessionToResume
+          pushEvent({
+            kind: 'response',
+            action: 'session/resume',
+            sessionId: activeSessionId,
+            payload: response
+          })
+          break
+        }
+        case 'sessionClose': {
+          if (!connection.unstable_closeSession) {
+            throw new Error('session/close is not supported by this SDK connection')
+          }
+          if (!handle.supportsSessionClose) {
+            throw new Error('Agent did not advertise sessionCapabilities.close')
+          }
+          const payloadOverrides = isPlainObject(request.payload) ? request.payload : undefined
+          const sessionToClose =
+            payloadOverrides && typeof payloadOverrides.sessionId === 'string'
+              ? payloadOverrides.sessionId
+              : activeSessionId
+          if (!sessionToClose) {
+            throw new Error('sessionId is required for sessionClose')
+          }
+          const body: schema.CloseSessionRequest = { sessionId: sessionToClose }
+          if (payloadOverrides && isPlainObject(payloadOverrides._meta)) {
+            body._meta = payloadOverrides._meta
+          }
+          pushEvent({
+            kind: 'request',
+            action: 'session/close',
+            sessionId: sessionToClose,
+            payload: body
+          })
+          const response = await connection.unstable_closeSession(body)
+          this.processManager.clearSession(sessionToClose)
+          activeSessionId = undefined
+          pushEvent({
+            kind: 'response',
+            action: 'session/close',
+            sessionId: sessionToClose,
+            payload: response
+          })
+          break
+        }
+        case 'sessionFork': {
+          if (!connection.unstable_forkSession) {
+            throw new Error('session/fork is not supported by this SDK connection')
+          }
+          if (!handle.supportsSessionFork) {
+            throw new Error('Agent did not advertise sessionCapabilities.fork')
+          }
+          const payloadOverrides = isPlainObject(request.payload) ? request.payload : undefined
+          const sessionToFork =
+            payloadOverrides && typeof payloadOverrides.sessionId === 'string'
+              ? payloadOverrides.sessionId
+              : activeSessionId
+          if (!sessionToFork) {
+            throw new Error('sessionId is required for sessionFork')
+          }
+          const body: schema.ForkSessionRequest = {
+            cwd: resolveWorkdir(),
+            mcpServers: await resolveMcpServers(),
+            sessionId: sessionToFork
+          }
+          if (payloadOverrides) {
+            const payloadWorkdir = resolvePayloadWorkdir(payloadOverrides.cwd)
+            if (payloadWorkdir) {
+              body.cwd = payloadWorkdir
+            }
+            if (Array.isArray(payloadOverrides.mcpServers)) {
+              body.mcpServers = payloadOverrides.mcpServers as schema.McpServer[]
+            }
+          }
+          if (payloadOverrides && isPlainObject(payloadOverrides._meta)) {
+            body._meta = payloadOverrides._meta
+          }
+          pushEvent({
+            kind: 'request',
+            action: 'session/fork',
+            sessionId: sessionToFork,
+            payload: body
+          })
+          const response = await connection.unstable_forkSession(body)
+          activeSessionId = response.sessionId
+          this.processManager.registerSessionWorkdir(activeSessionId, body.cwd)
+          attachSession(activeSessionId)
+          pushEvent({
+            kind: 'response',
+            action: 'session/fork',
+            sessionId: activeSessionId,
+            payload: response
+          })
+          break
+        }
         case 'prompt': {
           if (!activeSessionId) {
             throw new Error('Session ID is required for prompt')
@@ -911,7 +1229,8 @@ export class AcpProvider extends BaseLLMProvider {
     session: AcpSessionRecord,
     prompt: schema.ContentBlock[],
     queue: EventQueue,
-    modelConfig: ModelConfig
+    modelConfig: ModelConfig,
+    options: RunPromptOptions = {}
   ): Promise<void> {
     const timeoutMs = this.resolveModelRequestTimeout(modelConfig)
     let timeoutId: NodeJS.Timeout | null = null
@@ -973,6 +1292,7 @@ export class AcpProvider extends BaseLLMProvider {
             })
           ])
         : promptRequest)
+      options.onPromptSucceeded?.()
       const responseSummary = {
         sessionId: session.sessionId,
         conversationId,
@@ -1104,6 +1424,28 @@ export class AcpProvider extends BaseLLMProvider {
         mapped.configState
       )
     }
+
+    if ((mapped.sessionInfo || mapped.usage) && currentSession) {
+      const metadata = {
+        ...currentSession.metadata,
+        ...(mapped.sessionInfo
+          ? {
+              acpSessionInfo: mapped.sessionInfo
+            }
+          : {}),
+        ...(mapped.usage
+          ? {
+              acpUsage: mapped.usage
+            }
+          : {})
+      }
+      currentSession.metadata = metadata
+      void this.sessionPersistence
+        .mergeMetadata(conversationId, agentId, metadata)
+        .catch((error) => {
+          console.warn('[ACP] Failed to persist ACP session update metadata:', error)
+        })
+    }
   }
 
   private emitSessionModesReady(
diff --git a/src/main/presenter/sqlitePresenter/index.ts b/src/main/presenter/sqlitePresenter/index.ts
index d45a77767..d98ea7632 100644
--- a/src/main/presenter/sqlitePresenter/index.ts
+++ b/src/main/presenter/sqlitePresenter/index.ts
@@ -770,6 +770,14 @@ export class SQLitePresenter implements ISQLitePresenter {
     return row ? (row as AcpSessionEntity) : null
   }
 
+  public async getAcpSessionByAgentAndSessionId(
+    agentId: string,
+    sessionId: string
+  ): Promise<AcpSessionEntity | null> {
+    const row = await this.acpSessionsTable.getByAgentAndSessionId(agentId, sessionId)
+    return row ? (row as AcpSessionEntity) : null
+  }
+
   public async upsertAcpSession(
     conversationId: string,
     agentId: string,
diff --git a/src/main/presenter/sqlitePresenter/tables/acpSessions.ts b/src/main/presenter/sqlitePresenter/tables/acpSessions.ts
index ad9df040b..b5218261c 100644
--- a/src/main/presenter/sqlitePresenter/tables/acpSessions.ts
+++ b/src/main/presenter/sqlitePresenter/tables/acpSessions.ts
@@ -44,25 +44,71 @@ export class AcpSessionsTable extends BaseTable {
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         conversation_id TEXT NOT NULL,
         agent_id TEXT NOT NULL,
-        session_id TEXT UNIQUE,
+        session_id TEXT,
         workdir TEXT,
         status TEXT NOT NULL DEFAULT 'idle' CHECK(status IN ('idle', 'active', 'error')),
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
         metadata TEXT,
-        UNIQUE(conversation_id, agent_id)
+        UNIQUE(conversation_id, agent_id),
+        UNIQUE(agent_id, session_id)
       );
       CREATE INDEX IF NOT EXISTS idx_acp_sessions_session_id ON acp_sessions(session_id);
       CREATE INDEX IF NOT EXISTS idx_acp_sessions_agent ON acp_sessions(agent_id);
     `
   }
 
-  getMigrationSQL(_version: number): string | null {
+  getMigrationSQL(version: number): string | null {
+    if (version === 30) {
+      return `
+        DROP TABLE IF EXISTS acp_sessions_migrated;
+        CREATE TABLE acp_sessions_migrated (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          conversation_id TEXT NOT NULL,
+          agent_id TEXT NOT NULL,
+          session_id TEXT,
+          workdir TEXT,
+          status TEXT NOT NULL DEFAULT 'idle' CHECK(status IN ('idle', 'active', 'error')),
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL,
+          metadata TEXT,
+          UNIQUE(conversation_id, agent_id),
+          UNIQUE(agent_id, session_id)
+        );
+        INSERT OR IGNORE INTO acp_sessions_migrated (
+          id,
+          conversation_id,
+          agent_id,
+          session_id,
+          workdir,
+          status,
+          created_at,
+          updated_at,
+          metadata
+        )
+        SELECT
+          id,
+          conversation_id,
+          agent_id,
+          session_id,
+          workdir,
+          status,
+          created_at,
+          updated_at,
+          metadata
+        FROM acp_sessions
+        ORDER BY updated_at DESC;
+        DROP TABLE acp_sessions;
+        ALTER TABLE acp_sessions_migrated RENAME TO acp_sessions;
+        CREATE INDEX IF NOT EXISTS idx_acp_sessions_session_id ON acp_sessions(session_id);
+        CREATE INDEX IF NOT EXISTS idx_acp_sessions_agent ON acp_sessions(agent_id);
+      `
+    }
     return null
   }
 
   getLatestVersion(): number {
-    return 0
+    return 30
   }
 
   async getByConversationAndAgent(
@@ -83,6 +129,21 @@ export class AcpSessionsTable extends BaseTable {
     return row ? this.mapRow(row) : null
   }
 
+  async getByAgentAndSessionId(agentId: string, sessionId: string): Promise<AcpSessionRow | null> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT *
+        FROM acp_sessions
+        WHERE agent_id = ? AND session_id = ?
+        LIMIT 1
+      `
+      )
+      .get(agentId, sessionId) as AcpSessionDbRow | undefined
+
+    return row ? this.mapRow(row) : null
+  }
+
   async upsert(conversationId: string, agentId: string, data: AcpSessionUpsertData): Promise<void> {
     const now = Date.now()
     const payload = {
diff --git a/src/renderer/settings/components/AcpDebugDialog.vue b/src/renderer/settings/components/AcpDebugDialog.vue
index f388c633d..a607ecac8 100644
--- a/src/renderer/settings/components/AcpDebugDialog.vue
+++ b/src/renderer/settings/components/AcpDebugDialog.vue
@@ -252,6 +252,10 @@ const methodOptions = computed(() => [
     value: 'initialize' as const,
     label: t('settings.acp.debug.methods.initialize')
   },
+  {
+    value: 'authenticate' as const,
+    label: t('settings.acp.debug.methods.authenticate')
+  },
   {
     value: 'newSession' as const,
     label: t('settings.acp.debug.methods.newSession')
@@ -260,6 +264,22 @@ const methodOptions = computed(() => [
     value: 'loadSession' as const,
     label: t('settings.acp.debug.methods.loadSession')
   },
+  {
+    value: 'sessionList' as const,
+    label: t('settings.acp.debug.methods.sessionList')
+  },
+  {
+    value: 'sessionResume' as const,
+    label: t('settings.acp.debug.methods.sessionResume')
+  },
+  {
+    value: 'sessionClose' as const,
+    label: t('settings.acp.debug.methods.sessionClose')
+  },
+  {
+    value: 'sessionFork' as const,
+    label: t('settings.acp.debug.methods.sessionFork')
+  },
   {
     value: 'prompt' as const,
     label: t('settings.acp.debug.methods.prompt')
@@ -287,9 +307,16 @@ const methodOptions = computed(() => [
 ])
 
 const requiresSession = computed(() =>
-  ['prompt', 'cancel', 'setSessionMode', 'setSessionModel', 'loadSession'].includes(
-    selectedMethod.value
-  )
+  [
+    'prompt',
+    'cancel',
+    'setSessionMode',
+    'setSessionModel',
+    'loadSession',
+    'sessionResume',
+    'sessionClose',
+    'sessionFork'
+  ].includes(selectedMethod.value)
 )
 
 const requiresCustomMethod = computed(() =>
@@ -334,6 +361,8 @@ const templateForMethod = (method: AcpDebugRequest['action']) => {
   switch (method) {
     case 'initialize':
       return {}
+    case 'authenticate':
+      return { methodId: '' }
     case 'newSession':
       return {
         ...(workdirPath.value ? { cwd: workdirPath.value } : {}),
@@ -344,6 +373,27 @@ const templateForMethod = (method: AcpDebugRequest['action']) => {
         sessionId: debugSessionId.value,
         ...(workdirPath.value ? { cwd: workdirPath.value } : {})
       }
+    case 'sessionList':
+      return {
+        ...(workdirPath.value ? { cwd: workdirPath.value } : {}),
+        sync: true
+      }
+    case 'sessionResume':
+      return {
+        sessionId: debugSessionId.value,
+        ...(workdirPath.value ? { cwd: workdirPath.value } : {}),
+        mcpServers: []
+      }
+    case 'sessionClose':
+      return {
+        sessionId: debugSessionId.value
+      }
+    case 'sessionFork':
+      return {
+        sessionId: debugSessionId.value,
+        ...(workdirPath.value ? { cwd: workdirPath.value } : {}),
+        mcpServers: []
+      }
     case 'prompt':
       return {
         prompt: [{ type: 'text', text: 'ping' }]
@@ -373,7 +423,11 @@ const resetPayload = () => {
 const applyWorkdirToPayload = (
   payload: Record<string, unknown> | undefined
 ): Record<string, unknown> | undefined => {
-  if (!['newSession', 'loadSession'].includes(selectedMethod.value)) {
+  if (
+    !['newSession', 'loadSession', 'sessionList', 'sessionResume', 'sessionFork'].includes(
+      selectedMethod.value
+    )
+  ) {
     return payload
   }
   const base = payload ?? {}
@@ -384,7 +438,12 @@ const applyWorkdirToPayload = (
 }
 
 const syncWorkdirIntoPayload = () => {
-  if (!['newSession', 'loadSession'].includes(selectedMethod.value)) return
+  if (
+    !['newSession', 'loadSession', 'sessionList', 'sessionResume', 'sessionFork'].includes(
+      selectedMethod.value
+    )
+  )
+    return
   if (!payloadText.value.trim()) return
   try {
     const parsed = JSON.parse(payloadText.value) ?? {}
@@ -452,6 +511,9 @@ const parsePayload = () => {
   return JSON.parse(payloadText.value)
 }
 
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
 const handleSend = async () => {
   let parsedPayload: Record<string, unknown> | undefined
   try {
@@ -481,7 +543,16 @@ const handleSend = async () => {
     return
   }
 
-  const sessionId = requiresSession.value ? debugSessionId.value : undefined
+  const payloadSessionId =
+    isPlainObject(parsedPayload) &&
+    typeof parsedPayload.sessionId === 'string' &&
+    parsedPayload.sessionId.trim()
+      ? parsedPayload.sessionId.trim()
+      : undefined
+  const fallbackSessionId = requiresSession.value
+    ? debugSessionId.value.trim() || undefined
+    : undefined
+  const sessionId = payloadSessionId ?? fallbackSessionId
   const payloadToSend = applyWorkdirToPayload(parsedPayload)
 
   loading.value = true
diff --git a/src/renderer/src/i18n/da-DK/settings.json b/src/renderer/src/i18n/da-DK/settings.json
index 6b0fdf789..0e63eaea7 100644
--- a/src/renderer/src/i18n/da-DK/settings.json
+++ b/src/renderer/src/i18n/da-DK/settings.json
@@ -1550,6 +1550,11 @@
       "events": "Hændelser",
       "format": "Formater JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/aflys",
         "extMethod": "ext/metode",
         "extNotification": "ext/meddelelse",
diff --git a/src/renderer/src/i18n/de-DE/settings.json b/src/renderer/src/i18n/de-DE/settings.json
index c8dee2982..0f40594af 100644
--- a/src/renderer/src/i18n/de-DE/settings.json
+++ b/src/renderer/src/i18n/de-DE/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Bitte Erweiterungsmethodennamen eingeben",
       "requestFailed": "Anfrage fehlgeschlagen",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "initialize",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/en-US/settings.json b/src/renderer/src/i18n/en-US/settings.json
index 27d310987..a52f60c3e 100644
--- a/src/renderer/src/i18n/en-US/settings.json
+++ b/src/renderer/src/i18n/en-US/settings.json
@@ -1709,11 +1709,16 @@
       "customMethodRequired": "Provide a method name for extension calls",
       "requestFailed": "Request failed",
       "methods": {
+        "authenticate": "authenticate",
         "initialize": "initialize",
-        "newSession": "session/new",
         "loadSession": "session/load",
+        "newSession": "session/new",
         "prompt": "session/prompt",
         "cancel": "session/cancel",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "setSessionMode": "session/setMode",
         "setSessionModel": "session/setModel",
         "extMethod": "ext/method",
diff --git a/src/renderer/src/i18n/es-ES/settings.json b/src/renderer/src/i18n/es-ES/settings.json
index 80dcce35f..1d802a1dc 100644
--- a/src/renderer/src/i18n/es-ES/settings.json
+++ b/src/renderer/src/i18n/es-ES/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Proporcionar un nombre de método para llamadas de extensión",
       "requestFailed": "Solicitud fallida",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "inicializar",
         "newSession": "sesión/nuevo",
         "loadSession": "sesión/carga",
diff --git a/src/renderer/src/i18n/fa-IR/settings.json b/src/renderer/src/i18n/fa-IR/settings.json
index e24663454..7ff773591 100644
--- a/src/renderer/src/i18n/fa-IR/settings.json
+++ b/src/renderer/src/i18n/fa-IR/settings.json
@@ -1643,6 +1643,11 @@
       "events": "رویداد",
       "format": "فرمت JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/cancel",
         "extMethod": "ext/method",
         "extNotification": "ext/notification",
diff --git a/src/renderer/src/i18n/fr-FR/settings.json b/src/renderer/src/i18n/fr-FR/settings.json
index 8353ffe71..3fdb48565 100644
--- a/src/renderer/src/i18n/fr-FR/settings.json
+++ b/src/renderer/src/i18n/fr-FR/settings.json
@@ -1643,6 +1643,11 @@
       "events": "événement",
       "format": "Formater JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/annuler",
         "extMethod": "poste/méthode",
         "extNotification": "poste/notification",
diff --git a/src/renderer/src/i18n/he-IL/settings.json b/src/renderer/src/i18n/he-IL/settings.json
index 79cfd34c4..9ea034f97 100644
--- a/src/renderer/src/i18n/he-IL/settings.json
+++ b/src/renderer/src/i18n/he-IL/settings.json
@@ -1617,6 +1617,11 @@
       "events": "מִקרֶה",
       "format": "פורמט JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "הפעלה/ביטול",
         "extMethod": "הרחבה/שיטה",
         "extNotification": "שלוחה/הודעה",
diff --git a/src/renderer/src/i18n/id-ID/settings.json b/src/renderer/src/i18n/id-ID/settings.json
index b43b8d0ec..9b6ceacfb 100644
--- a/src/renderer/src/i18n/id-ID/settings.json
+++ b/src/renderer/src/i18n/id-ID/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Silakan isi nama metode ekstensi",
       "requestFailed": "Permintaan gagal",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "initialize",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/it-IT/settings.json b/src/renderer/src/i18n/it-IT/settings.json
index 9e99c94aa..e7f2638a2 100644
--- a/src/renderer/src/i18n/it-IT/settings.json
+++ b/src/renderer/src/i18n/it-IT/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Inserisci nome metodo esteso",
       "requestFailed": "Richiesta non riuscita",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "initialize",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/ja-JP/settings.json b/src/renderer/src/i18n/ja-JP/settings.json
index ab8432578..86bd64d6f 100644
--- a/src/renderer/src/i18n/ja-JP/settings.json
+++ b/src/renderer/src/i18n/ja-JP/settings.json
@@ -1643,6 +1643,11 @@
       "events": "イベント",
       "format": "JSON形式",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "セッション/キャンセル",
         "extMethod": "外部/メソッド",
         "extNotification": "内線/通知",
diff --git a/src/renderer/src/i18n/ko-KR/settings.json b/src/renderer/src/i18n/ko-KR/settings.json
index ae69e4eb3..2873436cb 100644
--- a/src/renderer/src/i18n/ko-KR/settings.json
+++ b/src/renderer/src/i18n/ko-KR/settings.json
@@ -1643,6 +1643,11 @@
       "events": "이벤트",
       "format": "JSON 형식",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/cancel",
         "extMethod": "ext/method",
         "extNotification": "ext/notification",
diff --git a/src/renderer/src/i18n/ms-MY/settings.json b/src/renderer/src/i18n/ms-MY/settings.json
index 17513433c..9b38ea043 100644
--- a/src/renderer/src/i18n/ms-MY/settings.json
+++ b/src/renderer/src/i18n/ms-MY/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Sila isikan nama kaedah sambungan",
       "requestFailed": "Permintaan gagal",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "initialize",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/pl-PL/settings.json b/src/renderer/src/i18n/pl-PL/settings.json
index cef044dcf..4e93f30b1 100644
--- a/src/renderer/src/i18n/pl-PL/settings.json
+++ b/src/renderer/src/i18n/pl-PL/settings.json
@@ -1649,6 +1649,11 @@
       "customMethodRequired": "Podaj nazwę metody dla wywołań wewnętrznych",
       "requestFailed": "Żądanie nie powiodło się",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "zainicjować",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/pt-BR/settings.json b/src/renderer/src/i18n/pt-BR/settings.json
index 4625ac0ef..1487d8484 100644
--- a/src/renderer/src/i18n/pt-BR/settings.json
+++ b/src/renderer/src/i18n/pt-BR/settings.json
@@ -1643,6 +1643,11 @@
       "events": "evento",
       "format": "Formatar JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/cancel",
         "extMethod": "ext/method",
         "extNotification": "ext/notification",
diff --git a/src/renderer/src/i18n/ru-RU/settings.json b/src/renderer/src/i18n/ru-RU/settings.json
index 181b20999..694072f2d 100644
--- a/src/renderer/src/i18n/ru-RU/settings.json
+++ b/src/renderer/src/i18n/ru-RU/settings.json
@@ -1643,6 +1643,11 @@
       "events": "События",
       "format": "Формат JSON",
       "methods": {
+        "authenticate": "Аутентификация",
+        "sessionClose": "Закрыть сеанс",
+        "sessionFork": "Создать ветку сеанса",
+        "sessionList": "Список сеансов",
+        "sessionResume": "Возобновить сеанс",
         "cancel": "сеанс/отмена",
         "extMethod": "расширение/метод",
         "extNotification": "расширение/уведомление",
diff --git a/src/renderer/src/i18n/tr-TR/settings.json b/src/renderer/src/i18n/tr-TR/settings.json
index 1cc5d8214..8a4c05967 100644
--- a/src/renderer/src/i18n/tr-TR/settings.json
+++ b/src/renderer/src/i18n/tr-TR/settings.json
@@ -1671,6 +1671,11 @@
       "customMethodRequired": "Dahili çağrılar için bir yöntem adı sağlayın",
       "requestFailed": "İstek başarısız oldu",
       "methods": {
+        "authenticate": "Kimlik doğrulama",
+        "sessionClose": "Oturumu kapat",
+        "sessionFork": "Oturumu çatalla",
+        "sessionList": "Oturumları listele",
+        "sessionResume": "Oturumu sürdür",
         "initialize": "başlatmak",
         "newSession": "oturum/new",
         "loadSession": "oturum/load",
diff --git a/src/renderer/src/i18n/vi-VN/settings.json b/src/renderer/src/i18n/vi-VN/settings.json
index 47b64406a..079f651bf 100644
--- a/src/renderer/src/i18n/vi-VN/settings.json
+++ b/src/renderer/src/i18n/vi-VN/settings.json
@@ -1649,6 +1649,11 @@
       "customMethodRequired": "Cung cấp tên phương thức cho cuộc gọi mở rộng",
       "requestFailed": "Yêu cầu không thành công",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "initialize": "khởi tạo",
         "newSession": "session/new",
         "loadSession": "session/load",
diff --git a/src/renderer/src/i18n/zh-CN/settings.json b/src/renderer/src/i18n/zh-CN/settings.json
index 111b2fb8c..ef31d16c9 100644
--- a/src/renderer/src/i18n/zh-CN/settings.json
+++ b/src/renderer/src/i18n/zh-CN/settings.json
@@ -1731,11 +1731,16 @@
       "customMethodRequired": "请填写扩展方法名",
       "requestFailed": "请求失败",
       "methods": {
+        "authenticate": "authenticate",
         "initialize": "initialize",
-        "newSession": "session/new",
         "loadSession": "session/load",
+        "newSession": "session/new",
         "prompt": "session/prompt",
         "cancel": "session/cancel",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "setSessionMode": "session/setMode",
         "setSessionModel": "session/setModel",
         "extMethod": "ext/method",
diff --git a/src/renderer/src/i18n/zh-HK/settings.json b/src/renderer/src/i18n/zh-HK/settings.json
index a7fe80ec7..d385a6ebb 100644
--- a/src/renderer/src/i18n/zh-HK/settings.json
+++ b/src/renderer/src/i18n/zh-HK/settings.json
@@ -1643,6 +1643,11 @@
       "events": "事件",
       "format": "格式化 JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/cancel",
         "extMethod": "ext/method",
         "extNotification": "ext/notification",
diff --git a/src/renderer/src/i18n/zh-TW/settings.json b/src/renderer/src/i18n/zh-TW/settings.json
index 8df583a43..3cb79e03a 100644
--- a/src/renderer/src/i18n/zh-TW/settings.json
+++ b/src/renderer/src/i18n/zh-TW/settings.json
@@ -1643,6 +1643,11 @@
       "events": "事件",
       "format": "格式化 JSON",
       "methods": {
+        "authenticate": "authenticate",
+        "sessionClose": "session/close",
+        "sessionFork": "session/fork",
+        "sessionList": "session/list",
+        "sessionResume": "session/resume",
         "cancel": "session/cancel",
         "extMethod": "ext/method",
         "extNotification": "ext/notification",
diff --git a/src/shared/types/presenters/legacy.presenters.d.ts b/src/shared/types/presenters/legacy.presenters.d.ts
index 9abb01f99..c323f0157 100644
--- a/src/shared/types/presenters/legacy.presenters.d.ts
+++ b/src/shared/types/presenters/legacy.presenters.d.ts
@@ -456,6 +456,10 @@ export interface ISQLitePresenter {
   getMainMessageByParentId(conversationId: string, parentId: string): Promise<SQLITE_MESSAGE | null>
   deleteAllMessagesInConversation(conversationId: string): Promise<void>
   getAcpSession(conversationId: string, agentId: string): Promise<AcpSessionEntity | null>
+  getAcpSessionByAgentAndSessionId(
+    agentId: string,
+    sessionId: string
+  ): Promise<AcpSessionEntity | null>
   upsertAcpSession(
     conversationId: string,
     agentId: string,
@@ -916,8 +920,13 @@ export type StandaloneVideoGenerationResult = {
 
 export type AcpDebugActionType =
   | 'initialize'
+  | 'authenticate'
   | 'newSession'
   | 'loadSession'
+  | 'sessionList'
+  | 'sessionResume'
+  | 'sessionClose'
+  | 'sessionFork'
   | 'prompt'
   | 'cancel'
   | 'setSessionMode'
diff --git a/test/main/presenter/acpProvider.test.ts b/test/main/presenter/acpProvider.test.ts
index 36e5d2419..1ab87c3e1 100644
--- a/test/main/presenter/acpProvider.test.ts
+++ b/test/main/presenter/acpProvider.test.ts
@@ -107,6 +107,23 @@ describe('AcpProvider runDebugAction error handling', () => {
     ).rejects.toThrow('boom')
   })
 
+  it('skips warmup when the selected workdir is unavailable', async () => {
+    const warmupProcess = vi.fn().mockResolvedValue(undefined)
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.getAgentById = vi.fn().mockResolvedValue(agent)
+    provider.sessionPersistence = {
+      isWorkdirUsable: vi.fn().mockReturnValue(false)
+    }
+    provider.processManager = {
+      warmupProcess
+    }
+
+    await provider.warmupProcess('agent1', '/tmp/missing-workdir')
+
+    expect(provider.sessionPersistence.isWorkdirUsable).toHaveBeenCalledWith('/tmp/missing-workdir')
+    expect(warmupProcess).not.toHaveBeenCalled()
+  })
+
   it('does not let undefined debug payload cwd overwrite the resolved workdir', async () => {
     const newSession = vi.fn().mockResolvedValue({ sessionId: 'debug-session' })
     const provider = Object.create(AcpProvider.prototype) as any
@@ -191,6 +208,247 @@ describe('AcpProvider runDebugAction error handling', () => {
     })
   })
 
+  it('syncs remote sessions when debug session/list requests sync', async () => {
+    const sessions = [
+      {
+        sessionId: 'remote-1',
+        cwd: '/tmp/debug-workdir',
+        title: 'Remote Session'
+      }
+    ]
+    const listSessions = vi.fn().mockResolvedValue({ sessions, nextCursor: null })
+    const syncRemoteSessions = vi.fn().mockResolvedValue({
+      imported: 1,
+      updated: 0,
+      skipped: 0,
+      sessions: [{ sessionId: 'remote-1', conversationId: 'conv-1', status: 'imported' }]
+    })
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.provider = { id: 'acp', name: 'ACP' }
+    provider.configPresenter = {
+      getAcpAgents: vi.fn().mockResolvedValue([agent])
+    }
+    provider.processManager = {
+      getDebugEvents: vi.fn().mockReturnValue([]),
+      getConnection: vi.fn().mockResolvedValue({
+        workdir: '/tmp/debug-workdir',
+        supportsSessionList: true,
+        connection: {
+          listSessions
+        },
+        status: 'ready',
+        agentId: 'agent1'
+      })
+    }
+    provider.sessionPersistence = {
+      syncRemoteSessions
+    }
+
+    const result = await provider.runDebugAction({
+      agentId: 'agent1',
+      action: 'sessionList',
+      payload: { cwd: '/tmp/debug-workdir', sync: true }
+    } as any)
+
+    expect(result.status).toBe('ok')
+    expect(listSessions).toHaveBeenCalledWith({
+      cwd: '/tmp/debug-workdir',
+      cursor: undefined
+    })
+    expect(syncRemoteSessions).toHaveBeenCalledWith({
+      agentId: 'agent1',
+      agentName: 'Agent 1',
+      providerId: 'acp',
+      workdir: '/tmp/debug-workdir',
+      sessions
+    })
+    expect(result.events.at(-1)).toMatchObject({
+      kind: 'lifecycle',
+      action: 'session/list.sync',
+      payload: {
+        imported: 1,
+        updated: 0,
+        skipped: 0
+      }
+    })
+  })
+
+  it('normalizes debug session/list cwd before requesting remote sessions', async () => {
+    const sessions = [
+      {
+        sessionId: 'remote-1',
+        cwd: '/tmp/missing-workdir',
+        title: 'Remote Session'
+      }
+    ]
+    const listSessions = vi.fn().mockResolvedValue({ sessions, nextCursor: null })
+    const syncRemoteSessions = vi.fn().mockResolvedValue({
+      imported: 1,
+      updated: 0,
+      skipped: 0,
+      sessions: [{ sessionId: 'remote-1', conversationId: 'conv-1', status: 'imported' }]
+    })
+    const isWorkdirUsable = vi.fn((workdir: string) => workdir === '/tmp/fallback')
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.provider = { id: 'acp', name: 'ACP' }
+    provider.configPresenter = {
+      getAcpAgents: vi.fn().mockResolvedValue([agent])
+    }
+    provider.processManager = {
+      getDebugEvents: vi.fn().mockReturnValue([]),
+      getConnection: vi.fn().mockResolvedValue({
+        workdir: '/tmp/fallback',
+        supportsSessionList: true,
+        connection: {
+          listSessions
+        },
+        status: 'ready',
+        agentId: 'agent1'
+      })
+    }
+    provider.sessionPersistence = {
+      isWorkdirUsable,
+      syncRemoteSessions
+    }
+
+    const result = await provider.runDebugAction({
+      agentId: 'agent1',
+      action: 'sessionList',
+      workdir: '/tmp/missing-from-dialog',
+      payload: { cwd: '/tmp/missing-workdir', sync: true }
+    } as any)
+
+    expect(result.status).toBe('ok')
+    expect(isWorkdirUsable).toHaveBeenCalledWith('/tmp/missing-workdir')
+    expect(listSessions).toHaveBeenCalledWith({
+      cwd: '/tmp/fallback',
+      cursor: undefined
+    })
+    expect(syncRemoteSessions).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workdir: '/tmp/fallback',
+        sessions
+      })
+    )
+  })
+
+  it('falls back when a cached debug handle workdir becomes unavailable', async () => {
+    const sessions = [
+      {
+        sessionId: 'remote-1',
+        cwd: '/tmp/stale-workdir',
+        title: 'Remote Session'
+      }
+    ]
+    const listSessions = vi.fn().mockResolvedValue({ sessions, nextCursor: null })
+    const syncRemoteSessions = vi.fn().mockResolvedValue({
+      imported: 1,
+      updated: 0,
+      skipped: 0,
+      sessions: [{ sessionId: 'remote-1', conversationId: 'conv-1', status: 'imported' }]
+    })
+    const isWorkdirUsable = vi.fn((workdir: string) => workdir === '/tmp/default-workdir')
+    const resolveWorkdir = vi.fn().mockReturnValue('/tmp/default-workdir')
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.provider = { id: 'acp', name: 'ACP' }
+    provider.configPresenter = {
+      getAcpAgents: vi.fn().mockResolvedValue([agent])
+    }
+    provider.processManager = {
+      getDebugEvents: vi.fn().mockReturnValue([]),
+      getConnection: vi.fn().mockResolvedValue({
+        workdir: '/tmp/stale-workdir',
+        supportsSessionList: true,
+        connection: {
+          listSessions
+        },
+        status: 'ready',
+        agentId: 'agent1'
+      })
+    }
+    provider.sessionPersistence = {
+      isWorkdirUsable,
+      resolveWorkdir,
+      syncRemoteSessions
+    }
+
+    const result = await provider.runDebugAction({
+      agentId: 'agent1',
+      action: 'sessionList',
+      workdir: '/tmp/stale-workdir',
+      payload: { sync: true }
+    } as any)
+
+    expect(result.status).toBe('ok')
+    expect(isWorkdirUsable).toHaveBeenCalledWith('/tmp/stale-workdir')
+    expect(resolveWorkdir).toHaveBeenCalledWith('/tmp/stale-workdir')
+    expect(listSessions).toHaveBeenCalledWith({
+      cwd: '/tmp/default-workdir',
+      cursor: undefined
+    })
+    expect(syncRemoteSessions).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workdir: '/tmp/default-workdir',
+        sessions
+      })
+    )
+  })
+
+  it('binds the forked debug session workdir and listeners', async () => {
+    const unstableForkSession = vi.fn().mockResolvedValue({ sessionId: 'forked-session' })
+    const registerSessionWorkdir = vi.fn()
+    const registerSessionListener = vi.fn().mockReturnValue(() => {})
+    const registerPermissionResolver = vi.fn().mockReturnValue(() => {})
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.configPresenter = {
+      getAcpAgents: vi.fn().mockResolvedValue([agent])
+    }
+    provider.processManager = {
+      getDebugEvents: vi.fn().mockReturnValue([]),
+      registerSessionWorkdir,
+      registerSessionListener,
+      registerPermissionResolver,
+      getConnection: vi.fn().mockResolvedValue({
+        workdir: '/tmp/debug-workdir',
+        supportsSessionFork: true,
+        connection: {
+          unstable_forkSession: unstableForkSession
+        },
+        status: 'ready',
+        agentId: 'agent1'
+      })
+    }
+    provider.sessionManager = {
+      resolveMcpServersForAgent: vi.fn().mockResolvedValue([])
+    }
+
+    const result = await provider.runDebugAction({
+      agentId: 'agent1',
+      action: 'sessionFork',
+      sessionId: 'source-session',
+      payload: { cwd: '/tmp/debug-workdir', mcpServers: [] }
+    } as any)
+
+    expect(result.status).toBe('ok')
+    expect(result.sessionId).toBe('forked-session')
+    expect(unstableForkSession).toHaveBeenCalledWith({
+      cwd: '/tmp/debug-workdir',
+      mcpServers: [],
+      sessionId: 'source-session'
+    })
+    expect(registerSessionWorkdir).toHaveBeenCalledWith('forked-session', '/tmp/debug-workdir')
+    expect(registerSessionListener).toHaveBeenCalledWith(
+      'agent1',
+      'forked-session',
+      expect.any(Function)
+    )
+    expect(registerPermissionResolver).toHaveBeenCalledWith(
+      'agent1',
+      'forked-session',
+      expect.any(Function)
+    )
+  })
+
   it('uses real ACP MCP selections for debug sessions', async () => {
     const mcpServers = [{ name: 'fs', command: 'node', args: ['server.js'] }]
     const newSession = vi.fn().mockResolvedValue({ sessionId: 'debug-session' })
@@ -282,6 +540,8 @@ describe('AcpProvider runDebugAction error handling', () => {
     const provider = Object.create(AcpProvider.prototype) as any
     provider.getAgentById = vi.fn().mockResolvedValue({ id: 'agent1', name: 'Agent 1' })
     provider.sessionPersistence = {
+      isWorkdirUsable: vi.fn().mockReturnValue(true),
+      resolveWorkdir: vi.fn((workdir) => workdir),
       updateWorkdir: vi.fn().mockResolvedValue(undefined)
     }
     provider.sessionManager = {
@@ -342,6 +602,35 @@ describe('AcpProvider runDebugAction error handling', () => {
     )
   })
 
+  it('falls back when prepareSession receives an unavailable workdir', async () => {
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.getAgentById = vi.fn().mockResolvedValue({ id: 'agent1', name: 'Agent 1' })
+    provider.sessionPersistence = {
+      isWorkdirUsable: vi.fn().mockReturnValue(false),
+      resolveWorkdir: vi.fn().mockReturnValue('/tmp/fallback'),
+      updateWorkdir: vi.fn().mockResolvedValue(undefined)
+    }
+    provider.sessionManager = {
+      getOrCreateSession: vi.fn().mockResolvedValue({
+        workdir: '/tmp/fallback',
+        currentModeId: undefined,
+        availableModes: undefined,
+        configState: null,
+        availableCommands: []
+      })
+    }
+
+    await provider.prepareSession('conv-2', 'agent1', '/tmp/missing-workspace')
+
+    expect(provider.sessionPersistence.updateWorkdir).toHaveBeenCalledWith('conv-2', 'agent1', null)
+    expect(provider.sessionManager.getOrCreateSession).toHaveBeenCalledWith(
+      'conv-2',
+      { id: 'agent1', name: 'Agent 1' },
+      expect.any(Object),
+      '/tmp/fallback'
+    )
+  })
+
   it('updates mode on bound handle by conversation id', async () => {
     const provider = Object.create(AcpProvider.prototype) as any
     const setSessionMode = vi.fn().mockResolvedValue(undefined)
@@ -675,6 +964,117 @@ describe('AcpProvider runDebugAction error handling', () => {
     }
   })
 
+  it('marks the system prompt as sent only after the ACP prompt succeeds', async () => {
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.emitRequestTrace = vi.fn().mockResolvedValue(undefined)
+    provider.promptController = {
+      begin: vi.fn().mockReturnValue({
+        id: 'turn-system',
+        sessionId: 'session-system',
+        conversationId: 'conv-system',
+        userMessageId: null,
+        startedAt: Date.now()
+      }),
+      complete: vi.fn().mockReturnValue({
+        id: 'turn-system',
+        completedAt: Date.now()
+      }),
+      fail: vi.fn()
+    }
+    provider.sessionPersistence = {
+      startTurn: vi.fn().mockResolvedValue(undefined),
+      finishTurn: vi.fn().mockResolvedValue(undefined)
+    }
+
+    let resolvePrompt!: (value: { stopReason: string }) => void
+    const prompt = vi.fn(
+      () =>
+        new Promise<{ stopReason: string }>((resolve) => {
+          resolvePrompt = resolve
+        })
+    )
+    const queue = {
+      push: vi.fn(),
+      done: vi.fn()
+    }
+    const onPromptSucceeded = vi.fn()
+
+    const runPrompt = provider['runPrompt'](
+      {
+        sessionId: 'session-system',
+        conversationId: 'conv-system',
+        connection: {
+          prompt
+        }
+      },
+      [{ type: 'text', text: 'System instructions:\nBe precise.' }],
+      queue,
+      {},
+      { onPromptSucceeded }
+    )
+
+    await vi.waitFor(() => expect(prompt).toHaveBeenCalledTimes(1))
+    expect(onPromptSucceeded).not.toHaveBeenCalled()
+
+    resolvePrompt({ stopReason: 'end_turn' })
+    await runPrompt
+
+    expect(onPromptSucceeded).toHaveBeenCalledTimes(1)
+    expect(queue.done).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not mark the system prompt when prompt dispatch fails first', async () => {
+    const provider = Object.create(AcpProvider.prototype) as any
+    provider.emitRequestTrace = vi.fn().mockRejectedValue(new Error('trace failed'))
+    provider.promptController = {
+      begin: vi.fn().mockReturnValue({
+        id: 'turn-trace',
+        sessionId: 'session-trace',
+        conversationId: 'conv-trace',
+        userMessageId: null,
+        startedAt: Date.now()
+      }),
+      complete: vi.fn(),
+      fail: vi.fn().mockReturnValue({
+        id: 'turn-trace',
+        completedAt: Date.now()
+      })
+    }
+    provider.sessionPersistence = {
+      startTurn: vi.fn().mockResolvedValue(undefined),
+      finishTurn: vi.fn().mockResolvedValue(undefined)
+    }
+
+    const prompt = vi.fn().mockResolvedValue({ stopReason: 'end_turn' })
+    const queue = {
+      push: vi.fn(),
+      done: vi.fn()
+    }
+    const onPromptSucceeded = vi.fn()
+
+    await provider['runPrompt'](
+      {
+        sessionId: 'session-trace',
+        conversationId: 'conv-trace',
+        connection: {
+          prompt
+        }
+      },
+      [{ type: 'text', text: 'System instructions:\nBe precise.' }],
+      queue,
+      {},
+      { onPromptSucceeded }
+    )
+
+    expect(prompt).not.toHaveBeenCalled()
+    expect(onPromptSucceeded).not.toHaveBeenCalled()
+    expect(queue.push).toHaveBeenCalledWith({
+      type: 'error',
+      error_message: 'ACP: trace failed'
+    })
+    expect(queue.done).toHaveBeenCalledTimes(1)
+  })
+
   it('awaits turn start persistence before sending the ACP prompt', async () => {
     const provider = Object.create(AcpProvider.prototype) as any
     provider.emitRequestTrace = vi.fn().mockResolvedValue(undefined)
diff --git a/test/main/presenter/agentRuntimePresenter/agentRuntimePresenter.test.ts b/test/main/presenter/agentRuntimePresenter/agentRuntimePresenter.test.ts
index 8e397b48a..f8c7aef77 100644
--- a/test/main/presenter/agentRuntimePresenter/agentRuntimePresenter.test.ts
+++ b/test/main/presenter/agentRuntimePresenter/agentRuntimePresenter.test.ts
@@ -5317,6 +5317,64 @@ describe('AgentRuntimePresenter', () => {
       expect(updatedBlocks[1].content).toBe('User denied the request.')
       expect(updatedBlocks[1].extra.needsUserAction).toBe(false)
     })
+
+    it('clears stale ACP permission modals when the provider request no longer exists', async () => {
+      await agent.initSession('s1', { providerId: 'acp', modelId: 'claude-code-acp' })
+      ;(agent as any).runtimeState.get('s1').status = 'generating'
+      llmProvider.resolveAgentPermission.mockRejectedValueOnce(
+        new Error('Unknown ACP permission request: acp-stale-req')
+      )
+      makeAssistantRow({
+        blocks: [
+          {
+            type: 'tool_call',
+            status: 'pending',
+            timestamp: 1,
+            tool_call: { id: 'tc1', name: 'Terminal', params: '{"command":"dir"}', response: '' }
+          },
+          {
+            type: 'action',
+            action_type: 'tool_call_permission',
+            status: 'pending',
+            timestamp: 2,
+            content: 'components.messageBlockPermissionRequest.description.command',
+            tool_call: { id: 'tc1', name: 'Terminal', params: '{"command":"dir"}' },
+            extra: {
+              needsUserAction: true,
+              permissionType: 'command',
+              providerId: 'acp',
+              permissionRequestId: 'acp-stale-req',
+              permissionRequest: JSON.stringify({
+                permissionType: 'command',
+                description: 'components.messageBlockPermissionRequest.description.command',
+                toolName: 'Terminal',
+                providerId: 'acp',
+                requestId: 'acp-stale-req',
+                command: 'dir'
+              })
+            }
+          }
+        ]
+      })
+
+      const result = await agent.respondToolInteraction('s1', 'm1', 'tc1', {
+        kind: 'permission',
+        granted: true
+      })
+
+      expect(result).toEqual({ resumed: false })
+      expect(llmProvider.resolveAgentPermission).toHaveBeenCalledWith('acp-stale-req', true)
+      expect(toolPresenter.callTool).not.toHaveBeenCalled()
+      expect(processStream).not.toHaveBeenCalled()
+      const updatedBlocks = JSON.parse(
+        sqlitePresenter.deepchatMessagesTable.updateContent.mock.calls[0][1]
+      )
+      expect(updatedBlocks[1].status).toBe('denied')
+      expect(updatedBlocks[1].content).toBe('Permission request expired.')
+      expect(updatedBlocks[1].extra.needsUserAction).toBe(false)
+      expect(sqlitePresenter.deepchatMessagesTable.updateStatus).toHaveBeenCalledWith('m1', 'sent')
+      expect((agent as any).runtimeState.get('s1').status).toBe('idle')
+    })
   })
 
   describe('permission mode', () => {
diff --git a/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts b/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
index 304c7714f..96e0a6f24 100644
--- a/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
+++ b/test/main/presenter/llmProviderPresenter/acp/acpProcessManager.test.ts
@@ -137,6 +137,62 @@ describe('AcpProcessManager config cache fallback', () => {
     expect(manager.getProcessModes('agent-2', '/tmp/missing')).toBeUndefined()
   })
 
+  it('falls back when a warmup workdir no longer exists', () => {
+    const manager = createManager()
+    const existsSpy = vi.spyOn(fs, 'existsSync').mockReturnValue(false)
+
+    try {
+      const resolved = (manager as any).resolveWorkdir('/tmp/missing-workspace')
+
+      expect(normalizePathValue(resolved)).toContain('/tmp/deepchat-acp/sessions')
+    } finally {
+      existsSpy.mockRestore()
+    }
+  })
+
+  it('buffers early session updates until a listener is registered', () => {
+    const manager = createManager()
+    const handler = vi.fn()
+    const notification = {
+      sessionId: 'session-early',
+      update: {
+        sessionUpdate: 'available_commands_update',
+        availableCommands: [{ name: 'plan', description: 'Plan work' }]
+      }
+    }
+
+    ;(manager as any).dispatchSessionUpdate(notification)
+    expect(handler).not.toHaveBeenCalled()
+
+    manager.registerSessionListener('agent-1', 'session-early', handler)
+    expect(handler).toHaveBeenCalledWith(notification)
+  })
+
+  it('drops expired buffered session updates before replaying them', () => {
+    vi.useFakeTimers()
+
+    try {
+      const manager = createManager()
+      const handler = vi.fn()
+      const notification = {
+        sessionId: 'session-expired',
+        update: {
+          sessionUpdate: 'available_commands_update',
+          availableCommands: [{ name: 'plan', description: 'Plan work' }]
+        }
+      }
+
+      vi.setSystemTime(0)
+      ;(manager as any).dispatchSessionUpdate(notification)
+      vi.setSystemTime(31_000)
+      manager.registerSessionListener('agent-1', 'session-expired', handler)
+
+      expect(handler).not.toHaveBeenCalled()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('refreshes the agent cache when bound session config changes', () => {
     const manager = createManager()
     const handle = {
@@ -450,20 +506,20 @@ describe('AcpProcessManager config cache fallback', () => {
   })
 
   it('moves only the broken npx hash directory and retries once', async () => {
-    const npxRoot = '/tmp/deepchat-acp-npx/_npx'
+    const npxRoot = normalizePathValue('/tmp/deepchat-acp-npx/_npx')
     const badHashDir = `${npxRoot}/286fc3b7ffd18687`
     const otherHashDir = `${npxRoot}/keep-me`
-    const existingDirs = new Set([badHashDir, otherHashDir])
+    const existingDirs = new Set([path.normalize(badHashDir), path.normalize(otherHashDir)])
     const renameImpl = vi.fn((from: string, to: string) => {
-      existingDirs.delete(from)
-      existingDirs.add(to)
+      existingDirs.delete(path.normalize(from))
+      existingDirs.add(path.normalize(to))
     })
     const renameSpy = vi.spyOn(fs, 'renameSync').mockImplementation(renameImpl)
     const existsSpy = vi
       .spyOn(fs, 'existsSync')
-      .mockImplementation((input) => existingDirs.has(String(input)))
+      .mockImplementation((input) => existingDirs.has(path.normalize(String(input))))
     const statSpy = vi.spyOn(fs, 'statSync').mockImplementation((input) => {
-      if (existingDirs.has(String(input))) {
+      if (existingDirs.has(path.normalize(String(input)))) {
         return { isDirectory: () => true } as fs.Stats
       }
       const error = new Error('ENOENT') as NodeJS.ErrnoException
@@ -508,11 +564,11 @@ describe('AcpProcessManager config cache fallback', () => {
 
       expect(spawnOnceSpy).toHaveBeenCalledTimes(2)
       expect(renameImpl).toHaveBeenCalledWith(
-        badHashDir,
-        expect.stringMatching(/\/286fc3b7ffd18687\.bad-\d+$/)
+        path.normalize(badHashDir),
+        expect.stringMatching(/[\\/]286fc3b7ffd18687\.bad-\d+$/)
       )
-      expect(existingDirs.has(badHashDir)).toBe(false)
-      expect(existingDirs.has(otherHashDir)).toBe(true)
+      expect(existingDirs.has(path.normalize(badHashDir))).toBe(false)
+      expect(existingDirs.has(path.normalize(otherHashDir))).toBe(true)
     } finally {
       renameSpy.mockRestore()
       existsSpy.mockRestore()
diff --git a/test/main/presenter/llmProviderPresenter/acp/acpProcessManagerCapabilities.test.ts b/test/main/presenter/llmProviderPresenter/acp/acpProcessManagerCapabilities.test.ts
new file mode 100644
index 000000000..421ed6973
--- /dev/null
+++ b/test/main/presenter/llmProviderPresenter/acp/acpProcessManagerCapabilities.test.ts
@@ -0,0 +1,123 @@
+import { EventEmitter } from 'events'
+import { PassThrough } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+
+const sdkMock = vi.hoisted(() => ({
+  initializeResponse: {
+    protocolVersion: 1,
+    agentInfo: { name: 'Agent One', version: '1.0.0' },
+    agentCapabilities: {
+      loadSession: true,
+      promptCapabilities: {
+        image: true,
+        audio: true,
+        embeddedContext: true
+      },
+      sessionCapabilities: {
+        list: {},
+        resume: {},
+        close: {},
+        fork: {}
+      },
+      mcpCapabilities: {
+        http: true
+      }
+    },
+    authMethods: [{ id: 'terminal', name: 'Terminal', type: 'terminal' }]
+  }
+}))
+
+vi.mock('@agentclientprotocol/sdk', () => ({
+  PROTOCOL_VERSION: 1,
+  ClientSideConnection: class {
+    closed = new Promise<void>(() => {})
+    initialize = vi.fn(async () => sdkMock.initializeResponse)
+  }
+}))
+
+vi.mock('electron', () => ({
+  app: {
+    getVersion: vi.fn(() => '0.0.0-test'),
+    getPath: vi.fn(() => '/tmp')
+  }
+}))
+
+vi.mock('@/eventbus', () => ({
+  eventBus: {
+    sendToRenderer: vi.fn()
+  },
+  SendTarget: {
+    ALL_WINDOWS: 'ALL_WINDOWS'
+  }
+}))
+
+vi.mock('@/routes/publishDeepchatEvent', () => ({
+  publishDeepchatEvent: vi.fn()
+}))
+
+class MockChild extends EventEmitter {
+  stdout = new PassThrough()
+  stderr = new PassThrough()
+  stdin = new PassThrough()
+  pid = 1234
+  killed = false
+  exitCode = null
+  signalCode = null
+  kill = vi.fn(() => true)
+}
+
+describe('AcpProcessManager initialized capabilities', () => {
+  it('carries initialize capabilities into the ready process handle', async () => {
+    const { AcpProcessManager } =
+      await import('@/presenter/llmProviderPresenter/acp/acpProcessManager')
+    const manager = new AcpProcessManager({
+      providerId: 'acp',
+      resolveLaunchSpec: vi.fn()
+    })
+    const child = new MockChild()
+    vi.spyOn(manager as any, 'spawnAgentProcess').mockResolvedValue(child)
+
+    const handle = await (manager as any).spawnProcessOnce(
+      {
+        id: 'agent-1',
+        name: 'Agent One',
+        command: 'agent'
+      },
+      '/tmp/workspace',
+      {
+        agentId: 'agent-1',
+        source: 'manual',
+        distributionType: 'manual',
+        command: 'agent',
+        args: [],
+        env: {}
+      },
+      'manual:agent'
+    )
+
+    expect(handle.promptCapabilities).toEqual({
+      image: true,
+      audio: true,
+      embeddedContext: true
+    })
+    expect(handle.sessionCapabilities).toEqual({
+      list: {},
+      resume: {},
+      close: {},
+      fork: {}
+    })
+    expect(handle.supportsLoadSession).toBe(true)
+    expect(handle.supportsSessionList).toBe(true)
+    expect(handle.supportsSessionResume).toBe(true)
+    expect(handle.supportsSessionClose).toBe(true)
+    expect(handle.supportsSessionFork).toBe(true)
+    expect(handle.authMethods).toEqual([{ id: 'terminal', name: 'Terminal', type: 'terminal' }])
+    expect(handle.capabilitySnapshot?.supports).toEqual({
+      loadSession: true,
+      sessionList: true,
+      sessionResume: true,
+      sessionClose: true,
+      sessionFork: true
+    })
+  })
+})
diff --git a/test/main/presenter/llmProviderPresenter/acp/acpTerminalManager.test.ts b/test/main/presenter/llmProviderPresenter/acp/acpTerminalManager.test.ts
index 623313c5d..9abaa1ea8 100644
--- a/test/main/presenter/llmProviderPresenter/acp/acpTerminalManager.test.ts
+++ b/test/main/presenter/llmProviderPresenter/acp/acpTerminalManager.test.ts
@@ -15,14 +15,6 @@ vi.mock('electron', () => ({
 }))
 
 describe('AcpTerminalManager', () => {
-  const getShellExpectation = () =>
-    process.platform === 'win32'
-      ? expect.stringMatching(/powershell/i)
-      : expect.stringMatching(/bash/i)
-
-  const getArgsExpectation = (command: string) =>
-    process.platform === 'win32' ? ['-NoLogo', '-Command', command] : ['-c', command]
-
   const createPty = () => ({
     onData: vi.fn(),
     onExit: vi.fn(),
@@ -45,8 +37,8 @@ describe('AcpTerminalManager', () => {
     })
 
     expect(spawn).toHaveBeenCalledWith(
-      getShellExpectation(),
-      getArgsExpectation('pwd'),
+      'pwd',
+      [],
       expect.objectContaining({
         cwd: expect.stringContaining(path.normalize('/tmp/workspace'))
       })
@@ -65,11 +57,54 @@ describe('AcpTerminalManager', () => {
       recursive: true
     })
     expect(spawn).toHaveBeenCalledWith(
-      getShellExpectation(),
-      getArgsExpectation('pwd'),
+      'pwd',
+      [],
       expect.objectContaining({
         cwd: expect.stringContaining(path.normalize('/tmp/deepchat-acp/terminals'))
       })
     )
   })
+
+  it('passes command arguments directly without shell concatenation', async () => {
+    const manager = new AcpTerminalManager()
+
+    await manager.createTerminal({
+      sessionId: 'session-1',
+      command: 'node',
+      args: ['-e', 'console.log("hello world")'],
+      cwd: '/tmp/workspace'
+    })
+
+    expect(spawn).toHaveBeenCalledWith(
+      'node',
+      ['-e', 'console.log("hello world")'],
+      expect.objectContaining({
+        cwd: expect.stringContaining(path.normalize('/tmp/workspace'))
+      })
+    )
+  })
+
+  it('retains the latest terminal output when outputByteLimit is exceeded', async () => {
+    const pty = createPty()
+    vi.mocked(spawn).mockReturnValue(pty as never)
+    const manager = new AcpTerminalManager()
+
+    const response = await manager.createTerminal({
+      sessionId: 'session-1',
+      command: 'node',
+      outputByteLimit: 6,
+      cwd: '/tmp/workspace'
+    })
+    const onData = pty.onData.mock.calls[0][0] as (data: string) => void
+
+    onData('abcdef')
+    onData('ghij')
+
+    await expect(
+      manager.terminalOutput({ sessionId: 'session-1', terminalId: response.terminalId })
+    ).resolves.toMatchObject({
+      output: 'efghij',
+      truncated: true
+    })
+  })
 })
diff --git a/test/main/presenter/llmProviderPresenter/acpCapabilities.test.ts b/test/main/presenter/llmProviderPresenter/acpCapabilities.test.ts
index 9eef648fb..339fb950f 100644
--- a/test/main/presenter/llmProviderPresenter/acpCapabilities.test.ts
+++ b/test/main/presenter/llmProviderPresenter/acpCapabilities.test.ts
@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { buildClientCapabilities } from '@/presenter/llmProviderPresenter/acp'
+import {
+  buildCapabilitySnapshot,
+  buildClientCapabilities
+} from '@/presenter/llmProviderPresenter/acp'
 
 describe('AcpCapabilities', () => {
   describe('buildClientCapabilities', () => {
@@ -39,5 +42,54 @@ describe('AcpCapabilities', () => {
       expect(caps.fs).toBeUndefined()
       expect(caps.terminal).toBeUndefined()
     })
+
+    it('advertises terminal auth only when enabled', () => {
+      expect(buildClientCapabilities().auth).toBeUndefined()
+      expect(buildClientCapabilities({ enableTerminalAuth: true }).auth).toEqual({
+        terminal: true
+      })
+      expect(
+        buildClientCapabilities({ enableTerminal: false, enableTerminalAuth: true }).auth
+      ).toBeUndefined()
+    })
+  })
+
+  describe('buildCapabilitySnapshot', () => {
+    it('normalizes initialize capabilities into support flags', () => {
+      const snapshot = buildCapabilitySnapshot({
+        protocolVersion: 1,
+        agentInfo: { name: 'dimcode', version: '0.0.75' },
+        authMethods: [{ id: 'login', name: 'Login' }],
+        agentCapabilities: {
+          loadSession: true,
+          promptCapabilities: {
+            image: true,
+            audio: false,
+            embeddedContext: true
+          },
+          mcpCapabilities: {
+            http: true,
+            sse: false
+          },
+          sessionCapabilities: {
+            list: {},
+            resume: {},
+            close: {}
+          }
+        }
+      })
+
+      expect(snapshot.agentInfo?.name).toBe('dimcode')
+      expect(snapshot.authMethods).toHaveLength(1)
+      expect(snapshot.promptCapabilities?.image).toBe(true)
+      expect(snapshot.mcpCapabilities).toEqual({ http: true, sse: false })
+      expect(snapshot.supports).toEqual({
+        loadSession: true,
+        sessionList: true,
+        sessionResume: true,
+        sessionClose: true,
+        sessionFork: false
+      })
+    })
   })
 })
diff --git a/test/main/presenter/llmProviderPresenter/acpContentMapper.test.ts b/test/main/presenter/llmProviderPresenter/acpContentMapper.test.ts
index 48d6a63d9..11a7f81d8 100644
--- a/test/main/presenter/llmProviderPresenter/acpContentMapper.test.ts
+++ b/test/main/presenter/llmProviderPresenter/acpContentMapper.test.ts
@@ -324,3 +324,45 @@ describe('AcpContentMapper config options handling', () => {
     expect(result.events).toHaveLength(0)
   })
 })
+
+describe('AcpContentMapper session metadata updates', () => {
+  it('maps session_info_update into session metadata', () => {
+    const mapper = new AcpContentMapper()
+
+    const result = mapper.map(
+      createNotification('session-1', {
+        sessionUpdate: 'session_info_update',
+        title: 'Imported Session',
+        updatedAt: '2026-06-02T10:00:00.000Z',
+        _meta: { source: 'agent' }
+      })
+    )
+
+    expect(result.sessionInfo).toEqual({
+      title: 'Imported Session',
+      updatedAt: '2026-06-02T10:00:00.000Z',
+      meta: { source: 'agent' }
+    })
+  })
+
+  it('maps usage_update into ACP usage metadata without standard token usage', () => {
+    const mapper = new AcpContentMapper()
+
+    const result = mapper.map(
+      createNotification('session-1', {
+        sessionUpdate: 'usage_update',
+        used: 42,
+        size: 128,
+        cost: { amount: 0.01, currency: 'USD' }
+      })
+    )
+
+    expect(result.usage).toEqual({
+      used: 42,
+      size: 128,
+      cost: { amount: 0.01, currency: 'USD' },
+      meta: null
+    })
+    expect(result.events).toEqual([])
+  })
+})
diff --git a/test/main/presenter/llmProviderPresenter/acpMessageFormatter.test.ts b/test/main/presenter/llmProviderPresenter/acpMessageFormatter.test.ts
new file mode 100644
index 000000000..589c26d77
--- /dev/null
+++ b/test/main/presenter/llmProviderPresenter/acpMessageFormatter.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { AcpMessageFormatter } from '@/presenter/llmProviderPresenter/acp'
+import type { ChatMessage } from '@shared/presenter'
+
+describe('AcpMessageFormatter', () => {
+  it('formats only the latest user message by default', () => {
+    const formatter = new AcpMessageFormatter()
+    const result = formatter.format([
+      { role: 'user', content: 'first question' },
+      { role: 'assistant', content: 'first answer' },
+      { role: 'user', content: 'second question' }
+    ] as ChatMessage[])
+
+    expect(result.blocks).toEqual([{ type: 'text', text: 'second question' }])
+    expect(result.includedSystemPrompt).toBe(false)
+  })
+
+  it('includes system prompt only when requested', () => {
+    const formatter = new AcpMessageFormatter()
+    const messages = [
+      { role: 'system', content: 'Be precise.' },
+      { role: 'user', content: 'What changed?' }
+    ] as ChatMessage[]
+
+    expect(formatter.format(messages).blocks).toEqual([{ type: 'text', text: 'What changed?' }])
+
+    const result = formatter.format(messages, { includeSystemPrompt: true })
+    expect(result.includedSystemPrompt).toBe(true)
+    expect(result.blocks).toEqual([
+      { type: 'text', text: 'System instructions:\nBe precise.' },
+      { type: 'text', text: 'What changed?' }
+    ])
+  })
+
+  it('sends image data blocks only when the agent supports images', () => {
+    const formatter = new AcpMessageFormatter()
+    const messages = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image_url',
+            image_url: {
+              url: 'data:image/png;base64,abc123'
+            }
+          }
+        ]
+      }
+    ] as ChatMessage[]
+
+    expect(formatter.format(messages, { promptCapabilities: { image: true } }).blocks).toEqual([
+      {
+        type: 'image',
+        data: 'abc123',
+        mimeType: 'image/png',
+        uri: 'data:image/png;base64,abc123'
+      }
+    ])
+
+    expect(formatter.format(messages, { promptCapabilities: { image: false } }).blocks).toEqual([
+      {
+        type: 'resource_link',
+        uri: 'data:image/png;base64,abc123',
+        name: 'image',
+        mimeType: 'image/png'
+      }
+    ])
+  })
+
+  it('accepts input_image data from source and top-level fields', () => {
+    const formatter = new AcpMessageFormatter()
+    const messages = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'input_image',
+            source: {
+              data: 'data:image/jpeg;base64,fromSource'
+            }
+          },
+          {
+            type: 'input_image',
+            data: 'data:image/png;base64,fromData'
+          }
+        ]
+      }
+    ] as ChatMessage[]
+
+    expect(formatter.format(messages, { promptCapabilities: { image: true } }).blocks).toEqual([
+      {
+        type: 'image',
+        data: 'fromSource',
+        mimeType: 'image/jpeg',
+        uri: 'data:image/jpeg;base64,fromSource'
+      },
+      {
+        type: 'image',
+        data: 'fromData',
+        mimeType: 'image/png',
+        uri: 'data:image/png;base64,fromData'
+      }
+    ])
+  })
+})
diff --git a/test/main/presenter/llmProviderPresenter/acpSessionPersistence.test.ts b/test/main/presenter/llmProviderPresenter/acpSessionPersistence.test.ts
new file mode 100644
index 000000000..a69e0f8b0
--- /dev/null
+++ b/test/main/presenter/llmProviderPresenter/acpSessionPersistence.test.ts
@@ -0,0 +1,450 @@
+import * as path from 'path'
+import * as fs from 'fs'
+import { app } from 'electron'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { AcpSessionPersistence } from '../../../../src/main/presenter/llmProviderPresenter/acp'
+import type { AcpSessionEntity, ISQLitePresenter } from '../../../../src/shared/types/presenters'
+
+vi.mock('electron', () => ({
+  app: {
+    getPath: vi.fn(() => '/home/tester')
+  }
+}))
+
+describe('AcpSessionPersistence remote session sync', () => {
+  beforeEach(() => {
+    const usableDirectories = new Set([process.cwd(), path.dirname(process.cwd()), '/home/tester'])
+    vi.mocked(fs.existsSync).mockImplementation((target) => usableDirectories.has(String(target)))
+    vi.mocked(fs.statSync).mockImplementation(
+      (target) =>
+        ({
+          isDirectory: () => usableDirectories.has(String(target))
+        }) as fs.Stats
+    )
+  })
+
+  it('falls back from missing persisted workdirs to the default workdir', () => {
+    const homeDir = process.cwd()
+    const missingDir = path.join(homeDir, 'missing-workdir-for-acp-test')
+    vi.mocked(app.getPath).mockReturnValue(homeDir)
+
+    const persistence = new AcpSessionPersistence({} as ISQLitePresenter)
+
+    expect(persistence.isWorkdirUsable(missingDir)).toBe(false)
+    expect(persistence.resolveWorkdir(missingDir)).toBe(homeDir)
+
+    vi.mocked(app.getPath).mockReturnValue('/home/tester')
+  })
+
+  it('imports remote sessions once and updates the existing link on later syncs', async () => {
+    const workspaceDir = process.cwd()
+    const localWorkdir = path.dirname(workspaceDir)
+    let storedSession: AcpSessionEntity | null = null
+    const sqlitePresenter = {
+      getAcpSessionByAgentAndSessionId: vi.fn(async () => storedSession),
+      createConversation: vi.fn(async () => 'conv-imported'),
+      updateAcpSessionStatus: vi.fn(async (_conversationId, _agentId, status) => {
+        if (storedSession) {
+          storedSession = {
+            ...storedSession,
+            status
+          }
+        }
+      }),
+      upsertAcpSession: vi.fn(
+        async (
+          conversationId: string,
+          agentId: string,
+          data: {
+            sessionId?: string | null
+            workdir?: string | null
+            status?: AcpSessionEntity['status']
+            metadata?: Record<string, unknown> | null
+          }
+        ) => {
+          storedSession = {
+            id: 1,
+            conversationId,
+            agentId,
+            sessionId: data.sessionId ?? null,
+            workdir: data.workdir ?? null,
+            status: data.status ?? 'idle',
+            createdAt: 1,
+            updatedAt: 2,
+            metadata: data.metadata ?? null
+          }
+        }
+      )
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+    const input = {
+      agentId: 'agent-1',
+      agentName: 'Agent One',
+      providerId: 'acp',
+      workdir: workspaceDir,
+      sessions: [
+        {
+          sessionId: 'remote-1',
+          cwd: workspaceDir,
+          title: 'Remote title',
+          updatedAt: '2026-06-02T00:00:00.000Z'
+        }
+      ]
+    }
+
+    const first = await persistence.syncRemoteSessions(input)
+    await persistence.clearSession('conv-imported', 'agent-1')
+    storedSession = storedSession ? { ...storedSession, workdir: localWorkdir } : storedSession
+    const second = await persistence.syncRemoteSessions(input)
+
+    expect(first).toMatchObject({
+      imported: 1,
+      updated: 0,
+      skipped: 0,
+      sessions: [{ sessionId: 'remote-1', conversationId: 'conv-imported', status: 'imported' }]
+    })
+    expect(second).toMatchObject({
+      imported: 0,
+      updated: 1,
+      skipped: 0,
+      sessions: [{ sessionId: 'remote-1', conversationId: 'conv-imported', status: 'updated' }]
+    })
+    expect(sqlitePresenter.createConversation).toHaveBeenCalledTimes(1)
+    expect(sqlitePresenter.createConversation).toHaveBeenCalledWith(
+      'Remote title',
+      expect.objectContaining({
+        providerId: 'acp',
+        modelId: 'agent-1',
+        chatMode: 'acp agent',
+        agentWorkspacePath: workspaceDir,
+        acpWorkdirMap: { 'agent-1': workspaceDir }
+      })
+    )
+    expect(sqlitePresenter.upsertAcpSession).toHaveBeenLastCalledWith(
+      'conv-imported',
+      'agent-1',
+      expect.objectContaining({
+        sessionId: 'remote-1',
+        workdir: localWorkdir,
+        status: 'idle',
+        metadata: expect.objectContaining({
+          agentName: 'Agent One',
+          remoteSession: expect.objectContaining({
+            protocol: 'acp',
+            sessionId: 'remote-1',
+            cwd: workspaceDir
+          }),
+          acpSync: expect.objectContaining({
+            source: 'session/list'
+          })
+        })
+      })
+    )
+  })
+
+  it('serializes concurrent imports of the same remote session', async () => {
+    const workspaceDir = process.cwd()
+    let storedSession: AcpSessionEntity | null = null
+    let releaseCreate!: () => void
+    let markCreateStarted!: () => void
+    const createGate = new Promise<void>((resolve) => {
+      releaseCreate = resolve
+    })
+    const createStarted = new Promise<void>((resolve) => {
+      markCreateStarted = resolve
+    })
+    const sqlitePresenter = {
+      getAcpSessionByAgentAndSessionId: vi.fn(async () => storedSession),
+      createConversation: vi.fn(async () => {
+        markCreateStarted()
+        await createGate
+        return 'conv-imported'
+      }),
+      deleteConversation: vi.fn().mockResolvedValue(undefined),
+      upsertAcpSession: vi.fn(
+        async (
+          conversationId: string,
+          agentId: string,
+          data: {
+            sessionId?: string | null
+            workdir?: string | null
+            status?: AcpSessionEntity['status']
+            metadata?: Record<string, unknown> | null
+          }
+        ) => {
+          storedSession = {
+            id: 1,
+            conversationId,
+            agentId,
+            sessionId: data.sessionId ?? null,
+            workdir: data.workdir ?? null,
+            status: data.status ?? 'idle',
+            createdAt: 1,
+            updatedAt: 2,
+            metadata: data.metadata ?? null
+          }
+        }
+      )
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+    const input = {
+      agentId: 'agent-1',
+      agentName: 'Agent One',
+      providerId: 'acp',
+      workdir: workspaceDir,
+      sessions: [
+        {
+          sessionId: 'remote-1',
+          cwd: workspaceDir,
+          title: 'Remote title'
+        }
+      ]
+    }
+
+    const firstPromise = persistence.syncRemoteSessions(input)
+    await createStarted
+    const secondPromise = persistence.syncRemoteSessions(input)
+    releaseCreate()
+    const [first, second] = await Promise.all([firstPromise, secondPromise])
+
+    expect(sqlitePresenter.createConversation).toHaveBeenCalledTimes(1)
+    expect(sqlitePresenter.deleteConversation).not.toHaveBeenCalled()
+    expect(first).toMatchObject({
+      imported: 1,
+      updated: 0,
+      sessions: [{ conversationId: 'conv-imported', status: 'imported' }]
+    })
+    expect(second).toMatchObject({
+      imported: 0,
+      updated: 1,
+      sessions: [{ conversationId: 'conv-imported', status: 'updated' }]
+    })
+  })
+
+  it('recovers when a remote session link is created concurrently before save', async () => {
+    const workspaceDir = process.cwd()
+    const existingSession: AcpSessionEntity = {
+      id: 1,
+      conversationId: 'conv-existing',
+      agentId: 'agent-1',
+      sessionId: 'remote-1',
+      workdir: workspaceDir,
+      status: 'idle',
+      createdAt: 1,
+      updatedAt: 2,
+      metadata: {
+        acpSync: {
+          importedAt: '2026-06-01T00:00:00.000Z'
+        }
+      }
+    }
+    let lookupCount = 0
+    const sqlitePresenter = {
+      getAcpSessionByAgentAndSessionId: vi.fn(async () => {
+        lookupCount += 1
+        return lookupCount === 1 ? null : existingSession
+      }),
+      createConversation: vi.fn(async () => 'conv-duplicate'),
+      deleteConversation: vi.fn().mockResolvedValue(undefined),
+      upsertAcpSession: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('UNIQUE constraint failed: acp_sessions.agent_id'))
+        .mockResolvedValue(undefined)
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+
+    const result = await persistence.syncRemoteSessions({
+      agentId: 'agent-1',
+      agentName: 'Agent One',
+      providerId: 'acp',
+      workdir: workspaceDir,
+      sessions: [
+        {
+          sessionId: 'remote-1',
+          cwd: workspaceDir,
+          title: 'Remote title'
+        }
+      ]
+    })
+
+    expect(result).toMatchObject({
+      imported: 0,
+      updated: 1,
+      sessions: [{ conversationId: 'conv-existing', status: 'updated' }]
+    })
+    expect(sqlitePresenter.deleteConversation).toHaveBeenCalledWith('conv-duplicate')
+    expect(sqlitePresenter.upsertAcpSession).toHaveBeenLastCalledWith(
+      'conv-existing',
+      'agent-1',
+      expect.objectContaining({
+        sessionId: 'remote-1',
+        workdir: workspaceDir,
+        metadata: expect.objectContaining({
+          acpSync: expect.objectContaining({
+            importedAt: '2026-06-01T00:00:00.000Z',
+            source: 'session/list'
+          })
+        })
+      })
+    )
+  })
+
+  it('cleans up the new conversation when remote session save cannot be recovered', async () => {
+    const workspaceDir = process.cwd()
+    const saveError = new Error('database unavailable')
+    const sqlitePresenter = {
+      getAcpSessionByAgentAndSessionId: vi.fn().mockResolvedValue(null),
+      createConversation: vi.fn(async () => 'conv-failed'),
+      deleteConversation: vi.fn().mockResolvedValue(undefined),
+      upsertAcpSession: vi.fn().mockRejectedValue(saveError)
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+
+    await expect(
+      persistence.syncRemoteSessions({
+        agentId: 'agent-1',
+        agentName: 'Agent One',
+        providerId: 'acp',
+        workdir: workspaceDir,
+        sessions: [
+          {
+            sessionId: 'remote-1',
+            cwd: workspaceDir,
+            title: 'Remote title'
+          }
+        ]
+      })
+    ).rejects.toThrow(saveError)
+
+    expect(sqlitePresenter.createConversation).toHaveBeenCalledWith(
+      'Remote title',
+      expect.any(Object)
+    )
+    expect(sqlitePresenter.deleteConversation).toHaveBeenCalledWith('conv-failed')
+  })
+
+  it('serializes concurrent metadata merges for the same local session', async () => {
+    let storedSession: AcpSessionEntity = {
+      id: 1,
+      conversationId: 'conv-1',
+      agentId: 'agent-1',
+      sessionId: 'session-1',
+      workdir: process.cwd(),
+      status: 'idle',
+      createdAt: 1,
+      updatedAt: 2,
+      metadata: {
+        base: true
+      }
+    }
+    let releaseFirstSave!: () => void
+    let markFirstSaveStarted!: () => void
+    const firstSaveGate = new Promise<void>((resolve) => {
+      releaseFirstSave = resolve
+    })
+    const firstSaveStarted = new Promise<void>((resolve) => {
+      markFirstSaveStarted = resolve
+    })
+    let saveCount = 0
+    const sqlitePresenter = {
+      getAcpSession: vi.fn(async () => ({
+        ...storedSession,
+        metadata: {
+          ...storedSession.metadata
+        }
+      })),
+      upsertAcpSession: vi.fn(
+        async (
+          conversationId: string,
+          agentId: string,
+          data: {
+            sessionId?: string | null
+            workdir?: string | null
+            status?: AcpSessionEntity['status']
+            metadata?: Record<string, unknown> | null
+          }
+        ) => {
+          saveCount += 1
+          if (saveCount === 1) {
+            markFirstSaveStarted()
+            await firstSaveGate
+          }
+          storedSession = {
+            ...storedSession,
+            conversationId,
+            agentId,
+            sessionId: data.sessionId ?? null,
+            workdir: data.workdir ?? null,
+            status: data.status ?? 'idle',
+            metadata: data.metadata ?? null
+          }
+        }
+      )
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+
+    const firstMerge = persistence.mergeMetadata('conv-1', 'agent-1', { first: true })
+    await firstSaveStarted
+    const secondMerge = persistence.mergeMetadata('conv-1', 'agent-1', { second: true })
+    releaseFirstSave()
+    await Promise.all([firstMerge, secondMerge])
+
+    expect(sqlitePresenter.getAcpSession).toHaveBeenCalledTimes(2)
+    expect(storedSession.metadata).toEqual({
+      base: true,
+      first: true,
+      second: true
+    })
+  })
+
+  it('keeps remote cwd metadata while using a local fallback for missing imported workdirs', async () => {
+    const fallbackDir = process.cwd()
+    const remoteMissingDir = path.join(fallbackDir, 'remote-missing')
+    vi.mocked(app.getPath).mockReturnValue(fallbackDir)
+
+    const sqlitePresenter = {
+      getAcpSessionByAgentAndSessionId: vi.fn(async () => null),
+      createConversation: vi.fn(async () => 'conv-imported'),
+      upsertAcpSession: vi.fn().mockResolvedValue(undefined)
+    } as unknown as ISQLitePresenter
+    const persistence = new AcpSessionPersistence(sqlitePresenter)
+
+    try {
+      await persistence.syncRemoteSessions({
+        agentId: 'agent-1',
+        agentName: 'Agent One',
+        providerId: 'acp',
+        workdir: remoteMissingDir,
+        sessions: [
+          {
+            sessionId: 'remote-1',
+            cwd: remoteMissingDir,
+            title: 'Remote title'
+          }
+        ]
+      })
+
+      expect(sqlitePresenter.createConversation).toHaveBeenCalledWith(
+        'Remote title',
+        expect.objectContaining({
+          agentWorkspacePath: fallbackDir,
+          acpWorkdirMap: { 'agent-1': fallbackDir }
+        })
+      )
+      expect(sqlitePresenter.upsertAcpSession).toHaveBeenCalledWith(
+        'conv-imported',
+        'agent-1',
+        expect.objectContaining({
+          workdir: fallbackDir,
+          metadata: expect.objectContaining({
+            remoteSession: expect.objectContaining({
+              cwd: remoteMissingDir
+            })
+          })
+        })
+      )
+    } finally {
+      vi.mocked(app.getPath).mockReturnValue('/home/tester')
+    }
+  })
+})
diff --git a/test/main/presenter/sqlitePresenter/acpSessions.test.ts b/test/main/presenter/sqlitePresenter/acpSessions.test.ts
new file mode 100644
index 000000000..989d7fb67
--- /dev/null
+++ b/test/main/presenter/sqlitePresenter/acpSessions.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { AcpSessionsTable } from '../../../../src/main/presenter/sqlitePresenter/tables/acpSessions'
+
+const sqliteModule = await import('better-sqlite3-multiple-ciphers').catch(() => null)
+const Database = sqliteModule?.default
+let sqliteAvailable = false
+if (Database) {
+  try {
+    const smokeDb = new Database(':memory:')
+    smokeDb.close()
+    sqliteAvailable = true
+  } catch {
+    sqliteAvailable = false
+  }
+}
+const describeIfSqlite = sqliteAvailable && Database ? describe : describe.skip
+const DatabaseCtor = Database!
+
+describe('AcpSessionsTable schema', () => {
+  it('scopes remote ACP session ids by agent', () => {
+    const table = new AcpSessionsTable({} as any)
+
+    expect(table.getCreateTableSQL()).toContain('UNIQUE(agent_id, session_id)')
+    expect(table.getCreateTableSQL()).not.toContain('session_id TEXT UNIQUE')
+    expect(table.getLatestVersion()).toBe(30)
+    expect(table.getMigrationSQL(30)).toContain('UNIQUE(agent_id, session_id)')
+  })
+})
+
+describeIfSqlite('AcpSessionsTable storage', () => {
+  it('allows the same remote ACP session id across different agents', async () => {
+    const db = new DatabaseCtor(':memory:')
+    try {
+      const table = new AcpSessionsTable(db)
+      table.createTable()
+
+      await table.upsert('conv-a', 'agent-a', { sessionId: 'remote-1', status: 'idle' })
+      await table.upsert('conv-b', 'agent-b', { sessionId: 'remote-1', status: 'idle' })
+
+      await expect(
+        table.upsert('conv-c', 'agent-a', { sessionId: 'remote-1', status: 'idle' })
+      ).rejects.toThrow()
+
+      expect(await table.getByAgentAndSessionId('agent-a', 'remote-1')).toMatchObject({
+        conversationId: 'conv-a',
+        agentId: 'agent-a',
+        sessionId: 'remote-1'
+      })
+      expect(await table.getByAgentAndSessionId('agent-b', 'remote-1')).toMatchObject({
+        conversationId: 'conv-b',
+        agentId: 'agent-b',
+        sessionId: 'remote-1'
+      })
+    } finally {
+      db.close()
+    }
+  })
+
+  it('keeps the latest duplicate row when migrating legacy ACP session links', async () => {
+    const db = new DatabaseCtor(':memory:')
+    try {
+      const table = new AcpSessionsTable(db)
+      db.exec(`
+        CREATE TABLE acp_sessions (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          conversation_id TEXT NOT NULL,
+          agent_id TEXT NOT NULL,
+          session_id TEXT,
+          workdir TEXT,
+          status TEXT NOT NULL DEFAULT 'idle',
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL,
+          metadata TEXT,
+          UNIQUE(conversation_id, agent_id)
+        );
+        INSERT INTO acp_sessions
+          (conversation_id, agent_id, session_id, workdir, status, created_at, updated_at, metadata)
+        VALUES
+          ('conv-old', 'agent-a', 'remote-1', '/old', 'idle', 1, 10, NULL),
+          ('conv-new', 'agent-a', 'remote-1', '/new', 'active', 1, 20, NULL),
+          ('conv-b', 'agent-b', 'remote-1', '/other', 'idle', 1, 15, NULL);
+      `)
+
+      db.exec(table.getMigrationSQL(30) ?? '')
+
+      expect(await table.getByAgentAndSessionId('agent-a', 'remote-1')).toMatchObject({
+        conversationId: 'conv-new',
+        agentId: 'agent-a',
+        sessionId: 'remote-1',
+        workdir: '/new',
+        status: 'active'
+      })
+      expect(await table.getByAgentAndSessionId('agent-b', 'remote-1')).toMatchObject({
+        conversationId: 'conv-b',
+        agentId: 'agent-b',
+        sessionId: 'remote-1',
+        workdir: '/other'
+      })
+    } finally {
+      db.close()
+    }
+  })
+})

From 898f8fd327b2b33a770381f98e268ec622f385d4 Mon Sep 17 00:00:00 2001
From: yyhhyyyyyy <yyhhyyyyyy8@gmail.com>
Date: Tue, 2 Jun 2026 16:03:30 +0800
Subject: [PATCH 4/8] fix(renderer): use capabilities for temperature UI
 (#1725)

* fix(renderer): use capabilities for temperature UI

* fix(renderer): remove unused chat config option
---
 .../remove-gpt5-temperature-hardcode/plan.md  | 19 ++++++++
 .../remove-gpt5-temperature-hardcode/spec.md  | 26 ++++++++++
 .../remove-gpt5-temperature-hardcode/tasks.md |  7 +++
 src/renderer/src/components/ChatConfig.vue    |  3 +-
 .../src/composables/useChatConfigFields.ts    |  7 ++-
 .../src/composables/useModelCapabilities.ts   | 12 ++++-
 .../src/composables/useModelTypeDetection.ts  | 11 -----
 .../composables/useChatConfigFields.test.ts   | 47 ++++++++++++++++++
 .../composables/useModelCapabilities.test.ts  | 48 +++++++++++++++++--
 .../composables/useModelTypeDetection.test.ts |  3 +-
 10 files changed, 159 insertions(+), 24 deletions(-)
 create mode 100644 docs/issues/remove-gpt5-temperature-hardcode/plan.md
 create mode 100644 docs/issues/remove-gpt5-temperature-hardcode/spec.md
 create mode 100644 docs/issues/remove-gpt5-temperature-hardcode/tasks.md
 create mode 100644 test/renderer/composables/useChatConfigFields.test.ts

diff --git a/docs/issues/remove-gpt5-temperature-hardcode/plan.md b/docs/issues/remove-gpt5-temperature-hardcode/plan.md
new file mode 100644
index 000000000..3a180f6b8
--- /dev/null
+++ b/docs/issues/remove-gpt5-temperature-hardcode/plan.md
@@ -0,0 +1,19 @@
+# Remove GPT-5 Temperature Hardcode Plan
+
+## Implementation
+
+- Extend `useModelCapabilities` to expose `supportsTemperatureControl`, using
+  `supportsTemperatureControl` first and `temperatureCapability` as the fallback.
+- Remove `isGPT5Model` from `useModelTypeDetection` and stop passing it through `ChatConfig`.
+- Update `useChatConfigFields` to show temperature unless `supportsTemperatureControl` is exactly
+  `false`.
+
+## Test Strategy
+
+- Update model type detection tests to cover only type and provider detection plus reasoning loading.
+- Add focused `useChatConfigFields` tests for unsupported, supported, and unknown temperature
+  capability states.
+
+## Compatibility
+
+- Capability `null` preserves the previous default-visible behavior for unknown and custom models.
diff --git a/docs/issues/remove-gpt5-temperature-hardcode/spec.md b/docs/issues/remove-gpt5-temperature-hardcode/spec.md
new file mode 100644
index 000000000..d4538fc57
--- /dev/null
+++ b/docs/issues/remove-gpt5-temperature-hardcode/spec.md
@@ -0,0 +1,26 @@
+# Remove GPT-5 Temperature Hardcode
+
+## User Story
+
+As a user configuring chat generation settings, I want temperature controls to follow model
+capability metadata instead of frontend model-name matching, so supported models keep their controls
+and unsupported models hide them consistently.
+
+## Acceptance Criteria
+
+- ChatConfig hides the temperature slider only when model capabilities explicitly report
+  temperature control as unsupported.
+- GPT-5-like model IDs do not automatically hide temperature when capabilities report support.
+- Missing or unavailable capability data keeps the existing conservative behavior and shows
+  temperature.
+
+## Non-goals
+
+- Do not change backend request filtering.
+- Do not update provider model database contents.
+- Do not introduce OpenAI-specific frontend special cases.
+
+## Constraints
+
+- Reuse the existing `models.getCapabilities` surface.
+- Keep the change scoped to renderer configuration UI behavior.
diff --git a/docs/issues/remove-gpt5-temperature-hardcode/tasks.md b/docs/issues/remove-gpt5-temperature-hardcode/tasks.md
new file mode 100644
index 000000000..81e08582c
--- /dev/null
+++ b/docs/issues/remove-gpt5-temperature-hardcode/tasks.md
@@ -0,0 +1,7 @@
+# Remove GPT-5 Temperature Hardcode Tasks
+
+- [x] Add SDD records.
+- [x] Expose temperature support from `useModelCapabilities`.
+- [x] Replace GPT-5 string matching in ChatConfig field generation.
+- [x] Update and add renderer composable tests.
+- [x] Run targeted tests and project checks.
diff --git a/src/renderer/src/components/ChatConfig.vue b/src/renderer/src/components/ChatConfig.vue
index 044aaf584..205dbfb09 100644
--- a/src/renderer/src/components/ChatConfig.vue
+++ b/src/renderer/src/components/ChatConfig.vue
@@ -110,8 +110,7 @@ const { sliderFields, inputFields, selectFields } = useChatConfigFields({
   providerId: toRef(props, 'providerId'),
 
   // Composables
-  isGPT5Model: modelTypeDetection.isGPT5Model,
-  isImageGenerationModel: modelTypeDetection.isImageGenerationModel,
+  supportsTemperatureControl: capabilities.supportsTemperatureControl,
   showThinkingBudget: thinkingBudget.showThinkingBudget,
   thinkingBudgetError: thinkingBudget.validationError,
   budgetRange: capabilities.budgetRange,
diff --git a/src/renderer/src/composables/useChatConfigFields.ts b/src/renderer/src/composables/useChatConfigFields.ts
index d09c1b40f..f6c6f8d5f 100644
--- a/src/renderer/src/composables/useChatConfigFields.ts
+++ b/src/renderer/src/composables/useChatConfigFields.ts
@@ -31,8 +31,7 @@ export interface UseChatConfigFieldsOptions {
   providerId: Ref<string | undefined>
 
   // Composables
-  isGPT5Model: ComputedRef<boolean>
-  isImageGenerationModel: ComputedRef<boolean>
+  supportsTemperatureControl: Ref<boolean | null>
   showThinkingBudget: ComputedRef<boolean>
   thinkingBudgetError: ComputedRef<string>
   budgetRange: Ref<{ min?: number; max?: number; default?: number } | null>
@@ -62,8 +61,8 @@ export function useChatConfigFields(options: UseChatConfigFieldsOptions) {
   const sliderFields = computed<SliderFieldConfig[]>(() => {
     const fields: SliderFieldConfig[] = []
 
-    // Temperature (hidden for GPT-5)
-    if (!options.isGPT5Model.value) {
+    // Temperature is hidden only when model capabilities explicitly disable it.
+    if (options.supportsTemperatureControl.value !== false) {
       fields.push({
         key: 'temperature',
         type: 'slider',
diff --git a/src/renderer/src/composables/useModelCapabilities.ts b/src/renderer/src/composables/useModelCapabilities.ts
index 3bb1002bf..a298d470c 100644
--- a/src/renderer/src/composables/useModelCapabilities.ts
+++ b/src/renderer/src/composables/useModelCapabilities.ts
@@ -17,6 +17,7 @@ export interface ModelCapabilities {
     forced?: boolean
     strategy?: 'turbo' | 'max'
   } | null
+  supportsTemperatureControl: boolean | null
 }
 
 export interface UseModelCapabilitiesOptions {
@@ -40,6 +41,7 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
     default?: number
   } | null>(null)
   const capabilitySupportsSearch = ref<boolean | null>(null)
+  const capabilitySupportsTemperatureControl = ref<boolean | null>(null)
   const capabilitySearchDefaults = ref<{
     default?: boolean
     forced?: boolean
@@ -53,6 +55,7 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
     capabilitySupportsReasoning.value = null
     capabilityBudgetRange.value = null
     capabilitySupportsSearch.value = null
+    capabilitySupportsTemperatureControl.value = null
     capabilitySearchDefaults.value = null
   }
 
@@ -69,11 +72,13 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
 
     isLoading.value = true
     try {
-      const [sr, br, ss, sd] = await Promise.all([
+      const [sr, br, ss, sd, stc, tc] = await Promise.all([
         modelClient.supportsReasoningCapability(currentProviderId, currentModelId),
         modelClient.getThinkingBudgetRange(currentProviderId, currentModelId),
         modelClient.supportsSearchCapability(currentProviderId, currentModelId),
-        modelClient.getSearchDefaults(currentProviderId, currentModelId)
+        modelClient.getSearchDefaults(currentProviderId, currentModelId),
+        modelClient.supportsTemperatureControl(currentProviderId, currentModelId),
+        modelClient.getTemperatureCapability(currentProviderId, currentModelId)
       ])
 
       if (currentRequestId !== requestId) return
@@ -82,6 +87,8 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
       capabilityBudgetRange.value = br || {}
       capabilitySupportsSearch.value = typeof ss === 'boolean' ? ss : null
       capabilitySearchDefaults.value = sd || {}
+      capabilitySupportsTemperatureControl.value =
+        typeof stc === 'boolean' ? stc : typeof tc === 'boolean' ? tc : null
     } catch (error) {
       if (currentRequestId !== requestId) return
 
@@ -104,6 +111,7 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
     budgetRange: capabilityBudgetRange,
     supportsSearch: capabilitySupportsSearch,
     searchDefaults: capabilitySearchDefaults,
+    supportsTemperatureControl: capabilitySupportsTemperatureControl,
     isLoading,
     // Methods
     refresh: fetchCapabilities
diff --git a/src/renderer/src/composables/useModelTypeDetection.ts b/src/renderer/src/composables/useModelTypeDetection.ts
index af6203408..f6e4d4230 100644
--- a/src/renderer/src/composables/useModelTypeDetection.ts
+++ b/src/renderer/src/composables/useModelTypeDetection.ts
@@ -17,7 +17,6 @@ export interface UseModelTypeDetectionReturn {
   isImageGenerationModel: ComputedRef<boolean>
   isVideoGenerationModel: ComputedRef<boolean>
   isTtsModel: ComputedRef<boolean>
-  isGPT5Model: ComputedRef<boolean>
   isGeminiProvider: ComputedRef<boolean>
   modelReasoning: Ref<boolean>
 }
@@ -59,15 +58,6 @@ export function useModelTypeDetection(
     return modelType.value === 'tts'
   })
 
-  /**
-   * Checks if current model is GPT-5 series
-   * GPT-5 models have special UI requirements (no temperature slider)
-   */
-  const isGPT5Model = computed(() => {
-    const id = modelId.value?.toLowerCase() || ''
-    return id.includes('gpt-5')
-  })
-
   /**
    * Checks if current provider is Gemini
    * Gemini has special thinking budget rules (-1 for unlimited)
@@ -106,7 +96,6 @@ export function useModelTypeDetection(
     isImageGenerationModel,
     isVideoGenerationModel,
     isTtsModel,
-    isGPT5Model,
     isGeminiProvider,
     modelReasoning
   }
diff --git a/test/renderer/composables/useChatConfigFields.test.ts b/test/renderer/composables/useChatConfigFields.test.ts
new file mode 100644
index 000000000..f11805b50
--- /dev/null
+++ b/test/renderer/composables/useChatConfigFields.test.ts
@@ -0,0 +1,47 @@
+import { computed, ref } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import { useChatConfigFields } from '@/composables/useChatConfigFields'
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key })
+}))
+
+function createFields(supportsTemperatureControl: boolean | null) {
+  return useChatConfigFields({
+    temperature: ref(0.7),
+    contextLength: ref(4096),
+    maxTokens: ref(1024),
+    contextLengthLimit: ref(undefined),
+    maxTokensLimit: ref(undefined),
+    thinkingBudget: ref(undefined),
+    reasoningEffort: ref(undefined),
+    verbosity: ref(undefined),
+    providerId: ref('openai'),
+    supportsTemperatureControl: ref(supportsTemperatureControl),
+    showThinkingBudget: computed(() => false),
+    thinkingBudgetError: computed(() => ''),
+    budgetRange: ref(null),
+    formatSize: (size: number) => String(size),
+    emit: vi.fn()
+  })
+}
+
+describe('useChatConfigFields', () => {
+  it('hides temperature when capabilities explicitly disable temperature control', () => {
+    const { sliderFields } = createFields(false)
+
+    expect(sliderFields.value.some((field) => field.key === 'temperature')).toBe(false)
+  })
+
+  it('shows temperature when capabilities support temperature control', () => {
+    const { sliderFields } = createFields(true)
+
+    expect(sliderFields.value.some((field) => field.key === 'temperature')).toBe(true)
+  })
+
+  it('shows temperature while temperature capability is unknown', () => {
+    const { sliderFields } = createFields(null)
+
+    expect(sliderFields.value.some((field) => field.key === 'temperature')).toBe(true)
+  })
+})
diff --git a/test/renderer/composables/useModelCapabilities.test.ts b/test/renderer/composables/useModelCapabilities.test.ts
index 2394c5d58..a74ca24d9 100644
--- a/test/renderer/composables/useModelCapabilities.test.ts
+++ b/test/renderer/composables/useModelCapabilities.test.ts
@@ -4,7 +4,9 @@ const modelClient = vi.hoisted(() => ({
   supportsReasoningCapability: vi.fn(),
   getThinkingBudgetRange: vi.fn(),
   supportsSearchCapability: vi.fn(),
-  getSearchDefaults: vi.fn()
+  getSearchDefaults: vi.fn(),
+  supportsTemperatureControl: vi.fn(),
+  getTemperatureCapability: vi.fn()
 }))
 
 vi.mock('@api/ModelClient', () => ({
@@ -38,6 +40,8 @@ describe('useModelCapabilities', () => {
       forced: false,
       strategy: 'turbo'
     })
+    modelClient.supportsTemperatureControl.mockResolvedValue(false)
+    modelClient.getTemperatureCapability.mockResolvedValue(true)
 
     const api = useModelCapabilities({ providerId, modelId })
     // initial immediate fetch occurs - wait for isLoading to become false
@@ -46,12 +50,30 @@ describe('useModelCapabilities', () => {
     expect(api.budgetRange.value?.max).toBe(200)
     expect(api.supportsSearch.value).toBe(true)
     expect(api.searchDefaults.value?.strategy).toBe('turbo')
+    expect(api.supportsTemperatureControl.value).toBe(false)
 
     // reset path
     providerId.value = undefined
     await vi.waitFor(() => expect(api.isLoading.value).toBe(false))
     expect(api.supportsReasoning.value).toBeNull()
     expect(api.budgetRange.value).toBeNull()
+    expect(api.supportsTemperatureControl.value).toBeNull()
+  })
+
+  it('falls back to temperatureCapability when supportsTemperatureControl is missing', async () => {
+    const providerId = ref<string | undefined>('openai')
+    const modelId = ref<string | undefined>('gpt-5-chat-latest')
+    modelClient.supportsReasoningCapability.mockResolvedValue(false)
+    modelClient.getThinkingBudgetRange.mockResolvedValue(null)
+    modelClient.supportsSearchCapability.mockResolvedValue(false)
+    modelClient.getSearchDefaults.mockResolvedValue(null)
+    modelClient.supportsTemperatureControl.mockResolvedValue(null)
+    modelClient.getTemperatureCapability.mockResolvedValue(true)
+
+    const api = useModelCapabilities({ providerId, modelId })
+
+    await vi.waitFor(() => expect(api.isLoading.value).toBe(false))
+    expect(api.supportsTemperatureControl.value).toBe(true)
   })
 
   it('ignores stale capability responses after model changes', async () => {
@@ -61,13 +83,17 @@ describe('useModelCapabilities', () => {
       supportsReasoning: deferred<boolean>(),
       budgetRange: deferred<{ min: number; max: number }>(),
       supportsSearch: deferred<boolean>(),
-      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>()
+      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>(),
+      supportsTemperatureControl: deferred<boolean>(),
+      temperatureCapability: deferred<boolean>()
     }
     const newResponse = {
       supportsReasoning: deferred<boolean>(),
       budgetRange: deferred<{ min: number; max: number }>(),
       supportsSearch: deferred<boolean>(),
-      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>()
+      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>(),
+      supportsTemperatureControl: deferred<boolean>(),
+      temperatureCapability: deferred<boolean>()
     }
 
     modelClient.supportsReasoningCapability.mockImplementation((_provider, model) =>
@@ -84,6 +110,16 @@ describe('useModelCapabilities', () => {
     modelClient.getSearchDefaults.mockImplementation((_provider, model) =>
       model === 'gpt-old' ? oldResponse.searchDefaults.promise : newResponse.searchDefaults.promise
     )
+    modelClient.supportsTemperatureControl.mockImplementation((_provider, model) =>
+      model === 'gpt-old'
+        ? oldResponse.supportsTemperatureControl.promise
+        : newResponse.supportsTemperatureControl.promise
+    )
+    modelClient.getTemperatureCapability.mockImplementation((_provider, model) =>
+      model === 'gpt-old'
+        ? oldResponse.temperatureCapability.promise
+        : newResponse.temperatureCapability.promise
+    )
 
     const api = useModelCapabilities({ providerId, modelId })
     await vi.waitFor(() => expect(modelClient.supportsReasoningCapability).toHaveBeenCalledTimes(1))
@@ -95,21 +131,27 @@ describe('useModelCapabilities', () => {
     newResponse.budgetRange.resolve({ min: 10, max: 20 })
     newResponse.supportsSearch.resolve(false)
     newResponse.searchDefaults.resolve({ strategy: 'max' })
+    newResponse.supportsTemperatureControl.resolve(false)
+    newResponse.temperatureCapability.resolve(true)
 
     await vi.waitFor(() => expect(api.budgetRange.value?.max).toBe(20))
     expect(api.supportsReasoning.value).toBe(false)
     expect(api.supportsSearch.value).toBe(false)
     expect(api.searchDefaults.value?.strategy).toBe('max')
+    expect(api.supportsTemperatureControl.value).toBe(false)
 
     oldResponse.supportsReasoning.resolve(true)
     oldResponse.budgetRange.resolve({ min: 100, max: 200 })
     oldResponse.supportsSearch.resolve(true)
     oldResponse.searchDefaults.resolve({ strategy: 'turbo' })
+    oldResponse.supportsTemperatureControl.resolve(true)
+    oldResponse.temperatureCapability.resolve(true)
     await Promise.resolve()
 
     expect(api.budgetRange.value?.max).toBe(20)
     expect(api.supportsReasoning.value).toBe(false)
     expect(api.supportsSearch.value).toBe(false)
     expect(api.searchDefaults.value?.strategy).toBe('max')
+    expect(api.supportsTemperatureControl.value).toBe(false)
   })
 })
diff --git a/test/renderer/composables/useModelTypeDetection.test.ts b/test/renderer/composables/useModelTypeDetection.test.ts
index 4f1703a09..99830ad70 100644
--- a/test/renderer/composables/useModelTypeDetection.test.ts
+++ b/test/renderer/composables/useModelTypeDetection.test.ts
@@ -26,7 +26,7 @@ describe('useModelTypeDetection', () => {
   })
 
   it('detects provider/model type and loads reasoning flag', async () => {
-    const modelId = ref<string | undefined>('gpt-5-pro')
+    const modelId = ref<string | undefined>('gemini-pro')
     const providerId = ref<string | undefined>('gemini')
     const modelType = ref<'chat' | 'imageGeneration' | 'embedding' | 'rerank' | undefined>(
       'imageGeneration'
@@ -34,7 +34,6 @@ describe('useModelTypeDetection', () => {
 
     const api = useModelTypeDetection({ modelId, providerId, modelType })
     expect(api.isImageGenerationModel.value).toBe(true)
-    expect(api.isGPT5Model.value).toBe(true)
     expect(api.isGeminiProvider.value).toBe(true)
 
     await Promise.resolve()

From 8003a56d50eeeee7f1a194dc21aedd89c3e3125a Mon Sep 17 00:00:00 2001
From: duskzhen <zerob13@gmail.com>
Date: Tue, 2 Jun 2026 18:08:56 +0800
Subject: [PATCH 5/8] feat(chat): collapse turn activity (#1727)

* feat(chat): collapse turn activity

* fix(chat): address activity review
---
 .../automatic-turn-activity-collapse/plan.md  | 345 ++++++++++++++++++
 .../automatic-turn-activity-collapse/spec.md  | 285 +++++++++++++++
 .../automatic-turn-activity-collapse/tasks.md |  21 ++
 .../src/components/chat/messageListItems.ts   |   1 +
 .../message/MessageBlockActivityGroup.vue     | 114 ++++++
 .../message/MessageItemAssistant.vue          |  74 +++-
 .../message/messageActivityGroups.ts          | 184 ++++++++++
 src/renderer/src/i18n/da-DK/chat.json         |  13 +
 src/renderer/src/i18n/de-DE/chat.json         |  13 +
 src/renderer/src/i18n/en-US/chat.json         |  13 +
 src/renderer/src/i18n/es-ES/chat.json         |  13 +
 src/renderer/src/i18n/fa-IR/chat.json         |  13 +
 src/renderer/src/i18n/fr-FR/chat.json         |  13 +
 src/renderer/src/i18n/he-IL/chat.json         |  13 +
 src/renderer/src/i18n/id-ID/chat.json         |  13 +
 src/renderer/src/i18n/it-IT/chat.json         |  13 +
 src/renderer/src/i18n/ja-JP/chat.json         |  13 +
 src/renderer/src/i18n/ko-KR/chat.json         |  13 +
 src/renderer/src/i18n/ms-MY/chat.json         |  13 +
 src/renderer/src/i18n/pl-PL/chat.json         |  13 +
 src/renderer/src/i18n/pt-BR/chat.json         |  13 +
 src/renderer/src/i18n/ru-RU/chat.json         |  13 +
 src/renderer/src/i18n/tr-TR/chat.json         |  13 +
 src/renderer/src/i18n/vi-VN/chat.json         |  13 +
 src/renderer/src/i18n/zh-CN/chat.json         |  13 +
 src/renderer/src/i18n/zh-HK/chat.json         |  13 +
 src/renderer/src/i18n/zh-TW/chat.json         |  13 +
 src/renderer/src/pages/ChatPage.vue           |   5 +-
 test/renderer/components/MessageList.test.ts  |   1 +
 .../message/MessageBlockActivityGroup.test.ts | 162 ++++++++
 .../message/MessageItemAssistant.test.ts      | 124 ++++++-
 .../message/messageActivityGroups.test.ts     | 159 ++++++++
 32 files changed, 1713 insertions(+), 22 deletions(-)
 create mode 100644 docs/features/automatic-turn-activity-collapse/plan.md
 create mode 100644 docs/features/automatic-turn-activity-collapse/spec.md
 create mode 100644 docs/features/automatic-turn-activity-collapse/tasks.md
 create mode 100644 src/renderer/src/components/message/MessageBlockActivityGroup.vue
 create mode 100644 src/renderer/src/components/message/messageActivityGroups.ts
 create mode 100644 test/renderer/components/message/MessageBlockActivityGroup.test.ts
 create mode 100644 test/renderer/components/message/messageActivityGroups.test.ts

diff --git a/docs/features/automatic-turn-activity-collapse/plan.md b/docs/features/automatic-turn-activity-collapse/plan.md
new file mode 100644
index 000000000..f7da5f43e
--- /dev/null
+++ b/docs/features/automatic-turn-activity-collapse/plan.md
@@ -0,0 +1,345 @@
+# Plan
+
+## Approach
+
+Implement a render-only activity grouping layer inside assistant message rendering:
+
+1. Expose assistant `updatedAt` on `DisplayMessage`.
+2. Add a small pure helper that turns assistant blocks into render items.
+3. Add a compact `MessageBlockActivityGroup.vue` component that renders the title and, when expanded,
+   delegates to the existing reasoning/tool-call block components.
+4. Update `MessageItemAssistant.vue` to render grouped items only when the turn is settled.
+5. Add localized title strings and duration formatter output.
+6. Cover the helper and component behavior with renderer tests.
+
+No main-process, preload, IPC, route, database, or shared event contract changes are planned for the
+first increment.
+
+Persistence decision:
+
+- Do not persist derived activity groups.
+- Do not persist per-group expanded/collapsed state.
+- Keep the default state collapsed each time a completed assistant message group is mounted.
+- Use renderer computation first; add only an in-memory cache if profiling shows a real bottleneck.
+
+## Affected Files
+
+Expected renderer files:
+
+- `src/renderer/src/components/chat/messageListItems.ts`
+- `src/renderer/src/pages/ChatPage.vue`
+- `src/renderer/src/components/message/MessageItemAssistant.vue`
+- `src/renderer/src/components/message/MessageBlockActivityGroup.vue`
+- `src/renderer/src/components/message/messageActivityGroups.ts`
+- `src/renderer/src/i18n/*/chat.json`
+
+Expected tests:
+
+- `test/renderer/components/message/MessageItemAssistant.test.ts`
+- `test/renderer/components/message/MessageBlockActivityGroup.test.ts`
+- `test/renderer/components/message/messageActivityGroups.test.ts`
+
+## Display Model
+
+Add `updatedAt` to the renderer-only `DisplayMessageBase`.
+
+```typescript
+type DisplayMessageBase = {
+  id: string
+  timestamp: number
+  updatedAt: number
+  // existing fields...
+}
+```
+
+Populate it in:
+
+- `toDisplayMessage(record)`: `updatedAt: record.updatedAt`
+- `toStreamingMessage(...)`: `updatedAt: Date.now()` for type completeness, though streaming messages
+  must not be auto-grouped.
+
+## Render Item Model
+
+Keep the persisted `DisplayAssistantMessageBlock[]` unchanged. Add only a local UI render model.
+
+```typescript
+type AssistantRenderItem =
+  | {
+      kind: 'block'
+      key: string
+      block: DisplayAssistantMessageBlock
+    }
+  | {
+      kind: 'activity-group'
+      key: string
+      blocks: DisplayAssistantMessageBlock[]
+      startedAt: number
+      endedAt: number
+      durationMs: number
+      reasoningCount: number
+      toolCallCount: number
+    }
+```
+
+This is not written to message content and is not sent over IPC.
+
+## Performance Model
+
+The grouping helper is an O(n) pass over the assistant block array, where n is the number of blocks in
+one assistant message. This is expected to be cheaper than markdown rendering, tool-call detail
+rendering, syntax highlighting, and media previews.
+
+Renderer computation is preferred over persistence because the renderer already needs the block array
+to decide which existing component to render. Persisting grouping state would not remove the need to
+parse/render the message content, but would add:
+
+- storage reads/writes for every manual toggle if UI state is persisted,
+- schema or settings-key lifecycle concerns,
+- stale synthetic ids after retry/regeneration/import,
+- cleanup work when messages are deleted,
+- extra compatibility surface for exports and variants.
+
+Implementation should keep the helper pure and easy to memoize. If needed, cache render items in
+memory by:
+
+```text
+messageId + content reference/hash + updatedAt + status + shouldGroupActivity
+```
+
+Do not add disk persistence as a performance optimization without measured renderer cost.
+
+## Grouping Helper
+
+Create a pure helper near message components:
+
+```typescript
+buildAssistantRenderItems({
+  blocks,
+  messageId,
+  messageUpdatedAt,
+  shouldGroup,
+  isInternalToolCall
+}): AssistantRenderItem[]
+```
+
+Rules:
+
+- `shouldGroup === false`: every visible block returns as `kind: 'block'`.
+- A block is activity when it matches the spec's collapsible activity definition.
+- A block is groupable only when its status is not `loading` or `pending`.
+- Consecutive groupable activity blocks are buffered.
+- Any non-groupable visible block flushes the buffer before itself.
+- Internal hidden tool calls are skipped exactly as they are today.
+
+Keying:
+
+- Use stable block ids/tool call ids when present.
+- Fall back to `messageId:index`.
+- Group key can be `activity:${messageId}:${firstIndex}:${lastIndex}`.
+
+## Turn Settled Gate
+
+In `MessageItemAssistant.vue`, compute:
+
+```typescript
+const shouldGroupActivity = computed(() => {
+  if (resolvedIsInGeneratingThread.value) return false
+  if (currentMessage.value.status === 'pending') return false
+  return true
+})
+```
+
+If implementation finds paused user-interaction turns have `status: pending` even after stream end,
+do not broaden the first increment. Keep pending turns ungrouped unless a reliable existing signal
+already distinguishes inactive pending from active streaming.
+
+This keeps the behavior strict and avoids hiding activity while the turn is still live.
+
+## Activity Group Component
+
+`MessageBlockActivityGroup.vue` props:
+
+```typescript
+defineProps<{
+  blocks: DisplayAssistantMessageBlock[]
+  messageId: string
+  threadId: string
+  usage: DisplayMessageUsage
+  startedAt: number
+  endedAt: number
+  reasoningCount: number
+  toolCallCount: number
+}>()
+```
+
+State:
+
+- `isExpanded = false` by default.
+- Local state only; no config setting and no message metadata write.
+- Toggling emits `toggle-collapse` so `MessageItemAssistant` can reuse the existing
+  `variantChanged` notification path.
+
+Rendering:
+
+- Title row mirrors `ThinkContent` text size/color/chevron.
+- The title row is a real button with reset button styles.
+- Expanded children render in a flat `flex flex-col gap-1.5` container with no added left padding.
+- Reasoning blocks use `MessageBlockThink`.
+- Tool-call blocks use `MessageBlockToolCall`.
+- Artifact thinking can reuse the same visual pattern as reasoning if the codebase already renders
+  it through `MessageBlockThink`; otherwise keep it as an explicit non-goal for the first
+  implementation pass.
+
+## Title Text
+
+Recommended Chinese title:
+
+```text
+已经工作了 {duration} · {reasoningCount} 段思考 · {toolCallCount} 次工具调用
+```
+
+Recommended English title:
+
+```text
+Worked for {duration} · {reasoningCount} thought(s) · {toolCallCount} tool call(s)
+```
+
+Omit count segments when the count is `0`:
+
+- reasoning only: `已经工作了 12秒 · 1 段思考`
+- tool calls only: `已经工作了 12秒 · 2 次工具调用`
+
+## Duration Formatting
+
+Add a local formatter in the grouping helper or a small companion file. Keep the formatter pure and
+pass localized unit labels from `MessageBlockActivityGroup.vue`:
+
+```typescript
+type ActivityDurationLabels = {
+  day: string
+  hour: string
+  minute: string
+  second: string
+}
+
+formatActivityDuration(durationMs: number, labels: ActivityDurationLabels): string
+```
+
+Implementation detail:
+
+- Clamp non-finite values to `0`.
+- `totalSeconds = Math.max(0, Math.floor(durationMs / 1000))`.
+- Compute days/hours/minutes/seconds.
+- Concatenate non-zero units and include seconds when all larger units are zero.
+- Use localized unit labels from `chat.activityCollapse.duration.*`.
+- Unit labels may include spacing when the locale needs spaces between duration segments.
+
+Avoid `Intl.DurationFormat` for now because support varies and would add fallback complexity.
+
+## Styling
+
+Use the current reasoning header as the visual reference:
+
+- `text-xs`
+- `leading-4`
+- muted foreground color consistent with `ThinkContent`
+- `lucide:chevron-right` when collapsed
+- `lucide:chevron-down` when expanded
+- no border/card wrapper
+- no additional content indentation
+- `self-start` width title, not full-width panel
+
+ASCII layout target:
+
+```text
+Assistant row
+  icon | message column
+       | info line
+       | > Worked for 1m 12s · 1 thought · 2 tool calls
+       | visible answer text
+```
+
+Expanded target:
+
+```text
+Assistant row
+  icon | message column
+       | v Worked for 1m 12s · 1 thought · 2 tool calls
+       | Thinking for 18s
+       | [tool] shell_command
+       | [tool] read_file
+       | visible answer text
+```
+
+## Compatibility
+
+- Existing persisted messages render unchanged except for the new collapsed presentation.
+- Export, context building, compaction, and model input are unaffected because stored blocks are not
+  changed.
+- Copy behavior remains based on `currentContent`.
+- Existing reasoning global setting `think_collapse` remains scoped to individual reasoning content
+  when a group is expanded. The group's default collapsed state is independent.
+- Manual activity-group expansion is intentionally not remembered across reloads in the first
+  increment.
+- Search and trace behavior are unaffected.
+
+## Risks
+
+1. **Duration overcounts separate groups in the same message.**
+   - Mitigation: first increment uses the only reliable end timestamp available in the current display
+     model, the final assistant message `updatedAt`. Do not add backend block update timestamps unless
+     the UX proves this is misleading.
+2. **Pending paused turns may remain long.**
+   - Mitigation: keep first increment strict. If needed later, add a reliable settled-state signal
+     rather than guessing from block shapes.
+3. **Rendering logic duplication.**
+   - Mitigation: group component renders only the narrow set of groupable block types.
+4. **Layout shift after reload.**
+   - Mitigation: collapse only after stream completion reload; this is expected and solves transcript
+     length. Keep scrolling behavior covered by existing message-list auto-scroll tests if affected.
+5. **Repeated renderer grouping work.**
+   - Mitigation: keep grouping pure and O(n). Add in-memory memoization only if profiling shows the
+     helper is material compared with existing block rendering.
+
+## Test Strategy
+
+Unit tests:
+
+- Group consecutive reasoning/tool-call blocks after a settled turn.
+- Split groups around `content` blocks.
+- Skip grouping when `shouldGroup` is false.
+- Skip `loading` and `pending` activity blocks.
+- Preserve internal hidden tool-call behavior.
+- Format duration for seconds, minutes, hours, and days.
+- Verify grouping helper remains deterministic so in-memory memoization is safe if added later.
+
+Component tests:
+
+- `MessageItemAssistant` renders `MessageBlockActivityGroup` for final messages.
+- `MessageItemAssistant` renders raw `MessageBlockThink` / `MessageBlockToolCall` while pending.
+- `MessageBlockActivityGroup` starts collapsed.
+- Clicking title expands and shows child reasoning/tool-call stubs.
+- Clicking again collapses.
+- Remounting a group returns it to the default collapsed state.
+- Title includes duration and counts.
+
+Manual QA:
+
+- Long agent turn with multiple tool calls.
+- Turn with only final text and no activity.
+- Turn with reasoning only.
+- Turn with tool calls only.
+- Error final message.
+- Dark mode.
+- Narrow chat width.
+
+Quality gates after implementation:
+
+```text
+pnpm run format
+pnpm run i18n
+pnpm run lint
+pnpm run typecheck
+pnpm test -- MessageItemAssistant
+pnpm test -- MessageBlockActivityGroup
+```
diff --git a/docs/features/automatic-turn-activity-collapse/spec.md b/docs/features/automatic-turn-activity-collapse/spec.md
new file mode 100644
index 000000000..be7fa8007
--- /dev/null
+++ b/docs/features/automatic-turn-activity-collapse/spec.md
@@ -0,0 +1,285 @@
+# Automatic Turn Activity Collapse
+
+## User Need
+
+DeepChat agent turns can include multiple reasoning sections and tool calls before the final answer.
+When every intermediate block remains expanded, one assistant turn becomes too long to scan and the
+final conclusion is pushed far down the transcript.
+
+Users need completed thinking/tool activity to collapse automatically after the turn settles, while
+keeping the final text answer visible and preserving the current message layout.
+
+## Goal
+
+After an assistant turn is complete, automatically group completed reasoning and visible tool-call
+blocks into a compact collapsible title row. The title should reuse the visual language of the
+current reasoning-content header, show how long the grouped work took, and expand/collapse on click.
+
+The grouping is a renderer-only presentation transform over the existing assistant message blocks.
+It must not create a new persisted message type, database table, or backend transport contract unless
+implementation proves the renderer cannot compute the required state reliably.
+
+## Current Structure Summary
+
+- Chat messages are loaded in `ChatPage.vue` from `ChatMessageRecord` into `DisplayMessage`.
+- Assistant content is stored as a JSON array of `AssistantMessageBlock`.
+- `MessageItemAssistant.vue` renders assistant blocks in order:
+  - `content` through `MessageBlockContent`
+  - `reasoning_content` through `MessageBlockThink`
+  - `tool_call` through `MessageBlockToolCall`
+  - other block types through their existing block components
+- Streaming updates apply blocks inline while the assistant message is pending, then stream end reloads
+  the persisted message.
+- Reasoning UI uses `ThinkContent.vue`, whose title row is compact text plus a chevron/ellipsis.
+
+## UX Requirements
+
+1. During streaming, keep the current layout and do not auto-collapse new blocks.
+2. After the turn settles, collapse completed reasoning/tool-call activity by default.
+3. Keep regular assistant text content visible by default.
+4. Clicking the activity title toggles the grouped activity open/closed.
+5. The activity title must not introduce a new indentation level for the expanded blocks.
+6. The expanded content must reuse existing reasoning/tool-call block rendering.
+7. Pending user actions, errors, media, plans, and normal text content must remain visible unless they
+   already have their own existing collapsed behavior.
+8. Internal tool calls that are already hidden, such as internal `update_plan`, must stay hidden.
+9. Copy behavior must continue to use the original assistant content array, so existing
+   `copyWithCotEnabled` behavior remains unchanged.
+10. The feature should not add a user setting in the first increment.
+
+## Collapsible Activity Definition
+
+The first increment treats these completed block types as collapsible activity:
+
+- `reasoning_content` with non-empty `content`
+- `artifact-thinking` with non-empty `content`
+- visible `tool_call` blocks, excluding current internal tool calls
+
+The first increment does not auto-collapse:
+
+- `content`
+- `plan`
+- `action`
+- `error`
+- `search`
+- `image`
+- `audio`
+- `video`
+- any block with `status` still `loading` or `pending`
+
+## Grouping Rules
+
+1. Build render groups only when the assistant turn is settled.
+2. Preserve the original block order.
+3. Consecutive collapsible activity blocks become one activity group.
+4. A visible non-activity block flushes the current activity group before rendering that block.
+5. If the final blocks are collapsible activity and the turn is settled, render them as the final
+   activity group.
+6. If a group contains only one collapsible block, still collapse it automatically after turn end.
+
+## Settled Turn Definition
+
+A turn is considered settled when the renderer is no longer receiving stream updates for that
+assistant message and the persisted message has been reloaded after stream completion or failure.
+
+Implementation should prefer existing signals:
+
+- `chat.stream.completed` / `chat.stream.failed` already trigger `loadMessages`.
+- Persisted `ChatMessageRecord.updatedAt` is available after reload.
+- `MessageItemAssistant` already receives message status and generating-thread state.
+
+The feature must not collapse blocks while the current assistant message is actively streaming.
+
+## Persistence Decision
+
+The first increment must not persist either the derived activity groups or each group's expanded /
+collapsed UI state.
+
+Keep these concepts separate:
+
+- Stored assistant blocks: existing source of truth, unchanged.
+- Derived activity groups: renderer-only, rebuilt from the block array.
+- Expanded/collapsed state: local component state, default collapsed after the group is mounted.
+
+Reasons:
+
+1. Grouping is a cheap linear pass over blocks that are already parsed for rendering.
+2. Persisting derived groups would duplicate source data and introduce invalidation rules when a
+   message is edited, retried, regenerated, imported, or rendered as a variant.
+3. Persisting per-group UI state would require stable synthetic group ids and storage cleanup for
+   deleted messages, without improving the main goal of reducing long completed turns.
+4. A stored state could make old long turns unexpectedly expanded on later visits, weakening the
+   default compact transcript behavior.
+
+If profiling later shows grouping is expensive, prefer an in-memory renderer cache keyed by message
+id, content identity, `updatedAt`, status, and the grouping gate. Do not add disk persistence for
+performance unless measurements show the renderer pass is a bottleneck.
+
+## Duration Display
+
+The collapsed title shows the duration from the grouped work's first creation timestamp to the
+containing assistant message's final update timestamp.
+
+Start timestamp:
+
+- Use the first folded block's `timestamp`.
+
+End timestamp:
+
+- Use the containing assistant message's `updatedAt` after it is exposed to the display message.
+- Clamp to the start timestamp if malformed or earlier than start.
+
+Formatting:
+
+- Use whole seconds.
+- Omit leading zero units.
+- Always include seconds when duration is under one minute.
+- Maximum display granularity is days, hours, minutes, seconds.
+- Unit labels must come from i18n, not hardcoded locale checks.
+
+Examples:
+
+- `已经工作了 8秒`
+- `已经工作了 3分钟12秒`
+- `已经工作了 2小时4分钟9秒`
+- `已经工作了 1天3小时10分钟2秒`
+
+English equivalent:
+
+- `Worked for 8s`
+- `Worked for 3m 12s`
+- `Worked for 2h 4m 9s`
+- `Worked for 1d 3h 10m 2s`
+
+## ASCII UI
+
+Before:
+
+```text
+Assistant  GPT-5  10:20
+
+Thinking for 18s                 v
+Reasoning text...
+More reasoning text...
+
+[tool] shell_command  pnpm run lint
+  params...
+  response...
+
+[tool] read_file  MessageItemAssistant.vue
+  params...
+  response...
+
+Final answer starts here...
+```
+
+After, collapsed:
+
+```text
+Assistant  GPT-5  10:20
+
+> 已经工作了 2分钟13秒 · 1 段思考 · 2 次工具调用
+
+Final answer starts here...
+```
+
+After, expanded:
+
+```text
+Assistant  GPT-5  10:20
+
+v 已经工作了 2分钟13秒 · 1 段思考 · 2 次工具调用
+Thinking for 18s                 v
+Reasoning text...
+More reasoning text...
+
+[tool] shell_command  pnpm run lint
+  params...
+  response...
+
+[tool] read_file  MessageItemAssistant.vue
+  params...
+  response...
+
+Final answer starts here...
+```
+
+No extra indentation:
+
+```text
+v 已经工作了 2分钟13秒 · 1 段思考 · 2 次工具调用
+Thinking for 18s
+[tool] shell_command
+Final answer starts here
+^ same left edge
+```
+
+Multiple activity phases in one turn:
+
+```text
+Assistant  GPT-5  10:20
+
+> 已经工作了 42秒 · 1 段思考 · 1 次工具调用
+
+I found the relevant file and will adjust the renderer grouping.
+
+> 已经工作了 1分钟9秒 · 1 段思考 · 2 次工具调用
+
+The implementation is complete.
+```
+
+## Accessibility
+
+1. The title row is a `button`.
+2. It exposes `aria-expanded`.
+3. It has an accessible label that includes the duration and whether it expands or collapses the
+   activity group.
+4. Keyboard activation uses native button behavior.
+5. The focus ring should match existing button/focus styling.
+
+## Acceptance Criteria
+
+1. Completed assistant messages with reasoning/tool-call blocks show collapsed activity groups by
+   default.
+2. Active streaming messages continue to show reasoning/tool-call progress as they do today.
+3. Clicking a collapsed group expands it and shows the original reasoning/tool-call components in the
+   original order.
+4. Clicking an expanded group collapses it again.
+5. The expanded content aligns with the group title and does not shift right compared with the
+   collapsed title.
+6. The final assistant text content remains visible without an extra click.
+7. Duration text is computed from the first folded block timestamp to the assistant message
+   `updatedAt`, formatted up to days/hours/minutes/seconds.
+8. Existing hidden internal tool calls remain hidden.
+9. Existing message copy behavior is unchanged.
+10. Grouping and expanded/collapsed UI state are not persisted in the first increment.
+11. Tests cover grouping, duration formatting, default collapsed state after turn completion, and no
+    grouping during active streaming.
+
+## Non-goals
+
+- No backend compaction or summarization of reasoning/tool results.
+- No deletion or mutation of stored assistant blocks.
+- No persistent per-user collapse preference.
+- No persisted per-message or per-group expansion state.
+- No new database table or migration.
+- No auto-collapse for pending permission/question cards.
+- No visual redesign of tool-call details.
+
+## Constraints
+
+- Keep the change focused in renderer message rendering.
+- Follow Vue 3 Composition API and existing Tailwind utility style.
+- Use existing i18n files for user-facing text.
+- Do not duplicate large message rendering logic unless extracted into a small local helper.
+- Avoid adding broad fallback heuristics for malformed historical data; clamp invalid duration and
+  render original blocks if grouping cannot be computed.
+
+## Open Questions
+
+Resolved: the first increment should be renderer-only and should not persist synthetic activity
+blocks.
+
+Resolved: grouping should happen only after a turn settles, not during streaming.
+
+Resolved: the group title should not create an indentation wrapper around expanded content.
diff --git a/docs/features/automatic-turn-activity-collapse/tasks.md b/docs/features/automatic-turn-activity-collapse/tasks.md
new file mode 100644
index 000000000..0192ccd0e
--- /dev/null
+++ b/docs/features/automatic-turn-activity-collapse/tasks.md
@@ -0,0 +1,21 @@
+# Tasks
+
+- [x] Inspect current assistant message rendering, reasoning header, tool-call block, stream end flow,
+      and display message conversion.
+- [x] Write SDD spec with UX requirements, grouping rules, duration rules, ASCII UI, and acceptance
+      criteria.
+- [x] Write implementation plan with affected files, render-only data model, component plan, and test
+      strategy.
+- [x] Document persistence and performance decision: renderer-derived grouping, local-only expansion
+      state, no disk persistence in the first increment.
+- [x] Add `updatedAt` to renderer display message types and conversion.
+- [x] Add pure activity grouping and duration formatting helper.
+- [x] Add `MessageBlockActivityGroup.vue`.
+- [x] Update `MessageItemAssistant.vue` to render grouped activity after settled turns.
+- [x] Add i18n keys for activity group title and duration units.
+- [x] Add renderer unit/component tests.
+- [x] Run `pnpm run format`.
+- [x] Run `pnpm run i18n`.
+- [x] Run `pnpm run lint`.
+- [x] Run focused renderer tests.
+- [x] Run `pnpm run typecheck` if the touched type surface is broader than expected.
diff --git a/src/renderer/src/components/chat/messageListItems.ts b/src/renderer/src/components/chat/messageListItems.ts
index f0370a21f..6033589bf 100644
--- a/src/renderer/src/components/chat/messageListItems.ts
+++ b/src/renderer/src/components/chat/messageListItems.ts
@@ -160,6 +160,7 @@ type DisplayMessageBase = {
   id: string
   role: 'user' | 'assistant'
   timestamp: number
+  updatedAt: number
   avatar: string
   name: string
   model_name: string
diff --git a/src/renderer/src/components/message/MessageBlockActivityGroup.vue b/src/renderer/src/components/message/MessageBlockActivityGroup.vue
new file mode 100644
index 000000000..854708d5e
--- /dev/null
+++ b/src/renderer/src/components/message/MessageBlockActivityGroup.vue
@@ -0,0 +1,114 @@
+<template>
+  <div class="flex flex-col w-full gap-1.5" data-testid="activity-group">
+    <button
+      type="button"
+      data-testid="activity-group-toggle"
+      class="inline-flex max-w-full min-w-0 items-center gap-[10px] self-start text-xs leading-4 text-[rgba(37,37,37,0.5)] dark:text-white/50 select-none rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+      :aria-expanded="isExpanded"
+      :aria-label="toggleLabel"
+      @click="toggleExpanded"
+    >
+      <Icon
+        :icon="isExpanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
+        class="w-[14px] h-[14px] shrink-0 text-[rgba(37,37,37,0.5)] dark:text-white/50"
+      />
+      <span class="min-w-0 truncate">
+        {{ titleText }}
+      </span>
+    </button>
+
+    <div v-show="isExpanded" class="flex flex-col w-full gap-1.5" data-testid="activity-group-body">
+      <template v-for="(block, index) in blocks" :key="buildActivityBlockKey(block, index)">
+        <MessageBlockThink
+          v-if="
+            (block.type === 'reasoning_content' || block.type === 'artifact-thinking') &&
+            block.content
+          "
+          :block="block"
+          :usage="usage"
+          @toggle-collapse="handleChildCollapseToggle"
+        />
+        <MessageBlockToolCall
+          v-else-if="block.type === 'tool_call'"
+          :block="block"
+          :message-id="messageId"
+          :thread-id="threadId"
+        />
+      </template>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { Icon } from '@iconify/vue'
+import { useI18n } from 'vue-i18n'
+import type {
+  DisplayAssistantMessageBlock,
+  DisplayMessageUsage
+} from '@/components/chat/messageListItems'
+import { formatActivityDuration } from './messageActivityGroups'
+import MessageBlockThink from './MessageBlockThink.vue'
+import MessageBlockToolCall from './MessageBlockToolCall.vue'
+
+const props = defineProps<{
+  blocks: DisplayAssistantMessageBlock[]
+  messageId: string
+  threadId: string
+  usage: DisplayMessageUsage
+  durationMs: number
+  reasoningCount: number
+  toolCallCount: number
+}>()
+
+const emit = defineEmits<{
+  'toggle-collapse': [isCollapsed: boolean]
+}>()
+
+const { t } = useI18n()
+const isExpanded = ref(false)
+
+const durationLabels = computed(() => ({
+  day: t('chat.activityCollapse.duration.day'),
+  hour: t('chat.activityCollapse.duration.hour'),
+  minute: t('chat.activityCollapse.duration.minute'),
+  second: t('chat.activityCollapse.duration.second')
+}))
+
+const durationText = computed(() => formatActivityDuration(props.durationMs, durationLabels.value))
+
+const countSegments = computed(() => {
+  const segments: string[] = []
+  if (props.reasoningCount > 0) {
+    segments.push(t('chat.activityCollapse.reasoningCount', { count: props.reasoningCount }))
+  }
+  if (props.toolCallCount > 0) {
+    segments.push(t('chat.activityCollapse.toolCallCount', { count: props.toolCallCount }))
+  }
+  return segments
+})
+
+const titleText = computed(() =>
+  [t('chat.activityCollapse.workedFor', { duration: durationText.value }), ...countSegments.value]
+    .filter(Boolean)
+    .join(' · ')
+)
+
+const toggleLabel = computed(() =>
+  isExpanded.value
+    ? t('chat.activityCollapse.collapseLabel', { title: titleText.value })
+    : t('chat.activityCollapse.expandLabel', { title: titleText.value })
+)
+
+const toggleExpanded = () => {
+  isExpanded.value = !isExpanded.value
+  emit('toggle-collapse', !isExpanded.value)
+}
+
+const handleChildCollapseToggle = (isCollapsed: boolean) => {
+  emit('toggle-collapse', isCollapsed)
+}
+
+const buildActivityBlockKey = (block: DisplayAssistantMessageBlock, index: number): string =>
+  block.id ?? block.tool_call?.id ?? `${block.type}:${block.timestamp}:${index}`
+</script>
diff --git a/src/renderer/src/components/message/MessageItemAssistant.vue b/src/renderer/src/components/message/MessageItemAssistant.vue
index 142687322..8a240850e 100644
--- a/src/renderer/src/components/message/MessageItemAssistant.vue
+++ b/src/renderer/src/components/message/MessageItemAssistant.vue
@@ -37,59 +37,76 @@
             class="size-3 text-muted-foreground"
           />
           <div v-else class="flex flex-col w-full gap-1.5" data-message-content="true">
-            <template v-for="(block, idx) in currentContent" :key="`${message.id}-${idx}`">
+            <template v-for="item in currentRenderItems" :key="item.key">
+              <MessageBlockActivityGroup
+                v-if="item.kind === 'activity-group'"
+                :blocks="item.blocks"
+                :message-id="currentMessage.id"
+                :thread-id="currentThreadId"
+                :usage="currentMessage.usage"
+                :duration-ms="item.durationMs"
+                :reasoning-count="item.reasoningCount"
+                :tool-call-count="item.toolCallCount"
+                @toggle-collapse="handleCollapseToggle"
+              />
               <MessageBlockContent
-                v-if="block.type === 'content'"
-                :block="block"
+                v-else-if="item.block.type === 'content'"
+                :block="item.block"
                 :message-id="currentMessage.id"
                 :thread-id="currentThreadId"
                 :is-search-result="isSearchResult"
               />
               <MessageBlockThink
-                v-else-if="block.type === 'reasoning_content' && block.content"
-                :block="block"
-                :usage="message.usage"
+                v-else-if="
+                  (item.block.type === 'reasoning_content' ||
+                    item.block.type === 'artifact-thinking') &&
+                  item.block.content
+                "
+                :block="item.block"
+                :usage="currentMessage.usage"
                 @toggle-collapse="handleCollapseToggle"
               />
-              <MessageBlockPlan v-else-if="block.type === 'plan'" :block="block" />
+              <MessageBlockPlan v-else-if="item.block.type === 'plan'" :block="item.block" />
               <MessageBlockToolCall
-                v-else-if="block.type === 'tool_call' && !isInternalToolCall(block)"
-                :block="block"
+                v-else-if="item.block.type === 'tool_call' && !isInternalToolCall(item.block)"
+                :block="item.block"
                 :message-id="currentMessage.id"
                 :thread-id="currentThreadId"
               />
               <MessageBlockQuestionRequest
-                v-else-if="block.type === 'action' && block.action_type === 'question_request'"
-                :block="block"
+                v-else-if="
+                  item.block.type === 'action' && item.block.action_type === 'question_request'
+                "
+                :block="item.block"
               />
               <MessageBlockAction
-                v-else-if="block.type === 'action'"
+                v-else-if="item.block.type === 'action'"
                 :message-id="currentMessage.id"
                 :conversation-id="currentThreadId"
-                :block="block"
+                :block="item.block"
                 :is-read-only="isReadOnly"
                 @continue="handleBlockContinue"
                 @switch-provider="handleBlockSwitchProvider"
               />
               <MessageBlockAudio
-                v-else-if="isAudioBlock(block)"
-                :block="block"
+                v-else-if="isAudioBlock(item.block)"
+                :block="item.block"
                 :message-id="currentMessage.id"
                 :thread-id="currentThreadId"
               />
               <MessageBlockVideo
-                v-else-if="isVideoBlock(block)"
-                :block="block"
+                v-else-if="isVideoBlock(item.block)"
+                :block="item.block"
                 :message-id="currentMessage.id"
                 :thread-id="currentThreadId"
               />
               <MessageBlockImage
-                v-else-if="block.type === 'image'"
-                :block="block"
+                v-else-if="item.block.type === 'image'"
+                :block="item.block"
                 :message-id="currentMessage.id"
                 :thread-id="currentThreadId"
               />
-              <MessageBlockError v-else-if="block.type === 'error'" :block="block" />
+              <MessageBlockError v-else-if="item.block.type === 'error'" :block="item.block" />
             </template>
           </div>
           <MessageToolbar
@@ -193,6 +210,8 @@ import MessageBlockImage from './MessageBlockImage.vue'
 import MessageBlockAudio from './MessageBlockAudio.vue'
 import MessageBlockVideo from './MessageBlockVideo.vue'
 import MessageBlockPlan from './MessageBlockPlan.vue'
+import MessageBlockActivityGroup from './MessageBlockActivityGroup.vue'
+import { buildAssistantRenderItems } from './messageActivityGroups'
 
 import {
   Dialog,
@@ -363,6 +382,21 @@ const currentContent = computed(() => {
   return (variant?.content || props.message.content) as DisplayAssistantMessageBlock[]
 })
 
+const shouldGroupActivity = computed(() => {
+  if (resolvedIsInGeneratingThread.value) return false
+  return currentMessage.value.status !== 'pending'
+})
+
+const currentRenderItems = computed(() =>
+  buildAssistantRenderItems({
+    blocks: currentContent.value,
+    messageId: currentMessage.value.id,
+    messageUpdatedAt: currentMessage.value.updatedAt,
+    shouldGroup: shouldGroupActivity.value,
+    isInternalToolCall
+  })
+)
+
 // 监听 allVariants 长度变化，用于新变体生成时的自动切换和持久化
 watch(
   () => allVariants.value.length,
diff --git a/src/renderer/src/components/message/messageActivityGroups.ts b/src/renderer/src/components/message/messageActivityGroups.ts
new file mode 100644
index 000000000..caf6e3395
--- /dev/null
+++ b/src/renderer/src/components/message/messageActivityGroups.ts
@@ -0,0 +1,184 @@
+import type { DisplayAssistantMessageBlock } from '@/components/chat/messageListItems'
+
+export type AssistantRenderItem =
+  | {
+      kind: 'block'
+      key: string
+      block: DisplayAssistantMessageBlock
+    }
+  | {
+      kind: 'activity-group'
+      key: string
+      blocks: DisplayAssistantMessageBlock[]
+      startedAt: number
+      endedAt: number
+      durationMs: number
+      reasoningCount: number
+      toolCallCount: number
+    }
+
+export type BuildAssistantRenderItemsOptions = {
+  blocks: DisplayAssistantMessageBlock[]
+  messageId: string
+  messageUpdatedAt: number
+  shouldGroup: boolean
+  isInternalToolCall?: (block: DisplayAssistantMessageBlock) => boolean
+}
+
+export type ActivityDurationLabels = {
+  day: string
+  hour: string
+  minute: string
+  second: string
+}
+
+type BufferedActivityBlock = {
+  block: DisplayAssistantMessageBlock
+  index: number
+}
+
+const ACTIVITY_BLOCK_TYPES = new Set<DisplayAssistantMessageBlock['type']>([
+  'reasoning_content',
+  'artifact-thinking',
+  'tool_call'
+])
+
+const isFiniteTimestamp = (value: number): boolean => Number.isFinite(value) && value >= 0
+
+const normalizeTimestamp = (value: number, fallback: number): number =>
+  isFiniteTimestamp(value) ? value : fallback
+
+const isReasoningActivityBlock = (block: DisplayAssistantMessageBlock): boolean =>
+  (block.type === 'reasoning_content' || block.type === 'artifact-thinking') &&
+  typeof block.content === 'string' &&
+  block.content.trim().length > 0
+
+export const isCompletedActivityBlock = (block: DisplayAssistantMessageBlock): boolean => {
+  if (!ACTIVITY_BLOCK_TYPES.has(block.type)) {
+    return false
+  }
+
+  if (block.status === 'loading' || block.status === 'pending') {
+    return false
+  }
+
+  if (block.type === 'tool_call') {
+    return true
+  }
+
+  return isReasoningActivityBlock(block)
+}
+
+const buildBlockKey = (
+  block: DisplayAssistantMessageBlock,
+  messageId: string,
+  index: number
+): string => {
+  const stableId = block.id ?? block.tool_call?.id
+  return stableId ? `${messageId}:${stableId}` : `${messageId}:${index}`
+}
+
+const buildGroupKey = (messageId: string, buffer: BufferedActivityBlock[]): string => {
+  const first = buffer[0]?.index ?? 0
+  const last = buffer[buffer.length - 1]?.index ?? first
+  return `activity:${messageId}:${first}:${last}`
+}
+
+const countReasoningBlocks = (blocks: DisplayAssistantMessageBlock[]): number =>
+  blocks.filter((block) => block.type === 'reasoning_content' || block.type === 'artifact-thinking')
+    .length
+
+const countToolCallBlocks = (blocks: DisplayAssistantMessageBlock[]): number =>
+  blocks.filter((block) => block.type === 'tool_call').length
+
+const buildActivityGroupItem = (
+  messageId: string,
+  messageUpdatedAt: number,
+  buffer: BufferedActivityBlock[]
+): AssistantRenderItem | null => {
+  const firstBlock = buffer[0]?.block
+  if (!firstBlock) {
+    return null
+  }
+
+  const startedAt = normalizeTimestamp(firstBlock.timestamp, messageUpdatedAt)
+  const endedAt = Math.max(startedAt, normalizeTimestamp(messageUpdatedAt, startedAt))
+  const blocks = buffer.map((item) => item.block)
+
+  return {
+    kind: 'activity-group',
+    key: buildGroupKey(messageId, buffer),
+    blocks,
+    startedAt,
+    endedAt,
+    durationMs: endedAt - startedAt,
+    reasoningCount: countReasoningBlocks(blocks),
+    toolCallCount: countToolCallBlocks(blocks)
+  }
+}
+
+export const buildAssistantRenderItems = ({
+  blocks,
+  messageId,
+  messageUpdatedAt,
+  shouldGroup,
+  isInternalToolCall
+}: BuildAssistantRenderItemsOptions): AssistantRenderItem[] => {
+  const items: AssistantRenderItem[] = []
+  let activityBuffer: BufferedActivityBlock[] = []
+
+  const flushActivityBuffer = () => {
+    if (activityBuffer.length === 0) {
+      return
+    }
+
+    const group = buildActivityGroupItem(messageId, messageUpdatedAt, activityBuffer)
+    if (group) {
+      items.push(group)
+    }
+    activityBuffer = []
+  }
+
+  blocks.forEach((block, index) => {
+    if (block.type === 'tool_call' && isInternalToolCall?.(block)) {
+      return
+    }
+
+    if (shouldGroup && isCompletedActivityBlock(block)) {
+      activityBuffer.push({ block, index })
+      return
+    }
+
+    flushActivityBuffer()
+    items.push({
+      kind: 'block',
+      key: buildBlockKey(block, messageId, index),
+      block
+    })
+  })
+
+  flushActivityBuffer()
+  return items
+}
+
+export const formatActivityDuration = (
+  durationMs: number,
+  labels: ActivityDurationLabels
+): string => {
+  const safeDurationMs = Number.isFinite(durationMs) ? Math.max(0, durationMs) : 0
+  let remainingSeconds = Math.floor(safeDurationMs / 1000)
+  const days = Math.floor(remainingSeconds / 86_400)
+  remainingSeconds %= 86_400
+  const hours = Math.floor(remainingSeconds / 3_600)
+  remainingSeconds %= 3_600
+  const minutes = Math.floor(remainingSeconds / 60)
+  const seconds = remainingSeconds % 60
+
+  const parts = [
+    days > 0 ? `${days}${labels.day}` : '',
+    hours > 0 ? `${hours}${labels.hour}` : '',
+    minutes > 0 ? `${minutes}${labels.minute}` : '',
+    seconds > 0 || (days === 0 && hours === 0 && minutes === 0) ? `${seconds}${labels.second}` : ''
+  ]
+  return parts.filter(Boolean).join('').trimEnd()
+}
diff --git a/src/renderer/src/i18n/da-DK/chat.json b/src/renderer/src/i18n/da-DK/chat.json
index 1ece7678d..9b01cb37b 100644
--- a/src/renderer/src/i18n/da-DK/chat.json
+++ b/src/renderer/src/i18n/da-DK/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Skill-kladden er kasseret.",
       "failed": "Kunne ikke håndtere skill-kladden: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Arbejdet i {duration}",
+    "reasoningCount": "{count} tanke(r)",
+    "toolCallCount": "{count} værktøjskald",
+    "expandLabel": "Udvid {title}",
+    "collapseLabel": "Skjul {title}",
+    "duration": {
+      "day": "d ",
+      "hour": "t ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/de-DE/chat.json b/src/renderer/src/i18n/de-DE/chat.json
index a584f9d26..a150b3bfe 100644
--- a/src/renderer/src/i18n/de-DE/chat.json
+++ b/src/renderer/src/i18n/de-DE/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Skill-Entwurf verworfen.",
       "failed": "Skill-Entwurf konnte nicht verarbeitet werden: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Gearbeitet für {duration}",
+    "reasoningCount": "{count} Gedanke(n)",
+    "toolCallCount": "{count} Werkzeugaufruf(e)",
+    "expandLabel": "Erweitern {title}",
+    "collapseLabel": "Einklappen {title}",
+    "duration": {
+      "day": "T ",
+      "hour": "Std. ",
+      "minute": "Min. ",
+      "second": "Sek."
+    }
   }
 }
diff --git a/src/renderer/src/i18n/en-US/chat.json b/src/renderer/src/i18n/en-US/chat.json
index e5ec4b9e1..c0076bb90 100644
--- a/src/renderer/src/i18n/en-US/chat.json
+++ b/src/renderer/src/i18n/en-US/chat.json
@@ -404,5 +404,18 @@
       "description": "Everything is ready. Type your first message here to finish the onboarding flow.",
       "caption": "The spotlight stays on the input box until you send your first message."
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Worked for {duration}",
+    "reasoningCount": "{count} thought(s)",
+    "toolCallCount": "{count} tool call(s)",
+    "expandLabel": "Expand {title}",
+    "collapseLabel": "Collapse {title}",
+    "duration": {
+      "day": "d ",
+      "hour": "h ",
+      "minute": "m ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/es-ES/chat.json b/src/renderer/src/i18n/es-ES/chat.json
index 10b836f25..ce5ea1d49 100644
--- a/src/renderer/src/i18n/es-ES/chat.json
+++ b/src/renderer/src/i18n/es-ES/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Borrador de skill descartado.",
       "failed": "No se pudo gestionar el borrador de skill: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Trabajó durante {duration}",
+    "reasoningCount": "{count} pensamiento(s)",
+    "toolCallCount": "{count} llamada(s) a herramienta",
+    "expandLabel": "Expandir {title}",
+    "collapseLabel": "Contraer {title}",
+    "duration": {
+      "day": "d ",
+      "hour": "h ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/fa-IR/chat.json b/src/renderer/src/i18n/fa-IR/chat.json
index 0d9ae4abb..00c7a9013 100644
--- a/src/renderer/src/i18n/fa-IR/chat.json
+++ b/src/renderer/src/i18n/fa-IR/chat.json
@@ -404,5 +404,18 @@
       "discarded": "پیش‌نویس مهارت دور انداخته شد.",
       "failed": "رسیدگی به پیش‌نویس مهارت ناموفق بود: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "به مدت {duration} کار کرده است",
+    "reasoningCount": "{count} مورد تفکر",
+    "toolCallCount": "{count} فراخوانی ابزار",
+    "expandLabel": "گسترش {title}",
+    "collapseLabel": "جمع کردن {title}",
+    "duration": {
+      "day": " روز ",
+      "hour": " ساعت ",
+      "minute": " دقیقه ",
+      "second": " ثانیه"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/fr-FR/chat.json b/src/renderer/src/i18n/fr-FR/chat.json
index 5cd7d1901..8094896ec 100644
--- a/src/renderer/src/i18n/fr-FR/chat.json
+++ b/src/renderer/src/i18n/fr-FR/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Brouillon de compétence ignoré.",
       "failed": "Impossible de traiter le brouillon de compétence : {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "A travaillé pendant {duration}",
+    "reasoningCount": "{count} réflexion(s)",
+    "toolCallCount": "{count} appel(s) d'outil",
+    "expandLabel": "Développer {title}",
+    "collapseLabel": "Réduire {title}",
+    "duration": {
+      "day": "j ",
+      "hour": "h ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/he-IL/chat.json b/src/renderer/src/i18n/he-IL/chat.json
index 9efdeb00c..9942b68a9 100644
--- a/src/renderer/src/i18n/he-IL/chat.json
+++ b/src/renderer/src/i18n/he-IL/chat.json
@@ -404,5 +404,18 @@
       "discarded": "טיוטת המיומנות נמחקה.",
       "failed": "הטיפול בטיוטת המיומנות נכשל: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "עבד במשך {duration}",
+    "reasoningCount": "{count} מחשבות",
+    "toolCallCount": "{count} קריאות כלי",
+    "expandLabel": "הרחב את {title}",
+    "collapseLabel": "כווץ את {title}",
+    "duration": {
+      "day": " יום ",
+      "hour": " שעה ",
+      "minute": " דק׳ ",
+      "second": " שנ׳"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/id-ID/chat.json b/src/renderer/src/i18n/id-ID/chat.json
index 19c0047bd..f39000e09 100644
--- a/src/renderer/src/i18n/id-ID/chat.json
+++ b/src/renderer/src/i18n/id-ID/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Draf skill dibuang.",
       "failed": "Gagal menangani draf skill: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Bekerja selama {duration}",
+    "reasoningCount": "{count} pemikiran",
+    "toolCallCount": "{count} panggilan alat",
+    "expandLabel": "Perluas {title}",
+    "collapseLabel": "Ciutkan {title}",
+    "duration": {
+      "day": "h ",
+      "hour": "j ",
+      "minute": "m ",
+      "second": "d"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/it-IT/chat.json b/src/renderer/src/i18n/it-IT/chat.json
index abbc75b6f..ea645ed93 100644
--- a/src/renderer/src/i18n/it-IT/chat.json
+++ b/src/renderer/src/i18n/it-IT/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Bozza di skill scartata.",
       "failed": "Impossibile gestire la bozza di skill: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Ha lavorato per {duration}",
+    "reasoningCount": "{count} ragionamento/i",
+    "toolCallCount": "{count} chiamata/e strumento",
+    "expandLabel": "Espandi {title}",
+    "collapseLabel": "Comprimi {title}",
+    "duration": {
+      "day": "g ",
+      "hour": "h ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/ja-JP/chat.json b/src/renderer/src/i18n/ja-JP/chat.json
index 794321898..383f54d84 100644
--- a/src/renderer/src/i18n/ja-JP/chat.json
+++ b/src/renderer/src/i18n/ja-JP/chat.json
@@ -404,5 +404,18 @@
       "discarded": "スキルドラフトを破棄しました。",
       "failed": "スキルドラフトの処理に失敗しました: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "{duration} 作業しました",
+    "reasoningCount": "{count} 件の思考",
+    "toolCallCount": "{count} 件のツール呼び出し",
+    "expandLabel": "{title} を展開",
+    "collapseLabel": "{title} を折りたたむ",
+    "duration": {
+      "day": "日",
+      "hour": "時間",
+      "minute": "分",
+      "second": "秒"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/ko-KR/chat.json b/src/renderer/src/i18n/ko-KR/chat.json
index 87de40f30..6b834d0d2 100644
--- a/src/renderer/src/i18n/ko-KR/chat.json
+++ b/src/renderer/src/i18n/ko-KR/chat.json
@@ -404,5 +404,18 @@
       "discarded": "스킬 초안을 버렸습니다.",
       "failed": "스킬 초안 처리에 실패했습니다: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "{duration} 동안 작업함",
+    "reasoningCount": "{count}개 사고",
+    "toolCallCount": "{count}개 도구 호출",
+    "expandLabel": "{title} 펼치기",
+    "collapseLabel": "{title} 접기",
+    "duration": {
+      "day": "일",
+      "hour": "시간",
+      "minute": "분",
+      "second": "초"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/ms-MY/chat.json b/src/renderer/src/i18n/ms-MY/chat.json
index b5060753b..e90fb2790 100644
--- a/src/renderer/src/i18n/ms-MY/chat.json
+++ b/src/renderer/src/i18n/ms-MY/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Draf skill telah dibuang.",
       "failed": "Gagal mengendalikan draf skill: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Bekerja selama {duration}",
+    "reasoningCount": "{count} pemikiran",
+    "toolCallCount": "{count} panggilan alat",
+    "expandLabel": "Kembangkan {title}",
+    "collapseLabel": "Runtuhkan {title}",
+    "duration": {
+      "day": "h ",
+      "hour": "j ",
+      "minute": "m ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/pl-PL/chat.json b/src/renderer/src/i18n/pl-PL/chat.json
index 7b5ce3d39..0a4173786 100644
--- a/src/renderer/src/i18n/pl-PL/chat.json
+++ b/src/renderer/src/i18n/pl-PL/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Odrzucono szkic umiejętności.",
       "failed": "Nie udało się obsłużyć szkicu umiejętności: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Pracowano przez {duration}",
+    "reasoningCount": "{count} rozumowanie(a)",
+    "toolCallCount": "{count} wywołanie(a) narzędzia",
+    "expandLabel": "Rozwiń {title}",
+    "collapseLabel": "Zwiń {title}",
+    "duration": {
+      "day": "d ",
+      "hour": "godz. ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/pt-BR/chat.json b/src/renderer/src/i18n/pt-BR/chat.json
index f0ca7ed34..9f84b518d 100644
--- a/src/renderer/src/i18n/pt-BR/chat.json
+++ b/src/renderer/src/i18n/pt-BR/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Rascunho de skill descartado.",
       "failed": "Falha ao lidar com o rascunho de skill: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Trabalhou por {duration}",
+    "reasoningCount": "{count} raciocínio(s)",
+    "toolCallCount": "{count} chamada(s) de ferramenta",
+    "expandLabel": "Expandir {title}",
+    "collapseLabel": "Recolher {title}",
+    "duration": {
+      "day": "d ",
+      "hour": "h ",
+      "minute": "min ",
+      "second": "s"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/ru-RU/chat.json b/src/renderer/src/i18n/ru-RU/chat.json
index 5fc83ae40..30a6f8f38 100644
--- a/src/renderer/src/i18n/ru-RU/chat.json
+++ b/src/renderer/src/i18n/ru-RU/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Черновик навыка отброшен.",
       "failed": "Не удалось обработать черновик навыка: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Работал(а) {duration}",
+    "reasoningCount": "{count} рассуждение(й)",
+    "toolCallCount": "{count} вызов(ов) инструмента",
+    "expandLabel": "Развернуть {title}",
+    "collapseLabel": "Свернуть {title}",
+    "duration": {
+      "day": "д ",
+      "hour": "ч ",
+      "minute": "мин ",
+      "second": "с"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/tr-TR/chat.json b/src/renderer/src/i18n/tr-TR/chat.json
index ae7847fba..7042b060d 100644
--- a/src/renderer/src/i18n/tr-TR/chat.json
+++ b/src/renderer/src/i18n/tr-TR/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Skill taslağından vazgeçildi.",
       "failed": "Skill taslağı işlenemedi: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "{duration} boyunca çalıştı",
+    "reasoningCount": "{count} düşünce",
+    "toolCallCount": "{count} araç çağrısı",
+    "expandLabel": "{title} öğesini genişlet",
+    "collapseLabel": "{title} öğesini daralt",
+    "duration": {
+      "day": "g ",
+      "hour": "sa ",
+      "minute": "dk ",
+      "second": "sn"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/vi-VN/chat.json b/src/renderer/src/i18n/vi-VN/chat.json
index c614876e1..ed3c23e41 100644
--- a/src/renderer/src/i18n/vi-VN/chat.json
+++ b/src/renderer/src/i18n/vi-VN/chat.json
@@ -404,5 +404,18 @@
       "discarded": "Đã loại bỏ bản nháp kỹ năng.",
       "failed": "Không thể xử lý bản nháp kỹ năng: {error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "Hoạt động trong {duration}",
+    "reasoningCount": "{count} suy nghĩ",
+    "toolCallCount": "{count} lần gọi công cụ",
+    "expandLabel": "Mở rộng {title}",
+    "collapseLabel": "Thu gọn {title}",
+    "duration": {
+      "day": "ng ",
+      "hour": "g ",
+      "minute": "p ",
+      "second": "gi"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/zh-CN/chat.json b/src/renderer/src/i18n/zh-CN/chat.json
index b085240c5..e81ce2892 100644
--- a/src/renderer/src/i18n/zh-CN/chat.json
+++ b/src/renderer/src/i18n/zh-CN/chat.json
@@ -404,5 +404,18 @@
       "description": "现在已经准备好了，在这里发送第一条消息即可完成引导。",
       "caption": "聚光会一直停留在输入框，直到你真正发出第一条消息。"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "已经工作了 {duration}",
+    "reasoningCount": "{count} 段思考",
+    "toolCallCount": "{count} 次工具调用",
+    "expandLabel": "展开 {title}",
+    "collapseLabel": "收起 {title}",
+    "duration": {
+      "day": "天",
+      "hour": "小时",
+      "minute": "分钟",
+      "second": "秒"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/zh-HK/chat.json b/src/renderer/src/i18n/zh-HK/chat.json
index d12e37dd7..992f4f460 100644
--- a/src/renderer/src/i18n/zh-HK/chat.json
+++ b/src/renderer/src/i18n/zh-HK/chat.json
@@ -404,5 +404,18 @@
       "discarded": "已丟棄技能草稿。",
       "failed": "處理技能草稿失敗：{error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "已經工作了 {duration}",
+    "reasoningCount": "{count} 段思考",
+    "toolCallCount": "{count} 次工具呼叫",
+    "expandLabel": "展開 {title}",
+    "collapseLabel": "收起 {title}",
+    "duration": {
+      "day": "天",
+      "hour": "小時",
+      "minute": "分鐘",
+      "second": "秒"
+    }
   }
 }
diff --git a/src/renderer/src/i18n/zh-TW/chat.json b/src/renderer/src/i18n/zh-TW/chat.json
index 57f489f6b..d1e4cb56a 100644
--- a/src/renderer/src/i18n/zh-TW/chat.json
+++ b/src/renderer/src/i18n/zh-TW/chat.json
@@ -404,5 +404,18 @@
       "discarded": "已捨棄技能草稿。",
       "failed": "處理技能草稿失敗：{error}"
     }
+  },
+  "activityCollapse": {
+    "workedFor": "已經工作了 {duration}",
+    "reasoningCount": "{count} 段思考",
+    "toolCallCount": "{count} 次工具呼叫",
+    "expandLabel": "展開 {title}",
+    "collapseLabel": "收合 {title}",
+    "duration": {
+      "day": "天",
+      "hour": "小時",
+      "minute": "分鐘",
+      "second": "秒"
+    }
   }
 }
diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index f3b5f99d2..d5cd0a40f 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -556,6 +556,7 @@ function toDisplayMessage(record: ChatMessageRecord): DisplayMessage {
   const baseMessage = {
     id: record.id,
     timestamp: record.createdAt,
+    updatedAt: record.updatedAt,
     avatar: '',
     name: record.role === 'user' ? 'You' : 'Assistant',
     model_name: modelName,
@@ -604,11 +605,13 @@ function toStreamingMessage(
   messageId?: string | null
 ): DisplayMessage {
   const modelId = sessionStore.activeSession?.modelId ?? ''
+  const now = Date.now()
   return {
     id: messageId ? `__streaming__:${messageId}` : '__streaming__',
     content: blocks as DisplayAssistantMessageBlock[],
     role: 'assistant',
-    timestamp: Date.now(),
+    timestamp: now,
+    updatedAt: now,
     avatar: '',
     name: 'Assistant',
     model_name: resolveAssistantModelName(modelId),
diff --git a/test/renderer/components/MessageList.test.ts b/test/renderer/components/MessageList.test.ts
index 5d9622579..8c1b84e30 100644
--- a/test/renderer/components/MessageList.test.ts
+++ b/test/renderer/components/MessageList.test.ts
@@ -89,6 +89,7 @@ function createMessage(id: string, role: 'user' | 'assistant', orderSeq: number)
           }
         : [],
     timestamp: orderSeq,
+    updatedAt: orderSeq,
     avatar: '',
     name: role === 'user' ? 'You' : 'Assistant',
     model_name: '',
diff --git a/test/renderer/components/message/MessageBlockActivityGroup.test.ts b/test/renderer/components/message/MessageBlockActivityGroup.test.ts
new file mode 100644
index 000000000..51b710c5e
--- /dev/null
+++ b/test/renderer/components/message/MessageBlockActivityGroup.test.ts
@@ -0,0 +1,162 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import MessageBlockActivityGroup from '@/components/message/MessageBlockActivityGroup.vue'
+import type {
+  DisplayAssistantMessageBlock,
+  DisplayMessageUsage
+} from '@/components/chat/messageListItems'
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({
+    t: (key: string, params?: Record<string, unknown>) => {
+      if (key === 'chat.activityCollapse.workedFor') {
+        return `Worked for ${params?.duration}`
+      }
+      if (key === 'chat.activityCollapse.reasoningCount') {
+        return `${params?.count} thought(s)`
+      }
+      if (key === 'chat.activityCollapse.toolCallCount') {
+        return `${params?.count} tool call(s)`
+      }
+      if (key === 'chat.activityCollapse.expandLabel') {
+        return `Expand ${params?.title}`
+      }
+      if (key === 'chat.activityCollapse.collapseLabel') {
+        return `Collapse ${params?.title}`
+      }
+      if (key === 'chat.activityCollapse.duration.day') {
+        return 'd '
+      }
+      if (key === 'chat.activityCollapse.duration.hour') {
+        return 'h '
+      }
+      if (key === 'chat.activityCollapse.duration.minute') {
+        return 'm '
+      }
+      if (key === 'chat.activityCollapse.duration.second') {
+        return 's'
+      }
+      return key
+    }
+  })
+}))
+
+const usage: DisplayMessageUsage = {
+  context_usage: 0,
+  tokens_per_second: 0,
+  total_tokens: 0,
+  generation_time: 0,
+  first_token_time: 0,
+  reasoning_start_time: 0,
+  reasoning_end_time: 0,
+  input_tokens: 0,
+  output_tokens: 0
+}
+
+const blocks: DisplayAssistantMessageBlock[] = [
+  {
+    type: 'reasoning_content',
+    content: 'thinking',
+    status: 'success',
+    timestamp: 1_000
+  },
+  {
+    type: 'tool_call',
+    status: 'success',
+    timestamp: 2_000,
+    tool_call: {
+      id: 'tc1',
+      name: 'shell_command'
+    }
+  }
+]
+
+const mountGroup = () =>
+  mount(MessageBlockActivityGroup, {
+    props: {
+      blocks,
+      messageId: 'm1',
+      threadId: 's1',
+      usage,
+      durationMs: 65_000,
+      reasoningCount: 1,
+      toolCallCount: 1
+    },
+    global: {
+      stubs: {
+        Icon: defineComponent({
+          name: 'Icon',
+          template: '<span data-testid="icon" />'
+        }),
+        MessageBlockThink: defineComponent({
+          name: 'MessageBlockThink',
+          props: {
+            block: {
+              type: Object,
+              required: true
+            }
+          },
+          template: '<div data-testid="think-block">{{ block.content }}</div>'
+        }),
+        MessageBlockToolCall: defineComponent({
+          name: 'MessageBlockToolCall',
+          props: {
+            block: {
+              type: Object,
+              required: true
+            }
+          },
+          template: '<div data-testid="tool-block">{{ block.tool_call?.name }}</div>'
+        })
+      }
+    }
+  })
+
+describe('MessageBlockActivityGroup', () => {
+  it('starts collapsed with duration and activity counts in the title', () => {
+    const wrapper = mountGroup()
+
+    expect(wrapper.get('[data-testid="activity-group-toggle"]').text()).toContain(
+      'Worked for 1m 5s · 1 thought(s) · 1 tool call(s)'
+    )
+    expect(wrapper.get('[data-testid="activity-group-toggle"]').attributes('aria-expanded')).toBe(
+      'false'
+    )
+    expect(wrapper.get('[data-testid="activity-group-body"]').isVisible()).toBe(false)
+  })
+
+  it('toggles expanded state and shows the original activity blocks', async () => {
+    const wrapper = mountGroup()
+
+    await wrapper.get('[data-testid="activity-group-toggle"]').trigger('click')
+
+    expect(wrapper.get('[data-testid="activity-group-toggle"]').attributes('aria-expanded')).toBe(
+      'true'
+    )
+    expect(wrapper.get('[data-testid="activity-group-body"]').isVisible()).toBe(true)
+    expect(wrapper.find('[data-testid="think-block"]').text()).toBe('thinking')
+    expect(wrapper.find('[data-testid="tool-block"]').text()).toBe('shell_command')
+
+    await wrapper.get('[data-testid="activity-group-toggle"]').trigger('click')
+
+    expect(wrapper.get('[data-testid="activity-group-toggle"]').attributes('aria-expanded')).toBe(
+      'false'
+    )
+  })
+
+  it('does not persist expanded state across remounts', async () => {
+    const wrapper = mountGroup()
+    await wrapper.get('[data-testid="activity-group-toggle"]').trigger('click')
+    expect(wrapper.get('[data-testid="activity-group-toggle"]').attributes('aria-expanded')).toBe(
+      'true'
+    )
+
+    wrapper.unmount()
+    const remounted = mountGroup()
+
+    expect(remounted.get('[data-testid="activity-group-toggle"]').attributes('aria-expanded')).toBe(
+      'false'
+    )
+  })
+})
diff --git a/test/renderer/components/message/MessageItemAssistant.test.ts b/test/renderer/components/message/MessageItemAssistant.test.ts
index 205230d23..394a1e610 100644
--- a/test/renderer/components/message/MessageItemAssistant.test.ts
+++ b/test/renderer/components/message/MessageItemAssistant.test.ts
@@ -100,6 +100,7 @@ const createMessage = (
   id: 'm1',
   role: 'assistant',
   timestamp: 1,
+  updatedAt: 1,
   avatar: '',
   name: 'Assistant',
   model_name: 'GPT-4',
@@ -137,6 +138,29 @@ const createVideoLikeImageBlock = (
   ...overrides
 })
 
+const createThinkingBlock = (
+  overrides: Partial<DisplayAssistantMessageBlock> = {}
+): DisplayAssistantMessageBlock => ({
+  type: 'reasoning_content',
+  content: 'thinking',
+  status: 'success',
+  timestamp: 1,
+  ...overrides
+})
+
+const createToolCallBlock = (
+  overrides: Partial<DisplayAssistantMessageBlock> = {}
+): DisplayAssistantMessageBlock => ({
+  type: 'tool_call',
+  status: 'success',
+  timestamp: 2,
+  tool_call: {
+    id: 'tc1',
+    name: 'read_file'
+  },
+  ...overrides
+})
+
 describe('MessageItemAssistant', () => {
   const global = {
     stubs: {
@@ -161,7 +185,18 @@ describe('MessageItemAssistant', () => {
         template: '<div data-testid="video-block" />'
       }),
       MessageBlockAudio: componentStub('MessageBlockAudio'),
-      MessageBlockPlan: componentStub('MessageBlockPlan')
+      MessageBlockPlan: componentStub('MessageBlockPlan'),
+      MessageBlockActivityGroup: defineComponent({
+        name: 'MessageBlockActivityGroup',
+        props: {
+          blocks: {
+            type: Array,
+            required: true
+          }
+        },
+        template:
+          '<div data-testid="activity-group" :data-block-count="String(blocks.length)">activity</div>'
+      })
     }
   }
 
@@ -224,4 +259,91 @@ describe('MessageItemAssistant', () => {
 
     expect(wrapper.find('[data-testid="video-block"]').exists()).toBe(false)
   })
+
+  it('groups completed assistant activity blocks after the turn is settled', () => {
+    const wrapper = mount(MessageItemAssistant, {
+      props: {
+        message: createMessage('sent', [createThinkingBlock(), createToolCallBlock()]),
+        isCapturingImage: false,
+        isInGeneratingThread: false
+      },
+      global
+    })
+
+    expect(wrapper.find('[data-testid="activity-group"]').exists()).toBe(true)
+    expect(wrapper.find('[data-testid="activity-group"]').attributes('data-block-count')).toBe('2')
+    expect(wrapper.findComponent({ name: 'MessageBlockThink' }).exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'MessageBlockToolCall' }).exists()).toBe(false)
+  })
+
+  it('does not group activity while the assistant message is pending', () => {
+    const wrapper = mount(MessageItemAssistant, {
+      props: {
+        message: createMessage('pending', [createThinkingBlock(), createToolCallBlock()]),
+        isCapturingImage: false,
+        isInGeneratingThread: true
+      },
+      global
+    })
+
+    expect(wrapper.find('[data-testid="activity-group"]').exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'MessageBlockThink' }).exists()).toBe(true)
+    expect(wrapper.findComponent({ name: 'MessageBlockToolCall' }).exists()).toBe(true)
+  })
+
+  it('does not group sent activity while the thread is still generating', () => {
+    const wrapper = mount(MessageItemAssistant, {
+      props: {
+        message: createMessage('sent', [createThinkingBlock(), createToolCallBlock()]),
+        isCapturingImage: false,
+        isInGeneratingThread: true
+      },
+      global
+    })
+
+    expect(wrapper.find('[data-testid="activity-group"]').exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'MessageBlockThink' }).exists()).toBe(true)
+    expect(wrapper.findComponent({ name: 'MessageBlockToolCall' }).exists()).toBe(true)
+  })
+
+  it('does not group pending activity when the thread is idle', () => {
+    const wrapper = mount(MessageItemAssistant, {
+      props: {
+        message: createMessage('pending', [createThinkingBlock(), createToolCallBlock()]),
+        isCapturingImage: false,
+        isInGeneratingThread: false
+      },
+      global
+    })
+
+    expect(wrapper.find('[data-testid="activity-group"]').exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'MessageBlockThink' }).exists()).toBe(true)
+    expect(wrapper.findComponent({ name: 'MessageBlockToolCall' }).exists()).toBe(true)
+  })
+
+  it('excludes internal tool calls from activity groups', () => {
+    const wrapper = mount(MessageItemAssistant, {
+      props: {
+        message: createMessage('sent', [
+          createThinkingBlock(),
+          createToolCallBlock({
+            extra: {
+              internalTool: true
+            },
+            tool_call: {
+              id: 'tc-plan',
+              name: 'update_plan'
+            }
+          })
+        ]),
+        isCapturingImage: false,
+        isInGeneratingThread: false
+      },
+      global
+    })
+
+    expect(wrapper.find('[data-testid="activity-group"]').exists()).toBe(true)
+    expect(wrapper.find('[data-testid="activity-group"]').attributes('data-block-count')).toBe('1')
+    expect(wrapper.findComponent({ name: 'MessageBlockToolCall' }).exists()).toBe(false)
+  })
 })
diff --git a/test/renderer/components/message/messageActivityGroups.test.ts b/test/renderer/components/message/messageActivityGroups.test.ts
new file mode 100644
index 000000000..b898e1b86
--- /dev/null
+++ b/test/renderer/components/message/messageActivityGroups.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import type { DisplayAssistantMessageBlock } from '@/components/chat/messageListItems'
+import {
+  type ActivityDurationLabels,
+  buildAssistantRenderItems,
+  formatActivityDuration
+} from '@/components/message/messageActivityGroups'
+
+const createBlock = (
+  type: DisplayAssistantMessageBlock['type'],
+  overrides: Partial<DisplayAssistantMessageBlock> = {}
+): DisplayAssistantMessageBlock => ({
+  type,
+  status: 'success',
+  timestamp: 1_000,
+  ...overrides
+})
+
+const zhDurationLabels: ActivityDurationLabels = {
+  day: '天',
+  hour: '小时',
+  minute: '分钟',
+  second: '秒'
+}
+
+const enDurationLabels: ActivityDurationLabels = {
+  day: 'd ',
+  hour: 'h ',
+  minute: 'm ',
+  second: 's'
+}
+
+describe('messageActivityGroups', () => {
+  it('groups consecutive completed reasoning and tool-call blocks', () => {
+    const items = buildAssistantRenderItems({
+      messageId: 'm1',
+      messageUpdatedAt: 70_000,
+      shouldGroup: true,
+      blocks: [
+        createBlock('reasoning_content', { content: 'thinking', timestamp: 10_000 }),
+        createBlock('tool_call', {
+          timestamp: 20_000,
+          tool_call: {
+            id: 'tc1',
+            name: 'read_file'
+          }
+        })
+      ]
+    })
+
+    expect(items).toHaveLength(1)
+    expect(items[0]).toMatchObject({
+      kind: 'activity-group',
+      startedAt: 10_000,
+      endedAt: 70_000,
+      durationMs: 60_000,
+      reasoningCount: 1,
+      toolCallCount: 1
+    })
+  })
+
+  it('splits activity groups around visible content blocks', () => {
+    const items = buildAssistantRenderItems({
+      messageId: 'm1',
+      messageUpdatedAt: 12_000,
+      shouldGroup: true,
+      blocks: [
+        createBlock('reasoning_content', { content: 'first' }),
+        createBlock('content', { content: 'answer' }),
+        createBlock('tool_call', {
+          tool_call: {
+            id: 'tc1',
+            name: 'shell'
+          }
+        })
+      ]
+    })
+
+    expect(items.map((item) => item.kind)).toEqual(['activity-group', 'block', 'activity-group'])
+  })
+
+  it('does not group when the turn is not settled', () => {
+    const items = buildAssistantRenderItems({
+      messageId: 'm1',
+      messageUpdatedAt: 12_000,
+      shouldGroup: false,
+      blocks: [
+        createBlock('reasoning_content', { content: 'thinking' }),
+        createBlock('tool_call', {
+          tool_call: {
+            id: 'tc1',
+            name: 'shell'
+          }
+        })
+      ]
+    })
+
+    expect(items.map((item) => item.kind)).toEqual(['block', 'block'])
+  })
+
+  it('does not group pending or loading activity blocks', () => {
+    const items = buildAssistantRenderItems({
+      messageId: 'm1',
+      messageUpdatedAt: 12_000,
+      shouldGroup: true,
+      blocks: [
+        createBlock('reasoning_content', { content: 'thinking', status: 'loading' }),
+        createBlock('tool_call', {
+          status: 'pending',
+          tool_call: {
+            id: 'tc1',
+            name: 'shell'
+          }
+        })
+      ]
+    })
+
+    expect(items.map((item) => item.kind)).toEqual(['block', 'block'])
+  })
+
+  it('skips internal hidden tool calls', () => {
+    const items = buildAssistantRenderItems({
+      messageId: 'm1',
+      messageUpdatedAt: 12_000,
+      shouldGroup: true,
+      isInternalToolCall: (block) =>
+        block.tool_call?.name === 'update_plan' && block.extra?.internalTool === true,
+      blocks: [
+        createBlock('tool_call', {
+          extra: {
+            internalTool: true
+          },
+          tool_call: {
+            id: 'tc1',
+            name: 'update_plan'
+          }
+        }),
+        createBlock('content', { content: 'visible' })
+      ]
+    })
+
+    expect(items).toHaveLength(1)
+    expect(items[0]).toMatchObject({
+      kind: 'block',
+      block: {
+        type: 'content'
+      }
+    })
+  })
+
+  it('formats duration up to days, hours, minutes, and seconds', () => {
+    expect(formatActivityDuration(8_900, zhDurationLabels)).toBe('8秒')
+    expect(formatActivityDuration(192_000, zhDurationLabels)).toBe('3分钟12秒')
+    expect(formatActivityDuration(7_449_000, zhDurationLabels)).toBe('2小时4分钟9秒')
+    expect(formatActivityDuration(97_802_000, zhDurationLabels)).toBe('1天3小时10分钟2秒')
+
+    expect(formatActivityDuration(192_000, enDurationLabels)).toBe('3m 12s')
+  })
+})

From c91a002e3f435ca0796fbc762727333c426b12eb Mon Sep 17 00:00:00 2001
From: yyhhyyyyyy <yyhhyyyyyy8@gmail.com>
Date: Tue, 2 Jun 2026 18:09:18 +0800
Subject: [PATCH 6/8] fix(renderer): honor provider-db budget sentinels (#1726)

* fix(renderer): honor provider-db budget sentinels

* fix(renderer): make budget sentinel bounds effective

* fix(renderer): preserve empty budget range state
---
 src/renderer/src/components/ChatConfig.vue    |   3 +-
 .../src/composables/useChatConfigFields.ts    |  32 ++-
 .../src/composables/useModelCapabilities.ts   |  72 ++++---
 .../src/composables/useModelTypeDetection.ts  |   8 -
 .../src/composables/useThinkingBudget.ts      |  19 +-
 .../composables/useChatConfigFields.test.ts   |  40 +++-
 .../composables/useModelCapabilities.test.ts  | 194 +++++++++++-------
 .../composables/useModelTypeDetection.test.ts |   1 -
 .../composables/useThinkingBudget.test.ts     |  43 ++--
 9 files changed, 272 insertions(+), 140 deletions(-)

diff --git a/src/renderer/src/components/ChatConfig.vue b/src/renderer/src/components/ChatConfig.vue
index 205dbfb09..f67a12afa 100644
--- a/src/renderer/src/components/ChatConfig.vue
+++ b/src/renderer/src/components/ChatConfig.vue
@@ -78,8 +78,7 @@ const thinkingBudget = useThinkingBudget({
   thinkingBudget: toRef(props, 'thinkingBudget'),
   budgetRange: capabilities.budgetRange,
   modelReasoning: modelTypeDetection.modelReasoning,
-  supportsReasoning: capabilities.supportsReasoning,
-  isGeminiProvider: modelTypeDetection.isGeminiProvider
+  supportsReasoning: capabilities.supportsReasoning
 })
 
 // === Utility Functions ===
diff --git a/src/renderer/src/composables/useChatConfigFields.ts b/src/renderer/src/composables/useChatConfigFields.ts
index f6c6f8d5f..8af8dca3c 100644
--- a/src/renderer/src/composables/useChatConfigFields.ts
+++ b/src/renderer/src/composables/useChatConfigFields.ts
@@ -10,6 +10,7 @@ import type {
   SelectOption,
   FieldConfig
 } from '@/components/ChatConfig/types'
+import type { ThinkingBudgetRange } from '@/composables/useThinkingBudget'
 import {
   DEFAULT_REASONING_EFFORT_OPTIONS as FALLBACK_REASONING_EFFORT_OPTIONS,
   isReasoningEffort,
@@ -17,6 +18,29 @@ import {
   type Verbosity
 } from '@shared/types/model-db'
 
+const getThinkingBudgetInputBounds = (
+  budgetRange: ThinkingBudgetRange | null
+): { min?: number; max?: number } => {
+  const bounds: { min?: number; max?: number } = {
+    min: budgetRange?.min,
+    max: budgetRange?.max
+  }
+  const sentinels = [budgetRange?.auto, budgetRange?.off].filter(
+    (value): value is number => typeof value === 'number'
+  )
+
+  for (const sentinel of sentinels) {
+    if (typeof bounds.min === 'number' && sentinel < bounds.min) {
+      bounds.min = sentinel
+    }
+    if (typeof bounds.max === 'number' && sentinel > bounds.max) {
+      bounds.max = sentinel
+    }
+  }
+
+  return bounds
+}
+
 // === Interfaces ===
 export interface UseChatConfigFieldsOptions {
   // Props
@@ -34,7 +58,7 @@ export interface UseChatConfigFieldsOptions {
   supportsTemperatureControl: Ref<boolean | null>
   showThinkingBudget: ComputedRef<boolean>
   thinkingBudgetError: ComputedRef<string>
-  budgetRange: Ref<{ min?: number; max?: number; default?: number } | null>
+  budgetRange: Ref<ThinkingBudgetRange | null>
 
   // Utils
   formatSize: (size: number) => string
@@ -119,6 +143,8 @@ export function useChatConfigFields(options: UseChatConfigFieldsOptions) {
 
     // Thinking Budget
     if (options.showThinkingBudget.value) {
+      const thinkingBudgetInputBounds = getThinkingBudgetInputBounds(options.budgetRange.value)
+
       fields.push({
         key: 'thinkingBudget',
         type: 'input',
@@ -126,8 +152,8 @@ export function useChatConfigFields(options: UseChatConfigFieldsOptions) {
         label: t('settings.model.modelConfig.thinkingBudget.label'),
         description: t('settings.model.modelConfig.thinkingBudget.description'),
         inputType: 'number',
-        min: options.budgetRange.value?.min,
-        max: options.budgetRange.value?.max,
+        min: thinkingBudgetInputBounds.min,
+        max: thinkingBudgetInputBounds.max,
         step: 128,
         placeholder: t('settings.model.modelConfig.thinkingBudget.placeholder'),
         getValue: () => options.thinkingBudget.value,
diff --git a/src/renderer/src/composables/useModelCapabilities.ts b/src/renderer/src/composables/useModelCapabilities.ts
index a298d470c..648d6e746 100644
--- a/src/renderer/src/composables/useModelCapabilities.ts
+++ b/src/renderer/src/composables/useModelCapabilities.ts
@@ -2,15 +2,43 @@
 import { ref, watch, type Ref } from 'vue'
 
 import { createModelClient } from '@api/ModelClient'
+import type { ReasoningPortrait } from '@shared/types/model-db'
+import type { ThinkingBudgetRange } from './useThinkingBudget'
+
+const normalizeBudgetRange = (
+  budget: ReasoningPortrait['budget'] | ThinkingBudgetRange | null | undefined
+): ThinkingBudgetRange | null => {
+  if (!budget) return null
+
+  const range: ThinkingBudgetRange = {}
+  if (typeof budget.min === 'number') range.min = budget.min
+  if (typeof budget.max === 'number') range.max = budget.max
+  if (typeof budget.default === 'number') range.default = budget.default
+  if (typeof budget.auto === 'number') range.auto = budget.auto
+  if (typeof budget.off === 'number') range.off = budget.off
+  if (typeof budget.unit === 'string') range.unit = budget.unit
+
+  return Object.keys(range).length > 0 ? range : null
+}
+
+const mergeBudgetRanges = (
+  base: ReasoningPortrait['budget'] | ThinkingBudgetRange | null | undefined,
+  overlay: ReasoningPortrait['budget'] | ThinkingBudgetRange | null | undefined
+): ThinkingBudgetRange | null => {
+  const normalizedBase = normalizeBudgetRange(base) ?? {}
+  const normalizedOverlay = normalizeBudgetRange(overlay) ?? {}
+  const merged = {
+    ...normalizedBase,
+    ...normalizedOverlay
+  }
+
+  return Object.keys(merged).length > 0 ? merged : null
+}
 
 // === Interfaces ===
 export interface ModelCapabilities {
   supportsReasoning: boolean | null
-  budgetRange: {
-    min?: number
-    max?: number
-    default?: number
-  } | null
+  budgetRange: ThinkingBudgetRange | null
   supportsSearch: boolean | null
   searchDefaults: {
     default?: boolean
@@ -35,11 +63,7 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
 
   // === Local State ===
   const capabilitySupportsReasoning = ref<boolean | null>(null)
-  const capabilityBudgetRange = ref<{
-    min?: number
-    max?: number
-    default?: number
-  } | null>(null)
+  const capabilityBudgetRange = ref<ThinkingBudgetRange | null>(null)
   const capabilitySupportsSearch = ref<boolean | null>(null)
   const capabilitySupportsTemperatureControl = ref<boolean | null>(null)
   const capabilitySearchDefaults = ref<{
@@ -72,23 +96,25 @@ export function useModelCapabilities(options: UseModelCapabilitiesOptions) {
 
     isLoading.value = true
     try {
-      const [sr, br, ss, sd, stc, tc] = await Promise.all([
-        modelClient.supportsReasoningCapability(currentProviderId, currentModelId),
-        modelClient.getThinkingBudgetRange(currentProviderId, currentModelId),
-        modelClient.supportsSearchCapability(currentProviderId, currentModelId),
-        modelClient.getSearchDefaults(currentProviderId, currentModelId),
-        modelClient.supportsTemperatureControl(currentProviderId, currentModelId),
-        modelClient.getTemperatureCapability(currentProviderId, currentModelId)
-      ])
+      const capabilities = await modelClient.getCapabilities(currentProviderId, currentModelId)
 
       if (currentRequestId !== requestId) return
 
-      capabilitySupportsReasoning.value = typeof sr === 'boolean' ? sr : null
-      capabilityBudgetRange.value = br || {}
-      capabilitySupportsSearch.value = typeof ss === 'boolean' ? ss : null
-      capabilitySearchDefaults.value = sd || {}
+      capabilitySupportsReasoning.value =
+        typeof capabilities.supportsReasoning === 'boolean' ? capabilities.supportsReasoning : null
+      capabilityBudgetRange.value = mergeBudgetRanges(
+        capabilities.thinkingBudgetRange,
+        capabilities.reasoningPortrait?.budget
+      )
+      capabilitySupportsSearch.value =
+        typeof capabilities.supportsSearch === 'boolean' ? capabilities.supportsSearch : null
+      capabilitySearchDefaults.value = capabilities.searchDefaults || {}
       capabilitySupportsTemperatureControl.value =
-        typeof stc === 'boolean' ? stc : typeof tc === 'boolean' ? tc : null
+        typeof capabilities.supportsTemperatureControl === 'boolean'
+          ? capabilities.supportsTemperatureControl
+          : typeof capabilities.temperatureCapability === 'boolean'
+            ? capabilities.temperatureCapability
+            : null
     } catch (error) {
       if (currentRequestId !== requestId) return
 
diff --git a/src/renderer/src/composables/useModelTypeDetection.ts b/src/renderer/src/composables/useModelTypeDetection.ts
index f6e4d4230..0755c3941 100644
--- a/src/renderer/src/composables/useModelTypeDetection.ts
+++ b/src/renderer/src/composables/useModelTypeDetection.ts
@@ -17,7 +17,6 @@ export interface UseModelTypeDetectionReturn {
   isImageGenerationModel: ComputedRef<boolean>
   isVideoGenerationModel: ComputedRef<boolean>
   isTtsModel: ComputedRef<boolean>
-  isGeminiProvider: ComputedRef<boolean>
   modelReasoning: Ref<boolean>
 }
 
@@ -58,12 +57,6 @@ export function useModelTypeDetection(
     return modelType.value === 'tts'
   })
 
-  /**
-   * Checks if current provider is Gemini
-   * Gemini has special thinking budget rules (-1 for unlimited)
-   */
-  const isGeminiProvider = computed(() => providerId.value?.toLowerCase() === 'gemini')
-
   // === Internal Methods ===
   const fetchModelReasoning = async () => {
     const currentRequestId = ++requestId
@@ -96,7 +89,6 @@ export function useModelTypeDetection(
     isImageGenerationModel,
     isVideoGenerationModel,
     isTtsModel,
-    isGeminiProvider,
     modelReasoning
   }
 }
diff --git a/src/renderer/src/composables/useThinkingBudget.ts b/src/renderer/src/composables/useThinkingBudget.ts
index 48d1e11be..6e9273b04 100644
--- a/src/renderer/src/composables/useThinkingBudget.ts
+++ b/src/renderer/src/composables/useThinkingBudget.ts
@@ -9,6 +9,9 @@ export interface ThinkingBudgetRange {
   min?: number
   max?: number
   default?: number
+  auto?: number
+  off?: number
+  unit?: string
 }
 
 export interface UseThinkingBudgetOptions {
@@ -16,7 +19,6 @@ export interface UseThinkingBudgetOptions {
   budgetRange: Ref<ThinkingBudgetRange | null>
   modelReasoning: Ref<boolean>
   supportsReasoning: Ref<boolean | null>
-  isGeminiProvider: ComputedRef<boolean>
 }
 
 export interface UseThinkingBudgetReturn {
@@ -29,8 +31,7 @@ export interface UseThinkingBudgetReturn {
  * Handles budget range validation, display logic, and error messages
  */
 export function useThinkingBudget(options: UseThinkingBudgetOptions): UseThinkingBudgetReturn {
-  const { thinkingBudget, budgetRange, modelReasoning, supportsReasoning, isGeminiProvider } =
-    options
+  const { thinkingBudget, budgetRange, modelReasoning, supportsReasoning } = options
   const { t } = useI18n()
 
   // === Computed Properties ===
@@ -46,13 +47,14 @@ export function useThinkingBudget(options: UseThinkingBudgetOptions): UseThinkin
       !!budgetRange.value &&
       (budgetRange.value.min !== undefined ||
         budgetRange.value.max !== undefined ||
-        budgetRange.value.default !== undefined)
+        budgetRange.value.default !== undefined ||
+        budgetRange.value.auto !== undefined ||
+        budgetRange.value.off !== undefined)
     )
   })
 
   /**
    * Validates thinking budget value and returns error message if invalid
-   * Handles special case for Gemini provider (-1 value)
    */
   const validationError = computed(() => {
     const value = thinkingBudget.value
@@ -62,8 +64,11 @@ export function useThinkingBudget(options: UseThinkingBudgetOptions): UseThinkin
       return ''
     }
 
-    // Gemini special case: -1 is valid (unlimited)
-    if (isGeminiProvider.value && value === -1) {
+    const isProviderDbSentinel =
+      (typeof range.auto === 'number' && value === range.auto) ||
+      (typeof range.off === 'number' && value === range.off)
+
+    if (isProviderDbSentinel) {
       return ''
     }
 
diff --git a/test/renderer/composables/useChatConfigFields.test.ts b/test/renderer/composables/useChatConfigFields.test.ts
index f11805b50..297736944 100644
--- a/test/renderer/composables/useChatConfigFields.test.ts
+++ b/test/renderer/composables/useChatConfigFields.test.ts
@@ -1,26 +1,34 @@
 import { computed, ref } from 'vue'
 import { describe, expect, it, vi } from 'vitest'
 import { useChatConfigFields } from '@/composables/useChatConfigFields'
+import type { ThinkingBudgetRange } from '@/composables/useThinkingBudget'
 
 vi.mock('vue-i18n', () => ({
   useI18n: () => ({ t: (key: string) => key })
 }))
 
-function createFields(supportsTemperatureControl: boolean | null) {
+function createFields(
+  supportsTemperatureControl: boolean | null,
+  options: {
+    showThinkingBudget?: boolean
+    thinkingBudget?: number
+    budgetRange?: ThinkingBudgetRange | null
+  } = {}
+) {
   return useChatConfigFields({
     temperature: ref(0.7),
     contextLength: ref(4096),
     maxTokens: ref(1024),
     contextLengthLimit: ref(undefined),
     maxTokensLimit: ref(undefined),
-    thinkingBudget: ref(undefined),
+    thinkingBudget: ref(options.thinkingBudget),
     reasoningEffort: ref(undefined),
     verbosity: ref(undefined),
     providerId: ref('openai'),
     supportsTemperatureControl: ref(supportsTemperatureControl),
-    showThinkingBudget: computed(() => false),
+    showThinkingBudget: computed(() => options.showThinkingBudget ?? false),
     thinkingBudgetError: computed(() => ''),
-    budgetRange: ref(null),
+    budgetRange: ref(options.budgetRange ?? null),
     formatSize: (size: number) => String(size),
     emit: vi.fn()
   })
@@ -44,4 +52,28 @@ describe('useChatConfigFields', () => {
 
     expect(sliderFields.value.some((field) => field.key === 'temperature')).toBe(true)
   })
+
+  it('expands thinking budget input bounds to include sentinels', () => {
+    const autoFields = createFields(true, {
+      showThinkingBudget: true,
+      budgetRange: { min: 128, max: 24576, auto: -1, unit: 'tokens' }
+    })
+    const autoBudgetField = autoFields.inputFields.value.find(
+      (field) => field.key === 'thinkingBudget'
+    )
+
+    expect(autoBudgetField?.min).toBe(-1)
+    expect(autoBudgetField?.max).toBe(24576)
+
+    const offFields = createFields(true, {
+      showThinkingBudget: true,
+      budgetRange: { min: 512, max: 24576, off: 0, unit: 'tokens' }
+    })
+    const offBudgetField = offFields.inputFields.value.find(
+      (field) => field.key === 'thinkingBudget'
+    )
+
+    expect(offBudgetField?.min).toBe(0)
+    expect(offBudgetField?.max).toBe(24576)
+  })
 })
diff --git a/test/renderer/composables/useModelCapabilities.test.ts b/test/renderer/composables/useModelCapabilities.test.ts
index a74ca24d9..b70d30db3 100644
--- a/test/renderer/composables/useModelCapabilities.test.ts
+++ b/test/renderer/composables/useModelCapabilities.test.ts
@@ -1,12 +1,7 @@
 import { ref } from 'vue'
 import { beforeEach, describe, it, expect, vi } from 'vitest'
 const modelClient = vi.hoisted(() => ({
-  supportsReasoningCapability: vi.fn(),
-  getThinkingBudgetRange: vi.fn(),
-  supportsSearchCapability: vi.fn(),
-  getSearchDefaults: vi.fn(),
-  supportsTemperatureControl: vi.fn(),
-  getTemperatureCapability: vi.fn()
+  getCapabilities: vi.fn()
 }))
 
 vi.mock('@api/ModelClient', () => ({
@@ -32,22 +27,31 @@ describe('useModelCapabilities', () => {
   it('fetches capabilities and resets when ids missing', async () => {
     const providerId = ref<string | undefined>('openai')
     const modelId = ref<string | undefined>('gpt-4')
-    modelClient.supportsReasoningCapability.mockResolvedValue(true)
-    modelClient.getThinkingBudgetRange.mockResolvedValue({ min: 100, max: 200 })
-    modelClient.supportsSearchCapability.mockResolvedValue(true)
-    modelClient.getSearchDefaults.mockResolvedValue({
-      default: true,
-      forced: false,
-      strategy: 'turbo'
+    modelClient.getCapabilities.mockResolvedValue({
+      supportsAudioInput: false,
+      supportsReasoning: true,
+      reasoningPortrait: {
+        budget: { min: 100, max: 200, default: -1, auto: -1, off: 0, unit: 'tokens' }
+      },
+      thinkingBudgetRange: { min: 100, max: 200 },
+      supportsSearch: true,
+      searchDefaults: {
+        default: true,
+        forced: false,
+        strategy: 'turbo'
+      },
+      supportsTemperatureControl: false,
+      temperatureCapability: true
     })
-    modelClient.supportsTemperatureControl.mockResolvedValue(false)
-    modelClient.getTemperatureCapability.mockResolvedValue(true)
 
     const api = useModelCapabilities({ providerId, modelId })
     // initial immediate fetch occurs - wait for isLoading to become false
     await vi.waitFor(() => expect(api.isLoading.value).toBe(false))
     expect(api.supportsReasoning.value).toBe(true)
     expect(api.budgetRange.value?.max).toBe(200)
+    expect(api.budgetRange.value?.auto).toBe(-1)
+    expect(api.budgetRange.value?.off).toBe(0)
+    expect(api.budgetRange.value?.unit).toBe('tokens')
     expect(api.supportsSearch.value).toBe(true)
     expect(api.searchDefaults.value?.strategy).toBe('turbo')
     expect(api.supportsTemperatureControl.value).toBe(false)
@@ -63,12 +67,16 @@ describe('useModelCapabilities', () => {
   it('falls back to temperatureCapability when supportsTemperatureControl is missing', async () => {
     const providerId = ref<string | undefined>('openai')
     const modelId = ref<string | undefined>('gpt-5-chat-latest')
-    modelClient.supportsReasoningCapability.mockResolvedValue(false)
-    modelClient.getThinkingBudgetRange.mockResolvedValue(null)
-    modelClient.supportsSearchCapability.mockResolvedValue(false)
-    modelClient.getSearchDefaults.mockResolvedValue(null)
-    modelClient.supportsTemperatureControl.mockResolvedValue(null)
-    modelClient.getTemperatureCapability.mockResolvedValue(true)
+    modelClient.getCapabilities.mockResolvedValue({
+      supportsAudioInput: false,
+      supportsReasoning: false,
+      reasoningPortrait: null,
+      thinkingBudgetRange: null,
+      supportsSearch: false,
+      searchDefaults: null,
+      supportsTemperatureControl: null,
+      temperatureCapability: true
+    })
 
     const api = useModelCapabilities({ providerId, modelId })
 
@@ -76,63 +84,103 @@ describe('useModelCapabilities', () => {
     expect(api.supportsTemperatureControl.value).toBe(true)
   })
 
+  it('keeps budget range null when capabilities have no budget metadata', async () => {
+    const providerId = ref<string | undefined>('openai')
+    const modelId = ref<string | undefined>('gpt-4o')
+    modelClient.getCapabilities.mockResolvedValue({
+      supportsAudioInput: false,
+      supportsReasoning: false,
+      reasoningPortrait: null,
+      thinkingBudgetRange: null,
+      supportsSearch: false,
+      searchDefaults: null,
+      supportsTemperatureControl: true,
+      temperatureCapability: true
+    })
+
+    const api = useModelCapabilities({ providerId, modelId })
+
+    await vi.waitFor(() => expect(api.isLoading.value).toBe(false))
+    expect(api.budgetRange.value).toBeNull()
+  })
+
+  it('merges thinking budget range with reasoning portrait sentinels', async () => {
+    const providerId = ref<string | undefined>('openrouter')
+    const modelId = ref<string | undefined>('google/gemini-2.5-flash')
+    modelClient.getCapabilities.mockResolvedValue({
+      supportsAudioInput: false,
+      supportsReasoning: true,
+      reasoningPortrait: {
+        budget: { auto: -1, off: 0, unit: 'tokens' }
+      },
+      thinkingBudgetRange: { min: 128, max: 24576, default: 1024 },
+      supportsSearch: false,
+      searchDefaults: null,
+      supportsTemperatureControl: true,
+      temperatureCapability: true
+    })
+
+    const api = useModelCapabilities({ providerId, modelId })
+
+    await vi.waitFor(() => expect(api.isLoading.value).toBe(false))
+    expect(api.budgetRange.value).toEqual({
+      min: 128,
+      max: 24576,
+      default: 1024,
+      auto: -1,
+      off: 0,
+      unit: 'tokens'
+    })
+  })
+
   it('ignores stale capability responses after model changes', async () => {
     const providerId = ref<string | undefined>('openai')
     const modelId = ref<string | undefined>('gpt-old')
     const oldResponse = {
-      supportsReasoning: deferred<boolean>(),
-      budgetRange: deferred<{ min: number; max: number }>(),
-      supportsSearch: deferred<boolean>(),
-      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>(),
-      supportsTemperatureControl: deferred<boolean>(),
-      temperatureCapability: deferred<boolean>()
+      capabilities: deferred<{
+        supportsAudioInput: boolean
+        supportsReasoning: boolean
+        reasoningPortrait: { budget: { min: number; max: number } } | null
+        thinkingBudgetRange: { min: number; max: number } | null
+        supportsSearch: boolean
+        searchDefaults: { strategy: 'turbo' | 'max' }
+        supportsTemperatureControl: boolean
+        temperatureCapability: boolean
+      }>()
     }
     const newResponse = {
-      supportsReasoning: deferred<boolean>(),
-      budgetRange: deferred<{ min: number; max: number }>(),
-      supportsSearch: deferred<boolean>(),
-      searchDefaults: deferred<{ strategy: 'turbo' | 'max' }>(),
-      supportsTemperatureControl: deferred<boolean>(),
-      temperatureCapability: deferred<boolean>()
+      capabilities: deferred<{
+        supportsAudioInput: boolean
+        supportsReasoning: boolean
+        reasoningPortrait: { budget: { min: number; max: number } } | null
+        thinkingBudgetRange: { min: number; max: number } | null
+        supportsSearch: boolean
+        searchDefaults: { strategy: 'turbo' | 'max' }
+        supportsTemperatureControl: boolean
+        temperatureCapability: boolean
+      }>()
     }
 
-    modelClient.supportsReasoningCapability.mockImplementation((_provider, model) =>
-      model === 'gpt-old'
-        ? oldResponse.supportsReasoning.promise
-        : newResponse.supportsReasoning.promise
-    )
-    modelClient.getThinkingBudgetRange.mockImplementation((_provider, model) =>
-      model === 'gpt-old' ? oldResponse.budgetRange.promise : newResponse.budgetRange.promise
-    )
-    modelClient.supportsSearchCapability.mockImplementation((_provider, model) =>
-      model === 'gpt-old' ? oldResponse.supportsSearch.promise : newResponse.supportsSearch.promise
-    )
-    modelClient.getSearchDefaults.mockImplementation((_provider, model) =>
-      model === 'gpt-old' ? oldResponse.searchDefaults.promise : newResponse.searchDefaults.promise
-    )
-    modelClient.supportsTemperatureControl.mockImplementation((_provider, model) =>
-      model === 'gpt-old'
-        ? oldResponse.supportsTemperatureControl.promise
-        : newResponse.supportsTemperatureControl.promise
-    )
-    modelClient.getTemperatureCapability.mockImplementation((_provider, model) =>
-      model === 'gpt-old'
-        ? oldResponse.temperatureCapability.promise
-        : newResponse.temperatureCapability.promise
+    modelClient.getCapabilities.mockImplementation((_provider, model) =>
+      model === 'gpt-old' ? oldResponse.capabilities.promise : newResponse.capabilities.promise
     )
 
     const api = useModelCapabilities({ providerId, modelId })
-    await vi.waitFor(() => expect(modelClient.supportsReasoningCapability).toHaveBeenCalledTimes(1))
+    await vi.waitFor(() => expect(modelClient.getCapabilities).toHaveBeenCalledTimes(1))
 
     modelId.value = 'gpt-new'
-    await vi.waitFor(() => expect(modelClient.supportsReasoningCapability).toHaveBeenCalledTimes(2))
-
-    newResponse.supportsReasoning.resolve(false)
-    newResponse.budgetRange.resolve({ min: 10, max: 20 })
-    newResponse.supportsSearch.resolve(false)
-    newResponse.searchDefaults.resolve({ strategy: 'max' })
-    newResponse.supportsTemperatureControl.resolve(false)
-    newResponse.temperatureCapability.resolve(true)
+    await vi.waitFor(() => expect(modelClient.getCapabilities).toHaveBeenCalledTimes(2))
+
+    newResponse.capabilities.resolve({
+      supportsAudioInput: false,
+      supportsReasoning: false,
+      reasoningPortrait: { budget: { min: 10, max: 20 } },
+      thinkingBudgetRange: null,
+      supportsSearch: false,
+      searchDefaults: { strategy: 'max' },
+      supportsTemperatureControl: false,
+      temperatureCapability: true
+    })
 
     await vi.waitFor(() => expect(api.budgetRange.value?.max).toBe(20))
     expect(api.supportsReasoning.value).toBe(false)
@@ -140,12 +188,16 @@ describe('useModelCapabilities', () => {
     expect(api.searchDefaults.value?.strategy).toBe('max')
     expect(api.supportsTemperatureControl.value).toBe(false)
 
-    oldResponse.supportsReasoning.resolve(true)
-    oldResponse.budgetRange.resolve({ min: 100, max: 200 })
-    oldResponse.supportsSearch.resolve(true)
-    oldResponse.searchDefaults.resolve({ strategy: 'turbo' })
-    oldResponse.supportsTemperatureControl.resolve(true)
-    oldResponse.temperatureCapability.resolve(true)
+    oldResponse.capabilities.resolve({
+      supportsAudioInput: false,
+      supportsReasoning: true,
+      reasoningPortrait: { budget: { min: 100, max: 200 } },
+      thinkingBudgetRange: null,
+      supportsSearch: true,
+      searchDefaults: { strategy: 'turbo' },
+      supportsTemperatureControl: true,
+      temperatureCapability: true
+    })
     await Promise.resolve()
 
     expect(api.budgetRange.value?.max).toBe(20)
diff --git a/test/renderer/composables/useModelTypeDetection.test.ts b/test/renderer/composables/useModelTypeDetection.test.ts
index 99830ad70..985299d11 100644
--- a/test/renderer/composables/useModelTypeDetection.test.ts
+++ b/test/renderer/composables/useModelTypeDetection.test.ts
@@ -34,7 +34,6 @@ describe('useModelTypeDetection', () => {
 
     const api = useModelTypeDetection({ modelId, providerId, modelType })
     expect(api.isImageGenerationModel.value).toBe(true)
-    expect(api.isGeminiProvider.value).toBe(true)
 
     await Promise.resolve()
     expect(api.modelReasoning.value).toBe(true)
diff --git a/test/renderer/composables/useThinkingBudget.test.ts b/test/renderer/composables/useThinkingBudget.test.ts
index 433f8c1ec..1dd35560c 100644
--- a/test/renderer/composables/useThinkingBudget.test.ts
+++ b/test/renderer/composables/useThinkingBudget.test.ts
@@ -1,6 +1,6 @@
-import { ref, computed } from 'vue'
-import { describe, it, expect } from 'vitest'
-import { useThinkingBudget } from '@/composables/useThinkingBudget'
+import { ref } from 'vue'
+import { describe, it, expect, vi } from 'vitest'
+import { useThinkingBudget, type ThinkingBudgetRange } from '@/composables/useThinkingBudget'
 
 // mock i18n -> return the key so we can assert on it
 vi.mock('vue-i18n', () => ({
@@ -10,20 +10,18 @@ vi.mock('vue-i18n', () => ({
 describe('useThinkingBudget', () => {
   it('computes showThinkingBudget only when reasoning supported and range provided', () => {
     const thinkingBudget = ref<number | undefined>(undefined)
-    const budgetRange = ref<{ min?: number; max?: number; default?: number } | null>({
+    const budgetRange = ref<ThinkingBudgetRange | null>({
       min: 256,
       max: 4096
     })
     const modelReasoning = ref(true)
     const supportsReasoning = ref<boolean | null>(true)
-    const isGeminiProvider = computed(() => false)
 
     const api = useThinkingBudget({
       thinkingBudget,
       budgetRange,
       modelReasoning,
-      supportsReasoning,
-      isGeminiProvider
+      supportsReasoning
     })
     expect(api.showThinkingBudget.value).toBe(true)
 
@@ -33,24 +31,25 @@ describe('useThinkingBudget', () => {
     supportsReasoning.value = true
     budgetRange.value = null
     expect(api.showThinkingBudget.value).toBe(false)
+
+    budgetRange.value = { auto: -1 }
+    expect(api.showThinkingBudget.value).toBe(true)
   })
 
-  it('validates range and returns translation keys; allows -1 for Gemini', () => {
+  it('validates ranges and allows provider-db budget sentinels', () => {
     const thinkingBudget = ref<number | undefined>(128)
-    const budgetRange = ref<{ min?: number; max?: number; default?: number } | null>({
+    const budgetRange = ref<ThinkingBudgetRange | null>({
       min: 256,
       max: 1024
     })
     const modelReasoning = ref(true)
     const supportsReasoning = ref<boolean | null>(true)
-    const isGeminiProvider = computed(() => false)
 
     const api = useThinkingBudget({
       thinkingBudget,
       budgetRange,
       modelReasoning,
-      supportsReasoning,
-      isGeminiProvider
+      supportsReasoning
     })
     expect(api.validationError.value).toBe(
       'settings.model.modelConfig.thinkingBudget.validation.minValue'
@@ -64,14 +63,16 @@ describe('useThinkingBudget', () => {
     thinkingBudget.value = 512
     expect(api.validationError.value).toBe('')
 
-    // Gemini special case
-    const gemApi = useThinkingBudget({
-      thinkingBudget: ref(-1),
-      budgetRange,
-      modelReasoning,
-      supportsReasoning,
-      isGeminiProvider: computed(() => true)
-    })
-    expect(gemApi.validationError.value).toBe('')
+    thinkingBudget.value = -1
+    expect(api.validationError.value).toBe(
+      'settings.model.modelConfig.thinkingBudget.validation.minValue'
+    )
+
+    budgetRange.value = { min: 0, max: 24576, default: -1, auto: -1, off: 0, unit: 'tokens' }
+    expect(api.validationError.value).toBe('')
+
+    budgetRange.value = { min: 512, max: 24576, off: 0 }
+    thinkingBudget.value = 0
+    expect(api.validationError.value).toBe('')
   })
 })

From b7269bbdb50c7841cb3a66f64001875ff1acc693 Mon Sep 17 00:00:00 2001
From: zerob13 <zerob13@gmail.com>
Date: Tue, 2 Jun 2026 18:39:50 +0800
Subject: [PATCH 7/8] chore(release): prepare v1.0.5-beta.8

---
 CHANGELOG.md                                 | 10 +++++
 docs/features/v1-0-5-beta-8-release/plan.md  | 45 +++++++++++++++++++
 docs/features/v1-0-5-beta-8-release/spec.md  | 47 ++++++++++++++++++++
 docs/features/v1-0-5-beta-8-release/tasks.md | 16 +++++++
 package.json                                 |  2 +-
 5 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 docs/features/v1-0-5-beta-8-release/plan.md
 create mode 100644 docs/features/v1-0-5-beta-8-release/spec.md
 create mode 100644 docs/features/v1-0-5-beta-8-release/tasks.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3141197a9..7ae3ca8be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## v1.0.5-beta.8 (2026-06-02)
+- Added a collapsible workspace file tree sidebar and an animated theme toggle in the app sidebar
+- Added automatic chat activity collapsing so completed reasoning and tool-call work stays easier to scan
+- Improved ACP v1 reliability with stronger capability handling, session persistence, terminal behavior, diagnostics, and protocol coverage
+- Fixed model capability handling for temperature controls and provider database budget sentinels
+- 新增可折叠的工作区文件树侧栏和应用侧栏动态主题切换按钮
+- 新增聊天活动自动折叠，让完成后的思考和工具调用内容更易扫读
+- 提升 ACP v1 可靠性，完善能力处理、会话持久化、终端行为、诊断和协议覆盖
+- 修复温度控制和 Provider 数据库预算特殊值的模型能力处理
+
 ## v1.0.5-beta.7 (2026-06-01)
 - Added agent session transfer so chats can be preserved or moved when changing agent ownership
 - Added a richer workspace Git diff panel rendering experience
diff --git a/docs/features/v1-0-5-beta-8-release/plan.md b/docs/features/v1-0-5-beta-8-release/plan.md
new file mode 100644
index 000000000..d8694a26b
--- /dev/null
+++ b/docs/features/v1-0-5-beta-8-release/plan.md
@@ -0,0 +1,45 @@
+# Implementation Plan - v1.0.5-beta.8 Release
+
+## Current State
+
+- Current branch: `dev`.
+- Current version: `1.0.5-beta.7`.
+- Target version: `1.0.5-beta.8`.
+- No local or remote `release/v1.0.5-beta.8` branch exists.
+- No local or remote `v1.0.5-beta.8` tag exists.
+- `git fetch --tags --prune` reports historical tag mismatches for `v1.0.0-beta.7` and
+  `v1.0.5-beta.3`; these are unrelated to the target release and must not be replaced.
+
+## Release Notes Source
+
+Summarize first-parent commits after `v1.0.5-beta.7`:
+
+- Collapsible workspace file tree sidebar.
+- Animated theme toggle button in the app sidebar.
+- ACP v1 protocol reliability improvements.
+- Automatic completed turn activity collapsing.
+- Model capability handling for temperature controls.
+- Provider database budget sentinel handling.
+
+## Steps
+
+1. Update `package.json` to `1.0.5-beta.8`.
+2. Add `CHANGELOG.md` notes for `v1.0.5-beta.8`.
+3. Run release checks.
+4. Commit release metadata on `dev`.
+5. Push `dev`.
+6. Create and push `release/v1.0.5-beta.8`.
+7. Open a PR from `release/v1.0.5-beta.8` to `main`.
+
+## Validation
+
+- `pnpm run format`
+- `pnpm run i18n`
+- `pnpm run lint`
+- `pnpm run typecheck`
+
+## Rollback
+
+If validation fails before pushing, keep the branch on `dev` and fix the metadata or report the
+blocking check. If the release branch is pushed but review rejects the release, delete only the
+disposable `release/v1.0.5-beta.8` branch and keep any agreed metadata fixes on `dev`.
diff --git a/docs/features/v1-0-5-beta-8-release/spec.md b/docs/features/v1-0-5-beta-8-release/spec.md
new file mode 100644
index 000000000..ac26dd12e
--- /dev/null
+++ b/docs/features/v1-0-5-beta-8-release/spec.md
@@ -0,0 +1,47 @@
+# v1.0.5-beta.8 Release
+
+## Context
+
+DeepChat v1.0.5-beta.7 was published on 2026-06-01. The `dev` branch now contains
+workspace navigation, sidebar theme switching, chat activity compaction, ACP v1 reliability, and
+model settings fixes that should be reviewed through a new beta release PR.
+
+## User Need
+
+Beta users need a prerelease build that includes the latest usability and reliability improvements
+without waiting for the next stable release.
+
+## Goals
+
+- Prepare release metadata for `v1.0.5-beta.8`.
+- Keep release notes concise and bilingual, with English bullets first and Chinese bullets second.
+- Cut a disposable `release/v1.0.5-beta.8` branch from the release-ready `dev` commit.
+- Open a PR from `release/v1.0.5-beta.8` to `main` for maintainer review.
+
+## Non-goals
+
+- No product behavior changes beyond release metadata.
+- No publishing step, `main` fast-forward, or release tag creation before maintainer review.
+- No replacement of mismatched historical tags unrelated to `v1.0.5-beta.8`.
+
+## Acceptance Criteria
+
+1. `package.json` reports version `1.0.5-beta.8`.
+2. `CHANGELOG.md` contains a top entry for `v1.0.5-beta.8` dated `2026-06-02`.
+3. The changelog entry summarizes first-parent commits after `v1.0.5-beta.7`.
+4. Required release checks pass: `pnpm run format`, `pnpm run i18n`, and `pnpm run lint`.
+5. `pnpm run typecheck` passes before cutting the release branch.
+6. `dev` contains the release metadata commit.
+7. `release/v1.0.5-beta.8` is pushed and points at the same commit as `dev`.
+8. A PR from `release/v1.0.5-beta.8` to `main` is open for review.
+
+## Constraints
+
+- Follow the repository release flow in `docs/release-flow.md`.
+- Keep `dev` as the integration branch.
+- Treat `release/v1.0.5-beta.8` as disposable and identical to a commit already on `dev`.
+- Do not replace or delete existing mismatched historical tags without maintainer approval.
+
+## Open Questions
+
+None.
diff --git a/docs/features/v1-0-5-beta-8-release/tasks.md b/docs/features/v1-0-5-beta-8-release/tasks.md
new file mode 100644
index 000000000..7543e1c1d
--- /dev/null
+++ b/docs/features/v1-0-5-beta-8-release/tasks.md
@@ -0,0 +1,16 @@
+# Tasks - v1.0.5-beta.8 Release
+
+- [x] Confirm current branch, working tree, existing release branches, and existing tags.
+- [x] Pull latest `dev` and `main` refs.
+- [x] Confirm `v1.0.5-beta.8` and `release/v1.0.5-beta.8` do not exist locally or remotely.
+- [x] Identify first-parent commits after `v1.0.5-beta.7`.
+- [x] Update `package.json` to `1.0.5-beta.8`.
+- [x] Add `CHANGELOG.md` notes for `v1.0.5-beta.8`.
+- [x] Run `pnpm run format`.
+- [x] Run `pnpm run i18n`.
+- [x] Run `pnpm run lint`.
+- [x] Run `pnpm run typecheck`.
+- [x] Commit release metadata on `dev`.
+- [x] Push `dev`.
+- [x] Create and push `release/v1.0.5-beta.8`.
+- [x] Open PR from `release/v1.0.5-beta.8` to `main`.
diff --git a/package.json b/package.json
index 49847f82c..49928257b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "DeepChat",
-  "version": "1.0.5-beta.7",
+  "version": "1.0.5-beta.8",
   "description": "DeepChat，一个简单易用的 Agent 客户端",
   "main": "./out/main/index.js",
   "author": "ThinkInAIXYZ",

From 0422b97bf4a1979b14ec148dd325743a66889208 Mon Sep 17 00:00:00 2001
From: zerob13 <zerob13@gmail.com>
Date: Tue, 2 Jun 2026 18:46:22 +0800
Subject: [PATCH 8/8] docs: exempt release metadata from sdd

---
 .agents/skills/deepchat-release/SKILL.md     |  1 +
 AGENTS.md                                    |  3 ++
 docs/features/v1-0-5-beta-7-release/plan.md  | 50 ------------------
 docs/features/v1-0-5-beta-7-release/spec.md  | 53 --------------------
 docs/features/v1-0-5-beta-7-release/tasks.md | 24 ---------
 docs/features/v1-0-5-beta-8-release/plan.md  | 45 -----------------
 docs/features/v1-0-5-beta-8-release/spec.md  | 47 -----------------
 docs/features/v1-0-5-beta-8-release/tasks.md | 16 ------
 docs/spec-driven-dev.md                      |  4 ++
 9 files changed, 8 insertions(+), 235 deletions(-)
 delete mode 100644 docs/features/v1-0-5-beta-7-release/plan.md
 delete mode 100644 docs/features/v1-0-5-beta-7-release/spec.md
 delete mode 100644 docs/features/v1-0-5-beta-7-release/tasks.md
 delete mode 100644 docs/features/v1-0-5-beta-8-release/plan.md
 delete mode 100644 docs/features/v1-0-5-beta-8-release/spec.md
 delete mode 100644 docs/features/v1-0-5-beta-8-release/tasks.md

diff --git a/.agents/skills/deepchat-release/SKILL.md b/.agents/skills/deepchat-release/SKILL.md
index 671c7ab2e..1ced084ab 100644
--- a/.agents/skills/deepchat-release/SKILL.md
+++ b/.agents/skills/deepchat-release/SKILL.md
@@ -42,6 +42,7 @@ When preparing a release on `dev`:
 - Add a new `CHANGELOG.md` section at the top.
 - Summarize only user-visible or release-relevant changes since the previous tag.
 - Prefer deriving the notes from recent commits or the diff since the previous release tag.
+- Do not create SDD folders for pure release metadata, branch, tag, or release PR work.
 
 For `v1.0.1` and later, format changelog entries in this order:
 
diff --git a/AGENTS.md b/AGENTS.md
index c94e97606..4fc5f9992 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,6 +46,9 @@
 
 Follow the SDD methodology before changing code, tests, configuration, documentation, build scripts, or project structure. See [docs/spec-driven-dev.md](docs/spec-driven-dev.md).
 
+Pure release metadata work does not require SDD. Version bumps, `CHANGELOG.md` updates, release branch management, tags, and release PR preparation should follow [docs/release-flow.md](docs/release-flow.md) without creating
+`docs/features/*release*` folders.
+
 Create one kebab-case folder per goal and keep `spec.md`, `plan.md`, and `tasks.md` together:
 
 - `docs/features/<goal>/` for new features, user-visible capabilities, integrations, and tools.
diff --git a/docs/features/v1-0-5-beta-7-release/plan.md b/docs/features/v1-0-5-beta-7-release/plan.md
deleted file mode 100644
index a52636860..000000000
--- a/docs/features/v1-0-5-beta-7-release/plan.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# Implementation Plan - v1.0.5-beta.7 Release
-
-## Current State
-
-- Current branch: `dev`.
-- Current version: `1.0.5-beta.7`.
-- Target version: `1.0.5-beta.7`.
-- Remote `v1.0.5-beta.7` exists on `894110a4a`.
-- Latest `origin/dev` includes additional commits after `894110a4a`.
-- No local or remote `release/v1.0.5-beta.7` branch exists.
-- `git fetch --tags --prune` reports historical tag mismatches for `v1.0.0-beta.7` and
-  `v1.0.5-beta.3`; these are unrelated to the target release and must not be replaced.
-
-## Release Notes Source
-
-Summarize first-parent commits after `v1.0.5-beta.6`:
-
-- Agent session transfer flow.
-- NewAPI routing and capability overlay fixes.
-- AI SDK system prompt request handling.
-- Workspace file reference insertion fix.
-- Floating button position persistence.
-- Image-capable model chat switching fix.
-- Collapsed sidebar agent click expansion fix.
-- Workspace Git diff panel rendering improvements.
-- Plan model styling fix.
-
-## Steps
-
-1. Keep `package.json` on `1.0.5-beta.7`.
-2. Update the `v1.0.5-beta.7` changelog entry for the latest merged commits.
-3. Run release checks.
-4. Commit release metadata on `dev`.
-5. Push `dev`.
-6. Fast-forward `main` to the latest release-ready commit.
-7. Move the local `v1.0.5-beta.7` tag to the latest release-ready commit.
-8. Do not push the moved tag until the maintainer wants to rerun the release action.
-
-## Validation
-
-- `pnpm run format`
-- `pnpm run i18n`
-- `pnpm run lint`
-- `pnpm run typecheck`
-
-## Rollback
-
-If validation fails before pushing, keep the branch on `dev` and fix the metadata or report the
-blocking check. If the retargeted tag must be abandoned before triggering the action, reset only the
-local tag back to the remote tag commit and leave the remote tag unchanged.
diff --git a/docs/features/v1-0-5-beta-7-release/spec.md b/docs/features/v1-0-5-beta-7-release/spec.md
deleted file mode 100644
index b3099e0c7..000000000
--- a/docs/features/v1-0-5-beta-7-release/spec.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# v1.0.5-beta.7 Release
-
-## Context
-
-DeepChat v1.0.5-beta.6 has been published. The `dev` branch now contains a small set of
-user-visible fixes and one agent session transfer feature that should be made available through the
-next beta release.
-
-An initial `v1.0.5-beta.7` tag was created on `894110a4a`, but new code was merged afterward. The
-beta should be retargeted to the latest release-ready commit before rerunning the release action.
-
-## User Need
-
-Beta users need a new prerelease build that includes the latest agent transfer flow, workspace input
-fixes, model routing fixes, and UI stability improvements without waiting for the next stable
-release.
-
-## Goals
-
-- Prepare release metadata for `v1.0.5-beta.7`.
-- Keep release notes concise and bilingual, with English bullets first and Chinese bullets second.
-- Cut a disposable `release/v1.0.5-beta.7` branch from the release-ready `dev` commit.
-- Retarget the beta to the latest release-ready commit without triggering a new release action until
-  the maintainer is ready.
-
-## Non-goals
-
-- No product behavior changes beyond release metadata.
-- No release-only code changes outside `package.json`, `CHANGELOG.md`, and this SDD record.
-- No replacement of existing tags that differ between local and remote history.
-
-## Acceptance Criteria
-
-1. `package.json` reports version `1.0.5-beta.7`.
-2. `CHANGELOG.md` contains a top entry for `v1.0.5-beta.7` dated `2026-06-01`.
-3. The changelog entry summarizes commits after `v1.0.5-beta.6`.
-4. Required release checks pass: `pnpm run format`, `pnpm run i18n`, and `pnpm run lint`.
-5. `main` is fast-forwarded to the latest release-ready commit.
-6. The local `v1.0.5-beta.7` tag points to that latest release-ready commit.
-7. The remote `v1.0.5-beta.7` tag is not replaced until the maintainer explicitly wants to trigger
-   the release action again.
-
-## Constraints
-
-- Follow the repository release flow in `docs/release-flow.md`.
-- Keep `dev` as the integration branch.
-- Treat `release/v1.0.5-beta.7` as disposable and identical to a commit already on `dev`.
-- Do not replace or delete existing mismatched historical tags without maintainer approval.
-- Do not push the retargeted `v1.0.5-beta.7` tag while the release action should remain paused.
-
-## Open Questions
-
-None.
diff --git a/docs/features/v1-0-5-beta-7-release/tasks.md b/docs/features/v1-0-5-beta-7-release/tasks.md
deleted file mode 100644
index caec05ab3..000000000
--- a/docs/features/v1-0-5-beta-7-release/tasks.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Tasks - v1.0.5-beta.7 Release
-
-- [x] Confirm current branch, working tree, existing release branches, and existing tags.
-- [x] Confirm `v1.0.5-beta.7` and `release/v1.0.5-beta.7` do not exist locally or remotely.
-- [x] Pull latest `dev` with fast-forward-only behavior.
-- [x] Update `package.json` to `1.0.5-beta.7`.
-- [x] Add `CHANGELOG.md` notes for `v1.0.5-beta.7`.
-- [x] Run `pnpm run format`.
-- [x] Run `pnpm run i18n`.
-- [x] Run `pnpm run lint`.
-- [x] Run `pnpm run typecheck`.
-- [x] Commit initial release metadata on `dev`.
-- [x] Push initial release metadata to `dev`.
-- [x] Create and push initial `v1.0.5-beta.7`.
-- [x] Fast-forward initial `main` to `v1.0.5-beta.7`.
-- [x] Clean up initial `release/v1.0.5-beta.7`.
-- [x] Pull latest merged code after the initial tag.
-- [x] Update `v1.0.5-beta.7` notes for the latest merged commits.
-- [x] Run release checks after the latest notes update.
-- [ ] Commit latest release metadata on `dev`.
-- [ ] Push latest `dev`.
-- [ ] Fast-forward `main` to the latest release-ready commit.
-- [ ] Move local `v1.0.5-beta.7` to the latest release-ready commit.
-- [ ] Push the moved `v1.0.5-beta.7` tag only when ready to trigger release action.
diff --git a/docs/features/v1-0-5-beta-8-release/plan.md b/docs/features/v1-0-5-beta-8-release/plan.md
deleted file mode 100644
index d8694a26b..000000000
--- a/docs/features/v1-0-5-beta-8-release/plan.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Implementation Plan - v1.0.5-beta.8 Release
-
-## Current State
-
-- Current branch: `dev`.
-- Current version: `1.0.5-beta.7`.
-- Target version: `1.0.5-beta.8`.
-- No local or remote `release/v1.0.5-beta.8` branch exists.
-- No local or remote `v1.0.5-beta.8` tag exists.
-- `git fetch --tags --prune` reports historical tag mismatches for `v1.0.0-beta.7` and
-  `v1.0.5-beta.3`; these are unrelated to the target release and must not be replaced.
-
-## Release Notes Source
-
-Summarize first-parent commits after `v1.0.5-beta.7`:
-
-- Collapsible workspace file tree sidebar.
-- Animated theme toggle button in the app sidebar.
-- ACP v1 protocol reliability improvements.
-- Automatic completed turn activity collapsing.
-- Model capability handling for temperature controls.
-- Provider database budget sentinel handling.
-
-## Steps
-
-1. Update `package.json` to `1.0.5-beta.8`.
-2. Add `CHANGELOG.md` notes for `v1.0.5-beta.8`.
-3. Run release checks.
-4. Commit release metadata on `dev`.
-5. Push `dev`.
-6. Create and push `release/v1.0.5-beta.8`.
-7. Open a PR from `release/v1.0.5-beta.8` to `main`.
-
-## Validation
-
-- `pnpm run format`
-- `pnpm run i18n`
-- `pnpm run lint`
-- `pnpm run typecheck`
-
-## Rollback
-
-If validation fails before pushing, keep the branch on `dev` and fix the metadata or report the
-blocking check. If the release branch is pushed but review rejects the release, delete only the
-disposable `release/v1.0.5-beta.8` branch and keep any agreed metadata fixes on `dev`.
diff --git a/docs/features/v1-0-5-beta-8-release/spec.md b/docs/features/v1-0-5-beta-8-release/spec.md
deleted file mode 100644
index ac26dd12e..000000000
--- a/docs/features/v1-0-5-beta-8-release/spec.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# v1.0.5-beta.8 Release
-
-## Context
-
-DeepChat v1.0.5-beta.7 was published on 2026-06-01. The `dev` branch now contains
-workspace navigation, sidebar theme switching, chat activity compaction, ACP v1 reliability, and
-model settings fixes that should be reviewed through a new beta release PR.
-
-## User Need
-
-Beta users need a prerelease build that includes the latest usability and reliability improvements
-without waiting for the next stable release.
-
-## Goals
-
-- Prepare release metadata for `v1.0.5-beta.8`.
-- Keep release notes concise and bilingual, with English bullets first and Chinese bullets second.
-- Cut a disposable `release/v1.0.5-beta.8` branch from the release-ready `dev` commit.
-- Open a PR from `release/v1.0.5-beta.8` to `main` for maintainer review.
-
-## Non-goals
-
-- No product behavior changes beyond release metadata.
-- No publishing step, `main` fast-forward, or release tag creation before maintainer review.
-- No replacement of mismatched historical tags unrelated to `v1.0.5-beta.8`.
-
-## Acceptance Criteria
-
-1. `package.json` reports version `1.0.5-beta.8`.
-2. `CHANGELOG.md` contains a top entry for `v1.0.5-beta.8` dated `2026-06-02`.
-3. The changelog entry summarizes first-parent commits after `v1.0.5-beta.7`.
-4. Required release checks pass: `pnpm run format`, `pnpm run i18n`, and `pnpm run lint`.
-5. `pnpm run typecheck` passes before cutting the release branch.
-6. `dev` contains the release metadata commit.
-7. `release/v1.0.5-beta.8` is pushed and points at the same commit as `dev`.
-8. A PR from `release/v1.0.5-beta.8` to `main` is open for review.
-
-## Constraints
-
-- Follow the repository release flow in `docs/release-flow.md`.
-- Keep `dev` as the integration branch.
-- Treat `release/v1.0.5-beta.8` as disposable and identical to a commit already on `dev`.
-- Do not replace or delete existing mismatched historical tags without maintainer approval.
-
-## Open Questions
-
-None.
diff --git a/docs/features/v1-0-5-beta-8-release/tasks.md b/docs/features/v1-0-5-beta-8-release/tasks.md
deleted file mode 100644
index 7543e1c1d..000000000
--- a/docs/features/v1-0-5-beta-8-release/tasks.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Tasks - v1.0.5-beta.8 Release
-
-- [x] Confirm current branch, working tree, existing release branches, and existing tags.
-- [x] Pull latest `dev` and `main` refs.
-- [x] Confirm `v1.0.5-beta.8` and `release/v1.0.5-beta.8` do not exist locally or remotely.
-- [x] Identify first-parent commits after `v1.0.5-beta.7`.
-- [x] Update `package.json` to `1.0.5-beta.8`.
-- [x] Add `CHANGELOG.md` notes for `v1.0.5-beta.8`.
-- [x] Run `pnpm run format`.
-- [x] Run `pnpm run i18n`.
-- [x] Run `pnpm run lint`.
-- [x] Run `pnpm run typecheck`.
-- [x] Commit release metadata on `dev`.
-- [x] Push `dev`.
-- [x] Create and push `release/v1.0.5-beta.8`.
-- [x] Open PR from `release/v1.0.5-beta.8` to `main`.
diff --git a/docs/spec-driven-dev.md b/docs/spec-driven-dev.md
index 9a89f76c9..01fbe16ca 100644
--- a/docs/spec-driven-dev.md
+++ b/docs/spec-driven-dev.md
@@ -14,6 +14,10 @@ Keep every active change in a lightweight SDD folder so reviewers can find the i
 - `docs/issues/<goal>/` - bug fixes, regressions, failing tests, CI failures, reliability issues, and prompt/runtime problems
 - `docs/architecture/<goal>/` - refactors, migrations, dependency boundaries, shared contracts, runtime architecture, and cross-module design
 
+Pure release metadata work is exempt from SDD. Version bumps, `CHANGELOG.md` updates, release branch
+management, tags, and release PR preparation should follow `docs/release-flow.md` without creating a
+release-specific SDD folder.
+
 Each active goal folder contains:
 
 - `spec.md` - user stories, acceptance criteria, non-goals, constraints, open questions