@orkastery/cli 0.5.1 → 0.5.6

package/dist/fila-pesada.js

@@ -0,0 +1,444 @@
+"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.ErroDaFilaPesada = exports.ENV_DONO_DA_FILA = exports.CONTRATO_FILA_PESADA = void 0;
+exports.kernelDisponivel = kernelDisponivel;
+exports.tentarTravaExclusiva = tentarTravaExclusiva;
+exports.dirDaFilaPesada = dirDaFilaPesada;
+exports.ocupantesDaFilaPesada = ocupantesDaFilaPesada;
+exports.comRecursoPesado = comRecursoPesado;
+/**
+ * RM-058, fatia N2 (D9 da ork-rm058n2): a fila de recursos pesados.
+ *
+ * Verify rodando junto com build de outra worktree deu regressão falsa nesta máquina: com a CPU dividida, teste
+ * com relógio estoura o prazo e a suíte reprova sem que nada tenha quebrado. A fila deixa no máximo `slots`
+ * operações pesadas ao mesmo tempo por raiz de estado (todas as worktrees do projeto nesta máquina) e nunca duas
+ * no mesmo artefato (o diretório onde a operação compila e testa).
+ *
+ * Tudo é trava do kernel (`flock` exclusivo, como a condução e o lock do HITL): quem segura é o processo, e a
+ * trava solta sozinha quando ele morre, inclusive por SIGKILL. Nenhum prazo, PID ou arquivo apagado libera vaga;
+ * um processo perdido em segundo plano não prende a fila. A ordem de chegada é uma senha, também com trava do
+ * kernel: quem chegou antes e segue vivo passa antes, e a senha de quem morreu não segura ninguém.
+ *
+ * Limites ditos: a fila é da raiz de estado, e outro projeto da mesma máquina tem a sua; o descritor não passa
+ * aos filhos, então o processo que morre por SIGKILL solta a vaga mesmo que um comando dele ainda rode até o
+ * próprio prazo (o `timeout` do verify o encerra); e só o Linux com `/usr/bin/flock` tem a fila.
+ *
+ * O dono da vez passa aos comandos que roda a marca da posse (`ORK_FILA_PESADA_DONO`): um verify aninhado num
+ * comando dele (a claim que roda `ork verify` de outra thread do mesmo projeto) entra como reentrada, em vez de
+ * esperar a vaga do próprio pai até o prazo. A marca só vale com o dono vivo, ancestral do processo e segurando a
+ * vaga que diz, com o identificador da posse que gravou nela: marca copiada para fora dessa árvore de processos, ou
+ * guardada de uma vez anterior do mesmo dono, não pula a fila.
+ */
+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 estado_thread_1 = require("./estado-thread");
+const horario_1 = require("./horario");
+exports.CONTRATO_FILA_PESADA = 'ork.fila-pesada/v1';
+/** A marca da posse que o dono da vez passa aos processos filhos. */
+exports.ENV_DONO_DA_FILA = 'ORK_FILA_PESADA_DONO';
+const FLOCK = '/usr/bin/flock';
+const DIR = 'fila-pesada';
+/** Entre uma tentativa e outra. A vez costuma durar minutos; meio segundo não pesa em ninguém. */
+const PAUSA_MS = 500;
+/** A recusa é resposta, não falha: o CLI a imprime como a da condução, e sai com 3. */
+class ErroDaFilaPesada extends Error {
+    recusa;
+    constructor(recusa) {
+        super(`fila-pesada.ocupada: ${recusa.texto}`);
+        this.name = 'ErroDaFilaPesada';
+        this.recusa = recusa;
+    }
+}
+exports.ErroDaFilaPesada = ErroDaFilaPesada;
+function kernelDisponivel() {
+    return process.platform === 'linux' && fs.existsSync(FLOCK);
+}
+/** O `flock` exclusivo sem espera sobre um descritor já aberto. O helper tranca a descrição de arquivo, que fica do processo. */
+function trancar(fd) {
+    const r = (0, node_child_process_1.spawnSync)(FLOCK, ['--exclusive', '--nonblock', '3'], { stdio: ['ignore', 'ignore', 'ignore', fd], timeout: 5000 });
+    return r.status === 0 && !r.error;
+}
+function abrirTrava(arquivo, criar) {
+    const fd = fs.openSync(arquivo, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW | (criar ? fs.constants.O_CREAT : 0), 0o600);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.uid !== process.getuid?.()) {
+        fs.closeSync(fd);
+        throw new Error(`fila-pesada: ${path.basename(arquivo)} não é arquivo de trava do núcleo`);
+    }
+    return fd;
+}
+/**
+ * A trava exclusiva do kernel num arquivo da raiz de estado: o descritor, ou `null` quando outro processo vivo a
+ * segura. A trava dura enquanto o descritor estiver aberto neste processo, e nunca mais que o processo.
+ */
+function tentarTravaExclusiva(arquivo) {
+    const fd = abrirTrava(arquivo, true);
+    if (trancar(fd))
+        return fd;
+    fs.closeSync(fd);
+    return null;
+}
+/** O diretório da fila na raiz de estado, criado privado. */
+function dirDaFilaPesada(raiz) {
+    const principal = (0, estado_thread_1.raizDoEstado)(raiz);
+    (0, estado_thread_1.exigirEstadoSemLink)(principal, ['.orkastery', DIR]);
+    const dir = path.join(principal, '.orkastery', DIR);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** O artefato pelo caminho real: a mesma worktree por dois caminhos é o mesmo artefato. */
+function chaveDoArtefato(artefato) {
+    let real;
+    try {
+        real = fs.realpathSync(artefato);
+    }
+    catch {
+        real = path.resolve(artefato);
+    }
+    return (0, node_crypto_1.createHash)('sha256').update(real).digest('hex').slice(0, 16);
+}
+/**
+ * A senha de chegada: criada com outro nome, trancada e só então renomeada, para ninguém vê-la destrancada e
+ * tomá-la por senha de processo morto. O nome começa pelo instante, com zeros: a ordem dos nomes é a de chegada.
+ */
+function tirarSenha(dir) {
+    const marca = `${String(Date.now()).padStart(15, '0')}-${String(process.pid).padStart(10, '0')}-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+    const provisorio = path.join(dir, `.senha-${marca}.tmp`);
+    const fd = abrirTrava(provisorio, true);
+    if (!trancar(fd)) {
+        fs.closeSync(fd);
+        fs.rmSync(provisorio, { force: true });
+        throw new Error('fila-pesada: a senha nova não trancou');
+    }
+    const nome = `senha-${marca}.lock`;
+    fs.renameSync(provisorio, path.join(dir, nome));
+    return { nome, fd };
+}
+/** Apaga a senha com a trava na mão e só depois a solta: ninguém a vê destrancada no diretório. */
+function devolverSenha(dir, senha) {
+    if (!senha)
+        return;
+    try {
+        fs.unlinkSync(path.join(dir, senha.nome));
+    }
+    catch { /* já saiu */ }
+    try {
+        fs.closeSync(senha.fd);
+    }
+    catch { /* já fechado */ }
+}
+/**
+ * É a vez desta senha? Só quando nenhuma senha anterior segue viva. A de processo morto está destrancada: quem a
+ * acha a tranca, apaga e solta, para ela não segurar a fila de ninguém. A provisória de quem morreu entre criar e
+ * renomear também sai, pelo mesmo teste da trava.
+ */
+function minhaVez(dir, senha) {
+    const nomes = fs.readdirSync(dir);
+    for (const nome of nomes.filter(n => /^\.senha-.+\.tmp$/.test(n))) {
+        // Entre criar e trancar, a provisória viva fica um instante destrancada: só a velha é de quem morreu.
+        const st = fs.statSync(path.join(dir, nome), { throwIfNoEntry: false });
+        if (!st || Date.now() - st.mtimeMs < 30_000)
+            continue;
+        let fd;
+        try {
+            fd = abrirTrava(path.join(dir, nome), false);
+        }
+        catch {
+            continue;
+        }
+        if (trancar(fd)) {
+            try {
+                fs.unlinkSync(path.join(dir, nome));
+            }
+            catch { /* outro já limpou */ }
+        }
+        fs.closeSync(fd);
+    }
+    const anteriores = nomes.filter(n => /^senha-.+\.lock$/.test(n) && n < senha.nome).sort();
+    for (const nome of anteriores) {
+        let fd;
+        try {
+            fd = abrirTrava(path.join(dir, nome), false);
+        }
+        catch {
+            continue;
+        }
+        if (!trancar(fd)) {
+            fs.closeSync(fd);
+            return false;
+        }
+        try {
+            fs.unlinkSync(path.join(dir, nome));
+        }
+        catch { /* outro já limpou */ }
+        fs.closeSync(fd);
+    }
+    return true;
+}
+function gravarDono(fd, dono, posse) {
+    const bytes = Buffer.from(JSON.stringify({ contrato: exports.CONTRATO_FILA_PESADA, ...dono, posse }) + '\n', 'utf8');
+    fs.ftruncateSync(fd, 0);
+    fs.writeSync(fd, bytes, 0, bytes.length, 0);
+}
+/** O artefato primeiro, depois a primeira vaga livre; sem vaga, solta o artefato. Nunca espera segurando nada. */
+function tentarVaga(dir, pedido) {
+    const fdArtefato = tentarTravaExclusiva(path.join(dir, `artefato-${chaveDoArtefato(pedido.artefato)}.lock`));
+    if (fdArtefato === null)
+        return null;
+    for (let slot = 0; slot < pedido.slots; slot++) {
+        const fdVaga = tentarTravaExclusiva(path.join(dir, `vaga-${slot}.lock`));
+        if (fdVaga === null)
+            continue;
+        const dono = { slot, operacao: pedido.operacao, thread: pedido.thread, artefato: path.resolve(pedido.artefato),
+            pid: process.pid, desde: new Date().toISOString() };
+        const id = (0, node_crypto_1.randomUUID)();
+        gravarDono(fdVaga, dono, id);
+        gravarDono(fdArtefato, dono, id);
+        return { fdArtefato, fdVaga, slot, id };
+    }
+    fs.closeSync(fdArtefato);
+    return null;
+}
+function soltar(posse) {
+    for (const fd of [posse.fdVaga, posse.fdArtefato]) {
+        try {
+            fs.ftruncateSync(fd, 0);
+        }
+        catch { /* o descritor fecha de qualquer jeito */ }
+        try {
+            fs.closeSync(fd);
+        }
+        catch { /* já fechado */ }
+    }
+}
+/**
+ * Quem ocupa as vagas agora. Somente leitura do que os donos gravaram; a vaga que tranca na hora está livre e é
+ * solta em seguida. Vaga trancada sem dono legível ainda conta, como ocupada por desconhecido.
+ */
+function ocupantesDaFilaPesada(raiz) {
+    if (!kernelDisponivel())
+        return [];
+    const dir = dirDaFilaPesada(raiz);
+    const ocupantes = [];
+    for (const nome of fs.readdirSync(dir).filter(n => /^vaga-\d+\.lock$/.test(n)).sort()) {
+        let fd;
+        try {
+            fd = abrirTrava(path.join(dir, nome), false);
+        }
+        catch {
+            continue;
+        }
+        try {
+            if (trancar(fd))
+                continue;
+            const slot = Number(/^vaga-(\d+)\.lock$/.exec(nome)[1]);
+            let dono = {};
+            try {
+                dono = JSON.parse(fs.readFileSync(path.join(dir, nome), 'utf8'));
+            }
+            catch { /* dono ainda gravando */ }
+            ocupantes.push({ slot, operacao: typeof dono.operacao === 'string' ? dono.operacao : 'desconhecida',
+                thread: typeof dono.thread === 'string' ? dono.thread : null, artefato: typeof dono.artefato === 'string' ? dono.artefato : '',
+                pid: typeof dono.pid === 'number' ? dono.pid : 0, desde: typeof dono.desde === 'string' ? dono.desde : '' });
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    return ocupantes;
+}
+function recusaDaFila(pedido, esperouMs, ocupantes) {
+    const espera = esperouMs < 60000 ? `${Math.round(esperouMs / 1000)} s` : `${Math.round(esperouMs / 60000)} min`;
+    const linhas = [
+        `Operação pesada não executada: ${pedido.operacao}${pedido.thread ? ` da thread ${pedido.thread}` : ''} esperou ${espera} ` +
+            `e a fila de recursos pesados não liberou a vez (até ${pedido.slots} ao mesmo tempo, concurrency.max_parallel_heavy). ` +
+            'Verify e build juntos nesta máquina dão regressão falsa.',
+        ...(ocupantes.length ? ocupantes.map(o => `  Quem ocupa: ${o.operacao}${o.thread ? ` da thread ${o.thread}` : ''}, ` +
+            `desde ${(0, horario_1.formatarDesde)(o.desde)}, processo ${o.pid}.`) : ['  Quem ocupa: a vez é de outro pedido que chegou antes e ainda espera.']),
+        'O que você pode fazer:',
+        '  1. Esperar a vez: o dono da vaga segue rodando e, quando ele termina ou morre, a vaga volta sozinha.',
+        ...(pedido.comandoDeEsperar ? [`     ${pedido.comandoDeEsperar}`] : []),
+        '  2. Desligar a fila só nesta máquina, se ela aguenta: concurrency.max_parallel_heavy no orkastery.yaml (0 desliga).',
+    ];
+    return { contrato: 'ork.fila-pesada-recusa/v1', motivo: 'fila-pesada.ocupada', operacao: pedido.operacao, thread: pedido.thread,
+        slots: pedido.slots, esperouMs, ocupantes, texto: linhas.join('\n') };
+}
+const pausa = new Int32Array(new SharedArrayBuffer(4));
+function dormir(ms) {
+    if (ms > 0)
+        Atomics.wait(pausa, 0, 0, Math.ceil(ms));
+}
+/** A vez que este processo segura, por raiz de estado: a reentrada não pede vaga de novo. */
+const emCurso = new Map();
+/** O campo 22 do `/proc/<pid>/stat` (instante de início em ticks): com o pid, identifica o processo sem reuso. */
+function inicioDoProcesso(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function paiDe(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const pai = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
+        return Number.isSafeInteger(pai) && pai > 0 ? pai : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** O processo é ancestral deste? Sobe pela cadeia de pais, no máximo 64 degraus. */
+function ancestral(pid) {
+    let atual = process.ppid;
+    for (let i = 0; i < 64 && atual !== null && atual > 1; i++) {
+        if (atual === pid)
+            return true;
+        atual = paiDe(atual);
+    }
+    return false;
+}
+/**
+ * A vaga que um processo ancestral segura nesta raiz, pela marca que ele passou; `null` quando a marca não vale: outra
+ * raiz, dono morto ou trocado (pid com outro início), dono que não é ancestral, ou vaga que ele não segura mais, inclusive
+ * a de uma vez anterior dele (o identificador da posse gravado na vaga é outro).
+ */
+function vagaDoAncestral(chave, dir) {
+    const bruto = process.env[exports.ENV_DONO_DA_FILA];
+    if (!bruto)
+        return null;
+    let marca;
+    try {
+        marca = JSON.parse(bruto);
+    }
+    catch {
+        return null;
+    }
+    const { pid, slot } = marca;
+    if (marca.raiz !== chave || typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid ||
+        typeof slot !== 'number' || !Number.isSafeInteger(slot) || slot < 0 || typeof marca.posse !== 'string')
+        return null;
+    if (inicioDoProcesso(pid) !== marca.inicio || !ancestral(pid))
+        return null;
+    const arquivo = path.join(dir, `vaga-${slot}.lock`);
+    try {
+        const gravado = JSON.parse(fs.readFileSync(arquivo, 'utf8'));
+        if (gravado.pid !== pid || gravado.posse !== marca.posse)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let fd;
+    try {
+        fd = abrirTrava(arquivo, false);
+    }
+    catch {
+        return null;
+    }
+    try {
+        return trancar(fd) ? null : slot;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Roda `executar` com a vez da fila de recursos pesados desta raiz de estado: a senha de chegada, a trava do
+ * artefato e uma das `slots` vagas, todas do kernel. Espera em primeiro plano até `esperarMs` e, sem a vez, lança
+ * `ErroDaFilaPesada` sem rodar nada. Dentro de quem já segura a vez neste processo, roda direto.
+ */
+function comRecursoPesado(raiz, pedido, executar) {
+    if (!(pedido.slots > 0))
+        return executar({ situacao: 'desligada', slot: null, esperouMs: 0 });
+    const chave = path.resolve((0, estado_thread_1.raizDoEstado)(raiz));
+    const atual = emCurso.get(chave);
+    if (atual)
+        return executar({ situacao: 'reentrada', slot: atual.slot, esperouMs: 0 });
+    if (!kernelDisponivel())
+        return executar({ situacao: 'sem-kernel', slot: null, esperouMs: 0 });
+    const dir = dirDaFilaPesada(raiz);
+    const doAncestral = vagaDoAncestral(chave, dir);
+    if (doAncestral !== null)
+        return executar({ situacao: 'reentrada', slot: doAncestral, esperouMs: 0 });
+    const inicio = Date.now();
+    const prazo = inicio + Math.max(0, pedido.esperarMs);
+    let senha = tirarSenha(dir);
+    let avisou = false;
+    try {
+        for (;;) {
+            const posse = minhaVez(dir, senha) ? tentarVaga(dir, pedido) : null;
+            if (posse) {
+                // Com a vaga na mão, a senha sai: quem vem depois disputa a próxima vaga livre.
+                devolverSenha(dir, senha);
+                senha = null;
+                emCurso.set(chave, { slot: posse.slot });
+                // Os comandos que rodam dentro da vez herdam a marca da posse: o verify aninhado neles é reentrada.
+                const marcaAnterior = process.env[exports.ENV_DONO_DA_FILA];
+                process.env[exports.ENV_DONO_DA_FILA] = JSON.stringify({ raiz: chave, pid: process.pid, inicio: inicioDoProcesso(process.pid), slot: posse.slot,
+                    posse: posse.id });
+                try {
+                    return executar({ situacao: 'adquirida', slot: posse.slot, esperouMs: Date.now() - inicio });
+                }
+                finally {
+                    if (marcaAnterior === undefined)
+                        delete process.env[exports.ENV_DONO_DA_FILA];
+                    else
+                        process.env[exports.ENV_DONO_DA_FILA] = marcaAnterior;
+                    emCurso.delete(chave);
+                    soltar(posse);
+                }
+            }
+            if (Date.now() >= prazo)
+                throw new ErroDaFilaPesada(recusaDaFila(pedido, Date.now() - inicio, ocupantesDaFilaPesada(raiz)));
+            if (!avisou) {
+                avisou = true;
+                try {
+                    pedido.aoEsperar?.(ocupantesDaFilaPesada(raiz));
+                }
+                catch { /* o aviso nunca derruba a espera */ }
+            }
+            dormir(Math.min(PAUSA_MS, prazo - Date.now()));
+        }
+    }
+    finally {
+        devolverSenha(dir, senha);
+    }
+}

package/dist/fix.js

@@ -213,7 +213,8 @@ function abrirRodada(carregado, threadId, opcoes = {}) {
 function abrirRodadaSobConducao(carregado, threadId, opcoes) {
     const { raiz } = carregado;
     const thread = (0, thread_1.lerThread)(raiz, threadId);
-    const resultado = (0, verify_1.verificar)(carregado, threadId, { soClaims: opcoes.soClaims });
+    // RM-058 N2 (A1 da rodada 2 do CHECK): a espera da fila pesada que o `--esperar` do CLI pediu.
+    const resultado = (0, verify_1.verificar)(carregado, threadId, { soClaims: opcoes.soClaims, conducao: { filaPesada: opcoes.conducao?.filaPesada } });
     const rodada = ultimaRodada(raiz, threadId) + 1;
     if (resultado.ok && resultado.motivos.length === 0) {
         return {
@@ -319,7 +320,7 @@ function reverificarSobConducao(carregado, threadId, opcoes) {
                 : `${execucoes.length} comando(s) reexecutado(s) com sucesso no HEAD real`,
         };
     });
-    const verify = cobertura === 'completa' ? (0, verify_1.verificar)(carregado, threadId) : null;
+    const verify = cobertura === 'completa' ? (0, verify_1.verificar)(carregado, threadId, { conducao: { filaPesada: opcoes.conducao?.filaPesada } }) : null;
     for (const v of vereditos) {
         // Correcao sem comando proprio herda o veredito do verify completo, e so quando ele
         // roda: sem ele, ela continua aberta em vez de virar aprovada por conveniencia.

package/dist/forja.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mesmaForja = exports.rotuloDaForja = exports.executorPadrao = void 0;
+exports.enderecoDoRemoto = enderecoDoRemoto;
+exports.repositorioGithubNoHost = repositorioGithubNoHost;
 exports.identidadeDaForja = identidadeDaForja;
 exports.forjaDoArgumento = forjaDoArgumento;
 exports.detalheSeguro = detalheSeguro;
@@ -27,14 +29,20 @@ exports.lerDaForja = lerDaForja;
 const node_child_process_1 = require("node:child_process");
 const hitl_1 = require("./hitl");
 const policies_1 = require("./policies");
+const rede_forja_1 = require("./rede-forja");
 const PRAZO_MS = 30000;
 const SHA = /^[0-9a-f]{40}$/;
 const SEGMENTO = /^[A-Za-z0-9_.-]+$/;
 /** Hostname de verdade: rotulos alfanumericos separados por ponto (`..` ou `a..b` nao passam). */
 const HOST = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/;
-/** Sem shell, sem token: a CLI usa a autenticacao que ja tem; prompt e aviso de versao desligados. */
+/**
+ * Sem shell, sem token: a CLI usa a autenticacao que ja tem; prompt e aviso de versao desligados.
+ * RM-054 (fatia 3): o binario e procurado como na rede (D11 da RM-053), no PATH e depois nas pastas de
+ * usuario (`~/.local/bin` e as outras): o gateway e o cron rodam com PATH curto, e o `gh` da maquina-b
+ * mora em `~/.local/bin`. Sem achar, o nome vai cru ao spawn, e o ENOENT continua `forja.ausente`.
+ */
 const executorPadrao = (cmd, args, entrada, timeoutMs) => {
-    const r = (0, node_child_process_1.spawnSync)(cmd, [...args], {
+    const r = (0, node_child_process_1.spawnSync)((0, rede_forja_1.acharBinario)(cmd) ?? cmd, [...args], {
         input: entrada, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024,
         env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1', GLAB_CHECK_UPDATE: 'false', NO_COLOR: '1' },
     });
@@ -63,10 +71,10 @@ function montar(tipo, host, caminho) {
     return { tipo, host, repo: partes.join('/') };
 }
 /**
- * A forja de uma URL de remoto (https, ssh ou scp). Credencial na URL nunca entra na identidade;
- * caminho local e forja desconhecida voltam null.
+ * RM-037 (fatia 5, A5): o host e o caminho de uma URL de remoto (https, ssh ou scp), de qualquer forja. Credencial
+ * na URL nunca entra; caminho local e host que nao e hostname voltam null.
  */
-function identidadeDaForja(url) {
+function enderecoDoRemoto(url) {
     const t = url.trim();
     const esquema = /^(?:https?|ssh|git|git\+ssh|ssh\+git):\/\/(?:[^@/]*@)?([^/:?#@]+)(?::\d+)?\/([^?#\s]+)$/i.exec(t);
     const scp = esquema ? null : /^(?:[^@\s/:]+@)?([^:\s/@]+):(?!\/\/)([^\s]+)$/.exec(t);
@@ -74,8 +82,24 @@ function identidadeDaForja(url) {
     if (!achado)
         return null;
     const host = achado[1].toLowerCase();
-    const tipo = tipoDoHost(host);
-    return tipo ? montar(tipo, host, achado[2].replace(/^\/+/, '')) : null;
+    return HOST.test(host) ? { host, caminho: achado[2].replace(/^\/+/, '') } : null;
+}
+/**
+ * RM-037 (fatia 5, A5): o `dono/nome` de um repositorio do GitHub no host do remoto, com qualquer host: o GitHub
+ * Enterprise mora em host proprio, com ou sem "github" no nome. Quem diz se o host e mesmo um GitHub e o `gh`.
+ */
+function repositorioGithubNoHost(url) {
+    const endereco = enderecoDoRemoto(url);
+    return endereco && tipoDoHost(endereco.host) !== 'gitlab' ? montar('github', endereco.host, endereco.caminho) : null;
+}
+/**
+ * A forja de uma URL de remoto (https, ssh ou scp). Credencial na URL nunca entra na identidade;
+ * caminho local e forja desconhecida voltam null.
+ */
+function identidadeDaForja(url) {
+    const endereco = enderecoDoRemoto(url);
+    const tipo = endereco ? tipoDoHost(endereco.host) : null;
+    return endereco && tipo ? montar(tipo, endereco.host, endereco.caminho) : null;
 }
 /** `github:dono/repo`, `gitlab:grupo/sub/repo` (com host proprio: `gitlab:host.tld/grupo/repo`) ou uma URL. */
 function forjaDoArgumento(texto) {

package/dist/gates.js

@@ -28,31 +28,10 @@ const thread_1 = require("./thread");
 const hitl_ingress_receipt_1 = require("./hitl-ingress-receipt");
 const hitl_local_receipt_1 = require("./hitl-local-receipt");
 const hitl_contract_1 = require("./hitl-contract");
+const locale_pulse_1 = require("./locale-pulse");
 /** O que cada motivo tipado significa, em uma linha, para a saida do CLI. */
-exports.DESCRICAO_DO_MOTIVO = {
-    'artifact.missing': 'artefato exigido pela fase nao existe no disco',
-    'claims.failed': 'alegacao verificavel reprovou na reexecucao no HEAD real',
-    'claims.unverifiable': 'alegacao sem comando de verificacao declarado',
-    'policy.violation': 'policy do manifesto com severidade block foi violada',
-    'runtime.autoconferencia': 'o CHECK foi despachado no mesmo runtime que fez o GO, e a thread exige validacao cruzada',
-    'verify.regression': 'comando que passava na baseline falha agora',
-    'verify.failed': 'comando de verificacao falhou (sem baseline para separar divida pre-existente)',
-    'verify.timeout': 'comando de verificacao estourou o prazo antes de terminar: nao ha veredito sobre ele',
-    'verify.sem-veredito': 'a rodada nao produziu veredito valido: comando que nao chegou a rodar, ou produto alterado entre o preparo e o fim',
-    'ci.failed': 'CHECK independente ausente, pendente ou reprovado no commit candidato',
-    'runtime.unavailable': 'runtime adapter indisponivel para o despacho',
-    'runtime.silencio': 'fase despachada sem heartbeat dentro do limite de liveness',
-    'runtime.rate-limited': 'o runtime bateu o limite de uso da assinatura e a fase morreu antes de terminar (bloco B3: entra na fila duravel e e retomada na janela seguinte)',
-    'runtime.quota-exhausted': 'a cota ou os creditos da conta do runtime acabaram (I-33: o perfil sai do rodizio e a fase segue em outro perfil, outro runtime ou na fila)',
-    'runtime.auth-missing': 'a conta do runtime nao esta autenticada (I-33: o perfil nunca recebe despacho ate o login ser refeito pelo proprio CLI)',
-    'runtime.model-unavailable': 'o modelo pedido nao existe ou a conta nao tem acesso a ele (RM-037: o perfil segue no rodizio e a fase vai a outro perfil com o mesmo modelo ou ao fallback do bloco)',
-    'cost.violation': 'o despacho seria redirecionado para provider pago (violacao de custo: e o unico motivo que NUNCA recebe retry automatico)',
-    'tree.blocked': 'a arvore de destino nao esta disponivel para o merge (branch em check-out com alteracao nao commitada, ou worktree que nao pode ser montada)',
-    'lease.busy': 'lease ocupado por outra thread',
-    'conducao.em-andamento': 'outra conducao ja executa na worktree da thread (I-36): o pedido foi recusado com quem conduz e as tres acoes (esperar, acompanhar, assumir)',
-    'hitl.formato': 'o pedido HITL saiu fora do formato obrigatorio (pergunta em uma frase, de 2 a 4 alternativas rotuladas com consequencia, exatamente uma recomendada com o porque, corpo em lista)',
-    'human.pending': 'gate humano do modo de conducao ainda nao autorizou',
-};
+// RM-061 (F2b): a fonte e o catalogo pt-BR (`locale-pulse.ts`), com o ingles ao lado; o texto nao muda.
+exports.DESCRICAO_DO_MOTIVO = locale_pulse_1.PULSE_PT_BR.motivos;
 /**
  * Motivos que reprovam em QUALQUER modo, inclusive `#Auto`.
  *

package/dist/handoff.js

@@ -73,6 +73,7 @@ const phase_1 = require("./phase");
 const thread_1 = require("./thread");
 const memoria_1 = require("./memoria");
 const util_1 = require("./util");
+const procedencia_1 = require("./procedencia");
 /** sha256 de um arquivo em disco, a prova de proveniencia de cada item. */
 function sha256DoArquivo(caminho) {
     if (!fs.existsSync(caminho))
@@ -98,7 +99,8 @@ function caminhoDoArtefato(raiz, thread, arquivo) {
         ? [path.resolve(thread.worktree, arquivo), path.resolve(raiz, arquivo)]
         : [path.resolve(raiz, arquivo)];
     for (const c of candidatos) {
-        if (fs.existsSync(c) && fs.statSync(c).isFile())
+        // RM-047 (P2): o arquivo da claim vem do estado; fora da raiz e da worktree registrada, não vira ponteiro.
+        if (fs.existsSync(c) && fs.statSync(c).isFile() && (0, procedencia_1.caminhoContidoOuNulo)(raiz, thread, c))
             return c;
     }
     return null;
@@ -222,7 +224,7 @@ function exportarHandoff(carregado, threadId, opcoes = {}) {
         if (s.origem === 'adocao')
             continue;
         const caminhoPrompt = path.resolve(raiz, s.promptPath);
-        if (!fs.existsSync(caminhoPrompt))
+        if (!fs.existsSync(caminhoPrompt) || !(0, procedencia_1.caminhoContidoOuNulo)(raiz, thread, caminhoPrompt))
             continue;
         addPonteiro(`Prompt da sessao ${s.slug} (fase ${s.fase})`, caminhoPrompt, 'pedido-do-builder', s.fase);
     }
@@ -261,7 +263,7 @@ function exportarHandoff(carregado, threadId, opcoes = {}) {
         for (const e of anteriores) {
             const arquivo = (0, memoria_1.arquivoDoHandoff)(e);
             const emDisco = arquivo ? path.resolve(raiz, arquivo) : '';
-            if (!emDisco || !fs.existsSync(emDisco))
+            if (!emDisco || !fs.existsSync(emDisco) || !(0, procedencia_1.caminhoContidoOuNulo)(raiz, thread, emDisco))
                 continue;
             addPonteiro(`Handoff anterior desta thread (${arquivo})`, emDisco, 'tudo', proximaFase, `orkmind://handoff/${e.id}`);
         }
@@ -270,7 +272,7 @@ function exportarHandoff(carregado, threadId, opcoes = {}) {
         for (const e of (0, memoria_1.licoesDoProduto)(memoria, manifesto, threadId)) {
             const postmortem = (0, memoria_1.postmortemDaLicao)(e);
             const emDisco = postmortem ? path.resolve(raiz, postmortem) : '';
-            if (!emDisco || !fs.existsSync(emDisco))
+            if (!emDisco || !fs.existsSync(emDisco) || !(0, procedencia_1.caminhoContidoOuNulo)(raiz, thread, emDisco))
                 continue;
             addPonteiro(`Licao da thread ${(0, memoria_1.threadDaEntrada)(e) ?? '(anterior)'}`, emDisco, 'json:resumo', 'MASTER', `orkmind://learning/${e.id}`);
         }
@@ -398,9 +400,11 @@ function recall(carregado, threadId, ponteiro) {
     if (!fs.existsSync(caminho) || !fs.statSync(caminho).isFile()) {
         throw new Error(`ponteiro nao resolve: arquivo "${bruto}" nao existe a partir de ${raiz}`);
     }
-    const conteudoBruto = fs.readFileSync(caminho, 'utf8');
+    // RM-047 (P2): o `location` vem do handoff.json (estado, talvez versionado); só lê dentro do projeto.
+    const real = (0, procedencia_1.exigirCaminhoContido)(raiz, (0, thread_1.lerThread)(raiz, threadId), caminho, bruto);
+    const conteudoBruto = fs.readFileSync(real, 'utf8');
     const linhas = conteudoBruto.split('\n');
-    const sha = sha256DoArquivo(caminho);
+    const sha = sha256DoArquivo(real);
     const base = { location: `${bruto}#${ancora}`, caminho, ancora, sha256: sha };
     const registrarRecall = (r) => {
         (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, ledger_1.TIPOS_DE_EVENTO.handoffRecuperado, {