@cjhyy/code-shell-server 0.9.8 → 0.9.9

package/dist/serve/headless-server.js

@@ -1,14 +1,8 @@
 // packages/server/src/serve/headless-server.ts
 //
-// Headless serve entry — the no-account web host (TODO「服务端部署 + Web
-// Client（无账号体系）」Phase 1').
-//
-// Composition, all pre-existing parts:
-//   - AccessPasscode        HTTP gate (challenge page) + WS `allows()`;
-//                           passcode + remember-cookie is the ONLY access
-//                           control — no AuthN/AuthZ, no users, by decision.
-//   - WorkerBridgeCore      spawns/drives ONE agent-server-stdio worker.
-//   - resolveSafe           path-traversal-safe static file resolution.
+// Single-workspace Node host. The CLI uses Hub administrator sessions; the
+// legacy passcode mode remains available to existing embedders.
+// One WorkerBridgeCore owns execution and the persistent workspace sessions.
 //
 // The browser uses a deliberately small CORE-protocol projection: the host
 // answers session list/detail itself and forwards only run/approve/cancel after
@@ -20,18 +14,39 @@
 // browser re-lists sessions over the same protocol.
 import { createServer } from "node:http";
 import { readFileSync, existsSync } from "node:fs";
-import { dirname, extname, join, resolve } from "node:path";
-import { randomBytes } from "node:crypto";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { randomBytes, randomUUID } from "node:crypto";
 import { WebSocketServer } from "ws";
-import { SessionManager } from "@cjhyy/code-shell-core";
+import { SessionManager, SettingsManager } from "@cjhyy/code-shell-core";
 import { AccessPasscode } from "../mobile-remote/access-passcode.js";
 import { resolveSafe } from "../mobile-remote/mobile-static.js";
 import { contentTypeFor } from "../static-files.js";
+import { createHubAuth } from "../hub/auth-http.js";
+import { ApprovalLeases } from "../hub/approval-lease.js";
+import { HubUploads, hubJson } from "../hub/uploads.js";
+import { createHubConfiguration, HubConfigurationError } from "../hub/configuration.js";
+import { HubRunReplay } from "../hub/run-replay.js";
+import { HubOutboundTransport } from "../hub/outbound-transport.js";
+import { createHubSkills } from "../hub/skills-management.js";
+import { createHubMcpConfiguration } from "../hub/mcp-configuration.js";
+import { createLinkHttp } from "../links/http.js";
+import { createPanelHttp } from "../panels/http.js";
+import { createHubPanelBinding } from "../panels/hub-binding.js";
+import { createHubSessions, hubSessionPreview, readHubSessionState, readHubTranscript, } from "../hub/session-management.js";
+import { createHubFiles } from "../hub/files.js";
 import { WorkerBridgeCore, previewLine } from "../worker-bridge-core.js";
 export async function startHeadlessServer(opts) {
     const host = opts.host ?? "127.0.0.1";
-    const log = opts.log ?? (() => { });
+    const log = (event, data) => {
+        if (!opts.log)
+            return;
+        // Transport diagnostics must not write prompts, approval answers or worker
+        // stderr previews to default service logs. Keep only structural metadata.
+        const { raw: _raw, text: _text, ...metadata } = data ?? {};
+        opts.log(event, opts.debugLogs ? data : metadata);
+    };
     const workspaceCwd = resolve(opts.cwd);
+    const panelBinding = opts.authMode === "hub" ? createHubPanelBinding(workspaceCwd) : undefined;
     const workerDataRoot = resolve(opts.workerDataRoot ??
         (opts.sessionRootDir ? dirname(resolve(opts.sessionRootDir)) : join(opts.dataDir, "worker")));
     const sessionRootDir = resolve(opts.sessionRootDir ?? join(workerDataRoot, "sessions"));
@@ -50,40 +65,95 @@ export async function startHeadlessServer(opts) {
     }
     const passcode = new AccessPasscode({ filePath: join(opts.dataDir, "access.json") });
     let generatedPasscode;
-    if (opts.passcode) {
+    if (opts.authMode !== "hub" && opts.passcode) {
         passcode.set(opts.passcode);
     }
-    else if (!passcode.isSet()) {
+    else if (opts.authMode !== "hub" && !passcode.isSet()) {
         generatedPasscode = randomBytes(6).toString("base64url");
         passcode.set(generatedPasscode);
     }
     const tabs = new Set();
+    // Auth revocation callbacks are registered before configuration modules are ready.
+    // eslint-disable-next-line prefer-const
+    let mcp;
+    // eslint-disable-next-line prefer-const
+    let configuration;
+    // eslint-disable-next-line prefer-const
+    let links;
+    // eslint-disable-next-line prefer-const
+    let panels;
+    const tabAuth = new Map();
+    const hubAuth = opts.authMode === "hub"
+        ? await createHubAuth({
+            dataDir: opts.dataDir,
+            publicOrigin: opts.publicOrigin,
+            onRevoke: (sessionId) => {
+                mcp?.cancelOwner(sessionId);
+                configuration?.cancelOwner(sessionId);
+                links?.cancelOwner(sessionId);
+                panels?.cancelOwner(sessionId);
+                for (const [ws, auth] of tabAuth) {
+                    if (auth.sessionId === sessionId)
+                        ws.close(4401, "session revoked");
+                }
+            },
+        })
+        : undefined;
+    const uploads = hubAuth ? new HubUploads(join(opts.dataDir, "uploads"), workspaceCwd) : undefined;
+    await uploads?.ready();
     const pendingWorkerResponses = new Map();
     const pendingResponsesByTab = new Map();
+    // Independent of response routing: leaving a tab does not stop its worker run.
+    const runningSessions = new Map();
+    const runOwners = new Map();
+    const runReplay = new HubRunReplay();
+    const runInputs = new Map();
+    let preparingRuns = 0;
+    let configurationChanging = false;
+    let configurationReloadFailed = false;
+    const runUploads = new Map();
+    const isRunning = (sessionId) => [...runningSessions.values()].includes(sessionId);
     let nextTabId = 1;
     let nextWorkerRequestId = 1;
-    const sendToTab = (tab, line, context) => {
-        if (tab.readyState !== tab.OPEN)
-            return false;
-        try {
-            tab.send(line);
-            return true;
-        }
-        catch (error) {
-            // readyState can change between the guard and send. A dead browser must
-            // never crash the shared worker router or its timeout reaper.
-            log("tab.send_failed", {
-                context,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return false;
-        }
-    };
+    const outbound = new HubOutboundTransport({
+        tabs: () => tabs,
+        onDrop: (metadata) => log("tab.backpressure_drop", { ...metadata }),
+    });
+    const sendToTab = (tab, line, _context) => outbound.send(tab, line);
     const broadcast = (line) => {
         for (const tab of tabs) {
             sendToTab(tab, line, "broadcast");
         }
     };
+    const notify = (method, params) => {
+        broadcast(JSON.stringify({ jsonrpc: "2.0", method, params }));
+    };
+    const publishStream = (sessionId, event) => {
+        const cursor = runReplay.append(sessionId, event);
+        notify("agent/streamEvent", {
+            sessionId,
+            event,
+            hubSequence: cursor.sequence,
+            hubEpoch: cursor.epoch,
+        });
+    };
+    const leases = new ApprovalLeases((lease) => notify("serve/approvalLease", lease));
+    const authReaper = hubAuth
+        ? setInterval(() => {
+            leases.sweep();
+            void uploads?.sweep().catch(() => { });
+            for (const [ws, auth] of tabAuth) {
+                void hubAuth
+                    .authenticate(auth.request)
+                    .then((session) => {
+                    if (!session)
+                        ws.close(4401, "session expired");
+                })
+                    .catch(() => ws.close(4401, "session unavailable"));
+            }
+        }, opts.authRecheckMs ?? 5_000)
+        : undefined;
+    authReaper?.unref?.();
     const deletePendingWorkerResponse = (requestId) => {
         const route = pendingWorkerResponses.get(requestId);
         if (!route)
@@ -97,7 +167,9 @@ export async function startHeadlessServer(opts) {
     };
     const clearPendingWorkerResponsesForTab = (tabId) => {
         for (const [requestId, route] of pendingWorkerResponses) {
-            if (route.tabId === tabId)
+            // A submitted approval still needs its worker ACK after this tab leaves.
+            // In particular, an error must reopen the card on the remaining devices.
+            if (route.tabId === tabId && !route.approvalId)
                 deletePendingWorkerResponse(requestId);
         }
     };
@@ -107,10 +179,20 @@ export async function startHeadlessServer(opts) {
         }
         pendingWorkerResponses.clear();
         pendingResponsesByTab.clear();
+        runningSessions.clear();
+        runOwners.clear();
+        runReplay.clear();
+        runInputs.clear();
+        for (const receipt of runUploads.values())
+            receipt.release();
+        runUploads.clear();
     };
     const pendingResponseReaper = setInterval(() => {
         const now = Date.now();
         for (const [requestId, route] of pendingWorkerResponses) {
+            // Runs answer only at turn end, potentially hours later.
+            if (hubAuth && (route.method === "agent/run" || route.approvalId))
+                continue;
             if (now - route.insertedAt < pendingResponseTtlMs)
                 continue;
             deletePendingWorkerResponse(requestId);
@@ -132,17 +214,132 @@ export async function startHeadlessServer(opts) {
             return;
         }
         if (!message || message.id === undefined || message.method !== undefined) {
+            if (hubAuth && message?.method === "agent/streamEvent") {
+                const params = message.params;
+                if (typeof params?.sessionId === "string" && params.event !== undefined) {
+                    let event = params.event;
+                    const value = event;
+                    if (value?.type === "session_user_message" && typeof value.clientMessageId === "string") {
+                        const input = [...runInputs.values()].find((candidate) => candidate.sessionId === params.sessionId &&
+                            candidate.event.clientMessageId === value.clientMessageId);
+                        if (input) {
+                            if (input.echoed)
+                                return;
+                            input.echoed = true;
+                            event = input.event;
+                        }
+                    }
+                    publishStream(params.sessionId, event);
+                    return;
+                }
+            }
+            if (hubAuth && message?.method === "agent/runAccepted") {
+                const params = message.params;
+                const requestId = String(params?.requestId);
+                const input = runInputs.get(requestId);
+                if (input && !input.echoed) {
+                    input.echoed = true;
+                    publishStream(input.sessionId, input.event);
+                }
+                const route = pendingWorkerResponses.get(requestId);
+                if (route)
+                    sendToTab(route.tab, JSON.stringify({
+                        ...message,
+                        params: { ...params, requestId: route.originalId },
+                    }), "run-accepted");
+                return;
+            }
+            if (hubAuth && message?.method === "agent/approvalRequest") {
+                const approval = message.params;
+                if (approval &&
+                    typeof approval.requestId === "string" &&
+                    typeof approval.sessionId === "string") {
+                    const request = approval.request;
+                    if (request?.toolName === "__panel_action__") {
+                        const ownerId = runOwners.get(approval.sessionId);
+                        const result = ownerId && panels
+                            ? panels.panelAction(ownerId, approval.sessionId, request.args ?? {})
+                            : Promise.resolve({ ok: false, detail: "当前对话没有可用的面板连接。" });
+                        void result.catch(() => ({ ok: false, detail: "面板操作未完成。" })).then((answer) => {
+                            if (!isRunning(approval.sessionId) || runOwners.get(approval.sessionId) !== ownerId)
+                                return;
+                            return bridge.request("agent/approve", {
+                                sessionId: approval.sessionId, requestId: approval.requestId,
+                                connectionId: approval.connectionId, generation: approval.generation,
+                                decision: { approved: true, answer: JSON.stringify(answer) },
+                            }, { id: `panel-reply-${randomUUID()}`, consume: true, settleOnExit: true, failFast: true, timeoutMs: 5000,
+                                meta: { origin: "host", producer: "hub-panel-action" },
+                            });
+                        }).catch(() => { });
+                        return;
+                    }
+                    try {
+                        leases.add(approval);
+                    }
+                    catch {
+                        workerUnavailable("pending approval limit exceeded");
+                        bridge.kill();
+                        return;
+                    }
+                }
+            }
+            else if (hubAuth && message?.method === "agent/approvalResolved") {
+                const requestId = message.params?.requestId;
+                if (requestId)
+                    leases.resolved(requestId);
+            }
             broadcast(line);
             return;
         }
+        const receipt = runUploads.get(String(message.id));
+        if (receipt) {
+            runUploads.delete(String(message.id));
+            if (message.error)
+                receipt.release();
+            else
+                void receipt.commit().catch(() => log("upload.finalize_failed"));
+        }
+        const runSessionId = runningSessions.get(String(message.id));
+        runInputs.delete(String(message.id));
+        if (runSessionId) {
+            const finishedSession = runningSessions.get(String(message.id));
+            runningSessions.delete(String(message.id));
+            if (finishedSession && !isRunning(finishedSession))
+                runOwners.delete(finishedSession);
+            runReplay.finish(runSessionId, String(message.id));
+            if (hubAuth)
+                notify("serve/sessionStatus", {
+                    sessionId: runSessionId,
+                    running: isRunning(runSessionId),
+                });
+        }
         const route = pendingWorkerResponses.get(String(message.id));
         if (!route) {
             log("worker.response_dropped", { reason: "unknown request id", id: message.id });
             return;
         }
+        if (route.approvalId) {
+            if (message.error) {
+                leases.retry(route.approvalId);
+                notify("serve/approvalSnapshot", { approvals: leases.snapshot() });
+            }
+            else {
+                // The worker's successful ACK is authoritative even if an implementation
+                // omits the separate approvalResolved notification.
+                leases.resolved(route.approvalId);
+                notify("agent/approvalResolved", { requestId: route.approvalId });
+            }
+        }
         deletePendingWorkerResponse(String(message.id));
         sendToTab(route.tab, JSON.stringify({ ...message, id: route.originalId }), "worker-response");
     };
+    const workerUnavailable = (message) => {
+        failPendingWorkerResponses(message);
+        leases.clear();
+        if (hubAuth)
+            notify("serve/approvalSnapshot", { approvals: [] });
+        notify("serve/workerExit", { clean: false, gaveUp: true });
+    };
     const bridge = new WorkerBridgeCore({
         entryPath: opts.workerEntryPath,
         execPath: opts.execPath,
@@ -150,14 +347,21 @@ export async function startHeadlessServer(opts) {
         buildEnv: () => ({
             ...process.env,
             CODE_SHELL_DATA_ROOT: workerDataRoot,
+            CODE_SHELL_CREDENTIAL_ACCESS: "local",
             ...(opts.workerCapabilityModules
                 ? { CODE_SHELL_CAPABILITY_MODULES: opts.workerCapabilityModules }
                 : {}),
         }),
         log,
         onStderr: (text) => log("worker.stderr", { text: previewLine(text) }),
+        onSpawnFailed: () => workerUnavailable("agent worker could not start"),
+        onSpawnError: () => workerUnavailable("agent worker could not start"),
         onExit: (info) => {
             failPendingWorkerResponses("agent worker stopped");
+            leases.clear();
+            if (hubAuth)
+                notify("serve/approvalSnapshot", { approvals: [] });
+            configurationReloadFailed = false;
             // Synthetic serve-level notification so the UI can show "agent worker
             // stopped" without conflating it with in-protocol agent/status.
             broadcast(JSON.stringify({
@@ -168,6 +372,102 @@ export async function startHeadlessServer(opts) {
         },
     });
     bridge.subscribeLines(routeWorkerLine);
+    const withConfigurationMutation = async (write) => {
+        if (configurationChanging ||
+            preparingRuns > 0 ||
+            runningSessions.size > 0 ||
+            (panels?.activeTaskCount() ?? 0) > 0 ||
+            pendingWorkerResponses.size > 0) {
+            throw new HubConfigurationError(409, "请等待当前任务完成后再保存配置。");
+        }
+        configurationChanging = true;
+        try {
+            const result = await write();
+            // Use Desktop's fixed hot-reload operation, preserving sessions and
+            // background commands. This host-only RPC is never browser-controlled.
+            if (bridge.hasChild()) {
+                const outcome = await bridge.request("agent/configure", {
+                    reloadModels: true,
+                    reloadSettings: true,
+                }, {
+                    id: `hub-configuration-${nextWorkerRequestId++}`,
+                    timeoutMs: 5_000,
+                    consume: true,
+                    settleOnExit: true,
+                    failFast: true,
+                    meta: { origin: "serve", producer: "serve-configuration" },
+                });
+                if (outcome.status !== "result") {
+                    configurationReloadFailed = bridge.hasChild();
+                    throw new HubConfigurationError(503, "配置已保存但未能生效，请重新保存或重启服务。");
+                }
+            }
+            configurationReloadFailed = false;
+            notify("serve/configurationChanged", {});
+            return result;
+        }
+        finally {
+            configurationChanging = false;
+        }
+    };
+    const configurationOptions = {
+        cwd: workspaceCwd,
+        isAuthorized: async (req) => !!(await hubAuth?.authenticate(req)),
+        ownerId: async (req) => (await hubAuth?.authenticate(req))?.id,
+        withMutation: withConfigurationMutation,
+    };
+    configuration = hubAuth ? createHubConfiguration(configurationOptions) : undefined;
+    links = hubAuth
+        ? createLinkHttp({
+            ...configurationOptions,
+            onChanged: () => notify("serve/configurationChanged", {}),
+        })
+        : undefined;
+    panels = hubAuth
+        ? createPanelHttp({
+            ...configurationOptions,
+            ...panelBinding,
+            dataDir: opts.dataDir,
+            host: "hub",
+            publicPathPrefix: opts.publicPathPrefix,
+            agentTaskOptions: {
+                workerEntryPath: opts.workerEntryPath,
+                buildEnv: () => ({
+                    ...process.env,
+                    CODE_SHELL_DATA_ROOT: workerDataRoot,
+                    CODE_SHELL_CREDENTIAL_ACCESS: "local",
+                    ...(opts.workerCapabilityModules ? { CODE_SHELL_CAPABILITY_MODULES: opts.workerCapabilityModules } : {}),
+                }),
+            },
+            onChanged: () => notify("serve/configurationChanged", {}),
+        })
+        : undefined;
+    const skills = hubAuth
+        ? createHubSkills({
+            ...configurationOptions,
+            dataDir: opts.dataDir,
+            owner: async (req) => (await hubAuth.authenticate(req))?.id ?? null,
+        })
+        : undefined;
+    mcp = hubAuth
+        ? createHubMcpConfiguration({
+            ...configurationOptions,
+            ownerId: async (req) => (await hubAuth.authenticate(req))?.id,
+        })
+        : undefined;
+    const sessionManagement = hubAuth
+        ? createHubSessions({
+            cwd: workspaceCwd,
+            sessionRootDir,
+            dataDir: opts.dataDir,
+            isAuthorized: configurationOptions.isAuthorized,
+            isRunning,
+            onChanged: (sessionId) => notify("serve/sessionsChanged", { sessionId }),
+        })
+        : undefined;
+    const files = hubAuth
+        ? createHubFiles({ cwd: workspaceCwd, isAuthorized: configurationOptions.isAuthorized })
+        : undefined;
     const serveStatic = (req, res) => {
         const root = opts.staticRootDir;
         if (!root) {
@@ -212,27 +512,105 @@ export async function startHeadlessServer(opts) {
             res.end("not found");
         }
     };
-    const server = createServer((req, res) => {
-        // The passcode gate fronts EVERY route — same posture as the tunnel mode
-        // of the mobile remote host. gate() renders the challenge page for HTML
-        // navigations and sets the remember cookie on success.
+    const handleHttp = async (req, res) => {
+        const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+        res.setHeader("x-content-type-options", "nosniff");
+        res.setHeader("referrer-policy", "no-referrer");
+        if (pathname === "/health" && req.method === "GET") {
+            hubJson(res, 200, { status: "ok", mode: hubAuth ? "hub" : "passcode" });
+            return;
+        }
+        if (hubAuth) {
+            if (await panels?.handleAssets(req, res))
+                return;
+            if (await hubAuth.handle(req, res))
+                return;
+            if (pathname.startsWith("/api/")) {
+                const session = await hubAuth.authenticate(req);
+                if (!session) {
+                    hubJson(res, 401, { error: "login required" });
+                    return;
+                }
+                if (!hubAuth.isOriginAllowed(req)) {
+                    hubJson(res, 403, { error: "origin rejected" });
+                    return;
+                }
+                if (await configuration.handle(req, res))
+                    return;
+                if (await links.handle(req, res))
+                    return;
+                if (await panels.handle(req, res))
+                    return;
+                if (await skills.handle(req, res))
+                    return;
+                if (await mcp.handle(req, res))
+                    return;
+                if (await sessionManagement.handle(req, res))
+                    return;
+                if (await files.handle(req, res))
+                    return;
+                const upload = /^\/api\/v1\/uploads\/([^/]+)$/.exec(pathname);
+                if (upload && req.method === "PUT") {
+                    await uploads.accept(upload[1], session.id, req, res, async () => !!(await hubAuth.authenticate(req)));
+                    return;
+                }
+                hubJson(res, 404, { error: "API endpoint not found" });
+                return;
+            }
+            if (req.method !== "GET" && req.method !== "HEAD") {
+                hubJson(res, 405, { error: "method not allowed" });
+                return;
+            }
+            // Public static shell contains no user data and supplies the setup/login page.
+            serveStatic(req, res);
+            return;
+        }
         if (!passcode.gate(req, res))
             return;
         serveStatic(req, res);
+    };
+    const server = createServer((req, res) => {
+        void handleHttp(req, res).catch(() => hubJson(res, 500, { error: "server request failed" }));
     });
     const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 });
-    server.on("upgrade", (req, socket, head) => {
+    const upgrade = async (req, socket, head) => {
         const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
-        if (pathname !== "/ws" || !passcode.allows(req)) {
+        const session = hubAuth ? await hubAuth.authenticate(req) : undefined;
+        const allowed = hubAuth
+            ? !!session && hubAuth.isOriginAllowed(req)
+            : passcode.allows(req);
+        if (pathname !== "/ws" || !allowed) {
             socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
             socket.destroy();
             return;
         }
+        if (tabs.size >= 64) {
+            socket.write("HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
         const tabId = nextTabId++;
         wss.handleUpgrade(req, socket, head, (ws) => {
             tabs.add(ws);
+            if (session)
+                tabAuth.set(ws, { sessionId: session.id, request: req });
+            const holderId = String(tabId);
+            if (hubAuth) {
+                sendToTab(ws, JSON.stringify({ jsonrpc: "2.0", method: "serve/hello", params: { tabId: holderId } }), "hello");
+                sendToTab(ws, JSON.stringify({
+                    jsonrpc: "2.0",
+                    method: "serve/approvalSnapshot",
+                    params: { approvals: leases.snapshot() },
+                }), "approval-snapshot");
+            }
             log("tab.connected", { tabs: tabs.size });
-            ws.on("message", (data) => {
+            const handleMessage = async (data) => {
+                if (ws.readyState !== ws.OPEN)
+                    return;
+                if (hubAuth && !(await hubAuth.authenticate(req))) {
+                    ws.close(4401, "session expired");
+                    return;
+                }
                 if (webSocketPayloadBytes(data) > 1024 * 1024) {
                     log("tab.frame_dropped", { reason: "payload too large" });
                     ws.close(1009, "payload too large");
@@ -253,57 +631,273 @@ export async function startHeadlessServer(opts) {
                     log("tab.frame_dropped", { reason: "not jsonrpc", raw: previewLine(line) });
                     return;
                 }
-                const hostReply = replyToHostSessionQuery(parsed, sessionManager, workspaceCwd);
+                if (hubAuth &&
+                    (parsed.method === "serve/approval.claim" || parsed.method === "serve/approval.release")) {
+                    const requestId = parsed.params?.requestId;
+                    try {
+                        if (typeof requestId !== "string")
+                            throw new Error("requestId required");
+                        const result = parsed.method === "serve/approval.claim"
+                            ? leases.claim(requestId, holderId)
+                            : (leases.release(requestId, holderId), { released: true });
+                        sendToTab(ws, JSON.stringify({ jsonrpc: "2.0", id: parsed.id ?? null, result }), "approval-lease");
+                    }
+                    catch (error) {
+                        sendToTab(ws, hostQueryError(parsed.id ?? null, -32009, error.message), "approval-lease");
+                    }
+                    return;
+                }
+                const hostReply = replyToHostSessionQuery(parsed, sessionManager, workspaceCwd, isRunning, hubAuth ? runReplay : undefined);
                 if (hostReply) {
-                    ws.send(hostReply);
+                    sendToTab(ws, hostReply, "host-session-query");
                     return;
                 }
-                const policyReply = authorizeServeRequest(parsed, sessionManager, workspaceCwd);
+                const policyReply = authorizeServeRequest(parsed, sessionManager, workspaceCwd, isRunning);
                 if (policyReply) {
-                    ws.send(policyReply);
+                    sendToTab(ws, policyReply, "request-policy");
+                    return;
+                }
+                if (hubAuth &&
+                    (parsed.id === undefined ||
+                        parsed.id === null ||
+                        (typeof parsed.id !== "string" && typeof parsed.id !== "number"))) {
+                    sendToTab(ws, hostQueryError(null, -32600, "request id required"), "request-id");
                     return;
                 }
-                // This host intentionally exposes one workspace. A browser must not be
-                // able to escape it by supplying another cwd, and a missing cwd must
-                // not silently become the worker's global no-repo conversation.
-                const workerMessage = parsed.method === "agent/run"
-                    ? { ...parsed, params: { ...(parsed.params ?? {}), cwd: workspaceCwd } }
-                    : parsed;
-                if (workerMessage.id === null) {
-                    ws.send(hostQueryError(null, -32600, "JSON-RPC request id must not be null"));
+                if ((pendingResponsesByTab.get(tabId) ?? 0) >= 64) {
+                    sendToTab(ws, hostQueryError(parsed.id ?? null, -32000, "too many pending agent worker requests for this tab"), "pending-limit");
                     return;
                 }
-                if (workerMessage.id !== undefined) {
-                    if ((pendingResponsesByTab.get(tabId) ?? 0) >= 64) {
-                        ws.send(hostQueryError(workerMessage.id, -32000, "too many pending agent worker requests for this tab"));
+                let approvalId;
+                if (hubAuth && parsed.method === "agent/approve") {
+                    const requestId = parsed.params?.requestId;
+                    const approval = typeof requestId === "string" ? leases.get(requestId) : undefined;
+                    if (!approval || approval.sessionId !== parsed.params?.sessionId) {
+                        sendToTab(ws, hostQueryError(parsed.id ?? null, -32009, "approval is no longer pending"), "approval");
                         return;
                     }
-                    const workerRequestId = `serve-${tabId}-${nextWorkerRequestId++}`;
-                    pendingWorkerResponses.set(workerRequestId, {
-                        tab: ws,
-                        originalId: workerMessage.id,
-                        tabId,
-                        insertedAt: Date.now(),
-                    });
-                    pendingResponsesByTab.set(tabId, (pendingResponsesByTab.get(tabId) ?? 0) + 1);
-                    workerMessage.id = workerRequestId;
+                    const decision = parsed.params?.decision;
+                    if (!decision ||
+                        typeof decision !== "object" ||
+                        typeof decision.approved !== "boolean") {
+                        sendToTab(ws, hostQueryError(parsed.id ?? null, -32602, "approval decision required"), "approval");
+                        return;
+                    }
+                    try {
+                        leases.submit(approval.requestId, holderId);
+                        approvalId = approval.requestId;
+                        // Connection/generation belong to the worker's request, never to browser input.
+                        parsed.params = {
+                            sessionId: approval.sessionId,
+                            requestId: approval.requestId,
+                            decision,
+                            ...(approval.connectionId !== undefined
+                                ? { connectionId: approval.connectionId }
+                                : {}),
+                            ...(approval.generation !== undefined ? { generation: approval.generation } : {}),
+                        };
+                    }
+                    catch (error) {
+                        sendToTab(ws, hostQueryError(parsed.id ?? null, -32009, error.message), "approval");
+                        return;
+                    }
+                }
+                let preparedUploads;
+                let uploadsTransferred = false;
+                const preparingRun = !!hubAuth && parsed.method === "agent/run";
+                if (hubAuth && (configurationChanging || configurationReloadFailed)) {
+                    sendToTab(ws, hostQueryError(parsed.id ?? null, -32009, configurationReloadFailed
+                        ? "请先重新保存配置或重启服务，再发送任务。"
+                        : "配置正在保存，请稍后重新发送任务。"), "configuration-changing");
+                    return;
                 }
-                const workerLine = JSON.stringify(workerMessage);
-                // Spawn-on-first-frame (idempotent): the browser's first request wakes
-                // the worker, mirroring the renderer's spawn-on-agent/run semantics.
-                bridge.ensureWorker(opts.cwd);
-                bridge.injectWorkerMessage(workerLine, { origin: "serve", producer: "serve-ws" });
+                if (preparingRun)
+                    preparingRuns++;
+                try {
+                    if (hubAuth && parsed.method === "agent/run") {
+                        // Server-assigned ids ensure even clients that omit them have
+                        // tracked runs, upload ownership and refreshable stream snapshots.
+                        parsed.params = {
+                            ...parsed.params,
+                            sessionId: parsed.params?.sessionId ?? randomUUID(),
+                            clientMessageId: parsed.params?.clientMessageId ?? randomUUID(),
+                        };
+                        if (runningSessions.size >= 64) {
+                            sendToTab(ws, hostQueryError(parsed.id ?? null, -32000, "too many active runs"), "run-limit");
+                            return;
+                        }
+                        try {
+                            preparedUploads = await uploads.prepare(parsed.params?.uploadIds, session.id, parsed.params?.sessionId);
+                            const { uploadIds: _uploadIds, attachments: _attachments, ...params } = parsed.params ?? {};
+                            const attachments = preparedUploads.attachments;
+                            parsed.params = { ...params, ...(attachments.length ? { attachments } : {}) };
+                        }
+                        catch (error) {
+                            sendToTab(ws, hostQueryError(parsed.id ?? null, -32602, error.message), "attachments");
+                            return;
+                        }
+                        if (ws.readyState !== ws.OPEN || !(await hubAuth.authenticate(req)))
+                            return;
+                    }
+                    // Recheck after asynchronous staging/authentication; other tabs may
+                    // have filled the runtime's capacity while this request was suspended.
+                    if (hubAuth && parsed.method === "agent/run" && runningSessions.size >= 64) {
+                        sendToTab(ws, hostQueryError(parsed.id ?? null, -32000, "too many active runs"), "run-limit");
+                        return;
+                    }
+                    // This host intentionally exposes one workspace. A browser must not be
+                    // able to escape it by supplying another cwd, and a missing cwd must
+                    // not silently become the worker's global no-repo conversation.
+                    let defaultModel;
+                    if (hubAuth && parsed.method === "agent/run" && parsed.params?.model === undefined) {
+                        try {
+                            // The preparation guard remains held while reading and dispatching.
+                            // Reloading the shared model pool alone does not change an existing
+                            // session's selected model; this normal run parameter switches it at
+                            // the turn boundary and also refreshes edited connection credentials.
+                            defaultModel = new SettingsManager(workspaceCwd, "full").get().defaults.text;
+                        }
+                        catch {
+                            sendToTab(ws, hostQueryError(parsed.id ?? null, -32602, "模型设置读取失败，请检查服务器配置。"), "configuration-invalid");
+                            return;
+                        }
+                    }
+                    const workerMessage = parsed.method === "agent/run"
+                        ? {
+                            ...parsed,
+                            params: {
+                                ...(parsed.params ?? {}),
+                                ...(defaultModel ? { model: defaultModel } : {}),
+                                cwd: workspaceCwd,
+                            },
+                        }
+                        : parsed;
+                    if (workerMessage.id === null) {
+                        sendToTab(ws, hostQueryError(null, -32600, "JSON-RPC request id must not be null"), "request-id");
+                        return;
+                    }
+                    let baselineEvents = 0;
+                    const baselineSessionId = workerMessage.params?.sessionId;
+                    if (hubAuth && parsed.method === "agent/run" && typeof baselineSessionId === "string") {
+                        try {
+                            if (readOptionalHubSessionState(sessionManager, baselineSessionId)) {
+                                baselineEvents = readHubTranscript(sessionRootDir, baselineSessionId).length;
+                            }
+                        }
+                        catch (cause) {
+                            sendToTab(ws, hostQueryError(workerMessage.id ?? null, -32001, cause instanceof Error ? cause.message : "会话记录无法读取，请检查服务器备份。"), "transcript-unavailable");
+                            return;
+                        }
+                    }
+                    if (workerMessage.id !== undefined) {
+                        if ((pendingResponsesByTab.get(tabId) ?? 0) >= 64) {
+                            sendToTab(ws, hostQueryError(workerMessage.id, -32000, "too many pending agent worker requests for this tab"), "pending-limit");
+                            return;
+                        }
+                        if (hubAuth && parsed.method === "agent/run") {
+                            const runSession = workerMessage.params?.sessionId;
+                            const ownerId = tabAuth.get(ws)?.sessionId;
+                            const activeOwner = typeof runSession === "string" ? runOwners.get(runSession) : undefined;
+                            if (activeOwner && activeOwner !== ownerId) {
+                                sendToTab(ws, hostQueryError(workerMessage.id, -32009, "此对话正在另一台设备运行，请等待完成后再发送。"), "run-owner");
+                                return;
+                            }
+                        }
+                        const workerRequestId = `serve-${tabId}-${nextWorkerRequestId++}`;
+                        pendingWorkerResponses.set(workerRequestId, {
+                            tab: ws,
+                            originalId: workerMessage.id,
+                            tabId,
+                            insertedAt: Date.now(),
+                            method: parsed.method,
+                            ...(approvalId ? { approvalId } : {}),
+                        });
+                        pendingResponsesByTab.set(tabId, (pendingResponsesByTab.get(tabId) ?? 0) + 1);
+                        workerMessage.id = workerRequestId;
+                        if (preparedUploads?.attachments.length) {
+                            runUploads.set(workerRequestId, preparedUploads);
+                            uploadsTransferred = true;
+                        }
+                        const runSessionId = workerMessage.params?.sessionId;
+                        if (parsed.method === "agent/run" && typeof runSessionId === "string") {
+                            if (hubAuth) {
+                                runReplay.begin(runSessionId, workerRequestId, baselineEvents);
+                                const params = workerMessage.params ?? {};
+                                runInputs.set(workerRequestId, {
+                                    sessionId: runSessionId,
+                                    echoed: false,
+                                    event: {
+                                        type: "session_user_message",
+                                        text: typeof params.displayText === "string" ? params.displayText : params.task,
+                                        clientMessageId: params.clientMessageId,
+                                        attachments: (preparedUploads?.attachments ?? []).map((attachment) => ({
+                                            name: attachment.originalName ?? basename(attachment.path),
+                                            size: attachment.size,
+                                            mime: attachment.mime,
+                                            path: attachment.relPath ?? attachment.absPath,
+                                        })),
+                                    },
+                                });
+                            }
+                            runningSessions.set(workerRequestId, runSessionId);
+                            const ownerId = tabAuth.get(ws)?.sessionId;
+                            if (ownerId)
+                                runOwners.set(runSessionId, ownerId);
+                            if (hubAuth)
+                                notify("serve/sessionStatus", { sessionId: runSessionId, running: true });
+                        }
+                    }
+                    const workerLine = JSON.stringify(workerMessage);
+                    // Spawn-on-first-frame (idempotent): the browser's first request wakes
+                    // the worker, mirroring the renderer's spawn-on-agent/run semantics.
+                    bridge.ensureWorker(opts.cwd);
+                    if (!bridge.canSend()) {
+                        workerUnavailable("agent worker is unavailable");
+                        return;
+                    }
+                    bridge.injectWorkerMessage(workerLine, { origin: "serve", producer: "serve-ws" });
+                }
+                finally {
+                    if (preparingRun)
+                        preparingRuns--;
+                    if (!uploadsTransferred)
+                        preparedUploads?.release();
+                }
+            };
+            let queued = 0;
+            let chain = Promise.resolve();
+            ws.on("message", (data) => {
+                if (++queued > 64) {
+                    ws.close(1008, "too many queued requests");
+                    queued--;
+                    return;
+                }
+                chain = chain
+                    .then(() => handleMessage(data))
+                    .catch(() => {
+                    sendToTab(ws, hostQueryError(null, -32000, "request failed"), "request-error");
+                })
+                    .finally(() => {
+                    queued--;
+                });
             });
             ws.on("close", () => {
                 tabs.delete(ws);
+                tabAuth.delete(ws);
+                leases.releaseHolder(holderId);
                 clearPendingWorkerResponsesForTab(tabId);
                 log("tab.closed", { tabs: tabs.size });
             });
             ws.on("error", () => {
                 tabs.delete(ws);
+                tabAuth.delete(ws);
+                leases.releaseHolder(holderId);
                 clearPendingWorkerResponsesForTab(tabId);
             });
         });
+    };
+    server.on("upgrade", (req, socket, head) => {
+        void upgrade(req, socket, head).catch(() => socket.destroy());
     });
     try {
         await new Promise((resolve, reject) => {
@@ -316,6 +910,15 @@ export async function startHeadlessServer(opts) {
     }
     catch (error) {
         clearInterval(pendingResponseReaper);
+        if (authReaper)
+            clearInterval(authReaper);
+        await uploads?.close();
+        await skills?.close();
+        await mcp?.close();
+        configuration?.close();
+        links?.close();
+        panels?.close();
+        files?.close();
         bridge.kill();
         wss.close();
         server.close();
@@ -330,12 +933,22 @@ export async function startHeadlessServer(opts) {
         host,
         port,
         ...(generatedPasscode ? { generatedPasscode } : {}),
+        ...(hubAuth?.bootstrapToken ? { bootstrapToken: hubAuth.bootstrapToken } : {}),
         passcode,
         bridge,
         tabCount: () => tabs.size,
         pendingResponseCount: () => pendingWorkerResponses.size,
         close: async () => {
             clearInterval(pendingResponseReaper);
+            if (authReaper)
+                clearInterval(authReaper);
+            await uploads?.close();
+            await skills?.close();
+            await mcp?.close();
+            configuration?.close();
+            links?.close();
+            panels?.close();
+            files?.close();
             for (const tab of tabs) {
                 try {
                     tab.terminate();
@@ -369,14 +982,13 @@ function webSocketPayloadBytes(data) {
     }
     return Buffer.byteLength(String(data), "utf8");
 }
-function replyToHostSessionQuery(message, sessionManager, workspaceCwd) {
+function replyToHostSessionQuery(message, sessionManager, workspaceCwd, isRunning = () => false, runReplay) {
     if (message.method !== "agent/query" || message.id === undefined)
         return undefined;
     const queryType = message.params?.type;
     if (queryType === "sessions") {
         const sessions = sessionManager
-            .list()
-            .filter((session) => resolve(session.cwd) === workspaceCwd)
+            .list(100, { cwd: workspaceCwd, archived: false, rootsOnly: true })
             .map((session) => ({
             sessionId: session.sessionId,
             cwd: session.cwd,
@@ -384,7 +996,9 @@ function replyToHostSessionQuery(message, sessionManager, workspaceCwd) {
             model: session.model,
             status: session.status,
             turnCount: session.turnCount,
-            ...(session.preview ? { preview: session.preview } : {}),
+            lastActiveAt: session.lastActiveAt,
+            ...(session.title ? { title: session.title } : {}),
+            ...(session.preview ? { preview: hubSessionPreview(session.preview) } : {}),
         }));
         return JSON.stringify({
             jsonrpc: "2.0",
@@ -398,31 +1012,68 @@ function replyToHostSessionQuery(message, sessionManager, workspaceCwd) {
     if (typeof sessionId !== "string" || sessionId.length === 0) {
         return hostQueryError(message.id, -32602, "sessionId required for session_detail");
     }
+    let missingSession = false;
     try {
-        const bundle = sessionManager.resume(sessionId);
-        if (resolve(bundle.state.cwd) !== workspaceCwd) {
+        const state = readOptionalHubSessionState(sessionManager, sessionId);
+        missingSession = !state;
+        if (!state)
+            throw new Error("Session not found in this workspace");
+        if (resolve(state.cwd) !== workspaceCwd) {
             return hostQueryError(message.id, -32001, "Session not found in this workspace");
         }
+        const transcript = readHubTranscript(sessionManager.getStorageDir(), sessionId);
         return JSON.stringify({
             jsonrpc: "2.0",
             id: message.id,
             result: {
                 type: "session_detail",
-                data: { state: bundle.state, transcript: bundle.transcript.getEvents() },
+                data: {
+                    state,
+                    ...(runReplay ? runReplay.snapshot(sessionId, transcript) : { transcript }),
+                    running: isRunning(sessionId),
+                },
             },
         });
     }
     catch (error) {
+        if (runReplay?.hasEmptyBaseline(sessionId) &&
+            isRunning(sessionId) &&
+            (missingSession || error.status === 404)) {
+            return JSON.stringify({
+                jsonrpc: "2.0",
+                id: message.id,
+                result: {
+                    type: "session_detail",
+                    data: {
+                        state: { sessionId, cwd: workspaceCwd, status: "active", turnCount: 0 },
+                        ...runReplay.snapshot(sessionId, []),
+                        running: true,
+                    },
+                },
+            });
+        }
         return hostQueryError(message.id, -32001, error instanceof Error ? error.message : "Session not found");
     }
 }
+/** A missing session can be created; malformed or unsafe existing storage must fail closed. */
+function readOptionalHubSessionState(sessionManager, sessionId) {
+    try {
+        return readHubSessionState(sessionManager.getStorageDir(), sessionId);
+    }
+    catch (error) {
+        if (error.status === 404 && !sessionManager.exists(sessionId)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
 const SERVE_ALLOWED_WORKER_METHODS = new Set(["agent/run", "agent/approve", "agent/cancel"]);
 /**
  * The no-account Web host deliberately exposes only the methods used by its
  * bundled SPA. Passcode possession grants control of this workspace, not raw
  * access to the worker's full local protocol surface.
  */
-function authorizeServeRequest(message, sessionManager, workspaceCwd) {
+function authorizeServeRequest(message, sessionManager, workspaceCwd, isRunning = () => false) {
     if (!message.method || !SERVE_ALLOWED_WORKER_METHODS.has(message.method)) {
         return hostQueryError(message.id ?? null, -32601, "Method is not available in Web serve mode");
     }
@@ -433,16 +1084,19 @@ function authorizeServeRequest(message, sessionManager, workspaceCwd) {
     if (!sessionId) {
         return hostQueryError(message.id ?? null, -32602, "sessionId is required");
     }
+    // A tracked run was already authorized for this host's forced workspace.
+    // Stop must work even before Core publishes its first persistent state file.
+    if (message.method === "agent/cancel" && isRunning(sessionId))
+        return undefined;
     try {
-        const session = sessionManager.resume(sessionId).state;
-        if (resolve(session.cwd) === workspaceCwd)
+        const session = readOptionalHubSessionState(sessionManager, sessionId);
+        if (session && resolve(session.cwd) === workspaceCwd)
+            return undefined;
+        if (!session && !sessionManager.exists(sessionId) && message.method === "agent/run")
             return undefined;
     }
     catch {
-        // A caller may choose the id for a brand-new run. Other methods must target
-        // an already-persisted session owned by this workspace.
-        if (message.method === "agent/run")
-            return undefined;
+        // Invalid ids and unreadable existing records must not become new sessions.
     }
     return hostQueryError(message.id ?? null, -32001, "Session not found in this workspace");
 }