@orkastery/cli 0.2.0 → 0.3.0

package/dist/hitl-sessions.js

@@ -0,0 +1,475 @@
+"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.abrirPedidoSessao = abrirPedidoSessao;
+exports.responderSessao = responderSessao;
+exports.responderSessaoLocal = responderSessaoLocal;
+exports.reconciliarEnvioDeSessao = reconciliarEnvioDeSessao;
+exports.controleNativo = controleNativo;
+exports.superarSessao = superarSessao;
+const fs = __importStar(require("node:fs"));
+const codex_controller_1 = require("./adapters/codex-controller");
+/** D4/D19: nenhuma sessão é encerrada por prefixo, nome, PID inferido ou mera ausência. */
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const claude_bg_1 = require("./adapters/claude-bg");
+const thread_1 = require("./thread");
+const ledger_1 = require("./ledger");
+const util_1 = require("./util");
+const hitl_gates_1 = require("./hitl-gates");
+const hitl_contract_1 = require("./hitl-contract");
+const hitl_local_atestado_1 = require("./hitl-local-atestado");
+const hitl_local_receipt_1 = require("./hitl-local-receipt");
+const hitl_ingress_receipt_1 = require("./hitl-ingress-receipt");
+const hitl_1 = require("./hitl");
+const hitl_canais_1 = require("./hitl-canais");
+const codex_question_1 = require("./adapters/codex-question");
+const uuidCompleto = (s) => /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(s);
+const reciboDaProva = (r) => (0, node_crypto_1.createHash)('sha256').update(r.prova).digest('hex');
+const mesmaInstancia = (a, b) => a.sessionId === b.sessionId && a.runtime === b.runtime && a.cwd === b.cwd && a.instancia === b.instancia;
+function controleDeResposta(raiz, id, sessionId, runtime, controle) {
+    const ctl = controle ?? controleNativo(runtime, raiz, id, sessionId);
+    if (!ctl.enviar || !ctl.confirmar)
+        throw new Error('runtime.unavailable: adapter não comprova entrada e recibo na mesma sessão; attach/resume não são fallback');
+    return ctl;
+}
+function observarBloqueio(ctl, sessionId, runtime, cwd) {
+    const consulta = ctl.consultar();
+    if (!consulta.ok)
+        throw new Error('runtime.unavailable: consulta falhou; sessão preservada');
+    const matches = consulta.sessoes.filter(s => s.sessionId === sessionId);
+    const s = matches[0];
+    if (matches.length !== 1 || !s || s.runtime !== runtime || s.cwd !== cwd || s.estado !== 'blocked' ||
+        !s.instancia || !s.bloqueio)
+        throw new Error('runtime.unavailable: identidade, cwd e prompt bloqueado exatos não comprovados');
+    return { sessionId: s.sessionId, runtime: s.runtime, cwd: s.cwd, estado: s.estado, instancia: s.instancia, bloqueio: s.bloqueio, perguntaNativa: s.perguntaNativa };
+}
+/** Cria somente um pedido vinculado ao despacho corrente e ao prompt nativo observado. */
+function abrirPedidoSessao(raiz, id, sessionId, opcoes, controle) {
+    return (0, hitl_gates_1.comLockHitl)(raiz, id, () => {
+        if (!uuidCompleto(sessionId))
+            throw new Error('identidade exige UUID completo');
+        const t = (0, thread_1.lerThread)(raiz, id), dir = (0, thread_1.dirThread)(raiz, id), eventos = (0, ledger_1.lerLedger)(dir);
+        const d = eventos.filter(e => e.tipo === 'phase_dispatch').at(-1);
+        if (t.status !== 'aberta' || t.faseAtual !== opcoes.fase || !t.sessoes.some(s => s.sessionId === sessionId && s.fase === opcoes.fase && s.runtime === opcoes.runtime && s.verificada) ||
+            d?.sessionId !== sessionId || d?.fase !== opcoes.fase || d?.runtime !== opcoes.runtime ||
+            !eventos.some(e => e.tipo === 'phase_dispatch_verified' && e.sessionId === sessionId && e.encontrada === true)) {
+            throw new Error('sessão não corresponde ao despacho corrente verificado da thread/fase/runtime');
+        }
+        const ctl = controleDeResposta(raiz, id, sessionId, opcoes.runtime, controle), cwd = path.resolve(t.worktree ?? raiz);
+        const sessao = observarBloqueio(ctl, sessionId, opcoes.runtime, cwd);
+        const revalidada = observarBloqueio(ctl, sessionId, opcoes.runtime, cwd);
+        if (!mesmaInstancia(sessao, revalidada) || sessao.bloqueio !== revalidada.bloqueio)
+            throw new Error('prompt ou instância mudou durante o pedido');
+        const nativa = sessao.perguntaNativa;
+        if (!nativa || JSON.stringify(nativa) !== JSON.stringify(revalidada.perguntaNativa) ||
+            (0, codex_question_1.projetarPergunta)({ isBlocking: true, questions: [nativa] }).sha256 !== nativa.sha256)
+            throw new Error('runtime.unavailable: conteúdo nativo da pergunta não comprovado');
+        if (opcoes.pergunta !== undefined && opcoes.pergunta !== nativa.question)
+            throw new Error('pergunta do operador diverge do conteúdo nativo; consentimento recusado');
+        const escolhas = nativa.options.map((o, i) => ({ numero: i + 1, texto: `${o.label} — ${o.description}`, acao: 'responder' }));
+        if ((0, hitl_1.redigirSegredos)(nativa.question) !== nativa.question || escolhas.some(o => o.texto.length > 200 || (0, hitl_1.redigirSegredos)(o.texto) !== o.texto))
+            throw new Error('runtime.unavailable: conteúdo nativo não pode ser publicado integralmente neste canal');
+        const contexto = (0, hitl_gates_1.contextoHitl)(raiz, id);
+        const existente = eventos.find(e => e.tipo === 'hitl_requested' && e.contexto === contexto &&
+            e.sessao?.sessionId === sessionId &&
+            e.sessao.instancia === sessao.instancia && e.sessao.bloqueio === sessao.bloqueio);
+        if (existente) {
+            const p = existente.pedido;
+            (0, hitl_contract_1.validarPedidoHitl)(p);
+            if (p.pergunta !== nativa.question || opcoes.prazo && p.prazo !== opcoes.prazo)
+                throw new Error('prompt já tem pedido; conteúdo divergente recusado');
+            return p; // inclusive expirado/respondido: não cria novo envio para o mesmo prompt
+        }
+        const quando = opcoes.quando ?? new Date().toISOString();
+        // O tipo aceito decide o que o canal orienta E o que o receptor recebe: uma coisa só.
+        const tipoAceito = escolhas.length && !nativa.isOther ? 'opcao' : 'texto';
+        // I-41 (T4d): a pergunta de SESSAO continua em `ork.hitl/v1`, e a razao e dura.
+        //
+        // O PLAN previa mover os dois emissores para v2. O gate deu certo porque as tres opcoes sao
+        // NOSSAS e a recomendada sai de fato registrado no ledger. Aqui nao: a pergunta e as opcoes
+        // vem do HOST, pelo prompt nativo. O v2 exige de 2 a 4 alternativas e EXATAMENTE UMA
+        // recomendada com o porque; uma pergunta nativa de texto livre nao tem alternativa nenhuma,
+        // uma com sete opcoes nao cabe em a-d, e o nucleo nao tem base para eleger a melhor entre
+        // opcoes que ele nao escreveu. Emitir v2 aqui exigiria inventar uma recomendada no chute,
+        // que e exatamente o defeito que esta thread existe para consertar; a alternativa seria
+        // recusar perguntas de sessao legitimas. v1 continua lido para sempre, e e o contrato certo
+        // para um conteudo que nao e nosso. Uma pergunta aberta tambem nao pertence a camada 2, que
+        // e de perguntas objetivas de cinco em cinco.
+        const pedido = { contrato: 'ork.hitl/v1', id: (0, node_crypto_1.randomUUID)(), thread: id, fase: opcoes.fase,
+            modo: t.modo, alvo: { tipo: 'session', sessionId, runtime: opcoes.runtime }, motivo: 'hitl.pergunta',
+            pergunta: nativa.question, opcoes: escolhas, recomendacao: orientacaoDaResposta(tipoAceito, escolhas.length),
+            criadoEm: quando, prazo: opcoes.prazo ?? new Date(Date.parse(quando) + 3600000).toISOString(),
+            acaoPadraoAoExpirar: 'esperar', respostaAceita: { tipo: tipoAceito, maxCaracteres: 4096 }, profundidade: (0, hitl_contract_1.profundidadeDoModo)(t.modo) };
+        (0, hitl_contract_1.validarPedidoHitl)(pedido);
+        (0, ledger_1.registrar)(dir, id, 'hitl_requested', { fase: pedido.fase, pedido, contexto, sessao,
+            evidencia: 'duas consultas do adapter concordam com despacho, instância, cwd e prompt bloqueado' });
+        return pedido;
+    });
+}
+/**
+ * A orientação do canal diz exatamente o que o receptor vai receber, e nada além disso.
+ * Quando a pergunta nativa aceita texto, um número digitado continua sendo esse texto.
+ */
+function orientacaoDaResposta(tipo, quantasOpcoes) {
+    const fecho = 'A resposta não aprova gates do bloco.';
+    if (tipo === 'opcao')
+        return `Responda com o número de uma das ${quantasOpcoes} opções desta sessão; o receptor recebe o rótulo nativo correspondente. ${fecho}`;
+    const contexto = quantasOpcoes
+        ? ` As opções listadas são o conteúdo nativo da pergunta, não um seletor: digitar um número envia esse número.`
+        : '';
+    return `Esta pergunta aceita texto livre: o receptor recebe a sua resposta literal, inclusive quando ela for um número.${contexto} ${fecho}`;
+}
+/**
+ * O núcleo da entrega, comum aos quatro canais: conferência do vínculo nativo, reserva
+ * durável, envio único e confirmação correlacionada. Nenhum canal ganha atalho aqui.
+ */
+function entregarNaSessao(raiz, id, pedido, prov, controle) {
+    if (pedido.alvo.tipo !== 'session')
+        throw new Error('pedido destina-se ao gate, não à sessão');
+    const pedidoId = pedido.id;
+    const { sessionId, runtime } = pedido.alvo;
+    const resultado = { ok: true, pedidoId, sessionId, estado: 'entregue' };
+    const dir = (0, thread_1.dirThread)(raiz, id), eventos = (0, ledger_1.lerLedger)(dir);
+    const solicitado = eventos.find(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedidoId);
+    const sessao = solicitado?.sessao;
+    if (!sessao || !uuidCompleto(sessionId) || sessao.sessionId !== sessionId || sessao.runtime !== runtime ||
+        !sessao.instancia || !sessao.bloqueio || sessao.cwd !== path.resolve((0, thread_1.lerThread)(raiz, id).worktree ?? raiz)) {
+        throw new Error('runtime.unavailable: pedido sem vínculo nativo exato');
+    }
+    const ctl = controleDeResposta(raiz, id, sessionId, runtime, controle);
+    const pendente = eventos.find(e => e.tipo === 'session_answer_sending' && e.pedidoId === pedidoId);
+    if (pendente && (pendente.recibo !== prov.recibo || pendente.mensagem !== prov.mensagem || pendente.autorizadoPor !== prov.autorizadoPor)) {
+        throw new Error('envio já iniciado; resposta divergente recusada');
+    }
+    if (eventos.some(e => e.tipo === 'session_answer_sending' && e.pedidoId !== pedidoId && e.mensagem === prov.mensagem)) {
+        throw new Error('mensagem já reservada para outro pedido');
+    }
+    const entrega = { contrato: 'ork.session-answer/v1',
+        envioId: pendente ? String(pendente.envioId) : (0, node_crypto_1.randomUUID)(), pedidoId, thread: id, fase: pedido.fase, sessao, recibo: prov.recibo };
+    if (!pendente) {
+        for (let i = 0; i < 2; i++) {
+            const atual = observarBloqueio(ctl, sessionId, runtime, sessao.cwd);
+            if (!mesmaInstancia(atual, sessao) || atual.bloqueio !== sessao.bloqueio || JSON.stringify(atual.perguntaNativa) !== JSON.stringify(sessao.perguntaNativa))
+                throw new Error('prompt ou instância mudou antes do envio');
+        }
+        (0, ledger_1.registrar)(dir, id, 'session_answer_sending', { ...prov.dados, sessionId, runtime,
+            instancia: sessao.instancia, bloqueio: sessao.bloqueio, envioId: entrega.envioId });
+        // O número só vira rótulo nativo quando o pedido aceita OPÇÃO. Em texto livre a
+        // resposta humana chega literal ao receptor, inclusive quando é "1" ou "12".
+        const numero = pedido.respostaAceita.tipo === 'opcao' && /^(?:[1-9]|1[0-2])$/.test(prov.resposta.trim())
+            ? Number(prov.resposta.trim()) - 1 : -1;
+        const respostaNativa = (numero < 0 ? undefined : sessao.perguntaNativa?.options[numero]?.label) ?? prov.resposta;
+        try {
+            ctl.enviar({ ...entrega, resposta: respostaNativa });
+        }
+        catch {
+            throw new Error('runtime.unavailable: resultado do envio incerto; não reenviar; consultar recibo do controller');
+        }
+    }
+    let ack;
+    try {
+        ack = ctl.confirmar(entrega);
+    }
+    catch {
+        throw new Error('runtime.unavailable: consulta do recibo falhou; envio não será repetido');
+    }
+    if (!ack || ack.estado !== 'recebida' || ack.contrato !== entrega.contrato || ack.envioId !== entrega.envioId ||
+        ack.pedidoId !== pedidoId || ack.thread !== id || ack.fase !== pedido.fase || ack.recibo !== entrega.recibo ||
+        !ack.sessao || !mesmaInstancia(ack.sessao, sessao) || ack.sessao.bloqueio !== sessao.bloqueio) {
+        throw new Error('runtime.unavailable: receptor não confirmou recebimento correlacionado na mesma sessão; não reenviar');
+    }
+    const evidencia = prov.evidenciar?.({ ...entrega, sessao });
+    (0, ledger_1.registrar)(dir, id, 'session_answered', { ...prov.dados, sessionId, runtime,
+        instancia: sessao.instancia, bloqueio: sessao.bloqueio, envioId: entrega.envioId, estado: 'entregue',
+        ...(evidencia ? { evidencia: evidencia.arquivo, evidenciaSha256: evidencia.sha256, recibo: evidencia.recibo } : {
+            evidencia: 'recibo do controller confirma envioId, pedido, thread/fase, UUID, instância, cwd, prompt e envelope'
+        }) });
+    return { ...resultado, repetida: !!pendente };
+}
+/** Uma intenção durável impede reenvio após crash, timeout ou confirmação divergente. */
+function responderSessao(raiz, id, pedidoId, r, controle, quando) {
+    (0, hitl_gates_1.receberResposta)(raiz, id, pedidoId, r, quando);
+    return (0, hitl_gates_1.comLockHitl)(raiz, id, () => {
+        const { pedido, anterior } = (0, hitl_gates_1.conferirResposta)(raiz, id, pedidoId, r, quando);
+        if (pedido.alvo.tipo !== 'session')
+            throw new Error('pedido destina-se ao gate, não à sessão');
+        if (anterior)
+            return { ok: true, pedidoId, sessionId: pedido.alvo.sessionId, estado: 'entregue', repetida: true };
+        return entregarNaSessao(raiz, id, pedido, { dados: (0, hitl_gates_1.dadosDaResposta)(pedido, r), resposta: r.resposta,
+            recibo: reciboDaProva(r), mensagem: r.mensagem, autorizadoPor: r.por,
+            // FX4: o ingresso duravel ja foi gravado e autenticado por `receberResposta`. Sem
+            // referencia-lo no `session_answered`, a prova existia em disco e nao chegava ao
+            // recibo: metade do HITL ficava com a palavra do controller e nada mais.
+            evidenciar: () => ({ ...(0, hitl_ingress_receipt_1.evidenciaDoIngresso)(raiz, id, pedidoId, r), recibo: reciboDaProva(r) }) }, controle);
+    });
+}
+/**
+ * D12: responder a pergunta nativa de uma sessão pelo canal MCP local.
+ *
+ * O HITL do Orkastery não é só gate de fase. Uma sessão bloqueada numa pergunta nativa é
+ * HITL igual, e antes desta função ela só podia ser respondida pelo Telegram: Codex e
+ * Claude Code tinham `mcp-local` para decidir bloco e não tinham para responder à própria
+ * sessão que o dono estava olhando. O canal, a correlação e o recibo vêm da CONEXÃO, nunca
+ * de argumento de ferramenta: é isso que impede o agente de responder por quem pediu.
+ *
+ * Aceita texto livre quando a pergunta nativa aceita, porque uma pergunta aberta respondida
+ * por menu vira outra pergunta.
+ */
+function responderSessaoLocal(raiz, id, pedidoId, token, controle) {
+    const atestado = (0, hitl_local_atestado_1.consumirAtestadoLocal)(token, raiz, id, pedidoId);
+    return (0, hitl_gates_1.comLockHitl)(raiz, id, () => {
+        const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+        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 || pedido.alvo.tipo !== 'session')
+            throw new Error('hitl.local.somente-sessoes');
+        const anterior = eventos.find(e => e.tipo === 'session_answered' && e.pedidoId === pedidoId);
+        if (anterior)
+            return { ok: true, pedidoId, sessionId: pedido.alvo.sessionId, estado: 'entregue', repetida: true };
+        (0, hitl_canais_1.conferirCanalSelecionado)(eventos, pedidoId, atestado.host, 'mcp-local', atestado.connectionId, atestado.requestId);
+        if (evento.contexto !== atestado.contexto || (0, hitl_gates_1.contextoHitl)(raiz, id) !== atestado.contexto ||
+            (0, hitl_local_atestado_1.hashPedidoLocal)(pedido) !== atestado.pedidoSha256)
+            throw new Error('hitl.local.pedido-antigo');
+        // Opção numerada continua sendo conferida contra o pedido; texto livre passa pelo
+        // mesmo limite de tamanho. Em nenhum dos dois casos o corpo é gravado.
+        (0, hitl_contract_1.validarRespostaHitl)(pedido, atestado.opcao);
+        const identidade = `mcp-local:${atestado.connectionId}:${atestado.requestId}`;
+        const dados = { contrato: pedido.contrato, pedidoId, fase: pedido.fase, origem: 'mcp-local',
+            source: 'human', proveniencia: 'ork.mcp-elicitation/v1',
+            canal: atestado.host, contratoResposta: 'ork.hitl-local-session/v1',
+            autorizadoPor: `mcp-local:${atestado.host}`, conexao: atestado.connectionId,
+            solicitacao: atestado.requestId, contexto: atestado.contexto, pedidoSha256: atestado.pedidoSha256,
+            recebidoEm: atestado.recebidoEm, mensagem: identidade,
+            // Amarra conteudo: o recibo que o controller confirmou deriva do hash da resposta.
+            reciboEntrega: (0, hitl_local_atestado_1.reciboDoAtestado)(atestado) };
+        return entregarNaSessao(raiz, id, pedido, {
+            dados, resposta: atestado.opcao, mensagem: identidade,
+            autorizadoPor: `mcp-local:${atestado.host}`,
+            // O recibo que o controller confirma amarra o CONTEUDO, nao so a conexao.
+            recibo: (0, hitl_local_atestado_1.reciboDoAtestado)(atestado),
+            evidenciar: (entrega) => (0, hitl_local_receipt_1.gravarEvidenciaLocalSessao)(atestado, { fase: String(pedido.fase),
+                sessionId: entrega.sessao.sessionId, runtime: entrega.sessao.runtime,
+                instancia: entrega.sessao.instancia, bloqueio: String(entrega.sessao.bloqueio), envioId: entrega.envioId }),
+        }, controle);
+    });
+}
+/**
+ * FX3: reconciliar um `session_answer_sending` orfao, sem o envelope original.
+ *
+ * O buraco que C-CHECK3 nomeou: a reserva duravel guardava `sha(prova)`, nunca a `prova`.
+ * Isso esta certo e continua assim. O problema era outro: o UNICO caminho que fechava um
+ * envio pendente exigia que o MESMO chamador reapresentasse a `RespostaHumana` inteira. Se
+ * o processo que originou o envio morresse com o `r` so na memoria, o pendente ficava para
+ * sempre: nao dava para confirmar, nem para saber se o receptor recebeu, e qualquer
+ * tentativa nova batia em "envio ja iniciado; resposta divergente recusada".
+ *
+ * Aqui a reconciliacao usa apenas o que ESTA no ledger: `envioId`, `recibo`, `mensagem`,
+ * `autorizadoPor` e o vinculo nativo do pedido. Com isso ela reconstroi a entrega e pergunta
+ * ao receptor, pelo recibo correlacionado, se ele recebeu aquele `envioId`. Ela NUNCA envia
+ * nada: reenviar as cegas e justamente o que a reserva duravel existe para impedir.
+ *
+ * Nao existe desfecho "cancelado". Nada observavel prova que o receptor NAO recebeu, e
+ * inventar essa prova seria o oposto do que este nucleo faz. Sem confirmacao, o pendente
+ * continua pendente, e a proxima chamada tenta de novo, sem efeito acumulado.
+ */
+function reconciliarEnvioDeSessao(raiz, id, pedidoId, controle) {
+    return (0, hitl_gates_1.comLockHitl)(raiz, id, () => {
+        const dir = (0, thread_1.dirThread)(raiz, id), eventos = (0, ledger_1.lerLedger)(dir);
+        const solicitado = eventos.find(e => e.tipo === 'hitl_requested' && e.pedido?.id === pedidoId);
+        (0, hitl_contract_1.validarPedidoHitl)(solicitado?.pedido);
+        const pedido = solicitado.pedido;
+        if (pedido.thread !== id || pedido.alvo.tipo !== 'session')
+            throw new Error('hitl.sessao.pedido-nao-e-de-sessao');
+        const { sessionId, runtime } = pedido.alvo;
+        const respondido = eventos.find(e => e.tipo === 'session_answered' && e.pedidoId === pedidoId);
+        const pendente = eventos.find(e => e.tipo === 'session_answer_sending' && e.pedidoId === pedidoId);
+        if (!pendente)
+            throw new Error('hitl.sessao.sem-envio-pendente');
+        const envioId = String(pendente.envioId);
+        // Idempotencia: ja respondido nao reabre envio, nao consulta receptor e nao regrava.
+        if (respondido) {
+            return { ok: true, pedidoId, sessionId, envioId, estado: 'entregue', repetida: true,
+                prova: respondido.evidenciaSha256 ? 'ingresso-duravel' : 'recibo-do-controller' };
+        }
+        const sessao = solicitado.sessao;
+        if (!sessao || sessao.sessionId !== sessionId || sessao.runtime !== runtime || !sessao.instancia || !sessao.bloqueio ||
+            sessao.cwd !== path.resolve((0, thread_1.lerThread)(raiz, id).worktree ?? raiz)) {
+            throw new Error('runtime.unavailable: pedido sem vinculo nativo exato');
+        }
+        const ctl = controleDeResposta(raiz, id, sessionId, runtime, controle);
+        const entrega = { contrato: 'ork.session-answer/v1', envioId,
+            pedidoId, thread: id, fase: pedido.fase, sessao, recibo: String(pendente.recibo) };
+        let ack;
+        try {
+            ack = ctl.confirmar(entrega);
+        }
+        catch {
+            throw new Error('runtime.unavailable: consulta do recibo falhou; envio nao sera repetido');
+        }
+        const confirmado = !!ack && ack.estado === 'recebida' && ack.contrato === entrega.contrato &&
+            ack.envioId === envioId && ack.pedidoId === pedidoId && ack.thread === id && ack.fase === pedido.fase &&
+            ack.recibo === entrega.recibo && !!ack.sessao && mesmaInstancia(ack.sessao, sessao) &&
+            ack.sessao.bloqueio === sessao.bloqueio;
+        const { ts: _ts, thread: _thread, tipo: _tipo, eventId: _eventId, ...origem } = pendente;
+        if (!confirmado) {
+            (0, ledger_1.registrar)(dir, id, 'session_answer_reconciled', { pedidoId, fase: pedido.fase, sessionId, runtime, envioId,
+                estado: 'pendente', decididoPor: 'nucleo ork',
+                razao: 'receptor nao confirmou recebimento correlacionado; envio preservado e nunca repetido' });
+            return { ok: false, pedidoId, sessionId, envioId, estado: 'pendente', repetida: false, prova: 'nenhuma' };
+        }
+        // A evidencia duravel do canal, quando existe, e derivavel SO do ledger: o nome do
+        // arquivo sai de `mensagem`. FX10: derivar nao e provar. O evento que esta prestes a ser
+        // gravado passa pelo MESMO MAC que o sync exige, ANTES de existir no ledger. Sem isso um
+        // byte trocado no pendente (ou no proprio arquivo de ingresso) virava `session_answered`
+        // com etiqueta de prova duravel, e a mentira so aparecia dias depois, no sync.
+        const evidencia = evidenciaReconciliada(raiz, id, origem);
+        const candidato = { ...origem, estado: 'entregue', reconciliado: true, ...evidencia.dados };
+        if (evidencia.prova === 'sem-prova-duravel' ||
+            evidencia.prova === 'ingresso-duravel' && !(0, hitl_ingress_receipt_1.validarEvidenciaReconstruida)(raiz, id, candidato)) {
+            // Falha FECHADA: nenhuma resposta gravada, o pendente continua pendente e a recusa
+            // fica auditavel. Reconciliar de novo com o estado consertado ainda funciona.
+            (0, ledger_1.registrar)(dir, id, 'session_answer_reconciled', { pedidoId, fase: pedido.fase, sessionId, runtime, envioId,
+                estado: 'recusado', decididoPor: 'nucleo ork',
+                razao: evidencia.prova === 'sem-prova-duravel'
+                    ? 'envio por telegram sem ingresso duravel correspondente; nenhuma resposta foi gravada'
+                    : 'evidencia duravel reconstruida nao revalidou o MAC do canal; nenhuma resposta foi gravada' });
+            throw new Error('hitl.sessao.evidencia-duravel-invalida: envio pendente nao revalida; nada foi gravado');
+        }
+        (0, ledger_1.registrar)(dir, id, 'session_answer_reconciled', { pedidoId, fase: pedido.fase, sessionId, runtime, envioId,
+            estado: 'entregue', decididoPor: 'nucleo ork',
+            razao: 'recibo do controller confirmou envioId, pedido, thread/fase, instancia e prompt, e o MAC duravel revalidou' });
+        (0, ledger_1.registrar)(dir, id, 'session_answered', candidato);
+        return { ok: true, pedidoId, sessionId, envioId, estado: 'entregue', repetida: false, prova: evidencia.prova };
+    });
+}
+/** Referencia duravel reconstruida so com o que o ledger ja guardava do envio pendente. */
+function evidenciaReconciliada(raiz, id, origem) {
+    const mensagem = typeof origem.mensagem === 'string' ? origem.mensagem : '';
+    const nome = (0, node_crypto_1.createHash)('sha256').update(mensagem).digest('hex') + '.json';
+    const file = path.join((0, thread_1.dirThread)(raiz, id), 'hitl-ingress', nome);
+    if (origem.origem === 'telegram' || origem.origem === 'native') {
+        // FX10: um envio de telegram SEM ingresso duravel nao pode cair no recibo do controller.
+        // Esse desvio transformava o sumico do arquivo de prova em um caminho mais permissivo,
+        // que e exatamente o contrario do que apagar a prova deveria causar.
+        if (!mensagem || !fs.existsSync(file))
+            return { prova: 'sem-prova-duravel', dados: {} };
+        const bytes = fs.readFileSync(file, 'utf8');
+        return { prova: 'ingresso-duravel', dados: { evidencia: `.orkastery/threads/${id}/hitl-ingress/${nome}`,
+                evidenciaSha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex') } };
+    }
+    // O ingresso MCP local grava o recibo duravel DEPOIS da confirmacao, e o atestado de uso
+    // unico morreu com o processo. Reconciliar nao reemite esse recibo: diz, com nome, que a
+    // prova aqui e o recibo do controller, e nao uma evidencia duravel que ninguem assinou.
+    return { prova: 'recibo-do-controller', dados: { evidencia: 'reconciliacao: recibo do controller confirma envioId, pedido, thread/fase, instancia e prompt; evidencia duravel do ingresso nao foi reemitida' } };
+}
+function controleNativo(runtime, raiz, id, sessionId) {
+    if (runtime === 'codex') {
+        const t = (0, thread_1.lerThread)(raiz, id), sessao = t.sessoes.find(s => s.sessionId === sessionId && s.runtime === runtime);
+        const d = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id)).find(e => e.tipo === 'phase_dispatch' && e.sessionId === sessionId);
+        if (sessao?.controlador && d?.controlador === sessao.controlador && d.promptSha256 === sessao.promptSha256) {
+            const base = fs.realpathSync(path.join((0, thread_1.dirThread)(raiz, id), 'sessoes')) + path.sep;
+            const dir = fs.realpathSync(sessao.controlador);
+            if (!dir.startsWith(base))
+                throw new Error('runtime.unavailable: controller fora do despacho canônico');
+            return (0, codex_controller_1.controleDoController)(dir, { thread: id, fase: sessao.fase, promptSha256: sessao.promptSha256 }, sessionId, path.resolve(t.worktree ?? raiz));
+        }
+    }
+    if (runtime !== 'claude-bg') {
+        throw new Error('runtime.unavailable: Codex exige identidade de controller vinculada pelo adapter; nenhum PID será inferido ou sinalizado');
+    }
+    return {
+        consultar: () => {
+            const r = (0, claude_bg_1.consultarSessoes)(undefined, true);
+            return { ok: r.ok, sessoes: r.sessoes.map(s => ({ sessionId: s.sessionId, runtime, cwd: s.cwd ?? '',
+                    estado: s.state ?? s.status ?? '', instancia: s.id && Number.isFinite(s.startedAt) ? JSON.stringify([s.id, s.startedAt]) : '' })) };
+        },
+        parar: s => (0, util_1.exec)('claude', ['stop', s.sessionId], undefined, 10000).ok,
+    };
+}
+/** Somente despacho posterior verificado torna uma sessão da mesma fase superável. */
+function superarSobLock(raiz, id, sessionId, fase, runtime, controle) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(sessionId))
+        throw new Error('identidade exige UUID completo');
+    const t = (0, thread_1.lerThread)(raiz, id), dir = (0, thread_1.dirThread)(raiz, id), eventos = (0, ledger_1.lerLedger)(dir);
+    if (!t.sessoes.some(s => s.sessionId === sessionId && s.fase === fase && s.runtime === runtime)) {
+        throw new Error('sessão não pertence à thread/fase/runtime informados');
+    }
+    const despachos = eventos.filter(e => e.tipo === 'phase_dispatch');
+    const i = despachos.findIndex(e => e.sessionId === sessionId && e.fase === fase && e.runtime === runtime);
+    const posterior = despachos.slice(i + 1).find(e => e.sessionId !== sessionId && e.fase === fase &&
+        eventos.some(v => v.tipo === 'phase_dispatch_verified' && v.sessionId === e.sessionId && v.encontrada === true));
+    if (i < 0 || !posterior)
+        throw new Error('superação exige despacho posterior da mesma fase verificado no runtime');
+    const ctl = controle ?? controleNativo(runtime, raiz, id, sessionId);
+    const observar = () => {
+        const r = ctl.consultar();
+        if (!r.ok)
+            throw new Error('runtime.unavailable: consulta falhou; alerta e sessão preservados');
+        const matches = r.sessoes.filter(s => s.sessionId === sessionId);
+        if (matches.length > 1)
+            throw new Error('identidade ambígua no runtime');
+        return matches[0];
+    };
+    const antes = observar();
+    const recibo = eventos.filter(e => e.tipo === 'session_superseded' && e.sessionId === sessionId && e.fase === fase && e.runtime === runtime).at(-1);
+    const terminou = (s) => !s || ['stopped', 'done', 'completed', 'exited'].includes(s.estado);
+    if (recibo && terminou(antes))
+        return { ok: true, sessionId, repetida: true };
+    if (!antes || antes.estado !== 'blocked' || antes.runtime !== runtime || !antes.instancia || !antes.cwd ||
+        path.resolve(antes.cwd) !== path.resolve(t.worktree ?? raiz))
+        throw new Error('sessão bloqueada com identidade e cwd correspondentes não comprovada');
+    const revalidada = observar();
+    if (JSON.stringify(revalidada) !== JSON.stringify(antes))
+        throw new Error('identidade ou estado mudou antes do encerramento');
+    (0, ledger_1.registrar)(dir, id, 'session_superseding', { fase, sessionId, runtime, instancia: antes.instancia, cwd: antes.cwd,
+        superadaPor: posterior.sessionId, evidencia: 'duas consultas nativas concordam: mesma identidade, cwd e estado blocked',
+        decididoPor: 'núcleo ork', razao: 'despacho posterior da mesma fase verificado; não encerrar sessão trabalhando' });
+    if (!ctl.parar(antes))
+        throw new Error('runtime.unavailable: encerramento não confirmado; alerta preservado');
+    const depois = observar();
+    if (!terminou(depois) || depois && (depois.instancia !== antes.instancia || depois.cwd !== antes.cwd || depois.runtime !== runtime)) {
+        throw new Error('runtime.unavailable: observação posterior não confirma encerramento da mesma instância');
+    }
+    (0, ledger_1.registrar)(dir, id, 'session_superseded', { fase, sessionId, runtime, instancia: antes.instancia, cwd: antes.cwd,
+        confirmacao: depois?.estado ?? 'ausente',
+        superadaPor: posterior.sessionId, evidencia: depois ? `runtime confirmou ${depois.estado}` : 'consulta nativa bem-sucedida confirmou ausência após stop',
+        decididoPor: 'núcleo ork', razao: 'encerramento confirmado após comando oficial do runtime' });
+    return { ok: true, sessionId, repetida: false };
+}
+function superarSessao(raiz, id, sessionId, fase, runtime, controle) {
+    return (0, hitl_gates_1.comLockHitl)(raiz, id, () => superarSobLock(raiz, id, sessionId, fase, runtime, controle));
+}