@henlii/pidance 0.2.37 → 0.2.40

package/.next/static/qrH41YQOkbPr0RvEZs8IZ/_buildManifest.js

@@ -0,0 +1 @@
+self.__BUILD_MANIFEST={__rewrites:{afterFiles:[],beforeFiles:[],fallback:[]},__routerFilterStatic:{numItems:49,errorRate:1e-4,numBits:940,numHashes:14,bitArray:[1,0,1,0,0,0,1,0,0,0,1,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,0,0,0,1,1,0,1,1,0,1,0,1,0,0,0,1,1,1,1,0,1,0,1,0,1,0,0,0,1,0,0,1,1,0,0,1,0,1,0,1,0,1,1,1,0,0,1,1,1,0,0,0,0,1,0,0,1,1,1,0,1,1,1,1,0,0,0,0,0,1,1,1,0,0,0,0,1,1,1,0,0,0,0,1,1,1,0,0,0,0,0,1,0,0,1,1,0,1,0,0,1,0,0,0,0,0,0,1,0,1,1,1,1,1,0,0,1,1,0,1,1,1,1,0,0,1,0,1,0,0,1,0,1,1,1,0,1,0,1,1,0,0,0,0,0,1,1,1,1,0,1,0,0,0,1,1,1,0,1,1,1,0,0,0,0,0,1,1,1,0,1,1,1,1,0,1,1,0,0,0,1,1,1,1,1,1,0,0,0,0,0,1,1,1,0,0,1,0,1,0,1,0,0,1,0,1,1,1,0,1,0,0,1,0,0,0,0,1,1,0,1,0,0,0,0,0,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,1,0,1,1,1,1,1,1,1,1,1,0,1,1,1,1,0,1,0,0,0,1,1,1,0,0,0,0,1,1,1,0,0,1,0,1,1,1,0,1,1,0,0,1,0,0,1,0,1,1,0,0,1,0,1,0,1,1,0,0,1,0,1,0,1,1,1,0,1,0,1,0,0,0,1,1,1,0,0,0,1,0,1,1,0,1,1,0,1,0,0,0,1,1,1,1,0,1,1,0,0,0,1,1,1,0,1,1,0,0,1,1,0,1,1,1,0,0,1,1,1,0,0,0,1,1,1,0,1,1,0,0,0,1,0,0,1,0,0,0,0,1,0,0,1,0,0,1,0,0,0,1,1,0,0,0,0,0,1,0,0,1,0,0,1,1,1,1,0,0,0,0,0,0,1,1,0,0,1,0,0,1,1,1,0,0,0,1,0,0,1,1,1,0,1,0,0,1,1,1,0,1,1,1,1,1,1,1,1,0,0,1,0,1,0,1,0,0,0,1,0,1,0,0,1,0,1,1,1,0,0,0,1,0,0,1,1,1,1,1,0,1,0,1,0,1,0,1,1,0,0,1,1,1,0,1,0,0,0,0,0,1,1,1,0,0,0,0,0,1,1,0,1,1,1,0,1,1,0,1,0,0,1,1,1,0,0,1,0,0,1,1,1,0,1,0,0,1,0,0,1,1,0,0,1,0,0,0,1,1,1,1,0,1,1,0,1,1,1,0,1,1,0,0,1,0,0,0,1,0,0,1,1,1,0,0,0,0,0,1,0,0,1,0,0,1,1,1,0,0,1,0,1,1,0,1,1,1,1,0,1,1,1,1,1,1,0,0,0,1,1,0,1,1,0,0,0,1,1,1,1,0,1,1,1,0,1,0,1,1,0,1,1,0,0,0,0,1,0,0,0,1,1,0,1,0,1,1,1,0,0,0,1,1,1,1,1,1,0,1,0,1,1,1,1,0,0,1,1,1,1,0,1,1,1,0,0,0,1,0,0,1,1,0,0,0,0,1,1,0,0,1,1,0,0,0,1,0,1,0,0,1,0,0,0,1,1,1,0,0,0,1,1,1,0,1,0,1,0,1,1,1,0,1,1,0,0,1,0,0,1,1,0,1,1,0,0,0,0,0,1,0,1,1,0,0,0,0,0,1,0,1,0,0,0,1,0,1,1,0,1,0,0,1,1,1,1,0,1,0,0,0,0,1,1,0,1,1,1,0,1,0,1,1,0,0,1,0,0,0,0,0,0,1,0,1,0,1,0,0,1,1,1,1,0,1,0,1,0,1,1,0,0,0,0,0,1,1,1,0,1,0,0,1,0,0,0,0,1,0,0,1,0,0,0,1,0,1,0,0,1,0,1,0,0,0,0,1,0,1,0,1,1,0,0,1,0,1,0,0,1,0,1,0,1,0,1,0,0,1,0,1,1,0,1,1,1,1,1,0,0,0,1,1,1,1,0,0,1,1,0,0,1,0,0,0,1,1,1,1,0,1,1,1,0,0,0,1]},__routerFilterDynamic:{numItems:8,errorRate:1e-4,numBits:154,numHashes:14,bitArray:[1,0,0,0,1,1,1,0,1,0,1,1,1,1,1,1,1,1,0,1,0,0,1,0,1,0,0,1,1,0,0,0,1,1,0,1,0,1,1,0,1,1,1,1,0,1,1,1,1,0,1,0,0,0,0,1,0,0,1,1,0,1,0,1,0,1,1,1,1,1,0,1,1,0,0,1,1,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,1,0,0,1,1,1,0,1,0,1,0,0,1,1,1,1,0,0,0,0,0,1,1,1,1,0,0,0,1,1,0,0,1,1,1,1,1,1,1,1,0,1,1,0,1,0,1,0,0,1,0,0,0,0,1,1,1,0,0,0,1,0]},sortedPages:["/_app"]},self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();

package/README.en.md

@@ -10,7 +10,16 @@
 
 Pidance is an open-source web client for the [Pi](https://github.com/badlogic/pi-mono) coding agent. It reads local Pi session files directly and preserves Pi SDK session and runtime semantics, bringing live chat, project files, Git, subagents, and configuration into one browser workspace. Pi remains the source of truth for data and execution semantics; Pidance provides a clearer and more complete interface.
 
-> Current version: `0.2.37` · npm package: `@henlii/pidance` · CLI: `pidance`
+> Current version: `0.2.40` · npm package: `@henlii/pidance` · CLI: `pidance`
+
+## Design principles
+
+**Compatibility first, then general display improvements on top of it.**
+
+1. **Content completeness comes first.** Pidance aims to let you experience what a native TUI session shows — **including extension (plugin) custom UI** — in the browser. Anything the native TUI can display, Pidance should display too; prefer showing it as-is over hiding it because it “looks off on the web”.
+2. **Compatibility outranks looks.** Content a plugin expresses through the TUI extension API (self-drawn components, overlays, widgets, status lines, dialogs) must always have a landing spot. When a capability is missing, degrade **visibly** — notify or return an explicit value, never drop it silently (silence makes plugin authors think it worked).
+3. **Improvements must be general.** Display-layer work (layout, collapsing, card shells, titles, accessibility) goes through mechanisms shared by every plugin — no per-plugin special cases. Plugin-specific code is allowed only in the compatibility layer: parsing a plugin's private payloads, or bridging TUI semantics to the web.
+4. **Pi stays the source of truth.** Session files, tool execution, compaction and branch semantics are decided by the Pi SDK; Pidance only projects and presents them. See [`docs/ui-vs-tui.md`](./docs/ui-vs-tui.md) for the surface-by-surface mapping.
 
 ## Preview
 

package/README.md

@@ -10,7 +10,16 @@
 
 Pidance 是面向 [Pi](https://github.com/badlogic/pi-mono) coding agent 的开源 Web 客户端。它直接读取本机 Pi 会话文件，并沿用 Pi SDK 的会话与运行时语义，把实时对话、项目文件、Git、工作树、子代理和配置管理汇集到一个浏览器工作区。Pi 仍是数据与执行语义的事实来源；Pidance 负责提供更清晰、更完整的操作界面。
 
-> 当前版本：`0.2.37` · npm 包：`@henlii/pidance` · CLI：`pidance`
+> 当前版本：`0.2.40` · npm 包：`@henlii/pidance` · CLI：`pidance`
+
+## 设计原则
+
+**兼容优先，然后在兼容之上做通用的显示优化。**
+
+1. **内容完整优先**：Pidance 的目标是在浏览器里体验原生 TUI 会话的内容，**包括扩展（插件）自定义的界面**。原生 TUI 里能显示的东西，Pidance 都要能显示；宁可先原样呈现，也不要因为「Web 里不好看」而少显示。
+2. **兼容高于观感**：插件用 TUI 扩展 API 表达的内容（自绘组件、overlay、widget、状态条、对话框）都必须有落点。暂不具备的能力按**可见方式**降级——给出提示或明确返回值，不静默丢弃（静默会让插件作者以为生效了）。
+3. **优化必须通用**：显示层的改进（排版、折叠、卡片壳、标题、无障碍）要走所有插件共用的机制，不为个别插件写特例。插件专属代码只允许出现在兼容层：解析它发的私有载荷、把 TUI 语义桥到 Web。
+4. **Pi 仍是事实来源**：会话文件、工具执行、压缩与分支语义由 Pi SDK 决定；Pidance 不复制、不覆盖这些语义，只负责投影与呈现。界面分区对照见 [`docs/ui-vs-tui.md`](./docs/ui-vs-tui.md)。
 
 ## 界面预览
 

package/bin/pidance-auth-gate.js

@@ -2,11 +2,50 @@
 
 // 启动认证门禁纯逻辑（CLI 门禁用；与 lib/request-guard.ts 的 isLoopbackHost 语义保持一致）：
 // 监听非回环地址且未设置认证密码 → 拒绝启动（fail-closed，发布阻断 P0）。
-// 密码来源：PIDANCE_PASSWORD 优先（产品名），兼容回退旧变量 PI_WEB_PASSWORD。
+// 密码来源：启动缓存（已搬走）→ PIDANCE_PASSWORD（产品名）→ 旧变量 PI_WEB_PASSWORD。
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { isIP } = require("net");
 
+/**
+ * 进程内密码缓存键，与 lib/request-guard.ts 的 __piAuthPassword 同形。
+ *
+ * 同进程共享：middleware / route / CLI 共用 globalThis（Next 的 Node middleware 是
+ * require 进同进程的），所以 CLI 写、服务端读。
+ */
+const AUTH_PASSWORD_CACHE_KEY = "__piAuthPassword";
+
+function readPasswordFromEnv(env) {
+  const p =
+    env && env.PIDANCE_PASSWORD && env.PIDANCE_PASSWORD.length > 0
+      ? env.PIDANCE_PASSWORD
+      : env && env.PI_WEB_PASSWORD;
+  return typeof p === "string" && p.length > 0 ? p : null;
+}
+
+/** 解析认证密码：启动缓存优先，否则读 env。 */
+function resolvePassword(env) {
+  const cached = globalThis[AUTH_PASSWORD_CACHE_KEY];
+  if (cached) return cached.value;
+  return readPasswordFromEnv(env);
+}
+
+/**
+ * 把 env 里的密码搬进进程内缓存，并从 process.env 删掉两个变量名。
+ *
+ * 为什么必须搬：主 agent 的 SDK bash 工具用 `{ ...process.env }` 构造命令环境，
+ * 密码留在 env 里会被 agent 一条 `env` 打进会话并永久落盘。删掉后命令环境拿不到，
+ * 认证改读缓存（只删不搬会让 resolvePassword fail-open）。
+ * 缓存不写盘。
+ */
+function primeAndScrubPassword(env = process.env) {
+  const value = readPasswordFromEnv(env);
+  globalThis[AUTH_PASSWORD_CACHE_KEY] = { value };
+  delete env.PIDANCE_PASSWORD;
+  delete env.PI_WEB_PASSWORD;
+  return value;
+}
+
 /** host 是否为回环（localhost / *.localhost / IPv4 127.x / IPv6 ::1）。 */
 function isLoopbackHost(host) {
   if (typeof host !== "string" || host.length === 0) return false; // 未指定 → Pidance 默认绑定 127.0.0.1
@@ -19,15 +58,6 @@ function isLoopbackHost(host) {
   return false;
 }
 
-/** 解析认证密码：PIDANCE_PASSWORD 优先（产品名，空/缺失时回退），兼容旧变量 PI_WEB_PASSWORD。 */
-function resolvePassword(env) {
-  const p =
-    env && env.PIDANCE_PASSWORD && env.PIDANCE_PASSWORD.length > 0
-      ? env.PIDANCE_PASSWORD
-      : env && env.PI_WEB_PASSWORD;
-  return typeof p === "string" && p.length > 0 ? p : null;
-}
-
 /**
  * 是否需要强制认证：非回环监听地址 + 未设置密码（env 明文或设置 → 通用 保存的服务端密码）。
  * serverConfig 来自 bin/pidance-server-config.js 的 { passwordSet, remoteEnabled } 投影。
@@ -44,4 +74,4 @@ function describeHost(host) {
   return typeof host === "string" && host.length > 0 ? host : "127.0.0.1（默认本机绑定）";
 }
 
-module.exports = { isLoopbackHost, resolvePassword, shouldRequireAuth, describeHost };
+module.exports = { isLoopbackHost, resolvePassword, primeAndScrubPassword, shouldRequireAuth, describeHost };

package/bin/pidance-http-server.js

@@ -58,6 +58,13 @@ async function startPidanceHttpServer(options) {
   const handle = app.getRequestHandler();
   const server = createHttpServer((req, res) => {
     installUpgradeHandler();
+    // 对端地址是我们唯一可信的客户端身份来源：先删掉客户端自带的同名头，
+    // 再写入 socket 地址。限流分桶读它（middleware 里读不到 socket）。
+    if (req.headers) {
+      delete req.headers["x-pidance-peer-ip"];
+      const address = req.socket?.remoteAddress;
+      if (address) req.headers["x-pidance-peer-ip"] = address;
+    }
     // Next 的 compress 只在它自己的内置服务器（router-server）里生效；
     // 自管 server 必须自己压缩，否则 JSON/HTML 明文下发。
     // 见 bin/pidance-compression.js。

package/bin/pidance.js

@@ -12,7 +12,7 @@ const { parseLaunchOptions } = require("./pidance-options");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { loadServerConfig } = require("./pidance-server-config");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const { shouldRequireAuth, resolvePassword, describeHost } = require("./pidance-auth-gate");
+const { shouldRequireAuth, resolvePassword, primeAndScrubPassword, describeHost } = require("./pidance-auth-gate");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { startPidanceHttpServer } = require("./pidance-http-server");
 
@@ -39,6 +39,10 @@ if (!nodeMeetsMin(process.versions.node)) {
 
 const { port: explicitPort, hostname: explicitHostname, openBrowser } = parseLaunchOptions();
 const serverConfig = loadServerConfig();
+// 密码只活在进程内缓存里：把 env 里的密码搬进缓存、再删掉两个变量名。
+// 必须在启动 Next 之前做——middleware / route / SDK bash 都在同一进程，读的是 globalThis
+// 缓存；env 里留着的密码会被 agent 的 bash 一条 `env` 打进会话并永久落盘。
+primeAndScrubPassword(process.env);
 // 默认绑定：设置 → 通用 开启远程服务 → 0.0.0.0；否则仅本机 127.0.0.1（免密码）。
 // 显式 --hostname / -H / HOSTNAME env 优先；显式 0.0.0.0 仍走密码门禁。
 const hostname = explicitHostname ?? (serverConfig.remoteEnabled ? "0.0.0.0" : "127.0.0.1");

package/bin/pty-manager.cjs

@@ -4,6 +4,7 @@
 const { existsSync, realpathSync } = require("fs");
 const { WebSocketServer } = require("ws");
 const { resolveShell } = require("./pty-shell.cjs");
+const { killPtyProcess, disposeWorkerChild } = require("./pty-process.cjs");
 const ptyWss = new WebSocketServer({ noServer: true });
 
 function sanitizeEnv(env) {
@@ -68,17 +69,57 @@ function startPtySession(options) {
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      killPtyProcess(proc);
+    },
+  };
+}
+
+const PTY_HEARTBEAT_MS = 30_000;
+const PTY_HEARTBEAT_MAX_MISSED = 2;
+// 取舍：看的是 WebSocket 协议级 ping/pong（浏览器自动回 pong），**不是**终端有没有输出，
+// 所以前台跑 `sleep 600` 之类不会因为「没输出」被判死。代价是：手机锁屏后网络栈不再回 pong，
+// 连续 3 拍（约 90 秒）没有任何 pong 就会 terminate → 面板重连时是**新** shell。
+// 要更宽松就调大这两个常量；不要改成按终端输出判活（那会杀掉长任务）。
+
+/**
+ * 判断这条连接是真死还是只是安静：手机掉网、进程被冻住时 TCP 不会发 FIN，
+ * 服务端会一直攥着 ws 和它背后的 shell（孤儿进程，还占着端口/内存）。
+ * 按 ping/pong 收尾，连续几轮没有 pong 就 terminate（触发 close → dispose）。
+ * 计时器与 readyState 判定可注入，单测用假计时器驱动。
+ */
+function startPtyHeartbeat(ws, options = {}) {
+  const intervalMs = options.intervalMs ?? PTY_HEARTBEAT_MS;
+  const maxMissed = options.maxMissed ?? PTY_HEARTBEAT_MAX_MISSED;
+  const setIntervalFn = options.setIntervalFn ?? setInterval;
+  const clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+  const isOpen = options.isOpen ?? (() => ws.readyState === 1);
+  let missedPongs = 0;
+  const onPong = () => {
+    missedPongs = 0;
+  };
+  ws.on("pong", onPong);
+  const timer = setIntervalFn(() => {
+    if (!isOpen()) return;
+    if (missedPongs >= maxMissed) {
       try {
-        if (proc.pid > 0) process.kill(-proc.pid, "SIGTERM");
-      } catch {
-        /* 进程组可能已不在 */
-      }
-      try {
-        proc.kill("SIGTERM");
+        ws.terminate();
       } catch {
-        /* 已退出 */
+        /* 已断开 */
       }
-    },
+      return;
+    }
+    missedPongs += 1;
+    try {
+      ws.ping();
+    } catch {
+      /* 已断开 */
+    }
+  }, intervalMs);
+  // unref：别让心跳计时器把进程吊在退出前。
+  if (timer && typeof timer.unref === "function") timer.unref();
+  return () => {
+    clearIntervalFn(timer);
+    if (typeof ws.off === "function") ws.off("pong", onPong);
   };
 }
 
@@ -86,10 +127,13 @@ function attachPtyToWebSocket(ws, cwd) {
   const { spawn } = require("child_process");
   const path = require("path");
   const workerPath = path.join(__dirname, "pty-worker.js");
+  let disposed = false;
   const child = spawn(process.execPath, [workerPath, cwd, "80", "24"], {
     stdio: ["pipe", "pipe", "pipe"],
     env: process.env,
   });
+  // stdin 在子进程已退出后写入会异步抛 EPIPE：这里吞掉，避免拆连接时崩服务端。
+  child.stdin.on("error", () => {});
   child.stderr.setEncoding("utf8");
   child.stderr.on("data", (data) => console.warn("[pidance] pty-worker stderr", data));
   child.on("error", (error) => console.warn("[pidance] pty-worker spawn", error.message));
@@ -98,7 +142,10 @@ function attachPtyToWebSocket(ws, cwd) {
     write: (data) => child.stdin.write(`${JSON.stringify({ type: "in", d: data })}\n`),
     resize: (cols, rows) => child.stdin.write(`${JSON.stringify({ type: "rs", cols, rows })}\n`),
     dispose: () => {
-      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      if (disposed) return;
+      disposed = true;
+      // 先请 worker 自己收尾，再按平台决定强杀时机（Windows 上不能同拍强杀，见 disposeWorkerChild）。
+      disposeWorkerChild(child);
     },
   };
   child.stdout.setEncoding("utf8");
@@ -135,8 +182,14 @@ function attachPtyToWebSocket(ws, cwd) {
     if (parsed && parsed.type === "in" && typeof parsed.d === "string") session.write(parsed.d);
     if (parsed && parsed.type === "rs" && parsed.cols > 0 && parsed.rows > 0) session.resize(parsed.cols, parsed.rows);
   });
-  ws.on("close", () => session.dispose());
-  ws.on("error", () => session.dispose());
+  // 心跳与 dispose 一起收：连接没了就别再 ping（也避免计时器残留）。
+  const stopHeartbeat = startPtyHeartbeat(ws);
+  const disposeSession = () => {
+    stopHeartbeat();
+    session.dispose();
+  };
+  ws.on("close", disposeSession);
+  ws.on("error", disposeSession);
   try { ws.send(JSON.stringify({ type: "out", d: "\r\n[pidance] terminal ready\r\n" })); } catch { /* ignore */ }
   return session;
 }
@@ -148,4 +201,4 @@ function completePtyUpgrade(req, socket, head, cwd) {
   });
 }
 
-module.exports = { startPtySession, tryLoadNodePty, resolvePtyCwd, attachPtyToWebSocket, completePtyUpgrade };
+module.exports = { startPtySession, tryLoadNodePty, resolvePtyCwd, attachPtyToWebSocket, completePtyUpgrade, startPtyHeartbeat };

package/bin/pty-process.cjs

@@ -0,0 +1,135 @@
+"use strict";
+
+/**
+ * PTY 子进程的收尾规则（bin/pty-manager.cjs 与 bin/pty-worker.js 共用一份）。
+ *
+ * 为什么不能只 `proc.kill(signal)`：node-pty 的 Unix 实现就是只杀那一个 pid
+ * （`node_modules/node-pty/lib/unixTerminal.js` 的 `kill` 里是 `process.kill(this.pid, signal)`），
+ * 而 shell 在**同一进程组**里起的后代（例如 `sh -c "sleep 600 & wait"` 那种同组后台作业）会被留下。
+ *
+ * forkpty 会让 shell 成为会话/进程组组长，所以先补一刀 `-pid` 打整组，再按 pid 收尾
+ * （组长可能已不在，两步都要容错）。
+ *
+ * 边界（别把组杀想得比它更大）：交互式 bash 里直接敲的 `sleep 600 &` 会被 job control 放进
+ * **另一个**进程组，`kill(-shellPid)` **打不中**它 —— 逃出会话组的后代本来就要按 SID 遍历进程树才收得掉，
+ * 那是平台相关的产品取舍，这里不做。
+ *
+ * Windows 上 `process.kill(-pid)` 会抛错（不支持杀进程组），而 node-pty 的
+ * `WindowsTerminal.kill(signal)` 在真正清理（`_close()` / `_agent.kill()`）**之前**就
+ * `throw new Error("Signals not supported on windows.")`（`node_modules/node-pty/lib/windowsTerminal.js`）——
+ * 所以 win32 必须**不传 signal** 地调用 `kill()`，否则那条真正的 ConPTY 清理会被空 catch 当成「已经退出」吞掉。
+ */
+function killPtyProcess(proc, signal = "SIGTERM", platform = process.platform) {
+  if (!proc || !(proc.pid > 0)) return;
+  // 进程组那一刀只在支持它的平台做（Windows 传负 pid 会抛）。
+  if (platform !== "win32") {
+    try {
+      process.kill(-proc.pid, signal);
+    } catch {
+      /* 进程组可能已不在 */
+    }
+  }
+  if (typeof proc.kill === "function") {
+    try {
+      // Windows：不能传 signal，否则 node-pty 在真正清理前就抛错（见文件头）。
+      if (platform === "win32") proc.kill();
+      else proc.kill(signal);
+    } catch {
+      /* 已退出 */
+    }
+  }
+}
+
+/**
+ * 请 pty-worker 自己收尾（发一条 {type:"bye"} 帧）。
+ * 为什么不能只靠 child.kill：Windows 上 Node 会忽略信号种类直接强杀 worker，
+ * worker 里的信号处理跑不到 → node-pty 的真实清理也跑不到。帧发不出去就返回 false，
+ * 由调用方继续走强杀兜底。
+ */
+function requestWorkerShutdown(child) {
+  try {
+    if (!child || !child.stdin || child.stdin.writable === false) return false;
+    child.stdin.write(`${JSON.stringify({ type: "bye" })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 请 worker 自己收尾之后等它退出的上限（Windows 上必须等：见 disposeWorkerChild）。 */
+const WORKER_SHUTDOWN_GRACE_MS = 2000;
+
+/**
+ * 关掉一条终端时收尾 pty-worker。
+ *
+ * Linux：worker 收到 SIGTERM 会跑自己的 shutdown（killPtyProcess + exit），所以直接发信号。
+ * Windows：`child.kill` 会**忽略信号种类、强制结束**（Node 文档：similar to SIGKILL），
+ * 同一次同步调用里就把 worker 结束了 —— 它下一次事件循环才会读到 stdin，所以先写 bye 帧再立刻
+ * 强杀等于 bye 从来没送到，worker 里的 node-pty 真实清理也跑不到。因此 win32 上先发 bye，
+ * 让它自己退出；只有超时未退才强杀。
+ */
+function disposeWorkerChild(child, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const graceMs = options.graceMs ?? WORKER_SHUTDOWN_GRACE_MS;
+  const setTimer = options.setTimer ?? setTimeout;
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  const kill = () => {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      /* 已退出 */
+    }
+  };
+  // 只在真的要等它的平台上发 bye 帧：非 win32 的路径与改动前逐字一致（就一次 SIGTERM）。
+  if (platform === "win32" && requestWorkerShutdown(child)) {
+    const timer = setTimer(kill, graceMs);
+    if (timer && typeof timer.unref === "function") timer.unref();
+    if (typeof child.once === "function") child.once("exit", () => clearTimer(timer));
+    return;
+  }
+  kill();
+}
+
+const PARENT_WATCH_MS = 5000;
+/** 连续探不到父进程几次才收尾（见 startParentWatchdog）。 */
+const PARENT_WATCH_MISSES = 2;
+
+/**
+ * 父进程被硬杀（SIGKILL / 崩溃 / 被强制结束）时不会发 SIGTERM，PTY worker 会连同
+ * 它下面的 shell 一起变成孤儿 —— 实测：改前（没有看护）worker 在父进程被 SIGKILL
+ * 之后一直活着，改后退出。定期确认父进程还在，不在了就收尾。
+ * 依赖与计时器可注入，单测用假计时器驱动。
+ */
+function startParentWatchdog(options = {}) {
+  const parentPid = options.parentPid ?? process.ppid;
+  const intervalMs = options.intervalMs ?? PARENT_WATCH_MS;
+  const missThreshold = options.missThreshold ?? PARENT_WATCH_MISSES;
+  const setIntervalFn = options.setIntervalFn ?? setInterval;
+  const clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+  // 只看「进程不存在」（ESRCH）：EPERM 是「存在但不是我们能碰的」，绝不能当死亡，
+  // 否则一次权限异常就会在 5 秒后拆掉用户的终端。
+  const isAlive = options.isAlive ?? ((pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error && error.code === "EPERM";
+    }
+  });
+  const onGone = options.onGone ?? (() => {});
+  // 连续两次探不到才收尾：杀错（拆掉用户正在用的终端）比晚 5 秒收尾严重得多。
+  let missed = 0;
+  const timer = setIntervalFn(() => {
+    if (isAlive(parentPid)) {
+      missed = 0;
+      return;
+    }
+    missed += 1;
+    if (missed >= missThreshold) onGone();
+  }, intervalMs);
+  // unref：看护计时器不该把进程吊住，worker 是靠 pty 活着的。
+  if (timer && typeof timer.unref === "function") timer.unref();
+  return () => clearIntervalFn(timer);
+}
+
+module.exports = { killPtyProcess, startParentWatchdog, requestWorkerShutdown, disposeWorkerChild };

package/bin/pty-worker.js

@@ -3,6 +3,7 @@
 
 const pty = require("node-pty");
 const { resolveShell } = require("./pty-shell.cjs");
+const { killPtyProcess, startParentWatchdog } = require("./pty-process.cjs");
 
 const cwd = process.argv[2] || process.cwd();
 const cols = Number(process.argv[3]) || 80;
@@ -48,10 +49,23 @@ process.stdin.on("data", (chunk) => {
     try { msg = JSON.parse(line); } catch { continue; }
     if (msg.type === "in" && typeof msg.d === "string") proc.write(msg.d);
     if (msg.type === "rs" && msg.cols > 0 && msg.rows > 0) proc.resize(msg.cols, msg.rows);
+    // 父进程请求收尾：Windows 上 child.kill 会忽略信号种类直接强杀 worker，
+    // worker 侧的信号处理跑不到，所以正常关闭走这条显式请求。
+    if (msg.type === "bye") shutdown();
   }
 });
 
-process.on("SIGTERM", () => {
-  try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+// 收尾：Linux 走父进程的 SIGTERM / SIGINT，Windows 走父进程发来的 bye 帧
+// （那边 child.kill 会忽略信号种类直接强杀，信号处理跑不到）；异常路径由下面的父进程看护兜底。
+let exiting = false;
+const shutdown = () => {
+  if (exiting) return;
+  exiting = true;
+  killPtyProcess(proc);
   process.exit(0);
-});
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+// 父进程真的没了才收尾：stdin EOF 不等于父进程退出（写端关闭就会 EOF，
+// 而父进程可能还在），所以这里看的是父进程本身还在不在。
+startParentWatchdog({ onGone: shutdown });

package/bin/pty-ws.js

@@ -69,6 +69,10 @@ function isLoopbackHost(hostHeader) {
 const UI_SESSION_COOKIE_NAME = "pidance_ui_session";
 
 function resolvePassword(env) {
+  // 启动时密码已搬进同进程 globalThis 缓存（bin/pidance-auth-gate.js 的
+  // primeAndScrubPassword），env 里不再有明文；两条来源同形，缺一不可。
+  const cached = globalThis.__piAuthPassword;
+  if (cached) return cached.value;
   const p =
     env && env.PIDANCE_PASSWORD && env.PIDANCE_PASSWORD.length > 0
       ? env.PIDANCE_PASSWORD
@@ -215,15 +219,22 @@ function ptyGuardHeaders(req) {
     secFetchUser: header(req, "sec-fetch-user"),
     authorization: header(req, "authorization"),
     cookie: header(req, "cookie"),
+    xForwardedFor: header(req, "x-forwarded-for"),
     method: "GET",
     url,
     pathname,
   };
 }
 
-function reject(socket, status, message) {
+function reject(socket, status, message, extraHeaders) {
+  const headers = {
+    Connection: "close",
+    "Content-Length": 0,
+    ...(extraHeaders || {}),
+  };
+  const lines = Object.keys(headers).map((name) => `${name}: ${headers[name]}\r\n`).join("");
   try {
-    socket.write(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+    socket.write(`HTTP/1.1 ${status} ${message}\r\n${lines}\r\n`);
   } catch {
     // ignore
   }
@@ -234,6 +245,99 @@ function reject(socket, status, message) {
   }
 }
 
+// ── 密码尝试限流（与 lib/auth-throttle.ts 同桶）──────────────────────────
+//
+// WebSocket 升级不经过 Next middleware，所以这里必须自己挡一次：否则 /api/pty
+// 就是一条不限速的密码预言机（Basic 可全速猜）。状态放在与 lib/auth-throttle.ts
+// 相同的 globalThis 键、相同结构上，两条入口在同进程里共用同一个桶。
+//
+// bin/ 是自包含发布物（见文件头注释，不依赖 lib/ 源码树），所以退避公式与常量
+// 在内联实现里保持语义一致；bin/pty-ws.test.mjs 有一条与 lib/auth-throttle.ts
+// 的 parity 断言，改一边不改另一边会红。
+
+const AUTH_THROTTLE_GLOBAL_KEY = "__piAuthThrottle";
+const AUTH_THROTTLE_BASE_DELAY_MS = 1000;
+const AUTH_THROTTLE_MAX_DELAY_MS = 60000;
+const AUTH_THROTTLE_RESET_AFTER_MS = 5 * 60 * 1000;
+const AUTH_THROTTLE_MAX_BUCKETS = 256;
+
+function authThrottleStore() {
+  if (!globalThis[AUTH_THROTTLE_GLOBAL_KEY]) globalThis[AUTH_THROTTLE_GLOBAL_KEY] = new Map();
+  return globalThis[AUTH_THROTTLE_GLOBAL_KEY];
+}
+
+function backoffDelayMs(failures) {
+  if (failures <= 0) return 0;
+  const exponent = Math.min(failures - 1, 31);
+  return Math.min(AUTH_THROTTLE_BASE_DELAY_MS * 2 ** exponent, AUTH_THROTTLE_MAX_DELAY_MS);
+}
+
+function expireIfStale(state, now) {
+  if (state.failures > 0 && now - state.lastFailureAt >= AUTH_THROTTLE_RESET_AFTER_MS) {
+    state.failures = 0;
+    state.lastFailureAt = 0;
+    state.blockedUntil = 0;
+  }
+}
+
+/** 该桶还需等多久（毫秒）；0 表示可以尝试。 */
+function getAuthRetryAfterMs(key, now = Date.now()) {
+  const state = authThrottleStore().get(key);
+  if (!state) return 0;
+  expireIfStale(state, now);
+  return Math.max(0, state.blockedUntil - now);
+}
+
+function pruneAuthThrottle(now) {
+  const map = authThrottleStore();
+  if (map.size <= AUTH_THROTTLE_MAX_BUCKETS) return;
+  for (const [key, state] of map) {
+    if (state.failures === 0 || now - state.lastFailureAt >= AUTH_THROTTLE_RESET_AFTER_MS) map.delete(key);
+  }
+  while (map.size > AUTH_THROTTLE_MAX_BUCKETS) {
+    const oldest = [...map.entries()].sort((a, b) => a[1].lastFailureAt - b[1].lastFailureAt)[0];
+    if (!oldest) break;
+    map.delete(oldest[0]);
+  }
+}
+
+/** 记一次失败并返回施加的退避（毫秒）。 */
+function recordAuthFailure(key, now = Date.now()) {
+  const map = authThrottleStore();
+  let state = map.get(key);
+  if (!state) {
+    state = { failures: 0, lastFailureAt: 0, blockedUntil: 0 };
+    map.set(key, state);
+  }
+  expireIfStale(state, now);
+  state.failures += 1;
+  state.lastFailureAt = now;
+  state.blockedUntil = now + backoffDelayMs(state.failures);
+  pruneAuthThrottle(now);
+  return backoffDelayMs(state.failures);
+}
+
+/**
+ * 限流分桶的身份，与 lib/request-guard.ts 的 `authIdentity` 同规则：
+ * 只在显式 `PIDANCE_TRUST_PROXY` 时信 `x-forwarded-for`，否则用对端地址；
+ * 都拿不到时退回固定全局桶（宁可误伤也不放行）。
+ */
+function authThrottleKey(socket, headers, env) {
+  const trustProxy = env.PIDANCE_TRUST_PROXY === "1" || env.PIDANCE_TRUST_PROXY === "true";
+  if (trustProxy) {
+    const first = (headers.xForwardedFor || "").split(",")[0];
+    const trimmed = first ? first.trim() : "";
+    if (trimmed) return trimmed.replace(/^::ffff:/, "");
+  }
+  const peer = typeof socket?.remoteAddress === "string" ? socket.remoteAddress.trim() : "";
+  if (peer) return peer.replace(/^::ffff:/, "");
+  return "unknown";
+}
+
+function retryAfterSeconds(retryAfterMs) {
+  return Math.max(1, Math.ceil(retryAfterMs / 1000));
+}
+
 async function handlePtyUpgrade(req, socket, head) {
   if (!tryLoadNodePty()) {
     reject(socket, 503, "PTY Unavailable");
@@ -251,10 +355,20 @@ async function handlePtyUpgrade(req, socket, head) {
     return;
   }
   if (passwordEnabled(process.env)) {
+    // 与 middleware / 登录表单共用同一个桶：封锁期内密码正确也不放行，
+    // 否则升级路径就是一条不限速的密码预言机。
+    const throttleKey = authThrottleKey(socket, guardHeaders, process.env);
+    const retryAfterMs = getAuthRetryAfterMs(throttleKey);
+    if (retryAfterMs > 0) {
+      reject(socket, 429, "Too Many Requests", { "Retry-After": retryAfterSeconds(retryAfterMs) });
+      return;
+    }
     if (!checkAuthenticated(guardHeaders, process.env)) {
+      recordAuthFailure(throttleKey);
       reject(socket, 401, "auth-required");
       return;
     }
+    // 成功不回退计数：Basic 每个请求都带，复位会让穿插猜测回到基准延迟。
   } else if (!isLoopbackHost(guardHeaders.host)) {
     // fail-closed 兜底：未设密码时仅放行回环请求（与 middleware 一致）。
     reject(socket, 401, "auth-required");
@@ -268,4 +382,13 @@ async function handlePtyUpgrade(req, socket, head) {
   completePtyUpgrade(req, socket, head, cwd);
 }
 
-module.exports = { handlePtyUpgrade, ptyGuardHeaders };
+module.exports = {
+  handlePtyUpgrade,
+  ptyGuardHeaders,
+  // 导出限流内联实现：bin/pty-ws.test.mjs 用它断言与 lib/auth-throttle.ts 的
+  // 退避公式一致、且两条入口共用同一个桶。
+  authThrottleKey,
+  backoffDelayMs,
+  getAuthRetryAfterMs,
+  recordAuthFailure,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henlii/pidance",
-  "version": "0.2.37",
+  "version": "0.2.40",
   "description": "Pidance：面向 Pi coding agent 的开源 Web 客户端",
   "homepage": "https://github.com/henlii/pidance#readme",
   "repository": {
@@ -55,20 +55,22 @@
     "check": "npm run typecheck && npm run lint && npm run test",
     "release:audit": "node scripts/audit-release-package.mjs --pre",
     "release:audit:tgz": "node scripts/audit-release-package.mjs --tgz",
+    "release:desktop-check": "node scripts/check-desktop-lockfile.mjs",
     "package:candidate": "node scripts/make-candidate-package.mjs",
     "release:check": "npm run check && npm run build && npm run release:audit",
     "test:browser:sse": "node --test scripts/sse-recording-replay.test.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.87.0",
+    "@earendil-works/pi-tui": "0.87.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "jiti": "^2.7.0",
     "lucide-react": "^0.562.0",
-    "next": "16.2.11",
+    "next": "16.3.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "undici": "8.5.0",
+    "undici": "8.11.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {

package/.next/server/app/_global-error.segments/_global-error.segment.rsc

@@ -1,5 +0,0 @@
-1:"$Sreact.fragment"
-2:I[57121,[],""]
-3:I[74581,[],""]
-4:[]
-0:{"rsc":["$","$1","c",{"children":[null,["$","$L2",null,{"parallelRouterKey":"children","template":["$","$L3",null,{}]}]]}],"isPartial":false,"staleTime":300,"varyParams":"$W4","buildId":"WyhxhOSSU4IaU7cnCvJTt"}