avorelo 0.1.0

package/scripts/lib/orchestration/routing-policy.js

@@ -0,0 +1,486 @@
+"use strict";
+
+const { detectProfile } = require("./model-profiles");
+
+const COST_SCORE = { free_local: 0, local: 0, low: 1, medium: 2, high: 3, premium: 4, highest: 4, unknown: 2 };
+const QUALITY_SCORE = { deterministic: 5, low: 1, medium: 2, medium_high: 3, high: 4, premium: 5, highest: 5, unknown: 1 };
+const TRUST_SCORE = { local: 5, trusted: 4, unknown: 2, external: 1 };
+const PRIVACY_SCORE = { local_only: 5, trusted_remote: 4, gateway_remote: 2, external_remote: 1, unknown: 1 };
+
+const FALLBACK_REASON_CODES = {
+  WORKER_RECENTLY_LIMITED: "WORKER_RECENTLY_LIMITED",
+  WORKER_NEEDS_LOGIN: "WORKER_NEEDS_LOGIN",
+  WORKER_RECENTLY_FAILED: "WORKER_RECENTLY_FAILED",
+  WORKER_UNAVAILABLE: "WORKER_UNAVAILABLE",
+  LOCAL_WORKER_AVAILABLE: "LOCAL_WORKER_AVAILABLE",
+  LOCAL_WORKER_NOT_RUNNING: "LOCAL_WORKER_NOT_RUNNING",
+  FALLBACK_RECOMMENDED: "FALLBACK_RECOMMENDED",
+  ESCALATION_RECOMMENDED: "ESCALATION_RECOMMENDED",
+  PREMIUM_CONFIRMATION_REQUIRED: "PREMIUM_CONFIRMATION_REQUIRED",
+  LOCAL_PRIVATE_ONLY_MODE: "LOCAL_PRIVATE_ONLY_MODE",
+  SENSITIVE_TASK_BLOCKS_EXTERNAL: "SENSITIVE_TASK_BLOCKS_EXTERNAL",
+};
+
+function isExternalTool(tool) {
+  return tool.privacyTier === "external_remote" || tool.trustTier === "external" || tool.privacyTier === "gateway_remote";
+}
+
+function supportsRole(tool, role) {
+  return Array.isArray(tool.supportedRoles) && tool.supportedRoles.includes(role);
+}
+
+function chooseProfile(tool, task, settings) {
+  const profiles = Array.isArray(tool.candidateProfiles) ? tool.candidateProfiles : [];
+  const confirmed = profiles.find((profile) => profile.availability === "confirmed");
+  if (confirmed) return confirmed;
+  if (task.risk === "low" || task.taskType === "docs") {
+    return profiles.find((profile) => /fast|mini|cheap|flash|summary|local_private/i.test(profile.id)) || profiles[0] || null;
+  }
+  if (task.risk === "high") {
+    return profiles.find((profile) => /high|reason|opus/i.test(profile.id)) || profiles.find((profile) => /default|coding|sonnet/i.test(profile.id)) || profiles[0] || null;
+  }
+  return profiles.find((profile) => /default|coding|sonnet|standard/i.test(profile.id)) || profiles[0] || null;
+}
+
+function chooseModel(tool, task, settings) {
+  const models = Array.isArray(tool.models) ? tool.models : [];
+  if (models.length === 0) return null;
+  const confirmed = models.filter((model) => model.availability === "confirmed");
+  const configured = models.filter((model) => model.availability === "configured");
+  const candidate = models.filter((model) => model.availability === "candidate");
+  const pool = confirmed.length ? confirmed : (configured.length ? configured : candidate);
+  if (task.risk === "high") {
+    return pool.find((model) => model.safeForHighRisk) || pool.find((model) => model.qualityTier === "highest" || model.qualityTier === "high") || null;
+  }
+  if (task.taskType === "docs" || task.risk === "low") {
+    return pool.find((model) => model.costTier === "free_local" || model.costTier === "low") || pool[0] || null;
+  }
+  return pool.find((model) => model.profiles.includes("coding_candidate")) || pool.find((model) => model.qualityTier === "high") || pool[0] || null;
+}
+
+function safeForTask(tool, task, settings) {
+  const reasons = [];
+  if (tool.enabled === false) reasons.push("disabled_by_user");
+  if (["unavailable", "missing", "stale"].includes(tool.workerState) || tool.installStatus === "not_installed") reasons.push("unavailable");
+  if (tool.workerState === "needs_login" || tool.availability === "needs_login") reasons.push("needs_login");
+  if (tool.workerState === "recently_limited") reasons.push("recently_limited");
+  if (tool.workerState === "recently_failed") reasons.push("recently_failed");
+  if (settings.mode === "disabled" || settings.enabled === false) reasons.push("orchestration_disabled");
+
+  if (settings.mode === "local_private_only" && tool.privacyTier !== "local_only" && !["git", "test_runner"].includes(tool.toolId)) {
+    reasons.push("local_private_only_mode");
+  }
+
+  if (task.risk === "high" && !tool.safeForHighRisk && !["git", "test_runner"].includes(tool.toolId)) {
+    reasons.push("not_safe_for_high_risk");
+  }
+
+  if (task.risk === "high" && settings.safety.blockCheapExternalHighRisk && isExternalTool(tool) && ["low", "free_local"].includes(tool.costTier)) {
+    reasons.push("cheap_external_blocked_for_high_risk");
+  }
+
+  if (["secret_risk", "customer_data_risk", "security_sensitive"].includes(task.sensitivity)
+    && settings.safety.blockExternalSecrets
+    && isExternalTool(tool)
+    && !["git", "test_runner"].includes(tool.toolId)) {
+    reasons.push("external_blocked_for_sensitive_task");
+  }
+
+  return {
+    allowed: reasons.every((reason) => ![
+      "disabled_by_user",
+      "unavailable",
+      "needs_login",
+      "orchestration_disabled",
+      "local_private_only_mode",
+      "not_safe_for_high_risk",
+      "cheap_external_blocked_for_high_risk",
+      "external_blocked_for_sensitive_task",
+      "recently_limited",
+      "recently_failed",
+    ].includes(reason)),
+    reasons,
+  };
+}
+
+function scoreTool(tool, role, task, settings, surface) {
+  if (!supportsRole(tool, role)) return -Infinity;
+  const safety = safeForTask(tool, task, settings);
+  if (!safety.allowed) return -Infinity;
+
+  let score = 10;
+  const profile = chooseProfile(tool, task, settings);
+  const model = chooseModel(tool, task, settings);
+  score += QUALITY_SCORE[tool.qualityTier] * (task.risk === "high" ? 3 : 2);
+  score -= COST_SCORE[tool.costTier] * (task.risk === "low" ? 2 : 1);
+  score += TRUST_SCORE[tool.trustTier] * (task.risk === "high" ? 3 : 1);
+  score += PRIVACY_SCORE[tool.privacyTier] * (settings.mode === "local_private_only" ? 3 : 1);
+
+  if (tool.availability === "confirmed") score += 3;
+  if (tool.availability === "configured") score += 2;
+  if (tool.executionMode === "in_session") score += 2;
+  if (surface === "claude_code" && tool.toolId === "claude_code") score += 2;
+  if (surface === "codex_cli" && tool.toolId === "codex") score += 2;
+  if (role === "verify" && ["test_runner", "git"].includes(tool.toolId)) score += 6;
+  if (task.taskType === "docs" && tool.toolId === "codex" && profile?.id === "fast_mini") score += 8;
+  if (["lm_studio", "ollama"].includes(tool.toolId) && settings.mode !== "local_private_only") score -= 6;
+  if (task.taskType === "security" && ["claude_code", "codex", "git", "test_runner"].includes(tool.toolId)) score += 4;
+  if (task.taskType === "docs" && ["lm_studio", "ollama"].includes(tool.toolId) && settings.mode === "local_private_only") score += 2;
+  if (model?.profiles?.includes("coding_candidate") && task.risk !== "high") score += 2;
+  if (settings.mode === "prefer_highest_quality") score += QUALITY_SCORE[tool.qualityTier] * 2;
+  return score;
+}
+
+function rankTools(tools, role, task, settings, surface) {
+  return tools
+    .map((tool) => ({
+      tool,
+      profile: chooseProfile(tool, task, settings),
+      model: chooseModel(tool, task, settings),
+      score: scoreTool(tool, role, task, settings, surface),
+      safety: safeForTask(tool, task, settings),
+    }))
+    .sort((a, b) => b.score - a.score);
+}
+
+function describeWhyChosen(selected, task, settings, role) {
+  const reasons = [];
+  reasons.push(`${selected.tool.label} is available for ${role}`);
+  if (selected.model?.modelId) reasons.push(`model ${selected.model.modelId} is available`);
+  if (task.risk === "high") reasons.push("high-risk work prefers trusted higher-quality paths");
+  if (settings.mode === "prefer_lowest_cost" || task.risk === "low") reasons.push("cost was optimized only after safety and capability checks");
+  if (settings.mode === "local_private_only") reasons.push("local/private-only mode restricted external routes");
+  if (selected.tool.executionMode === "in_session") reasons.push("the current surface can continue without a brittle external handoff");
+  if (selected.profile?.id) reasons.push(`profile ${selected.profile.id} matched the task quality/cost target`);
+  return reasons;
+}
+
+function describeWhyNotChosen(rankings, selectedToolId) {
+  return rankings
+    .filter((entry) => entry.tool.toolId !== selectedToolId)
+    .slice(0, 6)
+    .map((entry) => {
+      const safetyReason = entry.safety.reasons[0];
+      if (safetyReason) return `${entry.tool.label} was not chosen because ${safetyReason.replace(/_/g, " ")}`;
+      return `${entry.tool.label} was available but scored lower for this task`;
+    });
+}
+
+function blockedOptions(tools, task, settings) {
+  return tools
+    .map((tool) => ({ tool, safety: safeForTask(tool, task, settings), model: chooseModel(tool, task, settings) }))
+    .filter((entry) => !entry.safety.allowed || entry.safety.reasons.length > 0)
+    .map((entry) => ({
+      toolId: entry.tool.toolId,
+      label: entry.tool.label,
+      modelId: entry.model?.modelId || null,
+      reasons: entry.safety.reasons,
+    }));
+}
+
+function deriveQuotaSignal(tool) {
+  if (tool.workerState === "recently_limited") return "limited";
+  if (tool.quotaSignal === "local" || tool.costTier === "free_local") return "local";
+  if (tool.availability === "confirmed" || tool.availability === "configured") return "healthy";
+  return "unknown";
+}
+
+function deriveFallbackReasonCodes(tools, task, settings) {
+  const codes = [];
+  const localAvailable = tools.some((t) =>
+    ["lm_studio", "ollama"].includes(t.toolId) &&
+    !["unavailable", "missing"].includes(t.workerState)
+  );
+  const localNotRunning = tools.some((t) =>
+    ["lm_studio", "ollama"].includes(t.toolId) &&
+    t.installStatus === "installed_or_configured_but_not_running"
+  );
+  if (localAvailable) codes.push(FALLBACK_REASON_CODES.LOCAL_WORKER_AVAILABLE);
+  if (localNotRunning) codes.push(FALLBACK_REASON_CODES.LOCAL_WORKER_NOT_RUNNING);
+
+  tools.forEach((t) => {
+    if (t.workerState === "recently_limited") codes.push(FALLBACK_REASON_CODES.WORKER_RECENTLY_LIMITED);
+    if (t.workerState === "needs_login") codes.push(FALLBACK_REASON_CODES.WORKER_NEEDS_LOGIN);
+    if (t.workerState === "recently_failed") codes.push(FALLBACK_REASON_CODES.WORKER_RECENTLY_FAILED);
+    if (["unavailable", "missing"].includes(t.workerState) && t.toolId !== "test_runner" && t.toolId !== "git") {
+      codes.push(FALLBACK_REASON_CODES.WORKER_UNAVAILABLE);
+    }
+  });
+
+  if (task.risk === "high") codes.push(FALLBACK_REASON_CODES.ESCALATION_RECOMMENDED);
+  if (settings.mode === "local_private_only") codes.push(FALLBACK_REASON_CODES.LOCAL_PRIVATE_ONLY_MODE);
+  if (["secret_risk", "customer_data_risk", "security_sensitive"].includes(task.sensitivity)) {
+    codes.push(FALLBACK_REASON_CODES.SENSITIVE_TASK_BLOCKS_EXTERNAL);
+  }
+
+  return [...new Set(codes)];
+}
+
+function buildLocalWorkerRecommendation(tools, task) {
+  const localWorkers = tools.filter((t) =>
+    ["lm_studio", "ollama"].includes(t.toolId) &&
+    !["unavailable", "missing", "recently_failed"].includes(t.workerState)
+  );
+  if (!localWorkers.length) return null;
+  const available = localWorkers.filter((t) => t.workerState !== "recently_limited");
+  if (!available.length) return null;
+  const w = available[0];
+  return {
+    workerId: w.toolId,
+    label: w.label,
+    recommendedFor: ["inspect", "summarize", "repo_reading", "planning"].filter((role) =>
+      (w.supportedRoles || []).includes(role) || ["planning", "summaries", "repo_reading"].some((r) => (w.supportedRoles || []).includes(r))
+    ),
+    costTier: w.costTier,
+    quotaSignal: deriveQuotaSignal(w),
+    reason: "local worker is available and safe for low-sensitivity inspection/planning stages",
+  };
+}
+
+function buildStage(id, role, selected, fallback, task, settings, routeSummary, extras = {}) {
+  return {
+    id,
+    role,
+    state: "pending",
+    chosenTool: selected.tool.toolId,
+    chosenLabel: selected.tool.label,
+    chosenModel: selected.model?.modelId || selected.tool.activeModel || null,
+    chosenModelProfile: selected.profile?.id || selected.tool.activeProfile || selected.tool.activeModel || "unknown",
+    executionMode: selected.tool.executionMode,
+    fallbackTool: fallback?.tool.toolId || null,
+    fallbackModel: fallback?.model?.modelId || fallback?.tool.activeModel || null,
+    fallbackModelProfile: fallback?.profile?.id || fallback?.tool.activeProfile || fallback?.tool.activeModel || null,
+    whyChosen: describeWhyChosen(selected, task, settings, role),
+    safetyNotes: routeSummary.safetyNotes,
+    requiresConfirmation: routeSummary.requiresConfirmation,
+    quotaSignal: deriveQuotaSignal(selected.tool),
+    ...extras,
+  };
+}
+
+function planRoute({ taskText, task, inventory, settings, surface = "avorelo_cli" }) {
+  const tools = Array.isArray(inventory?.tools) ? inventory.tools : [];
+  const blocked = blockedOptions(tools, task, settings);
+
+  if (settings.mode === "disabled" || settings.enabled === false) {
+    return {
+      routeVersion: 2,
+      state: "blocked",
+      selectedRoute: "disabled",
+      stageList: [],
+      chosenTool: null,
+      selectedModel: null,
+      chosenModelProfile: null,
+      fallbackTool: null,
+      fallbackModel: null,
+      fallbackModelProfile: null,
+      whyChosen: ["Orchestration is disabled in settings"],
+      whyNotChosen: [],
+      blockedOptions: blocked,
+      expectedVerification: [],
+      safetyNotes: ["Avorelo will not route or hand off work while orchestration is disabled."],
+      requiresConfirmation: false,
+      externalModelInvolved: false,
+      premiumUseInvolved: false,
+      inventorySource: inventory?.inventorySource || "cache",
+      cacheUsed: inventory?.inventorySource === "cache",
+      lastFullModelRefreshAt: inventory?.lastFullModelRefreshAt || null,
+      nextFullModelRefreshAfter: inventory?.nextFullModelRefreshAfter || null,
+      refreshLevel: inventory?.refreshLevel || "cache",
+      task,
+      taskText,
+      surface,
+    };
+  }
+
+  const fallbackReasonCodes = deriveFallbackReasonCodes(tools, task, settings);
+  const localWorkerRecommendation = buildLocalWorkerRecommendation(tools, task);
+
+  const planRoleNeeded = task.risk !== "high" && task.taskType !== "docs";
+  const needsInspectStage = task.taskType !== "docs" && task.contextNeed !== "small";
+  const needsSecurityReview = task.taskType === "security" || task.sensitivity === "security_sensitive" || task.risk === "high";
+  const implementationRole = task.taskType === "docs" ? "docs" : (task.taskType === "tests" ? "tests" : "implementation");
+  const planningRank = rankTools(tools, "planning", task, settings, surface);
+  const implementationRank = rankTools(tools, implementationRole, task, settings, surface);
+  const verificationRank = rankTools(tools, "verify", task, settings, surface);
+  const reviewRank = rankTools(tools, "review", task, settings, surface);
+  const summaryRank = rankTools(tools, "summaries", task, settings, surface);
+  const securityRank = rankTools(tools, "security", task, settings, surface);
+
+  const selectedPlan = planRoleNeeded ? planningRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity) : null;
+  const selectedImplement = implementationRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity);
+  const selectedVerify = verificationRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity);
+  const selectedFallback = reviewRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity && entry.tool.toolId !== selectedImplement?.tool.toolId)
+    || implementationRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity && entry.tool.toolId !== selectedImplement?.tool.toolId);
+  const selectedSummary = summaryRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity);
+  const selectedSecurityReview = needsSecurityReview ? (securityRank.find((entry) => Number.isFinite(entry.score) && entry.score > -Infinity && entry.tool.toolId !== selectedImplement?.tool.toolId) || selectedFallback) : null;
+
+  if (!selectedImplement) {
+    return {
+      routeVersion: 2,
+      state: tools.length ? "blocked" : "unavailable",
+      selectedRoute: task.risk === "high" ? "high_risk_blocked" : "no_capable_worker",
+      stageList: [],
+      chosenTool: null,
+      selectedModel: null,
+      chosenModelProfile: null,
+      fallbackTool: null,
+      fallbackModel: null,
+      fallbackModelProfile: null,
+      whyChosen: [],
+      whyNotChosen: describeWhyNotChosen(implementationRank, null),
+      blockedOptions: blocked,
+      expectedVerification: ["git diff"],
+      safetyNotes: task.risk === "high"
+        ? ["Cheap or untrusted workers were blocked for this high-risk task."]
+        : ["No installed worker met the current safety/capability requirements."],
+      requiresConfirmation: false,
+      externalModelInvolved: false,
+      premiumUseInvolved: false,
+      inventorySource: inventory?.inventorySource || "cache",
+      cacheUsed: inventory?.inventorySource === "cache",
+      lastFullModelRefreshAt: inventory?.lastFullModelRefreshAt || null,
+      nextFullModelRefreshAfter: inventory?.nextFullModelRefreshAfter || null,
+      refreshLevel: inventory?.refreshLevel || "cache",
+      task,
+      taskText,
+      surface,
+    };
+  }
+
+  const premiumUseInvolved = ["high", "highest"].includes(selectedImplement.tool.costTier) || /high_reasoning|opus/i.test(selectedImplement.profile?.id || "");
+  const externalModelInvolved = isExternalTool(selectedImplement.tool) || (selectedPlan ? isExternalTool(selectedPlan.tool) : false) || (selectedFallback ? isExternalTool(selectedFallback.tool) : false);
+  const requiresConfirmation = Boolean(settings.askBeforePremium || settings.mode === "ask_before_premium") && premiumUseInvolved;
+  const safetyNotes = [];
+  if (task.risk === "high") safetyNotes.push("High-risk tasks block cheap external workers by default.");
+  if (["secret_risk", "customer_data_risk", "security_sensitive"].includes(task.sensitivity)) {
+    safetyNotes.push("External routing stays blocked when secrets, customer data, or security-sensitive scope is detected.");
+  }
+  if (settings.mode === "local_private_only") safetyNotes.push("Only local/private workers were considered.");
+  if (settings.safety.stopAfterRepeatedFailures) safetyNotes.push("Repeated worker failures stop or escalate instead of looping.");
+
+  const routeSummary = { requiresConfirmation, safetyNotes };
+  const stageList = [];
+
+  if (needsInspectStage && selectedSummary) {
+    stageList.push(buildStage("inspect", "summaries", selectedSummary, selectedPlan || null, task, settings, routeSummary, {
+      taskSlice: "Inspect repo structure, changed files, and relevant context",
+      contextNeed: "small",
+      reasoningNeed: "low",
+    }));
+  }
+
+  if (selectedPlan) {
+    stageList.push(buildStage("plan", "planning", selectedPlan, selectedFallback, task, settings, routeSummary, {
+      taskSlice: "Plan implementation approach, identify affected files and tests",
+      contextNeed: task.risk === "high" ? "large" : "medium",
+      reasoningNeed: task.risk === "high" ? "high" : "medium",
+    }));
+  }
+
+  stageList.push(buildStage("implement", implementationRole, selectedImplement, selectedFallback, task, settings, routeSummary, {
+    taskSlice: "Implement the changes with tests",
+    contextNeed: "large",
+    reasoningNeed: task.risk === "high" ? "high" : "medium",
+  }));
+
+  if (selectedVerify) {
+    stageList.push(buildStage("verify", "verify", selectedVerify, null, task, settings, routeSummary, {
+      taskSlice: "Run deterministic verification: tests, lint, git diff",
+      contextNeed: "small",
+      reasoningNeed: "low",
+    }));
+  }
+
+  if (needsSecurityReview && selectedSecurityReview) {
+    stageList.push(buildStage("security_review", "security", selectedSecurityReview, null, task, settings, routeSummary, {
+      taskSlice: "Security review: check for regressions in safety/governance/safe-path",
+      contextNeed: "medium",
+      reasoningNeed: "high",
+    }));
+  }
+
+  if (task.risk === "high" && selectedFallback) {
+    stageList.push(buildStage("review", "review", selectedFallback, null, task, settings, routeSummary, {
+      taskSlice: "Final review and merge readiness check",
+      contextNeed: "medium",
+      reasoningNeed: "high",
+    }));
+  }
+
+  if (selectedImplement.tool.executionMode === "handoff") {
+    stageList.push({
+      id: "handoff",
+      role: "handoff",
+      state: "pending",
+      chosenTool: "avorelo_handoff",
+      chosenLabel: "Avorelo handoff prompt",
+      chosenModel: null,
+      chosenModelProfile: "compact_handoff",
+      executionMode: "local_command",
+      fallbackTool: null,
+      fallbackModel: null,
+      fallbackModelProfile: null,
+      whyChosen: ["A handoff is needed to pass context to the next worker/session"],
+      safetyNotes: routeSummary.safetyNotes,
+      requiresConfirmation: false,
+      quotaSignal: "local",
+      taskSlice: "Generate compact handoff prompt for next worker/session",
+      contextNeed: "small",
+      reasoningNeed: "low",
+    });
+  }
+
+  const limitedWorkers = tools.filter((t) => t.workerState === "recently_limited").map((t) => ({
+    toolId: t.toolId,
+    label: t.label,
+    reasonCode: FALLBACK_REASON_CODES.WORKER_RECENTLY_LIMITED,
+  }));
+
+  const localWorkersAvailable = tools.filter((t) =>
+    ["lm_studio", "ollama"].includes(t.toolId) &&
+    !["unavailable", "missing"].includes(t.workerState)
+  ).map((t) => t.toolId);
+
+  const state = selectedVerify ? (selectedImplement.tool.executionMode === "handoff" ? "partial" : "ready") : "partial";
+  return {
+    routeVersion: 3,
+    state,
+    selectedRoute: `${task.risk}_${settings.mode}`,
+    stageList,
+    stageCount: stageList.length,
+    chosenTool: selectedImplement.tool.toolId,
+    selectedModel: selectedImplement.model?.modelId || selectedImplement.tool.activeModel || null,
+    chosenModelProfile: selectedImplement.profile?.id || selectedImplement.tool.activeProfile || selectedImplement.tool.activeModel || "unknown",
+    fallbackTool: selectedFallback?.tool.toolId || null,
+    fallbackModel: selectedFallback?.model?.modelId || selectedFallback?.tool.activeModel || null,
+    fallbackModelProfile: selectedFallback?.profile?.id || selectedFallback?.tool.activeProfile || selectedFallback?.tool.activeModel || null,
+    whyChosen: describeWhyChosen(selectedImplement, task, settings, implementationRole),
+    whyNotChosen: describeWhyNotChosen(implementationRank, selectedImplement.tool.toolId),
+    blockedOptions: blocked,
+    expectedVerification: selectedVerify ? [`${selectedVerify.tool.label} deterministic verification`] : ["Verification is currently insufficient; Avorelo will still capture proof."],
+    safetyNotes,
+    requiresConfirmation,
+    externalModelInvolved,
+    premiumUseInvolved,
+    selectionReason: describeWhyChosen(selectedImplement, task, settings, implementationRole),
+    fallbackReasonCodes,
+    limitedWorkers,
+    localWorkersAvailable,
+    localWorkerRecommendation,
+    handoffAvailable: selectedImplement.tool.executionMode === "handoff",
+    inventorySource: inventory?.inventorySource || "cache",
+    cacheUsed: inventory?.inventorySource === "cache",
+    lastFullModelRefreshAt: inventory?.lastFullModelRefreshAt || null,
+    nextFullModelRefreshAfter: inventory?.nextFullModelRefreshAfter || null,
+    refreshLevel: inventory?.refreshLevel || "cache",
+    task,
+    taskText,
+    surface,
+  };
+}
+
+module.exports = {
+  planRoute,
+  FALLBACK_REASON_CODES,
+};

package/scripts/lib/orchestration/settings.js

@@ -0,0 +1,112 @@
+"use strict";
+
+const { readProjectConfig, writeProjectConfig, ORCHESTRATION_WORKER_IDS } = require("../config");
+
+const MODE_LABELS = {
+  auto_recommended: "Auto recommended",
+  prefer_lowest_cost: "Prefer lower cost",
+  prefer_highest_quality: "Prefer highest quality",
+  local_private_only: "Local/private only",
+  ask_before_premium: "Ask before premium tools",
+  premium_only_for_risky: "Premium only for risky",
+  disabled: "Disable orchestration",
+};
+
+function getSettings(cwd) {
+  return readProjectConfig(cwd).orchestration;
+}
+
+function updateSettings(cwd, mutator) {
+  const config = readProjectConfig(cwd);
+  const next = mutator(config);
+  return writeProjectConfig(cwd, next).orchestration;
+}
+
+function setMode(cwd, mode) {
+  return updateSettings(cwd, (config) => ({
+    ...config,
+    orchestration: {
+      ...config.orchestration,
+      mode,
+      enabled: mode !== "disabled",
+      askBeforePremium: mode === "ask_before_premium" ? true : config.orchestration.askBeforePremium,
+    },
+  }));
+}
+
+function setBooleanFlag(cwd, keyPath, value) {
+  return updateSettings(cwd, (config) => {
+    const next = { ...config, orchestration: { ...config.orchestration, safety: { ...(config.orchestration?.safety || {}) } } };
+    if (keyPath === "askBeforePremium") {
+      next.orchestration.askBeforePremium = value;
+    } else {
+      next.orchestration.safety[keyPath] = value;
+    }
+    return next;
+  });
+}
+
+function setWorkerEnabled(cwd, workerId, enabled) {
+  if (!ORCHESTRATION_WORKER_IDS.includes(workerId)) {
+    throw new Error(`Unknown orchestration worker: ${workerId}`);
+  }
+  return updateSettings(cwd, (config) => ({
+    ...config,
+    orchestration: {
+      ...config.orchestration,
+      allowedWorkers: {
+        ...(config.orchestration?.allowedWorkers || {}),
+        [workerId]: enabled,
+      },
+    },
+  }));
+}
+
+function formatSettingsText(settings, inventory = null) {
+  const lines = [
+    "Avorelo Orchestration Settings",
+    `Mode: ${MODE_LABELS[settings.mode] || settings.mode}`,
+    `Ask before premium: ${settings.askBeforePremium ? "on" : "off"}`,
+    `Block cheap external models for high-risk tasks: ${settings.safety.blockCheapExternalHighRisk ? "on" : "off"}`,
+    `Block external models for secrets/customer-data risk: ${settings.safety.blockExternalSecrets ? "on" : "off"}`,
+    `Stop after repeated failures: ${settings.safety.stopAfterRepeatedFailures ? "on" : "off"}`,
+    `Require proof before completion: ${settings.safety.requireProofBeforeCompletion ? "on" : "off"}`,
+    `Full model refresh interval: ${settings.refreshPolicy?.fullRefreshIntervalHours || 72}h`,
+    `Single-model refresh on new usage: ${settings.refreshPolicy?.singleModelRefreshOnNewUsage !== false ? "on" : "off"}`,
+    "",
+    "Allowed workers:",
+    ...ORCHESTRATION_WORKER_IDS.map((workerId) => `- ${workerId}: ${settings.allowedWorkers[workerId] !== false ? "enabled" : "disabled"}`),
+  ];
+
+  if (inventory && Array.isArray(inventory.tools)) {
+    lines.push("", "Advanced detected tools/models:");
+    inventory.tools.forEach((tool) => {
+      lines.push(
+        `- ${tool.label}: ${tool.installStatus}/${tool.availability} · active ${tool.activeModel || tool.activeProfile || "unknown"} · roles ${(tool.supportedRoles || []).join(", ") || "n/a"} · cost ${tool.costTier} · trust ${tool.trustTier} · quota ${tool.quotaSignal}`
+      );
+    });
+  }
+
+  return lines.join("\n");
+}
+
+function settingsMetadata(settings) {
+  return {
+    currentMode: settings.mode,
+    options: Object.entries(MODE_LABELS).map(([value, label]) => ({ value, label })),
+    askBeforePremium: settings.askBeforePremium,
+    safety: settings.safety,
+    allowedWorkers: settings.allowedWorkers,
+    refreshPolicy: settings.refreshPolicy,
+  };
+}
+
+module.exports = {
+  MODE_LABELS,
+  getSettings,
+  setMode,
+  setBooleanFlag,
+  setWorkerEnabled,
+  formatSettingsText,
+  settingsMetadata,
+};