pi-web-ui 0.97.0 → 0.98.0

package/dist/server/agent-service.js

@@ -19,10 +19,11 @@ import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import * as fsPromises from "node:fs/promises";
-import { appendFileSync, existsSync, readFileSync, renameSync, rmSync, statSync, mkdirSync, watch, writeFileSync, } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, rmSync, statSync, mkdirSync, watch, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { writeAtomicSync } from "./atomic-file.js";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, createEditToolDefinition, createLocalBashOperations, createWriteToolDefinition, getAgentDir, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { BgServerTracker } from "./bg-servers.js";
@@ -54,7 +55,7 @@ import { PlanManager } from "./plan-manager.js";
 import { buildPlanModePrompt, planModeDenial, planModeNoticeText, PLAN_MODE_BLOCKED_TOOL_NAMES } from "./plan-mode.js";
 import { DELEGATION_SYSTEM_PROMPT, delegationDenial, delegateNoticeText } from "./delegate-mode.js";
 import { goalReviewDenial, shouldDeferPromptForReview } from "./goal-review-gate.js";
-import { readPlanModeFromSession } from "./permission-preset.js";
+import { readPlanModeFromSession, readPlanFromSession } from "./permission-preset.js";
 import { readDelegateModeFromSession } from "./permission-preset.js";
 import { applyHeadTail, makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, } from "./terminals.js";
 import { applyAgentToolsGating, ASK_USER_QUESTION_TOOL_NAME, BROWSER_PAGE_TOOL_NAME, effectiveDisabledAgentTools, isAgentToolEnabled, isTerminalGuidanceOn, localizedName, MARKERS_LIST_TOOL_NAME, PI_AGENT_PRESETS, PI_PERMISSION_OPTIONS, PLAN_UPDATE_TOOL_NAME, PRESENT_FILES_TOOL_NAME, presetAllowsPluginTools, presetHasQuestionnaire, presetShowsSkillCatalog, } from "./tool-manager.js";
@@ -66,7 +67,7 @@ import { makeEditSoftTool } from "./edit-soft-tool.js";
 // 覆盖 SDK 内置 read：路径是目录时列出目录条目（行为开关 readDirEnabled，默认开）。
 // 覆盖定义与「与扩展同名工具共存」的注入辅助分在两个文件（后者的依据见 tool-overrides.ts）。
 import { makeReadDirTool, withReadDirSupport } from "./read-tool.js";
-import { installToolOverrides, } from "./tool-overrides.js";
+import { installToolOverrides, syncSubagentOverride, } from "./tool-overrides.js";
 // 展示文件给用户（present_files）：图片/视频内联、文本开预览弹窗、本地打开按钮。
 import { makePresentFilesTool } from "./present-files-tool.js";
 // 主动压缩上下文工具（compact_context）：AI 主动根据当前问题精简上下文并自主控制范围。
@@ -88,10 +89,11 @@ import { makePatchTool } from "./patch-tool.js";
 import { makeLspTool } from "./lsp-tool.js";
 import { sameSessionFile } from "./scheduler-tasks.js";
 import { buildAttachmentMessages, parseModelSpec } from "./attachments.js";
+import { formatQuotedPrompt, readTextQuote } from "./text-quote.js";
 import { buildVisionBridgePrompt, findVisionModels, transcribeImages } from "./vision-bridge.js";
 import { isNotRepoError, scmCommitContext } from "./scm.js";
 import { buildCommitMsgInput, buildCommitMsgPrompt, sanitizeCommitMessage } from "./scm-commitmsg.js";
-import { BUILTIN_SOUL, DEFAULT_PROMPT_TEMPLATE, buildToolsSchemaText, estimatePromptTokens, renderPromptTemplate, resolveSectionTexts, } from "./prompt-composer.js";
+import { BUILTIN_SOUL, DEFAULT_PROMPT_TEMPLATE, buildToolsSchemaText, estimatePromptTokens, renderPromptTemplate, resolveSectionTexts, splitExtensionWrap, } from "./prompt-composer.js";
 import { launchOrigin, toServiceInfo } from "./launch-origin.js";
 import { findEntryByUiId, serializeMessage, serializeStreamingMessage, stripTransientRetryErrors, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager } from "./terminals.js";
@@ -159,6 +161,25 @@ export class QuiesceRejectedError extends Error {
 /** 自家内联扩展名（组合模板渲染，见 prompt-composer.ts）。SDK 以其
  *  "<inline:<name>>" 作为 path；扩展白名单/禁用过滤必须放行它。 */
 const INLINE_PERSONA_EXT = "<inline:pi-webui-persona>";
+/** 本次 run 的 SDK 原始提示词 + 早前扩展的首尾增补（见 splitExtensionWrap）。
+ *  导出仅为单测（tests/unit/persona-prompt-chain.test.ts）可达。
+ *  systemPromptOptions 就是 runner 里那个共享可变对象，forceSystemPrompt 有值即
+ *  说明前面有扩展替换过提示词；临时清掉再读 event.systemPrompt 就拿到原始基线
+ *  （公开字段，不碰 SDK 内部）。没人动过时零开销，直接返回当前文本。 */
+export function splitAgentStartPrompt(event) {
+    const current = event.systemPrompt;
+    const opts = event.systemPromptOptions;
+    const forced = opts?.forceSystemPrompt;
+    if (!opts || typeof forced !== "string")
+        return { pre: "", core: current, post: "" };
+    try {
+        opts.forceSystemPrompt = undefined;
+        return splitExtensionWrap(event.systemPrompt, current);
+    }
+    finally {
+        opts.forceSystemPrompt = forced;
+    }
+}
 /** Pi 包文档路径（composer 的 {{pi_docs}} 自动内容用）。随安装位置解析一次。 */
 const PI_DOC_PATHS = (() => {
     try {
@@ -738,7 +759,7 @@ function wrapEditSoftToolWithPermission(tool, cwd, getPermission, getRoots, getL
 /**
  * 结构化任务执行计划更新工具（plan_update）— Plan Mode / Step State Machine。
  */
-export function makePlanUpdateTool(planManager, getActiveConvId, emit, flushSnapshot) {
+export function makePlanUpdateTool(planManager, getActiveConvTarget, emit, flushSnapshot, onPersist) {
     return {
         name: PLAN_UPDATE_TOOL_NAME,
         label: "plan_update",
@@ -765,9 +786,21 @@ export function makePlanUpdateTool(planManager, getActiveConvId, emit, flushSnap
             activeStepId: Type.Optional(Type.String({ description: "ID of the step currently being executed" })),
         }),
         execute: async (toolCallId, params) => {
-            const convId = getActiveConvId();
+            const target = getActiveConvTarget();
+            const convId = typeof target === "string" ? target : target.id;
+            const sessionId = typeof target === "string" ? undefined : target.sessionId;
             const p = params;
-            const plan = planManager.setPlan(convId, p.steps, p.activeStepId);
+            const plan = planManager.setPlan(convId, p.steps, p.activeStepId, sessionId);
+            if (typeof target !== "string" && target.sessionManager) {
+                try {
+                    const sm = target.sessionManager;
+                    sm?.appendCustomEntry?.("plan/update", { plan });
+                }
+                catch {
+                    // 转录追加失败不影响主流程
+                }
+            }
+            onPersist?.(convId, plan);
             emit({
                 type: "plan_updated",
                 conversationId: convId,
@@ -1185,6 +1218,14 @@ function pluginToolToDefinition(tool) {
  * unlikely to matter).
  */
 function contentFingerprint(m) {
+    const summary = m.summary;
+    if (typeof summary === "string" && summary.length > 0) {
+        let h = 5381;
+        for (let i = 0; i < summary.length && i < 512; i++) {
+            h = ((h << 5) + h + summary.charCodeAt(i)) >>> 0;
+        }
+        return `sum:${h.toString(36)}:${summary.length}`;
+    }
     const content = m.content;
     if (!Array.isArray(content) || content.length === 0)
         return "empty";
@@ -1259,31 +1300,10 @@ function previewToolResult(result) {
     }
 }
 /**
- * 转录整文件重写的原子落盘：先写同目录临时文件再 rename。转录是 append-only
- * 的唯一事实源，compaction 收尾/清理的整文件重写若中途被打断（进程被杀/断电），
- * 原地 writeFileSync 会留下截断的 JSONL；同目录 rename 是原子的，最坏情况是
- * 旧文件原样保留，绝不会出现半份转录。Windows 下目标被外部占用（阅读器/杀软
- * 锁）时 rename 可能 EPERM —— 退回原地写保住功能（旧行为），不因小概率锁失败丢更新。
+ * 转录整文件重写的原子落盘：先写同目录临时文件再 rename。
  */
 function atomicWriteFileSync(file, data) {
-    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    try {
-        writeFileSync(tmp, data);
-        try {
-            renameSync(tmp, file);
-        }
-        catch {
-            writeFileSync(file, data);
-        }
-    }
-    finally {
-        try {
-            rmSync(tmp, { force: true });
-        }
-        catch {
-            // 临时文件清不掉只能留给下次（同目录 .tmp，不影响转录本身）
-        }
-    }
+    writeAtomicSync(file, data);
 }
 /** Cap on simultaneously open NON-subagent conversations of ONE project (each keeps a full
  *  runtime alive; conversations of other projects keep their own lists).
@@ -1338,18 +1358,17 @@ function conversationTitle(session) {
     }
     return DEFAULT_CONV_TITLE;
 }
-/** 全局搜索的会话匹配：大小写不敏感，命中任一项即算 ——
- *  显示名、当前项目内的文件名片段、首条消息，以及完整转录文本
- *  （SDK 的 allMessagesText 包含每一段 user 与 assistant 消息，AI 输出也在内）。 */
-function sessionMatchesSearch(q, s) {
+/** 全局搜索的会话元信息匹配：大小写不敏感，命中任一项即算 ——
+ *  显示名、当前项目内的文件名片段、首条消息。
+ *  转录全文匹配不在这里：全文单条可达 MB 级，不再随列表缓存常驻（issue #440），
+ *  由 filterSessionsForSearch 按需加载后判定（口径不变：user 与 assistant 消息文本）。 */
+function sessionMatchesMetadata(q, s) {
     if (s.name && s.name.toLowerCase().includes(q))
         return true;
     if (basename(s.path).toLowerCase().includes(q))
         return true;
     if (s.firstMessage.toLowerCase().includes(q))
         return true;
-    if (s.allMessagesText.toLowerCase().includes(q))
-        return true;
     return false;
 }
 /** 抽取一条 AgentMessage 的可搜索文本（user/assistant 的 text 块；
@@ -1373,6 +1392,12 @@ function messageSearchText(m) {
 /** 转录全文扫描/整读的大小上限（16MB，与 readHistorySession 一致）：
  *  超限文件同步 readFileSync 会卡事件循环数百毫秒起，搜索不值得。 */
 const MAX_TRANSCRIPT_SCAN_BYTES = 16 * 1024 * 1024;
+/** 转录全文进入内存/缓存的字符上限（256K 字符）：全文只服务搜索的命中判定
+ *  （issue #440 拆分后按需加载），封顶保证单条 worst case 内存可控（缓存 256 条
+ *  × 256K 字符 ≈ 64MB 上界，且只在搜索活动期间存在）。
+ *  影响面：超长转录在截断点之后的内容不参与「是否命中」判定；命中后的消息级
+ *  定位（collectSessionAnchors）仍扫全文件，不受此上限影响。 */
+const MAX_SEARCH_TEXT_CHARS = 256 * 1024;
 /** 扫描一个会话转录文件，收集文本命中查询的消息锚点（role + timestamp，
  *  按转录顺序，最多 cap 个）。仅 user/assistant 消息参与，与搜索范围一致。
  *  超过大小上限的转录直接跳过（stat 先行，不整读）—— 全局搜索逐会话同步
@@ -1486,8 +1511,13 @@ async function discoverRecentProjectsFromDisk(sessionRoots, limit = 30) {
         if (projects.size >= limit)
             break;
         try {
-            if (!existsSync(root))
+            // 异步探测（issue #441）：会话根可能在已断连的网络盘上，同步 existsSync 会冻结事件循环。
+            try {
+                await fsPromises.access(root);
+            }
+            catch {
                 continue;
+            }
             const entries = await fsPromises.readdir(root, { withFileTypes: true });
             // 1. 扁平布局（PI_CODING_AGENT_SESSION_DIR）：根目录下直接是 .jsonl
             const flatFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl"));
@@ -1511,8 +1541,9 @@ async function discoverRecentProjectsFromDisk(sessionRoots, limit = 30) {
                         const key = normalizePathKey(cwd);
                         if (!projects.has(key)) {
                             try {
-                                if (existsSync(cwd))
-                                    projects.set(key, { path: cwd, lastUsed: s.mtime });
+                                // 异步探测（issue #441）：cwd 可能在已断连的网络盘上。
+                                await fsPromises.access(cwd);
+                                projects.set(key, { path: cwd, lastUsed: s.mtime });
                             }
                             catch { }
                         }
@@ -1580,9 +1611,9 @@ async function discoverRecentProjectsFromDisk(sessionRoots, limit = 30) {
                         const key = normalizePathKey(r.path);
                         if (!projects.has(key)) {
                             try {
-                                if (existsSync(r.path)) {
-                                    projects.set(key, r);
-                                }
+                                // 异步探测（issue #441）：cwd 可能在已断连的网络盘上。
+                                await fsPromises.access(r.path);
+                                projects.set(key, r);
                             }
                             catch { }
                         }
@@ -1597,10 +1628,14 @@ async function discoverRecentProjectsFromDisk(sessionRoots, limit = 30) {
     return [...projects.values()].sort((a, b) => b.lastUsed - a.lastUsed);
 }
 /**
- * 快速解析单个会话文件（提取 id/cwd/name/parentSessionPath/firstMessage/messageCount/modified/allMessagesText）。
- * 仅用于会话列表发现与搜索，避免调用 SDK 重型的全量树解析。
+ * 快速解析单个会话文件（提取 id/cwd/name/parentSessionPath/firstMessage/messageCount/modified，
+ * 以及可选的转录全文 allMessagesText）。仅用于会话列表发现与搜索，避免调用 SDK 重型的全量树解析。
+ *
+ * withAllMessagesText=false（默认，列表路径）时不收集转录全文，allMessagesText 返回空串 ——
+ * 全文单条可达 MB 级，绝不随列表进任何缓存（issue #440）；true（搜索路径）时收集全文并在
+ * MAX_SEARCH_TEXT_CHARS 处截断。
  */
-async function parseSessionInfoFast(filePath, fileMtime) {
+async function parseSessionInfoFast(filePath, fileMtime, withAllMessagesText = false) {
     try {
         const content = await fsPromises.readFile(filePath, "utf8");
         const lines = content.split("\n");
@@ -1612,7 +1647,7 @@ async function parseSessionInfoFast(filePath, fileMtime) {
         let messageCount = 0;
         let lastActivityTime = 0;
         let headerTime = 0;
-        const allMessages = [];
+        const allMessages = withAllMessagesText ? [] : null;
         for (const line of lines) {
             if (!line.trim())
                 continue;
@@ -1658,7 +1693,7 @@ async function parseSessionInfoFast(filePath, fileMtime) {
                     if (text) {
                         if (!firstMessage && msg.role === "user")
                             firstMessage = text;
-                        allMessages.push(text);
+                        allMessages?.push(text);
                     }
                 }
             }
@@ -1666,6 +1701,11 @@ async function parseSessionInfoFast(filePath, fileMtime) {
         if (!id)
             return null;
         const modified = lastActivityTime > 0 ? lastActivityTime : headerTime > 0 ? headerTime : fileMtime;
+        let allMessagesText = "";
+        if (allMessages) {
+            const joined = allMessages.join(" ");
+            allMessagesText = joined.length > MAX_SEARCH_TEXT_CHARS ? joined.slice(0, MAX_SEARCH_TEXT_CHARS) : joined;
+        }
         return {
             path: filePath,
             id,
@@ -1676,7 +1716,7 @@ async function parseSessionInfoFast(filePath, fileMtime) {
             modified: new Date(modified),
             messageCount,
             firstMessage: firstMessage || "(no messages)",
-            allMessagesText: allMessages.join(" "),
+            allMessagesText,
         };
     }
     catch {
@@ -1730,11 +1770,8 @@ export function sameCwd(a, b) {
     const y = String(b ?? "").trim();
     if (!x || !y)
         return false;
-    const norm = (s) => s.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
-    if (norm(x) === norm(y))
-        return true;
     try {
-        return norm(resolve(x)) === norm(resolve(y));
+        return normalizePathKey(x) === normalizePathKey(y);
     }
     catch {
         return false;
@@ -2508,6 +2545,9 @@ export class ClientSession {
         const handoffMessage = `[Peer Hand-off from ${fromType} subagent (${fromRunId.slice(0, 8)})]:\n\n${payload}`;
         const record = { fromRunId, toRunId, timestamp: Date.now() };
         this.subagentHandoffs.push(record);
+        if (this.subagentHandoffs.length > 50) {
+            this.subagentHandoffs = this.subagentHandoffs.slice(-50);
+        }
         if (!fromConv?.peerHandoffTo) {
             if (fromConv)
                 fromConv.peerHandoffTo = [];
@@ -2999,7 +3039,7 @@ export class ClientSession {
      *  conversationId 记录谁问的：看门狗豁免、快照恢复都靠它。 */
     pendingQuestions = new Map();
     /** 任务计划管理器（Plan Mode / Step State Machine）。 */
-    planManager = new PlanManager();
+    planManager;
     approvalSeq = 0;
     /** 待审批高危工具调用（Human-in-the-Loop: Edit & Run）。 */
     pendingApprovals = new Map();
@@ -3026,6 +3066,7 @@ export class ClientSession {
         this.subagentTemplates = new SubagentTemplatesStore(join(stateStore.dataDir, "subagent-templates.json"));
         this.approvalRules = new ApprovalRulesStore(join(stateStore.dataDir, "approval-rules.json"));
         this.drafts = new ComposerDraftsStore(join(stateStore.dataDir, "composer-drafts.json"));
+        this.planManager = new PlanManager(join(stateStore.dataDir, "plans.json"));
         this.markerSvc = new MarkerService({
             clientId,
             stateStore,
@@ -3314,6 +3355,57 @@ export class ClientSession {
         }
         await cs.restoreProjectProviderKeysForCwd(cwd);
         await cs.restoreProjectModelForCwd(cwd);
+        if (conv.session.sessionFile && cs.stateStore?.isSessionPinned(cwd, conv.session.sessionFile)) {
+            conv.pinned = true;
+            conv.listed = true;
+        }
+        // 恢复本项目其他已被钉住的会话（重启后常驻运行列表，issue #433）
+        const pinnedPaths = cs.stateStore?.getPinnedSessions(cwd) ?? [];
+        for (const p of pinnedPaths) {
+            if (cs.convs.size >= MAX_OPEN_CONVERSATIONS)
+                break;
+            const normP = normalizePathKey(p);
+            const alreadyOpen = [...cs.convs.values()].some((c) => c.session.sessionFile && normalizePathKey(c.session.sessionFile) === normP);
+            if (alreadyOpen)
+                continue;
+            try {
+                const targetPath = resolve(p);
+                if (!existsSync(targetPath))
+                    continue;
+                cs.repairTranscriptFileBeforeOpen(targetPath);
+                const sm = SessionManager.open(targetPath);
+                const convId = cs.nextConversationId();
+                const terms = cs.makeTerminalManager(convId, cwd);
+                const rt = await createAgentSessionRuntime(cs.makeRuntimeFactory(terms, undefined, convId), {
+                    cwd,
+                    agentDir,
+                    sessionManager: sm,
+                });
+                const pinnedConv = cs.makeConversation(rt, convId, terms);
+                pinnedConv.pinned = true;
+                pinnedConv.listed = true;
+                pinnedConv.promptedSinceActive = true;
+                cs.convs.set(pinnedConv.id, pinnedConv);
+                pinnedConv.unsubscribe = pinnedConv.session.subscribe((event) => cs.onEvent(pinnedConv, event));
+                try {
+                    await pinnedConv.session.bindExtensions({
+                        mode: "rpc",
+                        uiContext: WebUIContext.headless(),
+                        onError: cs.makeExtensionErrorReporter({
+                            text: `会话 ${convId}：`,
+                            textEn: `Conversation ${convId}: `,
+                        }),
+                    });
+                }
+                catch {
+                    // 忽略扩展绑定失败
+                }
+                cs.applyToolGating(pinnedConv.session, pinnedConv.agentPreset);
+            }
+            catch {
+                // best effort
+            }
+        }
         return cs;
     }
     /**
@@ -3443,6 +3535,11 @@ export class ClientSession {
                             hidden: true,
                             factory: (pi) => {
                                 pi.on("before_agent_start", (event) => {
+                                    // 我们是链上最后一个 handler：先把早前扩展的首尾增补摘出来（pre/post），
+                                    // 只在 SDK 原始提示词 core 上做事，最后原样套回去——否则返回 systemPrompt
+                                    // 会整体替换，把别的扩展注入的内容（如 <invoked_skill>）一起丢掉。
+                                    const { pre, core, post } = splitAgentStartPrompt(event);
+                                    const rewrap = (next) => pre + next + post;
                                     // 子代理模板 replace（无 SYSTEM.md 时）：默认分支拼好的提示词里
                                     // 把灵魂段换成模板提示词，自动段保留；SYSTEM.md 情形已在
                                     // systemPromptOverride 整体替换，此处边界不存在会自然跳过。
@@ -3450,15 +3547,11 @@ export class ClientSession {
                                         const tplPrompt = pickTemplatePrompt(apply, this.getLang()).trim();
                                         if (apply.promptMode !== "replace" || !tplPrompt)
                                             return undefined;
-                                        const boundary = event.systemPrompt.indexOf("\n\nAvailable tools:");
+                                        const boundary = core.indexOf("\n\nAvailable tools:");
                                         // 边界串是 SDK 提示词的内部格式：版本一变就可能对不上。
                                         // 对不上时不再静默回退默认 persona（模板等于没生效），而是把模板
                                         // 提示词前置拼接——角色约束仍在，只是灵魂段没被精确替换。
-                                        if (boundary === -1) {
-                                            const fallback = `${tplPrompt}\n\n${event.systemPrompt}`;
-                                            return fallback === event.systemPrompt ? undefined : { systemPrompt: fallback };
-                                        }
-                                        const swapped = tplPrompt + event.systemPrompt.slice(boundary);
+                                        const swapped = rewrap(boundary === -1 ? `${tplPrompt}\n\n${core}` : tplPrompt + core.slice(boundary));
                                         return swapped === event.systemPrompt ? undefined : { systemPrompt: swapped };
                                     }
                                     // 主会话：按当前会话归属预设与真正活跃的工具列表组装系统提示词
@@ -3496,7 +3589,8 @@ export class ClientSession {
                                         })),
                                         preset: currentPreset,
                                     });
-                                    return rendered ? { systemPrompt: rendered } : undefined;
+                                    // 不自定义时 rendered 为 undefined：不返回提示词，前面扩展的改动原样保留。
+                                    return rendered ? { systemPrompt: rewrap(rendered) } : undefined;
                                 });
                             },
                         },
@@ -3638,7 +3732,15 @@ export class ClientSession {
                     // 内置标记只读查询工具（todo/svc 状态查询，写操作走内联标记）。
                     makeMarkersListTool(() => this.activeId, this.markerSvc),
                     // 结构化任务计划更新（Plan Mode / Step State Machine）。
-                    makePlanUpdateTool(this.planManager, () => ownerId ?? this.activeId, (msg) => this.emit(msg), () => this.flushSnapshot()),
+                    makePlanUpdateTool(this.planManager, () => {
+                        const id = ownerId ?? this.activeId;
+                        const c = this.convs.get(id);
+                        return {
+                            id,
+                            sessionId: c?.session?.sessionId,
+                            sessionManager: c?.session?.sessionManager,
+                        };
+                    }, (msg) => this.emit(msg), () => this.flushSnapshot()),
                     // 标准引擎的 ask_user_question：模型调用 → 浏览器富渲染问卷（复用 DSH
                     // 的 question_pending/question_answer 协议，前端 DshQuestionDialog）。
                     // DSH 引擎不经此（它走 goal-rpc 的 userQuestions provider）。
@@ -3694,9 +3796,9 @@ export class ClientSession {
                         lang: () => this.getLang(),
                     }),
                     // 高可靠行补丁工具（patch，基于内容哈希与语法块级替换）。
-                    makePatchTool({ cwd: effectiveCwd, ownerId }),
+                    makePatchTool({ cwd: effectiveCwd, ownerId, lang: () => this.getLang() }),
                     // 原生语言服务器工具（lsp，定义跳转/引用/悬停/诊断）。
-                    makeLspTool({ cwd: effectiveCwd, ownerId }),
+                    makeLspTool({ cwd: effectiveCwd, ownerId, lang: () => this.getLang() }),
                 ].map((t) => 
                 // 目标审查闸门在最外层（理由最贴合此刻）；插件工具也在这个数组里，
                 // 创建时注册的同样被闸门覆盖（后续动态补入的走 syncPluginTools，与
@@ -3730,7 +3832,7 @@ export class ClientSession {
     }
     /** Wrap a fresh runtime as a new conversation record. */
     makeConversation(runtime, id, terminals) {
-        return {
+        const conv = {
             id,
             title: conversationTitle(runtime.session),
             isSubagent: false,
@@ -3773,6 +3875,42 @@ export class ClientSession {
             toolWatchdogs: new Map(),
             workspaceSnapshots: [],
         };
+        this.restorePlan(conv);
+        return conv;
+    }
+    /** 会话计划回放恢复：持久化文件（sessionId）→ 转录 customType → 历史消息三重兜底。 */
+    restorePlan(conv) {
+        const sessionId = conv.session.sessionId;
+        if (sessionId) {
+            const existing = this.planManager.bindSession(conv.id, sessionId);
+            if (existing)
+                return;
+        }
+        // 2. 从 sessionManager entries 回放
+        const smPlan = readPlanFromSession(conv.session.sessionManager);
+        if (smPlan && Array.isArray(smPlan.steps) && smPlan.steps.length > 0) {
+            this.planManager.setPlan(conv.id, smPlan.steps, smPlan.activeStepId, sessionId);
+            return;
+        }
+        // 3. 从已有历史消息中回放最后一次成功的 plan_update 工具调用
+        const msgs = conv.session.agent?.state?.messages;
+        if (Array.isArray(msgs)) {
+            for (let i = msgs.length - 1; i >= 0; i--) {
+                const msg = msgs[i];
+                if (msg?.role === "assistant" && Array.isArray(msg.content)) {
+                    for (const part of msg.content) {
+                        const p = part;
+                        if (p?.type === "tool_use" &&
+                            p.name === "plan_update" &&
+                            Array.isArray(p.input?.steps) &&
+                            p.input.steps.length > 0) {
+                            this.planManager.setPlan(conv.id, p.input.steps, p.input.activeStepId ?? null, sessionId);
+                            return;
+                        }
+                    }
+                }
+            }
+        }
     }
     /** Summaries of conversations currently streaming — captured at shutdown
      *  so the next attach can reopen them and continue their runs. */
@@ -3980,9 +4118,13 @@ export class ClientSession {
             });
         };
     }
-    /** (Re)attach event plumbing to the ACTIVE conversation's session. */
-    async bindSession() {
-        const conv = this.conv;
+    /** (Re)attach event plumbing to a conversation's session. 默认绑当前活跃对话；
+     *  forceReset 重建非活跃对话（子代理/角色对话）时必须显式传入该对话，
+     *  否则重建后的会话永远拿不回事件订阅（issue #484）。
+     *  **public**：过户（take_over_conversation）后由 ClientSessionPool 对 **其它页面** 的
+     *  ClientSession 调用（切会话只重建 runtime，订阅得重新挂上，见 idle-takeover-test）。 */
+    async bindSession(target) {
+        const conv = target ?? this.conv;
         conv.unsubscribe?.();
         conv.session = conv.runtime.session;
         await conv.session.bindExtensions({
@@ -4219,7 +4361,7 @@ export class ClientSession {
         }
     }
     /** 插件扩展点 v2（供 conversationSearcher）：运行中对话标题 + 历史会话全文匹配，返回前 N 个 {id,title}。
-     *  复用 searchSessions 的 sessionMatchesSearch 判定（含转录全文），只读不 emit。 */
+     *  复用 searchSessions 的匹配口径（元信息 + 按需加载的转录全文），只读不 emit。 */
     async searchForPlugins(query, limit = 20) {
         const q = query.trim().toLowerCase();
         if (!q)
@@ -4233,9 +4375,8 @@ export class ClientSession {
         }
         try {
             const infos = await this.loadSessionInfos();
-            for (const s of infos) {
-                if (!sessionMatchesSearch(q, s))
-                    continue;
+            const matched = await ClientSession.filterSessionsForSearch(q, infos);
+            for (const s of matched) {
                 out.push({
                     id: s.path,
                     title: (s.name?.trim() || s.firstMessage.trim() || basename(s.path)).slice(0, 60),
@@ -5019,7 +5160,41 @@ export class ClientSession {
         // 一次扫描同时收齐「当前转写里的全部缓存键」（live 集合，供
         // pruneMessageCache 精确回收死条目）与各自的序列化结果。
         const live = new Set();
-        let rawMessages = conv.session.agent.state.messages
+        let agentMessages = conv.session.agent.state.messages;
+        // issue #448: 多次压缩后 SDK state.messages 只保留最后一次压缩卡片。
+        // 从当前分支祖先链中提取前序未展示的历史 compaction 并正序置前，
+        // 使前端能逐段回溯展开历史折叠内容。
+        if (conv.session.sessionManager?.getBranch) {
+            try {
+                const branch = conv.session.sessionManager.getBranch();
+                const compEntries = branch.filter((e) => e.type === "compaction");
+                if (compEntries.length > 1) {
+                    const existingCompKeys = new Set(agentMessages
+                        .filter((m) => m.role === "compactionSummary")
+                        .map((m) => `${m.timestamp}:${m.summary ?? ""}`));
+                    const missingComps = [];
+                    for (const ce of compEntries) {
+                        const ts = ce.timestamp ? new Date(ce.timestamp).getTime() : 0;
+                        const key = `${ts}:${ce.summary ?? ""}`;
+                        if (!existingCompKeys.has(key)) {
+                            missingComps.push({
+                                role: "compactionSummary",
+                                summary: ce.summary ?? "",
+                                tokensBefore: ce.tokensBefore,
+                                timestamp: ts,
+                            });
+                        }
+                    }
+                    if (missingComps.length > 0) {
+                        agentMessages = [...missingComps, ...agentMessages];
+                    }
+                }
+            }
+            catch {
+                // 获取分支异常不影响当前渲染
+            }
+        }
+        let rawMessages = agentMessages
             .map((m) => {
             const k = this.uiMessageKey(conv, m);
             live.add(k.cacheKey);
@@ -5621,7 +5796,36 @@ export class ClientSession {
     }
     updatePlan(steps, activeStepId, conversationId) {
         const convId = conversationId ?? this.activeId;
-        const plan = this.planManager.setPlan(convId, steps, activeStepId);
+        const conv = this.convs.get(convId);
+        const sessionId = conv?.session?.sessionId;
+        const plan = this.planManager.setPlan(convId, steps, activeStepId, sessionId);
+        try {
+            const sm = conv?.session?.sessionManager;
+            sm?.appendCustomEntry?.("plan/update", { plan });
+        }
+        catch {
+            // ignore
+        }
+        this.emit({
+            type: "plan_updated",
+            conversationId: convId,
+            plan,
+        });
+        this.flushSnapshot();
+    }
+    updatePlanStep(stepId, patch, conversationId) {
+        const convId = conversationId ?? this.activeId;
+        const plan = this.planManager.updateStep(convId, stepId, patch);
+        this.emit({
+            type: "plan_updated",
+            conversationId: convId,
+            plan,
+        });
+        this.flushSnapshot();
+    }
+    deletePlanStep(stepId, conversationId) {
+        const convId = conversationId ?? this.activeId;
+        const plan = this.planManager.deleteStep(convId, stepId);
         this.emit({
             type: "plan_updated",
             conversationId: convId,
@@ -5629,6 +5833,38 @@ export class ClientSession {
         });
         this.flushSnapshot();
     }
+    addPlanStep(step, afterStepId, conversationId) {
+        const convId = conversationId ?? this.activeId;
+        const plan = this.planManager.addStep(convId, step, afterStepId);
+        this.emit({
+            type: "plan_updated",
+            conversationId: convId,
+            plan,
+        });
+        this.flushSnapshot();
+    }
+    /** 「✨ 净室执行（Clean-session Handoff）」：
+     *  关闭源会话的计划闸门，新建隔离会话，在新会话中原子设置计划步骤、可选迁移目标，并触发实施轮 prompt。 */
+    async planCleanHandoff(steps, promptText) {
+        const sourceConv = this.conv;
+        if (sourceConv?.planMode) {
+            await this.setPlanMode(false, sourceConv.id);
+        }
+        const sourceGoal = sourceConv?.goal?.goal;
+        await this.newChat();
+        const targetConv = this.conv;
+        this.planManager.setPlan(targetConv.id, steps);
+        if (sourceGoal) {
+            try {
+                await this.goalSvc.setGoal(sourceGoal, { targetConvId: targetConv.id, autoStart: false });
+            }
+            catch {
+                // 目标迁移失败不阻塞实施
+            }
+        }
+        this.flushSnapshot();
+        await this.prompt(promptText);
+    }
     /** 关闭所有挂起提问（dispose 时清理）：以「取消」解析，避免模型挂死。 */
     cancelPendingQuestions() {
         for (const [, p] of this.pendingQuestions) {
@@ -5636,6 +5872,35 @@ export class ClientSession {
         }
         this.pendingQuestions.clear();
     }
+    /** #487：结算指定会话的挂起提问/审批（按 conversationId 精确匹配）。
+     *  abort/移除/重建会话后残留的条目会让 isWaitingOnUser 恒真——stall 失联
+     *  检测被永久豁免，且问卷/审批弹窗跨轮残留。dispose 口径范本：提问以
+     *  「取消」解析、审批以「拒绝」解析并广播 tool_approval_resolved。 */
+    settlePendingsForConv(convId) {
+        for (const [id, q] of this.pendingQuestions) {
+            if (q.conversationId !== convId)
+                continue;
+            this.pendingQuestions.delete(id);
+            try {
+                q.resolve(null);
+            }
+            catch {
+                // 单个结算异常不影响其余清理
+            }
+        }
+        for (const [id, a] of this.pendingApprovals) {
+            if (a.conversationId !== convId)
+                continue;
+            this.pendingApprovals.delete(id);
+            try {
+                a.resolve({ decision: "deny", reason: "运行已停止" });
+            }
+            catch {
+                // 单个结算异常不影响其余清理
+            }
+            this.emit({ type: "tool_approval_resolved", id });
+        }
+    }
     /** 关闭所有挂起审批（dispose 时清理）：以「拒绝」解析，避免等答复的
      *  Promise 与对应 runtime 泄漏（会话没了，审批弹窗永远不会有人点）。 */
     cancelPendingApprovals() {
@@ -5993,6 +6258,7 @@ export class ClientSession {
      * 主动检查已安装界面插件（<dataDir>/plugins）的更新状态并向客户端推送。
      */
     async checkPluginUpdates(manual = false) {
+        this.updatesAllCache = null;
         const lang = () => this.getLang();
         try {
             const updates = await checkPluginUpdates(this.stateStore.dataDir, undefined, lang);
@@ -6120,11 +6386,12 @@ export class ClientSession {
                 }));
                 this.lastPluginUpdates = list;
                 this.emit({ type: "plugin_updates", updates: list });
+                const fmtVer = (v) => (v ? (/^[vV]/.test(v) ? v : `v${v}`) : null);
                 pluginItems = pluginUpdates.map((p) => ({
                     name: p.name ? `${p.name} (${p.id})` : p.id,
                     kind: "plugin",
-                    current: p.version ? `v${p.version}` : (p.localSha ?? "unknown"),
-                    latest: p.latestVersion ? `v${p.latestVersion}` : (p.remoteSha ?? null),
+                    current: fmtVer(p.version) ?? p.localSha ?? "unknown",
+                    latest: fmtVer(p.latestVersion) ?? p.remoteSha ?? null,
                     latestPublishedAt: null,
                     upToDate: !p.updatable,
                     error: p.error,
@@ -6287,6 +6554,8 @@ export class ClientSession {
             this.flushSnapshot();
         },
         refreshSessions: () => this.refreshSessions(),
+        setPlanMode: (enabled) => this.setPlanMode(enabled),
+        getPlanMode: () => this.conv?.planMode === true,
         afterReload: () => {
             // /reload 同样重读磁盘 settings.json——重放重试覆盖 + 软上限覆盖 + 终端门控。
             this.applyRetryOverrides();
@@ -6833,6 +7102,10 @@ export class ClientSession {
             }
         }
         applyAgentToolsGating(session, [...disabled], targetPreset);
+        const ownerId = conv?.id;
+        syncSubagentOverride(session, disabled.has("subagent"), () => ownerId
+            ? makeSubagentTools(withSubagentOwner(this.subagentHost, ownerId), undefined, ownerId)[0]
+            : makeSubagentTools(this.subagentHost)[0]);
         this.syncPluginTools(session, targetPreset);
         this.sessionStatsCache = null;
         this.cachedBaseTokens = null;
@@ -7848,6 +8121,13 @@ export class ClientSession {
             conv.promptInFlight = true;
             // Attach files as independent nextTurn context messages (asides) so the
             // user message stays clean; they render as separate attachment cards.
+            // SDK 的流式队列只消费用户消息；引用须与对应队列项一起入队和撤回。
+            const streamingQuotes = s.isStreaming
+                ? (attachments ?? [])
+                    .filter((a) => a.mode === "quote")
+                    .map((a) => readTextQuote(a.quote))
+                    .filter((q) => q !== null)
+                : [];
             const asides = await buildAttachmentMessages({
                 cwd: this.cwd,
                 clientId: this.clientId,
@@ -7856,9 +8136,17 @@ export class ClientSession {
                 session: this.session,
                 // issue #91：附件/视觉桥文案按客户端 UI 语言出中英（英文默认）。
                 getLang: () => this.getLang(),
-            }, attachments);
+            }, streamingQuotes.length ? attachments?.filter((a) => a.mode !== "quote") : attachments);
             if (promptAc.signal.aborted) {
                 conv.activePromptAc = undefined;
+                // #492：displacement（新对话顶替/会话被移出）在 prompt 前置阶段 abort 时
+                // 原本静默 return——消息凭空消失、草稿已清，用户毫无回执。
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `消息未送达：该对话已被关闭或运行已被停止`,
+                    textEn: `Message not delivered: the conversation was closed or the run was stopped`,
+                });
                 return;
             }
             for (const aside of asides) {
@@ -7883,6 +8171,13 @@ export class ClientSession {
             }
             if (promptAc.signal.aborted) {
                 conv.activePromptAc = undefined;
+                // #492：同上——影子快照阶段的 abort 也必须给回执，不能静默黑洞。
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `消息未送达：该对话已被关闭或运行已被停止`,
+                    textEn: `Message not delivered: the conversation was closed or the run was stopped`,
+                });
                 return;
             }
             conv.activePromptAc = undefined;
@@ -7907,12 +8202,12 @@ export class ClientSession {
                 // Enter-during-streaming semantic (docs/usage: Enter queues a
                 // steering message); followUp would wait for the whole run
                 // to finish, which users perceive as ordinary queueing.
-                await s.prompt(text, {
+                await s.prompt(formatQuotedPrompt(text, streamingQuotes), {
                     streamingBehavior: queue ? "followUp" : "steer",
                 });
             }
             else {
-                await s.prompt(text);
+                await s.prompt(formatQuotedPrompt(text, streamingQuotes));
             }
             // 关联快照与本次 prompt 产生的用户消息 entry
             if (snapshotRef) {
@@ -8106,7 +8401,23 @@ export class ClientSession {
             this.flushSnapshot();
             return;
         }
-        const { steering, followUp } = s.clearQueue();
+        let steering;
+        let followUp;
+        try {
+            ({ steering, followUp } = s.clearQueue());
+        }
+        catch (err) {
+            // #491：runtime 被 forceReset 置换等半死状态下 clearQueue 可能抛错——
+            // 回退到本地显示镜像移除，等 queue_update 对账；绝不把 reject 的 Promise
+            // 扔回给 dispatch（无兜底 handler 时 unhandledRejection 直接崩进程）。
+            console.error("[agent-service] clearQueue failed while removing a queued message:", err);
+            const next = removeQueuedByIndexOrText(local, text, index);
+            if (next.length !== local.length) {
+                local.splice(0, local.length, ...next);
+            }
+            this.flushSnapshot();
+            return;
+        }
         // 气泡 ✕ 对应的是「第几个气泡」（index），不是「哪段文本」：同一文本排队两次时
         // 按文本只会删掉第一条，点第二个气泡却删掉第一个。用 index 定位，位置对不上
         // （队列在点击与执行之间变化）或旧客户端没发 index 时回落到第一处文本匹配。
@@ -8244,6 +8555,9 @@ export class ClientSession {
     }
     /** Interrupt a run: abort, with a force-reset fallback on timeout. */
     async interruptRun(conv, reason) {
+        // #487：停下就结算该会话的挂起提问/审批——残留条目让 isWaitingOnUser 恒真
+        // （stall 失联检测被永久豁免），弹窗也会跨轮残留；dispose 语义已范本化。
+        this.settlePendingsForConv(conv.id);
         if (!this.conversationStreaming(conv) && conv.session.isIdle) {
             return;
         }
@@ -8317,6 +8631,11 @@ export class ClientSession {
             conv.toolStartTimes.clear();
             disposeEvalSession(conv.id);
             await conv.runtime.dispose();
+            // #485：dispose 挂起期间会话可能已被强行关闭移出（forceDismiss 走
+            // removeConversation）——此时绝不能幽灵重建，否则新 runtime 挂在已脱离
+            // this.convs 的 conv 对象上，无人持有、永不回收。
+            if (!this.convs.has(conv.id))
+                return;
             // #280：dispose 丢弃了内存里的在飞状态（未落盘的工具结果蒸发），
             // 文件尾可能留下一个悬空 toolCall——先补合成 toolResult 再重建，
             // 否则重建后的 prompt 会把非法转录链喂给 provider（零落盘黑洞）。
@@ -8348,6 +8667,17 @@ export class ClientSession {
                 sessionManager: m,
             }), async () => (ownFile && existsSync(ownFile) ? ownFile : undefined));
             const runtime = opened.runtime;
+            // #485：openManagerAndRuntime 的长 await 期间会话被移出的同一守卫——
+            // 刚建好的 runtime 无人认领，就地 dispose 防止扩展宿主子进程泄漏。
+            if (!this.convs.has(conv.id)) {
+                try {
+                    await runtime.dispose();
+                }
+                catch {
+                    // 已被移除的会话：dispose 失败无处上报，best-effort。
+                }
+                return;
+            }
             if (opened.repair) {
                 for (const n of this.transcriptRepairNotices(opened.repair))
                     this.emit(n);
@@ -8381,7 +8711,10 @@ export class ClientSession {
                 text: reason,
                 textEn: `${reason} (forced reset: run did not terminate)`,
             });
-            await this.bindSession();
+            // #484：把订阅重挂到**被重建的那个对话**上。非活跃对话（子代理/角色
+            // 对话）此前永远走 bindSession() → 只给活跃对话挂订阅，重建后该对话
+            // 的所有 SDK 事件失聪：快照冻结、看门狗不再布防、turnEndWaiters 死等。
+            await this.bindSession(conv);
             this.emitConversations();
             void this.pushSlashCommands();
         }
@@ -8784,6 +9117,9 @@ export class ClientSession {
     }
     displaceActive() {
         const conv = this.conv;
+        // 正在过户给其他会话：绝不就地释放（runtime/终端等整体搬迁给 target）。
+        if (conv.transferring)
+            return null;
         // 子代理不受切换关闭影响（见上）。
         if (conv.isSubagent) {
             conv.listed = true;
@@ -8847,6 +9183,8 @@ export class ClientSession {
         const conv = this.convs.get(id);
         if (!conv || id === this.activeId)
             return;
+        // #487：会话没了，挂起的提问/审批永远等不到人点——按 dispose 口径就地结算。
+        this.settlePendingsForConv(id);
         // 正在投递的消息（附件构建 / 影子快照阶段）必须先打断：否则 prompt() 醒来
         // 后会把用户消息写进已销毁的 runtime，静默丢失。
         if (conv.activePromptAc) {
@@ -8925,21 +9263,37 @@ export class ClientSession {
         const convs = [...this.convs.values()].filter((c) => set.has(c.id));
         if (convs.length === 0)
             return { ok: false, reason: "missing" };
-        if (set.has(this.activeId)) {
-            const remaining = [...this.convs.values()].find((c) => !set.has(c.id) && !c.isSubagent) ??
-                [...this.convs.values()].find((c) => !set.has(c.id));
-            if (remaining) {
-                await this.switchConversation(remaining.id);
-            }
-            else if (!(await this.newChat())) {
-                return { ok: false, reason: "empty" };
+        for (const conv of convs)
+            conv.transferring = true;
+        try {
+            if (set.has(this.activeId)) {
+                const remaining = [...this.convs.values()].find((c) => !set.has(c.id) && !c.isSubagent) ??
+                    [...this.convs.values()].find((c) => !set.has(c.id));
+                if (remaining) {
+                    await this.switchConversation(remaining.id);
+                }
+                else if (!(await this.newChat())) {
+                    return { ok: false, reason: "empty" };
+                }
             }
         }
+        finally {
+            for (const conv of convs)
+                delete conv.transferring;
+        }
         for (const conv of convs) {
             this.convs.delete(conv.id);
             this.clearAllToolWatchdogs(conv);
             conv.unsubscribe?.();
             conv.unsubscribe = undefined;
+            // issue #457: 唤醒角色轮等待者与目标审查等待者，避免会话搬走后原会话循环永久卡死
+            const waiters = this.turnEndWaiters.get(conv.id);
+            if (waiters) {
+                this.turnEndWaiters.delete(conv.id);
+                for (const fn of waiters)
+                    fn("gone");
+            }
+            this.goalSvc.notifyTakeover(conv);
         }
         const questions = [];
         for (const [qid, p] of this.pendingQuestions) {
@@ -9304,8 +9658,118 @@ export class ClientSession {
     static projectsCache = null;
     static PROJECTS_CACHE_TTL = 60_000;
     static projectsInFlight = null;
-    /** 会话单文件 stat 缓存（path -> { mtime, size, info }）：避免对未修改的会话文件重复读取与 JSON 解析。 */
+    /**
+     * 会话单文件元信息缓存（path -> { mtime, size, info }）：避免对未修改的会话文件
+     * 重复读取与 JSON 解析。LRU 上限（issue #440）：静态 Map 跨项目共享，原先没有任何
+     * 上限/TTL —— 删除、更名、被挤出 200 名额的文件只要曾进过缓存就永久驻留，长驻
+     * 服务 + 多项目重度使用下 RSS 单调上涨。
+     *
+     * 上限 512 的依据：单项目单轮扫描只取最新 200 个候选，512 ≈ 2.5 倍余量，足够容纳
+     * 多个最近活跃项目的热集；且拆分后（issue #440）条目只含元信息不含转录全文
+     * （单条 KB 级），总占用恒定且极小 —— 上限防的是「无界累积」，不是单条重量。
+     *
+     * LRU 淘汰语义：把 Map 当 LRU 用（Map 迭代序 = 插入序）—— 命中即 delete+set 重插
+     * 到最新端，写入超上限从最旧端淘汰。mtime/size 未变的条目命中即复用（行为与原先
+     * 一致），变化的条目由调用方重新解析后经 store 覆盖（也落到最新端）。
+     */
     static sessionFileCache = new Map();
+    static SESSION_FILE_CACHE_MAX = 512;
+    /**
+     * 转录全文缓存（path -> { text, at }）：仅供 searchSessions / searchForPlugins 的
+     * 全文命中判定按需加载（issue #440 拆分）。与列表缓存分离的原因：列表路径
+     * （pushSessions / 插件列表 / 删除后切换）只需要元信息，而全文单条可达 MB 级，
+     * 随列表常驻会让每个曾进过列表的文件都占住内存。
+     *
+     * 容量依据：256 ≥ 单项目候选上限 200，键入查询的其余按键在 TTL 窗口内全程免读盘；
+     * 单条在 parseSessionInfoFast 里按 MAX_SEARCH_TEXT_CHARS（256K 字符）封顶。
+     * TTL 只在访问时判断（无定时器），每次载入顺手清扫过期项 —— 搜索空闲后不长期
+     * 占内存。删除/更名经 invalidateSessionInfos 同步清理。
+     */
+    static sessionTextCache = new Map();
+    static SESSION_TEXT_CACHE_MAX = 256;
+    static SESSION_TEXT_CACHE_TTL = 30_000;
+    /** sessionFileCache LRU 读取：命中即重插到最新端（续期），未命中返回 undefined。 */
+    static sessionFileCacheLookup(key) {
+        const entry = ClientSession.sessionFileCache.get(key);
+        if (!entry)
+            return undefined;
+        ClientSession.sessionFileCache.delete(key);
+        ClientSession.sessionFileCache.set(key, entry);
+        return entry;
+    }
+    /** sessionFileCache LRU 写入：新/更新条目放最新端，超上限从最旧端淘汰。 */
+    static sessionFileCacheStore(key, entry) {
+        ClientSession.sessionFileCache.delete(key);
+        ClientSession.sessionFileCache.set(key, entry);
+        while (ClientSession.sessionFileCache.size > ClientSession.SESSION_FILE_CACHE_MAX) {
+            const oldest = ClientSession.sessionFileCache.keys().next();
+            if (oldest.done)
+                break;
+            ClientSession.sessionFileCache.delete(oldest.value);
+        }
+    }
+    /** sessionTextCache 读取：TTL 内命中即重插续期；过期即清并按未命中处理。 */
+    static sessionTextCacheLookup(key, now) {
+        const entry = ClientSession.sessionTextCache.get(key);
+        if (!entry)
+            return undefined;
+        ClientSession.sessionTextCache.delete(key);
+        if (now - entry.at >= ClientSession.SESSION_TEXT_CACHE_TTL)
+            return undefined;
+        ClientSession.sessionTextCache.set(key, entry);
+        return entry.text;
+    }
+    /** sessionTextCache 写入：放最新端，超上限从最旧端淘汰。 */
+    static sessionTextCacheStore(key, text, at) {
+        ClientSession.sessionTextCache.delete(key);
+        ClientSession.sessionTextCache.set(key, { text, at });
+        while (ClientSession.sessionTextCache.size > ClientSession.SESSION_TEXT_CACHE_MAX) {
+            const oldest = ClientSession.sessionTextCache.keys().next();
+            if (oldest.done)
+                break;
+            ClientSession.sessionTextCache.delete(oldest.value);
+        }
+    }
+    /** 惰性清扫 sessionTextCache 过期项：TTL 只在访问时判断，没有定时器兜底，
+     *  靠每次全文载入顺手扫一遍，保证搜索空闲后全文不会无限期滞留内存。 */
+    static sessionTextCacheSweep(now) {
+        for (const [key, entry] of ClientSession.sessionTextCache) {
+            if (now - entry.at >= ClientSession.SESSION_TEXT_CACHE_TTL)
+                ClientSession.sessionTextCache.delete(key);
+        }
+    }
+    /**
+     * 转录全文按需加载（搜索专用）：TTL 缓存命中直接回；未命中读盘提取全文
+     * （与 parseSessionInfoFast 同口径：user/assistant 消息文本，MAX_SEARCH_TEXT_CHARS
+     * 截断）。解析失败回空串且不缓存 —— 与列表路径一样下次重试。
+     */
+    static async loadSessionSearchText(filePath) {
+        const now = Date.now();
+        ClientSession.sessionTextCacheSweep(now);
+        const hit = ClientSession.sessionTextCacheLookup(filePath, now);
+        if (hit !== undefined)
+            return hit;
+        const info = await parseSessionInfoFast(filePath, 0, true);
+        const text = info?.allMessagesText ?? "";
+        if (text)
+            ClientSession.sessionTextCacheStore(filePath, text, now);
+        return text;
+    }
+    /**
+     * searchSessions / searchForPlugins 共用的全文匹配：先比元信息（零 IO，覆盖绝大多数
+     * 按标题/文件名/首条消息的查询），元信息未命中的会话再按需加载转录全文判定
+     * （小容量短 TTL 缓存，见 sessionTextCache）。保序返回命中子集。
+     * issue #440：全文不再随列表缓存常驻，改在这里按需加载。
+     */
+    static async filterSessionsForSearch(q, infos) {
+        const flags = await Promise.all(infos.map(async (s) => {
+            if (sessionMatchesMetadata(q, s))
+                return true;
+            const text = await ClientSession.loadSessionSearchText(s.path);
+            return text.toLowerCase().includes(q);
+        }));
+        return infos.filter((_, i) => flags[i]);
+    }
     /** 会话列表缓存（按 cwdKey 隔离，30s TTL）。 */
     static sessionInfosCache = new Map();
     static sessionInfosInFlight = new Map();
@@ -9344,15 +9808,15 @@ export class ClientSession {
                 }));
                 const validStats = stats.filter((s) => s !== null);
                 validStats.sort((a, b) => b.mtime - a.mtime);
-                const candidates = validStats.slice(0, 200);
-                const results = await Promise.all(candidates.map(async (file) => {
-                    const cached = ClientSession.sessionFileCache.get(file.path);
+                const results = await Promise.all(validStats.map(async (file) => {
+                    const cached = ClientSession.sessionFileCacheLookup(file.path);
                     if (cached && cached.mtime === file.mtime && cached.size === file.size) {
                         return cached.info;
                     }
+                    // 列表路径不收集转录全文（issue #440）——全文只在搜索时按需加载
                     const info = await parseSessionInfoFast(file.path, file.mtime);
                     if (info) {
-                        ClientSession.sessionFileCache.set(file.path, {
+                        ClientSession.sessionFileCacheStore(file.path, {
                             mtime: file.mtime,
                             size: file.size,
                             info,
@@ -9361,15 +9825,28 @@ export class ClientSession {
                     return info;
                 }));
                 const validInfos = results.filter((info) => info !== null);
-                validInfos.sort((a, b) => b.modified.getTime() - a.modified.getTime());
-                ClientSession.sessionInfosCache.set(cwdKey, { infos: validInfos, at: Date.now() });
-                return validInfos;
+                // issue #438：扁平布局（PI_CODING_AGENT_SESSION_DIR）下根目录顶层直接是**所有项目**
+                // 共享的 .jsonl，所属 cwd 是文件内字段；不过滤的话其他项目的会话会混进本项目
+                // 「历史会话」列表，点开即把整个工作区切走。与 SessionManager.list(cwd, ...) 的
+                // fallback 及 discoverRecentProjectsFromDisk 同口径：normalizePathKey（Windows
+                // 大小写/斜杠归一）。空 cwd 的损坏文件须排除——normalizePathKey("") 会 resolve 到
+                // process.cwd()，恰好等于本项目时会把垃圾文件误收进来。
+                const ownInfos = validInfos.filter((info) => info.cwd !== "" && normalizePathKey(info.cwd) === cwdKey);
+                // 200 名额只在 cwd 过滤**之后**分配：扁平布局下若先截断，本项目会话可能被
+                // 其他项目的文件挤出列表。截断仍按上面的 mtime 降序序取（Promise.all 保序），
+                // 与原有选集口径一致；非扁平布局每-cwd 子目录内文件全属本项目，过滤幂等。
+                const candidates = ownInfos.slice(0, 200);
+                candidates.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+                ClientSession.sessionInfosCache.set(cwdKey, { infos: candidates, at: Date.now() });
+                return candidates;
             }
             catch {
                 try {
                     const fallback = await SessionManager.list(this.cwd, piSessionsRoot());
-                    ClientSession.sessionInfosCache.set(cwdKey, { infos: fallback, at: Date.now() });
-                    return fallback;
+                    // 统一口径：列表缓存一律不带转录全文（issue #440），搜索按需另行加载
+                    const stripped = fallback.map((s) => ({ ...s, allMessagesText: "" }));
+                    ClientSession.sessionInfosCache.set(cwdKey, { infos: stripped, at: Date.now() });
+                    return stripped;
                 }
                 catch {
                     return [];
@@ -9389,7 +9866,10 @@ export class ClientSession {
     invalidateSessionInfos(filePath) {
         ClientSession.sessionInfosCache.clear();
         if (filePath) {
-            ClientSession.sessionFileCache.delete(resolve(filePath));
+            const abs = resolve(filePath);
+            ClientSession.sessionFileCache.delete(abs);
+            // 全文缓存一并清（issue #440）：文件已删/更名，正文不该再被搜索命中
+            ClientSession.sessionTextCache.delete(abs);
         }
     }
     /** Push the persisted session list to the client (client-requested). */
@@ -9414,7 +9894,7 @@ export class ClientSession {
             const infos = await this.loadSessionInfos();
             // 隐藏「被 fork 掉的父会话」，历史列表只保留每条 fork 链最新的链尾会话
             // （全文搜索 searchSessions 保留全部会话，不受此影响）。
-            const normSessionPath = (p) => String(p).replace(/\\/g, "/").replace(/\/$/, "").toLowerCase();
+            const normSessionPath = (p) => normalizePathKey(p);
             const forkedParentPaths = new Set();
             for (const info of infos) {
                 if (typeof info.parentSessionPath === "string" && info.parentSessionPath) {
@@ -9429,6 +9909,7 @@ export class ClientSession {
                 : infos;
             const sessions = new Map();
             for (const s of visibleInfos) {
+                const isPinned = this.stateStore?.isSessionPinned(this.cwd, s.path);
                 sessions.set(s.path, {
                     path: s.path,
                     name: s.name,
@@ -9436,6 +9917,7 @@ export class ClientSession {
                     messageCount: s.messageCount,
                     modified: s.modified.getTime(),
                     source: "web",
+                    ...(isPinned ? { pinned: true } : {}),
                 });
             }
             const sorted = [...sessions.values()].sort((a, b) => b.modified - a.modified).slice(0, 200); // newest first — the panel shows recent history
@@ -9550,6 +10032,8 @@ export class ClientSession {
                 return;
             }
             rmSync(abs, { force: true });
+            // 转录删了，钉住记录一起清理（issue #433）。
+            this.stateStore?.cleanPinnedSession(abs);
             // 转录删了，sidecar 再留着就是孤儿，一起清掉（不存在不报错）。
             removeTouchSidecar(abs);
             // 转录删了，未发送草稿再留着就是孤儿，一起清掉。
@@ -9639,9 +10123,15 @@ export class ClientSession {
             conv.pinned = true;
             // 立即进入运行列表（含空白对话）：listed 一旦置位，shownInRunningList 即放行。
             conv.listed = true;
+            if (conv.session.sessionFile) {
+                this.stateStore?.setSessionPinned(conv.cwd, conv.session.sessionFile, true);
+            }
         }
         else {
             delete conv.pinned;
+            if (conv.session.sessionFile) {
+                this.stateStore?.setSessionPinned(conv.cwd, conv.session.sessionFile, false);
+            }
         }
         this.emitConversations();
         this.flushSnapshot();
@@ -9656,6 +10146,27 @@ export class ClientSession {
                 : `Unpinned "${conv.title}" — it will be handled by the usual rules on the next switch`,
         });
     }
+    /** 钉住 / 取消钉住历史会话（持久化并在运行中/历史列表生效）。 */
+    async pinSession(path, pinned) {
+        const targetPath = resolve(path);
+        this.stateStore?.setSessionPinned(this.cwd, targetPath, pinned);
+        // 如果当前已在运行列表中，同步其 pinned 状态
+        for (const conv of this.convs.values()) {
+            if (conv.session.sessionFile && resolve(conv.session.sessionFile) === targetPath) {
+                if (pinned) {
+                    conv.pinned = true;
+                    conv.listed = true;
+                }
+                else {
+                    delete conv.pinned;
+                }
+                break;
+            }
+        }
+        this.emitConversations();
+        this.flushSnapshot();
+        await this.refreshSessions();
+    }
     /** Rename a live conversation by id: retitle in memory AND persist a
      *  session_info entry to its transcript so History matches immediately. */
     async renameConversation(id, name) {
@@ -10307,6 +10818,10 @@ export class ClientSession {
             // Deliberately resumed — must not be dismissed when the user later
             // switches away without sending a new message.
             conv.promptedSinceActive = true;
+            if (this.stateStore?.isSessionPinned(targetCwd, targetPath)) {
+                conv.pinned = true;
+                conv.listed = true;
+            }
             this.noticeInterruptedCompaction(conv);
             this.convs.set(conv.id, conv);
             this.activeId = conv.id;
@@ -10315,6 +10830,10 @@ export class ClientSession {
             if (displaced)
                 this.removeConversation(displaced.id);
             await this.bindSession();
+            // #436：转录回放恢复的 planMode 在 runtime 工厂的 applyToolGating 时还读不到
+            //（conv 尚未进 this.convs，planModeOf 落空）——注册后统一补一次门控，让
+            // 计划模式的写类/旁路工具剥离对重开的会话同样生效。下同（forkSession/setCwd）。
+            this.applyToolGating(conv.session, conv.agentPreset);
             this.cwd = targetCwd;
             // 打开的历史会话可能属于另一个项目 —— 工作区跟随面（roots/文件树/
             // 历史列表/命令目录/最近项目）必须跟着切，否则 UI 停在旧项目。
@@ -10509,6 +11028,9 @@ export class ClientSession {
             if (displaced)
                 this.removeConversation(displaced.id);
             await this.bindSession();
+            // #436：同 switchSession —— 派生出的会话若从转录回放恢复了 planMode，
+            // 工厂里的门控当时读不到它，注册后补一次。
+            this.applyToolGating(newConv.session, newConv.agentPreset);
             if (prevModel && this.sharedModelRuntime) {
                 try {
                     const pm = prevModel;
@@ -10677,7 +11199,8 @@ export class ClientSession {
         if (this.quiesceBlocked())
             return;
         const trimmed = text.trim();
-        if (!trimmed) {
+        const hasAttachments = Boolean(attachments && attachments.length > 0);
+        if (!trimmed && !hasAttachments) {
             this.emit({
                 type: "notice",
                 level: "warning",
@@ -10787,14 +11310,14 @@ export class ClientSession {
             try {
                 const discovered = await discoverRecentProjectsFromDisk(sessionRoots, 30);
                 this.stateStore.mergeDiscoveredProjects(discovered);
-                const merged = this.stateStore.getRecentProjects(this.clientId);
+                const merged = await this.stateStore.getRecentProjects(this.clientId);
                 ClientSession.projectsCache = { at: Date.now(), projects: merged };
                 const result = this.withCurrentCwd(merged, Date.now());
                 this.emit({ type: "projects", projects: result });
                 return merged;
             }
             catch {
-                const fallback = this.withCurrentCwd(this.stateStore.getRecentProjects(this.clientId), Date.now());
+                const fallback = this.withCurrentCwd(await this.stateStore.getRecentProjects(this.clientId), Date.now());
                 this.emit({ type: "projects", projects: fallback });
                 return fallback;
             }
@@ -10835,8 +11358,9 @@ export class ClientSession {
     }
     /** 全局搜索：在当前工作区的会话转录全文里做大小写不敏感匹配 ——
      *  不止首条消息，而是每一段 user 与 assistant 文本（AI 输出也在内）。
-     *  结果经 session_search_results 回推（reqId 匹配）；复用 loadSessionInfos()
-     *  缓存，避免每个按键都重新解析全部转录文件。 */
+     *  结果经 session_search_results 回推（reqId 匹配）；元信息复用 loadSessionInfos()
+     *  缓存，转录全文按需加载（issue #440，小容量短 TTL 缓存），避免每个按键都重新
+     *  解析全部转录文件、也不让全文长期驻留内存。 */
     async searchSessions(query, reqId) {
         const q = query.trim().toLowerCase();
         if (!q) {
@@ -10845,11 +11369,12 @@ export class ClientSession {
         }
         try {
             const infos = await this.loadSessionInfos();
-            const results = infos
-                .filter((s) => sessionMatchesSearch(q, s))
+            const matched = await ClientSession.filterSessionsForSearch(q, infos);
+            const results = matched
                 .sort((a, b) => b.modified.getTime() - a.modified.getTime())
                 .slice(0, 50)
                 .map((s) => {
+                const isPinned = this.stateStore?.isSessionPinned(this.cwd, s.path);
                 const base = {
                     path: s.path,
                     name: s.name,
@@ -10857,6 +11382,7 @@ export class ClientSession {
                     messageCount: s.messageCount,
                     modified: s.modified.getTime(),
                     source: "web",
+                    ...(isPinned ? { pinned: true } : {}),
                 };
                 // 命中会话里再定位具体消息（供点击跳转）；仅元数据命中则无锚点
                 return { ...base, anchors: collectSessionAnchors(s.path, q) };
@@ -10985,26 +11511,6 @@ export class ClientSession {
             await this.setCwd(created);
         }
     }
-    async cycleModel() {
-        try {
-            const result = await this.session.cycleModel();
-            if (result?.model) {
-                const mid = `${result.model.provider}/${result.model.id}`;
-                await this.restoreKeyForModel(mid, this.cwd);
-                // Remember per-project like setModel — cycling is also a model switch.
-                this.rememberProjectModel(mid);
-            }
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `切换模型失败：${err.message}`,
-                textEn: `Failed to switch model: ${err.message}`,
-            });
-        }
-        this.flushSnapshot();
-    }
     /**
      * Path completion for the cwd input: expand ~/relative paths, list the parent
      * directory, and return prefix matches (dirs first, capped).
@@ -11152,6 +11658,9 @@ export class ClientSession {
                     }
                 }
                 await this.bindSession();
+                // #436：同 switchSession —— 续聊最近会话若从转录回放恢复了 planMode，
+                // 工厂里的门控当时读不到它，注册后补一次。
+                this.applyToolGating(conv.session, conv.agentPreset);
                 if (resumeSkipped) {
                     this.emit(resumeSkipped.isStreaming
                         ? {
@@ -11440,24 +11949,6 @@ export class ClientSession {
         }
         this.flushSnapshot();
     }
-    cycleThinking() {
-        try {
-            const nextLevel = this.session.cycleThinkingLevel({ persist: true });
-            const cur = this.session.model;
-            if (cur && nextLevel) {
-                this.session.settingsManager.setModelThinkingLevel(cur.provider, cur.id, nextLevel);
-            }
-        }
-        catch (err) {
-            this.emit({
-                type: "notice",
-                level: "error",
-                text: `切换思考强度失败：${err.message}`,
-                textEn: `Failed to switch thinking level: ${err.message}`,
-            });
-        }
-        this.flushSnapshot();
-    }
     /** Push the user command list (.pi/commands.json) to the client. */
     async listCommands() {
         const { commands, path, warning, warningEn } = await loadCommands(this.cwd);
@@ -12318,6 +12809,7 @@ export class AgentService {
                 textEn: `"${main.title}" was moved to this page — pick up right where it left off.`,
             });
             await target.switchConversation(newMainId);
+            await target.bindSession();
         }
         catch (err) {
             fail(`过户失败：${err.message}`, `Takeover failed: ${err.message}`);