@hyzyn/dsh-tty 0.20.0 → 0.20.2

package/lib/index.js

@@ -12,7 +12,7 @@ import WebSocket, { WebSocketServer } from 'ws';
 // found），必须默认导入后取 Terminal；类型用 InstanceType 别名保持同名可用
 import xtermHeadless from '@xterm/headless';
 const HeadlessTerminal = xtermHeadless.Terminal;
-import { definePlugin, dshHome as resolveDshHome } from '@hyzyn/dsh-kit';
+import { definePlugin, dshHome as resolveDshHome, plainConfig, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { spawnSsh, sshTarget, expandHome, setCredentialResolver } from './ssh.js';
 import { probeSsh } from './probe.js';
@@ -55,30 +55,37 @@ const TUNNEL_SCHEMA = z.object({
     localTargetPort: z.natural().max(65535).default(0),
     enabled: z.boolean().default(true),
 });
-/** 与「插件配置 → 终端面板」卡片表单对齐的 schema。 */
-const TTY_SETTINGS_SCHEMA = z.object({
-    enabled: z.boolean().default(true),
-    announceToAgent: z.boolean().default(true),
-    maxSessions: z.natural().max(16).default(4),
-    shell: z.string().default(''),
-    term: z.string().default('xterm-256color'),
-    colorTerm: z.string().default('truecolor'),
-    cwd: z.string().default(''),
-    reconnectGraceSec: z.natural().max(3600).default(120),
-    sshHosts: z.array(SSH_HOST_SCHEMA).default([]),
-    hostKeys: z.array(HOST_KEY_SCHEMA).default([]),
-    tunnels: z.array(TUNNEL_SCHEMA).default([]),
-    shellIntegration: z.boolean().default(true),
-    sftpStyle: z.union([z.const('dialog'), z.const('dual')]).default('dialog'),
-    persistence: z.union([z.const('off'), z.const('tmux')]).default('off'),
-    endOnPageClose: z.boolean().default(false),
-    statsEnabled: z.boolean().default(true),
+/**
+ * 运行时 Config schema——DSH ≥0.1.7 起同时就是本插件的 settings 存储。
+ *
+ * 全部字段都标 `.volatile()`：它们都是「插件配置 → 终端面板」卡片可改项，而
+ * `settings.update(entryId, patch)` 只接受 volatile 路径；loader 对 volatile-only
+ * 变更原地更新引用并发 `loader/volatile-update`，不重挂插件——插件订阅后走
+ * `applyPatch` 热应用（见 @hyzyn/dsh-kit 的 settingsEntryScope）。
+ */
+export const Config = z.object({
+    enabled: z.boolean().default(true).volatile(),
+    announceToAgent: z.boolean().default(true).volatile(),
+    maxSessions: z.natural().max(16).default(4).volatile(),
+    shell: z.string().default('').volatile(),
+    term: z.string().default('xterm-256color').volatile(),
+    colorTerm: z.string().default('truecolor').volatile(),
+    cwd: z.string().default('').volatile(),
+    reconnectGraceSec: z.natural().max(3600).default(120).volatile(),
+    sshHosts: z.array(SSH_HOST_SCHEMA).default([]).volatile(),
+    hostKeys: z.array(HOST_KEY_SCHEMA).default([]).volatile(),
+    tunnels: z.array(TUNNEL_SCHEMA).default([]).volatile(),
+    shellIntegration: z.boolean().default(true).volatile(),
+    sftpStyle: z.union([z.const('dialog'), z.const('dual')]).default('dialog').volatile(),
+    persistence: z.union([z.const('off'), z.const('tmux')]).default('off').volatile(),
+    endOnPageClose: z.boolean().default(false).volatile(),
+    statsEnabled: z.boolean().default(true).volatile(),
     sftpLimits: z.object({
         maxDownloadMb: z.natural().max(1024 * 1024).default(1024),
         maxUploadMb: z.natural().max(1024 * 1024).default(2048),
         maxUploadFiles: z.natural().max(100000).default(1000),
-    }).default({ maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000 }),
-    persistSessions: z.array(z.object({ tmuxName: z.string() })).default([]),
+    }).default({ maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000 }).volatile(),
+    persistSessions: z.array(z.object({ tmuxName: z.string() })).default([]).volatile(),
 });
 /* ------------------------------------------------------------------ *
  * 常量
@@ -90,6 +97,13 @@ const DEFAULT_RECONNECT_GRACE_SEC = 120;
 /** 下行背压阈值（ws.bufferedAmount 字节）。 */
 const BACKPRESSURE_HIGH = 512 * 1024;
 const BACKPRESSURE_LOW = 128 * 1024;
+/**
+ * 显式 kill 后的 exit 帧兜底（毫秒）。PTY 句柄的 `done` 承诺「恰好 resolve 一次」，
+ * 但个别平台/后端上 forceKill 之后它迟迟不兑现（实测 rc.1 的 subprocess-local 在
+ * Linux 上会卡住），而「发过 kill 就必须收到一条 exit 帧」是前端契约（B1/B3 用例
+ * 钉的就是它）。超时即按 SIGKILL 结案；done 真回来时靠 session.exitSent 幂等忽略。
+ */
+const KILL_EXIT_FALLBACK_MS = 2000;
 const SID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 /** 自定义命令标签（0.14.0）的长度上限：单条命令，防误传超长脚本。 */
 const COMMAND_MAX = 2000;
@@ -179,7 +193,7 @@ function sanitizeTermValue(value, fallback) {
     const trimmed = value.trim();
     return TERM_RE.test(trimmed) ? trimmed : fallback;
 }
-/** 可热更新的运行时配置（settings/updated 动态应用）。 */
+/** 可热更新的运行时配置（loader 的 volatile 更新事件动态应用）。 */
 class LiveConfig {
     shell;
     term;
@@ -803,6 +817,196 @@ function isLoopbackUpgrade(req) {
         return false;
     }
 }
+/* ------------------------------------------------------------------ *
+ * 虚拟屏（xterm-headless）——构造与异常兜底（D57）
+ * ------------------------------------------------------------------ */
+/**
+ * 虚拟屏的 scrollback 余量（D57）。
+ *
+ * **不能是 0。** xterm 的 `Buffer` 在 `scrollback: 0` 时把 `lines.maxLength` 压成
+ * `rows`，但 normal buffer 的 `_hasScrollback` 仍是 true（reflow 照常开启）：输出与
+ * resize（列宽变化触发 reflow）交错时，`lines` 会短于 `ybase + y`，于是
+ * `lineFeed()` 里 `lines.get(ybase + y).isWrapped = false` 命中 `undefined` →
+ * 未捕获 `TypeError: Cannot set properties of undefined (setting 'isWrapped')`。
+ *
+ * 该异常抛在 `WriteBuffer._innerWrite` 的 `setTimeout` 回调里，写入路径的同步
+ * try/catch 结构性拦不住，会直接打死整个宿主进程（线上 `last-failure-web.log`
+ * 的堆栈即此）。
+ *
+ * 关键在 `lines.maxLength`（= rows + scrollback）：`BufferService.scroll` 只在「没满」时
+ * 才 `lines.push` + `ybase++`（成对）。`scrollback: 0` 把 maxLength 钉死成 rows，
+ * 一旦有别的路径把 `ybase` 顶上去（resize 收缩 / reflow），`lines` 长度就再也追不上，
+ * `ybase + y + 1` 越界只是时间问题。留 1 行余量（maxLength = rows + 1）即维持住成对增长：
+ * 同一最小序列 `scrollback: 0` 崩 5/5，`scrollback: 1` 崩 0/5；700 块随机屏压测里
+ * `ybase` 涨到 16 也没再出现越界（见 test/screen-crash.test.ts）。
+ *
+ * 余量不影响 `tty_screen` 读数——它走 `buffer.getLine(row)`（内部 `ybase + row`，
+ * 即视口），多出来的行只在回滚区，不进读数。
+ */
+export const SCREEN_SCROLLBACK = 1;
+/**
+ * 建一块虚拟屏（`tty_screen` 的数据源）；失败降级为 null。
+ *
+ * 导出仅供单测（test/screen-crash.test.ts）钉住构造参数——生产路径是
+ * `SessionManager.createScreen`，它必须与这里同源（就一行委托）。
+ */
+export function createHeadlessScreen(cols, rows) {
+    try {
+        // buffer 命名空间在 xterm 5.x 是提案 API，必须开 allowProposedApi
+        return new HeadlessTerminal({ cols, rows, scrollback: SCREEN_SCROLLBACK, allowProposedApi: true });
+    }
+    catch {
+        return null;
+    }
+}
+/** xterm-headless 的异常都带这个文件名（压缩产物的堆栈里也是它）。 */
+const XTERM_SCREEN_CRASH_RE = /xterm-headless|@xterm\/headless/;
+/** 累计吞掉的虚拟屏异常数（只增不减；排障可见 + 单测断言用）。 */
+let screenCrashTotal = 0;
+/** 读累计吞掉的虚拟屏异常数。 */
+export function xtermScreenCrashCount() {
+    return screenCrashTotal;
+}
+/** 判定未捕获异常是否来自虚拟屏（xterm-headless）。导出仅供单测。 */
+export function isXtermScreenCrash(err) {
+    const stack = err instanceof Error ? (err.stack ?? '') : String(err);
+    return XTERM_SCREEN_CRASH_RE.test(stack);
+}
+/**
+ * 记账并吞掉一个虚拟屏异常；返回 true 表示已吞（非虚拟屏异常返回 false，交回调用方）。
+ * 导出仅供单测。
+ */
+export function swallowXtermScreenCrash(err) {
+    if (!isXtermScreenCrash(err))
+        return false;
+    screenCrashTotal++;
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[dsh-tty] 虚拟屏（xterm-headless）未捕获异常已吞掉，不影响宿主（累计 ${screenCrashTotal} 次）：${message}`);
+    return true;
+}
+let xtermGuardRefs = 0;
+let xtermGuardHandler;
+let xtermGuardRejectionHandler;
+/** 解绑兜底（引用计数归零才真正摘监听器）。 */
+function releaseXtermScreenCrashGuard() {
+    if (xtermGuardRefs === 0)
+        return;
+    if (--xtermGuardRefs > 0)
+        return;
+    if (xtermGuardHandler !== undefined) {
+        process.off('uncaughtException', xtermGuardHandler);
+        xtermGuardHandler = undefined;
+    }
+    if (xtermGuardRejectionHandler !== undefined) {
+        process.off('unhandledRejection', xtermGuardRejectionHandler);
+        xtermGuardRejectionHandler = undefined;
+    }
+}
+/**
+ * 注册进程级虚拟屏异常兜底（D57）：把来自 xterm-headless 的未捕获异常 / 未处理 rejection
+ * 吞掉并记账，让插件自己的 bug 不再拖垮整个 harness。幂等 + 引用计数，返回解绑函数。
+ *
+ * 覆盖两个入口：
+ *   - `uncaughtException`：同步路径（`_innerWrite` 的定时器回调里抛出，见上）；
+ *   - `unhandledRejection`：xterm 的异步 handler（DCS/OSC）rejection 走这里，宿主实测
+ *     **0 处**监听，Node 15+ 下未处理 rejection 直接杀进程。
+ *
+ * 三条边界（刻意如此，不是随手 `process.on`）：
+ *   1. **只吞虚拟屏异常**——`isXtermScreenCrash` 按堆栈判定；其余异常照旧。
+ *   2. **其余异常只在「我们是唯一的监听者」时抛回**：没有本兜底时未捕获异常会让宿主退出，
+ *      抛回保住这个语义；已经有别的监听者（宿主/其它插件）时保持沉默，由它们决定——
+ *      此时抛回反而会抢在别人前面把进程杀掉。
+ *   3. `unhandledRejection` 的「抛回」还有一层必要性：**只要挂了监听器，Node 就不再走
+ *      默认的致命处理**，所以非虚拟屏的 rejection 必须由我们抛出来还原默认行为
+ *      （已实测：抛回后进程照旧 exit 1）。
+ */
+export function installXtermScreenCrashGuard() {
+    if (xtermGuardRefs++ > 0)
+        return releaseXtermScreenCrashGuard;
+    const onUncaught = (err) => {
+        if (swallowXtermScreenCrash(err))
+            return;
+        if (process.listenerCount('uncaughtException') <= 1)
+            throw err;
+    };
+    const onRejection = (reason) => {
+        if (swallowXtermScreenCrash(reason))
+            return;
+        if (process.listenerCount('unhandledRejection') <= 1)
+            throw reason;
+    };
+    xtermGuardHandler = onUncaught;
+    xtermGuardRejectionHandler = onRejection;
+    process.on('uncaughtException', onUncaught);
+    process.on('unhandledRejection', onRejection);
+    return releaseXtermScreenCrashGuard;
+}
+/* ------------------------------------------------------------------ *
+ * 虚拟屏心跳（D57 停摆检测）
+ * ------------------------------------------------------------------ */
+/**
+ * 停摆判定窗口：写出去的数据超过这么久还没解析完，就认定那块屏的解析器已停摆。
+ * 正常屏的解析是毫秒级（回调随 `_innerWrite` 逐批回来），5s 不会误伤。
+ */
+export const SCREEN_STALL_MS = 5000;
+/** 退役原因①：写队列超限 / 尺寸非法导致的同步抛出。 */
+export const SCREEN_DOWN_WRITE_REJECTED = '写入被拒（写队列超限或尺寸非法）';
+/** 退役原因②：解析器停摆（超时窗口内没有任何一批数据被解析完）。 */
+export const SCREEN_DOWN_STALLED = '解析停摆（xterm 在超时窗口内未回调）';
+/** 建一份空心跳。 */
+export function newScreenHeartbeat() {
+    return { inflight: 0, watchdog: null, lastParseAt: 0 };
+}
+/** 摘掉看门狗（会话结束 / 屏退役时调用，避免定时器在会话死后误报）。 */
+export function clearScreenWatchdog(heartbeat) {
+    if (heartbeat.watchdog !== null) {
+        clearTimeout(heartbeat.watchdog);
+        heartbeat.watchdog = null;
+    }
+}
+/**
+ * 写一帧到虚拟屏，并维护停摆看门狗（D57）。
+ *
+ * **为什么需要心跳**：xterm 的解析在 `WriteBuffer._innerWrite` 的 setTimeout 回调里跑，
+ * 异常被进程级兜底吞掉之后，那块屏的解析器**永久停摆**——出错的那批数据留在写队列里、
+ * `_bufferOffset` 不前进，而 `write()` 只在队列**空**时才重新调度解析。后果：`tty_screen`
+ * 一直返回**冻结的旧画面**（agent 会据此行事），写队列还会一路堆到 5e7 字符上限。
+ * 心跳把这种屏识别出来退役，`tty_screen` 改为如实报「虚拟屏不可用」。
+ *
+ * 信号用 `write(data, cb)` 的回调（xterm 解析完这批数据才回调）：停摆时回调永远不来 →
+ * `inflight` 不归零 → 看门狗判定。**不能用 `onWriteParsed` 事件**——它在 5.5.0 不是
+ * 公开 API（`Terminal` 只暴露 onBell/onBinary/onCursorMove/onData/onLineFeed/onResize/
+ * onScroll/onTitleChange）。
+ */
+export function writeToScreen(screen, heartbeat, text, onStall, stallMs = SCREEN_STALL_MS) {
+    heartbeat.inflight++;
+    try {
+        screen.write(text, () => {
+            heartbeat.inflight = Math.max(0, heartbeat.inflight - 1);
+            heartbeat.lastParseAt = Date.now();
+            if (heartbeat.inflight === 0)
+                clearScreenWatchdog(heartbeat);
+        });
+    }
+    catch {
+        // 同步抛出（写队列超限 5e7 / 尺寸非法）：屏已不可用，立刻判定停摆
+        heartbeat.inflight = Math.max(0, heartbeat.inflight - 1);
+        onStall(SCREEN_DOWN_WRITE_REJECTED);
+        return;
+    }
+    if (heartbeat.watchdog === null) {
+        const armedAt = Date.now();
+        heartbeat.watchdog = setTimeout(() => {
+            heartbeat.watchdog = null;
+            // 停摆要**双条件**：还有批次没解析完，且整个窗口内**毫无**解析进展。
+            // 只看 inflight 会误杀连续输出的健康屏——看门狗按首次写入武装、5s 后到期时，
+            // 活跃会话几乎总有在途批次（实测：6s 连续输出误判 1 次，见 DEFECTS D57）。
+            if (heartbeat.inflight > 0 && heartbeat.lastParseAt < armedAt)
+                onStall(SCREEN_DOWN_STALLED);
+        }, stallMs);
+        heartbeat.watchdog.unref?.();
+    }
+}
 /* ------------------------------------------------------------------ *
  * 会话管理
  * ------------------------------------------------------------------ */
@@ -881,6 +1085,7 @@ export class SessionManager {
     retire(session) {
         session.closed = true;
         this.sessions.delete(session.id);
+        clearScreenWatchdog(session.screenHeartbeat);
         try {
             session.screen?.dispose();
         }
@@ -928,6 +1133,7 @@ export class SessionManager {
         this.sessions.clear();
         await Promise.all(all.map((session) => {
             session.closed = true;
+            clearScreenWatchdog(session.screenHeartbeat);
             try {
                 session.screen?.dispose();
             }
@@ -955,6 +1161,8 @@ export class TtyServer {
     pendingTmux = new Map();
     /** 已接线的面板连接（sessions 帧广播用；比 wss.clients 更贴合「面板」语义，单测也可驱动）。 */
     panels = new Set();
+    /** 会话 → 它所属连接的 sid 映射（kill 兜底结案时要从本地表里摘除）。 */
+    sessionLocals = new WeakMap();
     /** WS 闸门（插件禁用时关闭）：拒绝新升级 + 断开存量连接。 */
     wsGateOpen = true;
     /** 服务器状态条总开关（配置热生效；关闭时停掉全部采集，重开按订阅恢复）。 */
@@ -1479,6 +1687,8 @@ export class TtyServer {
                 buffer: '',
                 decoder: new StringDecoder('utf8'),
                 screen: this.createScreen(clampInt(cols, 80, 2, 500), clampInt(rows, 24, 2, 200)),
+                screenHeartbeat: newScreenHeartbeat(),
+                screenDownReason: null,
                 orphanedAt: null,
                 shellState: createShellState(),
                 pendingOutput: '',
@@ -1551,16 +1761,38 @@ export class TtyServer {
             /* 已退出 */
         }
         void forceKill(session.handle);
+        // 兜底：handle.done 不兑现时也要按「用户已 kill」结案（见 KILL_EXIT_FALLBACK_MS）。
+        const timer = setTimeout(() => {
+            this.finishSession(session, { exitCode: null, signal: 'SIGKILL' });
+        }, KILL_EXIT_FALLBACK_MS);
+        timer.unref?.();
     }
-    /** 每会话一块虚拟屏（xterm-headless）：tty_screen 的数据源；失败降级为 null。 */
+    /** 每会话一块虚拟屏（xterm-headless）：tty_screen 的数据源；失败降级为 null。
+     *  构造参数在 createHeadlessScreen（D57：scrollback 不能是 0），这里只做委托。 */
     createScreen(cols, rows) {
+        return createHeadlessScreen(cols, rows);
+    }
+    /**
+     * 退役一块**不可用**的虚拟屏（D57）：解析停摆或写队列满时调用。
+     *
+     * 只摘虚拟屏，**不动会话**——PTY 还活着、浏览器面板照常收发（虚拟屏只是 `tty_screen`
+     * 的数据源）。退役后 `tty_screen` 会如实报「虚拟屏不可用（原因）」，而不是返回冻结的
+     * 旧画面让 agent 据此行事。
+     */
+    dropScreen(session, reason) {
+        if (session.screen === null)
+            return;
+        const screen = session.screen;
+        session.screen = null;
+        session.screenDownReason = reason;
+        clearScreenWatchdog(session.screenHeartbeat);
         try {
-            // buffer 命名空间在 xterm 5.x 是提案 API，必须开 allowProposedApi
-            return new HeadlessTerminal({ cols, rows, scrollback: 0, allowProposedApi: true });
+            screen.dispose();
         }
         catch {
-            return null;
+            /* 已释放 */
         }
+        console.warn(`[dsh-tty] 虚拟屏已退役（${reason}），会话 ${session.id} 的 tty_screen 将报不可用；PTY 与前端不受影响`);
     }
     async handleMessage(ws, msg, local, cleanupAll, conn) {
         try {
@@ -1723,6 +1955,8 @@ export class TtyServer {
                         buffer: '',
                         decoder: new StringDecoder('utf8'),
                         screen: this.createScreen(clampInt(msg.cols, 80, 2, 500), clampInt(msg.rows, 24, 2, 200)),
+                        screenHeartbeat: newScreenHeartbeat(),
+                        screenDownReason: null,
                         orphanedAt: null,
                         shellState: createShellState(),
                         pendingOutput: '',
@@ -1915,33 +2149,42 @@ export class TtyServer {
     }
     /** 会话退出事实 → exit 帧（恰好一次；本地 PTY 与 SSH 共用）。 */
     watchDone(session, local) {
+        this.sessionLocals.set(session, local);
         session.handle.done.then((outcome) => {
-            // kill 主动关闭时会话可能已被移出 local，用 exitSent 保证 exit 帧恰好一次；
-            // 发送走 session.ws 动态取值——attach 换连接后 exit 也能跟着新连接走
-            if (session.exitSent === true)
-                return;
-            session.exitSent = true;
-            session.closed = true;
-            session.statsSubs.clear();
-            this.stopStats(session);
-            local.delete(session.id);
-            this.sessions.remove(session.id);
-            if (session.kind === 'ssh' && session.tmuxName !== null)
-                this.trackPersist(session.tmuxName, false);
-            try {
-                session.screen?.dispose();
-            }
-            catch {
-                /* 已释放 */
-            }
-            this.flushPendingOutput(session); // exit 前冲掉合并窗口里的尾巴，保序
-            // exit 广播到所有绑定连接（跨窗口共享），各客户端按自己的 sid 收址
-            for (const client of session.clients.values()) {
-                send(client.ws, { t: 'exit', sid: client.sid, code: outcome.exitCode, signal: outcome.signal });
-            }
-            session.clients.clear();
+            this.finishSession(session, outcome);
         }).catch(() => { });
     }
+    /**
+     * 会话终局的**唯一出口**：退役 + 清理 + 给所有绑定连接发 exit 帧（恰好一次）。
+     *
+     * `outcome` 正常来自 PTY 句柄的 done；显式 kill 的兜底（KILL_EXIT_FALLBACK_MS）
+     * 也走这里，带 code=null / signal=SIGKILL。exit 广播到所有绑定连接（跨窗口共享），
+     * 各客户端按自己的 sid 收址。
+     */
+    finishSession(session, outcome) {
+        if (session.exitSent === true)
+            return;
+        session.exitSent = true;
+        session.closed = true;
+        session.statsSubs.clear();
+        this.stopStats(session);
+        this.sessionLocals.get(session)?.delete(session.id);
+        this.sessions.remove(session.id);
+        if (session.kind === 'ssh' && session.tmuxName !== null)
+            this.trackPersist(session.tmuxName, false);
+        clearScreenWatchdog(session.screenHeartbeat);
+        try {
+            session.screen?.dispose();
+        }
+        catch {
+            /* 已释放 */
+        }
+        this.flushPendingOutput(session); // exit 前冲掉合并窗口里的尾巴，保序
+        for (const client of session.clients.values()) {
+            send(client.ws, { t: 'exit', sid: client.sid, code: outcome.exitCode, signal: outcome.signal });
+        }
+        session.clients.clear();
+    }
     /** 输出下行 + 基于 ws.bufferedAmount 的背压（暂停/恢复 PassThrough）。 */
     attachOutput(session) {
         const output = session.handle.output;
@@ -1978,11 +2221,12 @@ export class TtyServer {
             session.lastOutputAt = Date.now();
             session.buffer = tailFromSafeBoundary(session.buffer + text, BUFFER_CAP);
             feedShellIntegration(session, text);
-            try {
-                session.screen?.write(text);
-            }
-            catch {
-                /* 虚拟屏异常不阻断输出链路 */
+            const screen = session.screen;
+            if (screen !== null) {
+                // 心跳包裹（D57）：同步抛出 / 解析停摆的屏会被退役，而不是让 tty_screen 一直返回冻结画面
+                writeToScreen(screen, session.screenHeartbeat, text, (reason) => {
+                    this.dropScreen(session, reason);
+                });
             }
             if (session.clients.size === 0)
                 return; // 孤儿会话：仅积累缓冲，等待重连 attach 回放
@@ -2341,7 +2585,9 @@ const plugin = definePlugin({
     // 声明 inject：tools 服务只有声明式 inject 才能解析（动态 ctx.inject/ctx.get
     // 均拿不到，实测 mcp-client 同款模式），声明后 ctx.get('tools') 才能取到。
     inject: ['tools'],
-    apply(ctx, config) {
+    apply(ctx, rawConfig) {
+        // volatile 字段解析后是 `{ get() }` 引用，先还原成纯数据（见 @hyzyn/dsh-kit 的 plainConfig）。
+        const config = plainConfig((rawConfig ?? {}));
         if (config?.enabled === false)
             return;
         const live = new LiveConfig({
@@ -2433,7 +2679,7 @@ const plugin = definePlugin({
              */
             platform: process.platform,
         });
-        /** 规范化并应用一份配置补丁（settings/updated 事件与 HTTP POST 共用；幂等）。 */
+        /** 规范化并应用一份配置补丁（volatile 更新事件与 HTTP POST 共用；幂等）。 */
         const applyPatch = (section) => {
             live.apply({
                 shell: typeof section.shell === 'string' ? section.shell : undefined,
@@ -2653,8 +2899,8 @@ const plugin = definePlugin({
                         const scope = settingsScope;
                         if (scope !== undefined) {
                             try {
-                                // 官方持久化通道：写入 settings 命名空间（dsh-settings-file），
-                                // 成功后触发 settings/updated → applyPatch 热应用
+                                // 官方持久化通道：settings.update(entryId) 写进本插件 entry 的 profile
+                                // patch（volatile 字段），成功后 loader 发 volatile 更新 → applyPatch 热应用
                                 await scope.update(patch);
                             }
                             catch (error) {
@@ -3119,11 +3365,16 @@ const plugin = definePlugin({
                 };
             }, 'dsh-tty: web routes');
         });
-        // settings 命名空间：注册 + 启动合并持久化值 + settings/updated 热应用
+        // settings：DSH ≥0.1.7 起存储就是本插件 entry 的 Config（导出为 `Config`，可写字段
+        // 标了 volatile）。启动合并一次持久化值，之后由 loader 的 volatile 更新事件热应用。
         ctx.inject(['settings'], (settingsCtx) => {
             settingsCtx.effect(() => {
-                const settings = settingsCtx.settings;
-                const scope = settings.register('tty', TTY_SETTINGS_SCHEMA);
+                const scope = settingsEntryScope(settingsCtx, 'tty');
+                // 服务形态不符（老宿主 / 最小宿主）时不装 scope：卡片仍可看快照，只是不持久化。
+                if (scope === undefined)
+                    return () => { };
+                // 卡片是自定义页（plugins.row.config），别再让 DSH 为本 entry 自动生成一份。
+                const offAutoPage = suppressAutoSettingsPage(settingsCtx, ctx);
                 settingsScope = scope;
                 // 启动合并：字符串字段非空才覆盖；maxSessions/布尔用「非默认值才覆盖」启发式
                 //（schema 默认值会混入 resolved，无法区分「显式保存的 4」与「从未保存」）。
@@ -3168,14 +3419,10 @@ const plugin = definePlugin({
                     startup.tunnels = storedTunnels;
                 if (Object.keys(startup).length > 0)
                     applyPatch(startup);
-                const events = settingsCtx;
-                const off = events.events.on('settings/updated', (ns, next) => {
-                    if (ns !== 'tty' || typeof next !== 'object' || next === null)
-                        return;
-                    applyPatch(next);
-                });
+                const off = scope.onChanged(() => applyPatch(scope.get()));
                 return () => {
                     off();
+                    offAutoPage();
                     settingsScope = undefined;
                 };
             }, 'dsh-tty: settings');
@@ -3470,8 +3717,11 @@ const plugin = definePlugin({
                             if (session === undefined || session.closed)
                                 throw new Error(`会话不存在或已退出: ${input.sid}`);
                             const screen = session.screen;
-                            if (screen === null)
-                                throw new Error(`虚拟屏不可用: ${input.sid}`);
+                            if (screen === null) {
+                                // D57：屏可能被退役（解析停摆 / 写队列满）——如实报原因，别让 agent 以为只是没开
+                                const why = session.screenDownReason === null ? '' : `（${session.screenDownReason}）`;
+                                throw new Error(`虚拟屏不可用: ${input.sid}${why}`);
+                            }
                             const buffer = screen.buffer.active;
                             const lines = [];
                             for (let row = 0; row < screen.rows; row++) {
@@ -4110,6 +4360,10 @@ const plugin = definePlugin({
         }, REAPER_INTERVAL_MS);
         reaperTimer.unref?.();
         ctx.effect(() => () => clearInterval(reaperTimer), 'dsh-tty: orphan reaper');
+        // 虚拟屏异常兜底（D57）：xterm-headless 的解析跑在 WriteBuffer 的 setTimeout
+        // 回调里，写入路径的同步 try/catch 结构性拦不住；没有兜底时任何一处虚拟屏异常
+        // 都会直接打死宿主进程（Web GUI 掉线、会话表清空、agent 全丢）。插件卸载时摘掉。
+        ctx.effect(() => installXtermScreenCrashGuard(), 'dsh-tty: xterm crash guard');
         // 插件卸载时回收全部会话、隧道与 SFTP 连接
         ctx.effect(() => {
             return () => {