@tavaressan/vetor 0.1.0

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

@@ -0,0 +1,185 @@
+// Teste de ponta-a-ponta do CLI (issue #84): com uma entrada `degraded` sintética em
+// model-health.json para o modelo preferencial, confirma que a escolha cai para o próximo
+// modelo/provedor saudável da lista de fallback — e que, com todos degraded, o script sai com
+// código 1 (o issue-coordinator interpreta isso como "mantenha o grupo QUEUED").
+
+import { assertEquals, assertStringIncludes } from "@std/assert";
+
+const SCRIPT = new URL("./resolve-model.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 writeModelHealth(repo: string, content: unknown): Promise<void> {
+  const dir = `${repo}/.claude/vetor/status`;
+  await Deno.mkdir(dir, { recursive: true });
+  await Deno.writeTextFile(`${dir}/model-health.json`, JSON.stringify(content));
+}
+
+async function runCli(
+  input: unknown,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  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,
+    stdout: new TextDecoder().decode(out.stdout).trim(),
+    stderr: new TextDecoder().decode(out.stderr).trim(),
+  };
+}
+
+Deno.test("resolve-model CLI - sem model-health.json escolhe o primeiro da lista", async () => {
+  const repo = await makeRepo();
+  const result = await runCli({
+    fallback: ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"],
+    cwd: repo,
+  });
+  assertEquals(result.code, 0);
+  assertEquals(result.stdout, "anthropic/claude-haiku-4-5");
+});
+
+Deno.test("resolve-model CLI - preferencial degraded (sintético) cai para o próximo", async () => {
+  const repo = await makeRepo();
+  await writeModelHealth(repo, {
+    "anthropic/claude-haiku-4-5": {
+      status: "degraded",
+      until: Date.now() + 60_000,
+      lastError: "HTTP 429",
+    },
+  });
+
+  const result = await runCli({
+    fallback: ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"],
+    cwd: repo,
+  });
+
+  assertEquals(result.code, 0);
+  assertEquals(result.stdout, "anthropic/claude-sonnet-4-5");
+});
+
+Deno.test("resolve-model CLI - todos degraded sai com código 1 e sem stdout", async () => {
+  const repo = await makeRepo();
+  const until = Date.now() + 60_000;
+  await writeModelHealth(repo, {
+    "anthropic/claude-haiku-4-5": { status: "degraded", until, lastError: "HTTP 429" },
+    "anthropic/claude-sonnet-4-5": { status: "degraded", until, lastError: "HTTP 429" },
+  });
+
+  const result = await runCli({
+    fallback: ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"],
+    cwd: repo,
+  });
+
+  assertEquals(result.code, 1);
+  assertEquals(result.stdout, "");
+  assertStringIncludes(result.stderr, "degraded");
+});
+
+// Issue #307: no Git Bash do Windows, `$(pwd)` produz um path POSIX-style (`/c/Users/...`), não
+// nativo (`C:\Users\...`). `resolveWorktree()` roda `git` com esse cwd via `Deno.Command`, que no
+// Windows falha ao spawnar (`Failed to spawn ... No such cwd`) para paths desse formato — cai
+// silenciosamente no `DEFAULT_MODEL_FALLBACK` embutido em vez do `config.json` real.
+function toPosixPath(nativePath: string): string {
+  return nativePath.replace(/^([A-Za-z]):\\/, (_, d) => `/${d.toLowerCase()}/`).replaceAll(
+    "\\",
+    "/",
+  );
+}
+
+Deno.test({
+  name: "resolve-model CLI - resolve config.json real mesmo com cwd POSIX-style (Git Bash Windows)",
+  ignore: Deno.build.os !== "windows",
+  fn: async () => {
+    const repo = await makeRepo();
+    await Deno.mkdir(`${repo}/.claude/vetor`, { recursive: true });
+    await Deno.writeTextFile(
+      `${repo}/.claude/vetor/config.json`,
+      JSON.stringify({
+        modelFallback: { simple: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"] },
+      }),
+    );
+
+    const result = await runCli({ tier: "simple", cwd: toPosixPath(repo) });
+
+    assertEquals(result.code, 0);
+    assertEquals(result.stdout, "openai/gpt-5-mini");
+  },
+});
+
+Deno.test("resolve-model CLI - usa tier de config.json quando fallback não é passado", async () => {
+  const repo = await makeRepo();
+  await Deno.mkdir(`${repo}/.claude/vetor`, { recursive: true });
+  await Deno.writeTextFile(
+    `${repo}/.claude/vetor/config.json`,
+    JSON.stringify({
+      modelFallback: { simple: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"] },
+    }),
+  );
+
+  const result = await runCli({ tier: "simple", cwd: repo });
+
+  assertEquals(result.code, 0);
+  assertEquals(result.stdout, "openai/gpt-5-mini");
+});
+
+// Issue #312: o default embutido anterior assumia provider `anthropic` direto
+// (`anthropic/claude-haiku-4-5`), que falha com "Unexpected server error" do opencode real em
+// qualquer ambiente configurado só com outro provider (ex.: OpenRouter) — sem heurística confiável
+// para detectar o provider certo, a escolha (opção b da issue) é falhar cedo com mensagem acionável
+// em vez de devolver um modelo que pode não existir no ambiente do usuário.
+//
+// Código de saída 2, não 1: "não configurado" é um erro de configuração permanente, diferente de
+// "todos degraded" (transitório, código 1, que o coordinator interpreta como "mantenha QUEUED e
+// tente de novo"). Se "não configurado" também saísse com 1, o coordinator ficaria retentando um
+// grupo indefinidamente sem nunca mostrar a mensagem acionável — pior que o erro genérico que
+// substituiu.
+Deno.test(
+  "resolve-model CLI - sem config.json e sem fallback explícito falha cedo (código 2) com mensagem acionável",
+  async () => {
+    const repo = await makeRepo();
+
+    const result = await runCli({ tier: "simple", cwd: repo });
+
+    assertEquals(result.code, 2);
+    assertEquals(result.stdout, "");
+    assertStringIncludes(result.stderr, "modelFallback.simple");
+    assertStringIncludes(result.stderr, "config.json");
+  },
+);
+
+Deno.test(
+  "resolve-model CLI - config.json presente mas sem modelFallback para o tier falha cedo (código 2)",
+  async () => {
+    const repo = await makeRepo();
+    await Deno.mkdir(`${repo}/.claude/vetor`, { recursive: true });
+    await Deno.writeTextFile(
+      `${repo}/.claude/vetor/config.json`,
+      JSON.stringify({ runtime: "deno" }),
+    );
+
+    const result = await runCli({ tier: "complex", cwd: repo });
+
+    assertEquals(result.code, 2);
+    assertEquals(result.stdout, "");
+    assertStringIncludes(result.stderr, "modelFallback.complex");
+  },
+);

package/templates/opencode/scripts/safety-check.ts

@@ -0,0 +1,203 @@
+// Safety gate do Vetor para o Claude Code (hook PreToolUse, matcher Bash|Edit|Write).
+//
+// Substitui scripts/cc-safety-hook.sh, que dependia de `python3` no PATH — ausente no
+// Windows, onde o interpretador costuma se chamar `python`. Sob `set -euo pipefail`
+// aquele hook morria em silêncio e o gate não era aplicado.
+//
+// Contrato do Claude Code: recebe o evento em JSON no stdin; exit 2 BLOQUEIA a chamada.
+// Espelha a política de scripts/safety-check.sh, que segue servindo ao Antigravity —
+// exceto pelo guard de escrita, que o Antigravity não tem como aplicar (lá o matcher só
+// cobre run_command).
+//
+// Três políticas:
+//   Worktree    — dentro de um worktree, o cwd precisa estar em .claude/worktrees/ da raiz
+//                 e continuar registrado em `git worktree list` (não pode ser stale).
+//   Bash        — não empurrar para branch protegida; não fazer push/PR de worker não-GREEN.
+//   Edit/Write  — dentro de um worktree, não escrever fora dele; um agente vetor:issue-worker
+//                 nunca deveria escrever com cwd resolvendo para a raiz do projeto (fora de
+//                 qualquer worktree linkado) — se acontecer, é sinal de cwd mal resolvido pelo
+//                 harness, não uma escrita legítima (ver issue #57).
+//   Binding     — segunda camada, independente do guard acima: com múltiplos workers em
+//                 paralelo (ver issue #63), o cwd recebido no payload pode contaminar entre
+//                 subagentes — o cwd resolve para um worktree real, só que de OUTRO worker
+//                 ativo na mesma sessão. `isLinked` sozinho não pega esse caso. Aqui
+//                 correlacionamos `agent_id` (estável por instância de subagente, diferente
+//                 de `agent_type`) com o worktree resolvido na primeira chamada; uma mudança
+//                 de worktree para o mesmo agent_id é bloqueada.
+
+import { isWriteAllowed } from "./lib/guard.ts";
+import { run } from "./lib/project.ts";
+import {
+  agentBindingPath,
+  readStatus,
+  resolveWorktree,
+  statusFilePath,
+  type WorktreeInfo,
+} from "./lib/status.ts";
+import { evaluateFreshness } from "./lib/worktree.ts";
+
+const PROTECTED_BRANCHES = ["main", "master", "production"];
+
+interface HookInput {
+  tool_name?: string;
+  tool_input?: { command?: string; file_path?: string };
+  cwd?: string;
+  /** Presente quando o hook dispara dentro de um subagente (ex.: "vetor:issue-worker"). */
+  agent_type?: string;
+  /** Identificador único da instância do subagente — estável entre chamadas, ao contrário de agent_type. */
+  agent_id?: string;
+}
+
+function blocked(message: string): never {
+  console.error(message);
+  Deno.exit(2);
+}
+
+/** Extrai a branch de destino de um `git push [flags] [remote] <branch>[:<remote-branch>]`. */
+function pushDestination(command: string): string | null {
+  const push = command.match(/git push[^&|;]*/)?.[0];
+  if (!push) return null;
+
+  const last = push.trim().split(/\s+/).pop();
+  if (!last || last.startsWith("-")) return null;
+  return last.split(":")[0];
+}
+
+/**
+ * Só se aplica dentro de um worktree linkado (`wt.isLinked`): a raiz do repositório
+ * principal não tem essa restrição, senão o próprio uso legítimo do hook lá quebraria.
+ */
+async function checkFreshness(wt: WorktreeInfo): Promise<void> {
+  const list = await run("git", ["worktree", "list", "--porcelain"], wt.root);
+  const message = evaluateFreshness(wt.toplevel, wt.root, list.stdout);
+  if (message) blocked(message);
+}
+
+function checkBash(command: string, wt: WorktreeInfo | null): void {
+  const dest = pushDestination(command);
+  if (dest && PROTECTED_BRANCHES.includes(dest)) {
+    blocked(
+      "ERROR: Push to protected branches (main, master, production) is prohibited by Vetor Safety Hook.",
+    );
+  }
+
+  if (!/git push|gh pr (create|ready|merge)/.test(command)) return;
+  if (!wt?.isLinked) return;
+
+  const status = readStatus(statusFilePath(wt.root, wt.branch));
+  // Sem status file, a branch não pertence ao fluxo do coordinator: não interfere.
+  if (status === null) return;
+
+  if (status !== "GREEN") {
+    blocked(
+      `ERROR: worker não-GREEN (Status: ${
+        status || "desconhecido"
+      }) — push/PR bloqueado pelo Vetor Safety Hook.\n` +
+        "Registre BLOCKED_WAITING no status file se precisar de intervenção; o worktree-ship faz a entrega após GREEN.",
+    );
+  }
+}
+
+/**
+ * Segunda camada de defesa contra cwd contaminado (issue #63): sem `agent_id` não há como
+ * correlacionar, então não se aplica — não é regressão, é a mesma cobertura de antes.
+ * Na primeira chamada de um `agent_id`, grava o worktree resolvido; em chamadas seguintes,
+ * uma mudança de worktree para o MESMO agent_id indica cwd contaminado — bloqueia.
+ */
+function checkAgentBinding(root: string, agentId: string | undefined, toplevel: string): void {
+  if (!agentId) return;
+
+  const path = agentBindingPath(root, agentId);
+  let bound: string | null = null;
+  try {
+    bound = Deno.readTextFileSync(path).trim();
+  } catch {
+    // Primeira chamada deste agent_id: nada gravado ainda.
+  }
+
+  if (bound && bound !== toplevel) {
+    blocked(
+      `ERROR: cwd contaminado detectado pelo Vetor Safety Hook (issue #63): agent_id ${agentId} ` +
+        `já estava vinculado ao worktree ${bound}, mas este evento resolveu para ${toplevel}.\n` +
+        "Isso indica cwd entregue incorretamente pelo harness durante execução paralela de " +
+        "subagentes — a escrita foi bloqueada para não vazar entre workers.",
+    );
+  }
+
+  if (!bound) {
+    try {
+      Deno.mkdirSync(`${root}/.claude/vetor/status/.agent-cwd`, { recursive: true });
+      Deno.writeTextFileSync(path, `${toplevel}\n`);
+    } catch {
+      // Sem conseguir gravar o vínculo, a checagem principal (isWriteAllowed) já cobre
+      // a política de escrita — a ausência do vínculo só reduz a segunda camada.
+    }
+  }
+}
+
+async function checkWrite(
+  filePath: string,
+  cwd: string,
+  agentType?: string,
+  agentId?: string,
+): Promise<void> {
+  const wt = await resolveWorktree(cwd);
+
+  if (!wt?.isLinked) {
+    // Um vetor:issue-worker deveria estar sempre dentro do seu worktree isolado. cwd
+    // resolvendo para fora de um worktree linkado (ex.: a raiz do projeto) indica cwd
+    // incorreto entregue pelo harness — deixar passar contamina a raiz compartilhada por
+    // todos os workers em paralelo (reprodução real: issue #57).
+    if (agentType === "vetor:issue-worker") {
+      blocked(
+        `ERROR: vetor:issue-worker escrevendo com cwd fora de um worktree linkado: ${filePath}\n` +
+          `cwd resolvido: ${cwd}${wt ? ` (branch: ${wt.branch})` : ""}. Um issue-worker só ` +
+          "deveria escrever dentro do seu próprio worktree — bloqueado pelo Vetor Safety Hook.",
+      );
+    }
+    return;
+  }
+
+  checkAgentBinding(wt.root, agentId, wt.toplevel);
+
+  if (!isWriteAllowed(filePath, wt.toplevel, wt.root)) {
+    blocked(
+      `ERROR: escrita fora do worktree bloqueada pelo Vetor Safety Hook: ${filePath}\n` +
+        `O worker só escreve dentro de ${wt.toplevel} (e no seu status file). Editar a raiz ` +
+        "contamina os demais workers em paralelo.",
+    );
+  }
+}
+
+async function main() {
+  const raw = new TextDecoder().decode(await new Response(Deno.stdin.readable).arrayBuffer());
+
+  let input: HookInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    // Entrada ilegível não deve travar a sessão do usuário.
+    Deno.exit(0);
+  }
+
+  const cwd = input.cwd ?? Deno.cwd();
+  const wt = await resolveWorktree(cwd);
+
+  // A checagem de frescor só faz sentido dentro de um worktree linkado — na raiz do
+  // repositório principal (isLinked === false) o hook segue liberando normalmente.
+  if (wt?.isLinked) {
+    await checkFreshness(wt);
+  }
+
+  if (input.tool_name === "Edit" || input.tool_name === "Write") {
+    const filePath = input.tool_input?.file_path;
+    if (filePath) await checkWrite(filePath, cwd, input.agent_type, input.agent_id);
+    Deno.exit(0);
+  }
+
+  const command = input.tool_input?.command;
+  if (command) checkBash(command, wt);
+  Deno.exit(0);
+}
+
+await main();

package/templates/opencode/scripts/vetor-checks.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# Checagens determinísticas compartilhadas pelas skills do Vetor.
+#
+# Uso: vetor-checks.sh <subcomando> [args]
+#   default-branch             imprime a branch default do repositório (nunca assume master)
+#   in-worktree                exit 0 se o cwd é um worktree linkado; exit 1 se é o root
+#   migrations                 exit 1 se há versões de migration duplicadas (convenção Flyway)
+#   debug-scan <base-branch>   exit 1 se o diff vs. a base contém padrões de debug/teste exclusivo
+#   validate-issue-ref <valor> exit 1 se valor não for inteiro positivo; exit 0 caso contrário
+#   safe-remove-worktree <path> remove o worktree somente se não houver worktree filho ativo
+#   sync-root                  tenta retornar o repositório principal para a branch default de forma segura
+#   worktree-audit              lista worktrees linkados (exceto o root) com idade/tamanho/uncommitted
+#   find-orphan-status [dir]   lista status files sem worktree correspondente (default: .claude/vetor/status)
+#   archive-orphan-status <path> move um status file órfão para <dir>/archive/
+#
+# Exit codes: 0 = passou; 1 = checagem falhou (a skill deve parar e mostrar a saída); 2 = uso incorreto.
+
+set -uo pipefail
+
+cmd="${1:-}"
+
+case "$cmd" in
+  default-branch)
+    DEFAULT_BRANCH=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | sed -n '/HEAD branch/s/.*: //p')
+    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=master
+    echo "$DEFAULT_BRANCH"
+    ;;
+
+  in-worktree)
+    # Contrato estável para uso EXTERNO ao plugin (issue #129): hooks/scripts de projetos
+    # consumidores podem chamar `vetor-checks.sh in-worktree` diretamente para decidir se o
+    # cwd é um worktree linkado (exit 0) ou o repositório principal (exit 1), sem stdout.
+    # Não reimplemente essa comparação com `pwd` vs `git worktree list` — os formatos de path
+    # nunca coincidem no Windows/Git Bash, o que faz a comparação ingênua concluir "worktree"
+    # mesmo estando no root.
+    git_dir=$(git rev-parse --git-dir 2>/dev/null) || { echo "não é um repositório git" >&2; exit 1; }
+    common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+    if [ "$(cd "$git_dir" && pwd)" = "$(cd "$common_dir" && pwd)" ]; then
+      echo "cwd é o root do repositório, não um worktree linkado" >&2
+      exit 1
+    fi
+    ;;
+
+  migrations)
+    # Colisão semântica invisível ao git: dois arquivos com a mesma versão (V13__a.sql, V13__b.sql).
+    dups=$(git ls-files '*/db/migration/V*__*.sql' \
+      | sed -E 's#.*/V([0-9]+)__.*#\1#' | sort | uniq -d)
+    if [ -n "$dups" ]; then
+      echo "FALHA: colisão de versão de migration — versões duplicadas:" >&2
+      for v in $dups; do
+        echo "  V$v:" >&2
+        git ls-files "*/db/migration/V${v}__*.sql" | sed 's/^/    /' >&2
+      done
+      echo "Renumere a migration deste worker para a próxima versão livre antes de prosseguir." >&2
+      exit 1
+    fi
+    ;;
+
+  debug-scan)
+    base="${2:?uso: vetor-checks.sh debug-scan <base-branch>}"
+    # Grep only added lines from diff (lines starting with +), not the entire file content.
+    # The caller MUST pass origin/$DEFAULT_BRANCH (not local $DEFAULT_BRANCH) to avoid
+    # Stale branch references in worktrees (issue #70).
+    # Exclude script/test files that define or test the regex to avoid false positives (issue #108, #109)
+    hits=$(git diff "$base" -U0 -- '*.ts' '*.sh' '*.js' '*.tsx' '*.jsx' \
+      ':!scripts/vetor-checks.sh' ':!scripts/tests/vetor-checks_test.ts' ':!skills/**/*.md' \
+      ':!.opencode/scripts/vetor-checks.sh' ':!.opencode/skills/**/*.md' \
+      ':!opencode/scripts/vetor-checks.sh' ':!opencode/skills/**/*.md' 2>/dev/null \
+      | grep -E '^\+' | grep -vE '^\+\+\+' \
+      | grep -nE 'console\.log|var_dump|fit\(|fdescribe\(|it\.only' 2>/dev/null || true)
+    if [ -n "$hits" ]; then
+      echo "FALHA: padrões de debug/teste exclusivo no diff (remova antes do push):" >&2
+      echo "$hits" >&2
+      exit 1
+    fi
+    ;;
+
+  validate-issue-ref)
+    valor="${2:?uso: vetor-checks.sh validate-issue-ref <valor>}"
+    if ! [[ "$valor" =~ ^[1-9][0-9]*$ ]]; then
+      echo "ERRO: issue# deve ser um inteiro positivo, recebido \"$valor\"" >&2
+      exit 1
+    fi
+    ;;
+
+  safe-remove-worktree)
+    target="${2:?uso: vetor-checks.sh safe-remove-worktree <path>}"
+    target=$(cd "$target" && pwd -P) || {
+      echo "ERRO: worktree para cleanup não encontrado: $target" >&2
+      exit 1
+    }
+
+    children=()
+    while IFS= read -r line; do
+      case "$line" in
+        "worktree "*)
+          candidate="${line#worktree }"
+          candidate=$(cd "$candidate" 2>/dev/null && pwd -P) || continue
+          case "$candidate" in
+            "$target"/*) children+=("$candidate") ;;
+          esac
+          ;;
+      esac
+    done < <(git worktree list --porcelain)
+
+    if [ "${#children[@]}" -gt 0 ]; then
+      echo "FALHA: cleanup bloqueado; o worktree $target contém worktree(s) ativo(s):" >&2
+      printf '  %s\n' "${children[@]}" >&2
+      echo "Remova ou realoque os worktrees filhos antes de remover o pai." >&2
+      exit 1
+    fi
+
+    git worktree remove "$target"
+    ;;
+
+  sync-root)
+    # Tenta retornar a raiz do repo para a branch default se a branch atual estiver limpa
+    # e sem commits locais pendentes vs remote (ou sem remote tracker caso já deletada).
+    ROOT=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | xargs dirname)
+    [ -z "$ROOT" ] && exit 0
+    cd "$ROOT" || exit 0
+    
+    DEFAULT_BRANCH=$("$0" default-branch)
+    current=$(git branch --show-current 2>/dev/null)
+    [ -z "$current" ] || [ "$current" = "$DEFAULT_BRANCH" ] && exit 0
+    
+    # 1. Verifica se tem uncommitted changes
+    if ! git diff-index --quiet HEAD --; then
+      echo "AVISO: root tem mudanças pendentes na branch $current. Não mudando para $DEFAULT_BRANCH." >&2
+      exit 0
+    fi
+    
+    # 2. Verifica se a branch tem commits que não estão na default
+    if ! git merge-base --is-ancestor HEAD "origin/$DEFAULT_BRANCH" 2>/dev/null; then
+      echo "AVISO: root está na branch $current que possui commits não integrados em origin/$DEFAULT_BRANCH. Não mudando para $DEFAULT_BRANCH." >&2
+      exit 0
+    fi
+    
+    git checkout "$DEFAULT_BRANCH" >/dev/null 2>&1
+    git pull origin "$DEFAULT_BRANCH" >/dev/null 2>&1
+    echo "Root sincronizado com $DEFAULT_BRANCH (branch anterior: $current estava limpa e mesclada)."
+    ;;
+
+  worktree-audit)
+    # Emite uma linha por worktree linkado (exclui o root) no formato:
+    #   <path>|<branch>|<age_days>|<size_kb>|<uncommitted:yes/no>
+    # "age_days" é medido a partir do timestamp do último commit do worktree (proxy de
+    # staleness — evita depender de mtime de diretório, que muda a qualquer escrita).
+    main_worktree=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | xargs dirname)
+    now_ts=$(date +%s)
+    path=""
+    branch=""
+    while IFS= read -r line; do
+      case "$line" in
+        "worktree "*)
+          path="${line#worktree }"
+          branch=""
+          ;;
+        "branch refs/heads/"*)
+          branch="${line#branch refs/heads/}"
+          ;;
+        "")
+          if [ -n "$path" ] && [ "$path" != "$main_worktree" ] && [ -d "$path" ]; then
+            last_commit_ts=$(git -C "$path" log -1 --format=%ct 2>/dev/null || echo "$now_ts")
+            age_days=$(( (now_ts - last_commit_ts) / 86400 ))
+            size_kb=$(du -sk "$path" 2>/dev/null | cut -f1)
+            if [ -n "$(git -C "$path" status --porcelain 2>/dev/null)" ]; then
+              uncommitted="yes"
+            else
+              uncommitted="no"
+            fi
+            echo "${path}|${branch:-detached}|${age_days}|${size_kb:-0}|${uncommitted}"
+          fi
+          path=""
+          branch=""
+          ;;
+      esac
+    done < <(git worktree list --porcelain; echo "")
+    ;;
+
+  find-orphan-status)
+    # Lista status files (`.claude/vetor/status/*.md`) cujo worktree correspondente não
+    # existe mais em `git worktree list`. Report-only — não move nem apaga nada.
+    status_dir="${2:-.claude/vetor/status}"
+    [ -d "$status_dir" ] || exit 0
+    active=$(git worktree list --porcelain | sed -n 's#^branch refs/heads/##p' | tr '/' '-')
+    for f in "$status_dir"/*.md; do
+      [ -e "$f" ] || continue
+      name=$(basename "$f" .md)
+      if ! printf '%s\n' "$active" | grep -qx "$name"; then
+        echo "$f"
+      fi
+    done
+    ;;
+
+  archive-orphan-status)
+    # Move um status file órfão para <dir>/archive/ (não apaga — recolhimento reversível).
+    target="${2:?uso: vetor-checks.sh archive-orphan-status <path-do-status-file>}"
+    [ -f "$target" ] || {
+      echo "ERRO: status file não encontrado: $target" >&2
+      exit 1
+    }
+    status_dir=$(dirname "$target")
+    archive_dir="$status_dir/archive"
+    mkdir -p "$archive_dir"
+    mv "$target" "$archive_dir/"
+    echo "Arquivado: $archive_dir/$(basename "$target")"
+    ;;
+
+  *)
+    echo "uso: vetor-checks.sh <default-branch|in-worktree|migrations|debug-scan <base-branch>|validate-issue-ref <valor>|safe-remove-worktree <path>|sync-root|worktree-audit|find-orphan-status [dir]|archive-orphan-status <path>>" >&2
+    exit 2
+    ;;
+esac
+
+exit 0