feat(workspace): unify lifecycle refresh (#1352)

Author: zerob13

docs/specs/workspace-lifecycle/plan.md

@@ -0,0 +1,45 @@
+# Workspace Lifecycle Plan
+
+## Architecture
+
+- `WorkspacePresenter` owns watcher runtimes keyed by `workspacePath`.
+- Each runtime contains:
+  - a recursive filesystem watcher for workspace content
+  - a targeted Git metadata watcher for `HEAD`, `index`, `packed-refs`, and `refs`
+  - a debounce buffer that emits one invalidation payload
+- `registerWorkspace` remains the read-security boundary.
+- `watchWorkspace` / `unwatchWorkspace` control watcher lifecycle separately from path registration.
+
+## Event Contract
+
+- Channel: `workspace:files-changed`
+- Canonical constant: `WORKSPACE_EVENTS.INVALIDATED`
+- Legacy alias: `WORKSPACE_EVENTS.FILES_CHANGED`
+- Payload:
+
+```ts
+type WorkspaceInvalidationEvent = {
+  workspacePath: string
+  kind: 'fs' | 'git' | 'full'
+  source: 'watcher' | 'fallback' | 'lifecycle'
+}
+```
+
+## Renderer Refresh Flow
+
+- Initial load and all invalidation refreshes use the same sync helper.
+- `fs/full` refresh:
+  - reload root tree
+  - restore expanded directories
+  - reload Git state
+  - reload current preview and diff
+  - clear stale selected file/diff state
+- `git` refresh:
+  - reload Git state
+  - reload current diff
+  - leave file tree and plain file preview untouched
+
+## Test Strategy
+
+- Main-process tests cover watcher ref counting, debounce behavior, Git invalidation emission, and destroy cleanup.
+- Renderer tests cover watcher lifecycle, full-vs-git refresh routing, expanded directory restoration, and stale selection cleanup.

docs/specs/workspace-lifecycle/spec.md

@@ -0,0 +1,26 @@
+# Workspace Lifecycle
+
+## Summary
+
+Workspace sidepanel state should refresh through a single invalidation pipeline instead of ad-hoc reloads. The main process owns invalidation production, and the renderer owns refresh execution.
+
+## User Stories
+
+- As a user, when files are created, edited, moved, or removed in the current workspace, the file tree should refresh without manual action.
+- As a user, when Git metadata changes without a file content change, the Git section should still refresh.
+- As a maintainer, I need one clear contract for workspace invalidation so future features do not add more bespoke refresh paths.
+
+## Acceptance Criteria
+
+- Workspace content changes emit a typed invalidation event with `kind: 'fs'`.
+- Git metadata changes emit a typed invalidation event with `kind: 'git'`.
+- Renderer refreshes file tree, Git state, preview, and diff through one shared sync path.
+- Expanded directories stay expanded after a full refresh when the directory still exists.
+- Stale selected file and diff state are cleared when the backing file or Git change disappears.
+- Read-only filesystem operations do not emit workspace invalidation events.
+
+## Non-Goals
+
+- Artifact refresh is not part of workspace invalidation.
+- Hidden file visibility rules are unchanged.
+- Watchers are not promoted to a global always-on workspace service.

src/main/events.ts

@@ -256,7 +256,8 @@ export const LIFECYCLE_EVENTS = {
 
 // Workspace events
 export const WORKSPACE_EVENTS = {
-  FILES_CHANGED: 'workspace:files-changed' // File tree changed
+  INVALIDATED: 'workspace:files-changed', // Workspace invalidation event
+  FILES_CHANGED: 'workspace:files-changed' // Legacy alias
 }
 
 // ACP-specific workspace events

src/main/presenter/agentPresenter/acp/acpProcessManager.ts

@@ -19,7 +19,7 @@ import { buildClientCapabilities } from './acpCapabilities'
 import { AcpFsHandler } from './acpFsHandler'
 import { AcpTerminalManager } from './acpTerminalManager'
 import { eventBus, SendTarget } from '@/eventbus'
-import { ACP_WORKSPACE_EVENTS, WORKSPACE_EVENTS } from '@/events'
+import { ACP_WORKSPACE_EVENTS } from '@/events'
 
 export interface AcpProcessHandle extends AgentProcessHandle {
   child: ChildProcessWithoutNullStreams
@@ -139,14 +139,6 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
     return handler
   }
 
-  private notifyWorkspaceFilesChanged(sessionId: string): void {
-    const conversationId = this.sessionConversations.get(sessionId)
-    if (!conversationId) return
-    eventBus.sendToRenderer(WORKSPACE_EVENTS.FILES_CHANGED, SendTarget.ALL_WINDOWS, {
-      conversationId
-    })
-  }
-
   /**
    * Provide a fallback workspace for sessions that haven't registered a workdir.
    * Keeps file access constrained to a temp directory rather than the entire filesystem.
@@ -897,19 +889,11 @@ export class AcpProcessManager implements AgentProcessManager<AcpProcessHandle,
       // File system operations
       readTextFile: async (params) => {
         const handler = this.getFsHandler(params.sessionId)
-        try {
-          return await handler.readTextFile(params)
-        } finally {
-          this.notifyWorkspaceFilesChanged(params.sessionId)
-        }
+        return await handler.readTextFile(params)
       },
       writeTextFile: async (params) => {
         const handler = this.getFsHandler(params.sessionId)
-        try {
-          return await handler.writeTextFile(params)
-        } finally {
-          this.notifyWorkspaceFilesChanged(params.sessionId)
-        }
+        return await handler.writeTextFile(params)
       },
       // Terminal operations
       createTerminal: async (params) => {

src/main/presenter/agentPresenter/loop/agentLoopHandler.ts

@@ -5,8 +5,6 @@ import {
   LLMAgentEvent,
   MCPToolCall
 } from '@shared/presenter'
-import { eventBus, SendTarget } from '@/eventbus'
-import { WORKSPACE_EVENTS } from '@/events'
 import { BaseLLMProvider } from '@/presenter/llmProviderPresenter/baseProvider'
 import { StreamState } from './loopState'
 import { RateLimitManager } from '@/presenter/llmProviderPresenter/managers/rateLimitManager'
@@ -66,10 +64,6 @@ export class AgentLoopHandler {
           return null
         }
         return await toolPresenter.preCheckToolPermission(request)
-      },
-      onToolCallFinished: ({ toolServerName, conversationId }) => {
-        if (toolServerName !== 'agent-filesystem') return
-        this.notifyWorkspaceFilesChanged(conversationId)
       }
     })
   }
@@ -95,13 +89,6 @@ export class AgentLoopHandler {
     return this.options.sessionRuntime.resolveWorkspaceContext(conversationId, modelId)
   }
 
-  private notifyWorkspaceFilesChanged(conversationId?: string): void {
-    if (!conversationId) return
-    eventBus.sendToRenderer(WORKSPACE_EVENTS.FILES_CHANGED, SendTarget.ALL_WINDOWS, {
-      conversationId
-    })
-  }
-
   private requiresReasoningField(modelId: string): boolean {
     const lower = modelId.toLowerCase()
     return (
@@ -677,11 +664,6 @@ export class AgentLoopHandler {
 
       this.options.activeStreams.delete(eventId)
       console.log('Agent loop finished for event:', eventId, 'User stopped:', userStop)
-
-      // Trigger ACP workspace file refresh (only for ACP provider)
-      if (providerId === 'acp') {
-        this.notifyWorkspaceFilesChanged(conversationId)
-      }
     }
   }
 }

src/main/presenter/index.ts

@@ -566,6 +566,7 @@ export class Presenter implements IPresenter {
     this.syncPresenter.destroy() // 销毁同步相关资源
     this.notificationPresenter.clearAllNotifications() // 清除所有通知
     this.knowledgePresenter.destroy() // 释放所有数据库连接
+    ;(this.workspacePresenter as WorkspacePresenter).destroy() // 销毁 Workspace watchers
     ;(this.skillPresenter as SkillPresenter).destroy() // 销毁 Skills 相关资源
     ;(this.skillSyncPresenter as SkillSyncPresenter).destroy() // 销毁 Skill Sync 相关资源
     // 注意: trayPresenter.destroy() 在 main/index.ts 的 will-quit 事件中处理