@orkastery/cli 0.2.0

package/dist/retry.js

@@ -0,0 +1,917 @@
+"use strict";
+/**
+ * Politica de retry TIPADA e retomada automatica (bloco B3).
+ *
+ * O B1 deu ao `ork` o MOTIVO tipado de cada reprovacao; o B2 deu a thread um estado
+ * retomavel em disco. O B3 e a camada que liga os dois: para cada motivo tipado existe
+ * UMA acao de retry deterministica, igual em todos os modos de conducao.
+ *
+ * Tres regras mandam aqui, e nenhuma delas e afrouxavel por modo:
+ *
+ *   1. **Custo nunca reexecuta.** `cost.violation` (despacho que seria redirecionado
+ *      para provider pago) e o unico motivo sem retry automatico nenhum. Reexecutar
+ *      violacao de custo e gastar de novo, e a licao dos US$ 16 esta no manifesto.
+ *   2. **O modo afrouxa a PAUSA, nunca a VERIFICACAO.** A politica e identica em
+ *      `#Look` e em `#Auto`. O que muda e a AUTORIZACAO: num bloco de loop que pausa,
+ *      a acao espera `ork gate approve`; num bloco sem pausa (`#Maestro`, `#Auto`) o
+ *      `ork` executa sozinho e grava a decisao autonoma no ledger.
+ *   3. **O limite de escalacao pausa QUALQUER modo.** Estouradas as tentativas do
+ *      manifesto pelo MESMO motivo na MESMA fase, a acao vira `escalar-humano`,
+ *      inclusive em `#Auto`. E a invariante de escalacao tipada da secao 3.5.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLITICA_DE_RETRY = exports.ESCADA_DE_ESFORCO = void 0;
+exports.proximoEsforco = proximoEsforco;
+exports.politicaDoMotivo = politicaDoMotivo;
+exports.podeReexecutar = podeReexecutar;
+exports.tabelaDaPolitica = tabelaDaPolitica;
+exports.ultimaReprovacao = ultimaReprovacao;
+exports.tentativasFeitas = tentativasFeitas;
+exports.blocoPausa = blocoPausa;
+exports.planejarRetry = planejarRetry;
+exports.escalarEsforco = escalarEsforco;
+exports.redespachar = redespachar;
+exports.playbookDaRetomada = playbookDaRetomada;
+exports.retomarPedido = retomarPedido;
+exports.retomarFila = retomarFila;
+exports.retomarPorId = retomarPorId;
+exports.cancelarPedido = cancelarPedido;
+exports.executarRetry = executarRetry;
+exports.textoDoPlano = textoDoPlano;
+exports.textoDoRetry = textoDoRetry;
+exports.textoDaRetomada = textoDaRetomada;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const adapter = __importStar(require("./adapters/claude-bg"));
+const fix_1 = require("./fix");
+const gates_1 = require("./gates");
+const ledger_1 = require("./ledger");
+const phase_1 = require("./phase");
+const slug_1 = require("./slug");
+const policies_1 = require("./policies");
+const ratelimit_1 = require("./ratelimit");
+const thread_1 = require("./thread");
+const tokens_1 = require("./tokens");
+const util_1 = require("./util");
+const worktree_1 = require("./worktree");
+/**
+ * Escada de esforco da 2a tentativa em diante.
+ *
+ * Subir esforco e de graca na assinatura; trocar de provider nao e. Por isso a escada
+ * so anda dentro do runtime que ja esta configurado, e nunca vira "tenta no pago".
+ */
+exports.ESCADA_DE_ESFORCO = ['eco', 'low', 'medium', 'high', 'xhigh'];
+/** O proximo degrau de esforco, ou o mesmo quando ja esta no topo (sem inventar degrau). */
+function proximoEsforco(atual) {
+    const i = exports.ESCADA_DE_ESFORCO.indexOf(atual.trim().toLowerCase());
+    if (i < 0)
+        return atual;
+    return exports.ESCADA_DE_ESFORCO[Math.min(i + 1, exports.ESCADA_DE_ESFORCO.length - 1)];
+}
+/**
+ * A politica de retry, motivo tipado a motivo tipado.
+ *
+ * O mapa e TOTAL sobre `MotivoGate` de proposito: motivo novo no catalogo do gate nao
+ * compila sem decidir aqui o que se faz com ele. Silencio nao e politica.
+ */
+exports.POLITICA_DE_RETRY = {
+    'artifact.missing': {
+        motivo: 'artifact.missing',
+        acao: 'corrigir-dirigido',
+        automatica: true,
+        porque: 'o artefato exigido pela fase nao existe: a fase precisa de spec dirigida do que gravar, nao de repeticao cega do mesmo prompt',
+        correcao: 'ork fix open <thread> abre a rodada com a spec exata',
+    },
+    'claims.failed': {
+        motivo: 'claims.failed',
+        acao: 'corrigir-dirigido',
+        automatica: true,
+        porque: 'a alegacao reprovou na reexecucao no HEAD real: reexecutar a fase igual reproduz a mesma mentira; o que resolve e GO-FIX com a claim e o comando exatos',
+        correcao: 'ork fix open <thread> e depois ork fix reverify <thread>',
+    },
+    'claims.unverifiable': {
+        motivo: 'claims.unverifiable',
+        acao: 'corrigir-dirigido',
+        automatica: true,
+        porque: 'alegacao sem comando de verificacao vira correcao tipo A: anexar o comando (ou retirar a alegacao com motivo) e uma linha, nao um GO inteiro',
+        correcao: 'ork claims verificar <thread> <claim> --comando "<comando>"',
+    },
+    'policy.violation': {
+        motivo: 'policy.violation',
+        acao: 'escalar-humano',
+        automatica: false,
+        porque: 'policy com severidade block reprova em qualquer modo: reexecutar sozinho seria a maquina revogando a policy do manifesto',
+        correcao: 'corrija a violacao no pedido/manifesto; policy block nao se resolve por repeticao',
+    },
+    'cost.violation': {
+        motivo: 'cost.violation',
+        acao: 'sem-retry',
+        automatica: false,
+        porque: 'violacao de CUSTO nunca recebe retry automatico: cada reexecucao gastaria de novo pelo provider pago (a licao dos US$ 16 e regra de codigo, nao lembrete)',
+        correcao: 'tire do ambiente a variavel que redireciona o despacho e rode a fase de novo a mao, com o gasto sob os olhos de um humano',
+    },
+    'verify.regression': {
+        motivo: 'verify.regression',
+        acao: 'corrigir-dirigido',
+        automatica: true,
+        porque: 'o comando passava na baseline e falha agora: o defeito e desta thread e tem alvo conhecido, entao ele vira spec de GO-FIX tipo B',
+        correcao: 'ork fix open <thread> (a reexecucao seguinte e completa)',
+    },
+    'verify.failed': {
+        motivo: 'verify.failed',
+        acao: 'corrigir-dirigido',
+        automatica: true,
+        porque: 'o comando falha sem baseline para separar regressao de divida: a correcao dirigida conserta ou grava a baseline, mas nao chuta de quem e a culpa',
+        correcao: 'ork fix open <thread>, ou ork verify <thread> --baseline antes do proximo GO',
+    },
+    'runtime.unavailable': {
+        motivo: 'runtime.unavailable',
+        acao: 'reexecutar',
+        automatica: true,
+        porque: 'falha de infraestrutura no despacho nao e falha de conteudo: o MESMO prompt, com o mesmo sha256, e redespachado sem alterar uma virgula',
+        correcao: 'ork retry run <thread> redespacha o prompt ja gravado em disco',
+    },
+    'runtime.rate-limited': {
+        motivo: 'runtime.rate-limited',
+        acao: 'esperar-janela',
+        automatica: true,
+        porque: 'o limite de uso tem HORA de volta: a fase entra na fila duravel e e retomada na janela seguinte, sem humano no meio e sem gastar por fora da assinatura',
+        correcao: 'ork retry list mostra a fila; ork retry resume retoma o que ja liberou',
+    },
+    'tree.blocked': {
+        motivo: 'tree.blocked',
+        acao: 'sincronizar-worktree',
+        automatica: true,
+        porque: 'a arvore de destino andou por baixo da thread: rebasar a worktree contra a base e o passo que desbloqueia, e reexecutar antes disso so repete o conflito',
+        correcao: 'ork worktree sync <thread> e so entao repetir o passo',
+    },
+    'lease.busy': {
+        motivo: 'lease.busy',
+        acao: 'reexecutar',
+        automatica: true,
+        porque: 'o lease e de outra thread e vai ser liberado: a fila ja serializa, entao a acao e tentar de novo quando chegar a vez, nunca furar a fila',
+        correcao: 'ork lease list mostra a fila; a vez chega sem ninguem forcar',
+    },
+    'human.pending': {
+        motivo: 'human.pending',
+        acao: 'escalar-humano',
+        automatica: false,
+        porque: 'nao e reprovacao de verdade, e espera de autorizacao: automatizar a espera seria a maquina se autorizando',
+        correcao: 'ork gate approve <thread> <sobre> --por <quem>',
+    },
+};
+/** A politica de um motivo tipado. */
+function politicaDoMotivo(motivo) {
+    return exports.POLITICA_DE_RETRY[motivo];
+}
+/** O motivo pode ser reexecutado automaticamente pelo `ork`? Custo nunca pode. */
+function podeReexecutar(motivo) {
+    return exports.POLITICA_DE_RETRY[motivo].acao !== 'sem-retry';
+}
+/** Tabela de `ork retry policy`. */
+function tabelaDaPolitica() {
+    const linhas = Object.values(exports.POLITICA_DE_RETRY).map((p) => [
+        p.motivo,
+        p.acao,
+        p.automatica ? 'sim' : 'nao',
+        p.porque,
+    ]);
+    return (0, util_1.tabela)(['MOTIVO TIPADO', 'ACAO DE RETRY', 'AUTOMATICA', 'POR QUE'], linhas);
+}
+/** A fase a que um evento de gate reprovado se refere. */
+function faseDoEvento(evento, thread) {
+    const declarada = typeof evento.fase === 'string' ? evento.fase : null;
+    if (declarada && thread.fases.includes(declarada))
+        return declarada;
+    if (evento.gate === 'verify')
+        return 'CHECK';
+    if (evento.gate === 'ship')
+        return 'SHIP';
+    return thread.faseAtual;
+}
+/** O ultimo gate reprovado da thread, ou null quando nao ha reprovacao pendente. */
+function ultimaReprovacao(raiz, threadId) {
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId));
+    for (let i = eventos.length - 1; i >= 0; i--) {
+        const e = eventos[i];
+        if (e.tipo === ledger_1.TIPOS_DE_EVENTO.gateBloqueado && typeof e.motivo === 'string')
+            return e;
+    }
+    return null;
+}
+/**
+ * Tentativas automaticas ja feitas pelo MESMO motivo na MESMA fase.
+ *
+ * Conta o que o `ork` REALMENTE executou (`retry_attempt` no ledger), nao o que ele
+ * planejou: planejar nao gasta janela nem toca no repositorio.
+ */
+function tentativasFeitas(raiz, threadId, fase, motivo) {
+    return (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId)).filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.retryTentado && e.fase === fase && e.motivo === motivo).length;
+}
+/** O bloco de loop desta fase pausa para o humano neste modo? */
+function blocoPausa(thread, fase) {
+    return (0, thread_1.blocoDaThread)(thread, fase).pausa;
+}
+/**
+ * Calcula o plano de retry SEM executar nada.
+ *
+ * Separado da execucao de proposito: `ork retry plan` precisa poder responder "o que
+ * voce faria agora e por que" sem gastar uma tentativa nem tocar no repositorio.
+ */
+function planejarRetry(carregado, threadId, opcoes = {}) {
+    const { raiz, manifesto } = carregado;
+    const thread = (0, thread_1.lerThread)(raiz, threadId);
+    const limite = manifesto.retry.max_tentativas;
+    const effortBase = manifesto.runtime.effort;
+    const evento = opcoes.motivo ? null : ultimaReprovacao(raiz, threadId);
+    const motivo = opcoes.motivo ?? (evento && evento.motivo);
+    if (!motivo) {
+        return {
+            thread: threadId,
+            modo: thread.modo,
+            fase: opcoes.fase ?? thread.faseAtual,
+            motivo: null,
+            detalhe: 'nenhum gate reprovado no ledger desta thread',
+            politica: null,
+            acao: 'sem-retry',
+            tentativas: 0,
+            limite,
+            effort: effortBase,
+            effortAnterior: effortBase,
+            automatica: false,
+            bloqueio: 'gate.sem-reprovacao',
+            razao: 'nao ha o que repetir: o ledger da thread nao tem reprovacao tipada pendente',
+        };
+    }
+    const fase = opcoes.fase ?? (evento ? faseDoEvento(evento, thread) : thread.faseAtual);
+    const politica = politicaDoMotivo(motivo);
+    const tentativas = tentativasFeitas(raiz, threadId, fase, motivo);
+    const detalhe = evento && typeof evento.detalhe === 'string' ? evento.detalhe : '';
+    // Custo primeiro: nenhuma tentativa, nenhum degrau de esforco, nenhum modo. Nunca.
+    if (politica.acao === 'sem-retry') {
+        return {
+            thread: threadId,
+            modo: thread.modo,
+            fase,
+            motivo,
+            detalhe,
+            politica,
+            acao: 'sem-retry',
+            tentativas,
+            limite,
+            effort: effortBase,
+            effortAnterior: effortBase,
+            automatica: false,
+            bloqueio: 'politica.nao-automatica',
+            razao: politica.porque,
+        };
+    }
+    // Limite de escalacao: pausa QUALQUER modo, inclusive #Auto.
+    if (tentativas >= limite) {
+        return {
+            thread: threadId,
+            modo: thread.modo,
+            fase,
+            motivo,
+            detalhe,
+            politica,
+            acao: 'escalar-humano',
+            tentativas,
+            limite,
+            effort: effortBase,
+            effortAnterior: effortBase,
+            automatica: false,
+            bloqueio: 'escalacao.limite',
+            razao: `${tentativas} tentativa(s) automatica(s) por ${motivo} em ${fase}, no limite de ${limite} ` +
+                'do manifesto: escalacao tipada pausa qualquer modo, inclusive #Auto',
+        };
+    }
+    // Da 2a tentativa em diante o esforco sobe um degrau, quando o manifesto permite.
+    // `tentativas` e quantas JA rodaram, entao a 1a tentativa (tentativas 0) sai no
+    // esforco base do manifesto e so a partir da 2a a escada anda.
+    const escala = manifesto.retry.escalar_esforco && tentativas >= 1;
+    const effortAnterior = escalarEsforco(effortBase, Math.max(0, tentativas - 1));
+    const effort = escala ? escalarEsforco(effortBase, tentativas) : effortBase;
+    const acao = escala ? 'escalar-esforco' : politica.acao;
+    const pausa = blocoPausa(thread, fase);
+    const autorizado = (opcoes.autorizadoPor ?? '').trim() !== '';
+    let bloqueio = null;
+    let automatica = politica.automatica;
+    let razao = politica.porque;
+    if (!politica.automatica) {
+        automatica = false;
+        bloqueio = 'politica.nao-automatica';
+    }
+    else if (pausa && !autorizado) {
+        // O bloco de loop deste modo pausa: o humano ja e parte do caminho aqui, e por isso
+        // a acao fica planejada e nao executada. `#Maestro` e `#Auto` nao caem neste ramo.
+        automatica = false;
+        bloqueio = 'modo.bloco-pausa';
+        razao =
+            `o bloco ${(0, thread_1.blocoDaThread)(thread, fase).fases.join('-')} pausa neste modo ` +
+                `(${(0, thread_1.blocoDaThread)(thread, fase).pausaSobre}): a acao ${acao} espera autorizacao humana. ` +
+                'O modo afrouxa a pausa, nunca a verificacao.';
+    }
+    return {
+        thread: threadId,
+        modo: thread.modo,
+        fase,
+        motivo,
+        detalhe,
+        politica,
+        acao,
+        tentativas,
+        limite,
+        effort,
+        effortAnterior,
+        automatica,
+        bloqueio,
+        razao,
+    };
+}
+/** O esforco depois de `n` escaladas a partir do esforco base do manifesto. */
+function escalarEsforco(base, degraus) {
+    let atual = base;
+    for (let i = 0; i < degraus; i++)
+        atual = proximoEsforco(atual);
+    return atual;
+}
+/**
+ * Redespacha um prompt JA GRAVADO, byte a byte.
+ *
+ * As duas guardas que fazem disto uma retomada, e nao um despacho novo:
+ *   - o arquivo precisa existir e o sha256 precisa bater com o registrado. Prompt
+ *     alterado entre a morte e a retomada e outro pedido, e por isso recusa;
+ *   - as MESMAS policies do `phase.dispatch` sao reavaliadas contra o texto lido. E
+ *     assim que a regra de custo alcanca a retomada: se o ambiente ganhou uma variavel
+ *     de provider pago enquanto a fase esperava, a retomada recusa em vez de gastar.
+ */
+function redespachar(carregado, thread, fase, promptRelativo, sha, opcoes = {}) {
+    const { raiz, manifesto } = carregado;
+    const absoluto = path.isAbsolute(promptRelativo)
+        ? promptRelativo
+        : path.join(raiz, promptRelativo);
+    const slug = opcoes.slug ?? (0, phase_1.slugDaSessao)(thread, fase);
+    const vazio = { slug, sessionId: null, verificada: false, sinal: null, comando: [] };
+    if (!fs.existsSync(absoluto)) {
+        return {
+            ...vazio,
+            ok: false,
+            motivo: 'artifact.missing',
+            detalhe: `o prompt gravado sumiu do disco: ${promptRelativo}`,
+            dryRun: opcoes.dryRun === true,
+        };
+    }
+    const prompt = fs.readFileSync(absoluto, 'utf8');
+    const shaAtual = (0, phase_1.hashDoPrompt)(prompt);
+    if (shaAtual !== sha) {
+        return {
+            ...vazio,
+            ok: false,
+            motivo: 'artifact.missing',
+            detalhe: `o prompt em ${promptRelativo} mudou desde o despacho original ` +
+                `(sha256 ${shaAtual.slice(0, 12)} != ${sha.slice(0, 12)}): retomada e redespachar o MESMO texto`,
+            dryRun: opcoes.dryRun === true,
+        };
+    }
+    const violacoes = (0, policies_1.bloqueantes)((0, policies_1.avaliarPolicies)(manifesto, { gate: 'phase.dispatch', prompt }));
+    if (violacoes.length > 0) {
+        const motivo = (0, policies_1.motivoDominante)(violacoes);
+        const detalhe = violacoes.map((v) => `${v.policy}: ${v.detalhe}`).join('; ');
+        (0, gates_1.registrarGateBloqueado)((0, thread_1.dirThread)(raiz, thread.id), thread.id, {
+            gate: 'phase.dispatch',
+            motivo,
+            modo: thread.modo,
+            detalhe,
+            correcao: violacoes.map((v) => v.correcao).join('; '),
+            fase,
+            slug,
+            origem: opcoes.origem ?? 'retry',
+            evidencia: `prompt sha256 ${sha} (retomada recusada antes de despachar)`,
+        });
+        return { ...vazio, ok: false, motivo, detalhe, dryRun: opcoes.dryRun === true };
+    }
+    const cwd = opcoes.cwd ?? thread.worktree ?? raiz;
+    // Mesma resolucao do `ork phase run`: a retomada carimba no ledger o par que ela de
+    // fato despachou, inclusive quando o pedido da fila trazia um modelo proprio.
+    const { model, effort } = (0, phase_1.resolverDespacho)(manifesto, {
+        model: opcoes.model ?? undefined,
+        effort: opcoes.effort ?? undefined,
+    });
+    const resultado = adapter.despachar({
+        prompt,
+        nome: slug,
+        cwd,
+        model,
+        effort,
+        dryRun: opcoes.dryRun,
+    });
+    if (opcoes.dryRun) {
+        return {
+            ok: true,
+            slug,
+            sessionId: null,
+            verificada: false,
+            motivo: null,
+            detalhe: 'ensaio (--dry-run): comando montado, nada despachado',
+            sinal: null,
+            comando: resultado.comando,
+            dryRun: true,
+        };
+    }
+    if (!resultado.ok || !resultado.sessionId) {
+        const sinal = resultado.rateLimit ?? null;
+        return {
+            ok: false,
+            slug,
+            sessionId: null,
+            verificada: false,
+            motivo: sinal ? 'runtime.rate-limited' : 'runtime.unavailable',
+            detalhe: resultado.erro ?? 'sem sessionId na saida do runtime',
+            sinal,
+            comando: resultado.comando,
+            dryRun: false,
+        };
+    }
+    const ctx = {
+        raiz,
+        thread,
+        fase,
+        slug,
+        promptPath: absoluto,
+        promptSha256: sha,
+        runtime: manifesto.runtime.adapter,
+        cwd,
+        model,
+        effort,
+        origem: opcoes.origem ?? 'retry',
+    };
+    (0, phase_1.concluirDespacho)(ctx, resultado.sessionId, resultado.verificada, resultado.comando);
+    return {
+        ok: true,
+        slug,
+        sessionId: resultado.sessionId,
+        verificada: resultado.verificada,
+        motivo: null,
+        detalhe: `sessao ${resultado.sessionId} despachada com o mesmo prompt sha256 ${sha.slice(0, 12)}`,
+        sinal: null,
+        comando: resultado.comando,
+        dryRun: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Os 3 playbooks de recuperacao, em codigo.
+// ---------------------------------------------------------------------------
+/**
+ * Escolhe o playbook da retomada.
+ *
+ * Nao ha regra nova de rotacao aqui: quem decide entre a MESMA sessao e uma NOVA e o
+ * gate de tokens do B1 (visao, secao 3.6), com `refazer: true`, porque retomar uma fase
+ * morta E refazer uma fase. `escalada` e a terceira porta: o limite do manifesto.
+ */
+function playbookDaRetomada(carregado, pedido, opcoes = {}) {
+    const { manifesto } = carregado;
+    if (pedido.tentativas >= manifesto.retry.max_tentativas) {
+        return {
+            playbook: 'escalada',
+            razao: `${pedido.tentativas} retomada(s) do pedido ${pedido.id} para o limite de ` +
+                `${manifesto.retry.max_tentativas}: escalacao tipada pausa qualquer modo, inclusive #Auto`,
+            slugSugerido: null,
+        };
+    }
+    const veredito = (0, tokens_1.gateDeTokens)(carregado, pedido.thread, {
+        proximo: pedido.fase,
+        refazer: true,
+        ocupacao: opcoes.ocupacao,
+        fonte: opcoes.fonte,
+    });
+    if (veredito.veredito === 'new-session') {
+        return {
+            playbook: 'nova-sessao',
+            razao: `gate de tokens: ${veredito.razao}`,
+            slugSugerido: veredito.slugSugerido,
+        };
+    }
+    return {
+        playbook: 'mesma-sessao',
+        razao: `gate de tokens: ${veredito.razao}`,
+        slugSugerido: null,
+    };
+}
+/** Retoma UM pedido da fila, aplicando o playbook que couber. */
+function retomarPedido(carregado, pedidoOriginal, opcoes = {}) {
+    const { raiz } = carregado;
+    const quando = opcoes.quando ?? (0, util_1.agora)();
+    const thread = (0, thread_1.lerThread)(raiz, pedidoOriginal.thread);
+    const dir = (0, thread_1.dirThread)(raiz, thread.id);
+    let pedido = pedidoOriginal;
+    if (!opcoes.forcar && pedido.liberaEm > quando) {
+        return {
+            pedido,
+            playbook: 'mesma-sessao',
+            slug: pedido.slug,
+            despachada: false,
+            sessionId: null,
+            verificada: false,
+            motivo: 'runtime.rate-limited',
+            detalhe: `a janela ainda nao liberou (libera em ${pedido.liberaEm})`,
+            dryRun: opcoes.dryRun === true,
+        };
+    }
+    const escolha = playbookDaRetomada(carregado, pedido, opcoes);
+    // Playbook 3: escalada. Pausa QUALQUER modo, e o pedido sai da fila de espera.
+    if (escolha.playbook === 'escalada') {
+        (0, gates_1.registrarGateBloqueado)(dir, thread.id, {
+            gate: 'phase.dispatch',
+            motivo: 'human.pending',
+            modo: thread.modo,
+            detalhe: escolha.razao,
+            correcao: `ork gate approve ${thread.id} retomada --por <quem>`,
+            fase: pedido.fase,
+            slug: pedido.slug,
+            pedido: pedido.id,
+            pausaQualquerModo: true,
+        });
+        (0, ledger_1.registrar)(dir, thread.id, ledger_1.TIPOS_DE_EVENTO.retryEscalado, {
+            fase: pedido.fase,
+            motivo: 'runtime.rate-limited',
+            origem: 'rate-limit.fila',
+            pedido: pedido.id,
+            tentativas: pedido.tentativas,
+            limite: carregado.manifesto.retry.max_tentativas,
+            modo: thread.modo,
+            razao: escolha.razao,
+        });
+        pedido = (0, ratelimit_1.gravarPedido)(raiz, { ...pedido, estado: 'escalado', detalhe: escolha.razao });
+        return {
+            pedido,
+            playbook: 'escalada',
+            slug: pedido.slug,
+            despachada: false,
+            sessionId: null,
+            verificada: false,
+            motivo: 'human.pending',
+            detalhe: escolha.razao,
+            dryRun: opcoes.dryRun === true,
+        };
+    }
+    // Playbooks 1 e 2: mesma sessao (mesmo slug) ou nova sessao (slug rotacionado).
+    //
+    // A rotacao conta o slug da sessao MORTA junto dos slugs ja usados na thread. A fase
+    // morreu antes de virar sessao registrada, entao sem isso o `slugDaSessao` devolveria
+    // o mesmo slug e a "nova sessao" nasceria com o nome da que acabou de cair.
+    const slug = escolha.playbook === 'nova-sessao'
+        ? (0, slug_1.proximaRotacao)(pedido.slug, [...thread.sessoes.map((s) => s.slug), pedido.slug])
+        : pedido.slug;
+    const r = redespachar(carregado, thread, pedido.fase, pedido.promptPath, pedido.promptSha256, {
+        slug,
+        model: pedido.model,
+        effort: pedido.effort,
+        cwd: pedido.cwd,
+        origem: 'retry.rate-limit',
+        dryRun: opcoes.dryRun,
+    });
+    (0, ledger_1.registrar)(dir, thread.id, ledger_1.TIPOS_DE_EVENTO.retryTentado, {
+        fase: pedido.fase,
+        motivo: 'runtime.rate-limited',
+        acao: 'esperar-janela',
+        playbook: escolha.playbook,
+        pedido: pedido.id,
+        slug,
+        tentativa: pedido.tentativas + 1,
+        limite: carregado.manifesto.retry.max_tentativas,
+        modo: thread.modo,
+        dryRun: opcoes.dryRun === true,
+        ok: r.ok,
+        detalhe: r.detalhe,
+    });
+    if (opcoes.dryRun) {
+        return {
+            pedido,
+            playbook: escolha.playbook,
+            slug,
+            despachada: false,
+            sessionId: null,
+            verificada: false,
+            motivo: r.motivo,
+            detalhe: `${escolha.razao}; ${r.detalhe}`,
+            dryRun: true,
+        };
+    }
+    if (r.ok) {
+        (0, ledger_1.registrar)(dir, thread.id, ledger_1.TIPOS_DE_EVENTO.rateLimitRetomado, {
+            fase: pedido.fase,
+            pedido: pedido.id,
+            playbook: escolha.playbook,
+            slug,
+            sessionId: r.sessionId,
+            promptSha256: pedido.promptSha256,
+            esperouAte: pedido.liberaEm,
+            janelaEstimada: pedido.janelaEstimada,
+            modo: thread.modo,
+            autorizadoPor: 'politica de retry do bloco B3 (rate limit nao pausa modo nenhum)',
+            evidencia: `mesmo prompt sha256 ${pedido.promptSha256}`,
+            razao: escolha.razao,
+        });
+        pedido = (0, ratelimit_1.gravarPedido)(raiz, {
+            ...pedido,
+            estado: 'retomado',
+            tentativas: pedido.tentativas + 1,
+            detalhe: r.detalhe,
+        });
+        return {
+            pedido,
+            playbook: escolha.playbook,
+            slug,
+            despachada: true,
+            sessionId: r.sessionId,
+            verificada: r.verificada,
+            motivo: null,
+            detalhe: r.detalhe,
+            dryRun: false,
+        };
+    }
+    // Falhou de novo. Rate limit outra vez reagenda o MESMO pedido com a hora nova;
+    // qualquer outro motivo devolve o pedido para a fila com a tentativa contada.
+    const novaJanela = r.sinal?.resetEm ?? pedido.liberaEm;
+    pedido = (0, ratelimit_1.gravarPedido)(raiz, {
+        ...pedido,
+        tentativas: pedido.tentativas + 1,
+        liberaEm: novaJanela,
+        janelaEstimada: r.sinal ? r.sinal.resetEm === null : pedido.janelaEstimada,
+        sinal: r.sinal ?? pedido.sinal,
+        detalhe: r.detalhe,
+    });
+    return {
+        pedido,
+        playbook: escolha.playbook,
+        slug,
+        despachada: false,
+        sessionId: null,
+        verificada: false,
+        motivo: r.motivo,
+        detalhe: r.detalhe,
+        dryRun: false,
+    };
+}
+/** Retoma todos os pedidos cuja janela ja liberou. */
+function retomarFila(carregado, opcoes = {}) {
+    const quando = opcoes.quando ?? (0, util_1.agora)();
+    const alvos = opcoes.forcar ? (0, ratelimit_1.aguardando)(carregado.raiz) : (0, ratelimit_1.vencidos)(carregado.raiz, quando);
+    return alvos.map((p) => retomarPedido(carregado, p, { ...opcoes, quando }));
+}
+/** Retoma um pedido especifico pelo id. */
+function retomarPorId(carregado, id, opcoes = {}) {
+    return retomarPedido(carregado, (0, ratelimit_1.exigirPedido)(carregado.raiz, id), opcoes);
+}
+/** Cancela um pedido da fila, com motivo obrigatorio. */
+function cancelarPedido(carregado, id, motivo) {
+    const pedido = (0, ratelimit_1.exigirPedido)(carregado.raiz, id);
+    const cancelado = (0, ratelimit_1.gravarPedido)(carregado.raiz, {
+        ...pedido,
+        estado: 'cancelado',
+        detalhe: motivo,
+    });
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(carregado.raiz, pedido.thread), pedido.thread, ledger_1.TIPOS_DE_EVENTO.retryEscalado, {
+        fase: pedido.fase,
+        motivo: 'runtime.rate-limited',
+        origem: 'rate-limit.fila',
+        pedido: pedido.id,
+        estado: 'cancelado',
+        razao: motivo,
+    });
+    return cancelado;
+}
+/** O ultimo despacho que falhou nesta fase, de onde sai o prompt a redespachar. */
+function ultimoDespachoFalho(raiz, threadId, fase) {
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId));
+    for (let i = eventos.length - 1; i >= 0; i--) {
+        const e = eventos[i];
+        if (e.tipo === ledger_1.TIPOS_DE_EVENTO.despachoFalhou && e.fase === fase)
+            return e;
+    }
+    return null;
+}
+/**
+ * Executa a acao de retry do ultimo gate reprovado da thread.
+ *
+ * O que ele NAO faz: inventar uma acao que a politica nao previu, executar acao nao
+ * automatica sem autorizacao humana registrada, e reexecutar violacao de custo.
+ */
+function executarRetry(carregado, threadId, opcoes = {}) {
+    const { raiz } = carregado;
+    const plano = planejarRetry(carregado, threadId, opcoes);
+    const thread = (0, thread_1.lerThread)(raiz, threadId);
+    const dir = (0, thread_1.dirThread)(raiz, threadId);
+    const vazio = {
+        plano,
+        executada: false,
+        rodada: null,
+        reverify: null,
+        sync: null,
+        redespacho: null,
+        fila: [],
+        detalhe: plano.razao,
+    };
+    (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.retryPlanejado, {
+        fase: plano.fase,
+        motivo: plano.motivo,
+        acao: plano.acao,
+        modo: thread.modo,
+        tentativas: plano.tentativas,
+        limite: plano.limite,
+        automatica: plano.automatica,
+        bloqueio: plano.bloqueio,
+        effort: plano.effort,
+        razao: plano.razao,
+    });
+    if (!plano.automatica || plano.motivo === null) {
+        // Escalacao e custo viram gate humano explicito no ledger, nao silencio.
+        if (plano.bloqueio === 'escalacao.limite' || plano.acao === 'sem-retry') {
+            (0, gates_1.registrarGateBloqueado)(dir, threadId, {
+                gate: 'phase.dispatch',
+                motivo: plano.acao === 'sem-retry' ? plano.motivo : 'human.pending',
+                modo: thread.modo,
+                detalhe: plano.razao,
+                correcao: plano.politica?.correcao ?? `ork gate approve ${threadId} retry --por <quem>`,
+                fase: plano.fase,
+                origem: 'retry.run',
+                pausaQualquerModo: true,
+            });
+            (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.retryEscalado, {
+                fase: plano.fase,
+                motivo: plano.motivo,
+                origem: 'retry.run',
+                acao: plano.acao,
+                tentativas: plano.tentativas,
+                limite: plano.limite,
+                modo: thread.modo,
+                razao: plano.razao,
+            });
+        }
+        return vazio;
+    }
+    const acaoBase = plano.politica?.acao ?? plano.acao;
+    const registrarTentativa = (ok, detalhe) => {
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.retryTentado, {
+            fase: plano.fase,
+            motivo: plano.motivo,
+            acao: plano.acao,
+            acaoBase,
+            modo: thread.modo,
+            tentativa: plano.tentativas + 1,
+            limite: plano.limite,
+            effort: plano.effort,
+            effortAnterior: plano.effortAnterior,
+            dryRun: opcoes.dryRun === true,
+            autorizadoPor: blocoPausa(thread, plano.fase)
+                ? (opcoes.autorizadoPor ?? 'humano')
+                : `politica de retry do bloco B3 (bloco sem pausa no modo ${thread.modo})`,
+            ok,
+            detalhe,
+        });
+    };
+    // `esperar-janela`: quem retoma e a fila, e ela ja esta gravada em disco.
+    if (acaoBase === 'esperar-janela') {
+        const fila = (0, ratelimit_1.lerFilaDeRetomada)(raiz).filter((p) => p.thread === threadId && p.estado === 'aguardando');
+        const detalhe = fila.length > 0
+            ? `${fila.length} pedido(s) na fila duravel; o proximo libera em ${fila[0].liberaEm}`
+            : 'nenhum pedido aguardando na fila para esta thread';
+        registrarTentativa(fila.length > 0, detalhe);
+        return { ...vazio, executada: fila.length > 0, fila, detalhe };
+    }
+    if (acaoBase === 'sincronizar-worktree') {
+        const sync = (0, worktree_1.sincronizarWorktree)(carregado, threadId, { dryRun: opcoes.dryRun });
+        const detalhe = sync.ok
+            ? `worktree sincronizada com a base (${sync.passos.join('; ')})`
+            : `sincronizacao nao concluiu: ${sync.detalhe}`;
+        registrarTentativa(sync.ok, detalhe);
+        return { ...vazio, executada: sync.ok, sync, detalhe };
+    }
+    if (acaoBase === 'corrigir-dirigido') {
+        const rodada = (0, fix_1.abrirRodada)(carregado, threadId);
+        const reverify = opcoes.reverify && rodada.correcoes.length > 0
+            ? (0, fix_1.reverificar)(carregado, threadId, { rodada: rodada.rodada })
+            : null;
+        const detalhe = rodada.correcoes.length === 0
+            ? 'o CHECK passou no HEAD real: nao ha correcao a dirigir'
+            : `${rodada.correcoes.length} correcao(oes) na rodada ${rodada.rodada}` +
+                (reverify ? `; CHECK-REVERIFY: ${reverify.veredito}` : '');
+        registrarTentativa(rodada.correcoes.length > 0, detalhe);
+        return { ...vazio, executada: rodada.correcoes.length > 0, rodada, reverify, detalhe };
+    }
+    // `reexecutar` e `escalar-esforco`: o MESMO prompt volta ao runtime.
+    const falho = ultimoDespachoFalho(raiz, threadId, plano.fase);
+    if (!falho || typeof falho.promptPath !== 'string' || typeof falho.promptSha256 !== 'string') {
+        const detalhe = `nao ha despacho falho registrado em ${plano.fase} com prompt gravado: ` +
+            `rode a fase de novo com \`ork phase run ${threadId} ${plano.fase} --prompt "..."\``;
+        registrarTentativa(false, detalhe);
+        return { ...vazio, detalhe };
+    }
+    const redespacho = redespachar(carregado, thread, plano.fase, falho.promptPath, falho.promptSha256, {
+        effort: plano.effort,
+        model: typeof falho.model === 'string' ? falho.model : null,
+        origem: 'retry.run',
+        dryRun: opcoes.dryRun,
+    });
+    registrarTentativa(redespacho.ok, redespacho.detalhe);
+    return {
+        ...vazio,
+        executada: redespacho.ok,
+        redespacho,
+        detalhe: redespacho.detalhe,
+    };
+}
+/** Texto de `ork retry plan`. */
+function textoDoPlano(p) {
+    const linhas = [];
+    linhas.push(`Plano de retry da thread ${p.thread}`);
+    linhas.push(`  modo            ${p.modo}`);
+    linhas.push(`  fase            ${p.fase ?? '(nenhuma)'}`);
+    linhas.push(`  motivo tipado   ${p.motivo ?? '(nenhuma reprovacao pendente)'}`);
+    if (p.detalhe)
+        linhas.push(`  detalhe         ${p.detalhe}`);
+    linhas.push(`  acao            ${p.acao}`);
+    linhas.push(`  tentativas      ${p.tentativas} de ${p.limite} antes da escalacao`);
+    linhas.push(`  esforco         ${p.effort}${p.effort !== p.effortAnterior ? ` (escalado de ${p.effortAnterior})` : ''}`);
+    linhas.push(`  automatica      ${p.automatica ? 'sim' : 'nao'}`);
+    if (p.bloqueio)
+        linhas.push(`  bloqueio        ${p.bloqueio}`);
+    linhas.push(`  razao           ${p.razao}`);
+    if (p.politica && !p.automatica)
+        linhas.push(`  correcao        ${p.politica.correcao}`);
+    return linhas.join('\n');
+}
+/** Texto de `ork retry run`. */
+function textoDoRetry(r) {
+    const linhas = [textoDoPlano(r.plano), ''];
+    linhas.push(`Execucao: ${r.executada ? 'acao executada' : 'nada executado'}`);
+    linhas.push(`  ${r.detalhe}`);
+    if (r.rodada && r.rodada.correcoes.length > 0) {
+        linhas.push('');
+        linhas.push(`GO-FIX rodada ${r.rodada.rodada}: ` +
+            r.rodada.correcoes.map((c) => `${c.id} (tipo ${c.tipo}, ${c.origem})`).join(', '));
+    }
+    if (r.reverify) {
+        linhas.push(`CHECK-REVERIFY: ${r.reverify.veredito} (cobertura ${r.reverify.cobertura})`);
+    }
+    if (r.fila.length > 0) {
+        linhas.push('');
+        linhas.push('Fila de rate limit desta thread:');
+        for (const p of r.fila) {
+            linhas.push(`  ${p.id}  ${p.fase}  libera em ${p.liberaEm}${p.janelaEstimada ? ' (janela estimada)' : ''}`);
+        }
+    }
+    return linhas.join('\n');
+}
+/** Texto de `ork retry resume`. */
+function textoDaRetomada(rs) {
+    if (rs.length === 0) {
+        return 'Nenhum pedido da fila de rate limit com a janela liberada agora.';
+    }
+    const linhas = [];
+    for (const r of rs) {
+        linhas.push(`${r.pedido.id}  thread ${r.pedido.thread}  fase ${r.pedido.fase}`);
+        linhas.push(`  playbook    ${r.playbook}`);
+        linhas.push(`  slug        ${r.slug}`);
+        linhas.push(`  retomada    ${r.despachada ? `sim (sessao ${r.sessionId})` : 'nao'}`);
+        if (r.motivo)
+            linhas.push(`  motivo      ${r.motivo}`);
+        linhas.push(`  detalhe     ${r.detalhe}`);
+        linhas.push(`  estado      ${r.pedido.estado}`);
+    }
+    return linhas.join('\n');
+}