better-dsh 0.2.4 → 0.2.5

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

package/docs/20_specs/lsp/spec.md

@@ -0,0 +1,121 @@
+# lsp Specification
+
+## Purpose
+`lsp` 是**双模**语言服务能力：passive push 模（插件订阅 dsh 文件事件流，替 agent 向 per-session LSP server 子进程做 `didOpen/didChange/didSave` 文本同步，缓存 server 推回的 `publishDiagnostics`）+ proactive tool 模（agent 经 `dvc://lsp` 主动要 `diagnostics`/`format`/`definition` 等）。工作单位 = agent session（cwd 即 workspace root 候选）；**每 session 每语言一个 server 子进程**，不跨 session 共享。生命周期三级供给，类比 repl kernel：host start 零重物、session-start 登记零子进程、首用 lazy spawn。
+
+## Requirements
+
+### Requirement: Root-marker probing (lspMarker)
+Server availability and project-root determination SHALL follow the per-language marker table（`pyrightconfig.json`/`pyproject.toml`、`tsconfig.json`/`jsconfig.json`、`Cargo.toml`、`go.mod` …配置驱动，不发明 `lsp.json`）——编辑器侧工程惯例，非 LSP 协议标准。Marker 缺席不阻断：server 仍可 spawn，root 退化为 mutation 文件所在目录。
+
+#### Scenario: Marker present
+- **WHEN** a session's cwd contains a language marker file and the language's server is locally available
+- **THEN** the manager resolves project root to the marker's directory and reports availability for that language
+
+#### Scenario: Marker absent
+- **WHEN** no marker exists for the mutated file's language
+- **THEN** availability is `unknown`, not `unavailable` — the gate below still offers opt-in
+
+### Requirement: Gated notice with explicit per-session opt-in (on/off)
+The manager at session start SHALL check local availability of each language server in its table（Python/TypeScript 为必备，缺失即安装；Rust/Go 保留 nag 检测，server 缺失时按需安装）. When a session performs file mutations (edit/write 落盘) in a language with availability `available` or `unknown` and the session gate is `unasked`, the tool result MAY append the availability notice (lsp 可用，`dvc://lsp` 开/关) **at most 10 times per session**（防刷屏上限）. Both `on` and `off` are PER-SESSION state — the manager handles everything, and SHALL write NO repo artifact or marker file in either direction（无 `.dashr/lsp.json`，无任何落盘偏好）.
+
+#### Scenario: Mutation nag capped
+- **WHEN** the agent edits `.py` files repeatedly in a session with gate `unasked`
+- **THEN** at most 10 tool results carry the notice; afterwards mutations stay silent until the gate is decided
+
+#### Scenario: Explicit on (per session)
+- **WHEN** the agent sets `dvc://lsp` on
+- **THEN** the session gate becomes `on` and the manager warm-starts the language server; nothing is written to the repo
+
+#### Scenario: Explicit off (per session)
+- **WHEN** the agent sets `dvc://lsp` off
+- **THEN** the gate becomes `off`, no server spawns, the notice is muted for the session, and no repo marker is written
+
+### Requirement: Must-have servers installed, niche on demand
+At session start the manager SHALL verify Python and TypeScript servers and INSTALL a missing one (pip/npm, pinned, fail-soft — 安装失败降级为该语言 `unavailable`)；Rust/Go servers SHALL NOT be installed proactively — they stay in the nag-detection table and install only when the agent turns lsp on for that language.
+
+#### Scenario: Missing pyright on a fresh host
+- **WHEN** a session starts and no Python language server is installed
+- **THEN** the manager installs it in the background and reports availability `available` once done（安装期间 `unknown`，nag 照常）
+
+#### Scenario: Rust opted in on demand
+- **WHEN** the agent sets lsp on in a session touching Rust files and rust-analyzer is absent
+- **THEN** the manager installs rust-analyzer then spawns it — never before the opt-in
+
+### Requirement: Lazy spawn, session lifetime
+Server subprocesses SHALL spawn lazily on first post-on use, one subprocess per (session, language), registered under the agent's own tool effect so agent dispose unwinds them via `shutdown`+`exit`; an idle timeout reclaims servers of still-live sessions.
+
+#### Scenario: Per-session isolation
+- **WHEN** two sessions work in different cwd/repo simultaneously
+- **THEN** each owns independent server subprocesses with its own workspace root and document mirrors
+
+### Requirement: Text synchronization is post-hoc, never intercepting
+The plugin SHALL feed document sync (`didOpen`/`didChange` full-text + `didSave`) from AFTER-THE-FACT dsh events only — `tools/post-execute` on successful read/edit/write, mirroring the exact landed content（EXACT content, didSave freshness, span guard）— and SHALL NOT intercept, wrap, or delay any dsh read/write/edit flow. The version ledger follows the host fs observation policy's read-before-edit accounts; no second version book is kept.
+
+#### Scenario: Landed content is the mirror
+- **WHEN** an edit lands and lsp is on for that language
+- **THEN** the server receives a full-text `didChange` + `didSave` with the exact written content before diagnostics are requested, so line numbers match what the model just wrote
+
+### Requirement: Dual-mode results
+Proactive mode (`dvc://lsp` write: `diagnostics`/`format`/`definition`/…) and passive mode (cached `publishDiagnostics` attached to tool results, e.g. hashline edit 的 post-edit summary，经注入回调而非模块内依赖) SHALL both be served from the same session manager. Every failure — no server, gate off, cold-start noise — SHALL read as "no feedback": a serverless mutation is byte-identical to stock behavior.
+
+#### Scenario: Diagnostics ride the edit result
+- **WHEN** lsp is on, an edit lands, and the server answers diagnostics
+- **THEN** the edit's tool result carries the diagnostics summary; when the server is absent or slow, the result is unchanged
+
+### Requirement: Spin-up latency is absorbed, never blocking
+Server cold-start（spawn + `initialize` + 首轮索引）SHALL be handled by three means: (1) **warm-start at opt-in** — gate on 即后台 spawn，不等首个请求; (2) **fire-and-attach** — diagnostics 请求带超时，超时/未就绪读作"no feedback"，server 稍后推回的 `publishDiagnostics` 缓存并附到**下一个** mutation 的 tool result（延迟附挂，不丢不阻塞）; (3) **read 预热** — session 内首个某语言文件 read 即提前 `didOpen`，使首个 edit 命中已初始化的 server. The mutation path SHALL NEVER wait on server readiness — worst case is a summary arriving one tool call late.
+
+#### Scenario: First edit on a cold server
+- **WHEN** the gate turns on and the very next mutation hits an uninitialized server
+- **THEN** the edit result carries no diagnostics (no feedback), and when the server finishes indexing the diagnostics attach to the next mutation's result
+
+#### Scenario: Read pre-warms
+- **WHEN** the agent reads a `.ts` file before editing it and lsp gate is on for TypeScript
+- **THEN** the read triggers `didOpen` and server initialization, so the subsequent edit usually gets same-call diagnostics
+
+### Requirement: Orthogonality and injection boundaries
+The lsp capability SHALL be a self-contained module: no url-schemes/hashline imports; per-feature attachments (edit-result diagnostics, availability notices) arrive as injected callbacks from composition roots. Host start SHALL NOT probe markers or spawn processes — all discovery is per-session, on demand.
+
+#### Scenario: Host boot cost
+- **WHEN** the host starts with the lsp capability mounted
+- **THEN** no subprocess spawns, no marker probing runs, and nothing on the boot path can fail because of lsp
+
+## Surface syntax (`dvc://lsp`)
+
+The dvc contract is uniform: **bare read = roster, `<device>` read = doc/status, `<device>` write = action dispatch**. Gate state is per-session — the write dispatcher injects the calling agent's session id automatically; agents never type it.
+
+Read-vs-write follows GET/PUT semantics — **reads never mutate, writes always do**:
+
+- `read dvc://lsp` — the device doc: actions, args, current contract.
+- `read dvc://lsp/status` — the calling session's gate (session injected from the read env; no session → an explicit pointer note).
+- `read dvc://lsp/diagnostics?file=<path>&all=1` — fan-out query (read-only; spawning a lazily-managed server is the side effect of asking, not a mutation).
+- `read dvc://lsp/definition?file=&line=&character=|&symbol=` (also `references`, `hover`) — position queries, 1-based.
+- `write dvc://lsp` `{"action":"on"}` / `{"action":"off"}` — per-session gate decision; ack describes the effect. No repo artifact in either direction.
+- `write dvc://lsp` `{"action":"reload"}` — restart the server (config re-read).
+- `write dvc://lsp` `{"action":"rename",...}` / `{"action":"code_actions",...,"apply":N}` / `{"action":"format","file":...}` — workspace-mutating operations.
+
+The write surface retains `status` for symmetry with the session-injected dispatcher, but the read form is canonical for all queries. Path-mutation forms (`dvc://lsp/on`) are NOT part of the contract: mutation never rides a read URL.
+
+### Requirement: Session transport is out-of-band
+The per-session gate addressing SHALL ride the dvc write dispatcher's `execute(args, { session })` context — NOT the args payload — so devices with strict argument validators (browser) are unaffected; the lsp device reads `ctx.session` with a legacy in-args fallback for direct callers. The read surface receives the calling session through the resolver env the same way (`dvc://lsp/status` returns the calling session's gate).
+
+#### Scenario: Strict-validator device unaffected
+- **WHEN** the model writes `dvc://browser` with `{"action":"open","url":…}` from a session
+- **THEN** the browser device's validator sees only its declared fields and the action executes (the session rides the dispatcher's out-of-band ctx)
+
+#### Scenario: Status read is session-aware
+- **WHEN** the model turns lsp on and then reads `dvc://lsp/status` from the same session
+- **THEN** the status reports that session's gate (`"gate":"on"`)
+
+## OMP parity progress
+
+The device vendored a trimmed upstream oh-my-pi (`packages/coding-agent/src/lsp`) surface; parity is being completed in stages, each keeping the module boundary (nothing imports hash-edit/ast/url-schemes internals):
+
+1. ✅ `rename` / `code_actions` / `reload` actions (apply/preview WorkspaceEdit over `changes` + `documentChanges`; code action apply by index; reload = shutdown + evict).
+2. ✅ Workspace-wide diagnostics (`{"action":"diagnostics","file":"*"}` — aggregate cached publishDiagnostics across all live servers, per-file E/W counts) + `documentDiagnostic` pull for servers advertising `diagnosticProvider` (pull wins over last push on the saved path).
+3. ✅ Per-file fan-out: `{"action":"diagnostics","file":...,"all":true}` queries every registered server covering the file and merges results tagged per server (single-coverage falls through to the primary path).
+4. ✅ `symbol` / `symbol#N` position resolution on definition/references/rename/hover (word-bounded exact first, case-insensitive fallback, structured `LSP_SYMBOL_NOT_FOUND`; explicit `character` wins).
+5. ✅ Must-have installer: registry `installServer()` runs the package-manager command (npm/pip/go/rustup, 5 min timeout, fail-soft) for missing python/ts/js primaries once per session at first nag; niche languages stay install-on-opt-in.
+
+All five stages are in-tree; residual deltas vs upstream (lspmux, deferred-diagnostics ledger, writethrough editor integration) are IDE-side facilities without a dsh counterpart and are tracked as out of scope by the lsp spec's post-hoc sync ruling.

package/docs/20_specs/mobile-layout/spec.md

@@ -0,0 +1,108 @@
+# mobile-layout Specification
+
+## Purpose
+better-dsh 的移动端布局与输入契约：窄视口侧栏轨 0（注入 CSS 覆盖，桌面档零影响）、三条件滑动手势（边缘带 × 距离 × 速率，纯函数可测）、iOS focus 自动放大抑制 zoomGuard（browser=viewport meta token 改写 / standalone=16px 字号地板双形态，`'off'` 逃生门），全部随插件发布、config 门控（`mobile.enabled` / `mobile.breakpoint` / `mobile.zoomGuard`）。
+
+## Requirements
+
+### Requirement: iOS focus auto-zoom suppression on narrow viewports
+
+The plugin's host half SHALL suppress the iOS Safari focus-triggered auto-zoom with **display-mode-dependent behavior**:
+
+- **Browser context** (not standalone): rewrite the page's viewport meta (appending `maximum-scale=1` and `user-scalable=no`) inside the injected head boot script — before any application bundle can focus an input — with the v0.2.4 machinery (double gate iOS-class UA AND narrow viewport, breakpoint re-evaluation, provisional/reconcile single-meta invariant, early-load re-evaluation ladder, idempotent merge, byte-level restore). Real-device datum (2026-09-03): in-browser iOS Safari ignores `user-scalable=no` for pinch, so pinch zoom remains available in this mode.
+- **Standalone context** (`(display-mode: standalone)` media query matches OR `navigator.standalone === true`): the plugin SHALL NOT touch the viewport meta at all (no rewrite, no provisional, no listeners, no timers — real-device datum: standalone iOS honors `user-scalable=no` and pinch would break), and SHALL instead inject a static style element (`id="ios-zoom-font-floor"`, carrying the plugin's style-claim attributes) with `@media (max-width: {breakpoint-0.02}px){ input,textarea,select,[contenteditable="true"]{ font-size:16px !important } }`, which suppresses the focus auto-zoom by the font-size mechanism.
+
+Both branches SHALL be config-gated via `mobile.zoomGuard` (`'meta'` default = auto dual-mode behavior; `'off'` emits neither branch on any platform). Non-iOS browsers and wide viewports SHALL observe stock behavior in both display modes.
+
+#### Scenario: iOS narrow focus does not zoom
+
+- **WHEN** an input, select, checkbox, or contenteditable receives focus on an iOS-class browser below the breakpoint with `zoomGuard: 'meta'`
+- **THEN** no auto-zoom occurs in either display mode: browser mode suppresses it via the rewritten viewport meta, standalone mode via the 16px font-floor style
+
+#### Scenario: Rewrite lands before first possible focus
+
+- **WHEN** the head boot script executes during page load in browser (non-standalone) display mode
+- **THEN** the viewport meta rewrite is applied synchronously before any application bundle materializes, so no zoom flash can occur on an early auto-focus
+
+#### Scenario: Browser mode rewrites meta (unchanged from v0.2.4)
+
+- **WHEN** an iOS-class browser below the breakpoint loads in a non-standalone display mode with `zoomGuard: 'meta'`
+- **THEN** the viewport meta carries `maximum-scale=1, user-scalable=no` (single meta, idempotent, restorable) and no font-floor style is injected
+
+#### Scenario: Standalone mode never touches the viewport meta
+
+- **WHEN** an iOS-class browser below the breakpoint loads with display-mode standalone (matched via media query or `navigator.standalone`) and `zoomGuard: 'meta'`
+- **THEN** the viewport meta is byte-identical to stock, no provisional meta is created, no resize/MQ listeners or re-evaluation timers are armed, and the `ios-zoom-font-floor` style element is present with the 16px floor rules scoped to the configured breakpoint
+
+#### Scenario: Standalone pinch zoom is preserved
+
+- **WHEN** the user pinch-zooms in standalone display mode with the guard active
+- **THEN** the viewport meta contains no zoom-restricting tokens (pinch is engine-available; suppression relies solely on the font-size floor)
+
+#### Scenario: Font floor suppresses the focus zoom in standalone
+
+- **WHEN** an input, textarea, select, or `[contenteditable="true"]` element receives focus in standalone mode below the breakpoint
+- **THEN** its computed font-size is at least 16px and no auto-zoom occurs
+
+#### Scenario: Non-iOS touch browsers unaffected
+
+- **WHEN** the page loads on a non-iOS touch browser (e.g. Android Chrome) below the breakpoint, in either display mode
+- **THEN** the viewport meta is not rewritten and no font-floor style is injected (Android never focus-zooms; the iOS gate avoids `maximum-scale` side effects there)
+
+#### Scenario: Breakpoint crossing re-evaluates
+
+- **WHEN** the viewport crosses the breakpoint after load (rotation, split-screen) in browser display mode
+- **THEN** the rewrite is applied on entering the narrow band and the stock meta content is restored on leaving it; in standalone mode the font-floor style's media query naturally stops matching above the breakpoint (no JS re-evaluation exists there)
+
+#### Scenario: Desktop and wide viewports unaffected
+
+- **WHEN** the page loads on a desktop browser, a non-iOS browser, or at/above the breakpoint (either display mode)
+- **THEN** the viewport meta is stock and no font-floor style is injected (the floor's media query does not match above the breakpoint)
+
+#### Scenario: Config off restores stock behavior
+
+- **WHEN** `mobile.zoomGuard` is `'off'`
+- **THEN** neither the meta machinery nor the font-floor style exists in any display mode
+
+#### Scenario: Idempotent evaluation
+
+- **WHEN** the browser-mode re-evaluation runs multiple times within one state (load, resize storms, repeated crossings)
+- **THEN** the meta content does not accumulate duplicate tokens or regress (standalone mode arms no re-evaluation machinery at all)
+
+### Requirement: Sidebar occupies zero width on narrow viewports
+
+The plugin's client half SHALL hide the sidebar rail (zero-width column track) on narrow viewports via injected static CSS (media query + semantic attribute selectors, `!important` over the inline grid template), aligned with the upstream CSS-first layout paradigm and WITHOUT JavaScript geometry measurement; desktop-class rendering SHALL remain identical to the unpatched product, and the feature SHALL ship with the plugin, config-gated (`mobile.enabled`, default on).
+
+#### Scenario: Mobile viewport hides the rail
+
+- **WHEN** the page renders at a mobile-class viewport width below the configured breakpoint with the feature enabled
+- **THEN** the sidebar column track is zero width and the conversation area spans the frame
+
+#### Scenario: Desktop unaffected
+
+- **WHEN** the page renders at or above the breakpoint
+- **THEN** layout behavior is identical to the unpatched product
+
+#### Scenario: Degradation is benign
+
+- **WHEN** upstream DOM/attribute changes break the CSS override
+- **THEN** the layout falls back to the native rail rendering without errors or blank areas
+
+### Requirement: Three-condition swipe recognition
+
+Swipe recognition SHALL require all three of: gesture origin within the edge band, displacement at or above the distance threshold, and average velocity at or above the velocity threshold; slow press-drag gestures (text selection and similar) SHALL NOT trigger a swipe, and a recognized swipe SHALL toggle the sidebar via the layout service (`ctx.layout.toggleSidebar()`, narrow-viewport semantics), with the velocity/distance predicates implemented as pure functions under unit test.
+
+#### Scenario: Slow text-selection drag does not toggle
+
+- **WHEN** a pointer press-drag covers the distance threshold at sub-threshold velocity (e.g. selecting text to copy)
+- **THEN** no sidebar toggle occurs
+
+#### Scenario: Fast swipe toggles
+
+- **WHEN** a pointer gesture starts in the edge band, exceeds the distance threshold, and meets the velocity threshold
+- **THEN** the sidebar overlay state toggles (narrowExpanded flips)
+
+#### Scenario: Interactive-element origins are ignored
+
+- **WHEN** a gesture begins on an interactive element (link, button, input)
+- **THEN** no swipe recognition runs for that gesture

package/docs/20_specs/model-failover/spec.md

@@ -0,0 +1,20 @@
+# model-failover Specification
+
+## Purpose
+TBD - created by archiving change 2026-09-02-model-failover-settings-surface. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Model Failover surface in General settings
+
+The plugin SHALL register a Model Failover row into the Settings > General page via the `settings.general.item` slot, exposing the failover pair (primary/secondary model selectors) with persisted configuration, wherever the plugin's client bundle is built and loaded — including the source-level test instance — and the row SHALL remain functional across upstream settings-slot contract evolutions covered by the alignment process.
+
+#### Scenario: Row renders in the source-level test instance
+
+- **WHEN** the Dev/Test 1 instance starts with the plugin's client bundle built and the user opens Settings > General
+- **THEN** the Model Failover row with both model selectors is visible and its selections persist across instance restarts
+
+#### Scenario: Failover engages on primary failure
+
+- **WHEN** a turn's primary model request fails and a secondary model is configured in the row
+- **THEN** the host-side per-turn waterfall retries via the configured secondary and the outcome is observable in the session

package/docs/20_specs/plugins-page-components/spec.md

@@ -0,0 +1,79 @@
+# plugins-page-components Specification
+
+## Purpose
+
+让 better-dsh 在原生 Plugins 页（`dsh-client-ui-plugin-manager`）上呈现与官方 bundle 同等的两件事：
+
+1. **卡片描述**：页面的 `BundleInfo.description` 直接取自包 manifest 的 `description` 字段；better-dsh 的 package.json 缺该字段导致卡片无描述。补齐为 awesome-dsh-plugins listing 的同款文案（单一事实源，两表面一致）。
+2. **组件化**：页面只把 bundle patch 的 **`insert` 行**列为可开关组件（每行一个 toggle，写 profile 用户层 `cordis.patch.yml` 的 `{id, disabled}` 覆盖行，HMR 即时生效）；非 insert 行只进 `overrides`（本页不显示）。现状 better-dsh 只有一条 insert（`dashr-repl`），整个插件是"一个组件"。本变更把 bundle patch 拆成 **6 条 insert**，每条 = 一个可独立开关的功能组件，映射原生 Agent Teams 的双组件形态。
+
+## Requirements
+
+### Requirement: 六组件行结构
+
+bundle patch（`cordis.patch.yml`）SHALL 恰好声明 6 条 insert 行，全部指向同一 npm 包 `better-dsh` 的子路径导出：
+
+| row id | module | 内容 |
+|---|---|---|
+| `dashr-repl` | `better-dsh` | 核心：kernel runtime + spin-up 供给检查 + `eval` + 三委派桥 + `llm_completion` + wire mask + escalation guidance |
+| `dashr-url-schemes` | `better-dsh/url-schemes` | URL 感知 I/O + hashline + devices（原 `DshUrlSchemes`，行配置载 `urlSchemes`/`hashline` gates） |
+| `dashr-failover` | `better-dsh/failover` | LLM failover 瀑布（settings 驱动，行配置 = 两个 fallback 槽） |
+| `dashr-compaction-tuning` | `better-dsh/compaction-tuning` | 自动压缩阈值偏好（settings 驱动） |
+| `dashr-web-trust` | `better-dsh/web-trust` | `webserver/index-inject` **authorities 腿**（`__DSH_TRANSPORT__.ownsHost`）；行配置 `trustedPageAuthorities`（schema 默认派生自 `DSH_TRUSTED_HOSTS`） |
+| `dashr-mobile` | `better-dsh/mobile` | `webserver/index-inject` **mobile 腿**（`__DASHR_MOBILE__` + zoomGuard 段）；行配置 = 原 `MOBILE_CONFIG` |
+
+#### Scenario: 页面呈现
+
+- **WHEN** 用户打开 Plugins 页的 better-dsh 卡片
+- **THEN** 卡片显示 listing 文案描述与 6 个组件行，每行可独立开关
+
+#### Scenario: 行开关落盘
+
+- **WHEN** 用户关闭任一组件行
+- **THEN** profile 用户层 patch 追加该 id 的 `{disabled: true}` 覆盖行，HMR 即时卸载该组件；重新打开则移除覆盖
+
+### Requirement: 配置键迁移（行 = 配置归属）
+
+`urlSchemes`、`hashline`、`trustedPageAuthorities`、`mobile` SHALL 从 `dashr-repl` 的 Config schema 移除，改由所属行的 schema 承载（schema 级默认逐键填充，跨 patch 覆盖层存活——v0.2.2a 裁决的延续）。config-file 用户改以行 id 为目标。
+
+#### Scenario: 行级 gates
+
+- **WHEN** `dashr-url-schemes` 行配置 `hashline: false`
+- **THEN** hashline read 锚点与 edit/undo 家族不安装，captured 原生 read 独立站立（既有 gate 语义不变，只是配置位置从核心行移到本行）
+
+### Requirement: 行间无注入边，排序无关
+
+任何组件行 SHALL NOT inject 另一组件行提供的服务；行为正确的唯一跨行约束——**capture-before-mask**（url-schemes 的继承面快照必须在 wire mask `restrict({deny})` 之前完成，快照保存被 mask 的委派工具定义）——SHALL 由 mask 监听器自身保证：mask 监听器第一步调用共享模块 `native-capture`（单例 chunk）的 `captureAllTools(agent)`（幂等，WeakMap 缓存），随后才 restrict。两个入口行（entry）的激活顺序因此无关紧要。
+
+#### Scenario: 顺序反转仍正确
+
+- **WHEN** cordis 激活顺序使 mask 监听器先于 url-schemes 的 session-start 监听器运行
+- **THEN** mask 先经 `captureAllTools` 固化 pre-mask 全量快照再 restrict；url-schemes 随后的 `captureNativeTools` 命中同一缓存，wrappers 照常安装（own-layer 注册不受已落限制过滤）
+
+#### Scenario: url-schemes 行关闭时桥不断
+
+- **WHEN** `dashr-url-schemes` 行关闭、`dashr-repl` 行开启
+- **THEN** mask 监听器的 capture 步骤照常固化快照，captured 委派工具定义仍可供读取；eval 与委派桥正常工作
+
+### Requirement: 双腿 boot script
+
+`buildBootScript` SHALL 拆为两个纯函数腿构建器：`buildTrustScript`（authorities 段）与 `buildMobileScript`（`__DASHR_MOBILE__` + zoomGuard 段），各自为空即注入 nothing；两行各自注册 `webserver/index-inject` 监听器（list 事件，`table.push` 天然可组合）。
+
+#### Scenario: 单腿开关
+
+- **WHEN** `dashr-mobile` 行关闭而 `dashr-web-trust` 行开启
+- **THEN** 页面仍注入 authorities 腿脚本，`__DASHR_MOBILE__` 缺席，client 移动手势/zoomGuard 保持惰性（client 半无改动，读页面全局缺席即休眠）
+
+### Requirement: override 行保持原样
+
+compaction 再启用三条（`compaction-basic`/`command-compact`/`tool-result-pruner`）与 `connection` fence 行 SHALL 保持 override 行形态。原生页面不列出 override 行（把再启用做成 insert 需 fork 上游插件模块，不采纳）。
+
+### Requirement: 描述单源
+
+package.json `description` SHALL 逐字采用 awesome-dsh-plugins listing 的 en 文案，使 Plugins 卡片与市场 listing 单源一致。
+
+## Out of Scope
+
+- npm publish（另行裁决，按发布红线走两道闸）。
+- `plugins.row.config` / `plugins.bundle.config` 配置表单（本变更只要求原生行开关；行配置仍走 config file）。
+- client half 改动（页面全局缺席即休眠的既有形态已满足）。

package/docs/20_specs/preact-ui-shell/spec.md

@@ -0,0 +1,22 @@
+# preact-ui-shell Specification
+
+## Purpose
+为测试线（test-line）的 `apps/web` shell 提供构建期 React 家族到 `preact/compat` 的 vite alias patch：上游 ui-* 插件 bundle 的 `require("react")` 零改动获得 Preact 实例，shell 体积随之显著缩减。该 patch 仅限测试线 checkout，随 tag 切换重放；是否随插件包发布 dist 由 ship 决策另行裁决、暂缓。
+
+### Requirement: Preact-shell build for the web UI
+The test-line harness build SHALL support building the web shell (`apps/web`) with the React family aliased to `preact/compat` (including `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`, `react-dom/client` subpaths) via a build-time vite alias, so the platform module seed materializes Preact instances and every upstream client plugin bundle's `require("react")` receives Preact with zero upstream component edits. The alias SHALL be a monorepo-local build patch (documented, re-applied on tag switches), never an upstream source fork.
+
+#### Scenario: Shell serves the UI with Preact
+- **WHEN** the test-line instance is rebuilt with the alias patch and a browser loads the served UI
+- **THEN** the full upstream UI corpus mounts (sidebar/workspace/settings/chat), the session reports zero `pageerror` and zero `console.error`, and the shell bundle contains no `react-dom` production banner while carrying `preact` identity
+
+#### Scenario: Size regression is measured, not assumed
+- **WHEN** the alias build completes
+- **THEN** the shell `index` chunk (where the React family rides) is measured against the stock build and the delta recorded in the change report
+
+### Requirement: Test-line-only scope pending a ship decision
+The alias patch lives in the harness checkout only. The published plugin package (`@pgmi-builds/better-dsh`) SHALL NOT silently fork the web-UI serve surface: shipping a Preact-built frontend dist through the plugin (web-runtime override rows) is a separate decision gated on the prod host version upgrade, because a shipped dist freezes the UI corpus at the fork point.
+
+#### Scenario: Plugin publish content unchanged by this change
+- **WHEN** the next plugin alpha is published after this change
+- **THEN** the Preact enhancement is not part of the published artifact; the report records the ship-in-plugin option (dist + override rows) and its corpus-freeze trade-off as a pending decision tied to the prod host upgrade

package/docs/20_specs/repl-dispatch-resilience/spec.md

@@ -0,0 +1,21 @@
+# repl-dispatch-resilience Specification
+
+## Purpose
+REPL（`eval` cell）子分派的韧性契约：分派层的任何错误——调度器缺失、工具体抛错、取消——都必须 settle 为 cell 可见的 `ToolCallError` 结果，绝不外泄为 unhandled rejection 或使宿主进程崩溃。生产组合必须把带 `TOOL_RUNTIME_SCHEDULER` symbol 的原生 `ToolRuntime` 实例解析给插件，测试组合与生产组合之间不得存在环境差异导致的静默行为分裂。
+
+## Requirements
+
+### Requirement: Dispatch errors settle as visible ToolCallError
+The system SHALL resolve the plugin's tools service to the native `ToolRuntime` instance carrying the `TOOL_RUNTIME_SCHEDULER` symbol in the production composition, so REPL sub-dispatches execute through the same staged scheduler as the agent loop and return real tool results to the cell. The symbol this plugin imports SHALL be identical (`===`) to the one keying the mounted instance — a second dsh-tools module copy reachable from the deployed plugin (e.g. stray nested `@deepseek-ai` symlinks) breaks that identity and is a deployment defect (2026-09-02 corrected root cause; the plain `runtimeCtx.tools` read is the sanctioned resolution path). A mount whose tools service genuinely lacks the symbol SHALL be treated as a loud, diagnosable configuration failure — the error names the plugin's own `dsh-tools` resolution path — rather than a silent runtime crash, and that loud failure SHALL be the abnormal fallback, not the normal production state.
+
+#### Scenario: Production mount carries the scheduler symbol
+- **WHEN** the DASHR plugin mounts in the production composition and a cell dispatches a real tool call
+- **THEN** the dispatch executes through `registry[TOOL_RUNTIME_SCHEDULER]` and returns the tool result to the cell without crashing the daemon
+
+#### Scenario: Legitimate cell tool call returns its real result
+- **WHEN** a cell dispatches a legitimate tool call (e.g. `tool.read({ path })`) in a live session after the fix
+- **THEN** the cell receives the tool's actual result, not the `TOOL_RUNTIME_SCHEDULER` loud error
+
+#### Scenario: Regression probes pass after the fix
+- **WHEN** the four probe cells from the diagnosis matrix (`tool.subagent` background:false, `tool.subagent` background:true, `tool.bash` background:true, `tool.read`) run in a live session after the fix
+- **THEN** all four return a real result (or a visible `ToolCallError` where the call is legitimately invalid) instead of truncating, and the journal contains no new daemon crash

package/docs/20_specs/skill/spec.md

@@ -0,0 +1,58 @@
+# skill Specification
+
+## Purpose
+
+Let the model address skill bodies and internal skill resources via `skill://` URLs, with discovery tied to the same workspace source that advertises skills, and replace the skill tool's body-loading role on the REPL surface.
+
+## Requirements
+
+### Requirement: Skill body addressing
+The system SHALL let read accept `skill://<name>` and return that skill's SKILL.md body in full text (no default truncation; only explicit selectors page).
+
+#### Scenario: Reading an existing skill
+- **WHEN** the model reads `skill://<registered skill name>`
+- **THEN** the system returns the skill's body text in full
+
+#### Scenario: Reading an unknown skill
+- **WHEN** the model reads `skill://<unregistered name>`
+- **THEN** the system returns the structured `URL_SKILL_NOT_FOUND` error ("unknown or no longer available")
+
+### Requirement: Skill internal resource addressing
+The system SHALL let read accept `skill://<name>/<path>` and return the named file inside the skill's resource directory, loaded through the sandboxed filesystem (same containment/audit rules as host reads). A skill without a filesystem resource directory returns `URL_SKILL_NO_RESOURCE_BASE`; a subpath escaping the directory returns `URL_SKILL_RESOURCE_ESCAPE`.
+
+#### Scenario: Reading a referenced skill file
+- **WHEN** the model reads `skill://foo/references/x.md`
+- **THEN** the system returns the content of `references/x.md` inside foo's resource directory
+
+#### Scenario: Resource path escapes the skill directory
+- **WHEN** the model reads `skill://foo/../../etc/passwd`
+- **THEN** the system returns the structured `URL_SKILL_RESOURCE_ESCAPE` error and reads nothing
+
+### Requirement: Workspace-cwd-sensitive discovery
+The system SHALL pass the calling agent's session cwd (`{cwd: agent.session.header.cwd}`) to every skill-registry lookup — the same source `dsh-tool-skill` uses to render `<available_skills>` — so `skill://` can address exactly the skills the catalog advertises for the current workspace.
+
+#### Scenario: Skill visible in the current workspace
+- **WHEN** the model reads `skill://foo` from a session whose cwd is inside a project root that provides foo
+- **THEN** the lookup succeeds and the body resolves
+
+#### Scenario: Skill outside the workspace is unknown
+- **WHEN** a skill's project roots do not cover the session cwd
+- **THEN** the lookup misses and the system returns `URL_SKILL_NOT_FOUND`, matching what `<available_skills>` advertised
+
+### Requirement: Path-backed search view
+The system SHALL expose the handler's `resolvePath`: `skill://<name>` maps to the skill's resource-directory root and `skill://<name>/<subpath>` to the joined file (same escape guard), letting grep/glob search the real files; unmappable URLs (unknown skill, non-directory resource base, escaping subpath) resolve to `undefined` so callers fall back to text resolution with its structured error.
+
+#### Scenario: grep searches the skill's real directory
+- **WHEN** the model greps a `skill://foo` URL
+- **THEN** the search runs natively over foo's on-disk resource directory
+
+### Requirement: Skill tool masked on the REPL surface only
+The system SHALL mask the upstream `skill` tool presentation-only (ADR-0002): it disappears from the REPL `tool.*` binding names and the dashr tool-catalog section, while the host-layer native `skill` tool stays registered and executable and the `<available_skills>` discovery catalog is retained.
+
+#### Scenario: Skill absent from the REPL surface
+- **WHEN** the model inspects the kernel tool bindings or the tool-catalog text
+- **THEN** neither contains `skill`, and `skill://` URLs remain the addressing path for skill content
+
+#### Scenario: Host-native skill tool survives
+- **WHEN** any host-plane consumer dispatches the native `skill` tool directly
+- **THEN** the tool remains registered and executable — the mask touched only presentation surfaces