• Detection: Reads the first matching context field in priority order (context_length, context_window, max_model_len, max_input_tokens, …) and the output cap (max_output_tokens, max_completion_tokens, max_tokens, …). A generic max_tokens equal to the window is the context length, not an output cap.
• Conservative: Rejects unit anomalies (a per-request number an order of magnitude below the current window); keeps a real API shrink but ignores noise. Output caps above the window are clamped to it.
• Provenance: Each network value is stamped in pi-auto-compat-sync.json. A hand-edited value is detected as a manual override and never overwritten twice; a real API correction still applies. Flips both values at once (a manual lower output cap does not freeze the window).
• TTL & Signature: Non-forced runs re-probe a channel only when its baseUrl + model-id signature changed or the 6-hour TTL expired; /auto-compat forces a full re-probe.
• Credentials: Resolved from models.json ($ENV, !command, or literal) without logging. Unreachable channels are reported, never silently mis-detected.

• Why: Pi sends thinkingLevelMap[level] ?? level as reasoning_effort, so an unsupported level reaches the upstream and returns 400 — surfaced by routers as 502 provider_error when the body carries the hint (Enclave → Together rejects medium for deepseek-v4.1-flash). GET /models does not advertise the accepted subset.
• Discovery: One tiny completion per level (max_tokens: 16, carrying the same thinking/reasoning payload Pi would send) — 7 requests per model per probe. A level is only marked accepted on success; a 400 gets one confirmation retry, so a single upstream flake cannot rewrite the map.
• Remap: A rejected level maps to the nearest accepted value in Pi's clamp order — up first, ties down (a failed request is worse than a slightly weaker answer). Pi assumes support for unmapped levels, so identity mappings still have to be written once a sibling is dropped; the entry is only written when it carries information.
• Opt-in levels: off, xhigh, and max are only adjusted where the model already declares them, and only when the probe tested the value it currently sends. A deliberate opt-out (null) stays an opt-out.
• User wins: A map the user shaped deliberately (a remap, or an explicit null) is skipped and not even probed — not by the background pass, not by /auto-compat. Delete the entry to opt back in.
• Provenance & TTL: Outcomes are stamped in pi-auto-compat-sync.json together with the effective map. Untouched models are re-probed after 24 hours, or immediately when the model's map no longer matches the recorded one. A channel that answered nothing is retried after 1 hour instead.
• Triggers: session_start, model_select, the models.json watcher (/better-custom, /login), and a reactive pass on message_end that probes the model from the registry when an inference error carries the parameter-rejection hint. /auto-compat forces a full re-probe.
• Scope: reasoning models on openai-completions / openai-responses channels that are not first-party (official OpenAI, OpenRouter, built-in llama.cpp) and are expected to send reasoning_effort — supportsReasoningEffort: false and the openrouter / chat-template / qwen-chat-template / ant-ling formats are excluded.

• Provider Settings: Writes channel-wide parameters (session affinity, cache retention) directly to provider blocks.
• Model Overrides: Writes model-specific flags under models[].compat, or modelOverrides for dynamic extension providers.

• Shard Lock Protection: Wraps writeStatsShardV7 in pi-cache-optimizer with safeAtomicRename (retry with backoff + copy fallback) against NTFS EPERM/EBUSY.
• Orphan Cleanup: Unlinks stale .tmp files in pi-cache-optimizer-stats.d/shards/ automatically on session start.

• Credential-Safe: Only writes compat, modelOverrides, thinkingLevelMap, and contextWindow / maxTokens. The metadata probe reads baseUrl and apiKey from models.json to authenticate; neither is ever written back or logged.
• Rotating Backups: Retains up to 3 timestamped backups (models.json.bak-auto-compat-*) before saving.

npm test    # Run the unit suites: compat flags, placement, metadata sync, thinking effort, Windows patch
npm run dev # Launch local Pi instance with auto-compat active