@co0ontty/wand 3.1.1 → 4.0.0

package/dist/server.js

@@ -2,31 +2,35 @@ import crypto from "node:crypto";
 import { compareApkInstallOrder, compareSemver, extractSemver } from "./version-utils.js";
 import compression from "compression";
 import express from "express";
-import { createReadStream, existsSync, readFileSync, writeFileSync } from "node:fs";
-import { lstat, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readdir, readFile, stat } from "node:fs/promises";
 import { createServer as createHttpServer } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
-import { exec, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import os from "node:os";
-import { promisify } from "node:util";
 import path from "node:path";
 import process from "node:process";
 import { WebSocketServer } from "ws";
-import { createSession, readSessionCookie, revokeSession, SESSION_COOKIE_HTTP, SESSION_COOKIE_HTTPS, SESSION_COOKIE_LEGACY, setAuthStorage, validateSession, } from "./auth.js";
+import { AuthService, BROWSER_ADMIN_PRINCIPAL, CONNECTED_APP_PRINCIPAL, principalHasScope, readSessionCookie, SESSION_COOKIE_HTTP, SESSION_COOKIE_HTTPS, SESSION_COOKIE_LEGACY, } from "./auth.js";
 import { ensureCertificates } from "./cert.js";
-import { buildChildEnv } from "./env-utils.js";
-import { getDefaultModelForProvider, getProviderDefaultModels, isExecutionMode, normalizeMode, PREFERENCE_KEYS, resolveConfigDir, saveConfig, writePreferenceToStorage, } from "./config.js";
-import { getCachedModels, refreshModels } from "./models.js";
+import { getDefaultModelForProvider, getProviderDefaultModels, isExecutionMode, resolveConfigDir, } from "./config.js";
+import { refreshModels } from "./models.js";
 import { ProcessManager } from "./process-manager.js";
 import { SessionLogger } from "./session-logger.js";
+import { SessionRegistry } from "./session-registry.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
+import { recordRecentPath, registerFileRoutes } from "./server-file-routes.js";
+import { registerSettingsRoutes } from "./server-settings-routes.js";
+import { refreshProviderCliUpdateState, registerAdminUpdateRoutes, registerPublicUpdateRoutes, ServerUpdateState, } from "./server-update-routes.js";
 import { parseSessionCreationOrigin, registerClaudeHistoryRoutes, registerSessionRoutes } from "./server-session-routes.js";
 import { getErrorMessage } from "./error-utils.js";
+import { asyncRoute, jsonErrorHandler } from "./express-async.js";
 import { checkPackageUpdateAsync, installPackageGloballyAsync, normalizeUpdateChannel, resolveGlobalWandCli, } from "./npm-update-utils.js";
 import { repairServiceUnitAfterUpdate } from "./service-self-repair.js";
 import { computeRelaunch } from "./relaunch.js";
+import { RuntimeConfigState } from "./runtime-config.js";
 import { isServiceInstalled } from "./tui/commands.js";
-import { canUseDetachedUpdateHelper, checkManagedServiceUpdatePreflight, startDetachedUpdateHelper, } from "./update-helper.js";
+import { checkManagedServiceUpdatePreflight, } from "./update-helper.js";
 import { registerUploadRoutes } from "./upload-routes.js";
 import { optimizePrompt, PromptOptimizeError } from "./prompt-optimizer.js";
 import { resolveDatabasePath, WandStorage } from "./storage.js";
@@ -37,9 +41,7 @@ import { EMBEDDED_WEB_ASSETS } from "./web-ui/embedded-assets.js";
 import { renderApp } from "./web-ui/index.js";
 import { WsBroadcastManager } from "./ws-broadcast.js";
 import { checkRateLimit, recordFailedLogin, resetRateLimit } from "./middleware/rate-limit.js";
-import { isPathWithinBase, isBlockedFolderPath, normalizeFolderPath } from "./middleware/path-safety.js";
-import { checkProviderCliUpdates, updateProviderClis, verifyProviderCliUpdateResults, } from "./provider-cli-updater.js";
-const execAsync = promisify(exec);
+import { updateProviderClis, verifyProviderCliUpdateResults, } from "./provider-cli-updater.js";
 const SERVER_MODULE_DIR = path.dirname(new URL(import.meta.url).pathname);
 const RUNTIME_ROOT_DIR = path.resolve(SERVER_MODULE_DIR, "..");
 // ── Package info ──
@@ -359,103 +361,83 @@ async function buildStructuredChatPersonaPayload(configPath, config) {
         return undefined;
     return { user, assistant };
 }
-// ── Git helpers ──
-async function getGitRepoRoot(dirPath) {
-    try {
-        const { stdout } = await execAsync("git rev-parse --show-toplevel", { cwd: dirPath });
-        return stdout.trim();
-    }
-    catch {
-        return null;
-    }
-}
-async function getGitStatusMap(gitRoot) {
-    const statusMap = new Map();
-    try {
-        const { stdout: stagedStdout } = await execAsync("git status --porcelain -uno", { cwd: gitRoot });
-        const { stdout: untrackedStdout } = await execAsync("git ls-files --others --exclude-standard", { cwd: gitRoot });
-        const lines = stagedStdout.split("\n").filter((line) => line.trim());
-        for (const line of lines) {
-            if (line.length < 4)
-                continue;
-            const stagedChar = line[0];
-            const unstagedChar = line[1];
-            const filePath = line.slice(3).trim();
-            if (!filePath)
-                continue;
-            const status = {};
-            if (stagedChar === "M")
-                status.staged = "modified";
-            else if (stagedChar === "A")
-                status.staged = "added";
-            else if (stagedChar === "D")
-                status.staged = "deleted";
-            else if (stagedChar === "R")
-                status.staged = "renamed";
-            if (unstagedChar === "M")
-                status.unstaged = "modified";
-            else if (unstagedChar === "D")
-                status.unstaged = "deleted";
-            statusMap.set(filePath, status);
-        }
-        const untrackedFiles = untrackedStdout.split("\n").filter((line) => line.trim());
-        for (const filePath of untrackedFiles) {
-            const existing = statusMap.get(filePath);
-            if (existing) {
-                existing.untracked = true;
-            }
-            else {
-                statusMap.set(filePath, { untracked: true });
-            }
-        }
-        return statusMap;
-    }
-    catch {
-        return statusMap;
-    }
-}
-async function enrichWithGitStatus(items, dirPath) {
-    try {
-        const gitRoot = await getGitRepoRoot(dirPath);
-        if (!gitRoot)
-            return items;
-        const gitStatusMap = await getGitStatusMap(gitRoot);
-        return items.map((item) => {
-            const relativePath = path.relative(gitRoot, item.path);
-            const normalizedPath = relativePath.replace(/\\/g, "/");
-            const gitStatus = gitStatusMap.get(normalizedPath);
-            return { ...item, gitStatus: gitStatus || undefined };
-        });
-    }
-    catch {
-        return items;
-    }
-}
 // ── Auth helpers ──
-function buildRequireAuth(useHttps, storage, config) {
+const requestPrincipals = new WeakMap();
+function buildRequireAuth(useHttps, storage, config, authService) {
     return function requireAuth(req, res, next) {
-        if (!validateSession(readSessionCookie(req, useHttps)) && !validateBearerAppToken(req, storage, config)) {
+        const principal = authService.authenticateSession(readSessionCookie(req, useHttps))
+            ?? authenticateBearerAppToken(req, storage, config);
+        if (!principal) {
+            res.status(401).json({ error: "未授权，请先登录。" });
+            return;
+        }
+        requestPrincipals.set(req, principal);
+        next();
+    };
+}
+function buildRequireScope(scope) {
+    return function requireScope(req, res, next) {
+        const principal = requestPrincipals.get(req);
+        if (!principal) {
             res.status(401).json({ error: "未授权，请先登录。" });
             return;
         }
+        if (!principalHasScope(principal, scope)) {
+            res.status(403).json({ error: "当前连接没有执行此操作的权限。" });
+            return;
+        }
         next();
     };
 }
+const CONNECTED_APP_PREFERENCE_KEYS = new Set([
+    "defaultMode",
+    "defaultModel",
+    "defaultCodexModel",
+    "defaultOpenCodeModel",
+    "defaultModels",
+    "defaultThinkingEffort",
+    "defaultProvider",
+    "defaultSessionKind",
+]);
+function requireAdminOrSessionPreferences(req, res, next) {
+    const principal = requestPrincipals.get(req);
+    if (!principal) {
+        res.status(401).json({ error: "未授权，请先登录。" });
+        return;
+    }
+    if (principalHasScope(principal, "admin")) {
+        next();
+        return;
+    }
+    const body = req.body && typeof req.body === "object" && !Array.isArray(req.body)
+        ? req.body
+        : {};
+    const keys = Object.keys(body);
+    if (!principalHasScope(principal, "session-preferences")
+        || keys.length === 0
+        || keys.some((key) => !CONNECTED_APP_PREFERENCE_KEYS.has(key))) {
+        res.status(403).json({ error: "当前连接只能修改新会话默认偏好。" });
+        return;
+    }
+    next();
+}
 function getEffectivePassword(storage, config) {
     return storage.getPassword() ?? config.password;
 }
-function validateBearerAppToken(req, storage, config) {
+function authenticateBearerAppToken(req, storage, config) {
     const header = firstHeaderValue(req.headers.authorization);
     if (!header?.startsWith("Bearer "))
-        return false;
+        return null;
     const token = header.slice("Bearer ".length).trim();
     if (!token)
-        return false;
+        return null;
     try {
-        return verifyAppToken(token, getEffectivePassword(storage, config), config.appSecret ?? "");
+        return verifyAppToken(token, getEffectivePassword(storage, config), config.appSecret ?? "")
+            ? { ...CONNECTED_APP_PRINCIPAL, scopes: [...CONNECTED_APP_PRINCIPAL.scopes] }
+            : null;
     }
     catch {
-        return false;
+        return null;
     }
 }
 function appTokenLoginPayload(storage, config) {
@@ -780,29 +762,6 @@ async function resolveMacosDmgAsset(configDir, config, configPath) {
         source: "local",
     };
 }
-async function listPathSuggestions(input, fallbackCwd) {
-    const normalizedInput = input.trim();
-    const baseInput = normalizedInput || fallbackCwd;
-    const resolvedInput = normalizeFolderPath(baseInput);
-    const endsWithSeparator = /[\\/]$/.test(normalizedInput);
-    let searchDir = resolvedInput;
-    let partialName = "";
-    if (!endsWithSeparator) {
-        searchDir = path.dirname(resolvedInput);
-        partialName = path.basename(resolvedInput);
-    }
-    const entries = await readdir(searchDir, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory())
-        .filter((entry) => !partialName || entry.name.toLowerCase().startsWith(partialName.toLowerCase()))
-        .sort((a, b) => a.name.localeCompare(b.name))
-        .slice(0, 8)
-        .map((entry) => ({
-        path: path.join(searchDir, entry.name),
-        name: entry.name,
-        isDirectory: true,
-    }));
-}
 // ── Startup error handling ──
 process.on("uncaughtException", (err) => {
     wandError("服务器异常", err.message, "请检查配置是否正确，或尝试重启服务。");
@@ -835,218 +794,6 @@ function wandWarn(message, hint) {
     if (hint)
         process.stderr.write(`  提示：${hint}\n`);
 }
-function parseStoredPathList(raw) {
-    if (!raw)
-        return [];
-    try {
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) ? parsed : [];
-    }
-    catch {
-        return [];
-    }
-}
-const MAX_RECENT_PATHS = 10;
-/** Persist a cwd to recent paths. Used by both REST and session creation hooks. */
-export function recordRecentPath(storage, cwd) {
-    if (!cwd)
-        return;
-    const trimmed = cwd.trim();
-    if (!trimmed)
-        return;
-    let resolved;
-    try {
-        resolved = normalizeFolderPath(trimmed);
-    }
-    catch {
-        return;
-    }
-    if (isBlockedFolderPath(resolved))
-        return;
-    const stored = storage.getConfigValue("recent_paths");
-    let recent = parseStoredPathList(stored);
-    recent = recent.filter((r) => normalizeFolderPath(r.path) !== resolved);
-    recent.unshift({
-        path: resolved,
-        name: path.basename(resolved),
-        lastUsedAt: new Date().toISOString(),
-    });
-    recent = recent.slice(0, MAX_RECENT_PATHS);
-    storage.setConfigValue("recent_paths", JSON.stringify(recent));
-}
-// ── File language detection ──
-function getLanguageFromExt(ext, filePath) {
-    const map = {
-        ".ts": "typescript", ".tsx": "tsx", ".js": "javascript", ".jsx": "jsx",
-        ".json": "json", ".html": "html", ".htm": "html",
-        ".css": "css", ".scss": "scss", ".less": "less",
-        ".py": "python", ".rb": "ruby", ".go": "go", ".rs": "rust",
-        ".java": "java", ".c": "c", ".cpp": "cpp", ".h": "c", ".hpp": "cpp",
-        ".cs": "csharp", ".swift": "swift", ".kt": "kotlin", ".scala": "scala",
-        ".php": "php", ".sh": "bash", ".bash": "bash", ".zsh": "bash",
-        ".yaml": "yaml", ".yml": "yaml", ".toml": "toml", ".ini": "ini",
-        ".xml": "xml", ".sql": "sql", ".graphql": "graphql",
-        ".md": "markdown", ".markdown": "markdown", ".mdown": "markdown",
-        ".mkd": "markdown", ".mkdn": "markdown",
-        ".dockerfile": "dockerfile", ".gitignore": "plaintext",
-        ".diff": "diff", ".patch": "diff", ".proto": "protobuf",
-        ".env": "bash", ".editorconfig": "ini",
-        ".mdx": "markdown", ".vue": "html", ".svelte": "html",
-    };
-    const baseName = path.basename(filePath).toLowerCase();
-    if (baseName === "dockerfile")
-        return "dockerfile";
-    if (baseName === ".gitignore")
-        return "plaintext";
-    return map[ext] || "plaintext";
-}
-// ── File preview classification ──
-const TEXT_PREVIEWABLE_EXTS = new Set([
-    ".md", ".markdown", ".mdown", ".mkd", ".mkdn", ".mdx",
-    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
-    ".json", ".jsonc", ".html", ".htm", ".css", ".scss", ".less",
-    ".py", ".rb", ".go", ".rs", ".java", ".c", ".cpp", ".h", ".hpp",
-    ".cs", ".swift", ".kt", ".scala", ".php", ".sh", ".bash", ".zsh", ".fish",
-    ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", ".env",
-    ".xml", ".sql", ".graphql", ".proto",
-    ".dockerfile", ".gitignore", ".editorconfig",
-    ".vue", ".svelte",
-    ".txt", ".log", ".diff", ".patch",
-    ".lua", ".r", ".dart", ".pl", ".pm",
-]);
-const IMAGE_EXTS = new Set([
-    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif",
-    ".bmp", ".ico", ".heic", ".heif",
-]);
-const VIDEO_EXTS = new Set([
-    ".mp4", ".webm", ".mov", ".mkv", ".m4v", ".ogv",
-]);
-const AUDIO_EXTS = new Set([
-    ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".opus",
-]);
-const PDF_EXTS = new Set([".pdf"]);
-const MIME_BY_EXT = {
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-    ".svg": "image/svg+xml",
-    ".avif": "image/avif",
-    ".bmp": "image/bmp",
-    ".ico": "image/x-icon",
-    ".heic": "image/heic",
-    ".heif": "image/heif",
-    ".pdf": "application/pdf",
-    ".mp4": "video/mp4",
-    ".webm": "video/webm",
-    ".mov": "video/quicktime",
-    ".mkv": "video/x-matroska",
-    ".m4v": "video/x-m4v",
-    ".ogv": "video/ogg",
-    ".mp3": "audio/mpeg",
-    ".wav": "audio/wav",
-    ".ogg": "audio/ogg",
-    ".m4a": "audio/mp4",
-    ".flac": "audio/flac",
-    ".aac": "audio/aac",
-    ".opus": "audio/opus",
-};
-const TEXT_BASENAME_ALLOW = new Set([
-    "dockerfile", ".gitignore", ".dockerignore", ".env", ".env.local",
-    ".env.development", ".env.production", ".env.test",
-    "makefile", "readme", "license", "changelog",
-]);
-function classifyFile(ext, baseName) {
-    const lowerExt = ext.toLowerCase();
-    const lowerBase = baseName.toLowerCase();
-    if (IMAGE_EXTS.has(lowerExt))
-        return "image";
-    if (PDF_EXTS.has(lowerExt))
-        return "pdf";
-    if (VIDEO_EXTS.has(lowerExt))
-        return "video";
-    if (AUDIO_EXTS.has(lowerExt))
-        return "audio";
-    if (TEXT_PREVIEWABLE_EXTS.has(lowerExt))
-        return "text";
-    if (TEXT_BASENAME_ALLOW.has(lowerBase))
-        return "text";
-    // Files with no extension that look like text-y dotfiles
-    if (lowerExt === "" && /^[a-z0-9._-]+$/i.test(lowerBase))
-        return "text";
-    return "binary";
-}
-function mimeForExt(ext) {
-    return MIME_BY_EXT[ext.toLowerCase()] || "application/octet-stream";
-}
-function parseByteRange(rangeHeader, total) {
-    if (!rangeHeader)
-        return null;
-    const trimmed = rangeHeader.trim();
-    if (!trimmed.startsWith("bytes="))
-        return null;
-    const match = /^bytes=(\d*)-(\d*)$/.exec(trimmed);
-    if (!match || (match[1] === "" && match[2] === ""))
-        return "invalid";
-    let start;
-    let end;
-    if (match[1] === "") {
-        const suffixLength = Number(match[2]);
-        if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0)
-            return "invalid";
-        start = Math.max(0, total - suffixLength);
-        end = total - 1;
-    }
-    else {
-        start = Number(match[1]);
-        end = match[2] === "" ? total - 1 : Math.min(Number(match[2]), total - 1);
-    }
-    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || start > end || start >= total) {
-        return "invalid";
-    }
-    return { start, end };
-}
-function streamFileWithRange(req, res, options) {
-    res.setHeader("Content-Type", options.contentType);
-    if (options.disposition)
-        res.setHeader("Content-Disposition", options.disposition);
-    for (const [name, value] of Object.entries(options.headers ?? {})) {
-        res.setHeader(name, value);
-    }
-    res.setHeader("Accept-Ranges", "bytes");
-    if (options.size === 0) {
-        if (req.headers.range?.trim().startsWith("bytes=")) {
-            res.status(416).setHeader("Content-Range", "bytes */0").end();
-            return;
-        }
-        res.setHeader("Content-Length", "0");
-        res.end();
-        return;
-    }
-    const parsedRange = parseByteRange(req.headers.range, options.size);
-    if (parsedRange === "invalid") {
-        res.status(416).setHeader("Content-Range", `bytes */${options.size}`).end();
-        return;
-    }
-    const start = parsedRange?.start ?? 0;
-    const end = parsedRange?.end ?? options.size - 1;
-    if (parsedRange) {
-        res.status(206);
-        res.setHeader("Content-Range", `bytes ${start}-${end}/${options.size}`);
-    }
-    res.setHeader("Content-Length", String(end - start + 1));
-    const stream = createReadStream(options.filePath, { start, end });
-    stream.on("error", (err) => {
-        if (!res.headersSent) {
-            res.status(500).json({ error: getErrorMessage(err, options.readErrorMessage ?? "读取文件失败。") });
-        }
-        else {
-            res.destroy();
-        }
-    });
-    stream.pipe(res);
-}
 export class PortInUseError extends Error {
     port;
     host;
@@ -1064,7 +811,7 @@ export function isPortInUseError(error) {
             && typeof error === "object"
             && error.code === "EADDRINUSE");
 }
-export async function startServer(config, configPath) {
+export async function startServer(config, configPath, options = {}) {
     // 关键：在创建 ProcessManager / 任何 spawn 之前先修 PATH。
     // 服务被注册为 systemd / launchd 时，unit 文件里的 PATH 是安装那一刻烧死的，
     // 之后用户切 node 版本 / 重装 wand / 把 claude 装到新位置都不会更新 unit，
@@ -1087,27 +834,57 @@ export async function startServer(config, configPath) {
         process.stdout.write(`[wand] ${formatPathRepairSummary(pathRepair)}\n`);
     }
     const app = express();
+    let shuttingDown = false;
     app.set("trust proxy", "loopback, 172.16.0.0/12");
     const storage = new WandStorage(resolveDatabasePath(configPath));
-    setAuthStorage(storage);
+    const runtimeConfig = new RuntimeConfigState(config);
+    const authService = new AuthService(storage);
+    const getModelRefreshOptions = () => {
+        const injected = options.modelRefreshOptions?.() ?? {};
+        return {
+            storage,
+            inheritEnv: config.inheritEnv !== false,
+            apiKey: process.env.ANTHROPIC_API_KEY,
+            ...injected,
+            configuredClaudeModels: [
+                getProviderDefaultModels(config).claude,
+                config.commitCli === "claude" ? config.commitModel : undefined,
+                ...(injected.configuredClaudeModels ?? []),
+            ],
+        };
+    };
     const configDir = resolveConfigDir(configPath);
     const processes = new ProcessManager(config, storage, configDir);
     const structuredLogger = new SessionLogger(configDir, config.shortcutLogMaxBytes);
     const structuredSessions = new StructuredSessionManager(storage, config, structuredLogger);
-    let providerCliUpdateCache = null;
-    let providerCliUpdateInFlight = false;
-    let updateInFlight = false;
+    const sessionRegistry = new SessionRegistry(processes, structuredSessions, storage);
+    const updateState = new ServerUpdateState();
+    const getUpdateChannel = () => normalizeUpdateChannel(storage.getConfigValue("updateChannel"));
+    let disconnectAuthenticatedSockets = () => { };
     const refreshProviderCliUpdates = async () => {
-        const items = await checkProviderCliUpdates({ inheritEnv: config.inheritEnv !== false });
-        const result = { items, checkedAt: new Date().toISOString() };
-        providerCliUpdateCache = result;
-        return result;
+        return refreshProviderCliUpdateState(updateState, config);
     };
     const useHttps = config.https === true;
     const protocol = useHttps ? "https" : "http";
-    const requireAuth = buildRequireAuth(useHttps, storage, config);
+    const requireAuth = buildRequireAuth(useHttps, storage, config, authService);
+    const requireAdmin = buildRequireScope("admin");
+    const requireSessions = buildRequireScope("sessions");
+    const requireFiles = buildRequireScope("files");
+    const requirePasswordVault = buildRequireScope("password-vault");
+    // Route-specific parsers must run before the global parser. Once body-parser
+    // has consumed a request, a later express.json() cannot tighten or widen it.
+    app.use("/api/optimize-prompt", express.json({ limit: "256kb" }));
+    app.use("/api/file-write", express.json({ limit: "2mb" }));
     app.use(express.json({ limit: "1mb" }));
     app.use(compression({ threshold: 1024 }));
+    app.use((_req, res, next) => {
+        if (!shuttingDown) {
+            next();
+            return;
+        }
+        res.setHeader("Connection", "close");
+        res.status(503).json({ error: "Server is shutting down." });
+    });
     app.use((req, res, next) => {
         const origin = firstHeaderValue(req.headers.origin);
         if (origin && isBrowserExtensionOrigin(origin)) {
@@ -1136,7 +913,7 @@ export async function startServer(config, configPath) {
         res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
         res.type("html").send(renderApp(configPath));
     });
-    app.get("/api/structured-chat-avatar/:role", async (req, res) => {
+    app.get("/api/structured-chat-avatar/:role", asyncRoute(async (req, res) => {
         const role = req.params.role === "user" || req.params.role === "assistant"
             ? req.params.role
             : null;
@@ -1179,7 +956,7 @@ export async function startServer(config, configPath) {
         catch {
             res.status(404).end();
         }
-    });
+    }));
     // ── Auth routes ──
     app.post("/api/login", (req, res) => {
         const clientIp = req.ip || req.socket.remoteAddress || "unknown";
@@ -1189,26 +966,29 @@ export async function startServer(config, configPath) {
         }
         const { password, appToken, client } = req.body;
         const effectivePassword = getEffectivePassword(storage, config);
-        // App token login — derived from password, so password change invalidates it
-        let authenticated = false;
+        // App token login is intentionally restricted even though the token remains
+        // password-derived for compatibility with existing connect codes.
+        let principal = null;
         if (appToken) {
             try {
-                authenticated = verifyAppToken(appToken, effectivePassword, config.appSecret ?? "");
+                if (verifyAppToken(appToken, effectivePassword, config.appSecret ?? "")) {
+                    principal = { ...CONNECTED_APP_PRINCIPAL, scopes: [...CONNECTED_APP_PRINCIPAL.scopes] };
+                }
             }
             catch {
-                authenticated = false;
+                principal = null;
             }
         }
-        if (!authenticated) {
+        if (!principal) {
             if (password !== effectivePassword) {
                 recordFailedLogin(clientIp);
                 res.status(401).json({ error: "密码错误，请重试。" });
                 return;
             }
-            authenticated = true;
+            principal = { ...BROWSER_ADMIN_PRINCIPAL, scopes: [...BROWSER_ADMIN_PRINCIPAL.scopes] };
         }
         resetRateLimit(clientIp);
-        const token = createSession();
+        const token = authService.createSession(principal);
         const cookieOpts = {
             httpOnly: true,
             sameSite: "strict",
@@ -1231,117 +1011,70 @@ export async function startServer(config, configPath) {
         }
         res.json({
             ok: true,
+            principal,
             ...(client === "browser-extension" ? appTokenLoginPayload(storage, config) : {}),
         });
     });
     app.post("/api/logout", (req, res) => {
-        revokeSession(readSessionCookie(req, useHttps));
+        authService.revokeSession(readSessionCookie(req, useHttps));
         // 全部名字都清一遍，避免遗留 cookie 在下次同源访问时被回放。
         for (const name of [SESSION_COOKIE_HTTPS, SESSION_COOKIE_HTTP, SESSION_COOKIE_LEGACY]) {
             res.clearCookie(name, { path: "/" });
         }
         res.json({ ok: true });
     });
-    app.post("/api/set-password", requireAuth, (req, res) => {
+    app.post("/api/set-password", requireAuth, requireAdmin, (req, res) => {
         const { password } = req.body;
         if (!password || password.length < 6) {
             res.status(400).json({ error: "密码长度至少为 6 个字符。" });
             return;
         }
         storage.setPassword(password);
-        res.json({ ok: true });
-    });
-    // ── Android APK update & download (no auth required) ──
-    app.get("/api/android-apk-update", async (req, res) => {
-        const currentVersion = req.query.currentVersion?.trim();
-        if (!currentVersion) {
-            res.status(400).json({ error: "Missing currentVersion query parameter." });
-            return;
-        }
-        // 更新通道：beta 包含 -debug.* 构建，stable（默认，含不传参的老客户端）只推正式版。
-        const channel = parseApkChannel(req.query.channel);
-        const latest = await resolveLatestApkVersion(configDir, config, channel, configPath);
-        if (!latest) {
-            res.json({ updateAvailable: false, currentVersion, latestVersion: null, downloadUrl: null, source: null, channel });
-            return;
-        }
-        // 安装序比较（镜像 versionCode），不是标准 semver：只在系统安装器真能装上时才提示，
-        // 避免「提示升级 → 下载 → 被按降级拒装」的死循环（如已装 1.55.0-debug 提示装 1.55.0）。
-        const updateAvailable = compareApkInstallOrder(latest.version, currentVersion) > 0;
-        res.json({
-            updateAvailable,
-            currentVersion,
-            latestVersion: latest.version,
-            downloadUrl: updateAvailable ? latest.downloadUrl : null,
-            fileName: updateAvailable ? latest.fileName : null,
-            size: updateAvailable ? latest.size : null,
-            source: latest.source,
-            channel,
-            releaseNotes: updateAvailable ? (latest.releaseNotes ?? null) : null,
-        });
-    });
-    app.get("/android/download", async (req, res) => {
-        // 更新弹窗的下载链接由 /api/android-apk-update 按通道生成（始终带 ?channel=）。
-        // 裸 /android/download（网页下载页、二维码落地页）不带参时默认 beta ——
-        // 保持「下载页拿到的就是目录里真正最新的包」的旧行为。
-        const channel = req.query.channel === "stable" ? "stable" : "beta";
-        const androidApk = await resolveAndroidApkAsset(configDir, config, channel, configPath);
-        if (!androidApk) {
-            res.status(404).json({ error: "当前没有可下载的 APK 文件。" });
-            return;
-        }
-        streamFileWithRange(req, res, {
-            filePath: androidApk.filePath,
-            size: androidApk.size,
-            contentType: "application/vnd.android.package-archive",
-            disposition: `attachment; filename="${encodeURIComponent(androidApk.fileName)}"`,
-            readErrorMessage: "读取 APK 文件失败。",
-        });
-    });
-    // ── macOS DMG update & download (no auth required) ──
-    app.get("/api/macos-dmg-update", async (req, res) => {
-        const currentVersion = req.query.currentVersion?.trim();
-        if (!currentVersion) {
-            res.status(400).json({ error: "Missing currentVersion query parameter." });
-            return;
-        }
-        const latest = await resolveLatestDmgVersion(configDir, config, configPath);
-        if (!latest) {
-            res.json({ updateAvailable: false, currentVersion, latestVersion: null, downloadUrl: null, source: null });
-            return;
+        authService.revokeAllSessions();
+        disconnectAuthenticatedSockets();
+        for (const name of [SESSION_COOKIE_HTTPS, SESSION_COOKIE_HTTP, SESSION_COOKIE_LEGACY]) {
+            res.clearCookie(name, { path: "/" });
         }
-        const updateAvailable = compareSemver(latest.version, currentVersion) > 0;
-        res.json({
-            updateAvailable,
-            currentVersion,
-            latestVersion: latest.version,
-            downloadUrl: updateAvailable ? latest.downloadUrl : null,
-            fileName: updateAvailable ? latest.fileName : null,
-            size: updateAvailable ? latest.size : null,
-            source: latest.source,
-        });
+        res.json({ ok: true, reauthenticationRequired: true });
     });
-    app.get("/macos/download", async (req, res) => {
-        const macosDmg = await resolveMacosDmgAsset(configDir, config, configPath);
-        if (!macosDmg) {
-            res.status(404).json({ error: "当前没有可下载的 DMG 文件。" });
-            return;
-        }
-        streamFileWithRange(req, res, {
-            filePath: macosDmg.filePath,
-            size: macosDmg.size,
-            contentType: "application/x-apple-diskimage",
-            disposition: `attachment; filename="${encodeURIComponent(macosDmg.fileName)}"`,
-            readErrorMessage: "读取 DMG 文件失败。",
-        });
+    // ── Android APK update & download (no auth required) ──
+    registerPublicUpdateRoutes(app, {
+        resolveLatestApk: (channel) => resolveLatestApkVersion(configDir, config, channel, configPath),
+        resolveAndroidDownload: (channel) => resolveAndroidApkAsset(configDir, config, channel, configPath),
+        resolveLatestDmg: () => resolveLatestDmgVersion(configDir, config, configPath),
+        resolveMacosDownload: () => resolveMacosDmgAsset(configDir, config, configPath),
     });
     // Public probe so the unauthenticated browser does not log a 401 on /api/config
     app.get("/api/session-check", (req, res) => {
-        res.json({ authed: validateSession(readSessionCookie(req, useHttps)) });
+        res.json({ authed: authService.validateSession(readSessionCookie(req, useHttps)) });
     });
     app.use("/api", requireAuth);
+    // Connected apps receive only the route families used by native clients and
+    // the browser extension. Browser-admin sessions implicitly satisfy all scopes.
+    app.use([
+        "/api/config",
+        "/api/models",
+        "/api/sessions",
+        "/api/structured-sessions",
+        "/api/commands",
+        "/api/claude-history",
+        "/api/codex-history",
+        "/api/claude-sessions",
+        "/api/codex-sessions",
+        "/api/optimize-prompt",
+    ], requireSessions);
+    app.use([
+        "/api/directory",
+        "/api/folders",
+        "/api/path-suggestions",
+        "/api/recent-paths",
+        "/api/file-preview",
+        "/api/file-raw",
+        "/api/file-write",
+    ], requireFiles);
+    app.use("/api/browser-extension", requirePasswordVault);
     // ── Config & Session info ──
-    app.get("/api/config", async (_req, res) => {
+    app.get("/api/config", asyncRoute(async (_req, res) => {
         const structuredChatPersona = await buildStructuredChatPersonaPayload(configPath, config);
         const defaultModels = getProviderDefaultModels(config);
         res.json({
@@ -1375,7 +1108,7 @@ export async function startServer(config, configPath) {
             packageVersion: PKG_VERSION,
             serverInstanceId: SERVER_INSTANCE_ID,
         });
-    });
+    }));
     // ── Browser extension password vault endpoints ──
     app.get("/api/browser-extension/status", (_req, res) => {
         res.json({
@@ -1490,17 +1223,10 @@ export async function startServer(config, configPath) {
         res.json({ report: buildPasswordSecurityReport(storage.listPasswordItems({ includeArchived: false, limit: 200 })) });
     });
     // ── Settings endpoints ──
-    app.get("/api/settings", async (_req, res) => {
-        const certPaths = {
-            keyPath: path.join(configDir, "server.key"),
-            certPath: path.join(configDir, "server.crt"),
-        };
-        const { password: _pw, ...safeConfig } = config;
-        const defaultModels = getProviderDefaultModels(config);
+    const getDistributionSettings = async () => {
         const localApk = await resolveAndroidApkAsset(configDir, config, "beta", configPath);
         const ghApk = await fetchGitHubLatestApk();
         const apkDir = resolveAndroidApkDir(configDir, config);
-        // Backward-compatible: pick best available for hasApk/version/downloadUrl
         const resolvedApk = localApk
             ? { hasApk: true, fileName: localApk.fileName, version: localApk.version, size: localApk.size, updatedAt: localApk.updatedAt, downloadUrl: localApk.downloadUrl, source: "local" }
             : ghApk
@@ -1514,34 +1240,7 @@ export async function startServer(config, configPath) {
             : ghDmg
                 ? { hasDmg: true, fileName: ghDmg.fileName, version: ghDmg.version, size: ghDmg.size, updatedAt: null, downloadUrl: ghDmg.downloadUrl, source: "github" }
                 : null;
-        res.json({
-            version: DISPLAY_VERSION,
-            packageName: PKG_NAME,
-            nodeVersion: PKG_NODE_REQ,
-            repoUrl: PKG_REPO_URL,
-            config: {
-                ...safeConfig,
-                defaultModel: defaultModels.claude,
-                defaultCodexModel: defaultModels.codex,
-                defaultOpenCodeModel: defaultModels.opencode,
-                defaultModels,
-            },
-            hasCert: existsSync(certPaths.keyPath) && existsSync(certPaths.certPath),
-            updateAvailable: cachedUpdateInfo?.updateAvailable ?? false,
-            latestVersion: cachedUpdateInfo?.latest ?? null,
-            updateChannel: getUpdateChannel(),
-            build: {
-                commit: BUILD_INFO.commit,
-                shortCommit: BUILD_INFO.commit ? BUILD_INFO.commit.slice(0, 7) : null,
-                builtAt: BUILD_INFO.builtAt,
-                channel: BUILD_INFO.channel,
-            },
-            autoUpdate: {
-                web: storage.getConfigValue("autoUpdateWeb") === "true",
-                apk: storage.getConfigValue("autoUpdateApk") === "true",
-                dmg: storage.getConfigValue("autoUpdateDmg") === "true",
-                cli: storage.getConfigValue("autoUpdateProviderClis") === "true",
-            },
+        return {
             androidApk: {
                 enabled: config.android?.enabled === true,
                 apkDir,
@@ -1568,295 +1267,47 @@ export async function startServer(config, configPath) {
                 local: localDmg ? { fileName: localDmg.fileName, version: localDmg.version, size: localDmg.size, updatedAt: localDmg.updatedAt, downloadUrl: localDmg.downloadUrl } : null,
                 github: ghDmg ? { fileName: ghDmg.fileName, version: ghDmg.version, size: ghDmg.size, downloadUrl: ghDmg.downloadUrl } : null,
             },
-        });
-    });
-    app.get("/api/android-apk", async (_req, res) => {
-        const localApk = await resolveAndroidApkAsset(configDir, config, "beta", configPath);
-        const ghApk = await fetchGitHubLatestApk();
-        const apkDir = resolveAndroidApkDir(configDir, config);
-        const resolvedApk = localApk
-            ? { hasApk: true, fileName: localApk.fileName, version: localApk.version, size: localApk.size, updatedAt: localApk.updatedAt, downloadUrl: localApk.downloadUrl, source: "local" }
-            : ghApk
-                ? { hasApk: true, fileName: ghApk.fileName, version: ghApk.version, size: ghApk.size, updatedAt: null, downloadUrl: ghApk.downloadUrl, source: "github" }
-                : null;
-        res.json({
-            enabled: config.android?.enabled === true,
-            apkDir,
-            hasApk: resolvedApk?.hasApk ?? false,
-            fileName: resolvedApk?.fileName ?? null,
-            version: resolvedApk?.version ?? null,
-            size: resolvedApk?.size ?? null,
-            updatedAt: resolvedApk?.updatedAt ?? null,
-            downloadUrl: resolvedApk?.downloadUrl ?? null,
-            source: resolvedApk?.source ?? null,
-            local: localApk ? { fileName: localApk.fileName, version: localApk.version, size: localApk.size, updatedAt: localApk.updatedAt, downloadUrl: localApk.downloadUrl } : null,
-            github: ghApk ? { fileName: ghApk.fileName, version: ghApk.version, size: ghApk.size, downloadUrl: ghApk.downloadUrl } : null,
-        });
-    });
-    app.get("/api/macos-dmg", async (_req, res) => {
-        const localDmg = await resolveMacosDmgAsset(configDir, config, configPath);
-        const ghDmg = await fetchGitHubLatestDmg();
-        const dmgDir = resolveMacosDmgDir(configDir, config);
-        const resolvedDmg = localDmg
-            ? { hasDmg: true, fileName: localDmg.fileName, version: localDmg.version, size: localDmg.size, updatedAt: localDmg.updatedAt, downloadUrl: localDmg.downloadUrl, source: "local" }
-            : ghDmg
-                ? { hasDmg: true, fileName: ghDmg.fileName, version: ghDmg.version, size: ghDmg.size, updatedAt: null, downloadUrl: ghDmg.downloadUrl, source: "github" }
-                : null;
-        res.json({
-            enabled: config.macos?.enabled === true,
-            dmgDir,
-            hasDmg: resolvedDmg?.hasDmg ?? false,
-            fileName: resolvedDmg?.fileName ?? null,
-            version: resolvedDmg?.version ?? null,
-            size: resolvedDmg?.size ?? null,
-            updatedAt: resolvedDmg?.updatedAt ?? null,
-            downloadUrl: resolvedDmg?.downloadUrl ?? null,
-            source: resolvedDmg?.source ?? null,
-            local: localDmg ? { fileName: localDmg.fileName, version: localDmg.version, size: localDmg.size, updatedAt: localDmg.updatedAt, downloadUrl: localDmg.downloadUrl } : null,
-            github: ghDmg ? { fileName: ghDmg.fileName, version: ghDmg.version, size: ghDmg.size, downloadUrl: ghDmg.downloadUrl } : null,
-        });
-    });
-    // 返回当前 inheritEnv 配置下，wand 启动 PTY / 结构化子进程时实际会传给
-    // claude / codex 的环境变量集合。值会按下面的规则做掩码：
-    //   - 名字里含 KEY/TOKEN/SECRET/PASSWORD/AUTH/CREDENTIAL/COOKIE/SESSION 的视为敏感
-    //   - 敏感值默认显示为 ***（保留长度提示），可通过 ?reveal=1 取消掩码
-    // 即使开启 reveal，仍只对已认证用户可见（路由由全局 requireAuth 保护）。
-    app.get("/api/settings/env-preview", (req, res) => {
-        const inheritEnv = config.inheritEnv !== false;
-        // 复用与 process-manager / structured-session-manager 相同的组装逻辑，
-        // 这样 UI 上看到的就是真正会被注入到子进程的那一份环境。
-        const env = buildChildEnv(inheritEnv, {
-            // PTY runner 还会注入 WAND_* 用于 mode 协调，这里也展示出来便于排查。
-            WAND_MODE: "<runtime>",
-            WAND_AUTO_CONFIRM: "<runtime>",
-            WAND_AUTO_EDIT: "<runtime>",
-        });
-        const reveal = req.query.reveal === "1" || req.query.reveal === "true";
-        const SENSITIVE_PATTERN = /(KEY|TOKEN|SECRET|PASSWORD|AUTH|CREDENTIAL|COOKIE|SESSION)/i;
-        const entries = Object.keys(env)
-            .sort()
-            .map((name) => {
-            const raw = env[name] ?? "";
-            const sensitive = SENSITIVE_PATTERN.test(name);
-            const masked = sensitive && !reveal;
-            // WAND_* 占位值不算敏感，保持原样。
-            const isPlaceholder = raw.startsWith("<") && raw.endsWith(">");
-            return {
-                name,
-                value: masked && !isPlaceholder ? "***" : raw,
-                length: raw.length,
-                sensitive,
-            };
-        });
-        res.json({
-            inheritEnv,
-            total: entries.length,
-            reveal,
-            entries,
-        });
-    });
-    app.get("/api/app-connect-code", requireAuth, (req, res) => {
-        const effectivePassword = getEffectivePassword(storage, config);
-        const protocol = getPublicRequestProtocol(req, useHttps ? "https" : "http");
-        const host = getPublicRequestHost(req, config);
-        const browserOrigin = normalizePublicOrigin(firstQueryStringValue(req.query.origin));
-        const serverUrl = resolveAppConnectOrigin(browserOrigin ?? `${protocol}://${host}`, config);
-        const appSecret = config.appSecret ?? "";
-        const token = generateAppToken(effectivePassword, appSecret);
-        const code = encodeConnectCode(serverUrl, token);
-        res.json({ code, url: serverUrl });
-    });
-    app.post("/api/settings/config", async (req, res) => {
-        const body = req.body;
-        // 部署字段：写 JSON，需要重启服务才生效（host/port/https 影响监听，shell 影响新 PTY）
-        const deployFields = ["host", "port", "https", "shell"];
-        let touchedDeployField = false;
-        let touchedPreferenceField = false;
-        for (const field of deployFields) {
-            if (!(field in body) || body[field] === undefined)
-                continue;
-            if (field === "port") {
-                const p = Number(body.port);
-                if (!Number.isInteger(p) || p < 1 || p > 65535) {
-                    res.status(400).json({ error: `无效端口号: ${body.port}` });
-                    return;
-                }
-                config.port = p;
-            }
-            else if (field === "https") {
-                config.https = body.https === true;
-            }
-            else if (field === "host") {
-                config.host = String(body.host);
-            }
-            else if (field === "shell") {
-                config.shell = String(body.shell);
-            }
-            touchedDeployField = true;
-        }
-        // 偏好字段：写 SQLite app_config，立即热生效（manager 持有 config 同一引用）。
-        // defaultMode 单独做严格校验以保留 400 错误响应，其余字段走 writePreferenceToStorage 的统一类型化处理。
-        if (body.defaultMode !== undefined && !isExecutionMode(body.defaultMode)) {
-            res.status(400).json({ error: `无效执行模式: ${body.defaultMode}` });
-            return;
-        }
-        if (body.defaultModels && typeof body.defaultModels === "object") {
-            const modelDefaults = body.defaultModels;
-            try {
-                if (Object.prototype.hasOwnProperty.call(modelDefaults, "claude")) {
-                    writePreferenceToStorage(config, storage, "defaultModel", modelDefaults.claude);
-                    touchedPreferenceField = true;
-                }
-                if (Object.prototype.hasOwnProperty.call(modelDefaults, "codex")) {
-                    writePreferenceToStorage(config, storage, "defaultCodexModel", modelDefaults.codex);
-                    touchedPreferenceField = true;
-                }
-                if (Object.prototype.hasOwnProperty.call(modelDefaults, "opencode")) {
-                    writePreferenceToStorage(config, storage, "defaultOpenCodeModel", modelDefaults.opencode);
-                    touchedPreferenceField = true;
-                }
-            }
-            catch (err) {
-                res.status(400).json({ error: getErrorMessage(err, "默认模型配置校验失败") });
-                return;
-            }
-        }
-        for (const field of PREFERENCE_KEYS) {
-            if (!(field in body) || body[field] === undefined)
-                continue;
-            try {
-                writePreferenceToStorage(config, storage, field, body[field]);
-            }
-            catch (err) {
-                res.status(400).json({ error: getErrorMessage(err, `字段 ${field} 校验失败`) });
-                return;
-            }
-            touchedPreferenceField = true;
-        }
-        if (!touchedDeployField && !touchedPreferenceField) {
-            res.status(400).json({ error: "没有可更新的配置字段。" });
-            return;
-        }
-        try {
-            if (touchedDeployField) {
-                await saveConfig(configPath, config);
-            }
-            const { password: _pw, ...safeConfig } = config;
-            const defaultModels = getProviderDefaultModels(config);
-            // 只有部署字段才需要重启；偏好字段已经热生效。
-            res.json({
-                ok: true,
-                config: {
-                    ...safeConfig,
-                    defaultModel: defaultModels.claude,
-                    defaultCodexModel: defaultModels.codex,
-                    defaultOpenCodeModel: defaultModels.opencode,
-                    defaultModels,
-                },
-                restartRequired: touchedDeployField,
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "保存配置失败。") });
-        }
-    });
-    app.get("/api/models", (_req, res) => {
-        const cached = getCachedModels();
-        const defaultModels = getProviderDefaultModels(config);
-        res.json({
-            models: cached.models,
-            codexModels: cached.codexModels,
-            opencodeModels: cached.opencodeModels,
-            claudeVersion: cached.claudeVersion,
-            opencodeVersion: cached.opencodeVersion,
-            refreshedAt: cached.refreshedAt,
-            defaultModel: defaultModels.claude,
-            defaultCodexModel: defaultModels.codex,
-            defaultOpenCodeModel: defaultModels.opencode,
-            defaultModels,
-        });
-    });
-    app.post("/api/models/refresh", async (_req, res) => {
-        try {
-            const refreshed = await refreshModels();
-            const defaultModels = getProviderDefaultModels(config);
-            res.json({
-                models: refreshed.models,
-                codexModels: refreshed.codexModels,
-                opencodeModels: refreshed.opencodeModels,
-                claudeVersion: refreshed.claudeVersion,
-                opencodeVersion: refreshed.opencodeVersion,
-                refreshedAt: refreshed.refreshedAt,
-                defaultModel: defaultModels.claude,
-                defaultCodexModel: defaultModels.codex,
-                defaultOpenCodeModel: defaultModels.opencode,
-                defaultModels,
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "刷新模型列表失败。") });
-        }
-    });
-    app.get("/api/provider-cli-updates", async (req, res) => {
-        try {
-            const force = req.query.refresh === "1" || !providerCliUpdateCache;
-            const data = force ? await refreshProviderCliUpdates() : providerCliUpdateCache;
-            res.json({
-                ...data,
-                updating: providerCliUpdateInFlight,
-                autoUpdate: storage.getConfigValue("autoUpdateProviderClis") === "true",
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "检查 CLI 更新失败。") });
-        }
-    });
-    app.post("/api/provider-cli-updates", async (req, res) => {
-        if (providerCliUpdateInFlight || updateInFlight) {
-            res.status(409).json({ error: "CLI 更新正在进行中，请稍候。" });
-            return;
-        }
-        const rawIds = Array.isArray(req.body?.ids) ? req.body.ids : [];
-        const ids = rawIds.filter((value) => value === "claude" || value === "codex" || value === "opencode");
-        providerCliUpdateInFlight = true;
-        try {
-            const before = await refreshProviderCliUpdates();
-            const commandResults = await updateProviderClis(before.items, ids.length ? ids : undefined, {
-                inheritEnv: config.inheritEnv !== false,
-                onLog: (line) => process.stdout.write(`[wand] ${line}\n`),
-            });
-            const after = await refreshProviderCliUpdates();
-            const results = verifyProviderCliUpdateResults(commandResults, after.items);
-            refreshModels().catch(() => { });
-            res.json({ ok: results.every((item) => item.ok), results, ...after, autoUpdate: storage.getConfigValue("autoUpdateProviderClis") === "true" });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "更新 CLI 失败。") });
-        }
-        finally {
-            providerCliUpdateInFlight = false;
-        }
+        };
+    };
+    registerSettingsRoutes(app, {
+        storage,
+        config,
+        runtimeConfig,
+        configPath,
+        configDir,
+        requireAdmin,
+        requireAdminOrSessionPreferences,
+        packageInfo: { version: DISPLAY_VERSION, name: PKG_NAME, nodeVersion: PKG_NODE_REQ, repoUrl: PKG_REPO_URL },
+        buildInfo: BUILD_INFO,
+        getCachedUpdateInfo: () => cachedUpdateInfo,
+        getUpdateChannel,
+        getDistributionSettings,
+        getModelRefreshOptions,
+        resolveAppConnectCode: (req) => {
+            const effectivePassword = getEffectivePassword(storage, config);
+            const requestProtocol = getPublicRequestProtocol(req, useHttps ? "https" : "http");
+            const requestHost = getPublicRequestHost(req, config);
+            const browserOrigin = normalizePublicOrigin(firstQueryStringValue(req.query.origin));
+            const serverUrl = resolveAppConnectOrigin(browserOrigin ?? `${requestProtocol}://${requestHost}`, config);
+            const token = generateAppToken(effectivePassword, config.appSecret ?? "");
+            return { code: encodeConnectCode(serverUrl, token), url: serverUrl };
+        },
     });
-    app.post("/api/settings/upload-cert", async (req, res) => {
-        const { key, cert } = req.body;
-        if (!key || !cert) {
-            res.status(400).json({ error: "请提供 key 和 cert 内容。" });
-            return;
-        }
-        if (!key.includes("-----BEGIN") || !cert.includes("-----BEGIN")) {
-            res.status(400).json({ error: "证书内容格式无效，请上传 PEM 格式的文件。" });
-            return;
-        }
-        try {
-            const keyPath = path.join(configDir, "server.key");
-            const certPath = path.join(configDir, "server.crt");
-            writeFileSync(keyPath, key, { mode: 0o600 });
-            writeFileSync(certPath, cert, { mode: 0o644 });
-            res.json({ ok: true, restartRequired: true });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "保存证书失败。") });
-        }
+    registerAdminUpdateRoutes(app, {
+        storage,
+        config,
+        configPath,
+        requireAdmin,
+        state: updateState,
+        getDistributionSettings,
+        getModelRefreshOptions,
+        getUpdateChannel,
+        checkLatestPackageVersion,
+        buildInfo: BUILD_INFO,
+        serverInstanceId: SERVER_INSTANCE_ID,
+        emitSystemNotification: (data) => {
+            wsManager.emitEvent({ type: "notification", sessionId: "__system__", data });
+        },
     });
     // ── Global npm install (with leftover cleanup + ENOTEMPTY fallback) ──
     // 把所有恢复逻辑下沉到 ./npm-update-utils，TUI 和 server 共用，确保自动更新、
@@ -1866,92 +1317,12 @@ export async function startServer(config, configPath) {
             process.stdout.write(`${line}\n`);
         });
     }
-    /** 当前更新通道：stable（npm @latest，纯 tag）或 beta（npm @beta，tag + commit 尾标）。 */
-    const getUpdateChannel = () => normalizeUpdateChannel(storage.getConfigValue("updateChannel"));
-    app.get("/api/check-update", async (_req, res) => {
-        try {
-            const channel = getUpdateChannel();
-            const info = await checkLatestPackageVersion(channel, true);
-            res.json({
-                ...info,
-                build: {
-                    commit: BUILD_INFO.commit,
-                    shortCommit: BUILD_INFO.commit ? BUILD_INFO.commit.slice(0, 7) : null,
-                    builtAt: BUILD_INFO.builtAt,
-                    channel: BUILD_INFO.channel,
-                },
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "检查更新失败。") });
-        }
-    });
-    app.post("/api/update", async (_req, res) => {
-        if (updateInFlight || providerCliUpdateInFlight) {
-            res.status(409).json({ error: "更新正在进行中，请稍候。" });
-            return;
-        }
-        updateInFlight = true;
-        try {
-            const channel = getUpdateChannel();
-            const info = await checkLatestPackageVersion(channel, true);
-            if (!info.latest) {
-                res.status(502).json({ error: "无法连接到 npm registry。" });
-                return;
-            }
-            const targetLabel = info.latest;
-            const reinstalling = !info.updateAvailable;
-            if (!canUseDetachedUpdateHelper()) {
-                res.status(500).json({ error: "当前平台暂不支持 Web 异步更新，请在终端运行 install.sh 更新。" });
-                return;
-            }
-            const helper = startDetachedUpdateHelper({
-                installSpec: info.installSpec,
-                configPath,
-                parentPid: process.pid,
-                cliArgs: process.argv.slice(2),
-                cwd: process.cwd(),
-                env: process.env,
-                timeoutMs: 300000,
-            });
-            if (!helper.started) {
-                res.status(500).json({ error: helper.message, detail: `script=${helper.scriptPath}\nlog=${helper.logPath}` });
-                return;
-            }
-            process.stdout.write(`[wand] ${helper.message}\n`);
-            wsManager.emitEvent({
-                type: "notification",
-                sessionId: "__system__",
-                data: {
-                    kind: "auto-update-restart",
-                    current: info.current,
-                    latest: targetLabel,
-                    previousInstanceId: SERVER_INSTANCE_ID,
-                },
-            });
-            res.json({
-                ok: true,
-                message: reinstalling ? `已开始重新安装 ${targetLabel}` : `已开始更新到 ${targetLabel}`,
-                restartRequired: false,
-                detachedUpdate: true,
-                version: targetLabel,
-                previousInstanceId: SERVER_INSTANCE_ID,
-                logPath: helper.logPath,
-            });
-        }
-        catch (error) {
-            res.status(500).json({ error: getErrorMessage(error, "更新失败。") });
-        }
-        finally {
-            updateInFlight = false;
-        }
-    });
-    registerSessionRoutes(app, processes, structuredSessions, storage, config.defaultMode, config, (cwd) => {
+    registerSessionRoutes(app, processes, structuredSessions, storage, config.defaultMode, config, sessionRegistry, (cwd) => {
         recordRecentPath(storage, cwd);
     });
-    registerClaudeHistoryRoutes(app, processes, storage);
+    registerClaudeHistoryRoutes(app, processes, structuredSessions, storage, sessionRegistry);
     registerUploadRoutes(app, processes);
-    app.post("/api/optimize-prompt", express.json({ limit: "256kb" }), async (req, res) => {
+    app.post("/api/optimize-prompt", asyncRoute(async (req, res) => {
         const body = (req.body ?? {});
         const text = typeof body.text === "string" ? body.text : "";
         let cwd;
@@ -1972,425 +1343,8 @@ export async function startServer(config, configPath) {
             }
             res.status(500).json({ error: getErrorMessage(error, "提示词优化失败。") });
         }
-    });
-    // ── Path suggestion ──
-    app.get("/api/path-suggestions", async (req, res) => {
-        const query = typeof req.query.q === "string" ? req.query.q : "";
-        try {
-            const suggestions = await listPathSuggestions(query, config.defaultCwd);
-            res.json(suggestions);
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "无法加载路径建议。") });
-        }
-    });
-    // ── File browsing ──
-    const DIRECTORY_MAX_ITEMS = 200;
-    app.get("/api/directory", async (req, res) => {
-        const q = typeof req.query.q === "string" ? req.query.q : "";
-        const includeGitStatus = req.query.gitStatus === "true";
-        const targetPath = path.resolve(q || config.defaultCwd);
-        try {
-            const entries = await readdir(targetPath, { withFileTypes: true });
-            const sorted = entries.sort((a, b) => {
-                if (a.isDirectory() && !b.isDirectory())
-                    return -1;
-                if (!a.isDirectory() && b.isDirectory())
-                    return 1;
-                return a.name.localeCompare(b.name);
-            });
-            const total = sorted.length;
-            const truncated = total > DIRECTORY_MAX_ITEMS;
-            const sliced = sorted.slice(0, DIRECTORY_MAX_ITEMS);
-            // Fetch size/mtime in parallel; tolerate per-entry failures.
-            let items = await Promise.all(sliced.map(async (entry) => {
-                const fullPath = path.join(targetPath, entry.name);
-                const isDir = entry.isDirectory();
-                const base = {
-                    path: fullPath,
-                    name: entry.name,
-                    type: isDir ? "dir" : "file",
-                };
-                if (isDir)
-                    return base;
-                try {
-                    const st = await lstat(fullPath);
-                    base.size = st.size;
-                    base.mtime = st.mtime.toISOString();
-                }
-                catch {
-                    // Permission errors etc — leave size/mtime undefined.
-                }
-                return base;
-            }));
-            if (includeGitStatus) {
-                items = await enrichWithGitStatus(items, targetPath);
-            }
-            const payload = { items, truncated, total };
-            res.json(payload);
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "无法读取目录。可能原因：路径不存在或权限不足。") });
-        }
-    });
-    const MAX_TEXT_PREVIEW_SIZE = 512 * 1024;
-    app.get("/api/file-preview", async (req, res) => {
-        const filePath = typeof req.query.path === "string" ? req.query.path : "";
-        if (!filePath) {
-            res.status(400).json({ error: "Missing path parameter" });
-            return;
-        }
-        const resolvedPath = path.resolve(filePath);
-        if (isBlockedFolderPath(resolvedPath)) {
-            res.status(403).json({ error: "Access denied" });
-            return;
-        }
-        try {
-            const fileStat = await stat(resolvedPath);
-            if (fileStat.isDirectory()) {
-                res.status(400).json({ error: "Cannot preview a directory" });
-                return;
-            }
-            const ext = path.extname(filePath).toLowerCase();
-            const baseName = path.basename(filePath);
-            const kind = classifyFile(ext, baseName);
-            const mime = mimeForExt(ext);
-            // Non-text kinds: respond with metadata so the client can pick a renderer.
-            if (kind !== "text") {
-                const payload = {
-                    kind,
-                    path: resolvedPath,
-                    name: baseName,
-                    ext,
-                    size: fileStat.size,
-                    mime,
-                };
-                res.json(payload);
-                return;
-            }
-            // Text/code preview path — still subject to the 512 KB cap.
-            if (fileStat.size > MAX_TEXT_PREVIEW_SIZE) {
-                res.status(413).json({
-                    error: "文件太大，无法在线预览（限 512 KB）。",
-                    truncated: true,
-                    size: fileStat.size,
-                    maxSize: MAX_TEXT_PREVIEW_SIZE,
-                });
-                return;
-            }
-            const content = await readFile(resolvedPath, "utf-8");
-            const lang = getLanguageFromExt(ext, filePath);
-            const payload = {
-                kind: "text",
-                path: resolvedPath,
-                name: baseName,
-                ext,
-                size: fileStat.size,
-                mime,
-                lang,
-                content,
-            };
-            res.json(payload);
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "Failed to read file") });
-        }
-    });
-    // Write/overwrite a text file's content. Used by the file-preview modal's
-    // edit mode. Only text-classified files are writable, and only when the file
-    // already exists (we never create files via this endpoint to keep the surface
-    // narrow). Atomic via tmp-file + rename to avoid partial writes.
-    const MAX_TEXT_WRITE_SIZE = 1024 * 1024; // 1 MB cap for safety
-    app.post("/api/file-write", express.json({ limit: "2mb" }), async (req, res) => {
-        const body = (req.body ?? {});
-        const filePath = typeof body.path === "string" ? body.path : "";
-        const content = typeof body.content === "string" ? body.content : null;
-        if (!filePath || content === null) {
-            res.status(400).json({ error: "缺少 path 或 content 参数。" });
-            return;
-        }
-        const resolvedPath = path.resolve(filePath);
-        if (isBlockedFolderPath(resolvedPath)) {
-            res.status(403).json({ error: "访问被拒绝：无法修改系统目录下的文件。" });
-            return;
-        }
-        // Encode-size check (UTF-8 byte length, not character length).
-        const byteLength = Buffer.byteLength(content, "utf-8");
-        if (byteLength > MAX_TEXT_WRITE_SIZE) {
-            res.status(413).json({
-                error: `内容超出保存上限（${Math.round(MAX_TEXT_WRITE_SIZE / 1024)} KB）。`,
-                size: byteLength,
-                maxSize: MAX_TEXT_WRITE_SIZE,
-            });
-            return;
-        }
-        try {
-            const fileStat = await stat(resolvedPath);
-            if (fileStat.isDirectory()) {
-                res.status(400).json({ error: "目标是目录，无法写入。" });
-                return;
-            }
-            if (!fileStat.isFile()) {
-                res.status(400).json({ error: "目标不是普通文件。" });
-                return;
-            }
-            const ext = path.extname(resolvedPath).toLowerCase();
-            const baseName = path.basename(resolvedPath);
-            const kind = classifyFile(ext, baseName);
-            if (kind !== "text") {
-                res.status(415).json({ error: "仅支持编辑文本类文件。" });
-                return;
-            }
-            // Atomic write: dump to a sibling temp file, then rename.
-            const dir = path.dirname(resolvedPath);
-            const tmpPath = path.join(dir, `.${baseName}.wand-tmp-${crypto.randomBytes(6).toString("hex")}`);
-            try {
-                await writeFile(tmpPath, content, { encoding: "utf-8", mode: fileStat.mode & 0o777 });
-                await rename(tmpPath, resolvedPath);
-            }
-            catch (writeError) {
-                // Best-effort cleanup if rename failed but tmp got created.
-                try {
-                    await unlink(tmpPath);
-                }
-                catch { }
-                throw writeError;
-            }
-            const newStat = await stat(resolvedPath);
-            res.json({
-                ok: true,
-                path: resolvedPath,
-                size: newStat.size,
-                mtime: newStat.mtime.toISOString(),
-            });
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "保存文件失败。") });
-        }
-    });
-    // Streams the raw bytes of a file for inline media previews (image/PDF/video/audio)
-    // and downloads. Honors HTTP Range so video/audio scrubbing works.
-    const RAW_MAX_BYTES_BY_KIND = {
-        text: 5 * 1024 * 1024,
-        image: 50 * 1024 * 1024,
-        pdf: 50 * 1024 * 1024,
-        video: 200 * 1024 * 1024,
-        audio: 200 * 1024 * 1024,
-        binary: 50 * 1024 * 1024,
-    };
-    app.get("/api/file-raw", async (req, res) => {
-        const filePath = typeof req.query.path === "string" ? req.query.path : "";
-        const asDownload = req.query.download === "1" || req.query.download === "true";
-        if (!filePath) {
-            res.status(400).json({ error: "Missing path parameter" });
-            return;
-        }
-        const resolvedPath = path.resolve(filePath);
-        if (isBlockedFolderPath(resolvedPath)) {
-            res.status(403).json({ error: "Access denied" });
-            return;
-        }
-        try {
-            const fileStat = await stat(resolvedPath);
-            if (!fileStat.isFile()) {
-                res.status(400).json({ error: "Not a regular file" });
-                return;
-            }
-            const ext = path.extname(filePath).toLowerCase();
-            const baseName = path.basename(filePath);
-            const kind = classifyFile(ext, baseName);
-            const cap = RAW_MAX_BYTES_BY_KIND[kind] ?? RAW_MAX_BYTES_BY_KIND.binary;
-            if (fileStat.size > cap) {
-                res.status(413).json({
-                    error: `文件超出可在线预览的上限（${Math.round(cap / 1024 / 1024)} MB）。`,
-                    size: fileStat.size,
-                    maxSize: cap,
-                });
-                return;
-            }
-            const mime = mimeForExt(ext);
-            // SVG can be served with its proper type; binary fallback uses octet-stream.
-            const contentType = kind === "binary" ? "application/octet-stream" : mime;
-            // Encode the filename for Content-Disposition (RFC 5987).
-            const encodedName = encodeURIComponent(baseName);
-            const disposition = asDownload
-                ? `attachment; filename*=UTF-8''${encodedName}`
-                : `inline; filename*=UTF-8''${encodedName}`;
-            streamFileWithRange(req, res, {
-                filePath: resolvedPath,
-                size: fileStat.size,
-                contentType,
-                disposition,
-                headers: {
-                    "Cache-Control": "private, max-age=60",
-                    "X-Content-Type-Options": "nosniff",
-                },
-                readErrorMessage: "Failed to read file",
-            });
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "Failed to read file") });
-        }
-    });
-    app.get("/api/folders", async (req, res) => {
-        const q = typeof req.query.q === "string" ? req.query.q : "/tmp";
-        const targetPath = normalizeFolderPath(q);
-        if (isBlockedFolderPath(targetPath)) {
-            res.status(403).json({ error: "访问被拒绝：无法访问系统敏感目录。" });
-            return;
-        }
-        try {
-            const entries = await readdir(targetPath, { withFileTypes: true });
-            const items = [];
-            const parentPath = path.dirname(targetPath);
-            if (parentPath !== targetPath) {
-                items.push({ path: parentPath, name: "..", type: "parent", isParent: true });
-            }
-            entries
-                .filter((entry) => entry.isDirectory())
-                .sort((a, b) => a.name.localeCompare(b.name))
-                .slice(0, 100)
-                .forEach((entry) => {
-                items.push({ path: path.join(targetPath, entry.name), name: entry.name, type: "dir" });
-            });
-            res.json({ currentPath: targetPath, items });
-        }
-        catch (error) {
-            const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-            if (code === "ENOENT") {
-                res.status(404).json({ error: "路径不存在：" + q, currentPath: q, items: [] });
-            }
-            else if (code === "EACCES") {
-                res.status(403).json({ error: "权限不足，无法访问：" + q, currentPath: q, items: [] });
-            }
-            else {
-                res.status(400).json({ error: "无法读取目录：" + getErrorMessage(error, "未知错误"), currentPath: q, items: [] });
-            }
-        }
-    });
-    app.get("/api/quick-paths", async (_req, res) => {
-        const home = process.env.HOME || process.env.USERPROFILE || "/home";
-        res.json([
-            { path: "/tmp", name: "临时目录", icon: "🗑️" },
-            { path: home, name: "主目录", icon: "🏠" },
-            { path: process.cwd(), name: "当前目录", icon: "📂" },
-            { path: "/", name: "根目录", icon: "📁" },
-        ]);
-    });
-    app.get("/api/recent-paths", (_req, res) => {
-        const stored = storage.getConfigValue("recent_paths");
-        const recent = parseStoredPathList(stored);
-        res.json(recent.filter((item) => !isBlockedFolderPath(normalizeFolderPath(item.path))));
-    });
-    app.post("/api/recent-paths", (req, res) => {
-        const { path: usedPath } = req.body;
-        if (!usedPath) {
-            res.status(400).json({ error: "路径不能为空。" });
-            return;
-        }
-        const resolvedRecentPath = normalizeFolderPath(usedPath);
-        if (isBlockedFolderPath(resolvedRecentPath)) {
-            res.status(403).json({ error: "访问被拒绝：无法保存系统敏感目录。" });
-            return;
-        }
-        recordRecentPath(storage, resolvedRecentPath);
-        res.json({
-            path: resolvedRecentPath,
-            name: path.basename(resolvedRecentPath),
-            lastUsedAt: new Date().toISOString(),
-        });
-    });
-    app.get("/api/validate-path", async (req, res) => {
-        const inputPath = typeof req.query.path === "string" ? req.query.path : "";
-        if (!inputPath.trim()) {
-            res.json({ valid: false, error: "路径不能为空" });
-            return;
-        }
-        try {
-            const resolvedPath = normalizeFolderPath(inputPath);
-            if (isBlockedFolderPath(resolvedPath)) {
-                res.json({ valid: false, error: "访问被拒绝：无法访问系统敏感目录。", resolvedPath });
-                return;
-            }
-            const stats = await import("node:fs/promises").then((fs) => fs.stat(resolvedPath));
-            if (!stats.isDirectory()) {
-                res.json({ valid: false, error: "路径不是目录", resolvedPath });
-                return;
-            }
-            try {
-                await readdir(resolvedPath);
-                res.json({ valid: true, resolvedPath, name: path.basename(resolvedPath) });
-            }
-            catch {
-                res.json({ valid: false, error: "没有读取权限", resolvedPath });
-            }
-        }
-        catch (error) {
-            const err = error;
-            if (err.code === "ENOENT") {
-                res.json({ valid: false, error: "路径不存在" });
-            }
-            else if (err.code === "EACCES") {
-                res.json({ valid: false, error: "没有访问权限" });
-            }
-            else {
-                res.json({ valid: false, error: `无效路径: ${err.message}` });
-            }
-        }
-    });
-    app.get("/api/file-search", async (req, res) => {
-        const query = typeof req.query.q === "string" ? req.query.q : "";
-        const cwd = typeof req.query.cwd === "string" ? req.query.cwd : process.cwd();
-        const maxDepth = typeof req.query.depth === "string" ? parseInt(req.query.depth, 10) : 5;
-        const maxResults = typeof req.query.limit === "string" ? parseInt(req.query.limit, 10) : 50;
-        const allowedBase = process.cwd();
-        const resolvedCwd = path.resolve(allowedBase, cwd);
-        if (!isPathWithinBase(resolvedCwd, allowedBase)) {
-            res.status(403).json({ error: "访问被拒绝：路径必须在项目目录内。" });
-            return;
-        }
-        if (!query) {
-            res.json({ results: [], query: "", cwd: resolvedCwd });
-            return;
-        }
-        try {
-            const results = [];
-            const queryLower = query.toLowerCase();
-            async function searchDir(dirPath, currentDepth) {
-                if (currentDepth > maxDepth || results.length >= maxResults)
-                    return;
-                const entries = await readdir(dirPath, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (results.length >= maxResults)
-                        break;
-                    const entryPath = path.join(dirPath, entry.name);
-                    const nameLower = entry.name.toLowerCase();
-                    const matchIndex = nameLower.indexOf(queryLower);
-                    if (matchIndex !== -1) {
-                        results.push({
-                            path: entryPath,
-                            name: entry.name,
-                            type: entry.isDirectory() ? "dir" : "file",
-                            matchScore: matchIndex,
-                        });
-                    }
-                    if (entry.isDirectory()) {
-                        await searchDir(entryPath, currentDepth + 1);
-                    }
-                }
-            }
-            await searchDir(resolvedCwd, 0);
-            results.sort((a, b) => {
-                if (a.matchScore !== b.matchScore)
-                    return a.matchScore - b.matchScore;
-                return a.name.localeCompare(b.name);
-            });
-            res.json({ results: results.slice(0, maxResults), query, cwd: resolvedCwd });
-        }
-        catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "搜索失败。可能原因：路径不存在或权限不足。") });
-        }
-    });
+    }));
+    registerFileRoutes(app, { storage, defaultCwd: config.defaultCwd });
     // ── Session control ──
     app.post("/api/commands", (req, res) => {
         const body = req.body;
@@ -2398,6 +1352,10 @@ export async function startServer(config, configPath) {
             res.status(400).json({ error: "请输入要执行的命令。" });
             return;
         }
+        if (body.mode !== undefined && !isExecutionMode(body.mode)) {
+            res.status(400).json({ error: `无效执行模式: ${String(body.mode)}` });
+            return;
+        }
         const initialInput = body.initialInput?.trim();
         try {
             const origin = parseSessionCreationOrigin(body);
@@ -2410,7 +1368,7 @@ export async function startServer(config, configPath) {
             const effectiveModel = rawModel || getDefaultModelForProvider(config, provider) || undefined;
             const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
             const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
-            const snapshot = processes.start(body.command, body.cwd, normalizeMode(body.mode, config.defaultMode), initialInput || undefined, {
+            const snapshot = processes.start(body.command, body.cwd, body.mode ?? config.defaultMode, initialInput || undefined, {
                 worktreeEnabled: body.worktreeEnabled === true,
                 provider,
                 model: effectiveModel,
@@ -2464,14 +1422,19 @@ export async function startServer(config, configPath) {
     const wss = new WebSocketServer({
         server,
         path: "/ws",
+        // Incoming frames are control messages (subscribe/resync/pong), never
+        // transcripts. Bound them so a single client cannot allocate arbitrarily
+        // large buffers before JSON parsing.
+        maxPayload: 256 * 1024,
         perMessageDeflate: {
             zlibDeflateOptions: { level: 1 },
             threshold: 512,
             concurrencyLimit: 10,
         },
     });
-    const wsManager = new WsBroadcastManager(wss, () => config.cardDefaults ?? {}, useHttps);
-    wsManager.setup((id) => structuredSessions.get(id) ?? processes.get(id));
+    const wsManager = new WsBroadcastManager(wss, () => config.cardDefaults ?? {}, useHttps, authService);
+    wsManager.setup((id) => sessionRegistry.get(id));
+    disconnectAuthenticatedSockets = () => wsManager.disconnectAll();
     wss.on("error", (err) => {
         if (err.code === "EADDRINUSE")
             return;
@@ -2504,13 +1467,7 @@ export async function startServer(config, configPath) {
             serviceInstalled: safeServiceInstalled(),
             globalCli: resolveGlobalWandCli(),
         });
-        try {
-            wss.clients.forEach((client) => client.close());
-        }
-        catch {
-            /* noop */
-        }
-        server.close(() => {
+        void close().finally(() => {
             if (plan.mode === "spawn") {
                 spawn(process.execPath, [plan.bin ?? "", ...(plan.args ?? [])], {
                     detached: true,
@@ -2522,23 +1479,42 @@ export async function startServer(config, configPath) {
             process.exit(0);
         });
         // Force exit after 5s if graceful shutdown stalls
-        setTimeout(() => process.exit(0), 5000);
+        const forceExitTimer = setTimeout(() => process.exit(0), 5000);
+        forceExitTimer.unref?.();
     }
-    app.post("/api/restart", async (_req, res) => {
+    app.post("/api/restart", requireAdmin, asyncRoute(async (_req, res) => {
         res.json({ ok: true, message: "服务正在重启..." });
         wsManager.emitEvent({
             type: "notification",
             sessionId: "__system__",
             data: { kind: "restart" },
         });
-        setTimeout(() => {
+        const restartTimer = setTimeout(() => {
             relaunchAfterShutdown();
         }, 600);
-    });
+        restartTimer.unref?.();
+    }));
     let bindAddr = config.host === "0.0.0.0" ? "0.0.0.0" : config.host;
     const collectedUrls = [];
     await new Promise((resolve, reject) => {
         const cleanupFailedListen = () => {
+            shuttingDown = true;
+            try {
+                processes.dispose();
+            }
+            catch { /* noop */ }
+            try {
+                structuredSessions.dispose();
+            }
+            catch { /* noop */ }
+            try {
+                structuredLogger.dispose();
+            }
+            catch { /* noop */ }
+            try {
+                wsManager.dispose();
+            }
+            catch { /* noop */ }
             try {
                 wss.close();
             }
@@ -2547,6 +1523,7 @@ export async function startServer(config, configPath) {
                 server.close();
             }
             catch { /* noop */ }
+            authService.dispose();
             try {
                 storage.close();
             }
@@ -2590,17 +1567,17 @@ export async function startServer(config, configPath) {
     }
     // Pre-warm model cache (probes claude --version + codex debug models).
     if (!testMode) {
-        refreshModels().catch(() => { });
+        refreshModels(getModelRefreshOptions()).catch(() => { });
     }
     // ── Auto-update endpoints ──
-    app.get("/api/auto-update", (_req, res) => {
+    app.get("/api/auto-update", requireAdmin, (_req, res) => {
         const web = storage.getConfigValue("autoUpdateWeb") === "true";
         const apk = storage.getConfigValue("autoUpdateApk") === "true";
         const dmg = storage.getConfigValue("autoUpdateDmg") === "true";
         const cli = storage.getConfigValue("autoUpdateProviderClis") === "true";
         res.json({ web, apk, dmg, cli });
     });
-    app.post("/api/auto-update", (req, res) => {
+    app.post("/api/auto-update", requireAdmin, (req, res) => {
         const { web, apk, dmg, cli } = req.body;
         if (typeof web === "boolean") {
             storage.setConfigValue("autoUpdateWeb", String(web));
@@ -2622,7 +1599,7 @@ export async function startServer(config, configPath) {
         });
     });
     // ── Update channel (stable / beta) ──
-    app.get("/api/update-channel", (_req, res) => {
+    app.get("/api/update-channel", requireAdmin, (_req, res) => {
         res.json({
             channel: getUpdateChannel(),
             build: {
@@ -2633,16 +1610,24 @@ export async function startServer(config, configPath) {
             },
         });
     });
-    app.post("/api/update-channel", (req, res) => {
+    app.post("/api/update-channel", requireAdmin, (req, res) => {
         const body = (req.body ?? {});
         const channel = body.channel === "beta" ? "beta" : "stable";
         storage.setConfigValue("updateChannel", channel);
         res.json({ channel });
     });
+    // Express 4 does not forward rejected route promises automatically. Every
+    // async route above is wrapped with asyncRoute, and this final middleware
+    // keeps parser, synchronous middleware, and async failures JSON-shaped.
+    app.use(jsonErrorHandler);
     // ── Auto-update logic ──
     async function performAutoUpdate() {
+        if (shuttingDown)
+            return;
         const channel = getUpdateChannel();
         const info = await checkLatestPackageVersion(channel, true);
+        if (shuttingDown)
+            return;
         cachedUpdateInfo = info;
         if (!info.latest || !info.updateAvailable)
             return;
@@ -2686,6 +1671,8 @@ export async function startServer(config, configPath) {
         });
         try {
             await npmInstallGlobal(info.installSpec, 120000);
+            if (shuttingDown)
+                return;
             // 镜像 install.sh：装完用全局安装刷新服务 unit（ExecStart/PATH），重启才会跑到新版。
             const repair = repairServiceUnitAfterUpdate(configPath);
             if (repair.scope)
@@ -2702,9 +1689,10 @@ export async function startServer(config, configPath) {
                 },
             });
             // Restart after a brief delay
-            setTimeout(() => {
+            const restartTimer = setTimeout(() => {
                 relaunchAfterShutdown();
             }, 1000);
+            restartTimer.unref?.();
         }
         catch (error) {
             const msg = getErrorMessage(error, "未知错误");
@@ -2718,11 +1706,13 @@ export async function startServer(config, configPath) {
         }
     }
     async function performProviderCliAutoUpdate() {
-        if (storage.getConfigValue("autoUpdateProviderClis") !== "true" || providerCliUpdateInFlight || updateInFlight)
+        if (shuttingDown || storage.getConfigValue("autoUpdateProviderClis") !== "true" || updateState.providerCliUpdateInFlight || updateState.updateInFlight)
             return;
-        providerCliUpdateInFlight = true;
+        updateState.providerCliUpdateInFlight = true;
         try {
             const before = await refreshProviderCliUpdates();
+            if (shuttingDown)
+                return;
             const available = before.items.filter((item) => item.updateAvailable && item.updateSupported);
             if (!available.length)
                 return;
@@ -2730,18 +1720,20 @@ export async function startServer(config, configPath) {
                 inheritEnv: config.inheritEnv !== false,
                 onLog: (line) => process.stdout.write(`[wand] ${line}\n`),
             });
+            if (shuttingDown)
+                return;
             const after = await refreshProviderCliUpdates();
             const results = verifyProviderCliUpdateResults(commandResults, after.items);
             for (const result of results) {
                 process.stdout.write(`[wand] CLI 自动更新 ${result.ok ? "完成" : "失败"}: ${result.message}\n`);
             }
-            refreshModels().catch(() => { });
+            refreshModels(getModelRefreshOptions()).catch(() => { });
         }
         catch (error) {
             process.stdout.write(`[wand] CLI 自动更新失败: ${getErrorMessage(error)}\n`);
         }
         finally {
-            providerCliUpdateInFlight = false;
+            updateState.providerCliUpdateInFlight = false;
         }
     }
     let updateCheckTimer = null;
@@ -2764,42 +1756,87 @@ export async function startServer(config, configPath) {
         }, 2 * 60 * 1000);
         providerCliUpdateTimer.unref();
     }
-    const close = () => new Promise((resolve) => {
-        let done = false;
-        const finish = () => {
-            if (done)
-                return;
-            done = true;
+    let closePromise = null;
+    const close = () => {
+        if (closePromise)
+            return closePromise;
+        closePromise = (async () => {
+            shuttingDown = true;
+            if (updateCheckTimer) {
+                clearInterval(updateCheckTimer);
+                updateCheckTimer = null;
+            }
+            if (providerCliUpdateTimer) {
+                clearTimeout(providerCliUpdateTimer);
+                providerCliUpdateTimer = null;
+            }
+            // Stop accepting requests first. Existing requests get a short grace
+            // period while managers flush and active runners are cancelled.
+            const serverClosed = new Promise((resolve) => {
+                let settled = false;
+                let fallbackTimer = null;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (fallbackTimer)
+                        clearTimeout(fallbackTimer);
+                    resolve();
+                };
+                fallbackTimer = setTimeout(() => {
+                    try {
+                        server.closeAllConnections?.();
+                    }
+                    catch { /* ignore */ }
+                    finish();
+                }, 3000);
+                fallbackTimer.unref?.();
+                try {
+                    server.close(() => finish());
+                }
+                catch {
+                    finish();
+                }
+            });
             try {
-                storage.close();
+                processes.dispose();
+            }
+            catch { /* best-effort shutdown */ }
+            try {
+                structuredSessions.dispose();
+            }
+            catch { /* best-effort shutdown */ }
+            try {
+                structuredLogger.dispose();
+            }
+            catch { /* best-effort shutdown */ }
+            try {
+                wsManager.dispose();
+            }
+            catch { /* best-effort shutdown */ }
+            try {
+                wss.close();
             }
             catch { /* ignore */ }
-            resolve();
-        };
-        try {
-            wss.clients.forEach((c) => c.close());
-        }
-        catch { /* ignore */ }
-        try {
-            wss.close();
-        }
-        catch { /* ignore */ }
-        if (updateCheckTimer)
-            clearInterval(updateCheckTimer);
-        if (providerCliUpdateTimer)
-            clearInterval(providerCliUpdateTimer);
-        try {
-            server.close(() => finish());
-        }
-        catch {
-            finish();
-            return;
-        }
-        setTimeout(finish, 3000); // 兜底：3s 内未关完强制 resolve
-    });
+            try {
+                await serverClosed;
+            }
+            finally {
+                // Auth cleanup must precede DatabaseSync.close() so its cleanup timer
+                // can never retain or call a closed storage instance.
+                authService.dispose();
+                try {
+                    storage.close();
+                }
+                catch { /* ignore */ }
+            }
+        })();
+        return closePromise;
+    };
     return {
         processManager: processes,
         structuredSessions,
+        authService,
         configPath,
         dbPath: resolveDatabasePath(configPath),
         urls: collectedUrls,