@orkastery/cli 0.6.0 → 0.6.1

package/dist/session-watcher-grok.js

@@ -0,0 +1,425 @@
+"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.CONTRATO_CURSOR_GROK = exports.HEARTBEAT_GROK_MS = exports.AVISO_DA_RETOMADA_COM_MCP = void 0;
+exports.baseDoArtefato = baseDoArtefato;
+exports.fonteGrokDoDespacho = fonteGrokDoDespacho;
+exports.validarFonteGrok = validarFonteGrok;
+exports.fonteRegistradaGrok = fonteRegistradaGrok;
+exports.resultadoDoDespacho = resultadoDoDespacho;
+exports.classificarSessaoGrok = classificarSessaoGrok;
+exports.observarGrokSobLock = observarGrokSobLock;
+/**
+ * RM-067 (F2 da ork-grokbuild): conclusão de sessões `grok`. O fim vem do que o próprio runtime e o supervisor gravam
+ * (D9): o `end` do stream `streaming-json`, no log do supervisor, e o recibo do supervisor (`.exit.json`, com o código e
+ * o sinal do `close` real). A pasta da sessão (`<GROK_HOME>/sessions/<grupo>/<id>/updates.jsonl`) é prova de existência
+ * e de progresso, só pelo tamanho e pelo mtime: o `ork` nunca lê o conteúdo dela. O texto do agente nunca conclui
+ * nada, e o `end_turn` é necessário e nunca suficiente: a fase só conclui com a prova do `ork` (`provaDoOrk`, a mesma do
+ * claude-bg). Interrupção e fim por limite do runtime vão ao humano com a retomada (`-r <id>`), porque reexecutar a fase
+ * sobre a worktree já alterada é a armadilha que a D13 e a D17 da I-34 evitaram no claude-bg. O lock, a pasta de
+ * sensores e o processo destacado continuam no `session-watcher`; este módulo não o importa, para não criar ciclo.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const grok_1 = require("./adapters/grok");
+const grok_events_1 = require("./adapters/grok-events");
+const codex_runner_1 = require("./adapters/codex-runner");
+const session_events_1 = require("./session-events");
+const ledger_1 = require("./ledger");
+const thread_1 = require("./thread");
+const session_watcher_claude_1 = require("./session-watcher-claude");
+const doctor_pulse_cron_1 = require("./doctor-pulse-cron");
+/**
+ * RM-067 (F4b, GO-FIX A3; F4c, D10): a retomada manual parte do `.grok/config.toml` da worktree como ele está, e a sessão
+ * podia escrever nele no perfil `workspace`. Desde a F4c, o servidor do `ork` morre com a sessão, e o token dele só existia
+ * no ambiente dela (`bearer_token_env_var`): a retomada manual não alcança o MCP do `ork`, nem o servidor de outra sessão que
+ * pegue a mesma porta, que recusa sem o token dela; o `ork retry` sobe outro servidor e reescreve a config antes de redespachar.
+ */
+exports.AVISO_DA_RETOMADA_COM_MCP = 'o servidor MCP do ork terminou com a sessao, e o token dele so existia no ambiente ' +
+    'dela, entao a retomada manual roda sem o MCP do ork e parte do .grok/config.toml da worktree como a sessao o deixou: para ' +
+    'retomar com o MCP, redespache pelo ork retry, que sobe outro servidor e reescreve a config';
+/** D12: no máximo um `runtime_heartbeat` por minuto; o stream do `grok` emite um evento por pedaço de texto. */
+exports.HEARTBEAT_GROK_MS = 60_000;
+exports.CONTRATO_CURSOR_GROK = 'ork.session-cursor-grok/v1';
+/** Bloco lido por observação: uma linha no limite e folga para as seguintes. */
+const BLOCO_GROK_BYTES = grok_events_1.LIMITE_LINHA_GROK + 65536;
+const LIMITE_METADADO_BYTES = 65536;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SHA_COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+/**
+ * D8: a base do artefato da fase, lida ANTES do despacho, como o HEAD do GO. O despacho do grok espera a pasta da
+ * sessão, e a sessão pode gravar o documento antes do registro da fonte: a base lida depois seria o próprio documento.
+ * `null` quando a fase não entrega artefato.
+ */
+function baseDoArtefato(raiz, threadId, fase) {
+    const arquivo = session_watcher_claude_1.ARTEFATO_DA_FASE[fase];
+    return arquivo ? { arquivo, sha256: (0, session_watcher_claude_1.estadoDoArtefato)(raiz, threadId, arquivo).sha256 } : null;
+}
+/**
+ * D8: a fonte do despacho, com a base do artefato e o HEAD do GO lidos antes dele (`noDespacho`); sem a base, ela é
+ * lida agora, como no claude-bg.
+ */
+function fonteGrokDoDespacho(raiz, threadId, fase, cwd, sensores, grokHome, noDespacho = {}) {
+    if (!path.isAbsolute(cwd))
+        throw new Error('despacho grok sem cwd absoluto');
+    const artefato = noDespacho.artefato !== undefined ? noDespacho.artefato : baseDoArtefato(raiz, threadId, fase);
+    return { grok: 'streaming-json', logPath: sensores.logPath, processoPath: sensores.processoPath, reciboPath: sensores.reciboPath,
+        cwd, grokHome,
+        ...(artefato ? { artefato } : {}),
+        ...(fase === 'GO' ? { head: noDespacho.head ?? null } : {}) };
+}
+/** D8: confere a fonte do `grok` contra o despacho e o diretório de sessões da thread. */
+function validarFonteGrok(eventos, sessionId, registro, dirDaThread) {
+    if (registro.grok !== 'streaming-json' || typeof registro.cwd !== 'string' || !path.isAbsolute(registro.cwd) ||
+        typeof registro.grokHome !== 'string' || !path.isAbsolute(registro.grokHome))
+        throw new Error('registro de sensor do grok inválido');
+    const sessoes = path.join(dirDaThread, 'sessoes');
+    if (typeof registro.logPath !== 'string' || registro.logPath !== path.join(sessoes, `${sessionId}.grok.jsonl`) ||
+        registro.processoPath !== `${registro.logPath}.process.json` || registro.reciboPath !== `${registro.logPath}.exit.json`)
+        throw new Error('fonte de sensor do grok fora do diretório canônico de sessões');
+    const despacho = eventos.filter(e => e.tipo === 'phase_dispatch' && e.sessionId === sessionId).at(-1);
+    if (despacho?.cwd !== undefined && despacho.cwd !== registro.cwd)
+        throw new Error('cwd registrado divergente do despacho');
+    if (registro.artefato !== undefined && (!Object.values(session_watcher_claude_1.ARTEFATO_DA_FASE).includes(registro.artefato.arquivo) ||
+        (typeof despacho?.fase === 'string' && session_watcher_claude_1.ARTEFATO_DA_FASE[despacho.fase] !== registro.artefato.arquivo) ||
+        (registro.artefato.sha256 !== null && !SHA256.test(String(registro.artefato.sha256)))))
+        throw new Error('base de artefato do registro do grok inválida');
+    if (registro.head !== undefined && ((registro.head !== null && !SHA_COMMIT.test(String(registro.head))) ||
+        (typeof despacho?.fase === 'string' && despacho.fase !== 'GO')))
+        throw new Error('HEAD de despacho do registro do grok inválido');
+}
+/** A fonte do `grok` registrada para este despacho, se houver. Leitura pura do ledger. */
+function fonteRegistradaGrok(eventos, sessao) {
+    const r = eventos.filter(e => e.tipo === 'session_sensor_registered' && e.sessionId === sessao.sessionId &&
+        e.despachoEm === sessao.despachadaEm).at(-1);
+    return r?.grok === 'streaming-json' ? r : undefined;
+}
+/** D10: o resultado já gravado para este despacho, de qualquer fonte (o observador ou a batida). */
+function resultadoDoDespacho(eventos, sessao) {
+    return eventos.find(e => e.tipo === 'phase_result' && e.sessionId === sessao.sessionId &&
+        (e.despachoEm === undefined || e.despachoEm === sessao.despachadaEm));
+}
+const RETOMADA = 'o estado da sessão ficou salvo até a última ferramenta concluída e os arquivos alterados ficam como estão: ' +
+    'retome a sessão com o comando da retomada ou redespache a fase';
+/**
+ * D9: a tabela de classificação, pura sobre as entradas. A ordem importa: sem recibo, o processo vivo espera; o recibo
+ * de interrupção vem antes do código; a saída 0 só conclui pelo `end`; a outra saída só é tipada pelo `error` do runtime.
+ * GO-FIX 1 (A5): com outra saída e sem `error`, o `end` válido vai ao humano, e o `cancelled` vale como interrupção: o
+ * turno parou, e o `runtime.unavailable` que a batida reexecuta refaria a fase sobre a worktree já alterada.
+ */
+function classificarSessaoGrok(e) {
+    const { estado, recibo } = e;
+    const bloqueio = (motivo, fonte, extra = {}) => ({ terminal: true, classificacao: 'gate_blocked', motivo, fonte, conclusaoNativa: false, diagnostico: fonte, ...extra });
+    const interrupcao = (codigo, sinal, fonte) => bloqueio('human.pending', fonte, { interrupcao: { codigo, sinal, stopReason: estado.fim?.stopReason ?? null },
+        retomar: true, diagnostico: `${fonte}; ${RETOMADA}` });
+    const pelaFim = (comRecibo) => {
+        const fim = estado.fim;
+        if (fim.stopReason === grok_events_1.STOP_CANCELADO)
+            return interrupcao(recibo?.exitCode ?? null, recibo?.signal ?? null, 'end com stopReason cancelled');
+        if (fim.stopReason !== grok_events_1.STOP_FIM_NORMAL) {
+            return bloqueio('human.pending', `end com stopReason ${fim.stopReason}`, { retomar: true,
+                diagnostico: `o grok encerrou o turno por ${fim.stopReason}, sem o fim normal; ${RETOMADA}` });
+        }
+        const sinal = comRecibo ? 'end com stopReason end_turn e saida 0 no recibo do supervisor'
+            : 'end com stopReason end_turn e processo encerrado sem o recibo do supervisor';
+        const prova = e.prova();
+        if (!prova.ok) {
+            return bloqueio(prova.motivo ?? 'human.pending', `${sinal}; sem prova do ork: ${prova.fonte}`, { conclusaoNativa: comRecibo, diagnostico: `sem prova do ork: ${prova.fonte}` });
+        }
+        if (e.pausaAoFim) {
+            return bloqueio('human.pending', `${sinal}; ${prova.fonte}; pausa prevista ao fim do bloco`, { conclusaoNativa: comRecibo, diagnostico: null });
+        }
+        return { terminal: true, classificacao: 'fase_concluida', motivo: null, fonte: `${sinal}; ${prova.fonte}`,
+            conclusaoNativa: comRecibo, diagnostico: null };
+    };
+    const valido = !estado.invalido && !estado.sessaoDivergente;
+    if (!recibo) {
+        if (e.filho === 'vivo')
+            return { terminal: false, espera: 'sessão trabalhando' };
+        if (e.supervisor === 'vivo')
+            return { terminal: false, espera: 'processo do grok encerrado; aguardando o recibo do supervisor' };
+        if (estado.fim && valido && e.filho === 'ausente')
+            return pelaFim(false);
+        if (e.agoraMs - e.progressoEm >= e.limiteMs) {
+            return bloqueio('runtime.unavailable', estado.fim ? 'end sem recibo do supervisor e processo sem prova de vida além do limite'
+                : 'stream sem o evento end, processo sem prova de vida e sem progresso além do limite de estabilidade', { morte: true });
+        }
+        return { terminal: false, espera: 'processo sem prova de vida e sem recibo; aguardando o limite de estabilidade' };
+    }
+    if (recibo.erro)
+        return bloqueio('runtime.unavailable', `o supervisor não iniciou o grok (${recibo.erro})`);
+    if (recibo.exitCode === 130 || recibo.exitCode === 143 || recibo.signal === 'SIGINT' || recibo.signal === 'SIGTERM') {
+        return interrupcao(recibo.exitCode, recibo.signal, `processo interrompido (${recibo.signal ?? `saida ${recibo.exitCode}`}) no recibo do supervisor`);
+    }
+    if (recibo.exitCode === 0) {
+        if (estado.sessaoDivergente)
+            return bloqueio('runtime.unavailable', 'saida 0 com o end sem o id da sessão despachada');
+        if (estado.invalido)
+            return bloqueio('runtime.unavailable', 'saida 0 com linha inválida no stream');
+        if (!estado.fim)
+            return bloqueio('runtime.unavailable', 'saida 0 sem o evento end no stream');
+        return pelaFim(true);
+    }
+    const codigo = recibo.exitCode ?? recibo.signal ?? 'sem codigo';
+    if (estado.erro) {
+        const conta = (0, grok_events_1.falhaDoErroGrok)(estado.erro, e.agoraMs);
+        return bloqueio(conta?.motivo ?? 'runtime.unavailable', `saida ${codigo} com o objeto error do runtime: ${estado.erro.mensagem}`, { erroDoRuntime: estado.erro.mensagem, ...(conta ? { falhaDeConta: conta } : {}) });
+    }
+    if (estado.fim && valido) {
+        if (estado.fim.stopReason === grok_events_1.STOP_CANCELADO) {
+            return interrupcao(recibo.exitCode, recibo.signal, `end com stopReason cancelled e saida ${codigo}`);
+        }
+        return bloqueio('human.pending', `saida ${codigo} depois do end com stopReason ${estado.fim.stopReason}, sem o objeto error`, { retomar: true, diagnostico: `o grok saiu ${codigo} depois de encerrar o turno (${estado.fim.stopReason}), sem o objeto error: ` +
+                `a fase pode ter terminado; ${RETOMADA}` });
+    }
+    return bloqueio('runtime.unavailable', `saida ${codigo} sem o objeto error no stream`);
+}
+function lerJson(arquivo) {
+    let fd;
+    try {
+        fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > LIMITE_METADADO_BYTES)
+            throw new Error('metadado de sensor excessivo');
+        const bytes = Buffer.alloc(st.size);
+        fs.readSync(fd, bytes, 0, st.size, 0);
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * O recibo do supervisor só vale inteiro e do mesmo processo do `.process.json`, como no codex. GO-FIX 1: o código
+ * negativo só vale com o erro de spawn, que o Node entrega como o errno negativo no `close` (`-2` com `ENOENT`).
+ */
+function conferirRecibo(recibo, processo, agoraMs) {
+    const erroDeSpawn = typeof recibo.erro === 'string' && recibo.erro !== '';
+    if (!processo || recibo.schema !== 'ork.codex-process/v1' || recibo.iniciadoEm !== processo.iniciadoEm ||
+        JSON.stringify(recibo.filho) !== JSON.stringify(processo.filho) || !Number.isFinite(Date.parse(recibo.terminadoEm)) ||
+        Date.parse(recibo.terminadoEm) > agoraMs || !Number.isFinite(recibo.duracaoMs) || recibo.duracaoMs < 0 ||
+        (recibo.exitCode !== null && (!Number.isInteger(recibo.exitCode) || (recibo.exitCode < 0 && !erroDeSpawn))) ||
+        (recibo.signal !== null && typeof recibo.signal !== 'string') ||
+        (recibo.erro !== null && typeof recibo.erro !== 'string'))
+        throw new Error('recibo de processo inválido');
+}
+/**
+ * Lê do log do stream o que cresceu desde o cursor, só linhas inteiras. O supervisor abre o log com `O_EXCL` e ele só
+ * cresce: trocado ou encurtado é corrupção, e o stream fica inválido.
+ */
+function lerStream(arquivo, cursor, sessionId) {
+    let fd;
+    try {
+        fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { bytes: 0, eventos: 0, backlog: false, parcial: false, mtimeMs: null };
+        throw e;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            throw new Error('runtime.unavailable: stream do grok não é arquivo comum');
+        if ((cursor.ino !== null && cursor.ino !== st.ino) || st.size < cursor.offset) {
+            cursor.parser = { ...cursor.parser, invalido: true };
+            cursor.ino = st.ino;
+            cursor.offset = st.size;
+            return { bytes: 0, eventos: 0, backlog: false, parcial: false, mtimeMs: st.mtimeMs };
+        }
+        cursor.ino = st.ino;
+        const n = Math.min(BLOCO_GROK_BYTES, st.size - cursor.offset);
+        const buf = Buffer.alloc(n);
+        const lidos = fs.readSync(fd, buf, 0, n, cursor.offset);
+        const parser = new grok_events_1.ParserGrok(sessionId, cursor.parser);
+        const fim = buf.subarray(0, lidos).lastIndexOf(10);
+        if (fim >= 0) {
+            parser.push(buf.subarray(0, fim + 1));
+            cursor.offset += fim + 1;
+        }
+        else if (lidos >= grok_events_1.LIMITE_LINHA_GROK) {
+            parser.estado.invalido = true;
+            cursor.offset += lidos;
+        }
+        cursor.parser = parser.estado;
+        const resta = st.size > cursor.offset;
+        return { bytes: lidos, eventos: parser.eventosValidos, backlog: resta && lidos === BLOCO_GROK_BYTES,
+            parcial: resta && lidos < BLOCO_GROK_BYTES, mtimeMs: st.mtimeMs };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+const tokensIndisponiveis = () => ({ disponivel: false, input: null, cachedInput: null, output: null,
+    total: null, unidade: 'tokens', escopo: 'sessao', fonte: 'unavailable' });
+/** Corpo da observação do `grok`, chamado pelo `session-watcher` já dentro do lock do watcher. */
+function observarGrokSobLock(ctx) {
+    const { raiz, thread, sessao, dir, agoraMs } = ctx;
+    const base = { sessionId: sessao.sessionId, thread: thread.id, concluido: false, bytesLidos: 0 };
+    const resultadoId = `grok:${ctx.chave}`;
+    const gravar = (tipo, dados) => {
+        if (!(0, ledger_1.registrarSeExiste)(dir, thread.id, tipo, dados))
+            throw new Error(session_watcher_claude_1.THREAD_REMOVIDA);
+    };
+    const eventos = (0, ledger_1.lerLedger)(dir);
+    const pronto = resultadoDoDespacho(eventos, sessao);
+    if (pronto)
+        return { ...base, concluido: true, classificacao: String(pronto.classificacao) };
+    const fonte = fonteRegistradaGrok(eventos, sessao);
+    if (!fonte)
+        throw new Error('fonte de sensor do grok ausente');
+    validarFonteGrok(eventos, sessao.sessionId, fonte, dir);
+    const arquivoCursor = path.join(ctx.pasta, 'cursor-grok.json');
+    const lido = lerJson(arquivoCursor);
+    if (lido && (lido.schema !== exports.CONTRATO_CURSOR_GROK || lido.sessionId !== sessao.sessionId || lido.despachoEm !== sessao.despachadaEm))
+        throw new Error('cursor de outra sessão/despacho');
+    const cursor = lido ?? { schema: exports.CONTRATO_CURSOR_GROK, sessionId: sessao.sessionId, despachoEm: sessao.despachadaEm,
+        ino: null, offset: 0, parser: new grok_events_1.ParserGrok(sessao.sessionId).estado, progressoEm: Date.parse(sessao.despachadaEm),
+        heartbeatEm: 0, updatesBytes: null };
+    // A ordem das leituras é a do supervisor ao contrário: ele grava o recibo depois do `close` do filho e só então sai.
+    // GO-FIX 2 (N1): a vida antes do recibo; o supervisor visto ausente já deixou no disco o recibo que gravaria.
+    // GO-FIX 1 (A2): o recibo antes do stream; com o recibo no disco, o stream lido em seguida está inteiro.
+    const processo = lerJson(fonte.processoPath);
+    const vida = { filho: (0, codex_runner_1.estadoProcesso)(processo?.filho ?? null), supervisor: (0, codex_runner_1.estadoProcesso)(processo?.supervisor ?? null) };
+    const recibo = lerJson(fonte.reciboPath);
+    if (recibo)
+        conferirRecibo(recibo, processo, ctx.relogioReal ? Date.now() : agoraMs);
+    const leitura = lerStream(fonte.logPath, cursor, sessao.sessionId);
+    let progrediu = false;
+    if (leitura.eventos > 0 && leitura.mtimeMs !== null) {
+        progrediu = true;
+        cursor.progressoEm = Math.max(cursor.progressoEm, Math.min(agoraMs, leitura.mtimeMs));
+    }
+    // O processo terminou e a última linha não terminou: ela nunca vai se completar.
+    if (recibo && leitura.parcial)
+        cursor.parser = { ...cursor.parser, invalido: true };
+    // A pasta da sessão é do runtime: só o tamanho do `updates.jsonl` conta como progresso, nunca o conteúdo.
+    const emDisco = (0, grok_1.acharSessaoGrok)(sessao.sessionId, fonte.grokHome);
+    if (emDisco && (cursor.updatesBytes === null || emDisco.tamanho > cursor.updatesBytes)) {
+        progrediu = true;
+        cursor.progressoEm = Math.max(cursor.progressoEm, Math.min(agoraMs, emDisco.mtimeMs));
+    }
+    if (emDisco)
+        cursor.updatesBytes = emDisco.tamanho;
+    let prova;
+    const c = leitura.backlog ? { terminal: false, espera: 'stream com bytes ainda não lidos' }
+        : classificarSessaoGrok({ estado: cursor.parser,
+            recibo: recibo ? { exitCode: recibo.exitCode, signal: recibo.signal, erro: recibo.erro, duracaoMs: recibo.duracaoMs } : null,
+            filho: recibo ? 'ausente' : vida.filho,
+            supervisor: recibo ? 'ausente' : vida.supervisor,
+            progressoEm: cursor.progressoEm, agoraMs, limiteMs: ctx.limiteMs, pausaAoFim: (0, thread_1.pausaNaThread)(thread, sessao.fase),
+            prova: () => prova ??= (0, session_watcher_claude_1.provaDoOrk)(raiz, thread.id, sessao, eventos, fonte) });
+    (0, codex_runner_1.gravarAtomico)(arquivoCursor, cursor);
+    if (!(0, ledger_1.threadPresente)(dir)) {
+        fs.rmSync(arquivoCursor, { force: true });
+        throw new Error(session_watcher_claude_1.THREAD_REMOVIDA);
+    }
+    return (0, session_events_1.comLockDeSessao)(dir, () => {
+        const atuais = (0, ledger_1.lerLedger)(dir);
+        if (progrediu && (cursor.heartbeatEm === 0 || cursor.progressoEm - cursor.heartbeatEm >= exports.HEARTBEAT_GROK_MS)) {
+            const heartbeatId = `${resultadoId}:heartbeat:${cursor.progressoEm}`;
+            if (!atuais.some(e => e.sensorEventId === heartbeatId))
+                gravar('runtime_heartbeat', {
+                    ts: new Date(cursor.progressoEm).toISOString(), fase: sessao.fase, sessionId: sessao.sessionId,
+                    despachoEm: sessao.despachadaEm, sensorEventId: heartbeatId, runtime: 'grok',
+                    fonte: 'progresso do stream ou do updates.jsonl do grok', bytesLidos: leitura.bytes
+                });
+            cursor.heartbeatEm = cursor.progressoEm;
+            (0, codex_runner_1.gravarAtomico)(arquivoCursor, cursor);
+        }
+        if (!c.terminal)
+            return { ...base, bytesLidos: leitura.bytes, espera: c.espera };
+        const ja = resultadoDoDespacho(atuais, sessao);
+        if (ja)
+            return { ...base, bytesLidos: leitura.bytes, concluido: true, classificacao: String(ja.classificacao) };
+        // RM-067 (F4b, G8 e D6): com o MCP, a sessão grava commit, artefato e verify pelo núcleo até o fim, e o ledger da prova
+        // foi lido antes do recibo. A prova é refeita sobre o ledger relido sob o lock; se mudou, a decisão fica para a próxima
+        // volta, como a do Stop no claude-bg. Converge: a prova só muda com evento novo do intervalo. GO-FIX A1: a prova inteira
+        // (o `verify` do CHECK, os commits do GO, o evento do SHIP e do MASTER), não só o texto, porque o `phase_result` a grava.
+        if (prova !== undefined && JSON.stringify((0, session_watcher_claude_1.provaDoOrk)(raiz, thread.id, sessao, atuais, fonte)) !== JSON.stringify(prova))
+            return { ...base, bytesLidos: leitura.bytes, espera: 'evento do núcleo gravado durante a observação; reavaliar na próxima volta' };
+        const despacho = atuais.filter(e => e.tipo === 'phase_dispatch' && e.sessionId === sessao.sessionId).at(-1);
+        const comando = Array.isArray(despacho?.comando) && despacho.comando.every(a => typeof a === 'string') ? despacho.comando : [];
+        const retomada = c.retomar ? (0, grok_1.montarComandoDeRetomada)(comando, sessao.sessionId) : null;
+        const artefato = (0, session_watcher_claude_1.saidaDoArtefato)(raiz, thread.id, sessao, fonte, eventos);
+        const fim = cursor.parser.fim;
+        // GO-FIX 1 (S4): o comando da retomada vai pronto para colar, com aspas no argumento que precisa delas. RM-067 (F4b, D5):
+        // com as variáveis do filho na frente, para a sessão retomada também não carregar o MCP de outros clientes. GO-FIX A3: com
+        // o MCP do ork, a retomada parte da config que a sessão podia escrever, e o detalhe diz isso.
+        const ambiente = Object.entries(grok_1.AMBIENTE_SEM_MCP_DE_OUTROS_CLIENTES).map(([nome, valor]) => `${nome}=${valor}`);
+        // GO-FIX N4: o aviso vem antes do comando, que pode levar uma dezena de regras e as telas cortam o detalhe no fim.
+        const comMcp = retomada?.some((a) => a.startsWith('MCPTool(orkastery__')) ? `; ${exports.AVISO_DA_RETOMADA_COM_MCP}` : '';
+        const detalhe = c.diagnostico === null ? null
+            : retomada ? `${c.diagnostico}${comMcp}; retomada: ${[...ambiente, ...retomada.map(doctor_pulse_cron_1.citarNoShell)].join(' ')}` : c.diagnostico;
+        const dados = { fase: sessao.fase, sessionId: sessao.sessionId, despachoEm: sessao.despachadaEm, sensorResultId: resultadoId,
+            classificacao: c.classificacao, motivo: c.motivo, runtime: 'grok', fonte: c.fonte,
+            stopReason: fim?.stopReason ?? null, numTurnos: fim?.numTurnos ?? null, tokens: fim?.tokens ?? tokensIndisponiveis(),
+            custoUsd: fim?.custoUsd ?? null,
+            exitCode: recibo?.exitCode ?? null, exitCodeFonte: recibo ? 'supervisor.close' : 'unavailable', signal: recibo?.signal ?? null,
+            duracaoMs: recibo?.duracaoMs ?? null, duracaoFonte: recibo ? 'supervisor.close' : 'unavailable',
+            ok: c.classificacao === 'fase_concluida' && recibo?.exitCode === 0,
+            estado: c.classificacao === 'fase_concluida' ? 'concluida' : 'bloqueada',
+            conclusaoNativa: c.conclusaoNativa, conclusaoNativaAusente: c.conclusaoNativa ? null : c.fonte,
+            ...(artefato ? { artefato: { arquivo: artefato.arquivo, sha256Base: artefato.sha256Base, sha256Atual: artefato.sha256 } } : {}),
+            ...(prova ? { provaOrk: prova } : {}),
+            ...(c.interrupcao ? { interrupcao: c.interrupcao } : {}),
+            ...(c.retomar ? { retomada: retomada ? { sessionId: sessao.sessionId, comando: retomada } : null } : {}),
+            ...(c.erroDoRuntime ? { erroDoRuntime: c.erroDoRuntime } : {}),
+            ...(c.falhaDeConta ? { falhaDeConta: { motivo: c.falhaDeConta.motivo, resetEm: c.falhaDeConta.resetEm,
+                    fonte: c.falhaDeConta.fonte, trecho: c.falhaDeConta.trecho } } : {}),
+            // D18 da I-34: o diagnóstico vai ao pedido HITL e, como `detalhe` do `gate_blocked`, ao monitor e ao pulse.
+            diagnostico: c.diagnostico, ...(detalhe ? { detalhe } : {}),
+            observadoEm: new Date(agoraMs).toISOString(), gate: 'phase.dispatch', origem: 'sessions.watch',
+            morteLatenciaMs: c.morte ? agoraMs - cursor.progressoEm : null };
+        // GO-FIX 1 (S1): cada evento do fim uma vez por despacho, como nos outros observadores; o processo que morre entre as
+        // gravações não repete o `gate_blocked` na volta seguinte.
+        const gravarUmaVez = (tipo) => {
+            if (!atuais.some(e => e.tipo === tipo && e.sensorResultId === resultadoId))
+                gravar(tipo, dados);
+        };
+        if (c.morte)
+            gravarUmaVez('sessao_morta');
+        gravarUmaVez(c.classificacao);
+        gravar('phase_result', dados);
+        return { ...base, bytesLidos: leitura.bytes, concluido: true, classificacao: c.classificacao };
+    });
+}

package/dist/session-watcher.js

@@ -58,6 +58,7 @@ const codex_controller_sensor_1 = require("./adapters/codex-controller-sensor");
 const retry_1 = require("./retry");
 const ratelimit_1 = require("./ratelimit");
 const session_watcher_claude_1 = require("./session-watcher-claude");
+const session_watcher_grok_1 = require("./session-watcher-grok");
 const conta_esgotada_1 = require("./conta-esgotada");
 const trabalho_thread_1 = require("./trabalho-thread");
 /** Falhas operacionais e bloqueios sem retry automático não alegam conclusão do produto. */
@@ -286,7 +287,7 @@ function conferirRegistro(dir, registro) {
  * com o dono da remoção.
  */
 function desfazerNaThreadRemovida(pasta, criadas) {
-    for (const cursor of ['cursor.json', 'cursor-claude.json']) {
+    for (const cursor of ['cursor.json', 'cursor-claude.json', 'cursor-grok.json']) {
         try {
             fs.rmSync(path.join(pasta, cursor), { force: true });
         }
@@ -393,7 +394,7 @@ function reconciliarSessaoSemWatcher(carregado, threadId, agoraMs = Date.now())
     const ignorada = (detalhe) => ({ thread: threadId,
         sessionId: sessao?.sessionId ?? null, estado: 'ignorada', detalhe });
     if (thread.status === 'fechada' || !sessao || sessao.verificada !== true ||
-        !['codex', 'claude-bg'].includes(sessao.runtime) || typeof sessao.despachadaEm !== 'string')
+        !['codex', 'claude-bg', 'grok'].includes(sessao.runtime) || typeof sessao.despachadaEm !== 'string')
         return ignorada('sem sessão despachada e verificada que o watcher possa reconciliar');
     const dir = (0, thread_1.dirThread)(carregado.raiz, threadId);
     let eventos = (0, ledger_1.lerLedger)(dir);
@@ -489,8 +490,8 @@ function reconciliarSessaoSemWatcher(carregado, threadId, agoraMs = Date.now())
 }
 function observarSessaoResolvida(carregado, sessionId, { thread, sessao: registrada }, opcoes) {
     const sessao = (0, session_events_1.exigirSessaoDespachada)(registrada, sessionId);
-    if (sessao.runtime !== 'codex' && sessao.runtime !== 'claude-bg')
-        throw new Error('watch requer sessão Codex ou claude-bg registrada');
+    if (sessao.runtime !== 'codex' && sessao.runtime !== 'claude-bg' && sessao.runtime !== 'grok')
+        throw new Error('watch requer sessão Codex ou claude-bg ou grok registrada');
     const now = opcoes.agoraMs ?? Date.now();
     if (!Number.isFinite(now))
         throw new Error('relógio inválido');
@@ -526,6 +527,12 @@ function observarSessaoResolvida(carregado, sessionId, { thread, sessao: registr
                 thread, sessao, dir, pasta, chave, agoraMs: now, limiteMs: exports.LIMITE_MORTE_MS, consulta: opcoes.consultaClaude, carregado })) ?? { ...base, ocupado: true };
             return (0, ledger_1.threadPresente)(dir) ? r : desfazer();
         }
+        // RM-067 (F2): o grok tem observador próprio (stream, recibo do supervisor e pasta da sessão), no mesmo lock.
+        if (sessao.runtime === 'grok') {
+            const r = comLockWatcher(pasta, () => (0, session_watcher_grok_1.observarGrokSobLock)({ raiz: carregado.raiz, thread, sessao, dir, pasta, chave,
+                agoraMs: now, limiteMs: exports.LIMITE_MORTE_MS, relogioReal: opcoes.agoraMs === undefined })) ?? { ...base, ocupado: true };
+            return (0, ledger_1.threadPresente)(dir) ? r : desfazer();
+        }
         let contaParaReconciliar = null;
         const observado = comLockWatcher(pasta, () => {
             const eventos = (0, ledger_1.lerLedger)(dir), resultadoId = `codex:${chave}`;
@@ -798,6 +805,10 @@ function validarRegistroWatcher(raiz, sessionId, fonte) {
         throw new Error('fonte nativa claude-agents em sessão de outro runtime');
     if (registro.controlador && sessao.runtime !== 'codex')
         throw new Error('fonte do controller Codex em sessão de outro runtime');
+    if (registro.grok !== undefined && sessao.runtime !== 'grok')
+        throw new Error('fonte do grok em sessão de outro runtime');
+    if (sessao.runtime === 'grok' && registro.grok === undefined)
+        throw new Error('sessão grok sem a fonte do grok');
     return { thread, sessao, dir, eventos, registro };
 }
 /** Validação profunda feita pelo laço: prontidão eventual nunca impede o registro do vínculo. */
@@ -807,6 +818,10 @@ function validarFonteWatcher(raiz, sessionId, fonte) {
         (0, session_watcher_claude_1.validarFonteClaude)(eventos, sessionId, registro);
         return;
     }
+    if (registro.grok !== undefined) {
+        (0, session_watcher_grok_1.validarFonteGrok)(eventos, sessionId, registro, dir);
+        return;
+    }
     if (registro.controlador) {
         const despacho = eventos.filter(e => e.tipo === 'phase_dispatch' && e.sessionId === sessionId).at(-1);
         if (despacho?.controlador !== undefined && despacho.controlador !== registro.controlador)

package/dist/sessoes-contas.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIMES_DAS_SESSOES = void 0;
 exports.pidVivo = pidVivo;
 exports.ehFantasma = ehFantasma;
 exports.encerradaNaLista = encerradaNaLista;
@@ -49,6 +50,10 @@ exports.sessoesVivasPorPerfil = sessoesVivasPorPerfil;
  * perfil do store, sem repetir diretorio, e cada sessao volta com o id do perfil dela (nunca o
  * diretorio nem nada de dentro dele).
  *
+ * RM-067 (F4): o `grok` entra com a pasta `sessions/` que o proprio runtime grava em cada casa (`GROK_HOME`), lida so
+ * pelos nomes e pelo mtime do `updates.jsonl`. A conta do processo dele so entra quando essa pasta existe: maquina sem o
+ * `grok` nao ganha fonte nova.
+ *
  * Fantasma (D5): sessao claude-bg com estado nao terminal sem pid, ou com pid sem processo. O
  * `claude agents` guarda o registro, mas nao ha quem trabalhe: ela nao ocupa vaga, e
  * `ork sessions limpar-fantasmas` solta o vinculo do `ork` sem tocar no runtime.
@@ -57,6 +62,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const claude_bg_1 = require("./adapters/claude-bg");
 const codex_1 = require("./adapters/codex");
+const grok_1 = require("./adapters/grok");
 const runtime_profiles_1 = require("./runtime-profiles");
 const TERMINAIS = ['done', 'completed', 'exited', 'stopped', 'failed'];
 const estadoDe = (s) => String(s.state ?? s.status ?? '').trim().toLowerCase();
@@ -108,17 +114,26 @@ function contasDeSessoes(raiz, env = process.env) {
         try {
             for (const p of (0, runtime_profiles_1.lerPerfis)(raiz).perfis) {
                 const d = (0, runtime_profiles_1.perfilDeDespacho)(p);
-                incluir(d.runtime, d, (d.configDir ?? d.codexHome));
+                if (exports.RUNTIMES_DAS_SESSOES.includes(d.runtime))
+                    incluir(d.runtime, d, (0, runtime_profiles_1.diretorioDoPerfil)(d));
             }
         }
         catch (e) {
             fontes.push({ origem: 'perfis de conta (ork accounts)', ok: false, detalhe: e.message });
         }
     }
-    for (const runtime of runtime_profiles_1.RUNTIMES_COM_PERFIL)
+    for (const runtime of runtime_profiles_1.RUNTIMES_COM_INVENTARIO)
         incluir(runtime, null, (0, runtime_profiles_1.diretorioImplicito)(runtime, env));
+    const casaGrok = (0, runtime_profiles_1.diretorioImplicito)('grok', env);
+    if (fs.existsSync(path.join(casaGrok, 'sessions')))
+        incluir('grok', null, casaGrok);
     return { contas, fontes };
 }
+/**
+ * RM-067 (F4): os runtimes cujas sessoes o `ork sessions` lista por conta. O grok entra aqui, e nao em
+ * `RUNTIMES_COM_INVENTARIO`, que tambem diz os runtimes de assinatura do #Noctum (a medicao dele segue sem o grok).
+ */
+exports.RUNTIMES_DAS_SESSOES = [...runtime_profiles_1.RUNTIMES_COM_INVENTARIO, 'grok'];
 const rotulo = (c) => c.perfil ? `perfil ${c.perfil.id}` : 'conta do processo';
 /**
  * D4: as sessoes de todas as contas. Consulta que falha vira fonte `ok: false`, nunca "zero
@@ -154,7 +169,7 @@ function consultarContas(raiz, opcoes = {}) {
                 sessoes.push({ ...s, runtime: 'claude-bg', perfil, fantasma, viva: !fantasma && !TERMINAIS.includes(estadoDe(s)) });
             }
         }
-        else {
+        else if (conta.runtime === 'codex') {
             const r = (0, codex_1.consultarRollouts)(opcoes.todas, conta.dir);
             // A conta do processo segue com o caminho de antes; a do perfil vai pelo id, nunca pela pasta.
             fontes.push(...(conta.perfil ? r.resultadosFontes.map(f => ({ ...f,
@@ -164,6 +179,17 @@ function consultarContas(raiz, opcoes = {}) {
                 sessoes.push({ ...s, runtime: 'codex', perfil, fantasma: false, viva: estadoDe(s) !== 'completed' && recente });
             }
         }
+        else if (conta.runtime === 'grok') {
+            // RM-067 (F4): a pasta da sessao que o runtime grava; viva e a escrita recente no updates.jsonl, como no codex.
+            const r = (0, grok_1.consultarSessoesGrok)(conta.dir);
+            const origem = `grok sessions (${rotulo(conta)})`;
+            fontes.push(r.ausente ? { origem, ok: true, ausente: true, detalhe: 'nenhuma sessao grok nesta conta ainda' }
+                : { origem, ok: r.ok, detalhe: r.detalhe });
+            for (const s of r.sessoes) {
+                const recente = typeof s.atividadeEm === 'number' && agoraMs - s.atividadeEm <= janelaMs;
+                sessoes.push({ ...s, runtime: 'grok', perfil, fantasma: false, viva: recente });
+            }
+        }
     }
     return { sessoes, fontes, contas: base.contas };
 }
@@ -176,10 +202,12 @@ function consultarContas(raiz, opcoes = {}) {
 function estadosNasContas(raiz, opcoes = {}) {
     const r = consultarContas(raiz, opcoes);
     const claude = r.fontes.filter(f => f.origem.startsWith('claude agents'));
-    if (claude.length > 0 && !claude.some(f => f.ok) && !r.sessoes.some(s => s.runtime === 'codex'))
+    if (claude.length > 0 && !claude.some(f => f.ok) && !r.sessoes.some(s => s.runtime === 'codex' || s.runtime === 'grok'))
         return null;
+    // RM-067 (F4): a sessao grok sem escrita recente fica `idle`; o runtime nao grava estado terminal que o ork leia sem o conteudo.
     return new Map(r.sessoes.map(s => [s.sessionId,
-        s.fantasma ? 'fantasma' : s.runtime === 'codex' ? (s.viva ? 'working' : estadoDe(s)) : estadoDe(s)]));
+        s.fantasma ? 'fantasma' : s.runtime === 'codex' ? (s.viva ? 'working' : estadoDe(s))
+            : s.runtime === 'grok' ? (s.viva ? 'working' : 'idle') : estadoDe(s)]));
 }
 /**
  * RM-056 (D3): sessoes vivas de cada perfil do runtime nesta maquina, a carga do rodizio por