fix(engine): warn when requested thinking tier changes - #1661

QA Review: fix/809-thinking-tier-warning

Scope: 4 files, +105/−19 · reviewed: db81fd38
Risk: LOW
Why this exists: an operator's explicit thinkingEffort that a model doesn't offer is stepped down or dropped with no log line, often toward a deeper and more expensive provider default (#809).

Critical (must fix)

None.

Fix in-PR

None.

Suggestions (optional)

• r1s1 [src/engine/engine.ts:233, docs/src/content/docs/config/nimblebrain-json.mdx:179] The unknown-xAI-ladder warning covers a state that test/unit/catalog.test.ts:541 already forbids (xaiUnmeasuredReasoningModels() must be empty), and resolveThinking drops overrides for uncatalogued and non-reasoning models before the builder runs. So in a shipped build this branch is defense in depth, not an operator-visible path. [reasoned] The code is harmless. The operator docs sentence about "an xAI model with no measured ladder" describes a case an operator can't hit, so consider dropping it from the docs and keeping it in the pickTier comment.
• r1s2 [test/unit/engine.test.ts:2297] warnedTierDivergence is process-wide, so the exact-count assertions depend on no earlier test warning for the same (model, tier) key. They pass today because the earlier gpt-5-pro and flash-lite-image cases use source: "platform" or tier medium. Using model/tier keys unique to this test would remove the coupling. [reproduced] The test passes alone (-t "warns once per model") and in the full unit run.

What Looks Good

• The warning sits at the one shared decision point (pickTier), so OpenAI, Gemini levels and xAI get the same rule without per-provider copies. This matches the shape A dropped or stepped-down thinking tier is silent on both Google and OpenAI #809 asked for.
• Nothing changes on the wire. pickTier returns the same tier as before in every case, and xAI's off/adaptive paths still send nothing when no ladder exists.
• A measured-empty xAI ladder (grok-build-0.1) stays silent. So do platform and mode sources. Only an explicit operator choice is reported.
• The test checks the step-down text (sending "minimal"), the drop text, dedup across effort and enabled modes, and the silent cases through a final total count. Removing either the warning or the size === 0 guard would make it fail.

Body claims

• ✅ "221 passed" across engine/catalog/resolve-thinking. Reproduced: 221 pass, 0 fail.
• ✅ Tests cover all three providers, dedup, and the silent platform/default cases.
• ✅ Full unit suite passes locally: 6558 pass, 0 fail (Bun 1.3.12).
• ⚠️ CI: Lint & Typecheck pass, but Unit, Integration and docs jobs show skipping on this run, so the full-suite result the body defers to CI hasn't come in yet. Those checks still need to go green before merge.

{
  "kind": "review", "pr": 1661, "round": 1,
  "reviewed": "db81fd38d4ecdcf9aa4aae49883cc9e81b1a5164", "delta_base": null,
  "risk": "LOW", "stop_gate": "n/a",
  "verdict": "Correct, minimal, matches the issue's shape; no Criticals. Mergeable once required checks run green.",
  "findings": [
    {"id": "r1s1", "bucket": "suggestion", "file": "src/engine/engine.ts", "line": 233,
     "claim": "Unknown-xAI-ladder warning guards a state catalog.test.ts:541 forbids; operator docs describe an unreachable case.",
     "evidence": "reasoned", "receipt": "grep xaiUnmeasuredReasoningModels -> test/unit/catalog.test.ts:541 expects []",
     "preconditions": null, "fix": "drop the xAI-unknown sentence from nimblebrain-json.mdx; keep code", "scope": "peripheral"},
    {"id": "r1s2", "bucket": "suggestion", "file": "test/unit/engine.test.ts", "line": 2297,
     "claim": "Process-wide dedup set couples the new test's exact counts to earlier tests' keys.",
     "evidence": "reproduced", "receipt": "bun test -t 'warns once per model' -> pass; bun test test/unit -> 6558 pass",
     "preconditions": null, "fix": "use model/tier keys unique to this test", "scope": "peripheral"}
  ]
}

Thanks for the contribution @Coding-Professional

@mgoldsborough Thank you for the opportunity! Glad to contribute. Looking forward to contributing more and building together.