agentgui 1.0.1126 → 1.0.1127

package/lib/http-handler.js

@@ -1,400 +1,931 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import crypto from 'crypto';
-import * as term from './terminal.js';
-import { confineToRoots, fsAllowRoots, maskToken, SECRET_RE } from './http-routes/shared.js';
-import { handleStat, handleList, handleFile, handleDownload, handleImage } from './http-routes/reads.js';
-import { handleRename, handleMove, handleDelete, handleRestore, handleMkdir, handleUploadFile } from './http-routes/mutations.js';
-
-export { confineToRoots, fsAllowRoots, maskToken, SECRET_RE };
-
-export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, serveFile, staticDir, messageQueues, getWss, activeExecutions, getACPStatus, discoveredAgents, PKG_VERSION, RATE_LIMIT_MAX, rateLimitMap, routes, PORT }) {
-  // Warn operators when CORS_ORIGIN=* is combined with no PASSWORD: any
-  // cross-origin page can make credentialless fetch() calls to all /api/*
-  // endpoints (list, file, download, rename, delete, mkdir) and read or
-  // modify the filesystem. The existing code is structurally correct (no
-  // Access-Control-Allow-Credentials with wildcard), but the exposure is
-  // easy to miss.
-  if (process.env.CORS_ORIGIN === '*' && !process.env.PASSWORD) {
-    console.warn('[agentgui] WARNING: CORS_ORIGIN=* is set without PASSWORD. Any cross-origin page can make credentialless requests to all /api/* endpoints and read/modify the filesystem. Set PASSWORD or restrict CORS_ORIGIN to a specific origin.');
-  }
-  return async function httpHandler(req, res) {
-    // CORS: emit ACAO only when CORS_ORIGIN is explicitly set. A wildcard would
-    // let any webpage the user visits make credentialless fetches to /api/list,
-    // /api/file/*, etc. and read ~/.claude/projects content — even on a no-
-    // PASSWORD localhost deploy. Set CORS_ORIGIN=<origin> for cross-origin tools.
-    const _corsOrigin = process.env.CORS_ORIGIN;
-    if (_corsOrigin) {
-      // Never set a wildcard when credentials (cookies) may be in play — a
-      // wildcard + credentials is rejected by browsers and leaks session tokens.
-      // A specific origin allows credentialed cross-origin requests safely.
-      res.setHeader('Access-Control-Allow-Origin', _corsOrigin);
-      if (_corsOrigin !== '*') res.setHeader('Access-Control-Allow-Credentials', 'true');
-      res.setHeader('Vary', 'Origin');
-      // Allow-Methods and Allow-Headers are only meaningful on CORS preflights
-      // or CORS requests; emitting them unconditionally leaks the method surface
-      // to same-origin (and non-CORS) responses unnecessarily.
-      if (req.method === 'OPTIONS' || req.headers['origin']) {
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-      }
-    } // no ACAO header -> browsers enforce same-origin by default
-    // The password can ride in a ?token= query param (EventSource/deep-links
-    // can't set headers), so a navigation away from the app would leak it in
-    // the Referer header to the destination. Strip the referrer on every
-    // response so the credential never crosses an origin boundary that way.
-    res.setHeader('Referrer-Policy', 'no-referrer');
-    // Prevent MIME-sniffing attacks on all responses including file downloads.
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-    // Emit HSTS when the connection is known-TLS so clients pin HTTPS and
-    // refuse future downgrade attempts (protects cookie + ?token= in transit).
-    if (req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https') {
-      res.setHeader('Strict-Transport-Security', 'max-age=31536000');
-    }
-    // CSP: the markdown stack (marked/dompurify/prismjs) and the DS kit load
-    // from unpkg/jsdelivr; everything else is self. connect-src also allows
-    // self for the same-origin WS/SSE. script-src drops 'unsafe-inline' in
-    // favour of a per-request nonce threaded onto every server-injected and
-    // static inline <script> (bootstrap, hot-reload, importmap) by the asset
-    // server. style-src keeps 'unsafe-inline' because the DS injects a runtime
-    // <style> with no hook to nonce.
-    const cspNonce = crypto.randomBytes(16).toString('base64');
-    res.setHeader('Content-Security-Policy', [
-      "default-src 'self'",
-      `script-src 'self' 'nonce-${cspNonce}' https://unpkg.com https://cdn.jsdelivr.net`,
-      "style-src 'self' 'unsafe-inline' https://unpkg.com https://cdn.jsdelivr.net https://fonts.googleapis.com",
-      "img-src 'self' data: blob:",
-      "font-src 'self' data: https://unpkg.com https://cdn.jsdelivr.net https://fonts.gstatic.com",
-      "connect-src 'self' https://unpkg.com https://cdn.jsdelivr.net ws: wss:",
-      "object-src 'none'",
-      "base-uri 'self'",
-      "frame-ancestors 'self'",
-    ].join('; '));
-    if (req.method === 'OPTIONS') { res.writeHead(200); res.end(); return; }
-    if (req.headers.upgrade && req.headers.upgrade.toLowerCase() === 'websocket') return;
-
-    // Only honour X-Forwarded-For behind a trusted proxy (TRUST_PROXY=1), and
-    // then take the RIGHT-MOST hop (the one the trusted proxy itself observed,
-    // not a client-spoofed left-most value). Otherwise the socket peer is the
-    // only trustworthy source - a client can forge the header freely.
-    let clientIp;
-    if (process.env.TRUST_PROXY === '1' && req.headers['x-forwarded-for']) {
-      const hops = req.headers['x-forwarded-for'].split(',').map(s => s.trim()).filter(Boolean);
-      clientIp = hops[hops.length - 1] || req.socket.remoteAddress;
-    } else {
-      clientIp = req.socket.remoteAddress;
-    }
-    // Normalize IPv4-mapped IPv6 addresses (::ffff:1.2.3.4 -> 1.2.3.4) so the
-    // rate-limit bucket is the same regardless of how the OS presents the peer.
-    if (clientIp && clientIp.startsWith('::ffff:')) clientIp = clientIp.slice(7);
-    const hits = (rateLimitMap.get(clientIp) || 0) + 1;
-    rateLimitMap.set(clientIp, hits);
-    res.setHeader('X-RateLimit-Limit', RATE_LIMIT_MAX);
-    res.setHeader('X-RateLimit-Remaining', Math.max(0, RATE_LIMIT_MAX - hits));
-    if (hits > RATE_LIMIT_MAX) { res.writeHead(429, { 'Retry-After': '60' }); res.end('Too Many Requests'); return; }
-
-    const _pwd = process.env.PASSWORD;
-    // Optional: exempt /health from auth so container/k8s probes work
-    // without distributing the password to monitoring infra.
-    const _bareEarly = req.url.split('?')[0];
-    const _healthExempt = process.env.HEALTH_NO_AUTH === '1' && (_bareEarly === '/health' || _bareEarly === '/api/health' || _bareEarly === (BASE_URL + '/health') || _bareEarly === (BASE_URL + '/api/health'));
-    if (_pwd && !_healthExempt) {
-      const _auth = req.headers['authorization'] || '';
-      let _ok = false;
-      // Constant-time compare over fixed-width SHA-256 digests so neither the
-      // password length nor a byte-position mismatch leaks via timing.
-      const _checkToken = (tok) => {
-        try {
-          const a = crypto.createHash('sha256').update(String(tok)).digest();
-          const b = crypto.createHash('sha256').update(String(_pwd)).digest();
-          return crypto.timingSafeEqual(a, b);
-        } catch { return false; }
-      };
-      if (_auth.startsWith('Basic ')) {
-        try {
-          const _decoded = Buffer.from(_auth.slice(6), 'base64').toString('utf8');
-          const _ci = _decoded.indexOf(':');
-          if (_ci !== -1) _ok = _checkToken(_decoded.slice(_ci + 1));
-        } catch (_) {}
-      } else if (_auth.startsWith('Bearer ')) {
-        const bearerToken = _auth.slice(7);
-        // Validate Bearer token format: non-empty, no whitespace. Prevents
-        // timing-attack length inference if PASSWORD contains spaces.
-        if (/^[\S]+$/.test(bearerToken)) _ok = _checkToken(bearerToken);
-      }
-      // EventSource and same-origin links can't set headers - accept ?token= as fallback.
-      let _viaQuery = false;
-      if (!_ok) {
-        try {
-          const _qsTok = new URL(req.url, 'http://localhost').searchParams.get('token');
-          if (_qsTok) { _ok = _checkToken(_qsTok); _viaQuery = _ok; }
-        } catch (_) {}
-      }
-      // Static subresources (js/css/vendor) are requested by the BROWSER, which
-      // can attach neither a header nor a ?token= - without a cookie the SPA
-      // can never boot behind PASSWORD (index.html 200s, app.js 401s, blank
-      // page). On any successful auth, set an HttpOnly SameSite=Lax cookie the
-      // gate accepts for subsequent requests. Lax + the CSRF guard below keep
-      // cross-site mutations rejected; the value is URL-encoded (a password
-      // may carry cookie-hostile characters like commas).
-      if (!_ok) {
-        try {
-          const _ck = req.headers['cookie'] || '';
-          const _m = /(?:^|;\s*)agentgui_token=([^;]+)/.exec(_ck);
-          if (_m) _ok = _checkToken(decodeURIComponent(_m[1]));
-        } catch (_) {}
-      } else if (_viaQuery || _auth) {
-        try {
-          // Secure only over a real TLS connection (or behind an https proxy /
-          // explicit opt-in) so the localhost-http witness still gets a usable
-          // cookie. Max-Age bounds the credential's lifetime to a day.
-          const _https = req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' || process.env.COOKIE_SECURE === '1';
-          res.setHeader('Set-Cookie', 'agentgui_token=' + encodeURIComponent(_pwd) + '; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400' + (_https ? '; Secure' : ''));
-        } catch (_) {}
-      }
-      if (!_ok) {
-        // Penalize failed auth heavily in the rate bucket so a credential
-        // brute-force trips the 429 limiter long before it can guess.
-        rateLimitMap.set(clientIp, (rateLimitMap.get(clientIp) || 0) + 100);
-        res.writeHead(401, { 'WWW-Authenticate': 'Basic realm="agentgui"' }); res.end('Unauthorized'); return;
-      }
-    }
-
-    const pathOnly = req.url.split('?')[0];
-
-    // Terminal RCE guard: the terminal surface spawns an interactive shell, so
-    // it is fail-closed by default. It is reachable ONLY when PASSWORD is set
-    // AND ENABLE_TERMINAL=1 is explicitly opted in. (Under the localhost-PASSWORD
-    // witness ENABLE_TERMINAL is unset, so the terminal is correctly disabled -
-    // it is not part of the witness.)
-    if (pathOnly.startsWith('/api/terminal/') || pathOnly.startsWith(BASE_URL + '/api/terminal/')) {
-      if (!process.env.PASSWORD || process.env.ENABLE_TERMINAL !== '1') {
-        sendJSON(req, res, 403, { error: 'terminal disabled (requires PASSWORD and ENABLE_TERMINAL=1)' });
-        return;
-      }
-    }
-
-    // CSRF guard on every state-changing method. Without PASSWORD the server
-    // is open and advertises a wildcard ACAO, so a cross-site page could POST
-    // a form at the mutation routes (rename/delete/mkdir/upload) on localhost.
-    // A simple cross-site form cannot set Sec-Fetch-Site:same-origin, send
-    // application/json, or attach custom headers - so: accept when the
-    // browser says same-origin/none (direct nav, same-origin fetch), when the
-    // body is declared JSON, or when an Authorization header rode along (a
-    // credentialed programmatic client). Reject the rest with 403.
-    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'DELETE') {
-      const sfs = req.headers['sec-fetch-site'];
-      const ct = (req.headers['content-type'] || '').toLowerCase();
-      // A MISSING Sec-Fetch-Site header must NOT be treated as same-site -
-      // older browsers/non-browser clients omitting it would otherwise pass
-      // unconditionally regardless of true origin. Only an explicit
-      // same-origin/none value counts; a present-but-absent header falls
-      // through to the Origin-host check below.
-      const sameSite = sfs === 'same-origin' || sfs === 'none';
-      // Only application/json counts as a non-cross-site body now: a simple
-      // cross-site <form> can send only urlencoded/multipart/text-plain, and
-      // octet-stream / empty CT were too broad an escape (a no-CORS fetch can
-      // send octet-stream). The binary upload PUT still rides the same-origin
-      // SPA fetch (Sec-Fetch-Site: same-origin), so it passes via sameSite.
-      const jsonBody = ct.startsWith('application/json');
-      const authed = !!req.headers['authorization'];
-      // If an Origin header is present, its host MUST match the Host header -
-      // a cross-origin page's Origin will not, regardless of Sec-Fetch-Site.
-      let originOk = true;
-      const origin = req.headers['origin'];
-      if (origin) {
-        try { originOk = new URL(origin).host === req.headers['host']; }
-        catch { originOk = false; }
-      }
-      if (!originOk || (!sameSite && !jsonBody && !authed)) {
-        res.writeHead(403, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'cross-site request rejected' }));
-        return;
-      }
-    }
-
-    if (pathOnly.startsWith(BASE_URL + '/api/upload/') || pathOnly.startsWith(BASE_URL + '/files/') || pathOnly.startsWith('/v1/history') || (BASE_URL && pathOnly.startsWith(BASE_URL + '/v1/history'))) return expressApp(req, res);
-
-    if (req.url === '/favicon.ico' || req.url === BASE_URL + '/favicon.ico') {
-      const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" rx="20" fill="#3b82f6"/><text x="50" y="68" font-size="50" font-family="sans-serif" font-weight="bold" fill="white" text-anchor="middle">G</text></svg>';
-      res.writeHead(200, { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'public, max-age=86400' });
-      res.end(svg); return;
-    }
-
-    // serve index.html at root directly (no redirect)
-
-    let routePath = req.url;
-    const _bareUrl = req.url.split('?')[0];
-    if (_bareUrl.startsWith(BASE_URL + '/')) { routePath = req.url.slice(BASE_URL.length); }
-    else if (_bareUrl === BASE_URL) { routePath = '/'; }
-    else if (_bareUrl.startsWith('/api/') || _bareUrl.startsWith('/js/') || _bareUrl.startsWith('/css/') ||
-             _bareUrl.startsWith('/vendor/') || _bareUrl.startsWith('/sync') || _bareUrl === '/' ||
-             _bareUrl === '/health' || _bareUrl.startsWith('/v1/') ||
-             _bareUrl.startsWith('/api/terminal/') ||
-             _bareUrl.startsWith('/conversations/')) { routePath = req.url; }
-    else { res.writeHead(404); res.end('Not found'); return; }
-
-    routePath = routePath || '/';
-
-    try {
-      const pathOnly = routePath.split('?')[0];
-
-      if ((pathOnly === '/api/health' || pathOnly === '/health') && req.method === 'GET') {
-        let dbStatus = { ok: true };
-        try { queries._db.prepare('SELECT 1').get(); } catch (e) { dbStatus = { ok: false, error: e.message }; }
-        const queueSizes = {};
-        for (const [k, v] of messageQueues) queueSizes[k] = v.length;
-        const _body = {
-          status: 'ok', version: PKG_VERSION, uptime: process.uptime(), agents: discoveredAgents.length,
-          activeExecutions: activeExecutions.size, wsClients: getWss()?.clients?.size ?? 0,
-          acp: getACPStatus(), db: dbStatus, queueSizes,
-          // Surfaces the console-only CORS_ORIGIN=*+no-PASSWORD warning (above)
-          // as a fact the GUI settings panel can render a persistent banner
-          // from - an operator not tailing logs otherwise never sees the risk.
-          corsWildcardOpen: process.env.CORS_ORIGIN === '*' && !process.env.PASSWORD,
-        };
-        // Host-internal facts (memory, filesystem paths) are exposed only to an
-        // authenticated caller, never on the unauthenticated health-probe bypass.
-        if (!_healthExempt) {
-          _body.memory = process.memoryUsage();
-          _body.projectsDir = process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
-          _body.allowRoots = fsAllowRoots();
-        }
-        sendJSON(req, res, 200, _body);
-        return;
-      }
-
-      // Existence/shape probe for a proposed chat working directory - see
-      // lib/http-routes/reads.js for the confinement contract.
-      if (routePath.startsWith('/api/stat') && req.method === 'GET') {
-        handleStat(req, res, routePath, sendJSON);
-        return;
-      }
-
-      // Terminal sessions - gated by the Basic-auth check at the top of this handler.
-      // Never expose these routes without PASSWORD set.
-      if (pathOnly === '/api/terminal/sessions' && req.method === 'GET') {
-        sendJSON(req, res, 200, term.listSessions()); return;
-      }
-      if (pathOnly === '/api/terminal/sessions' && req.method === 'POST') {
-        let body = ''; for await (const c of req) body += c;
-        let p = {}; try { p = body ? JSON.parse(body) : {}; } catch {}
-        // Never honour a client-supplied shell or env - that would be a direct
-        // command/arg injection into the spawned process. Only geometry + cwd.
-        // Confine cwd to allowed roots; fall back to STARTUP_CWD on failure.
-        let termCwd = process.env.STARTUP_CWD || process.cwd();
-        if (p.cwd) {
-          const cwdConf = confineToRoots(p.cwd, fsAllowRoots());
-          if (cwdConf.ok) termCwd = cwdConf.realPath;
-        }
-        const s = term.createSession({ cwd: termCwd, cols: p.cols, rows: p.rows });
-        sendJSON(req, res, 200, { sid: s.sid, kind: s.kind, shell: s.shell, cwd: s.cwd, cols: s.cols, rows: s.rows, pid: s.proc.pid });
-        return;
-      }
-      const termMatch = pathOnly.match(/^\/api\/terminal\/sessions\/([0-9a-f]+)$/);
-      if (termMatch && req.method === 'GET') {
-        const s = term.getSession(termMatch[1]);
-        if (!s) { sendJSON(req, res, 404, { error: 'session not found' }); return; }
-        sendJSON(req, res, 200, { sid: s.sid, kind: s.kind, shell: s.shell, cwd: s.cwd, cols: s.cols, rows: s.rows, pid: s.proc.pid, clients: s.clients.size });
-        return;
-      }
-      if (termMatch && req.method === 'DELETE') {
-        const ok = term.closeSession(termMatch[1]);
-        sendJSON(req, res, ok ? 200 : 404, { ok }); return;
-      }
-
-      // Legacy REST handlers removed. History served by ccsniff at /v1/history/*.
-      for (const key of Object.keys(routes)) {
-        try {
-          const h = routes[key]?._match?.(req.method, pathOnly);
-          if (h) { await h(req, res); return; }
-        } catch (_) {}
-      }
-      // Directory listing for the Files / folder-browser view - see
-      // lib/http-routes/reads.js for the confinement contract.
-      if (routePath.startsWith('/api/list')) {
-        handleList(req, res, routePath, sendJSON);
-        return;
-      }
-
-      // Raw file bytes for the Files preview pane - see lib/http-routes/reads.js.
-      if (routePath.startsWith('/api/file/') || routePath.startsWith('/api/file?')) {
-        handleFile(req, res, routePath);
-        return;
-      }
-
-      // Confined raw-bytes download - see lib/http-routes/reads.js.
-      if (routePath.startsWith('/api/download/') || routePath.startsWith('/api/download?')) {
-        handleDownload(req, res, routePath);
-        return;
-      }
-
-      // --- File mutations ----------------------------------------------------
-      // The Files surface is a real manager (fsbrowse-grade): rename, delete,
-      // mkdir, upload. See lib/http-routes/mutations.js for the shared
-      // confinement/sanitization contract every route below follows.
-
-      // POST /api/rename {path, newName} -> {ok, path}
-      if (routePath.split('?')[0] === '/api/rename' && req.method === 'POST') {
-        await handleRename(req, res, sendJSON);
-        return;
-      }
-
-      // POST /api/move {path, destDir, overwrite?} -> {ok, path}
-      if (routePath.split('?')[0] === '/api/move' && req.method === 'POST') {
-        await handleMove(req, res, sendJSON);
-        return;
-      }
-
-      // POST /api/delete {path, recursive?} -> {ok}
-      if (routePath.split('?')[0] === '/api/delete' && req.method === 'POST') {
-        await handleDelete(req, res, sendJSON);
-        return;
-      }
-
-      // POST /api/restore {trashId} -> {ok, path}
-      if (routePath.split('?')[0] === '/api/restore' && req.method === 'POST') {
-        await handleRestore(req, res, sendJSON);
-        return;
-      }
-
-      // POST /api/mkdir {dir, name} -> {ok, path}
-      if (routePath.split('?')[0] === '/api/mkdir' && req.method === 'POST') {
-        await handleMkdir(req, res, sendJSON);
-        return;
-      }
-
-      // PUT /api/upload-file?dir=<enc>&name=<enc> with raw file bytes as the body
-      if (routePath.split('?')[0] === '/api/upload-file' && req.method === 'PUT') {
-        await handleUploadFile(req, res, sendJSON);
-        return;
-      }
-
-      // Confined image bytes - see lib/http-routes/reads.js.
-      if (routePath.startsWith('/api/image/') || routePath.startsWith('/api/image?')) {
-        handleImage(req, res, routePath, sendJSON);
-        return;
-      }
-
-      if (pathOnly.match(/^\/conversations\/[^\/]+$/)) { serveFile(path.join(staticDir, 'index.html'), res, req, cspNonce); return; }
-
-      const routePathBare = routePath.split('?')[0];
-      let filePath = routePathBare === '/' ? '/index.html' : routePathBare;
-      filePath = path.join(staticDir, filePath);
-      const normalizedPath = path.normalize(filePath);
-      if (!normalizedPath.startsWith(staticDir)) { res.writeHead(403); res.end('Forbidden'); return; }
-
-      fs.stat(filePath, (err, stats) => {
-        if (err) { res.writeHead(404); res.end('Not found'); return; }
-        if (stats.isDirectory()) {
-          filePath = path.join(filePath, 'index.html');
-          fs.stat(filePath, (err2) => { if (err2) { res.writeHead(404); res.end('Not found'); return; } serveFile(filePath, res, req, cspNonce); });
-        } else { serveFile(filePath, res, req, cspNonce); }
-      });
-    } catch (e) {
-      console.error('Server error:', maskToken(e.message), e.stack, '| path:', maskToken(req.url.split('?')[0]));
-      sendJSON(req, res, 500, { error: 'internal server error' });
-    }
-  };
-}
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import * as term from './terminal.js';
+
+// Confine a requested filesystem path to an allowlist of roots. Two layers:
+//   1. normalize + resolved-prefix check on the LEXICAL path (blocks `../`
+//      traversal, which path.normalize collapses so a literal `..` test is a
+//      no-op);
+//   2. fs.realpathSync + the SAME prefix check on the REAL path, so a symlink
+//      that lives inside an allowed root but points outside it cannot escape
+//      (the lexical path passes layer 1, the resolved target fails layer 2).
+// Returns { ok, realPath, reason }. realPath is the symlink-resolved absolute
+// path to stat/read; callers use it, never the raw input. A non-existent path
+// has no realpath yet, so it fails closed with reason 'not found'.
+// Mask ?token=VALUE in a URL string before logging so credentials never
+// appear in server logs or error messages.
+export function maskToken(url) {
+  if (typeof url !== 'string') return url;
+  return url.replace(/([?&]token=)[^&]*/gi, '$1***');
+}
+
+// Module-level platform constant — never changes at runtime.
+const IS_WINDOWS = os.platform() === 'win32';
+
+export function confineToRoots(inputPath, allowRoots) {
+  const norms = allowRoots.map(r => path.normalize(r));
+  const expanded = inputPath && inputPath.startsWith('~') ? inputPath.replace('~', os.homedir()) : inputPath;
+  const normalizedPath = path.normalize(expanded || '');
+  const isAbsolute = IS_WINDOWS ? /^[A-Za-z]:[\\/]/.test(normalizedPath) : normalizedPath.startsWith('/');
+  const within = (p) => {
+    const np = IS_WINDOWS ? p.toLowerCase() : p;
+    return norms.some(root => {
+      const r = IS_WINDOWS ? root.toLowerCase() : root;
+      return np === r || np.startsWith(r + path.sep);
+    });
+  };
+  if (!isAbsolute || !within(normalizedPath)) return { ok: false, reason: 'path outside allowed roots' };
+  // realpath the target and re-confine, defeating symlink escape (TOCTOU/link
+  // traversal). If realpath throws (missing path / broken link) fail closed.
+  let realPath;
+  try { realPath = fs.realpathSync(normalizedPath); }
+  catch (e) { return { ok: false, reason: e && e.code === 'ENOENT' ? 'not found' : 'cannot resolve path', code: e && e.code }; }
+  if (!within(realPath)) return { ok: false, reason: 'symlink target outside allowed roots' };
+  return { ok: true, realPath };
+}
+
+// Secret-bearing basenames that must never be readable through ANY confined
+// raw-bytes route (preview or download), even when they sit inside an allowed
+// root: dotfiles, env/key/cert material, and credential stores. One const so
+// /api/file and /api/download can never drift apart.
+export const SECRET_RE = /(^\.|\.(env|pem|key|crt|p12|pfx)$|secret|credential|\.npmrc$|\.netrc$)/i;
+
+// The allowlist the Files surface operates within: server cwd + Claude
+// projects dir, widened via FS_ROOTS (path-separated). One construction so
+// /api/list,file,download and the mutation routes can never drift apart.
+export function fsAllowRoots() {
+  const roots = [
+    process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+  ];
+  // The server cwd is only exposed when PASSWORD is set (the witnessed
+  // localhost-PASSWORD deploy lists the repo tree) or FS_ALLOW_CWD=1 is opted
+  // in. An open no-PASSWORD deploy must NOT expose the whole server tree.
+  if (process.env.PASSWORD || process.env.FS_ALLOW_CWD === '1') {
+    roots.push(process.env.STARTUP_CWD || process.cwd());
+  }
+  if (process.env.FS_ROOTS) roots.push(...process.env.FS_ROOTS.split(path.delimiter));
+  return roots.map(r => path.normalize(r));
+}
+
+// A new file/dir name must be a single path component: no separators, no
+// traversal, no NTFS alternate-data-stream colon, no reserved Windows device
+// names, no trailing dot/space (Windows silently strips them, aliasing two
+// names onto one entry). Returns the trimmed name or null when inadmissible.
+function sanitizeEntryName(name) {
+  if (typeof name !== 'string') return null;
+  const n = name.trim();
+  if (!n || n.length > 255) return null;
+  if (/[\\/:*?"<>|\x00-\x1f]/.test(n)) return null;
+  if (n === '.' || n === '..') return null;
+  if (/[. ]$/.test(n)) return null;
+  if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(n)) return null;
+  return n;
+}
+
+// Every confined filesystem route accepts its target path via a `?path=`/
+// `?dir=` query param, preferred over a path SEGMENT. A reverse proxy's
+// proxy_pass URI normalization can decode-then-reencode the request path,
+// collapsing an encoded %2F segment slash back into a literal '/' before
+// forwarding - the app then sees extra path segments instead of one opaque
+// one, strips what it thinks is a leading '/', and silently turns an absolute
+// path into a relative one that fails confinement even for genuinely
+// accessible directories/files. A query param is untouched by that
+// normalization on any proxy in front of this app. `legacyPrefix` is the old
+// `/api/xxx/<path>` route prefix, still accepted for any caller not yet
+// updated to the query-param form.
+function resolveConfinedPath(req, routePath, queryKey, legacyPrefix) {
+  const url = new URL(req.url, 'http://x');
+  const qVal = url.searchParams.get(queryKey);
+  if (qVal != null) return qVal;
+  const raw = routePath.split('?')[0].slice(legacyPrefix.length).replace(/^\//, '');
+  return raw ? decodeURIComponent(raw) : '';
+}
+
+// Map a Node.js filesystem error code to a safe human-readable string that
+// does not disclose host paths or internal stack context. Used everywhere an
+// err.message would otherwise be returned to the client.
+function safeErrMsg(err) {
+  if (!err) return 'unknown error';
+  switch (err.code) {
+    case 'ENOENT': return 'file not found';
+    case 'EACCES': return 'permission denied';
+    case 'EPERM':  return 'operation not permitted';
+    case 'EISDIR': return 'path is a directory';
+    case 'ENOTDIR': return 'path is not a directory';
+    case 'ENOTEMPTY': return 'directory is not empty';
+    case 'EEXIST': return 'file already exists';
+    case 'EXDEV': return 'cannot move across drives';
+    case 'EMFILE': return 'too many open files';
+    case 'ENOSPC': return 'no space left on device';
+    default: return 'operation failed';
+  }
+}
+
+// Read a request body with a hard size cap; resolves a Buffer or rejects with
+// .code='TOO_LARGE' so the caller can answer 413 without buffering the rest.
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let total = 0;
+    req.on('data', (c) => {
+      total += c.length;
+      if (total > maxBytes) { const e = new Error('body too large'); e.code = 'TOO_LARGE'; req.destroy(); reject(e); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+// True when the resolved path IS one of the allowlist roots - the roots
+// themselves are never mutation targets (rename/delete of a root would orphan
+// the whole surface).
+function isAllowRoot(realPath, allowRoots) {
+  const p = IS_WINDOWS ? realPath.toLowerCase() : realPath;
+  return allowRoots.some(r => (IS_WINDOWS ? r.toLowerCase() : r) === p);
+}
+
+// --- Soft-delete (trash) -----------------------------------------------
+// /api/delete moves entries into <root>/.agentgui-trash/<trashId>__<name>
+// instead of unlinking, giving a short undo window. In-memory index only
+// (server restart forfeits the undo window - acceptable since the retention
+// window itself is short and this is a convenience net on top of, not a
+// replacement for, the pre-delete ConfirmDialog). Purged after
+// TRASH_RETENTION_MS or when trashIndex grows past TRASH_MAX_ENTRIES
+// (oldest-first), so a long-running server's trash dir can't grow unbounded.
+const TRASH_DIR_NAME = '.agentgui-trash';
+const TRASH_RETENTION_MS = parseInt(process.env.AGENTGUI_TRASH_RETENTION_MS || '', 10) || 10 * 60 * 1000;
+const TRASH_MAX_ENTRIES = 200;
+const trashIndex = new Map(); // trashId -> { trashPath, originalPath, root, deletedAt }
+
+function purgeExpiredTrash() {
+  const now = Date.now();
+  for (const [id, info] of trashIndex) {
+    if (now - info.deletedAt > TRASH_RETENTION_MS) {
+      try { fs.rmSync(info.trashPath, { recursive: true, force: true }); } catch { /* already gone */ }
+      trashIndex.delete(id);
+    }
+  }
+  if (trashIndex.size > TRASH_MAX_ENTRIES) {
+    const sorted = [...trashIndex.entries()].sort((a, b) => a[1].deletedAt - b[1].deletedAt);
+    for (const [id, info] of sorted.slice(0, trashIndex.size - TRASH_MAX_ENTRIES)) {
+      try { fs.rmSync(info.trashPath, { recursive: true, force: true }); } catch {}
+      trashIndex.delete(id);
+    }
+  }
+}
+
+// Which allowed root a confined realPath lives under - the trash dir sits
+// alongside it (still inside the SAME root, so confineToRoots covers the
+// trash path too - no new unconfined surface).
+function rootFor(realPath, allowRoots) {
+  const p = IS_WINDOWS ? realPath.toLowerCase() : realPath;
+  return allowRoots.find(r => { const rr = IS_WINDOWS ? r.toLowerCase() : r; return p === rr || p.startsWith(rr + path.sep); });
+}
+
+function moveToTrash(realPath, allowRoots) {
+  purgeExpiredTrash();
+  const root = rootFor(realPath, allowRoots);
+  if (!root) { const e = new Error('not confined to an allowed root'); e.code = 'EACCES'; throw e; }
+  const trashDir = path.join(root, TRASH_DIR_NAME);
+  fs.mkdirSync(trashDir, { recursive: true });
+  const trashId = crypto.randomBytes(8).toString('hex');
+  const base = path.basename(realPath);
+  const trashPath = path.join(trashDir, trashId + '__' + base);
+  fs.renameSync(realPath, trashPath);
+  trashIndex.set(trashId, { trashPath, originalPath: realPath, root, deletedAt: Date.now() });
+  return { trashId };
+}
+
+function restoreFromTrash(trashId, allowRoots) {
+  const info = trashIndex.get(trashId);
+  if (!info) { const e = new Error('nothing to restore - the undo window has expired or this was already restored'); e.code = 'NOT_FOUND'; throw e; }
+  // Re-confine the ORIGINAL path at restore time (not trust the cached one
+  // blindly) - the allowlist itself doesn't change at runtime, but this keeps
+  // restore honoring the exact same confinement contract every other route does.
+  const conf = confineToRoots(info.originalPath, allowRoots);
+  if (!conf.ok && conf.reason !== 'not found') { const e = new Error('restore target is no longer inside an accessible folder'); e.code = 'CONFLICT'; throw e; }
+  if (fs.existsSync(info.originalPath)) { const e = new Error('a file already exists at the original location'); e.code = 'CONFLICT'; throw e; }
+  fs.mkdirSync(path.dirname(info.originalPath), { recursive: true });
+  fs.renameSync(info.trashPath, info.originalPath);
+  trashIndex.delete(trashId);
+  return { path: info.originalPath };
+}
+
+export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, serveFile, staticDir, messageQueues, getWss, activeExecutions, getACPStatus, discoveredAgents, PKG_VERSION, RATE_LIMIT_MAX, rateLimitMap, routes, PORT }) {
+  // Warn operators when CORS_ORIGIN=* is combined with no PASSWORD: any
+  // cross-origin page can make credentialless fetch() calls to all /api/*
+  // endpoints (list, file, download, rename, delete, mkdir) and read or
+  // modify the filesystem. The existing code is structurally correct (no
+  // Access-Control-Allow-Credentials with wildcard), but the exposure is
+  // easy to miss.
+  if (process.env.CORS_ORIGIN === '*' && !process.env.PASSWORD) {
+    console.warn('[agentgui] WARNING: CORS_ORIGIN=* is set without PASSWORD. Any cross-origin page can make credentialless requests to all /api/* endpoints and read/modify the filesystem. Set PASSWORD or restrict CORS_ORIGIN to a specific origin.');
+  }
+  return async function httpHandler(req, res) {
+    // CORS: emit ACAO only when CORS_ORIGIN is explicitly set. A wildcard would
+    // let any webpage the user visits make credentialless fetches to /api/list,
+    // /api/file/*, etc. and read ~/.claude/projects content — even on a no-
+    // PASSWORD localhost deploy. Set CORS_ORIGIN=<origin> for cross-origin tools.
+    const _corsOrigin = process.env.CORS_ORIGIN;
+    if (_corsOrigin) {
+      // Never set a wildcard when credentials (cookies) may be in play — a
+      // wildcard + credentials is rejected by browsers and leaks session tokens.
+      // A specific origin allows credentialed cross-origin requests safely.
+      res.setHeader('Access-Control-Allow-Origin', _corsOrigin);
+      if (_corsOrigin !== '*') res.setHeader('Access-Control-Allow-Credentials', 'true');
+      res.setHeader('Vary', 'Origin');
+      // Allow-Methods and Allow-Headers are only meaningful on CORS preflights
+      // or CORS requests; emitting them unconditionally leaks the method surface
+      // to same-origin (and non-CORS) responses unnecessarily.
+      if (req.method === 'OPTIONS' || req.headers['origin']) {
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+      }
+    } // no ACAO header -> browsers enforce same-origin by default
+    // The password can ride in a ?token= query param (EventSource/deep-links
+    // can't set headers), so a navigation away from the app would leak it in
+    // the Referer header to the destination. Strip the referrer on every
+    // response so the credential never crosses an origin boundary that way.
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    // Prevent MIME-sniffing attacks on all responses including file downloads.
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    // Emit HSTS when the connection is known-TLS so clients pin HTTPS and
+    // refuse future downgrade attempts (protects cookie + ?token= in transit).
+    if (req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https') {
+      res.setHeader('Strict-Transport-Security', 'max-age=31536000');
+    }
+    // CSP: the markdown stack (marked/dompurify/prismjs) and the DS kit load
+    // from unpkg/jsdelivr; everything else is self. connect-src also allows
+    // self for the same-origin WS/SSE. script-src drops 'unsafe-inline' in
+    // favour of a per-request nonce threaded onto every server-injected and
+    // static inline <script> (bootstrap, hot-reload, importmap) by the asset
+    // server. style-src keeps 'unsafe-inline' because the DS injects a runtime
+    // <style> with no hook to nonce.
+    const cspNonce = crypto.randomBytes(16).toString('base64');
+    res.setHeader('Content-Security-Policy', [
+      "default-src 'self'",
+      `script-src 'self' 'nonce-${cspNonce}' https://unpkg.com https://cdn.jsdelivr.net`,
+      "style-src 'self' 'unsafe-inline' https://unpkg.com https://cdn.jsdelivr.net https://fonts.googleapis.com",
+      "img-src 'self' data: blob:",
+      "font-src 'self' data: https://unpkg.com https://cdn.jsdelivr.net https://fonts.gstatic.com",
+      "connect-src 'self' https://unpkg.com https://cdn.jsdelivr.net ws: wss:",
+      "object-src 'none'",
+      "base-uri 'self'",
+      "frame-ancestors 'self'",
+    ].join('; '));
+    if (req.method === 'OPTIONS') { res.writeHead(200); res.end(); return; }
+    if (req.headers.upgrade && req.headers.upgrade.toLowerCase() === 'websocket') return;
+
+    // Only honour X-Forwarded-For behind a trusted proxy (TRUST_PROXY=1), and
+    // then take the RIGHT-MOST hop (the one the trusted proxy itself observed,
+    // not a client-spoofed left-most value). Otherwise the socket peer is the
+    // only trustworthy source - a client can forge the header freely.
+    let clientIp;
+    if (process.env.TRUST_PROXY === '1' && req.headers['x-forwarded-for']) {
+      const hops = req.headers['x-forwarded-for'].split(',').map(s => s.trim()).filter(Boolean);
+      clientIp = hops[hops.length - 1] || req.socket.remoteAddress;
+    } else {
+      clientIp = req.socket.remoteAddress;
+    }
+    // Normalize IPv4-mapped IPv6 addresses (::ffff:1.2.3.4 -> 1.2.3.4) so the
+    // rate-limit bucket is the same regardless of how the OS presents the peer.
+    if (clientIp && clientIp.startsWith('::ffff:')) clientIp = clientIp.slice(7);
+    const hits = (rateLimitMap.get(clientIp) || 0) + 1;
+    rateLimitMap.set(clientIp, hits);
+    res.setHeader('X-RateLimit-Limit', RATE_LIMIT_MAX);
+    res.setHeader('X-RateLimit-Remaining', Math.max(0, RATE_LIMIT_MAX - hits));
+    if (hits > RATE_LIMIT_MAX) { res.writeHead(429, { 'Retry-After': '60' }); res.end('Too Many Requests'); return; }
+
+    const _pwd = process.env.PASSWORD;
+    // Optional: exempt /health from auth so container/k8s probes work
+    // without distributing the password to monitoring infra.
+    const _bareEarly = req.url.split('?')[0];
+    const _healthExempt = process.env.HEALTH_NO_AUTH === '1' && (_bareEarly === '/health' || _bareEarly === '/api/health' || _bareEarly === (BASE_URL + '/health') || _bareEarly === (BASE_URL + '/api/health'));
+    if (_pwd && !_healthExempt) {
+      const _auth = req.headers['authorization'] || '';
+      let _ok = false;
+      // Constant-time compare over fixed-width SHA-256 digests so neither the
+      // password length nor a byte-position mismatch leaks via timing.
+      const _checkToken = (tok) => {
+        try {
+          const a = crypto.createHash('sha256').update(String(tok)).digest();
+          const b = crypto.createHash('sha256').update(String(_pwd)).digest();
+          return crypto.timingSafeEqual(a, b);
+        } catch { return false; }
+      };
+      if (_auth.startsWith('Basic ')) {
+        try {
+          const _decoded = Buffer.from(_auth.slice(6), 'base64').toString('utf8');
+          const _ci = _decoded.indexOf(':');
+          if (_ci !== -1) _ok = _checkToken(_decoded.slice(_ci + 1));
+        } catch (_) {}
+      } else if (_auth.startsWith('Bearer ')) {
+        const bearerToken = _auth.slice(7);
+        // Validate Bearer token format: non-empty, no whitespace. Prevents
+        // timing-attack length inference if PASSWORD contains spaces.
+        if (/^[\S]+$/.test(bearerToken)) _ok = _checkToken(bearerToken);
+      }
+      // EventSource and same-origin links can't set headers - accept ?token= as fallback.
+      let _viaQuery = false;
+      if (!_ok) {
+        try {
+          const _qsTok = new URL(req.url, 'http://localhost').searchParams.get('token');
+          if (_qsTok) { _ok = _checkToken(_qsTok); _viaQuery = _ok; }
+        } catch (_) {}
+      }
+      // Static subresources (js/css/vendor) are requested by the BROWSER, which
+      // can attach neither a header nor a ?token= - without a cookie the SPA
+      // can never boot behind PASSWORD (index.html 200s, app.js 401s, blank
+      // page). On any successful auth, set an HttpOnly SameSite=Lax cookie the
+      // gate accepts for subsequent requests. Lax + the CSRF guard below keep
+      // cross-site mutations rejected; the value is URL-encoded (a password
+      // may carry cookie-hostile characters like commas).
+      if (!_ok) {
+        try {
+          const _ck = req.headers['cookie'] || '';
+          const _m = /(?:^|;\s*)agentgui_token=([^;]+)/.exec(_ck);
+          if (_m) _ok = _checkToken(decodeURIComponent(_m[1]));
+        } catch (_) {}
+      } else if (_viaQuery || _auth) {
+        try {
+          // Secure only over a real TLS connection (or behind an https proxy /
+          // explicit opt-in) so the localhost-http witness still gets a usable
+          // cookie. Max-Age bounds the credential's lifetime to a day.
+          const _https = req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' || process.env.COOKIE_SECURE === '1';
+          res.setHeader('Set-Cookie', 'agentgui_token=' + encodeURIComponent(_pwd) + '; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400' + (_https ? '; Secure' : ''));
+        } catch (_) {}
+      }
+      if (!_ok) {
+        // Penalize failed auth heavily in the rate bucket so a credential
+        // brute-force trips the 429 limiter long before it can guess.
+        rateLimitMap.set(clientIp, (rateLimitMap.get(clientIp) || 0) + 100);
+        res.writeHead(401, { 'WWW-Authenticate': 'Basic realm="agentgui"' }); res.end('Unauthorized'); return;
+      }
+    }
+
+    const pathOnly = req.url.split('?')[0];
+
+    // Terminal RCE guard: the terminal surface spawns an interactive shell, so
+    // it is fail-closed by default. It is reachable ONLY when PASSWORD is set
+    // AND ENABLE_TERMINAL=1 is explicitly opted in. (Under the localhost-PASSWORD
+    // witness ENABLE_TERMINAL is unset, so the terminal is correctly disabled -
+    // it is not part of the witness.)
+    if (pathOnly.startsWith('/api/terminal/') || pathOnly.startsWith(BASE_URL + '/api/terminal/')) {
+      if (!process.env.PASSWORD || process.env.ENABLE_TERMINAL !== '1') {
+        sendJSON(req, res, 403, { error: 'terminal disabled (requires PASSWORD and ENABLE_TERMINAL=1)' });
+        return;
+      }
+    }
+
+    // CSRF guard on every state-changing method. Without PASSWORD the server
+    // is open and advertises a wildcard ACAO, so a cross-site page could POST
+    // a form at the mutation routes (rename/delete/mkdir/upload) on localhost.
+    // A simple cross-site form cannot set Sec-Fetch-Site:same-origin, send
+    // application/json, or attach custom headers - so: accept when the
+    // browser says same-origin/none (direct nav, same-origin fetch), when the
+    // body is declared JSON, or when an Authorization header rode along (a
+    // credentialed programmatic client). Reject the rest with 403.
+    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'DELETE') {
+      const sfs = req.headers['sec-fetch-site'];
+      const ct = (req.headers['content-type'] || '').toLowerCase();
+      const sameSite = !sfs || sfs === 'same-origin' || sfs === 'none';
+      // Only application/json counts as a non-cross-site body now: a simple
+      // cross-site <form> can send only urlencoded/multipart/text-plain, and
+      // octet-stream / empty CT were too broad an escape (a no-CORS fetch can
+      // send octet-stream). The binary upload PUT still rides the same-origin
+      // SPA fetch (Sec-Fetch-Site: same-origin), so it passes via sameSite.
+      const jsonBody = ct.startsWith('application/json');
+      const authed = !!req.headers['authorization'];
+      // If an Origin header is present, its host MUST match the Host header -
+      // a cross-origin page's Origin will not, regardless of Sec-Fetch-Site.
+      let originOk = true;
+      const origin = req.headers['origin'];
+      if (origin) {
+        try { originOk = new URL(origin).host === req.headers['host']; }
+        catch { originOk = false; }
+      }
+      if (!originOk || (!sameSite && !jsonBody && !authed)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'cross-site request rejected' }));
+        return;
+      }
+    }
+
+    if (pathOnly.startsWith(BASE_URL + '/api/upload/') || pathOnly.startsWith(BASE_URL + '/files/') || pathOnly.startsWith('/v1/history') || (BASE_URL && pathOnly.startsWith(BASE_URL + '/v1/history'))) return expressApp(req, res);
+
+    if (req.url === '/favicon.ico' || req.url === BASE_URL + '/favicon.ico') {
+      const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" rx="20" fill="#3b82f6"/><text x="50" y="68" font-size="50" font-family="sans-serif" font-weight="bold" fill="white" text-anchor="middle">G</text></svg>';
+      res.writeHead(200, { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'public, max-age=86400' });
+      res.end(svg); return;
+    }
+
+    // serve index.html at root directly (no redirect)
+
+    let routePath = req.url;
+    const _bareUrl = req.url.split('?')[0];
+    if (_bareUrl.startsWith(BASE_URL + '/')) { routePath = req.url.slice(BASE_URL.length); }
+    else if (_bareUrl === BASE_URL) { routePath = '/'; }
+    else if (_bareUrl.startsWith('/api/') || _bareUrl.startsWith('/js/') || _bareUrl.startsWith('/css/') ||
+             _bareUrl.startsWith('/vendor/') || _bareUrl.startsWith('/sync') || _bareUrl === '/' ||
+             _bareUrl === '/health' || _bareUrl.startsWith('/v1/') ||
+             _bareUrl.startsWith('/api/terminal/') ||
+             _bareUrl.startsWith('/conversations/')) { routePath = req.url; }
+    else { res.writeHead(404); res.end('Not found'); return; }
+
+    routePath = routePath || '/';
+
+    try {
+      const pathOnly = routePath.split('?')[0];
+
+      if ((pathOnly === '/api/health' || pathOnly === '/health') && req.method === 'GET') {
+        let dbStatus = { ok: true };
+        try { queries._db.prepare('SELECT 1').get(); } catch (e) { dbStatus = { ok: false, error: e.message }; }
+        const queueSizes = {};
+        for (const [k, v] of messageQueues) queueSizes[k] = v.length;
+        const _body = {
+          status: 'ok', version: PKG_VERSION, uptime: process.uptime(), agents: discoveredAgents.length,
+          activeExecutions: activeExecutions.size, wsClients: getWss()?.clients?.size ?? 0,
+          acp: getACPStatus(), db: dbStatus, queueSizes,
+          // Surfaces the console-only CORS_ORIGIN=*+no-PASSWORD warning (above)
+          // as a fact the GUI settings panel can render a persistent banner
+          // from - an operator not tailing logs otherwise never sees the risk.
+          corsWildcardOpen: process.env.CORS_ORIGIN === '*' && !process.env.PASSWORD,
+        };
+        // Host-internal facts (memory, filesystem paths) are exposed only to an
+        // authenticated caller, never on the unauthenticated health-probe bypass.
+        if (!_healthExempt) {
+          _body.memory = process.memoryUsage();
+          _body.projectsDir = process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
+          _body.allowRoots = fsAllowRoots();
+        }
+        sendJSON(req, res, 200, _body);
+        return;
+      }
+
+      // Existence/shape probe for a proposed chat working directory, confined
+      // to the same allowlist as the Files surface (an unconfined stat would be
+      // a filesystem oracle). Returns {ok, dir} or a 403/404 with plain copy.
+      if (routePath.startsWith('/api/stat') && req.method === 'GET') {
+        const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/stat');
+        const conf = confineToRoots(decodedPath, fsAllowRoots());
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: conf.reason }); return; }
+        try {
+          const st = fs.statSync(conf.realPath);
+          sendJSON(req, res, 200, { ok: true, dir: st.isDirectory(), path: conf.realPath });
+        } catch (err) {
+          sendJSON(req, res, err.code === 'ENOENT' ? 404 : 403, { error: safeErrMsg(err) });
+        }
+        return;
+      }
+
+      // Terminal sessions - gated by the Basic-auth check at the top of this handler.
+      // Never expose these routes without PASSWORD set.
+      if (pathOnly === '/api/terminal/sessions' && req.method === 'GET') {
+        sendJSON(req, res, 200, term.listSessions()); return;
+      }
+      if (pathOnly === '/api/terminal/sessions' && req.method === 'POST') {
+        let body = ''; for await (const c of req) body += c;
+        let p = {}; try { p = body ? JSON.parse(body) : {}; } catch {}
+        // Never honour a client-supplied shell or env - that would be a direct
+        // command/arg injection into the spawned process. Only geometry + cwd.
+        // Confine cwd to allowed roots; fall back to STARTUP_CWD on failure.
+        let termCwd = process.env.STARTUP_CWD || process.cwd();
+        if (p.cwd) {
+          const cwdConf = confineToRoots(p.cwd, fsAllowRoots());
+          if (cwdConf.ok) termCwd = cwdConf.realPath;
+        }
+        const s = term.createSession({ cwd: termCwd, cols: p.cols, rows: p.rows });
+        sendJSON(req, res, 200, { sid: s.sid, kind: s.kind, shell: s.shell, cwd: s.cwd, cols: s.cols, rows: s.rows, pid: s.proc.pid });
+        return;
+      }
+      const termMatch = pathOnly.match(/^\/api\/terminal\/sessions\/([0-9a-f]+)$/);
+      if (termMatch && req.method === 'GET') {
+        const s = term.getSession(termMatch[1]);
+        if (!s) { sendJSON(req, res, 404, { error: 'session not found' }); return; }
+        sendJSON(req, res, 200, { sid: s.sid, kind: s.kind, shell: s.shell, cwd: s.cwd, cols: s.cols, rows: s.rows, pid: s.proc.pid, clients: s.clients.size });
+        return;
+      }
+      if (termMatch && req.method === 'DELETE') {
+        const ok = term.closeSession(termMatch[1]);
+        sendJSON(req, res, ok ? 200 : 404, { ok }); return;
+      }
+
+      // Legacy REST handlers removed. History served by ccsniff at /v1/history/*.
+      for (const key of Object.keys(routes)) {
+        try {
+          const h = routes[key]?._match?.(req.method, pathOnly);
+          if (h) { await h(req, res); return; }
+        } catch (_) {}
+      }
+      // Directory listing for the Files / folder-browser view (mirrors fsbrowse
+      // /api/list). Confined to an allowlist root exactly like /api/image - the
+      // normalize-then-prefix-check is the real guard (a `..` test after
+      // path.normalize is a no-op). Returns {path, segments, entries} so the kit
+      // FileGrid + BreadcrumbPath render directly. Allowed roots default to the
+      // server cwd + Claude projects dir; widen via FS_ROOTS (path-separated).
+      if (routePath.startsWith('/api/list')) {
+        const decodedPath = resolveConfinedPath(req, routePath, 'dir', '/api/list');
+        const allowRoots = fsAllowRoots();
+        // Empty path = the first allow-root (a sane default landing dir).
+        const reqPath = !decodedPath ? allowRoots[0] : decodedPath;
+        const conf = confineToRoots(reqPath, allowRoots);
+        if (!conf.ok) {
+          const code = conf.reason === 'not found' ? 404 : 403;
+          sendJSON(req, res, code, { error: 'forbidden: ' + conf.reason }); return;
+        }
+        // Use the symlink-resolved real path for all reads.
+        const normalizedPath = conf.realPath;
+        try {
+          const st = fs.statSync(normalizedPath);
+          if (!st.isDirectory()) { sendJSON(req, res, 400, { error: 'not a directory' }); return; }
+          // Classify by extension into the kit's data-file-type buckets so
+          // FileGrid renders the right rail/icon. dir/symlink come from stat.
+          const EXT_TYPE = {
+            image: ['png','jpg','jpeg','gif','webp','svg','bmp','ico','avif'],
+            video: ['mp4','webm','mov','mkv','avi','m4v'],
+            audio: ['mp3','wav','ogg','flac','m4a','aac'],
+            code: ['js','mjs','cjs','ts','tsx','jsx','rs','go','py','rb','java','c','cpp','h','hpp','cs','php','sh','css','html','json','yml','yaml','toml','sql'],
+            text: ['txt','md','log','csv','env'],
+            archive: ['zip','tar','gz','tgz','rar','7z','bz2','xz'],
+            document: ['pdf','doc','docx','xls','xlsx','ppt','pptx','odt'],
+          };
+          const typeFor = (name, dirent) => {
+            if (dirent.isSymbolicLink()) return 'symlink';
+            if (dirent.isDirectory()) return 'dir';
+            const ext = path.extname(name).slice(1).toLowerCase();
+            for (const [t, exts] of Object.entries(EXT_TYPE)) if (exts.includes(ext)) return t;
+            return 'other';
+          };
+          const dirents = fs.readdirSync(normalizedPath, { withFileTypes: true }).filter((d) => !SECRET_RE.test(d.name));
+          const entries = dirents.map((d) => {
+            const full = path.join(normalizedPath, d.name);
+            let size = null, modified = null, permissions;
+            try {
+              const s = fs.statSync(full); size = s.isDirectory() ? null : s.size; modified = s.mtime.toISOString();
+              // Per-entry permission probe (mirrors fsbrowse checkPermissions) so
+              // the row reads honestly (read-only / no access) instead of a silent
+              // size:null on a stat failure. A stat success means at least read.
+              const perms = ['read'];
+              try { fs.accessSync(full, fs.constants.W_OK); perms.push('write'); } catch (_) {}
+              permissions = perms;
+            } catch (e) {
+              // Could not stat (commonly EACCES): mark no-access so the client
+              // disables open + shows the tag, rather than failing silently.
+              permissions = e && e.code === 'EACCES' ? 'EACCES' : [];
+            }
+            return { name: d.name, type: typeFor(d.name, d), size, modified, path: full, permissions };
+          }).sort((a, b) => (a.type === 'dir' ? 0 : 1) - (b.type === 'dir' ? 0 : 1) || a.name.localeCompare(b.name));
+          // Breadcrumb segments from the absolute path (drive/root aware).
+          const segments = normalizedPath.split(/[\\\/]+/).filter(Boolean);
+          sendJSON(req, res, 200, { path: normalizedPath, segments, entries, roots: allowRoots });
+        } catch (err) {
+          const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+          sendJSON(req, res, code, { error: safeErrMsg(err) });
+        }
+        return;
+      }
+
+      // Raw file bytes for the Files preview pane. Confined to the SAME
+      // allowlist roots as /api/list (server cwd + Claude projects dir, widened
+      // via FS_ROOTS). Same normalize-then-prefix-check guard. Capped at 512KB
+      // and limited to reasonable text/code/image types so this is never a
+      // generic arbitrary-file reader. Images are served via /api/image; this
+      // returns text/* with utf-8.
+      if (routePath.startsWith('/api/file/') || routePath.startsWith('/api/file?')) {
+        const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/file/');
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(decodedPath, allowRoots);
+        if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end('Forbidden'); return; }
+        const normalizedPath = conf.realPath;
+        // Block secret-bearing files regardless of root: dotfiles, env/key/cert
+        // material, and credential stores must never be readable through the
+        // Files preview even when they sit inside an allowed root.
+        const base = path.basename(normalizedPath);
+        if (SECRET_RE.test(base)) { res.writeHead(403); res.end('Forbidden'); return; }
+        // Only known text/code extensions (images go through /api/image). An
+        // unknown/binary extension is rejected, never served as octet-stream.
+        // env/conf/cfg/ini are dropped - they commonly carry secrets.
+        const TEXT_EXTS = new Set([
+          'js','mjs','cjs','ts','tsx','jsx','rs','go','py','rb','java','c','cpp','h','hpp','cs','php','sh','css','html','json','yml','yaml','toml','sql',
+          'txt','md','log','csv','xml','gitignore','dockerfile','svg',
+        ]);
+        const ext = path.extname(normalizedPath).slice(1).toLowerCase()
+          || path.basename(normalizedPath).toLowerCase();
+        if (!TEXT_EXTS.has(ext)) { res.writeHead(403); res.end('Forbidden: unsupported type'); return; }
+        try {
+          const st = fs.statSync(normalizedPath);
+          if (!st.isFile()) { res.writeHead(400); res.end('Not a file'); return; }
+          const MAX = 512 * 1024;
+          const fd = fs.openSync(normalizedPath, 'r');
+          const len = Math.min(st.size, MAX);
+          const buf = Buffer.alloc(len);
+          fs.readSync(fd, buf, 0, len, 0);
+          fs.closeSync(fd);
+          res.writeHead(200, {
+            'Content-Type': 'text/plain; charset=utf-8',
+            'Cache-Control': 'no-cache',
+            'X-File-Truncated': st.size > MAX ? '1' : '0',
+          });
+          res.end(buf);
+        } catch (err) {
+          const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+          res.writeHead(code); res.end(safeErrMsg(err));
+        }
+        return;
+      }
+
+      // Confined raw-bytes download (any type) with an attachment disposition,
+      // so the Files view can offer download on a row. Same allowlist + realpath
+      // confinement as /api/file and /api/image - never a generic file reader.
+      if (routePath.startsWith('/api/download/') || routePath.startsWith('/api/download?')) {
+        const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/download/');
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(decodedPath, allowRoots);
+        if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end('Forbidden'); return; }
+        const normalizedPath = conf.realPath;
+        // Same secret-name block as /api/file: a download must not exfiltrate
+        // .env/.pem/.key/credential material just because it streams bytes.
+        if (SECRET_RE.test(path.basename(normalizedPath))) { res.writeHead(403); res.end('Forbidden'); return; }
+        try {
+          const st = fs.statSync(normalizedPath);
+          if (!st.isFile()) { res.writeHead(400); res.end('Not a file'); return; }
+          const MAX = 50 * 1024 * 1024; // 50MB cap so a download can't exhaust memory
+          if (st.size > MAX) { res.writeHead(413); res.end('File too large to download'); return; }
+          const base = path.basename(normalizedPath);
+          const asciiName = base.replace(/[\\"\r\n]/g, '').replace(/[^\x20-\x7e]/g, '_');
+          res.writeHead(200, {
+            'Content-Type': 'application/octet-stream',
+            'Content-Disposition': 'attachment; filename="' + asciiName + '"; filename*=UTF-8\'\'' + encodeURIComponent(base),
+            'Content-Length': String(st.size),
+            'Cache-Control': 'no-cache',
+          });
+          const rs = fs.createReadStream(normalizedPath);
+          rs.on('error', (streamErr) => { if (!res.writableEnded) res.destroy(streamErr); });
+          rs.pipe(res);
+        } catch (err) {
+          const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+          res.writeHead(code); res.end(safeErrMsg(err));
+        }
+        return;
+      }
+
+      // --- File mutations ----------------------------------------------------
+      // The Files surface is a real manager (fsbrowse-grade): rename, delete,
+      // mkdir, upload. Every route re-confines via confineToRoots (realpath, so
+      // a symlink inside a root cannot point a mutation outside it), refuses
+      // the roots themselves as targets, and sanitizes any NEW name to a single
+      // path component (sanitizeEntryName). All are POST/PUT-only with JSON or
+      // raw-byte bodies; errors map to plain machine codes the client renders
+      // as human copy.
+
+      // POST /api/rename {path, newName} -> {ok, path}
+      if (routePath.split('?')[0] === '/api/rename' && req.method === 'POST') {
+        let body;
+        try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+        catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(String(body.path || ''), allowRoots);
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+        if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot rename an allowed root' }); return; }
+        const newName = sanitizeEntryName(body.newName);
+        if (!newName) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+        if (SECRET_RE.test(newName)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+        const target = path.join(path.dirname(conf.realPath), newName);
+        // The target stays in the same (already-confined) directory by
+        // construction, but re-check anyway so the invariant is local.
+        const tConf = confineToRoots(path.dirname(target), allowRoots);
+        if (!tConf.ok) { sendJSON(req, res, 403, { error: 'forbidden: target outside allowed roots' }); return; }
+        if (fs.existsSync(target)) { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+        try { fs.renameSync(conf.realPath, target); sendJSON(req, res, 200, { ok: true, path: target }); }
+        catch (err) { sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: safeErrMsg(err) }); }
+        return;
+      }
+
+      // POST /api/move {path, destDir, overwrite?} -> {ok, path}. Moves an
+      // entry into another directory; BOTH endpoints re-confine via realpath.
+      // Refuses: a root as the source, a directory moved into itself or its
+      // own subtree, and an existing target unless overwrite:true (and never
+      // overwrites a directory).
+      if (routePath.split('?')[0] === '/api/move' && req.method === 'POST') {
+        let body;
+        try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+        catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(String(body.path || ''), allowRoots);
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+        if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot move an allowed root' }); return; }
+        const dConf = confineToRoots(String(body.destDir || ''), allowRoots);
+        if (!dConf.ok) { sendJSON(req, res, dConf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + dConf.reason }); return; }
+        let destIsDir = false;
+        try { destIsDir = fs.statSync(dConf.realPath).isDirectory(); } catch {}
+        if (!destIsDir) { sendJSON(req, res, 400, { error: 'destination is not a directory' }); return; }
+        const name = sanitizeEntryName(path.basename(conf.realPath));
+        if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+        // A directory must never move into itself or its own subtree.
+        const srcPrefix = conf.realPath + path.sep;
+        if (dConf.realPath === conf.realPath || dConf.realPath.startsWith(srcPrefix)) {
+          sendJSON(req, res, 400, { error: 'cannot move a folder into itself' }); return;
+        }
+        const target = path.join(dConf.realPath, name);
+        if (target === conf.realPath) { sendJSON(req, res, 200, { ok: true, path: target }); return; }
+        if (fs.existsSync(target)) {
+          let targetIsDir = false;
+          try { targetIsDir = fs.lstatSync(target).isDirectory(); } catch {}
+          if (targetIsDir || body.overwrite !== true) {
+            sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return;
+          }
+        }
+        try { fs.renameSync(conf.realPath, target); sendJSON(req, res, 200, { ok: true, path: target }); }
+        catch (err) {
+          const code = err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400;
+          sendJSON(req, res, code, { error: err.code === 'EXDEV' ? 'cannot move across drives' : err.message });
+        }
+        return;
+      }
+
+      // POST /api/delete {path, recursive?} -> {ok}. Deleting a non-empty dir
+      // requires recursive:true (the client confirms first).
+      if (routePath.split('?')[0] === '/api/delete' && req.method === 'POST') {
+        let body;
+        try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+        catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(String(body.path || ''), allowRoots);
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+        if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot delete an allowed root' }); return; }
+        try {
+          const st = fs.lstatSync(conf.realPath);
+          // Soft-delete: move into a confined per-root .agentgui-trash/ instead
+          // of unlinking, so the only safety net isn't confirm-before (the
+          // pre-existing ConfirmDialog) but also undo-after, matching an
+          // fsbrowse-grade file manager. A non-empty directory without
+          // recursive=true still throws ENOTEMPTY BEFORE any move happens
+          // (checked via a dry probe) to keep that existing guard's semantics.
+          if (st.isDirectory() && body.recursive !== true) {
+            const dryEntries = fs.readdirSync(conf.realPath);
+            if (dryEntries.length) { sendJSON(req, res, 409, { error: 'directory is not empty' }); return; }
+          }
+          const trashInfo = moveToTrash(conf.realPath, allowRoots);
+          sendJSON(req, res, 200, { ok: true, trashId: trashInfo.trashId });
+        } catch (err) {
+          const code = err.code === 'ENOTEMPTY' ? 409 : (err.code === 'EACCES' || err.code === 'EPERM' ? 403 : (err.code === 'ENOENT' ? 404 : 400));
+          sendJSON(req, res, code, { error: err.code === 'ENOTEMPTY' ? 'directory is not empty' : err.message });
+        }
+        return;
+      }
+
+      // POST /api/restore {trashId} -> {ok, path}. Undoes a /api/delete within
+      // its retention window (trashRetentionMs, default 10 minutes) by moving
+      // the entry back from .agentgui-trash/ to its original confined path.
+      if (routePath.split('?')[0] === '/api/restore' && req.method === 'POST') {
+        let body;
+        try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+        catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+        try {
+          const restored = restoreFromTrash(String(body.trashId || ''), fsAllowRoots());
+          sendJSON(req, res, 200, { ok: true, path: restored.path });
+        } catch (err) {
+          sendJSON(req, res, err.code === 'NOT_FOUND' ? 404 : (err.code === 'CONFLICT' ? 409 : 400), { error: err.message });
+        }
+        return;
+      }
+
+      // POST /api/mkdir {dir, name} -> {ok, path}. dir must exist inside roots.
+      if (routePath.split('?')[0] === '/api/mkdir' && req.method === 'POST') {
+        let body;
+        try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+        catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(String(body.dir || ''), allowRoots);
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+        const name = sanitizeEntryName(body.name);
+        if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+        if (SECRET_RE.test(name)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+        const target = path.join(conf.realPath, name);
+        if (fs.existsSync(target)) { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+        try { fs.mkdirSync(target); sendJSON(req, res, 200, { ok: true, path: target }); }
+        catch (err) { sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: err.message }); }
+        return;
+      }
+
+      // PUT /api/upload-file?dir=<enc>&name=<enc> with raw file bytes as the
+      // body (no multipart dependency; the client sends fetch(file)). 50MB cap,
+      // never overwrites unless ?overwrite=1. Distinct path from the legacy
+      // express-mounted /api/upload/:conversationId.
+      if (routePath.split('?')[0] === '/api/upload-file' && req.method === 'PUT') {
+        let qs;
+        try { qs = new URL(req.url, 'http://localhost').searchParams; } catch { qs = new URLSearchParams(); }
+        // Require Content-Length header: rejects chunked or missing-length requests
+        // that could claim any size. Pre-validates the announced size before streaming.
+        const contentLength = req.headers['content-length'];
+        if (!contentLength) {
+          sendJSON(req, res, 411, { error: 'length required' }); return;
+        }
+        const MAX_UPLOAD = 50 * 1024 * 1024;
+        const len = parseInt(contentLength, 10);
+        if (isNaN(len) || len < 0 || len > MAX_UPLOAD) {
+          sendJSON(req, res, 413, { error: `file too large (max ${MAX_UPLOAD} bytes)` }); return;
+        }
+        const allowRoots = fsAllowRoots();
+        const conf = confineToRoots(qs.get('dir') || '', allowRoots);
+        if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+        const name = sanitizeEntryName(qs.get('name'));
+        if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+        if (SECRET_RE.test(name)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+        const target = path.join(conf.realPath, name);
+        if (fs.existsSync(target) && qs.get('overwrite') !== '1') { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+        // Stream the upload body to a temp file to keep memory constant and
+        // avoid blocking the event loop with a large synchronous writeFileSync.
+        const tmpPath = target + '.tmp.' + crypto.randomBytes(6).toString('hex');
+        try {
+          await new Promise((resolve, reject) => {
+            const ws = fs.createWriteStream(tmpPath);
+            let total = 0;
+            ws.on('error', reject);
+            req.on('error', reject);
+            req.on('data', (chunk) => {
+              total += chunk.length;
+              if (total > MAX_UPLOAD) {
+                ws.destroy();
+                req.destroy();
+                const e = new Error('file too large (50MB cap)'); e.code = 'TOO_LARGE';
+                reject(e); return;
+              }
+              ws.write(chunk);
+            });
+            req.on('end', () => ws.end());
+            ws.on('finish', () => resolve(total));
+          });
+          fs.renameSync(tmpPath, target);
+          const uploadedSize = fs.statSync(target).size;
+          sendJSON(req, res, 200, { ok: true, path: target, size: uploadedSize });
+        } catch (err) {
+          try { fs.unlinkSync(tmpPath); } catch (_) {}
+          if (err.code === 'TOO_LARGE') { sendJSON(req, res, 413, { error: 'file too large (50MB cap)' }); return; }
+          sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: 'upload failed' });
+        }
+        return;
+      }
+
+      if (routePath.startsWith('/api/image/') || routePath.startsWith('/api/image?')) {
+        const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/image/');
+        // Confine reads to an allowlist root. Without this the route is an
+        // arbitrary-file-read of any image-extensioned path on the host (the
+        // prior `includes('..')` guard is a no-op after path.normalize resolves
+        // the segments). Allowed roots: the Claude projects dir (history images)
+        // only; add more via IMAGE_ROOTS (path-separated). The user home is NOT
+        // a default root - it covers ~/.ssh, ~/.aws, dotfiles etc., so an image
+        // route reaching all of home is a broad read of anything image-shaped.
+        // confineToRoots also realpath-resolves so a symlink inside a root can't
+        // point an image read at an out-of-root file.
+        const allowRoots = [
+          process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+          ...(process.env.IMAGE_ROOTS ? process.env.IMAGE_ROOTS.split(path.delimiter) : []),
+        ].map(r => path.normalize(r));
+        const conf = confineToRoots(decodedPath, allowRoots);
+        if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end(conf.reason === 'not found' ? 'Not found' : 'Forbidden'); return; }
+        const normalizedPath = conf.realPath;
+        try {
+          const ext = path.extname(normalizedPath).toLowerCase();
+          const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+          // SVG is intentionally excluded: browsers render SVG as a live document
+          // in the app's origin, so an agent-written SVG with a <script src=CDN>
+          // would execute in the agentgui origin (CSP allows unpkg/jsdelivr).
+          // Files preview uses /api/file/download (attachment) for SVG.
+          const contentType = mimeTypes[ext];
+          if (!contentType) { res.writeHead(403); res.end('Forbidden'); return; }
+          const imgSt = fs.statSync(normalizedPath);
+          const IMG_MAX = 20 * 1024 * 1024; // 20MB hard cap
+          if (imgSt.size > IMG_MAX) { res.writeHead(413); res.end('Image too large'); return; }
+          // Always stream to avoid blocking the event loop on large synchronous reads.
+          res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-cache', 'Content-Length': String(imgSt.size) });
+          const imgRs = fs.createReadStream(normalizedPath);
+          imgRs.on('error', (streamErr) => { if (!res.writableEnded) res.destroy(streamErr); });
+          imgRs.pipe(res);
+        } catch (err) { sendJSON(req, res, 400, { error: 'cannot read image' }); }
+        return;
+      }
+
+      if (pathOnly.match(/^\/conversations\/[^\/]+$/)) { serveFile(path.join(staticDir, 'index.html'), res, req, cspNonce); return; }
+
+      const routePathBare = routePath.split('?')[0];
+      let filePath = routePathBare === '/' ? '/index.html' : routePathBare;
+      filePath = path.join(staticDir, filePath);
+      const normalizedPath = path.normalize(filePath);
+      if (!normalizedPath.startsWith(staticDir)) { res.writeHead(403); res.end('Forbidden'); return; }
+
+      fs.stat(filePath, (err, stats) => {
+        if (err) { res.writeHead(404); res.end('Not found'); return; }
+        if (stats.isDirectory()) {
+          filePath = path.join(filePath, 'index.html');
+          fs.stat(filePath, (err2) => { if (err2) { res.writeHead(404); res.end('Not found'); return; } serveFile(filePath, res, req, cspNonce); });
+        } else { serveFile(filePath, res, req, cspNonce); }
+      });
+    } catch (e) {
+      console.error('Server error:', maskToken(e.message), e.stack, '| path:', maskToken(req.url.split('?')[0]));
+      sendJSON(req, res, 500, { error: 'internal server error' });
+    }
+  };
+}