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

package/lib/index.d.ts

@@ -68,6 +68,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { PassThrough } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 import xtermHeadless from '@xterm/headless';
@@ -155,10 +156,10 @@ export declare const Config: z;
  *
  * - 时间上界对用户是**第二重惊喜**——「命令跑完 → 下一轮读结果」之间隔着人离开、
  *   模型排队，多久都有可能；一个到期就消失的输出比「要主动关」更难理解；
- * - 内存与句柄本来也不由时间决定：条数由 [`MAX_EXITED_SESSIONS`](#) 兜（8 条，
+ * - 内存与句柄本来也不由时间决定：条数由 [`MAX_EXITED_SESSIONS`](#) 兜（16 条，
  *   单条几百 KB~一两 MB），而「永久」还有一条天然上界——保留是**内存态**，
  *   宿主 / 插件重启即清空，不会跨天累积；
- * - 连续跑很多短命令时，淘汰节奏变成「超过 8 条按最旧淘汰」（`capExited`），
+ * - 连续跑很多短命令时，淘汰节奏变成「超过 16 条按最旧淘汰」（`capExited`），
  *   正是想要的语义：近的才有人读。
  *
  * 需要时间上界的人把这里改成任意毫秒数即可——`reapExited` 那条通路还在
@@ -180,6 +181,24 @@ export declare const EXITED_RETAIN_MS: number;
  * 淘汰一律 `logger.warn` 留痕（见 finishSession），否则这件事在事后完全不可查。
  */
 export declare const MAX_EXITED_SESSIONS = 16;
+/** DSH spawnTerminal 返回 handle 的最小形状（含内部耦合的 terminal 字段）。 */
+interface PtyHandle {
+    pid: number;
+    output: PassThrough;
+    write(data: string): Promise<unknown>;
+    terminate(): Promise<unknown>;
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    /** 内部耦合：DSH 的 LocalTerminalHandle 未暴露 resize/kill，直接透传 node-pty。 */
+    terminal?: {
+        resize?(cols: number, rows: number): void;
+        kill?(signal: string): void;
+    };
+}
+/** 本地 PTY 包装成 TermHandle（resize/kill 仍是透传 node-pty 的内部耦合；防御性降级）。 */
+export declare function wrapLocalPty(handle: PtyHandle): TermHandle;
 /**
  * 本地 PTY 顶层 shell 的 best-effort 强杀（D48）。
  *
@@ -305,6 +324,10 @@ interface TtySession {
     stats: StatsCollector | null;
     /** 采集已永久失败（远端无 /proc、exec 被拒、连接断开）：不再重启，前端隐藏状态条。 */
     statsFailed: boolean;
+    /** 采集失败后的重挂时刻（0 = 没有待重挂）：失败位不再是粘性的（D83）。 */
+    statsRetryAt: number;
+    /** 连续失败次数：退避倍数按它递增，出过帧即归零。 */
+    statsFailures: number;
 }
 interface ReqLike {
     method?: string;
@@ -655,10 +678,24 @@ export declare class TtyServer {
      *     共享一次 df/netstat）；
      *   - SSH：远端 sh + awk 常驻循环，每秒一行 JSON 走**非 PTY** exec channel；
      *     速率类由远端算好，宿主只解析 + 清洗。
-     * 任何失败都静默停表并置 statsFailed（粘性，避免每秒重启）：前端靠「无数据」
-     * 隐藏状态条，PTY 数据路径与终端体验完全不受影响。
+     * 失败时静默停表并置 statsFailed：前端靠「无数据」隐藏状态条，PTY 数据路径与
+     * 终端体验完全不受影响。
+     *
+     * 但失败位**不再粘死整个会话**（D83）：原先置位后永不复位，一次瞬态故障
+     * （sshd MaxSessions 拒绝并发 channel、单通道 ECONNRESET）就让状态条与 agent
+     * tty_stats 在会话余生里彻底没有数据，而主 PTY 通道其实是健康的。现在按指数
+     * 退避自动重挂（出过帧即计数归零），既保住「别每秒重启」的本意，又能自愈。
      */
     private startStats;
+    /**
+     * 采集失败后的退避重挂（D83）。
+     *
+     * 退避而不是立刻重试，是为了保住原先「粘性失败位」想解决的问题——远端平台压根
+     * 没有采集源（macOS/BSD：既无 /proc 也无 PowerShell）时不能每秒重启一个必然失败
+     * 的 channel。指数退避 + 上限把这种「稳态失败」压到几分钟一次，同时让瞬态故障
+     * 在恢复后自动回到有数据状态（出过帧就归零）。
+     */
+    private scheduleStatsRetry;
     /** 停表（幂等）：订阅清零 / 会话结束 / 插件禁用 / 配置关闭都走它。 */
     private stopStats;
     private stopAllStats;

package/lib/index.js

@@ -17,7 +17,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 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 { buildCommandSpawn, buildShellSpawn, commandShellHint, defaultShellPath } from './shell-integration.js';
 import { parseSshConfigDetailed } from './ssh-config.js';
 import { parseKnownHostsDetailed } from './known-hosts.js';
 import { TunnelManager } from './tunnels.js';
@@ -147,10 +147,10 @@ const DEFAULT_RECONNECT_GRACE_SEC = 120;
  *
  * - 时间上界对用户是**第二重惊喜**——「命令跑完 → 下一轮读结果」之间隔着人离开、
  *   模型排队，多久都有可能；一个到期就消失的输出比「要主动关」更难理解；
- * - 内存与句柄本来也不由时间决定：条数由 [`MAX_EXITED_SESSIONS`](#) 兜（8 条，
+ * - 内存与句柄本来也不由时间决定：条数由 [`MAX_EXITED_SESSIONS`](#) 兜（16 条，
  *   单条几百 KB~一两 MB），而「永久」还有一条天然上界——保留是**内存态**，
  *   宿主 / 插件重启即清空，不会跨天累积；
- * - 连续跑很多短命令时，淘汰节奏变成「超过 8 条按最旧淘汰」（`capExited`），
+ * - 连续跑很多短命令时，淘汰节奏变成「超过 16 条按最旧淘汰」（`capExited`），
  *   正是想要的语义：近的才有人读。
  *
  * 需要时间上界的人把这里改成任意毫秒数即可——`reapExited` 那条通路还在
@@ -212,10 +212,37 @@ const TERM_RE = /^[A-Za-z0-9_.+-]+$/;
 const REAPER_INTERVAL_MS = 10_000;
 /** 服务器状态条的采集/推送间隔（mvp 固定 1s，不做配置项）。 */
 const STATS_INTERVAL_MS = 1000;
+/**
+ * 采集失败后的退避重挂：`base × 2^(失败次数-1)`，上限 `MAX`（D83）。
+ *
+ * 上限 5 分钟是给「远端压根没有采集源」那种稳态失败留的——既要重挂（瞬态故障能自愈），
+ * 又不能把必然失败的 channel 重开得太勤。出过帧即计数归零，恢复正常节奏。
+ */
+const STATS_RETRY_BASE_MS = 30_000;
+const STATS_RETRY_MAX_MS = 300_000;
+/**
+ * agent `tty_stats` 一发式远端采样的超时（D84）。
+ *
+ * 原先写死 3s，而这条路径要等**第一帧**：远端 shell 启动 + 脚本首次迭代，Windows
+ * 远端还要算 PowerShell 冷启动 + 多次 WMI 查询——状态条那条推送路径没有这个上限，
+ * 于是出现过「面板有数据、agent tty_stats 每次都报超时」的错位。放宽到 15s：工具
+ * 调用等得起，而写死的小值会把慢首帧误报成「采不到」。
+ */
+const STATS_ONESHOT_TIMEOUT_MS = 15_000;
 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) {
+export function wrapLocalPty(handle) {
     let resizeWarned = false;
+    // D79：README 承诺「DSH 升级若改内部结构会警告一次并退化为固定尺寸」，但老写法是
+    // `handle.terminal?.resize?.(…)` —— `?.` 只在**抛错**时才进 catch，DSH 若把
+    // `handle.terminal` 改名 / 移除（而不是让 resize 抛错），这里既不 resize 也不警告，
+    // 排查时一点线索都没有（承诺成了空头支票）。两种坏法现在都记一条日志。
+    const warnResizeDegraded = (reason) => {
+        if (resizeWarned)
+            return;
+        resizeWarned = true;
+        console.warn('[dsh-tty] resize 透传失败（DSH 内部结构可能已变化，退化为固定尺寸）: ' + reason);
+    };
     return {
         kind: 'local',
         pid: handle.pid,
@@ -223,15 +250,16 @@ function wrapLocalPty(handle) {
         done: handle.done,
         write: (data) => handle.write(data),
         resize: (cols, rows) => {
+            const terminal = handle.terminal;
+            if (terminal === undefined || typeof terminal.resize !== 'function') {
+                warnResizeDegraded('handle.terminal.resize 不存在');
+                return;
+            }
             try {
-                handle.terminal?.resize?.(cols, rows);
+                terminal.resize(cols, rows);
             }
             catch (error) {
-                // DSH 升级若改内部结构，降级为固定尺寸而不是每帧抛错
-                if (!resizeWarned) {
-                    resizeWarned = true;
-                    console.warn('[dsh-tty] resize 透传失败（DSH 内部结构可能已变化，退化为固定尺寸）: ' + String(error?.message ?? error));
-                }
+                warnResizeDegraded(String(error?.message ?? error));
             }
         },
         terminate: () => handle.terminate(),
@@ -522,9 +550,15 @@ const expectCounts = new WeakMap();
  * 整数夹紧（0.19.0）：ws 帧输入零信任——`Number('abc')=NaN`、`-5`、`1.5`、
  * `1e9` 都不能原样透传给 node-pty 的 ioctl 与 xterm-headless（后者曾在
  * resize 帧路径直接炸出未捕获异常）。非法值回落 fallback，范围内取整。
+ *
+ * D79 补的一档（0.22.1）：`null` / `''` / 布尔 / 对象也**不是数字**，但
+ * `Number(null)` = 0、`Number('')` = 0 会通过 isFinite 检查 ⇒ 被夹成下限 2。而客户端
+ * 把 NaN 发成 JSON 时正是 `null`（FitAddon 对游离 / 隐藏容器给 NaN，见
+ * `client-src/fit-size.js`），于是「根本不该发」的尺寸被翻译成「合法的极小尺寸」——
+ * 后台标签的 PTY 就是这么变成 2×2 的。非数值一律与 NaN 同档：回落 fallback。
  */
 function clampInt(value, fallback, min, max) {
-    const n = Number(value);
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : Number.NaN;
     if (!Number.isFinite(n))
         return fallback;
     return Math.min(max, Math.max(min, Math.round(n)));
@@ -1577,8 +1611,13 @@ export class TtyServer {
      *     共享一次 df/netstat）；
      *   - SSH：远端 sh + awk 常驻循环，每秒一行 JSON 走**非 PTY** exec channel；
      *     速率类由远端算好，宿主只解析 + 清洗。
-     * 任何失败都静默停表并置 statsFailed（粘性，避免每秒重启）：前端靠「无数据」
-     * 隐藏状态条，PTY 数据路径与终端体验完全不受影响。
+     * 失败时静默停表并置 statsFailed：前端靠「无数据」隐藏状态条，PTY 数据路径与
+     * 终端体验完全不受影响。
+     *
+     * 但失败位**不再粘死整个会话**（D83）：原先置位后永不复位，一次瞬态故障
+     * （sshd MaxSessions 拒绝并发 channel、单通道 ECONNRESET）就让状态条与 agent
+     * tty_stats 在会话余生里彻底没有数据，而主 PTY 通道其实是健康的。现在按指数
+     * 退避自动重挂（出过帧即计数归零），既保住「别每秒重启」的本意，又能自愈。
      */
     startStats(session) {
         // D77：只读保留态没有进程可采（本地会取到宿主、远端 channel 早断了）——直接不起表
@@ -1619,7 +1658,9 @@ export class TtyServer {
         }
         const statsExec = session.handle.statsExec;
         if (statsExec === undefined) {
+            // 句柄缺失（连接已断等）同样退避重挂，而不是永久放弃（D83）
             session.statsFailed = true;
+            this.scheduleStatsRetry(session);
             return;
         }
         let stopped = false;
@@ -1647,6 +1688,7 @@ export class TtyServer {
                 if (frame === null)
                     return;
                 sawFrame = true;
+                session.statsFailures = 0; // 出过帧：退避计数归零，下次失败从头退避
                 if (hasStatsData(frame))
                     this.sendStats(session, frame);
             }, () => {
@@ -1656,10 +1698,12 @@ export class TtyServer {
                     attempt(buildWindowsStatsCommand(), true);
                     return;
                 }
-                // 读过帧 = 远端采集进程自己停了；一帧未读 = 彻底失败——都停表并置粘性失败位
+                // 读过帧 = 远端采集进程自己停了；一帧未读 = 这一跳没起来——都停表。
+                // D83：置失败位让前端先隐藏状态条，但排一次退避重挂，恢复后自愈
                 session.statsFailed = true;
                 session.stats = null;
                 collector.stop();
+                this.scheduleStatsRetry(session);
             });
         };
         // 先登记再起采集：同步失败（conn.exec 直接抛错）也走同一套收尾
@@ -1668,6 +1712,29 @@ export class TtyServer {
         // 双跳同步失败时 collector.stop() 已把当时在手的句柄停掉；conn.exec 直接抛错的
         // 那一跳压根没建 channel，句柄是惰性的，不需要额外收尾。
     }
+    /**
+     * 采集失败后的退避重挂（D83）。
+     *
+     * 退避而不是立刻重试，是为了保住原先「粘性失败位」想解决的问题——远端平台压根
+     * 没有采集源（macOS/BSD：既无 /proc 也无 PowerShell）时不能每秒重启一个必然失败
+     * 的 channel。指数退避 + 上限把这种「稳态失败」压到几分钟一次，同时让瞬态故障
+     * 在恢复后自动回到有数据状态（出过帧就归零）。
+     */
+    scheduleStatsRetry(session) {
+        if (session.closed || session.exited !== null || !this.statsOn)
+            return;
+        session.statsFailures += 1;
+        const delay = Math.min(STATS_RETRY_BASE_MS * 2 ** (session.statsFailures - 1), STATS_RETRY_MAX_MS);
+        session.statsRetryAt = Date.now() + delay;
+        const timer = setTimeout(() => {
+            session.statsRetryAt = 0;
+            if (session.closed || session.exited !== null || !this.statsOn)
+                return;
+            session.statsFailed = false; // 清位后 startStats 的门禁才放行
+            this.startStats(session);
+        }, delay);
+        timer.unref?.();
+    }
     /** 停表（幂等）：订阅清零 / 会话结束 / 插件禁用 / 配置关闭都走它。 */
     stopStats(session) {
         const collector = session.stats;
@@ -1959,7 +2026,7 @@ export class TtyServer {
                 }
                 resolve(result);
             };
-            const timer = setTimeout(() => { finish({ available: false, reason: '远端采集超时（3s）' }); }, 3000);
+            const timer = setTimeout(() => { finish({ available: false, reason: `远端采集超时（${String(STATS_ONESHOT_TIMEOUT_MS / 1000)}s）` }); }, STATS_ONESHOT_TIMEOUT_MS);
             timer.unref?.();
             try {
                 handle = statsExec(buildRemoteStatsCommand(), (line) => {
@@ -2020,6 +2087,8 @@ export class TtyServer {
             : buildShellSpawn(this.options.shell, this.options.term, this.options.colorTerm, this.options.shellIntegration);
         let tmuxName = null;
         let degraded = false;
+        /** 降级原因：探测**超时**（机器忙）还是确定没装——提示文案必须分开（D80）。 */
+        let degradedInconclusive = false;
         if (wantsPersist) {
             const probe = await probeTmux();
             if (probe.available) {
@@ -2028,7 +2097,8 @@ export class TtyServer {
                 spawnPlan = buildTmuxSpawnPlan({ shell: this.options.shell, term: this.options.term, colorTerm: this.options.colorTerm, tmuxName });
             }
             else {
-                degraded = true; // tmux 不在：降级普通会话，由调用方给灰字提示
+                degraded = true; // 降级普通会话，由调用方给灰字提示；原因（超时/没装）一并带出去
+                degradedInconclusive = probe.inconclusive === true;
             }
         }
         const create = (async () => {
@@ -2076,6 +2146,8 @@ export class TtyServer {
                 lastStats: null,
                 stats: null,
                 statsFailed: false,
+                statsRetryAt: 0,
+                statsFailures: 0,
             };
             // 绑定：有客户端才绑（agent 路径 client === null → 保持空表 = 无客户端会话）。
             // 空表但 owner:'agent'，故不会被孤儿回收器当孤儿收掉。
@@ -2104,7 +2176,7 @@ export class TtyServer {
         const session = await create;
         this.attachOutput(session);
         this.watchDone(session, local);
-        return { session, wantsPersist, degraded };
+        return { session, wantsPersist, degraded, degradedInconclusive };
     }
     /**
      * 立即终止会话：同步退役 + 顶层 shell 直接 SIGKILL，让 done/exit 帧立刻可发；
@@ -2255,7 +2327,12 @@ export class TtyServer {
                 const next = created.session;
                 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';
+                    // 超时与「确定没装」的提示分开（D80）：前者让用户重开一次标签即可（那时
+                    // 机器已经不忙了），后者才需要去装 tmux。原先一律写「未检测到 tmux」，
+                    // 把「机器忙」误报成「没装」，排障方向被带偏。
+                    const notice = created.degradedInconclusive
+                        ? '\x1b[2m[dsh-tty] tmux 探测超时（机器较忙），本标签以普通会话运行；重开一个标签页即可再试持久化\x1b[0m\r\n'
+                        : '\x1b[2m[dsh-tty] 未检测到 tmux，本标签以普通会话运行；安装 tmux 后持久化标签可跨宿主重启恢复现场\x1b[0m\r\n';
                     appendOutput(next, notice);
                     send(ws, { t: 'data', sid, d: notice });
                 }
@@ -2359,6 +2436,8 @@ export class TtyServer {
                         lastStats: null,
                         stats: null,
                         statsFailed: false,
+                        statsRetryAt: 0,
+                        statsFailures: 0,
                     };
                     local.set(sid, next);
                     this.sessions.add(next);
@@ -2414,6 +2493,9 @@ export class TtyServer {
                 }
             }
             else if (msg.t === 'resize') {
+                // D79：`msg.cols/rows` 缺失或非数值（客户端把 NaN 序列化成 `null` 就是这种）时
+                // clampInt 回落 80×24，**不是**夹到下限 2——客户端的门槛在 client-src/fit-size.js，
+                // 这里是防御纵深：旧版本客户端 / 第三方客户端发来的垃圾值不该把 PTY 压成 2×2。
                 const resolved = this.resolveSid(ws, msg, local);
                 if (resolved === undefined || 'unknown' in resolved)
                     return;
@@ -2473,8 +2555,13 @@ export class TtyServer {
                 // tmux 托管、本机清单看不到，从 settings 留存读取）——客户端用它确认
                 // localStorage 里的持久标签规格是否仍可恢复（新窗口/新浏览器）
                 const localTmux = await listTmuxSessions();
-                const tmuxSessions = [...new Set([...localTmux, ...this.options.persistSessions])];
-                send(ws, { t: 'sessions', list: this.sessions.listForAttach(), tmux: tmuxSessions });
+                // 本机清单探不明白（超时）时**整个字段缺席**（D81）：只给 SSH 侧的名字会被
+                // 读成「本机没有持久会话」——正是「失败伪装成确定答案」要避免的
+                send(ws, {
+                    t: 'sessions',
+                    list: this.sessions.listForAttach(),
+                    ...(localTmux !== undefined ? { tmux: [...new Set([...localTmux, ...this.options.persistSessions])] } : {}),
+                });
             }
             else if (msg.t === 'attach') {
                 const raw = msg.sid;
@@ -4141,7 +4228,7 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_open',
-                        description: '开一个新的终端会话（本地 shell，或 `command` 直接跑一条命令，如 dev server）。会话出现在用户的终端面板里、用户可见可接管，长驻进程与 watch 类任务应该用它（不要在 bash 工具里挂起等待）。开了之后用 tty_expect 等就绪信号、tty_capture{last:true} 拿结果；用完用 tty_close 关闭。`command` 按 **shell 语法整体**执行（`cd dir && cmd`、`a; b`、`for …; do …; done` 都可以，D78：旧版本里 `exec` 包装只跑第一条）；**它跑完退出后会话不会立刻消失**：会转成只读保留（留到显式关闭，最多留 8 条），退出前最后的输出与退出码都还能用 tty_capture / tty_screen 读——所以「跑一条会结束的命令、回头再取结果」不需要套一层 `sh`。cwd 缺省为插件配置的工作目录。',
+                        description: '开一个新的终端会话（本地 shell，或 `command` 直接跑一条命令，如 dev server）。会话出现在用户的终端面板里、用户可见可接管，长驻进程与 watch 类任务应该用它（不要在 bash 工具里挂起等待）。开了之后用 tty_expect 等就绪信号、tty_capture{last:true} 拿结果；用完用 tty_close 关闭。`command` 按 **宿主 shell 的语法整段执行**（D78：旧版本里 `exec` 包装只跑第一条）——POSIX shell 上 `cd dir && cmd`、`a; b`、`for …; do …; done` 都可以，**Windows 的 cmd / PowerShell 则按它们自己的语法**（当前执行命令的 shell 与语法见 systemPrompt 里的终端一行）；**它跑完退出后会话不会立刻消失**：会转成只读保留（留到显式关闭，最多留 16 条），退出前最后的输出与退出码都还能用 tty_capture / tty_screen 读——所以「跑一条会结束的命令、回头再取结果」不需要套一层 `sh`。cwd 缺省为插件配置的工作目录。',
                         parameters: {
                             cwd: { type: 'string', description: '工作目录（必须是已存在的绝对路径）；缺省用插件配置的 cwd' },
                             command: { type: 'string', description: '直接执行的命令（非交互）：按**整段 shell 代码**执行，`cd x && cmd`、`a; b`、管道、多行脚本都可以（D78）；给出时不做 tmux 持久化。省略或全空白 = 交互式 shell' },
@@ -4160,7 +4247,7 @@ const plugin = definePlugin({
                             },
                             render: (_args, value) => {
                                 const v = value;
-                                return [{ type: 'text', text: `已开终端会话 sid=${v.sid ?? '?'}${v.persist === true ? '（tmux 持久）' : ''}。它在用户的终端面板里可见；下一步可用 tty_send 执行命令、tty_expect 等就绪信号。` }];
+                                return [{ type: 'text', text: `已开终端会话 sid=${v.sid ?? '?'}${v.persist === true ? '（tmux 持久）' : ''}。它在用户的终端面板里可见；下一步可用 tty_send 执行命令、tty_expect 等就绪信号。\n${commandShellHint(live.shell)}` }];
                             },
                         },
                         async execute(args) {
@@ -4176,7 +4263,7 @@ const plugin = definePlugin({
                     })));
                     activeDisposers.push(tools.register(defineTool({
                         name: 'tty_close',
-                        description: '关闭一个由 tty_open 开的终端会话（结束其中的进程）。**只能关 agent 自己开的会话**：用户在面板里开的标签会被拒绝，请让用户自己在面板里关，不要越权结束用户正在用的终端。对**进程已退出但仍只读保留着**的会话同样可用——那就是它的释放入口（把屏与缓冲还回去）。只读保留默认留到显式关闭（宿主重启也会清空），不按时间释放；同时最多留 8 条，超出按最旧淘汰。',
+                        description: '关闭一个由 tty_open 开的终端会话（结束其中的进程）。**只能关 agent 自己开的会话**：用户在面板里开的标签会被拒绝，请让用户自己在面板里关，不要越权结束用户正在用的终端。对**进程已退出但仍只读保留着**的会话同样可用——那就是它的释放入口（把屏与缓冲还回去）。只读保留默认留到显式关闭（宿主重启也会清空），不按时间释放；同时最多留 16 条，超出按最旧淘汰。',
                         parameters: {
                             sid: { type: 'string', required: true, description: '会话 id（tty_open 或 tty_list 提供）' },
                         },
@@ -5090,16 +5177,19 @@ const plugin = definePlugin({
                         order: 150,
                         text: () => {
                             const list = sessions.list();
+                            // D78 补：本地命令的语法随宿主 shell 变（POSIX / cmd / PowerShell），
+                            // 而「Shell 路径」是热改的配置——所以这行每轮现算，不冻在工具描述里。
+                            const shellLine = commandShellHint(live.shell);
                             if (list.length === 0)
-                                return '当前没有终端面板会话（可用 tty_open 自己开一个，或引导用户打开「终端」面板）。';
+                                return `当前没有终端面板会话（可用 tty_open 自己开一个，或引导用户打开「终端」面板）。\n${shellLine}`;
                             // D77：只读保留态（进程已退出）**不能冒充活会话**——模型会以为那个长驻
                             // 任务还在跑、或者对它发命令。这里把两者分开：活会话逐条列，保留态压成
                             // 一行汇总（每轮 prompt 的增量是常数，不随条数线性膨胀）。
-                            const live = list.filter((s) => s.exited !== true);
+                            const alive = list.filter((s) => s.exited !== true);
                             const gone = list.filter((s) => s.exited === true);
-                            const head = live.length === 0
+                            const head = alive.length === 0
                                 ? '当前没有活着的终端面板会话。'
-                                : '当前活跃的终端面板会话（可用 tty_capture / tty_screen / tty_expect / tty_send 操作，用 tty_open / tty_close 开关，sid 如下）：\n' + live.map((s) => {
+                                : '当前活跃的终端面板会话（可用 tty_capture / tty_screen / tty_expect / tty_send 操作，用 tty_open / tty_close 开关，sid 如下）：\n' + alive.map((s) => {
                                     const where = s.kind === 'ssh' ? `ssh ${s.target}` : `pid=${String(s.pid ?? '?')} cwd=${s.cwd}`;
                                     const owner = s.owner === 'agent' ? ' [agent 开的]' : '';
                                     return `- sid=${s.sid} [${s.kind}]${owner}${s.persist === true ? ' [tmux 持久]' : ''} ${where} (最后活动 ${new Date(s.lastOutputAt).toLocaleTimeString()})`;
@@ -5110,7 +5200,7 @@ const plugin = definePlugin({
                                     const how = s.signal !== undefined ? `signal=${s.signal}` : s.exitCode === undefined ? '退出码未知' : `exitCode=${String(s.exitCode)}`;
                                     return `sid=${s.sid} (${how})`;
                                 }).join('、');
-                            return head + tail;
+                            return head + tail + '\n' + shellLine;
                         },
                     });
                     sectionDisposable = systemPrompt.section({ name: 'plugin:dsh-tty', order: 150, text: TTY_GUIDANCE });