better-dsh 0.2.3 → 0.2.4

package/docs/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/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/upstream-dsh-0.1.5-rc.2-report.md

@@ -0,0 +1,156 @@
+# upstream dsh npm 版本对账：prod 0.1.3-alpha.2 → 0.1.5-rc.2
+
+> 生成时间：2026-09-10（本地时区）
+> 数据源：npm registry（`@deepseek-ai/dsh`）元数据 + `upstream/deepseek-harness` git tag 对账
+> 目标：回答「npm 上比 prod 更高的版本是什么、diff 有多大、对 prod 意味着什么」
+
+---
+
+## 〇、一句话结论
+
+prod 当前跑 **`@deepseek-ai/dsh@0.1.3-alpha.2`**。npm 上比它高的版本是整条 **0.1.5 线**（`alpha.1 / alpha.2 / rc.1 / rc.2`，**0.1.4 从未发布，直接跳号**）。最高版本是 **`0.1.5-rc.2`**（挂在 `next` dist-tag，而 `latest` 还停在 `0.1.5-rc.1`）。
+
+这条 0.1.5 线是**大版本级聚合**：846 commits、3170 文件、约 10.4 万行新增。核心是 **Session 格式 v3 重写**（会话持久化契约变更，对 prod 是**破坏性升级，不可 drop-in**），外加 Electron 桌面打包、Sidebar/dockkit 重构、文件交付「present」工具、图渲染预览、模型默认值切换（DeepSeek V41 Flash）等一批功能。**升级 prod 前必须按 AGENTS.md §一/§二 走对齐轮，不能只换版本号。**
+
+---
+
+## 一、版本全景
+
+npm registry 当前 dist-tags：
+
+| dist-tag | 指向版本 |
+|---|---|
+| `latest` | 0.1.5-rc.1 |
+| `next` | **0.1.5-rc.2**（最高） |
+| `alpha` | 0.1.5-alpha.2 |
+
+比 prod（0.1.3-alpha.2）更高的版本，按发布顺序：
+
+| 版本 | npm 发布时间 (UTC) | dist-tag |
+|---|---|---|
+| 0.1.5-alpha.1 | 2026-09-08 15:57 | — |
+| 0.1.5-alpha.2 | 2026-09-09 14:41 | `alpha` |
+| 0.1.5-rc.1 | 2026-09-10 03:12 | `latest` |
+| **0.1.5-rc.2** | **2026-09-10 14:57** | `next` |
+
+> 注意点：`latest` 并不指向最高版本（rc.1 vs rc.2）；「最高版本」= `next` 上的 **0.1.5-rc.2**。0.1.4 未在 npm 出现过。
+
+对应 git tag（本地 `upstream/deepseek-harness`，已 fetch）：
+
+```
+dsh-v0.1.3-alpha.2  2026-09-07 19:45 +0800   ← prod 当前
+dsh-v0.1.5-alpha.1  2026-09-08 23:25 +0800
+dsh-v0.1.5-alpha.2  2026-09-09 22:13 +0800
+dsh-v0.1.5-rc.1     2026-09-10 09:36 +0800
+dsh-v0.1.5-rc.2     2026-09-10 21:50 +0800
+```
+
+---
+
+## 二、diff 规模
+
+`dsh-v0.1.3-alpha.2 .. dsh-v0.1.5-rc.2`：
+
+| 指标 | 值 |
+|---|---|
+| commits | **846** |
+| 文件 | 3170 changed |
+| 行 | +103,990 / −17,687 |
+| 源码侧（排除 snapshots/tests） | 2474 文件，+68,818 / −13,973 |
+
+分段 commit 分布：
+
+| 区间 | commits |
+|---|---|
+| 0.1.3-alpha.2 → 0.1.5-alpha.1 | 563（大头，聚合了 Session V3 与一堆 feature） |
+| 0.1.5-alpha.1 → 0.1.5-alpha.2 | 262 |
+| 0.1.5-alpha.2 → 0.1.5-rc.1 | 17 |
+| 0.1.5-rc.1 → 0.1.5-rc.2 | 4（收尾/backport） |
+
+---
+
+## 三、依赖面变化（对 prod 直接可见）
+
+prod 0.1.3-alpha.2 有 **71 个 dependencies**，0.1.5-rc.2 有 **72 个**。差异：
+
+1. **新增运行期包 `@deepseek-ai/dsh-tool-present`**（`packages/fs/tool-present`）——新「present」工具：把 agent 产出的文件以不可变交付卡片（download card）呈现，是文件交付特性的宿主半。
+2. `apps/cli` devDeps 新增 `@deepseek-ai/dsh-agent-loop`、`@deepseek-ai/dsh-agent-loop-testkit`（内部，不影响 prod 运行面）。
+3. 新增 client 包 `ui-deliverables`（`PresentRow` / `PresentedFileCard` / `present-open`），属 web shell 交付卡片 UI。
+4. 其余全部 `@deepseek-ai/*` 依赖整体从 `^0.1.3-alpha.2` 抬到 `^0.1.5-rc.2`（同版本号齐步，无个别漂移）。
+5. 底层 `cordis` / `schemastery` / `commander` / `js-yaml` 等版本**未变**（`cordis ^4.0.2`、`schemastery ^3.18.2` 等，与 0.1.3-alpha.2 相同）。
+
+---
+
+## 四、主要变更主题（按 prod 相关度排序）
+
+### 1. Session 格式 v3 重写（⚠ 破坏性，最高风险）
+`session-log-v3` 工作线，是本次最大的变更块。要点：
+
+- 会话身份 **V2 → V3 迁移**（`feat(session): add identity V2-to-V3 migration and writer skeleton`）。
+- system prompt 表示为 **surface node zero**（`refactor(session): represent the system prompt as surface node zero`）。
+- **canonical envelopes**、PTC durable vocabulary、in-history system prompt 表示、JSONL 跨进程写所有权（lease）。
+- 大量 `session.v3.jsonl` 快照与 V2/V3 迁移覆盖面单测。
+
+> **对 prod 的含义**：会话持久化契约改变。上一轮（0.1.3-alpha.2 对齐）已实测：上游 tag diff 会打到 `session-persistence-omp.ts` / `replay.ts` / store 的 handle+lease 契约（见 2026-09-08 对齐报告）。**0.1.5 的 V3 比 0.1.3 的 V2 更进一步，破坏面更大**，`better-dsh` / `omp-web` 这类桥接会话数据的插件必须重新对齐，不能 drop-in。
+
+### 2. Electron 桌面打包（对 3080 web 无直接作用）
+Windows/macOS/Linux 构建、mac 签名+公证、Windows 签名、auto-update、IPC 性能优化。纯桌面宿主线，与本机 `dsh web`（3080）部署无关，但意味着上游发布面从此多一个桌面产物。
+
+### 3. Sidebar / dockkit 重构
+- `dockkit` 可逆停靠引擎、pointer 交互。
+- 全局 sidebar panel、tab 导航、live tab 标题 + 文件类型图标、末 tab 关闭规则、响应式右栏、全屏 shell。
+- session-log 控制移入 header「更多」菜单。
+
+### 4. 文件交付「present」工具 + 文档预览
+- 新 `dsh-tool-present` 包：不可变文件交付下载卡片、artifact 卡原生文件动作、workspace 文件操作。
+- 可扩展文档预览、文本预览分页 tab、文件类型图标集、`ui-deliverables` client 卡。
+- `feat(fs)`：bounded byte-range reads（fs-local / fs-e2b）、dual-face 文件 API。
+
+### 5. 图表 / Markdown 预览
+Chat 代码块内预览 Mermaid / Graphviz / SVG / HTML fence，适配应用主题。
+
+### 6. LLM 模型默认值切换（⚠ 影响 prod 行为）
+- Chat Completions 默认切到 **DeepSeek V41 Flash**（`feat(llm): default Chat Completions to DeepSeek V41 Flash`）。
+- 保留 V4 模型、恢复 V4 Flash Vision Exp catalog 条目。
+> prod 若升级，默认模型会跟着变；需确认是否期望。
+
+### 7. Feedback 对话框
+`/feedback` 与 Dislike 统一为一个带分类的对话框 + toast。
+
+### 8. Subagent catalog
+记录并观察 parent-owned child catalog（子代理目录）。
+
+### 9. native system / node-addon-system
+包族改名 `node-addon-system`，预编译 Node-API flock、Landlock capability 子路径。**新增原生依赖面，升级安装需留意 prod 机上的原生构建/预编译匹配**（本机已有一处 zeromq allowBuilds 特例，见 AGENTS.md §二）。
+
+### 10. minimal profile 行为调整
+- `str_replace_editor` 从 minimal profiles 移除。
+- persistent bash 输出与 one-shot shell 契约对齐。
+> 只影响 minimal profile，不影响 prod `web` profile 的默认工具集。
+
+### 11. 其它
+- CLI：从 shipped 模板创建 profile。
+- skills：Playwright 视频录制 GIF。
+- 内部 CI/审查自动化（weighted PR approval、review owner 排名等）——与 prod 运行无关。
+
+---
+
+## 五、对 prod 升级的风险评估（简要）
+
+| 风险项 | 级别 | 说明 |
+|---|---|---|
+| Session V3 格式迁移 | 🔴 高 | 会话持久化契约变更；`better-dsh`/`omp-web` 会话桥接面需重新对齐，先例（0.1.3 V2）已证实非 drop-in |
+| 模型默认切 V41 Flash | 🟠 中 | 默认行为变化，需 user 确认是否接受 |
+| 新原生依赖（node-addon-system） | 🟡 中低 | 安装面原生构建/预编译匹配；本机 pnpm strictDepBuilds/allowBuilds 需复核 |
+| 新工具 `dsh-tool-present` | 🟡 中低 | 新工具进入 agent 运行时，需确认与现有工具/插件无 id 冲突 |
+| Sidebar/dockkit UI 重构 | 🟢 低（功能面） | 纯增量 UI，但 better-dsh 的 mobile 手势/侧栏 patch 需复测是否仍对齐 |
+| Electron 桌面 | ⚪ 无关 | 不影响 web 部署 |
+
+---
+
+## 六、建议
+
+1. 本次**只做对账、不做升级**：0.1.5 是聚合大版本，且含 Session V3 破坏性契约变更，不能当「换版本号」处理。
+2. 若后续要升级，按 AGENTS.md §一/§二走 **Dev/Test 1（4999 源码级）对齐轮**：切 `dsh-v0.1.5-rc.2` → 重放三处本地 patch（storeDir / unrun devDep / resolveRepositoryRoot）→ install/build → 插件契约对齐（重点 `session-persistence-omp.ts`/`replay.ts`/store 的 V3 handle+lease）→ tsc/单测 → 4999 第一人称实测 → 报告落 `docs/50_test-reports/` → user 确认 → 才动 prod 3080。
+3. 升级目标版本**首选 `0.1.5-rc.2`（`next`）而非 `latest`（rc.1）**，因为 rc.2 才是最高版本；但 rc 阶段仍建议等上游正式 stable 后再定。
+4. 升级前单独确认模型默认值（V41 Flash）是否要在 prod 生效。

package/dsh-docs/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
+## Writing rules
+
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
+- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
+
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
+- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Cross-reference with machine-checkable links, never free prose
+
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).

package/dsh-docs/agent-lifecycle.md

@@ -0,0 +1,84 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>assistant/attempt</code>
+    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
+
+`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
+
+The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
+
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

package/dsh-docs/agent-lifecycle.zh.md

@@ -0,0 +1,86 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
+
+# Agent 轮次与步骤生命周期
+
+[English](agent-lifecycle.md) | 中文
+
+此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>assistant/attempt</code>
+    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用，并嵌入精确的紧凑带时间 stream。空内容不会进入派生历史。失败、重试、取消或 stream error attempt 到达 settlement 时，如果没有 surface message，就会把 stream 记录为 `assistant/attempt`。实时 `agent/assistant-stream` chunk frame 是瞬态数据；回放读取任一种持久 settlement，如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
+
+`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
+
+以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
+
+需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
+
+维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。