pi-smart-router 0.13.0 → 0.15.0

package/.pi/extensions/smart-router/command-formatters.ts

@@ -17,6 +17,7 @@ import {
   DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT,
   parseExportTelemetryContribArgs,
 } from '../../../src/cli/smart-router-cli.js';
+import type { PlacementPlanReport } from '../../../src/infrastructure/hardware/placement-plan.js';
 import {
   DEFAULT_DATASET_EXPORT_LIMIT,
   MAX_DATASET_EXPORT_LIMIT,
@@ -146,12 +147,20 @@ export function parseExportLimit(tokens: string[]): number {
   return limit;
 }
 
-export function parseSmartRouterArgs(args: string): SmartRouterCommand {
+export function parseSmartRouterArgs(args: string): ParsedSmartRouterCommand {
   const tokens = args.trim().split(/\s+/).filter(Boolean);
   if (tokens.length === 0 || tokens[0] === 'status') {
     return { command: 'status' };
   }
 
+  if (tokens[0] === 'plan' && (tokens.length === 1 || (tokens.length === 2 && tokens[1] === '--json'))) {
+    return { command: 'plan', format: tokens[1] === '--json' ? 'json' : 'text' };
+  }
+
+  if (tokens[0] === 'doctor' && tokens.length === 1) {
+    return { command: 'doctor' };
+  }
+
   if (tokens[0] === 'history') {
     return { command: 'history', limit: parseHistoryLimit(tokens[1]) };
   }
@@ -339,3 +348,70 @@ export function buildStatsSnapshot(
 }
 
 export type { FleetMode };
+
+/**
+ * Read-only placement commands (SP-216, #116). Declared here instead of
+ * types.ts to keep the SmartRouterCommand union untouched.
+ */
+export type SmartRouterPlacementCommand =
+  | { command: 'plan'; format: 'text' | 'json' }
+  | { command: 'doctor' };
+
+export type ParsedSmartRouterCommand = SmartRouterCommand | SmartRouterPlacementCommand;
+
+function formatTps(value: number | null): string {
+  return value === null ? 'n/a' : `${value.toFixed(1)} tok/s`;
+}
+
+function formatGb(value: number | null): string {
+  return value === null ? 'unknown' : `${value.toFixed(1)} GiB`;
+}
+
+function formatPing(label: string, ping: PlacementPlanReport['localModel']['lmStudio']): string {
+  if (!ping.available) {
+    return `  ${label}: unreachable`;
+  }
+  return `  ${label}: up, model ${ping.hasLoadedModel ? 'loaded (warm)' : 'not loaded (cold)'}`;
+}
+
+/** Human-readable placement report for `/smart-router plan` (read-only). */
+export function formatPlacementPlanMessage(report: PlacementPlanReport): string {
+  const lines = [
+    `Placement plan (read-only, schema v${report.schemaVersion}) — ${report.generatedAt}`,
+    `Recommendation: ${report.recommendation}`,
+    `Bottleneck guess: ${report.bottleneck.guess} — ${report.bottleneck.rationale}`,
+    `Encoder: ${report.encoder.resident ? 'resident' : 'not resident'} (${report.encoder.model}) at ${report.encoder.cachePath}`,
+    `Local model: ${report.localModel.warm ? 'warm' : report.localModel.coldStartExpected ? 'cold (load on first request)' : 'unavailable'}`,
+    formatPing('LM Studio', report.localModel.lmStudio),
+    formatPing('Ollama', report.localModel.ollama),
+    `Hardware: ${report.hardware.platform}/${report.hardware.arch}, total ${formatGb(report.hardware.totalMemoryGb)}, free ${formatGb(report.hardware.freeMemoryGb)}, probe=${report.hardware.probe}`,
+    `Disk (${report.disk.path}): free ${formatGb(report.disk.freeGb)}${report.disk.constrained ? ' [constrained]' : ''}`,
+    `Throughput: ${report.throughput.classification} | warm median ${formatTps(report.throughput.warmMedianTps)} (${report.throughput.warmSamples} samples) | cold median ${formatTps(report.throughput.coldMedianTps)} (${report.throughput.coldSamples} samples) | threshold ${report.throughput.thresholdTps} tok/s | viable=${report.throughput.viable}`,
+    `Policy: quality-preserving — on resource pressure: ${report.policy.onResourcePressure}`,
+  ];
+  return lines.join('\n');
+}
+
+/** Checklist-style readiness verdict for `/smart-router doctor` (read-only). */
+export function formatDoctorMessage(report: PlacementPlanReport): string {
+  const check = (ok: boolean, label: string): string => `${ok ? '✓' : '✗'} ${label}`;
+  const lines = [
+    'smart-router doctor (read-only)',
+    check(report.encoder.resident, `encoder resident (${report.encoder.model})`),
+    check(report.hardware.probe === 'full_local', `hardware probe: ${report.hardware.probe}`),
+    check(!report.disk.constrained, `disk: ${formatGb(report.disk.freeGb)} free${report.disk.constrained ? ' [constrained]' : ''}`),
+    check(
+      report.localModel.lmStudio.available || report.localModel.ollama.available,
+      'local runtime reachable (LM Studio / Ollama)',
+    ),
+    check(report.localModel.warm, `local model ${report.localModel.warm ? 'warm' : 'cold/not loaded'}`),
+    check(
+      report.throughput.viable,
+      `throughput: ${report.throughput.classification}, viable=${report.throughput.viable}${report.throughput.classification === 'cold-only' ? ' (cold-only windows fail closed)' : ''}`,
+    ),
+    `Bottleneck guess: ${report.bottleneck.guess} — ${report.bottleneck.rationale}`,
+    `Recommendation: ${report.recommendation}`,
+    'Policy: quality-preserving — under resource pressure local is reported unavailable and routing escalates safely; encoder fidelity is never weakened.',
+  ];
+  return lines.join('\n');
+}

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

@@ -1,20 +1,24 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { join } from 'node:path';
 
 import {
+  formatDoctorMessage,
   formatHistoryMessage,
+  formatPlacementPlanMessage,
   formatStatsMessage,
   formatStatusMessage,
   parseSmartRouterArgs,
 } from './command-formatters.js';
 import { exportDatasetToFile } from './dataset-export.js';
 import { exportTelemetryContrib } from '../../../src/cli/smart-router-cli.js';
+import { collectPlacementPlan } from '../../../src/infrastructure/hardware/placement-plan.js';
 import { bindSharedModelRegistry, rebuildFleet } from './fleet-bootstrap.js';
 import { refreshPricingCatalog } from './pricing-lifecycle.js';
 import { FLEET_MODE_ENTRY_TYPE } from './session-lifecycle.js';
 import type { SmartRouterRuntime } from './types.js';
 
 export const SMART_ROUTER_USAGE =
-  '/smart-router [status] | history [limit] | stats [limit] | mode scoped|all | pricing refresh | export dataset [--limit N] | export telemetry-contrib [--limit N] | feedback good|bad | unpin';
+  '/smart-router [status] | history [limit] | stats [limit] | mode scoped|all | pricing refresh | export dataset [--limit N] | export telemetry-contrib [--limit N] | feedback good|bad | unpin | plan [--json] | doctor';
 
 type CompletionItem = { value: string; label: string };
 
@@ -27,6 +31,8 @@ const TOP_LEVEL: CompletionItem[] = [
   { value: 'export', label: 'Export opt-in routing dataset' },
   { value: 'feedback', label: 'Label last routing outcome good or bad' },
   { value: 'unpin', label: 'Clear current session pin' },
+  { value: 'plan', label: 'Read-only local placement report (warm/cold, bottleneck)' },
+  { value: 'doctor', label: 'Read-only local readiness checklist' },
 ];
 
 const MODE_COMPLETIONS: CompletionItem[] = [
@@ -66,6 +72,9 @@ export const SMART_ROUTER_FULL_INVOCATIONS = [
   'feedback good',
   'feedback bad',
   'unpin',
+  'plan',
+  'plan --json',
+  'doctor',
 ] as const;
 
 function filterByPrefix(items: CompletionItem[], prefix: string): CompletionItem[] {
@@ -267,6 +276,27 @@ export function registerSmartRouterCommand(
           return;
         }
 
+        if (parsed.command === 'plan' || parsed.command === 'doctor') {
+          throwIfCommandAborted(signal);
+          // Read-only: pings + fs stats only; never mutates route/pin/gates.
+          const report = await collectPlacementPlan({
+            encoderCachePath: join(ctx.cwd, '.pi-smart-router/models'),
+            diskPath: ctx.cwd,
+          });
+          throwIfCommandAborted(signal);
+          if (parsed.command === 'plan' && parsed.format === 'json') {
+            ctx.ui.notify(JSON.stringify(report, null, 2), 'info');
+            return;
+          }
+          ctx.ui.notify(
+            parsed.command === 'doctor'
+              ? formatDoctorMessage(report)
+              : formatPlacementPlanMessage(report),
+            'info',
+          );
+          return;
+        }
+
         if (parsed.command === 'unpin') {
           const sessionId = ctx.sessionManager.getSessionId();
           const sessionPinner = runtime.streamDeps.sessionPinner;

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

@@ -225,9 +225,31 @@ Cursor models bill against your **Cursor Pro subscription quota**, not per-token
 | `/smart-router export telemetry-contrib [--limit N]` | Export privacy-safe community telemetry JSON for calibration contributions |
 | `/smart-router feedback good\|bad` | Label the last auto-routed request outcome (requires `SMART_ROUTER_DATASET=1`) |
 | `/smart-router unpin` | Clear the current session pin (in-memory and SQLite) so the next request runs the full routing pipeline |
+| `/smart-router plan [--json]` | **Read-only** local placement report: encoder resident status, local model warm/cold, RAM/disk constraints, cold vs warm TPS, and bottleneck guess. `--json` prints the schema-stable report for automation |
+| `/smart-router doctor` | **Read-only** local readiness checklist (✓/✗) with bottleneck guess and recommendation — validate placement without starting a route |
 
 Fleet mode persists in the session. Use `scoped` to respect your `/model` enable-list; use `all` when you want the router to consider every provider you have logged into.
 
+### Local placement plan / doctor (read-only, #116)
+
+`/smart-router plan` and `/smart-router doctor` report **local placement readiness without mutating anything** — no route, pin, or gate is touched. Inspired by Colibrì's `coli plan` / `coli doctor`.
+
+The report covers:
+
+- **Encoder** — whether HyDRA ONNX artifacts are resident in the cache (`.pi-smart-router/models/`) or will download on first route
+- **Local model warm/cold** — LM Studio / Ollama reachability and whether a model is actually loaded (`warm`) vs reachable-but-unloaded (`cold-start expected`)
+- **Hardware** — platform/arch, total/free RAM, hardware-probe verdict (`full_local` / `classification_only` / `disabled`), battery state
+- **Disk** — free GiB; flagged constrained below 2 GiB
+- **Throughput (cold vs warm TPS)** — see formula below
+- **Bottleneck guess** — one of `none`, `unsupported-platform`, `battery`, `memory`, `disk`, `no-local-runtime`, `cold-start`, `cold-throughput`, `warm-throughput`, with a rationale string
+- **Recommendation** — `local-ready`, `local-warmup-needed`, or `local-unavailable`
+
+`/smart-router plan --json` prints the same report as schema-stable JSON (`schemaVersion: 1`, `kind: "smart-router-placement-plan"`; all keys always present, unknowns are `null`) for automation.
+
+**Cold vs warm TPS formula.** Throughput samples are tagged by phase: `warm` samples measure steady-state generation after model load; `cold` samples include cold-start load cost and never count toward viability. `warmMedianTps = median(tps where phase='warm')`; viability is `warmSamples > 0 AND warmMedianTps >= threshold` (default 25 tok/s). **Cold-only windows fail closed**: when only cold samples exist, local viability is false by policy (`requireWarmSamples: true`) — cold-start cost must not masquerade as steady-state throughput.
+
+**Quality-preserving resource policy.** Under RAM/disk/battery pressure the router prefers **"local unavailable / escalate safely"** to a cloud default over silently weakening encoder fidelity (no quantization flips, no cheaper cascades, no FrugalGPT-style downgrade chains). `plan`/`doctor` surface this policy verbatim in the report's `policy` block.
+
 After typing `/smart-router ` (with a trailing space), press **TAB** to see subcommands. Continue TAB-completing after `mode` or `pricing` for sub-options (`scoped`/`all`, `refresh`).
 
 ### 5. Verify
@@ -368,6 +390,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 +466,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 +505,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`):

package/dist/config/defaults.d.ts

@@ -3,7 +3,7 @@
  * Values sourced from specs/001-build-smart-router/data-model.md § Configuration (Operator).
  */
 import { type OperatorConfig } from '../domain/types/schemas.js';
-export { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
+export { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, DEFAULT_SPECULATIVE_PREWARM_CONFIG, DEFAULT_WORKLOAD_HEAT_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
 /** Merge operator env overrides onto defaults (SAAR and planning delegate sections). */
 export declare function resolveOperatorConfigFromEnv(base?: OperatorConfig): OperatorConfig;
 export declare const DEFAULT_OPERATOR_CONFIG: Readonly<OperatorConfig>;

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,EASL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,kCAAkC,EAClC,4BAA4B,EAC5B,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,CAqCnD,CAAC"}

package/dist/config/defaults.js

@@ -2,9 +2,9 @@
  * 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, DEFAULT_SPECULATIVE_PREWARM_CONFIG, DEFAULT_WORKLOAD_HEAT_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';
+export { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, DEFAULT_SPECULATIVE_PREWARM_CONFIG, DEFAULT_WORKLOAD_HEAT_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
 /** Merge operator env overrides onto defaults (SAAR and planning delegate sections). */
 export function resolveOperatorConfigFromEnv(base = DEFAULT_OPERATOR_CONFIG) {
     return {
@@ -44,6 +44,11 @@ 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,
+    /** Heat knobs only (SP-215) — no frugality default or absolute-gate flips. */
+    workload_heat: DEFAULT_WORKLOAD_HEAT_CONFIG,
+    /** Speculative prewarm (SP-217, #117): default OFF; opt-in via operator config. */
+    speculative_prewarm: DEFAULT_SPECULATIVE_PREWARM_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,kCAAkC,EAClC,4BAA4B,EAC5B,oCAAoC,EACpC,wBAAwB,GAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,kCAAkC,EAClC,4BAA4B,EAC5B,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,8EAA8E;IAC9E,aAAa,EAAE,4BAA4B;IAC3C,mFAAmF;IACnF,mBAAmB,EAAE,kCAAkC;IACvD,iBAAiB,EAAE,KAAK;CAChB,CAAC"}