DeepSeek Harness · 最早的 1000 个提交

新增 .gitignore、LICENSE、README.md、AGENTS.md，以及 CLAUDE.md（指向 AGENTS.md 的符号链接）。

建立仓库骨架与基本的 agent 协作约定入口。

AGENTS.md 追加 5 行，引入 MVP 需求分析与微内核架构设计文档的链接。

把早期设计思路纳入仓库说明，为后续开发对齐方向。

新增 package.json、.yarnrc.yml、yarn.lock、tsconfig.base/build/test.json、scripts/build.ts、vitest.config.ts。

确立 vendor/*（Cordis 源码）与 packages/*（dsh-* harness 包）两类 workspace；开发用 tsx + paths 直跑源码，构建用 tsc -b（声明）+ dumble（JS 包），测试用 vitest。

在 vendor/ 下扁平化放入 cordis 4.0.0-rc.6、plugin-loader、-include、-group、-timer、-hmr、-logger-console、cosmokit 1.8.1、schemastery 3.18.0；新增 vendor/README.md 作为清单（上游仓库 + SHA、本地改动日志、同步流程）。

把 Cordis 作为源码而非依赖 vendoring 进来，保留原 npm 名、private: true；本地裁掉 hmr 的 locale YAML 引用避免运行时 YAML 钩子。

新增 @deepseek-ai/dsh-llm（provider-neutral 内容块词汇表、StreamChunk 协议、ToolSchema、LlmAdapter、LlmService 注册表、BlockAssembler）、dsh-session（事件溯源 Session、SessionStore、session/flush 持久化缝）、dsh-system-prompt（有序 section + 工具 schema 提供者、assemble waterfall）、dsh-tools（工具注册表 + execute waterfall，沙箱/权限/钩子的单一缝）、dsh-agent（Agent 接口、AgentRegistry、agent/* 事件分类）。

定义产品 API 主干的抽象接口（capability seam），让具体实现和循环彼此解耦。

新增 dsh-agent-loop：LoopAgent（带 queued + steering FIFO 的 inbox、per-step AbortController）与流式优先的 session/turn/step 循环；扩展缝含 agent/request、agent/step-result、agent/turn-continuation waterfall；附 16 个脚本化 mock 测试。

给出唯一可替换的具体 agent 循环，验证整条主干能否端到端跑通（生命周期、工具往返、steering、inject、continuation 覆盖/否决、中止、回放等价、HMR 安全销毁）。

examples/echo-agent/ 下用 cordis.yml 串联 mock-echo LlmAdapter（流式文本 + "echo" 工具调用）、echo 工具、stdio 聊天 UI 插件、JSONL 持久化插件（演示 write-behind + session/flush checkpoint）。

用最小可运行 demo 端到端验证整套架构（loader、include、HMR 热重载全部活跃，通过 yarn demo 直接跑源码）。

新增 docs/architecture.md（分层、service map、事件分类、session/turn/step 生命周期、Cordis waterfall 语义、扩展 cookbook、MVP-到-扩展点对照表、延期 TODO）；重写 AGENTS.md（仓库布局、命令、约定、vendoring 政策）。

把已经成型的设计写下来，对齐 agent 与人类贡献者。

高优先级（loop 流水线）：agent/step-result 移到追加 assistant message 之前；中止在工具调用之间也生效；step 起点排空 steering、pending steering 可覆盖负向 continuation 决定、残余 steering 作为 queued 消息重入队；turn-continuation 与 session/flush 异常被圈在 turn 内（error 事件 + agent/error）。中低优先级：disposal 发 agent/status('disposed')、重复 LLM adapter 抛错、SessionEvent 变真 discriminated union、无模型 agent 报清晰错误、流严格按序 yield、BlockAssembler 在 block-end 冻结、turn 号从日志种子起算、stop disposer 不可抛等。附 21 个回归测试。

落实评审意见，把若干隐性不变量改对并固化测试。

为 packages/、examples/、examples/echo-agent/ 等每个目录补 README 与 AGENTS.md（+ CLAUDE.md 符号链接）；为每个 packages/*/src 文件加模块级注释、为导出 API 加更完整 JSDoc；根 AGENTS.md 新增 "Type Safety and Documentation" 政策。类型：从 tsconfig.base.json 移除 noImplicitAny: false，清掉所有 : any / as any（catch 用 unknown + CodedError 收窄）。新增 dsh-tools schema DSL：SchemaSpec + InferArgs<S> + 转 JSON Schema + defineTool()（首方工具零 cast 拿到类型化 execute）。

把仓库拉到"严格类型 + 充分文档"的基线，工具 schema 直接面向 JSON Schema 生成（弃用 schemastery）。

InferArgs 真正产出 optional 键（RequiredKeys + 映射 ?）；数组元素递归推断对象形状；工具执行对非 Error 抛出（如 throw { message }）能正确报 message；schema 字面量用 satisfies SchemaSpec；新增 tsconfig.typecheck.json 把"测试与示例也类型检查"纳入 yarn typecheck。+4 回归测试。

修掉类型层与运行层不一致的若干漏洞，新增 tests/examples 的类型门。

docs/architecture.md 的 cookbook 工具插件示例改用 defineTool + 类型化 args，并注明原始 JSON Schema 仍是 MCP 互操作路径；echo-agent README 的 mock-llm / echo-tool 行与代码对齐。

消除文档与代码漂移（前一提交的原始 JSON Schema + args: any 示例与紧邻的类型安全政策自相矛盾）。

tsconfig.base.json 叠加 noUncheckedIndexedAccess、exactOptionalPropertyTypes、noImplicitOverride、noFallthroughCasesInSwitch、noUnusedLocals、noUnusedParameters；vendor 包本地 opt-out 以便上游同步。相应修复：index 访问承认 undefined、optional 属性省略而非置 undefined、Session.onAppend 显式 (…) => void | undefined 等。

在不影响 vendor 同步友好度的前提下，把自有代码顶到最严类型档。

flat config 两层——正确性（no-floating-promises/no-misused-promises 是 agent loop 的主要 bug 类、switch-exhaustiveness、no-unnecessary-condition、require-await、no-explicit-any）；风格（@stylistic：2 空格、无分号、单引号、尾逗号、max-len 140）。vendor 排除、测试放松若干。代码相应调整（registry disposer 包同步 () => void、BlockAssembler 用 mustGet 代替非空断言、waterfall tail 返回 Promise.resolve 等），新增 yarn lint / lint:fix。

把既有 house style 从"agent 间漂移"变为机械强制。

vitest coverage（v8 provider）+ per-file 100% 阈值（statements/branches/functions/lines）；范围限定运行时源码（types-only 文件、vendor、examples 排除）。新增 59 个测试补齐所有缺口（llm generate-waterfall/adapter 销毁、assembler 边缘协议、整个 Inbox 含 wakeup-overwrite 竞态、LoopAgent disposed 态、config 驱动 agent 创建、loop backstop、system-prompt 动态 section、tools schema 矩阵等）；真正不可达的防御守卫带 /* v8 ignore */ 注释。

用机械覆盖率门把"测试覆盖"从口号变成 CI 门。

knip（workspace-aware，检未用文件/导出/依赖，vendor 排除，允许 default+named 双导出）；scripts/publint-all.ts 检每个 packages/* 的发布正确性；yarn.config.cjs 用 constraints 机械化 AGENTS.md 包规则（全部 private、dsh-* 包 cordis 同时作为 peer+dev、统一 0.0.1 版本、ESM）。yarn hygiene 一键跑。

把包规约从文档约束变成机械检查。

lefthook.yml 配置 pre-commit（staged 文件 ESLint --fix、增量 typecheck、vendor manifest 守卫——vendor/*/src 改动必须同 commit 改 vendor/README.md）与 pre-push（测试 + hygiene）；hooks 复用 package.json 脚本（单一真实源）；postinstall 自动安装。

把本地修改日志纪律和提交前质量检查机械强制到每个提交。

.github/workflows/ci.yml（push/PR 触发）：不可变安装、constraints、lint、typecheck（src + tests + examples）、带 per-file 100% 覆盖门的测试、knip + publint、完整 build、echo-agent demo 烟测（脚本化 stdin，断言工具调用往返与 JSONL 会话 dump）。

把本地脚本和 git hooks 跑的同一组命令纳入 CI 矩阵。

用 unique-symbol brand 实现零运行时成本的 nominal string 类型（packages/llm/src/brand.ts）；CallId 在 dsh-llm（跨 block/chunk/session 事件/执行结果关联工具调用）、SessionId 在 dsh-session、AgentId 在 dsh-agent；对外 string-in API（sessions.create、agentLoop.create）仍接 plain string 并内部 brand。

阻止跨包 ID 误传（AgentId 不能塞进要 CallId 的位置），但只 brand 跨包 ID 而非每个 string。

dsh-llm 新增 assertNever（packages/llm/src/never.ts），用于 CLOSED union 的不可达 default——新增 StreamChunk 变体会在 BlockAssembler.push 处编译失败；模块文档 + AGENTS.md 约定明确：merge-extensible union（SessionEventMap、ContentBlockMap 等）禁止用 assertNever，应处理已知 case 后 fall through 并注释。

在不误伤插件可扩展 union 的前提下，让闭合 union 的穷尽性由编译器守护。

docs/adr/ 下 7 条 ADR：vendoring Cordis（含 manifest 守卫）、微内核事件分类（单一可替换 loop）、事件溯源 session（派生历史 + append-before-emit）、自有 content-block 词汇表（为何不用 OpenAI/Anthropic 形状）、自定义 schema DSL（弃 schemastery）、工具 schema 进 prompt 装配、机械质量门（agent 写代码的理由）。

把已做决策的"为什么"固化下来。

docs/rfc/ 下 8 条提案（property-based testing、mutation testing、确定性测试 + 通用回放不变量 fixture + 夜间竞态压测、architectural conformance（dependency-cruiser + LlmAdapter conformance kit）、模型边界运行时参数校验 + 结构化错误分类、doc-sync（类型化代码片段、API 报告）、供应链检查 + 夜间 vendor-drift 验证、deep-readonly 公共面）；AGENTS.md 指向 docs/adr 与 docs/rfc。

把尚未落地的质量改进思路写成可评审提案。

删除 scripts/build.ts（dumble 编排），新增 tsdown.config.ts（workspace globs ['vendor/*', 'packages/*']，显式排除 examples），两个 per-package override 在 vendor/（schemastery 双 .mjs/.cjs、logger-console node+browser）；yarn build = tsc -b && tsdown（tsc 仍管声明，dts: false、clean: false）；输出与 dumble 快照 diff 完全一致（17 JS bundle、externals、双入口保持）。新增 ADR 0008。

消除 dumble（0.2.x、~530 dl/wk、单维护者）的 bus-factor 风险，换到 rolldown-based、~2.5M dl/wk、活跃维护的 tsdown。

CI 在 Lint 阶段爆 1519 个 no-unsafe-* 错误（本地因 lib/ 残留看不出来）。修复：把 Lint 移到 Typecheck 之后（type-aware ESLint 经 tsconfig.typecheck.json 解析 vendor 的 built 声明，需 Typecheck 先 emit）；把源码级 paths 从根 tsconfig.json（dev-only、不被 package build 继承）移进 tsconfig.base.json，使整张 build 图源码优先解析（tsconfig.typecheck.json 仍整体覆盖为 lib 解析）；Hygiene 的 publint 移到 Build 之后；checkout/setup-node v4 → v6；AGENTS.md 记录"fresh clone 需先 yarn typecheck 再 yarn lint"。

让 CI 在干净 checkout 上也能通过。

vitest.config.ts 加 15 行注释解释：Vite >=8 警告该插件可用原生实验性 resolve.tsconfigPaths 替代，但本仓库不行——原生选项按每个导入文件最近的 tsconfig.json 的 paths 解析，而我们的 paths 只在根 tsconfig，packages/* 和 vendor/* 的 workspace tsconfig 没有 paths，原生解析会 fall through 到 package.json exports（lib/，未 build 前不存在），所有未构建的测试导入都会失败（在 vite 8.0.16 / vitest 4.1.8 上验证）。

把"为什么保留这个插件"的依据留在代码里，避免被未来的升级误删。

vitest.config.ts 新增 15 行注释/配置说明

文档化为什么 vite-tsconfig-paths 插件不能用 vite 原生 resolve.tsconfigPaths 替换，避免后续误删

.gitignore 新增 2 条忽略规则

补充仓库需要忽略的产物/文件

合并 codex/update-gitignore 分支，内容同上一条 gitignore 更新

将 gitignore 更新通过 PR 流程合入主线

按 capability-seam 模式新增三包——dsh-bash（抽象 BashExecutor 服务 + 词汇类型）、dsh-bash-local（本地子进程实现：bash -c + 进程组 SIGTERM→SIGKILL、截断+溢出文件、后台任务注册表）、dsh-tool-bash（bash/bash_output/bash_kill 工具 schema + 运行时参数校验 + 通过 agent.inject() 发后台完成通知；非零退出上报而非报错）；同时更新 docs/architecture.md、tsconfig、AGENTS.md、publint 脚本

交付首个完整的 bash 执行 capability seam（接口/实现/消费者三件套），参考 Claude Code、OpenCode、Codex、pi 的 bash 工具设计

新增首批真正的 LlmAdapter 实现——dsh-llm-deepseek（手写 fetch + SSE 解析 + chunk 翻译状态机，处理 thinking 模式、空串 reasoning_content 首块、usage 归并、reasoning_content 回传、cache token 计数）和 dsh-llm-pi-ai（经 @earendil-works/pi-ai 走同一端点）；agent-loop 现在识别流末尾的 finish {error|aborted} 并转为 step error；新增 yarn test:e2e（带 key 门控、自跳过）跑 V4 Flash/Pro 全档位矩阵；更新 architecture.md 与 StreamChunk 文档

用一对"同模型同协议、不同实现"的适配器交叉验证 StreamChunk 协议，并把 in-band error 路径落到实处

新增首个真实 agent 接线示例 examples/coding-agent（cordis.yml 组合 llm-deepseek + bash-local/tool-bash，bash 专用系统提示，max-steps 守护插件，stdio UI 带暗色 reasoning、pipe stdin 退出），swebench 风格 e2e（coding-task.e2e.ts 让测试自己重跑 add.test.js 验证而非信任 agent），以及三篇 cookbook（adding-a-package / adding-a-tool / adding-an-llm-adapter）；修正文档中 !js 应为 !!js

交付首个可运行端到端 demo，并把"加包/加工具/加适配器"的校验清单沉淀为文档

对所有非 vendor 的 Markdown（加 vendor/AGENTS.md）做 reflow，每段散文压成单行；保留代码块、表格、列表结构

消除段中硬换行，让一处改词不再触发整段 reflow 和 diff 噪音；约定写入 AGENTS.md

修正 AGENTS.md Commands（typecheck/build 描述、补全 lint/test:coverage/knip/publint/hygiene）；用 demo:echo + demo:coding 取代裸 yarn demo；新增 cookbook adding-a-vendored-package.md；architecture.md 加目录、抽出 extension-cookbook；新增 ADR 0009（capability seams）+ 0010（双 LLM 适配器）；提交 dsh-code-review skill 并通过 .claude/skills 符号链接暴露给 Claude Code

补齐命令文档、补齐 vendor 包添加流程、固化两条架构决策、引入代码评审 skill

defineTool 在 execute 前对 SchemaSpec 跑 validateArgs，畸形调用返回可自纠的 isError 而非穿透到类型体；校验语义与 schemaSpecToJsonSchema 完全一致（required 仅来自 required:true、允许额外键、不应用 default 等）；tool-bash 去掉手写类型/required 检查，只保留 DSL 表达不了的值约束；RFC 005 pt 1 升格为 ADR 0011

在工具执行边界挡住模型畸形调用，避免"名义有类型、实际无类型"

enum 成员检查对所有 SchemaTypes 统一生效（原先只查 string）；checkValue switch 以 assertNever 收尾；同步 cookbook；弱化 ADR 0011 关于属性测试的措辞

修正首轮评审发现的 enum 漏检和闭联合收尾问题

新增 dsh-invariants 插件（纯监听器，prod 关闭），在运行时断言事件分类——seq 单调、turn/step 嵌套、tool/result 必须有前置 tool/call（反向不要求）、合法 agent/status 转移；并对已记录事件数据做 deepFreeze；session/created 时检查并冻结 seeded 会话；真正常态修复是 deriveMessages 改为 structured-clone，使 loop/adapter 的 sanctioned 变更无法回写 append-only log；新增 ADR 0012（dev invariants 优于 DeepReadonly）；两个 demo 都接入

在开发期以运行时断言守住事件契约和日志不可变，常态路径用 clone 彻底切断回写

HMR 状态正确性——inject 会话、按重放已有 session log 重建每会话 trace，reload 不再误报；收紧嵌套（turn/end 拒绝未闭合 step、chunk/message/tool 事件必须命名当前 turn+step、pendingCalls 在 step/end 清空避免跨步污染）；去掉默认导出（会丢 inject 元数据，改用具名导出对齐 tool-bash）；文档化 deepFreeze 自顶向下前提

修正 HMR 重载误报、收紧嵌套规则、修复导出形式

引入 fast-check，为 llm/BlockAssembler、session、tools/schema DSL、agent-loop 调度各加 properties.spec.ts；tools 套件覆盖 RFC 001↔005 组合属性（满足 spec 的生成参数必过 validateArgs），堵住 ADR 0011 提到的 validator/InferArgs 漂移；loop 属性确定性（不依赖 sleep）；首次运行即发现 BlockAssembler 真实 bug（同 index 重复 block-end 覆盖已 flush 的块），修复并加回归；RFC 001 升格为 ADR 0013

用基于属性的测试覆盖协议形状代码，并顺手暴露 assembler 的重复块 bug

llm 生成器补发 finish 块（原先 finish-defaults 属性恒绿）并加流式/一次性装配一致性属性；agent-loop 断言同步突发只合成一个 turn、加 mixed-schedule 属性、recordStatus 返回 disposer、每 run 独立超时；session 随机化 noise/message 交错；tools 生成数值参数排除非有限 double

补齐评审指出的属性覆盖空洞，让属性测试真正有意义

新增两个 tsx CI 门禁——doc-typecheck（抽取 README/docs/package README 的 fenced ts 块，用 tsc --noEmit 编译，允许 ts ignore-check 退出并设上限）和 verify-event-taxonomy（断言 architecture.md 分类表的事件名与 interface Events 块完全一致；这次顺手补了三个漏表事件 tools/change、llm/adapter-change、system-prompt/change）；为代码片段补 stub 声明使其可编译；接入 CI；RFC 006 pts 1-2 升格 ADR 0014

让文档与代码漂移在 CI 早期失败

verify-event-taxonomy.ts 在 interface-Events 大括号遍历前先剥注释，避免 Events 块内 {@link} 或 // { 行打乱深度计数

消除评审指出的潜在计数失衡风险（事件名只在代码不在注释，剥注释无损）

在叶包 dsh-llm 引入 HarnessError——稳定可机器路由的 code、cause 链、子类名即 name、isHarnessError；LlmError/ToolArgsError/InvariantError 均改为其子类；ToolExecutionResult 增 error: {name, code}（由抛出的 HarnessError 填充），loop 将其转发到 tool/result 事件（同字段可选），toError 把非 Error 抛出包成 HarnessError(code: UNKNOWN, cause)；RFC 005 pt 2 升格 ADR 0015，RFC 005 至此全部落地

用统一的结构化错误基类让工具失败信息端到端可路由，替换先前 PR 的裸 Error+code

deepFreeze 去掉 Object.isFrozen 提前返回，始终向下递归并用 WeakSet 记录已访问对象以做循环终止与幂等

修正 PR 评审发现——调用方传入浅冻结对象时旧逻辑会跳过整棵树，留下可变子孙，违背 ADR 0012 的历史不可变承诺

新增共享 doc-sync package.json 脚本（doc-typecheck + verify-event-taxonomy）接入 lefthook pre-push，CI 步骤也指向同一脚本

原先 doc-sync 仅在 CI，本地推完才发现；统一脚本一处真相、本地提前拦截（对齐 ADR 0007）

注册表的 unknown-tool 分支原先只返回 isError 文本、无 {name, code}；现引入 ToolNotFoundError（HarnessError，code UNKNOWN_TOOL）并把 unknown-tool 走与工具抛错相同的 catch 路径，两类失败都从同一出口暴露结构化元数据

堵上本 PR 引入的分类法缺口，让 unknown tool 也产出可路由错误

把 dev-invariants（含 a45bc8da67 的 deepFreeze 修复）合进 property-tests 分支

在 property-tests 分支上叠加 dev-invariants 的最新结果，为后续链式合并做准备

把 property-tests（含上一步并入的 dev-invariants）合进 doc-sync 分支

继续把 RFC 链向 doc-sync 分支汇聚

把 doc-sync 分支（已含前面两条 RFC 的累积改动）合进 error-taxonomy 分支；CI、lefthook、ADR 0014、invariants 包一起带入

将四条 RFC 分支汇总到 error-taxonomy 分支，准备统一出 PR

新增 docs/development.md（97 行），README.md 加入对应入口

补齐"如何从零搭起本地开发环境"的文档

docs/development.md 增补 19 行，澄清 CI 与本地 hook 各自跑哪些门禁

让贡献者明确本地 hook 与 CI 的分工边界

README.md，删除 3 行冗余指引文字。

压缩 README 中的指导内容，为后续按受众拆分做准备。

README.md，将指引按读者类型分条。

让不同受众（用户/贡献者）各取所需，提升可读性。

docs/development.md，补充分层（stacked）gate 的描述。

让开发文档与实际 CI/lefthook 中分层执行的 gate 保持一致。

docs/development.md，修正 Node 版本 CI 矩阵表述。

准确说明 CI 测试覆盖的 Node 版本范围。

合并 feat/rfc005-arg-validation 分支。新增 ADR 0011；在 packages/tools/src/schema.ts 中实现工具参数运行时校验（+119 行），packages/tools/src/index.ts 暴露校验入口；tool-bash 适配；补全 tools/tool-bash 测试；更新 cookbook 与 RFC 005 状态。

落实 RFC 005 第一阶段，在工具调用入口对模型传入的参数做 schema 校验。

合并 feat/rfc001-property-tests 分支。新增 packages/invariants（240 行实现 + 331 行测试 + README/package.json/tsconfig），引入 fast-check（yarn.lock + package.json）；为 agent-loop/llm/session/tools 各加 properties.spec.ts；新增 ADR 0012、0013；更新多份 tsconfig 与 example cordis.yml。

为协议形状（protocol-shaped）代码引入 property-based 测试与不可变性/invariant 检查基础设施。

合并 feat/rfc006-doc-sync 分支。新增 scripts/doc-typecheck.ts（校验 markdown 中可编译 ts 代码块，151 行）和 scripts/verify-event-taxonomy.ts（校验事件分类表，114 行）；接入 CI（.github/workflows/ci.yml）、lefthook 与 package.json scripts；新增 ADR 0014；更新多份 README/architecture/cookbook。

建立文档同步门禁，防止文档中的代码示例和事件分类表与实现脱节。

合并 feat/rfc005-error-taxonomy 分支。新增 packages/llm/src/error.ts（HarnessError 基类，33 行）；packages/tools 重构错误抛出（schema.ts/index.ts）；agent-loop/src/loop.ts 调整错误处理；invariants 适配；补全各包测试；新增 ADR 0015。

统一全 harness 的错误模型，用结构化 HarnessError 取代裸 Error，配合运行时校验产出可分类错误。

合并 codex/dev-guide 分支。新增 docs/development.md（118 行开发环境搭建说明），更新 README.md 指向。

补齐新贡献者上手所需的本地环境与工具链说明。

新增三份 RFC：009 抽象 append-only 的 SessionPersistence 服务（基于现有 SessionEvent log，JSONL 实现，SessionMeta 头，异步 resume 路径）；010 ACP（Agent Client Protocol）支持作为 dsh-acp 客户端驱动插件；011 在单连接上多路复用并发 ACP 会话；更新 docs/rfc/README.md。

为会话可恢复性与 ACP 接入做设计铺垫，依赖顺序 009→010→011。

修改 009/010/011 三份 RFC。009：dsh-session 拥有 SessionMeta（持久化层 re-export）以避免包循环；将可变摘要拆到 sidecar 以保持事件 log append-only；确定 load-repair 规则。010：去掉"零运行时依赖"说法（SDK 有 zod peer）；session/new 需要 create seam；dsh-agent 提供抽象 create/resume 工厂；明确 TurnEndReason→ACP StopReason 映射；MVP 拒绝非空 additionalDirectories。011：用真实 per-session disposer scope 取代 ctx.extend()。

根据 PR #18 评审意见修正设计，使其与代码库、@agentclientprotocol/sdk@0.25.1 和 Cordis 语义自洽。

009 将"crash-tail overwrite"重新定义为一次性 truncation-repair（ftruncate+fsync 到上一个完整 turn/end 字节偏移），只删除从未提交的崩溃尾部，明确不重写已提交事件；010 移除剩余的 concrete-loop 引用，session/new 与 session/load 改指向 dsh-agent 工厂，Risks 中的 disposal 用接口级 settle 信号（agent/status）替代 LoopAgent 专属的 agent.done。

消除 append-only 契约与崩溃恢复措辞间的矛盾，去除对具体 loop 实现的耦合。

合并 feat/rfc009-011-acp-and-persistence 分支，落地上述三份 RFC（含前两次修订）。

正式采纳 009/010/011 设计。

AGENTS.md：Repository Layout 加入 invariants/，Commands 加入 doc-typecheck/verify-event-taxonomy/doc-sync，重写"CI 无 doc-sync gate"的错误表述为 gate 实际覆盖范围；packages/AGENTS.md 修正同一过时表述；packages/README.md 在依赖图与包表中加入 dsh-invariants。

doc-sync gate 与 dsh-invariants 已落地但指令文档未跟上，且 gate 的 markdown 范围不覆盖 AGENTS.md 导致静默漂移；此次同步纠正。

.agents/skills/dsh-code-review/SKILL.md，将"doc-sync 规则没有 gate"改为准确表述（gate 确实校验可编译 ts 块和事件分类表，只有 prose 漂移未被 gate 覆盖）。

code-review 发现 P1-16 同类过时表述存在于第三处文件，一并修正；ADR 0014 已确认正确无需改动。

packages/agent-loop/src/loop.ts，交换两行顺序使 session.append('step/start') 先于 emit；同步修正 runLoop JSDoc 伪代码和 docs/architecture.md 中同样的顺序错误；新增回归测试。

所有 loop 边界都遵循 ADR 0003 的 append-before-emit 规则，唯独 step/start 反了，导致 agent/step-start 监听器看不到刚被告知开始的 step。

packages/agent-loop/src/loop.ts（+212/-71）重构 runTurn 为基于幂等 finalizer 的结构：closeStep()/closeTurn() 受 stepOpen/turnEnded 守卫至多执行一次；failTurn() 用 errorReported 守卫保证错误事件和 agent/error 只发一次；catch 中先关 step 再关 turn（invariants 拒绝 step 开着时的 turn/end），仅 pre-turn 抛出时 rethrow；disposal precedence 规则改为 reason 在 disposed 且无错误时报 disposed。新增 review-fixes.spec.ts（248 行，6 个场景，以 dsh-invariants 作 balance oracle）；agent-loop 增加 dsh-invariants devDependency（仅测试用）。

turn/start 之后任何 throw 都无法保证 turn/end，留下不平衡 turn，破坏 replay/telemetry/invariants 的基本假设；此次补全所有错误路径下的 turn/step 闭合。

packages/agent-loop/src/loop.ts，将 tool/result 的 callId 从 result.callId（tools/execute waterfall listener 返回值）改为 call.id（loop 的权威 id）；新增测试验证监听器返回错误 callId 时仍记录正确 id，且 deriveMessages() 产出的 tool-result block 的 toolCallId 配对正确。

callId 是模型转写关联 id，deriveMessages() 用它生成 tool-result block 的 toolCallId 必须与 assistant tool-call block 配对；错配会在下一次模型请求中孤立该配对。

packages/llm/src/index.ts、packages/agent/src/index.ts、packages/session/src/index.ts、packages/system-prompt/src/index.ts、packages/tools/src/index.ts，将 registerAdapter/register/create/section/tools/register 六个方法改为 generator-effect 模式（mutate → yield disposer → emit change），与 AgentLoop.create 已验证模式一致；为每个方法新增 listener-throw 回滚测试。

Cordis 中 effect 返回 disposer 前同步抛错会让 fiber 无可收集对象，导致注册项永久泄漏（HMR/dispose 无法清理，duplicate-name 检查卡死直到重启）；generator-effect 保证后续步骤抛错时已 mutate 的状态能被回滚。

新增 docs/rfc/012-optional-code-mode.md（84 行）与 README 条目。提出可选 Code Mode：模型编写 TypeScript 程序调用生成出的 SDK（包装所有注册工具），而非每步发一个原生 tool-call；按 Cordis capability-seam 三件套实现（code-runtime 接口 / node:vm 参考桩 / code-mode consumer 插件），零核心包改动；硬化的执行底座延后到后续 RFC。

为工具组合与减少往返提供新的执行模型设计。

docs/rfc/012-optional-code-mode.md。并发：改为强制 serialize-by-default（SDK binding 中 per-run dispatch queue，非重叠为硬性验收标准）；node:vm guard：改为可执行的（CodeRuntime 暴露 safe:boolean，VM stub 除非 { unsafe:true } 构造否则抛错，code-mode 在不安全 runtime 上拒绝注册 run_code 除非 allowUnsafeRuntime，测试覆盖拒绝路径）；prompt 预算：撤回"零 prompt token"说法（SDK .d.ts 注入 system prompt 会消耗上下文），补充 budget/caching tradeoff（Code Mode 节省的是输出/往返而非输入侧工具描述）。

根据 PR 评审把模糊建议变成可执行、可测试的硬约束。

docs/rfc/012-optional-code-mode.md。新增 Alternatives 段：对比更窄的原生 tool-calling 上的 result-elision/summarization（解决 context-bloat 但不解决组合/往返）和 parallel native dispatch（核心 loop 改动仍缺组合），说明为何选 Code Mode 及其代价；修正 Problem 段表述，把"模型可并发运行独立调用"改为"表达 fan-out，在有并发安全元数据前先序列化"。

消除与 serialize-by-default 决策的矛盾，讲清早期收益是组合 + 更少往返而非并行。

合并 worktree-rfc-012-code-mode 分支，落地 RFC 012（含两轮评审修订，共 102 行）。

正式采纳 Code Mode 设计提案。

docs/rfc/012-optional-code-mode.md，补充 CodeRuntime seam 可承载按语言/运行时不同的后端（如天然沙箱化的 AssemblyScript/WASM 后端、基于 CPython 或可嵌入解释器的 Python 后端）；执行契约语言无关，但 SDK codegen/prompt 呈现按语言定制；将这些后端列入延后 follow-up。

澄清 seam 不限于按信任级别区分后端。

合并 worktree-docs+rfc012-multi-backend 分支，落地上一条 RFC 012 多后端说明。

正式并入多语言 Code Mode 后端的补充说明。

packages/agent-loop/src/loop.ts 的 closeStep() 原先 catch 后静默吞掉 agent/step-end 监听器抛出的异常，导致 runTurn 仍以 completed 收尾，session 记录一个零错误事件的"成功"轮次；改为调用 failTurn(toError(error)) 追加单一错误事件并将 reason 置为 error。新增 review-fixes.spec.ts 回归测试。

兑现"抛错的插件必须被收敛为 turn 错误而非静默成功"的契约。

packages/session 新增 SessionHeader/SessionSummary/SessionMeta/CreateSessionOptions，Session 暴露 readonly header，SessionStore.create 接受 { seed, meta } 并校验 cwd/父会话血缘；新增 json.ts 的 isJsonValue（拒绝 BigInt/函数/symbol/undefined/非有限数/稀疏数组/循环引用/exotic 对象）；Session.append 与构造器对 seed 事件做可序列化与 seq 连续性校验。迁移约 3 处内部 create(id, seed) 调用点，调整 invariants 测试。

在源头保证日志可被任意持久化后端无丢失地序列化，为后续 durable backend 打底。

要求所有 session 事件必须落在某个 turn/start…turn/end 之间；循环在 turn/start 之后入队 user/message 事件，idle agent.inject() 用一次性 injection turn 包裹上下文/消息；turn 关闭后的失败（session/flush 拒绝、agent/turn-end 监听器抛错）只能经 agent/error + logger 上报。dsh-invariants 通过 default 分支强制该不变量；新增 ADR 0017 与 architecture.md 更新；agent/loop 大量测试。

把 turn 作为唯一的 durability/replay 边界，使持久化后端可安全截断最后的 crash tail。

新增 dsh-session-persistence（抽象 SessionPersistence 服务，ctx.sessionPersistence，定义 create/append/load/list/has/delete/update，复用现有 SessionEvent）和 dsh-session-persistence-jsonl（每会话 append-only JSONL 日志、原子写、未提交 tail 截断修复、replay 路径，SessionMeta 走 session.header）；提供共享 runPersistenceContract 套件。examples 移除手写 session-jsonl.ts 改由 cordis.yml 加载 JSONL 后端；config-driven create 改用 ${id}-session-<uuid> 避免命名冲突。ADR 0016。

建立可插拔持久化能力 seam，并给出第一份实现以验证抽象。

packages/agent 新增 AgentRegistry（ctx.agents：setFactory/create/resume）与 AgentFactory/CreateAgentOptions/ResumeAgentOptions；AgentLoop 实现该接口并自注册。create 接受调用方提供的 sessionId，resume 经 ctx.sessionPersistence 载入后恢复（turn 编号与历史延续），sessionPersistence 不做硬注入（无后端 demo 仍可跑），缺失时 resume 以带类型错误拒绝；assertAgentIdFree 在建会话前后各跑一次防孤儿会话。新增 resume.spec.ts。

让插件经接口而非具体 loop 包创建/恢复 agent。

新增 dsh-session-persistence-sqlite（基于 node:sqlite），每条 SessionEvent 1:1 映射到 events 行（session_id/seq/type/time/data），append 为事务内 INSERT 且断言连续 seq；可变 SessionSummary 落在 sessions 元数据行。满足与 JSONL 相同的契约语义（延迟物化、crash-tail 裁剪、事务回滚），并跑共享 runPersistenceContract + SQLite 专属测试。文档将所有"SQLite 待办"改为"已实现"。

用第二份实现证明抽象 seam 与共享契约确实后端无关。

合并 docs/sync-doc-sync-gate-and-invariants 分支，同步 .agents/skills/dsh-code-review/SKILL.md、AGENTS.md、packages/AGENTS.md、packages/README.md。

让 doc-sync gate 与 dsh-invariants 相关的高权威文档与代码对齐。

合并 fix/agent-loop-step-start-order，loop.ts 调整为先 append step/start 再 emit agent/step-start，并在 review-fixes.spec.ts 增测；architecture.md 同步。

保证监听器触发时 step/start 已落日志，避免监听器看到无对应事件的 step-start。

合并 fix/agent-loop-turn-step-balance，loop.ts（约 215 行变更）重写错误路径，确保任何已开启的 turn 与未关 step 在出错时都被关闭；review-fixes.spec.ts 新增 288 行回归。

任何错误路径下边界事件都必须配对，符合 turn-enclosure 不变量。

合并 fix/agent-loop-tool-result-callid，loop.ts 让 tool/result 以发起调用的 call.id 写入日志；review-fixes.spec.ts 加测。

保证 tool 调用与结果在日志中的调用 id 对齐，便于重放与关联。

合并 fix/registration-atomicity，对 agent/llm/session/system-prompt/tools 五个包（六个注册方法）调整注册逻辑使其原子化，并各自补测。

注册失败时不会留下半注册状态，保证注册副作用可回滚。

把 origin/master 合入 split/session-meta，带来 docs/rfc/012-optional-code-mode.md、loop.ts 的 9 行修正与对应 review-fixes 测试。

把 master 的最新进展并入 session-meta 分支以便继续栈式开发。

把 split/session-meta 合入 split/turn-enclosure（解决 review-fixes.spec.ts 冲突），内容同 611791ba7f。

栈式 PR 的 merge-forward，保持下游分支基于最新基。

把 split/turn-enclosure 合入 split/session-persistence，内容同前。

沿 PR 栈继续 merge-forward。

把 split/session-persistence 合入 split/agent-factory，内容同前。

栈式 merge-forward。

把 split/agent-factory 合入 split/session-persistence-sqlite，内容同前。

栈顶分支对齐，准备最终合入。

src/index.ts 让 append() 在入链等待前同步做可序列化校验并 structuredClone 整批，避免调用方事后修改持久化副本/游标；load() 仅用 seq+type 列计算 cutAtLastTurnEnd，只对已提交前缀解析 data，crash tail 中的坏 data 丢弃而非整体不可加载。新增两类回归测试。

与 JSONL 后端行为对齐，修复 review 中发现的两处一致性缺口。

packages/session/src/index.ts 构造器在校验后深拷贝每个 seed 事件（原先只复制数组、对象仍共享），append() 存储 structuredClone(data) 并让返回事件携带同一快照；json.ts 补充 isJsonValue 范围说明；README 同步 create() 签名与 meta.createdAt。新增事后修改 seed/append 对象的回归测试。

把可序列化不变量从"预检"升级为真正的不变量，避免事后修改污染日志。

把 split/session-meta（含 #31 修复）合入 split/turn-enclosure。

将 review #31 的修复 merge-forward 到下游分支。

loop.ts 的 outer catch 不再依赖 turnStarted 标志（turn/start 监听器抛错会让标志为 false 而漏写 turn/end），改为从日志读取本 turn 的 turn/start 是否存在；agent.ts inject() 的 idle 一次性 turn flush 同样改为从日志判定；throwing turn/end 监听器与 idle flush 失败统一经 agent/error + logger 上报。重写编码旧错误的测试并补回归。

消除"监听器抛错 → 永久开 turn / 丢失持久化检查点"的竞态，兑现 ADR 0017。

把 split/turn-enclosure（含 #32 修复）合入 split/session-persistence。

栈式 merge-forward。

新增 isENOENT() 助手；listCwdDirs() 与 exists() 仅对 ENOENT 返回空/缺失，其他错误（EACCES/ENOTDIR/瞬时 IO）重新抛出；writeSidecar() 改用排他 owner-only 临时文件（'wx', 0o600），避免可预测路径被跟随；共享 runPersistenceContract 的可序列化用例覆盖 isJsonValue 拒绝的全部值，MemoryPersistence 改用规范 isJsonValue 校验。

持久化后端绝不能把存储故障误判为"无会话"。

把 split/session-persistence（含 #33 修复）合入 split/agent-factory。

栈式 merge-forward。

packages/agent/README.md 的 inject() 行由"不触发 turn"还原为 idle 注入包裹一次性 injection turn 的表述（对齐 ADR 0017 与 JSDoc）；packages/agent-loop/src/index.ts 的 resume() JSDoc 由"throws a typed error"软化为"rejects with a clear error"（代码本就抛普通 Error）。

纯文档/注释同步，使措辞与当前代码行为一致。

把 split/agent-factory（含 #34 文档修订）合入 split/session-persistence-sqlite，是栈顶最后一次 merge-forward。

使栈顶分支包含整条栈的全部修复，准备整体合入主线。

packages/session-persistence-sqlite 的 index.ts/schema.ts 与测试。load() 不再删除崩溃尾事件，改为记录 repairFrom，下一次 append 在自身事务里执行 DELETE；all-tail 场景把元数据行的 materialized 置 0；openDatabase 在新建库时把 SCHEMA_VERSION 写入 PRAGMA user_version，并拒绝打开比本构建更新的 schema。

让 SQLite backend 与 JSONL 共享同一"load 非变异"契约，使 has()/list() 在崩溃后立即一致，并防止旧构建误开未来不兼容布局。

packages/agent-loop/src/loop.ts 与 tests/review-fixes.spec.ts。failTurn() 先设 reason 再 append error 事件并对监听器抛错容错；closeStep()/closeTurn() 对 step/end、turn/end 的 append 与 emit 都包了 try/catch。

防止会话/事件监听器在 finalizer 路径上抛错时把 turn 卡在打开状态或漏发 turn/end，保持 turn 平衡、loop 存活。

合并提交，把 split/turn-enclosure（含 #32 finalizer 容错修复）并入 split/session-persistence。

在 session-persistence 分支上带入 turn-enclosure 的 agent-loop 修复。

docs/adr/0016-session-persistence.md 一行文案。

resume seam 故意抛普通 Error，ADR 措辞与 JSDoc/#34 评审对齐；纯文档无行为变化。

合并提交，带入 #32 finalizer 修复与 ADR 文案；冲突在 docs/adr/0016-session-persistence.md。

把 session-persistence 的修复同步到 agent-factory 分支。

packages/session-persistence-jsonl/src/index.ts。重构 materialize()：先标记 link() 是否成功，失败时只删 temp 再抛；成功后 fsync 目录、置 materialized、再 best-effort 删冗余 temp 链接。

避免 temp 硬链接删除失败导致 state.materialized 保持 false，使后续每次重试都撞 "already exists" 把会话卡死。

合并提交，带入 #33 JSONL 修复。

把 JSONL materialize 修复同步到 agent-factory 分支。

合并提交，带入 #32、#33 修复与 ADR 文案。

在 sqlite 分支上汇集 agent-factory 的累积修复。

packages/agent-loop（loop.ts/README/tests/mock-adapter）、packages/session（types.ts/tests）、AGENTS.md、docs/architecture.md。在 TurnEndReasonMap 加 max-tokens 变体，把模型 finish reason 从 runStep 透传到 runTurn（turn 内任一 step 命中即标记，disposed/aborted/error 仍优先）。

让消费者区分干净停止与被截断的 turn，为 RFC 010 ACP bridge 映射到 max_tokens stop reason 提供契约。

全仓库切换包管理器——根 package.json、新增 pnpm-workspace.yaml/pnpm-lock.yaml、删除 yarn.lock/yarn.config.cjs/.yarnrc.yml，更新 CI/lefthook/各包 package.json 与众多 docs，新增 scripts/check-workspace-constraints.ts。

生态对齐、用严格 linker 消除幽灵依赖、引入 build 脚本 allowlist 与包管理器无关的约束脚本。

新增 docs/adr/0016-pnpm-over-yarn.md 并登记到 docs/adr/README.md。

记录 Yarn 4 → pnpm 的动机（生态、严格 linker、allowlist、约束脚本）、迁移时基准与 gate 套件无变化。

pnpm-workspace.yaml 的 allowBuilds。把 @google/genai 和 protobufjs（dsh-llm-pi-ai 的传递依赖）从 true 改为 false 并加注释。

这些包是 prebuilt 消费的，其 lifecycle 脚本是 no-op，禁用以避免不必要的安装时代码执行。

pnpm-workspace.yaml，精简各条目的注释。

文档清晰，无行为变化。

合并提交，把 pnpm 迁移整批（含 ADR 0016、allowBuilds、约束脚本）并入 master。

在主干上落地 pnpm 迁移。

合并提交，把 master（含已落地的 pnpm 迁移）拉进 split/session-meta 分支。

让 session-meta 分支与 master 的包管理器变更同步。

packages/session/src/json.ts 一处引用。

master 的 pnpm 迁移占了 ADR 0016，与本栈的 session-persistence ADR 编号冲突，故把后者重编号为 0018（turn-enclosure 保持 0017）。

合并提交，带入 master 同步与 ADR 重编号；冲突在 docs/adr/README.md。

把 session-meta 的同步结果并入 turn-enclosure 分支。

合并提交；冲突在 docs/adr/README.md、packages/agent-loop/package.json、yarn.lock。同时把 0016-session-persistence.md 重命名为 0018-session-persistence.md。

在 session-persistence 分支汇集 turn-enclosure 与 master 的 pnpm 同步。

合并提交；冲突在 docs/adr/README.md、packages/agent-loop/package.json、yarn.lock。

把累积的 session-persistence 变更（含 pnpm 迁移、ADR 重编号）带入 agent-factory 分支。

合并提交；冲突在 yarn.lock。

把 agent-factory 的全部变更同步到 sqlite 分支，完成 pnpm 迁移在整条栈上的对齐。

新增 packages/acp（AgentSideConnection 接线、initialize/newSession/loadSession/prompt/cancel、TurnEndReason→StopReason codec、settle-once 回退链、单 session 守卫、cwd 校验、session/load 从事件日志重放）；packages/agent 加 whenIdle() 静默信号（LoopAgent 实现）；抽出 examples/base.yml，新增 examples/acp-agent；48 个 bridge 测试，100% 单文件覆盖，含子进程 e2e。

实现 RFC 010 MVP，让 Zed 等 ACP 编辑器可流式渲染、显示 tool-call、通过 session/load 恢复会话地驱动 coding agent。

packages/acp/src/index.ts 用 Map<sessionId, SessionRecord> + agent→sessionId 反向 WeakMap，让 agent/* 事件 O(1) 路由到所属 session，并发 session 互不串扰；session/cancel/load 按 id 隔离，销毁时并行 drain 到静默。packages/tool-bash 在 spawn 时记录后台任务所属 agent 并保留终身，bash_output/bash_kill 拒绝跨 agent 访问；新增多 session 与跨 agent 测试。

解除 RFC 010 单 session/连接限制；防止一个 session 的 agent 读/杀另一个 session 的后台任务（RFC 011）。

合并提交，把 packages/session 的 metadata seam 与 JSON 可序列化不变量（src/index.ts/json.ts/types.ts/README/tests，及 invariants 测试）并入 master。

在主干落地 5 段 split 中的第一段——session metadata 接缝与 JSON 序列化不变量。

packages/session-persistence-sqlite 的 index.ts/schema.ts/README/测试。移除 materialized INTEGER 列，改用 sessions 行的存在性作为 materialization 信号；all-tail 会话保留行（与 JSONL 一致），孤儿尾部行仍由下次 append 的延迟修复删除。补充 cordis db service 的 TODO，修正 README 的 Node 版本表述。

该列原本只是为 all-tail 场景强行让 has()/list() 为 false，反而与 JSONL backend 分歧；删除后简化代码并与 JSONL 的"文件存在 ⇔ materialized"对齐（#35 评审）。

新增 scripts/gen-module-graph.ts，从每个包的 @deepseek-ai/dsh-* peerDependencies 推导包间依赖图，渲染 docs/module-graph.md（GitHub 原生 Mermaid 图 + 依赖表），输出确定性；在 ci.yml、lefthook.yml、package.json、AGENTS.md 接入 verify-module-graph gate。

让包依赖图可视化，并在 pre-push 与 CI 上检测提交的图与生成器输出是否漂移。

scripts/gen-module-graph.ts 把模块图表格/图列表的排序从字母序改为 Kahn 风格拓扑排序（同层按字母序保证确定性），docs/module-graph.md 重新生成。

让表格先列叶子接口、依赖方在后，读起来更贴合依赖层级。

docs/development.md 把 verify-module-graph 加入 pre-push/CI gate 列表和日常命令；gen-module-graph.ts/module-graph.md 把 intro 段落输出为单行。

Codex review 跟进——让贡献者指南与新新鲜度 gate 一致，并遵守「每段一行」的 Markdown 约定（重新生成时不会再次引入硬换行）。

packages/session 新增 TurnEndReason {kind:'interrupted'} 和 interruptedTurnClosers() 修复助手；JSONL backend（format.ts/index.ts）保留最长连续前缀、丢弃撕裂尾部、持久写入合成边界事件关闭孤儿 turn；session-persistence 契约/测试加崩溃恢复用例；新增 ADR 0017/0018、RFC 013。

旧实现截断最后一个未关闭的 turn，但单个 turn 在长任务中可能极大，静默截断会丢失已持久化的真实工作——改为「保留事件 + 合成边界关闭」让恢复的会话立即可用。

合并 worktree-module-graph 分支：新增 scripts/gen-module-graph.ts、docs/module-graph.md，并把新鲜度 gate 接入 CI（ci.yml）、lefthook、package.json、AGENTS.md。

提供自动生成且可校验新鲜度的模块依赖图。

AGENTS.md 要求 PR 用 gh pr merge --merge 合并（禁止 squash/rebase）；新增 scripts/verify-md-wrap.ts（检测硬换行段落，带代码块/表格/列表等豁免），并入 doc-sync gate，覆盖 README、docs、AGENTS.md。

保留每 PR 的有意提交历史；统一「每段一行」的散文约定并用 gate 强制。

把 split/session-persistence（中断 turn 保留 + ADR/RFC）合入 split/agent-factory，冲突在 docs/adr/0017、docs/architecture.md。

在 agent-factory 分支上同步崩溃恢复改动。

packages/agent-loop/src/index.ts 支持 resumeSessionId：从 cordis.yml 的 env 读取，等持久化 backend load 后（ctx.inject）续接已有会话；不可读时仅告警不启动；新增 examples/coding-agent 的 resume e2e 与单测。

让 coding-agent demo 无需改代码即可恢复先前对话，验证跨进程续接。

把 split/agent-factory（含会话恢复 + 崩溃恢复）合入 split/session-persistence-sqlite，冲突在 docs/adr/0018、docs/architecture.md。

在 sqlite 分支上汇集上述改动。

docs/development.md 定义三种紧急度标记：FIXME（发布阻塞）、TODO（近期修）、XXX（ someday/maybe）。

让贡献者一致地用标记标注不同紧急度的待处理项。

packages/session-persistence-sqlite 的 load() 改为保留中断 turn 的真实事件，在单个事务内合成 step/end + turn/end {interrupted} 关闭孤儿 turn 并删除撕裂尾行；用 scanRows 替换 cutAtLastTurnEnd；更新测试与 README；共享 runPersistenceContract 现对两个 backend 起相同断言。

与 JSONL backend 契约一致——不再截断大 turn，改为持久化关闭孤儿 turn。

AGENTS.md 增加一行，指向 docs/development.md 中的 FIXME/TODO/XXX 语义说明。

把仓库约定与详细说明挂上钩。

合并 split/turn-enclosure（re-land，split 2/5）：新增 ADR 0017；agent-loop 的 agent.ts/loop.ts 强化 turn-enclosure 不变量与 turn 后错误模型；packages/invariants 扩展；大量测试扩充。

固化「每个 turn 必须闭合」的不变量并定义 turn 结束后的错误处理模型。

把 master（含 module-graph 生成器、gate、lefthook 等）合入 split/session-persistence。

在 session-persistence 分支上同步 master 的文档/工具改动。

把 origin/split/session-persistence（已含 master 改动）合入 split/agent-factory。

在 agent-factory 分支上同步上述合并结果。

把 origin/split/agent-factory 合入 split/session-persistence-sqlite。

在 sqlite 分支上同步 master 与各 split 的累积改动。

合并 worktree-docs+todo-markers：docs/development.md 定义三种标记语义，AGENTS.md 加指向链接。

正式把 TODO 标记约定并入主线。

把 origin/split/session-persistence-sqlite 合入 feat/acp-1-max-tokens-turn-end，冲突在 packages/session/src/types.ts；带入大量累积改动（pnpm 迁移、ADR 0016/0017/0018、RFC 013、agent-loop 会话恢复、各包 README 等）。

在 ACP 功能分支上汇集 split 链与 master 的全部工作。

按 review 反馈重写 scripts/verify-md-wrap.ts，改用 mdast-util-from-markdown（+GFM）解析，对跨多行的 paragraph 节点报错；修复正则版两个 bug（现在能抓到列表/引用块内换行段落，不再误报长 fence 包裹短 fence）；顺手展开 architecture.md、adding-a-tool.md 里两处既有硬换行；新增依赖与 lock。

用真正的 Markdown 解析器（带源位置）替代脆弱的正则，提升 gate 准确性。

把 master（含 PR #45/#46 的 turn-enclosure、TODO 标记等）合入 worktree-md-wrap-guard，冲突在 AGENTS.md。

在 md-wrap guard 分支上同步 master，准备合并。

把 feat/acp-1-max-tokens-turn-end 合入 feat/acp-2-bridge，冲突在 AGENTS.md、docs/cookbook/extension-cookbook.md、yarn.lock；带入 ACP 包、pnpm 迁移等大量累积改动。

ACP 多阶段特性栈的向前合并。

把 feat/acp-2-bridge 合入 feat/acp-3-multi-session，带入与上一次合并相同的累积改动集合。

ACP 特性栈继续向前合并到多会话阶段。

packages/session/src/repair.ts 的 interruptedTurnClosers 现在扫描中断 turn 中无匹配 tool/result 的 tool-call 块，为每个合成一个 error tool/result（放在 step/end 之前）；新增 packages/session/tests/repair.spec.ts 和共享契约用例；更新 ADR 0018 与各 README、load() JSDoc；修正 echo-agent README 的 session 清理路径。

循环在运行工具前就持久化了 assistant 消息，崩溃会留下悬空 tool-call，恢复后 deriveMessages() 重放出非法 transcript 被所有 provider 拒绝——合成错误 result 让重水化历史成为合法 transcript。

把 origin/split/session-persistence（含 2bae18f811 的 tool-result 合成修复）合入 split/agent-factory。

在 agent-factory 分支上同步 tool-result 合成修复。

把 origin/split/agent-factory 合入 split/session-persistence-sqlite，冲突在 docs/adr/0018-session-persistence.md。

在 sqlite 分支上同步 tool-result 合成修复。

AGENTS.md 删除两行——origin/master 合并解决时意外重复的「Symmetry」和「Tests」Conventions 条目，各保留一份。

消除合并引入的重复约定文字。

更新 .github/workflows/ci.yml 的 CI 步骤标签/注释，并在 docs/adr/0014-doc-sync-enforcement.md 补日期修订（去掉"两类可检查项"措辞，记录第三个门禁）。

新增 verify-md-wrap 门禁后，定义该门禁的 ADR 与 CI 注释已过时，需同步保持单一事实源。

packages/acp 去掉 cwd === process.cwd() 守卫及 session/load 中持久化 cwd 与启动目录的比对；packages/tool-bash 新增 resolveWorkdir，默认从 exec.agent.session.header.cwd 取 bash workdir（显式 workdir 仍优先，相对路径相对会话 cwd 解析）；测试、README、RFC 010 同步。

解除 RFC 010 "服务器须在 workspace 启动" 的限制，编辑器可打开任意项目目录，同一连接上 N 个并发会话可各自指向不同目录。

合并 worktree-md-wrap-guard 分支，引入 scripts/verify-md-wrap.ts 门禁、package.json 合并提交策略、AGENTS.md/docs/architecture.md/development.md 等文档与 pnpm-lock 更新。

强制 merge-commit 策略并新增 markdown 硬换行检查门禁。

合并 split/session-persistence 分支——新增 packages/session-persistence（抽象 Service Definition + 契约测试）、packages/session-persistence-jsonl（首个后端实现）、packages/session/src/repair.ts（崩溃修复合成 tool-result closer）；新增 ADR 0018、RFC 013；coding-agent/echo-agent 改用新服务；agent-loop 加 config-session-id。

引入可插拔的会话持久化抽象层并提供首个 JSONL 后端，奠定会话可恢复性基础。

把 master 的 md-wrap 门禁等改动同步进 split/agent-factory 特性分支。

在 agent-factory 特性分支上对齐 master 最新状态。

把 split/agent-factory 的进度同步进 split/session-persistence-sqlite 分支。

sqlite 持久化分支继承 agent-factory 的工厂接缝改动。

合并 split/agent-factory 分支——packages/agent 新增工厂方法，packages/agent-loop 加 resume 逻辑与 config-session-id，新增 coding-agent resume e2e 与 agent-loop resume 测试。

为 agent 提供创建与恢复的工厂接缝，支撑会话恢复。

把 master 最新改动同步进 split/session-persistence-sqlite（merge message 为空）。

sqlite 持久化分支再次同步 master。

合并 split/session-persistence-sqlite 分支——新增 packages/session-persistence-sqlite（schema.ts + index.ts + 测试），session-persistence 抽象小调整，tsconfig/publint 接线。

用第二个后端（SQLite）验证持久化抽象的通用性，结束 5 步拆分。

把 master（md-wrap 门禁、session-persistence 等）同步进 ACP max-tokens 特性分支，解决 AGENTS.md 冲突。

ACP max-tokens 特性分支同步 master 最新进度。

把 feat/acp-1-max-tokens-turn-end 合并进 feat/acp-2-bridge。

ACP bridge 分支继承 max-tokens 改动。

把 feat/acp-2-bridge 合并进 feat/acp-3-multi-session。

multi-session 分支继承 bridge 改动。

把 feat/acp-3-multi-session 合并进 feat/acp-4-session-cwd。

session-cwd 分支继承 multi-session 改动，构成 ACP 四步特性栈。

新增 ADR 0019 与 packages/session/src/surface.ts（SurfaceManager，基于 surfaceOp 标记增量维护的缓存链表）；SessionEvent 新增可选字段 sourceEventSeqs/surfaceOp；Session.append 加 SurfaceAppendOpts 第三参；deriveMessages 优先走 surface 路径并保留 legacy 线性扫描回退；sqlite schema v1→v2 迁移（两列）；invariants 加 surface 校验。

为 compaction、tool-result 剪枝等会话历史操作插件提供中央 hub——带溯源的派生链表，避免每个插件各自包装 agent/request 造成监听器顺序脆弱与无持久记录。

agent.ts 把 emit('agent/status') 包进 try/catch 防监听器抛出挂起；whenIdle 增加 inbox.hasQueued 检查（有排队工作时不立即 resolve）；loop.ts 的 closeStep 返回是否有失败、有失败则 break；max-tokens 步骤不再派发或记录 tool-call 块。

隔离监听器异常、避免排队 turn 被忽略、失败步骤立即终止、防止 max-tokens 截断的不完整 tool-call 被误执行。

adapter.ts 新增 patchPayload，统一经 pi-ai 的 onPayload 钩子修补 provider payload——回填原始 tool-call arguments、per-tool strict、stop 序列、省略 reasoning_effort；convert.ts 把 error finish 细分为 AUTH/RATE_LIMIT/INVALID_REQUEST/SERVER 码，流未正常结束抛 STREAM_CLOSED。

让 pi-ai 后端产出与 dsh-llm 契约一致（原始 JSON arguments、分类错误码），不因 provider 库的表达力限制破坏 adapter 契约。

system-prompt 的 assemble() 对 sections 与 tool parameters 做 structuredClone 快照；tools 的 schemas() 对 parameters 做 structuredClone；ToolRegistry.execute 的 waterfall 失败用 .catch 转成 isError 结果而非向上抛出。

防止下游修改污染注册表中的 schema，并让单个 waterfall 监听器抛出不致整体工具执行失败。

invariants 加 turn/step 序号连续性校验（nextTurn/nextStep）并豁免 interrupted 合成结果；jsonl/sqlite 后端 dispose 改用 settledErrors 聚合错误并以 AggregateError 抛出（不再静默 allSettled）；jsonl materialize 加父目录 mkdir+syncDir；sidecar 读取区分 ENOENT 与损坏（损坏即抛）；repair 在 mutating load 期间持久化合成 closer。

序号不连续即报错、dispose 失败不再静默吞掉、损坏 sidecar 不被当成缺失，提升持久化健壮性。

acp codec.ts 支持 resource_link 块（渲染为显式文本引用而非丢弃）；session/load 要求请求 cwd 与持久化 cwd 一致，否则 invalidParams；validateWorkspaceParams 增加 mcpServers 非空拒绝；user/message 在 live prompt 时不回显（仅 load replay 时发 user_message_chunk）；RFC 010 文案对齐。

支持 baseline 的 resource_link、防止 cwd 不匹配导致编辑器与 bash 执行器工作区不一致、避免静默丢弃或重复回显内容。

package.json postinstall 从直接 lefthook install 改为 scripts/install-lefthook.mjs（非 git 仓库或缺 lefthook 时安全退出）；bash-local 加 assertPositiveFinite 校验 timeoutMs/maxTimeoutMs/maxOutputBytes（配置级与请求级）。

让 hook 安装在缺 git/lefthook 时不报错，并防止 bash 配置传入非正有限数导致静默错误。

新增 RFC 014（agent lifecycle and ownership seams）与 RFC 015（shared persistence write coordinator）；更新 ADR 0002/0014、architecture、RFC 009/011、packages README。

把前述修复暴露出的后续清理工作（agent 生命周期/所有权、共享持久化写协调器）记录为 RFC 追踪。

llm-pi-ai/adapter.ts 给 patchPayload 的防御性分支加 /* v8 ignore next */ 注释，并补 400→INVALID_REQUEST 用例；jsonl 测试加"损坏 sidecar 应拒绝而非视为缺失"；tools 测试加 tools/execute 抛 HarnessError 时结构化 error 信息保留。

为前述修复引入的新防御分支补充测试覆盖并标注忽略以维持覆盖率门禁。

.agents/skills/dsh-code-review/SKILL.md 重写定位，新增 "How to think about a review" 章节——强调独立从代码推理、覆盖所有方面（正确性/并发/安全/设计/测试/文档…）、验证后再标记、校准置信度抑制噪声、以严重性为首；加 receiving-review 注意事项。

避免 skill 被误读为完整审查清单，明确它是降低启动成本的指引，审查者仍需独立全面推理。

合并 feat/acp-1-max-tokens-turn-end 分支——agent-loop/loop.ts 把 max-tokens 上浮为独立的 TurnEndReason，session types 新增对应类型，新增 mock-adapter 与 loop 测试。

将 max-tokens 作为独立的 turn 结束原因上浮，与 ACP 的 max_tokens stop reason 对齐。

SKILL.md 限定"独立判断"仅适用于"看什么"和"如何应用规则"，而非"文档化要求是否成立"；把检查项拆为 "Hard blockers（文档化要求：doc-sync/HMR-safety/ADR 0007 门禁）" 与 "Reviewer-only checks（判断）" 两类。

修正上一提交"指导而非权威"的过度修正——避免被读成可放弃真正阻塞性的文档化检查，AGENTS.md/packages ADR 0007 仍具权威性。

.agents/skills/dsh-code-review/SKILL.md，在质量门硬阻断清单中加入 doc-sync 与 module-graph 新鲜度检查

补上 Codex 第二轮审查发现的遗漏，避免文档类门失败被误判为阻断清单之外

合并 worktree-improve-dsh-code-review-skill 分支，重写 dsh-code-review/SKILL.md（+34/-11）

把该技能明确定位为审阅指引而非裁决权威

将 docs/adr/ 与 docs/rfc/ 合并为 docs/rfc/{proposed,implemented,rejected}/，所有文件按 yyyy-mm-dd-topic.md 重命名；新增 scripts/verify-md-links.ts 交叉链接校验门；新增 docs/AGENTS.md 交叉链接规范；同步 ~40 处文档链接

消除两套并行文档树，用机器可校验的相对链接替代散乱的 "ADR NNNN"/"RFC NNN" 文字引用

修正两条根 AGENTS.md 指错文档的交叉链接；扩展 verify-md-links 覆盖 .agents/skills/**/*.md；支持路径百分号解码；删除属性测试 RFC 中未实现的 "nightly 100x" 表述

补齐重组遗留的链接错指与门覆盖盲区

合并 worktree-rfc-naming-overhaul 分支到 master，含 78 文件改动

将上述 RFC 重组落地到主干

packages/acp/src/index.ts 删除多余的 export default apply（它让 Loader 丢弃 inject 等命名导出）；packages/agent-loop/src/index.ts 将 this.ctx.sessionPersistence 改为 this.ctx.get('sessionPersistence', false)；新增 docs/postmortem/0001-acp-default-export-drops-inject.md；新增无 key 的 session/new e2e

修复编辑器（Zed）连接时 session/new、session/load 双崩溃；178 个单元测试 100% 覆盖却未覆盖到，因为测试手工挂载插件绕过了 Loader

将 master（含 RFC 重组、ACP 崩溃修复、postmortem 0001）合入 feat/acp-2-bridge；解决 SKILL.md、AGENTS.md、ACP RFC 三处冲突

让 ACP bridge 特性分支跟上主干变更

AgentLoop.resume 改用严格 ctx.get('sessionPersistence')；修正 bridge teardown 注释（ACP 创建 agent 的注册项绑定在 BRIDGE fiber 而非 AgentLoop fiber）；新增对应回归测试；同步 postmortem/packages AGENTS/review skill

保证非激活后端读作 undefined 而非 teardown 中途被返回，并钉死 fiber 归属语义

合并 bridge 特性到 multi-session 分支，解决 ACP RFC 与 packages/acp/src/index.ts 冲突

多会话特性分支继承已落地的 bridge 修复

合并 multi-session 到 session-cwd 分支，解决 ACP RFC 与 acp 入口冲突

session-cwd 特性分支继承 multi-session 与 bridge 的全部修复

新增 MARKERS.md（161 行），按 docs/development.md 标准统计 FIXME（2）/TODO（30+）/XXX（28）分布

对仓库内所有 FIXME/TODO/XXX 标记做一次完整分类盘点

将 vendor/cordis/src/reflect.ts、packages/bash-local/src/run.ts 的 TODO 改为 XXX；vendor/loader/src/index.ts、vendor/cordis/src/fiber.ts 的 FIXME 改为 TODO；删除 MARKERS.md

使 4 处标记与其真实紧迫度匹配

将 packages/bash-local/src/run.ts、packages/tool-bash/src/index.ts 及其测试中的 4 个 TODO(tool-bash-owner-hmr)/TODO(stateful-shell) 改为 XXX；恢复 vendor 文件；保留其余 TODO（demo/sub-agents/permissions 等）

明确这些项为 someday-maybe，无落地承诺

packages/bash-local/README.md 与 packages/tool-bash/README.md 将 TODO(...) 改为 XXX(...)，与源码保持一致

修复 Codex CLI 审查发现的 README 与源码标记不一致

packages/tools/src/index.ts 在 ToolDefinition/defineTool 上新增 presentCall/presentResult 两阶段展示接缝（含中性 ToolCallKind/ToolCallPresentation 词汇）；packages/tool-bash/src/index.ts 为 bash/bash_output/bash_kill 声明展示函数；packages/acp/src/index.ts 注入 tools、引入 ToolPresenter 把中性展示映射到 ACP wire 形态

修复 Zed 工具卡片只显示 "bash" 的问题，让每个工具自管其渲染而非 bridge 硬编码

将 sqlite 持久化分支合入 session-surface；带来 scripts/verify-md-wrap.ts、CI、AGENTS、架构文档与 pnpm-lock 更新

session-surface 特性分支吸收 sqlite 持久化与 doc-wrap 门

将 master（含 RFC 重组、code-review skill、verify-md-links 门、loop.ts 与多个会话包改动）合入 session-surface 分支

让 session-surface 分支与主干同步

修正 docs/rfc/implemented/2026-06-18-session-surface.md 中 3 处链接与 packages/session-persistence-sqlite/README.md 中 1 处链接

修复合并引入的失效文档链接

packages/tools/src/index.ts 的 schemas() 改用显式 allowlist 构建 ToolSchema（不再剥离 execute，避免 presentCall/presentResult 泄漏到模型请求）；packages/acp/src/index.ts 的 session/load 重放改用一次性 ToolPresenter，ToolPresenter.call/result 含抛错的展示回调并通过 onError 兜底；补充多组回归测试

堵住展示函数泄漏到模型请求、历史中断 turn 污染活跃 presenter、以及展示回调抛错拖垮在线 turn 三类风险

packages/tool-bash/src/index.ts 将 presentCall 标题改为 "description — command"；重写 acp 测试用真实 dsh-tool-bash+dsh-bash-local 跑 echo；新增 makeBridgeHarness({ withBash })；AGENTS.md 增加 "测试优先用真实实现而非 mock" 原则；新增 docs/rfc/proposed/2026-06-18-acp-terminal-and-tool-rendering.md

让 execute 卡片（Zed 隐藏 rawInput）可见命令，并使测试覆盖真实展示路径

packages/session/src/types.ts、surface.ts、index.ts 引入并强制 SurfaceEvent 类型；packages/invariants 与 session-persistence-sqlite 同步调整；更新相关测试

把 session 对外投影事件收敛为受类型约束的 SurfaceEvent，由 invariants 门把关

将原 proposed RFC 改写为 implemented 版（docs/rfc/implemented/2026-06-18-acp-terminal-and-tool-rendering.md）：保留 dsh-bash agent 侧执行，经 _meta（terminal_info/terminal_output/terminal_exit）渲染 Zed 终端卡片，capability 门控；拒绝 spec 的 client-side terminal/create

在实现前固化已验证的 wire 设计，记录为何不走 spec 的客户端终端路径

packages/tools/src/index.ts 新增 provider 中立的 ToolTerminal 形态；packages/tool-bash/src/index.ts 在 presentCall/presentResult 标记 terminal；packages/acp/src/index.ts 读取 clientCapabilities._meta.terminal_output 能力，capability 开启时映射到 content:[{type:'terminal',...}]+_meta.terminal_info/output，否则走文本路径；新增 e2e 与单测

Zed 客户端声明能力时把 bash 渲染为真实终端卡片（cwd 头+命令+输出），无能力时回退到 ```console 文本块

docs/rfc/implemented/2026-06-18-acp-terminal-and-tool-rendering.md 与 packages/acp/README.md 措辞调整

说明 _meta 是 ACP spec 的扩展机制，而 terminal_info 等键是 Zed 的约定而非规范要求

packages/acp/src/index.ts 与 packages/tool-bash/src/index.ts：execute 卡片标题改为命令本身、模型描述作为 content 文本块置于卡片上方、完成卡片经 _meta.terminal_exit 携带退出状态；修复 terminal 模式下 tool_call_update.content 省略、保留原始换行、相对 workdir 按 session cwd 解析、结果侧终端输出门控；packages/tools 新增 exitCode/signal 与 content 块字段；含往返测试与真实模型 e2e

使 bash 终端卡片外观与 claude-agent-acp/codex-acp 一致，并修复上一终端卡片提交的多个 bridge 问题

packages/acp/src/index.ts、packages/tool-bash/src/index.ts 及对应测试，agent note 一处。

修复三处真实缺陷——parseExitStatus 把末尾恰好是 marker 文本的 exit 0 误判为失败（改为锚定前导换行）；后台启动和 isError 结果被错误渲染成 exit-0 终端卡片（改为不再标记 terminal）；结果路径上 live 重读 terminal 能力会因第二次 initialize 而错位（改为在 SessionRecord 创建时快照 terminalEnabled）。

packages/tool-bash/src/index.ts 一处注释。

评审细节——KNOWN RESIDUAL 注释原本只提到 [exit code: N] 末尾欺骗，同样问题对 [killed by signal: SIG] marker 也成立，措辞改为覆盖两种 marker。

合并 feat/acp-2-bridge 分支。新增 packages/acp/（codec.ts、index.ts ~750 行 + 8 个测试文件、harness）、examples/acp-agent/（含 e2e 与 cordis.yml）、examples/base.yml，并改 agent-loop/agent 暴露所需钩子。

引入 Agent Client Protocol 桥，让外部编辑器通过 JSON-RPC over stdio 驱动整个 coding agent；附带 postmortem 0001（默认导出丢失 inject 的事故）。

合并 feat/acp-3-multi-session。改 packages/acp/src/index.ts、packages/tool-bash（任务归属）并新增 multi-session.spec.ts，新增 docs/rfc/proposed/2026-06-14-acp-multi-session.md。

单条 stdio 连接上多路复用 N 个并发 ACP 会话，并将 bash 工具调用与发起会话绑定（任务归属）。

合并 feat/acp-4-session-cwd。改 packages/acp/src/index.ts、packages/tool-bash 接受每会话 cwd，更新 acp-agent e2e 和 README。

让每个 ACP 会话使用独立的 cwd，在各自工作区内运行 bash 与工具调用。

合并提交（无 body）。把 master 上 PR #41/#42/#48 三次合并（ACP bridge、multi-session、session-cwd）合入 feat/acp-5-tool-call-ui 特性分支。

在 tool-call UI 特性分支上同步已落地的 ACP 主线进展，准备后续 PR。

合并提交（无 body）。把 feat/acp-5-tool-call-ui（连同其刚合入的 master）合入 feat/acp-6-terminal-rendering 特性分支。

让 terminal-rendering 分支基于已更新的 tool-call-ui 分支，保证后续 terminal 卡片工作建立在统一基线上。

packages/tools/src/index.ts 新增一段 FIXME 注释（12 行）。

ToolCallPresentation/ToolResultPresentation/ToolTerminal 随增量演进职责已模糊（call/result 终端字段重叠、桥接需拼接 content/terminal/rawInput）。标记为发布前阻断性 FIXME，要求围绕工具渲染 INTENT（按卡片类型的 tagged union）重设计，并在更多工具/UI 依赖当前 optionals 集合前先落地 RFC。

合并 feat/acp-5-tool-call-ui。改 packages/acp/src/index.ts、packages/tools（新增 schema.ts 扩展、Presentation 类型）、packages/tool-bash 暴露 title/command/output，新增 RFC 2026-06-18-acp-terminal-and-tool-rendering.md，扩展 stream-update/turns/load 测试与 e2e。

把 tool-call 的 UI 呈现职责交还给工具自身（title、command、output），ACP 桥据此渲染，统一工具呈现契约。

合并 feat/acp-6-terminal-rendering。改 packages/acp/src/index.ts、packages/tool-bash（terminal 输出经 _meta 传递、含 cwd 头）、packages/tools，更新对应 RFC（移到 implemented），扩 e2e 与测试。

为 bash 工具提供 terminal 风格的调用卡片，显示 cwd 头并通过 _meta 通道携带输出，对齐 claude-agent-acp 的终端渲染形态。

合并提交，把 master（含 PR #56/#58 的 ACP terminal & tool rendering 全套改动）合入 chore/classify-markers 分支。

在 marker 分类特性分支上同步 master 已合入的 tool-rendering/terminal 主线，便于后续分类改动可基于最新基线。

packages/bash-local（README + run.ts）、packages/tool-bash（README + index.ts + 测试）共 5 处。

4 个非 vendor 的 TODO 被标得过重，按仓库 FIXME/TODO/XXX 分级语义降级——stateful-shell（设计参考，当前 spawn-per-call 工作正常）与 tool-bash-owner-hmr（仅 HMR 开发问题，当前可接受）改为 XXX；其余 TODO 保持不变。

合并提交（带多处冲突解决）。把 master 合入 codex/pr48-repo-hardening-rfcs，冲突覆盖 docs/adr、docs/rfc/ 多个 RFC、packages/acp/src/index.ts、packages/agent-loop/src/loop.ts、packages/tools/src/index.ts 等。本合并汇集了 acp/tool-rendering/terminal/session-persistence 大量重构与 RFC 目录重组（RFC 迁移到 implemented/proposed 子目录）。

将仓库硬化 RFC 工作分支与已演进的 master 对齐，使后续 PR 能基于统一目录结构和最新 ACP 实现。

新增 docs/rfc/implemented/2026-06-19-acp-snapshot-tests.md，docs/rfc/README.md 加链接。

记录新增的第三测试层级——通过 cordis Loader 启动真实 acp-agent 子进程，record-once 录制真实 LLM 流响应，后续在 CI 中确定性地回放，对完整 stdout 转录做 golden diff，实现无 key 运行。固化 Codex (xhigh) 评审得出的设计（provider 中性的 llm/stream 录制点、discriminated fixture schema、positional replay、per-stream 原子 flush、replay 用 providerless 配置）。

examples/acp-agent/start.ts、packages/acp/src/index.ts、packages/agent-loop/src/loop.ts、packages/session-persistence-sqlite/src/index.ts、packages/system-prompt/src/index.ts、packages/tools/src/index.ts 及相关测试。

处理 Claude code review 的若干跟进项（acp-agent start、ACP 主流程、agent-loop、sqlite 持久化、system-prompt、tools 各处小修与对应单测补全）。

新增 examples/acp-agent/src/llm-replay.ts（function/namespace 插件）及 tests/llm-replay.spec.ts，扩展 vitest.config.ts 和 knip.json。

在 llm/stream waterfall 上挂监听器——record 模式把真实流按每个 stream 原子写入 llm.json（子进程被 SIGKILL，无 dispose 路径），replay 模式短路 waterfall 按位置回放第 N 个 stream() 调用，使 snapshot 测试无需 key 即可驱动真实 agent。fixture entry 为 discriminated {chunks|throw|hang}，能同时表达两种 LLM 失败分支（stream 抛错 vs finish-error chunk）与取消；缺/耗尽 fixture 时 fail-loud。

packages/invariants/src/index.ts、packages/session-persistence-jsonl/src/index.ts 及其测试。

list 会话时若 JSONL sidecar 文件损坏应被妥善处理（而非让列举整个失败），新增对应容错与单测。

packages/bash-local/src/run.ts 及 run.spec.ts。

spill（溢出文件/管道）关闭时若失败不应扩散影响外层执行，做隔离处理并加测试。

packages/acp/src/index.ts（28 行，+15/-13）。

把回合结束时 prompt 结算（settlement）的重复逻辑抽取为共用实现，消除重复、便于后续一致修改。

packages/session-persistence/src/index.ts 新增公共守卫，session-persistence-jsonl、session-persistence-sqlite 删除各自的重复拷贝并改调用，persistence.spec.ts 扩展。

把 jsonl 与 sqlite 两个后端里相同的纯守卫抽到 session-persistence 基类，消除重复（净删 ~69 行）。

packages/agent-loop/src/loop.ts、packages/agent/src/index.ts、packages/agent/src/types.ts、packages/session/src/index.ts。

删除已过期的注释和重复字符串字面量，做小幅清理。

packages/tool-bash/src/index.ts 及 README、测试，packages/bash/src/types.ts、packages/bash-local/README.md 及两处 RFC 措辞。

spill 路径不可用时（如能力未提供/被禁用）应正确处理而非崩溃，补测试与文档。

合并提交（无 body）。把 master 上 marker 分类相关改动（ede9c1bb 的 4 处 TODO→XXX 降级、d397d0da 的 marker 分支合并、以及若干 classify-markers 跟进）合入 codex/pr48-repo-hardening-rfcs。

在仓库硬化 RFC 分支上同步 master 的 marker 分类结果，保持基线一致。

重写 examples/acp-agent/src/llm-replay.ts（移除 record tee，改 replay-only 派生器）与 tests/llm-replay.spec.ts，更新示例 README 与 RFC 措辞（2026-06-19-acp-snapshot-tests.md）。

按设计修订，snapshot fixture 直接复用已持久化的 session JSONL（<scenario>/session.jsonl）而非手写 llm.json——日志已含全部 LLM 行为（assistant/chunk）与 harness 行为（tool/call、tool/result、turn/*、usage），一份产物同时驱动回放兼作行为 golden。deriveReplayScript 按 (turn,step) 分组；不含 finish 终结的组即 stream() 抛错的指纹，fail-loud 而非当作正常停止；两种日志无法表达的情形（抛错、取消/hang）通过可选 replay.override.json sidecar 补充。

新增 snapshot-harness.ts、snapshot-normalize.ts（+ spec）、acp.snapshot.ts、两个 cordis.snapshot*.yml、handshake 场景 fixture（input.json/session.jsonl/stdout.golden.txt）、vitest.snapshot.config.ts，并改 start.ts、lefthook.yml、knip.json、package.json（新增 test:snapshot/test:snapshot:record 脚本）。

把无 key 的 snapshot 回放管线端到端打通：harness 经 cordis Loader 启动真实 acp-agent 子进程、把原始 stdout 喂入 SDK ClientSideConnection、解释 input.json DSL、关 stdin 触发优雅关闭、采集 session.jsonl（finally 中 SIGKILL 并清理临时目录）；两个纯 normalizer 规整 cwd/sessionId/UUID/JSON-RPC id/时间但保留 seq，stdout 出现非 JSON 行即抛（purity 检查）；start.ts 按 DSH_SNAPSHOT 选 replay/record 配置并在 stdin 结束时 dispose 以保证持久化先 flush；handshake 场景作为首个 golden。

在 examples/acp-agent/tests/ 新增 5 个快照场景——text-turn、tool-call-turn、multi-turn（真实 API 录制）、error-finish、cancel（用 replay.override.json 模拟 401/中途取消）；在 snapshot-harness.ts 增加 promptExpectError、promptAndCancel 两个输入 DSL 操作。

建立可重放、无 key、确定性的 ACP 快照测试基线。

AGENTS.md 补充 test:snapshot/test:snapshot:record 命令并修正 pnpm run test 注释；新增约定条目（影响 editor transcript 或端到端 UX 的改动必须带快照测试）；dsh-code-review SKILL 增加 reviewer 对 golden diff 的检查。

把快照测试确立为仓库约定。

.github/workflows/ci.yml 新增 test:snapshot 步骤；vitest.snapshot.config.ts 改为仅当 DSH_SNAPSHOT=record 时加载 .env，非 ENOENT 的加载错误不再吞掉；修正 start.ts 优雅退出注释；docs/development.md 同步。

补齐 CI 真实闸门并修正 replay 不应触网的安全语义。

AGENTS.md 把 pnpm run test:snapshot -- -t <name> 改为不带 -- 的形式（pnpm 透传 --，vitest 会把后续当作文件名过滤导致 -t 失效）。

修正会让命令静默跑全部场景的文档错误。

清理 docs/rfc/implemented/2026-06-11-content-block-vocabulary.md 中已完成的 review TODO，以及 packages/agent/src/types.ts、packages/session/src/index.ts 里对应注释。

清理过时 TODO。

所有 *.golden.txt 重命名为 *.golden.jsonl，normalizer 去掉 2 空格缩进；11 个 golden 全部重生成；normalizer spec 断言紧凑形式。

让 golden 忠实对应 NDJSON stdout 与 JSONL session log 的实际形态，保持 grep/jq 友好。

合并仓库范围的"生命周期、持久化与契约加固"分支，涉及 acp/agent-loop/agent/bash/session-persistence(jsonl/sqlite)/system-prompt/tool-bash/invariants/llm-pi-ai 等大量包，并新增两份 RFC（agent 生命周期/归属、共享持久化写协调）。

合入 repo-hardening 改动。

抽出 examples/base-core.yml（无 provider 的 provider/tool 核心）与 examples/acp-agent/acp-tail.yml（agent-loop + 持久化 + ACP bridge）；base.yml = base-core + llm-deepseek，replay 配置 = base-core + llm-replay；删除 cordis.snapshot-record.yml，录制改复用 cordis.yml。

消除三个 acp-agent 配置间的复制粘贴，避免漂移。

修 examples/coding-agent 与 examples/echo-agent 的 src/stdio-chat.ts readline 编辑问题，并为两者新增 stdio-chat.spec.ts；.gitignore/vitest.config.ts 小调整。

修复 demo 输入行编辑 bug。

harness 支持可选的 <scenario>/workspace/ 目录，record/replay 前拷入临时 cwd，cwd 在 golden 中被归一化；新增 workspace-edit 场景（种子 greeting.txt，prompt 让 agent 追加 WORLD 并 cat 回读）；snapshot-harness.ts 把种子/spawn 纳入同一 try/finally 防泄漏。

让快照能基于非空工作区跑完整的读→写→验证循环。

把 master（已含 PR #50 repo-hardening）合入 feat/acp-snapshot-tests 分支。

特性分支与 master 同步。

master 的 "fix(acp): align prompt and workspace contracts" 改变了 transcript（live prompt 不再回显 user/message），6 个 golden 漂移；重新录制 4 个真实 API 场景、重接受 2 个 authored golden。

让快照反映合并后的行为，验证快照机制按设计工作。

新增 reject-extra-dirs 场景与 newSessionExpectError 输入操作，固定 bridge 对非空 additionalDirectories 返回 -32602 Invalid params 的契约。

用快照钉住 editor-facing 的 workspace-scope 拒绝行为。

把 packages/agent-loop 的具体 Agent 类改名 ReactLoopAgent，更新 README/docs/examples/tests；包名、AgentLoop 默认导出与 ctx.agentLoop service key 保持不变。

让类名显式表达 ReAct 风格推理循环。

合并 ACP 快照测试特性（record-once / replay-deterministic），含 llm-replay、snapshot-harness、normalizer、各场景 golden、CI 接入、vitest.snapshot.config.ts 等。

合入快照测试特性。

把 master（已含 PR #59 快照测试）合入 worktree-rename-react-loop-agent 分支。

rename 分支与 master 同步。

合并把 LoopAgent 重命名为 ReactLoopAgent 的重构 PR。

合入重命名改动。

新增 packages/ui-stdio（统一两份发散的 stdio-chat.ts，带测试 I/O 缝隙）、packages/llm-replay（把 examples/acp-agent/src/llm-replay.ts 及其 spec 移入并补测到 100%）；echo/coding 改用新包并删除旧 src；为 echo/coding 增加 keyless Loader-path e2e smoke；examples/AGENTS.md 写入 smoke 约定；AGENTS.md 加入 scoped、可移除的 pre-release stance。

让原属 examples/、落在覆盖率闸门外的逻辑进入 100% 覆盖 gate 并去重。

新增 .github/workflows/e2e.yml，用 repo secret 跑 pnpm run test:e2e 对 https://api.deepseek.com；触发含 workflow_dispatch、push、nightly、pull_request；job 级 if: 跳过 fork/Dependabot 等 untrusted PR；缺 secret 时 preflight 硬失败；permissions: contents: read，超时 45m。

填补 CI 没有任何 with-key 套件的空白，同时保持 ci.yml 仍 keyless/可 fork。

跟踪 200ms EOF-exit setTimeout 句柄并在 disposer 中清除，重入 maybeExit() 合并到一个挂起定时器，新增两条回归测试；README/Config JSDoc 更正"渲染是全局而非按 agent scoped"；createStdioChat 在 helper 内默认 welcome/agent（不再依赖 cast）；快照 RFC 补注 replay 插件已移入包。

修复 dispose 竞态与文档过claim，Codex 审查 round 1。

原地重写快照 RFC 的 replay 插件段为当前事实；新增 docs/rfc/implemented/AGENTS.md（+ CLAUDE.md symlink）要求"已实现 RFC 必须随代码改动就地更新路径/名称/结构，不得 append-only 记录漂移"；调整 docs/rfc/README.md 区分"追踪决策落点（必需）"与"翻转决策（禁止）"。

让 implemented RFC 与实际 shipped 代码保持一致。

.github/workflows/e2e.yml 把名为 DEEPSEEK_API_KEY_EXTERNAL 的 repo secret 映射到 e2e 套件读取的 DEEPSEEK_API_KEY 环境变量。

修正 secret 名与套件期望的环境变量不一致。

.github/workflows/e2e.yml cron 从原时间改为 00:17 UTC（北京 08:17）。

把夜间跑的时间调到更合适的窗口。

合并把 examples 可复用逻辑抽成受测包（ui-stdio、llm-replay）的重构 PR，含 round-1 审查修复与 RFC 同步。

合入抽取改动。

新增 docs/rfc/implemented/2026-06-19-real-api-e2e-ci.md，覆盖独立 secret 消费工作流的理由、fork/Dependabot/secret 威胁模型、pull_request 触发的残余暴露与公开后的变化，并索引到 RFC README；在 e2e.yml 的 pull_request 触发处加 SECURITY 注释，禁止改用 pull_request_target。

沉淀该 CI 决策的依据与安全边界，防止后续引入 untrusted-code-with-secrets 泄漏。

合并 PR #64（分支 worktree-e2e-real-api-workflow）。新增 .github/workflows/e2e.yml、对应 RFC 文档 docs/rfc/implemented/2026-06-19-real-api-e2e-ci.md，并在 docs/rfc/README.md 登记。

在 CI 中跑真实 DeepSeek 外部 API 的端到端测试，保障 provider 行为。

新增 docs/rfc/implemented/2026-06-20-ts-build-config.md，并登记到 RFC 索引。

以 ADR 形式记录"先 TSC 构建、统一 tsconfig"的构建配置决策，为后续一系列 tsconfig 重构奠基。

packages/ 下 22 个文件，把相对导入中的 .ts/.js 后缀去掉。

统一为 extensionless 导入，配合新的 TS 构建配置。

vendor/ 下 8 个文件（hmr、loader、logger-console 等）去掉相对导入后缀。

vendored 包与 packages 保持一致的 extensionless 导入风格。

36 个 package.json + tsconfig.json，把 TS 声明输出指向 lib/typings 子目录，并相应调整 files/导出。

分离 TS 中间产物（lib/typings）与 tsdown 最终发布的 lib/ 运行时产物，避免互相污染。

18 个 vendor 包的 package.json + tsconfig.json，同步上述 typings 子目录调整。

vendored 包与 packages 构建产物布局保持一致。

vendor/README.md，补充 package.json/tsconfig.json 的重生规则、新增 loader/src/config/isolate.ts 的 declaration merge 去 .ts 后缀改动、并说明 tsdown 配置读取 lib/typings 下产物。

把上一组 typings/lib 布局变更如实登记到 vendored 包的修改日志，保持 sync 记录可追溯。

packages/*/tests 下 24 个测试文件去掉相对导入后缀。

测试侧同样统一 extensionless 导入。

package.json、tsconfig.base.json、tsdown.config.ts、vendor 的 tsdown 配置、若干文档与 pnpm-lock.yaml；说明先 TSC 再 tsdown 的两步构建流程。

实现 ADR 中提出的"TSC 先生成声明到 lib/typings，tsdown 再打包到 lib/"的两步构建。

删除 tsconfig.test.json、tsconfig.typecheck.json，合并进根 tsconfig.json；调整 eslint.config.mjs、scripts/doc-typecheck.ts、各 vitest 配置与 examples 测试。

用一份 tsconfig 配合不同规则替代三份分散配置，简化构建矩阵。

docs/rfc/implemented/2026-06-11-doc-sync-enforcement.md、2026-06-11-quality-gates.md。

把旧 ADR 中关于 tsconfig 的过时描述更新为当前统一 tsconfig 的真实行为。

CI yml、cookbook、RFC 文件改名（2026-06-20-ts-build-config.md → 2026-06-17-ts-build-config.md）、为所有 packages/vendor 的 package.json 增加字段，新增 scripts/check-workspace-constraints.ts，调整 scripts/doc-typecheck.ts。

落实代码 review 的构建配置整改项，并加一个工作区约束检查脚本。

所有 packages/vendor 的 package.json、tsconfig.json、tsdown 配置、cookbook、check-workspace-constraints.ts 等共 65 个文件，把 lib/typings 重命名为 lib/types。

统一术语，发布目录命名更直观。

移除 SessionSummary（updatedAt/title/firstPrompt）及 SessionPersistence.update()；删除 JSONL .summary.json sidecar 机制、SQLite 的 title/first_prompt/updated_at 列与每次 append 的 updated_at bump；SQLite SCHEMA_VERSION 1→2 且拒绝任何非当前 user_version（不做迁移）；新增 RFC 与 AGENTS.md 的"Tests document behavior"一节。净 -400 行。

这些字段在生产中无读取者、update() 无生产调用方（ACP 标题来自 tool-call presenter 而非存储），属纯死代码；删除同时消除 JSONL sidecar 与 SQLite 列的持久化分歧，为后续 write coordinator 铺路。

拟议的 write-coordinator RFC、JSONL README 的格式版本说明、findLog 中一条遗留 sidecar 注释。

根据 Codex review 修正上一提交删除后留下的三处与现状不符的描述（明确无迁移策略）。

新增 packages/session-persistence/src/coordinator.ts（PersistenceCoordinator + PersistenceBackend hook 接口），JSONL/SQLite 两个 backend 改为组合它并只实现存储原语；把原本重复的编排测试合并为 runCoordinatorContract 套件（memory/jsonl/sqlite 各跑一遍）。净 -112 行，backends 缩减约 1200 行重复代码；RFC 由 proposed 迁到 implemented。

JSONL 与 SQLite 的写路径编排（四张 map、installWritePath、flush、drain、adopt 等）完全相同，每个修复都要改两遍，抽出共享 coordinator 去重并固化崩溃修复语义。

session-persistence-jsonl/src/index.ts 的 loadLive 直接走 logPath(cwd, id)（undefined 视为确定的 no-cwd 桶而非"未知"），不再扫所有 cwd 桶；findLog 退化为纯全桶扫描；coordinator 的 has() 改为对未跟踪 id 用 loadStored、对已跟踪 session 才用 loadLive；新增跨-cwd 回归测试。

Codex review 发现的 HMR live-adoption 漏洞——一个 no-cwd 的 live session 会误采纳来自真实 cwd 桶的同 id 日志，导致 cwd 被污染。

agent-loop/src/agent.ts 新增 cancel()，清空 queued/steering FIFO 并 abort 进行中的 step；loop.ts 加 turn 级 marker，在每个 turn 可能启动/继续的四个窗口（idle 等待后、setStatus running 后、step 启动前、continuation gate）检查；ACP session/cancel 改用 agent.cancel()；新增 cancel.spec.ts（279 行）。关闭 TODO(rfc010-cancel-prestep)。

原 abort() 只能杀进行中的 step，已排队但未启动的 prompt 仍会跑完，且紧接着的新 prompt 会被并入被取消的 turn；cancel() 提供独立的取消动词关闭该竞态窗口。

agent-loop/src/loop.ts 的 window-1 cancel 分支，仅当没有新任务入队时才 settleIdle()，否则清掉旧 marker 继续跑新 prompt 的 turn；新增精确复现该交错（send A → whenIdle → cancel → send B）的回归测试。

Codex review 发现：cancel() 清掉 A 后若有 B 在 loop 恢复前入队，原代码无条件 settleIdle() 会让 A 的 whenIdle waiter 在 B 还没跑时就 resolve（零事件返回）。

AgentFactory/ctx.agents.create/resume 返回 AgentHandle = { agent; dispose(): Promise<void> }；dispose() 按序执行：注册+启动 effect disposer → await agent.done（loop 退出并捕获最终 flush）→ session disposer（detach onAppend + 删 store）；新增 SessionStore.createOwned() 与 AgentLoop.startOwned；ctx.agents.get(id) 仍返回裸 Agent。

把"销毁这一个 agent"做成一种 capability——只有持有 handle 的 owner 能精确停掉它的 loop、等待真正 quiescence、注销并清理 session，且 teardown 顺序对持久化是 load-bearing 的（最终 turn/end 与 session/flush 必须在 onAppend 仍 attach 时产生）。

ACP bridge 在 SessionRecord 中持有该 session 的 AgentHandle disposer，teardown（client 断连或 fiber dispose）时执行它，替换旧的 abort()+whenIdle() drain；session/load 与 teardown 竞态时把刚 resume 出来的 handle 先 dispose 再抛；新增断言 agent 已注销 + session 已移除断开、重载日志验证 closing turn/end 落盘、兄弟隔离等测试；更新各 README。

裸断连后不再残留"已 idle 但仍注册"的 agent 与 store 条目；handle disposer 内的 queue-aware cancel 同时关掉了 pre-step best-effort 窗口，使 teardown 达到真正 quiescence。

SessionStore 用 prepare（校验+构造不入库）/enter（attach onAppend+入库存）/announce（emit session/created）替代 createOwned 的兄弟 effect 模式；AgentLoop.start 构建单个复合 effect，按序 yield：session-detach → register → stop-and-await agent.done；LIFO disposal 以有序链方式运行每个 disposer 的 promise。新增 mid-turn dispose + 重载断言 closing 事件为真实 disposed 而非恢复的 interrupted 的耐久性测试。

更强的耐久性测试发现原双兄弟 effect 设计在裸 fiber-unload 路径上会丢掉 loop 的 closing turn/end——fiber 用 Promise.all 并发 dispose 兄弟 effect，session-create 的 detach 与 loop 最终 flush 竞争。折叠为单 effect 后无论走 handle dispose 还是 fiber unload 都保证有序 teardown。

.agents/skills/dsh-code-review/SKILL.md 的"Test quality"检查项扩展。

明确 100% 覆盖只证明行被执行，不代表功能按发布形态工作；reviewer 应从"回归是否会失败""是否驱动真实路径而非伪造输入"两个轴评估，并点名 happy-path 测试覆盖了本应为 mid-flight/error 场景代码的陷阱。

packages/agent/src/index.ts 把 agent/disposed 的 emit 包进 try/catch + logger.warn（store 条目在 emit 前已删，状态已捕获，继续即可）；新增注册 throwing listener 后断言 session 仍被移除的回归测试；并在 dsh-session README 记录新的 prepare/enter/announce 有序 teardown 原语。agent/created 的 emit 故意保持不隔离（其抛出用于回滚注册）。

Codex review 发现的 teardown 泄漏——复合 effect 的 disposers 以 .then() 链运行，register disposer 内未隔离的 agent/disposed emit 若被 throwing listener reject，会跳过后续 session-detach disposer，导致 session 残留且 onAppend 仍 attach。

BashExecRequest 加可选 owner?: string，解析后的 BashExecSpec 加必填可空 owner: string | undefined（像 workdir/timeoutMs 一样在 spec 上必填，忘传会显式 undefined 而非被忽略）；resolve() 透传；新增 BashExecutor.ownerOf(id) 单一读取 seam；bash-local 在 TrackedTask 上存 owner 并实现 ownerOf；更新 StubExecutor 测试与 README；删除旧的所有权 RFC 文件。

后台任务的所有权需要能在 consumer HMR 重载后存活；所有权存在 executor 的 task 上（随 dsh-bash fiber dispose），因而能扛 tool-bash 的 HMR 重载，访问策略留给 consumer（dsh-tool-bash）。

删除 packages/tool-bash 中 plugin-local 的 taskOwner: Map<string, Agent>；owner 改为在 spawn 时通过 resolve({ …, owner }) 盖到 executor 的 task 上（key 为 session.header.id）；bash_output/bash_kill 的访问控制和完成通知都改读 token；新增 RFC 2026-06-18-agent-lifecycle-and-ownership-seams.md；更新 README 与测试。

让 ownership 在 tool-bash HMR 重载后存活（关闭 XXX(tool-bash-owner-hmr) 缺口），并修正原本测试 fake 因只填 header.id 而通过错误路径的问题。

packages/tool-bash/tests/tools.spec.ts 给完成通知的 fake 注册一个 agent-<sessionId> 的 agentId，与 session token 不同。

Codex review 指出原 fake agent.id === session.header.id，无法区分代码按 agentId 还是 session token 匹配；修正后测试真正钉住「按 session.header.id 匹配」这一区分性行为。

packages/agent-loop/src/agent.ts 在 arming marker 时捕获 reason ?? 'cancelled' 并通过 LoopHandle.cancelReason() 暴露；loop.ts 两个 marker 分支改用它；更新 packages/acp/src/codec.ts 与 index.ts 的 session/cancel 映射注释；改 cancel.spec.ts 断言 caller reason。

原本 marker-only 窗口（step-start、continuation gate）硬编码 reason: 'cancelled'，丢了 caller 传入的 reason；修复后 turn 提前结束时记录的 reason 与中段路径一致。

将 origin/worktree-cancel-primitive 合入 worktree-agent-handle，带入上面 cancel(reason) 的代码与测试。

把 cancel primitive 的修复向上合到 agent-handle 分支。

packages/acp/README.md 与 src/index.ts 中 quiesce() 注释把「queue-aware cancel」措辞改为实际的 disposed 路径描述。

review 指出 AgentHandle.dispose() 实际委托给 start-disposer 的 stop(); await agent.done（设置 disposed 并 abort 当前 controller），并不调用 agent.cancel()，turn 中段以 disposed 结束而非 aborted；文档需对齐实际机制。

将 origin/worktree-agent-handle 合入 worktree-bash-owner-token，带入 ACP/agent-loop/session 的 cancel、dispose、文档修正。

把 agent-handle 分支的修复整合到 bash-owner-token 分支。

AGENTS.md § Type Safety and Documentation 增加一条：文档写当前状态（what + why），不写 process/history（禁用 previously/now/used-to/replaces 等措辞）；并修正「tests document behavior」例子中对 summary 审计的夸大表述（后端其实写过 JSONL sidecar 和 SQLite updated_at，只是没有 consumer 和 update() 调用）。

review 发现两处问题：缺少明确的「当前状态」文档约定；worked example 与历史事实不符。

将 origin/worktree-drop-session-summary 合入 worktree-persistence-coordinator，带入 AGENTS.md 文档约定更新。

把 drop-session-summary 分支（含文档约定）整合到 persistence-coordinator 分支。

packages/session-persistence/src/coordinator.ts 在 ownerless-claim 分支 seed 检查之前加 cwd 相等性检查；共享 coordinator-contract 测试新增三个用例（跨 cwd 不能 claim cursor-0、不能 claim loaded-prefix、no-cwd 不能被 cwd'd session claim）；补 materialized flag 由来的说明，并把模块文档改写为当前状态。

review 发现跨 cwd 漏洞：原本只校验 seed 前缀，未比对 tracked header 的 cwd 与 live session 的 cwd，导致 /b 的 live session 能 claim /a 的 ownerless artifact 并把事件追加到错误 header 下；此为 coordinator 级不变式，对两个后端都适用。

将 origin/worktree-persistence-coordinator 合入 worktree-cancel-primitive，带入 cwd 校验和 AGENTS 文档。

把 persistence-coordinator 分支的修复整合到 cancel-primitive 分支。

packages/agent-loop/src/loop.ts window 2（同步 agent/status('running') listener 的 cancel）镜像 window 1 的处理：清 marker 后只有无新排队时才 setStatus('idle')，否则继续跑 queued replacement；新增回归测试复现该交错；更新两份 ACP RFC 把 session/cancel 描述从 agent.abort() 改为 queue-aware agent.cancel()。

review 指出 window 2 无条件 setStatus('idle') 会让 whenIdle() waiter 在 replacement 还排队未跑时就 resolve，caller 观察到错误的 quiescence；修复后 waiter 只在 replacement turn 的 running→idle 时 resolve。

将 origin/worktree-cancel-primitive 合入 worktree-agent-handle，带入 window-2 竞态修复、cwd 校验、AGENTS 文档。

cancel-primitive 分支向上合到 agent-handle 分支。

packages/session/src/index.ts 的 SessionStore.enter() 重新加上 duplicate-id throw 并补 prepare/enter/announce 生命周期测试；packages/agent-loop/src/index.ts 的 startOwned memoize disposal promise；packages/acp/tests/dispose.spec.ts 和 packages/session/tests/session.spec.ts 新增回归测试。

deep review 的两个阻塞性 lifecycle 问题：(1) enter() 是跨包 public primitive，caller 可在 prepare() 与 enter() 间插入任意工作，必须重新检查 id 以防 stale prepared session 覆盖 live 同 id entry；(2) AgentHandle.dispose() 直接返回 cordis effect disposer，第二次调用会立即返回而不等在飞 teardown，违反所有 caller 共享同一 quiescence 边界的契约。

将 origin/worktree-agent-handle 合入 worktree-bash-owner-token，带入 enter() id 检查、dispose memoize、cancel/persistence 修复。

把 agent-handle 分支全部修复整合到 bash-owner-token 分支。

packages/acp/README.md 把任务隔离描述从 object-identity 改写为 session-token 模型；packages/tool-bash/src/index.ts 模块文档按当前状态重写；新增 proposed RFC 2026-06-20-unify-agent-and-session-id.md（提议 agent 即其 session、一个 id），并从 agent-lifecycle RFC 的 precondition 处交叉链接。

review 指出 README 仍是旧的对象身份叙述；同时 notice 按 session.header.id 路由但 registry 只强制 agent.id 唯一，存在理论上的误路由（ACP 不可达），与其加 invariant 不如用 RFC 从构造上消除该 precondition。

packages/session-persistence/tests/coordinator-contract.ts 模块文档改写为描述「每个 scenario 在此定义一次、经 fixture 按 backend 运行」，而非叙述「以前在 per-backend specs 里重复」。

遵循 repo 的 doc-current-state 约定，不在注释中写 process/history。

packages/agent-loop/tests/cancel.spec.ts 模块文档去掉「PR C」字样，只描述测试套件测什么。

遵循 doc-current-state 约定，当前树里没有 PR C 可锚定。

packages/acp/tests/dispose.spec.ts 的 disconnect-mid-prompt 测试注释去掉「PR D's per-agent AgentHandle teardown」中的 PR 字样。

同上，描述机制本身而非引入它的 PR。

packages/tool-bash/tests/tools.spec.ts 两条 ownership 测试去掉「the old design fenced by Agent object identity」「closing the old XXX(tool-bash-owner-hmr) gap」等历史叙述，改为陈述当前契约（按 session.header.id 隔离；token 在 executor task 上，tool-bash 重载后保留）。

遵循 doc-current-state 约定。

AGENTS.md 的 doc-current-state 约定增加显式条款：永远不要在 comment、JSDoc、test name 中命名不可见的 change unit（PR/commit/stack position），要描述机制本身。

review 发现既有约定虽禁了 process-narration 措辞，但没显式覆盖「(PR D's teardown)」「(PR C)」「identity no longer matters」这类引用，需补一条明确条款。

将 origin/worktree-drop-session-summary 合入 worktree-persistence-coordinator，带入 AGENTS.md 的 change-unit 禁令。

把 drop-session-summary 的文档约定更新整合到 persistence-coordinator 分支。

将 origin/worktree-persistence-coordinator 合入 worktree-cancel-primitive，带入 coordinator-contract 文档当前状态化与 AGENTS change-unit 禁令。

persistence-coordinator 分支向上合到 cancel-primitive 分支。

将 origin/worktree-cancel-primitive 合入 worktree-agent-handle，带入 cancel.spec.ts header 修正与 coordinator-contract 文档修正。

cancel-primitive 分支向上合到 agent-handle 分支。

将 origin/worktree-agent-handle 合入 worktree-bash-owner-token，带入 cancel/dispose 测试中 PR-letter 引用的清除和 coordinator-contract 文档修正。

把 agent-handle 分支的文档清理整合到 bash-owner-token 分支，使整条 stack 对齐 doc-current-state 约定。

合并 PR #66 worktree-drop-session-summary。移除 packages/session/src/types.ts 中的 SessionSummary 类型，删除 jsonl/sqlite 两个后端中相关的写入/更新字段与 schema、format 代码；瘦身 contract、persistence、ACP load 测试；更新 architecture.md、各 README；新增 RFC 2026-06-19-drop-mutable-session-summary.md。

SessionSummary（mutable、由后端写入但无 consumer 也无 update() 调用）是 dead state，整体移除以简化持久化层。

无内容合并，仅将 origin/master 同步进 worktree-persistence-coordinator。

开 PR #67 前先把 feature 分支与主干对齐。

从 session-persistence-jsonl 和 session-persistence-sqlite 两个后端抽出一个共用的 coordinator.ts（新增约 578 行 + 契约测试 786 行），大幅瘦身两个后端实现与测试；新增 RFC、废弃旧的 mutable-session-summary 计划。

消除 jsonl/sqlite 后端重复的写入编排逻辑，统一到一处。

无内容合并，同步主干到 worktree-cancel-primitive。

开 PR #68 前对齐主干。

agent-loop 的 agent.ts/inbox.ts/loop.ts 加入取消原语（感知队列状态），新增 cancel.spec.ts（337 行）；更新 agent 类型、ACP 入口与 turns 测试、architecture.md。

为 agent 提供可正确取消在途/排队任务的公开能力。

无内容合并，同步主干到 worktree-agent-handle。

开 PR #69 前对齐主干。

agent-loop/src/index.ts、agent/src/index.ts、session/src/index.ts 引入 AgentHandle（每个 agent 的异步释放句柄）；ACP index 与 dispose 测试大改；resume/resume.e2e 适配。

让多 agent 场景下每个 agent 能独立、异步地释放资源。

无内容合并，同步主干到 worktree-bash-owner-token。

开 PR #70 前对齐主干。

bash、bash-local、tool-bash 的 types/src/index 注入 owner token；tool-bash 测试大改（+152/-）；新增 agent-lifecycle-and-ownership-seams RFC 与 unify-agent-and-session-id RFC。

bash 执行链路上携带调用者身份（owner token），为多 agent/多会话下的归属与生命周期打基础。

新增 scripts/verify-type-equiv.ts（208 行）与 scripts/type-equiv.manifest.json（中心化的 provenance 表）；doc-typecheck 识别 ts type-equiv fence 并跳过编译、不计入 opt-out 比例；接入 doc-sync 链。

让文档里逐字粘贴的类型定义能被 TypeScript parser 与源符号比对，防止文档与源码漂移。

新增 docs/core-data-structures/（core.md 定义"核心"边界 + llm-streaming/session/persistence/tools/bash 各 seam 子页），类型定义用 ts type-equiv 块逐字粘贴并漂移检测；从 architecture.md 交叉链接，development.md 记录机制。

系统梳理 agent-loop 脊椎及其周边 seam 的核心数据结构，作为单一权威参考。

AGENTS.md 加一条常驻规则；dsh-code-review skill 加硬阻断检查。

凡是新增/删除/重塑目录中记录的类型，必须在同一 diff 内更新目录（prose + verbatim 块 + manifest）；verify-type-equiv 只能查漂移，查不到"新类型未文档化"。

在 docs/rfc/proposed/ 下新增 20 个简化 RFC（assembled-assistant-messages-only、classify-support-packages、collapse-trace-only-session-events、drop-acp-session-load、drop-bash-output-spill-files、generic-tool-rendering、retire-mid-turn-steering 等），更新 RFC README。

集中提出一批"可删/可合并"的候选简化项，供评审排程。

新增 docs/acp-feature-support.md（163 行），盘点 ACP v1 面（stable schema 1.14.0 + claude-agent-acp/codex-acp 参考适配器的不稳定特性），逐项标注 dsh-acp 桥的进度，并给出排序的 gap 摘要。

明确 ACP 桥相对参考适配器的覆盖与缺口。

对前述 20 个 RFC 逐篇修订（措辞、范围、结论），顺带修 publint-all.ts。

根据评审反馈定稿这批 RFC。

verify-type-equiv 改为扫描整个 markdown glob 范围（原先只扫 manifest 已命名的文档，孤儿块会被静默跳过），并支持 abstract class；persistence.md 补全 has/delete；AGENTS.md doc-sync 概要补回两个门禁。

堵上 1:1 保证的漏洞，让任何文档里的未登记 type-equiv 块都能被捕获。

汇总 PR #71 内容（前述 core-data-structures 文档 + verify-type-equiv 门禁 + AGENTS/code-review 规则）到主干。

将文档脊柱与漂移检测门禁正式落地。

docs/acp-feature-support.md 调整若干状态标记（session/close ⚠️→❌、Codex plan ⚠️→✅、Codex elicitation ✅→⚠️），限定"两个适配器都发货"的措辞，删除末尾多余的 </content> sentinel。

按评审核对修正 checklist 的状态与措辞。

将 checklist 从 docs/ 迁到 packages/acp/acp-feature-support.md 并重写相对链接深度；doc-typecheck/verify-md-wrap/verify-md-links 的 glob 从 packages/*/README.md 放宽到 packages/*/*.md，AGENTS.md 同步描述。

让 checklist 与其所属桥包同处；并使包级非 README 文档也纳入 drift 门禁。

同步主干到 worktree-acp-feature-checklist（有 AGENTS.md 冲突已解决）。

开 PR #73 前对齐主干（此时主干已含 PR #71 的文档/门禁）。

汇总 ACP checklist（迁移到 packages/acp、修订状态、放宽 doc-sync glob）到主干。

将 ACP 桥特性清单正式落地。

在 agent/llm/session/system-prompt/tools 五个声明事件的包里，给全部 24 个 harness 事件加 @mode emit|waterfall|parallel 标签并补自包含 JSDoc。

让生成的 cordis 目录能直接从源码渲染每个事件的模式与说明。

新增 3 个 RFC（drop-unconsumed-llm-block-views、drop-unconsumed-registry-change-events、prune-dead-seam-methods），修订 public-agent-stop-surface；顺带在 acp/bash-local/tools 的实现里做配套小改（标记未消费视图/事件）。

把评审中产出的有价值简化项归档进 RFC 体系。

新增 scripts/gen-cordis-catalog.ts（458 行）生成 docs/cordis-catalog/events-and-services.md（482 行），覆盖每个 cordis 事件（含 @mode）与 ctx.<key> 服务接口；带 --write/--check 新鲜度门禁；硬性校验缺失 @mode 或标签与签名矛盾（trailing next 即 waterfall）；删除旧的 verify-event-taxonomy，由 verify-cordis-catalog 接入 doc-sync；新增 RFC 与 ci/AGENTS/architecture 配套。

用生成器替代手维护的事件分类表，保证事件/服务目录与源码一致。

生成器的方法过滤器改为排除 private/protected/static（protected 是子类钩子，非公开 ctx 表面）；BashTaskRead 加入类型交叉链接映射；改写生成器模块注释与 AGENTS @mode 规则措辞（不再叙述已退役的 verifier）。

让生成的服务接口只反映插件作者实际可调用的公开表面。

新增 .agents/skills/dsh-find-simplifications/SKILL.md（106 行）及 agents/openai.yaml 配置。

提供一个可调用的 skill，用于主动发现仓库中可删/可合并的简化项。

调整 docs/rfc/ 下简化候选清单——删除 drop-unconsumed-llm-block-views、drop-unconsumed-registry-change-events、foreground-only-bash 等提案，新增 drop-unconsumed-llm-adapter-change-event、drop-unconsumed-llm-assembled-surfaces、generic-long-running-tool-runtime；更新 dsh-find-simplifications/agents/openai.yaml 与 RFC README 索引、若干 RFC 标题/分类。

根据简化评审意见收拢候选 RFC 列表。

新增 classify-packages-by-aspect.md 提案；更新 RFC README 索引、discover-package-inventory、remove-redundant-snapshot-log-goldens 等若干 RFC 的分类与交叉引用。

处理最新一轮简化评审反馈。

新增 proposed/2026-06-20-package-hierarchy.md；删除被取代的 classify-packages-by-aspect 与 classify-support-packages；调整 publint-all.ts 与 discover-package-inventory。

把分散的"包分类"思路统一收敛为单一 package-hierarchy RFC。

新增 implemented/2026-06-20-core-data-structures-catalog.md，回溯记录 PR #71 已落地但漏写 RFC 的 core-data-structures 目录与 verify-type-equiv drift gate——spine-vs-seam 范围规则、verbatim-match-over-assignability 选择、含 Codex 抓到的 scan-gap bug 修复过程；交叉链接到 generated-cordis-catalog RFC。

补齐缺失的已实现 RFC，使两份 catalog RFC 对称记录。

微调 proposed/2026-06-20-package-hierarchy.md 的示例措辞（9+/7-）。

澄清 hierarchy 示例表达。

合并 cordis-catalog 分支。新增 docs/cordis-catalog/events-and-services.md（481 行）与 scripts/gen-cordis-catalog.ts（464 行）源码生成器及其测试；新增 core-data-structures-catalog 与 generated-cordis-catalog 两份 RFC；删除旧 verify-event-taxonomy.ts；更新 agent/llm/session/system-prompt/tools 的类型导出与 CI/AGENTS 文档。

用源码生成的方式产出 Cordis 事件/服务目录文档，替换手工 taxonomy 校验。

Merge commit，把 master（含 PR #75 cordis-catalog、core-data-structures 目录、type-equiv gate、acp-feature-support 等）合入简化候选分支。

让 simplify-candidates 分支与最新 master 同步。

合并 codex/rfc-simplify-candidates 分支。新增 dsh-find-simplifications skill；批量新增/移动 20+ 份简化候选 RFC（drop-*、prune-dead-seam-methods、retire-mid-turn-steering、collapse-trace-only-session-events、discover-package-inventory、package-hierarchy、providerless-example-base 等）；packages/acp、bash-local、tools 做了支撑分类的小改动。

集中提交一批架构简化候选 RFC。

在 docs/rfc/{lifecycle}/ 下加第二维 class 子目录（feature/bug-fix/simplification/architecture/process/testing），目录即标签；把全部已有 RFC 迁移到对应 class 目录；新增 verify-rfc-classification.ts（校验 RFC 落在合法 class 目录且 README 索引匹配）和 verify-doc-refs.ts（校验 TS 注释引用的 docs/*.md 路径真实存在）两个 doc-sync gate；README 增加分类说明；新增 process/2026-06-20-rfc-classification.md 记录该方案。

用目录结构强制封闭分类集，替代解析式字段。

删除 knip.json 中无匹配的 examples/acp-agent/src/*.ts 入口；package.json 给 hygiene 加 --treat-config-hints-as-errors。

消除 knip 配置漂移，让未来 stale 入口直接 fail gate 而非退化成静默 hint。

合并 rfc-classification 分支（即 605587e + 8c16524 的结果）。

引入 RFC 分类目录结构与配套校验 gate。

新增 proposed/architecture/2026-06-20-branded-ids.md：把现有 Branded<B>（CallId/SessionId/AgentId）扩展到未加 brand 的跨边界 id（主要是 BashTask.id 的 bash-N 计数器、独立的 OwnerToken brand），并修复现有 brand 在 Map key/方法参数处退化为 string 的侵蚀；ModelId/ToolName/数字序号等明确列为延后项。

加强跨边界 id 的类型安全。

把 18 个 packages/<name> 迁入按职责分组的目录 core/、llm/、bash/、session-persistence/、ui/、support/；组目录是纯容器，包名保持 @deepseek-ai/dsh-*；把每包独立的 tsconfig paths 合并成 @deepseek-ai/dsh-* 通配符；更新所有深度耦合配置（workspace、tsdown、vitest、eslint、knip、tsconfig includes/refs、生成器、type-equiv manifest）和测试中跨包相对导入；修复 doc-typecheck 用 regex 解析 JSONC 的 bug（改用 TS API 正确解析含注释的通配路径）。标注 WIP：doc 交叉链接和包/RFC 文档待更新。

落地 package-hierarchy RFC，把扁平包按职责分组。

Merge commit，把 master（含 PR #76 rfc-classification）合入 package-hierarchy 分支。

分支同步最新 master。

新增 proposed/architecture/2026-06-20-extract-example-app-packages.md：让 examples 目录变薄——每个 example 主要调用一个 app package；共享 dsh-agent-core bundle 拥有 providerless spine；dsh-stdio-agent、dsh-acp-agent app package 内置各自 front-door cluster（UI + logger/hmr policy + agent 预创建），把 ACP stdout 纯度 footgun 变成 artifact 属性；leaf cordis.yml 缩到 backends + config，start.ts 由 package bin 取代。取代 providerless-example-base RFC。

提出 example 提取为 app package 的架构方案。

修正 branded-ids.md 三处——SessionStore.get(id: string) 非可选（仅 create/prepare 接受可选 id）；ACP brand-erosion 描述扩展到 bySession WeakMap、loadingIds Set、streamSessionEventUpdate(sessionId) 签名；代码路径用 bare inline code span 而非 markdown 链接，符合其它架构 RFC 的 house style。

修正 Codex review 指出的不准确之处。

合并 RFC-classification 重组后，批量改写所有漂移的 packages/<name> 交叉链接（Markdown 链接目标、移动后 README 相对深度、.ts 注释/字符串中的路径）到 grouped 路径；新增两个 gate——verify-package-paths.ts（标记指向已 MOVED 包的 stale packages/<path> 引用，但放过指向不存在包的前瞻性提案）和扩展 check-workspace-constraints（断言 packages/<group>/<pkg> 深度-2 形状、组目录无 package.json）。

修复重组带来的链接漂移，把这次的人工检查自动化为 gate。

合并 worktree-branded-ids-rfc 分支（即 ae5a908 + bf3cfe8 的结果）。

合入 branded IDs RFC。

对 extract-example-app-packages RFC 自审后修正三处——agent-loop 放置（core bundle 转发 agents 列表为自身 config 默认 []，而非硬编码 []，反驳了 base-core.yml 当初把 loop 排除出 core 的理由）；timer 通用且 stdout 安全，应进共享 spine（只有 logger + hmr 是 app-specific）；model/systemPrompt 落点因 app 而异（stdio 落到预创建 agent、acp 落到 bridge plugin），由各 app package 自己的 Config 路由。

让 RFC 与实际源码严格一致。

给每个组目录（core/llm/bash/session-persistence/ui/support）加 README 说明角色和 product-vs-support 分类；重写 packages/README.md 围绕 hierarchy（组表、grouped "what goes where"，删除 package-hierarchy FIXME）；把 package-hierarchy RFC 移到 implemented/architecture/ 并改写为已发布描述（放置理由、paths 通配符与 publint 去重、两个新 guardrail gate）；把剩余 tsconfig.build.json references 去重并入 discover-package-inventory 提案；更新 AGENTS.md（重组 repo-layout map、depth-2 globs、新增 verify-package-paths gate、agentic-coding 时代倾向更严 lint 的说明）。

最终落实 package hierarchy 并把 RFC 标记为已实现。

Merge commit，把 master（含 PR #77 branded-ids RFC）合入该分支；docs/rfc/README.md 有冲突。

分支同步最新 master。

git mv 把 providerless-example-base.md 从 proposed/ 移到 rejected/architecture/（保留历史）；把 supersede 注记折叠成一行 rejected Status——extract-example-app-packages RFC 取代它（spine 移到 dsh-agent-core、base*.yml 删除后无共享 base YAML 可重命名）；更新 README 行与交叉链接。

正式拒绝被新方案取代的旧 RFC。

合并 worktree-rfc-extract-example-app-packages 分支（即 034779d + d9c9c5d + 94a7626 等的结果）。

合入 example-app-packages RFC 系列。

自审 implemented/architecture/2026-06-20-package-hierarchy.md 每个事实声明与已发布分支对照（hierarchy tree、无组 manifest、两个 tsconfig 的 dsh-* 通配符、publint glob、显式 build references、两个新 gate）；把 paths-wildcard bullet 措辞改为当前状态；记录 doc-typecheck JSONC 解析微妙点（通配符引入的），防止未来编辑重新引入 regex 注释剥离 bug。

让已实现 RFC 描述与事实严格对齐。

Merge commit，把 master（含 branded-ids RFC、extract-example-app-packages RFC、providerless-example-base rejected）合入 package-hierarchy 分支；docs/rfc/README.md 有冲突。

分支同步最新 master。

两个 RFC（branded-ids.md、extract-example-app-packages.md）的包路径由旧的扁平 packages/<name> 改写为分组布局，并修正交叉链接指向 implemented/architecture/。

#79 合并带入的两个 RFC 仍引用旧路径，verify-package-paths 和 verify-md-links gate 报错。

将扁平 packages/<name> 大规模重组为 packages/<group>/<pkg>/ 分组结构（232 文件，+1357/−877）。新增 verify-package-paths.ts gate，更新 tsconfig、scripts、catalog、knip、AGENTS.md 等。新增 2026-06-20-package-hierarchy.md RFC。

把 packages 按模块域（core/llm/bash/session-persistence/ui/support 等）分组，建立可扩展的模块层级。

新增 docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md（154 行）并在 README 索引登记。

为 LLM provider API 不稳定（限流、抖动、瞬时错误）场景提出恢复策略 RFC。

新增 docs/rfc/proposed/policy/2026-06-21-mandatory-app-attribution-headers.md（81 行）并在 README 索引登记。

提出要求所有 app 请求携带归属 header 的策略 RFC。

删除 LlmService.streamBlocks()/generate()、llm/generate waterfall、GenerateResult、llm/adapter-change 事件（含声明和 emit）、以及 BlockAssembler 的 flushReady/flushRemaining/result 切片；adapter 测试改用 stream()+BlockAssembler 的 assemble.ts helper；落地 AGENTS.md「RFC 是提案而非金科玉律」原则；两个 RFC 移到 implemented。

生产唯一消费者（agent loop）只用 stream()，其余是投机便捷面；无人监听的 registry-change 事件无价值。

修正 LlmService 类 JSDoc 为单 streaming 面；从 gen-cordis-catalog.ts 的 LINK_MAP 删除已移除的 GenerateResult；adapter-change RFC 验收条件改指 verify-cordis-catalog；删除已同义反复的「streaming/one-shot 一致」property test。

PR1 review 发现的文档/catalog 漂移。

删除 SessionPersistence.has()/delete()、coordinator 的 has/delete/deleteCore、PersistenceBackend.deleteStored hook（含 jsonl/sqlite/in-spec 实现）；删除 BashExecutor.get(id)/list()；测试改用基于 onTaskDone 的 doneFor(id) helper；更新 seam README 为 4 方法持久化面。

无消费者编程的抽象方法不是 seam，而是每个实现都得提供的投机性 surface。

更新 core-data-structures/{persistence,bash}.md、sqlite README 与源注释（移除 has/delete/get/list）；doneFor 懒挂监听器替换为 trackCompletions——setup 中预先挂载一个监听器记录所有完成，已完成的任务立即 resolve。

doc-sync gate 不覆盖的文档漂移；原 helper 在任务已结束后才挂监听会错过完成事件而挂起。

从 branded-ids.md 和 generic-long-running-tool-runtime.md 两个 proposed RFC 的 BashExecutor seam 描述中去掉 get/list（保留 resolve/run/start/ownerOf/readOutput/kill/onTaskDone）；trackCompletions 改为无条件记录每次完成并唤醒等待者，第二次 doneFor(id) 也能 resolve。

二轮 review 防止 prune 落地后这些 RFC 读起来过时；修复 helper 边缘。

恢复 BashExecutor.get()/list() 及其 LocalBashExecutor 实现、bash 测试用例，删除 doneFor/trackCompletions 脚手架；persistence 的 has()/delete()/deleteStored 删除保留；RFC 重命名为 persistence-only 并加实现说明记录 bash 回退理由。

bash get/list 各是一行 accessor，移除后需 ~35 行 onTaskDone 跟踪脚手架替代一行 ctx.bash.get(id)；按「RFC 是提案」原则，测试 harness 本身就是 seam 消费者，迁移成本不合理。

新建零依赖类型包 @deepseek-ai/dsh-brand（packages/util/brand）；mint BashTaskId/OwnerToken 并贯穿 BashTask.id、get/ownerOf/list/readOutput/kill seam、bash-local 生成点、tool-bash 校验面；agent-loop Config 在源点 brand（agents[].id: AgentId、resumeSessionId: SessionId）；将 CallId/SessionId/AgentId 传播到 registry/store Map key、公开参数、ACP 表面、persistence coordinator 等。

类型层修复 branded-id policy 两个 gap，并修正依赖方向——通用 capability 包不得耦合 LLM/session 词汇；dsh-bash 只依赖 dsh-brand。

从接口与 ReactLoopAgent 实现移除 Agent.abort()；空队列 abort 测试改用 cancel(reason)，两处 review-fixes 测试直接驱动私有 currentAbort 字段；保留 whenIdle()。公开停止面收敛为 cancel() + whenIdle()。

无生产消费者用 abort()（ACP 用 cancel()，owner 用 dispose()，loop 内部直接 abort per-step controller）；实现发现 whenIdle() 是 load-bearing 的 quiescence primitive（有 ACP 测试消费者、有替换-turn race 契约），RFC 提案移除它是错的。

docs/architecture.md 删除公开 abort() 行；cancel.spec.ts 模块注释、acp/src/index.ts 的 resume-leak 注释把 abort() 改为 cancel()；public-agent-stop-surface RFC 移到 implemented/simplification 并加实现说明（记录 whenIdle() 保留理由）；AGENTS.md 添加 abort/whenIdle 作为「RFC 是提案」的具体例证；重新生成 catalog。

Codex no-ship 是文档/完整性 gap 而非 loop 行为问题。

docs/architecture.md、extension-cookbook.md（正文 + ts 注释）、acp-agent-client-protocol.md 的 lifecycle 段：teardown 表述改为 await AgentHandle.dispose()，明确 whenIdle() 只是观察 quiescence 而非 teardown。

之前的 doc fix 把一个错误 primitive 换成另一个；真正的 teardown 是 disposer 的 stop(); await agent.done + 注销，cancel()+whenIdle() 会重新引入孤儿 agent/session 泄漏。

token usage 改挂在 assistant/message 的可选 usage 字段；max-tokens 截断路径改为空内容 assistant/message { content: [], usage }（deriveMessages 跳过空内容）；operational error 的 step 号挂到 turn/end.reason 的 kind:'error'；failTurn 直接设置 reason；未 bump format version（pre-release v1 不变）；重录 ACP fixtures/goldens；RFC 移到 implemented。

两个独立 trace-only 事件不是 load-bearing 记录，事实应折进邻近的 load-bearing 事件以减少事件词汇膨胀。

仅修改 2026-06-21-unstable-llm-api-recovery.md（+86/−37）。

收紧该 RFC 的适用范围，避免过度触及无关面。

修正 whenIdle() 自身 JSDoc（agent/src/types.ts、agent-loop/src/agent.ts）、agent/README.md、core-data-structures/core.md、ACP RFC 两处：disposer 不调 whenIdle()，而是 stop(); await agent.done；非 owner 观察用接口级 agent.whenIdle()；重新生成 catalog。

teardown 表述错误比之前三处更深——whenIdle() 的契约文档本身错误地声称 teardown 会 await 它。

whenIdle() JSDoc（types.ts）、core.md、catalog：删除「closing ACP connection」的引用，替换为真实的非 owner 观察者（await 一轮 settle 的测试、monitor），并明确 owner 不需要 whenIdle()（dispose 已 await loop-exit）。

review 发现 JSDoc 引用的 ACP 例子与代码不符——ACP 实际 own handle 并通过 dispose teardown，从不调用 whenIdle()；只有测试是真实消费者。

仅修改 2026-06-21-unstable-llm-api-recovery.md（+12/−4）。

与并行的 sibling PR 保持 RFC 描述一致。

仅修改 2026-06-21-unstable-llm-api-recovery.md（+4）。

在 RFC 中说明正在并行进行的实现栈，便于评审跟踪。

删除所有 session.golden.jsonl；每个 model 场景至多保留一个 session.jsonl，既作 replay 源又作期望日志；新增 fixtureContext helper 对 fixture 自身做归一化（避免录制的 stale cwd 泄漏）；快照比较两侧各自归一化后用 normalized-string toEqual 而非 toMatchFileSnapshot（不会覆写）；authored 场景（error-finish、cancel）的期望日志放 session.jsonl；required-fixture guard 改为按 kind；ACP-snapshot-tests RFC 更新为缩减后的 fixture 集并移到 implemented。

录制场景下 session.jsonl 与 golden 字节相同，纯重复；减少 fixture 维护面。

仅修改 2026-06-11-property-based-testing.md（+1/−1）。

ordered-prefix 契约和 streaming/one-shot usage 一致性早已随 flush/generate API 一并消失；改为枚举 property suite 实际断言的内容（blocks() 数 ≤ distinct index、幂等重组、blocks 不抛并产出合法 tag、finish 反映最后 finish chunk）。

新增 packages/util/README.md（group README）；packages/README.md 添加 util/ group、dsh-brand 包与依赖图节点，并修正「无 harness 依赖」的过时声明（dsh-llm/dsh-bash/dsh-session/dsh-agent 均依赖 dsh-brand）；根 AGENTS.md Repository Layout 加 util/brand；branded-ids RFC 对齐实际 shipped 状态（Branded 在 dsh-brand，dsh-bash 只依赖该 util 包）。

新建 packages/util/brand/ 后产生的顶层 util/ group 此前未被任何层级文档枚举。

docs/rfc/README.md 索引行从「persistence and bash seams」改为「Prune dead methods from the persistence seam」；重写 prune-dead-seam-methods.md 正文为持久化决策记录形态（Problem/Proposal/criteria/risks 仅描述 has/delete 移除，bash reasoning 折进顶部「considered and deliberately kept」决策说明）；删除陈旧 bash 源行引用，保留指向当前代码的 persistence 消费者链接。

bash 回退后 RFC 仍以 both-seams 框架描述，与实际 shipped scope 不符（verify-rfc-classification 只校验路径被索引，文案漂移逃过 gate）。

集中 SESSION_FORMAT_VERSION 常量（dsh-session，pin 0），由 Session 构造默认值、SessionStore.prepare 头部两处写入点和 coordinator 的 load-time assertVersion 共同读取；非 0 log 在 load 时被拒绝（不迁移）；所有测试/fixture/doc 中当前写入的 header 改为引用该常量，版本拒绝测试的 bad 值改为 99；AGENTS.md 记录 monotonic（SQLite SCHEMA_VERSION）与 pinned-0（session log）两种 pre-release 立场；failTurn 在 turn 已关闭后用 ctx.logger.warn 记录 late throw（而非无效赋值），并加回归测试；normal-step assistant/message append 加 content-or-usage guard（与 max-tokens 分支一致）。

trace-event 折叠改变了持久化 SessionEventMap shape，按 policy 必须 bump 版本并由 backend 拒绝旧 log（pre-release 下保持 v0、任何非 0 即拒绝）；late turn-end throw 不能消失到无效赋值；空内容空 usage 的 step 不应留 trace-only 行。

把 trace-only session event 折叠（agent-loop/loop.ts、session types/index、各类 session.jsonl snapshot、相关测试）合并进 PR6 分支；带冲突解决（多个 snapshot golden/jsonl）

将"折叠 trace-only 会话事件 + 锁定 SESSION_FORMAT_VERSION=0"的工作向下传递到 PR6

session index.ts/README、agent-loop loop.ts JSDoc、persistence/collapse-trace RFC、acp-feature-support.md 等多处文档与注释

上一修复遗漏的文档/注释漂移——版本号实为 0 非 1、独立的 usage/error 事件已不存在、措辞需对齐 pinned-v0 立场

把上一条文档同步修复合并进 PR6

使 PR6 也带上 PR5 的 doc-sync 修正

新增三个包——dsh-agent-core（加载无 provider/executor/UI 的主干 bundle）、dsh-stdio-agent（终端聊天 APP + bin）、dsh-acp-agent（ACP server APP + bin，无 stdout logger）；删除各 example 的 start.ts 与 base.yml/base-core.yml/acp-tail.yml；boot glue 移入各 app bin；新增 keyless 真实加载路径测试；更新 RFC/文档/模块图

消除每个 example 的厚模板（手写 start.ts、infra 前导、嵌套 include、靠散文维系的前门集群），让每个 example 变成薄叶子 cordis.yml；将 stdout-purity footgun 在结构上从 ACP 叶子中隔离

把 trace-event 折叠 + agent-loop/session 相关改动一并合并进 PR7

将 PR6 的工作向下传递到 PR7

重写 coding-agent README 插件表为当前四个叶子条目；为 agent-core/stdio-agent/acp-agent 三个新包加显式 export-shape 守卫（断言无 default 导出且 Loader.unwrapExports 不破坏 name/Config/apply）；软化 agent-core/acp-agent README 与 RFC 中"结构上不可达"的过度断言

修复抽取重构 PR #88 评审发现的三类问题——文档陈旧、缺少对缺 inject 时 export default 会静默丢导出的守卫、措辞夸大

acp-agent/src/index.ts 模块注释把"footgun 从叶子结构上不可达"改为"app 不给默认前门留 logger 条目"

叶子仍可能加 sibling logger 条目，原措辞不实；改写为准确表述

.github/workflows/ci.yml 把 "Demo smoke test" 从已删除的 examples/echo-agent/start.ts 改为调用 pnpm run demo:echo，断言不变

抽取重构删除了 echo-agent/start.ts，导致 CI 在 node 24/26 失败；通过 canonical demo 脚本避免再次漂移

两 bin（stdio/acp）在 loader.create() 后加 await ctx.loader.await() 等整树就绪、传 config 的绝对 file:// URL；boot() 加 assertEntriesLoaded() 让 fiber-less 条目 fail loud；main() 加 unhandledRejection guard（installFailLoud）；新增 built-bin.e2e.ts（用真实 lib/bin.js 在临时消费目录跑 node，验证 echo/ACP + stdout 纯度 + 缺目录/缺文件 fail-loud）；架构文档为 dsh-agent-core 依赖具体 loop 开 COMPOSITION 例外；snapshot fixture 守卫要求所有场景都有 session.jsonl

BLOCKER——发布的 lib/bin.js 之前只经 tsx 验证，未在 plain node 下被守护；修正 boot settle race、配置路径鲁棒性、静默 load 失败，并把"真实入口路径=已发布 artifact"纳入测试

examples/acp-agent/tests/acp.snapshot.ts 的 per-kind fixture 守卫及注释

no-model 场景其实也需要 session.jsonl（harness 无条件传给 llm-replay，缺失则 loadReplayScript 抛错）；守卫与注释对齐现实

把 snapshot-goldens 分支合并进 extract-examples 分支（空合并）

把移除 snapshot golden 的工作并入 extract-examples 链

AGENTS.md 新增 "## Orchestrating review feedback across a stacked PR chain" 章节（一 worktree 一分支、修复落在引入 PR 再向下流、review-fix 独立提交不 amend、委托工作须 trust-but-verify）；"## Conventions" 加 "Never rewrite a pushed branch" 规则；扩展 "Line coverage is not behavior coverage" 两条推论（export-shape 守卫需断言坏形状会失败；真实入口路径指已发布 artifact 而非 tsx dev runtime）

把 7-PR 简化栈两轮评审中习得的教训固化为文档

scripts/verify-package-paths.ts 跳过任何含 lib/ 段的引用（doc-sync 在 build 前跑，无 lib/）；acp built-bin smoke 改为从 ui/acp 包 URL 解析 zod/@agentclientprotocol/sdk（acp-agent 不声明它们）

新 built-bin smoke 的 lib/bin.js 引用被误判为陈旧源漂移；pnpm 严格布局下 acp-agent 解析不到 zod，导致 CI built-bin 步骤失败

public-agent-stop-surface RFC 把"活跃消费者（ACP bridge 的 settle 点）"改为 ACP/agent 测试通过公共 seam 等待结算

packages/ui/acp/src 实际没有 whenIdle() 调用（bridge 走 AgentHandle.dispose），原说法不实

docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md 措辞

harness 无条件把 session.jsonl 传给 llm-replay，no-model 场景也必需；代码已如此，对齐 RFC 文字

把 agent-stop 分支（agent.ts、agent types.ts、agent stop-surface RFC 等）合并进 trace-events

把"公开 agent stop 表面"工作并入 trace-events 链

把 trace-events + agent-stop 一并合并进 snapshot-goldens（同 f09a88ecee 的改动集合）

把 trace-event 折叠 + agent-stop 向下流入 snapshot-goldens 链

进一步把 snapshot-goldens（含 trace-events/agent-stop）合并进 extract-examples

把累积的简化分支汇入 extract-examples 链

把 extract-examples（及其已合并的 snapshot-goldens/trace-events/agent-stop + built-bin/verify-package-paths 修复）汇入 lessons-learned 汇总分支

把整条简化栈汇总到 lessons-learned 分支

两 app bin 的 assertEntriesLoaded() 改为过滤 fiber === undefined && !entry.disabled（disabled 条目按设计无 fiber）；stdio built-bin smoke 加 disabled 条目配置仍能 boot 的用例；verify-package-paths 的 lib 跳过限定为 packages/<group>/<pkg> 之后段，避免误放过陈旧无 group 的 packages/acp-agent/lib/bin.js

disabled:true 条目是合法"插件关闭"而非坏导入；lib 无条件跳过会漏掉真正漂移

把上一条修复（disabled/lib-scope）合并进 lessons-learned

把评审修复带入汇总分支

合并 prune-seam 分支（prune-dead-seam-methods RFC），解决 RFC 文档冲突

把"修剪死 seam 方法"工作并入 branded-ids 链

合并 branded-ids（含 prune-seam）——branded-ids RFC、AGENTS.md Branded 规则、packages/util/README、prune-seam RFC

把 branded-ids + prune-seam 向下流入 agent-stop 链

把 agent-stop（及其已合并的 branded-ids/prune-seam）合并进 trace-events

累积简化栈继续向下游 trace-events 流转

把 trace-events（含 agent-stop/branded-ids/prune-seam）合并进 snapshot-goldens

完成整条 prune-seam → branded-ids → agent-stop → trace-events → snapshot-goldens 的 merge-forward 链

Merge worktree-simplify-snapshot-goldens → worktree-simplify-extract-examples；解决 AGENTS.md 冲突，带入 branded-ids / prune-dead-seam-methods 两条 RFC 笔记与新增的 packages/util/README.md。

在 extract-examples 特性分支上同步相关简化工作的结果。

Merge worktree-simplify-extract-examples → worktree-lessons-learned；带入同一批 AGENTS.md / RFC / packages/util 文档更新。

在 lessons-learned 分支上累积前面一串 simplify 工作的成果。

删除 packages/llm/llm 中 assembler/index/types 的死代码（净减约 277 行），同步 llm-deepseek / llm-pi-ai 的 assemble 测试拆分，更新 catalog、architecture、README。

清理 LLM seam 上无人消费的 adapter-change 事件和 assembled 调用表面，收敛公共表面积。

常规回合并，仅更新 docs/rfc/.../2026-06-11-property-based-testing.md 一行。

让特性分支跟上 master。

从 session-persistence / jsonl / sqlite 的接口和 coordinator 中删除不再使用的方法，新增 RFC 2026-06-20-prune-dead-seam-methods.md，更新 contract 测试。

移除持久化能力 seam 上未被调用的方法，保持 seam 精简。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

新增 packages/util/brand 工具包；在 bash / bash-local / tool-bash / core (agent-loop、agent、session) / llm / ui-acp 等多处把裸 string id 改为 branded 类型，并补 tsconfig 引用与 type-equiv manifest。

让跨边界 id 成为 Branded<B> 不透明类型，防止 brand 在传递中被悄悄丢失。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

从 packages/core/agent 类型与 agent-loop 实现中移除未被调用的 Agent.abort()，保留 whenIdle()；更新 architecture、core-data-structures、cookbook 及对应测试，新增 RFC 2026-06-20-public-agent-stop-surface.md。

收敛 Agent 的公共停止表面，只暴露实际被消费的 API。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

在 packages/core/session 与 agent-loop 中合并冗余的 trace-only 事件类型，重写相关 spec，重新生成所有 ACP 快照（multi-turn、tool-call-turn、workspace-edit 等的 session.jsonl/golden）。

去除只为 trace 存在的事件，把 usage / error 信息并入真正承载功能的事件流。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

删除各 snapshot 目录下冗余的 session.golden.jsonl，改由 session.jsonl 单独承担；扩展 acp.snapshot.ts 比较逻辑，更新 RFC 与快照 normalize。

去掉重复的 golden 副本，简化快照产物。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

新增 packages/core/agent-core、packages/ui/acp-agent、packages/ui/stdio-agent 三个包承载原 examples 中的应用主干与 bin；删除 examples 下散落的 start.ts / base*.yml，改造 acp-agent / coding-agent / echo-agent 的 cordis.yml 与 e2e，新增 verify-package-paths.ts。

把 example 中重复的应用装配逻辑提炼为可复用包，examples 回归为薄壳。

回合并，仅更新 property-based-testing RFC 一行。

让特性分支跟上 master。

仅改 AGENTS.md，新增 14 行关于 stacked-PR 编排流程和真实入口路径选择的教训。

把 lessons-learned 分支的踩坑经验沉淀进 AGENTS.md。

新增 packages/subagent/ 组（dsh-subagent 提供 SubagentService 注册表 + Provider/Run 词汇 + start/end 事件，dsh-tool-subagent 提供模型可见的 subagent 工具）、packages/support/subagent-mock 脚本化测试 provider；写 RFC 2026-06-21-subagent-capability-seam.md，接入 tsconfig、catalog、module-graph。

为「agent 委托子 agent」建立命名 provider 注册表 seam，使 in-process / ACP / 未来 A2A 等多种传输能共存。

对 subagent start|end 事件加 emitContainedStart/End（避免抛错泄露子 agent），把 dsh-tool-subagent 工具名改为可配置（Config.toolName，默认 subagent），补齐 per-file 100% 覆盖率用例，新增 docs/core-data-structures/subagent.md 并登记 type-equiv。

处理首轮 Codex review 的四项问题：泄露、重名、覆盖率缺口、文档缺失。

把 subagent start/end 事件的异常容错从「整个 emit 一个 try/catch」改为通过 ctx.events.dispatch 逐个 listener 调用并各自收容；测试改为注册两个 listener（第一个抛错）验证第二个仍能收到事件。

遵循 AGENTS.md 的 callback-boundary 规则，避免一个坏订阅者饿死后面的监听器。

撤销 AGENTS.md、docs/development.md、2026-06-11-doc-sync-enforcement.md 和 pnpm-lock.yaml 上 rebase 误带入的改动。

让分支只保留属于自己的改动，剔除 rebase 串入的内容。

Merge master → feat/adr0016-type-build-check，巨大合并（365 文件）：带入 master 上 packages 按 group（bash/core/llm/ui/session-persistence/support 等）重组、examples 抽包、大量 RFC 重新分类归档以及新增 verify-type-equiv.ts / verify-rfc-classification.ts / verify-doc-refs.ts / gen-cordis-catalog.ts 等脚本。

把 type-build-check 特性分支 rebase 到当前 master 形态，以便后续基于新包结构落地 ts 构建配置。

调整 agent-core / acp-agent / stdio-agent / brand / bash 等新包的 package.json 与 tsconfig.json、tsdown 配置，统一根 tsconfig.json 的构建引用。

让前一合并带入的新包符合 adr0016 的 ts 构建配置约定。

把 2026-06-17-ts-build-config.md 移到 rfc/implemented/process/，微调 adding-a-package.md、eslint 配置，扩展 check-workspace-constraints.ts。

修复合并后遗留的约束 / lint / 死链问题，让门禁恢复绿色。

仅改 docs/rfc/implemented/process/2026-06-17-ts-build-config.md，把其中描述的 packages 层级对齐到当前 RFC。

让该 RFC 与实际的 packages 分组结构保持一致。

新增 dsh-subagent-spawn（通过 ctx.agents.create 造全新子 agent，独立 session，默认继承父 model）与 dsh-subagent-fork（以父 agent 已完成 turn 的前缀作为 seed 造子 agent，继承上下文）；扩展 CreateAgentOptions.seed、AgentOptions.subagentDepth；在 coding-agent 示例接入 spawn 后端与 subagent 工具。

落实 subagent 能力缝（capability seam）的第二条 PR，让同一 cordis context 上可运行父子 agent，复用 agent factory 的 quiescent teardown。

恢复源码中相对导入的显式 .ts 扩展符；启用 rewriteRelativeImportExtensions 让产物 JS 用 .js、声明保留显式 .ts；全仓 vendored/loader/llm/core 各包源文件批量调整扩展符；新增 scripts/verify-node-next-types.ts（160 行）作为 NodeNext 声明消费方闸门；CI 与 build 配置同步。

解决 NodeNext 下声明文件相对导入扩展符缺失的回归，建立可机械检查的闸门。

subagent-spawn/src/in-process.ts 的 readResult 改为只扫描子 agent 自身事件（seed 前缀之后），取消队列前映射为 aborted；修正 SubagentRun.id 文档（是 agent id 非 session id）；刷新 coding-agent welcome 串与 TODO(sub-agents) 旧文；补两条红→绿回归测试。

修两个合并阻断 bug：pre-turn cancel 被误判为 error、fork 子无消息时返回了父 seed 的最后一条 assistant/message。

in-process.ts 在结果路径开头检查 request.signal?.aborted，已 abort 则直接 settle aborted 不跑子 agent；补回归测试；更新 subagent RFC 与 unify-id RFC 中已过时的 "deferred" 措辞。

request signal 在 run 开始前就 abort 时 addEventListener 不会触发，后端 bridge 会漏掉而把子 agent 跑到 completed。

GenerateOptions.sessionId（Branded）打在模型请求上，由 agent loop 设置；dsh-llm-replay 按 session 加载父日志 + 每个子日志、按首次调用顺序绑定 live session↔recorded script；快照 harness 收集所有 .jsonl 并以 session.jsonl/session.<n>.jsonl 写回；acp-agent 示例接入 subagent seam，新增 subagent-spawn、subagent-multi 两组真实 API 录制的无密钥快照场景；新增 testing RFC。

原快照层是单 session 单游标，无法确定性重放或收割子 session 日志；解决 TODO(subagent-snapshots)。

仅注释/RFC 文本——把 replay sort 与 harvest sort 的 "tie-safe" 注释改为真实不变量陈述：当前同步场景下 sibling 的 createdAt 严格递增、与首次调用顺序一致；id tiebreak 仅让退化碰撞确定性；XXX(concurrent-subagents) 标注未来并发场景需要真正的 first-call 序号。

修正 review 指出的过度声称，记录已知限制；无行为变更。

39 个测试/源文件的导入扩展符批量调整（恢复/对齐到本仓当前约定）。

对 07f4047ff0 路线的回退或对齐——按当前 RFC 重新落地 .d.ts 解析策略。提交标题以 "revert:" 标注，由 imccyu 提交。

改 docs/rfc/implemented/process/2026-06-17-ts-build-config.md、scripts/verify-node-next-types.ts、tsconfig.json 三处文档/配置。

让 RFC 文本、验证脚本与 tsconfig 与当前 rewriteRelativeImportExtensions 实际行为一致。

大合并（docs/architecture、cordis-catalog、core-data-structures、postmortem、RFC 大量重排）。关键实质：采用 master 的折叠 usage 字段（assistant/message.usage）并重新挂载 surface metadata；surface opts 接到 master 新的 max-tokens append；surface 列表移植到 coordinator 重构后的 SQLite 新路径，丢弃 v1→v2 migration（按 pre-release bump-and-reject）；session-surface RFC 移到 implemented/architecture/；重生成 cordis catalog；重新收割 ACP 快照 fixture 带 surface 元数据。

让 session-surface 特性分支与 master 的包重组、折叠 usage、persistence coordinator 等改动对齐。

新增 dsh-subagent-acp——每次 run spawn 子进程，harness 作为 ACP client（与 dsh-acp server 方向相反）走 initialize/newSession/prompt，dispose kill 子进程并等退出；最小 client stub（无 fs/terminal capability、累积 agent_message_chunk、按策略自动答 permission）；StopReason→结果映射；credential 形态的环境变量被 scrub，子 agent key 仅经显式 config.env 透传；ENOENT spawn 错误被捕获与 ACP drive 竞速。测试：mock ACP server 子进程的无密钥集成（含 cancel 竞态、permission、非消息更新、spawn 失败、HMR）+ 真实 acp-agent 进程的 with-key e2e。

证明 subagent seam 能推广到进程外后端，完成 PR1→PR2→PR2.5→PR3 的 seam stack；留在 @agentclientprotocol/sdk 0.25.1（0.28.x 只 deprecate 当前 API，本后端无需其新特性）。

新增 packages/fs/ 下四个包——fs（Service Definition）、fs-local（fsio.ts + 本地 provider）、tool-fs（read/write/edit 三个工具）、相应 README/tsconfig/pnpm-lock；新增 filesystem 能力缝 RFC 与 filesystem tool schemas RFC；docs/module-graph、cordis-catalog、architecture 同步。

按 Service Definition/Provider/Consumer 角色补齐文件系统能力缝并提供模型可见工具。

合并 07f4047ff0 那条 "Use explicit ts specifiers for NodeNext-safe declarations" 到主干，即统一全仓 .ts 扩展符 + NodeNext 声明闸门。

通过 GitHub PR #93 落地显式 ts 扩展符约定。

改 docs/cookbook/adding-a-package.md（22 行）与 docs/rfc/.../2026-06-20-package-hierarchy.md（2 行）。

让 "添加一个包" cookbook 与当前 ts-build-config（lib/types 产物布局）一致。

subagent-acp/src/run.ts dispose 改为：关 stdin（graceful ACP close）→ SIGTERM → grace 内未退则 SIGKILL，并 await 确定 exit（grace 经 spec.disposeGraceMs 可调，镜像 bash executor 的有界 teardown）；startAcpRun 在 request 已 abort 时返回 inert already-aborted run 不 spawn；mock 加 trap-ready 信号；cancelled flag 移到 holder 对象避免 TS 控制流窄化。

修两个生命周期问题——dispose 只发 SIGTERM 可能永久挂起（孤儿化子 agent 持有的 bash 等）；已取消的请求仍去 spawn 配置的二进制。

dispose 改为三级阶梯——stdin EOF 后先等子进程自然退出（tier 1），再 SIGTERM（grace），再 SIGKILL；新增 exitsWithin helper；mock 新增 MOCK_FLUSH_ON_EOF（异步 flush marker 后自退）与 MOCK_IGNORE_EOF 模式，tier-1 测试 proven RED on same-tick SIGTERM。

原 dispose 同 tick 关 stdin + 发 SIGTERM，子进程 EOF 驱动的 quiesce（含持久化 flush、停子 bash）来不及跑，导致中途被杀、flush 丢失、孤儿 bash。

仅 docs/development.md（2 行）。

让开发文档中 CI gate 描述与实际 gate 列表一致。

(A) 拆出独立 disposeEofGraceMs（默认 6000ms）——因为子 acp-agent 的 EOF teardown 会停它自己持有的 bash，而 SIGTERM-trapping 的 bash 孙子进程能占满 ~3s 才被自己的 SIGKILL，原 3000ms 与 dsh-bash-local 的 SIGTERM→SIGKILL grace 相等导致父 SIGTERM 正好撞上子的 SIGKILL+flush；tier-1 测试用超过 SIGTERM grace 但在 EOF grace 内的 flush（proven RED 当 tier 1 复用小 grace）。(B) 中档 SIGTERM 测试原来只断言 dispose 返回及时，无法区分 EOF→SIGKILL（跳过 SIGTERM 档）——mock 的 MOCK_IGNORE_EOF 现装 SIGTERM handler 并 touch marker 后退出，SIGKILL 不可捕获故移除 SIGTERM 档会缺 marker（proven RED）。

让有界 dispose 真正覆盖任意 ACP 子进程的嵌套 teardown 时长，并加固中档测试使其能区分阶梯被删。

合并 "Unified TypeScript Build and Config" RFC——declaration 产物移到 lib/types，types/exports/files 指向那里；全仓包 package.json/tsconfig.json 批量对齐；新增 scripts/check-workspace-constraints.ts（51 行）与 verify-node-next-types.ts；tsconfig.base/test/typecheck 重构；vendored 包同步。

统一全仓 TypeScript 构建与产物布局约定（ADR0016）。

新增纯库包 dsh-subagent-inprocess，把 startInProcessRun/depthOf/SubagentDepthError/InProcessRunOptions 从 dsh-subagent-spawn 搬过去（spawn 不再 re-export，fork 不再从 spawn 反向依赖）；coding-agent/cordis.yml 同时挂 spawn + fork + 两个 tool-subagent 实例（subagent→spawn、subagent_fork→fork）演示多 transport 纯配置即可。

让两个进程内后端互相独立——spawn 原本携带 fork-aware seeding 逻辑，fork 反向依赖 spawn。

把 #36（ADR0016 ts-build-config）的包级改动（package.json/tsconfig.json/产物布局）并入 subagent seam 分支；tsconfig.typecheck.json 冲突已解。

在 subagent seam 分支上同步 master 的统一 ts 构建配置。

把 pr1（含 pr1 之上已合并的 master 改动）并入 pr2 分支；同样主要是 package.json/tsconfig.json/tsdown 等 ts-build-config 对齐。

pr2 分支获取 pr1 + #36 的基线，便于后续在统一 ts 配置上继续工作。

subagent-inprocess、subagent-spawn、subagent-fork 三个包的 package.json（产物/exports 指向 lib/types）与 tsconfig.json 对齐新约定；加入顶层 typecheck tsconfig 的 references。

merge 把既有包迁到 lib/types，但这三个新包还是旧 lib/ 布局，需补齐到统一约定。

并入 pr2 的全部（含 inprocess 拆分、多 backend cordis 配置、ts-build-config）。

pr2.5（快照重放）分支获取 pr2 最新基线，包括拆出的 inprocess 包与统一构建配置。

新增 docs/core-data-structures/filesystem.md（145 行）；更新 docs/cordis-catalog/events-and-services.md、core-data-structures/core.md；scripts/gen-cordis-catalog.ts 与 type-equiv.manifest.json 同步以纳入 fs 类型。

为 5e01564afb 引入的 filesystem 能力缝补齐核心数据结构目录文档。

把 pr2.5（含 inprocess 拆分、按 session 快照重放、统一 ts 配置）并入 pr3（ACP 后端）分支；docs/module-graph.md 与 packages/subagent/README.md 冲突已解。

pr3 分支获取 pr2.5 基线，使 ACP 后端 PR 建立在已统一构建配置与快照基础设施之上。

新增 @deepseek-ai/dsh-compact 接口包，定义抽象 CompactService（ctx.compact，含 compactIfNeeded/compactRegion），通过 SessionEventMap 声明合并加入 compact/* 会话事件类型，并附 RFC；接入三个根 tsconfig 与 cordis catalog。

建立 compaction 能力 seam 的服务定义层，后端实现后续单独落地。

packages/subagent/tool-subagent 在注册 addEventListener('abort') 后立即复查 exec.signal.aborted 并显式 cancel；新增只对 cancel() 反应的 spy provider 回归测试。

abort 监听器对已 abort 信号不会触发，导致父步骤在工具运行前取消时子 agent 永远收不到取消，修复该边界（评审反馈）。

packages/subagent/subagent-acp 的 result 路径将 ACP drive 与 cancelSettled promise 竞速，请求 cancel 即令 result 置为 aborted；原先空的 broad catch 改为绑定并扁平化错误，经新 AcpRunSpec.onError 由 provider 上报到 ctx.logger.warn；新增 MOCK_IGNORE_CANCEL mock 模式与回归测试。

阻塞 bug——子进程忽略 cancel 或卡住 prompt 时父侧 result 永久挂起、子进程不退出，违反 SubagentRun.cancel() 契约（评审反馈）。

examples/acp-agent 的 cordis.yml 与 cordis.snapshot.yml 中再注册一个绑定 fork 的 dsh-tool-subagent，工具名 subagent_fork。

原先 demo 只把唯一的 tool-subagent 绑定到 spawn，fork 虽加载却对模型不可达，注释声称的「两种传输并用」并不成立（评审反馈）。

将 PR1（subagent 接口 + 工具桥 fix）合入 pr2 分支。

把 subagent 能力 seam 的第一层叠入后续 PR 的工作分支。

把 pr2 的内容合入 pr2.5 分支。

继续在子分支间合并前置 PR，维持堆栈链路。

把 pr2.5（含 acp-agent demo fork 修复与工具桥 fix）合入 pr3 分支。

把前两层叠进第三层 PR 分支，准备后续 fork/spawn 后端工作。

packages/fs/fs-local/src/fsio.ts 重写观测处理（约 105 行变动），更新 README、filesystem capability seam RFC 及 fsio/filesystem 测试。

对文本观测做安全校验，拒绝不安全的输入。

SessionHeader 新增可选 seedLength（继承自父日志的前缀长度），贯穿 CreateSessionOptions/CreateAgentOptions meta 并由 fork 后端打戳；JSONL header 行与 SQLite 新增 seed_length 列（SCHEMA_VERSION 2→3，按预发布策略拒绝旧版无迁移）；llm-replay 读取 seedLength 并在生成子脚本时跳过继承前缀。

fork 子会话的 .jsonl 以父事件开头，快照重放会把父的 recorded 响应当成子的模型调用而静默错路由；显式记录边界并跳过前缀修复此正确性缺口。

新增 subagent-fork（父完成一轮后 fork 一个子）与 subagent-mixed（同一 transcript 中 spawn + fork 各一次）两组真实 fork 子场景的 input/session.jsonl/stdout.golden；两个场景均要求 turn-1 完成以使 seed 前缀非空；更新 RFC。

seed-boundary 改动此前只在单元/持久化层验证，补齐端到端快照层的覆盖，且 subagent-mixed 首次在一个 transcript 内同时驱动两种 subagent 后端。

packages/session-persistence/session-persistence-sqlite 的 schema.ts 与对应测试改 SCHEMA_VERSION 至 3。

为即将到来的 session-surface 新列预留版本号（预发布期不接受旧格式）。

docs/rfc/implemented/architecture/2026-06-18-session-surface.md 单行措辞调整。

澄清 compaction 是在既有事件类型上走 replace 操作，而非新事件类型。

packages/core/session 的 index.ts、surface.ts、types.ts、README 与测试；更新 jsonl coordinator-contract、invariants 测试与 catalog 文档。

移除遗留派生回退，确立 surface 为唯一派生路径，简化并收敛语义。

packages/core/session/src/surface.ts 用 nodeBySeq map 替换原有查找并删除死参数；扩写 docs/core-data-structures/session.md；scripts/type-equiv.manifest.json 加条目。

提升 replace 路径的查找效率与清晰度，去掉遗留冗余参数。

packages/support/invariants/src/index.ts 新增校验：replace 的 sourceEventSeqs 必须覆盖它所遮蔽的每个 surface 节点；新增 90 行测试；更新 RFC 文档。

把 replace 的来源约束设为可执行的不变量，防止遮蔽了未被来源覆盖的 surface 节点。

把 session-surface（surface 唯一派生、replace 溯源不变量、SCHEMA_VERSION 3 等）合入 compact-interface 分支。

让 compaction 工作基于已收敛的 surface 派生路径。

packages/compact/compact/src/index.ts 的 seam 方法加上可选 cancellation signal；README、catalog 文档与 compact 测试同步更新（+33 行测试）。

使 compaction 支持中途取消，对齐其它能力 seam 的取消语义。

compaction capability-seam RFC 与 packages/compact/compact/README.md。

明确 compaction 对 surface 的变更必须在 compaction 锁保护下进行，避免并发竞争。

大型 merge，带入 master 上大量重构（包目录按 group 重组、agent-core/session-persistence coordinator、acp-agent/stdio-agent bundle、snapshot 测试体系、cordis-catalog 生成器、各类 RFC 重分类等）。

将 stdio/readline terminal 修复分支与上游 master 同步。

新增 docs/core-data-structures/compaction.md（46 行）；core.md 加索引、session.md 微调；scripts/type-equiv.manifest.json 加条目。

把 compaction 能力 seam 纳入 core-data-structures 目录编目，便于查阅。

docs/architecture.md、packages/README.md、packages/compact/README.md。

把 compact 包组与服务补进架构图与包清单，保持文档与代码同步。

packages/compact/compact/src/types.ts、测试、README、RFC 与 docs/core-data-structures/compaction.md 对齐为 shadowed* 命名。

让 compaction 的 summary 与 CompactionResult 字段命名一致（shadowed*），消除不对称。

合并 PR #90（worktree-subagent-seam-pr1）。新增 subagent（Service Definition）、tool-subagent（模型可见工具）、subagent-mock（测试后端）三个包及其文档/测试/catalog/RFC。

落地 subagent 能力 seam 的第一层：接口、mock 实现与面向模型的委托工具。

将上游 master 同步进 PR2 分支。

让 PR2（in-process spawn + fork 后端）与上游 master 保持一致，便于后续合并。

合并 PR #92（worktree-subagent-seam-pr2）。新增 subagent-inprocess、subagent-spawn、subagent-fork 三个后端实现及其文档/测试；更新 coding-agent/cordis.yml、agent-loop/agent 类型、llm-replay、knip 等。

在 PR1 的接口之上落地三种 subagent 后端实现（进程内、spawn 子进程、fork 父日志前缀子会话）。

将 origin/master 同步进 subagent seam PR2.5 分支，无内容冲突。

在 PR2.5 落地前把分支与主干对齐，便于后续 review/合入。

扩展 dsh-llm-replay 支持按 session 路由回放（packages/support/llm-replay），llm/types.ts 增加 session 维度，agent-loop 传入 sessionId；新增 subagent-spawn/subagent-multi 快照 fixture，更新 acp-agent snapshot harness。

让嵌套（in-process）subagent 的快照回放能区分父子 session，保证测试可重放。

将 origin/master 同步进 subagent seam PR3 分支。

PR3 落地前与主干对齐。

新增 packages/subagent/subagent-acp（含 README、run.ts、mock ACP server、e2e + spec），把 subagent 委托给外部 ACP 服务；更新 subagent README、knip/tsconfig、module-graph 等。

为 subagent 能力 seam 补上 out-of-process 后端，使 agent 可把子任务委托给独立 ACP 进程。

将 origin/master 同步进 subagent fork replay 分支。

fork replay 后续 PR 前与主干对齐。

session/types.ts 新增 seed 边界字段，session-persistence-jsonl/format.ts、session-persistence-sqlite/schema.ts（含 SCHEMA 调整）落盘；agent/agent-loop/subagent-inprocess/llm-replay 配合使用种子边界；新增 coordinator contract 测试与 RFC 笔记。

fork 出的子 session 需要在持久化层记住种子边界，恢复/回放时才能正确从父 session 切片重建。

将 origin/master 同步进 subagent fork scenario 分支。

fork 场景 PR 前与主干对齐。

在 acp-agent snapshot harness 新增 subagent-fork 与 subagent-mixed 两套 fixture（input/session.jsonl/stdout.golden），并补对应 RFC 测试笔记。

覆盖 fork 单独场景与 spawn/fork 混用场景，固化可重放输出。

将 session-surface（surfaceOp/sourceEventSeqs 作为唯一派生路径）与 master 的 worktree-subagent 系列（fork 种子边界 + ACP 后端）合并；解决 SQLite SCHEMA_VERSION 冲突（两侧都 2→3，合并为单一 v3 同时携带 seed_length、source_event_seqs、surface_op），agent-loop runStep 同时带 sessionId 与每-append 的 surfaceOp；subagent 快照 fixture 用无 key 确定性回放重新补充 surfaceOp。

两条并行主线（session surface 派生模型 + 子 agent 持久化）首次合流，保证两侧的字段与语义共存且测试全绿。

SQLite SCHEMA_VERSION 从 3 跳到 4（合并布局）以拒绝两个语义不同的 v3；session 在 append() 与 seed 构造处运行时守卫 surface 事件必须带 surfaceOp，导出 isSurfaceEligibleType；fixture 显式带 surfaceOp，补三类回归测试。

上一合并留下的两个隐患——版本号冲突误接受、无 marker 的 surface 事件会从 deriveMessages() 静默丢失——必须以严格版本号 + 运行时守卫堵住。

ui-stdio 开启 readline 终端行编辑能力，更新 .gitignore；bash-local/tool-bash 的测试与新增 readline.spec.ts 跟进。

让 demo agent 在终端里可正常行编辑（方向键、退格等），修复 codex 分支发现的 stdio readline terminal 问题。

把 session-surface 的全部工作（含上一条 SCHEMA v4 与 marker 守卫）并入 compact-interface；手工解决 docs/core-data-structures/core.md、packages/README.md、scripts/type-equiv.manifest.json、tsconfig.base.json、tsconfig.typecheck.json 冲突。

在 compact-interface 分支上承载 session-surface 的最新语义，让后续 compaction 改造基于 surface 派生模型。

将 origin/master（PR #61 的终端行编辑改动）同步进 session-surface 分支。

session-surface 落地前与主干对齐。

再次把 session-surface（已含 #61 改动）并入 compact-interface，无冲突。

把主干最新进度同步到 compact-interface，准备 compaction 基线落地。

新增 packages/core/project-instructions（index.ts + 单元/e2e 测试，共 ~360 行实现 + ~440 行 spec），agent-core 接入加载逻辑，更新 stdio/acp-agent bin、knip、tsconfig、module-graph，新增 RFC 笔记。

让 agent 启动时按层级加载项目指令文件（如 AGENTS.md/CLAUDE.md），把仓库约定注入 system prompt。

新增 packages/compact/compact-basic（index.ts 753 行 + 1361 行测试），定义 compaction Service Provider 基线实现；dsh-session 新增 step-boundary.ts（97 行）支持 step 对齐判定；更新 compact Service Definition、architecture/docs、coding-agent 接线。

把 compact-basic 分支多轮 review churn 压成一条干净基线，使后续 retention 重构以新历史起始而非叠加在修复之上。

新增 packages/core/tool-ask-user 与 packages/core/user-interaction（Service Definition + 实现 + 测试），ui-stdio 扩展交互能力（+146 行实现、+231 行测试），stdio-agent 接线；更新 architecture/module-graph/catalog。

提供 agent 主动向用户提问的交互工具与底层 user-interaction 能力 seam。

新增 packages/core/skill（425 行实现 + 342 行测试，skill 注册/加载/catalog）与 packages/core/tool-skill（skill 调用工具），agent-core/agent-loop/stdio-agent 接线；更新 docs。

让 agent 能发现并加载本地 skill（可复用提示/工作流），并提供模型可调用的 skill 工具。

新增 packages/core/session/src/surface.ts（159 行）与 surface 类型/测试；session/src/index.ts 改写消息派生为 surface 驱动；agent-loop 在每 append 带 surfaceOp；SQLite/jsonl persistence 与 invariants 测试跟进；重录大量 snapshot（multi-turn/tool-call/workspace-edit 等）。

把消息派生从直接扫日志改为基于 surface 链表的唯一派生路径，解决 replace/compact 等结构变更下的消息一致性。

compact-basic 重写（228 行净变化）——删除 in-flight-turn 保护，retention 改为统一的 tail→head 整单元扫描，唯一结构守卫是 step 对齐；auto-compaction 从 agent/request waterfall 迁到新的 agent/pre-request loop seam（在历史派生前触发）；resolveConfig 强制单次收敛不变量；新增 coding-agent compaction e2e；RFC 重写并移到 implemented/。

消除"单个超长 turn 撑爆窗口"的失败模式，并让 compaction 在 surface 派生前一次性生效，避免 listener 读到未派生消息。

新增 packages/compact/compact（Service Definition + types + 107 行 spec），定义抽象 CompactService；新增 core-data-structures/compaction.md、compact README、catalog 项、RFC 笔记。

为 compaction 建立能力 seam（Service Definition），使 compact-basic 等具体后端可按统一接口插拔。

新增 docs/i18n/terminology.md（110 行）。

为中英双语文档建立统一的术语翻译对照表，规范后续文档翻译。

把 step-boundary.ts 重命名为 tool-pairing.ts，用基于 surface 的 isToolPairingBalanced 替代按日志 seq 的 isStepAlignedStart/End；compaction seam 从 in-step 迁到新的 agent/pre-step（在 turn/start 后、step/start 前），dispatch 由并行改串行（@mode serial），catalog 生成器支持 @mode serial；新增 compact-loop-repro.spec.ts 与多组回归测试。

修复头锚定 compaction checkpoint 被按日志位置的 step 扫描误判为 mid-step、导致二次自动 compaction 静默失败的问题；并让 compact 记录落在任何 step 之外以满足崩溃安全。

compact-basic/src/types.ts 的 resolveConfig 把收敛边界从严格大于改为 >= 即拒绝（原先允许 summarizationMaxTokens + retainTokens == threshold），更新边界测试并新增"刚好低于阈值被接受"用例。

消除 compactIfNeeded 仅在 < threshold 时才 decline 与配置允许相等边界共同导致的"压实后历史正好卡在阈值、下一步立刻再触发"死循环。

更新 agent/agent-loop/system-prompt/compact/compact-basic 的 README 与 JSDoc、architecture.md、core-data-structures/compaction.md、已实现的 compaction RFC：统一表述为 serial agent/pre-step seam、tool-pairing balance 对齐判定、严格收敛边界；纠正原 RFC 关于"不改 dsh-session/dsh-invariants"的错误声明（dsh-session 新增 tool-pairing 谓词，dsh-invariants 移除 start <= end 的 replace 断言）。

使文档与上一对 CBR 修复（pre-step seam、严格边界、tool-pairing）实际代码一致，消除 review 发现的文档漂移。

examples/coding-agent/cordis.yml 一处注释，把旧的 agent/pre-request seam 名改成已发布的 agent/pre-step。

CBR-004 评审意见，对齐示例配置与实际发布的 seam 命名。

packages/compact/compact-basic/src/index.ts（修正 JSDoc，明确按 surface 顺序而非 log 顺序遍历）及对应 compact-basic.spec.ts（在 HMR-safety 套件里增加 mount/dispose/断言 ctx.get('compact') 为 undefined 的测试）。

CBR-005/006，纠正文档与 replace 后高 seq checkpoint 在 surface 头部这一事实的不一致，并补齐按名字才找得到的 disposal 测试。

新增 .github/workflows/mirror-to-gitlab.yml（33 行）。

把仓库自动镜像到 GitLab。

examples/coding-agent/tests/compaction.e2e.ts（缩小 contextWindow 到 2400、retainTokens 500、summarizationMaxTokens 300，fixture 扩到 6 个文件）；并同步 README、session types、core-data-structures 等处的文档（加入真实的 compact/start、compact/summary、compact/end 事件名，替换假设性的 compaction/marker 命名）。

CBR-007，原 e2e 峰值仅约 1389 tokens，始终低于 4000 阈值，从未真正触发 compaction；修正后能稳定命中并收敛。

合并入 origin/master（带入上一个 mirror-to-gitlab workflow）。

把 compact-basic-refactor 分支与 master 同步。

新增 RFC 与 dsh-file-context 包（types/window/policy），dsh-fs 收窄为带 branded FsTargetKey/FsVersion、FsWriteExpectation 的文本存储 provider seam；fs-local、tool-fs 全部适配；更新 architecture、cordis-catalog、type-equiv manifest、tsconfig.build。

实现 split-the-filesystem-seam RFC。授权改为基于 freshness：窗口化读取记录版本，文件未变时允许后续 edit，消除“读了大文件 100-150 行却无法编辑 120 行”的死路；editText 保持为 provider 原语以做 version guard + 字面量匹配 + 原子重写。

fs-local/src/fsio.ts 的 readWholeText/readForEdit 把读取中途的 AbortError 转成结构化 FsError('FS_ABORTED')；socket 类型探测测试在监听错误时 reject 而非挂起。

补齐读路径与流/写路径一致的 abort 错误处理，修复 unix-domain socket 不可用时测试 hang。

fs-local/src/fsio.ts 的 targetKey 解析改为 realpath 最近的已存在祖先再拼回缺失后缀；socket 探测测试在沙箱禁用时改为 skip。

让 symlinked 祖先下尚未创建的文件在创建前后拿到同一 key，保持 observed-state 在 write→edit 周期内一致。

file-context/src/index.ts 读取后再次 stat 记录 freshness token（文件消失则回退到 routing stat）；后端无 size 时改为流式读取；同步 cordis-catalog 链接到当前 filesystem API 符号。

使返回的 version 与返回的 bytes 一致，防止 routing-stat 与 read 之间的写竞争让后续 edit 误判 stale；size-less 后端不再整缓冲大文件。

新增 RFC docs/rfc/proposed/architecture/2026-06-24-web-capability-seam.md（385 行）及 README 索引。

提出把 web 访问做成一等 capability seam 的设计。

新增 dsh-web（ctx.web provider 注册表 + WebError 分类 + 注册序无关选择）、dsh-web-search-exa、dsh-web-search-perplexity、dsh-web-fetch-local、dsh-tool-web（仅拥有 model-facing web_search/web_fetch schema、prompt 段、HTML→markdown 呈现）；更新 architecture、knip、tsconfig.build、pnpm-lock；把 RFC 移到 implemented/。

把 web 访问做成 capability seam，工具 schema 稳定而后端可换；search/fetch 合为一个 seam，provider 按 namespace 插件注册（类比 LlmAdapter），工具注册跟随产品启用而非后端可用性。示例/应用配置此时尚未接线。

web-fetch-local 的 policy/provider——重定向目标在跟随前经 validateFetchUrl 复检；只有真正被丢弃的字节才算 truncation；按 Content-Type 声明的 charset 解码（不支持则 WEB_UNSUPPORTED_CONTENT_TYPE）；新增 docs/core-data-structures/web.md 与 type-equiv manifest 条目。

堵住重定向 URL 绕过传输卫生的口子，修正恰好等于 maxResponseBytes 时的假截断，正确处理非 UTF-8 编码。

Exa 与 Perplexity provider——在解析搜索响应体时保留 abort 错误，信号触发后 surface WEB_ABORTED 而非包装成 WEB_PROVIDER_ERROR；status() 用 URL.canParse 把畸形 baseURL 报为 misconfigured。

避免把 agent cancel/dispose 误报为 provider 故障，并让 selection 诊断与执行一致地提前发现配置错误。

web-fetch-local/src/provider.ts——body 读期间触发的 timeout 归类为 WEB_FETCH_TIMEOUT（通过 signal.reason 恢复）；每条被阻断的重定向 throw 路径（跨源、非法目标、缺 Location）先 cancel body；charset 校验失败也 cancel body。

兑现 WEB_FETCH_TIMEOUT 对停滞响应体的契约，避免被拒重定向的大/流式 body 泄漏 socket。

web-fetch-local/src/provider.ts 删除连续两块 JSDoc 中过时的那块，保留含 timeout-recovery 契约的准确版本。

清理重复且不准确的文档。

在根 tsconfig.json 注册五个 web 包（master 已改为 tsc -b tsconfig.json，弃用独立 tsconfig.typecheck.json），重新生成 module-graph 与 cordis-catalog。

把 web 包纳入 master 的项目图，让 catalog 反映这些包。

所有 web 包的 tsconfig.json 把 outDir 指向 lib/types，package.json 的 types/exports/files 改为 lib/types 声明 + lib/ bundle 形态（对齐 dsh-bash/dsh-tool-bash）；tool-web 的 subpath 从 lib/types/*.js 打包。

web 包原本按旧的 tsc 直出 lib/ 的单阶段布局编写，需迁到 master 的 tsc 声明到 lib/types + tsdown 打 JS 到 lib/ 的两阶段布局。

无 diff 的空提交。

占位/标记用提交，无实际内容。

把 master 合入 compact-basic-refactor 分支（无冲突文件列出）。

同步 compact-basic-refactor 与 master。

.github/workflows/ci.yml 给 Lint 步骤加 NODE_OPTIONS 8GB old-space 上限。

type-aware ESLint 通过 project service 加载所有包 tsconfig，峰值约 3.4GB RSS，默认 ~2GB V8 上限会 OOM（exit 134）；提高上限到 8GB。

packages/core/session/tests/surface.spec.ts 新增 39 行，直接测试 type-only 合格性检查、positive narrowing、非合格类型，以及 markerless-but-eligible 分支（surface.ts 第 46 行）。

满足 per-file 100% 覆盖率门对该分支的要求。

合并 PR #115，带入上一条 CI heap 提升 + surface.ts 覆盖率补齐。

修复 lint OOM 与覆盖率缺口，重新启用 CI。

把 master 合入 compact-basic-refactor，packages/core/session/tests/surface.spec.ts 有冲突并解决。

再次同步分支与 master（含 PR #115 的改动）。

按 file-context event-gate RFC 反转控制流——dsh-tool-fs 成为执行者，直接经 ctx.fs 读写、自己拥有 read windowing，并派发 fs/write-expectation、fs/edit-expectation（单槽 waterfall）加一次 fs/observed 发射；dsh-file-context 去掉 ctx.fileContext 服务，变成纯 event-gate 插件；provider 的 version guard 变为可选（window.ts 从 file-context 迁到 tool-fs）；新增 RFC、更新 architecture、catalog、type-equiv、README。

移除 tool↔policy 的 service-injection 耦合；仅加载 ctx.fs 即为完整的无约束文本存储 seam，移除策略插件只会优雅丢失策略而非在注入边界上崩溃。

修正 architecture、core-data-structures/filesystem、RFC、packages/fs/README、tool-fs/README 中的措辞。

纠正文档不实陈述——当前没有任何默认/示例配置接线 fs 工具（demo agent 通过 bash 做文件操作），文档不再声称“默认产品配置加载 dsh-file-context”，改为陈述“加载 fs 工具的部署应同时加载 dsh-file-context 以获得 read-before-write/edit”这一预期姿态。

packages/fs/tool-fs/src/edit.ts 在 model-facing prompt 中补入"编辑前需先读"的要求（含本会话已建/已编辑例外），与 write 工具一致；修订两份 RFC（fsspec-style-fs-seam、filesystem-tool-schemas），纠正过时的 ctx.fileContext 与"需完整文件状态"措辞，改为版本新鲜度表述。

避免模型仅通过 FS_NOT_OBSERVED 失败才学到读前置条件；同步 RFC 与已落地设计。

删除 packages/web/tool-web 的 ./search、./fetch 子路径导出及其 lib/*.js、tsdown 单独 override、search.ts/fetch.ts 中 plugin 形态导出，统一由根插件组合（重命名为 applyWeb{Search,Fetch}Tool）。更新 README/package.json。

无人消费的多入口是多余定制，还触发 workspace constraints 门禁；与同级 dsh-tool-bash 保持单入口一致，按 config 选择启用。

将 master 合入 fs-tool-clean 分支，含大量文件冲突解决（docs、tsconfig、catalog、subagent/compact 等新增包）。

把 fs 工具清理分支同步到最新 master，承接单 tsconfig 构建规范及 subagent/compact 等新引入的包。

packages/fs/tool-fs 适配 master 的单 tsconfig 构建约定（lib/types outDir + types path + files allowlist）；删除 /read、/write、/edit 子路径插件、bespoke tsdown、subpaths.spec.ts，改为根插件注册三工具，镜像 dsh-tool-bash。修订两份 file-context RFC 记录收窄后的范围。

消除唯一子路径导出包带来的特殊配置负担；统一构建形态，聚焦部署用例已无消费者需要。

packages/core/session/src/types.ts 增加 TodoItem 类型与 todo/write SessionEventMap 变体（整表快照、last-write-wins）；明确非 SurfaceEventType，不产生 LLM 消息。新增快照克隆、replay round-trip 等测试；docs/session.md、core.md（变体数到十二）、type-equiv manifest 同步。

为持久化、可重放的 UI 状态（待办列表）建立 session 事件基础，先于工具实现。

packages/core/session/src/types.ts 与 docs/core-data-structures/session.md 删除描述 Phase 2 消费者（todo_write 工具、stdio 打印、ACP plan 映射）的当前态表述，去掉错误的 @mode 标签（该事件走 session/event，非一等 Cordis Events）。

Codex Phase 1 评审修正——JSDoc 只描述事件自身契约，不预示未实现消费。

master 合入 web-capability-seam 分支；CI 增加 5 行，packages/core/session/tests/surface.spec.ts 增 40 行。

将 web 能力线分支与 master 同步，承接 surface 测试与 CI 更新。

新增 packages/todo/ 组与 @deepseek-ai/dsh-tool-todo：todo_write(todos:[{content,status}]) 整表替换语义，每次调用把完整列表作为 todo/write 事件追加到当前 agent 会话日志；单 owner（非 agent 调用被拒）；execute 在 schema 之外拒绝空/重复 content 和多个 in_progress。stdio UI 打印 glyphed 清单；ACP 桥映射为 plan sessionUpdate（todosToPlan 合成 priority）。接入 coding-agent、acp-agent、snapshot 配置与 system-prompt 提示。配套单元/集成测试、RFC、doc-inventory 扫描、TS 接线。

为模型提供结构化任务跟踪工具，复用既有 session/event 持久化与双端 UI 渲染路径。

packages/fs/tool-fs 将 window.ts+types.ts+formatReadOutput 合并为单一 read-render.ts（line windowing、FileReadOutcome、输出格式同属读渲染关注点）；删除 observe.ts，改用 ctx.emit 直接发 fs/observed（该事件契约上是同步、无副作用记录器，per-call try/catch 是为不可能场景做的防御）。read.ts 仅剩 schema + I/O。更新 fs 事件契约 JSDoc/README/RFC 为 fire-and-forget。

内聚清理——拆三文件无价值；删除针对已发布监听器不可能违约的防御代码。

把 tool-ask-user 从 packages/core/ 移到 packages/ui/；新增 docs/core-data-structures/user-interaction.md、docs/rfc/feature/2026-06-25-ask-user-question.md；扩展 packages/ui/acp/src/index.ts（+156 行）及 bridge.spec；acp-agent、stdio-agent 的 tsconfig/package 接线；catalog、module-graph、type-equiv 同步。

根据评审重组 ask-user 工具归属（移入 ui 组）并补齐 user-interaction 数据结构与文档。

packages/todo/tool-todo/src/index.ts 单行修改——toTodoList 之前按 trimmed 内容去重却存储原始 item.content，现改为存储 trimmed 后的 content。

保证持久化值与唯一性键一致，避免首尾空白导致去重与存储不一致。

master 合入 codex/ask-user-question 分支（解决 packages/README.md 冲突）；带入 session surface、compact 包、subagent 快照格式更新等大量内容。

将 ask-user-question 分支同步到最新 master。

master 合入 codex/project-instruction-files 分支；带入 compact 包、session surface、invariants/sqlite 测试扩展等。

将 project-instruction-files 分支同步到最新 master。

录制 examples/acp-agent/tests/snapshots/todo-plan/ 快照（真实 prompt 驱动模型调用 todo_write，golden 校验三条 priority=medium、status 1:1 的 plan sessionUpdate 及持久化 todo/write 事件），注册到 SCENARIOS 可无 key 重放；新增 examples/coding-agent/tests/todo-write.e2e.ts（真实模型调用落事件、校验单 in_progress 列表），并把 tool-todo 接入 e2e harness。

为 todo_write 提供端到端 transcript 快照与真实 API 验证，覆盖模型可观察行为。

packages/core/project-instructions 增 spec（+50 行覆盖配置分支），并在 agent-core、acp-agent、stdio-agent 的 spec 中各加用例；源码加 1 行（覆盖一分支）。

补齐 project-instructions 各配置分支的测试覆盖。

packages/todo/tool-todo/tests/tool-todo.spec.ts 加 10 行测试，断言输入 " plan the work " 被存为 "plan the work"；已验证对修复前代码会红。

为上一提交 e17c4b748d 的 trim 修复补回归测试（既有断言都用已 trimmed 的 todo，无法捕获回退）。

把 packages/core/project-instructions 整体迁移到 packages/prompt/project-instructions（包内容不变，调整 README、tsconfig.base/build、knip、AGENTS、architecture、RFC 中的路径引用）；spec 中 12 行测试相应调整。

按"prompt 组"归类重组，让 project-instructions 与其它 prompt 相关包同组。

新增 @deepseek-ai/dsh-web-search-deepseek（packages/web/web-search-deepseek/）：调用 DeepSeek 的 Anthropic-兼容 Messages API + 原生 web_search_20250305 server tool，解析结构化 web_search_tool_result 块为 ctx.web 的 WebSearchResult。命名空间插件（inject:['web']）无默认导出；严格模式——无 search 结果块则抛 WEB_PROVIDER_ERROR；复用 $DEEPSEEK_API_KEY，baseURL 默认 anthropic 兼容 base（不复用 $DEEPSEEK_BASE_URL）；snippet 来自 text-block citations，url 去重。两阶段 outDir 构建；接入 tsconfig/knip/module-graph；含 spec 与 with-key e2e。

为 ctx.web 能力线补上 DeepSeek 原生 web 搜索 provider。

packages/todo/tool-todo/src/index.ts 重排 14 行——registry 的 validateArgs 已在 execute 前拒绝非法 status，函数体内 status !== 'pending' && … → throw 为不可达死代码（第 70 行未覆盖，使 per-file 100% 门禁失败）。改为用 status as TodoItem['status'] 收窄 registry 保证的值，镜像 tool-bash（只查 DSL 无法表达的部分）。malformed-status 测试仍通过（走 registry 拒绝路径）。

消除不可达代码以恢复 100% 覆盖率门禁。

docs/i18n/terminology.md 重写——歧义术语保留英文（Cordis、fork、harness、schema、spawn、manifest、transcript、compaction、dispose）；CLI/Function Calling/HMR/fiber 首次出现加注；inference/reasoning 括注英文；memory 区分 记忆（agent 记忆）vs 内存（资源）；plugin→插件，新增 mod→模组 行；补充中英搭配说明（wire format、adapter contract）。

根据评审统一 i18n 术语表，澄清而非纯翻译歧义词。

AGENTS.md 新增"Run the CI gates locally BEFORE marking a PR ready"小节——给出 CI 等价的本地命令行，明确 pnpm run test:coverage（per-file 100%，CI 强制）而非 pnpm run test 才是门禁测试命令，并配 hygiene/snapshot/doc-sync。