better-dsh 0.2.3 → 0.2.4

package/docs/specs/ctx/spec.md

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

package/docs/specs/dsh/spec.md

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

package/docs/specs/dvc/spec.md

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

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

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

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

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

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

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

package/docs/specs/http-read/spec.md

@@ -0,0 +1,73 @@
+# http-read Specification
+
+## Purpose
+
+Let the model read plain-text web resources via `http://` / `https://` URLs — a curl-equivalent direct HTTP GET with a hard budget, never a browser. One stateless handler serves both schemes.
+
+## Requirements
+
+### Requirement: GET-only plain-text fetch
+The system SHALL resolve `http://` and `https://` URLs by one GET request (redirects followed) to the exact URL — parsed strictly with `new URL(raw)` from the env's `rawUrl`, so ports and queries survive at the handler level — and return the disclaimer line, a blank line, then the decoded body text.
+
+#### Scenario: Fetching a text resource
+- **WHEN** the model reads `https://example.com/a.txt` and the server responds 200 with a text content-type
+- **THEN** the system returns the disclaimer line, a blank line, and the body text
+
+#### Scenario: The disclaimer is always first
+- **WHEN** any http(s) URL resolves successfully
+- **THEN** the first line of the result is `[url-fetch] plain-text result of a direct HTTP GET (curl-equivalent). No JS execution or interaction — use browser tools, if any, for that.` — the consumer sees the fetch semantics before any body content
+
+#### Scenario: Non-http(s) protocol is rejected
+- **WHEN** the handler is asked to resolve a URL whose strict-parsed protocol is neither `http:` nor `https:`
+- **THEN** the system returns the structured `URL_INVALID` error
+
+### Requirement: Hard time budget
+The system SHALL abort the GET after 20 seconds and return the structured `URL_HTTP_TIMEOUT` error.
+
+#### Scenario: Server never responds
+- **WHEN** the server accepts the connection but sends no response within the deadline
+- **THEN** the system aborts the fetch and returns `URL_HTTP_TIMEOUT`
+
+### Requirement: Hard size cap
+The system SHALL reject bodies over 2 MiB: first via a `Content-Length` precheck when present, then via streaming byte accounting while decoding (and a buffered re-check on bodyless runtimes), returning the structured `URL_HTTP_TOO_LARGE` error with the actual byte count.
+
+#### Scenario: Oversized declared body
+- **WHEN** the response declares a Content-Length over 2 MiB
+- **THEN** the system returns `URL_HTTP_TOO_LARGE` without downloading the body
+
+#### Scenario: Undeclared oversized body
+- **WHEN** no Content-Length is declared but the streamed bytes pass 2 MiB
+- **THEN** the system aborts decoding and returns `URL_HTTP_TOO_LARGE` with the received byte count
+
+### Requirement: Text-only media whitelist
+The system SHALL accept only textual responses: any `text/*` content-type, or `application/{json, xml, yaml, toml, xhtml+xml, javascript, plain}` (charset parameters ignored). A missing content-type fails the check. Anything else returns the structured `URL_HTTP_UNSUPPORTED_MEDIA` error — binary decoding is deliberately not guessed.
+
+#### Scenario: JSON response resolves
+- **WHEN** the server responds with `application/json`
+- **THEN** the body text resolves normally
+
+#### Scenario: Binary response is rejected
+- **WHEN** the server responds with `image/png`
+- **THEN** the system returns `URL_HTTP_UNSUPPORTED_MEDIA` and decodes nothing
+
+### Requirement: Structured failure codes
+The system SHALL report every failure with a structured code: non-2xx status → `URL_HTTP_STATUS` (status + statusText); network/DNS failure → `URL_HTTP_FETCH_FAILED` (with the underlying cause message); unparseable or non-http(s) URL → `URL_INVALID`. Precedence: status → size precheck → media whitelist → streamed body.
+
+#### Scenario: HTTP error status
+- **WHEN** the server responds 404
+- **THEN** the system returns `URL_HTTP_STATUS` with the status in the message
+
+#### Scenario: DNS failure
+- **WHEN** the host does not resolve
+- **THEN** the system returns `URL_HTTP_FETCH_FAILED` with the underlying cause
+
+### Requirement: No scheme-specific selector
+The system SHALL define no selector of its own for http(s): the handler always returns the disclaimer plus the full body. Selector handling is inherited solely from the shared resolver layer, whose parse runs first on the tool path — a URL query (`?…`) is consumed as a query selector by the shared parser (the fetch itself still uses the complete raw URL), and a `:port` currently fails the shared `URL_BAD_SELECTOR` check end-to-end. This is a documented known limitation, not a hidden behavior.
+
+#### Scenario: Query string is preserved for the fetch
+- **WHEN** the model reads `https://example.com/x?q=1`
+- **THEN** the fetch uses the complete URL `https://example.com/x?q=1` (from the env's rawUrl), and the shared parser's query selector applies only to the result text
+
+#### Scenario: Port-carrying URL on the tool path
+- **WHEN** the model reads `https://example.com:8443/x` through the read tool
+- **THEN** the shared selector parse fails with `URL_BAD_SELECTOR` — the handler's whole-URL parse is only reachable directly or via URLs without a port

package/docs/specs/kernel-provisioning/spec.md

@@ -0,0 +1,53 @@
+# kernel-provisioning Specification
+
+## Purpose
+better-dsh 的 REPL kernel（IPython）供给契约：独占 managed venv（插件包目录内，`kernelEnvDir` 可显式覆盖）、版本锁定（ipykernel 7.3.0 / dill 0.4.1，uv 与 pip 双路径）、三级触发供给（postinstall 加速器 / daemon spin-up 主路径 / 首用 lazy 兜底）全 fail-open 且幂等、供给状态可观测；npm 包不内嵌预建 venv（供给能力随包，供给结果不随包）。
+
+## Requirements
+
+### Requirement: Exclusive managed kernel venv
+
+The plugin SHALL provision its REPL kernel interpreter exclusively inside a managed venv rooted in the plugin's own package directory (web-profile scope in production deployments, `kernelEnvDir` as the explicit override), and SHALL NOT install into, mutate, or depend on the user's global Python environment; kernel probes MUST NOT import user-site modules, and the distributed npm package MUST NOT embed a prebuilt venv (provisioning capability ships, not provisioning results).
+
+#### Scenario: Venv lives inside the plugin territory
+
+- **WHEN** the plugin is installed into a web profile and the kernel is provisioned
+- **THEN** the venv root is inside the plugin's package directory (or the explicitly configured `kernelEnvDir`), and no file outside that territory is required for kernel operation
+
+#### Scenario: User global environment untouched
+
+- **WHEN** provisioning runs on a host with an existing global Python installation
+- **THEN** no package is installed into, and no configuration of, the user's global environment is modified
+
+### Requirement: Robust provisioning with pinned versions
+
+Provisioning SHALL redirect its tool caches (uv) to a plugin-territory location so read-only home directories cannot block it, SHALL fall back to `python3 -m venv` + ensurepip when `uv` is unavailable, and SHALL install pinned, tested versions of `ipykernel` and `dill` alongside the pinned CPython version; provisioning MUST be idempotent (a complete venv is reused; a partial one is repaired).
+
+#### Scenario: Read-only home cache does not block
+
+- **WHEN** the kernel is provisioned on a host whose `~/.cache` is read-only
+- **THEN** provisioning succeeds using the redirected cache location
+
+#### Scenario: Pinned versions installed
+
+- **WHEN** provisioning creates or repairs the venv
+- **THEN** the installed `ipykernel` and `dill` match the pinned tested versions, verifiable by the kernel probe
+
+### Requirement: Provisioning ladder — install-time, daemon spin-up, first-use
+
+The plugin SHALL provision the kernel through a three-trigger ladder converging on the same managed venv, every trigger fail-open (a failure or suppression at any level degrades to a logged status message and NEVER blocks package installation, daemon startup, or plugin mounting, and never asks the user for approval): (1) an install-time postinstall best-effort step that runs only when the package manager executes build scripts; (2) a daemon spin-up check as the PRIMARY path — when the plugin is brought up on the host plane by the host daemon, it asynchronously verifies the kernel environment and provisions it immediately when absent (uv → `python3 -m venv` → explicit configuration), so an agent session never discovers a missing kernel at first use; (3) first-use lazy provisioning as the final fallback. Provisioning status (provisioning/ready/degraded/failed) SHALL be logged, and failure messages MUST name the available remedies (`npm run kernel:venv`, `kernelAutoInstall`, explicit `python`).
+
+#### Scenario: Daemon spin-up provisions before any agent session
+
+- **WHEN** the host daemon starts and brings the plugin up on the host plane, and the managed venv is absent
+- **THEN** the plugin asynchronously provisions the kernel within the spin-up window without blocking daemon startup or plugin mounting, and a new agent session's first REPL cell finds the kernel already in place
+
+#### Scenario: Suppressed postinstall still reaches a working kernel
+
+- **WHEN** the package manager skips the plugin's postinstall script and the daemon later starts
+- **THEN** the spin-up check provisions the kernel and REPL cells execute, with the install itself never having failed and no approval ever having been requested
+
+#### Scenario: Failure is non-blocking and visible
+
+- **WHEN** provisioning fails on a constrained host at any trigger
+- **THEN** the installation, daemon startup, and plugin mounting all succeed; the surfaced error names the concrete remedy commands/configuration paths