cc-viewer 1.7.0 → 1.7.1

package/server/routes/events.js

@@ -6,7 +6,9 @@ import { LOG_DIR } from '../../findcc.js';
 import { streamRawEntriesAsync } from '../lib/log-stream.js';
 import { migrationStatus } from '../lib/v2/migrate-prompt.js';
 import { reportSwallowed } from '../lib/error-report.js';
-import { awaitDrainOrClose } from '../lib/sse-backpressure.js';
+import { sseHead, sseWrite, needsDrain, wireEnd, awaitWireDrain } from '../lib/wire-compress.js';
+import { readV2ColdBundle } from '../lib/v2/meta-rows.js';
+import { readV2SingleEntry } from '../lib/v2/adapter.js';
 import { enrichRawIfNeeded } from '../lib/enrich-plan-input.js';
 import { validateLogPath } from '../lib/log-management.js';
 import { isMainAgentEntry, extractCachedContent } from '../lib/kv-cache-analyzer.js';
@@ -60,7 +62,10 @@ export function sseUpdateBadgeFrame(pending) {
 }
 
 async function events(req, res, parsedUrl, isLocal, deps) {
-  res.writeHead(200, {
+  // 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',
@@ -74,7 +79,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
 
   // SSE 心跳保活：每 30s 发送 ping 事件，防止连接被 OS/代理/浏览器静默断开
   const pingTimer = setInterval(() => {
-    try { res.write('event: ping\ndata: {}\n\n'); } catch {}
+    try { sseWrite(res, 'event: ping\ndata: {}\n\n'); } catch {}
   }, 30000);
 
   // server_config: 给前端推一次性的关键运行时常量，让前端 cooldown / debounce 等
@@ -82,7 +87,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 见 server.js 顶部 turnEnd debounce 的 SUNSET-MARKER 注释。
   // write 失败要 warn：之前静默吞会让 env override 漂移到前端硬常量 10s 而无人发觉。
   try {
-    res.write(`event: server_config\ndata: ${JSON.stringify({ turnEndDebounceMs: deps.turnEndDebounceMs })}\n\n`);
+    sseWrite(res, `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);
   }
@@ -90,7 +95,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 补推「有新版」徽标：复用启动检查缓存的结果，让刷新/新标签页连上即恢复徽标。
   // 置于 deps.clients.push(res) 之前 → 新客户端仅得一份，不与一次性广播竞态。
   const updFrame = sseUpdateBadgeFrame(deps.pendingMajorUpdate);
-  if (updFrame) res.write(updFrame);
+  if (updFrame) sseWrite(res, updFrame);
 
   // 1.7.0 迁移引导（P2）：当前项目仍有未转换的 v1 日志 → 连接即推 migrate_prompt。
   // 是否弹窗由客户端决定（「不再提醒」偏好在客户端；continued=true 时无视 dismissed
@@ -99,7 +104,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   try {
     const mig = migrationStatus(LOG_DIR, _projectName || '');
     if (mig.pending) {
-      res.write(`event: migrate_prompt\ndata: ${JSON.stringify({ ...mig, continued: isContinuedLaunch() })}\n\n`);
+      sseWrite(res, `event: migrate_prompt\ndata: ${JSON.stringify({ ...mig, continued: isContinuedLaunch() })}\n\n`);
     }
   } catch (e) { reportSwallowed('sse.migrate_prompt', e); }
 
@@ -144,9 +149,15 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   const MAINAGENT_SCAN_RING = 3;
   const mainAgentRawRing = [];
 
+  // Wire v3 (V3.S5): flagged + v2 source ⇒ the legacy full-entry cold stream
+  // is REPLACED by rows + native lines (the byte win); the client assembler
+  // rebuilds entries locally. v1 legacy files keep the entry pipeline.
+  const _v3Src = deps.wireV3 ? getLiveLogSource() : null;
+  const v3Cold = !!(_v3Src && existsSync(join(_v3Src, 'journal.jsonl')));
+
   // S6b: the cold-load source is the current v2 session dir when the v2
   // writer is active (adapter stream), else the v1 file.
-  const coldLoadResult = await streamRawEntriesAsync(getLiveLogSource(), async (raw) => {
+  const coldLoadResult = v3Cold ? null : await streamRawEntriesAsync(getLiveLogSource(), async (raw) => {
     // 直接发送原始 JSON 字符串，不做 parse/reconstruct/stringify
     // ExitPlanMode V2 空 input 的条目按需补全 plan / planFilePath，其它原样透传
     if (res.destroyed || !res.writable) return;
@@ -156,9 +167,15 @@ async function events(req, res, parsedUrl, isLocal, deps) {
     // 把 EPIPE 抛穿 async callback；res.on('close'|'error') 已会做 clients 数组清理。
     let drained = true;
     try {
-      res.write('event: load_chunk\ndata: [');
-      drained = res.write(out.includes('\n') ? out.replace(/\n/g, '') : out);
-      res.write(']\n\n');
+      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);
     } catch {
       return;
     }
@@ -166,7 +183,7 @@ async function events(req, res, parsedUrl, isLocal, deps) {
     // helper 内部会在 fulfill 时把另外两个监听器从 res 上摘掉，避免 N 次 backpressure
     // 累积出 N 个 stale close/error listener 触发 MaxListenersExceededWarning。
     if (!drained) {
-      await awaitDrainOrClose(res, deps.SSE_BACKPRESSURE_TIMEOUT_MS);
+      await awaitWireDrain(res, deps.SSE_BACKPRESSURE_TIMEOUT_MS);
     }
   }, {
     since: useIncremental ? sinceParam : undefined,
@@ -190,11 +207,54 @@ async function events(req, res, parsedUrl, isLocal, deps) {
         loadStartData.hasMore = !!hasMore;
         loadStartData.oldestTs = oldestTs || '';
       }
-      res.write(`event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
+      sseWrite(res, `event: load_start\ndata: ${JSON.stringify(loadStartData)}\n\n`);
     },
   });
 
-  res.write(`event: load_end\ndata: {}\n\n`);
+  // Wire v3 (V3.S2/S4/S5): cold rows + native lines land BEFORE load_end so
+  // the flagged client can assemble its window in the same load cycle. The
+  // legacy chunk stream was skipped above (v3Cold) — load_start is emitted
+  // here from the rows metadata instead.
+  if (v3Cold) {
+    try {
+      const src = _v3Src;
+      // Single-flighted bundle (review P2-b): a reconnect storm coalesces to
+      // one journal fold + one native read per (dir, window). `since` scopes
+      // an incremental reconnect to the delta window (review P1-2) — the
+      // client upserts those rows instead of resetting the list.
+      const { meta, native } = await readV2ColdBundle(src, {
+        limit: useLimit ? effectiveLimit : 0,
+        since: useIncremental ? sinceParam : null,
+      });
+      // Build every payload BEFORE load_start so it can carry the exact byte
+      // total — the client renders a real received/total progress (the legacy
+      // wire's per-entry count-up has no per-frame granularity here).
+      const rowsPayload = JSON.stringify({ rows: meta.rows, totalCount: meta.totalCount, hasMore: meta.hasMore, oldestTs: meta.oldestTimestamp, incremental: !!useIncremental });
+      let v3Bytes = rowsPayload.length;
+      for (const p of native.convPayloads) v3Bytes += p.length;
+      for (const p of native.respPayloads) v3Bytes += p.length;
+      const loadStartData = { total: meta.totalCount, incremental: !!useIncremental, v3Bytes };
+      if (useLimit) {
+        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`);
+      // 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
+      // synthesis-gated orphan — earlier candidates then provide the values.
+      const mains = meta.rows.filter((r) => r.mainAgent && !r.inProgress).slice(-3);
+      for (const m of mains) {
+        const detail = await readV2SingleEntry(src, { seq: m.seq, sessionId: m.sessionId });
+        if (detail && detail.entry) mainAgentRawRing.push(detail.entry);
+      }
+    } catch (err) { reportSwallowed('sse.v2_requests', err); }
+  }
+
+  sseWrite(res, `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
@@ -227,10 +287,10 @@ async function events(req, res, parsedUrl, isLocal, deps) {
 
   // 发送最新 MainAgent 的 KV-Cache 和 context_window
   if (latestKvCache) {
-    res.write(`event: kv_cache_content\ndata: ${JSON.stringify(latestKvCache)}\n\n`);
+    sseWrite(res, `event: kv_cache_content\ndata: ${JSON.stringify(latestKvCache)}\n\n`);
   }
   if (latestContextWindow) {
-    res.write(`event: context_window\ndata: ${JSON.stringify(latestContextWindow)}\n\n`);
+    sseWrite(res, `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
@@ -250,7 +310,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 };
-        res.write(`event: context_window\ndata: ${JSON.stringify(data)}\n\n`);
+        sseWrite(res, `event: context_window\ndata: ${JSON.stringify(data)}\n\n`);
       }
     } catch { }
   }
@@ -274,16 +334,26 @@ async function events(req, res, parsedUrl, isLocal, deps) {
 // API endpoint
 async function requests(req, res) {
   // 异步流式 JSON 数组输出，不做 reconstruct，发原始条目
-  res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.write('[');
-  let first = true;
-  await streamRawEntriesAsync(getLiveLogSource(), (raw) => {
-    if (!first) res.write(',');
-    res.write(enrichRawIfNeeded(raw));
-    first = false;
-  });
-  res.write(']');
-  res.end();
+  // flush:false —— whole-stream response: the client parses the array only
+  // when complete, so per-macrotask flush boundaries would just cost ratio.
+  sseHead(req, res, 200, { 'Content-Type': 'application/json' }, { flush: false });
+  try {
+    sseWrite(res, '[');
+    let first = true;
+    await streamRawEntriesAsync(getLiveLogSource(), (raw) => {
+      if (!first) sseWrite(res, ',');
+      sseWrite(res, enrichRawIfNeeded(raw));
+      first = false;
+    });
+    sseWrite(res, ']');
+    wireEnd(res);
+  } catch (err) {
+    // Mid-stream failure (e.g. session dir converted/removed while streaming):
+    // without this catch the rejection propagates through the dispatcher and
+    // kills the process. Headers are already sent — close the stream cleanly.
+    console.error('[api-requests]', err && err.stack || err);
+    wireEnd(res);
+  }
 }
 
 export const eventsRoutes = [

package/server/routes/logs.js

@@ -7,6 +7,7 @@ import { LOG_DIR } from '../../findcc.js';
 import { _projectName, _v2Writer } from '../interceptor.js';
 import { listV2Logs, listLocalLogs, countListedV1Files, deleteLogFiles, validateLogPath } from '../lib/log-management.js';
 import { countLogEntries, streamRawEntriesAsync, readTailEntries } from '../lib/log-stream.js';
+import { sseHead, sseWrite, wireEnd } from '../lib/wire-compress.js';
 import { dirSizeSync } from '../lib/v2/layout.js';
 import { extractV2Zip } from '../lib/log-zip.js';
 import { startConvert, stopConvert, convertStatus } from '../lib/v2/convert-manager.js';
@@ -191,7 +192,9 @@ async function localLog(req, res, parsedUrl) {
     const filePath = validateLogPath(LOG_DIR, file);
     const limitVal = Math.min(parseInt(parsedUrl.searchParams.get('limit'), 10) || 0, 500);
 
-    res.writeHead(200, {
+    // Negotiated Content-Encoding (br|identity) — every subsequent byte MUST
+    // go through sseWrite/wireEnd (see server/lib/wire-compress.js).
+    sseHead(req, res, 200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
       'Connection': 'keep-alive',
@@ -200,24 +203,24 @@ async function localLog(req, res, parsedUrl) {
     if (limitVal > 0) {
       // 尾部加载模式：跳过 countLogEntries，只读文件末尾
       const { entries, hasMore, oldestTimestamp, estimatedTotal } = await readTailEntries(filePath, { limit: limitVal });
-      res.write(`event: load_start\ndata: ${JSON.stringify({ total: estimatedTotal, incremental: false, hasMore, oldestTs: oldestTimestamp })}\n\n`);
+      sseWrite(res, `event: load_start\ndata: ${JSON.stringify({ total: estimatedTotal, incremental: false, hasMore, oldestTs: oldestTimestamp })}\n\n`);
       for (const raw of entries) {
-        res.write('event: load_chunk\ndata: [');
-        res.write(raw.includes('\n') ? raw.replace(/\n/g, '') : raw);
-        res.write(']\n\n');
+        sseWrite(res, 'event: load_chunk\ndata: [');
+        sseWrite(res, raw.includes('\n') ? raw.replace(/\n/g, '') : raw);
+        sseWrite(res, ']\n\n');
       }
     } else {
       // 全量加载模式（向后兼容）
       const total = await countLogEntries(filePath);
-      res.write(`event: load_start\ndata: ${JSON.stringify({ total, incremental: false })}\n\n`);
+      sseWrite(res, `event: load_start\ndata: ${JSON.stringify({ total, incremental: false })}\n\n`);
       await streamRawEntriesAsync(filePath, (raw) => {
-        res.write('event: load_chunk\ndata: [');
-        res.write(raw.includes('\n') ? raw.replace(/\n/g, '') : raw);
-        res.write(']\n\n');
+        sseWrite(res, 'event: load_chunk\ndata: [');
+        sseWrite(res, raw.includes('\n') ? raw.replace(/\n/g, '') : raw);
+        sseWrite(res, ']\n\n');
       });
     }
-    res.write(`event: load_end\ndata: {}\n\n`);
-    res.end();
+    sseWrite(res, `event: load_end\ndata: {}\n\n`);
+    wireEnd(res);
   } catch (err) {
     // 如果 headers 未发送，返回 JSON 错误；否则关闭连接
     // 落 stderr 让用户在 ccv 终端能看到具体原因（SSE onerror 在客户端
@@ -228,7 +231,7 @@ async function localLog(req, res, parsedUrl) {
       res.writeHead(status, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: err.message }));
     } else {
-      res.end();
+      wireEnd(res); // flush the encoder trailer if the stream was compressed
     }
   }
 }

package/server/routes/v2.js

@@ -0,0 +1,60 @@
+// Wire v3 routes (V3.S1+): on-demand single-entry detail for the metadata-row
+// request list. Registered unconditionally — harmless while CCV_WIRE_V3 is off
+// (nothing calls it), so the route itself needs no flag gate.
+import { join } from 'node:path';
+import { LOG_DIR } from '../../findcc.js';
+import { validateLogPath } from '../lib/log-management.js';
+import { resolveSessionDirName } from '../lib/v2/session-select.js';
+import { readV2SingleEntry } from '../lib/v2/adapter.js';
+import { sseHead, sseWrite, wireEnd } from '../lib/wire-compress.js';
+
+/**
+ * GET /api/v2-entry?file=v2:<project>/<dirToken>&seq=N[&sid=<uuid>]
+ * dirToken is normally the session dir basename (`<ts>_<uuid>`); a bare UUID
+ * (the client only holds `_seqEpoch="v2:<uuid>"`) is resolved to the basename
+ * BEFORE validateLogPath — validation expects an existing directory path.
+ * `sid` disambiguates teammate rows: the fold runs over the leader dir, the
+ * target is keyed (sid, seq); omitted = match seq in any folded session.
+ */
+async function v2Entry(req, res, parsedUrl) {
+  const file = parsedUrl.searchParams.get('file') || '';
+  const seq = parseInt(parsedUrl.searchParams.get('seq'), 10);
+  const sid = parsedUrl.searchParams.get('sid') || null;
+  const m = /^v2:([^/]+)\/([^/]+)$/.exec(file);
+  if (!m || !Number.isInteger(seq) || seq < 0) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'expected file=v2:<project>/<session>&seq=<n>' }));
+    return;
+  }
+  try {
+    // UUID → dir-basename resolution first (rename/-c adoption safe), then the
+    // same path validation every other v2 ref goes through.
+    const [, project, dirToken] = m;
+    const resolved = resolveSessionDirName(join(LOG_DIR, project), dirToken) || dirToken;
+    const sessionDir = validateLogPath(LOG_DIR, `v2:${project}/${resolved}`);
+    const result = await readV2SingleEntry(sessionDir, { seq, sessionId: sid });
+    if (!result) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'entry not found' }));
+      return;
+    }
+    // Whole-stream JSON (like /api/requests): compress without per-event flush.
+    sseHead(req, res, 200, { 'Content-Type': 'application/json' }, { flush: false });
+    // slots are raw JSON strings — compose without re-parse/re-stringify.
+    sseWrite(res, `{"entry":${result.entry},"prevMain":${result.prevMain ?? 'null'}}`);
+    wireEnd(res);
+  } catch (err) {
+    console.error('[v2-entry]', file, err && err.stack || err);
+    if (!res.headersSent) {
+      const status = err.code === 'NOT_FOUND' ? 404 : err.code === 'ACCESS_DENIED' ? 403 : 500;
+      res.writeHead(status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    } else {
+      wireEnd(res);
+    }
+  }
+}
+
+export const v2Routes = [
+  { method: 'GET', match: 'exact', path: '/api/v2-entry', handler: v2Entry },
+];

package/server/routes/workspaces.js

@@ -17,6 +17,7 @@ const RESUME_FLAGS = new Set(['-r', '--resume']);
 import { unwatchAllWorkflows } from '../lib/workflow-watcher.js';
 import { readClaudeProjectModel } from '../lib/context-watcher.js';
 import { countLogEntries, streamRawEntriesAsync } from '../lib/log-stream.js';
+import { sseWrite } from '../lib/wire-compress.js';
 
 function workspacesList(req, res, parsedUrl, isLocal, deps) {
   import('../workspace-registry.js').then(async ({ getWorkspaces }) => {
@@ -91,7 +92,7 @@ function workspacesLaunch(req, res, parsedUrl, isLocal, deps) {
       const startedPayload = `event: workspace_started\ndata: ${JSON.stringify({ projectName: result.projectName, path: wsPath, claudeProjectModel: readClaudeProjectModel(wsPath) })}\n\n`;
       deps.clients.forEach(client => {
         try {
-          client.write(startedPayload);
+          sseWrite(client, startedPayload);
         } catch {}
       });
 
@@ -102,15 +103,15 @@ function workspacesLaunch(req, res, parsedUrl, isLocal, deps) {
       const wsReloadSource = getLiveLogSource();
       const wsReloadTotal = await countLogEntries(wsReloadSource);
       deps.clients.forEach(client => {
-        try { client.write(`event: load_start\ndata: ${JSON.stringify({ total: wsReloadTotal, incremental: false })}\n\n`); } catch {}
+        try { sseWrite(client, `event: load_start\ndata: ${JSON.stringify({ total: wsReloadTotal, incremental: false })}\n\n`); } catch {}
       });
       await streamRawEntriesAsync(wsReloadSource, (raw) => {
         deps.clients.forEach(client => {
-          try { client.write('event: load_chunk\ndata: ['); client.write(raw.replace(/\n/g, '')); client.write(']\n\n'); } catch {}
+          try { sseWrite(client, 'event: load_chunk\ndata: ['); sseWrite(client, raw.replace(/\n/g, '')); sseWrite(client, ']\n\n'); } catch {}
         });
       });
       deps.clients.forEach(client => {
-        try { client.write(`event: load_end\ndata: {}\n\n`); } catch {}
+        try { sseWrite(client, `event: load_end\ndata: {}\n\n`); } catch {}
       });
 
       // 1.7.0 迁移引导（P2）：切进的项目仍有未转换 v1 日志 → 对存量连接广播
@@ -119,7 +120,7 @@ function workspacesLaunch(req, res, parsedUrl, isLocal, deps) {
         const mig = migrationStatus(LOG_DIR, result.projectName || '');
         if (mig.pending) {
           const frame = `event: migrate_prompt\ndata: ${JSON.stringify({ ...mig, continued: isContinuedLaunch() })}\n\n`;
-          deps.clients.forEach(client => { try { client.write(frame); } catch {} });
+          deps.clients.forEach(client => { try { sseWrite(client, frame); } catch {} });
         }
       } catch (e) { reportSwallowed('sse.migrate_prompt', e); }
 
@@ -185,7 +186,7 @@ function workspacesStop(req, res, parsedUrl, isLocal, deps) {
     // 通知所有 SSE 客户端
     deps.clients.forEach(client => {
       try {
-        client.write(`event: workspace_stopped\ndata: {}\n\n`);
+        sseWrite(client, `event: workspace_stopped\ndata: {}\n\n`);
       } catch {}
     });
 

package/server/server.js

@@ -9,6 +9,7 @@ import { execFile, exec, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { Worker } from 'node:worker_threads';
 import { isPathContained } from './lib/file-api.js';
+import { sseWrite, isWireV3Enabled } from './lib/wire-compress.js';
 import { setEntry as askStoreSetEntry, deleteEntry as askStoreDeleteEntry, pruneStale as askStorePruneStale, markAnswered as askStoreMarkAnswered, markCancelled as askStoreMarkCancelled, loadAskStore as askStoreLoad } from './lib/ask-store.js';
 import { ASK_TIMEOUT_MS, ASK_WAITER_REAP_INTERVAL_MS, ASK_WAITER_LIVENESS_MS } from './lib/ask-constants.js';
 import { reapDeadAskWaiters, sweepOrphanedDiskAsks } from './lib/ask-reaper.js';
@@ -33,6 +34,7 @@ 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 { v2Routes } from './routes/v2.js';
 import { askPermRoutes } from './routes/ask-perm.js';
 import { teamRoutes } from './routes/team.js';
 import { authRoutes } from './routes/auth.js';
@@ -315,6 +317,22 @@ const MAX_POST_BODY = 10 * 1024 * 1024;
 // 防止长会话把数十 MB 历史一次性灌进浏览器导致 renderer OOM。
 // 用户显式 ?limit=0 可恢复全量加载（power-user 逃生口）。
 const DEFAULT_EVENTS_LIMIT = 1000;
+// Wire v3 flag (V3.S6: DEFAULT ON) — read ONCE at startup; a read/UI-shape
+// toggle the server and client must agree on per process, not per request
+// (unlike wire-compress's per-connection content negotiation). Broadcast to
+// clients via the server_config SSE frame; tests inject deps.wireV3 directly.
+// CCV_WIRE_V3=0 (or =off) is the escape hatch back to the legacy full-entry
+// wire — kept (not deleted) for one release cycle before the legacy live UI
+// path is removed; v1 legacy FILES always use the legacy pipeline regardless.
+const WIRE_V3 = isWireV3Enabled(process.env.CCV_WIRE_V3);
+// Build stamp broadcast in server_config: a tab that survives a server
+// upgrade reconnects with a STALE JS bundle that lacks the new wire's
+// listeners (silent empty session). The fresh bundle compares this stamp on
+// reconnect and reloads itself on mismatch (review P2-a; heals upgrades from
+// this version onward — older bundles predate the guard).
+const SERVER_BUILD = (() => {
+  try { return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version || ''; } catch { return ''; }
+})();
 // SSE 单客户端 backpressure 容忍上限：连续未排空 > 此时长则视为 dead 客户端剔除。
 // 调高至 30s：大会话首屏/重连重放时，渲染器（尤其 Windows 浏览器，大 DOM layout 更重）
 // 可能短暂忙到来不及排空 socket。过早剔除会触发「断开→EventSource 自动重连→再次重放」
@@ -427,6 +445,7 @@ function _ensureV2LiveFeed() {
       runParallelHook,
       // The stats worker's v2 units are session dirs (stats-worker.js v9).
       notifyStatsWorker,
+      wireV3: WIRE_V3,
     });
   }
   return _v2LiveFeed;
@@ -591,6 +610,8 @@ const deps = {
   WINDOWS_RESERVED_NAMES,
   DEFAULT_EVENTS_LIMIT,
   SSE_BACKPRESSURE_TIMEOUT_MS,
+  wireV3: WIRE_V3,
+  serverBuild: SERVER_BUILD,
   IGNORED_PATTERNS,
   isCliMode,
   isSdkMode,
@@ -623,6 +644,7 @@ const _routes = [
   ...workspacesRoutes,
   ...expertRoutes,
   ...eventsRoutes,
+  ...v2Routes,
   ...askPermRoutes,
   ...teamRoutes,
   ...dingtalkRoutes,
@@ -2375,7 +2397,7 @@ if (!isWorkspaceMode) {
             pendingMajorUpdate = { version: result.remoteVersion, source: result.status };
             const payload = JSON.stringify(pendingMajorUpdate);
             clients.forEach(client => {
-              try { client.write(`event: update_major_available\ndata: ${payload}\n\n`); } catch { }
+              try { sseWrite(client, `event: update_major_available\ndata: ${payload}\n\n`); } catch { }
             });
           } else if (result.status === 'upgrading_in_background') {
             console.error(`[CC Viewer] background upgrade to ${result.remoteVersion} started (active after next launch)`);

package/src/utils/apiUrl.js

@@ -0,0 +1,26 @@
+// 从 URL 中提取 LAN 访问 token，附加到所有 API 请求 / WebSocket 握手
+const _urlToken = new URLSearchParams(window.location.search).get('token');
+
+// 反向代理子路径部署: 从 <base> 标签或 SSR 注入的全局变量读取 base path，
+// 使 API/WebSocket 等动态请求也能正确路由到代理后端。
+export function getBasePath() {
+  if (typeof window !== 'undefined' && window.__CCV_BASE_PATH__) return window.__CCV_BASE_PATH__;
+  if (typeof document === 'undefined' || !document.querySelector) return '';
+  const base = document.querySelector('base');
+  if (base && base.href) return base.getAttribute('href');
+  return '';
+}
+
+// 把 token 追加到任意 URL（HTTP path 或 ws:// 完整 URL 皆可）。无 token 时原样返回。
+// WS 握手必须也带 token —— 否则启用鉴权后远程「?token=」终端会被 socket.destroy()。
+export function appendToken(url) {
+  if (!_urlToken) return url;
+  const sep = url.includes('?') ? '&' : '?';
+  return `${url}${sep}token=${_urlToken}`;
+}
+
+export function apiUrl(path) {
+  const base = getBasePath();
+  const fullPath = base ? base.replace(/\/$/, '') + path : path;
+  return appendToken(fullPath);
+}

package/src/utils/askFallback.js

@@ -0,0 +1,21 @@
+// Decision helper for ApprovalModal's fallback AskQuestionForm.
+//
+// The Question modal body is normally filled by the transcript tool_use block
+// portaling an AskQuestionForm into the modal's ask slot (see askPortalMatcher.js).
+// When no block portals in — a stale replayed ask whose block is old history, or a
+// fresh ask arriving before transcript ingest — the modal would show an empty body.
+// The fallback renders a form directly from the authoritative pending-ask broadcast.
+//
+// Contract: `slotOccupied` is DOM occupancy of the ask slot (MutationObserver on
+// childList + sync initial read); `graceElapsed` flips true ASK_FALLBACK_GRACE_MS
+// after the ask becomes visible, giving the real portal one commit cycle so fresh
+// asks never flash the fallback before the portaled form mounts.
+
+export const ASK_FALLBACK_GRACE_MS = 120;
+
+export function shouldRenderAskFallback({ isAskActive, slotOccupied, graceElapsed, questions, submitHandler }) {
+  if (!isAskActive || slotOccupied || !graceElapsed) return false;
+  if (!Array.isArray(questions) || questions.length === 0) return false;
+  if (typeof submitHandler !== 'function') return false;
+  return true;
+}

package/src/utils/askOptionDesc.js

@@ -0,0 +1,55 @@
+import { isPlaceholderAskId } from './askPortalMatcher.js';
+
+// AskUserQuestion options[].description is schema-optional; centralize fallback
+// so AskQuestionForm and ChatMessage recap stay aligned.
+
+export function optionAriaLabel(opt) {
+  if (!opt || opt.label == null) return '';
+  return opt.description
+    ? `${opt.label}: ${opt.description}`
+    : String(opt.label);
+}
+
+export function hasOptionDescription(opt) {
+  return Boolean(opt && opt.description);
+}
+
+// Pick the questions the interactive AskUserQuestion card actually renders.
+//
+// The modal body is filled by the inline tool_use block (reconstructed from the log
+// stream) portaling into the modal's askSlot — it does not read pendingAsk.questions
+// (the authoritative copy broadcast over WS ask-hook-pending / sdk-ask-pending, fully
+// parsed server-side before the hook fires) directly. During streaming of a large
+// payload there is a window where the modal is already open but the reconstructed
+// block's input is still partial JSON. Crucially, partial-JSON parsing materializes
+// the outer questions[] array shape before the element content arrives, so the
+// streamed copy can be HOLLOW AT EQUAL LENGTH (e.g. two question objects with empty
+// text/options while big options[].preview strings are still streaming — the
+// 2026-07-04 blank-popup regression; a strictly-longer length heuristic missed it).
+//
+// So: for the currently pending ask (toolId === lastPendingAskId, id-matched), always
+// prefer the authoritative copy. It is complete by construction, and the submit path
+// (handleAskQuestionSubmit in askFlowController) maps answer indices through the same
+// authoritative _askHookQuestions copy — rendering it keeps rendered indices aligned
+// with the mapping array. Historical blocks never match lastPendingAskId and always
+// keep their own streamed questions (history view unchanged).
+//
+// Legacy/no-id servers use placeholder pendingAsk ids ('__ask__', 'ask_<ts>_<rnd>')
+// that can never equal the real tool_use id. There the authoritative copy is only
+// borrowed when the streamed render would otherwise be completely empty — it can fill
+// a blank popup but never override visible content (a stale legacy pendingAsk must
+// not inject a previous ask's questions over a rendered one).
+export function resolveAskQuestions(streamedQuestions, toolId, lastPendingAskId, pendingAsk) {
+  const streamed = Array.isArray(streamedQuestions) ? streamedQuestions : [];
+  if (!pendingAsk || toolId == null || toolId !== lastPendingAskId) {
+    return streamed;
+  }
+  const idMatches = pendingAsk.id === toolId;
+  if (!idMatches && !(isPlaceholderAskId(pendingAsk.id) && streamed.length === 0)) {
+    return streamed;
+  }
+  const authoritative = Array.isArray(pendingAsk.questions) ? pendingAsk.questions : [];
+  if (authoritative.length === 0) return streamed; // defensive: WS handlers guarantee non-empty
+  if (streamed.length > authoritative.length) return streamed; // never shrink (belt-and-braces)
+  return authoritative;
+}

package/src/utils/askPortalMatcher.js

@@ -0,0 +1,54 @@
+/**
+ * Portal 决策：判断 inline AskQuestionForm（在 ChatMessage 里渲染的某条 tool_use）
+ * 是否应该 createPortal 到 ApprovalModal 的 askSlot。
+ *
+ * activeAskId 三种合法形态（与 server 端协议绑定，改一边必须改另一边）：
+ *
+ *   1. `toolu_xxx` — SDK 模式 / 新版 Claude Code 透传的真实 tool_use_id
+ *      → 走 strict 匹配：activeAskId === toolId
+ *
+ *   2. `__ask__` — LEGACY 老 server（pre-Map 协议）的单槽占位
+ *      → 走 owner 通配：仅 owner-idx 锁定的那条 ChatMessage（lastPendingAskId === toolId）命中
+ *
+ *   3. `ask_${ts}_${rnd}` — 老 Claude Code PreToolUse hook payload 不带 tool_use_id 时
+ *      server.js 自生成的 fallback id（修复 modal 标题在但内容空白的根因）
+ *      → 走 owner 通配：与 __ask__ 同语义
+ *
+ * 协议锚点：
+ *   - server 端 fallback id 生成：server.js（搜索 `ask_${Date.now()}` 定位）
+ *   - server 端 LEGACY 占位推送：server.js 推送 ask-hook-pending 事件时 id 为 '__ask__'
+ *   - 前端 setState pendingAsk：src/components/chat/ChatView.jsx
+ *
+ * 改 server 端 fallback id 格式时，必须同步更新此文件的 isFallbackId 检测。
+ */
+
+const FALLBACK_ID_PREFIX = 'ask_';
+const LEGACY_PLACEHOLDER_ID = '__ask__';
+
+/**
+ * True when the given pending-ask id is a placeholder that can never equal a real
+ * tool_use id: the LEGACY single-slot '__ask__' or a server-generated 'ask_<ts>_<rnd>'
+ * fallback id. Consumers (e.g. resolveAskQuestions) use this to apply the same
+ * owner-wildcard semantics as shouldPortalAskForm on the legacy paths.
+ */
+export function isPlaceholderAskId(id) {
+  return id === LEGACY_PLACEHOLDER_ID
+    || (typeof id === 'string' && id.startsWith(FALLBACK_ID_PREFIX));
+}
+
+/**
+ * @param {*} activeAskId   ApprovalPortalContext.Consumer 提供的 activeAskId（modal 当前 active ask 的 id）
+ * @param {*} toolId        当前 ChatMessage 里 tool_use 块的 id（toolu_xxx）
+ * @param {*} lastPendingAskId  ChatMessage 收到的 owner-idx 派生信号；非 owner 永远为 null
+ * @returns {boolean} true 表示当前 ChatMessage 应该 portal 到 askSlot
+ */
+export function shouldPortalAskForm(activeAskId, toolId, lastPendingAskId) {
+  if (activeAskId == null) return false;
+  // strict：SDK / 新 Claude Code 真实 tool_use_id
+  if (String(activeAskId) === String(toolId)) return true;
+  // owner 通配：__ask__（LEGACY 老 server）∪ ask_*（server fallback）
+  // 必须同时满足 owner-idx 锁定（lastPendingAskId === toolId），否则会让历史所有真实 toolId
+  // 都被通配命中，重现旧的双份 portal bug
+  if (isPlaceholderAskId(activeAskId) && lastPendingAskId === toolId) return true;
+  return false;
+}