dsh-hitl 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,7 @@
 # dsh-hitl · Human-in-the-loop for any tool
 
+[![npm version](https://img.shields.io/npm/v/dsh-hitl)](https://www.npmjs.com/package/dsh-hitl) [![license](https://img.shields.io/npm/l/dsh-hitl)](LICENSE) [![Website](https://img.shields.io/badge/Website-4c566a)](https://yunpengdon.github.io/dsh-hitl-landing/)
+
 English | [中文](README.zh.md)
 
 > **Let the agent ask you before it acts.**
@@ -7,7 +9,7 @@ English | [中文](README.zh.md)
 
 `dsh-hitl` is an installable DeepSeek Harness (DSH) plugin (bundle): **zero dependencies, zero build** — `index.js` (host half) + `client.js` (browser half) + `lib/` are plain JS that loads as it is. Install it, refresh the page once, and it works.
 
-![A complete decision card: title, pending proposal, approve/modify/reject buttons, and a countdown](docs/01-panel-en.png)
+**[View Website](https://yunpengdon.github.io/dsh-hitl-landing/)**
 
 ## Features
 
@@ -18,24 +20,26 @@ English | [中文](README.zh.md)
 - **Rejection with feedback**: 【Reject】 can carry a **feedback box**, and what you write there reaches the agent together with the rejection — it knows "don't do it" *and* "why not";
 - **Configurable countdown**: a **countdown** plus three endings (**approve automatically / reject automatically / report the timeout to the agent**).
 
-![The three proposal renderers in one card: a split diff, a text input, and markdown preview with edit](docs/02-fields-en.png)
 
 ## Made for DSH
 
 **Subagent pass-through: a tool call inside a subagent raises its approval request in the main conversation too.** Every tool call inside an in-process subagent (`spawn` / `fork`) goes through the same gate — the request is filed **both** under the child Session that made it and under the Session you are currently looking at: whichever conversation you are in, the card can appear there, labelled 「from subagent Session xxx」 with an 【Open that Session】 button.
 (Out-of-process backends never reach this gate — see §6.1.)
 
-![A card in the main conversation, labelled as coming from a subagent Session, with a jump button](docs/03-subagent-en.png)
+[See this card on the landing page →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 **A mini approval request even when you are not in a conversation.** Switch to the plugins page, open settings, or select no Session at all, and a notice floats at the top of the page, so HITL does not have to block the run while you are elsewhere (count, tool name, source Session, remaining time + 【Approve】【Reject】【Open that Session】).
 
-![The fallback notice floating above the settings modal](docs/04-overlay-en.png)
+[See the notice on the landing page →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 ---
 
 ## 1. Install
 
 ```sh
+# From npm (the canonical install)
+dsh plugin --profile <your profile> add dsh-hitl
+
 # Straight from GitHub (nothing to build)
 dsh plugin --profile <your profile> add github:YunpengDon/dsh-hitl
 
@@ -66,7 +70,7 @@ Once installed:
   config:
     protect:
       - tool: bash                      # tool name; patterns like 'mcp__*' work too
-        title: 执行命令前确认            # panel title (bold, wraps)
+        title: Confirm before running    # panel title (bold, wraps)
         countdown: { seconds: 30, action: reject }
         reject: { feedback: true }      # show the feedback box on reject
 ```
@@ -82,13 +86,13 @@ export const inject = ['hitl']            // wait for the hitl service before ap
 export function apply(ctx) {
   // Passing your own ctx as the third argument binds the mount to this plugin's lifetime
   ctx.hitl.protect('bash', {
-    title: '这条命令要执行吗？',
+    title: 'Run this command?',
     countdown: { seconds: 30, action: 'reject' },
     reject: { feedback: true },
   }, ctx)
 
   ctx.hitl.protect(['write', 'edit'], {   // arrays, globs, RegExp, and predicates all work
-    title: '改动前确认',
+    title: 'Confirm before editing',
     diff: { path: 'file_path', before: 'old_string', after: 'new_string' },  // folded into a side-by-side diff
     countdown: null,                     // no countdown = wait forever (still cancellable)
   }, ctx)
@@ -139,23 +143,23 @@ Without `fields`, the proposal is **every parameter of this call**:
 | `reject.feedbackPrompt` | string | built-in copy | Feedback box placeholder |
 | `reject.requireFeedback` | boolean | `false` | Feedback is required (an empty box is refused with a hint) |
 | `modify.mode` | `revise-request` \| `allow-and-inform` | `revise-request` | What 【Modify】 means after an edit; see §5 |
-| `whenUnavailable` | `reject` \| `wait` | `reject` | Behaviour with no browser connected (`reject` = fail-closed) |
+| `whenUnavailable` | `reject` \| `wait` | `reject` | Behaviour with no browser connected: `reject` = fail-closed; `wait` = wait indefinitely, so **pair it with a `countdown`** or that call hangs until its Session ends (the host warns at mount time); see §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | Turn a mount off temporarily / make it conditional |
 | `maxFieldChars` | number | `20000` | Per-field render cap; longer values are truncated with a note |
 
 ### FieldSpec
 
 ```js
-{ param: 'content', title: '新内容', description: '会写入文件的内容',
+{ param: 'content', title: 'New content', description: 'Text that will be written to the file',
   render: 'markdown',        // markdown | text | diff | json | hidden
   editable: true,            // overrides the default editability
-  labels: ['不可撤销'],       // field-level labels
+  labels: ['irreversible'],  // field-level labels
   diff: { before: 'old_string', after: 'new_string', path: 'file_path' } }   // used when render: 'diff'
 ```
 
 - With no `render`, a field renders as a diff when one can be configured, and as a markdown input otherwise.
 - When `fields` is given, **only** the listed fields are shown (parameters you leave out never reach the panel).
-- Config rows may shorten a spec to a bare string: `fields: ['command', { param: 'cwd', title: '工作目录' }]`.
+- Config rows may shorten a spec to a bare string: `fields: ['command', { param: 'cwd', title: 'Working directory' }]`.
 
 ### The three endings of a countdown
 
@@ -271,12 +275,36 @@ The panel follows the **application's current language** — not the mounting pl
 - **With no browser connected the default is fail-closed**: a tool mounted behind HITL is rejected and the model sees `Error: HITL: no browser is connected to decide, so tool "x" did not run (fail-closed).` Set `whenUnavailable` to `wait` if it should wait forever in unattended runs instead.
 - In a composition with no Web service at all (headless/TUI) the plugin **stays active and keeps gating** — "no UI, therefore no gate" is not this plugin's semantics.
 
+### 7.1 The security boundary: what HITL stops and what it cannot
+
+- **It stops a call from *starting*; it does not stop the world.** If a tool has already produced a side effect inside its own
+  execution layer (a concurrent race, an asynchronous write, a request already sent), a rejection prevents "next", never "already" —
+  **HITL is neither a transaction nor a sandbox**.
+- So how safe you actually are depends on two things: **① how dangerous the operations your matcher covers are; ② whether the tool
+  puts its irreversible step last.** Mounting `bash` / `write` / `edit` — tools that are dangerous the moment they start — is the
+  right use. If a tool only reveals its risk halfway through, HITL can only help you decide whether to begin.
+- **A human's approval is not a privilege escalation**: the sandbox, guards, hooks and approval still run afterwards (§8); and the
+  reverse holds too — another pre-execution policy can refuse *before* this plugin is even asked. That was measured once:
+  `fs-observation-policy` stopped a call before the human pressed 【Approve】, so no HITL panel ever appeared (§8).
+- **`whenUnavailable: wait` is fail-open**: with no browser connected the call simply waits, and without a `countdown` it waits until
+  its Session ends. Use the fail-closed default (`reject`) when an unattended run must not stall, or pair `wait` with a `countdown`
+  (the host warns at mount time when you do not).
+- **The local trust boundary**: the decision channel and `/status` answer loopback addresses only. Any process on this machine can
+  read `/status`, which carries the **mount list** and, per pending decision, the **tool name / Session id / remaining milliseconds /
+  hold state** — **no tool arguments and no token**. To size that hole precisely: a local process can already read the session logs
+  under `~/.dsh/sessions/**`, which do contain every tool argument, so `/status` exposes a strictly smaller subset of what is already
+  readable locally. The hole is deliberate: without it, "what is HITL holding right now?" could only be answered by opening the page.
+
 ---
 
 ## 8. Relationship to other pre-execution policies
 
 - This plugin listens on `tools/pre-execute` with `prepend: true`, i.e. **ask the human first**; once the human agrees, the sandbox, guards, hooks, approval, and every other policy still run afterwards. **A human's approval is not a privilege escalation.**
 - So "the human approved but the sandbox or a guard still refused" is by design, not a bug.
+- **The reverse holds too**: another pre-execution policy can refuse **before** this plugin is ever asked, in which case no HITL panel
+  appears at all — so "it ran (or failed) without asking me" is a question for the other policies first. Measured once:
+  `fs-observation-policy` demands a re-read before overwriting a deleted file, and it stopped a call both *after* the human pressed
+  【Approve】 (the panel had appeared as usual) and, in another round, *before* this plugin was reached (no panel at all).
 - This plugin only asks before execution: it never rewrites a tool's arguments and never rewrites a tool's result.
 
 ---
@@ -284,6 +312,7 @@ The panel follows the **application's current language** — not the mounting pl
 ## 9. Known limitations
 
 - **Tool arguments cannot be rewritten** (see §5), so 【Modify】 defaults to "refuse and hand the edit back".
+- **HITL is not a side-effect boundary** (see §7.1): it stops a call from starting and cannot roll back a side effect that already happened; how much it protects you depends on the matcher and on the tool's own design.
 - **Mount copy is not localized**: `title` / `labels` / field titles are strings the mounting plugin supplies; this plugin does not translate them and does not accept a `{zh, en}` map (see §6.3).
 - **No session audit event**: DSH does not let a plugin append new event types, so the decision trail lives only in the tool result (and, under `allow-and-inform`, in one user message).
 - **Only the Web UI has a panel**: under ACP/TUI/headless the mount's `whenUnavailable` decides (reject by default).
@@ -356,28 +385,30 @@ Reply: `{ ok: true, accepted: true, held?, expiresAt? }` or
 
 ```text
 dsh-hitl/
-├── index.js                629   host half: service + gate + countdown/hold + SSE & decision routes + token injection
+├── index.js                639   host half: service + gate + countdown/hold + SSE & decision routes + token injection
 ├── client.js              1918   browser half: decision panel + frame-level notice (self-contained classic script, no imports)
 ├── lib/                          the host half's pure logic: no Cordis, no DOM, testable on its own
 │   ├── protocol.js         182   frame and uplink validation, limits, error codes (the single source of the protocol)
-│   ├── resolve.js          302   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
+│   ├── resolve.js          311   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
 │   ├── fields.js           244   default proposal derivation, diff pairing, decision → model-visible text
 │   └── pending.js          217   the pending-decision state machine (injectable clock): countdown, hold, settle-once
 ├── locale/                       the plugin list's name and description (shape must be {"meta":{...}}, see §6.3)
 │   ├── en.json               6
 │   └── zh.json               6
-├── docs/                         the screenshots shown above, one set per language (-en / -cn)
-├── tests/                        zero-dependency Node tests, 151 cases in total
+├── docs/                         screenshot sources, deliberately NOT shipped: the README links the landing page instead
+├── tests/                        zero-dependency Node tests, 153 cases in total
 │   ├── client.test.js      818   (65) the browser half's pure helpers + store / connection / seat
 │   ├── fields.test.js      269   (26) proposal derivation and decision text
 │   ├── pending.test.js     240   (18) the state machine (injected clock, no real waiting)
-│   ├── resolve.test.js     162   (18) matchers and option normalization
+│   ├── resolve.test.js     181   (19) matchers and option normalization
 │   ├── protocol.test.js    117   (16) frame and uplink validation
-│   ├── docs.test.js        116   (5) the two READMEs, their links, and the numbers in this very table
-│   └── manifest.test.js     61   (3) package metadata and the locale resource shape
-├── package.json             69   manifest: exports / dsh.bundle.patch / dsh.client / icon
+│   ├── docs.test.js        121   (5) the two READMEs, the landing-page link, and the numbers in this very table
+│   └── manifest.test.js     77   (4) package metadata and the locale resource shape
+├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
+├── package.json             68   manifest: exports / dsh.bundle.patch / dsh.client / icon
 ├── cordis.patch.yml         17   the bundle's configuration layer (inserts the row with id `hitl`)
 ├── icon.svg                  6   the plugin list icon
+├── LICENSE                       MIT
 ├── README.md                     this document
 └── README.zh.md                  the Chinese twin of this document
 ```
@@ -389,7 +420,7 @@ dsh-hitl/
 | `index.js`, `lib/*.js` | host half (Node) | **restart dsh**. Node's ESM module cache is not invalidated by "disable → enable on that row" |
 | `client.js` | browser half | **client hot-reload** picks it up (the host stats each row's client artefact every 500ms and broadcasts over `/plugins/events`); no page refresh needed |
 | `locale/*.json` | plugin-list metadata | when the plugin manager re-reads metadata (opening the plugins page / restarting dsh) |
-| `docs/*.png` | documentation | when the README is rendered |
+| `docs/*.png` | screenshot sources | kept in the repository only; the published package excludes them (see the appendix note) |
 | `package.json`, `cordis.patch.yml` | manifest and config layer | a restart or a reload of that row; an installed package is not swapped in place |
 | `tests/*.js` | development | never runs in production; executed by `npm test` / `node --test` |
 
@@ -405,7 +436,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # syntax
-npm test                                     # 151 zero-dependency cases: pure functions, state machines, the channel
+npm test                                     # 153 zero-dependency cases: pure functions, state machines, the channel
 npm run check                                # both of the above (syntax + the whole suite)
 ```
 

package/README.zh.md

@@ -1,5 +1,7 @@
 # dsh-hitl · 给任意工具挂上人工决策（Human-in-the-loop）
 
+[![npm version](https://img.shields.io/npm/v/dsh-hitl)](https://www.npmjs.com/package/dsh-hitl) [![license](https://img.shields.io/npm/l/dsh-hitl)](LICENSE) [![官网](https://img.shields.io/badge/%E5%AE%98%E7%BD%91-4c566a)](https://yunpengdon.github.io/dsh-hitl-landing/)
+
 [English](README.md) | 中文
 
 > **让 Agent 在动手之前，先问你一句。**
@@ -8,7 +10,7 @@
 `dsh-hitl` 是 DeepSeek Harness (DSH) 的可安装插件（bundle）：**零依赖、零构建**——`index.js`（宿主半）+ `client.js`（浏览器半）+ `lib/`
 全是可直接加载的纯 JS，装上刷新一次页面就能用。
 
-![一张完整的决策卡：标题 + 待决策提案 + 同意/修改/拒绝 + 倒计时](docs/01-panel-cn.png)
+**[访问网站](https://yunpengdon.github.io/dsh-hitl-landing/)**
 
 ## 主要功能
 
@@ -19,7 +21,6 @@
 - **带反馈文本的拒绝**：【拒绝】可以带一个**反馈栏**，在反馈栏中写下的意见会随拒绝一起交给 Agent——它知道"不要做"，也知道"为什么不要做"；
 - **支持倒计时配置**：可配置**倒计时**与三种结局（**自动同意 / 自动拒绝 / 把超时事件反馈给 Agent**）；
 
-![提案区三种形态同框：并排 diff / 文本输入框 / markdown 的预览与编辑](docs/02-fields-cn.png)
 
 ## 为DSH定制的适配
 
@@ -28,18 +29,21 @@
 「来自子代理会话 xxx」+【前往该会话】。
 （跨进程后端不进这道门禁，见 §6.1。）
 
-![主对话里的卡片：标着「来自子代理会话」+【前往该会话】](docs/03-subagent-cn.png)
+[在 landing page 上看这张卡 →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 **不在对话界面上时，支持弹出迷你批准请求** 切到插件页、打开设置、甚至没选会话时，页面顶部会浮出一条提醒事项，减少用户不在对话页时HITL对流程的阻塞。
 （条数、工具名、来源会话、剩余时间 +【同意】【拒绝】【前往该会话】）。
 
-![设置面板之上浮着的兜底提醒条](docs/04-overlay-cn.png)
+[在 landing page 上看这条浮层 →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 ---
 
 ## 1. 安装
 
 ```sh
+# 从 npm 装（推荐方式）
+dsh plugin --profile <你的 profile> add dsh-hitl
+
 # 直接从 GitHub 装（无需构建）
 dsh plugin --profile <你的 profile> add github:YunpengDon/dsh-hitl
 
@@ -152,7 +156,7 @@ export function apply(ctx) {
 | `reject.feedbackPrompt` | string | 内置文案 | 反馈栏 placeholder |
 | `reject.requireFeedback` | boolean | `false` | 反馈必填（为空时拒绝按钮会提示） |
 | `modify.mode` | `revise-request` \| `allow-and-inform` | `revise-request` | 用户改了文本后点【修改】的语义，见 §5 |
-| `whenUnavailable` | `reject` \| `wait` | `reject` | 没有任何浏览器连接时的行为（`reject` = fail-closed） |
+| `whenUnavailable` | `reject` \| `wait` | `reject` | 没有任何浏览器连接时的行为：`reject` = fail-closed；`wait` = 一直等，**务必配 `countdown`**，否则那次调用会挂到会话结束（挂载时宿主会给 `dsh-hitl:` 警告），见 §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | 临时关闭 / 条件挂载 |
 | `maxFieldChars` | number | `20000` | 单字段渲染上限，超出会截断并提示 |
 
@@ -337,6 +341,21 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
   想让它在无人值守时一直等，把 `whenUnavailable` 设为 `wait`。
 - 插件在没有任何 Web 服务的组合里（headless/TUI）**仍然激活并继续拦**——"没有 UI 就不拦"不是本插件的语义。
 
+### 7.1 安全边界：HITL 拦得住什么、拦不住什么
+
+- **它拦的是"这一次调用在真正执行之前"，不是世界状态。** 如果工具在自己的执行层已经产生了副作用（并发竞态、异步落盘、
+  已经发出去的外部请求），拒绝只能阻止"接下来"，回滚不了"已经"——**HITL 不是事务，也不是沙箱**。
+- 所以实际安全程度取决于两件事：**① 你的 matcher 覆盖了多危险的操作；② 工具是否把不可逆动作放在最后一刻。**
+  把 `bash` / `write` / `edit` 这类"入口即危险"的工具挂上是对的；若某个工具的风险要到执行中途才出现，HITL 只能替你决定"要不要开始"。
+- **用户的同意 ≠ 越权**：同意之后沙箱、guard、hooks、审批照常随后生效（§8）；反过来，别的执行前策略也可能**先于**本插件拒绝——
+  实测过一次：`fs-observation-policy` 在用户点【同意】之前就把调用挡了，HITL 连面板都没弹（见 §8）。
+- **`whenUnavailable: wait` 是 fail-open**：没有任何浏览器连接时会一直等，没配 `countdown` 就是等到会话结束。
+  想让"无人值守也不卡死"，用默认的 `reject`，或者 `wait` + `countdown`（挂载时宿主会对这种组合给出警告）。
+- **本机信任边界**：决策通道与 `/status` 都只认回环地址。同机任意进程可以读 `/status`，它只含**挂载列表**与**待决策的
+  工具名 / 会话 id / 剩余毫秒 / 是否暂停**——**没有工具参数，也没有令牌**。要把这个口子量准：同机进程本来就能读
+  `~/.dsh/sessions/**` 的会话日志，而那里有完整的工具参数，所以 `/status` 的暴露面是它严格更小的子集。
+  这个口子是有意保留的：没有它，在终端里回答"HITL 现在拦着什么"就只能靠翻页面。
+
 ---
 
 ## 8. 与其他执行前策略的关系
@@ -344,6 +363,9 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 - 本插件用 `tools/pre-execute` 且 `prepend: true`，也就是**先问人**；用户同意后，
   沙箱、guard、hooks、审批等其它策略照常随后生效。**用户的同意不等于越权**。
 - 因此可能出现"用户同意了，但工具仍被沙箱/守卫拒绝"——这是设计使然，不是 bug。
+- **反过来也成立**：别的执行前策略可能在**本插件之前**就拒绝，此时 HITL 面板根本不会出现——所以"没弹面板就直接执行了/就失败了"
+  两种现象都要先看别的策略。实测过一次：`fs-observation-policy` 要求"重写已删除文件前先重读"，
+  它在用户点【同意】**之后**把调用挡了下来（面板照常弹过），也在另一轮里**先于**本插件直接拒绝（面板没弹）。
 - 本插件只做"执行前问人"，不改变工具参数、不改变工具结果。
 
 ---
@@ -351,6 +373,7 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 ## 9. 已知限制
 
 - **不能改写工具参数**（见 §5），所以【修改】默认走"拒绝并交回修改内容"。
+- **HITL 不是副作用边界**（见 §7.1）：它拦的是"调用开始之前"，回滚不了已经发生的副作用；安全性取决于 matcher 覆盖面与工具自身的设计。
 - **挂载文案不本地化**：`title` / `labels` / 字段标题都是挂载方给的字符串，本插件不翻译，也不接受 `{zh, en}` 映射（见 §6.3）。
 - **不写会话审计事件**：DSH 不允许插件追加新的事件类型，决策痕迹只存在于工具结果（和 `allow-and-inform` 的那条 user 消息）里。
 - **只有 Web 界面有面板**：ACP/TUI/headless 下按 `whenUnavailable` 处理（默认拒绝）。
@@ -425,28 +448,30 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 
 ```text
 dsh-hitl/
-├── index.js                629   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
+├── index.js                639   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
 ├── client.js              1918   浏览器半：决策面板 + 帧级浮层（自包含 classic script，无 import）
 ├── lib/                          宿主半的纯逻辑：不碰 Cordis、不碰 DOM，可单独跑测试
 │   ├── protocol.js         182   帧与上行校验、上限、错误码（协议规范的唯一出处）
-│   ├── resolve.js          302   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
+│   ├── resolve.js          311   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
 │   ├── fields.js           244   默认提案推导、diff 配对、决策 → 模型可见文本
 │   └── pending.js          217   待决策状态机（可注入时钟）：倒计时、持握、恰好一次的结算
 ├── locale/                       插件列表里的名字与简介（形状必须是 {"meta":{...}}，见 §6.3）
 │   ├── en.json               6
 │   └── zh.json               6
-├── docs/                         上文那些截图，中英各一套（-cn / -en）
-├── tests/                        零依赖 Node 测试，共 151 个用例
+├── docs/                         截图源文件，**故意不进 npm 包**：README 改为链接 landing page
+├── tests/                        零依赖 Node 测试，共 153 个用例
 │   ├── client.test.js      818   （65）浏览器半的纯函数 + store / connection / seat
 │   ├── fields.test.js      269   （26）提案推导与决策文本
 │   ├── pending.test.js     240   （18）状态机（注入时钟，无真实等待）
-│   ├── resolve.test.js     162   （18）matcher 与选项归一化
+│   ├── resolve.test.js     181   （19）matcher 与选项归一化
 │   ├── protocol.test.js    117   （16）帧与上行校验
-│   ├── docs.test.js        116   （5）两份 README、互链，以及上面这张表里的每个数字
-│   └── manifest.test.js     61   （3）包元数据与 locale 资源形状
-├── package.json             69   清单：exports / dsh.bundle.patch / dsh.client / icon
+│   ├── docs.test.js        121   （5）两份 README、landing page 链接，以及上面这张表里的每个数字
+│   └── manifest.test.js     77   （4）包元数据与 locale 资源形状
+├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
+├── package.json             68   清单：exports / dsh.bundle.patch / dsh.client / icon
 ├── cordis.patch.yml         17   bundle 的配置层（插入 id 为 hitl 的那一行）
 ├── icon.svg                  6   插件列表图标
+├── LICENSE                       MIT
 ├── README.md                     本文档（英文版）
 └── README.zh.md                  本文档的中文版
 ```
@@ -458,7 +483,7 @@ dsh-hitl/
 | `index.js`、`lib/*.js` | 宿主半（Node） | 必须**重启 dsh**。Node 的 ESM 模块缓存不会因为"禁用→启用这一行"而失效 |
 | `client.js` | 浏览器半 | **客户端热重载**自动拾取（宿主每 500ms stat 一次各行的 client 产物并广播 `/plugins/events`），不用刷新页面 |
 | `locale/*.json` | 插件列表元数据 | 插件管理器重读元数据时生效（打开插件页 / 重启 dsh） |
-| `docs/*.png` | 文档 | README 渲染时 |
+| `docs/*.png` | 截图源文件 | 只留在仓库里；发布的包里不再包含（见附录说明） |
 | `package.json`、`cordis.patch.yml` | 清单与配置层 | 需要重启或重新加载该行；已安装包不会被就地替换 |
 | `tests/*.js` | 开发期 | 不参与运行，只由 `npm test` / `node --test` 执行 |
 
@@ -480,7 +505,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # 语法
-npm test                                     # 151 个纯函数/状态机/通道用例，零依赖
+npm test                                     # 153 个纯函数/状态机/通道用例，零依赖
 npm run check                                # 上面两步合起来（语法 + 全部用例）
 ```
 

package/index.js

@@ -107,7 +107,14 @@ export function apply(ctx, config = {}) {
   const clients = new Set()
   const resolvers = new Map()
   const cleanups = new Map()
-  const revisions = new Map()
+  // Revision context for `allow-and-inform`, keyed by the execution object the
+  // pipeline carries from `tools/pre-execute` through `tools/post-execute`.
+  // A WeakMap, not a callId-keyed Map: if a call is allowed and then never
+  // reaches post-execute (an aborted turn, a process torn down mid-execution),
+  // a Map entry would outlive the call for the rest of the process. Keyed by
+  // the execution itself, the entry dies with the call that owns it, so there
+  // is nothing to leak and nothing to remember to clean up.
+  const revisions = new WeakMap()
 
   const registry = createPendingRegistry({
     holdGraceMs: positiveInteger(options.holdGraceMs, DEFAULT_HOLD_GRACE_MS),
@@ -293,7 +300,9 @@ export function apply(ctx, config = {}) {
     if (settlement.decision.kind === 'cancel') return { kind: 'cancel' }
     const revising = isRevision(settlement.decision)
     if (revising && mount.options.modify.mode === 'allow-and-inform' && settlement.source === OUTCOMES.user) {
-      if (exec.callId !== undefined) revisions.set(String(exec.callId), { request, decision: settlement.decision })
+      // The call is about to run with its original arguments; the edit rides
+      // along as context on the result instead (see the post-execute listener).
+      revisions.set(exec, { request, decision: settlement.decision })
       return { kind: 'allow' }
     }
     const info = settlement.source === OUTCOMES.timeout
@@ -342,17 +351,17 @@ export function apply(ctx, config = {}) {
 
   /**
    * Hand the user's revision to the model next to the result it approved, in
-   * the `allow-and-inform` modify mode. The message is built to the shape
-   * `createUserMessage` produces, because a plain bundle cannot import that
-   * factory; `source.kind` is the standard `user` one.
+   * the `allow-and-inform` modify mode. Lookup is by the execution object, so a
+   * call that never reaches this stage costs nothing but its own lifetime; the
+   * delete keeps a second post-execute for the same execution from attaching
+   * the same context twice.
    */
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    if (revisions.size === 0 || exec.callId === undefined) return decision
-    const key = String(exec.callId)
-    const revision = revisions.get(key)
+    const revision = revisions.get(exec)
     if (revision === undefined) return decision
-    revisions.delete(key)
+    revisions.delete(exec)
+    const label = exec.callId === undefined ? String(exec.name) : String(exec.callId)
     try {
       const message = {
         id: randomUUID(),
@@ -362,7 +371,7 @@ export function apply(ctx, config = {}) {
       }
       return { ...decision, additionalContexts: [...(decision.additionalContexts ?? []), message] }
     } catch (error) {
-      warn(`the revision context for ${key} was dropped: ${String(error)}`)
+      warn(`the revision context for ${label} was dropped: ${String(error)}`)
       return decision
     }
   })
@@ -622,7 +631,8 @@ export function apply(ctx, config = {}) {
       }
     }
     mounts.length = 0
-    revisions.clear()
+    // `revisions` is a WeakMap: shutdown has nothing to clear, and a call that
+    // never came back takes its own entry with it.
     resolvers.clear()
     cleanups.clear()
   }, 'dsh-hitl: shutdown')

package/lib/resolve.js

@@ -216,6 +216,17 @@ export function normalizeMount(input, source) {
   const labels = Array.isArray(input.labels)
     ? input.labels.filter(label => typeof label === 'string' && label !== '')
     : []
+  const countdown = normalizeCountdown(input.countdown, report)
+  const unavailable = WHEN_UNAVAILABLE.includes(whenUnavailable)
+    ? whenUnavailable
+    : DEFAULT_OPTIONS.whenUnavailable
+  // `wait` is fail-open by design: with no browser attached the call sits there
+  // until something ends it. Without a countdown, "something" means the session
+  // or the plugin, so an unattended run blocks an agent for as long as it lives.
+  // Say so at mount time rather than letting the first unattended run discover it.
+  if (unavailable === 'wait' && countdown === null) {
+    report('whenUnavailable: wait without a countdown blocks an unattended call until its session ends; pair it with countdown.seconds or use the fail-closed default')
+  }
   const mount = {
     describe: matcher.describe,
     test: matcher.test,
@@ -226,12 +237,10 @@ export function normalizeMount(input, source) {
       buttons: normalizeButtons(input.buttons, report),
       fields,
       diff: input.diff,
-      countdown: normalizeCountdown(input.countdown, report),
+      countdown,
       reject: normalizeReject(input.reject, report),
       modify: normalizeModify(input.modify, report),
-      whenUnavailable: WHEN_UNAVAILABLE.includes(whenUnavailable)
-        ? whenUnavailable
-        : DEFAULT_OPTIONS.whenUnavailable,
+      whenUnavailable: unavailable,
       enabled: input.enabled === undefined ? true : input.enabled,
       maxFieldChars,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hitl",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Human-in-the-loop gate for DSH tool calls: mount any tool behind an approve / modify / reject decision card in the DSH Web UI, with an optional countdown.",
   "keywords": [
     "dsh",
@@ -39,7 +39,6 @@
     "lib",
     "tests",
     "locale",
-    "docs",
     "icon.svg",
     "cordis.patch.yml",
     "README.md",

package/tests/docs.test.js

@@ -15,6 +15,8 @@ import { fileURLToPath } from 'node:url'
  */
 const root = join(dirname(fileURLToPath(import.meta.url)), '..')
 
+const LANDING_PAGE = 'https://yunpengdon.github.io/dsh-hitl-landing/'
+
 /** The English README is the package's front page; the Chinese one is its twin. */
 const READMES = [
   { language: 'en', file: 'README.md', other: 'README.zh.md', suffix: '-en' },
@@ -62,21 +64,22 @@ describe('docs: the English and Chinese READMEs', () => {
     }
   })
 
-  it('shows every screenshot, and only its own language', () => {
-    const referenced = new Set()
-    const available = new Set(readdirSync(join(root, 'docs')))
+  it('sends the reader to the landing page instead of shipping screenshots', () => {
+    // The four screenshots used to be the bulk of the published tarball. They
+    // live on the landing page now (its own repository carries them, in both
+    // languages), so the READMEs must link it and must not reference a local
+    // copy — and the package must not carry one either.
+    const manifest = JSON.parse(read('package.json'))
+    assert.equal(manifest.files.includes('docs'), false, 'screenshots must stay out of the tarball')
     for (const readme of READMES) {
-      const images = [...read(readme.file).matchAll(/!\[[^\]]*\]\((docs\/[^)]+)\)/g)].map(match => match[1])
-      assert.equal(images.length, 4, `${readme.file} must place all four screenshots`)
-      for (const image of images) {
-        const name = image.slice('docs/'.length)
-        assert.equal(available.has(name), true, `${readme.file} references a missing screenshot: ${image}`)
-        assert.equal(name.endsWith(`${readme.suffix}.png`), true, `${readme.file} must use its ${readme.suffix} screenshots`)
-        referenced.add(name)
-      }
-    }
-    for (const name of available) {
-      assert.equal(referenced.has(name), true, `docs/${name} is shipped but never shown`)
+      const text = read(readme.file)
+      assert.equal(text.includes(LANDING_PAGE), true, `${readme.file} must link the landing page`)
+      assert.equal(
+        /!\[[^\]]*\]\(docs\//.test(text), false,
+        `${readme.file} must not embed a local screenshot`,
+      )
+      const header = text.split('\n').slice(0, 8).join('\n')
+      assert.equal(header.includes(LANDING_PAGE), true, `${readme.file} must offer the tour near the top`)
     }
   })
 
@@ -108,9 +111,11 @@ describe('docs: the English and Chinese READMEs', () => {
     }
   })
 
-  it('keeps the screenshot folder shipped', () => {
+  it('publishes both READMEs and keeps the screenshot sources in the repository only', () => {
     const manifest = JSON.parse(read('package.json'))
-    assert.equal(manifest.files.includes('docs'), true, '`docs` must be published with the screenshots')
     assert.equal(manifest.files.includes('README.zh.md'), true, 'the Chinese README must be published too')
+    // The landing page's own repository carries the screenshots, so a second
+    // copy inside the package would only double the download for every install.
+    assert.equal(manifest.files.includes('docs'), false, 'screenshot sources must stay out of the tarball')
   })
 })

package/tests/manifest.test.js

@@ -24,6 +24,22 @@ const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
 const LANGUAGES = ['en', 'zh']
 
 describe('manifest: what a profile reads about this plugin', () => {
+  it('keeps the tag-triggered release on stage-only trusted publishing', () => {
+    const workflow = readFileSync(join(root, '.github', 'workflows', 'release.yml'), 'utf8')
+    assert.equal(workflow.includes("tags: ['v*']"), true, 'the workflow must trigger on version tags')
+    assert.equal(workflow.includes('id-token: write'), true, 'OIDC publishing needs the id-token permission')
+    assert.equal(workflow.includes('contents: read'), true)
+    // Stage-only: the workflow may upload a release, but a maintainer approves
+    // it with 2FA before it becomes public, so it must never publish directly.
+    assert.equal(/run: npm stage publish/.test(workflow), true, 'the release step must stage')
+    assert.equal(/run: npm publish\b/.test(workflow), false, 'a direct publish would need "publish directly" granted')
+    // Provenance is automatic under trusted publishing — but this file *talks*
+    // about that, so assert on the command, not on the words.
+    assert.equal(/npm stage publish[^\n]*--provenance/.test(workflow), false, 'no --provenance flag on the command')
+    // npm matches the configured trusted publisher against this exact filename.
+    assert.equal(workflow.includes('release.yml'), true, 'the trusted publisher is configured with this filename')
+  })
+
   it('resolves the resources the Loader asks for by name', () => {
     assert.equal(manifest.name, 'dsh-hitl')
     assert.equal(typeof manifest.description, 'string')

package/tests/resolve.test.js

@@ -79,6 +79,25 @@ describe('resolve: normalizeMount', () => {
     assert.match(warnings[0], /countdown.seconds/)
   })
 
+  it('warns when a mount waits forever with nothing to end the wait', () => {
+    // Fail-open plus no deadline is legal, and it blocks an unattended call for
+    // as long as its session lives. The mount is still installed; the warning is
+    // the whole point, because the first unattended run must not be the discovery.
+    const open = normalizeMount({ tool: 'bash', whenUnavailable: 'wait' }, 'src')
+    assert.equal(open.ok, true)
+    assert.equal(open.mount.options.whenUnavailable, 'wait')
+    assert.equal(open.warnings.length, 1)
+    assert.match(open.warnings[0], /whenUnavailable: wait without a countdown/)
+
+    // A deadline is what bounds it, so the pairing is silent — and so is the
+    // fail-closed default, which needs no deadline to be safe.
+    const bounded = normalizeMount({ tool: 'bash', whenUnavailable: 'wait', countdown: { seconds: 300, action: 'reject' } }, 'src')
+    assert.equal(bounded.warnings.length, 0)
+    const closed = normalizeMount({ tool: 'bash' }, 'src')
+    assert.equal(closed.mount.options.whenUnavailable, 'reject')
+    assert.equal(closed.warnings.length, 0)
+  })
+
   it('normalizes field entries and drops invalid ones', () => {
     const { mount, warnings } = normalizeMount({
       tool: 'edit',