@orkastery/cli 0.2.0 → 0.4.1

package/dist/hitl-local-receipt.js

@@ -0,0 +1,328 @@
+"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.gravarEvidenciaLocal = gravarEvidenciaLocal;
+exports.gravarEvidenciaLocalSessao = gravarEvidenciaLocalSessao;
+exports.validarEvidenciaLocalSessao = validarEvidenciaLocalSessao;
+exports.validarEvidenciaLocal = validarEvidenciaLocal;
+/** Recibo durável do callback MCP local, autenticado por chave fora das threads. */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const estado_thread_1 = require("./estado-thread");
+const thread_1 = require("./thread");
+const ledger_1 = require("./ledger");
+const hitl_contract_1 = require("./hitl-contract");
+const hitl_local_atestado_1 = require("./hitl-local-atestado");
+const sha = (v) => (0, node_crypto_1.createHash)('sha256').update(v).digest('hex');
+const uid = () => {
+    const atual = process.getuid?.();
+    if (atual === undefined)
+        throw new Error('hitl.local.evidencia-invalida');
+    return atual;
+};
+function validarDiretorio(file, modo) {
+    const st = fs.lstatSync(file);
+    if (!st.isDirectory() || st.isSymbolicLink() || st.uid !== uid() || (st.mode & 0o777) !== modo ||
+        fs.realpathSync(file) !== file)
+        throw new Error('hitl.local.evidencia-invalida');
+    return st;
+}
+function diretorioPrivado(file) {
+    try {
+        fs.mkdirSync(file, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+    }
+    return validarDiretorio(file, 0o700);
+}
+function chaveLocal(raiz, criar) {
+    const estado = path.join((0, estado_thread_1.raizDoEstado)(raiz), '.orkastery');
+    const stEstado = fs.lstatSync(estado);
+    if (!stEstado.isDirectory() || stEstado.isSymbolicLink() || fs.realpathSync(estado) !== estado) {
+        throw new Error('hitl.local.chave-invalida');
+    }
+    const pasta = path.join(estado, 'private');
+    const pastaSt = criar ? diretorioPrivado(pasta) : validarDiretorio(pasta, 0o700);
+    const dfd = fs.openSync(pasta, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    const file = `/proc/self/fd/${dfd}/hitl-local-signing.key`;
+    try {
+        if (criar) {
+            const temp = `/proc/self/fd/${dfd}/.${(0, node_crypto_1.randomUUID)()}.tmp`;
+            try {
+                const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+                    fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+                try {
+                    fs.writeFileSync(fd, (0, node_crypto_1.randomBytes)(32).toString('hex') + '\n');
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                try {
+                    fs.linkSync(temp, file);
+                }
+                catch (e) {
+                    if (e.code !== 'EEXIST')
+                        throw e;
+                }
+                finally {
+                    fs.unlinkSync(temp);
+                }
+                fs.fsyncSync(dfd);
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+        }
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const st = fs.fstatSync(fd), atual = fs.lstatSync(pasta);
+            if (!st.isFile() || st.nlink !== 1 || st.uid !== uid() || (st.mode & 0o777) !== 0o600 ||
+                atual.dev !== pastaSt.dev || atual.ino !== pastaSt.ino)
+                throw new Error('hitl.local.chave-invalida');
+            const raw = fs.readFileSync(fd, 'utf8');
+            if (!/^[a-f0-9]{64}\n$/.test(raw))
+                throw new Error('hitl.local.chave-invalida');
+            return Buffer.from(raw.trim(), 'hex');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    finally {
+        fs.closeSync(dfd);
+    }
+}
+const assinatura = (chave, dados) => (0, node_crypto_1.createHmac)('sha256', chave).update(JSON.stringify(dados)).digest('hex');
+function referencia(thread, nome) {
+    return `.orkastery/threads/${thread}/hitl-ingress-local/${nome}`;
+}
+function lerRecibo(raiz, thread, nome) {
+    const pasta = path.join((0, thread_1.dirThread)(raiz, thread), 'hitl-ingress-local');
+    const pastaSt = validarDiretorio(pasta, 0o700);
+    const dfd = fs.openSync(pasta, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        const fd = fs.openSync(`/proc/self/fd/${dfd}/${nome}`, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const st = fs.fstatSync(fd), atual = fs.lstatSync(pasta);
+            if (!st.isFile() || st.nlink !== 1 || st.uid !== uid() || (st.mode & 0o777) !== 0o600 ||
+                atual.dev !== pastaSt.dev || atual.ino !== pastaSt.ino)
+                throw new Error('hitl.local.evidencia-invalida');
+            const bytes = fs.readFileSync(fd);
+            const recibo = JSON.parse(bytes.toString('utf8'));
+            if (!recibo.dados || !/^[a-f0-9]{64}$/.test(recibo.assinatura ?? '') ||
+                Object.keys(recibo).sort().join(',') !== 'assinatura,dados')
+                throw new Error('hitl.local.evidencia-invalida');
+            return { bytes, dados: recibo.dados, assinatura: recibo.assinatura };
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    finally {
+        fs.closeSync(dfd);
+    }
+}
+/** O nome do recibo e determinado pela conexao e pela solicitacao, nunca pelo conteudo. */
+const nomeDoRecibo = (a) => sha(JSON.stringify([a.connectionId, a.requestId])) + '.json';
+/**
+ * Escrita atomica e conferida do recibo assinado. Extraida porque gate e sessao gravam a
+ * mesma coisa em lugares diferentes do contrato: duplicar aqui seria duplicar o cofre.
+ */
+function gravarRecibo(raiz, thread, nome, dados) {
+    const chave = chaveLocal(raiz, true);
+    const pasta = path.join((0, thread_1.dirThread)(raiz, thread), 'hitl-ingress-local');
+    const pastaSt = diretorioPrivado(pasta);
+    const sig = assinatura(chave, dados), bytes = Buffer.from(JSON.stringify({ dados, assinatura: sig }) + '\n');
+    const dfd = fs.openSync(pasta, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        const file = `/proc/self/fd/${dfd}/${nome}`;
+        const temp = `/proc/self/fd/${dfd}/.${(0, node_crypto_1.randomUUID)()}.tmp`;
+        try {
+            const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+                fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            try {
+                fs.writeFileSync(fd, bytes);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            try {
+                fs.linkSync(temp, file);
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+            finally {
+                fs.unlinkSync(temp);
+            }
+            fs.fsyncSync(dfd);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        const atual = fs.lstatSync(pasta);
+        if (atual.dev !== pastaSt.dev || atual.ino !== pastaSt.ino)
+            throw new Error('hitl.local.evidencia-invalida');
+    }
+    finally {
+        fs.closeSync(dfd);
+    }
+    const lido = lerRecibo(raiz, thread, nome);
+    if (!lido.bytes.equals(bytes))
+        throw new Error('hitl.local.evidencia-invalida');
+    return { arquivo: referencia(thread, nome), sha256: sha(bytes), recibo: sha(sig) };
+}
+/** Persiste a decisão normalizada que já entra no ledger; nunca o texto bruto respondido. */
+function gravarEvidenciaLocal(atestado, veredito) {
+    const dados = { contrato: 'ork.hitl-local-ingress/v1', thread: atestado.thread,
+        pedidoId: atestado.pedidoId, contexto: atestado.contexto, pedidoSha256: atestado.pedidoSha256,
+        host: atestado.host, connectionId: atestado.connectionId, requestId: atestado.requestId,
+        recebidoEm: atestado.recebidoEm, ...veredito };
+    return gravarRecibo(atestado.raiz, atestado.thread, nomeDoRecibo(atestado), dados);
+}
+function gravarEvidenciaLocalSessao(atestado, entrega) {
+    const dados = { contrato: 'ork.hitl-local-session/v1', thread: atestado.thread,
+        pedidoId: atestado.pedidoId, contexto: atestado.contexto, pedidoSha256: atestado.pedidoSha256,
+        host: atestado.host, connectionId: atestado.connectionId, requestId: atestado.requestId,
+        recebidoEm: atestado.recebidoEm, ...entrega, estado: 'entregue', respostaSha256: sha(atestado.opcao),
+        reciboEntrega: (0, hitl_local_atestado_1.reciboDoMaterial)(atestado.connectionId, atestado.requestId, atestado.pedidoSha256, sha(atestado.opcao)) };
+    return gravarRecibo(atestado.raiz, atestado.thread, nomeDoRecibo(atestado), dados);
+}
+/** Revalida no sync o recibo de uma resposta de sessao entregue pelo canal MCP local. */
+function validarEvidenciaLocalSessao(raiz, thread, evento) {
+    try {
+        if (evento.tipo !== 'session_answered' || evento.origem !== 'mcp-local' ||
+            !['mcp-local:codex', 'mcp-local:claude-code'].includes(String(evento.autorizadoPor)) ||
+            typeof evento.pedidoId !== 'string' || typeof evento.contexto !== 'string' ||
+            typeof evento.pedidoSha256 !== 'string' || typeof evento.conexao !== 'string' ||
+            typeof evento.solicitacao !== 'string' || typeof evento.recebidoEm !== 'string' ||
+            typeof evento.envioId !== 'string' || typeof evento.evidencia !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(String(evento.evidenciaSha256 ?? '')))
+            return false;
+        const host = String(evento.autorizadoPor).slice('mcp-local:'.length);
+        // `canal` e `contratoResposta` sao campos publicos do evento: se nao forem conferidos
+        // contra o host que assinou, da para adulterar o canal do recibo sem reprovar nada.
+        if (evento.canal !== host || evento.contratoResposta !== 'ork.hitl-local-session/v1')
+            return false;
+        const nome = sha(JSON.stringify([evento.conexao, evento.solicitacao])) + '.json';
+        if (evento.evidencia !== referencia(thread, nome))
+            return false;
+        const lido = lerRecibo(raiz, thread, nome);
+        const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, thread));
+        const solicitados = eventos.filter(e => e.tipo === 'hitl_requested' && e.pedido?.id === evento.pedidoId);
+        const respostas = eventos.filter(e => e.tipo === 'session_answered' && e.pedidoId === evento.pedidoId);
+        if (solicitados.length !== 1 || respostas.length !== 1 || JSON.stringify(respostas[0]) !== JSON.stringify(evento))
+            return false;
+        const pedido = solicitados[0].pedido;
+        (0, hitl_contract_1.validarPedidoHitl)(pedido);
+        if (pedido.thread !== thread || pedido.alvo.tipo !== 'session' ||
+            sha(JSON.stringify(pedido)) !== evento.pedidoSha256 ||
+            pedido.alvo.sessionId !== evento.sessionId || pedido.alvo.runtime !== evento.runtime)
+            return false;
+        const esperado = { contrato: 'ork.hitl-local-session/v1', thread,
+            pedidoId: evento.pedidoId, contexto: evento.contexto, pedidoSha256: evento.pedidoSha256,
+            host, connectionId: evento.conexao, requestId: evento.solicitacao, recebidoEm: evento.recebidoEm,
+            fase: String(evento.fase), sessionId: String(evento.sessionId), runtime: String(evento.runtime),
+            instancia: String(evento.instancia), bloqueio: String(evento.bloqueio), envioId: evento.envioId,
+            estado: 'entregue', respostaSha256: String(lido.dados.respostaSha256),
+            reciboEntrega: (0, hitl_local_atestado_1.reciboDoMaterial)(String(evento.conexao), String(evento.solicitacao), String(evento.pedidoSha256), String(lido.dados.respostaSha256)) };
+        // O recibo confirmado pelo receptor tem de derivar do MESMO hash de resposta: sem isso
+        // o recibo provaria so que alguem respondeu daquela conexao, nunca o que ele recebeu.
+        if (evento.reciboEntrega !== esperado.reciboEntrega)
+            return false;
+        const sig = assinatura(chaveLocal(raiz, false), esperado);
+        return JSON.stringify(lido.dados) === JSON.stringify(esperado) &&
+            (0, node_crypto_1.timingSafeEqual)(Buffer.from(lido.assinatura, 'hex'), Buffer.from(sig, 'hex')) &&
+            evento.evidenciaSha256 === sha(lido.bytes) && evento.recibo === sha(lido.assinatura);
+    }
+    catch {
+        return false;
+    }
+}
+/** Revalida no sync a prova criptográfica e o vínculo exato entre recibo e ledger. */
+function validarEvidenciaLocal(raiz, thread, evento) {
+    try {
+        if (evento.origem !== 'mcp-local' || evento.proveniencia !== 'ork.mcp-elicitation/v1' ||
+            !['mcp-local:codex', 'mcp-local:claude-code'].includes(String(evento.autorizadoPor)) ||
+            typeof evento.pedidoId !== 'string' || typeof evento.contexto !== 'string' ||
+            typeof evento.pedidoSha256 !== 'string' || typeof evento.conexao !== 'string' ||
+            typeof evento.solicitacao !== 'string' || typeof evento.recebidoEm !== 'string' ||
+            !Number.isInteger(evento.opcao) || typeof evento.evidencia !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(String(evento.evidenciaSha256 ?? '')) ||
+            !/^[a-f0-9]{64}$/.test(String(evento.recibo ?? '')))
+            return false;
+        const host = String(evento.autorizadoPor).slice('mcp-local:'.length);
+        if (evento.canal !== host || evento.contratoResposta !== 'ork.mcp-elicitation/v1')
+            return false;
+        const nome = sha(JSON.stringify([evento.conexao, evento.solicitacao])) + '.json';
+        if (evento.evidencia !== referencia(thread, nome))
+            return false;
+        const lido = lerRecibo(raiz, thread, nome);
+        const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, thread));
+        const solicitados = eventos.filter(e => e.tipo === 'hitl_requested' && e.pedido?.id === evento.pedidoId);
+        const gates = eventos.filter(e => e.tipo === 'human_gate' && e.pedidoId === evento.pedidoId);
+        if (solicitados.length !== 1 || gates.length !== 1 || JSON.stringify(gates[0]) !== JSON.stringify(evento) || Object.hasOwn(evento, 'observacao'))
+            return false;
+        const pedido = solicitados[0].pedido;
+        (0, hitl_contract_1.validarPedidoHitl)(pedido);
+        const escolhas = (0, hitl_contract_1.escolhasDoPedido)(pedido);
+        if (pedido.thread !== thread || (0, hitl_contract_1.alvoDoPedido)(pedido)?.tipo !== 'gate' || sha(JSON.stringify(pedido)) !== evento.pedidoSha256 ||
+            escolhas.every(o => o.numero !== evento.opcao))
+            return false;
+        const opcao = escolhas.find(o => o.numero === evento.opcao);
+        const veredito = (0, hitl_contract_1.vereditoDoGate)(pedido, opcao);
+        if (evento.fase !== veredito.fase || evento.sobre !== veredito.sobre || evento.estado !== veredito.estado)
+            return false;
+        const esperado = { contrato: 'ork.hitl-local-ingress/v1', thread,
+            pedidoId: evento.pedidoId, contexto: evento.contexto, pedidoSha256: evento.pedidoSha256,
+            host, connectionId: evento.conexao, requestId: evento.solicitacao,
+            recebidoEm: evento.recebidoEm, ...veredito };
+        const sig = assinatura(chaveLocal(raiz, false), esperado);
+        return JSON.stringify(lido.dados) === JSON.stringify(esperado) &&
+            (0, node_crypto_1.timingSafeEqual)(Buffer.from(lido.assinatura, 'hex'), Buffer.from(sig, 'hex')) &&
+            evento.evidenciaSha256 === sha(lido.bytes) && evento.recibo === sha(lido.assinatura);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/hitl-local.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reciboDoAtestado = exports.hashPedidoLocal = exports.consumirAtestadoLocal = void 0;
+exports.criarIngressoLocal = criarIngressoLocal;
+/** Ingresso do cliente MCP confiável. Não é uma API de resposta do modelo.
+ * A instalação/perfil do cliente pertence à fronteira de confiança: não autentica
+ * uma pessoa contra comprometimento do próprio cliente ou da conta local.
+ */
+const node_crypto_1 = require("node:crypto");
+const hitl_contract_1 = require("./hitl-contract");
+const hitl_gates_1 = require("./hitl-gates");
+const hitl_sessions_1 = require("./hitl-sessions");
+const ledger_1 = require("./ledger");
+const hitl_canais_1 = require("./hitl-canais");
+const hitl_lock_1 = require("./hitl-lock");
+const thread_1 = require("./thread");
+const hitl_local_atestado_1 = require("./hitl-local-atestado");
+var hitl_local_atestado_2 = require("./hitl-local-atestado");
+Object.defineProperty(exports, "consumirAtestadoLocal", { enumerable: true, get: function () { return hitl_local_atestado_2.consumirAtestadoLocal; } });
+Object.defineProperty(exports, "hashPedidoLocal", { enumerable: true, get: function () { return hitl_local_atestado_2.hashPedidoLocal; } });
+Object.defineProperty(exports, "reciboDoAtestado", { enumerable: true, get: function () { return hitl_local_atestado_2.reciboDoAtestado; } });
+const idValido = (s) => typeof s === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(s);
+/** O callback é fornecido pelo servidor, nunca pelos argumentos de tools/call. */
+function criarIngressoLocal(raiz, origem, elicitar, 
+/** Vinculo do adapter para resposta de SESSAO, fornecido pelo servidor. E o mesmo ponto
+ *  de injecao que `responderSessao` ja tem; ausente, vale o controle nativo do runtime. */
+opcoes = {}) {
+    if (!['claude-code', 'codex'].includes(origem.host) || !idValido(origem.connectionId))
+        throw new Error('hitl.local.origem-invalida');
+    const conexao = { ...origem }, ativos = new Map();
+    let fechada = false;
+    return {
+        fechar() { fechada = true; for (const c of ativos.values())
+            c.abort(); },
+        async solicitar(threadId, pedidoId, signal) {
+            if (fechada)
+                throw new Error('hitl.local.conexao-fechada');
+            if (!idValido(threadId) || !idValido(pedidoId))
+                throw new Error('hitl.local.identificador-invalido');
+            if (signal?.aborted)
+                return { ok: false, pedidoId, estado: 'pendente', repetida: false };
+            const key = `${threadId}:${pedidoId}`;
+            if (ativos.has(key))
+                throw new Error('hitl.local.solicitacao-em-curso');
+            (0, thread_1.lerThread)(raiz, threadId);
+            const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId));
+            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 !== threadId)
+                throw new Error('hitl.local.pedido-de-outra-thread');
+            // D12: gate e sessão são os dois alvos do contrato HITL, e os dois atendem aqui.
+            const alvo = pedido.alvo.tipo;
+            const respondido = alvo === 'gate'
+                ? eventos.find(e => e.tipo === 'human_gate' && e.pedidoId === pedidoId)
+                : eventos.find(e => e.tipo === 'session_answered' && e.pedidoId === pedidoId);
+            if (respondido) {
+                return alvo === 'gate'
+                    ? { ok: true, pedidoId, estado: String(respondido.estado), repetida: true }
+                    : { ok: true, pedidoId, sessionId: String(respondido.sessionId), estado: 'entregue', repetida: true };
+            }
+            const contexto = (0, hitl_gates_1.contextoHitl)(raiz, threadId);
+            if (evento.contexto !== contexto)
+                throw new Error('hitl.local.pedido-antigo');
+            if ((0, hitl_contract_1.estadoDoPedido)(pedido) !== 'aberto')
+                throw new Error('hitl.local.pedido-expirado');
+            const pedidoSha256 = (0, hitl_local_atestado_1.hashPedidoLocal)(pedido), requestId = (0, node_crypto_1.randomUUID)(), controller = new AbortController();
+            let liberarReserva;
+            (0, hitl_gates_1.comLockHitl)(raiz, threadId, () => {
+                const current = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId));
+                if (current.some(e => e.tipo === 'session_answer_sending' && e.pedidoId === pedidoId))
+                    throw Error('hitl.channel.delivery-uncertain');
+                const selected = (0, hitl_canais_1.selecaoDeCanal)(current, pedidoId);
+                if (selected) {
+                    if (selected.transporte !== 'mcp-local' || selected.reserva !== 'ork.hitl-dialogue/v1' ||
+                        typeof selected.requestId !== 'string' || typeof selected.connectionId !== 'string')
+                        throw Error('hitl.channel.in-use: seleção sem prova de abandono');
+                    const release = (0, hitl_lock_1.reservarDialogoHitl)((0, thread_1.dirThread)(raiz, threadId), selected.requestId, selected.connectionId, true);
+                    try {
+                        (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, 'hitl_channel_released', { pedidoId, requestId: selected.requestId,
+                            reason: 'abandoned-dialogue', evidence: 'kernel-exclusive-lock', connectionId: conexao.connectionId });
+                    }
+                    finally {
+                        release();
+                    }
+                }
+                liberarReserva = (0, hitl_lock_1.reservarDialogoHitl)((0, thread_1.dirThread)(raiz, threadId), requestId, conexao.connectionId);
+                try {
+                    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, 'hitl_channel_selected', { pedidoId,
+                        canal: conexao.host, transporte: 'mcp-local', connectionId: conexao.connectionId, requestId, contexto, pedidoSha256,
+                        reserva: 'ork.hitl-dialogue/v1' });
+                }
+                catch (e) {
+                    liberarReserva();
+                    throw e;
+                }
+            });
+            ativos.set(key, controller);
+            const abortar = () => controller.abort();
+            signal?.addEventListener('abort', abortar, { once: true });
+            const cancelar = new Promise(resolve => controller.signal.addEventListener('abort', () => resolve({ action: 'cancel' }), { once: true }));
+            const timer = setTimeout(() => controller.abort(), Math.min(300000, Date.parse(pedido.prazo) - Date.now()));
+            try {
+                // Copia isolada: o cliente não altera o snapshot usado na conferência final.
+                const resposta = await Promise.race([elicitar(JSON.parse(JSON.stringify(pedido)), controller.signal), cancelar]);
+                if (fechada || controller.signal.aborted || resposta?.action === 'cancel' || resposta?.action === 'decline') {
+                    return { ok: false, pedidoId, estado: 'pendente', repetida: false };
+                }
+                if (resposta?.action !== 'accept' || !resposta.content ||
+                    Object.keys(resposta.content).length !== 1 || typeof resposta.content.opcao !== 'string' ||
+                    resposta.content.opcao.length > pedido.respostaAceita.maxCaracteres) {
+                    throw new Error('hitl.local.resposta-invalida');
+                }
+                const token = Object.freeze({});
+                (0, hitl_local_atestado_1.registrarAtestadoLocal)(token, { raiz, thread: threadId, pedidoId, contexto, pedidoSha256, ...conexao,
+                    requestId, opcao: resposta.content.opcao, recebidoEm: new Date().toISOString(), alvo });
+                try {
+                    return alvo === 'gate'
+                        ? (0, hitl_gates_1.responderGateLocal)(raiz, threadId, pedidoId, token)
+                        : (0, hitl_sessions_1.responderSessaoLocal)(raiz, threadId, pedidoId, token, opcoes.controle);
+                }
+                finally {
+                    (0, hitl_local_atestado_1.descartarAtestadoLocal)(token);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', abortar);
+                ativos.delete(key);
+                try {
+                    (0, hitl_gates_1.comLockHitl)(raiz, threadId, () => {
+                        const current = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId)), selected = (0, hitl_canais_1.selecaoDeCanal)(current, pedidoId);
+                        if (selected?.requestId === requestId && !current.some(e => ['human_gate', 'session_answer_sending', 'session_answered'].includes(e.tipo) && e.pedidoId === pedidoId))
+                            (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, 'hitl_channel_released', { pedidoId, requestId, reason: 'dialogue-ended-without-effect' });
+                    });
+                }
+                finally {
+                    liberarReserva?.();
+                }
+            }
+        }
+    };
+}

package/dist/hitl-lock.js

@@ -0,0 +1,139 @@
+"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.reservarDialogoHitl = reservarDialogoHitl;
+exports.comLockInspecionavel = comLockInspecionavel;
+/** Linux flock(2): o descritor do dono mantém a exclusão, inclusive após o helper sair. */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+/** Reserva por apresentação. Só o kernel prova abandono; PID e prazo não liberam. */
+function reservarDialogoHitl(dir, requestId, connectionId, recuperar = false) {
+    if (process.platform !== 'linux' || !/^[a-f0-9-]{36}$/.test(requestId))
+        throw Error('hitl.channel.recovery-unproven');
+    const file = path.join(dir, `.hitl-dialogue-${requestId}.lock`);
+    const flags = fs.constants.O_RDWR | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK |
+        (recuperar ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL);
+    let fd;
+    try {
+        fd = fs.openSync(file, flags, 0o600);
+    }
+    catch {
+        throw Error('hitl.channel.recovery-unproven');
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.uid !== process.getuid?.() || (st.mode & 0o777) !== 0o600 || st.nlink !== 1 || st.size > 1024)
+            throw Error('hitl.channel.recovery-unproven');
+        const r = (0, node_child_process_1.spawnSync)('/usr/bin/flock', ['--exclusive', '--nonblock', '3'], { stdio: ['ignore', 'pipe', 'pipe', fd], timeout: 2000 });
+        if (r.status !== 0 || r.error)
+            throw Error('hitl.channel.in-use: apresentação ainda reservada pelo kernel');
+        const current = fs.lstatSync(file);
+        if (current.ino !== st.ino || current.dev !== st.dev || current.isSymbolicLink())
+            throw Error('hitl.channel.recovery-unproven');
+        const metadata = JSON.stringify({ contrato: 'ork.hitl-dialogue/v1', requestId, connectionId });
+        if (recuperar) {
+            if (fs.readFileSync(fd, 'utf8') !== metadata)
+                throw Error('hitl.channel.recovery-unproven');
+        }
+        else {
+            fs.writeFileSync(fd, metadata);
+            fs.fsyncSync(fd);
+        }
+        return () => fs.closeSync(fd); // o inode permanece; nunca libera uma reserva por unlink
+    }
+    catch (e) {
+        fs.closeSync(fd);
+        throw e;
+    }
+}
+function comLockInspecionavel(dir, operacao, executar) {
+    if (process.platform !== 'linux')
+        throw new Error('runtime.unavailable: lock HITL exige flock Linux');
+    // Mesmo inode/nome do protocolo legado: writer wx antigo também recusa enquanto existir.
+    const file = path.join(dir, '.hitl.lock');
+    let fd, criado = false;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+        criado = true;
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+        fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.uid !== process.getuid?.() || st.mode & 0o077 || st.nlink !== 1)
+            throw new Error('HITL lock exige arquivo privado do uid');
+        const r = (0, node_child_process_1.spawnSync)('/usr/bin/flock', ['--exclusive', '--nonblock', '3'], { stdio: ['ignore', 'pipe', 'pipe', fd], timeout: 2000 });
+        if (r.status !== 0)
+            throw new Error('HITL ocupado; exclusão do kernel não adquirida');
+        // fd 3 no helper é dup do mesmo open file description. Fechar o helper não libera fd no dono.
+        const atual = fs.lstatSync(file);
+        if (atual.ino !== st.ino || atual.dev !== st.dev || atual.isSymbolicLink())
+            throw new Error('HITL lock mudou durante aquisição');
+        let anterior = null;
+        const raw = fs.readFileSync(fd, 'utf8');
+        if (!criado) {
+            let v;
+            try {
+                v = JSON.parse(raw);
+            }
+            catch { /* legado ambíguo permanece preservado */ }
+            if (v?.contrato !== 'ork.hitl-lock/v1')
+                throw new Error('HITL ocupado; lock legado exige inspeção e migração coordenada');
+            anterior = { token: v.token, dono: v.dono, estado: v.estado };
+        }
+        const stat = fs.readFileSync('/proc/self/stat', 'utf8');
+        const info = { contrato: 'ork.hitl-lock/v1', token: (0, node_crypto_1.randomUUID)(), operacao, estado: 'ocupado', adquiridoEm: new Date().toISOString(),
+            dono: { pid: process.pid, uid: process.getuid(), bootId: fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(),
+                inicio: stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19], executavel: fs.readlinkSync('/proc/self/exe'), cwd: process.cwd() },
+            anterior, evidencia: 'flock exclusivo adquirido pelo kernel; PID/TTL são somente metadados' };
+        const salvar = () => { fs.ftruncateSync(fd, 0); fs.writeSync(fd, JSON.stringify(info), 0, 'utf8'); fs.fsyncSync(fd); };
+        salvar();
+        try {
+            return executar();
+        }
+        finally {
+            info.estado = 'liberado';
+            salvar();
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    } // não unlink, não sinal, não TTL
+}