@hyzyn/dsh-tty 0.20.2 → 0.22.0-rc.1

package/README.en.md

@@ -97,7 +97,7 @@ Both were reproduced on **Windows 11 ARM (24H2) + Node 22 ARM64**. The fix:
   on Windows, and its `_deferNoArgs` re-throws that error from a socket callback, where the caller’s
   try/catch cannot see it.
 
-## Agent tools (P1)
+## Agent tools
 
 The plugin injects sixteen tools into the agent (with the same power as the bash tool; operations show up live in the user’s terminal):
 
@@ -109,7 +109,7 @@ The plugin injects sixteen tools into the agent (with the same power as the bash
 | `tty_stats` | Read live host metrics for a session’s machine (0.20.0): CPU / memory / disk / TCP connections / network rates / temperature / uptime. Local sessions report the host; SSH sessions report that remote host over a separate non-PTY channel that never touches the terminal. Check it before deploying or load-testing |
 | `tty_capture` | Read recent output (last N lines, ANSI stripped by default, `raw:true` for the raw stream); **`last:true` returns only the output + exit code of the previous completed command** (shell integration markers, see the next section); when a command is **in flight** (just sent, completion marker not in yet) it returns `inProgress:true` without the stale result, so the previous command is never mistaken for this one (0.19.0) |
 | `tty_screen` | Read the **currently visible screen** as rendered (xterm-headless virtual screen, plain text) — it can genuinely read TUI interfaces such as vim / htop / menus |
-| `tty_expect` | Wait with a regex for a readiness signal in **subsequent output** (dev server URL, build finished, …); a timeout does not throw (`matched:false` + tail output), and a command that ends early also returns early with its exit code; at most 5 in-flight calls per session, and the accumulated window keeps only the last 64KB (0.19.0) |
+| `tty_expect` | Wait with a regex for a readiness signal (dev server URL, build finished, …). It **looks back first** at output that has not been read yet (including the full output of “the previous command”, so a command that finished instantly no longer burns the whole timeout) and then waits for subsequent output; on a hit it returns `matched:true` plus `matchedFrom` (`live` produced during this wait / `last` the previous command’s output / `buffered` buffered output that had already arrived). A timeout does not throw (`matched:false` + tail output, and it **does not consume the unread region**, so a different pattern can still look back at the same output), and a command that ends early also returns early with its exit code; the echo never counts as a hit (via the OSC 133 A..B boundary — see the next section for environments without markers); at most 5 in-flight calls per session, and the accumulated window keeps only the last 64KB (0.19.0; look-back matching, see D72) |
 | `tty_send` | Send keys/text to a given session (such as `q` to a dev server, or a menu selection) |
 | `sftp_list` | List a remote SSH directory (name/type/size/mtime, directories first); `book` is the connection-book entry name and `path` defaults to the login home; at most 500 entries by default (`truncated:true` beyond that), and `isSymlink` distinguishes a symlink from a real directory (0.19.0) |
 | `sftp_read` | Read a remote **text** file (≤256KB by default, adjustable to 1MB, truncated beyond that); `offset` pages from a given byte (handy for log tails), an invalid `maxBytes` errors out instead of silently falling back, and binary detection is a double test (NUL + illegal-UTF-8 ratio) (0.19.0) |
@@ -152,6 +152,30 @@ At spawn time hooks are injected through the existing `-c` wrapper layer accordi
   code / `OSC 7 file://…` cwd reporting (`tty_list.cwd` follows `cd`, and SSH sessions report the remote path);
 - Other shells are silently disabled; `shellIntegration: false` turns the whole thing off (escape hatch).
 
+**Look-back matching and the read watermark (D72)**: `tty_expect` first looks back at output that has
+**not been read yet** (when a command finishes instantly, the marker you are waiting for is already in the
+buffer). The look-back lower bound is raised to “just after the last `B` marker” inside the unread region —
+the echo sits between `A` and `B`, so text in the echo never counts as a hit (deliberately no text
+comparison here: line wrapping / ANSI / multi-line paste would break it).
+
+- **Environments without `B` markers** (integration off / local Windows tabs / a remote host without the
+  hooks) cannot tell the echo apart and degrade to “scan from the watermark, possibly matching the echo
+  itself” — a known limitation;
+- **The tradeoff in that look-back range**: raising the lower bound to “just after the last `B` marker”
+  costs you the unread output that precedes the newest command’s start. It deliberately prefers a miss
+  over a false hit — treating the echo as a match would make the agent believe the event just happened.
+  Use `tty_capture` for that text. The mirror-image corner exists too: right after `tty_send`, before the
+  new command’s `B` marker arrives, the unread region still holds the previous command’s output, so a
+  pattern in it matches at once (the agent’s next call almost always lands after that `B`, where this
+  text has already been cut off by it);
+- **Read watermark**: whatever `tty_capture` / `tty_expect` returns counts as read, and later
+  `tty_expect` calls will not look back at it (use `tty_capture` to re-read older output). `tty_screen`
+  deliberately does **not** advance it (the screen is a different representation, not a text stream);
+  `tty_send` only initialises it (the output of the command just sent has not been seen yet); **a timeout
+  does not consume the unread region** either (another pattern can still look back at the same output).
+  A tab the user opened gets its watermark placed at the moment the agent first touches it — history
+  before that does not count as unread.
+
 SSH sessions are scheduled on the same table: entries with `kind: 'ssh'` in `tty_list` are identified by
 `target` (user@host[:port]), and `tty_capture` / `tty_expect` / `tty_send` are used exactly as for local
 sessions — dev server logs and key interactions on the remote machine remain available as usual.
@@ -248,6 +272,11 @@ references one connection-book entry (host and authentication come with it), in
   SSH connection), and tunnels keep running with the panel closed; SSH disconnects reconnect automatically
   with exponential backoff (1s→15s cap), and the remote direction re-runs forwardIn after a reconnect; after
   the connection-book password changes, a reconnect uses the new credentials automatically;
+- **Profiles running side by side must offset their localPort**: port forwarding is a **machine-level**
+  resource, while the configuration is stored per profile (copying a profile copies its tunnels too). Two
+  profiles running the same tunnel at the same time leave the later one with `EADDRINUSE`, stuck in
+  `error` with `fatal:true` (**no retry**; changing the configuration rebuilds it from the new spec). The
+  error message names “possibly the host process of another DSH profile” and offers two ways out;
 - **Status badges**: while the card is expanded it polls live status every 2s (active green/connecting
   blue/error red/stopped grey + last error); connection-book entries in the “+” menu show a `⇄N` tunnel
   badge; the agent can query status with the `tunnel_list` tool;
@@ -455,7 +484,22 @@ and the agent tools all reuse the same scheduling.
   `agentForward` and show `· fwd` in the list;
 - **`~/.ssh/config` import (0.4.0)**: “Import from ~/.ssh/config” in the connection-book area of the settings
   card — parses `HostName/User/Port/IdentityFile` into candidate entries (skipping wildcard blocks and
-  entries without a User; `Include` is not expanded), skips same names, and writes them on “save”;
+  entries without a User; `Include` is not expanded), skips same names, and writes them on “save”.
+  **Every skip is now reported** (this round): blocks that depend on a jump host (`ProxyJump` /
+  `ProxyCommand`) are **not imported and are named** — this version does not support jump hosts, and
+  importing one would only produce an entry that cannot connect and reports a generic timeout; the
+  over-limit count and the “not a concrete host” count are reported too. `ProxyJump none` /
+  `ProxyCommand none` mean an explicit direct connection and are imported as usual.
+  **`ProxyJump` is resolved into the entry's jump host (single hop) and imported with it**: the
+  value may be `user@host:port` (IPv6 as `[::1]:22`) or another concrete Host in the same config
+  (resolved by block name, in any order); the jump host **inherits the target hop's credentials**
+  by default, so set `jump.keyPath` / `jump.password` on the entry when it needs its own.
+  Unresolvable ones (missing alias, or an alias that itself needs a jump) are still skipped and
+  named; `ProxyCommand` is not supported (it would let a settings field drive arbitrary local
+  command execution — a different trust tier, see project ROADMAP item 2). **The dialog also has a “Jump host” section**: one
+  `[user@]host[:port]` input (matching OpenSSH), with user / auth / key / passphrase overrides
+  revealed only after ticking “use separate credentials”; entry rows show “⇢ via X”, and the
+  “Test” button reports the jump hop on its own line;
 - **Credential-reference picker (0.4.0; decoupled from the env plugin since 0.17)**: next to the password /
   passphrase fields in the SSH dialog there is a filter box plus a height-limited list whose candidates are
   **the reference names the credential store already knows** (the host reads the `refs:` keys of
@@ -597,6 +641,12 @@ ctx.inject(['ttyConnbar'], (c) => {
 | `requestRender()` | Asks tty to re-render the connection bar (for when a consumer has new data asynchronously and needs the button to appear immediately) |
 
 - It only fires on **SSH tabs**; the connection bar of a local tab is hidden anyway.
+- **Command tabs do not fire it** (`spawnSpec.command` non-empty, i.e. a tab running a command through
+  `ttyTerminal.open`, such as dsh-docker’s `docker exec -it …`): those connection-bar extensions act on
+  **the connection itself**, and hanging them on a command tab would mislead (SFTP would browse the host,
+  not the inside of the container the user has in mind). Built-in and third-party actions are hidden
+  together; the reopen entry point for an exited tab is not affected — the terminal body already carries a
+  “click to reopen” overlay.
 - A throwing factory is only logged with `console.warn`, without affecting the connection bar or the built-in buttons.
 - The service name `ttyConnbar` is not declared on tty’s `Context` type surface, so consumers can inject it by
   string; when tty is not installed or is older than 0.13.0 the injection never fires, so consumers must treat
@@ -730,6 +780,22 @@ ctx.inject(['ttyPanel'], (c) => {
 - The title bar (title / collapse / ✕) is provided by tty, and consumers only own their own body; a throwing
   `onClose` is only logged with `console.warn`, without affecting closing the panel.
 
+**`minimize()` (contract v2)** folds the whole terminal panel away: the modal is hidden, but the DOM /
+WebSocket / xterm buffers are all kept and **the session keeps running**; restoring it goes through the badge
+on the sidebar’s “Terminal” entry. Consumers use it to “give the stage back” — the typical case is dsh-docker
+handing the logs over to the session and folding the terminal away automatically, so the user sees the session
+directly instead of staring at a modal covering it and guessing “did my click do nothing?”. The return value is
+the minimized state after the call, which the caller uses to decide whether its message still needs to say
+“the session is behind the panel”.
+
+```js
+ctx.inject(['ttyPanel'], (c) => {
+  if (Number(c.ttyPanel.version ?? 0) < 2 || typeof c.ttyPanel.minimize !== 'function') return false
+  if (c.ttyPanel.isOpen() !== true) return false
+  return c.ttyPanel.minimize()   // fold the terminal away so the session shows through
+})
+```
+
 > Contract versions: `ttyConnbar.version === 1`, `ttyTerminal.version === 3` (1 = `open` only,
 > 2 = adds `mount`, 3 = `open` reuses an existing live tab for the same connection + command by default),
 > `ttyPanel.version === 2` (1 = `mountPane` + `isOpen`, 2 = adds `minimize`). Consumers **decide capabilities
@@ -964,7 +1030,13 @@ Host half (src/index.ts)
   │  /api/dsh-tty/credential-refs (reference names known to the credential store — names only, see
   │  “Credential storage”), /api/dsh-tty/env-vars (variable names managed by the env plugin), /api/dsh-tty/known-hosts
   │  (TOFU fingerprint prefill, src/known-hosts.ts parses hashed entries too),
-  │  /api/dsh-tty/shells (shell path candidates) — all behind the loopback fence
+  │  /api/dsh-tty/shells (shell path candidates) — all behind the loopback fence (hardened
+  │  tier: the whole 127/8 range + DNS confirmation for alias hostnames + source checks before
+  │  DNS; one implementation only, in @hyzyn/dsh-kit); **state-changing endpoints additionally
+  │  require a same-origin proof** (POST /probe, sftp mkdir/rename/remove/upload, local-fs
+  │  mkdir/rename/remove/transfer); read-only endpoints (including sftp /list and /download)
+  │  need no proof, so bare curl still works. POST /config is deliberately exempt — it is the
+  │  only recovery entry once the plugin is disabled
   ├─ SFTP (src/sftp.ts, 0.7.0): lazy connection pool (reclaimed after 120s idle, reconnected on
   │  demand when dropped, TOFU shared) → POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|
   │  upload (spec in body/headers, credentials never in the URL; uploads/downloads streamed via pipe) +

package/README.md

@@ -91,7 +91,7 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
   出现的问题——node-pty 在 Windows 上不接受 signal，而它的 `_deferNoArgs` 会把这个异常推迟到
   socket 回调里抛出，调用方的 try/catch 拦不住。
 
-## agent 工具（P1）
+## agent 工具
 
 插件向 agent 注入十六个工具（与 bash 工具同权，操作实时显示在用户终端里）：
 
@@ -103,7 +103,7 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
 | `tty_stats` | 读会话所在机器的实时指标（0.20.0）：CPU / 内存 / 磁盘 / TCP 连接数 / 网速 / 温度 / 在线时长。本地会话取宿主机；SSH 会话取那台远程主机（另开一段非 PTY 通道，不影响终端）。部署、压测前先看它 |
 | `tty_capture` | 读取近期输出（尾部 N 行，默认清洗 ANSI，`raw:true` 取原始流）；**`last:true` 只返回上一条已完成命令的输出 + 退出码**（shell 集成标记，见下节）；命令**在途**时（刚发送、完成标记未到）返回 `inProgress:true` 且不带旧结果——避免把上一条的输出当成这一条（0.19.0） |
 | `tty_screen` | 读取**当前可见屏幕**的渲染结果（xterm-headless 虚拟屏，纯文本）——能真正读懂 vim / htop / 菜单等 TUI 界面 |
-| `tty_expect` | 用正则**等待后续输出**中的就绪信号（dev server URL、构建完成等）；超时不抛错（`matched:false` + 尾部输出），命令提前结束也会带退出码早停；同一会话在途调用最多 5 个，累积窗口只保留尾部 64KB（0.19.0） |
+| `tty_expect` | 用正则等一个就绪信号（dev server URL、构建完成等）。**先回溯**还没被读过的输出（含「上一条命令」的完整输出，故命令瞬间跑完也不会白等），再等后续输出；命中即返回 `matched:true` + `matchedFrom`（`live` 本次等待期间新产生 / `last` 上一条命令的输出 / `buffered` 此前已到达的缓冲输出）。超时不抛错（`matched:false` + 尾部输出，且**不消耗未读区**——换个 pattern 还能回溯到同一段），命令提前结束也会带退出码早停；回显不算命中（靠 OSC 133 的 A..B 边界，无标记环境见下节）；同一会话在途调用最多 5 个，累积窗口只保留尾部 64KB（0.19.0；回溯匹配见 D72） |
 | `tty_send` | 向指定会话发送按键/文本（如 dev server 的 q 键、菜单选择） |
 | `sftp_list` | 列出 SSH 远程目录内容（名称/类型/大小/修改时间，目录在前）；`book` 为连接簿条目名，`path` 缺省为登录 home；默认最多 500 项（超限 `truncated:true`），`isSymlink` 区分软链与真目录（0.19.0） |
 | `sftp_read` | 读取远程**文本**文件（默认 ≤256KB 可调至 1MB，超出截断）；`offset` 可从指定字节分页（适合读日志尾部），非法 `maxBytes` 直接报错，二进制判定 = NUL + 非法 UTF-8 占比双判据（0.19.0） |
@@ -112,7 +112,7 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
 | `sftp_rename` | 重命名/移动远程文件或目录（`to` 与 `from` 不同目录即移动；不覆盖已存在的目标） |
 | `sftp_remove` | 删除远程文件/目录；目录默认 rmdir（非空明确报错），`recursive:true` 整树删除（不可恢复）；会拒绝 `/`、`~`、含 `.`/`..` 段的路径（不可恢复操作的前置护栏，0.19.0） |
 | `sftp_tree` | 递归列举远程目录结构（深度优先、目录优先；`maxDepth` 1~8 / `maxEntries` 1~2000 限流，超限 `truncated:true`；symlink 不跟随防环） |
-| `tunnel_list` | 列出端口转发隧道及其实时状态（活跃/连接中/错误/停止、规则、连接数） |
+| `tunnel_list` | 列出端口转发隧道及其实时状态（活跃/连接中/错误/停止、规则、连接数）；`fatal:true` = 人工介入级故障（本地监听失败 / 连接簿缺失），**不会自动重试**，修配置后重建 |
 
 典型 agent 流程（推荐）：`tty_open` 开一个会话（长驻进程用 `persistName` 要 tmux 持久化）
 → `tty_send` 启动命令 → `tty_expect` 等就绪标记 → `tty_capture{last:true}` 拿单条命令结果
@@ -144,6 +144,24 @@ spawn 时经既有的 `-c` 包装层按 shell 类型注入钩子（对用户透
   SSH 会话则上报远程路径）；
 - 其他 shell 静默关闭；配置 `shellIntegration: false` 可整体关掉（逃生门）。
 
+**回溯匹配与已读水位线（D72）**：`tty_expect` 会先回看**还没被读过**的输出（命令瞬间跑完时
+要等的标记早就在缓冲区里了），回看的起点抬到「未读区内最后一个 `B` 标记之后」——回显落在 `A`
+与 `B` 之间，所以回显里的字样不会被当成命中（这里刻意不做文本比对：折行 / ANSI / 多行粘贴
+都会把它打碎）。
+
+- **没有 `B` 标记的环境**（未开集成 / Windows 本地标签 / 远端未装集成）分不出回显，退化为
+  「从水位线起扫，可能匹配到回显本身」——这是已知限制；
+- **回看范围的取舍**：起点抬到「未读区内最后一个 `B` 标记之后」，代价是最后一条命令**开始
+  之前**的那段未读输出不在回看范围内。刻意选「宁可漏、不可误报」——把回显当成命中会让 AI
+  以为事件刚刚发生。要那段内容用 `tty_capture`。反过来的窄窗口也有一个：`tty_send` 之后、
+  新命令的 `B` 标记到达之前，未读区里仍然是上一条命令的输出，里面有要等的 pattern 就会立即
+  命中（AI 的下一次调用几乎总在新 `B` 之后，那种情况下这段已被新 `B` 切掉）；
+- **已读水位线**：`tty_capture` / `tty_expect` 返回的内容算「已读」，之后的 `tty_expect` 不再
+  回扫它们（要回看更早的内容用 `tty_capture`）。`tty_screen` 刻意**不**推进（屏幕是另一种
+  表示，不是文本流）；`tty_send` 只初始化不推进（刚发出去的命令输出还没被看见）；**超时也不
+  消耗未读区**（换一个 pattern 还能回溯到同一段）。用户自己开的标签在 agent 第一次触达时
+  才把水位线落在当下——那之前的历史输出不算「未读」。
+
 SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
 （user@host[:port]）识别，`tty_capture` / `tty_expect` / `tty_send` 用法与
 本地会话完全一致——远程机器上的 dev server 日志与按键交互照常可用。
@@ -220,7 +238,13 @@ SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
   dev server 暴露给远程/内网；
 - **宿主自持生命周期**：隧道与终端标签互相独立（各有各的 SSH 连接），面板
   关了隧道照跑；SSH 断线自动指数退避重连（1s→15s 封顶），remote 方向重连
-  后自动重新 forwardIn；连接簿改密码后重连自动用新凭证；
+  后自动重新 forwardIn；连接簿改密码后重连自动用新凭证。**例外**：本地监听失败
+  （端口被占等）/ 连接簿条目缺失是人工介入级故障——状态停在 `error` 且
+  `fatal:true`、**不会自动重试**，改配置（或恢复条目）后按新规格重建（见 DEFECTS D58）；
+- **多 profile 同跑要错开 localPort**：端口转发是**机器级**资源，而配置按 profile
+  各存一份（复制 profile 会连隧道一起拷走）。两个 profile 同时跑同一条隧道 → 后起的
+  那个 `EADDRINUSE`，状态停在 `error` 且 `fatal:true`（**不重试**，改配置后按新规格
+  重建）；报错文案会直接点明「可能是另一个 DSH profile 的宿主进程」并给出两条出路；
 - **状态徽标**：卡片展开期间 2s 轮询实时状态（活跃绿/连接中蓝/错误红/停止
   灰 + 最近错误）；「+」菜单的连接簿条目显示 `⇄N` 隧道徽标；agent 可用
   `tunnel_list` 工具查询状态；
@@ -313,6 +337,10 @@ subsystem，宿主半体 `src/sftp.ts`）：
 tmux server（专用 socket `dsh-tty`，与用户自己的 tmux 完全隔离），断线保活
 超时、甚至宿主重启后都能接回：
 
+> ⚠️ **socket 是全 profile 共用的**（`tmux -L dsh-tty`，不随 profile 区分）。多 profile
+> 同跑时：`tty_list` 的持久会话清单会**跨 profile** 出现；而「改 tmux 配置后生效」用的
+> `tmux -L dsh-tty kill-server` 会**一并杀掉另一个 profile 的持久会话**。
+
 - **入口（0.10.1 简化）**：设置卡片「会话持久化」选 `tmux` 即唯一开关——开启后
   **所有新开的标签默认持久化**：「+」菜单的「本地终端」、连接簿条目点击、
   SSH 连接对话框（「持久会话」默认勾选，单次连接可取消）。不再有单独的
@@ -399,7 +427,44 @@ tmux server（专用 socket `dsh-tty`，与用户自己的 tmux 完全隔离）
   失效。连接簿条目随 `agentForward` 保存，列表里显示 `· fwd`；
 - **`~/.ssh/config` 导入（0.4.0）**：设置卡片连接簿区「从 ~/.ssh/config
   导入」——解析 `HostName/User/Port/IdentityFile` 生成候选条目（跳过通配符
-  块与无 User 条目，`Include` 不展开），同名跳过，随「保存」写入；
+  块与无 User 条目，`Include` 不展开），同名跳过，随「保存」写入。
+  **每一种跳过都会当场说明**（本轮起）：依赖跳板机的块（`ProxyJump` / `ProxyCommand`）
+  **不导入并点名**——本版本不支持跳板机，导进来只会得到一条连不上、且只报通用超时的条目；
+  超过导入上限的条数与「非具体主机」的条数也各自报数。`ProxyJump none` /
+  `ProxyCommand none` 是显式直连，照常导入。
+  **`ProxyJump` 会解析成连接条目的跳板机（单跳）一起导入**：值可以是 `user@host:port`
+  （IPv6 写 `[::1]:22`），也可以是同一份 config 里的另一个具体 Host（按块名解析，块序任意）；
+  跳板机缺省**继承目标那一跳的凭据**，要不同的钥匙就在条目里填 `jump` 的 `keyPath`/`password`。
+  解析不出来的（别名缺失、别名自己又依赖跳板机）仍会跳过并点名。
+  **`ProxyCommand` 永不自动导入**（单独报数并说明为什么）：它等于让设置字段驱动本地任意
+  命令执行，所以只在**手动填写 + 打开开关**之后才会跑（见下一段）。
+  **对话框里也有「跳板机」一段**：一个 `[用户@]主机[:端口]` 输入框（与 OpenSSH 写法一致），
+  勾「使用独立凭据」才展开用户名 / 认证方式 / 私钥 / 口令；条目行显示「⇢ 经 X」，「试连」
+  会把跳板机那一跳单列出来；
+- **代理命令 / ProxyCommand（0.21.0，默认关）**：连接簿条目（或连接对话框）里可填一条
+  **本机命令**，它的 stdin/stdout 就是到目标的 SSH 传输——等价于 OpenSSH 的 `ProxyCommand`
+  （典型写法 `ssh -W %h:%p bastion`）。支持 `%h` 目标主机、`%p` 端口、`%r` 用户名、`%n` 主机、
+  `%%` 字面 `%`，其余 `%X` 原样保留；**代入值只允许字母数字与 `._@:[]-`，含 shell 特殊字符
+  直接拒绝执行**（不做「按平台各写一套转义」：命令最终交给 `sh -c` / `cmd /c`，两边规则不同）。
+  **闸门**：设置卡片「允许 ProxyCommand（本机执行命令）」**默认关**，它的**提权有两条通道**：
+  ① **启动环境变量** `DSH_TTY_ALLOW_PROXY_COMMAND=1`（最严档，进程启动时采样，只认继承来的
+  `process` 层——写项目 `.env` 或 `~/.dsh/env.yml` **不算**授权）；② **就地提权**（免重启）：
+  卡片上点那个开关 → 面板给出一条「在宿主终端执行」的命令 → 执行后十秒内解锁并替你打开开关。
+  HTTP / 界面**不能凭空打开**它（给 `true` 而无授权会被 400 拒绝并说清两条路），但**关掉**永远
+  可用（紧急刹车不能依赖重启）。授权是**持久**的（落在 `<DSH home>/dsh-kit/capability-grants.json`，
+  0600）：宿主重启后直接生效、不再确认，所以每次启动会打一行
+  `[dsh-tty] elevation: load capability=… via=file grantedAt=…`，卡片上也显示「已授权 · 时刻」并给
+  「撤销宿主授权」入口。**升级影响**：升级前靠界面打开的这个开关会变成关。为什么这么设计：
+  回环围栏与同源证明都拦不住跨站页面与页内脚本，而这一档是「配置里写一行就在本机跑命令」——
+  配置界面若能凭空提权，这道闸门等于没有（细节见
+  [architecture.md § 7](../../docs/architecture.md#7-一条请求经过什么)）。关着时携带代理命令的连接
+  **明确失败、不退回直连**（直连多半也连不上，还会把配置问题伪装成网络问题），「试连」在
+  阶段 0 就返回并点名这个开关。与跳板机同时填时按 OpenSSH 语义**跳板机优先**，并记一条 warn。
+  闸门只有一处（本插件 settings）：docker 容器面板读同一个开关——连接簿配一次、两处生效；
+  代价是代理命令是**本机**执行的，docker 目标也会用这条命令（详见
+  [docs/proxyjump-plan.md](../../docs/proxyjump-plan.md) §6.1 的闸门定案表）；
+  与跳板机一样，**它是另一条独立传输，收尾必须成对**（终端 / SFTP / 隧道 / 探针四条路都在
+  同一个收尾入口里 `dispose()`：关传输 + 杀进程组，子进程不会变成常驻孤儿）；
 - **凭据引用选择器（0.4.0，0.17 起与 env 插件解耦）**：SSH 对话框的密码/口令字段旁有筛选框 +
   限高列表，候选 = **凭据存储里已有的引用名**（宿主读 `.credentials.yaml` 的 `refs:` 键，
   **只回名字、绝不含值**）∪ **本机连接簿里已经在用的引用名**；点击即填 `env:NAME`，也可手输
@@ -500,6 +565,7 @@ tmux server（专用 socket `dsh-tty`，与用户自己的 tmux 完全隔离）
 | `persistence` | `off` | 会话持久化：`off` 会话随宿主生死（默认）；`tmux` 开启后**所有新开的标签默认由 tmux server 托管**、可跨宿主重启恢复（需本机/远程安装 tmux）；SSH 对话框可对单次连接取消 |
 | `endOnPageClose` | `false` | 页面（最后一个连接）断开且保活期结束时，是否连 tmux 持久会话一起结束。默认 `false` = 留存可恢复；`true` = 页面关了就不保活（保活期内刷新仍可无缝接回） |
 | `sftpLimits` | `{maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000}` | SFTP 传输限制（浏览器侧保护，均为 **0 = 不限**）：`maxDownloadMb` 单文件下载上限（超限中止并提示用双栏 `⇦`/终端 scp）、`maxUploadMb` 单文件上传上限、`maxUploadFiles` 一次批量/拖拽上传的文件数上限；大文件请走双栏 `⇨/⇦` 服务端直传（字节不经过浏览器，不占内存） |
+| `allowProxyCommand` | `false` | 允许连接簿条目里的**代理命令（ProxyCommand）在本机执行**。默认关：关着时携带代理命令的连接**明确失败**（不退回直连），`~/.ssh/config` 导入**永不**自动带入该字段。docker 容器面板读同一个开关（连接簿只有一处）。支持 `%h/%p/%r/%n/%%` 展开，代入值走白名单；命令的子进程不会残留（四条连接路径共用同一收尾）。**两条提权通道**：① 启动环境变量 `DSH_TTY_ALLOW_PROXY_COMMAND=1`（判定源是宿主的**启动环境快照**，只认继承来的 `process` 层：写项目 `.env` 或 `~/.dsh/env.yml` **不算**授权）；② **就地提权**（免重启）：设置卡片点那个开关 → 面板给出「在宿主终端执行」的命令 → 十秒内解锁。HTTP / 界面**不能凭空打开**它（给 `true` 而无授权 400 并说清两条路），但**关掉**永远可用；配置里的 `true` 不算授权。授权持久（`<DSH home>/dsh-kit/capability-grants.json`），重启后直接生效并在卡片上显示时刻与「撤销宿主授权」（见 [architecture.md § 7](../../docs/architecture.md#7-一条请求经过什么)） |
 | `statsEnabled` | true | 服务器状态条（0.17.0）：按标签可见性采集并推送 CPU / 内存 / 磁盘 / 在线时长 / TCP 连接数 / 网速 / CPU 温度；关闭即停表（远端 exec channel 一并关闭），保存即热生效 |
 
 ## 连接栏扩展点（客户端服务 `ttyConnbar`，0.13.0）
@@ -856,7 +922,11 @@ node scripts/preview.mjs --theme=light   # 浅色主题
   │  /api/dsh-tty/credential-refs（凭据存储里已知的引用名 —— 只要名字，见「凭据存储」）、
   │  /api/dsh-tty/env-vars（env 插件托管变量名）、/api/dsh-tty/known-hosts
   │  （TOFU 指纹预填充，src/known-hosts.ts 解析含 hashed 条目）、
-  │  /api/dsh-tty/shells（Shell 路径候选）——均 loopback 围栏
+  │  /api/dsh-tty/shells（Shell 路径候选）——均 loopback 围栏（加固档：127/8 全段 +
+  │  别名主机名的 DNS 确认 + 来源检查在 DNS 之前，实现只有一份在 @hyzyn/dsh-kit）；
+  │  **改状态的端点另需同源证明**（POST /probe、sftp 的 mkdir/rename/remove/upload、
+  │  local-fs 的 mkdir/rename/remove/transfer）；只读端点（含 sftp /list 与 /download）
+  │  不要求证明，裸 curl 也能读。POST /config 刻意豁免——它是插件被禁用后唯一的恢复入口
   ├─ SFTP（src/sftp.ts，0.7.0）：懒连接池（空闲 120s 回收、断开按需重连、
   │  TOFU 共用）→ POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|
   │  upload（spec 走体/头，凭证不进 URL；上传下载流式 pipe）+