super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/50_test-reports/2026-10-03-ast-engine-deomp-4999/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,325 @@
+# better-dsh AST 引擎去 OMP（in-package WASM）— 4999 第一人称实测报告
+
+日期：2026-10-03/04 ｜ 规格：`docs/specs/ast-engine-deomp/spec.md` ｜ 目标版本：`0.2.5-c`（本地过程版本，未发布）｜ 计划：`.superpowers/sdd/2026-10-03-ast-engine-deomp/`（Task 11 验收）
+
+## 0. 一句话
+
+AST 设备（`dvc://ast_grep` / `dvc://ast_edit`）已整体运行在**包内 WASM 引擎**上：真实 agent session（HTTP RPC 驱动、4999 rig、`.vendor` 预先删除）里完成结构化搜索（34 命中/8 文件/11 检索，含完整元变量捕获）、dryRun 拦截（`applied:false` 文件不动）与真写盘（`git diff` 可见后回滚）；tarball 零 OMP 代码、零 `.node`、零运行时依赖；与 prod 树残留的 **native addon 直接对拍，处方 pattern 两引擎逐字段一致**。
+
+## 1. 验收口径（AGENTS §〇 第 2 条：与改动点同类）
+
+改动点是"实际运行时上下文里 ast 设备可不可用 + OMP 供给链是否根除"，验收即：真实 agent session 在 4999 rig 的真实运行时里走 `write dvc://ast_*` 全链路（host 侧被测路径全覆盖），并以 `.vendor` 不重建 + tarball 零 OMP 证明供给链死亡。构建卫生（tsc/单测/产物 grep）只是前置，不是验收本体。
+
+## 2. 全量卫生（Step 1）
+
+| 项 | 结果 |
+|---|---|
+| `npm run build`（tsdown + build-client） | ✅ 通过；`ast-assets: 16 files, 14.4 MB`（构建日志原句） |
+| `npm run typecheck`（tsc + tsc -p tsconfig.client.json） | ✅ 0 错（exit 0） |
+| `npx vitest run` | ✅ **Test Files 63 passed (63)；Tests 681 passed, 1 skipped (682)** |
+
+## 3. tarball 零 OMP（Step 2）
+
+`npm pack` → `better-dsh-0.2.5-c.tgz`（22,250,332 B），解包至 `/tmp/astpkg/package`：
+
+| 检查 | 结果 |
+|---|---|
+| `grep -rc "pi_natives\|@oh-my-pi"` 代码面（`lib/`、`package.json`、`scripts/`） | **0 命中** |
+| 同 grep 全包 | 11 个文件命中，**全部在 `package/docs/`**（specs/plans/报告/upstream 文档里对本次去 OMP 迁移的自指文字记录——纯 prose，非代码非依赖） |
+| `.node` 原生二进制 / `.vendor` / `natives-loader` | tarball 内 **0 项**（`natives-loader.ts` 已从 src 删除） |
+| `lib/ast-assets` | **16 个文件**（ast-grep.wasm + tree-sitter.wasm + 14 语法），15,091,049 B |
+| `dependencies` / `optionalDependencies` | **空**（安装面只加 1 个包） |
+
+## 4. 离线 rig 第一人称实测（Step 3）
+
+### 4.1 rig 安装与离线前置
+
+- `rm -rf <pkg>/.vendor`（start 前执行；当时本就不存在——上一任务已清）
+- `plugin --profile web remove better-dsh` → `add …/better-dsh-0.2.5-c.tgz`：`Packages: +1 … Done in 2.2s`
+- 安装位与fresh构建**字节一致**（`lib/index.js` cmp 相等；`lib/ast-assets` 目录 diff 为空；版本 0.2.5-c）
+- `bash .test/seed/test123/start.sh` 启动：boot graph 含 `"id":"better-dsh"`，`/plugins/??better-dsh/client.js&rev=af3132a66867` → 200 / 29,700 B
+
+### 4.2 驱动方式（HTTP RPC，真实 session）
+
+web-password 门（本插件自己的 feature，独占 `/`）铸 cookie：`curl -c jar -X POST -d "password=admin" /` → 303。此后按 0.1.7 `/api` HTTP JSON RPC 两段形端点（typert 具名参数，`{args:{request:{…}}}` 包裹）：
+
+- `POST /api/session/create` → `{"sessionId":"session-91ea4282-99b4-4941-89ab-8cc7bc199a4a","agentPreset":"standard"}`
+- `POST /api/session/prompt`（`mode:'queue'`，全文任务指令见会话日志 seq 20 / seq 68）
+
+会话 `session-91ea4282…`：2 个 turn、11 次工具调用（write×6 / bash×4 / memory_add×1），全部走宿主 write 工具的 dvc:// URL 分支。日志：`.test/home/compat/sessions/--home-u1-workspaces-dashr--/session-91ea4282…/session.v4.jsonl.zstd`。
+
+### 4.3 Round 1 —— 任务处方的三次调用（args 原样，返回原样 JSON）
+
+**（a）`write dvc://ast_grep`**，content：`{"patterns":["export function $NAME($$$ARGS)"],"path":"<ws>/better-dsh/src/devices/ast"}`（seq 21→22）：
+
+```json
+{
+  "matches": [],
+  "totalMatches": 0,
+  "filesWithMatches": 0,
+  "filesSearched": 11,
+  "limitReached": false
+}
+```
+
+**（b）`write dvc://ast_edit`（dryRun 默认）**，content：`{"ops":[{"pat":"export function $NAME($$$ARGS)","out":"export function $NAME($$$ARGS) {}"}],"paths":["<ws>/better-dsh/src/devices/ast/ast-reminder.ts"]}`（seq 28→29）：
+
+```json
+{
+  "changes": [],
+  "fileChanges": [],
+  "totalReplacements": 0,
+  "filesTouched": 0,
+  "filesSearched": 1,
+  "applied": false,
+  "limitReached": false
+}
+```
+
+随后 `git status --porcelain -- …/ast-reminder.ts` → **空输出**（文件未变 ✅）。
+
+**（c）同 ops + `"dryRun":false`**（seq 42→43）：
+
+```json
+{
+  "changes": [],
+  "fileChanges": [],
+  "totalReplacements": 0,
+  "filesTouched": 0,
+  "filesSearched": 1,
+  "applied": true,
+  "limitReached": false
+}
+```
+
+`applied:true`（非 dry-run 确已进入写盘路径）但 0 命中 → 文件内容不变，`git diff --stat` 空输出；agent 仍按剧本执行 `git checkout --` 回滚（幂等 no-op），树保持干净。
+
+**处方 pattern 0 命中的定性**：这是 ast-grep **严格结构匹配**的正确行为，不是引擎退化——无函数体的 pattern 无法命中带函数体的声明节点（pattern 子节点必须逐一对齐；本仓函数全部带 body 与返回类型标注）。**Native 对拍证实**（§5）：同一 pattern 在真实 OMP native addon 上同样 0/0/11，逐字段一致。为完成"真命中 + 真写盘"的验收意图，Round 2 用结构对齐的 pattern 补测（§4.4），两轮合计覆盖：结构化命中、元变量捕获、分页、dryRun 拦截、真写盘、diff、回滚。
+
+### 4.4 Round 2 —— 结构对齐补测（同一 session 第二 turn）
+
+**（a'）`dvc://ast_grep`**：`{"patterns":["function $NAME($$$ARGS): $RET { $$$BODY }"],"path":"<ws>/better-dsh/src/devices/ast","includeMeta":true,"limit":3}`（seq 69→70，节选）：
+
+```json
+{
+  "matches": [
+    {
+      "path": "better-dsh/src/devices/ast/ast-device.ts",
+      "text": "function ctxCwd(ctx: unknown): string {\n  if (ctx !== null && typeof ctx === 'object' && typeof (ctx as { cwd?: unknown }).cwd === 'string') {\n    return (ctx as { cwd: string }).cwd\n  }\n  return process.cwd()\n}",
+      "byteStart": 2610,
+      "byteEnd": 2821,
+      "startLine": 59,
+      "startColumn": 1,
+      "endLine": 64,
+      "endColumn": 2,
+      "metaVariables": {
+        "NAME": "ctxCwd",
+        "ARGS": "[ctx: unknown]",
+        "RET": "string",
+        "BODY": "[if (ctx !== null && typeof ctx === 'object' && …, return process.cwd()]"
+      }
+    }
+  ],
+  "totalMatches": 34,
+  "filesWithMatches": 8,
+  "filesSearched": 11,
+  "limitReached": true
+}
+```
+
+34/8/11 + `limitReached:true`（`limit:3` 分页后的合法语义）；与离线预计算（同引擎直接驱动：34 命中/8 文件）**完全一致**。元变量四类（单变量 `$NAME`/`$RET`、多捕获 `$$$ARGS`/`$$$BODY` 的 Rust Debug 数组串形态）齐活。
+
+**（b'）`dvc://ast_edit` dryRun 默认**：`{"ops":[{"pat":"export function disposeAstReminders(sessionId: string): void { $$$BODY }","out":"export function disposeAstReminders(sessionId: string): void { /*ast-live-proof*/ $$$BODY }"}],"paths":["…/ast-reminder.ts"]}`（seq 77→78）：
+
+```json
+{
+  "changes": [
+    {
+      "path": "better-dsh/src/devices/ast/ast-reminder.ts",
+      "before": "export function disposeAstReminders(sessionId: string): void {\n  counters.delete(sessionId)\n}",
+      "after": "export function disposeAstReminders(sessionId: string): void { /*ast-live-proof*/ counters.delete(sessionId) }",
+      "byteStart": 2063,
+      "byteEnd": 2156,
+      "deletedLength": 93,
+      "startLine": 42,
+      "startColumn": 1,
+      "endLine": 44,
+      "endColumn": 2
+    }
+  ],
+  "fileChanges": [{ "path": "better-dsh/src/devices/ast/ast-reminder.ts", "count": 1 }],
+  "totalReplacements": 1,
+  "filesTouched": 1,
+  "filesSearched": 1,
+  "applied": false,
+  "limitReached": false
+}
+```
+
+`git status --porcelain` → **空**（预览未落盘 ✅）。
+
+**（c'）同 ops + `"dryRun":false`**（seq 91→92）：同上 changes，`"applied": true`。随后 `git diff` 真实可见（seq 98→99）：
+
+```diff
+-export function disposeAstReminders(sessionId: string): void {
+-  counters.delete(sessionId)
+-}
++export function disposeAstReminders(sessionId: string): void { /*ast-live-proof*/ counters.delete(sessionId) }
+```
+
+agent 立即 `git checkout --` 回滚，复检 `git status --porcelain` → 空 ✅。**真写盘-可见-回滚闭环完成。**
+
+### 4.5 过程事件：4999 端口被并发抢占一次
+
+Round 1 结束后（03:56:36）本机另一 agent（superd 工作区）重启了它自己的 `superd-4999-test.service`，杀掉了我们的 `dsh-4999-test123`（LAN relay socat 同刻 signal 15）。复跑 `start.sh`（其无主化接管逻辑再次停掉对方、夺回端口），**同一 sessionId 在同一 rig home 上续跑 Round 2**——两轮证据完整连续。此为共享测试机上的已知端口竞争形态（AGENTS §二），非被测面问题。
+
+### 4.6 离线/.vendor 证据
+
+- **start 前**：`rm -rf <pkg>/.vendor`（当时本已不存在）
+- **两轮全部 dvc 调用之后**：`.test/home/compat/profiles/web/node_modules/better-dsh/.vendor` **仍未被创建**（最终复检 ABSENT）——WASM 资产随包分发，无任何按需自装路径被触发
+- rig 日志 `.scratch/dsh-4999-test123.log` 全文件（188 行、45 次历史 boot）：`oh-my-pi|pi_natives|registry.npm|npmjs` **0 命中**；本次 boot 后 0 错误
+- profile 树根的空壳目录 `node_modules/@oh-my-pi/`（0 文件，时间戳 10-03 01:15，早于本任务）为上一纪元残留 husk，非本插件产物；`.pnpm` store 内无相关条目
+
+## 5. Native A/B 直接对拍（意外收获：native addon 仍在 prod 树）
+
+`~/.dsh/profiles/web/node_modules/@oh-my-pi/pi-natives-linux-x64/`（prod 由 `super-dsh` 引入的 352 MB 二进制，非我们的）仍可 dlopen——用它对拍本次全部 live 输入（脚本 `/tmp/ab-prescribed.mjs`、`/tmp/ab-dir.mjs`，spike 同款手法）：
+
+| 输入 | OMP native | WASM（live rig） | 一致 |
+|---|---|---|---|
+| 处方 pattern `export function $NAME($$$ARGS)`（目录） | `0 / 0 / 11` | `0 / 0 / 11` | ✅ |
+| 对齐 pattern `function $NAME($$$ARGS): $RET { $$$BODY }`（目录） | `34 / 8 / 11` | `34 / 8 / 11` | ✅ |
+| edit dryRun 默认（disposeAstReminders 单点） | `totalReplacements:1, applied:false` | `totalReplacements:1, applied:false` | ✅ |
+| edit `dryRun:false` | `totalReplacements:1, applied:true` | `totalReplacements:1, applied:true` | ✅ |
+
+顺带记录 native 的一个路径怪癖（对迁移结论无影响）：`astEdit` 收绝对文件路径时会从 cwd 起走整树（`filesSearched:1976`）并按重定基底径写盘（对拍探针因此摸脏了工作树一次，当场 `git checkout --` 复原）；我们的 controller 对绝对文件路径正确给 `filesSearched:1` 并写回原路径。
+
+## 6. Task 8 评审两项遗留的处置（按移交指令：观察记录，不修）
+
+1. **`limitReached` 纯 offset 边**：公式 `totalMatches > paged.length`（`ast-device.ts:274`）意味着 `offset>0` 且无 `limit` 的查询在有命中文件上恒报 `limitReached:true`。本任务**记录为接受边**（brief 明示公式如此；native 已删，该边无从 A/B）。live 旁证：Round 2 的 `limitReached:true` 出现在 `limit:3` 分页场景（34>3，合法语义），与本边无关亦不矛盾。
+2. **`engine/edit.ts` 只吞 multi-root 错误**：**已直接核验**——`edit.ts:54-56` 的 catch 仅当 `error.message.includes('Multiple AST nodes are detected')`（`MULTI_NODE`，`edit.ts:13`）时 `continue`，其余一律 rethrow；`match.ts:67-69` 同款归零逻辑。无吞错面扩大。
+
+## 7. 第一人称机制发现（本轮新增）
+
+ast-grep 匹配是**子节点严格对齐**的：pattern 缺 body 子节点 → 永不命中带 body 的函数声明；缺返回类型标注 → 永不命中带标注的签名。离线矩阵（同引擎，`$$$`-pattern × 三种源）：
+
+| pattern | 无返回标注源 | `: void` 标注源 | 仓库真文件 |
+|---|---|---|---|
+| `export function $NAME($$$ARGS)`（无 body） | 0 | 0 | 0 |
+| `function $NAME($$$ARGS) { $$$BODY }` | 2 | 0 | 0 |
+| `export function $NAME($$$ARGS): void { $$$BODY }` | 0 | 1 | 1 |
+
+与 spec §2.1"C / CSS 的匹配不到是上游 pattern 上下文歧义，不是 WASM 退化"同族——native 对拍 0=0 坐实。**写 pattern 必须带上目标声明的完整子节点形态（含返回类型），文本级 grep 直觉在这里不成立。**
+
+## 8. 规格 §2.1 spike A/B 表（provenance 照录）
+
+| 用例 | OMP native | WASM 栈 | |
+|---|---|---|---|
+| `c` `foo($A)` | 0 | 0 | ✅ |
+| `c` `return foo($A)` | 1 | 1 | ✅ |
+| `cpp` `foo($A)` | 1 | 1 | ✅ |
+| `css` `color: $V` / `color: red` | 0 / 0 | 0 / 0 | ✅ |
+| `html` `<div class=$C>$$$K</div>` | 1 | 1 | ✅ |
+| `python` `return $X` | 1 | 1 | ✅ |
+| `js` `foo($$$A)` / `rust` `vec![$$$A]` / `yaml` `b: $V` / `go` `foo($A)` | 1 | 1 | ✅ |
+
+本轮 §5 的对拍把该表延伸到了本次 live 实际输入（含处方 pattern 的 0=0）。
+
+## 9. 未做 / 边界
+
+- **未发布**：`npm publish` 需 user 单独明确放行（AGENTS §〇 红线），本任务不含。
+- 版本 `0.2.5-c` 为本地过程版本；tarball 仅入 rig（file: 安装），registry 无足迹。
+- native 对拍依赖的 prod 树残留 `@oh-my-pi` 属 `super-dsh` 的依赖，不因本插件去 OMP 而消失（prod 面清理不属本计划）。
+- 第一人称会话的 token 消耗（两 turn 合计约 15k output / 150k+ cache-read）留在 rig home，随下次 home 复用自然沉淀。
+
+## 四、4998 复测（user 指令：4999 被并发 agent 占用）
+
+日期：2026-10-04 ｜ 前提：4999 端口被另一并发 agent 的 rig 占用，user 指令改在 **4998** 重跑验收 live-fire。**上文 §1–§9 的 4999 实测结论（native A/B 对拍 0/0/11 逐字段一致、两轮 live 证据）原样保留，本节为同口径独立复测**，不覆盖、不替代上文。
+
+### 4.8.1 rig 状态与启动
+
+- 前置核验：profile 安装位 `lib/ast-assets` **16 文件**（Task 11 remove→add 的产物原样在场）；`.vendor` start 前 **ABSENT**。
+- `PORT=4998 bash .test/seed/test123/start.sh`：unit `dsh-4998-test123` + `test123-lan-4998-relay` 起动，`127.0.0.1:4998` 与 LAN `192.168.31.130:4998` 双监听；日志 **`.scratch/dsh-4998-test123.log`**（append，本次 boot 前历史 5 行）。
+- 认证：与 §4.2 同一形态——better-dsh `dashr-web-password` 行独占 `/`（launch-token URL 被 password 门先行接管，GET `/?token=…` 直接 200 不铸 cookie），`curl -c jar -X POST -d "password=admin" /` → **303** + 原生 `dsh-auth-<authority-hash>` cookie（HttpOnly）。此后 `/api` 全部携带该 cookie。
+
+### 4.8.2 HTTP RPC 驱动（真实 session，同 §4.2 两段形）
+
+- `POST /api/session/create`（client-request 信封，`payload.args.request.cwd=/home/u1/workspaces/dashr`）→ `{"sessionId":"session-1aa5f442-9058-49fb-bf31-74a2780a90ab","agentPreset":"standard"}`
+- `POST /api/session/prompt`（`mode:'queue'`，rpcId `req-ast-4998-live`）→ `{"accepted":true}`
+- 会话 `session-1aa5f442…`：1 turn、7 次工具调用（bash×3 / write dvc://×3 / memory_add×1），全部 dvc 调用走宿主 write 工具的 URL 分支。日志：`.test/home/compat/sessions/--home-u1-workspaces-dashr--/session-1aa5f442…/session.v4.jsonl.zstd`（seq 28→29 / 35→36 / 49→50）。
+
+### 4.8.3 三次 live 调用（结构对齐 pattern，§4.4 同款）
+
+**（a）`write dvc://ast_grep`** content：`{"patterns":["function $NAME($$$ARGS): $RET { $$$BODY }"],"path":"/home/u1/workspaces/dashr/better-dsh/src/devices/ast","includeMeta":true,"limit":3}`（seq 28→29，返回原样 JSON 节选）：
+
+```json
+{
+  "matches": [
+    {
+      "path": "better-dsh/src/devices/ast/ast-device.ts",
+      "text": "function ctxCwd(ctx: unknown): string { … }",
+      "byteStart": 2610, "byteEnd": 2821,
+      "startLine": 59, "startColumn": 1, "endLine": 64, "endColumn": 2,
+      "metaVariables": { "NAME": "ctxCwd", "ARGS": "[ctx: unknown]", "RET": "string", "BODY": "[if (ctx !== null && …, return process.cwd()]" }
+    },
+    {
+      "path": "better-dsh/src/devices/ast/ast-device.ts",
+      "text": "function rel(file: string, cwd: string): string { … }",
+      "byteStart": 2895, "byteEnd": 3006,
+      "startLine": 67, "startColumn": 1, "endLine": 69, "endColumn": 2,
+      "metaVariables": { "NAME": "rel", "ARGS": "[file: string, ,, cwd: string]", "RET": "string", "BODY": "[return path.relative(cwd, file).split(path.sep).join('/')]" }
+    }
+  ],
+  "totalMatches": 34,
+  "filesWithMatches": 8,
+  "filesSearched": 11,
+  "limitReached": true
+}
+```
+
+**34/8/11 + `limitReached:true`（`limit:3` 分页）**——与 4999 轮 §4.4(a') 及 native 对拍 §5 的 34/8/11 **完全一致**（首条 match 的 byteOffset 2610/2821、元变量四类捕获逐字段相同）。
+
+**（b）`write dvc://ast_edit` dryRun 默认**，content：`{"ops":[{"pat":"export function disposeAstReminders(sessionId: string): void { $$$BODY }","out":"export function disposeAstReminders(sessionId: string): void { /*ast-live-proof*/ $$$BODY }"}],"paths":["…/ast-reminder.ts"]}`（seq 35→36）：
+
+```json
+{
+  "changes": [{ "path": "better-dsh/src/devices/ast/ast-reminder.ts", "before": "export function disposeAstReminders(sessionId: string): void {\n  counters.delete(sessionId)\n}", "after": "export function disposeAstReminders(sessionId: string): void { /*ast-live-proof*/ counters.delete(sessionId) }", "byteStart": 2063, "byteEnd": 2156, "deletedLength": 93, "startLine": 42, "startColumn": 1, "endLine": 44, "endColumn": 2 }],
+  "fileChanges": [{ "path": "better-dsh/src/devices/ast/ast-reminder.ts", "count": 1 }],
+  "totalReplacements": 1,
+  "filesTouched": 1,
+  "filesSearched": 1,
+  "applied": false,
+  "limitReached": false
+}
+```
+
+`applied:false` ✅；调用前后 `git status --short -- better-dsh/src/devices/ast/` 均为**空**（baseline seq 22 / 复检 seq 43，文件未动）。
+
+**（c）同 ops + `"dryRun":false`**（seq 49→50）：同上 changes，`"applied": true, "totalReplacements": 1, "filesTouched": 1`。随后（seq 57）：
+
+```text
+ better-dsh/src/devices/ast/ast-reminder.ts | 4 +---
+ 1 file changed, 1 insertion(+), 3 deletions(-)
+```
+
+`git checkout --` 立即回滚，复检 `git status --short -- better-dsh/src/devices/ast/` → **空** ✅。真写盘-可见-回滚闭环复现。
+
+### 4.8.4 供给链证据（本次 run 复检）
+
+- **`.vendor`**：全部 dvc 调用之后 `.test/home/compat/profiles/web/node_modules/better-dsh/.vendor` 仍 **ABSENT**（`ls` exit 2）；`lib/ast-assets` 仍 16 文件——无任何按需自装路径被触发。
+- **rig 日志**：`grep -icE "omp|oh-my-pi|registry" .scratch/dsh-4998-test123.log` → **0 命中**（全文件，含本次 boot 全部输出）——零 OMP/registry 供给痕迹。
+
+### 4.8.5 复测结论
+
+4998 独立复测与 4999 首测**逐项同构**：对齐 pattern 34/8/11（含元变量捕获与 byteOffset 级一致）、dryRun 拦截（applied:false 文件不动）、真写盘（applied:true + git diff 可见 + 回滚）、`.vendor` 全程不重建、日志零 OMP/registry 行。被测面（包内 WASM 引擎 + 宿主 write dvc:// 路径）与端口无关，验收结论不受端口变更影响。
+
+
+## 五、终审补测（trimmed tarball）
+
+日期：2026-10-04 ｜ 背景：packaging-trim 后的发布物（`docs-packaging-trim`，731 文件 / 5.1 MB，此前轮为 22.2 MB）从未有 ast 调用驱动过——终审 Finding I3 补上这一半。`skill://dsh-dev-skill` 半边仍留作 publish-gate 条件（需 live LLM session，human 执行）。
+
+- **安装**：`npm pack` → `better-dsh-0.2.5-c.tgz`（shasum `5469abae…`）→ rig profile `plugin remove` → `add`（`Packages: +1`）；安装位 `lib/index.js` 与 fresh 构建字节一致、`lib/ast-assets` 16 文件 diff 为空；start 前 `.vendor` **ABSENT**。
+- **tarball 双面复核**：代码/产物面（`lib/`、`package.json`、`scripts/`）`grep -rc "pi_natives\|@oh-my-pi"` = **0 命中**；docs 面 6 个文件命中（trim 前 11），全部为 specs/plans/报告对本次迁移的历史 prose 记录——与 spec §1.2/§5.3 终审定界后的口径一致（docs 提及数量随发布内容浮动，非回归信号）。
+- **rig**：`PORT=4998` 重启（start.sh 接管旧 unit）；shell 页 boot graph 含 `"id":"better-dsh"`，`/plugins/??…better-dsh/client.js&rev=…` → **200**。
+- **驱动**：HTTP RPC 同 §4.8 两段形（web-password 铸 cookie → `session/create` → `session/prompt`，信封补 `type:"client-request"` 判别键）。会话 `session-cca50096-36f1-4d84-b3a0-9a75f06443d7`，1 turn、1 次工具调用（seq 20 `write` `dvc://ast_grep`，args 与 §4.8.3(a) 同款：`function $NAME($$$ARGS): $RET { $$$BODY }` / `includeMeta` / `limit:3`）。
+- **结果**（seq 21 原样）：**`totalMatches: 34, filesWithMatches: 8, filesSearched: 11, limitReached: true`**，分页返回 3 条 match；首条 `ctxCwd` 的 `byteStart 2610 / byteEnd 2821 / startLine 59` 与元变量四类捕获（NAME/ARGS/RET/BODY）与 §4.4(a')（4999 首测）、§4.8.3(a)（4998 复测）**逐字段一致**——trimmed tarball 的引擎面与 trim 前发布物零漂移。
+- **供给链**：调用之后 `.vendor` 仍 **ABSENT**（`ls` exit 2）；rig 日志 `omp|oh-my-pi|registry` **0 命中**。

package/node_modules/better-dsh/docs/50_test-reports/2026-10-03-better-dsh-tool-surface-repl-dvc-browser-ast-lsp-4999/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,185 @@
+# better-dsh 0.2.5-a 工具面实测报告：REPL / dvc://browser / dvc://ast_grep / dvc://ast_edit / dvc://lsp（4999 rig）
+
+> **状态**：第一人称实测完成（agent 在真实 4999 会话内自测并留证）。
+> **性质**：工具面**冒烟 + 回归**，**不是**发布验收——本轮未走 AGENTS.md §〇 的 a–d 发布闸，
+> 不涉及也不授权 `npm publish`。
+> **被测版本**：better-dsh `0.2.5-a`（package.json 与 profile 实装双侧一致）；core `@deepseek-ai/dsh` `0.2.0-rc.2`。
+> **仓库 commit**：`fb49834`（根仓与 `better-dsh/` 同 SHA）。
+> **rig**：`.test/home/compat`，端口 4999，unit `dsh-4999-test123`；本轮**未重启、未改产物、未动 prod**。
+> **时间**：2026-10-03 01:40–01:56 HKT（2026-10-02 17:40–17:56 UTC）。
+> **相关前序**：[2026-09-27-lsp-ast-reminder-4999实测报告.md](2026-09-27-lsp-ast-reminder-4999实测报告.md)（lsp/ast 提醒的发布轮）。
+
+---
+
+## 0. 方法
+
+- 全部证据取自**本会话内的真实工具调用**（第一人称），非单测、非静态检查、非进程活性。
+- `dvc://` 设备经 `write dvc://<device>` 执行，`read dvc://<device>` 仅取用法；REPL 证据取自 `eval` 单元。
+- 临时产物集中在 `.scratch/ast-probe/`；browser 设备测毕已 `close`（无孤儿 Chrome）。
+
+## 1. 结论摘要
+
+| # | 面 | 结论 | 关键证据 |
+|---|---|---|---|
+| 1 | REPL（`eval`） | ✅ 全绿 | 跨 cell 状态、完成值、工具桥、错误信封、异常存活 7/7 |
+| 2 | `dvc://browser` | ✅ 功能全绿；⚠️ 进不去带密码闸的 GUI | open/run/type+click/close + 字段白名单全通 |
+| 3 | `dvc://ast_grep` | ✅ 可用；⚠️ 相对路径基准非 workspace | 15 命中、`metaVariables`、`offset/limit` |
+| 4 | `dvc://ast_edit` | ✅ dryRun 与实写均正确 | `dryRun:true` 不落盘；`false` → `applied:true` 且盘面核实 |
+| 5 | `dvc://lsp` | ✅ gate + diagnostics + hover 全绿 | TS2322 error + TS6133 hint，坐标精确 |
+| 6 | AST 可用性提醒 | ✅ 实测出现 | `write` 结果尾行一行提醒 |
+
+净结论：**四个 dvc 设备与 REPL 主体功能无回归**；发现 2 个可用性摩擦（F1/F2）与 1 个 API 面不一致（F3），
+均非阻断，建议并入下一次批量发布（AGENTS.md §〇.5）。
+
+## 2. REPL（`eval` / dashr-repl 桥）— 全绿
+
+| 探针 | 结果 |
+|---|---|
+| 跨 cell 状态 | cell 1 设 `REPL_MARKER = "cell-1-alive"`，cell 2/4/6 读回一致 |
+| 导入持久 | cell 3 `import asyncio, json, collections`，cell 4 仍绑定 |
+| 完成值协议 | 末行裸表达式 `x`（=42）作为 completion value 返回，与 `print` 并存 |
+| 工具桥 | `await tool.bash({"command": "echo bridge-ok"})` → `bridge-ok`，exit 0 |
+| 错误信封 | 失败子调用抛 `ToolCallError`，`.toolName == "read"` |
+| 入参校验 | `tool.read({})` → `[E_BAD_SHAPE] Read request requires a non-empty "path" string.` |
+| 异常存活 | 内核在 SyntaxError、AttributeError 两次异常后仍持有全部状态 |
+| 内核 | CPython `3.11.15`（profile 内 `.venv-kernel`） |
+
+桥接口径与 wire description 一致（`await tool.<name>(args)` 单位置参数对象，`true/false/null` → `True/False/None`）。
+
+## 3. `dvc://browser`
+
+| 动作 | 结果 |
+|---|---|
+| `{"action":"open","url":"https://example.com"}` | `{ok:true, url, title:"Example Domain"}` |
+| `{"action":"run","code":"…"}`（DOM eval） | 取回 `title/links/readyState`，JSON 字符串回传 |
+| `{"action":"run","type":…,"click":…}` | 复合动作生效：`data:` 页 title 由 `t0` → `hello-dvc` |
+| `{"action":"close"}` | `{ok:true}` |
+| 未知字段 | `{"action":"open",…,"bogusField":1}` → `unknown field(s) "bogusField" for action "open" — allowed: "action", "url", "executablePath"` |
+
+**⚠️ 限制（F2）**：指向本 GUI（`http://127.0.0.1:4999`）时，`?token=` 启动 URL **不能**为新浏览器铸出会话——
+页面停在 `Enter the session password to continue. PASSWORD Unlock`，`window.__DSH_BOOT__` 不存在、
+无任何 `better-dsh` 资源请求。因此 `dvc://browser` 目前**无法**用于对本 GUI 做端到端第一人称验收，
+除非补一条 cookie 注入/免密通道。（本 rig 是密码闸实例；token 只负责首铸 cookie，而全新 Chrome 无 cookie。）
+
+**方法学附注（假阳性预防）**：首轮 DOM 探针返回 `h1count: 0`，一度疑似设备缺陷；
+核对线上原文后确认 **example.com 今日已无 `<h1>`**（仅 `<p>` + `<script>`），**设备是对的，探针是我的错**。
+记录此条以防后续把同类现象误判为插件 bug。
+
+## 4. `dvc://ast_grep`
+
+| 项 | 结果 |
+|---|---|
+| 模式 | `defineTool($$$ARGS)`，`includeMeta:true` → 命中 15 / 13 文件 / 扫 189 文件，`limitReached:true` |
+| 结构信息 | 每条含 `byteStart/byteEnd/startLine/startColumn/endLine/endColumn` + AST 级 `metaVariables` |
+| 分页 | `offset:10, limit:2` → 精确返回 2 条（分页生效） |
+| 语法错误容忍 | `defineTool({$$$})` 在 `defaults.json` 上语法不合法 → 该文件进 `parseErrors[]`，**整次搜索不失败**，其余 15 命中照常返回 |
+
+**⚠️ 相对路径基准（F1）**：`path:"better-dsh/src"` → `Path not found: No such file or directory (os error 2)`；
+改为绝对路径即通。决定性实验：**`path:"../../better-dsh/src"` 命中 15 条，与绝对路径结果一致**。
+即 ast 设备的相对路径基准 = **harness 进程 cwd（`upstream/deepseek-harness`）**，而非会话 workspace
+（`/home/u1/workspaces/dashr`）——与 `read/glob/grep` 的 workspace 基准**不一致**。
+返回值里的 `path` 也用同一基准显示（`../../better-dsh/src/bridges/index.ts`）。
+**规避**：始终传绝对路径。
+
+## 5. `dvc://ast_edit`
+
+输入（作用于 scratch 文件）：
+
+```json
+{"ops":[{"pat":"const $NAME = function ($ARG) { $$$B }","out":"function $NAME($ARG) { $$$B }"}],
+ "paths":["/home/u1/workspaces/dashr/.scratch/ast-probe/sample.ts"],"dryRun":true}
+```
+
+| 项 | 结果 |
+|---|---|
+| `dryRun:true`（默认） | 返回 `before`/`after` 与字节区间 `byteStart:74, byteEnd:128, deletedLength:54`；**`applied:false`，盘面未变** |
+| `dryRun:false` | 同区间，**`applied:true`**；盘面核实：`const legacy = function (x: number) {…}` → `function legacy(x: number) { return x * 2 }` |
+| `fileChanges`/`totalReplacements`/`filesTouched` | 1 / 1 / 1，与 `limitReached:false` 自洽 |
+
+`paths` 同样受 F1 影响（本轮用绝对路径，未复现相对路径问题）。
+
+## 6. `dvc://lsp`
+
+| 步骤 | 结果 |
+|---|---|
+| 初始 `status` | `{ok:true, gate:"unasked"}` —— per-session 闸，未询问态 |
+| `{"action":"on"}` | `{ok:true, gate:"on", message:"lsp on for this session: servers warm-start per language on first file contact; no repo artifacts are written."}` |
+| `diagnostics`（植入 2 处错） | `server:"typescript-language-server"`，自动推断 `root`；返回 **TS2322 error**（`Type 'number' is not assignable to type 'string'`，4:3）+ **TS6133 hint**（`'unusedVar' is declared but its value is never read.`，1:7）；`summary:"1 error(s), 1 hint(s)"` |
+| `hover`（3:17） | ```typescript\nfunction bad(x: number): string\n``` |
+
+坐标与 `severityName`（error/hint）均正确；服务器来源为 `typescript-language-server`。
+
+## 7. AST 可用性提醒 — 实测出现
+
+对新建 `.ts` 文件执行 `write`，结果尾部实测出现：
+
+```
+ast_edit / ast_grep available — write dvc://ast_edit (structured rewrite) or dvc://ast_grep (pattern search)
+```
+
+与前序报告的制度一致（提醒挂 `write/edit/grep` 结果尾部、per-session cap）。
+**注**：本轮未观测到 **LSP nag**（在接触代码文件前已把 gate 置 `on`，`unasked` 条件不再成立），故 nag 路径未覆盖；
+提醒的 **cap 计数**本轮亦未触及边界（未做 >5 次触发）。
+
+## 8. 发现清单
+
+| ID | 严重度 | 面 | 现象 | 建议 |
+|---|---|---|---|---|
+| **F1** | 中（摩擦） | `dvc://ast_grep`/`ast_edit` | 相对 `path` 基准 = harness 进程 cwd（`upstream/deepseek-harness`），非会话 workspace；`"better-dsh/src"` 直接 `Path not found` | 二选一：①基准改为 workspace / `exec.cwd`；②保持现状但在 device help 明写"仅收绝对路径" |
+| **F2** | 中（能力缺口） | `dvc://browser` | 无 cookie 注入通道，进不去密码闸 GUI；`?token=` 不足以对新浏览器铸会话 | 若要支撑 GUI 端到端第一人称验收，需补 cookie/免密通道 |
+| **F3** | 中（API 一致性） | `llm_completion` | **返回类型不稳定**：成功回 **裸 `str`**（`'alpha beta gamma'`），失败回 **`dict`**（`{"error":"llm_completion() output reached its maxTokens ceiling"}`）；调用方 `r["text"]` / `r.keys()` 会炸 | 统一为判别式对象（`{ok:true,text}` / `{ok:false,error}`） |
+| **F4** | 低（调优） | REPL 子调用池 | 变更类子调用实际**串行**：4×`sleep 1` = 4.78s；6×`glob` = 14.71s。源码有 `maxParallelSubCalls`（默认 10）与 `parallel\|exclusive` 分类，但观测未见并行收益 | 复核 classify 是否把常用工具过度判为 `exclusive` |
+| **F5** | 低（体验） | `llm_completion` | `maxTokens` 偏小（16）时因推理吃掉预算而**整次失败**而非截断 | 考虑截断或给出可操作的错误提示 |
+| — | 观察（正面） | harness | 连续 5 次同参调用触发**重复调用护栏**并阻止了潜在死循环 | 保留 |
+
+## 9. 未覆盖 / 遗留
+
+- `dvc://lsp` 的 `references` / `definition` / `format` / `rename` / `code_actions` / `reload` 未在本轮复测
+  （2026-09-27 报告已全绿；本轮只补 `status`/`on`/`diagnostics`/`hover`）。
+- LSP **nag 路径**与 AST 提醒 **cap 边界**未覆盖（见 §7）。
+- ~~`dvc://ast_edit` 相对路径未复测（F1 已在 `ast_grep` 上定位）。~~ → **2026-10-04 已在 trimmed 安装位（4998, better-dsh 0.2.5-c）复测：F1 修复生效，`ast_grep` 与 `ast_edit` 的相对路径均按会话 workspace 解析，本轮无回归**；契约与边界面另见 `2026-10-04-ast_grep与ast_edit契约与边界实测报告.md`。
+- `agent` / `agent_message` / `agent_workflow` / `remote` / 各 URL scheme（`ctx://` `skill://` `dsh://`）
+  本轮未测（不属本次指定的工具面；`ctx://` 另有 2026-10-02 专项报告）。
+- 生产 3080 **未部署验证**（本轮纯 4999，未触碰 prod）。
+
+## 10. 复现命令
+
+```bash
+# REPL：在任意 4999 会话内
+#   eval: REPL_MARKER = "cell-1-alive"   →  下一 cell: print(REPL_MARKER)
+
+# ast_grep（务必绝对路径，或按 F1 用 ../../ 相对 harness 根）
+#   write dvc://ast_grep {"patterns":["defineTool($$$ARGS)"],
+#     "path":"/home/u1/workspaces/dashr/better-dsh/src","limit":5,"includeMeta":true}
+
+# ast_edit dryRun → 实写
+#   write dvc://ast_edit {"ops":[{"pat":"const $NAME = function ($ARG) { $$$B }",
+#     "out":"function $NAME($ARG) { $$$B }"}],
+#     "paths":["<abs>/sample.ts"],"dryRun":true}     # 再 dryRun:false 并 cat 盘面
+
+# lsp
+#   write dvc://lsp {"action":"status"}              # → gate:"unasked"
+#   write dvc://lsp {"action":"on"}                  # → gate:"on"
+#   write dvc://lsp {"action":"diagnostics","file":"<abs>/diag.ts"}
+#   write dvc://lsp {"action":"hover","file":"<abs>/diag.ts","line":3,"character":17}
+
+# browser
+#   write dvc://browser {"action":"open","url":"https://example.com"}
+#   write dvc://browser {"action":"run","code":"document.title"}
+#   write dvc://browser {"action":"close"}
+```
+
+## 11. 附：本轮环境事实
+
+| 项 | 值 |
+|---|---|
+| better-dsh | `0.2.5-a`（package.json ≡ profile 实装） |
+| core | `@deepseek-ai/dsh` `0.2.0-rc.2` |
+| commit | `fb49834` |
+| rig home | `.test/home/compat` |
+| 内核 | CPython `3.11.15`（`.venv-kernel`） |
+| LSP 服务器 | `typescript-language-server` |
+| browser 引擎 | Chromium（`puppeteer-core`，UA 含 `HeadlessChrome`） |
+
+> 注：`readlink /proc/<pid>/cwd` 在本沙箱内取不到 4999 进程的 cwd（进程在另一命名空间），
+> F1 的基准结论由**路径算术实验**（`better-dsh/src` 失败 vs `../../better-dsh/src` 全量命中）独立钉死，不依赖该读法。

package/node_modules/better-dsh/docs/50_test-reports/2026-10-03-docs-packaging-trim/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,82 @@
+# 2026-10-03 docs-packaging-trim 实测报告
+
+- **Change**: `docs-packaging-trim`（spec: `docs/specs/docs-packaging-trim/spec.md`，档位 F）
+- **执行**: 2026-10-04（batch 执行 Task 1 + Task 2）
+- **范围**: 仅发布打包面。repo 的 `docs/` 树一字未动（git status 复核，仅既有 ast-work 脏文件，与本 change 无关）。
+
+## 一、改动面（Task 1，commit `411ef47`）
+
+- `better-dsh/scripts/copy-docs.mjs` 重构为可导入模块：
+  - `export const EXCLUDE`（既有 4 条 + 新增 3 条：`hermes-dev-skill`、`dsh-dev-skill/pi-and-omp`、`dsh-dev-skill/src-scripts`）；
+  - `export function excluded(srcPath)`；
+  - `cpSync` filter 改为 `src => !excluded(relativeSrc(src))`（`relativeSrc` 剥前导 `../`；cpSync 传入的是绝对源路径，`(^|\/)` 锚使绝对/相对两形态等价匹配，目录遍历方式未动，既有行为字节等价）；
+  - 原直跑主体（rmSync + cpSync + boot-token 脱敏 walk）包进 `import.meta.url === pathToFileURL(process.argv[1]).href` CLI 守卫。
+- 新增 `better-dsh/scripts/copy-docs.d.mts`（brief 外必要补充）：brief 给定的测试文件原样 import `.mjs`，`tsc --noEmit`（NodeNext）报 TS7016；按仓内既有惯例（`src/devices/ast/engine/grammar-manifest.d.mts`）补兄弟声明文件后 tsc 归零。
+- 新增 `better-dsh/test/packaging/copy-docs-exclude.spec.ts`（brief 原文，5 用例）。
+- 验证：`npx vitest run test/packaging/copy-docs-exclude.spec.ts` **5/5 PASS**（TDD 先红后绿：改写前 5/5 FAIL，`EXCLUDE` 无导出）；`npx tsc --noEmit` **0 错**。CLI 守卫双向实测：`import()` 不触发拷贝；`node scripts/copy-docs.mjs` 正常产出（2 文件 token 脱敏）。
+- 全量 vitest 套件本批未重跑（纯构建脚本改动，无运行时面；仓内基线 600/601 先于本 change）。
+
+## 二、量化（Task 2）
+
+| 指标 | 前 | 后 | 备注 |
+|---|---|---|---|
+| `better-dsh/docs` 磁盘 | **89 MB** | **6.6 MB** | 前 = 用 `411ef47~1` 旧脚本现场重建后 `du` 实测 |
+| `80_upstream-docs-and-skills/` 内 | hermes-dev-skill 77M + dsh-dev-skill 11M | 仅 dsh-dev-skill **4.3M**（skill 304K + src 4.0M + src-README） | repo 侧 pi-and-omp 2.8M、src-scripts 3.4M 实测 |
+| npm tarball（0.2.5-c 同工作树） | **21.22 MB** | **4.84 MB**（**−77%**） | 前值 = 旧 docs 拷贝下 `npm pack` 现场实测；设计轮估值 20.3→3.7 MB 基于旧包构成（现包含 ast WASM assets 等），以本表为准 |
+| tarball 内 `hermes-dev-skill` 条目 | 794 | **0** | |
+
+与 brief 预期的偏差均为**基线漂移**（设计轮数字按当时包构成估算），非实现缺口。
+
+## 三、验收清单（spec §4）
+
+1. ✅ 发布副本不再出现 `hermes-dev-skill/`、`dsh-dev-skill/pi-and-omp/`、`dsh-dev-skill/src-scripts/`：`tar -tzf | grep -c` = **0**。
+2. ✅ repo `docs/` 一字不动：`git status -- docs/` 仅既有脏文件（ast-work 的 plan 文件，先于本 change）。
+3. ✅ 承重面完好：tarball 内 `dsh-dev-skill/skill/SKILL.md` = **1**、`dsh-dev-skill/src/site-pages-map.txt` = **1**；skill/chapters ch01–ch04 在。**SKILL.md sha256 三方一致**（repo = tarball = rig 安装位 `552cbc9c5efc…`）。
+4. ⚠️→✅ 零新增悬空引用：见下节。
+5. ✅ 发布副本 = repo docs 严格子集减 7 类排除（`comm` 交叉核验：shipped-not-in-repo = **0**；repo-minus-shipped 全部落在排除类内）。
+
+## 四、悬空引用核查（对 brief Step 3 预期的修正）
+
+解包 grep `hermes-dev-skill|pi-and-omp|src-scripts` 命中 **3 个文件**，非 brief 预期的"仅 src-README 一处"：
+
+| 文件 | 性质 |
+|---|---|
+| `80_.../dsh-dev-skill/src-README.md:22` | spec §3 **已知例外**（对 src-scripts 的结构自述，明示接受） |
+| `docs/specs/docs-packaging-trim/spec.md` | **本 change 自己的 spec**（描述"摘了什么"，自指引用） |
+| `docs/superpowers/plans/2026-10-03-docs-packaging-trim.md` | **本 change 自己的 plan**（brief/测试片段文本） |
+
+定性：后两处是 change 自带文档对被摘目录的**提名**，非指向已摘内容的活引用；spec §1.4 的实质契约（无悬空活引用）成立。字面 grep 预期在设计轮无法预见 spec/plan 自身随 docs 发布。**接受，不改写正文**（改写即分叉 repo 副本，违背 §1.2）。
+
+## 五、rig 冒烟（4998，rig 在场 → 执行）
+
+1. `dsh plugin remove better-dsh` → `plugin add /tmp/trimpkg/better-dsh-0.2.5-c.tgz`（compat home，remove→add 完整来回）。
+2. 安装位物理核验：`profiles/web/node_modules/better-dsh/docs/80_upstream-docs-and-skills/` 仅 `dsh-dev-skill`；SKILL.md、site-pages-map.txt 在位；`find` 无 hermes/pi-and-omp/src-scripts；docs 6.4M；`dsh-docs/` 48 项在位。
+3. `PORT=4998 bash .test/seed/test123/start.sh` 重启：监听正常。
+4. HTTP 实测（密码闸，seeded 口令登录）：shell 200（39,772 B）；boot graph 含 `"id":"better-dsh"`；`/plugins/??better-dsh/client.js&rev=98a2110f16da` 200（29,700 B ≈ 本地 lib/client 29,632 B + sourceMappingURL 行）。
+5. **技能面等价证据**：`skill-filesystem` 扫描根（project/user/agent-preset/custom）静态配置均不指向插件 docs；本会话（prod，仍在 pre-trim 安装位）技能目录实时列出 `dsh-dev-skill`，其描述与该 SKILL.md frontmatter 逐字一致 → 技能目录确从该文件取得；trim 保持该文件与章节、`src/docs/`、`site-pages-map.txt` 字节不变（sha256 同上），只移除正文零引用的兄弟目录。
+6. ~~**未执行项（记录在案）**：rig 上的活会话技能目录读取（`skill://dsh-dev-skill` 现场解析）未驱动——需要经密码闸 GUI 发起真实 LLM 会话，超出本批范围；按编排方预授权口径记录跳过理由。~~ → **已于 2026-10-04 由本 batch 之外的终审轮现场闭环，见 §七**。原文保留：rig 自身干净 boot（boot graph + client.js 200）已实证插件装载无损。
+
+### `dsh://docs` 拓扑澄清（brief Step 4 子项修正）
+
+`dsh://docs` 的解析（`src/url-schemes/docs-dir.ts` 最近优先 walk-up，`dsh-docs` 先于 `docs`）在**安装态**命中包根 `dsh-docs/`（DSH 官方文档，本 change 未触碰）。故"`read dsh://docs/50_test-reports/` 一份可读"在安装态拓扑下**不适用**——`docs/` 树仅在 `dsh-docs/` 缺席时才充当 `dsh://docs` 兜底。本会话实测 `dsh://docs` 列表正常（官方文档 200+ 项，无 `50_test-reports/`），与上述一致；trimmed `docs/` 树的消费者是技能面（第五节证据链）。
+
+## 六、结论与红线
+
+- Task 1 + Task 2 全部落地：发布副本 89 MB→6.6 MB 磁盘、21.22→4.84 MB tarball（−77%），外来材料（77 MB Hermes 镜像 + 59 MB api-skills.json 所在树）、未引用第三方资料、抓取工具全部离场；承重技能面字节不变；rig 在 trimmed 安装上干净 boot。
+- **`npm publish` 不在本 change 内**——按根 AGENTS.md 〇节，发包需第一人称实测通过 + user 单次明确放行，两道闸缺一不可。
+
+## 七、终审人为条件闭环：`skill://dsh-dev-skill` 活会话实测（2026-10-04）
+
+§五.6 记录的唯一未执行项（trimmed rig 上的活会话技能目录读取）已于本批之外驱动并通过。**执行方式**：在 trimmed 安装位（本 rig，端口 4998，密码闸 GUI 之后的真实 LLM 会话）现场执行 `read skill://dsh-dev-skill`，且由**两个互相独立的主体**各跑一次——(a) 编排会话本体；(b) **冷上下文子 agent**（不带任何预热/继承的技能目录状态，独立 session）。
+
+| 检查 | 结果 |
+|---|---|
+| `read skill://dsh-dev-skill` 返回 SKILL.md 正文 | ✅ 完整正文：H1 + `**Source**` 行 + How to Use This Skill + 8 条 Core Mental Models + 章索引 ch01–ch22 + ~55 条 Topic Index + Supporting Files + Scope & Limits 收尾。无错误信封、无 `[truncated]`、无缺路径标记；结尾句完整，非截断 |
+| 冷上下文子 agent 独立复现 | ✅ 与 (a) 逐字一致（含前 20 行原文引用）；两通道均 PASS、均零错误文本 |
+| 技能目录**树**承重面（不只在 router 层） | ✅ `read skill://dsh-dev-skill/chapters/ch15-subsystems-tool-execution.md:1-15` 返回真实章正文（Core Idea / Frameworks Introduced），非空、非错误 —— 证明解析穿透到章文件，router 之外的目录亦在位 |
+| 解析源确为 **trimmed 安装位**（非 repo 旁路） | ✅ 安装位 `…/profiles/web/node_modules/better-dsh/docs/80_upstream-docs-and-skills/` 顶层**仅 `dsh-dev-skill`**（无 `hermes-dev-skill`/`pi-and-omp`/`src-scripts`）；`skill/chapters` = **22** 项；`skill/SKILL.md` sha256 = `552cbc9c5efcc418e8e10eb85e8628a61174a283bf2b8df9b5180d184ea3d375`，与 repo 副本**逐字节一致**，亦即 §三.3 记录的那一枚 |
+| 与 §五.5 静态等价证据的关系 | 本轮为**活会话动态解析证据**，补上 §五.5 静态等价链缺的那一环；两者路径独立、结论一致 |
+
+**结论：技能面在 trimmed 安装位上现场可用，`docs/` 瘦身未打断技能目录解析。§五.6 未执行项关闭。** 证据边界（诚实记录）：`read` 面返回的是 SKILL.md 正文，**未显示 YAML frontmatter**（`---` 包裹的 `name`/`description`）——与该 face 的既有呈现方式一致，不影响正文完整性判定；§五.5 已用 frontmatter 描述逐字比对另行取证。
+
+**附（同批顺带执行，非本 change 验收项）**：`write dvc://ast_grep {"patterns":["export function $NAME($$$ARGS)"],"path":"better-dsh/src/devices/ast"}` 实测 `totalMatches: 0`、`filesSearched: 11`。根因非工具故障：该 pattern 非完整 AST 节点（缺函数体），ast-grep 抛 `Multiple AST nodes are detected`，而 `src/devices/ast/engine/match.ts:68` 对该错误**静默回落为空结果**（`return { matches: [], unavailable: false }`）。交叉验证：同目录 grep 实测 10 处 `export function`；改用完整节点 pattern（`export function $NAME($$$ARGS) { $$$BODY }` 等三条）当场得 `totalMatches: 13 / filesWithMatches: 8`。记录为**已知行为面（错误静默）**，不影响本 change 结论，另见 ast 设备契约条目。