better-dsh 0.2.3-e → 0.2.3-g

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

@@ -34,7 +34,7 @@ AGENTS.md §二 harness 本地 patch 已记档（换 tag 需重放）。
 | shell 内 react-dom 痕迹 | **`version:"18.3.1", rendererPackageName:"react-dom"` banner 在 shell** | **无**（唯一 `react-dom` 字串 = 平台模块种子表键 `{react:Y3, "react-dom":Y3, ...}`——同一个 preact 实例登记两个平台词，设计终态） |
 | pageerror | slot 重复注册 ×1 | slot 重复注册 ×1 |
 
-**pageerror 定责（A/B）**：`settings.general.item` slot id `compaction-tuning` 重复注册在 **stock 上同样存在**（factory id `Ba` vs `f5` 仅 minified 差异）→ **存量问题**，属 `.dsh-test` profile 的 compaction-tuning 本地插件，与渲染引擎无关，挂账另修。`better-dsh/client.js` 内的 `react-dom` 匹配为 pnpm 依赖路径字符串（`@tanstack+react-virtual@…_react-dom@18.3.1…`），stock/preact 两面同在，非本体。
+**pageerror 定责（A/B + 发布前验尸修正）**：`settings.general.item` slot id `compaction-tuning` 重复注册在 **stock 上同样存在**（factory id `Ba` vs `f5` 仅 minified 差异）→ 与渲染引擎无关。**根因（publish 前验尸确认）**：canonical 树里有一份**未提交的半成品 compaction-tuning 吸收工作**（`src/compaction/` + `installCompactionTuning` 接线，随 rsync 进入 4999 副本），与 `.dsh-test` profile 仍挂着的 local-plugin 版 compaction-tuning **同 id 注册两次**——两因叠加。该半成品已 `git stash`（带说明消息）移出 0.2.3-e 发布内容，续作时须先摘除 profile 的 local-plugin 行再合入。`better-dsh/client.js` 内的 `react-dom` 匹配为 pnpm 依赖路径字符串（`@tanstack+react-virtual@…_react-dom@18.3.1…`），stock/preact 两面同在，非本体。
 
 **user 未亲自引爆项声明**：深交互面（聊天流式渲染、shiki 高亮、markdown 管线）未逐项人工过——零 console.error 为强信号非穷尽证明（PoC 同款边界声明）。
 

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

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

package/docs/specs/agent/spec.md

@@ -0,0 +1,54 @@
+# agent Specification
+
+## Purpose
+
+Let the model address the agent roster, output artifacts, and full transcripts via `agent://` URLs — the single home for what upstream split across roster tools and a separate `history://` scheme.
+
+## Requirements
+
+### Requirement: Agent roster addressing
+The system SHALL let bare `agent://` return the roster of every live session, oldest first, as a five-column table: `id`, `status`, `kind`, `parent`, `last activity`. `status` comes from the live agent registry (`idle`/`running`; `-` when the session has no live agent); `kind` is the session header's `origin` (default `main`); `parent` is the delegating parent session id (`-` at top level); `last activity` is the last session event's time in ISO 8601 (`-` when the session has no events).
+
+#### Scenario: Listing all agents
+- **WHEN** the model reads bare `agent://`
+- **THEN** the system returns one row per live session with all five columns, e.g. `id  status  kind  parent  last activity`
+
+#### Scenario: Session without a live agent
+- **WHEN** a roster row's session has no entry in the live agent registry
+- **THEN** its `status` column renders `-`
+
+### Requirement: Agent output addressing
+The system SHALL let `agent://<id>` return that agent's output artifact: the rendered content of its last non-empty assistant message (matching `SubagentResult.output` semantics), or empty text when the agent produced no non-empty assistant output. Addressing is scoped to the caller's own family (the caller itself and its descendant children) — ids outside the family return `AGENT_UNKNOWN_ID`.
+
+#### Scenario: Reading a completed agent's output
+- **WHEN** the model reads `agent://<finished agent id>` from within its family
+- **THEN** the system returns the rendered text of that agent's last non-empty assistant message
+
+#### Scenario: Reading an unknown agent
+- **WHEN** the model reads `agent://<unknown id>` (or an id outside the caller's family)
+- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
+
+### Requirement: Agent transcript addressing
+The system SHALL let `agent://<id>/transcript` return the agent's full derived message history in order, each message headed by its role (`assistant`, `user`, `tool result`, `system`), with tool calls rendered as `[tool: name] arguments` and errors as `[tool error] …`. Addressing follows the same family scoping as output addressing.
+
+#### Scenario: Reading an agent's session history
+- **WHEN** the model reads `agent://<id>/transcript` for an agent in the caller's family
+- **THEN** the system returns every message of that session in order, role-headed
+
+### Requirement: Nested output addressing
+The system SHALL let `agent://<id>/<child>` return a direct child's output artifact, resolving the child only through the parent's enumerated children. Unknown children, or children not live in the session store, return `AGENT_UNKNOWN_ID`. Paths with more than two segments return `AGENT_BAD_PATH`.
+
+#### Scenario: Reading a nested child output
+- **WHEN** the model reads `agent://<parent id>/<child id>` and the child is a direct child of that parent
+- **THEN** the system returns the child's output artifact
+
+#### Scenario: Child not enumerable from the parent
+- **WHEN** the model reads `agent://<id>/<non-child id>`
+- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
+
+### Requirement: history has no scheme of its own
+The system SHALL provide transcript history only under `agent://<id>/transcript`. There is no `history://` handler and no special-case error for it: `history://` produces the generic `URL_UNREGISTERED_SCHEME` error like any other unregistered scheme.
+
+#### Scenario: history scheme is unregistered
+- **WHEN** the model reads `history://<id>`
+- **THEN** the system returns the structured `URL_UNREGISTERED_SCHEME` error listing the registered schemes (history not among them)

package/docs/specs/ast/spec.md

@@ -0,0 +1,34 @@
+# ast Specification
+
+## Purpose
+`ast` 是**纯 tool 设施**：无进程、无状态、无协议——文本进 → tree-sitter 语法树 → 结构匹配/改写 → 结果出。以 `dvc://ast` 设备面挂载（`ast_grep` 结构搜索 + `ast_edit` 结构改写，natives 懒加载），由 agent 在工具循环里主动调用；不设任何运行时拦截点、不订阅文件事件、不参与文本同步。与 hash-edit/LSP 的分工：结构问题归 ast，语义问题（类型/跨文件引用/诊断）归 LSP，锚点编辑归 hash-edit。
+
+## Requirements
+
+### Requirement: Pure tool semantics
+The ast device SHALL behave as a stateless function: every call carries its inputs (pattern, paths, content) and returns its result; no server process, no document mirror, no cross-call state SHALL exist.
+
+#### Scenario: Stateless call
+- **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.
+
+#### 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
+
+### 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.
+
+#### Scenario: Surface inventory
+- **WHEN** the model-facing tool surface is enumerated
+- **THEN** ast appears only as the `dvc://ast` device — its invocation is an ordinary `write` the agent decides to make
+
+### Requirement: Structural semantics boundary
+The ast device SHALL provide structural matching/rewriting only. It makes no claim about types, cross-file references, or diagnostics; a deployment wanting semantics SHALL use the lsp capability instead.
+
+#### 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)

package/docs/specs/compaction-recall/spec.md

@@ -0,0 +1,46 @@
+# compaction-recall Specification
+
+## Purpose
+TBD - created by archiving change 2026-09-11-url-schemes-recallable-context. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Compaction manifest with nested chain
+The system SHALL expose the compaction manifest of the live session, one entry per successful compaction episode, each carrying: `label` (the `compaction/summary` event seq), `checkpoint_seq` (summary seq + 1), `compactionId`, timestamp, `shadowedRange`, `shadowedItems`, `shadowedTokenCount`, `replaces_checkpoint` (the previous episode's checkpoint seq when absorbed, else null), and an 8-section summary preview (≤100 chars per section).
+
+#### Scenario: Manifest reflects nested compaction
+- **WHEN** a session has two successful compactions where the second absorbed the first's checkpoint
+- **THEN** the manifest lists both episodes and the second entry carries `replaces_checkpoint` equal to the first episode's checkpoint seq
+
+### Requirement: Label resolution precedes ordinal
+For any bracket-addressed collection, the system SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal only when no label matches. Compaction episodes SHALL use the `compaction/summary` event seq as label; failed compactions SHALL NOT appear in any collection because they never emit a summary event.
+
+#### Scenario: Failed compaction is not addressable
+- **WHEN** a compaction attempt fails (summary not smaller than shadowed content) and the model reads the compactions manifest
+- **THEN** the failed episode is absent from the manifest and has no addressable label
+
+### Requirement: Canonical and prepared faces for compaction episodes
+For `ctx://session/compactions[<label>]`, the bare URL SHALL return the episode's structured summary (all 8 sections verbatim) as the prepared default face, and `:raw` SHALL return the episode's canonical content — the original shadowed span derived from `shadowedSeqs` (role + content per item). Line windows SHALL always apply to the canonical content, and the composite `:raw:<lines>` form SHALL be valid and equal `:<lines>`. The former `/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. When an unwindowed `:raw` read of the canonical face exceeds 65536 chars, the system SHALL append an actionable note naming `:N-M` line-window paging; windowed reads (`:N-M`, `:raw:N-M`) and the bare prepared face SHALL NOT carry the note.
+
+#### Scenario: Recall of the original span behind a summary
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` after the episode shadowed 559 items
+- **THEN** the system returns the original message-level content of all shadowed items, including tool results and assistant messages
+
+#### Scenario: Chained recall to pre-previous originals
+- **WHEN** the model reads `ctx://session/compactions[109245]:raw` (the first episode in a nested chain)
+- **THEN** the system returns the first span's original content even though later compactions shadowed its checkpoint
+
+#### Scenario: Unwindowed raw recall of an oversized span pages explicitly
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` and the span exceeds 65536 chars
+- **THEN** the system returns the full span followed by a note naming `:N-M` line-window paging, while `:raw:N-M` / `:N-M` return the windowed lines without the note
+
+#### Scenario: Removed /original sub-path
+- **WHEN** the model reads `ctx://session/compactions[221217]/original`
+- **THEN** the system rejects the path with `CTX_BAD_PATH`, echoing the URL
+
+### Requirement: Recall is read-only and lazily materialized
+The system SHALL serve all recall resources strictly read-only, SHALL build the episode index lazily from the session log (zstd-decompressed, single-pass seq index) with invalidation on session-file change, and SHALL NOT impose truncation on canonical content beyond the tool layer's own limits, surfacing an actionable truncation note instead.
+
+#### Scenario: Oversized original request
+- **WHEN** the model reads an original span exceeding the tool-layer response cap
+- **THEN** the system returns the truncated head (or the requested line window) with a note naming the `:raw`/line-window addressing for the remainder

package/docs/specs/ctx/spec.md

@@ -0,0 +1,107 @@
+# ctx Specification
+
+## Purpose
+
+Let the model read a curated, read-only snapshot of its calling environment via `ctx://` URLs — small, static, agent-derived facts (who am I, what model, what cwd) addressable like any other resource. This replaces the v0.1.8c design that mapped `ctx://` onto persistent-kernel variables; see design.md D4 for why that semantics was wrong (the kernel namespace is the model's own REPL scratchpad, not its environment).
+
+## Requirements
+
+### Requirement: Curated snapshot keys
+The system SHALL resolve `ctx://session` as the recallable-context statistics snapshot: the prepared default face SHALL carry the session header (absorbing the former identity fields `id`/`status`/`origin`/`delegationDepth`), storage facts, totals using native DSH field names, per-compaction segments plus a `live` tail segment, the inline compactions manifest (label, checkpoint_seq, compactionId, shadowedRange, shadowedItems, shadowedTokenCount, `replaces_checkpoint`, and an 8-section × ≤100-char summary preview per episode), and a `system_prompt` info card. The canonical face (see `:raw`) SHALL be the full session transcript. The first-level keys `model` and `cwd` SHALL be removed — their information SHALL appear only as info-card fields inside the snapshot. Any other first-level key SHALL return the structured `CTX_UNKNOWN_KEY` error listing the known keys and sub-paths.
+
+#### Scenario: Reading session identity
+- **WHEN** the model reads `ctx://session` from a delegated subagent session
+- **THEN** the snapshot header carries the agent id, status, origin, and delegation depth
+
+#### Scenario: Reading the model configuration
+- **WHEN** the model reads `ctx://session`
+- **THEN** the snapshot info card carries the provider, model, and maxTokens of the calling agent's request options
+
+#### Scenario: Reading the working directory
+- **WHEN** the model reads `ctx://session`
+- **THEN** the session's creation working directory appears as an info-card field, not as a separate key
+
+#### Scenario: Unknown key
+- **WHEN** the model reads `ctx://<other key>`
+- **THEN** the system returns the structured `CTX_UNKNOWN_KEY` error naming the known keys and sub-paths
+
+### Requirement: Bare listing
+The system SHALL let bare `ctx://` return the roster of available resources and usage entry points (one per line), including the `session` root, the sub-path grammar pointer (naming the composite `:raw:N-M` form), and the `transcript`/`compactions`/`user_prompts`/`tool_calls`/`agent_responses`/`thinking`/`system`/`injections` sub-paths; the static portion SHALL not require a live agent, and the roster SHALL stay within its line budget (its previous size plus the three collection entries).
+
+#### Scenario: Listing keys
+- **WHEN** the model reads bare `ctx://`
+- **THEN** the system returns the roster naming `session`, its sub-paths (including `thinking` and `system`), and the addressing-grammar pointer
+
+### Requirement: Snapshot requires a live agent
+The system SHALL read every snapshot value from the calling agent supplied in the resolver env; an env with no live agent returns the structured `CTX_NO_AGENT` error on any value read.
+
+#### Scenario: No agent in the context
+- **WHEN** a ctx:// value read runs with no live agent in the resolver env
+- **THEN** the system returns the structured `CTX_NO_AGENT` error
+
+### Requirement: ctx is strictly read-only
+The system SHALL reject every write to `ctx://` with the structured `URL_READ_ONLY` error explaining the scheme is a curated read-only snapshot. There is no kernel-variable write channel and no variable mutation of any kind.
+
+#### Scenario: Writing to a snapshot key
+- **WHEN** the model writes to `ctx://<any key>`
+- **THEN** the system returns the structured `URL_READ_ONLY` error and changes nothing
+
+### Requirement: Session sub-path grammar
+The system SHALL resolve `ctx://session/…` sub-paths: `transcript` (full transcript), `compactions` (manifest), `compactions[<label|ordinal>]` (the episode summary, 8 sections verbatim), `user_prompts[<n|seq>]`, `tool_calls[<n|seq>]`, `agent_responses[<n|seq>]`, `thinking[<n|seq>]` (reasoning blocks), and `system[<n|seq>]` (system messages). The former `compactions[<label|n>]/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. Bracket resolution SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal on miss. The system SHALL support `:raw` and line windows (`:N`, `:N-M`, `:N+K`, `:N-`, comma-separated ranges) on every resolved resource, and the composite `:raw:<lines>` form SHALL be valid everywhere and SHALL equal `:<lines>` (the `:raw` prefix is redundant in a line-window context but MUST parse).
+
+#### Scenario: Drilling into a compaction episode by label
+- **WHEN** the model reads `ctx://session/compactions[221217]`
+- **THEN** the system returns that episode's structured summary (all 8 sections verbatim)
+
+#### Scenario: Ordinal fallback
+- **WHEN** the model reads `ctx://session/compactions[0]` and no episode carries the label `0`
+- **THEN** the system returns the first-recorded episode (0-based)
+
+#### Scenario: Composite raw selector
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw:500-560`
+- **THEN** the system returns the same lines as `ctx://session/compactions[221217]:500-560`
+
+#### Scenario: Removed /original sub-path
+- **WHEN** the model reads `ctx://session/compactions[221217]/original`
+- **THEN** the system returns the structured `CTX_BAD_PATH` error echoing the URL and naming the `:raw` / `:N-M` selectors as the replacement
+
+### Requirement: Canonical and prepared content faces
+The system SHALL treat every resource as having one canonical content: `:raw` SHALL return the canonical full content, line windows SHALL always apply to the canonical content, and the bare URL SHALL return the prepared default face when one is prepared (session → statistics snapshot; compaction episodes → 8-section summary; `thinking` → per-block index list; `system` → per-message index list) or the canonical content when none is. `:raw:<lines>` SHALL equal `:<lines>` — the composite form is accepted on every resource.
+
+#### Scenario: Line windows ignore the prepared face
+- **WHEN** the model reads `ctx://session/compactions[221217]:500-560`
+- **THEN** the system returns lines 500–560 of the episode's original shadowed span, not of the summary
+
+### Requirement: Thinking, system, and injections collections
+The system SHALL expose three index-faced collections under `ctx://session/`, all following the canonical/prepared face model (bare URL = prepared index; `:raw` / `:N-M` = canonical full text):
+
+- `thinking` — the reasoning blocks of `assistant/message` events (`message.content` blocks of `type: "reasoning"`, in event order; a message may carry several). The bare URL SHALL return an index list, one line per block: 0-based ordinal, event seq, turn/step, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that block's full text (label = the block's event seq, exact match first, 0-based ordinal fallback). `:raw` SHALL return all blocks' full text joined in event order with a blank line between blocks, and line windows SHALL index that canonical text.
+- `system` — the session's `system/message` events (text from `data.text` when present, else the message content blocks; source kind/plugin from `data.source` when present). The bare URL SHALL return an index list, one line per message: event seq, source kind/plugin, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that message's full text. `:raw` SHALL return all messages' full text joined with a blank line between messages, and line windows SHALL index that canonical text.
+- `injections` — the session's injected `user/message` events, i.e. every `user/message` whose `source.kind` is not `user` (agent instructions, runtime-context snapshots, …; the exact complement of the `user_prompts` collection). The bare URL SHALL return an index list, one line per message: event seq, source kind, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that message's full text rendered as `[<zero-padded seq>] INJECTED <kind>` followed by the content. `:raw` SHALL return all messages' full text joined with a blank line between messages, and line windows SHALL index that canonical text.
+
+#### Scenario: Index then drill into a reasoning block
+- **WHEN** the model reads `ctx://session/thinking` and then `ctx://session/thinking[2]`
+- **THEN** the index lists one line per reasoning block (ordinal, seq, turn/step, preview) and the drilled read returns the third block's full text
+
+#### Scenario: Canonical window over the joined blocks
+- **WHEN** the model reads `ctx://session/thinking:10-20`
+- **THEN** the system returns lines 10–20 of the reasoning blocks' full text joined with blank lines, ignoring the index face
+
+#### Scenario: System message by seq label
+- **WHEN** the model reads `ctx://session/system[7]` where event seq 7 is a system message
+- **THEN** the system returns that message's full text
+
+#### Scenario: Injections complement user_prompts
+- **WHEN** the model reads `ctx://session/injections` in a session whose `user/message` events carry both `source.kind: "user"` and non-`user` sources (agent instructions, runtime snapshots)
+- **THEN** the index lists only the non-`user` messages (seq, source kind, preview), `ctx://session/injections[<n|seq>]` returns one message's full text, and `ctx://session/user_prompts` continues to list only the real prompts
+
+#### Scenario: Injection message by ordinal or seq
+- **WHEN** the model reads `ctx://session/injections[0]` or `ctx://session/injections[<seq>]`
+- **THEN** the system returns that injected message's full text with its `INJECTED <kind>` header line
+
+### Requirement: Unknown key echoes known keys
+The `CTX_UNKNOWN_KEY` error SHALL list the currently known first-level keys and the sub-path pointer, so the model can self-correct without leaving the read tool.
+
+#### Scenario: Unknown key with roster echo
+- **WHEN** the model reads `ctx://bogus`
+- **THEN** the system returns `CTX_UNKNOWN_KEY` naming `session` and the sub-path roster

package/docs/specs/dsh/spec.md

@@ -0,0 +1,47 @@
+# dsh Specification
+
+## Purpose
+
+Let the model read the harness's own documentation and its effective configuration via `dsh://` URLs — runtime self-description, shipped with the package so it resolves in source, built, and installed layouts alike.
+
+## Requirements
+
+### Requirement: Documentation addressing
+The system SHALL let `dsh://docs` return the sorted recursive listing of readable harness docs as JSON, and `dsh://docs/<doc>` return that document's content. A missing docs tree returns `URL_DOCS_UNAVAILABLE`; a missing document, a path escaping the docs directory, or a non-file target returns `URL_DOC_NOT_FOUND`. Any other root resource returns `URL_UNKNOWN_RESOURCE`.
+
+#### Scenario: Browsing the doc listing
+- **WHEN** the model reads `dsh://docs`
+- **THEN** the system returns the JSON array of doc paths relative to the docs root
+
+#### Scenario: Reading a specific document
+- **WHEN** the model reads `dsh://docs/<doc>`
+- **THEN** the system returns that document's content
+
+#### Scenario: Path traversal is rejected
+- **WHEN** the model reads `dsh://docs/../secrets`
+- **THEN** the system returns the structured `URL_DOC_NOT_FOUND` error (path escapes the docs directory) and reads nothing
+
+### Requirement: Docs tree resolves in every layout
+The system SHALL locate the docs tree by a nearest-first walk-up from the module's own location (`docs-dir.ts`), and the package SHALL ship the docs (`prebuild` copies the repo `docs/` into the package; the `files` array includes it) so source-tree, bundled-lib, and installed-`node_modules` layouts all resolve the package's own docs first.
+
+#### Scenario: Installed package resolves its own docs
+- **WHEN** the plugin runs from `node_modules/<dashr>/lib/index.js`
+- **THEN** `dsh://docs` serves the docs shipped inside that package, not an ancestor directory's
+
+### Requirement: Effective config addressing
+The system SHALL let `dsh://config` return the current resolved settings as JSON keyed by namespace, and `dsh://config/<ns>` return one namespace. A missing settings service returns `URL_SETTINGS_UNAVAILABLE`; an unknown namespace returns `URL_UNKNOWN_SETTINGS_NAMESPACE`.
+
+#### Scenario: Reading the effective config
+- **WHEN** the model reads `dsh://config`
+- **THEN** the system returns the resolved (not documented-default) configuration, namespace by namespace
+
+#### Scenario: Reading one namespace
+- **WHEN** the model reads `dsh://config/<known namespace>`
+- **THEN** the system returns that namespace's resolved value as JSON
+
+### Requirement: Config never leaks secrets
+The system SHALL strip secrets from every config response: schema-declared `role('secret')` redaction plus a defensive key-name denylist matched against normalized key names (credential/env/API-key material), applied recursively.
+
+#### Scenario: Config hides keys
+- **WHEN** the model reads `dsh://config` or `dsh://config/<ns>` and a resolved field is an API key or other secret-named field
+- **THEN** the returned JSON does not contain the secret value

package/docs/specs/dvc/spec.md

@@ -0,0 +1,87 @@
+# dvc Specification
+
+## Purpose
+
+Reserve DASHR's device I/O surface under `dvc://` (renamed from the earlier `xd://` placeholder — no `xd` name remains anywhere): a read = device list/document view, a write = device dispatch entry. No device provider is mounted this wave, so both views are placeholders that fix the URL shapes and the structured write error for whatever device layer lands later.
+
+## Requirements
+
+### Requirement: Device roster placeholder
+`dvc://` SHALL return the mounted-device roster listing every registered device name. With no device modules loaded the roster is the placeholder text `no devices mounted`; once devices are registered it lists their names.
+
+#### Scenario: Listing mounted devices
+- **WHEN** the model reads bare `dvc://`
+- **THEN** the system returns the roster of registered device names (or `no devices mounted` when none)
+
+### Requirement: Unknown device placeholder
+The system SHALL let `dvc://<device>` return placeholder text `unknown device: <name>` — no device provider exists to answer with a real document.
+
+#### Scenario: Reading an unmounted device
+- **WHEN** the model reads `dvc://<any device name>`
+- **THEN** the system returns `unknown device: <name>`
+
+### Requirement: Write dispatch is a structured no-op
+Every write to `dvc://<device>` SHALL dispatch to the registered device's execute with the JSON-args payload; with no devices mounted the structured `DVC_NO_DEVICE` error stands, and an unknown device name remains a structured error.
+
+#### Scenario: Writing with no devices
+- **WHEN** the model writes to `dvc://<device>` and no device module is registered
+- **THEN** the system returns the structured `DVC_NO_DEVICE` error and dispatches nothing
+
+### Requirement: Device dispatch contract
+The system SHALL implement the device write contract: `write dvc://<device>` with a JSON-args content executes the device and returns its result; a non-JSON content or a device-reported failure returns a structured error carrying the device name.
+
+#### Scenario: Executing a registered device
+- **WHEN** the model writes `dvc://ast_edit` with valid JSON args
+- **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.
+
+#### 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: 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.
+
+#### Scenario: Opening a page headlessly
+- **WHEN** the model writes `dvc://browser` with an open action and URL
+- **THEN** a headless tab opens and the action result returns
+
+### Requirement: lsp device
+The system SHALL provide an `lsp` device (definition/references/diagnostics/actions) vendored from the omp harness; languages whose server binary is absent degrade gracefully per language.
+
+#### Scenario: Diagnostics for an installed language server
+- **WHEN** the model writes `dvc://lsp` requesting diagnostics for a file whose language server is installed
+- **THEN** the device returns the diagnostics
+
+#### Scenario: Missing language server degrades
+- **WHEN** the requested language's server binary is not installed
+- **THEN** the device reports the missing server without crashing the session
+
+### Requirement: lsp wired into write
+The system SHALL close the write-feedback loop: after a `write` lands a file whose language has an available language server, the tool result SHALL include a diagnostics summary for that file (error/warning counts plus the first message detail when non-zero), and the content SHALL be formatted before the single native write when the language server provides formatting capability. The diagnostics pipeline SHALL be honest about freshness: the feedback path syncs the exact written content, then signals the standard save notification (`textDocument/didSave`) so save-triggered checkers (e.g. rust-analyzer's flycheck) re-run, and waits for the refreshed diagnostics under a bounded timeout. When the wait times out, save-triggered compiler-source diagnostics (which are provably stale at that point) SHALL be dropped while immediately-computed diagnostics are kept — under-reporting beats mis-reporting. As a final guard, any diagnostic whose line lies beyond the just-written content's line count SHALL be dropped: it cannot refer to what was written. Languages with no server available (absent binary or unsupported extension) SHALL behave exactly as before — the hook adds nothing and fails silently, and the native write receives the caller's arguments object unchanged when formatting changes nothing.
+
+#### Scenario: Write surfaces the damage it just caused
+- **WHEN** a write lands content that introduces a type error in a file with a language server installed and its check-on-save pipeline completes within the timeout
+- **THEN** the write result carries a diagnostics summary describing the EXACT content just written (never a stale earlier version), so the model learns of the breakage without a separate diagnostics call
+
+#### Scenario: A fixed error stops being reported
+- **WHEN** a write replaces content that previously had a type error with correct content
+- **THEN** the write result no longer reports the old error — the save-triggered checker re-ran on the new content, and any compiler-source diagnostic still describing the old content is either refreshed or dropped
+
+#### Scenario: Slow checks degrade honestly
+- **WHEN** the save-triggered check does not complete within the bounded timeout
+- **THEN** compiler-source diagnostics are dropped from the summary (they are provably stale), immediately-computed diagnostics remain, and the result never reports an error that refers to content other than what was just written
+
+#### Scenario: Out-of-range spans are dropped
+- **WHEN** a published diagnostic references a line beyond the just-written content's line count
+- **THEN** that diagnostic is excluded from the summary and the counts reflect only the retained set
+
+#### Scenario: Format-before-write
+- **WHEN** a write targets a file whose server provides formatting
+- **THEN** the native write receives and stores the formatted content (one write, one audit), and the before/after pair stays truthful
+
+#### Scenario: Serverless language unchanged
+- **WHEN** a write targets a file whose language has no server available
+- **THEN** the result is byte-identical to the pre-change behavior (no diagnostics block, no formatting, no error)

package/docs/specs/escalation-guidance/spec.md

@@ -0,0 +1,44 @@
+# escalation-guidance Specification
+
+## Purpose
+在 workspace-write 沙箱模式下，向模型的运行时上下文注入 per-call 升级能力的精简披露：受限操作可被拒/已拒后按调用以 `sandbox_permissions` + 一行 `justification` 升级（runtime 提示 user 审批，审批/拒绝均为 per-call，无会话级预算措辞）。该注入只披露能力、不劝导行为，且不依赖 upstream 源码修改。
+
+## Requirements
+
+### Requirement: Escalation guidance injected under workspace-write only
+
+The system SHALL inject an escalation-guidance context entry into the model-facing system prompt when the session's effective sandbox mode is `workspace-write`, and SHALL NOT inject it when the effective mode is `read-only` or `danger-full-access`. The guidance SHALL state the per-call escalation semantics in the approved wording: a sandbox-deniable or sandbox-denied call MAY be escalated with `sandbox_permissions` and a one-line `justification`; the runtime SHALL prompt the user for approval; escalation and its approval/denial SHALL be per-call. The guidance text SHALL NOT contain quota wording (`retried once`, `once`, allowed-once) or any claim of a session-level escalation budget.
+
+#### Scenario: Workspace-write session sees the guidance
+
+- **WHEN** a DASHR agent session runs with effective sandbox mode `workspace-write`
+- **THEN** the runtime-context snapshot contains the escalation-guidance entry stating the deniable/denied per-call escalation path (`sandbox_permissions` + one-line `justification`, user approval prompted by the runtime)
+
+#### Scenario: Guidance contains no quota wording
+
+- **WHEN** the escalation-guidance entry renders under `workspace-write`
+- **THEN** its text contains none of `retried once` / allowed-once / per-session budget claims, and states that escalation and its approval/denial are per-call
+
+#### Scenario: Read-only session skips the guidance
+
+- **WHEN** a DASHR agent session runs with effective sandbox mode `read-only`
+- **THEN** the runtime-context snapshot contains no escalation-guidance entry from DASHR (the upstream read-only policy sentence already teaches the escalation guidance)
+
+#### Scenario: Danger-full-access session skips the guidance
+
+- **WHEN** a DASHR agent session runs with effective sandbox mode `danger-full-access`
+- **THEN** the runtime-context snapshot contains no escalation-guidance entry (there is no restricted operation to escalate)
+
+### Requirement: Guidance is minimal disclosure, not behavioral coaching
+The system SHALL keep the injected guidance text limited to disclosing the escalation capability — it SHALL NOT instruct the model to attempt restricted operations, SHALL NOT instruct it to refrain, and SHALL NOT restate or claim the sandbox is immutable. Whether to attempt an out-of-box operation SHALL remain the model's own decision.
+
+#### Scenario: Text states the lever only
+- **WHEN** the escalation-guidance entry renders under `workspace-write`
+- **THEN** its text discloses the single-call escalation path and contains no imperative coaching sentence (no "do not refuse", no "go try", no "you are sandboxed and cannot change it")
+
+### Requirement: Guidance rides the runtime-context snapshot
+The system SHALL render the escalation guidance inside the same runtime-context snapshot region as the sandbox and approval policy entries (positioned after the approval-policy entry), so it is adjacent to the policy statements the model already reads. The injection SHALL register through the plugin system-prompt context API (`ctx.systemPrompt.context`) without modifying upstream DSH source.
+
+#### Scenario: Guidance sits beside the policy entries
+- **WHEN** a `workspace-write` session renders the system prompt
+- **THEN** the escalation-guidance entry appears in the runtime-context snapshot, ordered after the `approval:policy` entry and before any later context entries

package/docs/specs/fs-scheme-resolution/spec.md

@@ -0,0 +1,37 @@
+# fs-scheme-resolution Specification
+
+## Purpose
+定义文件系统服务层的 URL scheme 解析契约：通过 `urlSchemes` 配置门控，在 `ctx.fs` 实例上原位包裹，使 `dsh://`、`dvc://`、`http(s)://` 等静态 scheme 经统一解析器读出虚拟目标。门控关闭时透明退化为 stock 行为（bit-for-bit 等价），真实路径语义不受影响。
+
+### Requirement: FS-gate scheme resolution
+The system SHALL resolve file-type scheme URLs (`dsh://`, `dvc://`, `http(s)://`) at the filesystem service seam by wrapping the LIVE `ctx.fs` instance in place (instance-level method wrap of its five public methods; symbol-idempotent, re-applied per boot, every added behavior gated behind `urlSchemes`; a wrap failure degrades to the stock service, never a failed boot). Every `ctx.fs` consumer — including the platform's native read/write/edit tools with no tool-layer wrapping — SHALL thus resolve these URLs through the URL resolver: `resolve` returns a virtual target keyed by the URL, `stat` answers a synthesized file entry, and `readText` dereferences the resolved text.
+#### Scenario: Native read of a static scheme without tool-layer participation
+- **WHEN** the hashline tool gate is disabled (the wrapped read delegates to the captured native read) and the model reads `dsh://docs/<doc>`
+- **THEN** the native read resolves the document through the filesystem backend and returns its text — no tool-layer scheme code participated
+
+#### Scenario: Real-path passthrough
+- **WHEN** any consumer resolves, reads, or mutates a real filesystem path
+- **THEN** every operation delegates to the inherited sandboxed backend unchanged (containment, observation events, atomic writes, read-match-write critical section)
+
+### Requirement: Virtual targets are read-only
+The backend SHALL refuse mutations that target a virtual scheme path with the structured `FS_VIRTUAL_READONLY` error before any policy or filesystem work, while `urlSchemes` is enabled. Real-path mutations keep the stock fence.
+
+#### Scenario: Native write against a virtual target
+- **WHEN** the model writes to a scheme path that has no write channel at the FS layer
+- **THEN** the call fails with `FS_VIRTUAL_READONLY` and no file is created
+
+### Requirement: Session-layer schemes stay at the tool layer
+`ctx://`, `agent://`, and `skill://` require live-agent semantics the filesystem layer does not have: the first two read session state, and `skill://` must consult the host skill registry's layered catalog — whose discovery (which roots load: project/user/preset/custom/bundled, scan depth, rank and scope merge) is business logic owned by the host `skill-filesystem` provider and resolves only against a calling agent. The backend SHALL answer all three with a structured session-layer boundary error naming the sanctioned channel (the native `skill` tool for skill loading), and SHALL NOT re-implement or approximate skill discovery (no own root parsing, no cwd heuristics, no scope guessing). The wrapped read tool's scheme branch SHALL continue to serve `ctx://`/`agent://` with the calling agent's context, and the skill handler at the tool layer SHALL mirror the native tool's lookup exactly (`cwd` from the agent's session header, the agent as viewing scope).
+#### Scenario: Native read of ctx:// names the boundary
+- **WHEN** the model reads a `ctx://` URL through a consumer that has no live-agent resolver environment
+- **THEN** the backend returns a structured error explaining that `ctx://` is served by the session-layer read, instead of a raw filesystem failure
+
+#### Scenario: Native read of skill:// names the session-layer boundary
+- **WHEN** the model reads any `skill://` URL through a filesystem-layer consumer (no calling agent)
+- **THEN** the backend returns the structured session-layer boundary error pointing at the native `skill` tool — never a registry verdict (such as "unknown skill") guessed from a deployment-declared cwd
+### Requirement: Gate disables resolution transparently
+When `urlSchemes` is `false`, the backend SHALL short-circuit every override to the inherited stock behavior — scheme paths fail as ordinary native paths, real-path semantics are untouched, and the deployment behaves bit-for-bit like the stock `fs-sandbox` row.
+
+#### Scenario: Stock degradation
+- **WHEN** the deployment sets `urlSchemes: false` on the mounted row and a consumer reads a scheme URL
+- **THEN** the call fails as it would under the stock backend (no scheme interception anywhere)

package/docs/specs/hash-edit/spec.md

@@ -0,0 +1,41 @@
+# hash-edit Specification
+
+## Purpose
+DASHR 的哈希锚点读写/edit 契约：`read` 以 `HASH│content` 行锚点呈现文件；`edit`/`undo_last_edit` 以锚点定位做单文件原子编辑；served 账本（schema v7，path 主键，集中存储于 `$DSH_HOME/storages/dsh-better-edit/`）保证锚点跨会话可验证。hash-edit 是自包含模块（`src/hashline/`），对 url-schemes 零出向引用；与 url-schemes 的组合只发生在 `url-schemes/index.ts` 组合根（read 链：scheme wrapper → hashline read → captured native）。
+
+## Requirements
+
+### Requirement: Anchored read presentation
+The hashline read doer SHALL present every served text file as `HASH│content` rows (3-char hash anchors for later edit calls), with paging via `offset`/`limit` on file reads.
+
+#### Scenario: Anchored read
+- **WHEN** the agent calls `read` on a filesystem path with hashline enabled
+- **THEN** each line returns as `HASH│content` and the served rows persist to the centralized store keyed by absolute path
+
+### Requirement: Content-anchored edit with single-file atomicity
+The `edit` tool SHALL apply the payload `{ path: string|null, edits: [[remove_from, remove_to, replacement_text], ...] }` as a single-file atomic batch; `null` path infers via anchors; `undo_last_edit` reverts the last edit on a file. Edit verification is content-anchored: a range whose bounds are unseen by the served ledger MAY pass via the content fast-path; `E_RANGE_STALE`/`E_RANGE_UNSERVED` semantics are preserved.
+
+#### Scenario: Atomic batch
+- **WHEN** an edit payload contains multiple edits and one anchor fails to resolve
+- **THEN** no edit from the batch is written and the failing range is echoed back with fresh anchors
+
+### Requirement: Host guard independence
+The host `dsh-fs-observation-policy`'s `E_NOT_OBSERVED` (read-before-edit) SHALL remain an independent design-intent guard for cross-session edits; hash-edit verification complements, never replaces, it.
+
+#### Scenario: Cross-session edit
+- **WHEN** a session edits a file it never read and no served rows exist for its bounds
+- **THEN** the host observation policy still denies or the content fast-path rules, per its own contract — hash-edit does not silently relax it
+
+### Requirement: Module orthogonality
+The hashline module SHALL NOT import anything from `url-schemes` (or any scheme surface). Its standalone entries — `initHashlineRuntime()`, `createHashlineReadTool()`, `installHashline()` — SHALL work with url-schemes absent; per-agent features it does not own (e.g. lsp edit feedback) arrive only as injected callbacks.
+
+#### Scenario: Standalone mount
+- **WHEN** a deployment mounts hashline without url-schemes
+- **THEN** anchored read + edit/undo + guidance register and function; no scheme branch exists anywhere in the module
+
+### Requirement: Shared sandbox controller
+When co-mounted with a write wrapper, the `FsSandboxController` instance SHALL be created by the composition root and injected into both the hashline edit family and the write wrapper, so escalation advertisement and per-call policy stamping share one controller.
+
+#### Scenario: Shared escalation surface
+- **WHEN** a confining sandbox backend is mounted and both hashline and the write wrapper are active
+- **THEN** `edit` and `write` escalate through the same controller with the session workspace root stamped