@jsonstudio/rcc 0.90.872 → 0.90.1270

package/docs/audit/286.1-provider-failure-policy-audit.md

@@ -0,0 +1,341 @@
+# 286.1 全局审计：Provider Failure Policy 重复实现
+
+## 索引概要
+- L1-L10 `summary`：审计结论总览。
+- L12-L25 `scope`：审计范围。
+- L27-L120 `request-executor-audit`：request-executor.ts 内部决策点清单。
+- L122-L175 `executor-provider-audit`：executor-provider.ts 决策点清单。
+- L177-L220 `classifier-audit`：provider-error-classifier.ts 决策点清单。
+- L222-L260 `quota-audit`：quota-state.ts 决策点清单。
+- L262-L310 `router-health-audit`：Virtual Router health 决策点清单。
+- L312-L350 `overlap-summary`：交叉重复矩阵。
+- L352-L420 `migration-targets`：迁移去向标记。
+
+---
+
+## 审计结论总览
+
+| 维度 | 重复真源数 | 主要 owner（当前 active path） | 迁移目标 |
+|------|-----------|------------------------------|----------|
+| recoverability 分类 | **3** | request-executor `resolveRequestExecutorProviderErrorClassification` + executor-provider `shouldRetryProviderError` + classifier `classifyProviderError` | → ProviderFailurePolicy.classify |
+| blocking recoverable 判定 | **2** | request-executor `isBlockingRecoverableRetryError` + `shouldApplyProviderTransportBackoff` | → ProviderFailurePolicy.isBlockingRecoverable |
+| exclusion 决策 | **1** | request-executor `resolveProviderRetryExclusionPlan` | → ProviderFailurePolicy.decide.exclusion |
+| health 影响 | **3** | request-executor `isHealthNeutralProviderError` + classifier `affectsHealth` + router-health event handler | → ProviderFailurePolicy.decide.health |
+| retry 门控 | **2** | request-executor `resolveProviderRetryEligibilityPlan` + executor-provider `shouldRetryProviderError` | → ProviderFailurePolicy.decide.action |
+| backoff 计算 | **4** | request-executor 3× consume-function + executor-provider `computeRetryDelayMs` | → ProviderFailurePolicy.backoff + 统一 consume |
+| network error 判定 | **2** | request-executor `isNetworkTransportLikeError` + executor-provider `isNetworkTransportError` + classifier `looksLikeNetworkTransportError` | → 统一 shared predicate |
+
+---
+
+## 审计范围
+
+| 文件 | 行数 | 角色 |
+|------|------|------|
+| `src/server/runtime/http-server/request-executor.ts` | ~4550 | Host 执行器（orchestrator + policy helper 堆积） |
+| `src/server/runtime/http-server/executor-provider.ts` | ~400 | Provider runtime 轮询/退避工具 |
+| `src/providers/core/runtime/provider-error-classifier.ts` | ~230 | Provider runtime 独立分类器 |
+| `sharedmodule/llmswitch-core/src/quota/quota-state.ts` | ~210 | Quota 冷却状态机 |
+| `sharedmodule/llmswitch-core/src/router/virtual-router/engine/health/index.ts` | ~950 | VR health event handler |
+| `src/providers/core/runtime/provider-error-reporter.ts` | **NOT EXISTS** | 已删除或未创建 |
+
+---
+
+## request-executor.ts 内部决策点
+
+### A1. resolveRequestExecutorProviderErrorClassification (L895-L973)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | classify error → `recoverable` / `unrecoverable` / `special_400` / `undefined` |
+| 依据 | stage → client disconnect → status 400 → CONTEXT_LENGTH_EXCEEDED → INVALID_REQUEST_ERROR → status 401/402/403 → 10个 unrecoverable code → reason substring |
+| 独占? | **否**。与 `shouldRetryProviderError` 冲突：401 在此为 unrecoverable，在 shouldRetryProviderError 为 retryable |
+| 迁移去向 | → `ProviderFailurePolicy.classify` |
+
+### A2. isBlockingRecoverableRetryError (L1276-L1317)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 判定错误是否为"阻塞可恢复"（需要指数退避而非快速重试） |
+| 依据 | status 408/425/429/≥500; errorCode PROVIDER_TRAFFIC_SATURATED/HTTP_429/500/502/503/504/SSE_TO_JSON_ERROR/SSE_DECODE_ERROR/UPSTREAM_EMPTY_OUTPUT; reason fetch_failed/network/timeout |
+| 独占? | **否**。与 `shouldApplyProviderTransportBackoff` 大量重叠（429/408/425/≥500/PROVIDER_TRAFFIC_SATURATED）；与 `shouldRetryProviderError` 重叠（408/425/429/≥500） |
+| 迁移去向 | → `ProviderFailurePolicy.isBlockingRecoverable` |
+
+### A3. shouldBlockRetryOnCurrentProvider (L1319-L1326)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 纯 1:1 委托 `isBlockingRecoverableRetryError` |
+| 独占? | **死代码别名**，零独特逻辑 |
+| 迁移去向 | → 删除，调用方直接用 policy |
+
+### A4. resolveProviderRetryExclusionPlan (L2670-L2771)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 是否从 route pool exclude 当前 provider |
+| 路径 | promptTooLong→exclude; trafficSaturated→don't exclude; network→don't exclude; no-alt-candidate→don't exclude; antigravity verify/429→exclude; antigravity reauth→exclude; non-antigravity→exclude |
+| 独占? | **是**（file 内唯一 exclusion 决策者） |
+| 迁移去向 | → `ProviderFailurePolicy.decide.exclusion` |
+
+### A5. resolveProviderRetryExecutionPlan (L1846-L2000)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 编排器：组合 eligibility + exclusion + hold + backoff + switch |
+| 独占? | **是**（orchestrator only）；唯一独有逻辑：`unrecoverable + exclude_and_reroute + no-alt → no retry` |
+| 迁移去向 | → orchestrator（调用 policy，不再自带逻辑） |
+
+### A6. resolveProviderRetryEligibilityPlan (L1772-L1834)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | `shouldRetry` boolean |
+| 独占? | **是**（file 内唯一门控），但最终委托 `shouldRetryProviderError` |
+| 迁移去向 | → `ProviderFailurePolicy.decide.shouldRetry` |
+
+### A7. resolveProviderRetryBackoffPlan (L2252-L2355)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 选择 backoff scope（attempt/provider/recoverable）+ 计算延迟 |
+| 独占? | **是**（file 内唯一 scope 选择者） |
+| 迁移去向 | → `ProviderFailurePolicy.decide.backoff` |
+
+### A8. resolveProviderRetrySwitchPlan (L2357-L2400)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | switchAction label + runtime-scope expansion |
+| 独占? | **是** |
+| 迁移去向 | → 保持为 orchestrator 内标签计算 |
+
+### A9. isLastAvailableProvider429 (L975-L995)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | "最后一个 provider 遇到 429"检测 |
+| 独占? | **是** |
+| 迁移去向 | → `ProviderFailurePolicy.decide.holdOnLastProvider` |
+
+### A10. isHealthNeutralProviderError (L1097-L1144)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 错误是否**不影响** provider health |
+| 依据 | followup/host stage → special_400 → recoverable → CLIENT_DISCONNECTED → PROVIDER_TRAFFIC_SATURATED → CLIENT_TOOL_ARGS_INVALID → network → server-tool-followup → CLIENT_INJECT_FAILED |
+| 独占? | **否**。与 classifier `affectsHealth` 冲突（classifier 认为 500/affectsHealth=true，此函数认为 recoverable errors 不影响 health） |
+| 迁移去向 | → `ProviderFailurePolicy.decide.health` |
+
+### A11. shouldApplyProviderTransportBackoff (L998-L1029)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 是否记录 transport backoff |
+| 依据 | followup/host→false; network→true; status 429/408/425/≥500/PROVIDER_TRAFFIC_SATURATED→true; classification=recoverable→true |
+| 独占? | **否**。与 isBlockingRecoverableRetryError 几乎完全重叠 |
+| 迁移去向 | → `ProviderFailurePolicy.isBlockingRecoverable`（合并） |
+
+### A12-A14. Backoff consume functions
+
+| 函数 | 行 | state map | 迁移 |
+|------|-----|-----------|------|
+| `consumeRecoverableErrorBackoffMs` | L1387 | `recoverableErrorBackoffState` | → 统一 backoff engine |
+| `consumeProviderScopedRetryBackoffMs` | L1497 | `recoverableErrorBackoffState`（共享!） | → 统一 backoff engine（修复 state 共享 bug） |
+| `consumeProviderTransportBackoffMs` | L1569 | `providerTransportBackoffState`（独立） | → 统一 backoff engine |
+
+**注意**：consumeProviderScopedRetryBackoffMs 和 consumeRecoverableErrorBackoffMs 共享同一个 state map，key 碰撞时 consecutive 计数器会互相干扰。
+
+### A15. isNetworkTransportLikeError (L1430-L1463)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 错误是否为 network/transport 类型 |
+| 独占? | **否**。executor-provider.ts 有独立的 `isNetworkTransportError`（不同 name 但相同语义）；classifier 有 `looksLikeNetworkTransportError` |
+| 迁移去向 | → 统一 shared predicate |
+
+### A16-A17. Backoff cap 函数
+
+| 函数 | 行 | 范围 | cap 429 | cap default |
+|------|-----|------|---------|-------------|
+| `resolveRecoverableBackoffCapMs` | L1363 | recoverable | 800/4000ms | 5000/120000ms |
+| `resolveProviderScopedRetryBackoffCapMs` | L1465 | provider-scoped | 800/30000ms | 15000/60000ms |
+
+### A18. isProviderTrafficSaturatedRetryError (L2658-L2669)
+
+| 字段 | 值 |
+|------|------|
+| 独占? | **否**。isBlockingRecoverableRetryError 重复检查 PROVIDER_TRAFFIC_SATURATED；resolveProviderRetrySwitchPlan 内联独立判断 |
+
+### A19. applyRetryExclusionForCurrentProvider (L2646-L2656)
+
+| 字段 | 值 |
+|------|------|
+| 独占? | **是**（file 内唯一 exclusion mutation point） |
+
+### A20. hasAlternativeRouteCandidate / hasExplicitAlternativeRouteCandidate
+
+| 函数 | 空 pool 行为 | 调用方 |
+|------|-------------|--------|
+| `hasAlternativeRouteCandidate` L2001 | pool 空→return `true`（permissive） | isLastAvailableProvider429, resolveProviderRetryExecutionPlan |
+| `hasExplicitAlternativeRouteCandidate` L2804 | pool 空→return `false`（strict） | resolveProviderRetryExclusionPlan |
+
+**语义不一致**：permissive/strict 是故意设计，但维护风险高。
+
+---
+
+## executor-provider.ts 决策点
+
+### B1. shouldRetryProviderError (L99-L155)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 错误是否 retryable |
+| 依据 | client disconnect→no; prompt too long→no; virtualRouterSeriesCooldown→yes; GLM 514→yes; deterministic invalid request→no; status 401/429/413/408/425→yes; ≥500→yes; error.retryable flag; network→yes |
+| 与 A1 冲突 | **401**: 此函数→retryable; A1→unrecoverable |
+| 迁移去向 | → `ProviderFailurePolicy.classify.retryable`（合并） |
+
+### B2. isNetworkTransportError (L69-L97)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 网络/传输错误检测 |
+| 与 A15 关系 | **几乎相同**，code set + hints 略有差异（多了 `client network socket disconnected` 等） |
+| 迁移去向 | → 统一 shared predicate |
+
+### B3. computeRetryDelayMs / waitBeforeRetry (L241-L375)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 计算重试延迟（含 Retry-After header 解析） |
+| 迁移去向 | → 保持为通用 wait 工具，延迟值由 policy 产出 |
+
+---
+
+## provider-error-classifier.ts 决策点
+
+### C1. classifyProviderError (L65-L171)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | `recoverable` + `affectsHealth` 双布尔 |
+| 与 request-executor 关系 | **独立的第二中心**。500→这里 recoverable=false,affectsHealth=true; request-executor A1→recoverable（非 special_400/unrecoverable） |
+| 迁移去向 | → 删除或降为 thin adapter，consumes ProviderFailurePolicy |
+
+### C2. looksLikeNetworkTransportError (L175-L190)
+
+| 字段 | 值 |
+|------|------|
+| 与 A15/B2 关系 | **第三份**网络错误检测，hint 列表略有差异 |
+| 迁移去向 | → 统一 shared predicate |
+
+---
+
+## quota-state.ts 决策点
+
+### D1. normalizeErrorSeries (L49-L70)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 错误→ErrorSeries（E429/E5XX/ENET/EFATAL/EOTHER） |
+| 依据 | status 429/RATE/QUOTA→E429; ≥500→E5XX; TIMEOUT/network codes→ENET; AUTH/FATAL→EFATAL |
+| 与 request-executor 关系 | **独立分类维度**，无直接重叠（quota 是 cooldown 驱动，非 retry 决策） |
+| 迁移去向 | → **保留**（quota 是独立消费者，消费 policy 产出的 classification） |
+
+### D2. applyErrorEvent (L156-L210)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | cooldown schedule + keepPool 逻辑 |
+| 迁移去向 | → **保留**，但 event 应携带 policy 产出的 classification |
+
+---
+
+## Virtual Router Health 决策点
+
+### E1. handleProviderErrorEvent (health/index.ts ~L586-L620)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | 根据 event reason + statusCode 触发 tripProvider / cooldownProvider |
+| 与 request-executor 关系 | **独立的 health 投影**。event 上的 reason/statusCode 由 request-executor 传入，但 VR 侧自己重新判定冷却时长 |
+| 迁移去向 | → VR 只消费 policy 产出的 `affectsHealth` + cooldown duration，不再自行判定 |
+
+### E2. 429 阶梯退避 (health/index.ts ~L131-L140)
+
+| 字段 | 值 |
+|------|------|
+| 决策 | VR 内部维护 429 退避计数（与 host 侧 backoff 独立） |
+| 迁移去向 | → **保留**（VR 路由决策层面的退避，与 host retry 层面的退避正交） |
+
+---
+
+## 交叉重复矩阵
+
+| 决策维度 | request-executor | executor-provider | classifier | quota | router-health |
+|----------|:---:|:---:|:---:|:---:|:---:|
+| 429 检测 | A1/A2/A11 | B1 | C1 | D1 | E1 |
+| 5xx 检测 | A1/A2/A11 | B1 | C1 | D1 | — |
+| 401 处理 | A1(unrecoverable) | B1(retryable) | C1(unrecoverable) | — | — |
+| network 检测 | A15 | B2 | C2 | D1 | — |
+| PROVIDER_TRAFFIC_SATURATED | A2/A11/A18 | — | — | — | — |
+| affectsHealth | A10 | — | C1 | — | E1 |
+| backoff timing | A12-A14,A16-A17 | B3 | — | D2 | E2 |
+| exclusion | A4 | — | — | — | — |
+| retry 门控 | A6 | B1 | — | — | — |
+
+**关键冲突**：401 在 A1(unrecoverable) vs B1(retryable) 语义矛盾。
+
+---
+
+## 迁移去向标记
+
+### → ProviderFailurePolicy（新模块）
+
+| 原函数 | 迁移后 |
+|--------|--------|
+| A1 resolveRequestExecutorProviderErrorClassification | → `Policy.classify` |
+| A2 isBlockingRecoverableRetryError | → `Policy.isBlockingRecoverable` |
+| A11 shouldApplyProviderTransportBackoff | → 合并入 `Policy.isBlockingRecoverable` |
+| A4 resolveProviderRetryExclusionPlan | → `Policy.decide.exclusion` |
+| A6 resolveProviderRetryEligibilityPlan | → `Policy.decide.shouldRetry` |
+| A7 resolveProviderRetryBackoffPlan | → `Policy.decide.backoff` |
+| A9 isLastAvailableProvider429 | → `Policy.decide.holdOnLastProvider` |
+| A10 isHealthNeutralProviderError | → `Policy.decide.health` |
+| B1 shouldRetryProviderError | → 合并入 `Policy.classify`（解决 401 冲突） |
+| C1 classifyProviderError | → 删除/降级为 adapter |
+
+### → 统一 shared predicate
+
+| 原函数 | 统一后 |
+|--------|--------|
+| A15 isNetworkTransportLikeError | → `shared/is-network-error.ts` |
+| B2 isNetworkTransportError | → 删除，用统一 |
+| C2 looksLikeNetworkTransportError | → 删除，用统一 |
+
+### → 删除
+
+| 原函数 | 原因 |
+|--------|------|
+| A3 shouldBlockRetryOnCurrentProvider | 纯别名 |
+| A18 isProviderTrafficSaturatedRetryError | 内联重复 |
+| A20a/A20b hasAlternative/ExplicitAlternative | → 保留但文档化 permissive/strict 语义 |
+
+### → 保留（独立消费者）
+
+| 模块 | 原因 |
+|------|------|
+| D1/D2 quota-state | cooldown 消费者，不是 policy 产出者 |
+| E2 VR 429 退避 | 路由层面正交于 host retry |
+| B3 waitBeforeRetry | 通用等待工具，延迟由 policy 产出 |
+
+### → 需修复 state 共享 bug
+
+| 问题 | 位置 |
+|------|------|
+| `consumeProviderScopedRetryBackoffMs` 和 `consumeRecoverableErrorBackoffMs` 共享 `recoverableErrorBackoffState` | A13/A12 |
+
+---
+
+*审计完成时间：2026-04-27*
+*审计人：RouteCodex Bot*
+*下一步：W2 抽单一 ProviderFailurePolicy 策略块（routecodex-286.2）*

package/docs/audits/2026-04-26-fallback-silent-failure-audit.md

@@ -0,0 +1,119 @@
+# RouteCodex 全局审计：fallback / 静默失败（2026-04-26）
+
+## 执行命令
+
+```bash
+node scripts/ci/silent-failure-audit.mjs --json
+```
+
+## 结果快照
+
+- 扫描文件数：`1295`
+- 风险 catch 块：`510`（模式匹配，含合法 best-effort + 已修复的 MAIN_PATH_RISK）
+- 风险 promise.catch：`15`
+
+## 已修复的 MAIN_PATH_RISK（按语义修复，非模式计数）
+
+### 第一轮：观测性提升（补 non-blocking 日志，保留返回语义）
+
+1. `src/server/runtime/http-server/request-executor.ts`
+   - `previous.catch(() => undefined)` → 节流 non-blocking 日志。
+
+2. `src/server/runtime/http-server/daemon-admin/quota-handler.ts`
+   - `getRawSnapshot` / `loadTokenPortalFingerprintSummary` / `findGoogleAccountVerificationIssue` catch 补日志。
+
+3. `src/utils/snapshot-request-retention.ts`
+   - `readdir/stat/rm` catch 补日志（ENOENT 按边界放过）。
+
+4. `src/server/runtime/http-server/session-scope-resolution.ts`
+   - decode/base64/json/url-params/isAlive catch 补日志。
+
+5. `src/providers/core/runtime/deepseek-http-provider.ts`
+   - queue gate / SSE 解析 / 业务错误解析 / destroy 清理 catch 补日志。
+
+6. `src/providers/core/config/camoufox-launcher.ts`
+   - `runCamoCliCheck/profileDirExists/loadFingerprintEnv/portalUrlParse/localCallbackParse` catch 补日志。
+
+### 第二轮：主链语义修复（错误必须传播，不得吞掉）
+
+7. `src/modules/llmswitch/bridge/antigravity-signature.ts`
+   - **L56 `loadAntigravitySignatureModule`**：不再永久缓存 null。瞬态 require 失败后下次调用重试。
+   - **L92 `extractAntigravityGeminiSessionId`**：`return undefined` → `throw`。错误不再静默消失。
+   - **L140 `getAntigravityLatestSignatureSessionIdForAlias`**：同上，`throw` 替代 `return undefined`。
+   - **L161 `lookupAntigravitySessionSignatureEntry`**：同上。
+   - 修复前模式：log + return undefined → 请求无签名静默发出。修复后：log + throw → 上层 provider 能看到错误。
+
+8. `src/providers/auth/oauth-auth.ts`
+   - **L133 `validateCredentials`**：refresh 失败时 status 消息包含具体 error message。
+   - **L344 `saveToken`**：磁盘持久化失败不再吞错，`throw error`。
+   - **L364 `loadToken`**：非 ENOENT 错误（损坏 JSON / 权限）不再吞掉，`throw error`。
+   - **L389 `ensureTokenFileExists`**：文件/目录创建失败不再吞错，`throw error`。
+
+9. `src/providers/auth/token-storage/token-persistence.ts`
+   - **L19 `readTokenFromFile`**：非 ENOENT 错误（损坏 JSON / 权限）`throw error`，不再一律返回 null。
+   - **L63 `restoreTokenFileFromBackup`**：恢复失败 `throw error`，不再只打日志。
+
+10. `src/providers/core/strategies/oauth-auth-code-flow.ts`
+    - **L214 `authenticate.update_redirect_uri`**：redirect-URI 参数应用失败 `throw error`。
+    - **L371 `start_callback_server.parse_redirect_uri`**：redirect-URI 解析失败 `throw error`。
+    - 修复前：失败后静默 fallback 到默认 localhost:8080/oauth2callback → callback 永远收不到。
+
+11. `sharedmodule/llmswitch-core/src/servertool/server-side-tools.ts`
+    - **L393 `replaceJsonObjectInPlace`**：移除 try/catch，改为 copy-before-delete 排序。先写新属性再删旧 key，消除半删除的中间态风险。
+
+## 保留 BEST_EFFORT_OK 的分类（审计结论）
+
+以下 catch 块经审查确认为合理 best-effort / 观测 / 清理路径，保留原语义：
+
+- `antigravity-user-agent.ts`（4）：磁盘缓存 / 远程版本探测 → floor version fallback 是设计意图。
+- `http-transport-provider.ts`（4）：logger 保护 / 超时保护 → 内部 logNonBlockingError 体系。
+- `runtime-exit-forensics.ts`（4）：forensic read/write/pid-check → 纯观测。
+- `provider-response.ts`（4）：model override / conversation capture / usage persistence → 不影响响应交付。
+- `server-side-tools.ts`（其余 9）：trace callback / JSON.stringify 降级 / retry loop / error rethrow → 无吞错。
+- CLI 层 `session-inject/guardian/client/camoufox-fp/index.ts` 等 15 个 `.catch(() => null)` → CLI / 启动路径，非主链。
+
+### 第三轮：token-daemon 主链修复
+
+12. `src/token-daemon/token-daemon.ts`
+    - **L288 `tick.loadRouteCodexConfig`**：config 加载失败改为 `throw`。修复前：`configuredProviders = new Set()` 导致本 tick 所有 token refresh 全部跳过，零可见性。
+    - **L741 `ensurePortalEnvironment`**：移除 boolean-return wrapper（仅 `logDebug`，生产关闭）。改为直接 `await`；调用方 L395 用 `try/catch` + `console.error` + `logTokenDaemonNonBlockingError` 确保 portal 失败可见。
+
+## 全局趋势
+
+- 第一轮（观测性）：风险 catch `538 → 510`（-28），promise.catch `22 → 15`（-7）
+- 第二轮（语义修复）：11 处 MAIN_PATH_RISK 从"吞错"改为"throw/重试/消除中间态"
+- 第三轮（token-daemon）：2 处 MAIN_PATH_RISK 改为 throw + 可见错误
+
+## 第四轮：全局分层审计（最终扫描结果）
+
+### 已审查确认 BEST_EFFORT_OK 的文件（全部 catch 块均为主链无关）
+
+| 文件 | catch 数 | 理由 |
+|------|:--------:|------|
+| `antigravity-user-agent.ts` | 4 | 磁盘缓存 / 远程版本探测 → floor version fallback 是设计意图 |
+| `http-transport-provider.ts` | 4 | logger 保护 / 超时保护 → 内部 logNonBlockingError 体系 |
+| `runtime-exit-forensics.ts` | 4 | forensic read/write/pid-check → 纯观测 |
+| `provider-response.ts` | 4 | model override / conversation capture / usage persistence → 不影响响应交付 |
+| `server-side-tools.ts` | 9 | trace callback / JSON.stringify 降级 / retry loop / error rethrow → 无吞错 |
+| `oauth-auth-code-flow.ts` | 17 | L214/L371 已修复；其余为 retry loop / callback / listen / cleanup → 正确 rethrow 或 best-effort |
+| 4 × pipeline-semantics | 32 | 全部为 parser fallback（`return null` → pipeline fail-fast at validation）+ `fail('invalid payload')` |
+| `ai-followup.ts` | 9 | process spawn/kill/cleanup/file read/logging → 非阻断 |
+| `pending-session.ts` | 5 | file resolution / stale cleanup / pending read → best-effort |
+| `provider-response-converter.ts` | 10 | JSON parse fallbacks / tool call recovery → 非阻断 |
+| `sse-error-handler.ts` | 3 | error normalization → best-effort |
+| `managed-process-probe.ts` | 7 | pid probe / kill / command read → best-effort |
+| `session-storage-cleanup.ts` | 8 | 全部带 non-blocking 日志 → cleanup 路径 |
+| `tmux-session-probe.ts` | 9 | 全部带 non-blocking 日志或结构化 error return → probe 路径 |
+| `request-id-manager.ts` | 3 | persistence best-effort → 计数器回退到内存 |
+
+### 15 个 `.catch(() => null/undefined)` 确认为非主链
+
+CLI 层（`session-inject` / `guardian/client` / `camoufox-fp` / `index.ts`）、warmup、quota serialized-write chain、token portal → 全部为 CLI / 启动路径 / best-effort 非主链。
+
+### 全局结论
+
+- **已修复 MAIN_PATH_RISK：15 处**（第一轮 0 + 第二轮 11 + 第三轮 2 + replaceJsonObjectInPlace 1 + session storm backoff 1）
+- **剩余 MAIN_PATH_RISK：0**（经 explorer + 手动逐文件审查确认）
+- **扫描器 catchRiskCount：509**（全部为 BEST_EFFORT_OK / LOGGING_ONLY / parser-fallback）
+
+> 注：审计扫描器按 `catch` 模式计数，不会因 throw 修复而减少计数。509 个 catch 经分层审查均不在主链上。

package/docs/audits/2026-04-27-provider-failure-policy-ssot-audit.md

@@ -0,0 +1,153 @@
+# 2026-04-27 Provider Failure Policy SSOT 审计
+
+## 索引概要
+- L1-L8 `purpose`：审计目标与范围。
+- L10-L28 `live-evidence`：线上证据与已确认现象。
+- L30-L72 `duplicate-policy-centers`：重复实现清单。
+- L74-L103 `active-path-conflicts`：当前 active path 冲突点。
+- L105-L126 `migration-target`：每个重复点的迁移去向。
+- L128-L139 `next-step`：下一步执行顺序。
+
+## 目的
+审计 RouteCodex 当前 provider 执行期错误处理链中所有“第二中心”，确认：
+- recoverability
+- affectsHealth
+- retry/reroute
+- backoff
+
+这些事实目前分别由谁定义、哪些属于 active path、哪些会造成线上风暴。
+
+## 线上证据
+已确认线上日志同时存在以下现象：
+
+1. **当前请求主链已部分修正**
+- `switch=retry_same_provider`
+- `decision=recoverable_backoff_same_provider`
+- `backoffScope=recoverable`
+
+说明 `request-executor` 对 `provider.send` 上的 `SQLITE_BUSY / new_api_error` 已不再默认走 `exclude_and_reroute`。
+
+2. **并发 sibling 请求仍被毒化**
+- 在 recoverable same-provider backoff 之后，仍立即出现多个：
+  - `openai-responses-unknown-unknown-*`
+  - `PROVIDER_NOT_AVAILABLE`
+
+这证明 storm 的剩余来源不是“当前请求 retry plan”本身，而是**其他 active path 仍在把 provider health/cooldown 打坏**。
+
+## 重复实现清单
+
+### A. request-executor（active path）
+文件：`src/server/runtime/http-server/request-executor.ts`
+
+当前承载：
+- `resolveRequestExecutorProviderErrorClassification(...)`
+- `isHealthNeutralProviderError(...)`
+- `resolveProviderRetryEligibilityPlan(...)`
+- `resolveProviderRetryExclusionPlan(...)`
+- `resolveProviderRetryBackoffPlan(...)`
+- `resolveProviderRetryExecutionPlan(...)`
+
+性质：**active path，当前 host 主策略中心**
+
+问题：
+- 它已经形成一套完整 policy，但仓内还有别处也在定义同一事实。
+
+### B. provider runtime classifier（active path）
+文件：`src/providers/core/runtime/provider-error-classifier.ts`
+
+当前承载：
+- `recoverable`
+- `affectsHealth`
+- `forceFatalRateLimit`
+
+性质：**active path，第二中心**
+
+已确认冲突：
+- generic `500`：`recoverable=false`、`affectsHealth=true`
+- 短期 `429`：`recoverable=true`、但 `affectsHealth=true`
+
+这与当前全局规则冲突：
+- recoverable => block + exponential backoff
+- recoverable => health-neutral
+- unrecoverable => direct return
+
+### C. provider base-provider emit path（active path）
+文件：`src/providers/core/runtime/base-provider.ts`
+
+当前承载：
+- 直接消费 `classifyProviderError(...)`
+- 直接把 `recoverable/affectsHealth` 写入 `emitProviderError(... stage='provider.http')`
+
+性质：**active path，第二中心的下游发射器**
+
+风险：
+- 即使 `request-executor` 已在 `provider.send` 把错误当 recoverable + health-neutral 处理，
+  provider runtime 仍可能通过 `provider.http` 路径把 router health 毒化。
+
+### D. provider-error-reporter（active path）
+文件：`src/providers/core/utils/provider-error-reporter.ts`
+
+当前承载：
+- 当调用方未显式给 `affectsHealth` 时，默认落到 `true`
+- 当调用方未显式给 `recoverable` 时，回退到 `err.retryable === true`
+
+性质：**active path，policy fallback 第二中心**
+
+问题：
+- reporter 不应再脑补 policy。
+- 它应该只透传已决策好的语义，而不是“帮忙猜”。
+
+### E. executor-provider / retry-engine（compat/残留策略点）
+文件：
+- `src/server/runtime/http-server/executor-provider.ts`
+- `src/server/runtime/http-server/executor/retry-engine.ts`
+
+当前承载：
+- `shouldRetryProviderError(...)`
+- `computeRetryDelayMs(...)`
+- `waitBeforeRetry(...)`
+
+性质：**半 active，仍参与 host 决策**
+
+问题：
+- “要不要重试”与“退避时间”不应散落为另一套半独立规则。
+
+## 当前 active path 冲突点
+
+### 冲突 1：host 认为 recoverable，provider runtime 认为 fatal/poison
+- host `request-executor`：`SQLITE_BUSY / 500 new_api_error` 已改成 recoverable same-provider backoff
+- provider runtime classifier：generic 500 仍当 `recoverable=false + affectsHealth=true`
+
+结果：
+- 当前请求本身不再 storm
+- sibling/fresh 请求仍因 provider health 被旧路径毒化而掉进 `PROVIDER_NOT_AVAILABLE`
+
+### 冲突 2：429 仍有 health 污染
+- host 新规则：recoverable 应 health-neutral
+- provider runtime 旧规则：短期 429 仍 `affectsHealth=true`
+
+结果：
+- 即使局部 backoff 正常，健康状态仍会被 router 看成 provider 不可用，继续制造风暴式旁路失败。
+
+### 冲突 3：reporter 仍有默认脑补
+- 若 caller 少传 policy 字段，reporter 仍会回退为 `affectsHealth=true`
+
+结果：
+- 即使上游开始收口，也可能被 reporter 再次改坏语义。
+
+## 迁移去向
+
+| 现有点 | 性质 | 迁移去向 |
+| --- | --- | --- |
+| `request-executor` classification/backoff/exclusion helpers | active | 收进单一 `ProviderFailurePolicy`，executor 只执行 decision |
+| `provider-error-classifier.ts` | active second center | 降为 thin adapter 或删除 |
+| `base-provider.ts` 的 `recoverable/affectsHealth` 自产逻辑 | active second center consumer | 改成只上报 transport/context 原始事实 |
+| `provider-error-reporter.ts` 默认 `affectsHealth/recoverable` fallback | active second center | 改成 fail-closed：缺字段即调用方 bug |
+| `executor-provider.ts` retry/backoff helpers | compat/半 active | 仅保留 sleep primitive，不再定义 policy |
+
+## 下一步
+1. 完成 `286.1`：以本审计为基础补充 owner / active / migration map。
+2. 进入 `286.2`：抽单一 `ProviderFailurePolicy`。
+3. 进入 `286.3`：`request-executor` 去脑化。
+4. 进入 `286.4`：收掉 provider runtime classifier + reporter fallback。
+5. 最后 `286.5`：build/install/restart/live verify。