dsh-clean-desktop-shell 0.1.12 → 0.1.13

package/CONTRIBUTORS.md

@@ -7,6 +7,12 @@ maintainer does not use daily.
 
 - **Icather** — Windows side, plugin architecture, backend lifecycle, CI setup.
 
+## Contributors
+
+- **[@lispv](https://github.com/lispv)** — DSH 0.1.2 launch-token authentication on plugin cold start (the host half mints the process's launch URL and hands it to Electron), the desktop titlebar inset contract, preserving loaded pages during backend outages, and the macOS titlebar drag-strip hit area. His commit authorships are preserved in the merged history (#5, #6).
+- **[@lzd-loostone](https://github.com/lzd-loostone)** — capturing the full launch-token URL instead of only host:port, so a shell-started backend stops landing on the 401 page (#4).
+- **[@e16a](https://github.com/e16a)** — the issue that pinned the black-window root cause precisely (the dropped `?token=` and `probe()` scoring a 401 as healthy); the fix followed that diagnosis directly (#2).
+
 ## Looking for help
 
 - **macOS maintainer / co-developer**: validate the .dmg install flow,

package/README.en.md

@@ -46,29 +46,32 @@ No terminal, no commands. **Double-click the desktop shortcut and the DSH window
 
 The tray **shows the backend state in real time** (running / starting / stopped / error) with one-click controls:
 
-- **Live monitoring**: the window keeps probing the backend; the moment it is killed, crashes or is stopped, the window flips to the offline screen — a stale page never fakes "still alive"
-- **Auto-reconnect**: the instant the backend recovers, the window reloads the real page by itself
+- **Responsiveness monitoring**: the probe timeout remains 1,500 ms. A failed response is not a process exit: transient and persistent failures retain the loaded page and show a connection notice.
+- **In-page recovery**: HTTP and client-runtime state are combined, and the client's own connection service resumes synchronization without automatic reloads. Automatic retries use the existing 4-second watch; manual retries share its duplicate-request guards.
 - **Quick start/stop**: one-click start / restart / stop from the tray (with progress dialogs); "stop backend" really shuts the service down on 3080, including externally started instances
 
 ## Usage
 
 1. If the plugin is installed, launching `dsh` from the command line pops up the desktop window automatically; you can also double-click the desktop shortcut created by the plugin — on par with a native desktop app.
 2. Everything from the original web UI works as-is.
-3. Detailed settings live in the tray right-click menu. The main window adds no controls of its own, keeping the page clean.
+3. Detailed settings live in the tray right-click menu. The original page remains unchanged while connected; connection failures show a recovery notice.
 
-**All backend controls live in the tray** — the main window stays a pure shell:
+**Backend lifecycle controls live in the tray**:
 
 - Start / restart / stop the backend (with progress dialogs; stopping really shuts down the service on 3080, including externally started instances)
 - Auto-detect backend · set the backend install folder (auto-detect default)
 - Reload window · create desktop shortcut · check for updates · repo homepage
 
-**Window reliability (Edge-style instant refresh):**
+**Window reliability (non-destructive connection recovery):**
 
 - Shows immediately on launch, never waits for the backend
-- While the backend is down, a local "backend offline" screen is shown and re-probed; the real page loads automatically the moment it answers
-- The instant the backend stops (tray stop, kill or crash) the window flips back to the offline screen — a stale page never fakes "still alive"
+- When no usable page exists at startup, the local offline screen remains until backend startup is ready
+- Only a confirmed managed-child exit or an explicit stop of an identified backend switches back to the offline screen; an unreachable external backend remains a responsiveness failure
+- Persistent failures offer retry and explicit page reload; reloading can discard unsaved page state
 - The offline screen has self-service buttons: reload / start backend / auto-detect backend / set backend install folder
 
+The shell does not recreate the loaded document after probe failures, but third-party plugins may still change their own views when handling disconnection. Confirmed exits and explicit reloads still leave the current page.
+
 ## macOS status (v0.1.7 important note)
 
 v0.1.7 fixes the plugin-mode bug where the shell could not locate `Electron.app`
@@ -124,6 +127,67 @@ and both can be avoided entirely by setting `DSH_SHELL_ELECTRON_DIR`.
 The unsigned-installer warnings (Windows SmartScreen, macOS Gatekeeper) come from
 the **absence of a code-signing certificate**, not from any of the above.
 
+## Compatibility & runtime bounds
+
+The "high capability" rating comes from the four capabilities listed above (files, network,
+commands, credentials). Compatibility ranges, dependencies, external services and failure
+bounds are declared below for human review — **a declaration is not an acceptance run**, so
+every row names its evidence.
+
+### Compatibility ranges
+
+| Item | Declaration | Basis |
+|:--|:--|:--|
+| Node.js | `>=20.0.0` (`engines.node`) | The host half uses global `fetch` and `AbortSignal.timeout`; the Electron half runs on Electron 33's embedded Node 20.18. Nothing newer is required. |
+| DSH | `>=0.1.1 <0.2.0` (`dsh.compatibility.dsh`) | Targets the 0.1.x plugin contract. Before 0.1.2 there is no BrowserAuth, and the host half has an explicit guard for that generation (it still launches the window, just without a bootstrap URL). |
+
+`dsh.compatibility.dshReleases` records the tested status per release:
+
+| DSH version | Status | Evidence |
+|:--|:--|:--|
+| `0.1.5-rc.1` | `compatible` | Real end-to-end: launch-token banner → plugin auto-launches the shell → the window renders the UI and stores a `dsh-auth` cookie; keep-page-on-outage and offline-screen-on-confirmed-exit both pass |
+| `0.1.5-rc.2`, `0.1.5-alpha.2` | `unknown` | No runtime acceptance run |
+| `0.1.1-rc.2` | `unknown` | The "pre-0.1.2" code path is asserted separately (real host module against a connection without `authenticatedUrl`), but no full acceptance run on that release |
+
+### Dependencies & lifecycle scripts
+
+| Kind | Content |
+|:--|:--|
+| Runtime deps | `electron-updater` (tray "check for updates"), `semver` (version comparison). Both are used in the Electron half only; **the host half loads no third-party dependency**. |
+| Peer dep | `@deepseek-ai/dsh` (optional) — the host is provided by DSH, never installed with this package. |
+| Dev deps | `electron`, `electron-builder`, `sharp`, `png-to-ico` (build and icon generation only). |
+| Lifecycle scripts | **None.** This package declares no `preinstall` / `install` / `postinstall` / `prepare`; `scripts` holds only manual entries (`build` / `check` / `dev` / `icons` / `pack`). |
+| Install-script exception | `pnpm.allowScripts` allows `electron`'s own postinstall (it downloads the Electron binary). That is a **dependency's** script, not this package's, and only appears when dev dependencies are installed. |
+
+### External services
+
+| Endpoint | When | Failure behaviour |
+|:--|:--|:--|
+| `github.com` / `npmmirror.com` | First-time Electron runtime provisioning; two sources race with a 3 s timeout (~100 MB) | Both fail → the window does not start, and `<DSH_HOME>/desktop-shell-launch.log` records the platform, the raw error and alternatives |
+| `github.com` (rcedit) | First-time taskbar-icon patch on the runtime exe (~1.3 MB) | Capped at 20 s for the fetch and 25 s for the whole step; a timeout only costs the custom icon — **never the window** — and the next launch retries |
+| `api.github.com` | Tray "check for updates" / auto-update | Fails silently; nothing else is affected |
+| Anything else | None. No uploads, no conversation data, no telemetry. | — |
+
+### Failure bounds
+
+- **Backend will not start**: the offline screen is shown and re-probed every 2.5 s; it loads the moment the backend answers.
+- **Backend drops**: the loaded page is kept with an in-page notice (no reload, no lost drafts); only a confirmed process exit or an explicit stop swaps in the offline screen.
+- **Not Windows**: the taskbar-icon patch is skipped outright (first line of `patchExeIcon` is an `isWin` check).
+- **`dsh` CLI not found**: point the tray at the folder, or set `DSH_BACKEND_DIR`.
+
+### Disposable-profile acceptance record
+
+A full install / start / uninstall cycle in a clean throwaway DSH home and profile
+(**never the daily profile**), DSH `0.1.5-rc.1`, Windows 11:
+
+| Step | Command | Result |
+|:--|:--|:--|
+| Install | `dsh plugin --profile web add file:<repo>` | exit 0 (pnpm 2.2 s); the plugin entry appears in `--dump-config` |
+| Start | `dsh web --no-open` | launch-token banner printed; bare `/` → 401, with token → 303 + `Set-Cookie: dsh-auth-…`, with cookie → 200; the index manifest contains `dsh-clean-desktop-shell/client.js` (plugin mounted in the front end) |
+| Plugin launches the window | same run | The host half completed every step: `inject(['connection'])` fired → `webServer` resolved → launch URL minted → `launchShell()` called (asserted point by point with a temporary probe). **Window visibility was not accepted on this machine**: the acceptance host is a GPU-less CI-style sandbox where Electron exits with `FATAL: GPU process isn't usable` — unrelated to this plugin (a blank Electron app with no GPU flags exits there too, and `--in-process-gpu` makes it work). Window rendering itself was verified separately with a GPU-flagged harness. |
+| Uninstall | `dsh plugin --profile web remove dsh-clean-desktop-shell` | exit 0 (pnpm 1.4 s); plugin entries in `--dump-config` drop to zero |
+| Rollback | Uninstall is the rollback: `dsh.profile.bundles` and `dependencies` are updated together, and backend/window behaviour returns to the uninstalled state | — |
+
 ## Install
 
 **Option 1: download the installer from Releases (for a standalone desktop app)**
@@ -229,8 +293,25 @@ npm run dev     # launch the shell (dev mode)
 npm run pack    # package NSIS (Win) / DMG (mac)
 ```
 
+`npm run check` runs syntax and Node self-checks. Running `scripts/selftest-recovery.mjs` with Electron additionally checks retry after a real spawn failure, burst retries, and immediate-failure feedback; use `--user-data-dir` with a temporary directory.
+
+The following sh/bash example expects `ELECTRON` to name an already installed Electron executable. It uses isolated user-data, does not launch the daily application, and does not send a model request:
+
+```sh
+test -n "$ELECTRON" && "$ELECTRON" --user-data-dir="$(mktemp -d)" scripts/selftest-recovery.mjs
+```
+
+This entry exercises recovery boundaries using a temporary non-executable file and a local page on an ephemeral port; it is not a substitute for real-session or performance acceptance.
+
 ## Changelog
 
+### 0.1.13
+- Fixed a first launch that could stay windowless for minutes: the taskbar-icon patch (rcedit) reused the generic 600 s download budget, so a slow GitHub could hold the window back for ten minutes. It now has its own 20 s cap plus a 25 s deadline for the whole step, and runs in parallel with the Electron runtime download — a miss only costs the custom icon, never the window.
+- Declared compatibility ranges explicitly (`engines.node: ">=20.0.0"` and `dsh.compatibility` with per-release status), plus dependencies, lifecycle scripts (none), external services, failure bounds and a disposable-profile install / start / uninstall record — meeting the DSH STORE listing contract.
+- A slow backend response no longer navigates away to the offline screen: the loaded page is preserved and an in-page notice is shown, so drafts, scroll position and selection survive.
+- Probe observations are separated from confirmed exits: only a real process exit or an explicit stop counts as the backend going down, and the probe keeps its 1,500 ms timeout.
+- Real client connection state and the runtime's own reconnect action are bridged in (`shellAPI.connectionReport` / `onReconnectRequest`): a live HTTP port can no longer hide a dead page WebSocket, and manual plus automatic retries share one guard so an immediate failure cannot feed a reconnect loop.
+
 ### 0.1.12
 - **DSH 0.1.2 BrowserAuth compatibility, plugin form included**: on plugin cold start the host defers-injects the Connection service and, after the Loader tree settles, mints this process's launch URL for Electron — first entry completes the `?token=` → Cookie exchange automatically, no manual backend restart. Until now only a shell-started backend could obtain a token; the plugin form (`dsh web` auto-launching the shell) and "start `dsh web` yourself, then open the shell" both stayed on the unauthenticated page.
 - Electron-managed backend (start / restart) keeps the stdout launch-URL bootstrap: it matches the `dsh web:` banner strictly and keeps the whole `?token=` (loopback only — the token is a local-process secret), with a fallback parse for pre-0.1.2 bare URLs so those no longer degrade into a startup timeout; an externally running backend is never restarted or killed on its own.

package/README.md

@@ -46,29 +46,32 @@
 
 托盘**实时显示后端状态**（运行中 / 启动中 / 未运行 / 错误），一键启停：
 
-- **活性监测**：窗口持续探测后端；后端一旦被杀、崩溃或手动关闭，窗口立刻切到离线页，绝不停在旧页面假装还活着
-- **自动重连**：后端恢复的一刻，窗口自动加载回真实页面，无需手动刷新
+- **响应监测**：保留 1,500 ms 探测超时。响应失败不等于进程退出：短暂或持续失败都保留已加载页面，只显示连接提示。
+- **原页重连**：结合 HTTP 与客户端连接状态，通过客户端自身的连接服务恢复同步，不自动重载。自动重试沿用 4 秒探测节奏；手动重试共用防重复请求检查。
 - **快捷启停**：托盘右键一键启动 / 重启 / 关闭后端（带进度弹窗）；「关闭后端」真正停掉 3080 端口上的服务，含外部启动的实例
 
 ## 使用
 
 1. 若安装过插件，命令行启动 `dsh` 自动弹出桌面窗口；也可通过插件创建的桌面快捷方式双击，媲美原生桌面端的体验。
 2. 使用原网页端的一切功能。
-3. 托盘右键可以进行详细设置。主窗口不添加任何控件，保持页面纯净。
+3. 托盘右键可以进行详细设置。正常连接时保持原网页；连接异常时显示恢复提示。
 
-**后端的一切操作都在托盘右键**，主窗口保持纯壳：
+**后端启停等管理操作在托盘右键**：
 
 - 启动 / 重启 / 关闭后端（带进度弹窗；关闭会真正停掉 3080 上的服务，包括外部启动的实例）
 - 自动探测后端 · 设置后端安装文件夹（默认自动探测定位）
 - 刷新窗口 · 创建桌面快捷方式 · 检查更新 · 仓库主页
 
-**窗口的可靠性（Edge 式即时刷新）**：
+**窗口的可靠性（保留页面的连接恢复）**：
 
 - 双击启动立即出窗，不等后端就绪
-- 后端没起来时显示「后端未连接」页，自动探测；后端一通立即加载
-- 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
+- 启动时尚无可用页面，显示「后端未连接」页；后端启动就绪后加载
+- 只有确认自管进程退出或明确停止已识别的后端，才切回离线页；外部后端失联仍按响应故障提示
+- 持续故障提供「立即重试」与「重新加载页面」；后者是会丢失未保存页面状态的显式操作
 - 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
 
+壳不会因探测失败重建已加载文档，但第三方插件自身的断线处理仍可能改变其局部视图。确认退出与显式重载仍会离开当前页面。
+
 ## macOS 状态（v0.1.7 重要说明）
 
 v0.1.7 修复了插件形态在 macOS 上无法定位 `Electron.app` 路径的问题（该 bug 导致窗口在 Mac 上完全静默失败）。
@@ -105,6 +108,63 @@ v0.1.7 修复了插件形态在 macOS 上无法定位 `Electron.app` 路径的
 
 安装包的未签名警告（Windows SmartScreen、macOS Gatekeeper）来自**缺少代码签名证书**，与上述行为无关。
 
+## 兼容性与运行边界
+
+扫描器给出的「高能力」评级来自上一节那四类能力（文件 / 网络 / 命令 / 凭据）。下面把兼容范围、依赖、外部服务与失败边界摊开声明，供人工审阅——**声明不等于验收**，逐条注明证据。
+
+### 兼容范围
+
+| 项 | 声明 | 依据 |
+|:--|:--|:--|
+| Node.js | `>=20.0.0`（`engines.node`） | host 半边用全局 `fetch` 与 `AbortSignal.timeout`；Electron 半边跑在 Electron 33 内嵌的 Node 20.18 上。没有更新 API 的依赖。 |
+| DSH | `>=0.1.1 <0.2.0`（`dsh.compatibility.dsh`） | 面向 0.1.x 的插件契约；0.1.2 之前没有 BrowserAuth，host 半边对该代有显式守卫（拿不到 `authenticatedUrl()` 时照常拉起窗口，只是不带 bootstrap URL）。 |
+
+`dsh.compatibility.dshReleases` 逐版本标注实测状态：
+
+| DSH 版本 | 状态 | 证据 |
+|:--|:--|:--|
+| `0.1.5-rc.1` | `compatible` | 真机端到端：token 横幅 → 插件自动弹壳 → 窗口渲染 UI 并写入 `dsh-auth` cookie；掉线保留页面、确认退出切离线页均实测通过 |
+| `0.1.5-rc.2`、`0.1.5-alpha.2` | `unknown` | 未做运行验收 |
+| `0.1.1-rc.2` | `unknown` | 「0.1.2 之前」这条代码路径有独立断言（真实 host 模块 + 无 `authenticatedUrl` 的 connection），但没在真实该版本上跑完整验收 |
+
+### 依赖与生命周期脚本
+
+| 类型 | 内容 |
+|:--|:--|
+| 运行时依赖 | `electron-updater`（托盘「检查更新」）、`semver`（版本比较）。两者都只在 Electron 半边使用；**host 半边不加载任何第三方依赖**。 |
+| peer 依赖 | `@deepseek-ai/dsh`（可选）——宿主由 DSH 提供，不随本包安装。 |
+| 开发依赖 | `electron`、`electron-builder`、`sharp`、`png-to-ico`（仅构建与图标生成）。 |
+| 生命周期脚本 | **无。** 本包不声明 `preinstall` / `install` / `postinstall` / `prepare`；`scripts` 只有 `build` / `check` / `dev` / `icons` / `pack` 这些手动入口。 |
+| 安装期脚本例外 | `pnpm.allowScripts` 放行了 `electron` 自身的 postinstall（它要下载 Electron 二进制）。这是**依赖的**脚本、不是本包的，且只在装开发依赖时出现。 |
+
+### 外部服务
+
+| 端点 | 何时访问 | 失败后果 |
+|:--|:--|:--|
+| `github.com` / `npmmirror.com` | 首次准备 Electron 运行时，两源 3 秒竞速下载（约 100MB） | 两源都失败 → 窗口不启动，并写入 `<DSH_HOME>/desktop-shell-launch.log`（含平台、错误原文与替代方案） |
+| `github.com`（rcedit） | 首次给 runtime exe 打任务栏图标（约 1.3MB） | 下载限时 20 秒、整步限时 25 秒，超时只损失自定义图标，**不影响出窗**；下次启动重试 |
+| `api.github.com` | 托盘「检查更新」/ 自动更新 | 静默失败，不影响使用 |
+| 其他 | 无。不上传数据、不读会话内容、无遥测。 | — |
+
+### 失败边界
+
+- **后端起不来**：显示离线页并每 2.5 秒重探，后端一通立即加载。
+- **后端掉线**：保留已加载页面 + 页内提示（不重载、不丢草稿）；只有确认进程退出或用户主动停止才切离线页。
+- **非 Windows**：任务栏图标补丁直接跳过（`patchExeIcon` 首行 `isWin` 判断）。
+- **找不到 `dsh` CLI**：托盘「设置后端文件夹」手动指定，或设 `DSH_BACKEND_DIR`。
+
+### 一次性 Profile 验收记录
+
+在一台干净的一次性 DSH home + 一次性 profile 上跑完整安装 / 启动 / 卸载循环（**不触碰日常 profile**），DSH `0.1.5-rc.1`、Windows 11：
+
+| 步骤 | 命令 | 结果 |
+|:--|:--|:--|
+| 安装 | `dsh plugin --profile web add file:<repo>` | 退出码 0（pnpm 2.2s）；`--dump-config` 出现插件条目 |
+| 启动 | `dsh web --no-open` | 打印 launch token 横幅；裸 `/` → 401、带 token → 303 + `Set-Cookie: dsh-auth-…`、带 cookie → 200；首页 manifest 含 `dsh-clean-desktop-shell/client.js`（插件在前端已挂载） |
+| 插件拉起窗口 | 同上 | host 半边完整走通：`inject(['connection'])` 触发 → `webServer` 可解析 → 铸出 launch URL → `launchShell()` 被调用（用临时探针逐点断言）。**窗口是否可见未在本环境验收**：验收机是 CI 式无 GPU 沙箱，Electron 报 `FATAL: GPU process isn't usable` 后退出，与本插件无关（同一台机器上不带任何 GPU 参数的空白 Electron 应用同样退出，带 `--in-process-gpu` 则正常）。窗口渲染本身在此前用带 GPU 参数的 harness 单独验证过。 |
+| 卸载 | `dsh plugin --profile web remove dsh-clean-desktop-shell` | 退出码 0（pnpm 1.4s）；`--dump-config` 中插件条目归零 |
+| 回滚 | 卸载即回滚：`dsh.profile.bundles` 与 `dependencies` 同步移除，后端与窗口行为回到未安装状态 | — |
+
 ## 安装
 
 **方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
@@ -210,8 +270,25 @@ npm run dev     # 启动壳（开发模式）
 npm run pack    # 打包 NSIS (Win) / DMG (mac)
 ```
 
+`npm run check` 运行语法和 Node 自检。用 Electron 运行 `scripts/selftest-recovery.mjs` 还会验证真实启动失败后的重试、连续手动重试及即时失败不会形成重连循环；建议通过 `--user-data-dir` 指定临时目录。
+
+以下为 sh/bash 示例；`ELECTRON` 指向预先安装的 Electron 可执行文件。用独立 user-data 目录运行，不启动日常应用、不发送模型请求：
+
+```sh
+test -n "$ELECTRON" && "$ELECTRON" --user-data-dir="$(mktemp -d)" scripts/selftest-recovery.mjs
+```
+
+该入口使用临时无执行权限文件与随机端口的本地页面验证恢复边界；不是完整真实会话或性能验收的替代品。
+
 ## 更新历史
 
+### 0.1.13
+- 修复首次启动可能长时间不出窗：任务栏图标补丁（rcedit）此前沿用通用下载预算（600 秒），GitHub 慢时能把窗口拖到十分钟才出现。现在它单独限时 20 秒、整步另有 25 秒硬上限，并与 Electron 运行时下载并行；超时只损失自定义图标，不再影响出窗。
+- 显式声明兼容范围：`engines.node: ">=20.0.0"` 与 `dsh.compatibility`（含逐版本实测状态），并补齐依赖、生命周期脚本（无）、外部服务、失败边界与一次性 profile 的安装 / 启动 / 卸载验收记录——满足 DSH STORE 的上架契约。
+- 后端响应超时不再直接跳离线页：改为页内提示并保留已加载页面，草稿/滚动/选中状态不受影响。
+- 区分「探测结果」与「确认退出」：只有进程真的退出或用户主动停止才算后端下线，探测超时不再被当成退出；探测超时保留 1,500 ms。
+- 接入真实客户端连接状态与重连入口（`shellAPI.connectionReport` / `onReconnectRequest`）：HTTP 活着但页面 WebSocket 已断的情况不再被掩盖；手动与自动重试共用同一次检查，避免即时失败反馈成重连循环。
+
 ### 0.1.12
 - **适配 DSH 0.1.2 BrowserAuth，插件形态一并修复**：插件冷启动时由 host 延迟注入 Connection 服务、等 Loader settle 后铸造本进程 launch URL 交给 Electron，首次进入自动完成 `?token=` → Cookie 认证，无需手动重启后端。此前只有「壳自己启动后端」这条路能拿到 token，插件形态（`dsh web` 自动弹壳）与「先手动跑 `dsh web` 再开壳」都会停在未认证页。
 - Electron 自管后端（启动 / 重启）沿用 stdout launch URL bootstrap：严格匹配 `dsh web:` 横幅并保留完整 `?token=`（只接受 loopback，token 属本机进程机密），对 0.1.2 之前的裸 URL 保留回退解析以免退化成等待超时；外部已运行的 backend 不会被擅自重启或杀掉。

package/electron/outage.js

@@ -0,0 +1,60 @@
+/**
+ * Per-window backend-outage run (liveness-watch state).
+ *
+ * Pure module — no Electron imports — so the recovery self-test
+ * (scripts/selftest-recovery.mjs) can exercise the real transitions under
+ * plain node: consecutive-failure escalation, reset-on-recovery, and the
+ * navigation token that discards probe results which finished after the
+ * window navigated away or was disposed.
+ */
+
+// An outage escalates from transient to persistent/unavailable copy after
+// this many consecutive failed probes (~3 × 4s watch interval).
+export const PERSISTENT_AFTER_FAILURES = 3
+
+export class OutageRun {
+  constructor() {
+    this.failures = 0
+    // Navigation epoch. reset() bumps it; every async probe captures a
+    // checkpoint() before awaiting and apply() discards the result if the
+    // epoch moved meanwhile — a stale probe can never act on a newer
+    // navigation (or on a disposed window's fresh lookalike state).
+    this.epoch = 0
+  }
+
+  /** Capture the current epoch before starting an async probe. */
+  checkpoint() {
+    return this.epoch
+  }
+
+  /** True while the run is still on the navigation `token` was taken under. */
+  isCurrent(token) {
+    return token === this.epoch
+  }
+
+  /** Navigation/flip (or fresh page load): invalidate in-flight probes and start a fresh run. */
+  reset() {
+    this.epoch += 1
+    this.failures = 0
+  }
+
+  /**
+   * Apply a probe result taken under `token`. Returns null when the run was
+   * reset (the window navigated away or was disposed) while the probe was in
+   * flight — the result is stale and must not act. Otherwise advances the
+   * consecutive-failure counter and returns the exact renderer payload for
+   * the in-page connection notice (window.js sends it verbatim).
+   */
+  apply(token, up) {
+    if (!this.isCurrent(token)) return null
+    if (up) {
+      this.failures = 0
+      return { state: 'ok' }
+    }
+    this.failures += 1
+    return {
+      state: 'degraded',
+      persistent: this.failures >= PERSISTENT_AFTER_FAILURES,
+    }
+  }
+}

package/electron/preload.js

@@ -12,9 +12,28 @@
  * use a pragmatic height and rely on the page's own top padding for the
  * DSH top bar area. Overlap is acceptable: the strip is click-through for
  * everything except dragging (app-region drag areas swallow mouse events).
+ *
+ * The in-page connection notice is the non-destructive counterpart of the
+ * offline screen: while a real page is loaded, backend liveness failures
+ * never navigate away — the main process pushes watch results here and we
+ * show/clear a small fixed banner instead. Draft, scroll and selection in
+ * the loaded page are untouched.
  */
 const { contextBridge, ipcRenderer } = require('electron')
 
+// Page-side handler invoked when the main process asks the DSH client
+// runtime (injected page module, src/client/client.js) to reconnect. One
+// handler per page context — navigation resets it with the page.
+let reconnectHandler = null
+
+ipcRenderer.on('shell:client-reconnect', () => {
+  try {
+    if (typeof reconnectHandler === 'function') reconnectHandler()
+  } catch {
+    // page handler errors must not break the shell
+  }
+})
+
 contextBridge.exposeInMainWorld('shellAPI', {
   // Ask the main process to (re)load the real target URL. Used by the
   // offline screen's retry button.
@@ -23,12 +42,153 @@ contextBridge.exposeInMainWorld('shellAPI', {
   startBackend: () => ipcRenderer.send('shell:start-backend'),
   detectBackend: () => ipcRenderer.send('shell:detect-backend'),
   chooseBackendFolder: () => ipcRenderer.send('shell:choose-backend-folder'),
+  // DSH client-runtime connection bridge (see src/client/client.js):
+  // - connectionReport(state) forwards the page connection lifecycle
+  //   ('connected' | 'connecting' | 'disconnected') to the main process so
+  //   HTTP health alone can never hide a terminal disconnect;
+  // - onReconnectRequest(cb) registers the page-side reconnect action (the
+  //   runtime's own reconnect(), never a page reload); returns an
+  //   unregister function.
+  connectionReport: (state) => ipcRenderer.send('shell:client-connection', state),
+  onReconnectRequest: (cb) => {
+    if (typeof cb !== 'function') return () => {}
+    reconnectHandler = cb
+    return () => {
+      if (reconnectHandler === cb) reconnectHandler = null
+    }
+  },
+})
+
+// ---------- in-page connection notice ----------
+
+// Latest push from window.js refreshNotice: { state: 'ok' } or
+// { state: 'degraded', persistent: boolean }, computed from merged HTTP
+// probe + client-runtime connection state. Kept until the DOM is ready
+// (messages can arrive before DOMContentLoaded on very fast loads).
+let connState = null
+let connUi = null
+
+ipcRenderer.on('shell:connection-state', (_event, state) => {
+  connState = state
+  applyConnState()
 })
 
+function applyConnState() {
+  if (!connState || !connUi) return
+  if (!connState.state || connState.state === 'ok') {
+    connUi.el.style.display = 'none'
+    return
+  }
+  const persistent = connState.persistent === true
+  connUi.title.textContent = persistent
+    ? '后端暂时无法访问'
+    : '与后端的连接暂时中断'
+  connUi.sub.textContent = persistent
+    ? '当前页面已保留，连接恢复后本页会自动继续，也可手动重试。'
+    : '正在自动重连，当前页面已保留。'
+  connUi.retryBtn.hidden = false
+  // Full reload is only offered once the outage is persistent: it is
+  // destructive to unsaved page state, so it stays an explicit user choice.
+  connUi.reloadBtn.hidden = !persistent
+  connUi.el.style.display = 'flex'
+}
+
+/**
+ * Build the notice banner below the drag strip (top-center, fixed). Uses
+ * inline styles like the drag strip — no <style> injection, so the loaded
+ * page's Content-Security-Policy cannot block it. The element itself is
+ * inert while hidden and never steals focus while visible.
+ */
+function buildConnUi() {
+  const base = {
+    position: 'fixed',
+    top: '0',
+    left: '50%',
+    transform: 'translateX(-50%)',
+    display: 'none',
+    alignItems: 'center',
+    gap: '14px',
+    maxWidth: '76vw',
+    padding: '8px 14px',
+    background: 'rgba(16, 19, 26, 0.94)',
+    border: '1px solid #33405a',
+    borderRadius: '10px',
+    color: '#e8eaf0',
+    font: '13px/1.4 system-ui, "Segoe UI", "Microsoft YaHei", sans-serif',
+    boxShadow: '0 8px 24px rgba(0, 0, 0, 0.45)',
+    zIndex: '2147483646',
+    pointerEvents: 'auto',
+    userSelect: 'none',
+    WebkitUserSelect: 'none',
+  }
+  const el = document.createElement('div')
+  el.id = 'dsh-clean-shell-conn'
+  el.setAttribute('role', 'status')
+  el.setAttribute('aria-live', 'polite')
+  Object.assign(el.style, base)
+
+  const copy = document.createElement('div')
+  copy.style.display = 'flex'
+  copy.style.flexDirection = 'column'
+  copy.style.gap = '2px'
+
+  const title = document.createElement('div')
+  title.id = 'dsh-clean-shell-conn-title'
+  title.style.fontWeight = '600'
+  title.style.color = '#e8eaf0'
+  const sub = document.createElement('div')
+  sub.id = 'dsh-clean-shell-conn-sub'
+  sub.style.fontSize = '12px'
+  sub.style.opacity = '0.75'
+  copy.append(title, sub)
+
+  const actions = document.createElement('div')
+  actions.style.display = 'flex'
+  actions.style.gap = '8px'
+
+  const btnStyle = {
+    padding: '5px 12px',
+    fontSize: '12px',
+    color: '#e8eaf0',
+    background: '#232d3d',
+    border: '1px solid #33405a',
+    borderRadius: '7px',
+    cursor: 'pointer',
+  }
+
+  const retryBtn = document.createElement('button')
+  retryBtn.id = 'dsh-clean-shell-conn-retry'
+  retryBtn.type = 'button'
+  retryBtn.textContent = '立即重试'
+  Object.assign(retryBtn.style, btnStyle)
+  retryBtn.addEventListener('mouseenter', () => { retryBtn.style.background = '#2b3750' })
+  retryBtn.addEventListener('mouseleave', () => { retryBtn.style.background = '#232d3d' })
+  retryBtn.addEventListener('click', () => ipcRenderer.send('shell:retry-connection'))
+
+  const reloadBtn = document.createElement('button')
+  reloadBtn.id = 'dsh-clean-shell-conn-reload'
+  reloadBtn.type = 'button'
+  reloadBtn.textContent = '重新加载页面'
+  Object.assign(reloadBtn.style, btnStyle)
+  reloadBtn.hidden = true
+  reloadBtn.addEventListener('mouseenter', () => { reloadBtn.style.background = '#2b3750' })
+  reloadBtn.addEventListener('mouseleave', () => { reloadBtn.style.background = '#232d3d' })
+  reloadBtn.addEventListener('click', () => ipcRenderer.send('shell:reload'))
+
+  actions.append(retryBtn, reloadBtn)
+  el.append(copy, actions)
+  return { el, title, sub, retryBtn, reloadBtn }
+}
+
 window.addEventListener('DOMContentLoaded', () => {
   const platform = process.platform
   const isWin = platform === 'win32'
-  const dragHeight = isWin ? 32 : 28
+  // macOS: 12px (was 28). The DSH web UI's own top toolbar starts ~16px
+  // from the window top and does NOT consume dsh-desktop-titlebar-inset,
+  // so a 28px strip swallowed the upper half of every toolbar control —
+  // clicks had to aim low. 12px stays above that padding (drag-only band)
+  // while better-sidebar keeps yielding 28px for the traffic lights.
+  const dragHeight = isWin ? 32 : 12
   // Width reserved for native window controls (Win caption buttons / mac
   // traffic lights live at the top-right / top-left).
   const rightReserve = isWin ? 138 : 80
@@ -46,4 +206,11 @@ window.addEventListener('DOMContentLoaded', () => {
     z-index: 2147483647;
   `
   document.body.appendChild(strip)
+
+  connUi = buildConnUi()
+  // Clear the drag band so the banner is clickable, then render any state
+  // pushed before the DOM was ready.
+  connUi.el.style.top = `${dragHeight + 10}px`
+  document.body.appendChild(connUi.el)
+  applyConnState()
 })