cc-viewer 1.6.300 → 1.6.301

package/dist/index.html

@@ -21,7 +21,7 @@
     // 整体显示大小已弃用 CSS zoom：Electron 改用 webFrame.setZoomFactor（首屏抢占见
     // electron/tab-content-preload.js），纯浏览器交由用户用浏览器自带快捷键缩放，故此处不再设 zoom。
   </script>
-  <script type="module" crossorigin src="/assets/index-BXb1GO0R.js"></script>
+  <script type="module" crossorigin src="/assets/index-DpIkVZv8.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/vendor-antd-Bur5ZxWE.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-codemirror-Si44UqBp.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-mdxeditor-Cco3AQJS.js">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-viewer",
-  "version": "1.6.300",
+  "version": "1.6.301",
   "description": "Claude Code Logger visualization management tool",
   "license": "MIT",
   "main": "server.js",

package/server/i18n.js

@@ -448,44 +448,44 @@ const i18nData = {
     "uk": "\nCC Viewer запущено:"
   },
   "server.startedLocal": {
-    "zh": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "en": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "zh-TW": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ko": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ja": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "de": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "es": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "fr": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "it": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "da": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "pl": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ru": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ar": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "no": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "pt-BR": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "th": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "tr": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "uk": "  ➜ Local:   {protocol}://127.0.0.1:{port}"
+    "zh": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "en": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "zh-TW": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ko": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ja": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "de": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "es": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "fr": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "it": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "da": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "pl": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ru": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ar": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "no": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "pt-BR": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "th": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "tr": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "uk": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}"
   },
   "server.startedNetwork": {
-    "zh": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "en": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "zh-TW": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ko": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ja": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "de": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "es": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "fr": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "it": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "da": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "pl": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ru": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ar": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "no": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "pt-BR": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "th": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "tr": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "uk": "  ➜ Network: {protocol}://{ip}:{port}?token={token}"
+    "zh": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "en": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "zh-TW": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ko": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ja": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "de": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "es": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "fr": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "it": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "da": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "pl": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ru": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ar": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "no": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "pt-BR": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "th": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "tr": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "uk": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}"
   },
   "server.passwordActive": {
     "zh": "  🔒 密码保护已开启，密码: {password}",
@@ -527,6 +527,26 @@ const i18nData = {
     "tr": "  ⚠️  Parola boş: uzaktan erişim doğrulama gerektirmez — güvenlik riski",
     "uk": "  ⚠️  Пароль порожній: віддалений доступ не потребує перевірки — загроза безпеці"
   },
+  "basePath.missingLeadingSlash": {
+    "zh": "  ⚠️  CCV_BASE_PATH \"{value}\" 必须以 \"/\" 开头，已忽略。示例：\"/proxy/\"",
+    "en": "  ⚠️  CCV_BASE_PATH \"{value}\" must start with \"/\" — ignored. Use e.g. \"/proxy/\".",
+    "zh-TW": "  ⚠️  CCV_BASE_PATH \"{value}\" 必須以 \"/\" 開頭，已忽略。範例：\"/proxy/\"",
+    "ko": "  ⚠️  CCV_BASE_PATH \"{value}\"는 \"/\"로 시작해야 합니다 — 무시됨. 예: \"/proxy/\"",
+    "ja": "  ⚠️  CCV_BASE_PATH \"{value}\" は \"/\" で始まる必要があります — 無視されました。例: \"/proxy/\"",
+    "de": "  ⚠️  CCV_BASE_PATH \"{value}\" muss mit \"/\" beginnen — ignoriert. Beispiel: \"/proxy/\"",
+    "es": "  ⚠️  CCV_BASE_PATH \"{value}\" debe comenzar con \"/\" — ignorado. Ejemplo: \"/proxy/\"",
+    "fr": "  ⚠️  CCV_BASE_PATH \"{value}\" doit commencer par \"/\" — ignoré. Exemple : \"/proxy/\"",
+    "it": "  ⚠️  CCV_BASE_PATH \"{value}\" deve iniziare con \"/\" — ignorato. Esempio: \"/proxy/\"",
+    "da": "  ⚠️  CCV_BASE_PATH \"{value}\" skal starte med \"/\" — ignoreret. Eksempel: \"/proxy/\"",
+    "pl": "  ⚠️  CCV_BASE_PATH \"{value}\" musi zaczynać się od \"/\" — zignorowano. Przykład: \"/proxy/\"",
+    "ru": "  ⚠️  CCV_BASE_PATH \"{value}\" должен начинаться с \"/\" — проигнорировано. Пример: \"/proxy/\"",
+    "ar": "  ⚠️  يجب أن يبدأ CCV_BASE_PATH \"{value}\" بـ \"/\" — تم التجاهل. مثال: \"/proxy/\"",
+    "no": "  ⚠️  CCV_BASE_PATH \"{value}\" må starte med \"/\" — ignorert. Eksempel: \"/proxy/\"",
+    "pt-BR": "  ⚠️  CCV_BASE_PATH \"{value}\" deve começar com \"/\" — ignorado. Exemplo: \"/proxy/\"",
+    "th": "  ⚠️  CCV_BASE_PATH \"{value}\" ต้องขึ้นต้นด้วย \"/\" — ถูกละเว้น ตัวอย่าง: \"/proxy/\"",
+    "tr": "  ⚠️  CCV_BASE_PATH \"{value}\" \"/\" ile başlamalıdır — yok sayıldı. Örnek: \"/proxy/\"",
+    "uk": "  ⚠️  CCV_BASE_PATH \"{value}\" має починатися з \"/\" — проігноровано. Приклад: \"/proxy/\""
+  },
   "server.auth.loginTitle": {
     "zh": "请输入访问密码",
     "en": "Enter access password",

package/server/lib/base-path.js

@@ -0,0 +1,34 @@
+// CCV_BASE_PATH（反向代理子路径部署）的统一 normalize / validate / strip。
+// 纯函数，无副作用，server.js（HTTP 剥离 / <base> 注入 / WS upgrade）与 cli.js（启动 URL
+// 打印）共用，消除各处复制粘贴的 normalize 逻辑。vite.config.js 不复用（构建期 base 有
+// `undefined→'/'` 的三态语义，与运行时"未设=无前缀"不同，见该文件注释）。
+
+// 规范化 basePath：未设 / 空串 / 根 '/' → ''（无前缀）；其余补尾斜杠（'/proxy' → '/proxy/'）。
+// 尾斜杠是 startsWith 匹配的防歧义关键（'/proxy/' 不会误命中 '/proxyextra/x'）。
+// 缺前导 '/' 的非法值（'proxy/x'）也返回 ''（忽略）——否则注入段会产出相对 <base> 破坏页面；
+// 告警由 validateBasePath 在启动期负责。
+export function normalizeBasePath(raw) {
+  if (!raw || raw === '/' || !raw.startsWith('/')) return '';
+  // 剥裸换行符：含 \n/\r 的值会把 index.html 注入的 JS 字符串断成语法错误（页面级 DoS）
+  return raw.replace(/[\r\n]/g, '').replace(/\/?$/, '/');
+}
+
+// 校验 + 规范化。非空但缺前导 '/'（如 'proxy/x'）属配置错误：startsWith 永不命中、剥离
+// 静默失效。不自动补 '/' —— 自动修正会掩盖与代理侧前缀的错配，更难排查；这里选择
+// 忽略（按无前缀工作）并返回 i18n key 供启动期 console.warn。
+export function validateBasePath(raw) {
+  if (raw && raw !== '/' && !raw.startsWith('/')) {
+    return { ok: false, normalized: '', warning: 'basePath.missingLeadingSlash' };
+  }
+  return { ok: true, normalized: normalizeBasePath(raw), warning: null };
+}
+
+// 从请求 pathname 剥掉 basePath 前缀，保证结果带前导 '/'（路由表按 '/api/...' 匹配）。
+// slice(length - 1) 让 normalizedBase 的尾斜杠留作结果的前导斜杠：
+//   stripBasePath('/proxy/api/x', '/proxy/') → '/api/x'
+//   stripBasePath('/proxy/',      '/proxy/') → '/'
+// 不匹配（含裸前缀 '/proxy' 无尾斜杠的访问）原样返回，由调用方按 SPA/404 处理。
+export function stripBasePath(pathname, normalizedBase) {
+  if (!normalizedBase || !pathname.startsWith(normalizedBase)) return pathname;
+  return pathname.slice(normalizedBase.length - 1) || '/';
+}

package/server/lib/log-watcher.js

@@ -249,10 +249,16 @@ function _scheduleDebouncedRead(fileState) {
   }, FSWATCH_DEBOUNCE_MS);
 }
 
+// 测试注入缝(仿 updater fetchImpl 惯例):替换轮询分支的 watchFile 实现。
+// 真实 watchFile 的 stat 基线与 500ms 间隔在 CI 慢机上不可确定性驱动(基线竞态曾致
+// 25s 全程静默 flake),单测注入假实现手动触发回调即可零时序覆盖。生产恒为 node:fs 原版。
+let _watchFileImpl = watchFile;
+export function __setWatchFileImplForTests(fn) { _watchFileImpl = fn || watchFile; }
+
 function _fallbackToPolling(fileState) {
   if (fileState.polling) return;
   fileState.polling = true;
-  watchFile(fileState.logFile, { interval: 500 }, () => {
+  _watchFileImpl(fileState.logFile, { interval: 500 }, () => {
     _readDelta(fileState);
   });
 }

package/server/lib/term-signals.js

@@ -0,0 +1,80 @@
+// Windows Ctrl+C 退出链三层防御（macOS/Linux 行为不变）。
+// 背景：cli.js / server.js 的 SIGINT handler 都是 `doCleanup → .finally(process.exit)` 形态，
+// 注册 handler 后 Node 不再默认退出 —— 链上任何一环挂住（node-pty ConPTY kill 同步挂起、
+// IM bridge teardown await 无超时、SIGINT 事件被 ConPTY 吞掉）进程就永不退出，
+// 即 Windows 用户报告的 "Ctrl+C 完全无反应"。
+// 三函数全部依赖注入（仿 log-watcher __setWatchFileImplForTests 惯例），纯逻辑可单测。
+
+import { spawnSync as _spawnSync } from 'node:child_process';
+import { emitKeypressEvents as _emitKeypressEvents } from 'node:readline';
+
+// 把 `doCleanup → exit` 包装成幂等 + 双保险的 cleanup：
+//   首次触发：先武装 watchdog（watchdogMs 后强制 exit(130)，unref 不滞留事件循环），
+//             再 try/catch 跑 doCleanup（同步抛错不阻断退出），完成后 exit()。
+//   二次触发（用户连按 Ctrl+C）：立即 exit(130)，不再等优雅收尾。
+// watchdogMs 默认 5s：_doStop 内 IM teardown + serverStopping hook 共用一个 3s 总预算
+// （见 server.js _doStop 的合并 race），其后还有 rename temp jsonl（用户数据）要顺序
+// 执行 —— watchdog 必须 > 3s 总预算 + rename 余量，避免中途截断。
+export function createHardenedCleanup({ doCleanup, exit = process.exit, setTimeoutImpl = setTimeout, watchdogMs = 5000 }) {
+  let invoked = false;
+  return function hardenedCleanup() {
+    if (invoked) { exit(130); return; }
+    invoked = true;
+    const watchdog = setTimeoutImpl(() => exit(130), watchdogMs);
+    if (watchdog && typeof watchdog.unref === 'function') watchdog.unref();
+    try {
+      const r = doCleanup();
+      if (r && typeof r.then === 'function') {
+        r.then(() => exit(), () => exit(130));
+      } else {
+        // 同步 doCleanup：完成即退（统一契约"doCleanup 结束 → exit"；当前所有调用方
+        // 都返回 promise 走上面分支，此分支为前向兼容）
+        exit();
+      }
+    } catch {
+      exit(130);
+    }
+  };
+}
+
+// Windows 下 ConPTY/控制台事件链偶发吞掉 Ctrl+C（SIGINT 永不送达）的兜底：
+// 把本地终端 stdin 切 raw mode 监听 keypress，\x03(Ctrl+C)/\x04(Ctrl+D) 直连 onInterrupt。
+// 注意：raw mode 下控制台**不再产生 SIGINT**，onInterrupt 必须直接是 hardened cleanup
+// 本体（不能 re-emit SIGINT —— 那条路在 raw mode 下已死）。
+// 仅 win32 且 stdin 是 TTY 时安装（silent/PTY 与 SDK 模式本地终端本就无人读 stdin，
+// 无副作用；proxy 模式 stdio:'inherit' 子进程持有控制台，调用方不得安装）。
+// 进程退出时通过 'exit' 同步钩子恢复 cooked mode，防 Windows 终端残留 raw 态
+// （watchdog 的 exit(130) 同样触发 'exit' 钩子）。
+export function installWinKeypressFallback({ stdin = process.stdin, onInterrupt, platform = process.platform, emitKeypressEvents = _emitKeypressEvents }) {
+  if (platform !== 'win32' || !stdin || !stdin.isTTY) return null;
+  emitKeypressEvents(stdin);
+  try { stdin.setRawMode(true); } catch { return null; }
+  const restore = () => { try { stdin.setRawMode(false); } catch { /* noop */ } };
+  process.on('exit', restore);
+  const onKeypress = (str, key) => {
+    const isCtrlC = (key && key.ctrl && key.name === 'c') || str === '\u0003';
+    const isCtrlD = (key && key.ctrl && key.name === 'd') || str === '\u0004';
+    if (isCtrlC || isCtrlD) onInterrupt();
+  };
+  stdin.on('keypress', onKeypress);
+  stdin.resume();
+  return () => {
+    stdin.off('keypress', onKeypress);
+    restore();
+    process.off('exit', restore);
+  };
+}
+
+// Windows 下杀掉 PTY 进程树（ConPTY agent + claude）。
+// 用 spawnSync taskkill 而非 ptyProcess.kill()：后者在 ConPTY 下有已知同步挂起问题
+// （microsoft/node-pty#454 等），且 killPty 的 respawn 调用方（spawnClaude 内部
+// kill→立即重启、workspaces stop→launch）需要"返回时进程已死"的同步语义 ——
+// taskkill /F 通常 <200ms，timeout 2s 兜底有界，不会废掉 5s watchdog。
+// 非 win32 返回 false，调用方走原 ptyProcess.kill() 路径。
+export function killPtyTree(pid, { platform = process.platform, spawnSyncImpl = _spawnSync } = {}) {
+  if (platform !== 'win32' || !pid) return false;
+  try {
+    spawnSyncImpl('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 2000, windowsHide: true });
+  } catch { /* taskkill 不在 PATH 等极端情况，调用方仍有 watchdog 兜底 */ }
+  return true;
+}

package/server/pty-manager.js

@@ -5,6 +5,7 @@ import { chmodSync, statSync } from 'node:fs';
 import { platform, arch, homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { prepareEmbeddedShellSpawn, stripClaudeNoFlickerUnlessOptedIn } from './lib/terminal-env.js';
+import { killPtyTree } from './lib/term-signals.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -474,7 +475,14 @@ export function killPty() {
     flushBatch();
     batchBuffer = '';
     batchScheduled = false;
-    try { ptyProcess.kill(); } catch { }
+    // Windows：node-pty 的 ConPTY kill 有已知同步挂起问题（microsoft/node-pty#454），
+    // 挂住会连 Ctrl+C 退出链的 watchdog 一起废掉。改用 spawnSync taskkill /T /F 收割
+    // 整棵进程树（ConPTY agent + claude），有界（timeout 2s）且提供"返回时已死"语义
+    // （spawnClaude 内部 kill→respawn、workspaces stop→launch 依赖这一点）。
+    // win32 下完全跳过 ptyProcess.kill()。非 Windows 行为不变。
+    if (!killPtyTree(ptyProcess.pid)) {
+      try { ptyProcess.kill(); } catch { }
+    }
     ptyProcess = null;
     ptyKind = null;
     ptySkipPermissions = false;

package/server/routes/misc.js

@@ -1,6 +1,7 @@
 // Miscellaneous small routes (moved verbatim from server.js handleRequest).
 import { getUserProfile } from '../lib/user-profile.js';
 import { runWaterfallHook } from '../lib/plugin-loader.js';
+import { normalizeBasePath } from '../lib/base-path.js';
 
 async function userProfile(req, res) {
   const profile = await getUserProfile();
@@ -10,7 +11,10 @@ async function userProfile(req, res) {
 
 async function localUrl(req, res, parsedUrl, isLocal, deps) {
   const localIp = deps.getLocalIp();
-  const defaultUrl = `${deps.protocol}://${localIp}:${deps.actualPort}?token=${deps.ACCESS_TOKEN}`;
+  // 反代子路径部署时分享/二维码 URL 也要带前缀，否则扫码绕过代理直连源站端口（与
+  // server.startedNetwork 启动打印保持一致）。未设 CCV_BASE_PATH 时为空串，行为不变。
+  const basePath = normalizeBasePath(process.env.CCV_BASE_PATH);
+  const defaultUrl = `${deps.protocol}://${localIp}:${deps.actualPort}${basePath}?token=${deps.ACCESS_TOKEN}`;
   const hookResult = await runWaterfallHook('localUrl', { url: defaultUrl, ip: localIp, port: deps.actualPort, token: deps.ACCESS_TOKEN });
   res.writeHead(200, { 'Content-Type': 'application/json' });
   res.end(JSON.stringify({ url: hookResult.url }));

package/server/scratch-pty-manager.js

@@ -4,6 +4,7 @@ import { chmodSync, statSync } from 'node:fs';
 import { platform, arch, homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { prepareEmbeddedShellSpawn } from './lib/terminal-env.js';
+import { killPtyTree } from './lib/term-signals.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -219,7 +220,11 @@ export function killScratch(id) {
     flushBatch(s);
     s.batchBuffer = '';
     s.batchScheduled = false;
-    try { s.ptyProcess.kill(); } catch { }
+    // 与 pty-manager.killPty 同款：win32 用 taskkill /T 收割 ConPTY 树，
+    // 绕开 node-pty kill 的同步挂起问题；非 Windows 走原路径。
+    if (!killPtyTree(s.ptyProcess.pid)) {
+      try { s.ptyProcess.kill(); } catch { }
+    }
     s.ptyProcess = null;
   }
   // 显式 kill 后整条记录清掉，监听器一并丢弃（前端 ws.close 也会清）

package/server/server.js

@@ -78,6 +78,8 @@ import { CONTEXT_WINDOW_FILE, readModelContextSize } from './lib/context-watcher
 import { watchLogFile, startWatching, unwatchAll, sendEventToClients, sendToClients } from './lib/log-watcher.js';
 import { cleanupExtractCache } from './lib/jsonl-archive.js';
 import { backupConfigs } from './lib/config-backup.js';
+import { normalizeBasePath, validateBasePath, stripBasePath } from './lib/base-path.js';
+import { createHardenedCleanup } from './lib/term-signals.js';
 import { createBackpressureGate } from './lib/ws-backpressure.js';
 
 
@@ -567,12 +569,13 @@ async function handleRequest(req, res) {
   let url = parsedUrl.pathname;
 
   // CCV_BASE_PATH reverse proxy: strip prefix at TOP so API/WS/static/SPA
-  // all work with original unprefixed paths. basePath normalized.
-  const bpRaw = process.env.CCV_BASE_PATH || '';
-  const bp = bpRaw && bpRaw !== '/' ? bpRaw.replace(/\/?$/, '/') : '';
-  if (bp && url.startsWith(bp)) {
-    url = url.slice(bp.length) || '/';
-  }
+  // all work with original unprefixed paths. 剥离后必须写回 parsedUrl.pathname ——
+  // dispatch()（routes/_dispatch.js）与多个 handler（files-content/ask-perm/im）直读
+  // parsedUrl.pathname 做路由匹配和偏移 slice，不写回则前缀下全部 /api/* 与 SSE /events
+  // 命不中、落 SPA fallback（PR #108 遗留 P0）。searchParams 不受 pathname 赋值影响。
+  const bp = normalizeBasePath(process.env.CCV_BASE_PATH);
+  url = stripBasePath(url, bp);
+  parsedUrl.pathname = url;
   const method = req.method;
 
   // WebSocket 路径不处理，交给 upgrade 事件
@@ -677,14 +680,9 @@ async function handleRequest(req, res) {
 
   // 静态文件服务
   if (method === 'GET') {
-    const rawBase = process.env.CCV_BASE_PATH || '';
-    // Normalize to ensure trailing slash; prevents /proxy/ws from
-    // incorrectly matching /proxy/ws-other due to startsWith ambiguity.
-    const basePath = rawBase && rawBase !== '/' ? rawBase.replace(/\/?$/, '/') : '';
+    // basePath 已在 handleRequest 顶部统一剥离，这里不可再剥——否则 /proxy/proxy/x
+    // 这类路径会被双重剥离。
     let filePath = url;
-    if (basePath && url.startsWith(basePath)) {
-      filePath = url.slice(basePath.length) || '/';
-    }
     if (filePath === '/') filePath = '/index.html';
     // 去掉 query string
     filePath = filePath.split('?')[0];
@@ -728,12 +726,12 @@ async function handleRequest(req, res) {
         html = html.replace(/<html([^>]*?)data-theme="[^"]*"/, `<html$1data-theme="${themeColor}"`);
         // 运行时注入 <base> 标签：当 CCV_BASE_PATH 设置为非空非根路径时，
         // 使浏览器将所有相对 URL 解析到代理子路径下。配合 Vite base='' 输出相对路径。
-        const basePath = process.env.CCV_BASE_PATH || '';
-        if (basePath && basePath !== '/') {
-          const safeBase = basePath.replace(/\/?$/, '/');
-                  const escapedBase = safeBase.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-        const jsSafeBase = safeBase.replace(/"/g, '"').replace(/<\//g, '<\/');
-        html = html.replace(/<head[^>]*>/i, m => m + `<base href="${escapedBase}"><script>window.__CCV_BASE_PATH__="${jsSafeBase}"</script>`);
+        const injectBase = normalizeBasePath(process.env.CCV_BASE_PATH);
+        if (injectBase) {
+          const escapedBase = injectBase.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+          // JS 双引号字符串转义：\ → \\、" → \"、</ → <\/（防 </script> 提前闭合）
+          const jsSafeBase = injectBase.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/<\//g, '<\\/');
+          html = html.replace(/<head[^>]*>/i, m => m + `<base href="${escapedBase}"><script>window.__CCV_BASE_PATH__="${jsSafeBase}"</script>`);
         }
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
         res.end(html);
@@ -877,17 +875,25 @@ export async function startViewer() {
               if (_prefs.lang) setLang(_prefs.lang);
             }
           } catch { /* 读 prefs 失败就保持默认语言 */ }
+          // CCV_BASE_PATH 配置校验：缺前导 '/' 时剥离静默失效（startsWith 永不命中），
+          // 启动期告警一次。放在 setLang 之后，告警语言才跟随用户配置。
+          {
+            const _bpCheck = validateBasePath(process.env.CCV_BASE_PATH);
+            if (_bpCheck.warning) console.warn(t(_bpCheck.warning, { value: process.env.CCV_BASE_PATH }));
+          }
           // interceptor.js runs in this same process (via proxy.js → setupInterceptor).
           // Inject live-port via module-level setter instead of process.env to avoid
           // polluting env of child_process.spawn descendants (Bash tools / MCP / Electron tabs).
           setLivePort(port, serverProtocol);
-          const url = `${serverProtocol}://127.0.0.1:${port}`;
+          // 自动打开/serverStarted hook 用的 URL 也要带反代前缀（与启动打印一致）
+          const url = `${serverProtocol}://127.0.0.1:${port}${normalizeBasePath(process.env.CCV_BASE_PATH)}`;
           if (!isCliMode) {
             console.error(t('server.started'));
-            console.error(t('server.startedLocal', { protocol: serverProtocol, port }));
+            const _bp = normalizeBasePath(process.env.CCV_BASE_PATH);
+            console.error(t('server.startedLocal', { protocol: serverProtocol, port, basePath: _bp }));
             const _ips = getAllLocalIps();
             for (const _ip of _ips) {
-              console.error(t('server.startedNetwork', { protocol: serverProtocol, ip: _ip, port, token: ACCESS_TOKEN }));
+              console.error(t('server.startedNetwork', { protocol: serverProtocol, ip: _ip, port, basePath: _bp, token: ACCESS_TOKEN }));
             }
             if (authConfig.enabled) {
               if (authConfig.password === '') console.error(t('server.passwordEmptyWarn'));
@@ -1064,12 +1070,8 @@ async function setupTerminalWebSocket(httpServer) {
 
     httpServer.on('upgrade', (req, socket, head) => {
       const wsUrl = new URL(req.url, `${serverProtocol}://${req.headers.host}`);
-      let pathname = wsUrl.pathname;
-      const bpRaw = process.env.CCV_BASE_PATH || '';
-      const wsBp = bpRaw && bpRaw !== '/' ? bpRaw.replace(/\/?$/, '/') : '';
-      if (wsBp && pathname.startsWith(wsBp)) {
-        pathname = '/' + pathname.slice(wsBp.length);
-      }
+      // upgrade 不经 handleRequest，basePath 需独立剥离（与 HTTP 段同走统一函数）
+      let pathname = stripBasePath(wsUrl.pathname, normalizeBasePath(process.env.CCV_BASE_PATH));
       // 与 HTTP 一致的鉴权（此前 WS upgrade 完全不校验 token，远程终端实为无门禁——本次堵洞）。
       // 在此显式计算 isLocal（与 handleRequest 同款三态判断），WS 视作非 HTML 请求。
       const wsRemoteIp = req.socket.remoteAddress;
@@ -1929,8 +1931,20 @@ async function _doStop() {
   _lastCliActive = false;
   // 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.
-  try { await imCore.stopAll(); } catch { }
-  try { await Promise.race([runParallelHook('serverStopping'), new Promise(r => setTimeout(r, 3000))]); } catch { }
+  // IM teardown + serverStopping hook 共用一个 3s 总预算（保持串行语义）：
+  // Windows 上 IM bridge WS teardown 挂住会卡死整条退出链（原本裸 await 是
+  // "Ctrl+C 完全无反应"的 B 类成因）；两段若各自 3s race 串行最坏 6s，会越过
+  // cleanup watchdog(5s) 截断其后的 temp jsonl rename（用户数据）——合并为单预算
+  // 保证 teardown ≤3s，watchdog 前始终留出 rename 余量。超时后控制流顺序继续。
+  try {
+    await Promise.race([
+      (async () => {
+        try { await imCore.stopAll(); } catch { }
+        await runParallelHook('serverStopping');
+      })(),
+      new Promise(r => setTimeout(r, 3000)),
+    ]);
+  } catch { }
   // 如果用户未做选择，将临时文件转为正式文件
   if (_resumeState && _resumeState.tempFile) {
     try {
@@ -2100,6 +2114,9 @@ function handleExit() {
 if (!globalThis._ccvServerSignalsRegistered) {
   globalThis._ccvServerSignalsRegistered = true;
   process.on('exit', handleExit);
-  process.on('SIGINT', () => { stopViewer().finally(() => process.exit()); });
-  process.on('SIGTERM', () => { stopViewer().finally(() => process.exit()); });
+  // hardened：watchdog 5s 强退 + 重复触发立退（防 Windows 上 stopViewer 内部
+  // await 挂住导致 .finally(exit) 永不执行 = Ctrl+C 完全无反应）。
+  const _hardenedStop = createHardenedCleanup({ doCleanup: () => stopViewer() });
+  process.on('SIGINT', _hardenedStop);
+  process.on('SIGTERM', _hardenedStop);
 }