@orkastery/cli 0.2.0 → 0.3.0

package/dist/hitl-classificacao.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLASSES_QUE_NAO_BLOQUEIAM = exports.JANELA_PADRAO_MIN = void 0;
+exports.atoIrreversivelDoItem = atoIrreversivelDoItem;
+exports.classificarItem = classificarItem;
+exports.contarClassificacoes = contarClassificacoes;
+/**
+ * I-41 (D16): as tres classificacoes que o resumo recorrente conta, cada uma com definicao
+ * verificavel e domicilio unico aqui.
+ *
+ * A ordem do dono era "urgente, bloqueando, critico", e a armadilha declarada era inventar tres
+ * nomes para a mesma coisa. Os tres predicados abaixo perguntam coisas diferentes:
+ *
+ *   BLOQUEANTE pergunta sobre ESTRUTURA: tem alguem parado esperando por isso?
+ *   URGENTE    pergunta sobre RELOGIO:   isso vence antes do proximo resumo?
+ *   CRITICO    pergunta sobre NATUREZA:  responder isso autoriza um ato que nao se desfaz?
+ *
+ * Elas nao sao independentes nos dados de hoje, e esconder isso seria pior que dizer. Com
+ * `ork.hitl/v1`, prazo so existe dentro de um pedido, e pedido so e anexado a item que tem
+ * sessao ou fase parada (`core/src/pulse.ts`, laco de `precisaDeHumanoAgora`): logo hoje
+ * URGENTE esta contido em BLOQUEANTE. Sob `ork.hitl/v2` isso se separa, porque uma pergunta
+ * com `seguir-recomendada` corre contra o relogio SEM segurar ninguem: a fabrica segue com a
+ * recomendada quando o prazo vence. O teste desta entrega prova os dois fatos, o de hoje e o
+ * de depois, em vez de prometer independencia que a medicao nega.
+ *
+ * I-41 (GO-FIX 1, A2), a resposta a "as duas colapsam?": NAO colapsam, porque BLOQUEANTE e
+ * estritamente maior. Hoje URGENTE esta contido nele (nenhum emissor usa `seguir-recomendada`,
+ * entao nenhum prazo corre sem alguem parado), mas a maioria do que trava nao vence antes do
+ * proximo resumo. As duas linhas ficam porque respondem perguntas diferentes: "tem alguem
+ * parado?" e "isso acaba antes do proximo aviso?". Somar as duas e o erro que o texto nao convida.
+ *
+ * I-41 (GO-FIX 1, A1): CRITICO deixou de ser zero por construcao. O emissor do gate declara o ato
+ * quando a pausa libera push na base protegida (`atoDaPausa`), e o item que espera nesse gate e
+ * contado como sem volta mesmo antes de o pedido nascer (`atoDoItem`).
+ *
+ * Nenhum dos tres predicado olha para texto. Todos leem campo estruturado.
+ */
+const hitl_contract_1 = require("./hitl-contract");
+/**
+ * Janela default da cadencia do resumo, em minutos. O dono pediu de hora em hora em 20/09; as
+ * tags dele preveem 8h, 2h, 60min, 30min e 15min, entao a janela e parametro, nao constante
+ * escondida. Ela entra em URGENTE porque "urgente" so quer dizer alguma coisa em relacao ao
+ * proximo aviso: o que vence depois do proximo resumo pode esperar por ele.
+ */
+exports.JANELA_PADRAO_MIN = 60;
+/**
+ * A unica classe de item que NAO bloqueia ninguem, e por isso a unica excecao escrita aqui.
+ * O score pendente nasce depois do `ship_done`: a entrega ja aconteceu, nenhuma fase espera por
+ * ele. Chamar 13 scores de "bloqueio" foi parte do que fez o produto dizer que 45 itens
+ * precisavam do dono agora quando 44 deles nao eram decisao dele.
+ */
+exports.CLASSES_QUE_NAO_BLOQUEIAM = ['score_pendente'];
+/**
+ * O ato irreversivel que responder este item autoriza, ou `undefined`.
+ *
+ * Duas fontes, nesta ordem. Primeiro o proprio pedido, quando ele declara (`ork.hitl/v2`);
+ * depois o mapa congelado por motivo, que e o que existe para um pedido `ork.hitl/v1`, que nao
+ * tem onde declarar. A declaracao vence o mapa porque e mais especifica: dois pedidos do mesmo
+ * motivo podem autorizar atos diferentes.
+ */
+function atoIrreversivelDoItem(item) {
+    const declarado = item.pedido?.ato;
+    if (typeof declarado === 'string' && hitl_contract_1.ATOS_IRREVERSIVEIS.includes(declarado)) {
+        return declarado;
+    }
+    return hitl_contract_1.ATO_IRREVERSIVEL_DO_MOTIVO[item.motivo];
+}
+/** Nome curto da sessao, do jeito que o dono ja ve em `ork board` e nos comandos de log. */
+const sessaoCurta = (id) => id.slice(0, 8);
+function classificarItem(item, opcoes) {
+    const agoraMs = Date.parse(opcoes.quando);
+    if (!Number.isFinite(agoraMs))
+        throw new Error('classificação HITL: instante de consulta inválido');
+    const janelaMin = opcoes.janelaMin ?? exports.JANELA_PADRAO_MIN;
+    if (!Number.isFinite(janelaMin) || janelaMin <= 0)
+        throw new Error('classificação HITL: janela da cadência inválida');
+    // BLOQUEANTE: existe sessao ou fase parada esperando por ele.
+    let bloqueante, porqueBloqueante;
+    if (exports.CLASSES_QUE_NAO_BLOQUEIAM.includes(item.classe)) {
+        bloqueante = false;
+        porqueBloqueante = 'a entrega já aconteceu; a nota é fila, não bloqueio';
+    }
+    else if (item.sessionId) {
+        bloqueante = true;
+        porqueBloqueante = `a sessão ${sessaoCurta(item.sessionId)} está parada esperando`;
+    }
+    else if (item.thread) {
+        bloqueante = true;
+        porqueBloqueante = item.fase
+            ? `a fase ${item.fase} de ${item.thread} está parada esperando`
+            : `${item.thread} está parada esperando`;
+    }
+    else {
+        bloqueante = false;
+        porqueBloqueante = 'não aponta sessão nem fase parada';
+    }
+    // URGENTE: o prazo vence antes do proximo resumo, ou ja venceu.
+    const prazoMs = item.pedido ? Date.parse((0, hitl_contract_1.prazoDoPedido)(item.pedido) ?? '') : NaN;
+    const urgente = Number.isFinite(prazoMs) && prazoMs <= agoraMs + janelaMin * 60000;
+    const porqueUrgente = !Number.isFinite(prazoMs)
+        ? 'não tem prazo correndo; antiguidade sozinha não cria urgência'
+        : prazoMs <= agoraMs ? 'o prazo já venceu' : `o prazo vence dentro dos próximos ${janelaMin} min`;
+    // CRITICO: responder autoriza um ato que nao se desfaz.
+    const ato = atoIrreversivelDoItem(item) ?? opcoes.atoDoItem?.(item);
+    const critico = ato !== undefined;
+    return {
+        urgente, bloqueante, critico, ...(ato ? { ato } : {}),
+        porque: {
+            urgente: porqueUrgente,
+            bloqueante: porqueBloqueante,
+            critico: ato ? `responder autoriza um ato que não se desfaz: ${ato}` : 'não autoriza nenhum ato da lista congelada',
+        },
+    };
+}
+function contarClassificacoes(itens, opcoes) {
+    const threads = new Set();
+    let urgentes = 0, bloqueantes = 0, criticos = 0;
+    for (const item of itens) {
+        const c = classificarItem(item, opcoes);
+        if (c.urgente)
+            urgentes++;
+        if (c.critico)
+            criticos++;
+        if (c.bloqueante) {
+            bloqueantes++;
+            if (item.thread)
+                threads.add(item.thread);
+        }
+    }
+    return { total: itens.length, urgentes, bloqueantes, criticos, threadsBloqueadas: [...threads].sort() };
+}

package/dist/hitl-contract.js

@@ -0,0 +1,465 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTRATOS_DE_PEDIDO = exports.CAMPOS_DE_GATE = exports.TETOS_HITL_V2 = exports.LETRAS_DE_ALTERNATIVA = exports.CONTRATO_HITL_V2 = exports.ATO_IRREVERSIVEL_DO_MOTIVO = exports.ATOS_IRREVERSIVEIS = exports.CONTRATO_HITL = void 0;
+exports.atoDaPausa = atoDaPausa;
+exports.profundidadeDoModo = profundidadeDoModo;
+exports.profundidadeDoPedido = profundidadeDoPedido;
+exports.validarPedidoHitlV1 = validarPedidoHitlV1;
+exports.estadoDoPedido = estadoDoPedido;
+exports.respostaAceitaDoPedido = respostaAceitaDoPedido;
+exports.validarRespostaHitl = validarRespostaHitl;
+exports.vereditoDoGate = vereditoDoGate;
+exports.validarPedidoHitlV2 = validarPedidoHitlV2;
+exports.validarPedidoHitl = validarPedidoHitl;
+exports.ehV2 = ehV2;
+exports.classificarDecisao = classificarDecisao;
+exports.motivoDaRecusaDeFormato = motivoDaRecusaDeFormato;
+exports.escolhasDoPedido = escolhasDoPedido;
+exports.chaveDaEscolha = chaveDaEscolha;
+exports.prazoDoPedido = prazoDoPedido;
+exports.expiracaoDoPedido = expiracaoDoPedido;
+exports.alvoDoPedido = alvoDoPedido;
+exports.textoDoPedido = textoDoPedido;
+exports.chavesAceitas = chavesAceitas;
+exports.recomendacaoDoPedido = recomendacaoDoPedido;
+exports.ehContratoDePedido = ehContratoDePedido;
+exports.motivoDoPedido = motivoDoPedido;
+/** D1: contrato de pedido, independente do host. Expiração nunca autoriza. */
+const modos_1 = require("./modos");
+const types_1 = require("./types");
+exports.CONTRATO_HITL = 'ork.hitl/v1';
+/**
+ * D5: a lista FECHADA de atos que nao se desfazem. Ela mora no nucleo, congelada, e nao no
+ * manifesto: `owner.timezone` pode ser configuracao, "nao gaste meu dinheiro sozinho" nao pode.
+ * Uma lista de seguranca que a configuracao do projeto afrouxa deixa de ser seguranca.
+ */
+exports.ATOS_IRREVERSIVEIS = ['dinheiro', 'publicacao-externa', 'apagar-dado', 'push-base-protegida'];
+/**
+ * D16: qual ato irreversivel um motivo tipado autoriza. O mapa e PARCIAL de proposito. A maioria
+ * dos motivos nao autoriza ato nenhum, e inventar um ato para cada motivo transformaria a lista
+ * congelada em decoracao. Sob `ork.hitl/v2` a fonte autoritativa passa a ser o proprio pedido,
+ * que declara qual dos quatro; este mapa e o que responde por um pedido `ork.hitl/v1`, que nao
+ * tem onde declarar. Ausencia aqui significa "nao se sabe que seja irreversivel", nunca
+ * "reversivel provado": e por isso que ele nunca libera nada, so acende a marca de critico.
+ */
+exports.ATO_IRREVERSIVEL_DO_MOTIVO = Object.freeze({ 'cost.violation': 'dinheiro' });
+/**
+ * I-41 (GO-FIX 1, A1): o ato que APROVAR uma pausa autoriza, lido do que a pausa declara.
+ *
+ * Ate aqui `criticos` era zero por construcao: o mapa por motivo tem uma entrada so, e nenhum
+ * emissor declarava ato. Mas a pausa ja diz sobre o que ela e, e isso e dado do nucleo
+ * (`modos.ts`), nao texto do agente. A pausa do `#Classic` sobre "evidencias, com autorizacao
+ * antecipada de push" e a do `#Look` e do `#Ork` sobre "push" liberam o push na base protegida:
+ * o SHIP le exatamente essa aprovacao como autorizacao (`autorizacaoDePush`). Aprovar uma delas
+ * e ato sem volta, e o resumo precisa dizer isso em vez de mostrar zero.
+ */
+function atoDaPausa(motivo, pausaSobre) {
+    const doMotivo = exports.ATO_IRREVERSIVEL_DO_MOTIVO[motivo];
+    if (doMotivo)
+        return doMotivo;
+    return motivo === 'human.pending' && /\bpush\b/i.test(pausaSobre) ? 'push-base-protegida' : undefined;
+}
+const identificador = (v) => typeof v === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(v);
+const texto = (v, limite) => typeof v === 'string' && !!v.trim() && v.length <= limite && !/[\x00-\x08\x0b-\x1f\x7f]/.test(v);
+const objeto = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const iso = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(v) &&
+    Number.isFinite(Date.parse(v)) && new Date(v).toISOString().replace('.000Z', 'Z') === v.replace('.000Z', 'Z');
+/**
+ * Profundidade derivada do modo do pedido.
+ *
+ * I-43 alargou SO a assinatura, de `Modo` para `ModoLegado`, e nao encostou no corpo:
+ * um pedido `ork.hitl/v1` gravado com `modo: look` precisa continuar devolvendo
+ * `profunda`, senao o recibo historico deixa de bater com o que ele diz.
+ *
+ * COSTURA COM A I-41: e a I-41 que torna a profundidade propriedade do PEDIDO, e e
+ * esta funcao inteira que ela substitui. O mapa abaixo fica intacto de proposito, para
+ * que o merge das duas threads nao escolha um mapa e perca o outro em silencio; quando
+ * a I-41 chegar, ele vira o fallback de leitura de recibo antigo.
+ */
+function profundidadeDoModo(modo) {
+    return modo === 'look' ? 'profunda' : modo === 'classic' || modo === 'ork' ? 'detalhada' : 'resumo';
+}
+/**
+ * D1/T6: a profundidade com que um pedido NASCE.
+ *
+ * Sob `ork.hitl/v2` ela e escolha do PEDIDO e vale nos cinco modos: `profundidadeDoModo` continua
+ * sendo o default sugerido, nao mais criterio de validacao. GOAL e PLAN sobem para `profunda`
+ * porque e ali que se decide premissa, e premissa sem artefato e sem diff e decidida no escuro.
+ * Em 20/09 um pedido de PLAN sobre premissas saiu em `resumo` (sem artefato, sem diff) porque o
+ * modo mandava; o modo nao sabe sobre o que se esta perguntando, a fase sabe.
+ *
+ * Isto governa somente o BLOCO DE EVIDENCIA. A pergunta, as alternativas, as consequencias e a
+ * recomendada saem identicas nas tres profundidades.
+ */
+function profundidadeDoPedido(fase, modo) {
+    return fase === 'GOAL' || fase === 'PLAN' ? 'profunda' : profundidadeDoModo(modo);
+}
+/**
+ * D1: o validador de `ork.hitl/v1`, CONGELADO.
+ *
+ * Ele e o que era `validarPedidoHitl` ate a I-41, movido sem alterar uma regra, e continua sendo
+ * a unica coisa que julga um pedido v1. Tres recibos v1 estao gravados em disco e pode haver
+ * pedido em voo; um validador compartilhado faria qualquer aperto futuro em v2 mudar o
+ * comportamento sobre eles. Congelar v1 em funcao propria e o que torna a promessa "v1 lido para
+ * sempre" verificavel por diff, e nao por intencao.
+ *
+ * Erros não ecoam o conteúdo recebido, que pode conter credencial.
+ */
+function validarPedidoHitlV1(v) {
+    if (!objeto(v) || v.contrato !== exports.CONTRATO_HITL || !identificador(v.id) || !identificador(v.thread) ||
+        !types_1.FASES.includes(v.fase) || !modos_1.MODOS_LEGADOS.includes(v.modo) ||
+        !texto(v.motivo, 100) || !texto(v.pergunta, 2000) || !texto(v.recomendacao, 1000)) {
+        throw new Error('pedido HITL: identificação, modo ou pergunta inválidos');
+    }
+    if (!iso(v.criadoEm) || !iso(v.prazo) || Date.parse(v.prazo) <= Date.parse(v.criadoEm) ||
+        !['esperar', 'escalar'].includes(v.acaoPadraoAoExpirar)) {
+        throw new Error('pedido HITL: prazo ou ação de expiração inválidos');
+    }
+    const alvo = v.alvo;
+    if (!objeto(alvo) || !(alvo.tipo === 'gate' && texto(alvo.sobre, 100) ||
+        alvo.tipo === 'session' && identificador(alvo.sessionId) && ['claude-bg', 'codex'].includes(alvo.runtime))) {
+        throw new Error('pedido HITL: alvo inválido');
+    }
+    const aceita = v.respostaAceita;
+    if (!objeto(aceita) || !['opcao', 'texto'].includes(aceita.tipo) ||
+        !Number.isInteger(aceita.maxCaracteres) || Number(aceita.maxCaracteres) < 1 || Number(aceita.maxCaracteres) > 4096 ||
+        alvo.tipo === 'gate' && aceita.tipo !== 'opcao')
+        throw new Error('pedido HITL: resposta aceita inválida');
+    if (!Array.isArray(v.opcoes) || v.opcoes.length > 12 || (aceita.tipo === 'opcao' && v.opcoes.length < 1) ||
+        v.opcoes.some((o, i) => !objeto(o) || o.numero !== i + 1 || !texto(o.texto, 200) ||
+            !['aprovar', 'recusar', 'responder', 'esperar'].includes(o.acao))) {
+        throw new Error('pedido HITL: opções devem ser numeradas, consecutivas e explícitas');
+    }
+    if (v.profundidade !== profundidadeDoModo(v.modo))
+        throw new Error('pedido HITL: profundidade incompatível com o modo');
+}
+function estadoDoPedido(pedido, quando = new Date().toISOString()) {
+    validarPedidoHitl(pedido);
+    if (!iso(quando))
+        throw new Error('instante de consulta HITL inválido');
+    if (Date.parse(quando) < Date.parse(pedido.criadoEm))
+        throw new Error('pedido HITL ainda não criado');
+    const prazo = prazoDoPedido(pedido), expiracao = expiracaoDoPedido(pedido);
+    // Fato consumado não tem relógio: ele não expira, não escala e não avança.
+    if (prazo === undefined || expiracao === undefined)
+        return 'aberto';
+    return Date.parse(quando) >= Date.parse(prazo) ? expiracao : 'aberto';
+}
+/** A forma de resposta que o pedido aceita. `decidido` não aceita nenhuma. */
+function respostaAceitaDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'pergunta' ? p.respostaAceita : undefined) : p.respostaAceita;
+}
+function validarRespostaHitl(pedido, resposta, quando) {
+    if (estadoDoPedido(pedido, quando) !== 'aberto')
+        throw new Error('pedido HITL expirado; nenhuma autorização concedida');
+    const aceita = respostaAceitaDoPedido(pedido);
+    // Responder a um fato consumado não é recusa de conteúdo: é não haver o que responder.
+    if (!aceita)
+        throw new Error('decisão informada não aceita resposta');
+    if (!texto(resposta, aceita.maxCaracteres))
+        throw new Error('resposta HITL inválida');
+    if (aceita.tipo === 'texto')
+        return null;
+    const digitado = resposta.trim().toLowerCase();
+    const escolhas = escolhasDoPedido(pedido);
+    // No v2 o dono digita a LETRA; o número continua aceito porque recusá-lo não protege nada e
+    // quem lê a mensagem antiga do terminal digitaria o número sem saber que mudou.
+    const opcao = escolhas.find((o, i) => chaveDaEscolha(pedido, i + 1).toLowerCase() === digitado || String(o.numero) === digitado);
+    if (!opcao)
+        throw new Error('resposta HITL deve escolher uma opção explícita');
+    return opcao;
+}
+/** Deriva todos os campos da decisão que podem alimentar memória humana. */
+function vereditoDoGate(pedido, opcao) {
+    validarPedidoHitl(pedido);
+    const alvo = alvoDoPedido(pedido);
+    if (!alvo)
+        throw new Error('decisão informada não tem gate: ela não pede nada');
+    if (alvo.tipo !== 'gate')
+        throw new Error('pedido destina-se à sessão, não ao gate');
+    const motivo = ehV2(pedido) ? (pedido.classe === 'pergunta' ? pedido.motivo : '') : pedido.motivo;
+    return {
+        fase: pedido.fase,
+        sobre: alvo.sobre,
+        estado: opcao?.acao === 'aprovar' && motivo === 'human.pending'
+            ? 'aprovado' : opcao?.acao === 'recusar' ? 'recusado' : 'aguardando',
+        opcao: opcao?.numero ?? null,
+    };
+}
+// ---------------------------------------------------------------------------
+// I-41 (D1): `ork.hitl/v2`. v1 continua sendo LIDO para sempre; v2 e o que passa a ser ESCRITO.
+//
+// O caminho e este e nao "v1 com campos opcionais" porque campo opcional que todo mundo precisa
+// preencher e ambiguidade que vira bug: nove arquivos de teste constroem pedido literal e nenhum
+// deles saberia quais opcionais sao obrigatorios na pratica.
+//
+// A uniao e discriminada por `classe`, e a diferenca entre as duas nao e de grau:
+//
+//   `decidido` e fato consumado. Nao tem prazo, nao tem identificador para colar, nao tem
+//   caminho de resposta, e nao segura fase nenhuma. Trazer campo de gate e RECUSA.
+//   `pergunta` e o unico que pode segurar, e o unico que o dono precisa responder.
+// ---------------------------------------------------------------------------
+exports.CONTRATO_HITL_V2 = 'ork.hitl/v2';
+exports.LETRAS_DE_ALTERNATIVA = ['a', 'b', 'c', 'd'];
+/** D13: tetos com origem na maior medida ja gravada nos catorze pedidos do historico. */
+exports.TETOS_HITL_V2 = Object.freeze({
+    pergunta: 200, alternativaTexto: 140, consequencia: 140, porque: 140,
+    corpoLinha: 200, corpoLinhas: 8, campoDaDecisao: 200, custo: 140, traducao: 120,
+});
+/** Campos de gate que um `decidido` NAO pode trazer. Trazer qualquer um e recusa. */
+exports.CAMPOS_DE_GATE = ['prazo', 'acaoPadraoAoExpirar', 'respostaAceita', 'opcoes', 'alternativas', 'codigo'];
+const linhaUnica = (v, limite) => texto(v, limite) && !/[\r\n]/.test(v);
+function validarComumV2(v) {
+    if (!identificador(v.id) || !identificador(v.thread) || !types_1.FASES.includes(v.fase) ||
+        !modos_1.MODOS_LEGADOS.includes(v.modo) || !iso(v.criadoEm) ||
+        !['resumo', 'detalhada', 'profunda'].includes(v.profundidade)) {
+        throw new Error('pedido HITL v2: identificação, modo, instante ou profundidade inválidos');
+    }
+}
+function validarDecidido(v) {
+    for (const campo of exports.CAMPOS_DE_GATE) {
+        if (v[campo] !== undefined)
+            throw new Error(`pedido HITL v2: decisão informada não pode trazer ${campo}`);
+    }
+    if (!linhaUnica(v.decidido, exports.TETOS_HITL_V2.campoDaDecisao) || !linhaUnica(v.porque, exports.TETOS_HITL_V2.campoDaDecisao) ||
+        !linhaUnica(v.comoMudar, exports.TETOS_HITL_V2.campoDaDecisao)) {
+        throw new Error('pedido HITL v2: decisão informada exige o que foi decidido, o porquê e como mudar');
+    }
+    const custo = v.custoDeReverter;
+    if (!objeto(custo) || !linhaUnica(custo.agora, exports.TETOS_HITL_V2.custo) || !linhaUnica(custo.depois, exports.TETOS_HITL_V2.custo)) {
+        throw new Error('pedido HITL v2: custo de reverter exige agora e depois, os dois presentes');
+    }
+    const criterio = v.criterio;
+    if (!objeto(criterio) || !['manifesto', 'ledger', 'medicao'].includes(criterio.tipo) ||
+        !linhaUnica(criterio.referencia, 300)) {
+        throw new Error('pedido HITL v2: decisão informada exige critério citado e resolvível');
+    }
+    // R1, porta fechada: ato irreversivel nunca se qualifica como decisao informada.
+    if (v.irreversivel === true)
+        throw new Error('pedido HITL v2: ato irreversível nunca é decisão informada');
+}
+function validarAlternativas(v) {
+    const alternativas = v.alternativas;
+    if (!Array.isArray(alternativas) || alternativas.length < 2 || alternativas.length > exports.LETRAS_DE_ALTERNATIVA.length) {
+        throw new Error('pedido HITL v2: de 2 a 4 alternativas, rotuladas de a a d');
+    }
+    let recomendadas = 0;
+    alternativas.forEach((bruta, i) => {
+        if (!objeto(bruta) || bruta.letra !== exports.LETRAS_DE_ALTERNATIVA[i]) {
+            throw new Error('pedido HITL v2: de 2 a 4 alternativas, rotuladas de a a d');
+        }
+        if (!linhaUnica(bruta.texto, exports.TETOS_HITL_V2.alternativaTexto))
+            throw new Error('pedido HITL v2: alternativa sem texto');
+        if (!['aprovar', 'recusar', 'responder', 'esperar'].includes(bruta.acao)) {
+            throw new Error('pedido HITL v2: alternativa sem ação explícita');
+        }
+        if (!linhaUnica(bruta.consequencia, exports.TETOS_HITL_V2.consequencia)) {
+            throw new Error('pedido HITL v2: alternativa sem consequência em uma linha');
+        }
+        if (bruta.recomendada === undefined) {
+            if (bruta.porque !== undefined)
+                throw new Error('pedido HITL v2: só a alternativa recomendada diz o porquê');
+            return;
+        }
+        if (bruta.recomendada !== true)
+            throw new Error('pedido HITL v2: recomendada só aceita true ou ausência');
+        if (!linhaUnica(bruta.porque, exports.TETOS_HITL_V2.porque)) {
+            throw new Error('pedido HITL v2: a alternativa recomendada precisa dizer o porquê em uma linha');
+        }
+        recomendadas++;
+    });
+    if (recomendadas !== 1)
+        throw new Error('pedido HITL v2: exatamente uma alternativa é recomendada');
+}
+function validarPergunta(v) {
+    if (!linhaUnica(v.pergunta, exports.TETOS_HITL_V2.pergunta)) {
+        throw new Error('pedido HITL v2: a pergunta é uma frase, sem quebra de linha');
+    }
+    if (!texto(v.motivo, 100))
+        throw new Error('pedido HITL v2: motivo inválido');
+    validarAlternativas(v);
+    if (!Array.isArray(v.corpo) || v.corpo.length > exports.TETOS_HITL_V2.corpoLinhas ||
+        v.corpo.some(l => !linhaUnica(l, exports.TETOS_HITL_V2.corpoLinha))) {
+        throw new Error('pedido HITL v2: o corpo é lista de linhas, nunca prosa corrida');
+    }
+    if (!['objetiva', 'aberta'].includes(v.tipoDeResposta))
+        throw new Error('pedido HITL v2: tipo de resposta inválido');
+    if (!/^[0-9A-Za-z]{3,8}$/.test(String(v.codigo ?? '')))
+        throw new Error('pedido HITL v2: código curto inválido');
+    const alvo = v.alvo;
+    if (!objeto(alvo) || !(alvo.tipo === 'gate' && texto(alvo.sobre, 100) ||
+        alvo.tipo === 'session' && identificador(alvo.sessionId) && ['claude-bg', 'codex'].includes(alvo.runtime))) {
+        throw new Error('pedido HITL v2: alvo inválido');
+    }
+    const aceita = v.respostaAceita;
+    if (!objeto(aceita) || !['opcao', 'texto'].includes(aceita.tipo) ||
+        !Number.isInteger(aceita.maxCaracteres) || Number(aceita.maxCaracteres) < 1 || Number(aceita.maxCaracteres) > 4096) {
+        throw new Error('pedido HITL v2: resposta aceita inválida');
+    }
+    if (!iso(v.prazo) || Date.parse(v.prazo) <= Date.parse(v.criadoEm) ||
+        !['esperar', 'escalar', 'seguir-recomendada'].includes(v.acaoPadraoAoExpirar)) {
+        throw new Error('pedido HITL v2: prazo ou ação de expiração inválidos');
+    }
+    if (typeof v.irreversivel !== 'boolean')
+        throw new Error('pedido HITL v2: irreversível precisa ser declarado');
+    if (v.irreversivel) {
+        if (!exports.ATOS_IRREVERSIVEIS.includes(String(v.ato))) {
+            throw new Error('pedido HITL v2: ato irreversível precisa nomear um da lista congelada');
+        }
+        // D5, primeira das quatro barreiras: a combinacao nao chega a existir.
+        if (v.acaoPadraoAoExpirar === 'seguir-recomendada') {
+            throw new Error('pedido HITL v2: ato irreversível nunca avança por expiração');
+        }
+    }
+    else if (v.ato !== undefined) {
+        throw new Error('pedido HITL v2: só pedido irreversível nomeia ato');
+    }
+}
+/** Valida `ork.hitl/v2`. Nunca aceita um v1: quem julga v1 e o validador congelado. */
+function validarPedidoHitlV2(v) {
+    if (!objeto(v) || v.contrato !== exports.CONTRATO_HITL_V2)
+        throw new Error('pedido HITL v2: contrato inválido');
+    validarComumV2(v);
+    if (v.classe === 'decidido')
+        return validarDecidido(v);
+    if (v.classe === 'pergunta')
+        return validarPergunta(v);
+    throw new Error('pedido HITL v2: classe precisa ser decidido ou pergunta');
+}
+/**
+ * O leitor das duas versoes. Despacha por contrato: v1 pelo validador congelado, v2 pelo novo.
+ *
+ * Os predicados basicos (`texto`, `iso`, `identificador`, `objeto`) sao compartilhados; so as
+ * regras de FORMA diferem, que e justamente o que mudou entre as versoes.
+ */
+function validarPedidoHitl(v) {
+    if (objeto(v) && v.contrato === exports.CONTRATO_HITL_V2)
+        return validarPedidoHitlV2(v);
+    validarPedidoHitlV1(v);
+}
+/** `true` para pedido `ork.hitl/v2`, para quem precisa escolher caminho sem repetir a string. */
+function ehV2(p) {
+    return p.contrato === exports.CONTRATO_HITL_V2;
+}
+function classificarDecisao(sinais) {
+    const pergunta = (motivo) => ({ classe: 'pergunta', motivo });
+    // As portas fechadas vêm primeiro: nenhuma quantidade de evidência as abre.
+    if (sinais.irreversivel)
+        return pergunta('o ato é irreversível');
+    if (sinais.gastaDinheiro)
+        return pergunta('o ato gasta dinheiro');
+    if (sinais.mudaEscopoOuProduto)
+        return pergunta('o ato muda escopo ou produto');
+    // Depois as quatro condições, na ordem em que o GOAL as escreveu.
+    const referencia = sinais.criterio?.referencia;
+    if (!sinais.criterio || typeof referencia !== 'string' || !referencia.trim()) {
+        return pergunta('não há critério escrito que sustente a escolha');
+    }
+    if (!sinais.alternativasEstritamentePiores)
+        return pergunta('as alternativas não são estritamente piores pelo critério');
+    if (!sinais.reversivelAntesDaEntrega)
+        return pergunta('não dá para desfazer antes da entrega');
+    if (!sinais.erroBaratoEDetectavel)
+        return pergunta('errar não sai barato, ou o erro não apareceria');
+    return { classe: 'decidido', motivo: `as quatro condições valem, pelo critério ${sinais.criterio.tipo}` };
+}
+/**
+ * D10: a recusa de FORMA do contrato v2 vira o motivo tipado `hitl.formato`.
+ *
+ * Ela existe para que quem emite um pedido malformado receba um motivo do catalogo, e nao uma
+ * string solta. `hitl.formato` tem politica de retry propria: `corrigir-dirigido` e automatica,
+ * porque o defeito e de quem escreveu o pedido. Escalar formato para o dono seria pedir que ele
+ * revise a sintaxe do robo.
+ *
+ * Recusa que nao e de forma (por exemplo contrato desconhecido) devolve `null`: inventar
+ * `hitl.formato` para tudo tornaria o motivo tao generico quanto a string que ele substitui.
+ */
+function motivoDaRecusaDeFormato(erro) {
+    const mensagem = erro instanceof Error ? erro.message : String(erro);
+    return mensagem.startsWith('pedido HITL v2: ') && !mensagem.includes('contrato inválido')
+        ? 'hitl.formato' : null;
+}
+// ---------------------------------------------------------------------------
+// I-41 (T4): a leitura COMUM as duas versoes.
+//
+// Quem consome um pedido (apresentacao, pulse, gate, sessao) nao deveria precisar saber qual
+// contrato ele usa. Estas funcoes dao a visao uniforme, e por isso `validarRespostaHitl` e
+// `vereditoDoGate` seguem com a mesma assinatura de antes: o que muda e o que elas aceitam.
+// ---------------------------------------------------------------------------
+/** As escolhas do pedido na forma que o resto do nucleo ja consome. `decidido` nao tem nenhuma. */
+function escolhasDoPedido(p) {
+    if (!ehV2(p))
+        return p.opcoes;
+    if (p.classe === 'decidido')
+        return [];
+    return p.alternativas.map((a, i) => ({ numero: i + 1, texto: a.texto, acao: a.acao }));
+}
+/**
+ * O que o dono DIGITA para escolher a n-esima alternativa (1-based).
+ *
+ * No v1 e o numero; no v2 e a letra. E esta a unica diferenca que o humano percebe entre as
+ * duas versoes, e ela existe porque letra dentro de um lote e o que o ponto (9) pede.
+ */
+function chaveDaEscolha(p, numero) {
+    return ehV2(p) ? (exports.LETRAS_DE_ALTERNATIVA[numero - 1] ?? String(numero)) : String(numero);
+}
+/** O prazo do pedido, ou `undefined` quando ele nao tem um. Fato consumado nao tem prazo. */
+function prazoDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'pergunta' ? p.prazo : undefined) : p.prazo;
+}
+/** A acao ao expirar, ou `undefined` quando o pedido nao expira. */
+function expiracaoDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'pergunta' ? p.acaoPadraoAoExpirar : undefined) : p.acaoPadraoAoExpirar;
+}
+/** O alvo do pedido, ou `undefined` para `decidido`, que nao se dirige a gate nem a sessao. */
+function alvoDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'pergunta' ? p.alvo : undefined) : p.alvo;
+}
+/** A frase que o dono le. Para `decidido`, o que foi decidido; para `pergunta`, a pergunta. */
+function textoDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'decidido' ? p.decidido : p.pergunta) : p.pergunta;
+}
+/**
+ * Tudo que o dono pode digitar para escolher a n-esima alternativa (1-based).
+ *
+ * No v1 e so o numero. No v2 e a letra E o numero: recusar o numero nao protege nada, e quem le
+ * uma mensagem antiga do terminal digitaria o numero sem saber que a forma mudou. Quem confere
+ * recibo precisa da lista inteira, senao uma resposta legitima deixaria de bater com o pedido.
+ */
+function chavesAceitas(p, numero) {
+    const chave = chaveDaEscolha(p, numero);
+    return chave === String(numero) ? [chave] : [chave, String(numero)];
+}
+/**
+ * A recomendacao em texto, nas duas versoes.
+ *
+ * No v1 e o campo livre `recomendacao`, que e justamente o que esta thread conserta. No v2 ela e
+ * DERIVADA da alternativa marcada: o texto dela mais o porque em uma linha. Derivar em vez de
+ * guardar um campo livre e o que impede a recomendacao de voltar a nao apontar alternativa
+ * nenhuma, como "Confira artefatos, claims e riscos antes de responder." nao apontava.
+ */
+function recomendacaoDoPedido(p) {
+    if (!ehV2(p))
+        return p.recomendacao;
+    if (p.classe === 'decidido')
+        return p.porque;
+    const escolhida = p.alternativas.find(a => a.recomendada);
+    return escolhida ? `${escolhida.letra}) ${escolhida.texto}: ${escolhida.porque ?? ''}`.trim() : '';
+}
+/** O motivo tipado do pedido, ou string vazia para `decidido`, que nao tem gate. */
+/**
+ * Os contratos que um recibo de pedido pode carregar, e SO eles.
+ *
+ * Um evento `human_gate` copia o contrato do pedido que respondeu. Quem confere autoria precisa
+ * aceitar as duas versoes, senao uma aprovacao legitima sob v2 vira autoria ambigua e o dono
+ * deixa de conseguir liberar a propria fase. Aceitar por lista fechada, e nao por prefixo, e o
+ * que mantem contrato desconhecido recusado: a promessa e ler v1 para sempre, nao ler qualquer
+ * coisa que comece com "ork.hitl".
+ */
+exports.CONTRATOS_DE_PEDIDO = [exports.CONTRATO_HITL, exports.CONTRATO_HITL_V2];
+function ehContratoDePedido(v) {
+    return exports.CONTRATOS_DE_PEDIDO.includes(v);
+}
+function motivoDoPedido(p) {
+    return ehV2(p) ? (p.classe === 'pergunta' ? p.motivo : '') : p.motivo;
+}