cc-viewer 1.8.19 → 1.8.21

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 ────────────────────────────────────────────────────────────

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;
+}

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

@@ -23,7 +23,7 @@ import { existsSync, readFileSync, openSync, readSync, closeSync } from 'node:fs
 import { join } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 import { listSessionIds } from './replay.js';
-import { isSupportedWireFormat } from './layout.js';
+import { isSupportedWireFormat, normalizeSessionCwd } from './layout.js';
 import { isForeignLiveOwned } from './session-owner.js';
 
 /**
@@ -261,12 +261,21 @@ export function isDiscardableSession(dir, meta) {
  * (getLiveLogSource fallback, _resolveAdoption) pass true; default false keeps
  * the raw picker semantics for everything else.
  * @param {string} projectDir - absolute LOG_DIR/<project>
- * @param {{excludeDir?: string, skipForeignLive?: boolean}} [opts]
+ * @param {{excludeDir?: string, skipForeignLive?: boolean, instanceKey?: string, targetCwd?: string}} [opts]
+ *   `instanceKey` (multi-instance, 2026-10-06): when set, only consider session dirs whose
+ *   meta.json `instance` matches it — so two concurrent same-cwd instances (sharing one
+ *   basename project dir but distinct session dirs) each resolve to THEIR OWN latest session.
+ *   Dirs with no `instance` (legacy / external producers) are EXCLUDED under this filter.
+ *   `targetCwd` (same-name isolation, 2026-10-07): when set WITH `instanceKey`, scopes the
+ *   cross-instance FALLBACK pool to sessions stamped with this cwd (or with NO meta.cwd —
+ *   keep-missing). Applies ONLY to the fallback pool, never the instance filter; an empty
+ *   value disables the cwd filter. No effect without `instanceKey`.
  * @returns {{dir:string, sessionId:string}|null}
  */
-export function latestMainSession(projectDir, { excludeDir = '', skipForeignLive = false } = {}) {
+export function latestMainSession(projectDir, { excludeDir = '', skipForeignLive = false, instanceKey = '', targetCwd = '' } = {}) {
   if (!projectDir) return null;
-  const candidates = []; // { dir, sessionId, startTs }
+  const instanceCandidates = []; // session dirs stamped with the requested instanceKey
+  const projectCandidates = [];  // every eligible session dir of the project (any/no instance)
   for (const name of listSessionIds(projectDir)) {
     const dir = join(projectDir, 'sessions', name);
     if (excludeDir && dir === excludeDir) continue;
@@ -282,24 +291,64 @@ export function latestMainSession(projectDir, { excludeDir = '', skipForeignLive
     // folds in its siblings when rendered, so a teammate dir loaded directly
     // renders wrong. Keep only main (leader-less) sessions.
     if (meta.leader) continue;
-    candidates.push({ dir, sessionId: meta.sessionId || '', startTs: meta.startTs || '' });
+    const cand = {
+      dir,
+      sessionId: meta.sessionId || '',
+      startTs: meta.startTs || '',
+      // Same-name isolation (2026-10-07): the session's owning cwd (absent on legacy
+      // dirs → null). Read once here from the already-parsed meta; used ONLY to scope
+      // the cross-instance fallback pool below, never the instance filter. Normalized
+      // with the SAME lexical normalizer the writer/read side use, so the comparison
+      // stays symmetric even when a raw cwd carries `.`/`..`/duplicate separators.
+      metaCwd: (typeof meta.cwd === 'string' && meta.cwd) ? normalizeSessionCwd(meta.cwd) : null,
+    };
+    projectCandidates.push(cand);
+    if (instanceKey && meta.instance === instanceKey) instanceCandidates.push(cand);
   }
-  // Newest first, then return the first that actually has a main turn — skipping
-  // a not-yet-activated newest session (the refresh-bug fix).
-  candidates.sort((a, b) => (a.startTs < b.startTs ? 1 : a.startTs > b.startTs ? -1 : 0));
-  for (const c of candidates) {
-    if (sessionHasMainTurn(c.dir)) return { dir: c.dir, sessionId: c.sessionId };
+  const byNewest = (a, b) => (a.startTs < b.startTs ? 1 : a.startTs > b.startTs ? -1 : 0);
+  const newestWithMainTurn = (list) => {
+    const sorted = [...list].sort(byNewest);
+    for (const c of sorted) { if (sessionHasMainTurn(c.dir)) return c; }
+    return null;
+  };
+  // Multi-instance (2026-10-06): "show the instance's session when it has content, else fall
+  // back to the project's latest session WITH content" (user-pinned). An instance that exists
+  // but has only sub/system requests (no user main turn — a freshly-spawned same-cwd twin, or
+  // one rebuilt by a server restart) must NOT blank the view with its empty shell, and must
+  // NOT hard-error as "not found" either. Scope: instance-with-content → that; else → the
+  // project's newest content-bearing session (the history the user actually wants back).
+  if (instanceKey) {
+    const own = newestWithMainTurn(instanceCandidates);
+    if (own) return own;
+    // Same-name isolation (2026-10-07): scope the cross-instance fallback to the
+    // TARGET cwd so a cross-dir same-basename project sharing this pool can't be
+    // served. Keep-missing: legacy dirs with NO meta.cwd (null) stay eligible —
+    // excluding them would re-create the historical "excluded history" regression
+    // (sid-not-found / mis-detach). Same-cwd candidates always match, so same-cwd
+    // twin collaboration is unaffected. An empty targetCwd (instance dead / cwd
+    // unknown) disables the filter entirely — conservative, identical to today.
+    // This filters ONLY the fallback pool (projectCandidates), NEVER
+    // instanceCandidates above — an adopted/resumed dir's meta.cwd belongs to its
+    // original author and must not disqualify it from its own instance filter.
+    const fallbackPool = targetCwd
+      ? projectCandidates.filter((c) => c.metaCwd == null || c.metaCwd === targetCwd)
+      : projectCandidates;
+    const proj = newestWithMainTurn(fallbackPool);
+    if (proj) return proj;
+    // Nothing with a main turn anywhere: degrade to the instance's own newest dir (a truly
+    // fresh project) — still strictly this instance, never another's.
+    const ownAny = [...instanceCandidates].sort(byNewest)[0];
+    return ownAny || null;
   }
-  return null;
+  return newestWithMainTurn(projectCandidates);
 }
 
 /**
  * Absolute dir of the newest readable, non-teammate session that HAS a main
  * turn, or '' if there is none. Thin wrapper over {@link latestMainSession}.
  * @param {string} projectDir - absolute LOG_DIR/<project>
- * @param {{excludeDir?: string, skipForeignLive?: boolean}} [opts] - see {@link latestMainSession}
+ * @param {{excludeDir?: string, skipForeignLive?: boolean, instanceKey?: string, targetCwd?: string}} [opts] - see {@link latestMainSession}
  * @returns {string} absolute session dir, or ''
  */
-export function latestMainSessionDir(projectDir, opts) {
-  return latestMainSession(projectDir, opts)?.dir || '';
+export function latestMainSessionDir(projectDir, opts) {  return latestMainSession(projectDir, opts)?.dir || '';
 }