better-dsh 0.2.3 → 0.2.4

package/cordis.patch.yml

@@ -15,7 +15,7 @@
       name: 'better-dsh'
       config:
         python: !!js process.env.DASHR_KERNEL_PYTHON ?? 'python3'
-        # NOTE (v0.2.3): trustedPageAuthorities' DERIVED default lives in the
+        # NOTE (v0.2.2a): trustedPageAuthorities' DERIVED default lives in the
         # plugin's Config schema (src/index.ts), NOT here — a profile/home
         # layer row with this id whole-row-overrides this config object, which
         # would wipe any default declared at the bundle layer (empirically

package/docs/50_test-reports/2026-09-06-write/345/267/245/345/205/267sandbox/345/215/207/347/272/247/351/200/217/344/274/240bug/345/244/215/345/217/221/345/217/212/346/214/202/350/265/267-/344/272/213/344/273/266/346/212/245/345/221/212.md

@@ -0,0 +1,176 @@
+# 事件报告：write 工具 sandbox 升级透传 bug（复发 + 新失败模式：调用挂起）
+
+> 日期：2026-09-06 · 环境：DSH v0.1.2-alpha 线（prod 3080 / Web GUI），session 模型 GLM，
+> file policy = workspace-write（workspace：`/home/u1/workspaces/dashr`），approval policy = ask。
+> 前置记录：2026-09-03 edit 工具同类 bug（session `8e966430`，"hashline edit escalation
+> passthrough bug"；dashr 插件侧修复 commit `e27fdec` + 报告 follow-up `419ca0e`——该修复仅覆盖
+> vendored hashline edit 路径，本次 write 工具复发说明 harness 层文件工具透传问题未除根）。
+
+## 场景
+
+向 workspace 之外写文件：`/home/u1/workspaces/superd/docs/00-blueprint.md`（Super D 蓝图，
+新建同级仓）。workspace-write 模式下首次尝试即被拒（`Read-only file system` / file access denied），
+按规则走单次 `sandbox_permissions` 升级重试。
+
+## 失败 1（已知 bug 复发）：write 的升级字段被丢弃
+
+首次 `write` 调用携带 `sandbox_permissions: "danger-full-access"` + justification，直接返回
+`[sandbox: file access denied under workspace-write mode]`——**未弹出任何审批卡片**，升级字段
+疑似在 harness 透传层被丢弃。与 2026-09-03 记录的 edit 工具症状同类：**文件类工具（write/edit）
+的 sandbox_permissions 透传失效，bash 工具的升级正常**。
+
+## 失败 2（新失败模式，更严重）：升级后的 write 调用挂起至手动停止
+
+agent 推理链（UI 可见）：此前一次 bash 升级到 workspace-write 被拒，报错提示"升级必须严格宽于
+当前模式"（当前已是 workspace-write）；据此判断应改用 danger-full-access 重试 `write`。
+该重试调用**表面上已发出，但此后 >5 分钟 agent 无任何活动**——非响应/挂起。用户在 UI 按
+"stop" 并发新 prompt 才恢复。
+
+即：升级版 write 不仅没有触发审批提示，还把整个 turn 挂死直到手动中断。两种可能根因待查：
+(a) 审批提示从未渲染（透传丢失后 promise 悬空）；(b) 调用 promise 永不 settle。
+
+## 有效的 workaround
+
+`bash` heredoc + `sandbox_permissions: "danger-full-access"` —— bash 的升级链路正常，审批弹出、
+批准后写入成功（superd 仓蓝图 + git commit `1c1969a` 均经此路径完成）。
+
+## 建议
+
+1. **修复前**：跨 workspace 文件写入一律走 bash heredoc + 升级，不用 write/edit 的升级。
+2. **根因排查**：write/edit 的 sandbox_permissions 透传丢失点（harness 文件工具包装层）；
+   以及挂起问题——需区分"审批提示未渲染"与"promise 未 settle"，二者修法不同。
+3. 回归范围：至少覆盖 write / edit / undo_last_edit 三个文件工具 × workspace-write 与
+   read-only 两种基线模式下的升级路径。
+
+## 同日复测（本地 Web GUI）：write 升级链路实测通过
+
+> 环境差异：prod 3080 / GLM → 本地 Web GUI（127.0.0.1:4999）/ deepseek-v4-flash；
+> file policy = workspace-write（workspace：`/home/u1/workspaces/temp`），approval policy = ask。
+> 测试目标（workspace 之外）：`/home/u1/workspaces/base/.scratch/dsh_ws_test.txt`
+
+### 实测记录
+
+1. **基线越界 write → 立即被拒，无审批卡**：
+   `[sandbox: file access denied under workspace-write mode]`
+   且拒绝消息自带第二行 affordance 提示（本轮行为的关键信号源）：
+   `[sandbox: escalation available — retry this exact operation once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`
+2. **单次升级重试**：`sandbox_permissions: "danger-full-access"` + justification → 返回
+   `Created`（审批通过），未再出现 denial；磁盘校验 `-rw------- 1 u1 u1 26`，内容
+   `test write from dsh agent`。
+3. 全程**无挂起、无字段丢弃、无静默失败**。
+
+**结论**：本地构建上 write 升级链路（字段透传 → 审批渲染 → promise settle）实测通过，与 prod 3080
+报告的「字段丢弃 + 挂起」复发症状不一致 → 缺陷疑为环境/构建相关（或已被修复）。建议按上文
+「建议 3」在 prod 3080 上回归 write / edit / undo_last_edit × workspace-write 与 read-only 基线。
+
+## 附 A：escalation 提示机制的优化（reminder 文案）
+
+同一机制在 system prompt 中至少出现三处，语义同一但角色不同：
+① 工具 schema 参数声明（affordance / API 表面，只声明字段存在）；
+② policy 规则段（procedure：何时、怎么用 + 大量禁令）；
+③ runtime-context 快照补充句（情境重启，位于每次 turn 顶部、工具调用前最后读到的位置）。
+
+本轮讨论聚焦③的措辞。现文：
+
+> Restricted operations may be retried once with sandbox_permissions for single-call escalation,
+> pending user approval.
+
+对字面论 / 风险厌恶型模型，存在两种可被误读的推理路径：
+
+(a) **配额式误读**：「once」被理解为一次性越权许可——只能带 escalation 请求一次；若首次升级被
+user deny，模型可能推断整个机制已耗尽、连后续命令也不再尝试升级。但 runtime **无状态**：不记录某
+命令是否已 escalate / 被 deny，系统不存在这类配额。
+(b) **ask-first 误读**：「pending user approval」被读成先征得批准再 retry，与 policy 的
+「don\'t detour through chat — the retry itself raises the approval prompt」相悖。
+
+「once」的字面语义与真实策略（单次 retry）并不冲突；歧义在于**未声明机制的 per-call / 无状态属性**，
+而该属性正是阻止 (a) 误读的关键事实。因此措辞应从「配额式」改为「机制式」，显式声明：per-call、
+无配额记录、审批由 retry 自动触发、单次 deny 只作用于该 call。
+
+**定稿（同日终版，替换③；上文「主推 / 短变体」作废）**：
+
+> A sandbox-deniable/denied call may be escalated with `sandbox_permissions="danger-full-access"` and a
+> one-line `justification`; the runtime will prompt for user approval. Escalation and its
+> approval/denial are per-call.
+
+双词并列**中立覆盖两条路径**：`deniable`——读到本段、且按 policy 可演绎判定为越界的调用（workspace +
+temporary 之外）直接升级，不做 doomed 往返；`denied`——未注意本段、已被拒的调用同样可升级。全文无
+retry / once / 配额措辞。安全边界是**双重硬 guard**：sandbox（policy 判定）+ user approval（审批卡）；
+预升级至多多弹一张可拒审批卡，无实害，「等审批」的心理摩擦天然抑制滥用。`danger-full-access` 经源码
+核对（`escalation.ts` `WIDER_MODES`：workspace-write → [danger-full-access]，且本句仅在该模式下渲染），
+参数名与 justification 单句配对均与 schema 一致。
+
+**具体 example（agent 视角最小推演）**：
+
+```
+#1  write(workspace 外路径)                          → denied（无审批，返回 marker + affordance 行）
+#2  write(同路径, sandbox_permissions="danger-full-access", justification="…")   → 弹审批卡
+    user 点 deny
+    → 语义：该 call 就此结束（stop and explain），≠ 「escalation 机制已耗尽」
+#3  稍后另一条命令被拒 → 仍可走同一升级路径（per-call，runtime 无配额记录）
+    ✗ 错误推理：#2 被 deny ⇒ 我不能再发起任何 escalation
+```
+
+**配套建议**：
+
+- ②policy 段的关键句（rejected = final for that command，但不禁止后续命令升级）与③措辞需锁死一致，
+  避免三处漂移；
+- 最强一层是**环境内信号**：denial 消息自带 affordance 行（本轮实测可见，现构建已带）。它零 token、
+  位置恰好、不可能被 attention 漏掉；应作为固定格式保留，并让提示中的 mode / 参数名与消息完全一致。
+
+## 附 B：保留并补充该 reminder 的必要性（语态 / 效价问题）
+
+系统 prompt 原本已含等价语义（②policy 段），但该段 **permission 密度低、被高强度禁令包围**
+（Do not detour… / Never escalate speculatively / A rejected escalation is final / no exception /
+a denial is final）。LLM 对禁令性词语的权重显著高于许可性陈述；风险厌恶型模型读后的净效价收敛为
+「escalation 是高风险的非常规动作，能避则避」——这为观测到的「静默失败」（denial 后直接放弃、从不
+尝试升级）提供了行为学解释：**这不是注意力丢失，而是语态 / 效价问题**。
+
+③是全文唯一「零否定、纯许可」的 escalation 表述，且位于 turn 顶部快照（决策前最后读到）→ 命题上
+与②重复，但功能上不冗余：它承载 **grant（放行）**，②承载 **procedure（程序 + 禁令）**。本轮复测中
+agent 在 denial 后正确、立即升级，除错误消息 affordance 外，③的纯许可语态是「敢试」的直接依据。
+
+结论：③应保留并按附 A 修正措辞；不要在静态 prompt 中继续增加第四处副本（边际收益到顶），后续投资
+应放在 denial 消息的 affordance 质量（直接给出该传的 mode）。
+
+## 附 C（新发现 · 待修）：rules 段「escalating up front is fine only when this session already denied the same access」自相矛盾
+
+> 追加于定稿同日；定位为文本漂移，修复另行排期，本轮未改动任何源码。
+
+**归属结论（同日追查）**：该子句位于**上游** DSH v0.1.2-alpha.5 源码——本 checkout 即
+github.com/deepseek-ai/deepseek-harness 的浅克隆（HEAD `db6bdc3576`，唯一 remote 为上游
+origin）；`packages/shell/tool-bash/src/index.ts:89` 与 `packages/shell/tool-pwsh/src/index.ts:140`
+均经 `git ls-files` 确认是上游跟踪文件。blame 止于 `47f943859b`（2026-08-13，上游 PR #2519
+merge）系浅克隆边界，真实引入 commit 更早、被截断。对照：刚定稿的快照句（dashr:escalation-
+guidance，`packages/better-dsh/better-dsh/src/index.ts`）属 Better Dash（repo：pgmi-builds/
+better-dsh），在上游 tree 内为 untracked（`??`）叠层。**修复含义**：改矛盾句 = 改上游跟踪
+文件，不能直接 commit 进本 checkout；两条路——上游 PR，或在 better-dsh 的 prompt 装配层覆盖
+订正 bash/pwsh 工具描述（与 dashr:escalation-guidance 同款注入方式）。
+
+**自相矛盾分析**：按字面语义，「escalating up front」（未尝试即升级）与「already denied the
+same access」（已尝试且被拒，同一 access）互斥——后者成立则前者必然不成立，条件永远无法满足。
+属两条规则被硬拼成一句的编辑事故。**推断的原意**：同一 access 已被本 session 拒绝过一次之后，
+再次需要时不必重发 doomed 调用、可直接升级（豁免重复往返）——但这层豁免语义句子本身没写出来。
+
+**事实核对（源码）**：
+
+- 该子句仅存在于两处模型可见的工具描述：`packages/shell/tool-bash/src/index.ts:89`、
+  `packages/shell/tool-pwsh/src/index.ts:140`；并随描述文本进入 35 个
+  `snapshots/**/tool-schemas*.expected.json` 快照（随源重生成，不需手改）。
+- 同策略的文档版本（tool-bash / tool-pwsh 的 README.md 与 README.zh.md）**均无此子句**
+  （0 命中）——同一策略在工具描述与文档中本就是两个版本（次级漂移）。
+- runtime 无 prior-denial 状态：`approveEscalation`（`packages/sandbox/sandbox/src/escalation.ts`）
+  只有三道闸——参数配对、严格更宽（`WIDER_MODES`）、审批通道。文档所称
+  「a request with no real prior denial … fails closed」在代码中并未实现为状态检查；
+  该子句纯属 prompt 层规范。
+
+**与本轮定稿的关系**：附 A 定稿（快照句）规定 deniable（policy 可演绎判定越界）调用可直接升级；
+本子句规定 upfront 升级仅在 same-access 已 denied 后才允许——同一动作两个触发定义，且其中之一
+自相矛盾。rules 段禁令权重高（见附 B 效价分析），模型大概率取 deny-first 读法，与快照句的
+deniable 路径持续张力。
+
+**修复方向（未实施，待排期）**：把豁免语义显式化，例如「once this session has already denied
+the same access, you may escalate again without re-firing the doomed call」；或与 deniable 原则
+统一为「policy 可演绎判定将被拒的调用可直接升级」。需同步：tool-bash / tool-pwsh 工具描述 ×2、
+README ×2（en/zh 一并对齐）、35 个快照重生成；并与 deniable/denied 的 deny-first vs 预判升级
+产品决策对齐后再动。

package/docs/50_test-reports/2026-09-08-hashline-edit-E_RANGE_UNVERIFIED/350/267/250/350/275/256/344/274/232/350/257/235/351/224/256/345/244/261/346/225/210-/350/257/212/346/226/255/346/212/245/345/221/212.md

@@ -0,0 +1,226 @@
+# 诊断报告：hashline edit `E_RANGE_UNVERIFIED` 跨轮会话键失效
+
+> 日期：2026-09-08 · 环境：DSH v0.1.2-alpha 线（Web GUI），file policy = workspace-write
+> （workspace：`/home/u1/workspaces/dashr`），better-dsh hashline edit 桥（vendored
+> `dashr/src/url-schema/vendored/hashline/`，dsh-better-edit 工具集）。
+> 性质：**行为诊断**（非实测计划）；一次真实触发 + 源码级与账本级取证。
+> 前置关联：`2026-09-06-write工具sandbox升级透传bug复发及挂起-事件报告.md`（同桥另一缺陷线）。
+
+---
+
+## 0. 一句话结论
+
+`E_RANGE_UNVERIFIED` 拒绝**不是校验代码的 bug**：write 后 auto-read 确实记了账，但 hashline
+的 served 账本按 **(session_id, path)** 键存储，而本部署**每个对话轮（continuation round）更换
+harness session id**——上一轮 write-hook 记的账，下一轮 edit 用自己的新键去查，必然查空。锚点
+与磁盘内容当时完全匹配（echo 可证），拒绝是**出处（provenance）账本问题，不是 staleness**。
+fail-closed 与批量原子性按设计工作，零数据损伤；代价是**跨轮编辑必须冗余 read 一次**。
+
+---
+
+## 1. 现象与错误解剖
+
+原始报错（13-tuple 批量 edit 的第 0 个 tuple）：
+
+```
+Error: [E_BATCH_ABORT] edits[0] (…/docs/superd/01-component-boundaries.md) failed:
+[E_RANGE_UNVERIFIED] cannot verify range against served state in …:
+remove_from "Utw" has no served position; remove_to "Utw" has no served position.
+Current range:
+Utw│# Super D 组件边界与 UI 组合层（v0.1）
+Retry with these anchors (no read needed). … The whole batch was rejected and
+NOTHING was written — no file changed and earlier items in the batch were NOT applied.
+```
+
+三层套叠，每层各自按契约工作：
+
+| 错误码 | 含义 | 触发条件 | 本次是否命中 |
+|---|---|---|---|
+| `E_RANGE_UNVERIFIED` | 出处校验失败：锚点 hash 在**本会话 served 账本**查无位置 | 账本没记过"你看过这行" | ✅（本案） |
+| `E_RANGE_STALE` | 内容漂移：served 位置上的 hash 与当前文件不一致 | 文件在 serve 之后被改过 | ❌ |
+| `E_RANGE_UNSERVED` | 区间中洞：起止锚在账，中间行从未 served | 部分服务（截断读后编辑跨页） | ❌ |
+| `E_BATCH_ABORT` | 批量原子中止：任一 tuple 失败 ⇒ 整批不写、先前 tuple 也不应用 | 防半套状态 | ✅（外层包装） |
+
+注意 echo 行 `Utw│# Super D 组件边界与 UI 组合层（v0.1）` 与磁盘逐字节一致——**锚点本身完全
+有效**，拒绝纯粹因为账本查无出处。
+
+---
+
+## 2. 事发回放（时间线）
+
+| 时刻 | 轮 | 动作 | 结果 |
+|---|---|---|---|
+| 轮 B | 蓝图 + 边界文档轮 | `write` 创建 `01-component-boundaries.md`（244 行） | write-hook 触发：结果尾部带 `--- Auto-read (hashline anchors) ---`，全文件锚点（`Utw…Pb8`）；`readAndServe → recordServed` 记账，键 = 轮 B 的 session id |
+| 轮 B→C | 轮边界 | harness 换 session id | （无感知） |
+| 轮 C | 透传/认证轮 | 拿 auto-read 锚点提交 13-tuple edit | `loadServed(轮C键, path)` = 空 → `E_RANGE_UNVERIFIED` → 整批拒绝，**零写入** |
+| 轮 C | 同轮 | `read` 全文（重新记账到轮 C 键）→ 原样重交 | 13/13 全部成功 |
+
+---
+
+## 3. 取证
+
+### 3.1 代码链（vendored hashline，全部一手核对）
+
+| 环节 | 文件 | 事实 |
+|---|---|---|
+| 拒绝点 | `hashline/anchor-pipeline.js:462` `verifyServedRange()` | 先 `servedPositionsOf(served, hash)` 查账：查无 → `E_RANGE_UNVERIFIED`；查到但内容不匹配 → `E_RANGE_STALE`；区间中洞 → `E_RANGE_UNSERVED` |
+| 批量原子性 | `edit-engine.js:270` | 任一 item 失败 → `[E_BATCH_ABORT]` + 当前区间 echo，整批不写 |
+| write 记账 | `write-hook.js`（`tools/post-execute` 监听） | write 成功后调 `readAndServe(io, path, cwd, { sessionKey: execSessionKey(exec) })`——**渲染锚点与记账是同一次调用**，preview 出现 = 记账执行过；catch 兜底只影响回显不影响 write 本体 |
+| 账本读写 | `read-and-serve.js` → `session-view.js` `recordServed/loadServed` | served 按 **(session_id, path)** 唯一键 upsert |
+| 键推导 | `session-view.js:47-58` | `sessionKeyFor(exec.agent?.session.id)`；缺 id 时落到进程级 `randomUUID()` 兜底键 |
+| 存储位置 | `paths.js` `configDir(cwd)` | `<workspace>/.dsh_better_edit/hash-store.sqlite`；workspace = `exec.agent.session.header.cwd`（`withWorkspace` 传播） |
+
+### 3.2 账本验尸（sqlite 实查）
+
+库：`/home/u1/workspaces/dashr/.dsh_better_edit/hash-store.sqlite`（表：snapshots / meta / undo /
+served；served 666 行、579 快照）。
+
+本对话相关行（节选，按时间）：
+
+```
+09-08 01:18  session-cb07ad10…  （轮 A：dash-research 深化轮）
+09-08 02:13  session-a1b3097d…  01-component-boundaries.md  ["Utw","AuN",…]   ← v0.1 布局
+09-08 02:15  session-a1b3097d…  00-blueprint.md              ["aD5",…]
+09-08 03:20  session-a61bbf92…  00-blueprint.md              ["C7S",…]（v0.3 期）
+09-08 03:41  session-328368a6…  01-component-boundaries.md  ["pKk",…]        ← v0.3 后布局
+09-08 03:53  session-328368a6…  00-blueprint.md              ["rJz",…]
+```
+
+关键观察：
+
+1. **每轮一个键**：served 表共 50+ 个 distinct session 键（含大量无 `session-` 前缀的裸 UUID——
+   `sessionKeyFor(undefined)` 的进程兜底键，来自 preview/test 形态）。本对话各轮 `memory_flush`
+   回显的 session id 与账本键一一对应（轮 A=`cb07ad10…`、轮 B=`7104efad…`），**轮 B 的键在
+   本库无任何行**——它的 read/edit/write-hook 记账落在了别处（store 跟随 exec cwd）或同样因
+   轮界不可见；轮 C 的编辑因此查空。
+2. **(session, path) upsert 语义**：同键同路径后写覆盖前写，跨键各留一行——这正是"跨轮每换
+   一键就重读一次"摩擦的账面痕迹（blueprint 在 4+ 个键下各有一行）。
+3. **snapshots 表全局按 path**（不分会话）——与 served 的会话隔离形成对照：文件指纹证据本来
+   就有全局权威，只有"谁看过"是会话私有的。
+
+### 3.3 判定时刻的锚点有效性
+
+拒绝时的 echo 显示 `Utw` 行与磁盘一致；且调用方必须先在**当前文件哈希表**里定位出锚点区间才能
+构造该 echo（`verifyServedRange` 收到 `fileHashes` 与定位后的 `startLine/endLine`）。即：**锚点
+与磁盘逐字节匹配的条件下仍然被拒**——拒绝条件是纯账本出处，非内容漂移。这是提出修复方案 1
+（content-match 快道）的直接依据。
+
+---
+
+## 4. 判定
+
+**没有坏的部分**（逐项核对通过）：
+
+- 校验逻辑三分支语义正确、先账本后内容、顺序合理；
+- write-hook 记账链无缺陷（渲染与记账同调用，preview 出现即记账执行）；
+- fail-closed：查不到出处一律拒绝，绝不带疑写入；
+- 批量原子性：`E_BATCH_ABORT` 整批回滚，先前的 tuple 不落盘（本案 13 tuple 零写入）；
+- 恢复路径干净：一次 `read` 重记帐后原样重交即全绿。
+
+**缺口**（设计假设与部署现实不符）：
+
+- 账本假设"一个逻辑对话 = 一个稳定 session id"；本部署每个 continuation round 换新 id（且
+  store 目录跟随 exec cwd），**跨轮 served 必然不可见** ⇒ 每个轮界对每个待编辑文件强制一次
+  冗余 read——纯摩擦、无风险、可完全消除。
+- 报错文案 `"Retry with these anchors (no read needed)"` 对多 tuple 批是误导：echo 只把
+  `edits[0]` 的区间记为 served，原样重交会在 `edits[1]` 上再失败、循环往复；正确指引是
+  "read 一次后整批重交"。
+
+---
+
+## 5. 修复建议（better-dsh，按性价比排序）
+
+1. **content-match 快道（推荐）**：`verifyServedRange` 已持有当前 `fileHashes` 与定位区间——
+   当锚点 hash 在当前文件的定位区间上**逐行全匹配**时直接接受。byte-exact 保障不损（全匹配
+   ⇔ 自锚点生成以来该区间未变），served 账本从"门禁"降级为 echo/undo 的辅助。整体消灭此类
+   摩擦，且不依赖 harness 侧任何改动。
+2. **served 键去 session 化**：per-workspace 一份；或当前键为空时采纳该 path 的最近 serves
+   （`snapshots` 已是全局按 path 的先例）。改动小，但弱化"多会话并行同一文件"的隔离语义，
+   需评估并发场景。
+3. **改键源**：若 harness exec 暴露 conversation/root id（resume/continuation 的稳定根），
+   以其代替 `session.id` 做键——语义最正，依赖上游字段存在。
+4. **廉价修（文案）**：多 tuple 批失败时指引改为"对本文件 read 一次后整批重交"；顺带在
+   `E_RANGE_UNVERIFIED` 文案中点明"write auto-read 的锚点跨轮不可复用"这一部署事实。
+
+建议 1 与 2/3 不互斥：1 消摩擦，2/3 修语义。落地走 openspec change 流程（含单测：write → 模拟
+换 sessionKey → edit 应成功/回退行为明确）。
+
+---
+
+## 6. 复现与回归要点
+
+- 触发条件：轮 N `write`（或 read）文件 → 轮 N+1 直接 edit 同文件 → 必现
+  `E_RANGE_UNVERIFIED`（首个 tuple 即拒）。
+- 快速复现（不依赖轮界）：同文件两次 edit 之间，用不同 `sessionKey` 调 `loadServed` 即等价
+  （单测可直接构造）。
+- 回归断言：修复后 write/read 的锚点在**任意后续轮**直接可用；`E_RANGE_STALE`（真漂移）与
+  `E_RANGE_UNSERVED`（区间中洞）行为不变；批量原子性不变。
+
+## 来源
+
+- 一手源码：`dashr/src/url-schema/vendored/hashline/{write-hook,read-and-serve,session-view,
+  paths}.js`、`hashline/anchor-pipeline.js`（verifyServedRange）、`edit-engine.js`（批量中止）
+- 一手账本：`/home/u1/workspaces/dashr/.dsh_better_edit/hash-store.sqlite`（served/snapshots/
+  undo 表实查，2026-09-08）
+- 触发实录：本 session 轮 B→轮 C（`docs/superd/01-component-boundaries.md`，13-tuple 批，
+  拒绝后 read 重交 13/13 成功）
+
+---
+
+
+## 7. 勘误与设计裁决（2026-09-08 第二轮复核，user 主持）
+
+> 本节修正上文 §0/§2/§4 的关键归因错误，并记录用户裁决的修复方向。原文保留作诊断过程记录。
+
+### 7.1 勘误："每轮换 session id" 不成立，真实机制是会话树 fork
+
+| 上文断言 | 复核结论 | 一手证据 |
+|---|---|---|
+| "本部署每个 continuation round 更换 harness session id" | **不成立**。账本键 = `exec.agent?.session.id` 原样（`session-view.js:47-58`，无加工），与 `~/.dsh/sessions/<workspace>/session-<uuid>/` 目录及 `session.jsonl.zstd` header.id **一一对应**；同 id 跨多小时/多轮复用（328368a6：03:41+03:53 两笔；2f3a8234：04:27→11:41 跨 7h，本报告即该会话所写） | dashr 桶 6 个 session 目录与账本键全对上 |
+| "轮 B→C harness 换 id（无感知）" | 真实机制 = **DSH 会话是树，延续/fork 产生新节点**：header 带 `parentSession` + `seedLength`；`packages/core/session/src/index.ts` 有显式 `fork(source, boundary?, childSessionId?)`（注释："Seeding with an existing event log replays/forks a session"）。fork 对 UI 与上下文透明，故 agent/user 均感知为"同一对话" | 实测谱系：`345e1e12 →fork→ cb07ad10 (seed 23,388)`；`a1b3097d(根, 01:24) →fork(03:08)→ 328368a6 (seed 65,305) →fork(03:11)→ a61bbf92 (seed 65,308)`；`2f3a8234` 独立根 |
+| 病根表述 | 修正为：**轮 B write（02:13:16/02:15:02，键 a1b3097d）与轮 C edit（03:41:38/03:53:15，键 328368a6）分属父子会话节点**，served 按 (session节点， path) 记账 → 子节点查空 → `E_RANGE_UNVERIFIED`。fail-closed、批量原子、恢复路径等结论不变 | 账本 sqlite 逐行时间核对 |
+| "memory_flush 回显 session id 与账本键一一对应（轮 B=7104efad…）" | **不成立，观察源即错**。corti-memory `memory_flush` 回显的是 `exec?.session?.id`（`corti-memory/dist/index.js:381-384`，fallback `lastSeenSessionId`/"dsh-session"），**不是写账本的 `exec.agent?.session.id`**；7104efad 属 `/home/u1/workspaces/base`（workspace.json：base 桶 updated `09-07T18:13:19Z` = 本地 09-08 02:13；base 桶 `session-7104efad…/session.jsonl.zstd` 206KB，02:13–02:18 活跃），而账本 02:13 行键 = a1b3097d | 两个 id 分属不同 workspace 的会话对象 |
+
+### 7.2 write 语义与守卫归属（确认）
+
+- better-dsh **未干预 write 执行**：上游 `packages/fs/tool-fs/src/write.ts` 自述 *"Model-facing full-file write … no policy means an unconditional atomic create-or-overwrite"*，确认信封 *"no file content is echoed back"*。better-dsh 仅经 `tools/post-execute` 追加锚点回放（模型面 content）。
+- **整文件写在逻辑上不要求"之前见过"**：新文件天然无此前提；已有文件的守卫归覆盖确认层（DSH approval policy + `dsh-fs-observation-policy` 的 createIfAbsent/replaceIfVersion），与 hashline 无关。上文 §5 建议 4 中"write auto-read 锚点跨轮不可复用"的文案指引随 §7.3 裁决一并重写。
+
+### 7.3 hook 时机与回放必要性（裁决）
+
+- `tools/post-execute` 即 **tool-result 相位**水漏（`pre-execute → execute → post-execute`；core/tools invariant："post-execute must follow pre-execute or execute"；spill-policy 同瀑布组合；签名 `(exec, result, next) → Promise<PostToolDecision>`，write-hook `await next()` 后追加内容，**异步安全**）。挂点选对了。
+- 脆弱点：`final-result` 路径 **bypass post-execute**（core/tools `index.ts:421`）——未来异步/后台写工具若走该路径，回放会静默丢失。
+- **回放与 edit 解耦（裁决）**：OMP write 模型面 = 成功确认 + 新 `[path#TAG]`，**不回显内容**（渲染器 12/6 行预览仅 UI 侧）。DSH write-hook 现回放全文件锚点预览（`fmtReadPreview` 默认上限 `DEFAULT_MAX_LINES=2000` 行、单行 200KB）——对整文件写是过度供给。裁决：write 结果**仅返回动作确认（+ 可选新 tag 头）**，内容核实由 agent 主动 read；write-hook 回放砍掉或降级为确认行。
+
+### 7.4 locator 去 session 化（裁决）
+
+- 键 = **canonical 绝对路径（现成键，零新增）**：全部状态表本就以 `resolveTarget()` 的绝对路径为主键——`snapshots(path PRIMARY KEY)`、`undo(path PRIMARY KEY)` 现状即无 session；唯一 session 化的 `served` 去 `session_id` 列、PK 改 `(path)`，drift `reported` 列随行走。绝对路径单机全局唯一，集中单库不撞键。**不引入 CWD basename 前缀**（第三轮复核裁决）：模型面 locator（行级 3-char 锚）永远伴随 edit 调用的显式 path 参数使用，不存在"裸 hash 找文件"的 surface，前缀列零收益——minimal effort 即删列。
+- 全量哈希（xxh64 `contentChecksum`）仍是内容身份，现库 checksum 命中原样保留；跨会话共享同 path 的 served 行是期望行为（内容权威下"谁看过"无判定义务）。随键清理：`wipeServedState(sessionKey)` 删除；`SERVED_TTL_MS` 7 天 TTL 按 `updated_at` 照常 prune（`hash-store.js:488`）。迁移 = `HASH_STORE_VERSION` 6→7 重建 served 表；旧 12 个点目录弃置（TTL 反正清空，不作数据导入）。
+- **§5 建议 3（改用 conversation/root id 作键源）作废**：host session id 引入 fork/子代理嵌套等不可控复杂度，被本节 path 键方案整体取代。建议 1（content-match 快道）与本节合流：内容即权威，served 出处账本对校验不再必需（undo/echo 归属另议）。
+
+### 7.5 存储布局："到处拉屎"（裁决：集中化）
+
+- 现状：`configDir(cwd)` 把 `hash-store.sqlite` 落在每个 workspace 下，实测 **12 个 workspace 各一份**（base 1.4MB、dashr 6.1MB+4MB WAL、superd/research/dsh-omp/browser-agent/temp/agent-harness/kb-dev/sidecarx/SoftEng/orchestra …）。
+- 裁决（第三轮精化）：迁移到 **`$DSH_HOME/storages/dsh-better-edit/hash-store.sqlite`**。`storages/` 是宿主状态数据区（workspace.json / message_feedback.json / session_projcache），语义对口；实测 `~/.dsh/plugins/dsh-better-edit/` 是安装脚手架位（README/code/cordis/minimal/standard），代码里原"无 cwd 兜底"指向 `plugins/` 属语义错位，一并修正。实现 = `configDir(cwd)` 删除 cwd 分支，统一走 `resolveDshHome()`（感知 `DSH_HOME` → 4999 测试线 `.dsh-test` 自动隔离）。
+
+### 7.6 修复批次合并
+
+§7.2–§7.5 与原 §5 建议 1/2/4 合并为**一个 openspec change**（暂名 `hashline-content-locator`）：内容寻址 locator + 集中存储 + write 回放解耦 + 多 tuple 失败文案修正。回归断言沿用 §6，另加：write→（fork 会话）→edit 应直接成功；`.dsh_better_edit/` 不再新建；上游 `~/.dsh` 下单库增长可观测。
+
+### 7.7 渊源备注
+
+better-dsh vendored 头注自述 *"a dsh port of pi-hashline-edit-lsz"*（pi 系 = OMP 同族，即用户所称 "BetaEdit" 分支）。两支同源已分岔：OMP = 整文件快照 + 4-hex tag + session 级内存 store；DSH 分支 = 3-char 行锚（62³ 文件内唯一分配）+ (session,path) served 账本 + per-workspace SQLite。本次裁决实质是把 DSH 分支的校验权威从"会话出处"迁回 OMP 所在的"内容快照"一边，存储形态再叠加集中化。
+
+---
+
+
+## 8. 落地回执（v0.2.3b，2026-09-08）
+
+
+§7 五项裁决已实现并实测：change `openspec/changes/2026-09-08-v0-2-3b-hashline-content-locator/`；
+单测 `test/hashline-store.spec.ts` 12/12；4999 第一人称实测见
+`v0.2.3b-hashline-content-locator实测报告.md`。要点：中心库落位
+`.dsh-test/storages/dsh-better-edit/`（served 表无 session_id 列）、write 无回放、
+内容快道在账本未见时直接放行；实测发现宿主 `dsh-fs-observation-policy` 的
+`E_NOT_OBSERVED`（read-before-edit）为跨会话 edit 的另一道设计内守卫，予以保留。
+发布闸：a 实测 ✅ / b 报告 ✅ / c user 确认 ⏳。