better-dsh 0.2.4-c → 0.2.5-a

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/superpowers/plans/2026-10-02-ctx-navigation.md

@@ -0,0 +1,319 @@
+# ctx:// Long-Session Navigability Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `ctx://` a navigable long-session surface: every coordinate it shows is addressable, digests are pointers not re-dumps, and landmarks/fidelity direct the model to what matters.
+
+**Architecture:** One handler file (`src/url-schemes/handlers/ctx.ts`) gains a transcript line index (single source of truth for line coordinates), transcript-relative episode windows, a digest-residence rule, a landmark/fidelity block, and `:path/`/`?q=` selector support via the existing `applySelector` in `selector.ts`.
+
+**Tech Stack:** TypeScript (ESM), Vitest, the `@deepseek-ai/dsh-*` harness peer types.
+
+**Spec:** `docs/superpowers/specs/2026-10-02-ctx-navigation-design.md` (algorithms) and `docs/specs/ctx/spec.md` (requirements). Executors read both.
+
+## Global Constraints
+
+- Coordinate invariant: every number shown is labeled (`seq=` or `lines=`) and directly addressable; transcript is the canonical line space.
+- Episode line windows are transcript-relative (`compactions[label]:N-M` ≡ `transcript:N-M`).
+- Out-of-span windows return an explicit boundary note, never a silent empty/truncated view.
+- Digest residence: latest episode's prepared face never re-dumps the digest; older episodes return their full digest; `:raw` always returns the span.
+- Landmarks and fidelity are capped to one screen and tail `… +N more`.
+- No semantic/vector retrieval. Phone book + index + pointer only.
+- `tsc --noEmit` 0 errors; `npx vitest run` green (baseline 641 passed / 1 skipped).
+
+---
+
+## Task 1: Transcript line index + episode `lines`
+
+**Files:**
+- Modify: `better-dsh/src/url-schemes/handlers/ctx.ts`
+- Test: `better-dsh/test/url-schemes/ctx.spec.ts`
+
+**Interfaces:**
+- Produces: `TranscriptIndex { text; totalLines; lineOfSeq: Map<number, {start,end}> }` (see design §3.1); each episode gains `lines: { start: number; end: number } | null` and `originalText` is derived from the transcript slice.
+
+- [ ] **Step 1: Add the failing test for episode line coordinates**
+
+```ts
+it('reports transcript line coordinates per episode and keeps the snapshot labeled', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  const ep0 = snap.compacted[0]
+  expect(ep0.lines).toBeTypeOf('object')
+  expect(ep0.lines.start).toBeGreaterThanOrEqual(1)
+  expect(ep0.lines.end).toBeGreaterThanOrEqual(ep0.lines.start)
+  // the manifest prints labeled lines= too
+  const manifest = await r.resolve({} as ResolverEnv, 'ctx://session/compactions', null)
+  expect(manifest).toMatch(/lines=\d+\.\.\d+/)
+  expect(manifest).toMatch(/seq=\d+\.\.\d+/)
+})
+```
+
+- [ ] **Step 2: Run it, confirm it fails** (`npx vitest run test/url-schemes/ctx.spec.ts` — `lines` is `undefined`)
+
+- [ ] **Step 3: Implement `buildTranscript` and derive episode `lines`/`originalText`**
+
+```ts
+interface TranscriptIndex {
+  text: string
+  totalLines: number
+  lineOfSeq: Map<number, { start: number; end: number }>
+}
+function buildTranscript(events: readonly PersistenceEvent[], toolNameOf: (s?: number) => string | undefined): TranscriptIndex {
+  const entries = events.map(e => ({ seq: e.seq as number, text: renderEntry(e, toolNameOf) })).filter(t => t.text !== '')
+  const lineOfSeq = new Map<number, { start: number; end: number }>()
+  let line = 1
+  for (let i = 0; i < entries.length; i++) {
+    const n = entries[i].text.split('\n').length
+    lineOfSeq.set(entries[i].seq, { start: line, end: line + n - 1 })
+    line += n + (i < entries.length - 1 ? 1 : 0)
+  }
+  return { text: entries.map(e => e.text).join('\n\n'), totalLines: line - 1, lineOfSeq }
+}
+```
+
+In `resolve`, replace the standalone `transcript()` closure with a single `const tIdx = buildTranscript(events, toolNameOf)` computed once (after `toolNameOf` is defined) and reuse `tIdx.text` everywhere `transcript()` was called. In the episode build loop, after `originalText` is assembled, set:
+
+```ts
+const shadowLines = d.shadowedSeqs
+  .map(s => tIdx.lineOfSeq.get(s)).filter((x): x is {start:number;end:number} => x !== undefined)
+const lines = shadowLines.length === 0 ? null
+  : { start: Math.min(...shadowLines.map(x => x.start)), end: Math.max(...shadowLines.map(x => x.end)) }
+const originalText = lines === null ? ''
+  : tIdx.text.split('\n').slice(lines.start - 1, lines.end).join('\n')
+```
+
+- [ ] **Step 4: Run the test, confirm it passes**
+
+- [ ] **Step 5: Commit** `git add better-dsh/src/url-schemes/handlers/ctx.ts better-dsh/test/url-schemes/ctx.spec.ts && git commit -m "feat(ctx): transcript line index + per-episode line coordinates (N1)"`
+
+---
+
+## Task 2: Transcript-relative episode windows + boundary note
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `applyEpisodeLines(slice: string, lineStart: number, lineEnd: number, ranges: Array<[number,number]>): string`.
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('episode line window is transcript-relative (≡ transcript window)', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const ep0 = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null)).compacted[0]
+  const viaEpisode = await r.resolve({} as ResolverEnv, `ctx://session/compactions[${ep0.label}]:${ep0.lines.start}-${ep0.lines.end}`, null)
+  const viaTranscript = await r.resolve({} as ResolverEnv, `ctx://session/transcript:${ep0.lines.start}-${ep0.lines.end}`, null)
+  expect(viaEpisode).toBe(viaTranscript)
+})
+
+it('out-of-span episode window returns an explicit boundary note', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const ep0 = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null)).compacted[0]
+  const out = await r.resolve({} as ResolverEnv, `ctx://session/compactions[${ep0.label}]:${ep0.lines.end + 1000}`, null)
+  expect(out).toMatch(/end of episode span|span is transcript lines/)
+})
+```
+
+- [ ] **Step 2: Run, confirm both fail**
+
+- [ ] **Step 3: Implement transcript-relative episode line application**
+
+```ts
+function applyEpisodeLines(slice: string, lineStart: number, lineEnd: number, ranges: Array<[number, number]>): string {
+  const lines = slice.split('\n')
+  const out: string[] = []
+  let noted = false
+  for (const [aRaw, bRaw] of ranges) {
+    const a = Math.max(1, aRaw); const b = bRaw === Infinity ? lineEnd : bRaw
+    if (b < lineStart || a > lineEnd) { noted = true; continue }
+    const la = Math.max(a, lineStart) - lineStart + 1
+    const lb = Math.min(b, lineEnd) - lineStart + 1
+    out.push(...lines.slice(la - 1, lb))
+    if (bRaw === Infinity ? false : b > lineEnd || a < lineStart) noted = true
+  }
+  const body = out.join('\n')
+  const note = noted ? `\n\n[ctx:// note: episode span is transcript lines ${lineStart}-${lineEnd}]` : ''
+  return body + note
+}
+```
+
+In the episode branch, when the episode has `lines !== null`, route `sel.kind === 'lines'` through `applyEpisodeLines(episode.originalText, episode.lines.start, episode.lines.end, sel.ranges)` instead of the shared `applyLines`.
+
+- [ ] **Step 4: Run, confirm both pass (the first test also proves the episode-span ≡ transcript-slice invariant)**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): transcript-relative episode windows + explicit span bounds (N1/F10)"`
+
+---
+
+## Task 3: Digest residence rule
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `episodeNavigation(episode, isLatest, checkpointLines) => string` (latest → navigation block, older → digest + pointer block).
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('latest episode prepared face is a navigation block without the digest text', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const latest = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[40]', null)  // label 40 is last
+  expect(latest).toMatch(/digest is already in your live context/)
+  expect(latest).toMatch(/digest resident .*seq=41/)
+  expect(latest).not.toMatch(/second round/)  // the digest body must NOT be dumped
+})
+
+it('older episode prepared face returns its full digest', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const older = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[20]', null)
+  expect(older).toMatch(/do the thing/)       // digest body present
+  expect(older).toMatch(/lines=\d+\.\.\d+/)
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** the checkpoint-line lookup (the `user/message` whose `source.plugin === 'compact'` at `checkpointSeq`, via `tIdx.lineOfSeq`, fallback `undefined`) and the two branches. Latest block shape (no digest): see design §4 (N2). Older: `episode.summaryText` + the pointer block. `:raw`/`:N-M` unchanged (span).
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): digest residence rule — latest is a pointer, older dumps digest (N2)"`
+
+---
+
+## Task 4: Landmark roster + fidelity
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `landmarksOf(episodeEvents, tIdx): string` and `fidelityOf(episodeEvents): { userTurns; toolCalls }`.
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('landmark block lists user-turn and failure lines and touched paths', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const out = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[20]', null)
+  expect(out).toMatch(/user turns \(\d+\): \d+/)
+  expect(out).toMatch(/touched paths:/)
+})
+
+it('manifest and snapshot carry fidelity', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  expect(await r.resolve({} as ResolverEnv, 'ctx://session/compactions', null)).toMatch(/fidelity=\d+:\d+/)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  expect(snap.compacted[0].fidelity).toEqual(expect.objectContaining({ userTurns: expect.any(Number), toolCalls: expect.any(Number) }))
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** `landmarksOf` (user turns = `user/message` with `source.kind==='user'` → `tIdx.lineOfSeq` line; failures = `tool/result` with `data.message.isError===true` or `data.error` present → line + tool name; touched paths = path-valued strings from `tool/call` args keys `path`/`file_path`/`filePath`/`file` + `edits[].path` + `files[].path`, args > 64 000 chars skipped; prior checkpoints = count of `user/message` with `source.plugin==='compact'`). Caps: 30 / 20 / 12. `fidelityOf` = counts of user turns and `tool/call` events. Wire into the episode block (Task 3), the manifest line, and the snapshot `compacted[]`.
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): landmark roster + fidelity signal (N3/N4)"`
+
+---
+
+## Task 5: `:path/` + `?q=` selectors + error echo
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Consumes `applySelector(text, sel)` from `../../src/url-schemes/selector.ts` (already exported).
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('supports :path/ on the snapshot JSON and ?q= on an index face', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const n = await r.resolve({} as ResolverEnv, 'ctx://session:path/totals.tool_calls', null)
+  expect(n).toMatch(/^\d+$/)
+  const q = await r.resolve({} as ResolverEnv, 'ctx://session/injections?q=agent-instructions', null)
+  expect(q).toMatch(/AGENTS\.md/)
+})
+
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** — in `applyFace`, before the `lines` branch:
+
+```ts
+if (selector.kind === 'path' || selector.kind === 'query') {
+  return applySelector(face === 'canonical' ? canonical : prepared, selector)
+}
+```
+
+Import `applySelector` from `../selector.ts` (add to the existing `import { UrlSchemesError }` line). Replace the manifest special-case rejection with `return applySelector(body, sel)` so `?q=`/`:N-M`/`:path/` all work there too. Keep the now-unreachable `CTX_BAD_SELECTOR` throw but give it a support-set message (`:raw`, `:N-M`, `:path/`, `?q=`) for future kinds.
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): :path/ and ?q= selectors (N5/F5/F8)"`
+
+---
+
+## Task 6: `asOf`, F1 index faces, F2 result shape
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('snapshot carries asOf', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  expect(snap.asOf).toEqual(expect.objectContaining({ seq: expect.any(Number), line: expect.any(Number) }))
+})
+
+it('bare element collections return index faces, not an empty-bracket error', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const idx = await r.resolve({} as ResolverEnv, 'ctx://session/user_prompts', null)
+  expect(idx).toMatch(/seq=\d+/)
+  expect(idx).toMatch(/hello world/)
+})
+
+it('flat tool-result content renders (F2)', async () => {
+  const closed = { value: false }
+  const flat: PersistenceEvent[] = [
+    { seq: 5, type: 'tool/call', time: T, data: { callId: 'c1', name: 'bash', arguments: '{"command":"echo hi"}' } },
+    { seq: 6, type: 'tool/result', time: T, sourceEventSeqs: [5], data: { message: { role: 'tool', isError: false, content: [{ type: 'text', text: 'hi' }] } } },
+  ]
+  const r = ctxResolver(closed, flat)
+  expect(await r.resolve({} as ResolverEnv, 'ctx://session/tool_calls[5]', null)).toMatch(/result: hi/)
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement**
+  - `asOf`: add `asOf: { seq: <max seq>, line: tIdx.totalLines }` to `buildSnapshot`.
+  - F1: give `user_prompts`/`tool_calls`/`agent_responses` a bare index face (per-element `seq=<s> <preview>`), capping `tool_calls`/`agent_responses` at 20 lines with a `… +N more` tail; `[n|seq]` and `:raw` unchanged. Update the element error to name the collection + count (no `ctx://…[]`).
+  - F2: `resultTextOf` returns `nested !== '' ? nested : textOf(blocks)` (flat fallback; see design §3.3).
+
+- [ ] **Step 4: Run full suite** `npx vitest run` and `npx tsc --noEmit` — all green.
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): asOf, element index faces, flat tool-result rendering (N6/F1/F2)"`
+
+---
+
+## Task 7: Docs, rig verification, report
+
+**Files:** `docs/specs/ctx/spec.md` (already updated), `better-dsh/dashr/url-schemes-instruction.md` (model-facing instruction, if it lists selectors — verify and add `:path/`/`?q=`/transcript-relative note), `docs/50_test-reports/2026-10-02-ctx-navigation实测报告.md`.
+
+- [ ] **Step 1:** Grep `better-dsh/` for the model-facing `url-schemes` instruction doc and update the ctx selector list if present.
+
+- [ ] **Step 2:** Rebuild + sync: `cd better-dsh && npm run build && cd .. && rsync -a --delete better-dsh/lib/ .test/home/compat/profiles/web/node_modules/better-dsh/lib/` and restart `bash .test/seed/test123/start.sh`.
+
+- [ ] **Step 3:** First-person verify on 4999 via `dvc://browser` and a `headless` rigcheck session: snapshot has `asOf` + labeled `lines`; a deep episode windows by transcript line; `?q=` filters an index; `:path/` narrow-reads; a tool result is non-empty.
+
+- [ ] **Step 4:** Write the test report to `docs/50_test-reports/2026-10-02-ctx-navigation实测报告.md` (findings, probes, verdict).
+
+- [ ] **Step 5: Commit** `git commit -am "docs(ctx): navigation change — instruction + first-person test report"`