cc-viewer 1.9.3 → 1.9.4

package/server/server.js

@@ -2,7 +2,7 @@ import { createServer } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
 import { createConnection } from 'node:net';
 import { randomBytes } from 'node:crypto';
-import { readFileSync, existsSync, unwatchFile, statSync, renameSync, unlinkSync } from 'node:fs';
+import { readFileSync, existsSync, unwatchFile, statSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { join, extname, resolve, sep } from 'node:path';
 import { platform, networkInterfaces, tmpdir } from 'node:os';
 import { execFile, exec, spawn } from 'node:child_process';
@@ -41,6 +41,8 @@ import { authRoutes } from './routes/auth.js';
 import { dingtalkRoutes } from './routes/dingtalk.js';
 import { imRoutes } from './routes/im.js';
 import { resumeRoutes } from './routes/resume.js';
+import { sdkContextRoutes } from './routes/sdk-context.js';
+import { sdkMcpStatusRoutes } from './routes/sdk-mcp-status.js';
 import { proxyStatsRoutes } from './routes/proxy-stats.js';
 import { setProxyStatsListener } from './lib/proxy/proxy-stats.js';
 import * as imCore from './lib/im/im-bridge-core.js';
@@ -95,7 +97,7 @@ function execWithStdin(cmd, args, input, options) {
     }
   });
 }
-import { _initPromise, _projectName, _logDir, _v2Writer, streamingState, resetStreamingState, PROFILE_PATH, RETRY_CONFIG_PATH, _retryConfigState, setLivePort, getImLiveText, resetImLiveText, markSessionStart } from './interceptor.js';
+import { _initPromise, _projectName, _logDir, _v2Writer, streamingState, resetStreamingState, turnActive, setTurnActive, PROFILE_PATH, RETRY_CONFIG_PATH, _retryConfigState, setLivePort, getImLiveText, resetImLiveText, markSessionStart } from './interceptor.js';
 import { V2LiveFeed } from './lib/v2/live-feed.js';
 import { filterClientsByViewProject, projectOfSessionDir, resolveActivityFeedKey } from './lib/v2/view-router.js';
 import { sanitizePathComponent } from './lib/v2/layout.js';
@@ -117,6 +119,7 @@ import { loadPlugins, runWaterfallHook, runParallelHook } from './lib/plugin-loa
 import { CONTEXT_WINDOW_FILE, readModelContextSize } from './lib/context-watcher.js';
 import { sendEventToClients } from './lib/log-watcher.js';
 import { applyTaskEvent, resetTasks, getTaskSnapshot, shouldResetTasks } from './lib/task-state.js';
+import { projectKeyForCwd } from './lib/system-prompt-snapshots.js';
 import { createImLogWatcher } from './lib/im/im-log-watcher.js';
 import { unwatchAllWorkflows } from './lib/workflow-watcher.js';
 import { backupConfigs } from './lib/config-backup.js';
@@ -692,6 +695,15 @@ const deps = {
   stopLogWatch,
   ensureProjectFeed: _ensureProjectFeed,
   scheduleTurnEndBroadcast: _scheduleTurnEndBroadcast,
+  // Raw Stop-hook POST arrival (routes/events.js turnEndNotify): clears the
+  // turn-level loading flag immediately — the debounced `turn_end` SSE frame is
+  // voice-pack semantics and too slow for the spinner. This is the ONLY clear
+  // path when the turn produced no API traffic (hook-only turn), so it must not
+  // wait on the debounce timer.
+  onTurnActiveClear: () => { _setTurnActive(false, null); },
+  // SSE connect replay: a page refresh mid-turn restores the spinner without
+  // waiting for the next streaming tick (routes/events.js events() connect block).
+  getPtyTurnActive: () => turnActive.active,
   // SessionStart hook notify → conversation-switch signal (in-terminal
   // /resume). The source gate + V2Writer re-bind live in the interceptor.
   onSessionStartNotify: markSessionStart,
@@ -703,6 +715,13 @@ const deps = {
     try {
       applyTaskEvent(payload);
       _scheduleTaskUpdateBroadcast();
+      // Turn-level loading: a new main-agent prompt marks the turn active.
+      // Subagent/teammate events are excluded inside the predicate (agentId +
+      // the load-bearing sessionId gate against the currently tracked turn).
+      if (isTurnStartTaskEvent(payload, _turnSessionId)) {
+        _turnSessionId = payload.sessionId;
+        _setTurnActive(true, payload.sessionId);
+      }
     } catch (err) { reportSwallowed('task-state.apply', err); }
   },
   // Session-boundary reset for the task checklist. The gate itself lives in
@@ -814,6 +833,8 @@ const _routes = [
   ...imRoutes,
   ...proxyStatsRoutes,
   ...resumeRoutes,
+  ...sdkContextRoutes,
+  ...sdkMcpStatusRoutes,
 ];
 const dispatch = createDispatcher(_routes);
 
@@ -1380,7 +1401,7 @@ export async function startViewer() {
 async function setupTerminalWebSocket(httpServer) {
   try {
     const { WebSocketServer } = await import('ws');
-    const { writeToPty, writeToPtySequential, writeToPtyFor, writeToPtySequentialFor, resizePty, onPtyData, onPtyExit, getPtyState, getPtyKind, getOutputBuffer, getCurrentWorkspace, spawnShell, findSafeSliceStart, attachPtyFor } = await import('./pty-manager.js');
+    const { writeToPty, writeToPtySequential, writeToPtyFor, writeToPtySequentialFor, resizePty, onPtyData, onPtyExit, getPtyState, getPtyKind, getOutputBuffer, getCurrentWorkspace, spawnShell, findSafeSliceStart, attachPtyFor, listLivePtys } = await import('./pty-manager.js');
     const {
       spawnScratch,
       writeScratch,
@@ -1392,10 +1413,18 @@ async function setupTerminalWebSocket(httpServer) {
       getScratchOutputBuffer,
       getScratchShellBasename,
       getScratchPtyCount,
+      getScratchPtyCountForCwd,
       hasScratchPty,
     } = await import('./scratch-pty-manager.js');
+    const { loadWorkspaces } = await import('./workspace-registry.js');
+    const { resolveViewRoot } = await import('./lib/view-root.js');
     const SCRATCH_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
-    const MAX_SCRATCH_PTYS = 16;
+    // Per-workspace cap = 2x the client's tab cap (8), same semantics as the old global
+    // 16 for single-workspace use. Hidden workspaces keep their PTYs alive by design
+    // (per-workspace tab groups restore on switch-back), so the global bound must be
+    // larger yet finite — each entry is a real shell process.
+    const MAX_SCRATCH_PTYS_PER_CWD = 16;
+    const MAX_SCRATCH_PTYS_TOTAL = 64;
     _writeToPty = writeToPty;
     _onPtyData = onPtyData;
     // Chat-composer busy queue (terminal-hidden PTY mode): holds Enter-while-busy messages
@@ -1473,7 +1502,15 @@ async function setupTerminalWebSocket(httpServer) {
         if (viewProject || viewInstance) {
           try { attachPtyFor({ project: viewProject || undefined, instanceKey: viewInstance || undefined }); } catch { }
         }
+        // SDK multi-session (2026-10-12): remember this connection's viewed project so
+        // broadcastWsMessage can route cwd-tagged SDK frames only to the client(s) watching
+        // that workspace. No ?project= → bound view → receives every project (old behavior).
+        // Set it directly in THIS upgrade's callback (fires once per connection, so reconnects
+        // get re-stamped) — NOT via a one-shot wss.once('connection') listener, which would
+        // only ever stamp the FIRST connection and leave every later/reconnected client
+        // unstamped (receiving all workspaces' frames).
         wss.handleUpgrade(req, socket, head, (ws) => {
+          try { ws._ccvViewProject = viewProject || null; } catch {}
           wss.emit('connection', ws, req);
         });
       } else if (pathname === '/ws/terminal-scratch') {
@@ -1483,17 +1520,53 @@ async function setupTerminalWebSocket(httpServer) {
           socket.destroy();
           return;
         }
-        // 硬上限基于后端 ptys Map 大小（含 running 与已退出未回收），
-        // 已有 id 走重连路径不计入新增配额；防止用户关浏览器后老 pty 仍存活、
-        // 新会话又能开 16 个导致总量翻番的累积膨胀
-        if (!hasScratchPty(scratchId) && getScratchPtyCount() >= MAX_SCRATCH_PTYS) {
-          socket.destroy();
+        // Single upgrade hand-off used by the accept and both reject branches below.
+        const handOffScratch = () => {
+          req.ccvScratchId = scratchId;
+          wssScratch.handleUpgrade(req, socket, head, (ws) => {
+            wssScratch.emit('connection', ws, req);
+          });
+        };
+        // Multi-project (2026-10-12): ?project=/?instance= pin the scratch shell's cwd to
+        // the VIEWED workspace — same resolution as every project-scoped READ route
+        // (resolveViewRoot is sync: fs + sync registry read). No params → bound root.
+        // Accepted: with no instance and a same-basename twin live, the name path can
+        // resolve to the twin's dir (the single-live-PTY rule designed for READ routes);
+        // an unresolvable/ambiguous name takes the fatal-toast path below instead, so a
+        // wrong-cwd spawn is bounded to that deliberate arbitration, never silent.
+        const vr = resolveViewRoot({
+          projectParam: wsUrl.searchParams.get('project'),
+          instanceParam: wsUrl.searchParams.get('instance'),
+          boundCwd: process.env.CCV_PROJECT_DIR || process.cwd(),
+          loadWorkspaces,
+          listLivePtys,
+        });
+        if (!vr.ok) {
+          // Unresolvable/deleted/ambiguous workspace: do NOT bare-destroy — the client
+          // would retry every 2s forever. Complete the upgrade, report once with a fatal
+          // toast (client stops reconnecting), then close. Nothing spawns on this path.
+          req.ccvScratchReject = vr.error || 'workspace unavailable';
+          handOffScratch();
           return;
         }
-        req.ccvScratchId = scratchId;
-        wssScratch.handleUpgrade(req, socket, head, (ws) => {
-          wssScratch.emit('connection', ws, req);
-        });
+        // Normalize once: the bound branch of resolveViewRoot returns the root un-normalized,
+        // named branches realpathSync — without this the same dir can key two buckets.
+        let scratchCwd = vr.root;
+        try { scratchCwd = realpathSync(vr.root); } catch { }
+        // Hard caps (per-workspace + global) on the ptys Map size (running and
+        // exited-not-yet-reaped entries included); an existing id+cwd reconnect is exempt
+        // so it can't be locked out by its own still-alive entry. Rejection goes through
+        // the same fatal-toast hand-off as a resolve failure (never a bare destroy) so the
+        // client stops reconnecting instead of retrying every 2s against a full bucket.
+        if (!hasScratchPty(scratchId, { cwd: scratchCwd })
+          && (getScratchPtyCount() >= MAX_SCRATCH_PTYS_TOTAL
+            || getScratchPtyCountForCwd(scratchCwd) >= MAX_SCRATCH_PTYS_PER_CWD)) {
+          req.ccvScratchReject = 'scratch terminal limit reached';
+          handOffScratch();
+          return;
+        }
+        req.ccvScratchCwd = scratchCwd;
+        handOffScratch();
       } else {
         socket.destroy();
       }
@@ -1561,19 +1634,30 @@ async function setupTerminalWebSocket(httpServer) {
     // scratch 终端 WS：极简版，仅承载 input/resize/data/exit + 显式 kill；不掺杂 hook/SDK/preset
     wssScratch.on('connection', async (ws, req) => {
       const id = req.ccvScratchId;
+      // Resolve-failure branch from the upgrade handler: report once, close, spawn nothing.
+      // The client treats fatal toasts as stop-reconnecting (no 2s retry loop against a
+      // deleted/ambiguous workspace).
+      if (req.ccvScratchReject) {
+        try { ws.send(JSON.stringify({ type: 'toast', message: req.ccvScratchReject, fatal: true })); } catch {}
+        try { ws.close(); } catch {}
+        return;
+      }
+      // cwd resolved once at upgrade time; every manager call for this connection uses it
+      // so no call site can drift to a different (id-only/STARTUP_CWD) bucket.
+      const opts = req.ccvScratchCwd ? { cwd: req.ccvScratchCwd } : undefined;
       // 懒启动 scratch shell（首次连接才 spawn）
       try {
-        if (!getScratchState(id).running) {
-          await spawnScratch(id);
+        if (!getScratchState(id, opts).running) {
+          await spawnScratch(id, opts);
         }
       } catch (err) {
         try { ws.send(JSON.stringify({ type: 'toast', message: `scratch spawn failed: ${err.message}` })); } catch {}
       }
 
-      const state = getScratchState(id);
-      try { ws.send(JSON.stringify({ type: 'state', running: state.running, exitCode: state.exitCode, shellBasename: getScratchShellBasename() })); } catch {}
+      const state = getScratchState(id, opts);
+      try { ws.send(JSON.stringify({ type: 'state', running: state.running, exitCode: state.exitCode, cwd: state.cwd, shellBasename: getScratchShellBasename() })); } catch {}
 
-      const buffer = getScratchOutputBuffer(id);
+      const buffer = getScratchOutputBuffer(id, opts);
       if (buffer) {
         try { ws.send(JSON.stringify({ type: 'data', data: buffer })); } catch {}
       }
@@ -1590,7 +1674,7 @@ async function setupTerminalWebSocket(httpServer) {
       // 调用前须 floodGate.reset()（快照已含 pending 字节，残留会在快照后回灌重复）。
       const sendScratchResync = () => {
         if (ws.readyState !== 1) return;
-        try { ws.send(JSON.stringify({ type: 'data-resync', data: getScratchOutputBuffer(id) })); } catch {}
+        try { ws.send(JSON.stringify({ type: 'data-resync', data: getScratchOutputBuffer(id, opts) })); } catch {}
       };
       const resyncReqGate = createResyncNudgeGate({ cooldownMs: RESYNC_REQ_COOLDOWN_MS });
       const bpGate = createBackpressureGate({
@@ -1635,25 +1719,25 @@ async function setupTerminalWebSocket(httpServer) {
 
       const removeDataListener = onScratchData(id, (data) => {
         floodGate.offer(data);
-      });
+      }, opts);
 
       const removeExitListener = onScratchExit(id, (exitCode) => {
         if (ws.readyState === 1) {
           try { ws.send(JSON.stringify({ type: 'exit', exitCode })); } catch {}
         }
-      });
+      }, opts);
 
       ws.on('message', async (raw) => {
         try {
           const msg = JSON.parse(raw.toString());
           if (msg.type === 'input') {
-            const s = getScratchState(id);
+            const s = getScratchState(id, opts);
             if (!s.running) {
-              try { await spawnScratch(id); } catch {}
+              try { await spawnScratch(id, opts); } catch {}
             }
-            writeScratch(id, msg.data);
+            writeScratch(id, msg.data, opts);
           } else if (msg.type === 'resize') {
-            resizeScratch(id, msg.cols, msg.rows);
+            resizeScratch(id, msg.cols, msg.rows, opts);
           } else if (msg.type === 'resync-request') {
             // 客户端 write-queue 积压丢弃后请求快照对齐（utils/terminalWriteQueue.js onTrim）
             if (resyncReqGate.shouldNudge()) {
@@ -1662,7 +1746,7 @@ async function setupTerminalWebSocket(httpServer) {
             }
           } else if (msg.type === 'kill') {
             // 用户主动关闭 tab：杀 pty（killScratch 内部 ptys.delete 后配额自动释放）；前端会随后 close ws
-            killScratch(id);
+            killScratch(id, opts);
           }
         } catch {}
       });
@@ -1672,8 +1756,10 @@ async function setupTerminalWebSocket(httpServer) {
         floodGate.dispose();
         removeDataListener();
         removeExitListener();
-        // pty 本身**不杀**（保留以支持刷新重连），由 kill 消息或 /api/workspaces/stop 触发；
-        // 配额由 ptys Map 自身大小决定，不需在此手动维护连接集合
+        // The pty itself is deliberately NOT killed (kept for refresh-reconnect and for
+        // per-workspace tab-group restore on switch-back); teardown happens via the kill
+        // message or /api/workspaces/stop. Cap accounting is driven by the ptys Map size,
+        // so no connection set is maintained here.
       });
     });
 
@@ -1719,6 +1805,19 @@ async function setupTerminalWebSocket(httpServer) {
         } catch {}
       }
 
+      // SDK multi-session (2026-10-12): replay frames are per-session too. A reconnected
+      // client must only restore the workspace it is VIEWING — otherwise a background
+      // workspace's approval/spinner/queue would pop into the foreground. Filter each
+      // snapshot by this connection's `_ccvViewProject` (bound view / no ?project= → all).
+      const _viewProj = ws._ccvViewProject || null;
+      const _base = (c) => (typeof c === 'string' && c) ? c.replace(/\\/g, '/').split('/').filter(Boolean).pop() : null;
+      const _sdkFrameForView = (frame) => {
+        if (!frame || typeof frame !== 'object') return true;      // no cwd → view-agnostic, replay
+        if (!_viewProj) return true;                               // bound view → all workspaces
+        const fproj = (typeof frame.cwd === 'string' && frame.cwd) ? _base(frame.cwd) : null;
+        return !fproj || fproj === _viewProj;                      // no-cwd frame → replay; else must match
+      };
+
       // Replay SDK 模式 pendings(sdk-manager canUseTool 的 ask/plan/perm):
       // 与上面 perm-hook 同理,但快照来自 sdk-manager(_pendingApprovals)。
       // ask 类带 startedAt/timeoutMs —— 与 ask-hook replay 同款剩余时间重算。
@@ -1726,6 +1825,7 @@ async function setupTerminalWebSocket(httpServer) {
         for (const p of _sdkGetPendingApprovals() || []) {
           if (!p || !p.replay || !p.id) continue;
           const payload = { ...p.replay };
+          if (!_sdkFrameForView(payload)) continue; // 别的工作区的待审批不进本视图
           if (p.kind === 'ask') {
             payload.startedAt = now;           // 让前端按"还剩 remaining"起算
             payload.timeoutMs = p.remainingMs; // 剩余可用时间
@@ -1738,17 +1838,46 @@ async function setupTerminalWebSocket(httpServer) {
       // surface and model info without waiting for the next session.
       if (isSdkMode && _sdkGetInitSnapshot) {
         const initSnap = _sdkGetInitSnapshot();
-        if (initSnap) {
+        if (initSnap && _sdkFrameForView(initSnap)) {
           try { ws.send(JSON.stringify(initSnap)); } catch {}
         }
       }
 
+      // Replay the last sdk-session-state frame so a page refreshed mid-turn restores
+      // the spinner immediately (sdk-init snapshot parity; null → no frame, client
+      // stays at its idle default).
+      if (isSdkMode && _sdkGetSessionStateSnapshot) {
+        const stateSnap = _sdkGetSessionStateSnapshot();
+        if (stateSnap && _sdkFrameForView(stateSnap)) {
+          try { ws.send(JSON.stringify(stateSnap)); } catch {}
+        }
+      }
+
+      // Replay the last sdk-context-usage snapshot so a reconnected panel restores the
+      // latest numbers (null snapshot → no frame, the panel falls back to its HTTP pull).
+      if (isSdkMode && _sdkGetContextUsageSnapshot) {
+        const cuSnap = _sdkGetContextUsageSnapshot();
+        if (cuSnap && _sdkFrameForView(cuSnap)) {
+          try { ws.send(JSON.stringify(cuSnap)); } catch {}
+        }
+      }
+
+      // Replay the last sdk-mcp-status snapshot (sdk-context-usage parity). A null snapshot
+      // sends no frame; the panel then falls back to its HTTP pull.
+      if (isSdkMode && _sdkGetMcpStatusSnapshot) {
+        const mcpSnap = _sdkGetMcpStatusSnapshot();
+        if (mcpSnap && _sdkFrameForView(mcpSnap)) {
+          try { ws.send(JSON.stringify(mcpSnap)); } catch {}
+        }
+      }
+
       // Replay the chat-composer busy queue so a refreshed/reconnected page restores the
       // floating queued-message bubbles (server is the source of truth in both modes).
       {
         const qItems = (isSdkMode && _sdkGetQueueSnapshot) ? _sdkGetQueueSnapshot() : chatQueue.getSnapshot();
         if (Array.isArray(qItems) && qItems.length) {
-          try { ws.send(JSON.stringify({ type: 'queue-state', items: qItems })); } catch {}
+          const qFrame = { type: 'queue-state', items: qItems };
+          if (_sdkFrameForView(qFrame)) { try { ws.send(JSON.stringify(qFrame)); } catch {} }
         }
       }
 
@@ -1877,11 +2006,17 @@ async function setupTerminalWebSocket(httpServer) {
       ws.on('message', async (raw) => {
         try {
           const msg = JSON.parse(raw.toString());
-          // SDK 模式没有 PTY：PTY 专属消息(input/sequential input/resync/resize/attach)一律 no-op,
+          // SDK 模式没有 PTY：PTY 专属消息(input/sequential input/resync/resize)一律 no-op,
           // 否则 'input' 会在无会话时触发 spawnShell() 拉出一个用户看不见的裸 shell。
           // sdk-*/ask-*/perm-*/image-* 等控制消息不受影响。scratch WS 是独立 handler,不受此闸门影响。
-          if (isSdkMode && (msg.type === 'input' || msg.type === 'input-sequential'
-              || msg.type === 'resync-request' || msg.type === 'resize' || msg.type === 'attach')) {
+          // attach 例外:SDK 模式虽无 PTY 可挂,但 attach 携带的是视图身份变更(chip 切换),
+          // 必须刷新该连接的 cwd-路由 stamp,否则广播过滤(_ccvViewProject)停留在旧视图,
+          // 新视图的 sdk-session-state/审批/队列帧会被静默丢弃。
+          if (msg.type === 'attach') {
+            try { ws._ccvViewProject = (typeof msg.project === 'string' && msg.project) || null; } catch {}
+            if (isSdkMode) return;
+          } else if (isSdkMode && (msg.type === 'input' || msg.type === 'input-sequential'
+              || msg.type === 'resync-request' || msg.type === 'resize')) {
             return;
           }
           if (msg.type === 'input') {
@@ -2229,9 +2364,11 @@ async function setupTerminalWebSocket(httpServer) {
               });
             }
           } else if (msg.type === 'sdk-user-message') {
-            // User message in SDK mode — relay to sdk-manager
+            // User message in SDK mode — relay to sdk-manager, addressed to the viewed
+            // workspace's session (multi-session). msg.project is the workspace basename.
             if (_sdkSendUserMessage && msg.text) {
-              _sdkSendUserMessage(msg.text).catch(err => {
+              const anchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined;
+              _sdkSendUserMessage(msg.text, anchor).catch(err => {
                 console.error('[SDK] sendUserMessage error:', err.message);
               });
             }
@@ -2241,7 +2378,8 @@ async function setupTerminalWebSocket(httpServer) {
             // fetch hook → streamingState → SSE), same as PTY mode; sdk-manager
             // no longer emits its own streaming_status.
             if (isSdkMode && _sdkInterruptTurn) {
-              const cancelled = _sdkInterruptTurn() || [];
+              const anchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined;
+              const cancelled = _sdkInterruptTurn(anchor) || [];
               _broadcastApprovalCloses(cancelled, 'Turn interrupted');
             } else {
               // sdk-interrupt 收到却没生效：客户端按 props.sdkMode 发了中断，但本端不是 SDK 模式或
@@ -2257,7 +2395,8 @@ async function setupTerminalWebSocket(httpServer) {
             if (typeof msg.text === 'string' && msg.text) {
               if (isSdkMode) {
                 if (_sdkSendUserMessage) {
-                  _sdkSendUserMessage(msg.text).catch(err => {
+                  const anchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined;
+                  _sdkSendUserMessage(msg.text, anchor).catch(err => {
                     console.error('[SDK] queue-message relay error:', err.message);
                   });
                 }
@@ -2273,7 +2412,10 @@ async function setupTerminalWebSocket(httpServer) {
             if (qid) {
               if (isSdkMode) {
                 if (_sdkSendQueuedNow) {
-                  try { _broadcastApprovalCloses(_sdkSendQueuedNow(qid) || [], 'Queued message sent now'); }
+                  // Multi-session: address the bubble's own workspace (the viewed project), not
+                  // the global active session — bubbles are cwd-scoped, the action must match.
+                  const qAnchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined;
+                  try { _broadcastApprovalCloses(_sdkSendQueuedNow(qid, qAnchor) || [], 'Queued message sent now'); }
                   catch (err) { reportSwallowed('server.queue-send-now', err); }
                 }
               } else {
@@ -2284,7 +2426,7 @@ async function setupTerminalWebSocket(httpServer) {
             const qid = (typeof msg.id === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(msg.id)) ? msg.id : null;
             if (qid) {
               if (isSdkMode) {
-                if (_sdkRemoveQueued) { try { _sdkRemoveQueued(qid); } catch (err) { reportSwallowed('server.queue-remove', err); } }
+                if (_sdkRemoveQueued) { const qAnchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined; try { _sdkRemoveQueued(qid, qAnchor); } catch (err) { reportSwallowed('server.queue-remove', err); } }
               } else {
                 try { chatQueue.remove(qid); } catch (err) { reportSwallowed('server.queue-remove', err); }
               }
@@ -2293,7 +2435,7 @@ async function setupTerminalWebSocket(httpServer) {
             // Session/workspace switch: drop the parked queue WITHOUT interrupting a running
             // turn. (Stop semantics live elsewhere: PTY queue-suppress, SDK sdk-interrupt.)
             if (isSdkMode) {
-              if (_sdkClearQueued) { try { _sdkClearQueued(); } catch (err) { reportSwallowed('server.queue-clear', err); } }
+              if (_sdkClearQueued) { const qAnchor = (typeof msg.project === 'string' && msg.project) ? { project: msg.project } : undefined; try { _sdkClearQueued(qAnchor); } catch (err) { reportSwallowed('server.queue-clear', err); } }
             } else {
               try { chatQueue.clear(); } catch (err) { reportSwallowed('server.queue-clear', err); }
             }
@@ -2302,6 +2444,10 @@ async function setupTerminalWebSocket(httpServer) {
             // (SDK mode handles this inside sdk-manager.interruptTurn; no PTY queue exists.)
             if (!isSdkMode) {
               try { chatQueue.suppressNextDrain(); } catch (err) { reportSwallowed('server.queue-suppress', err); }
+              // The Stop hook does NOT fire on user interrupt (documented Claude Code
+              // behavior), so the web Stop button must clear the turn-level loading
+              // flag itself or the spinner would outlive the interrupted turn.
+              _setTurnActive(false, null);
             }
           } else if (msg.type === 'image-remove-notify' || msg.type === 'image-upload-notify') {
             // Security: only allow paths within upload directories, reject traversal
@@ -2418,6 +2564,9 @@ export function getAuthConfig() {
 // 的 hook（如 Stop 输入带 `is_final_turn:true`、SDK `result` 带 `subtype:'final'`、
 // 或 `onUserTurnEnd` 回调）就拆掉。拆除时一并 grep 上面 SUNSET-MARKER 标签
 // 定位所有相关代码（server / voicePackPlayer / test / history.md）。
+// 相邻信号说明(2026-10-12):本防抖 `turn_end` 只服务语音包/IM/队列;对话 spinner 的
+// 回合级信号是 `turn_active`(PTY,见下方 Turn-level active state 段)与 SDK 的
+// `sdk-session-state`(WS)。三者语义不同,勿混用。
 //
 // **用户原始语义**：「等 10 秒钟。如果这 10 秒钟内没有新的请求发起，那么就认为
 // 任务真的已经完成了，开始执行播放」—— 隐含：10s 内**有**新请求 → 不算完成 →
@@ -2553,6 +2702,90 @@ function _onStreamingActivated() {
   try { chatQueue.onStreamingActivated(); } catch { /* best-effort */ }
 }
 
+// ── Turn-level active state ────────────────────────────────────────────────
+// `streamingState.active` flips per API call, so the spinner dies during local
+// tool execution between calls (see turn-end-bridge.js header). The turn-level
+// truth lives in interceptor.js (`turnActive` + setTurnActive, shared by PTY
+// hook paths here and the SDK push path in cli.js) so it survives server.js
+// stop/start cycles the same way streamingState does.
+// PTY: set by the UserPromptSubmit hook (task-bridge → /api/task-event),
+// cleared by the raw Stop-hook POST arrival (pre-debounce, pre-SSE) or an
+// explicit user interrupt. No streaming rising-edge fallback by design:
+// housekeeping/telemetry requests after query() end would re-light it for the
+// whole staleness window (see HISTORY note at _scheduleTurnEndBroadcast).
+// Single global flag, same constraint as streamingState (one streaming session
+// per server process). Broadcasts/replay reach only viewers of the BOUND project
+// (more filtered than streaming_status, which broadcasts bound-project state to
+// all clients): a chip-switched parallel view sees no spinner, matching the
+// pre-multi-PTY single-project posture (see the streaming_status timer comment).
+//
+// Heartbeat: while the flag is up, re-broadcast `turn_active` every
+// TURN_ACTIVE_HEARTBEAT_MS. Local tool execution (Bash > 30s builds/tests) produces
+// NO turn-level frames and NO API traffic — without a heartbeat the client's
+// staleness escape cannot distinguish "silent tool" from "lost Stop POST" and
+// would kill the spinner mid-turn. The heartbeat rides the same view-project
+// filter; when the flag drops (Stop POST / interrupt), it stops, and the client
+// backstop still catches a process-death/stuck-server within one window.
+
+// Pure predicate (unit-tested): does this /api/task-event payload mark a new
+// main-agent user prompt? Mirrors task-state.js's shouldResetTasksOnPrompt gate:
+// agentId excludes teammate/subagent when present, but agentId is NOT reliably
+// present on UserPromptSubmit (task-bridge header), so the sessionId check is the
+// load-bearing one — a prompt from a DIFFERENT session than the one we track must
+// not light the main view. currentSessionId follows the same convention as
+// task-state: null window (nothing tracked yet) passes, matching the checklist.
+export function isTurnStartTaskEvent(payload, currentSessionId) {
+  if (!payload || payload.hookEventName !== 'UserPromptSubmit') return false;
+  if (payload.agentId) return false;
+  if (!payload.sessionId) return false;
+  if (currentSessionId && payload.sessionId !== currentSessionId) return false;
+  return true;
+}
+
+const TURN_ACTIVE_HEARTBEAT_MS = 10 * 1000;
+let _turnActiveHeartbeat = null;
+// Session tag of the turn that lit the flag — the load-bearing gate for
+// UserPromptSubmit (agentId is unreliable on this hook; see task-state.js). A Stop
+// POST clears the flag but keeps the tag: the NEXT prompt re-tags, and a stale tag
+// must not reject it (the tag only rejects prompts from a DIFFERENT live session).
+let _turnSessionId = null;
+
+function _armTurnActiveHeartbeat(sessionId) {
+  if (_turnActiveHeartbeat) return; // already armed
+  _turnActiveHeartbeat = setInterval(() => {
+    if (_isStopping || !turnActive.active) { _clearTurnActiveHeartbeat(); return; }
+    _broadcastTurnActive(true, sessionId || null);
+  }, TURN_ACTIVE_HEARTBEAT_MS);
+  if (typeof _turnActiveHeartbeat.unref === 'function') _turnActiveHeartbeat.unref();
+}
+
+function _clearTurnActiveHeartbeat() {
+  if (_turnActiveHeartbeat) { clearInterval(_turnActiveHeartbeat); _turnActiveHeartbeat = null; }
+}
+
+function _broadcastTurnActive(active, sessionId) {
+  if (_isStopping) return;
+  if (!sendEventToClients || clients.length === 0) return;
+  try {
+    sendEventToClients(
+      _filterClientsByViewProject(clients, _projectName || ''),
+      'turn_active',
+      { active, sessionId: sessionId || null, ts: Date.now() },
+    );
+  } catch (err) { reportSwallowed('turn-active.broadcast', err); }
+}
+
+// State-change guard: only broadcast on real transitions (SDK paths share the
+// turn-end entry points and would otherwise emit duplicate frames). The heartbeat
+// is armed/disarmed here so it tracks the flag exactly.
+function _setTurnActive(active, sessionId) {
+  const next = !!active;
+  if (next === turnActive.active) return;
+  setTurnActive(next);
+  if (next) _armTurnActiveHeartbeat(sessionId); else _clearTurnActiveHeartbeat();
+  _broadcastTurnActive(next, sessionId);
+}
+
 // 统一的 streaming-state 观察入口。production polling 和 SDK push 都调它，测试也走它，
 // 不再为「测试桩」单独维护 mirror state（杜绝逻辑漂移）。返回是否检测到 rising edge。
 // `_isStopping` 时直接返回 false：shutdown 中迟到的 tick 不应再去 flush。
@@ -2582,6 +2815,9 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
     _lastCliActive = false;
     _stoppingPromise = null;
     _onTurnEndBroadcastForTests = null;
+    setTurnActive(false);
+    _clearTurnActiveHeartbeat();
+    _turnSessionId = null;
   },
   onBroadcast(fn) { _onTurnEndBroadcastForTests = fn; },
   getPendingKeys() { return [..._pendingTurnEndTimers.keys()]; },
@@ -2589,6 +2825,21 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
   observeStreamingTick(activeNow, mode = 'cli') { return _observeStreamingTick(activeNow, mode); },
   scheduleTurnEnd(sessionId, ts) { _scheduleTurnEndBroadcast(sessionId, ts); },
   getDebounceMs() { return TURN_END_DEBOUNCE_MS; },
+  getPtyTurnActive() { return turnActive.active; },
+  setPtyTurnActive(v, sessionId = null) { _setTurnActive(v, sessionId); },
+  // Routes the payload through the SAME predicate the deps.onTaskEvent closure
+  // uses, so tests exercise the production gate rather than a mirror of it.
+  notifyTaskEvent(payload) {
+    if (isTurnStartTaskEvent(payload, _turnSessionId)) {
+      _turnSessionId = payload?.sessionId || null;
+      _setTurnActive(true, payload?.sessionId);
+    }
+  },
+  // Clear drops the flag but KEEPS the session tag: the next prompt of the SAME
+  // session re-lights fast (tag match), while a foreign session's prompt stays
+  // rejected. The tag resets only on test reset / server stop.
+  clearPtyTurnActive() { _setTurnActive(false, null); },
+  getTurnSessionId() { return _turnSessionId; },
 } : Object.freeze({
   reset() {},
   onBroadcast() {},
@@ -2597,6 +2848,10 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
   observeStreamingTick() { return false; },
   scheduleTurnEnd() {},
   getDebounceMs() { return TURN_END_DEBOUNCE_MS; },
+  getPtyTurnActive() { return false; },
+  setPtyTurnActive() {},
+  notifyTaskEvent() {},
+  clearPtyTurnActive() {},
 });
 
 /**
@@ -2665,6 +2920,7 @@ async function _doStop() {
   // 对称 startViewer：下一次启动后第一次 active 才算 rising edge
   _lastSdkActive = false;
   _lastCliActive = false;
+  _clearTurnActiveHeartbeat();
   // Tear down all IM bridge connections so a stop/start cycle (Electron tab switch, tests) never
   // leaks a second WS to the same app. Idempotent + swallows errors.
   // IM teardown + serverStopping hook 共用一个 3s 总预算（保持串行语义）：
@@ -2729,6 +2985,11 @@ async function _doStop() {
   }
   resetTasks();
   resetStreamingState();
+  // Turn-level flag dies with the server, cleared AFTER connections close (same slot
+  // as resetStreamingState): a task-event arriving during the 3s IM-teardown window
+  // must not re-light the flag for the fresh process's first SSE replay.
+  setTurnActive(false);
+  _clearTurnActiveHeartbeat();
   // 清 interceptor 的 live-port，避免 stop/start 循环（Electron tab 切换 / 测试）间隙内
   // 早期请求向已关闭的端口 POST 丢包。新 startViewer 的 listen 回调会再次 setLivePort
   setLivePort(null);
@@ -2744,9 +3005,21 @@ async function _doStop() {
 /** Broadcast a message to all terminal WS clients (for SDK canUseTool). */
 export function broadcastWsMessage(msg) {
   if (terminalWss) {
+    // SDK multi-session (2026-10-12): a cwd-tagged frame belongs to one workspace's session.
+    // Route it only to clients viewing that workspace (or the bound view with no ?project=),
+    // so a background workspace's approval/queue/spinner never bleeds into the foreground.
+    // Untagged frames keep the historical broadcast-to-all behavior.
+    const frameCwd = (msg && typeof msg === 'object' && typeof msg.cwd === 'string' && msg.cwd) ? msg.cwd : null;
+    // The client stamp is the SANITIZED project key (projectKeyForCwd), so the raw
+    // basename would misroute any cwd with chars outside [a-zA-Z0-9._-] (spaces, CJK)
+    // — every frame for such a workspace would be silently dropped for its viewer.
+    let frameProj = null;
+    if (frameCwd) frameProj = projectKeyForCwd(frameCwd) || null;
     const str = typeof msg === 'string' ? msg : JSON.stringify(msg);
     terminalWss.clients.forEach((c) => {
-      if (c.readyState === 1) try { c.send(str); } catch {}
+      if (c.readyState !== 1) return;
+      if (frameProj && c._ccvViewProject && c._ccvViewProject !== frameProj) return; // other workspace's frame
+      try { c.send(str); } catch {}
     });
   }
   // 仅对 ask 类型转译给主进程；perm-hook-* / sdk-plan-* 维持 inline-only（红线）。
@@ -2802,6 +3075,18 @@ export function setSdkGetPendingApprovals(fn) { _sdkGetPendingApprovals = fn; }
 let _sdkGetInitSnapshot = null;
 export function setSdkGetInitSnapshot(fn) { _sdkGetInitSnapshot = fn; }
 
+/** Reference to sdk-manager's getContextUsageSnapshot (set by cli.js after import). */
+let _sdkGetContextUsageSnapshot = null;
+export function setSdkGetContextUsageSnapshot(fn) { _sdkGetContextUsageSnapshot = fn; }
+
+/** Reference to sdk-manager's getMcpStatusSnapshot (set by cli.js after import). */
+let _sdkGetMcpStatusSnapshot = null;
+export function setSdkGetMcpStatusSnapshot(fn) { _sdkGetMcpStatusSnapshot = fn; }
+
+/** Reference to sdk-manager's getSessionStateSnapshot (set by cli.js after import). */
+let _sdkGetSessionStateSnapshot = null;
+export function setSdkGetSessionStateSnapshot(fn) { _sdkGetSessionStateSnapshot = fn; }
+
 /** Reference to sdk-manager's sendQueuedNow (set by cli.js after import). */
 let _sdkSendQueuedNow = null;
 export function setSdkSendQueuedNow(fn) { _sdkSendQueuedNow = fn; }