better-dsh 0.2.4 → 0.2.5-a

package/docs/10_plans/2026-09-26-lsp-ast-reminder.md

@@ -0,0 +1,64 @@
+# 2026-09-26 — LSP mount 收尾 + AST 可用性提醒 hook
+
+状态：**已实现，测试全绿，未发布**（commit 见 better-dsh `change(2026-09-26-lsp-ast-reminder)`）。
+
+## 背景（已裁决的事实）
+
+1. LSP gate 的 per-agent 挂载修复（`agent/session-start` → `agent/created`）已在 HEAD
+   （`ce0541c`，2026-09-24），**未发布未部署**（最后 tag `v0.2.4b`，prod 跑的是它）。
+   本计划核实其完备性，不重复实现。
+2. AST 提醒（新功能）：在 `write`/`edit`/`grep` 的工具结果尾部追加一行
+   "ast_edit / ast_grep 可用"提示。**无 cap、每次都提示**（user 裁决 2026-09-26），
+   但按文件类型收窄（user 裁决：只认 Python/TypeScript 有限集）。
+   不与 LSP gate 交互、不中断/不改写原结果。
+3. auto-review 适配（binding schema）**本计划不做**（user 裁决：experimental，不适配）。
+
+## 核实项（Task 0，只读）— 全部通过
+
+- [x] `src/url-schemes/index.ts` per-agent 挂载在 `agent/created`（HEAD 已修）
+- [x] `src/index.ts`（REPL 行）同上（:1114）
+- [x] 核心 0.1.7 发 `agent/created`/`agent/disposed`，不发 `agent/session-start`
+- [x] 核心 `postExecute` 认 accept+content 变体 → notice append 在挂载后即生效
+- [x] `src/hashline/index.js` 的 `session-start` 监听属旧独立插件壳，不在 bundle
+  exports（活路径是 `install.js#installHashline`，随 installAgentTools 走）
+  → **不改动**，仅在报告中记录
+- [x] 全量 grep src 确认无其他死事件注册
+
+## Task 1: `ast-reminder` 纯函数模块（TDD）✅
+
+- `src/devices/ast/ast-reminder.ts`
+- `test/surface-devices/ast-reminder.spec.ts`
+- 扩展名集：`.py .ts .tsx .mts .cts`；grep 规则：include 命中 py/ts、或 path 为
+  目录/缺省/代码文件 → 提示；仅当 path 明确指向非代码文件时静默。
+- 文案单行：`ast_edit / ast_grep available for Python/TypeScript — write
+  dvc://ast_edit (structured rewrite) or dvc://ast_grep (pattern search)`
+
+## Task 2: 接入 post-execute 钩子 ✅
+
+`src/url-schemes/index.ts`：工具名集合扩为 `read/edit/write/grep`；LSP 语义逐字节
+不变（副作用时序、isError 早退、accept-only append）；两个 suffix 组合到一次
+append（`appendSuffixes` 泛型 helper）。
+
+## Task 3: 构建 + 全量测试 ✅
+
+`npm run build` ✔；`tsc --noEmit` host+client ✔；`vitest run` **617 passed +
+1 skipped**（基线 611+1skip，新增 ast-reminder 单测 7 + 钩子级 6）。
+
+## Task 4: 4999 实测 ✅（2026-09-27 user 第一人称实测通过）
+
+报告：`docs/50_test-reports/2026-09-27-lsp-ast-reminder-4999实测报告.md`。
+三设备全绿 + 提醒链路 session log 实证（nag×1 + AST×1）；gotcha G1–G4 记录在报告 §4。
+
+已完成：occupant（native-ui-fusion 实例）经 user 批准退役；新 lib 已 rsync 进
+test123 profile；rig 重启（token 见 start.sh 输出），boot graph 含 `better-dsh`。
+RPC 探针（`POST /api/session/list`）证明网关面存活，但完整 session 驱动需 gateway
+`_request` 描述符契约，未逆向。**浏览器验收清单（user，1 分钟）**：
+1. 打开 rig URL → 新会话；2. 让它写一个 `.py` 文件 → 工具结果尾部应出现两行：
+   LSP nag（`lsp diagnostics available…`）+ AST 行（`ast_edit / ast_grep available…`）；
+3. 让它写一个 `.md` → 两行都不出现；4. 会话里 `write dvc://ast_grep {"patterns":["..."],"path":"..."}` 真实可用。
+
+## 明确不做
+
+- auto-review binding schema 适配（user：experimental，不适配）
+- `src/hashline/index.js` 死事件改名（不在发布面，记录即可）
+- npm publish / GitHub tag（需 user 单次确认）

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