feat: ship Effective Route Inspector and escalation guard

[Altairpaca]

Problem

DSH users can select or observe one root-agent route while child agents execute a different provider/model/reasoning route. That difference is not merely cosmetic: it affects reproducibility, capability expectations and cost. Recent community reports include Flash/root selections whose subagents actually ran on Pro-class routes without an explicit warning.

DSHelm should make the route that actually reached execution a first-class product surface instead of treating requested/displayed state as runtime truth.

Community context:

• [bug]SubAgent routing can use stale/wrong models and silently escalate cost deepseek-ai/deepseek-harness#5973
• Authoritative effective model selection for subagents and plugin runtimes deepseek-ai/deepseek-harness#2053

Product contract

For every DSHelm-managed root/child execution where the host exposes enough evidence, retain and display three distinct layers:

1. requested — what the user/profile/caller asked for;
2. resolved — what DSHelm policy selected before execution;
3. effective — what the DSH request path actually executed.

The effective layer must come from runtime evidence, not from root-agent UI state or inheritance assumptions.

Scope

• Define a stable host-agnostic EffectiveRouteObservation contract containing provider, model, reasoning effort, role/child identity, evidence source and observation time (feat(core): define effective route truth contract #49).
• Capture actual provider/model/reasoning from the durable DSH request/header for DSHelm-managed calls (feat(dsh): capture effective route from durable request evidence #50). The production helper returns undefined if no valid runtime header exists.
• Thread requested → resolved → effective provenance into the parent-session Resolution Trace / control-plane snapshot.
• Show the effective route in the Control Plane rather than only the pre-execution selection.
• Classify route divergence explicitly while preserving separate requested→resolved policy changes and resolved→effective runtime changes (feat(core): define effective route truth contract #49).
• Emit a visible escalation warning when a child route materially moves to a higher configured model/cost tier than its parent/requested route.
• Keep unknown explicit when cost/tier metadata is missing; do not invent a price ranking.
• Keep missing effective runtime evidence as unknown rather than inferring it from the resolved route (feat(core): define effective route truth contract #49/feat(dsh): capture effective route from durable request evidence #50).
• Do not silently rewrite an explicit user route merely because a heuristic prefers another model.
• Add deterministic execution fixtures for root → child route inheritance, fallback, and Flash → Pro-style escalation. The real AgentLoop fixture now covers same-route and explicit-override effective observations (feat(dsh): capture effective route from durable request evidence #50); fallback/escalation execution fixtures remain pending.
• Ensure reconnect/session replay does not turn historical effective observations back into inferred state.

Landed foundation

#49 — semantic contract

@dshelm/core exports RouteIdentity, EffectiveRouteState, durable EffectiveRouteObservation, divergence types, and classifyRouteDivergence(). The classifier keeps policyChanges and runtimeChanges separate and exposes whether runtime matched the pre-execution resolution.

#50 — runtime observation

@dshelm/dsh exports observeEffectiveRouteFromSession(). It scans the stable session-log snapshot for the latest valid request/header, structurally extracts provider/model/reasoning, and emits evidenceSource = dsh.session.request/header. The existing credential-free real AgentLoop contract now cross-checks the observation against both the adapter's actual GenerateOptions and the durable header. No-header sessions return undefined instead of inheriting the resolved route.

Initial UI target

role        worker-2
requested   deepseek/deepseek-flash
resolved    deepseek/deepseek-v4-pro
effective   deepseek/deepseek-v4-pro
source      worker policy override → request/header
change      MODEL_ESCALATION
risk        higher configured cost tier

Exact copy/layout may change; the semantic distinction may not.

Acceptance

• A same-route fixture produces no escalation warning.
• A deliberate user override is labelled as explicit rather than suspicious.
• A fallback is distinguishable from policy-selected escalation.
• A child whose effective route differs from both requested and resolved state is visibly flagged.
• Missing price/tier evidence results in unknown, not a fabricated cost claim.
• Runtime-facing tests assert against the actual execution record, not only the preflight policy object.

Non-goals

• replacing DSH Agent/Subagent execution;
• estimating dollar cost without source-backed pricing metadata;
• automatically blocking every escalation in the first increment;
• claiming that a root model must always be inherited by children.

Next implementation increment: make runRoleAgent/the reference slice return or record the effective observation after each completed role, then append those observations into the canonical parent-session control-plane snapshot so the current native Web panel can render runtime truth without inference.

Related: #31 #32 #34 #49 #50