cc-viewer 1.9.4 → 1.9.5

package/server/pty-manager.js

@@ -1,4 +1,5 @@
 import { resolveNativePath, LOG_DIR } from '../findcc.js';
+import { normalizeSessionCwd } from './lib/v2/layout.js';
 import { fileURLToPath } from 'node:url';
 import { join, dirname, sep } from 'node:path';
 import { chmodSync, statSync } from 'node:fs';
@@ -1215,6 +1216,58 @@ export function setPtySessionIdForInstance(instanceKey, sessionId) {
   return true;
 }
 
+/**
+ * Resolve a claude session uuid to its owning PTY record's scope identity, for
+ * producer-side event routing (2026-10 per-workspace SSE channels). Returns
+ * null for a dead record: sidToKey survives killPtyFor (only respawn/overwrite
+ * /reap clear it, see setPtySessionId), so without the liveness gate a just-
+ * closed workspace's turn-end/task frames would resolve to a corpse scope.
+ * @param {string} sessionId
+ * @returns {{instanceKey: string, cwd: string|null, project: string}|null}
+ */
+export function resolvePtyForSession(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  const key = sidToKey.get(sessionId);
+  if (!key) return null;
+  const rec = ptys.get(key);
+  if (!rec || !rec.ptyProcess) return null;
+  const cwd = (typeof rec.cwd === 'string' && rec.cwd) || null;
+  return { instanceKey: key, cwd, project: cwd ? projectKeyForCwd(cwd) : '' };
+}
+
+/**
+ * Resolve a cwd to its SINGLE live PTY instanceKey, for hook-scope resolution
+ * (2026-10 per-workspace SSE channels). A hook payload that only carries cwd
+ * (no sessionId hit) would otherwise degrade to project-level scope — and
+ * `filterClientsByScope` treats instance=null as "every viewer of the project",
+ * over-delivering the frame to a same-cwd twin. Upgrade to the exact instance
+ * ONLY when exactly one live record owns this cwd; with two live twins there
+ * is no honest pick, so the caller keeps project-level (today's behavior).
+ * Matches on the record's persistent `cwd` (never realpath'd — both sides stay
+ * in the same path space), after a lexical normalize so a trailing slash or
+ * `/tmp` vs `/private/tmp` alias from the hook's stdin can't split the match.
+ * @param {string} cwd
+ * @returns {string|null} the sole live instanceKey, or null (none / ambiguous)
+ */
+export function resolveInstanceForCwd(cwd) {
+  if (typeof cwd !== 'string' || !cwd) return null;
+  let norm;
+  try { norm = normalizeSessionCwd(cwd); } catch { norm = cwd; }
+  if (!norm) return null;
+  let found = null;
+  for (const [k, rec] of ptys) {
+    if (!rec || !rec.ptyProcess) continue; // LIVE only — a dead record must not claim the scope
+    const recCwd = rec.cwd || null;
+    if (!recCwd) continue;
+    let recNorm;
+    try { recNorm = normalizeSessionCwd(recCwd); } catch { recNorm = recCwd; }
+    if (recNorm !== norm) continue;
+    if (found !== null) return null; // a second live twin — ambiguous, keep project-level
+    found = k;
+  }
+  return found;
+}
+
 /**
  * Resolve the PTY-map key for a chat send anchor. Order:
  *   1. project + sessionId TOGETHER: sessionId is trusted only when the record

package/server/routes/ask-perm.js

@@ -2,7 +2,7 @@
 import { loadAskStore, consumeIfFinal as askStoreConsumeIfFinal, markCancelled as askStoreMarkCancelled } from '../lib/ask/ask-store.js';
 import { runWaterfallHook, runParallelHook } from '../lib/plugin-loader.js';
 import { sendEventToClients } from '../lib/log-watcher.js';
-import { filterClientsByViewProject } from '../lib/v2/view-router.js';
+import { filterClientsByScope } from '../lib/v2/view-router.js';
 import { _projectName } from '../interceptor.js';
 
 function pendingAsks(req, res, parsedUrl, isLocal, deps) {
@@ -517,12 +517,16 @@ function streamChunk(req, res, parsedUrl, isLocal, deps) {
       // Multi-project (2026-10): stamp the SOURCE project so the broadcast can
       // be routed only to clients VIEWING that project — an unfiltered
       // broadcast let project A's typewriter render inside project B's view
-      // (the SSE cross-project bleed). `entry._resumeProject` is the emitting
-      // claude's own project (self-reported via x-ccv-project-dir); absent ⇒
-      // the bound project (legacy no-header producer).
-      const sourceProject = (typeof entry._resumeProject === 'string' && entry._resumeProject)
-        ? entry._resumeProject
-        : (_projectName || '');
+      // (the SSE cross-project bleed). The interceptor now stamps the chunk
+      // with the emitting claude's self-reported project/instance (x-ccv-
+      // project-dir / x-ccv-instance); `entry._resumeProject` is the fallback
+      // for older producers, and absent everything ⇒ the bound project.
+      const sourceProject = (typeof entry.project === 'string' && entry.project)
+        ? entry.project
+        : (typeof entry._resumeProject === 'string' && entry._resumeProject)
+          ? entry._resumeProject
+          : (_projectName || '');
+      const sourceInstance = (typeof entry.instance === 'string' && entry.instance) ? entry.instance : null;
       const _streamChunkPayload = {
         timestamp: entry.timestamp,
         url: entry.url,
@@ -533,9 +537,10 @@ function streamChunk(req, res, parsedUrl, isLocal, deps) {
         // ignore it.
         sessionId: typeof entry.sessionId === 'string' ? entry.sessionId : null,
         project: sourceProject,
+        instance: sourceInstance,
       };
       sendEventToClients(
-        filterClientsByViewProject(deps.clients, sourceProject, _projectName || ''),
+        filterClientsByScope(deps.clients, sourceProject, sourceInstance, _projectName || ''),
         'stream-progress',
         _streamChunkPayload,
       );

package/server/routes/events.js

@@ -7,6 +7,7 @@ import { streamRawEntriesAsync } from '../lib/log-stream.js';
 import { migrationStatus } from '../lib/v2/migrate-prompt.js';
 import { reportSwallowed } from '@ccv/core/error-report';
 import { sseHead, sseWrite, needsDrain, wireEnd, awaitWireDrain, isWireV3Enabled } from '../lib/wire-compress.js';
+import { scopeKeyForProducer } from '../lib/scope-router.js';
 import { readV2ColdBundle } from '../lib/v2/meta-rows.js';
 import { readV2SingleEntry } from '../lib/v2/adapter.js';
 import { resolveSessionDirName, latestMainSessionDir } from '../lib/v2/session-select.js';
@@ -49,11 +50,17 @@ function turnEndNotify(req, res, parsedUrl, isLocal, deps) {
       res.end(JSON.stringify({ error: 'malformed JSON body' }));
       return;
     }
-    deps.scheduleTurnEndBroadcast(payload.sessionId || null, payload.ts || Date.now(), payload.transcriptPath || null);
+    // Per-workspace: resolve the emitting claude's scope (sid→PTY first, cwd
+    // fallback, bound last) so the turn_end frame and the immediate turn-active
+    // clear land on exactly one workspace's viewers.
+    const scope = typeof deps.resolveScopeForHookPayload === 'function'
+      ? deps.resolveScopeForHookPayload(payload)
+      : { project: '', instance: null };
+    deps.scheduleTurnEndBroadcast(payload.sessionId || null, payload.ts || Date.now(), payload.transcriptPath || null, scope);
     // Turn-level loading clears on the RAW Stop POST arrival — the debounced
     // `turn_end` SSE frame (voice-pack semantics) would keep the spinner up for
     // the whole debounce window. Idempotent on the server side.
-    try { deps.onTurnActiveClear?.(); }
+    try { deps.onTurnActiveClear?.(scope); }
     catch (err) { reportSwallowed('turn-end-notify.turn-active-clear', err); }
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: true }));
@@ -151,6 +158,28 @@ function taskEventNotify(req, res, parsedUrl, isLocal, deps) {
   });
 }
 
+/**
+ * Parse the /events query into the canonical params object — the SINGLE parser shared by
+ * both transports (SSE: from the request URL; WS mux: from the `open` frame's raw query
+ * string fed through `new URL('?'+qs, …)`), so the two can never drift. Keeping `?limit`
+ * absent-vs-0 distinct (absent ⇒ DEFAULT_EVENTS_LIMIT, explicit 0 ⇒ "all") is load-bearing.
+ */
+export function paramsFromParsedUrl(parsedUrl) {
+  const g = (k) => parsedUrl.searchParams.get(k);
+  const sidRaw = g('sid');
+  const instanceRaw = g('instance');
+  const limitRaw = g('limit');
+  return {
+    sid: (typeof sidRaw === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sidRaw)) ? sidRaw : null,
+    project: g('project'),
+    instance: (typeof instanceRaw === 'string' && /^ccv-[0-9a-f]+$/.test(instanceRaw)) ? instanceRaw : null,
+    since: g('since'),
+    cc: parseInt(g('cc'), 10) || 0,
+    limitRaw,                       // keep the raw string so "absent" (null) ≠ "explicit 0"
+    limitGiven: limitRaw !== null,
+  };
+}
+
 // SSE endpoint
 // 构造「有新版」徽标的 SSE 帧（pending = {version, source}）。pending 为空返回 null。
 // 抽成纯函数便于单测帧格式；events() 在新连接上调用它补推，使版本徽标跨刷新持续显示。
@@ -160,15 +189,50 @@ export function sseUpdateBadgeFrame(pending) {
     : null;
 }
 
-async function events(req, res, parsedUrl, isLocal, deps) {
-  // Negotiated Content-Encoding (br|identity). From here on, every byte of
-  // this response MUST go through sseWrite — a bare res.write would corrupt
-  // the compressed stream (see server/lib/wire-compress.js).
-  sseHead(req, res, 200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive',
-  });
+/**
+ * The sink contract — the transport-agnostic target the serve core writes to. An SSE
+ * `res` is adapted with `registrable === res`; a WS-mux logical stream provides its own
+ * shim (which IS the registrable). Both produce the identical (name, data) frame sequence
+ * by construction, because both run through this one function.
+ *   sink.write(text) -> bool     opaque SSE byte-append (a load_chunk is split across 3 writes)
+ *   sink.alive() -> bool         !destroyed && writable
+ *   sink.needsDrain() -> bool    socket-level backpressure signal
+ *   sink.awaitDrain() -> Promise resolves on drain / close / error / 30s timeout
+ *   sink.registrable             the object pushed into deps.clients (gets _ccvView* stamps)
+ */
+
+/**
+ * serveEventStream — THE single implementation of one /events stream, behind both the SSE
+ * route and the WS-mux stream. Resolves after history + kv/context + the broadcast-list
+ * push (so callers awaiting it observe the client registered). Returns { dispose } —
+ * dispose is idempotent: clears the per-stream pingTimer and splices the registrable out
+ * of deps.clients.
+ */
+export async function serveEventStream(sink, params, deps) {
+  const registrable = sink.registrable;
+  let closed = false;
+  let pingTimer = null;
+  const dispose = () => {
+    if (closed) return;
+    closed = true;
+    if (pingTimer) { clearInterval(pingTimer); pingTimer = null; }
+    const idx = deps.clients.indexOf(registrable);
+    if (idx !== -1) deps.clients.splice(idx, 1);
+  };
+  // Register the close hook at the ENTRY (not after the history stream): a client that
+  // disconnects mid-cold-load must still clear the pingTimer and never be pushed — the
+  // previous tail-registration leaked the timer and pushed a dead res in that window.
+  sink.onClose?.(dispose);
+
+  const { sidParam, projectParam, instanceParam, sinceParam, ccParam, limitRaw, limitGiven } = {
+    sidParam: params.sid,
+    projectParam: params.project,
+    instanceParam: params.instance,
+    sinceParam: params.since,
+    ccParam: params.cc,
+    limitRaw: params.limitRaw,
+    limitGiven: params.limitGiven,
+  };
 
   // 注意：不要在此处 clients.push(res)！
   // 必须等 load_end + kv_cache + context_window 全部发送完毕后再加入广播列表，
@@ -177,8 +241,8 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 已处理的 live entry，导致 对话条目"显示→消失→重现"闪烁。
 
   // SSE 心跳保活：每 30s 发送 ping 事件，防止连接被 OS/代理/浏览器静默断开
-  const pingTimer = setInterval(() => {
-    try { sseWrite(res, 'event: ping\ndata: {}\n\n'); } catch {}
+  pingTimer = setInterval(() => {
+    try { sink.write('event: ping\ndata: {}\n\n'); } catch {}
   }, 30000);
 
   // server_config: 给前端推一次性的关键运行时常量，让前端 cooldown / debounce 等
@@ -186,15 +250,15 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 见 server.js 顶部 turnEnd debounce 的 SUNSET-MARKER 注释。
   // write 失败要 warn：之前静默吞会让 env override 漂移到前端硬常量 10s 而无人发觉。
   try {
-    sseWrite(res, `event: server_config\ndata: ${JSON.stringify({ turnEndDebounceMs: deps.turnEndDebounceMs, wireV3: !!deps.wireV3, build: deps.serverBuild || '' })}\n\n`);
+    sink.write(`event: server_config\ndata: ${JSON.stringify({ turnEndDebounceMs: deps.turnEndDebounceMs, wireV3: !!deps.wireV3, build: deps.serverBuild || '' })}\n\n`);
   } catch (err) {
     console.warn(`[server_config] SSE write failed (turnEndDebounceMs=${deps.turnEndDebounceMs}):`, err && err.message);
   }
 
   // 补推「有新版」徽标：复用启动检查缓存的结果，让刷新/新标签页连上即恢复徽标。
-  // 置于 deps.clients.push(res) 之前 → 新客户端仅得一份，不与一次性广播竞态。
+  // 置于 deps.clients.push 之前 → 新客户端仅得一份，不与一次性广播竞态。
   const updFrame = sseUpdateBadgeFrame(deps.pendingMajorUpdate);
-  if (updFrame) sseWrite(res, updFrame);
+  if (updFrame) sink.write(updFrame);
 
   // 1.7.0 迁移引导（P2）：「正在被查看的项目」仍有未转换的 v1 日志 → 连接即推 migrate_prompt。
   // 是否弹窗由客户端决定（「不再提醒」偏好在客户端；continued=true 时无视 dismissed
@@ -203,17 +267,15 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // (declared below from ?project=) scopes the check to the project the client is
   // actually viewing, not always the bound one.
   try {
-    const migProject = parsedUrl.searchParams.get('project') || _projectName || '';
+    const migProject = projectParam || _projectName || '';
     const mig = migrationStatus(LOG_DIR, migProject);
     if (mig.pending) {
-      sseWrite(res, `event: migrate_prompt\ndata: ${JSON.stringify({ ...mig, continued: isContinuedLaunch() })}\n\n`);
+      sink.write(`event: migrate_prompt\ndata: ${JSON.stringify({ ...mig, continued: isContinuedLaunch() })}\n\n`);
     }
   } catch (e) { reportSwallowed('sse.migrate_prompt', e); }
 
-  // 增量加载参数：移动端带 since/cc/project 请求增量数据
-  const sinceParam = parsedUrl.searchParams.get('since');
-  const ccParam = parseInt(parsedUrl.searchParams.get('cc'), 10) || 0;
-  const projectParam = parsedUrl.searchParams.get('project');
+  // 增量加载参数：移动端带 since/cc/project 请求增量数据（sinceParam/ccParam/projectParam
+  // 已在头部从 params 解构）。
   // Multi-project (2026-10): a foreign `?project=` (a parallel-project VIEW)
   // may ALSO resume incrementally — the view-state cache keeps the departing
   // project's lastTs and the client returns with `?project=<p>&since=<lastTs>`.
@@ -224,12 +286,12 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // so the bound-match condition is dropped (cc>0 + a valid date still guard).
   const useIncremental = !!(sinceParam && ccParam > 0 && !isNaN(new Date(sinceParam).getTime()));
 
-  // 分页参数：
+  // 分页参数（limitRaw/limitGiven 已在头部从 params 解构，保留 absent≠0 语义）：
   // - mobile 首次加载传 ?limit=200
   // - bare desktop 请求（无任何 query 参数）默认套 DEFAULT_EVENTS_LIMIT
   // - 显式 ?limit=0 表示"我要全量"（保留旧行为入口）
-  const limitParamRaw = parsedUrl.searchParams.get('limit');
-  const limitParamGiven = limitParamRaw !== null;
+  const limitParamRaw = limitRaw;
+  const limitParamGiven = limitGiven;
   const limitParamNum = parseInt(limitParamRaw, 10);
   let effectiveLimit = 0;
   if (!useIncremental) {
@@ -250,18 +312,10 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   //  - `?project=<p>` (no sid): project <p>'s CURRENT session — the newest
   //    readable, non-teammate session with a main turn — so a parallel-project
   //    chip can be VIEWED without respawning or killing its process.
-  const sidParamRaw = parsedUrl.searchParams.get('sid');
-  const sidParam = (typeof sidParamRaw === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sidParamRaw)) ? sidParamRaw : null;
-  // Multi-instance (2026-10-06): `?instance=<instanceKey>` narrows the view to ONE concurrent
-  // process of a same-cwd project (which otherwise share a basename session dir pool). It
-  // scopes the no-sid cold-load pick (each instance resolves to ITS OWN latest session) and is
-  // stamped on the SSE response so the per-project live feed can route to exactly the clients
-  // viewing that instance. Validated to the minted `ccv-<hex>` shape.
-  const instanceParamRaw = parsedUrl.searchParams.get('instance');
-  const instanceParam = (typeof instanceParamRaw === 'string' && /^ccv-[0-9a-f]+$/.test(instanceParamRaw)) ? instanceParamRaw : null;
+  // sidParam / instanceParam 已在头部从 params 解构并校验（sid=uuid 形状、instance=ccv-<hex>）。
   // `projectParam` (declared above for the incremental guard) doubles as the view
   // scope. The project this client is VIEWING: the explicit ?project= override,
-  // else the bound project. Stamped onto the SSE response so per-project feeds can
+  // else the bound project. Stamped onto the sink registrable so per-project feeds can
   // route live entries to exactly the clients viewing that project.
   const viewedProject = projectParam || (_projectName || '');
   const resolveColdSource = () => {
@@ -316,7 +370,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // it attached — tell the client explicitly so it can toast + auto-detach.
   const sidNotFound = !!(sidParam && !viewColdDir);
   if (sidNotFound) {
-    try { sseWrite(res, `event: sid-not-found\ndata: ${JSON.stringify({ sid: sidParam, ts: Date.now() })}\n\n`); } catch { }
+    try { sink.write(`event: sid-not-found\ndata: ${JSON.stringify({ sid: sidParam, ts: Date.now() })}\n\n`); } catch { }
   }
   // Multi-instance (2026-10-06): an explicit `?instance=` that resolves to NO session dir must
   // likewise NOT silently fall through to the bound project's current session (the instance
@@ -346,7 +400,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
     }
   }
   if (instanceNoSession && !instanceAlive) {
-    try { sseWrite(res, `event: sid-not-found\ndata: ${JSON.stringify({ sid: null, instance: instanceParam, reason: 'instance-no-session', ts: Date.now() })}\n\n`); } catch { }
+    try { sink.write(`event: sid-not-found\ndata: ${JSON.stringify({ sid: null, instance: instanceParam, reason: 'instance-no-session', ts: Date.now() })}\n\n`); } catch { }
   }
   // When a view-scoped dir was requested AND resolved, it replaces the live-source
   // cold load; otherwise fall back to the standard single-current-session source.
@@ -398,30 +452,28 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   const coldLoadResult = v3Cold ? null : await streamRawEntriesAsync(emptyLiveView ? '' : (coldSource || getLiveLogSource({ serveInFlight: !!deps.wireV3 })), async (raw) => {
     // 直接发送原始 JSON 字符串，不做 parse/reconstruct/stringify
     // ExitPlanMode V2 空 input 的条目按需补全 plan / planFilePath，其它原样透传
-    if (res.destroyed || !res.writable) return;
+    if (!sink.alive()) return;
     const out = enrichRawIfNeeded(raw);
     // SSE data 字段不允许裸换行，去除 pretty-printed JSON 的换行
-    // 写入路径整体 try-catch 兜底：连接在 res.write 之间被对端 RST/destroy 时不至于
-    // 把 EPIPE 抛穿 async callback；res.on('close'|'error') 已会做 clients 数组清理。
+    // 写入路径整体 try-catch 兜底：连接在 write 之间被对端 RST/destroy 时不至于
+    // 把 EPIPE 抛穿 async callback；sink 的 close/error 已会做 clients 数组清理。
     let drained = true;
     try {
-      sseWrite(res, 'event: load_chunk\ndata: [');
-      const ok = sseWrite(res, out.includes('\n') ? out.replace(/\n/g, '') : out);
-      sseWrite(res, ']\n\n');
-      // Two pressure signals: `ok` is the write target's input buffer (the
-      // ENCODER on compressed paths — its backlog would otherwise be invisible
-      // because compressed output is 20-80x smaller and rarely fills the
-      // socket), needsDrain(res) is the socket itself. awaitWireDrain below
-      // waits on whichever stream actually applies the pressure.
-      drained = ok && !needsDrain(res);
+      sink.write('event: load_chunk\ndata: [');
+      const ok = sink.write(out.includes('\n') ? out.replace(/\n/g, '') : out);
+      sink.write(']\n\n');
+      // Two pressure signals: `ok` is the write target's input buffer (the ENCODER on
+      // compressed SSE paths), sink.needsDrain() is the socket itself. sink.awaitDrain()
+      // below waits on whichever stream actually applies the pressure.
+      drained = ok && !sink.needsDrain();
     } catch {
       return;
     }
     // 写缓冲满则等 drain（或 close/error/超时任一 fulfill），防止浏览器侧 renderer OOM。
-    // helper 内部会在 fulfill 时把另外两个监听器从 res 上摘掉，避免 N 次 backpressure
+    // helper 内部会在 fulfill 时把另外两个监听器从 sink 上摘掉，避免 N 次 backpressure
     // 累积出 N 个 stale close/error listener 触发 MaxListenersExceededWarning。
     if (!drained) {
-      await awaitWireDrain(res, deps.SSE_BACKPRESSURE_TIMEOUT_MS);
+      await sink.awaitDrain();
     }
   }, {
     since: useIncremental ? sinceParam : undefined,
@@ -451,7 +503,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
         loadStartData.hasMore = !!hasMore;
         loadStartData.oldestTs = oldestTs || '';
       }
-      sseWrite(res, `event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
+      sink.write(`event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
     },
   });
 
@@ -485,10 +537,10 @@ async function events(req, res, parsedUrl, isLocal, deps) {
         loadStartData.hasMore = !!meta.hasMore;
         loadStartData.oldestTs = meta.oldestTimestamp || '';
       }
-      sseWrite(res, `event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
-      sseWrite(res, `event: v2_requests\ndata: ${rowsPayload}\n\n`);
-      for (const payload of native.convPayloads) sseWrite(res, `event: v3_conv\ndata: ${payload}\n\n`);
-      for (const payload of native.respPayloads) sseWrite(res, `event: v3_resp\ndata: ${payload}\n\n`);
+      sink.write(`event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
+      sink.write(`event: v2_requests\ndata: ${rowsPayload}\n\n`);
+      for (const payload of native.convPayloads) sink.write(`event: v3_conv\ndata: ${payload}\n\n`);
+      for (const payload of native.respPayloads) sink.write(`event: v3_resp\ndata: ${payload}\n\n`);
       // kv-cache / context_window sources: rebuild the newest completed
       // mainAgent rows. Depth 3 mirrors the legacy scan-ring fallback (review
       // P2-e): the newest main may lack usage/cached-content or be a
@@ -501,7 +553,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
     } catch (err) { reportSwallowed('sse.v2_requests', err); }
   }
 
-  sseWrite(res, `event: load_end\ndata: {}\n\n`);
+  sink.write(`event: load_end\ndata: {}\n\n`);
 
   // S10a: v2 sources no longer invoke onScan (the two-pass window never
   // stringifies out-of-window entries) — the adapter returns the newest-main
@@ -534,17 +586,21 @@ async function events(req, res, parsedUrl, isLocal, deps) {
 
   // 发送最新 MainAgent 的 KV-Cache 和 context_window
   if (latestKvCache) {
-    sseWrite(res, `event: kv_cache_content\ndata: ${JSON.stringify(latestKvCache)}\n\n`);
+    sink.write(`event: kv_cache_content\ndata: ${JSON.stringify(latestKvCache)}\n\n`);
   }
   if (latestContextWindow) {
-    sseWrite(res, `event: context_window\ndata: ${JSON.stringify(latestContextWindow)}\n\n`);
+    sink.write(`event: context_window\ndata: ${JSON.stringify(latestContextWindow)}\n\n`);
     pushedContextWindow = true;
   }
   // Fallback: no MainAgent in log (e.g. fresh session after -c), read context-window.json.
   // Skipped for an empty live view: CONTEXT_WINDOW_FILE is a single GLOBAL file (not
   // project-scoped), so pushing it here would paint another project's usage onto a
   // brand-new workspace. The first real main turn pushes a genuine measurement instead.
-  if (!pushedContextWindow && !emptyLiveView) {
+  // Per-workspace: the same global-file constraint applies to ANY non-bound view —
+  // a parallel project's viewers must not see the bound project's global fallback
+  // either (their live feed pushes their own measurement on the next main turn).
+  const viewedIsBound = !viewedProject || viewedProject === (_projectName || '');
+  if (!pushedContextWindow && !emptyLiveView && viewedIsBound) {
     try {
       const cwRaw = readFileSync(CONTEXT_WINDOW_FILE, 'utf-8');
       const cwFile = JSON.parse(cwRaw);
@@ -560,7 +616,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
         const effectiveSize = adaptContextWindow(contextSize, inputTokens);
         const usedPct = effectiveSize > 0 ? Math.round((totalTokens / effectiveSize) * 100) : 0;
         const data = { ...cw, context_window_size: effectiveSize, used_percentage: usedPct, remaining_percentage: 100 - usedPct };
-        sseWrite(res, `event: context_window\ndata: ${JSON.stringify(data)}\n\n`);
+        sink.write(`event: context_window\ndata: ${JSON.stringify(data)}\n\n`);
       }
     } catch { }
   }
@@ -569,45 +625,85 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 这样 watcher 的 sendToClients 不会在 load 阶段向该客户端推送 live entry。
   // Stamp the viewed project so per-project feeds route live entries to exactly
   // the clients viewing that project (unset ⇒ the bound project, the default).
-  if (viewedProject) res._ccvViewProject = viewedProject;
+  // Stamped on the REGISTRABLE (the object in deps.clients): for SSE that is the res
+  // itself; for a WS-mux stream it is the per-stream shim (never the shared socket).
+  if (viewedProject) registrable._ccvViewProject = viewedProject;
   // Multi-instance: stamp the viewed instance too, so a same-cwd project's live feed can
   // route each instance's entries to exactly the clients viewing THAT instance (unset ⇒
   // instance-agnostic, the pre-multi-instance default).
-  if (instanceParam) res._ccvViewInstance = instanceParam;
-  deps.clients.push(res);
+  if (instanceParam) registrable._ccvViewInstance = instanceParam;
+  // Push-guard: a client whose close fired mid-cold-load (dispose already ran via the
+  // entry-registered onClose hook) must NOT be re-added to the broadcast list.
+  if (!closed) deps.clients.push(registrable);
 
   // 任务清单快照补推：内存态不在冷加载数据里，页面刷新/重连后横条要等下一次
   // 任务事件才恢复 —— 连接建立即推一份当前快照（空列表也推，清掉客户端残留）。
+  // Per-workspace: the snapshot comes from the VIEWED scope's bucket, so a
+  // parallel view never receives the bound project's checklist (and vice versa).
+  // The scope key is built by the SAME normalizer the producers use (bound
+  // collapses to ''), so a bound view and its producer always meet in one bucket.
+  const _viewScopeKey = scopeKeyForProducer(
+    { project: viewedProject || null, instance: instanceParam || null },
+    _projectName || '',
+  );
   try {
-    const snap = deps.getTaskSnapshot?.();
-    if (snap) sseWrite(res, `event: task_update\ndata: ${JSON.stringify({ sessionId: snap.sessionId, tasks: snap.tasks, ts: Date.now() })}\n\n`);
+    const snap = typeof deps.getTaskSnapshot === 'function' ? deps.getTaskSnapshot(_viewScopeKey) : null;
+    if (snap) sink.write(`event: task_update\ndata: ${JSON.stringify({ sessionId: snap.sessionId, tasks: snap.tasks, ts: Date.now() })}\n\n`);
   } catch (err) { reportSwallowed('sse.task_update.snapshot', err); }
 
   // Turn-level loading replay: a page refresh mid-turn restores the spinner in the
   // same connect block (turn-level state is in-memory only, not in the cold load).
-  // The flag is a bound-project global (same constraint as streamingState), so the
-  // replay only goes to viewers of the bound project — a chip-switched parallel view
-  // must not latch the bound project's spinner. NOTE: this makes turn_active MORE
-  // filtered than streaming_status/turn_end (which broadcast to all); the parallel
-  // view simply shows no spinner for its own project, matching the pre-multi-PTY
-  // single-project posture documented at the streaming_status timer.
+  // Per-workspace: the replay reads the VIEWED scope's bucket, so a parallel
+  // view restores ITS OWN spinner (previously bound-only — the parallel view
+  // simply never showed one).
   try {
-    const viewedIsBound = !viewedProject || viewedProject === (_projectName || '');
-    if (viewedIsBound && deps.getPtyTurnActive?.()) {
-      sseWrite(res, `event: turn_active\ndata: ${JSON.stringify({ active: true, sessionId: null, ts: Date.now() })}\n\n`);
+    // 按返回值区分（不是按存在性）：getTurnActiveFor 存在但查不到该 scope 的
+    // 活跃回合（false/undefined）时，仍回落 legacy 的 bound-only getPtyTurnActive —
+    // 否则一个「存在但恒 false」的退化实现会静默消灭整个连接回放。
+    const _forScope = typeof deps.getTurnActiveFor === 'function' ? deps.getTurnActiveFor(_viewScopeKey) : undefined;
+    const _turnActive = (_forScope !== undefined && _forScope !== null)
+      ? _forScope
+      : (viewedIsBound && deps.getPtyTurnActive?.());
+    if (_turnActive) {
+      sink.write(`event: turn_active\ndata: ${JSON.stringify({ active: true, sessionId: null, ts: Date.now() })}\n\n`);
     }
   } catch (err) { reportSwallowed('sse.turn_active.replay', err); }
 
-  // req.on('close') 在某些异常断连时不一定立即触发；res 端 close/error 兜底保证
-  // 不会在 clients 数组里留下幽灵 res，防止 sendToClients 后续写入触发慢泄漏。
-  const removeFromClients = () => {
-    clearInterval(pingTimer);
-    const idx = deps.clients.indexOf(res);
-    if (idx !== -1) deps.clients.splice(idx, 1);
+  // Close cleanup lives in the entry-registered dispose (sink.onClose at the top): it clears
+  // the pingTimer and splices the registrable out of deps.clients, covering a disconnect at
+  // ANY point (mid-cold-load included — the previous tail-only listener leaked that window).
+  return { dispose };
+}
+
+// /events route handler — a thin SSE-only shell over serveEventStream. It negotiates the
+// wire encoding, adapts the res into the sink contract, and lets the sink's onClose hook
+// register dispose on the transport's req/res close/error. The WS-mux path calls
+// serveEventStream directly with its own shim (whose onClose fires on stream teardown).
+async function events(req, res, parsedUrl, isLocal, deps) {
+  // Negotiated Content-Encoding (br|identity). From here on, every byte of this response
+  // MUST go through sseWrite — a bare res.write would corrupt the compressed stream.
+  sseHead(req, res, 200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+  });
+  // onClose is set BEFORE serveEventStream runs so the entry-registered hook captures it:
+  // serveEventStream calls sink.onClose(dispose) at entry, and we fan dispose out to the
+  // req/res lifecycle. (req close may not fire on some abrupt disconnects; res close/error
+  // backstop guarantees no ghost res is left in clients — preventing a slow write leak.)
+  const sink = {
+    registrable: res,
+    write: (s) => sseWrite(res, s),
+    alive: () => !res.destroyed && res.writable !== false,
+    needsDrain: () => needsDrain(res),
+    awaitDrain: () => awaitWireDrain(res, deps.SSE_BACKPRESSURE_TIMEOUT_MS),
+    onClose: (dispose) => {
+      req.on('close', dispose);
+      res.on('close', dispose);
+      res.on('error', dispose);
+    },
   };
-  req.on('close', removeFromClients);
-  res.on('close', removeFromClients);
-  res.on('error', removeFromClients);
+  await serveEventStream(sink, paramsFromParsedUrl(parsedUrl), deps);
 }
 
 // API endpoint

package/server/routes/resume.js

@@ -262,6 +262,23 @@ function postLiveProcessCloseHandler(req, res, parsedUrl, isLocal, deps) {
       try {
         rebound = _maybeRebindAfterClose(r, deps);
       } catch (err) { reportSwallowed('resume-route.close-rebind', err); }
+      // A PTY killed here fires no Stop POST, so its scope's streaming/turn
+      // bucket would stay `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).
+      // Reap exactly that scope. The producer buckets it under
+      // projectKeyForCwd(cwd) (interceptor scopeKeyForEntry / server
+      // _resolveScopeForHookPayload), NOT the instanceKey — so resolve the same
+      // project-scoped key here, collapsed to '' when it was the bound project.
+      try {
+        if (r.cwd && deps.clearScopeRuntimeFor) {
+          const { projectKeyForCwd } = await import('../lib/system-prompt-snapshots.js');
+          const { normalizeProducerScope, scopeKeyOf } = await import('../lib/scope-router.js');
+          const proj = projectKeyForCwd(r.cwd);
+          const n = normalizeProducerScope({ project: proj, instance: null }, deps.projectName || '');
+          deps.clearScopeRuntimeFor(scopeKeyOf(n.project, n.instance));
+        }
+      } catch (err) { reportSwallowed('resume-route.close-clear-scope', err); }
       // Closing a project/instance must also reap its scratch (mini-terminal) shells, or
       // the viewed-then-switched-away workspace's shells stay alive as orphans until a
       // full workspacesStop/process exit. The killed record's original spawn cwd keys

package/server/routes/session-pin.js

@@ -4,9 +4,10 @@
 //   - GET  /api/session-pin                                  → { pinnedSessionId }
 //   - POST /api/session-pin {pinnedSessionId: string|null}   → persist + SSE-broadcast
 // `_logDir` is the live per-project dir ('' = no active project → GET null / POST no-op).
-import { _logDir } from '../interceptor.js';
+import { _logDir, _projectName } from '../interceptor.js';
 import { readPin, writePin } from '../lib/session-pin-store.js';
 import { sendEventToClients } from '../lib/log-watcher.js';
+import { filterClientsByViewProject } from '../lib/v2/view-router.js';
 
 function sendJson(res, code, obj) {
   res.writeHead(code, { 'Content-Type': 'application/json' });
@@ -28,7 +29,16 @@ function postHandler(req, res, parsedUrl, isLocal, deps) {
     const pinnedSessionId = (typeof raw === 'string' && raw) ? raw : null;
     writePin(_logDir, pinnedSessionId);
     // Broadcast to THIS process's SSE clients so every device stays in sync.
-    sendEventToClients(deps.clients, 'session_pin', { pinnedSessionId });
+    // Per-workspace: the pin file is the BOUND project's (`_logDir`), so the
+    // frame must reach only bound-project viewers — a parallel view's pin must
+    // not be clobbered by it (and vice versa). Payload carries the project so
+    // the client can guard in depth.
+    const bound = _projectName || '';
+    sendEventToClients(
+      filterClientsByViewProject(deps.clients, bound, bound),
+      'session_pin',
+      { pinnedSessionId, project: bound },
+    );
     sendJson(res, 200, { ok: true, pinnedSessionId });
   });
   req.on('error', () => { try { sendJson(res, 400, { error: 'read-error' }); } catch {} });

package/server/routes/workflow-journal.js

@@ -33,10 +33,13 @@ function workflowJournal(req, res, parsedUrl, isLocal, deps) {
     }
 
     // 惰性 arm：只监视真有人在看的 session workflows 目录，后续 journal 覆写经 SSE 实时推送。
+    // Per-workspace: the server-supplied filter routes the frames to only this
+    // project's viewers (absent ⇒ legacy broadcast-to-all).
+    const _wfFilter = typeof deps.filterClientsByViewProject === 'function' ? deps.filterClientsByViewProject : null;
     const wfDir = resolveWorkflowsDir(session, project);
     if (wfDir && deps && Array.isArray(deps.clients)) {
       try {
-        armWorkflowWatch({ workflowsDir: wfDir, sessionId: session, project, clients: deps.clients });
+        armWorkflowWatch({ workflowsDir: wfDir, sessionId: session, project, clients: deps.clients, clientFilter: _wfFilter });
       } catch {}
     }
 
@@ -57,7 +60,7 @@ function workflowJournal(req, res, parsedUrl, isLocal, deps) {
       const live = runDir ? deriveLiveJournal(runDir, runId) : null;
       if (live) {
         if (deps && Array.isArray(deps.clients)) {
-          try { armWorkflowLiveWatch({ runDir, runId, sessionId: session, project, clients: deps.clients }); } catch {}
+          try { armWorkflowLiveWatch({ runDir, runId, sessionId: session, project, clients: deps.clients, clientFilter: _wfFilter }); } catch {}
         }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ ok: true, data: live }));