@migor/agentia 0.10.3 → 0.10.5

package/CHANGELOG.md

@@ -5,6 +5,548 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.10.5] - 2026-11-05
+
+### 变更
+
+本版包含**可信边界收紧、可授权可对外暴露的生产宿主面、以及「顺序由代码定」的子循环**：
+
+- ⚠️ **行为变更（安全修）**：`POST /tasks` 的 `options` 只认 `traceContext` / `maxCostUsd` /
+  `maxTotalTokens`，**其余键一律 400 并点名**；身份与租户改由宿主新增的
+  `resolveRunOptions(req, { route, principal })` 按请求注入（`authenticate` 的返回值从此不再被丢弃）。
+  在 HTTP 的 `options` 里传过 `model` / `blackboard` / `maxIterations` 的调用方**必须改接法**，
+  迁移见下方该条目。
+- 新增**任务对象级授权** `authorizeTask`（poll / approve / cancel / event / stream 逐动作判定，
+  读任务快照不触发惰性推进）与**可信审批人** `resolveApprovalActor`（由 principal 生成 `decidedBy`，
+  覆盖请求体自报身份）；两者缺省不配 = 旧行为。
+- 新增 `responseMode: 'full' | 'public'` 与 `exposeTraceEvents`：把 trace 的**存储面**与
+  **HTTP 暴露面**分开 —— 对外服务可以不返回 trace / 任务 spec / 挂起历史 / `ownerId`，
+  而 `TaskStore` 与 sinks 仍保留完整记录。
+- 新增 `runCapabilityLoop(ctx, opts)`：顺序由**代码**定、但活不过这次请求的子循环；
+  配 `@Tool({ approval: 'required' })` 就能挂起等人批，且与调用方**同一棵** trace。
+- 新增**能力契约** `buildCapabilityManifest` / `app.getCapabilityManifest()` 与 CLI `agentia manifest`
+  （真装配、不调模型）；四类能力可标 `metadata.{owner,version,risk,sideEffect}`，
+  hash 覆盖描述 / schema / 审批 / 元数据且**与输入顺序无关**，可当 PR 留档的比较基座。
+- 挂起恢复的**预算按任务累计**（`TaskRecord.usageTotal` + 段内 `usageOffset`），恢复段的会话输入
+  随任务落库（`sessionInput`）；新增 `maxToolResultChars`，把「回模型的截断」与「记账的截断」
+  拆成两条**互相独立**的闸。
+- 新增 `docs/multi-replica.md`（三种拓扑 + 六个会坏的点 + 故障转移 runbook）与
+  `examples/super-agent` 多工单编排示例（按产物自己复算 trace 图，已纳入 e2e 门禁）。
+- 另含公共导出补齐（`parseTaskRecord`、`CLIENT_RUN_OPTION_KEYS`、`TaskHttpResponse`、
+  `CapabilityMetadata` 等类型面扩展），详细条目如下。
+
+### ⚠️ 行为变更（安全修）：`POST /tasks` 的 `options` 白名单化 + 宿主 `resolveRunOptions` 缝（2026-11-04 ref-run-options-trust-boundary）
+
+- **修的是什么**：`POST /tasks` 此前把 `body.options` **整体透传**给引擎，而它是
+  `RunInvocationOptions` 的全套旋钮。任何能调这个端点的人都能写
+  `{ blackboard: { tenant: '别人的租户' } }`，而 usage-guide §6.6 的多租户配额配方第一步正是
+  「用黑板存 tenant」⇒ 额度记到别人头上。同一件事在 `POST /run` 上却是**死路**（body 是 `RunInput`，
+  没有 options 入口）：需要身份的那条拿不到，拿得到的那条不可信。
+- **现在**：客户端只能设 `traceContext` / `maxCostUsd` / `maxTotalTokens`，**其余键一律 400 并点名**
+  （`blackboard` / `tools` / `model` / `fallbacks` / `priceOverrides` …）。身份 / 租户由新增的
+  `HttpHandlerOptions.resolveRunOptions(req, { route, principal })` 按请求注入 —— `authenticate`
+  的返回值从此**不再被丢弃**，作为 `principal` 传进该钩子（此前注释建议「存在钩子自己的闭包里」，
+  但闭包与 run 之间没有任何关联手段）。`/run` 与 `/tasks` 都过这条缝。
+- **合并语义（三条各不相同）**：`blackboard` **整体替换**（身份载体不允许与客户端键合并）；
+  `labels` 按键盘合并、服务端胜；预算与客户端值取**更严者** —— 上限不能由叫价方抬高。
+- **迁移**：若你在 HTTP 的 `options` 里传了上述按键之外的字段（例如 `maxIterations` / `model` /
+  `blackboard`），请求现在会 400。这些旋钮请改成应用级配置（`createApp` / `RunnerOptions`），
+  或由宿主在 `resolveRunOptions` 里注入。TS 侧 `TaskSubmitBody.options` 从 `RunInvocationOptions`
+  收窄为 `ClientRunOptions`，这类写法会**当场编译报错**。
+- **验证**：`tests/transport/http-run-options.test.ts`（9 例）+ `tests/transport/run-options.test.ts`（9 例）。
+  反向变异 4/4 咬住（放行未知键 / 上限取更宽 / 钩子结果不生效 / `principal` 不转交）；
+  实测读数：`options.blackboard` → 400 且任务表为空；宿主注入后工具方法体里读到的是
+  `tenant-of-u-42`（来自 `authenticate`）。决策：`docs/spec.md` §10 ref-run-options-trust-boundary。
+
+### 新增：`runCapabilityLoop(ctx, opts)` —— 代码控制顺序的子循环（2026-11-04 ref-run-capability-loop）
+
+- **补的是哪一格**：顺序由**代码**定、但活**不过**这次请求 —— `@SubAgent` / `@Skill` 的子循环审批挂不起
+  整条 run、`contextPolicy` 也不进子循环；`AsyncRunner` 的 task 能挂起能续跑，但要为它造一条任务记录。
+  中间这一格此前只能手写 `runAgentScoped` + 自己转发 `ToolRunContext` 的七个旋钮（漏一个是**静默**的）。
+- **形状**：`runCapabilityLoop(ctx, { name?, input, system?, tools?, model?, contextPolicy?, resultSchema?, onText? })`
+  → `{ text, typed, stopReason, iterations, spanId, error? }`。内部 `...forwardToolContext(ctx)` 取自唯一单源、
+  会 combine「放弃等待」信号、自建一个 `capability` span（**同树**，`runId` 不多一个）。
+- **配 `@Tool({ approval: 'required' })` 就能挂起等人批**：审批落在**外层工具调用**上，于是
+  「代码定顺序 + 子循环可裁剪 + 人批可挂起 + 同一棵树」四样可以同时要。
+- **刻意不导出 `runAgentScoped`**：它把「哪些旋钮必须下交」的责任交给调用方，而 TS 对漏写可选字段
+  不报错。公共面只给「不可能漏」的那个形状。`@SubAgent` / `@Skill` 的行为一个字没变。
+- **验证**：`tests/toolkit/capability-loop.test.ts`（5 例：同树 / `typed` / `contextPolicy` 生效 /
+  预算护栏经 ctx 透传 / 工具菜单不继承）。反向变异：去掉 `...forwardToolContext(ctx)` ⇒ 预算用例红。
+
+### 新增：`examples/super-agent` 多工单编排示例，并纳入 e2e 门禁（2026-11-03）
+
+- **示例形状**：Router 把一句目标拆成可并行工单，Worker 走 `AsyncRunner` 的 **task**（不是 `@SubAgent`）、
+  各自独立上下文；改数据的动作标 `approval: 'required'`，挂起等人批后恢复；四棵 trace 靠 `traceContext`
+  连成一条链。`npm run demo` 零网络、零 key、约 30ms 自检。
+- **门禁**：`scripts/e2e-examples.ts` 第 11 步（`verifySuperAgent`）按示例自己的 `npm run build` 构建，
+  再跑 dist 形态的 demo，然后**从它落的产物自己复算一遍 trace 图**（唯一的根 / 每条树几跳回家 /
+  哪条是恢复段），不转发 demo 的 `hopsTo` 结论。产物只在 `SUPERAGENT_DEMO_OUT` 指向文件时写，
+  交互式 demo 保持零副作用。`examples/super-agent/src` 同时进了 `tsconfig.tests.json`（类型层面也纳入门禁）。
+- **反向验证（三个变异 + 一个反方向探针）**：中和 demo 全部断言后 —— 去掉 Worker 的 `traceContext`
+  ⇒ 门禁红「每条 trace 都要沿 links 回得到 Router，断了的是 […]」；摘掉 `write_file` 的 `approval`
+  ⇒ 门禁红「要审批的工单应产生两棵 trace（挂起段 + 恢复段），实际 1」。反方向：实现不动、只让 demo 的
+  `hopsTo` 谎报一跳 ⇒ 门禁**仍绿**且自己算出 `worker-fix@2` —— 它算的是产物，不是文案。还原后 `sha256` 逐字节一致。
+
+### 文档：多副本部署参考架构（新增 `docs/multi-replica.md`）
+
+- **补的是哪一格**：`deployment.md` §8 此前只有一句话结论（「单宿主写者 + 认领语义不等于分布式锁」），
+  没有回答「那多副本到底怎么摆」。文档缺口会让每个接入方各自试错，而试错的代价是**同一任务跑两遍**。
+- **内容**：三种拓扑的选型判据（单副本 / 单机多进程 / 单写者+只读副本 / 按 `taskId` 分片）、
+  六个会坏的点（写路径交错、审批双派发、唤醒抢所有权、`cancel` 打不到 owner、跨进程 SSE、
+  定时任务每个副本各触发一次）、故障转移 runbook、粘性路由三种实现、多副本自检清单。
+- **一个此前没被写下来的陷阱**：`createHttpHandler` 的 `runner` 是可选的，缺省会造一个
+  `InMemoryTaskStore` 的 runner（`http.ts` + `async.ts` 两处缺省）。漏接线的副本表现为
+  「同一个任务 id 在 A 查得到、B 返 404」，**不报错也不告警**。
+- **如实标注的边界**：`approve` / `signal` 的互斥是**进程内**的（`#inflight` Map），
+  跨进程并发会各派发一次；`drain()` 是单向闩，停机后被拒的记录只能等下次启动认领。
+  这些是设计取舍，不是待修缺陷 —— 文档的职责是让部署方知道要自己兜。
+
+### 新增：任务对象级授权 `authorizeTask` 与可信审批人 `resolveApprovalActor`（2026-11-05 ref-http-task-authorization）
+
+- **补的是哪个洞**：`authenticate` 只回答「你是谁」，不回答「你能不能碰这个任务」。多租户宿主
+  此前只能在**每个**端点里自己查一次，漏一处的表现是「别人的任务能被取消 / 被批准 / 被读事件」。
+- **形状**：`authorizeTask(req, { action, taskId, task, principal })` —— action 取
+  `poll` / `approve` / `cancel` / `event` / `stream`，返回 `false` → 403，抛 `HttpException`
+  按其状态码回；审批与事件的判定发生在**读 body 之前**。缺省不配 = 旧行为（不拦）。
+- **为什么不走 poll 取快照**：它直接读 `runner.store.get`。走 poll 会让「查一次权限」触发
+  惰性超时判定与到期推进 —— 授权检查不该有副作用（`docs/spec.md` §10 该条有完整理由）。
+- **`decidedBy` 不再是自报字段**：配 `resolveApprovalActor` 后由 principal 生成并**覆盖**请求体；
+  返回 `undefined` = 不记审批人，空字符串算宿主配置错误（500）。不配则 `decidedBy` 仍只是
+  调用方填写的审计字段，不是可信身份。
+- **验证**：`tests/transport/http-authorization.test.ts`（五个动作 × 拒/过/抛错映射）+
+  `tests/transport/httpApproval.test.ts` 的可信审批人用例。
+
+### 新增：`responseMode: 'public'` —— trace 的存储面与 HTTP 暴露面分开（2026-11-05 ref-public-response-mode）
+
+- **补的是哪个洞**：trace 既是本框架的卖点，也是**信息泄露面** —— 它含工具入参出参、
+  任务 `spec.messages`、挂起历史与 `ownerId`。此前接对外服务只有「全关端点」或「全露」两个选择。
+- **形状**：`responseMode: 'full'`（缺省，历史形状）/ `'public'`；后者从 run / task 响应里去掉
+  trace、任务 spec、`suspendedMessages`、`ownerId` / `pendingEvents`，并**默认关闭** SSE 的
+  `trace.event` 帧。`exposeTraceEvents: true` 可单独开帧，但不会把完整 trace 加回 `run.end`。
+- **边界**：它只改 HTTP 输出 —— `TaskStore` 与 `TraceSink` 的记录**保持完整**（脱敏不是存储职责）；
+  也不能替代 `authorizeTask`，两者一个管「这条响应里有什么」，一个管「你能不能读这条任务」。
+- **单源**：公共投影只在 `http-shapes.ts` 一处实现，所有任务响应与 `task.end` 共用，
+  避免某条路由漏脱敏。验证：`tests/transport/http-response-mode.test.ts`。
+
+### 新增：能力契约 `agentia manifest` 与四类能力的 `metadata`（2026-11-05 ref-capability-manifest）
+
+- **补的是哪个洞**：多人协作时「这次 PR 到底改了哪个能力的哪个 schema」只能靠读 diff。
+- **形状**：`@Tool` / `@Skill` / `@SubAgent` / `@Prompt` 增加可选
+  `metadata: { owner?, version?, risk?, sideEffect? }`；`buildCapabilityManifest` /
+  `app.getCapabilityManifest()` 从**最终菜单**产出 `{ app, hash, capabilities }`，
+  hash 覆盖名称 / 类别 / description / schema / strict / 审批 / 元数据，**与输入顺序无关**
+  ⇒ 可以直接当 PR 留档的比较基座。CLI `agentia manifest` 真装配 `src/app.ts`、**不调用模型**。
+- **不做什么**：它是留档与比较基座，不替代 code review，也不执行安全策略。
+- **验证**：`tests/toolkit/manifest.test.ts`；`scripts/e2e-cli.ts` 真跑产物路径。
+
+### 改动：恢复段预算按任务累计 + 工具结果回模型截断（2026-11-05 ref-durable-resume-accounting / ref-tool-result-limit）
+
+- **预算**：`TaskRecord` 新增 `usageTotal`（每个已收尾段折进去）与 `sessionInput`（首个挂起段
+  存下本轮输入，恢复成功后补写会话、终态清除）。恢复段经段内 `usageOffset` 参与
+  `maxTotalTokens` / `maxCostUsd`，主/子循环同口径；`trace.totalUsage` 仍只代表本段。
+- **如实标注的边界**：进程崩在「模型已花 / 工具已执行、结果尚未落库」那个窗口时，那笔用量
+  **追不回来** —— 它不是精确的全局账单。旧版本留下的挂起记录没有 `sessionInput`，仍只能跳过补写。
+- **`maxToolResultChars`**：新旋钮，只裁**回模型**的 `tool_result`（缺省 / `false` = 不截断，
+  `0` = 截到零长度并留 `…(+N)`），经 `forwardToolContext` 透传嵌套循环；与 `maxEventChars`
+  （只管记账）**互相独立**、不改变副作用。验证：`tests/engine/tool-result-limit.test.ts`
+  真穿两回合，断言模型看到截断而 trace 仍完整。
+
+### 新增：`parseTaskRecord` 公共导出（2026-11-05 ref-task-record-parser-public）
+
+- 外部 `TaskStore` 不再用 `JSON.parse(raw) as TaskRecord` 绕过旧形状归一：
+  公共入口做 JSON 解析 + 形状守卫 + 旧版本归一，坏 JSON 抛错、非记录返回 `undefined`
+  （坏数据吞不吞仍由各 store 决定）。`docs/database.md` 的 MySQL 骨架改走该入口，代码围栏真编译。
+
+## [Unreleased]
+
+## [0.10.4] - 2026-10-28
+
+### 变更
+
+本版包含**渐进式上手、结构化结果契约与生产可靠性修复**：
+
+- 新增 `agentia create --minimal`：单文件 + 裸工具即可跑通 agent；默认完整服务模板不变。
+- 声明 `resultSchema` 后未提交合法结构化结果时，以 `result_missing` 失败，不再静默算成功；
+  依赖旧宽松行为的调用方需显式处理该失败，普通文本 run 不受影响。
+- `gracefulShutdown` 的总预算覆盖 drain 本身；trace sink 默认最多等待 10 秒，
+  抛错或超时均告警且不阻断后续 sink。
+- `cloneTaskRecord` 保留 `__proto__` 自有键，不再丢字段或改变副本原型。
+- 另含数据库接入文档、HTTP serve/优雅停机、CLI view/harvest 与官网可读性改进。
+  详细条目如下。
+
+### 新增：`agentia create --minimal` 与渐进式上手路径（2026-10-27 ref-progressive-onboarding）
+
+- **最小模板**：单个 `src/main.ts` + 裸工具，不要求先理解装饰器、DI、registry 或 HTTP 宿主；
+  `dev` / `typecheck` / `build` / `start` 四个脚本均可直接运行。
+- **默认不变**：不带 `--minimal` 仍生成完整服务模板，既有项目、inspector 与部署路径不受影响。
+- **CLI 与文档**：帮助按核心工作流、观测与调优、评测与数据、能力包分组；README、usage-guide、
+  中英官网都先讲裸工具，再进入完整装配。
+- **验证**：默认与 minimal 都真建工程过类型检查；E2E 按 minimal 自己的 scripts 真跑，
+  pack → 离线安装后也能创建 minimal。依赖版本仍复用同一发布面，不新增运行时依赖。
+
+### 修复：结构化结果、停机总预算、sink 挂起与任务记录副本（2026-10-26）
+
+- **行为变更**：声明 `resultSchema` 后，模型自然收尾但未提交合法结构化结果时，run 现在以
+  `stopReason='result_missing'` 失败，不再返回 `succeeded` + `typed=undefined`。子 agent
+  同样以 `is_error` 交回，不再退化为纯文本报告。依赖旧宽松行为的调用方需显式处理该失败；
+  未声明 schema 的普通文本 run 不变。决策：`docs/spec.md` §10 ref-structured-result-required。
+- **停机**：`gracefulShutdown({ timeoutMs })` 的总预算现在真正覆盖 drain 本身；drain 永不返回
+  也会到期关服务器并回报 `false`。Node 26 的裸 TCP / 半开连接测试改为按运行时行为分支。
+- **观测**：run 与 MCP 反向桥的 sink 投递共用一套实现；单个 sink 默认最多等 10 秒，
+  抛错或超时都告警且不影响后续 sink。超时是放弃等待，不取消底层导出。
+- **存储**：`cloneTaskRecord` 保留 `__proto__` 自有键，不再丢字段或改变副本原型。
+
+### 文档：接数据库（新增 `docs/database.md` + MySQL `TaskStore` 骨架）
+
+宿主问的是「我要连 mysql，是不是得再写个数据库的包」—— 答案是不用，但这个答案此前**没有落点**：
+`TaskStore` 的注释写着「队列 / DB 版只需实现 `TaskStore`」，而宿主从零实现时要自己摸清
+「哪份数据归框架、哪份归自己」「`listDue` 为什么值得实现」「多实例为什么会双跑」。
+
+- **落库**：[`docs/database.md`](docs/database.md) —— 三件事分治表（业务数据 / 任务状态 / 会话记忆）、
+  业务数据的构造注入写法（provider + `@Tool`，框架零改动）、`TaskStore` 的 6 必需 + 3 可选契约、
+  可照抄的 MySQL 骨架（建表 DDL、`ON DUPLICATE KEY UPDATE`、`(status, wake_at)` 到期索引）、
+  三个真坑（幂等键 last-wins 不能靠插入序 / `listDue` 写成 `JSON_EXTRACT` 等于白实现 /
+  **跨进程认领不是原子的**：靠 `ownerId` + pid 存活 + 新鲜度启发式，要真原子得在 store 内部加锁，
+  而那不是接口的一部分）、以及「别把业务事务和 run 记录塞进一个事务」。
+- **不做什么**：不新增 `@migor/*-mysql` 包（拆包判据是**真有第二个使用方**，而 `TaskStore` 接口已冻结
+  ⇒ 将来提取只是剪切粘贴，成本不随时间涨）；不把驱动放进核心（`dependencies` 仍为空 ——
+  `SqliteTaskStore` 能进核只因为 `node:sqlite` 随 Node 发行）。
+- **记录一个缺口**（不改公共面）：`src/store/record.ts` 的 `parseTaskRecord`（含旧形状归一）**没导出**，
+  而它是读回记录的**唯一入口**；外部实现 `TaskStore` 只能 `JSON.parse(...) as TaskRecord`，
+  正是那个 `as` 在讲的东西（旧记录带着已不存在的状态值被读回来）。文档里给了「自己补归一」的
+  临时写法，并把导出这件事留给后续决策。
+- **守卫**：`docs/database.md` 纳入 `tests/docs/code-fences.test.ts` 取样面（骨架是宿主会逐字复制的，
+  必须真编译）；`docs/guards.md` 的取样面描述同步。变异 2 条各咬住预期用例：删掉 `clear()` ⇒
+  `docs/database.md:124（块内第 26 行）TS2420`；把 `pool.execute` 改成 `pool.exec` ⇒
+  `docs/database.md:29（块内第 13 行）TS2339`。README 中英两版补索引行。
+- **§7 回答「要不要出包 / NestJS 式接入」**（同一问题问了两次 ⇒ 判据落纸）：拆包的判据是
+  **真有第二个使用方**，而 `TaskStore` 接口已冻结 ⇒ 提取成本不随时间涨，提前出包反而要认领
+  驱动版本 / 变体语义 / 表结构迁移；真出包时形态是**收 pool 不 import 驱动**（照 `RedisTaskStore`
+  的 `RedisLike` 先例，仍是零运行时依赖）。NestJS 四部件对照：DI + token 有（但 `Token = string`，
+  拼错只在首次 `resolve` 才抛）、模块化靠返回 `Provider[]` 的函数拆、**生命周期刻意没有**
+  （判据是**进程级决策归宿主**：不读 env / 不订阅信号 / 不关 store / `createHttpHandler` 不 listen
+  ⇒ 关池是宿主的 `SIGTERM` 钩子；⚠️ 唯一例外是 MCP 反向桥，那里它自己就是服务端）、实体 → Repository 不做。
+
+### 新增：`serve()` / `gracefulShutdown()` —— 起服务 + 优雅停机的两个宿主原语（2026-10-22 ref-serve-graceful-shutdown）
+
+宿主反馈「server 这块让用户写的好麻烦」。对照 `examples/deploy/src/main.ts`：108 行里约 35 行是与
+业务无关的 server 样板，而那 35 行藏着四个**静默错** —— 写错没人报，只在 K8s 滚动更新那天发作：
+
+- **新增导出**（`src/transport/serve.ts`，决策见 `docs/spec.md` §10）：
+  `serve(handler, { port, host?, backlog? })` → `{ server, port, close() }`；
+  `gracefulShutdown({ server, drain, signals?, timeoutMs?, onSecondSignal?, onShutdown? })` → 幂等 `stop()`。
+  宿主侧从 ~35 行降到 ~8 行（两份参考示例已改用，`e2e-deploy` 仍报 `shutdownExitCode: 0`）。
+- **收进实现的四条**：① 连接收干净 —— ⚠️ 版本有关：Node **19.0.0** 起 `close()` 自己会收空闲连接
+  （nodejs/node#43522），只有 18.x 必须显式 `closeIdleConnections()`；旧版 Node 对裸 TCP 还需
+  `closeAllConnections()` 兜底（Node 26 已可提前干净收口）；② **先 drain 再 close**（反过来切断在飞请求）；
+  ③ 第二次信号**不吞** —— `if (stopping) return` 是反例：信号**已被拦截**，Node 默认行为不会发生
+  ⇒ 运维强杀杀不掉（两份示例当时都这么写）；④ `onShutdown(clean)` 把结论交回宿主。
+- **边界**：`signals` **不传 = 一个信号都不订阅**；本原语**不调 `process.exit`**（退出码与
+  「关池 / 冲 sink 之后再退」是宿主的编排）。判据是**谁发起** —— 与 Nest 的 `app.listen()` /
+  `enableShutdownHooks()` 同构（那边信号订阅**默认也是关的**）。不做 `serve(app, {...})` 一体化：
+  那会把 `createApp` / `AsyncRunner` / `createHttpHandler` 焊死，挂进已有 Express 的宿主反而用不上。
+- **验证**：`tests/transport/serve.test.ts` 15 例（真实 http server + 真实 socket），**变异 8/8**
+  各咬住预期用例后还原。⚠️ `closeIdleConnections` 那条**只能用调用断言钉**（当前运行时 Node 22
+  自带该行为 ⇒ 行为断言抓不到），期望次数按运行时算 ⇒ 18 与 ≥19 上删掉它都红。
+- **同步**：`docs/usage-guide.md` 优雅停机小节、`docs/deployment.md` §5（含那四个坑的清单）、
+  `docs/database.md` §7（`pool.end()` 接在 `onShutdown`）、`docs/guards.md` 登记行。
+
+### 修复：`view` 取最近 N 条、`harvest` 接 opt-in 文本、bundle 加构建期语法闸（2026-10-21 ① ref-view-limit-harvest-text）
+
+对最近 45 个提交复评后的一批修复（评审记录 `docs/reviews/2026-10-21/recent-code-review.md`）。
+四条都是「两边各自自洽、中间那条缝没人负责」的同族失效：
+
+- **`agentia view --limit` 缺省取「最近」N 条（P1，主场景失效）**：`.agentia/traces.jsonl` 只增不减
+  （`dev-runner.ts` 明写不轮转），最新在文件末尾，而原实现 `slice(0, cap)` 取**最早** N 条 ——
+  长跑 dev 环里「想复盘刚才那次」拿到的是今早第一批。实测：4 行文件 `--limit 2` 出
+  `t1-old` / `t2`，最新的 `t3` 不在页里；注释还自称「与 dev 面板 ring 50 对齐」（ring 保留最新，
+  方向正好相反）。同一条纪律下沉到去重：位置跟着**最后一行**（`Map` 原地 `set` 不移动位置）。
+  新增 `--head` 保留「从头看」，截断文案按方向说（`只含最近 N 条` / `只含最早 N 条`）。
+- **`harvest` 读 `output.text`（P2，与 2026-10-16 ① 同族）**：框架早有 `traceContent: 'full'`
+  这条 opt-in 缝（`turn.ts` 写 `output.text`，`export.ts` 已接），`harvest` 仍硬编码占位
+  `'[harvest] assistant 文本未入 trace'` ⇒ 用户付了体积与脱敏的代价，产出的回归用例仍跑不起来。
+  现在有文本就用真值；**纯 tool_use 回合不补占位**（占位 = 一条「模型说过这句话」的假事实），
+  只有「既没文本又没工具」的终端回合才占位；骨架头注按这一次的实际情况二选一（开没开开关、
+  几个回合没文本）。框架与 CLI 两份移植同步（七组夹具逐字对拍，新增含 `output.text` 一组）。
+- **bundle 构建期按 classic script 编译一次（P2，静默白屏）**：`view` 把 bundle 内联进普通
+  `<script>`，而 `bundle.test.js` 用 **ESM import** 验产物 —— 后者的语法集更宽 ⇒
+  `export default` / `export *` / 残留副作用 `import './x.js'` 三种形态**构建绿、测试绿、页面白屏**，
+  而 CLI 已经打印了「已生成」（2026-10-21 用真实 `dist/` + 真实 CLI 逐一实测）。
+  现在 `buildBundle` 末尾用 `vm.Script` 编译整段 body（按 script 而非 function body 解析），
+  报错还能定位回具体 `src/` 模块；`view` 侧 `stripExports` 同时补查残留 `import`。
+- **产物落点 / 覆盖 / `--open`**：缺省产物避开点目录（输入在 `.agentia/` 时上跳到最近的可见目录，
+  否则 Finder 里看不见、也容易被 `.gitignore` 吞掉）；产物路径等于输入文件本身直接报错；
+  覆盖同名文件在 stdout 出声（**不引入** `--force` —— HTML 是派生物、重跑是常态，与 harvest
+  「产物里有你改过的断言」不是同一种风险）；`--open` 在 Windows 改走 `cmd /c start "" <file>`
+  （`start` 是 cmd 内建命令，直接 spawn 必 ENOENT）。
+- **空 `spans` 的 trace 残留上一条树（P3）**：`playTrace` 原先直接 `return`，切换 trace 后页面
+  还留着**上一条的树**（下拉里选中的是这一条）。现在空树也 `reset`，并用它自己的 traceId 作标题。
+- **文档**：`usage-guide` 的「CLI 四件套」改五件套（含 `jsonlTraceSink` 的输入方列表）；
+  harvest 的「trace 不记 assistant 文本」改成条件式表述；`view` 节补 `--limit` 方向与产物落点。
+
+**棘轮**：CLI 实测 10060 → 10135（+75），基线之和 10574 → 10653（+79，5% 缓冲口径）；
+`packages/trace-view` 的 `fromTrace.js` 173 → 181（空树 reset）。两处都写了「为什么」。
+决策登记：`docs/spec.md` §10 2026-10-21 ref-view-limit-harvest-text。
+
+### 文档：框架兼容性实测结论落库（新增 docs/frameworks.md + README / 边界表同步）（2026-10-17 ⑨ ref-frameworks-compat）
+
+- **病灶**：README 与 `usage-guide.md` §7 都写着「未对 Deno / edge 做验证」—— 今天它已是**假话**：
+  Node 22.13.1 / Bun 1.4.3 / Deno 2.9.6 三运行时跑过「导入 → 装配 → HTTP → 副作用」**四步**判定；
+  NestJS 12.1.3（CJS + ESM）/ Egg 4.0.10 两个 Web 框架宿主**只验到第三步**（导入 / 装配 / HTTP），
+  **副作用未验** —— 那两个宿主用 `scriptedClient`，且 cluster 那次真请求拿到的是 Anthropic 403、
+  run 未成功。而结论只活在会话里，仓库零记录。
+- **落库**：新增 [`docs/frameworks.md`](docs/frameworks.md) —— 判定标准（四步，缺一步不算「可用」）、
+  实测环境、运行时轴 / Web 框架轴两张结论表、各宿主最小接入代码、**Egg 的三个坑**
+  （CSRF 拦 POST 回 403；bodyParser 提前消费请求流 ⇒ POST 挂死而 GET 仍 200；cluster 下每 worker
+  各持一份内存 store ⇒ 同一 taskId 轮询 `404 200` 完美交替 ⇒ 必须换共享 store）。
+- **同步**：README 中英两版的「运行时」bullet、稳定性边界表「运行环境」行、集成节补宿主表；
+  `usage-guide.md` §7「运行时是 Node」行改为「Node 承诺，Bun / Deno 实测」
+  （`boundary-table.test.ts` 登记表 key 同步改，双向比对绿）。
+- **宣传面**：`docs/promotion.md` 劝退节「Deno / Bun / edge 未验证」改如实表述；中文主稿补
+  **「增量、不侵入」主打条**（五条同向的设计决定 + git 证据：示例 49 行业务文件全 git 史
+  只有一个 commit）与**「支持的宿主」列表**（刻意不写版本号 —— 防腐烂，指回
+  `docs/frameworks.md`）；短版 / X 线程 / Product Hunt 中英 / awesome / 30 秒视频旁白 /
+  评论区竞品应答同步。另有两篇对外宣传文章（不在本仓库）结尾同步精确化：punchline 之外补
+  「结构性原因」与「边界」——「一个文件」是 `node:http` 基线的下限，不是普适上限。
+- **如实标注**：Bun / Deno 是**实测**不是**承诺** —— 不在 `engines` 内、不在 CI 上；
+  Express / Fastify / Koa 作为独立宿主未逐一实测；Node 18 / 20 未跑（「`require(ESM)` 在 22.12
+  前不可用」是按发布时间线的推断，按 `await import()` 写可避开）；edge 仍未验证。
+- **更正（同日，⑨ 合并后 review 发现）**：⑨ 初稿写的是「四宿主都跑过四步判定」—— **过度承诺**，
+  NestJS / Egg 只到第三步。已修：`docs/frameworks.md` 的 Web 框架轴表加「副作用」列（那两行标
+  **未验**），判定标准那节补射程说明（四步全过是对**运行时**的要求）；`docs/spec.md` §10 ⑨ 同款
+  措辞就地更正（**追加**不改写 —— 决策日志只增不改）。同批还修了两处：官网 6 处「Deno / Bun /
+  edge 未验证」与两个 README 的新表述**公开矛盾**（中英各 3 处，已同步）；
+  `docs/frameworks.md` 里「一等公民」与 trace 那句「一等公民」同词不同指（已消歧义），
+  cluster store 表补上 `deployment.md` 的「单宿主写者」前提。另给 `stability.test.ts` 补了一条
+  镜像锚点 —— 它此前只钉 5 条承诺锚点，**钉不住「排除面」**，所以三面各说各话也能全绿
+  （变异验证：摘掉官网那句的 Bun ⇒ 守卫红；还原 ⇒ 绿）。
+- **验证**：`docs/frameworks.md` 的三个 ts 块按 `code-fences` 守卫同手法（`paths` → `src/index.ts`，
+  不依赖 build）真编译通过 —— 其中 CJS 片段第一稿写了顶层 `await`，探针当场报
+  `TS1309`（CommonJS 里不合法），已改成包一层；这正是实测时踩过的同一个坑，
+  也是把 `docs/frameworks.md` 纳入 `code-fences` 取样面的理由（该页承诺「照抄可跑」）。
+  `boundary-table` / `stability` / `code-fences` / `scoreboard` 等文档守卫全绿，
+  `bash scripts/verify-all.sh` 八步通过。
+
+### 文档：README 精简（中文 451 → 314 行，英文同步）（2026-10-17 ⑧ ref-readme-slim）
+
+- **病灶**：中文 README 是英文版的**两倍**（451 vs 229 行），差额几乎全在三节：
+  四类能力 62 vs 10、运行时特性 68 vs 10、集成 59 vs 13。这三节把
+  `docs/usage-guide.md`（1923 行）的完整示例抄了一遍 —— README 在替参考手册干活。
+- **删掉的是「探索过程」而非信息**：
+  ① `.env` 为什么放在装配模块而非入口的 3 行论证（压成一句括号）；
+  ② `examples/` 用 `file:../..` 的理由（`examples/README.md` 已有）；
+  ③ Node 版本矩阵的细节（压成一句）；
+  ④ 四类能力的三个完整类定义 + 装配示例（已指向 `usage-guide` §3）；
+  ⑤ 长上下文 / 结构化结果 / 中间件三块完整示例（压成三条 bullet + 指向 §6.3 / §5.3 / §6.6）；
+  ⑥ 迁移纪律「逐步收紧」的历史（`0.7.1` 怎么样、`0.8.1`~`0.8.3` 怎么样）—— 只留「这条命令是下限」；
+  ⑦ 「本仓的老病」「为此吃过教训」这类自嘲；
+  ⑧ 性能节后半段「定下处置的计划文档路径」。
+- **一条没动的**：所有**承诺**与**边界**（稳定性承诺表、1.0 门槛、未验证 Deno/edge、
+  零依赖由守卫守着）—— 压缩的是叙述，不是承诺。
+- **被迫保留的**：README 的骨架被 5 个守卫钉着（记分牌四个数字、`## 性能量级` 的五个复跑命令、
+  `## 稳定性与版本策略`、代码块**真编译**且块数 ≥ 20 的防假绿下限）。删掉四类能力的代码块后
+  触发了「只抽到 19 个块」，故把多模型示例恢复成代码块（它有信息量，不是凑数）。
+- **边界**：压缩的是叙述，不是承诺；删的是重复示例，不是 API 信息（详细示例的住址写清楚了）。
+- **英文版同步**：229 → 240 行 —— 补了「API at a glance」表（中文有、英文此前缺），删了同类
+  探索过程（`.env` 论证、`0.7.1` 的迁移史、性能节的计划文档路径）。顺带修正一处**事实错误**：
+  `.env` 由 `src/app.ts` 读取，英文原文写的是 `src/main.ts`。
+- **一处回滚**：中文版第一稿把「路线 C：已有服务」整节删掉了（只在页尾留了链接）——
+  那是 #266 给 `examples/agent-endpoint/` 的正文入口，不该在精简中丢失，已恢复。
+
+### 元数据：包描述英文化 + keywords 补全（2026-10-17 ⑦ ref-discovery-metadata）
+
+- **病灶**：两个发布包的 `description` 是纯中文 —— npm 搜索按英文 token 匹配，该字段对英文
+  查询的贡献为 **0**。实测五个查询（`agent framework` / `typescript agent` / `ai agent typescript` /
+  `llm agent node` / `mcp framework`），`@migor/agentia` **全部在前 15 名之外**；唯一命中的是
+  搜 `agentia` 排第 **9**，而前 5 里 4 个是另一家公司的 `@copado/agentia-*`。
+  `keywords` 只有 7 个，缺 `typescript` / `nodejs` / `ai-agent` / `agent-framework` /
+  `model-context-protocol` 这批高频检索词。
+- **改了什么**：`@migor/agentia` 的 description 改英文（中文原文**移进 `README.md` 首屏**，
+  一个字没丢），keywords 7 → 20；`@migor/cli` 同样处理（description 英文化，keywords 4 → 12）。
+  `README.md` 首屏在中文段前加一句英文定位句 —— npm 包页首屏就是它。
+- **刻意不做**：keywords 里**不放 `nestjs`**。本包没有 NestJS 集成，放进去是蹭词，
+  会让人以为存在官方适配。「NestJS 场景」靠文档与落地页命中，不靠元数据误导。
+- **生效时机**：npm 元数据**要等下一次发版**才进搜索索引（本地改 `package.json` 不改变线上排名）；
+  GitHub 的 `about` 是即时生效的字段，但当前令牌无 Administration 权限，本轮未改。
+- **边界**：这是消除明显错误，不是增长手段 —— keywords 影响「能命中哪些长尾查询」，
+  不改变「在泛词里排第几」（那由下载量与 star 决定）。「改完排名上升」**未验证**。
+
+### 文档：补「本地怎么调」—— 四条路径 + 可直接复制的 curl（2026-10-16）
+
+- **为什么**：`docs/usage-guide.md` 的 HTTP 端点契约表是完整的，但**一个可直接复制的命令都没有**
+  （全文 0 处 `curl`）；更要紧的是没写那句「**这里没有『一个业务一个 URL』的接口层**」——
+  照别的框架的经验来找，会一直找错东西：加一个 `@Tool` **不会**多出一条路，
+  **调哪个能力由模型决定、不在 URL 里**。
+- **加了什么**：① 不起服务跑一次（`start:batch`）；② curl 四句（`/healthz` / `/run` / `/run` + SSE /
+  `/tasks`）；③ `agentia dev` 面板；④ **想单挑某一个工具**走 `createMcpServer`（每个 `@Tool`
+  变成一个标准 MCP tool —— 这才是「一个能力一个接口」的形态，只是它长在 MCP 层，不是 HTTP 路由层）。
+- **两个写进去的判据**（都是「只看 curl 退出码就会误判」的那类）：`POST /run`
+  **失败也回 200**（硬失败在响应体的 `status:"failed"` + `error` 字段里，脚本要判 `status`
+  不是判 `$?`）；SSE 那条必须加 `curl -N`，否则是 curl 自己在缓冲、看着像服务没吐东西。
+- **落在**：`docs/usage-guide.md`（= 项目内 `AGENTS.md` 的单源）§6.2 新增一小节 +
+  模板 `README.md` 新增「本地怎么调」。文档字数闸对 `usage-guide` **刻意不设上限**
+  （参考手册按需查，见 `doc-budget.test.ts`），故无需调数。
+
+### 新增：`agentia view <trace.jsonl>` —— 落盘 trace 的可视化出口（2026-10-16 ⑤ ref-view-single-file-html）
+
+- **缺什么**：`agentia dev` 的面板是**在飞**的（run 列表是内存 ring，重启即空）；落盘 / 生产的
+  trace 此前只有文本侧（`report` 排行 / `diff` 差异 / `harvest` / `export`）—— **没有任何一处
+  能把它画出来**。「数据没丢但看不见」，且**不能转发**。
+- **形态**：单文件自包含 HTML（CSS 与渲染器 bundle **全部内联**、零外链、离线可开、可转发）。
+  业界 2026 已收敛到这一形态（agentskit / telltrace / claude-tap / AgentCanvas 四家不约而同，
+  且都默认 redact）⇒ 这不是「多一个选项」，是「别再自己发明」。方案对比见
+  `docs/plans/2026-10-16-trace-view-local-file.md`（取它而非「起服务」的关键理由：一次性看文件
+  不该再付一遍 inspector 的 D0 鉴权税）。
+- **flag**：`-o <out.html>` / `--open` / `--raw` / `--limit N`（默认 50，超了明说）/
+  `--trace-id <id>` / `--redact-key <字段名>`。
+- **默认脱敏**（`--raw` 关闭，且 stderr 出声 + 产物打水印）：`src/core/trace.ts:79` 划的是
+  「脱敏在 sink 缝外 = **宿主职责**」，**CLI 正是宿主** ⇒ 这条是执行既定缝，`src/` 零改动。
+  实现是 `examples/observability` 那份 `redactSink` 的去类型移植（正文逐行同形，源码级对拍守着）。
+  ⚠️ **best-effort**：6 类预设覆盖值内凭证形态（bearer / jwt / aws-access-key / llm-api-key /
+  email / phone-cn），**`password=` 这类不在内**（实测确认）；`--redact-key` 是**按字段名**整字段
+  抹平，与前一种是两种机制 ⇒ 产物 banner 把两档各自能干什么都写出来，不暗示「加了 key 就都解决了」。
+- **安全**：trace 内联进 `<script>` 前把 `<` 转义成 `\u003c` —— trace 含**模型输出 = 不可信输入**，
+  一个 `</script>` 就能提前闭合脚本块、注入任意脚本，而产物的默认命运正是被转发。
+- **配置**：`@migor/trace-view` 多一个产物 `dist/trace-view.bundle.js`，由
+  `scripts/bundle.mjs` 从 `src/` **自动派生**（依赖拓扑 + 导出名都现场解析；撞名 / 环 / 引用
+  不存在的模块 ⇒ 构建期响亮报错）。它是**运行形态**不是第二份实现：面板与官网仍用分文件，
+  同源由 `test/bundle.test.js` 钉住。
+- **验证**：`packages/cli/test/view.test.mjs` 15 条 + `packages/trace-view/test/bundle.test.js`
+  7 条；**变异 9 条**各自咬住预期那条（摘 `<` 转义 / 摘 export 剥离 / 摘默认脱敏 / 改截断措辞 /
+  摘去重 / 摘撞名检测 / 摘环检测 / 只拼一个模块 / 少导出一个符号）。
+  ⚠️ 其中一条变异起初**不红**：同源那条断言读的是 `dist/`（构建产物），改 `bundle.mjs` 不会重建
+  dist ⇒ 拿着旧产物一路变绿。已改为 import `buildBundle()` 的当次产出。
+
+### 修复：会话（对话历史）读写失败零信号（2026-10-16 ① ref-session-failure-loud）
+
+- **病灶**：`loadSession` / `appendSession` 两个「辅助动作失败不得击穿 run」的 `catch` 是**裸吞**
+  —— 不抛、不 warn、不进 trace。而这一处失败的**形状最坏**：读失败 ⇒ 本次 run 表现成「这是第一轮」；
+  写失败 ⇒ 这一轮白聊；下一次 `append` 把坏的那份覆盖掉 ⇒ **整段对话历史无声消失**，
+  使用者只会觉得「它忘了」。`TraceSink` 也拿不到它，唯一可见性出口是 dev runner **启动期**的探测。
+- **修法**：吞之前落一条 `console.warn`（与 `flushSinks` / memory 回写 / metrics 导出同款纪律）。
+  **不抛、不改 run 结果** —— 变的只是有没有声音。
+- **边界**：只到 `console.warn`，**不进 trace**（要挂得先定「会话维 span」，本轮不做）。
+- **验证**：`tests/runtime/session.test.ts` +2 条（读 + 写各告警一次 / 正常路径零告警）；
+  两条 `catch` **各自**做过反向验证（摘掉告警 ⇒ 恰好那条红）。
+
+### 新增：能力类自带依赖声明（`static deps`）+ 显式侧 DI 重名出声（2026-10-16 ② ref-di-dup-loud）
+
+- **病灶**：`discover` 对「default export 是类」只产 `{ useClass }`（没有 deps）⇒ 需要注入的能力
+  只能**挪出 discover**、在装配文件里**再注册一遍** ⇒ 同一 token 出现两份（一份无 deps、一份有），
+  靠「后注册覆盖先注册」碰巧成立 —— 顺序一变就静默失效，且框架零信号。真实形态：脚手架里
+  `WORKDIR` 被 `discover` 与 `registry.ts` 各声明一遍、值还不同。
+- **修法①**：能力类写 `static readonly deps = ['WORKDIR']` ⇒ `discover` 带上 deps（形状不是
+  字符串数组则**响亮报错**，不当成「没有依赖」去无参构造）。
+- **修法②**：`AgentApp` 装配期对**显式 providers** 的同 token 重复注册给一条 `console.warn`
+  （覆盖语义不变）；模块级 → 应用级那条**刻意不告警**（那是设计好的覆盖，不该吵）。
+- **验证**：`tests/toolkit/discover.test.ts` +3（含「真的注入」端到端 + 坏形状报错 + 普通类行为不变）、
+  `tests/toolkit/module.test.ts` +3（重名告警 / 模块覆盖不告警 / 无重复零告警）；
+  两处各做过反向验证。
+
+### 脚手架：默认接 trace 出口 + `AGENTS.md` 版本标记 + 模板编译级对拍（2026-10-16 ③ ref-scaffold-observability-gap）
+
+三件都在**脚手架侧**（框架核心刻意不内建 trace 出口这件事没变，见 `docs/spec.md` §9.3）：
+
+- **① 模板默认接一条 `jsonlTraceSink`**（落 `.agentia/traces.jsonl`，已 gitignore，删一行即关）：
+  此前不接 ⇒ 同步 `/run` 的 trace 随响应回去了，而**异步 `/tasks` 的 trace 落进任务库里没有任何人导出**
+  ——「这个任务为什么慢」要查时它正好不在。接上后 `agentia report` / `diff` / `harvest` / `export` 开箱可读。
+  ⚠️ 落的是完整 trace（含 prompt 与工具出入参）⇒ 模板注释写明「上线前按你的合规要求处置」。
+- **② `agentia doctor` 两条新检查**：未配 `sinks` ⇒ 警告；项目内 `AGENTS.md` 无版本标记
+  （或标记与当前 CLI 不同版）⇒ 警告。`create` 写 `AGENTS.md` 时插一行
+  `<!-- agentia-guide-version: x.y.z -->`；CLI 版本号抽成 `packages/cli/src/version.ts` **单源**
+  （`cli` / `create` / `doctor` 三处共用）。→ 这份说明是 `docs/usage-guide.md` 的**快照**，
+  而 CLI 没有任何命令更新它，它恰恰是「AI 辅助编码的权威入口」⇒ 升级后不能再静默过期。
+- **③ 新增 `packages/cli/test/templates-typecheck.test.mjs`**：用模板真建一个工程 → 真跑
+  `tsc --noEmit`。此前模板只有**文本级**守卫，没人证明「建出来的工程编译得过」。
+- **顺带**：模板 `read-file` 改用 `static deps`、`app.ts` 删掉那条冗余注册、`registry.ts` 的
+  `WORKDIR` 改为按文件位置解析（与 `app.ts` **逐字同值**）；`docs/usage-guide.md`
+  （= 项目内 `AGENTS.md` 的单源）补形态说明。
+
+### 修复：同一落盘文件被两条 sink 对口 ⇒ 一条 trace 落两行（2026-10-16 ④ ref-sink-exactly-once）
+
+- **病灶（CI 真现场，不是推定）**：③ 给脚手架接上 `sinks` 之后，`e2e-dev` 立刻红 ——
+  脚手架的 `createApp({ sinks })` 与 `agentia dev` 的 `registerDefaultTraceSink` **都**往
+  `.agentia/traces.jsonl` 写（两边各自都合理），于是同一个 traceId 落**两行**。而
+  `report` / `diff` / `harvest` 的前提是「一行 = 一次 run」⇒ 一次 run 被**数两次**
+  （成本翻倍、错误率减半），**且全程不报错** —— 不落盘是「没数据」，重复落盘是
+  「数据看着正常但错了」。
+- **修法**：`jsonlTraceSink` 对同一路径**进程内幂等**（两次调用返回同一个 sink 对象），
+  `AgentApp` 收 `sinks` 时对 sink **对象**去重（`new Set`）—— 两处都要：只幂等不 set ⇒
+  数组里仍有两个条目、收尾还是调两次；只 set 不幂等 ⇒ 两个不同对象，set 去不掉。
+  「两处都接」从此退化成「恰好一次」。
+- **验证**：`tests/integrations/sink-exactly-once.test.ts`（真跑一次 run ⇒ 恰好一行 +
+  不同文件各写各的）+ `tests/integrations/file-sink.test.ts` 的幂等条（含「不同路径仍是
+  两个 sink」的反向钉）。**两条变异各自亲跑**：摘 `new Set` ⇒ 恰好端到端那条红；
+  摘工厂幂等 ⇒ 两条红。
+- **边界**：幂等是**进程内**按解析后的绝对路径；跨进程仍受「单进程写者」前提约束。
+  两份**不同实现**的 sink 写同一文件不在射程内（去重只认对象同一性）。
+
+### 仓库自身 · 测试判据：与墙钟赛跑的计时器族换成「等真实事件」（2026-10-17 ① ref-flaky-timer-tests）
+
+- **为什么**：完整套件连跑 7 次 **5 次红**，且每次红的是**不同**用例 —— 全是计时器/超时族。
+  共用假设是「毫秒级余量够用」（`timeout: 30` 配下界 `dt >= 20`、`sleep(40)` 配 5ms tick），
+  而满载 runner 上一次事件循环饿住就能吃掉它。⚠️ **4 个 CPU burner 复现不出，必须饱和**
+  （32 核起 32 个 burner）。
+- **改了什么**：5 处判据 —— 能等的换成 `waitFor`（仓内既有工具），**否定断言**（「不得再发生」）
+  改成按 tick 间隔的倍数给窗口；`mcpConnector` 那条的慢调用改用**测试掌控的闸门**
+  （抬预算会同时削弱区分力，闸门不会）。**`src/` 一行未动**。
+- **验证**：定向对照（`git show HEAD:` 取原版）—— 旧版在饱和负载下 **5 次红 4 次**，
+  新版 **5 次全绿**；修后完整套件连跑 **6 次全绿**；`verify-all.sh` 八步全绿。
+- **边界**：`withTimeout` 的硬超时判据（实测耗时）是**有意**语义，改的是用例预算量级
+  （50ms → 1000ms）不是源码；不引入假时钟（跨进程握手 / 真实 SSE / 子进程 spawn 依赖真时序）。
+
+### 仓库自身 · 验证链：`rapid` 分片补前置检查（2026-10-17 ② ref-rapid-requires-dist）
+
+- **为什么**：`rapid` 声明「不需要构建产物」，但它选的 `types` / `tests-types` 两步被测文件
+  从 `../../dist/index.js` 导入。干净克隆实测：缺产物 ⇒ **1/3**、**30 条 TS 错误**
+  （全是 `TS2307` 级联，**没有一条是真缺陷**）；`build` 之后 ⇒ 3/3。
+  而 `.githooks/pre-push` 用 `rapid` ⇒ 干净克隆上必红、红的还是假信号。
+- **改了什么**：缺 `dist/index.js` 时**响亮失败**并给下一步（exit 2）；注释里的假承诺一并改掉。
+  步骤数仍是 8（`ci.yml` 的 job 名不用动）。
+- **验证**：缺产物 ⇒ 明确报错 + 提示；有产物 ⇒ `rapid` 3/3（与改前一致）。
+
+### 仓库自身 · 结构：装配期纯件与大体量函数三处外移（2026-10-17 ③ ref-assembly-pure-extract）
+
+- **为什么**：方法级体量闸（阈值 240）的两处余量只剩 **4 / 5 行**（`module.ts` 构造 236、
+  `mcp-stdio.ts` 工厂 235）——「加一个分支就可能顶线」，那是下一次改动替这次付账。
+- **改了什么**：纯搬移、零行为变化 —— 成环检测与菜单重名查重抽成装配期纯件；
+  `mcp-stdio` 的 stdout 分帧抽成 `attachResponseReader`；`renderPrometheus` 的四个 run 级家族
+  抽成 `appendRunFamilies`。抽后分别 236→**195**、235→**206**、224→**187**，
+  全仓最大体 **218**（余量 22）。
+- **验证**：`toolkit` / `mcpConnector` / `metrics` 套件全绿（180 + 48 + 59）；八步全绿。
+- **边界**：**未**继续拆 `agentLoop`（218 行 —— 主循环一气呵成，余量不抵可读性损失）。
+  ⚠️ 本笔**没有**腾出 CLI 棘轮余量（`TOTAL_BUDGET` 余量仍为 0）：实证表明**搬移不降总量**
+  （零死导出、重复已被 `duplicated-blocks` 守卫覆盖），真降需要删减/精简，另案。
+
+### 仓库自身 · 治理：CLI 规模棘轮改为「每文件 5% 缓冲」（2026-10-17 ⑤ ref-ratchet-headroom）
+
+- **为什么**：此前的基线 = 当前实测、**余量 0** ⇒ 任何增行当场红，每次改代码都要顺手改基线。
+  而「真腾余量」经本轮实证**走不通**：190 个导出里零死代码、201 个顶层函数里只有 1 组逐字
+  重复（抽出来净减 5 行）、249 行 CSS 零死样式 ⇒ **可榨取空间本身约为零**，不是「没做」。
+- **改了什么**：`LINE_BUDGET` 全部改为 `ceil(实测 × 1.05)`，`TOTAL_BUDGET` 9560 → **10049**
+  （取单文件新基线之和 —— 否则会「单文件都没超、总量先红」）。总缓冲 **489 行（5.1%）**。
+- **语义**：**不是**「认可披露器」—— 闸门仍挡增长（单文件涨过 5% 就红）；缓冲是**预留给下个
+  功能的额度**，吃完只有两条路：降回去，或显式提基线并写理由。缓冲不许再整体上调。
+- **验证**：W1 断言逻辑未改；反向验证 —— 给 `version.ts`（36 行 / 新基线 38）加 3 行 ⇒
+  当场红（`version.ts 超了：40 行 > 基线 38`），还原后复绿 ⇒ **缓冲是真的，闸门仍咬**。
+- **边界**：这是一次**提高**基线（违反「只许往下调」的旧纪律），故在注释里写明是**一次性政策
+  调整**并附实证，不让它看起来像悄悄抬价；单体文件的绝对膨胀仍无闸（缓冲就是这个意思）。
+
+### 示例：存量服务增量加 agent 端点（2026-10-17 ⑥ ref-agent-endpoint-example）
+
+- **为什么**：现有 9 个示例全是「从零建」，而目标用户（已经在写 Node 后端、要把 agent 塞进
+  现有服务的团队）的真实场景是**增量改造**。这一格此前空着。
+- **加了什么**：`examples/agent-endpoint/` —— 一个已在跑的订单服务（`GET /api/orders/:id`），
+  加上 `/run` + `/tasks`；**`src/orders.ts` 一行未改**。改造清单 6 步、全部改动集中在一个文件：
+  装包 → 把已有函数包成 `@Tool`（约 20 行）→ **复用**同一份鉴权 → 加**一条分支** →
+  `drain()` 接进已有 SIGTERM → 四个预算旋钮。
+- **顺带明确**：**不做 RAG 适配器**。`@Tool` 已能包任何检索，内置会撞「零运行时依赖」与
+  「只给缝不给策略」两条硬约定 —— 示例里用内存订单表，就是要说清「RAG 是你的工具」。
+- **验证**：`typecheck:tests` 通过（已加入 `tsconfig.tests.json`）；
+  `examples-table` 守卫绿（表格集合 ↔ 目录集合一致）。
+- **边界**：**不进** `e2e-examples`（要真 API key 才有意义），保证是编译级；
+  `InMemoryTaskStore`（重启即丢），README 写明换持久 store 的路径。
+
 ## [0.10.3] - 2026-10-14
 
 > 本版主题（窗口 `0.10.2 → 0.10.3`）：**把「可观测」从「能导出」推进到「跨进程接得上、agent 自己查得到」**，
@@ -1623,8 +2165,6 @@ toolkit 142 / runtime 55 / engine 403 / container 10 / store 55 —— 全绿。
 `AGENTS.md` 的 `transport/` 段补登记三个监督件，并订正那句已过时的「910 行的类 / 后续抽块三步一步
 没走」（抽块其实已走了三步）。
 
-## [Unreleased]
-
 ## [0.9.5] - 2026-09-29
 
 > 本版主题（窗口 `0.9.4 → 0.9.5`）：**外部深评 P2 表的最后三条收口（K5 / T4 / K2）+ 两处「报告的判据要订正」**。
@@ -3760,31 +4300,33 @@ toolkit 142 / runtime 55 / engine 403 / container 10 / store 55 —— 全绿。
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.10.3...HEAD
-[0.10.3]: https://github.com/retrychx/agentia/releases/tag/v0.10.3
-[0.10.2]: https://github.com/retrychx/agentia/releases/tag/v0.10.2
-[0.10.1]: https://github.com/retrychx/agentia/releases/tag/v0.10.1
-[0.10.0]: https://github.com/retrychx/agentia/releases/tag/v0.10.0
-[0.9.5]: https://github.com/retrychx/agentia/releases/tag/v0.9.5
-[0.9.4]: https://github.com/retrychx/agentia/releases/tag/v0.9.4
-[0.9.3]: https://github.com/retrychx/agentia/releases/tag/v0.9.3
-[0.9.2]: https://github.com/retrychx/agentia/releases/tag/v0.9.2
-[0.9.1]: https://github.com/retrychx/agentia/releases/tag/v0.9.1
-[0.9.0]: https://github.com/retrychx/agentia/releases/tag/v0.9.0
-[0.8.3]: https://github.com/retrychx/agentia/releases/tag/v0.8.3
-[0.8.2]: https://github.com/retrychx/agentia/releases/tag/v0.8.2
-[0.8.1]: https://github.com/retrychx/agentia/releases/tag/v0.8.1
-[0.8.0]: https://github.com/retrychx/agentia/releases/tag/v0.8.0
-[0.7.2]: https://github.com/retrychx/agentia/releases/tag/v0.7.2
-[0.7.1]: https://github.com/retrychx/agentia/releases/tag/v0.7.1
-[0.7.0]: https://github.com/retrychx/agentia/releases/tag/v0.7.0
-[0.6.3]: https://github.com/retrychx/agentia/releases/tag/v0.6.3
-[0.6.2]: https://github.com/retrychx/agentia/releases/tag/v0.6.2
-[0.6.1]: https://github.com/retrychx/agentia/releases/tag/v0.6.1
-[0.6.0]: https://github.com/retrychx/agentia/releases/tag/v0.6.0
-[0.5.0]: https://github.com/retrychx/agentia/releases/tag/v0.5.0
-[0.4.2]: https://github.com/retrychx/agentia/releases/tag/v0.4.2
-[0.4.1]: https://github.com/retrychx/agentia/releases/tag/v0.4.1
-[0.4.0]: https://github.com/retrychx/agentia/releases/tag/v0.4.0
-[0.3.0]: https://github.com/retrychx/agentia/releases/tag/v0.3.0
-[0.2.2]: https://github.com/retrychx/agentia/releases/tag/v0.2.2
+[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.5...HEAD
+[0.10.5]: https://github.com/migoric/agentia/releases/tag/v0.10.5
+[0.10.4]: https://github.com/migoric/agentia/releases/tag/v0.10.4
+[0.10.3]: https://github.com/migoric/agentia/releases/tag/v0.10.3
+[0.10.2]: https://github.com/migoric/agentia/releases/tag/v0.10.2
+[0.10.1]: https://github.com/migoric/agentia/releases/tag/v0.10.1
+[0.10.0]: https://github.com/migoric/agentia/releases/tag/v0.10.0
+[0.9.5]: https://github.com/migoric/agentia/releases/tag/v0.9.5
+[0.9.4]: https://github.com/migoric/agentia/releases/tag/v0.9.4
+[0.9.3]: https://github.com/migoric/agentia/releases/tag/v0.9.3
+[0.9.2]: https://github.com/migoric/agentia/releases/tag/v0.9.2
+[0.9.1]: https://github.com/migoric/agentia/releases/tag/v0.9.1
+[0.9.0]: https://github.com/migoric/agentia/releases/tag/v0.9.0
+[0.8.3]: https://github.com/migoric/agentia/releases/tag/v0.8.3
+[0.8.2]: https://github.com/migoric/agentia/releases/tag/v0.8.2
+[0.8.1]: https://github.com/migoric/agentia/releases/tag/v0.8.1
+[0.8.0]: https://github.com/migoric/agentia/releases/tag/v0.8.0
+[0.7.2]: https://github.com/migoric/agentia/releases/tag/v0.7.2
+[0.7.1]: https://github.com/migoric/agentia/releases/tag/v0.7.1
+[0.7.0]: https://github.com/migoric/agentia/releases/tag/v0.7.0
+[0.6.3]: https://github.com/migoric/agentia/releases/tag/v0.6.3
+[0.6.2]: https://github.com/migoric/agentia/releases/tag/v0.6.2
+[0.6.1]: https://github.com/migoric/agentia/releases/tag/v0.6.1
+[0.6.0]: https://github.com/migoric/agentia/releases/tag/v0.6.0
+[0.5.0]: https://github.com/migoric/agentia/releases/tag/v0.5.0
+[0.4.2]: https://github.com/migoric/agentia/releases/tag/v0.4.2
+[0.4.1]: https://github.com/migoric/agentia/releases/tag/v0.4.1
+[0.4.0]: https://github.com/migoric/agentia/releases/tag/v0.4.0
+[0.3.0]: https://github.com/migoric/agentia/releases/tag/v0.3.0
+[0.2.2]: https://github.com/migoric/agentia/releases/tag/v0.2.2