dsh-retrace 0.4.30 → 0.4.32

package/README.md

@@ -360,7 +360,7 @@ Read it before filing an issue.
 ### Upgrading
 
 ```bash
-dsh plugin --profile desktop add dsh-retrace@0.4.30
+dsh plugin --profile desktop add dsh-retrace@0.4.32
 # then restart DSH — plugins are not hot-reloaded
 ```
 
@@ -385,7 +385,7 @@ whole tree down, so recover first and diagnose second:
 
 ### Pinning
 
-Pin an exact plugin version (`dsh-retrace@0.4.26`) and let `dsh-log-contract` resolve to
+Pin an exact plugin version (`dsh-retrace@0.4.32`) and let `dsh-log-contract` resolve to
 `>=0.3.12`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
 the **host surface**, not by semver alone.
 
@@ -439,34 +439,63 @@ the **host surface**, not by semver alone.
 | 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
 | 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
 | ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
-| 🔒 | **Page-close interception (web browsers)** | `beforeunload` interception, armed only where the host reports a native confirm dialog: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
+| 🔒 | **Page-close interception** | **Does not arm the host's native confirm dialog**; uses a **page-drawn confirm gate** instead: it draws the box and **verifies visibility synchronously** before blocking (`preventDefault`); if it cannot draw, is not visible, or the page is hidden ⇒ **lets the close through immediately**; the dialog waits for your choice (**Esc = cancel**); a **Web-Worker watchdog** (immune to background throttling) is only the *last* resort; turning the setting off returns to the official behaviour (**no restart**) |
 | 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports; the all-sessions shape also carries the host-reported page surface (`surface` / `quitVeto`) |
 
-> Desktop note: quit entry points differ by version/platform, and the DSH Desktop Electron
-> shell we inspected has no `will-prevent-unload` handler (0 hits across the packaged 2.0.9
-> `app.asar`). Where the entry does reach the page — the external report's DSH Desktop 0.9.0 /
-> Windows — the page `beforeunload` veto is **swallowed silently**: no dialog, no feedback, and
-> the exit looks stuck (only a force-quit works). Where it does not — the 2.0.9 shell we
-> inspected routes the tray item through `requestQuit(0) → window.destroy() → app.exit(0)` — the
-> quit is unaffected either way. The page cannot tell which case it is in, so desktop **never**
-> arms the native gate; it relies on the running banner plus the dispose notice. The gate is
-> armed only where the host reports that the page really surfaces a native dialog
-> (`quitVeto: true`, i.e. browser pages).
+> Desktop wording (corrected 2026-09-20): **desktop never arms the host's native confirm dialog** —
+> quit entry points differ **by version/platform**, and the native dialog either does not exist on a
+> desktop shell or is swallowed: the 2.0.9 shell we inspected has no `will-prevent-unload` handler
+> (0 hits across the packaged `app.asar`) and routes the tray item through
+> `requestQuit(0) → window.destroy() → app.exit(0)`; on the external report's DSH Desktop 0.9.0 /
+> Windows the entry **does reach** the page `beforeunload` (0.9.0), but the veto is **swallowed
+> silently** (no dialog, no feedback — the exit just looks stuck).
 >
-> **Both criteria must hold** (2026-09-18, second round): the host side is only a
-> *non-objection*, and the client keeps a **veto** — if this page's `navigator.userAgent`
-> contains `Electron`, or the page URL contains `dsh-desktop-` (the external report's shell
-> puts its desktop marker in the query string), the gate is **never** armed. The host-side
-> criteria were widened to four request-level facts: the `x-dsh-desktop-renderer` capability
-> header, a request `User-Agent` containing `Electron`, or a request URL **or `Referer`**
-> containing `dsh-desktop-` — **any one** of them classifies the page as a desktop page. (Our own
-> polling URL carries no query string, so the page marker is in practice read from `Referer`,
-> which a same-origin `fetch` sends by default.) That covers the
-> hosts that expose no desktop evidence at all (the reporter's: a pure-Node harness plus an
-> Electron renderer, where all three older criteria were false, and the old code filed
-> "no evidence at all" as a browser page ⇒ the gate was still armed ⇒ the exit still hung).
-> If Desktop cannot quit, turning off "Exit confirmation (close guard)" in settings recovers
-> immediately (no restart).
+> What actually protects on desktop is the **page-drawn confirm gate** (finalised 2026-09-19):
+> it **does call `preventDefault`** — but only after it has **drawn the box and verified it is
+> visible, synchronously**; a `visibilityState` pre-check lets the close through immediately when the
+> box cannot be drawn / is not visible / the page is hidden; the dialog waits for your choice
+> (**Esc = cancel**); a **Web-Worker watchdog** (immune to background throttling) is only the
+> **last** resort.
+>
+> **Both criteria must hold** (2026-09-18, second round): the host side is only a *non-objection*
+> (`quitVeto: true`), and the client keeps a **veto** — if this page's `navigator.userAgent`
+> contains `Electron`, or the page URL contains `dsh-desktop-` (the external report's shell puts its
+> desktop marker in the query string), the native gate is **never** armed. The host-side criteria
+> were widened to four request-level facts: the `x-dsh-desktop-renderer` capability header, a
+> request `User-Agent` containing `Electron`, or a request URL **or `Referer`** containing
+> `dsh-desktop-` — **any one** of them classifies the page as a desktop page. (Our own polling URL
+> carries no query string, so the page marker is in practice read from `Referer`, which a
+> same-origin `fetch` sends by default.) That covers the hosts that expose no desktop evidence at
+> all (the reporter's: a pure-Node harness plus an Electron renderer, where all three older criteria
+> were false, and the old code filed "no evidence at all" as a browser page ⇒ the gate was still
+> armed ⇒ the exit still hung).
+>
+> **Known limitation (stated plainly)**: some desktop shells route quit **around the page entirely**
+> (e.g. `requestQuit → destroy → app.exit`, or the X button merely hides the window) ⇒ on those
+> shells a plugin **cannot** show a confirm dialog at quit time; it **needs a shell seam**
+> (a `will-prevent-unload` handler, or a pre-quit prompt hook). If Desktop cannot quit, turning off
+> "Exit confirmation (close guard)" in settings recovers immediately (no restart).
+
+**Session badge & display name** (**planned / off by default**) — badges are for human
+collaboration; **identity is still decided by the session id**. The transports
+(`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`, on both HTTP and harness),
+the resolver and the write guards are **in place**, but the **automatic startup path that writes
+titles is off by default** (after three distinct on-device failures it moves to the **scripting
+layer T3**, which is not implemented yet) — set `__DSH_RETRACE_BADGE_BOOTSTRAP = true` to enable it:
+
+- A session title renders as `[badge] original title` (shape placeholder: `[opxxxopxxx] original title`); the badge
+  shape is **`opxxxopxxx`** and comes from the **real table** `codes.json` (workspace + sequence +
+  parent-chain semantics — **not a hash**).
+- Sessions with **no `session/title` event are left blank on purpose** (the title shows just
+  `[badge]`) — **no project-name fallback, no fabricated name**.
+- If the table / resolver is unavailable it falls back to the **raw session id as a placeholder**,
+  and **never** to FNV.
+- The sidebar row, the running banner and the checkpoint view share **one source**: the same badge
+  map the host hands down (host op `badgeMap`).
+
+> **Planned (not shipped)**: the scripting-layer T3 is not implemented yet (the badge/name
+> **automatic title-writing startup path** is blocked on it); the agent business-layer plan (runtime guard,
+> interruption governance, ecosystem-facing interfaces) is a **plan**, not a shipped capability.
 
 > Command surface: `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP).
 

package/README.zh.md

@@ -271,7 +271,7 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 ### 升级
 
 ```bash
-dsh plugin --profile desktop add dsh-retrace@0.4.26
+dsh plugin --profile desktop add dsh-retrace@0.4.32
 # 然后重启 DSH —— 插件不会热重载
 ```
 
@@ -285,7 +285,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 
 ### 版本固定建议
 
-请固定到确切版本（`dsh-retrace@0.4.26`），并让 `dsh-log-contract` 解析到 `>=0.3.12`。
+请固定到确切版本（`dsh-retrace@0.4.32`），并让 `dsh-log-contract` 解析到 `>=0.3.12`。
 **不要在跨宿主升级时依赖 `^0.4` 这种范围**：这里的兼容性由**宿主的面**决定，光看 semver 不够。
 
 ---
@@ -326,25 +326,47 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 | 🛡️ | **运行中检测** | 逐会话扫描运行中工作：agent 正在跑 / inbox 排队 / 后台 jobs / 未闭合轮 |
 | 📋 | **运行中横幅** | 有运行中工作的会话显示页面常驻横幅（会话短码 + 原因），退出前可见 |
 | ⚠️ | **退出提示** | 插件 dispose（应用退出/重载）时中文提示列出每个运行中会话与原因——只提示，绝不代你取消 agent |
-| 🔒 | **页面关闭拦截（普通浏览器）** | `beforeunload` 拦截，只在宿主回报会弹原生确认框的页面上武装：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
+| 🔒 | **页面关闭拦截** | **不武装宿主原生确认框**；改用**页面自绘确认门**：先画框并**同步校验可见**才拦（`preventDefault`），画不出 / 不可见 / 页面不可见 ⇒ **当场放行**；确认框一直等你选择（Esc = 取消）；**看门狗（Web Worker 计时器，不受后台节流）**只作最后一道；关掉设置项即退回官方形态（免重启） |
 | 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状；全会话形状另带宿主判定的承载面（`surface` / `quitVeto`） |
 
-> 桌面说明：**退出入口随版本/平台而变**，而我们检查的 Electron 壳没有处理 `will-prevent-unload`
-> （装好的 2.0.9 `app.asar` 全文检索 0 命中）。**会走到该入口的那类版本**（外部报告所在的
-> DSH Desktop 0.9.0 / Windows）上，页面 `beforeunload` 否决被**静默吞掉**：不弹界面、不给
-> 反馈，表现为退出卡住（只能强退）；**不走该入口的版本**（我们检查的 2.0.9：托盘项走
-> `requestQuit(0) → window.destroy() → app.exit(0)`）上，退出本来就不受影响。页面里分不出
-> 自己属于哪一类，因此**桌面端一律不武装**原生门，保护由运行中横幅 + dispose 提示承担；
-> 只有宿主回报"这个页面会弹原生确认框"（`quitVeto: true`，即普通浏览器页）时才武装。
+> **桌面端口径（2026-09-20 更正）**：**桌面端一律不武装宿主原生确认框** —— **退出入口随版本/平台而变**，
+> 而原生确认框在桌面壳上要么不存在、要么被静默吞掉：我们检查的 2.0.9 壳没有处理
+> `will-prevent-unload`（打包 `app.asar` 全文检索 0 命中），托盘项走
+> `requestQuit(0) → window.destroy() → app.exit(0)`；外部报告那套 DSH Desktop 0.9.0 / Windows
+> 上虽然**会走到页面** `beforeunload`，但页面否决被**静默吞掉**（不弹界面、不给反馈，表现为退出卡住）。
 >
-> **两道判据都成立才武装**（2026-09-18 第二轮）：宿主那条只是"不反对"，客户端还有**一票否决** ——
-> 本页 `navigator.userAgent` 含 `Electron`，或页面 URL 含 `dsh-desktop-`（外部报告那套壳的查询参数
-> 前缀）⇒ 一律不武装。宿主侧的判据也补成四条请求级证据：能力头 `x-dsh-desktop-renderer` /
-> 请求 UA 含 Electron / 请求 URL **或 `Referer`** 含 `dsh-desktop-`（我们自己的轮询 URL 没有 query，
-> 所以页面标记实际是从 `Referer` 读到的），**任一成立**即判桌面页面。这样"壳什么桌面痕迹
-> 都不给"的宿主（报告人那台：纯 Node 跑 harness + Electron 渲染页，三条旧判据全不成立，
-> 旧实现把"完全没有证据"归成了浏览器页 ⇒ 照旧武装 ⇒ 仍退不掉）也不会再把退出卡住。
-> 桌面端退不掉时，把设置里的「退出确认（关闭守卫）」关掉即可立即恢复（不用重启）。
+> **桌面端真正生效的是页面自绘确认门**（2026-09-19 收尾）：它**确实会调用 `preventDefault`** ——
+> 但只在"**先画出来 + 同步可见性校验通过**"之后才拦；`visibilityState` 前置检查，框画不出来 /
+> 不可见 / 页面不可见 ⇒ **当场放行**；确认框一直等你选择（**Esc = 取消**）；
+> **看门狗用 Web Worker 计时器**（不受后台节流）只作**最后一道**分流。
+>
+> 武装**宿主原生门**的判据：**两道判据都成立才武装**（2026-09-18 第二轮）—— 宿主那条只是"不反对"
+> （`quitVeto: true`），客户端还有**一票否决**：本页 `navigator.userAgent` 含 `Electron`，
+> 或页面 URL 含 `dsh-desktop-`（外部报告那套壳把桌面标记放在查询串里）⇒ 一律不武装。
+> 宿主侧判据补成**四条请求级证据**：能力头 `x-dsh-desktop-renderer` / 请求 UA 含 `Electron` /
+> 请求 URL **或 `Referer`** 含 `dsh-desktop-`（我们自己的轮询 URL 没有 query，所以页面标记
+> 实际是从 `Referer` 读到的），**任一成立**即判桌面页面。这样"壳什么桌面痕迹都不给"的宿主
+> （报告人那台：纯 Node 跑 harness + Electron 渲染页，三条旧判据全不成立，旧实现把
+> "**完全没有证据**"归成了浏览器页 ⇒ 照旧武装 ⇒ 仍退不掉）也不会再把退出卡住。
+>
+> **已知限制（照实写）**：某些桌面壳的退出口径**根本不经过页面**（如
+> `requestQuit → destroy → app.exit`，或点 X 只是隐藏窗口）⇒ 那类壳上"退出时弹确认"
+> **插件侧做不到**，需要**壳提供 seam**（`will-prevent-unload` 处理，或退出前的询问钩子）。
+> **桌面端退不掉时**，把设置里的「退出确认（关闭守卫）」关掉即退回官方形态（**不用重启**）。
+
+**会话短码与显示名**（**计划 / 默认关闭**）—— 人机协作用短码，**身份判定仍以 session id 为准**。
+通道（`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`，HTTP + harness 两入口）与
+解析器、写护栏**均已就位**；但**启动自动写标题那条路默认关闭**（真机上三次不同失败后按
+「文件/脚本优先」改走**脚本层 T3**，T3 尚未实现）—— 需要时置 `__DSH_RETRACE_BADGE_BOOTSTRAP = true` 打开：
+
+- 会话标题显示为 `[短码] 原标题`（形态占位：`[opxxxopxxx] 原标题`），短码形态 **`opxxxopxxx`**，
+  由**真表** `codes.json` 解析（工作区 + 序号 + 父链语义，**不是 hash**）。
+- **没有 `session/title` 事件的会话如实留空**（标题只显示 `[短码]`）—— **不回落项目名、不伪造名字**。
+- 拿不到短码表 / 解析器不可用时退回**原始 session id 占位**，**绝不回落 FNV**。
+- 侧栏会话行、运行中横幅、读档点视图的短码**同源**：都取宿主下发的**同一份**映射（宿主 op `badgeMap`）。
+
+> **计划（未上线）**：脚本层 T3 尚未实现（短码/名字的**启动自动写标题**即卡在这里）；业务层规划
+> （运行时守护、中断治理、生态开放接口）见下节，属**计划**而非已上线能力。
 
 **未来计划**——agent 业务层规划（运行时守护、中断治理、生态开放接口）**尚未发布**，此节是**计划**而非已上线能力。本 README 描述的是**开发线（main）**，可能领先于 npm 上最新发布版。