better-dsh 0.2.3 → 0.2.4

package/docs/50_test-reports/upstream-dsh-0.1.5-rc.2-local-test-report.md

@@ -0,0 +1,79 @@
+# upstream dsh 0.1.5-rc.2 本地对齐实测报告（Dev/Test 1 · 4988 实例）
+
+> 日期：2026-09-11（HKT）
+> 执行：对齐轮 S1–S7（runbook：`docs/60_exploration-and-research/05-dashr-dev/upstream-alignment.md`）
+> 目标 tag：`dsh-v0.1.5-rc.2`（npm dist-tag `next`，最高版本；`latest` 停在 rc.1）
+> 前置版本对账报告：`docs/upstream-dsh-0.1.5-rc.2-report.md`（846 commits / 3170 files / ~104k 行）
+
+---
+
+## 一、实测范围与结果表
+
+| # | 步骤 | 结果 |
+|---|---|---|
+| S1 | patch 载体 tag 间 diff + dashr 56 个 `@deepseek-ai/*` 引用名对新 tag 包集全数命中 | ✅ |
+| S2 | checkout `dsh-v0.1.5-rc.2` + 三 patch 手工重放（pnpm-workspace.yaml 冲突按新 allowBuilds 手解） | ✅ |
+| S3 | rsync 副本 + stale peerDep 复查（absent）+ **新增 devDeps 手术**（见瑕疵 F2） | ✅ |
+| S4 | `pnpm install`（36s，供应链策略 1543 entries 过）+ `pnpm run build`（234 client artifacts）+ 副本 tsdown/client 半 | ✅ |
+| S5 | 插件契约对齐：**4 处真实语义漂移移植**（见 §三） | ✅ |
+| S6 | `tsc --noEmit` **0 errors**；`vitest --run` **493/493**（37 files，128s） | ✅ |
+| S7 | 4998 实例 systemd-run 冒烟 **8/8 探针全绿**（见 §四） | ✅ |
+
+红线遵守：未 npm publish、未动 prod 3080、未动 Caddyfile。
+
+## 二、环境事实
+
+- monorepo：`upstream/deepseek-harness` @ `dsh-v0.1.5-rc.2`（detached），本地 patch 三件套在场（unrun devDep / storeDir+verifyDepsBeforeRun+zeromq / tsdown resolveRepositoryRoot）。
+- allowBuilds 冲突解：采纳上游新集（**fs-ext 移除**——flock 改走 node-addon-system 预编译；新增 `electron-winstaller: false`、`msgpackr-extract: false`），保留本地 `zeromq: true` 与两条 `dsh-subprocess-local`。
+- 副本 `packages/better-dsh/better-dsh/` = canonical 0.2.3-b + devDeps 手术（14 个 `workspace:*`）。
+- 实例：unit `dsh-4988-test`，`DSH_HOME=~/.dsh-test`，`DSH_TRUSTED_HOSTS=test.pc.randomhash.app pc.randomhash.app 192.168.31.130`，`UnsetEnvironment=DISPLAY WAYLAND_DISPLAY`，**端口 4988**（4997–4999 被 superd PoC 占用，见瑕疵 F4）。
+- 残留实验文件未动：`packages/boot/app-boot/bun-registry/`、`bun-internal-bridge.ts`（2026-09-06 bun compile 实验，构建容忍，untracked 不碍 checkout）。
+
+## 三、契约漂移与移植（本轮核心工作）
+
+对 0.1.5-rc.2 的 **4 处真实漂移**全部移植，canonical 已同步（src/test 与副本 diff = 空）：
+
+1. **会话事件改名**（Session V3「PTC durable vocabulary」）：`tool/code-dispatch(-start)` → `tool/ptc-dispatch(-start)`。`src/index.ts` 2 处 append + 3 处注释；测试 3 文件的字符串断言同步。
+2. **subagents 统一消息缝**：`followup`/`reportFrom` 两方法合并为 `sendMessage(sender, targetId, content, {signal})`（上行 = targetId 命中 sender 的 `parentSession` 自动走 send-to-parent；`source`/`delivery` 选项 knobs 已删，runtime 自盖章）。移植面：`src/subagents-surface.ts` 接口重述、`src/bridges/index.ts` 两调用点（parent 方向新增 root-agent 本地护栏，语义等价旧 UNAUTHORIZED）、`delegation.spec`/`bridges.spec`/`helpers.ts` 全部 fake 与断言。
+3. **持久化读路径**：`SessionPersistence.inspect` 消失（接口只剩 create/open/flush/stat/list）；读 = `open(id,'read')` → `handle.read(offset?,length?,opts)` + `close()`，元数据 = `stat(id).header.createdAt`。移植面：`src/url-schema/handlers/agent.ts` 的 surface 接口重述 + 3 调用点收敛为 `persistedEventsOf` helper。
+4. **SessionSeq 品牌化**：裸 `number` 不再可赋值，需 `SessionSeq(n)` 构造（`dsh-session` 导出）；`assistant/message` 事件 data 新增必填 `stream: AssistantStreamRecord[]`（V3 in-history stream 内嵌）——测试 fixture 两处补 `stream: []`。
+
+另有两处**行形状查表结论**（runbook S7.5/S7.8，全绿）：
+- `connection` 行（web-app cordis.patch.yml）tag 间**逐字节同形**（仅注释位移）——fence 腿整行重述继续有效；
+- `__DSH_TRANSPORT__`/ownsHost 消费点、`data-sidebar-collapsed`（AppFrame.tsx:210 仍在）、`conversation.session.header` 与 `settings.general.item` slot、`apps/web/index.html` viewport meta、`webserver injections.ts` head splice——**全部原样存活**。
+
+## 四、S7 冒烟明细（unit dsh-4988-test）
+
+| 探针 | 结果 |
+|---|---|
+| `web --dump-config` → dashr-repl 行 + `DASHR_KERNEL_PYTHON` 注入 | ✅ |
+| fence：trusted Host `/api` = **401**（过栅栏卡认证）；evil Host = **403** | ✅ |
+| token 鉴权根页 200 + `__DSH_TRANSPORT__` boot script 在页 | ✅ |
+| boot graph `"id":"better-dsh"` + `/plugins/??better-dsh/client.js&rev=…` | ✅ |
+| client bundle：200，**17824B 与本地逐字节一致**（+84B = 服务端 sourceMappingURL 追加，符合已知行为） | ✅ |
+| mobile 锚点：layout 模块含 `data-sidebar-collapsed` + `SIDEBAR_AUTO_COLLAPSE = 1024` | ✅ |
+| hashline 中央库 `$DSH_HOME/storages/dsh-better-edit/hash-store.sqlite` 在位 | ✅ |
+| 0.1.5 新组合在场：ui-sidebar-right/documentpreview/files、client-resources、api-workspace-files、ui-deliverables 均入 module batch | ✅ |
+
+实例**保持运行**供 user 验收：`http://127.0.0.1:4988/?token=<redacted>`（token 每次重启轮换）。
+
+## 五、发现的瑕疵（定性 + 去向）
+
+- **F1（流程/runbook 漂移）**：`packages/node_modules` 在新 tag 安装布局下不再生成 → runbook 的 `../../node_modules/.bin/tsx`（build-client）失效，正确为 `../../../node_modules/.bin/tsx`。→ 已回写 AGENTS.md §二。
+- **F2（工具链坑，重要）**：canonical 的 npm-range optional peerDeps（`>=0.1.2-alpha.1 <0.2.0-0`）在 pnpm 11 严格预发布 semver 下**不匹配 workspace `0.1.5-rc.2`**（元组规则），autoInstallPeers 落到 registry **0.1.2-rc.1**（唯一满足该 range 的 registry 版本）→ 副本 node_modules 双身份，tsc 品牌类型互斥报错。**解法（S3 新增手术）**：副本 package.json devDependencies 注入 14 个 `workspace:*`（dashr 实际 import 的 dsh-* 名单），每次 rsync 后重打。→ 已回写 AGENTS.md §二；canonical 不动（npm 发布语义保持）。
+- **F3（上游观察，非阻塞）**：rc.2 的 `test`/`build:bench` scripts 前置 `build:native-system`；主 `build` 已含（scripts/build.ts:44），无额外步骤。`native/system/packages/linux-x64/bin/glibc/system.node` 已产出。
+- **F4（环境冲突）**：4997（127.0.0.1）、4998、4999（0.0.0.0）被 superd multi-context PoC 占用（`~/workspaces/superd/.scratch/multi-context-poc/poc4-v3-e2e.mjs`，pid 2233871 + 1393092，Sep 10 19:41 起，独立 DSH_HOME）——不可杀（user 的在跑实验），本轮实例改 **4988**。**注意：若 Caddy test.pc.randomhash.app 后端指 4999，域名叫到的将是 superd 实例**——user 域名验收前需先对齐端口或等 PoC 结束（Caddyfile 红线未动）。
+- **F5（上游观察）**：`pnpm peers check` 有 WARN（副本 npm-range peers vs workspace 版本）——F2 的同一根源，运行期无影响（profile symlink 直连 monorepo）。
+
+## 六、流程化产出
+
+- 本报告 + AGENTS.md §二 write-back（tag 对齐记录、tsx 路径、devDeps 手术、端口事实）。
+- `.scratch/dsh-v0.1.3-alpha.2-local-patches-backup.patch`（旧 patch 备份，切换前快照）。
+
+## 七、Open items
+
+1. **user 验收**（第一人称）：127.0.0.1:4988 实例（域名词见 F4 注意）；重点 = dashr-repl 真跑一轮（kernel 三级供给在新 runtime 下）、better-edit 读改写、mobile 手势/zoomGuard 真机。
+2. canonical 改动（4 文件 src + 6 文件 test）**未 commit**——等 user 指令（上轮有 commit 前 "Wait" 先例）。
+3. Caddy test.pc → 4999 端口归属与 superd PoC 的冲突排查（user 裁决）。
+4. 既有遗留：v0.2.5 zoomGuard standalone 双形态 CDP 复验（AGENTS.md 已记）。
+5. prod（3080）**维持 0.1.3-alpha.2 不动**；升 0.1.5 需另行裁决（对账报告 §六建议先行）。

package/docs/50_test-reports/v0.2.3b-hashline-content-locator/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,73 @@
+# v0.2.3b hashline-content-locator 实测报告
+
+> 2026-09-08 · 环境：DSH 4999 dev 线（upstream checkout `0.1.3-alpha.2-82a5fd6-dirty`，
+> `DSH_HOME=~/.workspaces/dashr/.dsh-test` 语义路径 `.dsh-test`），better-dsh vendored
+> hashline 桥（change `2026-09-08-v0-2-3b-hashline-content-locator`）。
+> 前置：诊断报告 `2026-09-08-hashline-edit-E_RANGE_UNVERIFIED跨轮会话键失效-诊断报告.md` §7。
+
+## 0. 一句话结论
+
+五项裁决全部落地并实测通过：served 账本去 session 化（schema v7，path 主键）、集中存储
+`$DSH_HOME/storages/dsh-better-edit/`、verifyServedRange 内容快道、write 回放移除、失败文案
+修正。单测 12/12 新增全绿、全量 491 过 2 挂（挂项为先于本改动存在的上游类型漂移，stash 基线
+复跑证实）；4999 真实 agent session 第一人称实测：write 只回确认信封（无锚点回放）、read 记账
+进中心库（served 表 `path,hashes,reported,updated_at`，无 session_id 列）、跨会话 edit 链路
+走通、全程无任何 `.dsh_better_edit` 点目录。
+
+## 1. 单元层（canonical，`npx vitest --run`）
+
+- 新增 `test/hashline-store.spec.ts` **12/12 绿**：v7 中心库落位与无点目录断言、path 主键
+  upsert 合并、跨"会话"上下文免 read 取行（fork 模拟）、drift 标记随 path、v6→v7 迁移重建
+  （ handmade 旧库打开后 `session_id` 列消失、version=7）、TTL prune、verifyServedRange 六态
+  矩阵（账本未见→内容快道通过；账本全知匹配→过；内部漂移→`E_RANGE_STALE`；账本洞→
+  `E_RANGE_UNSERVED`；单边账本→`E_RANGE_UNVERIFIED`；拒绝文案含"Read the file once…
+  resubmit the whole batch"）。
+- 全量：**491 passed / 2 failed**，2 挂项（`handlers/agent.ts` `snapshotEvents`、
+  `SessionHeader.isSeeded`）经 `git stash` 基线复跑**证实先于本改动存在**（上游 alpha.2 对齐
+  类型漂移，非本 change 引入；tsc 同样仅此 3 条既有错）。
+
+## 2. 构建（monorepo 副本）
+
+- rsync（AGENTS exclude 表）→ `pnpm --filter better-dsh exec tsdown` → **9 files 529.98 kB**，
+  `lib/index.js` 形态正确 → `tsx scripts/build-client.ts` → `lib/client/index.js`
+  17.82 kB（md5 `a88850ec056aae943934adfdeb79347e`，client 半零改动）。
+- **教训（新增坑，已亲历）**：直接以 `node_modules/.bin/tsdown` 裸跑（不经 pnpm workspace env）
+  会产出 `.mjs` 形态（7 files），boot 即 `ERR_MODULE_NOT_FOUND lib/index.js`——**必须用
+  `pnpm --filter better-dsh exec tsdown`**；且 `--delete` rsync + tsdown clean 会连带重置副本
+  配置与 lib（本次已重建，副本 package.json/tsdown.config 现与 canonical 一致）。
+
+## 3. 4999 第一人称实测（真实 agent session，CDP 驱动 GUI）
+
+工作区 `/home/u1`（GUI 工作区选择器未绑到 ws-probe，落在默认 home 桶——不影响断言），
+模型 DeepSeek-V4-Flash。三段剧本：
+
+| 步 | 动作 | 断言 | 结果 |
+|---|---|---|---|
+| S1 | write 创建 `probe-v023b.md`（6 行规格内容） | write 结果**无** `--- Auto-read (hashline anchors) ---` 段，仅确认信封 | ✅（transcript 仅 "Produced probe-v023b.md"） |
+| S1 | read 全文 | 锚点记账进**中心库** | ✅ `.dsh-test/storages/dsh-better-edit/hash-store.sqlite`（+WAL）出现；served 表列 `path,hashes,reported,updated_at`，**无 session_id**；单行 `path=/home/u1/probe-v023b.md → ["Udx","nyO","zlr","DBc","Zuy","GTH"]` |
+| S2（**新会话**，不同 session id，从未观察/读过该文件） | 直接 edit（锚点 zlr/zlr 来自 S1） | 旧代码此处必 `E_RANGE_UNVERIFIED` | ⚠️ 见 §4——被**宿主层另一道闸**前置拦截 |
+| S2 | read 一次后同参数 edit | 成功落盘 | ✅ 文件第 3 行 = `beta line EDITED-BY-v0.2.3b-PROBE`；无任何 E_RANGE_* |
+
+存储探针：`/home/u1/.dsh_better_edit` **不存在** ✓（home 即 workspace，dot-dir 若仍会创建必然在此）。
+
+## 4. 实测发现：宿主 fs 观察策略是跨会话 edit 的另一道（设计内）闸
+
+S2 盲 edit 返回 `[E_NOT_OBSERVED] The file has not been observed in this session
+(read-before-write policy). Call read() first` ——这是 **`dsh-fs-observation-policy` 宿主插件**
+的 observed-state 守卫（owner=agent 会话的 WeakMap，read/write/edit 记版本），**不是** hashline
+served 账本。定性：
+
+- **保留**（user 裁决语义："安全守卫在确认覆盖/见过"——read-before-edit 正是宿主层的"见过"）；
+  本 change 的范围是把 hashline 层的**重复**session 账本拿掉，不是拆宿主守卫。
+- 事故剧本（S1 write → fork 子会话 edit）在原线上之所以先报 hashline 错，是 fork 继承了观察态；
+  hashline 层修复后，**同进程 fork 续聊**的 edit 将直接由内容快道放行（fork 不再需要冗余 read）。
+- 全新无关会话（如本 S2）盲 edit 被宿主拦——符合"读过才许改"的常理，非回归。
+
+## 5. 残留与移交
+
+- 预置 guidance 覆盖目录现种子于 `storages/dsh-better-edit/`（ensurePresetGuidance 同目录）——
+  与 store 同居一处，属可接受的组织形态。
+- 旧 12 个 `<workspace>/.dsh_better_edit/` 弃置未删（TTL 语义自然清空；物理清理留 user 决定）。
+- 4999 实例已停本探针产物：`/home/u1/probe-v023b.md` 与 `.scratch/ws-probe/` 已清理。
+- **发布闸状态**：a 第一人称实测 ✅ → b 本报告 ✅ → **c user 明确确认放行 ⏳**（单次有效；
+  未 commit、未 tag、未 publish）。

package/docs/50_test-reports/v0.2.3c-mobile-wave/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,47 @@
+# v0.2.3-c mobile wave 实测报告
+
+- 日期：2026-09-11
+- 范围：`better-dsh@0.2.3-c`（npm）/ tag `v0.2.3c`
+- 验证环境：Dev/Test 1 源码线 4988 实例（upstream `dsh-v0.1.5-rc.2`，`DSH_HOME=~/.dsh-test`，LAN=1 socat 中继），user iPhone 真机第一人称实测
+- 关联：`upstream-dsh-0.1.5-rc.2-local-test-report.md`（对齐轮全链路）、AGENTS.md §二 mobile wave 条目、§四红线
+
+## 一、变更清单
+
+1. **手势状态输入只认官方面**（红线落地；起因：旧实现读第三方 Better Sidebar 的 `body[data-dsh-sidebar-collapsed]`，插件移除后属性恒缺 → `readRightOpen` 永真 → 状态机整体毒死）：
+   - 左栏：动作 `ctx.layout.toggleSidebar()`；状态读 AppFrame `[data-sidebar-collapsed]`。
+   - 右栏（0.1.5 ui-sidebar-right）：开 = 官方控件 `[data-sidebar-right-expand]`（会话头角落），关 = `[data-sidebar-right-toggle]`（dock chrome）；状态读双 facet：`fullscreen = [data-rightbar-fullscreen] 在场`，`trackless = [data-rightbar-collapsed] 在场`，`readRightOpen = fullscreen || !trackless`。
+2. **响应式零自设像素阈值**：CSS 规则键纯 `[data-sidebar-collapsed]`（无 @media），上游 auto-collapse 收 rail（今日 56px）时我们压成 0px，上游改阈值自动跟随；手势激活 band = 粗指针（`pointer: coarse`）∨ 任一面板窄态，细指针全静息。
+3. **`mobile.breakpoint` 配置删除**（schema + boot payload + client 三处）；zoomGuard 内部 768 兜底不动。所谓"mobile 配置卡"从未存在（client 半唯一设置行是 failover）。
+4. **0.1.5-rc.2 对齐移植**（随批发布）：persistence seam `inspect`→`stat`+`open(id,'read')`+`handle.read()`（`src/url-schema/handlers/agent.ts` `persistedEventsOf`）；`subagents.sendMessage` 统一 seam（下行 child / 上行 `parentSession`，`src/bridges/index.ts`、`src/subagents-surface.ts`）；session 事件名 `tool/code-dispatch(-start)` → `tool/ptc-dispatch(-start)`（`src/index.ts`，载波 `tools/ptc-dispatch-log` 名不变）。
+5. **船货卫生**（本次新增 `dashr/scripts/copy-docs.mjs` 替换裸 `cpSync` prebuild）：发布 docs 副本排除 `60_exploration-and-research/`（gitignore 明文 never publish）、`superd/`、`dsh-sys-prompt_*.md`、`*_artifacts/`（2.8MB 探针产物），并对副本内 .md 做 `token=<20+字面量>` 脱敏。**事实记录（2026-09-11 全版本扫描）**：泄漏机制 = prebuild `cpSync('../docs','docs')` 把仓库根 docs 全量拷进包内再随 `files:["docs"]` 打包（docs:// URL schema 的运行时供给面，v0.1.8d 起存在）；包内镜像 `dashr/docs/` 被 `dashr/.gitignore` 的 `/docs/` 忽略 → git 永远看不见，2026-09-03 "never publish" 裁决只落了 git 轴，npm 轴漏网。受影响版本（registry 不可撤）：0.2.2-a(6 文件) / 0.2.2-b(8) / 0.2.2-c(33) / 0.2.3 游离(6) / 0.2.3-b(48 + superd 4)。**内容定级复核：全部 `token=` 命中均为占位符（`token=…` / `token=«redacted»`），真实 token 字面量从未上过 registry**——泄漏内容 = 研究笔记 + superd 蓝图 + 测试报告，无凭据类材料。0.2.3-c tarball 70 文件 / 757KB，敏感扫描零命中。
+
+## 二、第一人称验收（user 真机，2026-09-11）
+
+1. 初版手势（读第三方 body 属性）：左滑右滑全灭——user 报障并裁决"左栏是官方的，必须永远工作；状态输入只许寻址官方面"。
+2. 官方面重写版：左滑开右面板成功；右滑误开左栏——user 亲自诊断"手机上右栏全屏不占轨道，`data-rightbar-collapsed` 在场而面板盖满 → readRightOpen 误判 false"。修为双 facet 读法后 user 确认：**"没有问题，是成功的"**。
+3. 4988 活体证据：boot graph 含 `"id":"better-dsh"`；served client.js 官方选择器 4 处（`data-sidebar-collapsed` / `data-sidebar-right-expand` / `data-sidebar-right-toggle` / 双 facet 读法）、第三方死引用 0。
+
+## 三、构建与套件
+
+- 发布产物在 monorepo（0.1.5-rc.2 workspace 手术环境）构建：tsdown 9 文件 530KB + client 18.57KB；canonical 与副本 src/cordis.patch.yml/build-client.ts 逐字节一致（diff rc=0）。
+- 套件：monorepo 环境 492/492 通过 + tsc 0（对齐轮已录）。canonical 本地套件 14 挂 + src 5 类型错——**环境错位非产物缺陷**：canonical node_modules 的 `@deepseek-ai/*` peers 停在 0.1.2-alpha.3（registry fallback），而 src/test 已按 0.1.5 API 移植；canonical package.json 按教义保持 npm-range peers 不动（发布语义），手术只在副本。canonical dev 环境刷新另行处理，不阻塞本发布（同源同产物已由 4988 全链路验证）。
+
+## 四、0.1.3-alpha.2（当前 prod host）兼容矩阵（2026-09-11 源码核验）
+
+| seam | 0.1.3-alpha.2 | 结论 |
+|---|---|---|
+| `sessionPersistence.stat` / `open(id,'read')` / `handle.read()` | handle 模型已在（types/index.d.ts + handle.d.ts 实证） | 兼容 |
+| `subagents.sendMessage` / `startContinuable` | 二者均在 lib/index.js 导出实证 | 兼容 |
+| 载波 `tools/ptc-dispatch-log` | spill-policy/tools/scope/tool-cordis 均引用 | 兼容 |
+| session 事件 `tool/ptc-dispatch(-start)` | 不在旧 catalog（旧名 code-dispatch），但 `adoptSessionEvent` 与 seed envelope 校验只查 envelope 不查目录（vocabulary-growth 容忍设计，`ignorable` 键合法） | **降级不破坏**：事件安全落盘，旧 host UI 不渲染 dispatch 卡片；host 升 0.1.5 后自愈 |
+| mobile wave（CSS/手势/boot payload） | 纯 client 面，host 无关 | 兼容 |
+
+结论：0.2.3-c 在 0.1.3-alpha.2 prod host 可安全安装运行，repl-dispatch 卡片渲染待 host 升级后恢复。
+
+## 五、发布操作记录
+
+- canonical `package.json`：version `0.2.3-c`；prebuild → `node scripts/copy-docs.mjs`。
+- lib/ 构建：monorepo `pnpm --filter better-dsh exec tsdown` + `tsx scripts/build-client.ts`（三级 ../..），拷回 canonical。
+- `npm pack --dry-run`：70 文件 / 757KB，`60_exploration|superd|_artifacts` 零命中，token 零命中。
+- GitHub：commit + tag `v0.2.3c` → push origin main；npm：publish → `npm view` 复核（实际时间戳以操作为准）。
+- prod 3080 部署：**未执行**（user 未指令；user 以普通用户身份自装实测，per 2026-09-03 裁决先例）。

package/docs/50_test-reports/v0.2.4-ios-focus-zoom-suppression/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,158 @@
+# v0.2.4 iOS Focus 放大抑制（zoomGuard）实测报告
+
+- **Change**: `openspec/changes/2026-09-03-ios-focus-zoom-suppression`
+- **版本**: better-dsh 0.2.2-a → **0.2.4**（canonical `dashr/package.json`；npm 已发布线 v0.2.3 顺延一档）
+- **日期**: 2026-09-03
+- **范围**: 纯 host 半（boot script 增量 + config 面 + payload 扩键）；client 半零改动，无需 build-client
+- **状态**: 单测/构建层自测完成；4999 实例验证（2.3）与真机观察（3.x）待做
+- **状态**: 4999 实例验证（2.3）✅ 完成（含一轮 blocker 返修 commit `59870fc`）；真机观察（3.x）待 user
+---
+
+## 一、实测范围与结果表
+
+| # | 项目 | 层面 | 结果 | 证据 |
+|---|------|------|------|------|
+| 1 | vitest 全量（canonical） | 单测 | ✅ **460/460**（基线 428 + 新增 32；36 files） | `cd dashr && npm test` |
+| 2 | tsc --noEmit（含新 spec） | 类型 | ✅ 0 错 | `npx tsc --noEmit` |
+| 3 | schema：默认值 / off 透传 / font·bogus fail-loud | 单测 | ✅ | `test/zoom-guard.spec.ts` 'config schema' |
+| 4 | 纯函数矩阵（UA × 视口 × config；幂等；还原；bare token；大小写） | 单测 | ✅ 32 tests | 同上 |
+| 5 | 生成脚本形状（ES5、无 `</script`、断点派生 `(max-width:767.98px)`、payload 序列化） | 单测 | ✅ | 同上 'generated zoomGuard section' |
+| 6 | **boot script 评估端到端**（stub DOM 执行真实脚本文本） | 单测 | ✅ 全矩阵 | 同上 'boot script evaluation'（12 场景） |
+| 7 | 构建产物复核（lib/index.js 抽取嵌入函数源重组段 eval） | 构建 | ✅ ES5-ok + provisional/reconcile/还原/风暴全绿 | `.scratch/zg-built-check.ts` |
+| 8 | monorepo 副本 rsync + tsdown（host 半） | 构建 | ✅ 9 files 528.31 kB | `pnpm --filter better-dsh exec tsdown` |
+| 9 | dump-config 覆盖层渲染 `mobile.zoomGuard` | 集成 | ✅ `'off'` 逐字渲染于 dashr-repl 行 | `--patch .scratch/zg-overlay.yml` |
+| 10 | 4999 实例（boot script 注入形状 + CDP 视口矩阵 + off 逃生门 + 桌面 user 复验） | 集成 | ✅ **9/9 矩阵 + 4 冒烟 + off PASS + 桌面 PASS**（经一轮 blocker 返修，见八） | §八；脚本 `.scratch/zg-verify/` |
+| 11 | 真机 iOS PWA 观察（放大抑制/键盘自愈/回弹） | 真机 | ⏳ **待做**（user） | tasks 3.1–3.3 |
+
+## 二、实现要点（含 design.md 偏差说明）
+
+1. **纯函数 = 发布源**：`src/mobile/zoom-guard.ts` 的 `isIOSClassUA` / `mergeViewportTokens` / `shouldApplyZoomGuard` 以 ES5 自包含风格编写，boot script 经 `Function.prototype.toString()` 嵌入这三个函数 —— 单测覆盖的源码与页面执行的源码字节一致（构建后产物已复核该嵌入幸存于 tsdown bundle）。
+2. **schema enum 形式**：本 fork schemastery 无 `choice()`；采用 `z.union(['meta','off']).default('meta')`（字面量 union 即 enum，非法值 config load 即抛）。**'font' 预留值位不进 enum**（决策：未实现值若被 schema 接受则运行期静默 no-op，fail-loud 优于静默；预留以注释标注）。
+3. **⚠ 与 design D4 的重要发现级偏差（已按 D4 精神实现）**：webserver 的 head 注入 splice 点在 `<head>` 开标签**紧后**（`packages/host/webserver/src/injections.ts` `renderIndexInjections`），即 boot script 执行时上游 stock viewport meta（`apps/web/index.html:5`）**尚未解析**——"meta 缺失 → 创建"是常态路径而非边角。若照 D4 字面创建后不管，页面将永久双 meta，依赖引擎未定义的 multi-meta 合并语义，且 spec 的"还原 stock content"场景失义。实现为 **provisional meta + MutationObserver reconcile**：脚本执行时即建 provisional meta（抑制令牌先于一切 bundle 生效，时序要求满足）→ parser 插入 stock meta 时记录真 stock、token merge 改写 **stock meta 本体**、移除 provisional → 单 meta 文档；此后 resize 进出断口均以记录的 stock 为基线改写/还原（字节级还原）。无 MutationObserver 的引擎降级为 provisional 常驻（仍具抑制）。两路径（stock 先在场 = 直接改写；stock 后到 = reconcile）均有单测钉住。
+4. **payload 面**：`zoomGuard` 与 breakpoint 等键同构（配置了才进 payload，schema 默认保证生产必带 'meta'）；`zoomGuard:'off'` 时整段不生成（逃生门 = 零脚本段，非运行期判断）。
+5. **配置生命周期**：zoomGuard 随 mobile 腿（`mobile.enabled=false` 时整个 `__DASHR_MOBILE__` 不注入，zoomGuard 一并不生效）——design D5 "同路径同生命周期" 的字面执行。
+
+## 三、环境事实
+
+- canonical：`/home/u1/workspaces/dashr/dashr`（node_modules 在场，vitest/tsc 直接跑）
+- monorepo 副本：`upstream/deepseek-harness/packages/better-dsh/better-dsh`（rsync + tsdown host 半）
+- Node v22.22.1 / vitest 4.x / tsdown 0.15.x
+- dump-config：`DSH_HOME=.dsh-test npm run dsh -- web --dump-config --patch .scratch/zg-overlay.yml`（dump-config 只渲染 patch 层，schema 默认由单测钉住）
+
+## 四、boot script 评估测试明细（单测第 6 项）
+
+stub DOM（El/Document/MutationObserver/live matchMedia/resize 记录），`new Function` 执行 `buildBootScript` 真实输出：
+
+| 场景 | 断言 |
+|------|------|
+| iPhone ∧ 窄 | 脚本时 provisional meta（`maximum-scale=1, user-scalable=no`）；stock 解析后单 meta、content = `width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no` |
+| 非 viewport 解析插入 | observer 不误触发，继续守望 |
+| 宽↔窄往返 + 5 连 resize 风暴 | 离带 = 字节级还原 stock；回带 = 合并；风暴零叠加 |
+| stock 先在场（worker 形态） | 直接改写，无 provisional |
+| 无 stock 页面 | provisional 常驻；离带移除自建 meta |
+| iPad / iPadOS 桌面 UA+多点 | 改写生效；Mac 桌面（单/零触点）不生效 |
+| Android ∧ 窄 / 桌面任意宽 | stock 原样、零监听器 |
+| iPhone 宽载入后旋转入带 | 后补改写生效 |
+| zoomGuard off | 无脚本段、零改写、零监听 |
+| authorities + mobile 双腿 | `__DSH_TRANSPORT__` 与 zoomGuard 互不干扰 |
+| 断点 900 | matchMedia 收到 `(max-width:899.98px)`，payload 带 `"breakpoint":900` |
+
+## 五、真机观察（user，PWA standalone 主用法）—— TODO
+
+> 以下三章按 design D6 留给 user 真机执行（4999 或真实入口，iOS 版本号请记录）。
+
+### 5.1 放大抑制判定（tasks 3.1）— TODO
+
+- [ ] Safari 态：focus composer / permission select / settings 各 input / 切会话自动聚焦 —— 无 115–120% 放大
+- [ ] PWA standalone 态：同上全过
+- [ ] 双指缩放仍可用（iOS 10+ 应忽略 user-scalable=no 对 pinch 的约束）
+- [ ] `zoomGuard:'off'` 时放大复现（逃生门复验）
+
+### 5.2 键盘遮蔽自愈判定（tasks 3.2）— TODO
+
+- [ ] PWA 态 unzoomed 下 focus composer：键盘弹出后 composer 是否被引擎 resize 抬到键盘上方（innerHeight/100dvh 收缩联动）
+- [ ] 键盘关闭后 viewport 回弹（对照 dev.to 2026-07 记录的 iOS 17/18 standalone 卡死 bug）
+- [ ] Safari 态对照记录
+
+### 5.3 观察结论回填（tasks 3.3）— TODO
+
+- [ ] 研究文档 v2 §6 决策点 3/4 回填
+- [ ] follow-up 取舍：visualViewport shim / display-flip 自愈 / focus gate 讨论输入
+
+## 六、发现的瑕疵与去向
+
+- **发现（非瑕疵）**：head 注入 splice 位于 stock meta 之前 → 促成 provisional+reconcile 设计（见二.3）；已进 upstream-alignment S7 查表第 8 条（viewport 行形状 + splice 次序两查点）。
+- dump-config 只渲染 patch 层、不显 schema 默认 —— zoomGuard 默认值的可观测面在 payload（4999 shell 页）与单测，不在 dump-config；如需 dump 可见需显式配置（本报告第 9 项即此形态）。
+
+## 七、Open items
+- ~~tasks 2.3（4999 实例验证）~~ ✅ 完成（见八；返修 `59870fc` 后 9/9）
+- tasks 3.x 真机观察 —— user
+- 发布/npm publish 与 prod 部署 —— 另按年龄门流程，不在本 change 内
+
+---
+
+## 八、4999 实测记录与 blocker 返修轮（lead，2026-09-03 晚）
+
+### 8.1 首轮矩阵与 blocker 发现
+
+- 冒烟四断言全过：A）shell head 内联脚本含 zoomGuard 段；B）boot graph 含 `"id":"better-dsh"` 与 client URL；C）zoomGuard 段（HTML 偏移 25313）早于应用入口 module script（27056）——注：client-modules 的 combo 注册脚本（1286）先于我们执行，但纯工厂注册无 DOM/focus，行为层时序满足 S2；client.js 单包 URL 200 且与 `lib/client/index.js` 前缀字节一致（+84B sourceMappingURL，S7 惯例）。
+- **CDP 视口矩阵首轮 7/9**：两个失败项均为**初始窄载入不 guard**（iOS+390、iPadOS 冒充+390）；跨断口 resize 与事后 synthetic resize 均生效。
+
+### 8.2 根因定位（诊断脚本 `diag.mjs` / `isolate.mjs`）
+
+- 事件时序实测：boot script 执行于 head 解析期，此时布局视口为 viewport-meta 未应用前的默认宽 **980**（`docStart innerWidth=980, mq.matches=false`）→ 首评不 guard；引擎随后应用 `width=device-width` 收窄到 390，但**该转换在载入期间不向页面派发 `resize` 事件**（探针隔离三变体一致；我们的 resize 监听在位且事后手动 dispatch 立即生效）。
+- 关键后果：deferred module script（React 挂载 → unlock effect 自动聚焦）在 DOMContentLoaded 前执行——依赖 resize 事件的补评可能晚于首次 auto-focus。**初始窄载入 = iPhone 用户打开 DSH 的主路径，blocker 级**。
+
+### 8.3 返修（doer 第二轮，commit `59870fc`，tag `v0.2.4` 前移）
+
+- **早期载入重评梯子**：首评未 applied 时启动 ~10ms poll 调 `re()`，三停条件 = applied / readyState complete / 200 tick（~2s）；`apply(true)` 主动取消待发 tick，稳态零 timer。guard 不再依赖任何事件通知——事件缺失只影响"多快"发现，不影响"是否"发现；首次布局必然先于 deferred scripts，抑制仍落在任何输入可聚焦之前。
+- **MQ change 监听兜底**（`mq.addEventListener('change', re)`，老引擎 `addListener` 形态）与 window resize 双通道。
+- 测试 466/466（+6：晚翻无 resize、readyState 停止、非 iOS 零 setTimeout、MQ 通道、legacy addListener、梯子先于 stock 解析落 provisional）；tsc 0。
+
+### 8.4 返修后终验（全绿）
+
+- **CDP 矩阵 9/9**：iOS+390 → guarded（单 meta、两 token 在位）；iOS+1280 → stock；iPadOS 桌面冒充+touch+390 → guarded；Android+390 / 桌面+390 / 桌面+1280 → stock（零改写）；跨断口三段（宽载入 stock → 入带 guard → 出带字节级还原 stock）。
+- **off 逃生门 live PASS**：home 层 `.dsh-test/cordis.patch.yml` 覆盖（注：CLI `web` 子命令不认 `--patch`，该路仅 dump-config 可用）→ shell **整段不发射**、payload `zoomGuard:'off'`、iOS+390 live = stock。验后已删覆盖文件并还原默认态。
+- **默认态恢复复验 + 桌面 user 复验 PASS**：还原后 iOS+390 → guarded；桌面（无 UA 伪装）meta stock 单条、app 完整渲染（root/composer/`[data-composer-card]`/sidebar/slots 在位，标题与占位文案正常）。
+
+### 8.5 遗留观察（非阻塞）
+
+- 真机 iOS Safari 上 8.2 竞态是否同样存在未证（无法本地复现 iOS 引擎）；梯子设计使其无关化——真机观察（五）会给出实证。
+- 探针实验中一次"全探针"运行曾捕捉到 resize 送达（时序非确定论），进一步佐证不能依赖事件通道。
+- CDP 测试脚本存 `.scratch/zg-verify/`（matrix/diag/isolate/off/final 五件），可复跑。
+
+## 九、v0.2.5 standalone 分流（change `2026-09-03-zoomguard-standalone-font-floor`）—— 骨架，4999/真机结论待回填
+
+> 背景：真机首批观察（§五）——浏览器态 meta 改写完美（放大抑制 + pinch 保留），但 **Add to Home Screen PWA standalone 态引擎尊重 `user-scalable=no` → pinch 失效**（Discourse 注释未覆盖的形态；spec v1 的 "pinch remains engine-controlled" 括号在 standalone 不成立）。user 裁决：standalone 态完全不碰 viewport meta，改注入 16px 字号地板 CSS；browser 态维持 v0.2.4。user 主用法即 PWA。
+
+### 9.1 实现摘要（doer，2026-09-03）
+
+- 纯函数（`src/mobile/zoom-guard.ts`，ES5 自包含，toString 嵌入，`var ZD=`/`var ZF=` 与 ZI/ZM/ZS 同款）：`isStandaloneDisplay(mqMatchesStandalone, navStandalone)` = 严格 `=== true` 双源 OR（MQ 主源 + `navigator.standalone` 老 iOS 兜底）；`buildFontFloorCss(bp)` → `@media (max-width:{bp-0.02}px){ input,textarea,select,[contenteditable="true"]{ font-size:16px !important } }`（断口派生与 meta 腿一致：768→767.98、900→899.98）。
+- boot script 分流（D1）：iOS 判定后、任何 meta 逻辑前 —— `var sa=ZD((window.matchMedia&&window.matchMedia('(display-mode: standalone)').matches),(navigator.standalone===true));` standalone → `headEl()` 注入 `<style id="ios-zoom-font-floor" data-plugin="better-dsh" data-plugin-css="better-dsh/zoom-font-floor">`（textContent=ZF(rawBp)）后 **return**：其后 provisional/reconcile/监听/梯子代码字面不可达，meta 字节不动。**style 注入不设宽度门**（宽度由 CSS media query 表达，宽屏 standalone 也注入、规则自然不匹配）。
+- `'off'`：整段不发射（web-trust 门不变、零改动）；`'meta'` 语义升级为自动双形态（enum 不动）。web-trust.ts / client 半零改动。
+
+### 9.2 单测（canonical，doer）
+
+- **478/478 + tsc 0**（v0.2.4 基线 466，+12）：双源判定矩阵（含 undefined 单源兜底）、CSS 文本钉扎（selector 集合 / `!important` / 768→767.98 与 900→899.98）、standalone 矩阵（MQ 源：style 在场 + 三认领属性 + meta 字节不动 + 零 addEventListener/setTimeout/MutationObserver 痕迹 + 零窄带 MQ 探针；宽屏仍注入；navigator.standalone 单源；无 matchMedia 兜底；断口 900；browser 态显式无 style；off 双零）。
+- stub 基建：`runBootScript` 增 `standaloneAtScriptTime`/`navStandalone` 参数，matchMedia 按查询串分流（display-mode 探针不再误读窄带裁定）；browser 全矩阵零回归（mediaQueries 断言更新为含 display-mode 前导探针）。
+
+### 9.3 4999 CDP 双形态（lead，2026-09-03 深夜）—— ✅ 8/8 全绿
+
+**⚠ 测试方法学发现（重要）**：Chrome 的 `Emulation.setEmulatedMedia` **不支持 `display-mode` 特性**（实测 pre-nav/post-nav 设置后页面内 `matchMedia('(display-mode: standalone)').matches)` 恒 false —— Chrome 可仿真特性集不含它，DevTools Rendering 面板亦无此项）。改用 **matchMedia API 边界注入**：`Page.addScriptToEvaluateOnNewDocument` 在一切页面脚本（含 head 注入 boot script）之前包一层 `matchMedia`，仅对含 display-mode+standalone 的查询返回 `{matches:true}`，其余透传 —— boot script 全部分支逻辑照真运行（自检探针 truth=true 证实注入生效）。
+
+| 场景 | 断言 | 结果 |
+|---|---|---|
+| standalone+iOS+390 | meta **字节不动**（`width=device-width, initial-scale=1` 原文）= pinch 恢复前提 | ✅ |
+| standalone+iOS+390 | `#ios-zoom-font-floor` 在场，认领属性齐（data-plugin / data-plugin-css=better-dsh/zoom-font-floor），CSS 文本与 user 提案逐字一致 | ✅ |
+| standalone+iOS+390 | composer computed font-size = **16px**（地板生效） | ✅ |
+| browser+iOS+390 | meta guarded（两 token 在场）、无 font-floor | ✅ |
+| browser+iOS+390 | **client 特性探针**：sidebar computed 首列 0px、认领样式 98 条（v0.2.1f 特性在位） | ✅ |
+| standalone+iOS+1280 | floor 已注入（宽度无关）但 media query 不激活（composer 14px） | ✅ |
+| standalone+Android+390 | iOS 门 → 无 floor、meta stock | ✅ |
+| off | 双形态零发射（单测钉住；'off' 代码路径 v0.2.4 未动） | ✅ |
+
+脚本 `.scratch/zg-verify/dual-mode.mjs`（含 matchMedia 边界注入实现）；重启后 boot graph rev 已随 v0.2.5 变化，tsdown+build-client 双步完成、lib/client 在场（md5 `a88850ec…`）。
+### 9.4 真机复验（user）—— TODO（tasks 3.1）
+
+- [ ] PWA standalone：pinch 恢复 + focus 无放大（输入面 16px）。
+- [ ] 浏览器态：维持 §五 结论（meta 改写 + pinch 保留）。

package/docs/specs/agent/spec.md

@@ -0,0 +1,54 @@
+# agent Specification
+
+## Purpose
+
+Let the model address the agent roster, output artifacts, and full transcripts via `agent://` URLs — the single home for what upstream split across roster tools and a separate `history://` scheme.
+
+## Requirements
+
+### Requirement: Agent roster addressing
+The system SHALL let bare `agent://` return the roster of every live session, oldest first, as a five-column table: `id`, `status`, `kind`, `parent`, `last activity`. `status` comes from the live agent registry (`idle`/`running`; `-` when the session has no live agent); `kind` is the session header's `origin` (default `main`); `parent` is the delegating parent session id (`-` at top level); `last activity` is the last session event's time in ISO 8601 (`-` when the session has no events).
+
+#### Scenario: Listing all agents
+- **WHEN** the model reads bare `agent://`
+- **THEN** the system returns one row per live session with all five columns, e.g. `id  status  kind  parent  last activity`
+
+#### Scenario: Session without a live agent
+- **WHEN** a roster row's session has no entry in the live agent registry
+- **THEN** its `status` column renders `-`
+
+### Requirement: Agent output addressing
+The system SHALL let `agent://<id>` return that agent's output artifact: the rendered content of its last non-empty assistant message (matching `SubagentResult.output` semantics), or empty text when the agent produced no non-empty assistant output. Addressing is scoped to the caller's own family (the caller itself and its descendant children) — ids outside the family return `AGENT_UNKNOWN_ID`.
+
+#### Scenario: Reading a completed agent's output
+- **WHEN** the model reads `agent://<finished agent id>` from within its family
+- **THEN** the system returns the rendered text of that agent's last non-empty assistant message
+
+#### Scenario: Reading an unknown agent
+- **WHEN** the model reads `agent://<unknown id>` (or an id outside the caller's family)
+- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
+
+### Requirement: Agent transcript addressing
+The system SHALL let `agent://<id>/transcript` return the agent's full derived message history in order, each message headed by its role (`assistant`, `user`, `tool result`, `system`), with tool calls rendered as `[tool: name] arguments` and errors as `[tool error] …`. Addressing follows the same family scoping as output addressing.
+
+#### Scenario: Reading an agent's session history
+- **WHEN** the model reads `agent://<id>/transcript` for an agent in the caller's family
+- **THEN** the system returns every message of that session in order, role-headed
+
+### Requirement: Nested output addressing
+The system SHALL let `agent://<id>/<child>` return a direct child's output artifact, resolving the child only through the parent's enumerated children. Unknown children, or children not live in the session store, return `AGENT_UNKNOWN_ID`. Paths with more than two segments return `AGENT_BAD_PATH`.
+
+#### Scenario: Reading a nested child output
+- **WHEN** the model reads `agent://<parent id>/<child id>` and the child is a direct child of that parent
+- **THEN** the system returns the child's output artifact
+
+#### Scenario: Child not enumerable from the parent
+- **WHEN** the model reads `agent://<id>/<non-child id>`
+- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
+
+### Requirement: history has no scheme of its own
+The system SHALL provide transcript history only under `agent://<id>/transcript`. There is no `history://` handler and no special-case error for it: `history://` produces the generic `URL_UNREGISTERED_SCHEME` error like any other unregistered scheme.
+
+#### Scenario: history scheme is unregistered
+- **WHEN** the model reads `history://<id>`
+- **THEN** the system returns the structured `URL_UNREGISTERED_SCHEME` error listing the registered schemes (history not among them)

package/docs/specs/ast/spec.md

@@ -0,0 +1,34 @@
+# ast Specification
+
+## Purpose
+`ast` 是**纯 tool 设施**：无进程、无状态、无协议——文本进 → tree-sitter 语法树 → 结构匹配/改写 → 结果出。以 `dvc://ast` 设备面挂载（`ast_grep` 结构搜索 + `ast_edit` 结构改写，natives 懒加载），由 agent 在工具循环里主动调用；不设任何运行时拦截点、不订阅文件事件、不参与文本同步。与 hash-edit/LSP 的分工：结构问题归 ast，语义问题（类型/跨文件引用/诊断）归 LSP，锚点编辑归 hash-edit。
+
+## Requirements
+
+### Requirement: Pure tool semantics
+The ast device SHALL behave as a stateless function: every call carries its inputs (pattern, paths, content) and returns its result; no server process, no document mirror, no cross-call state SHALL exist.
+
+#### Scenario: Stateless call
+- **WHEN** the agent invokes `ast_grep` twice with identical inputs
+- **THEN** both calls parse independently and return identical results, with no cached tree or warm process in between
+
+### Requirement: Lazy natives, zero startup cost
+Parser natives SHALL load lazily on first use (natives-loader); host start and agent session start SHALL NOT spawn anything or load grammar binaries.
+
+#### Scenario: Cold session
+- **WHEN** a session ends without ever invoking the ast device
+- **THEN** no native library was loaded and no subprocess was created for it
+
+### Requirement: dvc scheme surface only
+The ast capability SHALL expose exclusively through the `dvc://ast` write/read contract (bare `dvc://` roster lists it; `dvc://ast` read returns its doc; `dvc://ast` write dispatches). No dedicated tool name, no scheme branches in read/grep/glob, and no hook into read/write/edit flows SHALL be added.
+
+#### Scenario: Surface inventory
+- **WHEN** the model-facing tool surface is enumerated
+- **THEN** ast appears only as the `dvc://ast` device — its invocation is an ordinary `write` the agent decides to make
+
+### Requirement: Structural semantics boundary
+The ast device SHALL provide structural matching/rewriting only. It makes no claim about types, cross-file references, or diagnostics; a deployment wanting semantics SHALL use the lsp capability instead.
+
+#### Scenario: No semantic answers
+- **WHEN** the agent asks the ast device for type information or project diagnostics
+- **THEN** no such capability exists on the device surface (the call is not offered)

package/docs/specs/compaction-recall/spec.md

@@ -0,0 +1,46 @@
+# compaction-recall Specification
+
+## Purpose
+TBD - created by archiving change 2026-09-11-url-schemes-recallable-context. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Compaction manifest with nested chain
+The system SHALL expose the compaction manifest of the live session, one entry per successful compaction episode, each carrying: `label` (the `compaction/summary` event seq), `checkpoint_seq` (summary seq + 1), `compactionId`, timestamp, `shadowedRange`, `shadowedItems`, `shadowedTokenCount`, `replaces_checkpoint` (the previous episode's checkpoint seq when absorbed, else null), and an 8-section summary preview (≤100 chars per section).
+
+#### Scenario: Manifest reflects nested compaction
+- **WHEN** a session has two successful compactions where the second absorbed the first's checkpoint
+- **THEN** the manifest lists both episodes and the second entry carries `replaces_checkpoint` equal to the first episode's checkpoint seq
+
+### Requirement: Label resolution precedes ordinal
+For any bracket-addressed collection, the system SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal only when no label matches. Compaction episodes SHALL use the `compaction/summary` event seq as label; failed compactions SHALL NOT appear in any collection because they never emit a summary event.
+
+#### Scenario: Failed compaction is not addressable
+- **WHEN** a compaction attempt fails (summary not smaller than shadowed content) and the model reads the compactions manifest
+- **THEN** the failed episode is absent from the manifest and has no addressable label
+
+### Requirement: Canonical and prepared faces for compaction episodes
+For `ctx://session/compactions[<label>]`, the bare URL SHALL return the episode's structured summary (all 8 sections verbatim) as the prepared default face, and `:raw` SHALL return the episode's canonical content — the original shadowed span derived from `shadowedSeqs` (role + content per item). Line windows SHALL always apply to the canonical content, and the composite `:raw:<lines>` form SHALL be valid and equal `:<lines>`. The former `/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. When an unwindowed `:raw` read of the canonical face exceeds 65536 chars, the system SHALL append an actionable note naming `:N-M` line-window paging; windowed reads (`:N-M`, `:raw:N-M`) and the bare prepared face SHALL NOT carry the note.
+
+#### Scenario: Recall of the original span behind a summary
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` after the episode shadowed 559 items
+- **THEN** the system returns the original message-level content of all shadowed items, including tool results and assistant messages
+
+#### Scenario: Chained recall to pre-previous originals
+- **WHEN** the model reads `ctx://session/compactions[109245]:raw` (the first episode in a nested chain)
+- **THEN** the system returns the first span's original content even though later compactions shadowed its checkpoint
+
+#### Scenario: Unwindowed raw recall of an oversized span pages explicitly
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` and the span exceeds 65536 chars
+- **THEN** the system returns the full span followed by a note naming `:N-M` line-window paging, while `:raw:N-M` / `:N-M` return the windowed lines without the note
+
+#### Scenario: Removed /original sub-path
+- **WHEN** the model reads `ctx://session/compactions[221217]/original`
+- **THEN** the system rejects the path with `CTX_BAD_PATH`, echoing the URL
+
+### Requirement: Recall is read-only and lazily materialized
+The system SHALL serve all recall resources strictly read-only, SHALL build the episode index lazily from the session log (zstd-decompressed, single-pass seq index) with invalidation on session-file change, and SHALL NOT impose truncation on canonical content beyond the tool layer's own limits, surfacing an actionable truncation note instead.
+
+#### Scenario: Oversized original request
+- **WHEN** the model reads an original span exceeding the tool-layer response cap
+- **THEN** the system returns the truncated head (or the requested line window) with a note naming the `:raw`/line-window addressing for the remainder