@epoch-agent/plugin-terminal 0.1.0

package/LICENSE

@@ -0,0 +1,219 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+--------------------------------------------------------------------------------
+
+epoch-agent
+Copyright 2024-2026 bowen
+
+Portions of this software are derived from the Gemini CLI
+(https://github.com/google-gemini/gemini-cli), Copyright 2025 Google LLC,
+licensed under the Apache License, Version 2.0. Those files have been modified;
+each one retains its original copyright notice and SPDX-License-Identifier
+header. See the NOTICE file in the project source repository for the complete
+list of derived files.
+
+This software also quotes, with attribution, two lines of prose from OpenAI
+Codex (https://github.com/openai/codex), Copyright 2025 OpenAI, licensed under
+the Apache License, Version 2.0. No source file is a derived work of Codex.
+See the NOTICE file for details.

package/README.md

@@ -0,0 +1,291 @@
+# @epoch-agent/plugin-terminal
+
+终端插件。**五个工具**：`terminal` + 后台任务的 `task_list` / `task_output` /
+`task_wait` / `task_stop`。
+
+- ✅ **做**：起进程、收输出（执行期间同时喂给 `ctx.onOutput`）、到点杀干净（含孙进程）、
+  危险命令拦截、workdir 边界校验、**三条执行路径各过一道进程沙箱**（2026-08-17，见下）；
+  **后台长任务**（不等它跑完就返回）
+- ❌ **不做**：不自己实现沙箱（调 [infra](../../infra) 的 `confine()`）。危险命令表是
+  **护栏**——它拦的是手滑，不是对抗，**上了沙箱之后这条一个字没松**。
+  后台任务**不能活过 epoch 进程**（刻意的，见下）
+- **依赖**：`node-pty`。[protocol](../../protocol) 和 [infra](../../infra) 是 peer
+
+## 沙箱：三条路径都包上了，但**只管写入**
+
+2026-08-16（方案 46 PR-1）之前，`code_exec` 有 OS 强制的隔离而 `terminal` **什么都没有** ——
+后者的调用频率高一个量级。现在三条执行路径在起进程之前各过一道 `confine()`：
+
+| 路径                 | 插入点                               | 落地               |
+| -------------------- | ------------------------------------ | ------------------ |
+| 管道（默认）         | `exec.ts` 的 `runCommand()`          | PR-1（2026-08-16） |
+| 后台（`background`） | **`background.ts` 的 `startTask()`** | PR-4（2026-08-17） |
+| PTY（`pty`）         | `pty.ts` 的 `runCommandPty()`        | PR-5（2026-08-17） |
+
+⚠️ 后台那一行的插入点是 `startTask()`，**不是** `exec.ts` 里那个 `runBackground()` ——
+后者从方案 36 起就没有任何调用方，2026-08-17 一并删了。
+
+边界按**权限档位**推导，用户不多学一个概念：
+
+| 权限档位                           | 沙箱模式             | 能写到哪                                |
+| ---------------------------------- | -------------------- | --------------------------------------- |
+| `plan`                             | `read-only`          | 哪都不行（`/dev/null` 除外）            |
+| `auto` / `default` / `acceptEdits` | `workspace-write`    | 工作区 + 额外根 + 临时目录 + 工具链缓存 |
+| `bypass`                           | `danger-full-access` | 不设限 —— **但危险命令表照旧拦**        |
+
+⚠️ **三件必须说清楚的事**，不然「terminal 有沙箱了」会被读成「terminal 安全了」：
+
+1. **只管写入。** 读取和网络都**不设限** —— 给终端上读白名单会让 `git push`
+   （要读 `~/.ssh`）和 `pnpm install`（要读 `~/.npmrc`）当场废掉。
+   沙箱里的命令还能 `ps` 看见主机上别的进程。
+2. **「三条路径都包上了」不等于「terminal 安全了」。** 安全中心那份「不在沙箱里」的
+   点名清单现在是空的，它只说**没有哪条路径看起来在沙箱里而实际不在** ——
+   第 1 条和第 3 条一个字都没变。
+3. **Windows 上没有后端**，所以那儿一次都没包上 —— 工具输出里会逐字说
+   「本次没有 OS 级隔离」。`epoch doctor` 的沙箱一节印的是实测值。
+
+PTY 那条是最后接的，而且方案里**允许的结论是「不上沙箱，如实说明」**：
+`sandbox-exec` 包一层之后 tty 分配 / 窗口尺寸 / 信号转发都可能坏，坏法还很阴
+（「交互式命令看起来跑起来了，但 Ctrl+C 不响应」）。三样在 macOS + 真 Seatbelt 上
+拿裸 PTY 做对照逐条实测过，结果完全一致才接的，用例在
+[`__tests__/sandbox-pty.test.ts`](__tests__/sandbox-pty.test.ts)。
+
+后台那条同理有一条要验的：`sandbox-exec` 会不会破坏
+[infra](../../infra) 那条 `detached: false` 的决定（Ctrl+C 靠内核发给整个前台进程组）。
+实测**没有** —— 包与不包，整棵树的 pgid 都等于我们自己，而且 `sandbox-exec`
+**不 fork 一层**（套上 profile 之后直接 `exec`，同一个 pid）。真发一次 SIGINT
+查残留的用例在 [`__tests__/sandbox-process-tree-e2e.test.ts`](__tests__/sandbox-process-tree-e2e.test.ts)。
+
+失败分两种说，对应两个错误码：**2008** = 被沙箱挡下（命令跑了、动作被拒），
+**2009** = 沙箱自己没起来（**命令根本没跑，别去改命令**）。
+
+## 后台任务：`pnpm build` 三分钟不用干等
+
+```
+terminal({ command: 'pnpm dev', background: true })   → 立即返回 t1
+task_output({ id: 't1', since })                      → 增量取输出
+task_wait({ id: 't1', timeoutMs })                    → 等它结束（**超时不杀它**）
+task_stop({ id: 't1' })                               → 停掉（杀整棵树）
+task_list()                                           → 看全部
+```
+
+这条路真正解锁的是「**起服务 → 连上去验证 → 停掉**」：在这之前起服务那条命令
+永远不返回，而且老的后台分支是 `stdio: 'ignore'`，`listening on :3000` 那一行
+根本不存在。
+
+六条边界（「谁看得见」那一条是 2026-08-15 新加的，它以前的答案是「所有人」）：
+
+| 事情            | 取舍                                                                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| 活过一轮对话    | **会**（任务表挂在会话上，不是一次工具调用）                                                                           |
+| 谁看得见        | **只有起它的那个会话**（2026-08-15 收窄，见下）                                                                        |
+| 活过 epoch 进程 | **不会**，且这是刻意的 —— 见下                                                                                         |
+| 同时几个        | **每个会话** 8 个，超了拒绝并列出**这个会话**在跑的                                                                    |
+| `epoch -p` 里   | 跑完给一段摘要（`--json` 里是 `backgroundTasks` 字段），随后一并终止。见 [docs/HEADLESS.md](../../../docs/HEADLESS.md) |
+| 输出            | 单任务 256KB **环形**缓冲（丢头保尾）+ 溢出时全文落 artifact，`task_output` 单次 8KB                                   |
+
+环形缓冲丢头保尾，和前台命令的「**头尾都留**」正好相反：后台任务里最有价值的
+永远是最后几行（构建结果、报错栈），而一次性命令的头部是「跑的是什么命令、
+什么配置」、尾部是结论，两头都要。滚出去多少会在 `task_output` 里明说，不静默。
+
+一溢出，全文就同时写进 `~/.epoch/artifacts/<会话 id>/`（方案 47），
+于是滚出缓冲的开头不再是真的没了 —— 但**预览仍然取尾部**，
+落盘只是让被丢的头留下来，不是反转上面那个决定。落盘是懒的：
+没溢出过的任务一个文件都不产生。
+
+### 任务表按会话分（2026-08-15）
+
+一条后台任务归**起它的那个会话**（`ToolContext.sessionId`）。别的会话
+`task_list` 里看不到它，拿它的 id 也取不到输出、停不掉 —— 和「没有这个任务」
+同一句话。
+
+在这之前那张表是**进程级**的：一个进程里两个会话看到的是同一批任务，于是
+A 会话每轮被告知一批它没起过的命令在跑，而一句 `task_stop t1` 能停掉 B 会话
+的构建。当时那么写的理由是「plugin 拿不到会话对象」—— 拿不到*对象*是真的，
+但会话 _id_ 一直在工具契约上。
+
+两条跟着变的：
+
+- **8 个的名额按会话算**（原来是进程级）。判据是那句话本身：满了时给的建议是
+  「先用 `task_stop` 停掉一个」，而别的会话的任务这个会话够不着 ——
+  一条做不到的建议比没有建议更坏。代价是进程里的总数变成 `8 × 活跃会话数`
+- **`/resume` 换会话 id 时那一格跟着搬**，`delegate_task` 的子任务跑完之后把它
+  起的后台任务**归还给派活的会话** —— 否则它会变成谁都看不见、谁也停不掉的孤儿
+
+会话被**冷却**（web 的 LRU，`live: false`）时这批任务**一个字都不动**：会话可以
+被释放，而进程还在跑是一个仍然成立的事实，且这张表是唯一还能停掉它的把手。
+完整判据（含进程退出时的清理为什么不受影响）在
+[src/background.ts](src/background.ts) 的文件头。
+
+### 为什么后台任务不能活过 epoch
+
+因为它们和前台命令一样 **`detached: false`**。理由在
+[infra/child-process.ts](../../infra/src/child-process.ts) 的文件头：epoch 装了
+`installSignalHandlers`，Ctrl+C 时那个监听器直接 `dispose(); process.exit(0)`，
+**没有任何一行我们的清理代码有机会跑完**。不残留靠的是内核 —— 子进程和我们在
+同一个前台进程组，终端把 SIGINT 发给整组。
+
+这条对长期任务**更重要**：它们活得久，撞上 Ctrl+C 的概率高得多。代价就是
+「起个服务然后退出 epoch，服务还在」做不到 —— 写进了工具描述。
+
+> ⚠️ **后台不是权限旁路。** `background: true` 走的是**同一条**危险命令表和
+> 权限判定 —— 同一条命令前台要确认，后台也要。四个 task 工具本身不执行命令
+> （`operation: 'file_read'`），所以取一次输出不会弹确认框。用例守着这两条。
+
+## 参数
+
+`command` / `background` / `pty` / `stdin` / `workdir`，**逐个说明和默认值在
+[docs/TOOLS.md](../../../docs/TOOLS.md#终端与后台任务)** —— 那份是工具清单的唯一真源。
+
+「在工作区内」（`workdir` 的判定）用的是 infra 的
+[`isInWorkspace()`](../../infra/src/workspace.ts) —— 全仓唯一一份，权限层和 plugin-file
+共用（本插件里原来有一份逐字相同的私有实现）。`ctx.extraRoots`（`epoch --add-dir`）
+里的目录同样算工作区内。
+
+## 三条执行路径
+
+管道（默认）走 `child_process.spawn`，PTY（`pty: true`）走 `node-pty`，
+后台（`background: true`）走 infra 的 `startLongLivedProcess()` 并登记进任务表，
+只回一个任务 id。三条各自的超时和输出上限见
+[docs/TOOLS.md](../../../docs/TOOLS.md#终端与后台任务)。
+
+源码按**关注点**分（2026-08-17 从一个 649 行的 `exec.ts` 拆开，判据在各自的文件头）：
+
+| 文件                                         | 管什么                                             |
+| -------------------------------------------- | -------------------------------------------------- |
+| [`exec.ts`](src/exec.ts)                     | 管道那条路 + 退出清理。主题是**别留下孤儿进程**    |
+| [`pty.ts`](src/pty.ts)                       | PTY 那条路。它的进程组语义和另外两条**相反**       |
+| [`background.ts`](src/background.ts)         | 后台任务表（状态 / 环形缓冲 / 落盘 / 停等）        |
+| [`sandbox.ts`](src/sandbox.ts)               | 把 argv 包进沙箱 + 算出要上报的东西。三条路共用    |
+| [`sandbox-notice.ts`](src/sandbox-notice.ts) | 把上面那份**说成给模型读的一行话**                 |
+| [`limits.ts`](src/limits.ts)                 | 输出上限和两句共用措辞。下沉成叶子，避开 import 环 |
+
+前两条路径在执行**期间**把每一块 stdout / stderr 交给 `ctx.onOutput`（宿主那边最终
+表现为 `tool-output-delta`）。后台路径没有「执行期间」可言——起完就返回 PID，一个字
+都不发。交出去的是**原始字节解码后的文本**，不做任何加工：合并窗口、剥 ANSI、
+`\r` 折叠、总量封顶都在 [core](../../core) 的 `tool-output-pump.ts` 里，这样三个宿主
+看到的是同一种节奏。宿主不接这条通道时行为与改动前完全一致。
+
+上表的 50 KB 上限管的是**返回给模型的** `output`，和实时通道的封顶是两回事——
+实时那条是纯展示，跑满了就闭嘴，不影响最终结果。
+
+### 超过 50 KB：落盘，不再杀进程（方案 47）
+
+改造前超 50 KB 是**截断 + 把进程杀掉**，理由是「反正也留不住」。落盘之后这个理由
+不成立了：命令跑完，全文进 `~/.epoch/artifacts/<会话 id>/`，回给模型的是头 2000 +
+尾 2000 字符加一句取回提示（措辞和阈值都在 [spill.ts](./src/spill.ts)）。
+这修的是一个很具体的坏结果：`pnpm test` 输出 300 KB 时**测试跑到一半被杀**，
+而那恰好是最需要看最后几行的场景。
+
+还剩一条 **10 MB** 的硬上限，超了才恢复截断 + 杀进程 —— 一条命令吐 10 MB 到 stdout
+不是一次正常的命令输出。三条路径共用同一句措辞（`OVER_CAPTURE_NOTICE`）。
+
+落盘一律 **best-effort**：写不进去就退回纯截断、如实说明，**不把一次成功的调用变成
+失败**。真正写盘的那几行在 [infra 的 artifact-store](../../infra/src/artifact-store.ts)
+（`0700` 目录、`0600` 文件、`open(path,'wx')` 独占写，所以预埋 symlink
+劫持不了写入）—— 多模态那条落盘路径走的是同一份实现。
+
+三条路径的进程组语义各不相同，逐条写在 `exec.ts` / `pty.ts` 的函数注释里。
+`exec.ts` 的主题只有一个：**别留下孤儿进程**。`killProcessTree` 走
+SIGTERM → SIGKILL，但另外还有一个「发完 kill 最多再等多久就带着已有输出返回」的
+上限——处在不可中断睡眠的进程连 SIGKILL 都不理，不设上限的话用户按了 Esc 之后
+这次调用会永远挂着。
+
+## 后台进程谁来收
+
+`background: true` 起的进程登记在 [infra](../../infra) 的 pid 表里（那是所有长期子进程的
+唯一真源），PTY 会话记在 `pty.ts` 的模块级表里，两边由 [runtime](../../runtime) 的
+`dispose()` 调 `cleanupBackgroundProcesses()` 统一收掉 —— 所以宿主退出时它们不会留在
+机器上，前提是宿主**调了** `dispose()`（能 `await` 就 `await`，收进程树是异步的）。
+
+> 2026-08-17 之前这里收的是**三**张表：多出来的那张属于 `runBackground()`，
+> 一个从方案 36 起就零调用方的函数。它连着那张表一起删了。
+
+这些表是**模块级**的（和 `applyShell` 一样，跟着进程走而不是跟着 runtime 走）。
+同一个 Node 进程里建多个 runtime 时，先 dispose 的那个会把别人的后台进程一起收掉。
+CLI / TUI / server 都是一进程一 runtime，碰不到；嵌入宿主要开多 runtime 就得知道这件事。
+
+## `cd` 不会留存，而且工具会明说
+
+命令是在一次性子 shell 里跑的，退出后 cwd 根本没变。所以检测到裸 `cd` 时，工具返回
+一条**准确**的提示：
+
+> `[提示] cd 只在本次子 shell 内生效，下次调用仍在原工作目录。若后续命令需要在 X 下执行，请传 workdir 参数，或写成 "cd X && <命令>"。`
+
+之前这里返回的是「[工作目录已切换: X]」——谎报会让模型基于错误的 cwd 假设继续拼
+相对路径。**这个插件不维护会话级工作目录。**
+
+## annotations 四个都到顶
+
+```ts
+{ readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
+```
+
+任意 shell 命令能删数据、能联网，两个方向都到头。`openWorldHint: true` 同时让
+[core](../../core) 把输出包进 `<tool_output untrusted="true">`——`curl` 抓回来的东西
+和 `web_fetch` 抓的没有区别。
+
+## 平台差异
+
+Windows 默认走 `cmd.exe /d /s /c "<命令>"` + `windowsVerbatimArguments`，POSIX 走
+`$SHELL -c`。判定在 [infra](../../infra) 的 `platform.ts`，两处：`shellSpawnArgs`
+（spawn 用）和 `shellPtyArgs`（node-pty 用）。**不能合并**——node-pty 在 Windows 上
+自己有一套转义，数组形式会被二次转义，实测直接「系统找不到指定的路径」，所以
+Windows 上给字符串、POSIX 上给数组。
+
+Windows 控制台的代码页解码也在 infra（`createStreamDecoder`）。
+
+### 换 shell（只有 Windows 有这回事）
+
+配 `shell: powershell`（或 `pwsh`，见 [cli](../../cli) 的配置表）之后，这个插件
+**一行都不用改**——两个拼参数的函数就是为此存在的抽象边界。但 PowerShell 那条路
+和 cmd 完全不是一回事，两点值得知道：
+
+- **退出码要靠一段收尾语句才准。** PowerShell 5.1 不传播被调命令的退出码，
+  实测 `-Command "cmd /c exit 3"` 拿到的是 `1`。infra 在命令后面接了一段同时读
+  `$?` 和 `$LASTEXITCODE` 的收尾语句，`exitCode` 才是真的
+- **危险命令表仍是 cmd / POSIX 口味的。** `command-safety.ts` 里有 PowerShell 的
+  常见破坏性写法（`Remove-Item -Recurse`、`iwr | iex`、`Start-Process -Verb RunAs`
+  等），但 `isReadOnlyCommand` 的只读白名单认的是 `ls` / `cat` / `git status` 这类。
+  于是 `Get-ChildItem` 不在白名单里 → **更常弹权限确认**。方向是安全的那一边，
+  但用户会明显感觉到多问
+
+POSIX 上这个设置无效，永远 `/bin/sh` —— macOS 走的就是这一支。
+
+### macOS 上要先给 node-pty 的 `spawn-helper` 补执行位
+
+node-pty 1.1.0 发到 npm 的 tarball 里，`prebuilds/darwin-*/spawn-helper` 记的模式是
+`-rw-r--r--`——**没有执行位**。而 POSIX 分支不是自己 `fork()`，是
+`posix_spawnp()` 这个小可执行文件，于是 macOS 上每一次 PTY 执行都直接
+`Error: posix_spawnp failed.`。npm 解包时会按自己的规则重设权限所以看不见，
+**pnpm 忠实照抄 tarball 的模式，就炸**（2026-08-08 CI 的 macOS 腿实测）。
+
+`pty-helper.ts` 在起第一个 PTY 之前把它 `chmod 0o755`，幂等、只跑一次、
+Windows 跳过。放运行时而不是 postinstall：装到用户机器上的是发布出去的包，
+我们的 postinstall 管不到别人怎么装。目录只读时 chmod 会失败，那句失败原因会接在
+node-pty 的报错后面一起返回，而不是让人对着 `posix_spawnp failed.` 猜。
+
+上游是 microsoft/node-pty#850，修在 #866，只进了 1.2.0-beta 线；`latest` 至今还是
+1.1.0。**不为这个升 beta** —— native 模块的 beta 版进产品依赖，风险比这二十行大。
+
+## 开发
+
+```bash
+pnpm --filter @epoch-agent/plugin-terminal test
+```
+
+两个真起进程、真杀、真查残留的端到端用例文件，**改 kill 逻辑必须跑**：
+
+| 文件                       | 平台            | 覆盖                                            |
+| -------------------------- | --------------- | ----------------------------------------------- |
+| `kill-paths-e2e.test.ts`   | Windows + macOS | 超时 / 中断 / PTY 三条终止路径                  |
+| `process-tree-e2e.test.ts` | 仅 POSIX        | 中断 / 输出超限，用 `sh -c 'sleep & wait'` 造树 |
+
+前者造树用 `node spawner.cjs`、查残留用命令行标记（POSIX `pgrep -f`、Windows CIM），
+所以两个平台通吃；后者依赖 shell 方言，Windows 上整个 skip。
+
+⚠️ **PTY 那条用例的曾孙必须 `detached: true`**，否则它在 Windows 上是空的：
+ConPTY 一关，挂在那个伪控制台上的后代会被系统连坐收掉，我们的树遍历一个字都用不上。
+同理 Windows 上 node 起的非 detached 子进程会被 libuv 的全局 Job Object 连坐收掉。
+两条都是实测出来的，别按「能跑就行」改回去——细节记在
+[验收记录](../../../docs/verify/VERIFY_RECORD-16-process-tree.md) 的「追加二」。