@hyzyn/dsh-tty 0.21.0 → 0.22.0-rc.2

package/README.en.md

@@ -76,6 +76,12 @@ Both were reproduced on **Windows 11 ARM (24H2) + Node 22 ARM64**. The fix:
   TERM / COLORTERM are meaningless for ConPTY and are no longer injected;
 - **“Run one command” tabs** (docker exec, command tabs opened by the agent) use `cmd /c` or
   `PowerShell -Command`;
+- **Input line-ending normalisation (D74, reported on real hardware 2026-09-27)**: conhost treats Enter as
+  **CR**, so a bare LF only moves the cursor down and **does not submit the command line** — `tty_send`
+  writing `echo X\n` as the tool description says leaves the command sitting on the input line (no output,
+  no new prompt, looking like “it was sent but never ran”). For **local sessions on win32** the plugin now
+  turns a bare LF into CRLF (an existing CRLF is not doubled; non-Windows and SSH sessions pass through
+  untouched), so the documented `\n` path just works;
 - **Three things are not supported** (the host turns them off and the settings card explains why):
   - **Shell integration (OSC 133/7)**: injection relies on POSIX rc stubs plus the `-c` wrapper, neither of
     which exists for cmd / PowerShell, so it is permanently off — **local** tabs therefore lose cwd tracking
@@ -92,7 +98,9 @@ Both were reproduced on **Windows 11 ARM (24H2) + Node 22 ARM64**. The fix:
   rebuild), plus `[dsh-tty] mounted (shell=C:\WINDOWS\system32\cmd.exe)`.
   x64 Windows is covered by the CI matrix (build / typecheck / test, see Development).
 - **End-to-end coverage (0.19.0)**: `scripts/windows-smoke.mjs` drives a real `cmd.exe` through
-  spawn → input echo → kill → respawn on the CI windows-latest runner. It caught and now pins a
+  spawn → input echo → kill → respawn on the CI windows-latest runner, plus two links that only hold on
+  a real machine (W6: after normalisation a bare LF really does submit in conhost, D74; W7: a `command`
+  session that exits turns into read-only retention and `tty_capture` still reads its pre-exit output, D77). It caught and now pins a
   Windows-only failure class: force-killing a local PTY crashed the host — node-pty rejects signals
   on Windows, and its `_deferNoArgs` re-throws that error from a socket callback, where the caller’s
   try/catch cannot see it.
@@ -103,14 +111,14 @@ The plugin injects sixteen tools into the agent (with the same power as the bash
 
 | Tool | Purpose |
 | --- | --- |
-| `tty_list` | List active terminal sessions (sid / kind (`local\|ssh`) / target / pid / **cwd tracked live as you `cd`** / activity time; tmux persistent sessions carry a `persist` marker; sessions the agent opened carry `owner: 'agent'`) |
-| `tty_open` | **Open a terminal session yourself** (0.20.0): a local shell, or a long-running command via `command` (dev server / watch), with optional tmux persistence via `persistName`. The session **shows up in the user’s terminal panel** as an ordinary tab the user can see and take over — never a hidden session |
-| `tty_close` | Close a session opened by `tty_open` (0.20.0). **Only the agent’s own sessions may be closed**: a tab the user opened is refused, so the agent never ends a terminal the user is working in |
+| `tty_list` | List terminal sessions (sid / kind (`local\|ssh`) / target / pid / **cwd tracked live as you `cd`** / activity time; tmux persistent sessions carry a `persist` marker; sessions the agent opened carry `owner: 'agent'`). **Includes sessions whose process has exited but which are still inside their read-only retention window** (`exited:true` + exit code/signal, see below) |
+| `tty_open` | **Open a terminal session yourself** (0.20.0): a local shell, or a command via `command` (dev server / watch; it runs as **a whole piece of shell code** — `cd x && cmd`, `a; b`, even a multi-line script, and it is *not* subject to the “single line ≤2000” client rule below — D78), with optional tmux persistence via `persistName`. The session **shows up in the user’s terminal panel** as an ordinary tab the user can see and take over — never a hidden session |
+| `tty_close` | Close a session opened by `tty_open` (0.20.0). **Only the agent’s own sessions may be closed**: a tab the user opened is refused, so the agent never ends a terminal the user is working in. It also works on an **exited session that is still in read-only retention** — that is its release entry point (by default it is retained **until explicitly closed**, never on a timer) |
 | `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_send` | Send keys/text to a given session (such as `q` to a dev server, or a menu selection) |
+| `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 of the command just sent never counts as a hit** (via the OSC 133 A..B boundary, or via the send record where there are no markers — see the next section; when only the echo ever matched, the timeout result carries `echoOnly:true`); 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; echo exclusion, see D75) |
+| `tty_send` | Send keys/text to a given session (such as `q` to a dev server, or a menu selection). End a command with `\n`: on a **local Windows session** a trailing bare LF is normalised to CRLF (D74, see the “Windows hosts” section); non-Windows and SSH sessions pass through untouched. On an **exited** session it fails explicitly (such sessions are read-only) |
 | `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) |
 | `sftp_write` | Write a remote text file (overwrite by default, `append:true` appends; ≤1MB per call) |
@@ -134,6 +142,39 @@ the orphan collector** (which only reaps disconnected *user* sessions); it ends
 `tty_close` or the user closing the tab. Conversely the agent **cannot close a user-opened tab**
 (`tty_close` refuses explicitly).
 
+### Read-only retention after the process exits (D77)
+
+A process exit **no longer means the session is gone** — the session turns into a **read-only retained** one,
+**kept until it is explicitly closed** by default (`EXITED_RETAIN_MS = ∞`; a host/plugin restart clears them).
+While retained:
+
+- **Reads keep working**: `tty_capture` (tail or `last`, including the final batch of output printed
+  before exit), `tty_screen` (the screen as of the exit) and `tty_list` (entry carries `exited:true` +
+  `exitCode`/`signal`) all still answer, and their results carry an `exited` marker;
+  `tty_expect` no longer burns its timeout — it settles against the existing output and returns
+  `exited:true`;
+- **Writes are refused**: `tty_send` reports an explicit error (the process is gone; a write would
+  vanish into a dead PTY), and `tty_resize` / `tty_stats` no longer apply to it (stats honestly returns
+  `available:false`);
+- **No re-attaching a terminal**: `attach` is explicitly refused (there is no live PTY; the panel does
+  not create a tab for it either) — read the output with `tty_capture`;
+- **Who releases it**: the agent’s `tty_close` (its own sessions only), the user closing that tab in the
+  panel, or a host/plugin restart (retention lives in memory). The concurrency limit counts **live
+  sessions only** (retained ones do not consume a slot), and at most `MAX_EXITED_SESSIONS` (8) retained
+  sessions are kept — the oldest is evicted beyond that (each eviction logs the sid it drops). So the
+  rule is “the last 16 exited sessions stay readable”, which is the only bound on memory and handles
+  (16 of them is on the order of ~20MB).
+
+  Why **not** a timer: memory and handles are not actually time-driven (see above), while a deadline is a
+  second surprise for whoever reads the output — the gap between “the command finished” and “the next
+  round reads the result” spans people walking away and queued model turns. An output that vanishes on
+  schedule is harder to reason about than one you have to close. If you do want a time bound (or no
+  retention at all), set `EXITED_RETAIN_MS` to a millisecond value / 0 — the `reapExited` path is still
+  wired into the reaper, and `tty_list`’s `retainMs` field only appears when a timer is in play.
+
+This is why “`tty_open` a command that finishes and read the result afterwards” now just works — no
+`sh` wrapper needed (the request in issue #4).
+
 ### Shell integration (OSC 133/7, 0.4.0)
 
 At spawn time hooks are injected through the existing `-c` wrapper layer according to the shell type (transparent to the user, no rc changes):
@@ -152,6 +193,37 @@ 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) have no boundary to cut at, so since D75 the echo is excluded by a different test: the command
+  lines that the most recent `tty_send` submitted are stripped out of the candidate text and the pattern
+  is retried — only “no longer matches after stripping” counts as a pure echo. That removes the false
+  positive where the command never ran yet the wait reported `matched:true`, while the same text really
+  printed later still matches. When the wait times out and the pattern only ever matched the echo, the
+  result carries `echoOnly:true` and the message says plainly that the command was probably never
+  executed. **Boundary**: only lines written by `tty_send` are known (typing in the panel is not
+  simulated as line editing), and stripping is disabled while a command is running (in a full-screen TUI
+  redraw, the typed text appearing on screen is real output);
+- **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.
@@ -460,7 +532,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
@@ -633,13 +720,23 @@ ctx.inject(['ttyTerminal'], (c) => {
 
 - Command tabs are **not persisted in tmux** (commands are short-lived and attaching is meaningless) and do
   not go through a login shell; the SSH side uses `conn.exec(command, {pty})`, and the local side uses
-  `sh -c 'export TERM=…; exec <command>'`.
+  `sh -c 'export TERM=…; exec <the same shell> -c <command>'` — the outer `exec` makes the process
+  the command itself (faithful exit code and signal), and the **inner `-c`** is what makes the whole
+  string run as shell code: `cd x && cmd`, `a; b`, `for …; do …; done` all run to completion
+  (D78: the old form appended the command straight after `exec`, so only the first one ran and a
+  builtin such as `cd` ended the wrapper shell outright).
 - **Command tabs reopen automatically**: after a host restart / reconnect the sid is gone, and the client
   re-runs the command from the original spec for tabs with `spawnSpec.command` (ordinary non-persistent tabs
   keep the old “click to retry” behavior). After a page refresh they are restored by the original command too.
 - The command comes from a **host-side plugin** (not from remote user input), so its trust level equals the
   plugin’s own; tty only validates the shape: non-empty, single line, length ≤2000 (a newline would break the
   local `-c` wrapper layer).
+- **“Single line, ≤2000” is this channel’s rule, not `tty_open`’s** (raised in the 2026-09-27 review): the
+  `command` in a `spawn` / `ssh` frame gets spliced into the `-c` wrapper, so `sanitizeCommand` rejects
+  newlines and NUL. The agent’s `tty_open.command` takes a different path — the command is wrapped **whole**
+  in `shSingleQuote` and handed to the inner `-c` (see above), so it **may contain newlines** (multi-line
+  scripts do run) and is bounded only by the tool parameter’s string type. Do not read this section’s limit
+  as a `tty_open` restriction.
 - The service name `ttyTerminal` is likewise not declared on the `Context` type surface; inject it as an
   optional dependency; when tty is not installed or is older than 0.14.0 it never fires (dsh-docker degrades
   to “copy command”).
@@ -777,7 +874,7 @@ ctx.inject(['ttyPanel'], (c) => {
 | C→S | `{t:'attach', sid}` | Reattach an orphan session (inside the keep-alive window): after `ready(reattached:true)` a single `data` frame replays the output buffer |
 | C→S | `{t:'statsOn' \| 'statsOff', sid}` | Subscribe/unsubscribe that session’s server status bar (0.17.0): driven by tab visibility, and the host collects only while a subscription exists (lazy start + unsubscribing stops the meter and closes the remote channel) |
 | S→C | `{t:'ready', sid, pid, kind, target?, persist?, reattached?}` | Session ready; `kind:'local'` carries a pid, while `kind:'ssh'` has pid=null and target=user@host[:port]; attach reuses this frame with `reattached:true`; `persist:true` means a tmux persistent session (0.10.0) |
-| S→C | `{t:'data', sid, d}` | Terminal output (utf8 text, StringDecoder covers multi-byte sequences split across frames); **coalesced into frames over a 12ms window / 64KB threshold** (0.4.1), with a forced flush before exit/kill to guarantee frame order |
+| S→C | `{t:'data', sid, d}` | Terminal output (utf8 text, StringDecoder covers multi-byte sequences split across frames); **coalesced into frames over a 12ms window / 64KB threshold** (0.4.1), with a forced flush before exit/kill to guarantee frame order — **the last batch before exit is always sent** (D76: it used to be swallowed whole by the exit path’s own `closed` guard, so a process that printed and exited immediately was permanently missing its final lines) |
 | S→C | `{t:'stats', sid, stats}` | Resource metric frame (0.17.0): `{cpuPct, cores, memUsed, memTotal, memPct, diskUsed, diskTotal, diskPct, uptimeSec, tcpConns, rxRate, txRate, tempC?}`; missing fields are omitted (best-effort, the frontend shows “n/a”), byte fields are bytes and rates are B/s |
 | S→C | `{t:'exit', sid, code, signal}` | The PTY exit fact (exactly once; after attach moves to a new connection it is still delivered over the current connection) |
 | S→C | `{t:'error', sid?, m}` | Error |
@@ -991,7 +1088,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

@@ -75,6 +75,10 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
   没有意义，也不再注入；
 - **「跑一条命令」的标签**（docker exec、agent 起的命令标签）走 `cmd /c` 或
   `PowerShell -Command`；
+- **输入行尾归一化（D74，2026-09-27 真机报告）**：conhost 的 Enter 是 **CR**，裸 LF 只把光标
+  下移一格、**不提交命令行**——`tty_send` 按工具描述发 `echo X\n` 时命令停在输入行上（没有输出、
+  没有新提示符，看起来像「发出去了但没执行」）。**win32 的本地会话**上插件现在把裸 LF 补成 CRLF
+  （已经是 CRLF 的不重复补；非 Windows 与 SSH 会话原样透传），所以照描述写 `\n` 这条主路径直接可用；
 - **不支持的三项（宿主侧自动关掉，设置卡片里写明原因）**：
   - **shell 集成（OSC 133/7）**：注入靠 POSIX rc 桩 + `-c` 包装层，cmd / PowerShell 上都不成立，
     因此恒关 —— **本地标签**的 `tty_list.cwd` 跟随 `cd`、`tty_capture{last}` 与 `tty_expect`
@@ -87,7 +91,9 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
   内容标记一致；不写死字节数——每次重建都会变）、`[dsh-tty] mounted (shell=C:\WINDOWS\system32\cmd.exe)`；x64 Windows 由 CI
   的三平台矩阵覆盖（build / typecheck / test，见「开发」）。
 - **端到端覆盖（0.19.0）**：`scripts/windows-smoke.mjs` 在 CI 的 windows-latest 上跑真实 `cmd.exe`
-  的 spawn → 输入回显 → kill → 重开。它抓出并钉住了「强杀本地 PTY 会崩宿主」这类只在 Windows
+  的 spawn → 输入回显 → kill → 重开，外加两条只在真机上成立的链路（W6：`tty_send` 的裸 LF 经归一化
+  后 conhost 真的执行了命令，D74；W7：`command` 型会话跑完退出后转只读保留、`tty_capture` 仍读得到
+  退出前的输出，D77）。它抓出并钉住了「强杀本地 PTY 会崩宿主」这类只在 Windows
   出现的问题——node-pty 在 Windows 上不接受 signal，而它的 `_deferNoArgs` 会把这个异常推迟到
   socket 回调里抛出，调用方的 try/catch 拦不住。
 
@@ -97,14 +103,14 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
 
 | 工具 | 作用 |
 | --- | --- |
-| `tty_list` | 列出活跃终端会话（sid / kind（local\|ssh）/ target / pid / **cwd 实时跟随 cd** / 活动时间；tmux 持久会话带 `persist` 标记；agent 自己开的带 `owner: 'agent'`） |
-| `tty_open` | **自己开一个终端会话**（0.20.0）：本地 shell，或 `command` 直接跑一条长驻命令（dev server / watch），`persistName` 可要 tmux 持久化。**开出来的会话出现在用户的终端面板里**（普通标签、用户可见可接管），不做隐形会话 |
-| `tty_close` | 关掉一个由 `tty_open` 开的会话（0.20.0）。**只允许关 agent 自己开的**：用户在面板里开的标签会被拒绝——agent 不越权结束用户正在用的终端 |
+| `tty_list` | 列出终端会话（sid / kind（local\|ssh）/ target / pid / **cwd 实时跟随 cd** / 活动时间；tmux 持久会话带 `persist` 标记；agent 自己开的带 `owner: 'agent'`）。**含进程已退出但仍在只读保留期内的会话**（`exited:true` + 退出码/信号，见下节） |
+| `tty_open` | **自己开一个终端会话**（0.20.0）：本地 shell，或 `command` 直接跑一条命令（dev server / watch；**按整段 shell 代码执行**——`cd x && cmd`、`a; b`、多行脚本都可以，且不受下面「命令标签单行 ≤2000」那条客户端约束，D78），`persistName` 可要 tmux 持久化。**开出来的会话出现在用户的终端面板里**（普通标签、用户可见可接管），不做隐形会话 |
+| `tty_close` | 关掉一个由 `tty_open` 开的会话（0.20.0）。**只允许关 agent 自己开的**：用户在面板里开的标签会被拒绝——agent 不越权结束用户正在用的终端。对**已退出但仍只读保留着**的会话同样可用——那是它的释放入口（默认**保留到显式关闭**，不按时间释放） |
 | `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_send` | 向指定会话发送按键/文本（如 dev server 的 q 键、菜单选择） |
+| `tty_expect` | 用正则等一个就绪信号（dev server URL、构建完成等）。**先回溯**还没被读过的输出（含「上一条命令」的完整输出，故命令瞬间跑完也不会白等），再等后续输出；命中即返回 `matched:true` + `matchedFrom`（`live` 本次等待期间新产生 / `last` 上一条命令的输出 / `buffered` 此前已到达的缓冲输出）。超时不抛错（`matched:false` + 尾部输出，且**不消耗未读区**——换个 pattern 还能回溯到同一段），命令提前结束也会带退出码早停；**刚发进去的命令回显不算命中**（靠 OSC 133 的 A..B 边界，无标记环境靠发送记录剔除，见下节；只命中回显时超时结果带 `echoOnly:true`）；同一会话在途调用最多 5 个，累积窗口只保留尾部 64KB（0.19.0；回溯匹配见 D72，回显剔除见 D75） |
+| `tty_send` | 向指定会话发送按键/文本（如 dev server 的 q 键、菜单选择）。命令以 `\n` 结尾即可：**Windows 本地会话**上行尾裸 LF 会被归一成 CRLF（D74，见「Windows 宿主」一节），非 Windows 与 SSH 会话原样透传。对**已退出**的会话会明确报错（那种会话只能读） |
 | `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） |
 | `sftp_write` | 写远程文本文件（默认覆盖，`append:true` 追加；单次 ≤1MB） |
@@ -125,6 +131,33 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
 （回收器只收「断连的用户会话」），关闭入口是 agent 的 `tty_close` 或用户在面板里关标签；
 反过来说，agent 也**关不掉用户开的标签**（`tty_close` 会明确拒绝）。
 
+### 进程退出后的「只读保留」（D77）
+
+会话的进程退出**不再等于会话消失**——它转成**只读保留态**，
+**默认保留到显式关闭**（`EXITED_RETAIN_MS = ∞`；宿主 / 插件重启即清空），期间：
+
+- **读得到**：`tty_capture`（尾部/`last`，含退出前的最后一批输出）、`tty_screen`（退出那一刻
+  的屏）、`tty_list`（条目带 `exited:true` + `exitCode`/`signal`）都照常可用，
+  结果里也带 `exited` 标记；`tty_expect` 不再空等——它按现存输出立刻结算并带 `exited:true`；
+- **写不进去**：`tty_send` 明确报错（进程已经没了，写进去只会在死 PTY 上静默消失），
+  `tty_resize` / `tty_stats` 同样不再作用于它（stats 如实回 `available:false`）；
+- **不再接回终端**：`attach` 会被明确拒绝（没有活着的 PTY；面板也不会为它建标签），
+  输出用 `tty_capture` 读；
+- **谁释放它**：agent 的 `tty_close`（仅限自己开的）、用户在面板里关那个标签、
+  或宿主 / 插件重启（保留是内存态）。并发上限**只数活着的会话**（保留态不占名额）；
+  保留态本身最多留 `MAX_EXITED_SESSIONS`（16）条，超出按最旧淘汰（淘汰时
+  `logger.warn` 记下被挤掉的 sid）——也就是「最近的 16 条退出会话一直可读」，
+  这是内存与句柄的唯一上界（16 条约 ~20MB 量级）。
+
+  为什么**不用时间**淘汰：内存与句柄本来就不由时间决定（见上一句），而时间上界对
+  使用者是第二重惊喜——「命令跑完 → 下一轮读结果」之间隔着人离开、模型排队，多久
+  都有可能，一个到期就消失的输出比「要主动关掉」更难理解。想要时间上界（或干脆
+  不保留）把 `EXITED_RETAIN_MS` 改成毫秒数 / 0 即可：`reapExited` 那条通路还在，
+  回收器每轮都会调它；`tty_list` 的 `retainMs` 字段也只在按时间释放时才出现。
+
+这就是「`tty_open` 跑一条会结束的命令、回头再取结果」能直接用的原因——不需要套一层
+`sh`（issue #4 的诉求）。
+
 ### shell 集成（OSC 133/7，0.4.0）
 
 spawn 时经既有的 `-c` 包装层按 shell 类型注入钩子（对用户透明，不改 rc）：
@@ -144,6 +177,29 @@ spawn 时经既有的 `-c` 包装层按 shell 类型注入钩子（对用户透
   SSH 会话则上报远程路径）；
 - 其他 shell 静默关闭；配置 `shellIntegration: false` 可整体关掉（逃生门）。
 
+**回溯匹配与已读水位线（D72）**：`tty_expect` 会先回看**还没被读过**的输出（命令瞬间跑完时
+要等的标记早就在缓冲区里了），回看的起点抬到「未读区内最后一个 `B` 标记之后」——回显落在 `A`
+与 `B` 之间，所以回显里的字样不会被当成命中（这里刻意不做文本比对：折行 / ANSI / 多行粘贴
+都会把它打碎）。
+
+- **没有 `B` 标记的环境**（未开集成 / Windows 本地标签 / 远端未装集成）没有边界可切，D75 起
+  改用另一条判据剔除回显：把**最近 `tty_send` 提交过的命令行**从候选文本里削掉再试一次，
+  只有「削掉后不再命中」才算纯回显——这样「命令没执行、等待却自称 matched」这条假阳性没了，
+  而回显之后真的跑出来的同一段文本照旧命中。等满超时且 pattern 只命中过回显时，结果带
+  `echoOnly:true`，文案会直说「命令大概率没有被执行」。**边界**：只认 `tty_send` 写进去的行
+  （用户在面板里逐键敲的不做行编辑模拟），且命令正在跑（TUI 全屏重画里出现输入文本是真实
+  输出）时不启用剔除；
+- **回看范围的取舍**：起点抬到「未读区内最后一个 `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 日志与按键交互照常可用。
@@ -409,7 +465,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`，也可手输
@@ -510,6 +603,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）
@@ -575,12 +669,21 @@ ctx.inject(['ttyTerminal'], (c) => {
 ```
 
 - 命令标签**不做 tmux 持久化**（命令短命，attach 无意义），也不走登录 shell；
-  SSH 侧用 `conn.exec(command, {pty})`，本地侧用 `sh -c 'export TERM=…; exec <command>'`。
+  SSH 侧用 `conn.exec(command, {pty})`，本地侧用
+  `sh -c 'export TERM=…; exec <同一个 shell> -c <command>'`——外层 `exec` 让进程就是命令本身
+  （退出码与信号忠实），**内层 `-c` 才保证整段命令被当 shell 代码执行**：`cd x && cmd`、
+  `a; b`、`for …; do …; done` 都完整跑（D78：旧写法把命令直接缀在 `exec` 后面，只跑第一条，
+  内建命令还会直接结束外层 shell）。
 - **命令标签会自动重开**：宿主重启 / 断线重连后 sid 已失效，客户端对
   `spawnSpec.command` 的标签按原规格重新执行命令（普通非持久标签维持「点击重试」
   的旧行为）。页面刷新后同样按原命令恢复。
 - 命令来自**宿主侧插件**（不是远程用户输入），信任级与插件本身相同；tty 只校验
   形状：非空、单行、长度 ≤2000（换行会破坏本地 `-c` 包装层）。
+- **「单行 ≤2000」是这条通道的约束，不是 `tty_open` 的**（2026-09-27 复核指出）：
+  `spawn` / `ssh` 帧的 `command` 要拼进 `-c` 包装层，所以由 `sanitizeCommand` 拒绝
+  换行与 NUL；而 agent 的 `tty_open.command` 走另一条路——命令**整段**用
+  `shSingleQuote` 包住交给内层 `-c`（见上一条），**可以含换行**（多行脚本实测可跑），
+  只受工具参数的字符串约束。两条通道的入参规则不同，别把这里当 `tty_open` 的限制。
 - 服务名 `ttyTerminal` 同样未声明在 `Context` 类型面上，按可选依赖注入；tty 未安装
   或版本 < 0.14.0 时不会触发（dsh-docker 会退化为「复制命令」）。
 
@@ -706,7 +809,7 @@ ctx.inject(['ttyPanel'], (c) => {
 | C→S | `{t:'attach', sid}` | 重连孤儿会话（保活窗口内）：`ready(reattached:true)` 后紧跟一帧 `data` 回放输出缓冲 |
 | C→S | `{t:'statsOn' \| 'statsOff', sid}` | 订阅/退订该会话的服务器状态条（0.17.0）：按标签可见性驱动，宿主只在有订阅时采集（懒启动 + 退订即停表并关远端 channel） |
 | S→C | `{t:'ready', sid, pid, kind, target?, persist?, reattached?}` | 会话就绪；`kind:'local'` 带 pid，`kind:'ssh'` 时 pid=null、target=user@host[:port]；attach 复用此帧并带 `reattached:true`；`persist:true` 表示 tmux 持久会话（0.10.0） |
-| S→C | `{t:'data', sid, d}` | 终端输出（utf8 文本，StringDecoder 兜跨帧多字节序列）；**12ms 窗口/64KB 阈值合并成帧**（0.4.1），exit/kill 前强制冲刷保证帧序 |
+| S→C | `{t:'data', sid, d}` | 终端输出（utf8 文本，StringDecoder 兜跨帧多字节序列）；**12ms 窗口/64KB 阈值合并成帧**（0.4.1），exit/kill 前强制冲刷保证帧序——**退出前最后一批一定发出**（D76：这一批曾被终局路径自己的 `closed` 守卫整批吞掉，于「打印完就退出」的进程上表现为面板永远少最后几行） |
 | S→C | `{t:'stats', sid, stats}` | 资源指标帧（0.17.0）：`{cpuPct, cores, memUsed, memTotal, memPct, diskUsed, diskTotal, diskPct, uptimeSec, tcpConns, rxRate, txRate, tempC?}`；缺失字段即省略（best-effort，前端显示「无」），字节类为 bytes、速率为 B/s |
 | S→C | `{t:'exit', sid, code, signal}` | PTY 退出事实（恰好一次；attach 换连接后仍随当前连接送达） |
 | S→C | `{t:'error', sid?, m}` | 错误 |
@@ -866,7 +969,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）+