@orkastery/cli 0.2.0 → 0.4.1

package/dist/hitl-gates.js

@@ -0,0 +1,554 @@
+"use strict";
+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.MOTIVOS_DE_ESCALACAO_HUMANA = exports.contaDoEnvelope = exports.canalDoEnvelope = void 0;
+exports.contratoDaResposta = contratoDaResposta;
+exports.contextoHitl = contextoHitl;
+exports.contextoHitlDosEventos = contextoHitlDosEventos;
+exports.contextoDoPedidoNativo = contextoDoPedidoNativo;
+exports.comLockHitl = comLockHitl;
+exports.assinaturaDaResposta = assinaturaDaResposta;
+exports.autenticarResposta = autenticarResposta;
+exports.resolverCriterio = resolverCriterio;
+exports.registrarPedidoHitl = registrarPedidoHitl;
+exports.abrirPedidoGate = abrirPedidoGate;
+exports.prepararPedidoGate = prepararPedidoGate;
+exports.conferirResposta = conferirResposta;
+exports.dadosDaResposta = dadosDaResposta;
+exports.receberResposta = receberResposta;
+exports.responderGate = responderGate;
+exports.responderGateLocal = responderGateLocal;
+exports.lerRespostaStdin = lerRespostaStdin;
+/** D2: pedidos correlacionados; somente o ingresso autenticado pode atestar resposta. */
+const fs = __importStar(require("node:fs"));
+const hitl_lock_1 = require("./hitl-lock");
+const node_crypto_1 = require("node:crypto");
+const hitl_contract_1 = require("./hitl-contract");
+const hitl_lote_1 = require("./hitl-lote");
+const pulse_consentimento_1 = require("./pulse-consentimento");
+const manifest_1 = require("./manifest");
+const thread_1 = require("./thread");
+const ledger_1 = require("./ledger");
+const hitl_ingress_receipt_1 = require("./hitl-ingress-receipt");
+// FX5: `canalDoEnvelope` e `contaDoEnvelope` moraram aqui ate a conta entrar no corpo
+// assinado. As duas conferem ENVELOPE contra REGISTRO e ambiente, que e o assunto de
+// `hitl-ingress-receipt`; mante-las aqui obrigaria esse modulo a importar este de volta, e
+// o ciclo em tempo de execucao so aparece como `undefined is not a function`. A reexportacao
+// preserva a superficie publica que adaptadores e testes ja usam.
+var hitl_ingress_receipt_2 = require("./hitl-ingress-receipt");
+Object.defineProperty(exports, "canalDoEnvelope", { enumerable: true, get: function () { return hitl_ingress_receipt_2.canalDoEnvelope; } });
+Object.defineProperty(exports, "contaDoEnvelope", { enumerable: true, get: function () { return hitl_ingress_receipt_2.contaDoEnvelope; } });
+const hitl_local_atestado_1 = require("./hitl-local-atestado");
+const hitl_local_receipt_1 = require("./hitl-local-receipt");
+const memoria_humana_1 = require("./memoria-humana");
+const hitl_canais_1 = require("./hitl-canais");
+const hitl_native_1 = require("./hitl-native");
+const modos_1 = require("./modos");
+/**
+ * D12: o canal entra no corpo assinado, e é isso que o torna recibo em vez de rótulo.
+ * Hermes e OpenClaw compartilham transporte, mas usam chaves próprias e identidades
+ * distintas; sem o canal dentro do HMAC o recibo ainda perderia essa proveniência. O envelope `v1`
+ * continua aceito byte a byte, e um `v1` nunca ganha canal por inferência.
+ */
+function contratoDaResposta(r) {
+    if (r.origem === 'native')
+        return 'ork.hitl-native/v1';
+    return r.canal === undefined ? 'ork.hitl-answer/v1' : 'ork.hitl-answer/v2';
+}
+const sha = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+function contextoHitl(raiz, id) {
+    return contextoHitlDosEventos((0, thread_1.lerThread)(raiz, id), (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id)));
+}
+/** Mesmo contexto na autorização e na projeção, usando as fontes já observadas. */
+function contextoHitlDosEventos(t, eventos) {
+    const despacho = eventos.filter(e => e.tipo === 'phase_dispatch').at(-1);
+    return sha(JSON.stringify([t.modo, t.faseAtual, t.status, t.base, despacho?.sessionId, despacho?.ts]));
+}
+/** Leitura para o callback; não abre pedido nem recebe resposta ou identidade humana. */
+function contextoDoPedidoNativo(raiz, id, pedidoId) {
+    const events = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    const matches = events.filter(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedidoId);
+    if (matches.length !== 1)
+        throw Error('hitl.native.request-unavailable');
+    const event = matches[0];
+    (0, hitl_contract_1.validarPedidoHitl)(event.pedido);
+    const pedido = event.pedido;
+    if (pedido.thread !== id || event.contexto !== contextoHitl(raiz, id) || (0, hitl_contract_1.estadoDoPedido)(pedido) !== 'aberto')
+        throw Error('hitl.native.request-stale');
+    return { pedido, contexto: event.contexto, pedidoSha256: (0, hitl_local_atestado_1.hashPedidoLocal)(pedido) };
+}
+/** Serializa respostas concorrentes da mesma thread; lock ocupado recusa sem efeito. */
+function comLockHitl(raiz, id, executar) {
+    const dir = (0, thread_1.dirThread)(raiz, id);
+    (0, thread_1.lerThread)(raiz, id);
+    return (0, hitl_lock_1.comLockInspecionavel)(dir, 'thread-dispatch-ou-hitl', executar);
+}
+/** O corpo não é gravado. A chave pertence somente ao ingresso nativo do gateway. */
+function assinaturaDaResposta(thread, pedido, resposta, chave) {
+    if (resposta.origem === 'native')
+        return (0, hitl_native_1.nativeSignature)(thread, pedido, resposta, chave);
+    // FX5: `conta` tem posicao FIXA no corpo v2, e `null` quando o canal nao tem conta. Um
+    // campo opcional mudaria a aridade do array conforme o envelope, e dois envelopes
+    // diferentes poderiam produzir o mesmo corpo assinado. O v1 segue byte a byte o de antes.
+    const corpo = resposta.canal === undefined
+        ? ['ork.hitl-answer/v1', thread, pedido, resposta.origem, resposta.por, resposta.mensagem, resposta.recebidoEm, resposta.resposta]
+        : ['ork.hitl-answer/v2', thread, pedido, resposta.canal, resposta.conta ?? null,
+            resposta.origem, resposta.por, resposta.mensagem, resposta.recebidoEm, resposta.resposta];
+    return (0, node_crypto_1.createHmac)('sha256', chave).update(JSON.stringify(corpo)).digest('hex');
+}
+function autenticarResposta(thread, pedido, r, quando = new Date().toISOString()) {
+    if (r.origem === 'native') {
+        (0, hitl_native_1.authenticateNative)(thread, pedido, r, quando);
+        return;
+    }
+    // FX1: o canal decide a chave, e por isso ele e conferido ANTES dela. Um envelope que
+    // declara canal fora do registro nunca chega a consultar segredo nenhum.
+    const canal = (0, hitl_ingress_receipt_1.canalDoEnvelope)(r);
+    (0, hitl_ingress_receipt_1.contaDoEnvelope)(canal, r.conta);
+    const chave = (0, hitl_ingress_receipt_1.chaveDoIngresso)(canal);
+    const usuarios = (process.env.ORK_HITL_TELEGRAM_USERS ?? '').split(',').map(s => s.trim());
+    const chats = (process.env.ORK_HITL_TELEGRAM_CHATS ?? '').split(',').map(s => s.trim());
+    const usuario = /^telegram:(\d+)$/.exec(r.por ?? '');
+    const mensagem = /^telegram:(-?\d+):([a-zA-Z0-9_-]{1,100})$/.exec(r.mensagem ?? '');
+    const idade = Date.parse(quando) - Date.parse(r.recebidoEm);
+    if (r.origem !== 'telegram' || !usuario || !mensagem || !usuarios.includes(usuario[1]) || !chats.includes(mensagem[1]) ||
+        !Number.isFinite(idade) || idade < 0 || idade > 60000 || typeof r.resposta !== 'string' || r.resposta.length > 4096 ||
+        !/^[a-f0-9]{64}$/.test(r.prova ?? ''))
+        throw new Error('resposta humana sem proveniência válida');
+    const esperado = assinaturaDaResposta(thread, pedido, r, chave);
+    if (!(0, node_crypto_1.timingSafeEqual)(Buffer.from(esperado, 'hex'), Buffer.from(r.prova, 'hex')))
+        throw new Error('resposta humana não autenticada');
+}
+/**
+ * D2: o criterio de uma decisao informada RESOLVE, ou o pedido nao existe.
+ *
+ * Duas das tres resolvem de verdade. `manifesto` le a chave pelo caminho pontuado e confere que
+ * ela existe e tem valor; `ledger` le o ledger da thread e confere que o evento existe. A
+ * terceira, `medicao`, so tem a FORMA conferida, e o buraco esta dito com todas as letras:
+ * um comando citado pode nao provar nada, falhar, ou nao ter relacao com a decisao, e o nucleo
+ * nao sabe a diferenca na hora de abrir o pedido.
+ *
+ * Nao se fecha esse buraco executando o comando aqui, e por dois motivos: abrir um pedido HITL
+ * viraria executar comando arbitrario, e isto roda sob lock, entao um comando lento travaria a
+ * thread inteira. Quem fecha e o CHECK, que percorre os itens `decidido` e EXECUTA os comandos
+ * citados. A divisao fica registrada assim: a validacao impede citar NADA; o CHECK impede citar
+ * MENTIRA.
+ */
+function resolverCriterio(raiz, pedido) {
+    const { tipo, referencia } = pedido.criterio;
+    if (tipo === 'medicao') {
+        return { resolve: true, detalhe: 'comando citado; quem executa e reprova é o CHECK' };
+    }
+    if (tipo === 'manifesto') {
+        let alvo;
+        try {
+            alvo = (0, manifest_1.exigirManifesto)(raiz).manifesto;
+        }
+        catch {
+            return { resolve: false, detalhe: 'manifesto do projeto não pôde ser lido' };
+        }
+        for (const parte of referencia.split('.')) {
+            if (!alvo || typeof alvo !== 'object' || !(parte in alvo)) {
+                return { resolve: false, detalhe: `o manifesto não tem a chave ${referencia}` };
+            }
+            alvo = alvo[parte];
+        }
+        const vazio = alvo === undefined || alvo === null || alvo === '' ||
+            (Array.isArray(alvo) && alvo.length === 0);
+        return vazio
+            ? { resolve: false, detalhe: `a chave ${referencia} existe mas está vazia` }
+            : { resolve: true, detalhe: `chave ${referencia} lida do manifesto` };
+    }
+    // `ledger`: `<thread>#evento:<n>` (1-based) ou o `eventId` do proprio evento.
+    const comIndice = /^([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})#evento:(\d+)$/.exec(referencia);
+    const thread = comIndice ? comIndice[1] : pedido.thread;
+    let eventos;
+    try {
+        eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, thread));
+    }
+    catch {
+        return { resolve: false, detalhe: `a thread ${thread} não tem ledger legível` };
+    }
+    if (comIndice) {
+        const n = Number(comIndice[2]);
+        return n >= 1 && n <= eventos.length
+            ? { resolve: true, detalhe: `evento ${n} de ${thread}` }
+            : { resolve: false, detalhe: `${thread} não tem evento ${n}` };
+    }
+    return eventos.some(e => e.eventId === referencia)
+        ? { resolve: true, detalhe: `evento ${referencia} de ${thread}` }
+        : { resolve: false, detalhe: `nenhum evento de ${thread} tem esse identificador` };
+}
+function registrarPedidoHitl(raiz, pedido) {
+    (0, hitl_contract_1.validarPedidoHitl)(pedido);
+    // R1, camada 1: um `decidido` cujo critério não resolve não chega a existir.
+    if ((0, hitl_contract_1.ehV2)(pedido) && pedido.classe === 'decidido') {
+        const { resolve, detalhe } = resolverCriterio(raiz, pedido);
+        if (!resolve)
+            throw new Error(`decisão informada: critério não resolve (${detalhe})`);
+    }
+    return comLockHitl(raiz, pedido.thread, () => {
+        const t = (0, thread_1.lerThread)(raiz, pedido.thread), dir = (0, thread_1.dirThread)(raiz, t.id);
+        if (t.status === 'fechada' || t.faseAtual !== pedido.fase || t.modo !== pedido.modo)
+            throw new Error('pedido não corresponde à thread corrente');
+        const eventos = (0, ledger_1.lerLedger)(dir), existente = eventos.find(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedido.id);
+        if (existente) {
+            if (JSON.stringify(existente.pedido) !== JSON.stringify(pedido))
+                throw new Error('id de pedido reutilizado com outro conteúdo');
+            return existente.pedido;
+        }
+        (0, ledger_1.registrar)(dir, t.id, 'hitl_requested', { fase: pedido.fase, pedido, contexto: contextoHitl(raiz, t.id) });
+        return pedido;
+    });
+}
+/**
+ * D18: diagnóstico de um `phase_result` `human.pending` que não é conclusão provada. O watcher
+ * claude-bg grava `diagnostico`; resultado anterior a ele cai no `provaOrk.fonte` sem prova.
+ * Texto limpo de controle e com teto, para caber no pedido HITL.
+ */
+function diagnosticoSemConclusao(resultado) {
+    const prova = resultado.provaOrk;
+    const bruto = typeof resultado.diagnostico === 'string' ? resultado.diagnostico
+        : prova?.ok === false && typeof prova.fonte === 'string' ? `sem prova do ork: ${prova.fonte}` : null;
+    const limpo = bruto === null ? '' : Array.from(bruto.replace(/\p{Cc}/gu, ' ').trim()).slice(0, 600).join('');
+    return limpo === '' ? null : limpo;
+}
+/**
+ * As escalacoes tipadas que abrem gate para o dono. Lista fechada, domicilio unico: quem abre o
+ * gate e quem pergunta se um gate ainda espera o dono leem a mesma.
+ */
+exports.MOTIVOS_DE_ESCALACAO_HUMANA = ['policy.violation', 'cost.violation', 'retry.max_tentativas',
+    'hitl.credencial', 'runtime.unavailable'];
+/** Uma pausa do modo cria pedido, nunca human_gate. Escalação exige evento tipado. */
+function abrirPedidoGate(raiz, id, motivo = 'human.pending', quando = new Date().toISOString()) {
+    const preparado = prepararPedidoGate(raiz, id, motivo, quando);
+    return 'aberto' in preparado ? preparado.aberto : registrarPedidoHitl(raiz, preparado.novo);
+}
+/**
+ * I-41 (GO-FIX 1, B3): o gate que ainda espera o dono, SEM escrever nada.
+ *
+ * Faz todas as conferencias de `abrirPedidoGate` e devolve o pedido aberto que ja existe, ou o
+ * pedido novo que seria registrado. Nao grava, nao toma lock e nao mexe no ledger. E por aqui que
+ * o resumo sabe quantas perguntas vao de fato sair: um gate que ainda espera o dono e pergunta; um
+ * pedido velho cuja thread ja seguiu em frente e historia, e contar historia como pergunta era o
+ * defeito de B3 (o dono via "esperando voce" e, ao consentir, recebia zero perguntas).
+ *
+ * Lanca, com a mesma mensagem de sempre, quando o gate nao espera ninguem: modo sem pausa nesta
+ * fase, conclusao da fase ainda nao registrada, ou escalacao sem evento tipado que a prove.
+ */
+function prepararPedidoGate(raiz, id, motivo = 'human.pending', quando = new Date().toISOString()) {
+    const t = (0, thread_1.lerThread)(raiz, id), bloco = (0, thread_1.blocoDaThread)(t, t.faseAtual);
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    let semConclusao = null;
+    let parecerNegativo = '';
+    if (motivo === 'human.pending') {
+        if (!(0, thread_1.pausaNaThread)(t, t.faseAtual) || bloco.fases.at(-1) !== t.faseAtual)
+            throw new Error('modo não prevê pausa humana nesta fase');
+        // I-34 (D7, GO-FIX 1): vale o resultado do despacho corrente da fase, e só a falha de
+        // execução não é conclusão (o turno não terminou ou não entregou o artefato; cada motivo tem
+        // retry ou escalação própria). Parecer negativo (`claims.failed`, `verify.*`, `ci.failed`)
+        // é fase concluída e abre a pausa. Resultado legado sem classificação ou sem sessão vale.
+        const despacho = eventos.filter(e => e.tipo === 'phase_dispatch' && e.fase === t.faseAtual).at(-1);
+        const falhaDeExecucao = ['runtime.unavailable', 'runtime.silencio', 'runtime.rate-limited', 'artifact.missing'];
+        const doDespacho = (e) => !e.sessionId || !despacho?.sessionId || e.sessionId === despacho.sessionId;
+        const conclusao = (e) => e.tipo === 'phase_result' &&
+            !(e.classificacao === 'gate_blocked' && falhaDeExecucao.includes(String(e.motivo)));
+        if (!eventos.some(e => e.fase === t.faseAtual && doDespacho(e) && (conclusao(e) ||
+            e.tipo === 'gate_blocked' && e.motivo === 'human.pending')))
+            throw new Error('a conclusão da fase precisa estar registrada antes da pausa');
+        // D18: `human.pending` sem conclusão provada (falta de prova do ork, ou `failed` depois do
+        // Stop) leva o diagnóstico ao pedido, que não se apresenta como fase concluída.
+        const resultado = eventos.filter(e => e.tipo === 'phase_result' && e.fase === t.faseAtual && doDespacho(e)).at(-1);
+        if (resultado?.motivo === 'human.pending')
+            semConclusao = diagnosticoSemConclusao(resultado);
+        else if (PARECERES_QUE_PEDEM_REVISAO.includes(String(resultado?.motivo ?? '')))
+            parecerNegativo = String(resultado?.motivo);
+    }
+    else if (!exports.MOTIVOS_DE_ESCALACAO_HUMANA.includes(motivo) ||
+        !eventos.some(e => e.fase === t.faseAtual && (e.tipo === 'gate_blocked' && e.motivo === motivo ||
+            e.tipo === 'retry_escalated' && motivo === 'retry.max_tentativas')))
+        throw new Error('escalação tipada não comprovada');
+    // I-41 (T4d): pedido aberto e lido pelos leitores das duas versoes. Ler `.alvo.tipo` direto
+    // lancaria TypeError diante de um `decidido`, que nao tem alvo e pode estar no mesmo ledger.
+    // GO-FIX 1: o contexto e calculado uma vez sobre o que ja foi lido; reler thread e ledger por
+    // pedido deixava a conferencia quadratica, e o resumo agora a faz para cada thread da fila.
+    const contexto = contextoHitlDosEventos(t, eventos);
+    const atual = eventos.filter(e => e.tipo === 'hitl_requested' && e.contexto === contexto &&
+        (0, hitl_contract_1.alvoDoPedido)(e.pedido)?.tipo === 'gate' &&
+        (0, hitl_contract_1.motivoDoPedido)(e.pedido) === motivo).at(-1);
+    const pedidoAtual = atual?.pedido;
+    if (pedidoAtual && (0, hitl_contract_1.estadoDoPedido)(pedidoAtual, quando) === 'aberto' &&
+        !eventos.some(e => e.tipo === 'human_gate' && e.pedidoId === pedidoAtual.id))
+        return { aberto: pedidoAtual };
+    const sobre = motivo === 'human.pending' ? bloco.pausaSobre : `escalacao:${motivo}`;
+    const primeira = semConclusao ? 'Aprovar sem conclusão provada (conferi a entrega)'
+        : motivo === 'human.pending' ? 'Aprovar com as evidências apresentadas' : 'Reconhecer e encaminhar a correção';
+    const recomendada = recomendadaDoGate(motivo, semConclusao, parecerNegativo);
+    const alternativas = [
+        [primeira, motivo === 'human.pending' ? 'aprovar' : 'responder'],
+        ['Solicitar revisão', 'recusar'],
+        ['Continuar esperando', 'esperar'],
+    ].map(([texto, acao], i) => {
+        const letra = LETRAS_DO_GATE[i];
+        return { letra, texto, acao, consequencia: hitl_lote_1.CONSEQUENCIA_DA_ACAO[acao],
+            ...(letra === recomendada.letra ? { recomendada: true, porque: recomendada.porque } : {}) };
+    });
+    // A1: o ato vem do motivo ou do que a pausa declara. A pausa que libera push na base protegida
+    // e sem volta, e dizer isso e o que tira `criticos` do zero por construcao.
+    const ato = (0, hitl_contract_1.atoDaPausa)(motivo, bloco.pausaSobre);
+    // O codigo curto e unico contra os que ja estao no ledger desta thread. T11 acrescenta o
+    // comando que o resolve; a unicidade precisa nascer com o primeiro pedido que o carrega.
+    const codigo = (0, pulse_consentimento_1.gerarCodigo)(eventos.flatMap(e => {
+        const c = e.pedido?.codigo;
+        return typeof c === 'string' ? [c] : [];
+    }));
+    // I-43: thread em modo aposentado e lida para sempre, mas nao escreve pergunta nova.
+    const modo = (0, modos_1.exigirModoVivo)(t.modo);
+    const pedido = { contrato: hitl_contract_1.CONTRATO_HITL_V2, classe: 'pergunta', id: (0, node_crypto_1.randomUUID)(),
+        thread: id, fase: t.faseAtual, modo, criadoEm: quando,
+        // T6: GOAL e PLAN nascem em `profunda`. Um gate sobre premissa sem artefato e sem diff e
+        // decidido no escuro, e o modo nao sabe sobre o que se esta perguntando; a fase sabe.
+        profundidade: (0, hitl_contract_1.profundidadeDoPedido)(t.faseAtual, modo),
+        alvo: { tipo: 'gate', sobre }, motivo,
+        // I-41 (D1/T6): a pergunta e uma frase e a evidencia mora no corpo. O diagnostico de uma
+        // fase sem conclusao chega a 600 caracteres e estourava o teto da pergunta; separado, ele
+        // cabe e passa a ser lido como evidencia, que e o que ele sempre foi.
+        pergunta: `Qual é o veredito sobre ${sobre}?`,
+        alternativas,
+        corpo: [`Fase ${t.faseAtual}, motivo ${motivo}`,
+            ...(semConclusao ? [linhaDoCorpo(`Sem conclusão provada: ${semConclusao}`)] : []),
+            ...(parecerNegativo ? [`Parecer registrado da fase: ${parecerNegativo}`] : [])],
+        tipoDeResposta: 'objetiva', irreversivel: ato !== undefined, ...(ato ? { ato } : {}), codigo,
+        prazo: new Date(Date.parse(quando) + 60 * 60 * 1000).toISOString(), acaoPadraoAoExpirar: 'esperar',
+        respostaAceita: { tipo: 'opcao', maxCaracteres: 100 } };
+    return { novo: pedido };
+}
+const LETRAS_DO_GATE = ['a', 'b', 'c'];
+/** Corta uma linha de evidencia no teto do corpo, sem deixar o pedido inteiro ser recusado. */
+const linhaDoCorpo = (texto) => texto.slice(0, hitl_contract_1.TETOS_HITL_V2.corpoLinha);
+/**
+ * Pareceres que ja sao conclusao da fase E pedem revisao. Um `phase_result` com qualquer um
+ * deles abre a pausa (I-34/D7), e recomendar "aprovar" em cima dele seria recomendar aprovar
+ * uma fase que o proprio produto reprovou.
+ */
+const PARECERES_QUE_PEDEM_REVISAO = ['claims.failed', 'claims.unverifiable', 'verify.failed', 'verify.regression', 'verify.timeout', 'verify.sem-veredito', 'ci.failed'];
+/**
+ * Qual alternativa o nucleo recomenda neste gate, e por que, em uma linha.
+ *
+ * I-41: ate aqui a recomendacao era "Confira artefatos, claims e riscos antes de responder.",
+ * que nao aponta alternativa nenhuma e por isso nao e recomendacao: e um aviso. Os tres casos
+ * abaixo saem de FATO REGISTRADO no ledger, nunca de julgamento do agente, e e essa derivacao
+ * que faz a recomendada ser verificavel em vez de escolhida no chute.
+ */
+function recomendadaDoGate(motivo, semConclusao, parecer) {
+    if (motivo !== 'human.pending') {
+        return { letra: 'a', porque: `escalação tipada ${motivo}: reconhecer encaminha a correção dirigida` };
+    }
+    if (semConclusao)
+        return { letra: 'b', porque: 'a fase não tem conclusão provada; o diagnóstico está no corpo' };
+    if (parecer)
+        return { letra: 'b', porque: `o parecer registrado da fase foi ${parecer}` };
+    return { letra: 'a', porque: 'a fase registrou conclusão e as evidências acompanham o pedido' };
+}
+const CAMPOS_QUE_A_DERIVADA_PRESERVA = ['origem', 'por', 'mensagem', 'recebidoEm', 'prova', 'canal', 'conta'];
+/** Quem prova que a resposta veio do dono: o envelope do proprio pedido, ou o do endereco assinado. */
+function provaDaResposta(id, pedidoId, resposta, assinado) {
+    if (!assinado)
+        return instante => autenticarResposta(id, pedidoId, resposta, instante);
+    const { envelope } = assinado;
+    // So o endereco do pulse e aceito. Um envelope assinado para OUTRO pedido nunca serve de prova
+    // para este: sem esta porta, quem tivesse um envelope legitimo de um gate poderia aponta-lo
+    // para outro pedido, e a assinatura continuaria batendo com o endereco que ela de fato cobre.
+    if (assinado.alvo !== pulse_consentimento_1.ALVO_DO_PULSE || assinado.endereco !== pulse_consentimento_1.ENDERECO_DA_RESPOSTA) {
+        throw new Error('endereço assinado fora do pulse não prova resposta a outro pedido');
+    }
+    if (envelope.origem !== 'telegram' || resposta.native !== undefined || envelope.native !== undefined ||
+        CAMPOS_QUE_A_DERIVADA_PRESERVA.some(c => resposta[c] !== envelope[c])) {
+        throw new Error('resposta derivada diverge do envelope assinado pelo ingresso');
+    }
+    return instante => autenticarResposta(assinado.alvo, assinado.endereco, envelope, instante);
+}
+/** Usado sob lock tanto por gates como por sessões. Repetição não executa novamente. */
+function conferirResposta(raiz, id, pedidoId, resposta, quando, assinado) {
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    const anterior = eventos.find(e => ['human_gate', 'session_answered'].includes(e.tipo) && e.pedidoId === pedidoId);
+    if (!anterior)
+        (0, hitl_canais_1.conferirCanalSelecionado)(eventos, pedidoId, resposta.canal, resposta.origem, resposta.native?.connectionId);
+    const pendente = eventos.find(e => e.tipo === 'session_answer_sending' && e.pedidoId === pedidoId);
+    const conhecido = anterior ?? pendente;
+    const replay = conhecido && typeof resposta.prova === 'string' && conhecido.mensagem === resposta.mensagem &&
+        conhecido.autorizadoPor === resposta.por && conhecido.recibo === sha(resposta.prova);
+    // Recibo persistido de um envelope idêntico já prova sua janela original. Replay
+    // ainda verifica assinatura/allowlists, mas não volta a executar após os 60 segundos.
+    // Primeiro verifica chave, allowlists e assinatura; a janela real é exigida logo abaixo.
+    const provar = provaDaResposta(id, pedidoId, resposta, assinado);
+    provar(resposta.recebidoEm);
+    const ingresso = (0, hitl_ingress_receipt_1.instanteDoIngresso)(raiz, id, pedidoId, resposta);
+    provar(replay ? resposta.recebidoEm : ingresso ?? quando);
+    const evento = eventos.find(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedidoId);
+    if (!evento)
+        throw new Error('pedido HITL não encontrado nesta thread');
+    const pedido = evento.pedido;
+    (0, hitl_contract_1.validarPedidoHitl)(pedido);
+    if (resposta.origem === 'native' && (resposta.native?.pedidoSha256 !== (0, hitl_local_atestado_1.hashPedidoLocal)(pedido) ||
+        resposta.native.context !== evento.contexto || resposta.native.expiresAt !== pedido.prazo))
+        throw Error('hitl.native.request-mismatch');
+    if (anterior) {
+        if (anterior.mensagem !== resposta.mensagem || anterior.autorizadoPor !== resposta.por || anterior.recibo !== sha(resposta.prova))
+            throw new Error('pedido já respondido; resposta divergente recusada');
+        return { pedido, anterior, opcao: null };
+    }
+    if (pendente && pedido.alvo.tipo === 'session') {
+        if (!replay)
+            throw new Error('envio já iniciado; resposta divergente recusada');
+        // responderSessao apenas consulta o envioId persistido neste caminho. Não
+        // reaplica o conteúdo, não responde à sessão nova e não autoriza o bloco.
+        return { pedido, opcao: null };
+    }
+    if (eventos.some(e => ['human_gate', 'session_answered', 'session_answer_sending'].includes(e.tipo) &&
+        e.pedidoId !== pedidoId && e.mensagem === resposta.mensagem))
+        throw new Error('mensagem já usada ou reservada em outro pedido');
+    if (evento.contexto !== contextoHitl(raiz, id))
+        throw new Error('pedido antigo: fase, modo ou sessão mudou');
+    return { pedido, opcao: (0, hitl_contract_1.validarRespostaHitl)(pedido, resposta.resposta, quando) };
+}
+function dadosDaResposta(pedido, r) {
+    const canal = (0, hitl_ingress_receipt_1.canalDoEnvelope)(r);
+    return { contrato: pedido.contrato, pedidoId: pedido.id, fase: pedido.fase, origem: r.origem,
+        autorizadoPor: r.por, mensagem: r.mensagem, recebidoEm: r.recebidoEm, recibo: sha(r.prova),
+        canal, conta: r.origem === 'native' ? r.conta : (0, hitl_ingress_receipt_1.contaDoEnvelope)(canal, r.conta), contratoResposta: contratoDaResposta(r),
+        ...(r.origem === 'native' ? { native: hitl_native_1.nativeContextSchema.parse(r.native) } : {}) };
+}
+function receberResposta(raiz, id, pedidoId, r, quando = new Date().toISOString(), assinado) {
+    // Consulta sem efeito: prova a janela antes da contenção, mas não autoriza efeito fora do lock.
+    const conferida = conferirResposta(raiz, id, pedidoId, r, quando, assinado);
+    if (conferida.anterior || (0, hitl_ingress_receipt_1.instanteDoIngresso)(raiz, id, pedidoId, r))
+        return;
+    const pendente = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id)).some(e => e.tipo === 'session_answer_sending' && e.pedidoId === pedidoId);
+    if (!pendente)
+        (0, hitl_ingress_receipt_1.gravarIngresso)(raiz, id, pedidoId, r, quando);
+}
+function responderGate(raiz, id, pedidoId, r, quando, assinado) {
+    receberResposta(raiz, id, pedidoId, r, quando, assinado);
+    const resultado = comLockHitl(raiz, id, () => {
+        const { pedido, anterior, opcao } = conferirResposta(raiz, id, pedidoId, r, quando, assinado);
+        if (pedido.alvo.tipo !== 'gate')
+            throw new Error('pedido destina-se à sessão, não ao gate');
+        if (anterior)
+            return { ok: true, pedidoId, estado: String(anterior.estado), repetida: true, evento: anterior };
+        const evidencia = (0, hitl_ingress_receipt_1.evidenciaDoIngresso)(raiz, id, pedidoId, r);
+        const veredito = registrarVereditoGate(raiz, id, pedido, opcao, {
+            ...dadosDaResposta(pedido, r), source: 'human', evidencia: evidencia.arquivo, evidenciaSha256: evidencia.sha256,
+            // O caminho que o numero da pergunta percorreu ate este pedido, para a auditoria refazer.
+            ...(assinado ? { enderecoAssinado: { alvo: assinado.alvo, endereco: assinado.endereco, ...assinado.rastro } } : {}),
+        });
+        return { ok: true, pedidoId, estado: String(veredito.estado), repetida: false, evento: veredito };
+    });
+    if (resultado.repetida || resultado.estado !== 'aprovado') {
+        const { evento: _evento, ...publico } = resultado;
+        return publico;
+    }
+    const publicacaoMemoria = (0, memoria_humana_1.publicarAprovacaoHumana)(raiz, id, resultado.evento);
+    const { evento: _evento, ...publico } = resultado;
+    return { ...publico, publicacaoMemoria };
+}
+/** Transição única para ambos os ingressos: reconhecer escalação não libera policy. */
+function registrarVereditoGate(raiz, id, pedido, opcao, proveniencia) {
+    return (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, id), id, 'human_gate', { ...proveniencia, ...(0, hitl_contract_1.vereditoDoGate)(pedido, opcao) });
+}
+/** Não aceita envelope JSON: o servidor fornece capacidade local de uso único. */
+function responderGateLocal(raiz, id, pedidoId, token) {
+    const atestado = (0, hitl_local_atestado_1.consumirAtestadoLocal)(token, raiz, id, pedidoId);
+    const resultado = comLockHitl(raiz, id, () => {
+        const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+        const anterior = eventos.find(e => e.tipo === 'human_gate' && e.pedidoId === pedidoId);
+        if (anterior)
+            return { ok: true, pedidoId, estado: String(anterior.estado), repetida: true };
+        (0, hitl_canais_1.conferirCanalSelecionado)(eventos, pedidoId, atestado.host, 'mcp-local', atestado.connectionId, atestado.requestId);
+        const evento = eventos.find(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedidoId);
+        (0, hitl_contract_1.validarPedidoHitl)(evento?.pedido);
+        const pedido = evento.pedido;
+        if (pedido.thread !== id || evento.contexto !== atestado.contexto || contextoHitl(raiz, id) !== atestado.contexto ||
+            (0, hitl_local_atestado_1.hashPedidoLocal)(pedido) !== atestado.pedidoSha256)
+            throw new Error('hitl.local.pedido-antigo');
+        const opcao = (0, hitl_contract_1.validarRespostaHitl)(pedido, atestado.opcao);
+        const evidencia = (0, hitl_local_receipt_1.gravarEvidenciaLocal)(atestado, (0, hitl_contract_1.vereditoDoGate)(pedido, opcao));
+        const veredito = registrarVereditoGate(raiz, id, pedido, opcao, {
+            contrato: pedido.contrato, pedidoId, fase: pedido.fase, origem: 'mcp-local', source: 'human',
+            proveniencia: 'ork.mcp-elicitation/v1',
+            // D12: os quatro canais gravam `canal`; aqui ele vem da conexão, não de argumento.
+            canal: atestado.host, contratoResposta: 'ork.mcp-elicitation/v1',
+            autorizadoPor: `mcp-local:${atestado.host}`, conexao: atestado.connectionId, solicitacao: atestado.requestId,
+            contexto: atestado.contexto, pedidoSha256: atestado.pedidoSha256,
+            recebidoEm: atestado.recebidoEm, recibo: evidencia.recibo,
+            evidencia: evidencia.arquivo, evidenciaSha256: evidencia.sha256,
+        });
+        return { ok: true, pedidoId, estado: String(veredito.estado), repetida: false, evento: veredito };
+    });
+    const evento = 'evento' in resultado ? resultado.evento : undefined;
+    const { evento: _evento, ...publico } = resultado;
+    if (resultado.repetida || resultado.estado !== 'aprovado' || !evento)
+        return publico;
+    const publicacaoMemoria = (0, memoria_humana_1.publicarAprovacaoHumana)(raiz, id, evento);
+    return { ...publico, publicacaoMemoria };
+}
+/** Stdin contém um envelope assinado pelo ingresso; argv só carrega identificadores. */
+function lerRespostaStdin(meta) {
+    const partes = [];
+    let total = 0;
+    while (true) {
+        const buf = Buffer.alloc(4096), n = fs.readSync(0, buf, 0, buf.length, null);
+        if (!n)
+            break;
+        total += n;
+        if (total > 32768)
+            throw new Error('envelope HITL excede limite');
+        partes.push(buf.subarray(0, n));
+    }
+    let r;
+    try {
+        r = JSON.parse(Buffer.concat(partes).toString('utf8'));
+    }
+    catch {
+        throw new Error('ingresso autenticado exige envelope JSON em stdin');
+    }
+    // D12: o canal tambem e proveniencia. Envelope que declara canal sem `--canal` em argv,
+    // ou com canal diferente, e recusado antes de qualquer conferencia de assinatura.
+    if (!r || r.por !== meta.por || r.mensagem !== meta.mensagem || r.origem !== meta.origem ||
+        (r.canal ?? undefined) !== (meta.canal ?? undefined) ||
+        (r.conta ?? undefined) !== (meta.conta ?? undefined))
+        throw new Error('proveniência em argv diverge do envelope');
+    return r;
+}