pi-smart-router 0.12.2 → 0.14.0

package/.pi/extensions/smart-router/extension-setup.ts

@@ -77,6 +77,7 @@ export async function createSmartRouterRuntime(cwd: string): Promise<{
       fleet: [],
       executionLedger,
       lifecycleHookState,
+      planningDelegateConfig: operatorConfig.planning_delegate,
       datasetRecorder,
       outcomeRecorder,
       sessionPinner,

package/.pi/extensions/smart-router/fleet-bootstrap.ts

@@ -15,6 +15,13 @@ import {
   createOnnxEmbeddingProvider,
 } from '../../../src/domain/matching/hydra-matcher.js';
 import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import {
+  collectPoolModelIds,
+  resolveQuotaWindowEstimateConfigFromEnv,
+  resolveQuotaWindowPosition,
+  type QuotaWindowAdapter,
+  type QuotaWindowEstimateConfig,
+} from '../../../src/domain/pricing/quota-window-feed.js';
 import type { ModelProfile, PriceCatalog } from '../../../src/domain/types/index.js';
 import type { QuotaWindowPosition } from '../../../src/domain/types/entities.js';
 import type { OperatorConfig } from '../../../src/domain/types/schemas.js';
@@ -38,10 +45,51 @@ export interface CreateDispatchOptionsExtras {
   readonly operatorConfig?: OperatorConfig;
   /** Live price catalog when fleet discovery has loaded one. */
   readonly priceCatalog?: PriceCatalog | null;
-  /** Rolling subscription quota position when available. */
+  /** Rolling subscription quota position when available (see resolveQuotaWindowFeedPosition, SP-214). */
   readonly quotaWindowPosition?: QuotaWindowPosition;
 }
 
+/** Max telemetry rows scanned for the quota-window burn estimate (SP-214). */
+const QUOTA_FEED_TELEMETRY_LIMIT = 5000;
+
+export interface ResolveQuotaWindowFeedDeps {
+  /** Optional provider adapter (degrade chain step 1). */
+  readonly adapter?: QuotaWindowAdapter;
+  /** Estimate config override; defaults to env-resolved config. */
+  readonly estimateConfig?: QuotaWindowEstimateConfig;
+  readonly now?: Date;
+}
+
+/**
+ * Resolve the pool-level `QuotaWindowPosition` for the fleet via the SP-214
+ * degrade chain: adapter → telemetry burn estimate → omit. Returns `undefined`
+ * when the fleet has no subscription pool and no adapter, or when the feed is
+ * disabled — callers then fall back to flat virtual cost + SP-097 failover.
+ */
+export async function resolveQuotaWindowFeedPosition(
+  store: StorePort,
+  fleet: readonly ModelProfile[],
+  deps?: ResolveQuotaWindowFeedDeps,
+): Promise<QuotaWindowPosition | undefined> {
+  const poolModelIds = collectPoolModelIds(fleet);
+  if (poolModelIds.size === 0 && !deps?.adapter) {
+    return undefined;
+  }
+  const estimateConfig =
+    deps?.estimateConfig ?? resolveQuotaWindowEstimateConfigFromEnv();
+  const entries =
+    poolModelIds.size > 0
+      ? await store.listTelemetry({ limit: QUOTA_FEED_TELEMETRY_LIMIT })
+      : [];
+  return resolveQuotaWindowPosition({
+    adapter: deps?.adapter,
+    entries,
+    poolModelIds,
+    estimateConfig,
+    ...(deps?.now !== undefined ? { now: deps.now } : {}),
+  });
+}
+
 /** Minimal settings surface used for scoped fleet discovery. */
 export interface ScopedSettingsReader {
   getEnabledModels(): string[] | null | undefined;
@@ -235,9 +283,11 @@ export async function rebuildFleet(
   );
   runtime.priceCatalog = catalog;
   runtime.fleetScopeFingerprint = fingerprint;
+  const quotaWindowPosition = await resolveQuotaWindowFeedPosition(runtime.store, fleet);
   const router = createRouterFromFleet(fleet, {
     ...createDispatchOptions(runtime.store, runtime.sessionPinner, runtime.hydraMatcher, {
       priceCatalog: catalog,
+      ...(quotaWindowPosition !== undefined ? { quotaWindowPosition } : {}),
     }),
     lifecycleHookState: runtime.lifecycleHookState,
   });

package/.pi/extensions/smart-router/planning-delegate.ts

@@ -5,6 +5,11 @@
  * on compressed context, inject the result as an observation, and keep primary
  * inference on the pinned economical model. Falls back to direct frontier routing
  * when sub-agent spawn is unavailable (pi has no native sub-agent API yet).
+ *
+ * SP-213 / #120: sub-calls are bounded by a global stage timeout and a per-call
+ * worker timeout (llm-use WORKER_GLOBAL_TIMEOUT / WORKER_CALL_TIMEOUT pattern).
+ * On timeout the worker is cancelled/abandoned, `planning_delegate_timeout` is
+ * recorded, and routing falls back to the direct frontier path — never a hang.
  */
 
 import {
@@ -22,10 +27,12 @@ import type {
   PlanningDelegateObservability,
   RoutingDecision,
 } from '../../../src/domain/types/index.js';
+import { DEFAULT_PLANNING_DELEGATE_CONFIG } from '../../../src/domain/types/schemas.js';
 import {
   createPlanningDelegateObservability,
   enrichRoutingDecisionWithPlanningDelegate,
   PLANNING_DELEGATE,
+  PLANNING_DELEGATE_TIMEOUT,
   PLANNING_DELEGATE_UNAVAILABLE,
   PLANNING_DIRECT_FRONTIER,
 } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
@@ -222,6 +229,65 @@ export interface PlanningDelegateResolution {
   readonly usedDelegatePath: boolean;
 }
 
+/** Worker telemetry analogs for one planning turn (SP-213, #120). */
+interface DelegateWorkerTelemetry {
+  readonly workers_spawned: number;
+  readonly workers_succeeded: number;
+  readonly worker_timeout_count: number;
+}
+
+/**
+ * Race a delegate sub-call against a bounded timeout (SP-213, #120).
+ *
+ * On expiry the worker is signalled for cancellation (AbortSignal forwarded to
+ * the sub-call options) and abandoned — the race resolves immediately so a
+ * stalled worker can never hang TTFT. An outer caller abort is forwarded to
+ * the worker as well. No retries and no queue: exactly one worker per call.
+ */
+async function spawnPlanningDelegateWithTimeout(
+  spawnFn: PlanningDelegateSpawnFn,
+  frontierModel: Model<Api>,
+  compressedContext: Context,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+  timeoutMs: number,
+): Promise<PlanningDelegateSpawnResult> {
+  const controller = new AbortController();
+  const outerSignal = options?.signal;
+  const forwardOuterAbort = (): void => controller.abort();
+  if (outerSignal) {
+    if (outerSignal.aborted) {
+      controller.abort();
+    } else {
+      outerSignal.addEventListener('abort', forwardOuterAbort, { once: true });
+    }
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const spawnOptions: SimpleStreamOptions = {
+      ...(options ?? {}),
+      signal: controller.signal,
+    };
+    const spawnPromise = spawnFn(frontierModel, compressedContext, spawnOptions, deps);
+    // Swallow late rejections from an abandoned worker so a timeout never
+    // surfaces as an unhandled rejection after the fallback already routed.
+    spawnPromise.catch(() => {});
+    const timeoutPromise = new Promise<PlanningDelegateSpawnResult>((resolve) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        resolve({ ok: false, reason: PLANNING_DELEGATE_TIMEOUT });
+      }, timeoutMs);
+    });
+    return await Promise.race([spawnPromise, timeoutPromise]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    outerSignal?.removeEventListener('abort', forwardOuterAbort);
+  }
+}
+
 /**
  * Resolve planning delegate path: sub-call + observation injection, or direct frontier fallback.
  */
@@ -237,6 +303,10 @@ export async function resolvePlanningDelegatePath(
   const observability = decision.features!.planning_delegate!;
   const delegateModelId = observability.delegate_model_id!;
   const primaryModelId = decision.selected_model_id;
+  const delegateConfig =
+    deps.planningDelegateConfig ?? DEFAULT_PLANNING_DELEGATE_CONFIG;
+  // Global stage deadline: bounds compression + sub-call wall-clock (SP-213, #120).
+  const globalDeadlineMs = Date.now() + delegateConfig.global_timeout_ms;
 
   const frontierProfile = findFleetProfile(deps.fleet, delegateModelId);
   const frontierModel = frontierProfile
@@ -254,6 +324,7 @@ export async function resolvePlanningDelegatePath(
       delegateModelId,
       PLANNING_DELEGATE_UNAVAILABLE,
       deps,
+      { workers_spawned: 0, workers_succeeded: 0, worker_timeout_count: 0 },
     );
   }
 
@@ -262,20 +333,60 @@ export async function resolvePlanningDelegatePath(
     observability.compressed_context,
   );
   throwIfAborted(options);
+
+  const remainingGlobalMs = globalDeadlineMs - Date.now();
+  if (remainingGlobalMs <= 0) {
+    console.warn(
+      '[smart-router] planning delegate global timeout exhausted before sub-call, falling back to direct frontier route',
+      delegateModelId,
+    );
+    return applyPlanningDelegateDirectFallback(
+      context,
+      decision,
+      delegateModelId,
+      PLANNING_DELEGATE_TIMEOUT,
+      deps,
+      { workers_spawned: 0, workers_succeeded: 0, worker_timeout_count: 1 },
+    );
+  }
+
   const spawnFn = deps.spawnPlanningDelegate ?? defaultSpawnPlanningDelegate;
-  const spawnResult = await spawnFn(frontierModel, compressedContext, options, deps);
+  // Per-call cap, further bounded by the remaining global budget.
+  const subCallTimeoutMs = Math.min(
+    delegateConfig.sub_call_timeout_ms,
+    remainingGlobalMs,
+  );
+  const spawnResult = await spawnPlanningDelegateWithTimeout(
+    spawnFn,
+    frontierModel,
+    compressedContext,
+    options,
+    deps,
+    subCallTimeoutMs,
+  );
 
   if (!spawnResult.ok) {
+    const timedOut = spawnResult.reason === PLANNING_DELEGATE_TIMEOUT;
+    const fallbackReason = timedOut
+      ? PLANNING_DELEGATE_TIMEOUT
+      : PLANNING_DELEGATE_UNAVAILABLE;
     console.warn(
-      '[smart-router] planning delegate sub-call failed, falling back to direct frontier route',
+      timedOut
+        ? '[smart-router] planning delegate sub-call timed out, falling back to direct frontier route'
+        : '[smart-router] planning delegate sub-call failed, falling back to direct frontier route',
       spawnResult.reason,
     );
     return applyPlanningDelegateDirectFallback(
       context,
       decision,
       delegateModelId,
-      PLANNING_DELEGATE_UNAVAILABLE,
+      fallbackReason,
       deps,
+      {
+        workers_spawned: 1,
+        workers_succeeded: 0,
+        worker_timeout_count: timedOut ? 1 : 0,
+      },
     );
   }
 
@@ -290,7 +401,12 @@ export async function resolvePlanningDelegatePath(
 
   return {
     context: injectPlanningDelegateObservation(context, spawnResult.observationText),
-    decision,
+    decision: enrichRoutingDecisionWithPlanningDelegate(decision, {
+      ...observability,
+      workers_spawned: 1,
+      workers_succeeded: 1,
+      worker_timeout_count: 0,
+    }),
     targetModelId: primaryModelId,
     usedDelegatePath: true,
   };
@@ -302,6 +418,7 @@ function applyPlanningDelegateDirectFallback(
   delegateModelId: string,
   fallbackReason: string,
   deps: StreamDelegationDeps,
+  workerTelemetry?: DelegateWorkerTelemetry,
 ): PlanningDelegateResolution {
   const profile = findFleetProfile(deps.fleet, delegateModelId);
   const fallbackDecision = enrichRoutingDecisionWithPlanningDelegate(
@@ -316,6 +433,9 @@ function applyPlanningDelegateDirectFallback(
       delegate_model_id: delegateModelId,
       planning_delegate_reason_code: PLANNING_DIRECT_FRONTIER,
       fallback_reason: fallbackReason,
+      workers_spawned: workerTelemetry?.workers_spawned ?? null,
+      workers_succeeded: workerTelemetry?.workers_succeeded ?? null,
+      worker_timeout_count: workerTelemetry?.worker_timeout_count ?? null,
     }),
   );
 

package/.pi/extensions/smart-router/types.ts

@@ -12,6 +12,7 @@ import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger
 import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
 import type {
   ModelProfile,
+  PlanningDelegateConfig,
   PriceCatalog,
   RoutingDecision,
 } from '../../../src/domain/types/index.js';
@@ -60,6 +61,8 @@ export interface StreamDelegationDeps {
   delegateStream?: DelegateStreamFn;
   /** Injectable planning delegate sub-call; production uses frontier stream delegate. */
   spawnPlanningDelegate?: PlanningDelegateSpawnFn;
+  /** Planning delegate knobs incl. global + per-call timeout bounds (SP-213, #120). */
+  readonly planningDelegateConfig?: PlanningDelegateConfig;
   readonly lifecycleHookState?: LifecycleHookState;
   readonly datasetRecorder?: DatasetRecorder;
   readonly outcomeRecorder?: OutcomeRecorder;

package/README.md

@@ -246,7 +246,7 @@ When you use `smart-router/auto`, the extension does **not** read `config/models
 4. **Route** — `createRouterFromFleet()` runs the 12-stage pipeline on each request.
 5. **Delegate** — The extension resolves the chosen model in the registry and forwards the stream via pi-ai's built-in provider APIs.
 
-Unknown models receive conservative economical-cloud defaults. Local providers (`lmstudio`, `ollama`) map to `zero-tier`. Cursor provider models (`cursor/*`, `composer-*`, opaque id `default`) map to `frontier-cloud` with explicit capability defaults (SP-086, SP-098).
+Unknown models receive conservative economical-cloud defaults. Local providers (`lmstudio`, `ollama`) map to `zero-tier`. Cursor provider models (`cursor/*`, `composer-*`, opaque id `default`) map to `frontier-cloud` with explicit capability defaults (SP-086, SP-098). Benchmark-grounded capability vectors (including multi-fleet `github-copilot/*`, Gemini, and Anthropic dogfood IDs, aliased family-by-family) are documented in the [capability profile coverage report](docs/capability-profile-coverage.md) ([#108](https://github.com/beettlle/pi-smart-router/issues/108) / [#124](https://github.com/beettlle/pi-smart-router/issues/124)).
 
 To refresh after auth or settings changes, restart pi or `/reload` extensions.
 
@@ -368,6 +368,8 @@ Cluster IDs are stable reason-code prefixes (`cluster_low_stakes_general`, `clus
 | `SMART_ROUTER_PLANNING_DELEGATE_MAX_MESSAGES` | `12` | Compressed-context message cap for frontier sub-call |
 | `SMART_ROUTER_PLANNING_DELEGATE_MAX_TOKENS` | `16384` | Compressed-context token cap for frontier sub-call |
 | `SMART_ROUTER_PLANNING_DELEGATE_EXCLUDE_EXECUTION_HISTORY` | `true` | Exclude tool execution history from delegate payload |
+| `SMART_ROUTER_PLANNING_DELEGATE_GLOBAL_TIMEOUT_MS` | `120000` | Global cap (ms) on the whole planning-delegate stage per planning turn — bounds fan-out wall-clock so a stalled worker cannot hang TTFT ([#120](https://github.com/beettlle/pi-smart-router/issues/120)) |
+| `SMART_ROUTER_PLANNING_DELEGATE_SUB_CALL_TIMEOUT_MS` | `30000` | Per-call cap (ms) on each delegate sub-call worker; on expiry the worker is cancelled/abandoned and routing falls back to direct frontier with `planning_delegate_timeout` ([#120](https://github.com/beettlle/pi-smart-router/issues/120)) |
 | `SMART_ROUTER_PREFIX_CACHE_WEIGHT` | `0.20` | SAAR weight on warm prefix value in cache breakeven math (0–1; [#73](https://github.com/beettlle/pi-smart-router/issues/73)) |
 | `SMART_ROUTER_IDLE_TIMEOUT_SECONDS` | `300` | SAAR idle seconds before pin reopens for full re-route |
 | `SMART_ROUTER_SWITCH_THRESHOLD` | `0.5` | SAAR switch score gate (0–1) for tier upgrades during hard-lock |
@@ -442,6 +444,25 @@ When a **planning** turn would route primary inference to frontier while a warm
 
 See [routing-roadmap.md](docs/routing-roadmap.md) §2 P0 and GitHub [#71](https://github.com/beettlle/pi-smart-router/issues/71) for acceptance criteria.
 
+### Degraded neural failover sandwich (#119)
+
+When the encoder/neural stage (HyDRA) **fails, is misconfigured, or exceeds its latency budget without a selection**, routing fails open through a cheap chain instead of crashing the host agent ([#119](https://github.com/beettlle/pi-smart-router/issues/119)):
+
+1. **learned** — optional privacy-safe map keyed by requirement fingerprint (SHA-256 of the rounded requirement vector) or cluster id → preferred tier. **Raw prompt text is never stored.** Exact-key policy: fingerprint match first, cluster id second (no fuzzy matching). Writes are validated (bounded floats, snake_case cluster ids, tier enum) and capped (FIFO eviction) so confounder attacks cannot poison routing memory.
+2. **heuristic** — optional operator **pattern pack** (router_rules-style regex overlay) for known-simple intents. Deny-by-default (no match → no decision) and **fail closed on invalid regex** (the rule is rejected at load and never applies).
+3. **safe_default** — context-fit aware safe economical/frontier default (`degraded_safe_default`).
+
+Explain/telemetry expose `route_path` (`neural` \| `learned` \| `heuristic` \| `safe_default`) plus `route_path_confidence` on every decision; degraded decisions carry reason codes `degraded_learned_route`, `degraded_pattern_<rule_id>`, or `degraded_safe_default`. A learned/pattern suggestion toward a cheaper tier is only honored when the cheap tool-use cue estimate is below `pattern_tool_use_ceiling` — a cheap overlay **never alone overrides a predicted capability shortfall**.
+
+| Knob (`degraded_route` operator config) | Default | Effect |
+|------|---------|--------|
+| `enabled` | `true` | When `false`, neural failures use the legacy `safe_default` stage pass-through |
+| `learned_min_confidence` | `0.6` | Minimum learned-entry confidence to honor a tier suggestion |
+| `learned_max_entries` | `512` | Learned-map cap per key space (FIFO eviction) |
+| `pattern_tool_use_ceiling` | `0.3` | Tool-use cue ceiling for honoring cheaper-tier learned/pattern suggestions |
+
+Distinct from soft heat affinity (healthy-path bias): this is failover / skip-expensive-stage only. Routing remains **pre-generation** — no FrugalGPT-style cascades (see [routing-roadmap.md](docs/routing-roadmap.md) §1).
+
 ### Virtual cost v2 (v0.5.0 subscription economics)
 
 **Virtual cost v2** extends SP-096 flat `quota_cost_per_1m` with deterministic subscription-window economics ([#78](https://github.com/beettlle/pi-smart-router/issues/78)). It inflates effective frontier cost late in a rolling quota window and credits warm prefix-cache value on active pins — without MDP or reinforcement-learning quota policy (SeqRoute HBR+CQL is deferred).
@@ -462,6 +483,10 @@ See [routing-roadmap.md](docs/routing-roadmap.md) §2 P0 and GitHub [#71](https:
 
 Rolling-window position is supplied to the router pipeline as `quotaWindowPosition` (library API / telemetry integration). Use `remaining_window_fraction` in `[0, 1]` (1 = full budget). Optionally derive it from elapsed time and consumed quota via `deriveRemainingWindowFraction(elapsed_seconds, consumed_fraction)` in `virtual-cost-v2.ts` (defaults assume a Cursor-style **5h** window).
 
+**Quota window feed (producer, [#125](https://github.com/beettlle/pi-smart-router/issues/125))**
+
+There is no universal cross-provider "remaining quota" API, so `src/domain/pricing/quota-window-feed.ts` produces the position via an adapter + degrade chain: (1) a provider `QuotaWindowAdapter` when a trustworthy signal exists, (2) a telemetry-derived **pool-level** burn estimate over the rolling window (subscription-pool models = fleet entries with `quota_cost_per_1m`; enabled via `SMART_ROUTER_QUOTA_POOL_BUDGET_TOKENS` + `SMART_ROUTER_QUOTA_WINDOW_SECONDS`), (3) omit → flat virtual cost + SP-097 exhaustion failover. The smart-router extension resolves the feed at fleet rebuild and passes it through `createDispatchOptions` (SP-173 wiring gap closed). Soft bias only — no hard ban at any threshold; SP-097 reactive failover remains the safety net when the feed is missing or stale. Per-model fractions for shared pools are never invented.
+
 When `quotaWindowPosition` is omitted, λ stays at 1 and quota premiums are zero — behavior matches SP-096 flat virtual cost.
 
 **Operator knobs** (`VirtualCostV2Config` — wire through `RouterPipeline` options today; defaults in `DEFAULT_VIRTUAL_COST_V2_CONFIG`):
@@ -1202,6 +1227,60 @@ Confirm https://pi.dev/packages/pi-smart-router shows the new version (may lag n
 | [config/models.yaml.example](config/models.yaml.example) | Fleet catalog template (library API) |
 | [config/routing-clusters.yaml.example](config/routing-clusters.yaml.example) | Routing cluster reference-prompt catalog (library API) |
 
+## Develop with pi-spine (agent models)
+
+This repo is developed with [pi-spine](https://github.com/beettlle/pi-spine) batches. Agent model pins live in [`.spine/spine-config.json`](.spine/spine-config.json) under `agents.*`. Use **canonical** `provider/model` ids from `pi --list-models` (not TUI labels like `glm-5.2 [zai]`). Run `spine doctor` before real-pi batches.
+
+Named profiles (`agents.profiles` + `agents.activeProfile`) and `agents.escalatePolicy` are configured in spine-config ([pi-spine#216](https://github.com/beettlle/pi-spine/issues/216) / SP-664). Live stack resolves from `activeProfile` over the base `agents` block. Hybrid cost/quality recipes are documented upstream in [pi-spine#210](https://github.com/beettlle/pi-spine/issues/210).
+
+### Default profile (`activeProfile: "default"`)
+
+| Role | Model | Thinking |
+|------|--------|----------|
+| Worker | `zai/glm-5.2` | `high` |
+| Plan review | `google/gemini-flash-latest` | `low` |
+| Code review | `kimi-coding/kimi-k2-thinking` | `high` |
+| Final review | `google/gemini-3.1-pro-preview` | `high` |
+| Supervisor | `google/gemini-flash-lite-latest` | `off` |
+
+### When to escalate (hard packets / sticky failures)
+
+Escalate when:
+
+- The same SP fails final or code review **2+** times with substantive `REVISE` (not broad `testCommand` / lane noise)
+- The worker stalls or oscillates on multi-file design
+- The packet needs deeper reasoning than the default stack delivered
+
+### Tier 1 — mid escalate
+
+Switches the worker to `kimi-coding/kimi-for-coding` (reviewer pins inherit default).
+
+```bash
+spine settings set agents.activeProfile mid
+spine batch retry <SP-ID>
+# restore:
+spine settings set agents.activeProfile default
+```
+
+### Tier 2 — hard escalate
+
+| Role | Model | Thinking |
+|------|--------|----------|
+| Worker | `kimi-coding/k3` | `high` |
+| Plan | `kimi-coding/kimi-k2-thinking` | `medium` |
+| Code | `google/gemini-3.1-pro-preview` | `high` |
+| Final | `google/gemini-3.1-pro-preview` | `high` |
+
+`escalatePolicy.toProfile` is `hard`. Switch explicitly when a packet is sticky:
+
+```bash
+spine settings set agents.activeProfile hard
+spine doctor
+spine batch retry <SP-ID>
+# restore:
+spine settings set agents.activeProfile default
+```
+
 ## Built with
 
 - [pi](https://pi.dev) — Coding agent harness (extension host)

package/config/benchmark-profiles.json

@@ -7,26 +7,47 @@
       "livecodebench": "https://livecodebench.github.io/leaderboard.html",
       "bfcl": "https://gorilla.cs.berkeley.edu/leaderboard.html"
     },
-    "scrape_date": "2026-07-16",
-    "catalog_freeze_date": "2026-07-16"
+    "scrape_date": "2026-07-20",
+    "catalog_freeze_date": "2026-07-20"
   },
   "aliases": {
+    "anthropic/claude-opus-4": "claude-opus-4-5",
+    "anthropic/claude-sonnet-4": "claude-sonnet-4-6",
     "claude-3-5-sonnet": "claude-sonnet-4-6",
+    "claude-3-7-sonnet": "claude-sonnet-4-6",
+    "claude-3-7-sonnet-latest": "claude-sonnet-4-6",
     "claude-3.5-sonnet": "claude-sonnet-4-6",
     "claude-3.5-sonnet-latest": "claude-sonnet-4-6",
+    "claude-3.7-sonnet": "claude-sonnet-4-6",
     "claude-opus-4": "claude-opus-4-5",
+    "claude-opus-4-1": "claude-opus-4-5",
     "claude-opus-4-20250514": "claude-opus-4-5",
+    "claude-opus-4.1": "claude-opus-4-5",
     "claude-sonnet-4": "claude-sonnet-4-6",
     "claude-sonnet-4-20250514": "claude-sonnet-4-6",
+    "claude-sonnet-4-5": "claude-sonnet-4-6",
+    "claude-sonnet-4.5": "claude-sonnet-4-6",
     "composer-1": "gpt-5.3-codex",
     "composer-latest": "gpt-5.3-codex",
     "cursor/auto": "gpt-5.3-codex",
     "cursor/composer-latest": "gpt-5.3-codex",
     "default": "gpt-5.3-codex",
+    "gemini-1.5-flash": "gemini-2.5-flash",
     "gemini-2.0-flash": "gemini-2.5-flash",
+    "gemini-2.0-flash-001": "gemini-2.5-flash",
+    "gemini-2.5-flash-002": "gemini-2.5-flash",
     "gemini-2.5-flash-lite": "gemini-2.5-flash",
     "gemini-2.5-flash-preview": "gemini-2.5-flash",
+    "gemini-flash-8b": "gemini-2.5-flash",
     "gemini-flash-latest": "gemini-2.5-flash",
+    "github-copilot/claude-3.5-sonnet": "claude-sonnet-4-6",
+    "github-copilot/claude-sonnet-4": "claude-sonnet-4-6",
+    "github-copilot/claude-sonnet-4.5": "claude-sonnet-4-6",
+    "github-copilot/gemini-2.0-flash": "gemini-2.5-flash",
+    "github-copilot/gemini-2.5-flash": "gemini-2.5-flash",
+    "github-copilot/gpt-5": "gpt-5.3-codex",
+    "github-copilot/gpt-5-codex": "gpt-5.3-codex",
+    "google/gemini-2.5-flash": "gemini-2.5-flash",
     "gpt-5": "gpt-5.3-codex",
     "gpt-5-codex": "gpt-5.3-codex",
     "gpt-5.3": "gpt-5.3-codex",

package/dist/config/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,wFAAwF;AACxF,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,cAAwC,GAC7C,cAAc,CAMhB;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,cAAc,CAgCnD,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,wFAAwF;AACxF,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,cAAwC,GAC7C,cAAc,CAMhB;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,cAAc,CAiCnD,CAAC"}

package/dist/config/defaults.js

@@ -2,7 +2,7 @@
  * Operator configuration defaults (FR-021).
  * Values sourced from specs/001-build-smart-router/data-model.md § Configuration (Operator).
  */
-import { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
+import { DEFAULT_DEGRADED_ROUTE_CONFIG, DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
 import { DEFAULT_LOW_INTENSITY_WEIGHTS } from '../domain/routing/tier-features.js';
 export { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
 /** Merge operator env overrides onto defaults (SAAR and planning delegate sections). */
@@ -44,6 +44,7 @@ export const DEFAULT_OPERATOR_CONFIG = {
     saar: DEFAULT_SAAR_CONFIG,
     planning_delegate: DEFAULT_PLANNING_DELEGATE_CONFIG,
     local_zero: DEFAULT_LOCAL_ZERO_CONFIG,
+    degraded_route: DEFAULT_DEGRADED_ROUTE_CONFIG,
     pin_only_fallback: false,
 };
 //# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,wFAAwF;AACxF,MAAM,UAAU,4BAA4B,CAC1C,OAAuB,uBAAuB;IAE9C,OAAO;QACL,GAAG,IAAI;QACP,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC;QACzC,iBAAiB,EAAE,oCAAoC,CAAC,IAAI,CAAC,iBAAiB,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAA6B;IAC/D,SAAS,EAAE;QACT,WAAW,EAAE,GAAG;QAChB,cAAc,EAAE,GAAG;QACnB,gBAAgB,EAAE,IAAI;KACvB;IACD,eAAe,EAAE;QACf,SAAS,EAAE,CAAC;KACb;IACD,OAAO,EAAE;QACP,cAAc,EAAE,EAAE;KACnB;IACD,KAAK,EAAE;QACL,kBAAkB,EAAE,EAAE;QACtB,4BAA4B,EAAE,CAAC;QAC/B,qBAAqB,EAAE,EAAE;KAC1B;IACD,KAAK,EAAE;QACL,mBAAmB,EAAE,0BAA0B;QAC/C,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,oBAAoB;KAClC;IACD,aAAa,EAAE;QACb,OAAO,EAAE,6BAA6B;QACtC,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,GAAG;KACrB;IACD,IAAI,EAAE,mBAAmB;IACzB,iBAAiB,EAAE,gCAAgC;IACnD,UAAU,EAAE,yBAAyB;IACrC,iBAAiB,EAAE,KAAK;CAChB,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,wFAAwF;AACxF,MAAM,UAAU,4BAA4B,CAC1C,OAAuB,uBAAuB;IAE9C,OAAO;QACL,GAAG,IAAI;QACP,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC;QACzC,iBAAiB,EAAE,oCAAoC,CAAC,IAAI,CAAC,iBAAiB,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAA6B;IAC/D,SAAS,EAAE;QACT,WAAW,EAAE,GAAG;QAChB,cAAc,EAAE,GAAG;QACnB,gBAAgB,EAAE,IAAI;KACvB;IACD,eAAe,EAAE;QACf,SAAS,EAAE,CAAC;KACb;IACD,OAAO,EAAE;QACP,cAAc,EAAE,EAAE;KACnB;IACD,KAAK,EAAE;QACL,kBAAkB,EAAE,EAAE;QACtB,4BAA4B,EAAE,CAAC;QAC/B,qBAAqB,EAAE,EAAE;KAC1B;IACD,KAAK,EAAE;QACL,mBAAmB,EAAE,0BAA0B;QAC/C,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,oBAAoB;KAClC;IACD,aAAa,EAAE;QACb,OAAO,EAAE,6BAA6B;QACtC,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,GAAG;KACrB;IACD,IAAI,EAAE,mBAAmB;IACzB,iBAAiB,EAAE,gCAAgC;IACnD,UAAU,EAAE,yBAAyB;IACrC,cAAc,EAAE,6BAA6B;IAC7C,iBAAiB,EAAE,KAAK;CAChB,CAAC"}

package/dist/domain/pinning/loop-escalation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop-escalation.d.ts","sourceRoot":"","sources":["../../../src/domain/pinning/loop-escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIlF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,EAAG,eAAwB,CAAC;AA4BvE;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAOlF;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAKjF;AA+GD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,UAAU,GAAG,IAAI,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAwDtB"}
+{"version":3,"file":"loop-escalation.d.ts","sourceRoot":"","sources":["../../../src/domain/pinning/loop-escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIlF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,EAAG,eAAwB,CAAC;AA4BvE;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAOlF;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAKjF;AA+GD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,UAAU,GAAG,IAAI,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAgFtB"}

package/dist/domain/pinning/loop-escalation.js

@@ -195,8 +195,31 @@ export function evaluateLoopEscalation(pin, request, fleet, config) {
         }
         return noEscalation('no_failure');
     }
+    //
+    // Economical pin — observational churn (SP-210, #122):
+    //
+    // A hard multi-step / tool-failure session pinned economical must not stay
+    // stuck when quality recovery needs a higher tier. Unlike the zero-tier
+    // path (which counts every tool_result turn) economical models CAN complete
+    // most tool loops, so we only count actual tool *failures*. But unlike the
+    // frontier identical-failure gate (FR-014), distinct/varied failures are
+    // still evidence the economical tier cannot recover the loop — a session
+    // failing repeatedly with different errors (ENOENT → ECONNREFUSED → timeout)
+    // is just as stuck as one hitting the same error 3×. We therefore count
+    // consecutive failures of ANY signature toward the escalation threshold.
+    //
+    // Break/upgrade conditions while pinned economical:
+    //   • N consecutive tool failures (any signature) → escalate to frontier
+    //   • a successful tool result → reset the failure streak
+    //   • escalation fires once per session (pin_reason === 'loop_escalation')
+    // History surfaces the break via pin_reason='loop_escalation' plus the new
+    // selected_model_id on the subsequent session_pin stage (see router-pipeline).
+    //
+    const isEconomical = resolvePinnedTier(pin, fleet) === 'economical-cloud';
     const isIdentical = pin.last_tool_failure_signature === signature;
-    const newCount = isIdentical ? pin.consecutive_tool_failures + 1 : 1;
+    const newCount = isEconomical || isIdentical
+        ? pin.consecutive_tool_failures + 1
+        : 1;
     const updated = {
         ...pin,
         consecutive_tool_failures: newCount,

package/dist/domain/pinning/loop-escalation.js.map

@@ -1 +1 @@
-{"version":3,"file":"loop-escalation.js","sourceRoot":"","sources":["../../../src/domain/pinning/loop-escalation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop-escalation.js","sourceRoot":"","sources":["../../../src/domain/pinning/loop-escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsBH,wEAAwE;AACxE,MAAM,CAAC,MAAM,8BAA8B,GAAG,eAAwB,CAAC;AAEvE,iFAAiF;AAEjF,MAAM,gBAAgB,GAAG;IACvB,OAAO;IACP,MAAM;IACN,WAAW;IACX,WAAW;IACX,SAAS;IACT,cAAc;IACd,WAAW;IACX,YAAY;IACZ,OAAO;CACC,CAAC;AAEX,oFAAoF;AACpF,MAAM,yBAAyB,GAAG;IAChC,cAAc;IACd,kBAAkB;IAClB,gBAAgB;IAChB,cAAc;IACd,mBAAmB;IACnB,qBAAqB;IACrB,qBAAqB;IACrB,kBAAkB;CACV,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAuB;IACjE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gCAAgC,CAAC,OAAuB;IACtE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAuB;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,OAAO,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,2DAA2D;AAC3D,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9D,IAAI,CAAC,GAAG,IAAI,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,iBAAiB,CACxB,GAAe,EACf,KAA8B;IAE9B,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,eAAe,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;AACvE,CAAC;AAED,SAAS,gCAAgC,CAAC,MAA4B;IACpE,OAAO,MAAM,CAAC,6BAA6B,IAAI,MAAM,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,SAAS,WAAW,CAClB,GAAe,EACf,KAA8B,EAC9B,OAAmB,EACnB,MAAc;IAEd,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IAClE,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,cAAc,EAAE,IAAI;YACpB,UAAU,EAAE,OAAO;YACnB,gBAAgB,EAAE,MAAM;YACxB,MAAM;SACP,CAAC;IACJ,CAAC;IACD,OAAO;QACL,cAAc,EAAE,KAAK;QACrB,UAAU,EAAE,OAAO;QACnB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,uBAAuB;KAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,kCAAkC,CACzC,GAAe,EACf,OAAuB,EACvB,KAA8B,EAC9B,MAA4B;IAE5B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,IAAI,gCAAgC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAe;YAC1B,GAAG,GAAG;YACN,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,yBAAyB,EAAE,CAAC,CAAC;YACrE,2BAA2B,EAAE,qBAAqB;YAClD,UAAU,EAAE,GAAG;SAChB,CAAC;QACF,OAAO,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,4BAA4B,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,cAAc,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,GAAG,CAAC,2BAA2B,KAAK,8BAA8B,CAAC;IACnF,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,yBAAyB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,MAAM,OAAO,GAAe;QAC1B,GAAG,GAAG;QACN,yBAAyB,EAAE,QAAQ;QACnC,2BAA2B,EAAE,8BAA8B;QAC3D,UAAU,EAAE,GAAG;KAChB,CAAC;IAEF,IAAI,QAAQ,IAAI,cAAc,EAAE,CAAC;QAC/B,OAAO,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC;IAClE,CAAC;IAED,OAAO;QACL,cAAc,EAAE,KAAK;QACrB,UAAU,EAAE,OAAO;QACnB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,2BAA2B;KACpC,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAsB,EACtB,OAAuB,EACvB,KAA8B,EAC9B,MAA4B;IAE5B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,KAAK,iBAAiB,EAAE,CAAC;QACzC,OAAO,YAAY,CAAC,mBAAmB,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,KAAK,aAAa,EAAE,CAAC;QACxC,OAAO,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,WAAW,EAAE,CAAC;QAClD,OAAO,kCAAkC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAEvD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,GAAG,CAAC,yBAAyB,GAAG,CAAC,EAAE,CAAC;YACtC,OAAO;gBACL,cAAc,EAAE,KAAK;gBACrB,UAAU,EAAE;oBACV,GAAG,GAAG;oBACN,yBAAyB,EAAE,CAAC;oBAC5B,2BAA2B,EAAE,IAAI;oBACjC,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACrC;gBACD,gBAAgB,EAAE,IAAI;gBACtB,MAAM,EAAE,eAAe;aACxB,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IAED,EAAE;IACF,uDAAuD;IACvD,EAAE;IACF,2EAA2E;IAC3E,wEAAwE;IACxE,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,6EAA6E;IAC7E,wEAAwE;IACxE,yEAAyE;IACzE,EAAE;IACF,oDAAoD;IACpD,yEAAyE;IACzE,0DAA0D;IAC1D,2EAA2E;IAC3E,2EAA2E;IAC3E,+EAA+E;IAC/E,EAAE;IACF,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,kBAAkB,CAAC;IAC1E,MAAM,WAAW,GAAG,GAAG,CAAC,2BAA2B,KAAK,SAAS,CAAC;IAClE,MAAM,QAAQ,GACZ,YAAY,IAAI,WAAW;QACzB,CAAC,CAAC,GAAG,CAAC,yBAAyB,GAAG,CAAC;QACnC,CAAC,CAAC,CAAC,CAAC;IAER,MAAM,OAAO,GAAe;QAC1B,GAAG,GAAG;QACN,yBAAyB,EAAE,QAAQ;QACnC,2BAA2B,EAAE,SAAS;QACtC,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACrC,CAAC;IAEF,IAAI,QAAQ,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACjC,OAAO,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC;IAChE,CAAC;IAED,OAAO;QACL,cAAc,EAAE,KAAK;QACrB,UAAU,EAAE,OAAO;QACnB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,iBAAiB;KAC1B,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,CAAC;AAED,sFAAsF;AACtF,SAAS,sBAAsB,CAC7B,KAA8B,EAC9B,cAAsB;IAEtB,OAAO,CACL,KAAK,CAAC,IAAI,CACR,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,cAAc,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CACrF,IAAI,IAAI,CACV,CAAC;AACJ,CAAC"}

package/dist/domain/pinning/session-pinner.d.ts

@@ -21,9 +21,16 @@ import type { StorePort } from '../types/store-port.js';
 import { type CacheEconomicsConfig } from './cache-economics.js';
 import { type CacheBreakevenResult } from './cache-breakeven.js';
 import { FlipFlopGuard, type FlipFlopObservation, type FlipFlopSessionState } from './flip-flop-guard.js';
-export type PinAction = 'use_pin' | 'sub_route' | 'saar_route' | 'break' | 'no_pin';
+export type PinAction = 'use_pin' | 'sub_route' | 'saar_route' | 'break' | 'no_pin' | 'force_rejected';
 export type PinSaarReason = 'saar_buffer_active' | 'saar_hard_lock' | 'saar_idle_reopen' | 'saar_tier_upgrade';
 export type PinFlipFlopReason = 'flip_flop_tier_pinned';
+/**
+ * SP-209 / #121 — force_model_id could not be honored. Surfaced as the routing
+ * decision `reason_code` so explain / `SMART_ROUTER_LOG_ROUTING=1` makes the
+ * rejection explicit instead of silently remapping across provider families.
+ */
+export declare const FORCE_REJECTED_NOT_IN_FLEET: "force_rejected_not_in_fleet";
+export declare const FORCE_REJECTED_UNHEALTHY: "force_rejected_unhealthy";
 export interface PinLookupResult {
     readonly action: PinAction;
     readonly pinnedModel?: ModelProfile;
@@ -32,6 +39,10 @@ export interface PinLookupResult {
     readonly saarReason?: PinSaarReason;
     readonly flipFlopReason?: PinFlipFlopReason;
     readonly breakReason?: PinReason;
+    /** SP-209 / #121: rejection reason code when force_model_id cannot be honored. */
+    readonly forceRejectionReason?: string;
+    /** SP-209 / #121: the force_model_id value that was rejected. */
+    readonly forceModelId?: string;
 }
 export interface SessionPinnerConfig {
     /** FR-024: max payload size (bytes or token estimate) for sub-routing. Default 2048. */
@@ -141,7 +152,16 @@ export declare class SessionPinner {
     private evaluateBreakRules;
     private evaluateContextOverflowBreak;
     private evaluateCacheEconomicsBreak;
-    private handleForceOverride;
+    /**
+     * SP-209 / #121: resolve an explicit force_model_id override.
+     *
+     * Healthy in-fleet target → pin to it (`use_pin`). Unavailable target → fail
+     * closed (`force_rejected`) carrying an explicit reason code so the pipeline
+     * can surface the rejection in explain / SMART_ROUTER_LOG_ROUTING instead of
+     * silently remapping to a different provider family. A rejected force is a
+     * no-op on pin state — the existing pin (if any) is preserved.
+     */
+    private resolveForceOverride;
     private persistPin;
     private deletePersistedPin;
     private evaluateSubRouting;