cc-viewer 1.7.23 → 1.8.1

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

@@ -0,0 +1,452 @@
+// Per-project store of the RENDERED system-prompt content each claude session was
+// launched with — the "snapshot" that lets `-c`/`-r` resumes re-inject byte-identical
+// text instead of re-rendering `${...}` template variables (which change between
+// launches and bust the whole prompt-prefix KV cache; git.status/recentCommits/dates
+// are the usual drifters).
+//
+// Layout under <LOG_DIR>/<projectKey>/system-prompt-snapshots/:
+//   <transcriptUuid>.json  — { v, entries:[{flag, basename, content}], model, createdAt, boundVia }
+//                            Only sessions that actually had an injection get records:
+//                            empty-entries snapshots are never persisted (a resume target
+//                            with no record simply follows the no-record path every time —
+//                            same outcome, zero poisoning surface).
+//   pending.json           — FIFO queue (cap PENDING_CAP) of launches awaiting binding:
+//                            { entries, model, cwd, createdAt, pid, resumeExpected, resolvedUuid, fork }
+//
+// Binding channels (both consume the queue):
+//   - Bind A (wire): v2-writer sees a session's first MAIN request and matches its
+//     system text against pending contents — content is the capability, so teammate /
+//     subagent requests can never steal a bind. Fresh sessions: wire sid == transcript uuid.
+//   - Bind B (hook): the SessionStart hook reports the resumed conversation's transcript
+//     uuid; a resume launch's pending is consumed EXACTLY by resolvedUuid (source
+//     'resume') or by fork flag (source 'fork'). Non-matching hooks consume nothing —
+//     a stolen in-terminal /resume hook or an out-of-order racing hook can neither
+//     poison an innocent conversation's record nor cascade-destroy the queue.
+//
+// Failure philosophy: every public function is total (returns null/false on error,
+// never throws) — a lost snapshot only means a later resume falls back to the
+// no-record path, never a broken spawn or a dropped log entry.
+//
+// GC (lazy, spawn-path only): appendPending drops records whose transcript file is
+// gone (past a 1h grace window — bind-before-transcript races) or older than 30 days.
+// Identical re-binds refresh createdAt, so actively-resumed conversations stay alive.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync, statSync, realpathSync, openSync, readSync, closeSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { reportSwallowed } from '@ccv/core/error-report';
+import { LOG_DIR, getClaudeConfigDir } from '../../findcc.js';
+import { renameSyncWithRetry } from './file-api.js';
+
+const STORE_DIR_NAME = 'system-prompt-snapshots';
+const PENDING_FILE = 'pending.json';
+const PENDING_CAP = 16; // generous headroom for sequential launches; FIFO beyond
+// Bind B freshness window: a resume launch's hook lands seconds after spawn; the TTL
+// only bounds how long an abandoned pending (crashed launch, hook never fired) stays
+// consumable. Bind A ignores age — content matching is self-validating regardless of
+// how long the user waited to send the first message.
+const RESUME_PENDING_TTL_MS = 15 * 60 * 1000;
+const QUEUE_GC_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const SNAPSHOT_GC_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+// A just-bound record can predate claude's transcript flush (fork hooks fire before the
+// first message; /compact rename windows). Records younger than this are never
+// transcript-gone-collected.
+const GC_TRANSCRIPT_GRACE_MS = 60 * 60 * 1000;
+const MAX_STORE_FILE_BYTES = 8 * 1024 * 1024;   // corrupt multi-GB files must not stall spawns
+const MAX_ENTRY_CONTENT_BYTES = 256 * 1024;     // rendered prompts are KB-scale; bigger = junk
+const TRANSCRIPT_HEAD_BYTES = 64 * 1024;        // -c candidate filter reads only the head
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KNOWN_FLAGS = new Set(['--system-prompt-file', '--append-system-prompt-file']);
+// `-c` candidate filter: teammate and sidechain transcripts share the project's
+// transcript dir but are never claude's continue target (mirrors claude's own filter).
+const TRANSCRIPT_SKIP_MARKERS = ['"isSidechain":true', '"teamName"'];
+
+// Test seam (repo _setXxxForTests style): the clock. The projects dir is steered via
+// CCV_PROJECTS_DIR / CLAUDE_CONFIG_DIR envs (findcc's test barriers apply).
+let _now = Date.now;
+export function _setSnapshotDepsForTests({ now } = {}) {
+  _now = typeof now === 'function' ? now : Date.now;
+}
+
+/** projectName derivation — same algorithm as interceptor.js (basename + sanitize). */
+export function projectKeyForCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return '';
+  const key = basename(cwd).replace(/[^a-zA-Z0-9_\-\.]/g, '_');
+  // Parity with v2/layout.js sanitizePathComponent: all-dots degenerate names must not
+  // become path traversal segments.
+  return (!key || /^\.+$/.test(key)) ? '_' : key;
+}
+
+/** claude transcript projects root: CCV_PROJECTS_DIR override, else <config>/projects. */
+function projectsDir() {
+  return process.env.CCV_PROJECTS_DIR || join(getClaudeConfigDir(), 'projects');
+}
+
+/** claude transcript dir for a launch cwd: <projects>/<slug>/ (slug = non-alnum → '-'). */
+export function transcriptDirForCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return '';
+  return join(projectsDir(), cwd.replace(/[^A-Za-z0-9]/g, '-'));
+}
+
+/** Flatten a request body's system field (string | array of text blocks) for matching. */
+export function systemTextOfBody(body) {
+  const system = body && body.system;
+  if (typeof system === 'string') return system;
+  if (Array.isArray(system)) return system.map(s => (s && s.text) || '').join('');
+  return '';
+}
+
+// The spawn side learns cwd from the launch, the hook side from claude's payload —
+// symlinks (/tmp → /private/tmp on macOS) and trailing separators would silently break
+// the byte-equality the queue matching relies on. Best-effort realpath both sides.
+function normalizeCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return '';
+  let out = cwd;
+  try { out = realpathSync.native(out); } catch { /* path may not exist yet — keep raw */ }
+  return out.length > 1 ? out.replace(/[\\/]+$/, '') : out;
+}
+
+function storeDirForKey(projectKey, logDir = LOG_DIR) {
+  return projectKey ? join(logDir, projectKey, STORE_DIR_NAME) : '';
+}
+
+/**
+ * Validate + normalize a raw entries array → [{flag, basename, content}] (drops junk).
+ * Beyond shape: flags are whitelisted and basenames must be bare filenames — a corrupted
+ * or planted record must never become a path escape (materialize joins it) or an
+ * arbitrary claude argv flag (materialize pushes it).
+ */
+function sanitizeEntries(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    if (!KNOWN_FLAGS.has(e.flag)) continue;
+    if (typeof e.basename !== 'string' || !e.basename) continue;
+    if (basename(e.basename) !== e.basename || e.basename.startsWith('.')) continue;
+    if (typeof e.content !== 'string') continue; // unavailable entries never reach the store
+    if (Buffer.byteLength(e.content, 'utf-8') > MAX_ENTRY_CONTENT_BYTES) continue;
+    out.push({ flag: e.flag, basename: e.basename, content: e.content });
+  }
+  return out;
+}
+
+function entriesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return a.every((e, i) => e.flag === b[i].flag && e.basename === b[i].basename && e.content === b[i].content);
+}
+
+function readJsonFileCapped(file) {
+  try {
+    if (statSync(file).size > MAX_STORE_FILE_BYTES) return null;
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch { return null; }
+}
+
+function atomicWriteJson(file, obj) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(obj));
+    renameSyncWithRetry(tmp, file);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* already absent */ }
+    throw err;
+  }
+}
+
+/**
+ * Read a conversation's snapshot by project key. Missing / corrupt / wrong shape → null.
+ * @returns {{entries:Array, model:string|null, createdAt:number, boundVia:string}|null}
+ */
+export function readSnapshotByKey(projectKey, uuid, logDir) {
+  try {
+    if (!UUID_RE.test(String(uuid || ''))) return null;
+    const dir = storeDirForKey(projectKey, logDir);
+    if (!dir) return null;
+    const obj = readJsonFileCapped(join(dir, `${uuid}.json`));
+    if (!obj || typeof obj !== 'object' || !Array.isArray(obj.entries)) return null;
+    return {
+      entries: sanitizeEntries(obj.entries),
+      model: typeof obj.model === 'string' ? obj.model : null,
+      createdAt: typeof obj.createdAt === 'number' ? obj.createdAt : 0,
+      boundVia: obj.boundVia === 'hook' ? 'hook' : 'wire',
+    };
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.read', err);
+    return null;
+  }
+}
+
+export function readSnapshot(cwd, uuid) {
+  return readSnapshotByKey(projectKeyForCwd(cwd), uuid);
+}
+
+/**
+ * Persist a conversation's snapshot by project key. Empty-entries records are refused
+ * ('empty'): a resume target with no injection history is indistinguishable from an
+ * unrecorded one by design — both take the no-record path, and no stored record can
+ * later mislabel a session. Default skipIfPresent: an existing record whose entries
+ * DIFFER is kept (first bind wins — a later conflicting bind means a resolution
+ * mistake, and the warning is the diagnostic); identical content rewrites the file
+ * just to refresh createdAt (otherwise gc would age out actively-resumed conversations
+ * 30 days after their FIRST bind).
+ * @returns {{written:boolean, reason?:'identical'|'exists'|'invalid'|'empty'}}
+ */
+export function writeSnapshotByKey(projectKey, uuid, rec, { skipIfPresent = true, logDir } = {}) {
+  try {
+    if (!UUID_RE.test(String(uuid || ''))) return { written: false, reason: 'invalid' };
+    const dir = storeDirForKey(projectKey, logDir);
+    if (!dir) return { written: false, reason: 'invalid' };
+    const entries = sanitizeEntries(rec && rec.entries);
+    if (entries.length === 0) return { written: false, reason: 'empty' };
+    const next = {
+      v: 1,
+      entries,
+      model: rec && typeof rec.model === 'string' ? rec.model : null,
+      createdAt: _now(),
+      boundVia: rec && rec.boundVia === 'hook' ? 'hook' : 'wire',
+    };
+    const prev = readSnapshotByKey(projectKey, uuid, logDir);
+    if (prev) {
+      if (entriesEqual(prev.entries, next.entries)) {
+        // Refresh the clock so active conversations survive age-based gc.
+        atomicWriteJson(join(dir, `${uuid}.json`), next);
+        return { written: false, reason: 'identical' };
+      }
+      if (skipIfPresent) {
+        console.warn(`[CC Viewer] system-prompt snapshot for ${uuid} already exists with different content — keeping the first bind`);
+        return { written: false, reason: 'exists' };
+      }
+    }
+    atomicWriteJson(join(dir, `${uuid}.json`), next);
+    // No gc() here: binding fires at session-start time when claude's transcript may
+    // not be visible to us yet (bind-before-transcript would self-collect the record
+    // we just wrote). Hygiene runs on the spawn path (appendPending) instead, where
+    // every stored record refers to a long-settled conversation.
+    return { written: true };
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.write', err);
+    return { written: false, reason: 'invalid' };
+  }
+}
+
+export function writeSnapshot(cwd, uuid, rec, opts) {
+  return writeSnapshotByKey(projectKeyForCwd(cwd), uuid, rec, opts);
+}
+
+// ─── pending queue ────────────────────────────────────────────────────────────
+
+function readPendingsByKey(projectKey, logDir) {
+  try {
+    const dir = storeDirForKey(projectKey, logDir);
+    if (!dir) return [];
+    const obj = readJsonFileCapped(join(dir, PENDING_FILE));
+    const list = obj && Array.isArray(obj.pendings) ? obj.pendings : [];
+    return list.filter(p => p && typeof p === 'object' && typeof p.cwd === 'string');
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.pending-read', err);
+    return [];
+  }
+}
+
+function writePendingsByKey(projectKey, list, logDir) {
+  const dir = storeDirForKey(projectKey, logDir);
+  if (!dir) return;
+  atomicWriteJson(join(dir, PENDING_FILE), { v: 1, pendings: list });
+}
+
+/**
+ * Enqueue a launch's effective injection content for later binding.
+ * rec: { entries, model, resumeExpected, resolvedUuid, fork } — cwd/createdAt/pid stamped here.
+ */
+export function appendPending(cwd, rec = {}, logDir) {
+  try {
+    const projectKey = projectKeyForCwd(cwd);
+    if (!projectKey) return false;
+    const list = readPendingsByKey(projectKey, logDir);
+    const cutoff = _now() - QUEUE_GC_AGE_MS;
+    const kept = list.filter(p => (typeof p.createdAt === 'number' ? p.createdAt : 0) >= cutoff);
+    kept.push({
+      entries: sanitizeEntries(rec.entries),
+      model: typeof rec.model === 'string' ? rec.model : null,
+      cwd: normalizeCwd(cwd),
+      createdAt: _now(),
+      pid: process.pid,
+      resumeExpected: rec.resumeExpected === true,
+      resolvedUuid: typeof rec.resolvedUuid === 'string' ? rec.resolvedUuid : null,
+      fork: rec.fork === true,
+    });
+    while (kept.length > PENDING_CAP) kept.shift();
+    writePendingsByKey(projectKey, kept, logDir);
+    gc(cwd, logDir);
+    return true;
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.pending-append', err);
+    return false;
+  }
+}
+
+/**
+ * Bind A (wire): match a session's first main request's system text against the queue.
+ * Non-empty pendings require EVERY entry content to appear in systemText (content is
+ * the capability — only the process we injected can present it); among matches the
+ * LONGEST total content wins, so a superset launch can never be claimed by a subset
+ * pending. When no content match exists, the oldest EMPTY pending is consumed (empty
+ * records are interchangeable — a mismatch binds "no injection" to a session that had
+ * none). resumeExpected pendings are reserved for Bind B and never consumed here.
+ * @returns {object|null} the consumed pending
+ */
+export function consumePendingForWireByKey(projectKey, systemText, logDir) {
+  try {
+    if (!projectKey || typeof systemText !== 'string') return null;
+    const list = readPendingsByKey(projectKey, logDir);
+    if (list.length === 0) return null;
+    const eligible = p => p.resumeExpected !== true;
+    let hitIdx = -1;
+    let hitLen = -1;
+    for (let i = 0; i < list.length; i++) {
+      const p = list[i];
+      if (!eligible(p) || p.entries.length === 0) continue;
+      if (!p.entries.every(e => e.content && systemText.includes(e.content))) continue;
+      const total = p.entries.reduce((n, e) => n + e.content.length, 0);
+      if (total > hitLen) { hitLen = total; hitIdx = i; }
+    }
+    if (hitIdx === -1) hitIdx = list.findIndex(p => eligible(p) && p.entries.length === 0);
+    if (hitIdx === -1) return null;
+    const [hit] = list.splice(hitIdx, 1);
+    writePendingsByKey(projectKey, list, logDir);
+    return hit;
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.wire-consume', err);
+    return null;
+  }
+}
+
+/**
+ * Bind B (hook): consume the pending that belongs to THIS hook's conversation.
+ *   source 'resume' → exact resolvedUuid match only;
+ *   source 'fork'   → the oldest fork pending (fork hooks carry the fork's NEW
+ *                     transcript uuid, which the spawn could not have known).
+ * Anything else consumes NOTHING: a stolen in-terminal /resume hook or an out-of-order
+ * racing hook finds no exact match and leaves the queue intact — no cascade of
+ * guard-refusals, no destroyed pendings (strays age out via RESUME_PENDING_TTL_MS).
+ * @returns {object|null} { hit } | { mismatch: resolvedUuid } | null
+ */
+export function consumePendingForResume(cwd, transcriptUuid, source, logDir) {
+  try {
+    const normCwd = normalizeCwd(cwd);
+    if (!normCwd) return null;
+    const projectKey = projectKeyForCwd(cwd);
+    const list = readPendingsByKey(projectKey, logDir);
+    if (list.length === 0) return null;
+    const cutoff = _now() - RESUME_PENDING_TTL_MS;
+    const kept = list.filter(p => {
+      if (p.resumeExpected !== true) return true;
+      return (typeof p.createdAt === 'number' ? p.createdAt : 0) >= cutoff; // stale strays drop out
+    });
+    const changed = kept.length !== list.length;
+    let idx = -1;
+    if (source === 'fork') {
+      idx = kept.findIndex(p => p.resumeExpected === true && p.fork === true && p.cwd === normCwd);
+    } else {
+      idx = kept.findIndex(p => p.resumeExpected === true && p.fork !== true
+        && p.cwd === normCwd && p.resolvedUuid === transcriptUuid);
+    }
+    if (idx === -1) {
+      if (changed) writePendingsByKey(projectKey, kept, logDir);
+      // Diagnostic surface for a -c mis-resolution: a RESUME hook arrived but the
+      // only resume pendings for this cwd name a DIFFERENT conversation than the
+      // one claude actually resumed. Fork hooks never warn (their new uuid differs
+      // from resolvedUuid by design); equal-uuid leftovers aren't mismatches either.
+      const other = source !== 'fork' && kept.find(p => p.resumeExpected === true && p.fork !== true
+        && p.cwd === normCwd && p.resolvedUuid && p.resolvedUuid !== transcriptUuid);
+      return other ? { mismatch: other.resolvedUuid } : null;
+    }
+    const [hit] = kept.splice(idx, 1);
+    writePendingsByKey(projectKey, kept, logDir);
+    return { hit };
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.resume-consume', err);
+    return null;
+  }
+}
+
+/** Bounded head read (transcripts can reach GB scale — never whole-file them here). */
+function readHead(file, maxBytes) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const n = readSync(fd, buf, 0, maxBytes, 0);
+    return buf.toString('utf-8', 0, n);
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Resolve which conversation `claude -c` would continue in cwd: the newest-mtime
+ * uuid-named transcript in <projects>/<slug>/, skipping teammate/sidechain transcripts
+ * (they share the dir but are never continue targets). Missing dir / no candidates /
+ * fs error → null (caller treats as "target unidentifiable" → fresh-launch behavior).
+ */
+export function resolveContinueTargetUuid(cwd) {
+  try {
+    const dir = transcriptDirForCwd(cwd);
+    if (!dir || !existsSync(dir)) return null;
+    let best = null;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.jsonl')) continue;
+      const uuid = basename(name, '.jsonl');
+      if (!UUID_RE.test(uuid)) continue;
+      const file = join(dir, name);
+      let stat;
+      try { stat = statSync(file); } catch { continue; }
+      if (best && stat.mtimeMs <= best.mtimeMs) continue;
+      try {
+        const head = readHead(file, TRANSCRIPT_HEAD_BYTES);
+        if (TRANSCRIPT_SKIP_MARKERS.some(m => head.includes(m))) continue;
+      } catch { continue; }
+      best = { uuid, mtimeMs: stat.mtimeMs };
+    }
+    return best ? best.uuid : null;
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.resolve-continue', err);
+    return null;
+  }
+}
+
+/**
+ * Lazy hygiene, invoked from the spawn path (appendPending): drop snapshot files whose
+ * transcript is gone (past the grace window) or older than SNAPSHOT_GC_AGE_MS. Queue
+ * aging is handled inside the queue readers/writers themselves.
+ */
+export function gc(cwd, logDir) {
+  try {
+    const projectKey = projectKeyForCwd(cwd);
+    const dir = storeDirForKey(projectKey, logDir);
+    if (!dir || !existsSync(dir)) return 0;
+    const tDir = transcriptDirForCwd(cwd);
+    const cutoff = _now() - SNAPSHOT_GC_AGE_MS;
+    const graceCutoff = _now() - GC_TRANSCRIPT_GRACE_MS;
+    let removed = 0;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json') || name === PENDING_FILE) continue;
+      const uuid = basename(name, '.json');
+      if (!UUID_RE.test(uuid)) continue;
+      const rec = readSnapshotByKey(projectKey, uuid, logDir);
+      if (!rec) continue; // corrupt → leave it for a human, don't churn
+      const stale = rec.createdAt > 0 && rec.createdAt < cutoff;
+      const transcriptGone = rec.createdAt < graceCutoff
+        && tDir && !existsSync(join(tDir, `${uuid}.jsonl`));
+      if (stale || transcriptGone) {
+        try { unlinkSync(join(dir, name)); removed++; } catch { /* best-effort */ }
+      }
+    }
+    return removed;
+  } catch (err) {
+    reportSwallowed('sys-prompt-snap.gc', err);
+    return 0;
+  }
+}

package/server/lib/updater.js

@@ -42,6 +42,51 @@ export function detectHomebrewInstall(dirOverride, realpathImpl = realpathSync)
   return normalized.slice(0, idx); // 返回 brew prefix
 }
 
+// Detect whether cc-viewer was installed via a pnpm global install (`pnpm add -g`).
+// pnpm's global layout: <root>/global/<id>/node_modules/.pnpm/cc-viewer@<version>/node_modules/cc-viewer/
+//   - macOS default root:    ~/Library/pnpm (PNPM_HOME)
+//   - Linux default root:    ~/.local/share/pnpm
+//   - Windows default root:  %LOCALAPPDATA%\pnpm
+//   - custom PNPM_HOME / global-dir: any path, but the `.pnpm` virtual-store segment stays fixed.
+// Detection key: the `/.pnpm/cc-viewer@` virtual-store segment. npm never creates a `.pnpm`
+// directory and the `pkg@<version>`-style segment only occurs inside pnpm-managed trees, so this
+// is reliable regardless of where PNPM_HOME lives — a plain `/pnpm/` segment check would misfire
+// on `npm i -g --prefix ~/Library/pnpm` installs. The marker covers `pnpm add -g` installs,
+// `pnpm dlx` caches, and pnpm projects running cc-viewer from their own node_modules — all of
+// them must NOT be upgraded via `npm install -g` (dual-channel pollution). The module's own
+// realpath always flows through the virtual store (bin-shim symlinks resolve there too), so no
+// PNPM_HOME env read is needed.
+// dirOverride is for unit-test injection; realpathImpl likewise.
+// Fail-safe: realpath throwing / path mismatch -> null (upstream falls back to the default npm
+// path, never an unintended upgrade).
+export function detectPnpmGlobalInstall(dirOverride, realpathImpl = realpathSync) {
+  const dir = dirOverride || __dirname;
+  let real;
+  try {
+    real = realpathImpl(dir);
+  } catch {
+    real = dir;
+  }
+  // Normalize Windows backslashes (forward slashes keep indexOf portable)
+  const normalized = real.replace(/\\/g, '/');
+  const marker = '/.pnpm/cc-viewer@';
+  const idx = normalized.indexOf(marker);
+  if (idx === -1) return null;
+  // The segment after `cc-viewer@` must be version-shaped (same regex as the brew detector):
+  // rejects dev-clone / backup paths that merely contain the literal marker text, and tag-style
+  // segments like `cc-viewer@nightly` (pnpm tag installs — same caveat as the brew HEAD comment).
+  const after = normalized.slice(idx + marker.length);
+  if (!/^\d[\w.\-+]*\//.test(after)) return null;
+  // Return the pnpm root (PNPM_HOME / custom global-dir): the path up to the first `/global/`
+  // segment; without one (e.g. a dlx cache) strip the trailing `/node_modules` and return that.
+  const globalIdx = normalized.indexOf('/global/');
+  if (globalIdx !== -1) return normalized.slice(0, globalIdx);
+  const preMarker = normalized.slice(0, idx);
+  return preMarker.endsWith('/node_modules')
+    ? preMarker.slice(0, -'/node_modules'.length)
+    : preMarker;
+}
+
 const CHECK_INTERVAL = 4 * 60 * 60 * 1000; // 4 hours
 const CACHE_DIR = join(getClaudeConfigDir(), 'cc-viewer');
 const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
@@ -138,10 +183,12 @@ export function isAnyCcvBusy({ currentPid, busy, portRange, lsofImpl } = {}) {
 //                       undefined 或不传 = 走真探测。改用 !== undefined 比 hasOwnProperty 更稳，
 //                       避免 caller 用 `{ ...opts, brewPrefix: maybe }` 时 maybe 为 undefined
 //                       却被当显式传值，从而绕过自动检测，让 brew 用户被错误地走 npm 路径升级。
+//   pnpmRoot         -- 测试注入。语义与 brewPrefix 完全相同：非 undefined = 显式覆盖（含 null/''），
+//                       undefined = 走真探测 detectPnpmGlobalInstall()。
 //
 // 返回 status:
 //   disabled | skipped | skipped_test_context | latest | major_available | deferred_busy
-//   | brew_managed | upgrading_in_background | error
+//   | brew_managed | pnpm_managed | upgrading_in_background | error
 export async function checkAndUpdate(options = {}) {
   const fetchImpl = options.fetchImpl || fetch;
   const spawnImpl = options.spawnImpl || realSpawn;
@@ -153,6 +200,11 @@ export async function checkAndUpdate(options = {}) {
   const brewPrefix = options.brewPrefix !== undefined
     ? options.brewPrefix
     : detectHomebrewInstall();
+  // pnpm 全局安装（pnpm add -g）→ 同样不能 npm install -g：会在 npm 全局前缀残留第二份
+  // cc-viewer（双渠道污染），改建议 pnpm add -g cc-viewer@<version>
+  const pnpmRoot = options.pnpmRoot !== undefined
+    ? options.pnpmRoot
+    : detectPnpmGlobalInstall();
   const currentVersion = getCurrentVersion();
 
   // 跟随 Claude Code 全局配置
@@ -188,8 +240,8 @@ export async function checkAndUpdate(options = {}) {
     const remoteVersion = data['dist-tags']?.latest;
 
     // saveCheckTime 在所有分支前统一记录：4h 节流既避免 npm fetch 频繁，
-    // 也覆盖 brew_managed banner 的提示频率（stderr 一行 + SSE 一次足够，4h 后再提）。
-    // 故意不为 brew_managed 单独提速：banner 刷屏比慢提示更扰人，stderr 仍是侧通道。
+    // 也覆盖 brew_managed / pnpm_managed banner 的提示频率（stderr 一行 + SSE 一次足够，4h 后再提）。
+    // 故意不为 brew_managed / pnpm_managed 单独提速：banner 刷屏比慢提示更扰人，stderr 仍是侧通道。
     saveCheckTime();
 
     if (!remoteVersion) {
@@ -212,6 +264,14 @@ export async function checkAndUpdate(options = {}) {
       return { status: 'brew_managed', currentVersion, remoteVersion, brewPrefix };
     }
 
+    // pnpm 全局安装：不能 npm install -g（会在 npm 全局前缀造出第二份，双渠道污染）
+    // → 提示 pnpm add -g cc-viewer@<version>。同样必须放在 major_available 之前，
+    // 否则 pnpm 用户跨大版本时会被引导跑 npm i -g，触发我们正想杜绝的双渠道污染。
+    if (pnpmRoot) {
+      console.error(`[CC Viewer] ${t('update.pnpmManaged', { version: remoteVersion })}`);
+      return { status: 'pnpm_managed', currentVersion, remoteVersion, pnpmRoot };
+    }
+
     // 跨大版本：仅提示
     if (remote.major !== current.major) {
       console.error(`[CC Viewer] ${t('update.majorAvailable', { version: remoteVersion })}`);

package/server/lib/user-prompt-extract.js

@@ -6,17 +6,17 @@
 //
 // NOTE: this is a deliberate server-side SUBSET of the frontend classifier.
 // The full classification (synthetic prompts, secondary recycling, …) lives in
-// src/utils/contentFilter.js:isSystemText — frontend (dist) and server are two
+// @ccv/core/contentFilter:isSystemText — frontend (dist) and server are two
 // separate bundles that cannot share a module, so only the rules that would
 // LEAK into previews are mirrored here: system tags + cross-session teammate
 // notifications.
 import { openSync, readSync, closeSync } from 'node:fs';
 
 // Cross-session / teammate protocol notification `type` whitelist (must match
-// src/utils/contentFilter.js INTER_SESSION_NOTIFICATION_TYPES; add new types in
+// @ccv/core/contentFilter INTER_SESSION_NOTIFICATION_TYPES; add new types in
 // BOTH places). One array derives the Set (brace scan) + the RegExp
 // (isSystemText) so this file cannot drift internally.
-// test/stats-worker-notification-filter.test.js guards frontend↔server sync.
+// packages/app/test/stats-worker-notification-filter.test.js guards frontend↔server sync.
 export const INTER_SESSION_TYPES = [
   'idle_notification', 'shutdown_request', 'shutdown_response', 'shutdown_approved',
   'teammate_terminated', 'plan_approval_request', 'plan_approval_response',
@@ -25,7 +25,7 @@ const INTER_SESSION_TYPES_SET = new Set(INTER_SESSION_TYPES);
 const INTER_SESSION_TYPES_RE = new RegExp(`"type"\\s*:\\s*"(?:${INTER_SESSION_TYPES.join('|')})"`);
 
 // CLI-synthesized prompts (HTTP role=user but not typed by a human): Recap /
-// Title / Compact / Topic / Summary. Must match src/utils/contentFilter.js
+// Title / Compact / Topic / Summary. Must match @ccv/core/contentFilter
 // SYNTHETIC_PROMPTS (KEEP IN SYNC — same rule set, `^`-anchored on trimmed
 // text so quoted user text is never swallowed). Without this filter they leak
 // into the "all user prompts" preview (observed on real data: "The user
@@ -112,7 +112,7 @@ export function stripSystemTags(text) {
 
 /**
  * Extract the list of user prompt texts from a wire `messages` array.
- * (Kept in sync with src/utils/contentFilter.js:classifyUserContent.)
+ * (Kept in sync with @ccv/core/contentFilter:classifyUserContent.)
  */
 export function extractUserTexts(messages) {
   const texts = [];

package/server/lib/v2/adapter.js

@@ -29,12 +29,12 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
-import { reportSwallowed } from '../error-report.js';
+import { reportSwallowed } from '@ccv/core/error-report';
 import { isMainAgentRequest } from '../interceptor-core.js';
 import { readSession } from './replay.js';
 import { iterateJsonlLines } from './jsonl-read.js';
 import { isDiscardableSession } from './session-select.js';
-import { LIVE_SESSION_MTIME_MS } from '../log-management.js';
+import { LIVE_SESSION_MTIME_MS } from '../log-file-utils.js';
 import { blobPath, isSupportedWireFormat } from './layout.js';
 import { SingleFlight } from './singleflight.js';
 import { listV2Sessions } from './session-list.js';
@@ -834,7 +834,7 @@ export async function scanV2Descriptors(sessionDir) {
     // the old substring filter (`"mainAgent":true` && !`"teammate"`) also
     // admitted sub/misc entries whose backfilled body LOOKED main-agent; the
     // isMain ring drops those — intentional, more-correct behavior (pinned in
-    // test/v2-window-two-pass.test.js). Teammate-session main entries are
+    // packages/app/test/v2-window-two-pass.test.js). Teammate-session main entries are
     // excluded by both (they carry the teammate tag / isMain=false).
     if (d.isMain) {
       ring.push(d);

package/server/lib/v2/conversation-store.js

@@ -17,7 +17,7 @@
 // append order is completion order, semantic order is seq.
 
 import { readdirSync } from 'node:fs';
-import { isPostClearCheckpoint, isCompactContinuation, normalizeMsgForEquality } from '../session-boundary.js';
+import { isPostClearCheckpoint, isCompactContinuation, normalizeMsgForEquality } from '@ccv/core/session-boundary';
 import { fingerprintMsg } from '../interceptor-core.js';
 import { ensureConvDirSync, convEpochPath, convDir } from './layout.js';
 

package/server/lib/v2/convert.js

@@ -26,9 +26,9 @@
 import { readdirSync, existsSync, statSync, statfsSync, renameSync, rmSync, readFileSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { iterateRawEntriesAsync } from '../log-stream.js';
-import { createIncrementalReconstructor } from '../delta-reconstructor.js';
-import { isLogFileName, parseLogTs } from '../log-management.js';
-import { reportSwallowed } from '../error-report.js';
+import { createIncrementalReconstructor } from '@ccv/core/delta-reconstructor';
+import { isLogFileName, parseLogTs } from '../log-file-utils.js';
+import { reportSwallowed } from '@ccv/core/error-report';
 import { V2Writer } from './v2-writer.js';
 import { verifyV1File } from './verify.js';
 import { parseUserId } from './identity.js';

package/server/lib/v2/jsonl-read.js

@@ -14,7 +14,7 @@
 // mirroring readJsonlTolerant's torn-tail tolerance (spec §14).
 
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
-import { reportSwallowed } from '../error-report.js';
+import { reportSwallowed } from '@ccv/core/error-report';
 
 const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
 // Node's max string length is 0x1fffffe8 (~512MiB) — a line this long can