@hassangameryt/freeflow 0.5.0 → 0.7.0

package/pi-extension/src/settings/settings-ui.ts

@@ -4,53 +4,33 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 
 import {
-  DEFAULT_OBSERVED_ROUTING_CONFIG,
-  DEFAULT_OUTPUT_ROUTER_ENABLED,
-  DEFAULT_POST_TOOL_ROUTING,
-  DEFAULT_ROUTER_THRESHOLDS,
-  DEFAULT_SCRIPT_TRANSFORM_CONFIG,
-  DEFAULT_STORAGE_POLICY,
-  DEFAULT_VAULT_RETENTION,
-  DEFAULT_VAULT_ROOT,
-  normalizeFreeflowConfig,
-} from "../../../router/dist/index.js";
-import {
-  handleModeCommand,
   readCapabilityState,
   readFreeflowConfig,
   readFreeflowConfigLayers,
   readFreeflowLocalConfig,
-  readModeState,
   resetSessionOverrides,
   setSessionCoreOverride,
-  VALID_MODES,
 } from "../runtime/runtime-context.js";
 import {
   PiSettingsComponent,
   type SettingsCommitResult,
   type SettingsEntry,
   type SettingsSessionResult,
+  type SettingsWizard,
+  type SettingsWizardStep,
 } from "./settings-tui.js";
+import { supportsPiSessionModelStateApi } from "../cognitive-routing/pi-session-control.js";
+import { isPiFlowHost } from "../runtime/runtime-identity.js";
+import type {
+  CognitiveRoutingCapabilityState,
+  CognitiveRoutingProfile,
+  CognitiveRoutingProfileName,
+  CognitiveRoutingThinkingLevel,
+} from "../cognitive-routing/types.js";
 
-const POST_TOOL_ROUTING_VALUES = ["off", "safety-net", "strict"] as const;
-const STORAGE_POLICY_VALUES = ["hybrid-dedupe", "store-everything"] as const;
-const OBSERVED_PERSISTENCE_VALUES = ["none", "metadata-only", "exact"] as const;
-const SCRIPT_LANGUAGES = ["javascript", "python", "jq"] as const;
 const DEFAULT_FREEFLOW_ENABLED = true;
-const DEFAULT_INTERACTION_CONTRACT_ENABLED = true;
-const DEFAULT_SKILLS_ENABLED = true;
-const MODE_VALUES = ["conversation", "workflow", "strict-workflow"];
-const MODE_LABELS = {
-  default: "Use configured default",
-  conversation: "conversation",
-  workflow: "workflow",
-  "strict-workflow": "strict-workflow",
-};
-const MODE_DESCRIPTIONS = {
-  conversation: "Discussion and read-only inspection",
-  workflow: "Adaptive workflow for consequential work",
-  "strict-workflow": "Stronger decision and evidence pressure for high-risk work",
-};
+const DEFAULT_CONTEXT_VIRTUALIZATION_ENABLED = false;
+const DEFAULT_CONVERSATION_HISTORY_ENABLED = false;
 const LOCAL_INHERIT = "inherit";
 const execFileAsync = promisify(execFile);
 
@@ -58,6 +38,7 @@ type ConfigScope = "session" | "local" | "repository";
 type ConfigSource = "session" | "local" | "repository" | "builtin";
 
 type SettingKind = "boolean" | "enum" | "integer" | "string" | "list" | "json" | "group";
+type SettingsValue = boolean | number | string | null | SettingsValue[] | { [key: string]: SettingsValue };
 
 type SettingsItem = {
   id: string;
@@ -71,8 +52,10 @@ type SettingsItem = {
   valueLabels?: Record<string, string>;
   valueDescriptions?: Record<string, string>;
   inactive?: boolean;
+  runtimeInactive?: boolean;
   displaySuffix?: string;
   children?: SettingsItem[];
+  wizard?: () => SettingsWizard;
   parse?: (text: string) => unknown;
   format?: (value: unknown) => string;
   configScope?: ConfigScope;
@@ -85,6 +68,18 @@ type SettingsItem = {
   transient?: boolean;
 };
 
+type CognitiveRoutingSettingsController = {
+  state(): { effective: boolean; controlMode: string; activeProfile?: string };
+  setManualProfile(profile: "standard" | "reasoning", mechanism?: string): Promise<{ status: string; reason?: string }>;
+  setAutomaticControl(mechanism?: string): Promise<{ status: string; reason?: string }>;
+};
+
+type AfterChangeOptions = {
+  reconcileCognitiveRouting?: boolean;
+};
+
+type AfterChange = (changed: boolean, options?: AfterChangeOptions) => Promise<void> | void;
+
 type OpenSettingsOptions = {
   title: string;
   items: SettingsItem[];
@@ -106,13 +101,13 @@ function cloneJson<T>(value: T): T {
   }
 }
 
-function getPath(source: unknown, path: string[]): unknown {
-  let current = source;
+function getPath(source: unknown, path: string[]): SettingsValue | undefined {
+  let current: unknown = source;
   for (const key of path) {
     if (!isRecord(current)) return undefined;
-    current = current[key];
+    current = current[key] as SettingsValue | undefined;
   }
-  return current;
+  return current as SettingsValue | undefined;
 }
 
 function setPath(target: Record<string, unknown>, path: string[], value: unknown) {
@@ -170,318 +165,29 @@ function setConfigValue(config: Record<string, unknown>, item: SettingsItem, val
   setPath(config, item.path, value);
 }
 
-function parseStringList(text: string): string[] {
-  return text
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
-function parsePositiveInteger(text: string): number {
-  const value = Number(text.trim());
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new Error("Expected a positive integer.");
-  }
-  return value;
-}
-
-function parseJsonObject(text: string): unknown {
-  const trimmed = text.trim();
-  if (!trimmed) return {};
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch (error) {
-    throw new Error(`Expected valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  if (!isRecord(parsed)) {
-    throw new Error("Expected a JSON object.");
-  }
-  return parsed;
-}
-
-function formatList(value: unknown): string {
-  return Array.isArray(value) ? value.join(", ") : "";
-}
-
-function formatJson(value: unknown): string {
-  return JSON.stringify(isRecord(value) ? value : {});
-}
-
 function booleanValue(value: unknown): string {
   return value === true ? "enabled" : "disabled";
 }
 
-function normalizedSettingsConfig(rawConfig: Record<string, unknown>) {
-  const rawRouter = isRecord(rawConfig.outputRouter) ? rawConfig.outputRouter : {};
-  const normalized = normalizeFreeflowConfig({
-    ...rawConfig,
-    outputRouter: { ...rawRouter, enabled: true },
-  });
-  return normalized.config;
-}
-
-function rawValue(rawConfig: Record<string, unknown>, path: string[], fallback: unknown): unknown {
-  const value = getPath(rawConfig, path);
-  return value === undefined ? fallback : value;
-}
-
-function outputRouterItems(rawConfig: Record<string, unknown>, freeflowInactive = false): SettingsItem[] {
-  const effective = normalizedSettingsConfig(rawConfig);
-  const routerEnabled = normalizeFreeflowConfig(rawConfig).config.outputRouter.enabled;
-  const router = effective.outputRouter;
-  const scriptTransform = effective.scriptTransform;
-  const observedRouting = effective.observedRouting;
-  const inactive = freeflowInactive || !routerEnabled;
-
-  return [
-    {
-      id: "outputRouter.enabled",
-      label: "Output Router",
-      description: "Master switch for Freeflow routed evidence tools and router runtime guidance.",
-      path: ["outputRouter", "enabled"],
-      kind: "boolean",
-      value: routerEnabled,
-      defaultValue: DEFAULT_OUTPUT_ROUTER_ENABLED,
-      inactive: freeflowInactive,
-    },
-    {
-      id: "outputRouter.postToolRouting",
-      label: "Native safety net",
-      description:
-        "Post-process large/noisy native read/bash output. safety-net can replace oversized native output with vaulted routed evidence; strict is stronger.",
-      path: ["outputRouter", "postToolRouting"],
-      kind: "enum",
-      value: router.postToolRouting,
-      values: [...POST_TOOL_ROUTING_VALUES],
-      valueDescriptions: {
-        off: "Leave native tool output unchanged",
-        "safety-net": "Route oversized or noisy native output",
-        strict: "Apply stronger native output routing",
-      },
-      defaultValue: DEFAULT_POST_TOOL_ROUTING,
-      inactive,
-    },
-    {
-      id: "outputRouter.storagePolicy",
-      label: "Storage policy",
-      description: "Vault storage behavior for exactness-sensitive and noisy output.",
-      path: ["outputRouter", "storagePolicy"],
-      kind: "enum",
-      value: router.storagePolicy,
-      values: [...STORAGE_POLICY_VALUES],
-      defaultValue: DEFAULT_STORAGE_POLICY,
-      inactive,
-    },
-    {
-      id: "outputRouter.thresholds.largeOutputBytes",
-      label: "Large output bytes",
-      description: "Byte threshold for treating command/tool output as large.",
-      path: ["outputRouter", "thresholds", "largeOutputBytes"],
-      kind: "integer",
-      value: router.thresholds.largeOutputBytes,
-      defaultValue: DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.thresholds.largeOutputLines",
-      label: "Large output lines",
-      description: "Line threshold for treating command/tool output as large.",
-      path: ["outputRouter", "thresholds", "largeOutputLines"],
-      kind: "integer",
-      value: router.thresholds.largeOutputLines,
-      defaultValue: DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.vault.root",
-      label: "Vault root",
-      description: "Root directory for recoverable routed output.",
-      path: ["outputRouter", "vault", "root"],
-      kind: "string",
-      value: router.vault.root,
-      defaultValue: DEFAULT_VAULT_ROOT,
-      inactive,
-    },
-    {
-      id: "outputRouter.vault.retention.ttlDays",
-      label: "Vault retention days",
-      description: "TTL retention for vaulted output. Set a positive integer; default is 7 days.",
-      path: ["outputRouter", "vault", "retention", "ttlDays"],
-      kind: "integer",
-      value:
-        router.vault.retention?.strategy === "ttl" ? router.vault.retention.ttlDays : DEFAULT_VAULT_RETENTION.ttlDays,
-      defaultValue: DEFAULT_VAULT_RETENTION.ttlDays,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.generatedPaths",
-      label: "Generated paths",
-      description:
-        "Comma-separated globs for generated repo paths that should be treated as noisy or lower-priority evidence.",
-      path: ["outputRouter", "hints", "generatedPathGlobs"],
-      kind: "list",
-      value: rawValue(
-        rawConfig,
-        ["outputRouter", "hints", "generatedPathGlobs"],
-        rawValue(rawConfig, ["outputRouter", "generatedPaths"], router.hints?.generatedPathGlobs ?? []),
-      ),
-      format: formatList,
-      parse: parseStringList,
-      inactive,
-    },
-    {
-      id: "outputRouter.noisyCommandHints",
-      label: "Noisy command hints",
-      description: "Comma-separated command patterns that are likely to produce noisy output.",
-      path: ["outputRouter", "hints", "noisyCommandPatterns"],
-      kind: "list",
-      value: rawValue(
-        rawConfig,
-        ["outputRouter", "hints", "noisyCommandPatterns"],
-        rawValue(rawConfig, ["outputRouter", "noisyCommandHints"], router.hints?.noisyCommandPatterns ?? []),
-      ),
-      format: formatList,
-      parse: parseStringList,
-      inactive,
-    },
-    {
-      id: "outputRouter.scriptTransform.enabled",
-      label: "Script transform",
-      description:
-        "Enable sandboxed script transforms/producers. Requires proof-backed adapters; no unsandboxed fallback.",
-      path: ["outputRouter", "scriptTransform", "enabled"],
-      kind: "boolean",
-      value: scriptTransform.enabled,
-      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.enabled,
-      inactive,
-    },
-    {
-      id: "outputRouter.scriptTransform.languages",
-      label: "Script languages",
-      description: "Comma-separated sandbox languages to allow: javascript, python, jq.",
-      path: ["outputRouter", "scriptTransform", "languages"],
-      kind: "list",
-      value: scriptTransform.languages,
-      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.languages,
-      format: formatList,
-      parse: (text) => parseStringList(text).filter((value) => (SCRIPT_LANGUAGES as readonly string[]).includes(value)),
-      inactive,
-    },
-    {
-      id: "outputRouter.scriptTransform.limits.timeoutMs",
-      label: "Script timeout ms",
-      description: "Maximum sandboxed script execution time.",
-      path: ["outputRouter", "scriptTransform", "limits", "timeoutMs"],
-      kind: "integer",
-      value: scriptTransform.limits.timeoutMs,
-      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.timeoutMs,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.scriptTransform.limits.maxInputBytes",
-      label: "Script max input bytes",
-      description: "Maximum input size for sandboxed scripts.",
-      path: ["outputRouter", "scriptTransform", "limits", "maxInputBytes"],
-      kind: "integer",
-      value: scriptTransform.limits.maxInputBytes,
-      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxInputBytes,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.scriptTransform.limits.maxOutputBytes",
-      label: "Script max output bytes",
-      description: "Maximum output size for sandboxed scripts.",
-      path: ["outputRouter", "scriptTransform", "limits", "maxOutputBytes"],
-      kind: "integer",
-      value: scriptTransform.limits.maxOutputBytes,
-      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxOutputBytes,
-      parse: parsePositiveInteger,
-      inactive,
-    },
-    {
-      id: "outputRouter.observedRouting.enabled",
-      label: "Observed routing",
-      description: "Route configured host tool results after they run, e.g. MCP/web/fetch/code-search output.",
-      path: ["outputRouter", "observedRouting", "enabled"],
-      kind: "boolean",
-      value: observedRouting.enabled,
-      defaultValue: DEFAULT_OBSERVED_ROUTING_CONFIG.enabled,
-      inactive,
-    },
-    ...observedProducerItems("web", "Web search", observedRouting.web, inactive),
-    ...observedProducerItems("fetch", "Fetch content", observedRouting.fetch, inactive),
-    ...observedProducerItems("codeSearch", "Code search", observedRouting.codeSearch, inactive),
-    {
-      id: "outputRouter.observedRouting.mcp.servers",
-      label: "MCP servers JSON",
-      description: 'JSON object keyed by MCP server id. Example: {"github":{"enabled":true,"persistence":"exact"}}',
-      path: ["outputRouter", "observedRouting", "mcp", "servers"],
-      kind: "json",
-      value: observedRouting.mcp?.servers ?? {},
-      defaultValue: DEFAULT_OBSERVED_ROUTING_CONFIG.mcp.servers,
-      format: formatJson,
-      parse: parseJsonObject,
-      inactive,
-    },
-  ];
-}
-
-function observedProducerItems(
-  id: "web" | "fetch" | "codeSearch",
-  label: string,
-  value: any,
-  inactive: boolean,
-): SettingsItem[] {
-  return [
-    {
-      id: `outputRouter.observedRouting.${id}.enabled`,
-      label: `${label} observed`,
-      description: `Enable observed routing for ${label.toLowerCase()} output.`,
-      path: ["outputRouter", "observedRouting", id, "enabled"],
-      kind: "boolean",
-      value: value?.enabled === true,
-      defaultValue: false,
-      inactive,
-    },
-    {
-      id: `outputRouter.observedRouting.${id}.persistence`,
-      label: `${label} persistence`,
-      description: "Persistence mode for this observed producer: none, metadata-only, or exact.",
-      path: ["outputRouter", "observedRouting", id, "persistence"],
-      kind: "enum",
-      value: value?.persistence ?? "none",
-      values: [...OBSERVED_PERSISTENCE_VALUES],
-      valueDescriptions: {
-        none: "Do not persist observed output",
-        "metadata-only": "Persist metadata without raw output",
-        exact: "Persist exact recoverable output",
-      },
-      defaultValue: value?.enabled === true ? undefined : "none",
-      inactive,
-    },
-  ];
-}
-
-function configValueForChoice(item: SettingsItem, value: unknown): unknown {
+function configValueForChoice(item: SettingsItem, value: unknown): SettingsValue | undefined {
   const key = String(value);
   if (item.configValues && Object.hasOwn(item.configValues, key)) {
-    return item.configValues[key];
+    return item.configValues[key] as SettingsValue | undefined;
   }
-  return value;
+  return value as SettingsValue | undefined;
 }
 
-function effectiveItemValue(item: SettingsItem): unknown {
-  return item.effectiveValue !== undefined ? item.effectiveValue : item.value;
+function effectiveItemValue(item: SettingsItem): SettingsValue | undefined {
+  return (item.effectiveValue === undefined ? item.value : item.effectiveValue) as SettingsValue | undefined;
 }
 
 function formatCoreValue(value: unknown): string {
-  return typeof value === "boolean" ? booleanValue(value) : String(value ?? "");
+  if (typeof value === "boolean") return booleanValue(value);
+  if (isRecord(value) && typeof value.provider === "string" && typeof value.model === "string") {
+    const effort = typeof value.thinkingLevel === "string" ? ` · ${value.thinkingLevel}` : "";
+    return `${value.provider}/${value.model}${effort}`;
+  }
+  return String(value ?? "");
 }
 
 function coreDisplaySuffix(item: SettingsItem, inactive = false): string {
@@ -585,120 +291,38 @@ function createScopedBooleanItem(options: ScopedBooleanItemOptions): SettingsIte
   return item;
 }
 
-type ScopedDefaultModeItemOptions = {
-  scope: ConfigScope;
-  repositoryDefaultMode: string;
-  repositoryDefaultSource: ConfigSource;
-  localDefaultMode?: string;
-  effectiveValue: string;
-  effectiveSource: ConfigSource;
-};
-
-function createScopedDefaultModeItem(options: ScopedDefaultModeItemOptions): SettingsItem {
-  let item: SettingsItem;
-  if (options.scope === "local") {
-    item = {
-      id: "freeflow.defaultMode",
-      label: "Default mode",
-      description:
-        "Personal default mode for this checkout. Choose inherit to use the repository default; use /freeflow settings repo to edit shared defaults.",
-      path: ["defaultMode"],
-      kind: "enum",
-      value: options.localDefaultMode ?? LOCAL_INHERIT,
-      values: [LOCAL_INHERIT, ...MODE_VALUES],
-      valueLabels: {
-        inherit: "Inherit repository",
-        ...MODE_LABELS,
-      },
-      valueDescriptions: {
-        inherit: `Use ${options.repositoryDefaultMode} from ${options.repositoryDefaultSource}.`,
-        ...MODE_DESCRIPTIONS,
-      },
-      format: (value) => String(value),
-      configScope: "local",
-      configValues: { inherit: undefined },
-      effectiveValue: options.effectiveValue,
-      effectiveSource: options.effectiveSource,
-      inheritedValue: options.repositoryDefaultMode,
-      inheritedSource: options.repositoryDefaultSource,
-    };
-  } else {
-    item = {
-      id: "freeflow.defaultMode",
-      label: "Default mode",
-      description:
-        "Shared repository default Freeflow mode used when Skills are enabled. This edits .freeflow/config.json.",
-      path: ["defaultMode"],
-      kind: "enum",
-      value: options.repositoryDefaultMode,
-      values: MODE_VALUES,
-      valueLabels: MODE_LABELS,
-      valueDescriptions: MODE_DESCRIPTIONS,
-      configScope: "repository",
-      effectiveValue: options.effectiveValue,
-      effectiveSource: options.effectiveSource,
-      localOverrideValue: options.localDefaultMode,
-    };
-  }
-  item.displaySuffix = coreDisplaySuffix(item);
-  return item;
-}
-
-function sessionModeDisplaySuffix(
-  sessionMode: string,
-  defaultMode: string,
-  defaultSource: ConfigSource,
-  inactive: boolean,
-): string | undefined {
-  if (sessionMode !== "default") return undefined;
-  const inactiveSuffix = inactive ? " · inactive" : "";
-  return `(${defaultMode} · ${defaultSource}${inactiveSuffix})`;
-}
-
-function validModeOrUndefined(value: unknown): string | undefined {
-  return typeof value === "string" && VALID_MODES.has(value) ? value : undefined;
-}
-
 function resolveSettingsCoreView(
   rawConfig: Record<string, unknown>,
   layers?: Awaited<ReturnType<typeof readFreeflowConfigLayers>>,
 ) {
   const localConfig = layers?.local.valid && isRecord(layers.local.parsed) ? layers.local.parsed : {};
-  const repositorySkillsValue = getPath(rawConfig, ["skills"]);
-  const repositorySkills = isRecord(repositorySkillsValue) ? repositorySkillsValue : {};
   const fallbackCore = {
     enabled: getPath(rawConfig, ["enabled"]) !== false,
-    interactionContract: getPath(rawConfig, ["interactionContract"]) !== false,
-    skills: { enabled: getPath(repositorySkills, ["enabled"]) !== false },
-    defaultMode: validModeOrUndefined(rawConfig.defaultMode) ?? "workflow",
+    contextVirtualization: getPath(rawConfig, ["contextVirtualization"]) === true,
+    conversationHistory: getPath(rawConfig, ["conversationHistory"]) === true,
   };
   const fallbackSources = {
     enabled: typeof getPath(rawConfig, ["enabled"]) === "boolean" ? "repository" : "builtin",
-    interactionContract: typeof getPath(rawConfig, ["interactionContract"]) === "boolean" ? "repository" : "builtin",
-    skillsEnabled: typeof getPath(repositorySkills, ["enabled"]) === "boolean" ? "repository" : "builtin",
-    defaultMode: validModeOrUndefined(rawConfig.defaultMode) !== undefined ? "repository" : "builtin",
+    contextVirtualization:
+      typeof getPath(rawConfig, ["contextVirtualization"]) === "boolean" ? "repository" : "builtin",
+    conversationHistory: typeof getPath(rawConfig, ["conversationHistory"]) === "boolean" ? "repository" : "builtin",
   } as const;
   return {
     localConfig,
     core: layers?.coreConfig ?? fallbackCore,
     sources: (layers?.sources ?? fallbackSources) as {
       enabled: ConfigSource;
-      interactionContract: ConfigSource;
-      skillsEnabled: ConfigSource;
-      defaultMode: ConfigSource;
+      contextVirtualization: ConfigSource;
+      conversationHistory: ConfigSource;
     },
   };
 }
 
-function groupEnabled(items: SettingsItem[], id: string): boolean {
-  return items.find((item) => item.id === id)?.value === true;
-}
-
 function createSessionBooleanItem(options: {
   id: string;
   label: string;
   description: string;
-  key: "enabled" | "interactionContract" | "skillsEnabled";
+  key: "enabled" | "contextVirtualization" | "conversationHistory";
   inheritedValue: boolean;
   inheritedSource: ConfigSource;
   effectiveValue: boolean;
@@ -744,19 +368,19 @@ function createSessionBooleanItem(options: {
 
 function sessionFreeflowItems(
   state: Awaited<ReturnType<typeof readCapabilityState>>,
-  modeState: Awaited<ReturnType<typeof readModeState>>,
+  cognitiveRoutingController?: CognitiveRoutingSettingsController,
 ): SettingsItem[] {
   const sessionOverrides = state.sessionOverrides as Record<string, boolean>;
   const configured = state.configuredCoreConfig;
   const configuredSources = state.configuredSources as {
     enabled: ConfigSource;
-    interactionContract: ConfigSource;
-    skillsEnabled: ConfigSource;
+    contextVirtualization: ConfigSource;
+    conversationHistory: ConfigSource;
   };
   const effectiveSources = state.configSources as {
     enabled: ConfigSource;
-    interactionContract: ConfigSource;
-    skillsEnabled: ConfigSource;
+    contextVirtualization: ConfigSource;
+    conversationHistory: ConfigSource;
   };
 
   const freeflowItem = createSessionBooleanItem({
@@ -770,70 +394,71 @@ function sessionFreeflowItems(
     effectiveSource: effectiveSources.enabled,
     sessionOverrides,
   });
-  const interactionItem = createSessionBooleanItem({
-    id: "freeflow.interactionContract",
-    label: "Interaction Contract",
-    description: "Temporary Interaction Contract override for this Pi session.",
-    key: "interactionContract",
-    inheritedValue: configured.interactionContract,
-    inheritedSource: configuredSources.interactionContract,
-    effectiveValue: state.interactionContract.enabled,
-    effectiveSource: effectiveSources.interactionContract,
+  const contextVirtualizationItem = createSessionBooleanItem({
+    id: "freeflow.contextVirtualization",
+    label: "Context Virtualization",
+    description: "Temporary Context Virtualization override for this Pi session.",
+    key: "contextVirtualization",
+    inheritedValue: configured.contextVirtualization,
+    inheritedSource: configuredSources.contextVirtualization,
+    effectiveValue: state.contextVirtualization.enabled,
+    effectiveSource: effectiveSources.contextVirtualization,
     sessionOverrides,
   });
-  const skillsItem = createSessionBooleanItem({
-    id: "freeflow.skills.enabled",
-    label: "Skills",
-    description: "Temporary Freeflow Skills override for this Pi session.",
-    key: "skillsEnabled",
-    inheritedValue: configured.skills.enabled,
-    inheritedSource: configuredSources.skillsEnabled,
-    effectiveValue: state.skills.enabled,
-    effectiveSource: effectiveSources.skillsEnabled,
+  const conversationHistoryItem = createSessionBooleanItem({
+    id: "freeflow.conversationHistory",
+    label: "Conversation History",
+    description: "Temporary Conversation History override for this Pi session.",
+    key: "conversationHistory",
+    inheritedValue: configured.conversationHistory,
+    inheritedSource: configuredSources.conversationHistory,
+    effectiveValue: state.conversationHistory.enabled,
+    effectiveSource: effectiveSources.conversationHistory,
     sessionOverrides,
   });
 
   const freeflowInactive = !state.enabled;
-  const skillsEnabled = state.skills.enabled;
-  interactionItem.inactive = freeflowInactive;
-  skillsItem.inactive = freeflowInactive;
-
-  const sessionMode = modeState.currentMode ?? "default";
-  const sessionModeItem: SettingsItem = {
-    id: "freeflow.sessionMode",
-    label: "Mode",
-    description: "Temporary mode override for this Pi session.",
-    kind: "enum",
-    value: sessionMode,
-    values: ["default", ...MODE_VALUES],
-    valueLabels: {
-      ...MODE_LABELS,
-      default: "Use configured default",
-    },
-    valueDescriptions: {
-      default: `${modeState.defaultMode} from ${modeState.defaultModeSource}`,
-      ...MODE_DESCRIPTIONS,
-    },
-    inactive: freeflowInactive || !skillsEnabled,
-    displaySuffix: sessionModeDisplaySuffix(
-      sessionMode,
-      modeState.defaultMode,
-      modeState.defaultModeSource,
-      freeflowInactive || !skillsEnabled,
-    ),
-    inheritedValue: modeState.defaultMode,
-    inheritedSource: modeState.defaultModeSource,
-  };
+  contextVirtualizationItem.inactive = freeflowInactive;
+  conversationHistoryItem.inactive = freeflowInactive;
+
+  const cognitiveRoutingState = cognitiveRoutingController?.state();
+  const cognitiveRoutingProfile =
+    cognitiveRoutingState?.controlMode === "manual-standard"
+      ? "standard"
+      : cognitiveRoutingState?.controlMode === "manual-reasoning"
+        ? "reasoning"
+        : "auto";
+  const cognitiveRoutingItem: SettingsItem | undefined = state.cognitiveRouting
+    ? {
+        id: "freeflow.cognitiveRouting.profile",
+        label: "Cognitive Routing",
+        description: "Hold a profile manually or release the hold for automatic model control.",
+        kind: "enum",
+        value: cognitiveRoutingProfile,
+        values: ["auto", "standard", "reasoning"],
+        valueLabels: {
+          auto: "automatic",
+          standard: "manual · standard",
+          reasoning: "manual · reasoning",
+        },
+        valueDescriptions: {
+          auto: "Release the manual hold without forcing a model transition.",
+          standard: "Hold the standard profile until /freeflow profile auto.",
+          reasoning: "Hold the reasoning profile until /freeflow profile auto.",
+        },
+        inactive: freeflowInactive || !state.cognitiveRouting.effective || cognitiveRoutingController === undefined,
+        runtimeInactive: state.cognitiveRouting.blockingReason?.code === "runtime_disabled",
+        displaySuffix: cognitiveRoutingState?.effective ? cognitiveRoutingProfile : "unavailable",
+      }
+    : undefined;
 
   return [
     freeflowItem,
-    interactionItem,
-    skillsItem,
-    sessionModeItem,
+    ...(cognitiveRoutingItem ? [cognitiveRoutingItem] : []),
     {
       id: "freeflow.session.reset",
       label: "Reset session overrides",
-      description: "Clear Freeflow, Interaction Contract, Skills, and mode overrides for this Pi session.",
+      description: "Clear Freeflow, Context Virtualization, and Conversation History overrides for this Pi session.",
       kind: "enum",
       value: "available",
       values: ["reset"],
@@ -842,15 +467,370 @@ function sessionFreeflowItems(
       format: () => "available",
       transient: true,
     },
+    {
+      id: "freeflow.context",
+      label: "Freeflow Context",
+      description: "Choose which context projection and conversation-history operations are available to the model.",
+      kind: "group",
+      value: contextVirtualizationItem.effectiveValue === true || conversationHistoryItem.effectiveValue === true,
+      displaySuffix: `${[contextVirtualizationItem, conversationHistoryItem].filter((item) => item.effectiveValue === true).length}/2 enabled`,
+      children: [contextVirtualizationItem, conversationHistoryItem],
+    },
+  ];
+}
+
+const COGNITIVE_ROUTING_THINKING_LEVELS: CognitiveRoutingThinkingLevel[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+const COGNITIVE_ROUTING_EFFORT_DESCRIPTIONS: Record<CognitiveRoutingThinkingLevel, string> = {
+  off: "No reasoning",
+  minimal: "Very brief reasoning",
+  low: "Light reasoning",
+  medium: "Moderate reasoning",
+  high: "Deep reasoning",
+  xhigh: "Extra-high reasoning",
+  max: "Maximum reasoning",
+};
+
+type CognitiveRoutingModelOption = {
+  key: string;
+  provider: string;
+  model: string;
+  label: string;
+  description: string;
+  thinkingLevels: CognitiveRoutingThinkingLevel[];
+};
+
+function cognitiveRoutingModelKey(provider: string, model: string): string {
+  return `${provider}/${model}`;
+}
+
+function isCognitiveRoutingProfile(value: unknown): value is CognitiveRoutingProfile {
+  return (
+    isRecord(value) &&
+    typeof value.provider === "string" &&
+    typeof value.model === "string" &&
+    typeof value.thinkingLevel === "string" &&
+    COGNITIVE_ROUTING_THINKING_LEVELS.includes(value.thinkingLevel as CognitiveRoutingThinkingLevel)
+  );
+}
+
+function cognitiveRoutingThinkingLevels(model: any, registry: any): CognitiveRoutingThinkingLevel[] {
+  if (typeof registry?.clampThinkingLevel !== "function") {
+    return model?.reasoning === true ? [...COGNITIVE_ROUTING_THINKING_LEVELS] : ["off"];
+  }
+  return COGNITIVE_ROUTING_THINKING_LEVELS.filter((level) => {
+    try {
+      return registry.clampThinkingLevel(model, level) === level;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function cognitiveRoutingModelOptions(ctx: any): CognitiveRoutingModelOption[] {
+  const registry = ctx?.modelRegistry;
+  if (typeof registry?.getAvailable !== "function") return [];
+  let models: any[];
+  try {
+    models = registry.getAvailable();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(models)) return [];
+
+  return models
+    .filter((model) => typeof model?.provider === "string" && typeof model?.id === "string")
+    .map((model) => {
+      const thinkingLevels = cognitiveRoutingThinkingLevels(model, registry);
+      const provider = model.provider as string;
+      const modelId = model.id as string;
+      const key = cognitiveRoutingModelKey(provider, modelId);
+      const displayName = typeof model.name === "string" && model.name !== modelId ? model.name : undefined;
+      return {
+        key,
+        provider,
+        model: modelId,
+        label: key,
+        description: displayName ? `${displayName} · ${thinkingLevels.join(", ")}` : thinkingLevels.join(", "),
+        thinkingLevels,
+      };
+    })
+    .filter((model) => model.thinkingLevels.length > 0)
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+function cognitiveRoutingProfileDisplay(value: unknown): string {
+  return isCognitiveRoutingProfile(value) ? formatCoreValue(value) : "not configured";
+}
+
+function cognitiveRoutingSettingsSource(source: unknown): ConfigSource {
+  if (source === "repository") return "repository";
+  if (source === "personal" || source === "local") return "local";
+  return "builtin";
+}
+
+function cognitiveRoutingProfileDisplaySuffix(source: unknown, scope: ConfigScope): string | undefined {
+  if (!source) return undefined;
+  if (source === "personal" && scope === "repository") return "(effective personal)";
+  return `(${source})`;
+}
+
+function cognitiveRoutingConfirmStep(summary: string): SettingsWizardStep {
+  return {
+    title: "Confirm preset",
+    choices: [
+      {
+        key: "__save__",
+        value: "save",
+        label: `Save ${summary}`,
+        description: "Write the complete profile atomically.",
+      },
+      { key: "__cancel__", value: "cancel", label: "Cancel", description: "Leave the previous preset unchanged." },
+    ],
+    selectedKey: "__save__",
+  };
+}
+
+function createCognitiveRoutingProfileWizard(
+  currentValue: unknown,
+  models: CognitiveRoutingModelOption[],
+  allowInherit: boolean,
+): SettingsWizard {
+  const currentProfile = isCognitiveRoutingProfile(currentValue) ? currentValue : undefined;
+  const currentModelKey = currentProfile
+    ? cognitiveRoutingModelKey(currentProfile.provider, currentProfile.model)
+    : undefined;
+  const firstChoices = [
+    ...(allowInherit
+      ? [
+          {
+            key: LOCAL_INHERIT,
+            value: LOCAL_INHERIT,
+            label: "Inherit repository preset",
+            description: "Remove the personal override without changing the repository preset.",
+          },
+        ]
+      : []),
+    ...models.map((model) => ({
+      key: model.key,
+      value: model,
+      label: model.label,
+      description: model.description,
+    })),
   ];
+  if (firstChoices.length === 0) {
+    firstChoices.push({
+      key: "__cancel__",
+      value: "cancel",
+      label: "No authenticated models available",
+      description: "Authenticate a provider before configuring this preset.",
+    });
+  }
+
+  return {
+    firstStep: () => ({
+      title: "Choose model",
+      choices: firstChoices,
+      selectedKey:
+        currentValue === LOCAL_INHERIT
+          ? LOCAL_INHERIT
+          : firstChoices.some((choice) => choice.key === currentModelKey)
+            ? currentModelKey
+            : firstChoices[0]?.key,
+    }),
+    nextStep: (selectedValues) => {
+      if (selectedValues.length === 1) {
+        const selected = selectedValues[0];
+        if (selected === LOCAL_INHERIT) {
+          return cognitiveRoutingConfirmStep("inherit repository preset");
+        }
+        const model = selected as CognitiveRoutingModelOption;
+        if (!model?.key || model.thinkingLevels.length === 0) return undefined;
+        const currentEffort =
+          currentProfile && currentModelKey === model.key ? currentProfile.thinkingLevel : undefined;
+        return {
+          title: `Choose effort · ${model.label}`,
+          choices: model.thinkingLevels.map((level) => ({
+            key: level,
+            value: level,
+            label: level,
+            description: COGNITIVE_ROUTING_EFFORT_DESCRIPTIONS[level],
+          })),
+          selectedKey:
+            currentEffort && model.thinkingLevels.includes(currentEffort) ? currentEffort : model.thinkingLevels[0],
+        };
+      }
+      if (selectedValues.length === 2) {
+        const model = selectedValues[0] as CognitiveRoutingModelOption;
+        const effort = selectedValues[1] as CognitiveRoutingThinkingLevel;
+        return cognitiveRoutingConfirmStep(`${model.label} · ${effort}`);
+      }
+      return undefined;
+    },
+    valueFromSelections: (selectedValues) => {
+      if (selectedValues[0] === LOCAL_INHERIT) return undefined;
+      const model = selectedValues[0] as CognitiveRoutingModelOption;
+      return {
+        provider: model.provider,
+        model: model.model,
+        thinkingLevel: selectedValues[1] as CognitiveRoutingThinkingLevel,
+      } satisfies CognitiveRoutingProfile;
+    },
+  };
+}
+
+function cognitiveRoutingProfileItem(options: {
+  name: CognitiveRoutingProfileName;
+  scope: ConfigScope;
+  rawConfig: Record<string, unknown>;
+  localConfig: Record<string, unknown>;
+  capabilityState: CognitiveRoutingCapabilityState | undefined;
+  ctx: any;
+}): SettingsItem {
+  const path = ["cognitiveRouting", "profiles", options.name];
+  const repositoryProfile = getPath(options.rawConfig, path);
+  const localProfile = getPath(options.localConfig, path);
+  const effectiveProfile = options.capabilityState?.profiles?.[options.name] ?? repositoryProfile;
+  const localValue = isCognitiveRoutingProfile(localProfile) ? localProfile : LOCAL_INHERIT;
+  const value = options.scope === "local" ? localValue : repositoryProfile;
+  const source =
+    options.capabilityState?.profileSources?.[options.name] ??
+    (isCognitiveRoutingProfile(repositoryProfile) ? "repository" : undefined);
+  const models = cognitiveRoutingModelOptions(options.ctx);
+  const inactive = options.scope === "local" && models.length === 0 && localValue !== LOCAL_INHERIT;
+
+  return {
+    id: `freeflow.cognitiveRouting.${options.name}`,
+    label: `${options.name.charAt(0).toUpperCase()}${options.name.slice(1)} preset`,
+    description:
+      "Choose an authenticated available model and one effort supported by that model. Confirming writes the complete preset; cancel leaves it unchanged.",
+    path,
+    kind: "string",
+    value,
+    format: cognitiveRoutingProfileDisplay,
+    configScope: options.scope,
+    effectiveValue: effectiveProfile,
+    effectiveSource: cognitiveRoutingSettingsSource(source),
+    inheritedValue: repositoryProfile,
+    inheritedSource: "repository",
+    inactive,
+    displaySuffix: cognitiveRoutingProfileDisplaySuffix(source, options.scope),
+    wizard: () => createCognitiveRoutingProfileWizard(value, models, options.scope === "local"),
+  };
+}
+
+type CognitiveRoutingSessionStartSetting = "control" | "profile";
+
+function cognitiveRoutingSessionStartItem(options: {
+  setting: CognitiveRoutingSessionStartSetting;
+  scope: ConfigScope;
+  rawConfig: Record<string, unknown>;
+  localConfig: Record<string, unknown>;
+  capabilityState: CognitiveRoutingCapabilityState | undefined;
+}): SettingsItem {
+  const path = ["cognitiveRouting", "sessionStart", options.setting];
+  const defaultValue = options.setting === "control" ? "automatic" : "reasoning";
+  const values = options.setting === "control" ? ["automatic", "manual"] : ["standard", "reasoning"];
+  const labels = Object.fromEntries(values.map((value) => [value, value]));
+  const descriptions =
+    options.setting === "control"
+      ? {
+          automatic: "Start the new session in Reasoning; automatic delegation may use Standard during execution.",
+          manual: "Hold the selected profile for the new session until the user changes it.",
+        }
+      : {
+          standard: "Start a new manual session with the configured Standard preset.",
+          reasoning: "Start a new manual session with the configured Reasoning preset.",
+        };
+  const repositoryValue = getPath(options.rawConfig, path);
+  const localValue = getPath(options.localConfig, path);
+  const isValidValue = (value: unknown): value is string => values.includes(value as string);
+  const repositorySetting = isValidValue(repositoryValue) ? repositoryValue : undefined;
+  const localSetting = isValidValue(localValue) ? localValue : undefined;
+  const inheritedValue = repositorySetting ?? defaultValue;
+  const inheritedSource: ConfigSource = repositorySetting ? "repository" : "builtin";
+  const configuredSource =
+    options.capabilityState?.sessionStartSources?.[options.setting] ?? (repositorySetting ? "repository" : undefined);
+  const effectiveSessionStartControl =
+    options.capabilityState?.sessionStart?.control ??
+    getPath(options.localConfig, ["cognitiveRouting", "sessionStart", "control"]) ??
+    getPath(options.rawConfig, ["cognitiveRouting", "sessionStart", "control"]) ??
+    "automatic";
+  const effectiveValue =
+    options.setting === "profile" && effectiveSessionStartControl === "automatic"
+      ? "reasoning"
+      : (options.capabilityState?.sessionStart?.[options.setting] ?? inheritedValue);
+  const effectiveSource = cognitiveRoutingSettingsSource(configuredSource);
+  const label = options.setting === "control" ? "Session start control" : "Manual session-start profile";
+  const description =
+    options.setting === "control"
+      ? "Choose automatic or manual control for new sessions only; changing this does not alter the active session."
+      : "Choose the profile for manual session starts; automatic sessions always start in Reasoning.";
+
+  const item: SettingsItem =
+    options.scope === "local"
+      ? {
+          id: `freeflow.cognitiveRouting.sessionStart.${options.setting}`,
+          label,
+          description: `${description} Choose inherit to use the repository value; use /freeflow settings repo to edit shared defaults.`,
+          path,
+          kind: "enum",
+          value: localSetting ?? LOCAL_INHERIT,
+          values: [LOCAL_INHERIT, ...values],
+          valueLabels: { inherit: "Inherit repository", ...labels },
+          valueDescriptions: {
+            inherit: `Use ${inheritedValue} from ${inheritedSource}.`,
+            ...descriptions,
+          },
+          format: (value) => String(value),
+          configScope: "local",
+          configValues: { inherit: undefined },
+          effectiveValue,
+          effectiveSource,
+          inheritedValue,
+          inheritedSource,
+        }
+      : {
+          id: `freeflow.cognitiveRouting.sessionStart.${options.setting}`,
+          label,
+          description: `${description} This edits shared .freeflow/config.json.`,
+          path,
+          kind: "enum",
+          value: inheritedValue,
+          values,
+          valueLabels: labels,
+          valueDescriptions: descriptions,
+          format: (value) => String(value),
+          defaultValue,
+          configScope: "repository",
+          effectiveValue,
+          effectiveSource,
+          localOverrideValue: localSetting,
+        };
+  item.displaySuffix = coreDisplaySuffix(item);
+  return item;
+}
+
+function isCognitiveRoutingRuntimeAvailable(pi: any): boolean {
+  return isPiFlowHost(pi?.host) || supportsPiSessionModelStateApi(pi);
 }
 
 function freeflowItems(
   rawConfig: Record<string, unknown>,
-  modeState?: Awaited<ReturnType<typeof readModeState>>,
   options: {
     scope?: ConfigScope;
     layers?: Awaited<ReturnType<typeof readFreeflowConfigLayers>>;
+    cognitiveRouting?: CognitiveRoutingCapabilityState;
+    ctx?: any;
+    runtimeAvailable?: boolean;
   } = {},
 ): SettingsItem[] {
   const scope = options.scope ?? "repository";
@@ -863,240 +843,128 @@ function freeflowItems(
     localConfig,
     id: "freeflow.enabled",
     label: "Freeflow",
-    description: "Master switch for the Interaction Contract and Freeflow skills in this checkout.",
+    description: "Master switch for Freeflow's core guidance, skills, and optional capabilities in this checkout.",
     path: ["enabled"],
     effectiveValue: core.enabled,
     effectiveSource: sources.enabled,
     defaultValue: DEFAULT_FREEFLOW_ENABLED,
   });
-  const interactionItem = createScopedBooleanItem({
+  const contextVirtualizationItem = createScopedBooleanItem({
     scope,
     rawConfig,
     localConfig,
-    id: "freeflow.interactionContract",
-    label: "Interaction Contract",
-    description: "Apply Freeflow's compact turn-interpretation and collaboration guidance.",
-    path: ["interactionContract"],
-    effectiveValue: core.interactionContract,
-    effectiveSource: sources.interactionContract,
-    defaultValue: DEFAULT_INTERACTION_CONTRACT_ENABLED,
+    id: "freeflow.contextVirtualization",
+    label: "Context Virtualization",
+    description: "Let the model archive consumed tool results from future context while preserving session history.",
+    path: ["contextVirtualization"],
+    effectiveValue: core.contextVirtualization,
+    effectiveSource: sources.contextVirtualization,
+    defaultValue: DEFAULT_CONTEXT_VIRTUALIZATION_ENABLED,
   });
-  const skillsItem = createScopedBooleanItem({
+  const conversationHistoryItem = createScopedBooleanItem({
     scope,
     rawConfig,
     localConfig,
-    id: "freeflow.skills.enabled",
-    label: "Skills",
-    description: "Expose Freeflow skills and load Workflow once on the first turn.",
-    path: ["skills", "enabled"],
-    effectiveValue: core.skills.enabled,
-    effectiveSource: sources.skillsEnabled,
-    defaultValue: DEFAULT_SKILLS_ENABLED,
-  });
-
-  const repositoryModeValue = validModeOrUndefined(rawConfig.defaultMode);
-  const repositoryDefaultMode = repositoryModeValue ?? "workflow";
-  const repositoryDefaultSource: ConfigSource = repositoryModeValue ? "repository" : "builtin";
-  const localDefaultMode = validModeOrUndefined(localConfig.defaultMode);
-  const defaultModeItem = createScopedDefaultModeItem({
-    scope,
-    repositoryDefaultMode,
-    repositoryDefaultSource,
-    localDefaultMode,
-    effectiveValue: core.defaultMode,
-    effectiveSource: sources.defaultMode,
+    id: "freeflow.conversationHistory",
+    label: "Conversation History",
+    description: "Let the model search and retrieve hidden conversation history on the active branch.",
+    path: ["conversationHistory"],
+    effectiveValue: core.conversationHistory,
+    effectiveSource: sources.conversationHistory,
+    defaultValue: DEFAULT_CONVERSATION_HISTORY_ENABLED,
   });
 
   const freeflowInactive = !core.enabled;
-  const skillsEnabled = core.skills.enabled;
-  interactionItem.inactive = freeflowInactive;
-  skillsItem.inactive = freeflowInactive;
-  defaultModeItem.inactive = freeflowInactive;
-  defaultModeItem.displaySuffix = coreDisplaySuffix(defaultModeItem, freeflowInactive || !skillsEnabled);
-  const sessionMode = modeState?.currentMode ?? "default";
-  const sessionModeItem: SettingsItem = {
-    id: "freeflow.sessionMode",
-    label: "Session mode",
-    description:
-      "Temporary mode override for this Pi session. Use configured default clears the override without changing either config file.",
-    kind: "enum",
-    value: sessionMode,
-    values: ["default", ...MODE_VALUES],
-    valueLabels: {
-      ...MODE_LABELS,
-      default: "Use configured default",
-    },
-    valueDescriptions: {
-      default: `${core.defaultMode} from ${sources.defaultMode}`,
-      ...MODE_DESCRIPTIONS,
-    },
-    inactive: freeflowInactive || !skillsEnabled,
-    displaySuffix: sessionModeDisplaySuffix(
-      sessionMode,
-      core.defaultMode,
-      sources.defaultMode,
-      freeflowInactive || !skillsEnabled,
-    ),
-  };
+  contextVirtualizationItem.inactive = freeflowInactive;
+  conversationHistoryItem.inactive = freeflowInactive;
+
+  const cognitiveRoutingState = options.cognitiveRouting;
+  const cognitiveRoutingRuntimeDisabled = options.runtimeAvailable !== true;
+  const cognitiveRoutingGroup = (() => {
+    const cognitiveRoutingEnabledItem = createScopedBooleanItem({
+      scope,
+      rawConfig,
+      localConfig,
+      id: "freeflow.cognitiveRouting.enabled",
+      label: "Enabled",
+      description: cognitiveRoutingRuntimeDisabled
+        ? "Requires a host model-state control API; configuration is read-only on this host."
+        : "Allow Cognitive Routing to own the session model lease and switch the configured profiles.",
+      path: ["cognitiveRouting", "enabled"],
+      effectiveValue: cognitiveRoutingState?.enabled ?? false,
+      effectiveSource: cognitiveRoutingSettingsSource(cognitiveRoutingState?.enabledSource),
+      defaultValue: false,
+    });
+    cognitiveRoutingEnabledItem.inactive = freeflowInactive || cognitiveRoutingRuntimeDisabled;
+    cognitiveRoutingEnabledItem.runtimeInactive = cognitiveRoutingRuntimeDisabled;
 
-  const routerItems = outputRouterItems(rawConfig, freeflowInactive);
-  const routerEnabled = groupEnabled(routerItems, "outputRouter.enabled");
+    const cognitiveRoutingProfiles = ["standard", "reasoning"].map((name) =>
+      cognitiveRoutingProfileItem({
+        name: name as CognitiveRoutingProfileName,
+        scope,
+        rawConfig,
+        localConfig,
+        capabilityState: cognitiveRoutingState,
+        ctx: options.ctx,
+      }),
+    );
+    const cognitiveRoutingSessionStart = (["control", "profile"] as CognitiveRoutingSessionStartSetting[]).map(
+      (setting) =>
+        cognitiveRoutingSessionStartItem({
+          setting,
+          scope,
+          rawConfig,
+          localConfig,
+          capabilityState: cognitiveRoutingState,
+        }),
+    );
+    for (const item of [...cognitiveRoutingProfiles, ...cognitiveRoutingSessionStart]) {
+      item.inactive ||= freeflowInactive || cognitiveRoutingRuntimeDisabled;
+      item.runtimeInactive = cognitiveRoutingRuntimeDisabled;
+    }
+    const cognitiveRoutingStatus = cognitiveRoutingRuntimeDisabled
+      ? "unavailable · host unsupported"
+      : cognitiveRoutingState
+        ? cognitiveRoutingState.effective
+          ? "active"
+          : cognitiveRoutingState.blockingReason?.code === "profile_missing"
+            ? "not configured"
+            : (cognitiveRoutingState.blockingReason?.code ?? "inactive")
+        : "unavailable";
+    return {
+      id: "freeflow.cognitiveRouting",
+      label: "Cognitive Routing",
+      description: cognitiveRoutingRuntimeDisabled
+        ? "Cognitive Routing configuration is visible for inspection but requires a host model-state control API."
+        : "Configure the Standard and Reasoning profiles and choose whether Freeflow may manage model state for this repository.",
+      kind: "group" as const,
+      value: cognitiveRoutingRuntimeDisabled ? false : (cognitiveRoutingState?.enabled ?? false),
+      inactive: freeflowInactive,
+      displaySuffix: cognitiveRoutingStatus,
+      children: [cognitiveRoutingEnabledItem, ...cognitiveRoutingProfiles, ...cognitiveRoutingSessionStart],
+    } satisfies SettingsItem;
+  })();
 
   return [
     freeflowItem,
-    interactionItem,
-    skillsItem,
-    sessionModeItem,
-    defaultModeItem,
+    ...(cognitiveRoutingGroup ? [cognitiveRoutingGroup] : []),
     {
-      id: "outputRouter.group",
-      label: "Output Router",
-      description:
-        "Shared repository settings for routed evidence tools, native output safety net, vault storage, script transforms, and observed tool routing.",
+      id: "freeflow.context",
+      label: "Freeflow Context",
+      description: "Choose which context projection and conversation-history operations are available to the model.",
       kind: "group",
-      value: routerEnabled,
-      inactive: freeflowInactive,
-      displaySuffix: "(repository)",
-      children: routerItems,
+      value: contextVirtualizationItem.effectiveValue === true || conversationHistoryItem.effectiveValue === true,
+      displaySuffix: `${[contextVirtualizationItem, conversationHistoryItem].filter((item) => item.effectiveValue === true).length}/2 enabled`,
+      children: [contextVirtualizationItem, conversationHistoryItem],
     },
   ];
 }
 
-function migrateLegacyRouterConfig(config: Record<string, unknown>) {
-  const outputRouter = isRecord(config.outputRouter) ? config.outputRouter : undefined;
-  if (!outputRouter) return;
-  if (config.scriptTransform !== undefined && outputRouter.scriptTransform === undefined) {
-    outputRouter.scriptTransform = config.scriptTransform;
-    delete config.scriptTransform;
-  }
-  if (config.observedRouting !== undefined && outputRouter.observedRouting === undefined) {
-    outputRouter.observedRouting = config.observedRouting;
-    delete config.observedRouting;
-  }
-
-  const thresholds = isRecord(outputRouter.thresholds) ? outputRouter.thresholds : {};
-  if (outputRouter.largeOutputBytes !== undefined && thresholds.largeOutputBytes === undefined) {
-    thresholds.largeOutputBytes = outputRouter.largeOutputBytes;
-    outputRouter.thresholds = thresholds;
-    delete outputRouter.largeOutputBytes;
-  }
-  if (outputRouter.largeOutputLines !== undefined && thresholds.largeOutputLines === undefined) {
-    thresholds.largeOutputLines = outputRouter.largeOutputLines;
-    outputRouter.thresholds = thresholds;
-    delete outputRouter.largeOutputLines;
-  }
-
-  const vault = isRecord(outputRouter.vault) ? outputRouter.vault : {};
-  if (outputRouter.vaultRoot !== undefined && vault.root === undefined) {
-    vault.root = outputRouter.vaultRoot;
-    outputRouter.vault = vault;
-    delete outputRouter.vaultRoot;
-  }
-  if (outputRouter.vaultRetentionDays !== undefined && !isRecord(vault.retention)) {
-    vault.retention = {
-      strategy: "ttl",
-      ttlDays: outputRouter.vaultRetentionDays,
-    };
-    outputRouter.vault = vault;
-    delete outputRouter.vaultRetentionDays;
-  }
-
-  const hints = isRecord(outputRouter.hints) ? outputRouter.hints : {};
-  if (outputRouter.generatedPaths !== undefined && hints.generatedPathGlobs === undefined) {
-    hints.generatedPathGlobs = outputRouter.generatedPaths;
-    outputRouter.hints = hints;
-    delete outputRouter.generatedPaths;
-  }
-  if (outputRouter.noisyCommandHints !== undefined && hints.noisyCommandPatterns === undefined) {
-    hints.noisyCommandPatterns = outputRouter.noisyCommandHints;
-    outputRouter.hints = hints;
-    delete outputRouter.noisyCommandHints;
-  }
-}
-
 function pruneKnownDefaults(config: Record<string, unknown>) {
   const defaultPaths: Array<{ path: string[]; value: unknown }> = [
     { path: ["enabled"], value: DEFAULT_FREEFLOW_ENABLED },
-    {
-      path: ["interactionContract"],
-      value: DEFAULT_INTERACTION_CONTRACT_ENABLED,
-    },
-    { path: ["skills", "enabled"], value: DEFAULT_SKILLS_ENABLED },
-    { path: ["outputRouter", "enabled"], value: DEFAULT_OUTPUT_ROUTER_ENABLED },
-    {
-      path: ["outputRouter", "postToolRouting"],
-      value: DEFAULT_POST_TOOL_ROUTING,
-    },
-    { path: ["outputRouter", "storagePolicy"], value: DEFAULT_STORAGE_POLICY },
-    {
-      path: ["outputRouter", "thresholds", "largeOutputBytes"],
-      value: DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
-    },
-    {
-      path: ["outputRouter", "thresholds", "largeOutputLines"],
-      value: DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
-    },
-    { path: ["outputRouter", "vault", "root"], value: DEFAULT_VAULT_ROOT },
-    {
-      path: ["outputRouter", "vault", "retention", "ttlDays"],
-      value: DEFAULT_VAULT_RETENTION.ttlDays,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "enabled"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.enabled,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "sandbox"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.sandbox,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "languages"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.languages,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "network"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.network,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "rawScriptPersistence"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.rawScriptPersistence,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "limits", "timeoutMs"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.timeoutMs,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "limits", "maxInputBytes"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxInputBytes,
-    },
-    {
-      path: ["outputRouter", "scriptTransform", "limits", "maxOutputBytes"],
-      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxOutputBytes,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "enabled"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.enabled,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "onRoutingFailure"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.onRoutingFailure,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "mcp", "servers"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.mcp.servers,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "web", "enabled"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.web.enabled,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "fetch", "enabled"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.fetch.enabled,
-    },
-    {
-      path: ["outputRouter", "observedRouting", "codeSearch", "enabled"],
-      value: DEFAULT_OBSERVED_ROUTING_CONFIG.codeSearch.enabled,
-    },
+    { path: ["contextVirtualization"], value: DEFAULT_CONTEXT_VIRTUALIZATION_ENABLED },
+    { path: ["conversationHistory"], value: DEFAULT_CONVERSATION_HISTORY_ENABLED },
   ];
 
   for (const item of defaultPaths) {
@@ -1104,19 +972,6 @@ function pruneKnownDefaults(config: Record<string, unknown>) {
       deletePath(config, item.path);
     }
   }
-
-  for (const producer of ["web", "fetch", "codeSearch"]) {
-    const enabledPath = ["outputRouter", "observedRouting", producer, "enabled"];
-    const persistencePath = ["outputRouter", "observedRouting", producer, "persistence"];
-    if (getPath(config, enabledPath) !== true && getPath(config, persistencePath) === "none") {
-      deletePath(config, persistencePath);
-    }
-  }
-
-  const servers = getPath(config, ["outputRouter", "observedRouting", "mcp", "servers"]);
-  if (isRecord(servers) && Object.keys(servers).length === 0) {
-    deletePath(config, ["outputRouter", "observedRouting", "mcp", "servers"]);
-  }
 }
 
 async function ensureLocalConfigIgnored(cwd: string) {
@@ -1190,15 +1045,20 @@ async function updateConfig(
   const current = await readFreeflowConfig(cwd);
   const next = cloneJson(current) as Record<string, unknown>;
   setConfigValue(next, item, value);
-  migrateLegacyRouterConfig(next);
   pruneKnownDefaults(next);
   await mkdir(join(cwd, ".freeflow"), { recursive: true });
   await writeFile(join(cwd, ".freeflow/config.json"), `${JSON.stringify(next, null, 2)}\n`, "utf8");
 }
 
+function isCognitiveRoutingProfileItem(item: SettingsItem): boolean {
+  return item.id === "freeflow.cognitiveRouting.standard" || item.id === "freeflow.cognitiveRouting.reasoning";
+}
+
 function valueForDisplay(item: SettingsItem): string {
   let value: string;
-  if (item.configScope === "local" || item.configScope === "session") {
+  if (isCognitiveRoutingProfileItem(item) && item.format) {
+    value = item.format(effectiveItemValue(item));
+  } else if (item.configScope === "local" || item.configScope === "session") {
     value = formatCoreValue(effectiveItemValue(item));
   } else if (item.kind === "boolean") {
     value = booleanValue(item.value);
@@ -1233,54 +1093,46 @@ function findSettingsItem(items: SettingsItem[], id: string): SettingsItem | und
 function refreshSettingsDerivedState(items: SettingsItem[]) {
   const freeflowItem = findSettingsItem(items, "freeflow.enabled");
   const freeflowInactive = freeflowItem ? effectiveItemValue(freeflowItem) !== true : false;
-  const skillsItem = findSettingsItem(items, "freeflow.skills.enabled");
-  const skillsEnabled = skillsItem ? effectiveItemValue(skillsItem) === true : true;
-  const routerEnabled = findSettingsItem(items, "outputRouter.enabled")?.value === true;
-  const sessionModeItem = findSettingsItem(items, "freeflow.sessionMode");
-  const defaultModeItem = findSettingsItem(items, "freeflow.defaultMode");
-  const routerGroup = findSettingsItem(items, "outputRouter.group");
-
-  if (sessionModeItem) {
-    const defaultMode = String(
-      defaultModeItem ? effectiveItemValue(defaultModeItem) : (sessionModeItem.inheritedValue ?? "workflow"),
-    );
-    const defaultSource = defaultModeItem?.effectiveSource ?? sessionModeItem.inheritedSource ?? "builtin";
-    sessionModeItem.inactive = freeflowInactive || !skillsEnabled;
-    sessionModeItem.displaySuffix = sessionModeDisplaySuffix(
-      String(sessionModeItem.value),
-      defaultMode,
-      defaultSource,
-      freeflowInactive || !skillsEnabled,
+  const cognitiveRoutingGroup = findSettingsItem(items, "freeflow.cognitiveRouting");
+  const cognitiveRoutingEnabledItem = findSettingsItem(items, "freeflow.cognitiveRouting.enabled");
+  const cognitiveRoutingProfiles = [
+    findSettingsItem(items, "freeflow.cognitiveRouting.standard"),
+    findSettingsItem(items, "freeflow.cognitiveRouting.reasoning"),
+  ];
+
+  if (cognitiveRoutingGroup && cognitiveRoutingEnabledItem) {
+    const enabled = effectiveItemValue(cognitiveRoutingEnabledItem) === true;
+    const profilesConfigured = cognitiveRoutingProfiles.every((item) =>
+      item ? isCognitiveRoutingProfile(effectiveItemValue(item)) : false,
     );
-    sessionModeItem.valueDescriptions = {
-      default: `${defaultMode} from ${defaultSource}`,
-      ...MODE_DESCRIPTIONS,
-    };
+    cognitiveRoutingGroup.value = enabled;
+    cognitiveRoutingGroup.displaySuffix = enabled
+      ? profilesConfigured
+        ? cognitiveRoutingGroup.displaySuffix === "active"
+          ? "active"
+          : "configured"
+        : "not configured"
+      : "disabled";
+    cognitiveRoutingGroup.inactive = freeflowInactive;
   }
 
-  if (routerGroup) {
-    routerGroup.value = routerEnabled;
-    routerGroup.inactive = freeflowInactive;
+  const contextGroup = findSettingsItem(items, "freeflow.context");
+  if (contextGroup?.children?.length) {
+    const enabledCount = contextGroup.children.filter((item) => effectiveItemValue(item) === true).length;
+    contextGroup.value = enabledCount > 0;
+    contextGroup.displaySuffix = `${enabledCount}/${contextGroup.children.length} enabled`;
   }
 
   walkSettingsItems(items, (candidate) => {
     if (candidate.id === "freeflow.session.reset") {
       candidate.inactive = false;
     } else if (candidate.configScope) {
-      const inactive = candidate.id === "freeflow.enabled" ? false : freeflowInactive;
-      const displayInactive = candidate.id === "freeflow.defaultMode" ? freeflowInactive || !skillsEnabled : inactive;
+      const inactive =
+        candidate.id === "freeflow.enabled" ? false : candidate.runtimeInactive === true || freeflowInactive;
       candidate.inactive = inactive;
-      candidate.displaySuffix = coreDisplaySuffix(candidate, displayInactive);
-    } else if (candidate.id === "freeflow.sessionMode") {
-      candidate.inactive = freeflowInactive || !skillsEnabled;
-    } else if (candidate.id === "outputRouter.group") {
-      candidate.inactive = freeflowInactive;
-    } else if (candidate.id === "outputRouter.enabled") {
-      candidate.inactive = freeflowInactive;
-    } else if (candidate.id.startsWith("outputRouter.")) {
-      candidate.inactive = freeflowInactive || !routerEnabled;
+      candidate.displaySuffix = coreDisplaySuffix(candidate, inactive);
     } else {
-      candidate.inactive = freeflowInactive;
+      candidate.inactive = candidate.runtimeInactive === true || freeflowInactive;
     }
   });
 }
@@ -1327,6 +1179,7 @@ function settingsEntries(
     currentChoiceKey: () => String(item.value),
     choices: settingsChoices(item),
     children: item.children ? () => settingsEntries(item.children!, rootItems, onChange) : undefined,
+    wizard: item.wizard ? () => item.wizard!() : undefined,
     edit:
       !item.children && !["boolean", "enum", "group"].includes(item.kind)
         ? {
@@ -1385,48 +1238,45 @@ async function openSettings(options: OpenSettingsOptions): Promise<SettingsSessi
   return component?.sessionResult() ?? { changed: false, configChanged: false, failed: false };
 }
 
-function outputRouterStatusText(rawConfig: Record<string, unknown>): string {
-  const settingsConfig = normalizedSettingsConfig(rawConfig);
-  const actual = normalizeFreeflowConfig(rawConfig).config;
-  const freeflowEnabled = rawConfig.enabled !== false;
-  const router = actual.outputRouter;
-  const configured = settingsConfig;
-  const generatedPaths = router.hints?.generatedPathGlobs?.length ?? 0;
-  const noisyHints = router.hints?.noisyCommandPatterns?.length ?? 0;
-  return [
-    `Output Router: ${freeflowEnabled && router.enabled ? "enabled" : "disabled"}${freeflowEnabled ? "" : " (inactive: Freeflow off)"}`,
-    `script transform: ${freeflowEnabled && configured.scriptTransform.enabled ? "enabled" : "disabled"}${freeflowEnabled && router.enabled ? "" : " (inactive)"}`,
-    `observed routing: ${freeflowEnabled && configured.observedRouting.enabled ? "enabled" : "disabled"}${freeflowEnabled && router.enabled ? "" : " (inactive)"}`,
-    `native safety net: ${freeflowEnabled ? router.postToolRouting : "off"}`,
-    `storage: ${router.storagePolicy}`,
-    `generated paths: ${generatedPaths}`,
-    `noisy command hints: ${noisyHints}`,
-  ].join("; ");
-}
-
-function freeflowStatusText(state: Awaited<ReturnType<typeof readCapabilityState>>): string {
+function freeflowStatusText(
+  state: Awaited<ReturnType<typeof readCapabilityState>>,
+  cognitiveRoutingController?: CognitiveRoutingSettingsController,
+): string {
   if (!state.configured) {
     return state.configExists
       ? `Freeflow: inactive (invalid config: ${state.parseError ?? "unknown parse error"}); run /setup-freeflow or fix .freeflow/config.json`
       : "Freeflow: inactive (repo not set up); run /setup-freeflow";
   }
   const sessionSuffix = (source: ConfigSource) => (source === "session" ? " (session override)" : "");
+  const routingState = cognitiveRoutingController?.state();
+  const cognitiveRouting = state.cognitiveRouting;
+  const cognitiveRoutingStatus = cognitiveRouting
+    ? cognitiveRouting.blockingReason?.code === "runtime_disabled"
+      ? "unavailable (host unsupported)"
+      : cognitiveRouting.effective
+        ? routingState?.effective
+          ? `active (${routingState.activeProfile ?? "unknown"}, ${routingState.controlMode})`
+          : "effective (inactive)"
+        : cognitiveRouting.enabled
+          ? `blocked (${cognitiveRouting.blockingReason.code})`
+          : "disabled"
+    : undefined;
+  const contextEnabled = state.contextVirtualization?.effective || state.conversationHistory?.effective;
   return [
     `Freeflow: ${state.enabled ? "enabled" : "disabled"}${sessionSuffix(state.configSources.enabled as ConfigSource)}`,
-    `interaction contract: ${state.interactionContract.effective ? "enabled" : "disabled"}${sessionSuffix(
-      state.configSources.interactionContract as ConfigSource,
-    )}`,
-    `skills: ${state.skills.effective ? "enabled" : "disabled (workflow modes inactive)"}${sessionSuffix(
-      state.configSources.skillsEnabled as ConfigSource,
-    )}`,
-    `output router: ${state.outputRouter.enabled ? "enabled" : "disabled"}`,
+    `context: ${contextEnabled ? "enabled" : "disabled"} (virtualization ${state.contextVirtualization?.effective ? "enabled" : "disabled"}, history ${state.conversationHistory?.effective ? "enabled" : "disabled"})`,
+    ...(cognitiveRoutingStatus ? [`cognitive routing: ${cognitiveRoutingStatus}`] : []),
   ].join("; ");
 }
 
 const NON_TUI_SETTINGS_GUIDANCE =
-  "Freeflow settings require Pi TUI mode. Use /freeflow status to inspect current state; supported non-TUI changes are /freeflow enable, /freeflow disable, and /freeflow mode <conversation|workflow|strict-workflow|reset>.";
-const NON_TUI_MODE_GUIDANCE =
-  "Freeflow mode selector requires Pi TUI mode. Use /freeflow mode conversation, /freeflow mode workflow, /freeflow mode strict-workflow, or /freeflow mode reset.";
+  "Freeflow settings require Pi TUI mode. Use /freeflow status to inspect current state; supported non-TUI changes are /freeflow enable and /freeflow disable.";
+
+function ensureSettingsIdle(ctx: any): boolean {
+  if (typeof ctx?.isIdle !== "function" || ctx.isIdle()) return true;
+  ctx.ui?.notify?.("Freeflow settings and profile changes are available only while Pi is idle.", "warning");
+  return false;
+}
 
 function nonTuiGuidance(ctx: any, message: string) {
   if (ctx?.hasUI === false) throw new Error(message);
@@ -1437,13 +1287,14 @@ function nonTuiGuidance(ctx: any, message: string) {
 async function finalizeSettingsSession(
   session: SettingsSessionResult,
   ctx: any,
-  afterChange: (changed: boolean) => Promise<void> | void,
+  afterChange: AfterChange,
   savedMessage: string,
   reloadWarning = "Run /reload for Freeflow changes to fully apply.",
+  afterChangeOptions: AfterChangeOptions = {},
 ) {
   if (!session.configChanged) return false;
 
-  await afterChange(true);
+  await afterChange(true, afterChangeOptions);
   if (session.failed) return false;
 
   ctx.ui.notify(savedMessage, "info");
@@ -1456,11 +1307,7 @@ async function finalizeSettingsSession(
   return true;
 }
 
-async function finalizeSessionSettings(
-  session: SettingsSessionResult,
-  ctx: any,
-  afterChange: (changed: boolean) => Promise<void> | void,
-) {
+async function finalizeSessionSettings(session: SettingsSessionResult, ctx: any, afterChange: AfterChange) {
   if (!session.changed) return false;
 
   await afterChange(true);
@@ -1480,43 +1327,17 @@ async function finalizeSessionSettings(
   return true;
 }
 
-function actionIsMutation(action: string): boolean {
-  return action === "" || action === "settings" || ["enable", "on", "true", "disable", "off", "false"].includes(action);
-}
-
-async function maybeBlockLayerMutation(action: string, ctx: any, layerName: string) {
-  if (!actionIsMutation(action)) return false;
-  const state = await readCapabilityState(ctx.cwd);
-  if (!state.configured) {
-    ctx.ui.notify(
-      `Freeflow is installed but this repo is not set up. Run /setup-freeflow before configuring ${layerName}.`,
-      "warning",
-    );
-    return true;
-  }
-  if (!state.enabled) {
-    ctx.ui.notify(
-      `Freeflow is disabled for this repo. Use /freeflow enable before configuring ${layerName}.`,
-      "warning",
-    );
-    return true;
-  }
-  return false;
-}
-
 export async function handleFreeflowCommand(
   args: string | undefined,
   ctx: any,
-  afterChange: (changed: boolean) => Promise<void> | void,
+  afterChange: AfterChange,
   pi: any,
+  cognitiveRoutingController?: CognitiveRoutingSettingsController,
 ) {
   const input = (args ?? "settings").trim().toLowerCase() || "settings";
   const [action, ...rest] = input.split(/\s+/);
   const actionValue = rest.join(" ");
   const nonTui = ctx?.mode && ctx.mode !== "tui";
-  if (nonTui && action === "mode" && !actionValue) {
-    return nonTuiGuidance(ctx, NON_TUI_MODE_GUIDANCE);
-  }
   const settingsSelector =
     action === "settings" &&
     (!actionValue || ["session", "local", "personal", "repo", "repository", "shared"].includes(actionValue));
@@ -1524,21 +1345,20 @@ export async function handleFreeflowCommand(
     return nonTuiGuidance(ctx, NON_TUI_SETTINGS_GUIDANCE);
   }
 
-  const [layers, state, modeState] = await Promise.all([
+  const [layers, state] = await Promise.all([
     readFreeflowConfigLayers(ctx.cwd),
-    readCapabilityState(ctx.cwd),
-    readModeState(ctx.cwd),
+    readCapabilityState(ctx.cwd, ctx, pi?.host),
   ]);
   const configState = layers.repository;
   const raw = configState.valid ? configState.parsed : {};
 
   if (action === "status") {
-    ctx.ui.notify(freeflowStatusText(state), "info");
+    ctx.ui.notify(freeflowStatusText(state, cognitiveRoutingController), "info");
     return { changed: false, reloaded: false };
   }
 
   if (!configState.valid) {
-    ctx.ui.notify(freeflowStatusText(state), "warning");
+    ctx.ui.notify(freeflowStatusText(state, cognitiveRoutingController), "warning");
     return { changed: false, reloaded: false, error: "not_configured" };
   }
   if (layers.local.exists && !layers.local.valid) {
@@ -1549,42 +1369,15 @@ export async function handleFreeflowCommand(
     return { changed: false, reloaded: false, error: "invalid_local_config" };
   }
 
-  if (action === "mode") {
-    if (actionValue) {
-      const result = await handleModeCommand(actionValue, ctx, pi);
-      return { changed: result.changed, reloaded: false, error: result.error };
-    }
-    if (!state.enabled || !state.skills.effective) {
-      const result = await handleModeCommand(undefined, ctx, pi);
-      return { changed: false, reloaded: false, error: result.error };
-    }
-    if (typeof ctx?.ui?.custom !== "function") {
-      const result = await handleModeCommand(undefined, ctx, pi);
-      return { changed: false, reloaded: false, error: result.error };
-    }
-
-    const item = freeflowItems(raw, modeState, {
-      scope: "local",
-      layers,
-    }).find((candidate) => candidate.id === "freeflow.sessionMode")!;
-    const session = await openSettings({
-      title: "Freeflow Mode",
-      items: [item],
-      initialChoice: item,
-      ctx,
-      onChange: async (_item, value) => {
-        const result = await handleModeCommand(String(value), ctx, pi);
-        return { changed: result.changed, reloadRequired: false };
-      },
-    });
-    return { changed: session.changed, reloaded: false, error: session.failed ? "write_failed" : undefined };
-  }
-
   if (["enable", "on", "true", "disable", "off", "false"].includes(action)) {
+    if (!ensureSettingsIdle(ctx)) return { changed: false, reloaded: false, error: "busy" };
     const enabled = ["enable", "on", "true"].includes(action);
-    const item = freeflowItems(raw, modeState, {
+    const item = freeflowItems(raw, {
       scope: "repository",
       layers,
+      cognitiveRouting: state.cognitiveRouting as CognitiveRoutingCapabilityState,
+      ctx,
+      runtimeAvailable: isCognitiveRoutingRuntimeAvailable(pi),
     }).find((candidate) => candidate.id === "freeflow.enabled")!;
     await updateConfig(ctx.cwd, item, enabled, "repository");
     await afterChange(true);
@@ -1599,7 +1392,7 @@ export async function handleFreeflowCommand(
 
   if (action && action !== "settings") {
     ctx.ui.notify(
-      "Usage: /freeflow, /freeflow settings [local|repo], /freeflow status, /freeflow mode [conversation|workflow|strict-workflow|reset], /freeflow enable, or /freeflow disable",
+      "Usage: /freeflow, /freeflow settings [local|repo], /freeflow status, /freeflow enable, or /freeflow disable",
       "warning",
     );
     return { changed: false, reloaded: false, error: "invalid_action" };
@@ -1618,10 +1411,19 @@ export async function handleFreeflowCommand(
     return { changed: false, reloaded: false, error: "invalid_scope" };
   }
 
+  if (!ensureSettingsIdle(ctx)) return { changed: false, reloaded: false, error: "busy" };
+
+  let reconcileCognitiveRouting = settingsScope === "session";
   const items =
     settingsScope === "session"
-      ? sessionFreeflowItems(state, modeState)
-      : freeflowItems(raw, modeState, { scope: settingsScope, layers });
+      ? sessionFreeflowItems(state, cognitiveRoutingController)
+      : freeflowItems(raw, {
+          scope: settingsScope,
+          layers,
+          cognitiveRouting: state.cognitiveRouting as CognitiveRoutingCapabilityState,
+          ctx,
+          runtimeAvailable: isCognitiveRoutingRuntimeAvailable(pi),
+        });
   const session = await openSettings({
     title:
       settingsScope === "session"
@@ -1632,9 +1434,29 @@ export async function handleFreeflowCommand(
     items,
     ctx,
     onChange: async (item, value) => {
-      if (item.id === "freeflow.sessionMode") {
-        const result = await handleModeCommand(String(value), ctx, pi);
-        return { changed: result.changed, reloadRequired: false };
+      if (!ensureSettingsIdle(ctx)) return { changed: false, reloadRequired: false };
+      if (!isCognitiveRoutingRuntimeAvailable(pi) && item.id.startsWith("freeflow.cognitiveRouting.")) {
+        ctx.ui.notify("Cognitive Routing is unavailable because this host lacks model-state controls.", "warning");
+        return { changed: false, reloadRequired: false };
+      }
+      if (item.id === "freeflow.cognitiveRouting.profile") {
+        if (!cognitiveRoutingController) {
+          ctx.ui.notify("Cognitive Routing is unavailable for this session.", "warning");
+          return { changed: false, reloadRequired: false };
+        }
+        const result =
+          value === "auto"
+            ? await cognitiveRoutingController.setAutomaticControl("profile-settings")
+            : await cognitiveRoutingController.setManualProfile(value as "standard" | "reasoning", "profile-settings");
+        if ((result.status !== "automatic" && result.status !== "active") || result.reason) {
+          ctx.ui.notify(
+            `Cognitive Routing settings could not be applied: ${result.reason ?? result.status}.`,
+            "warning",
+          );
+          return { changed: false, reloadRequired: false };
+        }
+        await afterChange(false);
+        return { changed: true, reloadRequired: false };
       }
       if (item.id === "freeflow.session.reset") {
         const result = await resetSessionOverrides(ctx, pi);
@@ -1643,8 +1465,8 @@ export async function handleFreeflowCommand(
       if (item.configScope === "session") {
         const keyById = {
           "freeflow.enabled": "enabled",
-          "freeflow.interactionContract": "interactionContract",
-          "freeflow.skills.enabled": "skillsEnabled",
+          "freeflow.contextVirtualization": "contextVirtualization",
+          "freeflow.conversationHistory": "conversationHistory",
         } as const;
         const key = keyById[item.id as keyof typeof keyById];
         const override = value === LOCAL_INHERIT ? null : value === "true";
@@ -1652,6 +1474,9 @@ export async function handleFreeflowCommand(
         return { changed: result.changed, reloadRequired: result.reloadRequired === true };
       }
       await updateConfig(ctx.cwd, item, value, item.configScope ?? "repository");
+      if (!item.id.startsWith("freeflow.cognitiveRouting.sessionStart.")) {
+        reconcileCognitiveRouting = true;
+      }
       return { changed: true, reloadRequired: true };
     },
   });
@@ -1667,64 +1492,8 @@ export async function handleFreeflowCommand(
     ctx,
     afterChange,
     `Freeflow ${savedTarget} saved. Reloading Freeflow runtime...`,
-  );
-  return { changed: session.changed, reloaded, error: session.failed ? "write_failed" : undefined };
-}
-
-export async function handleOutputRouterCommand(
-  args: string | undefined,
-  ctx: any,
-  afterChange: (changed: boolean) => Promise<void> | void,
-) {
-  const action = (args ?? "").trim().toLowerCase();
-  const raw = await readFreeflowConfig(ctx.cwd);
-
-  if (await maybeBlockLayerMutation(action, ctx, "Output Router")) {
-    return { changed: false, reloaded: false, error: "freeflow_inactive" };
-  }
-
-  if (action === "status") {
-    const state = await readCapabilityState(ctx.cwd);
-    const prefix = !state.configured || !state.enabled ? `${freeflowStatusText(state)}; ` : "";
-    ctx.ui.notify(`${prefix}${outputRouterStatusText(raw)}`, !state.configured || !state.enabled ? "warning" : "info");
-    return { changed: false, reloaded: false };
-  }
-
-  if (["enable", "on", "true", "disable", "off", "false"].includes(action)) {
-    const enabled = ["enable", "on", "true"].includes(action);
-    const item = outputRouterItems(raw).find((candidate) => candidate.id === "outputRouter.enabled")!;
-    await updateConfig(ctx.cwd, item, enabled);
-    await afterChange(true);
-    ctx.ui.notify(`Output Router ${enabled ? "enabled" : "disabled"}. Reloading Freeflow runtime...`, "info");
-    if (typeof ctx.reload === "function") {
-      await ctx.reload();
-      return { changed: true, reloaded: true };
-    }
-    ctx.ui.notify("Run /reload for Output Router changes to fully apply.", "warning");
-    return { changed: true, reloaded: false };
-  }
-
-  if (action && action !== "settings") {
-    ctx.ui.notify("Usage: /output-router, /output-router settings, or /output-router status", "warning");
-    return { changed: false, reloaded: false, error: "invalid_action" };
-  }
-
-  const session = await openSettings({
-    title: "Output Router Settings",
-    items: outputRouterItems(raw),
-    ctx,
-    onChange: async (item, value) => {
-      await updateConfig(ctx.cwd, item, value);
-      return { changed: true, reloadRequired: true };
-    },
-  });
-
-  const reloaded = await finalizeSettingsSession(
-    session,
-    ctx,
-    afterChange,
-    "Output Router settings saved. Reloading Freeflow runtime...",
-    "Run /reload for Output Router changes to fully apply.",
+    "Run /reload for Freeflow changes to fully apply.",
+    { reconcileCognitiveRouting },
   );
   return { changed: session.changed, reloaded, error: session.failed ? "write_failed" : undefined };
 }