[stanleytejakusuma]

Summary

Implements #10681: an opaque, per-invocation decision trace for combo fallbacks.

Priority combos can be impossible to audit after a mixed fallback. Dispatched attempts are persisted in call_logs, but targets excluded before dispatch leave no correlated decision record — you cannot tell whether a configured target was evaluated and gated, reordered, or never reached after a later success.

What this adds

1. open-sse/services/combo/decisionTrace.ts — createInvocationId() (opaque combo-<uuid>), startComboTrace, recordComboDecision, finalizeComboTrace (marks never-iterated targets not_reached), getComboTrace. Bounded in-memory retention: 30min TTL, 2000 invocations (LRU).
2. combo.ts — hooks at every pre-dispatch skip site (circuit open, provider cooldown, request exhaustion, model lockout, quota cutoff, availability, credential gate, concurrency cap, admission lane, predictive TTFT) recording skipped_before_dispatch with an allowlisted reason; a single dispatched record per target (per-target retries dedupe); and finalize on success / global timeout / all-failed / all-skipped terminals.
3. GET /api/usage/combo-trace/[id] — management-auth read of the trace for a given invocation.

Safety contract

The trace contains routing metadata only: invocation id, combo name, strategy, per-target provider/model, decision, allowlisted skip reason, timestamps, terminal status. Never prompts, request/response bodies, headers, credentials, account ids, or raw upstream error strings. Routing semantics are unchanged — this is a read-only projection of existing dispatch decisions.

Tests

• Unit: invocation-id uniqueness, skip-reason allowlist enforcement, not_reached finalize.
• Integration (public handleComboChat + injected handleSingleModel): mixed 429 fallback yields [dispatched, dispatched, not_reached]; availability skip yields skipped_before_dispatch/availability.
• 5/5 pass. Combo suite: 1183/1185 (the 2 failures — combo-runtime-unit-concurrency tmpdir-symlink assertion and the zero-latency compression-opt-in 500 — are identical on clean release/v3.8.50, pre-existing). typecheck:core errors are the pre-existing OmniGlyph baseline.

Notes

• Retention is in-memory by design (matches the issue's "normal bounded retention"); a follow-up could persist to call-log metadata if desired.
• Nested combo-ref dispatches get their own invocation id (per-dispatch traces); the top-level handleComboChat accepts an optional invocationId for callers that want to seed it.

[stanleytejakusuma]

Follow-up c469c26 (after review): stamps the trace id on the receipt so the store is actually reachable post-incident, per the #10681 auditability goal.

• X-OmniRoute-Combo-Trace: combo-<uuid> header on the final Response at every exit path (wrapper around handleComboChat; callers may still supply their own invocationId).
• One metadata-only log line at finalize (id, terminal status, decision count) so finalized traces survive restarts via the existing log pipeline.
• Eviction at the MAX_TRACES cap now prefers FINALIZED traces, pinning in-flight invocations against bursts.
• Tests: header on success + all-failed paths, log-line shape, eviction preference. Combo suite 162/162.