better-dsh 0.2.3 → 0.2.4

package/docs/50_test-reports/2026-09-13-hashline-off/344/270/213scheme/345/217/257/350/276/276/346/200/247/345/267/245/345/205/267/351/235/242/344/270/215/345/257/271/347/247/260-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,246 @@
+# hashline:false 配置下 URL scheme 可达性的**工具面不对称** — 实测报告
+
+- 日期：2026-09-13
+- 被测对象：`dashr/src/url-schemes/` 七类 URL scheme（`skill://`、`agent://`、`dsh://`、`ctx://`、`dvc://`、`http(s)://`）在**当前活体配置**下的 `read`/`grep`/`glob`/`write` 行为。
+- 被测运行时：**本 agent 自己所在的活体实例** —— `dsh web` @ `http://127.0.0.1:4999`，`DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`，`DSH_SESSION_ID=session-1ae1181e-abb7-4d59-939e-f5e0400a4258`，cwd `/home/u1/workspaces/dashr`。
+- 方法：**第一人称实测**。全部调用由本 agent 在真实 runtime 中发出（`read`/`grep`/`glob`/`write` 工具），无静态推断。被观测返回值原文摘录于 §3。
+- change：无（系统冒烟，非某 change 的验收）。
+- 关联：`2026-09-12-fs-scheme-resolution-实测报告.md`、`2026-09-12-url-schemes-六scheme冒烟与边界实测报告.md`（差异见 §5）。
+
+---
+
+## 0. 结论速览
+
+| 判定项 | 结果 |
+|---|---|
+| `dsh://` / `dvc://` / `http://` 在 `read` 上可达 | ✅ |
+| `skill://` 在 `read` 上 | ✅ **已收口（2026-09-13 user 裁决后返工）**：不再查 registry——`isSessionLayerScheme` 在 `wrap.ts` 与 `sandbox-plugin.ts` 双处纳入 `skill://`，直接抛结构化 `CTX_SESSION_LAYER` 边界错误，文案可执行（指 `skill` 工具 / `grep`,`glob path=skill://…`）；活的假 "unknown" 消失，`sessionCwd`/`scopedAwareSkills`/`URL_SKILL_NOT_INVOCABLE_SCOPE` 死代码在 src/副本/活体 bundle 全 0 命中（user 第二轮亲自复验） |
+| `https://` 在 `read` 上可达 | ✅ 已修（`HTTP_SCHEMES` 循环登记）并两轮复验存活 |
+| 同一批 scheme 在 `grep`/`glob` 上可达 | ✅ `ctx://`、`agent://`、`skill://`、`https://` 全部可达（§2、§3） |
+| 根因 | **`hashline:false` 使 DASHR 的 `read` 包装不安装 → `read` 退化为平台原生工具 → 只剩 FS 层 resolver；`grep`/`glob`/`write` 包装仅由 `urlSchemes` 门控，仍在场 → 走工具层 resolver** |
+
+**一句话**：不是 scheme 坏了，是**同一实例里 `read` 与 `grep`/`glob`/`write` 分属两套 resolver**。`hashline:false` 配置下，会话型（`ctx://`/`agent://`）只经 `grep`/`glob` 抵达，`read` 是死的；`https://` 更因 FS 层只登记了 `http` 而整条断掉。
+
+> **2026-09-13 收口更新（user 第二轮复验确认）**：`https://` 已修（两轮活体存活）；`skill://` 按业务逻辑归属裁决重分类为会话型边界（§4 P1-skill 处置块），行为收窄（全局技能亦不在 FS 层解析）但文案已指替代路径，`grep`/`glob` 回退复验通过。
+---
+
+## 1. 环境与配置锚定
+
+### 1.1 配置来源（profile 层唯一）
+
+`.dsh-test/profiles/web/cordis.patch.yml`（0.1.5-rc.2 无 home patch 层，故 `.dsh-test/cordis.patch.yml` 空）：
+
+```yaml
+- id: dashr-repl
+  config:
+    python: !!js process.env.DASHR_KERNEL_PYTHON ?? 'python3'
+    snapshotDir: /home/u1/workspaces/dashr/.dsh-test/snapshots
+    hashline: false        # ← 关键
+    urlSchemes: true
+
+- id: fs-sandbox
+  name: './node_modules/better-dsh/lib/fs-aware/sandbox-plugin.js'
+  config:
+    urlSchemes: true
+```
+
+### 1.2 活体日志佐证
+
+`.scratch/dsh-4999.log`（每个 session-start 一行）：
+
+```
+DEBUG-INSTALL gates: {"urlSchemes":true,"hashline":false}
+```
+
+### 1.3 工具面身份判定（决定性）
+
+当前 `read` 工具**不是** DASHR 的 URL-aware read：
+
+| 证据 | 值 |
+|---|---|
+| 工具入参名 | `file_path`（DASHR 包装用 `path`，见 `url-schemes/tools/read.ts:92`） |
+| 输出形态 | 行号前缀 `N: content`（DASHR 包装 scheme 分支返回原文、文件分支返回 `HASH│content`） |
+| 包装注册门 | `url-schemes/index.ts:188` `if (gates.hashline) { …register(createReadTool…) }` → `hashline:false` 即不注册 |
+| 注释自证 | `index.ts:158-159`：**"`hashline: false` → read wrapper 不安装（captured 原生 read 独立站立，scheme 解析由挂载的 FS 后端承担）"** |
+
+`grep`/`glob`/`write` 的注册门是 `urlSchemes`（`index.ts:197`、`266-268`），故**仍在场**，走工具层 resolver。实测 `write dsh://config` 报的是 `url-schemes/tools/write.ts:130` 的文案、`write dvc://ast_grep` 成功派发，均可交叉印证工具层包装在场。
+
+### 1.4 两套 resolver 的登记差异（根因表）
+
+| resolver | 构造点 | 登记 schemes | 环境字段 |
+|---|---|---|---|
+| **工具层**（read/grep/glob/write 包装消费） | `url-schemes/index.ts:283-328` | `skill`、`agent`、`dsh`、`dvc`、`ctx`、**`HTTP_SCHEMES = ['http','https']`** | `{ agent, cwd, rawUrl }`（`tools/read.ts:119-121`、`tools/grep.ts:69`） |
+| **FS 层**（原生 read/grep/glob 经 `ctx.fs` 消费） | `fs-aware/wrap.ts:49-59` | `skill`、`dsh`、`dvc`、**仅字面 `http`** | 仅 `{ fs, rawUrl }`（`wrap.ts:81`，**无 agent/cwd**） |
+| **FS 层会话型守卫** | `wrap.ts:37-46`、`99-115` | `ctx://`/`agent://` → 结构化 `CTX_SESSION_LAYER` | — |
+
+两处差异直接产生全部四个失败：`https` 未登记、`ctx`/`agent` 被守卫、`skill` 缺 `cwd`+`scope`。
+
+---
+
+## 2. scheme × 工具 可达性矩阵
+
+（✅ 实测可达；❌ 实测失败；`—` 本轮未测）
+
+| scheme | `read`（原生 / FS 层） | `grep`（工具层） | `glob`（工具层） | `write`（工具层） |
+|---|---|---|---|---|
+| `dsh://` | ✅ 列表/配置/选择器 | ✅（`path: dsh://docs` 命中 4 行） | ✅（`dsh://docs/subsystems` → 116 文件） | ❌ 只读（`tools/write.ts:130`） |
+| `dvc://` | ✅ roster + 各设备文档 | — | — | ✅ 三设备真派发（`ast_grep`/`ast_edit`/`browser`） |
+| `http://` | ✅（`example.com` 抓回） | — | — | ❌ 只读 |
+| `https://` | ❌ **未登记** | ✅（`example.com` 命中） | — | — |
+| `skill://` | ❌ **unknown** | ✅（`book-to-skill` 命中 560 行/约 130 文件） | ✅（全部文件路径列出） | ❌ 只读 |
+| `ctx://` | ❌ **边界错误** | ✅（`user_prompts[0]` 命中本轮首条 prompt） | — | — |
+| `agent://` | ❌ **边界错误** | — | ✅（物化到 `/dev/shm`） | — |
+
+`dsh://` 选择器四形态在 `read` 上全通：`:N-M`、`:raw`（与 `:raw:N-M` 等价）、`:path/agent-loop`、`?q=`。
+
+---
+
+## 3. 原始观测（判定依据，原文摘录）
+
+### 3.1 `read` 侧四个失败
+
+```
+read dsh://docs                      → ✅ 251 条文档索引
+read dsh://config:path/agent-loop    → ✅ {"maxParallelToolCalls":10}
+read dsh://docs/tool-catalog.md?q=ui-deliverables → ✅ 过滤命中 1 行
+
+read skill://book-to-skill           → ❌ skill "book-to-skill" is unknown or no longer available
+read skill://book-to-skill/SKILL.md  → ❌ 同上（子路径无效，仍是 registry 查无此名）
+read ctx://session/transcript:1-8    → ❌ CTX_SESSION_LAYER: session-layer scheme — read it through the read tool (…)
+read ctx://session/compactions       → ❌ 同上
+read agent://                        → ❌ 同上
+read https://example.com             → ❌ no handler registered for scheme "https" (registered: dsh, dvc, http, skill)
+```
+
+后者的 `registered: dsh, dvc, http, skill` 是 **FS 层 resolver 的登记表**，直接坐实 `read` 走的是 FS 层。
+
+### 3.2 `grep`/`glob` 侧全通（反证）
+
+```
+grep  path=skill://book-to-skill  pattern=^#      → ✅ 560 matches（真实落到 .agents/skills/book-to-skill/*）
+glob  path=skill://book-to-skill  pattern=*       → ✅ 约 130 条文件路径
+grep  path=ctx://session/user_prompts[0] pattern="test your tools"
+                                                  → ✅ 1 match:/dev/shm/dashr-url-UTBpHR/content.txt:2
+grep  path=https://example.com    pattern="Example Domain"
+                                                  → ✅ 1 match:/dev/shm/dashr-url-NqMEfC/content.txt:3
+glob  path=agent://               pattern=*       → ✅ /dev/shm/dashr-url-6h2V9Y/content.txt
+```
+
+并可见 `ctx://` 选择器语法细节：集合下标是 **0-based 方括号**，标签为事件 seq：
+
+```
+grep path=ctx://session/user_prompts pattern=… → ❌ ctx://…[]: no such element
+                                                  (collection "user_prompts" has 2 items, 0-based; labels are event seqs)
+```
+
+### 3.3 `write` 侧
+
+```
+write dsh://config   {…}   → ❌ write to dsh:// is not supported (read-only scheme, or its write channel is not wired yet)
+write dvc://ast_grep {patterns:[…] path:/abs} → ✅ 结构化 payload 完整渲染（含 matches/totalMatches/parseErrors）
+write dvc://ast_edit {ops:[…] dryRun:true}    → ✅ {"applied": false, …}（dryRun 生效，未落盘）
+write dvc://browser  {"action":"open"|"close"} → ✅ {"ok":true,"url":"about:blank"} / {"ok":true}
+```
+
+**`dvc://` 设备 payload 已被完整渲染进工具结果**（见 §5 与旧报告的差异）。
+
+### 3.4 旁路发现
+
+1. **`dvc://` 设备相对路径以服务端 cwd 为根，不是会话 workspace。** `path:"."` 全量搜了 monorepo checkout（6950 文件，返回 `../../dashr/src/...`）；`path:"dashr/src"` 直接 `Path not found`；绝对路径才命中（163 文件）。设备 cwd = `upstream/deepseek-harness`。
+2. **`ast_grep` 的 `export function $NAME` 形态静默 0 命中**，而 `function $NAME` 在同一路径命中 646。导出声明的 pattern 形态在本 vendored 实现下**不报错也不匹配**（部分语言另报 `Multiple AST nodes are detected`）。
+3. **发布面残留调试日志**：`url-schemes/index.ts:154` 与 `:337` 仍有 `console.log('DEBUG-INSTALL …')`，并已在 4999 日志里逐 session 打印。
+4. **会话指引与部署面不符**：本 session 收到的 URL scheme 指引把 `read` 描述为 `HASH│content` 锚点读；`hashline:false` 下实际是原生行号读。指引来源疑为 `renderGeneralSectionText()` / `generalSection()`（`index.ts:263`、`catalog.ts:135`），建议门控对齐。
+
+---
+
+## 4. 发现清单
+
+### P1 — `https://` 在 FS 层未登记（一行修复，✅ 2026-09-13 复验存活）
+
+`fs-aware/wrap.ts:57` 写死 `resolver.register('http', createHttpHandler())`，而工具层正确循环 `HTTP_SCHEMES = ['http','https']`（`handlers/http.ts:45`）。`hashline:false` 时 FS 层是 `read` 的唯一路径 → `read https://…` 恒失败。修法：`buildFsLayerResolver` 同样 `for (const s of HTTP_SCHEMES) resolver.register(s, handler)`。skill:// 重分类重构后复验：`read https://example.com` 正常抓取（session 60418790）。遗留小项（与本次无关，记录在案）：`read https://example.com:1-3` 这类**把行选择器写进 URL** 的形态会整串进 `new URL()` 报 invalid URL——http handler 不剥选择器后缀，dsh handler 剥（`dsh://docs:1-3` 正常）；属探针写法与既有限制，非本次回归。
+
+### P1 — `skill://` 在 FS 层丢失 agent/cwd（workspace 技能全不可见）
+
+`wrap.ts:81` 只给 `{ fs, rawUrl }`；`handlers/skill.ts:106-113` 的 `lookupOptions` 需要 `cwd` + `scope`，两者皆缺时 workspace 作用域技能层读作 absent → 全部 `unknown`。FS 层结构性拿不到 agent，所以要么把 skill 解析留在工具层、要么在 `hashline:false` 下补一条 scheme 呈现通道。
+
+> **处置（2026-09-13 user 裁决后重定方向，推翻本报告早前的"补通道"方案）**：第一版补通道（sessionCwd 配置 + scopedAware list 启发式）经活体证伪——dump-config 实证 **dsh-web-app bundle patch 在宿主层 disable 了 `skill-filesystem`/`tool-skill`**，web profile 全局层没有任何 skill provider，list 与 get 同空，启发式从未命中（A/B 活体：user-global 的 `skill://markitdown` 与 project 的 `skill://book-to-skill` 双双 `unknown`，session 8b6dcf85）。根因不是"缺 cwd"，而是**技能加载路径解析（CWD/user-global/app 运行时根、扫描深度）是宿主 `dsh-skill-filesystem` 的业务逻辑**，FS 层不得自写近似版。最终处置：`skill://` 重分类为会话层 scheme，FS 层一律答 `CTX_SESSION_LAYER` 边界错误（指名原生 `skill` 工具）；`sessionCwd` 配置整体移除；工具层 handler lookup 收敛为 `dsh-tool-skill` 的精确镜像。详见 `2026-09-12-fs-scheme-resolution-实测报告.md` §4d 与 change design.md §D6。
+>
+> **活体复验（session 37899b26 / bfa99754 / f12a206e / 60418790 / 029aa5bb，2026-09-13）**：`read skill://book-to-skill` → 结构化边界错误（指名原生 skill 工具）；`read skill://markitdown:1-5` → 同（与技能名无关）；**原生 `skill` 工具加载 `book-to-skill` 成功**（完整 `<skill_content>` + resourceBase）；`grep path=skill://book-to-skill pattern=^#` → 560 matches（工具层通道完好）；`read https://example.com` → 正常抓取（P1-a 存活）。
+>
+> **user 第二轮复验（2026-09-13，第一人称）**：lib 02:32 重建 → 02:33 重启；规范源与副本三文件逐字节一致；`https://` / DEBUG-INSTALL / gate 注释 / `skill://` 收口四项全过；`sessionCwd`、`scopedAwareSkills`、`URL_SKILL_NOT_INVOCABLE_SCOPE` 在 src/副本/**活体 bundle** 三面 **0 命中**；`grep path=skill://` 回退复验通过。user 点评：**"以承认边界替代假装能查"是对的**——上轮 `list({cwd})` 无 scope 读不到 workspace 技能（宿主 `SkillViewOptions` 明写 "omitted reads the global layer alone"）本是不可达探针；定性为会话型比修探针干净。行为收窄代价（全局技能亦不在 FS 层解析）已被可执行文案覆盖。user 唯一未亲自引爆文案指向的原生 `skill` 工具（agent probe session f12a206e 已验加载成功）。
+>
+> **user 复验带出两处小瑕疵，本轮已修**：① `sandbox-plugin.ts` 的 `buildResolver` 有**重复的 `register('dsh', …)` 块**（改 skill 块时拼接失误；`register` 是 `handlers.set`，覆盖不抛错，纯死代码）且 `'http'` 仍是字面量未跟 `HTTP_SCHEMES` 对齐（当前非最外层故潜伏，挂载顺序一翻 https 即静默回归）→ **删除私有登记面，`buildResolver` 改为复用 `wrap.ts` 的共享 `buildFsLayerResolver`**（登记单源，双消费方永不再漂移；其 `ctx`/`agent` handler 在本类不可达——前置守卫先拦）；② `url-schemes/index.ts` 两个同名 `export interface Config`（sessionCwd 增删残留）→ 并回一个。单测断言同步：https 注册性检查改为网络无关（成功/取数失败皆证登记，唯 "no handler" 才是回归）。收口烟测（session 0335526e，重启后）：`skill://` 边界 / `https://` 抓取 / `dsh://docs:1-3` 三连全过；回归 vitest 489/14 基线族、tsc 13、openspec valid。
+
+### P2 — `hashline:false` 下会话型 scheme 无 `read` 通道，且注释与事实不符
+
+`index.ts:288-290` 声称 *"Session-layer schemes (ctx://, agent://) answer the structured boundary error here; **the read tool's scheme branch keeps serving them with the calling agent's context**"* —— 该 "read tool's scheme branch" 只在 `hashline:true` 时存在。`hashline:false` 下 `ctx://`/`agent://` 在 `read` 上无任何通道（`grep`/`glob` 可用，但那是另一个工具面的补偿，不等于 read 通道）。注释与 `index.ts:158-159` 的 gate 说明应统一。
+
+### P2 — 发布前清理 `DEBUG-INSTALL` 调试 `console.log`
+
+`url-schemes/index.ts:154`、`:337`。
+
+### P3 — `ast_grep` 导出形态 pattern 静默漏报
+
+建议在设备文档或实现里显式声明支持的 pattern 形态（或对 0 命中且 pattern 含 `export ` 时给出提示）。
+
+### P3 — `dvc://` 设备根目录与会话 workspace 不一致
+
+易误伤脚本化调用（相对路径静默落到别的树）。建议设备文档写明"相对路径以服务端 cwd 为根"，或与 `ctxFsIO` 的 workspace 对齐。
+
+### P3 — 会话指引把 `read` 描述为 `HASH│content` 锚点读，`hashline:false` 下实为行号读
+
+`url-schemes-instruction.md`（owner 维护）对 read 输出的描述按 hashline 锚点语义书写；`hashline:false` 活体下 read 实际返回行号形式。建议按 gates 加一句条件说明（2026-09-13 复核：三项 P3 均无变化、未复测，挂账）。
+---
+
+## 5. 与既有报告的差异（待对齐）
+
+| 项 | 既有报告 | 本轮观测 | 研判 |
+|---|---|---|---|
+| `read` 上六 scheme 全可达 | `2026-09-12-url-schemes-六scheme冒烟与边界实测报告.md` §0：**✅ 6/6** | `read` 上 `ctx`/`agent`/`skill`/`https` **全 ❌** | **两次实测的 `gates` 不同**：该报告应以 `hashline:true`（DASHR read 包装在场）跑出；本轮为 `hashline:false`。二者不矛盾，但结论必须带配置标签——"六 scheme 可达"仅在 `hashline:true` 成立 |
+| `glob` 的 URL-in-`path` 分支在 `dsh://docs` 失效 | 同上 §0：⚠️ 失效 | ✅ 正常（`glob path=dsh://docs/subsystems` → 116 文件） | 疑似已修或与 `hashline` 门控相关，建议复测后销项 |
+| `dvc://` 设备 payload 在渲染面丢失 | 同上 §0：❌ 缺口（只输出 `Executed dvc://<device>`） | ✅ payload 完整渲染（§3.3） | **该缺口在当前构建已不复现**，建议销项 |
+| FS 层 = dsh/dvc/http(s)，会话型（含 `skill://`）走边界错误 | `2026-09-12-fs-scheme-resolution-实测报告.md` §1/§2（D2） | 一致（skill 已并入会话型族） | ✅ 与本轮 §1.4 吻合；**2026-09-13 起 FS 层登记面 = dsh/dvc/http/https（`HTTP_SCHEMES` 共享 builder），`skill://` 归入会话型边界** |
+| `skill://` 假 "unknown"（本报告 §1.4/探针清单） | —（本报告当时的活体事实） | **✅ 已消灭**：user 第二轮复验（2026-09-13）——规范源/副本/活体 bundle 三面逐字节核验，`sessionCwd`/`scopedAwareSkills`/`URL_SKILL_NOT_INVOCABLE_SCOPE` 全 0 命中；活体 `read skill://…` 恒答可执行边界文案 | **按业务逻辑归属裁决返工**（`4c21c94` + 本轮清理）：技能路径解析/扫描深度属宿主 `skill-filesystem`，插件不再自写近似版；user 唯一未亲自引爆的是文案指向的原生 `skill` 工具本身（agent 前序 probe session f12a206e 已验：完整 `<skill_content>` 加载成功） |
+
+**建议**：两份 09-12 报告在标题或结论处补注其 `gates.urlSchemes/hashline` 取值，否则后来者会据"6/6"误判 `read` 可用性。
+
+---
+
+## 6. 未覆盖面（诚实声明）
+
+- `grep` 未测 `dvc://`、`agent://`、`http://`；`glob` 未测 `ctx://`、`http(s)://`、`dvc://`（矩阵中以 `—` 标注）。
+- `write` 仅测 `dvc://`（三设备）与 `dsh://`（只读拦截）；未测 `ctx://`/`agent://`/`skill://` 写拦截的具体错误分类器。
+- 未测 `hashline:true` 组合作对照（本轮无该实例），故 §5 的"配置差异"为**推断**，需一次 `hashline:true` 复跑坐实。
+- 未测 `skill://` 的**全局（非 workspace）技能**路径——它们可能不依赖 cwd，若存在则 FS 层 `skill://` 并非全灭。
+- 未覆盖工具：`eval` 桥（`await tool.*` 内调用 scheme）、`present`、`subagent`、`workflow`、`agent_message`、`web_search`、`web_fetch`、`goal_*`、`todo_write`、`ask_user_question`。
+- 未做 `tsc`/`vitest`——本轮是活体冒烟，非 change 验收。
+
+---
+
+## 附：探针清单（可复现）
+
+```
+# read（原生 / FS 层）
+read dsh://docs
+read dsh://config:path/agent-loop
+read dsh://docs/tool-catalog.md?q=ui-deliverables
+read skill://book-to-skill            # ❌ unknown
+read ctx://session/transcript:1-8     # ❌ CTX_SESSION_LAYER
+read agent://                         # ❌ CTX_SESSION_LAYER
+read https://example.com              # ❌ unregistered
+read http://example.com               # ✅
+
+# grep / glob（工具层）
+grep path=dsh://docs pattern=trustedHosts
+glob path=dsh://docs/subsystems pattern=*.md
+grep path=skill://book-to-skill pattern='^#'
+grep path=ctx://session/user_prompts[0] pattern='test your tools'
+grep path=https://example.com pattern='Example Domain'
+glob path=agent:// pattern='*'
+
+# write（工具层）
+write dvc://ast_grep {"patterns":["function $NAME"],"path":"/home/u1/workspaces/dashr/dashr/src","limit":3}
+write dvc://ast_edit {"ops":[{"pat":"console.log($$$A)","out":"logger.info($$A)"}],"paths":[…],"dryRun":true}
+write dvc://browser {"action":"open","url":"about:blank"} ; write dvc://browser {"action":"close"}
+write dsh://config "nope"             # ❌ read-only
+```

package/docs/50_test-reports/2026-09-13-preact-ui-shell/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,50 @@
+# 2026-09-13-preact-ui-shell 实测报告
+
+- change: `2026-09-13-preact-ui-shell`（openspec valid）
+- 依据: `~/workspaces/superd/apps/ui-preact` PoC（2026-09-09，0.1.3-alpha.2 + superd 伺服路径）
+- gates: 测试线 4999，`urlSchemes:true + hashline:false + preact shell build`
+- 结论先行: **shell 渲染引擎已换 Preact**（只 preact，无 @preact/signals——user 2026-09-13 裁决），全上游 UI 语料零改动获得 Preact 渲染；shell index chunk **555,959 → 434,173 B（−21.9%）**；浏览器级 A/B 实测挂载面与 stock 完全一致。
+
+## 1. 改动面（全部属 monorepo 本地 patch，不入 upstream git）
+
+| # | 改动 | 说明 |
+|---|---|---|
+| 1 | `apps/web/vite.config.ts` `resolve.alias` +5 条 | react / react/jsx-runtime / react/jsx-dev-runtime / react-dom / react-dom/client → preact/compat 家族（regex 锚定，防 `react-dom` 先命中 `react`） |
+| 2 | 同文件 `resolve.dedupe` + `'preact'` | dedupe 条目从本包 node_modules 解析——**缺它必挂**：seed importer 在 `packages/client/web/lib`，node 向上走看不到 `apps/web/node_modules/preact`（报 `Could not load preact/compat`） |
+| 3 | `apps/web/package.json` devDeps + `preact@10.29.8` | 精确 pin 对齐 PoC；仅 devDep，发布面无它 |
+| 4 | `vendor/{AGENTS,CLAUDE,README}.md` → `vendor/docs/` | **根除 `vendor/CLAUDE.md` ENOTDIR/exit 236 老坑**（见 §4） |
+
+AGENTS.md §二 harness 本地 patch 已记档（换 tag 需重放）。
+
+## 2. 体积（实测）
+
+| chunk | stock | preact build | Δ |
+|---|---|---|---|
+| `index-*.js`（react 家族 rides index） | 555,959 B | 434,173 B | **−121,786 B（−21.9%）** |
+| `vendor-*.js`（react-free，katex/shiki/markdown 管线） | 740,575 B | 740,575 B | 0（设计内） |
+
+## 3. 浏览器级 A/B 验证（playwright，同脚本双跑）
+
+| 断言 | stock React build | preact build |
+|---|---|---|
+| UI 语料挂载（侧栏/会话列表/Settings/输入框文本） | ✅ 全 | ✅ 全（逐字一致） |
+| `#root button` 数 | 31 | 31 |
+| composer（textarea/contenteditable） | 1 | 1 |
+| console.error | 0 | 0 |
+| shell 内 react-dom 痕迹 | **`version:"18.3.1", rendererPackageName:"react-dom"` banner 在 shell** | **无**（唯一 `react-dom` 字串 = 平台模块种子表键 `{react:Y3, "react-dom":Y3, ...}`——同一个 preact 实例登记两个平台词，设计终态） |
+| pageerror | slot 重复注册 ×1 | slot 重复注册 ×1 |
+
+**pageerror 定责（A/B + 发布前验尸修正）**：`settings.general.item` slot id `compaction-tuning` 重复注册在 **stock 上同样存在**（factory id `Ba` vs `f5` 仅 minified 差异）→ 与渲染引擎无关。**根因（publish 前验尸确认）**：canonical 树里有一份**未提交的半成品 compaction-tuning 吸收工作**（`src/compaction/` + `installCompactionTuning` 接线，随 rsync 进入 4999 副本），与 `.dsh-test` profile 仍挂着的 local-plugin 版 compaction-tuning **同 id 注册两次**——两因叠加。该半成品已 `git stash`（带说明消息）移出 0.2.3-e 发布内容，续作时须先摘除 profile 的 local-plugin 行再合入。`better-dsh/client.js` 内的 `react-dom` 匹配为 pnpm 依赖路径字符串（`@tanstack+react-virtual@…_react-dom@18.3.1…`），stock/preact 两面同在，非本体。
+
+**user 未亲自引爆项声明**：深交互面（聊天流式渲染、shiki 高亮、markdown 管线）未逐项人工过——零 console.error 为强信号非穷尽证明（PoC 同款边界声明）。
+
+## 4. 顺带根除：`vendor/CLAUDE.md` ENOTDIR/exit 236 老坑
+
+`vendor/` 根下三个文档文件（AGENTS/CLAUDE/README.md）撞 `pnpm-workspace.yaml` 的 `vendor/*` workspace glob：任何 workspace 枚举器读 `<条目>/package.json`——目录 ENOENT（容忍跳过），**文件 ENOTDIR（炸）**。历史受害面：`npm run build-client`（2026-09-03 记档）、本轮 `npx vite build`（exit 236、裸单行错误）。已移入 `vendor/docs/`（目录无 package.json → ENOENT 跳过）。换 tag 重放时记得同款处理。
+
+**新坑记档**：`pnpm add` 之后 `npx vite` 从根解析到 **vite 8/rolldown**（错误形态完全不同）——web 构建一律走 `pnpm run build:web`（workspace 内 vite 6.4.3）。
+
+## 5. 范围裁决
+
+- **不入 better-dsh npm 发布物**：本 change 是测试线 monorepo 本地 patch。插件若要随发布把 Preact UI 带到 prod，必须附带 preact 前端 dist + web-runtime override 行（PoC 路径 B 已在 0.1.3-alpha.2 验证可行）——代价是 UI 语料冻结在 fork 点，且 prod host（0.1.3-alpha.2）与测试线（0.1.5-rc.2）语料版本错位。**该决定挂 prod host 升级门下，另行裁决。**
+- 因此本轮 npm alpha（0.2.3-e）的插件内容不含 Preact——发布内容 = url-schemes 系（skill:// 收口等）+ 本轮清理。

package/docs/50_test-reports/2026-09-14-4999-skill/346/270/205/345/215/225/344/270/216lsp-gate/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,63 @@
+# 4999 实测报告 — skill:// 空路径清单 + lsp gate/fan-out（2026-09-14）
+
+## 被测构建
+- canonical：`dashr/dashr` @ `0da6a9f`（skill:// bare list）+ `84a98dc`（lsp parity stages 2/3/5）+ `3a94ce1`（stage 4）+ `7373d4e`（gate）
+- 部署：rsync → monorepo `packages/better-dsh/better-dsh`（tsdown + build-client）→ 4999 实例（unit `dsh-4999-test`，DSH_HOME=`.dsh-test`）重启后验证。
+
+## 方法
+真实 agent 会话（headless Chrome CDP 驱动 GUI，复用 `.scratch/cdp-chat.mjs`），会话 `session-3dc1ae5b`（workspace `--home-u1-workspaces-dashr--`），prompt 指示执行指定 tool call 并原样回报输出；tool result 从 session v3 jsonl（zstd）落账本取证。
+
+## 结果
+
+### 1. 裸 `skill://` → 可用技能清单 ✅
+`read skill://`（无名字）返回 cwd 范围技能目录（`N available skill(s):` + 逐条 `skill://<name> — <description> (use when: …)`），实际返回 11 条（book-to-skill … markitdown），与会话 skill catalog 一致。此前"returns nothing"的空白路径消除。
+
+### 2. `write dvc://lsp {"action":"status"}` ✅
+返回 `{"ok":true,"gate":"unasked"}` —— gate 动作走通，session id 由 write 分发器自动注入，agent 无需手填。
+
+### 3. `{"action":"diagnostics","file":"<abs .ts>","all":true}` fan-out ✅
+```json
+{ "ok": true, "fanout": true,
+  "servers": ["typescript-language-server","biome","eslint","denols","tailwindcss"],
+  "diagnostics": [],
+  "summary": "fan-out …/src/index.ts: 0 diagnostic(s) across 5 server(s) — …" }
+```
+5 个覆盖 .ts 的注册 server 全部被查询、合并、按 server 标注，无崩溃。
+
+### 4. 结构化错误路径 ✅（负例）
+相对路径 `dashr/dashr/src/index.ts`（相对 session cwd 不存在）→ 结构化 `file not found: <cwd>/…`，非崩溃非静默。
+
+## 结论
+本轮三项改动（skill:// 清单、lsp gate、fan-out 诊断）在 4999 真实运行时第一人称实测通过。单测侧：lsp-device 22 过、lsp-gate 5 过、skill.spec 17 过；tsc/构建绿。
+
+## 遗留
+- 真实 language server 端到端诊断（安装 pyright/ts 后取非空诊断、didOpen/didSave 同步行号对齐）未覆盖——本机当时无 server 二进制，fan-out 返回 0 视为"无 server/干净"两可；待装齐后补测。
+- gate on 后的 warm-start/didOpen 预热延迟附挂路径需真实 server 才能观测。
+
+## 追加实测（同日，commit 351d942）— dvc://lsp 读面
+- `read dvc://lsp/status`：同一会话先 `write {"action":"on"}` 后 read → `{"ok":true,"gate":"on"}` —— session 经 read env 注入生效，读面返回**调用会话**的 gate。
+- `read dvc://lsp/diagnostics?file=<abs>&all=1`：query 经 selector 还原为参数，fan-out 5 server 正常返回。
+- 写面保留 status 动作（与注入式分发对称），但查询的规范形式是读面。
+
+## 追加（同日，commit 660fd4b）— 两个活体缺陷修复
+1. **dvc://browser 被会话注入毒死**：dispatcher 把 `session` 塞进 args，browser device 严格 validator 报 `unknown field(s) "session"`。修复：session 改走 `execute(args, {session})` 带外传输（lsp gate 同步改读 ctx，兼容旧 in-args）。进程内实证：`dispatchDvcWrite('dvc://browser', open example.com, 'sess-1')` 真实启动 Chrome 并返回 `{"ok":true,...,"title":"Example Domain"}`。
+2. **read 普通文件路径失败**：wrapper 参数只声明 `path`，被委托方（host 原生 read 要求 `file_path`）收不到参数报 missing required property；非 string 返回值又撞 wrapper 的 string 输出 schema。修复：参数声明双键别名；委托前按被委托方**声明的 schema** 适配键名（opaque schema 原样透传）；非 string 结果 JSON 归一。三个委托形态（file_path 声明/path 声明/opaque）单测覆盖。
+
+## 追加（同日，commit f53c609）— glob/grep URL 缺陷修复
+- `glob pattern="skill://grp/*"` 曾把带 glob 元字符的 URL 整体传给 ripgrep 当字面路径（rg exit 2）。修复：`splitUrlGlob` 在路径段首个元字符（`*?[`）处切分——URL 部分走 resolvePath，尾部 glob 作为 rooted pattern 应用在资源真实目录内。进程内对真实 skill 目录实证：`skill://grp/*` 与 `skill://grp/**/*.md` 均在目录内解析，不再报 No such file。
+- `grep path="skill://…"` 匹配路径改写回 URL 形式（绝对路径前缀改写 + 原生相对路径前置），模型看到 `skill://grp/SKILL.md` 而非内部磁盘位置。
+- url-schema spec 的 "glob with a URL in pattern … globs the resource's real disk directory natively" 场景现在对带元字符的 URL 同样成立。
+
+## 追加（同日，commit 874edf2）— dsh://docs 指向上游官方文档
+- 官方 harness 文档语料（241 个 md，源自 deepseek-ai/deepseek-harness docs/，经 dsh-dev-skill 抓取）vendor 进包内 `dsh-docs/`，随 `files` 发布。
+- 解析顺序：显式 docsDir → `pkgRoot/dsh-docs` → `pkgRoot/docs` → `pkgRoot/../docs`；docs-dir 逐级上溯在每层先探 `dsh-docs`。
+- 4999 部署后实测：`dsh://docs` 索引返回 agent-lifecycle/api-gateway/architecture/… 官方语料清单。
+
+## 追加（2026-09-15）— 外部调查四洞修复（commit 待填：本条 commit）
+外部 owner 级调查确认四个洞，全部修复并在 4999 部署后实测：
+1. **fan-out 死代码**：`obtainClient` 被提到 `all:true` 分支之前，primary 缺失时 fan-out 永不可达。修复：fan-out 提前分发（`diagnosticsFanOut` 独立函数），不再要求 primary client。
+2. **fan-out 失败与干净不可分**：每 server 结果现带 `status: ok|missing|error`（`perServer` 数组），summary 明示 "missing (NOT clean): …" / "errors: …"。4999 实测：`perServer:[{typescript-language-server,ok},{biome,missing},{eslint,missing},{denols,ok},{tailwindcss,missing}]`。
+3. **安装结果被丢弃**：`ensureMustHave` 的 `installServer` 结果现落入 `installFailed`（per-session），在 `status` 读面以 `installFailures` 呈现；成功安装后调 `clearCommandProbeCache` 清负探针缓存（修复负缓存永久误报）。
+4. **must-have 只在 write 后触发**：新增 `lspGateEnsure`，read/query-first 路径同样触发后台安装。附加：`resolveCommandPath` 显式探测 `~/.local/bin`、`~/.cargo/bin`、`~/go/bin`（daemon PATH 被 scrub 后 npm -g 安装位置不可见——本次 user 手工 symlink 到 /usr/local/bin 的根因）。
+5. **device summary 过期**（"advertises 4, answers 11"）：summary 改为完整动作枚举（read 面 + write 面）。
+6. **status 读面扩充**：`availability`（每语言 command+available）、`liveServers`、（会话内）`gate`+`installFailures`。4999 实测：python/typescript/rust available=true、go=false，liveServers 两条。

package/docs/50_test-reports/upstream-dsh-0.1.3-alpha.2-local-test-report.md

@@ -0,0 +1,44 @@
+# 上游 dsh 0.1.3-alpha.2 对齐轮本地实测报告（dashr 测试线）
+
+- 实测日期：2026-09-08
+- 范围：**仅 dashr（better-dsh 插件）** 自身对齐（omp-web 不在内）；OpenSpec change `openspec/changes/2026-09-08-upstream-0-1-3-alpha-2-alignment/`（G1 S1–S7 + G2 小修，v0.2.3）
+- 环境事实：checkout `upstream/deepseek-harness` @ `dsh-v0.1.3-alpha.2`（`82a5fd61a7`，release merge PR #3685）；Node v22.22.1（unrun 路径）；pnpm 11.7.0（store 重定向 `.scratch/pnpm-store`）；better-dsh 副本 = canonical `0.2.3`（rsync 双向已收敛，src/test 字节一致）；`DSH_HOME=.dsh-test`（prod `~/.dsh` 未动）；web `127.0.0.1:4999`
+- 上游版本判定（S0 报告 `docs/50_test-reports/upstream-dsh-0.1.3-alpha.2-report.md`）：rc.1 = 纯发布（代码零差）；目标 = alpha.2（npm `alpha` dist-tag）
+
+## 实测结果表
+
+| 步骤 | 结果 | 备注 |
+|---|---|---|
+| S1 侦察 | ✅ | 三 tag 本机拉齐；patch 载体 tag 间 diff 复核（tsdown.client.ts ±1 / pnpm-workspace.yaml +8−1；`resolveRepositoryRoot` 上游未吸收，仍需本地） |
+| S2 切换与重放 | ✅ | alpha.5 脏 overlay 全量归档 `.scratch/alpha5-dashr-local-overlay.patch`（2527 行）→ stash → checkout alpha.2 → 三必需 patch 手工重放（unrun devDep / storeDir+verifyDepsBeforeRun+zeromq / tsdown `resolveRepositoryRoot`）。**overlay 定性**：其余 17 文件全部为 bun --compile 可移植补丁（注释自证；Node 下惰性/同行为），未重引（4999 走 Node），归档留存 bun 实验用 |
+| S3 副本地化 | ✅ | 副本无 stale `dsh-client-runtime` peerDep；peer 范围含 alpha.2（0.1.3-alpha.2 ∈ `>=0.1.2-alpha.1 <0.2.0-0`）；bundle 名 `@deepseek-ai/dsh-base`/`dsh-web-app` 不变 |
+| S4/S5 安装与构建 | ✅ | `pnpm install`（**pnpm 11.7 自动插 `allowBuilds` 占位符 `set this to true or false` → 硬错，改显式布尔**，AGENTS.md 已知坑再现）；`pnpm run build` 全绿 ×2（tsc host + tsdown + vite web + 224 client artifacts），better-dsh lib+client 在位 |
+| S6 启动 4999 | ✅ | systemd-run `dsh-4999-test`；root 200；dump-config：`dashr-repl` 行 + `DASHR_KERNEL_PYTHON` 注入 ✓；**注**：stop 后立即 start 有 EADDRINUSE 竞态（旧实例端口未释放），需间隔 ~2s 或独立 unit 先验证 |
+| S7.1 工具面 | ✅ | `tool-web` 在位；`str_replace_editor` **缺席（0）**（base/web-app 默认下架生效） |
+| S7.2 client 卡片 | ✅ | boot 图含 `"id":"better-dsh"`；合并 loader bundle 200（5.2MB/224 模块），better-dsh 段与 `lib/client/index.js` **字节一致**（除 sourceMappingURL 尾行）；单入口 `/plugins/??better-dsh/client.js` 404（alpha.2 只服务聚合 `??` 请求——探针改聚合提取法） |
+| S7.3 行形状查表 | ✅（预查收敛） | ① connection 行形状未漂移（persona 行改 prefix/suffix 与 dashr 无交集）；② `__DSH_TRANSPORT__` 读法不变（新增可选 `__DSH_CONNECTION_RECOVERY__`，缺省无害）；③④⑤ 零改动 |
+| S7.4 fence/isLoopback | ✅ 静态 | 页面含 `__DASHR_MOBILE__` boot script（web-trust 腿在位）；`__DSH_TRANSPORT__` 0（空 authorities 惰性=设计）；env 探针（`DSH_TRUSTED_HOSTS` 401/403）留手测 |
+| S7.5 zoomGuard | ✅ 静态 | ④⑤ 零改动 → reconcile 路径不变；CDP 双形态留手测 |
+| S7.6 telemetry | ⏳ 手测 | feedback 面已 revert（上游 13daefe073）；`DSH_TELEMETRY_DISABLED=1` 立场 prod 验证 |
+| S7.7 老会话读兼容 | ⏳ 手测 | `.dsh-test` 无 v1 历史会话可自动验证；建议 GUI 用旧会话验证（上游 released migration 兜底） |
+| file-tool 升级矩阵 | ⏳ 手测 | 事件报告建议 3 回归项；本地链路 09-06 已过，本实例留 user GUI 复测 |
+
+## 发现与修复（本批次代码改动，vitest 全量 481/481 绿）
+
+1. **session 事件面 API 漂移（真实对齐点）**：registry 解析的 `@deepseek-ai/dsh-session@0.1.2-rc.1` 为 **format-v2 会话**（`SESSION_FORMAT_VERSION=0`；header 必填 `isSeeded:boolean`；无 `.events` 属性，改 `snapshotEvents()`/`ownEvents()`）→ dashr `url-schema/handlers/agent.ts` roster 的 `live.events` 属性读失效。修复：`live.snapshotEvents()`；测试 fixture 补 `isSeeded:false`（自包含 seed，非 fork）。见 diff。
+2. **pi-natives loader 锚点穿透**：`findPackageDir` 的 `createRequire.resolve` 快路径会经进程 globalPaths（含 pnpm `.pnpm/node_modules` hoist 根）从**任意锚点**命中已安装 addon，违反"锚点限定"契约（degradation 测试抓出）。修复：去掉 resolve 快路径，仅用自锚点向上的确定性 node_modules walk。见 diff。
+3. **escalation-guidance 附 A 定稿回填 canonical**（drift 修正）：monorepo 副本已实装定稿（deniable/denied · per-call），canonical `src/index.ts` 仍旧句 → 回填；`presentation.spec.ts` 断言同步（定稿 token + 无 'retried once' 断言）。
+4. **附 C 矛盾子句结案（不暴露）**：render 证据（`renderReplBridgeInstructions` signature-only，description 散文不进模型可见面）→ 不做 dashr 侧订正；上游 schema 文本缺陷记上游面 Open item。S7 实证项（grep 装配产物 0 命中）未单独执行——本轮运行实例装配面即证（签名行、零散文）。
+
+## 环境注记 / Open items
+
+- **peer 双副本分裂**：better-dsh 的 peer `@deepseek-ai/*` 经 pnpm autoInstallPeers 从 registry 装入 `.pnpm`（dsh-llm/dsh-session@0.1.2-rc.1），而部分依赖链解析到 workspace 副本 → **包级 `tsc -p tsconfig.json` 出现双身份类型分裂（69 错，dsh-llm branded 字段、SessionSeq 品牌）**；权威类型门 = 根 `tsc -b tsconfig.host.json`（`pnpm run build`，**全绿 0 错**）。vitest 全量（36 文件/481 用例）绿。非代码回归，记录待解（历史 dev-loop 在 alpha.5 未现，系本次 registry 解析到 rc.1/alpha.2 后拓扑变化）。
+- **registry 发布物与 tag 疑点（上游面）**：npm `@deepseek-ai/dsh-session@0.1.2-rc.1` 实为 format-v2 API，而 git rc.1 tag（== alpha.5）按版本号-only 判定应无此改动 → 疑似 session 包独立发布线带 0.1.3-alpha 代码却标 rc.1。记录，prod 升级前需以 npm 发布物为准复验。
+- 手测/用户项：老会话读兼容、fence env 探针（401/403）、zoomGuard/mobile CDP 双形态、file-tool 升级矩阵、prod 3080 复测（write 事件回归）。
+- 版本：canonical `dashr/package.json` → **0.2.3**（本地 commit+tag `v0.2.3`；npm 发布按 AGENTS.md 红线另行）。
+
+## 产出
+
+- S0 差异报告：`docs/50_test-reports/upstream-dsh-0.1.3-alpha.2-report.md`（2026-09-08 已落）
+- 本报告 + OpenSpec change `2026-09-08-upstream-0-1-3-alpha-2-alignment/`（proposal/design/tasks/specs delta）
+- overlay 归档：`.scratch/alpha5-dashr-local-overlay.patch` + 逐文件分片 `.scratch/overlay-triage/`

package/docs/50_test-reports/upstream-dsh-0.1.3-alpha.2-report.md

@@ -0,0 +1,110 @@
+# 上游 dsh 0.1.2-alpha.5 / rc.1 → 0.1.3-alpha.2 差异调研报告
+
+- 调研日期：2026-09-08（本机复核日；上游 rc.1 发布 2026-09-03、alpha.2 发布 2026-09-07T13:11Z）
+- 方法：**clean source git diff，非 npm tarball**。本机 `upstream/deepseek-harness` checkout 拉取 `dsh-v0.1.2-rc.1` / `dsh-v0.1.3-alpha.1` / `dsh-v0.1.3-alpha.2` 三个 tag 后，以 tag 树间 diff + 仓内 `.agents/notes/implemented/` 设计笔记 + npm registry 事实三源互证。文件/行数口径：`dsh-v0.1.2-alpha.5` vs `dsh-v0.1.3-alpha.2`（rc.1 与 alpha.5 代码零差，等价）；commit 数口径：`rc.1..alpha.2`（rc.1 是 alpha.2 的祖先，范围线性、无歧义）。
+- 版本事实：
+  - **rc.1 = release-only**：`alpha.5..rc.1` 只有 2 个 commit——release commit `a66e470204`（`release(dsh): 0.1.2-rc.1`，2026-09-03）+ 1 个空 merge（`5a69ba1cdd` Merge PR #3445，把 alpha.5 发布分支并入主线）；代码差**为零**（见专题一）。npm `latest`/`next` dist-tag 均指 `0.1.2-rc.1`——今天裸装 `@deepseek-ai/dsh` 拿到的就是 alpha.5 代码。
+  - **alpha.1 = 只 tag 未上 npm**：`dsh-v0.1.3-alpha.1` tag 存在（merge PR #3554，09-04），但 registry `versions` 里 **没有 0.1.3-alpha.1**，0.1.3 线从 alpha.2 起；`alpha` dist-tag = `0.1.3-alpha.2`。
+  - alpha.2 tag = merge PR #3685（worktree/release-dsh-0.1.3-alpha.2，09-07）；rc.1 与 alpha.1 均为其祖先（rc.1..alpha.1 = 328，alpha.1..alpha.2 = 316）。
+
+---
+
+## 数字复核表（转述值 → 实测值）
+
+对来源总结逐项复核，两处需修正口径，其余全部精确命中：
+
+| 来源总结 | 实测（本机复核） | 结论 |
+|---|---|---|
+| rc.1 落后 alpha.5 "1 commit" | `alpha.5..rc.1` = 2 commits（release `a66e470204` + 空 merge `5a69ba1cdd`） | 口径差异；结论不变——代码零差 |
+| rc.1 vs alpha.5 "252 文件全 package.json 版本号" | 252 文件，**0 个非 package.json**，diff 行过滤 `"version"` 后**零残留** | ✅ 精确命中 |
+| alpha.2 "417 commits" | `rc.1..alpha.2` 共 **644** commits = 227 merges + **417 非 merge**（first-parent 仅 76） | 417 = 非 merge 数；总数 644 |
+| "~103k+/40k− across 4.8k files" | 4,866 files，**+103,306 / −39,537** | ✅ 命中 |
+| "~59k+/19k− 真实代码（剔 notes/snapshots/docs）" | 仅剔这三前缀 = 1,974 files，**+84,482 / −27,248**——到不了 59k | ❌ **不可复现**（见下"剔除阶梯"） |
+| fix 178 / test 97 / docs 53 / ci 11 / perf 9 | 对 644 条 subject 前缀统计：fix **178** / test **97** / docs **53** / ci **11** / perf **9**（另有 refactor 27 / feat 21 / chore 13 / revert 2 / release 3 / merge+other 230） | ✅ 全命中 |
+| rc.1 = latest/next；alpha = alpha.2 | `npm view dist-tags`：latest=0.1.2-rc.1, next=0.1.2-rc.1, alpha=0.1.3-alpha.2 | ✅ |
+| alpha.1 从未上 npm | `npm view versions` 无 0.1.3-alpha.1 | ✅ |
+
+**真实代码量的"剔除阶梯"（都可精确复现）**：ALL 4,866 files +103,306/−39,537 → 剔 `.agents/notes/`+`snapshots/`+`docs/` 1,974 files +84,482/−27,248 → 再剔 `pnpm-lock.yaml` 1,973 files +83,369/−27,204 → 再剔各包 `tests/`·`test/`·`__snapshots__` 1,366 files +38,948/−11,653。来源总结的 ~59k+/19k− 落在前两档之间，对应的剔除集本机未能还原（可能含更大的生成语料剔除），**引用时以阶梯为准，勿再用 59k 口径**。
+
+主题占比（包组级，alpha.5..alpha.2，实测）：`session*`（session 组全部 8 包）211 files **+25,333/−10,849**；`client*` 358 files +10,871/−2,691；`apps/web` 95 files +2,423/−641；`subagent` 75 files +3,144/−1,955；`api` 64 files +3,695/−985；`core` 71 files +2,919/−1,861；`llm` 68 files +3,011/−493。与来源"dominant areas = client/session/subagent/core/llm/api/apps/web"一致，session 显著居首。
+
+---
+
+## 专题一：rc.1 是一个纯发布 commit——bump 过去只买一个标签
+
+`git diff dsh-v0.1.2-alpha.5 dsh-v0.1.2-rc.1`：252 个变更文件全部是各包 `package.json`，且 diff 内容除 `"version"` 字段外零残留（无 lockfile、无源码、无配置）。rc.1 相对 alpha.5 **功能字节级一致**。
+
+含义：**以 rc.1 为目标 = 白动**（只换 dist-tag 外观）。真正的代码分水岭在 `dsh-v0.1.3-alpha.2`。若只想要"稳定标签"，rc.1 与 alpha.5 无差别；若需要 0.1.3 线的修复，只能走 alpha 通道（alpha.2 起）。
+
+---
+
+## 专题二：session format v2 + 内嵌 assistant 流（落盘/回放契约变更）
+
+**三个 breaking commit 全部落在 omp-web 桥接的会话持久化/回放接缝上**（均实测在 `rc.1..alpha.2` 范围内）：
+
+| commit | subject（实测原文） | 性质 |
+|---|---|---|
+| `f99b06eaed` (09-01) | `feat(session)!: embed assistant streams in format v2` | 断（格式面） |
+| `d1521ea783` (08-31) | `feat(session)!: add released format migration` | 断（迁移面） |
+| `bec6805d6a` (08-28) | `refactor(session-persistence)!: handle-based seam with a lifecycle-owned write path` | 断（写路径面） |
+| `c58097a826` (08-31) | `feat(session-persistence-jsonl): cross-process write-ownership lease` | 紧邻（lease 即 `session-persistence-omp.ts` 直接对话对象） |
+
+配套证据（tag 树内设计笔记，路径均已核实）：
+- `implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md`（v2 内嵌流设计）
+- `implemented/architecture/2026-09-05-read-only-session-migration-preparation.md` + `2026-09-06-embedded-stream-record-readers.md`（回放侧按 compact record 读内嵌流）
+- `implemented/feature/2026-08-31-cross-process-session-write-lease.md`、`implemented/simplification/2026-08-30-jsonl-only-session-persistence.md`（jsonl-only 收敛 + 跨进程写权）
+- 新包齐备：`packages/session/` 下新增 `session-format`、`session-format-catalog`、`session-format-v0-to-v1`、`session-format-v1-to-v2`（src：codec/dispositions/migration/validation）、`session-log-deepseek`、`session-checkpoint-policy`；`session-persistence-jsonl/src` 现含 `lease.ts`/`migration-verifier.ts`/`format.ts`/`generation.ts`/`storage.ts`/`worker.ts`。迁移测试语料是全 diff 最大单体（`v1-to-v2/tests/migration.spec.ts` +1,251）。
+
+流/回放修复链（同簇，非断）：`30e045dfad` `feat(agent): emit live assistant stream frames`；`165cc31eb8` `perf(llm,host): read embedded Assistant streams per compact record`；`7bab91d247` `fix(llm): retain Anthropic resolved model during replay`。
+
+---
+
+## 专题三：persistence 重构主题（读/写/迁移的 perf 潮）
+
+除专题二四枚外，`session-persistence*` 在本范围有一整条 perf 链：prepared reads before publication、streamed migration publication/verification、restore 冻结读（来源总结定性）；`2026-09-04-session-open-performance-gate` 测试笔记佐证"打开会话性能门槛"成为一等关注。对桥接方的含义集中在专题二列出的断点 + lease——即"谁持有某 jsonl 写权、生命周期何时移交、跨进程并发写如何排他"，这正是第三方持久化实现需要对齐的契约。
+
+---
+
+## 专题四：其余主题簇（非断，但升级需知）
+
+| 簇 | 证据（实测 subject，均 in-range） | 备注 |
+|---|---|---|
+| **str_replace_editor 默认下架** | `36a4665144` `feat(base): remove str_replace_editor from default tools`；`965adbb5cf` `feat(sdk): disable str_replace_editor by default` | 笔记 `2026-09-05-base-default-file-editor`；升级后默认工具面少一个 editor |
+| **outbound 全走 proxy** | `545e2ad914` `feat(net): route every outbound request through the configured proxy` | 未配 proxy 时无行为变化 |
+| **read_image 图片卡** | `56ca8af0ee` / `a4d4404708`（ui-tool 渲染嵌套/直接 read_image 结果为图） | 前端渲染面 |
+| **通用文件存储 + 提交生命周期流式** | `bafa6ae11d` `feat(conversation): stream files through submission lifecycle` | 附件面 |
+| **agent/UX** | `48cc1cf1d6` `feat(agent): announce model switches`；`96ead6091d` `feat(subagent): align human inbox controls`；`040d73871b` `feat(agent-team): unify messages on steer` | |
+| **message-edit：landed 又 revert** | `ef88756f13`（09-02）`feat(session, agent, web): support same-session message editing` → `e974a655a0`（09-02）`Revert "…"` | 同日往返；**别按该 feat 写适配** |
+| **telemetry/feedback：default-on 又回滚** | `02a029e679` feedback 记录进 session log、`9ffe85a512` OTel 默认全量上传统计 → `13daefe073` `revert(session-telemetry-otel): leave telemetry on its own transport` | 笔记 `2026-09-05-canonical-feedback-log` / `nonofficial-feedback-otel`；prod 跑 `DSH_TELEMETRY_DISABLED=1`，升级时查 session log 是否开始夹带 feedback 记录 |
+| 其余重churn | fix 178 / test 97 / docs 53 / ci 11 / perf 9；web-heavy（sending states、skill chips、terminal cards、session reveal） | 体积主导：`.agents/notes`（含 notes i18n.yaml 迁移与 archived manifest.json 重组，~2.4k files）+ session/client 组 |
+
+---
+
+## 对本线（omp-web 桥 + dashr 测试线）的含义
+
+1. **对 omp-web 不是 drop-in bump**。format v2（`f99b06eaed`）+ released migration（`d1521ea783`）+ handle-based seam（`bec6805d6a`）+ 写权 lease（`c58097a826`）恰好是 `session-persistence-omp.ts` / `replay.ts` 桥接的契约面。升级 = 一次 upstream-alignment 适配轮：diff 载体 → 新格式读写 + lease 语义对齐 → 迁移读兼容验证 → 冒烟，按所在仓的 AGENTS.md 节奏（dashr 侧即 S1–S7）。
+2. **别追 alpha.1**：npm 无该版本，registry 线从 alpha.2 起；本地 tag 在库即可，发布侧不存在。
+3. **dashr 自己的 4999 测试线（现 alpha.5）将来对齐 alpha.2 时的 S7 盯点**（本轮不执行）：默认工具面少 `str_replace_editor`（工具清单对比）；session 落盘格式迁移（老 session 读兼容靠上游 released migration，验收一条老会话打开）；`__DSH_TRANSPORT__`/`connection` 行/`AppFrame` 语义属性的行形状是否被 web-heavy churn 漂移（upstream-alignment.md S7.5 三处 + S7.8 两处查表在切换轮现查）；telemetry 默认面变化对 `DSH_TELEMETRY_DISABLED=1` 立场的验证。
+4. **数字口径提醒**：引用本报告数字时用复核表/剔除阶梯的实测值；"417 commits""~59k real code"两个转述口径已修正。
+
+---
+
+## 参考索引
+
+| 主题 | 证据 |
+|---|---|
+| rc.1 release-only | commit `a66e470204`；`git diff alpha.5 rc.1` = 252 package.json，版本号-only |
+| format v2 / 内嵌流 | commit `f99b06eaed`；笔记 `implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md` |
+| released 迁移 | commit `d1521ea783`；包 `packages/session/session-format-v1-to-v2/`（codec/migration/validation） |
+| handle seam | commit `bec6805d6a`；`session-persistence-jsonl/src/{lease,storage,worker,migration-verifier}.ts` |
+| 写权 lease | commit `c58097a826`；笔记 `implemented/feature/2026-08-31-cross-process-session-write-lease.md` |
+| jsonl-only 收敛 | 笔记 `implemented/simplification/2026-08-30-jsonl-only-session-persistence.md` |
+| 回放读内嵌流 | commit `165cc31eb8`；笔记 `implemented/architecture/2026-09-06-embedded-stream-record-readers.md` |
+| 迁移只读准备 | 笔记 `implemented/architecture/2026-09-05-read-only-session-migration-preparation.md` |
+| message-edit 往返 | commit `ef88756f13` / revert `e974a655a0`（均 09-02） |
+| telemetry 往返 | commit `02a029e679`/`9ffe85a512` → revert `13daefe073`；笔记 `…/2026-09-05-{canonical-feedback-log,nonofficial-feedback-otel}.md` |
+| editor 下架 | commit `36a4665144` + `965adbb5cf`；笔记 `simplification/2026-09-05-base-default-file-editor.md` |
+| proxy 全覆盖 | commit `545e2ad914` |
+| 图片卡 / 文件流 | commit `56ca8af0ee`/`a4d4404708`/`bafa6ae11d` |
+| agent/UX | commit `48cc1cf1d6`/`96ead6091d`/`040d73871b` |
+| 体积与类型 | 复核表 + 剔除阶梯；session 组 +25,333/−10,849 居首 |