pi-smart-router 0.20.0 → 0.22.0

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

@@ -1,23 +1,21 @@
 import {
   DEFAULT_HISTORY_LIMIT,
   MAX_HISTORY_LIMIT,
-} from '../../../src/infrastructure/telemetry/telemetry-limits.js';
+  aggregateSessionStatsFromFleet,
+  DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT,
+  parseExportTelemetryContribArgs,
+} from '../../../src/index.js';
 import type {
   ModelProfile,
   PriceCatalog,
   RoutingDecision,
   RoutingTelemetry,
-} from '../../../src/domain/types/index.js';
-import {
-  aggregateSessionStatsFromFleet,
-  type SessionStatsSnapshot,
-} from '../../../src/infrastructure/telemetry/session-stats.js';
+  SessionStatsSnapshot,
+  PlacementPlanReport,
+} from '../../../src/index.js';
+
 import { SMART_ROUTER_USAGE } from './commands.js';
-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,

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

@@ -10,8 +10,11 @@ import {
   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 {
+  exportTelemetryContrib,
+  collectPlacementPlan,
+} from '../../../src/index.js';
+
 import { bindSharedModelRegistry, rebuildFleet } from './fleet-bootstrap.js';
 import { refreshPricingCatalog } from './pricing-lifecycle.js';
 import { FLEET_MODE_ENTRY_TYPE } from './session-lifecycle.js';

package/.pi/extensions/smart-router/dataset-export.ts

@@ -6,15 +6,16 @@ import { createHash } from 'node:crypto';
 import {
   attachOutcomeLabelsToExport,
   indexOutcomesByRequestId,
-} from '../../../src/domain/routing/p-success-classifier.js';
-import { DATASET_MAX_ENTRIES } from '../../../src/infrastructure/telemetry/dataset-limits.js';
-import {
+  DATASET_MAX_ENTRIES,
   DatasetRecorder,
   DATASET_ENABLED_NOTIFY_MESSAGE,
-} from '../../../src/infrastructure/telemetry/dataset-recorder.js';
-import { OutcomeRecorder } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import type { RoutingDatasetRecord, RoutingOutcomeRecord } from '../../../src/domain/types/index.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
+  OutcomeRecorder,
+} from '../../../src/index.js';
+import type {
+  RoutingDatasetRecord,
+  RoutingOutcomeRecord,
+  StorePort,
+} from '../../../src/index.js';
 
 const DEFAULT_DATASET_EXPORT_DIR = '.pi-smart-router/exports';
 const DEFAULT_DATASET_EXPORT_LIMIT = DATASET_MAX_ENTRIES;

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

@@ -9,13 +9,16 @@ import {
   streamSimple as compatDelegateStream,
 } from '@earendil-works/pi-ai/compat';
 
-import { parseAssistantMessageError } from '../../../src/infrastructure/delegation/provider-error.js';
-import { extractUsageActuals } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
 import {
+  parseAssistantMessageError,
+  extractUsageActuals,
   resolveAdaptiveReasoning,
-  type AdaptiveReasoningResult,
-  type AdaptiveReasoningSignal,
-} from '../../../src/domain/delegation/adaptive-reasoning.js';
+} from '../../../src/index.js';
+import type {
+  AdaptiveReasoningResult,
+  AdaptiveReasoningSignal,
+} from '../../../src/index.js';
+
 import {
   buildDelegationContext,
   forwardDelegatedEvent,

package/.pi/extensions/smart-router/delegation-runtime.ts

@@ -15,26 +15,23 @@ import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 
 import {
   applyConcisenessHint,
-  type AdaptiveReasoningResult,
-} from '../../../src/domain/delegation/adaptive-reasoning.js';
-import {
   isGoogleDelegationTarget,
   normalizeDelegationContext,
   repairGeminiReplayContext,
-} from '../../../src/domain/delegation/delegation-context.js';
-import {
   computeOutputHeadroom,
-  type OutputHeadroomConfig,
-} from '../../../src/domain/delegation/output-headroom.js';
-import type { ModelProfile } from '../../../src/domain/types/index.js';
-import {
   formatGeminiThoughtSignatureErrorMessage,
   formatProviderErrorMessage,
   isGeminiThoughtSignatureAssistantError,
   parseAssistantMessageError,
   sanitizeLengthStopMessage,
-  type LengthStopHints,
-} from '../../../src/infrastructure/delegation/provider-error.js';
+} from '../../../src/index.js';
+import type {
+  AdaptiveReasoningResult,
+  OutputHeadroomConfig,
+  ModelProfile,
+  LengthStopHints,
+} from '../../../src/index.js';
+
 import type { StreamDelegationDeps } from './types.js';
 
 /** Stream options safe to forward to a delegated provider call. */

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

@@ -4,10 +4,15 @@ import {
   type ExtensionAPI,
 } from '@earendil-works/pi-coding-agent';
 
-import { resolveOperatorConfigFromEnv } from '../../../src/config/defaults.js';
-import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
-import type { SessionRoutingSnapshot } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import { createRouterFromFleet, LifecycleHookState } from '../../../src/index.js';
+import {
+  resolveOperatorConfigFromEnv,
+  ExecutionLedger,
+  createRouterFromFleet,
+  LifecycleHookState,
+} from '../../../src/index.js';
+import type {
+  SessionRoutingSnapshot,
+} from '../../../src/index.js';
 
 import { registerSmartRouterCommand } from './commands.js';
 import {

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

@@ -2,39 +2,37 @@ import type { Api, Model } from '@earendil-works/pi-ai/compat';
 import {
   ModelRegistry,
   SettingsManager,
-  type ExtensionAPI,
+  ExtensionAPI,
 } from '@earendil-works/pi-coding-agent';
 
-import { mapFleetFromRegistry } from '../../../src/config/pi-model-mapper.js';
 import {
+  mapFleetFromRegistry,
   DEFAULT_OPERATOR_CONFIG,
   resolveOperatorConfigFromEnv,
-} from '../../../src/config/defaults.js';
-import {
   HydraMatcher,
   createOnnxEmbeddingProvider,
-} from '../../../src/domain/matching/hydra-matcher.js';
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
-import {
+  SessionPinner,
   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';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import { getDefaultSystemInfo } from '../../../src/infrastructure/hardware/hardware-probe.js';
-import { DEFAULT_LOCAL_CONFIG } from '../../../src/infrastructure/local/local-zero-tier.js';
-import { RoutingTelemetryEmitter } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
-import { applyCatalogPricesToFleet } from '../../../src/infrastructure/pricing/price-broker.js';
-import {
+  getDefaultSystemInfo,
+  DEFAULT_LOCAL_CONFIG,
+  RoutingTelemetryEmitter,
+  applyCatalogPricesToFleet,
   createRouterFromFleet,
-  type GatewayDispatchOptions,
-  type PiExtensionHooks,
 } from '../../../src/index.js';
+import type {
+  QuotaWindowAdapter,
+  QuotaWindowEstimateConfig,
+  ModelProfile,
+  PriceCatalog,
+  QuotaWindowPosition,
+  OperatorConfig,
+  StorePort,
+  GatewayDispatchOptions,
+  PiExtensionHooks,
+} from '../../../src/index.js';
+
 import { resolveModelScope } from './pi-model-scope.js';
 import type { FleetMode, SmartRouterRuntime } from './types.js';
 import { resolveRateLimiter } from './utils.js';

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

@@ -6,8 +6,9 @@
  * hooks for routing state. Stream delegation routes each request through the
  * pipeline and forwards to the selected provider's built-in streaming API.
  *
- * Imports from ../../../src/** (not dist/) because the extension is loaded by pi
- * from source at dev time and is excluded from the npm dist artifact.
+ * Imports the package public facade (../../../src/index.js, not dist/) because
+ * the extension is loaded by pi from source at dev time and is excluded from
+ * the npm dist artifact. Deep src/** subpath imports are forbidden (SP-256/257).
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -116,14 +117,14 @@ export { routeAndDelegate } from './route-and-delegate.js';
 export {
   formatGeminiThoughtSignatureErrorMessage,
   isGeminiThoughtSignatureAssistantError,
-} from '../../../src/infrastructure/delegation/provider-error.js';
+} from '../../../src/index.js';
 export {
   GEMINI_TOOL_HISTORY_EXCLUDED,
   hasToolCallHistory,
   hasToolCallHistoryFromContext,
   isGoogleGeminiProfile,
   resolveEffectiveFleet,
-} from '../../../src/domain/routing/tool-history-guard.js';
+} from '../../../src/index.js';
 
 export default async function smartRouterExtension(pi: ExtensionAPI): Promise<void> {
   const cwd = process.cwd();

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

@@ -22,21 +22,22 @@ import {
   type TextContent,
 } from '@earendil-works/pi-ai/compat';
 
-import type {
-  CompressedContextSpec,
-  PlanningDelegateObservability,
-  RoutingDecision,
-} from '../../../src/domain/types/index.js';
-import { resolveAdaptiveReasoning } from '../../../src/domain/delegation/adaptive-reasoning.js';
-import { DEFAULT_PLANNING_DELEGATE_CONFIG } from '../../../src/domain/types/schemas.js';
 import {
+  resolveAdaptiveReasoning,
+  DEFAULT_PLANNING_DELEGATE_CONFIG,
   createPlanningDelegateObservability,
   enrichRoutingDecisionWithPlanningDelegate,
   PLANNING_DELEGATE,
   PLANNING_DELEGATE_TIMEOUT,
   PLANNING_DELEGATE_UNAVAILABLE,
   PLANNING_DIRECT_FRONTIER,
-} from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+} from '../../../src/index.js';
+import type {
+  CompressedContextSpec,
+  PlanningDelegateObservability,
+  RoutingDecision,
+} from '../../../src/index.js';
+
 import { collectDelegatedStream } from './delegate-stream.js';
 import { findFleetProfile, resolveRegistryModel } from './delegation-runtime.js';
 import type { StreamDelegationDeps } from './types.js';

package/.pi/extensions/smart-router/pricing-lifecycle.ts

@@ -1,7 +1,12 @@
-import { DEFAULT_OPERATOR_CONFIG } from '../../../src/config/defaults.js';
-import type { PriceCatalog } from '../../../src/domain/types/index.js';
-import { fetchLitellmPriceCatalog } from '../../../src/infrastructure/pricing/litellm-fetch.js';
-import { checkStaleness } from '../../../src/infrastructure/pricing/pricing-monitor.js';
+import {
+  DEFAULT_OPERATOR_CONFIG,
+  fetchLitellmPriceCatalog,
+  checkStaleness,
+} from '../../../src/index.js';
+import type {
+  PriceCatalog,
+} from '../../../src/index.js';
+
 import type { SmartRouterRuntime } from './types.js';
 
 export async function refreshPricingCatalog(

package/.pi/extensions/smart-router/route-and-delegate.ts

@@ -7,27 +7,28 @@ import type {
   SimpleStreamOptions,
 } from '@earendil-works/pi-ai/compat';
 
-import { safeCloudDefault } from '../../../src/domain/pipeline/safe-default.js';
-import { computeOutputHeadroom } from '../../../src/domain/delegation/output-headroom.js';
-import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
 import {
+  safeCloudDefault,
+  computeOutputHeadroom,
+  resolvePeakPricingAdjustment,
   CONTEXT_OVERFLOW_NO_FIT,
   resolveContextOverflowFallback,
-} from '../../../src/domain/routing/context-fit.js';
-import {
   assertRoutableFleetAfterGeminiToolHistoryGuard,
   GEMINI_TOOL_HISTORY_EXCLUDED,
   isGoogleGeminiProfile,
   resolveEffectiveFleet,
-} from '../../../src/domain/routing/tool-history-guard.js';
-import type { ModelProfile, RoutingDecision, RoutingRequest } from '../../../src/domain/types/index.js';
-import type { GeminiToolHistoryGuardResult } from '../../../src/domain/routing/tool-history-guard.js';
-import {
   isGeminiThoughtSignatureAssistantError,
   parseAssistantMessageError,
-} from '../../../src/infrastructure/delegation/provider-error.js';
-import { GEMINI_REPLAY_INCOMPATIBLE } from '../../../src/infra/gemini-provider.js';
-import { shouldFailoverOnProviderError } from '../../../src/infrastructure/gateway/gateway-dispatch.js';
+  GEMINI_REPLAY_INCOMPATIBLE,
+  shouldFailoverOnProviderError,
+} from '../../../src/index.js';
+import type {
+  ModelProfile,
+  RoutingDecision,
+  RoutingRequest,
+  GeminiToolHistoryGuardResult,
+} from '../../../src/index.js';
+
 import {
   commitPipedTerminal,
   delegateWithOutcome,

package/.pi/extensions/smart-router/routing-context.ts

@@ -7,12 +7,14 @@ import {
   type TextContent,
 } from '@earendil-works/pi-ai/compat';
 
+import {
+  LifecycleHookState,
+} from '../../../src/index.js';
 import type {
   Message as RoutingMessage,
   RoutingRequest,
   TurnType,
-} from '../../../src/domain/types/index.js';
-import { LifecycleHookState } from '../../../src/index.js';
+} from '../../../src/index.js';
 
 const TOKEN_ESTIMATE_KEYS = [
   'estimatedInputTokens',

package/.pi/extensions/smart-router/routing-outcomes.ts

@@ -1,5 +1,9 @@
-import type { RoutingDecision, RoutingRequest } from '../../../src/domain/types/index.js';
-import type { SessionRoutingSnapshot } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
+import type {
+  RoutingDecision,
+  RoutingRequest,
+  SessionRoutingSnapshot,
+} from '../../../src/index.js';
+
 import type { StreamDelegationDeps } from './types.js';
 
 export function capturePreRouteOutcomes(

package/.pi/extensions/smart-router/session-lifecycle.ts

@@ -1,6 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import {
+  evictInMemorySessionState,
+  SessionPinner,
+} from '../../../src/index.js';
+
 import {
   bindSharedModelRegistry,
   ensureFleetFresh,
@@ -15,6 +19,15 @@ export const FLEET_MODE_ENTRY_TYPE = 'smart-router-fleet-mode' as const;
 const SMART_ROUTER_PROVIDER = 'smart-router' as const;
 const SMART_ROUTER_AUTO_ID = 'auto' as const;
 
+/**
+ * Orphan-session TTL fallback (SP-248, #145). `session_shutdown` is the primary
+ * teardown signal; if pi ever shuts a session down without delivering it
+ * (extension reload races, missed events), the session's in-memory routing
+ * state is evicted once it has been idle for ORPHAN_SESSION_TTL_MS. The sweep
+ * runs on `session_start` and fails open — eviction must never break startup.
+ */
+export const ORPHAN_SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
 export function isSmartRouterActive(model: { provider: string; id: string }): boolean {
   return model.provider === SMART_ROUTER_PROVIDER && model.id === SMART_ROUTER_AUTO_ID;
 }
@@ -97,6 +110,39 @@ export function setupSessionHooks(
 ): void {
   let activeModel: { provider: string; id: string } | undefined;
 
+  // Last-seen stamp per session for the orphan-TTL fallback (SP-248).
+  const lastSeenBySession = new Map<string, number>();
+
+  /** Evict all in-memory routing state for one session via the SP-247 helper. */
+  function evictSessionState(sessionId: string | undefined): void {
+    // Fail open: a missing/empty session id must never break teardown.
+    if (sessionId === undefined || sessionId === '') {
+      return;
+    }
+    evictInMemorySessionState(sessionId, {
+      executionLedger: runtime.executionLedger,
+      lifecycleHookState: runtime.lifecycleHookState,
+      sessionRouting: runtime.sessionRouting,
+    });
+    lastSeenBySession.delete(sessionId);
+  }
+
+  /** Drop sessions idle longer than ORPHAN_SESSION_TTL_MS (never throws). */
+  function sweepOrphanedSessions(now: number): void {
+    try {
+      for (const [sessionId, lastSeen] of lastSeenBySession) {
+        if (now - lastSeen > ORPHAN_SESSION_TTL_MS) {
+          evictSessionState(sessionId);
+        }
+      }
+    } catch (error) {
+      console.warn(
+        '[smart-router] orphan session sweep failed (fail open)',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
   pi.on('session_start', async (_event, ctx) => {
     activeModel = ctx.model;
     bindSharedModelRegistry(runtime, ctx.modelRegistry);
@@ -128,6 +174,10 @@ export function setupSessionHooks(
     datasetNotify.fn = runtime.notifyDatasetEnabled;
 
     const sessionId = ctx.sessionManager.getSessionId();
+    const now = Date.now();
+    lastSeenBySession.set(sessionId, now);
+    sweepOrphanedSessions(now);
+
     await sessionPinner.restoreSessionPin(sessionId);
 
     if (ctx.model !== undefined && isSmartRouterActive(ctx.model)) {
@@ -158,5 +208,17 @@ export function setupSessionHooks(
     delete runtime.streamDeps.ensureFleetFresh;
     datasetNotify.fn = undefined;
     ctx.ui.setStatus('smart-router-lmu', undefined);
+
+    // SP-248 (#145): drop per-session routing state so long-running pi
+    // processes do not retain ledger/lifecycle/routing maps forever.
+    // Fail open — teardown cleanup must never crash the host agent.
+    try {
+      evictSessionState(ctx.sessionManager.getSessionId());
+    } catch (error) {
+      console.warn(
+        '[smart-router] session teardown eviction failed (fail open)',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
   });
 }

package/.pi/extensions/smart-router/stream-delegation.ts

@@ -7,8 +7,14 @@ import {
   createAssistantMessageEventStream,
 } from '@earendil-works/pi-ai/compat';
 
-import type { RoutingDecision, RoutingFeatureSidecar } from '../../../src/domain/types/index.js';
-import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
+import {
+  resolvePeakPricingAdjustment,
+} from '../../../src/index.js';
+import type {
+  RoutingDecision,
+  RoutingFeatureSidecar,
+} from '../../../src/index.js';
+
 import { createErrorMessage } from './delegation-runtime.js';
 import { routeAndDelegate } from './route-and-delegate.js';
 import type { StreamDelegationDeps } from './types.js';

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

@@ -7,10 +7,15 @@ import type {
 } from '@earendil-works/pi-ai/compat';
 import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 
-import type { HydraMatcher } from '../../../src/domain/matching/hydra-matcher.js';
-import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import {
+  ExecutionLedger,
+  SessionPinner,
+  DatasetRecorder,
+  OutcomeRecorder,
+  LifecycleHookState,
+} from '../../../src/index.js';
 import type {
+  HydraMatcher,
   AdaptiveReasoningConfig,
   ModelProfile,
   PlanningDelegateConfig,
@@ -18,21 +23,13 @@ import type {
   RoutingDecision,
   RoutingReasoningTelemetry,
   RoutingUsageActuals,
-} from '../../../src/domain/types/index.js';
-import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import {
-  DatasetRecorder,
-} from '../../../src/infrastructure/telemetry/dataset-recorder.js';
-import {
-  OutcomeRecorder,
-  type SessionRoutingSnapshot,
-} from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import {
-  LifecycleHookState,
-  type RouterHandle,
+  StorePort,
+  SessionRoutingSnapshot,
+  RouterHandle,
 } from '../../../src/index.js';
 
+import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
+
 export type FleetMode = 'scoped' | 'all';
 
 export type SmartRouterCommand =

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

@@ -4,9 +4,11 @@ import {
   createResilientStore,
   SqliteStore,
   SqliteStoreError,
-} from '../../../src/infrastructure/persistence/sqlite-store.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import type { RateLimitPort } from '../../../src/infrastructure/gateway/gateway-dispatch.js';
+} from '../../../src/index.js';
+import type {
+  StorePort,
+  RateLimitPort,
+} from '../../../src/index.js';
 
 export const DEFAULT_ROUTER_STATE_DB_PATH = '.pi-smart-router/state.db';
 export const DEFAULT_RATE_LIMIT_MAX_TOKENS = 60;

package/README.md

@@ -290,7 +290,7 @@ These behaviors run in `.pi/extensions/smart-router/` and have **no equivalent i
 ### Recommended integration path
 
 - **pi users:** install the **extension** (`pi install npm:pi-smart-router`). It is the full product — everything in the table above works out of the box, including failover, delegate spawn, headroom escalation, and quota reaction.
-- **npm embedders:** you get the **routing core** (12-stage pipeline, fleet mapping, telemetry, gateway health tracking, failover *selection*). Plan to implement your own stream delegation, failover iteration, headroom checks, and planning-delegate spawn around the decisions the pipeline returns — or track [#149](https://github.com/beettlle/pi-smart-router/issues/149) (**extension public facade**), the migration plan for exposing the extension's stream/delegation surface as supported library API so this gap closes over time. Until #149 lands, the extension modules also import `src/**` internals directly, so deep imports into `src/` are not a stable API.
+- **npm embedders:** you get the **routing core** (12-stage pipeline, fleet mapping, telemetry, gateway health tracking, failover *selection*). Plan to implement your own stream delegation, failover iteration, headroom checks, and planning-delegate spawn around the decisions the pipeline returns — or track [#149](https://github.com/beettlle/pi-smart-router/issues/149) (**extension public facade**), the migration plan for exposing the extension's stream/delegation surface as supported library API so this gap closes over time. Until #149 lands, the extension modules also import `src/**` internals directly, so deep imports into `src/` are not a stable API. See [docs/extension-package-boundary.md](docs/extension-package-boundary.md) for the facade vs internal-API boundary, the deep-import lint guard, and the extension coverage gate.
 
 ```text
 pi extension path (full product)        npm library path (routing core)
@@ -489,6 +489,8 @@ v0.2.0 adds **Session-Aware Agentic Routing (SAAR)** pin knobs ([#72](https://gi
 
 See [routing-roadmap.md](docs/routing-roadmap.md) §2 P0 for design context.
 
+**Long-running pi sessions — in-memory state eviction (v0.21.0, [#145](https://github.com/beettlle/pi-smart-router/issues/145)).** Session pins and in-memory routing snapshots live in process memory, not in the SQLite telemetry store. When pi ends a session, the extension's `session_shutdown` handler (reason: `quit` / `reload` / `new` / `resume` / `fork`) calls `evictInMemorySessionState` (`src/api/session-eviction.ts`) and drops **all** in-memory routing state for that session — pins, cache-breakeven snapshots, turn metadata. A new session starts cold: no stale pin, no warm-cache assumption carries over. Persistent telemetry in `.pi-smart-router/state.db` is untouched. As a safety net for orphaned sessions (e.g. a crashed pi process that never emitted `session_shutdown`), a sweep on `session_start` evicts sessions idle longer than `ORPHAN_SESSION_TTL_MS` (**24 hours**, exported from `.pi/extensions/smart-router/session-lifecycle.ts`); the sweep fails open — a missing session id or sweep error never blocks session start.
+
 ### Planning delegate (v0.4.0 Delegate)
 
 When a **planning** turn would route primary inference to frontier while a warm **economical** session pin is active, smart-router prefers **cache-preserving delegation** ([#71](https://github.com/beettlle/pi-smart-router/issues/71)):
@@ -570,6 +572,16 @@ Explain/telemetry expose `route_path` (`neural` \| `learned` \| `heuristic` \| `
 | `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 |
+| `fail_closed_on_missing_weights` | `false` | When `true`, missing/placeholder neural weights fail **closed**: the matcher throws before paying embedding cost and the pipeline routes through the degraded sandwich (`neural_misconfigured`) with the SP-251 reason codes on the decision. When `false` (default), routing stays fail-open — placeholder weights score with neutral defaults and the reason codes are advisory telemetry only |
+
+**Missing-weights reason codes (v0.21.0, [#148](https://github.com/beettlle/pi-smart-router/issues/148)).** When the HyDRA matcher cannot load real neural weights, the decision surfaces structured reason codes (`src/domain/matching/missing-weights-reason-codes.ts`) on the routing decision / `requirement_reason_codes` — visible in explain (`pi router explain` / `POST /v1/route/explain`), `/smart-router history`, and telemetry — not stderr-only:
+
+| Reason code | Meaning | Operator action |
+|-------------|---------|-----------------|
+| `hydra_weights_missing` | HyDRA projection-head weights artifact is absent or unloadable, so neural scoring is running on fallback behavior | Restore the weights artifact (see [HyDRA model cache](#hydra-model-cache)); routing continues fail-open unless `fail_closed_on_missing_weights` is set |
+| `k4_heads_placeholder` | ModernBERT K4 heads are placeholder (untrained) weights — scores are neutral defaults, not learned predictions | Regenerate/install the trained K4 heads artifact; treat current K4 scores as non-authoritative |
+
+With the default fail-open behavior these codes are advisory: the route proceeds with safe defaults. Set `degraded_route.fail_closed_on_missing_weights: true` when you prefer an explicit degraded-route decision (sandwich chain above, `route_path` records the branch taken) over silently routing on placeholder neural scores.
 
 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).
 
@@ -764,6 +776,12 @@ npx pi-smart-router export telemetry-contrib [--limit N]
 
 This writes schema-valid JSON to `.pi-smart-router/exports/telemetry-contrib-<timestamp>.json`. Each row conforms to [`telemetry-contrib.schema.json`](specs/001-build-smart-router/contracts/telemetry-contrib.schema.json).
 
+**Export schema v2 — session-hash migration (v0.21.0, [#146](https://github.com/beettlle/pi-smart-router/issues/146)).** The contrib export schema was bumped **v1 → v2** (`TELEMETRY_CONTRIB_VERSION = 2` in `src/cli/smart-router-cli.ts`). In v1, `session_id_hash` was an **unsalted SHA-256** of the raw session id; in v2 it is an **HMAC-SHA256 keyed with an install-local pepper** (`hashSessionIdForTelemetryExport` in `src/infra/telemetry.ts`). The pepper is generated once per install at `.pi-smart-router/.dataset-key` (mode 0600) and is **never** included in export payloads — ingest strips pepper fields before aggregation. Consequences for operators comparing exports:
+
+- Hashes are **stable per install** (same session → same hash within one install/cwd) but **not correlatable across installs** — two machines routing the same prompt produce different hashes.
+- **v1 hashes are not comparable with v2 hashes.** If you maintain baselines that join or diff older v1 contrib exports, **re-baseline** on v2 output — do not mix rows across the version boundary.
+- Raw `session_id` / `request_id` values never appear in the JSONL in either version.
+
 **How to contribute**
 
 1. Opt in to dataset capture (`SMART_ROUTER_DATASET=1`) and dogfood with `/model smart-router/auto` for several sessions.
@@ -954,6 +972,32 @@ npm run benchmark:encoder
 
 The script reports p50/p95 latency for each encoder and asserts Granite p50/p95 stay within the 120 ms budget ceiling. Requires `@huggingface/transformers` and a one-time ONNX artifact download.
 
+#### Supply-chain: artifact pins, offline cache, and audit posture
+
+**Digest pinning (SP-259, [#147](https://github.com/beettlle/pi-smart-router/issues/147)).** The embedder verifies cached ONNX artifacts against SHA-256 pins before they are used. Pins live in [`config/onnx-artifact-pins.json`](config/onnx-artifact-pins.json) (`pins[modelId][cacheRelativePath] = sha256`; digests are the HuggingFace LFS oids for the default quantized artifacts). Pin mode is controlled by `SMART_ROUTER_ONNX_PIN_MODE`:
+
+| Mode | Behavior |
+|------|----------|
+| `off` (default) | No verification — first run downloads unpinned (local dogfood preserved). |
+| `verify` | Configured pins are verified after load; models without pins still download unpinned. |
+| `enforce` | CI/prod: pins are **required** for the loaded model — missing pin file, missing pins for the model, missing cached artifact, or any digest mismatch all fail closed. |
+
+Override the pin file location with `SMART_ROUTER_ONNX_PIN_FILE`. Verification runs **after** the transformers.js pipeline loads but **before** the embedder is returned, so even a first-run anonymous download is checked against configured pins — tampered or unexpected bytes fail closed and the session is never usable. Anonymous fetch does not silently bypass pins when they are configured. When upgrading model revisions, re-fetch digests from the HuggingFace API out-of-band and update the pin file; never pin a digest you have not verified.
+
+**Offline / air-gapped cache warm.** The artifact cache (`hydra.artifact_cache_path`, default `.pi-smart-router/models/`) is fully self-contained once warmed:
+
+1. On a networked host, warm the cache with the encoder you deploy — run any routed request, or `npm run benchmark:encoder -- --cache .pi-smart-router/models/`.
+2. Enable pin mode (`verify` or `enforce`) during the warm so digest mismatches surface on the networked host, before rollout.
+3. Copy the cache directory (and `config/onnx-artifact-pins.json` when pinning) to the offline host and point `hydra.artifact_cache_path` at the copy.
+4. Defense in depth: embedders can set `env.allowRemoteModels = false` (from `@huggingface/transformers`) before routing to forbid any network fetch, so no anonymous download path exists in production.
+
+**`npm audit` posture for the transformers chain.** The audit baseline includes high-severity advisories in `@huggingface/transformers` → `onnxruntime-node` → `adm-zip` ([GHSA-xcpc-8h2w-3j85](https://github.com/advisories/GHSA-xcpc-8h2w-3j85) — crafted ZIP triggers a 4GB memory allocation) and `sharp` (libvips CVEs), both **with no upstream fix available**. Accepted-risk rationale:
+
+- Model bytes in the pinned production path come only from the operator-controlled local cache, verified by SHA-256 — the vulnerable archive-decompression path is not exposed to untrusted input there.
+- Inference runs locally with no gradients and no untrusted deserialization; untrusted bytes enter only on first cache warm, over TLS from the HuggingFace hub, and (with pin mode on) are digest-checked before use.
+
+**Monitoring policy:** run `npm audit` at each release and record the baseline. A *new* high-severity advisory in the transformers/onnxruntime chain requires a documented exception with rationale (release notes or a linked issue) — never silently dismiss; exceptions without rationale are release blockers.
+
 ## Architecture
 
 ### Three execution tiers
@@ -1084,7 +1128,7 @@ Contributors must run `npm run build` before publishing or consuming the library
 | `npm run verify:ci` | Full CI parity: build, typecheck, lint, test, coverage (baseline PR gate; see [PR and pre-release quality gate set](#pr-and-pre-release-quality-gate-set)) |
 | `npm run typecheck` | TypeScript strict mode check (`tsc --noEmit`) |
 | `npm test` | Run test suite (`vitest run`) |
-| `npm run coverage:check` | Tests with line-coverage thresholds |
+| `npm run coverage:check` | Tests with line-coverage thresholds (src + extension, 80% floor — see [docs/extension-package-boundary.md](docs/extension-package-boundary.md#extension-coverage-gate-144)) |
 | `npm run lint` | ESLint + fleet catalog validation |
 | `npm run routing:bootstrap-centroids` | Regenerate `config/routing-centroids.json` from cluster catalog |
 | `npm run routing:calibration-aggregate` | Aggregate community telemetry for calibration |