cc-viewer 1.9.0 → 1.9.1

package/server/lib/json-store.js

@@ -0,0 +1,264 @@
+// Unified JSON store kernel — one locked + atomic read/write path per config file.
+//
+// cc-viewer historically copy-pasted the same "read → mutate → tmp→rename" block across
+// prefs-store / auth / im-config / workspace-registry / ask-store / session-pin-store, with
+// divergent lock and permission handling (and a few writers that were neither locked nor
+// atomic — see lib/im/im-config.js). This module extracts that pattern ONCE so the lock and
+// the 0600 policy live in a single place. It is the prerequisite for any consistent local
+// state (and, later, for cloud sync): a file cannot be projected or compared unless every
+// writer goes through the same locked, atomic path.
+//
+// Boundary: L1-lib. Imports only node builtins + the two L0-leaf primitives
+// (file-api.renameSyncWithRetry, async-file-lock.withFileLockAsync) + @ccv/core/error-report.
+// It deliberately does NOT import LOG_DIR — callers inject the file path so the kernel stays
+// a pure, reusable primitive with no data-root coupling.
+//
+// Two lock flavors are provided because callers split into two camps:
+//   - mutateJson      — async lock (withFileLockAsync), for async mutators.
+//   - mutateJsonSync  — synchronous spin lock (openSync('wx')), for the many existing SYNC
+//                       writers (auth.js, im-config.js) that cannot become async without
+//                       cascading signature changes through routes and server startup.
+// Both serialize same-process callers and mutex cross-process on the same `${file}.lock`.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, openSync, closeSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { renameSyncWithRetry } from './file-api.js';
+import { withFileLockAsync, hasLiveDiskHolder } from './async-file-lock.js';
+import { reportSwallowed } from '@ccv/core/error-report';
+
+/** Lock file lives next to the data file, derived from ITS name (not a fixed basename), so two
+ *  different files in the same directory never share a lock by accident. */
+export function lockPathFor(file) { return `${file}.lock`; }
+
+/**
+ * Tolerant JSON read. Missing / corrupt / non-object (when fallback is a plain object) → fallback.
+ * Arrays are accepted when the fallback is an array; a scalar never satisfies an object fallback.
+ */
+export function readJsonSafe(file, fallback = {}) {
+  try {
+    if (!existsSync(file)) return fallback;
+    const obj = JSON.parse(readFileSync(file, 'utf-8'));
+    if (obj === null || typeof obj !== 'object') return fallback;
+    // Shape guard: an array fallback accepts only an array; a plain-object fallback rejects one.
+    if (Array.isArray(fallback) !== Array.isArray(obj)) return fallback;
+    return obj;
+  } catch {
+    return fallback;
+  }
+}
+
+// Sentinel for "file exists but cannot be read/parsed". A MUTATE path can choose how to treat it:
+//   - DEFAULT (tolerant): collapse to `fallback` and write, so a corrupt preferences.json stays
+//     self-healing (the long-standing L66 behavior — a user re-saving recovers the file).
+//   - strictCorrupt:true: refuse to write, preserving the corrupt bytes — for files whose loss is
+//     unacceptable (e.g. profile.json, where a {} overwrite would drop every profile).
+const CORRUPT = Symbol('json-store.corrupt');
+function _readForMutation(file, fallback) {
+  if (!existsSync(file)) return fallback; // genuinely absent → seeding is fine
+  try {
+    const obj = JSON.parse(readFileSync(file, 'utf-8'));
+    if (obj === null || typeof obj !== 'object') return CORRUPT;
+    if (Array.isArray(fallback) !== Array.isArray(obj)) return CORRUPT;
+    return obj;
+  } catch {
+    return CORRUPT;
+  }
+}
+
+function _resolveForMutation(data, file, strictCorrupt) {
+  if (data !== CORRUPT) return data;
+  if (strictCorrupt) {
+    const err = new Error(`json-store: refusing to overwrite corrupt/unreadable file ${file}`);
+    err.code = 'JSON_STORE_CORRUPT';
+    reportSwallowed('json-store.corrupt-guard', err);
+    throw err;
+  }
+  return undefined; // tolerant: signal "use the fallback"
+}
+
+/**
+ * Atomic write (tmp + renameSyncWithRetry). `mode` defaults to 0600 (the file may carry secrets);
+ * pass `mode: false` to skip the permission bit entirely (non-secret stores under umask).
+ * Serialization: `pretty` (2-space, the prefs convention) or compact.
+ */
+export function writeJsonAtomic(file, data, { mode = 0o600, pretty = true } = {}) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+  try {
+    writeFileSync(tmp, pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data), mode ? { mode } : undefined);
+    renameSyncWithRetry(tmp, file);
+    if (mode) {
+      // writeFileSync's mode only applies on creation; re-assert on a pre-existing file.
+      try { chmodSync(file, mode); } catch { /* best-effort; non-POSIX or race */ }
+    }
+  } catch (err) {
+    try { unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Locked read-modify-write (async). Reads inside the lock, runs `mutator(data)` (mutate in
+ * place; may be async), atomically writes, returns the mutator's value when defined else data.
+ */
+export async function mutateJson(file, mutator, { mode = 0o600, pretty = true, fallback = {}, ensureDir, strictCorrupt = false } = {}) {
+  return withFileLockAsync(lockPathFor(file), async () => {
+    const resolved = _resolveForMutation(_readForMutation(file, fallback), file, strictCorrupt);
+    const data = resolved === undefined ? fallback : resolved;
+    const result = await mutator(data);
+    writeJsonAtomic(file, data, { mode, pretty });
+    return result !== undefined ? result : data;
+  }, { ensureDir: ensureDir ?? dirname(file) });
+}
+
+/**
+ * Lock-only primitive: holds the file's `${file}.lock` around `fn()` WITHOUT doing any read
+ * or write itself. For stores whose on-disk shape differs from their in-memory shape (e.g.
+ * ask-store's {version, entries} wrap) and therefore need to run their own domain read/save
+ * inside the mutex rather than the kernel's read→mutate→write. Shares the same lock as
+ * mutateJson / mutateJsonSync for the file.
+ */
+export async function withJsonLock(file, fn, { ensureDir } = {}) {
+  return withFileLockAsync(lockPathFor(file), fn, { ensureDir: ensureDir ?? dirname(file) });
+}
+
+// ─── Synchronous spin lock ───
+// Mirrors async-file-lock's two-tier stale detection (dead PID or aged mtime) but with
+// openSync('wx') + a blocking Atomics.wait so sync callers can hold the SAME `${file}.lock`.
+// Same-process serialization is inherent (JS is single-threaded; a sync critical section has
+// no interleaving). Cross-process mutual exclusion comes from the lock file.
+
+function _isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err && err.code === 'EPERM'; }
+}
+
+function _readLockOwnerPid(path) {
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    if (!raw) return null;
+    const obj = JSON.parse(raw);
+    if (obj && Number.isInteger(obj.pid)) return obj.pid;
+  } catch {}
+  return null;
+}
+
+function _isLockStale(path, mtimeFallbackMs) {
+  const pid = _readLockOwnerPid(path);
+  if (pid !== null) {
+    if (pid === process.pid) {
+      // Own pid is a crash leftover ONLY when this process does not currently hold the disk lock
+      // via the async flavor. An async holder (mutateJson / withJsonLock / mutatePrefs) is alive
+      // and mid-critical-section right now — it yields the JS thread at every await, so this sync
+      // caller can observe its lock; stealing it would let both writers commit and lose an update.
+      if (hasLiveDiskHolder(path)) return false;
+      return true;
+    }
+    return !_isPidAlive(pid);
+  }
+  try {
+    const stats = statSync(path);
+    return Date.now() - stats.mtimeMs > mtimeFallbackMs;
+  } catch {
+    return false; // conservative: cannot stat → assume held
+  }
+}
+
+function _blockingSleep(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch { /* Atomics.wait unavailable on the main thread in some embedders — best-effort */ }
+}
+
+// Returns true when the lock was acquired, false on timeout (caller decides how to degrade).
+// When the lock is held by THIS process's async flavor (mutateJson / withJsonLock / mutatePrefs),
+// the sync caller must NOT spin-then-degrade: the async holder is alive and mid-critical-section,
+// and a sync write issued from inside that critical section would alias the SAME in-memory object
+// the async holder is about to write back — so the sync update is silently lost (the exact failure
+// this kernel exists to prevent). That reentrancy is a programming error, not a race to ride out:
+// throw so the caller fails loudly instead of corrupting state. Foreign-process contention still
+// degrades per the caller's timeout policy.
+function _acquireLockSync(lockPath, { deadline = 2000, retryMs = 25, staleThresholdMs = 5000 } = {}) {
+  if (hasLiveDiskHolder(lockPath)) {
+    const err = new Error(`mutateJsonSync re-entered a lock held by this process's async flavor: ${lockPath}`);
+    err.code = 'JSON_STORE_REENTRANT';
+    reportSwallowed('json-store.reentrant-sync', err);
+    throw err;
+  }
+  const deadlineAt = Date.now() + deadline;
+  while (true) {
+    let fd;
+    try {
+      fd = openSync(lockPath, 'wx');
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() })); } finally { closeSync(fd); }
+      return true;
+    } catch (err) {
+      if (err?.code === 'EEXIST') {
+        if (Date.now() < deadlineAt) {
+          if (_isLockStale(lockPath, staleThresholdMs)) {
+            try { unlinkSync(lockPath); } catch {}
+            continue;
+          }
+          _blockingSleep(retryMs);
+          continue;
+        }
+        if (_isLockStale(lockPath, staleThresholdMs)) {
+          try { unlinkSync(lockPath); } catch {}
+          continue;
+        }
+        return false; // timeout — caller degrades instead of crashing
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Synchronous locked read-modify-write, for the existing SYNC writers (auth.js, im-config.js).
+ * Holds the SAME `${file}.lock` as mutateJson so a sync writer and an async writer of the same
+ * file still mutex cross-process. `mutator` must be synchronous (no await).
+ *
+ * Timeout / reentrancy policy:
+ *  - Foreign process holds the lock and it cannot be acquired in time: DEGRADE to an unlocked
+ *    atomic write rather than throwing — a 2s freeze plus an uncaught throw out of a route
+ *    callback would kill the whole server. The atomic write still can't tear the file; the
+ *    residual lost-update window is the pre-kernel status quo and is reported so it's visible.
+ *    Pass { strict: true } to throw instead.
+ *  - THIS process's async flavor holds the lock (reentrant sync call from inside an async
+ *    critical section): THROW (JSON_STORE_REENTRANT). That write would alias the async holder's
+ *    in-memory object and be silently overwritten — a fail-closed throw is the only safe answer.
+ */
+export function mutateJsonSync(file, mutator, { mode = 0o600, pretty = true, fallback = {}, ensureDir, deadline, strict = false, strictCorrupt = false } = {}) {
+  const dir = ensureDir ?? dirname(file);
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  const lockPath = lockPathFor(file);
+  const acquired = _acquireLockSync(lockPath, deadline ? { deadline } : {});
+  if (!acquired && strict) {
+    throw new Error(`Lock acquisition timeout: ${lockPath} (held by live process)`);
+  }
+  if (!acquired) {
+    reportSwallowed('json-store.lock-timeout-degraded', new Error(`mutateJsonSync degraded to unlocked write: ${file}`));
+  }
+  try {
+    const resolved = _resolveForMutation(_readForMutation(file, fallback), file, strictCorrupt);
+    const data = resolved === undefined ? fallback : resolved;
+    const result = mutator(data);
+    writeJsonAtomic(file, data, { mode, pretty });
+    return result !== undefined ? result : data;
+  } finally {
+    if (acquired) {
+      try { unlinkSync(lockPath); } catch (err) { reportSwallowed('json-store.lock-release', err); }
+    }
+  }
+}
+
+/**
+ * Generic shallow merge of a patch onto `target` IN PLACE. Domain-specific merges (e.g.
+ * approvalModal reconciliation in prefs-store) stay in the per-store layer — the kernel only
+ * provides the plain-object assign so every store doesn't re-hand-roll it.
+ */
+export function applyJsonPatch(target, patch) {
+  if (!patch || typeof patch !== 'object') return target;
+  Object.assign(target, patch);
+  return target;
+}

package/server/lib/log-watcher.js

@@ -5,6 +5,7 @@ import { reconstructEntries } from '@ccv/core/delta-reconstructor';
 import { enrichEntry } from './enrich-plan-input.js';
 import { enrichEntry as enrichWorkflowEntry } from './enrich-workflow.js';
 import { sseWrite } from './wire-compress.js';
+import { reportSwallowed } from '@ccv/core/error-report';
 
 // 1.7.0: the v1 log-file tail (fs.watch + byte cursors + rotation follow)
 // retired with the v1 write path — the live channel is server/lib/v2/
@@ -66,8 +67,15 @@ function _safeSseWrite(clients, client, payload) {
     // streams. The drain listener below stays on the res: the encoder is
     // piped into it, so socket drain still propagates.
     ok = sseWrite(client, payload);
-  } catch {
+  } catch (err) {
+    // A throwing write means this connection is unusable. Removing it from
+    // `clients` alone left the socket open and the 30s ping timer alive: the
+    // browser kept renewing its heartbeat watchdog on those pings, so it never
+    // reconnected and the chat panel stalled forever while the terminal WS
+    // stayed healthy. Report and CLOSE so the client's auto-reconnect fires.
+    reportSwallowed('sse.safe-write', err);
     _removeClient(clients, client);
+    try { client.end(); } catch {}
     return false;
   }
   if (!ok) {

package/server/lib/prefs-store.js

@@ -7,11 +7,8 @@
 // callers serialize via withFileLockAsync's per-lockPath Promise chain; cross-process
 // callers mutex on the lock file. This prevents a concurrent writer from clobbering the
 // password-bearing file or losing a fork update.
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { renameSyncWithRetry } from './file-api.js';
-import { withFileLockAsync } from './async-file-lock.js';
+import { mutateJson, readJsonSafe, writeJsonAtomic } from './json-store.js';
 import { mergeApprovalModalPrefs } from '@ccv/core/approval-modal-prefs';
 import { reconcileVoicePackPrefs } from './voice-pack-manager.js';
 import { LOG_DIR } from '../../findcc.js';
@@ -22,46 +19,24 @@ import { LOG_DIR } from '../../findcc.js';
 // override on the helpers below exists only so the preferences route can forward its
 // deps.getPrefsFile() seam (used by branch tests) and stay symmetric with the GET read.
 export function getPrefsFile() { return join(LOG_DIR, 'preferences.json'); }
-// Lock lives next to the file so every writer of the SAME preferences.json shares one lock
-// (global POST, fork ops, …). In prod all paths are canonical ⇒ one lock ⇒ serialized.
-function getPrefsLock(file) { return join(dirname(file), 'preferences.lock'); }
 
 /** Read the raw on-disk prefs object (no stripping, no virtual defaults). {} on miss/corrupt. */
 export function readPrefsRaw(file = getPrefsFile()) {
-  try {
-    if (!existsSync(file)) return {};
-    const obj = JSON.parse(readFileSync(file, 'utf-8'));
-    return obj && typeof obj === 'object' ? obj : {};
-  } catch { return {}; }
-}
-
-/** Atomic write (tmp + rename) with 0600 — the file may carry the base64 password. */
-function writePrefsAtomic(prefs, file) {
-  mkdirSync(dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
-  try {
-    writeFileSync(tmp, JSON.stringify(prefs, null, 2), { mode: 0o600 });
-    renameSyncWithRetry(tmp, file);
-    // writeFileSync's mode only applies on creation; re-assert 0600 on a pre-existing file.
-    try { chmodSync(file, 0o600); } catch { /* best-effort; non-POSIX or race */ }
-  } catch (err) {
-    try { unlinkSync(tmp); } catch {}
-    throw err;
-  }
+  return readJsonSafe(file, {});
 }
 
 /**
  * Locked read-modify-write. Reads the raw prefs inside the lock, runs mutator(prefs)
  * (mutate in place; may be async), atomically writes, and returns the mutator's return
  * value when defined, else the mutated prefs object. `file` defaults to the canonical path.
+ *
+ * Delegates to the unified json-store kernel (mutateJson): one async file lock derived from
+ * the file name + atomic tmp→rename at 0600. The lock is shared with the SYNC writers of the
+ * same file (auth.js / im-config.js via mutateJsonSync), so all preferences.json writers now
+ * mutex on the same `preferences.json.lock`.
  */
 export async function mutatePrefs(mutator, file = getPrefsFile()) {
-  return withFileLockAsync(getPrefsLock(file), async () => {
-    const prefs = readPrefsRaw(file);
-    const result = await mutator(prefs);
-    writePrefsAtomic(prefs, file);
-    return result !== undefined ? result : prefs;
-  }, { ensureDir: dirname(file) });
+  return mutateJson(file, mutator, { mode: 0o600, fallback: {}, ensureDir: dirname(file) });
 }
 
 /**

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/session-pin-store.js

@@ -8,10 +8,9 @@
 // '' means no active project (workspace mode not yet launched) → read = null / write = no-op.
 // Writes are atomic (tmp + rename) so a torn read can't happen when several writers race
 // (mirrors server/lib/prefs-store.js).
-import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { renameSyncWithRetry } from './file-api.js';
+import { writeJsonAtomic } from './json-store.js';
 
 /** Pin file path inside the project dir: `.session-pin.json`. */
 export function pinFilePath(logDir) {
@@ -32,8 +31,10 @@ export function readPin(logDir) {
 
 /**
  * Write (or clear) the pinned session id. No project (logDir = '') → no-op, returns false.
- * A null/empty pinnedSessionId deletes the file (back to "show latest"). Atomic tmp+rename.
- * Returns true on success, false on no-project / write failure (view state is best-effort).
+ * A null/empty pinnedSessionId deletes the file (back to "show latest"). Atomic via the
+ * json-store kernel (tmp + rename). Non-secret → mode:false (umask); the pin is a view
+ * preference, not a credential. Returns true on success, false on no-project / write
+ * failure (view state is best-effort).
  */
 export function writePin(logDir, pinnedSessionId) {
   if (!logDir) return false;
@@ -44,15 +45,7 @@ export function writePin(logDir, pinnedSessionId) {
       try { unlinkSync(file); } catch { /* already absent */ }
       return true;
     }
-    mkdirSync(logDir, { recursive: true });
-    const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
-    try {
-      writeFileSync(tmp, JSON.stringify({ pinnedSessionId: id }));
-      renameSyncWithRetry(tmp, file);
-    } catch (err) {
-      try { unlinkSync(tmp); } catch {}
-      throw err;
-    }
+    writeJsonAtomic(file, { pinnedSessionId: id }, { mode: false, pretty: false });
     return true;
   } 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 ────────────────────────────────────────────────────────────