cc-viewer 1.7.1 → 1.7.3

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
@@ -75,9 +76,13 @@ const SCAN_CHUNK = 64 * 1024;
  * @param {string} dir - absolute session dir
  * @param {number} budget - max bytes to read before giving up
  * @param {(line:string) => boolean} onLine
+ * @param {boolean} [ioErrorResult=false] - returned when the journal EXISTS
+ *   but reading it throws (transient lock / fd exhaustion). The cold-load
+ *   scanners keep the false default ("not activated"); the discard predicate
+ *   passes true so an I/O hiccup can never hide a REAL session.
  * @returns {boolean}
  */
-function scanJournal(dir, budget, onLine) {
+function scanJournal(dir, budget, onLine, ioErrorResult = false) {
   const journal = join(dir, 'journal.jsonl');
   if (!existsSync(journal)) return false;
   let fd;
@@ -105,7 +110,7 @@ function scanJournal(dir, budget, onLine) {
     const last = (carry + decoder.end()).trim();
     return !!(last && onLine(last));
   } catch {
-    return false;
+    return ioErrorResult;
   } finally {
     if (fd !== undefined) { try { closeSync(fd); } catch {} }
   }
@@ -167,6 +172,69 @@ export function sessionHasCompletedMainTurn(dir) {
   });
 }
 
+/**
+ * Does this session dir have at least one req of kind 'main' OR 'teammate'?
+ * The positive half of the discardable-session predicate. Budgeted with the
+ * WIDE budget (not MAIN_REQ_SCAN_BUDGET): journal req lines run ~1.1-1.3KB
+ * (headers + params), and time-driven heartbeat/countTokens lines can pile up
+ * before a real session's first main — a 256KB budget could give up early and
+ * misjudge a REAL session as discardable. Sessions that have a main still
+ * early-exit at its line; only genuinely main-less journals pay the budget.
+ * @param {string} dir - absolute session dir
+ * @returns {boolean}
+ */
+export function sessionHasMainOrTeammateReq(dir) {
+  // ioErrorResult=true: a transient read error must KEEP the session (treat
+  // as main-bearing) — hiding a real session is the worse failure direction;
+  // a missing journal still returns false (discard is correct there).
+  return scanJournal(dir, COMPLETED_TURN_SCAN_BUDGET, (line) => {
+    if (!line.includes('"ph":"req"')) return false;
+    if (!line.includes('"kind":"main"') && !line.includes('"kind":"teammate"')) return false;
+    try {
+      const o = JSON.parse(line);
+      return !!(o && o.ph === 'req' && (o.kind === 'main' || o.kind === 'teammate'));
+    } catch { return false; } // torn line — keep scanning
+  }, true);
+}
+
+/**
+ * Discardable-session predicate (2026-07-16): a session dir that must be
+ * DISCARDED by every read surface — never listed, counted, followed, or used
+ * as a candidate in any logic. These are orphan dirs minted by Claude Code's
+ * quota probes (max_tokens:1, one `'quota'` user message, a throwaway
+ * session_id per probe — fired at launches and agent-team spawns), plus any
+ * torn/empty dir with no renderable identity.
+ *
+ * discard ⟺ meta.leader ABSENT (not a teammate session)
+ *           AND no journal req line of kind 'main' or 'teammate'
+ *
+ * The 'teammate' kind clause is the safety net for a torn meta.json. Every
+ * real session carries a main req at/near the journal head (verified across
+ * the full real dataset: 18/18 main-less dirs were single quota probes), so a
+ * kept session early-exits its scan cheaply. Read-side only and self-healing:
+ * the moment a dir gains its first main req, the predicate flips and every
+ * surface picks it up on its next scan/poll.
+ *
+ * KEEP IN SYNC: adapter.js listV2Sessions pre-computes the same verdict
+ * inline (hasMainOrTeammate inside its existing full journal fold — unbounded,
+ * vs this predicate's 8MB budget; intentional asymmetry) and then CONFIRMS a
+ * discard through this predicate so the error→keep direction is shared.
+ * Change the rule here and there together.
+ *
+ * @param {string} dir - absolute session dir
+ * @param {object|null} [meta] - pre-parsed meta.json (avoids a re-read);
+ *   omitted → read here; unreadable → treated as leaderless (journal decides)
+ * @returns {boolean} true = discard everywhere
+ */
+export function isDiscardableSession(dir, meta) {
+  let m = meta;
+  if (m === undefined) {
+    try { m = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { m = null; }
+  }
+  if (m && m.leader) return false;
+  return !sessionHasMainOrTeammateReq(dir);
+}
+
 /**
  * The newest readable, non-teammate session that HAS a main turn, as
  * `{ dir, sessionId }`, or null. "Readable" mirrors listV2Sessions' gates (spec
@@ -180,17 +248,29 @@ export function sessionHasCompletedMainTurn(dir) {
  * 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/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;

package/server/routes/events.js

@@ -52,6 +52,49 @@ function turnEndNotify(req, res, parsedUrl, isLocal, deps) {
   });
 }
 
+// SessionStart hook notify (session-start-bridge.js): the conversation-switch
+// signal for an in-terminal /resume. Same security shape as turnEndNotify
+// (loopback-only + internal token + 16KB cap); the actual gating on
+// payload.source and the V2Writer re-bind live behind deps.onSessionStartNotify
+// (server.js → interceptor.markSessionStart).
+function sessionStartNotify(req, res, parsedUrl, isLocal, deps) {
+  if (!isLocal) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Loopback only' }));
+    return;
+  }
+  if (req.headers['x-ccviewer-internal'] !== deps.INTERNAL_TOKEN) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Invalid bridge token' }));
+    return;
+  }
+  let body = '';
+  let truncated = false;
+  req.on('data', chunk => {
+    body += chunk;
+    if (body.length > 16384) { truncated = true; req.destroy(); }
+  });
+  req.on('end', () => {
+    if (truncated) {
+      console.warn('[session-start-notify] body exceeded 16KB cap — request destroyed');
+      return; // socket already closed by destroy()
+    }
+    let payload = {};
+    let badJson = false;
+    try { payload = body ? JSON.parse(body) : {}; }
+    catch { badJson = true; console.warn('[session-start-notify] malformed JSON body'); }
+    if (badJson) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'malformed JSON body' }));
+      return;
+    }
+    try { deps.onSessionStartNotify(payload); }
+    catch (err) { reportSwallowed('session-start-notify.dispatch', err); }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+  });
+}
+
 // SSE endpoint
 // 构造「有新版」徽标的 SSE 帧（pending = {version, source}）。pending 为空返回 null。
 // 抽成纯函数便于单测帧格式；events() 在新连接上调用它补推，使版本徽标跨刷新持续显示。
@@ -358,6 +401,7 @@ async function requests(req, res) {
 
 export const eventsRoutes = [
   { method: 'POST', match: 'exact', path: '/api/turn-end-notify', handler: turnEndNotify },
+  { method: 'POST', match: 'exact', path: '/api/session-start-notify', handler: sessionStartNotify },
   { method: 'GET', match: 'exact', path: '/events', handler: events },
   { method: 'GET', match: 'exact', path: '/api/requests', handler: requests },
 ];