super-dsh 0.3.0-a → 0.3.0-d

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

@@ -1,222 +0,0 @@
-# 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/specs/url-schema/spec.md

@@ -1,148 +0,0 @@
-# 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/specs/web-trust-fence/spec.md

@@ -1,43 +0,0 @@
-# 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/specs/welcome-self-contained/spec.md

@@ -1,13 +0,0 @@
-# Super Dash 自包含 Better Dash 与 DSH 默认策略
-
-2026-10-07 user 裁决：两仓物理独立；Super Dash 每次打包都构建兄弟仓当前 Better Dash 源码，内嵌本地实际产物，不从 registry 取 Better Dash；WebTrust、dev WebMCP、webserver 默认监听及 onboarding/welcome 策略归 Better Dash。
-
-- Better Dash 独立 build/pack；Super Dash 用 npm bundledDependencies 内嵌该本地 tarball 展开的物理包。依赖版本 exact-pin 与源包一致。
-- Super Dash bundle 的有序 patch 文件先读取内嵌 Better Dash YAML，再读取自己的 YAML；消费者 profile 只声明 Super Dash，不单独声明 Better Dash。
-- Better Dash 的 WebTrust 默认组合启用 authentication-only，保留 native cookie 校验；Super Dash 删除重复实现及相关覆盖。
-- Better Dash 禁用原生 webserver 行、以独立 dashr-webserver 行继承原生 Service，并在监听前等待 welcome entry；默认 host 0.0.0.0，保留原生 port/压缩/CLI 配置机制；测试 launcher 默认仅覆盖 4999 端口，不再提供消费包未有的默认 host。
-- Better Dash 关闭 credentialOnboarding，人工模型配置保持可用。
-- `dashr-welcome-notice` 是可单行 disabled 的 Host entry：从实际安装锚的 Models 客户端读取当前 WELCOME_NOTICE_VERSION，经官方 internal/config 与 Entry.update 将确认同步投到原 ui-settings-general，不替换 Models UI，不写死版本，不用客户端 localStorage 假确认。
-- 静态私有常量没有公开 API；普通版本 bump 自动生效，符号/产物结构变化必须显式报错，不能静默保留旧版本。
-- dev WebMCP 移归 Better Dash 仓的开发测试目录，不进入正式插件 tarball；联合 launcher 仅将其作为开发附加 bundle。
-- 真实 tarball 安装、登录、native eval/create/prompt/resume、roster、首次 settings 快照、热禁用恢复为本轮验收；浏览器连接与 dev3 按可用环境如实记录。4999 保持运行。无 npm publish、commit/tag/push、上游或生产修改。

package/node_modules/better-dsh/docs/specs/zero-npm-runtime-deps/spec.md

@@ -1,85 +0,0 @@
-# better-dsh 归零 npm 运行时依赖（zero-npm-runtime-deps）
-
-状态：**已完成**（round 1–4 全部落地并实测；发布待 user 放行） ｜ 规格路径：`docs/specs/zero-npm-runtime-deps/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
-
-## 0. 动机（实证）
-
-一次 DSH UI Plugin Manager 安装的真实日志：
-
-```
-+ better-dsh 0.2.5-a
-Packages: +15 -71
-node_modules/zeromq install$ node ./script/install.js     ← 我们的 REPL 原生依赖，cmake 构建
-Done in 3.7s using pnpm v11.7.0
-[WARN] GET …/@oven/bun-linux-aarch64-android/-/…-1.4.2.tgz error (UND_ERR_SOCKET). Will retry in 10 seconds.
-dsh: pnpm printed nothing for 600000ms and was terminated
-```
-
-1. **卡住的东西不是 better-dsh 的**：`bun@1.4.2`（12 个平台包，各 ~86 MB）来自同一 profile 的 `super-dsh@0.1.9`。DSH 把插件 profile 设计成**一个共享 pnpm 工程**，于是"装插件 X" = "重解整个 profile"（`Packages: +15 -71` 是指纹）。
-2. **失败形态是超时、不是构建错误**：Plugin Manager 对每条捕获输出的 pnpm 运行挂 600000 ms 静默上限（`packages/boot/plugin-manager/src/index.ts:184`），超时杀树并打印 `operations.ts:453` 那句；真正的错误只是一条被吞掉的 WARN。
-3. **我们自己也在这条链上**：`zeromq@6.6.0` 是硬 `dependencies`，其 install 脚本用 cmake-ts 现场编译；`src/kernel.ts:20` 是**顶层静态 import**，该原生模块一旦拿不到，**整个插件加载死**（不只是 REPL）。`docs/specs/kernel-provisioning` 的三级自愈只覆盖 Python venv。
-
-user 裁决（2026-10-03）：**不要 declare 任何运行时依赖，不要 postinstall，不要碰 Node 包管理器**；二进制由我们自己的代码在 spin-up 自检与首次使用 lazy 时自装；装不上就那个组件不可用，其他组件照常。
-
-## 1. 目标态（硬契约）— ✅ 已达成
-
-- `package.json`：`dependencies` / `optionalDependencies` / `scripts.postinstall` **全部不存在**；60 条 `peerDependencies` 保留（harness 契约，由 loader 安装域供给）。真实安装器实测 `Packages: +1`（只加自己）。
-- 运行时需要的一切只有两条出路：**构建期进产物**（tsdown `noExternal` 内联；资产随 `files`）或**运行期自装到插件自管目录**（不调用 npm/pnpm/npx）。
-- 供给触发点只剩：**守护进程 spin-up 自检** + **首次使用 lazy**。
-- **fail-open 硬要求**：任何一项失败只让该组件不可用，插件整体加载与其余组件零影响。
-
-## 2. 逐依赖处置与进度
-
-| 依赖 | 用户 | 处置 | 状态 |
-|---|---|---|---|
-| `diff` | hashline `edit-diff.js` | tsdown `noExternal` 内联 | ✅ 已内联（`//#region node_modules/diff/...` 实证），已从 `dependencies` 移除 |
-| `xxhash-wasm` | hashline `hash-assign.js` | 同上（wasm 在 esm 构建里已内联为 `Uint8Array`，无外部资产） | ✅ 已内联，已移除 |
-| `file-type` | hashline `file-view.js`（A/B 实测：该调用点在**改动前就已被 tree-shake**，产物里只剩一条裸 `import "file-type"`） | 直接移除；内联与否不影响运行时 | ✅ 已移除 |
-| `use-sync-external-store` | client 半 | client 构建早已 `noExternal` 内联（产物零引用实证） | ✅ 已移除 |
-| `puppeteer-core` | `dvc://browser`（`await import()`） | 构建期内联（`lib/puppeteer-core-*.js`，206 导出）；实测拉起系统 Chrome 成功；保留 vendor 自装兜底 | ✅ 已移除声明 |
-| `zeromq` | REPL `src/kernel.ts:20` 静态 import | 删除；传输层改 venv 内 Python bridge | ✅ 已删除（`dependencies` 现只剩 `puppeteer-core`；Node 产物零 zeromq 引用） |
-| `@oh-my-pi/pi-natives-<platform>` | AST（`natives-loader.ts` 已 fail-open） | `ensurePiNatives()` 首用自装到 `<packageRoot>/.vendor`；加载器 vendor 精确查找 + 锚点有界 | ✅ 已移除声明，实测通过 |
-
-`scripts.postinstall`：✅ 早已不存在（0.2.2-a 起零 lifecycle script）——本次要消灭的是**依赖带进来的 install script**（zeromq）。
-
-## 3. REPL 传输层重写（round 2 已落地，待 4999 复测）
-
-现状：Node 是 Jupyter 客户端，用 `Dealer`/`Subscriber` 直连 ipykernel 的 shell/iopub/control（`src/kernel.ts:249-344`）。
-
-目标：
-
-```
-Node(TS) ──stdio JSON lines──► bridge.py（venv python + pyzmq/jupyter_client）──ZMQ──► ipykernel
-```
-
-- `pyzmq` / `jupyter_client` 由 `ipykernel` 传递依赖保证在场（实证：`.venv-kernel/lib/python3.11/site-packages/zmq`）。
-- 保留语义：cell 串行、iopub 流式、control 中断 + SIGALRM 升级、超时/dispose 时序、comm（host 请求桥）。
-- Node 侧不得再出现 zeromq/原生 socket；venv 未就绪时 `dashr-repl` 行**不抛**，标为未就绪。
-
-## 4. 供给阶梯（改造后）
-
-1. **守护进程 spin-up 自检**（主路径；`resolveKernelEnv` 已有，新增 bridge 可启动检查）。
-2. **首次使用 lazy**（兜底）。
-3. ~~postinstall~~ 不存在。
-
-## 5. 验收（对齐"改动点同类"红线）
-
-- 清单零 `dependencies`/`optionalDependencies`/`postinstall`；`npm pack` 后 tarball 自足。
-- 断网/无 npm：`dsh plugin add <tarball>` 成功、插件加载成功、REPL 由 venv 自足跑通一次真实 `eval`。
-- 无 zeromq 时：插件加载正常、其余组件全可用、只有 REPL 在缺 venv 时明确报"未就绪"。
-- 4999 第一人称实测 + 报告落 `docs/50_test-reports/`。
-- 发布仍需 user 明确放行。
-
-## 6. 已知风险
-
-- `puppeteer-core` 打包兼容性（动态 require / `import.meta`）未验。
-- Python bridge 多一跳后的中断/流式时序（SIGALRM 升级路径最敏感）。
-- 自装代码自担：版本钉死、sha512 校验、平台探测、并发去重、代理/离线行为。
-
-## 7. 进展日志
-
-- **round 1（2026-10-03）**：`tsdown.config.ts` 增 `BUNDLED_RUNTIME` + `noExternal`（含 `file-type` 的纯 JS 闭包：`@borewit/text-codec`/`@tokenizer/*`/`debug`/`ieee754`/`strtok3`/`token-types`/`uint8array-extras`）；`package.json` 的 `dependencies` 从 6 项降到 2 项（只剩 `puppeteer-core`、`zeromq`）。验证：`npm run build` 通过；产物内联 `diff` + `xxhash-wasm`，除 `puppeteer-core`/`zeromq` 外无任何外部包引用；全量单测 **649 passed / 1 skipped**。
-- 顺手发现：`better-dsh/docs/` 是构建产物（`scripts/copy-docs.mjs` 会 `rmSync + cpSync ../docs`），规格必须写在仓库根 `docs/`。
-- **round 4（2026-10-03）**：清单归零并接线自装器。`vendor.ts` 增 `VENDOR_ROOT = <packageRoot>/.vendor`；`natives-loader` 增 `ensurePiNatives()`（首用 lazy；显式 anchor 永不 provision）+ vendor 精确查找；`ast-device` 两处调用点 `await nativesOrThrow()`；`browser-device.loadPuppeteer()` 失败时走 vendor。删 `dependencies` + `optionalDependencies`（顺带修掉 round 2 我引入的重复 `puppeteer-core` 键）。实测：**`Packages: +1`**；puppeteer 内联后成功 `launch()` 系统 Chrome（`BUNDLED_PUPPETEER_OK`）；`dsh headless` 让 agent 走 `dvc://ast_grep` → `totalMatches 3 / files 2 / searched 189`，同时 `<plugin>/.vendor` 出现 314MB pi-natives，而 **profile 树里无 `@oh-my-pi`**（证明自装生效）；全量单测 **649 passed / 1 skipped**。报告：`docs/50_test-reports/2026-10-03-zero-npm-runtime-deps实测报告.md`。
-- **round 3（2026-10-03）**：① 新传输最后一条未验路径打通：`/tmp/smoke-comm.mts` 走通 host-request comm（内核 `create_comm('dashr.host')` → iopub → Node → **control** 通道 `comm_msg` 回包 → 内核 control-thread handler 解 future），cell 打印 `HOSTREPLY {'pong': True, ...}`。② **4999 第一人称实测**：新 tarball 装进 rig 的 web + headless profile（物理树里 **`zeromq` 已消失**），`dsh headless` 真实 session：`eval` 跑出 `REPL_OK 42`，同一 Python session 内 `await tool.bash({...})` 拿回 `HOST_OK\n`（宿主参数校验失败路径也顺带被触发），启动日志零错误、composed tree 含 `dashr-repl`。③ 新增 `src/vendor.ts`——零依赖自装器（registry packument → sha512/shasum 校验 → 自写 tar+pax 解包 → `createRequire` 解析入口 → 递归依赖闭包 + os/cpu/libc 平台过滤 → staging+rename 原子落盘）。实测：provision `@oh-my-pi/pi-natives-linux-x64@18.0.6`（2×163MB `.node`）并 **dlopen 成功**（exports `astGrep`/`astEdit`/…），二次调用 reuse。④ 注意：`better-dsh-0.2.5*.tgz` 是**入库的** rig 交付物，本轮为实测重新打包覆盖。
-- **round 2（2026-10-03）**：REPL 传输层换成 venv 内 Python bridge。新增 `src/kernel-bridge.py`（stdio JSON lines ↔ pyzmq/jupyter_client；`default=str` 序列化，避免 header 的 `datetime` 打死 pump 线程）与 `src/kernel-transport.ts`（spawn/readline/`waitFor`/`onExit`）；`kernel.ts` 删掉 `import { Dealer, Subscriber } from 'zeromq'`、`DELIM`/`encode`/`decode`/socket 字段/iopub pump，改由 `handleTransportMessage` 路由。`scripts/copy-kernel-bridge.mjs` 把 .py 拷进 `lib/`（`files: [lib]` 覆盖），`build` 链尾追加。验证：`tsc --noEmit` 0 错；全量产物零 `zeromq`；真实 ipykernel 冒烟通过（kernel_info ✅ / `print("SMOKE",6*7)` → `"SMOKE 42\n"` ✅ / 到 idle ✅ / **KERNEL_BOOTSTRAP 单元执行无错** ✅ / interrupt ✅ / dispose ✅）。⚠ 尚未经新传输验证的路径：host-request comm（内核侧 `dashr.host` → Node `serveHostRequest` → control 通道 comm_msg 回包），留给 4999 实测。