pi-web-ui 0.94.1 → 0.96.0

package/dist/server/tool-manager.js

@@ -34,6 +34,7 @@ export const SUBAGENT_TOOL_NAMES = [
     "subagent_stop",
     "subagent_wait_all",
     "subagent_templates",
+    "subagent_handoff",
 ];
 /** 独立宽松编辑工具（定义见 edit-soft-tool.ts）。 */
 export const EDIT_SOFT_TOOL_NAME = "edit_soft";
@@ -58,16 +59,28 @@ export const SKILL_TOOL_NAME = "skill";
 export const SCHEDULE_TASK_TOOL_NAME = "schedule_task";
 export const SCHEDULE_LIST_TOOL_NAME = "schedule_list";
 export const SCHEDULE_CANCEL_TOOL_NAME = "schedule_cancel";
+/** 持久代码求值沙箱工具（定义见 eval-tool.ts）：在受控持久内核中执行 Python 或 JS/TS 代码。 */
+export const EVAL_TOOL_NAME = "eval";
 /** 展示文件工具（定义见 present-files-tool.ts）：把图片/视频/文本作为预览卡片
  *  推到对话里，卡片带预览/本地打开/在文件夹中显示/下载/复制路径。 */
 export const PRESENT_FILES_TOOL_NAME = "present_files";
 /** 文件认领工具（定义见 claim-files-tool.ts）：声明要改哪些文件，让同项目的
  *  并行对话绕行（纯建议，不拦编辑）。 */
 export const CLAIM_FILES_TOOL_NAME = "claim_files";
+/** 任务计划看板更新工具（定义见 plan-manager.ts，Plan Mode / 步骤状态机）。 */
+export const PLAN_UPDATE_TOOL_NAME = "plan_update";
+/** 主动上下文压缩工具（定义见 compact-context-tool.ts）。 */
+export const COMPACT_CONTEXT_TOOL_NAME = "compact_context";
+/** 高可靠结构化补丁工具（定义见 patch-tool.ts）：基于内容哈希锚点与语法块的行补丁工具。 */
+export const PATCH_TOOL_NAME = "patch";
+/** 原生语言服务器工具（定义见 lsp-tool.ts）：代码定义跳转、引用查询、类型悬停与诊断。 */
+export const LSP_TOOL_NAME = "lsp";
 /** 旧工具名（持久化迁移用；新代码一律用 MARKERS_LIST_TOOL_NAME）。 */
 export const LEGACY_MARKERS_LIST_TOOL_NAME = "markers_list";
-/** 可开关的 Agent 工具总目录（共 26 个；bash 本体与 SDK 内置 edit/read
- *  不进目录——关了 agent 就残了，不给关）。 */
+/** 可开关的 Agent 工具总目录（共 27 个）。核心内置工具 bash/read/edit/write 不进
+ *  目录——目录条目 = OTHER_AGENT_TOOLS 自动渲染的设置行，而这四个在设置页
+ *  「核心工具」区单独开关（见 SettingsModal 的 CORE_BUILTIN_TOOL_NAMES 区块），
+ *  禁用名单同样接受它们（normalizeDisabledAgentTools）。 */
 export const AGENT_TOOL_CATALOG = [
     ...TERMINAL_TOOL_NAMES.map((name) => ({
         name,
@@ -135,6 +148,31 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "claimFilesEnabledDesc",
         offHintKey: "claimFilesOffHint",
     },
+    // 结构化任务计划更新（Plan Mode / Step State Machine），默认开。
+    {
+        name: PLAN_UPDATE_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: true,
+        descKey: "planUpdateEnabledDesc",
+        offHintKey: "planUpdateOffHint",
+    },
+    {
+        name: PATCH_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: false,
+        descKey: "patchToolEnabledDesc",
+        offHintKey: "patchToolOffHint",
+    },
+    {
+        name: LSP_TOOL_NAME,
+        group: "other",
+        defaultOn: false,
+        dshVisible: false,
+        descKey: "lspToolEnabledDesc",
+        offHintKey: "lspToolOffHint",
+    },
     // 展示文件给用户（图片/视频内联、文本开预览弹窗、本地打开按钮）：默认开，
     // 不打开模型根本不知道能“给用户看”；DSH 引擎没有该 customTool（走 shipped preset）。
     {
@@ -155,6 +193,16 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "skillEnabledDesc",
         offHintKey: "skillOffHint",
     },
+    // 持久代码求值沙箱（Python / Node.js）：默认关（opt-in，防工具挤占）；
+    // DSH 引擎没有该 customTool。
+    {
+        name: EVAL_TOOL_NAME,
+        group: "other",
+        defaultOn: false,
+        dshVisible: false,
+        descKey: "evalEnabledDesc",
+        offHintKey: "evalOffHint",
+    },
     // 定时/延时唤醒：默认开（不打开 AI 根本不知道能定时；60s 间隔底线＋面板可随时取消），
     // DSH 引擎没有该 customTool（走 goal-rpc，无 customTool 注册面）。
     {
@@ -181,6 +229,16 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "scheduleTaskEnabledDesc",
         offHintKey: "scheduleTaskOffHint",
     },
+    // 主动上下文压缩：默认开（让 AI 可以根据当前问题主动精简上下文）。
+    // DSH 引擎无 customTool 注册面，不接。
+    {
+        name: COMPACT_CONTEXT_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: false,
+        descKey: "compactContextEnabledDesc",
+        offHintKey: "compactContextOffHint",
+    },
     // todo_list 唯一例外：行不在「其他」组，固定在上面的 markers 分区（设置页循环
     // 跳过它，见 OTHER_AGENT_TOOLS；文案 key 照给，万一哪天搬家不用补）。
     {
@@ -192,13 +250,18 @@ export const AGENT_TOOL_CATALOG = [
         offHintKey: "todoListOffHint",
     },
 ];
+/** SDK 核心内置工具名（可被门控显式禁用或被预设白名单过滤）。 */
+export const CORE_BUILTIN_TOOL_NAMES = ["bash", "read", "edit", "write"];
+export function isCoreBuiltinTool(name) {
+    return CORE_BUILTIN_TOOL_NAMES.includes(name);
+}
 const KNOWN_NAMES = new Set(AGENT_TOOL_CATALOG.map((t) => t.name));
 /** 是否为本表登记的可开关工具（未知名一律 false，不抛错）。 */
 export function isKnownAgentTool(name) {
     return KNOWN_NAMES.has(name);
 }
 /** 归一化禁用名单：非数组回落默认（= 默认关的那些）；数组则只保留已知工具名
- *  （去重；未知名丢弃，防旧文件/手写脏数据污染）。 */
+ *  （去重；未知名丢弃，防旧文件/手写脏数据污染）。支持登记核心内置工具。 */
 export function normalizeDisabledAgentTools(v) {
     if (!Array.isArray(v))
         return defaultDisabledAgentTools();
@@ -206,8 +269,9 @@ export function normalizeDisabledAgentTools(v) {
     for (const x of v) {
         // 旧名迁移：markers_list → todo_list（改名前已关闭的用户保持关闭）。
         const name = x === LEGACY_MARKERS_LIST_TOOL_NAME ? MARKERS_LIST_TOOL_NAME : x;
-        if (typeof name === "string" && KNOWN_NAMES.has(name) && !out.includes(name))
+        if (typeof name === "string" && (KNOWN_NAMES.has(name) || isCoreBuiltinTool(name)) && !out.includes(name)) {
             out.push(name);
+        }
     }
     return out;
 }
@@ -261,26 +325,179 @@ export function setAgentToolsEnabled(session, names, on) {
     }
 }
 /**
- * 全量重放（创建会话 / reload 后 / 设置变更后调）：按禁用名单把目录内工具
- * 逐个加回或剔除；目录外的工具（bash/SDK 内置/插件工具）原样不动。
+ * 全量重放（创建会话 / reload 后 / 设置变更后调）：按禁用名单把目录内工具与
+ * 核心内置工具（bash/read/edit/write，禁用名单接受它们）逐个加回或剔除；
+ * 基线之外的工具（插件工具等）原样不动。
+ * 支持传入 preset（预设 id），按预设白名单做二次过滤。
+ * 复原基线取 session.getAllTools()（全集，含被禁用的）——基线里没有的工具不会凭空发明。
  * Session 未就绪时静默跳过（下次创建/reload 会再应用）。
  */
-export function applyAgentToolsGating(session, disabled) {
+export function applyAgentToolsGating(session, disabled, preset) {
     try {
         const off = new Set(disabled);
-        const names = new Set(session.getActiveToolNames());
+        const allNames = session.getAllTools().map((t) => t.name);
+        const names = new Set(allNames);
         for (const t of AGENT_TOOL_CATALOG) {
             if (off.has(t.name))
                 names.delete(t.name);
             else
                 names.add(t.name);
         }
-        session.setActiveToolsByName([...names]);
+        for (const core of CORE_BUILTIN_TOOL_NAMES) {
+            if (off.has(core))
+                names.delete(core);
+            else if (allNames.includes(core))
+                names.add(core);
+        }
+        const filtered = filterToolsByPreset(names, preset);
+        session.setActiveToolsByName(filtered);
     }
     catch {
         // Session 未就绪——下次创建/reload 会再应用。
     }
 }
+/** pi 引擎内置 Agent 预设名录（对齐 DSH 预设体系，会话级工具白名单）。 */
+export const PI_AGENT_PRESETS = [
+    {
+        id: "standard",
+        trust: "system",
+        isDefault: true,
+        name: "全功能",
+        description: "提供全部可用工具与扩展能力（默认）",
+        order: 0,
+    },
+    {
+        id: "minimal",
+        trust: "system",
+        isDefault: false,
+        name: "极简模式",
+        description: "仅保留 bash 与 read；插件工具、技能名录与终端引导同步隐藏",
+        order: 1,
+    },
+    {
+        id: "code",
+        trust: "system",
+        isDefault: false,
+        name: "代码开发",
+        description: "专注于代码读写与执行（bash, read, edit, write, edit_soft）；插件工具与技能名录同步隐藏",
+        order: 2,
+    },
+    {
+        id: "reader",
+        trust: "system",
+        isDefault: false,
+        name: "只读分析",
+        description: "仅保留只读工具，禁止写操作；插件工具同步隐藏（读写未知，保守处理）",
+        order: 3,
+    },
+    {
+        id: "ask",
+        trust: "system",
+        isDefault: false,
+        name: "纯对话",
+        description: "无工具问答模式，模型不调用任何工具；插件工具与技能名录同步隐藏",
+        order: 4,
+    },
+];
+/** pi 引擎权限预设选项（三档沙箱策略）。 */
+export const PI_PERMISSION_OPTIONS = [
+    {
+        value: "read-only",
+        name: "只读模式",
+        description: "禁止所有文件修改（write/edit/edit_soft）及任何非只读操作",
+    },
+    {
+        value: "workspace-write-never",
+        name: "工作区内修改",
+        description: "仅允许在当前工作区目录下修改文件，工作区外写操作一律拒绝",
+    },
+    {
+        value: "danger-full-access",
+        name: "完全权限",
+        description: "允许修改任意目录文件及执行全量操作（需要二次确认）",
+    },
+];
+/** 按预设过滤活跃工具名。 */
+export function filterToolsByPreset(tools, preset) {
+    const all = Array.from(tools);
+    if (!preset || preset === "standard")
+        return all;
+    if (preset === "ask")
+        return [];
+    if (preset === "minimal") {
+        return all.filter((n) => n === "bash" || n === "read");
+    }
+    if (preset === "code") {
+        const codeSet = new Set(["bash", "read", "edit", "write", "edit_soft"]);
+        return all.filter((n) => codeSet.has(n));
+    }
+    if (preset === "reader") {
+        const writeTools = new Set([
+            "write",
+            "edit",
+            "edit_soft",
+            "bash",
+            "terminal_create",
+            "terminal_input",
+            "terminal_close",
+            "terminal_key",
+        ]);
+        return all.filter((n) => !writeTools.has(n));
+    }
+    return all;
+}
+/**
+ * pi 预设语义总表（唯一事实源，本文件是唯一定义处）：
+ *
+ * 预设是「禁用名单之外」的第二层门控，按会话生效（conv.agentPreset），新对话
+ * 取默认预设、首轮发言后锁定。标准预设不过滤；其余预设同时约束四处：
+ *
+ * - 目录/内置工具（ActiveSet）：filterToolsByPreset 直接过滤活跃集
+ *   （standard 全留 / ask 全拔 / minimal 仅 bash+read /
+ *   code 仅 bash+read+edit+write+edit_soft / reader 拔写类）。
+ * - 插件工具（registerAgentTool 动态注册）：presetAllowsPluginTools —— 只有
+ *   standard 保留，其余已知预设一律拔掉。插件工具读写性质未知，保守按最严处理
+ *   （minimal/code/ask 是白名单语义本来就过不去；reader 是 deny 名单，
+ *   未知工具同样不放行；未知预设 id 按不过滤，与 filterToolsByPreset 同口径）。
+ * - 技能名录段（{{skills}} 名录＋全文注入）：presetShowsSkillCatalog —— 与
+ *   skill 加载工具同进退（minimal/code/ask 下 loader 不在，列出来只是噪音；
+ *   reader 下 loader 可用，保留）。子代理模板的技能白名单是显式配置，
+ *   优先级高于预设，不参与此门控。
+ * - 终端引导（TERMINAL_TOOLS_GUIDANCE）：isTerminalGuidanceOn(disabled, preset) ——
+ *   只教「开关开着且预设下仍可用」的终端工具，不教不存在的工具。
+ * - 并行提醒（parallel-work-reminder）：信息层，不按预设开关（只看
+ *   parallelReminderEnabled 开关）；但文案里的问卷指引按
+ *   presetHasQuestionnaire 切换措辞——有问卷工具时调工具，否则正文提问。
+ *   认领信息是事实层，照常展示（store 是按项目全局的）。
+ *
+ * 显式配置永远优先于预设：disabledAgentTools / disabledPluginTools /
+ * disabledSkills / 子代理模板白名单照常生效，预设只做减法不做加法
+ * （开关关掉的东西，standard 也不会加回来）。
+ */
+/**
+ * 预设是否允许插件工具（动态注册，读写未知）：只有 standard 允许；
+ * 其余已知预设一律拒绝。未知 id 按不过滤（与 filterToolsByPreset 同口径，
+ * 防手写脏配置把插件工具全灭）。
+ */
+export function presetAllowsPluginTools(preset) {
+    if (!preset || preset === "standard")
+        return true;
+    return !PI_AGENT_PRESETS.some((p) => p.id === preset);
+}
+/**
+ * 预设下是否展示技能名录段（与 skill 加载工具同进退，由 filterToolsByPreset
+ * 单源推导，不另维护名单：minimal/code/ask 藏，standard/reader 留）。
+ */
+export function presetShowsSkillCatalog(preset) {
+    return filterToolsByPreset([SKILL_TOOL_NAME], preset).includes(SKILL_TOOL_NAME);
+}
+/**
+ * 预设下问卷工具是否可用（并行提醒等服务端文案用：有则指引调工具，
+ * 无则指引正文提问——不教不存在的工具）。同样单源推导。
+ */
+export function presetHasQuestionnaire(preset) {
+    return filterToolsByPreset([ASK_USER_QUESTION_TOOL_NAME], preset).includes(ASK_USER_QUESTION_TOOL_NAME);
+}
 /**
  * 旧存档迁移：已有新字段直接归一化；否则按遗留三开关折算
  * （语义与改动前一致：terminal/edit 未设/关 = 禁用对应组；问卷未设/开 = 启用）。
@@ -337,7 +554,15 @@ export function effectiveDisabledAgentTools(s) {
         next.add(ASK_USER_QUESTION_TOOL_NAME);
     return [...next];
 }
-/** 终端使用引导是否注入（组内有任一工具启用才教 AI 用，否则就是教不存在的工具）。 */
-export function isTerminalGuidanceOn(disabled) {
-    return TERMINAL_TOOL_NAMES.some((n) => !disabled.includes(n));
+/**
+ * 终端使用引导是否注入：组内有任一工具「开关开着且预设下仍可用」才教 AI 用，
+ * 否则就是教不存在的工具（preset 缺省/standard = 只看开关，保持旧语义）。
+ */
+export function isTerminalGuidanceOn(disabled, preset) {
+    const on = TERMINAL_TOOL_NAMES.filter((n) => !disabled.includes(n));
+    if (on.length === 0)
+        return false;
+    if (!preset || preset === "standard")
+        return true;
+    return filterToolsByPreset(on, preset).length > 0;
 }

package/dist/server/tool-overrides.js

@@ -0,0 +1,59 @@
+/**
+ * tool-overrides.ts —— pi-web-ui 对 SDK 内置工具的覆盖（read / write / edit）如何与
+ * **第三方 pi 扩展提供的同名工具共存**。
+ *
+ * 为什么需要这个模块（问题）：SDK 的注册表合并链是
+ * `allCustomTools = [...扩展注册的工具, ...customTools]` 再逐个 `definitionRegistry.set(name, …)`
+ * —— 后写赢 ⇒ **customTools 恒顶掉扩展的同名工具，与加载顺序无关、也没有开关**（见
+ * `dist/core/agent-session.js` 的 `_refreshToolRegistry()`）。而官方
+ * `docs/extensions.md` §Overriding Built-in Tools 明写扩展**可以**覆盖 `read` / `bash` /
+ * `powershell` / `edit` / `write` / `grep` / `find` / `ls` 并逐个列出了 `read`。
+ * pi-web-ui 过去把这三个覆盖直接塞进创建时的 `customTools` ⇒ 那句话在 `read`/`write`/`edit`
+ * 上失效：第三方扩展的同名工具**永远轮不到**，而且症状会伪装（覆盖层转发内置实现 ⇒
+ * 「读文件/图片/目录都正常，只有扩展特有的能力没有」，例如 `pi-better-edit` 的 read 不出锚、
+ * 它的 edit 随后一律 `E_UNKNOWN_ANCHOR`）。
+ *
+ * 做法：这三个覆盖**不再于创建时注册**。会话建好后按名字从**扩展注册表**
+ * （`session.extensionRunner.getAllRegisteredTools()`，不受 customTools 顶替影响）取扩展的同名
+ * 实现当基底，没有则用 pi-web-ui 自己的完整实现，再交给装饰器（`composeWith`）在其上叠加
+ * pi-web-ui 的能力（目录列条目 / 权限沙箱）。装饰器必须把**行为**委托给基底，只加自己那一层；
+ * 基底的 schema、描述、prompt 指引、渲染全部原样保留，扩展独有的参数（如 better-edit 的
+ * `windows`）照旧可用。
+ *
+ * 注入手法与 `plugins.ts` 的 `syncPluginToolsIntoSession` 相同：改 `session._customTools`
+ * 后调 `_refreshToolRegistry()`（SDK 改私有字段名即返回 null，调用方按「覆盖没装上」降级；
+ * `extensionRunner` 缺失时退化成「有扩展也当内置」＝改动前的行为，不会更差）。
+ *
+ * 顺序：注入项排在既有 `_customTools` **之前** ⇒ pi-web-ui 插件注册的同名工具（也是
+ * customTools，比覆盖层后写）仍然是最后赢家，与改动前的相对顺序一致。
+ */
+/** 解析某个工具名在**扩展注册表**里的实现；没有扩展提供时返回 undefined。 */
+export function extensionToolDefinition(session, name) {
+    const tools = session.extensionRunner?.getAllRegisteredTools?.();
+    return tools?.find((tool) => tool.definition?.name === name)?.definition;
+}
+/**
+ * 把覆盖装进已建好的会话：逐个解析基底（扩展同名工具优先）→ 装饰 → 注入 → 刷新注册表。
+ * 返回注入的工具名；会话对象形状不符（SDK 改私有字段名）返回 null，调用方按「覆盖未生效」降级。
+ */
+export function installToolOverrides(session, specs) {
+    if (!Array.isArray(session._customTools) || typeof session._refreshToolRegistry !== "function")
+        return null;
+    const names = new Set(specs.map((s) => s.name));
+    const injected = [];
+    for (const spec of specs) {
+        const extensionTool = extensionToolDefinition(session, spec.name);
+        if (extensionTool) {
+            // 有扩展同名工具：只能叠（composeWith）；没给装饰器就整个让给它 ——
+            // **绝不**用 fallback 顶掉它（那就又是本模块存在要防的那个问题）。
+            if (spec.composeWith)
+                injected.push(spec.composeWith(extensionTool));
+            continue;
+        }
+        injected.push(spec.fallback());
+    }
+    // 同名项先剔除再前置：重复调用幂等（不会层层叠加），且插件工具仍然后写赢。
+    session._customTools = [...injected, ...session._customTools.filter((t) => !names.has(t.name))];
+    session._refreshToolRegistry();
+    return [...names];
+}

package/dist/server/update-check.js

@@ -13,6 +13,7 @@ import { readdirSync, readFileSync, realpathSync, existsSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { pick } from "./i18n.js";
+import { sdkCopies } from "./sdk-origin.js";
 const PI_CORE_PACKAGE = "@earendil-works/pi-coding-agent";
 /** npm 官方源；用户在 <agentDir>/npm/.npmrc 里配了镜像/私有源时会被覆盖（issue #151）。 */
 export const NPM_DEFAULT_REGISTRY = "https://registry.npmjs.org";
@@ -424,6 +425,32 @@ export function defaultProbePiCore() {
     piCoreProbe = { at: now, version };
     return version;
 }
+/**
+ * issue #321 — detect "a newer pi is installed on this machine than the one
+ * this process actually loaded". The panel's pi-core row probes the GLOBAL pi
+ * CLI (what `npm i -g` updates), but the server loads its own bundled copy
+ * (nested beats ancestor in Node resolution, issue #260) — so after upgrading
+ * the global pi the panel reads "up to date" while conversations still run the
+ * old SDK. That invisible split is exactly what #321 reports; this turns it
+ * into data the UI can explain.
+ *
+ * Two detectors, unioned (newest wins): the CLI probe (standard global
+ * install) and the ancestor-chain copies (fallback when the probe finds
+ * nothing — different npm prefix, bun, …). Pure — tests inject both.
+ * Returns null when nothing newer than `runningVersion` is found.
+ */
+export function detectPiSdkSplit(runningVersion, probePiCore = defaultProbePiCore, copies = sdkCopies()) {
+    let installed = probePiCore();
+    for (const copy of copies) {
+        if (compareVersions(copy.version, runningVersion) > 0 &&
+            (!installed || compareVersions(copy.version, installed) > 0)) {
+            installed = copy.version;
+        }
+    }
+    if (!installed || compareVersions(installed, runningVersion) <= 0)
+        return null;
+    return { running: runningVersion, installed };
+}
 /**
  * Fallback when the CLI probe yields nothing: the version of the vendored pi
  * core copy in <agentDir>/npm/node_modules, or null if that is absent too.
@@ -646,7 +673,7 @@ gitCheck = defaultCheckGitExtension) {
  *  up-to-date ones, errors last. Stable within each bucket (Array.sort is
  *  stable) so registry order survives ties. */
 export function sortUpdateItems(items) {
-    const kindRank = (k) => (k === "webui" ? 0 : k === "pi-core" ? 1 : 2);
+    const kindRank = (k) => (k === "webui" ? 0 : k === "pi-core" ? 1 : k === "plugin" ? 2 : 3);
     return [...items].sort((a, b) => {
         const ka = kindRank(a.kind);
         const kb = kindRank(b.kind);

package/dist/server/uploads.js

@@ -23,11 +23,26 @@ export function uploadRetentionDays() {
     const v = Number(process.env.PI_WEB_UPLOAD_RETENTION_DAYS);
     return Number.isFinite(v) && v >= 0 ? v : 14;
 }
-/** Persist an uploaded buffer; returns the absolute path + sanitized display name. */
+/** clientId 白名单：clientId 来自浏览器自报（ws hello），却直接拼进上传目录
+ *  路径 —— 只允许安全的单段字符（字母数字、:、_、-，1-128 长），否则可
+ *  "../" 遍历写任意目录。不匹配整条拒绝抛错：绝不能静默换 randomUUID，
+ *  上传目录必须与 ws 会话一一对应（编辑重问靠 uploadPath 按同一目录找回）。 */
+export const CLIENT_ID_PATTERN = /^[A-Za-z0-9:_-]{1,128}$/;
+/** Persist an uploaded buffer; returns the absolute path + sanitized display name.
+ *  clientId 不匹配白名单、displayName 为空 / "." / ".." 时抛错，调用方负责报错。 */
 export function saveUpload(clientId, name, buf, dataDir = resolveDataDir()) {
+    if (!CLIENT_ID_PATTERN.test(clientId)) {
+        throw new Error(`Invalid upload clientId: ${JSON.stringify(clientId.slice(0, 129))}`);
+    }
+    // displayName 只取 basename 并拒绝 "." / ".."：防 ".." 与绝对路径拼接穿越
+    // （最终文件名带 <ts>- 前缀兜底，这里从源头收紧）。
+    const base = name.split(/[\\/]/).pop() ?? "";
+    if (!base || base === "." || base === "..") {
+        throw new Error(`Invalid upload name: ${JSON.stringify(name.slice(0, 129))}`);
+    }
+    const displayName = base.replace(/[\\/:*?"<>|\x00-\x1f]/g, "_").slice(0, 80) || "file";
     const dir = join(uploadsRoot(dataDir), clientId);
     mkdirSync(dir, { recursive: true });
-    const displayName = name.replace(/[\\/:*?"<>|\x00-\x1f]/g, "_").slice(0, 80) || "file";
     const abs = join(dir, `${Date.now()}-${displayName}`);
     writeFileSync(abs, buf);
     return { abs, displayName };

package/dist/server/wait-subscription-scan.js

@@ -24,7 +24,7 @@
 // background subagent run, so its runtime must be kept alive across project /
 // conversation switches. See the Chinese block above for the persistence layout
 // and the fail-open vs fail-closed rationale.
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { homedir, tmpdir, userInfo } from "node:os";
 import path from "node:path";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -114,25 +114,32 @@ export function resolveAsyncRunsDir(env = process.env) {
     return path.join(resolveTempRoot(env), "async-subagent-runs");
 }
 /**
- * 活跃 run marker 的最长可信存活期：对齐 pi-subagents
- * active-run-index.ts 的 DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS（24h）。
- * 崩溃遗留的 marker 超过该时长即视为孤儿，不阻止运行时释放（保留自限）。
+ * 【已废弃】按 marker mtime 的 24h 孤儿守卫（原 DEFAULT_STALE_ACTIVE_MARKER_MS）
+ * 已移除：run 是否终结改由 status.json 的 state 判定（见 hasActiveSubagentRun）。
+ * mtime 只能说明「marker 很久没动」，对 >24h 的超长 run 会误杀活跃证据。
  */
-export const DEFAULT_STALE_ACTIVE_MARKER_MS = 24 * 60 * 60 * 1000;
 /** 活跃 marker 索引目录名，与 pi-subagents 的 ACTIVE_RUN_INDEX_DIR 一致。 */
 const ACTIVE_RUN_INDEX_DIR = ".active-runs";
 /**
  * 磁盘扫描：该会话是否还有活跃（queued/running）的 pi-subagents 异步 run。
- * 任何 I/O / 解析 / 过期错误都按「无证据」处理（fail-open，见文件头说明）。
+ * 任何 I/O / 解析错误都按「无证据」处理（fail-open，见文件头说明）。
  * ENOENT（目录/文件尚不存在、marker 刚被清掉）保持静默；其余 I/O 错误
  * console.warn 一次（与 hasPendingWaitSubscription 对齐）。
+ *
+ * run 是否已终结的廉价判据是 status.json 的 state 字段——它本来就在同一循环
+ * 里逐 marker 读取，零额外 I/O。孤儿清理因此只作用于「已终结 run」的遗留
+ * marker（终结态在下方无条件判为无证据）；曾按 marker mtime 超 24h 一律
+ * 跳过的旧守卫已移除：它同样命中「超长 run（>24h 仍在跑）」的活跃 marker，
+ * 会把正常运行误杀成孤儿、提前释放运行时，父会话永远等不到 wake。与上游
+ * pi-subagents 的 DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS 语义对齐——24h
+ * 自限只该管 terminal marker，不该管还声称存活的 run。代价：进程崩溃遗留
+ * 的 queued/running status 不再随 mtime 过期自动失效，其代价（多保留一个
+ * 空闲运行时）远小于误杀超长 run 的静默停滞。
  */
 export function hasActiveSubagentRun(options) {
     const sessionId = options.sessionId;
     if (!sessionId)
         return false;
-    const now = options.now ?? Date.now;
-    const staleMarkerMs = options.staleMarkerMs ?? DEFAULT_STALE_ACTIVE_MARKER_MS;
     const warn = options.warn ?? ((message, error) => console.warn(message, error));
     const isNotFound = (error) => typeof error === "object" &&
         error !== null &&
@@ -152,18 +159,6 @@ export function hasActiveSubagentRun(options) {
     for (const runId of markers) {
         if (runId.startsWith("."))
             continue; // 不把隐藏文件当 run 证据
-        const markerFile = path.join(indexDir, runId);
-        // 孤儿防护：marker 太久没被 touch（崩溃遗留，run 早已不在）→ 无证据。
-        try {
-            const ageMs = now() - statSync(markerFile).mtimeMs;
-            if (ageMs > staleMarkerMs)
-                continue;
-        }
-        catch (error) {
-            if (!isNotFound(error))
-                warn(`Failed to stat active-run marker '${markerFile}':`, error);
-            continue; // ENOENT（刚被清除的竞态）→ 无证据
-        }
         let status;
         try {
             status = JSON.parse(readFileSync(path.join(runsDir, runId, "status.json"), "utf-8"));
@@ -178,8 +173,10 @@ export function hasActiveSubagentRun(options) {
         const probe = status;
         if (probe.sessionId !== sessionId)
             continue; // 别的会话的 run
+        // 终结态（complete/failed/stopped/…）→ run 已结束：遗留 marker 按孤儿
+        // 清理对待，无条件不算证据；只有 queued/running 才是活跃证据。
         if (probe.state !== "queued" && probe.state !== "running")
-            continue; // 已结束
+            continue;
         return true;
     }
     return false;

package/dist/server/workspace-snapshot.js

@@ -0,0 +1,113 @@
+/**
+ * server/workspace-snapshot.ts
+ *
+ * 工作区版本影子快照机制（Workspace Snapshot / Dual-State Rollback）。
+ *
+ * 每次用户发起新任务或运行关键操作前，为当前工作区记录轻量快照引用（Git commit SHA）。
+ * 机制：
+ * - 利用独立的临时 GIT_INDEX_FILE，通过 `git add -A` + `git write-tree` + `git commit-tree` 生成独立 commit；
+ * - 绝不改变用户现有的 HEAD、branch 指针、工作区文件或 .git/index；
+ * - 回滚时若启用 restoreWorkspace，通过 `git checkout <snapshotRef> -- .` 与 `git clean -fd` 还原物理文件。
+ */
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { gitDirOf } from "./scm.js";
+const exec = promisify(execFile);
+/** 单次 git 快照/还原命令超时时间（毫秒）。 */
+const GIT_SNAPSHOT_TIMEOUT_MS = 15_000;
+/** 执行单条 git 命令，返回 stdout。 */
+async function runGit(cwd, args, envExtra) {
+    const { stdout } = await exec("git", ["-c", "core.quotepath=false", ...args], {
+        cwd,
+        env: envExtra ? { ...process.env, ...envExtra } : process.env,
+        timeout: GIT_SNAPSHOT_TIMEOUT_MS,
+        maxBuffer: 16 * 1024 * 1024,
+        windowsHide: true,
+    });
+    return stdout.trim();
+}
+/** 检查工作区是否由 Git 管理。 */
+export async function isGitWorkspace(cwd) {
+    return (await gitDirOf(cwd)) !== null;
+}
+/**
+ * 为当前工作区创建轻量版本快照。
+ * 若当前目录不在 Git 仓库内，返回 null。
+ *
+ * 该操作纯粹在临时 index 文件中完成，绝不影响用户的实际 index 或 HEAD。
+ */
+export async function createWorkspaceSnapshot(cwd) {
+    const gitDir = await gitDirOf(cwd);
+    if (!gitDir)
+        return null;
+    const tempIndex = join(gitDir, `temp-index-snapshot-${randomUUID()}`);
+    const env = { GIT_INDEX_FILE: tempIndex };
+    try {
+        // 1. 将当前工作区所有改动（含未跟踪与新增）记录到临时 index
+        await runGit(cwd, ["add", "-A"], env);
+        // 2. 写入 tree 对象
+        const tree = await runGit(cwd, ["write-tree"], env);
+        if (!tree)
+            return null;
+        // 3. 检查是否有 HEAD commit 作为 parent
+        let hasHead = false;
+        try {
+            await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+            hasHead = true;
+        }
+        catch {
+            hasHead = false;
+        }
+        // 4. 创建轻量 commit 对象，不关联任何分支引用
+        const commitArgs = ["commit-tree", tree];
+        if (hasHead) {
+            commitArgs.push("-p", "HEAD");
+        }
+        commitArgs.push("-m", `pi-web-ui: workspace shadow snapshot ${new Date().toISOString()}`);
+        const commitHash = await runGit(cwd, commitArgs, env);
+        return commitHash || null;
+    }
+    catch (err) {
+        console.warn(`[workspace-snapshot] 创建快照失败 (${cwd}):`, err.message);
+        return null;
+    }
+    finally {
+        // 务必清理临时 index 文件
+        try {
+            await rm(tempIndex, { force: true });
+        }
+        catch {
+            // ignore cleanup error
+        }
+    }
+}
+/**
+ * 将工作区物理文件还原到指定的快照状态。
+ *
+ * 执行步骤：
+ * 1. `git read-tree -u --reset <snapshotRef>` 将 index 与工作区重置为快照树，并删除快照之后新增的文件；
+ * 2. `git clean -fd` 清理快照之后新增的未跟踪文件与空目录。
+ */
+export async function restoreWorkspaceSnapshot(cwd, snapshotRef) {
+    const gitDir = await gitDirOf(cwd);
+    if (!gitDir) {
+        return { success: false, error: "Workspace is not a Git repository" };
+    }
+    try {
+        // 验证 snapshotRef 合法性
+        await runGit(cwd, ["rev-parse", "--verify", snapshotRef]);
+        // 1. 将 index 和工作区彻底重置到快照树状态（自动清除快照中不存在的文件）
+        await runGit(cwd, ["read-tree", "-u", "--reset", snapshotRef]);
+        // 2. 清理新产生的未跟踪文件与目录
+        await runGit(cwd, ["clean", "-fd"]);
+        return { success: true };
+    }
+    catch (err) {
+        const msg = err.message;
+        console.error(`[workspace-snapshot] 还原快照失败 (${cwd}, ${snapshotRef}):`, msg);
+        return { success: false, error: msg };
+    }
+}