@xingjisoft/neutrino 0.2.1 → 0.4.0

package/dist/web/server.js

@@ -16,13 +16,15 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { SESSION_DIR, listSessions, resolveModelSelection } from "../config.js";
+import { deleteSession, listSessions, loadConfig, normalizeApprovalMode, resolveModelSelection, saveConfig, sessionDir, } from "../config.js";
 import { getWebSettings, updateWebSettings } from "./settings.js";
 import { WebAuth } from "./auth.js";
-import { normalizeCwd } from "../cwd.js";
+import { normalizeCwd, sameCwd } from "../cwd.js";
 import { hub } from "./hub.js";
 import { writeCrashLog } from "../terminal/restore.js";
-import { resumeSession } from "./session.js";
+import { createWebSession, proInitialSelection, resumeSession } from "./session.js";
+import { defaultProPreset, requireProPreset } from "../pro/config.js";
+import { listAgentSessions, loadAgentMessages } from "../agents.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // dist/web -> package root (mirrors the same trick used in config.ts).
 const PKG_ROOT = path.resolve(__dirname, "..", "..");
@@ -42,6 +44,9 @@ function closeWebSession(key) {
 }
 /** Bind addresses that mean "every interface" rather than one host. */
 const WILDCARD_HOSTS = new Set(["0.0.0.0", "::", "[::]", ""]);
+/** The two interfaces the Web access switch moves between. */
+const LOOPBACK_HOST = "127.0.0.1";
+const WILDCARD_HOST = "0.0.0.0";
 /** True when `host` only accepts connections from this machine. */
 export function isLoopbackHost(host) {
     const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
@@ -49,6 +54,17 @@ export function isLoopbackHost(host) {
         return false;
     return h === "localhost" || h === "::1" || h.startsWith("127.");
 }
+/** True when `host` listens on every interface, i.e. what --lan selects. */
+export function isWildcardHost(host) {
+    return WILDCARD_HOSTS.has(host.trim().toLowerCase().replace(/^\[|\]$/g, ""));
+}
+/**
+ * The interface a fresh listener uses when the command line did not pick one.
+ * The saved Web access switch behaves exactly like `--lan`.
+ */
+function defaultWebHost() {
+    return loadConfig().web_lan === true ? WILDCARD_HOST : LOOPBACK_HOST;
+}
 /**
  * Adapters that only ever talk to this machine: hypervisor host-only switches,
  * container bridges and loopback variants. Listing them would bury the address
@@ -98,6 +114,26 @@ export function webUrls(host, port) {
         urls: hosts.map((h) => `http://${h}:${port}/`),
     };
 }
+/**
+ * Settings plus the live socket. The `web_lan` switch reports and changes what
+ * is listening right now, so a run started with --lan shows as on even though
+ * nothing was saved yet.
+ */
+function settingsPayload(mode, binding) {
+    const payload = getWebSettings(mode);
+    const lan = isWildcardHost(binding.host);
+    const { urls } = webUrls(binding.host, binding.port);
+    return {
+        ...payload,
+        settings: {
+            ...payload.settings,
+            web_lan: lan,
+            web_host: binding.host,
+            // Addresses another device can open; empty unless every interface is bound.
+            web_urls: lan ? urls.filter((url) => !url.includes("//127.0.0.1:")) : [],
+        },
+    };
+}
 const MIME_TYPES = {
     ".html": "text/html; charset=utf-8",
     ".css": "text/css; charset=utf-8",
@@ -119,11 +155,12 @@ const SESSION_ID_RE = /^[A-Za-z0-9._-]{1,200}$/;
 function isSafeSessionId(id) {
     return SESSION_ID_RE.test(id) && id !== "." && id !== ".." && !id.includes("..");
 }
-function loadSessionSafe(id) {
+function loadSessionSafe(id, mode = "standard") {
     if (!isSafeSessionId(id))
         return null;
-    const filePath = path.join(SESSION_DIR, `${id}.json`);
-    if (path.dirname(filePath) !== SESSION_DIR)
+    const dir = sessionDir(mode);
+    const filePath = path.join(dir, `${id}.json`);
+    if (path.dirname(filePath) !== dir)
         return null;
     try {
         return JSON.parse(fs.readFileSync(filePath, "utf-8"));
@@ -132,10 +169,198 @@ function loadSessionSafe(id) {
         return null;
     }
 }
-/** Build the sidebar payload: every session grouped by working directory. */
-function buildOverview() {
-    const sessions = listSessions();
-    const lives = hub.list();
+// ------------------------------------------------------- working directories
+//
+// The browser console can open any folder on this machine, which is exactly
+// what the terminal can do by being launched from that folder. Every route
+// below still sits behind the login cookie: browsing the filesystem is only as
+// exposed as the authenticated console itself.
+class ApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function sendApiError(res, error) {
+    if (error instanceof ApiError) {
+        sendJson(res, error.status, { error: error.message, code: error.code });
+        return;
+    }
+    const message = error instanceof Error ? error.message : "invalid request";
+    sendJson(res, 400, { error: message });
+}
+const MAX_RECENT_WORKSPACES = 12;
+const AGENT_IDS = new Set(["claude", "codex", "opencode"]);
+const AGENT_SESSION_ID_RE = /^[A-Za-z0-9._-]{1,200}$/;
+/** Expand `~` and require an absolute path; used by every folder route. */
+function absolutePath(raw) {
+    if (typeof raw !== "string" || !raw.trim()) {
+        throw new ApiError(400, "working directory is required", "working directory is required");
+    }
+    let value = raw.trim();
+    if (value === "~")
+        value = os.homedir();
+    else if (/^~[\\/]/.test(value))
+        value = path.join(os.homedir(), value.slice(2));
+    if (!path.isAbsolute(value)) {
+        throw new ApiError(400, "working directory must be an absolute path", "working directory must be an absolute path");
+    }
+    return path.resolve(value);
+}
+function existingDirectory(raw) {
+    const dir = absolutePath(raw);
+    let stat;
+    try {
+        stat = fs.statSync(dir);
+    }
+    catch {
+        throw new ApiError(400, "working directory does not exist", "working directory does not exist");
+    }
+    if (!stat.isDirectory()) {
+        throw new ApiError(400, "working directory is not a folder", "working directory is not a folder");
+    }
+    return dir;
+}
+let cachedRoots = null;
+/** Filesystem roots worth offering as shortcuts (every existing drive on Windows). */
+function filesystemRoots() {
+    if (cachedRoots)
+        return cachedRoots;
+    if (process.platform !== "win32") {
+        cachedRoots = ["/"];
+        return cachedRoots;
+    }
+    const roots = [];
+    for (let code = 65; code <= 90; code += 1) {
+        const root = `${String.fromCharCode(code)}:\\`;
+        try {
+            if (fs.statSync(root).isDirectory())
+                roots.push(root);
+        }
+        catch {
+            // A drive letter that does not exist is simply not offered.
+        }
+    }
+    cachedRoots = roots.length ? roots : [path.parse(process.cwd()).root];
+    return cachedRoots;
+}
+/** One directory listing for the folder picker. Files are hidden: the picker chooses directories. */
+function readFolder(raw) {
+    const dir = existingDirectory(raw);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        throw new ApiError(403, "cannot read this folder", err instanceof Error ? err.message : "cannot read this folder");
+    }
+    const folders = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+        name: entry.name,
+        path: path.join(dir, entry.name),
+        hidden: entry.name.startsWith("."),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+    const parent = path.dirname(dir);
+    return {
+        path: dir,
+        name: path.basename(dir) || dir,
+        parent: parent === dir ? null : parent,
+        separator: path.sep,
+        home: os.homedir(),
+        cwd: process.cwd(),
+        roots: filesystemRoots(),
+        entries: folders,
+    };
+}
+/** Recent working directories: explicitly opened ones first, then saved-session folders. */
+function recentWorkspacePaths(mode = "standard") {
+    const config = loadConfig(mode);
+    const stored = Array.isArray(config.web_workspaces)
+        ? config.web_workspaces.filter((entry) => typeof entry === "string" && entry.trim() !== "")
+        : [];
+    const saved = listSessions(mode).map((session) => session.cwd).filter(Boolean);
+    const seen = new Set();
+    const out = [];
+    for (const dir of [...stored, ...saved, process.cwd()]) {
+        const key = normalizeCwd(dir);
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(dir);
+        if (out.length >= MAX_RECENT_WORKSPACES)
+            break;
+    }
+    return out;
+}
+function workspaceList(mode = "standard") {
+    const sessions = listSessions(mode);
+    return recentWorkspacePaths(mode).map((dir) => {
+        let exists = false;
+        try {
+            exists = fs.statSync(dir).isDirectory();
+        }
+        catch {
+            // A folder that disappeared stays listed, greyed out, so it can be removed by choosing another.
+        }
+        return {
+            path: dir,
+            name: path.basename(dir) || dir,
+            sessions: sessions.filter((session) => sameCwd(session.cwd, dir)).length,
+            exists,
+        };
+    });
+}
+/** Best-effort persistence: failing to remember a folder must not fail the conversation. */
+function recordWorkspace(dir, mode = "standard") {
+    try {
+        const config = loadConfig(mode);
+        const stored = Array.isArray(config.web_workspaces)
+            ? config.web_workspaces.filter((entry) => typeof entry === "string")
+            : [];
+        config.web_workspaces = [dir, ...stored.filter((entry) => !sameCwd(entry, dir))]
+            .slice(0, MAX_RECENT_WORKSPACES);
+        saveConfig(config, mode);
+    }
+    catch {
+        // The picked folder still works for this conversation.
+    }
+}
+/** Create one folder inside an existing parent. */
+function createFolder(raw) {
+    const target = absolutePath(raw);
+    if (target === path.parse(target).root) {
+        throw new ApiError(400, "cannot create a folder here", "cannot create a folder here");
+    }
+    const parent = path.dirname(target);
+    if (!fs.existsSync(parent) || !fs.statSync(parent).isDirectory()) {
+        throw new ApiError(400, "parent folder does not exist", "parent folder does not exist");
+    }
+    if (fs.existsSync(target)) {
+        throw new ApiError(409, "folder already exists", "folder already exists");
+    }
+    try {
+        fs.mkdirSync(target);
+    }
+    catch (err) {
+        throw new ApiError(400, "cannot create a folder here", err instanceof Error ? err.message : "cannot create a folder here");
+    }
+    return target;
+}
+function isAgentId(value) {
+    return AGENT_IDS.has(value);
+}
+function safeAgentSessionId(id) {
+    return AGENT_SESSION_ID_RE.test(id) && !id.includes("..") && id !== "." && id !== "..";
+}
+/** Build the sidebar payload: the selected workspace's sessions grouped by directory. */
+function buildOverview(mode = "standard") {
+    const sessions = listSessions(mode);
+    const lives = hub.list(mode);
     const liveBySession = new Map();
     for (const live of lives) {
         if (live.sessionId)
@@ -178,7 +403,9 @@ function buildOverview() {
             provider: live.provider,
             intensity: live.intensity,
             cwd: live.cwd,
-            title: live.title || "New conversation",
+            // An unnamed conversation keeps an empty title: the browser translates
+            // its own fallback, and the terminal/server never impose one language.
+            title: live.title || "",
             message_count: 0,
             live: true,
             liveKey: live.key,
@@ -339,8 +566,7 @@ function streamLive(key, req, res) {
     // Without this, a client reset during a write is an uncaught 'error' event.
     res.on("error", cleanup);
 }
-async function handleApi(req, res, url, auth) {
-    const { pathname } = url;
+async function handleApi(req, res, url, auth, mode, pathname, binding) {
     if (!pathname.startsWith("/api/"))
         return false;
     if (req.method === "OPTIONS") {
@@ -386,22 +612,46 @@ async function handleApi(req, res, url, auth) {
     }
     if (pathname === "/api/settings") {
         if (req.method === "GET") {
-            sendJson(res, 200, getWebSettings());
+            sendJson(res, 200, settingsPayload(mode, binding));
         }
         else if (req.method === "POST") {
             if (!isSameOrigin(req)) {
                 sendJson(res, 403, { error: "cross-origin request rejected" });
                 return true;
             }
+            const wasLan = loadConfig(mode).web_lan === true;
             try {
                 const body = await readJsonBody(req);
-                updateWebSettings(body);
+                updateWebSettings(body, mode);
+                // `web_lan` is both a saved preference and a live switch: apply it to
+                // the socket now so the console starts or stops answering on the LAN
+                // without a restart. Other settings never move the listener, and an
+                // explicit --host still decides the interface until this is changed.
+                const patch = body?.settings;
+                const desired = patch && Object.prototype.hasOwnProperty.call(patch, "web_lan")
+                    ? patch.web_lan === true
+                    : isWildcardHost(binding.host);
+                if (desired !== isWildcardHost(binding.host)) {
+                    await binding.setHost(desired ? WILDCARD_HOST : LOOPBACK_HOST);
+                }
                 if (body.settings?.web_password !== undefined) {
                     auth.remember(res);
                 }
-                sendJson(res, 200, getWebSettings());
+                sendJson(res, 200, settingsPayload(mode, binding));
             }
             catch (err) {
+                // A switch that could not bind must not pretend the socket moved:
+                // restore the saved preference so the file matches what is running.
+                if ((loadConfig(mode).web_lan === true) !== wasLan) {
+                    try {
+                        const config = loadConfig(mode);
+                        config.web_lan = wasLan;
+                        saveConfig(config, mode);
+                    }
+                    catch {
+                        // Reporting the original failure matters more than the rollback.
+                    }
+                }
                 sendJson(res, err?.code ? 500 : 400, {
                     error: err instanceof Error ? err.message : "invalid settings",
                 });
@@ -413,15 +663,165 @@ async function handleApi(req, res, url, auth) {
         return true;
     }
     if (req.method === "GET" && pathname === "/api/health") {
-        sendJson(res, 200, { ok: true, live: hub.list().length });
+        sendJson(res, 200, { ok: true, live: hub.list(mode).length });
         return true;
     }
     if (req.method === "GET" && pathname === "/api/overview") {
-        sendJson(res, 200, buildOverview());
+        sendJson(res, 200, buildOverview(mode));
         return true;
     }
     if (req.method === "GET" && pathname === "/api/sessions") {
-        sendJson(res, 200, { sessions: listSessions() });
+        sendJson(res, 200, { sessions: listSessions(mode) });
+        return true;
+    }
+    if (pathname === "/api/workspaces") {
+        if (req.method === "GET") {
+            sendJson(res, 200, {
+                cwd: process.cwd(),
+                home: os.homedir(),
+                workspaces: workspaceList(mode),
+            });
+            return true;
+        }
+        if (req.method === "POST") {
+            if (!isSameOrigin(req)) {
+                sendJson(res, 403, { error: "cross-origin request rejected" });
+                return true;
+            }
+            try {
+                const body = await readJsonBody(req);
+                const dir = existingDirectory(body?.path);
+                recordWorkspace(dir, mode);
+                sendJson(res, 200, { ok: true, path: dir, workspaces: workspaceList(mode) });
+            }
+            catch (err) {
+                sendApiError(res, err);
+            }
+            return true;
+        }
+        sendJson(res, 405, { error: "method not allowed" });
+        return true;
+    }
+    if (pathname === "/api/fs") {
+        if (req.method !== "GET") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        try {
+            sendJson(res, 200, readFolder(url.searchParams.get("path") ?? process.cwd()));
+        }
+        catch (err) {
+            sendApiError(res, err);
+        }
+        return true;
+    }
+    if (pathname === "/api/fs/mkdir") {
+        if (req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const created = createFolder(body?.path);
+            sendJson(res, 200, { ok: true, path: created });
+        }
+        catch (err) {
+            sendApiError(res, err);
+        }
+        return true;
+    }
+    // Start a brand-new conversation in a working directory chosen by the
+    // browser. Unlike `/continue`, there is no transcript to load first.
+    if (pathname === "/api/conversations") {
+        if (req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            if (!body || typeof body !== "object" || Array.isArray(body)) {
+                throw new ApiError(400, "invalid request", "invalid request");
+            }
+            const input = body;
+            const cwd = existingDirectory(input.cwd ?? process.cwd());
+            const requested = input.selection === undefined
+                ? getWebSettings(mode).selection
+                : input.selection;
+            const preset = mode === "pro" ? requireProPreset(input.pro_preset ?? defaultProPreset()) : undefined;
+            const selection = mode === "pro" ? proInitialSelection(preset) : resolveModelSelection(requested, false);
+            let approvalMode;
+            if (input.approval_mode !== undefined) {
+                if (input.approval_mode !== "request" && input.approval_mode !== "auto") {
+                    throw new ApiError(400, "invalid approval mode", "invalid approval mode");
+                }
+                approvalMode = normalizeApprovalMode(input.approval_mode);
+            }
+            const session = createWebSession(cwd, selection, approvalMode, mode, preset);
+            const key = session.start();
+            webSessions.set(key, session);
+            recordWorkspace(cwd, mode);
+            sendJson(res, 200, { ok: true, key, cwd, snapshot: hub.snapshot(key) });
+        }
+        catch (err) {
+            sendApiError(res, err);
+        }
+        return true;
+    }
+    const deleteMatch = /^\/api\/session\/([^/]+)\/delete$/.exec(pathname);
+    if (req.method === "POST" && deleteMatch) {
+        if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        const id = decodeURIComponent(deleteMatch[1]);
+        if (!isSafeSessionId(id)) {
+            sendJson(res, 400, { error: "invalid session id" });
+            return true;
+        }
+        if (hub.list(mode).some((entry) => entry.sessionId === id)) {
+            sendJson(res, 409, { error: "cannot delete a running conversation" });
+            return true;
+        }
+        if (!deleteSession(id, mode)) {
+            sendJson(res, 404, { error: "session not found" });
+            return true;
+        }
+        sendJson(res, 200, { ok: true, deleted: true });
+        return true;
+    }
+    // Read-only history recorded by other agents (Claude Code, Codex, OpenCode).
+    const agentSessionsMatch = /^\/api\/agents\/([^/]+)\/sessions$/.exec(pathname);
+    if (req.method === "GET" && agentSessionsMatch) {
+        const agent = decodeURIComponent(agentSessionsMatch[1]);
+        if (!isAgentId(agent)) {
+            sendJson(res, 400, { error: "unknown agent" });
+            return true;
+        }
+        const cwd = url.searchParams.get("cwd") || process.cwd();
+        sendJson(res, 200, { agent, cwd, sessions: listAgentSessions(agent, cwd) });
+        return true;
+    }
+    const agentSessionMatch = /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)$/.exec(pathname);
+    if (req.method === "GET" && agentSessionMatch) {
+        const agent = decodeURIComponent(agentSessionMatch[1]);
+        const id = decodeURIComponent(agentSessionMatch[2]);
+        if (!isAgentId(agent)) {
+            sendJson(res, 400, { error: "unknown agent" });
+            return true;
+        }
+        if (!safeAgentSessionId(id)) {
+            sendJson(res, 400, { error: "invalid session id" });
+            return true;
+        }
+        sendJson(res, 200, { agent, id, messages: loadAgentMessages(agent, id) });
         return true;
     }
     const sessionMatch = /^\/api\/session\/([^/]+)$/.exec(pathname);
@@ -431,7 +831,7 @@ async function handleApi(req, res, url, auth) {
             sendJson(res, 400, { error: "invalid session id" });
             return true;
         }
-        const data = loadSessionSafe(id);
+        const data = loadSessionSafe(id, mode);
         if (!data) {
             sendJson(res, 404, { error: "session not found" });
             return true;
@@ -451,21 +851,32 @@ async function handleApi(req, res, url, auth) {
             return true;
         }
         let selection;
+        let preset;
         try {
             const body = await readJsonBody(req);
             if (!body || typeof body !== "object" || Array.isArray(body))
                 throw new Error("invalid JSON body");
             const requested = body.selection;
-            if (requested !== undefined)
+            if (requested !== undefined && mode !== "pro")
                 selection = resolveModelSelection(requested);
+            const requestedPreset = body.pro_preset;
+            if (requestedPreset !== undefined && mode === "pro")
+                preset = requireProPreset(requestedPreset);
         }
         catch (err) {
             sendJson(res, 400, { error: err instanceof Error ? err.message : "invalid model selection" });
             return true;
         }
         // Already running (TUI or another tab)? Attach instead of duplicating.
-        const existing = hub.list().find((entry) => entry.sessionId === id);
+        const existing = hub.list(mode).find((entry) => entry.sessionId === id);
         if (existing) {
+            if (preset !== undefined) {
+                const changed = hub.setProPreset(existing.key, preset);
+                if (!changed.ok) {
+                    sendJson(res, 409, { error: changed.error });
+                    return true;
+                }
+            }
             if (selection) {
                 const changed = hub.configure(existing.key, selection);
                 if (!changed.ok) {
@@ -476,15 +887,17 @@ async function handleApi(req, res, url, auth) {
             sendJson(res, 200, { key: existing.key, attached: true });
             return true;
         }
-        const data = loadSessionSafe(id);
+        const data = loadSessionSafe(id, mode);
         if (!data) {
             sendJson(res, 404, { error: "session not found" });
             return true;
         }
+        if (preset !== undefined)
+            data.pro_preset = preset;
         const requested = selection ? {
             provider: selection.provider, model: selection.model.name, intensity: selection.intensity,
         } : undefined;
-        const outcome = resumeSession(data, requested);
+        const outcome = resumeSession(data, requested, mode);
         if (!outcome.ok) {
             sendJson(res, 400, { error: outcome.error });
             return true;
@@ -496,15 +909,22 @@ async function handleApi(req, res, url, auth) {
     }
     const streamMatch = /^\/api\/live\/([^/]+)\/stream$/.exec(pathname);
     if (req.method === "GET" && streamMatch) {
-        streamLive(decodeURIComponent(streamMatch[1]), req, res);
+        const key = decodeURIComponent(streamMatch[1]);
+        // A Pro tab must never observe (or be handed) a session from the other
+        // workspace just because it guessed the key.
+        if (!hub.has(key, mode)) {
+            sendJson(res, 404, { error: "unknown live session" });
+            return true;
+        }
+        streamLive(key, req, res);
         return true;
     }
-    const liveMatch = /^\/api\/live\/([^/]+)(?:\/(pause|resume|message|approve|close|model|approval-mode))?$/.exec(pathname);
+    const liveMatch = /^\/api\/live\/([^/]+)(?:\/(pause|resume|message|approve|close|model|pro-preset|approval-mode|clear))?$/.exec(pathname);
     if (liveMatch) {
         const key = decodeURIComponent(liveMatch[1]);
         const action = liveMatch[2];
         if (req.method === "GET" && !action) {
-            const snapshot = hub.snapshot(key);
+            const snapshot = hub.has(key, mode) ? hub.snapshot(key) : null;
             if (!snapshot) {
                 sendJson(res, 404, { error: "unknown live session" });
                 return true;
@@ -517,10 +937,29 @@ async function handleApi(req, res, url, auth) {
                 sendJson(res, 403, { error: "cross-origin request rejected" });
                 return true;
             }
-            if (!hub.has(key)) {
+            if (!hub.has(key, mode)) {
                 sendJson(res, 404, { error: "unknown live session" });
                 return true;
             }
+            if (action === "pro-preset") {
+                if (mode !== "pro") {
+                    sendJson(res, 404, { error: "Pro presets are only available in Pro mode" });
+                    return true;
+                }
+                try {
+                    const body = await readJsonBody(req);
+                    const preset = requireProPreset(body?.preset);
+                    const changed = hub.setProPreset(key, preset);
+                    if (!changed.ok)
+                        sendJson(res, 409, { error: changed.error });
+                    else
+                        sendJson(res, 200, { ok: true, snapshot: hub.snapshot(key) });
+                }
+                catch (error) {
+                    sendJson(res, 400, { error: error instanceof Error ? error.message : "invalid Pro preset" });
+                }
+                return true;
+            }
             if (action === "approval-mode") {
                 let body;
                 try {
@@ -593,6 +1032,14 @@ async function handleApi(req, res, url, auth) {
                 sendJson(res, 200, { ok: true, closed: true });
                 return true;
             }
+            if (action === "clear") {
+                if (!hub.clear(key)) {
+                    sendJson(res, 409, { error: "this session cannot be cleared" });
+                    return true;
+                }
+                sendJson(res, 200, { ok: true, snapshot: hub.snapshot(key) });
+                return true;
+            }
             // action === "message"
             let body;
             try {
@@ -617,7 +1064,7 @@ async function handleApi(req, res, url, auth) {
     sendJson(res, 404, { error: "not found" });
     return true;
 }
-async function handleRequest(req, res, auth) {
+async function handleRequest(req, res, auth, binding) {
     let url;
     try {
         url = new URL(req.url ?? "/", "http://localhost");
@@ -626,20 +1073,59 @@ async function handleRequest(req, res, auth) {
         sendText(res, 400, "Bad request");
         return;
     }
-    if (await handleApi(req, res, url, auth))
+    // The Pro workspace is the same single-page app at /pro, talking to an
+    // isolated API under /pro/api. Static assets stay at the root (the app uses
+    // root-absolute URLs), so only the page route and the API prefix are special.
+    const pathname = url.pathname;
+    if (pathname === "/pro" || pathname === "/pro/") {
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            sendText(res, 405, "Method not allowed");
+            return;
+        }
+        if (pathname === "/pro/") {
+            // Canonical URL without the trailing slash keeps relative links rooted.
+            res.writeHead(308, { Location: `/pro${url.search}` });
+            res.end();
+            return;
+        }
+        serveStatic(res, "/index.html");
+        return;
+    }
+    let mode = "standard";
+    let apiPathname = pathname;
+    if (pathname.startsWith("/pro/api/")) {
+        mode = "pro";
+        apiPathname = pathname.slice("/pro".length);
+    }
+    if (await handleApi(req, res, url, auth, mode, apiPathname, binding))
         return;
+    if (mode === "pro") {
+        // Nothing else lives under /pro but the page and its API.
+        sendText(res, 404, "Not found");
+        return;
+    }
     if (req.method !== "GET" && req.method !== "HEAD") {
         sendText(res, 405, "Method not allowed");
         return;
     }
-    serveStatic(res, url.pathname);
+    serveStatic(res, pathname);
 }
 /** Start the web UI. Resolves once the socket is actually listening. */
 export async function startWebServer(options) {
-    const host = options.host ?? "127.0.0.1";
     const auth = new WebAuth(options.auth !== false);
+    // An explicit --host/--lan wins for this run; otherwise the saved Web access
+    // switch is applied exactly as if `--lan` had been passed.
+    let host = options.host?.trim() || defaultWebHost();
+    let port = options.port;
+    let closed = false;
+    // The settings page reads and changes this binding while the process runs.
+    const binding = {
+        host,
+        port,
+        setHost: (next) => rebind(next),
+    };
     const server = http.createServer((req, res) => {
-        handleRequest(req, res, auth).catch((err) => {
+        handleRequest(req, res, auth, binding).catch((err) => {
             if (!res.headersSent) {
                 sendJson(res, 500, { error: err instanceof Error ? err.message : "internal error" });
             }
@@ -648,41 +1134,116 @@ export async function startWebServer(options) {
             }
         });
     });
-    await new Promise((resolve, reject) => {
+    /** Wait for the socket to actually listen, or for it to fail. */
+    const listen = (onHost) => new Promise((resolve, reject) => {
         const onError = (err) => {
             server.removeListener("listening", onListening);
             reject(err);
         };
         const onListening = () => {
             server.removeListener("error", onError);
-            // Once listening, the server must tolerate connection-level failures
-            // (resets, EMFILE, half-open sockets) without the process dying. An
-            // 'error' event with no listener is fatal in Node.
-            server.on("error", (err) => {
-                writeCrashLog("web server", err);
-            });
-            server.on("clientError", (_err, socket) => {
-                if (socket.writable)
-                    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
-                socket.destroy();
-            });
             resolve();
         };
         server.once("error", onError);
         server.once("listening", onListening);
-        server.listen(options.port, host);
+        server.listen(port, onHost);
     });
-    const address = server.address();
-    const port = typeof address === "object" && address ? address.port : options.port;
-    return {
+    /** A just-closed port can need a moment to reappear: retry only that race. */
+    async function listenRetry(onHost) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await listen(onHost);
+                return;
+            }
+            catch (err) {
+                if (err.code !== "EADDRINUSE" || attempt >= 20)
+                    throw err;
+                await new Promise((done) => setTimeout(done, 10));
+            }
+        }
+    }
+    const syncAddress = () => {
+        const address = webUrls(host, port);
+        binding.host = host;
+        binding.port = port;
+        handle.host = host;
+        handle.port = port;
+        handle.url = address.url;
+        handle.urls = address.urls;
+    };
+    // Two tabs saving at once must not interleave close/listen on one socket.
+    let switches = Promise.resolve();
+    function rebind(next) {
+        const target = next.trim() || LOOPBACK_HOST;
+        const task = switches.then(async () => {
+            if (closed)
+                throw new Error("the Web console is shutting down");
+            if (target === host && server.listening)
+                return;
+            // `close` ends acceptance, not the connections already accepted. The
+            // listener is released immediately, which is all the switch needs, so a
+            // streaming turn and the tab that asked for the change stay connected.
+            if (server.listening)
+                server.close();
+            try {
+                await listenRetry(target);
+            }
+            catch (err) {
+                // Put the console back where it was rather than leaving it dark.
+                if (!closed) {
+                    try {
+                        await listenRetry(host);
+                    }
+                    catch {
+                        // The settings response still reports the original failure.
+                    }
+                }
+                throw err;
+            }
+            // A concurrent shutdown wins: never resurrect a console being closed.
+            if (closed) {
+                server.close();
+                throw new Error("the Web Console is shutting down");
+            }
+            host = target;
+            syncAddress();
+        });
+        switches = task.catch(() => undefined);
+        return task;
+    }
+    const handle = {
         host,
         port,
         authRequired: auth.enabled,
-        ...webUrls(host, port),
+        url: "",
+        urls: [],
+        setHost: (next) => rebind(next),
         close: () => new Promise((resolve) => {
+            closed = true;
             for (const key of [...webSessions.keys()])
                 closeWebSession(key);
+            if (!server.listening) {
+                resolve();
+                return;
+            }
             server.close(() => resolve());
         }),
     };
+    await listenRetry(host);
+    // Port 0 means "let the OS pick": remember the real one for every URL.
+    const address = server.address();
+    port = typeof address === "object" && address ? address.port : options.port;
+    syncAddress();
+    // Once listening, the server must tolerate connection-level failures
+    // (resets, EMFILE, half-open sockets) without the process dying: an 'error'
+    // event with no listener is fatal in Node.
+    server.on("error", (err) => {
+        writeCrashLog("web server", err);
+    });
+    server.on("clientError", (_err, socket) => {
+        if (socket.writable)
+            socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+        socket.destroy();
+    });
+    return handle;
 }