pi-web-ui 0.90.1 → 0.91.0

package/dist/server/agent-service.js

@@ -15,7 +15,7 @@
 // wholesale (no union merge / no stale built-in leftovers).
 import "./patch-remote-catalog.js";
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { appendFileSync, existsSync, readFileSync, rmSync, statSync, mkdirSync, watch, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -26,6 +26,7 @@ import { Type } from "typebox";
 import { BgServerTracker } from "./bg-servers.js";
 import { checkAll as checkAllUpdates, collectTargets, compareVersions as compareSemver, resolveNpmRegistry, sortUpdateItems, } from "./update-check.js";
 import { hasActiveSubagentRun, hasPendingWaitSubscription, shouldRetainActive } from "./wait-subscription-scan.js";
+import { COMPACTION_PENDING_TYPE, looksLikeChainCorruption, makeCompactionMarkerId, repairSessionFile, } from "./compaction-markers.js";
 import { removeQueuedByIndexOrText } from "./queue-utils.js";
 import { syncPluginToolsIntoSession } from "./plugins.js";
 import { SettingsService } from "./settings-service.js";
@@ -41,14 +42,19 @@ import { ComposerDraftsStore } from "./composer-drafts.js";
 import { applyHeadTail, makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, } from "./terminals.js";
 import { applyAgentToolsGating, ASK_USER_QUESTION_TOOL_NAME, BROWSER_PAGE_TOOL_NAME, effectiveDisabledAgentTools, isTerminalGuidanceOn, MARKERS_LIST_TOOL_NAME, } from "./tool-manager.js";
 import { WebUIContext } from "./webui-context.js";
+import { DEFAULT_COMPACTION_RESERVE_TOKENS, effectiveSoftCap, softCapToReserve } from "./soft-cap.js";
 import { decodeText } from "./text-sniff.js";
 import { makeEditSoftTool } from "./edit-soft-tool.js";
 import { collectSubagentDescendantIds, makeSubagentTools, subagentTitle, withSubagentOwner, } from "./subagents.js";
 import { makeDelegateTaskTool } from "./delegate-task.js";
 import { makeConversationReadTool, parseTranscriptLines, toTranscriptInput, } from "./conversation-read-tool.js";
+import { makeSkillTool } from "./skill-tool.js";
 import { makeScheduleTools } from "./schedule-agent-tool.js";
+import { sameSessionFile } from "./scheduler-tasks.js";
 import { buildAttachmentMessages, parseModelSpec } from "./attachments.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, renderPromptTemplate, resolveSectionTexts, } from "./prompt-composer.js";
 import { launchOrigin, toServiceInfo } from "./launch-origin.js";
 import { serializeMessage, serializeStreamingMessage, stripTransientRetryErrors, } from "./serialize.js";
@@ -68,6 +74,8 @@ 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;
+/** SCM「AI 生成提交信息」的单次补全超时——慢供应商不该让按钮转圈到天荒地老。 */
+const SCM_COMMITMSG_TIMEOUT_MS = 60_000;
 /** 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
@@ -648,6 +656,13 @@ const TOOL_WATCHDOG_TIMEOUT_MS = (() => {
  *  runtime alive; conversations of other projects keep their own lists).
  *  子代理不计入：子代理是 inMemory 后台任务，不参与此上限，既不占位也不被此上限拦截。 */
 const MAX_OPEN_CONVERSATIONS = 8;
+/** 同时存活的子代理上限（按客户端计，含嵌套派生的孙子辈）。每个子代理都是一个完整
+ *  runtime + TerminalManager，无上限时 AI 一次并行派发几十个会把服务进程拖垮。
+ *  主对话的 8 个上限是按项目计的，子代理按客户端全局计（wait_all 本来就是全局口径）。 */
+const MAX_SUBAGENTS = 16;
+/** SubagentSnapshot.prompt 下发上限：存的是全量 prompt，快照里只带前 N 字符，
+ *  避免 subagent_list 一次把几个长 prompt 全推给模型烧 token。 */
+const SUBAGENT_PROMPT_SNAPSHOT_CAP = 2000;
 const DEFAULT_CONV_TITLE = "新对话";
 /** First user text in a session, truncated for the conversation list. */
 function conversationTitle(session) {
@@ -784,6 +799,26 @@ export function isInsideSessionsDir(agentDir, targetPath) {
     const sessionsRoot = resolve(agentDir, "sessions");
     return abs.startsWith(sessionsRoot + sep);
 }
+/** 会话当前模型的 "provider/id"（无模型时 null；软上限按模型覆盖用，issue #229）。 */
+function modelKeyOf(session) {
+    const m = session?.model;
+    if (!m || typeof m.provider !== "string" || typeof m.id !== "string")
+        return null;
+    return `${m.provider}/${m.id}`;
+}
+/** 会话当前模型的上下文窗口（未知时 0）：live 统计优先，模型定义回落。 */
+function contextWindowOf(session) {
+    try {
+        const live = session?.getSessionStats?.()?.contextUsage?.contextWindow;
+        if (typeof live === "number" && live > 0)
+            return Math.floor(live);
+    }
+    catch {
+        // 会话未就绪 → 回落模型定义。
+    }
+    const def = session?.model?.contextWindow;
+    return typeof def === "number" && def > 0 ? Math.floor(def) : 0;
+}
 /**
  * 选一个断开的残留会话给新标签认领（纯函数）：
  * - 还有别的在线浏览器（非伪客户端且 live）→ 不认领（新标签是第二块屏，
@@ -804,6 +839,23 @@ export function pickAdoptableOrphan(cands) {
     }
     return best?.id ?? null;
 }
+/** 同项目判定（纯函数）：调度视口回退与 id 唤醒的 cwd 护栏用。
+ *  Windows 大小写/分隔符差异归一，空串永不相等。 */
+export function sameCwd(a, b) {
+    const x = String(a ?? "").trim();
+    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));
+    }
+    catch {
+        return false;
+    }
+}
 export class ClientSession {
     clientId;
     /** Set by AgentService.attach: reflects the SERVICE-wide quiesce flag
@@ -986,12 +1038,27 @@ export class ClientSession {
      *  回退到模板模型 / 设置面板默认模型；null = 跟随主对话当前模型（默认行为，
      *  runtime 重建时会继承共享 ModelRuntime 的当前默认）。 */
     async spawnSubagentConversation(prompt, type, cwd, apply, model, parentId) {
+        // 数量上限先行：每个子代理都是完整 runtime + TerminalManager，无上限时一次
+        // 并行派发几十个会把服务进程拖垮。抛错由 subagent_spawn / delegate_task 转成
+        // 返回文本，AI 读到后可改串行 / 等待收口后重试，而不是看到工具异常。
+        const liveSubagents = [...this.convs.values()].filter((c) => c.isSubagent).length;
+        if (liveSubagents >= MAX_SUBAGENTS) {
+            throw new Error(pick(this.getLang(), `子代理数量已达上限（${MAX_SUBAGENTS} 个），请先用 subagent_wait_all 等一部分完成、或用 subagent_stop 停掉不需要的再派发`, `Subagent limit reached (${MAX_SUBAGENTS} live). Wait for some with subagent_wait_all or stop unneeded ones with subagent_stop before spawning more`, "agent.subagent.limit.reached", { limit: MAX_SUBAGENTS }));
+        }
+        // 真正的派发者（withSubagentOwner 按 runtime 归属填入）：cwd 基准 / 跟随模型 /
+        // 跟随思考强度一律读它，而不是派发瞬间的 active——后台对话产出时用户可能正
+        // 看着别的项目，读 active 会跟错模型、把相对 cwd 解析到错误的项目下。
+        const spawner = parentId ? this.convs.get(parentId) : undefined;
+        const spawnerSession = spawner?.session ?? this.session;
+        const baseCwd = spawner?.cwd ?? this.cwd;
+        // 相对 cwd 按派发者所在目录解析：直接透传会相对 server 进程 cwd 落到别处。
+        const resolvedCwd = cwd ? resolve(baseCwd, cwd) : baseCwd;
         const conversationId = `sa-${randomUUID().slice(0, 8)}`;
-        const terminals = this.makeTerminalManager(conversationId, cwd);
+        const terminals = this.makeTerminalManager(conversationId, resolvedCwd);
         const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(terminals, apply, conversationId), {
-            cwd,
+            cwd: resolvedCwd,
             agentDir: this.agentDir,
-            sessionManager: SessionManager.inMemory(cwd),
+            sessionManager: SessionManager.inMemory(resolvedCwd),
         });
         const conv = this.makeConversation(runtime, conversationId, terminals);
         conv.isSubagent = true;
@@ -1000,6 +1067,11 @@ export class ClientSession {
         // 对话名下、沉到别的项目组底部（issue #95）。缺省才回退到 active。
         conv.parentId = parentId ?? this.activeId ?? undefined;
         conv.subagentType = type;
+        conv.subagentPrompt = prompt;
+        // 插件工具门与模板扩展白名单对齐：白名单非空时插件/MCP 工具（无 SDK
+        // extensionKey 身份）不进该会话。工厂期 customTools 不注册 + 下面的
+        // syncPluginTools 不回补，模板热改不影响已运行的子代理（与 prompt/技能一致）。
+        conv.subagentBarsPluginTools = !!apply && apply.enabledExtensions.length > 0;
         conv.listed = true;
         conv.title = subagentTitle(prompt);
         this.convs.set(conv.id, conv);
@@ -1009,6 +1081,8 @@ export class ClientSession {
         conv.unsubscribe = conv.session.subscribe((event) => this.onEvent(conv, event));
         // 子代理不走 bindSession——这里同样注入面板的重试次数覆盖。
         this.applyRetryOverrides();
+        // 软上限覆盖同样重放（子代理跟随主对话的压缩阈值，issue #229）。
+        this.applyCompactionOverrides();
         // 扩展绑定（rpc 模式）；用 headless 的 Web UI context：
         // 扩展绑定时不会因缺方法崩，UI 输出也不下发（不会与主对话的 widget/status 冲突）。
         try {
@@ -1030,8 +1104,8 @@ export class ClientSession {
         const resolvedModel = model ?? (apply?.model?.trim() || null) ?? (this.settingsSvc.current.subagentDefaultModel || null);
         const followModel = resolvedModel
             ? resolvedModel
-            : this.session.model
-                ? `${this.session.model.provider}/${this.session.model.id}`
+            : spawnerSession.model
+                ? `${spawnerSession.model.provider}/${spawnerSession.model.id}`
                 : null;
         if (followModel) {
             const slash = followModel.indexOf("/");
@@ -1041,7 +1115,8 @@ export class ClientSession {
             if (m) {
                 try {
                     // 先恢复该 provider 的项目密钥（setModel 的鉴权检查要用），再换模型。
-                    await this.restoreKeyForModel(followModel, cwd);
+                    // 按子代理自己的目录恢复（跨目录派发时派发者的密钥不一定适用）。
+                    await this.restoreKeyForModel(followModel, resolvedCwd);
                     await conv.session.setModel(m);
                 }
                 catch (err) {
@@ -1063,12 +1138,12 @@ export class ClientSession {
                 });
             }
         }
-        // 思考强度：模板指定则固定用它，否则跟随主对话当前强度（与「跟随主对话模型」
-        // 同一取数源：this.session，即共享 ModelRuntime 的当前活动会话）。所以子代理默认
-        // 与主对话一致，而不是默默回到 SDK 默认档位。放在换模型之后：setModel 会按模型
-        // 能力重算强度，我们先让它算完再覆盖。不传 persist：只影响这个子代理会话，不动
-        // 全局默认强度；模型不支持的档位由 SDK 自动收敛（reasoning:false 的模型只能是 off）。
-        const thinkingLevel = apply?.thinkingLevel?.trim() || this.session.thinkingLevel;
+        // 思考强度：模板指定则固定用它，否则跟随派发者当前强度（与「跟随派发者模型」
+        // 同一取数源：spawnerSession）。所以子代理默认与派发者一致，而不是默默回到
+        // SDK 默认档位。放在换模型之后：setModel 会按模型能力重算强度，我们先让它
+        // 算完再覆盖。不传 persist：只影响这个子代理会话，不动全局默认强度；模型不
+        // 支持的档位由 SDK 自动收敛（reasoning:false 的模型只能是 off）。
+        const thinkingLevel = apply?.thinkingLevel?.trim() || spawnerSession.thinkingLevel;
         if (thinkingLevel) {
             try {
                 conv.session.setThinkingLevel(thinkingLevel);
@@ -1109,7 +1184,10 @@ export class ClientSession {
     }
     toSubagentSnapshot(conv) {
         const streaming = conv.session.isStreaming;
-        const state = streaming ? "running" : "done";
+        const { error, canceled } = this.subagentRunOutcome(conv);
+        // state 如实反映终态：之前 canceled 的子代理报的也是 done，只能靠独立 flag
+        // 分辨。"queued" 保留给未来（排队调度），当前 spawn 即运行，无排队态。
+        const state = streaming ? "running" : canceled ? "canceled" : "done";
         let messageCount = 0;
         try {
             messageCount = conv.session.getSessionStats().totalMessages;
@@ -1117,12 +1195,14 @@ export class ClientSession {
         catch {
             // session being replaced — report defaults
         }
-        const { error, canceled } = this.subagentRunOutcome(conv);
+        const fullPrompt = conv.subagentPrompt ?? "";
         return {
             convId: conv.id,
             type: conv.subagentType ?? "general",
             title: conv.title,
-            prompt: "",
+            prompt: fullPrompt.length > SUBAGENT_PROMPT_SNAPSHOT_CAP
+                ? `${fullPrompt.slice(0, SUBAGENT_PROMPT_SNAPSHOT_CAP)}\n… [truncated]`
+                : fullPrompt,
             state,
             streaming,
             error,
@@ -1130,6 +1210,7 @@ export class ClientSession {
             messageCount,
             model: conv.session.model?.id,
             output: conv.session.getLastAssistantText() ?? "",
+            parentId: conv.parentId,
         };
     }
     /** 子代理最近一次运行的结局：最后一条 assistant 消息的 errorMessage / stopReason。
@@ -1200,6 +1281,9 @@ export class ClientSession {
     lastSdkAppendFiles = [];
     /** 当前活动会话的工具/资源快照 → composer 输入。cwd 取活动对话的。 */
     composeInputs(src) {
+        // 技能名录指纹观测（只打日志，不干预组装；预览与 run 共用此入口，
+        // 变化才记一行，首轮静默）。用未注文的目录（fill 前），全文注入不影响指纹。
+        this.noteSkillCatalogDigest(src.skills);
         return {
             cwd: src.cwd,
             systemPromptFile: this.lastBaseSystemPrompt || undefined,
@@ -1364,12 +1448,32 @@ export class ClientSession {
             return !!t && t.enabled;
         },
     };
-    /** schedule_* 工具的数据宿主：全局调度存储＋创建时刻 live 的 cwd/活动对话。 */
+    /** schedule_* 工具的数据宿主：全局调度存储＋创建时刻 live 的 cwd/活动对话。
+     *  issue #231：同时快照 owner 对话的落盘会话文件（压缩/重启后稳定），触发时
+     *  先按 sessionFile 认同一会话（内存对话 id 重启即失效，不可单独做持久键）。 */
     scheduleToolHost() {
         return {
             store: () => this.schedulerStore,
             cwd: () => this.cwd,
             activeConversationId: () => this.activeId,
+            conversationInfo: (id) => {
+                try {
+                    const target = (id ?? "").trim() ? this.convs.get((id ?? "").trim()) : this.convs.get(this.activeId);
+                    if (!target)
+                        return undefined;
+                    let sessionFile = "";
+                    try {
+                        sessionFile = String(target.session.sessionFile ?? "");
+                    }
+                    catch {
+                        sessionFile = "";
+                    }
+                    return { cwd: target.cwd ?? this.cwd, sessionFile };
+                }
+                catch {
+                    return undefined;
+                }
+            },
         };
     }
     /** conversation_read 工具的数据宿主：读本客户端的 conversation 体系 +
@@ -1452,6 +1556,45 @@ export class ClientSession {
             },
         };
     }
+    /** skill 工具的数据宿主：读所属会话 loader 的实时技能表 + 主会话禁用集过滤
+     * （与 skillsOverride 主会话语义一致）。ownerId 语义同 browser_page（本
+     * runtime 所属会话，不是派发瞬间的 active）。失败回空目录，不抛错。 */
+    skillToolHost(ownerId) {
+        return {
+            listSkills: () => {
+                try {
+                    const target = (ownerId ?? "").trim() !== "" ? this.convs.get(ownerId.trim()) : this.convs.get(this.activeId);
+                    const all = target?.session.resourceLoader.getSkills().skills ?? [];
+                    const disabled = new Set(this.settingsSvc.current.disabledSkills);
+                    return all
+                        .filter((s) => !disabled.has(s.name))
+                        .map((s) => ({
+                        name: s.name,
+                        description: s.description ?? "",
+                        filePath: s.filePath ?? "",
+                    }));
+                }
+                catch {
+                    return [];
+                }
+            },
+        };
+    }
+    /** 技能名录指纹（sha256 over name+description，非正文）：变化才打一行日志，
+     * 首轮静默。只观测不干预组装（digest 第一步：日志；复用以后再说）。 */
+    lastSkillCatalogDigest = "";
+    noteSkillCatalogDigest(skills) {
+        const d = createHash("sha256")
+            .update(skills.map((s) => `${s.name}\n${s.description}`).join("\n"))
+            .digest("hex")
+            .slice(0, 16);
+        if (d === this.lastSkillCatalogDigest)
+            return;
+        const prev = this.lastSkillCatalogDigest;
+        this.lastSkillCatalogDigest = d;
+        if (prev)
+            console.log(`[skills] catalog digest ${prev}→${d} (${skills.length} skills)`);
+    }
     widgetsTimer = null;
     /** Model-stall watchdog interval (see startStallTimer). */
     stallTimer = null;
@@ -1575,13 +1718,15 @@ export class ClientSession {
             reloadSession: async () => {
                 await this.session.reload();
                 // reload() 重读磁盘 settings.json，会丢掉内存 applyOverrides
-                // （含重试次数覆盖）——依次重放：重试覆盖 → 终端门控。
+                // （含重试次数覆盖）——依次重放：重试覆盖 → 软上限覆盖 → 终端门控。
                 this.applyRetryOverrides();
+                this.applyCompactionOverrides();
                 // reload() 会把 custom 工具重新加回活跃集——重放终端开关。
                 this.applyToolGating(this.session);
                 await this.pushSlashCommands();
             },
             applyRetryOverrides: () => this.applyRetryOverrides(),
+            applyCompactionOverrides: () => this.applyCompactionOverrides(),
             applyToolGating: () => this.applyToolGating(this.session),
             promptSnapshot: () => this.promptSnapshot(),
             getMarkerState: () => ({
@@ -1631,15 +1776,22 @@ export class ClientSession {
         const cs = new ClientSession(clientId, cwd, agentDir, stateStore);
         const conversationId = cs.nextConversationId();
         const terminals = cs.makeTerminalManager(conversationId, cwd);
-        const runtime = await createAgentSessionRuntime(cs.makeRuntimeFactory(terminals, undefined, conversationId), {
+        // 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.
+        // issue #145: opts.blank = 跳过恢复（最近那条在别处跑着），直接空白新对话。
+        // issue #235：坏转录（重复压缩标记成环）修一次再试，否则整项目首屏
+        // "Failed to initialize session"。
+        const opened = await cs.openManagerAndRuntime(() => (opts?.blank ? SessionManager.create(cwd) : SessionManager.continueRecent(cwd)), (m) => createAgentSessionRuntime(cs.makeRuntimeFactory(terminals, undefined, conversationId), {
             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.
-            // issue #145: opts.blank = 跳过恢复（最近那条在别处跑着），直接空白新对话。
-            sessionManager: opts?.blank ? SessionManager.create(cwd) : SessionManager.continueRecent(cwd),
-        });
+            sessionManager: m,
+        }), async () => (await SessionManager.list(cwd))[0]?.path);
+        const runtime = opened.runtime;
+        if (opened.repair) {
+            for (const n of cs.transcriptRepairNotices(opened.repair))
+                cs.pendingNotices.push(n);
+        }
         // First conversation = the resumed session; it also seeds the shared
         // ModelRuntime that every later conversation reuses.
         cs.sharedModelRuntime = runtime.services.modelRuntime;
@@ -1779,12 +1931,18 @@ export class ClientSession {
                                     // 把灵魂段换成模板提示词，自动段保留；SYSTEM.md 情形已在
                                     // systemPromptOverride 整体替换，此处边界不存在会自然跳过。
                                     if (apply) {
-                                        if (apply.promptMode !== "replace" || !pickTemplatePrompt(apply, this.getLang()).trim())
+                                        const tplPrompt = pickTemplatePrompt(apply, this.getLang()).trim();
+                                        if (apply.promptMode !== "replace" || !tplPrompt)
                                             return undefined;
                                         const boundary = event.systemPrompt.indexOf("\n\nAvailable tools:");
-                                        if (boundary === -1)
-                                            return undefined;
-                                        const swapped = pickTemplatePrompt(apply, this.getLang()).trimEnd() + event.systemPrompt.slice(boundary);
+                                        // 边界串是 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);
                                         return swapped === event.systemPrompt ? undefined : { systemPrompt: swapped };
                                     }
                                     // 主会话：组合模板渲染（模板为空且无覆盖时返回 undefined = 用 SDK 默认）。
@@ -1834,7 +1992,10 @@ export class ClientSession {
                     makeEditSoftTool(effectiveCwd, () => this.getLang()),
                     // 插件注册的 AI 工具（创建时刻的实时快照，已按 disabledPluginTools 过滤；
                     // 后续注册经 refreshPluginTools 动态补入已有会话）。
-                    ...this.enabledPluginToolDefs(),
+                    // 子代理模板带非空扩展白名单时不注入：插件/MCP 工具没有 SDK extensionKey
+                    // 身份、无法参与白名单匹配，全放行等于白名单没关门，全收编才符合「只加载这些」。
+                    // 空白名单 = 跟随主会话（插件工具照常进入子代理）。
+                    ...(apply && apply.enabledExtensions.length > 0 ? [] : this.enabledPluginToolDefs()),
                     // 第一方子代理工具（spawn/get_result/steer/list/stop）。子代理会话
                     // 也注册了它们，因此可自然嵌套派发。host 按 ownerId 包装：子代理的
                     // 父对话 = 真正调用 spawn 的那个会话（本 runtime 所属会话），而不是
@@ -1866,6 +2027,10 @@ export class ClientSession {
                     // 会话同样注册了它，可自然嵌套读取。不需要 ownerId——读的是本
                     // 客户端的 conversation 体系与落盘历史，与派发者无关。
                     makeConversationReadTool(this.conversationReadHost(), () => this.getLang()),
+                    // 技能全文按名加载（名录在 {{skills}} 段）：模型不再拼路径调 read。
+                    // 子代理会话同样注册（owner 即真正派发的父对话，读该会话 loader）。
+                    // DSH 引擎无 customTool 注册面，不接。开关走统一工具 tab。
+                    makeSkillTool(this.skillToolHost(ownerId), () => this.getLang()),
                     // 定时唤醒三件套（schedule_task/list/cancel，issue #193）：默认绑定
                     // 发起对话（ownerId，无则活动对话），到期 steer 语义唤醒它；子代理
                     // 会话同样注册（owner 即真正派发的父对话）。开关走统一工具 tab。
@@ -2075,6 +2240,8 @@ export class ClientSession {
         // 默认重试 3 次——这里把面板的 retryMaxAttempts 覆盖注入，否则“设了 6
         // 次还是按 3 次重试”。已存在会话重复注入是幂等的（同值覆盖）。
         this.applyRetryOverrides();
+        // 软上限覆盖同路重放（新 runtime 的 SettingsManager 是干净的，issue #229）。
+        this.applyCompactionOverrides();
         this.scheduleSnapshot();
         this.webUi.refresh();
         this.startWidgetsTimer();
@@ -2343,6 +2510,94 @@ export class ClientSession {
         await conv.session.sendUserMessage(text, conv.session.isStreaming ? { deliverAs: "steer" } : undefined);
         return { ok: true };
     }
+    /** issue #231：本客户端内按稳定键定位调度唤醒目标。
+     *  sessionFile 优先（压缩/重启后内存对话 id 已变，落盘会话文件才是同一会话）；
+     *  只有没给 sessionFile 时才按内存 id 找，且 id 必须附带 cwd 一致才认 ——
+     *  各客户端计数器都从 c1 开始，跨项目同 id 必然撞车，不校验 cwd 会把巡检
+     *  报告投进完全无关的项目对话。
+     *  excludeIds 用于视口回退时跳过已知的忙对话。 */
+    resolveSchedulerTarget(opts) {
+        const wantFile = String(opts.sessionFile ?? "").trim();
+        const wantId = String(opts.conversationId ?? "").trim();
+        const wantCwd = String(opts.cwd ?? "").trim();
+        const excluded = opts.excludeIds;
+        if (wantFile) {
+            let best = null;
+            for (const c of this.convs.values()) {
+                if (!c?.session || (excluded && excluded.has(c.id)))
+                    continue;
+                let f = "";
+                try {
+                    f = String(c.session.sessionFile ?? "");
+                }
+                catch {
+                    continue;
+                }
+                if (!sameSessionFile(f, wantFile))
+                    continue;
+                if (!best || c.lastActiveAt > best.lastActiveAt)
+                    best = c;
+            }
+            if (best)
+                return best;
+        }
+        if (wantId) {
+            const c = this.convs.get(wantId);
+            if (!c?.session || (excluded && excluded.has(c.id)))
+                return null;
+            if (wantCwd && !sameCwd(c.cwd, wantCwd))
+                return null;
+            return c;
+        }
+        return null;
+    }
+    /** issue #231：本客户端内同项目的最近活跃对话（视口回退目标）。
+     *  主对话优先（用户正看着的面），没有主对话时才考虑子代理行；
+     *  最近活跃者即用户当前的视口。 */
+    findViewportInCwd(cwd, excludeIds) {
+        const want = String(cwd ?? "").trim();
+        if (!want)
+            return null;
+        let best = null;
+        let bestSub = null;
+        for (const c of this.convs.values()) {
+            if (!c?.session || (excludeIds && excludeIds.has(c.id)))
+                continue;
+            if (!sameCwd(c.cwd, want))
+                continue;
+            if (c.isSubagent) {
+                if (!bestSub || c.lastActiveAt > bestSub.lastActiveAt)
+                    bestSub = c;
+            }
+            else if (!best || c.lastActiveAt > best.lastActiveAt) {
+                best = c;
+            }
+        }
+        return best ?? bestSub;
+    }
+    /** issue #231：带压缩忙检测的调度 steer。压缩进行中时 SDK 直接抛错
+     *  （Cannot submit a prompt while compaction is in progress），调用方据 busy
+     *  另寻视口兄弟或稍后重试，而不是当成“对话不在”静默转无头。 */
+    async trySteerScheduler(conv, text) {
+        try {
+            try {
+                if (conv.session.isCompacting === true) {
+                    return { ok: false, busy: true, error: "上下文压缩进行中，稍后重试" };
+                }
+            }
+            catch {
+                /* 读不到压缩态就直接投递，失败按异常走 */
+            }
+            await conv.session.sendUserMessage(text, conv.session.isStreaming ? { deliverAs: "steer" } : undefined);
+            return { ok: true };
+        }
+        catch (err) {
+            const msg = String(err?.message ?? err);
+            if (/compaction is in progress/i.test(msg))
+                return { ok: false, busy: true, error: msg };
+            return { ok: false, busy: false, error: msg };
+        }
+    }
     /** 插件扩展点（供 runSteerer）：向指定对话插队一条用户消息，复用子代理 steer 的
      *  sendUserMessage + deliverAs:'steer' 路径（运行时插队；未跑时按普通消息投递）。
      *  先找本客户端 conversations，找不到再经 steerConversationElsewhere 问其他客户端；
@@ -2949,12 +3204,14 @@ export class ClientSession {
                             contextWindow: cu.contextWindow,
                             percent: (conv.lastCompactionTokens / cu.contextWindow) * 100,
                             estimated: true,
+                            softCap: this.activeSoftCap(cu.contextWindow),
                         };
                     }
                     return {
                         tokens: cu.tokens,
                         contextWindow: cu.contextWindow,
                         percent: cu.percent,
+                        softCap: this.activeSoftCap(cu.contextWindow),
                     };
                 })(),
             };
@@ -3588,8 +3845,9 @@ export class ClientSession {
         },
         refreshSessions: () => this.refreshSessions(),
         afterReload: () => {
-            // /reload 同样重读磁盘 settings.json——重放重试覆盖 + 终端门控。
+            // /reload 同样重读磁盘 settings.json——重放重试覆盖 + 软上限覆盖 + 终端门控。
             this.applyRetryOverrides();
+            this.applyCompactionOverrides();
             this.applyToolGating(this.session);
         },
         pluginCommands: () => this.pluginCommandsProvider?.() ?? [],
@@ -3833,6 +4091,40 @@ export class ClientSession {
             }
         }
     }
+    /** 把压缩软上限换算成各存活会话的 compaction reserveTokens 覆盖
+     *  （issue #229）。与重试覆盖同一 live 机制：applyOverrides 只改内存
+     *  合并视图，SDK 每次自动压缩检查前都重读 getCompactionSettings()，
+     *  无需 reload；软上限关闭时回填 SDK 默认 reserve（不让旧覆盖泄漏）。
+     *  窗口未知（会话未就绪/无模型）的会话跳过——创建/就绪/换模型路径
+     *  会重放（见各 applyRetryOverrides 调用点）。 */
+    applyCompactionOverrides() {
+        const s = this.settingsSvc.current;
+        for (const c of this.convs.values()) {
+            try {
+                const modelId = modelKeyOf(c.session);
+                const contextWindow = contextWindowOf(c.session);
+                const cap = effectiveSoftCap(s.softCapTokens, s.softCapByModel, modelId);
+                const reserve = softCapToReserve(contextWindow, cap);
+                c.session.settingsManager.applyOverrides({
+                    compaction: { reserveTokens: reserve ?? DEFAULT_COMPACTION_RESERVE_TOKENS },
+                });
+            }
+            catch {
+                // 会话未就绪或已释放 → 其 runtime 创建时统一注入。
+            }
+        }
+    }
+    /** 当前活动对话的生效软上限（快照底栏标记线用；null = 关闭/未知）。 */
+    activeSoftCap(contextWindow) {
+        try {
+            const s = this.settingsSvc.current;
+            const cap = effectiveSoftCap(s.softCapTokens, s.softCapByModel, modelKeyOf(this.session));
+            return softCapToReserve(contextWindow, cap) === null ? null : cap;
+        }
+        catch {
+            return null;
+        }
+    }
     /** 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_end, same as settings reloads. */
@@ -3867,6 +4159,7 @@ export class ClientSession {
                 try {
                     await this.session.reload();
                     this.applyRetryOverrides();
+                    this.applyCompactionOverrides();
                     this.applyToolGating(this.session);
                     await this.pushSlashCommands();
                     this.pushSettings();
@@ -3929,8 +4222,14 @@ export class ClientSession {
         return (this.pluginToolsProvider?.() ?? []).filter((t) => !off.has(t.name)).map(pluginToolToDefinition);
     }
     /** 把插件 AI 工具同步进一个已存在的会话（新增/更新/移除；禁用工具同步移除）。
-     *  实际 diff 逻辑在 plugins.ts 的 syncPluginToolsIntoSession（可单测）。 */
+     *  实际 diff 逻辑在 plugins.ts 的 syncPluginToolsIntoSession（可单测）。
+     *  模板白名单的子代理（subagentBarsPluginTools）跳过：工厂期就没注册，这里
+     *  不回补，否则白名单等于没关门。 */
     syncPluginTools(session) {
+        for (const conv of this.convs.values()) {
+            if (conv.session === session && conv.subagentBarsPluginTools)
+                return;
+        }
         try {
             const defs = this.enabledPluginToolDefs();
             const next = syncPluginToolsIntoSession(session, defs, this.appliedPluginToolNames);
@@ -4202,7 +4501,8 @@ export class ClientSession {
             // issue #145：同项目并行感知 —— 同一 cwd 下别处（或其他对话）正在跑时，
             // 允许并行（可以同时改不同部分），但用户与 AI 都必须知道。只在新一轮启动时
             // 通告一次（steer/排队等流式中发送不重复打扰）。
-            if (!conv.isSubagent && !s.isStreaming) {
+            // parallelReminderEnabled=false 时整段跳过（不发 notice、不注 AI、不通知对端）。
+            if (!conv.isSubagent && !s.isStreaming && this.settingsSvc.current.parallelReminderEnabled !== false) {
                 const localRunners = [...this.convs.values()]
                     .filter((c) => c.id !== conv.id && !c.isSubagent && c.cwd === conv.cwd && this.conversationStreaming(c))
                     .map((c) => ({ title: c.title }));
@@ -4655,11 +4955,17 @@ export class ClientSession {
             this.clearAllToolWatchdogs(conv);
             conv.toolStartTimes.clear();
             await conv.runtime.dispose();
-            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(conv.terminals, undefined, conv.id), {
+            // #235：转录链损坏时修一次再试（见 openManagerAndRuntime）。
+            const opened = await this.openManagerAndRuntime(() => SessionManager.continueRecent(conv.cwd), (m) => createAgentSessionRuntime(this.makeRuntimeFactory(conv.terminals, undefined, conv.id), {
                 cwd: conv.cwd,
                 agentDir: this.agentDir,
-                sessionManager: SessionManager.continueRecent(conv.cwd),
-            });
+                sessionManager: m,
+            }), async () => (await SessionManager.list(conv.cwd))[0]?.path);
+            const runtime = opened.runtime;
+            if (opened.repair) {
+                for (const n of this.transcriptRepairNotices(opened.repair))
+                    this.emit(n);
+            }
             conv.runtime = runtime;
             conv.session = runtime.session;
             this.emit({
@@ -4814,9 +5120,11 @@ export class ClientSession {
                 return;
             // parentId joins the live chain: a null-parent marker would become a
             // second root and hijack the leaf, corrupting the transcript.
+            // #235: id 必须唯一——硬编码共享 id ＋ SDK byId last-wins ＋ 标记恰为末行
+            // 时新消息 parent 记成共享 id ＝ 下次 open 回溯成环，整个会话打不开。
             const marker = {
                 type: "custom",
-                id: "pi-web-ui-compaction-pending",
+                id: makeCompactionMarkerId("pending"),
                 parentId: conv.session.sessionManager.getLeafId(),
                 timestamp: new Date().toISOString(),
                 customType: "pi-web-ui/compaction-pending",
@@ -4843,10 +5151,18 @@ export class ClientSession {
             const file = conv.session.sessionFile;
             if (!file || !existsSync(file))
                 return;
-            const id = "pi-web-ui-compaction-pending";
             const raw = readFileSync(file, "utf8");
             const lines = raw.split("\n");
-            const idx = lines.findIndex((line) => line.includes(`"${id}"`));
+            // #235：按 customType 定位（id 自本 fix 起唯一，老文件仍是硬编码 id，
+            // 按 id 找已不可靠）。取最后一个：重叠压缩时它属于本次，旧残留留给
+            // 下次 open 的 repair/notice 处理。
+            let idx = -1;
+            for (let i = lines.length - 1; i >= 0; i--) {
+                if (lines[i].includes(`"${COMPACTION_PENDING_TYPE}"`)) {
+                    idx = i;
+                    break;
+                }
+            }
             if (idx < 0)
                 return;
             // ponytail: full-file rewrite on compaction end — compactions are rare
@@ -4864,7 +5180,7 @@ export class ClientSession {
                 }
                 const done = {
                     type: "custom",
-                    id: "pi-web-ui-compaction-done",
+                    id: makeCompactionMarkerId("done"),
                     parentId,
                     timestamp: new Date().toISOString(),
                     customType: "pi-web-ui/compaction-done",
@@ -4894,15 +5210,80 @@ export class ClientSession {
                 return;
             const kept = raw.split("\n").filter((line) => !line.includes("pi-web-ui/compaction-pending"));
             writeFileSync(file, kept.join("\n"));
-            this.emit({
+            this.emitCompactionInterruptedNotice();
+        }
+        catch {
+            // Best-effort, same as the write path.
+        }
+    }
+    emitCompactionInterruptedNotice() {
+        this.emit({
+            type: "notice",
+            level: "warning",
+            text: "上次压缩上下文被服务端重启打断，未完成。可发送 /compact 重试。",
+            textEn: "The last context compaction was interrupted by a server restart and did not finish. Send /compact to retry.",
+        });
+    }
+    /** #235 修复产生的提示（调用方决定 emit 还是进 pendingNotices）。 */
+    transcriptRepairNotices(repair) {
+        const out = [];
+        if (repair.interrupted) {
+            out.push({
                 type: "notice",
                 level: "warning",
                 text: "上次压缩上下文被服务端重启打断，未完成。可发送 /compact 重试。",
                 textEn: "The last context compaction was interrupted by a server restart and did not finish. Send /compact to retry.",
             });
         }
+        if (repair.renamedIds > 0 || repair.rewiredParents > 0 || repair.cyclesBroken > 0) {
+            out.push({
+                type: "notice",
+                level: "warning",
+                text: `对话记录链损坏已自动修复（重复的压缩标记），原文件备份在 ${repair.backup ?? "同目录 .bak 文件"}。如内容异常可手动恢复。`,
+                textEn: `The conversation transcript had a corrupted parent chain (duplicate compaction markers) and was auto-repaired. The original file is backed up at ${repair.backup ?? "a .bak file next to it"}; restore it manually if anything looks off.`,
+            });
+        }
+        return out;
+    }
+    /**
+     * #235：已知路径先修后开（openConversation 走这条——单文件预扫描零负担）。
+     * 返回 null = 文件健康或无需处理；返回 repair = 修过，调用方弹提示。
+     */
+    repairTranscriptFileBeforeOpen(filePath) {
+        let repair = null;
+        try {
+            repair = repairSessionFile(filePath);
+        }
         catch {
-            // Best-effort, same as the write path.
+            return null;
+        }
+        if (!repair?.changed)
+            return null;
+        for (const n of this.transcriptRepairNotices(repair))
+            this.emit(n);
+        return repair;
+    }
+    /**
+     * #235：manager＋runtime 一起建，链损坏报错则修最近文件后重试一次。
+     * SessionManager.open 本身不走 parent 链（真正死循环的是 runtime 初始化里的
+     * getBranch），所以重试必须把两步都包进来；修完用全新 manager 重读。
+     */
+    async openManagerAndRuntime(makeManager, makeRuntime, locateFile) {
+        try {
+            const manager = makeManager();
+            const runtime = await makeRuntime(manager);
+            return { manager, runtime, repair: null };
+        }
+        catch (err) {
+            if (!looksLikeChainCorruption(err))
+                throw err;
+            const file = await locateFile().catch(() => undefined);
+            const repair = file ? repairSessionFile(file) : null;
+            if (!repair?.changed)
+                throw err;
+            const manager = makeManager();
+            const runtime = await makeRuntime(manager);
+            return { manager, runtime, repair };
         }
     }
     displaceActive() {
@@ -5997,6 +6378,9 @@ export class ClientSession {
                     });
                 }
             }
+            // #235：先修后开——坏转录到 open 后的 getBranch 会死循环，修完再读。
+            // 单文件预扫描，健康文件只多一次小读；修过即弹提示（含压缩被打断）。
+            this.repairTranscriptFileBeforeOpen(targetPath);
             const sessionManager = SessionManager.open(targetPath);
             const targetCwd = sessionManager.getCwd();
             const conversationId = this.nextConversationId();
@@ -6301,6 +6685,79 @@ export class ClientSession {
     async scmQuery(kind, reqId, arg) {
         return this.files.scmQuery(kind, reqId, arg);
     }
+    /**
+     * SCM「AI 生成提交信息」：用当前对话模型做一次 completeSimple 一次性补全
+     * （与视觉桥同一条通路）——不进对话上下文、不打断正在流式的回复。
+     * 恰好应答一次：任何失败都以 ok:false 的 scm_data（kind "commitmsg"）收尾，
+     * 前端按钮不会卡在转圈。
+     */
+    async scmGenCommitMessage(reqId) {
+        const lang = this.getLang();
+        const cwd = this.conv?.cwd ?? this.cwd;
+        const reply = (ok, extra) => {
+            this.emit({ type: "scm_data", reqId, kind: "commitmsg", ok, ...extra });
+        };
+        const fail = (err) => {
+            reply(false, { error: err instanceof Error ? err.message : String(err) });
+        };
+        try {
+            const runtime = this.runtime.services.modelRuntime;
+            const model = this.session?.model;
+            if (!model) {
+                throw new Error(pick(lang, "当前没有可用模型——先在顶栏选择一个模型再生成", "No model available — pick one in the top bar first", "scm.commitmsg.no.model"));
+            }
+            const ctx = await scmCommitContext(cwd, () => lang);
+            const input = buildCommitMsgInput(ctx, lang === "zh" ? "zh" : "en");
+            if (!input) {
+                throw new Error(pick(lang, "没有可描述的更改（工作区干净）", "Nothing to describe (working tree clean)", "scm.commitmsg.no.changes"));
+            }
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), SCM_COMMITMSG_TIMEOUT_MS);
+            // 提示词可配置（设置 → 提示词 → AI 提交信息）：追加/替换内置默认。
+            const commitSettings = this.settingsSvc.current;
+            const systemPrompt = buildCommitMsgPrompt(commitSettings.scmCommitMsgPromptMode === "replace" ? "replace" : "append", commitSettings.scmCommitMsgPrompt ?? "");
+            let msg;
+            try {
+                msg = await runtime.completeSimple(model, {
+                    systemPrompt,
+                    messages: [
+                        {
+                            role: "user",
+                            timestamp: Date.now(),
+                            content: [{ type: "text", text: input }],
+                        },
+                    ],
+                }, { signal: ac.signal, maxTokens: 400 });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+                throw new Error(msg.errorMessage ||
+                    pick(lang, `模型异常终止（${msg.stopReason}）`, `Model terminated abnormally (${msg.stopReason})`, "scm.commitmsg.model.terminated"));
+            }
+            const raw = msg.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text ?? "")
+                .join("\n");
+            const text = sanitizeCommitMessage(raw);
+            if (!text) {
+                throw new Error(pick(lang, "模型返回了空的提交信息", "The model returned an empty commit message", "scm.commitmsg.empty"));
+            }
+            reply(true, { text });
+        }
+        catch (err) {
+            if (isNotRepoError(err)) {
+                fail(new Error(pick(lang, "当前目录不是 Git 仓库", "Current directory is not a Git repository", "scm.commitmsg.not.repo")));
+                return;
+            }
+            if (err instanceof Error && /abort/i.test(`${err.name} ${err.message}`)) {
+                fail(new Error(pick(lang, `生成提交信息超时（${Math.round(SCM_COMMITMSG_TIMEOUT_MS / 1000)} 秒）`, `Commit-message generation timed out (${Math.round(SCM_COMMITMSG_TIMEOUT_MS / 1000)}s)`, "scm.commitmsg.timeout")));
+                return;
+            }
+            fail(err);
+        }
+    }
     /** Read a workspace file for the preview panel (size-capped, binary-safe). */
     async readFile(relPath) {
         return this.files.readFile(relPath);
@@ -6469,7 +6926,6 @@ export class ClientSession {
                 // default-opening it would strand the tab on a conversation it
                 // cannot use (the prompt guard refuses) with a stale leaf that
                 // forks history once the owner finishes. Land blank instead.
-                let sessionManager = SessionManager.continueRecent(abs);
                 let resumeSkipped = null;
                 // 无人在跑时不扫目录（首访切项目的常见情形零开销）。
                 if (this.hasStreamingElsewhere?.() ?? false) {
@@ -6478,7 +6934,6 @@ export class ClientSession {
                         const recent = infos[0]?.path ? resolve(infos[0].path) : undefined;
                         const owner = recent ? this.findSessionOwner?.(recent) : null;
                         if (owner?.isStreaming) {
-                            sessionManager = SessionManager.create(abs);
                             resumeSkipped = owner;
                         }
                     }
@@ -6488,11 +6943,18 @@ export class ClientSession {
                 }
                 const conversationId = this.nextConversationId();
                 const terminals = this.makeTerminalManager(conversationId, abs);
-                const newRuntime = await createAgentSessionRuntime(this.makeRuntimeFactory(terminals, undefined, conversationId), {
+                // #235：manager＋runtime 一起建，转录链损坏时修最近文件后重试一次
+                // （见 openManagerAndRuntime）。blank（别处在跑）是全新空会话，不会坏。
+                const opened = await this.openManagerAndRuntime(() => (resumeSkipped ? SessionManager.create(abs) : SessionManager.continueRecent(abs)), (m) => createAgentSessionRuntime(this.makeRuntimeFactory(terminals, undefined, conversationId), {
                     cwd: abs,
                     agentDir: this.agentDir,
-                    sessionManager,
-                });
+                    sessionManager: m,
+                }), async () => (await SessionManager.list(abs))[0]?.path);
+                const newRuntime = opened.runtime;
+                if (opened.repair) {
+                    for (const n of this.transcriptRepairNotices(opened.repair))
+                        this.emit(n);
+                }
                 const conv = this.makeConversation(newRuntime, conversationId, terminals);
                 this.convs.set(conv.id, conv);
                 this.activeId = conv.id;
@@ -6642,7 +7104,9 @@ export class ClientSession {
             return "";
         }
     }
-    /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5"). */
+    /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5").
+     *  失败时只发 notice 不抛错（UI 路径靠 notice 提示，见 cycleModel 等调用方）。
+     *  需要「失败即拒绝」的无头路径（插件/定时任务）用 switchModelOrThrow。 */
     async setModel(modelId) {
         try {
             const mr = this.runtime.services.modelRuntime;
@@ -6661,6 +7125,8 @@ export class ClientSession {
             // project (not only after a turn). This is what makes project switching
             // restore both the model and the provider key.
             this.rememberProjectModel(modelId);
+            // 换模型后按新模型的窗口重算软上限覆盖（按模型覆盖可能不同，issue #229）。
+            this.applyCompactionOverrides();
         }
         catch (err) {
             this.emit({
@@ -6672,6 +7138,25 @@ export class ClientSession {
         }
         this.flushSnapshot();
     }
+    /** 切换模型，失败时抛出（无头路径专用：插件 host.chat / 定时任务）。
+     *  setModel 为兼容 UI 把异常吞成 notice（面板要能看到原因、调用方是 fire-and-forget），
+     *  无头路径拿不到那个 notice，于是「模型 ID 打错/没配密钥」会变成静默按旧模型跑 ——
+     *  账单与效果都和用户预期不符。这里统一改成响亮失败。 */
+    async switchModelOrThrow(modelId) {
+        await this.setModel(modelId);
+        // 复核结果：读不到（无活跃对话）不阻断，读得到且不符才拒绝。
+        // 注意 session 是 getter，无活跃对话时会抛，不能用 `?.` 兜底。
+        let curId = "";
+        try {
+            const cur = this.session?.model;
+            curId = cur ? `${cur.provider}/${cur.id}` : "";
+        }
+        catch {
+            curId = "";
+        }
+        if (curId && curId !== modelId)
+            throw new Error(`切换模型失败（${modelId}），当前仍是 ${curId} —— 请检查模型 ID 与供应商密钥`);
+    }
     /** Set the thinking level for future turns. */
     setThinking(level) {
         try {
@@ -6762,6 +7247,42 @@ export class ClientSession {
         }
     }
 }
+/** issue #226：插件无头调用的工作目录校验（纯函数，可单测）。
+ *  存在性语义与定时任务一致（须存在且为目录，不默默跑错目录）；另在
+ *  Windows 下拒绝 SystemRoot 及其子树（如 C:\Windows\System32）——后台服务/
+ *  快捷方式启动时宿主 cwd 常飘到 system32，直接跑就是高危误操作。 */
+export function checkPluginCwd(cwd) {
+    const trimmed = String(cwd ?? "").trim();
+    if (!trimmed)
+        return { ok: false, error: "工作目录为空" };
+    let abs;
+    try {
+        abs =
+            process.platform === "win32" && /^[A-Za-z]:$/.test(trimmed) ? `${trimmed.toUpperCase()}${sep}` : resolve(trimmed);
+    }
+    catch {
+        return { ok: false, error: `工作目录非法：${trimmed}` };
+    }
+    try {
+        if (!statSync(abs).isDirectory())
+            throw new Error("not-a-dir");
+    }
+    catch {
+        return { ok: false, error: `目标项目不存在或不是目录：${trimmed}` };
+    }
+    if (process.platform === "win32") {
+        const sysRoot = (process.env.SystemRoot || process.env.windir || "C:\\Windows")
+            .replace(/\//g, "\\")
+            .replace(/\\+$/, "");
+        const norm = abs.replace(/\//g, "\\").replace(/\\+$/, "");
+        const low = norm.toLowerCase();
+        const rootLow = sysRoot.toLowerCase();
+        if (low === rootLow || low.startsWith(`${rootLow}\\`)) {
+            return { ok: false, error: `拒绝在系统目录执行：${abs}（请在插件设置里指定项目工作目录）` };
+        }
+    }
+    return { ok: true, abs };
+}
 export class AgentService {
     cwd;
     /** index.ts 注入：SDK 工具执行事件的插件转发钩子，attach 时拷贝到每个新会话。 */
@@ -6875,30 +7396,165 @@ export class AgentService {
     }
     /** issue #193：定时任务唤醒发起对话。逐个客户端找持有方，用 steer 语义投递
      *  （运行时插队、未跑时普通投递，不切用户当前对话）；都找不到回 ok:false，
-     *  调用方（index.ts executor）回落无头执行。quiesced 时直接拒绝。 */
-    async wakeConversation(id, text) {
-        if (!id || !text.trim())
+     *  调用方（index.ts executor）回落视口/无头执行。quiesced 时直接拒绝。
+     *  issue #226：成功时带回持有方 clientId（插件绑定网页会话时原样回执）。
+     *  issue #231：opts.sessionFile 是跨压缩/重启的稳定键 —— 优先按它认同一会话
+     *  （内存对话 id 重启即失效，压缩后同文件对话可能已换新 id，成功时带回**实际**
+     *  投递的 conversationId + sessionFile，调用方据此重绑定任务）；id 相位带 cwd
+     *  护栏（各客户端计数器都从 c1 开始，不校验会把报告投进无关项目）。压缩进行中
+     *  的持有方回 busy:true（调用方另寻视口兄弟，而不是当成“不在”静默转无头）。 */
+    async wakeConversation(id, text, opts) {
+        const wantFile = String(opts?.sessionFile ?? "").trim();
+        const wantCwd = String(opts?.cwd ?? "").trim();
+        if ((!id && !wantFile) || !text.trim())
             return { ok: false, error: "唤醒目标或文本为空" };
         if (this.quiesced)
             return { ok: false, error: "服务器正忙（quiesced），请稍后重试" };
-        for (const cs of this.clients.values()) {
+        const liveFile = (c) => {
             try {
-                const r = await cs.steerOwnConversation(id, text);
-                if (r) {
+                return String(c.session.sessionFile ?? "");
+            }
+            catch {
+                return "";
+            }
+        };
+        const flush = (cs) => {
+            try {
+                cs.flushSnapshot();
+            }
+            catch {
+                // 推送失败不影响已投递的唤醒
+            }
+        };
+        // 相位一：落盘会话文件（稳定键）。同文件可能在多处打开，取最近活跃者；
+        // 全部忙（压缩中）则报 busy，调用方去找视口兄弟。
+        if (wantFile) {
+            const hits = [];
+            for (const [clientId, cs] of this.clients) {
+                try {
+                    const conv = cs.resolveSchedulerTarget({ sessionFile: wantFile });
+                    if (conv)
+                        hits.push({ cs, clientId, conv });
+                }
+                catch {
+                    // 单客户端坏了继续找下一个
+                }
+            }
+            hits.sort((a, b) => b.conv.lastActiveAt - a.conv.lastActiveAt);
+            let busyError;
+            for (const h of hits) {
+                try {
+                    const r = await h.cs.trySteerScheduler(h.conv, text);
+                    if (r.ok) {
+                        flush(h.cs);
+                        return { ok: true, conversationId: h.conv.id, sessionFile: liveFile(h.conv), clientId: h.clientId };
+                    }
+                    if (r.busy)
+                        busyError = r.error;
+                    // 非忙失败（投递异常）试下一个同文件持有方
+                }
+                catch {
+                    // 单客户端坏了继续找下一个
+                }
+            }
+            if (hits.length > 0) {
+                if (busyError)
+                    return { ok: false, busy: true, error: busyError };
+                // 同文件持有方都在但都投递失败 —— id 相位大概率指向同一批，无需再试
+                return { ok: false, error: "目标对话投递失败（持有方异常）" };
+            }
+            // 无同文件持有方 —— 老任务只有 id，继续相位二
+        }
+        // 相位二：内存对话 id（易失键，必须配 cwd 护栏防跨项目串台）。
+        if (id) {
+            const hits = [];
+            for (const [clientId, cs] of this.clients) {
+                try {
+                    const conv = cs.resolveSchedulerTarget({
+                        conversationId: id,
+                        ...(wantCwd ? { cwd: wantCwd } : {}),
+                    });
+                    if (conv)
+                        hits.push({ cs, clientId, conv });
+                }
+                catch {
+                    // 单客户端坏了继续找下一个
+                }
+            }
+            hits.sort((a, b) => b.conv.lastActiveAt - a.conv.lastActiveAt);
+            let busyError;
+            for (const h of hits) {
+                try {
+                    const r = await h.cs.trySteerScheduler(h.conv, text);
+                    if (r.ok) {
+                        flush(h.cs);
+                        return { ok: true, conversationId: h.conv.id, sessionFile: liveFile(h.conv), clientId: h.clientId };
+                    }
+                    if (r.busy)
+                        busyError = r.error;
+                }
+                catch {
+                    // 单客户端坏了继续找下一个
+                }
+            }
+            if (busyError)
+                return { ok: false, busy: true, error: busyError };
+        }
+        return { ok: false, error: "目标对话不在运行中（已关闭或服务重启过）" };
+    }
+    /** issue #231：同项目视口回退 —— 原绑定对话不在时，把唤醒投给该项目最近活跃
+     *  的对话（用户当前正看着的面），而不是静默转无头。excludeIds 跳过已知忙对话；
+     *  候选全部忙回 busy:true；无候选回 ok:false。成功带回实际投递方（调用方重绑定）。 */
+    async wakeViewportInCwd(cwd, text, excludeIds) {
+        const want = String(cwd ?? "").trim();
+        if (!want || !text.trim())
+            return { ok: false, error: "回退目标或文本为空" };
+        if (this.quiesced)
+            return { ok: false, error: "服务器正忙（quiesced），请稍后重试" };
+        const cands = [];
+        for (const [clientId, cs] of this.clients) {
+            try {
+                const conv = cs.findViewportInCwd(want, excludeIds);
+                if (conv)
+                    cands.push({ cs, clientId, conv });
+            }
+            catch {
+                // 单客户端坏了继续找下一个
+            }
+        }
+        cands.sort((a, b) => b.conv.lastActiveAt - a.conv.lastActiveAt);
+        if (cands.length === 0)
+            return { ok: false, error: "同项目无存活对话" };
+        let busyError;
+        for (const c of cands) {
+            try {
+                const r = await c.cs.trySteerScheduler(c.conv, text);
+                if (r.ok) {
                     try {
-                        cs.flushSnapshot();
+                        c.cs.flushSnapshot();
                     }
                     catch {
                         // 推送失败不影响已投递的唤醒
                     }
-                    return { ok: true, conversationId: id };
+                    let f = "";
+                    try {
+                        f = String(c.conv.session.sessionFile ?? "");
+                    }
+                    catch {
+                        f = "";
+                    }
+                    return { ok: true, conversationId: c.conv.id, sessionFile: f, clientId: c.clientId };
                 }
+                if (r.busy)
+                    busyError = r.error;
             }
             catch {
                 // 单客户端坏了继续找下一个
             }
         }
-        return { ok: false, error: "目标对话不在运行中（已关闭或服务重启过）" };
+        if (busyError)
+            return { ok: false, busy: true, error: busyError };
+        return { ok: false, error: "同项目对话投递失败" };
     }
     /** issue #145：别处在某 cwd 下正在跑的对话（同项目并行感知用，不含请求方）。 */
     listProjectRunners(cwd, excludeClientId) {
@@ -6985,7 +7641,11 @@ export class AgentService {
      *  快照/notice 发了即丢，不攒内存。fire-and-forget：prompt 投递即返回，
      *  运行结果经 onRunEvent(run_end) 按 conversationId 关联。
      *  v1 语义：与该服务 cwd 下最近会话共享（单用户视角连续）；peer 名由插件
-     *  拼进文本前缀，per-peer 会话隔离以后再加。 */
+     *  拼进文本前缀，per-peer 会话隔离以后再加。
+     *  issue #226：对齐定时任务的四件套——conversationId 命中时走 steer 语义
+     *  投递（网页端实时可见，miss 则回落无头）；cwd 显式 pin 住（不存在/系统
+     *  目录即拒绝，不默默跑错目录）；model/thinkingLevel 投递前应用（失败即
+     *  拒绝，不回落，避免账单/效果与预期不符）。 */
     async chatFromPlugin(pluginId, req) {
         const safe = String(pluginId ?? "plugin").replace(/[^A-Za-z0-9_-]/g, "") || "plugin";
         const acct = String(req?.accountId ?? "default").replace(/[^A-Za-z0-9_-]/g, "") || "default";
@@ -6995,10 +7655,52 @@ export class AgentService {
             throw new Error("chatFromPlugin: text 为空");
         if (this.quiesced)
             throw new QuiesceRejectedError("插件无头调用被拒绝，请等服务器恢复后重试");
+        // 1. 绑定已有会话：steer 语义投递，网页端实时可见（微信当远程遥控器用）。
+        // miss/已回收时不抛错，回落无头伪客户端（浏览器关着时微信照常可用）。
+        const target = String(req?.conversationId ?? "").trim();
+        if (target) {
+            const w = await this.wakeConversation(target, text);
+            if (w.ok)
+                return { conversationId: target, clientId: w.clientId ?? clientId };
+        }
+        // 2. 工作空间：不传回落伪客户端当前目录；传了必须存在且非系统目录。
+        const cwdReq = String(req?.cwd ?? "").trim();
+        let cwdAbs = "";
+        if (cwdReq) {
+            const chk = checkPluginCwd(cwdReq);
+            if (!chk.ok)
+                throw new Error(`chatFromPlugin: ${chk.error}`);
+            cwdAbs = chk.abs ?? "";
+        }
         const cs = await this.attach(clientId, () => { });
-        const before = cs.readConversationForPlugins()?.conversationId ?? "";
+        try {
+            if (cwdAbs && cs.cwd !== cwdAbs)
+                await cs.setCwd(cwdAbs);
+        }
+        catch (err) {
+            throw new Error(`chatFromPlugin: 切换工作目录失败（${cwdAbs}）：${err.message}`);
+        }
+        const model = String(req?.model ?? "").trim();
+        if (model) {
+            try {
+                await cs.switchModelOrThrow(model);
+            }
+            catch (err) {
+                throw new Error(`chatFromPlugin: 切换模型失败（${model}）：${err.message}`);
+            }
+        }
+        const thinking = String(req?.thinkingLevel ?? "").trim();
+        if (thinking) {
+            try {
+                cs.setThinking(thinking);
+            }
+            catch (err) {
+                throw new Error(`chatFromPlugin: 切换思考强度失败（${thinking}）：${err.message}`);
+            }
+        }
+        const conversationId = cs.readConversationForPlugins()?.conversationId ?? "";
         void cs.prompt(text);
-        return { conversationId: before, clientId };
+        return { conversationId, clientId };
     }
     /** 内置定时任务的无头执行（issue #184，server/scheduler-tasks.ts 的 executor）。
      *  每个任务独立伪客户端 `scheduler:<taskId>`（专属会话连续、无浏览器也能跑）；
@@ -7030,7 +7732,7 @@ export class AgentService {
             const model = String(task.model ?? "").trim();
             if (model) {
                 try {
-                    await cs.setModel(model);
+                    await cs.switchModelOrThrow(model);
                 }
                 catch (err) {
                     return { ok: false, error: `切换模型失败（${model}）：${err.message}` };