better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src-scripts/verify_orphans.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Makeup pass: verify URLs that the link-BFS crawl could not discover.
+
+Some live pages are orphans — present in the docs tree (and most also in llms.txt) but
+never linked from any crawled page's HTML, so a pure link-follow crawl never sees them.
+This script takes the reverse-check misses (LOCAL-ONLY entries), fetches each politely
+(serial, 0.5 s apart), and records the result in src/site-pages.json with provenance:
+    "source": "verify_orphans"  (plus "llms": true when llms.txt lists it)
+Re-run gen_mapping.py afterwards to refresh site-pages-map.txt.
+"""
+import json, os, time, re, urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SRC = os.path.join(HERE, "..", "src")
+ORIGIN = "https://hermes-agent.nousresearch.com"
+
+def fetch(url):
+    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0 (doc crawl)"})
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            return r.status
+    except urllib.error.HTTPError as e:
+        return e.code
+    except Exception:
+        return None
+
+def main():
+    # 1) normalize seed-variant collisions: '/docs/' vs '/docs', '/docs/zh-Hans/' vs '/docs/zh-Hans'
+    pages = json.load(open(os.path.join(SRC, "site-pages.json")))
+    for slash, bare in ((ORIGIN + "/docs/", ORIGIN + "/docs"),
+                        (ORIGIN + "/docs/zh-Hans/", ORIGIN + "/docs/zh-Hans")):
+        if slash in pages:
+            rec = pages.pop(slash)
+            pages.setdefault(bare, rec)
+    # 2) reverse-check misses, recomputed here (same rules as gen_mapping.resolve)
+    sys_path = os.path
+    miss_urls = []
+    map_txt = open(os.path.join(SRC, "site-pages-map.txt")).read()
+    miss_urls = re.findall(r"(" + re.escape(ORIGIN) + r"\S+)\tLOCAL-ONLY", map_txt)
+    llms = open(os.path.join(SRC, "llms.txt")).read()
+    for u in miss_urls:
+        if u in pages and pages[u]["status"] == 200:
+            continue
+        s = fetch(u)
+        time.sleep(0.5)
+        pages[u] = {"status": s, "lang": "zh-Hans" if "/zh-Hans" in u else "en",
+                    "source": "verify_orphans", "llms": u in llms}
+        print(s, u, flush=True)
+    json.dump(pages, open(os.path.join(SRC, "site-pages.json"), "w"), indent=1)
+    print("updated", os.path.join(SRC, "site-pages.json"))
+
+if __name__ == "__main__":
+    main()

package/docs/specs/ctx/spec.md

@@ -2,12 +2,19 @@
 
 ## Purpose
 
-Let the model read a curated, read-only snapshot of its calling environment via `ctx://` URLs — small, static, agent-derived facts (who am I, what model, what cwd) addressable like any other resource. This replaces the v0.1.8c design that mapped `ctx://` onto persistent-kernel variables; see design.md D4 for why that semantics was wrong (the kernel namespace is the model's own REPL scratchpad, not its environment).
+Let the model read a curated, read-only snapshot of its calling environment via `ctx://` URLs — small, static, agent-derived facts (who am I, what model, what cwd) addressable like any other resource, plus a recallable-context navigation surface over the live session's event log. This replaces the v0.1.8c design that mapped `ctx://` onto persistent-kernel variables; see design.md D4 for why that semantics was wrong (the kernel namespace is the model's own REPL scratchpad, not its environment).
 
 ## Requirements
 
+### Requirement: Coordinate invariant
+Every number the system shows the model SHALL be either directly usable as a selector in the same URL family, or explicitly labeled metadata with its unit. The two coordinates are `seq` (event sequence, for `[<label|n>]` addressing) and `line` (transcript line, for `:N-M` windows and `grep` on `ctx://session/transcript`); both SHALL be labeled wherever shown. An unlabeled number that is not an addressable coordinate SHALL NOT appear.
+
+#### Scenario: Labeled coordinates in the manifest
+- **WHEN** the model reads `ctx://session/compactions`
+- **THEN** every episode row carries `seq=<start>..<end>` and `lines=<start>..<end>` (or `lines=<none>` for an empty span), never a bare range that could be misread as the other unit
+
 ### Requirement: Curated snapshot keys
-The system SHALL resolve `ctx://session` as the recallable-context statistics snapshot: the prepared default face SHALL carry the session header (absorbing the former identity fields `id`/`status`/`origin`/`delegationDepth`), storage facts, totals using native DSH field names, per-compaction segments plus a `live` tail segment, the inline compactions manifest (label, checkpoint_seq, compactionId, shadowedRange, shadowedItems, shadowedTokenCount, `replaces_checkpoint`, and an 8-section × ≤100-char summary preview per episode), and a `system_prompt` info card. The canonical face (see `:raw`) SHALL be the full session transcript. The first-level keys `model` and `cwd` SHALL be removed — their information SHALL appear only as info-card fields inside the snapshot. Any other first-level key SHALL return the structured `CTX_UNKNOWN_KEY` error listing the known keys and sub-paths.
+The system SHALL resolve `ctx://session` as the recallable-context statistics snapshot: the prepared default face SHALL carry the session header (absorbing the former identity fields `id`/`status`/`origin`/`delegationDepth`), storage facts, totals using native DSH field names, per-compaction segments plus a `live` tail segment (each with `seq_start`/`seq_end` and `lines`), the inline compactions manifest (label, checkpoint_seq, compactionId, `seq_start`/`seq_end`, `lines`, shadowedItems, shadowedTokenCount, `fidelity`, `replaces_checkpoint`, and an 8-section × ≤100-char summary preview per episode), an `asOf` card (max seq and transcript line at read time, with a note that totals are live values), and a `system_prompt` info card. The canonical face (see `:raw`) SHALL be the full session transcript. The first-level keys `model` and `cwd` SHALL be removed — their information SHALL appear only as info-card fields inside the snapshot. Any other first-level key SHALL return the structured `CTX_UNKNOWN_KEY` error listing the known keys and sub-paths.
 
 #### Scenario: Reading session identity
 - **WHEN** the model reads `ctx://session` from a delegated subagent session
@@ -21,6 +28,10 @@ The system SHALL resolve `ctx://session` as the recallable-context statistics sn
 - **WHEN** the model reads `ctx://session`
 - **THEN** the session's creation working directory appears as an info-card field, not as a separate key
 
+#### Scenario: Staleness is self-evident
+- **WHEN** the model reads `ctx://session` and caches the snapshot
+- **THEN** the `asOf` card tells it the seq and line the snapshot was taken at, so it cannot mistake a cached snapshot for live totals
+
 #### Scenario: Unknown key
 - **WHEN** the model reads `ctx://<other key>`
 - **THEN** the system returns the structured `CTX_UNKNOWN_KEY` error naming the known keys and sub-paths
@@ -47,16 +58,20 @@ The system SHALL reject every write to `ctx://` with the structured `URL_READ_ON
 - **THEN** the system returns the structured `URL_READ_ONLY` error and changes nothing
 
 ### Requirement: Session sub-path grammar
-The system SHALL resolve `ctx://session/…` sub-paths: `transcript` (full transcript), `compactions` (manifest), `compactions[<label|ordinal>]` (the episode summary, 8 sections verbatim), `user_prompts[<n|seq>]`, `tool_calls[<n|seq>]`, `agent_responses[<n|seq>]`, `thinking[<n|seq>]` (reasoning blocks), and `system[<n|seq>]` (system messages). The former `compactions[<label|n>]/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. Bracket resolution SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal on miss. The system SHALL support `:raw` and line windows (`:N`, `:N-M`, `:N+K`, `:N-`, comma-separated ranges) on every resolved resource, and the composite `:raw:<lines>` form SHALL be valid everywhere and SHALL equal `:<lines>` (the `:raw` prefix is redundant in a line-window context but MUST parse).
+The system SHALL resolve `ctx://session/…` sub-paths: `transcript` (full transcript), `compactions` (manifest), `compactions[<label|ordinal>]` (the episode summary), `user_prompts[<n|seq>]`, `tool_calls[<n|seq>]`, `agent_responses[<n|seq>]`, `thinking[<n|seq>]` (reasoning blocks), and `system[<n|seq>]` (system messages). The former `compactions[<label|n>]/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. Bracket resolution SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal on miss. The system SHALL support `:raw`, line windows (`:N`, `:N-M`, `:N+K`, `:N-`, comma-separated ranges), `:path/<dot-path>`, and `?q=<query>` on every resolved resource; the composite `:raw:<lines>` form SHALL be valid everywhere and SHALL equal `:<lines>` (the `:raw` prefix is redundant in a line-window context but MUST parse). Line windows on a compaction episode SHALL interpret numbers as transcript line coordinates (identical to the same window on `transcript`), and `:path/`/`?q=` SHALL apply to the bare (prepared) face.
 
 #### Scenario: Drilling into a compaction episode by label
 - **WHEN** the model reads `ctx://session/compactions[221217]`
-- **THEN** the system returns that episode's structured summary (all 8 sections verbatim)
+- **THEN** the system returns that episode's structured summary (all 8 sections verbatim) or, for the latest episode, the navigation block (see digest residence)
 
 #### Scenario: Ordinal fallback
 - **WHEN** the model reads `ctx://session/compactions[0]` and no episode carries the label `0`
 - **THEN** the system returns the first-recorded episode (0-based)
 
+#### Scenario: Transcript-relative episode window
+- **WHEN** the model reads `ctx://session/compactions[<label>]:5300-5310`
+- **THEN** the system returns transcript lines 5300–5310 — the same bytes as `ctx://session/transcript:5300-5310`
+
 #### Scenario: Composite raw selector
 - **WHEN** the model reads `ctx://session/compactions[221217]:raw:500-560`
 - **THEN** the system returns the same lines as `ctx://session/compactions[221217]:500-560`
@@ -66,11 +81,56 @@ The system SHALL resolve `ctx://session/…` sub-paths: `transcript` (full trans
 - **THEN** the system returns the structured `CTX_BAD_PATH` error echoing the URL and naming the `:raw` / `:N-M` selectors as the replacement
 
 ### Requirement: Canonical and prepared content faces
-The system SHALL treat every resource as having one canonical content: `:raw` SHALL return the canonical full content, line windows SHALL always apply to the canonical content, and the bare URL SHALL return the prepared default face when one is prepared (session → statistics snapshot; compaction episodes → 8-section summary; `thinking` → per-block index list; `system` → per-message index list) or the canonical content when none is. `:raw:<lines>` SHALL equal `:<lines>` — the composite form is accepted on every resource.
+The system SHALL treat every resource as having one canonical content: `:raw` SHALL return the canonical full content, line windows SHALL always apply to the canonical content, and the bare URL SHALL return the prepared default face when one is prepared (session → statistics snapshot; compaction episodes → digest/navigation block; `thinking`/`system`/`injections` and the element collections → index lists) or the canonical content when none is. `:raw:<lines>` SHALL equal `:<lines>` — the composite form is accepted on every resource. A line window that reaches past a resource's canonical extent SHALL return an explicit boundary note (e.g. `[ctx:// note: … span is transcript lines <s>-<e>]`) rather than silently returning a truncated or empty view.
 
 #### Scenario: Line windows ignore the prepared face
 - **WHEN** the model reads `ctx://session/compactions[221217]:500-560`
-- **THEN** the system returns lines 500–560 of the episode's original shadowed span, not of the summary
+- **THEN** the system returns transcript lines 500–560 of the episode's original shadowed span, not of the summary
+
+#### Scenario: Out-of-span window is explicit
+- **WHEN** the model reads `ctx://session/compactions[221217]:5500` and the episode span ends before transcript line 5500
+- **THEN** the system returns the boundary note naming the episode's span instead of an empty string
+
+#### Scenario: Over-read notes, open tail does not
+- **WHEN** the model reads a window whose upper bound exceeds the canonical extent (e.g. `transcript:1940-2000` on a 1947-line transcript)
+- **THEN** the system returns the available lines plus the boundary note naming the canonical end — a partial over-read is still an over-read, because otherwise the model cannot tell "empty" from "does not exist"
+- **WHEN** the model reads the open-tailed `transcript:1940-`
+- **THEN** the system returns the remaining content to the end with no boundary note, provided the window's start is within the extent
+- **WHEN** the model reads an open tail whose start is already past the extent (e.g. `compactions:2-` when the canonical content is one line)
+- **THEN** the system returns the boundary note alone — there is no content to return, so the over-read must be spoken for
+
+#### Scenario: Upper bound exactly at the extent is not an over-read
+- **WHEN** the model reads `compactions:1-1` where the canonical content is exactly one line
+- **THEN** the system returns that line with no boundary note
+
+### Requirement: Episode digest residence
+The system SHALL render the prepared face of the **latest** compaction episode as a navigation block (NOT the digest text, which is already resident in the model's live context as the compact-checkpoint message): it SHALL name the episode's `lines`/`seq`/items/tokens, its `fidelity`, the transcript lines where the resident digest lives (`digest resident at transcript:<start>-<end> (seq=<checkpointSeq>)`), and the landmark roster. The prepared face of every **older** episode SHALL return that episode's full digest (`summaryText`) followed by the same pointer block. `:raw` on any episode SHALL always return the full shadowed span, so a digest is never lost.
+
+#### Scenario: Latest episode is a pointer, not a dump
+- **WHEN** the model reads the bare URL of the most recent compaction episode
+- **THEN** the system returns the navigation block with the digest's transcript location and landmarks, and does NOT repeat the digest text
+
+#### Scenario: Older episode returns its digest
+- **WHEN** the model reads the bare URL of a non-latest compaction episode
+- **THEN** the system returns that episode's full digest followed by its pointer block
+
+### Requirement: Landmark roster
+The system SHALL include, in each compaction episode's navigation/pointer block, a direction-marker roster computed over that episode's shadowed events, every marker expressed as transcript line coordinates directly usable with `:N-M`: user-turn lines, failure lines (tool results with `message.isError` true or a present error), touched file paths with occurrence counts (best-effort, from tool-call arguments), and the count of prior checkpoints absorbed in the span. Rosters SHALL be capped to a screen and SHALL tail with `… +N more` when capped.
+
+#### Scenario: Locating user turns and failures
+- **WHEN** the model reads a compaction episode's prepared face
+- **THEN** the landmark block lists user-turn lines and failure lines as transcript line numbers
+
+#### Scenario: Locating touched files
+- **WHEN** the model reads a compaction episode whose span contains file tool calls
+- **THEN** the landmark block lists each touched path with its occurrence count
+
+### Requirement: Fidelity signal
+The system SHALL include, per compaction episode, a `fidelity=<user_turns>:<tool_calls>` figure (in the manifest, the snapshot, and the episode pointer block) so the model can judge whether the digest is trustworthy: a tool-heavy span's digest is trustworthy and detail is regenerable, while a user-intent-heavy span must be drilled into.
+
+#### Scenario: Reading fidelity
+- **WHEN** the model reads `ctx://session/compactions` or a compaction episode's prepared face
+- **THEN** each episode carries its `fidelity` ratio
 
 ### Requirement: Thinking, system, and injections collections
 The system SHALL expose three index-faced collections under `ctx://session/`, all following the canonical/prepared face model (bare URL = prepared index; `:raw` / `:N-M` = canonical full text):
@@ -99,9 +159,21 @@ The system SHALL expose three index-faced collections under `ctx://session/`, al
 - **WHEN** the model reads `ctx://session/injections[0]` or `ctx://session/injections[<seq>]`
 - **THEN** the system returns that injected message's full text with its `INJECTED <kind>` header line
 
+### Requirement: Element collections carry index faces
+The system SHALL give `user_prompts`, `tool_calls`, and `agent_responses` the same prepared-index/canonical model: the bare URL SHALL return an index list (one line per element: event seq and a ≤100-char preview; the long `tool_calls`/`agent_responses` collections SHALL cap the bare index at a screen and tail with `… +N more — use :raw for all, ?q= to filter, [n|seq] for one`); `[<n|seq>]` SHALL return that element's full text; `:raw` SHALL return all elements' full text joined; line windows SHALL index that canonical text. The error for an unaddressed or out-of-range element SHALL name the collection and its count and SHALL NOT echo an empty-bracket URL.
+
+#### Scenario: Browsing user prompts
+- **WHEN** the model reads `ctx://session/user_prompts`
+- **THEN** the system returns an index list of the real user prompts (seq + preview)
+
+#### Scenario: Addressing a tool call
+- **WHEN** the model reads `ctx://session/tool_calls[<seq>]`
+- **THEN** the system returns that call's name, arguments, and result — where a present result's text is rendered from either the flat or the nested content-block shape, never silently empty
+
 ### Requirement: Unknown key echoes known keys
 The `CTX_UNKNOWN_KEY` error SHALL list the currently known first-level keys and the sub-path pointer, so the model can self-correct without leaving the read tool.
 
 #### Scenario: Unknown key with roster echo
 - **WHEN** the model reads `ctx://bogus`
 - **THEN** the system returns `CTX_UNKNOWN_KEY` naming `session` and the sub-path roster
+

package/docs/specs/model-picker-ios-blur/spec.md

@@ -0,0 +1,168 @@
+# model-picker-ios-blur Specification
+
+## Status
+
+**OPEN — 不修，仅记录。** 2026-10-01 user 裁决：按奥卡姆剃刀，production 没问题就不引入非必要的兜底；当时写好的页面级兜底**已 revert**（源码、单测、mobile leg 接线全部移除）。本文是该问题的**调查记录**，不含任何生效的代码变更。
+
+---
+
+## Purpose
+
+记录一个**未坐实的 iOS 触摸缺陷**的完整证据链，使得：
+
+1. 日后任何人不必从零重查——已知的事实、已证伪的假设、以及仍未知的部分都在这里；
+2. 当时那段**已删除**的兜底实现（要点 + 判据）可被重建；
+3. 「什么时候该重新研究」有明确触发条件。
+
+---
+
+## 现象（user 报告，2026-10-01）
+
+iPhone Safari / 加到主屏的 Web App，composer 的 model seat：
+
+- 第一次点触发按钮 → 弹出**一级菜单**（两行：`Model │ <当前模型>`、`Effort │ <当前等级>`）—— 正常。
+- 再点一级菜单里的 **`Model` 那一行**（期望进入二级的 provider 分组模型清单）→ **整个 menu 直接关掉**，清单不出现。
+- 换模型、resume 会话等后续流程在能进入二级菜单时一切正常。
+
+发生实例：**4999 rig**（DSH 0.1.7-rc.1 checkout 构建 + better-dsh 0.2.4-d）。
+未发生实例：**3080 production**（DSH 0.1.7-rc.2 全局安装 + better-dsh 0.2.4-c），同一台 iPhone。
+
+> user 补充的历史：更早 **test.pc 的 PC 端**也出现过同样行为，后来某次更新/调整后**自愈**了。这条是「上游版本差异」这一方向的重要旁证。
+
+---
+
+## Why not fixed (Occam 裁决)
+
+| 事实 | 含义 |
+|---|---|
+| prod（rc.2）在同机型同模式下**没有**这个问题 | 现役稳定版本不需要兜底 |
+| user 推测更早的 beta 也没有 | 不是「新版本引入的回归」 |
+| 曾经的 test.pc PC 端**自愈** | 更像上游某次改动带进来的差异，而非我们的插件 |
+| 两端**都是**加到主屏的 Web App（PWA） | PWA/浏览器模式差异这条最省事的解释被**排除** |
+
+结论：**不引入页面级兜底**；把证据留下，等有更强的复现条件（或上游版本对齐）再研究。
+
+---
+
+## 已确证的事实（证据）
+
+**E1 — 不是数据/凭据问题。** 4999 活体驱动该组件：根菜单正常；二级清单完整加载 `DeepSeek`（V4.1-Flash、V4-Pro）+ `zai`（GLM-4.7、GLM-5-Turbo、GLM-5.2、GLM-5.2 Highspeed、GLM-5.3、GLM-5.3-Flash、GLM-5.3 Highspeed），**无 error strip / warning 行**。host 侧 `agent-default-model: zai/glm-5.3-flash`，`ZAI_API_KEY` 在凭据库。
+
+**E2 — 上游的关闭逻辑在两版之间字节一致。** `@deepseek-ai/dsh-client-ui-model-selection` 的 `ModelSelect.onBlur`：
+
+```js
+const onBlur = (event) => {
+  if (event.relatedTarget instanceof Node && (rootRef.current?.contains(event.relatedTarget) === true
+      || menuRef.current?.contains(event.relatedTarget) === true)) return;
+  close();   // 任何「没落在卡片里」的 blur 都关菜单
+};
+```
+
+prod 的 rc.2 与 rig 的 rc.1 逐字符相同 ⇒ 组件本身在两个实例上**同样脆弱**。
+
+**E3 — 机制可达（本地复现，无需 iOS）。** 菜单开着、触发器持焦时，制造一个 `relatedTarget === null` 的 `focusout`：
+
+```
+before: menuOpen=1, active=Select model, current …
+after:  menuOpen=0        ← 菜单被 onBlur 关掉
+```
+
+即：**只要 iOS 在 tap 的触摸相位把焦点抹到"没有地方"，菜单就会在 click 之前被 unmount，tap 被吃掉。** 这也解释了 user 观察到的「按完直接关回去」。
+
+**E4 — prod 并不免疫（对照实验，决定性）。** 用 prod 自己的 cookie 在真实浏览器里对 **3080 活体页面**施加同一个事件：
+
+| | 菜单开 | 施加 `focusout(relatedTarget=null)` | 点 Model 行 |
+|---|---|---|---|
+| **PROD 3080** | ✓ | **菜单被关掉** ❌ | — |
+| **RIG 4999**（当时带兜底） | ✓ | 存活 ✓ | 9 行清单 ✓ |
+
+⇒ 「prod 的代码里没有这个缺陷」被**证伪**。差异不在组件逻辑。
+
+**E5 — 两个实例服务的组件实现并不"几乎一样"。** 抓取**实际被浏览器加载**的 client bundle 比对（rc.1 vs rc.2），差异是实质性的（非仅 CSS）：
+
+- 菜单容器：裸 `<div>` → primitives 的 **`MenuSurface`**（多一层 `material` + 一个 `position:fixed` 的 backing portal）；
+- `show()`：rc.2 在「没有当前选择」时**直接开二级清单**（`setPane(state.current === null ? 'model' : 'root')`），rc.1 永远先开一级；
+- 新增 `pending` / `StateDot` 转圈、`retainedEffort`、`deepseek-account` provider 分组与文案；
+- 删除 composer-block（`blocked.composer`）；
+- `busy` 语义：`status === 'selecting'` → `pending !== null`；
+- 目录同步整段重写：catalog 未就绪时 **rc.1 把 `current` 清成 null / `groups` 清空**（除非 `resolved`），**rc.2 保留**。
+
+**E6 — 我们的插件不碰焦点/指针默认。** `better-dsh/src/mobile/client/index.ts` 的滑动手势只在 `document` 上**记录** pointerdown/move 的起点与位移，**既不 `preventDefault()` 也不 `stopPropagation()`**；zoom guard 只在 iOS 窄视口下改 viewport meta / 注入字号地板，不触碰焦点。⇒ 没有「我们的插件把 tap 吃掉」的通路。
+
+---
+
+## 已证伪的假设
+
+| # | 假设 | 证伪方式 |
+|---|---|---|
+| H1 | 没有 GLM-5.3 的 key / catalog 两边对不上 → listing 报错后静默弹回 | **E1**（清单完整、无报错） |
+| H2 | 我们某个插件开发不到位（手势/zoom guard 吞掉了 tap） | **E6** |
+| H3 | prod 是 PWA、rig 是浏览器标签页，模式差异 | user 确认**两端都是加到主屏的 Web App** |
+| H4 | prod 的组件代码免疫，所以只有 rig 坏 | **E4**（prod 活体同样被关掉） |
+| H5 | 「两个实例几乎一样，只是版本落后一点点」 | **E5**（该组件实现有实质差异） |
+
+---
+
+## 仍然未知（open question）
+
+> 同一台 iPhone、同为 PWA：为什么 **rc.2 的页面不发**那个杀死菜单的 blur，而 **rc.1 的页面发**？
+
+按可疑度排序的候选方向（**均未验证**）：
+
+- **D1（最可疑）** rc.1 → rc.2 之间**该组件自身**的行为差异（E5 那一串），特别是菜单容器从裸 `div` 换成 `MenuSurface`、以及 `show()` 开窗策略/目录同步重写。这条与 user 的「更新后自愈」时间线吻合。
+- **D2** 壳层（shell / kernel / composer / `ui-conversation`）在 rc.1→rc.2 的焦点处理差异。
+- **D3（低）** better-dsh 0.2.4-c（prod）vs 0.2.4-d（rig）的差异 —— 但 c→d 只多了 web-password gate 与本次已 revert 的 fix，两者都不参与焦点。
+- **D4** 其它环境项：iOS 版本、键盘是否弹起、PWA 安装时间与缓存态、tap 时 `document.activeElement` 究竟是谁。
+
+**重新研究的触发条件**：把 rig 对齐到 rc.2 后现象**仍在** ⇒ 推翻 D1/D2，转 D4，此时才值得上真机探针。
+
+---
+
+## 复现与取证
+
+### R1 本地机制复现（Chromium，无需 iOS）
+
+```js
+// 菜单开着、触发器持焦时执行
+document.activeElement.blur()          // → menuOpen 1 → 0，菜单消失
+```
+
+或者用完整对照脚本：用 cookie 打开 3080 / 4999，`click` 触发器 → `document.activeElement.blur()` → 看 `[role="menu"]` 是否还在 → 若在，点 `[role="menuitem"]` 里含 `Model` 的那行，数 `[role="menuitemradio"]`。当时的脚本（已随 revert 删除）用的是 `puppeteer-core`（`better-dsh/node_modules`）+ playwright 缓存的 Chromium（`~/.cache/ms-playwright/chromium-1228/chrome-linux64/chrome`），cookie 从 curl 的 Netscape jar 解析（**注意 `#HttpOnly_` 前缀不是注释**）。
+
+### R2 真机取证（建议的下一步，尚未做）
+
+在页面注入探针，记录并**悬浮显示**最近 N 条 `touchstart / touchend / mousedown / focusin / focusout(relatedTarget) / click` + 每步的 `document.activeElement`，在 iPhone 上点一次、截图。这是唯一能看到「iOS 到底发了什么事件」的手段——本机没有可用真 WebKit（Playwright 不支持 Ubuntu 26.04，系统只有 snap epiphany）。
+
+---
+
+## 当时的兜底实现（已 revert，存档备查）
+
+若将来 R2 证明「iOS 确实发了那个 blur」，可按此重建（`better-dsh` 的 `dashr-mobile` boot-script 腿，纯函数 + `Function.prototype.toString` 内联，与 `zoom-guard.ts` 同一约束：ES5、自包含）：
+
+```js
+export function isSpuriousMenuBlur(target, relatedTarget) {
+  if (relatedTarget !== null && relatedTarget !== undefined) return false
+  if (target === null || typeof target !== 'object') return false
+  var el = target
+  if (typeof el.closest === 'function') {
+    var owner = el.closest('[role="menu"]')
+    if (owner !== null && owner !== undefined) return true
+  }
+  if (typeof el.getAttribute !== 'function') return false
+  return el.getAttribute('aria-haspopup') === 'menu'
+    && el.getAttribute('aria-expanded') === 'true'
+}
+```
+
+接线：`document.addEventListener('focusout', e => { if (isSpuriousMenuBlur(e.target, e.relatedTarget)) e.stopPropagation() }, true)` —— **capture 相位在 React 的 root container 监听器之前跑**，所以 React 的 `onBlur` 收不到该事件。
+
+验证过的安全性：菜单外 `mousedown`（不依赖焦点）、`Escape`、`Tab`、以及任何 `relatedTarget` 是真实元素的 blur，全部照旧关闭；只有「从打开的菜单里 blur 到没有地方」这一种被压掉。段落需自带分号定界（相邻的 zoom 段以 `})()` 结尾、靠 ASI，裸语句会拼成 `})()var …` = SyntaxError）。
+
+---
+
+## 参考锚点
+
+- 上游组件：`packages/client/ui-model-selection/src/client/ModelSelect.tsx`（`onBlur` / `show` / `drill` / `close`）
+- 上游 WebKit 相关的两笔提交（**只修了鼠标路径**，rig 与 prod 都已包含）：`6613660223`（keep model picker focus during mouse selection）、`06ef26a80f`（preserve focus when toggling the model picker），分支 `fix/webkit-model-picker`
+- 上游 e2e：`apps/web/tests/declared-reasoning.e2e.ts`（Chromium + WebKit 双引擎，含 `pointer-menu` 快照）；其 WebKit 用例走的是 `page.mouse.down()`（**鼠标**），因此覆盖不到触摸相位
+- 相关实现：`packages/client/ui-primitives/src/client/MenuSurface.tsx`（rc.2 新增的菜单容器）

package/docs/specs/plugins-page-components/spec.md

@@ -0,0 +1,79 @@
+# plugins-page-components Specification
+
+## Purpose
+
+让 better-dsh 在原生 Plugins 页（`dsh-client-ui-plugin-manager`）上呈现与官方 bundle 同等的两件事：
+
+1. **卡片描述**：页面的 `BundleInfo.description` 直接取自包 manifest 的 `description` 字段；better-dsh 的 package.json 缺该字段导致卡片无描述。补齐为 awesome-dsh-plugins listing 的同款文案（单一事实源，两表面一致）。
+2. **组件化**：页面只把 bundle patch 的 **`insert` 行**列为可开关组件（每行一个 toggle，写 profile 用户层 `cordis.patch.yml` 的 `{id, disabled}` 覆盖行，HMR 即时生效）；非 insert 行只进 `overrides`（本页不显示）。现状 better-dsh 只有一条 insert（`dashr-repl`），整个插件是"一个组件"。本变更把 bundle patch 拆成 **6 条 insert**，每条 = 一个可独立开关的功能组件，映射原生 Agent Teams 的双组件形态。
+
+## Requirements
+
+### Requirement: 六组件行结构
+
+bundle patch（`cordis.patch.yml`）SHALL 恰好声明 6 条 insert 行，全部指向同一 npm 包 `better-dsh` 的子路径导出：
+
+| row id | module | 内容 |
+|---|---|---|
+| `dashr-repl` | `better-dsh` | 核心：kernel runtime + spin-up 供给检查 + `eval` + 三委派桥 + `llm_completion` + wire mask + escalation guidance |
+| `dashr-url-schemes` | `better-dsh/url-schemes` | URL 感知 I/O + hashline + devices（原 `DshUrlSchemes`，行配置载 `urlSchemes`/`hashline` gates） |
+| `dashr-failover` | `better-dsh/failover` | LLM failover 瀑布（settings 驱动，行配置 = 两个 fallback 槽） |
+| `dashr-compaction-tuning` | `better-dsh/compaction-tuning` | 自动压缩阈值偏好（settings 驱动） |
+| `dashr-web-trust` | `better-dsh/web-trust` | `webserver/index-inject` **authorities 腿**（`__DSH_TRANSPORT__.ownsHost`）；行配置 `trustedPageAuthorities`（schema 默认派生自 `DSH_TRUSTED_HOSTS`） |
+| `dashr-mobile` | `better-dsh/mobile` | `webserver/index-inject` **mobile 腿**（`__DASHR_MOBILE__` + zoomGuard 段）；行配置 = 原 `MOBILE_CONFIG` |
+
+#### Scenario: 页面呈现
+
+- **WHEN** 用户打开 Plugins 页的 better-dsh 卡片
+- **THEN** 卡片显示 listing 文案描述与 6 个组件行，每行可独立开关
+
+#### Scenario: 行开关落盘
+
+- **WHEN** 用户关闭任一组件行
+- **THEN** profile 用户层 patch 追加该 id 的 `{disabled: true}` 覆盖行，HMR 即时卸载该组件；重新打开则移除覆盖
+
+### Requirement: 配置键迁移（行 = 配置归属）
+
+`urlSchemes`、`hashline`、`trustedPageAuthorities`、`mobile` SHALL 从 `dashr-repl` 的 Config schema 移除，改由所属行的 schema 承载（schema 级默认逐键填充，跨 patch 覆盖层存活——v0.2.2a 裁决的延续）。config-file 用户改以行 id 为目标。
+
+#### Scenario: 行级 gates
+
+- **WHEN** `dashr-url-schemes` 行配置 `hashline: false`
+- **THEN** hashline read 锚点与 edit/undo 家族不安装，captured 原生 read 独立站立（既有 gate 语义不变，只是配置位置从核心行移到本行）
+
+### Requirement: 行间无注入边，排序无关
+
+任何组件行 SHALL NOT inject 另一组件行提供的服务；行为正确的唯一跨行约束——**capture-before-mask**（url-schemes 的继承面快照必须在 wire mask `restrict({deny})` 之前完成，快照保存被 mask 的委派工具定义）——SHALL 由 mask 监听器自身保证：mask 监听器第一步调用共享模块 `native-capture`（单例 chunk）的 `captureAllTools(agent)`（幂等，WeakMap 缓存），随后才 restrict。两个入口行（entry）的激活顺序因此无关紧要。
+
+#### Scenario: 顺序反转仍正确
+
+- **WHEN** cordis 激活顺序使 mask 监听器先于 url-schemes 的 session-start 监听器运行
+- **THEN** mask 先经 `captureAllTools` 固化 pre-mask 全量快照再 restrict；url-schemes 随后的 `captureNativeTools` 命中同一缓存，wrappers 照常安装（own-layer 注册不受已落限制过滤）
+
+#### Scenario: url-schemes 行关闭时桥不断
+
+- **WHEN** `dashr-url-schemes` 行关闭、`dashr-repl` 行开启
+- **THEN** mask 监听器的 capture 步骤照常固化快照，captured 委派工具定义仍可供读取；eval 与委派桥正常工作
+
+### Requirement: 双腿 boot script
+
+`buildBootScript` SHALL 拆为两个纯函数腿构建器：`buildTrustScript`（authorities 段）与 `buildMobileScript`（`__DASHR_MOBILE__` + zoomGuard 段），各自为空即注入 nothing；两行各自注册 `webserver/index-inject` 监听器（list 事件，`table.push` 天然可组合）。
+
+#### Scenario: 单腿开关
+
+- **WHEN** `dashr-mobile` 行关闭而 `dashr-web-trust` 行开启
+- **THEN** 页面仍注入 authorities 腿脚本，`__DASHR_MOBILE__` 缺席，client 移动手势/zoomGuard 保持惰性（client 半无改动，读页面全局缺席即休眠）
+
+### Requirement: override 行保持原样
+
+compaction 再启用三条（`compaction-basic`/`command-compact`/`tool-result-pruner`）与 `connection` fence 行 SHALL 保持 override 行形态。原生页面不列出 override 行（把再启用做成 insert 需 fork 上游插件模块，不采纳）。
+
+### Requirement: 描述单源
+
+package.json `description` SHALL 逐字采用 awesome-dsh-plugins listing 的 en 文案，使 Plugins 卡片与市场 listing 单源一致。
+
+## Out of Scope
+
+- npm publish（另行裁决，按发布红线走两道闸）。
+- `plugins.row.config` / `plugins.bundle.config` 配置表单（本变更只要求原生行开关；行配置仍走 config file）。
+- client half 改动（页面全局缺席即休眠的既有形态已满足）。