pi-web-ui 0.92.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

@@ -6,18 +6,17 @@
 // 强制锁会死锁（见 claim-store.ts 文件头）。先到先得；自己的可刷新，
 // 别人的动不了；过期自动释放 + 发 prompt 心跳续期 + 对话关闭释放。
 //
-// 常驻工具、不进 AGENT_TOOL_CATALOG（例外，理由见下）：目录里的每个工具都
-// 必须在设置页有行（settings-tool-rows.test.ts 强制），而 web/src 正被并行
-// 任务占用。认领是纯 advisory（关掉只会少提醒），常驻默认开可接受；目录项 +
-// 设置行等 web/src 空出来后补（follow-up）。DSH 引擎无 customTool 注册面，
-// 只有 pi 引擎对话能认领（提醒是服务端算的，DSH 照样能看到别人的认领）。
+// 开关走统一工具 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";
-/** 工具名（改名需同步改 agent-service 注册处注释与单测）。 */
-export const CLAIM_FILES_TOOL_NAME = "claim_files";
+/** 工具名（唯一定义在 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`;

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,7 @@ 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
@@ -432,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,
@@ -474,6 +531,7 @@ 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,
@@ -483,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,

package/dist/server/conversation-read-tool.js

@@ -22,6 +22,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { bilingual, pick } from "./i18n.js";
+import { CONVERSATION_READ_TOOL_NAME } from "./tool-manager.js";
 import { extractTouches, formatTouchEntry, formatTouchesCompact, toolCallRefsOfContent, unionTouchLists, } from "./conversation-touches.js";
 /** 由 content 块提 toolCalls 字段（additive；格式化输出不受影响，见接口注释）。 */
 function fillToolCalls(target, content) {
@@ -366,7 +367,7 @@ export function makeConversationReadTool(host, lang, extras) {
         details,
     });
     return defineTool({
-        name: "conversation_read",
+        name: CONVERSATION_READ_TOOL_NAME,
         label: "Read another conversation",
         description: bilingual('Read ANOTHER conversation: a running conversation of this client (including subagents — use its conversation id like "c3", see action=list) or a persisted history session transcript (use its file path). ' +
             'Use it when the user references another chat (a quoted conversation, a pasted conversation id, or "see the other chat about X"). ' +

package/dist/server/delegate-task.js

@@ -17,9 +17,10 @@
 import { Type } from "typebox";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { bilingual, pick } from "./i18n.js";
+import { DELEGATE_TASK_TOOL_NAME } from "./tool-manager.js";
 import { subagentTitle } from "./subagents.js";
-/** 工具名（前端 ToolCallBlock 派单卡片靠它识别；改名需同步改前端）。 */
-export const DELEGATE_TOOL_NAME = "delegate_task";
+/** 工具名（唯一值在 tool-manager.ts；本别名保留：前端派单卡片与旧导入沿用它）。 */
+export const DELEGATE_TOOL_NAME = DELEGATE_TASK_TOOL_NAME;
 /** 各段最小长度（trim 后字符数）：TASK 必须具体，OUTCOME 必须可验收，其余段不许空着。 */
 const MIN_TASK = 20;
 const MIN_OUTCOME = 10;
@@ -40,6 +41,7 @@ export function normalizeDelegation(params) {
         must_not_do: str(p.must_not_do),
         context: str(p.context),
         model: str(p.model).trim() || undefined,
+        persist: typeof p.persist === "boolean" ? p.persist : undefined,
     };
 }
 /**
@@ -122,6 +124,11 @@ const delegateSchema = Type.Object({
     model: Type.Optional(Type.String({
         description: bilingual('Optional model "provider/id" for this delegation; omit = template model → panel default → follow the main conversation model.', "可选：本次派单的子代理模型（provider/id）；不传 = 模板模型 → 面板默认 → 跟随主对话模型。"),
     })),
+    persist: Type.Optional(Type.Boolean({
+        description: bilingual("Optional: persist this conversation to disk as a regular session (saved in history, resumable). " +
+            "Default false (lightweight in-memory subagent). Use true for tasks that need long-term retention.", "可选：是否将该对话持久化落盘为普通对话（保存在历史会话中，可随时回顾与继续）。" +
+            "默认 false（轻量内存子代理）。需要长期留存的任务建议设为 true。"),
+    })),
 });
 /** 结构化派单工具：校验六段 → 拼装标准 prompt → 走 host.spawnSubagent 真子代理。 */
 export function makeDelegateTaskTool(host, lang) {
@@ -163,7 +170,7 @@ export function makeDelegateTaskTool(host, lang) {
             // 创建失败都经由 host 抛错），转成返回文本让 AI 能读到原因并修正重试。
             let convId;
             try {
-                convId = await host.spawnSubagent(prompt, "delegate", ctx.cwd, input.agent, input.model);
+                convId = await host.spawnSubagent(prompt, "delegate", ctx.cwd, input.agent, input.model, undefined, input.persist);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);

package/dist/server/dsh/dsh-agent-service.js

@@ -29,12 +29,14 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { BgServerTracker } from "../bg-servers.js";
-import { ClientStateStore, DEFAULT_RETRY_MAX_ATTEMPTS } from "../client-state.js";
+import { ClientStateStore, DEFAULT_RETRY_MAX_ATTEMPTS, normalizeToolWatchdogTimeoutMs } from "../client-state.js";
 import { normalizeUiLayout } from "../client-state.js";
 import { FilesService, workspacePath, desktopDirWire } from "../files-service.js";
 import { QuiesceRejectedError } from "../agent-service.js";
 import { NATIVE_COMMANDS, parseSlash } from "../slash-commands.js";
 import { bilingual, pick, resolveServerLang } from "../i18n.js";
+// 工具定义说明的归一化（工具卡右键 → 「显示工具详细信息」，见 getToolInfo）。
+import { normalizeToolInfo, unsupportedToolInfo } from "../tool-info.js";
 import { TerminalManager, loadCommands, saveCommandsFile } from "../terminals.js";
 import { saveUpload } from "../uploads.js";
 import { checkAll as checkAllUpdates, collectTargets, resolveNpmRegistry } from "../update-check.js";
@@ -122,12 +124,14 @@ const DEFAULT_SETTINGS = {
     terminalToolsEnabled: false,
     terminalBash: false,
     terminalBashIdleMs: 15_000,
+    toolWatchdogTimeoutMs: 20 * 60_000,
     editSoftEnabled: false,
     questionnaireEnabled: true,
     goalModeEnabled: true,
     parallelReminderEnabled: true,
     thinkingWrap: false,
     toolsWrap: true,
+    toolImagesEnabled: true,
     disabledPlugins: [],
     uiLayout: {},
     reviewPrompt: "",
@@ -267,12 +271,14 @@ export class DshClientSession {
                 terminalToolsEnabled: savedSettings.terminalToolsEnabled,
                 terminalBash: savedSettings.terminalBash,
                 terminalBashIdleMs: savedSettings.terminalBashIdleMs,
+                toolWatchdogTimeoutMs: savedSettings.toolWatchdogTimeoutMs ?? 20 * 60_000,
                 editSoftEnabled: savedSettings.editSoftEnabled,
                 questionnaireEnabled: savedSettings.questionnaireEnabled ?? true,
                 goalModeEnabled: savedSettings.goalModeEnabled ?? true,
                 parallelReminderEnabled: savedSettings.parallelReminderEnabled ?? true,
                 thinkingWrap: savedSettings.thinkingWrap,
                 toolsWrap: savedSettings.toolsWrap,
+                toolImagesEnabled: savedSettings.toolImagesEnabled ?? true,
                 disabledPlugins: savedSettings.disabledPlugins ?? [],
                 uiLayout: normalizeUiLayout(savedSettings.uiLayout),
                 reviewPrompt: savedSettings.reviewPrompt,
@@ -563,16 +569,22 @@ export class DshClientSession {
                     // 记下待答问卷：`question_pending` 只推给「当时在线」的连接，刷新页面
                     // /WS 重连后靠快照（UiState.pendingQuestion）把对话框恢复出来。
                     // DSH 的提问桥是 runtime 级的（无 conversationId），故不分对话。
+                    const dshConv = this.convs.get(this.activeId);
+                    const conversationTitle = dshConv?.title;
                     this.pendingQuestion = {
                         id: params0.id,
                         ...(typeof params0.deadline === "number" ? { deadline: params0.deadline } : {}),
                         questions: mapped,
+                        ...(this.activeId ? { conversationId: this.activeId } : {}),
+                        ...(conversationTitle ? { conversationTitle } : {}),
                     };
                     this.emit({
                         type: "question_pending",
                         id: params0.id,
                         ...(typeof params0.deadline === "number" ? { deadline: params0.deadline } : {}),
                         questions: mapped,
+                        ...(this.activeId ? { conversationId: this.activeId } : {}),
+                        ...(conversationTitle ? { conversationTitle } : {}),
                     });
                 }
                 else if (method === "tools.call.request") {
@@ -658,6 +670,28 @@ export class DshClientSession {
             console.error(`[dsh] syncPluginTools 失败 (client=${this.clientId}):`, err);
         }
     }
+    /**
+     * 取一条工具的**定义说明**（工具卡右键 → 「显示工具详细信息」）→ `tool_info`。
+     *
+     * DSH 侧的定义来自运行时（`tools/list`：DSH 原生工具 + 桥接进来的插件工具）。
+     * 拿不到（运行时没起来 / RPC 报错）回 `unsupported`，让前端说「当前引擎不支持」
+     * 而不是「未找到工具定义」—— 后者会让用户以为工具名写错了。
+     */
+    async getToolInfo(name) {
+        if (!this.runtime.alive) {
+            this.emit({ type: "tool_info", ...unsupportedToolInfo(name) });
+            return;
+        }
+        try {
+            const res = await this.runtime.listTools();
+            const found = (res.tools ?? []).find((t) => t.name === name);
+            this.emit({ type: "tool_info", ...normalizeToolInfo(name, found) });
+        }
+        catch (err) {
+            console.error(`[dsh] listTools 失败 (client=${this.clientId}):`, err);
+            this.emit({ type: "tool_info", ...unsupportedToolInfo(name) });
+        }
+    }
     /** 从运行时拉取技能清单 → 缓存 → 重推 settings_state（enabled 由 disabledSkills 推导）。 */
     async refreshSkillsFromRuntime() {
         if (!this.runtime.alive)
@@ -2590,6 +2624,7 @@ export class DshClientSession {
             terminalToolsEnabled: this.settings.terminalToolsEnabled,
             terminalBash: this.settings.terminalBash,
             terminalBashIdleMs: this.settings.terminalBashIdleMs,
+            toolWatchdogTimeoutMs: this.settings.toolWatchdogTimeoutMs,
             // DSH 引擎无 customTool 注册面（工具来自 shipped preset），read 目录覆盖面不存在。
             readDirEnabled: true,
             editSoftEnabled: this.settings.editSoftEnabled,
@@ -2603,6 +2638,7 @@ export class DshClientSession {
             parallelReminderEnabled: this.settings.parallelReminderEnabled,
             thinkingWrap: this.settings.thinkingWrap,
             toolsWrap: this.settings.toolsWrap,
+            toolImagesEnabled: this.settings.toolImagesEnabled,
             // DSH 无 skill 全文注入概念，给空保协议完整。
             skillsFullText: [],
             visionBridgeEnabled: false,
@@ -2659,6 +2695,8 @@ export class DshClientSession {
             this.settings.terminalBash = partial.terminalBash;
         if (partial.terminalBashIdleMs !== undefined)
             this.settings.terminalBashIdleMs = partial.terminalBashIdleMs;
+        if (partial.toolWatchdogTimeoutMs !== undefined)
+            this.settings.toolWatchdogTimeoutMs = normalizeToolWatchdogTimeoutMs(partial.toolWatchdogTimeoutMs);
         if (partial.editSoftEnabled !== undefined)
             this.settings.editSoftEnabled = partial.editSoftEnabled;
         if (partial.questionnaireEnabled !== undefined)
@@ -2671,6 +2709,8 @@ export class DshClientSession {
             this.settings.thinkingWrap = partial.thinkingWrap;
         if (partial.toolsWrap !== undefined)
             this.settings.toolsWrap = partial.toolsWrap;
+        if (partial.toolImagesEnabled !== undefined)
+            this.settings.toolImagesEnabled = partial.toolImagesEnabled;
         if (partial.disabledPlugins !== undefined)
             this.settings.disabledPlugins = partial.disabledPlugins;
         if (partial.uiLayout !== undefined)
@@ -2706,6 +2746,7 @@ export class DshClientSession {
             parallelReminderEnabled: this.settings.parallelReminderEnabled,
             thinkingWrap: this.settings.thinkingWrap,
             toolsWrap: this.settings.toolsWrap,
+            toolImagesEnabled: this.settings.toolImagesEnabled,
             disabledPlugins: this.settings.disabledPlugins,
             uiLayout: normalizeUiLayout(this.settings.uiLayout),
             reviewPrompt: this.settings.reviewPrompt,
@@ -3071,6 +3112,7 @@ export class DshClientSession {
             editSoftEnabled: this.settings.editSoftEnabled,
             thinkingWrap: this.settings.thinkingWrap,
             toolsWrap: this.settings.toolsWrap,
+            toolImagesEnabled: this.settings.toolImagesEnabled,
             disabledPlugins: this.settings.disabledPlugins,
             uiLayout: normalizeUiLayout(this.settings.uiLayout),
             reviewPrompt: this.settings.reviewPrompt,

package/dist/server/files-service.js

@@ -5,7 +5,7 @@
  * 全部为无状态 fs 操作 + 两个自持的 watcher（当前列出目录、git dir），
  * 经 FilesHost 回调与 ClientSession 解耦。
  */
-import { mkdirSync, readFileSync, statSync, writeFileSync, watch } from "node:fs";
+import { Dirent, mkdirSync, readFileSync, statSync, writeFileSync, watch } from "node:fs";
 import { homedir } from "node:os";
 import { resolve, relative, sep } from "node:path";
 import { pick } from "./i18n.js";
@@ -57,7 +57,7 @@ export function isAbsoluteWirePath(p) {
  *  不产生结尾斜杠，这里只对补全/直接输入做防御性清理。 */
 export function normWirePath(p) {
     if (p.endsWith("/") && p !== "/")
-        return p.slice(0, -1);
+        return p.replace(/\/+$/, "") || "/";
     return p;
 }
 /** wire 绝对路径（"C:/Users/x" / "/Users/x" / "C:"）→ 原生绝对路径。
@@ -74,7 +74,7 @@ export function wireToAbs(wire) {
 /** 机器浏览模式下某目录的父级 wire 路径：盘符根（"C:"）→ 机器根；posix "/" 无父级。 */
 export function absoluteParent(wire) {
     const s = normWirePath(wire);
-    if (s === "" || s === MACHINE_ROOT)
+    if (s === "" || s === MACHINE_ROOT || s === "/")
         return null;
     const i = s.lastIndexOf("/");
     if (i < 0)
@@ -150,8 +150,9 @@ export function workspacePath(root, raw) {
  * system dirs (C:\$Recycle.Bin, Program Files internals, OneDrive placeholders)
  * throw EPERM/EACCES on open — that must not kill the panel, so it degrades
  * to an empty listing plus a warning. Directory symlinks/junctions are
- * followed so mklink /D folders stay navigable; broken links still show as
- * files instead of vanishing. The cap is 4x posix and truncation is reported
+ * followed (all platforms — Android/Termux's ~/storage/* entries are symlinks
+ * too) so folder links stay navigable; broken links still show as files
+ * instead of vanishing. The cap is 4x posix and truncation is reported
  * via `truncated` instead of happening silently.
  */
 async function readDirForUI(abs, rel) {
@@ -178,10 +179,10 @@ async function readDirForUI(abs, rel) {
         if (ignored.has(d.name))
             continue;
         let type;
-        if (IS_WIN32 && d.isSymbolicLink()) {
-            // mklink /D symlinks and junctions are reparse points — libuv
-            // classifies them as links, so isDirectory() is false. Follow the
-            // target so folder links stay navigable; broken links still show.
+        if (d.isSymbolicLink()) {
+            // Symlinks (mklink /D reparse points on win32, but also the directory
+            // links under Termux's ~/storage) are followed on ALL platforms so
+            // folder links stay navigable; broken links still show as files.
             try {
                 const st = await fs.stat(join(abs, d.name));
                 type = st.isDirectory() ? "dir" : "file";
@@ -210,6 +211,26 @@ async function readDirForUI(abs, rel) {
         out.length = MAX;
     return { entries: out, truncated };
 }
+/** dirent → FileEntry classification: directory symlinks are resolved via
+ *  stat() on ALL platforms (#262 — Termux's ~/storage/* entries are symlinks;
+ *  the directory-only cwd picker renders an empty list if they type as files). */
+async function classifyDirent(d, absDir) {
+    const fs = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    let type;
+    if (d.isSymbolicLink()) {
+        try {
+            type = (await fs.stat(join(absDir, d.name))).isDirectory() ? "dir" : "file";
+        }
+        catch {
+            type = "file"; // broken link
+        }
+    }
+    else {
+        type = d.isDirectory() ? "dir" : "file";
+    }
+    return { name: d.name, type };
+}
 export class FilesService {
     host;
     // ---- 当前列出目录的 watcher ----
@@ -248,6 +269,24 @@ export class FilesService {
             }
             return out;
         }
+        // Android/Termux: "/" itself is not listable (even `ls /` is denied),
+        // so fall back to $HOME + shared storage as the machine-root landing
+        // spots — otherwise machine browsing is a dead end on Android.
+        try {
+            await fsp.readdir("/");
+        }
+        catch {
+            const home = homedir();
+            const out = [{ name: home, path: home, type: "dir" }];
+            try {
+                await fsp.readdir("/storage/emulated/0");
+                out.push({ name: "/storage/emulated/0", path: "/storage/emulated/0", type: "dir" });
+            }
+            catch {
+                // no shared storage
+            }
+            return out;
+        }
         return [{ name: "/", path: "/", type: "dir" }];
     }
     /** 单字段错误文本的语言（host 未接线时英文默认）。 */
@@ -286,7 +325,13 @@ export class FilesService {
     async listFiles(relPath) {
         const { resolve, sep, relative } = await import("node:path");
         const root = resolve(this.host.getCwd());
-        const raw = relPath ?? "";
+        let raw = relPath ?? "";
+        // Expand a leading "~/" (path-bar input) to the home directory — same
+        // rules as completePath/makeDir. The result is absolute, so it lands in
+        // the machine-browse branch below; wire paths always use "/".
+        if (raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\")) {
+            raw = (raw === "~" ? homedir() : homedir() + raw.slice(1)).split(sep).join("/");
+        }
         // ---- 机器根（此电脑：盘符列表）—— 工作区之上的虚拟层 ----
         if (raw === MACHINE_ROOT || raw === MACHINE_ROOT + "/") {
             const entries = await this.machineRootEntries();
@@ -342,11 +387,12 @@ export class FilesService {
         else {
             this.watchDir(target, rel);
         }
+        const rootWire = normWirePath(root.split(sep).join("/"));
         this.host.emit({
             type: "files",
             path: rel === "" ? "" : rel,
-            // 工作区根也允许「上一级」→ 机器根（Windows 换盘符 / posix 到 /）。
-            parent: rel === "" ? MACHINE_ROOT : rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "",
+            // 工作区根也允许「上一级」→ 项目文件夹的上一级（盘符根则到机器根，posix 根无父级）。
+            parent: rel === "" ? absoluteParent(rootWire) : rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "",
             entries,
             truncated,
         });
@@ -399,14 +445,25 @@ export class FilesService {
                 if (ignored.has(d.name))
                     continue;
                 const childRel = rel ? `${rel}/${d.name}` : d.name;
+                let isDir = d.isDirectory();
+                if (d.isSymbolicLink()) {
+                    // Follow directory symlinks (Termux's ~/storage/*); the depth
+                    // cap doubles as a symlink-cycle guard, budgets bound the cost.
+                    try {
+                        isDir = (await fsp.stat(join(abs, d.name))).isDirectory();
+                    }
+                    catch {
+                        isDir = false; // broken link — treat as file
+                    }
+                }
                 if (d.name.toLowerCase().includes(q)) {
                     results.push({
                         path: childRel,
                         name: d.name,
-                        type: d.isDirectory() ? "dir" : "file",
+                        type: isDir ? "dir" : "file",
                     });
                 }
-                if (d.isDirectory()) {
+                if (isDir) {
                     await walk(join(abs, d.name), childRel, depth + 1);
                 }
             }
@@ -1344,13 +1401,8 @@ export class FilesService {
                         empty();
                         return;
                     }
-                    const items = dirents
-                        .filter((d) => !ignoredEntries().has(d.name))
-                        .map((d) => ({
-                        name: d.name,
-                        path: `${drive}/${d.name}`,
-                        type: (d.isDirectory() ? "dir" : "file"),
-                    }))
+                    const items = (await Promise.all(dirents.filter((d) => !ignoredEntries().has(d.name)).map((d) => classifyDirent(d, `${drive}\\`))))
+                        .map((e) => ({ ...e, path: `${drive}/${e.name}` }))
                         .sort((a, b) => {
                         const aHidden = a.name.startsWith(".");
                         const bHidden = b.name.startsWith(".");
@@ -1391,14 +1443,14 @@ export class FilesService {
                 return;
             }
             const { join } = await import("node:path");
-            const completions = dirents
+            const completions = (await Promise.all(dirents
                 .filter((d) => d.name.startsWith(prefix) && !ignoredEntries().has(d.name))
-                .map((d) => ({
-                name: d.name,
+                .map((d) => classifyDirent(d, dirPart))))
+                .map((e) => ({
+                ...e,
                 // Windows users type backslashes — normalize the completion to the
                 // wire format ("/") so the picked path round-trips cleanly.
-                path: IS_WIN32 ? join(dirPart, d.name).split(sep).join("/") : dirPart + d.name,
-                type: (d.isDirectory() ? "dir" : "file"),
+                path: IS_WIN32 ? join(dirPart, e.name).split(sep).join("/") : dirPart + e.name,
             }))
                 .sort((a, b) => {
                 const aHidden = a.name.startsWith(".");