cc-viewer 1.6.345 → 1.6.348

package/server/lib/spawn-model-resolver.js

@@ -0,0 +1,109 @@
+// Spawn-time model resolution from the CURRENTLY EFFECTIVE configuration.
+//
+// Replaces the old injection criterion for model-specific system prompts, which read
+// `projects[cwd].lastModelUsage` from ~/.claude.json — a usage STATISTIC of the previous
+// session, not configuration. A stale record (e.g. a past deepseek experiment) made ccv
+// inject a third-party override prompt into an official-model session. The new criterion
+// only trusts live configuration signals; with no signal it returns null and no model
+// entry is injected (the CC_SYSTEM.md / CC_APPEND_SYSTEM.md sentinels are unaffected).
+//
+// Signal priority (best-effort heuristic — the shell-env vs settings.json-env ordering is
+// a repo convention, not documented Claude Code semantics; a mismatch merely means "no
+// injection" or "same-family entry", both harmless):
+//   1. active third-party proxy profile for the spawned workspace (family mapping via
+//      resolveProfileModel — the model the ccv proxy will actually route to)
+//   2. env CLAUDE_MODEL > env ANTHROPIC_MODEL (shell exports inherited by the spawn)
+//   3. settings.json `env.ANTHROPIC_MODEL` > settings.json top-level `model`
+//      (the env block outranks the top-level field, mirroring how Claude Code applies it)
+// Known limitation: a `--model` flag passed through extraArgs is not consulted.
+//
+// Pure disk reads — deliberately NOT importing server/interceptor.js: its module-level
+// side effects (log init, watchFile) must not leak into pty-manager unit tests, and its
+// live `_activeProfile` reflects the ccv process's CURRENT workspace, which is not
+// necessarily the workspace being spawned (multi-workspace/tab mode). All paths are
+// injectable for tests; the defaults derive from LOG_DIR / getClaudeConfigDir(), both
+// covered by the L1b/L1c/L1d test-isolation barriers.
+import { readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { LOG_DIR, getClaudeConfigDir } from '../../findcc.js';
+import { resolveProfileModel } from './interceptor-core.js';
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null; // missing / unreadable / corrupt → treated as "no signal"
+  }
+}
+
+function nonEmpty(v) {
+  return (typeof v === 'string' && v.trim()) ? v.trim() : null;
+}
+
+// `model: "default"` means "let Claude Code pick" — it names no concrete model/family,
+// so it must not participate in entry matching (an entry literally named DEFAULT is
+// rejected by the entry-name grammar anyway). Other aliases (opus/sonnet/opusplan/…)
+// stay verbatim: they express an explicit family intent and matching a same-family
+// entry is the desired behavior.
+function normalizeAlias(model) {
+  if (!model) return null;
+  return model.toLowerCase() === 'default' ? null : model;
+}
+
+/**
+ * The active THIRD-PARTY proxy profile for the workspace being spawned, or null.
+ * Resolution mirrors interceptor.js `_loadProxyProfile`: the workspace-scoped
+ * `<logDir>/<project>/active-profile.json` activeId outranks the global
+ * `profile.json` `active`; id 'max' is the built-in Default (= no third-party profile).
+ * The project-dir derivation is character-identical to interceptor.js:353.
+ */
+function readActiveProfile(spawnDir, logDir) {
+  const data = readJson(join(logDir, 'profile.json'));
+  if (!data || !Array.isArray(data.profiles)) return null;
+  let activeId = null;
+  if (spawnDir) {
+    const projectName = basename(spawnDir).replace(/[^a-zA-Z0-9_\-\.]/g, '_');
+    const ws = readJson(join(logDir, projectName, 'active-profile.json'));
+    if (ws && typeof ws.activeId === 'string') activeId = ws.activeId;
+  }
+  if (!activeId) activeId = typeof data.active === 'string' ? data.active : null;
+  if (!activeId || activeId === 'max') return null;
+  const profile = data.profiles.find((p) => p && p.id === activeId);
+  return (profile && profile.id !== 'max') ? profile : null;
+}
+
+/**
+ * Resolve the model id the spawned claude session will effectively use, from live
+ * configuration only. Returns null when no configuration signal exists — the caller
+ * must then skip model-entry injection.
+ *
+ * @param {string} spawnDir workspace being launched (absolute path)
+ * @param {Object} [env] environment (default process.env)
+ * @param {{ logDir?: string, configDir?: string }} [opts] test seams for the data roots
+ * @returns {string|null}
+ */
+export function resolveSpawnModel(spawnDir, env = process.env, opts = {}) {
+  const logDir = opts.logDir || LOG_DIR;
+  const configDir = opts.configDir || getClaudeConfigDir();
+
+  // Base model: what claude itself is configured to request.
+  let base = nonEmpty(env?.CLAUDE_MODEL) || nonEmpty(env?.ANTHROPIC_MODEL);
+  if (!base) {
+    const settings = readJson(join(configDir, 'settings.json'));
+    base = nonEmpty(settings?.env?.ANTHROPIC_MODEL) || nonEmpty(settings?.model);
+  }
+  base = normalizeAlias(base);
+
+  // Active third-party profile: the proxy rewrites requests per model family, so the
+  // effective model is the mapping target; an unmapped family passes through as base.
+  const profile = readActiveProfile(spawnDir, logDir);
+  if (profile) {
+    const mapped = base ? resolveProfileModel(base, profile) : null;
+    return nonEmpty(mapped)
+      || base
+      || nonEmpty(profile.ANTHROPIC_MODEL)
+      || nonEmpty(profile.activeModel) // legacy whole-replacement profiles
+      || null;
+  }
+  return base;
+}

package/server/lib/system-prompt-files.js

@@ -53,13 +53,15 @@ function hasArg(args, ...names) {
  * @param {string[]} [existingArgs] 已有的 claude 参数(用于「手动优先」判断)
  * @param {Object} [env] 环境变量(默认 process.env)
  * @param {{ modelId?: string|null, globalModelDir?: string|null }} [opts]
- * @returns {{ args: string[], loaded: string[], model: string|null }}
- *          args: 待追加参数；loaded: 实际加载的文件(终端提示)；model: 命中的条目名(未命中为 null)
+ * @returns {{ args: string[], loaded: string[], model: string|null, suppressed?: 'env'|'manual-flag' }}
+ *          args: 待追加参数；loaded: 实际加载的文件(终端提示)；model: 命中的条目名(未命中为 null)；
+ *          suppressed: 注入被有意跳过的原因(env 开关 / 手动同义 flag 抑制了已命中的模型条目)——
+ *          调用方(pty-manager)据此不再打「no matching entry」误导性告警。
  */
 export function buildSystemPromptFileArgs(projectDir, existingArgs = [], env = process.env, opts = {}) {
   const out = { args: [], loaded: [], model: null };
   if (!projectDir) return out;
-  if (env?.[DISABLE_AUTO_SYSTEM_PROMPT_ENV] === '1') return out;
+  if (env?.[DISABLE_AUTO_SYSTEM_PROMPT_ENV] === '1') return { ...out, suppressed: 'env' };
 
   if (opts?.modelId) {
     const candidates = [{ dir: join(projectDir, MODEL_PROMPT_DIR), scope: 'workspace' }];
@@ -73,6 +75,8 @@ export function buildSystemPromptFileArgs(projectDir, existingArgs = [], env = p
         out.args.push(flagPair[1], match.path);
         out.loaded.push(`${match.scope === 'global' ? 'global ' : ''}${MODEL_PROMPT_DIR}/${match.fileName}`);
         out.model = match.name;
+      } else {
+        out.suppressed = 'manual-flag'; // 条目命中但用户手传了同义 flag：有意跳过，非「无条目」
       }
       return out; // 命中即返回：默认 sentinel 不再参与(含手动 flag 抑制注入的情况)。
     }

package/server/lib/system-prompt-render.js

@@ -0,0 +1,79 @@
+// Spawn-time `${...}` template-variable rendering for injected system-prompt files.
+//
+// The Edit System Prompt editor stores entries (model entries under system_prompt/ and the
+// CC_SYSTEM.md / CC_APPEND_SYSTEM.md sentinels) with `${...}` placeholders LITERAL — that is the
+// editing surface documented by the "Dynamic Parameter Documentation" popup. The substitution has
+// to happen when claude is launched: this module takes the args produced by
+// buildSystemPromptFileArgs, and for every injected file whose content contains template
+// variables, renders it via create_system_prompt.js and swaps in a rendered temp copy.
+//
+// Design constraints:
+// - Files without `${...}` pass through untouched (zero cost — no variable collection, which
+//   shells out to git several times, and no temp file).
+// - missingVariableMode is 'keep': unknown placeholders stay literal, so user-authored prompt
+//   text quoting shell syntax like `${HOME}` or `${1:-default}` is never eaten.
+// - Any failure (unreadable file, variable collection throwing, temp write failing) falls back
+//   to the raw path — rendering must never break the claude spawn.
+// - Temp copies live under <tmpdir>/cc-viewer-rendered-prompts/<pid>/: per-process so two ccv
+//   instances never clobber each other; sequential spawns of one instance overwrite the same
+//   basename, which is safe because claude reads the file once at startup.
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createSystemPrompt, createSystemPromptVariables } from './create_system_prompt.js';
+
+// Detection only (no capture): does the text contain at least one `${...}` placeholder?
+const TEMPLATE_VARIABLE_RE = /\$\{[^}]+\}/;
+
+/** Per-process directory holding the rendered temp copies. */
+export function renderedPromptDir(pid = process.pid) {
+  return join(tmpdir(), 'cc-viewer-rendered-prompts', String(pid));
+}
+
+/**
+ * Render template variables in the file args produced by buildSystemPromptFileArgs.
+ *
+ * @param {{ args: string[], loaded: string[], model: string|null }} sysPrompt
+ * @param {{ cwd?: string, modelId?: string|null, variablesFactory?: Function }} [opts]
+ *        cwd: workspace being launched (git/cwd/memory variables resolve against it);
+ *        modelId: resolved model id from the last launch — becomes ${model.name} (the [1m]
+ *        context-window suffix is stripped: it is a claude-code UI notation, not a model name);
+ *        variablesFactory: test seam replacing createSystemPromptVariables.
+ * @returns {{ args: string[], loaded: string[], model: string|null }} same shape; file paths
+ *          whose content was rendered point at the temp copy instead.
+ */
+export function renderSystemPromptFileArgs(sysPrompt, opts = {}) {
+  // Defensive: null / non-object → safe default, so the caller always gets a valid
+  // spread target and the "loaded" notice guard (sysPrompt.loaded.length) can't throw.
+  if (!sysPrompt || typeof sysPrompt !== 'object') return { args: [], loaded: [], model: null };
+  const args = Array.isArray(sysPrompt.args) ? sysPrompt.args : [];
+  if (args.length === 0) return sysPrompt;
+
+  let variables = null; // lazy: collected once, and only if some file actually has placeholders
+  const out = [...args];
+  for (let i = 0; i + 1 < out.length; i += 2) {
+    const flag = out[i];
+    if (flag !== '--system-prompt-file' && flag !== '--append-system-prompt-file') continue;
+    const path = out[i + 1];
+    try {
+      const text = readFileSync(path, 'utf-8');
+      if (!TEMPLATE_VARIABLE_RE.test(text)) continue;
+      if (!variables) {
+        const factory = opts.variablesFactory || createSystemPromptVariables;
+        const overrides = {};
+        if (opts.modelId) overrides.model = { name: String(opts.modelId).replace(/\[1m\]$/, '') };
+        variables = factory(overrides, { cwd: opts.cwd });
+      }
+      const rendered = createSystemPrompt(text, { variables, missingVariableMode: 'keep' });
+      if (rendered === text) continue; // every placeholder unknown → nothing changed, keep raw path
+      const dir = renderedPromptDir();
+      mkdirSync(dir, { recursive: true });
+      const target = join(dir, basename(path));
+      writeFileSync(target, rendered, 'utf-8');
+      out[i + 1] = target;
+    } catch (e) {
+      console.warn(`[CC Viewer] system-prompt template render failed for ${path} (injecting the raw file):`, e?.message || e);
+    }
+  }
+  return { ...sysPrompt, args: out };
+}

package/server/pty-manager.js

@@ -8,8 +8,9 @@ import { prepareEmbeddedShellSpawn, stripClaudeNoFlickerUnlessOptedIn, applyClau
 import { killPtyTree } from './lib/term-signals.js';
 import { findSafeSliceStart, splitTrailingIncomplete } from './lib/ansi-safe-slice.js';
 import { buildSystemPromptFileArgs } from './lib/system-prompt-files.js';
+import { renderSystemPromptFileArgs } from './lib/system-prompt-render.js';
 import { MODEL_PROMPT_DIR } from './lib/model-system-prompts.js';
-import { readClaudeProjectModel } from './lib/context-watcher.js';
+import { resolveSpawnModel } from './lib/spawn-model-resolver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -50,20 +51,31 @@ export function _setPtyImportForTests(fn) {
   _ptyImportForTests = fn;
 }
 
-// spawn 时读取「上次启动所用模型 id」供模型定制 system prompt 匹配。
-// readClaudeProjectModel 读的是真实 ~/.claude.json(无 NODE_TEST_CONTEXT 屏障)，
-// 而多数 pty 单测以仓库根为 cwd —— 默认读取器在测试上下文里必须失活，
-// 否则开发机的真实模型记录会漏进单测(机器状态依赖)。测试用 _setSpawnModelReaderForTests 显式注入。
-// env/reader 参数化只为可测性：单测能直接断言「测试上下文 → null / 生产 → 透传」，
-// 而无需真的读 ~/.claude.json(见 test/pty-manager.test.js 的 guard 单测)。
-export function _defaultSpawnModelReader(c, env = process.env, reader = readClaudeProjectModel) {
-  return env.NODE_TEST_CONTEXT ? null : reader(c);
+// spawn 时解析「当前生效配置」下的模型 id 供模型定制 system prompt 匹配（resolveSpawnModel：
+// 激活的三方 proxy profile 模型映射 > env CLAUDE_MODEL/ANTHROPIC_MODEL > settings.json；
+// 无实时配置信号 → null → 不注入模型条目）。旧判据读 ~/.claude.json 的 lastModelUsage
+// ——那是上次会话的使用统计而非配置，陈旧记录会把三方模型的 override 提示词强加给
+// 官方模型会话（review round：deepseek 残留记录事故）。
+// NODE_TEST_CONTEXT 屏障保留：resolveSpawnModel 会读 process.env 的模型变量，开发机
+// shell export 会漏进单测(机器状态依赖)；测试用 _setSpawnModelReaderForTests 显式注入。
+// env/reader 参数化只为可测性(见 test/pty-manager.test.js 的 guard 单测)。
+export function _defaultSpawnModelReader(c, env = process.env, reader = resolveSpawnModel) {
+  return env.NODE_TEST_CONTEXT ? null : reader(c, env);
 }
 let _spawnModelReader = _defaultSpawnModelReader;
 export function _setSpawnModelReaderForTests(fn) {
   _spawnModelReader = fn || _defaultSpawnModelReader;
 }
 
+// 启动兜底的时间源与窗口：spawn 后在窗口内死亡视为「引导期死亡」。真实引导崩溃 <1s，
+// 5s 足够；更长的窗口只会扩大「用户快速主动退出」的误报面(评审取值)。
+// _now 可注入：兜底用例需要拨表模拟「存活超窗后退出」。
+const SYS_PROMPT_BOOT_WINDOW_MS = 5000;
+let _now = Date.now;
+export function _setNowForTests(fn) {
+  _now = fn || Date.now;
+}
+
 async function getPty() {
   if (typeof _ptyImportForTests === 'function') {
     return _ptyImportForTests();
@@ -152,8 +164,15 @@ const _thinkingDisplayRejectedPaths = new Set();
 // 启动目录里的 CC_SYSTEM.md / CC_APPEND_SYSTEM.md 自动注入 --system-prompt-file/--append-system-prompt-file。
 // 若目标 claude(或三方 fork/wrapper)不识别该 flag，onExit 检测 "unknown option" 后把 claudePath 记入此集，
 // 下次 spawn 跳过注入并去 flag 重启(对齐 _thinkingDisplayRejectedPaths 自愈)。
+// 语义：永久(进程级)——"unknown option" 是该二进制不支持 flag 的确定性能力信号。
 const _systemPromptFileRejectedPaths = new Set();
 
+// 一次性跳过令牌：启动兜底一级的放宽半支(引导窗口内非信号 exit≠0)覆盖的是**瞬态**崩溃
+// (API key 失效/网络抖动/与注入无关的秒退)，不能写进上面的永久拒绝集——否则一次瞬态故障
+// 会在整个 ccv 进程生命周期内静默禁用该二进制的注入(review P1)。令牌在下一次 spawn 被
+// 消费(delete)：恰好保证去注入重试一次，之后的 spawn 恢复正常注入尝试。
+const _skipInjectionOncePaths = new Set();
+
 // 内部重启(-c 重试 / flag 自愈)时抑制一次注入提示，避免终端重复打印同一行。
 let _suppressNextSpawnNotice = false;
 
@@ -172,9 +191,10 @@ export function _markThinkingDisplayRejected(claudePath) {
   _thinkingDisplayRejectedPaths.add(claudePath);
 }
 
-// 仅用于测试/内部：清空 system-prompt-file 拒绝集
+// 仅用于测试/内部：清空 system-prompt-file 拒绝集(连同一次性跳过令牌，保持用例间干净)
 export function _clearSystemPromptFileRejectedPaths() {
   _systemPromptFileRejectedPaths.clear();
+  _skipInjectionOncePaths.clear();
 }
 
 // 仅用于测试：查询路径是否已被标记为不支持 --system-prompt-file
@@ -299,21 +319,40 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
   // LOG_DIR 内的 spawn(IM worker 工作目录 = <LOG_DIR>/IM_<id>/)跳过模型匹配：
   // IM 人格依赖默认 sentinel CC_APPEND_SYSTEM.md 注入，全局模型条目不得静默取代它。
   const spawnDir = cwd || process.cwd();
+  // insideLogDir 留在 try 外：下方 onExit 的启动兜底门控也要用它。
   const insideLogDir = spawnDir === LOG_DIR || spawnDir.startsWith(LOG_DIR + sep);
-  const resolvedModelId = insideLogDir ? null : _spawnModelReader(spawnDir);
-  let sysPrompt = buildSystemPromptFileArgs(spawnDir, finalExtraArgs, process.env, {
-    modelId: resolvedModelId,
-    globalModelDir: join(LOG_DIR, MODEL_PROMPT_DIR),
-  });
-  if (_systemPromptFileRejectedPaths.has(claudePath)) {
+  // 整个 system prompt 构建 + 渲染管道包在 try-catch 里(PR#128)：任何意外抛错(模型解析、
+  // buildSystemPromptFileArgs 文件系统竞态、渲染的 git 子进程异常)都走兜底——按「没命中任何
+  // 条目」处理，launch 不带 --system-prompt-file/--append-system-prompt-file，claude 用自身
+  // 默认 system prompt 启动。注入失败绝不能阻断 spawn。
+  let sysPrompt = { args: [], loaded: [], model: null };
+  // 一次性跳过令牌在进入管道前无条件消费(delete)：放宽半支的兜底只跳过紧随其后的这一次注入。
+  // 若放在 build 之后，build 抛错时令牌残留、会再多跳过一次(违反 exactly-once，review)。
+  const skipOnce = _skipInjectionOncePaths.delete(claudePath);
+  try {
+    const resolvedModelId = insideLogDir ? null : _spawnModelReader(spawnDir);
+    sysPrompt = buildSystemPromptFileArgs(spawnDir, finalExtraArgs, process.env, {
+      modelId: resolvedModelId,
+      globalModelDir: join(LOG_DIR, MODEL_PROMPT_DIR),
+    });
+    if (_systemPromptFileRejectedPaths.has(claudePath) || skipOnce) {
+      sysPrompt = { args: [], loaded: [], model: null };
+    } else if (resolvedModelId && !sysPrompt.model && !sysPrompt.suppressed
+      && (existsSync(join(spawnDir, MODEL_PROMPT_DIR)) || existsSync(join(LOG_DIR, MODEL_PROMPT_DIR)))) {
+      // The one diagnostic case worth a warning: a system_prompt dir is configured
+      // but the resolved model matched no entry (likely a misnamed file). Intentional
+      // skips (CCV_DISABLE_AUTO_SYSTEM_PROMPT=1, or a manual --system-prompt flag
+      // suppressing a matched entry) carry `suppressed` and stay quiet. The
+      // successful-injection notice is emitted below via emitSpawnNotice (with
+      // internal-restart suppression); no-modelId spawns are the normal quiet path.
+      console.warn(`[CC Viewer] model-specific prompt: modelId="${resolvedModelId}" resolved from active config but no matching entry found in workspace or global ${MODEL_PROMPT_DIR}/`);
+    }
+    // Resolve `${...}` template variables in the injected files (editor stores them literal —
+    // the substitution documented by the editor's parameter reference happens here, at launch).
+    sysPrompt = renderSystemPromptFileArgs(sysPrompt, { cwd: spawnDir, modelId: resolvedModelId });
+  } catch (err) {
+    console.warn('[CC Viewer] system prompt build/render failed, launching without injected prompt:', err?.message || err);
     sysPrompt = { args: [], loaded: [], model: null };
-  } else if (resolvedModelId && !sysPrompt.model
-    && (existsSync(join(spawnDir, MODEL_PROMPT_DIR)) || existsSync(join(LOG_DIR, MODEL_PROMPT_DIR)))) {
-    // The one diagnostic case worth a warning: a system_prompt dir is configured
-    // but the resolved model matched no entry (likely a misnamed file). The
-    // successful-injection notice is emitted below via emitSpawnNotice (with
-    // internal-restart suppression); no-modelId spawns are the normal quiet path.
-    console.warn(`[CC Viewer] model-specific prompt: modelId="${resolvedModelId}" resolved but no matching entry found in workspace or global ${MODEL_PROMPT_DIR}/`);
   }
   const launchArgs = sysPrompt.args.length ? [...finalExtraArgs, ...sysPrompt.args] : finalExtraArgs;
 
@@ -330,6 +369,9 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
   outputBuffer = '';
   currentWorkspacePath = cwd || process.cwd();
   lastWorkspacePath = currentWorkspacePath;
+  // Boot-window anchor for the injection fallback tiers below (same clock as the
+  // comparison — _now(), never Date.now(), so tests can steer both ends together).
+  const spawnedAt = _now();
 
   ptyProcess = pty.spawn(command, args, {
     name: 'xterm-256color',
@@ -342,13 +384,8 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
   // --allow-dangerously-skip-permissions only enables a later toggle, so it must NOT count.
   ptySkipPermissions = extraArgs.includes('--dangerously-skip-permissions');
 
-  // 注入了 system prompt 文件时向终端打印一行提示(可见性/安全)；内部重启已抑制以免重复。
-  if (sysPrompt.loaded.length && !_suppressNextSpawnNotice) {
-    const modelSuffix = sysPrompt.model ? ` (model match: ${sysPrompt.model})` : '';
-    emitSpawnNotice(`[CC Viewer] loaded ${sysPrompt.loaded.join(', ')} as system prompt${modelSuffix}`);
-  }
-  _suppressNextSpawnNotice = false;
-
+  // PTY 事件处理器必须紧随 spawn 注册(PR#128)：若子进程在 onExit 挂载前就退出(二进制缺失/
+  // 秒崩/拒绝注入 flag)，exit 事件会丢失——句柄释放后事件循环可能排空。注入提示挪到注册之后。
   ptyProcess.onData((data) => {
     outputBuffer += data;
     if (outputBuffer.length > MAX_BUFFER) {
@@ -363,12 +400,16 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
     }
   });
 
-  ptyProcess.onExit(({ exitCode }) => {
+  ptyProcess.onExit(({ exitCode, signal }) => {
     flushBatch(true);
     lastExitCode = exitCode;
     ptyProcess = null;
     ptyKind = null;
     ptySkipPermissions = false;
+    // 引导期死亡：spawn 后窗口内退出。窗口外的退出一律不属于「注入拖崩启动」的兜底范围。
+    // 单次取 _now(评审)：一级/二级共用同一时刻，注入的 fake clock 不会在分支间发散。
+    const elapsedMs = _now() - spawnedAt;
+    const diedInBootWindow = elapsedMs < SYS_PROMPT_BOOT_WINDOW_MS;
 
     // Auto-retry without -c/--continue if "No conversation found"
     // 注意：早退 return 会跳过下方的 exitListeners 广播——第一次失败的 pty 死亡对消费者
@@ -399,18 +440,48 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
       return;
     }
 
-    // 事后兜底：claude(或三方 fork/wrapper)不识别 --system-prompt-file/--append-system-prompt-file 而崩溃时，
-    // 记下该 claudePath、跳过注入并重启一次，避免自动注入把会话拖崩(对齐上面的 --thinking-display 自愈)。
+    // 事后兜底一级：注入过 system-prompt 文件的 claude 非正常死亡时，跳过注入重启一次
+    // (对齐上面的 --thinking-display 自愈；该确诊分支必须在前——用户自传 --thinking-display
+    // 且有注入时这里最多浪费一次去注入重试，第二次即广播真实报错)。两个半支的**持久性不同**：
+    //  - 精确半支(原语义)：输出含 "unknown option --system-prompt-file" —— 确诊该二进制不支持
+    //    flag(稳定能力信号)→ 写永久拒绝集；任何场景(含 IM worker，否则它永远起不来)都自愈。
+    //  - 放宽半支(启动兜底)：引导窗口内 exit≠0 —— 注入**可能**是拖崩启动的原因(也可能是无关的
+    //    瞬态故障)→ 只发一次性跳过令牌，绝不写永久集(review P1：一次瞬态崩溃不得在整个进程
+    //    生命周期内静默禁用注入)。门控 !signal(用户 Ctrl-C/关标签/切 workspace 的 killPtyTree
+    //    都是信号终止，不是引导崩溃，盲目重启会把用户刚关的会话强行拉回来；Windows ConPTY 无
+    //    POSIX 信号语义，已知限制：Ctrl-C 可能多一次无害重试)与 !insideLogDir(IM worker
+    //    「去注入重启」= 剥离 CC_APPEND_SYSTEM.md 人格后存活，比崩溃更难排查——IM 秒退只广播
+    //    真实报错)。
+    // 无死循环：respawn 时拒绝集/令牌把 loaded 清空 → 本分支不再命中，恰好重试一次。
+    // 一级重试只去掉注入、其余参数原样；根因是别的(如 API key 失效)时首次报错已实时流入
+    // 终端 scrollback 不丢失，第二次照常死亡并广播。
+    const unknownSysFileFlag = /unknown option ['"]--(append-)?system-prompt-file/i.test(outputBuffer);
+    const injectedBootCrash = !insideLogDir && !signal && diedInBootWindow;
     const sysFileRejected = sysPrompt.loaded.length > 0 && exitCode !== 0
-      && /unknown option ['"]--(append-)?system-prompt-file/i.test(outputBuffer);
+      && (unknownSysFileFlag || injectedBootCrash);
     if (sysFileRejected) {
-      console.error('[CC Viewer] claude rejected --system-prompt-file, skipping CC_SYSTEM.md/CC_APPEND_SYSTEM.md and retrying');
-      _systemPromptFileRejectedPaths.add(claudePath);
+      if (unknownSysFileFlag) {
+        console.error('[CC Viewer] claude rejected --system-prompt-file, marking as unsupported and retrying without injection');
+        _systemPromptFileRejectedPaths.add(claudePath);
+      } else {
+        console.error(`[CC Viewer] claude exited (code ${exitCode}) ${Math.round(elapsedMs / 1000)}s after launch with injected system prompt (${sysPrompt.loaded.join(', ')}); retrying once without injection`);
+        _skipInjectionOncePaths.add(claudePath);
+      }
       _suppressNextSpawnNotice = true;
+      // 措辞留有余地(评审)：引导期死亡可能与注入无关(API key/网络等)，不断言因果。
+      emitSpawnNotice(`[CC Viewer] claude exited during boot (code ${exitCode}); the injected system prompt may or may not be the cause — retrying once without ${sysPrompt.loaded.join(', ')}`);
       spawnClaude(proxyPort, cwd, extraArgs, claudePath, isNpmVersion, serverPort, serverProtocol, internalToken);
       return;
     }
 
+    // 事后兜底二级：注入过且 exit=0 秒退 —— 无法与「用户主动快速 /exit」区分(日常高频)，
+    // 所以只打诊断提示、不自动重启、不加入拒绝集(自动关停会因使用习惯静默禁用注入，评审否决)，
+    // 也不早退——照常广播 exit，前端退出横幅路径与用户正常 /exit 完全一致。
+    // !insideLogDir：IM worker 的 pty 数据流可能被桥接转发，诊断行不该漏进 IM 会话(评审)。
+    if (sysPrompt.loaded.length > 0 && exitCode === 0 && diedInBootWindow && !insideLogDir) {
+      emitSpawnNotice(`[CC Viewer] claude exited ${Math.round(elapsedMs / 1000)}s after launch with an injected system prompt (${sysPrompt.loaded.join(', ')}). If this keeps happening the injected prompt may be incompatible — remove the entry or set CCV_DISABLE_AUTO_SYSTEM_PROMPT=1 to skip injection.`);
+    }
+
     // 保留 lastWorkspacePath，不清除，用于 respawn
     currentWorkspacePath = null;
     for (const cb of exitListeners) {
@@ -418,6 +489,14 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
     }
   });
 
+  // 注入了 system prompt 文件时向终端打印一行提示(可见性/安全)；内部重启已抑制以免重复。
+  // 必须在 onData/onExit 注册之后再打(PR#128)，缩小「子进程在处理器挂载前退出」的丢事件窗口。
+  if (sysPrompt.loaded.length && !_suppressNextSpawnNotice) {
+    const modelSuffix = sysPrompt.model ? ` (model match: ${sysPrompt.model})` : '';
+    emitSpawnNotice(`[CC Viewer] loaded ${sysPrompt.loaded.join(', ')} as system prompt${modelSuffix}`);
+  }
+  _suppressNextSpawnNotice = false;
+
   return ptyProcess;
 }
 

package/server/routes/dingtalk.js

@@ -27,14 +27,20 @@ async function dingtalkStatus(req, res, parsedUrl, isLocal, deps) {
     conn = deps.dingtalk.getBridgeStatus();
   } else {
     processInfo = await deps.dingtalk.getProcessStatus();
-    conn = { running: processInfo.running, connected: processInfo.connected };
+    conn = {
+      running: processInfo.running,
+      connected: processInfo.connected,
+      connectionState: processInfo.connectionState,
+      lastError: processInfo.lastError ?? null,
+    };
   }
   res.writeHead(200, JSON_HEADERS);
   if (!isLocal) {
+    // connectionState passes through as-is; lastError stays loopback-only (mirrors routes/im.js).
     res.end(JSON.stringify({
       enabled: loadDingTalkState().enabled,
       hasSecret: loadDingTalkState().hasSecret,
-      connection: { running: conn.running, connected: conn.connected },
+      connection: { running: conn.running, connected: conn.connected, connectionState: conn.connectionState },
     }));
     return;
   }
@@ -93,7 +99,7 @@ function dingtalkConfigPost(req, res, parsedUrl, isLocal, deps) {
       console.error('[CC Viewer] IM config apply failed for dingtalk:', e?.message || e);
     }
     res.writeHead(200, JSON_HEADERS);
-    res.end(JSON.stringify({ ...loadDingTalkState(), connection: { running: !!(saved?.enabled ?? incoming.enabled), connected: false } }));
+    res.end(JSON.stringify({ ...loadDingTalkState(), connection: { running: !!(saved?.enabled ?? incoming.enabled), connected: false, connectionState: 'disconnected' } }));
   });
 }
 

package/server/routes/im.js

@@ -8,6 +8,11 @@
 //                                    runs with --dangerously-skip-permissions.
 //   POST /api/im/:platform/test    — loopback-only; validate creds (fetch an access token).
 //   POST /api/im/:platform/process — loopback-only; {action:start|stop|restart} the detached worker.
+//                                    'start' requires stored creds (400 `missing …` otherwise) and
+//                                    also persists enabled:true (merged into the stored config):
+//                                    a worker spawned while the config says disabled no-ops in
+//                                    im-bridge-core and would not survive a restart reconcile,
+//                                    so "start" must mean "enable + spawn".
 //   GET  /api/im/:platform/logs    — resolve the worker's latest .jsonl (for the records popup).
 //
 // Architecture: IM adapters no longer run in the main ccv. Each enabled IM runs as an independent
@@ -56,6 +61,27 @@ function secretKeys(id) {
   return getDescriptor(id).fields.filter((f) => f.type === 'secret').map((f) => f.key);
 }
 
+/** Required cred/secret field keys that are empty in `cfg` (same gate as the /test route). */
+function missingCreds(id, cfg) {
+  return getDescriptor(id).fields
+    .filter((f) => (f.type === 'cred' || f.type === 'secret') && !cfg[f.key])
+    .map((f) => f.key);
+}
+
+// Audit every path that flips a platform on with an empty sender allowlist (bind-first-conversation
+// under --dangerously-skip-permissions). Shared by config POST and process 'start' so no enabling
+// path can bypass the server-side warning — headless callers never see the frontend toast.
+function warnIfEmptyAllowlist(id, cfg) {
+  const allowField = getDescriptor(id).allowListField;
+  // 过滤空白项后再判空：saveConfig 会 normalize（trim+丢空），若只看原始长度，[" "] 这类全空白
+  // 白名单会被当成"已配置"而漏掉审计告警，但实际保存的是空名单（与 dingtalk 路由保持一致）。
+  const raw = Array.isArray(cfg[allowField]) ? cfg[allowField] : [];
+  const list = raw.filter((s) => typeof s === 'string' && s.trim());
+  if (list.length === 0) {
+    console.warn(`[CC Viewer] IM ${id} enabled with EMPTY allowlist — bind-first-conversation; the first conversation to message can drive this --dangerously-skip-permissions session`);
+  }
+}
+
 function readBody(req, deps, cb) {
   let body = '';
   req.on('data', (chunk) => {
@@ -79,16 +105,22 @@ async function imStatus(req, res, parsedUrl, isLocal, deps) {
   } else {
     // MAIN: the adapter runs in a detached worker, not here. Resolve process+connection via manager.
     processInfo = await deps.im.getProcessStatus(id);
-    connection = { running: processInfo.running, connected: processInfo.connected };
+    connection = {
+      running: processInfo.running,
+      connected: processInfo.connected,
+      connectionState: processInfo.connectionState,
+      lastError: processInfo.lastError ?? null,
+    };
   }
 
   res.writeHead(200, JSON_HEADERS);
   if (!isLocal) {
     // Loopback gate: a token-authorized LAN client sees only what the header chip needs.
+    // connectionState is passed through as-is (no defaulting); lastError stays loopback-only.
     res.end(JSON.stringify({
       enabled: state.enabled,
       hasSecret: state.hasSecret,
-      connection: { running: connection.running, connected: connection.connected },
+      connection: { running: connection.running, connected: connection.connected, connectionState: connection.connectionState },
     }));
     return;
   }
@@ -124,16 +156,7 @@ function imConfigPost(req, res, parsedUrl, isLocal, deps) {
     // bind-first-conversation（im-bridge-core.js）——首个向机器人发消息的会话被绑定，该会话内任何人
     // 都可无审批驱动本地会话。这里打一条服务端审计（curl/headless 启用走不到前端 toast），
     // PreToolUse permissions.deny 硬拦截（perm-bridge/im-deny，独立于白名单）仍然生效。
-    if (incoming.enabled) {
-      const allowField = getDescriptor(id).allowListField;
-      // 过滤空白项后再判空：saveConfig 会 normalize（trim+丢空），若只看原始长度，[" "] 这类全空白
-      // 白名单会被当成"已配置"而漏掉审计告警，但实际保存的是空名单（与 dingtalk 路由保持一致）。
-      const raw = Array.isArray(incoming[allowField]) ? incoming[allowField] : [];
-      const list = raw.filter((s) => typeof s === 'string' && s.trim());
-      if (list.length === 0) {
-        console.warn(`[CC Viewer] IM ${id} enabled with EMPTY allowlist — bind-first-conversation; the first conversation to message can drive this --dangerously-skip-permissions session`);
-      }
-    }
+    if (incoming.enabled) warnIfEmptyAllowlist(id, incoming);
     const saved = saveConfig(id, incoming);
     // applyProcess（默认 true，保持旧调用方语义）：前端 onBlur 自动保存传 false → 仅存盘、不驱动进程，
     // 否则每次输入框失焦都会重启 worker。显式「启动/停止」按钮则不传（=true），沿用下述驱动逻辑。
@@ -151,7 +174,7 @@ function imConfigPost(req, res, parsedUrl, isLocal, deps) {
     }
     res.writeHead(200, JSON_HEADERS);
     // 乐观返回：worker 刚 spawn 尚未就绪，避免回包瞬间显示"已停止"；chip 轮询会很快收敛到真实态。
-    res.end(JSON.stringify({ ...loadState(id), connection: { running: !!saved.enabled, connected: false } }));
+    res.end(JSON.stringify({ ...loadState(id), connection: { running: !!saved.enabled, connected: false, connectionState: 'disconnected' } }));
   });
 }
 
@@ -165,9 +188,7 @@ function imTestPost(req, res, parsedUrl, isLocal, deps) {
     const stored = loadConfig(id);
     const cfg = {};
     for (const f of getDescriptor(id).fields) cfg[f.key] = incoming[f.key] || stored[f.key];
-    const missing = getDescriptor(id).fields
-      .filter((f) => (f.type === 'cred' || f.type === 'secret') && !cfg[f.key])
-      .map((f) => f.key);
+    const missing = missingCreds(id, cfg);
     if (missing.length) {
       res.writeHead(200, JSON_HEADERS);
       res.end(JSON.stringify({ ok: false, detail: `missing ${missing.join('/')}` }));
@@ -195,8 +216,25 @@ function imProcessPost(req, res, parsedUrl, isLocal, deps) {
     try {
       if (action === 'stop') await deps.im.stopProcess(id);
       else if (action === 'restart') await deps.im.restartProcess(id);
-      else if (action === 'start') await deps.im.startProcess(id);
-      else {
+      else if (action === 'start') {
+        const cfg = loadConfig(id);
+        // Credential gate (same as /test): without creds the spawned worker's bridge no-ops
+        // forever, and persisting enabled:true would make reconcile respawn that zombie on
+        // every server restart. Reject up front — nothing is persisted, nothing is spawned.
+        const missing = missingCreds(id, cfg);
+        if (missing.length) {
+          res.writeHead(400, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: `missing ${missing.join('/')}`, detail: `missing ${missing.join('/')}` }));
+          return;
+        }
+        // Persist enabled:true first (read-merge-write keeps creds/allowlist intact): a worker
+        // spawned with enabled:false no-ops its bridge, and reconcile would not respawn it.
+        if (!cfg.enabled) {
+          warnIfEmptyAllowlist(id, cfg);
+          saveConfig(id, { ...cfg, enabled: true });
+        }
+        await deps.im.startProcess(id);
+      } else {
         res.writeHead(400, JSON_HEADERS);
         res.end(JSON.stringify({ error: 'action must be start|stop|restart' }));
         return;