cc-viewer 1.7.2 → 1.7.3

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-CjsQEQc2.js"></script>
+  <script type="module" crossorigin src="./assets/index-DidP9FCD.js"></script>
   <link rel="modulepreload" crossorigin href="./assets/vendor-antd-DI7JL-mE.js">
   <link rel="modulepreload" crossorigin href="./assets/vendor-codemirror-B9c49dtM.js">
   <link rel="modulepreload" crossorigin href="./assets/vendor-mdxeditor-B6cpBtIE.js">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-viewer",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Claude Code logging, visualization, and management toolkit — launch a web viewer alongside Claude Code with full request/response tracing, proxy, and mobile support",
   "license": "MIT",
   "main": "server.js",

package/server/i18n.js

@@ -142,6 +142,26 @@ const i18nData = {
     "tr": "   PATH'te de \"claude\" native komutu bulunamadı. @anthropic-ai/claude-code'un yüklü olduğundan emin olun",
     "uk": "   Також не знайдено нативну команду \"claude\" в PATH. Переконайтеся, що @anthropic-ai/claude-code встановлено"
   },
+  "cli.settingsMergeFailed": {
+    "zh": "⚠️  无法加载用户 --settings 值 {value}（{reason}），已仅以 CC Viewer 注入的 settings 启动",
+    "en": "⚠️  Could not load user --settings value {value} ({reason}); launching with CC Viewer's injected settings only",
+    "zh-TW": "⚠️  無法載入使用者 --settings 值 {value}（{reason}），已僅以 CC Viewer 注入的 settings 啟動",
+    "ko": "⚠️  사용자 --settings 값 {value}을(를) 로드할 수 없음({reason}), CC Viewer가 주입한 settings만으로 시작합니다",
+    "ja": "⚠️  ユーザーの --settings 値 {value} を読み込めません（{reason}）。CC Viewer が注入した settings のみで起動します",
+    "de": "⚠️  Der --settings-Wert des Benutzers {value} konnte nicht geladen werden ({reason}); Start nur mit den von CC Viewer injizierten Settings",
+    "es": "⚠️  No se pudo cargar el valor --settings del usuario {value} ({reason}); se inicia solo con los settings inyectados por CC Viewer",
+    "fr": "⚠️  Impossible de charger la valeur --settings de l'utilisateur {value} ({reason}) ; lancement avec uniquement les settings injectés par CC Viewer",
+    "it": "⚠️  Impossibile caricare il valore --settings dell'utente {value} ({reason}); avvio solo con i settings iniettati da CC Viewer",
+    "da": "⚠️  Kunne ikke indlæse brugerens --settings-værdi {value} ({reason}); starter kun med CC Viewers injicerede settings",
+    "pl": "⚠️  Nie można wczytać wartości --settings użytkownika {value} ({reason}); uruchamianie tylko z ustawieniami wstrzykniętymi przez CC Viewer",
+    "ru": "⚠️  Не удалось загрузить пользовательское значение --settings {value} ({reason}); запуск только с настройками, внедрёнными CC Viewer",
+    "ar": "⚠️  تعذّر تحميل قيمة --settings الخاصة بالمستخدم {value} ({reason})؛ سيتم التشغيل بإعدادات CC Viewer المحقونة فقط",
+    "no": "⚠️  Kunne ikke laste brukerens --settings-verdi {value} ({reason}); starter kun med CC Viewers injiserte settings",
+    "pt-BR": "⚠️  Não foi possível carregar o valor --settings do usuário {value} ({reason}); iniciando apenas com os settings injetados pelo CC Viewer",
+    "th": "⚠️  ไม่สามารถโหลดค่า --settings ของผู้ใช้ {value} ({reason}) จะเริ่มด้วย settings ที่ CC Viewer ฉีดเข้าไปเท่านั้น",
+    "tr": "⚠️  Kullanıcının --settings değeri {value} yüklenemedi ({reason}); yalnızca CC Viewer'ın enjekte ettiği settings ile başlatılıyor",
+    "uk": "⚠️  Не вдалося завантажити користувацьке значення --settings {value} ({reason}); запуск лише з налаштуваннями, впровадженими CC Viewer"
+  },
   "cli.inject.notFound": {
     "zh": "❌ 找不到 Claude Code cli.js: {path}",
     "en": "❌ Claude Code cli.js not found: {path}",

package/server/interceptor.js

@@ -306,7 +306,10 @@ export function getLiveLogSource() {
     // newest dir once its first main req is written) — handing back exactly the
     // blank in-flight session the strict gate rejected. Excluding it makes the
     // fallback actually land on the previous, renderable conversation.
-    const fallback = latestMainSessionDir(join(LOG_DIR, sanitizePathComponent(_projectName)), { excludeDir: dir });
+    // skipForeignLive: a parallel ccv window's in-flight session must never be
+    // served as THIS window's cold load (multi-window isolation); a crashed
+    // window's claim expires with its pid, so its session stays selectable.
+    const fallback = latestMainSessionDir(join(LOG_DIR, sanitizePathComponent(_projectName)), { excludeDir: dir, skipForeignLive: true });
     // A current-but-empty session with nothing else on disk: '' (still empty,
     // but the live feed fills it in place — no worse than before the fix).
     return fallback || dir || '';
@@ -316,6 +319,47 @@ export function getLiveLogSource() {
   }
 }
 
+// SessionStart hook notify (session-start-bridge.js → /api/session-start-notify
+// → server.js deps). The only source acted on is 'resume': an in-terminal
+// /resume switches the running claude to a PAST conversation while the wire
+// session_id may stay the same, so without this signal the writer keeps
+// routing the resumed conversation into the OLD session dir (and the panel —
+// keyed on `_seqEpoch = v2:<dir identity>` — never switches). The transcript
+// basename is the resumed conversation's stable identity; the hook session_id
+// is a fresh uuid usable as the new dir identity when nothing was recorded.
+// 'startup'/'clear'/'compact' are deliberately ignored (startup needs nothing;
+// /clear already has epoch machinery; teammate processes inherit
+// CCVIEWER_PORT and fire startup events at this endpoint — the source gate
+// drops them).
+export function markSessionStart(payload) {
+  try {
+    const { source, sessionId, transcriptPath, cwd } = payload || {};
+    if (source !== 'resume') return;
+    if (!transcriptPath || typeof transcriptPath !== 'string') {
+      console.warn('[ccv session-start] resume signal without transcript_path — ignored');
+      return;
+    }
+    // Soft cross-project guard: a foreign project's claude that somehow
+    // carries our CCVIEWER_PORT must not re-bind THIS project's writer. Only
+    // enforced when both sides are known (workspace mode may leave
+    // _projectName empty until bound).
+    if (cwd && typeof cwd === 'string' && _projectName) {
+      const cwdProject = basename(cwd).replace(/[^a-zA-Z0-9_\-\.]/g, '_');
+      if (cwdProject !== _projectName) {
+        console.warn(`[ccv session-start] resume signal from project "${cwdProject}" ignored (bound to "${_projectName}")`);
+        return;
+      }
+    }
+    const transcriptUuid = basename(transcriptPath, '.jsonl');
+    _v2Writer.beginResumeSwitch({
+      transcriptUuid,
+      hookSid: (typeof sessionId === 'string' && sessionId) ? sessionId : null,
+    });
+  } catch (err) {
+    reportSwallowed('session-start.mark', err);
+  }
+}
+
 // P2 (-c migration guidance): three detection channels, any one marks this
 // launch as "continuing an older conversation" — the migrate prompt then
 // re-prompts even a dismissed user, because the conversation's first half

package/server/lib/ensure-hooks.js

@@ -78,7 +78,7 @@ function _looksStaleManagedCommand(cmd) {
 
 function _purgeStaleManagedHooks(settings) {
   let removed = 0;
-  for (const sectionKey of ['PreToolUse', 'Stop']) {
+  for (const sectionKey of ['PreToolUse', 'Stop', 'SessionStart']) {
     const arr = settings.hooks?.[sectionKey];
     if (!Array.isArray(arr)) continue;
     for (let i = arr.length - 1; i >= 0; i--) {
@@ -99,7 +99,7 @@ function _purgeStaleManagedHooks(settings) {
 // 调用方负责 atomic write-back。返回 removed 数量。
 export function removeAllManagedHooks(settings) {
   let removed = 0;
-  for (const sectionKey of ['PreToolUse', 'Stop']) {
+  for (const sectionKey of ['PreToolUse', 'Stop', 'SessionStart']) {
     const arr = settings.hooks?.[sectionKey];
     if (!Array.isArray(arr)) continue;
     for (let i = arr.length - 1; i >= 0; i--) {
@@ -129,6 +129,7 @@ export function ensureHooks() {
     if (!settings.hooks) settings.hooks = {};
     if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
     if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+    if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
 
     let changed = false;
     // 先一次性清掉「path 已 stale 但还带 cc-viewer-managed marker」的老条目，
@@ -214,6 +215,31 @@ export function ensureHooks() {
       changed = true;
     }
 
+    // SessionStart hook → session-start-bridge.js. Fires on startup/resume/
+    // clear/compact; no matcher (= all sources) — the bridge forwards `source`
+    // and the server gates on it. The `resume` source is the conversation-
+    // switch signal the V2Writer needs to re-bind routing after an in-terminal
+    // /resume (the wire session_id may not change, so no wire-level signal
+    // exists). Same CCVIEWER_PORT guard pattern as the other bridges.
+    const sessionStartBridgePath = resolve(SERVER_LIB, 'session-start-bridge.js');
+    const sessionStartCmd = `[ -n "$CCVIEWER_PORT" ] && node "${sessionStartBridgePath}" || true ${CCV_HOOK_MARKER}`;
+    const sessionStartDesired = _buildHookObj(sessionStartCmd);
+    const sessionStartExisting = settings.hooks.SessionStart.find(h => {
+      const cmd = h.hooks?.[0]?.command || '';
+      return cmd.includes('session-start-bridge.js');
+    });
+    if (sessionStartExisting) {
+      if (!_hookObjEqual(sessionStartExisting.hooks?.[0], sessionStartDesired)) {
+        sessionStartExisting.hooks = [_mergeHookObj(sessionStartExisting.hooks?.[0], sessionStartDesired)];
+        changed = true;
+      }
+    } else {
+      settings.hooks.SessionStart.push({
+        hooks: [sessionStartDesired],
+      });
+      changed = true;
+    }
+
     if (changed) {
       mkdirSync(claudeDir, { recursive: true });
       // Atomic write(): write to a sibling temp file then rename. Concurrent

package/server/lib/log-watcher.js

@@ -92,7 +92,12 @@ function _safeSseWrite(clients, client, payload) {
   return true;
 }
 
+// Zero-client short-circuit (all four senders): the payload template is built
+// BEFORE the client loop, so with no SSE consumer connected every broadcast
+// still paid a full JSON.stringify — for reconstructed entries carrying
+// cumulative messages that is a giant allocation for nothing.
 export function sendToClients(clients, entry) {
+  if (clients.length === 0) return;
   const payload = `data: ${JSON.stringify(entry)}\n\n`;
   for (let i = clients.length - 1; i >= 0; i--) {
     _safeSseWrite(clients, clients[i], payload);
@@ -100,6 +105,7 @@ export function sendToClients(clients, entry) {
 }
 
 export function sendEventToClients(clients, eventName, data) {
+  if (clients.length === 0) return;
   const payload = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
   for (let i = clients.length - 1; i >= 0; i--) {
     _safeSseWrite(clients, clients[i], payload);
@@ -109,6 +115,7 @@ export function sendEventToClients(clients, eventName, data) {
 /** Like sendEventToClients but `json` is an ALREADY-serialized JSON string —
  *  wire v3 forwards raw stored lines verbatim without a parse/stringify trip. */
 export function sendEventRawToClients(clients, eventName, json) {
+  if (clients.length === 0) return;
   const payload = `event: ${eventName}\ndata: ${json}\n\n`;
   for (let i = clients.length - 1; i >= 0; i--) {
     _safeSseWrite(clients, clients[i], payload);
@@ -116,6 +123,7 @@ export function sendEventRawToClients(clients, eventName, json) {
 }
 
 export function sendChunkToClients(clients, dataJson) {
+  if (clients.length === 0) return;
   const payload = `event: load_chunk\ndata: ${dataJson}\n\n`;
   for (let i = clients.length - 1; i >= 0; i--) {
     _safeSseWrite(clients, clients[i], payload);

package/server/lib/pid-alive.js

@@ -0,0 +1,15 @@
+// Process-liveness probe shared by pid-validity claims (session-owner.js).
+// Deliberately dependency-free: im-lock.js's identical helper drags findcc.js
+// (LOG_DIR env resolution, a top-level node:worker_threads threadId import)
+// into every importer's module graph — the stats worker's loader shim has no
+// threadId export, and the v2 writer's synchronous ingest path doesn't want
+// node:http along for the ride. im-lock.js / async-file-lock.js keep their
+// local copies (same semantics); consolidation is backlog.
+
+/** Is `pid` alive? Signal 0 probes without delivering; EPERM means the
+ *  process exists but belongs to another user (still alive). */
+export function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}

package/server/lib/session-start-bridge.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * session-start-bridge.js — SessionStart hook bridge for conversation-switch
+ * signals (in-terminal /resume, and future /clear / compact interest).
+ *
+ * Called by Claude Code whenever a session (re)starts: source is one of
+ * "startup" | "resume" | "clear" | "compact". The one that matters today is
+ * `resume` — an in-terminal /resume switches the running process to a PAST
+ * conversation while the wire session_id may stay the same, so without this
+ * signal cc-viewer keeps writing the resumed conversation into the OLD
+ * session dir and the [对话] panel never switches. The bridge forwards the
+ * hook payload to cc-viewer's /api/session-start-notify; the server gates on
+ * source and tells the V2Writer to re-bind routing (see v2-writer.js
+ * beginResumeSwitch).
+ *
+ * Hook config in ~/.claude/settings.json (injected by ensure-hooks.js, tagged
+ * `# cc-viewer-managed`):
+ *   "hooks": {
+ *     "SessionStart": [{ "hooks": [{ "type": "command",
+ *       "command": "[ -n \"$CCVIEWER_PORT\" ] && node /path/to/session-start-bridge.js || true # cc-viewer-managed" }] }]
+ *   }
+ *
+ * Output contract (same as turn-end-bridge.js): NOTHING on stdout — Claude
+ * Code interprets SessionStart hook stdout as context-injection JSON
+ * (hookSpecificOutput.additionalContext), and any stray bytes would pollute
+ * the conversation. Optional stderr only when CCVIEWER_DEBUG=1. Always exit 0
+ * so a failed notify never blocks Claude Code's hook chain.
+ */
+
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+
+const debug = (msg) => {
+  if (process.env.CCVIEWER_DEBUG === '1') {
+    try { process.stderr.write(`[session-start-bridge] ${msg}\n`); } catch { /* ignore */ }
+  }
+};
+
+const port = process.env.CCVIEWER_PORT;
+const rawProtocol = process.env.CCVIEWER_PROTOCOL;
+const isHttps = rawProtocol === 'https';
+const httpClient = isHttps ? https : http;
+
+// cc-viewer not running — exit silently (stdout must stay clean, see header).
+if (!port) {
+  debug('CCVIEWER_PORT unset — exit silently');
+  process.exit(0);
+}
+
+// Drain stdin best-effort. Claude Code passes the hook JSON payload
+// ({session_id, transcript_path, source, cwd, ...}); capped to 64 KB to
+// defang any malformed huge payload.
+let stdinData = '';
+try {
+  const buf = readFileSync(0);
+  stdinData = (buf.length > 64 * 1024 ? buf.slice(0, 64 * 1024) : buf).toString('utf-8');
+} catch { /* stdin may not be piped — fine, still notify */ }
+let sessionId = null;
+let transcriptPath = null;
+let source = null;
+let cwd = null;
+try {
+  const parsed = JSON.parse(stdinData);
+  sessionId = parsed?.session_id || null;
+  transcriptPath = parsed?.transcript_path || null;
+  source = parsed?.source || null;
+  cwd = parsed?.cwd || null;
+} catch { /* fine — the server tolerates missing fields */ }
+debug(`payload source=${source} session_id=${sessionId} transcript=${transcriptPath}`);
+
+const internalToken = process.env.CCVIEWER_INTERNAL_TOKEN || '';
+const body = JSON.stringify({ source, sessionId, transcriptPath, cwd, ts: Date.now() });
+const reqOpts = {
+  hostname: '127.0.0.1',
+  port: parseInt(port, 10),
+  path: '/api/session-start-notify',
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+    // Same anti-spoof header as turn-end-bridge: matched against the server's
+    // per-startup INTERNAL_TOKEN, env-leaked only to the claude child.
+    ...(internalToken ? { 'X-CCViewer-Internal': internalToken } : {}),
+  },
+  // Keep the timeout snappy so a stale cc-viewer never blocks the Claude Code
+  // hook chain for a noticeable beat.
+  timeout: 500,
+};
+if (isHttps) {
+  // Loopback HTTPS is typically self-signed; validation would reject.
+  reqOpts.rejectUnauthorized = false;
+}
+
+let exited = false;
+const finish = (reason) => {
+  if (exited) return;
+  exited = true;
+  if (reason) debug(reason);
+  process.exit(0);
+};
+
+let req;
+try {
+  req = httpClient.request(reqOpts, (res) => {
+    res.resume();
+    res.on('end', () => finish(`POST done (status=${res.statusCode})`));
+  });
+  req.on('error', (err) => finish(`POST error: ${err?.message}`));
+  req.on('timeout', () => { try { req.destroy(); } catch { /* ignore */ } finish('POST timeout'); });
+  // Wrap the synchronous write/end so an immediate EPIPE never bubbles into
+  // Claude Code's transcript (same defensive shape as turn-end-bridge).
+  try {
+    req.write(body);
+    req.end();
+  } catch (err) {
+    finish(`req.write threw: ${err?.message}`);
+  }
+} catch (err) {
+  finish(`request() threw: ${err?.message}`);
+}

package/server/lib/settings-merge.js

@@ -0,0 +1,170 @@
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// Settings files are tiny in practice; this caps a hostile `--settings /dev/zero`
+// (a never-EOF read that would hang the server event loop) or a huge-file read.
+const MAX_SETTINGS_FILE_BYTES = 1024 * 1024;
+
+// Merges a user-supplied `--settings` launch arg into cc-viewer's injected settings
+// object, so the final claude argv carries a SINGLE `--settings` flag.
+//
+// Why: claude's argv parser is last-wins for duplicate `--settings` (empirically
+// verified on 2.1.212 — not documented). cc-viewer prepends its injected flag before
+// user args, so a user-supplied `--settings` used to silently clobber the injected
+// env.ANTHROPIC_BASE_URL proxy override (breaking capture) and the CCV_IM_DENY
+// permissions.deny hardening. Merging keeps both: injected keys win, everything
+// else the user set rides along.
+//
+// Parse rules pinned by experiments against claude 2.1.212:
+// - Tokens after a literal `--` are prompt text, never flags → scan stops there.
+// - `--settings <next>` consumes the next token as its value unconditionally, even
+//   an option-like one (`--settings --print` → claude reads "--print" as a settings
+//   path and hard-errors). The helper mirrors that consumption.
+// - A trailing valueless `--settings` makes claude exit with "argument missing" →
+//   left in place so claude surfaces its own usage error, exactly as pre-fix.
+// - An empty `--settings=` does NOT error but still clobbers earlier `--settings`
+//   flags via last-wins (the most dangerous form) → always stripped.
+//
+// Known accepted limitation (shared with withDefaultThinkingDisplay / hasArg): a
+// literal "--settings" appearing before `--` as ANOTHER value-flag's argument
+// (e.g. `--append-system-prompt "--settings"`) is indistinguishable without a full
+// claude flag table. Probability negligible; bounded by the stop-at-`--` rule.
+
+const FLAG = '--settings';
+
+function stripBom(s) {
+  return s.charCodeAt(0) === 0xFEFF ? s.slice(1) : s;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Remove C0 control chars (and DEL) so a value/reason echoed into the embedded xterm
+// (via emitSpawnNotice) or a log line cannot inject ANSI escape sequences — the raw
+// user value and a JSON.parse SyntaxError can both carry ESC bytes.
+function stripControls(s) {
+  return String(s).replace(/[\u0000-\u001F\u007F]/g, '');
+}
+
+// Read + parse a user-pointed settings file DEFENSIVELY. The failure reason is echoed
+// into a client-readable surface (the persistent terminal buffer + logs), so it must
+// never disclose file contents or resolved paths — a raw readFileSync/JSON.parse error
+// embeds the leading file bytes and the absolute path, turning the warning into a
+// file-probing oracle. All failures collapse to generic, content-free messages; a
+// statSync isFile()+size gate blocks /dev/zero-style hangs and oversized reads.
+function readSettingsFile(path) {
+  let st;
+  try { st = statSync(path); } catch { throw new Error('settings file not found'); }
+  if (!st.isFile()) throw new Error('settings path is not a regular file');
+  if (st.size > MAX_SETTINGS_FILE_BYTES) throw new Error('settings file too large');
+  let raw;
+  try { raw = stripBom(readFileSync(path, 'utf8')); } catch { throw new Error('settings file could not be read'); }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { throw new Error('settings file is not valid JSON'); }
+  if (!isPlainObject(parsed)) throw new Error('settings file must be a JSON object');
+  return parsed;
+}
+
+// Load a --settings value the way claude does: inline JSON when it looks like an
+// object literal, otherwise a settings file path (resolved against the cwd claude
+// itself will run with). Throws on any failure — caller turns that into a warning.
+function loadSettingsValue(value, cwd) {
+  const trimmed = stripBom(value).trim();
+  if (trimmed === '') throw new Error('empty value');
+  if (trimmed.startsWith('{')) {
+    // Inline JSON is the user's own text; echoing it back on failure is not disclosure
+    // (control chars are stripped at the warning surface). File contents are different —
+    // handled by readSettingsFile, which never surfaces them.
+    const parsed = JSON.parse(trimmed);
+    if (!isPlainObject(parsed)) throw new Error('settings must be a JSON object');
+    return parsed;
+  }
+  return readSettingsFile(resolve(cwd, trimmed));
+}
+
+// Shallow top-level merge with two special cases; injected keys win. Deep-merging
+// other keys (hooks, statusLine, ...) would splice into structures the user owns.
+function mergeSettings(userSettings, injectedSettings) {
+  const merged = { ...userSettings };
+  for (const [key, injectedValue] of Object.entries(injectedSettings)) {
+    if (key === 'env' && isPlainObject(merged.env)) {
+      merged.env = { ...merged.env, ...injectedValue };
+    } else if (key === 'permissions' && isPlainObject(merged.permissions)) {
+      const userDeny = Array.isArray(merged.permissions.deny) ? merged.permissions.deny : [];
+      const injectedDeny = Array.isArray(injectedValue.deny) ? injectedValue.deny : [];
+      merged.permissions = {
+        ...merged.permissions,
+        ...injectedValue,
+        deny: [...new Set([...userDeny, ...injectedDeny])],
+      };
+    } else {
+      merged[key] = injectedValue;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Extract any user `--settings` occurrences from launch args and merge the last
+ * one into the injected settings object (injected keys win; permissions.deny is
+ * unioned). Never throws — a value that cannot be loaded is dropped and reported
+ * via `warningDetail` so the caller can surface it (injection must never block spawn).
+ *
+ * @param {unknown} args launch args (user-controlled; may contain non-strings)
+ * @param {object} injectedSettings cc-viewer's settings object (env.ANTHROPIC_BASE_URL, optional permissions.deny)
+ * @param {{cwd?: string}} [opts] base dir for relative settings file paths — must match the cwd claude runs with
+ * @returns {{args: unknown[], settingsJson: string, merged: boolean, warningDetail: {value: string, reason: string}|null}}
+ *   args: input args with consumed `--settings` occurrences removed;
+ *   settingsJson: JSON for the single injected flag (byte-identical to
+ *   JSON.stringify(injectedSettings) when nothing merged);
+ *   merged: whether a user value was folded in; warningDetail: load-failure parts
+ *   ({value, reason}, control-chars stripped) for the caller to render/localize —
+ *   the English sentence lives only in the `cli.settingsMergeFailed` i18n key, so
+ *   there is no duplicated copy here to drift.
+ */
+export function mergeSettingsIntoArgs(args, injectedSettings, { cwd = process.cwd() } = {}) {
+  const passthrough = { merged: false, warningDetail: null, settingsJson: JSON.stringify(injectedSettings) };
+  if (!Array.isArray(args)) return { args: [], ...passthrough };
+
+  const cleaned = [];
+  let lastValue = null; // last consumed --settings value (claude is last-wins)
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (typeof token !== 'string') { cleaned.push(token); continue; }
+    if (token === '--') { cleaned.push(...args.slice(i)); break; }
+    if (token.startsWith(FLAG + '=')) {
+      lastValue = token.slice(FLAG.length + 1); // may be '' — still stripped (empty form clobbers via last-wins)
+      continue;
+    }
+    if (token === FLAG) {
+      if (i + 1 >= args.length) { cleaned.push(token); continue; } // trailing valueless: claude errors "argument missing" itself
+      lastValue = args[i + 1];
+      i++;
+      continue;
+    }
+    cleaned.push(token);
+  }
+
+  if (lastValue === null) return { args: cleaned, ...passthrough };
+
+  try {
+    if (typeof lastValue !== 'string') throw new Error('value is not a string');
+    const userSettings = loadSettingsValue(lastValue, cwd);
+    return {
+      args: cleaned,
+      settingsJson: JSON.stringify(mergeSettings(userSettings, injectedSettings)),
+      merged: true,
+      warningDetail: null,
+    };
+  } catch (err) {
+    const shown = typeof lastValue === 'string' ? lastValue : String(lastValue);
+    // Strip control chars: `shown` is raw user input and `err.message` from an inline
+    // JSON.parse can echo user bytes — both flow into the terminal buffer / logs.
+    return {
+      args: cleaned,
+      ...passthrough,
+      warningDetail: { value: stripControls(shown), reason: stripControls(err?.message || err) },
+    };
+  }
+}