@orkastery/cli 0.2.0 → 0.3.0

package/dist/indice.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * O indice automatico de qualidade da entrega (I-43, D3).
+ *
+ * Ele existe para substituir a fila de ratificacao de score, e o problema que a fila
+ * tinha nao era falta de lembrete: eram 13 entradas esperando nota humana justamente
+ * porque lembrete nao converte em nota. A saida e ACEITACAO POR DEFAULT com registro:
+ * entregue e aceito, a menos que o dono diga o contrario, e a nota humana passa a
+ * existir so quando ele reclamar, e ai vale.
+ *
+ * DUAS REGRAS DURAS, e elas explicam quase todo o resto deste arquivo.
+ *
+ * 1. So entra fato que tem ESCRITOR no nucleo e entrada no catalogo `TIPOS_DE_EVENTO`.
+ *    A medida que motivou isso: os 137 ledgers do projeto trazem mais de 200 valores
+ *    distintos de `tipo`, muitos com uma ocorrencia so, com variantes do mesmo fato
+ *    (`lease_acquire` x `lease_acquired`, `claim_novo` x `claim_added`) e ate lixo
+ *    literal (`B`, `path`, `commit`). Um indice que case string livre no ledger e um
+ *    indice que mente: `verify_result` tem 122 ocorrencias e ZERO escritor no nucleo.
+ *
+ * 2. O indice e DERIVADO, nunca digitado. Nao existe caminho que aceite um numero de
+ *    fora. E a diferenca entre este campo e o `score`, que hoje mistura tres coisas:
+ *    das 19 notas em disco, 9 nao sao juizo humano de qualidade (3 sao carimbo cujo
+ *    proprio texto diz "ratificacao pendente", 3 comecam com "Proponho" e sao proposta
+ *    de agente, e 3 sao `valor: 0` de encerramento administrativo).
+ *
+ * RESERVA HONESTA, que precisa estar escrita aqui e nao so no PLAN: o indice NAO
+ * classifica o passado. Com os insumos que hoje tem escritor, 23 das 29 threads
+ * entregues ficariam coladas no teto, porque `rollback_done` tinha ZERO ocorrencias.
+ * Ele comeca a discriminar a partir do momento em que o escritor de reversao existir
+ * (T7, em `ship.ts`). Cobrar do indice um veredito sobre o historico seria cobrar um
+ * numero que ele nao tem como produzir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSUMOS_DO_INDICE = exports.INDICE_MINIMO = exports.INDICE_BASE = void 0;
+exports.calcularIndice = calcularIndice;
+exports.textoDoIndice = textoDoIndice;
+const ledger_1 = require("./ledger");
+/** Nota maxima, e o ponto de partida: entregue e aceito ate prova em contrario. */
+exports.INDICE_BASE = 5;
+exports.INDICE_MINIMO = 0;
+/**
+ * Os pesos de D3. Reversao pesa sozinha mais que tudo junto, e e de proposito:
+ * ela e o unico fato que diz, sem interpretacao, que a entrega nao servia.
+ */
+exports.INSUMOS_DO_INDICE = [
+    { evento: ledger_1.TIPOS_DE_EVENTO.rollbackConcluido, peso: -3, piso: -3,
+        sobre: 'a entrega foi revertida depois do ship' },
+    { evento: ledger_1.TIPOS_DE_EVENTO.fixAberto, peso: -0.5, piso: -1.5,
+        sobre: 'rodadas de GO-FIX: o CHECK reprovou e a entrega precisou de correcao' },
+    { evento: ledger_1.TIPOS_DE_EVENTO.reverifyConcluido, peso: -0.5, piso: -1,
+        sobre: 'CHECK refeito: a verificacao precisou de uma segunda rodada' },
+    { evento: ledger_1.TIPOS_DE_EVENTO.shipBloqueado, peso: -0.25, piso: -0.5,
+        sobre: 'ship barrado antes de entregar' },
+];
+/**
+ * Calcula o indice de uma thread a partir do ledger dela.
+ *
+ * PURA: le eventos, devolve numero, nao escreve nada e nao toca em git. Quem detecta
+ * reversao e `ship.ts`, que e quem sabe de merge e de base; aqui so se conta o evento
+ * que ele gravou.
+ */
+function calcularIndice(eventos) {
+    const parcelas = [];
+    let valor = exports.INDICE_BASE;
+    for (const insumo of exports.INSUMOS_DO_INDICE) {
+        const ocorrencias = eventos.filter((e) => e.tipo === insumo.evento).length;
+        if (ocorrencias === 0)
+            continue;
+        const bruto = insumo.peso * ocorrencias;
+        const desconto = Math.max(bruto, insumo.piso);
+        parcelas.push({
+            evento: insumo.evento,
+            sobre: insumo.sobre,
+            ocorrencias,
+            desconto,
+            noPiso: bruto < insumo.piso,
+        });
+        valor += desconto;
+    }
+    return {
+        valor: Math.max(exports.INDICE_MINIMO, Math.min(exports.INDICE_BASE, Number(valor.toFixed(2)))),
+        base: exports.INDICE_BASE,
+        parcelas,
+        derivado: true,
+    };
+}
+/** Texto de uma linha por parcela, para `ork master` mostrar de onde o numero veio. */
+function textoDoIndice(indice) {
+    const linhas = [`indice ${indice.valor} de ${indice.base} (derivado do ledger, nunca digitado)`];
+    if (indice.parcelas.length === 0) {
+        linhas.push('  nenhum insumo: a entrega nao registrou reversao, GO-FIX, CHECK refeito nem ship barrado');
+        return linhas.join('\n');
+    }
+    for (const p of indice.parcelas) {
+        linhas.push(`  ${p.desconto.toFixed(2).padStart(6)}  ${p.evento} x${p.ocorrencias}${p.noPiso ? ' (no piso)' : ''}`);
+        linhas.push(`          ${p.sobre}`);
+    }
+    return linhas.join('\n');
+}

package/dist/init.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXIMO_PASSO_INIT = void 0;
 exports.raizDoRepo = raizDoRepo;
 exports.nomeDetectado = nomeDetectado;
 exports.baseBranchDetectada = baseBranchDetectada;
@@ -51,6 +52,9 @@ const path = __importStar(require("node:path"));
 const manifest_1 = require("./manifest");
 const slug_1 = require("./slug");
 const util_1 = require("./util");
+const horario_1 = require("./horario");
+const modos_1 = require("./modos");
+exports.PROXIMO_PASSO_INIT = 'Proximo passo: ork doctor; depois ork onboarding para conduzir a entrevista do projeto.';
 /** Raiz do repositorio git, resolvendo tambem o caso de worktree. */
 function raizDoRepo(dirInicial) {
     const r = (0, util_1.exec)('git', ['rev-parse', '--show-toplevel'], dirInicial);
@@ -148,22 +152,34 @@ project:
   abbrev: "${d.abbrev}"
   stage: nascente
 
+owner:
+  # fuso do dono (nome IANA): todo horario mostrado a pessoas usa este fuso.
+  # Ausente: fuso do sistema. Exemplo:
+  # timezone: "${horario_1.FUSO_DE_BRASILIA}"
+
 board:
   adapter: hermes-kanban
   default: default
 
 runtime:
-  # claude-bg despacha \`claude --bg\` (sessao visivel no app e em \`claude agents\`)
+  # Runtimes homologados:
+  #   claude-bg (padrao, mais maduro): despacha \`claude --bg\`, sessao visivel no app
+  #             e em \`claude agents --json\`
+  #   codex: despacha \`codex exec\` headless na sessao autenticada do Codex CLI,
+  #          verificado no rollout de $CODEX_HOME/sessions (requer \`codex login\`)
   adapter: claude-bg
   model: opus
   effort: high
-  # subscription-only: proibido despachar por provider pago (licao dos US$ 16)
+  # subscription-only: proibido despachar por provider pago (cobra por token, fora da assinatura)
   provider_policy: subscription-only
+  # sandbox do runtime codex: read-only | workspace-write | danger-full-access
+  # (danger-full-access SO onde o bubblewrap nao roda; \`ork doctor\` tem a sonda)
+  sandbox: workspace-write
 
 conduction:
   # modo usado quando o pedido do builder nao traz #TAG
   default_mode: classic
-  allowed_modes: [look, ork, classic, maestro, auto]
+  allowed_modes: [${modos_1.ORDEM_DOS_MODOS.join(', ')}]
 
 worktree:
   base_branch: "${d.baseBranch}"
@@ -175,8 +191,17 @@ ${linhaVerify('build', d.verify.build)}
 ${linhaVerify('test', d.verify.test)}
 ${linhaVerify('typecheck', d.verify.typecheck)}
 
+ci:
+  # Ative depois de publicar o workflow e tornar ork-verify um check obrigatório.
+  required_for_ship: false
+  context: ork-verify
+  # command: "npm test" # perfil hermético opcional do runner; sem ele, usa verify acima
+
 concurrency:
   max_parallel_threads: 3
+  # thread despachada sem atividade (ledger parado, sessao nao-working) por mais que
+  # isto NAO ocupa vaga do escalonador: a vaga volta para quem esta pronto para rodar
+  stale_after_min: 240
 
 handoff:
   # gate de tokens (bloco B1): rotaciona a sessao acima destas ocupacoes de janela

package/dist/integracoes-locais.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TESTES_DE_INTEGRACAO_LOCAL = void 0;
+/**
+ * I-53 (RM-037, D17): a lista unica dos testes que exigem integracao local.
+ *
+ * Sao os arquivos que dependem de recurso deliberadamente ausente no runner hospedado do GitHub
+ * (Docker, OrkMind instalado, sessao de runtime). Antes a lista vivia duplicada em `ci.ts` e em
+ * `scripts/test-ci.js`, e as duas copias podiam divergir sem ninguem ver. Agora `ci.ts` importa
+ * daqui, e o script le o mesmo modulo ja compilado em `dist/` (o `test:ci` compila antes).
+ */
+exports.TESTES_DE_INTEGRACAO_LOCAL = new Set([
+    'codex-controller-sensor.test.js', 'consulta-restrita-nativa.test.js', 'decision-identity.test.js',
+    'mcp-git.test.js', 'mcp-server.test.js', 'mcp-ship.test.js', 'mcp-verify.test.js',
+    'memory-native-preparation.test.js', 'memory-native-schema.test.js', 'memory-prospective.test.js',
+    'memory-publication-profile.test.js', 'native-fixture.test.js', 'orkmind-transport.test.js', 'verify-sandbox.test.js',
+]);

package/dist/leases.js

@@ -48,12 +48,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NOME_ARQUIVO_FILA = exports.FAMILIAS_DE_LEASE = exports.TTL_PADRAO_MS = exports.LEASE_MAIN_TREE = void 0;
+exports.NOME_ARQUIVO_FILA = exports.PREFIXO_EXEC = exports.FAMILIAS_DE_LEASE = exports.TTL_PADRAO_MS = exports.LEASE_MAIN_TREE = void 0;
 exports.dirLeases = dirLeases;
+exports.dirLeasesDeExecucao = dirLeasesDeExecucao;
 exports.nomeDeLease = nomeDeLease;
 exports.tipoDoLease = tipoDoLease;
 exports.alvoDoLease = alvoDoLease;
 exports.caminhoLease = caminhoLease;
+exports.regravarLease = regravarLease;
 exports.lerLease = lerLease;
 exports.expirado = expirado;
 exports.globParaRegex = globParaRegex;
@@ -77,7 +79,10 @@ exports.tabelaDeLeases = tabelaDeLeases;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const manifest_1 = require("./manifest");
+const estado_thread_1 = require("./estado-thread");
 const util_1 = require("./util");
+const horario_1 = require("./horario");
+const conducao_texto_1 = require("./conducao-texto");
 /** Nome do lease que serializa o merge na base (visao, paridade 5). */
 exports.LEASE_MAIN_TREE = 'main-tree';
 /** TTL padrao de 30 minutos: um SHIP que passe disso deixou de existir. */
@@ -89,11 +94,22 @@ exports.FAMILIAS_DE_LEASE = {
     path: 'uma regiao de arquivos por glob (colisao entre threads paralelas)',
     board: 'um card do board, para duas threads nao pegarem o mesmo cartao',
     service: 'uma porta de servico local, para dois runs nao subirem no mesmo lugar',
+    exec: 'a EXECUCAO na worktree de uma thread (I-36): um condutor por vez, em qualquer canal',
 };
+/** I-36 (D1): prefixo da familia de execucao, `exec:<thread>`. */
+exports.PREFIXO_EXEC = 'exec';
 /** Diretorio dos leases do projeto. */
 function dirLeases(raiz) {
     return path.join((0, manifest_1.dirEstado)(raiz), 'leases');
 }
+/**
+ * I-36: o lease de execucao mora no estado CANONICO do projeto (o mesmo das threads), nunca no
+ * checkout de quem chamou. Um canal que roda da raiz e outro que roda de uma worktree disputam o
+ * mesmo arquivo; com o diretorio do checkout, cada um teria o seu e os dois executariam juntos.
+ */
+function dirLeasesDeExecucao(raiz) {
+    return path.join((0, manifest_1.dirEstado)((0, estado_thread_1.raizDoEstado)(raiz)), 'leases');
+}
 /**
  * Nome canonico de um lease de familia tipada: `path:core/src/**`, `service:5173`.
  * `main-tree` nao tem alvo: e um so no projeto.
@@ -111,7 +127,8 @@ function tipoDoLease(nome) {
     if (nome === exports.LEASE_MAIN_TREE)
         return 'main-tree';
     const prefixo = nome.split(':')[0];
-    if (prefixo === 'worktree-write' || prefixo === 'path' || prefixo === 'board' || prefixo === 'service') {
+    if (prefixo === 'worktree-write' || prefixo === 'path' || prefixo === 'board' || prefixo === 'service' ||
+        prefixo === exports.PREFIXO_EXEC) {
         return prefixo;
     }
     return 'path';
@@ -127,7 +144,19 @@ function alvoDoLease(nome) {
  * inalterado, o que preserva os leases gravados pelo bloco B1.
  */
 function caminhoLease(raiz, nome) {
-    return path.join(dirLeases(raiz), `${encodeURIComponent(nome)}.json`);
+    const dir = tipoDoLease(nome) === 'exec' ? dirLeasesDeExecucao(raiz) : dirLeases(raiz);
+    return path.join(dir, `${encodeURIComponent(nome)}.json`);
+}
+/**
+ * I-36 (D3): regrava um lease que a propria operacao segura (renovacao do prazo e conversao do
+ * dono), por arquivo temporario e rename: quem le nunca ve o arquivo pela metade.
+ */
+function regravarLease(raiz, lease) {
+    const caminho = caminhoLease(raiz, lease.nome);
+    fs.mkdirSync(path.dirname(caminho), { recursive: true });
+    const temporario = `${caminho}.${process.pid}.tmp`;
+    fs.writeFileSync(temporario, JSON.stringify(lease, null, 2) + '\n', { encoding: 'utf8', mode: 0o644 });
+    fs.renameSync(temporario, caminho);
 }
 /** Le o lease em disco. Arquivo corrompido conta como lease ausente. */
 function lerLease(raiz, nome) {
@@ -253,7 +282,7 @@ function adquirir(raiz, nome, opcoes) {
             if (e.code !== 'EEXIST')
                 throw e;
             const atual = lerLease(raiz, nome);
-            if (atual && !expirado(atual)) {
+            if (opcoes.retomarVencido === false || (atual && !expirado(atual))) {
                 return { ok: false, lease: null, ocupadoPor: atual, tomadoDeVencido: false };
             }
             // Lease vencido ou corrompido: remove e tenta uma unica vez mais.
@@ -292,23 +321,32 @@ function liberar(raiz, nome, thread, forcar = false) {
 }
 /** Todos os leases existentes no projeto, pelo nome canonico gravado no arquivo. */
 function listarLeases(raiz) {
-    const dir = dirLeases(raiz);
-    if (!fs.existsSync(dir))
-        return [];
     const leases = [];
-    for (const arquivo of fs.readdirSync(dir)) {
-        if (!arquivo.endsWith('.json') || arquivo === exports.NOME_ARQUIVO_FILA)
-            continue;
-        try {
-            const bruto = fs.readFileSync(path.join(dir, arquivo), 'utf8');
-            const lease = JSON.parse(bruto);
-            if (lease && typeof lease.nome === 'string')
+    const ler = (dir, soExecucao) => {
+        if (!fs.existsSync(dir))
+            return;
+        for (const arquivo of fs.readdirSync(dir)) {
+            if (!arquivo.endsWith('.json') || arquivo === exports.NOME_ARQUIVO_FILA)
+                continue;
+            try {
+                const lease = JSON.parse(fs.readFileSync(path.join(dir, arquivo), 'utf8'));
+                if (!lease || typeof lease.nome !== 'string')
+                    continue;
+                if (soExecucao && tipoDoLease(lease.nome) !== 'exec')
+                    continue;
                 leases.push(lease);
+            }
+            catch {
+                /* arquivo corrompido conta como lease ausente */
+            }
         }
-        catch {
-            /* arquivo corrompido conta como lease ausente */
-        }
-    }
+    };
+    // I-36: os do checkout, mais os de execucao do estado canonico quando ele e outro diretorio.
+    const local = dirLeases(raiz), canonico = dirLeasesDeExecucao(raiz);
+    const real = (dir) => (fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir));
+    ler(local, false);
+    if (real(local) !== real(canonico))
+        ler(canonico, true);
     return leases.sort((a, b) => a.nome.localeCompare(b.nome));
 }
 /** Leases ativos (nao vencidos) que colidem com o nome pedido. */
@@ -488,8 +526,12 @@ function tabelaDeLeases(raiz) {
         for (const l of leases) {
             const situacao = expirado(l) ? 'VENCIDO (tomavel)' : 'ativo';
             linhas.push(`  ${l.nome.padEnd(28)} [${tipoDoLease(l.nome)}] thread ${l.thread.padEnd(18)} ${situacao}`);
-            linhas.push(`    desde ${l.adquiridoEm} ate ${l.expiraEm} (pid ${l.pid})`);
+            linhas.push(`    desde ${(0, horario_1.formatarDataHora)(l.adquiridoEm)} ate ${(0, horario_1.formatarDataHora)(l.expiraEm)} (pid ${l.pid})`);
             linhas.push(`    motivo: ${l.motivo}`);
+            // I-36: o lease de execucao diz quem conduz, com a mesma linha das outras superficies.
+            const conducao = (0, conducao_texto_1.conducaoDoLease)(l);
+            if (conducao)
+                linhas.push(`    ${(0, conducao_texto_1.linhaDeConducao)(conducao)}`);
         }
     }
     linhas.push('');
@@ -497,12 +539,14 @@ function tabelaDeLeases(raiz) {
     const regiao = fila.filter((p) => p.tipo !== 'main-tree');
     linhas.push(`Fila de merge (lease ${exports.LEASE_MAIN_TREE}): ${merge.length === 0 ? 'vazia' : `${merge.length} na espera`}`);
     merge.forEach((p, i) => {
-        linhas.push(`  ${i + 1}. thread ${p.thread} desde ${p.desdeEm} (bloqueada por ${p.bloqueadaPor})`);
+        linhas.push(`  ${i + 1}. thread ${p.thread} desde ${(0, horario_1.formatarDesde)(p.desdeEm)} (bloqueada por ${p.bloqueadaPor})`);
     });
     linhas.push(`Fila por colisao de regiao: ${regiao.length === 0 ? 'vazia' : `${regiao.length} na espera`}`);
     regiao.forEach((p, i) => {
         linhas.push(`  ${i + 1}. thread ${p.thread} quer ${p.nome}, colide com ${p.colidiuCom} ` +
-            `(thread ${p.bloqueadaPor}) desde ${p.desdeEm}`);
+            `(thread ${p.bloqueadaPor}) desde ${(0, horario_1.formatarDesde)(p.desdeEm)}`);
     });
+    if (leases.length > 0 || fila.length > 0)
+        linhas.push((0, horario_1.legendaDoFuso)());
     return linhas.join('\n');
 }

package/dist/ledger-stats.js

@@ -0,0 +1,272 @@
+"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.parsePeriodo = parsePeriodo;
+exports.coletarEstatisticas = coletarEstatisticas;
+exports.registrarEstimativaPlano = registrarEstimativaPlano;
+exports.textoDasEstatisticas = textoDasEstatisticas;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const thread_1 = require("./thread");
+const ledger_1 = require("./ledger");
+const util_1 = require("./util");
+const horario_1 = require("./horario");
+const MOTIVOS_PREVENTIVOS = new Set([
+    'policy.violation', 'cost.violation', 'verify.regression', 'claims.failed', 'claims.unverifiable',
+]);
+function numero(valor) {
+    return typeof valor === 'number' && Number.isFinite(valor) && valor >= 0 ? valor : null;
+}
+function parsePeriodo(valor, agoraMs = Date.now()) {
+    if (typeof valor === 'number') {
+        if (!Number.isFinite(valor))
+            throw Error('ledger.period.invalid');
+        return valor;
+    }
+    const relativo = /^(\d+(?:\.\d+)?)(m|h|d)$/.exec(valor.trim());
+    if (relativo) {
+        const fator = relativo[2] === 'm' ? 60_000 : relativo[2] === 'h' ? 3_600_000 : 86_400_000;
+        return agoraMs - Number(relativo[1]) * fator;
+    }
+    const absoluto = Date.parse(valor);
+    if (!Number.isFinite(absoluto))
+        throw Error(`ledger.period.invalid: ${valor}`);
+    return absoluto;
+}
+function lerTarifas() {
+    const candidatos = [
+        path.resolve(__dirname, '..', 'assets', 'reference-tariffs-i07.json'),
+        path.resolve(__dirname, '..', '..', 'assets', 'reference-tariffs-i07.json'),
+    ];
+    const arquivo = candidatos.find(fs.existsSync);
+    if (!arquivo)
+        throw Error('ledger.tariffs.unavailable');
+    return JSON.parse(fs.readFileSync(arquivo, 'utf8'));
+}
+function instante(evento) {
+    const valor = Date.parse(evento.ts);
+    return Number.isFinite(valor) ? valor : null;
+}
+function chaveResultado(e, indice) {
+    const sensor = typeof e.sensorResultId === 'string' ? e.sensorResultId : null;
+    const sessao = typeof e.sessionId === 'string' ? e.sessionId : null;
+    return sensor ?? (sessao ? `${sessao}:${String(e.fase ?? '')}` : `linha:${indice}`);
+}
+function modeloDoEvento(e, despachos) {
+    if (typeof e.model === 'string')
+        return e.model;
+    const sessao = typeof e.sessionId === 'string' ? e.sessionId : '';
+    const d = despachos.get(sessao);
+    return typeof d?.model === 'string' ? d.model : null;
+}
+/** Agrega somente fatos observados no ledger; ausencia aparece como cobertura, nunca como zero inventado. */
+function coletarEstatisticas(raiz, filtros) {
+    const agoraMs = filtros.agoraMs ?? Date.now();
+    const desdeMs = parsePeriodo(filtros.desde, agoraMs);
+    const ateMs = filtros.ate === undefined ? agoraMs : parsePeriodo(filtros.ate, agoraMs);
+    if (desdeMs >= ateMs)
+        throw Error('ledger.period.order');
+    if (filtros.thread && !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(filtros.thread))
+        throw Error('ledger.thread.invalid');
+    const tarifas = lerTarifas();
+    const candidatas = (0, thread_1.listarIds)(raiz).map(id => (0, thread_1.lerThread)(raiz, id)).filter(t => !filtros.thread || t.id === filtros.thread);
+    if (filtros.thread && candidatas.length === 0)
+        throw Error(`thread nao encontrada: ${filtros.thread}`);
+    const eventosPorThread = candidatas.map(t => ({ thread: t, eventos: (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, t.id)) }));
+    const selecionadas = eventosPorThread.filter(({ thread, eventos }) => {
+        const criada = eventos.find(e => e.tipo === 'thread_created');
+        const modo = typeof criada?.modo === 'string' ? criada.modo : thread.modo;
+        return !filtros.modo || modo === filtros.modo;
+    });
+    let despachadas = 0, concluidas = 0, retries = 0, ships = 0, duracao = 0;
+    let duracaoMedida = 0, duracaoAusente = 0, tokenMedido = 0, tokenAusente = 0;
+    let input = 0, cachedInput = 0, output = 0, total = 0, custo = 0, precificadas = 0, semTarifa = 0;
+    let esperaMs = 0, esperasFechadas = 0, esperasAbertas = 0, corrompidos = 0;
+    let estimativas = 0, semIaHoras = 0, iaSemOrkHoras = 0;
+    const riscos = {};
+    const leads = [];
+    const fontes = new Set();
+    for (const { eventos } of selecionadas) {
+        corrompidos += eventos.filter(e => e.tipo === 'ledger_corrupted').length;
+        const despachos = new Map();
+        for (const e of eventos)
+            if (e.tipo === 'phase_dispatch' && typeof e.sessionId === 'string')
+                despachos.set(e.sessionId, e);
+        const dentro = (e) => { const t = instante(e); return t !== null && t >= desdeMs && t < ateMs; };
+        const runtimeOk = (e) => {
+            if (!filtros.runtime)
+                return true;
+            if (e.runtime === filtros.runtime)
+                return true;
+            const sessao = typeof e.sessionId === 'string' ? e.sessionId : '';
+            return despachos.get(sessao)?.runtime === filtros.runtime;
+        };
+        despachadas += eventos.filter(e => e.tipo === 'phase_dispatch' && dentro(e) && runtimeOk(e)).length;
+        retries += eventos.filter(e => e.tipo === 'retry_attempt' && dentro(e)).length;
+        ships += eventos.filter(e => e.tipo === 'ship_done' && dentro(e)).length;
+        const resultados = new Map();
+        eventos.forEach((e, i) => {
+            if (e.tipo === 'phase_result' && dentro(e) && runtimeOk(e))
+                resultados.set(chaveResultado(e, i), e);
+        });
+        for (const e of resultados.values()) {
+            concluidas++;
+            const ms = numero(e.duracaoMs);
+            if (ms === null)
+                duracaoAusente++;
+            else {
+                duracao += ms;
+                duracaoMedida++;
+            }
+            const t = e.tokens && typeof e.tokens === 'object' ? e.tokens : null;
+            const tin = numero(t?.input), tcached = numero(t?.cachedInput), tout = numero(t?.output), ttotal = numero(t?.total);
+            if (!t || t.disponivel === false || tin === null || tcached === null || tout === null) {
+                tokenAusente++;
+                continue;
+            }
+            tokenMedido++;
+            input += tin;
+            cachedInput += Math.min(tcached, tin);
+            output += tout;
+            total += ttotal ?? tin + tout;
+            const modelo = modeloDoEvento(e, despachos);
+            const tarifa = modelo ? tarifas.models[modelo] : undefined;
+            if (!tarifa) {
+                semTarifa++;
+                continue;
+            }
+            custo += ((tin - Math.min(tcached, tin)) * tarifa.input + Math.min(tcached, tin) * tarifa.cachedInput + tout * tarifa.output) / tarifas.unitTokens;
+            precificadas++;
+            fontes.add(tarifa.source);
+        }
+        const criada = eventos.find(e => e.tipo === 'thread_created');
+        const criadaMs = criada ? instante(criada) : null;
+        for (const e of eventos.filter(e => e.tipo === 'ship_done' && dentro(e))) {
+            const fim = instante(e);
+            if (criadaMs !== null && fim !== null && fim >= criadaMs)
+                leads.push(fim - criadaMs);
+        }
+        const pedidos = new Map();
+        for (const e of eventos) {
+            if (e.tipo === 'gate_blocked' && e.motivo === 'human.pending') {
+                const chave = typeof e.pedidoId === 'string' ? e.pedidoId : `${String(e.fase ?? '')}:legacy`;
+                const t = instante(e);
+                if (t !== null)
+                    (pedidos.get(chave) ?? (pedidos.set(chave, []), pedidos.get(chave))).push(t);
+            }
+            if (e.tipo === 'human_gate') {
+                const chave = typeof e.pedidoId === 'string' ? e.pedidoId : `${String(e.fase ?? '')}:legacy`;
+                const inicio = pedidos.get(chave)?.shift();
+                const fim = instante(e);
+                if (inicio !== undefined && fim !== null && fim >= inicio) {
+                    const a = Math.max(inicio, desdeMs), b = Math.min(fim, ateMs);
+                    if (b > a)
+                        esperaMs += b - a;
+                    if (fim >= desdeMs && fim < ateMs)
+                        esperasFechadas++;
+                }
+            }
+        }
+        for (const aberturas of pedidos.values())
+            for (const inicio of aberturas) {
+                const a = Math.max(inicio, desdeMs);
+                if (ateMs > a)
+                    esperaMs += ateMs - a;
+                if (inicio < ateMs)
+                    esperasAbertas++;
+            }
+        for (const e of eventos.filter(e => e.tipo === 'gate_blocked' && dentro(e))) {
+            const motivo = typeof e.motivo === 'string' ? e.motivo : '';
+            if (MOTIVOS_PREVENTIVOS.has(motivo))
+                riscos[motivo] = (riscos[motivo] ?? 0) + 1;
+        }
+        for (const e of eventos.filter(e => e.tipo === 'plan_estimate' && dentro(e))) {
+            const a = numero(e.semIaHoras), b = numero(e.iaSemOrkHoras);
+            if (a !== null && b !== null) {
+                estimativas++;
+                semIaHoras += a;
+                iaSemOrkHoras += b;
+            }
+        }
+    }
+    const observacoes = [];
+    if (tokenAusente)
+        observacoes.push(`${tokenAusente} sessao(oes) sem medicao de tokens`);
+    if (semTarifa)
+        observacoes.push(`${semTarifa} sessao(oes) com tokens, mas sem tarifa de referencia`);
+    if (corrompidos)
+        observacoes.push(`${corrompidos} linha(s) de ledger corrompida(s) ignorada(s)`);
+    return {
+        schema: 'ork.ledger-stats/v1', periodo: { desde: new Date(desdeMs).toISOString(), ate: new Date(ateMs).toISOString(), intervalo: '[desde,ate)' },
+        filtros: { thread: filtros.thread ?? null, modo: filtros.modo ?? null, runtime: filtros.runtime ?? null }, threads: selecionadas.length,
+        sessoes: { despachadas, concluidas, retries }, throughput: { ships },
+        execucao: { milissegundos: duracao, horas: duracao / 3_600_000, cobertura: { medidas: duracaoMedida, semMedida: duracaoAusente } },
+        tokens: { input, cachedInput, uncachedInput: input - cachedInput, output, total, cobertura: { medidas: tokenMedido, semMedida: tokenAusente } },
+        custoReferencia: { natureza: tarifas.nature, moeda: tarifas.currency, valor: precificadas ? Number(custo.toFixed(6)) : null, sessoesPrecificadas: precificadas, sessoesSemTarifa: semTarifa, tarifasVerificadasEm: tarifas.verifiedAt, fontes: [...fontes].sort() },
+        leadTime: { mediaMs: leads.length ? leads.reduce((a, b) => a + b, 0) / leads.length : null, amostras: leads.length },
+        esperaHumana: { milissegundos: esperaMs, fechadas: esperasFechadas, abertas: esperasAbertas },
+        riscosPreventivos: { total: Object.values(riscos).reduce((a, b) => a + b, 0), porMotivo: riscos },
+        estimativasPlano: { amostras: estimativas, semIaHoras, iaSemOrkHoras },
+        qualidade: { ledgersCorrompidos: corrompidos, observacoes },
+    };
+}
+function registrarEstimativaPlano(raiz, threadId, dados) {
+    if (![dados.semIaHoras, dados.iaSemOrkHoras].every(v => Number.isFinite(v) && v > 0))
+        throw Error('ledger.estimate.hours-positive');
+    if (![dados.por, dados.metodo, dados.premissas].every(v => v.trim() !== ''))
+        throw Error('ledger.estimate.provenance-required');
+    const thread = (0, thread_1.listarIds)(raiz).map(id => (0, thread_1.lerThread)(raiz, id)).find(t => t.id === threadId);
+    if (!thread)
+        throw Error(`thread nao encontrada: ${threadId}`);
+    const head = (0, util_1.exec)('git', ['rev-parse', 'HEAD'], raiz);
+    if (!head.ok)
+        throw Error('ledger.estimate.head-unavailable');
+    return (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, 'plan_estimate', { fase: 'PLAN', unidade: 'hours', semIaHoras: dados.semIaHoras, iaSemOrkHoras: dados.iaSemOrkHoras, por: dados.por, metodo: dados.metodo, premissas: dados.premissas, incerteza: dados.incerteza ?? 'nao informada', head: head.stdout.trim() });
+}
+function textoDasEstatisticas(r) {
+    const dinheiro = r.custoReferencia.valor === null ? 'sem cobertura' : `USD ${r.custoReferencia.valor.toFixed(6)}`;
+    return [
+        `Ledger stats  ${(0, horario_1.formatarDataHora)(r.periodo.desde)} ate ${(0, horario_1.formatarDataHoraRotulada)(r.periodo.ate)} ${r.periodo.intervalo}`,
+        `  threads/sessoes  ${r.threads} / ${r.sessoes.concluidas} concluidas (${r.sessoes.despachadas} despachos)`,
+        `  throughput       ${r.throughput.ships} ship(s); ${r.sessoes.retries} retry(ies)`,
+        `  execucao         ${r.execucao.horas.toFixed(2)} h (${r.execucao.cobertura.medidas} medidas; ${r.execucao.cobertura.semMedida} ausentes)`,
+        `  tokens           ${r.tokens.total} total; input ${r.tokens.input} (cached ${r.tokens.cachedInput}); output ${r.tokens.output}`,
+        `  custo referencia ${dinheiro} — estimativa por tarifa publica, nao gasto/fatura`,
+        `  espera humana    ${(r.esperaHumana.milissegundos / 3_600_000).toFixed(2)} h; ${r.esperaHumana.abertas} aberta(s)`,
+        `  riscos evitados  ${r.riscosPreventivos.total} gate(s) preventivo(s)`,
+        `  estimativas PLAN ${r.estimativasPlano.amostras} amostra(s)`,
+        ...r.qualidade.observacoes.map(o => `  cobertura         ${o}`),
+    ].join('\n');
+}