better-dsh 0.0.0 → 0.2.2-a

package/docs/50_test-reports/kernel-provisioning.md

@@ -0,0 +1,44 @@
+# DASHR Kernel 供给（iKernel Provisioning）
+
+> One page（June R1.6 落实地）：dashr REPL 的 IPython kernel 由插件**全责供给**——位置、版本、触发时机、修复出路。对应 spec：`openspec/specs/kernel-provisioning/`（change `2026-09-02-kernel-provisioning-completeness`）。
+
+## 原则
+
+- **完全体**：不提供"只有 REPL 界面没有解析引擎"的形态。kernel 装好、能用是插件的责任。
+- **独占**：kernel 只活在插件自有 venv（`<packageRoot>/.venv-kernel`，prod 即 web profile 内插件领地；`kernelEnvDir` 可显式覆盖）。永不写用户全局 Python，probe 永不 import 用户 site 模块。
+- **不随包分发 venv**：npm 包只带 JS 产物；"随包"= 随包携带**供给能力**，供给结果在现场生成。
+- **fail-open**：任何一级供给失败只留提示（含修复出路），绝不阻断 npm 安装、daemon 启动或插件挂载。
+
+## 版本锁定（测试跑通值）
+
+| 组件 | 版本 | 出处 |
+|---|---|---|
+| CPython | 3.11（uv 拉取；无 uv 时宿主 python3 亦验证兼容——3.14.4 实测通过） | `DEFAULT_KERNEL_PYTHON_VERSION` |
+| ipykernel | 7.3.0 | `IPYKERNEL_VERSION` |
+| dill | 0.4.1 | `DILL_VERSION` |
+
+升级 = 显式 change + 回归跑通后再改常量。
+
+## 两级触发（全部幂等、全部 fail-open；v0.2.2-a 起 postinstall 已移除）
+
+1. **daemon spin-up（主路径）**：插件随宿主 daemon 在 host 平面启动即异步检查/补装。**agent session 永远不会在首用时才发现缺 kernel**。在就 pass（毫秒级 probe），缺才装（数十秒）。
+2. **首用 lazy（最后兜底）**：`kernelAutoInstall` 默认 true，覆盖 spin-up 失败/被跳过的残余场景。
+
+> **v0.2.2-a 设计变更（owner 裁决 2026-09-03）**：移除 postinstall 加速器，npm 包现为**零 lifecycle script**。原因：pnpm 10+ 供应链策略下，未经消费方 `allowBuilds` 白名单的 build script 是安装**硬错**——发布日新装的 friction 全部由此而来，而 spin-up 主路径本就覆盖其职责（fail-open、daemon 启动即检查、毫秒级 probe）。`npm run kernel:venv`（包内 `scripts/kernel-provision.mjs` 保留发布）作为手动预置入口不变。
+
+## 供给梯子与环境加固
+
+- 有 `uv`：`uv venv --python 3.11` + `uv pip install ipykernel==7.3.0 dill==0.4.1`，且 **`UV_CACHE_DIR`/`UV_PYTHON_INSTALL_DIR` 重定向到 `<packageRoot>/.uv-cache`**、`UV_LINK_MODE=copy`——只读 `~/.cache`/只读 home 的主机不再被阻断（2026-09-03 实测：HOME chmod 555 下供给成功）。
+- 无 `uv`：`python3 -m venv` + `pip install`（ensurepip，无 cache 依赖；3.14.4 实测通过）。
+
+## 各 profile 速查
+
+| Profile | venv 位置 | 验证 | 修复 |
+|---|---|---|---|
+| prod（web profile 插件） | `~/.dsh/profiles/web/node_modules/@pgmi-builds/better-dsh/.venv-kernel` | daemon 日志见 `kernel ready`；REPL 首 cell 即时响应 | 在包目录跑 `npm run kernel:venv`；或设 `python` 指向已备解释器 |
+| dev/test 4999（monorepo 副本） | `packages/better-dsh/better-dsh/.venv-kernel` | 同上（stdout 可见 provisioning→ready） | 同上；rsync 后照常（.venv-kernel 在排除清单，不被 --delete 清掉） |
+| 显式覆盖 | config `kernelEnvDir` | — | — |
+
+## 状态与错误
+
+供给各阶段有日志（provisioning / ready / degraded-dill / failed）；失败信息列三条出路：`npm run kernel:venv`（手动）、`kernelAutoInstall: true`（首用自动装）、config `python` 指向已备解释器。

package/docs/50_test-reports/repl-kernel-provisioning-test-report.md

@@ -0,0 +1,87 @@
+# REPL Pad Kernel Provisioning — Test Report & Forward Requirement
+
+- Date: 2026-06-03
+- Scope: DSH Web GUI session — `eval` (dashr REPL pad) kernel lifecycle, `dvc://` device surface smoke check
+- Result: **FAIL on first-run → FIXED (manual provision) → PASS**; forward requirement recorded below for the next dev phase
+
+---
+
+## 1. What was tested
+
+| # | Test | Outcome |
+|---|------|---------|
+| T1 | REPL pad first cell after a cold runtime (`eval "print(6*7)"`) | **FAIL** — kernel failed to start (`worker-exit`) |
+| T2 | Root-cause probes: filesystem writability, toolchain presence | PASS (diagnosed EROFS on `uv` cache) |
+| T3 | Managed kernel venv provisioned with redirected caches | PASS |
+| T4 | REPL pad retest after provision (`eval`, state persistence probe) | **PASS** — `pad alive: 42`, CPython `3.11.15` |
+| T5 | `dvc://` device surface (`read dvc://`, `read dvc://browser`) | PASS — roster serves `ast_edit`, `ast_grep`, `browser`, `lsp` |
+
+## 2. Environment facts (this host)
+
+| Item | Value |
+|------|-------|
+| Root filesystem | `/dev/sdc3 / ext4 ro` — **read-only** (container/image layout) |
+| Writable bind mount | `/dev/sdc3 /home/u1/workspaces/dashr ext4 rw` only |
+| `uv` cache home | `/home/u1/.cache/uv` — **on the read-only root → EROFS** |
+| `uv` | `0.11.15` (present; preferred by kernel-env provisioning) |
+| System Pythons | `3.14.4` (default `python3`), `3.11.15` (`/home/u1/.local/bin/python3.11`) |
+| Pad runtime package | `packages/better-dsh/better-dsh` (managed venv default `<package>/.venv-kernel`) |
+| Managed venv (provisioned) | CPython `3.11.15`, `ipykernel 7.3.0`, `dill 0.4.1` |
+
+## 3. Failure & root cause
+
+**Observed** (first `eval` after cold start):
+
+```
+Error: code run failed (worker-exit): kernel failed to start:
+Command failed: uv venv .../.venv-kernel --python 3.11
+error: Could not acquire lock
+  Caused by: Could not create temporary file
+  Caused by: Read-only file system (os error 30) at path "/home/u1/.cache/uv/.tmpmqu7oz"
+```
+
+**Root cause**: the dashr runtime owns a *managed* kernel venv and provisions it on first use via `uv` when no explicit interpreter is configured (`kernel-env.ts`: `createVenv`/`installDeps`, `python: python3` sentinel → managed). `uv` always stages a lock temp file under its cache dir (`~/.cache/uv`, overridable via `UV_CACHE_DIR`). On this host the root FS (and therefore `~/.cache`) is genuinely read-only, so provisioning cannot even start — an environment-portability defect, not a code bug in the provisioning logic itself.
+
+Supporting facts: provisioning is **retry-safe** (`runtime.ts` clears a rejected `kernelEnvPromise` in `.catch`, so the next `eval` retries) and **idempotent** (`ensureVenv` reuses a complete venv — `ipykernel && dill` present — without invoking `uv` again).
+
+## 4. Remediation applied (this session, host-local)
+
+1. Probed writability: `/tmp` ✅, `/home/u1/.cache` ❌ readonly (confirmed), dashr package dir ✅, repo-local cache dir ✅.
+2. Provisioned the managed venv **at the runtime's default location** so future `eval`s skip `uv` entirely:
+
+```bash
+REPO=/home/u1/workspaces/dashr/upstream/deepseek-harness
+PKG="$REPO/packages/better-dsh/better-dsh"
+export UV_CACHE_DIR="$REPO/.uv-cache" \
+       UV_PYTHON_INSTALL_DIR="$REPO/.uv-python" \
+       UV_LINK_MODE=copy
+cd "$PKG"
+uv venv .venv-kernel --python 3.11
+uv pip install --python .venv-kernel/bin/python ipykernel dill
+```
+
+3. Verified interpreter: `OK 3.11.15 ipykernel 7.3.0 dill 0.4.1`.
+4. Re-ran `eval` → PASS (see T4). The complete venv is reused on every later start; no further `uv` invocation.
+
+Artifacts left on disk (build state, not tracked source): `<package>/.venv-kernel`, sibling `$REPO/.uv-cache`, `$REPO/.uv-python`.
+
+## 5. Forward requirement — R1 (next dev phase)
+
+> **Proper kernel provisioning at installation time is a requirement, across all environments (prod / dev / test).**
+
+First-run lazy provisioning must **not** be the only path: an environment where the interpreter cannot be provisioned at runtime (read-only root, no writable home/cache, air-gapped, no `uv`) currently bricks the REPL pad entirely. The coming dev phase must make kernel setup an explicit, environment-aware installation step.
+
+Proposed acceptance criteria (to be confirmed/refined in the dev plan):
+
+- **R1.1 Install-time provision hook.** `npm run kernel:venv`-equivalent (already exists) is promoted to part of standard install; runtime lazy-provision remains only as a fallback for writable dev hosts.
+- **R1.2 Environment profiles.** prod / dev / test each declare kernel policy: explicit interpreter path vs. managed venv dir, auto-install on/off, version pin (`kernelPythonVersion`), and fail-fast behavior — surfaced as config, not code (`kernelEnvDir`, `kernelAutoInstall`, `kernelPythonVersion` already exist in the runtime config schema).
+- **R1.3 Writable-cache independence.** Provisioning must set/respect `UV_CACHE_DIR` / `UV_PYTHON_INSTALL_DIR` (or fall back to `python3 -m venv` + `ensurepip`) so read-only `~/.cache` or read-only root never blocks the pad.
+- **R1.4 Verification gate.** Install/CI runs a probe (`import ipykernel, dill`) and fails loudly with the actionable message already implemented in `kernel-env.ts` (`run 'npm run kernel:venv' … or set kernelAutoInstall: true`).
+- **R1.5 CI coverage.** dev/test CI exercises a cold start (no venv) and a pre-provisioned start; prod smoke test asserts the pad boots on first `eval` (or fails fast at deploy).
+- **R1.6 Docs.** One page: how each profile's kernel is provisioned, verified, and repaired — this report's §4 command becomes the canonical snippet.
+
+## 6. Open items
+
+- Host `python3` default is 3.14 while the managed venv pins 3.11 — confirm the intended matrix (the runtime already probes/pins independently of PATH default).
+- Decide whether the GUI should surface kernel provisioning status/errors (today failures surface only through the `eval` error).
+- `/tmp` is writable here but tmpfs-reaped on reboot — prefer repo/home-adjacent venv dirs (current default already avoids `/tmp` by design; keep it).

package/docs/50_test-reports/upstream-dsh-0.1.2-alpha.5-local-test-report.md

@@ -0,0 +1,81 @@
+# 上游 dsh 0.1.2-alpha.5 本地实测报告（Dev/Test 1 源码级 4999 实例）
+
+- 实测日期：2026-09-02
+- 范围：upstream checkout 升级 alpha.3 → alpha.5、本地构建、4999 隔离实例启动、工具面冒烟、agent 侧功能实测（user 驱动）、session storage 热升级观察、web UI 手工核查（user）
+- 结论：**PASS —— 无破坏性更新，整体可跑起来；dashr 工具与界面介入 functionality 衔接正常，无大适配性问题**。3 项 UI/功能瑕疵记录在案，作为下一波 alignment 的 change 输入（§4）。
+
+前置调研见 `upstream-dsh-0.1.2-alpha.5-report.md`（alpha.3 → alpha.5 差异分析）。
+
+---
+
+## 1. 实测范围与结果
+
+| # | 测试 | 结果 |
+|---|---|---|
+| T1 | checkout `dsh-v0.1.2-alpha.5` + 本地 patch 重放（stash → checkout → stash pop） | ✅ patch 载体文件（`pnpm-workspace.yaml`/`tsdown.client.ts`）tag 间零改动，干净重放；备份 `.scratch/alpha3-local-patches-backup.patch` |
+| T2 | `pnpm install`（268 workspace projects，store 重定向 `.scratch/pnpm-store`） | ✅ EXIT=0（修两坑后，见 §2 备注） |
+| T3 | `pnpm run build` + better-dsh tsdown | ✅ tsc + tsdown host/client + vite web（220 client artifacts）+ 插件产物 |
+| T4 | 4999 实例启动（`DSH_HOME=.dsh-test`，与 prod 3080 完全隔离） | ✅ `dsh-root@0.1.2-alpha.5` 监听 127.0.0.1:4999，token URL 正常签发 |
+| T5 | 工具面冒烟（dump-config） | ✅ `dashr-repl` 工具行在、`DASHR_KERNEL_PYTHON` 注入正常；`tool-web` 为 `fetchProvider: http`，`web-fetch-http` 服务挂载——alpha.5 的 **web_fetch 默认开放**在本实例得到确认（base 层行为，含无审批匿名公网抓取，见调研报告专题二） |
+| T6 | web shell 冒烟（cookie jar + 303 认证链） | ✅ 根页 200（title: DSH Local Build）+ 新构建 asset（`/assets/index-*.js`）200 |
+| T7 | **session storage 热升级观察**（重点，见 §3） | ✅ 结构变更就地完成，全程无崩溃 |
+| T8 | agent 侧功能实测（user 在实例上驱动运行中的 agent） | ✅ dashr 工具与界面介入 functionality 均能衔接，整体无大适配性问题 |
+| T9 | web UI 手工核查（user） | ⚠️ 3 项瑕疵，见 §4（1 项为 dashr 计划特色未实现；2 项为 user 私人 patch 未适配） |
+
+## 2. 环境事实
+
+| 项 | 值 |
+|---|---|
+| Harness checkout | `./upstream/deepseek-harness`，detached at `dsh-v0.1.2-alpha.5`（db6bdc3576） |
+| 本地 patch（3 个，全部重放成功） | ① `tsdown.client.ts` REPOSITORY_ROOT 推导（本机 Node 22.22.1 无 native TS loader，必需）；② `pnpm-workspace.yaml` storeDir 重定向 + `verifyDepsBeforeRun: false`；③ 根 `package.json` 补 `unrun` devDep |
+| dashr 副本 | `packages/better-dsh/better-dsh/`（workspace 成员，npm-range peerDeps 靠 `linkWorkspacePackages` 解析） |
+| 用户数据 | `DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`（**携 alpha.3 时代存量数据直接升级**，这正是 T7 的观察对象） |
+| 实例 | `npm run dsh -- web --no-open --port 4999`；prod `~/.dsh` 全程未动 |
+
+本轮融资到的两个坑（已修，并已固化进 AGENTS.md）：
+
+1. **stale peerDep 复发**：rsync 从 canonical 带回 `@deepseek-ai/dsh-client-runtime` peerDep；alpha.5 workspace 已无此包、npm 亦无匹配 range 的版本 → `ERR_PNPM_NO_MATCHING_VERSION`。修法：副本 package.json 删该 peerDep + `peerDependenciesMeta` 条目（每次 rsync 后须重删）。
+2. **zeromq build 审批**：pnpm 11.7 插入的 `set this to true or false` 占位符在 strictDepBuilds 下为硬错误。修法：`allowBuilds` 显式 `zeromq: true`（zeromq 是 better-dsh 自己的 kernel IPC 依赖，必须放行）。
+
+另：`pnpm install | tail` 会吞退出码（本次正是靠 `pipefail` 抓到第一坑），流程里一律 `set -o pipefail`。
+
+## 3. 重点观察：session storage 结构性更新与热升级自愈（T7）
+
+**这是本轮实测最重要的一条记录：上游 alpha.5 自带的 session storage 热升级在真实测试实体上可观察地完成了——结构变了，系统没有崩溃。**
+
+背景（上游笔记 `.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md`）：`session_projcache` 域磁盘结构三代演进——v3（0.1.1-rc.2，单文件）→ v4（0.1.2-alpha.3，per-record `sessions/<sessionId>.json`）→ v5（0.1.2-alpha.4/5，同布局，identity 新增 `isSeeded`/`inheritedEventCount` lineage 字段）。alpha.5 的热修以声明式读兼容实现自愈：域声明 `version: 5, compatibleVersions: [3, 4]`，旧版本戳记录直接读入，**读到旧记录后的下一次 checkpoint 自然把它重写为当前版本**；schema 兜底 `backup-and-skip`（改名 `.bak.<ts>` 留档跳过），取代此前"整域拒开/列表丢标题"的故障模式。
+
+本实例的磁盘证据（`.dsh-test/storages/`，时间线）：
+
+| 观察 | 事实 | 解读 |
+|---|---|---|
+| 存量保留 | `session_projcache/` 目录 mtime 停在 16:44（alpha.3 建域时刻）原地保留 | 升级未清场、未迁移重摆 |
+| **热升级写回** | `sessions/session-2547aab1….json`（createdAt ≈ 16:44，**与 alpha.3 建域精确吻合的旧会话**）mtime 21:48（alpha.5 运行期），内容已是 `"version": 5` 且带 `isSeeded`/`inheritedEventCount` | v4 旧记录被读兼容接受后，checkpoint 重写为 v5——**"自愈"的直接物证** |
+| 新写会话 | 23:31 起新会话文档 `version: 5` 正常写入（新 id 无 `session-` 前缀） | 新版本戳写入路径正常 |
+| 混版本共存 | 23:36/23:48 仍有 `version: 4` 新文档落盘（cwd=`.scratch/acp-playground`；**已确认（user）：另一 agent 的 dsh ACP 测试共享 `.dsh-test` profile**——隔离分区、共享测试 profile，属预期形态），与 v5 文档同域共存、SessionList 照常服务 | 读兼容不仅容忍存量，也容忍**并发旧版本写入**（新老实例并发共享一个 home 的额外压力证据） |
+| 无崩溃 | 整个测试窗口（含 user 交互实测至 23:49）实例持续服务 | "没有发生破坏性崩溃"——虽然结构变了，升级对使用侧透明 |
+
+结论：对将来的 prod 升级（目前 prod 仍为 alpha.3 = v4 home）而言，本轮等于在隔离实体上预演了同一条升级路径（v4 home → alpha.5），**存储侧无阻断性风险**。
+
+## 4. 发现的瑕疵（下一波 alignment 的 change 输入）
+
+| # | 现象 | 定性 | 去向 |
+|---|---|---|---|
+| P1 | Settings > General 未见 **Model Failover** 功能 | dashr 计划中的特色功能，尚未实现——非 alpha.5 回归 | 排入 dashr 下一波开发 |
+| P2 | **Loopback Auth Patch** 未生效：Settings > Models 显示 "loading the provider directory failed"，模型清单不出 | user 私人 patch（不随 dashr ship）；alpha.4/5 对 provider directory 相关代码有改动，patch 触点漂移 | alignment change：为 patch 重定位触点 |
+| P3 | **Mobile Responsiveness UI Patch** 未生效：移动端右侧栏未隐藏（宽度不为 0），手指左右滑动交互失效 | user 私人 patch（不随 dashr ship）；布局逻辑向 CSS 迁移（调研报告专题一）后原 JS 侧挂点失效 | alignment change：改走 CSS/语义属性路线重做 |
+
+dashr 本体（工具注册、REPL pad、界面介入）：无适配性问题（T5/T8）。
+
+## 5. 流程化产出（本轮已落地）
+
+1. **`.agents/skills/upstream-alignment/SKILL.md`**：把"上游插件项目的版本对齐"固化为可复用技能——checkout 最新上游 → wire 最新插件 → 验证运行 → 发现的不足作为下一波 change。本轮 alpha.5 实测即其首次全流程演练。
+2. **AGENTS.md 部署规范**：新增"user, just another user"生产部署原则（registry 同源安装：npm 主体 + npm/plugin-market 插件），与 dev/test 源码路径（第二、三节）正式分离。
+
+## 6. Open items
+
+- ~~确认 §3 混版本共存中 v4 新文档的确切写入方~~ **已确认（user 2026-09-02）**：另一 agent 的 dsh ACP 测试共享 `.dsh-test` profile（隔离分区、共享 profile），v4 新文档即其写入，属预期测试形态。
+- P2/P3 两个 user 私人 patch 在 alpha.5 下的重适配（触点重定位 / CSS 路线重做）。
+- P1 Model Failover 的设计与排期。
+- dashr web UI 卡片半边（`build-client`）在 monorepo 内仍未跑（沿用既有记载，需要时再补）。
+- prod（3080）升级决策：本轮存储侧与插件侧均无阻断项；升级时按调研报告专题二复核工具面（base 默认多出无审批 `web_fetch`）。

package/docs/50_test-reports/upstream-dsh-0.1.2-alpha.5-report.md

@@ -0,0 +1,93 @@
+# 上游 dsh 0.1.2-alpha.3 → 0.1.2-alpha.5 改进调研报告
+
+- 调研日期：2026-09-02
+- 方法：npm tarball diff（伞包仅版本号与 vendored 树增删变化）+ upstream git tag diff（`dsh-v0.1.2-alpha.3..alpha.5`，2391 文件 +30k/−21k）+ 仓内 `.agents/notes/implemented/` 设计笔记（上游每个决策都有 as-built 笔记，本报告的结论均有笔记或 diff 直接佐证）
+- 版本事实：alpha.4（09-01）为大批量发布（~8.5k agent 生成的 commit，重测试/文档）；alpha.5（09-02）为 4-commit 存储安全热修。`latest` dist-tag 仍为 0.1.1-rc.2，本线仅在 alpha 通道。
+
+---
+
+## 专题一：前端布局逻辑迁移到 CSS
+
+### 1.1 动机：不是"React 太重"，而是"JS 驱动的布局测量太贵"
+
+React 本身没有被替换——组件、store、渲染管线全部保留。被替换的是**用 JS 读 DOM 几何、再写回样式**的那类"布局反应性"代码。三个典型案例（均有 commit diff 实证）：
+
+**案例 A — ReasoningRow（`perf(ui-chat): move reasoning tail alignment to CSS`，203e2440ac）**
+- 之前：组件持有一个 40 行的 `use-throttled-visual-update` hook，每次流式文本更新后同步读 `scrollWidth`/`clientWidth` 再写 `scrollLeft`，把"推理摘要跟随末尾"对齐。这是教科书式的 forced synchronous layout（读-写-读交替触发反复强制布局），且发生在**每个流式 token 到达时**。
+- 之后：hook 整个删除；对齐改为 `data-follow-end` 属性 + CSS `display:flex; justify-content:flex-end; min-width:100%`，浏览器原生完成尾部跟随，零 JS。
+
+**案例 B — MessageIconActions（`derive user action reveal in CSS`，f808112ec8）**
+- 之前：每个用户消息组件订阅 conversation store，倒序遍历节点序列计算"我是不是最新用户行"，决定操作按钮常显/悬停显——转写一变就可能触发一批组件重渲染。
+- 之后：store 订阅与 `reveal` prop 全部删除；CSS 用 `:has(~ :is([data-chat-flow-kind='user'],…))` 兄弟选择器从 DOM 结构直接推导"后面还有没有更新的用户行"。
+
+**案例 C — ProducedFiles（`move overflow sizing to CSS`，e5bbee893b + 笔记 `2026-09-01-css-produced-file-layout`）**
+- 之前：产出文件行在隐藏探针树里**复制每个候选 chip**，layout effect 同步读 computed style 与元素几何，行或探针 resize 时反复重测——只为算"一行放得下几个文件名"。
+- 之后：探针树、resize observer、布局 state、几何读取全部删除；改为 inline-size 容器查询 + 预设宽度档位（`@container (max-width: 687/583/479/375px)` 四档，每档预算 = 96px/chip + 8px gap + 64px 剩余标签），flex 收缩 + ellipsis 兜底。
+
+**判断依据是逐案取舍，不是教条**：同一波里 `aad1ce0c68 perf(ui-chat): retain the stats resize observer` 明确保留了 StatsLine 的 resize observer——CSS 表达不了的真实内容测量仍留在 JS。配套的流式性能潮（每 2–3 帧发布一次流式更新、滚动几何采样节流）说明整体背景：流式会话让主线程每秒都在跑布局相关代码，把能下沉到 CSS 的布局反应性下沉，是性价比最高的削减。
+
+结论：**转变的动因是性能（layout thrashing / per-frame observer 与 state churn），而非框架更换或 React 本身太重**。
+
+### 1.2 解耦与维护维度：CSS 是静态资产，store 驱动的 DOM 自适应
+
+先回答核心疑问：**CSS 不随 store 动态增加或减少。它就是你猜的第二种——构建期静态资产，所有可能形态预定义在样式表（甚至预渲染在 DOM）里，React 产生的模块去自适应。**
+
+机制拆解（对照"基础组件 → 中间层转译 → 统一 store → 渲染层"的既有心智模型）：
+
+1. **store → 转译/slot → React 的管线完全没动**。变化只在渲染产物这一段：从"JS state 驱动布局"改为"语义属性 + 静态 CSS"。
+2. **CSS 载体是 CSS Modules**（`*.module.css`，与组件同目录，构建期编译打包）。alpha.3 → alpha.5 ui-chat 包内 `.module.css` 数量不变（16 → 16），不存在运行时生成/注入 CSS 的通道。
+3. **耦合面是一张有界的语义属性词表**：`data-chat-flow-kind={routedNode.kind}`、`data-follow-end`、`data-shown='N'`、`data-pending-steering`……全部是渲染时从节点数据**一次性落下的静态标注**。store 变化 → React 重渲染 → 属性/内容更新 → CSS 选择器（container query、`:has()`、media query）自动反应。CSS 侧永远不感知 store 结构。
+4. **"所有变体预渲染 + CSS 挑选"**：ProducedFiles 每行至多渲染 6 个 chip 加一组预渲染的本地化 `+ N files` span，CSS 档位只让其中 0 或 1 个可见——所有分支都在 DOM 里，由 `@container` 决定显隐，不做运行时测量。
+
+**是否多了一个维护维度？是，但有界、且被上游显式文档化并测试锁定**：
+
+- 代价 1：变体必须预渲染，DOM 略胖（每行多几个短 span）。
+- 代价 2：档位断点与布局预算强耦合——改 chip 最大宽/间距要同步改四档断点（预算以局部 CSS 自定义属性 `--produced-file-chip-max`/`--produced-file-gap` 为准，笔记里写明了换算）。
+- 代价 3：语义属性词表成为 React 侧与 CSS 侧的契约，两侧需同步演进；行为由 client spec + e2e 锁定（单行、无横向溢出、响应式省略、无悬停设备回退）。
+- 代价 4：**精度换确定性**——固定档位忽略实际文本宽度与本地化标签宽度，可能比精确测量多/少显示一个 chip。上游在笔记里明确接受了这一近似（`+ N files` 计数始终准确）。
+
+对比维护成本：删掉的是每组件一份的 observer + layout effect + 布局 state + 几何读取（每处 40–140 行 JS），换来的是一份静态样式表里的几十行声明式规则。上游把这类改动归档在 `simplification/`（简化）而非 `architecture/`（架构）目录——他们将其定性为**净删减复杂度**。
+
+---
+
+## 专题二：web_fetch 默认开放的含义
+
+**是什么**：共享基础 bundle `dsh-base` 的 `tool-web` 配置从 `fetch: false` 改为 `fetch: true`（`packages/bundle/base/cordis.patch.yml`）。即 `web_fetch` 从"各产品层各自 opt-in"变为 **base 层默认挂载的模型工具**。
+
+**之前（alpha.3 及更早，笔记 `2026-07-31-web-default-search`）**：base 只默认暴露 `web_search`；`web_fetch` 需要产品层逐个 override 开启（Web 的 cordis/ptc/standard presets、headless、full SDK 开了），ACP 被漏掉，新建 base-only profile 默认没有 fetch，快照头也因此按产品分裂。
+
+**之后（笔记 `2026-09-01-shared-base-web-fetch-default`）**：所有已交付完整产品对匿名公共抓取的策略已收敛一致，重复 override 不再编码任何产品差异，于是上收到 base：
+
+- headless / full SDK / **ACP** / 自定义 base-only profile 全部直接继承 `web_search` + `web_fetch`，零应用层 override；
+- Web app 改为禁用 base 的 tool-web 行、按 agent preset 组合同样一对工具（行为不变，配置位置变化）；
+- `sdk-minimal` 不经过 base，不受影响。
+
+**安全边界（笔记原文要点）**：
+
+- 匿名 `http:`/`https:` 请求，且**仅允许校验过的公共目的地**（public-destination validation，即防 SSRF 打内网/环回）；
+- 抓取在 shell/文件沙箱与审批预设**之外**执行，**无需逐调用审批**；
+- 笔记明说"public-destination validation does not prevent public data egress"——只限目的地是公网，不限制公网数据外发；
+- 需要不同网络策略的产品/部署，必须在更晚的 bundle 或 profile patch 里**显式覆盖整个 tool-web 配置**。
+
+**对本机的含义**：全局 dsh 若从 alpha.3 升级，所有 base-backed 面（含 Dash Agent 本体与 ACP）的默认模型工具面会多出无审批的 `web_fetch`。omp-web 因禁用了原生 agent-loop/llm routes，其 OMP-backed agent 不直接受影响，但共享同一 host 工具注册面，升级时值得在 4999 测例里过一眼工具清单。
+
+---
+
+## 其余要点（回顾，详见前次会话总结）
+
+- **新包 `dsh-experimental-code-runtime-python`**：`ctx.codeRuntime` 能力缝的 CPython 子进程实现（fd 3 JSON-lines 协议、RLIMIT/墙钟/SIGKILL 约束），即 `run_code`/"Code Mode" 底层；vendored 树同时移除 `dsh-tool-subagent-report`。
+- **内部破坏性重构**：session 事件 seq 与 log offset 分离（笔记 `2026-08-31-session-sequence-and-log-offset-brands`）。
+- **alpha.5 存储热修**：per-record 单元跨版本读兼容 + backup-and-skip 抢救；升级后的 session-projection 缓存保持可读（笔记 `2026-09-02-projcache-cross-version-read-compat`）——升级 prod 前必读。
+- **视觉刷新**：超椭圆圆角 + 发丝线阴影描边（两份 09-01 笔记）。
+
+## 参考索引
+
+| 主题 | 证据 |
+|---|---|
+| CSS 布局档位笔记 | `.agents/notes/implemented/simplification/2026-09-01-css-produced-file-layout.md`（中英双语） |
+| 尾部对齐 CSS 化 | commit `203e2440ac`（删 `use-throttled-visual-update.ts`） |
+| 悬停显隐 CSS 化 | commit `f808112ec8`（`:has(~ …)` 替代 store 订阅） |
+| 溢出测量 CSS 化 | commit `e5bbee893b` + `ProducedFiles.module.css` 宽度档位 |
+| 保留 observer 的反例 | commit `aad1ce0c68` |
+| web_fetch 默认开放 | 笔记 `feature/2026-09-01-shared-base-web-fetch-default.md`；`bundle/base/cordis.patch.yml` `fetch: false→true` |
+| 被取代的旧决策 | 笔记 `feature/2026-07-31-web-default-search.md`（fetch opt-in 段落被标注 superseded） |

package/docs/50_test-reports/v0.1.8-improved-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,142 @@
+# DASHR v0.1.8 改进版复测报告（第一人称实测）
+
+> 复测方式：仍以 DASHR 运行时自身为被测对象（本会话，dsh Web GUI）。运行时已按上版报告调整并重启，本次对**上版全部问题逐条复测**，并重跑测试套件。
+> 复测日期：2026-08-24（同日晚，更新 commit `7ec46ac`）
+
+---
+
+## 0. 结论摘要
+
+| 结论 | 结果 |
+|---|---|
+| 上版 **P0（snapshot 失效）** | ✅ **已修复** |
+| 上版 **P1（docstring 回归）** | ✅ **已修复** |
+| 上版 P2/P3（命名漂移、masking 张力、fgm→pgmi） | ✅ **全部修复/重新设计** |
+| 测试套件 | ✅ **156/156 全绿**（上版 155/163） |
+| 遗留问题 | 🟡 README 中后段 + 根 README 仍残留旧架构文档；`compact` 引擎本部署仍未挂载 |
+
+**一句话结论**：改进版把上版报告里的**功能性问题全部清零**——内核环境自管（Python 3.11 + dill）让 snapshot 复活，delegation 工具从「桥接包装」改为「直接暴露」消除了 masking 与 dual-exposure 的张力；但**文档层还有两处 README 残留旧架构描述**需要清理。
+
+---
+
+## 1. 本次变更（commit `7ec46ac`）
+
+```
+dashr: runtime-owned kernel environment + native delegation exposure
+```
+
+1. **内核环境自管**（新增 `src/kernel-env.ts`，210 行）：运行时自己 provision 一个托管 CPython 3.11 venv（`ipykernel` + `dill`），落在**包内 `.venv-kernel`**（不再 `/tmp` 悬空 symlink）。显式解释器被校验：缺 `dill` = 响亮告警（禁用快照），缺 `ipykernel` = 硬错误。
+2. **原生 delegation 直接暴露**：masking 从 8 名收敛到**仅 2 名**（`send_message` + `report`）；`subagent`/`subagent_fork`/`list_agents`/`interrupt_agent`/`workflow`/`ralph` 直接暴露为 `tool.*` 成员；**`rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 桥接全部删除**。
+3. **Rebrand**：`@fgm-builds/dashr` → `@pgmi-builds/dashr`；RLM 术语在 CONTEXT/ADR 去强调。
+
+---
+
+## 2. 上版问题逐条复测
+
+| 上版问题 | 严重度 | 本次实测证据 | 状态 |
+|---|---|---|---|
+| snapshot 失效（dill 缺 + Python 3.14） | 🔴 P0 | 实测内核 `Python 3.11.15` + `dill 0.4.1` + `ipykernel 7.3.0`；`.venv-kernel` 指向 uv 托管 3.11；快照测试全绿 | ✅ 修复 |
+| docstring 回归 | 🟠 P1 | 实测 `helper.__doc__ == 'First summary line.\n    Details follow.'`；`runtime.spec.ts` 绿 | ✅ 修复 |
+| `agent_message` vs `send_message` | 🟡 P2 | 实测 `tool.agent_message` → `unknown binding`；`tool.send_message` 为双向桥接；CONTEXT/ADR 已改 | ✅ 修复 |
+| flat-global vs `tool.*` | 🟡 P2 | CONTEXT.md「Binding」已改「`tool.*` member」 | ✅ 修复 |
+| `fgm` vs `pgmi` | 🟡 P2 | `package.json` name / `cordis.patch.yml` 均 `@pgmi-builds/dashr` | ✅ 修复 |
+| masking 7 vs 8 | 🟡 P2 | 重新设计为 2 名，ADR-0002 已同步 | ✅ 修复 |
+| masking 对直接面无效（结构性张力） | 🟡 P3 | 决策落地：delegation 直接暴露、`rlm` 删除，张力消除 | ✅ 修复 |
+| 桥接错误风格不一致 | 🟡 P3 | `rlm_workflow` 等已删，仅剩 `send_message`（结构化 error 值） | ✅ 消除 |
+
+---
+
+## 3. 新功能面实测（第一人称逐项）
+
+### ✅ 3.1 内核环境自管 —— 通过
+
+```
+kernel python: 3.11.15
+dill: 0.4.1
+ipykernel: 7.3.0
+```
+
+`.venv-kernel/bin/python` 现指向 `/home/u1/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11`（真实存在，非悬空）。
+
+### ✅ 3.2 原生 delegation 直接暴露 —— 通过
+
+`tool.subagent` / `tool.subagent_fork` / `tool.list_agents` / `tool.interrupt_agent` / `tool.workflow` / `tool.ralph` 现在**全部直接绑定**（call-through 返回的是真实工具的参数校验错误，而非 `unknown binding`）：
+
+```
+tool.subagent        -> REJECTED (invalid arguments: missing required property "description")
+tool.list_agents     -> bound+callable（返回子代理列表）
+tool.workflow        -> REJECTED (missing required property "script")
+tool.ralph           -> REJECTED (missing required property "objective")
+```
+
+### ✅ 3.3 桥接收敛（仅 send_message + refine + compact）—— 通过
+
+```
+tool.send_message    -> bound+callable   （双向桥接）
+tool.refine          -> bound+callable
+tool.compact         -> bound+callable
+tool.rlm             -> REJECTED (unknown binding "tool.rlm")
+tool.agent_list      -> REJECTED (unknown binding)
+tool.rlm_workflow    -> REJECTED (unknown binding)
+tool.rlm_ralph       -> REJECTED (unknown binding)
+tool.agent_message   -> REJECTED (unknown binding)
+```
+
+`rlm` 家族彻底移除，递归改走 `tool.subagent` / `tool.subagent_fork` 直连。
+
+### ✅ 3.4 递归 + A2A 全链路（新形态）—— 通过
+
+```
+tool.subagent spawn → {'kind':'continuable','subagentId':'3e8f3609-...'}   （8*9）
+child 完成上报
+tool.send_message(receiver='child') 下行追问 9*9 → 上报 "81"
+tool.send_message(receiver='parent') from root → 结构化 UNAUTHORIZED（guard 仍在）
+```
+
+### ✅ 3.5 无回归项 —— 通过
+
+`tool.*` 绑定、跨 cell 持久化、`ToolCallError(.toolName)`、`asyncio.gather`、顶层 `return` → SyntaxError 均与上版一致，无回归。
+
+### ✅ 3.6 测试套件 —— 全绿
+
+```
+Test Files  18 passed (18)
+     Tests  156 passed (156)
+```
+
+上版失败的 `snapshot-revive` / `snapshot-restore` / `lifecycle` / `session-keys` / `runtime`(docstring) 全部转绿；新增 `bindings.spec.ts`（7）、`parallel.spec.ts`（2）。
+
+---
+
+## 4. 遗留问题（新发现）
+
+### 🟡 4.1 包内 `dashr/README.md` 中后段仍描述旧架构
+
+header 段已更新（`dsh-rlm-mode`→`dashr`、`RLMRuntime`→`ReplRuntime`、`ipython`→`eval`、kernel 自管），但**中后段未同步**，仍残留：
+
+- 「**`ipython`** — the only tool the model may call directly」（应为 `eval`）
+- 「FLAT top-level callables — `await name({...})`」（应为 `tool.*` member）
+- 「bridge callables `rlm`, `send_message`, `agent_list`, `rlm_workflow`, `rlm_ralph`」（已删）
+- 「Delegation and messaging (rlm, send_message, agent_list, rlm_workflow, rlm_ralph)」整段 `rlm()` API 文档（已删）
+- install 段仍指 `dsh-rlm-mode` + `rlm-mode` preset（preset 已删）
+- `dashr-kernel` group `isolate: { rlmRuntime: true }`（旧 realm 架构，现为 host-plane `dashr-repl`）
+
+### 🟡 4.2 根 `README.md` 完全未 rebrand
+
+根 `README.md` 仍是「# Dashr: RLM Plugin for `dsh`」+ `dsh-rlm-mode` npm badge + 完整 RLM 定位 + `rlm()` API 示例——本次 commit **未触碰根 README**。
+
+### 🟡 4.3 `compact` 引擎本部署未挂载
+
+`tool.compact` 返回 `{'context_tokens': 137635, 'error': 'compact() is unavailable: no ctx.compaction engine is mounted in this composition'}`——桥接存在，但本 composition 无宿主压缩引擎（与上版一致，非本 commit 引入）。
+
+### ⚪ 4.4 观察项：会话续接时工具目录未随插件升级刷新
+
+本会话（`session-5037d6a6`）跨过了插件更新 + 运行时重启，但**本会话的 system prompt（Tool Catalog）仍是旧版**——仍在声明 `rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 可用，而实测运行时已 `unknown binding`。新开会话应得到正确目录，但「持久会话热升级插件后目录不刷新」值得留意。
+
+---
+
+## 5. 建议
+
+1. **清理 README 残留**：把 `dashr/README.md` 中后段（ipython/flat/rlm 家族/install/preset/isolate realm）+ 根 `README.md`（RLM 定位、`dsh-rlm-mode` badge、`rlm()` API）对齐 v0.1.8 实际形态（`eval`、`tool.*`、直接 delegation、`@pgmi-builds/dashr`）。
+2. **验证 compact 部署**：在目标部署形态下挂载宿主压缩引擎，复验 `compact` 与 Global Context Recency Window。
+3. **会话续接目录刷新**（可选）：考虑在插件升级/重启后让持久会话的 Tool Catalog 失效或重算，避免模型看到过期工具面。