avorelo 0.1.0

package/scripts/lib/orchestration/model-profiles.js

@@ -0,0 +1,252 @@
+"use strict";
+
+const { normalizeModelIdLower, inferProfilesFromModelId } = require("./model-profiler");
+
+const PROFILE_CATALOG = {
+  claude_code: [
+    {
+      id: "haiku",
+      provider: "anthropic",
+      label: "Haiku / cheap profile",
+      modelHints: ["haiku"],
+      costTier: "low",
+      qualityTier: "medium",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["planning", "docs", "tests"],
+    },
+    {
+      id: "sonnet",
+      provider: "anthropic",
+      label: "Sonnet profile",
+      modelHints: ["sonnet", "standard_quality"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["planning", "implementation", "review", "security", "ui", "cli", "tests", "docs"],
+    },
+    {
+      id: "opus",
+      provider: "anthropic",
+      label: "Opus profile",
+      modelHints: ["opus", "deep_reasoning"],
+      costTier: "high",
+      qualityTier: "highest",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["implementation", "review", "security", "refactor"],
+    },
+  ],
+  codex: [
+    {
+      id: "fast_mini",
+      provider: "openai",
+      label: "Fast / mini profile",
+      modelHints: ["mini", "nano", "fast", "fast_low_cost"],
+      costTier: "low",
+      qualityTier: "medium",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["planning", "docs", "tests"],
+    },
+    {
+      id: "default_coding",
+      provider: "openai",
+      label: "Default coding profile",
+      modelHints: ["gpt-5", "codex", "o4", "default", "standard_quality", "coding_candidate"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["planning", "implementation", "review", "ui", "cli", "tests", "refactor", "docs"],
+    },
+    {
+      id: "high_reasoning",
+      provider: "openai",
+      label: "Higher-reasoning profile",
+      modelHints: ["reason", "o3", "high", "deep_reasoning"],
+      costTier: "high",
+      qualityTier: "highest",
+      trustTier: "trusted",
+      privacyTier: "trusted_remote",
+      supportedRoles: ["implementation", "review", "security", "refactor"],
+    },
+  ],
+  gemini_cli: [
+    {
+      id: "flash",
+      provider: "google",
+      label: "Flash / cheap profile",
+      modelHints: ["flash", "fast_low_cost"],
+      costTier: "low",
+      qualityTier: "medium",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "docs", "tests", "ui"],
+    },
+    {
+      id: "pro",
+      provider: "google",
+      label: "Pro / long-context profile",
+      modelHints: ["pro", "standard_quality", "deep_reasoning"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "implementation", "tests", "ui", "docs"],
+    },
+  ],
+  lm_studio: [
+    {
+      id: "local_summary",
+      provider: "lm_studio",
+      label: "Local/private summary profile",
+      modelHints: ["chat_candidate", "standard_quality"],
+      costTier: "free_local",
+      qualityTier: "unknown",
+      trustTier: "local",
+      privacyTier: "local_only",
+      supportedRoles: ["planning", "docs", "tests", "summaries"],
+    },
+    {
+      id: "local_coding",
+      provider: "lm_studio",
+      label: "Local/private coding profile",
+      modelHints: ["coding_candidate"],
+      costTier: "free_local",
+      qualityTier: "medium",
+      trustTier: "local",
+      privacyTier: "local_only",
+      supportedRoles: ["planning", "docs", "tests", "implementation", "refactor", "cli", "summaries"],
+    },
+  ],
+  opencode: [
+    {
+      id: "cheap_coding",
+      provider: "opencode",
+      label: "Cheap coding profile",
+      modelHints: ["cheap", "mini", "flash", "fast_low_cost"],
+      costTier: "low",
+      qualityTier: "medium",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "docs", "tests"],
+    },
+    {
+      id: "standard_coding",
+      provider: "opencode",
+      label: "Standard coding profile",
+      modelHints: ["sonnet", "gpt", "default", "standard", "coding_candidate", "standard_quality"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "implementation", "tests", "docs", "ui", "cli"],
+    },
+  ],
+  aider: [
+    {
+      id: "repo_edit",
+      provider: "aider",
+      label: "Repo editing profile",
+      modelHints: ["aider", "default", "coding_candidate"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["implementation", "refactor", "tests", "cli"],
+    },
+  ],
+  ollama: [
+    {
+      id: "local_private",
+      provider: "ollama",
+      label: "Local/private profile",
+      modelHints: ["chat_candidate", "standard_quality"],
+      costTier: "free_local",
+      qualityTier: "unknown",
+      trustTier: "local",
+      privacyTier: "local_only",
+      supportedRoles: ["planning", "docs", "tests", "summaries"],
+    },
+    {
+      id: "local_private_coding",
+      provider: "ollama",
+      label: "Local/private coding profile",
+      modelHints: ["coding_candidate"],
+      costTier: "free_local",
+      qualityTier: "medium",
+      trustTier: "local",
+      privacyTier: "local_only",
+      supportedRoles: ["planning", "docs", "tests", "implementation", "summaries"],
+    },
+  ],
+  openrouter_api: [
+    {
+      id: "cheap_external",
+      provider: "openrouter",
+      label: "Cheap external profile",
+      modelHints: ["cheap", "mini", "free", "fast_low_cost"],
+      costTier: "low",
+      qualityTier: "medium",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "docs", "tests"],
+    },
+    {
+      id: "fallback_external",
+      provider: "openrouter",
+      label: "Fallback external profile",
+      modelHints: ["sonnet", "gpt", "claude", "coder", "coding_candidate", "standard_quality"],
+      costTier: "medium",
+      qualityTier: "high",
+      trustTier: "external",
+      privacyTier: "external_remote",
+      supportedRoles: ["planning", "implementation", "docs", "tests"],
+    },
+  ],
+  litellm_requesty: [
+    {
+      id: "gateway_candidate",
+      provider: "gateway",
+      label: "Gateway candidate profile",
+      modelHints: ["gateway", "router", "proxy", "standard_quality"],
+      costTier: "medium",
+      qualityTier: "unknown",
+      trustTier: "unknown",
+      privacyTier: "gateway_remote",
+      supportedRoles: ["planning", "implementation", "docs", "tests"],
+    },
+  ],
+};
+
+function getProfiles(toolId) {
+  return (PROFILE_CATALOG[toolId] || []).map((profile) => ({ ...profile }));
+}
+
+function detectProfile(toolId, modelId) {
+  const normalized = normalizeModelIdLower(modelId);
+  if (!normalized) return null;
+  const inferred = inferProfilesFromModelId(modelId);
+  return getProfiles(toolId).find((profile) => {
+    const hints = (profile.modelHints || []).map((hint) => String(hint).toLowerCase());
+    return hints.some((hint) => normalized.includes(hint) || inferred.includes(hint));
+  }) || null;
+}
+
+function buildProfileSummary(toolId, activeModel) {
+  const profiles = getProfiles(toolId);
+  const active = detectProfile(toolId, activeModel);
+  return profiles.map((profile) => ({
+    ...profile,
+    availability: active && active.id === profile.id ? "confirmed" : "candidate",
+  }));
+}
+
+module.exports = {
+  PROFILE_CATALOG,
+  getProfiles,
+  detectProfile,
+  buildProfileSummary,
+};

package/scripts/lib/orchestration/model-refresh-policy.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const fs = require("fs");
+const { getCurrentPaths, safeReadJson, writeJson } = require("./state");
+
+const INVENTORY_SCHEMA_VERSION = 3;
+const DEFAULT_FULL_REFRESH_INTERVAL_HOURS = 72;
+const LOCK_TTL_MS = 10 * 60 * 1000;
+
+function defaultRefreshPolicy(settings = {}) {
+  return {
+    fullRefreshIntervalHours: Number(settings?.refreshPolicy?.fullRefreshIntervalHours || DEFAULT_FULL_REFRESH_INTERVAL_HOURS),
+    singleModelRefreshOnNewUsage: settings?.refreshPolicy?.singleModelRefreshOnNewUsage !== false,
+  };
+}
+
+function nextRefreshAfter(lastFullModelRefreshAt, policy) {
+  const date = Date.parse(lastFullModelRefreshAt || "");
+  if (!Number.isFinite(date)) return null;
+  return new Date(date + (policy.fullRefreshIntervalHours * 60 * 60 * 1000)).toISOString();
+}
+
+function tryAcquireRefreshLock(cwd) {
+  const paths = getCurrentPaths(cwd);
+  const existing = safeReadJson(paths.inventoryRefreshLock, null);
+  const now = Date.now();
+  if (existing?.acquiredAt) {
+    const age = now - Date.parse(existing.acquiredAt);
+    if (Number.isFinite(age) && age < LOCK_TTL_MS) return { ok: false, staleRecovered: false };
+  }
+  if (existing?.acquiredAt) {
+    try { fs.unlinkSync(paths.inventoryRefreshLock); } catch {}
+  }
+  writeJson(paths.inventoryRefreshLock, { lockVersion: 1, acquiredAt: new Date(now).toISOString() });
+  return { ok: true, staleRecovered: Boolean(existing) };
+}
+
+function releaseRefreshLock(cwd) {
+  const paths = getCurrentPaths(cwd);
+  try { fs.unlinkSync(paths.inventoryRefreshLock); } catch {}
+}
+
+function determineRefreshDecision(cached, settings, options = {}) {
+  const policy = defaultRefreshPolicy(settings);
+  if (options.deepRefresh === true) {
+    return { refreshLevel: "deep", inventorySource: "rebuilt", lastRefreshReason: "explicit_deep_refresh", policy };
+  }
+  if (options.refresh === true) {
+    return { refreshLevel: "full", inventorySource: "rebuilt", lastRefreshReason: "explicit_refresh", policy };
+  }
+  if (!cached || cached.schemaVersion !== INVENTORY_SCHEMA_VERSION) {
+    return { refreshLevel: "full", inventorySource: cached ? "repaired" : "rebuilt", lastRefreshReason: cached ? "schema_upgrade" : "missing_cache", policy };
+  }
+  const lastFull = Date.parse(cached.lastFullModelRefreshAt || "");
+  if (!Number.isFinite(lastFull)) {
+    return { refreshLevel: "full", inventorySource: "repaired", lastRefreshReason: "invalid_timestamp", policy };
+  }
+  if (Date.now() >= lastFull + (policy.fullRefreshIntervalHours * 60 * 60 * 1000)) {
+    return { refreshLevel: "full", inventorySource: "rebuilt", lastRefreshReason: "scheduled_full_refresh", policy };
+  }
+  return { refreshLevel: "cache", inventorySource: "cache", lastRefreshReason: "fresh_cache", policy };
+}
+
+module.exports = {
+  INVENTORY_SCHEMA_VERSION,
+  DEFAULT_FULL_REFRESH_INTERVAL_HOURS,
+  defaultRefreshPolicy,
+  nextRefreshAfter,
+  determineRefreshDecision,
+  tryAcquireRefreshLock,
+  releaseRefreshLock,
+};

package/scripts/lib/orchestration/proof-writer.js

@@ -0,0 +1,349 @@
+"use strict";
+
+const path = require("path");
+const {
+  ensureOrchestrationDirs,
+  getCurrentPaths,
+  getRunPaths,
+  writeJson,
+  writeText,
+  relativeFromCwd,
+} = require("./state");
+
+function redactText(value) {
+  return String(value || "")
+    .replace(/(OPENROUTER_API_KEY|ANTHROPIC_AUTH_TOKEN|OPENAI_API_KEY|GEMINI_API_KEY|REQUESTY_API_KEY|LITELLM_API_KEY)=\S+/gi, "$1=[REDACTED]")
+    .replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+}
+
+function sanitizeValue(value) {
+  if (typeof value === "string") return redactText(value);
+  if (Array.isArray(value)) return value.map((item) => sanitizeValue(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeValue(entry)]));
+  }
+  return value;
+}
+
+function renderRouteMarkdown(route) {
+  const lines = [
+    "# Avorelo Route",
+    "",
+    `State: ${route.state}`,
+    `Selected route: ${route.selectedRoute}`,
+    `Inventory source: ${route.inventorySource || "cache"}`,
+    `Refresh level: ${route.refreshLevel || "cache"}`,
+    `Last full model refresh: ${route.lastFullModelRefreshAt || "unknown"}`,
+    `Next full model refresh after: ${route.nextFullModelRefreshAfter || "unknown"}`,
+    `Task type: ${route.task.taskType}`,
+    `Risk: ${route.task.risk}`,
+    `Sensitivity: ${route.task.sensitivity}`,
+    `Chosen worker: ${route.chosenTool || "none"}`,
+    `Chosen model: ${route.selectedModel || "none"}`,
+    `Chosen model/profile: ${route.chosenModelProfile || "none"}`,
+    `Fallback worker: ${route.fallbackTool || "none"}`,
+    `Fallback model: ${route.fallbackModel || "none"}`,
+    `Fallback model/profile: ${route.fallbackModelProfile || "none"}`,
+    "",
+    "Why chosen:",
+    ...(route.whyChosen || []).map((item) => `- ${item}`),
+    "",
+    "Why not chosen:",
+    ...(route.whyNotChosen || []).map((item) => `- ${item}`),
+    "",
+    "Safety notes:",
+    ...(route.safetyNotes || []).map((item) => `- ${item}`),
+    "",
+    "Stages:",
+    ...(route.stageList || []).map((stage) => `- ${stage.id}: ${stage.chosenLabel} (${stage.chosenModelProfile}) via ${stage.executionMode}`),
+  ];
+  return lines.join("\n").trim() + "\n";
+}
+
+function renderTaskMarkdown(taskContext) {
+  return [
+    "# Avorelo Current Task",
+    "",
+    redactText(taskContext.taskText),
+    "",
+    `Surface: ${taskContext.surface}`,
+    `Task type: ${taskContext.classification.taskType}`,
+    `Risk: ${taskContext.classification.risk}`,
+    `Sensitivity: ${taskContext.classification.sensitivity}`,
+    "",
+    "Signals:",
+    ...(taskContext.classification.signals || []).map((item) => `- ${item}`),
+  ].join("\n").trim() + "\n";
+}
+
+function renderProofMarkdown(proof, options = {}) {
+  const debug = options.debug === true || options.verbose === true;
+  const blockedOptions = proof.blockedOptions || [];
+  const skippedOptions = proof.skippedOptions || [];
+
+  const workerSummaryLines = debug
+    ? [
+        "",
+        "Blocked options:",
+        ...(blockedOptions.length
+          ? blockedOptions.map((item) => `- ${item.label}: ${(item.reasons || []).join(", ")}`)
+          : ["- none"]),
+        "",
+        "Skipped workers/models:",
+        ...(skippedOptions.length
+          ? skippedOptions.map((item) => `- ${item.label}: ${(item.reasons || []).join(", ")}`)
+          : ["- none"]),
+      ]
+    : [
+        "",
+        `Workers: ${blockedOptions.length} blocked · ${skippedOptions.length} unavailable · details: avorelo proof --debug`,
+      ];
+
+  const lines = [
+    "# Avorelo Proof",
+    "",
+    `Run: ${proof.runId}`,
+    `Status: ${proof.finalStatus}`,
+    `Surface: ${proof.surface}`,
+    `Task: ${proof.task}`,
+    `Chosen route: ${proof.route.selectedRoute}`,
+    `Inventory source: ${proof.inventorySource || "cache"}`,
+    `Refresh level: ${proof.refreshLevel || "cache"}`,
+    `Last full model refresh: ${proof.lastFullModelRefreshAt || "unknown"}`,
+    `Next full model refresh after: ${proof.nextFullModelRefreshAfter || "unknown"}`,
+    `Selected worker: ${proof.selectedWorker || "none"}`,
+    `Selected model: ${proof.selectedModel || "none"}`,
+    `Selected profile: ${proof.selectedProfile || "none"}`,
+    `Premium used: ${proof.premiumUsed ? "yes" : "no"}`,
+    `Premium avoided: ${proof.premiumAvoided ? "yes" : "no"}`,
+    `External model involved: ${proof.externalModelInvolved ? "yes" : "no"}`,
+    `Verification: ${proof.verification.status}`,
+    "",
+    "Tools used:",
+    ...(proof.toolsUsed || []).map((item) => `- ${item.toolId}: ${item.selectedModel || item.modelProfile || "unknown"} / ${item.modelProfile || "unknown"} (${item.executionMode})`),
+    ...workerSummaryLines,
+    "",
+    "Failures / fallbacks:",
+    ...((proof.failures || []).length
+      ? proof.failures.map((item) => `- ${item.stepId}: ${item.reason}`)
+      : ["- none"]),
+  ];
+  return redactText(lines.join("\n").trim() + "\n");
+}
+
+function buildProof({ runId, taskContext, route, execution, verification }) {
+  const toolsUsed = (execution.steps || [])
+    .filter((step) => step.toolId)
+    .map((step) => ({
+      stepId: step.stepId,
+      toolId: step.toolId,
+      selectedModel: step.selectedModel || null,
+      modelProfile: step.modelProfile || null,
+      executionMode: step.executionMode || "unknown",
+      status: step.status,
+    }));
+
+  return {
+    proofVersion: 1,
+    runId,
+    task: taskContext.taskText,
+    surface: taskContext.surface,
+    finalStatus: execution.finalStatus,
+    failureReason: execution.failureReason || null,
+    route,
+    inventorySource: route.inventorySource || "cache",
+    cacheUsed: route.cacheUsed === true,
+    lastFullModelRefreshAt: route.lastFullModelRefreshAt || null,
+    nextFullModelRefreshAfter: route.nextFullModelRefreshAfter || null,
+    refreshLevel: route.refreshLevel || "cache",
+    selectedWorker: route.chosenTool || null,
+    selectedModel: route.selectedModel || null,
+    selectedProfile: route.chosenModelProfile || null,
+    selectionReason: route.selectionReason || route.whyChosen || [],
+    toolsUsed,
+    toolsNotUsed: route.whyNotChosen || [],
+    skippedOptions: route.blockedOptions || [],
+    blockedOptions: route.blockedOptions || [],
+    reasons: route.whyChosen || [],
+    safetyDecisions: route.safetyNotes || [],
+    premiumAvoided: route.premiumUseInvolved !== true,
+    premiumUsed: route.premiumUseInvolved === true,
+    externalModelInvolved: route.externalModelInvolved === true,
+    verification,
+    failures: execution.failures || [],
+    diffSummary: execution.diffSummary || null,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function writeHostContracts(cwd, route, taskContext, proof = null) {
+  ensureOrchestrationDirs(cwd);
+  const current = getCurrentPaths(cwd);
+  const claudePath = path.join(current.hostContractsDir, "claude-code.md");
+  const codexPath = path.join(current.hostContractsDir, "codex-vscode.md");
+  const common = [
+    `Task: ${taskContext.taskText}`,
+    `Risk: ${taskContext.classification.risk}`,
+    `Selected worker: ${route.chosenTool || "none"} (${route.chosenModelProfile || "unknown"})`,
+    `Verification: ${(route.expectedVerification || []).join("; ") || "none"}`,
+    `Current route file: ${relativeFromCwd(cwd, current.currentRouteMd)}`,
+    `Current proof file: ${relativeFromCwd(cwd, current.currentProofMd)}`,
+  ];
+
+  writeText(claudePath, [
+    "# Claude Code Orchestration Contract",
+    "",
+    "Avorelo routes the task quietly and keeps the state local-first. Continue the task normally inside Claude Code and use the route/proof files as the bounded contract.",
+    "",
+    ...common,
+    "",
+    "If the route is blocked, prefer a trusted premium path before changing safety settings.",
+  ].join("\n"));
+
+  writeText(codexPath, [
+    "# Codex / VS Code Orchestration Contract",
+    "",
+    "Use the Avorelo route/proof files as the local handoff contract. This path is extension-ready and avoids depending on private Codex UI internals.",
+    "",
+    ...common,
+    "",
+    "Recommended commands:",
+    "- avorelo route \"<task>\"",
+    "- avorelo run \"<task>\" --dry-run",
+    "- avorelo proof",
+  ].join("\n"));
+
+  return {
+    claudeCodeContract: relativeFromCwd(cwd, claudePath),
+    codexVsCodeContract: relativeFromCwd(cwd, codexPath),
+    currentProofAvailable: Boolean(proof),
+  };
+}
+
+function writeCurrentArtifacts(cwd, taskContext, route, proof) {
+  ensureOrchestrationDirs(cwd);
+  const current = getCurrentPaths(cwd);
+  writeText(current.currentTask, renderTaskMarkdown(taskContext));
+  writeJson(current.currentRouteJson, sanitizeValue(route));
+  writeText(current.currentRouteMd, renderRouteMarkdown(sanitizeValue(route)));
+  if (proof) {
+    writeJson(current.currentProofJson, sanitizeValue(proof));
+    writeText(current.currentProofMd, renderProofMarkdown(sanitizeValue(proof)));
+  }
+}
+
+function writeRunArtifacts(cwd, runId, taskContext, route, execution, verification, proof) {
+  ensureOrchestrationDirs(cwd);
+  const runPaths = getRunPaths(cwd, runId);
+  writeJson(runPaths.task, {
+    taskText: redactText(taskContext.taskText),
+    surface: taskContext.surface,
+    classification: sanitizeValue(taskContext.classification),
+  });
+  writeJson(runPaths.route, sanitizeValue(route));
+  writeText(runPaths.diffSummary, redactText(execution.diffSummary || "No diff summary captured.\n"));
+  writeJson(runPaths.verification, sanitizeValue(verification));
+  writeJson(runPaths.proof, sanitizeValue(proof));
+  return runPaths;
+}
+
+const ORCHESTRATION_RECEIPT_SCHEMA_VERSION = 1;
+
+function buildAgentModelOrchestrationReceipt({ route, proof, handoffPath = null, cwd = null }) {
+  const paths = cwd ? getCurrentPaths(cwd) : null;
+  const stageList = Array.isArray(route?.stageList) ? route.stageList : [];
+  const blockedOptions = Array.isArray(route?.blockedOptions) ? route.blockedOptions : [];
+  const limitedWorkers = Array.isArray(route?.limitedWorkers) ? route.limitedWorkers : [];
+  const localWorkersAvailable = Array.isArray(route?.localWorkersAvailable) ? route.localWorkersAvailable : [];
+
+  const selectedWorkers = stageList
+    .filter((s) => s.chosenTool && s.chosenTool !== "avorelo_handoff")
+    .map((s) => ({ stageId: s.id, toolId: s.chosenTool, label: s.chosenLabel || s.chosenTool, model: s.chosenModel || s.chosenModelProfile || null }));
+
+  const fallbackWorkers = stageList
+    .filter((s) => s.fallbackTool)
+    .map((s) => ({ stageId: s.id, toolId: s.fallbackTool, model: s.fallbackModel || s.fallbackModelProfile || null }));
+
+  const skippedWorkers = (route?.whyNotChosen || []).slice(0, 6).map((reason) => ({ reason }));
+
+  return {
+    schemaVersion: ORCHESTRATION_RECEIPT_SCHEMA_VERSION,
+    contract: "avorelo.agentModelOrchestration.v1",
+    routeId: proof?.runId || `route-${Date.now()}`,
+    generatedAt: new Date().toISOString(),
+    taskSummary: redactText(String(route?.taskText || proof?.task || "")).slice(0, 200),
+    routeState: route?.state || "unknown",
+    selectedRoute: route?.selectedRoute || null,
+    stagePlan: stageList.map((s) => ({
+      id: s.id,
+      role: s.role,
+      worker: s.chosenLabel || s.chosenTool,
+      model: s.chosenModel || s.chosenModelProfile || null,
+      executionMode: s.executionMode,
+      quotaSignal: s.quotaSignal || "unknown",
+      fallback: s.fallbackTool || null,
+    })),
+    stageCount: stageList.length,
+    selectedWorkers,
+    fallbackWorkers,
+    skippedWorkers,
+    blockedWorkers: blockedOptions.map((b) => ({ toolId: b.toolId, label: b.label, reasons: b.reasons })),
+    quotaSignals: {
+      limitedWorkers: limitedWorkers.map((w) => ({ toolId: w.toolId, label: w.label, reasonCode: w.reasonCode })),
+      localWorkersAvailable,
+      fallbackReasonCodes: route?.fallbackReasonCodes || [],
+    },
+    localWorkerUse: localWorkersAvailable.length > 0,
+    localWorkerRecommendation: route?.localWorkerRecommendation || null,
+    premiumUse: Boolean(route?.premiumUseInvolved),
+    premiumAvoided: Boolean(proof?.premiumAvoided),
+    escalationRecommendations: (route?.fallbackReasonCodes || []).includes("ESCALATION_RECOMMENDED")
+      ? ["High-risk task detected — trusted higher-quality worker recommended for implementation/review"]
+      : [],
+    handoffAvailable: Boolean(route?.handoffAvailable),
+    handoffPromptPath: handoffPath || null,
+    expectedVerification: route?.expectedVerification || [],
+    safetyNotes: route?.safetyNotes || [],
+    nextAction: limitedWorkers.length
+      ? `Use fallback worker (${route?.fallbackTool || "local"}) — primary worker is recently limited`
+      : localWorkersAvailable.length
+        ? `Use local worker (${localWorkersAvailable[0]}) for inspect/plan, premium worker for implementation`
+        : `Run: avorelo route "<task>" --json for updated plan`,
+    redacted: true,
+    notAGateway: true,
+    foundationOnly: true,
+  };
+}
+
+function writeOrchestrationReceipt(cwd, receipt) {
+  const current = getCurrentPaths(cwd);
+  const receiptDir = path.join(current.root, "receipts");
+  const latestPath = path.join(receiptDir, "current-orchestration-receipt.json");
+  writeJson(latestPath, receipt);
+  return relativeFromCwd(cwd, latestPath);
+}
+
+function readOrchestrationReceipt(cwd) {
+  const current = getCurrentPaths(cwd);
+  const latestPath = path.join(current.root, "receipts", "current-orchestration-receipt.json");
+  try {
+    return JSON.parse(require("fs").readFileSync(latestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  redactText,
+  sanitizeValue,
+  renderRouteMarkdown,
+  renderProofMarkdown,
+  buildProof,
+  buildAgentModelOrchestrationReceipt,
+  writeOrchestrationReceipt,
+  readOrchestrationReceipt,
+  writeCurrentArtifacts,
+  writeRunArtifacts,
+  writeHostContracts,
+  ORCHESTRATION_RECEIPT_SCHEMA_VERSION,
+};