@fiale-plus/pi-rogue 0.2.1 → 0.2.3

package/node_modules/@fiale-plus/pi-rogue-router/src/learning.ts

@@ -0,0 +1,382 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { decideRoute, readCheckpointJsonl } from "./decision.js";
+import { hashText } from "./hash.js";
+import { readRouteEvents, type RouteEvent } from "./ledger.js";
+import { readOutcomes, type RouterOutcome } from "./outcomes.js";
+import type { RouteAction, RouteDecision, RouterCheckpoint } from "./types.js";
+
+export const MODEL_CAPABILITY_CARD_SCHEMA = "pi-router.model-capability-card.v1" as const;
+export const TEACHER_LABEL_SCHEMA = "pi-router.teacher-label.v1" as const;
+export const SHADOW_EVAL_SCHEMA = "pi-router.shadow-eval.v1" as const;
+
+export interface ModelCapabilityCard {
+  schema: typeof MODEL_CAPABILITY_CARD_SCHEMA;
+  modelId: string;
+  provider?: string;
+  generatedAt: string;
+  seed: {
+    source: "none" | "manual" | "public" | "default";
+    purpose: string;
+  };
+  observed: {
+    source: "local Pi telemetry";
+    events: number;
+    sessions: number;
+    actions: Record<string, number>;
+    averageLoopScore: number;
+    averageProgressScore: number;
+    averageContextTokensApprox: number | null;
+    outcomes: {
+      linked: number;
+      success: number;
+      partial: number;
+      failed: number;
+      abandoned: number;
+      unknown: number;
+      averageReworkTurns: number | null;
+    };
+  };
+  promotion: {
+    manualOnly: true;
+    promoted: false;
+  };
+}
+
+export interface TeacherLabel {
+  schema: typeof TEACHER_LABEL_SCHEMA;
+  labelId: string;
+  generatedAt: string;
+  teacher: string;
+  checkpointId: string;
+  sessionId: string;
+  rawSessionRef: RouterCheckpoint["rawSessionRef"];
+  suggestedAction: RouteAction;
+  confidence: number;
+  rationale: string;
+  source: "local-rule" | "teacher-output";
+}
+
+export interface TeacherPromptRequest {
+  schema: "pi-router.teacher-prompt.v1";
+  requestId: string;
+  teacher: string;
+  checkpointId: string;
+  sessionId: string;
+  rawSessionRef: RouterCheckpoint["rawSessionRef"];
+  allowedActions: RouteAction[];
+  instruction: string;
+  features: Pick<RouterCheckpoint, "phase" | "activeModel" | "provider"> & {
+    loopScore: number;
+    progressScore: number;
+    sameCommandRepeatedCount: number;
+    sameErrorRepeatedCount: number;
+    verifierUsed: boolean;
+    noVerifierUsed: boolean;
+    diffLines: number;
+    diffFilesChanged: number;
+  };
+}
+
+export interface ReflectionResult {
+  labels: TeacherLabel[];
+  markdown: string;
+}
+
+export interface ShadowEvalReport {
+  schema: typeof SHADOW_EVAL_SCHEMA;
+  generatedAt: string;
+  policyVersion: string;
+  checkpoints: number;
+  comparedEvents: number;
+  actionCounts: Record<string, number>;
+  ledgerActionCounts: Record<string, number>;
+  divergences: number;
+  divergenceRate: number;
+  likelySavingsSignals: {
+    summarizeContext: number;
+    runVerifier: number;
+    continueCurrent: number;
+  };
+  manualPromotionRequired: true;
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3));
+}
+
+function increment(map: Record<string, number>, key: string): void {
+  map[key] = (map[key] ?? 0) + 1;
+}
+
+function writeJsonl(path: string, rows: unknown[]): void {
+  const resolved = resolve(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, rows.map((row) => JSON.stringify(row)).join("\n") + (rows.length ? "\n" : ""));
+}
+
+function emptyOutcomeCounts(): ModelCapabilityCard["observed"]["outcomes"] {
+  return { linked: 0, success: 0, partial: 0, failed: 0, abandoned: 0, unknown: 0, averageReworkTurns: null };
+}
+
+function summarizeOutcomes(group: RouteEvent[], outcomes: RouterOutcome[]): ModelCapabilityCard["observed"]["outcomes"] {
+  const byRouteEvent = new Map(outcomes.flatMap((outcome) => outcome.routeEventId ? [[outcome.routeEventId, outcome] as const] : []));
+  const byCheckpoint = new Map(outcomes.flatMap((outcome) => outcome.checkpointId && !outcome.routeEventId ? [[outcome.checkpointId, outcome] as const] : []));
+  const linked = group.flatMap((event) => {
+    const outcome = byRouteEvent.get(event.eventId) ?? byCheckpoint.get(event.checkpointId);
+    return outcome ? [outcome] : [];
+  });
+  if (linked.length === 0) return emptyOutcomeCounts();
+  const counts = emptyOutcomeCounts();
+  counts.linked = linked.length;
+  for (const outcome of linked) counts[outcome.taskStatus]++;
+  const reworkValues = linked.map((outcome) => outcome.reworkTurns).filter((value): value is number => Number.isFinite(value));
+  counts.averageReworkTurns = reworkValues.length ? round(reworkValues.reduce((sum, value) => sum + value, 0) / reworkValues.length) : null;
+  return counts;
+}
+
+export function generateCapabilityCards(events: RouteEvent[], generatedAt = new Date().toISOString(), outcomes: RouterOutcome[] = []): ModelCapabilityCard[] {
+  const groups = new Map<string, RouteEvent[]>();
+  for (const event of events) {
+    const modelId = event.runtime.activeModel ?? "unknown";
+    const provider = event.runtime.provider ?? "unknown";
+    const key = `${provider}\0${modelId}`;
+    groups.set(key, [...(groups.get(key) ?? []), event]);
+  }
+
+  return [...groups.entries()].map(([key, group]) => {
+    const [provider, modelId] = key.split("\0");
+    const actions: Record<string, number> = {};
+    const sessions = new Set(group.map((event) => event.sessionId));
+    const contextValues = group
+      .map((event) => event.runtime.contextTokensApprox)
+      .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+    for (const event of group) increment(actions, event.decision.action);
+    return {
+      schema: MODEL_CAPABILITY_CARD_SCHEMA,
+      modelId,
+      provider,
+      generatedAt,
+      seed: {
+        source: "none",
+        purpose: "cold-start priors are intentionally absent in v0; local observations dominate",
+      },
+      observed: {
+        source: "local Pi telemetry",
+        events: group.length,
+        sessions: sessions.size,
+        actions,
+        averageLoopScore: round(group.reduce((sum, event) => sum + event.metrics.loopScore, 0) / group.length),
+        averageProgressScore: round(group.reduce((sum, event) => sum + event.metrics.progressScore, 0) / group.length),
+        averageContextTokensApprox: contextValues.length
+          ? round(contextValues.reduce((sum, value) => sum + value, 0) / contextValues.length)
+          : null,
+        outcomes: summarizeOutcomes(group, outcomes),
+      },
+      promotion: {
+        manualOnly: true,
+        promoted: false,
+      },
+    } satisfies ModelCapabilityCard;
+  }).sort((a, b) => `${a.provider}/${a.modelId}`.localeCompare(`${b.provider}/${b.modelId}`));
+}
+
+function readRequiredRouteEvents(path: string): RouteEvent[] {
+  if (!existsSync(resolve(path))) throw new Error(`required route events file not found: ${path}`);
+  return readRouteEvents(path);
+}
+
+export function writeCapabilityCards(eventsPath: string, outputPath: string, outcomesPath?: string): ModelCapabilityCard[] {
+  const cards = generateCapabilityCards(readRequiredRouteEvents(eventsPath), new Date().toISOString(), readOutcomes(outcomesPath));
+  writeJsonl(outputPath, cards);
+  return cards;
+}
+
+function labelFromDecision(
+  checkpoint: RouterCheckpoint,
+  decision: RouteDecision,
+  teacher: string,
+  source: TeacherLabel["source"],
+  generatedAt: string,
+): TeacherLabel {
+  return {
+    schema: TEACHER_LABEL_SCHEMA,
+    labelId: hashText(teacher, checkpoint.checkpointId, decision.action, checkpoint.rawSessionRef.contentHash),
+    generatedAt,
+    teacher,
+    checkpointId: checkpoint.checkpointId,
+    sessionId: checkpoint.sessionId,
+    rawSessionRef: checkpoint.rawSessionRef,
+    suggestedAction: decision.action,
+    confidence: decision.confidence,
+    rationale: decision.reason,
+    source,
+  };
+}
+
+export function readTeacherLabels(path: string): TeacherLabel[] {
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as TeacherLabel);
+}
+
+function importedTeacherDecisions(path: string): Map<string, RouteDecision> {
+  const map = new Map<string, RouteDecision>();
+  if (!path) return map;
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    const decision = JSON.parse(line) as RouteDecision;
+    map.set(decision.checkpointId, decision);
+  }
+  return map;
+}
+
+export function generateTeacherReflection(
+  checkpoints: RouterCheckpoint[],
+  options: { teacher: string; teacherOutputPath?: string; generatedAt?: string } = { teacher: "local-rule" },
+): ReflectionResult {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  if (options.teacher !== "local-rule" && !options.teacherOutputPath) {
+    throw new Error("non-local teacher reflection requires --teacher-output decisions JSONL in local-only v0");
+  }
+  const imported = options.teacherOutputPath ? importedTeacherDecisions(options.teacherOutputPath) : new Map<string, RouteDecision>();
+  const labels = checkpoints.map((checkpoint) => {
+    const importedDecision = imported.get(checkpoint.checkpointId);
+    if (options.teacher !== "local-rule" && !importedDecision) {
+      throw new Error(`teacher output missing decision for checkpoint: ${checkpoint.checkpointId}`);
+    }
+    const decision = importedDecision ?? decideRoute(checkpoint, { policyVersion: options.teacher });
+    const source: TeacherLabel["source"] = importedDecision ? "teacher-output" : "local-rule";
+    return labelFromDecision(checkpoint, decision, options.teacher, source, generatedAt);
+  });
+  const actionCounts: Record<string, number> = {};
+  for (const label of labels) increment(actionCounts, label.suggestedAction);
+  const markdown = [
+    `# Pi router teacher reflection`,
+    ``,
+    `- generatedAt: ${generatedAt}`,
+    `- teacher: ${options.teacher}`,
+    `- labels: ${labels.length}`,
+    `- source: ${options.teacherOutputPath ? "imported teacher output" : "local rule teacher"}`,
+    ``,
+    `## Suggested action counts`,
+    ``,
+    ...Object.entries(actionCounts).sort().map(([action, count]) => `- ${action}: ${count}`),
+    ``,
+    `Manual promotion only: these labels do not mutate router policy.`,
+  ].join("\n");
+  return { labels, markdown };
+}
+
+export function generateTeacherPromptRequests(checkpoints: RouterCheckpoint[], teacher: string): TeacherPromptRequest[] {
+  const allowedActions: RouteAction[] = [
+    "continue_current",
+    "continue_local",
+    "summarize_context",
+    "run_verifier",
+    "ask_micro_hint",
+    "escalate_plan_critique",
+    "escalate_debug_diagnosis",
+    "escalate_diff_review",
+    "delegate_full_step",
+    "spawn_subagent",
+    "stop_and_ask_user",
+  ];
+  return checkpoints.map((checkpoint) => ({
+    schema: "pi-router.teacher-prompt.v1",
+    requestId: hashText("teacher-request", teacher, checkpoint.checkpointId, checkpoint.rawSessionRef.contentHash),
+    teacher,
+    checkpointId: checkpoint.checkpointId,
+    sessionId: checkpoint.sessionId,
+    rawSessionRef: checkpoint.rawSessionRef,
+    allowedActions,
+    instruction: "Inspect the raw session span by pointer if needed. Return one pi-router.decision.v1 JSON object with checkpointId, action, adviceShape, contextPolicy, confidence, reason, and policyVersion. Prefer intervention only when it likely improves trajectory outcome; do not mutate policy.",
+    features: {
+      phase: checkpoint.phase,
+      activeModel: checkpoint.activeModel,
+      provider: checkpoint.provider,
+      loopScore: checkpoint.features.loopScore,
+      progressScore: checkpoint.features.progressScore,
+      sameCommandRepeatedCount: checkpoint.features.sameCommandRepeatedCount,
+      sameErrorRepeatedCount: checkpoint.features.sameErrorRepeatedCount,
+      verifierUsed: checkpoint.features.verifierUsed,
+      noVerifierUsed: checkpoint.features.noVerifierUsed,
+      diffLines: checkpoint.features.diffLines,
+      diffFilesChanged: checkpoint.features.diffFilesChanged,
+    },
+  }));
+}
+
+export function writeTeacherPromptRequests(checkpointPath: string, outputPath: string, teacher: string): TeacherPromptRequest[] {
+  const requests = generateTeacherPromptRequests(readCheckpointJsonl(checkpointPath), teacher);
+  writeJsonl(outputPath, requests);
+  return requests;
+}
+
+export function writeTeacherReflection(options: {
+  checkpointPath: string;
+  labelsPath: string;
+  reflectionPath: string;
+  teacher: string;
+  teacherOutputPath?: string;
+  teacherPromptPath?: string;
+}): ReflectionResult {
+  const checkpoints = readCheckpointJsonl(options.checkpointPath);
+  if (options.teacherPromptPath) writeJsonl(options.teacherPromptPath, generateTeacherPromptRequests(checkpoints, options.teacher));
+  const reflection = generateTeacherReflection(checkpoints, {
+    teacher: options.teacher,
+    teacherOutputPath: options.teacherOutputPath,
+  });
+  writeJsonl(options.labelsPath, reflection.labels);
+  const resolved = resolve(options.reflectionPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${reflection.markdown}\n`);
+  return reflection;
+}
+
+export function shadowEvaluate(checkpoints: RouterCheckpoint[], ledgerEvents: RouteEvent[] = [], generatedAt = new Date().toISOString()): ShadowEvalReport {
+  const ledgerByCheckpoint = new Map(ledgerEvents.map((event) => [event.checkpointId, event]));
+  const actionCounts: Record<string, number> = {};
+  const ledgerActionCounts: Record<string, number> = {};
+  let comparedEvents = 0;
+  let divergences = 0;
+  let summarizeContext = 0;
+  let runVerifier = 0;
+  let continueCurrent = 0;
+
+  for (const checkpoint of checkpoints) {
+    const decision = decideRoute(checkpoint);
+    increment(actionCounts, decision.action);
+    if (decision.action === "summarize_context") summarizeContext++;
+    if (decision.action === "run_verifier") runVerifier++;
+    if (decision.action === "continue_current") continueCurrent++;
+    const actual = ledgerByCheckpoint.get(checkpoint.checkpointId);
+    if (!actual) continue;
+    comparedEvents++;
+    increment(ledgerActionCounts, actual.decision.action);
+    if (actual.decision.action !== decision.action) divergences++;
+  }
+
+  return {
+    schema: SHADOW_EVAL_SCHEMA,
+    generatedAt,
+    policyVersion: checkpoints[0] ? decideRoute(checkpoints[0]).policyVersion : "pi-router.rule-policy.v0",
+    checkpoints: checkpoints.length,
+    comparedEvents,
+    actionCounts,
+    ledgerActionCounts,
+    divergences,
+    divergenceRate: comparedEvents ? round(divergences / comparedEvents) : 0,
+    likelySavingsSignals: { summarizeContext, runVerifier, continueCurrent },
+    manualPromotionRequired: true,
+  };
+}
+
+export function writeShadowEval(checkpointPath: string, outputPath: string, ledgerPath?: string): ShadowEvalReport {
+  const report = shadowEvaluate(readCheckpointJsonl(checkpointPath), ledgerPath ? readRequiredRouteEvents(ledgerPath) : []);
+  const resolved = resolve(outputPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${JSON.stringify(report, null, 2)}\n`);
+  return report;
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/ledger.ts

@@ -0,0 +1,94 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { decisionId } from "./decision.js";
+import type { RouteDecision, RouterCheckpoint } from "./types.js";
+
+export const ROUTE_EVENT_SCHEMA = "pi-router.route-event.v1" as const;
+
+export interface RouteRuntimeFacts {
+  activeModel?: string;
+  provider?: string;
+  contextTokensApprox: number | null;
+  gitDirty: boolean | null;
+}
+
+export interface RouteEvent {
+  schema: typeof ROUTE_EVENT_SCHEMA;
+  eventId: string;
+  recordedAt: string;
+  checkpointId: string;
+  sessionId: string;
+  rawSessionRef: RouterCheckpoint["rawSessionRef"];
+  sourceEvent: RouterCheckpoint["sourceEvent"];
+  decision: RouteDecision;
+  runtime: RouteRuntimeFacts;
+  observed: {
+    followed: boolean | null;
+    overriddenBy?: string;
+  };
+  metrics: {
+    loopScore: number;
+    progressScore: number;
+    sameCommandRepeatedCount: number;
+    sameErrorRepeatedCount: number;
+    verifierUsed: boolean;
+    diffLines: number;
+    diffFilesChanged: number;
+  };
+}
+
+export function buildRouteEvent(checkpoint: RouterCheckpoint, decision: RouteDecision, recordedAt = new Date().toISOString()): RouteEvent {
+  return {
+    schema: ROUTE_EVENT_SCHEMA,
+    eventId: decisionId(decision, checkpoint),
+    recordedAt,
+    checkpointId: checkpoint.checkpointId,
+    sessionId: checkpoint.sessionId,
+    rawSessionRef: checkpoint.rawSessionRef,
+    sourceEvent: checkpoint.sourceEvent,
+    decision,
+    runtime: {
+      activeModel: checkpoint.activeModel,
+      provider: checkpoint.provider,
+      contextTokensApprox: checkpoint.features.contextTokensApprox,
+      gitDirty: checkpoint.features.gitDirty,
+    },
+    observed: {
+      followed: null,
+    },
+    metrics: {
+      loopScore: checkpoint.features.loopScore,
+      progressScore: checkpoint.features.progressScore,
+      sameCommandRepeatedCount: checkpoint.features.sameCommandRepeatedCount,
+      sameErrorRepeatedCount: checkpoint.features.sameErrorRepeatedCount,
+      verifierUsed: checkpoint.features.verifierUsed,
+      diffLines: checkpoint.features.diffLines,
+      diffFilesChanged: checkpoint.features.diffFilesChanged,
+    },
+  };
+}
+
+export function appendRouteEvent(path: string, event: RouteEvent): void {
+  const resolved = resolve(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${JSON.stringify(event)}\n`, { flag: "a" });
+}
+
+export function readRouteEvents(path: string): RouteEvent[] {
+  const resolved = resolve(path);
+  try {
+    return readFileSync(resolved, "utf8")
+      .split("\n")
+      .filter((line) => line.trim())
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as RouteEvent];
+        } catch {
+          return [];
+        }
+      });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/observe.ts

@@ -0,0 +1,126 @@
+import { appendRouteEvent, buildRouteEvent } from "./ledger.js";
+import { decideRoute } from "./decision.js";
+import { checkpointWithDiffStats, streamCheckpointsFromSessionPath } from "./checkpoints.js";
+import {
+  activeProfile,
+  loadRouterConfig,
+  loadRouterState,
+  routerConfigPath,
+  routerDir,
+  routerEventsPath,
+  routerStatePath,
+  saveRouterState,
+  type RouterConfig,
+  type RouterProfile,
+} from "./config.js";
+import type { RouteAction, RouteDecision, RouterCheckpoint } from "./types.js";
+
+export interface RouterObserveSummary {
+  checkpointId: string;
+  action: RouteAction;
+  role: keyof RouterProfile | "none" | "current";
+  targetModel?: string;
+  currentModel?: string;
+  match: boolean | null;
+  confidence: number;
+  reason: string;
+  text: string;
+}
+
+function squish(text: unknown, max = 140): string {
+  const value = String(text ?? "").replace(/\s+/g, " ").trim();
+  return value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;
+}
+
+export function actionRole(action: RouteAction): RouterObserveSummary["role"] {
+  switch (action) {
+    case "continue_current": return "current";
+    case "continue_local": return "worker";
+    case "summarize_context": return "worker";
+    case "run_verifier": return "worker";
+    case "ask_micro_hint": return "smart";
+    case "escalate_plan_critique": return "smart";
+    case "escalate_debug_diagnosis": return "smart";
+    case "escalate_diff_review": return "reviewer";
+    case "delegate_full_step": return "smart";
+    case "spawn_subagent": return "smart";
+    case "merge_subagent_result": return "current";
+    case "stop_and_ask_user": return "none";
+  }
+}
+
+function modelLeaf(model: string): string {
+  return model.split("/").at(-1)?.toLowerCase() ?? model.toLowerCase();
+}
+
+export function modelsMatch(current: string | undefined, target: string | undefined): boolean | null {
+  if (!current || !target) return null;
+  const c = current.toLowerCase();
+  const t = target.toLowerCase();
+  return c === t || modelLeaf(c) === modelLeaf(t) || c.endsWith(`/${modelLeaf(t)}`) || t.endsWith(`/${modelLeaf(c)}`);
+}
+
+function targetForRole(role: RouterObserveSummary["role"], profile: RouterProfile, currentModel?: string): string | undefined {
+  if (role === "current") return currentModel;
+  if (role === "none") return undefined;
+  return profile[role];
+}
+
+export function summarizeRouterDecision(checkpoint: RouterCheckpoint, decision: RouteDecision, config: RouterConfig): RouterObserveSummary {
+  const profile = activeProfile(config);
+  const role = actionRole(decision.action);
+  const targetModel = targetForRole(role, profile, checkpoint.activeModel);
+  const match = role === "none" ? null : modelsMatch(checkpoint.activeModel, targetModel);
+  const verdict = match === null ? "INFO" : match ? "MATCH" : "MISMATCH";
+  const roleText = role === "none" ? "no-model" : role;
+  const targetText = targetModel ? `${roleText}(${targetModel})` : roleText;
+  const currentText = checkpoint.activeModel ? `current=${checkpoint.activeModel}` : "current=unknown";
+  return {
+    checkpointId: checkpoint.checkpointId,
+    action: decision.action,
+    role,
+    targetModel,
+    currentModel: checkpoint.activeModel,
+    match,
+    confidence: decision.confidence,
+    reason: decision.reason,
+    text: `router: ${verdict} ${decision.action} → ${targetText} · ${currentText} · ${decision.confidence.toFixed(2)} · ${squish(decision.reason)}`,
+  };
+}
+
+export async function latestCheckpointFromSession(sessionPath: string): Promise<RouterCheckpoint | null> {
+  let latest: RouterCheckpoint | null = null;
+  for await (const checkpoint of streamCheckpointsFromSessionPath(sessionPath)) latest = checkpoint;
+  return latest;
+}
+
+export async function observeRouterTurn(ctx: any): Promise<RouterObserveSummary | null> {
+  const config = loadRouterConfig(ctx);
+  if (!config.enabled || config.print === "off") return null;
+  const sessionPath = ctx?.sessionManager?.getSessionFile?.();
+  if (!sessionPath) return null;
+  const checkpoint = await latestCheckpointFromSession(String(sessionPath));
+  if (!checkpoint) return null;
+  const state = loadRouterState(ctx, String(sessionPath));
+  if (state.lastObservedCheckpointId === checkpoint.checkpointId) return null;
+
+  const liveCheckpoint = checkpointWithDiffStats(checkpoint, ctx?.cwd, [
+    String(sessionPath),
+    routerConfigPath(ctx),
+    routerDir(ctx),
+    routerStatePath(ctx, String(sessionPath)),
+    routerEventsPath(ctx, String(sessionPath)),
+  ]);
+  const decision = decideRoute(liveCheckpoint);
+  const summary = summarizeRouterDecision(liveCheckpoint, decision, config);
+  appendRouteEvent(routerEventsPath(ctx, String(sessionPath)), buildRouteEvent(liveCheckpoint, decision));
+  saveRouterState(ctx, {
+    lastObservedCheckpointId: checkpoint.checkpointId,
+    lastDecisionAction: decision.action,
+    lastSummary: summary.text,
+  }, String(sessionPath));
+
+  if (config.print === "mismatch_only" && summary.match !== false) return summary;
+  ctx.ui?.notify?.(summary.text, summary.match === false ? "warning" : "info");
+  return summary;
+}