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

package/lib/index.js

@@ -12,12 +12,13 @@ import WebSocket, { WebSocketServer } from 'ws';
 // found），必须默认导入后取 Terminal；类型用 InstanceType 别名保持同名可用
 import xtermHeadless from '@xterm/headless';
 const HeadlessTerminal = xtermHeadless.Terminal;
-import { definePlugin, dshHome as resolveDshHome, plainConfig, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
+import { definePlugin, dshHome as resolveDshHome, hasSameOriginProof, isLoopbackRequestStrict, plainConfig, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { spawnSsh, sshTarget, expandHome, setCredentialResolver } from './ssh.js';
+import { sanitizeJumpSpec, sanitizeProxyCommand, spawnSsh, sshTarget, expandHome, setCredentialResolver, setProxyCommandPolicy, validateJumpSpec, validateProxyCommand } from './ssh.js';
+import { sharedGrantStore, auditLoadedGrants, bindCapabilitySources, capabilityDeniedMessage, capabilityGrantAt, capabilityGrantVia, capabilityGranted, capabilityPaths, createElevationManager, } from '@hyzyn/dsh-kit';
 import { probeSsh } from './probe.js';
 import { buildCommandSpawn, buildShellSpawn, defaultShellPath } from './shell-integration.js';
-import { parseSshConfig } from './ssh-config.js';
+import { parseSshConfigDetailed } from './ssh-config.js';
 import { parseKnownHostsDetailed } from './known-hosts.js';
 import { TunnelManager } from './tunnels.js';
 import { SftpManager } from './sftp.js';
@@ -25,6 +26,22 @@ import { buildTmuxSpawnPlan, ensureTmuxAssets, killTmuxSession, listTmuxSessions
 import { buildRemoteStatsCommand, buildWindowsStatsCommand, hasStatsData, localStatsSampler, parseStatsLine } from './stats.js';
 /** SFTP 传输限制默认值。 */
 const DEFAULT_SFTP_LIMITS = { maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000 };
+/**
+ * 跳板机（ProxyJump 单跳）的 settings schema。
+ *
+ * 刻意**不给 `auth` / `keyPath` / `passphrase` / `password` / `username` 默认值**：
+ * 缺省的含义是「继承目标那一跳的凭据」，一旦给默认值（如 auth 默认 agent）就会把
+ * 「继承」变成「显式 agent」，用户配了密码的跳板机就会认证失败。
+ */
+const SSH_JUMP_SCHEMA = z.object({
+    host: z.string(),
+    port: z.natural().max(65535).default(22),
+    username: z.string().default(''),
+    auth: z.union([z.const('agent'), z.const('key'), z.const('password')]),
+    keyPath: z.string().default(''),
+    passphrase: z.string().default(''),
+    password: z.string().default(''),
+});
 const SSH_HOST_SCHEMA = z.object({
     name: z.string(),
     host: z.string(),
@@ -35,6 +52,13 @@ const SSH_HOST_SCHEMA = z.object({
     passphrase: z.string().default(''),
     password: z.string().default(''),
     agentForward: z.boolean().default(false),
+    /** 经跳板机连接（ProxyJump 单跳）；缺省 = 直连。 */
+    jump: SSH_JUMP_SCHEMA,
+    /**
+     * 代理命令（ProxyCommand）：本机执行、stdio 当 SSH 传输。**需要 allowProxyCommand 才生效**。
+     * `~/.ssh/config` 导入永不自动带入（那一档信任级要用户自己开开关并手填）。
+     */
+    proxyCommand: z.string().default(''),
     /** 该条目的 SSH 标签默认以 tmux 持久会话打开（仅 persistence=tmux 时生效）。 */
     persist: z.boolean().default(false),
 });
@@ -85,12 +109,29 @@ export const Config = z.object({
         maxUploadMb: z.natural().max(1024 * 1024).default(2048),
         maxUploadFiles: z.natural().max(100000).default(1000),
     }).default({ maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000 }).volatile(),
+    /**
+     * 允许 ProxyCommand（本机命令执行）：**默认 false**。
+     *
+     * 这是本插件唯一「由设置字段驱动本机任意命令执行」的开关，与跳板机（只连一跳 TCP）不同档；
+     * 关着时携带 proxyCommand 的连接**明确失败**（不退回直连），导入也永不自动带入该字段。
+     */
+    allowProxyCommand: z.boolean().default(false).volatile(),
     persistSessions: z.array(z.object({ tmuxName: z.string() })).default([]).volatile(),
 });
 /* ------------------------------------------------------------------ *
  * 常量
  * ------------------------------------------------------------------ */
 const WS_PATH = '/api/dsh-tty/ws';
+/**
+ * 代理命令这条能力的宿主侧授权（见 kit 的 capability.js 与 docs/architecture.md）。
+ *
+ * 两条提权通道（见 kit 的 capability.ts）：
+ *   ① 启动环境变量（最严档，判定源是宿主的启动环境快照）；
+ *   ② 就地提权（免重启）：卡片上点开关 → 在宿主文件系统上落地一个随机名确认文件。
+ * HTTP 侧**不能凭空打开**它——回环围栏与同源证明都拦不住跨站页面与页内脚本，配置路由若能
+ * 凭空提权，这道闸门等于没有；而「关掉」永远可用（紧急刹车不依赖重启）。
+ */
+const CAP_PROXY_COMMAND = { env: 'DSH_TTY_ALLOW_PROXY_COMMAND', label: '代理命令（ProxyCommand）' };
 const DEFAULT_MAX_SESSIONS = 4;
 /** 断线保活默认秒数（reconnectGraceSec；0 = 旧行为，断开立即结束会话）。 */
 const DEFAULT_RECONNECT_GRACE_SEC = 120;
@@ -134,7 +175,7 @@ const TERM_RE = /^[A-Za-z0-9_.+-]+$/;
 const REAPER_INTERVAL_MS = 10_000;
 /** 服务器状态条的采集/推送间隔（mvp 固定 1s，不做配置项）。 */
 const STATS_INTERVAL_MS = 1000;
-const TTY_GUIDANCE = '本机已安装 dsh-tty 插件（终端面板）：Web GUI 侧边栏的「终端」入口可打开交互终端（xterm.js + PTY），可运行任意命令与 TUI 程序（vim/htop 等），支持多标签页与断线自动重连（刷新页面/网络抖动后会话保活并恢复现场）；新标签默认在当前会话工作目录打开。标签栏「+」菜单还能开 SSH 标签页（ssh2 原生连接，连接簿在设置卡片维护，支持 agent forwarding 与主机指纹 TOFU 钉扎），像本地终端一样操作远程主机。设置卡片开启「会话持久化（tmux）」后，新开的本地/SSH 标签默认由 tmux server 托管（宿主重启/断线超时后重开即恢复现场），长任务建议在持久化开启时运行。长驻进程（dev server、watch、交互式程序）用 tty_open 开一个会话跑（或引导用户到终端面板里运行），不要在 bash 工具里挂起等待；用户提到「开个终端 / 在终端里跑 / SSH 到某台机器」时引导其打开该面板。agent 侧配套工具：tty_list 列出活跃终端会话（含 SSH 的 target 与实时 cwd），tty_capture 读取近期输出（默认清洗 ANSI；last:true 拿「上一条命令」的输出+退出码），tty_screen 读取当前可见屏幕（可读懂 vim/htop 等 TUI），tty_expect 用正则等待输出中的就绪信号（如 dev server URL、构建完成），tty_send 发送按键，tunnel_list 列出端口转发隧道状态——操作会实时显示在用户终端里。SFTP 文件传输：面板内可对 SSH 连接簿条目（或 SSH 连接对话框当前填写的信息）打开文件浏览（上传/下载/建目录/重命名/删除），传输期间进度条右侧 ✕ 可取消（半截文件自动清理）；agent 配套 sftp_list 列远程目录、sftp_tree 递归看目录结构、sftp_read 读远程文本文件（≤1MB）、sftp_write 写远程文本文件（≤1MB，可追加）、sftp_mkdir 建目录（parents 可逐级补齐）、sftp_rename 重命名/移动、sftp_remove 删除（目录需 recursive），book 参数为连接簿条目名。端口转发：连接簿条目可配本地/远程隧道（如把远程数据库映射到本地端口），宿主自动保活重连，用户提到「转发端口 / 访问远程库」时引导其到终端面板设置卡片配置。推荐流程：tty_send 启动长任务 → tty_expect 等就绪标记 → tty_capture{last:true} 拿结果。';
+const TTY_GUIDANCE = '本机已安装 dsh-tty 插件（终端面板）：Web GUI 侧边栏的「终端」入口可打开交互终端（xterm.js + PTY），可运行任意命令与 TUI 程序（vim/htop 等），支持多标签页与断线自动重连（刷新页面/网络抖动后会话保活并恢复现场）；新标签默认在当前会话工作目录打开。标签栏「+」菜单还能开 SSH 标签页（ssh2 原生连接，连接簿在设置卡片维护，支持 agent forwarding 与主机指纹 TOFU 钉扎；连接簿条目可配单跳跳板机 ProxyJump），像本地终端一样操作远程主机。设置卡片开启「会话持久化（tmux）」后，新开的本地/SSH 标签默认由 tmux server 托管（宿主重启/断线超时后重开即恢复现场），长任务建议在持久化开启时运行。长驻进程（dev server、watch、交互式程序）用 tty_open 开一个会话跑（或引导用户到终端面板里运行），不要在 bash 工具里挂起等待；用户提到「开个终端 / 在终端里跑 / SSH 到某台机器」时引导其打开该面板。agent 侧配套工具：tty_list 列出活跃终端会话（含 SSH 的 target 与实时 cwd），tty_capture 读取近期输出（默认清洗 ANSI；last:true 拿「上一条命令」的输出+退出码），tty_screen 读取当前可见屏幕（可读懂 vim/htop 等 TUI），tty_expect 用正则等待输出中的就绪信号（如 dev server URL、构建完成；它**先回看还没读过的已到达输出**，命令瞬间跑完也不会白等——超时若只返回一句诊断文案，别当成「命令没执行」），tty_send 发送按键，tunnel_list 列出端口转发隧道状态——操作会实时显示在用户终端里。SFTP 文件传输：面板内可对 SSH 连接簿条目（或 SSH 连接对话框当前填写的信息）打开文件浏览（上传/下载/建目录/重命名/删除），传输期间进度条右侧 ✕ 可取消（半截文件自动清理）；agent 配套 sftp_list 列远程目录、sftp_tree 递归看目录结构、sftp_read 读远程文本文件（≤1MB）、sftp_write 写远程文本文件（≤1MB，可追加）、sftp_mkdir 建目录（parents 可逐级补齐）、sftp_rename 重命名/移动、sftp_remove 删除（目录需 recursive），book 参数为连接簿条目名。端口转发：连接簿条目可配本地/远程隧道（如把远程数据库映射到本地端口），宿主自动保活重连，用户提到「转发端口 / 访问远程库」时引导其到终端面板设置卡片配置。推荐流程：tty_send 启动长任务 → tty_expect 等就绪标记 → tty_capture{last:true} 拿结果。';
 /** 本地 PTY 包装成 TermHandle（resize/kill 仍是透传 node-pty 的内部耦合；防御性降级）。 */
 function wrapLocalPty(handle) {
     let resizeWarned = false;
@@ -217,6 +258,8 @@ class LiveConfig {
     persistSessions;
     /** SFTP 传输限制（客户端浏览器侧执行）。 */
     sftpLimits;
+    /** 允许 ProxyCommand（本机命令执行）：默认关（见 Config.allowProxyCommand）。 */
+    allowProxyCommand;
     constructor(init) {
         this.shell = init.shell;
         this.term = sanitizeTermValue(init.term, 'xterm-256color');
@@ -232,6 +275,8 @@ class LiveConfig {
         // 只有显式 false 才关（缺省/旧配置一律视为开）
         this.statsEnabled = init.statsEnabled !== false;
         this.sftpLimits = sanitizeSftpLimits(init.sftpLimits);
+        // 缺省/旧配置一律视为**关**（这一档是「本机命令执行」，只有显式 true 才开）
+        this.allowProxyCommand = init.allowProxyCommand === true;
         this.persistSessions = init.persistSessions ?? [];
     }
     /** 合并部分更新；空字符串/undefined 保持原值；sshHosts/hostKeys/tunnels 传数组即整体替换。 */
@@ -263,6 +308,8 @@ class LiveConfig {
             this.statsEnabled = partial.statsEnabled;
         if (partial.sftpLimits !== undefined)
             this.sftpLimits = sanitizeSftpLimits({ ...this.sftpLimits, ...partial.sftpLimits });
+        if (typeof partial.allowProxyCommand === 'boolean')
+            this.allowProxyCommand = partial.allowProxyCommand;
         if (Array.isArray(partial.persistSessions))
             this.persistSessions = partial.persistSessions;
     }
@@ -501,6 +548,65 @@ export function feedShellIntegration(session, text) {
             state.cmdBuffer = (state.cmdBuffer + rest).slice(-COMMAND_CAP);
     }
 }
+/**
+ * 唯一追加点（D72）：环形缓冲与单调字符计数一起维护。水位线用绝对值定位
+ * 未读区（`buffer 起点 = outputSeq - buffer.length`，裁剪只会前移起点，
+ * 公式恒成立），漏掉任何一处追加都会让它错位——notice 注入那两处此前也是
+ * 各写各的 `tailFromSafeBoundary`。
+ */
+function appendOutput(session, text) {
+    session.outputSeq += text.length;
+    session.buffer = tailFromSafeBoundary(session.buffer + text, BUFFER_CAP);
+}
+/** 原始流里最后一个「命令开始」B 标记的结束位置；-1 = 窗口内没有（无 shell 集成 → 降级）。 */
+function lastCommandStart(text) {
+    OSC133_RE.lastIndex = 0;
+    let end = -1;
+    for (const match of text.matchAll(OSC133_RE)) {
+        if (match[1] === 'B')
+            end = (match.index ?? 0) + match[0].length;
+    }
+    OSC133_RE.lastIndex = 0; // 归位：这个正则是共用的（feedShellIntegration 也用它）
+    return end;
+}
+/** 首次被 agent 工具触达时把水位线落在当下——否则第一次回扫会把用户此前的历史输出当成「还没读过」。 */
+function ensureReadMark(session) {
+    if (session.readSeq >= 0)
+        return;
+    session.readSeq = session.outputSeq;
+    session.readMarkAt = Date.now();
+}
+/** 读侧工具返回前推进水位线：返回时刻 = 「AI 真正看到的内容」的上界。 */
+function advanceReadMark(session) {
+    session.readSeq = session.outputSeq;
+    session.readMarkAt = Date.now();
+}
+/**
+ * 水位线之后的**未读**原始输出。下界再抬到「最后一个 B 标记之后」：回显落在
+ * A（prompt 开始）与 B（命令开始）之间，所以这样能零启发式地排除回显——按
+ * 文本比对「跳过与发送内容相同的行」会被折行 / ANSI / 多行粘贴打碎。
+ * 没有 B 标记（未开 shell 集成 / Windows PowerShell / 远端未装集成）时无法
+ * 区分回显，退化为从水位线起扫（可能匹配到回显本身，文档已声明）。
+ */
+function unreadRegion(session) {
+    ensureReadMark(session);
+    const bufferStart = session.outputSeq - session.buffer.length;
+    const text = session.buffer.slice(Math.max(0, session.readSeq - bufferStart));
+    const start = lastCommandStart(text);
+    return start === -1 ? text : text.slice(start);
+}
+/**
+ * pattern 匹配的统一入口（D72）：先对含 ANSI 的原始流试（live 路径原语义），
+ * 未命中再对清洗后文本试一次——这样承诺才是「tty_capture 里看得到的，
+ * tty_expect 也能匹配到」，而不是回扫命中、返回文案里却看不到。
+ */
+function testPattern(re, text) {
+    re.lastIndex = 0;
+    if (re.test(text))
+        return true;
+    re.lastIndex = 0;
+    return re.test(cleanAnsiTail(text));
+}
 /** 宽松清洗一份 tunnels 输入；输入不是数组时返回 undefined（表示「未提供，保持原值」）。 */
 function sanitizeTunnels(input) {
     if (!Array.isArray(input))
@@ -610,6 +716,14 @@ function sanitizeSshHosts(input) {
             agentForward: raw.agentForward === true,
             persist: raw.persist === true,
         });
+        // 跳板机：清洗不出可用对象（host 为空）就当没配——不给下游留半个对象
+        const jump = sanitizeJumpSpec(raw.jump);
+        if (jump !== undefined)
+            out[out.length - 1].jump = jump;
+        // 代理命令：形状不合法（含换行 / 超长 / 非字符串）就当没配（**失败方向是关**）
+        const proxyCommand = sanitizeProxyCommand(raw.proxyCommand);
+        if (proxyCommand !== undefined)
+            out[out.length - 1].proxyCommand = proxyCommand;
     }
     return out;
 }
@@ -650,6 +764,16 @@ function validateSshHosts(input) {
         if ((raw.auth === 'key') && (typeof raw.keyPath !== 'string' || raw.keyPath.trim() === '')) {
             return { error: `sshHosts「${String(raw.name)}」auth=key 需要 keyPath` };
         }
+        if (raw.jump !== undefined) {
+            const checked = validateJumpSpec(raw.jump);
+            if (checked.error !== undefined)
+                return { error: `sshHosts「${String(raw.name)}」${checked.error}` };
+        }
+        if (raw.proxyCommand !== undefined) {
+            const checked = validateProxyCommand(raw.proxyCommand);
+            if (checked.error !== undefined)
+                return { error: `sshHosts「${String(raw.name)}」${checked.error}` };
+        }
     }
     return { hosts: sanitizeSshHosts(input) };
 }
@@ -788,34 +912,16 @@ class HostKeyStore {
         this.persist(next);
     }
 }
-/** upgrade 路由的 loopback 信任围栏（与 dsh-mcp 的 HTTP 围栏同思路，socket 版）。 */
+/**
+ * upgrade 路由的 loopback 信任围栏（socket 版）：直接用 kit 的加固档（docker D31/D80/D110）。
+ *
+ * 与 HTTP 路由的差别只有一处刻意为之：**不放开 Cookie 例外**。升级请求在浏览器里必带
+ * `Origin`，而加固档「Origin 有就必须与 Host 同源」这条已经等价于同源证明；而长连
+ * （PTY / 隧道帧）一旦建立就一直活着，没必要为桌面壳那种「只带 Cookie」的转发链开口子
+ * ——真要支持，也应该先在桌面壳上验一条真机链路（docker 的 D139 是那样定下来的）。
+ */
 function isLoopbackUpgrade(req) {
-    const address = req.socket.remoteAddress;
-    if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1')
-        return false;
-    const host = req.headers.host;
-    if (typeof host !== 'string')
-        return false;
-    let hostUrl;
-    try {
-        hostUrl = new URL('http://' + host);
-    }
-    catch {
-        return false;
-    }
-    if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]')
-        return false;
-    if (req.headers['sec-fetch-site'] === 'cross-site')
-        return false;
-    const origin = req.headers.origin;
-    if (origin === undefined)
-        return true;
-    try {
-        return new URL(origin).host === hostUrl.host;
-    }
-    catch {
-        return false;
-    }
+    return isLoopbackRequestStrict(req);
 }
 /* ------------------------------------------------------------------ *
  * 虚拟屏（xterm-headless）——构造与异常兜底（D57）
@@ -1361,10 +1467,26 @@ export class TtyServer {
     }
     /** registerUpgrade 的 handler（loopback 围栏 + ws 握手）。 */
     handleUpgrade(req, socket, head) {
-        if (!isLoopbackUpgrade(req)) {
+        const loopback = isLoopbackUpgrade(req);
+        // 字面量环回同步判定（绝大多数请求：握手第一拍就继续，不引入额外时序）；
+        // 只有主机名 / /etc/hosts 别名才等一次 DNS 确认（≤500ms），期间不碰 socket
+        if (loopback instanceof Promise) {
+            void loopback.then((ok) => {
+                if (ok)
+                    this.finishUpgrade(req, socket, head);
+                else
+                    socket.destroy();
+            }).catch(() => { socket.destroy(); });
+            return;
+        }
+        if (!loopback) {
             socket.destroy();
             return;
         }
+        this.finishUpgrade(req, socket, head);
+    }
+    /** 围栏放行之后的实际握手（与上面的异步分支共用）。 */
+    finishUpgrade(req, socket, head) {
         if (!this.wsGateOpen) {
             socket.destroy();
             return;
@@ -1512,6 +1634,10 @@ export class TtyServer {
             local: new Map(),
             owner: 'agent',
         });
+        // D72：agent 自己开的会话从出生起「什么都没读过」（水位线落在 seq 0）——
+        // 包括 `command` 型会话在第一次 expect 之前打印的启动输出。用户开的标签
+        // 相反：历史输出不算未读，首次被 agent 触达时才把水位线落在当下。
+        ensureReadMark(session);
         // 面板可见性：新会话推给所有已连接的面板（客户端据此建「agent 开的」标签）
         this.broadcastSessions();
         return { sid: session.id, persist: session.tmuxName !== null && !degraded };
@@ -1684,6 +1810,9 @@ export class TtyServer {
                 startedAt: Date.now(),
                 lastOutputAt: Date.now(),
                 lastInputAt: Date.now(),
+                outputSeq: 0,
+                readSeq: -1,
+                readMarkAt: 0,
                 buffer: '',
                 decoder: new StringDecoder('utf8'),
                 screen: this.createScreen(clampInt(cols, 80, 2, 500), clampInt(rows, 24, 2, 200)),
@@ -1869,7 +1998,7 @@ export class TtyServer {
                 send(ws, { t: 'ready', sid, pid: next.handle.pid, kind: 'local', ...(next.tmuxName !== null ? { persist: true } : {}) });
                 if (created.wantsPersist && created.degraded) {
                     const notice = '\x1b[2m[dsh-tty] 未检测到 tmux，本标签以普通会话运行；安装 tmux 后持久化标签可跨宿主重启恢复现场\x1b[0m\r\n';
-                    next.buffer = tailFromSafeBoundary(next.buffer + notice, BUFFER_CAP);
+                    appendOutput(next, notice);
                     send(ws, { t: 'data', sid, d: notice });
                 }
             }
@@ -1952,6 +2081,9 @@ export class TtyServer {
                         startedAt: Date.now(),
                         lastOutputAt: Date.now(),
                         lastInputAt: Date.now(),
+                        outputSeq: 0,
+                        readSeq: -1,
+                        readMarkAt: 0,
                         buffer: '',
                         decoder: new StringDecoder('utf8'),
                         screen: this.createScreen(clampInt(msg.cols, 80, 2, 500), clampInt(msg.rows, 24, 2, 200)),
@@ -1980,7 +2112,7 @@ export class TtyServer {
                         this.trackPersist(tmuxName, true); // 留存：远程 tmux 本机清单看不到
                     if (handle.startupNotice !== undefined) {
                         const notice = `\x1b[2m[dsh-tty] ${handle.startupNotice}\x1b[0m\r\n`;
-                        next.buffer = tailFromSafeBoundary(next.buffer + notice, BUFFER_CAP);
+                        appendOutput(next, notice);
                         send(ws, { t: 'data', sid, d: notice });
                     }
                     this.attachOutput(next);
@@ -2219,7 +2351,7 @@ export class TtyServer {
             // StringDecoder 兜跨 chunk 多字节序列，再喂 shell 集成解析与虚拟屏
             const text = session.decoder.write(chunk);
             session.lastOutputAt = Date.now();
-            session.buffer = tailFromSafeBoundary(session.buffer + text, BUFFER_CAP);
+            appendOutput(session, text);
             feedShellIntegration(session, text);
             const screen = session.screen;
             if (screen !== null) {
@@ -2335,8 +2467,7 @@ function readManagedEnvKeys() {
  * 值在任何分支都不进响应——SSH 对话框的选择器只需要「我存过哪些名字」。
  */
 export async function handleCredentialRefsRoute(req, res) {
-    if (!isLoopbackHttp(req)) {
-        writeJson(res, 403, { error: 'forbidden: loopback-only' });
+    if (!(await gateRoute(req, res))) {
         return;
     }
     if (req.method !== 'GET') {
@@ -2448,38 +2579,84 @@ function mergeSshSpec(findSshHost, name, inline) {
         password: typeof inline.password === 'string' && inline.password !== '' ? inline.password : profile?.password,
         agentForward: typeof inline.agentForward === 'boolean' ? inline.agentForward : profile?.agentForward ?? false,
     };
+    /*
+     * 跳板机：内联给了就以它为准（清洗不出可用对象则退回连接簿那一份），否则用连接簿的。
+     * `jump` 只在**目标那一跳**之外多一跳，不支持嵌套（单跳），所以这里不做递归解析。
+     */
+    const inlineJump = inline.jump === undefined ? undefined : sanitizeJumpSpec(inline.jump);
+    const jump = inlineJump ?? profile?.jump;
+    if (jump !== undefined)
+        spec.jump = jump;
+    /*
+     * 代理命令：与跳板机同款「内联优先、否则用连接簿那一份」。两者同时存在**不在这里二选一**：
+     * 优先关系（ProxyJump 优先）在拨号处 `attachSshTransport` 一处决定，并记 warn——否则
+     * 「配了代理命令却走了跳板机」会被这里静默掉。
+     */
+    const inlineProxyCommand = inline.proxyCommand === undefined ? undefined : sanitizeProxyCommand(inline.proxyCommand);
+    const proxyCommand = inlineProxyCommand ?? profile?.proxyCommand;
+    if (proxyCommand !== undefined)
+        spec.proxyCommand = proxyCommand;
     if (spec.host === '' || spec.username === '')
         return { error: 'SSH 会话需要 host 与 username（或用 name 引用连接簿）' };
     return { spec };
 }
-/** HTTP 路由的 loopback 信任围栏（与 dsh-mcp 同思路）。 */
-function isLoopbackHttp(req) {
-    const address = req.socket.remoteAddress;
-    if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1')
-        return false;
-    const host = req.headers.host;
-    if (typeof host !== 'string')
-        return false;
-    let hostUrl;
-    try {
-        hostUrl = new URL('http://' + host);
-    }
-    catch {
-        return false;
-    }
-    if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]')
-        return false;
-    if (req.headers['sec-fetch-site'] === 'cross-site')
+/*
+ * 回环围栏与同源证明：**实现已收敛到 `@hyzyn/dsh-kit`**（2026-09-25，项目级 ROADMAP 第 1
+ * 项）。本包此前那份只认 `127.0.0.1` 一个字面量的同步围栏已删除，改走 kit 的加固档
+ * （docker D31/D80/D110），并给变更端点补上同源证明（docker D32/D139）——成因与桌面版
+ * 例外（桌面壳转发会删掉 Origin / Sec-Fetch-Site，但必带宿主 Cookie）的唯一归宿在
+ * `packages/kit/src/http.ts`，这里只留指针。
+ */
+/**
+ * 数据路由的统一闸门（**导出仅供单测**）：回环围栏（加固档）+ 变更端点的同源证明。
+ * 十二处路由此前各抄一遍 403 样板，`mutation` 这条判据一加就会各写各的——收敛成一处后
+ * 「拒绝分支」只有一份，负例也只测这一份。
+ *
+ * 哪些是变更端点（`mutation: true`）——**判据是「这次请求会不会改状态」**：
+ *   - `POST /probe`：真的拨号，且连接簿条目测试会当场 TOFU 记录主机指纹；
+ *   - `POST /sftp/{mkdir,rename,remove,upload}`、`POST /local-fs/{mkdir,rename,remove,transfer}`：
+ *     写远端 / 写本机 / 起传输任务；
+ *   - `POST /config`**刻意不在其列**（与 docker 同口径）：它是插件被禁用后唯一的恢复入口
+ *     ——卡片靠它渲染、也是重新启用的唯一 UI 入口；跨站 POST 已由上面那条围栏的
+ *     `sec-fetch-site: cross-site` 与 Origin 比对拦住。
+ * 只读端点（GET 全家 + `sftp /list` `/download`、`local-fs /list`）维持 loopback-only：
+ * 它们读的是用户自己主动要的东西，读路由加证明只会把旧 Safari / 裸 curl 一起挡在门外。
+ *
+ * **WS upgrade 不走这里**（那是 socket 握手，不是 req/res 路由）：见 `handleUpgrade`
+ * 用的 `isLoopbackRequestStrict`——它自带「Origin 有则必须同源」这条判据，等价于给
+ * 升级请求也上了证明，但**刻意不放开 Cookie 例外**：长连的生命周期比一次 POST 长得多。
+ */
+export async function gateRoute(req, res, options) {
+    if (!(await isLoopbackRequestStrict(req))) {
+        writeJson(res, 403, { error: 'forbidden: loopback-only' });
         return false;
-    const origin = req.headers.origin;
-    if (origin === undefined)
-        return true;
-    try {
-        return new URL(origin).host === hostUrl.host;
     }
-    catch {
+    if (options?.mutation === true && !hasSameOriginProof(req)) {
+        writeJson(res, 403, { error: '缺少同源证明（需要 Origin 或 Sec-Fetch-Site: same-origin）：变更端点拒绝无来源请求' });
         return false;
     }
+    return true;
+}
+/** 变更动作的子路由（见 gateRoute 的判据）：前缀路由先取 sub、再连 mutation 一起过闸。 */
+const MUTATION_SUBROUTES = {
+    '/api/dsh-tty/sftp': new Set(['/mkdir', '/rename', '/remove', '/upload']),
+    '/api/dsh-tty/local-fs': new Set(['/mkdir', '/rename', '/remove', '/transfer']),
+    /*
+     * 就地提权：三条子路由**逐条**列（docker D144 的教训）——判据是「精确子路径 + POST」，
+     * 只写一条的话另外两条就是裸的（跨站页面能撤销授权、能反复对着确认挑战试错）。
+     */
+    '/api/dsh-tty/elevate': new Set(['', '/status', '/revoke']),
+};
+/**
+ * 这个前缀路由的子路径是否**会改状态**（导出仅供单测）。
+ *
+ * 为什么单独抽出来：`/list` 与 `/download` 也是 POST（凭证走 body、不进 URL），但它们只是
+ * 读——如果把「POST 就要求证明」一刀切下去，读路由会连带把旧 Safari / 裸 curl 挡在门外，
+ * 而它们本来就没有可被跨站利用的副作用。判据是**动作**不是**方法**，所以名单必须显式。
+ * 没见过的子路径一律 false（几步之后就是 404，不给它额外的信息量）。
+ */
+export function isMutationSubroute(prefix, sub) {
+    return MUTATION_SUBROUTES[prefix]?.has(sub) === true;
 }
 function writeJson(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' });
@@ -2586,6 +2763,24 @@ const plugin = definePlugin({
     // 均拿不到，实测 mcp-client 同款模式），声明后 ctx.get('tools') 才能取到。
     inject: ['tools'],
     apply(ctx, rawConfig) {
+        /*
+         * 授权来源必须在**第一次 capabilityGranted 之前**绑定（见 kit 的 capability.ts）。两条通道：
+         *   ① 启动环境快照（最严档，只认继承来的 `process` 层）；
+         *   ② 就地提权（免重启）：卡片上点开关 → 宿主文件系统上落地一个随机名确认文件 → 授权写进
+         *      grant-store（HTTP 写不到）。落点全部来自 kit 的 `capabilityPaths`（路径只在那里拼一次）。
+         * 存储每次 apply 新建一个实例 —— 这就是「宿主重启后重新读盘」的语义。
+         */
+        const paths = capabilityPaths(resolveDshHome());
+        // **共享实例**（kit D11）：tty 与 docker 同装时各 new 一个会各自缓存一份文件快照，
+        // 后绑定的那个看不到另一个后来写进去的授权（实测：tty 授权成功后自己的快照仍是 false）
+        const grantStore = sharedGrantStore(paths.dir);
+        bindCapabilitySources(ctx, grantStore);
+        /*
+         * 启动期审计：盘上已有的带外授权是**持久**的（重启后直接生效、不再有任何一次确认），所以那次
+         * 「静默继承」必须在日志里留下痕迹（kit D09）。刻意放在 `enabled` 判定**之前**：授权是宿主级的，
+         * 与插件这次是否启用无关。
+         */
+        auditLoadedGrants(grantStore, [CAP_PROXY_COMMAND.env], { info: (msg) => ctx.logger.info(msg), warn: (msg) => ctx.logger.warn(msg) }, '[dsh-tty]');
         // volatile 字段解析后是 `{ get() }` 引用，先还原成纯数据（见 @hyzyn/dsh-kit 的 plainConfig）。
         const config = plainConfig((rawConfig ?? {}));
         if (config?.enabled === false)
@@ -2609,8 +2804,20 @@ const plugin = definePlugin({
             endOnPageClose: config?.endOnPageClose === true,
             statsEnabled: config?.statsEnabled !== false,
             sftpLimits: sanitizeSftpLimits(config?.sftpLimits),
+            allowProxyCommand: config?.allowProxyCommand === true,
             persistSessions: sanitizePersistSessions(config?.persistSessions) ?? [],
         });
+        /*
+         * 闸门在**挂载时先初始化一次**（tty D70）。
+         *
+         * 它的唯一写入方是 `applyPatch`，而 `applyPatch` 在启动期**只在「settings 里存过东西」时才跑**
+         * （见那里 `if (Object.keys(startup).length > 0)`）。于是「配置里写着 `allowProxyCommand: true`
+         * + 已授权（环境变量或授权文件）+ 重启宿主」这条最平常的路径会停在模块级默认值
+         * `{granted:false, enabled:false}` 上：fail-closed（不是安全问题），但症状正是本仓最忌讳的
+         * 「配了没反应」——卡片显示已授权，代理命令却仍被拒。这条在接入就地提权后才致命：授权是
+         * **持久**的，重启后更要保证「界面上说已授权」与「闸门真的放行」一致。
+         */
+        setProxyCommandPolicy({ granted: capabilityGranted(CAP_PROXY_COMMAND), enabled: live.allowProxyCommand });
         const sessions = new SessionManager(config?.maxSessions ?? DEFAULT_MAX_SESSIONS, () => live.endOnPageClose);
         /** TOFU 指纹记录持久化：写入 settings 命名空间（合并语义），失败不影响连接。 */
         const persistHostKeys = (records) => {
@@ -2672,6 +2879,18 @@ const plugin = definePlugin({
             endOnPageClose: live.endOnPageClose,
             statsEnabled: live.statsEnabled,
             sftpLimits: live.sftpLimits,
+            allowProxyCommand: live.allowProxyCommand,
+            allowProxyCommandGranted: capabilityGranted(CAP_PROXY_COMMAND),
+            /*
+             * 授权来源：'env' = 启动环境变量（界面不给「撤销」按钮，它只能靠改启动环境撤销）、
+             * 'file' = 就地确认写下的带外授权（界面可撤销）、null = 没授权。
+             */
+            allowProxyCommandGrantSource: capabilityGrantVia(CAP_PROXY_COMMAND) ?? null,
+            /*
+             * 授权时刻（Unix 秒；只有 file 通道有值）。授权是**持久**的：重启后它直接生效、不再确认，
+             * 界面至少要能说出它是什么时候来的（kit D09）。
+             */
+            allowProxyCommandGrantedAt: capabilityGrantAt(CAP_PROXY_COMMAND) ?? null,
             toolsRegistered: stateRef.toolsRegistered,
             /**
              * 宿主平台（`process.platform`）：客户端据此把「Shell 路径 / shell 集成」的说明与候选
@@ -2695,8 +2914,16 @@ const plugin = definePlugin({
                 endOnPageClose: typeof section.endOnPageClose === 'boolean' ? section.endOnPageClose : undefined,
                 statsEnabled: typeof section.statsEnabled === 'boolean' ? section.statsEnabled : undefined,
                 sftpLimits: typeof section.sftpLimits === 'object' && section.sftpLimits !== null ? section.sftpLimits : undefined,
+                allowProxyCommand: typeof section.allowProxyCommand === 'boolean' ? section.allowProxyCommand : undefined,
                 persistSessions: sanitizePersistSessions(section.persistSessions),
             });
+            /*
+             * ProxyCommand 闸门跟着 settings 走（**每次热应用都写一次**）：这一档是「设置字段驱动的
+             * 本机任意命令执行」，关掉之后必须**立刻**对四条建连路径全部生效（终端 / SFTP / 隧道 /
+             * 探针共用 ssh.ts 的模块级策略，见 setProxyCommandPolicy）。启动路径也走这里
+             * （settings 就绪时 applyPatch 会被调用一次），所以不存在「忘了初始化 → 意外为开」。
+             */
+            setProxyCommandPolicy({ granted: capabilityGranted(CAP_PROXY_COMMAND), enabled: live.allowProxyCommand });
             if (typeof section.enabled === 'boolean')
                 stateRef.enabled = section.enabled;
             if (typeof section.announceToAgent === 'boolean')
@@ -2717,12 +2944,12 @@ const plugin = definePlugin({
             server.setWsGate(stateRef.enabled);
             // 状态条开关热生效：关的时候停掉全部采集（本地定时器 + 远端 exec channel）
             server.setStatsEnabled(live.statsEnabled);
-            console.log(`[dsh-tty] config applied (shell=${live.shell}, term=${live.term}, cwd=${live.cwd}, maxSessions=${sessions.limitValue}, sshHosts=${live.sshHosts.length}, enabled=${String(stateRef.enabled)})`);
+            console.log(`[dsh-tty] config applied (shell=${live.shell}, term=${live.term}, cwd=${live.cwd}, maxSessions=${sessions.limitValue}, sshHosts=${live.sshHosts.length}, allowProxyCommand=${String(live.allowProxyCommand)}, enabled=${String(stateRef.enabled)})`);
         };
         /** 校验 HTTP POST 的配置体；返回规范化补丁或错误信息。 */
         const normalizePatch = (input) => {
             const patch = {};
-            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'reconnectGraceSec', 'sshHosts', 'hostKeys', 'tunnels', 'shellIntegration', 'sftpStyle', 'persistence', 'endOnPageClose', 'statsEnabled', 'sftpLimits']);
+            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'reconnectGraceSec', 'sshHosts', 'hostKeys', 'tunnels', 'shellIntegration', 'sftpStyle', 'persistence', 'endOnPageClose', 'statsEnabled', 'sftpLimits', 'allowProxyCommand']);
             for (const key of Object.keys(input)) {
                 if (!known.has(key))
                     return { error: '未知配置项: ' + key };
@@ -2774,6 +3001,19 @@ const plugin = definePlugin({
                     return { error: 'statsEnabled 必须是布尔值' };
                 patch.statsEnabled = input.statsEnabled;
             }
+            if (input.allowProxyCommand !== undefined) {
+                if (typeof input.allowProxyCommand !== 'boolean')
+                    return { error: 'allowProxyCommand 必须是布尔值' };
+                /*
+                 * **只能降不能升**：提权只认宿主侧的环境变量（进程启动时采样一次），HTTP 侧给 true
+                 * 一律驳回并说清怎么做。这不是「输入不合法」，而是「没获授权」——所以文案必须同时
+                 * 给出变量名与「要重启宿主」，否则用户会对着一个点不动的开关反复点。
+                 */
+                if (input.allowProxyCommand && !capabilityGranted(CAP_PROXY_COMMAND)) {
+                    return { error: capabilityDeniedMessage(CAP_PROXY_COMMAND, { inPlace: true }) };
+                }
+                patch.allowProxyCommand = input.allowProxyCommand;
+            }
             for (const key of ['shell', 'term', 'colorTerm']) {
                 if (input[key] === undefined)
                     continue;
@@ -2847,6 +3087,30 @@ const plugin = definePlugin({
             setCredentialResolver(credCtx.credentials ?? null);
             return () => { setCredentialResolver(null); };
         });
+        /*
+         * 就地提权（见 kit 的 elevation.ts）：卡片上点开关 → 宿主在确认目录里等一个随机名文件出现
+         * → 授权写进 grant-store。
+         *
+         * `onGrantChange` 是这一段里**最容易漏、也最要紧**的一下：`setProxyCommandPolicy` 是终端 /
+         * SFTP / 隧道 / 探针**四条建连路径共用**的模块级闸门，只写存储不重算就会留下两种半个状态——
+         *   - 授权侧：授权到了，代理命令仍然被拒（用户以为没生效，再去点开关）；
+         *   - 撤销侧：记录没了，本机仍在跑连接簿里那条命令（这一侧是安全问题，不是体验问题）。
+         * `applyPatch({})` 用当前 live 兜底重算一次即可（它本来就每次都写一次策略，见那里的注释）。
+         */
+        const elevation = createElevationManager({
+            confirmDir: paths.confirmDir,
+            store: grantStore,
+            logger: { info: (msg) => ctx.logger.info(msg), warn: (msg) => ctx.logger.warn(msg) },
+            logPrefix: '[dsh-tty]',
+            onGrantChange: () => {
+                applyPatch({});
+            },
+        });
+        ctx.effect(() => {
+            return () => {
+                elevation.dispose();
+            };
+        }, 'dsh-tty: elevation cleanup');
         // webServer：WS upgrade 路由 + 配置读写路由（/api/dsh-tty/config）
         ctx.inject(['webServer'], (webCtx) => {
             webCtx.effect(() => {
@@ -2873,8 +3137,7 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/config',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method === 'GET') {
@@ -2913,13 +3176,74 @@ const plugin = definePlugin({
                         writeJson(res, 200, { ok: true, config: snapshot() });
                     },
                 }));
-                // ~/.ssh/config 导入候选（连接簿）：loopback 围栏，只回解析结果不落盘
+                /*
+                 * 就地提权（`/elevate`、`/elevate/status`、`/elevate/revoke`）。
+                 *
+                 * 三条**全 POST**、**逐条**进 MUTATION_SUBROUTES（判据是「精确子路径 + POST」，只写一条
+                 * 另外两条就是裸的 → docker D144），且分发必须在证明检查**之后**——`sub` 一旦拿去分支，
+                 * 后面再补证明就晚了。
+                 *
+                 * 刻意**不走** registerGated：授权是宿主级的，插件当前禁用时也该能在卡片里提权/撤销
+                 * （卡片本身是禁用后唯一的恢复入口，与 /config 同一条理由）。
+                 */
+                disposers.push(webServer.register({
+                    kind: 'prefix',
+                    path: '/api/dsh-tty/elevate',
+                    handler: async (req, res) => {
+                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/elevate'.length);
+                        if (!(await gateRoute(req, res, { mutation: isMutationSubroute('/api/dsh-tty/elevate', sub) }))) {
+                            return;
+                        }
+                        if (req.method !== 'POST') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        if (sub !== '' && sub !== '/status' && sub !== '/revoke') {
+                            writeJson(res, 404, { error: 'not found' });
+                            return;
+                        }
+                        const body = await readJsonBody(req);
+                        if (body === undefined) {
+                            writeJson(res, 400, { error: 'invalid JSON body' });
+                            return;
+                        }
+                        // 白名单：别让请求方决定查哪个键（那张表是宿主侧的策略来源）
+                        if (body.capability !== undefined && body.capability !== CAP_PROXY_COMMAND.env) {
+                            writeJson(res, 400, { error: '未知能力: ' + String(body.capability) });
+                            return;
+                        }
+                        if (sub === '/status') {
+                            writeJson(res, 200, elevation.status(CAP_PROXY_COMMAND.env));
+                            return;
+                        }
+                        if (sub === '/revoke') {
+                            // 降权零门槛：撤销不要求任何确认（紧急刹车不等重启）。撤销带来的策略重算由
+                            // elevation 的 onGrantChange 负责——不重算就会留下「记录没了、本机还在跑命令」
+                            writeJson(res, 200, { revoked: elevation.revoke(CAP_PROXY_COMMAND.env) });
+                            return;
+                        }
+                        const result = elevation.begin(CAP_PROXY_COMMAND.env);
+                        if (result.status === 'rate-limited') {
+                            writeJson(res, 429, { error: '请求过于频繁，请稍后再试', retryAfterMs: result.retryAfterMs });
+                            return;
+                        }
+                        if (result.status === 'error') {
+                            writeJson(res, 500, { error: result.error });
+                            return;
+                        }
+                        // 只回状态与一次性命令；nonce 就在命令里，**不进日志**（见 elevation.ts 的不变量）
+                        writeJson(res, 200, result);
+                    },
+                }));
+                // ~/.ssh/config 导入候选（连接簿）：loopback 围栏，只回解析结果不落盘。
+                // 除了候选，还**如实回报丢弃了什么**（依赖跳板机 / 通配 / 无 User / 超上限）：
+                // 静默少列是本仓反复出现的一类缺陷，而「导进来的条目注定连不上」更难排——见
+                // 项目级 ROADMAP 第 2 项。
                 registerGated({
                     kind: 'exact',
                     path: '/api/dsh-tty/ssh-config',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method !== 'GET') {
@@ -2928,7 +3252,7 @@ const plugin = definePlugin({
                         }
                         try {
                             const text = readFileSync(expandHome('~/.ssh/config'), 'utf8');
-                            writeJson(res, 200, { ok: true, entries: parseSshConfig(text) });
+                            writeJson(res, 200, { ok: true, ...parseSshConfigDetailed(text) });
                         }
                         catch (error) {
                             writeJson(res, 200, { ok: false, error: '无法读取 ~/.ssh/config: ' + (error instanceof Error ? error.message : String(error)) });
@@ -2940,8 +3264,7 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/env-vars',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method !== 'GET') {
@@ -2965,8 +3288,7 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/known-hosts',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method !== 'GET') {
@@ -2994,8 +3316,8 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/probe',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        // 变更端点：这次请求真的拨号，且连接簿条目测试会当场记录主机指纹（TOFU）
+                        if (!(await gateRoute(req, res, { mutation: true }))) {
                             return;
                         }
                         if (req.method !== 'POST') {
@@ -3024,6 +3346,22 @@ const plugin = definePlugin({
                         }
                         const auth = body.auth === 'key' || body.auth === 'password' ? body.auth : 'agent';
                         const spec = { host, port, username, auth };
+                        // 对话框「试连」可能带跳板机（连接簿条目由客户端先行展开；跳板机同理）
+                        const probeJump = validateJumpSpec(body.jump);
+                        if (body.jump !== undefined && probeJump.error !== undefined) {
+                            writeJson(res, 200, { ok: false, error: probeJump.error });
+                            return;
+                        }
+                        if (probeJump.jump !== undefined)
+                            spec.jump = probeJump.jump;
+                        // 代理命令同理（对话框试连会带上当前填写值）：形状非法就明确报错，别静默当没填
+                        const probeProxy = validateProxyCommand(body.proxyCommand ?? '');
+                        if (probeProxy.error !== undefined) {
+                            writeJson(res, 200, { ok: false, error: probeProxy.error });
+                            return;
+                        }
+                        if (probeProxy.proxyCommand !== undefined)
+                            spec.proxyCommand = probeProxy.proxyCommand;
                         if (auth === 'key') {
                             const keyPath = typeof body.keyPath === 'string' ? body.keyPath.trim() : '';
                             if (keyPath === '') {
@@ -3056,8 +3394,7 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/shells',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method !== 'GET') {
@@ -3072,8 +3409,7 @@ const plugin = definePlugin({
                     kind: 'exact',
                     path: '/api/dsh-tty/tunnels',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        if (!(await gateRoute(req, res))) {
                             return;
                         }
                         if (req.method !== 'GET') {
@@ -3093,11 +3429,11 @@ const plugin = definePlugin({
                     kind: 'prefix',
                     path: '/api/dsh-tty/sftp',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/sftp'.length);
+                        // 改状态的三个动作 + 上传要同源证明；/list 与 /download 只读（判据见 gateRoute）
+                        if (!(await gateRoute(req, res, { mutation: isMutationSubroute('/api/dsh-tty/sftp', sub) }))) {
                             return;
                         }
-                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/sftp'.length);
                         const jsonAction = ['/list', '/mkdir', '/rename', '/remove', '/download'].find((action) => action === sub);
                         if (jsonAction !== undefined) {
                             if (req.method !== 'POST') {
@@ -3253,11 +3589,11 @@ const plugin = definePlugin({
                     kind: 'prefix',
                     path: '/api/dsh-tty/local-fs',
                     handler: async (req, res) => {
-                        if (!isLoopbackHttp(req)) {
-                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/local-fs'.length);
+                        // 改状态的四个动作（含起一个传输任务）要同源证明；/list 只读（判据见 gateRoute）
+                        if (!(await gateRoute(req, res, { mutation: isMutationSubroute('/api/dsh-tty/local-fs', sub) }))) {
                             return;
                         }
-                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/local-fs'.length);
                         if (req.method !== 'POST') {
                             writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
                             return;
@@ -3458,6 +3794,8 @@ const plugin = definePlugin({
                     }
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_list',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '列出当前活跃的终端面板会话（sid / kind(local|ssh) / target / pid / cwd / 创建与最后活动时间）。用户开了终端面板后，用 tty_capture 读取某个 sid 的终端输出，用 tty_send 向该终端发送按键。',
                         parameters: {},
                         output: {
@@ -3500,6 +3838,9 @@ const plugin = definePlugin({
                             },
                         },
                         async execute() {
+                            // D72：agent 第一次「看见」这些会话时把水位线落在当下——否则第一次
+                            // tty_expect 会把用户早先的历史输出当成「还没读过的输出」回扫过来
+                            sessions.forEach((session) => { ensureReadMark(session); });
                             return { sessions: sessions.list() };
                         },
                     })));
@@ -3564,6 +3905,8 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_stats',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '读取某个终端会话所在机器的实时指标（CPU / 内存 / 磁盘 / TCP 连接数 / 网速 / 温度 / 在线时长）——本地会话取宿主机，SSH 会话取那台远程主机（另开一条非 PTY 通道，不影响终端）。部署、压测、排查「机器是不是满了」之前先看它。仅 Linux 远端字段齐全，Windows 远端部分字段可采，macOS/BSD 远端取不到。',
                         parameters: {
                             sid: { type: 'string', required: true, description: '会话 id（tty_list 提供）' },
@@ -3625,6 +3968,8 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_capture',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '读取某个终端面板会话（tty_list 提供 sid）的近期输出。默认读取尾部 N 行（60，最多 500，已剥离 ANSI 转义序列并收敛同行覆盖）；last:true 时只返回「上一条已完成命令」的输出与退出码（依赖 shell 集成标记，更适合拿单条命令的结果）——若命令在途（刚发送/未收到完成标记）返回 inProgress:true 且不携带旧结果，请稍后重试或改用 tty_expect。',
                         parameters: {
                             sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
@@ -3663,6 +4008,11 @@ const plugin = definePlugin({
                             if (session === undefined || session.closed)
                                 throw new Error(`会话不存在或已退出: ${input.sid}`);
                             const useRaw = input.raw === true;
+                            // D72：读侧工具返回前推进水位线——这里读到的内容算「已读」，后续
+                            // tty_expect 不再把它们当未读回扫（想回看更早的内容再用本工具）。
+                            // tty_screen 刻意**不**推进：它是「当前可见屏幕」这一种表示，不是
+                            // 文本流，推进它会把 AI 从未在文本里看过的输出标记成已读。
+                            advanceReadMark(session);
                             if (input.last === true) {
                                 const state = session.shellState;
                                 const last = state.lastCommand;
@@ -3689,6 +4039,8 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_screen',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '读取某个终端面板会话（tty_list 提供 sid）当前可见屏幕的渲染结果（纯文本，等价于用户此刻看到的画面）。适合查看全屏交互程序（vim / htop / 菜单选择）的当前界面状态；要历史滚动输出用 tty_capture。',
                         parameters: {
                             sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
@@ -3735,7 +4087,9 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_expect',
-                        description: '在某个终端面板会话（tty_list 提供 sid）的后续输出中等待一个正则出现（如 dev server 的 ready/URL、构建完成标记、交互提示）。匹配到立即返回 matched:true 与周边输出；超时不抛错，返回 matched:false + 尾部输出供判断重试或放弃；期间该命令若已结束（shell 集成标记）也会提前返回并带退出码。适合先 tty_send 启动长任务、再 tty_expect 等就绪信号的流程。',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
+                        description: '在某个终端面板会话（tty_list 提供 sid）等待一个正则出现（如 dev server 的 ready/URL、构建完成标记、交互提示）。**先回溯**还没被读过的输出（含「上一条命令」的完整输出），再等后续输出——所以命令瞬间跑完也不会白等；匹配到立即返回 matched:true（matchedFrom 说明匹配来自哪里：live=本次等待期间新产生 / last=上一条命令的输出 / buffered=此前已到达的缓冲输出）与周边输出。超时不抛错，返回 matched:false + 尾部输出；期间该命令若已结束（shell 集成标记）也会提前返回并带退出码。适合先 tty_send 启动长任务、再 tty_expect 等就绪信号的流程。注意：只对「还没读过的输出」负责——要回看更早的内容用 tty_capture。',
                         parameters: {
                             sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
                             pattern: { type: 'string', required: true, description: '等待匹配的正则表达式（JavaScript RegExp 语法）' },
@@ -3750,12 +4104,21 @@ const plugin = definePlugin({
                                     timedOut: { type: 'boolean', required: true },
                                     text: { type: 'string', required: true },
                                     exitCode: { type: 'number' },
+                                    matchedFrom: { type: 'string' },
                                 },
                             },
                             render: (_args, value) => {
                                 const v = value;
-                                if (v.matched === true)
-                                    return [{ type: 'text', text: `已匹配到等待的模式：\n\n${v.text ?? ''}` }];
+                                if (v.matched === true) {
+                                    const from = v.matchedFrom === 'last'
+                                        ? '（回溯自「上一条命令」的输出）'
+                                        : v.matchedFrom === 'buffered' ? '（回溯自此前已到达、还没读过的缓冲输出）' : '';
+                                    return [{ type: 'text', text: `已匹配到等待的模式${from}：\n\n${v.text ?? ''}` }];
+                                }
+                                if (v.timedOut === true && (v.text ?? '').trim() === '') {
+                                    // D72：这段空白此前被当成「命令没执行」——命令若是瞬间完成的，它早就跑完了
+                                    return [{ type: 'text', text: '等待超时，且注册之后没有任何新输出。命令若是瞬间完成的，它早已在开始等待之前跑完：用 tty_capture{last:true} 复核那条命令的输出与退出码，别把这段空白当成「没执行」。' }];
+                                }
                                 const why = v.timedOut === true ? '等待超时' : `命令已结束（exitCode=${String(v.exitCode ?? '?')}）但未出现匹配`;
                                 return [{ type: 'text', text: `${why}。尾部输出：\n\n${v.text ?? ''}` }];
                             },
@@ -3787,36 +4150,65 @@ const plugin = definePlugin({
                             expectCounts.set(session, inflight + 1);
                             return await new Promise((resolve) => {
                                 const startedAt = Date.now();
-                                const startedInCommand = session.shellState.inCommand;
+                                const state = session.shellState;
+                                const startedInCommand = state.inCommand;
                                 // 尾部窗口：匹配只看最近 16KB，acc 全量囤积对刷屏会话可涨到数百 MB
                                 let acc = '';
                                 let settled = false;
+                                let timer = null;
                                 const decoder = new StringDecoder('utf8');
                                 const output = session.handle.output;
-                                const finish = (result) => {
+                                /**
+                                 * 结算时的水位线（D72）：
+                                 *  - 匹配成功 / 会话结束 → 推进到当下（这段输出已经交回给 AI 了）；
+                                 *  - **超时不动**：那次只把注册之后的增量交回去，注册前就在缓冲里的
+                                 *    未读输出没被读过，而且下一次换个 pattern 还要靠它回溯——吞掉
+                                 *    它等于「等一次没等到，这段输出就作废了」。
+                                 */
+                                const finish = (result, consumeBacklog = true) => {
                                     if (settled)
                                         return;
                                     settled = true;
-                                    clearTimeout(timer);
+                                    if (timer !== null)
+                                        clearTimeout(timer);
                                     output.off('data', onData);
                                     expectCounts.set(session, Math.max(0, (expectCounts.get(session) ?? 1) - 1));
+                                    if (consumeBacklog)
+                                        advanceReadMark(session);
                                     resolve(result);
                                 };
-                                const onData = (chunk) => {
+                                function onData(chunk) {
                                     acc = (acc + decoder.write(chunk)).slice(-64 * 1024);
                                     const hay = acc.length > 16 * 1024 ? acc.slice(-16 * 1024) : acc;
-                                    if (re.test(hay)) {
-                                        finish({ matched: true, timedOut: false, text: cleanAnsiTail(hay.slice(-6 * 1024)) });
+                                    if (testPattern(re, hay)) {
+                                        finish({ matched: true, timedOut: false, matchedFrom: 'live', text: cleanAnsiTail(hay.slice(-6 * 1024)) });
                                         return;
                                     }
                                     // 命令早停：注册时命令在飞（B..D 之间），如今 D 已到仍未匹配
-                                    const state = session.shellState;
                                     if (startedInCommand && !state.inCommand && state.lastCommand !== null && state.lastCommand.endedAt >= startedAt) {
                                         finish({ matched: false, timedOut: false, ...(state.lastCommand.exitCode === null ? {} : { exitCode: state.lastCommand.exitCode }), text: cleanAnsiTail(acc.slice(-6 * 1024)) });
                                     }
-                                };
-                                const timer = setTimeout(() => {
-                                    finish({ matched: false, timedOut: true, text: cleanAnsiTail(acc.slice(-6 * 1024)) });
+                                }
+                                // ── 注册**之前**就已到达的输出（D72）─────────────────────────
+                                // 这段此前完全不匹配：acc 从空开始，所以「命令瞬间完成」时标记
+                                // 早就躺在缓冲区里、acc 里永远没有它 → 白等满超时、还只返回空白。
+                                ensureReadMark(session);
+                                // ① 上一条命令的完整输出（B..D 窗口：无回显、无提示符、自带退出码）。
+                                //    两个闸门保证它「还没被读过」：不晚于最后一次输入（否则是上一条
+                                //    命令的旧结果），且晚于水位线时刻（否则 AI 已经用 capture 看过了）。
+                                const last = state.lastCommand;
+                                if (!state.inCommand && last !== null && last.endedAt > session.readMarkAt && last.endedAt >= session.lastInputAt && testPattern(re, last.output)) {
+                                    finish({ matched: true, timedOut: false, matchedFrom: 'last', ...(last.exitCode === null ? {} : { exitCode: last.exitCode }), text: cleanAnsiTail(last.output.slice(-6 * 1024)) });
+                                    return;
+                                }
+                                // ② 泛化：水位线之后的未读缓冲（长驻输出落在多条命令之间、无 shell 集成……）
+                                const backlog = unreadRegion(session);
+                                if (backlog !== '' && testPattern(re, backlog)) {
+                                    finish({ matched: true, timedOut: false, matchedFrom: 'buffered', text: cleanAnsiTail(backlog.slice(-6 * 1024)) });
+                                    return;
+                                }
+                                timer = setTimeout(() => {
+                                    finish({ matched: false, timedOut: true, text: cleanAnsiTail(acc.slice(-6 * 1024)) }, false);
                                 }, timeoutMs);
                                 timer.unref?.();
                                 output.on('data', onData);
@@ -3857,12 +4249,17 @@ const plugin = definePlugin({
                             if (session === undefined || session.closed)
                                 throw new Error(`会话不存在或已退出: ${input.sid}`);
                             session.lastInputAt = Date.now();
+                            // D72：只初始化水位线，**不推进**——刚发出去的这条命令的输出 AI 还没看见；
+                            // 但这一刻之前的积压不该被第一次 expect 当成「未读」回扫。
+                            ensureReadMark(session);
                             await session.handle.write(input.data);
                             return { ok: true, sent: input.data.length };
                         },
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tunnel_list',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '列出端口转发隧道及其实时状态（活跃/连接中/错误/停止、规则、当前与累计连接数、最近错误）。用户说「隧道连不上 / 转发挂了 / 端口转发不通」时先用它诊断；隧道在 插件配置 → 终端面板 卡片维护。',
                         parameters: {},
                         output: {
@@ -3883,6 +4280,7 @@ const plugin = definePlugin({
                                                 bookName: { type: 'string', required: true },
                                                 state: { type: 'string', required: true },
                                                 error: { type: 'string' },
+                                                fatal: { type: 'boolean', required: true },
                                                 connections: { type: 'number', required: true },
                                                 totalConnections: { type: 'number', required: true },
                                             },
@@ -3896,7 +4294,10 @@ const plugin = definePlugin({
                                 if (tunnels.length === 0)
                                     return [{ type: 'text', text: '当前没有配置端口转发隧道（插件配置 → 终端面板 卡片可添加）' }];
                                 const text = '端口转发隧道：' + tunnels.map((t) => {
-                                    const tail = t.error !== null && t.error !== undefined ? `（错误: ${t.error}）` : t.lastForwardError !== null && t.lastForwardError !== undefined ? `（最近转发失败: ${t.lastForwardError}）` : `（连接 ${String(t.connections)}）`;
+                                    // fatal 单独措辞（D58）：这类故障不会自愈，不说清就会一直等「正在连」
+                                    const tail = t.error !== null && t.error !== undefined
+                                        ? (t.fatal === true ? `（错误: ${t.error} —— 不会自动重试，需修配置）` : `（错误: ${t.error}）`)
+                                        : t.lastForwardError !== null && t.lastForwardError !== undefined ? `（最近转发失败: ${t.lastForwardError}）` : `（连接 ${String(t.connections)}）`;
                                     return `\n- ${t.name} [${t.direction}] ${t.rule} — ${t.state}${tail}`;
                                 }).join('');
                                 return [{ type: 'text', text }];
@@ -3917,6 +4318,7 @@ const plugin = definePlugin({
                                     rule: t.rule,
                                     state: t.state,
                                     ...(t.error === null || t.error === undefined ? {} : { error: t.error }),
+                                    fatal: t.fatal,
                                     connections: t.connections,
                                     totalConnections: t.totalConnections,
                                 })),
@@ -3936,6 +4338,8 @@ const plugin = definePlugin({
                     };
                     activeDisposers.push(tools.register(defineTool({
                         name: 'sftp_list',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '列出 SSH 远程目录内容（名称/类型/大小/修改时间，目录在前；isSymlink 区分符号链接与真目录）。book 为 SSH 连接簿条目名；path 缺省为远程登录 home。默认最多列 500 项（超限 truncated:true，可按子目录分批）。',
                         parameters: {
                             book: { type: 'string', required: true, description: 'SSH 连接簿条目名（插件配置 → 终端面板 维护）' },
@@ -3987,6 +4391,8 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'sftp_read',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '读取 SSH 远程文本文件（book 连接簿条目 + path）。默认最多 256KB（可调至 1MB，非法值直接报错）；offset 可从指定字节起读（配合 maxBytes 分页拿到大文件尾部）；二进制判定用 NUL + 非法 UTF-8 占比双重检测，拒绝时说明原因。',
                         parameters: {
                             book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
@@ -4194,6 +4600,8 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'sftp_tree',
+                        // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                        isConcurrencySafe: () => true,
                         description: '递归列举 SSH 远程目录结构（book 连接簿条目 + path）：深度优先、目录优先，maxDepth（1~8，默认 3）限层、maxEntries（1~2000，默认 500）限条数，超限 truncated:true；符号链接不跟随；读取失败的子目录列入 errors。适合先看远程项目结构再定位文件。',
                         parameters: {
                             book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },