pi-smart-router 0.2.0 → 0.4.0

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

@@ -94,6 +94,15 @@ export {
   initHydraMatcher,
   wireSmartRouterExtension,
 };
+export {
+  buildCompressedDelegateContext,
+  defaultSpawnPlanningDelegate,
+  extractAssistantText,
+  injectPlanningDelegateObservation,
+  isPlanningDelegateActive,
+  PLANNING_DELEGATE_OBSERVATION_PREFIX,
+  resolvePlanningDelegatePath,
+} from './planning-delegate.js';
 export { SMART_ROUTER_FULL_INVOCATIONS, SMART_ROUTER_USAGE } from './commands.js';
 export { routeAndDelegate } from './route-and-delegate.js';
 export {

package/.pi/extensions/smart-router/pi-model-scope.ts

@@ -1,4 +1,7 @@
-import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -15,41 +18,145 @@ type ResolveModelScopeFn = (
   modelRegistry: ModelRegistry,
 ) => Promise<ScopedModel[]>;
 
-function findPiCodingAgentDir(): string {
+const PI_CODING_AGENT_PKG = '@earendil-works/pi-coding-agent';
+const MODEL_RESOLVER_REL = 'dist/core/model-resolver.js';
+const INSTALL_HINT =
+  'Install @earendil-works/pi-coding-agent where pi can resolve it ' +
+  '(e.g. cd ~/.pi/agent/npm && npm install @earendil-works/pi-coding-agent).';
+
+function hasModelResolver(pkgDir: string): boolean {
+  return existsSync(join(pkgDir, MODEL_RESOLVER_REL));
+}
+
+function collectAncestorPackageDirs(startDir: string, maxDepth = 12): string[] {
   const candidates: string[] = [];
-  const roots = [dirname(fileURLToPath(import.meta.url)), process.cwd()];
-
-  for (const start of roots) {
-    let dir = start;
-    for (let i = 0; i < 12; i++) {
-      candidates.push(join(dir, 'node_modules/@earendil-works/pi-coding-agent'));
-      const parent = dirname(dir);
-      if (parent === dir) {
-        break;
+  let dir = startDir;
+  for (let i = 0; i < maxDepth; i++) {
+    candidates.push(join(dir, 'node_modules', PI_CODING_AGENT_PKG));
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return candidates;
+}
+
+function resolvePiBinaryPackageDirs(): string[] {
+  try {
+    const piBin = execSync('which pi', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!piBin) {
+      return [];
+    }
+    return collectAncestorPackageDirs(dirname(realpathSync(piBin)), 8);
+  } catch {
+    return [];
+  }
+}
+
+function resolveViaModuleResolution(): string | undefined {
+  const attempts: Array<() => string> = [
+    () => fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PKG)),
+    () => createRequire(import.meta.url).resolve(`${PI_CODING_AGENT_PKG}/package.json`),
+    () => createRequire(import.meta.url).resolve(`${PI_CODING_AGENT_PKG}/${MODEL_RESOLVER_REL}`),
+  ];
+
+  for (const attempt of attempts) {
+    try {
+      const resolvedPath = attempt();
+      const marker = `node_modules/${PI_CODING_AGENT_PKG}`;
+      const markerIndex = resolvedPath.lastIndexOf(marker);
+      if (markerIndex === -1) {
+        continue;
       }
-      dir = parent;
+      const pkgDir = resolvedPath.slice(0, markerIndex + marker.length);
+      if (hasModelResolver(pkgDir)) {
+        return pkgDir;
+      }
+    } catch {
+      // Try the next resolution strategy.
+    }
+  }
+
+  return undefined;
+}
+
+/** Locate pi-coding-agent on disk for the resolveModelScope shim. */
+export function findPiCodingAgentDir(): string {
+  const seen = new Set<string>();
+  const candidates: string[] = [];
+
+  const addCandidate = (candidate: string): void => {
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      candidates.push(candidate);
     }
+  };
+
+  const viaModuleResolution = resolveViaModuleResolution();
+  if (viaModuleResolution) {
+    addCandidate(viaModuleResolution);
+  }
+
+  for (const start of [dirname(fileURLToPath(import.meta.url)), process.cwd()]) {
+    for (const candidate of collectAncestorPackageDirs(start)) {
+      addCandidate(candidate);
+    }
+  }
+
+  addCandidate(join(homedir(), '.pi/agent/npm/node_modules', PI_CODING_AGENT_PKG));
+
+  if (process.env.HOMEBREW_PREFIX) {
+    addCandidate(join(process.env.HOMEBREW_PREFIX, 'lib/node_modules', PI_CODING_AGENT_PKG));
+  }
+
+  for (const candidate of resolvePiBinaryPackageDirs()) {
+    addCandidate(candidate);
   }
 
   for (const candidate of candidates) {
-    if (existsSync(join(candidate, 'dist/core/model-resolver.js'))) {
+    if (hasModelResolver(candidate)) {
       return candidate;
     }
   }
 
-  throw new Error('Unable to locate @earendil-works/pi-coding-agent for resolveModelScope');
+  throw new Error(
+    `Unable to locate ${PI_CODING_AGENT_PKG} for resolveModelScope. ${INSTALL_HINT}`,
+  );
 }
 
-const piPkgDir = findPiCodingAgentDir();
-const modelResolver = await import(
-  pathToFileURL(join(piPkgDir, 'dist/core/model-resolver.js')).href
-);
-const piResolveModelScope = modelResolver.resolveModelScope as ResolveModelScopeFn;
+async function loadResolveModelScopeFn(): Promise<ResolveModelScopeFn> {
+  try {
+    const pkg = await import('@earendil-works/pi-coding-agent');
+    const publicResolve = (pkg as { resolveModelScope?: ResolveModelScopeFn }).resolveModelScope;
+    if (typeof publicResolve === 'function') {
+      return publicResolve;
+    }
+  } catch {
+    // Fall back to filesystem discovery when the public export is unavailable.
+  }
+
+  const piPkgDir = findPiCodingAgentDir();
+  const modelResolver = await import(
+    pathToFileURL(join(piPkgDir, MODEL_RESOLVER_REL)).href
+  );
+  return modelResolver.resolveModelScope as ResolveModelScopeFn;
+}
+
+let resolveModelScopeFnPromise: Promise<ResolveModelScopeFn> | undefined;
+
+function getResolveModelScopeFn(): Promise<ResolveModelScopeFn> {
+  resolveModelScopeFnPromise ??= loadResolveModelScopeFn();
+  return resolveModelScopeFnPromise;
+}
 
 /** Delegate to pi's resolveModelScope (not yet on the public package export surface). */
 export function resolveModelScope(
   patterns: string[],
   modelRegistry: ModelRegistry,
 ): Promise<ScopedModel[]> {
-  return piResolveModelScope(patterns, modelRegistry);
+  return getResolveModelScopeFn().then((fn) => fn(patterns, modelRegistry));
 }

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

@@ -0,0 +1,318 @@
+/**
+ * Cache-preserving planning delegate (SP-144, #71).
+ *
+ * When the pipeline emits `planning_delegate`, run an ephemeral frontier sub-call
+ * 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).
+ */
+
+import {
+  type Api,
+  type AssistantMessage,
+  type Context,
+  type Message,
+  type Model,
+  type SimpleStreamOptions,
+  type TextContent,
+} from '@earendil-works/pi-ai/compat';
+
+import type {
+  CompressedContextSpec,
+  PlanningDelegateObservability,
+  RoutingDecision,
+} from '../../../src/domain/types/index.js';
+import {
+  createPlanningDelegateObservability,
+  enrichRoutingDecisionWithPlanningDelegate,
+  PLANNING_DELEGATE,
+  PLANNING_DELEGATE_UNAVAILABLE,
+  PLANNING_DIRECT_FRONTIER,
+} from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+import { collectDelegatedStream } from './delegate-stream.js';
+import { findFleetProfile, resolveRegistryModel } from './delegation-runtime.js';
+import type { StreamDelegationDeps } from './types.js';
+
+/** Prefix for injected planning observations visible to the primary model. */
+export const PLANNING_DELEGATE_OBSERVATION_PREFIX =
+  '[smart-router planning delegate]' as const;
+
+export type PlanningDelegateSpawnResult =
+  | { readonly ok: true; readonly observationText: string }
+  | { readonly ok: false; readonly reason: string };
+
+/** Injectable sub-agent spawn hook (mocked in unit tests). */
+export type PlanningDelegateSpawnFn = (
+  frontierModel: Model<Api>,
+  compressedContext: Context,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+) => Promise<PlanningDelegateSpawnResult>;
+
+export function isPlanningDelegateActive(
+  decision: RoutingDecision,
+): decision is RoutingDecision & {
+  features: { planning_delegate: PlanningDelegateObservability };
+} {
+  const observability = decision.features?.planning_delegate;
+  return (
+    decision.reason_code === PLANNING_DELEGATE &&
+    observability?.path === 'delegate' &&
+    observability.delegate_model_id !== null
+  );
+}
+
+function isConversationalMessage(message: Message): boolean {
+  return message.role === 'user' || message.role === 'assistant';
+}
+
+function isExecutionTraceMessage(message: Message): boolean {
+  if (message.role === 'toolResult') {
+    return true;
+  }
+  if (message.role !== 'assistant') {
+    return false;
+  }
+  const blocks = message.content;
+  if (!Array.isArray(blocks) || blocks.length === 0) {
+    return false;
+  }
+  return blocks.every(
+    (block) => block.type === 'toolCall' || block.type === 'thinking',
+  );
+}
+
+function estimateContextTokens(context: Context): number {
+  let charCount = 0;
+  if (context.systemPrompt) {
+    charCount += context.systemPrompt.length;
+  }
+  for (const message of context.messages) {
+    if (typeof message.content === 'string') {
+      charCount += message.content.length;
+      continue;
+    }
+    for (const block of message.content) {
+      if (block.type === 'text') {
+        charCount += block.text.length;
+      } else if (block.type === 'thinking') {
+        charCount += block.thinking.length;
+      } else if (block.type === 'toolCall') {
+        charCount += JSON.stringify(block.arguments).length;
+      }
+    }
+  }
+  return Math.max(0, Math.ceil(charCount / 4));
+}
+
+/**
+ * Build compressed context for the ephemeral frontier sub-call (SP-142 limits).
+ * Excludes tool execution history when configured; caps message count and tokens.
+ */
+export function buildCompressedDelegateContext(
+  context: Context,
+  spec: CompressedContextSpec | null | undefined,
+): Context {
+  if (!spec) {
+    return context;
+  }
+
+  let messages = context.messages.filter(isConversationalMessage);
+  if (spec.exclude_execution_history) {
+    messages = messages.filter((message) => !isExecutionTraceMessage(message));
+  }
+
+  if (messages.length > spec.max_messages) {
+    messages = messages.slice(-spec.max_messages);
+  }
+
+  while (messages.length > 1 && estimateContextTokens({ ...context, messages }) > spec.max_tokens) {
+    messages = messages.slice(1);
+  }
+
+  return {
+    ...context,
+    messages,
+  };
+}
+
+export function extractAssistantText(message: AssistantMessage | undefined): string {
+  if (!message) {
+    return '';
+  }
+  return message.content
+    .filter((block): block is TextContent => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
+}
+
+/** Inject frontier sub-call output as a user observation for the primary model. */
+export function injectPlanningDelegateObservation(
+  context: Context,
+  observationText: string,
+): Context {
+  const trimmed = observationText.trim();
+  if (!trimmed) {
+    return context;
+  }
+
+  const observationMessage: Message = {
+    role: 'user',
+    content: `${PLANNING_DELEGATE_OBSERVATION_PREFIX}\n${trimmed}`,
+    timestamp: Date.now(),
+  };
+
+  return {
+    ...context,
+    messages: [...context.messages, observationMessage],
+  };
+}
+
+/** Default frontier sub-call via provider stream (ephemeral one-shot delegate). */
+export async function defaultSpawnPlanningDelegate(
+  frontierModel: Model<Api>,
+  compressedContext: Context,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+): Promise<PlanningDelegateSpawnResult> {
+  try {
+    const result = await collectDelegatedStream(
+      frontierModel,
+      compressedContext,
+      deps,
+      options,
+    );
+    if (result.failed || !result.finalMessage) {
+      return {
+        ok: false,
+        reason:
+          result.finalMessage?.errorMessage ??
+          'planning delegate sub-call failed',
+      };
+    }
+
+    const observationText = extractAssistantText(result.finalMessage);
+    if (!observationText) {
+      return {
+        ok: false,
+        reason: 'planning delegate sub-call returned empty response',
+      };
+    }
+
+    return { ok: true, observationText };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export interface PlanningDelegateResolution {
+  readonly context: Context;
+  readonly decision: RoutingDecision;
+  readonly targetModelId: string;
+  readonly usedDelegatePath: boolean;
+}
+
+/**
+ * Resolve planning delegate path: sub-call + observation injection, or direct frontier fallback.
+ */
+export async function resolvePlanningDelegatePath(
+  context: Context,
+  decision: RoutingDecision,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+): Promise<PlanningDelegateResolution> {
+  const observability = decision.features!.planning_delegate!;
+  const delegateModelId = observability.delegate_model_id!;
+  const primaryModelId = decision.selected_model_id;
+
+  const frontierProfile = findFleetProfile(deps.fleet, delegateModelId);
+  const frontierModel = frontierProfile
+    ? resolveRegistryModel(deps.modelRegistry, frontierProfile)
+    : undefined;
+
+  if (!frontierModel) {
+    console.warn(
+      '[smart-router] planning delegate unavailable: frontier model missing from registry',
+      delegateModelId,
+    );
+    return applyPlanningDelegateDirectFallback(
+      context,
+      decision,
+      delegateModelId,
+      PLANNING_DELEGATE_UNAVAILABLE,
+      deps,
+    );
+  }
+
+  const compressedContext = buildCompressedDelegateContext(
+    context,
+    observability.compressed_context,
+  );
+  const spawnFn = deps.spawnPlanningDelegate ?? defaultSpawnPlanningDelegate;
+  const spawnResult = await spawnFn(frontierModel, compressedContext, options, deps);
+
+  if (!spawnResult.ok) {
+    console.warn(
+      '[smart-router] planning delegate sub-call failed, falling back to direct frontier route',
+      spawnResult.reason,
+    );
+    return applyPlanningDelegateDirectFallback(
+      context,
+      decision,
+      delegateModelId,
+      PLANNING_DELEGATE_UNAVAILABLE,
+      deps,
+    );
+  }
+
+  console.warn(
+    '[smart-router] planning delegate sub-call completed',
+    JSON.stringify({
+      primary_model_id: primaryModelId,
+      delegate_model_id: delegateModelId,
+      observation_chars: spawnResult.observationText.length,
+    }),
+  );
+
+  return {
+    context: injectPlanningDelegateObservation(context, spawnResult.observationText),
+    decision,
+    targetModelId: primaryModelId,
+    usedDelegatePath: true,
+  };
+}
+
+function applyPlanningDelegateDirectFallback(
+  context: Context,
+  decision: RoutingDecision,
+  delegateModelId: string,
+  fallbackReason: string,
+  deps: StreamDelegationDeps,
+): PlanningDelegateResolution {
+  const profile = findFleetProfile(deps.fleet, delegateModelId);
+  const fallbackDecision = enrichRoutingDecisionWithPlanningDelegate(
+    {
+      ...decision,
+      selected_model_id: delegateModelId,
+      tier: profile?.tier ?? decision.tier,
+      reason_code: PLANNING_DIRECT_FRONTIER,
+    },
+    createPlanningDelegateObservability({
+      path: 'direct',
+      delegate_model_id: delegateModelId,
+      planning_delegate_reason_code: PLANNING_DIRECT_FRONTIER,
+      fallback_reason: fallbackReason,
+    }),
+  );
+
+  return {
+    context,
+    decision: fallbackDecision,
+    targetModelId: delegateModelId,
+    usedDelegatePath: false,
+  };
+}

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

@@ -34,6 +34,10 @@ import {
 } from './delegation-runtime.js';
 import { buildRoutingRequest } from './routing-context.js';
 import { capturePreRouteOutcomes, updateSessionRoutingSnapshot } from './routing-outcomes.js';
+import {
+  isPlanningDelegateActive,
+  resolvePlanningDelegatePath,
+} from './planning-delegate.js';
 import type { StreamDelegationDeps } from './types.js';
 
 function isRoutingLogEnabled(): boolean {
@@ -287,6 +291,22 @@ export async function routeAndDelegate(
   deps.datasetRecorder?.record(request, decision);
   updateSessionRoutingSnapshot(deps, sessionId, request, decision);
 
+  let delegationContext: Context = context;
+
+  if (isPlanningDelegateActive(decision)) {
+    const planningResolution = await resolvePlanningDelegatePath(
+      context,
+      decision,
+      options,
+      deps,
+    );
+    delegationContext = planningResolution.context;
+    decision = planningResolution.decision;
+    if (!planningResolution.usedDelegatePath) {
+      deps.onRoutingDecision?.(decision);
+    }
+  }
+
   let targetModel = resolveTargetModel(deps, decision);
   if (!targetModel) {
     console.warn(
@@ -374,7 +394,7 @@ export async function routeAndDelegate(
 
       const result = await delegateWithOutcome(
         targetModel,
-        context,
+        delegationContext,
         deps,
         options,
         sessionId,

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

@@ -15,6 +15,7 @@ import type {
   PriceCatalog,
   RoutingDecision,
 } 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,
@@ -56,6 +57,8 @@ export interface StreamDelegationDeps {
   readonly executionLedger: ExecutionLedger;
   /** Injectable for tests; production uses pi-ai streamSimple. */
   delegateStream?: DelegateStreamFn;
+  /** Injectable planning delegate sub-call; production uses frontier stream delegate. */
+  spawnPlanningDelegate?: PlanningDelegateSpawnFn;
   readonly lifecycleHookState?: LifecycleHookState;
   readonly datasetRecorder?: DatasetRecorder;
   readonly outcomeRecorder?: OutcomeRecorder;

package/README.md

@@ -344,6 +344,10 @@ Cluster IDs are stable reason-code prefixes (`cluster_low_stakes_general`, `clus
 | `SMART_ROUTER_DATASET_FINGERPRINT` | (unset) | Set to `1` (requires `SMART_ROUTER_DATASET=1`) to store an install-local HMAC-SHA256 fingerprint of each normalized prompt for duplicate detection within this install. The install pepper lives in `.pi-smart-router/.dataset-key` (gitignored) and is never exported. **Warning:** short or common prompts are vulnerable to offline rainbow-table guessing; use only when you accept that tradeoff. See [#10](https://github.com/beettlle/pi-smart-router/issues/10). |
 | `MODELS_YAML_PATH` | `./config/models.yaml` | Fleet catalog path (library API only) |
 | `SMART_ROUTER_PLANNING_TURN_BUFFER` | `2` | SAAR planning buffer: frontier planning turns allowed before hard-lock ([v0.2.0 Continuity](https://github.com/beettlle/pi-smart-router/issues/72)) |
+| `SMART_ROUTER_PLANNING_DELEGATE_ENABLED` | `true` | Enable cache-preserving planning delegate ([#71](https://github.com/beettlle/pi-smart-router/issues/71)) |
+| `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_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 |
@@ -371,6 +375,34 @@ 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.
 
+### 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)):
+
+1. **Pipeline** (`turn_envelope`) emits `planning_delegate` — primary stays on the pinned economical model; `features.planning_delegate` names the frontier **delegate** model and compressed-context limits.
+2. **Pi extension** (`.pi/extensions/smart-router`) runs an ephemeral frontier sub-call with compressed context (tool execution history excluded by default), injects the result as an observation user message, then delegates **primary** streaming to the pinned economical model.
+3. **Fallback** — when delegate is disabled, spawn fails, or the delegate model is missing from the registry, the extension falls back to a **direct frontier** route with a documented `fallback_reason` in explain/telemetry.
+
+| Knob | Env var | Default | Effect |
+|------|---------|---------|--------|
+| Delegate enabled | `SMART_ROUTER_PLANNING_DELEGATE_ENABLED` | `true` | When `false`, SAAR buffer allows direct frontier planning (`planning_direct_frontier` + `planning_delegate_disabled`) |
+| Compressed message cap | `SMART_ROUTER_PLANNING_DELEGATE_MAX_MESSAGES` | `12` | Max messages sent to the frontier sub-call |
+| Compressed token cap | `SMART_ROUTER_PLANNING_DELEGATE_MAX_TOKENS` | `16384` | Token budget for compressed delegate context |
+| Exclude tool history | `SMART_ROUTER_PLANNING_DELEGATE_EXCLUDE_EXECUTION_HISTORY` | `true` | Strip tool-call / tool-result turns from delegate payload |
+
+**Coordination boundary with pi core:** smart-router owns **routing** (when to delegate, which models, compressed limits, fallback reason codes). **Sub-agent spawn and observation injection** run in the pi extension via `streamSimple` — pi core must expose a delegate/stream API the extension can call; smart-router does not orchestrate pi's outer sub-agent scheduler. Operators enabling `/model smart-router/auto` get delegate behavior automatically when the extension is loaded; no separate pi sub-agent config is required beyond a frontier model in the registry.
+
+**Dogfood verification (planning delegate)**
+
+1. Start pi with routing logs: `SMART_ROUTER_LOG_ROUTING=1 pi` and `/model smart-router/auto`.
+2. Begin a session on an economical pin (routine prompts), then trigger planning turns (e.g. architecture or multi-step design work).
+3. Inspect stderr JSON — on delegate turns expect `reason_code: planning_delegate`, `planning_delegate_summary.path: "delegate"`, `primary_model_id` equal to the pin, and `delegate_model_id` pointing at frontier.
+4. Confirm primary inference stays on the economical model (cache-friendly) while stderr shows `[smart-router] planning delegate sub-call completed` with the frontier model id.
+5. Disable delegate (`SMART_ROUTER_PLANNING_DELEGATE_ENABLED=false`) and repeat — expect `planning_direct_frontier` with `fallback_reason: planning_delegate_disabled`.
+6. Use `pi router explain` (or `POST /v1/route/explain`) on the same session — `features.planning_delegate` mirrors live routing (`path: delegate` vs `direct`, `fallback_reason` when applicable).
+
+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.
+
 ### P(success) training export (baseline classifier)
 
 When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and behavioral outcome labels (model override, compaction pin break, `/smart-router feedback good|bad`). Export labeled training data from pi:
@@ -565,6 +597,25 @@ Contributors must run `npm run build` before publishing or consuming the library
 | `npm run routing:calibration-aggregate` | Aggregate community telemetry for calibration |
 | `npm run routing:train-calibration` | Train routing calibration artifact bundle |
 | `npm run routing:verify-calibration` | Verify calibration bundle against benchmark prompts |
+| `npm run routing:ingest-benchmarks` | Regenerate `config/benchmark-profiles.json` from leaderboard fixtures |
+| `npm run routing:verify-benchmark-profiles` | CI smoke: assert checked-in profiles match fixture ingest |
+
+### Benchmark profile refresh
+
+Capability scores in `config/benchmark-profiles.json` are grounded from public leaderboard snapshots under `tests/fixtures/benchmark-leaderboards/`. Each artifact records provenance (`source_urls`, `scrape_date`, `catalog_freeze_date`) in its header.
+
+**Operator policy:**
+
+1. **PR smoke** — `.github/workflows/benchmark-profile-refresh.yml` runs on PRs that touch fixtures, ingest, or the checked-in artifact. It executes `npm run routing:verify-benchmark-profiles` so fixture edits cannot drift from `config/benchmark-profiles.json`.
+2. **Monthly refresh** — the same workflow runs on the 1st of each month (06:00 UTC) and via `workflow_dispatch`. It re-ingests fixtures, updates `catalog_freeze_date` to the run date, and opens a PR when model scores change.
+3. **Manual updates** — after editing fixture snapshots, run `npm run routing:ingest-benchmarks` (optionally `--catalog-freeze-date YYYY-MM-DD`) and commit the regenerated `config/benchmark-profiles.json` with the PR.
+
+Regenerate locally:
+
+```bash
+npm run routing:ingest-benchmarks
+npm run routing:verify-benchmark-profiles
+```
 
 ### Releasing