@orkastery/cli 0.5.6 → 0.6.0

package/dist/varredura-acoes.js

@@ -0,0 +1,507 @@
+"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.IDADE_MINIMA_DA_FANTASMA_MIN = exports.MOTIVOS_DO_BLOQUEIO = exports.ACOES_DA_VARREDURA = void 0;
+exports.trabalhoNaWorktree = trabalhoNaWorktree;
+exports.lerSessoes = lerSessoes;
+exports.acoesPendentes = acoesPendentes;
+exports.buscarBase = buscarBase;
+exports.agirNaVarredura = agirNaVarredura;
+exports.acoesFeitasDesde = acoesFeitasDesde;
+/**
+ * RM-063 (F5): a varredura que age.
+ *
+ * Incidente de 03 a 12/10/2026 (P4 e P5 da pagina da RM-063): o PR #112 (`ork-rm043sobrasd`) foi mesclado e ficou dois
+ * dias sem `ork ship registrar-pr`, e as sessoes fantasmas de threads ja fechadas ficaram registradas, porque ninguem
+ * roda esses comandos sem um condutor. Aqui moram as tres acoes de arrumacao que a batida (`pulse-delivery`) faz:
+ *
+ *  - `limpar`: a sessao fantasma (sem pid e sem processo, RM-056) ainda presa a uma thread deste projeto, sem sinal de
+ *    vida ha pelo menos 30 min, sai do ork pelo `ork sessions limpar-fantasmas`, que grava `sessao_morta` e nunca toca o
+ *    runtime;
+ *  - `registrar`: o merge `ship(<thread>)` da branch `ork/*` da thread na base remota, sem `ship_done`, vira entrega
+ *    pelo `ork ship registrar-pr`, com a mesma prova de sempre (merge dentro da ponta remota e CI verde);
+ *  - `master`: a thread entregue, sem nota do dono e quieta (nada despachado depois da entrega, 30 min depois do
+ *    `ship_done`) fecha pelo MASTER por omissao, so ela (`ork master <thread> --aceitar-omissao`).
+ *
+ * `registrar` e `master` nunca agem sozinhos por cima de trabalho na thread: alguem conduzindo, sessao viva na worktree
+ * (ou o runtime que nao respondeu, sem a prova), worktree com alteracao nao commitada, commit na branch depois do head do
+ * PR mesclado, ou despacho depois dele. Nesses casos a acao fica com o dono, com o motivo tipado (`motivoDoBloqueio`).
+ *
+ * A deteccao (`acoesPendentes`) e leitura pura e alimenta a fila do pulse. A execucao (`agirNaVarredura`) so faz o que
+ * a autorizacao duravel do dono permite (`autorizacao-duravel.ts`), e cada acao feita ou recusada vai ao ledger da
+ * thread como `varredura_acao`, com a autorizacao que a permitiu; a mesma recusa seguida nao vira linha nova. Sem
+ * autorizacao, nada e feito: cada acao vira um item da fila do pulse com o comando pronto.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const autorizacao_duravel_1 = require("./autorizacao-duravel");
+const conducao_1 = require("./conducao");
+const entrega_pr_1 = require("./entrega-pr");
+const estado_thread_1 = require("./estado-thread");
+const ledger_1 = require("./ledger");
+const locale_1 = require("./locale");
+const master_1 = require("./master");
+const noctum_guarda_1 = require("./noctum-guarda");
+const parado_no_condutor_1 = require("./parado-no-condutor");
+const sessoes_1 = require("./sessoes");
+const sessoes_inventario_1 = require("./sessoes-inventario");
+const thread_1 = require("./thread");
+const util_1 = require("./util");
+const vida_da_thread_1 = require("./vida-da-thread");
+const worktree_1 = require("./worktree");
+/**
+ * As acoes da varredura. `limpar`, `registrar` e `master` sao da F5 (este modulo); `merge` e `despachar` sao da batida da
+ * conducao (F7, `conducao-batida.ts`), que grava o mesmo `varredura_acao` e entra no mesmo "feitas" do pulse.
+ */
+exports.ACOES_DA_VARREDURA = ['limpar', 'registrar', 'master', 'merge', 'despachar'];
+/**
+ * Por que nem a autorizacao faz a acao sozinha agora. Os sete primeiros sao o trabalho na thread (F5); os seguintes sao
+ * do merge e do despacho da batida da conducao (F7): o PR que ainda nao esta pronto, o conflito em codigo e a fase sem o
+ * prompt gravado.
+ */
+exports.MOTIVOS_DO_BLOQUEIO = ['conduzida', 'sessao-viva', 'sessoes-sem-leitura', 'worktree-suja', 'branch-com-commits',
+    'trabalho-novo', 'git-sem-resposta', 'pr-rascunho', 'checks-vermelhos', 'sem-checks-obrigatorios', 'pr-bloqueado',
+    'pr-instavel', 'conflito-em-codigo', 'branch-nao-publicada', 'sem-prompt-gravado', 'check-pendente', 'pendencia-do-dono',
+    'espera-longa', 'thread-do-arco'];
+/** A sessao so e tratada como fantasma depois de duas batidas sem sinal: a recem-despachada pode nao ter pid ainda. */
+exports.IDADE_MINIMA_DA_FANTASMA_MIN = 30;
+const SHA = /^[0-9a-f]{40}$/;
+/** Os eventos de trabalho novo numa fase: o pedido de despacho e o despacho. */
+const TRABALHO_NOVO = [ledger_1.TIPOS_DE_EVENTO.promptGravado, ledger_1.TIPOS_DE_EVENTO.faseDespachada];
+/** Os eventos que nao sao sinal de vida da sessao: a contabilidade do proprio ork. */
+const SO_DO_ORK = /^(conducao_|retry_|despacho_idempotente$|varredura_acao$)/;
+function lerThreads(raiz) {
+    const saida = [];
+    for (const id of (0, thread_1.listarIds)(raiz)) {
+        try {
+            saida.push((0, thread_1.lerThread)(raiz, id));
+        }
+        catch { /* thread ilegivel fica de fora */ }
+    }
+    return saida;
+}
+function ledgerDe(raiz, id) {
+    try {
+        return (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    }
+    catch {
+        return [];
+    }
+}
+/** A ultima tentativa recusada desta acao na thread, depois de `desde`. */
+function recusaDe(eventos, acao, sessionId, desde) {
+    const e = [...eventos].reverse().find((x) => x.tipo === ledger_1.TIPOS_DE_EVENTO.acaoDaVarredura && x.acao === acao &&
+        (sessionId === null || x.sessionId === sessionId));
+    if (!e || e.resultado !== 'recusada' || (desde && e.ts < desde))
+        return null;
+    return { em: e.ts, detalhe: typeof e.detalhe === 'string' ? e.detalhe : '' };
+}
+const conduzida = (raiz, id, quando) => {
+    try {
+        return (0, conducao_1.conducaoDaThread)(raiz, id, { agora: new Date(quando) }) !== null;
+    }
+    catch {
+        return true;
+    }
+};
+const real = (p) => { try {
+    return fs.realpathSync(p);
+}
+catch {
+    return path.resolve(p);
+} };
+/** O instante do commit pela copia local; `null` quando o git nao responde. */
+function dataDoCommit(raiz, sha) {
+    const r = (0, util_1.exec)('git', ['log', '-1', '--format=%cI', sha, '--'], raiz, 30000);
+    const ms = r.ok ? Date.parse(r.stdout.trim()) : NaN;
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+const comMotivo = (motivo) => ({ motivo, texto: (0, locale_1.textoDoCatalogo)((m) => m.pulse.varredura.bloqueios[motivo]) });
+/**
+ * O trabalho em curso na worktree da thread, que nenhuma acao automatica atropela: alguem conduzindo, sessao viva nela
+ * (ou o runtime que nao respondeu, sem a prova), ou alteracao nao commitada.
+ */
+function trabalhoNaWorktree(raiz, t, quando, vivas) {
+    if (conduzida(raiz, t.id, quando))
+        return comMotivo('conduzida');
+    if (vivas === null)
+        return comMotivo('sessoes-sem-leitura');
+    const wt = t.worktree ? real(t.worktree) : null;
+    if (!wt || !fs.existsSync(wt))
+        return null;
+    if (vivas.some((v) => { const c = real(v.cwd); return c === wt || c.startsWith(wt + path.sep); }))
+        return comMotivo('sessao-viva');
+    const st = (0, util_1.exec)('git', ['status', '--porcelain', '--', '.', ':(exclude).orkastery'], wt, 30000);
+    if (!st.ok)
+        return comMotivo('git-sem-resposta');
+    return st.stdout.trim() ? comMotivo('worktree-suja') : null;
+}
+/** Commits na branch da thread depois de `sha` (o head do PR mesclado); `null` quando o git nao responde. */
+function commitsDepois(raiz, t, sha) {
+    const branch = (0, worktree_1.branchDaWorktree)(t);
+    if (!(0, util_1.exec)('git', ['rev-parse', '--verify', '-q', `refs/heads/${branch}`], raiz, 30000).ok)
+        return 0;
+    const r = (0, util_1.exec)('git', ['rev-list', '--count', `${sha}..refs/heads/${branch}`], raiz, 30000);
+    return r.ok ? Number(r.stdout.trim()) : null;
+}
+/**
+ * Os merges `ship(<thread>)` da base remota (a copia local dela) numa leitura so, do mais novo ao mais velho: fica o mais
+ * novo de cada thread, com o head do PR (o segundo pai) e o instante do commit. E a mesma busca do `ork ship
+ * registrar-pr` (`mergeDaEntrega`).
+ */
+function mergesDaBase(raiz, remoto, base) {
+    const mapa = new Map();
+    const r = (0, util_1.exec)('git', ['log', `refs/remotes/${remoto}/${base}`, '--first-parent', '--format=%H%x09%P%x09%cI%x09%s', '--grep=^ship(',
+        '--'], raiz, 60000);
+    if (!r.ok)
+        return mapa;
+    for (const linha of r.stdout.split('\n')) {
+        const [sha, pais, em, assunto] = linha.split('\t');
+        const m = /^ship\(([A-Za-z0-9._-]+)\)/.exec(assunto ?? '');
+        if (!m || !sha || !SHA.test(sha) || mapa.has(m[1]))
+            continue;
+        const segundo = (pais ?? '').split(' ')[1] ?? null;
+        const ms = Date.parse(em ?? '');
+        mapa.set(m[1], { mergeSha: sha, headSha: segundo && SHA.test(segundo) ? segundo : null,
+            em: Number.isFinite(ms) ? new Date(ms).toISOString() : null });
+    }
+    return mapa;
+}
+/** As sessoes fantasmas presas a threads deste projeto, sem sinal de vida ha 30 min, uma acao por sessao. */
+function pendentesDeLimpar(raiz, threads, fantasmas, quando) {
+    const saida = [];
+    for (const f of fantasmas ?? []) {
+        const t = f.thread ? threads.get(f.thread) : undefined;
+        if (f.acao !== 'solto' || !t)
+            continue;
+        const eventos = ledgerDe(raiz, t.id);
+        // O ultimo sinal da sessao, sem a contabilidade do ork: a recusa da propria varredura nao rejuvenesce a fantasma.
+        const ultimo = [...eventos].reverse().find((e) => e.sessionId === f.sessionId && !SO_DO_ORK.test(e.tipo))?.ts ??
+            (t.sessoes ?? []).find((s) => s.sessionId === f.sessionId)?.despachadaEm ?? null;
+        if (!ultimo || Date.parse(quando) - Date.parse(ultimo) < exports.IDADE_MINIMA_DA_FANTASMA_MIN * 60000)
+            continue;
+        const id = f.sessionId.slice(0, 8);
+        saida.push({ acao: 'limpar', thread: t.id, fase: f.fase, sessionId: f.sessionId, desdeEm: ultimo,
+            comando: 'ork sessions limpar-fantasmas', oQue: (0, locale_1.textoDoCatalogo)((m) => m.pulse.varredura.oQue.limpar(id)),
+            evidencia: `claude agents lista a sessão ${id} sem pid ou com pid sem processo${f.perfil ? ` (perfil ${f.perfil})` : ''}`,
+            bloqueio: null, motivoDoBloqueio: null, recusa: recusaDe(eventos, 'limpar', f.sessionId, ultimo) });
+    }
+    return saida;
+}
+/**
+ * O merge `ship(<thread>)` da branch `ork/*` da thread na base remota (a copia local dela) sem `ship_done` que o cubra.
+ * O `ship_done` antigo sem o sha, ou o que gravou a ponta da base que contem o merge, cobre (a mesma regra do pulse).
+ */
+function pendentesDeRegistrar(carregado, threads, quando, vivas) {
+    const { raiz, manifesto } = carregado;
+    const remoto = manifesto.fabrica.remoto, base = manifesto.worktree.base_branch;
+    const saida = [];
+    const abertas = threads.filter((t) => t.status !== 'fechada' && (0, worktree_1.branchDaWorktree)(t).startsWith('ork/'));
+    const merges = abertas.length ? mergesDaBase(raiz, remoto, base)
+        : new Map();
+    for (const t of abertas) {
+        const merge = merges.get(t.id);
+        if (!merge)
+            continue;
+        const eventos = ledgerDe(raiz, t.id);
+        const ships = eventos.filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.shipConcluido);
+        const coberto = ships.some((e) => typeof e.mergeSha !== 'string' || !SHA.test(e.mergeSha) || e.mergeSha === merge.mergeSha ||
+            (0, util_1.exec)('git', ['merge-base', '--is-ancestor', merge.mergeSha, e.mergeSha], raiz, 30000).code === 0);
+        if (coberto)
+            continue;
+        // O registro avanca a fase da thread para SHIP: ele nao vai por cima do trabalho que veio depois do PR. Conta a partir
+        // do head do PR (o merge pode chegar horas depois): commit novo na branch, ou despacho depois dele.
+        const desde = (merge.headSha ? dataDoCommit(raiz, merge.headSha) : null) ?? merge.em;
+        const depois = merge.headSha ? commitsDepois(raiz, t, merge.headSha) : 0;
+        const motivo = trabalhoNaWorktree(raiz, t, quando, vivas)
+            ?? (depois === null ? comMotivo('git-sem-resposta') : depois > 0 ? comMotivo('branch-com-commits') : null)
+            ?? (desde && eventos.some((e) => TRABALHO_NOVO.includes(e.tipo) && e.ts > desde) ? comMotivo('trabalho-novo') : null);
+        const curto = merge.mergeSha.slice(0, 7);
+        saida.push({ acao: 'registrar', thread: t.id, fase: t.faseAtual, sessionId: null, desdeEm: merge.em,
+            comando: `ork ship registrar-pr ${t.id}`,
+            oQue: (0, locale_1.textoDoCatalogo)((m) => m.pulse.varredura.oQue.registrar(curto, (0, worktree_1.branchDaWorktree)(t), `${remoto}/${base}`)),
+            evidencia: `git log ${remoto}/${base}: merge ship(${t.id}) ${curto}, sem ship_done no ledger`,
+            bloqueio: motivo?.texto ?? null, motivoDoBloqueio: motivo?.motivo ?? null, recusa: recusaDe(eventos, 'registrar', null, merge.em) });
+    }
+    return saida;
+}
+/** A branch da thread tem commit fora da base? `null` quando o git nao responde (na duvida, nada fecha). */
+function produtoNovo(carregado, t) {
+    const { raiz, manifesto } = carregado;
+    const remoto = manifesto.fabrica.remoto, base = manifesto.worktree.base_branch, branch = (0, worktree_1.branchDaWorktree)(t);
+    const ref = (r) => (0, util_1.exec)('git', ['rev-parse', '--verify', '-q', r], raiz, 30000).ok;
+    if (!ref(`refs/heads/${branch}`))
+        return false;
+    const daBase = ref(`refs/remotes/${remoto}/${base}`) ? `refs/remotes/${remoto}/${base}` : `refs/heads/${base}`;
+    const r = (0, util_1.exec)('git', ['rev-list', '--count', `${daBase}..refs/heads/${branch}`], raiz, 30000);
+    return r.ok ? Number(r.stdout.trim()) > 0 : null;
+}
+/** A thread entregue e quieta, sem nota do dono: fecha pelo MASTER por omissao. */
+function pendentesDeMaster(carregado, threads, quando, vivas) {
+    const { raiz } = carregado;
+    const saida = [];
+    for (const t of threads) {
+        if (t.status === 'fechada')
+            continue;
+        let fora;
+        try {
+            fora = (0, master_1.motivoForaDaOmissao)(raiz, t.id);
+        }
+        catch {
+            continue;
+        }
+        if (fora)
+            continue;
+        const eventos = ledgerDe(raiz, t.id);
+        const ship = eventos.filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.shipConcluido).at(-1);
+        if (!ship)
+            continue;
+        // Quieta: nada pedido ou despachado depois da entrega, e o condutor teve 30 min para o MASTER dele.
+        if (eventos.some((e) => TRABALHO_NOVO.includes(e.tipo) && e.ts > ship.ts))
+            continue;
+        if (Date.parse(quando) - Date.parse(ship.ts) < parado_no_condutor_1.LIMIAR_PARADO_NO_CONDUTOR_MIN * 60000)
+            continue;
+        // A entrega conta do head que ela levou (o registro pode vir horas depois do PR): despacho depois dele e trabalho novo.
+        const desdeOHead = typeof ship.shaDe === 'string' && SHA.test(ship.shaDe) ? dataDoCommit(raiz, ship.shaDe) : null;
+        const novo = produtoNovo(carregado, t);
+        const motivo = trabalhoNaWorktree(raiz, t, quando, vivas)
+            ?? (novo === true ? comMotivo('branch-com-commits') : novo === null ? comMotivo('git-sem-resposta') : null)
+            ?? (desdeOHead && eventos.some((e) => TRABALHO_NOVO.includes(e.tipo) && e.ts > desdeOHead) ? comMotivo('trabalho-novo') : null);
+        saida.push({ acao: 'master', thread: t.id, fase: t.faseAtual, sessionId: null, desdeEm: ship.ts,
+            comando: `ork master ${t.id} --aceitar-omissao`, oQue: (0, locale_1.textoDoCatalogo)((m) => m.pulse.varredura.oQue.master),
+            evidencia: 'ledger: ship_done sem despacho nem MASTER depois dele',
+            bloqueio: motivo?.texto ?? null, motivoDoBloqueio: motivo?.motivo ?? null, recusa: recusaDe(eventos, 'master', null, ship.ts) });
+    }
+    return saida;
+}
+/**
+ * As fantasmas e as sessoes vivas numa leitura so do inventario de todas as contas, com o prazo curto da leitura da vida
+ * (20 s por conta): o pulse e o status nao esperam um daemon travado. Conta que nao respondeu deixa as vivas sem prova.
+ */
+function lerSessoes(raiz, opcoes) {
+    if (opcoes.fantasmas || opcoes.vivas) {
+        let fantasmas = null, vivas = null;
+        try {
+            fantasmas = opcoes.fantasmas ? opcoes.fantasmas() : null;
+        }
+        catch {
+            fantasmas = null;
+        }
+        try {
+            vivas = opcoes.vivas ? opcoes.vivas() : null;
+        }
+        catch {
+            vivas = null;
+        }
+        return { fantasmas, vivas };
+    }
+    try {
+        const inventario = (0, sessoes_inventario_1.inventariarSessoes)(raiz, { global: true, prazoMs: vida_da_thread_1.PRAZO_DA_LEITURA_MS });
+        const fantasmas = (0, sessoes_1.limparFantasmas)(raiz, { dryRun: true, inventario }).itens;
+        const claude = inventario.fontes.filter((f) => f.origem.startsWith('claude agents'));
+        const vivas = claude.every((f) => f.ok)
+            ? inventario.sessoes.filter((s) => s.viva && typeof s.cwd === 'string').map((s) => ({ sessionId: s.sessionId, cwd: s.cwd }))
+            : null;
+        return { fantasmas, vivas };
+    }
+    catch {
+        return { fantasmas: null, vivas: null };
+    }
+}
+/**
+ * As acoes que a varredura faria agora, sem fazer nenhuma. Leitura pura (o git da copia local, o ledger, o runtime pelo
+ * inventario), na ordem em que a execucao as faz: `limpar`, `registrar`, `master`.
+ *
+ * RM-058, integracao (T1.2, D3): a thread que um arco #Noctum segura nao tem acao de fora. Por padrao (o pulse) ela some da
+ * lista, porque quem diz dela ao dono e o relatorio do arco; com `comArco` (a varredura que age), ela fica com o bloqueio
+ * `thread-do-arco`, para o retrato da batida dizer o pulo. A retencao depois do arco nao segura estas tres acoes (D4).
+ */
+function acoesPendentes(carregado, opcoes = {}) {
+    const raiz = (0, estado_thread_1.raizDoEstado)(carregado.raiz);
+    const quando = opcoes.quando ?? new Date().toISOString();
+    const doProjeto = { ...carregado, raiz };
+    const threads = lerThreads(raiz);
+    const { fantasmas, vivas } = lerSessoes(raiz, opcoes);
+    const todas = [
+        ...pendentesDeLimpar(raiz, new Map(threads.map((t) => [t.id, t])), fantasmas, quando),
+        ...pendentesDeRegistrar(doProjeto, threads, quando, vivas),
+        ...pendentesDeMaster(doProjeto, threads, quando, vivas),
+    ];
+    const arcos = (0, noctum_guarda_1.lerArcosDaRaiz)(raiz, quando);
+    if (!arcos.lidos.size && !arcos.ilegiveis.size)
+        return todas;
+    const porThread = new Map();
+    const saida = [];
+    for (const a of todas) {
+        if (!porThread.has(a.thread))
+            porThread.set(a.thread, (0, noctum_guarda_1.arcoDoPasso)(raiz, arcos, a.thread, ledgerDe(raiz, a.thread)));
+        const arco = porThread.get(a.thread);
+        if (arco?.efeito !== 'guarda') {
+            saida.push(a);
+            continue;
+        }
+        // A6 do CHECK: o arco que nao se le nao tem relatorio que diga da thread ao dono; a acao fica no pulse, bloqueada.
+        if (opcoes.comArco || arco.motivo === noctum_guarda_1.MOTIVO_DO_ARCO_ILEGIVEL)
+            saida.push({ ...a, bloqueio: arco.detalhe, motivoDoBloqueio: 'thread-do-arco' });
+    }
+    return saida;
+}
+/** `git fetch` da base, sem pergunta no terminal e com prazo: e o que faz o merge do GitHub aparecer na batida. */
+function buscarBase(carregado) {
+    const { raiz, manifesto } = carregado;
+    const remoto = manifesto.fabrica.remoto, base = manifesto.worktree.base_branch;
+    if (!(0, util_1.exec)('git', ['remote', 'get-url', '--', remoto], raiz, 30000).ok)
+        return { ok: false, detalhe: `sem o remoto ${remoto}` };
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? 'ssh -o BatchMode=yes' };
+    const r = (0, util_1.exec)('git', ['fetch', '-q', '--no-tags', '--', remoto, `+refs/heads/${base}:refs/remotes/${remoto}/${base}`], raiz, 60000, env);
+    return r.ok ? { ok: true, detalhe: `${remoto}/${base} trazida` }
+        : { ok: false, detalhe: `git fetch ${remoto} ${base} saiu ${r.error ?? r.code}: ${r.stderr.trim().split('\n')[0]?.slice(0, 160) ?? ''}` };
+}
+/**
+ * A batida que age: traz a base, detecta as acoes e faz as que a autorizacao duravel permite, na ordem. Cada acao feita
+ * ou recusada vai ao ledger da thread (`varredura_acao`), com quem autorizou e ate quando; a mesma recusa da vez anterior
+ * nao vira linha nova. Sem autorizacao valida, nada e feito e tudo fica pendente para a fila do pulse.
+ */
+function agirNaVarredura(carregado, opcoes = {}) {
+    const raiz = (0, estado_thread_1.raizDoEstado)(carregado.raiz);
+    const quando = opcoes.quando ?? new Date().toISOString();
+    const leitura = opcoes.autorizacao ?? (0, autorizacao_duravel_1.lerAutorizacao)(raiz, { projeto: carregado.manifesto.project.name, agora: new Date(quando) });
+    const busca = opcoes.buscar === false ? null : buscarBase(carregado);
+    const sessoes = lerSessoes(raiz, opcoes);
+    const pendentes = acoesPendentes(carregado, { quando, fantasmas: () => sessoes.fantasmas, vivas: () => sessoes.vivas, comArco: true });
+    const feitas = [];
+    const ficam = [];
+    const referencia = (0, autorizacao_duravel_1.referenciaDaAutorizacao)(leitura);
+    const gravar = (p, resultado, detalhe) => {
+        const curto = detalhe.slice(0, 400);
+        // A mesma recusa da vez anterior (mesma acao, sessao e motivo) nao vira linha nova a cada batida.
+        const anterior = [...ledgerDe(raiz, p.thread)].reverse().find((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.acaoDaVarredura &&
+            e.acao === p.acao && (p.sessionId === null || e.sessionId === p.sessionId));
+        if (!(resultado === 'recusada' && anterior?.resultado === 'recusada' && anterior.detalhe === curto)) {
+            (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, p.thread), p.thread, ledger_1.TIPOS_DE_EVENTO.acaoDaVarredura, {
+                fase: p.fase, acao: p.acao, resultado, detalhe: curto, comando: p.comando,
+                ...(p.sessionId ? { sessionId: p.sessionId } : {}), origem: 'varredura', autorizacao: referencia,
+                quemDecidiu: referencia ? `varredura do ork, pela autorização durável de ${String(referencia.por)}` : null,
+                evidencia: p.evidencia,
+            });
+        }
+        feitas.push({ acao: p.acao, thread: p.thread, sessionId: p.sessionId, resultado, detalhe });
+    };
+    // `limpar` e uma chamada so para as fantasmas que a deteccao ja viu velhas: e o mesmo `ork sessions limpar-fantasmas`.
+    const aLimpar = pendentes.filter((p) => p.acao === 'limpar' && !p.bloqueio && (0, autorizacao_duravel_1.autorizada)(leitura, 'limpar'));
+    let soltas = null;
+    if (aLimpar.length) {
+        try {
+            const r = (0, sessoes_1.limparFantasmas)(raiz, { origem: 'varredura', sessoes: aLimpar.map((p) => p.sessionId) });
+            soltas = new Map(r.itens.filter((i) => i.thread).map((i) => [`${i.thread}|${i.sessionId}`, i]));
+        }
+        catch (e) {
+            soltas = null;
+            for (const p of aLimpar) {
+                gravar(p, 'recusada', `limpar-fantasmas falhou: ${e.message}`);
+                ficam.push(p);
+            }
+        }
+    }
+    for (const p of pendentes) {
+        if (p.bloqueio || !(0, autorizacao_duravel_1.autorizada)(leitura, p.acao)) {
+            ficam.push(p);
+            continue;
+        }
+        if (p.acao === 'limpar') {
+            if (!soltas)
+                continue;
+            const i = soltas.get(`${p.thread}|${p.sessionId}`);
+            if (i?.acao === 'solto' || i?.acao === 'ja-solto')
+                gravar(p, 'feita', `sessão ${String(p.sessionId).slice(0, 8)} solta: sessao_morta no ledger`);
+            else {
+                gravar(p, 'recusada', i ? `limpar-fantasmas respondeu ${i.acao}` : 'a sessão não apareceu como fantasma na execução');
+                ficam.push(p);
+            }
+            continue;
+        }
+        if (p.acao === 'registrar') {
+            let r;
+            try {
+                r = (0, entrega_pr_1.registrarEntregaPorPr)({ ...carregado, raiz }, p.thread, { buscar: false, remoto: carregado.manifesto.fabrica.remoto });
+            }
+            catch (e) {
+                gravar(p, 'recusada', e.message);
+                ficam.push(p);
+                continue;
+            }
+            if (r.acao === 'registrou' || r.acao === 'ja-registrada')
+                gravar(p, 'feita', `${r.acao}: ${r.motivo}`);
+            else {
+                gravar(p, 'recusada', `${r.acao}: ${r.motivo}`);
+                ficam.push({ ...p, recusa: { em: quando, detalhe: `${r.acao}: ${r.motivo}` } });
+            }
+            continue;
+        }
+        // RM-061 (F2b, G2): o MASTER log, o POSTMORTEM e o registro da omissao nascem em pt-BR, como no CLI.
+        let aceitas = [];
+        try {
+            aceitas = (0, locale_1.comLocale)('pt-BR', () => (0, master_1.aceitarPendentesPorOmissao)(raiz, { thread: p.thread }));
+        }
+        catch (e) {
+            gravar(p, 'recusada', e.message);
+            ficam.push(p);
+            continue;
+        }
+        if (aceitas.length === 1)
+            gravar(p, 'feita', `fechada pelo MASTER por omissão, índice ${aceitas[0].indice.valor}/${aceitas[0].indice.base}`);
+        else {
+            gravar(p, 'recusada', 'nenhuma entrega desta thread esperava o aceite');
+            ficam.push(p);
+        }
+    }
+    return { autorizacao: leitura, busca, feitas, pendentes: ficam };
+}
+/** As acoes feitas pela varredura desde `desde`, de todas as threads (a fechada pelo MASTER inclusive). */
+function acoesFeitasDesde(raiz, desde) {
+    const saida = [];
+    const canonica = (0, estado_thread_1.raizDoEstado)(raiz);
+    for (const id of (0, thread_1.listarIds)(canonica)) {
+        for (const e of ledgerDe(canonica, id)) {
+            if (e.tipo !== ledger_1.TIPOS_DE_EVENTO.acaoDaVarredura || e.resultado !== 'feita' || e.ts < desde)
+                continue;
+            if (!exports.ACOES_DA_VARREDURA.includes(String(e.acao)))
+                continue;
+            saida.push({ acao: e.acao, thread: id, sessionId: typeof e.sessionId === 'string' ? e.sessionId : null,
+                resultado: 'feita', detalhe: typeof e.detalhe === 'string' ? e.detalhe : '', em: e.ts, eventId: String(e.eventId ?? [id, e.ts].join('|')) });
+        }
+    }
+    return saida.sort((a, b) => a.em.localeCompare(b.em));
+}