cc-viewer 1.9.3 → 1.9.5

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';
@@ -33,7 +33,7 @@ import { filesFsRoutes } from './routes/files-fs.js';
 import { searchRoutes } from './routes/search.js';
 import { workspacesRoutes } from './routes/workspaces.js';
 import { expertRoutes } from './routes/expert.js';
-import { eventsRoutes } from './routes/events.js';
+import { eventsRoutes, serveEventStream, paramsFromParsedUrl } from './routes/events.js';
 import { v2Routes } from './routes/v2.js';
 import { askPermRoutes } from './routes/ask-perm.js';
 import { teamRoutes } from './routes/team.js';
@@ -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,9 +97,10 @@ 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, streamingStateFor, turnStateFor, activeStreamingScopes, activeTurnScopes, clearScopeState, clearScopeStateFor } from './interceptor.js';
 import { V2LiveFeed } from './lib/v2/live-feed.js';
-import { filterClientsByViewProject, projectOfSessionDir, resolveActivityFeedKey } from './lib/v2/view-router.js';
+import { filterClientsByViewProject, filterClientsByScope, projectOfSessionDir, resolveActivityFeedKey } from './lib/v2/view-router.js';
+import { BOUND_SCOPE, scopeKeyOf, parseScopeKey, normalizeProducerScope } from './lib/scope-router.js';
 import { sanitizePathComponent } from './lib/v2/layout.js';
 import { maybeResumeConvert } from './lib/v2/convert-manager.js';
 import { LOG_DIR, setLogDir, getClaudeConfigDir, isBrowserOpenSuppressed } from '../findcc.js';
@@ -116,7 +119,8 @@ import { checkAndUpdate } from './lib/updater.js';
 import { loadPlugins, runWaterfallHook, runParallelHook } from './lib/plugin-loader.js';
 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 { applyTaskEvent, resetTasks, resetAllTasks, 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';
@@ -323,6 +327,7 @@ const _editorCleanupTimer = setInterval(() => {
 }, 60000);
 _editorCleanupTimer.unref(); // Don't keep process alive for cleanup
 let terminalWss = null; // WebSocketServer reference for broadcasting
+let streamMux = null;   // /ws/mux dialogue-channel stream mux (SSE stays the fallback)
 let _writeToPty = null; // PTY write function reference (set by setupTerminalWebSocket)
 let _onPtyData = null;  // PTY data listener registration (set by setupTerminalWebSocket)
 export function setWorkspaceClaudeArgs(args) {
@@ -659,6 +664,9 @@ const deps = {
   get retryConfig() { return _retryConfigState; },
   get workspaceLaunched() { return _workspaceLaunched; },
   setWorkspaceLaunched(v) { _workspaceLaunched = v; },
+  // Bound project name (reassignable via interceptor) — getter so routes read
+  // the live value at request time (e.g. resume.js scope-key resolution).
+  get projectName() { return _projectName || ''; },
   get launchCallback() { return _launchCallback; },
   get workspaceClaudeArgs() { return _workspaceClaudeArgs; },
   get workspaceClaudePath() { return _workspaceClaudePath; },
@@ -692,6 +700,24 @@ const deps = {
   stopLogWatch,
   ensureProjectFeed: _ensureProjectFeed,
   scheduleTurnEndBroadcast: _scheduleTurnEndBroadcast,
+  // Full per-scope reap on workspace stop (interceptor buckets + the two
+  // server-side scope maps); a PTY killed here fires no Stop POST, so without
+  // this the killed scopes leak active buckets and stale session tags.
+  resetScopeRuntime: (...args) => resetScopeRuntime(...args),
+  // Single-scope reap for /api/live-processes/close (see that route).
+  clearScopeRuntimeFor: (...args) => clearScopeRuntimeFor(...args),
+  // 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: (scope = null) => { _setTurnActive(false, null, scope); },
+  // 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: (scopeKey = BOUND_SCOPE) => turnStateFor(scopeKey).active,
+  resolveScopeForHookPayload: _resolveScopeForHookPayload,
+  getTurnActiveFor: (scopeKey = BOUND_SCOPE) => turnStateFor(scopeKey).active,
+  filterClientsByViewProject: _filterClientsByViewProject,
   // SessionStart hook notify → conversation-switch signal (in-terminal
   // /resume). The source gate + V2Writer re-bind live in the interceptor.
   onSessionStartNotify: markSessionStart,
@@ -701,18 +727,35 @@ const deps = {
   // path broadcasts the empty snapshot — no separate reset route/hook.
   onTaskEvent: (payload) => {
     try {
-      applyTaskEvent(payload);
-      _scheduleTaskUpdateBroadcast();
+      const sc = _resolveScopeForHookPayload(payload);
+      const key = scopeKeyOf(sc.project, sc.instance);
+      applyTaskEvent(payload, key);
+      _scheduleTaskUpdateBroadcast(key);
+      // 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 of
+      // THIS scope — a foreign workspace's prompt must not light this one).
+      if (isTurnStartTaskEvent(payload, _turnSessionIdByScope.get(key) || null)) {
+        _turnSessionIdByScope.set(key, payload.sessionId);
+        _setTurnActive(true, payload.sessionId, sc);
+      }
     } catch (err) { reportSwallowed('task-state.apply', err); }
   },
   // Session-boundary reset for the task checklist. The gate itself lives in
   // task-state.shouldResetTasks (pure, unit-tested): main-agent startup/clear
   // resets; resume/fork to a different session resets; subagent/teammate
-  // events (payload.agentId) must not wipe the shared list.
+  // events (payload.agentId) must not wipe the shared list. Per-workspace: the
+  // bucket is resolved from the same hook-payload scope — a background
+  // workspace's SessionStart must never clear the bound project's checklist.
   onTaskSessionBoundary: (payload) => {
-    if (!shouldResetTasks(payload, getTaskSnapshot().sessionId)) return;
-    resetTasks();
-    _emitTaskUpdate();
+    const sc = _resolveScopeForHookPayload(payload);
+    const key = scopeKeyOf(sc.project, sc.instance);
+    if (!shouldResetTasks(payload, getTaskSnapshot(key).sessionId)) return;
+    resetTasks(key);
+    // Coalesce with any TaskCreated events that follow in the same SessionStart
+    // batch, and honor the _isStopping freeze — a synchronous _emitTaskUpdate
+    // here would duplicate the batch frame and write to dying connections.
+    _scheduleTaskUpdateBroadcast(key);
   },
   // Per-connection snapshot replay for fresh SSE clients (page refresh /
   // reconnect) — the checklist lives only in memory, not in the cold load.
@@ -814,6 +857,8 @@ const _routes = [
   ...imRoutes,
   ...proxyStatsRoutes,
   ...resumeRoutes,
+  ...sdkContextRoutes,
+  ...sdkMcpStatusRoutes,
 ];
 const dispatch = createDispatcher(_routes);
 
@@ -1068,6 +1113,10 @@ export async function startViewer() {
   _stoppingPromise = null;
   // 加载插件（需要在创建服务器之前，以便通过 hook 获取 HTTPS 证书）
   await loadPlugins();
+  // Per-workspace: warm the pty-manager namespace for the synchronous hook
+  // scope resolver (fire-and-forget; the import completes long before the
+  // first hook POST in practice, and the resolver degrades to cwd/bound hints).
+  _warmScopeResolver().catch(() => {});
 
   // 启动期配置备份:preferences/profile/workspaces → LOG_DIR 外的 cc-viewer-config-backups/
   // (滚动留 10 份)。2026-06-06 事故:配置随 LOG_DIR 整树丢失后无处可恢复。fire-and-forget。
@@ -1380,7 +1429,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 +1441,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
@@ -1417,6 +1474,18 @@ async function setupTerminalWebSocket(httpServer) {
     terminalWss = wss;
     const wssScratch = new WebSocketServer({ noServer: true });
 
+    // /ws/mux dialogue-channel stream mux (WS-mux migration phase B). Each logical stream is
+    // served by routes/events.js's serveEventStream — the SAME implementation behind the SSE
+    // /events route, so a mux stream produces the identical frame sequence (SSE stays the
+    // fallback transport). serveStream takes the sink + the open frame's raw query string,
+    // re-parsed through the SAME paramsFromParsedUrl so the two transports never drift.
+    const { createStreamMuxServer } = await import('./lib/ws-mux.js');
+    streamMux = createStreamMuxServer({
+      WebSocketServer,
+      serveStream: (sink, qs) => serveEventStream(sink, paramsFromParsedUrl(new URL(`http://x/?${qs || ''}`)), deps),
+      reportSwallowed,
+    });
+
     // 多客户端共享 PTY 的尺寸冲突解决：
     // 移动端优先——只要有移动端在线，PTY 始终使用移动端尺寸，
     // PC 端的 resize 仅存储不生效，避免宽屏尺寸导致移动端乱码。
@@ -1473,7 +1542,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 +1560,59 @@ 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 if (pathname === '/ws/mux') {
+        // Dialogue-channel stream mux. Auth already enforced by decideAuth above (token from
+        // ?token= / ccv_auth cookie — tokenInterceptor/appendToken put it on the ws:// URL
+        // exactly like /ws/terminal). No socket-level ?project= stamp: each logical stream
+        // carries its own scope in its `open` frame (one mux socket serves many workspaces).
+        streamMux.handleUpgrade(req, socket, head);
       } else {
         socket.destroy();
       }
@@ -1561,19 +1680,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 +1720,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 +1765,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 +1792,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 +1802,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 +1851,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 +1871,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 +1884,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 +2052,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 +2410,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 +2424,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 +2441,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 +2458,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 +2472,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 +2481,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 +2490,16 @@ 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.
+              // Per-workspace: the message carries the view's project/instance so
+              // the clear lands on exactly that scope (absent ⇒ bound).
+              const qScope = normalizeProducerScope(
+                { project: (typeof msg.project === 'string' && msg.project) || null, instance: (typeof msg.instanceKey === 'string' && msg.instanceKey) || null },
+                _projectName || '',
+              );
+              _setTurnActive(false, null, qScope);
             }
           } else if (msg.type === 'image-remove-notify' || msg.type === 'image-upload-notify') {
             // Security: only allow paths within upload directories, reject traversal
@@ -2418,6 +2616,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 内**有**新请求 → 不算完成 →
@@ -2453,19 +2654,82 @@ const TURN_END_DEBOUNCE_MS = (() => {
 })();
 let _isStopping = false;
 let _lastSdkActive = false;
-let _lastCliActive = false;
+// Per-scope CLI streaming edge state ('' = bound — the legacy single flag).
+const _lastCliActiveByScope = new Map();
 let _onTurnEndBroadcastForTests = null;
 
 function _normalizeKey(sessionId) {
   return (typeof sessionId === 'string' && sessionId) ? sessionId : null;
 }
 
-function _emitTurnEnd(sessionId, ts, transcriptPath = null) {
+// ── Per-workspace scope resolution (2026-10) ────────────────────────────────
+// ONE resolver for every hook-origin frame (turn_end / task_update / turn
+// boundary): the same precedence everywhere so a workspace's frames can never
+// split across two scope buckets. Order:
+//   1. sessionId → the live PTY record that owns it (exact project+instance);
+//   2. payload.cwd → projectKeyForCwd (no instance — hooks report no instance);
+//   3. the bound project ('' sentinel).
+// A dead record / a foreign sessionId yields null from the resolver and falls
+// through to the cwd/bound hints, never to a corpse scope.
+function _resolveScopeForHookPayload(payload) {
+  const p = payload || {};
+  try {
+    const sid = _normalizeKey(p.sessionId);
+    if (sid) {
+      // Lazy import kept out of the module graph (pty-manager pulls node-pty).
+      const pm = _ptyManagerForScope || null;
+      const rec = pm && typeof pm.resolvePtyForSession === 'function' ? pm.resolvePtyForSession(sid) : null;
+      if (rec && rec.project) {
+        return normalizeProducerScope({ project: rec.project, instance: rec.instanceKey || null }, _projectName || '');
+      }
+    }
+  } catch (err) { reportSwallowed('scope.resolve-sid', err); }
+  const cwd = (typeof p.cwd === 'string' && p.cwd) || '';
+  if (cwd) {
+    try {
+      const proj = projectKeyForCwd(cwd);
+      if (proj) {
+        // Upgrade to the exact instance ONLY when exactly one live record owns
+        // this cwd — a project-level frame (instance=null) reaches EVERY viewer
+        // of the project, over-delivering a same-cwd twin's hook to its sibling.
+        // Two live twins → no honest pick → keep project-level (today's behavior,
+        // and the twins' viewers share the cwd anyway).
+        const pm = _ptyManagerForScope || null;
+        const inst = pm && typeof pm.resolveInstanceForCwd === 'function' ? pm.resolveInstanceForCwd(cwd) : null;
+        if (!inst && pm && typeof pm.resolvePtyForSession === 'function') {
+          // Diagnostic only: a project-level frame for a cwd that HAS live
+          // instances is the over-delivery window — observable on real hardware.
+          try {
+            const liveCount = (pm.listLivePtys?.() || []).filter((r) => r && r.cwd && projectKeyForCwd(r.cwd) === proj).length;
+            if (liveCount > 1) reportSwallowed('scope.cwd-ambiguous', new Error(`cwd has ${liveCount} live instances, scope stays project-level`), { cwd: proj });
+          } catch { /* best-effort */ }
+        }
+        return normalizeProducerScope({ project: proj, instance: inst }, _projectName || '');
+      }
+    } catch (err) { reportSwallowed('scope.resolve-cwd', err); }
+  }
+  return { project: '', instance: null };
+}
+
+// Cached pty-manager namespace (first successful lazy import). Scope resolution
+// is synchronous (hook POST handlers are not async); the import completes at
+// startup via _warmScopeResolver, so production never sees the null window.
+let _ptyManagerForScope = null;
+async function _warmScopeResolver() {
+  try { _ptyManagerForScope = await import('./pty-manager.js'); }
+  catch (err) { reportSwallowed('scope.resolver-warm', err); }
+}
+
+function _emitTurnEnd(sessionId, ts, transcriptPath = null, scope = null) {
   const sid = _normalizeKey(sessionId);
   const t = ts || Date.now();
+  const sc = scope || { project: '', instance: null };
   try {
     if (clients.length > 0 && sendEventToClients) {
-      sendEventToClients(clients, 'turn_end', { sessionId: sid, ts: t });
+      const target = sc.project
+        ? filterClientsByScope(clients, sc.project, sc.instance, _projectName || '')
+        : _filterClientsByViewProject(clients, _projectName || '');
+      sendEventToClients(target, 'turn_end', { sessionId: sid, ts: t, project: sc.project || (_projectName || ''), instance: sc.instance || null });
     }
     // Forward the (clean) assistant reply for this turn to whichever IM bridge owns the in-flight
     // turn, if any. Fire-and-forget: a bridge failure must never affect SSE broadcast.
@@ -2483,10 +2747,13 @@ function _emitTurnEnd(sessionId, ts, transcriptPath = null) {
   }
 }
 
-function _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath = null) {
+function _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath = null, scope = null) {
   if (_isStopping) return;
   const sid = _normalizeKey(sessionId);
   const t = ts || Date.now();
+  // Resolve the scope ONCE at POST time: the debounced emit must not re-derive
+  // it from live state that a later switch may have changed.
+  const sc = scope || { project: '', instance: null };
   // chat-queue drain trigger #1: the Stop-hook POST arrival IS the authoritative
   // "query() ended" signal — don't wait out the SSE debounce window (default 10s),
   // or freshly-parked bubbles would sit visibly inert after every turn. The queue's
@@ -2499,10 +2766,10 @@ function _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath = null) {
   if (existing) clearTimeout(existing.timer);
   const timer = setTimeout(() => {
     _pendingTurnEndTimers.delete(sid);
-    _emitTurnEnd(sid, t, transcriptPath);
+    _emitTurnEnd(sid, t, transcriptPath, sc);
   }, TURN_END_DEBOUNCE_MS);
   if (typeof timer.unref === 'function') timer.unref();
-  _pendingTurnEndTimers.set(sid, { timer, ts: t });
+  _pendingTurnEndTimers.set(sid, { timer, ts: t, scopeKey: scopeKeyOf(sc.project, sc.instance) });
 }
 
 // Task-checklist broadcast (task-bridge.js → /api/task-event → deps.onTaskEvent).
@@ -2511,28 +2778,40 @@ function _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath = null) {
 // trailing debounce coalesces multi-task flips (e.g. a batch TaskCreate turn)
 // into one SSE frame.
 const TASK_UPDATE_DEBOUNCE_MS = 120;
-let _taskBroadcastTimer = null;
-
-function _emitTaskUpdate() {
+// Per-workspace: one debounce timer PER SCOPE — a single shared timer let a
+// later scope's schedule clearTimeout an earlier scope's pending frame and
+// drop it whole (a scope with a single TaskCreated then going quiet would
+// never show it). Mirrored after _pendingTurnEndTimers.
+const _taskBroadcastTimers = new Map(); // scopeKey → timer
+
+function _emitTaskUpdate(scopeKey = BOUND_SCOPE) {
+  if (_isStopping) return; // frozen state machine after stop: no late frames
   if (clients.length === 0 || !sendEventToClients) return;
   // Parity with _emitTurnEnd: a broadcast failure must never surface as an
   // uncaught exception from the debounce timer.
   try {
-    const snap = getTaskSnapshot();
-    sendEventToClients(clients, 'task_update', { sessionId: snap.sessionId, tasks: snap.tasks, ts: Date.now() });
+    const snap = getTaskSnapshot(scopeKey);
+    const sc = parseScopeKey(scopeKey);
+    const target = sc.project
+      ? filterClientsByScope(clients, sc.project, sc.instance, _projectName || '')
+      : _filterClientsByViewProject(clients, _projectName || '');
+    sendEventToClients(target, 'task_update', { sessionId: snap.sessionId, tasks: snap.tasks, ts: Date.now(), project: sc.project || (_projectName || ''), instance: sc.instance || null });
   } catch (err) {
     console.warn('[task-update] broadcast failed:', err && err.message);
   }
 }
 
-function _scheduleTaskUpdateBroadcast() {
+function _scheduleTaskUpdateBroadcast(scopeKey = BOUND_SCOPE) {
   if (_isStopping) return;
-  if (_taskBroadcastTimer) clearTimeout(_taskBroadcastTimer);
-  _taskBroadcastTimer = setTimeout(() => {
-    _taskBroadcastTimer = null;
-    _emitTaskUpdate();
+  const key = scopeKey || BOUND_SCOPE;
+  const existing = _taskBroadcastTimers.get(key);
+  if (existing) clearTimeout(existing);
+  const timer = setTimeout(() => {
+    _taskBroadcastTimers.delete(key);
+    _emitTaskUpdate(key);
   }, TASK_UPDATE_DEBOUNCE_MS);
-  if (typeof _taskBroadcastTimer.unref === 'function') _taskBroadcastTimer.unref();
+  if (typeof timer.unref === 'function') timer.unref();
+  _taskBroadcastTimers.set(key, timer);
 }
 
 // 直接丢弃所有 pending —— 用于两条路径：(1) `_doStop` shutdown，(2) rising-edge 新请求
@@ -2543,26 +2822,139 @@ function _cancelAllPendingTurnEndBroadcasts() {
   _pendingTurnEndTimers.clear();
 }
 
-function _onStreamingActivated() {
-  // rising-edge：Claude 又开始新一轮 query()，按用户原始语义「10s 内有新请求 → 不算完成 →
-  // 不播放」，直接 cancel 所有 pending（**不** flush）。这正是用户键入「请等待 10 秒钟」
-  // 的本意：被打断就当没完成。
-  _cancelAllPendingTurnEndBroadcasts();
+// Cancel the pending turn_end broadcasts of ONE scope (rising-edge new request
+// in that scope — by the user's original semantics "a new request within 10s ⇒
+// not really finished ⇒ don't play"). Other scopes' pending timers are
+// untouched (a foreign workspace's turn must never cancel this one's).
+function _cancelPendingTurnEndForScope(scopeKey) {
+  if (_pendingTurnEndTimers.size === 0) return;
+  for (const [sid, entry] of _pendingTurnEndTimers) {
+    if ((entry.scopeKey || BOUND_SCOPE) !== scopeKey) continue;
+    clearTimeout(entry.timer);
+    _pendingTurnEndTimers.delete(sid);
+  }
+}
+
+function _onStreamingActivated(scopeKey = BOUND_SCOPE) {
+  _cancelPendingTurnEndForScope(scopeKey);
   // A new turn also lifts the chat-queue Stop-park: parked bubbles resume auto-draining
   // at the next turn end.
   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).
+// Per-workspace (2026-10): the flag is bucketed per producer scope ('' = the
+// bound project — the legacy singleton). Broadcasts/replay reach exactly that
+// scope's viewers, so a parallel workspace's prompt lights ITS OWN spinner
+// (previously bound-only — a chip-switched parallel view saw none).
+//
+// Heartbeat: while any scope's flag is up, re-broadcast `turn_active` per scope
+// every TURN_ACTIVE_HEARTBEAT_MS (each scope with its own session tag). 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 a scope's
+// flag drops (Stop POST / interrupt) it leaves the iteration, 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;
+// Per-scope session tags of the turns that lit each flag — the load-bearing
+// gate for UserPromptSubmit (agentId is unreliable on this hook; see
+// task-state.js). Keyed by scope ('' = bound). A Stop POST clears the flag but
+// keeps the tag: the NEXT prompt of the same session re-tags, and a stale tag
+// must not reject it (the tag only rejects prompts from a DIFFERENT live
+// session of the SAME scope).
+const _turnSessionIdByScope = new Map();
+
+function _armTurnActiveHeartbeat() {
+  if (_turnActiveHeartbeat) return; // already armed
+  _turnActiveHeartbeat = setInterval(() => {
+    const scopes = activeTurnScopes();
+    if (_isStopping || scopes.length === 0) { _clearTurnActiveHeartbeat(); return; }
+    // Broadcast each scope's own tag — a foreign session's sid must never ride
+    // this scope's heartbeat (the connect replay validates against it).
+    for (const key of scopes) {
+      _broadcastTurnActive(true, _turnSessionIdByScope.get(key) || null, parseScopeKey(key));
+    }
+  }, TURN_ACTIVE_HEARTBEAT_MS);
+  if (typeof _turnActiveHeartbeat.unref === 'function') _turnActiveHeartbeat.unref();
+}
+
+function _clearTurnActiveHeartbeat() {
+  if (_turnActiveHeartbeat) { clearInterval(_turnActiveHeartbeat); _turnActiveHeartbeat = null; }
+}
+
+function _broadcastTurnActive(active, sessionId, scope = null) {
+  if (_isStopping) return;
+  if (!sendEventToClients || clients.length === 0) return;
+  const sc = scope || { project: '', instance: null };
+  try {
+    sendEventToClients(
+      sc.project
+        ? filterClientsByScope(clients, sc.project, sc.instance, _projectName || '')
+        : _filterClientsByViewProject(clients, _projectName || ''),
+      'turn_active',
+      { active, sessionId: sessionId || null, ts: Date.now(), project: sc.project || (_projectName || ''), instance: sc.instance || null },
+    );
+  } 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. Scope defaults to bound
+// ('') — the legacy single-workspace behavior is byte-identical.
+function _setTurnActive(active, sessionId, scope = null) {
+  const sc = scope || { project: '', instance: null };
+  const key = scopeKeyOf(sc.project, sc.instance);
+  const bucket = turnStateFor(key);
+  const next = !!active;
+  if (next === bucket.active) return;
+  bucket.active = next;
+  if (key === BOUND_SCOPE) setTurnActive(next);
+  if (next) _turnSessionIdByScope.set(key, sessionId || null);
+  if (activeTurnScopes().length > 0) _armTurnActiveHeartbeat(); else _clearTurnActiveHeartbeat();
+  _broadcastTurnActive(next, sessionId, sc);
+}
+
 // 统一的 streaming-state 观察入口。production polling 和 SDK push 都调它，测试也走它，
 // 不再为「测试桩」单独维护 mirror state（杜绝逻辑漂移）。返回是否检测到 rising edge。
 // `_isStopping` 时直接返回 false：shutdown 中迟到的 tick 不应再去 flush。
-function _observeStreamingTick(activeNow, mode /* 'cli' | 'sdk' */) {
+// Per-workspace: scopeKey defaults to bound (''); the rising-edge cancel only
+// clears THAT scope's pending turn_end timers. The 'sdk' mode lane has no
+// production caller (tests only) and stays a single bound-scope flag.
+function _observeStreamingTick(activeNow, mode /* 'cli' | 'sdk' */, scopeKey = BOUND_SCOPE) {
   if (_isStopping) return false;
   const isActive = !!activeNow;
-  const wasActive = mode === 'sdk' ? _lastSdkActive : _lastCliActive;
-  if (mode === 'sdk') _lastSdkActive = isActive; else _lastCliActive = isActive;
+  const wasActive = mode === 'sdk' ? _lastSdkActive : (_lastCliActiveByScope.get(scopeKey) || false);
+  if (mode === 'sdk') _lastSdkActive = isActive; else _lastCliActiveByScope.set(scopeKey, isActive);
   if (isActive && !wasActive) {
-    _onStreamingActivated();
+    _onStreamingActivated(scopeKey);
     return true;
   }
   return false;
@@ -2579,16 +2971,38 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
     _cancelAllPendingTurnEndBroadcasts();
     _isStopping = false;
     _lastSdkActive = false;
-    _lastCliActive = false;
+    _lastCliActiveByScope.clear();
     _stoppingPromise = null;
     _onTurnEndBroadcastForTests = null;
+    setTurnActive(false);
+    _clearTurnActiveHeartbeat();
+    _turnSessionIdByScope.clear();
+    clearScopeState();
   },
   onBroadcast(fn) { _onTurnEndBroadcastForTests = fn; },
   getPendingKeys() { return [..._pendingTurnEndTimers.keys()]; },
   setIsStopping(v) { _isStopping = !!v; },
-  observeStreamingTick(activeNow, mode = 'cli') { return _observeStreamingTick(activeNow, mode); },
-  scheduleTurnEnd(sessionId, ts) { _scheduleTurnEndBroadcast(sessionId, ts); },
+  observeStreamingTick(activeNow, mode = 'cli', scopeKey = BOUND_SCOPE) { return _observeStreamingTick(activeNow, mode, scopeKey); },
+  scheduleTurnEnd(sessionId, ts, scope = null) { _scheduleTurnEndBroadcast(sessionId, ts, null, scope); },
   getDebounceMs() { return TURN_END_DEBOUNCE_MS; },
+  getPtyTurnActive(scopeKey = BOUND_SCOPE) { return turnStateFor(scopeKey).active; },
+  setPtyTurnActive(v, sessionId = null, scope = null) { _setTurnActive(v, sessionId, scope); },
+  // 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) {
+    const sc = _resolveScopeForHookPayload(payload);
+    const key = scopeKeyOf(sc.project, sc.instance);
+    if (isTurnStartTaskEvent(payload, _turnSessionIdByScope.get(key) || null)) {
+      _turnSessionIdByScope.set(key, payload?.sessionId || null);
+      _setTurnActive(true, payload?.sessionId, sc);
+    }
+  },
+  // 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(scope = null) { _setTurnActive(false, null, scope); },
+  getTurnSessionId(scopeKey = BOUND_SCOPE) { return _turnSessionIdByScope.get(scopeKey) || null; },
+  resolveScopeForHookPayload(payload) { return _resolveScopeForHookPayload(payload); },
 } : Object.freeze({
   reset() {},
   onBroadcast() {},
@@ -2597,15 +3011,25 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
   observeStreamingTick() { return false; },
   scheduleTurnEnd() {},
   getDebounceMs() { return TURN_END_DEBOUNCE_MS; },
+  getPtyTurnActive() { return false; },
+  setPtyTurnActive() {},
+  notifyTaskEvent() {},
+  clearPtyTurnActive() {},
 });
 
 /**
  * Schedule a debounced turn_end SSE broadcast. **Returns immediately**; actual SSE write
  * happens up to TURN_END_DEBOUNCE_MS later (default 10s; clamped [100,60000]).
- * 详细语义见 SUNSET-MARKER patch-note。
+ * 详细语义见上方 SUNSET-MARKER 注释块（ccv-turn-end-debounce）。
+ * Per-workspace: `cwd` (SDK 'result' path) routes the frame to that workspace's
+ * scope; absent ⇒ the bound project (legacy). (A pre-resolved scope can instead
+ * be passed straight to `_scheduleTurnEndBroadcast` by the hook routes.)
  */
-export function broadcastTurnEnd(sessionId = null, ts = Date.now()) {
-  _scheduleTurnEndBroadcast(sessionId, ts);
+export function broadcastTurnEnd(sessionId = null, ts = Date.now(), transcriptPath = null, cwd = null) {
+  const scope = cwd
+    ? normalizeProducerScope({ project: projectKeyForCwd(cwd) || '', instance: null }, _projectName || '')
+    : null;
+  _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath, scope);
 }
 
 // 流式状态 SSE 推送定时器：检测 streamingState 变化并广播给所有客户端。
@@ -2621,27 +3045,48 @@ let _updateCheckTimer = null;
 // Exported for tests: workspace-mode startViewer defers this timer to initPostLaunch, but
 // lifecycle tests need to drive the streaming_status poll directly (setSdkStreamingState
 // was retired in the wire architecture; the timer reads interceptor's streamingState).
+// One 500ms tick over ONE scope's streaming bucket: rising-edge cancel + the
+// changed-or-active broadcast, routed to exactly that scope's viewers.
+function _streamingTickOnce(scopeKey) {
+  const st = streamingStateFor(scopeKey);
+  const isActive = st.active;
+  const wasActive = _lastCliActiveByScope.get(scopeKey) || false;
+  // 统一走 _observeStreamingTick：内部负责 rising-edge cancel（丢弃该 scope 的
+  // pending turn_end，不 flush）+ 更新该 scope 的 edge 记录。
+  _observeStreamingTick(isActive, 'cli', scopeKey);
+  const changed = wasActive !== isActive;
+  if (changed || isActive) {
+    const data = isActive
+      ? { ...st, elapsed: Date.now() - st.startTime }
+      : { active: false };
+    // Per-workspace: each scope's spinner reaches only its own viewers. The
+    // bound scope ('') rides the legacy project filter — byte-identical to the
+    // old bound-only broadcast when no parallel workspace exists.
+    if (clients.length > 0 && sendEventToClients) {
+      const sc = parseScopeKey(scopeKey);
+      const target = sc.project
+        ? filterClientsByScope(clients, sc.project, sc.instance, _projectName || '')
+        : _filterClientsByViewProject(clients, _projectName || '');
+      sendEventToClients(target, 'streaming_status', { ...data, project: sc.project || (_projectName || ''), instance: sc.instance || null });
+    }
+  }
+}
+
 export function startStreamingStatusTimer() {
   if (_streamingStatusTimer) return;
   _streamingStatusTimer = setInterval(() => {
-    const isActive = streamingState.active;
-    const wasActive = _lastCliActive;
-    // 统一走 _observeStreamingTick：内部负责 rising-edge cancel（丢弃 pending turn_end，不 flush）+ 更新 _lastCliActive。
-    _observeStreamingTick(isActive, 'cli');
-    const changed = wasActive !== isActive;
-    if (changed || isActive) {
-      const data = isActive
-        ? { ...streamingState, elapsed: Date.now() - streamingState.startTime }
-        : { active: false };
-      // Multi-project (2026-10): streamingState is a global singleton tracking the
-      // BOUND project's main process — route the spinner only to clients viewing
-      // that project, so a parallel project's view never shows the bound
-      // project's streaming flag (cross-project spinner bleed). (Per-project
-      // streaming state is a follow-up; today a parallel view simply shows no
-      // spinner, matching the pre-multi-PTY single-project behavior.)
-      if (clients.length > 0 && sendEventToClients) {
-        sendEventToClients(_filterClientsByViewProject(clients, _projectName || ''), 'streaming_status', data);
-      }
+    // Bound scope first (the common single-workspace case is exactly one
+    // iteration), then any parallel-workspace scopes with their own buckets.
+    _streamingTickOnce(BOUND_SCOPE);
+    // Tick active scopes AND every scope we have a last-active edge record for.
+    // activeStreamingScopes() alone only yields active:true buckets — a scope
+    // that just fell inactive would never be ticked again, so its falling edge
+    // is never observed (_lastCliActiveByScope stays true) and the rising-edge
+    // pending-turn_end cancel never fires for it from the second round on.
+    const keys = new Set(activeStreamingScopes());
+    for (const key of _lastCliActiveByScope.keys()) keys.add(key);
+    for (const key of keys) {
+      if (key !== BOUND_SCOPE) _streamingTickOnce(key);
     }
   }, 500);
   _streamingStatusTimer.unref();
@@ -2653,6 +3098,32 @@ export function stopViewer() {
   _stoppingPromise = _doStop();
   return _stoppingPromise;
 }
+
+// Reset every per-scope runtime structure: interceptor scope buckets plus the
+// two server-side maps that must not outlive the workspaces they describe —
+// _turnSessionIdByScope (a stale tag rejects the fresh session's first
+// UserPromptSubmit) and _lastCliActiveByScope (a stale edge breaks the
+// rising-edge cancel). Shared by _doStop and workspacesStop so both stop
+// paths reap the same set.
+export function resetScopeRuntime() {
+  _lastSdkActive = false;
+  _lastCliActiveByScope.clear();
+  _turnSessionIdByScope.clear();
+  try { clearScopeState(); } catch { /* best-effort */ }
+}
+
+// Reap ONE scope's runtime state (a single workspace's PTY was killed via
+// /api/live-processes/close — no Stop POST fires). Without this the killed
+// scope's bucket stays `active:true` forever: the heartbeat/streaming timer
+// keeps re-broadcasting it and the client's 30s staleness escape is
+// perpetually reset by those same frames (the permanent-spinner leak).
+export function clearScopeRuntimeFor(scopeKey) {
+  const key = (typeof scopeKey === 'string' && scopeKey) || BOUND_SCOPE;
+  try { clearScopeStateFor(key); } catch { /* best-effort */ }
+  _turnSessionIdByScope.delete(key);
+  _lastCliActiveByScope.delete(key);
+}
+
 async function _doStop() {
   // _isStopping 设 true 后：①新 schedule 全部入口短路（_scheduleTurnEndBroadcast 入口检查）
   // ②迟到的 streaming tick 也短路（_observeStreamingTick 入口检查）
@@ -2662,9 +3133,12 @@ async function _doStop() {
   // Drop chat-queue timers (rescue / idle poll) so a stop/start cycle never injects a stale
   // queued message into a fresh PTY session.
   try { chatQueue.stop(); } catch { /* best-effort */ }
-  // 对称 startViewer：下一次启动后第一次 active 才算 rising edge
-  _lastSdkActive = false;
-  _lastCliActive = false;
+  _clearTurnActiveHeartbeat();
+  // Per-workspace: tear down every scope bucket plus the per-scope session tags
+  // and streaming-edge records, so a restarted server never replays a stale
+  // spinner / rejects a fresh session's first prompt for a workspace that no
+  // longer exists.
+  resetScopeRuntime();
   // 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 总预算（保持串行语义）：
@@ -2688,6 +3162,13 @@ async function _doStop() {
   // Truncate in place (not `clients = []`) so the array reference stays stable across
   // stop/start cycles — deps.clients holds this same reference.
   clients.length = 0;
+  // Tear down the /ws/mux dialogue mux: server.close()/closeAllConnections() do NOT reach
+  // upgraded WebSocket sockets, so the mux must terminate its own sockets (and its per-socket
+  // ping timers / streams) or an Electron stop/start cycle would leak them.
+  if (streamMux) {
+    try { streamMux.close(); } catch { /* best-effort */ }
+    streamMux = null;
+  }
   if (server) {
     // 销毁所有活跃连接，防止 keep-alive 阻止进程退出
     server.closeAllConnections();
@@ -2723,12 +3204,15 @@ async function _doStop() {
   // empty), but the module-level checklist itself must not leak into the next
   // stop/start cycle — a client connecting before the new session's startup
   // boundary would otherwise get the PREVIOUS session's snapshot.
-  if (_taskBroadcastTimer) {
-    clearTimeout(_taskBroadcastTimer);
-    _taskBroadcastTimer = null;
-  }
-  resetTasks();
+  for (const t of _taskBroadcastTimers.values()) clearTimeout(t);
+  _taskBroadcastTimers.clear();
+  resetAllTasks();
   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 +3228,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 +3298,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; }