feature: runtime session token-budget enforcement with graduated response ladder

Summary

Add a graduated, per-session token-budget policy that can shape a request before dispatch and reconcile the actual usage after the response. The policy must be explicit, bounded, observable, and disabled by default.

Audited upstream baseline (2026-07-15)

• pkg/sessiontelemetry already keeps bounded in-process session state such as token/cost totals, last model, and switch data.
• Actual token usage is available only after a response completes. A hard pre-dispatch budget therefore needs a reservation or conservative estimate followed by reconciliation.
• Router Replay can persist the routing decision and final usage/outcome for later analysis.
• model_switch_gate is a rejected legacy public configuration surface on current main; this issue must not revive it.
• Multi-replica/session-global enforcement is not present today and requires an explicit consistency contract.

Scope

1. Define a global, disabled-by-default budget policy and an optional per-decision override.
2. Define a deterministic ladder, for example:
   • normal execution;
   • lower output cap or cheaper allowed model;
   • compression/reduced-context stage where already supported;
   • safe refusal when the configured hard ceiling cannot be honored.
3. Reserve estimated prompt/output demand before dispatch and reconcile with provider-reported usage after completion.
4. Record the selected stage, estimate, reservation, actual usage, and reason in metrics and Router Replay.
5. Specify single-process semantics first; make any shared-store/multi-replica mode an explicit later phase.
6. Keep offline learned budget recommendations in Router Learning/recipe learning; the request path only consumes validated policy.

Boundaries

• Authentication/authorization and safety constraints take precedence over budget shaping.
• A budget stage cannot bypass the configured candidate set, safety checks, or output contracts.
• No synchronous durable-store call is allowed on the hot path.
• This issue does not introduce a workflow scheduler or a new model_switch_gate API.

Acceptance criteria

• Disabled configuration preserves current behavior.
• Reservation and reconciliation behavior is deterministic and tested for missing/partial usage data.
• Concurrent requests for one session cannot silently overspend the locally enforced ceiling.
• Every stage transition has bounded-cardinality metrics and a replay reason.
• Hard safety/authorization rules win over cost or token objectives.
• E2E tests cover normal, degraded, refused, and reconciliation paths.
• Documentation states the consistency limits of single-process and any future shared mode.

Likely change surfaces

src/semantic-router/pkg/sessiontelemetry/, src/semantic-router/pkg/extproc/, src/semantic-router/pkg/routerruntime/, src/semantic-router/pkg/routerreplay/, src/semantic-router/pkg/config/, observability, maintained config examples, and E2E tests.

Validation

Start with make agent-report ENV=cpu CHANGED_FILES="...", then run the reported lint/CI/feature gates and affected E2E profile.