@orkastery/cli 0.2.0 → 0.3.0

package/dist/horario.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * I-35: horário do dono em toda superfície humana (domicílio único).
+ *
+ * Ordem do dono em 19/09/2026: nunca mais horário UTC para se comunicar com ele. Todo
+ * horário que o Orkastery mostra a uma pessoa passa por aqui. O fuso sai do manifesto
+ * (`owner.timezone`, nome IANA), com o fuso do sistema como default e UTC como piso; o
+ * formato é o brasileiro (`19/09 15:16`) e o fuso aparece uma vez por mensagem.
+ *
+ * Dado de máquina (ledger, JSON, recibos, hashes) continua em UTC ISO: este módulo só
+ * formata na saída, nunca reescreve o que é gravado. Ele também não importa o manifesto
+ * (sem ciclo): quem conhece o projeto registra a fonte com `registrarFonteDoFuso`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUSO_DE_BRASILIA = exports.CHAVE_DO_FUSO = void 0;
+exports.normalizarFuso = normalizarFuso;
+exports.fusoDoSistema = fusoDoSistema;
+exports.lerFusoDoDono = lerFusoDoDono;
+exports.fusoDoManifesto = fusoDoManifesto;
+exports.registrarFonteDoFuso = registrarFonteDoFuso;
+exports.definirFusoDoDono = definirFusoDoDono;
+exports.fusoDoDono = fusoDoDono;
+exports.partesLocais = partesLocais;
+exports.dataLocal = dataLocal;
+exports.duracaoCurta = duracaoCurta;
+exports.duracaoRelativa = duracaoRelativa;
+exports.rotuloDoFuso = rotuloDoFuso;
+exports.legendaDoFuso = legendaDoFuso;
+exports.formatarDataHora = formatarDataHora;
+exports.formatarHora = formatarHora;
+exports.formatarDataHoraRotulada = formatarDataHoraRotulada;
+exports.formatarPrazo = formatarPrazo;
+exports.formatarDesde = formatarDesde;
+exports.localizarTexto = localizarTexto;
+exports.localizarTextoRotulado = localizarTextoRotulado;
+exports.CHAVE_DO_FUSO = 'owner.timezone';
+/** Único fuso com nome próprio no rótulo; exemplo da documentação e do `ork init`. */
+exports.FUSO_DE_BRASILIA = 'America/Sao_Paulo';
+/** Forma canônica do Intl (`america/sao_paulo` vira `America/Sao_Paulo`) ou undefined. */
+function normalizarFuso(bruto) {
+    if (typeof bruto !== 'string' || bruto.trim() === '')
+        return undefined;
+    try {
+        return new Intl.DateTimeFormat('en-US', { timeZone: bruto.trim() }).resolvedOptions().timeZone || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fuso do sistema (`TZ` ou configuração do SO), com piso UTC quando nada resolve. */
+function fusoDoSistema() {
+    try {
+        return normalizarFuso(Intl.DateTimeFormat().resolvedOptions().timeZone) ?? 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+/** Valor bruto de `owner.timezone`: válido vale; ausente cai no sistema; inválido avisa. */
+function lerFusoDoDono(bruto) {
+    const fuso = normalizarFuso(bruto);
+    if (fuso)
+        return { fuso, origem: 'manifesto' };
+    const sistema = fusoDoSistema();
+    if (bruto === undefined || bruto === null || bruto === '')
+        return { fuso: sistema, origem: 'sistema' };
+    return {
+        fuso: sistema,
+        origem: 'sistema',
+        aviso: `${exports.CHAVE_DO_FUSO} invalido (${JSON.stringify(bruto).slice(0, 80)}): usando o fuso do sistema ` +
+            `(${sistema}); informe um nome IANA, ex.: ${exports.FUSO_DE_BRASILIA}`,
+    };
+}
+/** Fuso de um manifesto já carregado; o aviso de valor inválido vem de `avisos`. */
+function fusoDoManifesto(carregado) {
+    const configurado = carregado?.manifesto.owner?.timezone;
+    if (configurado)
+        return lerFusoDoDono(configurado);
+    const aviso = carregado?.avisos?.find(a => a.startsWith(`${exports.CHAVE_DO_FUSO} `));
+    return { fuso: fusoDoSistema(), origem: 'sistema', ...(aviso ? { aviso } : {}) };
+}
+let fonte;
+let resolvido;
+let fixo = false;
+let avisado = false;
+/**
+ * O ponto de entrada (CLI no cwd, MCP no `--project`) diz de onde vem o fuso. A leitura é
+ * preguiçosa: comando que não mostra horário não carrega nada a mais. Um fuso fixado por
+ * `definirFusoDoDono` prevalece.
+ */
+function registrarFonteDoFuso(f) {
+    if (fixo)
+        return;
+    fonte = f;
+    resolvido = undefined;
+    avisado = false;
+}
+/** Fixa o fuso do processo (testes, host que já resolveu); undefined volta ao default. */
+function definirFusoDoDono(fuso) {
+    fonte = undefined;
+    avisado = false;
+    fixo = fuso !== undefined;
+    resolvido = fuso === undefined ? undefined : lerFusoDoDono(fuso);
+}
+/** Fuso do dono deste processo; o aviso de valor inválido sai no stderr uma única vez. */
+function fusoDoDono() {
+    if (!resolvido) {
+        try {
+            resolvido = fonte ? fonte() : { fuso: fusoDoSistema(), origem: 'sistema' };
+        }
+        catch {
+            resolvido = { fuso: fusoDoSistema(), origem: 'sistema' };
+        }
+    }
+    if (resolvido.aviso && !avisado) {
+        avisado = true;
+        process.stderr.write(`aviso: ${resolvido.aviso}\n`);
+    }
+    return resolvido;
+}
+const formatadores = new Map();
+const ISO_SEM_FUSO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
+/** Milissegundos do instante; data-hora sem fuso é ambígua e vira NaN (sem chute). */
+function instante(v) {
+    if (v === undefined)
+        return Date.now();
+    if (v === null)
+        return NaN;
+    if (v instanceof Date)
+        return v.getTime();
+    if (typeof v === 'number')
+        return v;
+    if (typeof v !== 'string' || ISO_SEM_FUSO.test(v.trim()))
+        return NaN;
+    return Date.parse(v);
+}
+/** Ano, mês, dia, hora, minuto e segundo do instante no fuso pedido (relógio de 24 h). */
+function partesLocais(quando, fuso = fusoDoDono().fuso) {
+    const ms = instante(quando);
+    if (!Number.isFinite(ms))
+        throw new Error('data inválida');
+    let f = formatadores.get(fuso);
+    if (!f) {
+        f = new Intl.DateTimeFormat('en-US', { timeZone: fuso, year: 'numeric', month: '2-digit', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' });
+        formatadores.set(fuso, f);
+    }
+    const p = Object.fromEntries(f.formatToParts(new Date(ms)).map(x => [x.type, x.value]));
+    return { ano: p.year, mes: p.month, dia: p.day, hora: p.hour, minuto: p.minute, segundo: p.second };
+}
+/** Data local `AAAA-MM-DD` do instante no fuso (chave de dia, não texto para pessoa). */
+function dataLocal(quando, fuso = fusoDoDono().fuso) {
+    const p = partesLocais(quando, fuso);
+    return `${p.ano}-${p.mes}-${p.dia}`;
+}
+// ---------------------------------------------------------------------------
+// Texto para pessoa
+// ---------------------------------------------------------------------------
+/** Duração curta de minutos inteiros: `45min`, `1h00`, `2d 16h`. */
+function duracaoCurta(minutos) {
+    if (minutos < 60)
+        return `${minutos}min`;
+    const horas = Math.floor(minutos / 60);
+    if (horas < 24)
+        return `${horas}h${String(minutos % 60).padStart(2, '0')}`;
+    return `${Math.floor(horas / 24)}d ${String(horas % 24).padStart(2, '0')}h`;
+}
+/** Duração até ou desde agora: abaixo de 1 min diz `menos de 1 min`, nunca `0min`. */
+function duracaoRelativa(minutos) {
+    return minutos < 1 ? 'menos de 1 min' : duracaoCurta(minutos);
+}
+function sigla(fuso, ms) {
+    try {
+        return new Intl.DateTimeFormat('pt-BR', { timeZone: fuso, timeZoneName: 'short' })
+            .formatToParts(new Date(ms)).find(p => p.type === 'timeZoneName')?.value ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Como o fuso aparece entre parênteses: `horário de Brasília`, `UTC`, `Europe/Lisbon, GMT+1`. */
+function rotuloDoFuso(fuso = fusoDoDono().fuso, quando) {
+    if (fuso === exports.FUSO_DE_BRASILIA)
+        return 'horário de Brasília';
+    if (fuso === 'UTC')
+        return 'UTC';
+    const ms = instante(quando);
+    const s = sigla(fuso, Number.isFinite(ms) ? ms : Date.now());
+    return s && s !== fuso ? `${fuso}, ${s}` : fuso;
+}
+/** Legenda de mensagem com vários horários: `Horários de Brasília.` */
+function legendaDoFuso(fuso = fusoDoDono().fuso, quando) {
+    if (fuso === exports.FUSO_DE_BRASILIA)
+        return 'Horários de Brasília.';
+    return `Horários em ${rotuloDoFuso(fuso, quando)}.`;
+}
+/** `19/09 15:16`; `19/09/2025 15:16` quando o ano não é o corrente do dono. Inválido volta como veio. */
+function formatarDataHora(quando, opcoes = {}) {
+    const ms = instante(quando ?? null);
+    if (!Number.isFinite(ms))
+        return quando === null || quando === undefined ? '' : String(quando);
+    const fuso = opcoes.fuso ?? fusoDoDono().fuso;
+    const p = partesLocais(ms, fuso), a = partesLocais(instante(opcoes.agora), fuso);
+    return `${p.dia}/${p.mes}${p.ano !== a.ano ? `/${p.ano}` : ''} ${p.hora}:${p.minuto}` +
+        (opcoes.segundos ? `:${p.segundo}` : '');
+}
+/** Só `15:16` quando é hoje no fuso do dono; senão a data-hora completa. */
+function formatarHora(quando, opcoes = {}) {
+    const ms = instante(quando ?? null);
+    if (!Number.isFinite(ms))
+        return formatarDataHora(quando, opcoes);
+    const fuso = opcoes.fuso ?? fusoDoDono().fuso;
+    const p = partesLocais(ms, fuso), a = partesLocais(instante(opcoes.agora), fuso);
+    if (p.ano !== a.ano || p.mes !== a.mes || p.dia !== a.dia)
+        return formatarDataHora(ms, { ...opcoes, fuso });
+    return `${p.hora}:${p.minuto}${opcoes.segundos ? `:${p.segundo}` : ''}`;
+}
+/** Data-hora absoluta com o fuso entre parênteses: estável para JSON de exibição. */
+function formatarDataHoraRotulada(quando, opcoes = {}) {
+    const ms = instante(quando ?? null);
+    if (!Number.isFinite(ms))
+        return formatarDataHora(quando, opcoes);
+    const fuso = opcoes.fuso ?? fusoDoDono().fuso;
+    return `${formatarDataHora(ms, { ...opcoes, fuso })} (${rotuloDoFuso(fuso, ms)})`;
+}
+/**
+ * Prazo: `19/09 16:16, em 1h00` ou `19/09 14:00, venceu há 5min`; a menos de 1 min, `em menos de
+ * 1 min` ou `venceu há menos de 1 min`. `rotulo` põe o fuso.
+ */
+function formatarPrazo(quando, opcoes = {}) {
+    const ms = instante(quando ?? null);
+    if (!Number.isFinite(ms))
+        return formatarDataHora(quando, opcoes);
+    const fuso = opcoes.fuso ?? fusoDoDono().fuso;
+    const base = opcoes.rotulo ? formatarDataHoraRotulada(ms, { ...opcoes, fuso }) : formatarDataHora(ms, { ...opcoes, fuso });
+    const diferenca = ms - instante(opcoes.agora);
+    return diferenca >= 0
+        ? `${base}, em ${duracaoRelativa(diferenca < 60000 ? 0 : Math.ceil(diferenca / 60000))}`
+        : `${base}, venceu há ${duracaoRelativa(Math.floor(-diferenca / 60000))}`;
+}
+/**
+ * Desde: `11:00 (há 4h16)` hoje, `16/09 22:53 (há 2d 16h)` em outro dia, `(há menos de 1 min)`
+ * no limite. Instante 1 min ou mais à frente do relógio diz `relógio adiantado`. `rotulo` põe o fuso.
+ */
+function formatarDesde(quando, opcoes = {}) {
+    const ms = instante(quando ?? null);
+    if (!Number.isFinite(ms))
+        return formatarDataHora(quando, opcoes);
+    const fuso = opcoes.fuso ?? fusoDoDono().fuso;
+    const diferenca = instante(opcoes.agora) - ms;
+    const prefixo = `${formatarHora(ms, { ...opcoes, fuso })} (${opcoes.rotulo ? `${rotuloDoFuso(fuso, ms)}, ` : ''}`;
+    if (diferenca <= -60000)
+        return `${prefixo}relógio adiantado: ${duracaoCurta(Math.floor(-diferenca / 60000))} no futuro)`;
+    return `${prefixo}há ${duracaoRelativa(Math.max(0, Math.floor(diferenca / 60000)))})`;
+}
+/** ISO completo com `Z` ou offset; sem fuso fica como está (ambíguo, sem chute). */
+const ISO_EM_TEXTO = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})\b/g;
+/**
+ * Localiza os instantes ISO de um texto já composto (detalhe, evidência, correção) na hora
+ * de exibir. O dado gravado continua com o ISO; quem exibe põe a legenda uma vez.
+ */
+function localizarTexto(texto, opcoes = {}) {
+    return texto.replace(ISO_EM_TEXTO, iso => formatarDataHora(iso, opcoes));
+}
+/** Como `localizarTexto`, e rotula o fuso no fim quando algum horário foi trocado (campo de uma linha). */
+function localizarTextoRotulado(texto, opcoes = {}) {
+    const local = localizarTexto(texto, opcoes);
+    return local === texto ? texto : `${local} (${rotuloDoFuso(opcoes.fuso ?? fusoDoDono().fuso, opcoes.agora)})`;
+}

package/dist/hosts.js

@@ -12,9 +12,12 @@
  *  - **Uma copia so do catalogo.** O instalador copia de `skills/` e `references/`, sempre da
  *    mesma raiz, e grava a origem e o sha256 de cada arquivo em `INSTALADO.json`. Duas copias
  *    do catalogo divergem, e a divergencia so aparece quando ja custou uma entrega.
- *  - **Sobrescrever e decisao, nao efeito colateral.** Arquivo que ja existe diferente do que
- *    seria escrito faz a instalacao parar e pedir `--force`, listando os arquivos. Instalador
- *    que apaga edicao alheia em silencio e o mesmo defeito que o guard `git add -A` bloqueia.
+ *  - **Sobrescrever e decisao, nao efeito colateral.** Arquivo que ja existe diferente do
+ *    que seria escrito e CLASSIFICADO pelo recibo (I-43, D5): o que so mudou no catalogo a
+ *    instalacao resolve sozinha, porque sobrescrever copia intacta nao perde trabalho de
+ *    ninguem; o que a pessoa editou barra, com o diff na tela e as duas saidas por arquivo
+ *    (`--aceitar-catalogo`, `--manter-copia`). Instalador que apaga edicao alheia em
+ *    silencio e o mesmo defeito que o guard `git add -A` bloqueia.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -50,8 +53,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ORDEM_DOS_HOSTS = exports.HOSTS = void 0;
+exports.ORDEM_DOS_HOSTS = exports.HOSTS = exports.MAESTRO_HOST_SURFACES = exports.BRAIN_HOST_SURFACES = void 0;
 exports.parseHost = parseHost;
+exports.lerRecibo = lerRecibo;
+exports.classificarDivergencia = classificarDivergencia;
 exports.renderizarArquivo = renderizarArquivo;
 exports.instalarAdaptador = instalarAdaptador;
 exports.tabelaDeHosts = tabelaDeHosts;
@@ -59,13 +64,24 @@ exports.textoDosPitfalls = textoDosPitfalls;
 exports.textoDaInstalacao = textoDaInstalacao;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
+exports.BRAIN_HOST_SURFACES = {
+    hermes: 'cli', openclaw: 'cli', 'claude-code': 'mcp', codex: 'mcp',
+};
+/** Superfícies instaladas; a presença do arquivo não comprova ativação live. */
+exports.MAESTRO_HOST_SURFACES = {
+    codex: { entry: 'skills/ork/SKILL.md', transport: 'mcp', operation: 'ork_maestro' },
+    'claude-code': { entry: 'commands/ork.md', transport: 'mcp', operation: 'ork_maestro' },
+    hermes: { entry: 'bin/ork-maestro.sh', transport: 'argv', operation: 'maestro' },
+    openclaw: { entry: 'dist/index.js', transport: 'argv', operation: 'maestro' },
+};
 const path = __importStar(require("node:path"));
 const catalogo_1 = require("./catalogo");
 const util_1 = require("./util");
+const versao_1 = require("./versao");
 exports.HOSTS = {
     'claude-code': {
         host: 'claude-code',
-        descricao: 'Plugin com as 17 skills, 6 subagentes de fase, os comandos /goal ... /master e o guard PreToolUse',
+        descricao: 'Plugin com as skills do catalogo, subagentes de fase, entrada /orkastery:ork e hooks do Orkastery',
         destinoPadrao: '.claude',
         subdir: path.join('plugins', 'orkastery'),
         levaCatalogo: true,
@@ -77,7 +93,7 @@ exports.HOSTS = {
             },
             {
                 titulo: 'duas copias do catalogo divergem',
-                detalhe: 'a fonte unica e skills/ na raiz do produto; o INSTALADO.json guarda a origem e o sha256 de cada arquivo, e reinstalar com --force ressincroniza. Editar a copia instalada e bandeira vermelha',
+                detalhe: 'a fonte unica e skills/ na raiz do produto; o INSTALADO.json guarda a origem e o sha256 de cada arquivo, e reinstalar CLASSIFICA cada divergencia por ele: o que so mudou no catalogo ressincroniza sozinho, o que voce editou barra e pede decisao por arquivo (--aceitar-catalogo ou --manter-copia). Editar a copia instalada e bandeira vermelha',
                 prova: 'ork adapter install claude-code --dry-run   # mostra o que divergiu do catalogo',
             },
             {
@@ -87,6 +103,30 @@ exports.HOSTS = {
             },
         ],
     },
+    codex: {
+        host: 'codex',
+        descricao: 'Entrada $ork e catalogo de conducao em skills locais do projeto, sem configuracao global',
+        destinoPadrao: '.agents',
+        subdir: path.join('skills', 'orkastery'),
+        levaCatalogo: true,
+        pitfalls: [
+            {
+                titulo: 'skills instaladas fora do projeto da sessao',
+                detalhe: 'Codex descobre .agents/skills a partir do diretorio da sessao ate a raiz do repositorio; outra worktree precisa da sua propria instalacao e comprovacao de descoberta',
+                prova: 'No Codex aberto no projeto instalado: $ork',
+            },
+            {
+                titulo: 'copia instalada diferente do catalogo',
+                detalhe: 'o recibo INSTALADO.json registra os arquivos e hashes dentro da pasta propria orkastery; uma edicao divergente barra a reinstalacao sem substituir arquivos de outras skills',
+                prova: 'ork adapter install codex --dry-run',
+            },
+            {
+                titulo: 'skill confundida com autorizacao de runtime',
+                detalhe: 'instalar instrucoes nao habilita permissoes, hooks ou sandbox nem altera AGENTS.md; gates e preflight continuam no nucleo, e descoberta nao prova a jornada conversacional',
+                prova: 'ork doctor',
+            },
+        ],
+    },
     hermes: {
         host: 'hermes',
         descricao: 'Skill roteadora fina, plugin que a declara e script de abertura de thread',
@@ -113,19 +153,19 @@ exports.HOSTS = {
     },
     openclaw: {
         host: 'openclaw',
-        descricao: 'openclaw.plugin.json com as tools ork_*, cada uma uma chamada de CLI',
+        descricao: 'extensao do OpenClaw 2026.7.1 (package.json + dist/index.js) com as tools ork_*, cada uma uma chamada de CLI',
         destinoPadrao: '.openclaw',
-        subdir: '',
+        subdir: 'extensions/orkastery',
         levaCatalogo: false,
         pitfalls: [
             {
                 titulo: 'placeholder {{ork_bin}} que fica no arquivo',
-                detalhe: 'o host executa o vetor de comando como ele esta: um placeholder nao renderizado vira "comando nao encontrado" em toda tool, e a sessao so descobre depois de ja ter aberto thread na cabeca do agente',
-                prova: 'grep -c "{{" <destino>/openclaw.plugin.json   # precisa devolver 0',
+                detalhe: 'o entry executa o binario como ele esta: um placeholder nao renderizado cai no fallback (ORK_BIN ou o ork do PATH), e sem o fallback vira "comando nao encontrado" em toda tool, que a sessao so descobre depois de ja ter aberto thread na cabeca do agente',
+                prova: 'grep -c "{{" <destino>/extensions/orkastery/dist/index.js   # precisa devolver 0',
             },
             {
                 titulo: 'argumento com espaco quebrado em varios argumentos',
-                detalhe: 'cada tool declara o comando como VETOR, nunca como string de shell, para o pedido do builder chegar inteiro em --prompt; string de shell aqui vira injecao de comando com o texto do builder dentro',
+                detalhe: 'cada tool monta o comando como VETOR de argv, nunca como string de shell, para o pedido do builder chegar inteiro em --prompt; string de shell aqui vira injecao de comando com o texto do builder dentro',
                 prova: 'ork_phase_run com um prompt de varias linhas, conferido em ork phase list <thread>',
             },
             {
@@ -136,12 +176,14 @@ exports.HOSTS = {
         ],
     },
 };
-exports.ORDEM_DOS_HOSTS = ['claude-code', 'hermes', 'openclaw'];
+exports.ORDEM_DOS_HOSTS = ['claude-code', 'codex', 'hermes', 'openclaw'];
 /** Reconhece o nome do host, com os apelidos que o builder costuma digitar. */
 function parseHost(bruto) {
     const limpo = (bruto ?? '').trim().toLowerCase();
     if (limpo === 'claude-code' || limpo === 'claude' || limpo === 'claudecode')
         return 'claude-code';
+    if (limpo === 'codex')
+        return 'codex';
     if (limpo === 'hermes')
         return 'hermes';
     if (limpo === 'openclaw' || limpo === 'open-claw')
@@ -152,6 +194,37 @@ function parseHost(bruto) {
 const RENDERIZAVEIS = new Set(['.md', '.json', '.sh', '.js', '.yaml', '.yml', '.txt']);
 /** Extensoes que sao instaladas com bit de execucao. */
 const EXECUTAVEIS = new Set(['.sh', '.js']);
+/** Le o recibo do destino. Ausente ou ilegivel devolve null: nao se adivinha recibo. */
+function lerRecibo(destino) {
+    const caminho = path.join(destino, 'INSTALADO.json');
+    if (!fs.existsSync(caminho))
+        return null;
+    try {
+        const bruto = JSON.parse(fs.readFileSync(caminho, 'utf8'));
+        return Array.isArray(bruto?.arquivos) ? bruto : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classifica UMA divergencia usando o recibo (I-43, D5).
+ *
+ * As tres comparacoes sao entre tres shas: o do catalogo AGORA, o da copia AGORA, e o
+ * que o recibo gravou QUANDO instalou. Sem o terceiro nao ha classificacao possivel, e
+ * e por isso que `sem-recibo` pergunta em vez de chutar.
+ */
+function classificarDivergencia(shaDoCatalogo, shaDaCopia, shaDoRecibo) {
+    if (!shaDoRecibo)
+        return 'sem-recibo';
+    const copiaIntacta = shaDaCopia === shaDoRecibo;
+    const catalogoIntacto = shaDoCatalogo === shaDoRecibo;
+    if (copiaIntacta && !catalogoIntacto)
+        return 'catalogo-andou';
+    if (catalogoIntacto && !copiaIntacta)
+        return 'copia-editada';
+    return 'ambos-andaram';
+}
 function sha256(conteudo) {
     return (0, node_crypto_1.createHash)('sha256').update(conteudo).digest('hex');
 }
@@ -190,13 +263,14 @@ function instalarAdaptador(host, opcoes = {}) {
         ? path.resolve(projeto, opcoes.dir)
         : path.join(projeto, def.destinoPadrao);
     const destino = def.subdir ? path.join(base, def.subdir) : base;
-    const orkBin = opcoes.orkBin ?? (0, util_1.noPath)('ork') ?? path.join(catalogo, 'core', 'dist', 'index.js');
-    const versao = opcoes.versao ?? '0.2.0';
+    const orkBin = opcoes.orkBin ?? (0, util_1.noPath)('ork') ?? (0, catalogo_1.cliDoCatalogo)(catalogo);
+    const versao = opcoes.versao ?? versao_1.VERSAO_DO_ORK;
     const dirDoHost = path.join(catalogo, 'adapters', host);
     if (!fs.existsSync(dirDoHost)) {
         throw new Error(`adaptador do host ${host} nao existe em ${dirDoHost}`);
     }
-    const fontes = listarArquivos(dirDoHost);
+    const fontes = listarArquivos(dirDoHost).map(fonte => host === 'hermes' && fonte.relativo.startsWith('hitl-ingress/')
+        ? { ...fonte, relativo: fonte.relativo.replace(/^hitl-ingress\//, 'plugins/orkastery-hitl/') } : fonte);
     if (def.levaCatalogo) {
         for (const skill of (0, catalogo_1.skillsDoCatalogo)(catalogo)) {
             fontes.push({
@@ -208,6 +282,24 @@ function instalarAdaptador(host, opcoes = {}) {
             fontes.push({ origem: ref, relativo: path.posix.join('references', path.basename(ref)) });
         }
     }
+    // I-43 (D5): o recibo e lido UMA vez, antes de classificar, e e ele que transforma
+    // "divergente" em um dos quatro motivos.
+    const recibo = lerRecibo(destino);
+    /*
+     * I-43 (D5), segundo defeito medido em M3: a DETECCAO falhava em silencio quando o
+     * `--dir` apontava para a raiz.
+     *
+     * `--dir` e o destino COMPLETO, nao a raiz do projeto. Como o destino padrao do
+     * hermes e `.hermes`, passar `--dir $HOME` e o erro natural, e ele devolvia
+     * "22 novos, 0 divergentes" com saida 0: a copia editada passava despercebida, e a
+     * unica coisa que o recibo existe para pegar nao era pega.
+     *
+     * Agora o comando DIZ que encontrou o recibo um nivel abaixo, em vez de reportar
+     * tudo novo. Ele nao corrige sozinho: adivinhar o destino do operador seria trocar
+     * um silencio por outro.
+     */
+    const caminhoVizinho = def.destinoPadrao ? path.join(destino, def.destinoPadrao) : null;
+    const reciboVizinho = !recibo && caminhoVizinho && lerRecibo(caminhoVizinho) ? caminhoVizinho : null;
     const arquivos = [];
     for (const fonte of fontes) {
         const ext = path.extname(fonte.origem);
@@ -217,13 +309,21 @@ function instalarAdaptador(host, opcoes = {}) {
             : bruto;
         const alvo = path.join(destino, fonte.relativo);
         let estado = 'novo';
+        let divergencia;
         if (fs.existsSync(alvo)) {
-            estado = sha256(fs.readFileSync(alvo)) === sha256(conteudo) ? 'igual' : 'sobrescrito';
+            const shaDaCopia = sha256(fs.readFileSync(alvo));
+            const shaDoCatalogo = sha256(conteudo);
+            estado = shaDaCopia === shaDoCatalogo ? 'igual' : 'sobrescrito';
+            if (estado === 'sobrescrito') {
+                // I-43 (D5): o recibo responde POR QUE divergiu, em vez de so dizer que divergiu.
+                divergencia = classificarDivergencia(shaDoCatalogo, shaDaCopia, recibo?.arquivos.find((x) => x.arquivo === fonte.relativo)?.sha256);
+            }
         }
         arquivos.push({
             origem: fonte.origem,
             destino: alvo,
             relativo: fonte.relativo,
+            ...(divergencia ? { divergencia } : {}),
             sha256: sha256(conteudo),
             bytes: conteudo.length,
             executavel: EXECUTAVEIS.has(ext),
@@ -231,14 +331,35 @@ function instalarAdaptador(host, opcoes = {}) {
         });
     }
     const conflitos = arquivos.filter((a) => a.estado === 'sobrescrito');
-    const barrado = conflitos.length > 0 && opcoes.force !== true;
+    /**
+     * I-43 (D5): a divergencia continua sendo DETECTADA; ela deixa de BARRAR quando e
+     * segura.
+     *
+     * `catalogo-andou` significa que a copia esta exatamente como foi instalada e quem
+     * mudou foi o catalogo. Sobrescrever isso nao perde trabalho de ninguem, e e a maior
+     * parte do que aparece num destino real: o regime antigo barrava esses junto com os
+     * demais e mandava o operador descobrir sozinho qual importava, que e a arqueologia de
+     * madrugada que o GOAL mediu.
+     *
+     * O resto PERGUNTA, e e o que R1 exige: resolver `ambos-andaram` sozinho descartaria
+     * a edicao manual sem ninguem ver, que e o defeito silencioso com outro nome.
+     */
+    // I-43 (D5): a decisao do operador por ARQUIVO, que e o que faz `--force` deixar de
+    // ser o unico caminho. `--force` continua existindo como instrumento cego.
+    const decididos = new Set([...(opcoes.aceitarCatalogo ?? []), ...(opcoes.manterCopia ?? [])]);
+    const manter = new Set(opcoes.manterCopia ?? []);
+    const precisamDeDecisao = conflitos.filter((a) => a.divergencia !== 'catalogo-andou' && !decididos.has(a.relativo));
+    const barrado = precisamDeDecisao.length > 0 && opcoes.force !== true;
     const resultado = {
         host,
+        projeto,
         catalogo,
         destino,
         dryRun: opcoes.dryRun === true,
         arquivos,
         conflitos,
+        precisamDeDecisao,
+        ...(reciboVizinho ? { reciboVizinho } : {}),
         ok: !barrado,
         orkBin,
         pitfalls: def.pitfalls,
@@ -246,6 +367,11 @@ function instalarAdaptador(host, opcoes = {}) {
     if (opcoes.dryRun === true || barrado)
         return resultado;
     for (const arquivo of arquivos) {
+        // `--manter-copia`: a copia local fica como esta. Ela permanece DETECTADA como
+        // divergente na proxima rodada, porque esconder a divergencia seria o defeito
+        // silencioso de R1 voltando por outra porta.
+        if (manter.has(arquivo.relativo))
+            continue;
         const ext = path.extname(arquivo.origem);
         const bruto = fs.readFileSync(arquivo.origem);
         const conteudo = RENDERIZAVEIS.has(ext)
@@ -306,24 +432,74 @@ function textoDaInstalacao(r) {
     linhas.push(r.dryRun
         ? `Simulacao (--dry-run) da instalacao do adaptador ${r.host}: nada foi escrito.`
         : r.ok
-            ? `Adaptador ${r.host} instalado.`
+            ? `Arquivos do adaptador ${r.host} preparados.`
             : `Instalacao do adaptador ${r.host} BARRADA: ha arquivo diferente no destino.`);
+    if (r.ok && !r.dryRun && r.host === 'claude-code') {
+        const destino = "'" + r.destino.replace(/'/g, "'\"'\"'") + "'";
+        linhas.push('Uso no Claude Code ainda nao verificado por esta copia.');
+        linhas.push('No diretorio deste projeto, valide e ative o plugin:');
+        linhas.push(`  claude plugin validate ${destino}`);
+        linhas.push(`  claude plugin marketplace add ${destino} --scope project`);
+        linhas.push('  claude plugin install orkastery@orkastery --scope project');
+        linhas.push('  claude plugin list --json');
+        linhas.push('Depois, na sessao deste projeto: /orkastery:ork');
+    }
+    else if (r.ok && !r.dryRun && r.host === 'codex') {
+        linhas.push('Abra o Codex neste projeto e use $ork.');
+        linhas.push('Descoberta e uso nativo ainda nao verificados por esta copia.');
+    }
+    if (r.ok && !r.dryRun && (r.host === 'codex' || r.host === 'claude-code')) {
+        const projeto = "'" + r.projeto.replace(/'/g, "'\"'\"'") + "'";
+        linhas.push(`Prepare tambem as ferramentas do projeto: ork mcp install --project ${projeto} --host ${r.host}`);
+        linhas.push('A configuracao MCP exige descoberta e consentimento no cliente; a copia nao concede aprovacoes.');
+    }
     linhas.push(`  catalogo: ${r.catalogo}`);
     linhas.push(`  destino:  ${r.destino}`);
     linhas.push(`  ork:      ${r.orkBin}`);
     linhas.push('');
     const novos = r.arquivos.filter((a) => a.estado === 'novo').length;
     const iguais = r.arquivos.filter((a) => a.estado === 'igual').length;
+    const catalogoAndou = r.conflitos.filter((a) => a.divergencia === 'catalogo-andou').length;
     linhas.push(`  arquivos: ${r.arquivos.length} (${novos} novo(s), ${iguais} ja identico(s), ${r.conflitos.length} divergente(s))`);
     for (const a of r.arquivos) {
         const marca = a.estado === 'novo' ? '+' : a.estado === 'igual' ? '=' : '!';
-        linhas.push(`    ${marca} ${a.relativo}`);
+        const porque = a.divergencia ? `  (${a.divergencia})` : '';
+        linhas.push(`    ${marca} ${a.relativo}${porque}`);
+    }
+    // I-43 (D5): o `--dir` na raiz avisa, em vez de reportar "tudo novo" com saida 0.
+    if (r.reciboVizinho) {
+        linhas.push('');
+        linhas.push(`  ATENCAO: nao ha recibo em ${r.destino}, mas ha um em`);
+        linhas.push(`    ${r.reciboVizinho}`);
+        linhas.push('  `--dir` e o destino COMPLETO, nao a raiz do projeto. Do jeito que esta, esta');
+        linhas.push('  instalacao criaria uma copia nova ao lado da que ja existe, e a que existe');
+        linhas.push('  ficaria sem conferencia nenhuma.');
+    }
+    // I-43 (D5): o que o recibo garante seguro se resolve sozinho, e sai como uma linha
+    // de resumo em vez de virar decisao do operador.
+    if (catalogoAndou > 0) {
+        linhas.push('');
+        linhas.push(`  ${catalogoAndou} divergente(s) sao "catalogo-andou": a copia esta como foi instalada`);
+        linhas.push('  e quem mudou foi o catalogo. Sobrescrever nao perde trabalho de ninguem.');
     }
     if (!r.ok) {
+        // A pergunta de UMA linha, com o arquivo NOMEADO e as duas saidas reais. O `--dir`
+        // em uso e repetido de proposito: a linha antiga mandava rodar sem ele, e rodar o
+        // que estava na tela instalaria em `<catalogo>/<destinoPadrao>`, nao na copia real.
+        const dirEmUso = r.destino.startsWith(r.projeto + '/')
+            ? r.destino.slice(r.projeto.length + 1)
+            : r.destino;
+        linhas.push('');
+        linhas.push(`  ${r.precisamDeDecisao.length} arquivo(s) precisam de uma decisao sua:`);
+        for (const a of r.precisamDeDecisao) {
+            linhas.push(`    ${a.relativo}  (${a.divergencia})`);
+            linhas.push(`      $ diff -u ${a.origem} ${a.destino}`);
+        }
         linhas.push('');
-        linhas.push('  O destino tem arquivo diferente do catalogo. Ou a copia instalada foi editada');
-        linhas.push('  (e a correcao pertence ao catalogo), ou o catalogo andou. Para ressincronizar:');
-        linhas.push(`    ork adapter install ${r.host} --force`);
+        linhas.push('  Resolva em UM comando, por arquivo:');
+        const exemplo = r.precisamDeDecisao[0]?.relativo ?? '<arquivo>';
+        linhas.push(`    ork adapter install ${r.host} --dir ${dirEmUso} --aceitar-catalogo ${exemplo}`);
+        linhas.push(`    ork adapter install ${r.host} --dir ${dirEmUso} --manter-copia ${exemplo}`);
     }
     linhas.push('');
     linhas.push(textoDosPitfalls(r.host));