pi-web-ui 0.91.0 → 0.93.0

package/dist/server/auth-cookie.js

@@ -21,3 +21,29 @@ export function isTlsRequest(req) {
 export function buildPiWebTokenCookie(encodedValue, maxAge, secure) {
     return `pi_web_token=${encodedValue}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}${secure ? "; Secure" : ""}`;
 }
+/**
+ * `pi_web_token` cookie 值 → 原始口令。
+ *
+ * 下发时按 `encodeURIComponent` 编码（RFC 6265 的 cookie-value 只允许 ASCII，
+ * `=` / `+` / 空格 / 非 ASCII 都必须转义），所以**比对前必须先解码** —— 否则
+ * 含这些字符的口令永远匹配不上，表现为「`?token=` 那一次 200，之后所有资源与
+ * WS 全 401」（issue #261：base64 口令尾巴上的 `=` 被存成 `%3D`，服务端却拿
+ * `%3D` 去和 `=` 比）。
+ *
+ * 浏览器回来的一定是编码值，但手写 cookie / 旧客户端可能是明文（`=` 在值里
+ * 合法，我们按首个 `=` 切分），所以调用方应把「原样」与「解码后」两种候选都
+ * 试一遍（见 index.ts 的 requestTokens）。
+ *
+ * 不是合法百分号编码时原样返回：`decodeURIComponent` 会抛 `URIError`，
+ * 而一个手写的脏 cookie 绝不该把请求打成 500。
+ */
+export function decodeCookieToken(raw) {
+    if (!raw)
+        return "";
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}

package/dist/server/claim-files-tool.js

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// claim-files-tool.ts — 文件认领（claim_files）：并行冲突的「事前打招呼」
+// ---------------------------------------------------------------------------
+// 触碰集是事后信息（写完才知道），claim 是事前意图（"我要改这几个文件"）。
+// advisory 语义：认领只出现在提醒/files/list 里升级措辞，不拦 edit/bash ——
+// 强制锁会死锁（见 claim-store.ts 文件头）。先到先得；自己的可刷新，
+// 别人的动不了；过期自动释放 + 发 prompt 心跳续期 + 对话关闭释放。
+//
+// 开关走统一工具 tab（AGENT_TOOL_CATALOG 目录 + 设置页开关行；ActiveSet 门控，
+// live 生效）：认领是纯 advisory（关掉只会少提醒），默认开。DSH 引擎无 customTool
+// 注册面，只有 pi 引擎对话能认领（提醒是服务端算的，DSH 照样能看到别人的认领）。
+// ---------------------------------------------------------------------------
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { bilingual, pick } from "./i18n.js";
+import { CLAIM_FILES_TOOL_NAME } from "./tool-manager.js";
+import { CLAIM_TTL_MS, resolveClaimPath } from "./claim-store.js";
+/** 工具名（唯一定义在 tool-manager.ts，本模块 re-export 供单测沿用，模式同 present-files-tool.ts）。 */
+export { CLAIM_FILES_TOOL_NAME };
+function fmtTtl(ms) {
+    const m = Math.round(ms / 60000);
+    return m >= 60 ? `${Math.floor(m / 60)}h${m % 60 ? `${m % 60}m` : ""}` : `${m}m`;
+}
+export function makeClaimFilesTool(host, lang) {
+    const getLang = lang ?? (() => "en");
+    const text = (t, details = {}) => ({
+        content: [{ type: "text", text: t }],
+        details,
+    });
+    return defineTool({
+        name: CLAIM_FILES_TOOL_NAME,
+        label: "Claim files to avoid parallel conflicts",
+        description: bilingual("Declare which files you are about to edit so parallel runs in the same project can steer clear (advisory only — it never blocks edits). " +
+            "action=claim reserves paths for THIS conversation (first wins; already claimed by others is reported, not overridden); action=release frees yours (no paths = all yours); action=list shows this project's claim table. " +
+            "Claims expire after ~30 min idle (each of your prompts refreshes them) and are released when the conversation closes. " +
+            "Paths must stay inside the project directory. Only pi-engine conversations can claim (no customTool surface on DSH).", "声明你要改哪些文件，让同项目的并行对话绕行（纯建议，不拦任何编辑）。" +
+            "action=claim 把路径记到本对话名下（先到先得；别人已认领的会告诉你，不抢占）；action=release 放掉你自己的（不给 paths = 全放）；action=list 看本项目的认领表。" +
+            "认领闲置约 30 分钟过期（你每次发 prompt 自动续期），对话关闭时释放。" +
+            "路径必须在项目目录内。只有 pi 引擎对话能认领（DSH 无 customTool 注册面）。"),
+        promptSnippet: "claim files you are about to edit (advisory, first-wins) so parallel runs steer clear",
+        parameters: Type.Object({
+            action: Type.Optional(Type.String({ description: 'claim = reserve paths; release = free yours; list = show table. Default "list".' })),
+            paths: Type.Optional(Type.Array(Type.String(), { description: "claim/release only: file paths (inside the project)." })),
+            note: Type.Optional(Type.String({ description: "claim only: why you need them (shown to others, ≤200 chars)." })),
+            ttlMinutes: Type.Optional(Type.Number({ description: "claim only: expiry in minutes (1-480, default 30; refreshed by your prompts)." })),
+        }),
+        execute: async (_id, p, _signal, _onUpdate, _ctx) => {
+            const store = host.store();
+            if (!store) {
+                return text(pick(getLang(), `认领表暂不可用（服务端未接线），先按无认领处理。`, `Claim store unavailable (not wired); proceed as if nothing is claimed.`, "claimfiles.no.store"));
+            }
+            const cwd = host.cwd();
+            const self = host.self();
+            const action = (p.action ?? "list").trim().toLowerCase();
+            if (action === "list") {
+                const rows = store.list(cwd);
+                const L = getLang();
+                if (rows.length === 0) {
+                    return text(pick(L, `本项目暂无认领（parallel reminder 的触碰集照常工作）。`, `No claims in this project (parallel touch reminders still apply).`, "claimfiles.list.empty"), { cwd, total: 0, claims: [] });
+                }
+                const lines = rows.map((c) => `- ${c.path} · 「${c.ownerTitle}」${c.note ? ` · ${c.note}` : ""} · ${pick(L, `剩约 ${fmtTtl(Math.max(0, c.expiresAt - Date.now()))}`, `~${fmtTtl(Math.max(0, c.expiresAt - Date.now()))} left`, "claimfiles.list.ttl", { ttl: fmtTtl(Math.max(0, c.expiresAt - Date.now())) })}`);
+                return text(`${pick(L, `本项目认领表（${rows.length} 条，先到先得，只作绕行参考）：`, `Claim table for this project (${rows.length}, first-wins, advisory):`, "claimfiles.list.head", { total: rows.length })}\n${lines.join("\n")}`, {
+                    cwd,
+                    total: rows.length,
+                    claims: rows.map((c) => ({ path: c.path, ownerTitle: c.ownerTitle, note: c.note })),
+                });
+            }
+            if (action === "claim" || action === "release") {
+                const rawPaths = Array.isArray(p.paths) ? p.paths : [];
+                if (action === "release" && rawPaths.length === 0) {
+                    const n = store.release(cwd, self.convId);
+                    return text(pick(getLang(), n > 0 ? `已释放你名下 ${n} 条认领。` : `你名下没有认领，无事可做。`, n > 0 ? `Released ${n} of your claim(s).` : `You hold no claims; nothing to do.`, "claimfiles.release.all", { n }), { cwd, released: n });
+                }
+                if (rawPaths.length === 0) {
+                    return text(pick(getLang(), `action=${action} 需要 paths（release 不给 paths = 全放自己名下的）。`, `action=${action} needs paths (release without paths = free all yours).`, "claimfiles.bad.paths", { action }));
+                }
+                const bad = rawPaths.filter((s) => !resolveClaimPath(s, cwd));
+                if (bad.length > 0) {
+                    return text(pick(getLang(), `这些路径不在项目目录内，认领只接受项目内路径：${bad.slice(0, 3).join("、")}${bad.length > 3 ? `（等 ${bad.length} 个）` : ""}。`, `These paths escape the project directory (claims are project-local): ${bad.slice(0, 3).join(", ")}${bad.length > 3 ? ` (+${bad.length - 3})` : ""}.`, "claimfiles.bad.outside", { paths: bad.slice(0, 3).join(", ") }));
+                }
+                if (action === "claim") {
+                    const ttlMs = typeof p.ttlMinutes === "number" && Number.isFinite(p.ttlMinutes)
+                        ? Math.floor(p.ttlMinutes * 60000)
+                        : CLAIM_TTL_MS;
+                    const { claimed, conflicts } = store.claim(cwd, { convId: self.convId, title: self.title }, rawPaths.map((s) => ({
+                        path: s,
+                        ...(typeof p.note === "string" && p.note.trim() ? { note: p.note } : {}),
+                        ttlMs,
+                    })));
+                    const L = getLang();
+                    const okLine = claimed.length > 0
+                        ? pick(L, `已认领 ${claimed.length} 个（${claimed.map((c) => c.path).join("、")}），约 ${fmtTtl(ttlMs)} 后过期（你发 prompt 自动续）。`, `Claimed ${claimed.length} (${claimed.map((c) => c.path).join(", ")}), expiring in ~${fmtTtl(ttlMs)} (refreshed by your prompts).`, "claimfiles.claim.ok", { n: claimed.length })
+                        : "";
+                    const clashLine = conflicts.length > 0
+                        ? pick(L, `先到先得，以下已被别人认领（没抢占）：${conflicts.map((c) => `${c.path}（「${c.claim.ownerTitle}」${c.claim.note ? `：${c.claim.note}` : ""}）`).join("；")} —— 绕行，或问用户。`, `First-wins; already claimed by others (not overridden): ${conflicts.map((c) => `${c.path} ("${c.claim.ownerTitle}"${c.claim.note ? `: ${c.claim.note}` : ""})`).join("; ")} — steer clear or ask the user.`, "claimfiles.claim.conflict", { n: conflicts.length })
+                        : "";
+                    return text([okLine, clashLine].filter(Boolean).join("\n") ||
+                        pick(L, `无事可做。`, `Nothing to do.`, "claimfiles.claim.noop"), {
+                        cwd,
+                        claimed: claimed.map((c) => c.path),
+                        conflicts: conflicts.map((c) => ({ path: c.path, ownerTitle: c.claim.ownerTitle })),
+                    });
+                }
+                // release 指定 paths：只放自己的，别人的动不了（返回里如实说）。
+                const n = store.release(cwd, self.convId, rawPaths);
+                return text(pick(getLang(), n > 0
+                    ? `已释放 ${n} 条你名下的认领（别人的动不了，也没动）。`
+                    : `这些路径没有你名下的认领（可能是别人的，无权释放）。`, n > 0
+                    ? `Released ${n} of your claim(s) (others' untouched, as they should be).`
+                    : `None of these are yours (possibly someone else's — not yours to release).`, "claimfiles.release.paths", { n }), { cwd, released: n });
+            }
+            return text(pick(getLang(), `action 非法：${p.action}（只能是 claim、release 或 list）。`, `Invalid action: ${p.action} (must be "claim", "release" or "list").`, "claimfiles.bad.action", { "p.action": p.action }));
+        },
+    });
+}

package/dist/server/claim-store.js

@@ -0,0 +1,301 @@
+// ---------------------------------------------------------------------------
+// claim-store.ts — 文件认领表（claim store）+ 触碰 sidecar
+// ---------------------------------------------------------------------------
+// 背景：触碰集是「事后诸葛亮」（写完才知道），并行冲突要的是「事前打招呼」。
+// claim = 某对话声明「我要改这几个文件」，其他对话在提醒/files/status 里看到
+// 并绕行。注意这只是 advisory（建议）：提醒措辞升级，但不拦 edit/bash ——
+// 强制锁会引入死锁与 stall（见设计说明）， first-wins + 过期自动释放是唯一的
+// 防腐机制（fail-open：丢认领只会少一条提醒，绝不卡死任何人）。
+//
+// 存放：
+//   - 认领表全局共享（跨浏览器标签页可见）→ AgentService 级单例，落盘
+//     <dataDir>/claims.json（SubagentTemplatesStore 同款 best-effort 持久化：
+//     写坏/读坏绝不弄崩 server，坏文件直接丢弃重建）。
+//   - 触碰 sidecar 按会话落盘（<转录文件>.touches.json）：压缩后旧消息被摘要
+//     替代，sidecar 让 files/status 在压缩后仍有答案；只读小文件，不扫全量转录。
+//     inMemory 子代理没有转录文件 → 无 sidecar，走实时消息（老样子）。
+//
+// key 口径：认领按「项目 cwd」分表（默认不跨项目）；路径一律存绝对路径
+// （认领时按 conv cwd resolve），比对时触碰路径同样 resolve 后比较 —— 后缀
+// 模糊匹配继续禁用（假阳性比漏报更糟，见 conversation-touches 文件头）。
+// ---------------------------------------------------------------------------
+import { mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { normalizeTouchPath, unionTouchLists } from "./conversation-touches.js";
+/** 认领默认 TTL：30 分钟（每次发 prompt 心跳续期，对话关闭时释放）。 */
+export const CLAIM_TTL_MS = 30 * 60 * 1000;
+/** 认领 TTL 上下限（工具参数钳制用）。 */
+export const CLAIM_TTL_MIN_MS = 60 * 1000;
+export const CLAIM_TTL_MAX_MS = 8 * 60 * 60 * 1000;
+/** sidecar 条目上限（防无界增长；超了按 lastTs 掐尾）。 */
+export const SIDECAR_MAX_ENTRIES = 500;
+/** claims.json 版本（以后改格式时迁移用）。 */
+const CLAIMS_FILE_VERSION = 1;
+/** cwd 分表键：绝对归一（大小写不归一，见 touches 局限 3）。 */
+function cwdKey(cwd) {
+    try {
+        return resolve(cwd);
+    }
+    catch {
+        return cwd;
+    }
+}
+/** 认领路径合法性：必须落在 conv cwd 内（../ 逃逸拒绝，由工具转报错）。 */
+export function resolveClaimPath(raw, cwd) {
+    if (typeof raw !== "string" || !raw.trim())
+        return undefined;
+    let abs;
+    try {
+        abs = resolve(cwd, normalizeTouchPath(raw));
+    }
+    catch {
+        return undefined;
+    }
+    const root = cwdKey(cwd);
+    if (abs !== root && !abs.startsWith(root + sep))
+        return undefined;
+    return abs;
+}
+function isValidClaim(c) {
+    if (!c || typeof c !== "object")
+        return false;
+    const o = c;
+    return (typeof o.path === "string" &&
+        !!o.path &&
+        typeof o.ownerConvId === "string" &&
+        !!o.ownerConvId &&
+        typeof o.ownerTitle === "string" &&
+        typeof o.claimedAt === "number" &&
+        typeof o.expiresAt === "number");
+}
+/** 项目级认领表（AgentService 级单例；I/O 全 best-effort）。 */
+export class ClaimStore {
+    file;
+    tables = new Map();
+    constructor(file) {
+        this.file = file;
+        this.load();
+    }
+    /** 认领：先到先得。别人（含过期前）的 → conflicts；自己的 → 刷新 note/过期。 */
+    claim(cwd, owner, inputs, now = Date.now()) {
+        const key = cwdKey(cwd);
+        this.sweepTable(key, now);
+        const table = this.tables.get(key) ?? [];
+        const claimed = [];
+        const conflicts = [];
+        for (const input of inputs) {
+            const abs = resolveClaimPath(input.path, cwd);
+            if (!abs)
+                continue; // 非法路径调用方已拦，这里只跳过不抛错
+            const ttl = typeof input.ttlMs === "number" && Number.isFinite(input.ttlMs)
+                ? Math.min(CLAIM_TTL_MAX_MS, Math.max(CLAIM_TTL_MIN_MS, Math.floor(input.ttlMs)))
+                : CLAIM_TTL_MS;
+            const existing = table.find((c) => c.path === abs);
+            if (existing && existing.ownerConvId !== owner.convId) {
+                conflicts.push({ path: abs, claim: { ...existing } });
+                continue;
+            }
+            const row = {
+                path: abs,
+                ownerConvId: owner.convId,
+                ownerTitle: owner.title,
+                ...(typeof input.note === "string" && input.note.trim() ? { note: input.note.trim().slice(0, 200) } : {}),
+                claimedAt: existing?.claimedAt ?? now,
+                expiresAt: now + ttl,
+            };
+            if (existing)
+                Object.assign(existing, row);
+            else
+                table.push(row);
+            claimed.push({ ...row });
+        }
+        this.tables.set(key, table);
+        this.save();
+        return { claimed, conflicts };
+    }
+    /** 释放：只放自己的（别人的动不了）；paths 空 = 全放。返回释放条数。 */
+    release(cwd, ownerConvId, paths, now = Date.now()) {
+        const key = cwdKey(cwd);
+        this.sweepTable(key, now);
+        const table = this.tables.get(key) ?? [];
+        let drop = null;
+        if (Array.isArray(paths) && paths.length > 0) {
+            drop = new Set();
+            for (const p of paths) {
+                const abs = resolveClaimPath(p, cwd);
+                if (abs)
+                    drop.add(abs);
+            }
+        }
+        const before = table.length;
+        this.tables.set(key, table.filter((c) => c.ownerConvId !== ownerConvId || (drop !== null && !drop.has(c.path))));
+        const n = before - (this.tables.get(key)?.length ?? 0);
+        if (n > 0)
+            this.save();
+        return n;
+    }
+    /** 按 owner 全放（对话关闭/释放时调）。返回释放条数。 */
+    releaseByOwner(ownerConvId, now = Date.now()) {
+        let n = 0;
+        for (const [key, table] of this.tables) {
+            this.sweepTable(key, now);
+            const kept = (this.tables.get(key) ?? table).filter((c) => c.ownerConvId !== ownerConvId);
+            n += table.length - kept.length;
+            this.tables.set(key, kept);
+        }
+        if (n > 0)
+            this.save();
+        return n;
+    }
+    /** 心跳续期：该 owner 的全部认领延长 TTL（发 prompt 时调）。返回续期条数。 */
+    touch(ownerConvId, now = Date.now()) {
+        let n = 0;
+        for (const [key, table] of this.tables) {
+            this.sweepTable(key, now);
+            for (const c of this.tables.get(key) ?? table) {
+                if (c.ownerConvId === ownerConvId) {
+                    c.expiresAt = now + CLAIM_TTL_MS;
+                    n++;
+                }
+            }
+        }
+        if (n > 0)
+            this.save();
+        return n;
+    }
+    /** 读某项目认领表（已扫过期，返回副本，调用方随便改）。 */
+    list(cwd, now = Date.now()) {
+        const key = cwdKey(cwd);
+        this.sweepTable(key, now);
+        return (this.tables.get(key) ?? []).map((c) => ({ ...c }));
+    }
+    sweepTable(key, now) {
+        const table = this.tables.get(key);
+        if (!table || table.length === 0)
+            return;
+        const kept = table.filter((c) => c.expiresAt > now);
+        if (kept.length !== table.length) {
+            this.tables.set(key, kept);
+            this.save();
+        }
+    }
+    load() {
+        let raw = "";
+        try {
+            raw = readFileSync(this.file, "utf8");
+        }
+        catch {
+            return; // 文件不存在 = 空表
+        }
+        try {
+            const data = JSON.parse(raw);
+            if (!data || typeof data !== "object" || data.version !== CLAIMS_FILE_VERSION)
+                return;
+            if (!data.tables || typeof data.tables !== "object")
+                return;
+            for (const [key, rows] of Object.entries(data.tables)) {
+                if (!Array.isArray(rows))
+                    continue;
+                const valid = rows.filter(isValidClaim).map((c) => ({
+                    ...c,
+                    note: typeof c.note === "string" ? c.note : undefined,
+                }));
+                if (valid.length > 0)
+                    this.tables.set(key, valid);
+            }
+        }
+        catch {
+            // 坏文件丢弃（下次 save 覆盖重建），绝不抛错
+            this.tables.clear();
+        }
+    }
+    save() {
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            const tmp = `${this.file}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ version: CLAIMS_FILE_VERSION, tables: Object.fromEntries(this.tables) }));
+            renameSync(tmp, this.file);
+        }
+        catch {
+            // 持久化故障绝不能弄崩 server（内存表照常用）
+        }
+    }
+}
+/** 触碰集里命中认领表的条目（双方都 resolve 成绝对路径后比较）。 */
+export function matchClaims(touches, claims, cwd) {
+    if (!Array.isArray(touches) || !Array.isArray(claims) || touches.length === 0 || claims.length === 0)
+        return [];
+    const byPath = new Map(claims.map((c) => [c.path, c]));
+    const out = [];
+    for (const t of touches) {
+        let abs;
+        try {
+            abs = resolve(cwd, normalizeTouchPath(t.path));
+        }
+        catch {
+            continue;
+        }
+        const hit = byPath.get(abs);
+        if (hit)
+            out.push({ touch: t, claim: hit });
+    }
+    return out;
+}
+function sidecarPath(sessionFile) {
+    return `${sessionFile}.touches.json`;
+}
+/** 读触碰 sidecar（同步小文件；不存在/坏了 → undefined，调用方回落现算）。 */
+export function readTouchSidecar(sessionFile) {
+    if (typeof sessionFile !== "string" || !sessionFile)
+        return undefined;
+    let raw = "";
+    try {
+        if (statSync(sidecarPath(sessionFile)).size > 1024 * 1024)
+            return undefined;
+        raw = readFileSync(sidecarPath(sessionFile), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const data = JSON.parse(raw);
+        if (!data || !Array.isArray(data.files))
+            return undefined;
+        const valid = data.files.filter((f) => !!f && typeof f === "object" && typeof f.path === "string");
+        return valid.map((f) => ({
+            path: f.path,
+            count: typeof f.count === "number" && Number.isFinite(f.count) ? f.count : 1,
+            lastTs: typeof f.lastTs === "number" && Number.isFinite(f.lastTs) ? f.lastTs : 0,
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 写触碰 sidecar（读-合并-写；空集不写；全 best-effort， never throw）。 */
+export async function mergeTouchSidecar(sessionFile, fresh) {
+    if (typeof sessionFile !== "string" || !sessionFile)
+        return;
+    if (!Array.isArray(fresh) || fresh.length === 0)
+        return;
+    try {
+        const merged = unionTouchLists(readTouchSidecar(sessionFile) ?? [], fresh).slice(0, SIDECAR_MAX_ENTRIES);
+        const tmp = `${sidecarPath(sessionFile)}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ version: 1, updatedAt: Date.now(), files: merged }));
+        renameSync(tmp, sidecarPath(sessionFile));
+    }
+    catch {
+        // sidecar 只是加速+防压缩丢失，写坏了下次重算
+    }
+}
+/** 删 sidecar（会话删除时顺带；不存在不报错）。 */
+export function removeTouchSidecar(sessionFile) {
+    if (typeof sessionFile !== "string" || !sessionFile)
+        return;
+    try {
+        unlinkSync(sidecarPath(sessionFile));
+    }
+    catch {
+        // 不存在或删不掉都无所谓
+    }
+}

package/dist/server/client-state.js

@@ -12,6 +12,40 @@ import { normalizeSoftCapByModel, normalizeSoftCapTokens } from "./soft-cap.js";
 import { deriveLegacy, legacyToDisabled, normalizeDisabledAgentTools } from "./tool-manager.js";
 /** 大模型 API 出错自动重试次数的默认值（SDK 默认 3）。 */
 export const DEFAULT_RETRY_MAX_ATTEMPTS = 6;
+/** 工具执行看门狗超时的默认值（默认 20 分钟；环境变量 PI_WEB_TOOL_TIMEOUT_MS 覆盖）。 */
+export const DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS = (() => {
+    const v = Number(process.env.PI_WEB_TOOL_TIMEOUT_MS);
+    return Number.isFinite(v) && v >= 0 ? v : 20 * 60_000;
+})();
+/** 归一化工具看门狗超时（毫秒）：0 = 禁用；非数值、负数或空值回落默认值，非负整数保留。 */
+export function normalizeToolWatchdogTimeoutMs(v) {
+    if (v === null || v === undefined || v === "")
+        return DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS;
+    const n = Math.floor(Number(v));
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS;
+    return n;
+}
+/** 工具自己声明超时时留给它的余量（毫秒）：让工具先自己超时并返回错误，
+ *  而不是看门狗先下手把整轮对话 abort 掉。 */
+export const TOOL_WATCHDOG_EXPLICIT_GRACE_MS = 5_000;
+/** 计算单次工具调用的有效看门狗超时（毫秒；≤0 = 不布看门狗）。
+ *  基础值来自设置/环境变量（见 DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS）；**若工具调用
+ *  自己声明了更长的超时**（目前只有 bash 的 `args.timeout`，单位秒），自动顺延到
+ *  「工具超时 + 余量」—— 否则 AI 明确要求跑 90 分钟的命令，会被 20 分钟的看门狗
+ *  连同整轮对话一起剁掉。纯函数，可单测。 */
+export function effectiveToolWatchdogMs(baseMs, toolName, args) {
+    if (!Number.isFinite(baseMs) || baseMs <= 0)
+        return 0;
+    let ms = baseMs;
+    if (toolName === "bash" && args && typeof args === "object") {
+        const raw = args.timeout;
+        const sec = typeof raw === "number" ? raw : Number(raw);
+        if (Number.isFinite(sec) && sec > 0)
+            ms = Math.max(ms, sec * 1000 + TOOL_WATCHDOG_EXPLICIT_GRACE_MS);
+    }
+    return ms;
+}
 /** 归一化插件 AI 工具禁用名单：只收非空字符串（去重，上限 256 个）。
  *  与 disabledAgentTools 不同——插件工具名是动态的（注册才知道），不能按
  *  固定目录校验；未知/已卸载插件的条目刻意保留（重装后仍保持关闭）。
@@ -285,15 +319,20 @@ export class ClientStateStore {
         state.lastCwd = cwd;
         const now = Date.now();
         state.projects = [{ path: cwd, lastUsed: now }, ...state.projects.filter((p) => p.path !== cwd)].slice(0, 30);
-        // Opening the workspace again clears its removal tombstone.
-        if (state.removedProjects?.length) {
-            state.removedProjects = state.removedProjects.filter((p) => p !== cwd);
+        // 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) {
+                cState.removedProjects = cState.removedProjects.filter((p) => p !== cwd);
+            }
         }
         this.save();
     }
     /** Drop one workspace from the recent-project list (user-requested removal).
      *  Records a tombstone too: pushProjects() re-discovers cwds from session
-     *  files on every listing, so without it the entry would instantly reappear. */
+     *  files on every listing, so without it the entry would instantly reappear.
+     *  Recorded in both the requesting client and GLOBAL_SETTINGS_KEY so the
+     *  removal stays across all browser tabs and server restarts until the user
+     *  explicitly opens that project again. */
     removeProject(clientId, cwd) {
         const all = this.load();
         const state = (all[clientId] ??= { projects: [] });
@@ -303,12 +342,28 @@ export class ClientStateStore {
         const removed = new Set(state.removedProjects ?? []);
         removed.add(cwd);
         state.removedProjects = [...removed];
+        const globalState = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        const globalRemoved = new Set(globalState.removedProjects ?? []);
+        globalRemoved.add(cwd);
+        globalState.removedProjects = [...globalRemoved];
+        for (const [id, cState] of Object.entries(all)) {
+            if (id !== ClientStateStore.GLOBAL_SETTINGS_KEY && cState.projects) {
+                cState.projects = cState.projects.filter((p) => p.path !== cwd);
+            }
+        }
         this.save();
     }
     /** Tombstoned projects (explicitly removed by the user) for filtering the
-     *  merged recent-project list. */
+     *  merged recent-project list across clients. */
     getRemovedProjects(clientId) {
-        return this.load()[clientId]?.removedProjects ?? [];
+        const all = this.load();
+        const clientRemoved = all[clientId]?.removedProjects ?? [];
+        const globalRemoved = all[ClientStateStore.GLOBAL_SETTINGS_KEY]?.removedProjects ?? [];
+        if (globalRemoved.length === 0)
+            return clientRemoved;
+        if (clientRemoved.length === 0)
+            return globalRemoved;
+        return [...new Set([...clientRemoved, ...globalRemoved])];
     }
     /** Last-used goal/review prefs for a client, or undefined if never set. */
     getGoalPrefs(clientId) {
@@ -419,6 +474,8 @@ export class ClientStateStore {
                 : (stored?.terminalToolsEnabled ?? false),
             terminalBash: stored?.terminalBash ?? false,
             terminalBashIdleMs: stored?.terminalBashIdleMs ?? 15_000,
+            toolWatchdogTimeoutMs: normalizeToolWatchdogTimeoutMs(stored?.toolWatchdogTimeoutMs),
+            readDirEnabled: stored?.readDirEnabled ?? true,
             editSoftEnabled: stored?.disabledAgentTools !== undefined
                 ? deriveLegacy(legacyToDisabled(stored)).editSoftEnabled
                 : (stored?.editSoftEnabled ?? false),
@@ -431,6 +488,7 @@ export class ClientStateStore {
             devNoCache: stored?.devNoCache,
             autoReload: stored?.autoReload,
             toolsWrap: stored?.toolsWrap ?? true,
+            toolImagesEnabled: stored?.toolImagesEnabled ?? true,
             skillsFullText: normalizeSkillList(stored?.skillsFullText),
             visionBridgeEnabled: stored?.visionBridgeEnabled ?? true,
             visionBridgeModel: stored?.visionBridgeModel ?? null,
@@ -473,6 +531,8 @@ export class ClientStateStore {
             terminalToolsEnabled: settings.terminalToolsEnabled ?? cur.terminalToolsEnabled ?? false,
             terminalBash: settings.terminalBash ?? cur.terminalBash ?? false,
             terminalBashIdleMs: settings.terminalBashIdleMs ?? cur.terminalBashIdleMs ?? 15_000,
+            toolWatchdogTimeoutMs: normalizeToolWatchdogTimeoutMs(settings.toolWatchdogTimeoutMs ?? cur.toolWatchdogTimeoutMs ?? DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS),
+            readDirEnabled: settings.readDirEnabled ?? cur.readDirEnabled ?? true,
             editSoftEnabled: settings.editSoftEnabled ?? cur.editSoftEnabled ?? false,
             questionnaireEnabled: settings.questionnaireEnabled ?? cur.questionnaireEnabled ?? true,
             goalModeEnabled: settings.goalModeEnabled ?? cur.goalModeEnabled ?? true,
@@ -481,6 +541,7 @@ export class ClientStateStore {
             devNoCache: settings.devNoCache ?? cur.devNoCache,
             autoReload: settings.autoReload ?? cur.autoReload,
             toolsWrap: settings.toolsWrap ?? cur.toolsWrap ?? true,
+            toolImagesEnabled: settings.toolImagesEnabled ?? cur.toolImagesEnabled ?? true,
             skillsFullText: normalizeSkillList(settings.skillsFullText ?? cur.skillsFullText),
             visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
             visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
@@ -632,6 +693,53 @@ export class ClientStateStore {
             delete all[clientId].projectModels;
         this.save();
     }
+    /** 全局默认模型（跨客户端共享，存 __settings__ 键）。缺省 = 未设置。 */
+    getDefaultModel() {
+        return this.load()[ClientStateStore.GLOBAL_SETTINGS_KEY]?.defaultModel;
+    }
+    /** 设置全局默认模型（"provider/id"）。 */
+    saveDefaultModel(modelId) {
+        const all = this.load();
+        const state = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        state.defaultModel = modelId;
+        this.save();
+    }
+    /** 清除全局默认模型（连带其 key 记忆）。 */
+    clearDefaultModel() {
+        const all = this.load();
+        const state = all[ClientStateStore.GLOBAL_SETTINGS_KEY];
+        if (!state)
+            return;
+        delete state.defaultModel;
+        delete state.defaultProviderKeys;
+        this.save();
+    }
+    /** 取全局默认的某 provider key。 */
+    getDefaultProviderKey(provider) {
+        return this.load()[ClientStateStore.GLOBAL_SETTINGS_KEY]?.defaultProviderKeys?.[provider];
+    }
+    /** 记全局默认的某 provider key（设全局默认模型时连带记）。 */
+    saveDefaultProviderKey(provider, keyName) {
+        const all = this.load();
+        const state = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        (state.defaultProviderKeys ??= {})[provider] = keyName;
+        this.save();
+    }
+    /** 全局默认 key 跟随删除：被删的 key 若是全局默认记的，指到接替者（无接替则删引用）。 */
+    repointDeletedKeyInDefault(provider, deletedKeyName, newActive) {
+        const all = this.load();
+        const map = all[ClientStateStore.GLOBAL_SETTINGS_KEY]?.defaultProviderKeys;
+        if (!map || map[provider] !== deletedKeyName)
+            return;
+        if (newActive)
+            map[provider] = newActive;
+        else {
+            delete map[provider];
+            if (Object.keys(map).length === 0)
+                delete all[ClientStateStore.GLOBAL_SETTINGS_KEY].defaultProviderKeys;
+        }
+        this.save();
+    }
     /** 全局「快捷短语已 seed」标记（非 per-clientId）。
      *
      * 为什么全局：clientId 存 sessionStorage（每标签页独立、关浏览器即失），按