fix(consult): 第 0 步改回 auto，供应商 error 块不再被吞掉

BUG-937 撤回 thinking 模式下的 required toolChoice，只留 activeTools。BUG-938 让咨询流识别 Mastra error 块，公开码 calculation_failed，内部码进日志且不触发合同 retry。

docs/BUG_HISTORY.md

@@ -12030,12 +12030,12 @@
 - 用户现象：同 BUG-922。回执只有 skill 与 runtime-contract-retry，没有任何 tool 步骤。
 - 触发条件：同上。
 - 根因：提示词是软约束，`toolChoice: "auto"` 不能保证第 0 步调用排盘工具。申报时段路线甚至没有 `prepareStep`。
-- 修复：第 0 步 `activeTools` 仅排盘工具且 `toolChoice: "required"`；后续步骤 `"auto"`。窗口路线对称加 `prepareStep`，首次 stream 与合同 retry 使用它。`retryForAnswer` / 续写 / 分段仍不强制。未改 `contractReady()`。
+- 修复：第 0 步 `activeTools` 仅排盘工具且 `toolChoice: "auto"`（thinking 模式不得发 named / required，见 BUG-282 / BUG-937）；后续步骤仍 `"auto"`。窗口路线对称加 `prepareStep`，首次 stream 与合同 retry 使用它。`retryForAnswer` / 续写 / 分段仍不强制。未改 `contractReady()`。BUG-937 撤回了本条最初落地的 `required`。
 - 验证：natal / window prepareStep 单测；`route.ts` 源码契约。既有「失败后重试成功仍过门禁」「契约未绿文本丢弃」仍绿。
-- 防复发：本命与窗口第 0 步必须 `required`。思考模式供应商历史上拒 named/required，本仓 Mastra 类型接受 `'required'`；若线上某模型拒收，另立单，不得静默改回 auto 而不改提示词。
-- 相关记录：BUG-214、BUG-286、BUG-922
+- 防复发：本命与窗口第 0 步用 `activeTools` 收窄排盘工具，`toolChoice` 只能是 `auto`。咨询侧源码契约禁止 `required` 与 named `toolChoice`。提示词侧每轮必调（BUG-922）保留。
+- 相关记录：BUG-214、BUG-282、BUG-286、BUG-922、BUG-937、BUG-938
 - 复发自：无
-- 修复版本：待发布
+- 修复版本：`dc2f2a16`（required 已由 BUG-937 撤回）
 
 ## BUG-924 | 校正会话上普通输入框可用，问题发到 `/api/consult`
 
@@ -12253,3 +12253,35 @@
 - 相关记录：BUG-716（`/chart` 白屏 45 秒，另一条链路）
 - 复发自：无
 - 修复版本：未发布
+
+## BUG-937 | 咨询第 0 步 `toolChoice: required` 让全部咨询整轮失败
+
+- 状态：resolved
+- 首次发现：2026-09-17
+- 最近更新：2026-09-17
+- 影响面：`consultationNatalPrepareStep`、`consultationWindowPrepareStep`；本命与申报时段两条咨询路线的每一轮
+- 用户现象：staging 部署 `dc2f2a16` 之后，本命与申报时段会话每一轮都失败，提示「Agent 未完成必要的方法与计算步骤，本次不会扣点。」回执只有 skill 与 runtime-contract-retry，没有任何 tool 步骤。
+- 触发条件：已部署 `dc2f2a16` 的 staging 上发一轮咨询。首轮固定开 thinking。同日晚间本命路线用 `gpt-5.6-luna` 发正经问题时，第 0 步强制工具调用被该供应商接受（事件流走到「正在计算本命盘」），所以「供应商一律拒收 required」不能解释所有模型。
+- 根因：BUG-923 把两条路线的第 0 步改成 `toolChoice: "required"`。BUG-282 实证过至少一个 thinking 供应商拒绝非 auto 的 `tool_choice`（原文 `Thinking mode does not support this tool_choice`）。模型目录可切换，这条路仍会整轮失败。供应商拒收走 Mastra `error` 块，咨询流当时看不见，被翻译成合同未完成（见 BUG-938，本单第一优先）。同日反证：`gpt-5.6-luna` 接受了 `required`，那次截图另立单，不并进本条。
+- 修复：第 0 步撤回 `required`，只留 `activeTools` 收窄到排盘工具，`toolChoice` 为 `"auto"`。BUG-922 的提示词（每轮必调、packet 不跨请求）不动。不在本单尝试第 0 步关 thinking 再发 required。`activeTools` + `auto` 在所有供应商上都成立。
+- 验证：`consultation-agentic-runtime.test.ts` 两条 prepareStep 断言；`consultation-workflow-contract.test.ts` 源码契约禁止 `required` 与 named `toolChoice`。部署后真人走查见 `docs/testing/consult-followup-tool-contract-fix-20260917.md`。
+- 防复发：咨询侧 `consultation-tools.ts` 不得再写 `toolChoice: "required"` 或 named `{ type: "tool", toolName }`；thinking 模式只能用 `activeTools` 收窄。该约束以前只锁在校正 Agent 测试与 BUG-282 文字里，咨询侧无测试、任务书作者未检索到，所以没拦住 BUG-923。
+- 相关记录：BUG-282、BUG-630、BUG-922、BUG-923、BUG-938
+- 复发自：BUG-282
+- 修复版本：`a370bd54`
+
+## BUG-938 | 咨询流不处理 Mastra `error` 块，供应商拒收不可见
+
+- 状态：resolved
+- 首次发现：2026-09-17
+- 最近更新：2026-09-17
+- 影响面：`stream-agent-response.ts` `consumeAttempt`、`agent-observability.ts`
+- 用户现象：同 BUG-937。公开事件没有报错，回执没有 tool 步骤，`modelFinishReason` 为空，错误码被翻译成 `runtime_contract_incomplete`。合同 retry 用同一套选项再失败一次。本命路线在 `gpt-5.6-luna` 上能进计算阶段，说明失败形状不只有「拒收 required」一种，真实错误只能靠本条落地后的日志看到。
+- 触发条件：供应商调用失败（含 thinking 模式拒收非 auto 的 tool_choice，以及其它上游错误）。Mastra 1.50.1 把该失败 enqueue 成 `{ type: "error" }` 后关流，不抛给 `fullStream` 迭代。
+- 根因：`mapChunk` / `consumeAttempt` 不判断 `chunk.type === "error"`。校正 Agent 在 BUG-282 已把这条路做成 `thinking_tool_choice_unsupported`，咨询流没有对齐。本条是本单第一优先。
+- 修复：遇到 `error` 块立即结束本次 attempt，按原文分类为 `thinking_tool_choice_unsupported` 或 `provider_error`，回执追加 `validation model-stream-error failed`。这两个内部码不进公开 `run.failed` 枚举，公开层仍是 `calculation_failed`。供应商错误不触发合同 retry。服务端打 `[consult-provider-error]` 日志（`requestId`、内部码、原文头 200 字，不含请求体）。
+- 验证：`consultation-agentic-runtime.test.ts` 两条假流（thinking 拒收 / upstream 502）：公开码 `calculation_failed`、无 `loading-method`、retry 不调用、`onError` 收到内部码。`agent-observability.test.ts` 把这两个码原样落日志。
+- 防复发：咨询流必须识别 Mastra `error` 块；不得把供应商原文写进公开事件。合同 retry 只用于「没调工具」，不用于供应商拒收。
+- 相关记录：BUG-214、BUG-268、BUG-282、BUG-937
+- 复发自：无
+- 修复版本：`a370bd54`