better-dsh 0.0.0 → 0.2.3

package/docs/10_plans/kernel-refactoring/actinoable-surface-to-llm-in-agent-runtime_prime.md

@@ -0,0 +1,113 @@
+# Self Survey of `dsh` (DeepSeek Harness Agent) and Prime Agent - Actionable Surface to LLM in Agent runtime
+
+
+- Actionables: tools, toolset(s), skills, bash, executable code scripts (e.g. python ...)
+- Surface to LLM: the text/prompts exposed to LLM during agent runtime
+
+
+
+
+## Prime Agent(第一人称:Prime Agent 运行时自述)
+
+### 地基 — 我"调用工具"的 wire 形态(function calling)
+
+- 和 dsh 是同一个 function-calling JSON:`Function: { name, arguments }` —— 只有两个 element,`name` 平级、无 `tools.` 之类前缀命名空间。
+- **但我的平级工具枚举清单里只有一个名字:`ipython`。** 所以 wire 层固定是:`name` 只有 `"ipython"` 一种取值;`arguments` 只有一个必填键 `code`(字符串)。没有别的字段。
+
+- 我发出的真实 wire 原文(从我自己这个 session 的日志里抄的,一字未改):
+
+```json
+{"type": "toolCall", "id": "call_00_wf7zeFy6KRIXEaeC5zZS3896",
+ "name": "ipython",
+ "arguments": {"code": "%%bash\nls -la /home/u1/workspaces/dashr/dev/kernel-refactoring/"}}
+```
+
+- 客户端拿 `name: "ipython"` 定位唯一执行器,把 `arguments.code` 整段交给**常驻 IPython kernel** 执行,把我 print / 显示出来的 stdout 文本塞回 toolResult(原文照抄,stderr 与 kernel 状态另列):
+
+```json
+{"role": "toolResult", "toolCallId": "call_00_wf7zeFy6KRIXEaeC5zZS3896",
+ "toolName": "ipython",
+ "content": [{"type": "text", "text": "<cell 的 stdout>"}],
+ "details": {"durationMs": 472, "status": "ok", "stdout": "...", "stderr": "", "kernelRestarted": false},
+ "isError": false}
+```
+
+- **`await` 不在 wire 层,在 `code` 层**——`await` 是 Python 语法,发生在我写进 `arguments.code` 的那段程序里面。完整的语法链就四步:
+
+  1. 我要做一个动作 → 想好一段 **Python 程序**(一句话也是一个程序);
+  2. 把它写进 `arguments.code`(可以是 `await 技能函数(...)`、`%%bash` cell、`rlm(...)`、或任意 Python);
+  3. 发出唯一形态的 JSON:`Function: { name: "ipython", arguments: { code: "<那个程序>" } }`;
+  4. kernel 跑完,stdout 原样作为 toolResult 回到我的上下文,我再决定下一轮。
+
+- wire 示例(全部是同一个工具名,差别只在 `code` 里):
+
+```json
+// 例子1:调用联网技能 —— await 发生在 code 里
+Function: { name: "ipython", arguments: {"code": "await websearch('prime agent')"} }
+
+// 例子2:shell —— %%bash 必须是 code 的第一行
+Function: { name: "ipython", arguments: {"code": "%%bash\nls -la"} }
+
+// 例子3:子代理 admission —— 返回的是句柄,不是答案
+Function: { name: "ipython", arguments: {"code": "h = await rlm('sub-task', name='worker')"} }
+```
+
+### Actionables — 全部经 `ipython` 的 `code` 触达(没有第二层工具枚举)
+
+wire 层是平的、只有一个名字;dsh 那 29 个平级工具对应到我这边的全部"动作清单",都是我写进 `code` 里的 Python 对象:
+
+- **内核全局预导入的 9 个 python skill 模块**,调用形态统一是 `await <模块>.<函数>(...)`,返回值可绑定变量、可组合:
+  `agent_message`(send / list_agents)、`agent_observe`、`attach_image`、`compact`、`edit`、`goal`、`refine`(run)、`rlm_heartbeat`、`websearch`
+- **内核全局 `rlm`**:`await rlm('sub-task')`(非阻塞 admission,返回 rlm_child_id/name/session_dir/model,永不返回答案)、`rlm.list_subagents()`、`rlm.delete_subagent()`、`rlm.find_models()`、`rlm.get_harness_state()`、`rlm.harness.*`(memory / prompt_note / skill / subagent-spec 四类 CRUD,默认 session 本地,`global_=True` 才跨会话)
+- **`%%bash` cell**(必须是 `code` 的第一行)——shell、项目命令、CLI 全走这里;**没有独立的 bash 工具名**
+- **任意 Python**:stdlib 读/写/搜索文件、编排进程、`uv pip install` 装包、`%cd` / `os.environ` 管内核状态
+- **每个 skill 的 shell CLI**:`<skill> ...`(在 %%bash 里跑)
+- **markdown skills**(项目 `.agents/skills` 向上收集 + 用户级 + 捆绑 dist):不是 callable 绑定,用 ipython 读它们的 SKILL.md 学 API
+- **没有的东西**:read / write / glob / grep / todo_write / subagent / send_message……这些名字在我的 wire 枚举里**不存在**;对应能力 = code 里的 Python 或 skill 函数。这条不是靠运行时报错兜底,是 schema 面根本不暴露。
+
+### Surface to LLM — 我暴露给模型的文本
+
+- 系统提示正文(每次请求动态组装,顺序固定):code-first 人设开篇 → IPYTHON_CONTROL_PROMPT(长驻 notebook、%%bash 纪律、状态持久、await 调用、"do not invent non-native wrappers" 等反模式明令)→ RLM-native call contract → delegation doctrine(子代理 admission/消息/观察拓扑)→ continual harness 状态菜单(prompt/memory/skill/subagent 计数)→ 项目 AGENTS.md 链(Project Context)→ 会话变量:cwd、conversation log 路径、recursive agent depth、预装 Python 包清单
+- 工具 schema:只有 `ipython` 一个(`name` + `parameters:{code: string}`,description 写在 schema 里,正文不重复列工具目录)
+- skills catalog:`<available_skills>` XML 块拼在正文里(当前 session 26 条:name / type / python_import / description / location,措辞是 kernel 形态)
+- SKILL.md 本体:不注入;我用 ipython 读文件学 API
+- 对话历史 + 压缩(compact skill;单条 cell 输出截断上限默认 2000 行 / 50KB)
+- kernel 事件通知:`<ipython_kernel_reset>` 标记、interrupted cell 的 wait/kill 选择提示
+
+
+### 组合性 — 预绑定的名字是「Python 类型化的内置工具」,可当一等对象组合(本 session 已实测)
+
+- 术语(建议 Dash prompt 也采用):**Python 类型化的内置工具(typed Python built-in tools)**。它们不是 wire 层的 function call,而是 kernel 全局命名空间里的 typed Python 对象:
+  - `edit` = 可调用模块,成员 `run(path, old_str, new_str) -> str` 是 async 函数,抛 `FileNotFoundError` / `ValueError`
+  - `rlm` = 可调用模块(`rlm(...)` 即 spawn),成员 run / find_models / list_subagents / delete_subagent / harness / get_harness_state
+  - 实现层:`edit` 是进程内 async Python 函数(`Path.read_text/write_text` 直接 syscall),零 shell 零 subprocess
+- 实测组合模式(全部真实执行):
+
+| 组合模式 | 写法 | 结果 |
+|---|---|---|
+| 条件 | `if "x" in Path(p).read_text(): await edit(...)` | ✅ |
+| 异常 | `except ValueError` / `except FileNotFoundError` | ✅ 类型化异常 |
+| 重试 | for + try/except,失败换更宽 old_str | ✅ |
+| 批量 / 并行 | for 收集返回值 / `asyncio.gather(*[edit(...)])` | ✅ |
+| 对象化 | 存 dict、当参数传、自写 `safe_edit()` wrapper(加重试/降级策略) | ✅ |
+
+- 对照:平级 function call(DSH/Hermes)里组合只能发生在模型脑内、跨多轮往返、非确定;这里组合发生在确定性 Python 代码里,一个 cell 一轮往返。
+- **反面证据(诚实记录)**:本 session 的 system prompt 关于组合只有一句 "composed into program logic just like any other call",无例子、未说明是 typed 对象 → 本 session 模型未自发组合过一次(写文件全用裸 Python)。结论:**不写清楚,模型就不会。**(此为 prompt 缺口,补丁见下节)
+
+### 状态管理 — cell 化之后的「可回查状态机」(本 session 已实测)
+
+三种后台句柄,全部跨 cell 存活于 kernel 命名空间、可回查、可控制:
+
+| 句柄 | 创建 | 回查状态 | 控制 |
+|---|---|---|---|
+| asyncio Task | `t = asyncio.create_task(coro())` | `t.done()` / `t.result()` | `t.cancel()` |
+| 子进程(Hermes job/PID 等价物) | `p = subprocess.Popen(...)` | `p.poll()` / `p.pid` | `p.kill()` / `p.wait()` |
+| rlm 子代理 | `h = await rlm('sub-task')` | `rlm.list_subagents()` → `status` 字段 | `rlm.delete_subagent(h)` |
+
+- `await` 是"等"的语法;`asyncio.create_task` / Popen 是"不等"的句柄 —— 本 session 的 prompt 只教了 await,没教 async 句柄,这是第二个 prompt 缺口。
+- rlm 实测闭环:admission 立即返回 `RLMSpawnHandle(rlm_child_id, session_dir, model)` → `list_subagents()` 查 `status='completed'` → `delete_subagent` 回收 → 子代理回复经 agent_message **事件驱动送达**(实测:delete 之后消息仍到达,投递队列与句柄注册表解耦)。
+- 长命令(`%%bash` curl 等):包进 create_task/Popen,句柄落 kernel 命名空间,下一 cell 回查;kernel 死则句柄丢(进程还活,句柄没了)。
+
+### 建议 prompt 补丁(Prime upstream `IPYTHON_CONTROL_PROMPT` 与 Dash preset 共用)
+
+> Pre-imported skill modules and the global `rlm` are typed Python objects, not wire-level tools: each exposes documented async functions and raises typed exceptions (e.g. `edit` raises `FileNotFoundError`/`ValueError`). Treat them as first-class values: compose them with conditionals, `try/except` on their typed errors, loops, `asyncio.gather` for parallelism, custom wrapper functions for retry/degradation policies, or storage in data structures. For background work, keep pollable handles in the kernel namespace: `asyncio.create_task` → `done()/result()/cancel()`; `subprocess.Popen` → `pid/poll()/kill()`; `rlm()` admission → `rlm.list_subagents()/delete_subagent()`, with results arriving asynchronously via `agent_message`. Prefer composing multiple tool calls inside one cell over issuing them one call per cell.

package/docs/10_plans/recallable-compaction.md

@@ -0,0 +1,147 @@
+# Recallable Compaction（可回溯压缩）— 设计备忘
+
+> 状态：设计备忘（**未实现**）· 2026-08-20 · 用户方向 + API 面 spike 验证通过
+> 归属：`dashr/dev/`（gitignored 本地 scratch，不进公开仓库）
+> 上游文档：`dev/dashr-compaction-window-and-archive.md`（Feature 2 压缩损失补偿的总纲；本文档是其「回溯通道」的落地设计，并回收其 §3 开放问题中已解决项）
+
+## 0. 背景：Context as variable 的四方向与本 gap
+
+dashr 参考 Prime Agent 的三个核心特点（RLM 模式 / IPython REPL tool calling / Context as variable）中，前两个已完全实现；第三个目前只实现一半。完全体的四个方向：
+
+| 方向 | 状态 |
+|---|---|
+| 1. 事件流过滤 | ✅ 已实现（`recencyWindowTokens`，Feature 1，v0.1.1+） |
+| 2. 运行时变量存取 | ✅ 已实现（kernel 变量自由存取） |
+| 3. **上下文压缩与回溯** | ❌ **未实现 ← 本文档** |
+| 4. 广义上下文组件化 | ✅ 已实现（Continual Harness / `refine()`） |
+
+方向 3 的缺口：压缩后旧上下文被摘要 shadow，运行时模型无法直接读取原文（原文虽在 session 持久化文件中，但模型经资源工具查询繁琐且难定位）。Feature 2 原设计（强制归档 + 摘要尾部标记）解决「可恢复」，本文档补上「模型可寻址的回溯通道」与全部 API 面验证。
+
+## 1. Spike 结论（2026-08-20，Dash agent 实证 + 本机复验）
+
+> 委托方式：Dash HTTP API（session `session-a2a61011`，`cwd=/home/u1/workspaces/dashr`，rlm-mode preset）。证据脚本 `dev/spike-tag-repro.mjs` 已随文档保存，本机复跑 exit 0、输出吻合。
+
+| # | 事实 | 对设计的影响 |
+|---|---|---|
+| 1 | surface 是 **append-only + 深冻结** 的不可变投影；唯一写入口 `Session.append`；**不存在原地 patch 节点文本的 API** | 不能 mutate，只能 replace |
+| 2 | 「改写单个节点」的官方正解 = 再 append 一个 `replace`，`start === end === 目标 seq`，新节点 shadow 旧节点 —— 这正是上游 compaction 改写历史所用的同一机制 | 挂 tag 的通道 ✓ |
+| 3 | 新摘要节点 seq = **`result.summarySeq + 1`**（contractual adjacency；`commitCompactionBody` 源码确认：`compaction/summary` 事件后紧邻 `user/message` 替换节点，`= endSeq - 1`） | 摘要节点可精确定位 ✓ |
+| 4 | 被 shadow 的原文**事后仍可读**：`session.events[shadowedSeqs]` 完整保留（append-only log 不删除，shadow 只是从 surface 投影隐去） | **归档不必在压缩前捕获** —— 顺序约束消失 |
+| 5 | `user/message` 重写无限制（`assertToolResultRewrite` 只约束 `tool/result`） | 摘要文本可自由追加 tag 块 |
+| 6 | 替换节点保留原 `source`（含 `compactionId`）时，下游 checkpoint 识别（`isCompactCheckpointSource`）不破 | tag 挂载无损 ✓ |
+
+**关键修正**：原方案「归档先于压缩」（压缩前取到将被 shadow 的区间 → 归档 → 才允许压缩）不再需要。事实 #3+#4 意味着顺序可以是**先压缩、后归档、再挂 tag**——每一步只依赖已提交的事实，**tag 永不悬挂，无需任何补偿逻辑**。
+
+## 2. 设计：三步流程
+
+在 `compactIfNeeded`（与 `compactNow` 共用）的 `compactRegion` 返回之后：
+
+1. **读原文**（事后，从 append-only log）：`result.shadowedSeqs` → `session.deriveEventMessage(session.events[seq])` → 分类 → 序列化。
+2. **写归档存储**：介质二选一（§2.2，待用户拍板）。
+3. **挂 tag**：单节点 `replace`（`start === end === result.summarySeq + 1`），把 tag 文本块追加到摘要内容尾部。
+
+归档失败时降级为现状行为（照常压缩、仅无 tag），**不阻塞压缩**（沿用旧 doc 原则）。
+
+### 2.1 分类（沿用旧 doc §2.2，纯机械非语义）
+
+| bucket | 来源 | 说明 |
+|---|---|---|
+| `user_requests` | user 消息 | 用户指令原文 |
+| `assistant_responses` | assistant 消息 | 正文 verbatim；thinking 块剥除与否见开放项 |
+| `tool_results` | toolResult 消息 | 含 cell stdout |
+| `file_ops` | 机械提取 | read/modified 列表 |
+
+### 2.2 归档介质（开放决策，二选一）
+
+**方案 K — kernel 变量 + dill snapshot**（旧 doc 原方案）：
+- 复用 State Storage，实现量最小。
+- 代价：(a) trunk 与用户工作变量抢同一个 `capBytes` 预算，超限时**整个 snapshot 被 skip**（连用户变量一起丢）；(b) dill 跨 Python 版本脆弱；(c) 原文常驻 kernel 进程 RAM，随压缩次数线性涨。
+
+**方案 F — 独立 trunk 文件 + kernel 索引 + `recall()` 读文件**（推荐）：
+- trunk 本体 = 纯文本 JSON（带 role/seq），落 `kernel-snapshots/<sessionId>/trunks/<compactionId>.json`；kernel 里只放索引 dict（tag → 路径）；`recall(tag)` helper 直接读文件。
+- 好处：独立预算天然成立（不吃 snapshot cap）；写入即时持久（无 snapshot 的 1500ms debounce 窗口）；恢复 = 回填索引或重扫目录；绕开 dill 版本问题。
+- 代价：recall 读文件比读内存慢几毫秒，对 LLM 无感。
+- State Storage 职责因此更清晰：snapshot 管用户工作变量，trunk store 管压缩原文。
+
+### 2.3 tag 与 recall 协议
+
+- tag id：`ctx-<compactionId>`（或自增计数）。
+- tag 文本块（挂摘要尾部，格式示例）：
+
+```
+[原文回溯: ctx-12]
+本轮压缩的原始上下文已归档，需要细节时用 recall('ctx-12') 读取。
+```
+
+- `recall(tag)` helper（py-sdk 注入）：保留命名空间藏 trunk 数据（**不暴露裸全局**，防模型 cell 误覆盖/`del`）；只读访问；超长输出截断提示；缺失报明确错误。
+- Control Prompt 增加约定段：摘要条目带 `ctx-N` 标签时，需要全文就 `recall('ctx-N')`。
+- token 经济学：摘要照常在上下文（tag 一行文本 ≈ 0 成本）；模型只在需要时付出一次读取成本；归档不查询则不进上下文。
+
+### 2.4 预算与淘汰（开放数字）
+
+归档随压缩次数线性增长，必须设上限，否则省下的上下文 token 从 RAM/磁盘侧门还回去。候选：最近 N 档 / 总 token 预算 / LRU。淘汰是安全的——session log 里原文永远在（§2.5）。
+
+### 2.5 自愈（compactionId 稳定性）
+
+tag 携带 `compactionId + shadowedSeqs`；revive 时发现归档缺失，可从 session log 重放重建。本质：**session log 就是原文的持久层，归档只是模型可寻址的快路径缓存**。
+
+### 2.6 两条触发路径（共用挂点）
+
+- auto pressure：`RecencyAwareCompactionEngine.compactIfNeeded`
+- manual：`/compact` → `compactNow`
+- 挂点都在 `compactRegion` 返回后，路径无关。
+
+## 3. 代码骨架（compactRegion 返回后）
+
+```ts
+const result = await this.compactRegion(range.start, range.end, agent, signal)
+if (result === null) return null
+
+const session = agent.session
+const summaryNodeSeq = result.summarySeq + 1        // contractual adjacency
+
+// 1) 事后读原文（append-only log 完整保留）
+const original = result.shadowedSeqs
+  .map(seq => session.deriveEventMessage(session.events[seq]))
+  .filter((m): m is Message => m !== null)
+// 2) 归档（介质见 §2.2，失败则跳过第 3 步、不阻塞压缩）
+const tagId = `ctx-${result.compactionId}`
+// await archiveRecall(tagId, classify(original))   // 分类见 §2.1
+// 3) 单节点 replace 挂 tag
+const summaryMsg = session.deriveEventMessage(session.events[summaryNodeSeq])!
+session.append('user/message', createUserMessage({
+  content: [...summaryMsg.content, { type: 'text', text: `\n[原文回溯: ${tagId}] 全文可通过 recall('${tagId}') 读取。` }],
+  source: summaryMsg.source,                        // 保留 compactionId，checkpoint 识别不破
+}), {
+  surfaceOp: { op: 'replace', start: summaryNodeSeq, end: summaryNodeSeq },
+  sourceEventSeqs: [summaryNodeSeq],
+})
+```
+
+## 4. 与旧 doc §3 开放问题对照
+
+| # | 问题 | 状态 |
+|---|---|---|
+| 1 | 实现路径 A/B/C | 已裁定方案 B（子类化），Feature 1 已落地 v0.1.1+ |
+| 3 | 摘要后编辑口 | **已解决**（本文档 §1）：落盘前无插入口，落盘后单节点 replace 等效；且原文可事后读取，归档无需压缩前捕获 |
+| 8 | compactionId 稳定性 | **已解决**（§2.5 自愈：log 重放重建） |
+| 4 | 归档增长上限 | 仍开放（§2.4 候选方案） |
+| 5 | thinking 块剥不剥 | 仍开放（剥=省空间丢推理过程；留=完整但体积翻倍） |
+| 6 | 标记措辞与 token 预算 | 仍开放（§2.3 给出了候选格式） |
+| 7 | 与 pruner 的交互 | 仍开放，但假设已变：recency 路径在 compactRegion 前调 `pruneSession`；若 prune 也是 surface-replace 机制，则 log 原文应仍在（append-only），需实现时验证 |
+| 9 | recency 低于 system prompt 体积 | Feature 1 已带 no-op 守卫，软警告低优先 |
+
+## 5. 验证计划（实现时执行）
+
+- **单测**：分类落桶（每条消息恰落一桶）、tag 格式、单节点 replace（`dev/spike-tag-repro.mjs` 已是该场景的可运行骨架）。
+- **e2e**：灌满上下文 → 触发压缩（auto + manual 各一次）→ 断言：(1) 归档存储含被压缩区间原文；(2) 摘要尾部含 tag；(3) 模型执行 `recall(tag)` 能复述原文某细节。
+- **pruner 交互**（开放项 #7）：`pruneSession` 之后 log 里的原文事件是否完整。
+- **回归**：未配归档时行为与现状一致（默认全关）；测试只增不减（现有 140/140 不动）。
+
+## 6. 参考
+
+- `dev/dashr-compaction-window-and-archive.md`（Feature 2 总纲 + Feature 1 已实现记录）
+- `dev/spike-tag-repro.mjs`（API 面复现脚本，`node dev/spike-tag-repro.mjs` 可复跑，exit 0）
+- `dashr/src/compaction/recency-engine.ts`（挂点）、`dashr/src/py-sdk.ts`（recall helper 注入点）
+- 上游源码：`@deepseek-ai/dsh-session`（append/surface）、`@deepseek-ai/dsh-compaction-basic/lib/index.js` `commitCompactionBody`（替换节点 append 顺序）、`@deepseek-ai/dsh-compaction`（CompactionResult）
+- 委托 spike 报告：`/tmp/a2a/dashr-tag-spike.md`（Dash agent 产出，2026-08-20；关键结论已全部吸收进本文档 §1）

package/docs/10_plans/spike-tag-repro.mjs

@@ -0,0 +1,102 @@
+
+// Minimal reproduction: verify that a session surface node's text can be
+// "rewritten" (summary + recall tag) via the append-only replace surfaceOp,
+// and that the new compaction summary node's seq is determinable.
+// Read-only spike — no dashr repo files touched.
+
+import { Session } from '/home/u1/workspaces/dashr/dashr/node_modules/@deepseek-ai/dsh-session/lib/index.js'
+import { createUserMessage, createAssistantMessage } from '/home/u1/workspaces/dashr/dashr/node_modules/@deepseek-ai/dsh-llm/lib/index.js'
+
+const s = Session.create('spike-tag-demo')
+
+const userMsg = (text) => createUserMessage({
+  content: [{ type: 'text', text }],
+  source: { kind: 'user' },
+})
+
+const asstMsg = (text, step) => createAssistantMessage({
+  content: [{ type: 'text', text }],
+  source: { provider: 'p', model: 'm' },
+})
+
+const summarize = (m) => m.map(x => `${x.role}: ${x.content.map(b => b.text ?? '<non-text>').join('')}`).join('\n  ')
+
+console.log('=== stage 0: four surface appends ===')
+s.append('user/message', userMsg('user-0: hello'), { surfaceOp: 'append' })
+s.append('assistant/message', { turn: 1, step: 1, message: asstMsg('asst-1: world', 1) }, { surfaceOp: 'append' })
+s.append('user/message', userMsg('user-2: question'), { surfaceOp: 'append' })
+s.append('assistant/message', { turn: 1, step: 2, message: asstMsg('asst-3: answer', 2) }, { surfaceOp: 'append' })
+console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
+console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
+
+console.log('\n=== stage 1: simulate compactRegion writing a summary over nodes [1,2] ===')
+// Mirror commitCompactionBody exactly: log-only compaction/summary, then the
+// surface replacement user/message immediately after (summarySeq + 1).
+const summaryEvent = s.append('compaction/summary', {
+  compactionId: 'c-1',
+  summary: [{ type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' }],
+  shadowedRange: { start: 1, end: 2 },
+  shadowedSeqs: [1, 2],
+  shadowedTokenCount: 1234,
+  provider: 'p', model: 'm',
+})
+const replacement = s.append('user/message',
+  createUserMessage({
+    content: [
+      { type: 'text', text: 'This is an automatically generated checkpoint...\n\n<compacted-summary>' },
+      { type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' },
+      { type: 'text', text: '</compacted-summary>' },
+    ],
+    source: { kind: 'plugin', plugin: 'compact', compactionId: 'c-1' },
+  }),
+  {
+    surfaceOp: { op: 'replace', start: 1, end: 2 },
+    sourceEventSeqs: [summaryEvent.seq, 1, 2],
+  },
+)
+console.log('summaryEvent.seq (compaction/summary) =', summaryEvent.seq)
+console.log('replacement.seq (surface summary node) =', replacement.seq, ' === summarySeq+1 ?', replacement.seq === summaryEvent.seq + 1)
+console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
+console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
+
+console.log('\n=== stage 2: PATCH the summary node text (append recall tag) ===')
+// The summary surface node seq is determinable as summarySeq + 1 (== replacement.seq).
+const summaryNodeSeq = replacement.seq
+const tagged = s.append('user/message',
+  createUserMessage({
+    content: [
+      { type: 'text', text: 'This is an automatically generated checkpoint...\n\n<compacted-summary>' },
+      { type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' },
+      { type: 'text', text: '</compacted-summary>' },
+      { type: 'text', text: '\n[原文回溯: ctx-12] 全文可通过 recall(\'ctx-12\') 读取。' },
+    ],
+    source: { kind: 'plugin', plugin: 'compact', compactionId: 'c-1' },
+  }),
+  {
+    surfaceOp: { op: 'replace', start: summaryNodeSeq, end: summaryNodeSeq },
+    sourceEventSeqs: [summaryNodeSeq],
+  },
+)
+console.log('patched node seq =', tagged.seq)
+console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
+console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
+
+console.log('\n=== stage 3: shadowed originals remain recoverable from the append-only log ===')
+console.log('shadowedSeqs [1,2] still in session.events:')
+for (const seq of [1, 2]) {
+  const e = s.events[seq]
+  const m = s.deriveEventMessage(e)
+  console.log(`  seq ${seq}: type=${e.type} role=${m?.role} text="${m?.content.map(b => b.text ?? '').join('')}"`)
+}
+
+console.log('\n=== stage 4: confirm in-place mutation is rejected (deep-frozen) ===')
+const frozenMsg = s.deriveMessages().find(m => m.content.some(b => b.text?.includes('[原文回溯')))
+let mutateOk = false
+try {
+  frozenMsg.content.push({ type: 'text', text: 'sneaky' })
+  mutateOk = true
+} catch (err) {
+  console.log('mutation threw:', err.constructor.name, '-', err.message)
+}
+console.log('in-place push succeeded?', mutateOk)
+console.log('total events:', s.events.length, '| seq (next):', s.seq)

package/docs/10_plans/upstream-analysis.md

@@ -0,0 +1,128 @@
+# DASHR 上游源码分析（dsh × prime-agent）
+
+> 日期：2026-08-16 · 工具：Graphify (graphify-http-mcp :4749, AST 模式)
+> 用途：DASHR 自研运行时选型底图。两部分来源 + 结合方式蓝图见后续文档。
+
+## 0. 前置事实
+
+| 项 | deepseek-harness (dsh) | prime-agent (PI) |
+|---|---|---|
+| Clone | `dashr/deepseek-harness` @ `47f9438` (2026-08-13, npm-public PR #2519) | `dashr/prime-agent` @ `97b994c` (2026-08-14, daemon spawn ledger #1387) |
+| 语言主体 | TypeScript (ESM), Node ≥22.19 / ≥24 | TS host + Python runtime（模型面 Python，调度面 TS） |
+| 规模 | ~85MB 源码, 2319 ts + 19 py | ~30MB, 925 ts + 23 py（+runtime） |
+| pnpm workspaces | `packages/<group>/<pkg>` 两级, 50 组 ~230 包 | `packages/{agent,ai,coding-agent,tui}` 4 包 + `prime-agent-runtime/` (py) |
+| 许可 | MIT（预发布期承诺） | MIT |
+
+## 1. Graphify 图谱（AST，无 LLM 语义增强）
+
+| 指标 | dsh | prime-agent |
+|---|---|---|
+| nodes | 54,318 | 13,676 |
+| edges | 72,496 | 29,765 |
+| communities | 4,110 | 775 |
+| code 节点 | 33,026 | 10,784 |
+| graph.json | 44.9 MB | 15.4 MB |
+
+产物：各库 `graphify-out/{graph.json, GRAPH_REPORT.md, manifest.json}`。
+graph.html 因 >5000 节点未生成（GRAPHIFY_VIZ_NODE_LIMIT），交互视图需切子图或提限。
+增量更新：`update_graph(project_path)`；Graphify 缓存于 `graphify-out/cache/`。
+
+`.graphifyignore` 已写入两库（排除 node_modules/.git/dist/test fixtures/snapshots）。
+
+## 2. deepseek-harness 结构
+
+### 2.1 布局（依据 AGENTS.md + 实测目录）
+
+```
+vendor/      vendored Cordis 内核（manifest+sync procedure）
+packages/    @deepseek-ai/dsh-<name>，50 组 ~230 包
+  core/        agent, agent-loop, session, system-prompt, tools, scope
+  llm/         llm, llm-deepseek, llm-pi-ai, llm-retry, token-meter
+  subagent/    subagent + acp/claude-code/codex/dsh-sdk/fork-in-process/... 11 包
+  其他能力组:  fs, shell, subprocess, terminal, lsp, skill, web, mcp, acp,
+               compaction, context, workflow, todo, plan, preset, guard,
+               self-modification, hooks, session, identity, settings,
+               credentials, interaction, boot, sdk, typert, api, sandbox, ...
+apps/       cli + web
+python/     Python SDK + bundled runtime
+native/     node-addon-landlock-run（Landlock 沙箱 addon）
+.agents/    notes/（设计笔记，一手取证源）
+docs/       architecture, cordis-api, postmortem, subsystems
+```
+
+### 2.2 图谱枢纽（god_nodes, by degree）
+
+- `Context` (790) — Cordis 上下文，全库交汇点
+- `InvariantInstaller` (216), `Service` (138) — 插件注册骨架
+- `createSnapshotStore()` (97), `SnapshotStore` (79), `bindSnapshotSelector()` (88) — 会话快照存储链
+- `launchWebScaffold()` / `WebScaffold` / `watchConsole()` — web 测试脚手架
+- tsconfig `paths` (139) + package `scripts` (124) — workspace 胶水节点多，体现 monorepo 复杂度
+
+### 2.3 关键机制（docs/cordis-api 图谱查询 + AGENTS.md）
+
+- 插件注册原语：`ctx.plugin()` / `ctx.inject()` / `Registry`（docs/cordis-api/registry.md）
+- Registrations are effects：所有贡献走 `ctx.effect()` / `ctx.on()`，`register()` 返回 disposer（时空可组合性的实现基础；即 Cordis 论文「可逆效应」机制，论文仓库 `github.com/cordiverse/paper`，解读见 deepseek-dsh.md §1.4）
+- 能力三层拆分：Service Definition（接口）/ provider（实现）/ Consumer（消费者）→ 换实现不动消费者
+- per-session preset：`preset/` 包，agent.cordis.yml 组装，会话锁 `agent-preset-locked`
+
+## 3. prime-agent 结构
+
+### 3.1 布局
+
+```
+packages/
+  agent/         5 文件：agent-loop.ts, agent.ts, proxy.ts, types.ts（薄）
+  ai/            provider 层：api-registry, bedrock, stream, oauth,
+                 models.generated, openrouter-reasoning, mcp
+  coding-agent/  主体：src/core/{kernel, tools, session-manager, ...}
+                 skills/（Python 技能：rlm, refine, compact, goal, edit,
+                 websearch, agent-message, rlm-heartbeat, ...）
+  tui/           终端 UI
+prime-agent-runtime/   Python 侧 RLM runtime
+  src/rlm/{__init__, harness, skill, mcp_base}.py
+  test/           subagent_registry, mcp_base, agent_message_skill, harness
+```
+
+### 3.2 图谱枢纽（god_nodes）
+
+- `AgentSession` (430) — 核心会话对象
+- `InteractiveMode` (388), `TUI` (139), `Component` (134) — 交互层重
+- `AgentDaemon` (184), `DaemonSupervisor` (134), `DaemonAgentConnection` (122) — daemon 体系（最新 commit 正是 supervisor-owned rlm spawn ledger）
+- `SettingsManager` (172), `SessionManager` (108)
+
+### 3.3 关键链路（query_graph 取证）
+
+**子 agent spawn（rlm()）**：
+`rlm/__init__.py` → `run()` → `host_request()`（comm 通道发 TS host）→ `_spawn_handle_from_payload()` → `RLMSpawnHandle`；Python 侧 `HarnessState/HarnessScope/HarnessEntry/RefinementEvent`（harness.py, community 70/90）构成 Continual Harness 状态。TS 侧 `fork-server.ts SpawnParams`（community 157）承接。
+
+**IPython kernel（Context as Variable）**：
+- `core/tools/ipython.ts`：`IpythonKernelProvisioner` → `.startKernel()` / `.ensure()`
+- `core/kernel/index.ts` `KernelManager`：`.doStart()`, `.enqueueExecute()`, `.runIopubPump()`, `.handleExecutionMessage()`, `.shutdown()`
+- 状态持久化：`state-snapshot.ts` `.snapshotState()` / `.restoreState()` / `RestoreResult`（community 217）→ 变量级 checkpoint
+- fork：`fork-server.ts` `forkKernel()`（community 157，与 SpawnParams 同社区 → fork 复用 kernel 状态）
+
+## 4. 结合面初步观察（待蓝图输入）
+
+| 维度 | 取 dsh | 取 prime-agent |
+|---|---|---|
+| 内核/装配 | Cordis 插件体系, preset, 能力三层 | — |
+| 模型面 | — | 持久 IPython kernel + state-snapshot |
+| 子 agent | subagent 11 包矩阵 | `rlm()` 函数式 + fork-server |
+| 记忆 | — | Continual Harness (ρ,G,K,M) |
+| 沙箱 | bwrap+Landlock (native addon) | — |
+| LLM 接入 | llm-deepseek/pi-ai/retry/token-meter | ai/ 包多 provider |
+
+风险点：两库语言运行时不同（dsh 纯 TS vs PA 模型面 Python）；结合方式决定桥接层（PA 式 comm channel 或 dsh 式 in-process SDK）。
+
+## 5. 图谱查询备忘
+
+MCP endpoint `http://127.0.0.1:4749/mcp`（Streamable HTTP, 需 `Accept: application/json, text/event-stream`）。
+`graph_path` 参数 = `graphify-out/` 目录（含尾 graph.json 解析）。常用：
+`graph_stats / god_nodes / query_graph / get_neighbors / shortest_path / graph_affected(影响面) / graph_tree / surprising_connections`。
+
+增量：代码改动后 `update_graph`；LLM 语义增强需 API key（可选 gemini）。
+
+## 6. 相关档案
+
+- 调研/实测：`agent-harness/21_CLI-Agent/03_deepseek-dsh/deepseek-dsh.md`
+- `agent-harness/21_CLI-Agent/04_prime-agent/prime-agent-{research,deployment-experiment,rlm-analysis,paradigm-discussion,continual-harness}.md`

package/docs/50_test-reports/REPL-/345/267/245/345/205/267/350/260/203/347/224/250-/346/210/252/346/226/255/350/257/212/346/226/255.md

@@ -0,0 +1,110 @@
+# REPL 工具调用截断诊断（v0.2.1b 实测中发现，2026-09-01）
+
+## 结论先行
+
+**任何从 REPL（`eval` cell）内部发起的工具调用（`tool.<name>(...)`）都会让 dsh web daemon 进程崩溃并自动重启；会话日志在 `tool/code-dispatch-start` 处撕裂，恢复时 repair 机制合成「interrupted-tool-result」，模型看到的即「工具调用被截断、结果未知」。** 4 次探针 4 次复现，与 journald 守护进程崩溃记录逐条对应。
+
+这不是 REPL 同步/异步的问题，也不是 subagent 特有问题——是 dashr 子分派桥接层的结构性缺陷 + 部署运行态注册表视图缺 symbol 的直接原因叠加。
+
+## 一、复现矩阵（第一人称）
+
+| # | cell 内容 | 结果 |
+|---|---|---|
+| 1 | `await tool.subagent({… run_in_background: false })` | 截断（daemon 崩溃 17:39:17） |
+| 2 | `await tool.subagent({… run_in_background: true })` | 截断（daemon 崩溃 17:41:15） |
+| 3 | `await tool.bash({… run_in_background: true })` | 截断（daemon 崩溃 17:57:05） |
+| 4 | `await tool.read({path: "dashr/package.json"})` | 截断（daemon 崩溃 18:02:27） |
+
+对照：纯 Python cell（`dir(tool)`、顶层 `return` 判错、`await asyncio.sleep(0)`）全部正常。**凡含 `tool.*` RPC 的 cell 必崩，与工具、与 background 与否无关。**
+
+## 二、截断面定位（三层证据）
+
+### 1. 会话日志（`~/.dsh/sessions/…/session.jsonl.zstd`）
+4 次截断的共同指纹：`tool/call (eval)` → `tool/code-dispatch-start`（**已持久化**）→ 日志撕裂（无 `tool/code-dispatch`、无 `step/end`/`turn/end`）→ 重载时 `packages/core/session/src/repair.ts` 的 `interruptedTurnClosers` 合成 `interrupted-tool-result-<callId>-<seq>`（`TOOL_OUTCOME_UNKNOWN`）。会话内 **0 条 error 事件**——错误根本没走到会话层。
+
+### 2. 守护进程日志（`journalctl --user -u dsh.service`）——铁证
+```
+Sep 01 17:39:17 pnpm[414449]: dsh: fatal load failure: TypeError: Cannot read properties of undefined (reading 'prepare')
+    at Object.start (…/better-dsh/lib/index.js:11281:41)
+    at <anonymous> (…/lib/index.js:11191:21)
+    at drive (…/lib/index.js:11207:7)
+    at outcome (…/lib/index.js:11310:6)
+    at new Promise (<anonymous>)
+    at toolFunctions.<computed> (…/lib/index.js:11320:72)
+    at Proxy.dispatchHostRequest (…/lib/index.js:2180:21)
+Sep 01 17:39:19 systemd: dsh.service: Main process exited, code=exited, status=1/FAILURE
+Sep 01 17:39:23 systemd: dsh.service: Scheduled restart job, restart counter is at 1.
+```
+17:39:17 / 17:41:15 / 17:57:05 / 18:02:27 四次崩溃，栈完全一致。`scheduler.prepare` 中 `scheduler` 为 `undefined`——即 `registry[TOOL_RUNTIME_SCHEDULER]` 在部署运行态取不到值。
+
+### 3. 源码链（`dashr/src/index.ts`）
+- kernel 侧：`tool.<name>(...)` → `binding.call` RPC（`src/bootstrap.ts` `_dashr_callable`）。
+- host 侧：`dispatchHostRequest`（`src/runtime.ts:545`）→ `await fn(args)`（`src/index.ts` `binding()`）。
+- `binding()` 内部（`src/index.ts:666`）：`const scheduler = registry[TOOL_RUNTIME_SCHEDULER]` → 单驱动道 `drive()`（`src/index.ts:591-621`）→ `start()` 内 `await scheduler.prepare(input)`（`src/index.ts:712`）。
+- **结构性缺陷**：`drive()` 的 async IIFE 是 `try { … } finally { … }`，**没有 catch**；调用处是 `void drive()`。任何 `start()`/`commit()` 抛错（如 `scheduler.prepare` TypeError）都会变成 **unhandled rejection**——binding promise 既不 resolve 也不 reject，cell 永久挂起，错误外泄给进程。
+**完整链条**：cell 工具调用 → dispatch 启动（`code-dispatch-start` 已入日志）→ `registry[TOOL_RUNTIME_SCHEDULER]` 为 undefined → `scheduler.prepare` TypeError → driver 无 catch → unhandled rejection → `installFailLoud` 判定 fatal → daemon exit(1) → systemd 重启 → 会话重载 repair 合成「interrupted-tool-result」→ 模型收到截断消息。**截断面：binding 桥 → registry symbol 查询 → driver 的未处理拒绝。**
+
+## 三、命名澄清：REPL dispatch log 与 code-dispatch 是两个不同层（重要）
+
+容易混淆，先分清：
+
+| 名字 | 层级 | 是谁 | 本次 change 是否改名 |
+|---|---|---|---|
+| `tool/code-dispatch-start` / `tool/code-dispatch` | **会话持久日志事件**（durable log，`agent.session.append`） | dashr `src/index.ts:689,712`；harness `known-event-types.ts:63-64` 注册 | **否**——v0.1.x 就有，历史遗留名 |
+| `dashr/repl-dispatch-log` | **waterfall 扩展点**（内容整形监听事件） | dashr 自注册（`src/index.ts:458`） | **是**——v0.2.1 从上游 `tools/code-dispatch-log`/`tools/ptc-dispatch-log` 改名为「自己的 REPL dispatch log」 |
+| `tools/ptc-dispatch-log` | waterfall（上游 PTC 用） | harness `src/ptc.ts:282` + spill policy 监听（`spill-policy/src/index.ts:217`） | dashr 已不再 emit（仅注释提及） |
+
+**结论**：
+- 「自己的 REPL dispatch log」`dashr/repl-dispatch-log` **在代码里存在且自注册**——目标形态已就位。它之所以「没被触发」，是因为崩溃发生在它之前的 `scheduler.prepare`（它在 settle 之后才跑）——**是崩溃的结果，不是原因**。
+- 会话日志里我用作定位证据的 `tool/code-dispatch-start` 是**持久日志事件名**，与 waterfall 改名无关，只是「撕裂点之前最后一条已写入事件」的定位标记。
+- 改名引入了一个**真实但非崩溃的副作用**：harness 的 spill policy 仍监听上游 `tools/ptc-dispatch-log`，dashr 不再 emit → 溢出限幅（oversized 结果的 preview+locator 替换）对 eval 子调用日志**静默失效**。**已补（2026-09-01 晚，见六）**：dashr `shapeDispatchLog` 跑完 `dashr/repl-dispatch-log` 后，再把同一 dispatch（载荷结构与上游 `PtcDispatchLog` 完全一致）喂进 `tools/ptc-dispatch-log` 载体，spill 臂恢复生效。改动在 `dashr/src/index.ts`，lib 已重建（`f0febba7…`），**部署位同步 + daemon 重启待用户执行**。
+
+## 四、为什么 `registry[TOOL_RUNTIME_SCHEDULER]` 是 undefined（直接原因）
+
+
+- 已排除：dsh-tools 双副本 symbol 不一致（实测插件与 daemon 均解析到同一 realpath `/home/u1/workspaces/dsh-alpha/packages/core/tools`，symbol 严格相等）；dashr 分派代码改动（266d232/06e516a/HEAD 逐字节一致）；dsh-tools alpha.1 vs alpha.3 差异（仅 import 整理/ToolCallId brand 等外观差异）。
+- 关键观察：`classify()` 调用的 `registry.executionMode(input)` **正常**（`code-dispatch-start` 已写入日志，证明 `start()` 之前的分派逻辑跑通），而 `registry[TOOL_RUNTIME_SCHEDULER]` **取不到**。`executionMode` 是 ToolRuntime 类方法、`TOOL_RUNTIME_SCHEDULER` 是类实例 symbol 字段——即部署运行态 `runtimeCtx.tools` 返回的**不是原生 ToolRuntime 实例**，而是一个有方法、缺实例 symbol 字段的服务视图（cordis 作用域服务解析 / plugin tree 挂载路径差异）。
+- 测试为什么全绿：dashr 测试组合（`test/helpers.ts`）把 `ctx.tools` 解析到**根作用域的原生 ToolRuntime 实例**，symbol 在位；生产组合经 harness plugin tree / scope 层解析，拿到的是视图。
+- **何时坏的（重要修正）**：v0.1.8 实测报告（2026-08-24）实证 DASHR 自己的 `eval` 桥当时**正常工作**——同 cell 并发 `tool.read` + `tool.bash` 完成。2026-08-28 会话用的是 harness 自带 PTC `run_cell`（`tools.bash`，复数命名空间 = PTC SDK 形态；该 PTC 核心经 `@deepseek-ai/dsh-code-runtime-python` 执行 **Python**，非 TS），不能代表 dashr 桥状态。**崩溃由 2026-09-01 的 harness alpha（0.1.2-alpha.1）升级引入**——升级后 plugin tree 里 `runtimeCtx.tools` 变成缺实例 symbol 字段的服务视图；dashr v0.2.1 的 dispatch-log 改名不是崩溃原因。
+
+## 五、REPL 同步/异步问题的回答（顺带闭环）
+
+- 模型层：`eval` 是同步工具调用，模型等 cell 结果——这是设计使然，与缺陷无关。
+- cell 内：`tool.<name>(...)` 是 kernel→host 的 `binding.call` RPC，被 cell `await`；host 经与原生调用同一 registry 分派器执行。`run_in_background: true` 的工具实现**快速返回 id**（subagent `{kind:'continuable', subagentId}`、bash 返回 job id），background 语义本应保留、子任务与 cell 结束无关。
+- 但**当前运行时该路径整体坏掉**：任何子分派在 `scheduler.prepare` 即 TypeError，与 background 无关——所以「在 REPL 里 background 是否异步」目前是伪问题，路径不通；修好后 background 语义会按上述设计成立。
+
+## 六、修复方向（分层）
+
+1. **dashr 立即修（阻断 daemon 崩溃）**：`drive()` 加 catch / `start()`、`commit()` 失败必须 settle binding promise 为错误结果——cell 内工具调用失败应变成可见的 `ToolCallError`，**绝不允许以 unhandled rejection 外泄杀 daemon**。这是把「任何分派错误」放大成「整个运行时崩溃」的放大器，无论直接原因是什么都必须先修。
+2. **dashr 防御**：`registry[TOOL_RUNTIME_SCHEDULER]` 为 undefined 时抛带上下文的 loud 错误（cell 可见），而不是裸 `undefined.prepare` TypeError。
+3. **根因定位（harness 接线）**：在活体 daemon 上探针确认 plugin tree 中 `runtimeCtx.tools` 的实际对象（cordis 作用域服务视图 / 第二个 tools 实例），修正挂载使插件拿到原生 ToolRuntime（symbol 在位）。这一步需要 daemon 侧可写环境（本会话 bwrap 沙箱只读宿主，无法直接探查活体）。
+4. **测试补强（部分完成）**：已加「`tools/ptc-dispatch-log` 载体回喂」回归用例（`test/bridge.spec.ts`，全量 396 绿）。仍缺「生产形态」挂载测试——按 harness 的 plugin-tree/scope 方式挂载插件，断言 `ctx.tools[TOOL_RUNTIME_SCHEDULER]` 已定义 + 一个真实工具 RPC 从 cell 完成；防止此环境差异回归。
+5. **回归核验基线**：修复后重跑本文档第一节的 4 探针矩阵（4/4 应全部返回结果而非截断），并观察 `journalctl --user -u dsh.service` 无新崩溃。
+
+## 附：证据文件
+- 会话日志：`~/.dsh/sessions/--home-u1-workspaces-dashr--/session-ad9ac311-3400-4304-b501-e7303da850df/session.jsonl.zstd`
+- 守护进程日志：`journalctl --user -u dsh.service`（17:39:17 / 17:41:15 / 17:57:05 / 18:02:27 四条 fatal load failure）
+- 对照工作会话：`06ac8b2c-fb2e-458f-80d6-a0d28e50f193`（2026-08-28，9 对完整 code-dispatch，PTC run_cell 路径）
+
+---
+
+## 七、v0.2.1c 修复执行记录（2026-09-01，change v0-2-1c-repl-tool-crash-fix）
+
+### 六.1 + 六.2 已实现（dashr 侧）
+
+- `drive()` async IIFE 补 `catch`：lane 级 backstop——任何逃逸 start()/commit() 自身包裹的错误（或 classify() 抛错）settle 所有 queued-but-unsettled 分派为可见错误、清空队列、复位 exclusive、记 warn，**绝不外泄 unhandled rejection**。
+- `PendingDispatch` 新增 `fail(error)`：把 binding promise settle 为 `{ isError: true, message }`（经 `settleError` → `settle`，kernel 转 `ToolCallError`）。
+- `start()` / `commit()` 各自 try/catch：prepare 失败、dispatch body rejection、finalize/finish 失败都 settle 自己的 binding，不再向 lane 抛。
+- `binding()` 内 `registry[TOOL_RUNTIME_SCHEDULER]` 判空：undefined 时抛带上下文的 loud 错误（点名 symbol、指向 harness 挂载接线），替代裸 `undefined.prepare` TypeError。
+- 回归测试 3 个（`test/bridge.spec.ts`，全量 399 绿含 3 新）：view 缺 symbol → cell 收到含 `TOOL_RUNTIME_SCHEDULER` 的 loud 错误；`scheduler.prepare` 抛错 → binding settle 为可见错误；classify 抛错 → lane backstop settle 且进程存活。
+
+### 六.3 根因探针（本轮结论，待活体 daemon 复核）
+
+- **根因已锁定并更正（2026-09-02 活体探针 + 受控实验；推翻本节 2026-09-01 的 shadow 分支推断）**：真实根因是**部署拓扑 dual-copy**——崩溃期（2026-09-01 17:39–18:02）部署位插件嵌套 `node_modules/@deepseek-ai/*` 的 17 条 symlink（已退役 dev 接线）指向 dsh-alpha 源码树，插件 import 的 `TOOL_RUNTIME_SCHEDULER` 来自 alpha 副本的 dsh-tools 模块实例；daemon 的 `ToolRuntime` 实例由 host vendored 副本构建，其 symbol 字段以 host 副本 symbol 为键。两 symbol 为不同 `Symbol()` 实例：跨副本读实例字段 → `undefined`（`executionMode` 等字符串键方法不受影响、照常工作——症状逐字吻合）。
+- 证据链（2026-09-02）：① 活体 4 探针（`tool.bash` fg/bg、`tool.read`、`tool.subagent` bg:false/bg:true）经 `eval` cell 路径 4/4 真实结果——现行生产形态 symbol 在位；② 部署位 `require.resolve('@deepseek-ai/dsh-tools')` = `/home/u1/.local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools/lib/index.js`（host vendored，③→④ 层）；③ 受控实验：host 与 z_dsh-alpha 两副本 `TOOL_RUNTIME_SCHEDULER` 严格不等，host 键实例经 alpha symbol 读 → `undefined`、经 host symbol 读 → object；④ 时间线闭环：改名 `dsh-alpha → z_dsh-alpha`（2026-09-01 22:29）→ symlink 悬空 → 2026-09-02 清理删除 → daemon 重启 → 自愈。
+- shadow 分支理论为何被否：它与症状吻合但从未被活体证实，且无法解释「拓扑清理 + 重启后自愈」；dual-copy 机制同时解释故障与恢复。v0.2.1c 报告引「symbol 严格相等」的排除测量与崩溃期拓扑矛盾（疑测同一副本两次或取于改名后），以直接证据为准。
+- cordis traceable proxy 本身无嫌疑（symbol 转发分支在位；现行活体 plain read 即返回带 symbol 原生实例）。
+- dashr 侧交付边界：六.1+六.2（不崩溃 + loud 错误）继续有效；dual-copy 已由部署拓扑收敛消除（部署纪律：插件 `node_modules/@deepseek-ai/` 只留 `schemastery`+`cosmokit`）；v0.2.1d 给 guard 错误附 dsh-tools 解析路径实现事件自诊断。
+### 六.4 生产形态挂载测试（说明）
+
+- 三个回归用例以「缺 symbol 视图」「prepare 抛错」「classify 抛错」三种形态驱动 `createRunCellTool`，覆盖六.1+六.2 全部防御面；测试组合（根作用域原生实例）本就 symbol 在位，断言 `runtimeCtx.tools[TOOL_RUNTIME_SCHEDULER]` 定义的用例属于测试组合自身形态（根挂载原生实例），无法复现生产 realm 差异——该差异须在活体 daemon 上复核（六.5）。