@xiaoqiong0v0/opencode-ssh-tool 0.6.11 → 0.6.14

package/dist/server.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { WebSocketServer, WebSocket } from "ws";
 import { listAllSessions, removeSessionState } from "./session-store.js";
 import { tr } from "./i18n.js";
-import { PTY_COLS, PTY_ROWS } from "./constants.js";
+import { PTY_COLS, PTY_ROWS, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HEARTBEAT_CLIENT_TIMEOUT_MS, STATUS_PUSH_DEBOUNCE_MS, STATUS_PUSH_FALLBACK_MS, ORPHAN_STATE_GRACE_MS, ORPHAN_STATE_MIN_AGE_MS, } from "./constants.js";
 import log, { infoDedup } from "./log.js";
 const PAGE_KEYS = [
     "web_title",
@@ -19,7 +19,6 @@ const PAGE_KEYS = [
     "web_local",
     "web_delete_terminal",
     "web_cmd_placeholder",
-    "web_send_ctrlc",
     "web_raw",
 ];
 const JS_I18N_KEYS = {
@@ -29,9 +28,12 @@ const JS_I18N_KEYS = {
     local: "web_local",
     terminals: "web_terminals",
     cmdPlaceholder: "web_cmd_placeholder",
-    sendCtrlC: "web_send_ctrlc",
+    directInput: "web_direct_input",
+    inputOn: "web_input_on",
+    inputOff: "web_input_off",
+    inputDisconnected: "web_input_disconnected",
+    inputOffline: "web_input_offline",
 };
-const STATUS_PUSH_MS = 2000;
 const sessionKey = (sid, name) => `${sid}:${name}`;
 /**
  * 会话键（`sid:name`）转日志显示形式（`sid/name`）：与终端侧 `[busy]`/`[run]` 行同一写法，
@@ -47,8 +49,33 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
     let actualPort = port;
     const webDir = join(dirname(fileURLToPath(import.meta.url)), "web");
     const pageTemplate = readTemplate(webDir);
+    /** 服务启动时刻（孤儿状态文件清理的启动宽限基准，见 ORPHAN_STATE_GRACE_MS） */
+    const serverStartedAt = Date.now();
+    /**
+     * 本服务是否绑定在固定端口（port>0）。
+     * port=0 表示每个 opencode 实例各自起一个随机端口服务，本服务只能看见连到自己的 agent，
+     * "无已连 agent 认领"无法区分孤儿与**别的实例正在使用的活会话**，故磁盘孤儿清理不安全（见 sweepOrphanStateFiles）。
+     */
+    const isFixedPortServer = port !== 0;
     const agents = new Map();
     const agentBySession = new Map();
+    /** 当前是否存在 agent 连接（边沿状态，供 notifyAgentPresence 去重） */
+    let agentPresent = false;
+    /** "存在 agent 连接"边沿的订阅者（server-entry 用于事件驱动空闲关闭） */
+    const presenceListeners = [];
+    /** 在 agents 集合发生"空 ↔ 非空"翻转时通知订阅者（无翻转则不发） */
+    const notifyAgentPresence = () => {
+        const present = agents.size > 0;
+        if (present === agentPresent)
+            return;
+        agentPresent = present;
+        for (const cb of presenceListeners) {
+            try {
+                cb(present);
+            }
+            catch { /* 订阅回调异常不影响服务 */ }
+        }
+    };
     const streamBuf = new Map();
     const rawBuf = new Map();
     const cmdCount = new Map();
@@ -56,6 +83,12 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
     const seqHold = new Set();
     /** server 侧各终端最近一次的对外 busy 状态（仅用于日志：翻转时记一行） */
     const busyState = new Map();
+    /**
+     * 各 key 是否已处于"无 agent 连接且命令未完成"的 fallback 状态（仅用于日志：**边沿触发**）。
+     * buildSessions 由状态事件驱动（及低频兜底）被调用，故用 per-key 上一轮状态做**幂等**判定：
+     * 仅在进入该状态（首转 fallback）与离开该状态（agent 重连 / 命令收尾）各记一行，稳定期间不记。
+     */
+    const fallbackState = new Set();
     /**
      * 记录 server 侧 busy 翻转（仅在值变化时输出一行，带 session/终端/原因）：
      * 与终端侧 [busy] 行互补，便于对齐"server 认为忙/闲"的时间线。
@@ -80,7 +113,8 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
         }
         if (path === "/") {
             const html = renderPage(lang, pageTemplate);
-            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            // 不缓存：页面内联的 __I18N__ 由本进程注入，若被浏览器缓存会在 server 重启后与磁盘上的 app.js 版本错配
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
             res.end(html);
             return;
         }
@@ -108,6 +142,91 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
     const subscribersOf = (sid, name) => {
         return [...wss.clients].filter((c) => c.readyState === WebSocket.OPEN && c._sub?.sid === sid && c._sub?.name === name);
     };
+    /**
+     * 收到客户端应用层 pong：清除"等待应答"标记与超时定时器（心跳闭环）。
+     * @param ws 收到 pong 的连接
+     */
+    const markPong = (ws) => {
+        ws._awaitPong = false;
+        if (ws._pongTimer) {
+            clearTimeout(ws._pongTimer);
+            ws._pongTimer = undefined;
+        }
+    };
+    /** 所有已连 agent 认领的会话键并集（多实例：任一实例认领即视为有主） */
+    const claimedByAnyAgent = () => {
+        const claimed = new Set();
+        for (const set of agents.values())
+            for (const k of set)
+                claimed.add(k);
+        return claimed;
+    };
+    /**
+     * 清理"无任何已连 agent 认领"的**磁盘状态文件**：
+     * 正常关闭会调 removeSessionState 删文件，残留即属主进程异常退出（或进程退出兜底未清理）留下的孤儿；
+     * 其 connected=true/busy=true 不会自愈——旧实现只在 2s 轮询里读，故会长期误报"在线/忙"，
+     * 还会让 server-entry 的"无连接空闲自动关闭"永不触发。只删状态文件，**不动 history 目录**（离线历史仍可查看）。
+     * 保守优先：
+     * - **仅固定端口（port>0）服务执行**：port=0 时每实例各起一个服务（默认 config），本服务的"未认领"无法
+     *   区分孤儿与别的实例正在使用的活会话；且状态文件 updatedAt 不随空闲刷新，"陈旧"判据同样区分不了
+     *   → 直接跳过，宁可不清理也不删活数据（内存运行态回收在 cleanupOrphanRuntime 内照常执行，不受影响）；
+     * - 无 agent 代表（agents.size===0）时跳过——没有可信的"当前认领"视图，不判断；
+     * - 服务启动不足 ORPHAN_STATE_GRACE_MS 时跳过——给存量 agent 重连、注册的窗口，防误删活进程文件；
+     * - 仅清理 updatedAt 早于 ORPHAN_STATE_MIN_AGE_MS 的文件——避免误删刚写入、agent 尚未注册的文件。
+     * @param claimed 所有已连 agent 认领的会话键并集
+     */
+    const sweepOrphanStateFiles = (claimed) => {
+        if (!isFixedPortServer)
+            return;
+        if (agents.size === 0)
+            return;
+        if (Date.now() - serverStartedAt < ORPHAN_STATE_GRACE_MS)
+            return;
+        const now = Date.now();
+        const stale = listAllSessions(dir).filter((s) => {
+            if (claimed.has(sessionKey(s.sessionID, s.name)))
+                return false;
+            return now - (s.updatedAt ?? 0) > ORPHAN_STATE_MIN_AGE_MS;
+        });
+        if (!stale.length)
+            return;
+        for (const s of stale)
+            removeSessionState(dir, s.sessionID, s.name);
+        infoDedup(`orphan-state:${stale.map((s) => sessionKey(s.sessionID, s.name)).sort().join(",")}`, `清理无 agent 认领的孤儿状态文件 ${stale.length} 个: ${stale.map((s) => keyTag(sessionKey(s.sessionID, s.name))).join(", ")}`);
+    };
+    /**
+     * 清理"无任何已连 agent 认领"的终端运行态（僵尸条目）：
+     * agent 断开后其运行态（streamBuf 的 done=false / rawBuf / 排队保持等）若无人接管会永久滞留，
+     * 导致 busy 恒为 ⏳、[fallback] 长期存在、离线终端仍被当成"运行中"。
+     * 多实例安全：只回收**所有已连 agent 都没认领**的 key——任一实例注册时都可安全回收孤儿；
+     * 仍被本实例或其它实例认领的条目一律不动。history 落盘历史**不删**（仅供离线查看）。
+     * 同时（同一注册时机）清理无人认领的**状态文件**（见 sweepOrphanStateFiles），不留孤儿文件。
+     */
+    const cleanupOrphanRuntime = () => {
+        const claimed = claimedByAnyAgent();
+        const orphans = [];
+        for (const k of streamBuf.keys())
+            if (!claimed.has(k))
+                orphans.push(k);
+        for (const k of rawBuf.keys())
+            if (!claimed.has(k) && !orphans.includes(k))
+                orphans.push(k);
+        for (const k of seqHold)
+            if (!claimed.has(k) && !orphans.includes(k))
+                orphans.push(k);
+        for (const k of orphans) {
+            streamBuf.delete(k);
+            rawBuf.delete(k);
+            seqHold.delete(k);
+            cmdCount.delete(k);
+            busyState.delete(k);
+            fallbackState.delete(k);
+        }
+        if (orphans.length) {
+            infoDedup(`orphan-runtime:${orphans.slice().sort().join(",")}`, `清理无 agent 认领的运行态 ${orphans.length} 个: ${orphans.map(keyTag).join(", ")}`);
+        }
+        sweepOrphanStateFiles(claimed);
+    };
     const buildSessions = () => {
         const states = listAllSessions(dir);
         // 补：state 文件可能被清理（重启/断线），但 history 目录仍在——扫描发现离线历史终端
@@ -154,25 +273,45 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
         // 等待期间无输出，但 agent 仍在、命令未完成，busy 必须保持 true。
         // 命令真实结束只认 agent 上报的当前 seq 完成标记（cmdDone），会话拆除路径另算。
         for (const [key, b] of streamBuf) {
-            if (b && !b.done && !agentBySession.has(key)) {
-                infoDedup(`agent-offline:${key}`, `[fallback] ${keyTag(key)} 无 agent 连接：命令状态未知（保持未完成，不判完成/不发 diff done）command=${JSON.stringify((b.command ?? "").slice(0, 120))} ts=${b.ts}`);
+            const inFallback = !!b && !b.done && !agentBySession.has(key);
+            if (inFallback && !fallbackState.has(key)) {
+                fallbackState.add(key);
+                // 边沿触发：仅在首次转入"无 agent 且未完成"时记一行（不含命令内容，防敏感载荷落盘）
+                log.info(`[fallback] ${keyTag(key)} 无 agent 连接：命令状态未知（保持未完成，不判完成/不发 diff done）ts=${b.ts}`);
+            }
+            else if (!inFallback && fallbackState.has(key)) {
+                fallbackState.delete(key);
+                // 恢复：agent 重连（重新注册并补播 cmdStart）或命令被收尾，各记一行后回到稳定态不再记
+                const reason = agentBySession.has(key) ? "agent 重连" : b?.done ? "命令已收尾" : "状态已恢复";
+                log.info(`[fallback] ${keyTag(key)} 恢复：${reason}（退出"无 agent 且未完成"状态）`);
             }
             if (!agentBySession.has(key))
                 seqHold.delete(key); // agent 已消失：清排队序列 busy 保持
             liveBusy.set(key, (!!b && !b.done) || seqHold.has(key));
         }
+        // 清理已从 streamBuf 移除的 key（删除终端 / 缓冲回收）的 fallback 状态，避免同名 key 复用时漏记首次
+        for (const k of fallbackState)
+            if (!streamBuf.has(k))
+                fallbackState.delete(k);
         for (const s of states) {
-            if (s.connected && !liveKey.has(sessionKey(s.sessionID, s.name))) {
+            const lk = sessionKey(s.sessionID, s.name);
+            const online = liveKey.has(lk);
+            if (s.connected && !online) {
                 s.connected = false;
             }
-            const lk = sessionKey(s.sessionID, s.name);
             const busy = liveBusy.get(lk);
             if (busy !== undefined)
                 s.busy = busy;
-            // 盲点显式化：拿不到 agent/实时流状态时，busy 回退取状态文件（可能是命令执行前写的旧值，未必可靠）
+            // 无 agent 连接 = 终端离线：busy 归零，不回退状态文件（进程异常退出时那里可能残留 busy=true，
+            // 会让离线终端一直显示 ⏳）。离线用既有 ○ 表达，不再叠加"忙"。
+            else if (!online) {
+                s.busy = false;
+                logBusy(lk, false, "无 agent 连接(离线)");
+            }
+            // 盲点显式化：agent 在线但拿不到实时流状态时，busy 回退取状态文件（可能是命令执行前写的旧值，未必可靠）
             else
                 logBusy(lk, !!s.busy, "状态文件回退(无 agent 状态)");
-            seen.add(sessionKey(s.sessionID, s.name));
+            seen.add(lk);
         }
         const bySession = new Map();
         for (const s of states) {
@@ -253,6 +392,49 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
         const sep = key.indexOf(":");
         return [key.slice(0, sep), key.slice(sep + 1)];
     };
+    /**
+     * 注册时的运行态对账（修复"断线丢 cmdDone → server 内存僵尸 busy"）：
+     * agent 注册时上报"本进程认领的全部终端"（register.sessions）与"其中真正在运行命令的子集"（register.running）。
+     * 对**本 agent 认领、但不在运行子集内**的终端，把 server 仍标记 done=false 的残留流收尾
+     * （置 done、广播 diff done、busy 归 false）——这正是"命令在 agent 断线期间完成、cmdDone 发往已死 socket 而丢失"的僵尸。
+     * 只在对账可确定时收尾：register 未携带 running（旧 agent / agent 自身无法确定）时**不臆测**，
+     * 仅记一行"未能对账"后保持现状（宁可保留僵尸，也不误判在线命令已完成）。
+     * @param claimKeys 本 agent 本次认领的会话键集合
+     * @param runningRaw register 消息里的 running 字段（未知类型，需运行时校验）
+     */
+    const reconcileAgentRuntime = (claimKeys, runningRaw) => {
+        if (!Array.isArray(runningRaw)) {
+            log.info(`[reconcile] agent 注册未携带运行集合（未能对账），保持现状不臆测（认领 ${claimKeys.size} 个终端）`);
+            return;
+        }
+        const running = new Set();
+        for (const r of runningRaw) {
+            if (r && typeof r.sessionID === "string" && typeof r.name === "string")
+                running.add(sessionKey(r.sessionID, r.name));
+        }
+        let finalized = 0;
+        for (const k of claimKeys) {
+            if (running.has(k))
+                continue; // 确在运行：保留 busy（agent 紧随其后的 cmdStart 会补播命令文本）
+            const b = streamBuf.get(k);
+            if (b && !b.done) {
+                b.done = true;
+                b.endTs = b.endTs ?? Date.now();
+                logBusy(k, false, "register 对账(cmdDone 丢失)");
+                finalizeCommand(k);
+                finalized++;
+                continue;
+            }
+            if (seqHold.has(k)) {
+                // 排队保持也一并放开：其最后一条 cmdDone 同样可能随断线丢失，否则 busy 仍会被 hold 住
+                seqHold.delete(k);
+                logBusy(k, false, "register 对账(队列保持释放)");
+                finalized++;
+            }
+        }
+        if (finalized)
+            log.info(`[reconcile] agent 注册对账收尾 ${finalized} 个终端（认领但未运行，cmdDone 丢失）`);
+    };
     /** 广播 sessions（json 变化去重；busy 翻转必然变化） */
     const pushSessions = () => {
         const payload = buildSessions();
@@ -266,7 +448,57 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
             send(client, { type: "sessions", ...payload });
         }
     };
-    const statusTimer = setInterval(() => { pushSessions(); }, STATUS_PUSH_MS);
+    /** 状态推送合并定时器（事件驱动的去抖合并；null=空闲无待推） */
+    let statusPushTimer = null;
+    /**
+     * 请求一次状态推送（去抖合并）：所有**状态变化事件**（cmdStart/cmdDone/exec/busy 翻转/连接变化/会话增删/客户端拉取）
+     * 调用它，窗口内多次只推一次全量最新状态。不变化时不推（pushSessions 内按 json 逐客户端去重）。
+     */
+    const requestStatusPush = () => {
+        if (statusPushTimer !== null)
+            return;
+        statusPushTimer = setTimeout(() => {
+            statusPushTimer = null;
+            pushSessions();
+        }, STATUS_PUSH_DEBOUNCE_MS);
+    };
+    // 兜底：事件驱动已覆盖服务端内存态的全部变化；此低频周期只兜底**带外变化**（其他进程写入状态文件
+    // 导致的新终端 / pending / 标题变化等，服务端无对应事件），保证这类变化最长 STATUS_PUSH_FALLBACK_MS 内可达前端。
+    const statusFallbackTimer = setInterval(() => { pushSessions(); }, STATUS_PUSH_FALLBACK_MS);
+    /**
+     * 应用层心跳（server 侧）：每隔 HEARTBEAT_INTERVAL_MS 向每条连接下发 {type:"ping"}，
+     * 并在 HEARTBEAT_TIMEOUT_MS 内未收到 pong 时 terminate。server↔agent、server↔browser 两条 WS 共用：
+     * terminate 后对端 close 事件触发既有自动重连，把"半开连接"变成可发现、可自愈。
+     * 心跳只在 WS 通道收发，不写 PTY/终端。
+     */
+    const heartbeatTimer = setInterval(() => {
+        for (const ws of wss.clients) {
+            if (ws.readyState !== WebSocket.OPEN)
+                continue;
+            if (ws._awaitPong) {
+                // 上一条 ping 既没等到 pong、超时定时器也未生效（兜底路径）：判定半开，直接断开
+                log.info(`[heartbeat] 心跳无应答（兜底）断开连接 agent=${!!agents.get(ws)}`);
+                try {
+                    ws.terminate();
+                }
+                catch { /* 已关闭 */ }
+                continue;
+            }
+            ws._awaitPong = true;
+            send(ws, { type: "ping" });
+            ws._pongTimer = setTimeout(() => {
+                if (!ws._awaitPong)
+                    return;
+                log.info(`[heartbeat] 心跳超时 ${HEARTBEAT_TIMEOUT_MS}ms 无 pong，断开连接 agent=${!!agents.get(ws)}`);
+                try {
+                    ws.terminate();
+                }
+                catch { /* 已关闭 */ }
+            }, HEARTBEAT_TIMEOUT_MS);
+            if (typeof ws._pongTimer.unref === "function")
+                ws._pongTimer.unref();
+        }
+    }, HEARTBEAT_INTERVAL_MS);
     wss.on("connection", (ws) => {
         ws.on("message", (raw) => {
             let msg;
@@ -287,16 +519,23 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 for (const old of agents.get(ws) ?? [])
                     agentBySession.delete(old);
                 agents.set(ws, new Set());
+                const claimKeys = new Set();
                 for (const s of sessions) {
                     const k = sessionKey(s.sessionID, s.name);
                     agents.get(ws).add(k);
                     agentBySession.set(k, ws);
+                    claimKeys.add(k);
                 }
+                notifyAgentPresence();
                 {
                     // 记录 agent 上报的会话列表（批量实例注册同一列表时按内容去重），便于对齐 server 侧视角
                     const keys = [...(agents.get(ws) ?? [])];
                     infoDedup(`agent-register:${keys.slice().sort().join(",")}`, `agent 注册 ${keys.length} 个会话: ${keys.length ? keys.map(keyTag).join(", ") : "无"}`);
                 }
+                // 运行态对账：先按本 agent 上报的"运行子集"收尾断线丢 cmdDone 的僵尸 busy，再回收无人认领的运行态与状态文件
+                reconcileAgentRuntime(claimKeys, msg.running);
+                cleanupOrphanRuntime();
+                requestStatusPush();
                 return;
             }
             if (t === "cmdStart") {
@@ -322,7 +561,7 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                     c._txPos = 0;
                     send(c, { type: "diff", sessionID: sid, name, event: "cmd", command, ts: streamBuf.get(k).ts });
                 }
-                pushSessions();
+                requestStatusPush();
                 return;
             }
             if (t === "out") {
@@ -391,7 +630,7 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 }
                 logBusy(k, msg.more === true, msg.more === true ? "cmdDone(more 保持 busy)" : "cmdDone");
                 finalizeCommand(k);
-                pushSessions();
+                requestStatusPush();
                 return;
             }
             if (t === "raw") {
@@ -428,6 +667,17 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 return;
             }
             // ===== web 请求 =====
+            if (t === "list") {
+                // web 连接/重连后主动拉取一次会话列表（原依赖 2s 轮询被动收；改事件驱动后必须显式响应，
+                // 否则新开标签页要等兜底周期才有内容）。只回本连接，并按 json 去重。
+                const payload = buildSessions();
+                const json = JSON.stringify(payload);
+                if (json !== ws._lastSessionsJson) {
+                    ws._lastSessionsJson = json;
+                    send(ws, { type: "sessions", ...payload });
+                }
+                return;
+            }
             if (t === "subscribe") {
                 const sid = typeof msg.sessionID === "string" ? msg.sessionID : "";
                 const name = typeof msg.name === "string" ? msg.name : "";
@@ -501,8 +751,9 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 ws._mode = undefined;
                 return;
             }
-            if (t === "ping") {
-                send(ws, { type: "pong" });
+            // 应用层心跳应答：客户端收到 server 的 {type:"ping"} 后回 {type:"pong"}，闭环即可
+            if (t === "pong") {
+                markPong(ws);
                 return;
             }
             if (t === "exec") {
@@ -521,7 +772,7 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 const existing = streamBuf.get(k);
                 streamBuf.set(k, { data: existing && existing.done ? "" : existing?.data ?? "", done: false, ts: Date.now(), command });
                 logBusy(k, true, "exec");
-                pushSessions();
+                requestStatusPush();
                 send(agent, { type: "run-exec", reqId: `${sid}:${name}:${Date.now()}`, sessionID: sid, name, command });
                 return;
             }
@@ -541,9 +792,17 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 const name = typeof msg.name === "string" ? msg.name : "";
                 if (!sid || !name)
                     return;
-                const agent = agentBySession.get(sessionKey(sid, name));
-                if (agent)
-                    send(agent, { type: "run-delete", sessionID: sid, name });
+                const k = sessionKey(sid, name);
+                const agent = agentBySession.get(k);
+                // 归属校验：仅当本服务**已被该 key 的 agent 认领**（agentBySession 内有此 key，即 agents 集合含它）
+                // 时才允许删盘上状态文件与 history 目录。port:0 多实例下每实例各起一个服务，未认领的 key 极可能
+                // 属于**别的 opencode 实例正在使用的活会话**，无条件删会 rmSync 掉别人的历史目录
+                // （本模块唯一真·数据丢失路径）→ 未认领一律拒绝删除并留一行日志便于排查。
+                if (!agent) {
+                    log.info(`Web 页删除终端 ${sid}/${name} 被拒：本服务未认领该终端（无 agent 归属），跳过删除以免误删他实例数据`);
+                    return;
+                }
+                send(agent, { type: "run-delete", sessionID: sid, name });
                 removeSessionState(dir, sid, name);
                 // 删除该终端的 history 目录：buildSessions 会按 history 目录兜底列出离线历史终端，
                 // 只删 state 文件不清目录会导致"删除后页面仍在"（残留被兜底扫描重新发现）
@@ -556,11 +815,15 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 rawBuf.delete(sessionKey(sid, name));
                 busyState.delete(sessionKey(sid, name));
                 log.info(`Web 页删除终端 ${sid}/${name}`);
-                pushSessions();
+                requestStatusPush();
                 return;
             }
         });
         ws.on("close", () => {
+            if (ws._pongTimer) {
+                clearTimeout(ws._pongTimer);
+                ws._pongTimer = undefined;
+            }
             const reg = agents.get(ws);
             if (reg) {
                 // 盲点显式化：agent 断开时记录受影响的终端列表（仅 agent 连接，web 订阅者不在此列）
@@ -569,6 +832,10 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                     agentBySession.delete(k);
                 agents.delete(ws);
                 infoDedup(`agent-disconnect:${keys.slice().sort().join(",")}`, `agent 断开（受影响终端: ${keys.length ? keys.map(keyTag).join(", ") : "无"}）`);
+                // 连接变化是状态事件：立即推一次（原靠 2s 轮询，最坏 2s 才反映离线；改事件驱动后即时）；
+                // 同时通知"agent 存在性"边沿（server-entry 据最后一个 agent 断开启动空闲计时）
+                notifyAgentPresence();
+                requestStatusPush();
             }
         });
     });
@@ -582,7 +849,24 @@ export function startServer(port, _getSessions, dir, lang = "en", _streamTickMs
                 server,
                 port: actualPort,
                 url: `http://127.0.0.1:${actualPort}`,
-                close: () => { clearInterval(statusTimer); server.close(); wss.close(); },
+                close: () => {
+                    if (statusPushTimer) {
+                        clearTimeout(statusPushTimer);
+                        statusPushTimer = null;
+                    }
+                    clearInterval(statusFallbackTimer);
+                    clearInterval(heartbeatTimer);
+                    server.close();
+                    wss.close();
+                },
+                onAgentPresence: (cb) => {
+                    presenceListeners.push(cb);
+                    // 立即回报一次当前状态：订阅方（server-entry）据此决定是否已空闲（无 agent）
+                    try {
+                        cb(agents.size > 0);
+                    }
+                    catch { /* 订阅回调异常不影响服务 */ }
+                },
             });
         });
     });
@@ -600,6 +884,8 @@ function renderPage(lang, template) {
     out = out.replaceAll("__I18N_JSON__", JSON.stringify(i18nObj));
     out = out.replaceAll("__PTY_COLS_VAL__", String(PTY_COLS));
     out = out.replaceAll("__PTY_ROWS_VAL__", String(PTY_ROWS));
+    out = out.replaceAll("__HEARTBEAT_INTERVAL_MS_VAL__", String(HEARTBEAT_INTERVAL_MS));
+    out = out.replaceAll("__HEARTBEAT_CLIENT_TIMEOUT_MS_VAL__", String(HEARTBEAT_CLIENT_TIMEOUT_MS));
     return out;
 }
 function readTemplate(webDir) {
@@ -638,7 +924,8 @@ function serveStatic(res, webDir, rel) {
         return;
     }
     const ext = extname(file).toLowerCase();
-    res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream" });
+    // 不缓存：静态资源（app.js/app.css）无哈希文件名，缓存会与页面注入的 __I18N__ 版本错配
+    res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream", "Cache-Control": "no-store" });
     res.end(readFileSync(file));
 }
 function readHistoryFromFile(dir, sessionID, name) {