@tavaressan/vetor 0.1.0

package/templates/opencode/scripts/lib/project.ts

@@ -0,0 +1,240 @@
+// Detecção de runtime, gerenciador de pacotes e comando de teste de um projeto.
+// Compartilhado por detect-project.ts e prepare-worktree.ts.
+
+export type Runtime =
+  | "deno"
+  | "node"
+  | "rust"
+  | "go"
+  | "python"
+  | "gradle"
+  | "unknown";
+
+export interface ProjectInfo {
+  runtime: Runtime;
+  packageManager: string | null;
+  testCommand: string;
+  /** Deno com package.json precisa de `deno install`; Deno puro resolve tudo pelo cache global. */
+  needsInstall: boolean;
+}
+
+function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** JSON.parse rejeita BOM, comum em arquivos gerados no Windows. */
+export function readJson(path: string): unknown {
+  return JSON.parse(Deno.readTextFileSync(path).replace(/^/, ""));
+}
+
+/**
+ * Issue #307: no Git Bash do Windows, `$(pwd)` produz um path POSIX-style (`/c/Users/...`), não
+ * nativo (`C:\Users\...`). `Deno.Command`/`Deno.statSync` no Windows não resolvem esse formato —
+ * `git rev-parse` falha ao spawnar (`No such cwd`) e `Deno.statSync` trata `/c/...` como relativo à
+ * raiz da unidade atual, nunca encontrando o arquivo real. Normaliza só no Windows (no Linux/macOS
+ * `/c/Users/x` já é um path absoluto legítimo, nunca deve ser reescrito).
+ */
+export function normalizeCwd(cwd: string): string {
+  if (Deno.build.os !== "windows") return cwd;
+  const match = cwd.match(/^\/([a-zA-Z])\/(.*)$/);
+  if (!match) return cwd;
+  const [, drive, rest] = match;
+  return `${drive.toUpperCase()}:/${rest}`;
+}
+
+/** Lê o campo `tasks` de um deno.json para escolher entre `deno task test` e `deno test -A`. */
+function hasDenoTestTask(dir: string): boolean {
+  for (const name of ["deno.json", "deno.jsonc"]) {
+    const path = `${dir}/${name}`;
+    if (!exists(path)) continue;
+    try {
+      // jsonc com comentários falha aqui; nesse caso caímos no default (deno test -A).
+      const parsed = readJson(path) as { tasks?: { test?: unknown } };
+      return typeof parsed?.tasks?.test === "string";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function detectNodePackageManager(dir: string): string {
+  if (exists(`${dir}/bun.lockb`) || exists(`${dir}/bun.lock`)) return "bun";
+  if (exists(`${dir}/pnpm-lock.yaml`)) return "pnpm";
+  if (exists(`${dir}/yarn.lock`)) return "yarn";
+  return "npm";
+}
+
+export function detectProject(dir: string): ProjectInfo {
+  const hasDeno = exists(`${dir}/deno.json`) || exists(`${dir}/deno.jsonc`);
+  const hasPackageJson = exists(`${dir}/package.json`);
+
+  if (hasDeno) {
+    return {
+      runtime: "deno",
+      packageManager: "deno",
+      testCommand: hasDenoTestTask(dir) ? "deno task test" : "deno test -A",
+      // Sem package.json o nodeModulesDir default é "none": as deps vêm do cache
+      // global $DENO_DIR, que já é compartilhado por todos os worktrees.
+      needsInstall: hasPackageJson,
+    };
+  }
+
+  if (hasPackageJson) {
+    const pm = detectNodePackageManager(dir);
+    return {
+      runtime: "node",
+      packageManager: pm,
+      testCommand: `${pm} test`,
+      needsInstall: true,
+    };
+  }
+
+  if (exists(`${dir}/Cargo.toml`)) {
+    return {
+      runtime: "rust",
+      packageManager: "cargo",
+      testCommand: "cargo test",
+      needsInstall: false,
+    };
+  }
+  if (exists(`${dir}/go.mod`)) {
+    return {
+      runtime: "go",
+      packageManager: "go",
+      testCommand: "go test ./...",
+      needsInstall: false,
+    };
+  }
+  if (
+    exists(`${dir}/pyproject.toml`) || exists(`${dir}/requirements.txt`) ||
+    exists(`${dir}/poetry.lock`)
+  ) {
+    const pm = exists(`${dir}/poetry.lock`) ? "poetry" : "pip";
+    return { runtime: "python", packageManager: pm, testCommand: "pytest", needsInstall: true };
+  }
+  if (
+    exists(`${dir}/build.gradle`) || exists(`${dir}/build.gradle.kts`) ||
+    exists(`${dir}/gradlew`)
+  ) {
+    return {
+      runtime: "gradle",
+      packageManager: "gradle",
+      testCommand: "./gradlew test",
+      needsInstall: false,
+    };
+  }
+
+  return { runtime: "unknown", packageManager: null, testCommand: "", needsInstall: false };
+}
+
+/** Convenções observadas no repositório. Campo ausente = fato não encontrado. */
+export interface Conventions {
+  denoTasks?: string[];
+  denoImportMap?: boolean;
+  nodeScripts?: string[];
+  nodeModuleType?: string;
+  hasTsconfig?: boolean;
+  formatter?: "prettier" | "biome";
+  linter?: "eslint" | "biome";
+}
+
+const PRETTIER_CONFIGS = [
+  ".prettierrc",
+  ".prettierrc.json",
+  ".prettierrc.yaml",
+  ".prettierrc.yml",
+  ".prettierrc.js",
+  ".prettierrc.cjs",
+  "prettier.config.js",
+  "prettier.config.mjs",
+  "prettier.config.cjs",
+];
+
+const ESLINT_CONFIGS = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  ".eslintrc",
+  ".eslintrc.json",
+  ".eslintrc.js",
+  ".eslintrc.cjs",
+  ".eslintrc.yaml",
+  ".eslintrc.yml",
+];
+
+const BIOME_CONFIGS = ["biome.json", "biome.jsonc"];
+
+function anyExists(dir: string, names: string[]): boolean {
+  return names.some((name) => exists(`${dir}/${name}`));
+}
+
+function keysOf(record: unknown): string[] {
+  return record && typeof record === "object" ? Object.keys(record as object) : [];
+}
+
+/**
+ * Sonda as convenções do projeto. Só relata o que foi verificado em arquivo — um fato
+ * não encontrado é omitido, nunca substituído por um default plausível. Uma convenção
+ * inventada é pior que nenhuma: leva o agente a "consertar" código correto.
+ */
+export function detectConventions(dir: string): Conventions {
+  const conv: Conventions = {};
+
+  for (const name of ["deno.json", "deno.jsonc"]) {
+    if (!exists(`${dir}/${name}`)) continue;
+    try {
+      // jsonc com comentários falha aqui; sem o parse não afirmamos nada.
+      const parsed = readJson(`${dir}/${name}`) as { tasks?: unknown; imports?: unknown };
+      const tasks = keysOf(parsed.tasks);
+      if (tasks.length > 0) conv.denoTasks = tasks;
+      if (keysOf(parsed.imports).length > 0) conv.denoImportMap = true;
+    } catch { /* config ilegível: nenhum fato a relatar */ }
+    break;
+  }
+
+  if (exists(`${dir}/package.json`)) {
+    try {
+      const parsed = readJson(`${dir}/package.json`) as { scripts?: unknown; type?: unknown };
+      const scripts = keysOf(parsed.scripts);
+      if (scripts.length > 0) conv.nodeScripts = scripts;
+      if (typeof parsed.type === "string") conv.nodeModuleType = parsed.type;
+    } catch { /* package.json ilegível: nenhum fato a relatar */ }
+  }
+
+  if (exists(`${dir}/tsconfig.json`)) conv.hasTsconfig = true;
+
+  const hasBiome = anyExists(dir, BIOME_CONFIGS);
+  if (anyExists(dir, PRETTIER_CONFIGS)) conv.formatter = "prettier";
+  else if (hasBiome) conv.formatter = "biome";
+
+  if (anyExists(dir, ESLINT_CONFIGS)) conv.linter = "eslint";
+  else if (hasBiome) conv.linter = "biome";
+
+  return conv;
+}
+
+/** Executa um comando e devolve o código de saída, sem lançar. */
+export async function run(
+  cmd: string,
+  args: string[],
+  cwd: string,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  try {
+    const out = await new Deno.Command(cmd, { args, cwd, stdout: "piped", stderr: "piped" })
+      .output();
+    return {
+      code: out.code,
+      stdout: new TextDecoder().decode(out.stdout),
+      stderr: new TextDecoder().decode(out.stderr),
+    };
+  } catch (e) {
+    return { code: 127, stdout: "", stderr: String(e) };
+  }
+}

package/templates/opencode/scripts/lib/project_test.ts

@@ -0,0 +1,45 @@
+import { assertEquals } from "@std/assert";
+import { normalizeCwd } from "./project.ts";
+
+Deno.test({
+  name:
+    "normalizeCwd converte path POSIX-style de drive (Git Bash Windows) para nativo (issue #307)",
+  ignore: Deno.build.os !== "windows",
+  fn: () => {
+    assertEquals(normalizeCwd("/c/Users/test"), "C:/Users/test");
+  },
+});
+
+Deno.test({
+  name: "normalizeCwd não altera path já nativo (Windows)",
+  ignore: Deno.build.os !== "windows",
+  fn: () => {
+    assertEquals(normalizeCwd("C:/Users/test"), "C:/Users/test");
+  },
+});
+
+// Issue #313: um dispatch real do issue-coordinator, rodando de dentro de um mount MSYS sem letra
+// de unidade (`/tmp/...`, comum quando o cwd do Git Bash está sob um diretório temp), quebrou
+// `ensure-external-directory-permission.ts`/`resolve-model.ts` com `$(pwd)` cru — o Deno nativo do
+// Windows não resolve esse path, e o erro de escrita apareceu como um falso "config não encontrado".
+// `normalizeCwd()` só cobre o padrão `/<letra>/...` (issue #307), não mounts MSYS arbitrários — a
+// mitigação escolhida foi no call site (`issue-coordinator.md` usa `$(pwd -W 2>/dev/null || pwd)`
+// em vez de `$(pwd)`), não aqui. Este teste documenta a limitação conhecida para quem for revisitar
+// `normalizeCwd()` no futuro, em vez de deixá-la implícita.
+Deno.test({
+  name:
+    "normalizeCwd não resolve mounts MSYS sem letra de unidade (ex. /tmp/...) — mitigado no call site (issue #313)",
+  ignore: Deno.build.os !== "windows",
+  fn: () => {
+    assertEquals(normalizeCwd("/tmp/foo/bar"), "/tmp/foo/bar");
+  },
+});
+
+Deno.test({
+  name: "normalizeCwd é identidade fora do Windows",
+  ignore: Deno.build.os === "windows",
+  fn: () => {
+    assertEquals(normalizeCwd("/c/Users/test"), "/c/Users/test");
+    assertEquals(normalizeCwd("/home/test"), "/home/test");
+  },
+});

package/templates/opencode/scripts/lib/status.ts

@@ -0,0 +1,69 @@
+// Status file dos workers: <root>/.claude/vetor/status/<branch>.md
+//
+// Vive na raiz do repositório, não no worktree, para que o issue-coordinator consiga
+// agregar o andamento de todos os workers. Compartilhado por safety-check.ts (que barra
+// push de worker não-GREEN) e check-status.ts (que barra worker terminando sem status).
+
+import { run } from "./project.ts";
+
+/** Estados em que o worker pode legitimamente encerrar. */
+export const TERMINAL_STATES = ["GREEN", "FAILED_MAX_ITERATIONS", "BLOCKED_WAITING"];
+
+export interface WorktreeInfo {
+  /** Raiz do repositório principal (não do worktree). */
+  root: string;
+  /** Raiz do worktree atual — a fronteira de escrita do worker. */
+  toplevel: string;
+  branch: string;
+  /** git-dir difere de git-common-dir apenas em worktree linkado. */
+  isLinked: boolean;
+}
+
+export async function resolveWorktree(cwd: string): Promise<WorktreeInfo | null> {
+  const gitDir = (await run("git", ["rev-parse", "--git-dir"], cwd)).stdout.trim();
+  const commonDir = (await run("git", ["rev-parse", "--git-common-dir"], cwd)).stdout.trim();
+  if (!gitDir) return null;
+
+  const branch = (await run("git", ["branch", "--show-current"], cwd)).stdout.trim();
+  const root = (await run("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd))
+    .stdout.trim().replace(/\/?\.git\/?$/, "");
+  // O cwd pode ser um subdiretório do worktree; a fronteira é o toplevel.
+  const toplevel = (await run("git", ["rev-parse", "--show-toplevel"], cwd)).stdout.trim();
+  if (!branch || !root || !toplevel) return null;
+
+  return { root, toplevel, branch, isLinked: gitDir !== commonDir };
+}
+
+export function statusFilePath(root: string, branch: string): string {
+  return `${root}/.claude/vetor/status/${branch.replaceAll("/", "-")}.md`;
+}
+
+/**
+ * Onde fica registrado, por `agent_id`, qual worktree (toplevel) esse agente resolveu da
+ * primeira vez que o hook de escrita rodou para ele. `agent_id` é estável e único por
+ * instância de subagente (ver issue #63) — diferente de `agent_type`, compartilhado por
+ * todos os workers do mesmo tipo.
+ */
+export function agentBindingPath(root: string, agentId: string): string {
+  return `${root}/.claude/vetor/status/.agent-cwd/${agentId}`;
+}
+
+/** Marcador gravado por prepareDeps (prepare-worktree.ts) quando a instalação de deps falha. */
+export function prepareFailedMarkerPath(worktreePath: string): string {
+  return `${worktreePath}/.claude/vetor/prepare-failed`;
+}
+
+/** Devolve o valor de `Status:` do arquivo, ou null se ele não existe. */
+export function readStatus(path: string): string | null {
+  let content: string;
+  try {
+    content = Deno.readTextFileSync(path);
+  } catch {
+    return null;
+  }
+  return content.match(/^Status: *(.+)$/m)?.[1]?.trim() ?? "";
+}
+
+export function isTerminal(status: string | null): boolean {
+  return status !== null && TERMINAL_STATES.includes(status);
+}

package/templates/opencode/scripts/lib/worktree.ts

@@ -0,0 +1,41 @@
+// Frescor de worktree: garante que o cwd de um worker continua sendo um worktree válido
+// da raiz do projeto — dentro de `.claude/worktrees/` e ainda registrado em
+// `git worktree list`. Sem isso, um agente cujo worktree foi removido (worktree-ship) ou
+// aponta para fora da árvore esperada seguiria operando com um cwd stale/indevido.
+
+import { isWithin, normalizePath } from "./guard.ts";
+
+/** Extrai os paths de cada bloco `worktree <path>` de `git worktree list --porcelain`. */
+export function parseWorktreePaths(porcelain: string): string[] {
+  return [...porcelain.matchAll(/^worktree (.+)$/gm)].map((m) => m[1].trim());
+}
+
+function isListedWorktree(toplevel: string, porcelain: string): boolean {
+  const target = normalizePath(toplevel);
+  return parseWorktreePaths(porcelain).some((path) => normalizePath(path) === target);
+}
+
+/**
+ * Avalia se `toplevel` (o cwd resolvido do worker) ainda é um worktree válido de `root`
+ * (a raiz do repositório principal): precisa estar dentro de `<root>/.claude/worktrees` e
+ * continuar presente em `porcelain` (saída de `git worktree list --porcelain`, rodado a
+ * partir de `root`). Devolve a mensagem de bloqueio, ou `null` se estiver tudo certo.
+ */
+export function evaluateFreshness(
+  toplevel: string,
+  root: string,
+  porcelain: string,
+): string | null {
+  if (!isWithin(toplevel, `${root}/.claude/worktrees`)) {
+    return `ERROR: worktree fora de ${root}/.claude/worktrees bloqueado pelo Vetor Safety Hook: ${toplevel}\n` +
+      "Workers só devem operar dentro de .claude/worktrees/<slug> na raiz do projeto.";
+  }
+
+  if (!isListedWorktree(toplevel, porcelain)) {
+    return `ERROR: worktree stale bloqueado pelo Vetor Safety Hook: ${toplevel}\n` +
+      "Este worktree não aparece mais em `git worktree list` — provavelmente já foi removido " +
+      "(worktree-ship ou limpeza manual). Encerre esta sessão; ela não pode mais operar aqui.";
+  }
+
+  return null;
+}

package/templates/opencode/scripts/model-health.ts

@@ -0,0 +1,50 @@
+// CLI invocado por opencode/plugin/vetor.ts (hook `event`, evento `session.error`) via
+// `deno run -A`, no mesmo padrão de safety-check.ts/check-edit.ts: payload JSON no stdin,
+// silêncio se não houver o que registrar.
+//
+// Contrato de stdin:
+//   { model?: string; statusCode?: number; isRetryable?: boolean;
+//     responseHeaders?: Record<string,string>; message?: string; cwd?: string }
+//
+// `model` já vem resolvido pelo plugin como "<providerID>/<modelID>" (correlacionado via
+// `chat.params`, já que `session.error` não carrega o model/provider — ver lib/model-health.ts).
+// Sem `model` conhecido, ainda registramos sob a chave "unknown" — perder o sinal de rate-limit
+// custa mais do que uma chave imprecisa (o coordinator trata "unknown" como não-fallback-ável).
+
+import { resolveWorktree } from "./lib/status.ts";
+import { computeUntil, isRateLimitOrQuotaStatus, recordModelHealth } from "./lib/model-health.ts";
+
+interface Payload {
+  model?: string;
+  statusCode?: number;
+  responseHeaders?: Record<string, string>;
+  message?: string;
+  cwd?: string;
+}
+
+async function main() {
+  const raw = new TextDecoder().decode(await new Response(Deno.stdin.readable).arrayBuffer());
+
+  let input: Payload;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    Deno.exit(0);
+  }
+
+  if (!isRateLimitOrQuotaStatus(input.statusCode)) Deno.exit(0);
+
+  const cwd = input.cwd ?? Deno.cwd();
+  const worktree = await resolveWorktree(cwd);
+  if (!worktree) Deno.exit(0);
+
+  const path = `${worktree.root}/.claude/vetor/status/model-health.json`;
+  const now = Date.now();
+  const until = computeUntil(now, input.responseHeaders);
+  const key = input.model ?? "unknown";
+  const lastError = `HTTP ${input.statusCode}${input.message ? `: ${input.message}` : ""}`;
+
+  recordModelHealth(path, key, { status: "degraded", until, lastError });
+}
+
+await main();

package/templates/opencode/scripts/model-health_test.ts

@@ -0,0 +1,80 @@
+// Teste de ponta-a-ponta do CLI (issue #83): simula o payload que
+// opencode/plugin/vetor.ts envia via stdin ao detectar um `ApiError` com `statusCode: 429`
+// num evento `session.error`, e confirma que `.claude/vetor/status/model-health.json` é
+// criado/atualizado corretamente — incluindo o cálculo de `until` a partir de `retry-after`.
+
+import { assertEquals } from "@std/assert";
+
+const SCRIPT = new URL("./model-health.ts", import.meta.url).pathname;
+
+async function git(args: string[], cwd: string): Promise<void> {
+  await new Deno.Command("git", { args, cwd, stdout: "null", stderr: "null" }).output();
+}
+
+async function makeRepo(): Promise<string> {
+  const dir = await Deno.makeTempDir();
+  await git(["init", "-q", "-b", "main"], dir);
+  await git(["config", "user.email", "test@example.com"], dir);
+  await git(["config", "user.name", "Test"], dir);
+  await git(["commit", "-q", "--allow-empty", "-m", "init"], dir);
+  return dir;
+}
+
+async function runCli(input: unknown): Promise<{ code: number }> {
+  const command = new Deno.Command("deno", {
+    args: ["run", "-A", SCRIPT],
+    stdin: "piped",
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const child = command.spawn();
+  const writer = child.stdin.getWriter();
+  await writer.write(new TextEncoder().encode(JSON.stringify(input)));
+  await writer.close();
+  const out = await child.output();
+  return { code: out.code };
+}
+
+Deno.test("model-health CLI - ApiError 429 com retry-after grava model-health.json", async () => {
+  const repo = await makeRepo();
+  const now = Date.now();
+
+  await runCli({
+    model: "anthropic/claude-sonnet-4-5",
+    statusCode: 429,
+    responseHeaders: { "retry-after": "20" },
+    message: "rate limited",
+    cwd: repo,
+  });
+
+  const path = `${repo}/.claude/vetor/status/model-health.json`;
+  const file = JSON.parse(await Deno.readTextFile(path));
+  const entry = file["anthropic/claude-sonnet-4-5"];
+
+  assertEquals(entry.status, "degraded");
+  assertEquals(entry.lastError, "HTTP 429: rate limited");
+  // até 2s de tolerância pelo tempo de subida do processo `deno run`.
+  const expected = now + 20_000;
+  const diff = Math.abs(entry.until - expected);
+  if (diff > 5_000) throw new Error(`until fora da tolerância esperada: diff=${diff}ms`);
+});
+
+Deno.test("model-health CLI - status não relacionado a rate limit não grava nada", async () => {
+  const repo = await makeRepo();
+
+  const result = await runCli({
+    model: "anthropic/claude-sonnet-4-5",
+    statusCode: 500,
+    message: "internal error",
+    cwd: repo,
+  });
+
+  assertEquals(result.code, 0);
+  let exists = true;
+  try {
+    await Deno.stat(`${repo}/.claude/vetor/status/model-health.json`);
+  } catch {
+    exists = false;
+  }
+  assertEquals(exists, false);
+});

package/templates/opencode/scripts/resolve-model.ts

@@ -0,0 +1,112 @@
+// CLI invocado pelo issue-coordinator portado (opencode/agent/issue-coordinator.md,
+// issue #84) antes de montar cada comando `opencode run --dir ... --model <provider/model>`.
+//
+// Lê a lista de fallback ordenada de `.claude/vetor/config.json` (`modelFallback.<tier>`) e
+// `.claude/vetor/status/model-health.json` (escrito pelo hook `event` da issue #83), e devolve
+// no stdout o primeiro modelo/provedor saudável da lista.
+//
+// Códigos de saída (distintos porque o coordinator reage diferente a cada um — issue #312):
+//   0 - sucesso, modelo/provedor saudável no stdout.
+//   1 - todos os modelos do tier estão `degraded` (transitório) — o coordinator mantém o grupo
+//       `QUEUED` e tenta de novo no próximo ciclo de monitoramento.
+//   2 - `modelFallback.<tier>` não configurado e nenhum `fallback` explícito foi passado (erro de
+//       configuração permanente, não transitório) — o coordinator NÃO deve reter o grupo em
+//       `QUEUED` esperando algo mudar sozinho; precisa escalar/parar e pedir configuração.
+//
+// Contrato de stdin:
+//   { tier?: "simple" | "complex"; fallback?: string[]; cwd?: string }
+// `fallback` explícito tem prioridade sobre `tier` (permite o coordinator sobrescrever a lista
+// por grupo, ex.: resposta do usuário na Fase 2 do plano). Sem nenhum dos dois, usa `tier:
+// "simple"`.
+//
+// Issue #312: não há default embutido de provider/modelo. Um default assumindo `anthropic/...`
+// direto falha com "Unexpected server error" (erro genérico do opencode real, sem pista da causa)
+// em qualquer ambiente configurado só com outro provider (ex.: OpenRouter) — não há como adivinhar
+// o provider certo sem heurística especulativa. Sem `fallback` explícito e sem `modelFallback.<tier>`
+// em `.claude/vetor/config.json`, o script falha cedo (código 1, sem stdout) com mensagem acionável
+// em vez de devolver um modelo que o `opencode run` downstream pode rejeitar.
+
+import { normalizeCwd, readJson } from "./lib/project.ts";
+import { resolveWorktree } from "./lib/status.ts";
+import { pickHealthyModel, readModelHealthFile } from "./lib/model-health.ts";
+
+interface Payload {
+  tier?: "simple" | "complex";
+  fallback?: string[];
+  cwd?: string;
+}
+
+interface VetorConfig {
+  modelFallback?: Record<string, string[]>;
+}
+
+function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `null` significa "sem lista resolvível" — nem `fallback` explícito, nem `modelFallback.<tier>`
+ *  configurado em `config.json` (issue #312: sem default embutido, ver nota acima). */
+function resolveFallbackList(root: string, input: Payload): string[] | null {
+  if (input.fallback && input.fallback.length > 0) return input.fallback;
+
+  const tier = input.tier ?? "simple";
+  const configPath = `${root}/.claude/vetor/config.json`;
+  if (exists(configPath)) {
+    try {
+      const config = readJson(configPath) as VetorConfig;
+      const configured = config.modelFallback?.[tier];
+      if (configured && configured.length > 0) return configured;
+    } catch {
+      // config.json ilegível: trata como "não configurado" — cai no erro acionável do main().
+    }
+  }
+
+  return null;
+}
+
+async function main() {
+  const raw = new TextDecoder().decode(await new Response(Deno.stdin.readable).arrayBuffer());
+
+  let input: Payload;
+  try {
+    input = raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    input = {};
+  }
+
+  const cwd = normalizeCwd(input.cwd ?? Deno.cwd());
+  const worktree = await resolveWorktree(cwd);
+  const root = worktree?.root ?? cwd;
+
+  const tier = input.tier ?? "simple";
+  const fallback = resolveFallbackList(root, input);
+  if (!fallback) {
+    const configPath = `${root}/.claude/vetor/config.json`;
+    console.error(
+      `modelFallback.${tier} não configurado em ${configPath} e nenhum "fallback" explícito foi ` +
+        `passado. Configure "modelFallback.${tier}": ["<provider>/<model>", ...] em ` +
+        `.claude/vetor/config.json com um provider/modelo válido para o ambiente atual (confira com ` +
+        `"opencode models" e "opencode auth list") antes do primeiro dispatch.`,
+    );
+    Deno.exit(2);
+  }
+
+  const health = readModelHealthFile(`${root}/.claude/vetor/status/model-health.json`);
+  const chosen = pickHealthyModel(fallback, health, Date.now());
+
+  if (!chosen) {
+    console.error(
+      `Todos os modelos da lista de fallback estão degraded: ${fallback.join(", ")}`,
+    );
+    Deno.exit(1);
+  }
+
+  console.log(chosen);
+}
+
+await main();