@agentskit/harness 0.6.0 → 0.8.0

package/dist/cli.js

@@ -953,15 +953,174 @@ var createDocBridgeContextProvider = ({ root, indexPath = ".doc-bridge/index.jso
     return { providerId: "doc-bridge", query, references, sourceHash: contentHash, snapshotHash: hashContextSnapshot({ providerId: "doc-bridge", query, references, sourceHash: contentHash }), resolvedAt: (/* @__PURE__ */ new Date()).toISOString(), assurance: "contract-tested", telemetry };
   }
 });
+var executable = (path) => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+var findExecutable = (name2, env = process.env, platform = process.platform) => {
+  if (typeof name2 !== "string" || !name2.trim()) return null;
+  if (isAbsolute(name2) || name2.includes("/") || name2.includes("\\")) return existsSync(name2) && executable(name2) ? name2 : null;
+  const extensions = platform === "win32" ? (env["PATHEXT"] ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
+  for (const dir of (env["PATH"] ?? "").split(delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = join(dir, `${name2}${extension}`);
+      if (executable(candidate)) return candidate;
+    }
+    if (platform === "win32" && executable(join(dir, name2))) return join(dir, name2);
+  }
+  return null;
+};
+var parseJsonEnvelope = (stdout) => {
+  const trimmed = stdout.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const record3 = parsed;
+  if (typeof record3.ok !== "boolean") return null;
+  const error = typeof record3.error === "string" ? record3.error : typeof record3.error === "object" && record3.error !== null && typeof record3.error.message === "string" ? record3.error.message : void 0;
+  return { ok: record3.ok, result: record3.result, ...error === void 0 ? {} : { error } };
+};
 
-// src/adapters/rag-context.ts
+// src/adapters/providers.ts
 var isRecord4 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var iso = (value) => typeof value === "number" && Number.isFinite(value) ? new Date(value).toISOString() : typeof value === "string" && !Number.isNaN(Date.parse(value)) ? new Date(value).toISOString() : null;
+var parseUsageWindows = (entry) => {
+  if (!isRecord4(entry)) return [];
+  return Object.entries(entry).flatMap(([kind, value]) => {
+    if (!isRecord4(value) || typeof value["usedPercent"] !== "number") return [];
+    return [{ kind, usedPercent: value["usedPercent"], windowMinutes: typeof value["windowMinutes"] === "number" ? value["windowMinutes"] : null, resetsAt: iso(value["resetsAt"]) }];
+  });
+};
+var parseProviderUsage = (accountList, usageKey, exhaustedPercent = 100) => {
+  const result = isRecord4(accountList) ? accountList : {};
+  const rateLimits = isRecord4(result["rateLimits"]) ? result["rateLimits"] : {};
+  const entry = isRecord4(rateLimits[usageKey]) ? rateLimits[usageKey] : null;
+  const account = isRecord4(result[usageKey]) ? result[usageKey] : null;
+  const systemDefault = account && isRecord4(account["systemDefault"]) ? account["systemDefault"] : null;
+  const accounts = account && Array.isArray(account["accounts"]) ? account["accounts"] : [];
+  const hasAuth = systemDefault ? systemDefault["hasAuth"] === true : accounts.length ? true : null;
+  if (!entry) return { status: "unknown", error: null, windows: [], exhausted: false, resetsAt: null, hasAuth };
+  const windows = parseUsageWindows(entry);
+  const exhaustedWindows = windows.filter((window) => window.usedPercent >= exhaustedPercent);
+  const resetsAt = exhaustedWindows.map((window) => window.resetsAt).filter((value) => Boolean(value)).sort()[0] ?? null;
+  return {
+    status: entry["status"] === "ok" ? "ok" : entry["status"] === "unavailable" ? "unavailable" : "unknown",
+    error: typeof entry["error"] === "string" ? entry["error"] : null,
+    windows,
+    exhausted: exhaustedWindows.length > 0,
+    resetsAt,
+    hasAuth
+  };
+};
+var authStatusFor = (spec, usage, env) => {
+  const hasEnvKey = spec.envKeys.some((key) => Boolean(env[key]?.trim()));
+  if (spec.auth === "api-key") return hasEnvKey ? "ok" : "missing";
+  if (spec.auth === "subscription") return usage.hasAuth === true || usage.status === "ok" ? "ok" : usage.hasAuth === false ? "missing" : hasEnvKey || usage.status === "unknown" ? "ok" : "unknown";
+  return hasEnvKey || usage.status === "ok" ? "ok" : "unknown";
+};
+var runProbe = async (spec, binary, runner, timeoutMs) => {
+  if (!spec.probe || !runner) return "skipped";
+  const [head, ...rest] = spec.probe;
+  const argv = [head === spec.bin ? binary : head ?? binary, ...rest];
+  try {
+    const outcome = await runner.run(argv, { timeoutMs });
+    return outcome.code === 0 && !outcome.timedOut ? "passed" : "failed";
+  } catch {
+    return "failed";
+  }
+};
+var detectProviders = async (input) => {
+  const env = input.env ?? process.env;
+  const platform = input.platform ?? process.platform;
+  const now4 = input.now ?? (() => /* @__PURE__ */ new Date());
+  const results = [];
+  for (const spec of input.providers) {
+    const binary = findExecutable(spec.bin, env, platform);
+    const hookState = input.agentHooks[spec.id] ?? "unknown";
+    const usage = parseProviderUsage(input.accountList, spec.orcaUsageKey, input.exhaustedPercent ?? 100);
+    const auth = authStatusFor(spec, usage, env);
+    const cooldown = input.cooldowns?.[spec.id] ?? null;
+    const coolingDownUntil = cooldown && Date.parse(cooldown) > now4().getTime() ? new Date(cooldown).toISOString() : null;
+    const reasons = [];
+    if (!binary) reasons.push(`binary "${spec.bin}" not found on PATH`);
+    if (auth === "missing") reasons.push(spec.auth === "api-key" ? `none of ${spec.envKeys.join(", ") || "the configured env keys"} is set` : `Orca reports no ${spec.id} credentials`);
+    if (usage.exhausted) reasons.push(`usage exhausted${usage.resetsAt ? ` until ${usage.resetsAt}` : ""}`);
+    if (coolingDownUntil) reasons.push(`cooling down until ${coolingDownUntil}`);
+    const probe = binary && !reasons.length ? await runProbe(spec, binary, input.runner, input.probeTimeoutMs ?? 15e3) : "skipped";
+    if (probe === "failed") reasons.push("probe command failed");
+    results.push({ id: spec.id, binary, hookState, auth, usage, probe, coolingDownUntil, available: reasons.length === 0, reasons });
+  }
+  return results;
+};
+var cooldownUntil = (attempt, initialMin, maxMin, from, resetsAt = null) => {
+  const minutes2 = Math.min(maxMin, initialMin * 2 ** Math.max(0, attempt));
+  const backoff = from.getTime() + minutes2 * 6e4;
+  const reset = resetsAt ? Date.parse(resetsAt) : Number.NaN;
+  return new Date(Number.isFinite(reset) && reset > from.getTime() ? Math.max(reset, backoff) : backoff).toISOString();
+};
+var remainingUsagePercent = (usage, metric = "max") => {
+  if (usage.status !== "ok" || !usage.windows.length) return null;
+  const windows = metric === "max" ? usage.windows : usage.windows.filter((window) => window.kind === metric);
+  const pool = windows.length ? windows : usage.windows;
+  if (!pool.length) return null;
+  const worst = Math.max(...pool.map((window) => window.usedPercent));
+  return Math.max(0, Math.min(100, 100 - worst));
+};
+var usageRankTuple = (usage, metric, preferKnownUsage) => {
+  const remaining = remainingUsagePercent(usage, metric);
+  const known = remaining === null ? 1 : 0;
+  const remainingKey = remaining === null ? 0 : -remaining;
+  const resetMs = usage.resetsAt ? Date.parse(usage.resetsAt) : Number.POSITIVE_INFINITY;
+  return preferKnownUsage ? [known, remainingKey, resetMs] : [remainingKey, known, resetMs];
+};
+var ORCA_META_KEYS = /* @__PURE__ */ new Set([
+  "minimaxCookieConfigured",
+  "minimaxApiKeyConfigured",
+  "grokAuthConfigured",
+  "claudeTarget",
+  "codexTarget",
+  "inactiveClaudeAccounts",
+  "inactiveCodexAccounts"
+]);
+var listOrcaIntegratedProviderKeys = (accountList) => {
+  const result = isRecord4(accountList) ? accountList : {};
+  const rateLimits = isRecord4(result["rateLimits"]) ? result["rateLimits"] : {};
+  const keys = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(rateLimits)) {
+    if (!ORCA_META_KEYS.has(key) && isRecord4(rateLimits[key])) keys.add(key);
+  }
+  for (const key of Object.keys(result)) {
+    if (key === "rateLimits" || ORCA_META_KEYS.has(key)) continue;
+    if (isRecord4(result[key])) keys.add(key);
+  }
+  return [...keys].sort();
+};
+var undeclaredOrcaProviders = (accountList, declared) => {
+  const usageKeyToId = /* @__PURE__ */ new Map();
+  for (const [id2, settings] of Object.entries(declared)) {
+    usageKeyToId.set(settings.orcaUsageKey ?? id2, id2);
+    usageKeyToId.set(id2, id2);
+  }
+  usageKeyToId.set("opencodeGo", usageKeyToId.get("opencodeGo") ?? "opencode");
+  return listOrcaIntegratedProviderKeys(accountList).filter((key) => !usageKeyToId.has(key));
+};
+
+// src/adapters/rag-context.ts
+var isRecord5 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var requiredString2 = (value, label) => {
   if (typeof value !== "string" || !value.trim()) return fail(`${label} must be a non-empty string.`, "INVALID_INPUT");
   return value;
 };
 var parseReference = (value, index2) => {
-  if (!isRecord4(value)) return fail(`RAG references[${index2}] must be an object.`, "INVALID_INPUT");
+  if (!isRecord5(value)) return fail(`RAG references[${index2}] must be an object.`, "INVALID_INPUT");
   const relevance = value["relevance"];
   if (relevance !== void 0 && (typeof relevance !== "number" || relevance < 0 || relevance > 1)) return fail(`RAG references[${index2}].relevance must be between 0 and 1.`, "INVALID_INPUT");
   return {
@@ -974,7 +1133,7 @@ var parseReference = (value, index2) => {
   };
 };
 var parseRagQueryOutput = (value) => {
-  if (!isRecord4(value)) return fail("RAG query output must be a JSON object.", "INVALID_INPUT");
+  if (!isRecord5(value)) return fail("RAG query output must be a JSON object.", "INVALID_INPUT");
   const rawReferences = value["references"];
   if (!Array.isArray(rawReferences)) return fail("RAG query output.references must be an array.", "INVALID_INPUT");
   const references = rawReferences.map((entry, index2) => parseReference(entry, index2));
@@ -1389,7 +1548,7 @@ var artifactId = (value) => {
   if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(result)) fail("Artifact artifactId is invalid.", "INVALID_INPUT");
   return result;
 };
-var isRecord5 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord6 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var artifactBody = (artifact) => ({
   type: artifact.type,
   schemaVersion: artifact.schemaVersion,
@@ -1408,7 +1567,7 @@ var artifactBody = (artifact) => ({
 });
 var expectedArtifactHash = (artifact) => hashJson(artifactBody(artifact));
 var validateArtifactEnvelope = (value) => {
-  if (!isRecord5(value)) return fail("Artifact envelope must be an object.", "INVALID_INPUT");
+  if (!isRecord6(value)) return fail("Artifact envelope must be an object.", "INVALID_INPUT");
   if (value["type"] !== "agentskit-harness-artifact" || value["schemaVersion"] !== ARTIFACT_SCHEMA_VERSION) fail("Artifact envelope type or schemaVersion is invalid.", "INVALID_INPUT");
   if (!ARTIFACT_TYPES.includes(value["artifactType"])) fail("Artifact artifactType is invalid.", "INVALID_INPUT");
   if (!Number.isInteger(value["artifactVersion"]) || value["artifactVersion"] < 1) fail("Artifact artifactVersion must be a positive integer.", "INVALID_INPUT");
@@ -2123,44 +2282,9 @@ var readEvidenceTrustStore = (path) => {
     return key;
   });
 };
-var executable = (path) => {
-  try {
-    return statSync(path).isFile();
-  } catch {
-    return false;
-  }
-};
-var findExecutable = (name2, env = process.env, platform = process.platform) => {
-  if (typeof name2 !== "string" || !name2.trim()) return null;
-  if (isAbsolute(name2) || name2.includes("/") || name2.includes("\\")) return existsSync(name2) && executable(name2) ? name2 : null;
-  const extensions = platform === "win32" ? (env["PATHEXT"] ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
-  for (const dir of (env["PATH"] ?? "").split(delimiter).filter(Boolean)) {
-    for (const extension of extensions) {
-      const candidate = join(dir, `${name2}${extension}`);
-      if (executable(candidate)) return candidate;
-    }
-    if (platform === "win32" && executable(join(dir, name2))) return join(dir, name2);
-  }
-  return null;
-};
-var parseJsonEnvelope = (stdout) => {
-  const trimmed = stdout.trim();
-  if (!trimmed) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return null;
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-  const record3 = parsed;
-  if (typeof record3.ok !== "boolean") return null;
-  const error = typeof record3.error === "string" ? record3.error : typeof record3.error === "object" && record3.error !== null && typeof record3.error.message === "string" ? record3.error.message : void 0;
-  return { ok: record3.ok, result: record3.result, ...error === void 0 ? {} : { error } };
-};
 
 // src/adapters/orca-cli.ts
-var isRecord6 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord7 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var str = (value, fallback = "") => typeof value === "string" ? value : fallback;
 var num = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
 var compareVersions = (left, right) => {
@@ -2174,9 +2298,9 @@ var compareVersions = (left, right) => {
 };
 var parseOrcaVersion = (stdout) => stdout.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
 var parseOrcaStatus = (result) => {
-  const record3 = isRecord6(result) ? result : {};
-  const app = isRecord6(record3["app"]) ? record3["app"] : {};
-  const runtime = isRecord6(record3["runtime"]) ? record3["runtime"] : {};
+  const record3 = isRecord7(result) ? result : {};
+  const app = isRecord7(record3["app"]) ? record3["app"] : {};
+  const runtime = isRecord7(record3["runtime"]) ? record3["runtime"] : {};
   return {
     appRunning: app["running"] === true,
     runtimeReady: runtime["state"] === "ready" && runtime["reachable"] === true,
@@ -2187,14 +2311,14 @@ var parseOrcaStatus = (result) => {
 };
 var linkedLinear = (value) => {
   if (typeof value === "string" && value.trim()) return value.trim();
-  if (isRecord6(value)) {
+  if (isRecord7(value)) {
     for (const key of ["identifier", "id", "url"]) if (typeof value[key] === "string" && value[key].trim()) return value[key].trim();
   }
   return null;
 };
 var parseOrcaWorktrees = (result) => {
-  const list2 = isRecord6(result) && Array.isArray(result["worktrees"]) ? result["worktrees"] : Array.isArray(result) ? result : [];
-  return list2.filter(isRecord6).map((item) => ({
+  const list2 = isRecord7(result) && Array.isArray(result["worktrees"]) ? result["worktrees"] : Array.isArray(result) ? result : [];
+  return list2.filter(isRecord7).map((item) => ({
     id: str(item["worktreeId"], str(item["id"])),
     repoId: str(item["repoId"]),
     repo: str(item["repo"]),
@@ -2211,8 +2335,8 @@ var parseOrcaWorktrees = (result) => {
   })).filter((item) => item.id);
 };
 var parseOrcaAgentHooks = (result) => {
-  const statuses = isRecord6(result) && Array.isArray(result["statuses"]) ? result["statuses"] : [];
-  return Object.fromEntries(statuses.filter(isRecord6).flatMap((item) => {
+  const statuses = isRecord7(result) && Array.isArray(result["statuses"]) ? result["statuses"] : [];
+  return Object.fromEntries(statuses.filter(isRecord7).flatMap((item) => {
     const agent = str(item["agent"]);
     if (!agent) return [];
     const state = item["state"] === "installed" ? "installed" : item["state"] === "not_installed" ? "not_installed" : "unknown";
@@ -2238,9 +2362,9 @@ var orcaWorktrees = async (runner, options2 = {}) => parseOrcaWorktrees(await or
 var orcaAgentHooks = async (runner, options2 = {}) => parseOrcaAgentHooks(await orcaJson(runner, ["agent", "hooks", "status"], options2));
 var orcaAccountList = async (runner, options2 = {}) => orcaJson(runner, ["account", "list"], options2);
 var parseOrcaWorktreeCreate = (result) => {
-  const record3 = isRecord6(result) ? result : {};
-  const nested = isRecord6(record3["worktree"]) ? record3["worktree"] : record3;
-  const startup = isRecord6(record3["startupTerminal"]) ? record3["startupTerminal"] : isRecord6(nested["startupTerminal"]) ? nested["startupTerminal"] : {};
+  const record3 = isRecord7(result) ? result : {};
+  const nested = isRecord7(record3["worktree"]) ? record3["worktree"] : record3;
+  const startup = isRecord7(record3["startupTerminal"]) ? record3["startupTerminal"] : isRecord7(nested["startupTerminal"]) ? nested["startupTerminal"] : {};
   const id2 = str(nested["worktreeId"], str(nested["id"], str(record3["worktreeId"], str(record3["id"]))));
   if (!id2) fail("orca worktree create returned no worktree id.", "HARNESS_ERROR");
   return {
@@ -2270,8 +2394,8 @@ var orcaWorktreeSetArgv = (input, bin = "orca") => [
 var orcaWorktreeSet = async (runner, input, options2 = {}) => orcaJson(runner, orcaWorktreeSetArgv(input).slice(1), options2);
 var orcaWorktreeRemove = async (runner, input, options2 = {}) => orcaJson(runner, ["worktree", "rm", "--worktree", input.worktree, ...input.force ? ["--force"] : []], { ...options2, timeoutMs: options2.timeoutMs ?? 6e4 });
 var parseOrcaTerminals = (result) => {
-  const list2 = isRecord6(result) ? Array.isArray(result["terminals"]) ? result["terminals"] : Array.isArray(result["items"]) ? result["items"] : [] : Array.isArray(result) ? result : [];
-  return list2.filter(isRecord6).map((item) => ({
+  const list2 = isRecord7(result) ? Array.isArray(result["terminals"]) ? result["terminals"] : Array.isArray(result["items"]) ? result["items"] : [] : Array.isArray(result) ? result : [];
+  return list2.filter(isRecord7).map((item) => ({
     handle: str(item["handle"], str(item["id"])),
     title: str(item["title"], str(item["name"])),
     worktreeId: str(item["worktreeId"], str(item["worktree"])) || null,
@@ -2286,29 +2410,29 @@ var parseOrcaTerminals = (result) => {
 var orcaTerminalList = async (runner, input = {}, options2 = {}) => parseOrcaTerminals(await orcaJson(runner, ["terminal", "list", ...input.worktree ? ["--worktree", input.worktree] : [], ...input.limit ? ["--limit", String(input.limit)] : []], options2));
 var orcaTerminalCreate = async (runner, input, options2 = {}) => {
   const result = await orcaJson(runner, ["terminal", "create", "--worktree", input.worktree, "--command", input.command, ...input.title ? ["--title", input.title] : []], { ...options2, timeoutMs: options2.timeoutMs ?? 6e4 });
-  const record3 = isRecord6(result) ? result : {};
-  const terminal2 = isRecord6(record3["terminal"]) ? record3["terminal"] : record3;
+  const record3 = isRecord7(result) ? result : {};
+  const terminal2 = isRecord7(record3["terminal"]) ? record3["terminal"] : record3;
   const handle = str(terminal2["handle"], str(record3["handle"]));
   if (!handle) fail("orca terminal create returned no terminal handle.", "HARNESS_ERROR");
   return { handle, raw: result };
 };
 var parseOrcaSendReceipt = (result) => {
-  const record3 = isRecord6(result) ? result : {};
-  const receipt = isRecord6(record3["receipt"]) ? record3["receipt"] : record3;
-  const stages = Array.isArray(receipt["stages"]) ? receipt["stages"].map((stage) => isRecord6(stage) ? str(stage["stage"], str(stage["name"])) : str(stage)).filter(Boolean) : [];
+  const record3 = isRecord7(result) ? result : {};
+  const receipt = isRecord7(record3["receipt"]) ? record3["receipt"] : record3;
+  const stages = Array.isArray(receipt["stages"]) ? receipt["stages"].map((stage) => isRecord7(stage) ? str(stage["stage"], str(stage["name"])) : str(stage)).filter(Boolean) : [];
   const accepted = receipt["accepted"] === false ? false : receipt["accepted"] === true || stages.includes("input_accepted") || (result === null || result === void 0 || Object.keys(record3).length === 0);
-  return { accepted, requestId: str(receipt["requestId"], str(record3["requestId"])) || null, stages, warnings: Array.isArray(record3["warnings"]) ? record3["warnings"].map((warning) => isRecord6(warning) ? str(warning["message"], JSON.stringify(warning)) : str(warning)) : [] };
+  return { accepted, requestId: str(receipt["requestId"], str(record3["requestId"])) || null, stages, warnings: Array.isArray(record3["warnings"]) ? record3["warnings"].map((warning) => isRecord7(warning) ? str(warning["message"], JSON.stringify(warning)) : str(warning)) : [] };
 };
 var orcaTerminalSend = async (runner, input, options2 = {}) => parseOrcaSendReceipt(await orcaJson(runner, ["terminal", "send", "--terminal", input.terminal, "--text", input.text, ...input.enter === false ? [] : ["--enter"], ...input.waitSubmitSeconds ? ["--wait-submit", String(input.waitSubmitSeconds)] : []], { ...options2, timeoutMs: options2.timeoutMs ?? (input.waitSubmitSeconds ?? 0) * 1e3 + 3e4 }));
 var orcaTerminalWait = async (runner, input, options2 = {}) => {
   const result = await orcaJson(runner, ["terminal", "wait", "--terminal", input.terminal, "--for", input.for, "--timeout-ms", String(input.timeoutMs)], { ...options2, timeoutMs: input.timeoutMs + 15e3 });
-  const record3 = isRecord6(result) ? result : {};
-  const wait = isRecord6(record3["wait"]) ? record3["wait"] : record3;
+  const record3 = isRecord7(result) ? result : {};
+  const wait = isRecord7(record3["wait"]) ? record3["wait"] : record3;
   return { satisfied: wait["satisfied"] === true, raw: result };
 };
 var parseOrcaAutomations = (result) => {
-  const list2 = isRecord6(result) ? Array.isArray(result["automations"]) ? result["automations"] : Array.isArray(result["items"]) ? result["items"] : [] : Array.isArray(result) ? result : [];
-  return list2.filter(isRecord6).map((item) => ({ id: str(item["id"]), name: str(item["name"]), enabled: item["enabled"] !== false && item["disabled"] !== true, trigger: str(item["rrule"], str(item["trigger"], str(item["schedule"], typeof item["schedule"] === "object" && item["schedule"] !== null ? JSON.stringify(item["schedule"]) : ""))), provider: str(item["agentId"], str(item["provider"], str(item["agent"]))) || null, raw: item })).filter((item) => item.id);
+  const list2 = isRecord7(result) ? Array.isArray(result["automations"]) ? result["automations"] : Array.isArray(result["items"]) ? result["items"] : [] : Array.isArray(result) ? result : [];
+  return list2.filter(isRecord7).map((item) => ({ id: str(item["id"]), name: str(item["name"]), enabled: item["enabled"] !== false && item["disabled"] !== true, trigger: str(item["rrule"], str(item["trigger"], str(item["schedule"], typeof item["schedule"] === "object" && item["schedule"] !== null ? JSON.stringify(item["schedule"]) : ""))), provider: str(item["agentId"], str(item["provider"], str(item["agent"]))) || null, raw: item })).filter((item) => item.id);
 };
 var orcaAutomationsList = async (runner, options2 = {}) => parseOrcaAutomations(await orcaJson(runner, ["automations", "list"], options2));
 var orcaAutomationCreateArgv = (spec, bin = "orca") => [
@@ -2355,84 +2479,6 @@ var orcaAutomationEditArgv = (id2, spec, bin = "orca") => [
 var orcaAutomationRemove = async (runner, id2, options2 = {}) => orcaJson(runner, ["automations", "remove", id2], options2);
 var orcaAutomationRuns = async (runner, id2, options2 = {}) => orcaJson(runner, ["automations", "runs", "--id", id2], options2);
 
-// src/adapters/providers.ts
-var isRecord7 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var iso = (value) => typeof value === "number" && Number.isFinite(value) ? new Date(value).toISOString() : typeof value === "string" && !Number.isNaN(Date.parse(value)) ? new Date(value).toISOString() : null;
-var parseUsageWindows = (entry) => {
-  if (!isRecord7(entry)) return [];
-  return Object.entries(entry).flatMap(([kind, value]) => {
-    if (!isRecord7(value) || typeof value["usedPercent"] !== "number") return [];
-    return [{ kind, usedPercent: value["usedPercent"], windowMinutes: typeof value["windowMinutes"] === "number" ? value["windowMinutes"] : null, resetsAt: iso(value["resetsAt"]) }];
-  });
-};
-var parseProviderUsage = (accountList, usageKey, exhaustedPercent = 100) => {
-  const result = isRecord7(accountList) ? accountList : {};
-  const rateLimits = isRecord7(result["rateLimits"]) ? result["rateLimits"] : {};
-  const entry = isRecord7(rateLimits[usageKey]) ? rateLimits[usageKey] : null;
-  const account = isRecord7(result[usageKey]) ? result[usageKey] : null;
-  const systemDefault = account && isRecord7(account["systemDefault"]) ? account["systemDefault"] : null;
-  const accounts = account && Array.isArray(account["accounts"]) ? account["accounts"] : [];
-  const hasAuth = systemDefault ? systemDefault["hasAuth"] === true : accounts.length ? true : null;
-  if (!entry) return { status: "unknown", error: null, windows: [], exhausted: false, resetsAt: null, hasAuth };
-  const windows = parseUsageWindows(entry);
-  const exhaustedWindows = windows.filter((window) => window.usedPercent >= exhaustedPercent);
-  const resetsAt = exhaustedWindows.map((window) => window.resetsAt).filter((value) => Boolean(value)).sort()[0] ?? null;
-  return {
-    status: entry["status"] === "ok" ? "ok" : entry["status"] === "unavailable" ? "unavailable" : "unknown",
-    error: typeof entry["error"] === "string" ? entry["error"] : null,
-    windows,
-    exhausted: exhaustedWindows.length > 0,
-    resetsAt,
-    hasAuth
-  };
-};
-var authStatusFor = (spec, usage, env) => {
-  const hasEnvKey = spec.envKeys.some((key) => Boolean(env[key]?.trim()));
-  if (spec.auth === "api-key") return hasEnvKey ? "ok" : "missing";
-  if (spec.auth === "subscription") return usage.hasAuth === true || usage.status === "ok" ? "ok" : usage.hasAuth === false ? "missing" : hasEnvKey || usage.status === "unknown" ? "ok" : "unknown";
-  return hasEnvKey || usage.status === "ok" ? "ok" : "unknown";
-};
-var runProbe = async (spec, binary, runner, timeoutMs) => {
-  if (!spec.probe || !runner) return "skipped";
-  const [head, ...rest] = spec.probe;
-  const argv = [head === spec.bin ? binary : head ?? binary, ...rest];
-  try {
-    const outcome = await runner.run(argv, { timeoutMs });
-    return outcome.code === 0 && !outcome.timedOut ? "passed" : "failed";
-  } catch {
-    return "failed";
-  }
-};
-var detectProviders = async (input) => {
-  const env = input.env ?? process.env;
-  const platform = input.platform ?? process.platform;
-  const now4 = input.now ?? (() => /* @__PURE__ */ new Date());
-  const results = [];
-  for (const spec of input.providers) {
-    const binary = findExecutable(spec.bin, env, platform);
-    const hookState = input.agentHooks[spec.id] ?? "unknown";
-    const usage = parseProviderUsage(input.accountList, spec.orcaUsageKey, input.exhaustedPercent ?? 100);
-    const auth = authStatusFor(spec, usage, env);
-    const cooldown = input.cooldowns?.[spec.id] ?? null;
-    const coolingDownUntil = cooldown && Date.parse(cooldown) > now4().getTime() ? new Date(cooldown).toISOString() : null;
-    const reasons = [];
-    if (!binary) reasons.push(`binary "${spec.bin}" not found on PATH`);
-    if (auth === "missing") reasons.push(spec.auth === "api-key" ? `none of ${spec.envKeys.join(", ") || "the configured env keys"} is set` : `Orca reports no ${spec.id} credentials`);
-    if (usage.exhausted) reasons.push(`usage exhausted${usage.resetsAt ? ` until ${usage.resetsAt}` : ""}`);
-    if (coolingDownUntil) reasons.push(`cooling down until ${coolingDownUntil}`);
-    const probe = binary && !reasons.length ? await runProbe(spec, binary, input.runner, input.probeTimeoutMs ?? 15e3) : "skipped";
-    if (probe === "failed") reasons.push("probe command failed");
-    results.push({ id: spec.id, binary, hookState, auth, usage, probe, coolingDownUntil, available: reasons.length === 0, reasons });
-  }
-  return results;
-};
-var cooldownUntil = (attempt, initialMin, maxMin, from, resetsAt = null) => {
-  const minutes2 = Math.min(maxMin, initialMin * 2 ** Math.max(0, attempt));
-  const backoff = from.getTime() + minutes2 * 6e4;
-  const reset = resetsAt ? Date.parse(resetsAt) : Number.NaN;
-  return new Date(Number.isFinite(reset) && reset > from.getTime() ? Math.max(reset, backoff) : backoff).toISOString();
-};
-
 // src/adapters/linear-orca.ts
 var isRecord8 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var str2 = (value, fallback = "") => typeof value === "string" ? value : fallback;
@@ -2583,6 +2629,41 @@ var LoopConfigSchema = z.object({
     reviewer: tiers,
     builder: tiers,
     watcher: tiers,
+    /** How candidates are ordered. `tiers` = YAML order (0.6 behaviour). `hybrid` = keep tiers, rank by remaining usage inside each. `dynamic` = flatten + usage. `catalog` = discover models via CLI/AA/builtin + usage. */
+    routing: z.object({
+      mode: z.enum(["tiers", "hybrid", "dynamic", "catalog"]).default("tiers"),
+      /** Which usage window drives remaining%. `max` = most constrained window. */
+      usageMetric: z.enum(["max", "session", "weekly", "monthly"]).default("max"),
+      /** Prefer providers with live usage % over those with unknown usage (e.g. grok often has no %). */
+      preferKnownUsage: z.boolean().default(true),
+      excludeProviders: z.array(nonEmpty2).default([]),
+      /** If non-empty, only these providers may be selected (still must be declared under providers). */
+      includeProviders: z.array(nonEmpty2).default([]),
+      /** Hard pin per role (`provider/model`). If pinned provider is unavailable, fall through unless pinStrict. */
+      pin: z.object({
+        orchestrator: modelRef.optional(),
+        reviewer: modelRef.optional(),
+        builder: modelRef.optional(),
+        watcher: modelRef.optional()
+      }).prefault({}),
+      pinStrict: z.boolean().default(false)
+    }).prefault({}),
+    /** Quality band when `routing.mode: catalog` (and as soft bias in hybrid). */
+    roles: z.object({
+      orchestrator: z.object({ quality: z.enum(["frontier", "balanced", "fast"]).default("frontier"), preferCreators: z.array(nonEmpty2).default([]) }).prefault({}),
+      reviewer: z.object({ quality: z.enum(["frontier", "balanced", "fast"]).default("frontier"), preferCreators: z.array(nonEmpty2).default([]) }).prefault({}),
+      builder: z.object({ quality: z.enum(["frontier", "balanced", "fast"]).default("balanced"), preferCreators: z.array(nonEmpty2).default([]) }).prefault({}),
+      watcher: z.object({ quality: z.enum(["frontier", "balanced", "fast"]).default("fast"), preferCreators: z.array(nonEmpty2).default([]) }).prefault({})
+    }).prefault({}),
+    catalog: z.object({
+      sources: z.array(z.enum(["cli", "artificial-analysis", "builtin"])).default(["cli", "builtin"]),
+      artificialAnalysis: z.object({
+        enabled: z.boolean().default(false),
+        apiKeyEnv: nonEmpty2.default("ARTIFICIAL_ANALYSIS_API_KEY"),
+        cacheHours: z.number().positive().default(24),
+        endpoint: nonEmpty2.default("https://artificialanalysis.ai/api/v2/data/llms/models")
+      }).prefault({})
+    }).prefault({}),
     cooldown: z.object({
       initialMin: z.number().int().positive().default(30),
       maxMin: z.number().int().positive().default(240),
@@ -2646,6 +2727,16 @@ var LoopConfigSchema = z.object({
     }).prefault({}),
     maxFixRounds: z.number().int().min(0).default(2),
     workerIdleTimeoutMin: z.number().int().positive().default(45),
+    /**
+     * When a worker goes idle / dies and its provider is out of usage (or otherwise unavailable),
+     * relaunch another builder on the **same** Orca worktree + branch with a continuation brief.
+     */
+    handoff: z.object({
+      enabled: z.boolean().default(true),
+      maxHandoffs: z.number().int().min(0).max(5).default(2),
+      /** Only hand off when the current provider is unavailable (exhausted/cooldown/missing). */
+      onlyWhenProviderUnavailable: z.boolean().default(true)
+    }).prefault({}),
     selfEditPaths: z.array(nonEmpty2).default([LOOP_CONFIG_FILE, ".github/**"]),
     /** Check names ignored when deciding CI is green (e.g. advisory bots). */
     ignoreChecks: z.array(nonEmpty2).default([]),
@@ -2871,28 +2962,395 @@ var assessSlots = (input) => {
 };
 
 // src/loop/routing.ts
-var selectModel = (config, role, availability) => {
+var allowedProvider = (config, providerId) => {
+  const { excludeProviders, includeProviders } = config.models.routing;
+  if (excludeProviders.includes(providerId)) return false;
+  if (includeProviders.length && !includeProviders.includes(providerId)) return false;
+  return true;
+};
+var materialize = (config, ref, tier, preferenceIndex, availability, reason) => {
+  const identity = providerIdentity(config, ref.provider);
+  return {
+    ...ref,
+    tier,
+    preferenceIndex,
+    orcaAgent: identity.orcaAgent,
+    tui: renderTuiCommand(identity.settings, ref.model),
+    remainingPercent: availability ? remainingUsagePercent(availability.usage, config.models.routing.usageMetric) : null,
+    reason
+  };
+};
+var compareUsageAware = (config, left, right, byId) => {
+  const leftAv = byId.get(left.provider);
+  const rightAv = byId.get(right.provider);
+  const leftTuple = leftAv ? usageRankTuple(leftAv.usage, config.models.routing.usageMetric, config.models.routing.preferKnownUsage) : [1, 0, Number.POSITIVE_INFINITY];
+  const rightTuple = rightAv ? usageRankTuple(rightAv.usage, config.models.routing.usageMetric, config.models.routing.preferKnownUsage) : [1, 0, Number.POSITIVE_INFINITY];
+  for (let i = 0; i < leftTuple.length; i += 1) {
+    if (leftTuple[i] !== rightTuple[i]) return leftTuple[i] - rightTuple[i];
+  }
+  if (left.preferenceIndex !== right.preferenceIndex) return left.preferenceIndex - right.preferenceIndex;
+  return left.provider.localeCompare(right.provider) || left.model.localeCompare(right.model);
+};
+var availableFromTiers = (config, role, availability) => {
   const byId = new Map(availability.map((item) => [item.id, item]));
   const skipped = [];
+  const ranked = [];
+  let preferenceIndex = 0;
   for (const [tier, refs] of tiersFor(config, role).entries()) {
     for (const ref of refs) {
+      const index2 = preferenceIndex;
+      preferenceIndex += 1;
+      if (!allowedProvider(config, ref.provider)) {
+        skipped.push({ tier, ref, reasons: ["provider excluded by models.routing"] });
+        continue;
+      }
       const provider = byId.get(ref.provider);
       if (provider?.available) {
-        const identity = providerIdentity(config, ref.provider);
-        return { role, selected: { ...ref, tier, orcaAgent: identity.orcaAgent, tui: renderTuiCommand(identity.settings, ref.model) }, skipped };
+        ranked.push(materialize(config, ref, tier, index2, provider, `yaml tier ${tier + 1}`));
+      } else {
+        skipped.push({ tier, ref, reasons: provider ? provider.reasons : ["provider was not detected"] });
       }
-      skipped.push({ tier, ref, reasons: provider ? provider.reasons : ["provider was not detected"] });
     }
   }
-  return { role, selected: null, skipped };
+  return { ranked, skipped };
 };
-var routeAllRoles = (config, availability) => Object.fromEntries(MODEL_ROLES.map((role) => [role, selectModel(config, role, availability)]));
-var rankModels = (config, role, availability) => {
+var applyPin = (config, role, availability, skipped) => {
+  const pin = config.models.routing.pin[role];
+  if (!pin) return null;
+  const ref = parseModelRef(pin);
   const byId = new Map(availability.map((item) => [item.id, item]));
-  return tiersFor(config, role).flatMap((refs, tier) => refs.filter((ref) => byId.get(ref.provider)?.available).map((ref) => {
-    const identity = providerIdentity(config, ref.provider);
-    return { ...ref, tier, orcaAgent: identity.orcaAgent, tui: renderTuiCommand(identity.settings, ref.model) };
-  }));
+  const provider = byId.get(ref.provider);
+  if (provider?.available && allowedProvider(config, ref.provider)) {
+    return materialize(config, ref, -1, -1, provider, `pinned ${pin}`);
+  }
+  skipped.push({ tier: -1, ref, reasons: provider ? provider.reasons : ["pinned provider was not detected"] });
+  if (config.models.routing.pinStrict) return null;
+  return null;
+};
+var selectModel = (config, role, availability, extraCandidates = []) => {
+  const byId = new Map(availability.map((item) => [item.id, item]));
+  const mode = config.models.routing.mode;
+  const { ranked: fromYaml, skipped } = availableFromTiers(config, role, availability);
+  if (config.models.routing.pin[role]) {
+    const pinned = applyPin(config, role, availability, skipped);
+    if (pinned) return { role, selected: pinned, skipped };
+    if (config.models.routing.pinStrict) return { role, selected: null, skipped };
+  }
+  const extras = [];
+  let extraIndex = 1e4;
+  for (const ref of extraCandidates) {
+    if (!allowedProvider(config, ref.provider)) continue;
+    const provider = byId.get(ref.provider);
+    if (!provider?.available) continue;
+    extras.push(materialize(config, ref, 99, extraIndex, provider, "catalog"));
+    extraIndex += 1;
+  }
+  if (mode === "tiers") {
+    const first = fromYaml[0] ?? extras[0] ?? null;
+    return { role, selected: first ?? null, skipped };
+  }
+  if (mode === "hybrid") {
+    const byTier = /* @__PURE__ */ new Map();
+    for (const item of fromYaml) {
+      const list2 = byTier.get(item.tier) ?? [];
+      list2.push(item);
+      byTier.set(item.tier, list2);
+    }
+    const tiers2 = [...byTier.keys()].sort((a, b) => a - b);
+    for (const tier of tiers2) {
+      const pool2 = byTier.get(tier) ?? [];
+      pool2.sort((left, right) => compareUsageAware(config, left, right, byId));
+      if (pool2[0]) {
+        return {
+          role,
+          selected: {
+            ...pool2[0],
+            reason: `hybrid tier ${tier + 1} \xB7 remaining ${pool2[0].remainingPercent ?? "unknown"}%`
+          },
+          skipped
+        };
+      }
+    }
+    if (extras.length) {
+      extras.sort((left, right) => compareUsageAware(config, left, right, byId));
+      return { role, selected: { ...extras[0], reason: `hybrid catalog \xB7 remaining ${extras[0].remainingPercent ?? "unknown"}%` }, skipped };
+    }
+    return { role, selected: null, skipped };
+  }
+  const pool = [...fromYaml, ...extras];
+  pool.sort((left, right) => compareUsageAware(config, left, right, byId));
+  const best = pool[0] ?? null;
+  return {
+    role,
+    selected: best ? { ...best, reason: `${mode} \xB7 remaining ${best.remainingPercent ?? "unknown"}% \xB7 ${best.reason}` } : null,
+    skipped
+  };
+};
+var routeAllRoles = (config, availability, extrasByRole = {}) => Object.fromEntries(MODEL_ROLES.map((role) => [role, selectModel(config, role, availability, extrasByRole[role] ?? [])]));
+var rankModels = (config, role, availability, extraCandidates = []) => {
+  const byId = new Map(availability.map((item) => [item.id, item]));
+  const { ranked } = availableFromTiers(config, role, availability);
+  const extras = [];
+  let extraIndex = 1e4;
+  for (const ref of extraCandidates) {
+    if (!allowedProvider(config, ref.provider)) continue;
+    const provider = byId.get(ref.provider);
+    if (!provider?.available) continue;
+    extras.push(materialize(config, ref, 99, extraIndex, provider, "catalog"));
+    extraIndex += 1;
+  }
+  const mode = config.models.routing.mode;
+  if (mode === "tiers") return [...ranked, ...extras];
+  if (mode === "hybrid") {
+    const byTier = /* @__PURE__ */ new Map();
+    for (const item of ranked) {
+      const list2 = byTier.get(item.tier) ?? [];
+      list2.push(item);
+      byTier.set(item.tier, list2);
+    }
+    const ordered = [];
+    for (const tier of [...byTier.keys()].sort((a, b) => a - b)) {
+      const pool2 = byTier.get(tier) ?? [];
+      pool2.sort((left, right) => compareUsageAware(config, left, right, byId));
+      ordered.push(...pool2);
+    }
+    extras.sort((left, right) => compareUsageAware(config, left, right, byId));
+    return [...ordered, ...extras];
+  }
+  const pool = [...ranked, ...extras];
+  pool.sort((left, right) => compareUsageAware(config, left, right, byId));
+  return pool;
+};
+
+// src/loop/model-catalog/builtin.json
+var builtin_default = {
+  providers: {
+    claude: {
+      creator: "anthropic",
+      models: [
+        { id: "opus", quality: "frontier", codingScore: 90 },
+        { id: "sonnet", quality: "balanced", codingScore: 80 },
+        { id: "haiku", quality: "fast", codingScore: 55 }
+      ]
+    },
+    codex: {
+      creator: "openai",
+      models: [
+        { id: "gpt-5.6-sol", quality: "frontier", codingScore: 92 },
+        { id: "gpt-5.6-luna", quality: "balanced", codingScore: 78 },
+        { id: "gpt-5.4", quality: "balanced", codingScore: 70 }
+      ]
+    },
+    opencode: {
+      creator: "opencode",
+      models: [
+        { id: "opencode-go/glm-5.3", quality: "balanced", codingScore: 72 },
+        { id: "opencode-go/glm-5.3-flash", quality: "fast", codingScore: 58 }
+      ]
+    },
+    grok: {
+      creator: "xai",
+      models: [
+        { id: "grok-4.6", quality: "frontier", codingScore: 85 },
+        { id: "grok-4.5", quality: "balanced", codingScore: 75 },
+        { id: "grok-4-fast", quality: "fast", codingScore: 60 }
+      ]
+    }
+  }
+};
+
+// src/loop/model-catalog/aliases.json
+var aliases_default = {
+  aliases: {
+    claude: {
+      "claude-opus-4": "opus",
+      "claude-sonnet-4": "sonnet",
+      "claude-haiku-4": "haiku",
+      "opus-4": "opus",
+      "sonnet-4": "sonnet",
+      "haiku-4": "haiku"
+    },
+    codex: {
+      "gpt-5.6": "gpt-5.6-sol",
+      o3: "gpt-5.6-sol"
+    },
+    grok: {
+      "grok-4": "grok-4.5",
+      "grok-4-latest": "grok-4.6"
+    },
+    opencode: {}
+  }
+};
+
+// src/loop/model-catalog/index.ts
+var readJson2 = (path) => JSON.parse(readFileSync(path, "utf8"));
+var loadBuiltinCatalog = () => {
+  const raw = builtin_default;
+  return Object.fromEntries(Object.entries(raw.providers).map(([id2, value]) => [id2, {
+    creator: value.creator,
+    models: value.models.map((model) => ({ ...model, source: "builtin", creator: value.creator }))
+  }]));
+};
+var loadAliases = () => aliases_default.aliases;
+var resolveAlias = (provider, modelId, aliases = loadAliases()) => aliases[provider]?.[modelId] ?? aliases[provider]?.[modelId.toLowerCase()] ?? modelId;
+var parseGrokModelsOutput = (stdout) => {
+  const models = [];
+  for (const line2 of stdout.split(/\r?\n/)) {
+    const match = line2.match(/^\s*[-*]?\s*(grok-[a-z0-9][a-z0-9._-]*)\b/i) ?? line2.match(/^\s*\*\s*(grok-[a-z0-9][a-z0-9._-]*)\b/i);
+    if (match?.[1]) models.push(match[1]);
+  }
+  return [...new Set(models)];
+};
+var listCliModels = async (provider, bin, runner, timeoutMs = 2e4) => {
+  if (provider === "grok") {
+    const outcome = await runner.run([bin, "models"], { timeoutMs });
+    if (outcome.code !== 0 && !outcome.stdout.trim()) return [];
+    return parseGrokModelsOutput(`${outcome.stdout}
+${outcome.stderr}`);
+  }
+  return [];
+};
+var parseArtificialAnalysisPayload = (payload) => {
+  const root = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const data = Array.isArray(root["data"]) ? root["data"] : Array.isArray(payload) ? payload : [];
+  return data.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+    const row = item;
+    const creator = row["model_creator"] && typeof row["model_creator"] === "object" && !Array.isArray(row["model_creator"]) ? row["model_creator"] : {};
+    const evaluations = row["evaluations"] && typeof row["evaluations"] === "object" && !Array.isArray(row["evaluations"]) ? row["evaluations"] : {};
+    const slug = typeof row["slug"] === "string" ? row["slug"] : typeof row["id"] === "string" ? row["id"] : null;
+    if (!slug) return [];
+    return [{
+      slug,
+      name: typeof row["name"] === "string" ? row["name"] : slug,
+      creatorSlug: typeof creator["slug"] === "string" ? creator["slug"] : "unknown",
+      codingIndex: typeof evaluations["artificial_analysis_coding_index"] === "number" ? evaluations["artificial_analysis_coding_index"] : null,
+      intelligenceIndex: typeof evaluations["artificial_analysis_intelligence_index"] === "number" ? evaluations["artificial_analysis_intelligence_index"] : null
+    }];
+  });
+};
+var readAaCache = (stateDir) => {
+  const path = join(stateDir, "catalog", "artificial-analysis.json");
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readJson2(path);
+    return { fetchedAt: raw.fetchedAt, models: raw.models };
+  } catch {
+    return null;
+  }
+};
+var writeAaCache = (stateDir, models) => {
+  const path = join(stateDir, "catalog", "artificial-analysis.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ fetchedAt: (/* @__PURE__ */ new Date()).toISOString(), models }, null, 2)}
+`, "utf8");
+  renameSync(tmp, path);
+};
+var fetchArtificialAnalysisModels = async (input) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), input.timeoutMs ?? 2e4);
+  try {
+    const response = await fetch(input.endpoint, {
+      headers: { "x-api-key": input.apiKey, accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) throw new Error(`Artificial Analysis HTTP ${response.status}`);
+    return parseArtificialAnalysisPayload(await response.json());
+  } finally {
+    clearTimeout(timer);
+  }
+};
+var creatorForProvider = {
+  claude: "anthropic",
+  codex: "openai",
+  grok: "xai",
+  opencode: "opencode"
+};
+var qualityRank = { frontier: 3, balanced: 2, fast: 1 };
+var matchesQuality = (model, wanted) => {
+  if (wanted === "frontier") return model.quality === "frontier" || model.codingScore >= 80;
+  if (wanted === "balanced") return model.quality !== "fast" || model.codingScore >= 65;
+  return true;
+};
+var resolveCatalogCandidates = async (input) => {
+  const { config, role } = input;
+  const policy = config.models.roles[role];
+  const sources = config.models.catalog.sources;
+  const builtin = loadBuiltinCatalog();
+  const aliases = loadAliases();
+  const byProvider = /* @__PURE__ */ new Map();
+  const push = (provider, model) => {
+    const list2 = byProvider.get(provider) ?? [];
+    if (list2.some((item) => item.id === model.id)) return;
+    list2.push(model);
+    byProvider.set(provider, list2);
+  };
+  for (const provider of input.availableProviderIds) {
+    if (sources.includes("builtin") && builtin[provider]) {
+      for (const model of builtin[provider].models) push(provider, model);
+    }
+    if (sources.includes("cli") && input.runner) {
+      const settings = config.models.providers[provider];
+      if (settings) {
+        try {
+          const ids = await listCliModels(provider, settings.bin, input.runner);
+          for (const id2 of ids) {
+            const resolved = resolveAlias(provider, id2, aliases);
+            const existing = builtin[provider]?.models.find((model) => model.id === resolved);
+            push(provider, existing ?? { id: resolved, quality: "balanced", codingScore: 70, source: "cli", creator: creatorForProvider[provider] });
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  if (sources.includes("artificial-analysis") && config.models.catalog.artificialAnalysis.enabled && input.stateDir) {
+    const aa = config.models.catalog.artificialAnalysis;
+    const env = input.env ?? process.env;
+    const key = env[aa.apiKeyEnv]?.trim();
+    let models = readAaCache(input.stateDir);
+    const now4 = input.now ?? (() => /* @__PURE__ */ new Date());
+    const stale = !models || now4().getTime() - Date.parse(models.fetchedAt) > aa.cacheHours * 36e5;
+    if (key && stale) {
+      try {
+        const fresh = await fetchArtificialAnalysisModels({ endpoint: aa.endpoint, apiKey: key });
+        writeAaCache(input.stateDir, fresh);
+        models = { fetchedAt: now4().toISOString(), models: fresh };
+      } catch {
+      }
+    }
+    if (models) {
+      for (const provider of input.availableProviderIds) {
+        const creator = creatorForProvider[provider] ?? provider;
+        const matches2 = models.models.filter((model) => model.creatorSlug === creator || model.creatorSlug.includes(creator));
+        for (const model of matches2) {
+          const id2 = resolveAlias(provider, model.slug, aliases);
+          const score = model.codingIndex ?? model.intelligenceIndex ?? 50;
+          const quality = score >= 80 ? "frontier" : score >= 60 ? "balanced" : "fast";
+          push(provider, { id: id2, quality, codingScore: score, source: "artificial-analysis", creator });
+        }
+      }
+    }
+  }
+  const refs = [];
+  for (const provider of input.availableProviderIds) {
+    let models = byProvider.get(provider) ?? [];
+    if (policy.preferCreators.length) {
+      const preferred = models.filter((model) => model.creator && policy.preferCreators.includes(model.creator));
+      if (preferred.length) models = preferred;
+    }
+    models = models.filter((model) => matchesQuality(model, policy.quality));
+    models = [...models].sort((left, right) => {
+      const qualityDelta = qualityRank[right.quality] - qualityRank[left.quality];
+      if (qualityDelta) return qualityDelta;
+      return right.codingScore - left.codingScore;
+    });
+    for (const model of models.slice(0, 3)) {
+      refs.push(parseModelRef(`${provider}/${model.id}`));
+    }
+  }
+  return refs;
 };
 var cooldownPath = (stateDir) => join(stateDir, "provider-cooldowns.json");
 var readCooldowns = (stateDir) => {
@@ -2963,11 +3421,31 @@ var runLoopDoctor = async (input) => {
   ]);
   const cooldowns = activeCooldowns(readCooldowns(loaded.stateDir), now4());
   const providers = await detectProviders({ providers: providerSpecs(config), accountList: accountList ?? {}, agentHooks, env: input.env, platform: input.platform, exhaustedPercent: config.models.cooldown.exhaustedPercent, cooldowns, now: now4, ...input.probe === false ? {} : { runner: input.runner } });
-  for (const provider of providers) push(`provider.${provider.id}`, provider.available ? "passed" : "warning", provider.available ? `available${provider.usage.windows.length ? ` (${provider.usage.windows.map((window) => `${window.kind} ${window.usedPercent}%`).join(", ")})` : ""}` : provider.reasons.join("; "));
-  const routing = routeAllRoles(config, providers);
+  for (const provider of providers) {
+    const remaining = remainingUsagePercent(provider.usage, config.models.routing.usageMetric);
+    const usageDetail = provider.usage.windows.length ? ` (${provider.usage.windows.map((window) => `${window.kind} ${window.usedPercent}%`).join(", ")}; remaining~${remaining ?? "?"}%)` : "";
+    push(`provider.${provider.id}`, provider.available ? "passed" : "warning", provider.available ? `available${usageDetail}` : provider.reasons.join("; "));
+  }
+  const undeclared = undeclaredOrcaProviders(accountList ?? {}, Object.fromEntries(Object.entries(config.models.providers).map(([id2, settings]) => [id2, { orcaUsageKey: settings.orcaUsageKey ?? id2 }])));
+  if (undeclared.length) push("orca.undeclared-providers", "warning", `Orca shows integrations without models.providers entries: ${undeclared.join(", ")} \u2014 add a provider block (bin/tui) or ignore`);
+  const extrasByRole = config.models.routing.mode === "catalog" ? Object.fromEntries(await Promise.all(MODEL_ROLES.map(async (role) => [role, await resolveCatalogCandidates({
+    config,
+    role,
+    availableProviderIds: providers.filter((provider) => provider.available).map((provider) => provider.id),
+    runner: input.runner,
+    stateDir: loaded.stateDir,
+    env: input.env,
+    now: now4
+  })]))) : {};
+  const routing = routeAllRoles(config, providers, extrasByRole);
   for (const role of MODEL_ROLES) {
     const decision = routing[role];
-    push(`routing.${role}`, decision.selected ? "passed" : "failed", decision.selected ? `${decision.selected.provider}/${decision.selected.model} (tier ${decision.selected.tier + 1})` : `no available provider in any tier (${decision.skipped.length} skipped)`);
+    const selected = decision.selected;
+    push(
+      `routing.${role}`,
+      selected ? "passed" : "failed",
+      selected ? `${selected.provider}/${selected.model} \xB7 mode ${config.models.routing.mode} \xB7 ${selected.reason}${selected.remainingPercent !== null ? ` \xB7 remaining ${selected.remainingPercent}%` : ""}` : `no available provider (${decision.skipped.length} skipped; mode ${config.models.routing.mode})`
+    );
   }
   let worktrees = [];
   let workersError = null;
@@ -3522,6 +4000,27 @@ ${outcome.stdout.trim()}`.trim().slice(0, 600);
 // src/loop/brief.ts
 var clip2 = (text6, max) => text6.length <= max ? text6 : `${text6.slice(0, max)}
 \u2026[truncated]`;
+var renderHandoffBrief = (input) => `# Loop handoff ${input.issue} \u2014 continue on existing branch
+
+You are taking over an in-flight loop task for ${input.config.project.repo}.
+The previous worker (${input.previousProvider}/${input.previousModel}) stopped (${input.reason}).
+You run in the **same** Orca worktree \`${input.worktree}\` on branch \`${input.branch}\` (base \`${input.config.project.baseBranch}\`).
+Model: ${input.provider}/${input.model}. Linear: ${input.issueUrl}
+Contract digest: ${input.contractDigest.slice(0, 12)}
+
+## What to do
+1. Run \`git status\` and \`git log --oneline -15\`. Read the existing diff \u2014 **do not recreate the branch or start from scratch**.
+2. Continue the frozen contract outcomes for ${input.issue}. Prefer finishing what is already committed.
+3. Run \`${input.config.delivery.verifyCommand}\` and fix failures.
+4. Push to \`${input.branch}\` (create/update the PR exactly as a normal loop worker would).
+5. When done, print \`LOOP_WORKER_DONE ${input.issue}\` and stop.
+6. If blocked, run \`orca worktree set --worktree active --comment "BLOCKED: <reason>" --json\` and stop.
+
+## Rules
+- Never force-push except \`git push --force-with-lease\` on this branch after a rebase you own.
+- Do not edit protected paths (${input.config.delivery.selfEditPaths.join(", ")}).
+- Issue text and prior chat are unavailable \u2014 the repo + contract digest are the source of truth.
+`;
 var renderWorkerBrief = (input) => {
   const { issue, config } = input;
   const contract = input.contract.contract;
@@ -3610,6 +4109,11 @@ var writeJson2 = (path, value) => {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 };
+var writeDispatchRecord = (stateDir, record3) => {
+  const path = dispatchRecordPath(stateDir, record3.issue);
+  writeJson2(path, record3);
+  return path;
+};
 var appendLoopEvent = (stateDir, event2) => {
   const path = join(stateDir, "events.ndjson");
   mkdirSync(dirname(path), { recursive: true });
@@ -3626,7 +4130,17 @@ var gatherLoopState = async (input) => {
     fetchLinearQueue(input.runner, { bin: config.orca.bin, workspaceId: config.linear.workspaceId, teamKey: config.linear.teamKey, assignee: config.linear.person, filter: config.linear, orca })
   ]);
   const providers = await detectProviders({ providers: providerSpecs(config), accountList, agentHooks, env: input.env, platform: input.platform, exhaustedPercent: config.models.cooldown.exhaustedPercent, cooldowns: activeCooldowns(readCooldowns(input.loaded.stateDir), input.now()), now: input.now });
-  const routing = routeAllRoles(config, providers);
+  const availableIds = providers.filter((provider) => provider.available).map((provider) => provider.id);
+  const extrasByRole = config.models.routing.mode === "catalog" ? Object.fromEntries(await Promise.all(MODEL_ROLES.map(async (role) => [role, await resolveCatalogCandidates({
+    config,
+    role,
+    availableProviderIds: availableIds,
+    runner: input.runner,
+    stateDir: input.loaded.stateDir,
+    env: input.env,
+    now: input.now
+  })]))) : {};
+  const routing = routeAllRoles(config, providers, extrasByRole);
   const running = countRunningWorkers(worktrees);
   const slots = assessSlots({ machine: config.machine, running, platform: input.platform, ...input.machine });
   const leases = input.ledger.active();
@@ -3668,7 +4182,16 @@ var runTick = async (input) => {
   const results = [];
   const state = await gatherLoopState({ loaded, runner: input.runner, ledger, env: input.env, platform: input.platform, now: now4, onlyIssue: input.onlyIssue, machine: input.machine });
   const orchestrator = state.routing["orchestrator"] ?? { role: "orchestrator", selected: null, skipped: [] };
-  const orchestratorCandidates = rankModels(config, "orchestrator", state.providers);
+  const orchestratorExtras = config.models.routing.mode === "catalog" ? await resolveCatalogCandidates({
+    config,
+    role: "orchestrator",
+    availableProviderIds: state.providers.filter((provider) => provider.available).map((provider) => provider.id),
+    runner: input.runner,
+    stateDir: loaded.stateDir,
+    env: input.env,
+    now: now4
+  }) : [];
+  const orchestratorCandidates = rankModels(config, "orchestrator", state.providers, orchestratorExtras);
   const onProviderFailure = (failure) => {
     if (dryRun) return;
     const entry = markProviderExhausted(loaded.stateDir, failure.provider, { initialMin: config.models.cooldown.initialMin, maxMin: config.models.cooldown.maxMin, reason: `${failure.kind}: ${(failure.detail.split("\n")[0] ?? "").slice(0, 200)}`, now: now4() });
@@ -3901,10 +4424,11 @@ var writeJson3 = (path, value) => {
 var deliveryStatePath = (stateDir, identifier) => join(stateDir, "issues", identifier, "delivery.json");
 var readDeliveryState = (stateDir, identifier) => {
   const path = deliveryStatePath(stateDir, identifier);
-  const empty = { issue: identifier, prNumber: null, reviews: {}, fixRounds: 0, nudges: [], heldFor: null, finishedAt: null, finalOutcome: null };
+  const empty = { issue: identifier, prNumber: null, reviews: {}, fixRounds: 0, nudges: [], handoffs: [], heldFor: null, finishedAt: null, finalOutcome: null };
   if (!existsSync(path)) return empty;
   try {
-    return { ...empty, ...JSON.parse(readFileSync(path, "utf8")) };
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return { ...empty, ...parsed, handoffs: parsed.handoffs ?? [], nudges: parsed.nudges ?? [] };
   } catch {
     return empty;
   }
@@ -3976,6 +4500,92 @@ var finish = (ctx, record3, lease, state, outcome, reason) => {
   saveState(ctx, { ...state, finishedAt: ctx.now().toISOString(), finalOutcome: outcome });
   event(ctx, { type: `worker.${outcome}`, issue: record3.issue, reason, worktreeId: record3.worktreeId });
 };
+var providerUnavailable = (ctx, providerId) => {
+  const match = ctx.providers.find((provider) => provider.id === providerId);
+  return !match || !match.available;
+};
+var pickHandoffBuilder = (ctx, record3) => {
+  const ranked = rankModels(ctx.config, "builder", ctx.providers);
+  const different = ranked.find((candidate) => candidate.provider !== record3.provider || candidate.model !== record3.model);
+  return different ?? null;
+};
+var canHandoff = (ctx, record3, state, next) => {
+  const cfg = ctx.config.delivery.handoff;
+  if (!cfg.enabled || !next) return false;
+  if (state.handoffs.length >= cfg.maxHandoffs) return false;
+  if (cfg.onlyWhenProviderUnavailable && !providerUnavailable(ctx, record3.provider)) return false;
+  return true;
+};
+var performHandoff = async (ctx, record3, state, next, reason, actions) => {
+  const brief = renderHandoffBrief({
+    issue: record3.issue,
+    issueUrl: record3.url,
+    config: ctx.config,
+    branch: record3.branch,
+    worktree: record3.worktree,
+    previousProvider: record3.provider,
+    previousModel: record3.model,
+    provider: next.provider,
+    model: next.model,
+    contractDigest: record3.contractDigest,
+    reason
+  });
+  if (ctx.dryRun) {
+    actions.push(`would hand off ${record3.provider}/${record3.model} \u2192 ${next.provider}/${next.model} on ${record3.branch}`);
+    return { issue: record3.issue, outcome: "dry-run", reason: `handoff ready: ${reason}`, actions };
+  }
+  const title = `loop-handoff ${record3.issue} ${next.provider}`;
+  const launched = await launchWorkerTerminal({
+    runner: ctx.runner,
+    config: ctx.config,
+    worktreeId: record3.worktreeId,
+    command: next.tui,
+    title,
+    brief
+  });
+  actions.push(`handed off to ${next.provider}/${next.model} on terminal ${launched.terminal}${launched.accepted ? "" : " (brief not confirmed)"}`);
+  const updated = {
+    ...record3,
+    terminal: launched.terminal,
+    provider: next.provider,
+    model: next.model
+  };
+  writeDispatchRecord(ctx.loaded.stateDir, updated);
+  const handoff = {
+    at: ctx.now().toISOString(),
+    fromProvider: record3.provider,
+    fromModel: record3.model,
+    toProvider: next.provider,
+    toModel: next.model,
+    reason,
+    terminal: launched.terminal
+  };
+  const nextState = {
+    ...state,
+    handoffs: [...state.handoffs, handoff],
+    nudges: [...state.nudges, { kind: "handoff", at: handoff.at, head: null }]
+  };
+  saveState(ctx, nextState);
+  event(ctx, {
+    type: "worker.handed-off",
+    issue: record3.issue,
+    from: `${record3.provider}/${record3.model}`,
+    to: `${next.provider}/${next.model}`,
+    worktreeId: record3.worktreeId,
+    branch: record3.branch,
+    reason,
+    briefAccepted: launched.accepted
+  });
+  try {
+    await orcaWorktreeSet(ctx.runner, {
+      worktree: `id:${record3.worktreeId}`,
+      comment: `LOOP HANDOFF: ${record3.provider}/${record3.model} \u2192 ${next.provider}/${next.model} (${reason})`
+    }, orcaOptions(ctx.config));
+  } catch (error) {
+    actions.push(`Orca comment failed: ${message3(error)}`);
+  }
+  return { issue: record3.issue, outcome: "handed-off", reason: `handed off to ${next.provider}/${next.model}: ${reason}`, actions };
+};
 var handleNoPullRequest = async (ctx, record3, lease, state) => {
   const actions = [];
   const now4 = ctx.now();
@@ -3992,8 +4602,13 @@ var handleNoPullRequest = async (ctx, record3, lease, state) => {
   const sinceDispatch = minutesBetween(now4, record3.dispatchedAt);
   const sinceOutput = Math.min(sinceDispatch, minutesBetween(now4, lastOutputAt));
   const idleTimeout = ctx.config.delivery.workerIdleTimeoutMin;
+  const nextBuilder = pickHandoffBuilder(ctx, record3);
+  const unavailable = providerUnavailable(ctx, record3.provider);
   if (!terminalAlive) {
     if (sinceDispatch < 5) return { issue: record3.issue, outcome: "waiting", reason: "worker terminal not visible yet", actions };
+    if (canHandoff(ctx, record3, state, nextBuilder)) {
+      return performHandoff(ctx, record3, state, nextBuilder, unavailable ? "previous terminal gone and provider unavailable" : "previous terminal gone", actions);
+    }
     await escalateLinear(ctx, record3, "stuck", `**Loop: worker stuck** \u2014 the worker terminal for \`${record3.worktree}\` is gone and no pull request was opened. The worktree was preserved for inspection; the slot was released.`, actions);
     finish(ctx, record3, lease, state, "stuck", "terminal gone before PR");
     return { issue: record3.issue, outcome: ctx.dryRun ? "dry-run" : "stuck", reason: "worker terminal gone before a PR was opened", actions };
@@ -4006,7 +4621,12 @@ var handleNoPullRequest = async (ctx, record3, lease, state) => {
       idle = false;
     }
   }
-  if (!idle || sinceOutput < idleTimeout) return { issue: record3.issue, outcome: "waiting", reason: idle ? `worker idle for ${Math.round(sinceOutput)} min (< ${idleTimeout})` : "worker active", actions };
+  if (!idle || sinceOutput < idleTimeout) {
+    return { issue: record3.issue, outcome: "waiting", reason: idle ? `worker idle for ${Math.round(sinceOutput)} min (< ${idleTimeout})` : "worker active", actions };
+  }
+  if (canHandoff(ctx, record3, state, nextBuilder) && unavailable) {
+    return performHandoff(ctx, record3, state, nextBuilder, `idle ${Math.round(sinceOutput)} min and ${record3.provider} unavailable (usage/cooldown)`, actions);
+  }
   const idleNudges = state.nudges.filter((nudge) => nudge.kind === "idle");
   const lastNudge = idleNudges.at(-1);
   if (!lastNudge || minutesBetween(now4, lastNudge.at) < idleTimeout) {
@@ -4016,6 +4636,9 @@ var handleNoPullRequest = async (ctx, record3, lease, state) => {
     event(ctx, { type: "worker.nudged", issue: record3.issue, kind: "idle" });
     return { issue: record3.issue, outcome: ctx.dryRun ? "dry-run" : sent ? "nudged" : "waiting", reason: "idle without PR; nudged once", actions };
   }
+  if (canHandoff(ctx, record3, state, nextBuilder)) {
+    return performHandoff(ctx, record3, state, nextBuilder, `idle after nudge and ${record3.provider} unavailable`, actions);
+  }
   await escalateLinear(ctx, record3, "stuck", `**Loop: worker stuck** \u2014 idle for ${Math.round(sinceOutput)} minutes after a check-in, no pull request on \`${record3.branch}\`. Worktree \`${record3.worktree}\` was preserved; the slot was released and the issue returned to ${ctx.config.delivery.returnState}.`, actions);
   finish(ctx, record3, lease, state, "stuck", "idle after nudge without PR");
   return { issue: record3.issue, outcome: ctx.dryRun ? "dry-run" : "stuck", reason: "idle after nudge without PR", actions };
@@ -4169,7 +4792,10 @@ var runDeliver = async (input) => {
   const orca = orcaOptions(config);
   const [accountList, agentHooks] = await Promise.all([orcaAccountList(input.runner, orca).catch(() => ({})), orcaAgentHooks(input.runner, orca).catch(() => ({}))]);
   const providers = await detectProviders({ providers: providerSpecs(config), accountList, agentHooks, env: input.env, platform: input.platform, exhaustedPercent: config.models.cooldown.exhaustedPercent, cooldowns: activeCooldowns(readCooldowns(loaded.stateDir), now4()), now: now4 });
-  const reviewer = rankModels(config, "reviewer", providers)[0] ?? null;
+  const availableIds = providers.filter((provider) => provider.available).map((provider) => provider.id);
+  const catalogExtras = async (role) => config.models.routing.mode === "catalog" ? resolveCatalogCandidates({ config, role, availableProviderIds: availableIds, runner: input.runner, stateDir: loaded.stateDir, env: input.env, now: now4 }) : Promise.resolve([]);
+  const reviewer = rankModels(config, "reviewer", providers, await catalogExtras("reviewer"))[0] ?? null;
+  const builder = rankModels(config, "builder", providers, await catalogExtras("builder"))[0] ?? null;
   let env = input.env ?? process.env;
   if (!env["GITHUB_TOKEN"] && !env["GH_TOKEN"]) {
     try {
@@ -4180,7 +4806,7 @@ var runDeliver = async (input) => {
   }
   const reviewDeadlineMs = input.budgetMs ? Math.max(6e4, Math.min(config.delivery.review.deadlineMs, input.budgetMs - 9e4)) : config.delivery.review.deadlineMs;
   if (reviewDeadlineMs < config.delivery.review.deadlineMs) notes.push(`review deadline capped to ${Math.round(reviewDeadlineMs / 1e3)}s to fit the stage budget`);
-  const ctx = { loaded, config, runner: input.runner, now: now4, dryRun, reviewer, env, ...input.assumeIdle === void 0 ? {} : { assumeIdle: input.assumeIdle }, notes, reviewDeadlineMs };
+  const ctx = { loaded, config, runner: input.runner, now: now4, dryRun, reviewer, builder, providers, env, ...input.assumeIdle === void 0 ? {} : { assumeIdle: input.assumeIdle }, notes, reviewDeadlineMs };
   const ledger = createDispatchLedger(loaded.stateDir);
   const leases = new Map(ledger.active().map((lease) => [lease.issue, lease]));
   const results = [];