@hassangameryt/freeflow 0.6.0 → 0.7.1

package/pi-extension/src/index.ts

@@ -1,8 +1,11 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
 import {
   COGNITIVE_ROUTING_CONTROL_ENTRY,
+  COGNITIVE_ROUTING_INACTIVE_ENTRY,
   COGNITIVE_ROUTING_INTENT_ENTRY,
-  CognitiveRoutingController,
 } from "./cognitive-routing/controller.js";
+import { PiRoutingSession, type PiRoutingSessionSnapshot } from "./cognitive-routing/pi-routing-session.js";
 import {
   cognitiveRoutingProfileCompletions,
   handleCognitiveRoutingProfileCommand,
@@ -23,21 +26,18 @@ import {
   freeflowModelSkillPaths,
   freeflowSkillPath,
   getRuntimeContext,
+  hasUsableMandatoryPrompts,
+  isPromptAvailable,
   readCapabilityState,
-  readModeState,
   refreshRuntimeContext,
-  restoreModeOverride,
+  restoreSessionOverrides,
   runtimeContext,
   filterBootstrapMessage,
-  setModeStatus,
+  setFreeflowStatus,
   skillPrompt,
   withFreeflowRuntimeState,
 } from "./runtime/runtime-context.js";
 
-function startupSelectionSuppressesCognitiveRouting(ctx: any): boolean {
-  return ctx?.modelStateProvenance?.explicitModel === true || ctx?.modelStateProvenance?.explicitThinking === true;
-}
-
 function unavailableCapability(capability: any, code: string, message: string): any {
   return {
     ...capability,
@@ -48,15 +48,12 @@ function unavailableCapability(capability: any, code: string, message: string):
 
 function modelFacingCapabilityState(
   capabilityState: any,
-  ctx: any,
   freeflowContext: any,
-  cognitiveRoutingController: CognitiveRoutingController | undefined,
+  routingSnapshot: PiRoutingSessionSnapshot,
   cognitiveRoutingActivationFailed = false,
 ): any {
   const surfaceState = {
     ...capabilityState,
-    interactionContract: { ...capabilityState?.interactionContract },
-    skills: { ...capabilityState?.skills },
     contextVirtualization: { ...capabilityState?.contextVirtualization },
     conversationHistory: { ...capabilityState?.conversationHistory },
     cognitiveRouting: { ...capabilityState?.cognitiveRouting },
@@ -69,53 +66,59 @@ function modelFacingCapabilityState(
     }
   };
 
-  if (!freeflowContext?.corePrompt) {
-    for (const key of [
-      "interactionContract",
-      "skills",
-      "contextVirtualization",
-      "conversationHistory",
-      "cognitiveRouting",
-    ]) {
-      markUnavailable(key, "Freeflow core prompt is unavailable.");
+  if (!hasUsableMandatoryPrompts(freeflowContext)) {
+    for (const key of ["contextVirtualization", "conversationHistory", "cognitiveRouting"]) {
+      markUnavailable(key, "Mandatory Freeflow prompt is unavailable.");
     }
     return surfaceState;
   }
 
-  if (surfaceState.interactionContract?.effective === true && !freeflowContext.interactionContractPrompt) {
-    markUnavailable("interactionContract", "Interaction Contract prompt is unavailable.");
-  }
-  if (surfaceState.skills?.effective === true && !freeflowContext.skillsPrompt) {
-    markUnavailable("skills", "Skills prompt is unavailable.");
+  if (
+    surfaceState.contextVirtualization?.effective === true &&
+    !isPromptAvailable(freeflowContext.contextVirtualizationPrompt)
+  ) {
+    markUnavailable("contextVirtualization", "Context Virtualization prompt is unavailable.");
   }
-
-  if (surfaceState.skills?.effective === true) {
-    if (surfaceState.contextVirtualization?.effective === true && !freeflowContext.contextVirtualizationPrompt) {
-      markUnavailable("contextVirtualization", "Context Virtualization prompt is unavailable.");
-    }
-    if (surfaceState.conversationHistory?.effective === true && !freeflowContext.conversationHistoryPrompt) {
-      markUnavailable("conversationHistory", "Conversation History prompt is unavailable.");
-    }
-  } else {
-    for (const key of ["contextVirtualization", "conversationHistory", "cognitiveRouting"]) {
-      markUnavailable(key, "Skills prompt is unavailable.");
-    }
+  if (
+    surfaceState.conversationHistory?.effective === true &&
+    !isPromptAvailable(freeflowContext.conversationHistoryPrompt)
+  ) {
+    markUnavailable("conversationHistory", "Conversation History prompt is unavailable.");
   }
 
   if (surfaceState.cognitiveRouting?.effective === true) {
-    if (startupSelectionSuppressesCognitiveRouting(ctx)) {
+    const controllerState = routingSnapshot.runtimeState;
+    if (routingSnapshot.disposition === "blocked") {
+      surfaceState.cognitiveRouting = unavailableCapability(
+        surfaceState.cognitiveRouting,
+        "runtime_blocked",
+        routingSnapshot.reason ?? "Cognitive Routing is blocked because its inactive state could not be persisted.",
+      );
+    } else if (routingSnapshot.startupSelectionSuppressed || routingSnapshot.disposition === "inactive") {
+      surfaceState.cognitiveRouting = unavailableCapability(
+        surfaceState.cognitiveRouting,
+        "runtime_inactive",
+        "Cognitive Routing is inactive because Pi owns the startup model or thinking level.",
+      );
+    } else if (controllerState?.runtimeStatus === "inactive") {
       surfaceState.cognitiveRouting = unavailableCapability(
         surfaceState.cognitiveRouting,
         "runtime_inactive",
-        "Cognitive Routing is inactive because the host selected the startup model or thinking level.",
+        controllerState.runtimeReason ?? "Cognitive Routing is inactive because Pi owns the current model state.",
+      );
+    } else if (controllerState?.runtimeStatus === "blocked") {
+      surfaceState.cognitiveRouting = unavailableCapability(
+        surfaceState.cognitiveRouting,
+        "runtime_blocked",
+        controllerState.runtimeReason ?? "Cognitive Routing is blocked because its state is not proven.",
       );
-    } else if (cognitiveRoutingActivationFailed || cognitiveRoutingController?.state()?.effective === false) {
+    } else if (cognitiveRoutingActivationFailed || controllerState?.effective === false) {
       surfaceState.cognitiveRouting = unavailableCapability(
         surfaceState.cognitiveRouting,
         "unavailable",
         "Cognitive Routing could not activate for this session.",
       );
-    } else if (!freeflowContext.cognitiveRoutingPrompt) {
+    } else if (!isPromptAvailable(freeflowContext.cognitiveRoutingPrompt)) {
       markUnavailable("cognitiveRouting", "Cognitive Routing prompt is unavailable.");
     }
   }
@@ -123,11 +126,6 @@ function modelFacingCapabilityState(
   return surfaceState;
 }
 
-function modelFacingModeState(modeState: any, capabilityState: any): any {
-  if (capabilityState?.skills?.effective === true) return modeState;
-  return { ...modeState, active: false, effectiveMode: null };
-}
-
 type SessionEntriesContext = {
   sessionManager?: {
     getBranch?: () => readonly unknown[];
@@ -150,7 +148,9 @@ function sessionHasConversationOrRoutingState(ctx: SessionEntriesContext | undef
       }
       return (
         record.type === "custom" &&
-        (record.customType === COGNITIVE_ROUTING_INTENT_ENTRY || record.customType === COGNITIVE_ROUTING_CONTROL_ENTRY)
+        (record.customType === COGNITIVE_ROUTING_INTENT_ENTRY ||
+          record.customType === COGNITIVE_ROUTING_CONTROL_ENTRY ||
+          record.customType === COGNITIVE_ROUTING_INACTIVE_ENTRY)
       );
     });
   } catch {
@@ -158,51 +158,17 @@ function sessionHasConversationOrRoutingState(ctx: SessionEntriesContext | undef
   }
 }
 
-function hasCognitiveRoutingHost(pi: any, ctx: any): boolean {
-  return (
-    isPiFlowHost(pi?.host) &&
-    typeof pi?.appendEntryDurable === "function" &&
-    typeof pi?.acquireModelStateControl === "function" &&
-    typeof ctx?.modelRegistry?.getApiKeyAndHeaders === "function"
-  );
-}
-
-async function reconcileCognitiveRoutingController(
-  pi: any,
-  ctx: any,
-  capabilityState: any,
-  previous: CognitiveRoutingController | undefined,
-): Promise<CognitiveRoutingController | undefined> {
-  const cognitiveRouting = capabilityState?.cognitiveRouting;
-  if (
-    !isPiFlowHost(pi?.host) ||
-    !cognitiveRouting?.effective ||
-    startupSelectionSuppressesCognitiveRouting(ctx) ||
-    !hasCognitiveRoutingHost(pi, ctx)
-  ) {
-    if (previous) await previous.deactivate();
-    return undefined;
-  }
-
-  const controller = new CognitiveRoutingController({ capabilityState: cognitiveRouting, pi, ctx });
-  const recovered = await controller.recover();
-  if (recovered.status === "pending") return controller;
-  if (recovered.status !== "active") {
-    const activated = await controller.activate();
-    return activated.status === "active" ? controller : undefined;
-  }
-  return controller;
-}
-
 async function applyCapabilityToolVisibility(
   pi: any,
   ctx: any,
   capabilityState = undefined,
-  cognitiveRoutingController: CognitiveRoutingController | undefined = undefined,
+  routingSnapshot: PiRoutingSessionSnapshot = {
+    status: "available",
+    disposition: "available",
+    startupSelectionSuppressed: false,
+  },
 ): Promise<void> {
-  if (typeof pi?.setActiveTools !== "function" || typeof pi?.getAllTools !== "function") {
-    return;
-  }
+  if (typeof pi?.setActiveTools !== "function" || typeof pi?.getAllTools !== "function") return;
 
   const state = capabilityState ?? (await readCapabilityState(ctx.cwd, ctx, pi?.host));
   const allToolNames = pi
@@ -216,12 +182,11 @@ async function applyCapabilityToolVisibility(
   );
 
   if (allToolNameSet.has(COGNITIVE_ROUTING_SWITCH_TOOL_NAME)) {
-    const controllerState = cognitiveRoutingController?.state();
+    const controllerState = routingSnapshot.runtimeState;
     const routingToolActive =
       state.cognitiveRouting?.effective === true &&
       controllerState?.effective === true &&
-      controllerState.controlMode === "automatic" &&
-      !startupSelectionSuppressesCognitiveRouting(ctx);
+      controllerState.controlMode === "automatic";
     if (routingToolActive) active.add(COGNITIVE_ROUTING_SWITCH_TOOL_NAME);
     else active.delete(COGNITIVE_ROUTING_SWITCH_TOOL_NAME);
   }
@@ -237,29 +202,6 @@ async function applyCapabilityToolVisibility(
   pi.setActiveTools([...active]);
 }
 
-async function applyLiveCapabilityState(
-  pi: any,
-  ctx: any,
-  cognitiveRoutingController: CognitiveRoutingController | undefined,
-  options: { reconcileCognitiveRouting?: boolean } = {},
-): Promise<CognitiveRoutingController | undefined> {
-  const [modeState, capabilityState] = await Promise.all([
-    readModeState(ctx.cwd),
-    readCapabilityState(ctx.cwd, ctx, pi?.host),
-  ]);
-  await refreshRuntimeContext(capabilityState);
-  let nextController = cognitiveRoutingController;
-  if (
-    options.reconcileCognitiveRouting &&
-    (nextController === undefined || capabilityState.cognitiveRouting?.effective !== true)
-  ) {
-    nextController = await reconcileCognitiveRoutingController(pi, ctx, capabilityState, nextController);
-  }
-  setModeStatus(ctx, modeState, capabilityState, nextController?.state());
-  await applyCapabilityToolVisibility(pi, ctx, capabilityState, nextController);
-  return nextController;
-}
-
 function disabledToolCall(toolName: string, capability: string) {
   const command = capability === "freeflow" ? "/freeflow settings" : `/${capability} settings`;
   return {
@@ -268,7 +210,7 @@ function disabledToolCall(toolName: string, capability: string) {
   };
 }
 
-function freeflowCompletions(prefix: string | undefined, hostInfo = undefined) {
+function freeflowCompletions(prefix: string | undefined, cognitiveRoutingAvailable = false) {
   const query = prefix ?? "";
   if (query.startsWith("settings ")) {
     const settingsQuery = query.slice("settings ".length);
@@ -280,27 +222,12 @@ function freeflowCompletions(prefix: string | undefined, hostInfo = undefined) {
       .filter((item) => item.value.startsWith(settingsQuery))
       .map((item) => ({ ...item, value: `settings ${item.value}` }));
   }
-  if (isPiFlowHost(hostInfo) && query.startsWith("profile ")) {
+  if (cognitiveRoutingAvailable && query.startsWith("profile ")) {
     return cognitiveRoutingProfileCompletions(query.slice("profile ".length)).map((item) => ({
       ...item,
       value: `profile ${item.value}`,
     }));
   }
-  if (query.startsWith("mode ")) {
-    const modeQuery = query.slice("mode ".length);
-    return [
-      { value: "conversation", label: "conversation", description: "Read-only discussion and inspection" },
-      { value: "workflow", label: "workflow", description: "Adaptive workflow for consequential work" },
-      { value: "strict-workflow", label: "strict-workflow", description: "Stronger pressure at high-risk boundaries" },
-      {
-        value: "reset",
-        label: "reset",
-        description: "Clear the session override and use the configured default",
-      },
-    ]
-      .filter((item) => item.value.startsWith(modeQuery))
-      .map((item) => ({ ...item, value: `mode ${item.value}` }));
-  }
   if (query.startsWith("context ")) {
     const contextQuery = query.slice("context ".length);
     return [
@@ -316,8 +243,7 @@ function freeflowCompletions(prefix: string | undefined, hostInfo = undefined) {
     { value: "settings", label: "settings", description: "Open personal override settings" },
     { value: "status", label: "status", description: "Show effective Freeflow state" },
     { value: "context", label: "context", description: "Inspect Freeflow Context" },
-    { value: "mode", label: "mode", description: "Select a temporary session mode" },
-    ...(isPiFlowHost(hostInfo)
+    ...(cognitiveRoutingAvailable
       ? [{ value: "profile", label: "profile", description: "Hold or release Cognitive Routing profile control" }]
       : []),
     { value: "enable", label: "enable", description: "Enable Freeflow for this repository" },
@@ -333,10 +259,17 @@ function bypassCompletions(prefix: string | undefined) {
   ].filter((item) => item.value.startsWith(query));
 }
 
-async function sendSkillCommand(pi: any, ctx: any, skill: string, args: string | undefined) {
+type FreeflowExtensionAPI = ExtensionAPI & { host?: unknown };
+
+async function sendSkillCommand(
+  pi: FreeflowExtensionAPI,
+  ctx: ExtensionCommandContext,
+  skill: string,
+  args: string | undefined,
+) {
   const state = await readCapabilityState(ctx.cwd, ctx, pi?.host);
   if (skill === "setup-freeflow" && !state.configured) {
-    await pi.sendUserMessage(skillPrompt(skill, args));
+    await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
     return;
   }
   if (!state.configured) {
@@ -350,23 +283,27 @@ async function sendSkillCommand(pi: any, ctx: any, skill: string, args: string |
     );
     return;
   }
-  if (!state.skills.effective) {
-    ctx.ui.notify("Freeflow skills are disabled. Use /freeflow settings to enable skills.", "warning");
+  const freeflowContext = await getRuntimeContext(state);
+  if (!hasUsableMandatoryPrompts(freeflowContext)) {
+    ctx.ui.notify("Freeflow core prompts are unavailable; the requested skill cannot be dispatched.", "warning");
     return;
   }
-  await pi.sendUserMessage(skillPrompt(skill, args));
+  await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
 }
 
-export default function freeflow(pi) {
-  let cognitiveRoutingController: CognitiveRoutingController | undefined;
+export default function freeflow(pi: FreeflowExtensionAPI) {
+  // SAFETY: These helpers register complete Pi tool definitions but retain legacy structural typing for PiFlow compatibility.
+  const toolRegistrar = pi as unknown as { registerTool(tool: Record<string, unknown>): void };
+  const routingSession = new PiRoutingSession({ pi, stockPi: !isPiFlowHost(pi?.host) });
   let latestCognitiveRoutingContext: any;
   let providerSurfaceSnapshot: { context: any; value: any } | undefined;
+  let runtimeStateRefreshRequired = true;
   let freeflowContextRuntime: FreeflowContextRuntime | undefined;
   let contextVirtualizationRuntime: ContextVirtualizationRuntime | undefined;
   let conversationHistoryRuntime: ConversationHistoryRuntime | undefined;
   const registerContextToolForState = (capabilityState: any) => {
     registerFreeflowContextTool(
-      pi,
+      toolRegistrar,
       () => contextVirtualizationRuntime,
       () => conversationHistoryRuntime,
       {
@@ -376,73 +313,86 @@ export default function freeflow(pi) {
     );
   };
   const buildProviderSurface = async (ctx: any, activateCognitiveRouting = false): Promise<any> => {
-    const [modeState, capabilityState] = await Promise.all([
-      readModeState(ctx.cwd),
-      readCapabilityState(ctx.cwd, ctx, pi?.host),
-    ]);
+    const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
     const freeflowContext = await getRuntimeContext(capabilityState);
     const promptCapabilityState = modelFacingCapabilityState(
       capabilityState,
-      ctx,
       freeflowContext,
-      cognitiveRoutingController,
+      routingSession.snapshot(),
     );
     let activationAttempted = false;
     if (
       activateCognitiveRouting &&
-      (cognitiveRoutingController === undefined || promptCapabilityState.cognitiveRouting?.effective !== true)
+      routingSession.canAutoActivate() &&
+      (!routingSession.hasController() || promptCapabilityState.cognitiveRouting?.effective !== true)
     ) {
-      activationAttempted =
-        promptCapabilityState.cognitiveRouting?.effective === true && !startupSelectionSuppressesCognitiveRouting(ctx);
+      activationAttempted = promptCapabilityState.cognitiveRouting?.effective === true;
       try {
-        cognitiveRoutingController = await reconcileCognitiveRoutingController(
-          pi,
+        await routingSession.reconcileController(
           ctx,
           promptCapabilityState,
-          cognitiveRoutingController,
+          routingSession.armed ? { ...routingSession.armed } : undefined,
         );
+        if (routingSession.hasController()) {
+          routingSession.clearArmed();
+          if (routingSession.snapshot().status === "active") routingSession.markActive();
+        }
       } catch {
-        cognitiveRoutingController = undefined;
+        routingSession.clearController();
       }
     }
     const surfaceCapabilityState = modelFacingCapabilityState(
       promptCapabilityState,
-      ctx,
       freeflowContext,
-      cognitiveRoutingController,
-      activationAttempted && !cognitiveRoutingController,
+      routingSession.snapshot(),
+      activationAttempted && !routingSession.hasController(),
     );
+    const routingSnapshot = routingSession.snapshot();
     return {
-      modeState: modelFacingModeState(modeState, surfaceCapabilityState),
       capabilityState: surfaceCapabilityState,
       freeflowContext,
-      cognitiveRoutingRuntime: cognitiveRoutingController?.state(),
+      cognitiveRoutingRuntime: routingSnapshot.runtimeState,
       configuredCapabilityState: capabilityState,
     };
   };
   const applyLiveCapabilityStateForSession = async (
     ctx: any,
-    options: { reconcileCognitiveRouting?: boolean } = {},
+    options: { reconcileCognitiveRouting?: boolean; materializeCognitiveRouting?: boolean } = {},
   ): Promise<void> => {
-    cognitiveRoutingController = await applyLiveCapabilityState(pi, ctx, cognitiveRoutingController, options);
-    registerContextToolForState(await readCapabilityState(ctx.cwd, ctx, pi?.host));
+    providerSurfaceSnapshot = undefined;
+    await routingSession.applyLiveCapabilityState(ctx, options);
+    const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
+    const freeflowContext = await getRuntimeContext(capabilityState);
+    const surfaceCapabilityState = modelFacingCapabilityState(
+      capabilityState,
+      freeflowContext,
+      routingSession.snapshot(),
+    );
+    const routingSnapshot = routingSession.snapshot();
+    setFreeflowStatus(ctx, surfaceCapabilityState, routingSnapshot.runtimeState, freeflowContext, {
+      startupSelectionSuppressed: routingSnapshot.startupSelectionSuppressed,
+    });
+    await applyCapabilityToolVisibility(pi, ctx, surfaceCapabilityState, routingSnapshot);
+    registerContextToolForState(surfaceCapabilityState);
   };
 
-  if (isPiFlowHost(pi?.host)) {
-    registerCognitiveRoutingTool(pi, () => cognitiveRoutingController);
-    registerCognitiveRoutingHistoryTool(pi, (options, context) => {
-      if (cognitiveRoutingController) return cognitiveRoutingController.history(options);
-      return readCognitiveRoutingHistory(context ?? latestCognitiveRoutingContext, options);
+  if (routingSession.supportsCognitiveRoutingRuntime()) {
+    registerCognitiveRoutingTool(toolRegistrar, () => routingSession.controllerForTool());
+    registerCognitiveRoutingHistoryTool(toolRegistrar, (options, context) => {
+      return (
+        routingSession.history(options) ??
+        readCognitiveRoutingHistory(context ?? latestCognitiveRoutingContext, options)
+      );
     });
   }
   registerFreeflowContextTool(
-    pi,
+    toolRegistrar,
     () => contextVirtualizationRuntime,
     () => conversationHistoryRuntime,
     { contextVirtualization: false, conversationHistory: false },
   );
 
-  if (isPiFlowHost(pi?.host) && typeof pi.registerShortcut === "function") {
+  if (routingSession.supportsCognitiveRoutingRuntime() && typeof pi.registerShortcut === "function") {
     pi.registerShortcut("ctrl+shift+r", {
       description: "Cycle the Cognitive Routing manual standard/reasoning hold",
       handler: async (ctx) => {
@@ -450,17 +400,27 @@ export default function freeflow(pi) {
           ctx.ui?.notify?.("Freeflow settings and profile changes are available only while Pi is idle.", "warning");
           return;
         }
-        if (!cognitiveRoutingController) {
+        const armedCycle = routingSession.hasController() ? undefined : routingSession.cycleArmedManual();
+        if (armedCycle) {
+          routingSession.beginExplicitReactivation();
+          ctx.ui?.notify?.(`Cognitive Routing manual hold set to ${armedCycle.target}.`, "info");
+          await applyLiveCapabilityStateForSession(ctx, {
+            reconcileCognitiveRouting: true,
+            materializeCognitiveRouting: !isPiFlowHost(pi?.host),
+          });
+          return;
+        }
+        if (!routingSession.hasController()) {
+          routingSession.beginExplicitReactivation();
           await applyLiveCapabilityStateForSession(ctx, { reconcileCognitiveRouting: true });
         }
-        const controller = cognitiveRoutingController;
-        if (!controller) {
+        const state = routingSession.snapshot().runtimeState;
+        if (!state) {
           ctx.ui?.notify?.("Cognitive Routing is unavailable for this session.", "warning");
           return;
         }
-        const current = controller.state().activeProfile;
-        const target = current === "reasoning" ? "standard" : "reasoning";
-        const result = await controller.setManualProfile(target, "profile-shortcut");
+        const target = state.activeProfile === "reasoning" ? "standard" : "reasoning";
+        const result = await routingSession.setManualProfile(target, "profile-shortcut");
         if (result.status === "active") {
           ctx.ui?.notify?.(`Cognitive Routing manual hold set to ${target}.`, "info");
         } else {
@@ -470,43 +430,74 @@ export default function freeflow(pi) {
       },
     });
     pi.registerShortcut("ctrl+shift+a", {
-      description: "Cycle the Cognitive Routing automatic standard/reasoning profile",
+      description: "Set Cognitive Routing to automatic Reasoning control",
       handler: async (ctx) => {
         if (typeof ctx?.isIdle === "function" && !ctx.isIdle()) {
           ctx.ui?.notify?.("Freeflow settings and profile changes are available only while Pi is idle.", "warning");
           return;
         }
-        if (!cognitiveRoutingController) {
-          await applyLiveCapabilityStateForSession(ctx, { reconcileCognitiveRouting: true });
-        }
-        const controller = cognitiveRoutingController;
-        if (!controller) {
-          ctx.ui?.notify?.("Cognitive Routing is unavailable for this session.", "warning");
+        const armedCycle = routingSession.hasController() ? undefined : routingSession.cycleArmedAutomatic();
+        if (armedCycle) {
+          if (!armedCycle.changed) {
+            ctx.ui?.notify?.("Cognitive Routing automatic control active.", "info");
+            return;
+          }
+          ctx.ui?.notify?.("Cognitive Routing automatic control active.", "info");
+          routingSession.beginExplicitReactivation();
+          await applyLiveCapabilityStateForSession(ctx, {
+            reconcileCognitiveRouting: true,
+            materializeCognitiveRouting: !isPiFlowHost(pi?.host),
+          });
           return;
         }
-        const state = controller.state();
-        const target = state.activeProfile === "reasoning" ? "standard" : "reasoning";
-        const result =
-          state.controlMode === "automatic" && state.activeProfile
-            ? await controller.switchAutomaticProfile(
-                target,
-                `Cycle automatic profile to ${target}.`,
-                "user",
-                "profile-shortcut",
-              )
-            : await controller.setAutomaticControl("profile-shortcut");
+        if (!routingSession.hasController()) {
+          routingSession.beginExplicitReactivation();
+          await applyLiveCapabilityStateForSession(ctx, { reconcileCognitiveRouting: true });
+        }
+        const result = await routingSession.setAutomaticControl("profile-shortcut");
         if (result.status === "automatic") {
           ctx.ui?.notify?.("Cognitive Routing automatic control active.", "info");
-        } else if (result.status === "active") {
-          ctx.ui?.notify?.(`Cognitive Routing automatic profile set to ${result.profile}.`, "info");
         } else {
-          ctx.ui?.notify?.(`Cognitive Routing could not cycle the automatic profile: ${result.reason}.`, "warning");
+          ctx.ui?.notify?.(`Cognitive Routing could not change control: ${result.reason}.`, "warning");
         }
         await applyLiveCapabilityStateForSession(ctx);
       },
     });
   }
 
+  if (!isPiFlowHost(pi?.host) && routingSession.supportsCognitiveRoutingRuntime()) {
+    pi.on("model_select", async (event, ctx) => {
+      if (!routingSession.hasController()) {
+        if (!routingSession.armed) return;
+        routingSession.clearArmed();
+        routingSession.observeArmedNativeChange(ctx, "Pi model selection");
+        await applyLiveCapabilityStateForSession(ctx);
+        return;
+      }
+      const result = await routingSession.observeNativeChange("Pi model selection", event?.source);
+      if (result.status !== "ignored") {
+        latestCognitiveRoutingContext = ctx;
+        providerSurfaceSnapshot = undefined;
+        await applyLiveCapabilityStateForSession(ctx);
+      }
+    });
+    pi.on("thinking_level_select", async (_event, ctx) => {
+      if (!routingSession.hasController()) {
+        if (!routingSession.armed) return;
+        routingSession.clearArmed();
+        routingSession.observeArmedNativeChange(ctx, "Pi thinking-level selection");
+        await applyLiveCapabilityStateForSession(ctx);
+        return;
+      }
+      const result = await routingSession.observeNativeChange("Pi thinking-level selection");
+      if (result.status !== "ignored") {
+        latestCognitiveRoutingContext = ctx;
+        providerSurfaceSnapshot = undefined;
+        await applyLiveCapabilityStateForSession(ctx);
+      }
+    });
+  }
+
   pi.on("resources_discover", async (event, ctx) => {
     const cwd = ctx?.cwd ?? event?.cwd ?? process.cwd();
     const snapshot =
@@ -517,16 +508,18 @@ export default function freeflow(pi) {
     if (!state.configured) {
       return { skillPaths: [freeflowSkillPath("setup-freeflow")] };
     }
-    if (!state.enabled || !state.skills.effective) {
+    if (!state.enabled || !hasUsableMandatoryPrompts(snapshot.freeflowContext)) {
       return { skillPaths: [] };
     }
     return { skillPaths: freeflowModelSkillPaths(state) };
   });
 
-  pi.on("session_start", async (_event, ctx) => {
+  pi.on("session_start", async (event, ctx) => {
+    routingSession.resetForSession(ctx, event);
     latestCognitiveRoutingContext = ctx;
     providerSurfaceSnapshot = undefined;
-    restoreModeOverride(ctx);
+    runtimeStateRefreshRequired = true;
+    restoreSessionOverrides(ctx);
     freeflowContextRuntime = new FreeflowContextRuntime(ctx);
     contextVirtualizationRuntime = new ContextVirtualizationRuntime(pi, ctx, freeflowContextRuntime);
     conversationHistoryRuntime = new ConversationHistoryRuntime(
@@ -537,41 +530,51 @@ export default function freeflow(pi) {
     await contextVirtualizationRuntime.recover(ctx);
     const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
     await refreshRuntimeContext(capabilityState);
+    routingSession.ensureStartupInactive(ctx, capabilityState.cognitiveRouting?.effective === true);
+    routingSession.reconcileNativeEntries(ctx);
     const hasSessionState = sessionHasConversationOrRoutingState(ctx);
     const snapshot = await buildProviderSurface(ctx, hasSessionState);
-    const cognitiveRoutingStartupPending =
-      snapshot.capabilityState?.cognitiveRouting?.effective === true &&
+    if (
       !hasSessionState &&
-      !startupSelectionSuppressesCognitiveRouting(ctx);
+      snapshot.capabilityState?.cognitiveRouting?.effective === true &&
+      routingSession.canAutoActivate()
+    ) {
+      routingSession.armFromCapability(snapshot.capabilityState.cognitiveRouting);
+    } else {
+      routingSession.clearArmed();
+    }
     registerContextToolForState(snapshot.capabilityState);
-    setModeStatus(ctx, snapshot.modeState, snapshot.capabilityState, snapshot.cognitiveRoutingRuntime, {
-      cognitiveRoutingStartupPending,
-    });
-    await applyCapabilityToolVisibility(pi, ctx, snapshot.capabilityState, cognitiveRoutingController);
+    const routingSnapshot = routingSession.snapshot();
+    setFreeflowStatus(
+      ctx,
+      snapshot.capabilityState,
+      snapshot.cognitiveRoutingRuntime ?? routingSnapshot.runtimeState,
+      snapshot.freeflowContext,
+      { startupSelectionSuppressed: routingSnapshot.startupSelectionSuppressed },
+    );
+    await applyCapabilityToolVisibility(pi, ctx, snapshot.capabilityState, routingSnapshot);
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
-    if (!cognitiveRoutingController) return undefined;
+    if (!routingSession.hasController()) return undefined;
     await applyLiveCapabilityStateForSession(ctx);
     return undefined;
   });
 
   pi.on("session_shutdown", async (event) => {
+    await routingSession.shutdown(event?.reason);
     providerSurfaceSnapshot = undefined;
-    const controller = cognitiveRoutingController;
-    cognitiveRoutingController = undefined;
     freeflowContextRuntime = undefined;
     contextVirtualizationRuntime = undefined;
     conversationHistoryRuntime = undefined;
-    if (controller) await controller.shutdown(event?.reason);
   });
 
   pi.on("session_tree", async (_event, ctx) => {
     latestCognitiveRoutingContext = ctx;
     providerSurfaceSnapshot = undefined;
-    restoreModeOverride(ctx);
-    const controller = cognitiveRoutingController;
-    if (controller) await controller.reconcileBranch();
+    runtimeStateRefreshRequired = true;
+    restoreSessionOverrides(ctx);
+    await routingSession.reconcileBranch();
     if (contextVirtualizationRuntime) {
       contextVirtualizationRuntime.setContext(ctx);
       await contextVirtualizationRuntime.recover(ctx);
@@ -583,21 +586,14 @@ export default function freeflow(pi) {
   pi.on("session_compact", async (_event, ctx) => {
     latestCognitiveRoutingContext = ctx;
     providerSurfaceSnapshot = undefined;
-    const controller = cognitiveRoutingController;
-    if (controller) await controller.reconcileBranch("session-compact");
+    runtimeStateRefreshRequired = true;
+    await routingSession.reconcileBranch("session-compact");
     if (contextVirtualizationRuntime) {
       contextVirtualizationRuntime.setContext(ctx);
       await contextVirtualizationRuntime.recover(ctx);
     }
     conversationHistoryRuntime?.setContext(ctx);
-    const [modeState, capabilityState] = await Promise.all([
-      readModeState(ctx.cwd),
-      readCapabilityState(ctx.cwd, ctx, pi?.host),
-    ]);
-    await refreshRuntimeContext(capabilityState);
-    registerContextToolForState(capabilityState);
-    setModeStatus(ctx, modeState, capabilityState, cognitiveRoutingController?.state());
-    await applyCapabilityToolVisibility(pi, ctx, capabilityState, cognitiveRoutingController);
+    await applyLiveCapabilityStateForSession(ctx);
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
@@ -605,8 +601,11 @@ export default function freeflow(pi) {
     const snapshot = await buildProviderSurface(ctx, true);
     providerSurfaceSnapshot = { context: ctx, value: snapshot };
     registerContextToolForState(snapshot.capabilityState);
-    setModeStatus(ctx, snapshot.modeState, snapshot.capabilityState, snapshot.cognitiveRoutingRuntime);
-    await applyCapabilityToolVisibility(pi, ctx, snapshot.capabilityState, cognitiveRoutingController);
+    const routingSnapshot = routingSession.snapshot();
+    setFreeflowStatus(ctx, snapshot.capabilityState, snapshot.cognitiveRoutingRuntime, snapshot.freeflowContext, {
+      startupSelectionSuppressed: routingSnapshot.startupSelectionSuppressed,
+    });
+    await applyCapabilityToolVisibility(pi, ctx, snapshot.capabilityState, routingSnapshot);
     const freeflowRuntimeContext = runtimeContext(snapshot.freeflowContext, snapshot.capabilityState);
     const systemPrompt = freeflowRuntimeContext
       ? `${event.systemPrompt}\n\n${freeflowRuntimeContext}`
@@ -620,7 +619,6 @@ export default function freeflow(pi) {
     if (providerSurfaceSnapshot?.context === ctx) providerSurfaceSnapshot = undefined;
     const cognitiveRoutingRuntime = snapshot.cognitiveRoutingRuntime;
     const surfaceCapabilityState = snapshot.capabilityState;
-    const surfaceModeState = snapshot.modeState;
     let changed = false;
     let messages = event.messages
       .map((message) => {
@@ -644,14 +642,19 @@ export default function freeflow(pi) {
       conversationHistoryRuntime.setContext(ctx);
       conversationHistoryRuntime.capture(surfaceCapabilityState.contextVirtualization?.effective === true);
     }
+    const forceRuntimeStateRefresh = runtimeStateRefreshRequired;
     const nextMessages = withFreeflowRuntimeState(
       messages,
-      surfaceModeState,
       surfaceCapabilityState,
       cognitiveRoutingRuntime,
+      snapshot.freeflowContext,
+      { force: forceRuntimeStateRefresh },
     );
-    changed = true;
-    messages = nextMessages;
+    if (nextMessages !== messages) {
+      changed = true;
+      messages = nextMessages;
+    }
+    if (forceRuntimeStateRefresh) runtimeStateRefreshRequired = false;
     return changed ? { messages } : undefined;
   });
 
@@ -670,7 +673,7 @@ export default function freeflow(pi) {
 
   pi.on("tool_result", async (event, ctx) => {
     const toolName = typeof event?.toolName === "string" ? event.toolName : "";
-    if (isPiFlowHost(pi?.host) && toolName === COGNITIVE_ROUTING_SWITCH_TOOL_NAME) {
+    if (routingSession.supportsCognitiveRoutingRuntime() && toolName === COGNITIVE_ROUTING_SWITCH_TOOL_NAME) {
       await applyLiveCapabilityStateForSession(ctx);
     }
     return undefined;
@@ -697,7 +700,7 @@ export default function freeflow(pi) {
 
   pi.registerCommand("freeflow", {
     description: "Open unified Freeflow settings or print compact status",
-    getArgumentCompletions: (prefix) => freeflowCompletions(prefix, pi?.host),
+    getArgumentCompletions: (prefix) => freeflowCompletions(prefix, routingSession.supportsCognitiveRoutingRuntime()),
     handler: async (args, ctx) => {
       const contextInput = (args ?? "").trim();
       if (contextInput === "context" || contextInput.startsWith("context ")) {
@@ -711,23 +714,30 @@ export default function freeflow(pi) {
         );
         return;
       }
-      if (isPiFlowHost(pi?.host) && /^profile(?:\s|$)/i.test((args ?? "").trim())) {
+      if (routingSession.supportsCognitiveRoutingRuntime() && /^profile(?:\s|$)/i.test((args ?? "").trim())) {
         const profileCommandContext = {
           isIdle: ctx?.isIdle,
           ui: ctx?.ui,
-          history: (options) =>
-            cognitiveRoutingController?.history(options) ?? readCognitiveRoutingHistory(ctx, options),
+          history: (options) => routingSession.history(options) ?? readCognitiveRoutingHistory(ctx, options),
         };
         const historyCommand = /^profile\s+history(?:\s|$)/i.test((args ?? "").trim());
         if (historyCommand) {
-          await handleCognitiveRoutingProfileCommand(args, profileCommandContext, cognitiveRoutingController);
+          await handleCognitiveRoutingProfileCommand(args, profileCommandContext, routingSession.commandController());
           return;
         }
-        if (!cognitiveRoutingController) {
+        if (!routingSession.hasController() && !routingSession.armed) {
+          routingSession.beginExplicitReactivation();
           await applyLiveCapabilityStateForSession(ctx, { reconcileCognitiveRouting: true });
         }
-        if (await handleCognitiveRoutingProfileCommand(args, profileCommandContext, cognitiveRoutingController)) {
-          await applyLiveCapabilityStateForSession(ctx);
+        const profileController = routingSession.commandController();
+        if (await handleCognitiveRoutingProfileCommand(args, profileCommandContext, profileController)) {
+          if (profileController) {
+            routingSession.beginExplicitReactivation();
+            await applyLiveCapabilityStateForSession(ctx, {
+              reconcileCognitiveRouting: routingSession.armed !== undefined,
+              materializeCognitiveRouting: routingSession.armed !== undefined && !isPiFlowHost(pi?.host),
+            });
+          }
           return;
         }
       }
@@ -740,7 +750,7 @@ export default function freeflow(pi) {
           });
         },
         pi,
-        cognitiveRoutingController,
+        routingSession.commandController(),
       );
     },
   });