cc-viewer 1.8.19 → 1.8.21

package/server/routes/preferences.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { LOG_DIR, setLogDir, getClaudeConfigDir, discoverClaudeExecutables, resolveExplicitClaudePath, CLAUDE_EXECUTABLE_PREF_KEY } from '../../findcc.js';
-import { PROFILE_PATH, _defaultConfig, getActiveProfileId, getStoredRoles, isOfficialDefaultEndpoint, setActiveProfileForWorkspace, _loadProxyProfile, RETRY_CONFIG_PATH, _retryConfigState, _loadRetryConfigState } from '../interceptor.js';
+import { PROFILE_PATH, _defaultConfig, getActiveProfileId, getStoredRoles, isOfficialDefaultEndpoint, setActiveProfileForWorkspace, _loadProxyProfile, hydrateProfilesWithApiKeys, RETRY_CONFIG_PATH, _retryConfigState, _loadRetryConfigState } from '../interceptor.js';
 import { migrateProxyProfileList, isValidRoleValue, PROXY_ROLE_KEYS } from '../lib/interceptor-core.js';
 import { DEFAULT_RETRY_CONFIG, validateRetryConfig, resolveRetryConfig } from '../lib/proxy/proxy-retry.js';
 import { discoverCcSwitchProviders, mergeImportedProfiles } from '../lib/ccswitch-import.js';
@@ -15,7 +15,10 @@ import { inspectShellHook } from '../lib/shell-hook-inspect.js';
 import { sendEventToClients } from '../lib/log-watcher.js';
 import { listPlatforms } from '../lib/im/im-config.js';
 import { mutatePrefs, applyPrefsPatch, readPrefsRaw } from '../lib/prefs-store.js';
+import { mutateJsonSync } from '../lib/json-store.js';
+import { persistProfilesApiKeys } from '../lib/credential-access.js';
 import { isAdminReq } from '../lib/is-admin.js';
+import { isSameOriginBrowserRequest } from '../lib/same-origin.js';
 import {
   getCurrentProjectKey, getCurrentProjectName, hasFork, listForks, resolveScoped,
 } from '../lib/project-prefs.js';
@@ -27,22 +30,6 @@ function stripImConfigs(obj) {
   if (obj) for (const id of listPlatforms()) delete obj[id];
 }
 
-// Loopback identifies the socket peer, not the browser page that initiated a
-// request. Since the server intentionally has permissive CORS for legacy APIs,
-// sensitive executable-selection endpoints need their own same-origin guard.
-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;
-  }
-}
-
 // /theme 选择器特征：选项文案高特异、不太可能出现在普通生成输出里（ESC 兜底的门控签名）
 const THEME_PICKER_RE = /Auto \(match terminal\)|colorblind-friendly/;
 
@@ -163,12 +150,18 @@ function preferencesPost(req, res, parsedUrl, isLocal, deps) {
       // 切日志目录：把旧文件的完整内容（含 auth 密码 / prefsByProject forks / 其它偏好）带到新位置，
       // 避免切目录后密码与各项目 fork 凭空消失；并把写目标在 setLogDir 前后固定为"新文件"，让本次
       // 合并只跑在一个文件 / 一把锁上（不再因 LOG_DIR 中途漂移而劈裂进程内锁队列）。
+      // logDir 是机器全局、可改变进程数据根的操作（移动 vault 根会影响 LAN 门与代理注入），
+      // 因此只允许 admin（本机 loopback 或已鉴权远程 admin）触发——未鉴权远程/项目客户端直接剥掉。
       let targetFile = deps.getPrefsFile();
       let carried = null;
       if (incoming.logDir && typeof incoming.logDir === 'string') {
-        carried = readPrefsRaw(targetFile); // 旧文件全量（锁外读，迁移属罕见 admin 操作）
-        setLogDir(incoming.logDir);
-        targetFile = deps.getPrefsFile();
+        if (!isAdminReq(req, isLocal)) {
+          delete incoming.logDir; // non-admin cannot move the data root (would open the LAN gate)
+        } else {
+          carried = readPrefsRaw(targetFile); // 旧文件全量（锁外读，迁移属罕见 admin 操作）
+          setLogDir(incoming.logDir);
+          targetFile = deps.getPrefsFile();
+        }
       }
       // 全局写入：locked + atomic（prefs-store），与 fork 写共用同一把锁，避免并发写互相覆盖含密码的
       // preferences.json。Deep-merge approvalModal 的逻辑下沉到 applyPrefsPatch，与 /api/project-prefs
@@ -310,14 +303,28 @@ function proxyProfilesGet(req, res, parsedUrl, isLocal, deps) {
     if (Array.isArray(data.profiles)) {
       const { profiles: migrated, changed } = migrateProxyProfileList(data.profiles);
       if (changed) {
-        data = { ...data, profiles: migrated };
         try {
-          mkdirSync(dirname(PROFILE_PATH), { recursive: true });
-          writeFileSync(PROFILE_PATH, JSON.stringify(data, null, 2), { mode: 0o600 });
+          // Write the migration back while pulling apiKeys into the vault (so the old plaintext is
+          // never re-persisted). Read-merge-write INSIDE the lock (mutateJsonSync mutates in place
+          // and the kernel writes back the same reference), mutexed with the startup credential-strip
+          // and proxyProfilesPost.
+          mutateJsonSync(PROFILE_PATH, (current) => {
+            const base = (current && typeof current === 'object' && !Array.isArray(current)) ? current : {};
+            const stripped = persistProfilesApiKeys(migrated, null, { isMaskedFn: () => false });
+            base.profiles = stripped;
+            return base;
+          }, { mode: 0o600, strictCorrupt: true, fallback: {} });
+          data = { ...data, profiles: migrated };
           _loadProxyProfile();
         } catch { /* 迁移落盘失败不阻塞 GET；下次仍会尝试 */ }
       }
     }
+    // profile.json no longer carries apiKeys (they live in the credential vault) — decrypt-backfill
+    // them onto the list for serving. The local admin gets plaintext to view/copy; a remote caller
+    // is masked by deps.maskProfiles below (same as before).
+    if (Array.isArray(data.profiles)) {
+      data = { ...data, profiles: hydrateProfilesWithApiKeys(data.profiles) };
+    }
     // 用 interceptor.getActiveProfileId() 返回 effective active（workspace > profile.json.active > 'max'）
     const effectiveActive = getActiveProfileId();
     // 本机(127.0.0.1)= admin：下发明文 profile.apiKey 供本人在编辑表单(👁 折叠)里查阅/复制；已授权
@@ -353,22 +360,21 @@ function proxyProfilesPost(req, res, parsedUrl, isLocal, deps) {
       if (!incoming.profiles.some(p => p.id === 'max')) {
         incoming.profiles = [{ id: 'max', name: 'Default' }, ...(incoming.profiles || [])];
       }
-      // 如果 apiKey 是 mask 值（未修改），从磁盘读取原始值保留
-      let existing = {};
-      try { if (existsSync(PROFILE_PATH)) existing = JSON.parse(readFileSync(PROFILE_PATH, 'utf-8')); } catch { }
-      const existingMap = {};
-      if (existing.profiles) existing.profiles.forEach(p => { if (p.apiKey) existingMap[p.id] = p.apiKey; });
-      for (const p of incoming.profiles) {
-        if (p.apiKey && deps.isMasked(p.apiKey) && existingMap[p.id]) {
-          p.apiKey = existingMap[p.id];
-        }
-      }
-      // 只写 profiles 列表到 profile.json；active 不再入文件（避免跨进程串台）
-      // 保留老数据里的 active 字段不变，以便老版本 ccv 或手动编辑者的回退能力
-      const toWrite = { ...existing, profiles: incoming.profiles };
-      const dir = dirname(PROFILE_PATH);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      writeFileSync(PROFILE_PATH, JSON.stringify(toWrite, null, 2), { mode: 0o600 });
+      // Only the profiles list is written to profile.json; `active` is no longer persisted here
+      // (avoids cross-process clobbering). The existing file's `active` field is preserved so an
+      // older ccv or a hand editor can still fall back to it. Read-merge-write INSIDE the lock
+      // (mutateJsonSync), mutexed with the startup credential-strip and setActiveProfileForWorkspace —
+      // an unlocked snapshot would let persistProfilesApiKeys' deletion loop remove concurrently-added
+      // vault entries and overwrite the whole list.
+      // apiKey 抽出到凭证 vault（密文存 credentials.json），profile.json 不再携带 key。
+      // masked 回显 → 保留该 profile 的既有 vault 条目（不动、不回写 sentinel）；
+      // 新明文 → 写 vault；空 → 删该条目；被移除的 profile（全量替换端点）→ 删其 vault 条目。
+      mutateJsonSync(PROFILE_PATH, (current) => {
+        const existing = (current && typeof current === 'object' && !Array.isArray(current)) ? current : {};
+        const strippedProfiles = persistProfilesApiKeys(incoming.profiles, existing.profiles, { isMaskedFn: deps.isMasked });
+        existing.profiles = strippedProfiles;
+        return existing;
+      }, { mode: 0o600, strictCorrupt: true, fallback: {} });
       // 角色分配校验：只认 subagent/teammate 两个 key（roles.main 之类的杂键直接丢弃）；
       // 值必须是 follow / max / 入参 profiles 里存在的 id（按将落盘的列表校验，而非旧文件），
       // 非法值归 'follow'（宽容风格，不 400）。被删 profile 的悬空角色由读取时归 follow 兜底。
@@ -541,13 +547,20 @@ async function ccswitchImportPost(req, res, _parsedUrl, isLocal, deps) {
         }
         existing = parsed;
       }
-      // merge
-      const merged = mergeImportedProfiles(existing.profiles || [], result.profiles);
-      const toWrite = { ...existing, profiles: merged.profiles };
-      // 落盘
-      const dir = dirname(PROFILE_PATH);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      writeFileSync(PROFILE_PATH, JSON.stringify(toWrite, null, 2), { mode: 0o600 });
+      // Persist: locked read-merge-write (mutateJsonSync), mutexed with the other profile.json
+      // writers. The merge MUST be recomputed inside the lock against the CURRENT on-disk list —
+      // computing it outside from a pre-lock snapshot and overwriting the whole list would erase a
+      // proxy-profiles POST that lands in that window. apiKeys are pulled into the vault; merge
+      // semantics never delete existing vault entries (no existingProfiles passed). cc-switch imports
+      // fresh plaintext keys (not a masked echo), so isMaskedFn is always false. `merged` is read
+      // back out of the lock for the response counts.
+      let merged = null;
+      mutateJsonSync(PROFILE_PATH, (current) => {
+        const base = (current && typeof current === 'object' && !Array.isArray(current)) ? current : {};
+        merged = mergeImportedProfiles(base.profiles || [], result.profiles);
+        base.profiles = persistProfilesApiKeys(merged.profiles, null, { isMaskedFn: () => false });
+        return base;
+      }, { mode: 0o600, strictCorrupt: true, fallback: {} });
       // active 处理：setActive=true 且 cc-switch 有 current → 切换；否则保持现状
       let activeChanged = false;
       if (setActive && result.currentId) {

package/server/routes/project-meta.js

@@ -4,8 +4,32 @@ import { join } from 'node:path';
 import { PACKAGE_JSON } from '../_paths.js';
 import { LOG_DIR } from '../../findcc.js';
 import { _projectName } from '../interceptor.js';
+import { sanitizePathComponent } from '../lib/v2/layout.js';
+import { resolveViewRoot } from '../lib/view-root.js';
+import { loadWorkspaces } from '../workspace-registry.js';
+import { listLivePtys } from '../pty-manager.js';
 import { detectHomebrewInstall } from '../lib/updater.js';
 
+// Multi-project (2026-10, review P2-6): stats reads for a VIEWED project must
+// not become a presence oracle over LOG_DIR — `?project=` is accepted ONLY
+// when it resolves to a registered workspace / live PTY (or the bound
+// project), never an arbitrary sanitized name.
+function _resolveStatsName(projectParam, res) {
+  if (!projectParam) return _projectName || '';
+  const r = resolveViewRoot({
+    projectParam,
+    boundCwd: process.env.CCV_PROJECT_DIR || process.cwd(),
+    loadWorkspaces,
+    listLivePtys,
+  });
+  if (!r.ok) {
+    res.writeHead(r.status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: r.error }));
+    return null;
+  }
+  return sanitizePathComponent(projectParam);
+}
+
 // 判定当前 cc-viewer 的安装渠道，供前端精准匹配升级命令。
 //   - electron：桌面版（in-process server），走 GitHub Releases 重新下载安装包。
 //   - brew：Homebrew Cellar 布局命中 → `brew upgrade cc-viewer`（npm install -g 会跟 Cellar 打架）。
@@ -44,14 +68,19 @@ function versionInfo(req, res) {
   }
 }
 
-function projectStats(req, res) {
+function projectStats(req, res, parsedUrl) {
   try {
-    if (!_projectName) {
+    // Multi-project (2026-10): project-stats resolves the VIEWED project
+    // (?project=, registered/live only — never an arbitrary name).
+    const projectParam = parsedUrl && parsedUrl.searchParams ? parsedUrl.searchParams.get('project') : null;
+    const name = _resolveStatsName(projectParam, res);
+    if (name === null) return; // error already replied
+    if (!name) {
       res.writeHead(404, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: 'No project name' }));
       return;
     }
-    const statsFile = join(LOG_DIR, _projectName, `${_projectName}.json`);
+    const statsFile = join(LOG_DIR, name, `${name}.json`);
     if (!existsSync(statsFile)) {
       res.writeHead(404, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: 'Stats file not found' }));

package/server/routes/proxy-stats.js

@@ -10,17 +10,45 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { LOG_DIR } from '../../findcc.js';
 import { _projectName } from '../interceptor.js';
+import { sanitizePathComponent } from '../lib/v2/layout.js';
+import { resolveViewRoot } from '../lib/view-root.js';
+import { loadWorkspaces } from '../workspace-registry.js';
+import { listLivePtys } from '../pty-manager.js';
 
-// GET /api/proxy-stats — returns the current project's proxy retry stats (proxyStats field).
-// Response body: { proxyStats: {...} }; proxyStats is null when there is no data.
-function getProxyStats(req, res) {
+// Multi-project (2026-10, review P2-6): stats reads for a VIEWED project must
+// not become a presence oracle over LOG_DIR — `?project=` is accepted ONLY
+// when it resolves to a registered workspace / live PTY (or the bound
+// project), never an arbitrary sanitized name.
+function _resolveStatsName(projectParam, res) {
+  if (!projectParam) return _projectName || '';
+  const r = resolveViewRoot({
+    projectParam,
+    boundCwd: process.env.CCV_PROJECT_DIR || process.cwd(),
+    loadWorkspaces,
+    listLivePtys,
+  });
+  if (!r.ok) {
+    res.writeHead(r.status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: r.error }));
+    return null;
+  }
+  return sanitizePathComponent(projectParam);
+}
+
+// GET /api/proxy-stats — returns the VIEWED project's proxy retry stats
+// (?project=, registered/live only; the log store is name-keyed, not fs-dir).
+// Response body: { proxyStats: {...} }; null when there is no data.
+function getProxyStats(req, res, parsedUrl) {
   try {
-    if (!_projectName) {
+    const projectParam = parsedUrl && parsedUrl.searchParams ? parsedUrl.searchParams.get('project') : null;
+    const name = _resolveStatsName(projectParam, res);
+    if (name === null) return; // error already replied
+    if (!name) {
       res.writeHead(404, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: 'No project name', proxyStats: null }));
       return;
     }
-    const statsFile = join(LOG_DIR, _projectName, `${_projectName}.json`);
+    const statsFile = join(LOG_DIR, name, `${name}.json`);
     if (!existsSync(statsFile)) {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ proxyStats: null }));

package/server/routes/resume.js

@@ -0,0 +1,302 @@
+// /resume feature routes (2026-10).
+//
+//   GET  /api/resume-sessions?limit=5
+//       Recent-session list for the CURRENT project only (ccv's own v2 store).
+//       Powers the header's current-project hover dropdown. Read-only; no
+//       loopback gate (view state).
+//
+//   GET  /api/live-processes
+//       Live main claude PTYs this server owns (one per activated project), for
+//       the Header's parallel-project chips. Read-only.
+//
+//   POST /api/live-processes/attach  { project }
+//       Attach the main view's PTY stream to that project's record (multi-PTY
+//       view switch, 2026-10). Idempotent; never spawns/kills. 404 when the
+//       project has no live record (caller degrades silently).
+//
+//   POST /api/live-processes/close  { project }
+//       Kill that project's main PTY (the web header tab's × button). Admin-only
+//       (loopback or authenticated remote admin); 403 otherwise, 404 when the
+//       project has no record. The record is kept for a later re-launch.
+//
+//   POST /api/resume-session  { sessionUuid, project?, instanceKey? }
+//       TRUE /resume (2026-10-06): inject `/resume <uuid>` into the target
+//       project's running claude PTY so the process switches INTO that session
+//       in place (Claude Code's native SessionStart hook then re-binds the v2
+//       writer). Destructive-ish (re-points a live conversation), so admin +
+//       same-origin gated like /close. 409 busy when the TUI isn't observably
+//       idle, 409 ambiguous when a project-only target has 2+ live instances,
+//       404 when the target isn't a live claude PTY, 400 on a bad uuid.
+//
+// Boundary note (verify:boundaries): routes (L3) may import lib/ (L1) and
+// interceptor (L2) per the existing house pattern (session-pin.js / logs.js).
+// The aggregation itself lives in lib/v2/resume-list.js (pure, unit-tested);
+// this handler is a thin HTTP wrapper.
+
+import { LOG_DIR } from '../../findcc.js';
+import { _projectName, _v2Writer } from '../interceptor.js';
+import { listResumeSessions } from '../lib/v2/resume-list.js';
+import { projectKeyForCwd } from '../lib/system-prompt-snapshots.js';
+import { isAdminReq } from '../lib/is-admin.js';
+import { isSameOriginBrowserRequest } from '../lib/same-origin.js';
+import { reportSwallowed } from '@ccv/core/error-report';
+
+function sendJson(res, code, obj) {
+  res.writeHead(code, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(obj));
+}
+
+async function getSessionsHandler(req, res, parsedUrl) {
+  // parsedUrl is a URL object (server.js handleRequest) — read via searchParams.
+  const limitRaw = Number(parsedUrl.searchParams.get('limit'));
+  const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(Math.floor(limitRaw), 50) : 10;
+  try {
+    // Multi-project (2026-10): the viewed tab's hover dropdown may ask for the
+    // VIEWED project's sessions via ?project= (name-sanitized by
+    // listResumeSessions itself); absent ⇒ the bound project (the header's
+    // current-project dropdown, the pre-multi-project behavior).
+    const projectParam = parsedUrl.searchParams.get('project');
+    const project = (typeof projectParam === 'string' && projectParam) ? projectParam : (_projectName || '');
+    const { items, total } = listResumeSessions(LOG_DIR, { project, limit });
+    // currentSessionUuid: the single live session the main process is running.
+    // The client marks exactly ONE row "current" (its sessionUuid === this).
+    // Null before the first sid-bearing request.
+    let currentSessionUuid = null;
+    try { currentSessionUuid = _v2Writer && typeof _v2Writer.currentSessionId === 'function' ? _v2Writer.currentSessionId() : null; } catch (err) { reportSwallowed('resume-route.current-sid', err); }
+    sendJson(res, 200, { items, total, currentSessionUuid });
+  } catch (err) {
+    reportSwallowed('resume-route.list', err);
+    sendJson(res, 500, { error: 'list failed' });
+  }
+}
+
+// GET /api/live-processes — enumerate the LIVE main claude PTYs this server owns
+// (one per activated project, kept alive across project switches), for the Header's
+// parallel-project chips. Each entry: { kind:'main', project, cwd, pid, active }.
+// `project` is derived from cwd via projectKeyForCwd (same mapping the interceptor
+// uses for write routing). Read-only; a probe failure degrades to an empty list.
+async function getLiveProcessesHandler(req, res, parsedUrl) {
+  const processes = [];
+  let currentInstanceKey = null;
+  try {
+    const { listLivePtys } = await import('../pty-manager.js');
+    const live = listLivePtys();
+    // Bound project's own instanceKey (pure-client viewing, 2026-10-07): the identity of
+    // the BOUND project — the live record whose cwd equals the server's bound root. This
+    // is per-server and single-valued, deliberately NOT the shared `active` pointer (that
+    // is the terminal attachment, which lags and differs per client). The header uses it
+    // to single out THE bound tab among same-basename tabs without reading `active`.
+    const boundCwd = process.env.CCV_PROJECT_DIR || process.cwd();
+    for (const p of live) {
+      // Multi-project (2026-10, review P1): only CLAUDE main PTYs become project
+      // tabs. A scratch/$EDITOR shell (ptyKind 'shell') in a differently-named
+      // cwd would otherwise surface as a closable "project" tab and flip the
+      // Header into the multi-project tab-bar form on its own — violating the
+      // single-project parity contract.
+      if (p.ptyKind && p.ptyKind !== 'claude') continue;
+      if (!currentInstanceKey && p.instanceKey && (p.cwd || '') === boundCwd) {
+        currentInstanceKey = p.instanceKey;
+      }
+      processes.push({
+        kind: 'main',
+        project: projectKeyForCwd(p.cwd),
+        cwd: p.cwd,
+        pid: p.pid,
+        active: p.isActive === true,
+        // Multi-instance (2026-10-06): surface the per-process instanceKey so the web tab bar
+        // can tell two concurrent same-cwd instances apart and target attach/close precisely.
+        instanceKey: p.instanceKey || null,
+      });
+    }
+  } catch (err) { reportSwallowed('resume-route.live-main', err); }
+  sendJson(res, 200, { processes, currentProject: _projectName || '', currentInstanceKey });
+}
+
+// POST /api/live-processes/attach { project } — move the main view's PTY
+// attachment to the given project's record. Powers the terminal panel after a
+// chip view-switch / [+] launch: without it the shared /ws/terminal stream
+// stays pinned to the last-spawned project and the viewed project's terminal
+// shows the wrong screen (or never starts). Idempotent: re-attaching the
+// already-active project is a no-op; unknown projects get 404 and nothing
+// changes. Body capped via deps.MAX_POST_BODY like the other POST routes.
+function postLiveProcessAttachHandler(req, res, parsedUrl, isLocal, deps) {
+  let body = '';
+  req.on('data', (chunk) => { body += chunk; if (deps && body.length > deps.MAX_POST_BODY) req.destroy(); });
+  req.on('end', async () => {
+    let project = '';
+    let instanceKey = '';
+    try {
+      const parsed = JSON.parse(body || '{}');
+      project = typeof parsed.project === 'string' ? parsed.project : '';
+      instanceKey = typeof parsed.instanceKey === 'string' ? parsed.instanceKey : '';
+    } catch {
+      sendJson(res, 400, { ok: false, reason: 'bad-json' });
+      return;
+    }
+    if (!project && !instanceKey) {
+      sendJson(res, 400, { ok: false, reason: 'missing-project' });
+      return;
+    }
+    try {
+      const { attachPtyFor } = await import('../pty-manager.js');
+      const r = attachPtyFor({ project: project || undefined, instanceKey: instanceKey || undefined });
+      if (!r.ok) {
+        // Multi-instance: an ambiguous project-name-only attach (2+ live same-basename
+        // instances) is a 409 with the live candidates, so the client re-issues with an
+        // instanceKey instead of silently pinning an arbitrary process.
+        if (r.reason === 'ambiguous') {
+          sendJson(res, 409, { ok: false, reason: 'ambiguous', candidates: r.candidates || [] });
+          return;
+        }
+        sendJson(res, 404, { ok: false, reason: r.reason || 'not-found' });
+        return;
+      }
+      sendJson(res, 200, { ok: true, project, instanceKey: r.key || instanceKey || null, running: r.running, ptyKind: r.ptyKind, exitCode: r.exitCode, switched: r.switched });
+    } catch (err) {
+      reportSwallowed('resume-route.attach', err);
+      sendJson(res, 500, { ok: false, reason: 'attach-failed' });
+    }
+  });
+}
+
+// POST /api/live-processes/close { project } — kill that project's main PTY
+// (the web multi-project tab bar's × button, 2026-10). Destructive, so unlike
+// the read-only routes above this is admin-gated: loopback or an authenticated
+// remote admin (isAdminReq; killing another user's process over LAN must not be
+// possible with a mere view token). 404 when the project has no record. When
+// the killed PTY was the terminal's active attachment, the server re-anchors
+// the attachment to another live record internally (killedActive in the
+// response); the client decides its own view repair from the remaining tab
+// list (it does not need the re-anchor target).
+function postLiveProcessCloseHandler(req, res, parsedUrl, isLocal, deps) {
+  // Two gates, both required: admin identity (loopback or authenticated remote
+  // admin) AND same-origin browser context. The server intentionally answers
+  // CORS preflight permissively for legacy APIs, so without the second gate a
+  // cross-site page could kill a project's process through the user's browser
+  // (their token/cookie rides along). Same guard the executable-selection
+  // endpoints in routes/preferences.js stack on top of isAdminReq.
+  if (!isAdminReq(req, isLocal) || !isSameOriginBrowserRequest(req, parsedUrl)) {
+    sendJson(res, 403, { ok: false, reason: 'forbidden' });
+    return;
+  }
+  let body = '';
+  req.on('data', (chunk) => { body += chunk; if (deps && body.length > deps.MAX_POST_BODY) req.destroy(); });
+  req.on('end', async () => {
+    let project = '';
+    let instanceKey = '';
+    try {
+      const parsed = JSON.parse(body || '{}');
+      project = typeof parsed.project === 'string' ? parsed.project : '';
+      instanceKey = typeof parsed.instanceKey === 'string' ? parsed.instanceKey : '';
+    } catch {
+      sendJson(res, 400, { ok: false, reason: 'bad-json' });
+      return;
+    }
+    if (!project && !instanceKey) {
+      sendJson(res, 400, { ok: false, reason: 'missing-project' });
+      return;
+    }
+    try {
+      const { killPtyFor } = await import('../pty-manager.js');
+      const r = killPtyFor({ project: project || undefined, instanceKey: instanceKey || undefined });
+      if (!r.ok) {
+        // Multi-instance: an ambiguous project-name-only close (2+ live same-basename
+        // instances) is a 409 with the live candidates, so the client re-issues with an
+        // instanceKey instead of killing an arbitrary process.
+        if (r.reason === 'ambiguous') {
+          sendJson(res, 409, { ok: false, reason: 'ambiguous', candidates: r.candidates || [] });
+          return;
+        }
+        sendJson(res, 404, { ok: false, reason: r.reason || 'not-found' });
+        return;
+      }
+      sendJson(res, 200, { ok: true, project, instanceKey: r.key || instanceKey || null, killedActive: r.killedActive === true });
+    } catch (err) {
+      reportSwallowed('resume-route.close', err);
+      sendJson(res, 500, { ok: false, reason: 'close-failed' });
+    }
+  });
+}
+
+const RESUME_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// POST /api/resume-session { sessionUuid, project?, instanceKey? } — TRUE /resume:
+// inject `/resume <uuid>` into the target project's live claude PTY so the running
+// process switches INTO that session in place. Admin + same-origin gated (it re-points
+// a live conversation). See the header comment for the status/reason mapping.
+function postResumeSessionHandler(req, res, parsedUrl, isLocal, deps) {
+  if (!isAdminReq(req, isLocal) || !isSameOriginBrowserRequest(req, parsedUrl)) {
+    sendJson(res, 403, { ok: false, reason: 'forbidden' });
+    return;
+  }
+  let body = '';
+  req.on('data', (chunk) => { body += chunk; if (deps && body.length > deps.MAX_POST_BODY) req.destroy(); });
+  req.on('end', async () => {
+    let sessionUuid = '';
+    let project = '';
+    let instanceKey = '';
+    try {
+      const parsed = JSON.parse(body || '{}');
+      sessionUuid = typeof parsed.sessionUuid === 'string' ? parsed.sessionUuid.trim() : '';
+      project = typeof parsed.project === 'string' ? parsed.project : '';
+      instanceKey = typeof parsed.instanceKey === 'string' ? parsed.instanceKey : '';
+    } catch {
+      sendJson(res, 400, { ok: false, reason: 'bad-json' });
+      return;
+    }
+    if (!sessionUuid) {
+      sendJson(res, 400, { ok: false, reason: 'missing-session' });
+      return;
+    }
+    // Shape-validate BEFORE it ever reaches the TUI paste buffer (defense-in-depth;
+    // sanitizeInbound alone would still let `;`, quotes, `$()` through).
+    if (!RESUME_UUID_RE.test(sessionUuid)) {
+      sendJson(res, 400, { ok: false, reason: 'bad-uuid' });
+      return;
+    }
+    try {
+      const pm = await import('../pty-manager.js');
+      const targetProject = project || (_projectName || '');
+      // Multi-instance: a project-name-only resume that matches 2+ live same-basename
+      // instances is ambiguous — refuse with the candidates so the client re-issues
+      // with an instanceKey (mirror of attach/close).
+      if (!instanceKey && targetProject) {
+        const live = pm.liveInstancesForProject(targetProject);
+        if (live.length > 1) {
+          sendJson(res, 409, { ok: false, reason: 'ambiguous', candidates: live });
+          return;
+        }
+      }
+      // Strict target-kind gate (no active-PTY fallback): never inject into the wrong
+      // project's conversation when the anchor doesn't resolve, and never into a shell.
+      if (pm.getPtyKindFor({ project: targetProject || undefined, instanceKey: instanceKey || undefined }) !== 'claude') {
+        sendJson(res, 404, { ok: false, reason: 'not-found' });
+        return;
+      }
+      const chatQueue = await import('../lib/chat-queue.js');
+      const r = await chatQueue.injectResumeCommand(sessionUuid, { project: targetProject || undefined, instanceKey: instanceKey || undefined });
+      if (r.ok) {
+        // Session identity just changed — drop any still-queued composer messages so a
+        // message typed for the OLD conversation never drains into the resumed one.
+        try { chatQueue.clear(); } catch (err) { reportSwallowed('resume-route.clear-queue', err); }
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+      if (r.reason === 'busy') { sendJson(res, 409, { ok: false, reason: 'busy' }); return; }
+      if (r.reason === 'bad-uuid') { sendJson(res, 400, { ok: false, reason: 'bad-uuid' }); return; }
+      if (r.reason === 'no-deps') { sendJson(res, 409, { ok: false, reason: 'unavailable' }); return; }
+      sendJson(res, 500, { ok: false, reason: r.reason || 'inject-failed' });
+    } catch (err) {
+      reportSwallowed('resume-route.resume', err);
+      sendJson(res, 500, { ok: false, reason: 'resume-failed' });
+    }
+  });
+}
+
+export const resumeRoutes = [
+  { method: 'GET', match: 'exact', path: '/api/resume-sessions', handler: getSessionsHandler },
+  { method: 'GET', match: 'exact', path: '/api/live-processes', handler: getLiveProcessesHandler },
+  { method: 'POST', match: 'exact', path: '/api/live-processes/attach', handler: postLiveProcessAttachHandler },
+  { method: 'POST', match: 'exact', path: '/api/live-processes/close', handler: postLiveProcessCloseHandler },
+  { method: 'POST', match: 'exact', path: '/api/resume-session', handler: postResumeSessionHandler },
+];

package/server/routes/search.js

@@ -2,6 +2,22 @@
 // Scopes to the project root and delegates to lib/code-search.js and lib/code-replace.js.
 import { searchCode } from '../lib/code-search.js';
 import { searchReplace } from '../lib/code-replace.js';
+import { resolveViewRoot } from '../lib/view-root.js';
+import { loadWorkspaces } from '../workspace-registry.js';
+
+// Multi-project (2026-10): code SEARCH (read-only) resolves the viewed project
+// via resolveViewRoot (body {project}). search-replace (destructive) stays bound.
+async function _viewRootOrReply(req, res, projectParam, instanceParam) {
+  let listLivePtys = () => [];
+  try { ({ listLivePtys } = await import('../pty-manager.js')); } catch { /* no pty map */ }
+  return resolveViewRoot({
+    projectParam,
+    instanceParam,
+    boundCwd: process.env.CCV_PROJECT_DIR || process.cwd(),
+    loadWorkspaces,
+    listLivePtys,
+  });
+}
 
 const VALID_ENGINES = new Set(['auto', 'ripgrep', 'node']);
 const VALID_SCOPES = new Set(['all', 'file', 'match']);
@@ -50,7 +66,13 @@ function searchHandler(req, res, parsedUrl, isLocal, deps) {
     }
 
     const engine = VALID_ENGINES.has(parsed.engine) ? parsed.engine : 'auto';
-    const root = process.env.CCV_PROJECT_DIR || process.cwd();
+    const viewR = await _viewRootOrReply(req, res, typeof parsed.project === 'string' ? parsed.project : '', typeof parsed.instance === 'string' ? parsed.instance : '');
+    if (!viewR.ok) {
+      res.writeHead(viewR.status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: viewR.error }));
+      return;
+    }
+    const root = viewR.root;
 
     try {
       const result = await searchCode({

package/server/routes/skills.js

@@ -4,10 +4,26 @@ import { join, resolve, sep, dirname } from 'node:path';
 import { getClaudeConfigDir } from '../../findcc.js';
 import { listSkills, moveSkill, deleteSkill, validateSkillName, parseSkillFrontmatter } from '../lib/skills-api.js';
 import { isAdminReq } from '../lib/is-admin.js';
+import { viewRootOrReply } from '../lib/view-root.js';
+import { loadWorkspaces } from '../workspace-registry.js';
+import { listLivePtys } from '../pty-manager.js';
 
-async function skillsList(req, res) {
+// Multi-project (2026-10): the skills LIST resolves the viewed project via
+// the shared viewRootOrReply (?project=). toggle/delete (mutations) keep the
+// bound root.
+function _viewRootOrReply(req, res, parsedUrl) {
+  return viewRootOrReply(req, res, parsedUrl, {
+    boundCwd: process.env.CCV_PROJECT_DIR || process.cwd(),
+    loadWorkspaces,
+    listLivePtys,
+  });
+}
+
+async function skillsList(req, res, parsedUrl) {
   try {
-    const skills = listSkills({ projectDir: process.env.CCV_PROJECT_DIR || process.cwd() });
+    const viewRoot = _viewRootOrReply(req, res, parsedUrl);
+    if (!viewRoot) return;
+    const skills = listSkills({ projectDir: viewRoot });
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: true, skills }));
   } catch (err) {