{"record":{"id":"f92f63563a0d8dde","repo":"ruvnet/ruflo","slug":"selectagentbackend-pod-preferlocalexecution-must","errorCode":null,"errorMessage":"selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)","messagePattern":"selectAgentBackend: pod\\.preferLocalExecution must be boolean \\(validate via pod-schema first\\)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/business-pods/domain-affinity-policy.ts","lineNumber":56,"sourceCode":"export interface BackendDecision {\n  backend: AgentBackend;\n  reason: string;\n}\n\n/**\n * Decide which backend `@metaharness/router` should prefer for a pod tick.\n *\n * @param pod  A validated PodTemplate. Validation is the caller's\n *             responsibility; this function will throw on malformed input\n *             (specifically on missing `preferLocalExecution` or\n *             `budgetUsdMonthly`).\n */\nexport function selectAgentBackend(pod: PodTemplate): BackendDecision {\n  if (pod === null || typeof pod !== 'object') {\n    throw new TypeError('selectAgentBackend: pod must be a validated PodTemplate object');\n  }\n  if (typeof pod.preferLocalExecution !== 'boolean') {\n    throw new TypeError(\n      'selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)',\n    );\n  }\n  if (typeof pod.budgetUsdMonthly !== 'number' || !Number.isFinite(pod.budgetUsdMonthly)) {\n    throw new TypeError(\n      'selectAgentBackend: pod.budgetUsdMonthly must be a finite number (validate via pod-schema first)',\n    );\n  }\n\n  if (pod.preferLocalExecution) {\n    return {\n      backend: 'local-stdio',\n      reason: `pod \"${pod.name}\" preferLocalExecution=true — domain-affinity policy pins to local stdio`,\n    };\n  }\n  if (pod.budgetUsdMonthly >= CLOUD_BUDGET_THRESHOLD_USD) {\n    return {\n      backend: 'cloud-managed',","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/business-pods/domain-affinity-policy.ts#L38-L74","documentation":"TypeError in selectAgentBackend() when pod.preferLocalExecution is present but not a boolean (e.g., a string \"true\", a number, or undefined). The field is the primary routing switch (true pins to local-stdio). A non-boolean value means the pod object was constructed or parsed without running validatePodTemplate(), which enforces the boolean type.","triggerScenarios":"Calling selectAgentBackend(pod) where pod is an object but pod.preferLocalExecution is a string (\"true\"/\"false\" from a YAML parser without boolean coercion), undefined, or a number.","commonSituations":"A YAML pod template with `preferLocalExecution: \"true\"` (quoted string); a hand-built PodTemplate object that omitted the field; a JSON source where the field was written as 1/0.","solutions":["Run validatePodTemplate() on the pod — requireBoolean() enforces typeof === 'boolean' and throws PodTemplateValidationError with a clear path","If building the object in code, set preferLocalExecution to a literal true/false, never a string or number"],"exampleFix":"// before (YAML parsed preferLocalExecution as string \"true\"):\nselectAgentBackend({ ...pod, preferLocalExecution: \"true\" }); // throws\n\n// after:\nconst pod = validatePodTemplate(parsed);\nselectAgentBackend(pod); // preferLocalExecution is now boolean true","handlingStrategy":"validation","validationCode":"import { validatePodTemplate } from '@claude-flow/cli/business-pods/pod-schema';\n\n// validatePodTemplate's requireBoolean() enforces typeof === 'boolean'\n// for preferLocalExecution, so selectAgentBackend's boolean check is\n// only a belt-and-suspenders guard.\nconst pod = validatePodTemplate(parsedJson);\nselectAgentBackend(pod);","typeGuard":"function hasValidPreferLocalExecution(pod: unknown): boolean {\n  return typeof pod === 'object' && pod !== null\n    && typeof (pod as { preferLocalExecution?: unknown }).preferLocalExecution === 'boolean';\n}","tryCatchPattern":null,"preventionTips":["Validate pod templates via validatePodTemplate() before routing","When building PodTemplate objects in code, assign literal true/false — never strings or numbers","If loading from YAML, verify the parser coerces booleans (or pre-coerce explicitly)"],"tags":["routing","validation","pod-template","type-coercion"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}