pi-web-ui 0.96.1 → 0.98.0

package/dist/server/approval-rules.js

@@ -29,8 +29,9 @@
  *      老用户删掉的内置规则不会在重启后复活；发版新增的内置规则可安全合并进老用户文件）。
  *    - 内存缓存 + 文件 mtime 感知，支持直接编辑 JSON 文件热生效。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 /**
  * 跨平台判定 target 路径是否严格位于 root 目录内部或就是 root 本身。
  * 针对 Windows 盘符大小写不敏感及正反斜杠统一进行规范化，防止 .. 路径穿越逃逸。
@@ -438,10 +439,7 @@ export class ApprovalRulesStore {
     }
     saveSeeded(names) {
         try {
-            mkdirSync(dirname(this.seededPath()), { recursive: true });
-            const tmp = `${this.seededPath()}.${process.pid}.tmp`;
-            writeFileSync(tmp, JSON.stringify([...names].sort(), null, 2) + "\n");
-            renameSync(tmp, this.seededPath());
+            writeJsonAtomicSync(this.seededPath(), [...names].sort());
         }
         catch {
             // best effort
@@ -492,10 +490,7 @@ export class ApprovalRulesStore {
     }
     persist() {
         try {
-            mkdirSync(dirname(this.filePath), { recursive: true });
-            const tmp = `${this.filePath}.${process.pid}.tmp`;
-            writeFileSync(tmp, JSON.stringify(this.rules ?? [], null, 2) + "\n");
-            renameSync(tmp, this.filePath);
+            writeJsonAtomicSync(this.filePath, this.rules ?? []);
             try {
                 this.lastMtime = statSync(this.filePath).mtimeMs;
             }

package/dist/server/atomic-file.js

@@ -0,0 +1,40 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+/**
+ * 跨平台安全原子写文件：先写临时文件再 renameSync，进程崩溃不留半截文件。
+ * - tmp 文件位于目标文件同目录下（保证处于同物理卷，rename 为原子操作）；
+ * - tmp 文件名携带 pid + 时间戳 + 随机串，防止同机多进程互踩；
+ * - Windows 下目标文件若被外部临时占用（杀软/文本编辑器锁），rename 失败后退回原地写兜底；
+ * - 确保无论成功失败，临时文件在 finally 中及时清理，杜绝残留 .tmp 垃圾文件。
+ */
+export function writeAtomicSync(file, data) {
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const suffix = `${process.pid}.${Date.now()}.${randomUUID().slice(0, 8)}.tmp`;
+    const tmp = `${file}.${suffix}`;
+    try {
+        writeFileSync(tmp, data);
+        try {
+            renameSync(tmp, file);
+        }
+        catch {
+            writeFileSync(file, data);
+        }
+    }
+    finally {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+/**
+ * 原子写 JSON 辅助函数（默认 2 空格缩进 + 末尾换行）。
+ */
+export function writeJsonAtomicSync(file, data, indent = 2) {
+    const text = JSON.stringify(data, null, indent) + "\n";
+    writeAtomicSync(file, text);
+}

package/dist/server/attachments.js

@@ -1,3 +1,4 @@
+import { formatTextQuote, readTextQuote } from "./text-quote.js";
 import { sniffImageMime } from "./text-sniff.js";
 import { saveUpload, uploadsRoot } from "./uploads.js";
 import { isAbsoluteWirePath, wireToAbs } from "./files-service.js";
@@ -230,6 +231,27 @@ export async function buildAttachmentMessages(ctx, attachments) {
         }
     }
     for (const [idx, att] of attachments.entries()) {
+        if (att.mode === "quote") {
+            const quote = readTextQuote(att.quote);
+            if (!quote) {
+                ctx.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: "引用内容无效，请重新选择文字",
+                    textEn: "Select the text again to add a quote.",
+                });
+                continue;
+            }
+            out.push({
+                message: {
+                    customType: "file",
+                    content: [{ type: "text", text: formatTextQuote(quote) }],
+                    display: true,
+                    details: { mode: "quote", quote },
+                },
+            });
+            continue;
+        }
         // Quoted conversation (left-panel right-click / global-search quote):
         // `path` is unused — the reference travels in conversationId (running
         // conversation, incl. subagents) or sessionPath (history transcript).

package/dist/server/claim-store.js

@@ -19,8 +19,9 @@
 // （认领时按 conv cwd resolve），比对时触碰路径同样 resolve 后比较 —— 后缀
 // 模糊匹配继续禁用（假阳性比漏报更糟，见 conversation-touches 文件头）。
 // ---------------------------------------------------------------------------
-import { mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { readFileSync, statSync, unlinkSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 import { normalizeTouchPath, unionTouchLists } from "./conversation-touches.js";
 /** 认领默认 TTL：30 分钟（每次发 prompt 心跳续期，对话关闭时释放）。 */
 export const CLAIM_TTL_MS = 30 * 60 * 1000;
@@ -211,11 +212,7 @@ export class ClaimStore {
     }
     save() {
         try {
-            mkdirSync(dirname(this.file), { recursive: true });
-            // tmp 带进程唯一后缀：同机多实例（多 worktree/多开）写同一文件不互踩
-            const tmp = `${this.file}.${process.pid}.tmp`;
-            writeFileSync(tmp, JSON.stringify({ version: CLAIMS_FILE_VERSION, tables: Object.fromEntries(this.tables) }));
-            renameSync(tmp, this.file);
+            writeJsonAtomicSync(this.file, { version: CLAIMS_FILE_VERSION, tables: Object.fromEntries(this.tables) });
         }
         catch {
             // 持久化故障绝不能弄崩 server（内存表照常用）
@@ -281,10 +278,7 @@ export async function mergeTouchSidecar(sessionFile, fresh) {
         return;
     try {
         const merged = unionTouchLists(readTouchSidecar(sessionFile) ?? [], fresh).slice(0, SIDECAR_MAX_ENTRIES);
-        // tmp 带进程唯一后缀（同 client-state.ts 惯例）：避免并发进程互踩
-        const tmp = `${sidecarPath(sessionFile)}.${process.pid}.tmp`;
-        writeFileSync(tmp, JSON.stringify({ version: 1, updatedAt: Date.now(), files: merged }));
-        renameSync(tmp, sidecarPath(sessionFile));
+        writeJsonAtomicSync(sidecarPath(sessionFile), { version: 1, updatedAt: Date.now(), files: merged });
     }
     catch {
         // sidecar 只是加速+防压缩丢失，写坏了下次重算

package/dist/server/client-state.js

@@ -6,10 +6,13 @@
  *
  * 从 agent-service.ts 抽出，行为保持不变。
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 import { normalizeSoftCapByModel, normalizeSoftCapTokens } from "./soft-cap.js";
 import { deriveLegacy, legacyToDisabled, normalizeDisabledAgentTools } from "./tool-manager.js";
+import { UI_SLOTS } from "./plugins.js";
 /** 大模型 API 出错自动重试次数的默认值（SDK 默认 3）。 */
 export const DEFAULT_RETRY_MAX_ATTEMPTS = 6;
 /** 工具执行看门狗超时的默认值（默认 20 分钟；环境变量 PI_WEB_TOOL_TIMEOUT_MS 覆盖）。 */
@@ -168,6 +171,35 @@ export function normalizeUiLayout(v) {
     }
     // 顶栏按钮文字总开关：只收布尔值（缺席 = 显示，兼容老存档）。
     const topbarText = typeof o.topbarText === "boolean" ? o.topbarText : undefined;
+    // 侧边图标停靠栏形态：只收布尔值（缺席 = 贴边槽位）。
+    const sideDockFloat = typeof o.sideDockFloat === "boolean" ? o.sideDockFloat : undefined;
+    // 用户自定义槽位/位置：只收合法 slot 字符串
+    let slots;
+    if (o.slots && typeof o.slots === "object" && !Array.isArray(o.slots)) {
+        slots = {};
+        for (const [k, val] of Object.entries(o.slots).slice(0, 200)) {
+            if (k.length > 0 && k.length <= 96 && typeof val === "string" && UI_SLOTS.has(val)) {
+                slots[k] = val;
+            }
+        }
+        if (Object.keys(slots).length === 0)
+            slots = undefined;
+    }
+    // 品牌槽位同样折进 host:brand
+    if (slots && ("host:brand-logo" in slots || "host:brand-name" in slots)) {
+        const out = {};
+        for (const [k, val] of Object.entries(slots)) {
+            if (k === "host:brand-logo" || k === "host:brand-name")
+                continue;
+            out[k] = val;
+        }
+        if (out[BRAND_NEW] === undefined) {
+            const picked = slots["host:brand-logo"] ?? slots["host:brand-name"];
+            if (picked !== undefined)
+                out[BRAND_NEW] = picked;
+        }
+        slots = Object.keys(out).length ? out : undefined;
+    }
     return {
         ...(hidden ? { hidden } : {}),
         ...(shown ? { shown } : {}),
@@ -176,6 +208,8 @@ export function normalizeUiLayout(v) {
         ...(align ? { align } : {}),
         ...(labels ? { labels } : {}),
         ...(topbarText !== undefined ? { topbarText } : {}),
+        ...(sideDockFloat !== undefined ? { sideDockFloat } : {}),
+        ...(slots ? { slots } : {}),
     };
 }
 /** 归一化技能名单：字符串数组原样过滤；其他（含旧 bool 开关）回落空数组。 */
@@ -249,7 +283,7 @@ export function normalizeWorkspaceRoots(v) {
         if (!p || !isAbsolute(p))
             continue;
         const abs = resolve(p);
-        const key = process.platform === "win32" ? abs.toLowerCase() : abs;
+        const key = normalizePathKey(abs);
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -269,6 +303,17 @@ export function normalizePathKey(p) {
         return process.platform === "win32" ? p.toLowerCase() : p;
     }
 }
+/** 死 clientId 状态的保留期（issue #441）：距最近活跃超过该时长的 per-client 键在
+ *  加载/定期扫描时淘汰。取 30 天——clientId 存 sessionStorage，每个标签页每次会话
+ *  都生成新 id，远超 30 天才回来的标签页实际等同全新会话，误伤概率可忽略。 */
+export const CLIENT_STATE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** per-client 键数上限（issue #441）：活跃客户端数超过该值时按最近活跃保留前 50、
+ *  淘汰最旧的。兜底上限：完全无时间戳可推断的存量键不按年龄淘汰，靠它保证
+ *  client-state.json 不随时间无界膨胀。 */
+export const MAX_TRACKED_CLIENTS = 50;
+/** 死键清理扫描的最小间隔：load() 是所有读写的高频入口，扫描按 1 小时节流，
+ *  首次加载必扫。 */
+export const CLIENT_STATE_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
 /**
  * Persists which workspace each browser client last used + which workspaces it
  * has opened, so a server restart / page reload restores the same project and
@@ -278,6 +323,8 @@ export function normalizePathKey(p) {
 export class ClientStateStore {
     filePath;
     cache = null;
+    /** 上次死键清理扫描的时间戳（epoch ms；0 = 尚未扫过，首次 load 必扫）。 */
+    lastSweepAt = 0;
     constructor(filePath) {
         this.filePath = filePath;
     }
@@ -294,8 +341,10 @@ export class ClientStateStore {
         return dirname(this.filePath);
     }
     load() {
-        if (this.cache)
+        if (this.cache) {
+            this.sweepStaleClientsIfNeeded();
             return this.cache;
+        }
         try {
             const parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
             this.cache = parsed && typeof parsed === "object" ? parsed : {};
@@ -320,20 +369,85 @@ export class ClientStateStore {
                 }
             }
         }
-        if (migrated) {
+        // 死键清理（issue #441）：在墓碑迁移之后做——各 client 的墓碑已先并入全局键，
+        // 淘汰死 client 不会丢墓碑；合并一次 save 落盘（迁移和淘汰只发生一次时也只写一遍）。
+        this.lastSweepAt = Date.now();
+        const evicted = this.sweepDeadClients();
+        if (migrated || evicted > 0) {
             this.save();
         }
         return this.cache;
     }
+    /** 死键清理的节流入口：首次 load 必扫，之后按 CLIENT_STATE_SWEEP_INTERVAL_MS 节流。 */
+    sweepStaleClientsIfNeeded() {
+        if (Date.now() - this.lastSweepAt < CLIENT_STATE_SWEEP_INTERVAL_MS)
+            return;
+        this.lastSweepAt = Date.now();
+        if (this.sweepDeadClients() > 0)
+            this.save();
+    }
+    /** 淘汰长期不活跃的 per-client 状态（issue #441）。
+     *
+     * 背景：clientId 存 sessionStorage——每个浏览器标签页每次会话都生成新 id，服务端
+     * 却为每个见过的 id 永久建键（projects / workspaceRoots / projectProviderKeys /
+     * projectModels…），client-state.json 随死键线性膨胀，save() 的同步
+     * JSON.stringify + writeFileSync 成本也随之线性增长。
+     *
+     * 策略（保守，只动内存态，下次任意 save 自然落盘；绝不直接删文件）：
+     * - 距最近活跃超过 CLIENT_STATE_RETENTION_MS（30 天）的 clientId 淘汰。活跃时间
+     *   优先取显式 lastActive（写路径 touchClient 维护），旧存档回退按
+     *   max(projects[].lastUsed, interrupted[].at) 推断；推断值写回内存态，随下次
+     *   save 落盘。完全无时间戳可推断的（无法判定活跃度）不按年龄淘汰，仅受数量上限约束。
+     * - 淘汰后仍超过 MAX_TRACKED_CLIENTS（50）时按最近活跃保留前 50，其余淘汰
+     *   （无时间戳的排最旧优先淘汰）。
+     * - 全局键 __settings__ 永不淘汰：设置面板 config / 预设 / 墓碑都在它下面，
+     *   与任何 clientId 无关。
+     *
+     * 返回淘汰的键数（0 = 无变化，调用方无需为此 save）。 */
+    sweepDeadClients() {
+        const all = this.cache;
+        if (!all)
+            return 0;
+        const now = Date.now();
+        const dead = new Set();
+        const activity = new Map();
+        for (const [id, state] of Object.entries(all)) {
+            if (id === ClientStateStore.GLOBAL_SETTINGS_KEY)
+                continue;
+            let at = state.lastActive ?? 0;
+            if (at <= 0) {
+                for (const p of state.projects ?? [])
+                    if (p.lastUsed > at)
+                        at = p.lastUsed;
+                for (const i of state.interrupted ?? [])
+                    if (i.at > at)
+                        at = i.at;
+                if (at > 0)
+                    state.lastActive = at;
+            }
+            activity.set(id, at);
+            if (at > 0 && now - at > CLIENT_STATE_RETENTION_MS)
+                dead.add(id);
+        }
+        if (activity.size - dead.size > MAX_TRACKED_CLIENTS) {
+            const survivors = [...activity.entries()].filter(([id]) => !dead.has(id)).sort((a, b) => b[1] - a[1]);
+            for (const [id] of survivors.slice(MAX_TRACKED_CLIENTS))
+                dead.add(id);
+        }
+        for (const id of dead)
+            delete all[id];
+        return dead.size;
+    }
+    /** 打点客户端活跃时间（内存态，随任意后续 save 落盘；不主动触发 save）。
+     *  仅在 per-client 写路径上调用，键尚不存在时是 no-op（创建方随后 ??= 补上）。 */
+    touchClient(all, clientId) {
+        const state = all[clientId];
+        if (state)
+            state.lastActive = Date.now();
+    }
     save() {
         try {
-            mkdirSync(dirname(this.filePath), { recursive: true });
-            // Atomic write (tmp + rename): a crash mid-write must never leave a
-            // half-written JSON — that would wipe ALL persisted state (recent
-            // projects / presets / settings / goal prefs) on next load.
-            const tmp = `${this.filePath}.${process.pid}.tmp`;
-            writeFileSync(tmp, JSON.stringify(this.cache, null, 2) + "\n");
-            renameSync(tmp, this.filePath);
+            writeJsonAtomicSync(this.filePath, this.cache);
         }
         catch {
             // best effort
@@ -346,6 +460,7 @@ export class ClientStateStore {
     remember(clientId, cwd) {
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         state.lastCwd = cwd;
         const now = Date.now();
         const targetKey = normalizePathKey(cwd);
@@ -353,6 +468,12 @@ export class ClientStateStore {
             { path: cwd, lastUsed: now },
             ...state.projects.filter((p) => normalizePathKey(p.path) !== targetKey),
         ].slice(0, 30);
+        // Also persist in global settings so new tabs and sessions inherit it immediately
+        const globalState = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        globalState.projects = [
+            { path: cwd, lastUsed: now },
+            ...(globalState.projects ?? []).filter((p) => normalizePathKey(p.path) !== targetKey),
+        ].slice(0, 50);
         // Opening the workspace again clears its removal tombstone across all clients and global settings.
         for (const cState of Object.values(all)) {
             if (cState.removedProjects?.length) {
@@ -371,6 +492,7 @@ export class ClientStateStore {
         const all = this.load();
         const targetKey = normalizePathKey(cwd);
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         state.projects = state.projects.filter((p) => normalizePathKey(p.path) !== targetKey);
         if (state.lastCwd && normalizePathKey(state.lastCwd) === targetKey)
             delete state.lastCwd;
@@ -409,6 +531,90 @@ export class ClientStateStore {
         }
         return result;
     }
+    /**
+     * Get recent projects merged across the client's own history, global settings,
+     * and other clients in this store, filtering out tombstoned paths and non-existent paths.
+     *
+     * 性能（issue #441）：先按 lastUsed 排序截断到 30 条，再对候选做存活性探测——
+     * 旧实现先对全部合并路径逐个同步 existsSync 再截断，Windows 上已断连的网络
+     * 驱动器单次 existsSync 可阻塞数秒且直接跑在事件循环上，会把整个服务界面
+     * （所有客户端 WS/HTTP）冻结。截断后探测把单次探测次数封顶 30；探测改异步
+     * fsPromises.access（调用链本就是 async），不再阻塞事件循环。代价是前 30 名
+     * 里有失效路径时不再回补更旧的项目（列表可能短于 30），属可接受的取舍。
+     */
+    async getRecentProjects(clientId) {
+        const all = this.load();
+        const removedKeys = new Set(this.getRemovedProjects(clientId).map(normalizePathKey));
+        const map = new Map();
+        const merge = (list) => {
+            if (!list)
+                return;
+            for (const p of list) {
+                if (!p?.path)
+                    continue;
+                const key = normalizePathKey(p.path);
+                if (removedKeys.has(key))
+                    continue;
+                const existing = map.get(key);
+                if (!existing || p.lastUsed > existing.lastUsed) {
+                    map.set(key, { path: p.path, lastUsed: p.lastUsed });
+                }
+            }
+        };
+        // Merge client's own projects first, then global settings, then all other clients
+        merge(all[clientId]?.projects);
+        merge(all[ClientStateStore.GLOBAL_SETTINGS_KEY]?.projects);
+        for (const [id, cState] of Object.entries(all)) {
+            if (id !== clientId && id !== ClientStateStore.GLOBAL_SETTINGS_KEY) {
+                merge(cState.projects);
+            }
+        }
+        // 先截断后探测：探测次数 ≤ 30，且并发执行（Promise.allSettled 吸收单点失败）。
+        const candidates = [...map.values()].sort((a, b) => b.lastUsed - a.lastUsed).slice(0, 30);
+        const probes = await Promise.allSettled(candidates.map((p) => this.pathExists(p.path)));
+        return candidates.filter((_, i) => {
+            const probe = probes[i];
+            return probe?.status === "fulfilled" && probe.value;
+        });
+    }
+    /** 单条路径的存活性探测（issue #441）：异步 access，绝不阻塞事件循环。
+     *  独立成 protected 方法便于单测用子类覆写做计数探针。 */
+    async pathExists(path) {
+        return fsPromises.access(path).then(() => true, () => false);
+    }
+    /** Record discovered projects into global settings cache (without clobbering tombstones). */
+    mergeDiscoveredProjects(projects) {
+        if (!projects.length)
+            return;
+        const all = this.load();
+        const globalState = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        const removedKeys = new Set((globalState.removedProjects ?? []).map(normalizePathKey));
+        const map = new Map();
+        for (const p of globalState.projects ?? []) {
+            const key = normalizePathKey(p.path);
+            if (!removedKeys.has(key))
+                map.set(key, p);
+        }
+        let changed = false;
+        for (const p of projects) {
+            const key = normalizePathKey(p.path);
+            if (removedKeys.has(key))
+                continue;
+            const existing = map.get(key);
+            if (!existing) {
+                map.set(key, p);
+                changed = true;
+            }
+            else if (p.lastUsed > existing.lastUsed) {
+                existing.lastUsed = p.lastUsed;
+                changed = true;
+            }
+        }
+        if (changed) {
+            globalState.projects = [...map.values()].sort((a, b) => b.lastUsed - a.lastUsed).slice(0, 50);
+            this.save();
+        }
+    }
     /** Last-used goal/review prefs for a client, or undefined if never set. */
     getGoalPrefs(clientId) {
         const s = this.load()[clientId];
@@ -418,6 +624,7 @@ export class ClientStateStore {
             reviewModel: s.goalPrefs.reviewModel ?? null,
             maxRounds: s.goalPrefs.maxRounds ?? 0,
             locked: s.goalPrefs.locked ?? true,
+            execModel: s.goalPrefs.execModel ?? null,
         };
     }
     /** 某项目当前的额外工作区根（空数组 = 单根）。 */
@@ -428,6 +635,7 @@ export class ClientStateStore {
     saveWorkspaceRoots(clientId, cwd, roots) {
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         const next = normalizeWorkspaceRoots(roots);
         if (next.length === 0) {
             if (state.workspaceRoots) {
@@ -448,6 +656,7 @@ export class ClientStateStore {
             return;
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         if (state.locale === code)
             return;
         state.locale = code;
@@ -457,10 +666,12 @@ export class ClientStateStore {
     saveGoalPrefs(clientId, prefs) {
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         state.goalPrefs = {
             reviewModel: prefs?.reviewModel ?? null,
             maxRounds: prefs?.maxRounds ?? 0,
             locked: prefs?.locked ?? true,
+            execModel: prefs?.execModel ?? null,
         };
         this.save();
     }
@@ -471,6 +682,7 @@ export class ClientStateStore {
             return;
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         state.interrupted = list.slice(0, 8);
         this.save();
     }
@@ -481,6 +693,7 @@ export class ClientStateStore {
         const state = all[clientId];
         const list = state?.interrupted;
         if (list?.length && state) {
+            this.touchClient(all, clientId);
             delete state.interrupted;
             this.save();
         }
@@ -542,6 +755,8 @@ export class ClientStateStore {
             visionBridgePrompt: stored?.visionBridgePrompt ?? "",
             scmCommitMsgPromptMode: stored?.scmCommitMsgPromptMode === "replace" ? "replace" : "append",
             scmCommitMsgPrompt: stored?.scmCommitMsgPrompt ?? "",
+            planModePromptMode: stored?.planModePromptMode === "replace" ? "replace" : "append",
+            planModePrompt: stored?.planModePrompt ?? "",
             subagentDefaultModel: stored?.subagentDefaultModel ?? null,
             retryMaxAttempts: normalizeRetryMaxAttempts(stored?.retryMaxAttempts),
             softCapTokens: normalizeSoftCapTokens(stored?.softCapTokens),
@@ -606,6 +821,8 @@ export class ClientStateStore {
             visionBridgePrompt: settings.visionBridgePrompt ?? cur.visionBridgePrompt ?? "",
             scmCommitMsgPromptMode: settings.scmCommitMsgPromptMode ?? cur.scmCommitMsgPromptMode ?? "append",
             scmCommitMsgPrompt: settings.scmCommitMsgPrompt ?? cur.scmCommitMsgPrompt ?? "",
+            planModePromptMode: settings.planModePromptMode ?? cur.planModePromptMode ?? "append",
+            planModePrompt: settings.planModePrompt ?? cur.planModePrompt ?? "",
             reviewPrompt: settings.reviewPrompt ?? cur.reviewPrompt ?? "",
             reviewDisabledSkills: settings.reviewDisabledSkills ?? cur.reviewDisabledSkills ?? [],
             disabledPlugins: settings.disabledPlugins ?? cur.disabledPlugins ?? [],
@@ -667,6 +884,7 @@ export class ClientStateStore {
         const gMap = (globalState.projectProviderKeys ??= {});
         (gMap[cwd] ??= {})[provider] = keyName;
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         const map = (state.projectProviderKeys ??= {});
         const inner = (map[cwd] ??= {});
         inner[provider] = keyName;
@@ -783,6 +1001,7 @@ export class ClientStateStore {
         (globalState.projectModels ??= {})[cwd] = modelId;
         // 同时写入本客户端
         const state = (all[clientId] ??= { projects: [] });
+        this.touchClient(all, clientId);
         (state.projectModels ??= {})[cwd] = modelId;
         this.save();
     }
@@ -836,6 +1055,72 @@ export class ClientStateStore {
         (state.defaultProviderKeys ??= {})[provider] = keyName;
         this.save();
     }
+    /** 获取某项目已钉住的会话文件路径列表。 */
+    getPinnedSessions(cwd) {
+        const normCwd = normalizePathKey(cwd);
+        const map = this.load()[ClientStateStore.GLOBAL_SETTINGS_KEY]?.pinnedSessions;
+        return map?.[normCwd] ?? [];
+    }
+    /** 钉住 / 取消钉住某个会话文件。 */
+    setSessionPinned(cwd, sessionPath, pinned) {
+        const normCwd = normalizePathKey(cwd);
+        const normPath = normalizePathKey(sessionPath);
+        const absPath = resolve(sessionPath);
+        const all = this.load();
+        const state = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        const map = (state.pinnedSessions ??= {});
+        const list = map[normCwd] ?? [];
+        const filtered = list.filter((p) => normalizePathKey(p) !== normPath);
+        if (pinned) {
+            filtered.push(absPath);
+            map[normCwd] = filtered;
+        }
+        else {
+            if (filtered.length > 0) {
+                map[normCwd] = filtered;
+            }
+            else {
+                delete map[normCwd];
+            }
+        }
+        if (Object.keys(map).length === 0) {
+            delete state.pinnedSessions;
+        }
+        this.save();
+    }
+    /** 检查某个会话文件是否已被钉住。 */
+    isSessionPinned(cwd, sessionPath) {
+        const list = this.getPinnedSessions(cwd);
+        const norm = normalizePathKey(sessionPath);
+        return list.some((p) => normalizePathKey(p) === norm);
+    }
+    /** 会话文件被删除时清理钉住记录。 */
+    cleanPinnedSession(sessionPath) {
+        const norm = normalizePathKey(sessionPath);
+        const all = this.load();
+        const map = all[ClientStateStore.GLOBAL_SETTINGS_KEY]?.pinnedSessions;
+        if (!map)
+            return;
+        let changed = false;
+        for (const [cwdKey, list] of Object.entries(map)) {
+            const next = list.filter((p) => normalizePathKey(p) !== norm);
+            if (next.length !== list.length) {
+                changed = true;
+                if (next.length > 0) {
+                    map[cwdKey] = next;
+                }
+                else {
+                    delete map[cwdKey];
+                }
+            }
+        }
+        if (changed) {
+            if (Object.keys(map).length === 0) {
+                delete all[ClientStateStore.GLOBAL_SETTINGS_KEY].pinnedSessions;
+            }
+            this.save();
+        }
+    }
     /** 全局默认 key 跟随删除：被删的 key 若是全局默认记的，指到接替者（无接替则删引用）。 */
     repointDeletedKeyInDefault(provider, deletedKeyName, newActive) {
         const all = this.load();

package/dist/server/compact-context-tool.js

@@ -61,7 +61,9 @@ export const CompactContextParams = Type.Object({
         description: "Compression focus and requirements for the current issue/task. State: 1) the active problem/goal; 2) context to PRESERVE (key decisions, code changes, conventions, user constraints); 3) what to REMOVE or condense (failed attempts, resolved debugging, off-topic history).",
     }),
     keepRecentTokens: Type.Optional(Type.Number({
-        description: "Recent tokens to keep uncompacted (1000-64000). Smaller values (e.g. 3000-8000) compact more aggressively. Omit = auto-calculated from session size.",
+        minimum: MIN_KEEP_RECENT_TOKENS,
+        maximum: MAX_KEEP_RECENT_TOKENS,
+        description: "Recent tokens to keep uncompacted (1000-100000). Smaller values (e.g. 3000-8000) compact more aggressively. Omit = auto-calculated from session size.",
     })),
     summary: Type.Optional(Type.String({
         description: "Custom structured summary written by you; used as the core basis for the compaction entry if provided.",