cc-viewer 1.8.20 → 1.8.21

package/server/interceptor.js

@@ -566,23 +566,49 @@ export function markSessionStart(payload) {
       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) {
+    // Cross-project guard (2026-10-06, relaxed for true-/resume): a foreign project's
+    // claude that somehow carries our CCVIEWER_PORT must not re-bind THIS project's
+    // writer — BUT a resume in a PARALLEL project this server also manages (a live ccv
+    // PTY whose cwd maps to that project) is legitimate and must re-bind keyed by THAT
+    // project. Resolve the target project; drop only when neither bound nor a known
+    // live ccv project. This is what lets /api/resume-session switch a parallel
+    // viewed project and still have its writer follow.
+    let resumeProject = null; // null = bound project (default)
+    if (cwd && typeof cwd === 'string') {
       const cwdProject = projectKeyForCwd(cwd);
-      if (cwdProject !== _projectName) {
-        console.warn(`[ccv session-start] resume signal from project "${cwdProject}" ignored (bound to "${_projectName}")`);
-        return;
+      if (_projectName && cwdProject === _projectName) {
+        resumeProject = null; // bound project — default key
+      } else {
+        // Synchronously resolvable? No — isLiveClaudeProject lives in pty-manager
+        // (L2), imported lazily below. Compute the candidate key here and let the
+        // async gate decide whether to arm the switch.
+        resumeProject = cwdProject || null;
       }
     }
     const transcriptUuid = basename(transcriptPath, '.jsonl');
     if (source === 'resume') {
-      _v2Writer.beginResumeSwitch({
-        transcriptUuid,
-        hookSid: (typeof sessionId === 'string' && sessionId) ? sessionId : null,
-      });
+      const armSwitch = () => {
+        _v2Writer.beginResumeSwitch({
+          transcriptUuid,
+          hookSid: (typeof sessionId === 'string' && sessionId) ? sessionId : null,
+          // Keyed by the resumed conversation's project (bound = undefined default).
+          project: resumeProject || undefined,
+        });
+      };
+      if (!resumeProject || (_projectName && resumeProject === _projectName)) {
+        armSwitch();
+      } else {
+        // Parallel project: only arm when it's a live ccv-managed claude PTY.
+        import('./pty-manager.js')
+          .then((pm) => {
+            if (pm && typeof pm.isLiveClaudeProject === 'function' && pm.isLiveClaudeProject(resumeProject)) {
+              armSwitch();
+            } else {
+              console.warn(`[ccv session-start] resume signal from unmanaged project "${resumeProject}" ignored`);
+            }
+          })
+          .catch((err) => reportSwallowed('session-start.resume-project-gate', err));
+      }
     }
     // System-prompt snapshot, Bind B (system-prompt-snapshots.js): a process-level
     // -c/-r launch queued a resumeExpected pending at spawn (pty-manager). The
@@ -682,13 +708,20 @@ export function initForWorkspace(projectPath, { forceNew = false } = {}) { // es
   const dir = join(LOG_DIR, projectName);
   try { mkdirSync(dir, { recursive: true }); } catch {}
 
+  // Capture the project being switched AWAY from BEFORE rebinding: a scoped
+  // resetSessions(below) drops only THAT project's cached session bindings, so a
+  // concurrently-running BACKGROUND project (a cross-project /resume takeover's
+  // old project, still writing via entry._resumeProject) keeps its bindings and
+  // continues uninterrupted. Same-project re-init passes the same name (a no-op
+  // scoped clear of just that project, matching the old full clear for it).
+  const previousProject = _projectName;
   _projectName = projectName;
   setProjectName(projectName);
   _logDir = dir;
   // Fresh workspace context — no carried names apply; future requests must
   // create session dirs under the NEW project.
   _agentSpawnRegistry.clear();
-  _v2Writer.resetSessions(); // also clears the per-process `-c` adoption latch
+  _v2Writer.resetSessions(previousProject || null); // also clears the per-process `-c` adoption latch
   // A `--fork-session` / `-r` launch marks fork/resume intent; neither must
   // leak into a LATER workspace's `-c` (in a long-lived server that would
   // permanently suppress adoption). Clear both marks per launch and re-sync —
@@ -863,6 +896,9 @@ export function setupInterceptor() {
         if (isProxyTrace && options?.headers) {
           delete options.headers['x-cc-viewer-trace'];
         }
+        // NOTE: `x-ccv-project-dir` is stripped LATER (right before _originalFetch,
+        // after requestEntry has extracted `_resumeProject` from it) — stripping it
+        // here would delete it before the conversion copy below could read it.
 
         const timestamp = new Date().toISOString();
         let body = null;
@@ -926,10 +962,47 @@ export function setupInterceptor() {
             safeHeaders['authorization'] = '****';
           }
         }
+        // ccv-internal self-report headers (x-ccv-project-dir / x-ccv-instance) are routing
+        // metadata, not request content — drop them from the logged/forwarded `safeHeaders`
+        // copy so they never land in the on-disk journal or reach the frontend wire (they are
+        // extracted onto `_resumeProject`/`_ccvInstance` separately). Case-insensitive.
+        for (const k of Object.keys(safeHeaders)) {
+          const lk = k.toLowerCase();
+          if (lk === 'x-ccv-project-dir' || lk === 'x-ccv-instance') delete safeHeaders[k];
+        }
 
         requestEntry = {
           timestamp,
           project: (() => { try { return basename(process.cwd()); } catch { return 'unknown'; } })(),
+          // /resume global sessions: a child claude spawned for resume carries
+          // `x-ccv-project-dir` = its own cwd, so its traffic is logged under THAT
+          // project rather than this ccv process's cwd. Set ONLY the dedicated
+          // `_resumeProject` override (the writer prefers it over the bound
+          // project); `entry.project` keeps its original process-cwd meaning for
+          // every other consumer. projectKeyForCwd takes only the basename and
+          // sanitizes it, so the header cannot path-traverse.
+          ...(() => {
+            const dir = findHeader(headers, 'x-ccv-project-dir');
+            const proj = (typeof dir === 'string' && dir) ? projectKeyForCwd(dir) : '';
+            if (!proj) return {};
+            // Same-name session isolation (2026-10-07): also surface the RAW full cwd
+            // (`dir`, the findHeader output — NOT the projectKeyForCwd basename above)
+            // as `_resumeProjectCwd`, so the writer can stamp `meta.cwd` on the session
+            // dir. The read-side fallback then tightens by full-path cwd, telling two
+            // cross-dir same-basename projects apart (basename routing cannot). Using the
+            // basename here would never equal the read side's full-path targetCwd.
+            return { _resumeProject: proj, _resumeProjectCwd: dir };
+          })(),
+          // Multi-instance (2026-10-06): the spawned claude also self-reports its PTY
+          // instanceKey via `x-ccv-instance` (spawnClaude injects it). Surface it as
+          // `_ccvInstance` so the writer can pin the resolved sessionId to THIS exact process
+          // — basename routing cannot tell two same-cwd instances apart. Validated to the
+          // minted `ccv-<hex>` shape before use (it becomes a Map key downstream).
+          ...(() => {
+            const inst = findHeader(headers, 'x-ccv-instance');
+            const key = (typeof inst === 'string' && /^ccv-[0-9a-f]+$/.test(inst)) ? inst : '';
+            return key ? { _ccvInstance: key } : {};
+          })(),
           url: urlStr,
           method: options?.method || 'GET',
           headers: safeHeaders,
@@ -1231,6 +1304,32 @@ export function setupInterceptor() {
       catch (err) { reportSwallowed('interceptor.ingest-request', err); }
     }
 
+    // Strip the ccv-internal project self-report header right before forwarding
+    // upstream — AFTER requestEntry already read `_resumeProject` from it. Strip
+    // case-insensitively (the claude client applies it via ANTHROPIC_CUSTOM_HEADERS,
+    // so casing is not under ccv's control). `_fetchOpts` starts as the same object
+    // as `options` and is only shallow-copied on rewrite, so scrub BOTH.
+    // `x-ccv-instance` (the multi-instance self-report) is stripped the same way —
+    // it must never reach Anthropic.
+    const CCV_INTERNAL_HEADERS = ['x-ccv-project-dir', 'x-ccv-instance'];
+    const scrubHeaderBag = (hdrs) => {
+      if (!hdrs) return;
+      if (hdrs instanceof Headers) {
+        for (const name of CCV_INTERNAL_HEADERS) { if (hdrs.has(name)) hdrs.delete(name); }
+      } else if (typeof hdrs === 'object') {
+        for (const k of Object.keys(hdrs)) {
+          if (CCV_INTERNAL_HEADERS.includes(k.toLowerCase())) delete hdrs[k];
+        }
+      }
+    };
+    for (const optsBag of [options, _fetchOpts]) {
+      scrubHeaderBag(optsBag && optsBag.headers);
+    }
+    // Request-object form: `fetch(new Request(...))` carries headers on the Request itself
+    // (options may be undefined), so scrub those too or the internal header reaches upstream.
+    if (typeof Request !== 'undefined' && _fetchUrl instanceof Request) scrubHeaderBag(_fetchUrl.headers);
+    if (typeof Request !== 'undefined' && url instanceof Request && url !== _fetchUrl) scrubHeaderBag(url.headers);
+
     let response;
     try {
       response = await _originalFetch.call(this, _fetchUrl, _fetchOpts);
@@ -1291,6 +1390,10 @@ export function setupInterceptor() {
               url: requestEntry.url,
               response: { body: snap },
               body: { model: requestEntry.body?.model },
+              // B3 (multi-session view-attach): tag the live overlay stream with the
+              // session uuid so an attached client can show only ITS sid's typewriter
+              // and drop the other session's. Additive — older clients ignore it.
+              sessionId: parseUserId(requestEntry.body?.metadata?.user_id)?.sessionId ?? null,
             };
             sendStreamChunk(chunkEntry, ++liveChunkSeq, (ok) => {
               // 413 → 禁用当次流式，后续全由最终 v2 completion 交付
@@ -1314,6 +1417,9 @@ export function setupInterceptor() {
               url: requestEntry.url,
               response: { body: null },
               body: { model: requestEntry.body?.model },
+              // B3: same sessionId tag on the skeleton (seq 0) so the overlay filter
+              // keys on (timestamp, sessionId) from the very first frame.
+              sessionId: parseUserId(requestEntry.body?.metadata?.user_id)?.sessionId ?? null,
             }, 0, (ok) => { if (!ok) liveStreamEnabled = false; });
           }
 

package/server/lib/chat-queue.js

@@ -67,11 +67,12 @@ function _broadcast() {
   catch (err) { reportSwallowed('chat-queue.broadcast', err); }
 }
 
-function _makeItem(text) {
+function _makeItem(text, anchor) {
   return {
     id: 'q_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 8),
     text,
     ts: Date.now(),
+    anchor: anchor || null,   // { project, sessionId } from the enqueueing client (2026-10-05)
   };
 }
 
@@ -95,6 +96,13 @@ function _clearEscTimer() {
  * NOTE 2: `isStreaming` (streamingState.active) flickers false between tool calls mid-turn;
  * injecting into that gap is harmless (the TUI natively queues the paste) but it means an
  * "immediate" inject can land inside the current turn's chain — accepted risk class.
+ * KNOWN LIMITATION (multi-project, 2026-10-05): the busy gate is global/bound-scoped —
+ * `isStreaming` reads the bound project's streamingState and `getPtyKind` follows the
+ * global active PTY, and `_items` is a single FIFO across projects. A message queued on
+ * project A can be head-of-line blocked by (or misjudge the busyness of) project B.
+ * Injection itself IS anchor-routed (item.anchor), so a queued message still lands on
+ * the project it was written in; only the timing/busy heuristic is not per-project.
+ * Per-project streaming state + queue isolation is a follow-up.
  */
 function _safeToInject() {
   if (!_deps) return false;
@@ -126,7 +134,12 @@ function _injectHead() {
   _injecting = true;
   const gen = _gen; // invalidate on clear()/stop(): a stale completion must not re-park
   try {
-    _deps.writeToPtySequential(bracketPasteSubmit(item.text), (ok) => {
+    // Route the inject by the enqueueing client's anchor when one was captured,
+    // so a message queued while viewing project A never lands in project B's PTY.
+    const _write = _deps.writeToPtySequentialFor && item.anchor
+      ? (chunks, done, opts) => _deps.writeToPtySequentialFor(chunks, done, opts, item.anchor)
+      : _deps.writeToPtySequential;
+    _write(bracketPasteSubmit(item.text), (ok) => {
       _injecting = false;
       if (gen !== _gen) return;
       if (!ok) {
@@ -175,7 +188,7 @@ function _pollUntilSafe(fn, onTimeout) {
  * `\x1b[201~` would otherwise break the paste frame), broadcasts, and arms a rescue timer for
  * the stale-busy case (frontend's isStreaming lags the real turn end by up to its debounce).
  */
-export function enqueue(text) {
+export function enqueue(text, anchor) {
   if (!_deps) return null;
   const clean = sanitizeInbound(text == null ? '' : String(text)).trim();
   if (!clean) return null;
@@ -186,7 +199,7 @@ export function enqueue(text) {
     catch (err) { reportSwallowed('chat-queue.reject-broadcast', err); }
     return null;
   }
-  const item = _makeItem(clean);
+  const item = _makeItem(clean, anchor);
   _items.push(item);
   _clearRescueTimer();
   _broadcast();
@@ -335,6 +348,56 @@ export function stop() {
   _gen++;
 }
 
+const RESUME_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * True /resume (2026-10-06): inject `/resume <uuid>` into a target project's running claude
+ * PTY so the process switches INTO that session in place (Claude Code's native SessionStart
+ * hook then re-binds the v2 writer via beginResumeSwitch). This is the in-process switch —
+ * NOT a respawn — and must only happen when the TUI is observably idle.
+ *
+ * Promise-returning so the route can map the outcome to HTTP. Resolves:
+ *   { ok:true }                 — the paste was written
+ *   { ok:false, reason:'busy' } — TUI streaming / approval open / another inject or poll in
+ *                                 flight / timed out waiting for idle (never blind-injects)
+ *   { ok:false, reason:'bad-uuid' }     — sessionUuid is not a UUID shape
+ *   { ok:false, reason:'no-deps' }      — initChatQueue never ran (SDK mode / not wired)
+ *   { ok:false, reason:'write-failed' } — the PTY write failed or threw
+ *
+ * Shares the single `_injecting`/`_pollTimer` slots with the drain/sendNow paths, so it
+ * refuses up-front when either is owned (mirrors sendNow's guard) instead of clobbering a
+ * pending drain timer and stranding a queued message. The completion handler resets
+ * `_injecting` unconditionally (both callback and catch) so a mid-inject clear()/stop()
+ * generation bump can never wedge the queue.
+ */
+export function injectResumeCommand(sessionUuid, anchor) {
+  return new Promise((resolve) => {
+    if (!_deps) { resolve({ ok: false, reason: 'no-deps' }); return; }
+    const uuid = sanitizeInbound(String(sessionUuid == null ? '' : sessionUuid)).trim();
+    if (!RESUME_UUID_RE.test(uuid)) { resolve({ ok: false, reason: 'bad-uuid' }); return; }
+    // Refuse BEFORE touching _pollUntilSafe: a drain's poll owns the single _pollTimer slot,
+    // and an in-flight inject owns _injecting — barging in would strand a queued message.
+    if (_injecting || _pollTimer) { resolve({ ok: false, reason: 'busy' }); return; }
+    let settled = false;
+    const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+    const inject = () => {
+      _injecting = true;
+      try {
+        _deps.writeToPtySequentialFor(bracketPasteSubmit(`/resume ${uuid}`), (ok) => {
+          _injecting = false;
+          done(ok ? { ok: true } : { ok: false, reason: 'write-failed' });
+        }, { settleMs: 250 }, anchor || {});
+      } catch (err) {
+        _injecting = false;
+        reportSwallowed('chat-queue.resume.inject', err);
+        done({ ok: false, reason: 'write-failed' });
+      }
+    };
+    if (_safeToInject()) { inject(); return; }
+    _pollUntilSafe(inject, () => done({ ok: false, reason: 'busy' }));
+  });
+}
+
 export function __resetForTests() {
   stop();
   _deps = null;

package/server/lib/same-origin.js

@@ -0,0 +1,22 @@
+// Same-origin guard for sensitive browser-facing endpoints.
+//
+// Loopback identifies the socket peer, not the browser page that initiated a
+// request. Since the server intentionally has permissive CORS for legacy APIs,
+// sensitive endpoints (executable selection, process kill, ...) need their own
+// same-origin guard stacked on the admin check: a cross-site page riding the
+// user's browser (token cookie / ?token= URL) must not reach them, while
+// CLI/native clients (no Origin header) and same-origin pages pass through.
+//
+// Canonical implementation — every call site imports from here.
+export function isSameOriginBrowserRequest(req, parsedUrl) {
+  const origin = req.headers?.origin;
+  if (!origin) return true; // CLI/native clients do not send Origin.
+  if (req.headers?.['sec-fetch-site'] === 'cross-site') return false;
+  try {
+    const originUrl = new URL(origin);
+    if (parsedUrl?.origin) return originUrl.origin.toLowerCase() === parsedUrl.origin.toLowerCase();
+    return originUrl.host.toLowerCase() === String(req.headers?.host || '').toLowerCase();
+  } catch {
+    return false;
+  }
+}

package/server/lib/v2/convert.js

@@ -53,7 +53,7 @@ const STOP_CHECK_EVERY = 50; // entries between shouldStop() polls
 const PROXY_SHARD_NAME = /^proxy_\d{4}-\d{2}-\d{2}\.jsonl$/;
 
 /** Enumerate a project's v1 log files, ascending by filename timestamp.
- *  Excludes `_temp.jsonl` (resume scratch) and `proxy_*.jsonl` (retry stats). */
+ *  Excludes `_temp.jsonl` and `proxy_*.jsonl` (retry stats). */
 export function listV1Files(projectDir) {
   if (!existsSync(projectDir)) return [];
   return readdirSync(projectDir)

package/server/lib/v2/layout.js

@@ -6,7 +6,7 @@
 // and the swallowed ENOENT would silently drop v2 lines (plan risk F2).
 
 import { mkdirSync, writeFileSync, renameSync, existsSync, openSync, writeSync, fsyncSync, closeSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 
 // The wire-format version this build writes AND the only one it reads.
 // Stamped into meta.json and the journal sentinel at session creation; the
@@ -28,6 +28,29 @@ export function sanitizePathComponent(name) {
   return cleaned;
 }
 
+/**
+ * Normalize a session's owning cwd for cross-dir same-basename comparison
+ * (2026-10-07). Lexical ONLY — `resolve` collapses `.`/`..` and duplicate
+ * separators without touching the filesystem, then a trailing-separator strip
+ * evens `/a/x` vs `/a/x/`. (On POSIX `resolve` already drops trailing slashes,
+ * so the strip is redundant there; it still guards Windows `\` and the root
+ * case.) Deliberately NOT realpath: the write side stamps the raw spawn cwd and
+ * the read side reads the live PTY record's raw cwd, and both are the SAME raw
+ * string — realpath would introduce a symlink-mismatch (/tmp → /private/tmp)
+ * where the two raw sides already agree byte-for-byte. Applied identically on
+ * the write (meta.cwd stamp), read-candidate, and read-target sides so the
+ * comparison stays symmetric across a respawn. Absolute cwds pass through
+ * deterministically; a relative cwd would resolve against process.cwd() (never
+ * occurs for a spawn cwd, which is always absolute).
+ * @param {string} cwd
+ * @returns {string} '' for empty/non-string input.
+ */
+export function normalizeSessionCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return '';
+  const out = resolve(cwd);
+  return out.length > 1 ? out.replace(/[\\/]+$/, '') : out;
+}
+
 /** Session creation time (ISO) → a 14-digit LOCAL-time stamp `yyyymmddhhmmss`
  *  for the session dir-name prefix (task C). Deliberately NO internal separator
  *  (unlike log-management's `compactLocalTs`, which emits `YYYYMMDD_HHMMSS`) so
@@ -122,8 +145,10 @@ export function writeFileAtomicSync(finalPath, data) {
  * targeting this session. Returns the paths object.
  *
  * meta: { wireFormat:2, sessionId, project, pid, startTs, userIdRaw,
- *         userIdEncoding, leader?, im? } — spec §3. Existing meta is never
- * rewritten here (later additive updates go through updateMetaSync).
+ *         userIdEncoding, leader?, im?, cwd? } — spec §3. Existing meta is never
+ * rewritten here (later additive updates go through updateMetaSync). `cwd` is
+ * the session's owning full working directory (same-name isolation, 2026-10-07);
+ * absent for legacy/external producers.
  */
 export function ensureSessionDirSync(logDir, project, sessionId, meta = {}, sessionsDirName = SESSIONS_DIR_NAME, dirName = sessionId) {
   // Path uses dirName (`<ts>_<uuid>` for live, task C); IDENTITY (meta.sessionId

package/server/lib/v2/live-feed.js

@@ -183,6 +183,14 @@ export class V2LiveFeed {
     // row (v2_requests_delta). Explicit ctor param — this module has no access
     // to the server deps object.
     this._wireV3 = !!opts.wireV3;
+    // Per-project view layer (2026-10): this feed's project name + an optional
+    // client filter. The server runs ONE feed per project (bound + any viewed);
+    // each broadcast must reach only the clients whose viewed project matches
+    // THIS feed's project. `clientFilter(clients, project)` returns the subset;
+    // the default (no filter) is the legacy broadcast-to-all behavior, so the
+    // single-project case is byte-identical.
+    this._project = typeof opts.project === 'string' ? opts.project : '';
+    this._clientFilter = typeof opts.clientFilter === 'function' ? opts.clientFilter : null;
     this._sessions = new Map(); // dir → cursor bundle
     this._seenDirs = new Map(); // dir → last observed journal mtimeMs (attached or not)
     this._discardGated = new Set(); // dirs refused by the discard gate — first real attach must NOT suppress history
@@ -193,6 +201,29 @@ export class V2LiveFeed {
     this._active = false;
   }
 
+  /** Clients this feed's broadcasts should reach right now: the full list, or
+   *  the per-project filtered subset when a filter is installed. */
+  _clientsFor() {
+    return this._clientFilter ? this._clientFilter(this._clients, this._project) : this._clients;
+  }
+
+  /**
+   * Instance-scoped variant (multi-instance, 2026-10-06): narrow the per-project clients to
+   * those viewing the SAME instance as this session. Two concurrent same-cwd instances share
+   * one project feed, so this keeps instance A's entries out of instance B's viewers.
+   * Backward compatible: a client with NO `_ccvViewInstance` stamp (the default / legacy /
+   * single-instance view) sees every session regardless of `sessionInstance`; a session with
+   * no stamped instance (legacy/external) is likewise visible to all.
+   */
+  _clientsForInstance(sessionInstance) {
+    const base = this._clientsFor();
+    if (!sessionInstance) return base; // session carries no instance → visible to all viewers
+    let anyInstanceViewer = false;
+    for (const c of base) { if (c && c._ccvViewInstance) { anyInstanceViewer = true; break; } }
+    if (!anyInstanceViewer) return base; // nobody is instance-scoped → keep legacy broadcast
+    return base.filter((c) => !c || !c._ccvViewInstance || c._ccvViewInstance === sessionInstance);
+  }
+
   /** Begin (or switch to) live-following a project's sessions/ root. */
   start(projectDir) {
     this.stop();
@@ -374,9 +405,14 @@ export class V2LiveFeed {
     // 4GB main-thread OOM). Seek their cursors to EOF instead: nothing is
     // read, cloned, or broadcast; the cold-load channel owns their history.
     let convertOrigin = false;
+    let sessionInstance = null;
     try {
       const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8'));
       convertOrigin = !!meta && meta.origin === 'convert';
+      // Multi-instance (2026-10-06): the owning PTY instanceKey stamped on meta.json (by the
+      // writer) lets this feed route the session's entries to exactly the clients viewing
+      // THAT instance of a same-cwd project. Absent for legacy/convert/external sessions.
+      sessionInstance = (meta && typeof meta.instance === 'string' && meta.instance) ? meta.instance : null;
     } catch (err) {
       // meta.json is written synchronously BEFORE the journal's first async
       // drain (ensureSessionDirSync), so journal-present + meta-ABSENT is
@@ -409,6 +445,7 @@ export class V2LiveFeed {
       dirty: false,
       suppress: !!suppressExisting,
       convertOrigin,
+      sessionInstance,
       // Journal req seqs with no done yet. The journal is only touched at
       // request start and completion, so a single >10min request would look
       // "idle" to the mtime-based eviction and get detached mid-flight — its
@@ -611,7 +648,7 @@ export class V2LiveFeed {
       try {
         processWatchedEntry(parsed, {
           reconstructor: cur.reconstructor,
-          clients: this._clients,
+          clients: this._clientsForInstance(cur.sessionInstance),
           getClaudePid: this._getClaudePid,
           runParallelHook: this._runParallelHook,
           suppressEntryBroadcast: this._wireV3,
@@ -648,7 +685,7 @@ export class V2LiveFeed {
         ? `{"sessionId":${JSON.stringify(cur.synth.sessionId)},"channel":${JSON.stringify(channel)},"line":${raw}}`
         : `{"sessionId":${JSON.stringify(cur.synth.sessionId)},"line":${raw}}`;
       const eventName = kind === 'conv' ? 'v3_conv' : 'v3_resp';
-      sendEventRawToClients(this._clients, eventName, payload);
+      sendEventRawToClients(this._clientsForInstance(cur.sessionInstance), eventName, payload);
     } catch (err) {
       reportSwallowed('v2-live.native-forward', err);
     }
@@ -721,12 +758,12 @@ export class V2LiveFeed {
         const corrected = withAgentNameSubType(classifyRequest(prev.entry, parsed), prev.entry);
         if (JSON.stringify(corrected) !== JSON.stringify(prev.row.typeTag)) {
           prev.row.typeTag = corrected;
-          sendEventToClients(this._clients, 'v2_requests_delta', prev.row);
+          sendEventToClients(this._clientsForInstance(cur.sessionInstance), 'v2_requests_delta', prev.row);
         }
       } catch (err) { reportSwallowed('v2-live.row-classify', err); }
     }
     cur._v3Last = { row, entry: parsed };
-    sendEventToClients(this._clients, 'v2_requests_delta', row);
+    sendEventToClients(this._clientsForInstance(cur.sessionInstance), 'v2_requests_delta', row);
   }
 
   // ── safety poll ────────────────────────────────────────────────────────────

package/server/lib/v2/resume-list.js

@@ -0,0 +1,150 @@
+// Per-project "recent sessions" list for the /resume hover list (2026-10).
+//
+// Serves the N most-recent sessions of ONE project (the currently-bound one),
+// for the header's current-project hover dropdown. Kept as a pure lib function
+// (no HTTP, no interceptor state) so it is unit-testable with a temp LOG_DIR and
+// an injectable `now` seam — same test posture as listV2LogsPage / deleteLogFiles.
+//
+// Scope: ONLY ccv's own v2 store is listed (sessions ccv actually proxied).
+//
+// Cost shape: a CHEAP meta.json pass per session (startTs + leader), plus a
+// bounded journal head-scan (sessionHasMainOrTeammateReq) that drops quota-probe
+// orphan dirs BEFORE they can occupy a top slot. Candidates are sorted
+// newest-first, sliced to the top `limit`, and only THEN run the EXPENSIVE
+// summarize (journal fold + dir walk + prompts head) via summarizeSessionPage —
+// which shares listV2Sessions' freshness-keyed row cache, so repeat hover-opens
+// are ~1-3ms. Fields the cheap pass cannot supply (sessionUuid from
+// meta.sessionId, running, pinnedId) are read fresh per call for the surviving
+// rows only, never from the cached row.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizePathComponent } from './layout.js';
+import { listSessionIds } from './replay.js';
+import { summarizeSessionPage } from './session-list.js';
+import { sessionHasMainOrTeammateReq } from './session-select.js';
+import { readPin } from '../session-pin-store.js';
+import { LIVE_SESSION_MTIME_MS } from '../log-file-utils.js';
+import { reportSwallowed } from '@ccv/core/error-report';
+
+/**
+ * Liveness heuristic for the "running" placeholder column. A session is
+ * treated as possibly-live when its journal was appended within
+ * LIVE_SESSION_MTIME_MS. Coarse by design (a background-but-idle >5min session
+ * reads as not-running) — this is a display hint only. `now` is injectable for tests.
+ * @param {string} sessionDir
+ * @param {number} now - ms epoch
+ * @returns {boolean}
+ */
+function isRecentlyActive(sessionDir, now) {
+  try {
+    const st = statSync(join(sessionDir, 'journal.jsonl'));
+    return (now - st.mtimeMs) < LIVE_SESSION_MTIME_MS;
+  } catch { return false; }
+}
+
+/**
+ * List the `limit` most-recent v2 sessions of ONE project under `logDir`,
+ * newest-first. Row shape:
+ *   { source:'ccv', project, file, sessionUuid, startTs, turns, preview, running, pinnedId }
+ * - `project`     — the LOG_DIR subdirectory name (already sanitize-safe).
+ * - `file`        — v2 addressing token `v2:<project>/<dirName>` (dirName is
+ *                   `<ts>_<uuid>` or legacy `<uuid>`), for the existing
+ *                   open-log / live-tail paths.
+ * - `sessionUuid` — the Claude Code session UUID from meta.sessionId (NOT the
+ *                   dir name), the key the client uses to scope a `?sid=` view.
+ * - `pinnedId`    — the project's persisted pin value verbatim (readPin), a
+ *                   ts-based display id. The SERVER cannot map it to this row
+ *                   (the ts stable id is a frontend runtime _timestamp), so the
+ *                   row just carries it through; the CLIENT decides `selected`
+ *                   by comparing against its own session stable ids.
+ * - `running`     — coarse liveness placeholder (see isRecentlyActive).
+ *
+ * @param {string} logDir - LOG_DIR root (e.g. ~/.claude/cc-viewer).
+ * @param {object} [opts]
+ * @param {string} opts.project - the single project to list (required).
+ * @param {number} [opts.limit=10]
+ * @param {number} [opts.now] - ms epoch, injectable for tests.
+ * @returns {{ items: Array, total: number }}
+ */
+export function listResumeSessions(logDir, { project, limit = 10, now = Date.now() } = {}) {
+  const out = { items: [], total: 0 };
+  if (!project || project !== sanitizePathComponent(project)) return out;
+
+  const projectDir = join(logDir, project);
+  if (!logDir || !existsSync(projectDir)) return out;
+
+  // ── ccv's own v2 store (sessions ccv proxied). Cheap meta.json pass per
+  // session for startTs + leader ordering/filtering, no journal fold.
+  const candidates = [];
+  let sessionIds;
+  try { sessionIds = listSessionIds(projectDir); } catch (err) {
+    reportSwallowed('resume-list.readdir', err, { project });
+    return out;
+  }
+  for (const dirName of sessionIds) {
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(projectDir, 'sessions', dirName, 'meta.json'), 'utf-8')); } catch { /* journal is self-describing */ }
+    if (meta && meta.leader) continue; // teammate — folded into its leader's row
+    // Cheap discardable-session pre-check (bounded journal head-scan, early
+    // exit on the first main/teammate req): drops quota-probe orphan dirs
+    // BEFORE they can occupy a top-`limit` slot — without paying the full
+    // summarize (journal fold + dir walk) for every candidate. Same source
+    // predicate as session-list's isDiscardableSession (leader-absent + no
+    // main/teammate req), so a probe is filtered here and the summarize-time
+    // `discard` re-check below becomes a no-op for survivors.
+    if (!sessionHasMainOrTeammateReq(join(projectDir, 'sessions', dirName))) continue;
+    candidates.push({
+      project,
+      projectDir,
+      dirName,
+      startTs: (meta && meta.startTs) || '',
+      sessionUuid: (meta && meta.sessionId) || null,
+    });
+  }
+
+  // Order newest-first, then take the top `limit` BEFORE the expensive
+  // summarize (journal fold + dir walk + prompts head) — so a large history
+  // pays the summarize for at most `limit` rows, not for every session. Rows
+  // dropped by the summarize-time filters (teammate fold / quota-probe orphan /
+  // unreadable) leave their slot empty rather than being back-filled; such rows
+  // are rare and `limit` is small, so the occasional short list is accepted in
+  // exchange for the bounded cost.
+  candidates.sort((a, b) =>
+    b.startTs.localeCompare(a.startTs)
+    || String(b.dirName || '').localeCompare(String(a.dirName || '')));
+  const top = candidates.slice(0, limit);
+
+  const ccvRows = [];
+  for (const c of top) {
+    let s = null;
+    try { s = summarizeSessionPage(c.projectDir, c.dirName); } catch (err) {
+      reportSwallowed('resume-list.summarize', err, { project: c.project, dirName: c.dirName });
+      continue;
+    }
+    if (!s) continue;
+    if (s.leader) continue;
+    if (s.size === 0) continue;
+    if (s.discard) continue; // quota-probe orphans: never listed
+    const sessionDir = join(c.projectDir, 'sessions', c.dirName);
+    ccvRows.push({
+      source: 'ccv',
+      project: c.project,
+      file: `v2:${c.project}/${s.sid}`,
+      sessionUuid: c.sessionUuid,
+      startTs: s.startTs,
+      turns: s.turns,
+      preview: s.preview || [],
+      running: isRecentlyActive(sessionDir, now),
+      // The pin lives at the PROJECT dir and holds a ts-based display id, not a
+      // uuid — pass it through verbatim; the client maps it to a row.
+      pinnedId: readPin(c.projectDir),
+    });
+  }
+
+  // Already newest-first from the candidate sort (the summarize filter only
+  // drops rows, never reorders). total = surviving rows shown (≤ limit).
+  out.total = ccvRows.length;
+  out.items = ccvRows;
+  return out;
+}