coxpit 5.20.0 → 5.23.0

package/README.md

@@ -72,6 +72,23 @@ Your keys and login never touch coxpit's config or database.
 
 > **New here?** The **[full guide](docs/GUIDE.md)** ([한국어](docs/GUIDE.ko.md)) walks through starting a new project, your first fleet, comparing and merging, doc mode, the terminal, remote access, and every feature — task by task, with GIFs.
 
+## Dispatch from the terminal
+
+The daemon isn't only a web board — you can throw work at a project straight from a shell. Handy when your main workspace session is a terminal and you just want to fan agents at a repo without leaving it. You name the target project each time (no sticky default — the target stays visible in the command you typed):
+
+```console
+$ coxpit ls                              # projects + active runs
+  triforge   2 running
+  keeping    idle
+$ coxpit fan triforge "add retry to the uploader" -n 2
+  ▶ triforge · 2 runs (dry) · r58 r59
+$ coxpit ps                              # what's running
+$ coxpit steer r58 "log the retries too"
+$ coxpit add /path/to/repo               # register a repo as a project
+```
+
+Runs land in the project like any board-launched run (isolated worktree + branch, reviewable in the board/cockpit Review). Default is a **dry rehearsal** — add `--real` to spend credits (`-n` sets parallelism 1–8, `--agent`/`--model` override). The CLI finds the daemon via its lock file; if auth is on, set `COXPIT_KEY` (or `COXPIT_AUTH_PASS`) to your access key.
+
 ## Configuration
 
 | env | default | what |
@@ -79,6 +96,7 @@ Your keys and login never touch coxpit's config or database.
 | `COXPIT_HOST` / `COXPIT_PORT` | `127.0.0.1` / `8210` | daemon bind. If the port is busy the daemon **auto-moves to the next free port** (see the startup log / lock file for the actual one) |
 | `COXPIT_PORT_STRICT` | — | `1` = fail instead of auto-moving when the port is busy (pin a fixed port behind a reverse proxy) |
 | `COXPIT_DB` | `~/.coxpit/coxpit.db` | SQLite (libSQL) file (a legacy `./coxpit.db` in the cwd is still honored) |
+| `COXPIT_FILES_ROOT` | `~` (home) | root the built-in file viewer may read/edit within. `/` opens the whole filesystem. Also settable in **Settings → File viewer** (applies immediately, no restart); env wins and locks the field. An authed user already has a full shell (the terminal), so this is defense-in-depth for an exposed daemon, not real confinement — widen it on a box you trust |
 | `COXPIT_AUTH_PASS` | — | access key (back-compat, key-only). If set on an **exposed** bind, the branded unlock page asks for this key — no username. Empty = use the stored key, or first-run setup |
 | `COXPIT_AUTH_DISABLED` | — | `1` forces auth **off** (delegate to a front gateway like Cloudflare Access / Tailscale) |
 | `COXPIT_SSH_KEY` | — | private key for remote machines (else ssh defaults/agent) |

package/bin/coxpit.js

@@ -7,6 +7,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { readFileSync, existsSync, rmSync } from 'node:fs';
+import http from 'node:http';
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const entry = join(root, 'src', 'index.ts');
@@ -28,6 +29,18 @@ Usage:
   coxpit --version, -v   print version
   coxpit --help, -h      show this help
 
+Dispatch orchestration to a project (from your workspace terminal):
+  coxpit ls                             list projects + active runs
+  coxpit fan <project> "<goal>" [opts]  launch agent runs on <project>
+       -n N          number of parallel runs (1-8, default 1)
+       --real        run the real agent (spends credits; default is dry rehearsal)
+       --agent X     claude-code | codex     --model M   model override
+  coxpit ps                             list active runs
+  coxpit steer <run> "<message>"        send follow-up to a running agent
+  coxpit add <path>                     register a git repo as a project
+  The target is always named per command (no sticky default). Talks to the local
+  daemon via its lock file; set COXPIT_KEY (or COXPIT_AUTH_PASS) if auth is on.
+
 Access-key auth:
   On first boot with no key, open the board to set an access key (a one-time
   setup token is printed to the log — needed unless you visit http://127.0.0.1
@@ -65,13 +78,129 @@ if (args[0] === 'reset-key') {
   process.exit(0);
 }
 
-// --import 의 bare 'tsx' 는 사용자 cwd 기준으로 해석돼 npx 실행에서 깨진다 —
-// 패키지 루트 기준으로 절대경로 해석해 넘긴다.
-const require_ = createRequire(join(root, 'package.json'));
-const tsxEntry = pathToFileURL(require_.resolve('tsx')).href;
+// ── Orchestration from the terminal — dispatch to the local daemon ──────────
+// The session is your workspace command post; you name the target project per
+// command (no sticky default — the target is always visible in what you typed).
+// Reuses the same API the board uses; loopback is still key-gated, so we auth
+// with COXPIT_KEY / COXPIT_AUTH_PASS when the daemon requires it.
+const SUBCMDS = new Set(['ls', 'projects', 'fan', 'run', 'ps', 'steer', 'add']);
+if (SUBCMDS.has(args[0])) {
+  const dbEnv = process.env.COXPIT_DB;
+  const dir = dbEnv ? dirname(resolve(dbEnv)) : join(homedir(), '.coxpit');
+  const lockPath = join(dir, 'daemon.lock.json');
+
+  const die = (msg) => { console.error('coxpit: ' + msg); process.exit(1); };
+  let port;
+  try {
+    const lk = JSON.parse(readFileSync(lockPath, 'utf8'));
+    if (!Number.isInteger(lk?.port)) throw new Error('no port');
+    port = lk.port;
+  } catch {
+    die('no running daemon (lock not found at ' + lockPath + ') — start it with "coxpit".');
+  }
+  const key = process.env.COXPIT_KEY || process.env.COXPIT_AUTH_PASS || '';
+  const authHeaders = key ? { authorization: 'Basic ' + Buffer.from('coxpit:' + key).toString('base64') } : {};
+
+  const api = (method, path, body) => new Promise((res, rej) => {
+    const data = body != null ? JSON.stringify(body) : null;
+    const req = http.request(
+      { host: '127.0.0.1', port, path, method, headers: { 'content-type': 'application/json', ...authHeaders, ...(data ? { 'content-length': Buffer.byteLength(data) } : {}) } },
+      (r) => { let b = ''; r.on('data', (d) => b += d); r.on('end', () => { let j = null; try { j = b ? JSON.parse(b) : null; } catch { /* non-json */ } res({ status: r.statusCode, json: j, raw: b }); }); },
+    );
+    req.on('error', rej); if (data) req.write(data); req.end();
+  });
+  const guard = (r) => {
+    if (r.status === 401) die('daemon requires an access key — set COXPIT_KEY (or COXPIT_AUTH_PASS) to your key.');
+    if (r.status >= 400) die((r.json && r.json.error) || ('HTTP ' + r.status));
+    return r;
+  };
+  const num = (flag, def) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] != null ? Number(args[i + 1]) : def; };
+  const str = (flag, def) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] != null ? args[i + 1] : def; };
+  const has = (flag) => args.includes(flag);
+  // positional args = everything that isn't a flag or a flag's value
+  const positionals = () => {
+    const flagsWithVal = new Set(['-n', '--count', '--agent', '--model']);
+    const out = []; for (let i = 1; i < args.length; i++) { const a = args[i]; if (a.startsWith('-')) { if (flagsWithVal.has(a)) i++; continue; } out.push(a); }
+    return out;
+  };
+  const realRepos = async () => (guard(await api('GET', '/api/fleet?view=all')).json.repos || []).filter((r) => r.kind !== 'sessions');
+  const matchRepo = (repos, name) => {
+    const n = String(name || '').toLowerCase();
+    let hit = repos.filter((r) => r.name.toLowerCase() === n);
+    if (!hit.length) hit = repos.filter((r) => r.name.toLowerCase().startsWith(n));
+    if (!hit.length) hit = repos.filter((r) => r.name.toLowerCase().includes(n));
+    return hit;
+  };
+
+  (async () => {
+    const cmd = args[0];
+    if (cmd === 'ls' || cmd === 'projects') {
+      const fleet = guard(await api('GET', '/api/fleet?view=all')).json;
+      const repos = (fleet.repos || []).filter((r) => r.kind !== 'sessions');
+      const runs = fleet.runs || [];
+      if (!repos.length) { console.log('no projects registered — "coxpit add <path>" or register one in the board.'); process.exit(0); }
+      const active = (repoId) => runs.filter((r) => { const t = (fleet.tasks || []).find((x) => x.id === r.taskId); return t && t.repoId === repoId && (r.status === 'running' || r.status === 'pending'); }).length;
+      const w = Math.max(...repos.map((r) => r.name.length), 7);
+      for (const r of repos) { const a = active(r.id); console.log('  ' + r.name.padEnd(w) + '  ' + (a ? a + ' running' : 'idle')); }
+      process.exit(0);
+    }
+    if (cmd === 'ps') {
+      const fleet = guard(await api('GET', '/api/fleet?view=all')).json;
+      const repoName = Object.fromEntries((fleet.repos || []).map((r) => [r.id, r.name]));
+      const taskById = Object.fromEntries((fleet.tasks || []).map((t) => [t.id, t]));
+      const live = (fleet.runs || []).filter((r) => r.status === 'running' || r.status === 'pending');
+      if (!live.length) { console.log('no active runs.'); process.exit(0); }
+      for (const r of live) { const t = taskById[r.taskId]; const rn = t ? repoName[t.repoId] : '?'; console.log('  r' + r.id + '  ' + r.status.padEnd(8) + '  ' + (rn || '?') + '  ' + (t ? t.title : '').slice(0, 50)); }
+      process.exit(0);
+    }
+    if (cmd === 'add') {
+      const p = positionals()[0]; if (!p) die('usage: coxpit add <path>');
+      const abs = resolve(p);
+      const r = guard(await api('POST', '/api/repos', { machineSlug: 'local', path: abs }));
+      console.log('registered ' + (r.json.repo ? r.json.repo.name : abs));
+      process.exit(0);
+    }
+    if (cmd === 'steer') {
+      const pos = positionals(); const rid = String(pos[0] || '').replace(/^r/, ''); const msg = pos.slice(1).join(' ');
+      if (!rid || !msg) die('usage: coxpit steer <run> "<message>"');
+      guard(await api('POST', '/api/runs/' + Number(rid) + '/steer', { message: msg }));
+      console.log('steered r' + rid);
+      process.exit(0);
+    }
+    if (cmd === 'fan' || cmd === 'run') {
+      const pos = positionals();
+      const project = pos[0]; const goal = pos.slice(1).join(' ');
+      if (!project || !goal) die('usage: coxpit fan <project> "<goal>" [-n N] [--real] [--agent claude-code|codex] [--model M]');
+      const repos = await realRepos();
+      const hit = matchRepo(repos, project);
+      if (!hit.length) die('no project matches "' + project + '" — try "coxpit ls".');
+      if (hit.length > 1) die('"' + project + '" is ambiguous: ' + hit.map((r) => r.name).join(', '));
+      const repo = hit[0];
+      const count = Math.max(1, Math.min(8, num('-n', num('--count', 1)) || 1));
+      const real = has('--real');
+      const agent = str('--agent', undefined);
+      const model = str('--model', undefined);
+      const task = guard(await api('POST', '/api/tasks', { repoId: repo.id, title: goal.slice(0, 140), prompt: goal })).json.task;
+      const body = { count, real }; if (agent) body.agent = agent; if (model) body.model = model;
+      const runs = guard(await api('POST', '/api/tasks/' + task.id + '/run', body)).json.runs || [];
+      console.log('▶ ' + repo.name + ' · ' + count + (count === 1 ? ' run' : ' runs') + (real ? ' (real)' : ' (dry)') + ' · ' + runs.map((r) => 'r' + r.id).join(' '));
+      console.log('  watch: coxpit ps  ·  compare/merge in the board/cockpit Review');
+      process.exit(0);
+    }
+  })().catch((e) => die(String(e && e.message || e)));
+}
+
+// 서브커맨드는 위 async IIFE 가 처리하고 스스로 exit 한다 — 데몬 기동으로 fall through 하면 안 됨
+// (async 라 동기 흐름이 여기까지 내려오므로 명시 가드).
+if (!SUBCMDS.has(args[0])) {
+  // --import 의 bare 'tsx' 는 사용자 cwd 기준으로 해석돼 npx 실행에서 깨진다 —
+  // 패키지 루트 기준으로 절대경로 해석해 넘긴다.
+  const require_ = createRequire(join(root, 'package.json'));
+  const tsxEntry = pathToFileURL(require_.resolve('tsx')).href;
 
-const child = spawn(process.execPath, ['--import', tsxEntry, entry, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-  env: process.env,
-});
-child.on('exit', (code, sig) => process.exit(code ?? (sig ? 1 : 0)));
+  const child = spawn(process.execPath, ['--import', tsxEntry, entry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  child.on('exit', (code, sig) => process.exit(code ?? (sig ? 1 : 0)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coxpit",
-  "version": "5.20.0",
+  "version": "5.23.0",
   "description": "Self-hosted cockpit for running a fleet of AI coding agents across your own machines — parallel worktree runs, live board, compare & merge, web terminal, design capture.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/board.ts

@@ -1781,6 +1781,11 @@ async function renderSettings(){
         + '<input id="setHost" value="'+escA(ef.host)+'" placeholder="127.0.0.1"'+dis(L.host)+'></label>'
       + '<div class="set-note">Port and host apply on the next daemon restart.</div>'
     + '</div>'
+    + '<div class="set-sec"><div class="set-h">File viewer</div>'
+      + '<label class="set-row"><span class="set-lbl">Viewer root '+lockNote(L.filesRoot,'COXPIT_FILES_ROOT')+'</span>'
+        + '<input id="setFilesRoot" value="'+escA(ef.filesRoot||'')+'" placeholder="home (default) — set / for the whole filesystem"'+dis(L.filesRoot)+'></label>'
+      + '<div class="set-note">Folders the file viewer may open. Empty = your home folder; <code>/</code> = the whole filesystem; or an absolute path. Applies immediately. An authed user already has a full shell (the terminal), so this bounds an exposed daemon, not real confinement.</div>'
+    + '</div>'
     + '<div class="set-sec"><div class="set-h">Access key</div>'
       + '<div class="set-state">'+esc(keyState)+'</div>'
       + (au.canManage
@@ -1827,6 +1832,7 @@ function wireSettings(){
     const body = { agent:{} };
     if (!L.port){ body.port = Number($('setPort').value); body.portStrict = $('setStrict').checked; }
     if (!L.host) body.host = $('setHost').value.trim();
+    if (!L.filesRoot) body.filesRoot = $('setFilesRoot').value.trim();
     if (!L.webhookUrl) body.webhookUrl = $('setWebhook').value.trim();
     if (!L.publicUrl) body.publicUrl = $('setPublic').value.trim();
     body.agent.provider = $('setProv').value;

package/src/cockpit.ts

@@ -57,11 +57,12 @@ export const COCKPIT_HTML = /* html */ `<!doctype html>
   .layout > *{min-height:0;min-width:0}
 
   /* ── workspace tree ── */
-  .rail{border-right:1px solid var(--line);overflow:auto;padding:10px 8px;font-family:var(--mono);font-size:12.5px;display:flex;flex-direction:column}
+  .rail{border-right:1px solid var(--line);overflow:auto;padding:10px 8px;font-family:var(--mono);font-size:12.5px;display:flex;flex-direction:column;scrollbar-width:none;-ms-overflow-style:none}
+  .rail::-webkit-scrollbar{width:0;height:0;display:none}   /* 스크롤 UI 제거(흰 바), 스크롤 기능은 유지 */
   .lbl{font-size:10px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);padding:6px 8px 10px;display:flex;justify-content:space-between}
   .tnode{display:flex;align-items:center;gap:8px;padding:6px 8px;border-radius:7px;color:var(--muted);white-space:nowrap;cursor:default}
   .tnode .car{color:var(--faint);width:9px;display:inline-block;text-align:center;cursor:pointer}
-  .tnode .n{overflow:hidden;text-overflow:ellipsis;flex:1}
+  .tnode .n{overflow:hidden;text-overflow:ellipsis;flex:1;min-width:0}
   .tnode .meta{color:var(--faint);font-size:11px}
   .tnode.repo{color:var(--ink)}
   .tnode.goal{padding-left:20px} .tnode.goal .gi{color:var(--brand)}
@@ -220,7 +221,9 @@ export const COCKPIT_HTML = /* html */ `<!doctype html>
   .lbl .lnk{color:var(--brand);cursor:pointer;font-size:10px;letter-spacing:0;text-transform:none}
   .tnode.session{padding-left:20px;cursor:pointer} .tnode.session:hover{background:var(--surface)}
   .tnode.session.open{background:var(--brand-dim);color:var(--ink);box-shadow:inset 0 0 0 1px rgba(78,201,176,.22)}
-  .tnode.session .p{color:var(--faint);font-size:10.5px;overflow:hidden;text-overflow:ellipsis}
+  /* 이름 우선: .n(flex:1) 이 공간을 갖고, 경로는 끝만 짧게(고정 폭) — hover 시 title 로 전체 표시 */
+  .tnode.session .p{flex:0 1 auto;max-width:64px;color:var(--faint);font-size:10.5px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;direction:rtl;text-align:left}
+  .tnode.session:hover .p{color:var(--muted)}
   .tnode.session .del{margin-left:auto;color:var(--faint);border:none;background:none;cursor:pointer;font-size:13px;line-height:1;padding:0 3px;opacity:0;flex:none}
   .tnode.session:hover .del{opacity:1} .tnode.session .del:hover{color:var(--failed)}
   body.touch .tnode.session .del{opacity:.65}
@@ -552,8 +555,11 @@ export const COCKPIT_HTML = /* html */ `<!doctype html>
     if (sessRuns.length){
       sessRuns.forEach(function(s){
         var r=s.run; var open = tabs[r.id] ? ' open' : '';
-        html += '<div class="tnode session'+open+'" data-run="'+r.id+'"><span class="st '+esc(r.status)+'"></span>'
-          + '<span class="n">'+esc(s.title||'session')+'</span><span class="p">'+esc((r.worktreePath||'').replace(/^.*\\/([^/]+\\/[^/]+)$/,'…/$1'))+'</span>'
+        var sPath=(r.worktreePath||'');
+        var sTail=sPath.replace(/^.*\\/([^/]+)$/,'$1');   // 마지막 폴더명만(끝 조금)
+        html += '<div class="tnode session'+open+'" data-run="'+r.id+'" title="'+esc(sPath)+'"><span class="st '+esc(r.status)+'"></span>'
+          + '<span class="n" title="'+esc(s.title||'session')+'">'+esc(s.title||'session')+'</span>'
+          + '<span class="p" title="'+esc(sPath)+'">'+esc(sTail)+'</span>'
           + '<button class="del" data-delsession="'+r.id+'" title="세션 삭제 — 터미널만 종료, 폴더·파일은 보존">×</button></div>';
       });
     } else {

package/src/config.ts

@@ -46,7 +46,7 @@ const settingsPath = path.join(path.dirname(path.resolve(dbPath)), 'settings.jso
 // 영속 설정(settings.json)을 인라인으로 읽는다(순환 import 회피 — settings.ts 는 config 를 import).
 // 병합 우선순위: 명시 env > settings.json > 기본값.
 interface StoredSettings {
-  port?: number; portStrict?: boolean; host?: string; webhookUrl?: string; publicUrl?: string;
+  port?: number; portStrict?: boolean; host?: string; filesRoot?: string; webhookUrl?: string; publicUrl?: string;
   agent?: { provider?: string; model?: string; count?: number; real?: boolean };
 }
 const stored: StoredSettings = (() => {
@@ -75,6 +75,7 @@ export const config = {
   // UTF-8 보장된 로케일 — PTY/원격 셸에 명시 전달용
   lang: process.env.LANG!,
   host: env.COXPIT_HOST ?? stored.host ?? '127.0.0.1',
+  filesRoot: env.COXPIT_FILES_ROOT ?? stored.filesRoot ?? '',   // '' = home; '/' = whole fs (file viewer)
   // 선호 포트(env > settings > 8210). 점유 시 index.ts 가 자동 이동(portStrict 면 실패).
   port: num(env.COXPIT_PORT) ?? stored.port ?? 8210,
   // 포트 점유 시 자동 이동 대신 실패(리버스 프록시 등 고정 포트가 필수인 경우).
@@ -105,6 +106,7 @@ export const config = {
   envLocked: {
     port: env.COXPIT_PORT != null,
     host: env.COXPIT_HOST != null,
+    filesRoot: env.COXPIT_FILES_ROOT != null,
     webhookUrl: env.COXPIT_WEBHOOK_URL != null,
     publicUrl: env.COXPIT_PUBLIC_URL != null,
     real: env.COXPIT_AGENT_REAL != null,

package/src/files.ts

@@ -1,14 +1,33 @@
-// File viewer/edit backing (owner-only tool). Scoped to the daemon user's home
-// directory — reading file *contents* is higher-risk than /api/browse's dir listing,
-// so we jail here. All real work (repos, worktrees, sessions, ~/services) lives under ~.
+// File viewer/edit backing (owner-only tool). Scoped to a root — default the
+// daemon user's home. coxpit already grants a full shell to an authed user (the
+// terminal), so this jail is defense-in-depth for an *exposed* daemon, not a real
+// confinement; widen it with COXPIT_FILES_ROOT ("/" = whole filesystem) on a box
+// you trust. Everything under ~ (repos, worktrees, sessions, ~/services) is in the
+// default root.
 import { readdir, stat, readFile, writeFile, realpath } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { resolve as presolve, dirname as pdirname, join as pjoin, basename as pbasename, extname as pextname } from 'node:path';
+import { readSettings } from './settings';
 
 const HOME = presolve(homedir());
 const MAX_TEXT = 2 * 1024 * 1024;      // read as text up to 2MB
 const MAX_WRITE = 512 * 1024;          // edit-save cap (.env etc. are tiny)
 
+// Allowed root for reads/edits — resolved per call so the in-app Settings change
+// takes effect immediately (no restart). Precedence: env > settings.json > home.
+// "" = home, "/" = whole filesystem.
+function currentRoot(): string {
+  const r = process.env.COXPIT_FILES_ROOT || readSettings().filesRoot || HOME;
+  return presolve(r || HOME);
+}
+function withinRoot(full: string, root: string): boolean {
+  return root === '/' || full === root || full.startsWith(root + '/');
+}
+// Where listing/search start when no path is given (familiar), still within root.
+function startDir(root: string): string {
+  return (HOME === root || HOME.startsWith(root + '/')) ? HOME : root;
+}
+
 export type FileKind = 'md' | 'html' | 'pdf' | 'image' | 'text' | 'binary';
 
 const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp', '.ico', '.avif']);
@@ -49,19 +68,20 @@ export function mimeFor(p: string): string {
   return MIME[ext(p)] || 'application/octet-stream';
 }
 
-// Reject anything that escapes HOME (symlink-safe via realpath on the closest existing ancestor).
+// Reject anything that escapes the root (symlink-safe via realpath on the closest existing ancestor).
 async function jail(input?: string): Promise<string> {
-  const p = presolve(input && input.startsWith('/') ? input : HOME);
+  const root = currentRoot();
+  const p = presolve(input && input.startsWith('/') ? input : startDir(root));
   // realpath the deepest existing ancestor so a missing leaf (new file) still validates its dir
   let probe = p;
   for (;;) {
     try { const rp = await realpath(probe); const rest = p.slice(probe.length); const full = presolve(rp + rest);
-      if (full !== HOME && !full.startsWith(HOME + '/')) throw new Error('outside home');
+      if (!withinRoot(full, root)) throw new Error('outside root');
       return full;
     } catch (e: any) {
-      if (e && e.message === 'outside home') throw e;
+      if (e && e.message === 'outside root') throw e;
       const parent = pdirname(probe);
-      if (parent === probe) { if (p !== HOME && !p.startsWith(HOME + '/')) throw new Error('outside home'); return p; }
+      if (parent === probe) { if (!withinRoot(p, root)) throw new Error('outside root'); return p; }
       probe = parent;
     }
   }
@@ -115,9 +135,27 @@ export async function findFiles(input: string | undefined, q: string, limit = 30
   return { root, q: needle, results: out, truncated };
 }
 
+// Node fs errors are ugly ("ENOENT: no such file or directory, stat '/…'"). Map to a
+// short, human message (the viewer shows this verbatim). The path is echoed in the bar.
+function friendly(e: any): Error {
+  const code = e && e.code;
+  if (code === 'ENOENT') return new Error('파일을 찾을 수 없습니다');
+  if (code === 'EISDIR') return new Error('폴더입니다');
+  if (code === 'EACCES' || code === 'EPERM') return new Error('열 권한이 없습니다');
+  if (e && e.message === 'outside root') {
+    const root = currentRoot();
+    return new Error(root === HOME
+      ? '홈 폴더 밖이라 열 수 없습니다 (설정 → 파일 뷰어 루트에서 넓힐 수 있음)'
+      : '허용된 폴더 밖이라 열 수 없습니다 (' + root + ')');
+  }
+  return new Error(String((e && e.message) || e));
+}
+
 export async function readForView(input?: string) {
-  const path = await jail(input);
-  const st = await stat(path);
+  let path: string;
+  try { path = await jail(input); } catch (e) { throw friendly(e); }
+  let st;
+  try { st = await stat(path); } catch (e) { throw friendly(e); }
   if (st.isDirectory()) throw new Error('is a directory');
   const name = pbasename(path);
   let kind = classify(path);
@@ -140,14 +178,17 @@ export async function readForView(input?: string) {
 
 // Raw bytes with correct content-type — this is what makes PDFs/images/html render.
 export async function readRaw(input?: string) {
-  const path = await jail(input);
-  const st = await stat(path);
-  if (st.isDirectory()) throw new Error('is a directory');
+  let path: string;
+  try { path = await jail(input); } catch (e) { throw friendly(e); }
+  let st;
+  try { st = await stat(path); } catch (e) { throw friendly(e); }
+  if (st.isDirectory()) throw new Error('폴더입니다');
   return { path, name: pbasename(path), mime: mimeFor(path), buf: await readFile(path) };
 }
 
 export async function writeText(input: string, content: string) {
-  const path = await jail(input);
+  let path: string;
+  try { path = await jail(input); } catch (e) { throw friendly(e); }
   const st = await stat(path).catch(() => null);
   if (st && st.isDirectory()) throw new Error('is a directory');
   if (st && st.size > MAX_WRITE) throw new Error('file too large to edit here');

package/src/remote.ts

@@ -48,6 +48,21 @@ function jsonTargetsPort(raw: string, port: number): boolean {
   return textTargetsPort(raw, port);
 }
 
+/**
+ * Funnel is active only if `AllowFunnel` has a truthy entry AND our port is targeted.
+ * serve and funnel read the SAME ServeConfig, so `funnel status` prints the Serve
+ * config verbatim when Funnel is off — port-matching alone false-positives Funnel
+ * (issue #7). `AllowFunnel` is the only field that differs; it is absent when off.
+ */
+function funnelActiveForPort(raw: string, port: number): boolean {
+  let cfg: { AllowFunnel?: Record<string, unknown> };
+  try { cfg = JSON.parse(raw) as { AllowFunnel?: Record<string, unknown> }; } catch { throw new Error('not json'); }
+  const allow = cfg?.AllowFunnel;
+  if (!allow || typeof allow !== 'object') return false;
+  if (!Object.values(allow).some(Boolean)) return false;
+  return textTargetsPort(raw, port);   // still confirm it is *our* port
+}
+
 /** Plain-text fallback: any `:<port>` upstream mention (defensive across versions). */
 function textTargetsPort(raw: string, port: number): boolean {
   const p = String(port);
@@ -63,10 +78,12 @@ async function subStateForPort(bin: string, sub: 'serve' | 'funnel', port: numbe
   const jout = j.stdout.trim();
   if (jout) {
     try {
-      return jsonTargetsPort(jout, port);
+      return sub === 'funnel' ? funnelActiveForPort(jout, port) : jsonTargetsPort(jout, port);
     } catch { /* not json — fall through to text grep */ }
   }
   const t = await runShellOn(LOCAL, `${shq(bin)} ${sub} status 2>/dev/null || true`, 8000);
+  // `funnel status` prints "(tailnet only)" when Funnel is off — a cheap, version-tolerant guard.
+  if (sub === 'funnel' && /\(tailnet only\)/i.test(t.stdout)) return false;
   return textTargetsPort(t.stdout, port);
 }
 

package/src/server.ts

@@ -365,7 +365,7 @@ export async function buildServer(): Promise<FastifyInstance> {
     const m = authMode();
     return {
       effective: {
-        port: config.port, portStrict: config.portStrict, host: config.host,
+        port: config.port, portStrict: config.portStrict, host: config.host, filesRoot: config.filesRoot,
         webhookUrl: config.webhookUrl, publicUrl: config.publicUrl,
         agent: { provider: config.agent.provider, model: config.agent.model, count: config.agent.count, real: config.agent.real },
       },
@@ -380,11 +380,16 @@ export async function buildServer(): Promise<FastifyInstance> {
   // 부분 저장. env 로 고정된 필드는 무시(파일이 env 를 못 이김). 포트·호스트는 재시작 반영.
   app.patch('/api/settings', async (req, reply) => {
     const b = (req.body ?? {}) as {
-      port?: unknown; portStrict?: unknown; host?: unknown; webhookUrl?: unknown; publicUrl?: unknown;
+      port?: unknown; portStrict?: unknown; host?: unknown; filesRoot?: unknown; webhookUrl?: unknown; publicUrl?: unknown;
       agent?: { provider?: unknown; model?: unknown; count?: unknown; real?: unknown };
     };
     const patch: Record<string, unknown> = {};
     const L = config.envLocked;
+    if (!L.filesRoot && b.filesRoot !== undefined) {
+      const fr = String(b.filesRoot).trim();
+      if (fr !== '' && !fr.startsWith('/')) return reply.code(400).send({ error: 'file viewer root must be an absolute path, "/" for the whole filesystem, or empty for home' });
+      patch.filesRoot = fr;   // applies immediately (files.ts resolves per request)
+    }
     if (!L.port && b.port !== undefined) {
       const p = Number(b.port);
       if (!Number.isInteger(p) || p < 1 || p > 65535) return reply.code(400).send({ error: 'port must be 1–65535' });

package/src/settings.ts

@@ -9,6 +9,7 @@ export interface Settings {
   port?: number;
   portStrict?: boolean;
   host?: string;
+  filesRoot?: string;   // 파일 뷰어 루트(빈값=홈, "/"=전체). 즉시 반영(재시작 불요).
   webhookUrl?: string;
   publicUrl?: string;
   agent?: {