@youweichen/pi-harness 0.0.0-stage → 1.0.0

package/dist/server/agent-service.js

@@ -0,0 +1,3051 @@
+import { planSettings } from "./plan/settings.js";
+import { reloadSession } from "./session-reload.js";
+import { resolveNativeAttachments } from "./user-attachments.js";
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
+import { SessionTreeController } from "./session-tree-controller.js";
+import { SessionBranchCounts } from "./session-file-read.js";
+import { createHash, randomUUID } from "node:crypto";
+import { recoveryEvent, isRecovering, recoverySnapshot } from "./recovery-state.js";
+import { Readable } from "node:stream";
+import { openToolOutput, toolOutputManifest, toolOutputId } from "./tool-output.js";
+import { nativeToolDetails, toolExitCode } from "./serialize.js";
+import { flushPromptReload, getSystemPromptState, promptReloadStatus, promptUsesFile, queuePromptReload, writeSystemPromptFile } from "./system-prompt-files.js";
+import { parseNativeMcpStatus } from "./native-mcp-presentation.js";
+import { codemodeDetails } from "./codemode-presentation.js";
+import { NativeMcpConfigService } from "./native-mcp-config.js";
+import { conversationSettings, setConversationRunSettings, nativeToolExtensions } from "./native-tools.js";
+import { ProviderAuthService } from "./provider-auth.js";
+import { packageManagerFor, updateTargets, checkComponents, componentRestartRequired, updateComponentPackage } from "./component-updates.js";
+import { toolOutputUpdate } from "./tool-output.js";
+import { ThinkingTimings, ThinkingDurationStore } from "./thinking-timing.js";
+import { deliverPrompt, recallPending } from "./prompt-delivery.js";
+import { validateEditorSnapshots } from "./editor-snapshot.js";
+import { QueryCache } from "./query-cache.js";
+import { DEFAULT_CONV_TITLE, MAX_OPEN_CONVERSATIONS, QuiesceRejectedError, conversationTitle, skillAwareTitleText, } from "./conversation.js";
+import { browseDirs } from "./dir-browser.js";
+import { projectToolTextMessages } from "./tool-text-incidents.js";
+import { unexecutedToolText, TOOL_TEXT_CONTINUE_PROMPT } from "./tool-text.js";
+/** Upper bound of automatic requests per user prompt (each also needs real tool progress). */
+export const TOOL_TEXT_MAX_CONTINUES = 1;
+export { TOOL_TEXT_CONTINUE_PROMPT } from "./tool-text.js";
+import { clientIdleMsFromEnv, isClientEvictable } from "./client-eviction.js";
+import { PiConfigProbe, checkUpdate, installPiAgent, isPiCliInstalled } from "./pi-environment.js";
+export { QuiesceRejectedError };
+/**
+ * AgentService — wraps the pi SDK (@earendil-works/pi-coding-agent) for the web
+ * frontend. Each browser client (identified by a persistent clientId) gets its
+ * own AgentSessionRuntime, but sessions live in the SDK default per-project
+ * directory (<agentDir>/sessions/--<cwd>--/) — the same transcript files the
+ * pi CLI/TUI use — so every conversation of a folder shows up everywhere.
+ *
+ * Streaming model: the SDK emits AgentSessionEvents; we forward lightweight
+ * `tool_delta` messages for live tool output and schedule throttled full-state
+ * snapshots. The frontend is snapshot-driven (server is the source of truth),
+ * so reconnects just re-request a snapshot.
+ */
+import { existsSync, rmSync, statSync, writeFileSync, watch, } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
+// pi-coding-agent 自己压缩历史消息（agent-session.js 的 compact()）走的也是这两个
+// 调用，不是我们临时拼出来的私活。声明成显式依赖、锁成跟 pi-coding-agent 完全
+// 一致的版本号，保证两边用的是同一份实现。
+import { contentText } from "@earendil-works/pi-ai";
+import { estimateContextParts } from "./context-breakdown.js";
+import { BgServerTracker } from "./bg-servers.js";
+import { SettingsService } from "./settings-service.js";
+import { SlashCommandsService, parseSlash } from "./slash-commands.js";
+import { ModelAdminService } from "./model-admin.js";
+import { FilesService, existingConversationFiles, workspacePath } from "./files-service.js";
+import { ClientStateStore, mergeProjectSummaries, } from "./client-state.js";
+import { saveUpload } from "./uploads.js";
+import { WebUIContext } from "./webui-context.js";
+import { buildAttachmentMessages, } from "./attachments.js";
+import { serializeMessage, contentFingerprint, serializeStreamingMessage, } from "./serialize.js";
+import { deriveTaskProgress } from "./task-progress.js";
+import { taskHistoryFromSession } from "./plan/progress.js";
+import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
+const SNAPSHOT_INTERVAL_MS = 60;
+/** While assistant deltas are flowing, live rendering is carried by
+ *  message_delta — full snapshots become pure reconciliation checkpoints, so
+ *  send them on a slow event-driven cadence (see flushSnapshot call-sites:
+ *  agent_settled / tool_execution_end always checkpoint immediately). */
+const STREAMING_SNAPSHOT_INTERVAL_MS = 2000;
+/** Deltas newer than this keep the streaming (low-frequency) snapshot cadence. */
+const DELTA_ACTIVE_WINDOW_MS = 1500;
+const WIDGET_REFRESH_MS = 2000;
+/** Model-stall watchdog: warn (don't abort — deep thinking can be legitimately
+ *  quiet for minutes) when a streaming run produced NO SDK events for this long.
+ *  Covers the failure class the per-tool watchdog cannot see: half-open API
+ *  connections / hung proxies where no tool is running and no error is thrown.
+ *  Override: PI_WEB_STALL_NOTIFY_MS (milliseconds; 0 disables). */
+const STALL_NOTIFY_MS = (() => {
+    const v = Number(process.env.PI_WEB_STALL_NOTIFY_MS);
+    return Number.isFinite(v) && v >= 0 ? v : 180_000;
+})();
+/** Serialization-cache headroom per conversation (see serializeCached): the
+ *  cache holds the current transcript plus this many stale entries (old
+ *  tool-result revisions, abandoned branches) before evicting the oldest. */
+const UI_MESSAGE_CACHE_CAP = 4096;
+/** Preview panel cap: only the first 512KB of a file is ever read/sent. */
+// ---------------------------------------------------------------------------
+// Preview kind classification. The preview panel only opens image / video /
+// text-editable files; everything else (exe, jar, archives, …) is refused so
+// it is never read or sent to the browser. Media files are served over the
+// /api/file HTTP endpoint instead of the WebSocket, so they are classified
+// here but never read into the snapshot path.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Web UI context adapter — bridges extension UI calls (setWidget/notify) to the
+// browser. Extensions like rpiv-todo render a TUI widget via
+// `ui.setWidget(key, (tui, theme) => comp)`; we capture the component, render it
+// with a mock theme to plain text lines, and push them to the client.
+// ---------------------------------------------------------------------------
+export { workspacePath };
+/**
+ * 用当前会话的模型给对话起一个短标题。
+ *
+ * 注意：这里踩了两块 SDK 的非公开地面，都是有意为之、也都做了兜底——
+ *   1. `_getSummarizationRequestAuth` 是 AgentSession 的私有方法（下划线开头，
+ *      .d.ts 里只 declare、不给类型）。SDK 自己的 compact() 就是靠它解析
+ *      summarization 请求要用的 { model, apiKey, headers, env }，我们复用同一条
+ *      路径，省得自己再拼一遍 auth / baseUrl 解析。
+ *   2. `@earendil-works/pi-ai/compat` 这个入口，它自己的 .d.ts 里就写着是临时
+ *      兼容层，将来会随 ModelManager 迁移一起删掉。
+ *
+ * 所以整个函数包在 try/catch 里，方法不存在时用 typeof 判掉直接返回 null。任何
+ * 一步失败都只是「拿不到 AI 标题」，调用方会保留截断的兜底标题，用户侧看不到任何
+ * 报错。将来 SDK 把这两个口子改了，表现就是标题退回截断版本，不会崩。
+ */
+export class ClientSession {
+    clientId;
+    static liveClients = new Map();
+    /** Set by AgentService.attach: reflects the SERVICE-wide quiesce flag
+     *  (server draining — new work rejected). Default false for direct use. */
+    isQuiesced = () => false;
+    cwd;
+    /** pi config dir (auth/models/skills). */
+    agentDir;
+    /** Persisted per-client UI state (last workspace + recent projects). */
+    stateStore;
+    thinkingDurationStore;
+    /** Open conversations — each owns its OWN runtime, so starting a new chat
+     *  or switching chats never interrupts an in-flight run. `runtime` and
+     *  `session` accessors below target the ACTIVE conversation. */
+    convs = new Map();
+    activeId = "";
+    convSeq = 0;
+    creatingConversation = false;
+    /** One ModelRuntime shared by all conversations — the model chosen in the
+     *  top bar applies to every chat, not just the one that set it. Seeded by
+     *  the first conversation and reused by later ones. */
+    sharedModelRuntime;
+    // -----------------------------------------------------------------------
+    // -----------------------------------------------------------------------
+    settingsSvc; // 构造函数里创建（需要 clientId/stateStore）
+    /** How long a hard abort waits for session.abort() to make the run idle
+     *  before force-resetting the conversation (model streams that ignore the
+     *  abort signal would otherwise leave the chat stuck forever). */
+    static HARD_ABORT_TIMEOUT_MS = 15_000;
+    /** Extra settle window after session.abort() returns: the run is only
+     *  considered stopped once its agent_settled event arrives. If it doesn't
+     *  (model stream stuck before the run even started), force-reset. */
+    static HARD_ABORT_SETTLE_MS = 8_000;
+    /** Live AbortControllers of THIS client's running bash tool calls — aborting
+     *  them kills only the command (agent run and conversation continue). */
+    /** Background-server tracking (port snapshots + 后台任务 panel state) —
+     *  自包含模块，见 bg-servers.ts。列表按 CLIENT 存活，不随对话切换/结束消失。 */
+    /** 文件树 / 预览读写 / SCM 查询 / watcher —— 自包含模块，见 files-service.ts。 */
+    files = new FilesService({
+        emit: (msg) => this.emit(msg),
+        isDisposed: () => this.disposed,
+        getCwd: () => this.cwd,
+        getActiveCwd: () => this.conv?.cwd ?? this.cwd,
+    });
+    bg = new BgServerTracker({
+        emit: (msg) => this.emit(msg),
+        flushSnapshot: () => this.flushSnapshot(),
+        isDisposed: () => this.disposed,
+        // 插件注册的常驻任务（host.registerBackgroundTask）并入同一「后台任务」面板。
+        pluginTasks: () => this.pluginBgTasksProvider?.() ?? [],
+    });
+    /** index.ts 注入（经 AgentService 拷贝到每个新会话）：把 SDK 工具执行事件转发给
+     *  插件（PluginManager.emitToolEvent）。未设置时不做任何事。 */
+    onToolEvent = undefined;
+    /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
+    /** index.ts 注入：读取插件当前注册的斜杠命令（目录展示 + prompt 拦截执行）。 */
+    /** index.ts 注入：读取插件注册的常驻后台任务（并入 bg_servers 面板）。 */
+    pluginBgTasksProvider = undefined;
+    /** index.ts 注入：停止插件任务（kill_background_server with taskId）。 */
+    pluginStopBgTask = undefined;
+    /** 上一轮注入会话的插件工具名集合（用于检测注销/移除）。 */
+    /** The active conversation (all session operations target it). */
+    get conv() {
+        const conv = this.convs.get(this.activeId);
+        if (!conv)
+            throw new Error("no active conversation");
+        return conv;
+    }
+    /** Runtime of the active conversation. */
+    get runtime() {
+        return this.conv.runtime;
+    }
+    /** Session of the active conversation. */
+    get conversationId() { return this.activeId; }
+    get session() {
+        return this.conv.session;
+    }
+    /** PTYs are owned by individual conversations; this getter targets the active one
+     * for compatibility with the existing terminal-panel dispatch path. */
+    get terminals() {
+        return this.conv.terminals;
+    }
+    getTerminalManager(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.terminals;
+    }
+    getTerminalCwd(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.cwd ?? this.cwd;
+    }
+    makeTerminalManager(conversationId, cwd) {
+        const mgr = new TerminalManager((msg) => this.emitTerminal(conversationId, msg), cwd);
+        return mgr;
+    }
+    emitTerminal(conversationId, msg) {
+        // Background conversations keep collecting output in their own PTY buffer.
+        // Do not stream it into the active xterm; push the retained window on switch.
+        if (msg.type === "terminal_output" && conversationId !== this.activeId)
+            return;
+        if (msg.type === "terminal_output" || msg.type === "terminal_exit" || msg.type === "terminal_list") {
+            this.emit({ ...msg, conversationId });
+            return;
+        }
+        this.emit(msg);
+    }
+    pushTerminals(conversation = this.conv) {
+        this.emit({
+            type: "terminal_list",
+            conversationId: conversation.id,
+            terminals: conversation.terminals.list(),
+        });
+        for (const output of conversation.terminals.replay()) {
+            this.emit({
+                type: "terminal_output",
+                conversationId: conversation.id,
+                terminalId: output.terminalId,
+                data: output.data,
+            });
+        }
+    }
+    async systemPromptState() {
+        const session = this.session, cwd = this.cwd;
+        await flushPromptReload(session);
+        return getSystemPromptState(session, cwd, this.agentDir);
+    }
+    async savePromptFile(id, version, content, restore) {
+        const path = writeSystemPromptFile(this.session, this.cwd, this.agentDir, id, version, content, restore);
+        for (const client of ClientSession.liveClients.values())
+            for (const conv of client.convs.values()) {
+                if (!promptUsesFile(conv.session, conv.cwd, client.agentDir, path))
+                    continue;
+                await queuePromptReload(conv.session, () => { if (!client.disposed && client.activeId === conv.id) {
+                    client.pushSettings();
+                    void client.pushSlashCommands();
+                    client.flushSnapshot();
+                } });
+            }
+    }
+    async retryPromptReload() { await flushPromptReload(this.session, true); }
+    /** The FULL system prompt actually in effect right now (AgentSession getter,
+     *  includes native sections such as
+     *  project context, skills and tool guidance). Read-only view source for
+     *  the settings panel. */
+    effectiveSystemPrompt() {
+        try {
+            const sp = this.session.systemPrompt;
+            return typeof sp === "string" ? sp : "";
+        }
+        catch {
+            // Session not ready yet.
+            return "";
+        }
+    }
+    pendingMcpReload = new Set();
+    mcpStatus = new WeakMap();
+    async reloadMcpConversation(conv) {
+        const trust = new NativeMcpConfigService().isTrusted(conv.cwd);
+        conv.session.settingsManager.setProjectTrusted(trust);
+        await reloadSession(conv.session);
+        if (conv.id === this.activeId)
+            await this.pushSlashCommands();
+    }
+    async nativeMcpRequest(msg) {
+        const config = new NativeMcpConfigService();
+        const requestSession = this.session;
+        try {
+            if (msg.cwd !== this.cwd || this.switchingWorkspace)
+                throw new Error("Workspace unavailable");
+            if (this.isQuiesced() && msg.action !== "get")
+                throw new Error("Service draining");
+            if (msg.action === "codemode")
+                config.saveCodemode(this.cwd, msg.scope, msg.version ?? "", msg.codemode);
+            if (msg.action === "save")
+                config.save(this.cwd, msg.scope, msg.version ?? "", msg.document ?? {});
+            if (msg.action === "trust")
+                config.trust(this.cwd);
+            if (msg.action === "radius") {
+                if (!this.nativeModelRuntime.hasConfiguredAuth("radius"))
+                    throw new Error("Sign in to Radius first");
+                const state = config.get(this.cwd, "global");
+                const servers = (state.document.mcpServers ?? {});
+                const existing = Object.entries(servers).find(([, entry]) => typeof entry.url === "string" && entry.url.replace(/\/+$/, "") === "https://radius.pi.dev/mcp");
+                let name = existing?.[0] ?? "radius", index = 1;
+                if (!existing)
+                    while (Object.hasOwn(servers, name))
+                        name = `radius-${index++}`;
+                const entry = { ...(existing?.[1] ?? {}), url: "https://radius.pi.dev/mcp", auth: { provider: "radius" } };
+                delete entry.oauth;
+                config.save(this.cwd, "global", state.version, { ...state.document, mcpServers: { ...servers, [name]: entry } });
+                this.emit({ type: "notice", level: "info", text: `Radius MCP 已配置：${name}` });
+            }
+            if (msg.action === "command") {
+                const runner = this.session.extensionRunner;
+                const command = runner?.getCommand("mcp");
+                if (!command || !/^(builtin:mcp|<inline:mcp>)$/.test(command.sourceInfo.path))
+                    throw new Error("Official MCP command unavailable or replaced");
+                if (this.session.isStreaming)
+                    throw new Error("Wait for the current task before managing connections");
+                if (msg.name && !/^[\w.-]+$/.test(msg.name))
+                    throw new Error("Invalid server name");
+                await command.handler(msg.command === "status" ? "" : `${msg.command ?? ""} ${msg.name ?? ""}`, runner.createCommandContext());
+            }
+            if (["save", "trust", "radius", "codemode"].includes(msg.action)) {
+                for (const cs of ClientSession.liveClients.values()) {
+                    for (const conv of cs.convs.values()) {
+                        if (msg.scope === "project" && msg.action !== "radius" && conv.cwd !== msg.cwd)
+                            continue;
+                        if (conv.session.isStreaming)
+                            cs.pendingMcpReload.add(conv.id);
+                        else
+                            await cs.reloadMcpConversation(conv);
+                    }
+                }
+            }
+            if (this.cwd !== msg.cwd || this.session !== requestSession || this.switchingWorkspace)
+                throw new Error("Workspace or conversation changed");
+            const session = requestSession;
+            const runner = session.extensionRunner;
+            const command = runner?.getCommand("mcp");
+            let cached = this.mcpStatus.get(session);
+            if (!cached) {
+                cached = { text: "", pending: false };
+                this.mcpStatus.set(session, cached);
+            }
+            if (command && /^(builtin:mcp|<inline:mcp>)$/.test(command.sourceInfo.path) && !cached.pending) {
+                // Official /mcp waits for startup connections. Never block the settings reply on it.
+                const context = runner.createCommandContext(), target = cached;
+                target.pending = true;
+                void Promise.resolve(command.handler("", { ...context, mode: "rpc", ui: { ...context.ui, notify: (text) => { target.text = text; } } }))
+                    .catch(error => { target.text = String(error); }).finally(() => { target.pending = false; });
+            }
+            const statusText = cached.text;
+            const tools = session.getAllTools().filter(tool => tool.name.startsWith("mcp__"));
+            this.emit({ type: "native_mcp_result", requestId: msg.requestId, cwd: msg.cwd, state: config.get(msg.cwd, msg.scope),
+                pending: [...ClientSession.liveClients.values()].some(cs => cs.pendingMcpReload.size > 0), tools: tools.map(tool => tool.name),
+                toolInfo: tools.map(tool => ({ name: tool.name, exposure: tool.exposure, description: tool.description.slice(0, 2000), readOnly: tool.annotations?.readOnlyHint, destructive: tool.annotations?.destructiveHint })),
+                servers: parseNativeMcpStatus(statusText), statusText,
+                codemode: config.codemode(msg.cwd, msg.scope, session.settingsManager.getSettings().codemode),
+                ...(msg.action === "log" ? { log: config.log() } : {}),
+            });
+        }
+        catch (error) {
+            this.emit({ type: "native_mcp_result", requestId: msg.requestId, cwd: msg.cwd, error: error.message });
+        }
+    }
+    coordinatePlan(conv) {
+        const tree = conv.tree?.refresh();
+        planSettings().coordinate(conv.session, !tree?.externallyModified && !tree?.verifying && !tree?.busy);
+    }
+    async setPlanEnabled(enabled, conversationId) {
+        if (typeof enabled !== "boolean" || this.activeId !== conversationId || this.switchingWorkspace)
+            throw new Error("Conversation changed");
+        if (this.quiesceBlocked())
+            return;
+        planSettings().set(enabled);
+        for (const client of ClientSession.liveClients.values()) {
+            for (const conv of client.convs.values())
+                client.coordinatePlan(conv);
+            client.flushSnapshot();
+        }
+    }
+    get nativeModelRuntime() { return this.runtime.services.modelRuntime; }
+    providerAuth = new ProviderAuthService(() => this.runtime.services.modelRuntime, message => this.emit(message), async () => { this.piConfig.invalidate(); await this.modelAdmin.listProviders(); await this.listModels(); this.flushSnapshot(); }, () => this.session.settingsManager.getOrCreateDeviceId());
+    get webUi() { return this.conv.webUi; }
+    widgetsTimer = null;
+    /** Model-stall watchdog interval (see startStallTimer). */
+    stallTimer = null;
+    /** Connected sockets for this client (multiple tabs share the session). */
+    sinks = new Set();
+    pendingNotices = [];
+    snapshotTimer = null;
+    /** Timestamp of the most recent message_delta push — while fresh, snapshots
+     *  use the slower STREAMING_SNAPSHOT_INTERVAL_MS cadence. */
+    lastDeltaAt = 0;
+    sessionsTimer = null;
+    version = 0;
+    /** Snapshot revision counter (see emitSnapshotNow / protocol snapshot_delta). */
+    snapRev = 0;
+    /** Messages array as of the last emitted snapshot/delta — identity-walked
+     *  against the current array to detect append-only growth. */
+    emittedMessages = null;
+    /** Conversation whose messages emittedMessages belongs to. A conversation
+     *  switch (set_cwd / new_chat / switch_*) must fall back to a FULL snapshot:
+     *  two empty conversations have identical (empty) arrays, so the identity
+     *  walk alone would misread the switch as "nothing changed" → delta. */
+    emittedConvId = null;
+    /** snapRev value at which emittedMessages was captured. */
+    emittedRev = 0;
+    /**
+     * Per-conversation serialization caches (stable message ids, UiMessage
+     * object cache, message-array signature, queue counts) live inside each
+     * Conversation — see Conversation above.
+     */
+    disposed = false;
+    /** pi-config readiness check, cached briefly so 60ms snapshots don't hit disk. */
+    piConfig; // 构造函数里创建（需要 agentDir）
+    /** fs.watch on the currently-listed directory — file changes push an instant
+     *  refresh (`file_changed`) so the tree updates without waiting for the 10s
+     *  poll. Only the listed directory is watched (one level); navigating
+     *  re-watches the new target. fs.watch isn't available on every platform /
+     *  filesystem — failures silently fall back to the poll. */
+    fsWatcher = null;
+    watchPath = null;
+    /** fs.watch on the active repo's git dir — external changes (CLI commit,
+     *  IDE branch switch) push `scm_changed` so the panel refreshes itself.
+     *  One watcher per client session, re-targeted when the queried cwd
+     *  changes; failures (bare repo, unsupported fs) silently disable it. */
+    gitWatcher = null;
+    gitWatchCwd = null;
+    gitDirtyTimer = null;
+    watchTimer = null;
+    constructor(clientId, cwd, agentDir, stateStore, thinkingDurationStore) {
+        this.clientId = clientId;
+        ClientSession.liveClients.set(clientId, this);
+        this.cwd = cwd;
+        this.agentDir = agentDir;
+        this.piConfig = new PiConfigProbe(agentDir);
+        this.stateStore = stateStore;
+        this.thinkingDurationStore = thinkingDurationStore;
+        this.settingsSvc = new SettingsService({
+            clientId,
+            stateStore,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            getSession: () => this.session,
+            cwd: () => this.cwd,
+            agentDir: () => this.agentDir,
+            isStreaming: () => this.session.isStreaming,
+            reloadSession: async () => {
+                const session = this.session;
+                await reloadSession(session);
+                // reload() 会把 custom 工具重新加回活跃集——重放终端开关。
+                if (this.session === session)
+                    await this.pushSlashCommands();
+            },
+            effectiveSystemPrompt: () => this.effectiveSystemPrompt(),
+        });
+        this.modelAdmin = new ModelAdminService({
+            agentDir,
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            modelRuntime: () => this.runtime.services.modelRuntime,
+            invalidatePiConfig: () => {
+                this.piConfig.invalidate();
+            },
+            pushModels: async () => this.listModels(),
+        });
+        // Prune dead background tasks every 30s (only spawns netstat/lsof while
+        // the list is non-empty). unref: must not keep the process alive.
+        this.bg.start();
+    }
+    static async create(clientId, cwd, stateStore, thinkingDurationStore) {
+        const agentDir = process.env.PI_CODING_AGENT_DIR ?? getAgentDir();
+        const cs = new ClientSession(clientId, cwd, agentDir, stateStore, thinkingDurationStore);
+        const conversationId = cs.nextConversationId();
+        const terminals = cs.makeTerminalManager(conversationId, cwd);
+        const runtime = await createAgentSessionRuntime(cs.makeRuntimeFactory(), {
+            cwd,
+            agentDir,
+            // Resume the most recent session for this project — the SDK default
+            // per-project dir (<agentDir>/sessions/--<cwd>--/, shared with the
+            // pi CLI/TUI) — or start a fresh one on first visit.
+            sessionManager: SessionManager.continueRecent(cwd),
+        });
+        // First conversation = the resumed session; it also seeds the shared
+        // ModelRuntime that every later conversation reuses.
+        cs.sharedModelRuntime = runtime.services.modelRuntime;
+        const conv = cs.makeConversation(runtime, conversationId, terminals);
+        cs.convs.set(conv.id, conv);
+        cs.activeId = conv.id;
+        for (const d of runtime.diagnostics) {
+            if (d.type !== "info") {
+                cs.pendingNotices.push({
+                    type: "notice",
+                    level: d.type,
+                    text: d.message,
+                });
+            }
+        }
+        await cs.bindSession();
+        return cs;
+    }
+    /**
+     * Factory for cwd-bound runtimes. All conversations share ONE ModelRuntime
+     * (the model choice is client-wide), so later conversations reuse the
+     * instance created with the first one.
+     */
+    makeRuntimeFactory() {
+        return async ({ cwd, sessionManager }) => {
+            const services = await createAgentSessionServices({
+                cwd,
+                agentDir: this.agentDir,
+                modelRuntime: this.sharedModelRuntime,
+                settingsManager: conversationSettings(cwd, this.agentDir),
+                resourceLoaderOptions: { extensionFactories: nativeToolExtensions() },
+            });
+            const created = await createAgentSessionFromServices({ services, sessionManager });
+            return { ...created, services, diagnostics: services.diagnostics };
+        };
+    }
+    /** Allocate a stable conversation id before constructing its runtime/tools. */
+    nextConversationId() {
+        return `c${++this.convSeq}`;
+    }
+    /** Wrap a fresh runtime as a new conversation record. */
+    makeConversation(runtime, id, terminals) {
+        return {
+            id,
+            recovery: {},
+            webUi: new WebUIContext(msg => this.emit(msg), id, () => `${runtime.cwd} · ${this.convs.get(id)?.title ?? conversationTitle(runtime.session)}`),
+            title: runtime.session.sessionManager.getSessionName() || conversationTitle(runtime.session),
+            runtime,
+            session: runtime.session,
+            cwd: runtime.cwd,
+            createdAt: Date.now(),
+            // A brand-new conversation is not yet in the running list — it enters
+            // only when it is displaced to the background while still streaming.
+            listed: false,
+            promptedSinceActive: false,
+            lastActiveAt: Date.now(),
+            lastSdkEventAt: Date.now(),
+            lastTaskEndedAt: undefined,
+            stallNoticed: false,
+            runningToolNames: new Map(),
+            toolsExecutedSincePrompt: false,
+            toolTextContinues: 0,
+            toolRanSinceContinue: false,
+            deltaSeq: 0,
+            thinkingTimings: new ThinkingTimings(),
+            terminals,
+            msgIds: new Map(),
+            nextMsgId: 1,
+            userSeqByTs: new Map(),
+            userSeqByKey: new Map(),
+            uiMessageCache: new Map(),
+            lastMessagesSig: "",
+            lastMessagesArray: [],
+            queueSteering: [],
+            queueFollowUp: [],
+            toolStartTimes: new Map(),
+        };
+    }
+    /** Summaries of conversations currently streaming — captured at shutdown
+     *  so the next attach can tell the user their run was interrupted. */
+    streamingSummaries() {
+        const out = [];
+        for (const conv of this.convs.values()) {
+            if (conv.session.isStreaming)
+                out.push({ title: conv.title, cwd: conv.cwd });
+        }
+        return out;
+    }
+    /** Tell the user about runs lost to the last server restart (once). */
+    notifyInterrupted(list) {
+        if (!list || list.length === 0)
+            return;
+        const names = list
+            .map((r) => `「${r.title}」（${r.cwd}）`)
+            .join("、");
+        this.pendingNotices.push({
+            type: "notice",
+            level: "warning",
+            text: `上次服务重启时有 ${list.length} 个进行中的对话被中断：${names}。可在历史对话中恢复继续。`,
+        });
+    }
+    /** Add a socket to this client's broadcast set; flushes buffered startup notices. */
+    attachSink(send) {
+        this.sinks.add(send);
+        this.idleSince = 0;
+        for (const result of this.recalledQueues.values())
+            send(result);
+        this.providerAuth.replay();
+        for (const conv of this.convs.values()) {
+            conv.webUi.replayDialogs(send);
+            conv.webUi.replayTitle(send);
+            send({ type: "widgets", conversationId: conv.id, widgets: conv.webUi.snapshot() });
+            send({ type: "statuses", conversationId: conv.id, statuses: conv.webUi.statusSnapshot() });
+        }
+        for (const conv of this.convs.values())
+            if (conv.stallNoticed && conv.session.isStreaming)
+                send({ type: "agent_silence", conversationId: conv.id, phase: "silent", since: conv.lastSdkEventAt, activity: conv.runningToolNames.size ? "tool" : "model" });
+        for (const msg of this.pendingNotices)
+            send(msg);
+        this.pendingNotices = [];
+        // Replay current extension widgets (setWidget may have fired during
+        // session creation, before any socket was attached).
+        // Reconnect: push the current project's running-conversation list so the
+        // left panel shows every background chat (a fresh socket never got the
+        // newChat/switch pushes).
+        this.emitConversations();
+        // Reconnect: same for the slash-command catalog (the picker needs it even
+        // before the client asks).
+        void this.pushSlashCommands();
+        // Reconnect: push the remembered goal prefs (model choice, rounds cap,
+        // locked) so the goal bar restores them on reload — "全局记忆".
+        // Reconnect: push the settings panel state (prompt text/mode, skill &
+        // extension toggles, saved presets).
+        this.pushSettings();
+        // Reconnect: push the background-task list — it must survive reconnects
+        // and outlive the conversation that started the tasks.
+        this.bg.push();
+        // PTYs are conversation-owned and survive a socket reconnect.
+        this.pushTerminals();
+    }
+    detachSink(send) {
+        this.sinks.delete(send);
+        // PTYs intentionally survive a socket drop: they are owned by the
+        // conversation and can be inspected after reconnecting. Only conversation
+        // disposal or server shutdown kills them.
+        if (this.sinks.size === 0) {
+            this.idleSince = Date.now();
+            this.files.unwatchDir();
+        }
+    }
+    /** ms epoch since the last socket detached (0 while attached). */
+    idleSince = Date.now();
+    /** True when nothing is attached or running, so the session can be rebuilt on demand. */
+    isEvictable(now, idleMs) {
+        return isClientEvictable({
+            socketCount: this.sinks.size,
+            idleSince: this.idleSince,
+            streamingConversations: this.activeConversations(),
+            queuedMessages: this.pendingMessages(),
+            liveTerminals: [...this.convs.values()].reduce((n, conv) => n + conv.terminals.list().length, 0),
+            backgroundTasks: this.bg.hasServers() ? 1 : 0,
+            switchingWorkspace: this.cwdSwitchRunning,
+            disposed: this.disposed,
+        }, now, idleMs);
+    }
+    /** Broadcast to every connected socket of this client. */
+    emit(msg) {
+        if (this.disposed)
+            return;
+        for (const sink of [...this.sinks])
+            sink(msg);
+    }
+    /** (Re)attach event plumbing to the ACTIVE conversation's session. */
+    boundUiSessions = new WeakSet();
+    async bindSession(conv = this.conv) {
+        if (this.disposed || this.convs.get(conv.id) !== conv)
+            return;
+        conv.unsubscribe?.();
+        if (conv.session !== conv.runtime.session) {
+            conv.webUi.dispose();
+            conv.webUi = new WebUIContext(msg => this.emit(msg), conv.id, () => `${conv.cwd} · ${conv.title}`);
+        }
+        conv.session = conv.runtime.session;
+        conv.tree ??= new SessionTreeController({
+            conversationId: conv.id, runtime: () => conv.runtime,
+            active: () => this.activeId === conv.id && this.convs.get(conv.id) === conv,
+            admitted: () => !this.quiesceBlocked(),
+            emit: message => this.emit(message),
+            changed: () => { this.coordinatePlan(conv); this.scheduleSnapshot(); this.scheduleSessionsRefresh(); },
+            replaced: async () => { conv.treeProjectionRevision = undefined; conv.uiMessageCache.clear(); conv.title = conv.runtime.session.sessionManager.getSessionName() || conversationTitle(conv.runtime.session); await this.bindSession(conv); this.invalidateLists(); this.flushSnapshot(true); },
+            summary: operation => { conv.recovery = { ...conv.recovery, branch: operation, summary: !operation && conv.recovery.summary?.source === "branchSummary" ? undefined : conv.recovery.summary }; this.flushSnapshot(); },
+        });
+        conv.tree.bindFile();
+        if (!this.boundUiSessions.has(conv.session)) {
+            this.boundUiSessions.add(conv.session);
+            const session = conv.session;
+            const reload = session.reload.bind(session);
+            session.reload = async (options) => {
+                conv.webUi.dispose();
+                conv.webUi = new WebUIContext(msg => this.emit(msg), conv.id, () => `${conv.cwd} · ${conv.title}`);
+                await reload({ ...options, beforeSessionStart: async () => {
+                        session.extensionRunner.setUIContext(conv.webUi, "rpc");
+                        await options?.beforeSessionStart?.();
+                    } });
+                this.coordinatePlan(conv);
+            };
+        }
+        const runtime = conv.runtime;
+        const session = conv.session;
+        await session.bindExtensions({
+            mode: "rpc",
+            uiContext: conv.webUi,
+            onError: (err) => {
+                this.emit({ type: "notice", conversationId: conv.id, level: "error", text: err.error });
+            },
+        });
+        if (this.disposed || this.convs.get(conv.id) !== conv || conv.session !== session) {
+            // An async session_start may finish after the first shutdown.
+            // Dispose the captured runtime again to release those late resources.
+            await runtime.dispose();
+            return;
+        }
+        this.coordinatePlan(conv);
+        const unsubscribe = conv.session.subscribe((event) => this.onEvent(conv, event));
+        conv.unsubscribe = unsubscribe;
+        this.scheduleSnapshot();
+        conv.webUi.refresh();
+        this.startWidgetsTimer();
+        this.startStallTimer();
+    }
+    /** Poll extension widgets so TUI-only overlays (e.g. rpiv-todo) stay live. */
+    startWidgetsTimer() {
+        if (this.disposed || this.widgetsTimer)
+            return;
+        this.widgetsTimer = setInterval(() => {
+            if (!this.disposed)
+                for (const conv of this.convs.values())
+                    conv.webUi.refresh();
+        }, WIDGET_REFRESH_MS);
+    }
+    /** Report a quiet model or tool as conversation-scoped state. The WebSocket
+     * heartbeat is separate: a live socket does not imply a live model request. */
+    startStallTimer() {
+        if (this.disposed || this.stallTimer || STALL_NOTIFY_MS === 0)
+            return;
+        this.stallTimer = setInterval(() => {
+            if (this.disposed)
+                return;
+            const now = Date.now();
+            for (const conv of this.convs.values()) {
+                if (!isRecovering(conv.recovery) &&
+                    !conv.stallNoticed &&
+                    conv.session.isStreaming &&
+                    now - conv.lastSdkEventAt > STALL_NOTIFY_MS) {
+                    conv.stallNoticed = true;
+                    this.emit({ type: "agent_silence", conversationId: conv.id, phase: "silent", since: conv.lastSdkEventAt, activity: conv.runningToolNames.size ? "tool" : "model" });
+                }
+            }
+        }, 30_000);
+    }
+    /** Cancel a tool's watchdog — called when the tool finishes normally. */
+    /** Cancel every watchdog of a conversation (removeConversation / dispose). */
+    onEvent(conv, event) {
+        const contextTokens = event.type === "compaction_start" ? conv.session.getContextUsage()?.tokens ?? undefined : event.type === "compaction_end" && event.result ? conv.session.messages.reduce((total, message) => total + estimateTokens(message), 0) : undefined;
+        conv.recovery = recoveryEvent(conv.recovery, event, Date.now(), contextTokens);
+        if (event.type === "agent_settled" || event.type === "message_end")
+            conv.tree?.refresh();
+        // Any SDK event proves the run is alive — feeds the stall watchdog below.
+        if (conv.stallNoticed)
+            this.emit({ type: "agent_silence", conversationId: conv.id, phase: "active", since: Date.now(), activity: conv.runningToolNames.size ? "tool" : "model" });
+        conv.lastSdkEventAt = Date.now();
+        conv.stallNoticed = false;
+        switch (event.type) {
+            case "bash_execution_update": {
+                if (event.id) {
+                    this.emit({
+                        type: "tool_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
+                        toolCallId: event.id,
+                        toolName: "bash",
+                        delta: event.delta,
+                    });
+                }
+                break;
+            }
+            case "tool_execution_start": {
+                if (event.parentToolCallId)
+                    this.emit({
+                        type: "tool_status", conversationId: conv.id, parentToolCallId: event.parentToolCallId,
+                        toolCallId: event.toolCallId, toolName: event.toolName, isError: false, running: true,
+                        argumentsText: JSON.stringify(event.args)?.slice(0, 20_000),
+                    });
+                conv.runningToolNames.set(event.toolCallId, event.toolName);
+                conv.toolsExecutedSincePrompt = true;
+                conv.toolRanSinceContinue = true;
+                // Record the moment the tool actually starts so tool_status can
+                // report real execution time (vs. time spent waiting on the model).
+                conv.toolStartTimes.set(event.toolCallId, Date.now());
+                // Snapshot listeners before a bash run — the post-run diff catches
+                // servers the agent started in the background.
+                if (event.toolName === "bash") {
+                    this.bg.snapshotBefore();
+                }
+                // 插件扩展点：工具开始执行（异常由 emitToolEvent 隔离）。
+                this.onToolEvent?.({ phase: "start", toolName: event.toolName, conversationId: conv.id });
+                break;
+            }
+            case "tool_execution_end": {
+                conv.runningToolNames.delete(event.toolCallId);
+                const startedAt = conv.toolStartTimes.get(event.toolCallId);
+                conv.toolStartTimes.delete(event.toolCallId);
+                // Bash finished — wait briefly for background servers to bind their
+                // ports, then diff against the pre-run snapshot and record them.
+                if (event.toolName === "bash")
+                    void this.bg.trackAfterBash();
+                const durationMs = startedAt !== undefined ? Date.now() - startedAt : undefined;
+                // 插件扩展点：工具结束执行（带耗时与错误标志）。
+                this.onToolEvent?.({
+                    phase: "end",
+                    toolName: event.toolName,
+                    conversationId: conv.id,
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                    isError: event.isError,
+                });
+                const exitCode = toolExitCode(event.result, event.isError);
+                this.emit({
+                    type: "tool_status",
+                    conversationId: conv.id,
+                    running: false,
+                    parentToolCallId: event.parentToolCallId,
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    isError: event.isError,
+                    exitCode,
+                    durationMs,
+                });
+                break;
+            }
+            case "tool_execution_update": {
+                const update = toolOutputUpdate(event.partialResult);
+                const codemode = event.toolName === "codemode" ? codemodeDetails(event.partialResult?.details) : undefined;
+                if (update || codemode) {
+                    this.emit({
+                        type: "tool_delta",
+                        parentToolCallId: event.parentToolCallId,
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                        delta: "",
+                        ...update,
+                        codemode,
+                    });
+                }
+                break;
+            }
+            case "queue_update":
+                conv.queueSteering = event.steering.map(skillAwareTitleText).map(text => text.length > 2000 ? text.slice(0, 2000) + "…" : text);
+                conv.queueFollowUp = event.followUp.map(skillAwareTitleText).map(text => text.length > 2000 ? text.slice(0, 2000) + "…" : text);
+                break;
+            // A run finished or a new entry was persisted — keep the session list fresh
+            // (new chat + first message, completed turns, compaction, etc.).
+            case "agent_settled": {
+                this.coordinatePlan(conv);
+                if (this.pendingMcpReload.delete(conv.id))
+                    void this.reloadMcpConversation(conv).catch(error => this.emit({ type: "notice", level: "error", text: `MCP reload failed: ${error.message}` }));
+                conv.lastTaskEndedAt = Date.now();
+                this.scheduleSessionsRefresh();
+                void this.continueAfterToolText(conv);
+                // Deferred settings reload: settings (system prompt / skills /
+                // extensions) changed while the run was streaming — applying now
+                // would have torn down the in-flight run.
+                if (this.settingsSvc.hasPendingReload() && !this.disposed) {
+                    this.settingsSvc.consumePendingReload();
+                    void this.applySettingsReload();
+                }
+                break;
+            }
+            case "entry_appended":
+                this.scheduleSessionsRefresh();
+                break;
+            case "message_end": {
+                if (event.message.role === "assistant") {
+                    conv.thinkingTimings.finish(event.message.timestamp);
+                    this.thinkingDurationStore.save(conv.session.sessionFile, event.message.timestamp, conv.thinkingTimings.finishedDurations(event.message.timestamp));
+                }
+                break;
+            }
+            case "message_update": {
+                conv.thinkingTimings.observe(event.message.timestamp, event.assistantMessageEvent);
+                // Live assistant-message increment, deliberately OUTSIDE the snapshot
+                // channel: send() drops snapshots under backpressure (big sessions),
+                // but this small message must always get through or the UI freezes on
+                // stale state. Only the ACTIVE conversation streams to the browser —
+                // background conversations would clobber the streaming view; their
+                // state arrives via snapshot when switched to.
+                if (conv.id !== this.conv.id)
+                    break;
+                const ame = event.assistantMessageEvent;
+                const m = event.message;
+                this.lastDeltaAt = Date.now();
+                this.emit({
+                    type: "message_delta",
+                    conversationId: conv.id,
+                    seq: ++conv.deltaSeq,
+                    // Must match serializeStreamingMessage()'s stable id so deltas
+                    // patch onto the snapshot's streamingMessage and reconcile.
+                    messageId: `stream-${m?.timestamp ?? 0}`,
+                    usage: (() => {
+                        try {
+                            const t = this.session.getSessionStats().tokens;
+                            return t ? { input: t.input, output: t.output, total: t.total } : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    })(),
+                    // Strip `partial` (the cumulative message): re-serializing it per
+                    // token is exactly what we're trying to avoid. The next snapshot
+                    // carries the authoritative full message anyway.
+                    assistantMessageEvent: {
+                        type: ame.type,
+                        contentIndex: "contentIndex" in ame ? ame.contentIndex : undefined,
+                        delta: "delta" in ame ? ame.delta : undefined,
+                    },
+                });
+                break;
+            }
+            default:
+                break;
+        }
+        // Snapshot checkpoint policy: deltas carry live rendering during streaming;
+        // full snapshots are reconciliation checkpoints taken immediately at
+        // run/tool boundaries and on a slow timer otherwise.
+        if (event.type === "agent_settled" || event.type === "tool_execution_end") {
+            this.flushSnapshot();
+        }
+        else {
+            this.scheduleSnapshot();
+        }
+    }
+    /** Debounced push of the persisted session list + open conversations. */
+    scheduleSessionsRefresh() {
+        if (this.sessionsTimer)
+            return;
+        this.sessionsTimer = setTimeout(() => {
+            this.sessionsTimer = null;
+            if (this.disposed)
+                return;
+            for (const conv of [...this.convs.values()]) {
+                if (conv.wiki && conv.id !== this.activeId && !conv.session.isStreaming && conv.terminals.list().length === 0)
+                    this.removeConversation(conv.id);
+            }
+            this.invalidateLists();
+            this.emitConversations();
+            void this.pushSessions();
+        }, 800);
+        // pushSessions no-ops unless the client opted in via list_sessions.
+    }
+    toolContentIds = new WeakMap();
+    toolContentSeq = 0;
+    /** Serialize a persisted message with a STABLE id + cached object reference. */
+    serializeCached(m, entryId, occurrence = 0) {
+        const conv = this.conv;
+        // toolResult messages are keyed by toolCallId; everything else by
+        // role+timestamp. A single prompt can emit several same-role messages
+        // within the SAME millisecond (multiple attachment asides), so the
+        // timestamp alone collides in the cache and only the first one renders
+        // — append a full-content fingerprint to keep them distinct while
+        // staying stable across snapshots (content never changes once persisted).
+        const contentKey = m.role === "toolResult"
+            ? `t:${m.toolCallId}`
+            : `${m.role}:${m.timestamp}:${contentFingerprint(m)}`;
+        const key = entryId ? `entry:${entryId}:${contentKey}` : occurrence ? `${contentKey}:occurrence:${occurrence}` : contentKey;
+        let n = conv.msgIds.get(key);
+        if (n === undefined) {
+            n = conv.nextMsgId++;
+            conv.msgIds.set(key, n);
+        }
+        // Persisted content is immutable; inspect mutable projected metadata without
+        // rebuilding or hashing the potentially very large output on every snapshot.
+        let toolRevision = "";
+        if (m.role === "toolResult") {
+            let contentId = this.toolContentIds.get(m.content);
+            if (contentId === undefined) {
+                contentId = ++this.toolContentSeq;
+                this.toolContentIds.set(m.content, contentId);
+            }
+            const metadata = serializeMessage({ ...m, content: [] }, n);
+            toolRevision = `:${contentId}:${createHash("sha256").update(JSON.stringify(metadata)).digest("hex")}`;
+        }
+        const cacheKey = `${key}#${n}${toolRevision}`;
+        const cached = conv.uiMessageCache.get(cacheKey);
+        if (cached)
+            return cached;
+        // User-message id suffix is a 1-based count of user messages sharing
+        // this timestamp (that's what resolveUserMessageEntryId() expects). n is
+        // a global per-conversation counter across ALL roles, so it can't be
+        // reused as the seq — otherwise editing anything but the first question
+        // fails to resolve ("找不到要编辑的消息").
+        let seq = n;
+        if (m.role === "user") {
+            // Assigned once per message: re-serializing after cache eviction must
+            // keep the same id, or edits resolve the wrong message.
+            const known = conv.userSeqByKey.get(key);
+            if (known !== undefined)
+                seq = known;
+            else {
+                const ts = m.timestamp ?? 0;
+                seq = (conv.userSeqByTs.get(ts) ?? 0) + 1;
+                conv.userSeqByTs.set(ts, seq);
+                conv.userSeqByKey.set(key, seq);
+            }
+        }
+        const measured = conv.thinkingTimings.annotate(serializeMessage(m, seq), m.timestamp ?? 0);
+        const msg = this.thinkingDurationStore.annotate(measured, conv.session.sessionFile, m.timestamp ?? 0);
+        if (msg) {
+            if (m.role === "toolResult")
+                msg.toolOutputUrl = `/api/tool-output?${new URLSearchParams({ clientId: this.clientId, conversationId: conv.id, toolCallId: m.toolCallId })}`;
+            conv.uiMessageCache.set(cacheKey, msg);
+            // Bound the cache (marathon sessions otherwise grow without limit;
+            // single messages can reach TEXT_CAP = 200K chars). Map iteration is
+            // insertion order, so dropping from the front evicts the oldest —
+            // recent messages (the ones every snapshot touches) always survive.
+            // Safe: a miss just recomputes an identical object on next access.
+            // Every snapshot walks the whole transcript, so the cap must cover it:
+            // a cap below the message count evicts entries just before they are
+            // needed again and every snapshot re-serializes everything.
+            let excess = conv.uiMessageCache.size - (conv.session.agent.state.messages.length + UI_MESSAGE_CACHE_CAP);
+            while (excess-- > 0) {
+                const oldest = conv.uiMessageCache.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                conv.uiMessageCache.delete(oldest);
+            }
+        }
+        return msg;
+    }
+    /** Current messages array (with the existing sig-reuse optimization).
+     *  Element objects are reference-stable (serializeCached cache), which is
+     *  what lets emitSnapshotNow detect append-only growth via identity walk. */
+    currentMessages() {
+        const conv = this.conv;
+        const tree = conv.tree?.refresh();
+        const messageKey = (m) => m.role === "toolResult" ? `t:${m.toolCallId}` : `${m.role}:${m.timestamp}:${contentFingerprint(m)}`;
+        if (tree && conv.treeProjectionRevision !== tree.revision) {
+            conv.treeEntryIds = new Map();
+            for (const entry of conv.session.sessionManager.buildSessionProjection().entries)
+                for (const m of entry.messages) {
+                    const key = messageKey(m), ids = conv.treeEntryIds.get(key) ?? [];
+                    ids.push(entry.sourceEntry.id);
+                    conv.treeEntryIds.set(key, ids);
+                }
+            conv.treeProjectionRevision = tree.revision;
+        }
+        const occurrences = new Map();
+        const rawMessages = projectToolTextMessages(conv.session.agent.state.messages
+            .map((m) => {
+            const key = messageKey(m), index = occurrences.get(key) ?? 0;
+            occurrences.set(key, index + 1);
+            const entryId = conv.treeEntryIds?.get(key)?.[index];
+            const value = this.serializeCached(m, entryId, index);
+            return value ? conv.tree?.decorate(value, entryId) ?? value : null;
+        })
+            .filter((m) => m !== null));
+        // Reuse the previous array when nothing changed: the element objects are
+        // cached (reference-stable) anyway, and a stable array reference lets the
+        // frontend memoize derived maps instead of rebuilding them every 60ms.
+        const sig = rawMessages.map((m) => m.id).join("\u0001");
+        const messages = conv.lastMessagesArray.length === rawMessages.length && rawMessages.every((m, i) => m === conv.lastMessagesArray[i]) ? conv.lastMessagesArray : rawMessages;
+        conv.lastMessagesSig = sig;
+        conv.lastMessagesArray = messages;
+        return messages;
+    }
+    /** Build every UiState field EXCEPT messages (the expensive part). */
+    buildLightState(rev, messages) {
+        const conv = this.conv;
+        const state = conv.session.agent.state;
+        const model = state.model;
+        const streamingMessage = state.streamingMessage
+            ? conv.thinkingTimings.annotate(serializeStreamingMessage(state.streamingMessage), state.streamingMessage.timestamp ?? 0)
+            : null;
+        let stats = {
+            totalMessages: 0,
+            tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            cost: 0,
+            contextUsage: { tokens: null, contextWindow: 0, percent: null },
+            contextParts: null,
+        };
+        try {
+            const s = this.session.getSessionStats();
+            stats = {
+                totalMessages: s.totalMessages,
+                tokens: s.tokens,
+                cost: s.cost,
+                contextUsage: s.contextUsage
+                    ? {
+                        tokens: s.contextUsage.tokens,
+                        contextWindow: s.contextUsage.contextWindow,
+                        percent: s.contextUsage.percent,
+                    }
+                    : stats.contextUsage,
+                contextParts: estimateContextParts(this.session.messages, this.session.systemPrompt, s.contextUsage?.tokens ?? null),
+            };
+        }
+        catch {
+            // stats are best-effort
+        }
+        return {
+            planSettings: planSettings().state(conv.session),
+            tree: conv.tree?.refresh(),
+            clientId: this.clientId,
+            cwd: this.cwd,
+            sessionId: this.session.sessionId,
+            sessionFile: this.session.sessionFile,
+            conversationId: this.activeId,
+            cwdEvents: this.session.sessionManager.getBranch()
+                .filter((entry) => entry.type === "custom" && entry.customType === "pi-harness:cwd-switch" && typeof entry.data?.cwd === "string")
+                .slice(-40)
+                .map((entry) => ({ cwd: entry.data.cwd, timestamp: Date.parse(entry.timestamp) })),
+            rev,
+            // The in-progress assistant message lives in state.streamingMessage
+            // (the SDK only pushes it into state.messages at message_end). Surfacing
+            // it here is what makes thinking + text stream into the browser at
+            // ~60ms granularity instead of appearing only when the turn finishes.
+            streamingMessage,
+            taskProgress: deriveTaskProgress(conv.id, taskHistoryFromSession(conv.session.sessionManager, (message, entryId) => this.serializeCached(message, entryId)) ?? messages, streamingMessage, conv.session.isStreaming, conv.lastTaskEndedAt),
+            isStreaming: this.session.isStreaming,
+            recovery: recoverySnapshot(conv.recovery),
+            runSettings: { autoCompaction: conv.session.autoCompactionEnabled, autoRetry: conv.session.autoRetryEnabled },
+            model: model
+                ? {
+                    id: model.id,
+                    name: model.name,
+                    provider: model.provider,
+                    vision: model.input?.includes("image") ?? false,
+                }
+                : null,
+            ...(this.session.routedModel ? { routedModel: {
+                    id: this.session.routedModel.model.id, name: this.session.routedModel.model.name,
+                    provider: this.session.routedModel.model.provider,
+                    vision: this.session.routedModel.model.input.includes("image"),
+                    thinkingLevel: this.session.routedModel.thinkingLevel,
+                } } : {}),
+            thinkingLevel: state.thinkingLevel,
+            // Only the levels the current model actually supports — the SDK clamps
+            // anything else, so the UI must not offer (or must disable) the rest.
+            availableThinkingLevels: this.session.getAvailableThinkingLevels(),
+            queue: { steering: conv.queueSteering, followUp: conv.queueFollowUp },
+            errorMessage: state.errorMessage,
+            tools: state.tools.map((t) => t.name),
+            version: ++this.version,
+            piConfigured: this.isPiConfigured(),
+            piAgentInstalled: isPiCliInstalled(),
+            stats,
+        };
+    }
+    /** Emit one snapshot update — incremental when possible, full otherwise.
+     *
+     *  Persisted messages are content-immutable with reference-stable objects
+     *  (serializeCached), so an IDENTITY WALK over the previous array detects
+     *  append-only growth in O(n) pointer compares. Appends travel as
+     *  snapshot_delta carrying only the new tail + light fields; any mid-array
+     *  change/truncation (switch session, edit fork, compaction) or a forced
+     *  resync falls back to a full snapshot. The 10MB-stringify-per-checkpoint
+     *  cost of big sessions collapses to a few hundred bytes for the common
+     *  "nothing but stats/version changed" checkpoint. */
+    emitSnapshotNow(forceFull = false) {
+        if (this.disposed)
+            return;
+        const cur = this.currentMessages();
+        const prev = this.emittedMessages;
+        let incremental = !forceFull &&
+            prev !== null &&
+            this.emittedConvId === this.activeId &&
+            prev.length <= cur.length;
+        if (incremental && prev) {
+            for (let i = 0; i < prev.length; i++) {
+                if (prev[i] !== cur[i]) {
+                    incremental = false;
+                    break;
+                }
+            }
+        }
+        const rev = ++this.snapRev;
+        if (incremental && prev) {
+            const baseRev = this.emittedRev;
+            this.emittedMessages = cur;
+            this.emittedConvId = this.activeId;
+            this.emittedRev = rev;
+            this.emit({
+                type: "snapshot_delta",
+                conversationId: this.activeId,
+                rev,
+                baseRev,
+                appended: cur.slice(prev.length),
+                state: this.buildLightState(rev, cur),
+            });
+        }
+        else {
+            this.emittedMessages = cur;
+            this.emittedConvId = this.activeId;
+            this.emittedRev = rev;
+            this.emit({
+                type: "snapshot",
+                state: { ...this.buildLightState(rev, cur), messages: cur },
+            });
+        }
+    }
+    /** Resolve a browser-bridged dialog (select/confirm/input) for this session. */
+    cancelRecovery(conversationId, operationId) {
+        const conv = this.convs.get(conversationId);
+        if (!conv || conversationId !== this.activeId)
+            return;
+        const { compaction, retry, summary, branch } = conv.recovery;
+        if (branch?.id === operationId)
+            conv.session.abortBranchSummary();
+        else if (summary?.id === operationId) {
+            if (summary.source === "branchSummary")
+                conv.session.abortBranchSummary();
+            else
+                conv.session.abortCompaction();
+        }
+        else if (compaction?.id === operationId)
+            conv.session.abortCompaction();
+        else if (retry?.id === operationId)
+            conv.session.abortRetry();
+    }
+    async treeRequest(message) {
+        const conv = this.convs.get(message.conversationId);
+        if (!conv?.tree || conv.id !== this.activeId) {
+            this.emit({ type: "tree_navigate_result", conversationId: message.conversationId, reqId: message.reqId, status: "error", error: "只能操作当前活动对话。" });
+            return;
+        }
+        await conv.tree.request(message);
+        this.coordinatePlan(conv);
+        this.flushSnapshot(true);
+    }
+    setRunSettings(message) {
+        const conv = this.convs.get(message.conversationId);
+        if (!conv || conv.id !== this.activeId)
+            return;
+        setConversationRunSettings(conv.session.settingsManager, message);
+        this.flushSnapshot();
+    }
+    recalledQueues = new Map();
+    acknowledgeQueueRecall(conversationId, requestId) {
+        if (this.recalledQueues.get(requestId)?.conversationId === conversationId)
+            this.recalledQueues.delete(requestId);
+    }
+    recallQueue(conversationId, requestId) {
+        const conv = this.convs.get(conversationId);
+        if (!conv || conversationId !== this.activeId)
+            return;
+        const previous = this.recalledQueues.get(requestId);
+        if (previous) {
+            this.emit(previous);
+            return;
+        }
+        if (this.recalledQueues.size >= 8) {
+            this.emitNotice("warning", "请先接收已撤回的消息，再继续撤回。");
+            return;
+        }
+        const restored = recallPending(conv.session);
+        const result = { type: "queue_recalled", conversationId, requestId, text: [...restored.steering, ...restored.followUp].join("\n\n"), images: restored.images };
+        this.recalledQueues.set(requestId, result);
+        this.emit(result);
+        this.flushSnapshot();
+    }
+    toolResultForDownload(conversationId, toolCallId) {
+        const conv = this.convs.get(conversationId);
+        if (!conv)
+            throw Object.assign(new Error("Output access denied"), { code: "EACCES" });
+        // Context projection omits pre-compaction records. Native entries retain them.
+        const result = conv.session.sessionManager.getEntries().flatMap(entry => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolCallId === toolCallId ? [entry.message] : []).at(-1)
+            ?? conv.session.messages.find(m => m.role === "toolResult" && m.toolCallId === toolCallId);
+        if (!result || result.role !== "toolResult")
+            throw Object.assign(new Error("Output access denied"), { code: "EACCES" });
+        return { conv, result };
+    }
+    async listToolOutputs(conversationId, toolCallId) {
+        const { conv, result } = this.toolResultForDownload(conversationId, toolCallId);
+        const path = nativeToolDetails(result.toolName, result)?.fullOutputPath;
+        const text = result.content.filter(part => part.type === "text").map(part => part.text).join("\n");
+        return toolOutputManifest(conv.cwd, result.toolName, text, typeof path === "string" ? path : undefined);
+    }
+    async downloadToolOutput(conversationId, toolCallId, outputId) {
+        const { conv, result } = this.toolResultForDownload(conversationId, toolCallId);
+        const path = nativeToolDetails(result.toolName, result)?.fullOutputPath;
+        if (outputId && !(typeof path === "string" && outputId === toolOutputId(path))) {
+            const output = (await this.listToolOutputs(conversationId, toolCallId)).find(output => output.id === outputId);
+            if (!output)
+                throw Object.assign(new Error("Output access denied"), { code: "EACCES" });
+            return { name: output.name, handle: await openToolOutput(conv.cwd, output.path) };
+        }
+        if (typeof path === "string")
+            return { name: path.split(/[\\/]/).pop(), handle: await openToolOutput(conv.cwd, path) };
+        return { name: "tool-output.txt", handle: { createReadStream: () => Readable.from(result.content.filter(part => part.type === "text").map(part => part.text + "\n")) } };
+    }
+    resolveDialog(conversationId, id, value) {
+        if (conversationId !== this.activeId)
+            return;
+        this.convs.get(conversationId)?.webUi.resolveDialog(id, value);
+    }
+    /** Whether the pi agent config looks ready (cached for 2s). */
+    isPiConfigured() {
+        return this.piConfig.isConfigured();
+    }
+    /** Set by index.ts: called when /pi-harness:quit is invoked. */
+    onQuit = undefined;
+    /** 本客户端成功切换工作区（set_cwd）后触发，参数为新绝对路径。
+     *  attach 时由 AgentService 接到全局 onClientCwdChanged —— 编辑器等
+     *  工作区跟随型插件借此把根目录切到用户当前项目。 */
+    onCwdChanged = undefined;
+    /** Ask the npm registry for the latest pi-harness version and report it. */
+    async checkUpdate() {
+        return checkUpdate((msg) => this.emit(msg));
+    }
+    async checkComponentUpdates(requestId) {
+        const session = this.session;
+        const cwd = this.cwd;
+        this.emit({ type: "component_updates", requestId, cwd, phase: "checking", items: [] });
+        try {
+            const manager = packageManagerFor(session, cwd, this.agentDir);
+            const items = await checkComponents(updateTargets(session, manager));
+            this.emit({ type: "component_updates", requestId, cwd, phase: "ready", items, restartRequired: componentRestartRequired() });
+        }
+        catch (error) {
+            this.emit({ type: "component_updates", requestId, cwd, phase: "error", items: [], error: String(error) });
+        }
+    }
+    async updateComponent(requestId, id) {
+        const cwd = this.cwd;
+        const session = this.session;
+        this.emit({ type: "component_updates", requestId, cwd, phase: "updating", items: [] });
+        try {
+            const manager = packageManagerFor(session, cwd, this.agentDir);
+            const targets = updateTargets(session, manager);
+            await updateComponentPackage(targets, id, (source) => manager.update(source));
+            // SDK modules may be shared by other conversations. Restart, rather than
+            // hot-swapping one session and claiming every session now runs new code.
+            const items = await checkComponents(updateTargets(session, manager));
+            this.emit({ type: "component_updates", requestId, cwd, phase: "updated", items, restartRequired: true });
+        }
+        catch (error) {
+            this.emit({ type: "component_updates", requestId, cwd, phase: "error", items: [], error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    async installPiAgent() {
+        await installPiAgent(this.agentDir, (msg) => this.emit(msg));
+        this.flushSnapshot();
+    }
+    /** Send a snapshot immediately (cancels any pending throttled one).
+     *  forceFull skips the incremental path — used by get_state so a (re)
+     *  connecting or desynced client always receives an authoritative full
+     *  state it can rebuild from. */
+    flushSnapshot(forceFull = false) {
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        this.emitSnapshotNow(forceFull);
+    }
+    scheduleSnapshot() {
+        if (this.snapshotTimer || this.disposed)
+            return;
+        // During active streaming the deltas carry live rendering — full snapshots
+        // are just a periodic reconciliation checkpoint, so send them far less
+        // often (they serialize the whole session; big sessions made this path OOM).
+        const interval = Date.now() - this.lastDeltaAt < DELTA_ACTIVE_WINDOW_MS
+            ? STREAMING_SNAPSHOT_INTERVAL_MS
+            : SNAPSHOT_INTERVAL_MS;
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            this.emitSnapshotNow();
+        }, interval);
+    }
+    /** Slash-command catalog + native command execution — 自包含模块，见
+     *  slash-commands.ts（内置命令拦截 + 扩展/模板/技能目录推送）。 */
+    slash = new SlashCommandsService({
+        emit: (msg) => this.emit(msg),
+        cwd: () => this.cwd,
+        getSession: () => this.session,
+        startNewSession: () => this.startNewSession(),
+        treeCommand: async (name, args, context) => {
+            const conv = this.conv;
+            if (conv.id !== context.conversationId)
+                return;
+            if (name === "tree" || name === "fork")
+                this.emit({ type: "tree_open", conversationId: conv.id, mode: name === "fork" ? "fork" : "tree" });
+            else if (name === "name") {
+                conv.tree?.assertWritable();
+                if (!args.trim()) {
+                    this.emitNotice("info", "用法：/name <名称>");
+                    return;
+                }
+                conv.session.setSessionName(args.trim().slice(0, 200));
+                conv.title = args.trim().slice(0, 200);
+                this.invalidateLists();
+                this.scheduleSessionsRefresh();
+                this.flushSnapshot();
+            }
+            else
+                await this.treeRequest({ type: "session_clone", conversationId: conv.id, reqId: `command-${context.requestId}` });
+        },
+        setModel: (id) => this.setModel(id),
+        setCwd: (path) => this.setCwd(path),
+        setThinking: (level) => this.setThinking(level),
+        refreshSessions: () => this.refreshSessions(),
+        onQuit: () => this.onQuit?.() ?? false,
+    });
+    /** Catalog push — index.ts get_commands / attach / cwd 切换等都会调用。 */
+    pushSlashCommands() {
+        return this.slash.push();
+    }
+    /** 模型/服务商配置管理 —— 自包含模块，见 model-admin.ts。 */
+    modelAdmin;
+    /** Persist an api-key credential for a provider (auth.json). */
+    setProviderApiKey(provider, apiKey) {
+        return this.modelAdmin.setProviderApiKey(provider, apiKey);
+    }
+    clearProviderApiKey(provider) {
+        return this.modelAdmin.clearProviderApiKey(provider);
+    }
+    listProviders() {
+        return this.modelAdmin.listProviders();
+    }
+    listModelsConfig() {
+        return this.modelAdmin.listModelsConfig();
+    }
+    fetchModelsList(reqId, baseUrl, apiKey, authHeader, api) {
+        return this.modelAdmin.fetchModelsList(reqId, baseUrl, apiKey, authHeader, api);
+    }
+    refreshProviderModels(providerId, reqId) {
+        return this.modelAdmin.refreshProviderModels(providerId, reqId);
+    }
+    /** Copy a built-in provider into an editable custom-provider draft
+     *  (clone_provider_result) — lets the user run a second API key without
+     *  overwriting the built-in one. */
+    cloneProvider(providerId, reqId) {
+        return this.modelAdmin.cloneProvider(providerId, reqId);
+    }
+    saveModelConfig(providerId, config) {
+        return this.modelAdmin.saveModelConfig(providerId, config);
+    }
+    deleteModelConfig(providerId) {
+        return this.modelAdmin.deleteModelConfig(providerId);
+    }
+    // ---------------------------------------------------------------------------
+    // Settings (system prompt / skills / extensions / presets)
+    // ---------------------------------------------------------------------------
+    /** Push the full settings state (current settings + loaded skills/extensions
+     *  with enabled flags + saved presets). Pushed on attach and after every
+     *  settings change. */
+    pushSettings() {
+        this.settingsSvc.push();
+    }
+    /** Extensions/skills changed externally (e.g. `pi remove` finished in the
+     *  terminal): re-run session.reload() and re-push state. Streaming-safe —
+     *  deferred to agent_settled, same as settings reloads. */
+    async reloadExtensions() {
+        return this.settingsSvc.applyRuntime();
+    }
+    /** Persist + apply a partial settings update (prompt text/mode, toggles). */
+    async setSettings(partial) { await this.settingsSvc.set(partial); }
+    /** Replace the current settings with the named preset and apply it. */
+    /** Remove a named preset. */
+    /** Make settings effective in the running runtime（流式中则延迟到 agent_settled）。 */
+    async applyRuntimeSettings() {
+        return this.settingsSvc.applyRuntime();
+    }
+    /** 把终端工具开关应用到 session 的活跃工具集：关闭时从活跃集中剔除
+     *  terminal_*（工具仍留在注册表，重开时可直接加回）。session.reload() 与新
+     *  会话创建都会把 custom 工具加回活跃集，所以这两条路径之后都要重放本方法。 */
+    /** 把插件 AI 工具同步进一个已存在的会话（新增/更新/移除）。
+     *  实际 diff 逻辑在 plugins.ts 的 syncPluginToolsIntoSession（可单测）。 */
+    /** index.ts 经 pluginMgr.onAgentToolsChanged 触发：把插件 AI 工具推入全部会话。 */
+    async applySettingsReload() {
+        // 兼容旧入口：reload + 刷目录在宿主回调里完成
+        return this.settingsSvc.applyRuntime();
+    }
+    // ---------------------------------------------------------------------------
+    // Commands
+    // ---------------------------------------------------------------------------
+    /** True when the service is draining (quiesced): emits a rejection notice
+     *  and returns true. Guards every NEW-work entry point (prompt / new chat /
+     *  edit-resend / session resume / goal wizard) — existing runs keep going.
+     *  Called BEFORE any LLM/token work starts so quiesce is a hard admission
+     *  gate, not a best-effort hint. */
+    quiesceBlocked() {
+        if (!this.isQuiesced())
+            return false;
+        this.emit({
+            type: "notice",
+            level: "error",
+            text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-harness server unquiesce 可恢复。",
+        });
+        this.flushSnapshot();
+        return true;
+    }
+    /** Conversations with an in-flight run — active work for quiesce status. */
+    activeConversations() {
+        let n = 0;
+        for (const c of this.convs.values()) {
+            try {
+                if (c.session.isStreaming)
+                    n += 1;
+            }
+            catch {
+                // session being replaced — not running
+            }
+        }
+        return n;
+    }
+    /** Messages queued in the SDK (steer + follow-up) — pending work for
+     *  quiesce status. Quiesce refuses to add more, so this only drains. */
+    pendingMessages() {
+        let n = 0;
+        for (const c of this.convs.values())
+            n += c.queueFollowUp.length + c.queueSteering.length;
+        return n;
+    }
+    async prompt(text, attachments, 
+    /**
+     * true = followUp: while streaming, queue the prompt and deliver it only
+     * after the WHOLE run finishes (补充 button — "AI 生成结束才发送").
+     * false/undefined = steer: the pi CLI Enter semantic — injected right
+     * after the current turn settles, skipping remaining planned tool calls.
+     */
+    queue = false, requestId, onAccepted) {
+        const conv = this.conv;
+        let acknowledged = false;
+        const acknowledge = (ok, commandExecuted) => {
+            if (acknowledged)
+                return;
+            acknowledged = true;
+            if (requestId)
+                this.emit({ type: "prompt_result", requestId, conversationId: conv.id, ok, commandExecuted, attachmentsConsumed: ok && !commandExecuted });
+            onAccepted?.(ok);
+        };
+        try {
+            if (!["tree", "fork"].includes(parseSlash(text)?.name ?? ""))
+                await conv.tree?.waitForVerification();
+            const s = conv.session;
+            await flushPromptReload(s);
+            const promptReloadError = promptReloadStatus(s).reloadError;
+            if (promptReloadError)
+                throw new Error(`Native prompt reload failed: ${promptReloadError}`);
+            if (this.conv !== conv || conv.session !== s)
+                throw new Error("Conversation changed");
+            const extensionCommand = text.startsWith("/") && s.extensionRunner.getCommand(text.slice(1).split(" ", 1)[0]);
+            if (!extensionCommand) {
+                attachments = resolveNativeAttachments(s, attachments);
+                validateEditorSnapshots(this.cwd, attachments);
+            }
+            // Native slash commands (see NATIVE_COMMANDS) are executed here and
+            // never reach the SDK. Extension / skill / template commands fall
+            // through — AgentSession.prompt() handles those itself.
+            const slash = parseSlash(text);
+            if (slash?.name === "reload")
+                acknowledge(true);
+            if (slash && (await this.slash.exec(slash.name, slash.args, { conversationId: conv.id, requestId: requestId ?? `reload-${Date.now()}` }))) {
+                acknowledge(true);
+                this.flushSnapshot();
+                return;
+            }
+            // Native commands above are pure config tweaks (no tokens) — allow them
+            // even while quiesced. Everything that reaches the SDK is NEW work and
+            // is refused until admission reopens.
+            if (this.quiesceBlocked())
+                throw new Error("服务暂停接收消息");
+            if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
+                const temporary = skillAwareTitleText(text).trim().replace(/\s+/g, " ");
+                conv.title = temporary.length > 30 ? `${temporary.slice(0, 30)}…` : temporary;
+                this.emitConversations();
+            }
+            // Bundle file context with the question as one native queue item.
+            const asides = await buildAttachmentMessages({
+                cwd: this.cwd,
+                clientId: this.clientId,
+                emit: (msg) => this.emit(msg),
+                session: this.session,
+            }, extensionCommand ? undefined : attachments);
+            await conv.tree?.waitForVerification();
+            if (this.conv !== conv || conv.session !== s)
+                throw new Error("Conversation changed");
+            if (!s.isStreaming) {
+                conv.toolsExecutedSincePrompt = false;
+                conv.lastTaskEndedAt = undefined;
+            }
+            conv.toolTextContinues = 0;
+            this.coordinatePlan(conv);
+            await deliverPrompt(s, text, asides, queue, acknowledge);
+        }
+        catch (err) {
+            acknowledge(false);
+            this.emit({
+                type: "notice",
+                level: "error",
+                conversationId: conv.id,
+                text: `提示发送失败：${err.message}`,
+            });
+        }
+        // The active conversation has been continued since it was opened — it
+        // must not be dismissed when the user switches away. (Also bumps the
+        // per-project "most recently active" order used by set_cwd.)
+        conv.promptedSinceActive = true;
+        conv.lastActiveAt = Date.now();
+        // Fresh run — restart the stall watchdog window.
+        conv.lastSdkEventAt = Date.now();
+        if (conv.stallNoticed)
+            this.emit({ type: "agent_silence", conversationId: conv.id, phase: "active", since: conv.lastSdkEventAt, activity: "model" });
+        conv.stallNoticed = false;
+        this.flushSnapshot();
+    }
+    /**
+     * Turn attached files into custom-message payloads.
+     *
+     * Text files are size-aware: small files are inlined into the message so the
+     * model sees them immediately; large files are passed as a <file path="...">
+     * reference and the model reads them on demand with its read tool (which has
+     * built-in truncation). Images are always passed as image content. Mode
+     * "lines" inlines only a 1-based inclusive line range of the file. Raw
+     * pasted/dropped/uploaded images (attachment.imageData) skip the workspace
+     * path entirely and go straight to the model as image content. Raw uploaded
+     * files (attachment.fileData) are persisted under <dataDir>/uploads/ and
+     * attached as absolute-path references (small text ones are inlined).
+     */
+    /**
+     * Hard-abort the running agent (Stop button / global 中断). Tries
+     * session.abort() first; if the run is not idle within
+     * HARD_ABORT_TIMEOUT_MS (model stream ignoring the abort signal), the
+     * conversation's runtime is force-disposed and recreated from the last
+     * persisted session so the chat ALWAYS comes back usable — never stuck
+     * overnight. The notice fires only on the forced-reset path.
+     */
+    async abort() {
+        // 只停止智能体运行本身；AI 在后台启动的服务由「后台任务」面板单独
+        // 管理（可逐个停止或全部关闭），不会在停止对话时被连带杀掉。
+        const conv = this.conv;
+        await this.interruptRun(conv, "已停止");
+        conv.runningToolNames.clear();
+        if (conv.stallNoticed)
+            this.emit({ type: "agent_silence", conversationId: conv.id, phase: "active", since: Date.now(), activity: "model" });
+        conv.stallNoticed = false;
+        this.flushSnapshot();
+    }
+    /** Retry only a silent model request with no tool side effects in this turn. */
+    async retrySilentPrompt(conversationId, text) {
+        const conv = this.conv;
+        if (conv.id !== conversationId || isRecovering(conv.recovery) || !conv.stallNoticed || conv.toolsExecutedSincePrompt || conv.runningToolNames.size || !text.trim()) {
+            this.emit({ type: "notice", level: "warning", text: "当前运行状态已变化，无法手动重试；请检查对话后手动发送。" });
+            return;
+        }
+        const user = conv.session.messages.findLast(m => m.role === "user");
+        if (!user || user.role !== "user")
+            return;
+        const original = typeof user.content === "string" ? user.content : user.content.every(b => b.type === "text") ? user.content.map(b => b.type === "text" ? b.text : "").join("\n") : undefined;
+        if (original !== text)
+            return;
+        await this.abort();
+        if (this.conv !== conv || isRecovering(conv.recovery) || conv.toolsExecutedSincePrompt || conv.session.messages.findLast(m => m.role === "user")?.timestamp !== user.timestamp)
+            return;
+        await this.prompt(text);
+    }
+    /**
+     * A model sometimes writes a tool call as text (`<invoke …>` / DSML) instead of
+     * calling the tool. The SDK sees a plain answer and the run ends, leaving the task
+     * half done. Ask the model to re-issue it through the tool channel. Loop guard: at most TOOL_TEXT_MAX_CONTINUES reminder per user prompt,
+     * even when a real tool ran between leaks.
+     * The request is a visible user message and the run can be stopped as usual; when
+     * the guard stops it, the recovery card offers a manual retry.
+     */
+    async continueAfterToolText(conv) {
+        const session = conv.session;
+        if (this.disposed || conv.wiki || session.isStreaming || isRecovering(conv.recovery))
+            return;
+        if (conv.queueSteering.length || conv.queueFollowUp.length || this.quiesceBlocked())
+            return;
+        if (conv.toolTextContinues >= TOOL_TEXT_MAX_CONTINUES || (conv.toolTextContinues > 0 && !conv.toolRanSinceContinue))
+            return;
+        const messages = session.messages;
+        const userIndex = messages.findLastIndex(message => message.role === "user");
+        const last = messages[messages.length - 1];
+        if (userIndex < 0 || !last || last.role !== "assistant" || messages.indexOf(last) <= userIndex)
+            return;
+        if (last.stopReason === "aborted" || last.stopReason === "error")
+            return;
+        if (last.content.some(block => block.type === "toolCall"))
+            return;
+        const text = last.content.map(block => block.type === "text" ? block.text : "").join("\n");
+        if (!unexecutedToolText(text))
+            return;
+        conv.toolTextContinues += 1;
+        conv.toolRanSinceContinue = false;
+        try {
+            if (conv.session !== session || session.isStreaming)
+                return;
+            await deliverPrompt(session, TOOL_TEXT_CONTINUE_PROMPT, [], false, () => { });
+        }
+        catch (error) {
+            this.emit({ type: "notice", level: "error", conversationId: conv.id, text: `自动继续失败：${error.message}` });
+        }
+    }
+    /** Re-push the current list on request (panel opened); prunes dead entries first. */
+    async listBgServers() {
+        await this.bg.listAndPush();
+    }
+    /** 插件任务集合变化时由宿主调用：重推一次 bg_servers（含插件任务）。 */
+    refreshBgTasks() {
+        this.bg.push();
+    }
+    /** 插件设置保存结果等需要从 index.ts 发 notice 时用（emit 是私有的）。 */
+    emitNotice(level, text) {
+        this.emit({ type: "notice", level, text });
+    }
+    /** Kill ONE background server (by port); returns whether anything was killed. */
+    /** Kill ONE background server (by port) OR a plugin task (by taskId). */
+    async killBackgroundServer(port, taskId) {
+        if (taskId) {
+            // 插件任务：交给插件管理器 stop 回调（不杀进程树——任务在宿主进程内）。
+            const ok = this.pluginStopBgTask?.(taskId) ?? false;
+            if (!ok) {
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: `后台任务「${taskId}」不存在或已结束`,
+                });
+            }
+            this.bg.push();
+            this.flushSnapshot();
+            return ok;
+        }
+        if (typeof port !== "number")
+            return false;
+        return this.bg.killOne(port);
+    }
+    /** Kill every background server the agent started; returns the freed ports. */
+    async killAllBackgroundServers() {
+        return this.bg.killAll();
+    }
+    /** Kill only the running bash command(s) — the agent run itself continues
+     *  (the bash tool returns an aborted error and the model moves on). Uses
+     *  the per-client AbortController set registered by
+     *  makeKillableBashTool. */
+    /** Interrupt a run: abort, with a force-reset fallback on timeout. */
+    async interruptRun(conv, reason) {
+        const runtime = conv.runtime;
+        const current = () => !this.disposed && this.convs.get(conv.id) === conv && conv.runtime === runtime;
+        if (!current())
+            return;
+        // The run is only truly stopped when its agent_settled event arrives:
+        // session.abort() can return without stopping anything when the run is
+        // stuck before the agent even started (e.g. a model stream that never
+        // begins), so we watch for agent_settled and force-reset when it never
+        // comes — abort 卡住（超时）或空转（结算窗口）两条路都覆盖。
+        let ended = false;
+        let forced;
+        const off = conv.session.subscribe((e) => {
+            if (e.type === "agent_settled") {
+                ended = true;
+            }
+        });
+        const force = () => {
+            if (forced)
+                return forced;
+            if (!current())
+                return Promise.resolve();
+            return forced = this.forceResetConversation(conv, `${reason}：运行未终止，已强制重置当前对话`);
+        };
+        // 1) abort itself hangs (model stream ignores the signal) → hard kill.
+        const abortTimer = setTimeout(() => {
+            if (!ended)
+                force();
+        }, ClientSession.HARD_ABORT_TIMEOUT_MS);
+        abortTimer.unref?.();
+        // 2) abort itself (Stop semantics: kills the process tree, emits
+        //    agent_end with stopReason "aborted" on the normal path).
+        try {
+            await conv.runtime.session.abort();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `中止失败：${err.message}`,
+            });
+        }
+        // 3) abort returned but no agent_settled within the settle window → the
+        //    run was stuck before it started; force-reset to recover.
+        if (!ended) {
+            await new Promise((r) => setTimeout(r, ClientSession.HARD_ABORT_SETTLE_MS));
+        }
+        clearTimeout(abortTimer);
+        off();
+        if (!ended)
+            await force();
+    }
+    /** Force-reset a conversation: dispose the stuck runtime (kills the hung
+     *  model stream / child processes) and rebuild it from the most recent
+     *  persisted session. The conversation record itself is kept (same id,
+     *  same cwd, same serialization caches), so the UI stays attached. */
+    forcedResets = new WeakMap();
+    forceResetConversation(conv, reason) {
+        const pending = this.forcedResets.get(conv);
+        if (pending)
+            return pending;
+        const operation = this.rebuildConversation(conv, reason).finally(() => this.forcedResets.delete(conv));
+        this.forcedResets.set(conv, operation);
+        return operation;
+    }
+    async rebuildConversation(conv, reason) {
+        const previous = conv.runtime;
+        const current = () => !this.disposed && this.convs.get(conv.id) === conv && conv.runtime === previous;
+        if (!current())
+            return;
+        try {
+            conv.unsubscribe?.();
+            conv.unsubscribe = undefined;
+            const manager = conv.session.sessionManager;
+            const header = manager.getHeader();
+            const wikiManager = conv.wiki ? SessionManager.inMemory(conv.cwd, undefined, [...(header ? [header] : []), ...manager.getEntries()]) : null;
+            // Reopen THIS conversation's file. continueRecent() would pick the most
+            // recently written session of the project, which may be another open chat.
+            const sessionFile = conv.session.sessionFile;
+            conv.toolStartTimes.clear();
+            await previous.dispose();
+            if (!current())
+                return;
+            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(), {
+                cwd: conv.cwd,
+                agentDir: this.agentDir,
+                sessionManager: wikiManager ?? (sessionFile ? SessionManager.open(sessionFile) : SessionManager.create(conv.cwd)),
+            });
+            if (!current()) {
+                await runtime.dispose();
+                return;
+            }
+            conv.runtime = runtime;
+            conv.webUi.dispose();
+            conv.webUi = new WebUIContext(msg => this.emit(msg), conv.id, () => `${conv.cwd} · ${conv.title}`);
+            conv.recovery = {};
+            conv.session = runtime.session;
+            this.emit({ type: "notice", level: "warning", text: reason });
+            // Rebind the recovered conversation itself, which may be in the background.
+            await this.bindSession(conv);
+            if (this.disposed || this.convs.get(conv.id) !== conv || conv.runtime !== runtime)
+                return;
+            this.emitConversations();
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `强制中断失败：${err.message}`,
+            });
+        }
+    }
+    /** /new delegates session creation and history persistence to the SDK; the Web slot is reused. */
+    async startNewSession() {
+        if (this.conv.tree?.busy) {
+            this.emitNotice("warning", "等待当前切换完成。");
+            return;
+        }
+        if (this.quiesceBlocked())
+            return;
+        const previous = this.conv;
+        const model = previous.session.model;
+        const thinking = previous.session.thinkingLevel;
+        const result = await previous.runtime.newSession();
+        if (result.cancelled)
+            return;
+        previous.unsubscribe?.();
+        previous.tree?.dispose();
+        const conv = this.makeConversation(previous.runtime, previous.id, previous.terminals);
+        // IDs and delta sequence remain monotonic within this conversation.
+        conv.wiki = previous.wiki;
+        conv.deltaSeq = previous.deltaSeq;
+        conv.nextMsgId = previous.nextMsgId;
+        conv.createdAt = previous.createdAt;
+        this.convs.set(conv.id, conv);
+        await this.bindSession(conv);
+        if (model)
+            await conv.session.setModel(model);
+        conv.session.setThinkingLevel(thinking);
+        this.invalidateLists();
+        this.emitConversations();
+        if (previous.stallNoticed)
+            this.emit({ type: "agent_silence", conversationId: conv.id, phase: "active", since: Date.now(), activity: "model" });
+        this.flushSnapshot(true);
+        void this.pushSlashCommands();
+    }
+    async newChat(fresh = false, wiki = false) {
+        if (this.conv.tree?.busy) {
+            this.emitNotice("warning", "等待当前切换完成。");
+            return false;
+        }
+        if (this.creatingConversation)
+            return false;
+        this.creatingConversation = true;
+        const previous = this.activeId;
+        try {
+            await this.createChat(fresh, wiki);
+            return this.activeId !== previous;
+        }
+        finally {
+            this.creatingConversation = false;
+        }
+    }
+    async createChat(fresh, wiki = false) {
+        this.invalidateLists();
+        if (this.quiesceBlocked())
+            return;
+        // Reuse an already-open blank conversation instead of piling up new ones
+        // on every click: if the active chat has no messages it IS the new chat
+        // (focus already on it); otherwise switch to the first blank one (under
+        // the per-project running-list model displaced blanks are disposed, so
+        // this branch normally can't exist — kept as a safety net).
+        const isBlank = (c) => {
+            try {
+                return c.session.getSessionStats().totalMessages === 0 && c.terminals.list().length === 0;
+            }
+            catch {
+                // session being replaced — treat as used so we don't switch onto it
+                return false;
+            }
+        };
+        const active = this.conv;
+        if (!fresh && active && !active.wiki && isBlank(active)) {
+            this.flushSnapshot();
+            return;
+        }
+        for (const conv of this.convs.values()) {
+            if (conv.id === this.activeId)
+                continue;
+            if (!fresh && !conv.wiki && isBlank(conv)) {
+                await this.switchConversation(conv.id);
+                this.flushSnapshot();
+                return;
+            }
+        }
+        // Wiki opens a fresh session for each document. Retire the outgoing idle
+        // runtime after success; temporary Wiki history is discarded with it.
+        const replaceActive = fresh && active && !active.session.isStreaming && active.terminals.list().length === 0 ? active : null;
+        // Cap is per project — conversations of other projects keep their own
+        // lists and don't consume this project's slots.
+        const openInProject = [...this.convs.values()].filter((c) => c.cwd === this.cwd).length;
+        if (openInProject >= MAX_OPEN_CONVERSATIONS && !replaceActive) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+            });
+            return;
+        }
+        // The outgoing conversation is left behind — apply the running-list
+        // lifecycle. Removal is deferred until the new chat exists so the active
+        // conversation stays valid during the (async) runtime creation.
+        const displaced = replaceActive ?? this.displaceActive();
+        // Carry the model and thinking level chosen in the active chat over to the
+        // new chat so they don't silently revert to the defaults. Some models reject
+        // the default "off" level (e.g. always-thinking GLM), so this matters for Wiki.
+        const prevModel = this.conv.session.agent.state.model ?? null;
+        const prevThinking = this.conv.session.thinkingLevel;
+        try {
+            const conversationId = this.nextConversationId();
+            const terminals = this.makeTerminalManager(conversationId, this.cwd);
+            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(), {
+                cwd: this.cwd,
+                agentDir: this.agentDir,
+                sessionManager: wiki ? SessionManager.inMemory(this.cwd) : SessionManager.create(this.cwd),
+            });
+            const conv = this.makeConversation(runtime, conversationId, terminals);
+            conv.wiki = wiki;
+            this.convs.set(conv.id, conv);
+            this.activeId = conv.id;
+            if (displaced)
+                this.removeConversation(displaced.id);
+            await this.bindSession();
+            // New session seeds with the ModelRuntime default model — restore the
+            // model the user had selected in the previous chat.
+            if (prevModel && this.sharedModelRuntime) {
+                try {
+                    await this.session.setModel(prevModel);
+                }
+                catch {
+                    // model no longer resolvable — keep the default
+                }
+            }
+            // setModel applied the default level for the model; restore the chosen one (clamped by the SDK).
+            if (prevModel)
+                this.session.setThinkingLevel(prevThinking);
+            this.emitConversations();
+            this.pushTerminals();
+            // The new runtime re-discovered skills/templates — refresh the catalog
+            // so the picker stops showing the previous runtime's list.
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `新建对话失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * The active conversation is being left (new_chat / switch_conversation /
+     * set_cwd). Runs the running-list lifecycle:
+     *
+     * - still streaming → it becomes a background run: ensure it is listed;
+     * - idle + listed + continued → keep it (the user did continue it);
+     * - any retained terminal state → keep it listed until the terminals are closed;
+     * - idle + just-viewed (never prompted this visit) → ALSO kept listed, as
+     *   long as the owning project is under its MAX_OPEN_CONVERSATIONS cap.
+     *   Disposing on every glance meant switching back to a project you'd only
+     *   looked at (not typed into) paid a full cold restart — a fresh
+     *   AgentSessionRuntime + SessionManager.continueRecent() disk resume +
+     *   TerminalManager — every single time. That cost is real on any
+     *   platform but lands hardest on Windows (slower fs I/O, AV scanning
+     *   every spawned process/file, ConPTY init), which is what made "project
+     *   switching" itself feel slow rather than just the first visit. Idle
+     *   conversations are cheap to hold (no streaming, no PTYs) — bounding by
+     *   the existing per-project cap keeps memory use where it already was
+     *   allowed to go, just makes it more likely to actually get there.
+     * - only over-cap does the caller now actually drop it (returns it so
+     *   removal happens after the active conversation has been switched away).
+     */
+    displaceActive() {
+        const conv = this.conv;
+        // An isolated reviewer can keep working while the main session is idle;
+        // retain that conversation so its review is not disposed when the user
+        // switches away without sending another prompt.
+        if (conv.session.isStreaming) {
+            conv.listed = true;
+            return null;
+        }
+        // Terminal state is a reason to keep an otherwise idle conversation alive:
+        // switching chats must not kill a PTY the user or agent may still need.
+        if (conv.terminals.list().length > 0) {
+            conv.listed = true;
+            return null;
+        }
+        if (conv.wiki)
+            return conv;
+        if (conv.listed && conv.promptedSinceActive)
+            return null;
+        // Idle and never continued this visit — still worth keeping warm
+        // (see above) unless doing so would push this project over its cap,
+        // in which case free the slot the old way.
+        const openInProject = [...this.convs.values()].filter((c) => c.cwd === conv.cwd).length;
+        if (openInProject < MAX_OPEN_CONVERSATIONS) {
+            conv.listed = true;
+            return null;
+        }
+        return conv;
+    }
+    /** Remove a conversation from the running list and free its runtime. The
+     *  session stays persisted on disk, so it remains recoverable from the
+     *  history list. Never removes the active conversation. */
+    removeConversation(id) {
+        const conv = this.convs.get(id);
+        if (!conv || id === this.activeId)
+            return Promise.resolve();
+        conv.tree?.dispose();
+        conv.webUi.dispose();
+        this.convs.delete(id);
+        conv.terminals.killAll();
+        conv.unsubscribe?.();
+        conv.unsubscribe = undefined;
+        return conv.runtime.dispose().catch(() => { });
+    }
+    /** Switch the ACTIVE conversation without interrupting any other chat. */
+    async switchConversation(id) {
+        if (this.conv.tree?.busy) {
+            this.emitNotice("warning", "等待当前切换完成。");
+            return;
+        }
+        if (!this.convs.has(id) || id === this.activeId)
+            return;
+        const displaced = this.displaceActive();
+        this.activeId = id;
+        this.cwd = this.conv.cwd;
+        // All listed conversations share the current project's cwd, so this is
+        // normally a no-op — kept defensive for stale clients.
+        if (displaced)
+            this.removeConversation(displaced.id);
+        this.conv.promptedSinceActive = false;
+        this.conv.lastActiveAt = Date.now();
+        this.webUi.refresh();
+        this.emitConversations();
+        this.pushTerminals();
+        // The switched-to conversation has its own runtime (own resource cache).
+        void this.pushSlashCommands();
+        this.flushSnapshot();
+    }
+    /** Push the current project's running-conversation list to the client. */
+    emitConversations() {
+        const conversations = [];
+        for (const conv of this.convs.values()) {
+            // Wiki history stays out of the project list. Keep only running Wiki
+            // tasks reachable so users can stop a background run.
+            if (conv.wiki && !conv.session.isStreaming)
+                continue;
+            // Always include the active conversation. A fresh session has no
+            // transcript yet, so history cannot provide its sidebar row.
+            if (conv.cwd !== this.cwd || (!conv.listed && conv.id !== this.activeId))
+                continue;
+            let messageCount = 0;
+            let isStreaming = false;
+            try {
+                messageCount = conv.session.getSessionStats().totalMessages;
+                isStreaming = conv.session.isStreaming;
+            }
+            catch {
+                // session being replaced — report defaults
+            }
+            conversations.push({
+                branchPoints: conv.tree?.refresh().branchPoints,
+                parentSessionPath: conv.session.sessionManager.getHeader()?.parentSession,
+                id: conv.id,
+                createdAt: conv.createdAt,
+                title: conv.title,
+                cwd: conv.cwd,
+                messageCount,
+                isStreaming,
+                // resolve() so it is byte-comparable with the paths
+                // SessionManager.list() reports to the client — the two are
+                // compared as plain strings there, and an unnormalized form
+                // here would make the dedup silently miss.
+                sessionFile: conv.session.sessionFile
+                    ? resolve(conv.session.sessionFile)
+                    : undefined,
+            });
+        }
+        this.emit({
+            type: "conversations",
+            conversations,
+            activeId: this.activeId,
+        });
+    }
+    /** List persisted sessions for this client, newest first. */
+    /** The client asked for the session list at least once (lazy loading) —
+     *  background refreshes only re-push when this is true, so a mobile
+     *  client that never opened the panel never pays the disk scan. */
+    sessionsRequested = false;
+    sessionQueries = new QueryCache(5_000);
+    projectQueries = new QueryCache(30_000, 1);
+    invalidateLists() {
+        this.sessionQueries.clear();
+        this.projectQueries.clear();
+    }
+    /** Push the persisted session list to the client (client-requested). */
+    async refreshSessions() {
+        this.sessionsRequested = true;
+        await this.pushSessions();
+    }
+    branchCounts = new SessionBranchCounts();
+    async pushSessions() {
+        if (!this.sessionsRequested)
+            return;
+        const cwd = this.cwd;
+        try {
+            // Sessions live in the SDK default per-project dir
+            // (<agentDir>/sessions/--<cwd>--/), the same files the pi CLI/TUI
+            // use — one listing covers every conversation of the current folder.
+            const sorted = await this.sessionQueries.get(cwd, async () => {
+                const infos = await SessionManager.list(cwd);
+                // SDK SessionInfo includes allMessagesText. Retain only UI summaries.
+                const sessions = new Map();
+                const selected = infos.sort((a, b) => b.created.getTime() - a.created.getTime()).slice(0, 200);
+                const counts = await this.branchCounts.getMany(selected.map(info => resolve(info.path)));
+                for (const [index, info] of selected.entries()) {
+                    const path = resolve(info.path);
+                    sessions.set(path, {
+                        path, name: info.name, firstMessage: info.firstMessage,
+                        parentSessionPath: info.parentSessionPath,
+                        branchPoints: counts[index],
+                        messageCount: info.messageCount, modified: info.modified.getTime(),
+                        created: info.created.getTime(), source: "web",
+                    });
+                }
+                // 创建时间新→旧；条目位置此后固定（UI 不再按选中/活动重排）。
+                return [...sessions.values()].sort((a, b) => b.created - a.created).slice(0, 200);
+            }, () => { if (this.cwd === cwd)
+                void this.pushSessions(); });
+            this.emit({ type: "sessions", cwd, sessions: sorted });
+        }
+        catch {
+            this.emit({ type: "sessions", cwd, sessions: [] });
+        }
+    }
+    /** Remove an entry from the client's recent-project list (UI state only). */
+    async removeProject(path) {
+        this.invalidateLists();
+        this.stateStore.removeProject(this.clientId, path);
+        await this.pushProjects();
+    }
+    /** Permanently delete a persisted session transcript file (history list ✕). */
+    async deleteSession(path) {
+        this.invalidateLists();
+        try {
+            const abs = resolve(path);
+            // Guardrail: only transcripts under the shared sessions root
+            // (<agentDir>/sessions/) may be deleted — never arbitrary files.
+            const sessionsRoot = resolve(this.agentDir, "sessions");
+            if (!abs.startsWith(sessionsRoot + sep)) {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: "只能删除会话目录中的对话记录",
+                });
+                return;
+            }
+            // Warm, idle runtimes are caches, not active use. Protect actual work
+            // before releasing any matching runtimes and deleting the transcript.
+            const owners = [...this.convs.values()].filter((conv) => conv.session.sessionFile && resolve(conv.session.sessionFile) === abs);
+            for (const conv of owners) {
+                if (conv.id === this.activeId || conv.session.isStreaming ||
+                    conv.queueSteering.length > 0 || conv.queueFollowUp.length > 0 ||
+                    conv.terminals.list().length > 0) {
+                    this.emit({
+                        type: "notice",
+                        level: "warning",
+                        text: conv.id === this.activeId
+                            ? "该对话正在使用中，请先切换到其他对话再删除"
+                            : "该对话仍有后台任务或终端，请先停止任务并关闭终端再删除",
+                    });
+                    return;
+                }
+            }
+            await Promise.all(owners.map((conv) => this.removeConversation(conv.id)));
+            rmSync(abs, { force: true });
+            this.emitConversations();
+            await this.refreshSessions();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `删除会话失败：${err.message}`,
+            });
+        }
+    }
+    async browseDirs(path) {
+        return browseDirs(path, (msg) => this.emit(msg));
+    }
+    /** Rename a persisted session (history list ✎).
+     *
+     * The display name lives in the transcript itself as a `session_info`
+     * entry, so renaming means appending one via the SDK rather than touching
+     * any sidecar state — `SessionManager.list()` already surfaces the latest
+     * one as `SessionInfo.name`, which is what the panel renders. An empty
+     * name clears it and the list falls back to the first user message.
+     */
+    async renameSession(path, name) {
+        this.invalidateLists();
+        try {
+            const abs = resolve(path);
+            // Same guardrail as deleteSession: only transcripts under the
+            // shared sessions root may be written, never arbitrary files.
+            const sessionsRoot = resolve(this.agentDir, "sessions");
+            if (!abs.startsWith(sessionsRoot + sep)) {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: "只能重命名会话目录中的对话记录",
+                });
+                return;
+            }
+            const trimmed = name.trim().slice(0, 120);
+            // A live conversation holds its own SessionManager on this file;
+            // append through that one so the two don't fight over the tail.
+            const liveConv = [...this.convs.values()].find((conv) => conv.session.sessionFile === abs);
+            if (liveConv) {
+                liveConv.tree?.assertWritable();
+                liveConv.session.sessionManager.appendSessionInfo(trimmed);
+                liveConv.title = trimmed || conversationTitle(liveConv.session);
+                this.emitConversations();
+            }
+            else {
+                SessionManager.open(abs).appendSessionInfo(trimmed);
+            }
+            await this.refreshSessions();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `重命名会话失败：${err.message}`,
+            });
+        }
+    }
+    /** Open a persisted session as the active conversation (from listSessions).
+     *
+     * A persisted-session click must follow the same ownership rule as
+     * new_chat/switch_conversation: every open conversation keeps its own
+     * runtime. AgentSessionRuntime.switchSession() tears down (and aborts) the
+     * current runtime, which would otherwise stop a response merely because the
+     * user opened history while it was streaming.
+     */
+    async switchSession(path) {
+        if (this.conv.tree?.busy) {
+            this.emitNotice("warning", "等待当前切换完成。");
+            return;
+        }
+        if (this.quiesceBlocked())
+            return;
+        let openedRuntime = null;
+        let openedTerminals = null;
+        try {
+            const targetPath = resolve(path);
+            // A session may already be open in the running-conversation map. Reuse it
+            // instead of creating a second writer for the same JSONL transcript.
+            for (const conv of this.convs.values()) {
+                const sessionFile = conv.session.sessionFile;
+                if (sessionFile && resolve(sessionFile) === targetPath) {
+                    await this.switchConversation(conv.id);
+                    return;
+                }
+            }
+            const sessionManager = SessionManager.open(targetPath);
+            const targetCwd = sessionManager.getCwd();
+            const conversationId = this.nextConversationId();
+            openedTerminals = this.makeTerminalManager(conversationId, targetCwd);
+            openedRuntime = await createAgentSessionRuntime(this.makeRuntimeFactory(), {
+                cwd: targetCwd,
+                agentDir: this.agentDir,
+                sessionManager,
+            });
+            // Only displace the old active conversation after the replacement runtime
+            // is known-good. This keeps a failed history open entirely non-destructive.
+            const oldListed = this.conv.listed;
+            const displaced = this.displaceActive();
+            const openInProject = [...this.convs.values()].filter((c) => c.cwd === targetCwd).length +
+                1 -
+                (displaced?.cwd === targetCwd ? 1 : 0);
+            if (openInProject > MAX_OPEN_CONVERSATIONS) {
+                // displaceActive() may have promoted a streaming conversation into the
+                // running list. Roll that presentation-only mutation back because no
+                // switch will take place.
+                this.conv.listed = oldListed;
+                openedTerminals.killAll();
+                await openedRuntime.dispose();
+                openedRuntime = null;
+                openedTerminals = null;
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个），请先打开某个对话并离开（不继续对话）以移出列表`,
+                });
+                return;
+            }
+            const conv = this.makeConversation(openedRuntime, conversationId, openedTerminals);
+            // Deliberately resumed — must not be dismissed when the user later
+            // switches away without sending a new message.
+            conv.promptedSinceActive = true;
+            this.convs.set(conv.id, conv);
+            this.activeId = conv.id;
+            openedRuntime = null;
+            openedTerminals = null;
+            if (displaced)
+                this.removeConversation(displaced.id);
+            await this.bindSession();
+            this.cwd = targetCwd;
+            this.conv.lastActiveAt = Date.now();
+            this.webUi.refresh();
+            this.emitConversations();
+            this.pushTerminals();
+            // The restored conversation has a fresh project-bound resource cache.
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            openedTerminals?.killAll();
+            if (openedRuntime)
+                await openedRuntime.dispose().catch(() => { });
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换会话失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Map a rendered user-message id (`u-<timestamp>-<seq>`, assigned in
+     * serialize.ts) back to its append-only session entry id. The seq handles
+     * two user messages sharing the same millisecond timestamp.
+     */
+    resolveUserMessageEntryId(messageId) {
+        const m = /^u-(\d+)(?:-(\d+))?$/.exec(messageId);
+        if (!m)
+            return null;
+        const ts = Number(m[1]);
+        const seq = m[2] ? Number(m[2]) : 1;
+        let count = 0;
+        // Resolve against the compaction-aware current leaf path — the same list
+        // the UI renders (state.messages). Scanning the whole file (getEntries)
+        // could match a summarized entry or one on a different branch.
+        for (const entry of this.session.sessionManager.buildContextEntries()) {
+            if (entry.type !== "message")
+                continue;
+            const msg = entry.message;
+            if (!msg || msg.role !== "user" || msg.timestamp !== ts)
+                continue;
+            count += 1;
+            if (count === seq)
+                return entry.id;
+        }
+        return null;
+    }
+    /** Re-ask on a native in-file branch by default; an explicit choice or UI
+     * preference preserves the separate-file fork behavior. Attachments travel
+     * through prompt() again because their original asides remain on the old path. */
+    async editMessage(messageId, text, attachments, options = {}) {
+        if (this.quiesceBlocked())
+            return;
+        const trimmed = text.trim();
+        if (!trimmed) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "编辑内容为空，已取消",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        const conv = this.conv;
+        if (options.conversationId && options.conversationId !== conv.id)
+            return;
+        const entryId = options.entryId ?? this.resolveUserMessageEntryId(messageId);
+        if (!entryId) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: "找不到要编辑的消息（可能已被压缩或不在当前分支）",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        try {
+            attachments = resolveNativeAttachments(conv.session, attachments);
+            validateEditorSnapshots(this.cwd, attachments);
+            // Preserve the model the user had selected — fork() seeds a new
+            // branch with the ModelRuntime default model otherwise.
+            const prevModel = this.session.agent.state.model ?? null;
+            conv.tree?.assertWritable();
+            const entry = conv.session.sessionManager.getEntry(entryId);
+            if (entry?.type !== "message" || entry.message.role !== "user")
+                throw new Error("只能编辑用户消息。");
+            const newSession = options.newSession ?? this.settingsSvc.current.editResendNewSession ?? false;
+            let status = "error";
+            const context = { conversationId: conv.id, reqId: `edit-${randomUUID()}` };
+            await conv.tree?.request(newSession
+                ? { type: "session_fork", ...context, entryId, position: "before" }
+                : { type: "tree_navigate", ...context, targetId: entryId, summary: "none" }, result => { status = result; });
+            if (status !== "ok" || this.conv !== conv)
+                return;
+            await conv.tree?.waitForVerification();
+            if (newSession && prevModel && this.sharedModelRuntime) {
+                try {
+                    await conv.session.setModel(prevModel);
+                }
+                catch { /* Keep the runtime default if unavailable. */ }
+            }
+            await conv.tree?.waitForVerification();
+            if (this.conv !== conv)
+                return;
+            await this.prompt(trimmed, attachments);
+            if (newSession)
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: "已从该问题重新提问（原对话保留在会话列表中）",
+                });
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `编辑重问失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Push the recent-project list (persisted per client, merged with every cwd
+     * that has persisted sessions in this client's session store — so workspaces
+     * opened before the recent-list feature existed still show up).
+     */
+    async pushProjects() {
+        try {
+            const saved = this.stateStore.get(this.clientId);
+            const removedProjects = new Set(this.stateStore.getRemovedProjects(this.clientId));
+            const all = await this.projectQueries.get("all", async () => {
+                const newest = new Map();
+                for (const info of await SessionManager.listAll()) {
+                    if (!info.cwd)
+                        continue;
+                    const previous = newest.get(info.cwd);
+                    newest.set(info.cwd, {
+                        lastUsed: Math.max(previous?.lastUsed ?? 0, info.modified.getTime()),
+                        conversationCount: (previous?.conversationCount ?? 0) + 1,
+                        // 首次添加锚点：该 cwd 下最早的会话创建时间。
+                        firstAdded: Math.min(previous?.firstAdded ?? Number.MAX_SAFE_INTEGER, info.created.getTime()),
+                    });
+                }
+                return [...newest].map(([path, summary]) => ({ path, ...summary }));
+            }, () => { void this.pushProjects(); });
+            // Only keep directories that still exist — a deleted/unmounted workspace
+            // is useless in the picker. Tombstoned entries (explicitly removed by
+            // the user) stay hidden even though session files still mention them.
+            // Order is most recently used/activity first (mergeProjectSummaries).
+            const projects = mergeProjectSummaries(saved.projects.filter((p) => existsSync(p.path)), all.filter((p) => existsSync(p.path)), removedProjects);
+            this.stateStore.rememberDisplayedProjects(this.clientId, projects);
+            this.emit({ type: "projects", projects });
+        }
+        catch {
+            this.emit({ type: "projects", projects: [] });
+        }
+    }
+    /** List a workspace directory (relative to the configured cwd). */
+    async listFiles(relPath) {
+        return this.files.listFiles(relPath);
+    }
+    checkConversationFiles(cwd, reqId, paths) {
+        const current = this.cwd;
+        this.emit({ type: "conversation_files_checked", cwd, reqId, paths: cwd === current && Array.isArray(paths) ? existingConversationFiles(current, paths) : [] });
+    }
+    /** 全局搜索：递归文件名匹配（结果经 search_files_result 回推，reqId 匹配）。 */
+    async searchFiles(query, reqId) {
+        return this.files.searchFiles(query, reqId);
+    }
+    /** SCM 只读查询（结构化 JSON，reqId 匹配）。 */
+    async gitBranch() { return this.files.gitBranch(); }
+    async scmQuery(kind, reqId, arg) {
+        return this.files.scmQuery(kind, reqId, arg);
+    }
+    /** Read a workspace file for the preview panel (size-capped, binary-safe). */
+    async readFile(relPath, options) {
+        return this.files.readFile(relPath, options);
+    }
+    /** Save text from the file preview panel within the active workspace. */
+    async writeFile(relPath, text, options) {
+        return this.files.writeFile(relPath, text, options);
+    }
+    async cycleModel() {
+        try {
+            this.conv.tree?.assertWritable();
+            await this.session.cycleModel();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换模型失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /**
+     * Path completion for the cwd input: expand ~/relative paths, list the parent
+     * directory, and return prefix matches (dirs first, capped).
+     */
+    async completePath(input) {
+        return this.files.completePath(input);
+    }
+    cwdQueue = null;
+    cwdSwitchRunning = false;
+    get switchingWorkspace() { return this.cwdSwitchRunning; }
+    async setCwd(path, id, source) {
+        if (this.conv.tree?.busy) {
+            this.emitNotice("warning", "等待当前切换完成。");
+            return;
+        }
+        return new Promise((done) => {
+            if (this.cwdQueue) {
+                if (this.cwdQueue.id)
+                    this.emit({ type: "cwd_result", requestId: this.cwdQueue.id, cwd: this.cwd, ok: false, error: "superseded" });
+                this.cwdQueue.done();
+            }
+            this.cwdQueue = { path, id, source, done };
+            void this.drainCwdQueue();
+        });
+    }
+    async drainCwdQueue() {
+        if (this.cwdSwitchRunning)
+            return;
+        this.cwdSwitchRunning = true;
+        try {
+            while (this.cwdQueue) {
+                const next = this.cwdQueue;
+                this.cwdQueue = null;
+                await this.commitCwd(next.path, next.id, next.source);
+                next.done();
+            }
+        }
+        finally {
+            this.cwdSwitchRunning = false;
+        }
+    }
+    async commitCwd(newCwd, requestId, source) {
+        const startedAt = Date.now();
+        try {
+            const { resolve } = await import("node:path");
+            // Watchers change only after the target has been prepared.
+            const fs = await import("node:fs/promises");
+            const abs = resolve(newCwd);
+            const st = await fs.stat(abs);
+            if (!st.isDirectory()) {
+                throw new Error("路径不是目录");
+            }
+            if (abs === this.cwd) {
+                if (requestId)
+                    this.emit({ type: "cwd_result", requestId, cwd: abs, ok: true });
+                this.flushSnapshot(true);
+                return;
+            }
+            // The outgoing conversation is left behind — apply the running-list
+            // lifecycle (removal is deferred until the active conversation is
+            // safely switched away).
+            // Prefer the target project's own most recently active conversation;
+            // only create a fresh one (resuming its most recent session) when the
+            // project has none open yet.
+            let target;
+            for (const c of this.convs.values()) {
+                if (c.cwd === abs && !c.wiki &&
+                    (!target || c.lastActiveAt > target.lastActiveAt)) {
+                    target = c;
+                }
+            }
+            if (target) {
+                const displaced = this.displaceActive();
+                this.activeId = target.id;
+                if (displaced)
+                    this.removeConversation(displaced.id);
+            }
+            else {
+                // First visit to this project: resume its most recent session.
+                const conversationId = this.nextConversationId();
+                const terminals = this.makeTerminalManager(conversationId, abs);
+                const newRuntime = await createAgentSessionRuntime(this.makeRuntimeFactory(), {
+                    cwd: abs,
+                    agentDir: this.agentDir,
+                    sessionManager: SessionManager.continueRecent(abs),
+                });
+                const conv = this.makeConversation(newRuntime, conversationId, terminals);
+                this.convs.set(conv.id, conv);
+                try {
+                    await this.bindSession(conv);
+                }
+                catch (error) {
+                    this.removeConversation(conv.id);
+                    throw error;
+                }
+                const displaced = this.displaceActive();
+                this.activeId = conv.id;
+                if (displaced)
+                    this.removeConversation(displaced.id);
+                for (const d of newRuntime.diagnostics) {
+                    if (d.type !== "info") {
+                        this.emit({ type: "notice", level: d.type, text: d.message });
+                    }
+                }
+            }
+            this.pushTerminals();
+            this.conv.promptedSinceActive = false;
+            this.conv.lastActiveAt = Date.now();
+            this.cwd = abs;
+            this.files.unwatchGit();
+            this.files.unwatchDir();
+            if (source !== "ui") {
+                try {
+                    this.session.sessionManager.appendCustomEntry("pi-harness:cwd-switch", { cwd: abs });
+                }
+                catch { /* A transcript write failure must not turn a completed switch into an error. */ }
+            }
+            const preparedAt = Date.now();
+            this.flushSnapshot(true);
+            if (requestId)
+                this.emit({ type: "cwd_result", requestId, cwd: abs, ok: true,
+                    timing: { startedAt, preparedAt, snapshotAt: Date.now() },
+                });
+            // 工作区跟随型插件（编辑器文件树等）同步切根。
+            try {
+                this.onCwdChanged?.(abs);
+            }
+            catch {
+                /* 钩子异常不影响主流程 */
+            }
+            // Remember the new workspace (restore target + recent-project entry).
+            this.stateStore.remember(this.clientId, abs);
+            void this.pushProjects();
+            this.webUi.refresh();
+            this.emitConversations();
+            // Skills / prompt templates are project-bound — refresh the catalog.
+            void this.pushSlashCommands();
+            void this.refreshSessions();
+            // Commands are per-project (.pi/commands.json in the current cwd).
+            void this.listCommands();
+            return;
+        }
+        catch (err) {
+            if (requestId)
+                this.emit({ type: "cwd_result", requestId, cwd: this.cwd, ok: false, error: err.message });
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换工作目录失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot(true);
+    }
+    /** List models that have valid authentication configured. */
+    async listModels() {
+        try {
+            const mr = this.runtime.services.modelRuntime;
+            const available = await mr.getAvailable();
+            const models = available.map((m) => ({
+                id: `${m.provider}/${m.id}`,
+                name: m.name,
+                provider: m.provider,
+                reasoning: m.reasoning,
+                vision: m.input?.includes("image") ?? false,
+            }));
+            this.emit({ type: "models", models });
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `获取模型列表失败：${err.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Goal / review
+    // ---------------------------------------------------------------------------
+    /** Run a git diff (unstaged + staged) in a conversation's workspace, or
+     * "" when not a repo. */
+    /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5"). */
+    async setModel(modelId) {
+        try {
+            this.conv.tree?.assertWritable();
+            const mr = this.runtime.services.modelRuntime;
+            const slash = modelId.indexOf("/");
+            if (slash <= 0 || slash === modelId.length - 1) {
+                throw new Error(`无效的模型 ID：${modelId}`);
+            }
+            const provider = modelId.slice(0, slash);
+            const id = modelId.slice(slash + 1);
+            const model = mr.getModel(provider, id);
+            if (!model)
+                throw new Error(`模型不存在：${modelId}`);
+            await this.session.setModel(model);
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换模型失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** Set the thinking level for future turns. */
+    setThinking(level) {
+        try {
+            this.conv.tree?.assertWritable();
+            this.session.setThinkingLevel(level);
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换思考强度失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    cycleThinking() {
+        try {
+            this.conv.tree?.assertWritable();
+            this.session.cycleThinkingLevel();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `切换思考强度失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** Push the user command list (.pi/commands.json) to the client. */
+    async listCommands() {
+        const cwd = this.cwd;
+        const { commands, path, warning } = await loadCommands(cwd);
+        if (warning) {
+            this.emit({ type: "notice", level: "warning", text: warning });
+        }
+        this.emit({ type: "commands", commands, path, cwd });
+    }
+    /** Persist the user command list (.pi/commands.json). */
+    async saveCommands(commands) {
+        const cwd = this.cwd;
+        const { path, error } = await saveCommandsFile(cwd, commands);
+        if (error) {
+            this.emit({ type: "notice", level: "error", text: error });
+            return;
+        }
+        this.emit({ type: "commands", commands, path, cwd });
+        this.emit({ type: "notice", level: "info", text: `命令已保存：${path}` });
+    }
+    async dispose() {
+        ClientSession.liveClients.delete(this.clientId);
+        this.disposed = true;
+        for (const conv of this.convs.values()) {
+            conv.terminals.killAll();
+        }
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        if (this.sessionsTimer) {
+            clearTimeout(this.sessionsTimer);
+            this.sessionsTimer = null;
+        }
+        if (this.widgetsTimer) {
+            clearInterval(this.widgetsTimer);
+            this.widgetsTimer = null;
+        }
+        if (this.stallTimer) {
+            clearInterval(this.stallTimer);
+            this.stallTimer = null;
+        }
+        this.files.unwatchDir();
+        this.files.unwatchGit();
+        this.providerAuth.cancel();
+        for (const conv of this.convs.values()) {
+            conv.tree?.dispose();
+            conv.webUi.dispose();
+        }
+        this.bg.stop();
+        for (const conv of this.convs.values()) {
+            conv.unsubscribe?.();
+            conv.unsubscribe = undefined;
+            try {
+                await conv.runtime.dispose();
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+}
+export class AgentService {
+    cwd;
+    /** index.ts 注入：SDK 工具执行事件的插件转发钩子，attach 时拷贝到每个新会话。 */
+    onToolEvent = undefined;
+    /** index.ts 注入：读取插件当前注册的 AI 工具（attach 时拷贝到每个新会话）。 */
+    /** index.ts 注入：读取插件当前注册的斜杠命令（attach 时拷贝到每个新会话）。 */
+    /** index.ts 注入：读取插件注册的常驻后台任务（并入 bg_servers 面板）。 */
+    pluginBgTasksProvider = undefined;
+    /** index.ts 注入：停止插件任务（kill_background_server with taskId）。 */
+    pluginStopBgTask = undefined;
+    clients = new Map();
+    /** Quiesce (draining) state — the service refuses NEW work (prompts, forks,
+     *  session resumes, new clients) so a deploy/upgrade/backup can stop cleanly
+     *  once existing runs finish. Controlled via the local control socket:
+     *  `pi-harness server quiesce|unquiesce`. */
+    quiesced = false;
+    quiescedAt = 0;
+    /** Attached browser sockets (reported by index.ts on open/close) — the
+     *  control socket reports real sockets, not cached client-session objects. */
+    socketCount = 0;
+    pending = new Map();
+    stateStore;
+    thinkingDurationStore;
+    /** Set by index.ts: called when /pi-harness:quit is invoked. */
+    onQuit = undefined;
+    /** 任意客户端成功切换工作区后触发（新绝对路径）。index.ts 接到
+     *  PluginManager.notifyCwd，让插件宿主的 host.cwd 实时跟随当前项目。 */
+    onClientCwdChanged = undefined;
+    constructor(cwd, stateFile) {
+        this.cwd = cwd;
+        this.stateStore = new ClientStateStore(stateFile);
+        this.thinkingDurationStore = new ThinkingDurationStore(join(dirname(stateFile), "thinking-durations.json"));
+        const idleMs = clientIdleMsFromEnv(process.env.PI_WEB_CLIENT_IDLE_MINUTES);
+        if (idleMs > 0) {
+            this.evictTimer = setInterval(() => void this.evictIdleClients(idleMs), Math.min(5 * 60_000, idleMs));
+            this.evictTimer.unref();
+        }
+    }
+    evictTimer = null;
+    /** Dispose sessions of clients that left (closed tabs). Persisted state survives; a
+     *  returning clientId simply gets a fresh session. Skipped while draining. */
+    async evictIdleClients(idleMs, now = Date.now()) {
+        if (this.quiesced)
+            return 0;
+        const evicted = [];
+        for (const [id, cs] of [...this.clients]) {
+            if (!cs.isEvictable(now, idleMs))
+                continue;
+            this.clients.delete(id);
+            evicted.push(cs);
+        }
+        await Promise.all(evicted.map((cs) => cs.dispose().catch(() => { })));
+        return evicted.length;
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
+    /** True while the service is draining — new work is refused. */
+    isQuiesced() {
+        return this.quiesced;
+    }
+    /** Enter quiesce: stop admitting new work. Existing runs keep going. */
+    quiesce() {
+        this.quiesced = true;
+        this.quiescedAt = Date.now();
+    }
+    /** Leave quiesce: admit new work again. */
+    unquiesce() {
+        this.quiesced = false;
+        this.quiescedAt = 0;
+    }
+    /** Snapshot for the control socket / status command. */
+    quiesceInfo() {
+        return this.quiesced
+            ? { quiesced: true, quiescedSince: this.quiescedAt }
+            : { quiesced: false };
+    }
+    /** Aggregate across every client session: conversations with in-flight runs. */
+    activeConversations() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.activeConversations();
+        return n;
+    }
+    /** Aggregate across every client session: messages queued in the SDK. */
+    pendingMessages() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.pendingMessages();
+        return n;
+    }
+    /** index.ts calls this when a browser socket opens/closes. */
+    noteSocketOpen() {
+        this.socketCount += 1;
+    }
+    noteSocketClose() {
+        this.socketCount = Math.max(0, this.socketCount - 1);
+    }
+    /** Full status for the control socket / `server status` command. */
+    serviceStatus() {
+        return {
+            pid: process.pid,
+            version: VERSION,
+            cwd: this.cwd,
+            ...this.quiesceInfo(),
+            connectedClients: this.socketCount,
+            clientSessions: this.clients.size,
+            activeConversations: this.activeConversations(),
+            pendingMessages: this.pendingMessages(),
+        };
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
+    async attach(clientId, send) {
+        let cs = this.clients.get(clientId);
+        if (!cs) {
+            const inflight = this.pending.get(clientId);
+            if (inflight) {
+                cs = await inflight;
+            }
+            else {
+                // Restore this client's last-used workspace when it still exists;
+                // Admission gate: while quiesced, only clients with an EXISTING
+                // session may attach (they can watch their runs drain); brand-new
+                // clients are refused — index.ts closes their socket (4403) and the
+                // browser reconnect loop retries after admission reopens.
+                if (this.quiesced) {
+                    throw new QuiesceRejectedError("新连接被拒绝，请等服务器恢复后重试");
+                }
+                // otherwise fall back to the server's configured default cwd.
+                let cwd = this.cwd;
+                const saved = this.stateStore.get(clientId);
+                if (saved.lastCwd && saved.lastCwd !== this.cwd) {
+                    try {
+                        if (statSync(saved.lastCwd).isDirectory())
+                            cwd = saved.lastCwd;
+                    }
+                    catch {
+                        // gone (unmounted drive / deleted) — fall back to the default
+                    }
+                }
+                // Sessions use the SDK default per-project dir — no per-client dir.
+                const creating = ClientSession.create(clientId, cwd, this.stateStore, this.thinkingDurationStore).finally(() => {
+                    this.pending.delete(clientId);
+                });
+                this.pending.set(clientId, creating);
+                cs = await creating;
+                this.clients.set(clientId, cs);
+                // Make sure the restored/default workspace appears in the project list.
+                this.stateStore.remember(clientId, cwd);
+                if (cwd !== this.cwd) {
+                    send({
+                        type: "notice",
+                        level: "info",
+                        text: `已恢复上次的工作目录：${cwd}`,
+                    });
+                }
+            }
+        }
+        // First attach after a restart: report runs that were interrupted when
+        // the previous process shut down (consumed once, then cleared). Queue
+        // BEFORE attachSink so the notice rides the initial pending-notice flush.
+        cs.notifyInterrupted(this.stateStore.takeInterrupted(clientId));
+        cs.attachSink(send);
+        // Forward hooks (set once by index.ts) to every session.
+        cs.onQuit = this.onQuit;
+        cs.onToolEvent = this.onToolEvent;
+        cs.pluginBgTasksProvider = this.pluginBgTasksProvider;
+        cs.pluginStopBgTask = this.pluginStopBgTask;
+        cs.isQuiesced = () => this.quiesced;
+        // 插件宿主工作区跟随：初次接入也同步一次（恢复的 lastCwd 可能≠服务启动目录），
+        // notifyCwd 幂等去重；此后 set_cwd 成功时由 cs.onCwdChanged 继续驱动。
+        cs.onCwdChanged = (abs) => this.onClientCwdChanged?.(abs);
+        this.onClientCwdChanged?.(cs.cwd);
+        return cs;
+    }
+    /** 插件 AI 工具集合变化（注册/注销）时由 index.ts 触发：推送到所有客户端的全部会话。 */
+    /** 插件斜杠命令集合变化时由 index.ts 触发：重推各客户端的命令目录。 */
+    /** 插件常驻后台任务变化时由 index.ts 触发：重推各客户端的 bg_servers。 */
+    refreshBackgroundServers() {
+        for (const cs of this.clients.values())
+            cs.refreshBgTasks();
+    }
+    /** Remove a socket from a client's broadcast set (called on socket close). */
+    detach(clientId, send) {
+        this.clients.get(clientId)?.detachSink(send);
+    }
+    get(clientId) {
+        return this.clients.get(clientId);
+    }
+    async disposeAll() {
+        if (this.evictTimer)
+            clearInterval(this.evictTimer);
+        this.evictTimer = null;
+        // Record still-streaming conversations BEFORE tearing anything down, so
+        // the next attach can tell the user what was lost (SIGTERM / update).
+        for (const [clientId, cs] of [...this.clients]) {
+            try {
+                const running = cs.streamingSummaries();
+                if (running.length > 0) {
+                    this.stateStore.saveInterrupted(clientId, running.map((r) => ({ ...r, at: Date.now() })));
+                }
+            }
+            catch {
+                // best effort — never block shutdown on bookkeeping
+            }
+        }
+        const all = [...this.clients.values()];
+        this.clients.clear();
+        await Promise.all(all.map((cs) => cs.dispose()));
+    }
+}