@hassangameryt/freeflow 0.6.0 → 0.7.1

package/pi-extension/src/runtime/runtime-context.ts

@@ -3,9 +3,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
-import { isPiFlowHost } from "./runtime-identity.js";
-
-export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/host.js";
 
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
@@ -43,7 +41,6 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "execute-work",
   "finish-branch",
   "handoff",
-  "mode-contract",
   "release-work",
   "review-artifact",
   "review-work",
@@ -84,20 +81,11 @@ export function freeflowModelSkillPaths(capabilityState = undefined) {
   return paths;
 }
 
-type SessionCoreKey =
-  "enabled" | "interactionContract" | "skillsEnabled" | "contextVirtualization" | "conversationHistory";
+type SessionCoreKey = "enabled" | "contextVirtualization" | "conversationHistory";
 type SessionCoreOverrides = Partial<Record<SessionCoreKey, boolean>>;
 
-const MODE_STATE_ENTRY = "freeflow-mode";
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
-const SESSION_CORE_KEYS = new Set<SessionCoreKey>([
-  "enabled",
-  "interactionContract",
-  "skillsEnabled",
-  "contextVirtualization",
-  "conversationHistory",
-]);
-const RESET_MODE_ARGS = new Set(["reset"]);
+const SESSION_CORE_KEYS = new Set<SessionCoreKey>(["enabled", "contextVirtualization", "conversationHistory"]);
 
 export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
 export const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
@@ -107,12 +95,22 @@ export const COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE = "freeflow-cognitive-rout
 export const FREEFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-bootstrap";
 
 let runtimeContextCache = null;
-let currentModeOverride = null;
 let currentSessionOverrides: SessionCoreOverrides = {};
 
+export function isPromptAvailable(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function hasUsableMandatoryPrompts(freeflowContext: any): boolean {
+  return (
+    isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
+  );
+}
+
 async function readPromptFile(url: URL): Promise<string | null> {
   try {
-    return await readFile(url, "utf8");
+    const prompt = await readFile(url, "utf8");
+    return isPromptAvailable(prompt) ? prompt.trim() : null;
   } catch {
     return null;
   }
@@ -120,15 +118,12 @@ async function readPromptFile(url: URL): Promise<string | null> {
 
 async function loadRuntimeContext(capabilityState = undefined) {
   const freeflowEnabled = capabilityState?.enabled === true;
-  const interactionContractEnabled = capabilityState?.interactionContract?.effective === true;
-  const skillsEnabled = capabilityState?.skills?.effective === true;
   const contextVirtualizationEnabled = capabilityState?.contextVirtualization?.effective === true;
   const conversationHistoryEnabled = capabilityState?.conversationHistory?.effective === true;
   const cognitiveRoutingEnabled = capabilityState?.cognitiveRouting?.effective === true;
   const [
     corePrompt,
     interactionContractPrompt,
-    skillsPrompt,
     cognitiveRoutingPrompt,
     contextVirtualizationPrompt,
     conversationHistoryPrompt,
@@ -136,12 +131,9 @@ async function loadRuntimeContext(capabilityState = undefined) {
     freeflowEnabled
       ? readPromptFile(new URL("../../../runtime/prompts/core.md", import.meta.url))
       : Promise.resolve(null),
-    interactionContractEnabled
+    freeflowEnabled
       ? readPromptFile(new URL("../../../runtime/prompts/interaction-contract.md", import.meta.url))
       : Promise.resolve(null),
-    skillsEnabled
-      ? readPromptFile(new URL("../../../runtime/prompts/skills.md", import.meta.url))
-      : Promise.resolve(null),
     cognitiveRoutingEnabled
       ? readPromptFile(new URL("../../../runtime/prompts/cognitive-routing.md", import.meta.url))
       : Promise.resolve(null),
@@ -156,7 +148,6 @@ async function loadRuntimeContext(capabilityState = undefined) {
   return {
     corePrompt,
     interactionContractPrompt,
-    skillsPrompt,
     cognitiveRoutingPrompt,
     contextVirtualizationPrompt,
     conversationHistoryPrompt,
@@ -167,13 +158,12 @@ function runtimeContextCacheSatisfies(capabilityState) {
   if (!runtimeContextCache) return false;
   const expected = {
     corePrompt: capabilityState?.enabled === true,
-    interactionContractPrompt: capabilityState?.interactionContract?.effective === true,
-    skillsPrompt: capabilityState?.skills?.effective === true,
+    interactionContractPrompt: capabilityState?.enabled === true,
     cognitiveRoutingPrompt: capabilityState?.cognitiveRouting?.effective === true,
     contextVirtualizationPrompt: capabilityState?.contextVirtualization?.effective === true,
     conversationHistoryPrompt: capabilityState?.conversationHistory?.effective === true,
   };
-  return Object.entries(expected).every(([key, required]) => !required || Boolean(runtimeContextCache[key]));
+  return Object.entries(expected).every(([key, required]) => !required || isPromptAvailable(runtimeContextCache[key]));
 }
 
 export async function refreshRuntimeContext(capabilityState = undefined) {
@@ -223,10 +213,6 @@ function isRecord(value) {
 }
 
 function validateCoreConfigFields(value) {
-  if (value.defaultMode !== undefined && !VALID_MODES.has(value.defaultMode)) {
-    return `invalid defaultMode: ${JSON.stringify(value.defaultMode)}`;
-  }
-
   if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
     return "enabled must be a boolean";
   }
@@ -239,24 +225,6 @@ function validateCoreConfigFields(value) {
     return "conversationHistory must be a boolean";
   }
 
-  if (value.interactionContract !== undefined && typeof value.interactionContract !== "boolean") {
-    return "interactionContract must be a boolean";
-  }
-
-  if (value.skills !== undefined) {
-    if (!isRecord(value.skills)) {
-      return "skills must be an object";
-    }
-    for (const key of Object.keys(value.skills)) {
-      if (key !== "enabled") {
-        return `unsupported skills config key: ${key}`;
-      }
-    }
-    if (value.skills.enabled !== undefined && typeof value.skills.enabled !== "boolean") {
-      return "skills.enabled must be a boolean";
-    }
-  }
-
   return null;
 }
 
@@ -268,9 +236,6 @@ function validateFreeflowConfigShape(value) {
   // Keep retired capability keys shape-tolerated so existing repositories remain activated; runtime behavior ignores them.
   const allowedKeys = new Set([
     "enabled",
-    "defaultMode",
-    "interactionContract",
-    "skills",
     "outputRouter",
     "observedRouting",
     "scriptTransform",
@@ -303,9 +268,6 @@ function validateFreeflowLocalConfigShape(value) {
 
   const allowedKeys = new Set([
     "enabled",
-    "defaultMode",
-    "interactionContract",
-    "skills",
     "processing",
     "cognitiveRouting",
     "contextVirtualization",
@@ -387,30 +349,19 @@ function resolveLayeredValue(repository, local, key, fallback) {
 
 function resolveCoreConfig(repository, local) {
   const enabled = resolveLayeredValue(repository, local, "enabled", true);
-  const interactionContract = resolveLayeredValue(repository, local, "interactionContract", true);
   const contextVirtualization = resolveLayeredValue(repository, local, "contextVirtualization", false);
   const conversationHistory = resolveLayeredValue(repository, local, "conversationHistory", false);
-  const defaultMode = resolveLayeredValue(repository, local, "defaultMode", "workflow");
-  const repositorySkills = isRecord(repository.skills) ? repository.skills : {};
-  const localSkills = isRecord(local.skills) ? local.skills : {};
-  const skillsEnabled = resolveLayeredValue(repositorySkills, localSkills, "enabled", true);
 
   return {
     config: {
       enabled: enabled.value,
-      interactionContract: interactionContract.value,
       contextVirtualization: contextVirtualization.value,
       conversationHistory: conversationHistory.value,
-      skills: { enabled: skillsEnabled.value },
-      defaultMode: defaultMode.value,
     },
     sources: {
       enabled: enabled.source,
-      interactionContract: interactionContract.source,
       contextVirtualization: contextVirtualization.source,
       conversationHistory: conversationHistory.source,
-      skillsEnabled: skillsEnabled.source,
-      defaultMode: defaultMode.source,
     },
   };
 }
@@ -430,30 +381,21 @@ function resolveSessionCoreConfig(layers) {
   const configured = layers.coreConfig;
   const sources = layers.sources;
   const enabled = currentSessionOverrides.enabled;
-  const interactionContract = currentSessionOverrides.interactionContract;
   const contextVirtualization = currentSessionOverrides.contextVirtualization;
   const conversationHistory = currentSessionOverrides.conversationHistory;
-  const skillsEnabled = currentSessionOverrides.skillsEnabled;
 
   return {
     config: {
       enabled: typeof enabled === "boolean" ? enabled : configured.enabled,
-      interactionContract:
-        typeof interactionContract === "boolean" ? interactionContract : configured.interactionContract,
       contextVirtualization:
         typeof contextVirtualization === "boolean" ? contextVirtualization : configured.contextVirtualization,
       conversationHistory:
         typeof conversationHistory === "boolean" ? conversationHistory : configured.conversationHistory,
-      skills: { enabled: typeof skillsEnabled === "boolean" ? skillsEnabled : configured.skills.enabled },
-      defaultMode: configured.defaultMode,
     },
     sources: {
       enabled: typeof enabled === "boolean" ? "session" : sources.enabled,
-      interactionContract: typeof interactionContract === "boolean" ? "session" : sources.interactionContract,
       contextVirtualization: typeof contextVirtualization === "boolean" ? "session" : sources.contextVirtualization,
       conversationHistory: typeof conversationHistory === "boolean" ? "session" : sources.conversationHistory,
-      skillsEnabled: typeof skillsEnabled === "boolean" ? "session" : sources.skillsEnabled,
-      defaultMode: sources.defaultMode,
     },
   };
 }
@@ -488,55 +430,27 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
   const layers = await readFreeflowConfigLayers(cwd);
   const effectiveCore = resolveSessionCoreConfig(layers);
   const enabled = layers.configured && effectiveCore.config.enabled;
-  const interactionContractConfigEnabled = effectiveCore.config.interactionContract;
-  const skillsConfigEnabled = effectiveCore.config.skills.enabled;
   const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
   const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
-  const skillsEffective = enabled && skillsConfigEnabled;
-  const hostSupportsCognitiveRouting = isPiFlowHost(extensionHost);
+  const hostSupportsCognitiveRouting = supportsCognitiveRoutingModelRegistry(host);
   const configuredCognitiveRouting = await resolveCognitiveRoutingState(
     layers.repository.parsed,
     layers.local.parsed,
     hostSupportsCognitiveRouting ? host : undefined,
   );
-  const disabledReason = enabled
-    ? skillsEffective
-      ? undefined
-      : { code: "disabled" as const, message: "Skills are disabled" }
-    : { code: "disabled" as const, message: "Freeflow is disabled" };
+  const disabledReason = enabled ? undefined : { code: "disabled" as const, message: "Freeflow is disabled" };
   const childCapability = (configuredEnabled) => ({
     enabled: configuredEnabled,
-    effective: skillsEffective && configuredEnabled,
+    effective: enabled && configuredEnabled,
     ...(disabledReason ? { blockingReason: disabledReason } : {}),
   });
   const cognitiveRouting = enabled
-    ? skillsEffective
-      ? !hostSupportsCognitiveRouting && configuredCognitiveRouting.configValid
-        ? {
-            ...configuredCognitiveRouting,
-            effective: false,
-            blockingReason: {
-              code: "runtime_disabled" as const,
-              message: "Cognitive Routing is disabled outside the PiFlow runtime",
-            },
-          }
-        : configuredCognitiveRouting
-      : {
-          ...configuredCognitiveRouting,
-          effective: false,
-          blockingReason: {
-            code: "disabled" as const,
-            message: "Skills are disabled",
-          },
-        }
+    ? configuredCognitiveRouting
     : {
         ...configuredCognitiveRouting,
         enabled: false,
         effective: false,
-        blockingReason: {
-          code: "disabled" as const,
-          message: "Freeflow is disabled",
-        },
+        blockingReason: disabledReason,
       };
   return {
     configured: layers.configured,
@@ -553,16 +467,7 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
     configuredSources: layers.sources,
     sessionOverrides: { ...currentSessionOverrides },
     configSources: effectiveCore.sources,
-    defaultMode: effectiveCore.config.defaultMode,
     enabled,
-    interactionContract: {
-      enabled: interactionContractConfigEnabled,
-      effective: enabled && interactionContractConfigEnabled,
-    },
-    skills: {
-      enabled: skillsConfigEnabled,
-      effective: enabled && skillsConfigEnabled,
-    },
     contextVirtualization: childCapability(contextVirtualizationConfigEnabled),
     conversationHistory: childCapability(conversationHistoryConfigEnabled),
     hostSupportsCognitiveRouting,
@@ -572,53 +477,23 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
 
 export const readRuntimeState = readCapabilityState;
 
-export function restoreModeOverride(ctx) {
-  currentModeOverride = null;
+export function restoreSessionOverrides(ctx) {
   currentSessionOverrides = {};
   const entries = ctx.sessionManager?.getBranch?.() ?? ctx.sessionManager?.getEntries?.() ?? [];
 
   for (const entry of entries) {
-    if (entry.type !== "custom") continue;
-    if (entry.customType === MODE_STATE_ENTRY) {
-      const mode = entry.data?.currentMode;
-      currentModeOverride = VALID_MODES.has(mode) ? mode : null;
-    } else if (entry.customType === SESSION_OVERRIDES_ENTRY) {
+    if (entry.type === "custom" && entry.customType === SESSION_OVERRIDES_ENTRY) {
       currentSessionOverrides = normalizeSessionOverrides(entry.data?.overrides);
     }
   }
 }
 
-export async function readModeState(cwd) {
-  const layers = await readFreeflowConfigLayers(cwd);
-  const effectiveCore = resolveSessionCoreConfig(layers);
-  const repositoryDefaultMode = VALID_MODES.has(layers.repository.parsed.defaultMode)
-    ? layers.repository.parsed.defaultMode
-    : "workflow";
-  const personalDefaultMode = VALID_MODES.has(layers.local.parsed.defaultMode) ? layers.local.parsed.defaultMode : null;
-  const sessionMode = VALID_MODES.has(currentModeOverride) ? currentModeOverride : null;
-  const resolvedMode = sessionMode ?? effectiveCore.config.defaultMode;
-  const active = layers.configured && effectiveCore.config.enabled && effectiveCore.config.skills.enabled;
-
-  return {
-    repositoryDefaultMode,
-    repositoryDefaultModeSource: VALID_MODES.has(layers.repository.parsed.defaultMode) ? "repository" : "builtin",
-    personalDefaultMode,
-    defaultMode: effectiveCore.config.defaultMode,
-    defaultModeSource: effectiveCore.sources.defaultMode,
-    currentMode: sessionMode,
-    sessionMode,
-    resolvedMode,
-    active,
-    effectiveMode: active ? resolvedMode : null,
-  };
-}
-
-export function setModeStatus(
+export function setFreeflowStatus(
   ctx,
-  modeState,
   capabilityState = undefined,
   cognitiveRoutingRuntime = undefined,
-  options: { cognitiveRoutingStartupPending?: boolean } = {},
+  freeflowContext = undefined,
+  options: { cognitiveRoutingStartupPending?: boolean; startupSelectionSuppressed?: boolean } = {},
 ) {
   if (capabilityState && !capabilityState.configured) {
     ctx.ui.setStatus("freeflow", capabilityState.configExists ? "freeflow: config error" : "freeflow: setup needed");
@@ -629,23 +504,26 @@ export function setModeStatus(
     ctx.ui.setStatus("freeflow", `freeflow: off${source}`);
     return;
   }
+  if (capabilityState?.enabled === true && !hasUsableMandatoryPrompts(freeflowContext)) {
+    ctx.ui.setStatus("freeflow", "freeflow: unavailable");
+    return;
+  }
 
   const active: string[] = [];
-  if (capabilityState?.interactionContract.effective) {
-    active.push("interaction");
-  } else if (capabilityState?.configSources?.interactionContract === "session") {
-    active.push("interaction off (session)");
-  }
-  if (capabilityState?.skills.effective) {
-    active.push(`${modeState.effectiveMode}${modeState.currentMode ? " (session)" : ""}`);
-  } else if (capabilityState?.configSources?.skillsEnabled === "session") {
-    active.push("skills off (session)");
-  }
   const cognitiveRouting = capabilityState?.cognitiveRouting;
+  const cognitiveRoutingInactive =
+    cognitiveRouting?.enabled === true && cognitiveRoutingRuntime?.runtimeStatus === "inactive";
+  const cognitiveRoutingBlocked =
+    cognitiveRouting?.enabled === true &&
+    (cognitiveRouting?.blockingReason?.code === "runtime_blocked" ||
+      cognitiveRoutingRuntime?.runtimeStatus === "blocked");
   const cognitiveRoutingActive = cognitiveRouting?.effective === true && cognitiveRoutingRuntime?.effective === true;
-  const startupSelectionSuppressesCognitiveRouting =
-    ctx?.modelStateProvenance?.explicitModel === true || ctx?.modelStateProvenance?.explicitThinking === true;
-  if (cognitiveRoutingActive) {
+  const startupSelectionSuppressesCognitiveRouting = options.startupSelectionSuppressed === true;
+  if (cognitiveRoutingInactive) {
+    active.push("cognitive inactive");
+  } else if (cognitiveRoutingBlocked) {
+    active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
+  } else if (cognitiveRoutingActive) {
     const profile = cognitiveRoutingRuntime.activeProfile;
     const control =
       cognitiveRoutingRuntime.controlMode === "manual-standard" ||
@@ -655,18 +533,21 @@ export function setModeStatus(
     active.push(`${profile} · ${control}`);
   } else if (cognitiveRouting?.enabled === true) {
     if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
-      active.push("cognitive disabled · PiFlow only");
+      active.push("cognitive blocked · runtime_disabled");
     } else if (
       cognitiveRouting.effective === true &&
       cognitiveRoutingRuntime === undefined &&
       options.cognitiveRoutingStartupPending === true &&
       !startupSelectionSuppressesCognitiveRouting
     ) {
-      const startupProfile = cognitiveRouting.sessionStart?.profile ?? "standard";
+      const startupProfile =
+        cognitiveRouting.sessionStart?.control === "manual"
+          ? (cognitiveRouting.sessionStart.profile ?? "reasoning")
+          : "reasoning";
       active.push(`${startupProfile} · pending`);
     } else {
       const reason =
-        cognitiveRouting?.effective === true
+        cognitiveRouting.effective === true
           ? (cognitiveRoutingRuntime?.blockingReason?.code ?? "runtime_inactive")
           : (cognitiveRouting.blockingReason?.code ?? "unavailable");
       active.push(`cognitive blocked · ${reason}`);
@@ -675,21 +556,7 @@ export function setModeStatus(
   if (capabilityState?.contextVirtualization?.effective || capabilityState?.conversationHistory?.effective) {
     active.push("context");
   }
-  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "idle"}`);
-}
-
-function modeSourceLabel(source) {
-  if (source === "local") return "personal override";
-  if (source === "repository") return "repository default";
-  return "built-in default";
-}
-
-function describeModeState(modeState) {
-  const configuredDefault = `configured default ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)})`;
-  if (modeState.sessionMode) {
-    return `session ${modeState.sessionMode}; ${configuredDefault}`;
-  }
-  return configuredDefault;
+  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "active"}`);
 }
 
 export function skillPrompt(skill, args) {
@@ -699,6 +566,8 @@ export function skillPrompt(skill, args) {
 
 type CognitiveRoutingRuntimeSnapshot = {
   effective?: boolean;
+  runtimeStatus?: "active" | "inactive" | "blocked";
+  runtimeReason?: unknown;
   activeProfile?: unknown;
   controlMode?: unknown;
 };
@@ -727,10 +596,15 @@ function publicCapabilityStatus(capability) {
   return "inactive";
 }
 
+function publicCognitiveRoutingStatus(capability, runtime) {
+  if (runtime?.runtimeStatus === "inactive") return "inactive";
+  return publicCapabilityStatus(capability);
+}
+
 export function freeflowRuntimeStateMessage(
-  modeState,
   capabilityState,
   cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
+  freeflowContext = undefined,
 ) {
   const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
   const profile = publicCognitiveRoutingProfile(
@@ -739,8 +613,16 @@ export function freeflowRuntimeStateMessage(
   );
   const control =
     profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
-  const defaultMode = modeState?.defaultMode ?? "workflow";
-  const activeMode = modeState?.effectiveMode ?? "inactive";
+  const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
+  const freeflowStatus = capabilityState?.configured
+    ? capabilityState.enabled
+      ? mandatoryPromptAvailable
+        ? "active"
+        : "unavailable"
+      : "inactive"
+    : capabilityState?.configExists
+      ? "config error"
+      : "setup needed";
 
   return {
     role: "custom",
@@ -750,15 +632,12 @@ export function freeflowRuntimeStateMessage(
       "",
       "This is extension-generated runtime state. Use it to interpret the stable Freeflow guidance.",
       "",
-      `Default mode: \`${defaultMode}\``,
-      `Active mode: \`${activeMode}\``,
+      `Freeflow: ${freeflowStatus}`,
       "",
       "Capabilities:",
-      `- Interaction Contract: ${publicCapabilityStatus(capabilityState?.interactionContract)}`,
-      `- Skills: ${publicCapabilityStatus(capabilityState?.skills)}`,
       `- Context Virtualization: ${publicCapabilityStatus(capabilityState?.contextVirtualization)}`,
       `- Conversation History: ${publicCapabilityStatus(capabilityState?.conversationHistory)}`,
-      `- Cognitive Routing: ${publicCapabilityStatus(capabilityState?.cognitiveRouting)}`,
+      `- Cognitive Routing: ${publicCognitiveRoutingStatus(capabilityState?.cognitiveRouting, cognitiveRoutingRuntime)}`,
       "",
       "Cognitive Routing:",
       `- Control: \`${control}\``,
@@ -777,38 +656,75 @@ export function withoutFreeflowRuntimeState(messages: readonly FreeflowContextMe
   );
 }
 
+function lastUserMessageIndex(messages: readonly FreeflowContextMessage[]): number {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+
+function insertRuntimeStateBeforeLatestUser(
+  messages: readonly FreeflowContextMessage[],
+  runtimeState: FreeflowContextMessage,
+): FreeflowContextMessage[] {
+  const latestUserIndex = lastUserMessageIndex(messages);
+  if (latestUserIndex < 0) return [...messages, runtimeState];
+  return [...messages.slice(0, latestUserIndex), runtimeState, ...messages.slice(latestUserIndex)];
+}
+
 export function withFreeflowRuntimeState(
   messages: readonly FreeflowContextMessage[] | undefined,
-  modeState,
   capabilityState,
   cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
+  freeflowContext = undefined,
+  options: { force?: boolean } = {},
 ) {
-  return [
-    ...withoutFreeflowRuntimeState(messages),
-    freeflowRuntimeStateMessage(modeState, capabilityState, cognitiveRoutingRuntime),
-  ];
+  const source = Array.isArray(messages) ? messages : [];
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext);
+  const runtimeStateMessages = source.filter(
+    (message) =>
+      message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE ||
+      message?.customType === COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
+  const withoutRuntimeState = withoutFreeflowRuntimeState(source);
+  const expectedRuntimeStateIndex = lastUserMessageIndex(withoutRuntimeState);
+  const runtimeStateIndex = source.findIndex((message) => message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE);
+  const unchanged =
+    options.force !== true &&
+    runtimeStateMessages.length === 1 &&
+    runtimeStateMessages[0]?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+    runtimeStateMessages[0]?.content === runtimeState.content &&
+    runtimeStateIndex === (expectedRuntimeStateIndex < 0 ? withoutRuntimeState.length : expectedRuntimeStateIndex);
+  if (unchanged) return source;
+  return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
 }
 
 export function runtimeContext(freeflowContext, capabilityState) {
-  if (capabilityState?.configured !== true || capabilityState?.enabled !== true || !freeflowContext?.corePrompt) {
+  if (
+    capabilityState?.configured !== true ||
+    capabilityState?.enabled !== true ||
+    !hasUsableMandatoryPrompts(freeflowContext)
+  ) {
     return "";
   }
 
-  const blocks = [];
-  if (freeflowContext?.corePrompt) blocks.push(freeflowContext.corePrompt.trim());
-  if (capabilityState.interactionContract?.effective === true && freeflowContext?.interactionContractPrompt) {
-    blocks.push(freeflowContext.interactionContractPrompt.trim());
-  }
-  if (capabilityState.skills?.effective === true && freeflowContext?.skillsPrompt) {
-    blocks.push(freeflowContext.skillsPrompt.trim());
-  }
-  if (capabilityState.cognitiveRouting?.effective === true && freeflowContext?.cognitiveRoutingPrompt) {
+  const blocks = [freeflowContext.corePrompt.trim(), freeflowContext.interactionContractPrompt.trim()];
+  if (
+    capabilityState.cognitiveRouting?.effective === true &&
+    isPromptAvailable(freeflowContext.cognitiveRoutingPrompt)
+  ) {
     blocks.push(freeflowContext.cognitiveRoutingPrompt.trim());
   }
-  if (capabilityState.contextVirtualization?.effective === true && freeflowContext?.contextVirtualizationPrompt) {
+  if (
+    capabilityState.contextVirtualization?.effective === true &&
+    isPromptAvailable(freeflowContext.contextVirtualizationPrompt)
+  ) {
     blocks.push(freeflowContext.contextVirtualizationPrompt.trim());
   }
-  if (capabilityState.conversationHistory?.effective === true && freeflowContext?.conversationHistoryPrompt) {
+  if (
+    capabilityState.conversationHistory?.effective === true &&
+    isPromptAvailable(freeflowContext.conversationHistoryPrompt)
+  ) {
     blocks.push(freeflowContext.conversationHistoryPrompt.trim());
   }
   return blocks.filter(Boolean).join("\n\n");
@@ -837,7 +753,7 @@ export async function setSessionCoreOverride(key: SessionCoreKey, value: boolean
   pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...currentSessionOverrides } });
   return {
     changed: true,
-    reloadRequired: key === "enabled" || key === "skillsEnabled",
+    reloadRequired: key === "enabled",
     sessionOverrides: { ...currentSessionOverrides },
     capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
@@ -845,109 +761,17 @@ export async function setSessionCoreOverride(key: SessionCoreKey, value: boolean
 
 export async function resetSessionOverrides(ctx, pi) {
   const hadCoreOverrides = Object.keys(currentSessionOverrides).length > 0;
-  const reloadRequired =
-    Object.hasOwn(currentSessionOverrides, "enabled") || Object.hasOwn(currentSessionOverrides, "skillsEnabled");
-  const hadModeOverride = VALID_MODES.has(currentModeOverride);
+  const reloadRequired = Object.hasOwn(currentSessionOverrides, "enabled");
 
   if (hadCoreOverrides) {
     currentSessionOverrides = {};
     pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: {} });
   }
-  if (hadModeOverride) {
-    await setSessionMode(null, ctx, pi);
-  }
 
   return {
-    changed: hadCoreOverrides || hadModeOverride,
+    changed: hadCoreOverrides,
     reloadRequired,
     sessionOverrides: { ...currentSessionOverrides },
-    modeState: await readModeState(ctx.cwd),
+    capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
-
-export async function setSessionMode(mode, ctx, pi) {
-  const nextMode = mode === "default" || mode === "reset" || mode === null ? null : mode;
-  if (nextMode !== null && !VALID_MODES.has(nextMode)) {
-    throw new Error(`Invalid Freeflow mode: ${String(mode)}`);
-  }
-  currentModeOverride = nextMode;
-  pi?.appendEntry?.(MODE_STATE_ENTRY, { currentMode: nextMode });
-  return readModeState(ctx.cwd);
-}
-
-export async function handleModeCommand(args, ctx, pi) {
-  const arg = args?.trim();
-  const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
-  const inactiveModeState = await readModeState(ctx.cwd);
-
-  if (!capabilityState.configured) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is installed but this repo is not set up. Run /setup-freeflow before changing mode.",
-      "warning",
-    );
-    return { changed: false, error: "not_configured" };
-  }
-  if (!capabilityState.enabled) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is disabled for this repo. Use /freeflow enable or /freeflow settings to re-enable it.",
-      "warning",
-    );
-    return { changed: false, error: "freeflow_disabled" };
-  }
-  if (!capabilityState.skills.effective) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow modes are inactive because Skills are disabled. Configured default mode: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). Enable Skills in /freeflow settings before changing mode.`,
-      "warning",
-    );
-    return { changed: false, error: "skills_disabled" };
-  }
-
-  if (VALID_MODES.has(arg)) {
-    if (inactiveModeState.effectiveMode === arg) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      const message = inactiveModeState.sessionMode
-        ? `Freeflow is already in ${arg} mode for this Pi session. No session entry was added. Configured default remains ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}).`
-        : `Freeflow is already in ${arg} mode from the configured default (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override was created.`;
-      ctx.ui.notify(message, "info");
-      return { changed: false, modeState: inactiveModeState };
-    }
-
-    const modeState = await setSessionMode(arg, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode is now ${modeState.effectiveMode} for this Pi session. Stored in Pi session history; .freeflow/local.json and .freeflow/config.json were not changed. Configured default remains ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}).`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-
-  if (RESET_MODE_ARGS.has(arg) || arg === "default") {
-    if (!inactiveModeState.sessionMode) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      ctx.ui.notify(
-        `Freeflow is already using the configured default: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override is active.`,
-        "info",
-      );
-      return { changed: false, modeState: inactiveModeState };
-    }
-
-    const modeState = await setSessionMode(null, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode reset to configured default: ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}). Session override cleared; .freeflow/local.json and .freeflow/config.json were not changed.`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-
-  const modeState = await readModeState(ctx.cwd);
-  setModeStatus(ctx, modeState, capabilityState);
-  ctx.ui.notify(
-    `Freeflow mode is ${modeState.effectiveMode} (${describeModeState(modeState)}). Use /freeflow mode conversation, /freeflow mode workflow, /freeflow mode strict-workflow, or /freeflow mode reset.`,
-    "info",
-  );
-  return { changed: false, modeState, error: arg ? "invalid_mode" : undefined };
-}