cc-viewer 1.9.16 → 1.9.18

package/server/lib/target-scope.js

@@ -0,0 +1,174 @@
+// Shared resolution of a "target" (CLAUDE.md / skill folder) into the
+// navigation root the file browser walks, plus the path validation both the
+// read route (/api/target-files in routes/files-content.js) and the write
+// routes (/api/target-* in routes/target-files-fs.js) rely on.
+//
+// These helpers were moved verbatim out of routes/files-content.js so the new
+// target write routes resolve the EXACT same root as the read route — never
+// trust a client-supplied absolute root, always re-derive it from the target
+// identity (kind + id, or source + targetPath) via resolveTargetRoot.
+//
+// Layering: this is L1 (lib). It must NOT import from routes/ — routes import
+// lib, never the reverse (enforced by pnpm run verify:boundaries).
+import { realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { isReadAllowed, reasonToStatus } from './file-access-policy.js';
+import { listSkills } from './skills-api.js';
+import { discoverClaudeMdCandidates } from './claude-md-discovery.js';
+import { getClaudeConfigDir } from '../../findcc.js';
+
+export function targetError(status, message) {
+  return Object.assign(new Error(message), { status });
+}
+
+// Map fs errno to a sensible HTTP status: missing → 404, permission → 403,
+// symlink loop → 400 (treat as malformed), anything else → 404 (don't leak).
+export function errnoToStatus(err) {
+  const code = err?.code;
+  if (code === 'EACCES' || code === 'EPERM') return 403;
+  if (code === 'ELOOP') return 400;
+  return 404;
+}
+
+export function realDirectory(path, label) {
+  let real;
+  try { real = realpathSync(path); } catch (err) { throw targetError(errnoToStatus(err), `${label} not found`); }
+  let st;
+  try { st = statSync(real); } catch (err) { throw targetError(errnoToStatus(err), `${label} not found`); }
+  if (!st.isDirectory()) throw targetError(400, `${label} is not a directory`);
+  return real;
+}
+
+export function checkedDirectory(path, label) {
+  const real = realDirectory(path, label);
+  const policy = isReadAllowed(real);
+  if (!policy.ok) throw targetError(reasonToStatus(policy.reason), `${label} not readable`);
+  return policy.real;
+}
+
+export function insidePath(path, root) {
+  return path === root || path.startsWith(root + sep);
+}
+
+export function targetNavigation(targetReal, cwd) {
+  const projectReal = realDirectory(cwd, 'Project');
+  if (insidePath(targetReal, projectReal)) return { rootReal: projectReal, rootKind: 'project' };
+  // $HOME becomes the navigation root for home-resident targets (user skills,
+  // plugins, the global CLAUDE.md). Entries outside the allowlist (e.g. ~/.ssh,
+  // ~/.aws) are filtered per-entry by isReadAllowed, and sensitive paths inside
+  // ~/.claude are covered by file-access-policy's denylist. The /api/target-files
+  // handler additionally gates this endpoint behind isAdminReq + same-origin so
+  // a cross-site page cannot enumerate the user's home tree.
+  const homeReal = realDirectory(homedir(), 'Home');
+  if (insidePath(targetReal, homeReal)) {
+    checkedDirectory(targetReal, 'Directory');
+    return { rootReal: homeReal, rootKind: 'home' };
+  }
+  const configReal = realDirectory(getClaudeConfigDir(), 'Claude config');
+  if (insidePath(targetReal, configReal)) {
+    checkedDirectory(targetReal, 'Directory');
+    return { rootReal: realDirectory(dirname(configReal), 'Config root'), rootKind: 'config' };
+  }
+  // Allowlist fallback: targets that live inside another allowlisted root
+  // (registered workspaces, /tmp/cc-viewer-uploads, etc.) are reachable via
+  // /api/claude-md's discovery (which uses isReadAllowed), so we must not
+  // 403 them here. Use the target's own directory as the navigation root —
+  // no parent browsing, but at least the entry the user clicked actually opens.
+  const policy = isReadAllowed(targetReal);
+  if (!policy.ok) throw targetError(reasonToStatus(policy.reason), 'Target not readable');
+  return { rootReal: realDirectory(targetReal, 'Target'), rootKind: 'target' };
+}
+
+export function targetScope(targetReal, cwd) {
+  const navigation = targetNavigation(targetReal, cwd);
+  return { ...navigation, targetPath: relative(navigation.rootReal, targetReal).split(sep).join('/') };
+}
+
+export function targetRelPath(raw) {
+  if (raw == null) return null;
+  if (raw === '') return [];
+  if (typeof raw !== 'string' || raw.length > 2048 || raw.includes('\0') || raw.includes('\\')
+    || raw.startsWith('/') || /^[a-zA-Z]:/.test(raw)) {
+    throw targetError(400, 'Invalid path');
+  }
+  const segments = raw.split('/');
+  if (segments.some(segment => !segment || segment === '.' || segment === '..')) {
+    throw targetError(400, 'Invalid path');
+  }
+  // Hard cap on navigation depth: each segment triggers at least one
+  // synchronous readdir + per-entry realpath/stat in `ancestors`, and a 2KB
+  // free-form path could otherwise fan out into hundreds of syscalls per
+  // request. 32 is far deeper than any realistic skill / CLAUDE.md location.
+  if (segments.length > 32) throw targetError(400, 'Path too deep');
+  return segments;
+}
+
+export function resolveTargetRoot(parsedUrl, cwd) {
+  const kind = parsedUrl.searchParams.get('kind');
+  if (kind === 'claude-md') {
+    const id = parsedUrl.searchParams.get('id') || '';
+    if (!/^[0-9a-f]{12}$/i.test(id)) throw targetError(400, 'Invalid id');
+    const candidate = discoverClaudeMdCandidates({
+      cwd,
+      claudeConfigDir: getClaudeConfigDir(),
+      isReadAllowedFn: isReadAllowed,
+    }).find(entry => entry.id === id);
+    if (!candidate || basename(candidate.realPath) !== 'CLAUDE.md') throw targetError(404, 'Target not found');
+    return { ...targetScope(realDirectory(dirname(candidate.realPath), 'Directory'), cwd), targetKind: 'claude-md' };
+  }
+  if (kind !== 'skill') throw targetError(400, 'Invalid target kind');
+  const source = parsedUrl.searchParams.get('source');
+  const targetPath = parsedUrl.searchParams.get('targetPath');
+  if (!['user', 'project', 'plugin'].includes(source)) throw targetError(400, 'Invalid skill source');
+  if (typeof targetPath !== 'string' || !targetPath || targetPath.length > 4096 || targetPath.includes('\0')) {
+    throw targetError(400, 'Invalid skill path');
+  }
+  const skill = listSkills({ projectDir: cwd })
+    .find(entry => entry.source === source && entry.path === targetPath);
+  if (!skill) throw targetError(404, 'Target not found');
+  const rootReal = realDirectory(skill.path, 'Directory');
+  const scope = targetScope(rootReal, cwd);
+  const anchor = source === 'project'
+    ? scope.rootReal
+    : dirname(dirname(skill.path));
+  const anchorReal = realDirectory(anchor, 'Skill root');
+  if (!insidePath(rootReal, anchorReal)) throw targetError(403, 'Target outside skill root');
+  // Plugin root must follow the configured Claude config dir, not the default
+  // homedir()/.claude — otherwise plugin skills break under CLAUDE_CONFIG_DIR.
+  if (source === 'plugin' && !insidePath(rootReal, realDirectory(join(getClaudeConfigDir(), 'plugins'), 'Plugin root'))) {
+    throw targetError(403, 'Target outside plugin root');
+  }
+  return { ...scope, targetKind: 'skill' };
+}
+
+// ===========================================================================
+// Write-side scope resolution (used only by the /api/target-* write routes).
+// ===========================================================================
+
+// SECURITY / INTENTIONAL DESIGN (do NOT tighten in review without product sign-off):
+// the writable area for a target browser is the WHOLE navigation root returned by
+// targetNavigation (project / home / config / target), NOT just the target's own
+// subtree. This is a deliberate product decision — the user navigates the browser
+// up to ancestors (e.g. from a skill folder to ~ or ~/.claude) and expects the
+// context menu to keep working there. The sensitive-file / sensitive-directory
+// backstop for that wider surface is isWriteAllowed (lib/file-access-policy.js),
+// which every mutation runs through; containment in the navigation root plus
+// isWriteAllowed is the boundary, not the target subtree.
+export function resolveTargetWriteScope(parsedUrl, cwd) {
+  // Re-derive the target identity server-side (never trust a client-sent root).
+  // The writable surface is the WHOLE navigation root (scope.rootReal) — the
+  // target's own directory is NOT separately resolved here because the product
+  // decision is to allow writes anywhere in the navigation root, with the
+  // sensitive-file backstop living in isWriteAllowed (see file-access-policy.js).
+  return resolveTargetRoot(parsedUrl, cwd);
+}
+
+// targetRelPath treats null as "caller omitted path" (the read route uses that
+// to default to the target's own directory). The write routes always need an
+// explicit path, so this is the required variant: omitted → 400.
+export function requiredTargetRelPath(raw) {
+  const segs = targetRelPath(raw);
+  if (segs === null) throw targetError(400, 'Missing path');
+  return segs;
+}

package/server/proxy.js

@@ -1,5 +1,6 @@
 
 import { createServer } from 'node:http';
+import { Readable, Transform, pipeline } from 'node:stream';
 import { readFileSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
@@ -11,7 +12,7 @@ import { getClaudeConfigDir } from '../findcc.js';
 import { isAnthropicApiPath, classifyProxyRole } from './lib/interceptor-core.js';
 import { parseAgentId, findHeader } from './lib/v2/agent-id.js';
 import { liveSystemPromptEnabled } from './lib/system-prompt-live.js';
-import { executeRequest, extractModel } from './lib/proxy/proxy-retry.js';
+import { executeRequest, extractModel, isStreamResponse } from './lib/proxy/proxy-retry.js';
 import { buildRecord, appendRecord, dailyFilePath, todayStr, emitProxyStatsUpdate } from './lib/proxy/proxy-stats.js';
 import { reportSwallowed } from './lib/error-report.js';
 import { LOG_DIR } from '../findcc.js';
@@ -231,7 +232,6 @@ export function startProxy() {
         res.writeHead(response.status, responseHeaders);
 
         if (response.body) {
-          const { Readable, pipeline } = await import('node:stream');
           // @ts-ignore
           const nodeStream = Readable.fromWeb(response.body);
           // 持久 error handler 兜底：防止 pipeline 清理后延迟到达的 error 事件导致进程崩溃
@@ -388,15 +388,59 @@ async function handleLlmApiRequest(req, res, fullUrl, fetchOptions, body, proxyD
   res.writeHead(finalStatus, responseHeaders);
 
   if (response.body) {
-    const { Readable, pipeline } = await import('node:stream');
     // @ts-ignore
     const nodeStream = Readable.fromWeb(response.body);
     nodeStream.on('error', () => {});
-    pipeline(nodeStream, res, (err) => {
-      if (err && process.env.CCV_DEBUG) {
-        console.error('[CC-Viewer Proxy] Stream pipeline error:', err.message);
-      }
-    });
+    const streamIdleMs = retryConfig && retryConfig.mode === 'off'
+      ? (retryConfig.streamIdleTimeoutMs ?? 0)
+      : 0;
+    // Only gate SSE (streaming) responses: a non-stream body legitimately arrives as one
+    // whole payload after a long upstream think, and must not be truncated mid-wait.
+    if (streamIdleMs > 0 && isStreamResponse(response)) {
+      // Off-mode-only idle watchdog: retry modes already attach the equivalent
+      // guard on the Web-stream side upstream (applyStreamIdleWatchdog). That
+      // variant cannot run for off mode — its pipeThrough races the
+      // interceptor's getReader() body reconstruction (spurious `fetch failed`).
+      // This Node-side Transform sits after Readable.fromWeb, so it is immune
+      // to that race. The timer arms at construction, BEFORE the first chunk,
+      // so a stream that never sends its first byte is still bounded.
+      let watchdog = null;
+      let idleTimer = null;
+      const disarmIdle = () => {
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          idleTimer = null;
+        }
+      };
+      const armIdle = () => {
+        disarmIdle();
+        idleTimer = setTimeout(() => {
+          idleTimer = null;
+          // Log unconditionally: a destroyed stream surfaces downstream as an unexplained
+          // `fetch failed`; without this line there is no way to attribute it.
+          console.warn(`[CC-Viewer Proxy] off-mode stream idle timeout (${streamIdleMs}ms) — destroying upstream stream`);
+          watchdog.destroy(new Error(`proxy stream idle timeout (${streamIdleMs}ms)`));
+        }, streamIdleMs);
+        if (typeof idleTimer.unref === 'function') idleTimer.unref();
+      };
+      watchdog = new Transform({
+        transform(chunk, _enc, cb) { armIdle(); cb(null, chunk); },
+        flush(cb) { disarmIdle(); cb(); },
+        destroy(err, cb) { disarmIdle(); cb(err); },
+      });
+      armIdle();
+      pipeline(nodeStream, watchdog, res, (err) => {
+        if (err && process.env.CCV_DEBUG) {
+          console.error('[CC-Viewer Proxy] Stream pipeline error:', err.message);
+        }
+      });
+    } else {
+      pipeline(nodeStream, res, (err) => {
+        if (err && process.env.CCV_DEBUG) {
+          console.error('[CC-Viewer Proxy] Stream pipeline error:', err.message);
+        }
+      });
+    }
   } else if (response.text) {
     // 竞速失败兜底 response：用 text() 取 body
     const text = await response.text();

package/server/routes/files-content.js

@@ -1,10 +1,8 @@
 // Read-oriented file-access routes (moved verbatim from server.js handleRequest).
 import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync, realpathSync, createReadStream, readdirSync } from 'node:fs';
-import { join, basename, dirname, resolve, relative, sep } from 'node:path';
-import { homedir } from 'node:os';
-import { isReadAllowed, reasonToStatus } from '../lib/file-access-policy.js';
+import { join, basename, dirname, resolve, sep } from 'node:path';
+import { isReadAllowed, isWriteAllowed, reasonToStatus } from '../lib/file-access-policy.js';
 import { ERROR_STATUS_MAP, isPathContained } from '../lib/file-api.js';
-import { listSkills } from '../lib/skills-api.js';
 import { viewRootOrReply, resolveViewRoot } from '../lib/view-root.js';
 import { findSdkSessionByInstance } from '../lib/sdk-session-index.js';
 import { projectKeyForCwd } from '../lib/system-prompt-snapshots.js';
@@ -16,6 +14,10 @@ import { getClaudeConfigDir } from '../../findcc.js';
 import { _projectName } from '../interceptor.js';
 import { isAdminReq } from '../lib/is-admin.js';
 import { isSameOriginBrowserRequest } from '../lib/same-origin.js';
+import {
+  targetError, errnoToStatus, realDirectory, checkedDirectory, insidePath,
+  targetRelPath, resolveTargetRoot,
+} from '../lib/target-scope.js';
 
 // Multi-project file operations use the same viewed root for reads and writes.
 // Every file-browser mutation enforces realpath containment in that root;
@@ -546,6 +548,29 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
   // encoding. Normalize only this mutation's containment comparisons.
   let writeRoot;
   const isInsideWriteRoot = (path) => isPathContained(path, writeRoot);
+  // isPathContained realpaths its target, so it returns false for a not-yet-existing
+  // file — which wrongly 403s every new-file save in target mode. For a missing leaf,
+  // realpath the nearest existing ancestor, re-append the descent, then prefix-compare
+  // against the (already-real) write root; an existing path keeps the strict realpath.
+  const isInsideWriteRootAllowNew = (path) => {
+    if (isInsideWriteRoot(path)) return true;
+    if (existsSync(path)) return false; // exists but resolves outside → strict deny
+    const root = writeRoot.endsWith(sep) ? writeRoot : writeRoot + sep;
+    let cursor = resolve(path, '..');
+    const descent = [basename(path)];
+    for (let depth = 0; depth < 32; depth++) {
+      if (existsSync(cursor)) {
+        let rebuilt;
+        try { rebuilt = join(realpathSync(cursor), ...descent); } catch { return false; }
+        return rebuilt === writeRoot || rebuilt.startsWith(root);
+      }
+      const parent = resolve(cursor, '..');
+      if (parent === cursor) return false;
+      descent.unshift(basename(cursor));
+      cursor = parent;
+    }
+    return false;
+  };
   const MAX_BODY = 5 * 1024 * 1024; // 5MB，与 GET 路由限制对齐
   let body = '';
   let overflow = false;
@@ -563,7 +588,36 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
       const { path: reqPath, content, editorSession } = JSON.parse(body);
       const cwd = _viewRootOrReply(req, res, parsedUrl);
       if (!cwd) return;
-      try { writeRoot = realpathSync(cwd); } catch { writeRoot = cwd; }
+      // Target mode (the CLAUDE.md / skill browser modal) edits files that live in
+      // the target's NAVIGATION ROOT, which is frequently OUTSIDE the viewed project
+      // (~/.claude, $HOME). When the request carries a target identity
+      // (kind + id / source + targetPath, same as /api/target-files), resolve the
+      // write root to that navigation root instead of the project view root, so
+      // isInsideWriteRoot no longer 403s the file the user is explicitly editing.
+      // The target root is re-derived server-side (never trusted from the client),
+      // and the isWriteAllowed policy below still runs unchanged.
+      // SECURITY / INTENTIONAL DESIGN (do NOT tighten in review without product
+      // sign-off): in target mode the write policy is the WHOLE navigation root,
+      // and writes go through isWriteAllowed (NOT isReadAllowed) — so the LOG_DIR
+      // tree, ~/.claude credentials/settings, ~/.ssh, and the config-backup tree
+      // stay unwritable even though the wider surface is editable. This path is
+      // gated to admin + same-origin browser requests, the same bar as
+      // /api/target-files, because it can reach the user's home tree. A relative
+      // path in target mode is anchored at the navigation root, not the project.
+      const targetKind = parsedUrl.searchParams.get('kind');
+      let targetNavRoot = null;
+      if (targetKind) {
+        if (!isAdminReq(req, isLocal) || !isSameOriginBrowserRequest(req, parsedUrl)) {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'forbidden' }));
+          return;
+        }
+        const scope = resolveTargetRoot(parsedUrl, cwd);
+        writeRoot = scope.rootReal;
+        targetNavRoot = scope.rootReal;
+      } else {
+        try { writeRoot = realpathSync(cwd); } catch { writeRoot = cwd; }
+      }
       if (!reqPath) {
         res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Invalid path' }));
@@ -575,12 +629,18 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
         return;
       }
       const isAbs = /^([a-zA-Z]:[\\/]|[\\/])/.test(reqPath);
-      const absPath = isAbs ? reqPath : resolve(cwd, reqPath);
+      // In target mode a relative path is anchored at the navigation root; in
+      // project mode at the project view root (unchanged legacy behavior).
+      const absPath = isAbs ? reqPath : resolve(targetNavRoot || cwd, reqPath);
       // 写路径同样走 policy(收敛 editorSession 后门):允许覆盖现有文件;
       // 新文件场景递归向上找最近存在的祖先目录,只要它在 allowlist 内即放行。
       // (旧实现只查 immediate parent,父目录也不存在时误拒嵌套新建。)
+      // Target mode uses the WRITE policy (isWriteAllowed) so the LOG_DIR tree,
+      // ~/.claude credentials and other sensitive targets stay unwritable even
+      // though the navigation root is editable; project mode keeps isReadAllowed.
+      const policyFn = targetNavRoot ? isWriteAllowed : isReadAllowed;
       let targetReal;
-      const policy = isReadAllowed(absPath);
+      const policy = policyFn(absPath);
       if (policy.ok) {
         targetReal = policy.real;
       } else if (policy.reason === 'realpath-failed') {
@@ -644,7 +704,16 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
         res.end(JSON.stringify({ error: 'Forbidden', reason: 'editor-session-requires-admin' }));
         return;
       }
-      if (!editorSession && existsSync(targetReal) && !isInsideWriteRoot(targetReal)) {
+      // Target mode: containment in the navigation root must hold whether the file
+      // exists OR is being created — otherwise a crafted relative path could write
+      // outside the navigation root (isWriteAllowed only bounds by the allowlist).
+      // Project mode keeps the legacy existing-file-only check.
+      if (!editorSession && targetNavRoot && !isInsideWriteRootAllowNew(targetReal)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Forbidden', reason: 'outside-view-root' }));
+        return;
+      }
+      if (!editorSession && !targetNavRoot && existsSync(targetReal) && !isInsideWriteRoot(targetReal)) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Forbidden', reason: 'outside-view-root' }));
         return;
@@ -654,7 +723,9 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ ok: true, size: stat.size }));
     } catch (err) {
-      const status = ERROR_STATUS_MAP[err.code] || 500;
+      // targetError carries `.status` (400/403/404); fs errnos carry `.code`.
+      // Honor both so an invalid/stale target identity is not reported as 500.
+      const status = err.status || ERROR_STATUS_MAP[err.code] || 500;
       const message = status === 500 ? `Cannot save file: ${err.message}` : err.message;
       res.writeHead(status, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: message }));
@@ -662,130 +733,6 @@ function fileContentPost(req, res, parsedUrl, isLocal) {
   });
 }
 
-function targetError(status, message) {
-  return Object.assign(new Error(message), { status });
-}
-
-// Map fs errno to a sensible HTTP status: missing → 404, permission → 403,
-// symlink loop → 400 (treat as malformed), anything else → 404 (don't leak).
-function errnoToStatus(err) {
-  const code = err?.code;
-  if (code === 'EACCES' || code === 'EPERM') return 403;
-  if (code === 'ELOOP') return 400;
-  return 404;
-}
-
-function realDirectory(path, label) {
-  let real;
-  try { real = realpathSync(path); } catch (err) { throw targetError(errnoToStatus(err), `${label} not found`); }
-  let st;
-  try { st = statSync(real); } catch (err) { throw targetError(errnoToStatus(err), `${label} not found`); }
-  if (!st.isDirectory()) throw targetError(400, `${label} is not a directory`);
-  return real;
-}
-
-function checkedDirectory(path, label) {
-  const real = realDirectory(path, label);
-  const policy = isReadAllowed(real);
-  if (!policy.ok) throw targetError(reasonToStatus(policy.reason), `${label} not readable`);
-  return policy.real;
-}
-
-function insidePath(path, root) {
-  return path === root || path.startsWith(root + sep);
-}
-
-function targetNavigation(targetReal, cwd) {
-  const projectReal = realDirectory(cwd, 'Project');
-  if (insidePath(targetReal, projectReal)) return { rootReal: projectReal, rootKind: 'project' };
-  // $HOME becomes the navigation root for home-resident targets (user skills,
-  // plugins, the global CLAUDE.md). Entries outside the allowlist (e.g. ~/.ssh,
-  // ~/.aws) are filtered per-entry by isReadAllowed, and sensitive paths inside
-  // ~/.claude are covered by file-access-policy's denylist. The /api/target-files
-  // handler additionally gates this endpoint behind isAdminReq + same-origin so
-  // a cross-site page cannot enumerate the user's home tree.
-  const homeReal = realDirectory(homedir(), 'Home');
-  if (insidePath(targetReal, homeReal)) {
-    checkedDirectory(targetReal, 'Directory');
-    return { rootReal: homeReal, rootKind: 'home' };
-  }
-  const configReal = realDirectory(getClaudeConfigDir(), 'Claude config');
-  if (insidePath(targetReal, configReal)) {
-    checkedDirectory(targetReal, 'Directory');
-    return { rootReal: realDirectory(dirname(configReal), 'Config root'), rootKind: 'config' };
-  }
-  // Allowlist fallback: targets that live inside another allowlisted root
-  // (registered workspaces, /tmp/cc-viewer-uploads, etc.) are reachable via
-  // /api/claude-md's discovery (which uses isReadAllowed), so we must not
-  // 403 them here. Use the target's own directory as the navigation root —
-  // no parent browsing, but at least the entry the user clicked actually opens.
-  const policy = isReadAllowed(targetReal);
-  if (!policy.ok) throw targetError(reasonToStatus(policy.reason), 'Target not readable');
-  return { rootReal: realDirectory(targetReal, 'Target'), rootKind: 'target' };
-}
-
-function targetScope(targetReal, cwd) {
-  const navigation = targetNavigation(targetReal, cwd);
-  return { ...navigation, targetPath: relative(navigation.rootReal, targetReal).split(sep).join('/') };
-}
-
-function targetRelPath(raw) {
-  if (raw == null) return null;
-  if (raw === '') return [];
-  if (typeof raw !== 'string' || raw.length > 2048 || raw.includes('\0') || raw.includes('\\')
-    || raw.startsWith('/') || /^[a-zA-Z]:/.test(raw)) {
-    throw targetError(400, 'Invalid path');
-  }
-  const segments = raw.split('/');
-  if (segments.some(segment => !segment || segment === '.' || segment === '..')) {
-    throw targetError(400, 'Invalid path');
-  }
-  // Hard cap on navigation depth: each segment triggers at least one
-  // synchronous readdir + per-entry realpath/stat in `ancestors`, and a 2KB
-  // free-form path could otherwise fan out into hundreds of syscalls per
-  // request. 32 is far deeper than any realistic skill / CLAUDE.md location.
-  if (segments.length > 32) throw targetError(400, 'Path too deep');
-  return segments;
-}
-
-function resolveTargetRoot(parsedUrl, cwd) {
-  const kind = parsedUrl.searchParams.get('kind');
-  if (kind === 'claude-md') {
-    const id = parsedUrl.searchParams.get('id') || '';
-    if (!/^[0-9a-f]{12}$/i.test(id)) throw targetError(400, 'Invalid id');
-    const candidate = discoverClaudeMdCandidates({
-      cwd,
-      claudeConfigDir: getClaudeConfigDir(),
-      isReadAllowedFn: isReadAllowed,
-    }).find(entry => entry.id === id);
-    if (!candidate || basename(candidate.realPath) !== 'CLAUDE.md') throw targetError(404, 'Target not found');
-    return { ...targetScope(realDirectory(dirname(candidate.realPath), 'Directory'), cwd), targetKind: 'claude-md' };
-  }
-  if (kind !== 'skill') throw targetError(400, 'Invalid target kind');
-  const source = parsedUrl.searchParams.get('source');
-  const targetPath = parsedUrl.searchParams.get('targetPath');
-  if (!['user', 'project', 'plugin'].includes(source)) throw targetError(400, 'Invalid skill source');
-  if (typeof targetPath !== 'string' || !targetPath || targetPath.length > 4096 || targetPath.includes('\0')) {
-    throw targetError(400, 'Invalid skill path');
-  }
-  const skill = listSkills({ projectDir: cwd })
-    .find(entry => entry.source === source && entry.path === targetPath);
-  if (!skill) throw targetError(404, 'Target not found');
-  const rootReal = realDirectory(skill.path, 'Directory');
-  const scope = targetScope(rootReal, cwd);
-  const anchor = source === 'project'
-    ? scope.rootReal
-    : dirname(dirname(skill.path));
-  const anchorReal = realDirectory(anchor, 'Skill root');
-  if (!insidePath(rootReal, anchorReal)) throw targetError(403, 'Target outside skill root');
-  // Plugin root must follow the configured Claude config dir, not the default
-  // homedir()/.claude — otherwise plugin skills break under CLAUDE_CONFIG_DIR.
-  if (source === 'plugin' && !insidePath(rootReal, realDirectory(join(getClaudeConfigDir(), 'plugins'), 'Plugin root'))) {
-    throw targetError(403, 'Target outside plugin root');
-  }
-  return { ...scope, targetKind: 'skill' };
-}
-
 function listTargetDirectory(rootReal, segments, deps, requireReadable = true) {
   const dirReal = requireReadable
     ? checkedDirectory(segments.length ? join(rootReal, ...segments) : rootReal, 'Directory')

package/server/routes/files-fs.js

@@ -5,11 +5,12 @@ import {
 } from 'node:fs';
 import { join, dirname, basename, resolve, sep } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
-import { execFile, spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { bumpWorkspacesVersion, isReadAllowed } from '../lib/file-access-policy.js';
 import { isPathContained, validateImportDir, renameSyncWithRetry } from '../lib/file-api.js';
 import { reportSwallowed } from '../lib/error-report.js';
 import { viewRootOrReply } from '../lib/view-root.js';
+import { revealInOs, openTerminalAt } from '../lib/os-open.js';
 import { loadWorkspaces } from '../workspace-registry.js';
 import { listLivePtys } from '../pty-manager.js';
 import { PROFILE_PATH, _projectName, _logDir } from '../interceptor.js';
@@ -645,17 +646,12 @@ function revealFile(req, res, parsedUrl, isLocal, deps) {
         return;
       }
       const plat = process.platform;
-      if (plat === 'darwin') {
-        execFile('open', ['-R', fullPath], () => {});
-      } else if (plat === 'win32') {
-        // explorer /select 的规范形式是 /select,"<path>"（仅路径部分加引号、整体一个 arg）。
-        // 必须 windowsVerbatimArguments 透传：否则 Node 对含空格 arg 整体加引号生成
-        // explorer.exe "/select,C:\My Proj\x.txt"，explorer 解析不了 → 功能失效。
-        // Windows 文件名不允许 "，且不经 cmd.exe，无元字符注入面。
-        const child = spawn('explorer.exe', [`/select,"${fullPath}"`], { windowsVerbatimArguments: true, windowsHide: true });
-        child.on('error', () => {}); // 防 async ENOENT 变 uncaughtException 砸进程
+      if (plat === 'darwin' || plat === 'win32') {
+        revealInOs(fullPath);
       } else {
-        execFile('xdg-open', [dirname(fullPath)], () => {});
+        // Linux: a directory reveals itself; a file reveals its parent (xdg-open on
+        // a file would launch the default app). Shared helper, see lib/os-open.js.
+        revealInOs(fullPath, { isDir: statSync(fullPath).isDirectory() });
       }
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ ok: true, fullPath }));
@@ -919,49 +915,7 @@ function openTerminal(req, res, parsedUrl, isLocal, deps) {
         res.end(JSON.stringify({ error: 'Path traversal not allowed' }));
         return;
       }
-      const plat = process.platform;
-      if (plat === 'darwin') {
-        spawn('open', ['-a', 'Terminal', fullDir], { stdio: 'ignore', detached: true }).unref();
-      } else if (plat === 'win32') {
-        spawn('cmd.exe', ['/c', 'start', 'cmd.exe'], { cwd: fullDir, stdio: 'ignore', detached: true, windowsHide: true }).unref();
-      } else {
-        // Linux: try common terminal emulators
-        const terminals = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'xterm'];
-        // spawn reports a missing executable asynchronously, outside try/catch.
-        // Probe each candidate with piped stdio so the next one can be attempted
-        // after ENOENT; detach only after a successful spawn.
-        const tryTerminal = (index) => {
-          if (index >= terminals.length) {
-            const child = spawn('xdg-open', [fullDir], { stdio: 'ignore', detached: true });
-            child.on('error', (err) => { reportSwallowed('filesFs.openTerminal', err, { terminal: 'xdg-open' }); });
-            child.unref();
-            return;
-          }
-          const term = terminals[index];
-          let child;
-          try {
-            if (term === 'gnome-terminal') {
-              child = spawn(term, ['--working-directory=' + fullDir], { stdio: 'pipe' });
-            } else if (term === 'konsole') {
-              child = spawn(term, ['--workdir', fullDir], { stdio: 'pipe' });
-            } else {
-              child = spawn(term, [], { cwd: fullDir, stdio: 'pipe' });
-            }
-          } catch {
-            tryTerminal(index + 1);
-            return;
-          }
-          child.once('error', (err) => {
-            reportSwallowed('filesFs.openTerminal', err, { terminal: term });
-            tryTerminal(index + 1);
-          });
-          child.once('spawn', () => {
-            for (const stream of [child.stdin, child.stdout, child.stderr]) stream?.destroy();
-            child.unref();
-          });
-        };
-        tryTerminal(0);
-      }
+      openTerminalAt(fullDir);
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ ok: true }));
     } catch (err) {