better-dsh 0.2.5 → 0.3.0-a

package/docs/dev-test-environment-notes.md

@@ -0,0 +1,137 @@
+# 开发环境拓扑与历史记录（根 AGENTS.md 迁出）
+
+本文件按需阅读，不是自动加载的行为总纲。以下保留 2026-10-06 迁出时的原文，包含已退役路径、旧版本验证与待勘误事项，不能当作当前操作手册照抄。
+
+现行通用开发与测试规范以 [Cordis-dsh-dev-test-guides.md](../Cordis-dsh-dev-test-guides.md) 为准；rig、启动和测试资产以 [.test/README.md](../.test/README.md) 及对应 seed 文档为准。遇到冲突先核实当前脚本和上游官方入口，不将历史 workaround 当作必需机制。
+
+## 二、Dev/Test 1：源码级 4999 实例（upstream checkout + 内嵌 dashr）— 推荐回归路径
+
+整个 harness 从源码跑，dashr 作为 workspace 成员内嵌其中，与 prod 完全隔离。**2026-09-02 已全链路验证。**
+插件开发与测试环境的现行规范见仓库根 `Cordis-dsh-dev-test-guides.md`（两层文档制的第二层，2026-09-27 起；冲突以其为准）；本节记录本仓拓扑事实，rig 清单（含 bun distro 产物 rig `bun-test`）见 `.test/README.md`。
+
+### 组成（2026-09-24 重构：干净 harness + plugin-add 交付形态；旧 monorepo 内嵌流已退役）
+
+- Harness: `./upstream/deepseek-harness`，git tag **`dsh-v0.1.7-rc.1`**（2026-09-24 全新 clone 重建；本地 patch：unrun devDep / root vite devDep（rc.1 新增，apps/desktop tsdown config 运行时 import vite，unrun 缓存目录解析不到）/ storeDir+verifyDeps+zeromq+ssh2 / tsdown `resolveRepositoryRoot` / vite preact 三件套，重放流程与坑见 `docs/50_test-reports/2026-09-24-v0.1.7-rc.1对齐轮-compaction与failover设置面修复实测报告.md` §四）。**upstream 内不允许出现 better-dsh 的任何内容**（旧 `packages/better-dsh/` 内嵌副本 + devDeps 手术 + sync 脚本已于本轮废除）。
+- better-dsh **独立开发**：devDependencies 不含任何 `@deepseek-ai/*`（范围符号在 peerDependencies = 发布契约）；`node_modules/@deepseek-ai/*` 由 `scripts/link-upstream.mjs` 生成 symlink 农场指向 upstream 物理包——upstream 换 tag 后 farm 自动跟随（目录级 symlink），package.json 零改动。`.npmrc` `legacy-peer-deps=true` 防 npm 自动装 optional peers（tuple 规则会解析到三代前的 0.1.5-rc.3）。开发循环：`npm run build` → `tsc --noEmit`（0 错基线）→ `npx vitest run`（600/601）。
+- 测试 rig **`.test/seed/test123/`**（现行，README 有完整种子再生步骤）：home 在 `.test/home/`（2026-09-27 裁决：**home 复用不换场**——`compat/` = 默认长寿命 home，user data 与 `.credentials.yaml` 是测试资产跨重置保留；`RIG_HOME=clean` 仅在专门验证首次行为时临时建一个、用完即删；gitignored）；~~`profiles/node_modules/@deepseek-ai/*` symlink 农场~~ **已于 2026-09-26 删除**（user 指令；0.1.7 安装域拦截供给全部 harness 面——无农场 boot 实证：shell 200 + boot graph 含 better-dsh + client.js 200 + zoom-guard/`__DASHR_MOBILE__` host 半注入在位、日志零解析错误；rig 与 prod 解析模型现完全同构）；profile `web` 的 better-dsh 是 **`dsh plugin add <tarball>` 物理安装**（入场一律走 plugin add；`npm pack` 出交付物 → add → 重启；remove→add 一个来回才能刷新 file: tarball 内容）。旧 `.tests/dsh-test1/` 与 `.dsh-test/` 已删除（2026-09-24 清理，`.test/` 布局落地）。**0.1.7 settings 模型**：namespace = Loader entry id（如 `dashr-failover`），`installSection` 已删；volatile 字段 + `settings.configure({auto:false})` + configEditor 落 profile patch 用户层（upstream `agent-default-model` 范式）。
+
+### harness 本地 patch（该环境必须，缺一 build 即挂）
+
+1. `packages/client/tsdown.client.ts`: `REPOSITORY_ROOT` 由 `resolveRepositoryRoot()` 推导（`pnpm-workspace.yaml` 锚定，`process.cwd()` 兜底）。原因: 本机 Node 22.22.1 `process.features.typescript=false` → tsdown auto loader 选 unrun，unrun 的 bundle 级 define 把内联 preset 的 `import.meta.url` 改写成各包入口 config 的 URL，`packages/*/*` 深度下 `../..` 落到 `<repo>/packages/`，manifest glob 全空 → `no packages/*/*/package.json declares the name …`。upstream CI 的新 Node 走 native loader，看不到此问题。
+2. `pnpm-workspace.yaml`: `storeDir: /home/u1/workspaces/dashr/.scratch/pnpm-store` + `verifyDepsBeforeRun: false` + allowBuilds `zeromq: true`（better-dsh 自 0.2.2-a 起零 lifecycle script，无自身 allowBuilds 条目）。原因: pnpm 11 不读 `.npmrc`；默认 deps-check 会 spawn `pnpm install`，向只读的用户级 store 注册 project → EROFS；strictDepBuilds 下未列 build script = install 硬错。
+   （**另记 2026-09-13**：`pnpm add` 之后 `npx vite` 会从根解析到 vite 8/rolldown——web 构建一律走 `pnpm run build:web`（workspace 内 vite 6.4.3），勿用 npx 直呼。）
+3. **（2026-09-13，change `2026-09-13-preact-ui-shell`）** `apps/web/vite.config.ts`: `resolve.alias` 增 react 家族五条 → `preact/compat`（regex 锚定）+ `resolve.dedupe` 增 `'preact'`（dedupe 条目从本包 node_modules 解析——缺它则 `packages/client/web/lib` 的 seed 解析不到 apps/web 里的 preact）；`apps/web` devDeps 加 `preact@10.29.8` 精确 pin。效果：shell 平台种子物化 preact 实例，全部 ui-* 插件 bundle 的 `require("react")` 零改动获得 Preact；shell index chunk 555,959 → 434,173 B（−21.9%），A/B 实测挂载面一致、console 零错。**同一 patch 顺带根除了 `vendor/CLAUDE.md` ENOTDIR/exit 236 老坑**：`vendor/` 根下的三个文档文件（AGENTS/CLAUDE/README.md）撞 `vendor/*` workspace glob——**0.1.6 起 `vendor/docs/` 也不行**（tsdown root tsdown.config 的 `vendor/*` workspace glob 会把无 package.json 的目录当幻影包，整 build 死，见对齐轮 §七），三个文件现放 **`.scratch/vendor-docs/`**（vendor 根下不允许存在任何子目录缺 package.json）。
+### 构建（setup 或 harness 变更后）
+
+```bash
+cd ~/workspaces/dashr/upstream/deepseek-harness
+pnpm install        # store 已重定向到 .scratch/pnpm-store
+pnpm run build      # tsc lib/types + tsdown host/client + vite web + client build record（0.1.5-rc.2: 234 client artifacts，含 build:native-system）
+```
+
+### 启动 / 重启
+
+```bash
+# 2026-09-24 起：测试实例一律用 `bash .test/seed/test123/start.sh`（PORT=xxxx 可覆盖，默认 4999；
+# LAN 中继默认开——socat 只绑 LAN IP 转发 loopback；webserver 只收 127.0.0.1|0.0.0.0 字面量
+# 且 startup 硬拒 0.0.0.0，直接绑 LAN IP 不可能）。脚本自带：停旧+等端口真释放、
+# 测试口无主化接管（2026-09-27 裁决：占口者属测试 unit 即停掉接管，非测试监听才拒绝）、
+# seed 感知输出（seed 持久时明说 cookie 仍有效）、本 boot token 轮询提取（append 日志防串台）。
+# 脚本内部即下面的 canonical 命令（unit dsh-4999-test123 + test123-lan-4999-relay）：
+systemctl --user stop dsh-4999-test123 test123-lan-4999-relay 2>/dev/null
+systemd-run --user --unit=dsh-4999-test123 \
+  -p WorkingDirectory=/home/u1/workspaces/dashr/upstream/deepseek-harness \
+  -p Environment=DSH_HOME=/home/u1/workspaces/dashr/.test/home/compat \
+  -p 'Environment="DSH_TRUSTED_HOSTS=test.pc.randomhash.app pc.randomhash.app 192.168.31.130"' \
+  -p 'UnsetEnvironment=DISPLAY WAYLAND_DISPLAY' \
+  -p StandardOutput=append:/home/u1/workspaces/dashr/.scratch/dsh-4999-test123.log \
+  -p StandardError=append:/home/u1/workspaces/dashr/.scratch/dsh-4999-test123.log \
+  "$(which node)" apps/cli/lib/bin.js web --no-open --port 4999
+# ⚠⚠ 2026-09-22 双平面修复起：boot 必须走**构建产物** `apps/cli/lib/bin.js` + 裸 node，
+#   勿再用 `node --import tsx/esm apps/cli/src/bin.ts`（tsx 源码启动）！
+#   根因（dual-plane symbol split）：tsx 源码启动下 TS 文件经 tsconfig.base.json `paths`
+#   落 src/，而 plugin loader 把组合行解析到构建 lib 的 file URL → 同进程两份
+#   dsh-tools/cordis 模块实例 → `Symbol('@deepseek-ai/dsh-tools.scheduler')` 键在
+#   lib 侧 ToolRuntime 与 src 侧 agent-loop 之间错位 → 每个 session 的**第一个工具调用**
+#   必崩 `Cannot read properties of undefined (reading 'prepare')`（UNKNOWN），孤儿
+#   tool/call 事件毒化 session log → 后续每轮 DeepSeek INVALID_REQUEST "tool calls
+#   need immediate results"。const enum（如 cordis `FiberState`）使 paths-less 收敛
+#   不可行——唯一正解 = 产物面启动（与 prod 同构）。lib/bin.js 前置条件：改动 src 后先
+#   `pnpm run build` 全量。A/B + 真 session 证据见
+#   `docs/50_test-reports/2026-09-22-4988双平面启动修复实测报告.md`。
+# ⚠ 与 prod 对齐的两行必须带：DSH_TRUSTED_HOSTS（fence + web-trust authorities 单源，
+#   覆盖 test.pc… / pc.randomhash.app / LAN）与 UnsetEnvironment=DISPLAY WAYLAND_DISPLAY
+#   （prod dsh.service 同款——否则 directory-picker auto 在图形 env 下选 native，zenity
+#   弹在宿主桌面，经 Caddy 远端访问时 Add workspace 表现为无响应后置灰；2026-09-08 实证）
+# user 终端（非沙箱）等价简式:
+# cd ~/workspaces/dashr/upstream/deepseek-harness && DSH_HOME=~/workspaces/dashr/.test/home/compat node apps/cli/lib/bin.js web --no-open --port 4999
+# ⚠ 旧简式 `npm run dsh -- web …`（内部 tsx 源码启动）自 2026-09-22 起禁止用于回归验收——同上双平面必崩
+#   （`--dump-config` 这类 config 面检查不受影响，仍可用 tsx 形态）。
+```
+
+> **勿从 agent 沙箱化 bash 直接拉 daemon（2026-09-03 实证）**：沙箱内启动的 daemon 继承嵌套沙箱环境，其 bwrap 功能探测（`sandbox-local defaultProbeBwrap`）报 `No permissions to create a new namespace` → `SANDBOX_UNAVAILABLE`（agent bash 无沙箱后端）。systemd-run --user 在沙箱外启动（对齐 prod 形态）；沙箱内连 user bus 会被拒，需单命令 `danger-full-access` 升级。stop/日志：`systemctl --user ... dsh-4999-test` / `.scratch/dsh-4999.log`。
+
+- token（`?token=`）是 per-boot 进程内随机 launch token，只负责首铸 cookie；**认证 seed 持久在 `$DSH_HOME/.credentials.yaml`**——home 不换则 seed 不变，**浏览器 cookie 30 天内跨重启直接可用，重启 rig 不需要换 token / 重注 cookie**（2026-09-27 裁决；机制见 guide §3.3）。从 `.scratch/dsh-4999-test123.log`（或 start.sh 输出）取 token URL；curl 冒烟需 cookie jar: `curl -c jar -L '<token-url>'`（303 重定向靠 cookie 保认证）。
+- 数据只落 `.test/home/compat/`（sessions/storages），与 prod 隔离；重置只动 `profiles/web`，user data 保留。
+
+### 日常回归循环（recurring，2026-09-24 起：交付形态）
+
+canonical 构建 → 验收走 tarball；快速迭代走 profile 内物理 lib 替换（**只碰 profile，永不碰 upstream**）：
+
+```bash
+cd ~/workspaces/dashr/better-dsh && npm run build        # tsdown + build-client
+# 快路径（client 半边改动）：直接覆盖 profile 里的物理安装，刷新页面即生效
+rsync -a --delete lib/ ~/workspaces/dashr/.test/home/compat/profiles/web/node_modules/better-dsh/lib/
+# host 半边改动：同上覆盖后重启（start.sh）
+# 阶段性验收（发布前必走）：npm pack → remove → add → 重启
+cd ~/workspaces/dashr && DSH_HOME=$PWD/.test/home/compat node upstream/deepseek-harness/apps/cli/lib/bin.js \
+  plugin --profile web remove better-dsh
+DSH_HOME=$PWD/.test/home/compat node upstream/deepseek-harness/apps/cli/lib/bin.js \
+  plugin --profile web add $PWD/better-dsh/better-dsh-<version>.tgz
+bash .test/seed/test123/start.sh
+```
+
+- **⚠ file: tarball 内容更新 pnpm 不自动刷新**（同版本同路径 → `added 0`）：改完包必须 remove → add 一个来回，别信 add 幂等。
+- **⚠ lib/client 清洗陷阱仍在**：tsdown 清空 lib/ 会抹掉 lib/client/，`npm run build`（= tsdown && build-client）已串好两步，勿单跑 tsdown。
+- 验证：boot graph 含 `"id":"better-dsh"`；`/plugins/??better-dsh/client.js&rev=…` 200；Settings/General 两行在（compaction stepper + failover selects）。
+- `--dump-config`：`DSH_HOME=… node upstream/deepseek-harness/apps/cli/lib/bin.js web --dump-config | grep -A2 dashr-repl`。
+
+### 已验证 / 未验证
+
+- ✅ `dashr-repl` 工具行 + `DASHR_KERNEL_PYTHON` config 注入；web shell + assets HTTP 200；`.dsh-test/storages/workspace.json` 落盘。
+- ✅ **kernel 三级供给**（2026-09-03，change `kernel-provisioning-completeness`）：postinstall/spin-up/首用 lazy 全 fail-open；冷启动 spin-up 自动重建 venv（pinned ipykernel 7.3.0 / dill 0.4.1 / CPython 3.11，无 uv 时 python3-venv 兜底 3.14.4 实测兼容）；uv cache 重定向包内 `.uv-cache`，只读 HOME 实测无碍；一页文档 `docs/kernel-provisioning.md`。
+- ✅ **client 卡片半边已通**（2026-09-03，change `model-failover-settings-surface`；2026-09-03 npm 改名后 id 为 `better-dsh`）：副本内构建用 **`tsx scripts/build-client.ts` 直跑**（33ms；⚠ `npm run build-client` 在 monorepo 副本必死——npm 自身 pre-script 的 workspace 枚举读 pnpm-workspace `vendor/*` glob 匹配到普通文件 CLAUDE.md → ENOTDIR/exit 236，与脚本无关）；验证法：鉴权拉 shell 页 → boot graph 应含 `"id":"better-dsh"` 与 `/plugins/??better-dsh/client.js&rev=…` URL → curl 该 URL 200 且与 `lib/client/index.js` 字节一致（服务端仅追加 sourceMappingURL 行）。原生注册路径已核实：settings 行 = client bundle 内 `ctx.slots.inject('settings.general.item', …)`（与 locale/ui-chat 原生行同构）。
+- ✅ **web-trust 双腿 + mobile-layout 随插件发布**（2026-09-03，change `plugin-shipped-ui-patches`，v0.2.1-f；**round-4 手势整体重写为 z_dsh-alpha `1706b81` 逐条照搬**，commit `0676811`）：**fence 腿** = bundle patch 整行重述 `connection` 行（`trustedHosts: !!js (process.env.DSH_TRUSTED_HOSTS ?? '').split(/\s+/).filter(Boolean).concat(ctx.webRuntime.trustedHosts)`；⚠ `!!js` 是 scalar tag，表达式**不能以 `[` 开头**否则 yaml 按 flow-seq 拒收）；**isLoopback 腿** = host 半 `webserver/index-inject` 内联 boot script（trusted hostname → `window.__DSH_TRANSPORT__={ownsHost:true}`；mobile 阈值 → `__DASHR_MOBILE__`——client 半无 config，页面全局即配置通道）；**mobile 手势 = 旧 ui-layout 补丁 exact port**：X120 左缘带 / 右 3/4 起点区（viewport/4）/ 距离 40px / 水平占优 ×1.3 / 断点 <768 / **pointermove 中途一次性触发**（pointerup 判定被浏览器滚动手势 pointercancel 吃掉 = "必须快划"的根因）/ document 捕获监听 / 右面板 = Better Sidebar 浮层，经 `[data-dsh-toggle-cluster]` 末按钮 DOM click、状态读 `body[data-dsh-sidebar-collapsed]`、会话门槛读 `[data-slot="conversation.session.header"]`；**唯一增量** = 速率门 `swipeVelocityPxPerMs` 默认 0.15（0=关闭）。round-2 发明的 48/28 值已废弃。425/425 + tsc 0；4999 经用户真实 URL `https://test.pc.randomhash.app` CDP 实证（开/关左栏 + 开/关右栏 + Models provider 列表全过；该域名已入 trustedPageAuthorities）。报告 `docs/50_test-reports/v0.2.1f-plugin-shipped-ui-patches实测报告.md`。
+
+- ✅ **iOS focus 放大抑制 zoomGuard**（2026-09-03，change `ios-focus-zoom-suppression`，v0.2.4，commit `59870fc`；纯 host 半，client 零改动）：boot script 增 zoomGuard 段 —— iOS 系 UA（iPhone|iPod|iPad + iPadOS 桌面冒充 Macintosh&&maxTouchPoints>1）∧ 窄视口（`matchMedia('(max-width:'+(breakpoint-0.02)+'px)')`，断点复用 mobile.breakpoint）双门控下 token 级合并 viewport meta `maximum-scale=1, user-scalable=no`（幂等、可还原、resize + MQ change 双通道复评 + **早期载入重评梯子** ~10ms×200tick —— 引擎载入期应用 viewport 不派发 resize 的实测缺口，deferred focus 可先于事件补评）；**mobile 配置面新增 `zoomGuard`**：`'meta'`（默认，**v0.2.5 起自动双形态**：browser=meta 改写 / standalone=字号地板）| `'off'`（逃生门，'off' = 整段不发射），`'font'` 值位预留不进 enum（未实现值 fail-loud）。五个纯函数（`src/mobile/zoom-guard.ts`，ES5 自包含）经 `Function.prototype.toString` 嵌入 boot script = 单测源即发布源。**关键机制发现**：head 注入 splice 在 `<head>` 开标签紧后 = stock viewport meta 后于脚本解析 → provisional meta + MutationObserver reconcile（stock 插入时改写其本体并移除 provisional，单 meta 文档，S7 查表第 8 条盯两查点）。**v0.2.5 display-mode 分流**（2026-09-03，change `zoomguard-standalone-font-floor`，tag `v0.2.5`；真机实证：standalone PWA 态引擎尊重 `user-scalable=no` → pinch 失效）：iOS 门后、meta 机器前一次性判定 standalone（`(display-mode: standalone)` MQ ∨ `navigator.standalone===true`，严格 `=== true` 双源 OR）→ 注入 `<style id="ios-zoom-font-floor" data-plugin="better-dsh" data-plugin-css="better-dsh/zoom-font-floor">`（16px 字号地板，`@media (max-width:{bp-0.02}px)` 与 meta 腿同派生 768→767.98；**注入不设宽度门**，宽度由 CSS media query 表达）后 return —— 零 meta 机器/零监听/零 timer/零窄带 MQ 探针，meta 字节不动；browser 态 v0.2.4 机器原样，'off' 两形态都不发射（web-trust 门不变零改动）。478/478 + tsc 0。466/466 + tsc 0（v0.2.4）；**4999 已验**（CDP 矩阵 9/9 + off 逃生门 live + 桌面 user 复验，报告 §八；v0.2.5 双形态 CDP 待 lead，报告 §九）；真机 PWA 复验待 user（报告 `docs/50_test-reports/v0.2.4-ios-focus-zoom-suppression实测报告.md`，键盘遮蔽自愈判定驱动 follow-up 取舍）。CLI 注：`web` 子命令不认 `--patch`，config 覆盖走 home 层 `cordis.patch.yml`。**发布定格（2026-09-03 user 裁决）**：本地过程版本 0.2.4/0.2.5 的 tag（v0.2.3~v0.2.5）已清，npm/GitHub 发布为 **`0.2.2-b` / tag `v0.2.2b`**（0.2.2 系列顺延；真机全过后 user 以普通用户身份从 npm 装 prod 实测）。
+
+- ✅ **hashline content-locator**（2026-09-08，change `2026-09-08-v0-2-3b-hashline-content-locator`，v0.2.3-b）：served 账本去 session 化（schema v7，**path 主键**，`E_RANGE_UNVERIFIED` 跨会话类消灭）、集中存储 **`$DSH_HOME/storages/dsh-better-edit/`**（`configDir()` 无参化，终结 12 个 workspace 点目录——"到处拉屎"裁决落地）、verifyServedRange 内容快道（账本双界未见→内容放行；STALE/UNSERVED 保留；retryHint 改 read-once-then-resubmit）、write-hook 删除（write 仅上游确认信封，无锚点回放）。单测 `test/hashline-store.spec.ts` 12/12；全量 491/2（2 挂经 stash 基线证实先于本改动）；4999 第一人称实测通过（write 无回放 / 中心库无 session_id 列 / 无点目录 / read-then-edit 落盘）。实测定性：宿主 `dsh-fs-observation-policy` 的 `E_NOT_OBSERVED`（read-before-edit）为跨会话 edit 的**另一道设计内守卫，保留**。报告 `docs/50_test-reports/v0.2.3b-hashline-content-locator实测报告.md`。**新坑**：副本构建必须 `pnpm --filter better-dsh exec tsdown`——裸跑 `node_modules/.bin/tsdown` 产出 `.mjs` 形态，boot 即 `ERR_MODULE_NOT_FOUND lib/index.js`。已发布 **v0.2.3-b**（npm registry 2026-09-08 18:15 UTC+8，dist-tag `latest`）并部署 prod（18:19 装机、18:44 重启上线，中央 v7 库活体——本 3080 实例即运行其上）。
+
+- ✅ **mobile wave：官方寻址 + 状态驱动响应式**（2026-09-11，对齐 0.1.5-rc.2；**已发布 `0.2.3-c` / tag `v0.2.3c`**，npm dist-tag latest，含随批的 0.1.5 对齐移植；prod 3080 未部署——user 未指令，待 user 以普通用户身份自装实测）：①**手势状态输入只认官方面**（红线，起因：旧实现把 readRightOpen 挂在第三方 Better Sidebar 的 body 属性上，插件移除后恒 true 毒死整个状态机——左滑右滑全灭）；左栏 = `ctx.layout.toggleSidebar()` + AppFrame `[data-sidebar-collapsed]`，右栏 = 官方控件 `[data-sidebar-right-expand]`（会话头角落，开）/`[data-sidebar-right-toggle]`（dock chrome，关；store 动作 setExpanded/toggleExpanded 为 slot-store 内部，跨插件硬边界 → 原生按钮即正规入口）+ 状态读双 facet：`[data-rightbar-fullscreen]` 在场即开（手机全屏右栏不占轨道、`data-rightbar-collapsed` 同场在场——单 facet 读法致右滑误开左栏，user 真机诊断后修复）。②**响应式零自设像素阈值**：CSS 键纯 `[data-sidebar-collapsed]`（无 @media）——上游 auto-collapse（今日 1024）为真收 56px rail 时我们压成 0px，上游改阈值自动跟随；手势 band = 粗指针（`pointer: coarse`）∨ 任一面板处于窄态，细指针全静息（桌面文本拖选永不误触）。③**`mobile.breakpoint` 配置删除**（schema+boot payload+client），zoomGuard 自带内部 768 兜底不受影响；所谓"mobile 配置卡"从未存在过（client 半唯一设置行是 failover）——MOBILE_CONFIG 一直是纯配置文件面。425→492 tests + tsc 0（monorepo 0.1.5-rc.2 手术环境）；4988 已部署活体 + user iPhone 真机确认（"没有问题，是成功的"）；0.1.3-alpha.2 prod host 兼容矩阵源码核验通过（stat/open、sendMessage、ptc-dispatch-log 均在；`tool/ptc-dispatch` 事件 vocabulary-growth 容忍 = 降级不破坏，host 升 0.1.5 自愈），报告 `docs/50_test-reports/v0.2.3c-mobile-wave实测报告.md`。
+
+
+- ✅ **REPL 指引单源化：control prompt 并入 eval description**（2026-09-11，change `2026-09-11-control-prompt-into-eval-description`，**已发布 `0.2.3-d` / tag `v0.2.3d`**）：`dashr:control-prompt` + `dashr:tool-catalog` 两 system-prompt section 整体删除，全部 REPL 指引改由 **`eval` 的 wire description** 承载（内容 = 包根 `dashr/eval-description.md`，`package.json files` 同步——坑：漏列即模块期 readFileSync ENOENT、插件加载即死，实测已修）；`src/py-sdk.ts` 渲染器整体拆除只留 `isFlatBindableName`；桥接口径 = 统一调用形一句话（`await tool.<name>(args)` 单位置参数对象，`true/false/null`→`True/False/None`），**对返回值形态零陈述**（user 裁决：明写"不保证/试错"抑制使用）；示例键 `path`（D1 修正——注意 vendored `normalizeRequest` 的 `file_path→path` 别名仍在，旧键侥幸可用，见报告 §5.1）。提示面 A/B：两 section **−8,759 chars**（本 change 净 −52.6%，残余 +1,944 为 v0.2.3-b hashline 指引）。实测报告 `docs/50_test-reports/2026-09-11-control-prompt-into-eval-description实测报告.md`；遗留：非 flat 名无真实 MCP 端到端样本（本 runtime 无 MCP 工具）、prod 3080 未部署（待 user 以普通 user 自装实测）。
+
+---
+
+## 三、Dev/Test 2：wire the prod core（prod 核 + dev 插件）— 未实操，细节待勘误
+
+prod npm CLI 当 harness 核，只把插件本体和它的 harness 依赖换成 dev 版。
+
+- 核: `~/.local` npm 全局 `@deepseek-ai/dsh` 0.1.7-rc.1（2026-09-23/24 user 升级）；profile `web` 在 `~/.dsh/profiles/web`（pnpm hoisted 物理 tree）。
+- 插件线: `./better-dsh` `npm run build`（= `tsdown && npm run build-client`）→ md5 核对同步 `lib/` 到 `~/.dsh/profiles/web/node_modules/better-dsh/lib`（v0.2.1c 的部署方式）→ 重启 `dsh.service`。
+- harness 依赖线: **已退役**（原 `better-dsh/node_modules/@deepseek-ai/*` symlink 到 dsh-alpha 源码的方案，2026-09-02 已删——实测 host ②③ 层全量自供，嵌套 symlink 无一必需，且 alpha.1 指向对 alpha.3 host 是版本偏斜负债）。
+- 解析即第一节 ①→④ 分层；现已验证插件运行期只依赖 ②③（host 自供）+ ① 的 schemastery/cosmokit。
+- ~~剩余待验证~~ **已收敛（2026-09-02）**: `./better-dsh` 构建产物 md5 同步线的 prod 冒烟已跑（v0.2.1c 同步态活体 4 探针 4/4）；profile 锁/lockfile/部署位已统一为 `0.2.1-d`（经 `dsh plugin add @pgmi-builds/better-dsh@0.2.1-d`，见第一节供应链年龄门）。**发布态部署的正道是 pnpm add 精确版本**，手工 md5 同步仅限未发布的本地迭代。
+
+---
+
+## ✅ prod 插件嵌套 symlink 悬空 — 已清理（2026-09-02），重启安全
+
+`dsh-alpha` 改名 `z_dsh-alpha` 后，`~/.dsh/profiles/web/node_modules/better-dsh/node_modules/@deepseek-ai/*` 的 17 条 symlink 曾全部悬空。**实测: daemon 重启不会崩** —— 运行期实际 import 的 14 个 `@deepseek-ai/*` 包全部从 ②③ 层解析（host 自带）；`dsh-client-ui-slots` 不是运行期 import（只在 `scripts/build-client.ts` 的 client external 列表，浏览器侧经 shell module table / `.dsh-module-fallback` 解析）。
+
+**为什么声明 58 个 peerDeps**: 全是 dev-time 需要 —— `tsc --noEmit` 类型检查、`tsdown` dts、以及 vitest 单测（在 dsh host 之外直接 import harness 包；dev workspace 靠 pnpm `autoInstallPeers` 装上）。部署副本里它们是 `peerDependencies` 且 `peerDependenciesMeta` 全部 `optional: true`，pnpm-lock.yaml 对嵌套路径 0 引用 —— pnpm 从不要求它们在场。真正的 `dependencies` 只有 `@deepseek-ai/schemastery`（非 harness API，是插件自用的 Schema 描述符库；描述符是结构化数据、宿主 cordis 当数据解释，故可以自带副本，与 cordis 必须 peer 的身份要求相反）+ cosmokit（schemastery 的传递依赖）。
+
+**已执行**: 删除 17 条悬空 symlink，保留 `schemastery`+`cosmokit`；清理后 14/14 运行期 import 解析复测通过。曾考虑的 A（重指 z_dsh-alpha，alpha.1 与 alpha.3 host 版本偏斜、「两份 cordis」身份风险）与 B（重指 upstream checkout）均已否决。另: ~~profile package.json 锁 `0.2.1-a` 而部署实为 `0.2.1-c`~~ 漂移已于 2026-09-02 收敛——锁/lockfile/部署位统一 `0.2.1-d`（pnpm add 精确版本线）。
+
+---

package/docs/specs/ast/spec.md

@@ -12,12 +12,16 @@ The ast device SHALL behave as a stateless function: every call carries its inpu
 - **WHEN** the agent invokes `ast_grep` twice with identical inputs
 - **THEN** both calls parse independently and return identical results, with no cached tree or warm process in between
 
-### Requirement: Lazy natives, zero startup cost
-Parser natives SHALL load lazily on first use (natives-loader); host start and agent session start SHALL NOT spawn anything or load grammar binaries.
+### Requirement: Lazy in-package engine, zero startup cost
+The ast device's WASM engine SHALL load lazily on first use; host start and agent session start SHALL NOT parse anything or load grammar binaries. The engine and its grammars SHALL ship inside the package (`lib/ast-assets/`) and SHALL require no network access, no npm resolution, and no `.vendor` provisioning at call time.
 
 #### Scenario: Cold session
 - **WHEN** a session ends without ever invoking the ast device
-- **THEN** no native library was loaded and no subprocess was created for it
+- **THEN** no WASM engine was instantiated and no grammar binary was loaded
+
+#### Scenario: Offline first use
+- **WHEN** the device is first invoked with no network access and no `.vendor` directory
+- **THEN** the search still completes from the in-package engine
 
 ### Requirement: dvc scheme surface only
 The ast capability SHALL expose exclusively through the `dvc://ast` write/read contract (bare `dvc://` roster lists it; `dvc://ast` read returns its doc; `dvc://ast` write dispatches). No dedicated tool name, no scheme branches in read/grep/glob, and no hook into read/write/edit flows SHALL be added.
@@ -32,3 +36,22 @@ The ast device SHALL provide structural matching/rewriting only. It makes no cla
 #### Scenario: No semantic answers
 - **WHEN** the agent asks the ast device for type information or project diagnostics
 - **THEN** no such capability exists on the device surface (the call is not offered)
+
+### Requirement: Diagnostic fields (deliberate divergence from the native predecessor)
+The ast devices SHALL surface failure modes that the native predecessor swallowed silently (0.2.6 contract addition). `ast_grep` results SHALL carry `patternErrors?: string[]` — present (non-empty) iff at least one supplied pattern failed to compile as a single-root AST node, one entry per failing pattern formatted `pattern <index> ("<pattern text>"): <underlying message>`; multi-root patterns land here and matches from the remaining patterns still return — and `pathNotFound?: boolean` — `true` only when the resolved target path does not exist on disk, absent otherwise. `ast_edit` results SHALL carry the same `patternErrors` semantics over `ops[].pat` (a failing op contributes no edits), `overlapping?: number` — the count of edits dropped by the overlap guard, present only when greater than zero — and the same `pathNotFound` semantics (true when at least one resolved target root does not exist on disk). Patterns that fail with a hard syntax compile error SHALL still throw through as `DVC_DEVICE_ERROR`. The devices perform no workspace boundary check — the boundary is the approval/policy layer — and `ast_edit` writes whatever paths it is given. All pre-existing fields keep their names and semantics.
+
+#### Scenario: Multi-root pattern is reported, not swallowed
+- **WHEN** `ast_grep` runs a multi-root pattern (e.g. `"alpha": $V`) that fails to compile as a single-root AST node
+- **THEN** the result carries `patternErrors` with one entry naming the pattern index, the pattern text, and the underlying message, and zero matches from that pattern — instead of an indistinguishable empty result
+
+#### Scenario: Missing path is distinguishable from zero matches
+- **WHEN** the resolved target path does not exist on disk
+- **THEN** the result carries `pathNotFound: true` with `filesSearched: 0`, so "nothing there" is no longer confused with "pattern matched nothing"
+
+#### Scenario: Overlap-guard drops are counted
+- **WHEN** `ast_edit` ops produce edits that overlap an already accepted edit
+- **THEN** the first-registered op wins, the shadowed edit is dropped, and the result reports the dropped-edit count in `overlapping` instead of dropping it silently
+
+#### Scenario: Hard syntax errors still throw
+- **WHEN** a pattern fails with a hard syntax compile error (e.g. `$$$`)
+- **THEN** the device throws and the caller receives the structured `DVC_DEVICE_ERROR`, exactly as before

package/docs/specs/ast-engine-deomp/spec.md

@@ -0,0 +1,170 @@
+# AST 去 OMP 化：内置 WASM 引擎（ast-engine-deomp）
+
+状态：**设计已定（user 裁决 2026-10-03：路线 A + 14 语法全部随包）；spike 已证；待落实现**
+｜ 规格路径：`docs/specs/ast-engine-deomp/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+---
+
+## 0. 动机（实证）
+
+`dvc://ast_grep` / `dvc://ast_edit` 是插件里**最后一个还需要 OMP 二进制的组件**。`zero-npm-runtime-deps`（0.2.5-a/b）已把 `@oh-my-pi/pi-natives-<platform>` 从 `dependencies` 摘掉，改为首次使用 lazy 自装——安装不再背它，但**第一次用 AST 仍要付**：
+
+| 项 | 实测 |
+|---|---|
+| 自装下载量 | `@oh-my-pi/pi-natives-linux-x64@18.0.6` = **70.8 MB**（registry `content-range: bytes 0-1/70791219`） |
+| 自装落盘量 | `dist.unpackedSize` **328 MB**（本机 18.2.11 实测 352 MB：`pi_natives.*-modern.node` 183 MB + `-baseline.node` 183 MB） |
+| 前提 | 必须联网 + npm registry 可达（否则 AST 设备整个不可用） |
+
+三点归属澄清（避免误伤）：
+
+1. **better-dsh 声明的 OMP 依赖 = 0 条**（`package.json` 实证）。
+2. prod profile 里那 352 MB `@oh-my-pi/*` **不是我们的**——来自 `super-dsh@0.1.9` → `@oh-my-pi/pi-coding-agent@18.2.11`。
+3. 这条自装路径是 0.2.5-a 的**有意的临时态**（`zero-npm-runtime-deps` 第 2 节表格最后一行），不是终态。
+
+**为什么可以自己实现**：`@oh-my-pi/pi-natives` 的 ast 面（`crates/pi-ast` 4,448 行 + `crates/pi-natives/src/ast.rs` 1,509 行）分两层——
+
+- **引擎**（唯一真 native）：ast-grep 结构匹配/改写 + ~70 个 tree-sitter 语法。**OMP 自己也是抄的**：`Cargo.toml` 里 `ast-grep-core 0.39` + `tree-sitter 0.25`，全 MIT。上游 ast-grep 官方就发布**纯 WASM 构建**。
+- **底盘**（全是胶水，TS 可写）：`.gitignore` 感知遍历（`ignore` crate）、glob 过滤（`globset`）、扩展名→语言推断、`maxFiles`/`maxReplacements`、dryRun、parseError 收集、meta 变量、分页、聚合统计。
+
+**投入上限的负证据**：`docs/60_exploration-and-research/07-omp-usage-telemetry/omp-lsp-ast-device-usage-telemetry.md` —— 3 周、288 个 session、21,666 次 toolCall 的真实 OMP 语料里，`ast_edit` / `lsp` **执行 0 次**（对照 `dsh://browser` 631 次）。所以本 change 的取舍原则是**语义零回归、体积大降、不为性能做过度工程**，而不是把 native 性能复刻出来。
+
+---
+
+## 1. 目标态（硬契约）
+
+   > **2026-10-04 修订（task-12 诊断字段）**：本条的「一字不动」是 **parity swap 期的冻结口径**——它约束的是 native→WASM 替换本身的行为面 A/B。验收后的 0.2.6 起为可诊断性**有意背离**：`ast_grep`/`ast_edit` 结果新增**可选**诊断字段 `patternErrors` / `pathNotFound` / `overlapping`（native 对这三种失败同样静默，见 2026-10-04 实测报告 A1/A3/A6）。这是 spec'd 的契约扩展（ast/dvc spec 新增 Requirement "Diagnostic fields (deliberate divergence from the native predecessor)"），不属于本规格意义上的回归；既有字段名与语义仍一字不动。
+1. **模型面契约一字不动**：`ast_grep` 的 `{patterns, path, offset, limit, includeMeta}`、`ast_edit` 的 `{ops:[{pat,out}], paths, dryRun}`，以及结果里 `changes` / `fileChanges` / `totalReplacements` / `filesTouched` / `filesSearched` / `applied` / `limitReached` / `parseErrors` / `matches` / `totalMatches` / `filesWithMatches` 的字段与语义全部保持。
+2. **零 OMP 痕迹（代码/产物面）**：源码、产物、`.vendor`、运行时网络请求，以及 tarball 里运行时实际装载的面（`lib/`、`package.json`、`scripts/`）都不再出现 `@oh-my-pi` / `pi_natives`。tarball 内 `docs/` 是刻意的发布载荷，对本次迁移的历史性提及属预期、不计入该判据（2026-10-04 终审定界：代码/产物面实测 0 命中；docs prose 提及数量随发布内容浮动，非回归信号）。
+3. **守住 zero-npm-runtime-deps 契约**：`dependencies` / `optionalDependencies` / `postinstall` 维持不存在；引擎与语法是**构建期输入**（devDependencies），产物以**包内资产**形式随 `files` 发布——即该规格认可的"构建期进产物"那条出路，不引入新的运行时自装。
+4. **离线自足**：断网、无 npm、无 `.vendor` 的环境下 `ast_grep`/`ast_edit` 必须真实可用。
+5. **fail-open 保持**：引擎整体或某一种语法加载失败，只降级该设备/该语言，插件加载与其余组件零影响；对外仍是 `DVC_DEVICE_ERROR`，措辞改为指向内置引擎。
+
+---
+
+## 2. 技术选型（spike 已证）
+
+| 角色 | 选定 | 版本 | 体积 | 许可 |
+|---|---|---|---|---|
+| 匹配/改写引擎 | `@ast-grep/wasm`（**官方** ast-grep 的 WASM 构建） | 0.45.3 | 1.73 MB | MIT |
+| WASM 运行时 | `web-tree-sitter` | 0.26.x | 0.20 MB | MIT |
+| 语法（14 个） | `@lumis-sh/wasm-<lang>` | 0.26.x | 12.5 MB | MIT |
+
+**合计 14.4 MB 随包**，对照现状 **70.8 MB 下载 / 328 MB 落盘 / 必须联网**。
+
+语法↔扩展名表（沿用现有 `AST_CODE_EXTENSIONS`，本 change 不缩语言面）：
+
+| 扩展名 | 语法 | 扩展名 | 语法 |
+|---|---|---|---|
+| `.py` `.pyi` | python | `.c` `.h` | c |
+| `.js` `.jsx` `.mjs` `.cjs` | javascript | `.cpp` `.hpp` | cpp |
+| `.ts` `.mts` `.cts` | typescript | `.html` | html |
+| `.tsx` | tsx | `.css` | css |
+| `.rs` | rust | `.json` | json |
+| `.go` | go | `.yaml` `.yml` | yaml |
+| `.sh` | bash | `.rb` | ruby |
+
+### 2.1 spike 结论（丢弃式探针：`.scratch/ast-wasm-spike/`）
+
+**A/B 一致性**：用 `natives-loader.ts` 同款方式 dlopen 本机真实 `pi_natives.linux-x64.node`，与 WASM 栈跑同一组用例——
+
+| 用例 | 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 | ✅ |
+
+**C / CSS 的"匹配不到"是 ast-grep 上游的 pattern 上下文歧义，不是 WASM 退化**——native 给同样的 0。行为面零回归。
+
+**三个已解的坑**（实现时不得重新踩）：
+
+1. **Node 不吃 ESM wasm import**：`@ast-grep/wasm` 的 `wasm.js` 直接 `import "*.wasm"`，Node 22 需 `--experimental-wasm-modules`。正解是**手动装配**：`WebAssembly.instantiate(bytes, { './wasm_bg.js': bg })` → `bg.__wbg_set_wasm(instance.exports)` → `instance.exports.__wbindgen_start()`（wasm-bindgen 标准手法；wasm 的 import module 名实测为 `./wasm_bg.js`，102 个 import）。
+2. **`expandoChar` 必须显式给 `'µ'`**：默认值 `$` 只在 JS/TS/bash/cpp 下碰巧可用；python / rust / go 会**静默 0 命中**（实测矩阵：`default:0 / "$":0 / "µ":1`）。`µ` 在全部被测语言下可用。
+3. **语法 wasm 必须是新式 `dylink.0`**：最流行的 `tree-sitter-wasms@0.1.13` 是 legacy `dylink`，与 `web-tree-sitter@0.26` 硬不兼容（`getDylinkMetadata` → `need dylink section`）。`@lumis-sh/wasm-*`（`dylink.0` 实测为 1）是正解。
+
+**性能实测（诚实记录，见 §6）**：14 个语言 `registerDynamicLanguage` 冷启 **121 ms**；单文件 17 KB typescript 解析 **26.6 ms**；遍历 `better-dsh/src` 188 文件 / 1.1 MB 源码（解析+匹配）**1,273 ms ≈ 0.9 MB/s**（单线程）。
+
+---
+
+## 3. 模块设计
+
+```
+src/devices/ast/
+  engine/
+    wasm.ts          ← 手动 wasm 装配 + Parser.init + 惰性单例；唯一的 wasm 入口
+    grammars.ts      ← 语言注册表：lang → 资产路径 + expandoChar 'µ'；懒注册、按需
+    language-map.ts  ← 扩展名 → 语言（**单一真相源**）
+    match.ts         ← pattern 编译 + 多根节点记 0 命中 + 命中 → AstFindMatch 映射（字节偏移）
+    edit.ts          ← astEdit 核心：rewrites / dryRun / changes[] / 字节偏移换算
+  walker.ts          ← .gitignore 感知遍历 + glob + 语言推断 + maxFiles 限额
+  ast-device.ts      ← 保持公开契约，改为调 engine + walker（薄适配层）
+  ast-reminder.ts    ← 语言集合改为对齐 engine 的语法表（不再"对 shipped 二进制实测"）
+  natives-loader.ts  ← **删除**
+```
+
+**资产流**：新增 `scripts/copy-ast-assets.mjs`，构建期把 3 件套 wasm 从 `node_modules` 拷进 `lib/ast-assets/`（`files: ["lib", …]` 已覆盖，无需改发布面）。构建链改为：
+
+```
+tsdown && npm run build-client && node scripts/copy-kernel-bridge.mjs && node scripts/copy-ast-assets.mjs
+```
+
+> ⚠ 必须在 `tsdown` **之后**：tsdown 会清空 `lib/`（同 `lib/client/` 的老坑）。
+
+**依赖面**：`@ast-grep/wasm` / `web-tree-sitter` / `@lumis-sh/wasm-*`（14 个）进 `devDependencies`。`src/vendor.ts` 本身保留（`dvc://browser` 的 puppeteer 仍用它），只删掉 pi-natives 的调用点与 `PI_NATIVES_VERSION`。
+
+**需要主动补齐的行为（照 OMP 语义实现，不是搬运）**：
+
+- **多根节点 pattern = 记 0 命中**：`function $N($$$A) { $$$B }`、`"alpha": $V` 这类片段在 wasm 的 `findAll` 会抛 `Multiple AST nodes are detected`。OMP 的 Rust 库虽有 `compile_wrapped_fallback`（`ops.rs`，仅 JSON 有模板），但实测 shipped native 在这条路径上并未用它：`astGrep` 返回 `matches=0` 且 `parseErrors=null`，`astEdit` 返回 `totalReplacements=0` 且结果里没有 `parseErrors` 键。因此 TS 侧对齐的是 **native 的实测行为**：捕获该异常 → 记 0 命中、不写 `parseErrors`、不抛错。
+- **`.gitignore` 感知遍历** + glob 过滤 + `maxFiles` / `maxReplacements`。
+- **UTF-8 字节偏移换算**：`range().index` 是**字符**偏移，OMP 的 `byteStart`/`byteEnd`/`deletedLength` 是**字节**偏移（实测含中文时 17 vs 25）。`changes[]` 生成时换算。
+- **parseError 收集**、分页（`offset`/`limit`）、`includeMeta` 的 meta 变量收集、聚合统计。
+
+**错误处理**：`wasm.ts` 加载失败 → 设备级 `DVC_DEVICE_ERROR`（措辞：内置引擎不可用，不再叫用户去装 npm 包）；单语言语法加载失败 → 该语言文件跳过并计入 `parseErrors`，其余语言照常。
+
+---
+
+## 4. 随本 change 一并改的文档
+
+行为契约里目前写着 `@oh-my-pi/pi-natives`，必须同步改（否则 spec/impl 脱节）：
+
+- `docs/20_specs/ast/spec.md` + `docs/specs/ast/spec.md`（两文件当前**内容相同**，同步改）：`Lazy natives, zero startup cost` 一条的措辞从"natives 懒加载"改为"内置 WASM 引擎按需加载"。
+- `docs/20_specs/dvc/spec.md` + `docs/specs/dvc/spec.md`：`ast devices` 一条删掉 "backed by the published `@oh-my-pi/pi-natives` binding"，改为内置 WASM 引擎。
+- `THIRD_PARTY_NOTICES.md`：增列 ast-grep / tree-sitter / `@lumis-sh/wasm-*`（三件套均 MIT）。
+- `src/NOTICE-OMP.md`：**保留**（已核：该文件覆盖 browser / lsp / ast 三类共 8 个文件，ast 不是唯一来源）。`browser-device.ts`、`lsp-device.ts`/`lsp-client.ts`/`lsp-jsonrpc.ts`/`lsp-language.ts`/`lsp-types.ts`/`lsp-server-registry.ts` 仍显式引用它。正文无需改（通用措辞，未点名 ast）；仅在实现时确认 ast 的 2 个文件删除后**没有**残留 `../NOTICE-OMP.md` 引用。
+
+---
+
+## 5. 验收（对齐"改动点同类"红线）
+
+1. **A/B 一致性矩阵常驻单测**：同一组 pattern 在 native 与 WASM 下逐条结果相同（§2.1 的表落成 `test/`）。
+2. **离线第一人称实测**：断网 + 删掉 `<pkg>/.vendor` 后，4999 rig 上真实 session 走通 `dvc://ast_grep` 与 `dvc://ast_edit`（含 dryRun 与真写盘）。
+3. **零 OMP 实证（代码/产物面）**：`npm pack` 出的 tarball 在 `lib/`、`package.json`、`scripts/` 上 `grep -rc "pi_natives\|@oh-my-pi"` = 0（`docs/` 发布载荷的历史性提及不计入）；运行期无 registry 请求。
+4. **工具面口径同类**：`tsc --noEmit` 0 错；全量单测绿；boot graph 含 better-dsh；`dvc://` roster 仍列出两个 ast 设备。
+5. 实测报告落 `docs/50_test-reports/`；**发布仍需 user 明确放行**（单次授权，见根 AGENTS.md 〇节）。
+
+---
+
+## 6. 已知风险与代价
+
+| 风险 | 说明 | 处置 |
+|---|---|---|
+| **吞吐下降** | WASM 单线程 ≈ 0.9 MB/s；native 是 Rust 并行遍历。大仓全量 codemod 会明显变慢 | 明示接受（该设备 3 周 0 调用）。若日后成为瓶颈，再评估 worker 分片 |
+| **语法 ABI 锁步** | `dylink.0` 要求 `web-tree-sitter` 与语法包**主版本同步**升级 | 两者一起 pin；升级走显式、带 A/B 的变更 |
+| **语言面依赖第三方语法包** | `@lumis-sh/wasm-*` 是社区包（MIT，活跃） | 路径与版本在 `grammars.ts` 单点声明；若某语言其停更，可自行 `tree-sitter build --wasm`（本机有 docker）替换单个资产 |
+| **`expandoChar` 静默失效** | 漏给 `µ` 会导致某语言**静默 0 命中**（不报错） | 每个语言注册后跑一次自检 pattern；单测锁定全语言矩阵 |
+| **per-language pattern 歧义** | C 的 `foo($A)`、CSS 的 `color: $V` 匹配不到 | **与上游 native 行为一致**（已 A/B 证），非本 change 引入，不修 |
+| 字节偏移换算错位 | 含多字节字符时 `changes[]` 坐标会偏 | 单测覆盖 CJK 用例 |
+
+---
+
+## 7. 进展日志
+
+- **2026-10-03 设计轮**：user 裁决路线 A（官方 `@ast-grep/wasm` 引擎 + TS 底盘），14 个语法全部随包。丢弃式 spike 落在 `.scratch/ast-wasm-spike/`（`probe.mjs` / `iso.mjs` / `expando.mjs` / `comboA|B|C.mjs` / `probe3.mjs` / `probe4.mjs` / `ab-native.mjs`）：
+  - 证伪了 `tree-sitter-wasms@0.1.13`（legacy `dylink`）；
+  - 证真了 `@lumis-sh/wasm-*` 0.26.x（`dylink.0`）覆盖全部 14 语言；
+  - 定位并解决 `expandoChar` 与手动 wasm 装配两个坑；
+  - 与真 native 完成 A/B，行为零回归；
+  - 量得 14.4 MB 资产、0.9 MB/s 吞吐、字节偏移差异。

package/docs/specs/authentication-only-web-admission/spec.md

@@ -0,0 +1,51 @@
+# Authentication-only Web admission
+
+## Goal
+
+An operator can reach their authenticated DSH deployment through any domain or
+LAN address without maintaining separate server and browser address allowlists.
+The server keeps its current bind address; the existing rig's LAN relay supplies
+LAN reachability. This feature does not change listening interfaces.
+
+## Configuration
+
+Opt in through the existing `dashr-web-trust` row:
+
+```yaml
+- id: dashr-web-trust
+  name: better-dsh/web-trust
+  config:
+    trustAllHosts: true
+```
+
+The default is `false`, retaining existing declared-authority behavior. When
+enabled, `--trusted-host`, `DSH_TRUSTED_HOSTS` and `trustedPageAuthorities` are
+not needed for admission or page management privileges.
+
+## Contract
+
+- Keep the original Connection instance, transport, RPC registrations and token
+  exchange. No upstream source changes, replacement service or private-field
+  access are required.
+- Replace only its `requestRejection` method while this row is active. Delegate
+  cookie verification to public `authorizeIndex`, using the real request headers
+  and a fixed query-free index URL. Discard the index responder's output; the
+  transport remains responsible for the actual HTTP response.
+- Any address, Origin and Fetch-Metadata marker can pass after authentication.
+  Missing, invalid, expired or wrong-authority cookies still return 401. Cookie
+  lifetime and signing remain the native authenticator's responsibility.
+- This API admission delegate never exchanges a URL token: normal index login
+  still performs that exchange. Existing password-login behavior is unchanged.
+- Inject `ownsHost: true` before browser application initialization, regardless
+  of page hostname, without overwriting an existing transport. Management UI
+  consumers continue to use the original Connection's common capability flag.
+- Unloading or disabling this row restores the original admission method;
+  reload the page to update its initialization-time capability flag.
+
+## Acceptance
+
+Use a packaged plugin installed through `dsh plugin add` in the long-lived 4999
+rig, with no trusted-host CLI argument or environment variable. Verify loopback,
+LAN and the actual HTTPS deployment domain; an additional unlisted Host must
+authenticate successfully without bypassing cookie verification. Check settings
+persistence, provider settings and plugin management in the real browser.

package/docs/specs/docs-packaging-trim/spec.md

@@ -0,0 +1,110 @@
+# 发布包瘦身：摘掉与 DSH/本插件无关的 docs（docs-packaging-trim）
+
+状态：**设计已定（user 裁决 2026-10-03：档位 F）；待落实现**
+｜ 规格路径：`docs/specs/docs-packaging-trim/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+---
+
+## 0. 动机（审计实证）
+
+`better-dsh` 的 tarball 是 **20.2 MB**，而 `lib/`（真正的代码）只有 **2.5 MB**。差额几乎全在**随包发布的 docs 副本**上：`tar czf docs` = **20.3 MB**（含 tar 开销），即 tarball 基本等于 docs。
+
+`scripts/copy-docs.mjs` 把仓库 `docs/` 拷进 `better-dsh/docs/`（`files: ["docs"]` 发布），已有 EXCLUDE 规则只挡了 `60_exploration-and-research/`、`superd/`、`dsh-sys-prompt_*.md`、`*_artifacts/`。逐目录盘点后，剩下的发布面里混着**与 DSH 和本插件都无关的东西**。
+
+### 0.1 关键澄清：`80_upstream-docs-and-skills/` 不是"纯文档"
+
+user 提问："`api-skills.json` 不是给人读的，那它存在的唯一意义就是作为技能放在 skills 目录让 harness 读取，对吧？既然是纯文档就不需要它？"
+
+**比这更弱**——该目录自己的 `src-README.md` 写明：
+
+> This stage only does the **fetching**; distillation into a skill is a separate follow-up
+
+即 `hermes-dev-skill/` 是"抓取 → 蒸馏成技能"两阶段流水线的**第一阶段**，而**第二阶段从未执行**：整个目录没有 `SKILL.md`、没有 `skill/`。所以这 77 MB 是**没有被任何东西消费的流水线输入**——既不是技能，也不是文档。`api-skills.json` 是 `https://hermes-agent.nousresearch.com/docs/api/skills.json`（59 MB），**Hermes 自己那套技能的机器可读目录**，`grep` 全仓无引用。
+
+### 0.2 归属：这是别人的框架说明书
+
+`hermes-dev-skill` 是 **NousResearch/hermes-agent** 官方文档的完整镜像（`src-README.md` 记着 sparse clone commit `4e9d3c71…` 与抓取日期 2026-09-16），它自己声明的用途是：
+
+> so agents that develop / integrate with **Hermes Agent** can work without hitting the live site
+
+——一个**别的 agent 框架**的说明书。Hermes 有自己的文档站与仓库（该 README 自己就引了）。入库溯源：commit `d13c4a3`，提交信息为 *"rig(test123): remove profiles/node_modules symlink farm"*——一个与文档无关的 rig 提交把它捎带进来。
+
+### 0.3 全树盘点（`copy-docs.mjs` 实际发布范围）
+
+| 路径 | 磁盘 | 是什么 | 判定 |
+|---|---|---|---|
+| `00_adr/` `10_plans/` `20_specs/` `specs/` | 980 K | 本仓 ADR / 计划 / 规格 | ✅ 留 |
+| `50_test-reports/` | 3.5 M | 本仓实测报告（已做 token 脱敏） | ✅ 留 |
+| `superpowers/` | 40 K | 本仓两份 spec/plan | ✅ 留 |
+| `80_.../hermes-dev-skill/` | **77 M** | 别家框架文档镜像；抓取阶段，无 `SKILL.md`，零引用 | ❌ **摘** |
+| `80_.../dsh-dev-skill/pi-and-omp/` | **2.8 M** | OMP / Pi 第三方资料；**技能正文零引用**（`grep -rn "pi-and-omp" skill/` 为空） | ❌ **摘** |
+| `80_.../dsh-dev-skill/src-scripts/` | **3.4 M** | 抓取工具 + `docs-tree.json`（3.5 M 构建清单） | ❌ **摘** |
+| `80_.../dsh-dev-skill/skill/` | 304 K | DSH 开发知识库蒸馏稿（`SKILL.md` + 22 章）——**静态文档**，与技能运行时无关 | ✅ 留（DSH 相关） |
+| `80_.../dsh-dev-skill/src/` | 4.0 M | DSH 官方文档快照——**被 `SKILL.md` 与 4 个章节明确引用** | ✅ 留 |
+| `dsh-docs/`（包根） | 4.1 M | DSH 官方文档（较新），`dsh://docs` 主面 | ✅ 留 |
+| `60_exploration-and-research/` `superd/` | — | 已在既有 EXCLUDE 内 | — |
+
+> **不要整段摘 `80_upstream-docs-and-skills/`**：`dsh-dev-skill/` 的内容是**蒸馏过的官方 DSH 文档**，按本 change 的留置规则属「与 DSH 相关」的静态文档。**与技能运行时无关**：Harness 技能发现只扫四个根（`<project>/.dsh/skills`、`<project>/.agents/skills`、`~/.dsh/skills`、`~/.agents/skills`，见 `packages/skill/skill-filesystem/src`），插件 docs 树从来不在其中。`dsh://docs` 是纯静态资源——装了插件任何人都能读，里面的目录叫不叫 skill，与 Harness 加载什么技能毫无关系。早期版本的本节曾称它是「运行时真正加载的技能、整段摘会打断一个技能」，**那是错误推断**（把「文件存在」当成了「被运行时加载」），已撤回。
+
+> **重复发布（本 change 不处理）**：`dsh-docs/`（249 文件）与 `…/dsh-dev-skill/src/docs/`（241 文件）是同一套官方 DSH 文档的**两个修订版**（后者较旧）。摘后者需同时改写 `SKILL.md` 与 4 个章节里 `../src/docs/` 的指向——那是**文档内部交叉引用**问题（静态库里出现悬空指针），不是技能问题，另开 change 评估。
+
+---
+
+## 1. 目标态（硬契约）
+
+1. **发布副本里不再出现**：`hermes-dev-skill/`、`dsh-dev-skill/pi-and-omp/`、`dsh-dev-skill/src-scripts/`。
+2. **repo 的 `docs/` 一字不动**：`copy-docs.mjs` 只改写发布副本 `better-dsh/docs/`。本仓测试报告、技能源、任何交叉引用与本地技能（如引用 `site-pages-map.txt` 的 `.agents/skills/cordis-dsh-dev`）全不受影响。
+3. **承重面完好**：`dsh-dev-skill/skill/`（含 `SKILL.md`）与其引用的 `src/docs/`、`src/site-pages-map.txt` 必须**全部保留**。
+4. **无新的悬空引用**：发布副本内不得有指向被摘路径的活引用（见 §3 的已知例外）。
+5. **不改语言/行为面**：本 change 纯打包面，不触碰任何源码或技能正文。
+
+---
+
+## 2. 改动
+
+`scripts/copy-docs.mjs` 的 `EXCLUDE` 数组增加 3 条目录规则（沿用既有的"按源路径正则匹配"形式）：
+
+```js
+/(^|\/)hermes-dev-skill($|\/)/,
+/(^|\/)dsh-dev-skill\/pi-and-omp($|\/)/,
+/(^|\/)dsh-dev-skill\/src-scripts($|\/)/,
+```
+
+不删除任何仓库文件，只改变**进包集合**。
+
+---
+
+## 3. 已知例外（明示接受，不做过度工程）
+
+`docs/80_upstream-docs-and-skills/dsh-dev-skill/src-README.md` 在正文里提到 `src-scripts/`（抓取清单的结构说明）。摘掉该目录后，**发布副本**里这份 fetch manifest 会描述一个不在包内的目录。
+
+- 影响面：仅"文档自述"的措辞不一致，无功能影响；该 manifest 的价值在于说明 `src/` 是什么。
+- 处置：**接受**。不改写正文（改写会让发布副本与 repo 副本分叉，违背 §1.2）。若日后要更干净，用发布期的占位替换，另开 change。
+
+---
+
+## 4. 验收
+
+1. **量化**：`npm pack` 出的 tarball 从 **20.2 MB → ≈ 3.7 MB**（docs 贡献 20.3 → 3.7 MB）；安装后磁盘 sizeof(`docs/`) 从 **98 MB → ≈ 15 MB**。
+2. **承重存活**：解包 tarball，`docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 与 `src/docs/`、`src/site-pages-map.txt` 均在位；被摘三目录不存在。
+3. **静态文档可读**：rig 上 `read dsh://docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 能取回正文——它只是众多静态文档之一。~~会话技能目录仍列出 `dsh-dev-skill`、`skill://dsh-dev-skill` 可读~~ 该判据建立在错误模型上，撤回：技能是否被 Harness 加载取决于 user 本地 / per-workspace 安装，与本插件无关。
+4. **零新增悬空引用**：在解包后的 `docs/` 内 `grep -rn "hermes-dev-skill\|pi-and-omp\|src-scripts"` 只剩 §3 那一处已知例外。
+5. **`dsh://docs` 可读性不变**：`read dsh://docs` 列表与抽查若干路径仍正常。
+6. 实测报告落 `docs/50_test-reports/`；发布仍需 user 明确放行。
+
+---
+
+## 5. 风险
+
+| 风险 | 说明 | 处置 |
+|---|---|---|
+| 误摘承重目录 | `80_upstream-docs-and-skills/` 名字像"纯上游资料"，实则含承重技能 | §1.3 硬契约 + 验收第 2/3 条把关 |
+| 规则误伤同名目录 | EXCLUDE 是正则，若将来别处出现同名目录会被一并摘 | 规则带路径前缀锚定（`dsh-dev-skill/…`），不做裸名匹配 |
+| 与 ast-engine-deomp 同批发布 | 两者都改打包面，回归时互相遮蔽 | 验收分开做：先各自量化，再合并实测一次 |
+
+---
+
+## 6. 进展日志
+
+- **2026-10-03 设计轮**：user 发现 Hermes 材料混入并质疑归属，要求"只要跟 DSH 不相关、跟我们这个插件不相关的，全部摘掉"。完成全树审计（见 §0.3），确认：`hermes-dev-skill` 是别家框架的**未消费抓取产物**（无 `SKILL.md`）；`pi-and-omp` 被技能正文零引用；`dsh-dev-skill/skill` + `src/` 承重不可摘。user 裁决**档位 F**（只摘未引用的外来物与构建机械）。实测数字：tarball 20.3 → **3.7 MB**；磁盘 98 → **15 MB**。
+- 附带澄清（user 提问驱动）：`api-skills.json` 既非技能亦非文档，是未完成流水线的输入；"包内 gzip"被否决——npm tarball 本就是 gzip，包内再压只影响安装后磁盘，且 `dsh://docs` 读纯文本，需为**零引用**文件新增解压读路径，方向错误。

package/docs/specs/dvc/spec.md

@@ -35,12 +35,31 @@ The system SHALL implement the device write contract: `write dvc://<device>` wit
 - **THEN** the device executes and its result returns to the caller
 
 ### Requirement: ast devices
-The system SHALL provide `ast_edit` (staged structured codemod) and `ast_grep` (structured search) devices, vendored from the omp harness (MIT), backed by the published `@oh-my-pi/pi-natives` binding.
+The system SHALL provide `ast_edit` (staged structured codemod) and `ast_grep` (structured search) devices, backed by the official ast-grep engine compiled to WebAssembly plus an in-package tree-sitter grammar set (`lib/ast-assets/`), with no OMP and no native binary.
 
 #### Scenario: ast_grep search over a workspace file
 - **WHEN** the model writes `dvc://ast_grep` with a pattern and path
 - **THEN** structured matches return from the AST search
 
+### Requirement: Diagnostic fields (deliberate divergence from the native predecessor)
+The ast devices SHALL surface failure modes that the native predecessor swallowed silently (0.2.6 contract addition). `ast_grep` results SHALL carry `patternErrors?: string[]` — present (non-empty) iff at least one supplied pattern failed to compile as a single-root AST node, one entry per failing pattern formatted `pattern <index> ("<pattern text>"): <underlying message>`; multi-root patterns land here and matches from the remaining patterns still return — and `pathNotFound?: boolean` — `true` only when the resolved target path does not exist on disk, absent otherwise. `ast_edit` results SHALL carry the same `patternErrors` semantics over `ops[].pat` (a failing op contributes no edits), `overlapping?: number` — the count of edits dropped by the overlap guard, present only when greater than zero — and the same `pathNotFound` semantics (true when at least one resolved target root does not exist on disk). Patterns that fail with a hard syntax compile error SHALL still throw through as `DVC_DEVICE_ERROR`. The devices perform no workspace boundary check — the boundary is the approval/policy layer — and `ast_edit` writes whatever paths it is given. All pre-existing fields keep their names and semantics.
+
+#### Scenario: Multi-root pattern is reported, not swallowed
+- **WHEN** `ast_grep` runs a multi-root pattern (e.g. `"alpha": $V`) that fails to compile as a single-root AST node
+- **THEN** the result carries `patternErrors` with one entry naming the pattern index, the pattern text, and the underlying message, and zero matches from that pattern — instead of an indistinguishable empty result
+
+#### Scenario: Missing path is distinguishable from zero matches
+- **WHEN** the resolved target path does not exist on disk
+- **THEN** the result carries `pathNotFound: true` with `filesSearched: 0`, so "nothing there" is no longer confused with "pattern matched nothing"
+
+#### Scenario: Overlap-guard drops are counted
+- **WHEN** `ast_edit` ops produce edits that overlap an already accepted edit
+- **THEN** the first-registered op wins, the shadowed edit is dropped, and the result reports the dropped-edit count in `overlapping` instead of dropping it silently
+
+#### Scenario: Hard syntax errors still throw
+- **WHEN** a pattern fails with a hard syntax compile error (e.g. `$$$`)
+- **THEN** the device throws and the caller receives the structured `DVC_DEVICE_ERROR`, exactly as before
+
 ### Requirement: browser device
 The system SHALL provide a `browser` device (open/close/run over real browser tabs) vendored from the omp harness, using puppeteer-core against the system Chrome; when no browser can launch, the device returns a structured error.