docs(api): 契约 v0.93 — 审查预算的唯一真源（MEMORY_REVIEW_TIMEOUT_SEC 默认 20→90）

Docs/api-client.md

@@ -20,7 +20,7 @@
 
 > **v0.76 是三面增量版（⚠️ **逐条状态不同**：**① 已在 v0.78 实现、覆盖率又由 v0.79 补齐**；**②③ 已实现**）**：① **消息读取面新增 `toolCalls[]`（工具回看面）—— ✅ 已实现（v0.78，切片 CODE-TC），覆盖率已于 v0.79 补齐至全部编排回合**：`GET /api/v1/sessions/{id}/messages` 的消息对象加可选 `toolCalls`（`omitempty`），每条含工具名 / 状态（`ok`/`error`/`unknown`）/ 耗时毫秒 / **已脱敏**的入参与结果摘要；数据源是**已落盘的轮次链路图**（`flow_graphs`，迁移 `0022`；**v0.78 加迁移 `0023` 的按路查询键**，保留期 168h），**不从正文反解**。🔴 **缺席语义**：图取不到（超保留期 / 该轮未落盘 / 隔离渠道会话从不入库 / 该路标识查不到图）⇒ 字段**整体缺席**，**绝不回空数组**冒充「这一轮没调过工具」。⚠️ **历史说明（v0.76 登记时未实现的原因，实测确认非推断）**：`chat_messages.turn_id` 与 `flow_graphs.turn_id` **不同源** ⇒ 两者无法按消息字面 join，按时间窗猜映射项目口径不做；补齐需先让链路图带上**按路的回合标识**、并补一个**按路查图**的读侧入口。**v0.78 已把这两件都补上** ⇒ `toolCalls[]` 已实现；🔴 **v0.78 时只有真并行路能回看**（普通单路回合的图当时不带权威 `turnId`）—— **已由 v0.79（切片 CODE-TC-2）补齐**（见 **§4.4、§7.2、§7.4-23 与 §6 的 v0.78 ① / v0.79 ④**）。② **未读面（✅ 已实现）** —— `message_persisted` 的 `data` 加**可选** `unreadCount`（`omitempty`：只在 **>0 且确实算得出来**时出现；**缺席 = 老行为**），`GET /api/v1/sessions` 列表项同键（该键**自 D4 起就已在**，本版未改它）。口径 = **绝对未读 + 主人单一已读游标（`chat_sessions.read_at`）⇒ 多端共享**（Web 读了移动端也清），这是与安卓侧已对齐的**取舍**，不是缺陷。详见 **§3.4.4、§4.13**。③ **记忆整理试算加性异步** —— `POST /api/v1/admin/memories/tidy/dry-run?async=1` ⇒ `202` + `runId`；新增 `GET /api/v1/admin/memories/tidy/dry-run/{runId}` 轮询；**不带 `async` 仍是原同步行为**。**无破坏性变更**（新键 / 新可选参数 / 新端点；老客户端零影响）。详见 §1（会话列表与消息读取）、§2.2 B15 / §4.12.1、§3.4.4。
 
-> **v0.77 是链路图按路分桶 + 记忆整理护栏/异步落地版（已实现；纯增量）**：① **`graph_update` 按路分桶**（切片 FV2）—— 帧 `data` 新增可选 `turnId`（该图的**路**的权威回合标识）与 `round`（会话轮次号）；真并行（`parallel:true`）时同一会话**每一路各发自己的帧**（`data.id` / `data.turnId` 各不相同），两路不再互相顶掉；`GET /api/v1/admin/flow/graph` 响应新增 `lanes[]`（**最近一轮每一路**的图，恒为非 null 数组），`graph` 语义不变（最新一路 / 指定轮 / `null` 诚实空态）⇒ **老的读取方零改动**。**无破坏性变更**（两个新键可选；单路时 `turnId` 缺席 ⇒ 客户端行为与 v0.75 逐字相同）。详见 **§2.2 B13 / §3.4.5 / §4.11 / §7.4-19**。② **记忆整理护栏抬高 + 诚实截断 + 试算异步落地**（切片 MT-A）—— 每分区候选上限 `MEMORY_TIDY_CANDIDATE_LIMIT` 默认值 `20 → 200`、两两比对上限改为 env 键新键 `MEMORY_TIDY_COMPARE_LIMIT`（默认 `2000`，原先**写死** `400`）；配置事实面 **12 → 13 条**；`truncated` 新增第 4 种标签 **`(budget)`**（墙钟时间预算截断）；**v0.76 ③ 的加性异步已落地**（`?async=1` + B15 轮询可用；新错误码 **`tidy_run_not_found`**）。详见 **§2.2 B14/B15 / §4.10(a) / §4.12 / §4.12.1 / §5**。③ **「入库前审查」的 4 个 env 键登记**（切片 MT-B，纯增量）—— `MEMORY_REVIEW_ENABLED`（`true`）/ `MEMORY_REVIEW_QUEUE_SIZE`（`256`）/ `MEMORY_REVIEW_SCAN_LIMIT`（`200`）/ `MEMORY_REVIEW_TIMEOUT_SEC`（`20`）；⚠️ 该切片的**面板读侧 / 回滚端点目前没有 HTTP 入口**（见 §7.2）。详见 **§5**。
+> **v0.77 是链路图按路分桶 + 记忆整理护栏/异步落地版（已实现；纯增量）**：① **`graph_update` 按路分桶**（切片 FV2）—— 帧 `data` 新增可选 `turnId`（该图的**路**的权威回合标识）与 `round`（会话轮次号）；真并行（`parallel:true`）时同一会话**每一路各发自己的帧**（`data.id` / `data.turnId` 各不相同），两路不再互相顶掉；`GET /api/v1/admin/flow/graph` 响应新增 `lanes[]`（**最近一轮每一路**的图，恒为非 null 数组），`graph` 语义不变（最新一路 / 指定轮 / `null` 诚实空态）⇒ **老的读取方零改动**。**无破坏性变更**（两个新键可选；单路时 `turnId` 缺席 ⇒ 客户端行为与 v0.75 逐字相同）。详见 **§2.2 B13 / §3.4.5 / §4.11 / §7.4-19**。② **记忆整理护栏抬高 + 诚实截断 + 试算异步落地**（切片 MT-A）—— 每分区候选上限 `MEMORY_TIDY_CANDIDATE_LIMIT` 默认值 `20 → 200`、两两比对上限改为 env 键新键 `MEMORY_TIDY_COMPARE_LIMIT`（默认 `2000`，原先**写死** `400`）；配置事实面 **12 → 13 条**；`truncated` 新增第 4 种标签 **`(budget)`**（墙钟时间预算截断）；**v0.76 ③ 的加性异步已落地**（`?async=1` + B15 轮询可用；新错误码 **`tidy_run_not_found`**）。详见 **§2.2 B14/B15 / §4.10(a) / §4.12 / §4.12.1 / §5**。③ **「入库前审查」的 4 个 env 键登记**（切片 MT-B，纯增量）—— `MEMORY_REVIEW_ENABLED`（`true`）/ `MEMORY_REVIEW_QUEUE_SIZE`（`256`）/ `MEMORY_REVIEW_SCAN_LIMIT`（`200`）/ `MEMORY_REVIEW_TIMEOUT_SEC`（`20`，⚠️ **该默认值已由 v0.93 改为 `90`** —— 当时登记的值是准确的，见 §6 v0.93）；⚠️ 该切片的**面板读侧 / 回滚端点目前没有 HTTP 入口**（见 §7.2）。详见 **§5**。
 
 > **v0.86 是「搜索结果条数上限可配」版（已实现并推库 `bff57bd` + `c68387a`；**纯增量：面板多一个 number 字段 + 两个动作各多一个键；无破坏性变更**）**：`web-search` 的「结果条数上限」从**改不了**变成**面板上真能改**（此前三处断点：字段表里没这个字段 / `saveProvider` 只并四个键 / `mergeSelectionPatch` 只处理 `primary`+`fallback` ⇒ **手工塞进 `values` 也会被静默丢弃**，「我改了它却没变」成立）。① **面板声明**新增字段：`pluginId=web-search` / `panel=providers` / form `add` 多一个 **`maxResults`**（`type:"number"`, `min:1`, 标签「结果条数上限（默认 10）」）—— 前端本就渲染 `number` ⇒ **客户端零改动**。② **`plugin.saveProvider` 的 `values` 新增可写键 `maxResults`**：**三态** —— 缺位/null ⇒ 不改动；**正整数**（含整数字符串）⇒ 采用；`0` / 负数 / 小数 / 空串 / 非数 / 布尔 / 数组 ⇒ **`400 invalid_payload`**，且**盘上一字节不动**（**绝不静默忽略**）。③ 响应新增回显：`plugin.saveProvider` 的 `data.result.maxResults`（**0 = 文件里未声明**）、`plugin.reauthProvider` 的 `values.maxResults`（盘上有值才出现 ⇒ 用于「重配凭据」回填，否则一保存就把上限清掉）。④ **语义**：面板文件的 `maxResults` **压过** `.env` 的 `WEB_SEARCH_MAX_RESULTS`，是**运行期真上限**（模型的 `count` 只能更小），**保存即生效**（走既有热重载，响应里的 `hotReload`）；代码默认值 **5 → 10**（三处口径已一致：env 默认 / io 包 `defaultMaxResults` / 面板文件）。⑤ **计数不变**（无新端点 ⇒ §2.0 维持 `14 + 25 + 40 = 79`）。⚠️ **已知取舍（如实）**：**清空输入框 = `400`**（后端按「非数 ⇒ 报错」拒）⇒ 面板上**没有「去掉上限」的手势**（要回到 `.env` 兜底得改文件）；**小数/负数一律拒**；文件里没写该键时 `reauth` **不回填**（避免回填 0 让保存整笔进不去），因此那个框是空的、看不出当前生效值。
 > **v0.87 是「搜索 provider 扩到八家」版（已实现，纯增量；⚠️ 两家的成功响应都未真机实测）**：新增两家已登记接入位 —— **`tencent_wsa`**（腾讯云·元宝搜索，`POST {base}/SearchPro` + `Authorization: Bearer`，**零签名**；🔴 **HTTP 状态码恒 200** ⇒ 判失败**只能**读响应体 `Response.Error.Code`；`Pages` 是**JSON 字符串数组** ⇒ 需二次解析）与 **`metaso`**（秘塔搜索，`POST {base}/api/v1/search`；⚠️ 响应 schema 全部来自第三方来源且互相打架 ⇒ 实现走**宽松解析、未实测**）。对客户端的**唯一影响是两处名单**：`plugin.saveProvider` 的 `values.provider` 合法闭集（**六家 → 八家**）与 `plugin.providers` 的候选（多两条 `{value,label}`，中文名见 §6 本版条目）—— **端点形状 / 错误码 / 三态写回语义 / §2.0 计数（`14 + 25 + 40 = 79`）全部一字未改**，且前端候选本就是 `optionsFrom` 数据驱动 ⇒ **客户端零改动**。**零新配置键**：两家只走 `$DATA_DIR/config/plugins/web-search.json`，`.env` / `.env.example` **未动**。
@@ -1543,7 +1543,7 @@ curl -s -X POST -H "X-API-Key: $KEY" \
 | `MEMORY_REVIEW_ENABLED` | `true` | **v0.77 登记**：记忆「入库前审查」（`design/23 §15.1 D3`，切片 MT-B）总开关。新记忆落库后由**独立的记忆管理会话**（复用 `sess-memorytidy` 装配）在有界后台队列里判定 `skip`/`merge`/`modify`/`create`，结论以**软合并**回写（`status` + `merged_into`/`merged_from`/`merge_count`，**可 revert、绝不改既有行 `content`**）。`false` ⇒ 组合根不建、不接，写入路径**逐字回到**改动之前。默认开启是因为判定是**纯规则、零模型调用**（T1 灰区模型判定**未实现**） |
 | `MEMORY_REVIEW_QUEUE_SIZE` | `256` | **v0.77 登记**：有界审查队列长度。⚠️ **队列满 ⇒ 该条不做审查**（记忆本身早已落库，**绝不因队列满而丢记忆**），只记一条带来源的 WARN |
 | `MEMORY_REVIEW_SCAN_LIMIT` | `200` | **v0.77 登记**：每条审查在同一分区内最多看多少条既有记忆（top-K 上限） |
-| `MEMORY_REVIEW_TIMEOUT_SEC` | `20` | **v0.77 登记**：单条审查的墙钟上限（秒）。超时 ⇒ **不做任何改写**（记忆照旧保留）+ WARN |
+| `MEMORY_REVIEW_TIMEOUT_SEC` | **`90`**（v0.93 起；v0.77–v0.92 为 `20`） | 单条审查的墙钟上限（秒）。超时 ⇒ **不做任何改写**（记忆照旧保留）+ WARN。🔴 **默认值的唯一真源在 memory 包**（`internal/runtime/memory` 的 `defaultReviewTimeout`）—— 该 env 键**不设自带默认值**，未配置读出 `0` = 「没配」，由 `normalizeReviewConfig` 单点落地；**显式写正数才压过它**（不做「保底抬到 90」的加码）。⚠️ `20s` 已被实测证伪：批量 8 时一条完整召回链墙钟 **21.5–28.2s** ⇒ 20s 预算会让审查**整条失败且不写留痕**（见 §6 v0.93） |
 | （`MEMORY_REVIEW_*` 的共用口径） | — | 上面四个键 **`≤0` 一律视为「用默认」**（由 memory 包 normalize 收敛，避免一个笔误让进程起不来）；召回门**复用 `MEMORY_TIDY_RECALL_THRESHOLD`**，不另立键。⚠️ **本版只登记已实现的部分**：审查的**读侧 / 回滚目前没有 HTTP 端点**（见 §7.2） |
 
 > **上面 13 个键（记忆整理 8 + 后台思考心跳 3 + 安静时段 2）自 v0.68 起可经 `GET /api/v1/admin/config-facts` 读到**「进程生效值 + 声明默认值」（3 个心跳键自 v0.75 起并入、`MEMORY_TIDY_COMPARE_LIMIT` 自 v0.77 起并入）；在此之前面板没有任何 env 读取面。⚠️ `MEMORY_REVIEW_*` 四个键**不在**事实面里（那是「入库前审查」的另一组配置）。
@@ -1573,7 +1573,19 @@ curl -s -X POST -H "X-API-Key: $KEY" \
 > 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。
 > 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。**
 
-### v0.92（当前契约版本）
+### v0.93（当前契约版本）
+
+**「审查预算的唯一真源」版 —— 一个 env 默认值两处副本导致的静默失效**（实现切片 M16；起因 = **塔在部署后读真实启动行时发现** v0.92 那批修复里的 F1 **根本没生效**）
+
+- 🔴 **`MEMORY_REVIEW_TIMEOUT_SEC` 的默认值 `20` → `90`**，并把默认值**收到唯一真源**：它**不再自带 env tag 默认值**，未配置读出 `0` = 「没配」，由 memory 包 `normalizeReviewConfig` 单点落地 `defaultReviewTimeout`。
+  - **未配置 ⇒ `90s`**；**显式写正数 ⇒ 原样生效**（**不做**「保底抬到 90」的加码）；**写 `0` / 负数 ⇒ `90s`**。
+- 🔴 **它修的是一个「看起来改了、其实没改」的事故**：v0.92 那批切片把 memory 包的 `defaultReviewTimeout` 从 `20s` 改成 `90s`，但 config 包的 env tag `default:"20"` **永远产出非零的 20** ⇒ `normalizeReviewConfig` 的「`≤ 0` 才填默认」分支**永远不走** ⇒ **90s 是死代码**，线上启动行仍打印 `timeout=20s`。
+  - **为什么必须修**：批量上限抬到 8 之后，一条完整召回链实测 **21.5–28.2s** ⇒ 20s 预算下审查**整条失败、且不写留痕** ⇒ 召回降级、灰区恒空、T1 发不出调用 ⇒ 「重复记忆收不动」这条链**只修了一半**。
+  - **为什么旧断言拦不住**：既有跨包断言比的是 **memory 包的常量**（「我打算用多少」），而病害发生在**另一个包**（config 的 tag），单包自洽、跨包漂移看不见。本版新增一条**走真实组装路径**的断言（`LoadMemoryReviewConfig` → `ReviewConfig` → `normalizeReviewConfig` → **生效值**，再断言它 > 实测最坏链长 + T1 子超时），并在注释里写明「**比常量 vs 比生效值**」的区别。
+- **兼容性**：**纯行为修复，无 API 形状变化**；`.env` / `.env.example` 文件内容**一字未动**（该键从未进过模板，符合 `.env` 冻结口径）；受影响的只有「没显式配这个键」的部署 —— 它们的单条审查预算由 20s 变 90s。
+- **诚实边界**：若某部署**显式**写了 `MEMORY_REVIEW_TIMEOUT_SEC=20`，本版**不会**替你抬到 90（那是显式配置，尊重它）。另有两处**散文副本**仍写着旧值（`internal/runtime/memory/preinsert_t1.go` 的一处注释），已 file finding、不在本版改动面内。
+
+### v0.92
 
 **「记忆整理调优键可写」版 —— 管理面新增 2 条 `writeAuth` 端点，把面板从「只能改文件 + 重启」救出来**（依据：主人 2026-10-13 口径「`.env` 只做兜底…这些键优先从面板配置上取」「频率必须调…白天间隔短一点、静默期长一点」；实现切片 M4）
 
@@ -1787,7 +1799,7 @@ curl -s -X POST -H "X-API-Key: $KEY" \
 
 - **① `graph_update` 按路分桶（切片 FV2）**：帧 `data` 新增**可选** `turnId`（这张图所属**路**的权威回合标识，与 `turn_begin` / `steer_ack` / 流帧帧壳同值）与 `round`（会话轮次号）；图按 `{会话}#{路}` **归属桶**建（单路的桶逐字等于会话 id ⇒ **单路行为逐字不变**），因此真并行时**每一路各发自己的帧、各落一行**（`flow_graphs` 的唯一键 `(session_id, turn_id)` 不再把另一路整行顶掉）。`GET /api/v1/admin/flow/graph` 响应新增 **`lanes[]`**（最近一轮每一路的图 `[{turnId,graph}]`，按路开始时间升序，恒为非 null 数组；`graph` 仍是「最新一路」⇒ **老的读取方零改动**），前端在 ≥2 路时按**并列泳道**呈现 —— **§2.2 B13 / §3.4.5 / §4.11(a)(d) / §7.2 / §7.4-19**。⚠️ 留白：`turns[]` 仍按**路**列条目（一轮两路显示两条），按轮分组需新迁移 `0023`（**未做**）；Agents 页 / 后台思考页仍只显示最新一路。
 - **② 记忆整理护栏抬高 + 诚实截断 + 试算异步落地（切片 MT-A）**：每分区候选上限 `MEMORY_TIDY_CANDIDATE_LIMIT` 默认 **`20 → 200`**；两两比对上限从**写死的 `400`** 改为 env 键 **`MEMORY_TIDY_COMPARE_LIMIT`（默认 `2000`）**；配置事实面 **12 → 13 条**；`truncated` 新增第 4 种标签 **`(budget)`**（被**墙钟时间预算**截断：整分区跳过，或两两比对中途收手 —— 成因是**本次调用的时间上限**而不是配置配额）；**v0.76 ③ 的加性异步已落地**（`?async=1` + B15 轮询：并发**复用既有 `runId`**、与同步**同一个 3 分钟**墙钟、`done` 的 `result` 与同步 `data` **逐字节同形**、`running` 时 `result`/`error` **双缺席**、重启后旧 `runId` 如实 `404`）—— **§4.10(a) / §4.12 / §4.12.1 / §5**。
-- **③ 「入库前审查」（D3）的 4 个旋钮（切片 MT-B）**：`MEMORY_REVIEW_ENABLED`（`true`）/ `MEMORY_REVIEW_QUEUE_SIZE`（`256`）/ `MEMORY_REVIEW_SCAN_LIMIT`（`200`）/ `MEMORY_REVIEW_TIMEOUT_SEC`（`20`）—— 队列满 ⇒ **该条不审查但记忆不丢**（只 WARN）、超时 ⇒ **零改写** + WARN、`≤0` = 用默认、召回门**复用** `MEMORY_TIDY_RECALL_THRESHOLD`。🔴 **这 4 个键不进 `.env` 模板**（主人 2026-10-06：`.env` 冻结为「只保证最小化功能可跑」的引导面、**不再新增键**）⇒ **有效行为 = 上面这组代码默认值**，调优入口将由**配置文件 / 面板**提供（**未接线**）。⚠️ 该切片的**面板读侧端点（`GET /admin/memories/reviews`）与回滚端点（`POST /admin/memories/{id}/revert`）目前没有 HTTP 入口**，**本版不登记为可用**（见 §7.2）。
+- **③ 「入库前审查」（D3）的 4 个旋钮（切片 MT-B）**：`MEMORY_REVIEW_ENABLED`（`true`）/ `MEMORY_REVIEW_QUEUE_SIZE`（`256`）/ `MEMORY_REVIEW_SCAN_LIMIT`（`200`）/ `MEMORY_REVIEW_TIMEOUT_SEC`（`20`，⚠️ **默认值已由 v0.93 改为 `90`** —— 键名与文件内容未动，只是代码侧默认值，见 §6 v0.93）—— 队列满 ⇒ **该条不审查但记忆不丢**（只 WARN）、超时 ⇒ **零改写** + WARN、`≤0` = 用默认、召回门**复用** `MEMORY_TIDY_RECALL_THRESHOLD`。🔴 **这 4 个键不进 `.env` 模板**（主人 2026-10-06：`.env` 冻结为「只保证最小化功能可跑」的引导面、**不再新增键**）⇒ **有效行为 = 上面这组代码默认值**，调优入口将由**配置文件 / 面板**提供（**未接线**）。⚠️ 该切片的**面板读侧端点（`GET /admin/memories/reviews`）与回滚端点（`POST /admin/memories/{id}/revert`）目前没有 HTTP 入口**，**本版不登记为可用**（见 §7.2）。
 - **行为变更**：无（① 两个新键可选、`lanes[]` 纯增量、单路行为逐字不变；② 只改默认值 / 新增一个截断标签，同步试算的响应形状未变；③ 只多了一组**以代码默认值生效**的旋钮，**不进 `.env`**、不改变任何既有行为）。
 - **破坏性**：无。
 - **⚠️ 诚实边界**：① 真并行**未做真机端到端**（线上产物是旧构建；真并行是在单测层用「真 `Loop.Run` × 2 + 网关照同的 ctx 通道」复现的）—— 见 §7.4-24；② 上面 ②「抬高后真机 `compared == scanned`」**尚未被真机证实**（只有单测与量级推算支持）；③ MT-B 的入库前审查**未在生产库上跑过**。