@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/dist/settings/settings-ui.js

@@ -12,6 +12,7 @@ import {
 } from "../runtime/runtime-context.js";
 import { PiSettingsComponent } from "./settings-tui.js";
 import { isPiFlowHost } from "../runtime/runtime-identity.js";
+import { isWorkerProfile, workersForDelegation } from "../cognitive-routing-v2/types.js";
 const DEFAULT_FREEFLOW_ENABLED = true;
 const DEFAULT_CONTEXT_VIRTUALIZATION_ENABLED = false;
 const DEFAULT_CONVERSATION_HISTORY_ENABLED = false;
@@ -191,6 +192,68 @@ function createScopedBooleanItem(options) {
   item.displaySuffix = coreDisplaySuffix(item);
   return item;
 }
+function createScopedDelegationItem(options) {
+  const path = ["cognitiveRouting", "delegation"];
+  const repositoryValue = getPath(options.rawConfig, path);
+  const inheritedValue = ["executor", "helper", "both"].includes(repositoryValue) ? repositoryValue : "executor";
+  const inheritedSource = repositoryValue === undefined ? "builtin" : "repository";
+  const localValue = getPath(options.localConfig, path);
+  const descriptions = {
+    executor: "Coordinator delegates assignments to Executor.",
+    helper: "Coordinator delegates supporting assignments to Helper and keeps production implementation.",
+    both: "Coordinator chooses Helper or Executor for each assignment.",
+  };
+  const item =
+    options.scope === "local"
+      ? {
+          id: "freeflow.cognitiveRouting.delegation",
+          label: "Delegation method",
+          description:
+            "Choose enabled workers for automatic routing. Inherit uses the repository value; this setting does not rank model presets.",
+          path,
+          kind: "enum",
+          value: ["executor", "helper", "both"].includes(localValue) ? localValue : LOCAL_INHERIT,
+          values: [LOCAL_INHERIT, "executor", "helper", "both"],
+          valueLabels: {
+            inherit: "Inherit repository",
+            executor: "Executor only",
+            helper: "Helper only",
+            both: "Helper and Executor",
+          },
+          valueDescriptions: {
+            inherit: `Use ${inheritedValue} from ${inheritedSource}.`,
+            ...descriptions,
+          },
+          configScope: "local",
+          configValues: { inherit: undefined, executor: "executor", helper: "helper", both: "both" },
+          effectiveValue: options.effectiveValue,
+          effectiveSource: options.effectiveSource,
+          inheritedValue,
+          inheritedSource,
+        }
+      : {
+          id: "freeflow.cognitiveRouting.delegation",
+          label: "Delegation method",
+          description: "Choose enabled workers for automatic routing. This edits shared .freeflow/config.json.",
+          path,
+          kind: "enum",
+          value: inheritedValue,
+          values: ["executor", "helper", "both"],
+          valueLabels: {
+            executor: "Executor only",
+            helper: "Helper only",
+            both: "Helper and Executor",
+          },
+          valueDescriptions: descriptions,
+          defaultValue: "executor",
+          configScope: "repository",
+          effectiveValue: options.effectiveValue,
+          effectiveSource: options.effectiveSource,
+          localOverrideValue: ["executor", "helper", "both"].includes(localValue) ? localValue : undefined,
+        };
+  item.displaySuffix = coreDisplaySuffix(item);
+  return item;
+}
 function resolveSettingsCoreView(rawConfig, layers) {
   const localConfig = layers?.local.valid && isRecord(layers.local.parsed) ? layers.local.parsed : {};
   const fallbackCore = {
@@ -247,7 +310,7 @@ function createSessionBooleanItem(options) {
   item.displaySuffix = coreDisplaySuffix(item);
   return item;
 }
-function sessionFreeflowItems(state, cognitiveRoutingController) {
+function sessionFreeflowItems(state, cognitiveRoutingController, ctx) {
   const sessionOverrides = state.sessionOverrides;
   const configured = state.configuredCoreConfig;
   const configuredSources = state.configuredSources;
@@ -289,47 +352,76 @@ function sessionFreeflowItems(state, cognitiveRoutingController) {
   contextVirtualizationItem.inactive = freeflowInactive;
   conversationHistoryItem.inactive = freeflowInactive;
   const cognitiveRoutingState = cognitiveRoutingController?.state();
-  const cognitiveRoutingProfile =
-    cognitiveRoutingState?.controlMode === "manual-executor"
-      ? "executor"
-      : cognitiveRoutingState?.controlMode === "manual-coordinator"
-        ? "coordinator"
-        : "auto";
+  const delegation = state.cognitiveRouting?.delegation ?? "executor";
+  const heldProfile = cognitiveRoutingState?.controlMode.startsWith("manual-")
+    ? cognitiveRoutingState.activeProfile
+    : undefined;
+  const availableProfiles = ["coordinator", ...workersForDelegation(delegation)];
+  if (heldProfile === "coordinator" || isWorkerProfile(heldProfile)) availableProfiles.push(heldProfile);
+  const manualProfiles = [...new Set(availableProfiles)];
+  const cognitiveRoutingProfile = heldProfile && manualProfiles.includes(heldProfile) ? heldProfile : "auto";
   const cognitiveRoutingItem = state.cognitiveRouting
     ? {
         id: "freeflow.cognitiveRouting.profile",
         label: "Cognitive Routing",
-        description: "Hold a profile manually or release the hold for automatic model control.",
+        description: "Hold an enabled profile manually or release the hold for automatic model control.",
         kind: "enum",
         value: cognitiveRoutingProfile,
-        values: ["auto", "executor", "coordinator"],
-        valueLabels: {
-          auto: "automatic",
-          executor: "manual · executor",
-          coordinator: "manual · coordinator",
-        },
-        valueDescriptions: {
-          auto: "Release the manual hold and return to Coordinator reconciliation.",
-          executor: "Hold the executor profile until /freeflow profile auto.",
-          coordinator: "Hold the coordinator profile until /freeflow profile auto.",
-        },
+        values: ["auto", ...manualProfiles],
+        valueLabels: Object.fromEntries([
+          ["auto", "automatic"],
+          ...manualProfiles.map((profile) => [profile, `manual · ${profile}`]),
+        ]),
+        valueDescriptions: Object.fromEntries([
+          ["auto", "Release the manual hold and return to Coordinator reconciliation."],
+          ...manualProfiles.map((profile) => [profile, `Hold the ${profile} 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;
+  const sessionProfiles = cognitiveRoutingController?.sessionProfileOverrides();
+  const profileItems =
+    state.cognitiveRouting && cognitiveRoutingController
+      ? manualProfiles.map((name) =>
+          cognitiveRoutingProfileItem({
+            name,
+            scope: "session",
+            rawConfig: {},
+            localConfig: {},
+            capabilityState: state.cognitiveRouting,
+            ctx,
+            sessionProfiles,
+          }),
+        )
+      : [];
+  const cognitiveRoutingPresets = profileItems.length
+    ? {
+        id: "freeflow.cognitiveRouting.presets",
+        label: "Cognitive Routing presets",
+        description: "Temporarily choose complete model/effort pairs for profiles enabled in this Pi session.",
+        kind: "group",
+        value: profileItems.some((item) => item.value !== LOCAL_INHERIT && item.value !== undefined),
+        displaySuffix: `${profileItems.filter((item) => item.value !== LOCAL_INHERIT && item.value !== undefined).length}/${profileItems.length} session overrides`,
+        inactive: freeflowInactive || !state.cognitiveRouting?.effective || cognitiveRoutingController === undefined,
+        children: profileItems,
+      }
+    : undefined;
   return [
     freeflowItem,
     ...(cognitiveRoutingItem ? [cognitiveRoutingItem] : []),
+    ...(cognitiveRoutingPresets ? [cognitiveRoutingPresets] : []),
     {
       id: "freeflow.session.reset",
       label: "Reset session overrides",
-      description: "Clear Freeflow, Context Virtualization, and Conversation History overrides for this Pi session.",
+      description:
+        "Clear Freeflow, Context Virtualization, Conversation History, and routing profile overrides for this Pi session.",
       kind: "enum",
       value: "available",
       values: ["reset"],
       valueLabels: { reset: "Reset all session overrides" },
-      valueDescriptions: { reset: "Return every session setting to its configured value." },
+      valueDescriptions: { reset: "Return every session setting and routing preset to its configured value." },
       format: () => "available",
       transient: true,
     },
@@ -412,12 +504,14 @@ function cognitiveRoutingProfileDisplay(value) {
   return isCognitiveRoutingProfile(value) ? formatCoreValue(value) : "not configured";
 }
 function cognitiveRoutingSettingsSource(source) {
+  if (source === "session") return "session";
   if (source === "repository") return "repository";
   if (source === "personal" || source === "local") return "local";
   return "builtin";
 }
 function cognitiveRoutingProfileDisplaySuffix(source, scope) {
   if (!source) return undefined;
+  if (source === "session") return "(session override)";
   if (source === "personal" && scope === "repository") return "(effective personal)";
   return `(${source})`;
 }
@@ -436,7 +530,16 @@ function cognitiveRoutingConfirmStep(summary) {
     selectedKey: "__save__",
   };
 }
-function createCognitiveRoutingProfileWizard(currentValue, models, allowInherit) {
+function createCognitiveRoutingProfileWizard(
+  currentValue,
+  models,
+  allowInherit,
+  inheritChoice = {
+    label: "Inherit repository preset",
+    description: "Remove the personal override without changing the repository preset.",
+    summary: "inherit repository preset",
+  },
+) {
   const currentProfile = isCognitiveRoutingProfile(currentValue) ? currentValue : undefined;
   const currentModelKey = currentProfile
     ? cognitiveRoutingModelKey(currentProfile.provider, currentProfile.model)
@@ -447,8 +550,8 @@ function createCognitiveRoutingProfileWizard(currentValue, models, allowInherit)
           {
             key: LOCAL_INHERIT,
             value: LOCAL_INHERIT,
-            label: "Inherit repository preset",
-            description: "Remove the personal override without changing the repository preset.",
+            label: inheritChoice.label,
+            description: inheritChoice.description,
           },
         ]
       : []),
@@ -482,7 +585,7 @@ function createCognitiveRoutingProfileWizard(currentValue, models, allowInherit)
       if (selectedValues.length === 1) {
         const selected = selectedValues[0];
         if (selected === LOCAL_INHERIT) {
-          return cognitiveRoutingConfirmStep("inherit repository preset");
+          return cognitiveRoutingConfirmStep(inheritChoice.summary);
         }
         const model = selected;
         if (!model?.key || model.thinkingLevels.length === 0) return undefined;
@@ -521,31 +624,59 @@ function cognitiveRoutingProfileItem(options) {
   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 configuredProfile = options.capabilityState?.profiles?.[options.name] ?? repositoryProfile;
+  const sessionPair = options.sessionProfiles?.[options.name];
+  const sessionProfile = sessionPair
+    ? { provider: sessionPair.provider, model: sessionPair.modelId, thinking: sessionPair.thinking }
+    : undefined;
+  const effectiveProfile = sessionProfile ?? configuredProfile;
   const localValue = isCognitiveRoutingProfile(localProfile) ? localProfile : LOCAL_INHERIT;
-  const value = options.scope === "local" ? localValue : repositoryProfile;
-  const source =
+  const value =
+    options.scope === "session"
+      ? (sessionProfile ?? LOCAL_INHERIT)
+      : options.scope === "local"
+        ? localValue
+        : repositoryProfile;
+  const configuredSource =
     options.capabilityState?.profileSources?.[options.name] ??
     (isCognitiveRoutingProfile(repositoryProfile) ? "repository" : undefined);
+  const source = options.scope === "session" ? (sessionProfile ? "session" : configuredSource) : configuredSource;
   const models = cognitiveRoutingModelOptions(options.ctx);
-  const inactive = options.scope === "local" && models.length === 0 && localValue !== LOCAL_INHERIT;
+  const inactive = options.scope !== "repository" && models.length === 0 && value !== LOCAL_INHERIT;
+  const inheritChoice =
+    options.scope === "session"
+      ? {
+          label: "Inherit configured preset",
+          description: "Remove the session override without changing local or repository configuration.",
+          summary: "inherit configured preset",
+        }
+      : undefined;
   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.",
+      options.scope === "session"
+        ? "Temporarily choose the model and effort for this profile in the current Pi session only."
+        : "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,
+    format: (current) => {
+      const inherits = current === LOCAL_INHERIT || (options.scope === "session" && current === undefined);
+      return inherits
+        ? options.scope === "session"
+          ? "inherit configured preset"
+          : "inherit repository preset"
+        : cognitiveRoutingProfileDisplay(current);
+    },
     configScope: options.scope,
     effectiveValue: effectiveProfile,
     effectiveSource: cognitiveRoutingSettingsSource(source),
-    inheritedValue: repositoryProfile,
-    inheritedSource: "repository",
+    inheritedValue: options.scope === "session" ? configuredProfile : repositoryProfile,
+    inheritedSource: cognitiveRoutingSettingsSource(configuredSource ?? "builtin"),
     inactive,
     displaySuffix: cognitiveRoutingProfileDisplaySuffix(source, options.scope),
-    wizard: () => createCognitiveRoutingProfileWizard(value, models, options.scope === "local"),
+    wizard: () => createCognitiveRoutingProfileWizard(value, models, options.scope !== "repository", inheritChoice),
   };
 }
 function isCognitiveRoutingRuntimeAvailable(pi) {
@@ -557,7 +688,7 @@ function isCognitiveRoutingRuntimeAvailable(pi) {
   );
 }
 function freeflowItems(rawConfig, options = {}) {
-  const scope = options.scope ?? "repository";
+  const scope = options.scope === "local" ? "local" : "repository";
   const layers = options.layers;
   const { localConfig, core, sources } = resolveSettingsCoreView(rawConfig, layers);
   const freeflowItem = createScopedBooleanItem({
@@ -618,6 +749,15 @@ function freeflowItems(rawConfig, options = {}) {
     });
     cognitiveRoutingEnabledItem.inactive = freeflowInactive || cognitiveRoutingRuntimeDisabled;
     cognitiveRoutingEnabledItem.runtimeInactive = cognitiveRoutingRuntimeDisabled;
+    const cognitiveRoutingDelegationItem = createScopedDelegationItem({
+      scope,
+      rawConfig,
+      localConfig,
+      effectiveValue: cognitiveRoutingState?.delegation ?? "executor",
+      effectiveSource: cognitiveRoutingSettingsSource(cognitiveRoutingState?.delegationSource),
+    });
+    cognitiveRoutingDelegationItem.inactive = freeflowInactive || cognitiveRoutingRuntimeDisabled;
+    cognitiveRoutingDelegationItem.runtimeInactive = cognitiveRoutingRuntimeDisabled;
     const cognitiveRoutingProjectionItem = createScopedBooleanItem({
       scope,
       rawConfig,
@@ -625,7 +765,7 @@ function freeflowItems(rawConfig, options = {}) {
       id: "freeflow.cognitiveRouting.projection",
       label: "Context projection",
       description:
-        "Select Executor evidence for Coordinator; disable projection to keep ordinary Pi context in both profiles.",
+        "Select worker evidence for Coordinator; disable projection to keep ordinary Pi context in all enabled profiles.",
       path: ["cognitiveRouting", "projection"],
       effectiveValue: cognitiveRoutingState?.projection ?? false,
       effectiveSource: cognitiveRoutingSettingsSource(cognitiveRoutingState?.projectionSource),
@@ -633,7 +773,7 @@ function freeflowItems(rawConfig, options = {}) {
     });
     cognitiveRoutingProjectionItem.inactive = freeflowInactive || cognitiveRoutingRuntimeDisabled;
     cognitiveRoutingProjectionItem.runtimeInactive = cognitiveRoutingRuntimeDisabled;
-    const cognitiveRoutingProfiles = ["executor", "coordinator"].map((name) =>
+    const cognitiveRoutingProfiles = ["coordinator", "helper", "executor"].map((name) =>
       cognitiveRoutingProfileItem({
         name: name,
         scope,
@@ -661,12 +801,17 @@ function freeflowItems(rawConfig, options = {}) {
       label: "Cognitive Routing",
       description: cognitiveRoutingRuntimeDisabled
         ? "Cognitive Routing configuration is visible for inspection but requires a host model-state control API."
-        : "Configure the Executor and Coordinator profiles and choose whether Freeflow may manage model state for this repository.",
+        : "Configure Coordinator, Helper, and Executor profiles plus the workers available for delegation.",
       kind: "group",
       value: cognitiveRoutingRuntimeDisabled ? false : (cognitiveRoutingState?.enabled ?? false),
       inactive: freeflowInactive,
       displaySuffix: cognitiveRoutingStatus,
-      children: [cognitiveRoutingEnabledItem, ...cognitiveRoutingProfiles, cognitiveRoutingProjectionItem],
+      children: [
+        cognitiveRoutingEnabledItem,
+        cognitiveRoutingDelegationItem,
+        ...cognitiveRoutingProfiles,
+        cognitiveRoutingProjectionItem,
+      ],
     };
   })();
   return [
@@ -688,6 +833,7 @@ function pruneKnownDefaults(config) {
     { path: ["enabled"], value: DEFAULT_FREEFLOW_ENABLED },
     { path: ["contextVirtualization"], value: DEFAULT_CONTEXT_VIRTUALIZATION_ENABLED },
     { path: ["conversationHistory"], value: DEFAULT_CONVERSATION_HISTORY_ENABLED },
+    { path: ["cognitiveRouting", "delegation"], value: "executor" },
   ];
   for (const item of defaultPaths) {
     if (valuesEqual(getPath(config, item.path), item.value)) {
@@ -761,7 +907,7 @@ async function updateConfig(cwd, item, value, scope = item.configScope ?? "repos
   await writeFile(join(cwd, ".freeflow/config.json"), `${JSON.stringify(next, null, 2)}\n`, "utf8");
 }
 function isCognitiveRoutingProfileItem(item) {
-  return item.id === "freeflow.cognitiveRouting.executor" || item.id === "freeflow.cognitiveRouting.coordinator";
+  return ["coordinator", "helper", "executor"].some((profile) => item.id === `freeflow.cognitiveRouting.${profile}`);
 }
 function valueForDisplay(item) {
   let value;
@@ -801,10 +947,11 @@ function refreshSettingsDerivedState(items) {
   const freeflowInactive = freeflowItem ? effectiveItemValue(freeflowItem) !== true : false;
   const cognitiveRoutingGroup = findSettingsItem(items, "freeflow.cognitiveRouting");
   const cognitiveRoutingEnabledItem = findSettingsItem(items, "freeflow.cognitiveRouting.enabled");
-  const cognitiveRoutingProfiles = [
-    findSettingsItem(items, "freeflow.cognitiveRouting.executor"),
-    findSettingsItem(items, "freeflow.cognitiveRouting.coordinator"),
-  ];
+  const cognitiveRoutingDelegationItem = findSettingsItem(items, "freeflow.cognitiveRouting.delegation");
+  const delegation = cognitiveRoutingDelegationItem ? effectiveItemValue(cognitiveRoutingDelegationItem) : "executor";
+  const cognitiveRoutingProfiles = ["coordinator", ...workersForDelegation(delegation)].map((profile) =>
+    findSettingsItem(items, `freeflow.cognitiveRouting.${profile}`),
+  );
   if (cognitiveRoutingGroup && cognitiveRoutingEnabledItem) {
     const enabled = effectiveItemValue(cognitiveRoutingEnabledItem) === true;
     const profilesConfigured = cognitiveRoutingProfiles.every((item) =>
@@ -1079,7 +1226,7 @@ export async function handleFreeflowCommand(args, ctx, afterChange, pi, cognitiv
   let reconcileCognitiveRouting = settingsScope === "session";
   const items =
     settingsScope === "session"
-      ? sessionFreeflowItems(state, cognitiveRoutingController)
+      ? sessionFreeflowItems(state, cognitiveRoutingController, ctx)
       : freeflowItems(raw, {
           scope: settingsScope,
           layers,
@@ -1122,8 +1269,61 @@ export async function handleFreeflowCommand(args, ctx, afterChange, pi, cognitiv
         return { changed: true, reloadRequired: false };
       }
       if (item.id === "freeflow.session.reset") {
-        const result = await resetSessionOverrides(ctx, pi);
-        return { changed: result.changed, reloadRequired: result.reloadRequired };
+        const routingResult = cognitiveRoutingController
+          ? await cognitiveRoutingController.resetSessionProfileOverrides("Reset session overrides")
+          : { status: "unchanged" };
+        if (routingResult.status === "blocked" || routingResult.reason) {
+          ctx.ui.notify(
+            `Cognitive Routing session presets could not be reset: ${routingResult.reason ?? routingResult.status}.`,
+            "warning",
+          );
+          return { changed: false, reloadRequired: false };
+        }
+        try {
+          const result = await resetSessionOverrides(ctx, pi);
+          return {
+            changed: result.changed || routingResult.status !== "unchanged",
+            reloadRequired: result.reloadRequired,
+          };
+        } catch (error) {
+          ctx.ui.notify(
+            `Routing presets were reset, but core/context session overrides could not be reset: ${error instanceof Error ? error.message : String(error)}`,
+            "warning",
+          );
+          return {
+            changed: routingResult.status !== "unchanged",
+            reloadRequired: false,
+          };
+        }
+      }
+      if (item.configScope === "session" && isCognitiveRoutingProfileItem(item)) {
+        if (!cognitiveRoutingController) {
+          ctx.ui.notify("Cognitive Routing is unavailable for this session.", "warning");
+          return { changed: false, reloadRequired: false };
+        }
+        const profile = item.id.split(".").at(-1);
+        const override =
+          value === undefined || value === LOCAL_INHERIT
+            ? null
+            : {
+                provider: value.provider,
+                modelId: value.model,
+                thinking: value.thinking,
+              };
+        const result = await cognitiveRoutingController.setSessionProfileOverride(
+          profile,
+          override,
+          "Session profile settings",
+        );
+        if (result.status === "blocked" || result.reason) {
+          ctx.ui.notify(
+            `Cognitive Routing session preset could not be applied: ${result.reason ?? result.status}.`,
+            "warning",
+          );
+          return { changed: false, reloadRequired: false };
+        }
+        await afterChange(false);
+        return { changed: result.status !== "unchanged", reloadRequired: false };
       }
       if (item.configScope === "session") {
         const keyById = {

package/pi-extension/src/cognitive-routing-v2/config.ts

@@ -1,6 +1,18 @@
-import { EFFORTS, PROFILES, canonical, isObject, type Effort, type Pair, type Profile } from "./types.js";
+import {
+  DELEGATION_MODES,
+  EFFORTS,
+  PROFILES,
+  canonical,
+  isObject,
+  workersForDelegation,
+  type DelegationMode,
+  type Effort,
+  type Pair,
+  type Profile,
+} from "./types.js";
 export type CognitiveRoutingProfileName = Profile;
 export type CognitiveRoutingThinkingLevel = Effort;
+export type CognitiveRoutingDelegationMode = DelegationMode;
 export interface CognitiveRoutingProfile {
   provider: string;
   model: string;
@@ -12,6 +24,8 @@ export interface CognitiveRoutingCapabilityState {
   enabled: boolean;
   effective: boolean;
   enabledSource: string;
+  delegation: DelegationMode;
+  delegationSource: string;
   projection: boolean;
   projectionSource: string;
   profiles: Partial<Record<Profile, CognitiveRoutingProfile>>;
@@ -27,24 +41,29 @@ export const pairFromProfile = (profile: CognitiveRoutingProfile): Pair => ({
 });
 function parseLayer(raw: any): any {
   if (raw === undefined) return {};
-  if (!isObject(raw) || Object.keys(raw).some((k) => !["enabled", "projection", "profiles"].includes(k)))
+  if (
+    !isObject(raw) ||
+    Object.keys(raw).some((key) => !["enabled", "delegation", "projection", "profiles"].includes(key))
+  )
     throw new Error(
-      "Routing requires the new enabled/projection/profiles schema; experimental legacy configuration is not migrated.",
+      "Routing requires the enabled/delegation/projection/profiles schema; experimental legacy configuration is not migrated.",
     );
   for (const key of ["enabled", "projection"])
     if (raw[key] !== undefined && typeof raw[key] !== "boolean") throw new Error(`${key} must be boolean.`);
+  if (raw.delegation !== undefined && !DELEGATION_MODES.includes(raw.delegation))
+    throw new Error("delegation must be executor, helper, or both.");
   if (raw.profiles !== undefined) {
-    if (!isObject(raw.profiles) || Object.keys(raw.profiles).some((k) => !PROFILES.includes(k as Profile)))
-      throw new Error("Profiles must be coordinator/executor.");
-    for (const p of Object.values(raw.profiles) as any[]) {
+    if (!isObject(raw.profiles) || Object.keys(raw.profiles).some((key) => !PROFILES.includes(key as Profile)))
+      throw new Error("Profiles must be coordinator, helper, or executor.");
+    for (const profile of Object.values(raw.profiles) as any[]) {
       if (
-        !isObject(p) ||
-        Object.keys(p).some((k) => !["provider", "model", "thinking"].includes(k)) ||
-        typeof p.provider !== "string" ||
-        !p.provider.trim() ||
-        typeof p.model !== "string" ||
-        !p.model.trim() ||
-        !EFFORTS.includes(p.thinking)
+        !isObject(profile) ||
+        Object.keys(profile).some((key) => !["provider", "model", "thinking"].includes(key)) ||
+        typeof profile.provider !== "string" ||
+        !profile.provider.trim() ||
+        typeof profile.model !== "string" ||
+        !profile.model.trim() ||
+        !EFFORTS.includes(profile.thinking)
       )
         throw new Error("Each profile requires provider, model, and supported thinking.");
     }
@@ -62,6 +81,8 @@ export async function resolveCognitiveRoutingState(
     enabled: false,
     effective: false,
     enabledSource: "default",
+    delegation: "executor",
+    delegationSource: "default",
     projection: false,
     projectionSource: "default",
     profiles: {},
@@ -78,6 +99,10 @@ export async function resolveCognitiveRoutingState(
         state.enabled = layer.enabled;
         state.enabledSource = source;
       }
+      if (layer.delegation !== undefined) {
+        state.delegation = layer.delegation;
+        state.delegationSource = source;
+      }
       if (layer.projection !== undefined) {
         state.projection = layer.projection;
         state.projectionSource = source;
@@ -101,7 +126,8 @@ export async function resolveCognitiveRoutingState(
       ...state,
       blockingReason: { code: "host_unsupported", message: "Required public Pi model registry is unavailable." },
     };
-  for (const name of PROFILES) {
+  const requiredProfiles: Profile[] = ["coordinator", ...workersForDelegation(state.delegation)];
+  for (const name of requiredProfiles) {
     const profile = state.profiles[name];
     if (!profile)
       return { ...state, blockingReason: { code: "profile_missing", message: `Configure the ${name} profile.` } };
@@ -134,10 +160,14 @@ export async function resolveCognitiveRoutingState(
       };
     }
   }
-  if (canonical(state.profiles.coordinator) === canonical(state.profiles.executor))
-    return {
-      ...state,
-      blockingReason: { code: "profiles_identical", message: "Configure distinct effective model/effort pairs." },
-    };
+  for (const worker of workersForDelegation(state.delegation))
+    if (canonical(state.profiles.coordinator) === canonical(state.profiles[worker]))
+      return {
+        ...state,
+        blockingReason: {
+          code: "profiles_identical",
+          message: `Configure distinct Coordinator and ${worker} model/effort pairs.`,
+        },
+      };
   return { ...state, effective: true, blockingReason: { code: "", message: "" } };
 }