@evandu/super-pi 0.1.138 → 0.1.140

package/dist/server/http-server.js

@@ -1,7 +1,10 @@
 import { createReadStream, existsSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { readdir, rm, stat } from "node:fs/promises";
 import { createServer } from "node:http";
+import { gzip } from "node:zlib";
+import { promisify } from "node:util";
 import { homedir, networkInterfaces } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES, readWorkspaceFile, resolveInsideRoot, toRelative, writeWorkspaceFile, } from "./files.js";
@@ -276,258 +279,173 @@ export function createHttpServer(options) {
     const { store, paths, accessToken, broadcaster, runService, catalogService, execService, toolRegistry, toolRunner } = context;
     const { uploadsDir, clientDir, rootDir } = paths;
     return createServer(async (request, response) => {
-        // Internal tools use a narrow per-run capability, never the global management token.
-        const requestPath = request.url?.split("?")[0] ?? "";
-        // Tool REGISTRATION is checked after its JSON body is parsed: an agent proves its turn capability
-        // there, while an interactive browser uses the ordinary server access token. Reading and DELETING
-        // the registry have no such second channel, so they are NOT exempted here and fall through to the
-        // ordinary token check below - exempting the whole path is what let any local process list and
-        // delete a person's mounted tools on a server that had `SUPER_PI_ACCESS_TOKEN` set.
-        //
-        // `/api/knowledge/tool` is the same shape as `/api/memory/tool` and carries the same exemption for
-        // the same reason: it is reached only by the Pi process of one turn, carrying that turn's
-        // capability in a header. The MANAGEMENT half (`/api/knowledge`) is deliberately NOT exempted - it
-        // imports and deletes documents, so it stays behind the ordinary token.
-        //
-        // `/api/documents/tool` is the same shape again, and the exemption is safe for the same reason:
-        // the endpoint verifies the SESSION's capability on its own, and refuses a request whose turn is
-        // not running. The global token is a server-wide secret; the capability is a per-conversation
-        // one that only the Pi process of that conversation holds, so the exemption does not widen who
-        // can reach the server - it only spares the one caller that already proves who it is.
-        //
-        // `/api/feishu/tool` is that shape once more. The Feishu credential is a company secret, so
-        // the endpoint that can spend it is exactly the one an agent's own turn can reach, and the
-        // management half (`/api/feishu/config`) stays behind the ordinary token AND the local-address
-        // predicate.
-        if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && requestPath !== "/api/documents/tool" && requestPath !== "/api/web/tool" && requestPath !== "/api/feishu/tool" && requestPath !== "/api/todos" && requestPath !== "/api/scheduled-tasks" && requestPath !== "/api/question" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
-            response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
-            return;
-        }
-        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
-        const remote = request.socket.remoteAddress ?? "";
-        const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(JSON.stringify(body)); };
-        if (url.pathname === "/api/tools/export") {
-            // NOT EXEMPT FROM THE TOKEN CHECK ABOVE, and that is deliberate: an export hands out a tool's
-            // whole source, so it is a management read exactly like GET and DELETE, not a capability call.
-            try {
-                const id = url.searchParams.get("id");
-                if (!id) {
-                    json(400, { error: "缺少工具 id。" });
-                    return;
-                }
-                const exported = await toolRegistry.exportBundle(id);
-                if (!exported) {
-                    json(404, { error: "找不到这个工具。" });
-                    return;
-                }
-                json(200, exported);
-                return;
-            }
-            catch (error) {
-                json(400, { error: describeThrown(error) || "导出工具失败，没有拿到失败原因。" });
+        // Every HTTP request gets one stable id.  It is returned to the browser and
+        // included in the server log, so a report containing a status code or a
+        // timeout can be joined to the exact failing request without guessing from
+        // timestamps.  Do not echo arbitrary input into a header.
+        const suppliedRequestId = request.headers["x-request-id"];
+        const requestId = typeof suppliedRequestId === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(suppliedRequestId)
+            ? suppliedRequestId
+            : randomUUID();
+        response.setHeader("x-request-id", requestId);
+        try {
+            // Internal tools use a narrow per-run capability, never the global management token.
+            const requestPath = request.url?.split("?")[0] ?? "";
+            // Tool REGISTRATION is checked after its JSON body is parsed: an agent proves its turn capability
+            // there, while an interactive browser uses the ordinary server access token. Reading and DELETING
+            // the registry have no such second channel, so they are NOT exempted here and fall through to the
+            // ordinary token check below - exempting the whole path is what let any local process list and
+            // delete a person's mounted tools on a server that had `SUPER_PI_ACCESS_TOKEN` set.
+            //
+            // `/api/knowledge/tool` is the same shape as `/api/memory/tool` and carries the same exemption for
+            // the same reason: it is reached only by the Pi process of one turn, carrying that turn's
+            // capability in a header. The MANAGEMENT half (`/api/knowledge`) is deliberately NOT exempted - it
+            // imports and deletes documents, so it stays behind the ordinary token.
+            //
+            // `/api/documents/tool` is the same shape again, and the exemption is safe for the same reason:
+            // the endpoint verifies the SESSION's capability on its own, and refuses a request whose turn is
+            // not running. The global token is a server-wide secret; the capability is a per-conversation
+            // one that only the Pi process of that conversation holds, so the exemption does not widen who
+            // can reach the server - it only spares the one caller that already proves who it is.
+            //
+            // `/api/feishu/tool` is that shape once more. The Feishu credential is a company secret, so
+            // the endpoint that can spend it is exactly the one an agent's own turn can reach, and the
+            // management half (`/api/feishu/config`) stays behind the ordinary token AND the local-address
+            // predicate.
+            if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && requestPath !== "/api/documents/tool" && requestPath !== "/api/web/tool" && requestPath !== "/api/feishu/tool" && requestPath !== "/api/todos" && requestPath !== "/api/scheduled-tasks" && requestPath !== "/api/question" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
+                response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
                 return;
             }
-        }
-        if (url.pathname === "/api/tools") {
-            try {
-                if (request.method === "GET") {
-                    // The environment state is DERIVED per request and deliberately not stored: it changes when
-                    // the user installs Python, when a tool's venv is built, and when nothing at all happens.
-                    const tools = await toolRegistry.list();
-                    json(200, { tools: await Promise.all(tools.map(async (tool) => ({ ...tool, environmentState: await toolRunner.environmentState(tool) }))) });
-                    return;
-                }
-                if (request.method === "DELETE") {
+            const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+            const remote = request.socket.remoteAddress ?? "";
+            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(JSON.stringify(body)); };
+            if (url.pathname === "/api/tools/export") {
+                // NOT EXEMPT FROM THE TOKEN CHECK ABOVE, and that is deliberate: an export hands out a tool's
+                // whole source, so it is a management read exactly like GET and DELETE, not a capability call.
+                try {
                     const id = url.searchParams.get("id");
                     if (!id) {
                         json(400, { error: "缺少工具 id。" });
                         return;
                     }
-                    const removed = await toolRegistry.remove(id);
-                    // The venv is machine-local state that belongs to that tool and nothing else, so it goes with
-                    // it. Leaving it behind would mean a re-registered tool of the same slug silently inherits a
-                    // stale environment.
-                    if (removed)
-                        await rm(toolRunner.envDir(id), { recursive: true, force: true });
-                    if (removed)
-                        broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
-                    json(removed ? 200 : 404, { ok: removed });
-                    return;
-                }
-                if (request.method !== "POST") {
-                    json(405, { error: "这个接口只接受 POST 请求。" });
+                    const exported = await toolRegistry.exportBundle(id);
+                    if (!exported) {
+                        json(404, { error: "找不到这个工具。" });
+                        return;
+                    }
+                    json(200, exported);
                     return;
                 }
-                // BYTES, NOT CHARACTERS, AND FROM THE REGISTRY'S OWN CONSTANT. The old cap counted UTF-16 code
-                // units at 256,000, below the registry's own 512,000-byte asset limit, so JSON escaping decided
-                // where the real ceiling was and an exported bundle could be refused on the way back in.
-                const imported = await readRequestText(request, MAX_TOOL_BODY_BYTES);
-                if (imported.tooLarge) {
-                    json(413, { error: "导入的内容太大，超过了大小上限。" });
+                catch (error) {
+                    json(400, { error: describeThrown(error) || "导出工具失败，没有拿到失败原因。" });
                     return;
                 }
-                const raw = imported.text;
-                const body = JSON.parse(raw);
-                if (!isAuthorized(request, accessToken)) {
-                    if (!body.conversationId) {
-                        json(401, { error: "需要访问凭据，或正在运行的会话凭据。" });
+            }
+            if (url.pathname === "/api/tools") {
+                try {
+                    if (request.method === "GET") {
+                        // The environment state is DERIVED per request and deliberately not stored: it changes when
+                        // the user installs Python, when a tool's venv is built, and when nothing at all happens.
+                        const tools = await toolRegistry.list();
+                        json(200, { tools: await Promise.all(tools.map(async (tool) => ({ ...tool, environmentState: await toolRunner.environmentState(tool) }))) });
                         return;
                     }
-                    const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability ?? request.headers["x-super-pi-capability"]);
-                    if (!verdict.ok) {
-                        json(403, { error: verdict.message });
+                    if (request.method === "DELETE") {
+                        const id = url.searchParams.get("id");
+                        if (!id) {
+                            json(400, { error: "缺少工具 id。" });
+                            return;
+                        }
+                        const removed = await toolRegistry.remove(id);
+                        // The venv is machine-local state that belongs to that tool and nothing else, so it goes with
+                        // it. Leaving it behind would mean a re-registered tool of the same slug silently inherits a
+                        // stale environment.
+                        if (removed)
+                            await rm(toolRunner.envDir(id), { recursive: true, force: true });
+                        if (removed)
+                            broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
+                        json(removed ? 200 : 404, { ok: removed });
                         return;
                     }
-                }
-                if (!body.slug || !body.name || !Array.isArray(body.files)) {
-                    json(400, { error: "导入需要 slug、名称和文件列表。" });
-                    return;
-                }
-                // AN IMPORTED BUNDLE KEEPS THE EXPORTER'S FINGERPRINT. It describes where the tool was written
-                // and verified, and overwriting it with the importer's own machine would erase the very
-                // difference the tool list exists to show. A tool with no fingerprint gets one measured here.
-                let environment = body.environment;
-                if (environment && !environment.fingerprint) {
-                    const local = await toolRunner.describeLocalPython();
-                    if (local)
-                        environment = { ...environment, fingerprint: { python: local.python, platform: local.platform, packages: environment.requires } };
-                }
-                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, environment, permissions: body.permissions, files: body.files });
-                broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
-                json(201, tool);
-                return;
-            }
-            catch (error) {
-                json(400, { error: describeThrown(error) || "工具请求失败，没有拿到失败原因。" });
-                return;
-            }
-        }
-        if (url.pathname.startsWith("/tools/")) {
-            let id;
-            let resource;
-            try {
-                const parts = url.pathname.slice("/tools/".length).split("/");
-                id = decodeURIComponent(parts.shift() ?? "");
-                resource = parts.filter(Boolean).map(decodeURIComponent).join("/");
-            }
-            catch {
-                response.writeHead(400).end("Malformed tool resource");
-                return;
-            }
-            const listed = (await toolRegistry.list()).find((x) => x.id === id && x.enabled);
-            if (!listed) {
-                response.writeHead(404).end("Tool not found");
-                return;
-            }
-            // A mounted tool never learns its random registry id.  Its API is instead addressed relative
-            // to its own mount (`./api/run`), and this route supplies that identity from the URL.  Besides
-            // making a generated tool usable on its first render, this binds status and cancellation to the
-            // same tool that created a run: an opaque frame for tool A cannot inspect tool B's run ids.
-            const toolOrigin = request.headers.origin === "null";
-            const toolApi = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "access-control-allow-origin": "null", "vary": "Origin" });
-                response.end(JSON.stringify(body));
-            };
-            if (resource === "api/run") {
-                if (!toolOrigin) {
-                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
-                    return;
-                }
-                if (request.method === "OPTIONS") {
-                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
-                    return;
-                }
-                if (request.method !== "POST") {
-                    toolApi(405, { error: "method" });
-                    return;
-                }
-                const executed = await readRequestText(request, 64_000);
-                if (executed.tooLarge) {
-                    toolApi(413, { error: "request too large" });
-                    return;
-                }
-                const raw = executed.text;
-                try {
+                    if (request.method !== "POST") {
+                        json(405, { error: "这个接口只接受 POST 请求。" });
+                        return;
+                    }
+                    // BYTES, NOT CHARACTERS, AND FROM THE REGISTRY'S OWN CONSTANT. The old cap counted UTF-16 code
+                    // units at 256,000, below the registry's own 512,000-byte asset limit, so JSON escaping decided
+                    // where the real ceiling was and an exported bundle could be refused on the way back in.
+                    const imported = await readRequestText(request, MAX_TOOL_BODY_BYTES);
+                    if (imported.tooLarge) {
+                        json(413, { error: "导入的内容太大，超过了大小上限。" });
+                        return;
+                    }
+                    const raw = imported.text;
                     const body = JSON.parse(raw);
-                    const resolved = await toolRegistry.resolve(id);
-                    if (!resolved?.tool.script) {
-                        toolApi(404, { error: "python script is not registered" });
+                    if (!isAuthorized(request, accessToken)) {
+                        if (!body.conversationId) {
+                            json(401, { error: "需要访问凭据，或正在运行的会话凭据。" });
+                            return;
+                        }
+                        const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability ?? request.headers["x-super-pi-capability"]);
+                        if (!verdict.ok) {
+                            json(403, { error: verdict.message });
+                            return;
+                        }
+                    }
+                    if (!body.slug || !body.name || !Array.isArray(body.files)) {
+                        json(400, { error: "导入需要 slug、名称和文件列表。" });
                         return;
                     }
-                    const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {}, environment: resolved.tool.environment });
-                    toolApi(202, run);
-                }
-                catch (error) {
-                    toolApi(400, { error: describeThrown(error) || "工具运行失败，没有拿到失败原因。" });
-                }
-                return;
-            }
-            const runMatch = /^api\/runs\/([^/]+)$/.exec(resource);
-            if (runMatch) {
-                if (!toolOrigin) {
-                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                    // AN IMPORTED BUNDLE KEEPS THE EXPORTER'S FINGERPRINT. It describes where the tool was written
+                    // and verified, and overwriting it with the importer's own machine would erase the very
+                    // difference the tool list exists to show. A tool with no fingerprint gets one measured here.
+                    let environment = body.environment;
+                    if (environment && !environment.fingerprint) {
+                        const local = await toolRunner.describeLocalPython();
+                        if (local)
+                            environment = { ...environment, fingerprint: { python: local.python, platform: local.platform, packages: environment.requires } };
+                    }
+                    const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, environment, permissions: body.permissions, files: body.files });
+                    broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
+                    json(201, tool);
                     return;
                 }
-                if (request.method === "OPTIONS") {
-                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-max-age": "300", "vary": "Origin" }).end();
+                catch (error) {
+                    json(400, { error: describeThrown(error) || "工具请求失败，没有拿到失败原因。" });
                     return;
                 }
-                let runId;
+            }
+            if (url.pathname.startsWith("/tools/")) {
+                let id;
+                let resource;
                 try {
-                    runId = decodeURIComponent(runMatch[1]);
+                    const parts = url.pathname.slice("/tools/".length).split("/");
+                    id = decodeURIComponent(parts.shift() ?? "");
+                    resource = parts.filter(Boolean).map(decodeURIComponent).join("/");
                 }
                 catch {
-                    toolApi(400, { error: "Malformed tool resource" });
+                    response.writeHead(400).end("Malformed tool resource");
                     return;
                 }
-                if (request.method === "GET") {
-                    const run = toolRunner.get(runId, id);
-                    if (!run) {
-                        toolApi(404, { error: "run not found" });
-                        return;
-                    }
-                    toolApi(200, run);
+                const listed = (await toolRegistry.list()).find((x) => x.id === id && x.enabled);
+                if (!listed) {
+                    response.writeHead(404).end("Tool not found");
                     return;
                 }
-                if (request.method === "DELETE") {
-                    const run = toolRunner.cancel(runId, id);
-                    if (!run) {
-                        toolApi(404, { error: "run not found" });
+                // A mounted tool never learns its random registry id.  Its API is instead addressed relative
+                // to its own mount (`./api/run`), and this route supplies that identity from the URL.  Besides
+                // making a generated tool usable on its first render, this binds status and cancellation to the
+                // same tool that created a run: an opaque frame for tool A cannot inspect tool B's run ids.
+                const toolOrigin = request.headers.origin === "null";
+                const toolApi = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "access-control-allow-origin": "null", "vary": "Origin" });
+                    response.end(JSON.stringify(body));
+                };
+                if (resource === "api/run") {
+                    if (!toolOrigin) {
+                        toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
                         return;
                     }
-                    toolApi(200, run);
-                    return;
-                }
-                toolApi(405, { error: "method" });
-                return;
-            }
-            // ---- THE MODEL, ON THE TOOL'S OWN BEHALF ---------------------------------------------------
-            // A tool asking the model a question, over the same relative API as its Python jobs, so the frame
-            // still never learns an id, a path or a credential. Three gates, in this order:
-            //   1. the opaque sandbox origin - identical to every other tool API here;
-            //   2. the tool must CARRY the grant (`permissions.llm`), which is the thing the review card showed
-            //      the person before they accepted the file. A tool that quietly started asking the model
-            //      would be spending the user's quota from inside a sandbox they were told was isolated;
-            //   3. the run is bound to this tool id, so one frame cannot read or cancel another's answer.
-            const llmStart = /^api\/llm$/.exec(resource);
-            const llmRun = /^api\/llm\/([^/]+)$/.exec(resource);
-            if (llmStart || llmRun) {
-                if (!toolOrigin) {
-                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
-                    return;
-                }
-                // GRANT FIRST, THEN RUNTIME. What a tool is allowed to ask is a fact about the tool and does not
-                // depend on whether this machine happens to have a model, so a tool with no grant gets the same
-                // 403 whether or not Pi is installed.
-                if (!listed.permissions?.llm) {
-                    toolApi(403, { error: "这个工具没有调用模型的权限；注册或导入时它必须声明 permissions: { llm: true }。" });
-                    return;
-                }
-                if (!context.toolLlm?.available) {
-                    toolApi(503, { error: "这台机器上没有可用的 Pi 运行时，工具无法调用模型。" });
-                    return;
-                }
-                if (llmStart) {
                     if (request.method === "OPTIONS") {
                         response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
                         return;
@@ -536,1378 +454,1638 @@ export function createHttpServer(options) {
                         toolApi(405, { error: "method" });
                         return;
                     }
-                    const asked = await readRequestText(request, 64_000);
-                    if (asked.tooLarge) {
+                    const executed = await readRequestText(request, 64_000);
+                    if (executed.tooLarge) {
                         toolApi(413, { error: "request too large" });
                         return;
                     }
-                    const raw = asked.text;
+                    const raw = executed.text;
                     try {
                         const body = JSON.parse(raw);
-                        toolApi(202, context.toolLlm.start({ toolId: id, prompt: body.prompt ?? "", system: body.system, timeoutMs: body.timeoutMs }));
+                        const resolved = await toolRegistry.resolve(id);
+                        if (!resolved?.tool.script) {
+                            toolApi(404, { error: "python script is not registered" });
+                            return;
+                        }
+                        const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {}, environment: resolved.tool.environment });
+                        toolApi(202, run);
                     }
                     catch (error) {
-                        toolApi(400, { error: describeThrown(error) || "模型调用失败，没有拿到失败原因。" });
+                        toolApi(400, { error: describeThrown(error) || "工具运行失败，没有拿到失败原因。" });
                     }
                     return;
                 }
-                if (request.method === "OPTIONS") {
-                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                const runMatch = /^api\/runs\/([^/]+)$/.exec(resource);
+                if (runMatch) {
+                    if (!toolOrigin) {
+                        toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                        return;
+                    }
+                    if (request.method === "OPTIONS") {
+                        response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-max-age": "300", "vary": "Origin" }).end();
+                        return;
+                    }
+                    let runId;
+                    try {
+                        runId = decodeURIComponent(runMatch[1]);
+                    }
+                    catch {
+                        toolApi(400, { error: "Malformed tool resource" });
+                        return;
+                    }
+                    if (request.method === "GET") {
+                        const run = toolRunner.get(runId, id);
+                        if (!run) {
+                            toolApi(404, { error: "run not found" });
+                            return;
+                        }
+                        toolApi(200, run);
+                        return;
+                    }
+                    if (request.method === "DELETE") {
+                        const run = toolRunner.cancel(runId, id);
+                        if (!run) {
+                            toolApi(404, { error: "run not found" });
+                            return;
+                        }
+                        toolApi(200, run);
+                        return;
+                    }
+                    toolApi(405, { error: "method" });
                     return;
                 }
-                let llmId;
-                try {
-                    llmId = decodeURIComponent(llmRun[1]);
+                // ---- THE MODEL, ON THE TOOL'S OWN BEHALF ---------------------------------------------------
+                // A tool asking the model a question, over the same relative API as its Python jobs, so the frame
+                // still never learns an id, a path or a credential. Three gates, in this order:
+                //   1. the opaque sandbox origin - identical to every other tool API here;
+                //   2. the tool must CARRY the grant (`permissions.llm`), which is the thing the review card showed
+                //      the person before they accepted the file. A tool that quietly started asking the model
+                //      would be spending the user's quota from inside a sandbox they were told was isolated;
+                //   3. the run is bound to this tool id, so one frame cannot read or cancel another's answer.
+                const llmStart = /^api\/llm$/.exec(resource);
+                const llmRun = /^api\/llm\/([^/]+)$/.exec(resource);
+                if (llmStart || llmRun) {
+                    if (!toolOrigin) {
+                        toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                        return;
+                    }
+                    // GRANT FIRST, THEN RUNTIME. What a tool is allowed to ask is a fact about the tool and does not
+                    // depend on whether this machine happens to have a model, so a tool with no grant gets the same
+                    // 403 whether or not Pi is installed.
+                    if (!listed.permissions?.llm) {
+                        toolApi(403, { error: "这个工具没有调用模型的权限；注册或导入时它必须声明 permissions: { llm: true }。" });
+                        return;
+                    }
+                    if (!context.toolLlm?.available) {
+                        toolApi(503, { error: "这台机器上没有可用的 Pi 运行时，工具无法调用模型。" });
+                        return;
+                    }
+                    if (llmStart) {
+                        if (request.method === "OPTIONS") {
+                            response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                            return;
+                        }
+                        if (request.method !== "POST") {
+                            toolApi(405, { error: "method" });
+                            return;
+                        }
+                        const asked = await readRequestText(request, 64_000);
+                        if (asked.tooLarge) {
+                            toolApi(413, { error: "request too large" });
+                            return;
+                        }
+                        const raw = asked.text;
+                        try {
+                            const body = JSON.parse(raw);
+                            toolApi(202, context.toolLlm.start({ toolId: id, prompt: body.prompt ?? "", system: body.system, timeoutMs: body.timeoutMs }));
+                        }
+                        catch (error) {
+                            toolApi(400, { error: describeThrown(error) || "模型调用失败，没有拿到失败原因。" });
+                        }
+                        return;
+                    }
+                    if (request.method === "OPTIONS") {
+                        response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                        return;
+                    }
+                    let llmId;
+                    try {
+                        llmId = decodeURIComponent(llmRun[1]);
+                    }
+                    catch {
+                        toolApi(400, { error: "Malformed tool resource" });
+                        return;
+                    }
+                    if (request.method === "GET") {
+                        const run = context.toolLlm.get(llmId, id);
+                        if (!run) {
+                            toolApi(404, { error: "model call not found" });
+                            return;
+                        }
+                        toolApi(200, run);
+                        return;
+                    }
+                    if (request.method === "DELETE") {
+                        const run = context.toolLlm.cancel(llmId, id);
+                        if (!run) {
+                            toolApi(404, { error: "model call not found" });
+                            return;
+                        }
+                        toolApi(200, run);
+                        return;
+                    }
+                    toolApi(405, { error: "method" });
+                    return;
                 }
-                catch {
-                    toolApi(400, { error: "Malformed tool resource" });
+                if (resource === "super-pi-tool.js") {
+                    response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" }).end(toolBrowserSdk());
                     return;
                 }
-                if (request.method === "GET") {
-                    const run = context.toolLlm.get(llmId, id);
-                    if (!run) {
-                        toolApi(404, { error: "model call not found" });
+                try {
+                    const resolved = await toolRegistry.resolve(id, resource);
+                    if (!resolved) {
+                        response.writeHead(404).end("Tool not found");
                         return;
                     }
-                    toolApi(200, run);
+                    // Mounted tools run in an opaque sandbox origin (the iframe deliberately omits
+                    // `allow-same-origin`).  In that context CSP's `'self'` is the opaque origin and
+                    // does not authorize a request back to this server, even for a relative URL.
+                    const policy = "default-src 'self'; connect-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'";
+                    response.writeHead(200, { "content-type": MIME_TYPES[extname(resolved.file)] ?? "application/octet-stream", "cache-control": "no-store", "content-security-policy": policy });
+                    createReadStream(resolved.file).pipe(response);
                     return;
                 }
-                if (request.method === "DELETE") {
-                    const run = context.toolLlm.cancel(llmId, id);
-                    if (!run) {
-                        toolApi(404, { error: "model call not found" });
-                        return;
-                    }
-                    toolApi(200, run);
+                catch {
+                    response.writeHead(404).end("Tool file not found");
                     return;
                 }
-                toolApi(405, { error: "method" });
-                return;
-            }
-            if (resource === "super-pi-tool.js") {
-                response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" }).end(toolBrowserSdk());
-                return;
             }
-            try {
-                const resolved = await toolRegistry.resolve(id, resource);
-                if (!resolved) {
-                    response.writeHead(404).end("Tool not found");
+            /**
+             * THE TERMINAL IS NOT AN API ENDPOINT, and the routing above deliberately cannot reach one.
+             *
+             * Every command family in `CommandHandler` is answerable over plain HTTP except the terminal, which
+             * is WebSocket-only (`terminal.*` messages). `serverContext` therefore carries only the two
+             * predicates `/api/terminal` needs - is it on, and if not why - and NOT a handle on `TerminalService`.
+             * There is consequently no code path from an HTTP request to a spawned shell, which is the property
+             * worth having: the browser's own origin could not reach it even with a forged request.
+             */
+            if (url.pathname === "/api/memory/tool" || url.pathname === "/api/memory") {
+                if (!context.memory) {
+                    response.writeHead(503).end();
+                    return;
+                }
+                if ((url.pathname.endsWith("/tool") && request.method !== "POST") || !["GET", "POST"].includes(request.method ?? "")) {
+                    response.writeHead(405).end();
+                    return;
+                }
+                const origin = request.headers.origin;
+                if (origin && origin !== url.origin) {
+                    response.writeHead(403).end("Origin not allowed");
                     return;
                 }
-                // Mounted tools run in an opaque sandbox origin (the iframe deliberately omits
-                // `allow-same-origin`).  In that context CSP's `'self'` is the opaque origin and
-                // does not authorize a request back to this server, even for a relative URL.
-                const policy = "default-src 'self'; connect-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'";
-                response.writeHead(200, { "content-type": MIME_TYPES[extname(resolved.file)] ?? "application/octet-stream", "cache-control": "no-store", "content-security-policy": policy });
-                createReadStream(resolved.file).pipe(response);
-                return;
-            }
-            catch {
-                response.writeHead(404).end("Tool file not found");
-                return;
-            }
-        }
-        /**
-         * THE TERMINAL IS NOT AN API ENDPOINT, and the routing above deliberately cannot reach one.
-         *
-         * Every command family in `CommandHandler` is answerable over plain HTTP except the terminal, which
-         * is WebSocket-only (`terminal.*` messages). `serverContext` therefore carries only the two
-         * predicates `/api/terminal` needs - is it on, and if not why - and NOT a handle on `TerminalService`.
-         * There is consequently no code path from an HTTP request to a spawned shell, which is the property
-         * worth having: the browser's own origin could not reach it even with a forged request.
-         */
-        if (url.pathname === "/api/memory/tool" || url.pathname === "/api/memory") {
-            if (!context.memory) {
-                response.writeHead(503).end();
-                return;
-            }
-            if ((url.pathname.endsWith("/tool") && request.method !== "POST") || !["GET", "POST"].includes(request.method ?? "")) {
-                response.writeHead(405).end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin && origin !== url.origin) {
-                response.writeHead(403).end("Origin not allowed");
-                return;
-            }
-            try {
-                const remembered = await readRequestText(request, 512000);
-                if (remembered.tooLarge)
-                    throw new Error("记忆请求过大");
-                const raw = remembered.text;
-                const body = raw ? JSON.parse(raw) : {};
-                const result = url.pathname.endsWith("/tool")
-                    ? await context.memory.tool(String(request.headers["x-memory-capability"] ?? ""), body)
-                    : await context.memory.manage(url.searchParams.get("workspaceId") ?? "", body);
-                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
-            }
-            catch (error) {
-                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
-            }
-            return;
-        }
-        if (url.pathname === "/api/skills") {
-            const workspaceId = url.searchParams.get("workspaceId") ?? "";
-            const workspace = context.store.snapshot().workspaces.find((w) => w.id === workspaceId);
-            try {
-                const skills = await getAvailableSkills(workspace?.path, { memory: context.memory, workspaceId });
-                json(200, { skills });
-            }
-            catch (error) {
-                json(500, { error: error instanceof Error ? error.message : "获取技能失败" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/skills/read") {
-            let workspaceId = url.searchParams.get("workspaceId") ?? "";
-            let name = url.searchParams.get("name") ?? url.searchParams.get("skillId") ?? "";
-            if (request.method === "POST") {
                 try {
-                    const asked = await readRequestText(request, 512000);
-                    if (asked.tooLarge)
+                    const remembered = await readRequestText(request, 512000);
+                    if (remembered.tooLarge)
                         throw new Error("记忆请求过大");
-                    const raw = asked.text;
-                    if (raw) {
-                        const body = JSON.parse(raw);
-                        if (body.workspaceId)
-                            workspaceId = body.workspaceId;
-                        if (body.name || body.skillId)
-                            name = body.name || body.skillId;
-                    }
+                    const raw = remembered.text;
+                    const body = raw ? JSON.parse(raw) : {};
+                    const result = url.pathname.endsWith("/tool")
+                        ? await context.memory.tool(String(request.headers["x-memory-capability"] ?? ""), body)
+                        : await context.memory.manage(url.searchParams.get("workspaceId") ?? "", body);
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
                 }
-                catch {
-                    // ignore json parse error, fall back to url params
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
                 }
-            }
-            if (!name) {
-                json(400, { error: "技能名称不能为空" });
                 return;
             }
-            const workspace = context.store.snapshot().workspaces.find((w) => w.id === workspaceId);
-            try {
-                const result = await readSkill(name, workspace?.path, { memory: context.memory, workspaceId });
-                if (!result) {
-                    json(404, { error: "技能不存在" });
-                    return;
+            if (url.pathname === "/api/skills") {
+                const workspaceId = url.searchParams.get("workspaceId") ?? "";
+                const workspace = context.store.workspace(workspaceId);
+                try {
+                    const skills = await getAvailableSkills(workspace?.path, { memory: context.memory, workspaceId });
+                    json(200, { skills });
+                }
+                catch (error) {
+                    json(500, { error: error instanceof Error ? error.message : "获取技能失败" });
                 }
-                json(200, result);
-            }
-            catch (error) {
-                json(500, { error: error instanceof Error ? error.message : "读取技能失败" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/providers/fetch-models") {
-            if (request.method !== "POST") {
-                response.writeHead(405).end();
                 return;
             }
-            try {
-                const asked = await readRequestText(request, 512000);
-                if (asked.tooLarge) {
-                    json(413, { error: "请求过大" });
+            if (url.pathname === "/api/skills/read") {
+                let workspaceId = url.searchParams.get("workspaceId") ?? "";
+                let name = url.searchParams.get("name") ?? url.searchParams.get("skillId") ?? "";
+                if (request.method === "POST") {
+                    try {
+                        const asked = await readRequestText(request, 512000);
+                        if (asked.tooLarge)
+                            throw new Error("记忆请求过大");
+                        const raw = asked.text;
+                        if (raw) {
+                            const body = JSON.parse(raw);
+                            if (body.workspaceId)
+                                workspaceId = body.workspaceId;
+                            if (body.name || body.skillId)
+                                name = body.name || body.skillId;
+                        }
+                    }
+                    catch {
+                        // ignore json parse error, fall back to url params
+                    }
+                }
+                if (!name) {
+                    json(400, { error: "技能名称不能为空" });
                     return;
                 }
-                const raw = asked.text;
-                const body = raw ? JSON.parse(raw) : {};
-                const models = await context.providerService.fetchModels(body);
-                json(200, { ok: true, models });
-            }
-            catch (error) {
-                json(400, { ok: false, error: error instanceof Error ? error.message : String(error) });
-            }
-            return;
-        }
-        if (url.pathname === "/api/knowledge/tool" || url.pathname === "/api/knowledge") {
-            if (!context.knowledge) {
-                response.writeHead(503).end();
-                return;
-            }
-            if ((url.pathname.endsWith("/tool") && request.method !== "POST") || !["GET", "POST"].includes(request.method ?? "")) {
-                response.writeHead(405).end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin && origin !== url.origin) {
-                response.writeHead(403).end("Origin not allowed");
+                const workspace = context.store.workspace(workspaceId);
+                try {
+                    const result = await readSkill(name, workspace?.path, { memory: context.memory, workspaceId });
+                    if (!result) {
+                        json(404, { error: "技能不存在" });
+                        return;
+                    }
+                    json(200, result);
+                }
+                catch (error) {
+                    json(500, { error: error instanceof Error ? error.message : "读取技能失败" });
+                }
                 return;
             }
-            try {
-                let raw = "";
-                let totalBytes = 0;
-                // A pasted document rides in the body, so the cap is the document cap - past it the request is
-                // refused outright rather than truncated into a document that silently lost its tail.
-                const known = await readRequestText(request, MAX_KNOWLEDGE_REQUEST_BYTES);
-                if (known.tooLarge) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "知识库请求过大" }));
+            if (url.pathname === "/api/providers/fetch-models") {
+                if (request.method !== "POST") {
+                    response.writeHead(405).end();
                     return;
                 }
-                raw = known.text;
-                const body = raw ? JSON.parse(raw) : {};
-                const result = url.pathname.endsWith("/tool")
-                    ? await context.knowledge.tool(String(request.headers["x-knowledge-capability"] ?? ""), body, abortedAs(request))
-                    : await context.knowledge.manage(url.searchParams.get("workspaceId") ?? "", body);
-                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
-            }
-            catch (error) {
-                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
-            }
-            return;
-        }
-        if (url.pathname === "/api/documents/tool") {
-            if (!context.documentService) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (request.method !== "POST") {
-                response.writeHead(405).end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin && origin !== url.origin) {
-                response.writeHead(403).end("Origin not allowed");
+                try {
+                    const asked = await readRequestText(request, 512000);
+                    if (asked.tooLarge) {
+                        json(413, { error: "请求过大" });
+                        return;
+                    }
+                    const raw = asked.text;
+                    const body = raw ? JSON.parse(raw) : {};
+                    const models = await context.providerService.fetchModels(body);
+                    json(200, { ok: true, models });
+                }
+                catch (error) {
+                    json(400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                }
                 return;
             }
-            try {
-                let raw = "";
-                let totalBytes = 0;
-                // A DOCUMENT'S TEXT RIDES IN THE REQUEST BODY, so the cap is the document cap: a request
-                // past it is refused outright rather than truncated into a document that silently lost its
-                // tail.
-                const documented = await readRequestText(request, MAX_DOCUMENT_REQUEST_BYTES);
-                if (documented.tooLarge) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "文档请求过大" }));
+            if (url.pathname === "/api/knowledge/tool" || url.pathname === "/api/knowledge") {
+                if (!context.knowledge) {
+                    response.writeHead(503).end();
                     return;
                 }
-                raw = documented.text;
-                const body = raw ? JSON.parse(raw) : {};
-                // The capability says WHICH CONVERSATION is asking, and the workspace is derived from it
-                // rather than taken from the request: a request that named its own workspace would be a
-                // request that could read another workspace.
-                const conversationId = String(request.headers["x-documents-conversation"] ?? "");
-                const verdict = verifyCapability(conversationId, request.headers["x-documents-capability"], { running: context.runService.isRunning(conversationId) });
-                if (!verdict.ok) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
+                if ((url.pathname.endsWith("/tool") && request.method !== "POST") || !["GET", "POST"].includes(request.method ?? "")) {
+                    response.writeHead(405).end();
                     return;
                 }
-                const result = body.action === "write"
-                    ? await context.documentService.write(conversationId, String(body.path ?? ""), String(body.content ?? ""), typeof body.title === "string" ? body.title : undefined, typeof body.baseEtag === "string" ? body.baseEtag : undefined)
-                    : await context.documentService.read(conversationId, String(body.path ?? ""));
-                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
-            }
-            catch (error) {
-                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
-            }
-            return;
-        }
-        if (url.pathname === "/api/web/tool") {
-            if (!context.web) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (request.method !== "POST") {
-                response.writeHead(405).end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin && origin !== url.origin) {
-                response.writeHead(403).end("Origin not allowed");
-                return;
-            }
-            try {
-                let raw = "", totalBytes = 0;
-                const asked = await readRequestText(request, MAX_WEB_REQUEST_BYTES);
-                if (asked.tooLarge) {
-                    response.writeHead(413).end();
+                const origin = request.headers.origin;
+                if (origin && origin !== url.origin) {
+                    response.writeHead(403).end("Origin not allowed");
                     return;
                 }
-                raw = asked.text;
-                const conversationId = String(request.headers["x-web-conversation"] ?? "");
-                const verdict = verifyCapability(conversationId, request.headers["x-web-capability"], { running: context.runService.isRunning(conversationId) });
-                if (!verdict.ok) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
-                    return;
+                try {
+                    let raw = "";
+                    let totalBytes = 0;
+                    // A pasted document rides in the body, so the cap is the document cap - past it the request is
+                    // refused outright rather than truncated into a document that silently lost its tail.
+                    const known = await readRequestText(request, MAX_KNOWLEDGE_REQUEST_BYTES);
+                    if (known.tooLarge) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "知识库请求过大" }));
+                        return;
+                    }
+                    raw = known.text;
+                    const body = raw ? JSON.parse(raw) : {};
+                    const result = url.pathname.endsWith("/tool")
+                        ? await context.knowledge.tool(String(request.headers["x-knowledge-capability"] ?? ""), body, abortedAs(request))
+                        : await context.knowledge.manage(url.searchParams.get("workspaceId") ?? "", body);
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
+                }
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
                 }
-                const body = raw ? JSON.parse(raw) : {};
-                const result = body.action === "search"
-                    ? await context.web.search(String(body.query ?? ""), Number(body.limit ?? 5), abortedAs(request))
-                    : body.action === "fetch"
-                        ? await context.web.fetch(String(body.url ?? ""), abortedAs(request))
-                        : await Promise.reject(new Error("未知网页工具操作"));
-                json(200, result);
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : String(error) });
-            }
-            return;
-        }
-        if (url.pathname === "/api/feishu/tool") {
-            if (!context.feishu) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (request.method !== "POST") {
-                response.writeHead(405).end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin && origin !== url.origin) {
-                response.writeHead(403).end("Origin not allowed");
                 return;
             }
-            try {
-                let raw = "", totalBytes = 0;
-                // The Markdown of a document rides in the request body, so the cap is the document cap.
-                const asked = await readRequestText(request, MAX_FEISHU_REQUEST_BYTES);
-                if (asked.tooLarge) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "飞书请求过大" }));
+            if (url.pathname === "/api/documents/tool") {
+                if (!context.documentService) {
+                    response.writeHead(503).end();
                     return;
                 }
-                raw = asked.text;
-                const conversationId = String(request.headers["x-feishu-conversation"] ?? "");
-                // THE SAME PROOF THE DOCUMENT TOOLS USE: the request must carry the session's own
-                // capability, and the session must actually be running a turn. The Feishu credential is a
-                // company secret, so this endpoint is the only way to spend it.
-                const verdict = verifyCapability(conversationId, request.headers["x-feishu-capability"], { running: context.runService.isRunning(conversationId) });
-                if (!verdict.ok) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
+                if (request.method !== "POST") {
+                    response.writeHead(405).end();
                     return;
                 }
-                const body = raw ? JSON.parse(raw) : {};
-                json(200, await context.feishu.tool(body));
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : String(error) });
-            }
-            return;
-        }
-        /**
-         * THE FEISHU CONNECTION, as the settings panel sees it.
-         *
-         * A GET answers with what the official CLI can do right now: whether it is installed, whether
-         * it has an application, and whether a person has authorized it. It never answers with a
-         * credential - the CLI keeps those in the OS keychain, and this server never sees them.
-         *
-         * The address predicate is on the POSTs and not on the GET: connecting is a change to the
-         * machine, and the project's rule is that changes like this come from the local network.
-         * Reading whether the CLI is connected leaks nothing beyond what the panel already shows.
-         */
-        if (url.pathname === "/api/feishu/status") {
-            if (!context.feishu) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (request.method !== "GET") {
-                json(405, { error: "这个接口只接受 GET 请求。" });
-                return;
-            }
-            json(200, await context.feishu.status());
-            return;
-        }
-        /**
-         * STARTS THE CONNECT FLOW, and finishes it.
-         *
-         * The first POST asks the CLI for a device code (or for it to register an application), and
-         * answers with the URL the person has to open. The second one hands the device code back to
-         * the CLI once they have authorized it, which is where the token is written - into the keychain,
-         * not into this server.
-         *
-         * The CLI's own documentation describes exactly this two-step shape for agents, and the two
-         * calls are separate endpoints because the person has to go and do something in between.
-         */
-        if (url.pathname === "/api/feishu/connect" || url.pathname === "/api/feishu/connect/complete") {
-            if (!context.feishu) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (request.method !== "POST") {
-                json(405, { error: "这个接口只接受 POST 请求。" });
-                return;
-            }
-            if (!isLocalOrPrivateAddress(remote)) {
-                json(403, { error: "连接飞书账号只允许来自本机或局域网的请求。" });
-                return;
-            }
-            try {
-                const result = url.pathname.endsWith("/complete")
-                    ? await context.feishu.completeConnect()
-                    : await context.feishu.connect();
-                json(result.ok ? 200 : 400, result);
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : String(error) });
-            }
-            return;
-        }
-        /**
-         * CHECKS THE CONNECTION, and says why it does not work when it does not.
-         *
-         * The status already verifies the credential against Feishu, so this is the same answer shaped
-         * for a button - the difference is that a failure comes back as a MESSAGE AND A HINT rather
-         * than as a state the panel has to interpret.
-         */
-        if (url.pathname === "/api/feishu/verify" && request.method === "POST") {
-            if (!context.feishu) {
-                response.writeHead(503).end();
-                return;
-            }
-            if (!isLocalOrPrivateAddress(remote)) {
-                json(403, { error: "测试飞书连接只允许来自本机或局域网的请求。" });
-                return;
-            }
-            const result = await context.feishu.verify();
-            json(result.ok ? 200 : 400, result);
-            return;
-        }
-        if (url.pathname === "/api/shutdown") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Shutdown requires a loopback or private network POST");
-                return;
-            }
-            response.writeHead(202, { "content-type": "application/json; charset=utf-8" })
-                .end(JSON.stringify({ status: "shutting_down", message: "Server is stopping" }));
-            setTimeout(() => { void onShutdown("api-shutdown"); }, 50);
-            return;
-        }
-        if (url.pathname === "/api/update" && request.method === "POST") {
-            if (!isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403).end("Update requires a loopback or private network POST");
-                return;
-            }
-            response.writeHead(202, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ status: "updating" }));
-            // Use npm directly instead of `pi update` to avoid Windows detached+shell exit timing issues.
-            // npm's exit code correctly reflects whether the update succeeded.
-            const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-            const update = packageUpdateArgs(rootDir);
-            const child = spawn(npmCmd, update.args, { stdio: "ignore", shell: process.platform === "win32", env: process.env });
-            child.on("close", (code) => {
-                if (code === 0 || code === null) {
-                    console.log("Super Pi: npm install completed, triggering restart.");
-                    const restart = spawn(process.execPath, [join(rootDir, "scripts", "restart-server.mjs")], { cwd: rootDir, detached: true, stdio: "ignore", env: process.env });
-                    restart.on("error", (restartError) => console.error(`Super Pi: restart after update failed: ${restartError instanceof Error ? restartError.message : String(restartError)}`));
-                    restart.unref();
-                }
-                else {
-                    console.error(`Super Pi: npm install failed with code ${code}`);
+                const origin = request.headers.origin;
+                if (origin && origin !== url.origin) {
+                    response.writeHead(403).end("Origin not allowed");
+                    return;
+                }
+                try {
+                    let raw = "";
+                    let totalBytes = 0;
+                    // A DOCUMENT'S TEXT RIDES IN THE REQUEST BODY, so the cap is the document cap: a request
+                    // past it is refused outright rather than truncated into a document that silently lost its
+                    // tail.
+                    const documented = await readRequestText(request, MAX_DOCUMENT_REQUEST_BYTES);
+                    if (documented.tooLarge) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "文档请求过大" }));
+                        return;
+                    }
+                    raw = documented.text;
+                    const body = raw ? JSON.parse(raw) : {};
+                    // The capability says WHICH CONVERSATION is asking, and the workspace is derived from it
+                    // rather than taken from the request: a request that named its own workspace would be a
+                    // request that could read another workspace.
+                    const conversationId = String(request.headers["x-documents-conversation"] ?? "");
+                    const verdict = verifyCapability(conversationId, request.headers["x-documents-capability"], { running: context.runService.isRunning(conversationId) });
+                    if (!verdict.ok) {
+                        response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
+                        return;
+                    }
+                    const result = body.action === "write"
+                        ? await context.documentService.write(conversationId, String(body.path ?? ""), String(body.content ?? ""), typeof body.title === "string" ? body.title : undefined, typeof body.baseEtag === "string" ? body.baseEtag : undefined)
+                        : await context.documentService.read(conversationId, String(body.path ?? ""));
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
+                }
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
                 }
-            });
-            child.on("error", (error) => { console.warn(`Super Pi: update spawn failed: ${error instanceof Error ? error.message : "unknown error"}`); });
-            child.unref();
-            return;
-        }
-        if (url.pathname === "/api/update-check" && request.method === "GET") {
-            if (!isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403).end("Update check requires a loopback or private network request");
                 return;
             }
-            try {
-                const current = checkDiskVersion(rootDir);
-                // Query the npm registry for the latest @evandu/super-pi version.
-                const remoteVersion = await fetch("https://registry.npmjs.org/@evandu/super-pi/latest").then(async (result) => {
-                    if (!result.ok)
-                        throw new Error(`npm registry HTTP ${result.status}`);
-                    return result.json();
-                });
-                const latestVersion = typeof remoteVersion.version === "string" ? remoteVersion.version : undefined;
-                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ...current, latestVersion, updateAvailable: Boolean(latestVersion && latestVersion !== current.diskVersion) }));
-            }
-            catch (error) {
-                response.writeHead(502, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
-            }
-            return;
-        }
-        if (url.pathname === "/api/health") {
-            const version = checkDiskVersion(rootDir);
-            response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
-                .end(JSON.stringify({ status: "ok", service: "super-pi", ...version }));
-            return;
-        }
-        /**
-         * WHETHER THE TERMINAL EXISTS, as a plain GET rather than part of the `state` snapshot.
-         *
-         * It is deployment configuration, not application state: it does not change while the server runs,
-         * it is identical for every workspace, and putting it on `state` would drag it into the persistence
-         * layer and into every existing snapshot schema for no benefit. A `GET` also means the right rail
-         * can decide whether to RENDER the tab at all - and not rendering it is the point, because a tab
-         * that is present and refuses is a tab that invites a user to keep clicking a closed door.
-         *
-         * No address check: this leaks nothing beyond "is this build configured for a shell", which is
-         * already printed in the server's own startup banner to whoever can see the console.
-         */
-        if (url.pathname === "/api/terminal") {
-            const enabled = context.terminalEnabled?.() ?? false;
-            response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
-                .end(JSON.stringify({ enabled, reason: enabled ? "" : (context.terminalDisabledReason?.() ?? "终端未启用。") }));
-            return;
-        }
-        if (url.pathname === "/api/terminal-shell") {
-            const { defaultShell, shellSource, terminalShellCandidates } = await import("./terminal.js");
-            const configured = context.store.snapshot().terminalShell;
-            const shell = defaultShell(process.env, configured);
-            response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
-                .end(JSON.stringify({ shell, source: shellSource(process.env, configured), candidates: terminalShellCandidates() }));
-            return;
-        }
-        if (url.pathname === "/api/git") {
-            const json = (status, body) => response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            try {
-                const workspaceId = url.searchParams.get("workspaceId");
-                const workspace = context.store.snapshot().workspaces.find((item) => item.id === workspaceId);
-                if (!workspace) {
-                    json(404, { error: `工作区 ${workspaceId ?? "(missing)"} 不存在`, code: "no_workspace" });
+            if (url.pathname === "/api/web/tool") {
+                if (!context.web) {
+                    response.writeHead(503).end();
                     return;
                 }
-                const op = url.searchParams.get("op") ?? "status";
-                // Blame is a read with a GET shape: every other verb is refused HERE, before the POST branch
-                // could ever route the op into gitMutate and before any body is read.
-                if (op === "blame" && request.method !== "GET") {
-                    json(405, { error: "Git 请求方法不支持", code: "method" });
+                if (request.method !== "POST") {
+                    response.writeHead(405).end();
                     return;
                 }
-                if (request.method === "POST") {
-                    // A GIT WRITE IS A WRITE, AND IT GETS THE SAME GATE AS EVERY OTHER WRITE. `gitMutate` can
-                    // stage, DISCARD (`git restore -- <path>`, which throws away uncommitted work), commit,
-                    // pull and PUSH - so an endpoint that skips the address predicate hands a public caller the
-                    // keys to somebody's repository. The server listens on 0.0.0.0 by default and the global
-                    // access token is OPTIONAL (`isAuthorized` passes everyone when there is none), so this
-                    // predicate IS the boundary for every other write endpoint in this file (ledger TEST-042).
-                    if (!isLocalOrPrivateAddress(remote)) {
-                        json(403, { error: "Git 写操作只允许来自本机或局域网的请求。" });
+                const origin = request.headers.origin;
+                if (origin && origin !== url.origin) {
+                    response.writeHead(403).end("Origin not allowed");
+                    return;
+                }
+                try {
+                    let raw = "", totalBytes = 0;
+                    const asked = await readRequestText(request, MAX_WEB_REQUEST_BYTES);
+                    if (asked.tooLarge) {
+                        response.writeHead(413).end();
                         return;
                     }
-                    const asked = await readRequestText(request, 512000);
-                    if (asked.tooLarge) {
-                        json(413, { error: "请求过大" });
+                    raw = asked.text;
+                    const conversationId = String(request.headers["x-web-conversation"] ?? "");
+                    const verdict = verifyCapability(conversationId, request.headers["x-web-capability"], { running: context.runService.isRunning(conversationId) });
+                    if (!verdict.ok) {
+                        response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
                         return;
                     }
-                    const raw = asked.text;
                     const body = raw ? JSON.parse(raw) : {};
-                    json(200, await gitMutate(workspace.path, op, body.path, body.message));
+                    const result = body.action === "search"
+                        ? await context.web.search(String(body.query ?? ""), Number(body.limit ?? 5), abortedAs(request))
+                        : body.action === "fetch"
+                            ? await context.web.fetch(String(body.url ?? ""), abortedAs(request))
+                            : await Promise.reject(new Error("未知网页工具操作"));
+                    json(200, result);
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : String(error) });
+                }
+                return;
+            }
+            if (url.pathname === "/api/feishu/tool") {
+                if (!context.feishu) {
+                    response.writeHead(503).end();
                     return;
                 }
-                if (request.method !== "GET") {
-                    json(405, { error: "Git 请求方法不支持", code: "method" });
+                if (request.method !== "POST") {
+                    response.writeHead(405).end();
                     return;
                 }
-                if (op === "status")
-                    json(200, await gitStatus(workspace.path));
-                else if (op === "log")
-                    json(200, await gitLog(workspace.path, Number(url.searchParams.get("limit") ?? 20)));
-                else if (op === "diff") {
-                    const path = url.searchParams.get("path");
-                    if (!path) {
-                        json(400, { error: "diff 需要 path", code: "bad_path" });
+                const origin = request.headers.origin;
+                if (origin && origin !== url.origin) {
+                    response.writeHead(403).end("Origin not allowed");
+                    return;
+                }
+                try {
+                    let raw = "", totalBytes = 0;
+                    // The Markdown of a document rides in the request body, so the cap is the document cap.
+                    const asked = await readRequestText(request, MAX_FEISHU_REQUEST_BYTES);
+                    if (asked.tooLarge) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "飞书请求过大" }));
                         return;
                     }
-                    json(200, await gitDiff(workspace.path, path, url.searchParams.get("staged") === "1"));
-                }
-                else if (op === "blame") {
-                    const path = url.searchParams.get("path");
-                    if (!path) {
-                        json(400, { error: "blame 需要 path", code: "bad_path" });
+                    raw = asked.text;
+                    const conversationId = String(request.headers["x-feishu-conversation"] ?? "");
+                    // THE SAME PROOF THE DOCUMENT TOOLS USE: the request must carry the session's own
+                    // capability, and the session must actually be running a turn. The Feishu credential is a
+                    // company secret, so this endpoint is the only way to spend it.
+                    const verdict = verifyCapability(conversationId, request.headers["x-feishu-capability"], { running: context.runService.isRunning(conversationId) });
+                    if (!verdict.ok) {
+                        response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
                         return;
                     }
-                    const startLine = url.searchParams.get("startLine");
-                    const endLine = url.searchParams.get("endLine");
-                    json(200, await gitBlame(workspace.path, path, {
-                        revision: url.searchParams.get("revision") ?? undefined,
-                        startLine: startLine === null ? undefined : Number(startLine),
-                        endLine: endLine === null ? undefined : Number(endLine),
-                    }));
+                    const body = raw ? JSON.parse(raw) : {};
+                    json(200, await context.feishu.tool(body));
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : String(error) });
                 }
-                else
-                    json(400, { error: "未知 Git 操作", code: "bad_op" });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : "Git 读取失败";
-                const code = error?.code;
-                if (code === 128 || code === "not_a_repo" || /not a git repository/i.test(message))
-                    json(404, { error: "此工作区不是 git 仓库", code: "not_a_repo" });
-                else if (code === "path")
-                    json(400, { error: message, code: "bad_path" });
-                else if (code === "not_found")
-                    json(404, { error: message, code: "not_found" });
-                else if (code === "bad_range" || code === "bad_revision")
-                    json(400, { error: message, code });
-                else
-                    json(400, { error: message, code: "git_error" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/subagent/dispatch") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Sub-agent dispatch requires a loopback or private network POST");
                 return;
             }
-            let raw = "";
-            let totalBytes = 0;
-            const reader = textBodyReader();
-            for await (const chunk of request) {
-                const piece = chunk;
-                totalBytes += piece.length;
-                if (totalBytes > MAX_FILE_BYTES * 2) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
-                    request.destroy();
+            /**
+             * THE FEISHU CONNECTION, as the settings panel sees it.
+             *
+             * A GET answers with what the official CLI can do right now: whether it is installed, whether
+             * it has an application, and whether a person has authorized it. It never answers with a
+             * credential - the CLI keeps those in the OS keychain, and this server never sees them.
+             *
+             * The address predicate is on the POSTs and not on the GET: connecting is a change to the
+             * machine, and the project's rule is that changes like this come from the local network.
+             * Reading whether the CLI is connected leaks nothing beyond what the panel already shows.
+             */
+            if (url.pathname === "/api/feishu/status") {
+                if (!context.feishu) {
+                    response.writeHead(503).end();
                     return;
                 }
-                raw = reader.push(piece);
+                if (request.method !== "GET") {
+                    json(405, { error: "这个接口只接受 GET 请求。" });
+                    return;
+                }
+                json(200, await context.feishu.status());
+                return;
             }
-            raw = reader.finish();
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const body = JSON.parse(raw);
-                const result = await runService.dispatchTask(body);
-                json(result.status, result.body);
+            /**
+             * STARTS THE CONNECT FLOW, and finishes it.
+             *
+             * The first POST asks the CLI for a device code (or for it to register an application), and
+             * answers with the URL the person has to open. The second one hands the device code back to
+             * the CLI once they have authorized it, which is where the token is written - into the keychain,
+             * not into this server.
+             *
+             * The CLI's own documentation describes exactly this two-step shape for agents, and the two
+             * calls are separate endpoints because the person has to go and do something in between.
+             */
+            if (url.pathname === "/api/feishu/connect" || url.pathname === "/api/feishu/connect/complete") {
+                if (!context.feishu) {
+                    response.writeHead(503).end();
+                    return;
+                }
+                if (request.method !== "POST") {
+                    json(405, { error: "这个接口只接受 POST 请求。" });
+                    return;
+                }
+                if (!isLocalOrPrivateAddress(remote)) {
+                    json(403, { error: "连接飞书账号只允许来自本机或局域网的请求。" });
+                    return;
+                }
+                try {
+                    const result = url.pathname.endsWith("/complete")
+                        ? await context.feishu.completeConnect()
+                        : await context.feishu.connect();
+                    json(result.ok ? 200 : 400, result);
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : String(error) });
+                }
+                return;
             }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : "task dispatch failed" });
+            /**
+             * CHECKS THE CONNECTION, and says why it does not work when it does not.
+             *
+             * The status already verifies the credential against Feishu, so this is the same answer shaped
+             * for a button - the difference is that a failure comes back as a MESSAGE AND A HINT rather
+             * than as a state the panel has to interpret.
+             */
+            if (url.pathname === "/api/feishu/verify" && request.method === "POST") {
+                if (!context.feishu) {
+                    response.writeHead(503).end();
+                    return;
+                }
+                if (!isLocalOrPrivateAddress(remote)) {
+                    json(403, { error: "测试飞书连接只允许来自本机或局域网的请求。" });
+                    return;
+                }
+                const result = await context.feishu.verify();
+                json(result.ok ? 200 : 400, result);
+                return;
             }
-            return;
-        }
-        /**
-         * Lightweight background command execution, independent from subagent dispatch.
-         * POST with { cmd, cwd, conversationId, capability } -> 202 { sessionId, status: "running" }
-         * Result is delivered via WebSocket exec.exit event and injected into the conversation.
-         */
-        if (url.pathname === "/api/exec") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Exec requires a loopback or private network POST");
+            if (url.pathname === "/api/shutdown") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Shutdown requires a loopback or private network POST");
+                    return;
+                }
+                response.writeHead(202, { "content-type": "application/json; charset=utf-8" })
+                    .end(JSON.stringify({ status: "shutting_down", message: "Server is stopping" }));
+                setTimeout(() => { void onShutdown("api-shutdown"); }, 50);
                 return;
             }
-            if (!execService) {
-                response.writeHead(503, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "后台命令服务没有启用。", code: "unavailable" }));
+            if (url.pathname === "/api/update" && request.method === "POST") {
+                if (!isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403).end("Update requires a loopback or private network POST");
+                    return;
+                }
+                response.writeHead(202, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ status: "updating" }));
+                // Use npm directly instead of `pi update` to avoid Windows detached+shell exit timing issues.
+                // npm's exit code correctly reflects whether the update succeeded.
+                const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+                const update = packageUpdateArgs(rootDir);
+                const child = spawn(npmCmd, update.args, { stdio: "ignore", shell: process.platform === "win32", env: process.env });
+                child.on("close", (code) => {
+                    if (code === 0 || code === null) {
+                        console.log("Super Pi: npm install completed, triggering restart.");
+                        const restart = spawn(process.execPath, [join(rootDir, "scripts", "restart-server.mjs")], { cwd: rootDir, detached: true, stdio: "ignore", env: process.env });
+                        restart.on("error", (restartError) => console.error(`Super Pi: restart after update failed: ${restartError instanceof Error ? restartError.message : String(restartError)}`));
+                        restart.unref();
+                    }
+                    else {
+                        console.error(`Super Pi: npm install failed with code ${code}`);
+                    }
+                });
+                child.on("error", (error) => { console.warn(`Super Pi: update spawn failed: ${error instanceof Error ? error.message : "unknown error"}`); });
+                child.unref();
                 return;
             }
-            let raw = "";
-            let totalBytes = 0;
-            const reader = textBodyReader();
-            for await (const chunk of request) {
-                const piece = chunk;
-                totalBytes += piece.length;
-                if (totalBytes > MAX_FILE_BYTES * 2) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
-                    request.destroy();
+            if (url.pathname === "/api/update-check" && request.method === "GET") {
+                if (!isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403).end("Update check requires a loopback or private network request");
                     return;
                 }
-                raw = reader.push(piece);
-            }
-            raw = reader.finish();
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            let body;
-            try {
-                body = JSON.parse(raw);
+                try {
+                    const current = checkDiskVersion(rootDir);
+                    // Query the npm registry for the latest @evandu/super-pi version.
+                    const remoteVersion = await fetch("https://registry.npmjs.org/@evandu/super-pi/latest").then(async (result) => {
+                        if (!result.ok)
+                            throw new Error(`npm registry HTTP ${result.status}`);
+                        return result.json();
+                    });
+                    const latestVersion = typeof remoteVersion.version === "string" ? remoteVersion.version : undefined;
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ...current, latestVersion, updateAvailable: Boolean(latestVersion && latestVersion !== current.diskVersion) }));
+                }
+                catch (error) {
+                    response.writeHead(502, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
             }
-            catch {
-                json(400, { error: "请求体不是合法的 JSON。" });
+            if (url.pathname === "/api/health") {
+                const version = checkDiskVersion(rootDir);
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
+                    .end(JSON.stringify({ status: "ok", service: "super-pi", ...version }));
                 return;
             }
-            const { cmd, description, cwd, conversationId, capability, toolCallId } = body;
-            if (!cmd || !cwd || !conversationId) {
-                json(400, { error: "需要 cmd、cwd 和 conversationId。" });
+            /**
+             * WHETHER THE TERMINAL EXISTS, as a plain GET rather than part of the `state` snapshot.
+             *
+             * It is deployment configuration, not application state: it does not change while the server runs,
+             * it is identical for every workspace, and putting it on `state` would drag it into the persistence
+             * layer and into every existing snapshot schema for no benefit. A `GET` also means the right rail
+             * can decide whether to RENDER the tab at all - and not rendering it is the point, because a tab
+             * that is present and refuses is a tab that invites a user to keep clicking a closed door.
+             *
+             * No address check: this leaks nothing beyond "is this build configured for a shell", which is
+             * already printed in the server's own startup banner to whoever can see the console.
+             */
+            if (url.pathname === "/api/terminal") {
+                const enabled = context.terminalEnabled?.() ?? false;
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
+                    .end(JSON.stringify({ enabled, reason: enabled ? "" : (context.terminalDisabledReason?.() ?? "终端未启用。") }));
                 return;
             }
-            // Verify both the credential and RunService's authoritative active-turn state.
-            const result = runService.verifyPrimaryCapability(conversationId, capability);
-            if (!result.ok) {
-                json(403, { error: result.message });
+            if (url.pathname === "/api/terminal-shell") {
+                const { defaultShell, shellSource, terminalShellCandidates } = await import("./terminal.js");
+                const configured = context.store.snapshot().terminalShell;
+                const shell = defaultShell(process.env, configured);
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
+                    .end(JSON.stringify({ shell, source: shellSource(process.env, configured), candidates: terminalShellCandidates() }));
                 return;
             }
-            // The `cwd` here is the directory the Pi child was launched in - which is the conversation's
-            // workspace, already authenticated by the per-conversation capability check above. Validating it
-            // against the workspace list looked cheap, but Windows path normalization (8.3 short names, UNC
-            // prefixes, drive-letter case, separator styles) routinely produces the same path in two different
-            // strings and a strict equality check refused valid calls; a relaxed comparison is no longer
-            // providing a security boundary that the capability check is not already providing. The trust
-            // decision is the one above; this stays as a no-op.
-            void cwd;
-            // Set up the background task record BEFORE spawning, so the UI shows it immediately
-            const { randomUUID } = await import("node:crypto");
-            const sessionId = `exec_${randomUUID()}`;
-            // The same anchor a sub-agent card carries, for the same reason: a background command asked for
-            // inside a turn belongs at that call. Resolved AFTER the capability check above, because a position
-            // is worth reading only from a caller already inside the turn.
-            const origin = await runService.waitForToolCall(conversationId, toolCallId);
-            await store.setBackgroundTask({
-                id: sessionId,
-                conversationId,
-                title: description?.trim() || (cmd.length > 60 ? cmd.slice(0, 60) + "…" : cmd),
-                agentId: "exec",
-                status: "running",
-                startedAt: new Date().toISOString(),
-                resultBlockId: sessionId,
-                ...(origin ? origin : {}),
-            });
-            if (origin) {
-                const toolCalls = await store.updateToolCall(conversationId, origin.originMessageId, origin.originCallRow, { backgroundTask: { id: sessionId, status: "running" } });
-                broadcaster.broadcast({ type: "message.tools", conversationId, messageId: origin.originMessageId, toolCalls });
+            if (url.pathname === "/api/git") {
+                const json = (status, body) => response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                try {
+                    const workspaceId = url.searchParams.get("workspaceId");
+                    const workspace = workspaceId ? context.store.workspace(workspaceId) : undefined;
+                    if (!workspace) {
+                        json(404, { error: `工作区 ${workspaceId ?? "(missing)"} 不存在`, code: "no_workspace" });
+                        return;
+                    }
+                    const op = url.searchParams.get("op") ?? "status";
+                    // Blame is a read with a GET shape: every other verb is refused HERE, before the POST branch
+                    // could ever route the op into gitMutate and before any body is read.
+                    if (op === "blame" && request.method !== "GET") {
+                        json(405, { error: "Git 请求方法不支持", code: "method" });
+                        return;
+                    }
+                    if (request.method === "POST") {
+                        // A GIT WRITE IS A WRITE, AND IT GETS THE SAME GATE AS EVERY OTHER WRITE. `gitMutate` can
+                        // stage, DISCARD (`git restore -- <path>`, which throws away uncommitted work), commit,
+                        // pull and PUSH - so an endpoint that skips the address predicate hands a public caller the
+                        // keys to somebody's repository. The server listens on 0.0.0.0 by default and the global
+                        // access token is OPTIONAL (`isAuthorized` passes everyone when there is none), so this
+                        // predicate IS the boundary for every other write endpoint in this file (ledger TEST-042).
+                        if (!isLocalOrPrivateAddress(remote)) {
+                            json(403, { error: "Git 写操作只允许来自本机或局域网的请求。" });
+                            return;
+                        }
+                        const asked = await readRequestText(request, 512000);
+                        if (asked.tooLarge) {
+                            json(413, { error: "请求过大" });
+                            return;
+                        }
+                        const raw = asked.text;
+                        const body = raw ? JSON.parse(raw) : {};
+                        json(200, await gitMutate(workspace.path, op, body.path, body.message));
+                        return;
+                    }
+                    if (request.method !== "GET") {
+                        json(405, { error: "Git 请求方法不支持", code: "method" });
+                        return;
+                    }
+                    if (op === "status")
+                        json(200, await gitStatus(workspace.path));
+                    else if (op === "log")
+                        json(200, await gitLog(workspace.path, Number(url.searchParams.get("limit") ?? 20)));
+                    else if (op === "diff") {
+                        const path = url.searchParams.get("path");
+                        if (!path) {
+                            json(400, { error: "diff 需要 path", code: "bad_path" });
+                            return;
+                        }
+                        json(200, await gitDiff(workspace.path, path, url.searchParams.get("staged") === "1"));
+                    }
+                    else if (op === "blame") {
+                        const path = url.searchParams.get("path");
+                        if (!path) {
+                            json(400, { error: "blame 需要 path", code: "bad_path" });
+                            return;
+                        }
+                        const startLine = url.searchParams.get("startLine");
+                        const endLine = url.searchParams.get("endLine");
+                        json(200, await gitBlame(workspace.path, path, {
+                            revision: url.searchParams.get("revision") ?? undefined,
+                            startLine: startLine === null ? undefined : Number(startLine),
+                            endLine: endLine === null ? undefined : Number(endLine),
+                        }));
+                    }
+                    else
+                        json(400, { error: "未知 Git 操作", code: "bad_op" });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : "Git 读取失败";
+                    const code = error?.code;
+                    if (code === 128 || code === "not_a_repo" || /not a git repository/i.test(message))
+                        json(404, { error: "此工作区不是 git 仓库", code: "not_a_repo" });
+                    else if (code === "path")
+                        json(400, { error: message, code: "bad_path" });
+                    else if (code === "not_found")
+                        json(404, { error: message, code: "not_found" });
+                    else if (code === "bad_range" || code === "bad_revision")
+                        json(400, { error: message, code });
+                    else
+                        json(400, { error: message, code: "git_error" });
+                }
+                return;
             }
-            broadcaster.broadcastState();
-            try {
-                execService.spawn(sessionId, cmd, cwd);
-                json(202, { sessionId, status: "running" });
+            if (url.pathname === "/api/subagent/dispatch") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Sub-agent dispatch requires a loopback or private network POST");
+                    return;
+                }
+                let raw = "";
+                let totalBytes = 0;
+                const reader = textBodyReader();
+                for await (const chunk of request) {
+                    const piece = chunk;
+                    totalBytes += piece.length;
+                    if (totalBytes > MAX_FILE_BYTES * 2) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                        request.destroy();
+                        return;
+                    }
+                    raw = reader.push(piece);
+                }
+                raw = reader.finish();
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const body = JSON.parse(raw);
+                    const result = await runService.dispatchTask(body);
+                    json(result.status, result.body);
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "task dispatch failed" });
+                }
+                return;
             }
-            catch (error) {
+            /**
+             * Lightweight background command execution, independent from subagent dispatch.
+             * POST with { cmd, cwd, conversationId, capability } -> 202 { sessionId, status: "running" }
+             * Result is delivered via WebSocket exec.exit event and injected into the conversation.
+             */
+            if (url.pathname === "/api/exec") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Exec requires a loopback or private network POST");
+                    return;
+                }
+                if (!execService) {
+                    response.writeHead(503, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "后台命令服务没有启用。", code: "unavailable" }));
+                    return;
+                }
+                let raw = "";
+                let totalBytes = 0;
+                const reader = textBodyReader();
+                for await (const chunk of request) {
+                    const piece = chunk;
+                    totalBytes += piece.length;
+                    if (totalBytes > MAX_FILE_BYTES * 2) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                        request.destroy();
+                        return;
+                    }
+                    raw = reader.push(piece);
+                }
+                raw = reader.finish();
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    json(400, { error: "请求体不是合法的 JSON。" });
+                    return;
+                }
+                const { cmd, description, cwd, conversationId, capability, toolCallId } = body;
+                if (!cmd || !cwd || !conversationId) {
+                    json(400, { error: "需要 cmd、cwd 和 conversationId。" });
+                    return;
+                }
+                // Verify both the credential and RunService's authoritative active-turn state.
+                const result = runService.verifyPrimaryCapability(conversationId, capability);
+                if (!result.ok) {
+                    json(403, { error: result.message });
+                    return;
+                }
+                // The `cwd` here is the directory the Pi child was launched in - which is the conversation's
+                // workspace, already authenticated by the per-conversation capability check above. Validating it
+                // against the workspace list looked cheap, but Windows path normalization (8.3 short names, UNC
+                // prefixes, drive-letter case, separator styles) routinely produces the same path in two different
+                // strings and a strict equality check refused valid calls; a relaxed comparison is no longer
+                // providing a security boundary that the capability check is not already providing. The trust
+                // decision is the one above; this stays as a no-op.
+                void cwd;
+                // Set up the background task record BEFORE spawning, so the UI shows it immediately
+                const { randomUUID } = await import("node:crypto");
+                const sessionId = `exec_${randomUUID()}`;
+                // The same anchor a sub-agent card carries, for the same reason: a background command asked for
+                // inside a turn belongs at that call. Resolved AFTER the capability check above, because a position
+                // is worth reading only from a caller already inside the turn.
+                const origin = await runService.waitForToolCall(conversationId, toolCallId);
+                await store.setBackgroundTask({
+                    id: sessionId,
+                    conversationId,
+                    title: description?.trim() || (cmd.length > 60 ? cmd.slice(0, 60) + "…" : cmd),
+                    agentId: "exec",
+                    status: "running",
+                    startedAt: new Date().toISOString(),
+                    resultBlockId: sessionId,
+                    ...(origin ? origin : {}),
+                });
                 if (origin) {
-                    const toolCalls = await store.updateToolCall(conversationId, origin.originMessageId, origin.originCallRow, { backgroundTask: { id: sessionId, status: "failed", output: error instanceof Error ? error.message : "spawn failed" } });
+                    const toolCalls = await store.updateToolCall(conversationId, origin.originMessageId, origin.originCallRow, { backgroundTask: { id: sessionId, status: "running" } });
                     broadcaster.broadcast({ type: "message.tools", conversationId, messageId: origin.originMessageId, toolCalls });
                 }
-                await store.removeBackgroundTask(sessionId);
                 broadcaster.broadcastState();
-                json(500, { error: error instanceof Error ? error.message : "spawn failed" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/workflow/run") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Workflow dispatch requires a loopback or private network POST");
+                try {
+                    execService.spawn(sessionId, cmd, cwd);
+                    json(202, { sessionId, status: "running" });
+                }
+                catch (error) {
+                    if (origin) {
+                        const toolCalls = await store.updateToolCall(conversationId, origin.originMessageId, origin.originCallRow, { backgroundTask: { id: sessionId, status: "failed", output: error instanceof Error ? error.message : "spawn failed" } });
+                        broadcaster.broadcast({ type: "message.tools", conversationId, messageId: origin.originMessageId, toolCalls });
+                    }
+                    await store.removeBackgroundTask(sessionId);
+                    broadcaster.broadcastState();
+                    json(500, { error: error instanceof Error ? error.message : "spawn failed" });
+                }
                 return;
             }
-            let raw = "";
-            let totalBytes = 0;
-            const reader = textBodyReader();
-            for await (const chunk of request) {
-                const piece = chunk;
-                totalBytes += piece.length;
-                if (totalBytes > MAX_FILE_BYTES * 2) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
-                    request.destroy();
+            if (url.pathname === "/api/workflow/run") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Workflow dispatch requires a loopback or private network POST");
                     return;
                 }
-                raw = reader.push(piece);
-            }
-            raw = reader.finish();
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const result = await runService.runWorkflow(JSON.parse(raw));
-                json(result.status, result.body);
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : "workflow dispatch failed" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/todos") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Todo writes require a loopback or private network POST");
+                let raw = "";
+                let totalBytes = 0;
+                const reader = textBodyReader();
+                for await (const chunk of request) {
+                    const piece = chunk;
+                    totalBytes += piece.length;
+                    if (totalBytes > MAX_FILE_BYTES * 2) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                        request.destroy();
+                        return;
+                    }
+                    raw = reader.push(piece);
+                }
+                raw = reader.finish();
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const result = await runService.runWorkflow(JSON.parse(raw));
+                    json(result.status, result.body);
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "workflow dispatch failed" });
+                }
                 return;
             }
-            let raw = "";
-            let totalBytes = 0;
-            const reader = textBodyReader();
-            for await (const chunk of request) {
-                const piece = chunk;
-                totalBytes += piece.length;
-                if (totalBytes > MAX_FILE_BYTES * 2) {
-                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
-                    request.destroy();
+            if (url.pathname === "/api/todos") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Todo writes require a loopback or private network POST");
                     return;
                 }
-                raw = reader.push(piece);
+                let raw = "";
+                let totalBytes = 0;
+                const reader = textBodyReader();
+                for await (const chunk of request) {
+                    const piece = chunk;
+                    totalBytes += piece.length;
+                    if (totalBytes > MAX_FILE_BYTES * 2) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                        request.destroy();
+                        return;
+                    }
+                    raw = reader.push(piece);
+                }
+                raw = reader.finish();
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const body = JSON.parse(raw);
+                    const conversationId = body.conversationId?.trim();
+                    if (!conversationId)
+                        throw new Error("todowrite requires conversationId");
+                    const verdict = runService.verifyPrimaryCapability(conversationId, body.capability);
+                    if (!verdict.ok) {
+                        json(403, { error: verdict.message });
+                        return;
+                    }
+                    const { todos, dropped } = await store.setTodos(conversationId, body.todos);
+                    broadcaster.broadcastState();
+                    json(200, { todos, dropped, conversationId });
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "todo write failed" });
+                }
+                return;
             }
-            raw = reader.finish();
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const body = JSON.parse(raw);
-                const conversationId = body.conversationId?.trim();
-                if (!conversationId)
-                    throw new Error("todowrite requires conversationId");
-                const verdict = runService.verifyPrimaryCapability(conversationId, body.capability);
-                if (!verdict.ok) {
-                    json(403, { error: verdict.message });
+            if (url.pathname === "/api/scheduled-tasks") {
+                // THE AGENT'S DOOR TO THE SCHEDULED TASKS, and the same shape as `/api/todos`: exempt from the
+                // global token because the caller proves itself with a per-conversation capability instead, and
+                // restricted to loopback or a private network for the same reason `/api/todos` is.
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Scheduled task writes require a loopback or private network POST");
                     return;
                 }
-                const { todos, dropped } = await store.setTodos(conversationId, body.todos);
-                broadcaster.broadcastState();
-                json(200, { todos, dropped, conversationId });
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : "todo write failed" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/scheduled-tasks") {
-            // THE AGENT'S DOOR TO THE SCHEDULED TASKS, and the same shape as `/api/todos`: exempt from the
-            // global token because the caller proves itself with a per-conversation capability instead, and
-            // restricted to loopback or a private network for the same reason `/api/todos` is.
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Scheduled task writes require a loopback or private network POST");
+                let raw = "";
+                let totalBytes = 0;
+                const reader = textBodyReader();
+                for await (const chunk of request) {
+                    const piece = chunk;
+                    totalBytes += piece.length;
+                    if (totalBytes > MAX_FILE_BYTES * 2) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                        request.destroy();
+                        return;
+                    }
+                    raw = reader.push(piece);
+                }
+                raw = reader.finish();
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const body = JSON.parse(raw);
+                    const conversationId = body.conversationId?.trim();
+                    if (!conversationId)
+                        throw new Error("scheduled_task requires conversationId");
+                    const verdict = runService.verifyPrimaryCapability(conversationId, body.capability);
+                    if (!verdict.ok) {
+                        json(403, { error: verdict.message });
+                        return;
+                    }
+                    const service = context.scheduledTaskService;
+                    if (!service) {
+                        json(503, { error: "定时任务功能在这个实例上没有启用。" });
+                        return;
+                    }
+                    // THE WORKSPACE IS THE CALLER'S, not the agent's choice. The conversation the turn belongs to
+                    // decides where the task runs and what its defaults are; a task could otherwise be filed under
+                    // a workspace its own author cannot see.
+                    const workspaceId = conversationWorkspace(store.snapshot(), conversationId).id;
+                    const action = (body.action ?? "create").trim();
+                    if (action === "list") {
+                        json(200, { tasks: service.listForWorkspace(workspaceId) });
+                        return;
+                    }
+                    if (action === "create") {
+                        const task = await service.create({
+                            name: body.name,
+                            prompt: body.prompt,
+                            schedule: body.schedule,
+                            workspaceId,
+                            model: body.model ? { provider: body.model.provider, modelId: body.model.modelId, label: body.model.label ?? body.model.modelId } : null,
+                            agentId: body.agentId,
+                        }, "agent");
+                        json(200, { task, describe: describeSchedule(task.schedule) });
+                        return;
+                    }
+                    if (action === "update") {
+                        const id = body.id?.trim();
+                        if (!id)
+                            throw new Error("scheduled_task update requires an id");
+                        // THE TASK MUST BE THE CALLER'S TO CHANGE. A task runs in a workspace: it opens its
+                        // conversation there, uses that workspace's defaults and its tools. The caller cannot even
+                        // LIST another workspace's tasks (`list` is scoped), so it must not be able to change or
+                        // delete them either - and the refusal must not say "it exists, over there".
+                        service.requireForWorkspace(id, workspaceId);
+                        const task = await service.update(id, {
+                            name: body.name,
+                            prompt: body.prompt,
+                            schedule: body.schedule,
+                            // "NOT MENTIONED" AND "CLEARED" ARE DIFFERENT REQUESTS. The extension only sends the
+                            // fields the model actually wrote, so a model that changes the prompt and says nothing
+                            // about the model leaves the key ABSENT - and the service reads an absent model as
+                            // "keep what is there". Mapping absence to null made "not mentioned" mean "delete", so a
+                            // model the user had picked for this task was silently dropped and the task fell back to
+                            // the default model (measured by scripts/scheduled-task-scope.test.mjs, ledger
+                            // TEST-025). Every other field here already has this asymmetry right: name, prompt,
+                            // schedule and agentId are all "absent means unchanged".
+                            model: body.model === undefined
+                                ? undefined
+                                : (body.model ? { provider: body.model.provider, modelId: body.model.modelId, label: body.model.label ?? body.model.modelId } : null),
+                            agentId: body.agentId,
+                        });
+                        json(200, { task, describe: describeSchedule(task.schedule) });
+                        return;
+                    }
+                    if (action === "delete") {
+                        const id = body.id?.trim();
+                        if (!id)
+                            throw new Error("scheduled_task delete requires an id");
+                        service.requireForWorkspace(id, workspaceId);
+                        await service.remove(id);
+                        json(200, { deleted: id });
+                        return;
+                    }
+                    json(400, { error: "action 只能是 create、list、update 或 delete。" });
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "scheduled task request failed" });
+                }
                 return;
             }
-            let raw = "";
-            let totalBytes = 0;
-            const reader = textBodyReader();
-            for await (const chunk of request) {
-                const piece = chunk;
-                totalBytes += piece.length;
-                if (totalBytes > MAX_FILE_BYTES * 2) {
+            if (url.pathname === "/api/orchestrator") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Orchestrator requires a loopback or private network POST");
+                    return;
+                }
+                const asked = await readRequestText(request, MAX_FILE_BYTES * 2);
+                if (asked.tooLarge) {
                     response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
-                    request.destroy();
                     return;
                 }
-                raw = reader.push(piece);
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const body = JSON.parse(asked.text);
+                    const service = context.sessionOrchestratorService;
+                    if (!service) {
+                        json(503, { error: "编排服务未就绪" });
+                        return;
+                    }
+                    if (body.capability && body.parentConversationId) {
+                        const verdict = runService.verifyPrimaryCapability(body.parentConversationId, body.capability);
+                        if (!verdict.ok) {
+                            json(403, { error: verdict.message });
+                            return;
+                        }
+                    }
+                    else if (context.accessToken && !isAuthorized(request, context.accessToken)) {
+                        json(401, { error: "未授权" });
+                        return;
+                    }
+                    const action = (body.action || "").trim();
+                    if (action === "spawn") {
+                        if (!body.task)
+                            throw new Error("spawn requires task");
+                        const result = await service.spawn({
+                            task: body.task,
+                            parentConversationId: body.parentConversationId,
+                            workspaceId: body.workspaceId,
+                            title: body.title,
+                            agentId: body.agentId,
+                            model: body.model,
+                            thinkingLevel: body.thinkingLevel,
+                            initialPrompt: body.initialPrompt,
+                            wait: body.wait,
+                        });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
+                    if (action === "dispatch") {
+                        if (!body.conversationId)
+                            throw new Error("dispatch requires conversationId");
+                        if (!body.content)
+                            throw new Error("dispatch requires content");
+                        const result = await service.dispatch(body.conversationId, body.content, { wait: body.wait });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
+                    if (action === "status") {
+                        if (!body.conversationId)
+                            throw new Error("status requires conversationId");
+                        const summary = await service.status(body.conversationId);
+                        json(200, { ok: true, summary });
+                        return;
+                    }
+                    if (action === "list") {
+                        const sessions = await service.list(body.parentConversationId);
+                        json(200, { ok: true, sessions });
+                        return;
+                    }
+                    if (action === "stop") {
+                        if (!body.conversationId)
+                            throw new Error("stop requires conversationId");
+                        const result = await service.stop(body.conversationId, { mode: body.mode, messageId: body.messageId });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
+                    if (action === "resume") {
+                        if (!body.conversationId)
+                            throw new Error("resume requires conversationId");
+                        const result = await service.resume(body.conversationId, body.prompt, { wait: body.wait });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
+                    json(400, { error: `不支持的编排操作：${action}` });
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "orchestrator request failed" });
+                }
+                return;
             }
-            raw = reader.finish();
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const body = JSON.parse(raw);
-                const conversationId = body.conversationId?.trim();
-                if (!conversationId)
-                    throw new Error("scheduled_task requires conversationId");
-                const verdict = runService.verifyPrimaryCapability(conversationId, body.capability);
-                if (!verdict.ok) {
-                    json(403, { error: verdict.message });
+            if (url.pathname === "/api/orchestrator/status" && request.method === "GET") {
+                if (!isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403).end();
                     return;
                 }
-                const service = context.scheduledTaskService;
+                const service = context.sessionOrchestratorService;
                 if (!service) {
-                    json(503, { error: "定时任务功能在这个实例上没有启用。" });
-                    return;
-                }
-                // THE WORKSPACE IS THE CALLER'S, not the agent's choice. The conversation the turn belongs to
-                // decides where the task runs and what its defaults are; a task could otherwise be filed under
-                // a workspace its own author cannot see.
-                const workspaceId = conversationWorkspace(store.snapshot(), conversationId).id;
-                const action = (body.action ?? "create").trim();
-                if (action === "list") {
-                    json(200, { tasks: service.listForWorkspace(workspaceId) });
+                    response.writeHead(503, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "编排服务未就绪" }));
                     return;
                 }
-                if (action === "create") {
-                    const task = await service.create({
-                        name: body.name,
-                        prompt: body.prompt,
-                        schedule: body.schedule,
-                        workspaceId,
-                        model: body.model ? { provider: body.model.provider, modelId: body.model.modelId, label: body.model.label ?? body.model.modelId } : null,
-                        agentId: body.agentId,
-                    }, "agent");
-                    json(200, { task, describe: describeSchedule(task.schedule) });
+                const conversationId = url.searchParams.get("conversationId");
+                if (!conversationId) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "缺少 conversationId" }));
                     return;
                 }
-                if (action === "update") {
-                    const id = body.id?.trim();
-                    if (!id)
-                        throw new Error("scheduled_task update requires an id");
-                    // THE TASK MUST BE THE CALLER'S TO CHANGE. A task runs in a workspace: it opens its
-                    // conversation there, uses that workspace's defaults and its tools. The caller cannot even
-                    // LIST another workspace's tasks (`list` is scoped), so it must not be able to change or
-                    // delete them either - and the refusal must not say "it exists, over there".
-                    service.requireForWorkspace(id, workspaceId);
-                    const task = await service.update(id, {
-                        name: body.name,
-                        prompt: body.prompt,
-                        schedule: body.schedule,
-                        // "NOT MENTIONED" AND "CLEARED" ARE DIFFERENT REQUESTS. The extension only sends the
-                        // fields the model actually wrote, so a model that changes the prompt and says nothing
-                        // about the model leaves the key ABSENT - and the service reads an absent model as
-                        // "keep what is there". Mapping absence to null made "not mentioned" mean "delete", so a
-                        // model the user had picked for this task was silently dropped and the task fell back to
-                        // the default model (measured by scripts/scheduled-task-scope.test.mjs, ledger
-                        // TEST-025). Every other field here already has this asymmetry right: name, prompt,
-                        // schedule and agentId are all "absent means unchanged".
-                        model: body.model === undefined
-                            ? undefined
-                            : (body.model ? { provider: body.model.provider, modelId: body.model.modelId, label: body.model.label ?? body.model.modelId } : null),
-                        agentId: body.agentId,
-                    });
-                    json(200, { task, describe: describeSchedule(task.schedule) });
-                    return;
+                try {
+                    const summary = await service.status(conversationId);
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ok: true, summary }));
                 }
-                if (action === "delete") {
-                    const id = body.id?.trim();
-                    if (!id)
-                        throw new Error("scheduled_task delete requires an id");
-                    service.requireForWorkspace(id, workspaceId);
-                    await service.remove(id);
-                    json(200, { deleted: id });
-                    return;
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : "status failed" }));
                 }
-                json(400, { error: "action 只能是 create、list、update 或 delete。" });
-            }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : "scheduled task request failed" });
-            }
-            return;
-        }
-        if (url.pathname === "/api/question") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403).end();
                 return;
             }
-            // READ WITH A CEILING. This endpoint is exempt from the global token (the caller proves itself
-            // with a per-conversation capability instead), which means anyone on the LAN can REACH it - and
-            // this loop used to read the whole body into one string before checking anything, so an oversized
-            // body cost its full size in memory before the 403 said no. A question is a few hundred bytes;
-            // 64KB is orders of magnitude above any honest one and far below what a hostile body could use,
-            // and the shape is the same ceiling the `/api/tools` endpoints already enforce.
-            const asked = await readRequestText(request, 64_000);
-            if (asked.tooLarge) {
-                response.writeHead(413, { "content-type": "application/json" }).end(JSON.stringify({ error: "question request too large" }));
-                return;
-            }
-            const raw = asked.text;
-            try {
-                const body = JSON.parse(raw);
-                if (!body.conversationId || !body.question || !Array.isArray(body.options))
-                    throw new Error("invalid question");
-                const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability);
-                if (!verdict.ok) {
-                    response.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: verdict.message }));
+            if (url.pathname === "/api/orchestrator/list" && request.method === "GET") {
+                if (!isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403).end();
                     return;
                 }
-                const result = await runService.askQuestion(body.conversationId);
-                response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(result));
-            }
-            catch (error) {
-                response.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: describeThrown(error) || "问答失败，没有拿到失败原因。" }));
-            }
-            return;
-        }
-        if (url.pathname === "/api/files/diff") {
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const workspaceId = url.searchParams.get("workspaceId")?.trim();
-                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
-                if (!workspaceId || !workspace) {
-                    json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
+                const service = context.sessionOrchestratorService;
+                if (!service) {
+                    response.writeHead(503, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "编排服务未就绪" }));
                     return;
                 }
-                const path = url.searchParams.get("path")?.trim() ?? "";
-                if (!path) {
-                    json(400, { error: "需要 path 参数", code: "bad_request" });
-                    return;
+                const parentId = url.searchParams.get("parentId") || undefined;
+                try {
+                    const sessions = await service.list(parentId);
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ok: true, sessions }));
                 }
-                const requested = url.searchParams.get("base")?.trim();
-                const preferred = requested === "git" || requested === "agent" ? requested : "auto";
-                // The baseline is chosen by the server, but the client can name one - and when it names one, that
-                // is the one it gets. A silent fall-back would show the user a comparison they did not ask for.
-                const diff = await computeFileDiff({
-                    root: workspace.path,
-                    path,
-                    preferred,
-                    tracker: context.fileChanges,
-                    workspaceId,
-                });
-                json(200, diff);
-            }
-            catch (error) {
-                const described = describeFilesError(error);
-                json(described.status, described.body);
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : "list failed" }));
+                }
+                return;
             }
-            return;
-        }
-        if (url.pathname === "/api/files/search") {
-            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
-            try {
-                if (request.method !== "GET") {
-                    json(405, { error: "内容搜索需要 GET 请求。", code: "method" });
+            if (url.pathname === "/api/question") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403).end();
                     return;
                 }
-                const workspaceId = url.searchParams.get("workspaceId")?.trim();
-                const query = url.searchParams.get("q")?.trim() ?? "";
-                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
-                if (!workspaceId || !workspace) {
-                    json(404, { error: "找不到这个工作区——它可能已经被删除。", code: "no_workspace" });
+                // READ WITH A CEILING. This endpoint is exempt from the global token (the caller proves itself
+                // with a per-conversation capability instead), which means anyone on the LAN can REACH it - and
+                // this loop used to read the whole body into one string before checking anything, so an oversized
+                // body cost its full size in memory before the 403 said no. A question is a few hundred bytes;
+                // 64KB is orders of magnitude above any honest one and far below what a hostile body could use,
+                // and the shape is the same ceiling the `/api/tools` endpoints already enforce.
+                const asked = await readRequestText(request, 64_000);
+                if (asked.tooLarge) {
+                    response.writeHead(413, { "content-type": "application/json" }).end(JSON.stringify({ error: "question request too large" }));
                     return;
                 }
-                await resolveInsideRoot(workspace.path, "");
-                if (query.length > 256 || /[\r\n]/.test(query)) {
-                    json(400, { error: "搜索词只能是一行，且不超过 256 个字符。", code: "bad_query" });
-                    return;
+                const raw = asked.text;
+                try {
+                    const body = JSON.parse(raw);
+                    if (!body.conversationId || !body.question || !Array.isArray(body.options))
+                        throw new Error("invalid question");
+                    const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability);
+                    if (!verdict.ok) {
+                        response.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: verdict.message }));
+                        return;
+                    }
+                    const result = await runService.askQuestion(body.conversationId);
+                    response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(result));
                 }
-                if (!query) {
-                    json(200, { mode: "content", query, hits: [], truncated: false, skipped: [], complete: true, reasons: [], maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
-                    return;
+                catch (error) {
+                    response.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: describeThrown(error) || "问答失败，没有拿到失败原因。" }));
                 }
-                const indexes = context.fileIndexes ?? new Map();
-                if (!context.fileIndexes)
-                    context.fileIndexes = indexes;
-                let index = indexes.get(workspaceId);
-                if (!index) {
-                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
-                    indexes.set(workspaceId, index);
-                }
-                index.start(workspace.path);
-                const deadline = Date.now() + 4500;
-                while (!index.builtAt && Date.now() < deadline)
-                    await new Promise((resolve) => setTimeout(resolve, 25));
-                const snapshot = index.snapshot();
-                const result = await searchByContent(workspace.path, [...index.entries.values()], query, snapshot);
-                json(200, { mode: "content", query, ...result, maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
-            }
-            catch (error) {
-                const described = describeFilesError(error);
-                json(described.status, described.body);
+                return;
             }
-            return;
-        }
-        if (url.pathname === "/api/files/index") {
-            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
-            try {
-                if (request.method !== "GET") {
-                    json(405, { error: "文件索引需要 GET 请求。", code: "method" });
-                    return;
+            if (url.pathname === "/api/files/diff") {
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                    const workspace = workspaceId ? store.workspace(workspaceId) : undefined;
+                    if (!workspaceId || !workspace) {
+                        json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
+                        return;
+                    }
+                    const path = url.searchParams.get("path")?.trim() ?? "";
+                    if (!path) {
+                        json(400, { error: "需要 path 参数", code: "bad_request" });
+                        return;
+                    }
+                    const requested = url.searchParams.get("base")?.trim();
+                    const preferred = requested === "git" || requested === "agent" ? requested : "auto";
+                    // The baseline is chosen by the server, but the client can name one - and when it names one, that
+                    // is the one it gets. A silent fall-back would show the user a comparison they did not ask for.
+                    const diff = await computeFileDiff({
+                        root: workspace.path,
+                        path,
+                        preferred,
+                        tracker: context.fileChanges,
+                        workspaceId,
+                    });
+                    json(200, diff);
                 }
-                const workspaceId = url.searchParams.get("workspaceId")?.trim();
-                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
-                if (!workspaceId || !workspace) {
-                    json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
-                    return;
+                catch (error) {
+                    const described = describeFilesError(error);
+                    json(described.status, described.body);
                 }
-                const indexes = context.fileIndexes ?? new Map();
-                if (!context.fileIndexes)
-                    context.fileIndexes = indexes;
-                let index = indexes.get(workspaceId);
-                if (!index) {
-                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
-                    indexes.set(workspaceId, index);
-                }
-                index.start(workspace.path);
-                // The NAME index is started here too, and this is the whole reason the panel can promise a
-                // complete search: the client fetches this endpoint the moment a workspace opens, so the
-                // background scan is already running before anybody types. Without this the index would
-                // start on the first keystroke and the first search would be answered from a half-built map.
-                nameIndexFor(context, workspaceId, workspace.path);
-                const sinceRaw = url.searchParams.get("since");
-                const since = sinceRaw === null ? undefined : Number(sinceRaw);
-                json(200, index.snapshot(Number.isSafeInteger(since) && since >= 0 ? since : undefined));
-            }
-            catch (error) {
-                const described = describeFilesError(error);
-                json(described.status, described.body);
+                return;
             }
-            return;
-        }
-        if (url.pathname === "/api/files" || url.pathname === "/api/file") {
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                const workspaceId = url.searchParams.get("workspaceId")?.trim();
-                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
-                if (!workspaceId || !workspace) {
-                    json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
-                    return;
-                }
-                const root = workspace.path;
-                if (url.pathname === "/api/files") {
+            if (url.pathname === "/api/files/search") {
+                const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
+                try {
                     if (request.method !== "GET") {
-                        json(405, { error: "目录列表需要 GET 请求。", code: "method" });
-                        return;
-                    }
-                    const query = url.searchParams.get("q");
-                    if (query !== null && query.trim() !== "") {
-                        // THE SEARCH IS AN INDEX QUERY, not a walk.
-                        //
-                        // The old path re-walked the entire tree on every keystroke and then reported its own
-                        // limits ("已跳过 N 个目录", "结果不完整"). The index answers from memory - no filesystem
-                        // access at all - and covers every directory in the workspace, so there is nothing to
-                        // report a limit about. `truncated` and `skipped` stay in the response so the protocol
-                        // shape does not change under the client, but they are now constants that say the
-                        // opposite of what they used to.
-                        const index = nameIndexFor(context, workspaceId, root);
-                        // THE WORKSPACE MUST EXIST, AND THE INDEX IS WHAT KNOWS.
-                        //
-                        // The background scan records a root it could not read rather than throwing it - a scan
-                        // has no caller to receive a rejection, and an unhandled one terminates the process. So
-                        // the route asks the index what happened and turns the answer into the status it
-                        // deserves. Without this a workspace whose directory is gone would answer 200 with an
-                        // empty list, which is byte-for-byte the response for "your search matched nothing" -
-                        // the exact confusion this endpoint is supposed to avoid.
-                        await index.waitUntilIndexed(4000);
-                        index.throwIfBroken();
-                        // WAIT FOR THE INDEX, briefly. A search answered from a half-built map would say "no
-                        // matches" for files that are on disk - which is precisely the "搜不出他想搜的东西"
-                        // failure this work exists to remove. Past the deadline the answer is still returned, with
-                        // `indexed: false` so the UI can say the index is still building rather than pretending
-                        // the tree is empty.
-                        const result = index.search(query);
-                        json(200, {
-                            mode: "search",
-                            query: query.trim(),
-                            hits: result.hits.map((hit) => ({ path: hit.path, name: hit.name, directory: hit.directory })),
-                            total: result.total,
-                            truncated: false,
-                            skipped: [],
-                            indexed: result.indexed,
-                            progress: result.progress,
-                            incomplete: result.incomplete,
-                        });
+                        json(405, { error: "内容搜索需要 GET 请求。", code: "method" });
                         return;
                     }
-                    const listing = await listDirectory(root, url.searchParams.get("path"));
-                    json(200, { mode: "list", ...listing, maxEntries: 2000 });
-                    return;
+                    const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                    const query = url.searchParams.get("q")?.trim() ?? "";
+                    const workspace = workspaceId ? store.workspace(workspaceId) : undefined;
+                    if (!workspaceId || !workspace) {
+                        json(404, { error: "找不到这个工作区——它可能已经被删除。", code: "no_workspace" });
+                        return;
+                    }
+                    await resolveInsideRoot(workspace.path, "");
+                    if (query.length > 256 || /[\r\n]/.test(query)) {
+                        json(400, { error: "搜索词只能是一行，且不超过 256 个字符。", code: "bad_query" });
+                        return;
+                    }
+                    if (!query) {
+                        json(200, { mode: "content", query, hits: [], truncated: false, skipped: [], complete: true, reasons: [], maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
+                        return;
+                    }
+                    const indexes = context.fileIndexes ?? new Map();
+                    if (!context.fileIndexes)
+                        context.fileIndexes = indexes;
+                    let index = indexes.get(workspaceId);
+                    if (!index) {
+                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                        indexes.set(workspaceId, index);
+                    }
+                    index.start(workspace.path);
+                    const deadline = Date.now() + 4500;
+                    while (!index.builtAt && Date.now() < deadline)
+                        await new Promise((resolve) => setTimeout(resolve, 25));
+                    const snapshot = index.snapshot();
+                    const result = await searchByContent(workspace.path, [...index.entries.values()], query, snapshot);
+                    json(200, { mode: "content", query, ...result, maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
                 }
-                if (request.method === "GET") {
-                    const rel = url.searchParams.get("path") ?? "";
-                    if (url.searchParams.get("meta") === "1") {
-                        const resolved = await resolveInsideRoot(root, rel);
-                        const meta = await fileMeta(resolved);
-                        const path = toRelative(root, resolved);
-                        context.fileIndexes?.get(workspaceId)?.recordFile(path, meta);
-                        json(200, { path, ...meta });
+                catch (error) {
+                    const described = describeFilesError(error);
+                    json(described.status, described.body);
+                }
+                return;
+            }
+            if (url.pathname === "/api/files/index") {
+                const json = (status, body) => {
+                    const raw = Buffer.from(JSON.stringify(body), "utf8");
+                    // A workspace index is intentionally a JSON snapshot for quick-open, but it can be several MB.
+                    // Compress only when the browser advertises support; this keeps local callers and old clients
+                    // compatible while cutting remote transfer time by an order of magnitude on repetitive paths.
+                    const encodings = (request.headers["accept-encoding"] ?? "").split(",").map((part) => part.trim().split(";").map((value) => value.trim()));
+                    const gzipEntry = encodings.find(([name]) => name.toLowerCase() === "gzip") ?? encodings.find(([name]) => name === "*");
+                    const quality = gzipEntry?.find((part) => /^q=/i.test(part));
+                    if (gzipEntry && (!quality || Number(quality.slice(2)) > 0) && raw.length >= 1024) {
+                        void promisify(gzip)(raw, { level: 6 }).then((encoded) => {
+                            if (!response.destroyed)
+                                response.writeHead(status, { "content-type": "application/json; charset=utf-8", "content-encoding": "gzip", "vary": "Accept-Encoding", "content-length": encoded.length }).end(encoded);
+                        }).catch((error) => { console.warn("Super Pi: file index compression failed", error); if (!response.destroyed)
+                            response.writeHead(status, { "content-type": "application/json; charset=utf-8", "vary": "Accept-Encoding", "content-length": raw.length }).end(raw); });
                         return;
                     }
-                    const file = await readWorkspaceFile(root, rel);
-                    context.fileIndexes?.get(workspaceId)?.recordFile(file.path, file.meta);
-                    json(200, { path: file.path, content: file.content, eol: file.eol, bom: file.bom, meta: file.meta, maxBytes: MAX_FILE_BYTES });
-                    return;
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "vary": "Accept-Encoding", "content-length": raw.length }).end(raw);
+                };
+                try {
+                    if (request.method !== "GET") {
+                        json(405, { error: "文件索引需要 GET 请求。", code: "method" });
+                        return;
+                    }
+                    const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                    const workspace = workspaceId ? store.workspace(workspaceId) : undefined;
+                    if (!workspaceId || !workspace) {
+                        json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
+                        return;
+                    }
+                    const indexes = context.fileIndexes ?? new Map();
+                    if (!context.fileIndexes)
+                        context.fileIndexes = indexes;
+                    let index = indexes.get(workspaceId);
+                    if (!index) {
+                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                        indexes.set(workspaceId, index);
+                    }
+                    index.start(workspace.path);
+                    // Quick Open requests the full index on demand. Name search can share its background scan;
+                    // merely selecting a session no longer starts a multi-MB download.
+                    nameIndexFor(context, workspaceId, workspace.path);
+                    const sinceRaw = url.searchParams.get("since");
+                    const since = sinceRaw === null ? undefined : Number(sinceRaw);
+                    json(200, index.snapshot(Number.isSafeInteger(since) && since >= 0 ? since : undefined));
+                }
+                catch (error) {
+                    const described = describeFilesError(error);
+                    json(described.status, described.body);
                 }
-                if (request.method === "PUT") {
-                    const remoteAddr = request.socket.remoteAddress ?? "";
-                    if (!isLocalOrPrivateAddress(remoteAddr)) {
-                        json(403, { error: "保存文件需要从本机或局域网发起。", code: "not_loopback" });
+                return;
+            }
+            if (url.pathname === "/api/files" || url.pathname === "/api/file") {
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                    const workspace = workspaceId ? store.workspace(workspaceId) : undefined;
+                    if (!workspaceId || !workspace) {
+                        json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
                         return;
                     }
-                    let raw = "";
-                    let totalBytes = 0;
-                    const reader = textBodyReader();
-                    for await (const chunk of request) {
-                        const piece = chunk;
-                        totalBytes += piece.length;
-                        if (totalBytes > MAX_FILE_BYTES * 2) {
-                            json(413, { error: "请求体过大", code: "too_large" });
-                            request.destroy();
+                    const root = workspace.path;
+                    if (url.pathname === "/api/files") {
+                        if (request.method !== "GET") {
+                            json(405, { error: "目录列表需要 GET 请求。", code: "method" });
+                            return;
+                        }
+                        const query = url.searchParams.get("q");
+                        if (query !== null && query.trim() !== "") {
+                            // THE SEARCH IS AN INDEX QUERY, not a walk.
+                            //
+                            // The old path re-walked the entire tree on every keystroke and then reported its own
+                            // limits ("已跳过 N 个目录", "结果不完整"). The index answers from memory - no filesystem
+                            // access at all - and covers every directory in the workspace, so there is nothing to
+                            // report a limit about. `truncated` and `skipped` stay in the response so the protocol
+                            // shape does not change under the client, but they are now constants that say the
+                            // opposite of what they used to.
+                            const index = nameIndexFor(context, workspaceId, root);
+                            // THE WORKSPACE MUST EXIST, AND THE INDEX IS WHAT KNOWS.
+                            //
+                            // The background scan records a root it could not read rather than throwing it - a scan
+                            // has no caller to receive a rejection, and an unhandled one terminates the process. So
+                            // the route asks the index what happened and turns the answer into the status it
+                            // deserves. Without this a workspace whose directory is gone would answer 200 with an
+                            // empty list, which is byte-for-byte the response for "your search matched nothing" -
+                            // the exact confusion this endpoint is supposed to avoid.
+                            await index.waitUntilIndexed(4000);
+                            index.throwIfBroken();
+                            // WAIT FOR THE INDEX, briefly. A search answered from a half-built map would say "no
+                            // matches" for files that are on disk - which is precisely the "搜不出他想搜的东西"
+                            // failure this work exists to remove. Past the deadline the answer is still returned, with
+                            // `indexed: false` so the UI can say the index is still building rather than pretending
+                            // the tree is empty.
+                            const result = index.search(query);
+                            json(200, {
+                                mode: "search",
+                                query: query.trim(),
+                                hits: result.hits.map((hit) => ({ path: hit.path, name: hit.name, directory: hit.directory })),
+                                total: result.total,
+                                truncated: false,
+                                skipped: [],
+                                indexed: result.indexed,
+                                progress: result.progress,
+                                incomplete: result.incomplete,
+                            });
                             return;
                         }
-                        raw = reader.push(piece);
+                        const listing = await listDirectory(root, url.searchParams.get("path"));
+                        json(200, { mode: "list", ...listing, maxEntries: 2000 });
+                        return;
                     }
-                    raw = reader.finish();
-                    const declared = Number(request.headers["content-length"] ?? "0");
-                    if (Number.isFinite(declared) && declared > MAX_FILE_BYTES * 2) {
-                        json(413, { error: "请求体过大", code: "too_large" });
+                    if (request.method === "GET") {
+                        const rel = url.searchParams.get("path") ?? "";
+                        if (url.searchParams.get("meta") === "1") {
+                            const resolved = await resolveInsideRoot(root, rel);
+                            const meta = await fileMeta(resolved);
+                            const path = toRelative(root, resolved);
+                            context.fileIndexes?.get(workspaceId)?.recordFile(path, meta);
+                            json(200, { path, ...meta });
+                            return;
+                        }
+                        const file = await readWorkspaceFile(root, rel);
+                        context.fileIndexes?.get(workspaceId)?.recordFile(file.path, file.meta);
+                        json(200, { path: file.path, content: file.content, eol: file.eol, bom: file.bom, meta: file.meta, maxBytes: MAX_FILE_BYTES });
                         return;
                     }
-                    const parsed = JSON.parse(raw);
-                    if (typeof parsed.path !== "string" || typeof parsed.content !== "string") {
-                        json(400, { error: "写入需要 path 与 content 两个字符串字段", code: "bad_request" });
+                    if (request.method === "PUT") {
+                        const remoteAddr = request.socket.remoteAddress ?? "";
+                        if (!isLocalOrPrivateAddress(remoteAddr)) {
+                            json(403, { error: "保存文件需要从本机或局域网发起。", code: "not_loopback" });
+                            return;
+                        }
+                        let raw = "";
+                        let totalBytes = 0;
+                        const reader = textBodyReader();
+                        for await (const chunk of request) {
+                            const piece = chunk;
+                            totalBytes += piece.length;
+                            if (totalBytes > MAX_FILE_BYTES * 2) {
+                                json(413, { error: "请求体过大", code: "too_large" });
+                                request.destroy();
+                                return;
+                            }
+                            raw = reader.push(piece);
+                        }
+                        raw = reader.finish();
+                        const declared = Number(request.headers["content-length"] ?? "0");
+                        if (Number.isFinite(declared) && declared > MAX_FILE_BYTES * 2) {
+                            json(413, { error: "请求体过大", code: "too_large" });
+                            return;
+                        }
+                        const parsed = JSON.parse(raw);
+                        if (typeof parsed.path !== "string" || typeof parsed.content !== "string") {
+                            json(400, { error: "写入需要 path 与 content 两个字符串字段", code: "bad_request" });
+                            return;
+                        }
+                        const outcome = await writeWorkspaceFile(root, parsed.path, parsed.content, parsed.baseEtag);
+                        context.fileIndexes?.get(workspaceId)?.recordFile(outcome.path, outcome.meta);
+                        // The name index learns about the save too. A file the user just saved must be findable
+                        // by name immediately, and the index is the thing the search reads - so this is where the
+                        // index stays true without anybody re-scanning the tree.
+                        context.nameIndexes?.get(workspaceId)?.upsert(outcome.path);
+                        json(200, outcome);
                         return;
                     }
-                    const outcome = await writeWorkspaceFile(root, parsed.path, parsed.content, parsed.baseEtag);
-                    context.fileIndexes?.get(workspaceId)?.recordFile(outcome.path, outcome.meta);
-                    // The name index learns about the save too. A file the user just saved must be findable
-                    // by name immediately, and the index is the thing the search reads - so this is where the
-                    // index stays true without anybody re-scanning the tree.
-                    context.nameIndexes?.get(workspaceId)?.upsert(outcome.path);
-                    json(200, outcome);
-                    return;
+                    json(405, { error: `/api/file 不支持 ${request.method} 请求。`, code: "method" });
                 }
-                json(405, { error: `/api/file 不支持 ${request.method} 请求。`, code: "method" });
-            }
-            catch (error) {
-                const described = describeFilesError(error);
-                json(described.status, described.body);
+                catch (error) {
+                    const described = describeFilesError(error);
+                    json(described.status, described.body);
+                }
+                return;
             }
-            return;
-        }
-        if (url.pathname === "/api/fs/dirs") {
-            const fail = (status, message) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: message }));
-            };
-            try {
-                const rawPath = url.searchParams.get("path")?.trim();
-                const defaultDir = homedir() || rootDir;
-                const expandTilde = (filepath) => {
-                    if (filepath === "~")
-                        return homedir();
-                    if (filepath.startsWith("~/") || filepath.startsWith("~\\")) {
-                        return join(homedir(), filepath.slice(2));
-                    }
-                    return filepath;
+            if (url.pathname === "/api/fs/dirs") {
+                const fail = (status, message) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: message }));
                 };
-                const target = resolve(rawPath ? expandTilde(rawPath) : defaultDir);
-                const info = await stat(target).catch((error) => {
-                    if (error?.code === "ENOENT" || error?.code === "ENOTDIR")
-                        return undefined;
-                    throw error;
-                });
-                if (!info) {
-                    fail(404, `目录不存在：${target}`);
-                    return;
+                try {
+                    const rawPath = url.searchParams.get("path")?.trim();
+                    const defaultDir = homedir() || rootDir;
+                    const expandTilde = (filepath) => {
+                        if (filepath === "~")
+                            return homedir();
+                        if (filepath.startsWith("~/") || filepath.startsWith("~\\")) {
+                            return join(homedir(), filepath.slice(2));
+                        }
+                        return filepath;
+                    };
+                    const target = resolve(rawPath ? expandTilde(rawPath) : defaultDir);
+                    const info = await stat(target).catch((error) => {
+                        if (error?.code === "ENOENT" || error?.code === "ENOTDIR")
+                            return undefined;
+                        throw error;
+                    });
+                    if (!info) {
+                        fail(404, `目录不存在：${target}`);
+                        return;
+                    }
+                    if (!info.isDirectory()) {
+                        fail(400, `该路径不是目录：${target}`);
+                        return;
+                    }
+                    const dirents = await readdir(target, { withFileTypes: true });
+                    const entries = dirents
+                        .filter((item) => item.isDirectory())
+                        .map((item) => ({ name: item.name, path: join(target, item.name) }))
+                        .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+                    const truncated = entries.length > 2000;
+                    const parent = dirname(target);
+                    const getAvailableDrives = () => {
+                        if (process.platform !== "win32")
+                            return [];
+                        const drives = [];
+                        for (let i = 65; i <= 90; i++) {
+                            const drive = String.fromCharCode(i) + ":\\";
+                            try {
+                                if (existsSync(drive))
+                                    drives.push(drive);
+                            }
+                            catch { }
+                        }
+                        return drives;
+                    };
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                        path: target,
+                        parent: parent === target ? null : parent,
+                        suggestedName: basename(target) || target,
+                        entries: truncated ? entries.slice(0, 2000) : entries,
+                        truncated,
+                        drives: getAvailableDrives(),
+                        homeDir: homedir(),
+                    }));
                 }
-                if (!info.isDirectory()) {
-                    fail(400, `该路径不是目录：${target}`);
+                catch (error) {
+                    const code = error.code;
+                    if (code === "EACCES" || code === "EPERM")
+                        fail(403, `没有访问权限：${url.searchParams.get("path") ?? rootDir}`);
+                    else
+                        fail(500, `读取目录失败：${error instanceof Error ? error.message : "未知错误"}`);
+                }
+                return;
+            }
+            if (url.pathname === "/api/upload") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "上传需要从本机或局域网发起。" }));
                     return;
                 }
-                const dirents = await readdir(target, { withFileTypes: true });
-                const entries = dirents
-                    .filter((item) => item.isDirectory())
-                    .map((item) => ({ name: item.name, path: join(target, item.name) }))
-                    .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
-                const truncated = entries.length > 2000;
-                const parent = dirname(target);
-                const getAvailableDrives = () => {
-                    if (process.platform !== "win32")
-                        return [];
-                    const drives = [];
-                    for (let i = 65; i <= 90; i++) {
-                        const drive = String.fromCharCode(i) + ":\\";
-                        try {
-                            if (existsSync(drive))
-                                drives.push(drive);
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    let totalBytes = 0;
+                    const chunks = [];
+                    for await (const chunk of request) {
+                        totalBytes += chunk.length;
+                        if (totalBytes > MAX_UPLOAD_BODY_BYTES) {
+                            json(413, { error: "图片超过了大小上限。" });
+                            request.destroy();
+                            return;
                         }
-                        catch { }
+                        chunks.push(chunk);
                     }
-                    return drives;
-                };
-                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
-                    path: target,
-                    parent: parent === target ? null : parent,
-                    suggestedName: basename(target) || target,
-                    entries: truncated ? entries.slice(0, 2000) : entries,
-                    truncated,
-                    drives: getAvailableDrives(),
-                    homeDir: homedir(),
-                }));
-            }
-            catch (error) {
-                const code = error.code;
-                if (code === "EACCES" || code === "EPERM")
-                    fail(403, `没有访问权限：${url.searchParams.get("path") ?? rootDir}`);
-                else
-                    fail(500, `读取目录失败：${error instanceof Error ? error.message : "未知错误"}`);
-            }
-            return;
-        }
-        if (url.pathname === "/api/upload") {
-            if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "上传需要从本机或局域网发起。" }));
-                return;
-            }
-            const json = (status, body) => {
-                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
-            };
-            try {
-                let totalBytes = 0;
-                const chunks = [];
-                for await (const chunk of request) {
-                    totalBytes += chunk.length;
-                    if (totalBytes > MAX_UPLOAD_BODY_BYTES) {
-                        json(413, { error: "图片超过了大小上限。" });
-                        request.destroy();
+                    const raw = Buffer.concat(chunks).toString("utf8");
+                    const body = JSON.parse(raw);
+                    const conversationId = body.conversationId?.trim();
+                    if (!conversationId) {
+                        json(400, { error: "缺少会话 ID。" });
                         return;
                     }
-                    chunks.push(chunk);
-                }
-                const raw = Buffer.concat(chunks).toString("utf8");
-                const body = JSON.parse(raw);
-                const conversationId = body.conversationId?.trim();
-                if (!conversationId) {
-                    json(400, { error: "缺少会话 ID。" });
-                    return;
+                    const conversation = store.snapshot().conversations.find((c) => c.id === conversationId);
+                    if (!conversation) {
+                        json(404, { error: "找不到这个会话——它可能已经被删除。" });
+                        return;
+                    }
+                    if (!body.mimeType || typeof body.mimeType !== "string") {
+                        json(400, { error: "缺少图片类型。" });
+                        return;
+                    }
+                    if (!body.data || typeof body.data !== "string") {
+                        json(400, { error: "缺少图片数据。" });
+                        return;
+                    }
+                    const catalog = await catalogService.getCatalog(conversation.model);
+                    const currentModel = catalog.models.find((m) => m.provider === conversation.model?.provider && m.modelId === conversation.model?.modelId)
+                        ?? catalog.models.find((m) => m.provider === catalog.defaultModel?.provider && m.modelId === catalog.defaultModel?.modelId);
+                    if (currentModel && !currentModel.imageInput) {
+                        json(400, { error: `当前模型「${currentModel.label || currentModel.modelId}」不支持图片输入` });
+                        return;
+                    }
+                    const record = await saveUpload(uploadsDir, conversationId, body.name, body.mimeType, body.data);
+                    json(200, record);
                 }
-                const conversation = store.snapshot().conversations.find((c) => c.id === conversationId);
-                if (!conversation) {
-                    json(404, { error: "找不到这个会话——它可能已经被删除。" });
-                    return;
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "Upload failed" });
                 }
-                if (!body.mimeType || typeof body.mimeType !== "string") {
-                    json(400, { error: "缺少图片类型。" });
+                return;
+            }
+            if (url.pathname.startsWith("/api/upload/")) {
+                if (request.method !== "GET" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "读取上传的图片需要从本机或局域网发起。" }));
                     return;
                 }
-                if (!body.data || typeof body.data !== "string") {
-                    json(400, { error: "缺少图片数据。" });
+                const pathParts = url.pathname.slice("/api/upload/".length).split("/").filter(Boolean);
+                if (!pathParts.length || pathParts.length > 2) {
+                    response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "上传路径不合法。" }));
                     return;
                 }
-                const catalog = await catalogService.getCatalog(conversation.model);
-                const currentModel = catalog.models.find((m) => m.provider === conversation.model?.provider && m.modelId === conversation.model?.modelId)
-                    ?? catalog.models.find((m) => m.provider === catalog.defaultModel?.provider && m.modelId === catalog.defaultModel?.modelId);
-                if (currentModel && !currentModel.imageInput) {
-                    json(400, { error: `当前模型「${currentModel.label || currentModel.modelId}」不支持图片输入` });
+                const convId = pathParts.length === 2 ? pathParts[0] : undefined;
+                const fileOrId = pathParts.length === 2 ? pathParts[1] : pathParts[0];
+                const found = await findUploadFile(uploadsDir, convId, fileOrId);
+                if (!found) {
+                    response.writeHead(404, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Image not found" }));
                     return;
                 }
-                const record = await saveUpload(uploadsDir, conversationId, body.name, body.mimeType, body.data);
-                json(200, record);
+                response.writeHead(200, {
+                    "content-type": found.mimeType,
+                    "x-content-type-options": "nosniff",
+                    "cache-control": "public, max-age=31536000, immutable",
+                    "content-length": found.size,
+                });
+                createReadStream(found.filePath).on("error", () => {
+                    if (!response.headersSent) {
+                        response.writeHead(500, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Failed to read upload file" }));
+                        return;
+                    }
+                    response.destroy();
+                }).pipe(response);
+                return;
             }
-            catch (error) {
-                json(400, { error: error instanceof Error ? error.message : "Upload failed" });
+            // Static client asset handling
+            const requested = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
+            const requestedPath = resolve(clientDir, requested);
+            const safe = !relative(clientDir, requestedPath).startsWith("..") && !relative(clientDir, requestedPath).includes(":");
+            if (!safe) {
+                response.writeHead(403).end();
+                return;
             }
-            return;
-        }
-        if (url.pathname.startsWith("/api/upload/")) {
-            if (request.method !== "GET" || !isLocalOrPrivateAddress(remote)) {
-                response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "读取上传的图片需要从本机或局域网发起。" }));
+            // Only extensionless URLs are application-navigation requests.  A missing hashed
+            // asset must stay a real 404: returning index.html with text/html for /assets/*.js
+            // makes stale browser documents look like successful script loads and leaves the
+            // browser with an invalid application state after a refresh.
+            const requestedExtension = extname(requestedPath);
+            const candidate = existsSync(requestedPath)
+                ? requestedPath
+                : requestedExtension
+                    ? undefined
+                    : join(clientDir, "index.html");
+            if (!candidate) {
+                response.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }).end("Not found");
                 return;
             }
-            const pathParts = url.pathname.slice("/api/upload/".length).split("/").filter(Boolean);
-            if (!pathParts.length || pathParts.length > 2) {
-                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "上传路径不合法。" }));
+            if (!existsSync(candidate)) {
+                response.writeHead(503, { "content-type": "text/plain; charset=utf-8" }).end("Super Pi client has not been built. Run npm run build.");
                 return;
             }
-            const convId = pathParts.length === 2 ? pathParts[0] : undefined;
-            const fileOrId = pathParts.length === 2 ? pathParts[1] : pathParts[0];
-            const found = await findUploadFile(uploadsDir, convId, fileOrId);
-            if (!found) {
-                response.writeHead(404, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Image not found" }));
+            const candidateInfo = await stat(candidate).catch(() => undefined);
+            if (!candidateInfo?.isFile()) {
+                response.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found");
                 return;
             }
             response.writeHead(200, {
-                "content-type": found.mimeType,
+                "content-type": MIME_TYPES[extname(candidate)] ?? "application/octet-stream",
                 "x-content-type-options": "nosniff",
-                "cache-control": "public, max-age=31536000, immutable",
-                "content-length": found.size,
+                "cache-control": candidate === join(clientDir, "index.html") ? "no-store" : "public, max-age=31536000, immutable",
             });
-            createReadStream(found.filePath).on("error", () => {
-                if (!response.headersSent) {
-                    response.writeHead(500, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Failed to read upload file" }));
-                    return;
-                }
-                response.destroy();
-            }).pipe(response);
-            return;
+            const stream = createReadStream(candidate);
+            stream.on("error", () => { if (!response.headersSent)
+                response.writeHead(404); response.end(); });
+            stream.pipe(response);
         }
-        // Static client asset handling
-        const requested = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
-        const requestedPath = resolve(clientDir, requested);
-        const safe = !relative(clientDir, requestedPath).startsWith("..") && !relative(clientDir, requestedPath).includes(":");
-        if (!safe) {
-            response.writeHead(403).end();
-            return;
-        }
-        // Only extensionless URLs are application-navigation requests.  A missing hashed
-        // asset must stay a real 404: returning index.html with text/html for /assets/*.js
-        // makes stale browser documents look like successful script loads and leaves the
-        // browser with an invalid application state after a refresh.
-        const requestedExtension = extname(requestedPath);
-        const candidate = existsSync(requestedPath)
-            ? requestedPath
-            : requestedExtension
-                ? undefined
-                : join(clientDir, "index.html");
-        if (!candidate) {
-            response.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }).end("Not found");
-            return;
-        }
-        if (!existsSync(candidate)) {
-            response.writeHead(503, { "content-type": "text/plain; charset=utf-8" }).end("Super Pi client has not been built. Run npm run build.");
-            return;
-        }
-        const candidateInfo = await stat(candidate).catch(() => undefined);
-        if (!candidateInfo?.isFile()) {
-            response.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found");
-            return;
+        catch (error) {
+            // This is the last safety net for an async route.  Before this boundary,
+            // an unexpected throw became an unhandled rejection and left clients with
+            // a socket that simply hung.  Preserve the real reason in the detached
+            // server log and give the caller a bounded, correlatable response.
+            console.error(`Super Pi HTTP request failed requestId=${requestId} method=${request.method ?? "?"} url=${request.url ?? "?"}:`, describeThrown(error));
+            if (response.headersSent) {
+                response.destroy();
+            }
+            else {
+                response.writeHead(500, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+                response.end(JSON.stringify({ error: "服务端处理请求时发生异常。", requestId }));
+            }
         }
-        response.writeHead(200, {
-            "content-type": MIME_TYPES[extname(candidate)] ?? "application/octet-stream",
-            "x-content-type-options": "nosniff",
-            "cache-control": candidate === join(clientDir, "index.html") ? "no-store" : "public, max-age=31536000, immutable",
-        });
-        const stream = createReadStream(candidate);
-        stream.on("error", () => { if (!response.headersSent)
-            response.writeHead(404); response.end(); });
-        stream.pipe(response);
     });
 }