cc-viewer 1.7.2 → 1.7.4

package/server/lib/v2/session-owner.js

@@ -0,0 +1,135 @@
+// Per-session-dir live-owner claim (multi-window log isolation, 2026-07-17).
+//
+// Problem: every ccv window (one process = V2Writer + viewer server) writes
+// into the SHARED `LOG_DIR/<project>/sessions/` root. The "newest session"
+// selectors (cold-load fallback, `-c` folder adoption) and the live feed's
+// whole-root follow have no notion of "which process owns which dir", so
+// parallel windows on one project cross-read (and, via adoption, cross-WRITE)
+// each other's sessions.
+//
+// Mechanism: the writing process claims its session dir with an `owner.lock`
+// sidecar `{pid, startedAt}`. The file is only a POINTER — the claim's
+// validity is "the owning process is alive" (`process.kill(pid, 0)`, a
+// kernel-memory fact), so a crashed owner's claim expires the instant the
+// process dies and a dir can never be locked forever. Same liveness model as
+// im-lock.js / log-management.js. The sidecar never touches journal /
+// conversations / blobs — it is not part of the wire format.
+//
+// Error-direction asymmetry (deliberate — each path errs toward its safe side):
+// - acquire: an unreadable/half-written lock is treated as HELD (refuse) —
+//   worst case the caller mints a fresh dir, which is Claude Code's own
+//   `-c` fork semantics anyway; never two writers on one journal.
+// - isForeignLiveOwned: an unreadable lock is treated as UNOWNED (readable) —
+//   a torn crash residue must never permanently gate a dir out of the live
+//   feed / cold-load fallback.
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPidAlive } from '../pid-alive.js';
+import { reportSwallowed } from '../error-report.js';
+
+export const OWNER_LOCK_NAME = 'owner.lock';
+
+// Contention retries for the wx create-exclusive acquire (im-lock precedent).
+const MAX_CLAIM_ATTEMPTS = 3;
+
+export function ownerLockPath(dir) { return join(dir, OWNER_LOCK_NAME); }
+
+/** Read the claim; missing / half-written / non-object → null (tolerated,
+ *  never grounds for deletion here — acquire has its own recycle rules). */
+export function readSessionClaim(dir) {
+  try {
+    const o = JSON.parse(readFileSync(ownerLockPath(dir), 'utf-8'));
+    return (o && typeof o === 'object') ? o : null;
+  } catch { return null; }
+}
+
+/**
+ * Atomically claim `dir` for `pid` (default: this process). Modeled on
+ * im-lock.js acquireImLock: `wx` create-exclusive IS the arbiter, so two
+ * processes racing to adopt the same dead-owned dir get exactly one winner.
+ * Two DELIBERATE divergences from that model (don't "fix" them back):
+ * own-pid holder → idempotent {ok:true} without rewriting (acquire runs twice
+ * per dir: adoption, then _session), where im-lock recycles its own residue;
+ * and content is written in the same call as creation ('wx' flag) — no
+ * empty-file window between sentinel and payload, so no temp+rename step.
+ * `startedAt` is diagnostic only — validity is pid-liveness alone (the
+ * accepted im-lock-style pid-reuse tradeoff; a socket-bind probe would close
+ * it and is backlog).
+ *
+ * @param {string} dir - absolute session dir
+ * @param {{pid?: number, pidAlive?: (pid:number)=>boolean}} [opts] test seams
+ * @returns {{ok:true}|{ok:false, holder?:object|null}} ok:false = cannot
+ *   claim, for any of: a live foreign holder, an unreadable/half-written lock
+ *   (conservatively treated as held), an unexpected write I/O failure
+ *   (reported via reportSwallowed), or contention exhausting the retries.
+ *   `holder` is set only when a live foreign pid was identified. Either way
+ *   the caller must NOT write into this dir (adoption: mint a fresh one).
+ */
+export function acquireSessionClaim(dir, opts = {}) {
+  const pid = opts.pid ?? process.pid;
+  const pidAlive = opts.pidAlive || isPidAlive;
+  const p = ownerLockPath(dir);
+  for (let attempt = 0; attempt < MAX_CLAIM_ATTEMPTS; attempt++) {
+    try {
+      writeFileSync(p, JSON.stringify({ pid, startedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+      return { ok: true };
+    } catch (e) {
+      if (!e || e.code !== 'EEXIST') {
+        // Unexpected I/O failure (EACCES, EROFS, fd exhaustion…): a silently
+        // missing claim means the isolation quietly stops working — report.
+        reportSwallowed('v2-owner.claim', e);
+        return { ok: false, holder: null };
+      }
+      const holder = readSessionClaim(dir);
+      if (holder && holder.pid === pid) return { ok: true }; // idempotent re-entry
+      if (holder && pidAlive(holder.pid)) return { ok: false, holder };
+      if (!holder) {
+        // Unreadable: either a concurrent recycler unlinked it between our
+        // EEXIST and the read (→ retry the atomic create) or it is genuinely
+        // half-written (→ conservatively held; the writer is mid-claim).
+        if (!existsSync(p)) continue;
+        return { ok: false, holder: null };
+      }
+      // Dead holder → recycle the stale lock and retry the atomic create.
+      try { unlinkSync(p); } catch { /* concurrent recycler won the unlink — retry */ }
+    }
+  }
+  // Contention exhausted the retries: report the current holder if live.
+  const holder = readSessionClaim(dir);
+  if (holder && holder.pid !== pid && pidAlive(holder.pid)) return { ok: false, holder };
+  return { ok: false, holder: holder || null };
+}
+
+/**
+ * Release the claim on `dir` — identity-checked: only unlinks when the lock
+ * is held by `pid` (default: this process), so a successor process's claim is
+ * never deleted by a late-exiting predecessor. Missing file = already
+ * released. Synchronous on purpose: it runs at the top of V2Writer.close()
+ * ahead of the (bounded, raceable) async queue drain.
+ * @returns {boolean} true when the dir is no longer claimed by `pid`
+ */
+export function releaseSessionClaim(dir, opts = {}) {
+  const pid = opts.pid ?? process.pid;
+  const holder = readSessionClaim(dir);
+  if (holder && holder.pid !== pid) return false; // taken over — don't touch
+  try { unlinkSync(ownerLockPath(dir)); } catch { /* ENOENT = already released */ }
+  return true;
+}
+
+/**
+ * Is `dir` exclusively owned by ANOTHER live process? The single skip
+ * predicate used by latestMainSession (cold-load fallback + `-c` adoption
+ * candidates) and the live feed's attach/re-check gates. History readers
+ * never call this — a dead owner's claim makes the dir plain unowned data.
+ * @param {string} dir - absolute session dir
+ * @param {{pid?: number, pidAlive?: (pid:number)=>boolean}} [opts] test seams
+ * @returns {boolean}
+ */
+export function isForeignLiveOwned(dir, opts = {}) {
+  const pid = opts.pid ?? process.pid;
+  const pidAlive = opts.pidAlive || isPidAlive;
+  const holder = readSessionClaim(dir); // unreadable → null → unowned (self-healing)
+  if (!holder || !Number.isInteger(holder.pid)) return false;
+  return holder.pid !== pid && pidAlive(holder.pid);
+}

package/server/lib/v2/session-select.js

@@ -24,6 +24,7 @@ import { join } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 import { listSessionIds } from './replay.js';
 import { isSupportedWireFormat } from './layout.js';
+import { isForeignLiveOwned } from './session-owner.js';
 
 /**
  * Find the on-disk dir NAME of an existing session for `sessionId` (a UUID), or
@@ -247,17 +248,29 @@ export function isDiscardableSession(dir, meta) {
  * has-a-main-req gate would otherwise re-select exactly the dir the caller's
  * completed-turn gate just rejected (it IS the newest once its first main req
  * is written), nullifying the fallback.
+ *
+ * `skipForeignLive` (multi-window isolation, 2026-07-17) drops candidates
+ * whose `owner.lock` is held by ANOTHER live process — a parallel ccv window's
+ * in-flight session. Without it, the cold-load fallback serves the other
+ * window's conversation and `-c` adoption writes into its journal. A dead
+ * owner's claim expires with its pid (kernel liveness), so crashed windows'
+ * sessions stay selectable — never a permanent lock. Both consumers
+ * (getLiveLogSource fallback, _resolveAdoption) pass true; default false keeps
+ * the raw picker semantics for everything else.
  * @param {string} projectDir - absolute LOG_DIR/<project>
- * @param {{excludeDir?: string}} [opts]
+ * @param {{excludeDir?: string, skipForeignLive?: boolean}} [opts]
  * @returns {{dir:string, sessionId:string}|null}
  */
-export function latestMainSession(projectDir, { excludeDir = '' } = {}) {
+export function latestMainSession(projectDir, { excludeDir = '', skipForeignLive = false } = {}) {
   if (!projectDir) return null;
   const candidates = []; // { dir, sessionId, startTs }
   for (const name of listSessionIds(projectDir)) {
     const dir = join(projectDir, 'sessions', name);
     if (excludeDir && dir === excludeDir) continue;
     if (!existsSync(join(dir, 'journal.jsonl'))) continue;
+    // After the cheaper journal-existence reject: skips one owner.lock read
+    // per torn/non-session dir on large-history cold loads.
+    if (skipForeignLive && isForeignLiveOwned(dir)) continue;
     let meta = null;
     try { meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { continue; }
     if (!meta) continue;

package/server/lib/v2/v2-writer.js

@@ -22,6 +22,7 @@ import { AsyncWriteQueue } from '../async-write-queue.js';
 import { reportSwallowed } from '../error-report.js';
 import { ensureSessionDirSync, compactLocalTs14, sanitizePathComponent } from './layout.js';
 import { resolveSessionDirName, latestMainSession } from './session-select.js';
+import { acquireSessionClaim, releaseSessionClaim, isForeignLiveOwned } from './session-owner.js';
 import { BlobStore } from './blob-store.js';
 import { Journal } from './journal.js';
 import { ConversationStore } from './conversation-store.js';
@@ -76,6 +77,10 @@ export class V2Writer {
     // latency. Purely a nudge — the feed's data source stays the files.
     this._onActivity = typeof opts.onActivity === 'function' ? opts.onActivity : null;
     this._sessions = new Map(); // sessionId → {paths, blobs, journal, convs, resolver}
+    // Multi-window isolation (2026-07-17): session dirs this process has
+    // claimed via owner.lock. Released synchronously in resetSessions()/close()
+    // — a crash skips release harmlessly (claim validity is pid liveness).
+    this._claimedDirs = new Set();
     this._currentSid = null;    // last successfully resolved session (fallback routing §8.3)
     this._pendingNoSid = [];    // requests seen before any sid (cold-start heartbeats).
     // Contract with the caller: originalMessages held here must be a reference
@@ -92,6 +97,12 @@ export class V2Writer {
     this._forkSession = false;
     this._resumeSession = false;
     this._adopted = false;
+    // In-terminal /resume switch (SessionStart hook, source:'resume'): the
+    // next MAIN request must be re-routed to the resumed conversation's dir.
+    // {transcriptUuid, hookSid} | null; last-wins, consumed one-shot, no TTL
+    // (after a /resume the next main request belongs to the resumed
+    // conversation no matter how much later it is typed).
+    this._pendingResumeSwitch = null;
   }
 
   /** P2: true once any session's FIRST main wire already carried assistant
@@ -141,11 +152,126 @@ export class V2Writer {
     if (!m || m.length <= 1 || !m.some((x) => x && x.role === 'assistant')) return null;
     const projectDir = join(this._logDir, sanitizePathComponent(project));
     if (resolveSessionDirName(projectDir, sid, this._sessionsDirName)) return null; // same-UUID restart
-    const prev = latestMainSession(projectDir);
+    // Multi-window isolation: never adopt a dir another LIVE window is writing
+    // (that is the two-writers-one-journal corruption), and CLAIM the picked
+    // dir atomically BEFORE committing — two simultaneous `-c` launches racing
+    // onto the same dead-owned dir get exactly one adopter via the owner.lock
+    // 'wx' arbiter; the loser falls through to a fresh dir, which is Claude
+    // Code's own continue/fork semantics (fresh wire sid per continue).
+    // skipForeignLive is deliberately UNCONDITIONAL while the claim below is
+    // _claimsEnabled()-gated: a non-claiming writer must still never adopt a
+    // live window's dir — it just doesn't stamp ownership of its own.
+    const prev = latestMainSession(projectDir, { skipForeignLive: true });
     if (!prev || !prev.sessionId) return null;
+    if (this._claimsEnabled()) {
+      if (!acquireSessionClaim(prev.dir).ok) return null;
+      // Record immediately (not only in _session): a throw between here and
+      // _session must not leak an untracked lock file until process exit.
+      this._claimedDirs.add(prev.dir);
+    }
     return { dirName: basename(prev.dir), identityUUID: prev.sessionId };
   }
 
+  /** In-terminal /resume signal (interceptor.markSessionStart → here): arm a
+   *  one-shot routing switch. `transcriptUuid` is the resumed conversation's
+   *  stable identity (transcript basename); `hookSid` is the fresh session
+   *  uuid the hook minted — used as the NEW dir identity when the resumed
+   *  conversation was never recorded by ccv (it must not be the old wire sid:
+   *  `<ts>_<oldSid>` would be re-resolved back to the OLD dir by
+   *  resolveSessionDirName). Last-wins across repeated /resume picks. */
+  beginResumeSwitch({ transcriptUuid, hookSid } = {}) {
+    try {
+      if (!transcriptUuid || typeof transcriptUuid !== 'string') return;
+      this._pendingResumeSwitch = {
+        transcriptUuid,
+        hookSid: (typeof hookSid === 'string' && hookSid) ? hookSid : null,
+      };
+    } catch (err) {
+      reportSwallowed('v2-write.resume-switch', err);
+    }
+  }
+
+  /**
+   * Consume the pending /resume switch for the arriving MAIN request: pick
+   * the target dir, take its claim, drop the old same-sid binding, and return
+   * an adoptTarget for `_session()` (the same channel `-c` adoption uses).
+   * Target precedence: the recorded dir of the resumed conversation
+   * (resolveSessionDirName by transcript uuid — the log re-joins its original
+   * folder, identity preserved) unless another LIVE window holds its claim
+   * (acquire fails → fork semantics, mirror of `_resolveAdoption`); else a
+   * fresh `<ts>_<hookSid>` dir. Works for BOTH wire behaviors: same-sid
+   * (re-bind: delete the old map entry so `_session` re-creates it against
+   * the new dir) and fresh-sid (plain targeted adoption).
+   * @param {string|null} prevSid - the writer's active sid BEFORE this
+   *   request: on a fresh-sid resume the departing conversation is keyed by
+   *   it, not by the incoming `sid`
+   * @returns {{dirName:string, identityUUID:string}}
+   */
+  _resolveResumeSwitch(sid, project, prevSid = null) {
+    const sw = this._pendingResumeSwitch;
+    this._pendingResumeSwitch = null; // one-shot
+    const projectDir = join(this._logDir, sanitizePathComponent(project));
+    let dirName = resolveSessionDirName(projectDir, sw.transcriptUuid, this._sessionsDirName);
+    let identity = sw.transcriptUuid;
+    if (dirName) {
+      const targetDir = join(projectDir, this._sessionsDirName, dirName);
+      // Liveness guard is UNCONDITIONAL (mirror _resolveAdoption's
+      // unconditional skipForeignLive): even a non-claiming writer must never
+      // re-bind into a dir another live window is writing. The acquire below
+      // additionally arbitrates for claiming writers.
+      if (isForeignLiveOwned(targetDir)
+        || (this._claimsEnabled() && !acquireSessionClaim(targetDir).ok)) {
+        dirName = null; // live foreign owner — never share its journal
+      }
+    }
+    if (dirName) {
+      // Adopt the recorded dir under ITS identity (meta.sessionId,
+      // first-write-wins) so `_seqEpoch` continues that conversation.
+      try {
+        const m = JSON.parse(readFileSync(join(projectDir, this._sessionsDirName, dirName, 'meta.json'), 'utf-8'));
+        if (m && m.sessionId) identity = m.sessionId;
+      } catch { /* torn meta — transcriptUuid is the correct fallback identity */ }
+    } else {
+      identity = sw.hookSid || `resume-${process.pid}-${Date.now()}`;
+      dirName = `${compactLocalTs14(new Date().toISOString())}_${identity}`;
+    }
+    // Drop the departing conversation's binding and release its claim — this
+    // process has switched away and will not write it again, so other windows
+    // may now resume/adopt it. Same-sid wire (the observed behavior): the old
+    // binding is keyed by the INCOMING sid; fresh-sid wire: it is keyed by
+    // prevSid (review P2 — without this branch the old dir's claim + map
+    // entry leaked until process exit).
+    const oldKey = this._sessions.has(sid) ? sid
+      : (prevSid && prevSid !== sid && this._sessions.has(prevSid)) ? prevSid : null;
+    if (oldKey !== null) {
+      const old = this._sessions.get(oldKey);
+      this._sessions.delete(oldKey);
+      releaseSessionClaim(old.paths.dir);
+      this._claimedDirs.delete(old.paths.dir);
+    }
+    return { dirName, identityUUID: identity };
+  }
+
+  /** Multi-window isolation: does this writer claim its session dirs? Only a
+   *  MAIN interactive leader does — teammate writers (leader set) and IM
+   *  workers (CCV_IM_PLATFORM) stay unclaimed so any project viewer keeps
+   *  following them (cross-process producers by design), and the offline
+   *  converter (staging sessionsDirName) must never stamp live-ownership onto
+   *  migrated history. */
+  _claimsEnabled() {
+    return this._enabled && !this._leader
+      && !process.env.CCV_IM_PLATFORM
+      && this._sessionsDirName === 'sessions';
+  }
+
+  /** Release every dir this process claimed (identity-checked unlinks).
+   *  Synchronous on purpose — close() runs it ahead of the bounded async queue
+   *  drain so a hung drain can't strand live-looking locks on a clean exit. */
+  _releaseAllClaims() {
+    for (const dir of this._claimedDirs) releaseSessionClaim(dir);
+    this._claimedDirs.clear();
+  }
+
   _session(sessionId, userIdRaw, encoding, project, startTsIso, adoptTarget = null) {
     let s = this._sessions.get(sessionId);
     if (s) return s; // hot path: map hit is O(1), the scan below only runs on miss
@@ -184,6 +310,14 @@ export class V2Writer {
       }
     }
     const paths = ensureSessionDirSync(this._logDir, project, identityId, meta, this._sessionsDirName, dirName);
+    // Multi-window isolation: stamp this process's live claim on the dir. A
+    // fresh wire-UUID dir has no contention (always succeeds); the adoption
+    // path already holds the claim (idempotent re-entry). Failure (a live
+    // foreign holder appeared) degrades to today's unclaimed behavior — the
+    // write itself must never be blocked by the claim.
+    if (this._claimsEnabled() && acquireSessionClaim(paths.dir).ok) {
+      this._claimedDirs.add(paths.dir);
+    }
     s = {
       paths,
       blobs: new BlobStore(paths),
@@ -231,6 +365,13 @@ export class V2Writer {
       if (!this._diskOk()) return null;
 
       const parsed = parseUserId(entry.body && entry.body.metadata && entry.body.metadata.user_id);
+      // Captured BEFORE the reassignment below: when a /resume switch arrives
+      // on a FRESH wire sid, the departing conversation's binding is keyed by
+      // this previous sid, not the incoming one (review P2 — the fresh-sid
+      // variant would otherwise leak the old dir's claim + map entry until
+      // process exit, blocking other windows from resuming that ended
+      // conversation).
+      const prevSid = this._currentSid;
       let sid;
       if (parsed) {
         sid = parsed.sessionId;
@@ -258,8 +399,26 @@ export class V2Writer {
       // before the folder is created; null on every non-adoption path.
       let adoptTarget = null;
       if (parsed) {
-        adoptTarget = this._resolveAdoption(sid, project, originalMessages, entry);
-        if (adoptTarget) this._adopted = true;
+        // In-terminal /resume switch outranks launch adoption: the pending
+        // signal is consumed by the first REAL main request (countTokens
+        // probes and heartbeats wear main-agent body shapes but are not the
+        // user's resumed turn — consuming on them would re-bind too early
+        // with the same result, but keep the gate strict for clarity).
+        if (this._pendingResumeSwitch && entry.mainAgent
+          && !entry.isCountTokens && !entry.isHeartbeat) {
+          // Locally guarded (review P2): the switch resolution does dir-scan
+          // fs work (resolveSessionDirName → readdirSync) whose residual
+          // throw surface (EACCES/ENOTDIR) would otherwise escape to the
+          // outer catch and drop THIS request entirely — the resumed
+          // conversation's first main turn. A failure must degrade to normal
+          // routing (recorded in the current dir), never to a lost entry.
+          try { adoptTarget = this._resolveResumeSwitch(sid, project, prevSid); }
+          catch (err) { reportSwallowed('v2-write.resume-switch-apply', err); }
+        }
+        if (!adoptTarget) {
+          adoptTarget = this._resolveAdoption(sid, project, originalMessages, entry);
+          if (adoptTarget) this._adopted = true;
+        }
       }
 
       // entry.timestamp = this session's first-request time → meta.startTs +
@@ -484,9 +643,12 @@ export class V2Writer {
     return s ? s.paths.dir : null;
   }
 
-  /** Lifecycle hook (resume / workspace reset): drop in-memory conversation
-   *  continuity so the next request snapshots fresh. Journal seq keeps counting
-   *  (same process, same session dirs — seq must stay monotonic per session). */
+  /** Lifecycle hook: drop in-memory conversation continuity so the next
+   *  request snapshots fresh. Journal seq keeps counting (same process, same
+   *  session dirs — seq must stay monotonic per session). NOTE: the
+   *  in-terminal /resume switch does NOT ride this — it needs a DIR re-bind,
+   *  not just fresh continuity (see beginResumeSwitch); this stays for
+   *  in-place resets that keep the dir. */
   resetConversations() {
     try {
       for (const s of this._sessions.values()) {
@@ -505,6 +667,10 @@ export class V2Writer {
    *  under the new project — different directory, so no seq collision. */
   resetSessions() {
     try {
+      // Release live claims FIRST (before the session map is gone): a
+      // switched-away workspace's dirs are dormant and legitimately adoptable
+      // by other windows from this moment on.
+      this._releaseAllClaims();
       this._sessions.clear();
       this._pendingNoSid.length = 0;
       this._lateHandles.clear();
@@ -512,6 +678,9 @@ export class V2Writer {
       // A second workspace's `-c` must be able to adopt afresh — the previous
       // workspace's adoption doesn't carry over.
       this._adopted = false;
+      // A /resume signal armed in the previous workspace context is
+      // meaningless after the switch (its transcript belongs to that project).
+      this._pendingResumeSwitch = null;
     } catch (err) {
       reportSwallowed('v2-write.reset-sessions', err);
     }
@@ -523,6 +692,12 @@ export class V2Writer {
   }
 
   async close() {
+    // Synchronous claim release BEFORE the async drain: close() runs under
+    // interceptor.js's 2s-bounded shutdown race, and a hung drain must not
+    // strand owner.lock files on a clean exit. (A crash skips this entirely —
+    // harmless, the claim's validity dies with the pid.)
+    try { this._releaseAllClaims(); }
+    catch (err) { reportSwallowed('v2-write.release-claims', err); }
     await this._queue.close();
   }
 }

package/server/proxy.js

@@ -8,6 +8,8 @@ import { setupInterceptor } from './interceptor.js';
 import { extractApiErrorMessage, formatProxyRequestError } from './lib/proxy-errors.js';
 import { getProxyDispatcher } from './lib/proxy-env.js';
 import { getClaudeConfigDir } from '../findcc.js';
+import { isAnthropicApiPath } from './lib/interceptor-core.js';
+import { executeRequest } from './lib/proxy-retry.js';
 
 // Setup interceptor to patch fetch
 setupInterceptor();
@@ -111,27 +113,35 @@ export function startProxy() {
           headers: headers,
         };
 
-        // 标记此请求为 CC-Viewer 代理转发的 Claude API 请求
-        // 拦截器识别到此 Header 会强制记录，忽略 URL 匹配规则
-        fetchOptions.headers['x-cc-viewer-trace'] = 'true';
-
-        if (body.length > 0) {
-          fetchOptions.body = body;
-        }
-
         // 走用户的网络代理：Node 内置全局 fetch 既不读 http_proxy/https_proxy，也看不到
         // userland undici 的 setGlobalDispatcher，必须把代理 dispatcher 显式传进来，否则
         // 上游请求会绕过代理直连 api.anthropic.com（详见 lib/proxy-env.js 注释）。
         const proxyDispatcher = getProxyDispatcher();
-        if (proxyDispatcher) {
-          fetchOptions.dispatcher = proxyDispatcher;
-        }
 
         // 拼接完整 URL，保留 originalBaseUrl 中的路径前缀
         const cleanBase = originalBaseUrl.endsWith('/') ? originalBaseUrl.slice(0, -1) : originalBaseUrl;
         const cleanReq = req.url.startsWith('/') ? req.url.slice(1) : req.url;
         const fullUrl = `${cleanBase}/${cleanReq}`;
 
+        // 大模型 API 请求（/v1/messages 等）走重试引擎：serial/race/stagger 重试。
+        // 重试引擎内部用 x-cc-viewer-trace 头让 interceptor 记录每次重试尝试到会话日志（网络视图数据源），
+        // 模型替换由重试引擎用 resolveProfileModel 纯函数完成（interceptor 对 trace 请求会再跑一次，幂等 no-op）。
+        // 非大模型 API 请求走原逻辑（同样用 x-cc-viewer-trace 让 interceptor 记录，但不经重试引擎）。
+        if (isAnthropicApiPath(fullUrl)) {
+          await handleLlmApiRequest(req, res, fullUrl, fetchOptions, body, proxyDispatcher);
+          return;
+        }
+
+        // ── 非大模型 API：原逻辑（透传，interceptor 记录）──
+        fetchOptions.headers['x-cc-viewer-trace'] = 'true';
+
+        if (body.length > 0) {
+          fetchOptions.body = body;
+        }
+        if (proxyDispatcher) {
+          fetchOptions.dispatcher = proxyDispatcher;
+        }
+
         const response = await fetch(fullUrl, fetchOptions);
 
         // fetch 自动解压，需移除编码相关 header 避免客户端重复解压
@@ -201,3 +211,97 @@ export function startProxy() {
     });
   });
 }
+
+// ── 大模型 API 请求处理：重试引擎 ──────────────────────
+// mode=off 时退化为单次 fetch（与原透传一致）。
+// 重试配置由 interceptor._retryConfigState 提供（live binding，watchFile 热刷新），
+// 每请求取最新值，UI 改 retry-config.json 后下一个请求即生效，无需重启。
+const _retryConfigGetter = () => interceptor._retryConfigState;
+
+async function handleLlmApiRequest(req, res, fullUrl, fetchOptions, body, proxyDispatcher) {
+  const retryConfig = _retryConfigGetter(); // live binding：每请求取最新重试配置
+  const profile = interceptor._activeProfile || null;
+
+  // 清理可能的 trace 头（executeRequest 会重新加，避免旧值干扰）；interceptor 会正常记录请求
+  // 同时清理 hop-by-hop / 传输编码头：body 已被 buffer 成完整 Buffer，
+  // 残留的 transfer-encoding:chunked / content-length 会让 undici 拒绝（invalid transfer-encoding header）
+  const retryFetchOptions = {
+    method: fetchOptions.method,
+    headers: { ...fetchOptions.headers },
+  };
+  delete retryFetchOptions.headers['x-cc-viewer-trace'];
+  delete retryFetchOptions.headers['transfer-encoding'];
+  delete retryFetchOptions.headers['Transfer-Encoding'];
+  delete retryFetchOptions.headers['connection'];
+  delete retryFetchOptions.headers['Connection'];
+  delete retryFetchOptions.headers['content-length'];
+  delete retryFetchOptions.headers['Content-Length'];
+  if (body.length > 0) {
+    retryFetchOptions.body = body;
+  }
+
+  // Client-disconnect propagation: without this, a client that gave up leaves
+  // the retry loop hammering (and billing) the upstream for up to
+  // maxRetryDurationMs. res 'close' before the response is finished means the
+  // client is gone → abort every in-flight/queued attempt via the engine.
+  const clientAbort = new AbortController();
+  res.on('close', () => {
+    if (!res.writableEnded) {
+      try { clientAbort.abort(); } catch { /* best effort */ }
+    }
+  });
+
+  // 执行带重试的请求
+  const result = await executeRequest({
+    url: fullUrl,
+    fetchOptions: retryFetchOptions,
+    retryConfig,
+    ctx: { dispatcher: proxyDispatcher, profile, signal: clientAbort.signal },
+  });
+
+  const { response, attempts, finalStatus } = result;
+
+  // Client already gone: nothing to write; the engine has aborted upstream work.
+  if (clientAbort.signal.aborted || res.writableEnded) {
+    return;
+  }
+
+  // 注入 X-Forward-Attempts 头（告知客户端本次重试了几次，与 llm-retry-proxy 一致）
+  const responseHeaders = {};
+  if (response.headers && typeof response.headers.entries === 'function') {
+    for (const [key, value] of response.headers.entries()) {
+      if (key.toLowerCase() !== 'content-encoding' && key.toLowerCase() !== 'transfer-encoding' && key.toLowerCase() !== 'content-length') {
+        responseHeaders[key] = value;
+      }
+    }
+  }
+  responseHeaders['x-forward-attempts'] = String(attempts);
+
+  // 网络异常（finalStatus=0）或竞速全失败：返回 502 + Proxy Error，与原 catch 分支一致
+  if (finalStatus === 0) {
+    res.writeHead(502, { 'x-forward-attempts': String(attempts) });
+    res.end('Proxy Error');
+    return;
+  }
+
+  // 响应客户端
+  res.writeHead(finalStatus, responseHeaders);
+
+  if (response.body) {
+    const { Readable, pipeline } = await import('node:stream');
+    // @ts-ignore
+    const nodeStream = Readable.fromWeb(response.body);
+    nodeStream.on('error', () => {});
+    pipeline(nodeStream, res, (err) => {
+      if (err && process.env.CCV_DEBUG) {
+        console.error('[CC-Viewer Proxy] Stream pipeline error:', err.message);
+      }
+    });
+  } else if (response.text) {
+    // 竞速失败兜底 response：用 text() 取 body
+    const text = await response.text();
+    res.end(text);
+  } else {
+    res.end();
+  }
+}

package/server/pty-manager.js

@@ -11,6 +11,8 @@ 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 { resolveSpawnModel } from './lib/spawn-model-resolver.js';
+import { mergeSettingsIntoArgs } from './lib/settings-merge.js';
+import { t, tFor } from './i18n.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -302,14 +304,29 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
       ],
     };
   }
-  const settingsJson = JSON.stringify(settingsObj);
-
   // 注入 --thinking-display summarized；以下任一情况跳过注入：
   // - 路径在拒绝集里（上次因此 crash 过）
   // - 环境变量 CCV_SKIP_THINKING_DISPLAY=1（用户全局 opt-out，与 cli.js 保持一致）
   const shouldInjectThinkingDisplay = !_thinkingDisplayRejectedPaths.has(claudePath)
     && process.env.CCV_SKIP_THINKING_DISPLAY !== '1';
-  const finalExtraArgs = shouldInjectThinkingDisplay ? withDefaultThinkingDisplay(extraArgs) : extraArgs;
+
+  // Fold any user-supplied --settings into the injected settings so the final argv
+  // carries a SINGLE --settings flag. claude is last-wins for duplicate --settings
+  // (empirically verified), so a user flag sitting after ours would silently clobber
+  // the injected ANTHROPIC_BASE_URL proxy override and the CCV_IM_DENY deny hardening.
+  // Merged: injected keys win, deny is unioned, other user config rides along.
+  // Runs on the RAW user args BEFORE our own --thinking-display / --system-prompt-file
+  // tokens are appended: otherwise a trailing valueless user --settings would consume
+  // an injected token as its value, silently dropping the injection. Relative settings
+  // paths resolve against the cwd claude itself runs with (spawnDir, computed below).
+  const spawnDir = cwd || process.cwd();
+  const settingsMerge = mergeSettingsIntoArgs(extraArgs, settingsObj, { cwd: spawnDir });
+  if (settingsMerge.warningDetail) {
+    console.warn(`[CC Viewer] ${tFor('cli.settingsMergeFailed', 'en', settingsMerge.warningDetail)}`);
+  }
+  const settingsJson = settingsMerge.settingsJson;
+  const userArgs = settingsMerge.args;
+  const finalExtraArgs = shouldInjectThinkingDisplay ? withDefaultThinkingDisplay(userArgs) : userArgs;
 
   // 启动目录存在 CC_SYSTEM.md / CC_APPEND_SYSTEM.md(非空)时，自动追加
   // --system-prompt-file / --append-system-prompt-file(两者独立、用户已传同义 flag 时跳过对应项)。
@@ -318,7 +335,7 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
   // 注：currentWorkspacePath 在下方才赋值，这里用 cwd 参数判定启动目录。
   // LOG_DIR 内的 spawn(IM worker 工作目录 = <LOG_DIR>/IM_<id>/)跳过模型匹配：
   // IM 人格依赖默认 sentinel CC_APPEND_SYSTEM.md 注入，全局模型条目不得静默取代它。
-  const spawnDir = cwd || process.cwd();
+  // (spawnDir 已在上方 settings 合并处赋值。)
   // insideLogDir 留在 try 外：下方 onExit 的启动兜底门控也要用它。
   const insideLogDir = spawnDir === LOG_DIR || spawnDir.startsWith(LOG_DIR + sep);
   // 整个 system prompt 构建 + 渲染管道包在 try-catch 里(PR#128)：任何意外抛错(模型解析、
@@ -495,6 +512,13 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
     const modelSuffix = sysPrompt.model ? ` (model match: ${sysPrompt.model})` : '';
     emitSpawnNotice(`[CC Viewer] loaded ${sysPrompt.loaded.join(', ')} as system prompt${modelSuffix}`);
   }
+  // Settings-merge failures surface via emitSpawnNotice too: console.warn only reaches
+  // the server stdout, invisible in the embedded terminal. Localized here (the console.warn
+  // above stays English for greppable server logs). Must be emitted after spawn — the
+  // outputBuffer reset right before pty.spawn would swallow an earlier write.
+  if (settingsMerge.warningDetail && !_suppressNextSpawnNotice) {
+    emitSpawnNotice(`[CC Viewer] ${t('cli.settingsMergeFailed', settingsMerge.warningDetail)}`);
+  }
   _suppressNextSpawnNotice = false;
 
   return ptyProcess;