super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/20_specs/tool-surface/spec.md

@@ -0,0 +1,222 @@
+# tool-surface Specification
+
+## Purpose
+DASHR 的模型表面（model surface）契约：哪些工具出现在 registry 投影（LLM-client 协议 tools 数组、REPL 绑定）里。核心原则——掩码作用于 tool registry（被替代了呈现面的原生工具全部 visible=false）；REPL 绑定对 registry 可见集做机械/透明的自动桥接（零名单维护）；被掩工具的能力保留靠三桥 service 层直调（`agent` spawn/fork、`agent_message` 消息+中断、`agent_workflow` 编排），不靠 registry 豁免。全部 REPL 指引（cell 语义、调用形、非 flat 名例外、`subagent` 别名注记）只经由 `eval` 工具的 wire description 承载——system prompt 中不存在任何 DASHR 渲染的工具目录或 control-prompt section。
+
+## Requirements
+
+### Requirement: Registry masking of replaced-presentation native tools
+
+The system SHALL remove the native tools whose presentation surface DASHR replaces（`skill`、上游 `send_message`、`report`、`list_agents`、delegation 家族 `subagent_fork`/`interrupt_agent`/`workflow`/`ralph`）from the agent's tool registry projection via an agent-scope registry restriction —— wire tools array 与 REPL bindings 同源于该 projection，移除因此均匀生效。`subagent` is deliberately NOT masked：它在每个表面保持可见，且 **`eval` 工具的 description** 注记它是 `agent` delegation tool（统一 agent-spawn 入口）的别名。The restriction MUST NOT touch the registered tool definitions themselves；DASHR preserves each masked tool's native capability at the tool-bridge level（not by registry exemption）：`agent` spawns/forks subagents、`agent_message` 经 host-plane service 层传递 child-downlink/parent-uplink/interrupt、`agent_workflow` 把 script/rfc 透传给 CAPTURED native workflow/ralph definitions（workflowEngine service 是 preset delegation realm 的 entry-local 服务，任何外部 ctx 不可见——native execute closures 从内部解析）；`agent://` 取代 `list_agents`、`read skill://` 取代 `skill`。
+
+#### Scenario: Masked tool absent from every model-facing surface
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** the wire tools array 与 the REPL bindings 均不含 masked 名，对 masked 名的调用返回 `UNKNOWN_TOOL`
+
+#### Scenario: subagent stays visible as an annotated alias
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** `subagent` remains present on the wire tools array 与 the REPL bindings，且 `eval` 工具 description 注明它是 `agent` delegation tool 的别名
+
+#### Scenario: Masked capability preserved through the bridge
+
+- **WHEN** the model sends a child-downlink, parent-uplink, or interrupt through the `agent_message` bridge
+- **THEN** the service layer executes it with native delivery semantics (user-role next-turn delivery, `messageId` confirmation) and native authorization (direct-child-only lineage, ancestor authority for interrupt)
+
+#### Scenario: DASHR's own wrappers unaffected
+
+- **WHEN** the agent-scope restriction denies a native name that a DASHR wrapper shadows on the agent's own layer
+- **THEN** the wrapper (`read`/`write`/`grep`/`glob`, `agent`/`agent_message`/`agent_workflow`) remains visible and callable on every surface
+
+### Requirement: Delegation bridges are registry tools
+
+The system SHALL register the delegation bridges（`agent`、`agent_message`、`agent_workflow`）as real tools in the tool registry（与 `eval` transport 同一 host registration 层），runtime argument validation inside their execute、structured `{ error }` return values（bad input 不抛异常）。Registry projection 是**两个**模型表面的 single source：wire tools array 与 REPL `tool.*` bindings（经 mechanical auto-bridge）。两个表面 SHALL 每个 session name-by-name 相等（以 mechanical binding rule 的 flat-name 限定为界）；唯一允许的例外是 `eval` 本身排除在 binding set 之外（self-call prevention）。
+
+#### Scenario: Bridge callable directly on the wire
+
+- **WHEN** the model sends a direct tool call `agent` with `{ description, prompt }` (no cell)
+- **THEN** the call dispatches through the normal kernel pipeline and returns the same result shape the REPL binding returns, with the same audit events as any registry tool
+
+#### Scenario: Three-surface name equality
+
+- **WHEN** a DASHR session starts
+- **THEN** 目录表面已随「Catalog section presents REPL bridge instructions」的 REMOVED 撤销，原三表面等式收敛为两表面：the wire tools array 与 the REPL binding names 在 flat-name 规则内 equal as sets，excepting only `eval`
+
+#### Scenario: No dual-source drift
+
+- **WHEN** a bridge's parameter surface changes
+- **THEN** the wire schema 与 REPL binding 一起变化，因为两者都派生自同一注册 schema
+
+### Requirement: eval transport description matches runtime semantics
+
+The system SHALL state the eval transport's top-level semantics truthfully in **the `eval` tool's model-facing description（唯一的 REPL 指引载体）**：top-level `await` works —— kernel 以 `PyCF_ALLOW_TOP_LEVEL_AWAIT` 编译 cell 并运行 module coroutine；top-level `return` is a SyntaxError（cell 运行于 module scope，globals = locals）。The description SHALL NOT claim top-level `return` is accepted.
+
+#### Scenario: Description promises only what the kernel does
+
+- **WHEN** the model reads the `eval` tool description
+- **THEN** the text states that top-level `await` works，states that top-level `return` is a SyntaxError（module-scope cell），and contains no claim that top-level `return` is accepted
+
+#### Scenario: Top-level return stays rejected
+
+- **WHEN** a cell contains a top-level `return`
+- **THEN** the kernel rejects it with a SyntaxError, matching the description
+
+### Requirement: eval description is the single REPL guidance source
+
+The system SHALL carry ALL REPL guidance in the `eval` tool's wire description —— cell 语义、直调 vs 进 cell 的判据、非 flat 名例外、`subagent` 别名注记、**置于 description 末尾**的 mechanical bridge 调用形 —— 内容从**插件源码中的 Markdown 文件**加载、注册工具时作为 `description` 生效；system prompt 中 SHALL NOT 存在任何 DASHR 渲染的工具目录或 control-prompt section。桥接指引 SHALL 只陈述**一个**统一调用形、一句话说清：`await tool.<name>(argsObject)`，argsObject = 该工具 wire JSON-Schema 参数对象写成的 Python dict 字面量（同字段名、单个位置参数、不用 kwargs），唯一系统性语法差异为 `true`/`false`/`null` → `True`/`False`/`None`；SHALL NOT 渲染 per-tool 签名表，且 SHALL NOT 对桥接调用的返回值形态作任何陈述（不写"不保证形状/需试错"类措辞）。描述中的桥接示例 SHALL 使用与被引工具 wire schema 一致的参数名。
+
+#### Scenario: System prompt carries no DASHR catalog or control section
+
+- **WHEN** an agent session renders its system prompt
+- **THEN** 没有 DASHR 来源的 section 枚举 per-tool 签名，也没有独立的 control-prompt section 教 cell 范式；全部 REPL 指引只经由 `eval` description 到达模型
+
+#### Scenario: Description loads from the source Markdown
+
+- **WHEN** the plugin registers the `eval` tool
+- **THEN** 其 wire description 等于包内 Markdown 指引文件的内容——编辑该文件即改变模型可见的 description
+
+#### Scenario: One bridge call form, one syntax delta
+
+- **WHEN** the model reads the bridge instructions in the `eval` description
+- **THEN** it sees the single positional-args-object call form 与 `True`/`False`/`None` 大小写映射，and no per-tool signature table or output-shape caveat（无任何"不保证形态/试错"措辞）
+
+#### Scenario: Examples match wire parameter names
+
+- **WHEN** the description shows a bridge example for `read`
+- **THEN** 参数键与 `read` 的 wire schema 一致（如 `path`），而非其它工具的键名
+
+#### Scenario: Guidance lives and dies with the tool
+
+- **WHEN** a session's scope excludes the `eval` tool
+- **THEN** 任何地方都不渲染 REPL 指引（指引即工具自身的 description）；`eval` 在场时指引必然在场
+
+#### Scenario: Alias annotation present
+
+- **WHEN** the model reads the `eval` description
+- **THEN** it states that `subagent` is an alias of the `agent` delegation tool，两者经同一 runtime delegate
+
+#### Scenario: Non-flat exception present
+
+- **WHEN** the model reads the `eval` description
+- **THEN** it states that 含非标识符字符（如连字符）的工具名没有 `tool.<name>` member，必须以 direct tool call 调用
+
+### Requirement: Masking failures surface loudly
+
+The system SHALL surface a structured error, not a silent skip, when restricting any masked tool name fails at session start；application 完成后 mask SHALL verify 每个 masked 名在 **the wire tools array 与 the REPL bindings** 中均不存在。
+
+#### Scenario: A masked name's restriction errors and the session reports it
+
+- **WHEN** applying the mask, a single masked name's registry restriction throws
+- **THEN** the session surfaces the failure as a structured error naming the masked tool, and the name does not silently remain on any model-facing surface
+
+#### Scenario: Masked names absent after successful application
+
+- **WHEN** an agent session starts under DASHR with a healthy registry
+- **THEN** the wire tools array 与 the REPL bindings contain none of the masked names（`skill`、`send_message`、`report`、`list_agents`、`subagent_fork`、`interrupt_agent`、`workflow`、`ralph`），and a call naming a masked tool returns `UNKNOWN_TOOL`
+
+### Requirement: REPL bindings bridge the visible registry mechanically
+The system SHALL install REPL bindings by automatic, transparent conversion of every flat-bindable name in the registry's visible set at session start — no manual allowlist or denylist; masked names are naturally absent because the binding source and the masking act on the same projection. Non-flat names SHALL be skipped — a name is non-flat when it contains characters outside `[A-Za-z0-9_]` (e.g. hyphens); a `__` infix alone is a legal identifier and does not by itself make a name non-flat — and the bridge instructions SHALL state the name-shape limitation without enumerating affected tools.
+
+#### Scenario: A newly registered host tool appears in the REPL without list edits
+- **WHEN** the host registers a new flat-named tool after a DASHR upgrade
+- **THEN** the next agent session exposes it as `tool.<name>` with no DASHR source change
+
+#### Scenario: Non-flat MCP names documented, not listed
+- **WHEN** an MCP tool named `mcp__server__tool-name` is registered
+- **THEN** no binding is created for it, and the bridge instructions explain the name-shape limitation
+
+#### Scenario: Double-underscore infix alone stays bindable
+- **WHEN** a tool named `mcp__server__tool` (identifier characters only, no hyphen) is registered
+- **THEN** the name is flat-bindable (`'mcp__server__tool'.isidentifier()` is true) and appears as `tool.<name>` unless separately masked
+
+### Requirement: llm_completion tool
+The system SHALL provide an `llm_completion` tool: a one-shot, stateless LLM call — no tools, no conversation history, no agent creation. Inputs: `{ prompt, system?, maxTokens? }`; output: the model's text. The call SHALL be attributed to the calling agent's session through the normal tool-call audit (the host's auxiliary-purpose enum is closed and carries no completion class), SHALL honor the caller's abort signal, and SHALL resolve its model route from the calling agent's current model selection, and SHALL answer a structured error value — never a silent fallback route — when no selection is available. A finish other than a clean stop, or any tool-call block in the output, SHALL produce a structured error value, not a thrown exception.
+
+#### Scenario: Zero-spawn judge step inside a cell
+- **WHEN** a cell calls `await tool.llm_completion({ prompt: "<judge prompt>", system: "<rubric>" })`
+- **THEN** the value returned is the model's text; no subagent is spawned, no session besides the caller's is created, and the call is auditable under its own purpose
+
+#### Scenario: Model route follows the caller
+- **WHEN** the calling agent's selected model differs from the host default
+- **THEN** the completion runs on the caller's selection
+
+#### Scenario: Degraded finish is a structured error
+- **WHEN** the completion hits maxTokens or aborts
+- **THEN** the tool returns `{ error: <description> }` rather than throwing
+
+### Requirement: REPL tool namespace introspection
+The system SHALL make the REPL `tool` namespace introspectable: `dir(tool)` returns the sorted list of bound tool names — exactly the names callable as `tool.<name>(argsObject)`. The underlying injected mapping (e.g. `__dashr_injected__`) remains unchanged for compatibility; `dir()` is the documented introspection surface.
+
+#### Scenario: dir(tool) lists the binding set
+- **WHEN** a cell runs `dir(tool)`
+- **THEN** the returned list equals the sorted set of names bound in the `tool` namespace for that run (dunder members aside), including the delegation bridges and `llm_completion`
+
+### Requirement: Hashline edit family registered on the agent's own layer
+
+The system SHALL register the vendored hashline edit family on each agent's own scope layer at session start — `edit` (hash-anchored ordered edit tuples, shadowing the preset's built-in edit by nearest-layer resolution, no mask entry needed) and `undo_last_edit` (revert of the most recent hashline edit) — alongside the URL-aware read/write/grep/glob wrappers, unwinding with the agent. The write tool SHALL remain the upstream full-file write with its native confirmation envelope: no hook SHALL append a hashline preview to write results, and the hashline guidance SHALL NOT promise post-write anchors (the model MAY edit directly using anchors derived from the content it just wrote, or read first). The hashline guidance sections SHALL shadow the preset's built-in tool guidance on the same layer (compiled defaults when no agentPresets service or a failing override — never a failed install).
+
+#### Scenario: A hash-anchored edit lands and is reversible
+
+- **WHEN** the model calls `edit` with anchored edit tuples on a file whose current content matches the anchors
+- **THEN** the edit applies atomically (drift-checked against current content), and a subsequent `undo_last_edit` reverts it
+
+#### Scenario: A write result stays upstream-native
+
+- **WHEN** the model calls `write` and it succeeds
+- **THEN** the result content is the upstream confirmation envelope with no auto-read/anchor section appended, and no read is required before the next anchored `edit` on that file
+
+#### Scenario: The shadow replaces the built-in edit without masking
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** the `edit` the model sees is the hashline tool (own-layer shadow), the preset's built-in edit is unreachable for that agent, and no deny-list entry names `edit`
+
+### Requirement: Lsp feedback rides edit results
+The system SHALL attach the same write-feedback diagnostics contract to successful edits: after a landed `edit` with an explicit path, the result content carries the diagnostics summary computed from the exact landed content (didSave freshness, timeout degradation, span guard — the `dvc` write-feedback requirement's terms apply verbatim). Anchor-only edits (path inferred from anchors) and non-edit tools pass through untouched; the write tool's feedback stays with its wrapper (no double pull).
+
+#### Scenario: An edit that introduces a type error reports it
+- **WHEN** an edit lands content introducing a type error in a file with a language server and its check completes within the budget
+- **THEN** the edit result text carries the diagnostics summary for the exact landed content
+
+### Requirement: Hashline edit verification is content-anchored
+
+The system SHALL verify each edit tuple's anchors against the CURRENT file content before consulting any ledger: an anchor SHALL be accepted when its hash locates a unique, consistently pairable position in the current canonical line hashes; the served ledger SHALL be advisory (echo/undo attribution) and keyed by canonical absolute path with no session identity, so anchors survive session-tree forks and continuation without a re-read. Genuine drift SHALL still fail closed with nothing written, batch atomicity SHALL be unchanged, and a multi-tuple batch failure SHALL instruct reading the file once and resubmitting the whole batch.
+
+#### Scenario: An edit across a forked session lands without a re-read
+
+- **WHEN** a file is written or read in one session node, the conversation continues in a forked node (new session identity), and the model submits anchored edit tuples derived from that earlier content
+- **THEN** the edit applies without any intervening `read`, because verification matched current content
+
+#### Scenario: A drifted line still fails closed
+
+- **WHEN** an anchor's hash no longer exists in the current file (content changed or line removed externally)
+- **THEN** the tuple is rejected with a drift error stating the content changed and a read is needed, and nothing is written
+
+#### Scenario: An ambiguous anchor falls back before failing
+
+- **WHEN** an anchor's hash occurs at multiple current positions and the served ledger cannot disambiguate the span
+- **THEN** the tuple is rejected with nothing written, and the error names the ambiguity
+
+#### Scenario: Multi-tuple failure copy is actionable
+
+- **WHEN** any tuple in a multi-tuple batch fails verification
+- **THEN** the batch aborts with zero writes and the error instructs reading the file once, then resubmitting the whole batch
+
+### Requirement: Hashline store centralized under DSH_HOME
+
+The hashline store SHALL live at a single location — `$DSH_HOME/storages/dsh-better-edit/hash-store.sqlite` — for tool calls, previews, and tests alike, resolved through the harness home resolver so `DSH_HOME` isolates deployments; no per-workspace dot-directory SHALL be created. The served table SHALL be keyed by canonical absolute path (no session column), the 7-day TTL prune SHALL be retained, and the store schema version SHALL bump with a rebuild-on-mismatch gate that drops and recreates legacy session-keyed served tables.
+
+#### Scenario: No dot-directory is created
+
+- **WHEN** hashline tools run inside any workspace
+- **THEN** state lands in the centralized store and no `<workspace>/.dsh_better_edit/` directory is created
+
+#### Scenario: DSH_HOME isolates deployments
+
+- **WHEN** the harness runs with a test `DSH_HOME` (e.g. the 4999 line)
+- **THEN** its hashline store is a separate file under that home and never touches the production store
+
+#### Scenario: Legacy session-keyed served tables rebuild
+
+- **WHEN** the store opens with a schema version below the current one, or a served table still carrying a `session_id` column
+- **THEN** the served table is dropped and recreated with the path-keyed schema, and the version marker is updated

package/node_modules/better-dsh/docs/20_specs/url-schema/spec.md

@@ -0,0 +1,148 @@
+# url-schema Specification
+
+## Purpose
+
+Give DASHR one uniform URL resource-addressing layer: read/write/grep/glob accept `scheme://` URLs, route by scheme to a handler, apply one selector syntax uniformly, and keep non-URL behavior byte-identical to the native tools via delegation.
+
+## Requirements
+
+### Requirement: FS-shaped tools accept and route scheme URLs
+The scheme registry SHALL be owned by the `dsh-url-schemes` cordis service (renamed from `dsh-url-schema`), which SHALL contain the `UrlResolver` and scheme handlers only (no tool registrations inside the service). The URL-aware read/write/grep/glob tools SHALL be tool-layer consumers. read SHALL accept `scheme://` URLs and resolve them end-to-end through the scheme registry; grep/glob SHALL translate or materialize the resource for the native search; write SHALL dispatch to a structured per-scheme write channel (all rejected this wave).
+
+#### Scenario: Reading a registered scheme
+- **WHEN** the model calls read with a registered scheme URL (e.g. `skill://foo`)
+- **THEN** the system returns the handler-resolved content with the selector applied, not a filesystem read
+
+#### Scenario: Reading an unregistered scheme
+- **WHEN** the model calls read with a URL whose scheme has no registered handler (including `history://` — no special case exists)
+- **THEN** the system returns the structured `URL_UNREGISTERED_SCHEME` error listing the registered schemes
+
+#### Scenario: URL without a scheme prefix
+- **WHEN** a resolver-layer caller passes a string without `scheme://`
+- **THEN** the system returns the structured `URL_NO_SCHEME` error
+
+### Requirement: `dsh://docs` serves the vendored upstream official docs
+`dsh://docs` SHALL serve the shipped upstream official harness documentation corpus (`dsh-docs/`, vendored from the `deepseek-ai/deepseek-harness` repo `docs/`), not the DASHR repository's working notes. Resolution order: explicit `docsDir` → packaged `dsh-docs/` → packaged `docs/` → repo-root `docs/` (walk-up probes `dsh-docs` before `docs` at every level).
+
+#### Scenario: Docs index lists the official corpus
+- **WHEN** the model reads `dsh://docs`
+- **THEN** the index enumerates the upstream official docs tree (`agent-lifecycle.md`, `api-gateway.md`, `architecture.md`, …)
+
+### Requirement: Bare `skill://` lists the available skills
+A bare `skill://` URL (no skill name) SHALL render the cwd-scoped skill catalog from the registry's `list` face — one line per winning summary (`skill://<name> — <description>`, plus `(use when: …)` when `whenToUse` is present) — using the same discovery rule as a name lookup. An empty catalog SHALL answer explicitly, never with an error.
+
+#### Scenario: Bare skill list
+- **WHEN** the model reads `skill://` with no skill name
+- **THEN** the tool result contains the count header and per-skill lines, cwd-scoped exactly like `skill://<name>` resolution
+
+#### Scenario: Empty catalog
+- **WHEN** no skill is available in the workspace scope
+- **THEN** the result reads "No skills available in this workspace scope." — not a `URL_SKILL_NOT_FOUND` error
+
+### Requirement: Delegation shells preserve native non-URL behavior
+The system SHALL implement read/write/grep/glob as delegation shells over the definition registered under the same semantic name at capture time, captured once per agent via `ctx.tools.get(name, agent)` strictly before the wrappers register on the agent's own scope layer (`read` included — its captured delegate MAY be another feature's wrapper). Non-URL inputs SHALL be forwarded verbatim to `captured.execute(args, exec)`, preserving the native write-intent policy gate, sandbox resolution, ripgrep search semantics, and any outer-layer behavior already present. The shells SHALL honor per-feature config gates `Config = { urlSchemes?: boolean = true, hashline?: boolean = true }` from the patch-line `config:` block: with `urlSchemes: false`, scheme paths SHALL fall through to the captured definition (native failure semantics are honest); with `hashline: false`, file reads SHALL delegate without hashline anchoring.
+
+#### Scenario: Ordinary write keeps the policy gate
+- **WHEN** the model writes to an ordinary file path
+- **THEN** the call runs through the captured native write definition — the write-intent policy gate, sandbox resolution, and observation events behave exactly as before the URL schema existed
+
+#### Scenario: Ordinary grep/glob keep ripgrep semantics
+- **WHEN** the model greps or globs over ordinary paths
+- **THEN** the call delegates to the captured native definition with args untouched, returning native-shaped results
+
+#### Scenario: Missing native delegate fails loudly
+- **WHEN** a host did not deploy the native write/grep/glob and the corresponding wrapper is invoked on a non-URL input
+- **THEN** the system returns the structured `NATIVE_WRITE_UNAVAILABLE` / `NATIVE_GREP_UNAVAILABLE` / `NATIVE_GLOB_UNAVAILABLE` error instead of reimplementing the tool
+
+#### Scenario: Capture happens before registration
+- **WHEN** an agent session starts and the URL-aware tools are installed
+- **THEN** the definitions under `read`/`write`/`grep`/`glob` are captured strictly before any wrapper registers on that agent's scope layer, so the captured reference is the pre-existing tool rather than the wrapper (no self-recursion)
+
+#### Scenario: URL capability disabled by gate
+- **WHEN** the patch line sets `urlSchemes: false` and the model reads `ctx://session`
+- **THEN** the wrapper delegates to the captured read definition and the native failure surfaces
+
+### Requirement: URL search reuses the native engine
+The system SHALL run grep/glob over URL-addressed resources through the native search engine: path-backed schemes (a handler-implemented `resolvePath` mapping the URL to a real disk location — `skill://` today) have the URL translated to the disk path before delegating; content-backed schemes (agent, ctx, `dsh://config`, http, …) have the resolved text materialized into a fresh RAM-backed tempfs directory (`/dev/shm` when available and writable; falling back to the OS temp dir when unavailable or when a single materialization exceeds 8 MiB) which is removed afterwards whatever the outcome.
+
+#### Scenario: Searching a path-backed resource
+- **WHEN** the model greps a `skill://name` URL
+- **THEN** the URL is translated to the skill's real disk path and only the search root is rewritten before the native grep runs
+
+#### Scenario: Searching a content-backed resource
+- **WHEN** the model greps a content-backed URL (e.g. `ctx://model`)
+- **THEN** the resolved text is written into a fresh temp dir under `/dev/shm` (or the OS temp dir on fallback) as `content.txt`, the native grep searches it, and the temp dir is removed whether the search succeeds or fails
+
+#### Scenario: Listing a URL resource
+- **WHEN** the model calls glob with a URL in `pattern`
+- **THEN** a path-backed scheme globs the resource's real disk directory natively, and a content-backed scheme returns the resolved text's non-empty lines as the listing without a native call
+
+#### Scenario: Glob metacharacters in a URL pattern
+- **WHEN** the glob pattern is a URL carrying glob metacharacters (e.g. `skill://grp/*`, `skill://grp/**/*.md`)
+- **THEN** the pattern splits at the first metacharacter (`*?[`): the URL part resolves via `resolvePath` and the tail is the rooted glob pattern applied WITHIN the resource's real disk directory — the raw metachar-containing string is never handed to the native engine as a literal path
+
+#### Scenario: Grep match paths report URL addressing
+- **WHEN** a grep over a path-backed URL returns matches
+- **THEN** match paths are rewritten back to the URL form (`skill://grp/SKILL.md`), both for absolute paths under the disk root and for native-relative paths — the model never sees internal disk locations
+
+#### Scenario: Fallback to the OS temp dir
+- **WHEN** `/dev/shm` is unavailable or the content exceeds 8 MiB
+- **THEN** materialization falls back to the OS temp dir and the search still completes
+
+### Requirement: URL writes are rejected per scheme
+The system SHALL reject every `scheme://` write with a scheme-specific structured error: `dvc://` → `DVC_NO_DEVICE` (no device mounted), `ctx://` → `URL_READ_ONLY` (curated read-only snapshot), any other registered scheme → `URL_WRITE_UNSUPPORTED`, unregistered scheme → `URL_UNREGISTERED_SCHEME`.
+
+#### Scenario: Writing to a read-only scheme
+- **WHEN** the model writes to `ctx://model`
+- **THEN** the system returns the structured `URL_READ_ONLY` error explaining the scheme is a read-only snapshot
+
+#### Scenario: Writing to the device placeholder
+- **WHEN** the model writes to `dvc://<device>`
+- **THEN** the system returns the structured `DVC_NO_DEVICE` error (no devices mounted to route the write to)
+
+### Requirement: Unified selector syntax
+The system SHALL parse selectors once (`:N-M` comma-lists, `:raw`, `:path/…`, `?q=`) and apply them uniformly to every handler's full text after resolution. Handlers return full text with no default line truncation; only explicit selectors page. Malformed selectors return the structured `URL_BAD_SELECTOR` error.
+
+#### Scenario: Scheme URL with a line range
+- **WHEN** the model reads `skill://foo:50-100`
+- **THEN** the system resolves the full skill body and returns lines 50–100, exactly as it would slice a plain file
+
+#### Scenario: JSON path and query selectors
+- **WHEN** the resolved text is JSON and the URL carries `:path/a.b` or `?q=a.b`
+- **THEN** the system navigates the JSON by dot-path; for non-JSON text `?q=` keeps the lines containing the query string
+
+### Requirement: Read delegation shapes args to the delegate and coerces output
+The URL-aware read wrapper SHALL accept both `path` and `file_path` (aliased); when delegating a non-scheme path it SHALL shape args to the delegate's DECLARED parameters (`file_path` for the host-native read, `path` for hashline; opaque schemas forwarded verbatim — no keys added an unknown validator might reject) and SHALL coerce a non-string delegate result to the wrapper's string output (JSON serialization), since the wrapper declares the string face for every branch.
+
+#### Scenario: Host-native delegate receives file_path
+- **WHEN** a file path is delegated to a delegate whose schema declares `file_path`
+- **THEN** the delegate receives `file_path` (the `path` key removed) and its structured result is serialized into the wrapper's string output
+
+#### Scenario: Hashline delegate receives path
+- **WHEN** a file path is delegated to the hashline read (schema declares `path`)
+- **THEN** the delegate receives `path` only and the anchored text returns verbatim
+
+### Requirement: read's file branch stays vendored hashline
+The system SHALL keep the ordinary-file branch of read on the vendored hashline pipeline (HASH│content anchors plus the snapshot store the vendored edit tools depend on), reading through the sandboxed filesystem and the fs observation policy gate — read delegates to no native definition.
+
+#### Scenario: Plain file read returns hashline anchors
+- **WHEN** the model reads an ordinary file path
+- **THEN** the system returns hashline-anchored lines via the vendored pipeline and records the observation with the fs policy gate, so follow-up edit calls see the version just read
+
+### Requirement: Read chassis with ordered transforms
+The `read` tool registration SHALL be owned by a single chassis inside `dsh-url-schemes`: an ordered transform chain (URL transform, hashline anchor transform, …) with a terminal delegate to the captured read definition. Additional read-side features SHALL register transforms into the chassis rather than registering competing `read` definitions (same-layer same-name registration is a registry error); a read-interested feature SHALL fall back to its own minimal wrapper only when the chassis is absent.
+
+#### Scenario: Transforms compose deterministically
+- **WHEN** both the URL transform and the hashline anchor transform are registered and the model reads a filesystem path
+- **THEN** the path flows URL transform (no match) → anchor transform (anchors applied) → captured native read
+
+### Requirement: General syntax guidance section
+The service SHALL render a gated `url-schema:general` system-prompt section whose text is loaded once at module load from the package-root `url-schemes-instruction.md` (the owner-maintained instruction file; shipped via the package.json `files` array — an unlisted file is omitted from the published package and the module-load `readFileSync` fails plugin boot, the 0.2.3-d ENOENT lesson) (shipped via the package.json `files` array — an unlisted file is omitted from the published package and the module-load `readFileSync` fails plugin boot, the 0.2.3-d ENOENT lesson). The section is the SINGLE surfacing point of the URL scheme set to the model: the read/grep/glob/write tool descriptions SHALL carry NO `scheme://` mentions, so the model cannot believe only some tools accept URLs. The section text is the OWNER-MAINTAINED file rendered verbatim (2026-09-12 ruling: the file is hand-edited, not generated) and SHALL cover at minimum: the general URL grammar (`scheme://<path>[:selector]`); all six schemes (`skill://`, `agent://`, `dsh://`, `ctx://`, `dvc://`, `http(s)://`) with first-level resource coverage per scheme; the selector set including the composite `:raw:N-M` clause; and bulk-read guidance. The section renders only while the URL capability is enabled.
+
+#### Scenario: Gated disclosure
+- **WHEN** the URL capability is enabled and an agent session starts
+- **THEN** the system prompt contains the section text loaded from `url-schemes-instruction.md` with the grammar, selector, and scheme coverage
+
+#### Scenario: Tool descriptions stay scheme-silent
+- **WHEN** the model inspects any read/grep/glob/write tool description on the wire
+- **THEN** no description carries a `scheme://` mention — the `url-schema:general` section is the only place the scheme set is surfaced

package/node_modules/better-dsh/docs/20_specs/web-trust-fence/spec.md

@@ -0,0 +1,43 @@
+# web-trust-fence Specification
+
+## Purpose
+better-dsh 的 /api 信任栅栏随发契约（替代 prod 手改 patch）：bundle patch 整行重述 `connection` 行，`trustedHosts` = `DSH_TRUSTED_HOSTS` env 条目 + 上游 webRuntime 权威拼接（env 缺省时行为与原装行等价、零侵入）；host 半 boot script 的 isLoopback 腿——页面 origin 命中 `trustedPageAuthorities` 时置 `window.__DSH_TRANSPORT__ = { ownsHost: true }`（空列表不注入）。
+
+## Requirements
+
+### Requirement: Plugin-shipped fence authorities
+
+The plugin's bundle patch layer SHALL override the `connection` loader row by id, restating the row's full shape, with `config.trustedHosts` computed as the concatenation of `DSH_TRUSTED_HOSTS` environment entries (whitespace-separated) and the upstream `webRuntime`-derived authorities; with the environment variable unset or empty the resulting composition SHALL be byte-equivalent in behavior to the unpatched upstream row (inert by default).
+
+#### Scenario: Env-derived authority passes the fence
+
+- **WHEN** the daemon runs with `DSH_TRUSTED_HOSTS=host.example` and a browser reaches `/api` with `Host: host.example` and same-origin markers
+- **THEN** the request passes the Host/Origin trust fence (no 403 from the fence) and the Settings > Models provider directory loads from that authority
+
+#### Scenario: Inert without the environment variable
+
+- **WHEN** the daemon runs without `DSH_TRUSTED_HOSTS`
+- **THEN** the fence accepts exactly the authorities the unpatched upstream composition would (loopback, LAN literals on all-interface binds, `--trusted-host` extras)
+
+#### Scenario: Malformed entry fails loud at load
+
+- **WHEN** `DSH_TRUSTED_HOSTS` contains an entry that is not a bare canonical `host[:port]` authority
+- **THEN** plugin load fails loudly via the upstream `assertTrustedAuthority` validation instead of silently widening or narrowing the fence
+
+### Requirement: Upgrade-safe replacement of the hand patch
+
+The plugin SHALL NOT require source-level edits to vendored `@deepseek-ai/*` files for fence behavior; the alpha.3 hand patch (`isLoopbackHostname` widening in `dsh-client-connection` index.js and client bundle) SHALL be retirable on alpha.5+ by this capability alone, and the row-override shape SHALL be tracked as an upstream-alignment checklist item (diff `packages/bundle/web-app/cordis.patch.yml`'s `connection` row each alignment round).
+
+#### Scenario: Upstream row drift is detected at alignment time
+
+- **WHEN** an upstream release changes the `connection` row's keys (name, inject, or config shape)
+- **THEN** the alignment-round checklist surfaces the drift before the stale restated row ships
+
+### Requirement: User layer keeps precedence
+
+A user's own profile or home `cordis.patch.yml` override of the `connection` row SHALL take precedence over the plugin's bundle layer, preserving the upstream layering contract.
+
+#### Scenario: User override wins
+
+- **WHEN** the user's profile patch restates the `connection` row
+- **THEN** the user's row applies, not the plugin's

package/node_modules/better-dsh/docs/50_test-reports/2026-09-06-write/345/267/245/345/205/267sandbox/345/215/207/347/272/247/351/200/217/344/274/240bug/345/244/215/345/217/221/345/217/212/346/214/202/350/265/267-/344/272/213/344/273/266/346/212/245/345/221/212.md

@@ -0,0 +1,176 @@
+# 事件报告：write 工具 sandbox 升级透传 bug（复发 + 新失败模式：调用挂起）
+
+> 日期：2026-09-06 · 环境：DSH v0.1.2-alpha 线（prod 3080 / Web GUI），session 模型 GLM，
+> file policy = workspace-write（workspace：`/home/u1/workspaces/dashr`），approval policy = ask。
+> 前置记录：2026-09-03 edit 工具同类 bug（session `8e966430`，"hashline edit escalation
+> passthrough bug"；dashr 插件侧修复 commit `e27fdec` + 报告 follow-up `419ca0e`——该修复仅覆盖
+> vendored hashline edit 路径，本次 write 工具复发说明 harness 层文件工具透传问题未除根）。
+
+## 场景
+
+向 workspace 之外写文件：`/home/u1/workspaces/superd/docs/00-blueprint.md`（Super D 蓝图，
+新建同级仓）。workspace-write 模式下首次尝试即被拒（`Read-only file system` / file access denied），
+按规则走单次 `sandbox_permissions` 升级重试。
+
+## 失败 1（已知 bug 复发）：write 的升级字段被丢弃
+
+首次 `write` 调用携带 `sandbox_permissions: "danger-full-access"` + justification，直接返回
+`[sandbox: file access denied under workspace-write mode]`——**未弹出任何审批卡片**，升级字段
+疑似在 harness 透传层被丢弃。与 2026-09-03 记录的 edit 工具症状同类：**文件类工具（write/edit）
+的 sandbox_permissions 透传失效，bash 工具的升级正常**。
+
+## 失败 2（新失败模式，更严重）：升级后的 write 调用挂起至手动停止
+
+agent 推理链（UI 可见）：此前一次 bash 升级到 workspace-write 被拒，报错提示"升级必须严格宽于
+当前模式"（当前已是 workspace-write）；据此判断应改用 danger-full-access 重试 `write`。
+该重试调用**表面上已发出，但此后 >5 分钟 agent 无任何活动**——非响应/挂起。用户在 UI 按
+"stop" 并发新 prompt 才恢复。
+
+即：升级版 write 不仅没有触发审批提示，还把整个 turn 挂死直到手动中断。两种可能根因待查：
+(a) 审批提示从未渲染（透传丢失后 promise 悬空）；(b) 调用 promise 永不 settle。
+
+## 有效的 workaround
+
+`bash` heredoc + `sandbox_permissions: "danger-full-access"` —— bash 的升级链路正常，审批弹出、
+批准后写入成功（superd 仓蓝图 + git commit `1c1969a` 均经此路径完成）。
+
+## 建议
+
+1. **修复前**：跨 workspace 文件写入一律走 bash heredoc + 升级，不用 write/edit 的升级。
+2. **根因排查**：write/edit 的 sandbox_permissions 透传丢失点（harness 文件工具包装层）；
+   以及挂起问题——需区分"审批提示未渲染"与"promise 未 settle"，二者修法不同。
+3. 回归范围：至少覆盖 write / edit / undo_last_edit 三个文件工具 × workspace-write 与
+   read-only 两种基线模式下的升级路径。
+
+## 同日复测（本地 Web GUI）：write 升级链路实测通过
+
+> 环境差异：prod 3080 / GLM → 本地 Web GUI（127.0.0.1:4999）/ deepseek-v4-flash；
+> file policy = workspace-write（workspace：`/home/u1/workspaces/temp`），approval policy = ask。
+> 测试目标（workspace 之外）：`/home/u1/workspaces/base/.scratch/dsh_ws_test.txt`
+
+### 实测记录
+
+1. **基线越界 write → 立即被拒，无审批卡**：
+   `[sandbox: file access denied under workspace-write mode]`
+   且拒绝消息自带第二行 affordance 提示（本轮行为的关键信号源）：
+   `[sandbox: escalation available — retry this exact operation once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`
+2. **单次升级重试**：`sandbox_permissions: "danger-full-access"` + justification → 返回
+   `Created`（审批通过），未再出现 denial；磁盘校验 `-rw------- 1 u1 u1 26`，内容
+   `test write from dsh agent`。
+3. 全程**无挂起、无字段丢弃、无静默失败**。
+
+**结论**：本地构建上 write 升级链路（字段透传 → 审批渲染 → promise settle）实测通过，与 prod 3080
+报告的「字段丢弃 + 挂起」复发症状不一致 → 缺陷疑为环境/构建相关（或已被修复）。建议按上文
+「建议 3」在 prod 3080 上回归 write / edit / undo_last_edit × workspace-write 与 read-only 基线。
+
+## 附 A：escalation 提示机制的优化（reminder 文案）
+
+同一机制在 system prompt 中至少出现三处，语义同一但角色不同：
+① 工具 schema 参数声明（affordance / API 表面，只声明字段存在）；
+② policy 规则段（procedure：何时、怎么用 + 大量禁令）；
+③ runtime-context 快照补充句（情境重启，位于每次 turn 顶部、工具调用前最后读到的位置）。
+
+本轮讨论聚焦③的措辞。现文：
+
+> Restricted operations may be retried once with sandbox_permissions for single-call escalation,
+> pending user approval.
+
+对字面论 / 风险厌恶型模型，存在两种可被误读的推理路径：
+
+(a) **配额式误读**：「once」被理解为一次性越权许可——只能带 escalation 请求一次；若首次升级被
+user deny，模型可能推断整个机制已耗尽、连后续命令也不再尝试升级。但 runtime **无状态**：不记录某
+命令是否已 escalate / 被 deny，系统不存在这类配额。
+(b) **ask-first 误读**：「pending user approval」被读成先征得批准再 retry，与 policy 的
+「don\'t detour through chat — the retry itself raises the approval prompt」相悖。
+
+「once」的字面语义与真实策略（单次 retry）并不冲突；歧义在于**未声明机制的 per-call / 无状态属性**，
+而该属性正是阻止 (a) 误读的关键事实。因此措辞应从「配额式」改为「机制式」，显式声明：per-call、
+无配额记录、审批由 retry 自动触发、单次 deny 只作用于该 call。
+
+**定稿（同日终版，替换③；上文「主推 / 短变体」作废）**：
+
+> A sandbox-deniable/denied call may be escalated with `sandbox_permissions="danger-full-access"` and a
+> one-line `justification`; the runtime will prompt for user approval. Escalation and its
+> approval/denial are per-call.
+
+双词并列**中立覆盖两条路径**：`deniable`——读到本段、且按 policy 可演绎判定为越界的调用（workspace +
+temporary 之外）直接升级，不做 doomed 往返；`denied`——未注意本段、已被拒的调用同样可升级。全文无
+retry / once / 配额措辞。安全边界是**双重硬 guard**：sandbox（policy 判定）+ user approval（审批卡）；
+预升级至多多弹一张可拒审批卡，无实害，「等审批」的心理摩擦天然抑制滥用。`danger-full-access` 经源码
+核对（`escalation.ts` `WIDER_MODES`：workspace-write → [danger-full-access]，且本句仅在该模式下渲染），
+参数名与 justification 单句配对均与 schema 一致。
+
+**具体 example（agent 视角最小推演）**：
+
+```
+#1  write(workspace 外路径)                          → denied（无审批，返回 marker + affordance 行）
+#2  write(同路径, sandbox_permissions="danger-full-access", justification="…")   → 弹审批卡
+    user 点 deny
+    → 语义：该 call 就此结束（stop and explain），≠ 「escalation 机制已耗尽」
+#3  稍后另一条命令被拒 → 仍可走同一升级路径（per-call，runtime 无配额记录）
+    ✗ 错误推理：#2 被 deny ⇒ 我不能再发起任何 escalation
+```
+
+**配套建议**：
+
+- ②policy 段的关键句（rejected = final for that command，但不禁止后续命令升级）与③措辞需锁死一致，
+  避免三处漂移；
+- 最强一层是**环境内信号**：denial 消息自带 affordance 行（本轮实测可见，现构建已带）。它零 token、
+  位置恰好、不可能被 attention 漏掉；应作为固定格式保留，并让提示中的 mode / 参数名与消息完全一致。
+
+## 附 B：保留并补充该 reminder 的必要性（语态 / 效价问题）
+
+系统 prompt 原本已含等价语义（②policy 段），但该段 **permission 密度低、被高强度禁令包围**
+（Do not detour… / Never escalate speculatively / A rejected escalation is final / no exception /
+a denial is final）。LLM 对禁令性词语的权重显著高于许可性陈述；风险厌恶型模型读后的净效价收敛为
+「escalation 是高风险的非常规动作，能避则避」——这为观测到的「静默失败」（denial 后直接放弃、从不
+尝试升级）提供了行为学解释：**这不是注意力丢失，而是语态 / 效价问题**。
+
+③是全文唯一「零否定、纯许可」的 escalation 表述，且位于 turn 顶部快照（决策前最后读到）→ 命题上
+与②重复，但功能上不冗余：它承载 **grant（放行）**，②承载 **procedure（程序 + 禁令）**。本轮复测中
+agent 在 denial 后正确、立即升级，除错误消息 affordance 外，③的纯许可语态是「敢试」的直接依据。
+
+结论：③应保留并按附 A 修正措辞；不要在静态 prompt 中继续增加第四处副本（边际收益到顶），后续投资
+应放在 denial 消息的 affordance 质量（直接给出该传的 mode）。
+
+## 附 C（新发现 · 待修）：rules 段「escalating up front is fine only when this session already denied the same access」自相矛盾
+
+> 追加于定稿同日；定位为文本漂移，修复另行排期，本轮未改动任何源码。
+
+**归属结论（同日追查）**：该子句位于**上游** DSH v0.1.2-alpha.5 源码——本 checkout 即
+github.com/deepseek-ai/deepseek-harness 的浅克隆（HEAD `db6bdc3576`，唯一 remote 为上游
+origin）；`packages/shell/tool-bash/src/index.ts:89` 与 `packages/shell/tool-pwsh/src/index.ts:140`
+均经 `git ls-files` 确认是上游跟踪文件。blame 止于 `47f943859b`（2026-08-13，上游 PR #2519
+merge）系浅克隆边界，真实引入 commit 更早、被截断。对照：刚定稿的快照句（dashr:escalation-
+guidance，`packages/better-dsh/better-dsh/src/index.ts`）属 Better Dash（repo：pgmi-builds/
+better-dsh），在上游 tree 内为 untracked（`??`）叠层。**修复含义**：改矛盾句 = 改上游跟踪
+文件，不能直接 commit 进本 checkout；两条路——上游 PR，或在 better-dsh 的 prompt 装配层覆盖
+订正 bash/pwsh 工具描述（与 dashr:escalation-guidance 同款注入方式）。
+
+**自相矛盾分析**：按字面语义，「escalating up front」（未尝试即升级）与「already denied the
+same access」（已尝试且被拒，同一 access）互斥——后者成立则前者必然不成立，条件永远无法满足。
+属两条规则被硬拼成一句的编辑事故。**推断的原意**：同一 access 已被本 session 拒绝过一次之后，
+再次需要时不必重发 doomed 调用、可直接升级（豁免重复往返）——但这层豁免语义句子本身没写出来。
+
+**事实核对（源码）**：
+
+- 该子句仅存在于两处模型可见的工具描述：`packages/shell/tool-bash/src/index.ts:89`、
+  `packages/shell/tool-pwsh/src/index.ts:140`；并随描述文本进入 35 个
+  `snapshots/**/tool-schemas*.expected.json` 快照（随源重生成，不需手改）。
+- 同策略的文档版本（tool-bash / tool-pwsh 的 README.md 与 README.zh.md）**均无此子句**
+  （0 命中）——同一策略在工具描述与文档中本就是两个版本（次级漂移）。
+- runtime 无 prior-denial 状态：`approveEscalation`（`packages/sandbox/sandbox/src/escalation.ts`）
+  只有三道闸——参数配对、严格更宽（`WIDER_MODES`）、审批通道。文档所称
+  「a request with no real prior denial … fails closed」在代码中并未实现为状态检查；
+  该子句纯属 prompt 层规范。
+
+**与本轮定稿的关系**：附 A 定稿（快照句）规定 deniable（policy 可演绎判定越界）调用可直接升级；
+本子句规定 upfront 升级仅在 same-access 已 denied 后才允许——同一动作两个触发定义，且其中之一
+自相矛盾。rules 段禁令权重高（见附 B 效价分析），模型大概率取 deny-first 读法，与快照句的
+deniable 路径持续张力。
+
+**修复方向（未实施，待排期）**：把豁免语义显式化，例如「once this session has already denied
+the same access, you may escalate again without re-firing the doomed call」；或与 deniable 原则
+统一为「policy 可演绎判定将被拒的调用可直接升级」。需同步：tool-bash / tool-pwsh 工具描述 ×2、
+README ×2（en/zh 一并对齐）、35 个快照重生成；并与 deniable/denied 的 deny-first vs 预判升级
+产品决策对齐后再动。