@orkastery/cli 0.2.0 → 0.4.1

package/dist/conducao.js

@@ -0,0 +1,876 @@
+"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.ErroDeConducao = exports.ESPERA_PADRAO_MS = exports.PRAZO_DA_RESERVA_MS = exports.PRAZO_DE_SESSAO_PADRAO_MS = exports.MARGEM_DO_PRAZO_MS = exports.ENV_THREAD_DO_DESPACHO = exports.ENV_IDENTIDADE_DE_DESPACHO = exports.ENV_CANAL = exports.ERRO_CANAL_DESCONHECIDO = exports.CANAIS_DE_CONDUCAO = exports.conducaoDoLease = void 0;
+exports.validarCanal = validarCanal;
+exports.canalDoProcesso = canalDoProcesso;
+exports.ambienteDaConducao = ambienteDaConducao;
+exports.identidadeDoAmbiente = identidadeDoAmbiente;
+exports.prazoDaVerificacao = prazoDaVerificacao;
+exports.nomeDaConducao = nomeDaConducao;
+exports.fimDaSessao = fimDaSessao;
+exports.conducaoDosDados = conducaoDosDados;
+exports.conducaoDaThread = conducaoDaThread;
+exports.dormir = dormir;
+exports.vidaDoProcesso = vidaDoProcesso;
+exports.tomarConducao = tomarConducao;
+exports.registrarConducaoDaSessao = registrarConducaoDaSessao;
+exports.comandoDeEsperar = comandoDeEsperar;
+exports.recusaDeConducao = recusaDeConducao;
+exports.textoDoPedidoRepetido = textoDoPedidoRepetido;
+exports.registrarRecusa = registrarRecusa;
+exports.comConducao = comConducao;
+exports.esperarConducaoLivre = esperarConducaoLivre;
+exports.liberarSeOrfa = liberarSeOrfa;
+exports.assumirConducao = assumirConducao;
+exports.textoDoStatusDaConducao = textoDoStatusDaConducao;
+/**
+ * I-36 (RM-036): conducao multicanal do Maestro no nucleo.
+ *
+ * Existe UM Maestro, o dono, e varios canais por onde ele conduz a mesma fabrica: o Claude Code,
+ * o Hermes, o OpenClaw, o Codex, o MCP e o CLI. Um pedido vindo de outro canal e o mesmo dono
+ * chegando por outra porta, e nunca um intruso a ser derrubado. O que o nucleo garante e que dois
+ * pedidos nunca EXECUTEM juntos na mesma worktree: em 19/09/2026 duas sessoes de canais diferentes
+ * rodaram build e teste ao mesmo tempo na worktree da mesma thread, o `verify` gravou `code: -1`
+ * como reprovacao, e o unico jeito de destravar foi matar a sessao do outro canal.
+ *
+ * O recurso e o lease `exec:<thread>`, no estado canonico do projeto (D1). Quem conduz fica nele:
+ * canal, sessao ou processo, fase, desde quando e o sha do prompt. O segundo pedido e recusado na
+ * hora com `conducao.em-andamento` e as tres acoes (esperar, acompanhar, assumir), com `--esperar`
+ * como opcao (D2, decisao do dono em 27/09/2026). Vida se prova pelo kernel ou pelo runtime, nunca
+ * por PID ou prazo sozinhos (D7): liberar pelo prazo o que ainda roda e exatamente o incidente.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const codex_runner_1 = require("./adapters/codex-runner");
+const conducao_texto_1 = require("./conducao-texto");
+var conducao_texto_2 = require("./conducao-texto");
+Object.defineProperty(exports, "conducaoDoLease", { enumerable: true, get: function () { return conducao_texto_2.conducaoDoLease; } });
+const leases_1 = require("./leases");
+const ledger_1 = require("./ledger");
+const maquina_1 = require("./maquina");
+const thread_1 = require("./thread");
+const horario_1 = require("./horario");
+const util_1 = require("./util");
+// ---------------------------------------------------------------------------
+// Canais (D5, D6): registro fechado, declarado pela borda.
+// ---------------------------------------------------------------------------
+/** O registro fechado de canais: de onde o pedido chega e como a borda o declara. */
+exports.CANAIS_DE_CONDUCAO = {
+    'claude-code': {
+        origem: 'sessao interativa do Claude Code',
+        declaracao: 'servidor MCP iniciado com --host claude-code; no CLI, a variavel CLAUDECODE=1 que o proprio Claude Code exporta',
+    },
+    hermes: {
+        origem: 'assistente Hermes',
+        declaracao: 'HERMES_HOME, definido pelo servico do gateway, ou --canal hermes nos binarios do adaptador',
+    },
+    openclaw: {
+        origem: 'plugin OpenClaw',
+        declaracao: 'ORK_CANAL=openclaw no ambiente que o adaptador monta para cada chamada do ork',
+    },
+    codex: {
+        origem: 'sessao do Codex',
+        declaracao: 'servidor MCP iniciado com --host codex',
+    },
+    mcp: {
+        origem: 'cliente MCP sem host homologado',
+        declaracao: 'reservado: o servidor MCP atual exige host homologado e declara o canal dele',
+    },
+    cli: {
+        origem: 'terminal, ork chamado direto',
+        declaracao: 'padrao de quem nao declara canal',
+    },
+};
+/** Codigo tipado da recusa de canal fora do registro. */
+exports.ERRO_CANAL_DESCONHECIDO = 'conducao.canal-desconhecido';
+/** Canal fora do registro e recusado com motivo tipado, nunca adivinhado (T9). */
+function validarCanal(bruto) {
+    const canal = bruto.trim();
+    if (!Object.hasOwn(exports.CANAIS_DE_CONDUCAO, canal)) {
+        throw new Error(`${exports.ERRO_CANAL_DESCONHECIDO}: "${bruto}" nao e um canal de conducao homologado ` +
+            `(${Object.keys(exports.CANAIS_DE_CONDUCAO).join(', ')})`);
+    }
+    return canal;
+}
+/** Variavel com que um host ou adaptador declara o proprio canal. */
+exports.ENV_CANAL = 'ORK_CANAL';
+/**
+ * O canal deste processo (D6): `--canal`, depois `ORK_CANAL`, depois o que o proprio host exporta
+ * (`CLAUDECODE=1` do Claude Code, `HERMES_HOME` do gateway do Hermes), e por fim `cli`. O canal
+ * descreve a porta e nao concede autoridade: nenhum gate e nenhuma permissao dependem dele.
+ */
+function canalDoProcesso(explicito, ambiente = process.env) {
+    if (typeof explicito === 'string' && explicito.trim() !== '')
+        return validarCanal(explicito);
+    const declarado = (ambiente[exports.ENV_CANAL] ?? '').trim();
+    if (declarado)
+        return validarCanal(declarado);
+    if (ambiente.CLAUDECODE === '1')
+        return 'claude-code';
+    if ((ambiente.HERMES_HOME ?? '').trim())
+        return 'hermes';
+    return 'cli';
+}
+// ---------------------------------------------------------------------------
+// Identidade de despacho (D4): a reentrada da sessao que ja conduz.
+// ---------------------------------------------------------------------------
+/** Identidade do despacho no ambiente da sessao filha, para as chamadas do CLI de dentro dela. */
+exports.ENV_IDENTIDADE_DE_DESPACHO = 'ORK_DISPATCH_ID';
+exports.ENV_THREAD_DO_DESPACHO = 'ORK_DISPATCH_THREAD';
+/** O que o despacho poe no ambiente da sessao filha: identidade, thread e canal de origem. */
+function ambienteDaConducao(identidade, threadId, canal) {
+    return { [exports.ENV_IDENTIDADE_DE_DESPACHO]: identidade, [exports.ENV_THREAD_DO_DESPACHO]: threadId, [exports.ENV_CANAL]: canal };
+}
+/** A identidade de despacho que este processo herdou, quando ela e desta thread. */
+function identidadeDoAmbiente(threadId, ambiente = process.env) {
+    const id = (ambiente[exports.ENV_IDENTIDADE_DE_DESPACHO] ?? '').trim();
+    const thread = (ambiente[exports.ENV_THREAD_DO_DESPACHO] ?? '').trim();
+    return /^[a-f0-9-]{36}$/.test(id) && thread === threadId ? id : null;
+}
+// ---------------------------------------------------------------------------
+// Prazos (D3): derivados do teto real da operacao; metadado, nunca prova.
+// ---------------------------------------------------------------------------
+/** Folga sobre o teto: o `timeout(1)` ainda da 15 s de `--kill-after` depois do prazo. */
+exports.MARGEM_DO_PRAZO_MS = 60_000;
+/** Sessao despachada sem limite de duracao no setup do bloco. */
+exports.PRAZO_DE_SESSAO_PADRAO_MS = 12 * 60 * 60 * 1000;
+/** Reserva de quem assumiu a conducao: curta, porque nao e execucao. */
+exports.PRAZO_DA_RESERVA_MS = 15 * 60 * 1000;
+/** Espera padrao de `--esperar` sem valor. */
+exports.ESPERA_PADRAO_MS = 30 * 60 * 1000;
+/** O prazo do lease de uma verificacao: o teto de cada comando vezes quantos rodam, com folga. */
+function prazoDaVerificacao(prazoPorComandoMs, comandos) {
+    return prazoPorComandoMs * Math.max(1, comandos) + exports.MARGEM_DO_PRAZO_MS;
+}
+// ---------------------------------------------------------------------------
+// Leitura unica (T2, D9).
+// ---------------------------------------------------------------------------
+/** Nome canonico do lease de execucao da thread. */
+function nomeDaConducao(threadId) {
+    return `exec:${threadId}`;
+}
+/** Estados em que o runtime ja deu a sessao por encerrada. */
+const TERMINAIS = ['done', 'completed', 'exited', 'stopped', 'failed'];
+/**
+ * O evento que prova que a sessao dona do lease acabou: o resultado da fase dela (a prova da I-34
+ * que o observador grava), a morte registrada, a superacao, ou a thread fechada. So conta evento
+ * posterior ao inicio da conducao.
+ */
+function fimDaSessao(eventos, lease) {
+    const dono = lease.conducao?.dono;
+    if (!dono || dono.tipo !== 'sessao')
+        return null;
+    const desde = Date.parse(lease.adquiridoEm);
+    return eventos.find((e) => Date.parse(e.ts) >= desde && ((['phase_result', 'sessao_morta', 'session_superseded'].includes(e.tipo) && e.sessionId === dono.sessionId) ||
+        ['thread_closed_admin', 'master_done'].includes(e.tipo))) ?? null;
+}
+/**
+ * A leitura pura, para quem so tem os dados (o snapshot do Maestro le por um leitor confinado).
+ * Sessao encerrada no ledger e reserva vencida saem da leitura; processo sem prova de vida so sai
+ * quando a prova de processo diz `morto`.
+ */
+function conducaoDosDados(lease, eventos, opcoes = {}) {
+    if (!lease)
+        return null;
+    const atual = (0, conducao_texto_1.conducaoDoLease)(lease);
+    if (!atual)
+        return null;
+    if (atual.dono.tipo === 'reserva')
+        return (0, leases_1.expirado)(lease, opcoes.agora) ? null : atual;
+    if (atual.dono.tipo === 'processo')
+        return opcoes.vidaDoProcesso === 'morto' ? null : atual;
+    return fimDaSessao(eventos, lease) ? null : atual;
+}
+/**
+ * "Quem conduz agora" (T2): a UNICA fonte. Thread status, board, monitor, pulse e os hosts leem
+ * daqui, e nenhuma superficie recalcula. Nao escreve nada: liberar e trabalho de quem toma.
+ */
+function conducaoDaThread(raiz, threadId, opcoes = {}) {
+    const lease = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+    if (!lease?.conducao)
+        return null;
+    const vida = lease.conducao.dono.tipo === 'processo' ? vidaDoProcesso(raiz, threadId, lease) : undefined;
+    let eventos = [];
+    try {
+        eventos = lease.conducao.dono.tipo === 'sessao' ? (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId)) : [];
+    }
+    catch { /* ledger ilegivel nao prova fim de sessao */ }
+    let fechada = false;
+    try {
+        fechada = (0, thread_1.lerThread)(raiz, threadId).status === 'fechada';
+    }
+    catch { /* thread ilegivel segue como esta */ }
+    if (fechada && lease.conducao.dono.tipo !== 'processo')
+        return null;
+    return conducaoDosDados(lease, eventos, { agora: opcoes.agora, vidaDoProcesso: vida });
+}
+// ---------------------------------------------------------------------------
+// Exclusao do kernel (D7).
+// ---------------------------------------------------------------------------
+const FLOCK = '/usr/bin/flock';
+const pausa = new Int32Array(new SharedArrayBuffer(4));
+/** Espera sincrona sem ocupar CPU. */
+function dormir(ms) {
+    if (ms > 0)
+        Atomics.wait(pausa, 0, 0, Math.ceil(ms));
+}
+/** Arquivo da trava de kernel da thread: nunca apagado, como o lock HITL. */
+function caminhoDaTrava(raiz, threadId) {
+    return path.join((0, thread_1.dirThread)(raiz, threadId), '.conducao.lock');
+}
+function kernelDisponivel() {
+    return process.platform === 'linux' && fs.existsSync(FLOCK);
+}
+/**
+ * Tenta a trava exclusiva do kernel. O `flock` ajudante tranca a descricao de arquivo que este
+ * processo segura; ao sair, a trava continua do processo, e morre com ele. Devolve o descritor, ou
+ * null quando outro processo vivo segura a trava.
+ */
+function tentarTrava(raiz, threadId) {
+    const arquivo = caminhoDaTrava(raiz, threadId);
+    const fd = fs.openSync(arquivo, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+    if (!kernelDisponivel())
+        return fd;
+    const r = (0, node_child_process_1.spawnSync)(FLOCK, ['--exclusive', '--nonblock', '3'], { stdio: ['ignore', 'ignore', 'ignore', fd], timeout: 5000 });
+    if (r.status === 0 && !r.error)
+        return fd;
+    fs.closeSync(fd);
+    return null;
+}
+/**
+ * Prova de vida de um dono processo. No Linux, a trava do kernel: se ela esta livre, o dono nao
+ * existe mais (morreu, ou a maquina reiniciou). Fora do Linux, sem kernel lock, vale a identidade do
+ * processo (pid e instante de inicio), ou `desconhecido`.
+ */
+function vidaDoProcesso(raiz, threadId, lease) {
+    const dono = lease.conducao?.dono;
+    if (!dono || dono.tipo !== 'processo')
+        return 'desconhecido';
+    if (dono.maquina !== (0, maquina_1.nomeDaMaquina)())
+        return 'desconhecido';
+    if (!kernelDisponivel()) {
+        try {
+            process.kill(dono.pid, 0);
+        }
+        catch {
+            return 'morto';
+        }
+        const atual = (0, codex_runner_1.identidadeProcesso)(dono.pid);
+        return atual && atual.inicio === dono.inicio ? 'vivo' : 'desconhecido';
+    }
+    let fd = null;
+    try {
+        fd = tentarTrava(raiz, threadId);
+    }
+    catch {
+        return 'desconhecido';
+    }
+    if (fd === null)
+        return 'vivo';
+    fs.closeSync(fd);
+    return 'morto';
+}
+/** Conducoes que ESTE processo segura, pela chave canonica: a reentrada no mesmo processo. */
+const emCurso = new Map();
+function chave(raiz, threadId) {
+    return `${(0, leases_1.caminhoLease)(raiz, nomeDaConducao(threadId))}`;
+}
+/** A consulta padrao: o controle nativo do runtime (claude-bg ou o controller do codex). */
+const consultaNativa = (dono, raiz, threadId) => {
+    try {
+        // Carregado na hora: o modulo de sessoes puxa o HITL inteiro, que nao pertence a leitura.
+        const { controleNativo } = require('./hitl-sessions');
+        const r = controleNativo(dono.runtime, raiz, threadId, dono.sessionId).consultar();
+        if (!r.ok)
+            return { ok: false, estado: null, detalhe: 'o runtime nao respondeu a consulta' };
+        const achadas = r.sessoes.filter((s) => s.sessionId === dono.sessionId);
+        return { ok: true, estado: achadas[0]?.estado ?? null, detalhe: achadas.length ? `estado ${achadas[0].estado}` : 'sessao ausente' };
+    }
+    catch (e) {
+        return { ok: false, estado: null, detalhe: e.message };
+    }
+};
+/**
+ * A sessao dona acabou? Primeiro o ledger (a prova da I-34, barata); depois, se pedido, o runtime.
+ * Sessao ausente so prova fim quando a consulta foi feita na conta dela (sem perfil, a do processo).
+ * O estado visto no runtime volta junto: sessao `blocked` espera alguem e nao executa nada.
+ */
+function situacaoDaSessao(raiz, threadId, lease, pedido) {
+    let estadoNoRuntime = null;
+    const fim = provaDeFimDaSessao(raiz, threadId, lease, pedido, (estado) => { estadoNoRuntime = estado; });
+    return { fim, estadoNoRuntime };
+}
+function provaDeFimDaSessao(raiz, threadId, lease, pedido, anotarEstado = () => undefined) {
+    const dono = lease.conducao?.dono;
+    if (!dono || dono.tipo !== 'sessao')
+        return null;
+    let eventos = [];
+    try {
+        eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, threadId));
+    }
+    catch { /* sem ledger, so o runtime prova */ }
+    const fim = fimDaSessao(eventos, lease);
+    if (fim)
+        return { motivo: 'sessao-encerrada', prova: `ledger: ${fim.tipo}${fim.eventId ? ` ${String(fim.eventId)}` : ''}`, provaEm: fim.ts };
+    try {
+        if ((0, thread_1.lerThread)(raiz, threadId).status === 'fechada')
+            return { motivo: 'sessao-encerrada', prova: 'thread fechada' };
+    }
+    catch { /* thread ilegivel nao prova nada */ }
+    if (pedido.consultarRuntime === false)
+        return null;
+    const r = (pedido.consultarSessao ?? consultaNativa)(dono, raiz, threadId);
+    if (!r.ok)
+        return null;
+    anotarEstado(r.estado);
+    if (r.estado && TERMINAIS.includes(r.estado))
+        return { motivo: 'sessao-orfa', prova: `runtime ${dono.runtime}: ${r.detalhe}` };
+    if (r.estado === null && !dono.perfil)
+        return { motivo: 'sessao-orfa', prova: `runtime ${dono.runtime}: ${r.detalhe}` };
+    return null;
+}
+function dadosDoPedido(pedido, identidade, dono) {
+    return {
+        contrato: 'ork.conducao/v1',
+        canal: pedido.canal,
+        correlacao: pedido.correlacao ?? null,
+        operacao: pedido.operacao,
+        fase: pedido.fase ?? null,
+        promptSha256: pedido.promptSha256 ?? null,
+        identidade,
+        dono,
+    };
+}
+function donoProcesso() {
+    const id = process.platform === 'linux' ? (0, codex_runner_1.identidadeProcesso)(process.pid) : null;
+    return { tipo: 'processo', pid: process.pid, inicio: id?.inicio ?? '', bootId: id?.boot ?? '', maquina: (0, maquina_1.nomeDaMaquina)() };
+}
+/** Grava a liberacao com a prova e apaga o lease (quem chama segura a trava do kernel). */
+function liberarComProva(raiz, threadId, lease, tipo, dados) {
+    try {
+        fs.unlinkSync((0, leases_1.caminhoLease)(raiz, lease.nome));
+    }
+    catch { /* ja saiu */ }
+    const anterior = (0, conducao_texto_1.conducaoDoLease)(lease);
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, tipo, {
+        lease: lease.nome,
+        anterior: anterior ? { canal: anterior.canal, sessao: anterior.sessao, fase: anterior.fase, desde: anterior.desde,
+            operacao: anterior.operacao, dono: anterior.dono, promptSha256: anterior.promptSha256 } : null,
+        ...dados,
+    });
+}
+/**
+ * Com a trava do kernel na mao: o lease que estiver ai ainda vale? Dono processo nao vale (a trava
+ * estava livre, entao ele morreu). Dono sessao vale ate a prova de fim. Reserva vale no prazo, e para
+ * o mesmo canal vira a conducao dele.
+ */
+function avaliarComTrava(raiz, threadId, pedido, opcoes = { usarReserva: true }) {
+    const lease = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+    if (!lease)
+        return null;
+    const atual = (0, conducao_texto_1.conducaoDoLease)(lease);
+    if (!atual) {
+        liberarComProva(raiz, threadId, lease, ledger_1.TIPOS_DE_EVENTO.conducaoOrfaLiberada, { motivo: 'lease-invalido', prova: 'lease exec sem dados de conducao validos' });
+        return null;
+    }
+    if (atual.dono.tipo === 'processo') {
+        const d = atual.dono;
+        // Sem kernel lock (fora do Linux), segurar a "trava" nao prova nada: vale a identidade do processo.
+        if (!kernelDisponivel() && vidaDoProcesso(raiz, threadId, lease) !== 'morto')
+            return { ok: false, idempotente: false, atual };
+        liberarComProva(raiz, threadId, lease, ledger_1.TIPOS_DE_EVENTO.conducaoOrfaLiberada, {
+            motivo: 'processo-morto',
+            prova: kernelDisponivel()
+                ? `trava do kernel livre: o processo ${d.pid} (boot ${d.bootId.slice(0, 8) || '?'}) nao a segura mais`
+                : `processo ${d.pid} ausente`,
+        });
+        return null;
+    }
+    if (atual.dono.tipo === 'reserva') {
+        if ((0, leases_1.expirado)(lease)) {
+            liberarComProva(raiz, threadId, lease, ledger_1.TIPOS_DE_EVENTO.conducaoLiberada, { motivo: 'reserva-vencida', prova: `reserva de ${atual.dono.por} venceu em ${(0, horario_1.formatarDataHoraRotulada)(lease.expiraEm)}` });
+            return null;
+        }
+        if (opcoes.usarReserva && atual.canal === pedido.canal) {
+            liberarComProva(raiz, threadId, lease, ledger_1.TIPOS_DE_EVENTO.conducaoLiberada, { motivo: 'reserva-usada', prova: `pedido do mesmo canal ${pedido.canal} de quem assumiu` });
+            return null;
+        }
+        return { ok: false, idempotente: false, atual };
+    }
+    const { fim, estadoNoRuntime } = situacaoDaSessao(raiz, threadId, lease, pedido);
+    if (fim) {
+        liberarComProva(raiz, threadId, lease, fim.motivo === 'sessao-encerrada'
+            ? ledger_1.TIPOS_DE_EVENTO.conducaoLiberada : ledger_1.TIPOS_DE_EVENTO.conducaoOrfaLiberada, fim);
+        return null;
+    }
+    const despacho = pedido.operacao === 'phase.run' || pedido.operacao === 'retry.run';
+    const mesmaFase = atual.fase === (pedido.fase ?? null);
+    const mesmoPedido = despacho && mesmaFase && !!pedido.promptSha256 && atual.promptSha256 === pedido.promptSha256;
+    // A sucessora (fluxo de superacao das sessoes HITL): a sessao `blocked` espera alguem e nao executa;
+    // o despacho seguinte da MESMA fase a sucede, e a superacao a encerra pelo controle do runtime.
+    if (despacho && mesmaFase && !mesmoPedido && estadoNoRuntime === 'blocked') {
+        liberarComProva(raiz, threadId, lease, ledger_1.TIPOS_DE_EVENTO.conducaoLiberada, {
+            motivo: 'sessao-bloqueada-sucedida',
+            prova: `runtime ${atual.dono.tipo === 'sessao' ? atual.dono.runtime : '?'}: estado blocked; o despacho seguinte da fase ${atual.fase} a sucede`,
+        });
+        return null;
+    }
+    return { ok: false, idempotente: mesmoPedido, atual };
+}
+/**
+ * Toma a conducao da thread para esta operacao, ou diz quem a segura.
+ *
+ * Reentra quando este mesmo processo ja conduz, ou quando a identidade de despacho do pedido e a de
+ * quem conduz (a sessao de CHECK que roda `ork verify` dentro da propria fase, R3). Sem reentrada, a
+ * trava do kernel serializa a decisao e o lease registra quem conduz.
+ */
+function tomarConducao(raiz, threadId, pedido) {
+    const k = chave(raiz, threadId);
+    const propria = emCurso.get(k);
+    if (propria && !propria.convertida) {
+        propria.profundidade++;
+        return reentrada(propria.identidade, () => { propria.profundidade--; });
+    }
+    const existente = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+    if (pedido.identidade && existente?.conducao?.identidade === pedido.identidade) {
+        return reentrada(pedido.identidade, () => undefined);
+    }
+    let fd = null;
+    for (let tentativa = 0; tentativa < 3 && fd === null; tentativa++) {
+        fd = tentarTrava(raiz, threadId);
+        if (fd === null)
+            dormir(150);
+    }
+    if (fd === null) {
+        // Um processo vivo segura a trava: ou conduz, ou esta gravando o lease agora mesmo.
+        let atual = null;
+        for (let i = 0; i < 5 && !atual; i++) {
+            const lease = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+            atual = lease ? (0, conducao_texto_1.conducaoDoLease)(lease) : null;
+            if (!atual)
+                dormir(200);
+        }
+        return { ok: false, idempotente: false, atual };
+    }
+    try {
+        const ocupada = avaliarComTrava(raiz, threadId, pedido);
+        if (ocupada) {
+            fs.closeSync(fd);
+            return ocupada;
+        }
+        const identidade = pedido.identidade ?? (0, node_crypto_1.randomUUID)();
+        const lease = {
+            nome: nomeDaConducao(threadId),
+            thread: threadId,
+            motivo: `${conducao_texto_1.NOME_DA_OPERACAO[pedido.operacao]} pelo canal ${pedido.canal}`,
+            pid: process.pid,
+            adquiridoEm: (0, util_1.agora)(),
+            expiraEm: new Date(Date.now() + pedido.prazoMs).toISOString(),
+            conducao: dadosDoPedido(pedido, identidade, donoProcesso()),
+        };
+        (0, leases_1.regravarLease)(raiz, lease);
+        const estado = { identidade, profundidade: 0, lease, fd, convertida: false };
+        emCurso.set(k, estado);
+        return {
+            ok: true,
+            reentrada: false,
+            identidade,
+            renovar: (prazoDoProximoMs, agoraMs = Date.now()) => renovar(raiz, threadId, estado, prazoDoProximoMs, agoraMs),
+            converterEmSessao: (dados) => converter(raiz, k, estado, dados),
+            liberar: () => liberarPropria(raiz, k, estado),
+        };
+    }
+    catch (e) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch { /* ja fechado */ }
+        throw e;
+    }
+}
+function reentrada(identidade, sair) {
+    let saiu = false;
+    return {
+        ok: true, reentrada: true, identidade,
+        renovar: () => undefined,
+        converterEmSessao: () => undefined,
+        liberar: () => { if (!saiu) {
+            saiu = true;
+            sair();
+        } },
+    };
+}
+function renovar(raiz, threadId, estado, prazoDoProximoMs, agoraMs) {
+    if (estado.convertida)
+        return;
+    const falta = Date.parse(estado.lease.expiraEm) - agoraMs;
+    if (falta >= prazoDoProximoMs + exports.MARGEM_DO_PRAZO_MS)
+        return;
+    const c = estado.lease.conducao;
+    const renovacoes = (c.renovacoes ?? 0) + 1;
+    estado.lease = { ...estado.lease, expiraEm: new Date(agoraMs + prazoDoProximoMs + exports.MARGEM_DO_PRAZO_MS).toISOString(),
+        conducao: { ...c, renovacoes, renovadoEm: new Date(agoraMs).toISOString() } };
+    (0, leases_1.regravarLease)(raiz, estado.lease);
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, ledger_1.TIPOS_DE_EVENTO.conducaoRenovada, {
+        lease: estado.lease.nome, operacao: c.operacao, canal: c.canal, expiraEm: estado.lease.expiraEm, renovacoes,
+        razao: 'o prazo que faltava nao cobria o proximo comando: renovado com a operacao viva',
+    });
+}
+function converter(raiz, k, estado, dados) {
+    if (estado.convertida)
+        return;
+    const c = estado.lease.conducao;
+    estado.lease = {
+        ...estado.lease,
+        expiraEm: new Date(Date.now() + dados.prazoMs).toISOString(),
+        conducao: { ...c, dono: { tipo: 'sessao', sessionId: dados.sessionId, runtime: dados.runtime, perfil: dados.perfil,
+                maquina: (0, maquina_1.nomeDaMaquina)() } },
+    };
+    (0, leases_1.regravarLease)(raiz, estado.lease);
+    estado.convertida = true;
+    emCurso.delete(k);
+    try {
+        fs.closeSync(estado.fd);
+    }
+    catch { /* ja fechado */ }
+}
+function liberarPropria(raiz, k, estado) {
+    if (estado.convertida)
+        return;
+    if (estado.profundidade > 0) {
+        estado.profundidade--;
+        return;
+    }
+    const atual = (0, leases_1.lerLease)(raiz, estado.lease.nome);
+    if (atual?.conducao?.identidade === estado.identidade && atual.conducao.dono.tipo === 'processo') {
+        try {
+            fs.unlinkSync((0, leases_1.caminhoLease)(raiz, estado.lease.nome));
+        }
+        catch { /* ja saiu */ }
+    }
+    emCurso.delete(k);
+    try {
+        fs.closeSync(estado.fd);
+    }
+    catch { /* ja fechado */ }
+}
+/**
+ * Registra a conducao da sessao de um despacho que nao tomou o lease antes (chamada direta de
+ * `concluirDespacho`). So grava quando nao ha conducao nenhuma: nunca escreve por cima de outra.
+ */
+function registrarConducaoDaSessao(raiz, threadId, pedido, sessao) {
+    const t = tomarConducao(raiz, threadId, { ...pedido, consultarRuntime: false });
+    if (!t.ok)
+        return false;
+    if (t.reentrada) {
+        t.liberar();
+        return false;
+    }
+    t.converterEmSessao({ ...sessao, prazoMs: pedido.prazoMs });
+    return true;
+}
+/** O comando exato de repetir o pedido esperando a vez. */
+function comandoDeEsperar(threadId, pedido) {
+    switch (pedido.operacao) {
+        case 'phase.run': return `ork phase run ${threadId} ${pedido.fase ?? '<FASE>'} --prompt "<o mesmo pedido>" --esperar 30`;
+        case 'retry.run': return `ork retry run ${threadId} --esperar 30`;
+        case 'baseline': return `ork verify ${threadId} --baseline --esperar 30`;
+        case 'fix.open': return `ork fix open ${threadId} --esperar 30`;
+        case 'fix.reverify': return `ork fix reverify ${threadId} --esperar 30`;
+        default: return `ork verify ${threadId} --esperar 30`;
+    }
+}
+/** Como acompanhar quem conduz: o status da conducao e, se for sessao, os logs dela. */
+function comandoDeAcompanhar(threadId, atual) {
+    const base = `ork conducao status ${threadId}`;
+    return atual?.sessao ? `${base} && ork sessions logs ${atual.sessao.slice(0, 8)}` : base;
+}
+/**
+ * A recusa, em estrutura e em texto. O dono pediu que ela explique sempre, para um humano, o que
+ * aconteceu e o que fazer: o texto sai daqui e de lugar nenhum mais, e o JSON e a mesma estrutura.
+ */
+function recusaDeConducao(threadId, atual, pedido, opcoes = {}) {
+    const conducao = atual
+        ? { ...atual, desdeLocal: (0, horario_1.formatarDataHoraRotulada)(atual.desde, opcoes), linha: (0, conducao_texto_1.linhaDeConducao)(atual, opcoes) }
+        : null;
+    const acoes = [
+        { acao: 'esperar', comando: comandoDeEsperar(threadId, pedido),
+            explicacao: 'Esperar a vez: repete este pedido e segue sozinho quando a conducao atual terminar (ate 30 min).' },
+        { acao: 'acompanhar', comando: comandoDeAcompanhar(threadId, atual),
+            explicacao: 'Acompanhar quem conduz, sem mexer em nada.' },
+        { acao: 'assumir', comando: `ork conducao assumir ${threadId} --por <voce> --motivo "<por que>"`,
+            explicacao: 'Assumir a conducao: encerra a atual pelo proprio runtime e registra no ledger quem assumiu, de qual canal e por que.' },
+    ];
+    const linhas = [
+        `Pedido nao executado: a thread ${threadId} ja esta sendo conduzida agora, e duas execucoes na mesma worktree ` +
+            'se corrompem (foi o que aconteceu em 19/09/2026).',
+    ];
+    if (conducao) {
+        linhas.push(`  Quem conduz: canal ${conducao.canal}, ${(0, conducao_texto_1.quemConduz)(conducao)}, fase ${conducao.fase ?? '-'}, desde ${conducao.desdeLocal}.`);
+        if (conducao.promptSha256)
+            linhas.push(`  Pedido em curso: prompt sha256 ${conducao.promptSha256.slice(0, 12)}.`);
+    }
+    else {
+        linhas.push('  Outra operacao esta tomando a conducao neste instante; o registro dela ainda nao apareceu.');
+    }
+    linhas.push(`  Pedido recusado: ${conducao_texto_1.NOME_DA_OPERACAO[pedido.operacao]}${pedido.fase ? ` da fase ${pedido.fase}` : ''}, pelo canal ${pedido.canal}.`);
+    linhas.push('O que voce pode fazer:');
+    acoes.forEach((a, i) => { linhas.push(`  ${i + 1}. ${a.explicacao}`); linhas.push(`     ${a.comando}`); });
+    return {
+        contrato: 'ork.conducao-recusa/v1',
+        motivo: 'conducao.em-andamento',
+        thread: threadId,
+        conducao,
+        pedido: { canal: pedido.canal, operacao: pedido.operacao, fase: pedido.fase ?? null, promptSha256: pedido.promptSha256 ?? null },
+        acoes,
+        texto: linhas.join('\n'),
+    };
+}
+/**
+ * O pedido repetido (T14): a mesma fase com o mesmo prompt de quem ja conduz. Nada foi despachado,
+ * e o texto diz onde acompanhar a sessao que ja atende o pedido.
+ */
+function textoDoPedidoRepetido(threadId, atual, opcoes = {}) {
+    return [
+        `Pedido ja em andamento: a fase ${atual.fase ?? '-'} da thread ${threadId} roda com este mesmo prompt ` +
+            `(sha256 ${(atual.promptSha256 ?? '').slice(0, 12)}) desde ${(0, horario_1.formatarDataHoraRotulada)(atual.desde, opcoes)}. ` +
+            'Nenhuma sessao nova foi aberta e nenhuma cota foi gasta.',
+        `  ${(0, conducao_texto_1.linhaDeConducao)(atual, opcoes)}`,
+        `  acompanhar: ${comandoDeAcompanhar(threadId, atual)}`,
+    ].join('\n');
+}
+/** A recusa tipada como erro, para quem nao tem um resultado estruturado onde devolve-la. */
+class ErroDeConducao extends Error {
+    recusa;
+    constructor(recusa) {
+        super(`conducao.em-andamento: ${recusa.texto}`);
+        this.name = 'ErroDeConducao';
+        this.recusa = recusa;
+    }
+}
+exports.ErroDeConducao = ErroDeConducao;
+/** Grava a recusa no ledger: o segundo pedido deixa rastro, que era o que faltava em 19/09. */
+function registrarRecusa(raiz, recusa) {
+    try {
+        (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, recusa.thread), recusa.thread, ledger_1.TIPOS_DE_EVENTO.conducaoRecusada, {
+            motivo: recusa.motivo,
+            pedido: recusa.pedido,
+            conducao: recusa.conducao ? { canal: recusa.conducao.canal, sessao: recusa.conducao.sessao, fase: recusa.conducao.fase,
+                desde: recusa.conducao.desde, operacao: recusa.conducao.operacao, promptSha256: recusa.conducao.promptSha256 } : null,
+        });
+    }
+    catch { /* a recusa ao pedido vale mesmo sem o registro */ }
+}
+/**
+ * Roda a operacao de processo sob a conducao da thread (T4, T5). Sem a conducao, nada executa: a
+ * recusa sai como `ErroDeConducao`. Com `esperarMs`, espera a vez por sondagem ate o prazo.
+ */
+function comConducao(raiz, threadId, pedido, executar) {
+    const prazo = pedido.esperarMs && pedido.esperarMs > 0 ? Date.now() + pedido.esperarMs : null;
+    for (;;) {
+        const t = tomarConducao(raiz, threadId, pedido);
+        if (t.ok) {
+            try {
+                return executar(t);
+            }
+            finally {
+                t.liberar();
+            }
+        }
+        if (!prazo || Date.now() >= prazo) {
+            const recusa = recusaDeConducao(threadId, t.atual, pedido);
+            registrarRecusa(raiz, recusa);
+            throw new ErroDeConducao(recusa);
+        }
+        dormir(Math.min(2000, prazo - Date.now()));
+    }
+}
+/** Espera, sem tomar nada, ate nao haver conducao ou acabar o prazo. Devolve se liberou. */
+function esperarConducaoLivre(raiz, threadId, esperarMs) {
+    const prazo = Date.now() + esperarMs;
+    for (;;) {
+        if (!conducaoDaThread(raiz, threadId))
+            return true;
+        if (Date.now() >= prazo)
+            return false;
+        dormir(Math.min(2000, prazo - Date.now()));
+    }
+}
+// ---------------------------------------------------------------------------
+// Recuperacao de orfa (T16) e handoff (T15).
+// ---------------------------------------------------------------------------
+/**
+ * Libera a conducao que nao tem mais dono vivo, com a prova (D7). Nao conclui fase: a liberacao
+ * so apaga o lease e registra; `phase_result` continua sendo gravado so pela prova da I-34.
+ */
+function liberarSeOrfa(raiz, threadId, opcoes = {}) {
+    const antes = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+    if (!antes)
+        return { liberada: false, detalhe: 'nenhuma conducao registrada' };
+    const fd = tentarTrava(raiz, threadId);
+    if (fd === null)
+        return { liberada: false, detalhe: 'um processo vivo segura a conducao' };
+    try {
+        const ocupada = avaliarComTrava(raiz, threadId, { canal: 'cli', operacao: 'verify', prazoMs: 0, ...opcoes }, { usarReserva: false });
+        return ocupada ? { liberada: false, detalhe: 'a conducao tem dono vivo' } : { liberada: true, detalhe: 'conducao sem dono liberada, com prova no ledger' };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** O estado da worktree no handoff: o que ficou alterado, para quem assume saber. */
+function estadoDaWorktree(raiz, threadId) {
+    try {
+        const t = (0, thread_1.lerThread)(raiz, threadId);
+        const dir = t.worktree ?? raiz;
+        const head = (0, util_1.exec)('git', ['rev-parse', 'HEAD'], dir);
+        const st = (0, util_1.exec)('git', ['status', '--porcelain'], dir);
+        return { head: head.ok ? head.stdout.trim() : null, alterados: st.ok ? st.stdout.split('\n').filter(Boolean).slice(0, 40) : [] };
+    }
+    catch {
+        return { head: null, alterados: [] };
+    }
+}
+const controleNativoDoHandoff = (runtime, raiz, threadId, sessionId) => {
+    const { controleNativo } = require('./hitl-sessions');
+    const ctl = controleNativo(runtime, raiz, threadId, sessionId);
+    return {
+        consultar: () => ctl.consultar(),
+        parar: (s) => ctl.parar(s),
+    };
+};
+/**
+ * `ork conducao assumir` (T15): encerra a conducao atual pelo mecanismo suportado do runtime, toma
+ * uma reserva curta para o canal de quem assumiu e registra quem, de qual canal e por que. Processo
+ * local vivo nao e encerrado por sinal (D8): o handoff recusa e diz como esperar.
+ */
+function assumirConducao(raiz, threadId, opcoes) {
+    const por = opcoes.por.trim(), motivo = opcoes.motivo.trim();
+    if (!por)
+        throw new Error('conducao.assumir: informe --por <quem assume>');
+    if (!motivo)
+        throw new Error('conducao.assumir: informe --motivo; handoff sem razao registrada e o mesmo kill de antes, com outro nome');
+    const dir = (0, thread_1.dirThread)(raiz, threadId);
+    (0, thread_1.lerThread)(raiz, threadId);
+    liberarSeOrfa(raiz, threadId, { consultarSessao: opcoes.consultarSessao });
+    const fd = tentarTrava(raiz, threadId);
+    if (fd === null) {
+        const atual = conducaoDaThread(raiz, threadId);
+        return { ok: false, thread: threadId, anterior: atual, mecanismo: 'nenhum',
+            detalhe: `a conducao atual e um processo local vivo (${atual ? (0, conducao_texto_1.quemConduz)(atual) : 'gravando o lease'}), que termina sozinho. ` +
+                `O handoff nao envia sinal ao processo: espere com ${atual ? comandoDeEsperar(threadId, { operacao: atual.operacao, fase: atual.fase }) : '--esperar'}, ` +
+                'ou encerre-o no canal de onde ele saiu.' };
+    }
+    try {
+        const lease = (0, leases_1.lerLease)(raiz, nomeDaConducao(threadId));
+        const anterior = lease ? (0, conducao_texto_1.conducaoDoLease)(lease) : null;
+        let mecanismo = 'nenhum: nao havia conducao em andamento';
+        let prova = 'lease exec ausente';
+        if (lease && anterior?.dono.tipo === 'sessao') {
+            const dono = anterior.dono;
+            const ctl = (opcoes.controle ?? controleNativoDoHandoff)(dono.runtime, raiz, threadId, dono.sessionId);
+            const antes = ctl.consultar();
+            if (!antes.ok) {
+                return { ok: false, thread: threadId, anterior, mecanismo: 'nenhum',
+                    detalhe: 'runtime.unavailable: nao consegui consultar a sessao no runtime; nada foi encerrado e a conducao segue com ela' };
+            }
+            const s = antes.sessoes.find((x) => x.sessionId === dono.sessionId);
+            if (s && !TERMINAIS.includes(s.estado)) {
+                if (!ctl.parar(s)) {
+                    return { ok: false, thread: threadId, anterior, mecanismo: `parar ${dono.runtime}`,
+                        detalhe: `runtime.unavailable: o runtime ${dono.runtime} nao confirmou o encerramento; a conducao segue com a sessao ${dono.sessionId.slice(0, 8)}` };
+                }
+                const depois = ctl.consultar();
+                const ainda = depois.ok ? depois.sessoes.find((x) => x.sessionId === dono.sessionId) : s;
+                if (!depois.ok || (ainda && !TERMINAIS.includes(ainda.estado))) {
+                    return { ok: false, thread: threadId, anterior, mecanismo: `parar ${dono.runtime}`,
+                        detalhe: 'runtime.unavailable: a consulta depois do encerramento nao confirma a sessao parada; o lease foi mantido' };
+                }
+                mecanismo = `parar pelo runtime ${dono.runtime} (controle homologado)`;
+                prova = `runtime: ${s.estado} -> ${ainda?.estado ?? 'ausente'}`;
+            }
+            else {
+                mecanismo = 'nenhum: a sessao ja tinha terminado';
+                prova = `runtime: ${s?.estado ?? 'sessao ausente'}`;
+            }
+        }
+        else if (lease && anterior?.dono.tipo === 'reserva') {
+            mecanismo = `reserva de ${anterior.dono.por} substituida`;
+            prova = `reserva do canal ${anterior.canal}`;
+        }
+        if (lease) {
+            try {
+                fs.unlinkSync((0, leases_1.caminhoLease)(raiz, lease.nome));
+            }
+            catch { /* ja saiu */ }
+        }
+        const reserva = {
+            nome: nomeDaConducao(threadId), thread: threadId, motivo: `reserva de ${por} ao assumir: ${motivo}`, pid: process.pid,
+            adquiridoEm: (0, util_1.agora)(), expiraEm: new Date(Date.now() + exports.PRAZO_DA_RESERVA_MS).toISOString(),
+            conducao: { contrato: 'ork.conducao/v1', canal: opcoes.canal, correlacao: null, operacao: 'handoff', fase: null,
+                promptSha256: null, identidade: (0, node_crypto_1.randomUUID)(), dono: { tipo: 'reserva', por, maquina: (0, maquina_1.nomeDaMaquina)() } },
+        };
+        (0, leases_1.regravarLease)(raiz, reserva);
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.conducaoAssumida, {
+            por, canal: opcoes.canal, motivo, mecanismo, prova,
+            anterior: anterior ? { canal: anterior.canal, sessao: anterior.sessao, fase: anterior.fase, desde: anterior.desde,
+                operacao: anterior.operacao, promptSha256: anterior.promptSha256 } : null,
+            reservaAte: reserva.expiraEm,
+            worktree: estadoDaWorktree(raiz, threadId),
+        });
+        return { ok: true, thread: threadId, anterior, mecanismo,
+            detalhe: `conducao assumida por ${por} pelo canal ${opcoes.canal}; a proxima operacao desse canal usa a reserva ate ` +
+                `${(0, horario_1.formatarDataHoraRotulada)(reserva.expiraEm)}` };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Texto de `ork conducao status`. */
+function textoDoStatusDaConducao(threadId, atual) {
+    if (!atual)
+        return `Thread ${threadId}: ninguem conduz agora. Qualquer canal pode despachar ou verificar.`;
+    const linhas = [`Thread ${threadId}: ${(0, conducao_texto_1.linhaDeConducao)(atual)}`];
+    if (atual.promptSha256)
+        linhas.push(`  prompt sha256 ${atual.promptSha256.slice(0, 12)}`);
+    linhas.push(`  prazo do lease (metadado, nao prova): ${(0, horario_1.formatarDataHoraRotulada)(atual.expiraEm)}`);
+    if (atual.sessao)
+        linhas.push(`  acompanhar: ork sessions logs ${atual.sessao.slice(0, 8)}`);
+    linhas.push(`  assumir: ork conducao assumir ${threadId} --por <voce> --motivo "<por que>"`);
+    return linhas.join('\n');
+}