better-dsh 0.2.4 → 0.2.5

package/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/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/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/docs/50_test-reports/2026-09-17-plugins/351/241/265/345/205/255/347/273/204/344/273/266/346/213/206/345/210/206/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,76 @@
+# Plugins 页组件化（6 行拆分）+ 卡片描述 实测报告
+
+- 日期：2026-09-17
+- 变更：spec `dashr/docs/specs/plugins-page-components/spec.md`（bundle patch 1 insert → 6 inserts；package.json 补 `description`；native-capture 提升共享模块）
+- 测试环境：Dev/Test 1（upstream 0.1.5-rc.2 源码树 + 内嵌 dashr 副本），实例 **4988**（4999 被占用），LAN socat 中继
+- 结论：**目标全部达成**（dev 线可证的全部事实）；UI 行开关逐键验收待 prod 安装后（见 §六）
+
+## 一、机制事实（对 prod 0.1.3 线 plugin-manager 源码核实）
+
+- 插件页卡片描述 = 包 manifest `description` 字段（`BundleInfo.description` JSDoc："`description` of the package manifest"）。better-dsh 此前缺该字段 → 卡片无描述。官方包走 locale 表（`builtinAgentTeamTitle/Description`），非官方回退 manifest。
+- 页面"组件" = bundle patch 的 **insert 行**（`declaredRows()`：inserts 才进 `rows`；非 insert 行进 `overrides`，该页不显示）。行开关 = 向 profile 用户层 patch 写 `{id, disabled}`，HMR 即时生效（`writePluginEnabled(profile.patchPath, …)` + `reload()`）。
+- 0.1.5-rc.2 测试线无 plugin-manager（无行开关 UI，仅只读 inventory）；行结构为两线共用的 host 侧事实。
+
+## 二、交付物
+
+1. `package.json`：`description` 逐字取 awesome-dsh-plugins listing en 文案（与市场单源一致）；新增 5 个子路径导出（`./url-schemes`、`./failover`、`./compaction-tuning`、`./web-trust`、`./mobile`）。
+2. `cordis.patch.yml`：6 条 insert（dashr-repl 核心 / dashr-url-schemes / dashr-failover / dashr-compaction-tuning / dashr-web-trust / dashr-mobile）；compaction 再启用三条与 `connection` fence 保持 override 行（原生页不列 override——做成 insert 需 fork 上游模块，不采纳）。
+3. 配置键迁移：`urlSchemes`/`hashline`/`trustedPageAuthorities`/`mobile` 离开 dashr-repl Config，落所属行 schema（`DSH_TRUSTED_HOSTS` 派生默认保留在 web-trust 行 schema；MOBILE_CONFIG 原文迁至 mobile 行）。
+4. **顺序不变式结构化**：`native-capture` 升为共享模块（tsdown 多入口 chunk 共享 `native-capture-x_Hos2e8.js`，单例 WeakMap）；wire mask 监听器第一步 `captureAllTools(agent)` 后才 restrict——两行激活顺序无关（`lib/index.js` 与 `lib/url-schemes/index.js` 实测引用同一 chunk）。
+
+## 三、构建卫生
+
+- dev 基 `tsc --noEmit`：与 stash 基线**逐条一致**（仅同类既有错误的行号漂移；基线 15 条均为独立 dev 检出的 host 类型漂移）。
+- dev 基 vitest 全量：**508 过 / 14 挂** —— 14 挂经 stash 基线复跑证实**先于本改动**（url-schemes.spec 2 + agent-family 12，同源类型漂移）。
+- surface.spec 夹具更新为**双行挂载**（镜像真实组合），10/10 过；**反向挂载顺序**（mask 行先于 url-schemes 行）同样 10/10 —— 顺序无关性实测成立。
+- monorepo 副本：`pnpm install`（node_modules 曾被清，build 产物完好）→ `tsdown` + `build-client.ts` 双半重建成功。
+
+## 四、4988 实例实测（第一人称）
+
+boot log 当前段零 error/warn；shell 200；boot graph 含 `"id":"better-dsh"`；`/plugins/??better-dsh/client.js&rev=…` 200 且与 `lib/client/index.js` 仅差服务端追加的 sourceMappingURL 行。
+
+1. **组合面**：`web --dump-config` 六行齐落 —— `dashr-repl→better-dsh`、`dashr-url-schemes→better-dsh/url-schemes`、`dashr-failover→better-dsh/failover`、`dashr-compaction-tuning→better-dsh/compaction-tuning`、`dashr-web-trust→better-dsh/web-trust`、`dashr-mobile→better-dsh/mobile`；override 行 `compaction-basic` `disabled: false` 在位。
+2. **双腿活体**：served HTML 同时含 `__DSH_TRANSPORT__`（authorities = `[test.pc.randomhash.app, pc.randomhash.app, 192.168.31.130]`，schema 默认自 DSH_TRUSTED_HOSTS 派生 ✓）与 `__DASHR_MOBILE__` + zoomGuard 段。
+3. **行开关往返**（用户层 patch 写 `{id: dashr-mobile, disabled: true}`，即 prod 开关按钮的落盘形态）：
+   - 禁用 → 3 秒内 HMR 生效：`__DASHR_MOBILE__` 0、zoomGuard 0、`__DSH_TRANSPORT__` 1（web-trust 行不受牵连）；
+   - 恢复 → `__DASHR_MOBILE__` 2、zoomGuard 1、transport 1。零重启。
+4. **LAN 中继**：`http://192.168.31.130:4988/?token=…` 303（认证重定向，链路通）。
+5. `.dsh-test` 用户层旧 override（`hashline`/`urlSchemes` 挂在 dashr-repl 行）已顺手迁移清零（键已随拆分移行）。
+
+## 五、已知边界
+
+- 0.1.5 测试线的 Settings → Plugins → Plugin list 只读 inventory 不展示 bundle 行（新 UI 模型）；六行 UI 开关验收属 prod 0.1.3 线 plugin-manager 页面。
+- url-schemes 行关闭时：eval/委派桥正常（mask 自带 capture 步骤固化被 mask 定义——单元级由 surface.spec 双行挂载覆盖）；read/write/grep/glob 回落原生语义。
+- failover / compaction-tuning 行关闭后，其 client 设置卡仍在 General 页写 settings（无消费者）——与拆分前"卡在、宿主逻辑在"的形态一致的降级，已在 spec §Out of Scope 记录。
+
+## 六、待办
+
+- user 以普通 user 身份自装实测（发布红线 a→c；本次未 publish、未动 prod）。
+- prod 安装后的 UI 验收清单：better-dsh 卡片显示 listing 描述；6 组件行在列；逐行开关 + HMR 生效；`dashr-mobile` 关闭后真机手势熄灭。
+
+---
+
+## 七、追加轮（2026-09-21）：对齐 harness 0.1.6-alpha.2，真 UI 全量验收 ✅
+
+user 裁决：侧栏 Plugins 页（plugin-manager UI）仅存在于 **0.1.6-alpha.2** 线；prod 已是 0.1.6-alpha.2 + latest better-dsh（0.2.4）。Dev/Test 1 checkout 由 `dsh-v0.1.5-rc.2` 切至 `dsh-v0.1.6-alpha.2`（ddefc45fbc）。
+
+### 对齐轮落位
+
+- **本地 patch 手工重放**（未盲 apply）：pnpm-workspace.yaml（storeDir/verifyDepsBeforeRun/linkWorkspacePackages + allowBuilds `zeromq`、`@deepseek-ai/dsh-subprocess-local`）；root package.json devDep `unrun@^0.3.1`；`packages/client/tsdown.client.ts` REPOSITORY_ROOT 派生（clean apply）；apps/web vite preact alias/dedupe + devDeps preact 10.29.8 pin（冲突手工并，pin 保留）。
+- **vendor 文档再迁移**：`vendor/docs/`（前轮 ENOTDIR 补丁位）在 0.1.6 会被 root tsdown.config 的 `vendor/*` workspace glob 当作**幻影包**（无 package.json → 向上找名 → `@deepseek-ai/dsh-root` → `Cannot find entry lib/types/{index,invariant,startup}.js` 全 build 失败）。已移出 vendor，落 `.scratch/vendor-docs/`。vendor 根不允许任何子目录缺 package.json。
+- **bun 工作流隔离**：树内另一 workstream 的未跟踪 bun-compile 实验文件（`packages/boot/app-boot/src/bun-internal-bridge.ts` + `bun-registry/` + 根 `x`）破坏 pristine tag 的 tsc（生成物 `dsh-bun-registry-entries/bun-registry.generated` 不存在，tracked 代码零引用）。已整体隔离至 `.scratch/bun-workstream-quarantine/`，未删除。
+- **测试 profile 依赖声明**（本轮关键发现）：0.1.6 plugin-manager 以 **profile package.json `dependencies`** 判定"已安装 bundle"；`.dsh-test` profile 此前只有 bundle 行 + 手工 symlink、dependencies 为空 → better-dsh 卡片不出现。已补 `"better-dsh": "0.2.4"`（镜像 prod 形态；不跑 profile install，symlink 供位不变）。
+- 全量构建通过（248 client artifacts）；copy 侧 tsdown + build-client 双半重建；pnpm install 完成 copy 的 14 项 `workspace:*` devDeps 手术链接。
+
+### 真 UI 验收（CDP，4988 @ 0.1.6-alpha.2-ddefc45-dirty）
+
+1. **卡片**：`better-dsh v0.2.4` + listing 文案描述全文在卡（"Make your dsh ready for serious coding tasks. (Tools x Schemas)^REPL. …"）—— description 修复在真 UI 得证。
+2. **组件**：`Components 6 total · 6 running` —— dashr-repl / dashr-url-schemes / dashr-failover / dashr-compaction-tuning / dashr-web-trust / dashr-mobile，模块名逐行正确，各带 `role="switch"`。
+3. **行开关真 UI 往返**（dashr-mobile）：
+   - 关 → aria-checked true→false；用户层 patch 立现 `{id: dashr-mobile, disabled: true}`；2.5s 内 served HTML `__DASHR_MOBILE__` 归零、zoomGuard 消失、`__DSH_TRANSPORT__` 不受牵连；
+   - 开 → override 行被移除、行态回 true、mobile 全局 + zoomGuard 复返。零重启，零页面错误。
+4. 截图：`.scratch/4988-plugins-016.png`（列表）、`4988-mobile-off.png` / `4988-mobile-on.png`（往返两态）。
+
+### 结论
+
+两项原始诉求（卡片描述、组件化行开关）在**与 prod 同版**的 harness 上全量验收通过。发布仍按红线等待 user 单次明确放行。

package/docs/50_test-reports/2026-09-22-4988/345/217/214/345/271/263/351/235/242/345/220/257/345/212/250/344/277/256/345/244/215/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,76 @@
+# 4988 双平面启动修复（首工具调用 'prepare' 崩溃 + 会话毒化）实测报告
+
+- 日期：2026-09-22
+- 环境：Dev/Test 1（upstream `dsh-v0.1.6-alpha.2` checkout + 内嵌 better-dsh 0.2.4 副本），实例 4988（unit `dsh-4988-test` + LAN socat 中继），`DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`
+- 结论：**根因修复 + 第一人称实测通过**。崩溃与 better-dsh 无关（headless 无 better-dsh 一样崩；prod 3080 带 better-dsh 0.2.4 正常）；根因是 **tsx 源码启动的双平面模块分裂**。修复 = 产物面启动（`apps/cli/lib/bin.js` + 裸 node，与 prod 同构）。
+
+## 一、症状（user 报告，2026-09-21/22）
+
+每个新 session 的**第一个工具调用**必失败：
+
+```
+This turn failed  Cannot read properties of undefined (reading 'prepare')  UNKNOWN
+```
+
+其后同 session 任何后续轮次：
+
+```
+This turn failed  DeepSeek Messages tool calls need immediate results  INVALID_REQUEST
+```
+
+会话从此不可用。复现的失败工具：`bash`、`skill`；Llm `thinking` 流正常出字（LLM 请求/响应路径完好），崩溃点在工具调度。
+
+## 二、证据时间线（session log 全量扫描，88 个 zstd session）
+
+| 时间（HKT） | session | 工具调用数 | turn 错误 | 备注 |
+|---|---|---|---|---|
+| 09-12 ~ 09-15 01:09 | 数十个 | 1–289/个 | 0 | 同一 09-12 01:13 boot，read/write（dvc:// URI 走 better-dsh remask）全部成功 |
+| 09-15 01:26 | `…7842bf` | 1 | prepare + INVALID_REQUEST | **首例**；agent preset `cordis`；旧 0.1.5-rc.2 boot |
+| （无 session） | — | — | — | 09-15→09-22 间无任何真实 chat session 复测 |
+| 09-22 00:06 | `…8c2514ba` | 1 | prepare + INVALID_REQUEST | user 复测；默认组合 |
+| 09-22 00:12 | `…5ca418a1` | 1 | prepare | user 复测；preset cordis |
+
+关键事实：09-15 01:09（成功，13 调用）与 01:26（首败）在**同一 daemon 进程**上——非重启/重建引入；align 轮（09-21）之前已存在。
+
+## 三、根因链（每步有实证）
+
+1. **崩溃点**：`agent-loop/src/tool-calls.ts` `startCall` 的 `ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)`。栈经临时诊断打点捕获（已还原）。`tool/call` 事件先落（`appendToolCall`），prepare 抛 TypeError → turn 以 UNKNOWN 结束；**孤儿 tool/call 无结果** → 之后每轮 DeepSeek 序列化器拒绝（`llm-deepseek/src/protocols/messages/serialize.ts:117` 的 "tool calls need immediate results"）。
+2. **诊断打点实测**：`ctx.tools` 是 ToolRuntime 实例，ownSymbols 含 `Symbol(@deepseek-ai/dsh-tools.scheduler)`，但与 agent-loop 导入的 symbol **同 description 不同对象** = 同进程两份 `@deepseek-ai/dsh-tools`。
+3. **两份从哪来**：tsx 源码启动 = 双平面运行时——
+   - TS 文件（apps/cli、各包 src）经 `tsconfig.base.json` `paths`（`@deepseek-ai/dsh-*` → `packages/*/*/src/index.ts`）→ **src 副本**；
+   - plugin loader 把组合行模块名解析为构建 lib 的 file URL → **lib 副本**（且 vendor/cordis 的 lib bundle 陈旧——不含 `FiberState` 导出）。
+   - lib 侧 ToolRuntime 把 scheduler 挂在 lib 副本 symbol 下；src 侧 agent-loop 按 src 副本 symbol 查 → `undefined`。
+4. **为何 prepare 门不接住**：`prepareExecution` 的 try/catch 只包门内瀑布；`ctx.tools[SYMBOL]` 在 agent-loop 侧、门之前求值。
+5. **为何 paths-less 收敛不可行**：`vendor/cordis/src/fiber.ts` 的 `export const enum FiberState` 被 tsc 内联（bundle 无该运行时导出），tsx 只能保留 value import → 产物 lib 面 boot 必然 `SyntaxError: ... does not provide an export named 'FiberState'`。**源码启动本质上需要 src 面** → 唯一正解 = 产物面启动。
+
+## 四、better-dsh 判定：**无关（exonerated）**
+
+- headless 一次性任务（无 web profile、无 better-dsh、`--profile headless`）在 tsx 启动下**同栈同错**；
+- prod 3080（npm 0.1.6-alpha.2 + better-dsh 0.2.4，产物面运行）工具调用全部正常——本报告撰写会话即运行其上；
+- 九条运行期 import 的 better-dsh 嵌套链接审计：8 条本就指 workspace，1 条（`dsh-home-paths` → `.pnpm/@deepseek-ai+dsh-home-paths@0.1.2-rc.1`）为陈旧 registry 副本，**已改链**到 `packages/util/home-paths`（见 §六）。
+
+## 五、修复与验证
+
+**修复**（对 src 零改动——三个临时诊断打点已全部还原，`git status` 干净）：
+
+- `tests/start-4999.sh`：boot 行改为 `node apps/cli/lib/bin.js web --no-open --port $PORT`（产物面 + 裸 node，无 tsx），附根因注释与 lib/bin.js 存在性守卫；
+- `AGENTS.md` §二 启动块同步改写：新命令 + 红线（tsx 源码启动禁止用于回归验收）+ `pnpm run build` 前置条件；
+- 全量 `pnpm run build` 已跑（exit 0），产物面完整。
+
+**验证**：
+
+1. headless A/B（同 checkout 同 home）：tsx 启动 → 必现 `prepare` 崩溃；`node apps/cli/lib/bin.js` → 过（调度器查找命中）。
+2. **真 session 第一人称**（systemd-run 沙箱外一次性任务，真 LLM + 真 bwrap）：
+   - `bash`：`echo repro-marker-4988` → `repro-marker-4988`（exit 0）✅
+   - `skill`：调用返回**结构化结果**（"skill using-superpowers is unknown"——headless cwd 无该技能目录，属正常业务错误；关键在 tool result 落账，不再 UNKNOWN）✅
+3. 4988 web 实例（修复后重启，`LAN=1`）：shell HTTP 200、`__DSH_BOOT__` 在位、boot graph 含 `"id":"better-dsh"`；进程确认为 `node …/apps/cli/lib/bin.js web --no-open --port 4988`。
+4. agent-loop/tools lib 复查：无 `dashr-debug` 残留；两包 src 无本地改动。
+
+## 六、遗留与备注
+
+- better-dsh 副本嵌套树仍存在非运行期陈旧链（`dsh-agent-loop`、`dsh` → `.pnpm …@0.1.2-rc.1`；运行期不 import，无实害）。运行期九链已全 workspace 化。
+- `packages/subagent/tool-subagent-report/` 为**只含 lib/ 的异源残留**（无 package.json/src、git 未跟踪；疑另一 workstream 产物），未被任何 manifest 引用，无实害；处置待 user 裁决。
+- **旧中毒 session 无法复活**（孤儿 tool/call 已落账）：09-15 `7842bf` 与 09-22 两个 session 请弃用；新 session 正常。
+- prod 3080 无需任何动作（本就产物面运行）。
+- 09-15 `7842bf`（旧 0.1.5 树 + cordis preset）为同类双平面机制在旧树的另一形态；旧树已升级，不回溯归因。
+- 诊断过程临时文件：`.scratch/session-debug/`（session 解包与扫描脚本），留作证据。