better-dsh 0.2.5 → 0.3.0

package/README.md

@@ -1,3 +1,5 @@
+> Part of [Super D](../README.md). This is the independently installable `better-dsh` package. Super Dash embeds the same local build and registers it as a separate native Plugin Manager row, with its own enable/disable switch; both versions advance together toward 0.3.0. Active source is this directory, with shared specifications and references under root `docs/`.
+
 # Better Dsh — Dashr
 
 DASHR is a persistent-kernel REPL for the DeepSeek Harness (dsh): a
@@ -45,6 +47,30 @@ dsh runtime package dependencies**: only `@deepseek-ai/cordis` (peer),
   dependency imports external (`dts: { resolve: false }`): bundled copies
   would create duplicate type identities in a consumer's program.
 
+## Native Web defaults
+
+The bundle owns native DSH Web policies as independently toggleable components.
+`dashr-web-trust` accepts authenticated serving Host/Origin values while retaining
+native cookie authentication. `dashr-webserver` inherits the native server and
+waits for welcome confirmation before listening; its default address is
+`0.0.0.0`, with the native port and CLI override behavior preserved.
+Automatic credential onboarding is disabled; users can still configure models.
+
+`dashr-welcome-notice` reads the current `WELCOME_NOTICE_VERSION` from the Models
+client belonging to the actual DSH installation and acknowledges it through the
+original General settings namespace before the first HTTP read. No version is
+pinned in the plugin. Ordinary version bumps adapt at startup; changed private
+symbols or build layouts fail explicitly. Restore native welcome behavior with:
+
+```yaml
+- id: dashr-welcome-notice
+  disabled: true
+```
+
+The sibling Super Dash pack builds this repository locally and embeds its actual
+tarball. Better Dash remains independently installable. `../dev-webmcp` is an
+unshipped development-only bundle owned by this repository.
+
 ## Install
 
 ```sh
@@ -204,9 +230,7 @@ the host runtime's business, not the REPL's).
 
 ## Install
 
-The canonical path is the repo-root one-click installer (`install.sh`): it
-installs the plugin from the npm registry and notes the restart. The
-equivalent manual steps, for reference:
+Install this package independently with the native plugin command. Use Super Dash instead when you also want the Foreign Agent Hub:
 
 ```sh
 # 1. plugin — the pnpm registry-metadata cache can lag a fresh npm publish

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+`better-dsh` ships source copies of three MIT-licensed packages under
+[`third_party/`](third_party/). They are **vendored, not dependencies**: the
+plugin must not depend on how a host installation scope resolves them, so the
+sources live here, are imported by relative path, and are inlined into the
+published `lib/` bundle. Provenance, version pins, and the update procedure are
+documented in [`third_party/README.md`](third_party/README.md).
+
+| Package | Version | License | Upstream |
+|---|---|---|---|
+| `@deepseek-ai/schemastery` | 3.18.4 | MIT | <https://github.com/deepseek-ai/deepseek-harness> |
+| `@deepseek-ai/cosmokit` | 1.8.5 | MIT | <https://github.com/deepseek-ai/deepseek-harness> |
+| `@standard-schema/spec` | 1.1.0 | MIT | <https://github.com/standard-schema/standard-schema> |
+| `@ast-grep/wasm` | 0.45.3 | MIT | <https://github.com/ast-grep/ast-grep> |
+| `web-tree-sitter` | 0.26.12 | MIT | <https://github.com/tree-sitter/tree-sitter> |
+| `@lumis-sh/wasm-*` (14 grammars) | 0.26.x | MIT | <https://www.npmjs.com/org/lumis-sh> |
+
+`@standard-schema/spec` is a type-only import of `schemastery`'s declarations;
+`cosmokit` is `schemastery`'s sole runtime dependency and is resolved from
+`third_party/schemastery/node_modules/`.
+
+## MIT License
+
+Applies to all three packages above, each with its own copyright holder:
+
+```
+MIT License
+
+Copyright (c) 2021-present Shigma                 (schemastery, cosmokit)
+Copyright (c) 2024 Colin McDonnell                (@standard-schema/spec)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Each copy also retains its upstream `LICENSE` file in place.

package/cordis.patch.yml

@@ -17,6 +17,10 @@
 # `python` is only a hint: the runtime OWNS the kernel environment. An
 # explicit interpreter (DASHR_KERNEL_PYTHON) is verified; the bare
 - insert:
+    # No-op standalone; keeps a containing pack's local companion delivery current.
+    - id: dashr-bundle-delivery
+      name: 'better-dsh/bundle-delivery'
+
     - id: dashr-repl
       name: 'better-dsh'
       config:
@@ -42,6 +46,8 @@
     # config — they survive every overlay layer; an explicit value still wins).
     - id: dashr-web-trust
       name: 'better-dsh/web-trust'
+      config:
+        trustAllHosts: true
 
     # Mobile responsiveness leg of the boot script (gestures payload +
     # zoomGuard section). All knobs default ON; `enabled: false` opts out.
@@ -66,6 +72,11 @@
     - id: dashr-web-password
       name: 'better-dsh/web-password'
 
+    # Automatically acknowledge the installed Host's current welcome version.
+    # Single-row opt-out: dashr-welcome-notice: disabled.
+    - id: dashr-welcome-notice
+      name: 'better-dsh/welcome-notice'
+
 # Native compaction at the host plane: the base bundle ships the engine, the
 # `/compact` command, and the tool-result pruner as host rows; dsh-web-app
 # disables them to move compaction behind per-session presets. DASHR is
@@ -93,3 +104,36 @@
   inject: [webRuntime]
   config:
     trustedHosts: !!js (process.env.DSH_TRUSTED_HOSTS ?? '').split(/\s+/).filter(Boolean).concat(ctx.webRuntime.trustedHosts)
+
+# Replacement uses the public patch mechanism: disable the native provider,
+# then insert a distinct row providing the same native webServer service.
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  disabled: true
+- insert:
+    - id: dashr-webserver
+      name: 'better-dsh/webserver'
+      inject: [webStartup]
+      config:
+        host: !!js ctx.webStartup.host ?? '0.0.0.0'
+        port: !!js ctx.webStartup.port ?? 3080
+        compression: gzip
+        compressionLevel: 1
+        compressionThresholdBytes: 1024
+
+- id: ui-settings-models
+  name: '@deepseek-ai/dsh-client-ui-settings-models'
+  config:
+    credentialOnboarding: false
+
+# Native watcher/queue with scoped transaction context across listener replacement.
+# Distinct row preserves whole-bundle disablement in the native manager.
+- id: hmr
+  name: '@deepseek-ai/dsh-hmr'
+  disabled: true
+- insert:
+    - id: dashr-hmr
+      name: 'better-dsh/hmr'
+      disabled: !!js "!ctx.get('profileContext')"
+      config:
+        root: []

package/docs/20_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/20_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.
 

package/docs/50_test-reports/2026-10-02-better-dsh-schemastery/344/276/235/350/265/226/345/243/260/346/230/216/344/277/256/345/244/215/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,62 @@
+# better-dsh schemastery 依赖声明修复实测报告（2026-10-02）
+
+- **对象**：better-dsh **0.2.5 → 0.2.5-a** —— `@deepseek-ai/schemastery` 从 `dependencies` 改为 optional **peer**（commit `c4018aa`）
+- **症状（用户报告）**：prod 实例每次启动都出现
+  `dashr-failover (better-dsh/failover): failed to import` +
+  `dashr-compaction-tuning (better-dsh/compaction-tuning): failed to import`
+  （本机 PC 3080 journal 自 **Sep 29** 起、共 **10 次 boot** 均复现，另附 `corti-memory`；dev3 prod 3080 同样两行）
+- **载体**：本机 PC 3080 / dev3 prod 3080（dsh **0.2.0-rc.2**）+ 干净 profile 单变量复现 + dev3 全新重装验收
+
+## 一、根因
+
+**链条**：better-dsh 把 `@deepseek-ai/schemastery` 写在自己的 **`dependencies`** → pnpm 在 `profiles/<p>/node_modules/@deepseek-ai/schemastery` **实体化出第二份** → Node 就近 walk-up 先命中这一份，**永远走不到 harness 的 installation-scope 拦截** → 该份被 profile 的 lockfile 冻在 **3.18.2**，而宿主已随 dsh 升到 **3.18.4**。
+
+**为什么致命**：`.volatile()`（dsh 0.1.7+ settings 模型所需）**3.18.3 才引入**。better-dsh 的 `failover` / `compaction` 在**模块作用域**用 `.volatile()` 建 Config schema，导入即抛 → loader 记为 `failed to import`（fiber 根本没建）。
+
+| 构建产物 | `volatile` 命中 | 实测 |
+|---|---|---|
+| `lib/failover/index.js` | 4 | **FAILS** |
+| `lib/compaction/index.js` | 4 | **FAILS** |
+| `lib/url-schemes/index.js` | 0 | OK |
+| `lib/index.js`（main） | 0 | OK |
+
+**harness 本来就已经供给它**（app-boot `collectInstallationScopePackages`）：从已安装的 `@deepseek-ai/dsh` manifest 出发，BFS 走 **`dependencies ∪ peerDependencies` 传递闭包**，闭包内每个名字对**所有 profile** 生效。而 **dsh 自己 declare 了 `@deepseek-ai/schemastery: ~3.18.4`**，宿主树内即有（`…/dsh/node_modules/@deepseek-ai/schemastery`，**3.18.4**，带 `.volatile()`）。所以指针本应指向宿主，被我们自己搬到了 profile 层。
+
+## 二、修复
+
+`c4018aa`：把 `@deepseek-ai/schemastery` 从 `dependencies` **删除**，只保留 optional peer 声明（与 `@deepseek-ai/dsh-*` 等其他 harness 包同款）。这样 pnpm 不再在 profile 里物化副本，解析回落到 installation scope（宿主的 3.18.4）。
+
+（前一轮 `f11dda8` 的 floor bump `^3.18.1 → ^3.18.3` 保留为 0.2.5 存量用户的桥；peer 修正落地后不再有实际作用。**已按 §〇.5 撤回自包含/vendoring 方案** —— DSH 已 bundle 过一次，ride-on-DSH 的插件不应再抄一份。）
+
+## 三、验证
+
+**1) 单变量复现/对照（决定性）**：一个 boot 完全干净的 profile，把 schemastery 从 3.18.4 换成 **3.18.2** → 重启后**恰好这两行**失败；换回即干净。单一变量、单一结果。
+
+**2) 新 profile 装修正版**：profile 内 **`@deepseek-ai/` 整个目录都不存在**；boot **零 `did not activate`**。
+
+**3) dev3 全新重装验收（第一人称，按 user 指令做的实验）**：
+- 保留全部 user 数据（`sessions`/`storages`/`credentials`/`superd`/`task-board`），`cordis.patch.yml`（111 行用户层）原样恢复；
+- 清空 `~/.dsh/profiles`（2.4G）与全局 DSH → DSH **从 registry** 重装 `0.2.0-rc.2`；
+- profile 重建：DSH/SuperD **从 registry**，**better-dsh 用本次修正 tarball**；
+- 结果对照：
+
+  | | 修复前 | 修复后 |
+  |---|---|---|
+  | `dashr-failover`/`dashr-compaction-tuning` `failed to import` | **2** | **0** |
+  | `dsh: warning: N entries did not activate` | 有 | **整行消失** |
+  | profile 层 `node_modules/@deepseek-ai/` | schemastery 3.18.2 + cosmokit | **不存在** |
+  | 正向验证 `curl :3080/` | — | **200 + `Enter the session password`**（web-password 行活着，独占 exact `/`） |
+
+- 剩余 warning 属 **super-dsh**（`superd-hermes`/`superd-codex` 各 1 条 `session-controller: pending (waiting for service: fileUploads)`）——**pending 非 failed，且修复前的 boot 同样存在**，与本修复无关。
+
+**4) 单元/类型**：`tsc --noEmit` **0 错**；`vitest run` **649 passed / 1 skipped**（57 文件）。
+
+## 四、附：一个独立的运维坑（非本 bug）
+
+本机曾出现 `dsh plugin add/remove` 报 `node_modules was installed with a different major version of pnpm`。根因 = **两个 pnpm 版本打架**：`/home/u1/.local/bin/pnpm` = 11.7.0（profile 的 node_modules 由它建，store **v11**）、`/usr/local/bin/pnpm` = **10.29.2**；某些调用上下文 PATH 不含 `~/.local/bin` → harness 调到 pnpm 10 去动 v11 建的树 → 硬错。
+
+**已修**：`sudo npm i -g pnpm@11.7.0` → 两个路径均 **11.7.0**；模拟"`~/.local/bin` 掉出 PATH"的最坏情况仍得 11.7.0。dev3 全程用其本地 pnpm 10.33.2 干净完成安装，证明**该 bug 与 pnpm 无关**。
+
+## 五、判定
+
+**通过**。根因单一且已用单变量复现 + 全新重装双重证明；修复面只有一个声明位的移动；dev3 第一人称验收 0 失败。发布 `0.2.5-a`。

package/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 命中**。