@orkastery/cli 0.6.0 → 0.6.2

package/dist/adapters/grok.js

@@ -0,0 +1,686 @@
+"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.IGNORADOS_DA_CONFIG_DO_FILHO = exports.MARCA_DA_CONFIG_DO_FILHO = exports.ESPERA_PADRAO_MS = exports.ESFORCO_DO_GROK = exports.PERFIL_DE_SANDBOX_PADRAO = exports.PERFIL_DE_SANDBOX_DO_GROK = exports.AMBIENTE_SEM_MCP_DE_OUTROS_CLIENTES = exports.ENVS_REMOVIDAS_DO_DESPACHO = exports.FONTE_VERIFICACAO = exports.NOME_ADAPTER = void 0;
+exports.esforcoDoGrok = esforcoDoGrok;
+exports.ferramentasDoGrok = ferramentasDoGrok;
+exports.ferramentasServidasAoGrok = ferramentasServidasAoGrok;
+exports.ambienteDoDespacho = ambienteDoDespacho;
+exports.ambienteDoFilho = ambienteDoFilho;
+exports.comandoDeLogin = comandoDeLogin;
+exports.conferirAuth = conferirAuth;
+exports.disponivel = disponivel;
+exports.versao = versao;
+exports.casaDoGrok = casaDoGrok;
+exports.perfilDeSandbox = perfilDeSandbox;
+exports.montarComando = montarComando;
+exports.configDoFilho = configDoFilho;
+exports.gravarConfigDaWorktree = gravarConfigDaWorktree;
+exports.montarComandoDeRetomada = montarComandoDeRetomada;
+exports.acharSessaoGrok = acharSessaoGrok;
+exports.consultarSessoesGrok = consultarSessoesGrok;
+exports.despachar = despachar;
+/**
+ * RM-067 (F1 da ork-grokbuild): runtime `grok`, o Grok Build headless da xAI. Nasceu só para despacho explícito
+ * (`ork phase run --runtime grok`, D1); desde a F4, é runtime de bloco no setup, nunca o padrão do projeto, e desde a F4b
+ * leva o MCP do `ork` pela config que o despacho grava na worktree (`gravarConfigDaWorktree`). Desde a F4c, o servidor
+ * dessa config é um processo do `ork`, fora do sandbox do `grok` (`grok-mcp.ts`), e o `grok` se conecta a ele por `url`, com o
+ * token do despacho só no ambiente (`bearer_token_env_var`).
+ *
+ * O despacho roda `grok -p <prompt> --output-format streaming-json -s <id>` desanexado, pelo supervisor do `codex-runner`
+ * (D6): o log do stream, o `.process.json` com a identidade do filho e o `.exit.json` com o código e o sinal do `close`
+ * real. O id da sessão é escolhido pelo `ork` (D5), e a prova de que ela existe é a pasta
+ * `<GROK_HOME>/sessions/<grupo>/<id>/` com o `updates.jsonl`, que o próprio runtime grava. O `ork` só lista nomes e lê o
+ * tamanho e o mtime desse arquivo, nunca o conteúdo, e nunca abre o `auth.json`. O fim da sessão é do watcher
+ * (`session-watcher-grok.ts`), pelo `end` do stream e pelo recibo do supervisor.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const smol_toml_1 = require("smol-toml");
+const runtime_ambiente_1 = require("../runtime-ambiente");
+const runtime_context_1 = require("../runtime-context");
+const runtime_profiles_1 = require("../runtime-profiles");
+const util_1 = require("../util");
+const claude_bg_1 = require("./claude-bg");
+const codex_runner_1 = require("./codex-runner");
+const grok_events_1 = require("./grok-events");
+const grok_mcp_1 = require("./grok-mcp");
+const mcp_grafo_1 = require("../mcp-grafo");
+exports.NOME_ADAPTER = 'grok';
+/** De onde vem a prova de que a sessão existe (vai ao `phase_dispatch_verified`). */
+exports.FONTE_VERIFICACAO = 'pasta da sessao em $GROK_HOME/sessions';
+/**
+ * D4: o ambiente do filho é o da assinatura, sem as variáveis de provider pago e sem `XAI_API_KEY`. A D1 da RM-067 foi
+ * decidida pelo dono em 27/10/2026 pela alternativa b (a assinatura agora): o filho autentica pelo login que o próprio
+ * `grok` guardou no `GROK_HOME` do perfil, nunca pela chave. Tirar a variável do ambiente não lê nem copia a credencial.
+ * RM-067 (F4c, GO-FIX 2, R3): o token do servidor do `ork` herdado de uma sessão (o `ork` rodado no shell dela) também sai;
+ * o despacho com o MCP põe o token dele por cima.
+ */
+exports.ENVS_REMOVIDAS_DO_DESPACHO = [...runtime_ambiente_1.ENVS_DE_PROVIDER_PAGO, 'XAI_API_KEY', grok_mcp_1.ENV_DO_TOKEN_DO_SERVIDOR_GROK];
+/**
+ * RM-067 (F4b, G4 e D5): o filho do `grok` nunca carrega o MCP de outros clientes. Por padrão, o `grok` lê a config de MCP
+ * do Claude e a do Cursor (G16); as duas variáveis desligam essa leitura (`false` ou `0`, G5), com ou sem o MCP do `ork`.
+ */
+exports.AMBIENTE_SEM_MCP_DE_OUTROS_CLIENTES = Object.freeze({
+    GROK_CLAUDE_MCPS_ENABLED: '0', GROK_CURSOR_MCPS_ENABLED: '0',
+});
+/**
+ * D3 e F4 (E7 da RM-067): a postura de sandbox do manifesto (vocabulário do Codex) no perfil do `grok` (`--sandbox`).
+ * `workspace` é o piso, o perfil de toda postura que não afrouxa (o `grok` usa Landlock, não o bubblewrap do Codex). A
+ * postura mais frouxa (`danger-full-access`) vira `off`, sem sandbox, e só despacha com `ork setup sandbox confirmar`
+ * nesta máquina: sem a confirmação, o `ork phase run` e o `ork retry` recusam com `runtime.sandbox-nao-confirmado`
+ * (`postura-local.ts`) antes de montar o comando. O `strict` do `grok` não tem postura do Orkastery que o peça. Nenhuma
+ * postura aprova tudo: nunca `--yolo`, `--always-approve` nem `--permission-mode bypassPermissions`.
+ */
+exports.PERFIL_DE_SANDBOX_DO_GROK = Object.freeze({
+    'read-only': 'read-only',
+    'workspace-write': 'workspace',
+    'danger-full-access': 'off',
+});
+exports.PERFIL_DE_SANDBOX_PADRAO = 'workspace';
+/**
+ * RM-067 (F4, E6): o esforço do Orkastery nos níveis canônicos do `grok` (`none`, `minimal`, `low`, `medium`, `high`,
+ * `xhigh`, `max`, no guia headless). O `eco` vira `minimal`, para a escada de esforço (`eco` antes de `low`) seguir com
+ * degraus distintos; os outros cinco têm o mesmo nome. Cada modelo só aceita os níveis que o próprio menu anuncia, e esse
+ * menu só o runtime conhece (`grok models`): o nível que o modelo não anuncia é recusado pelo próprio `grok` no despacho.
+ * Valor fora da tabela vai como veio, porque o `grok` também aceita o id de uma opção do menu do modelo.
+ */
+exports.ESFORCO_DO_GROK = Object.freeze({
+    eco: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max',
+});
+/** O nível do `--effort` do `grok` para o esforço do Orkastery (E6). */
+function esforcoDoGrok(effort) {
+    const chave = effort.trim().toLowerCase();
+    return Object.hasOwn(exports.ESFORCO_DO_GROK, chave) ? exports.ESFORCO_DO_GROK[chave] : effort.trim();
+}
+/** O prefixo das ferramentas do servidor `orkastery` no `--allowedTools` do `claude-bg`. */
+const PREFIXO_DO_CLAUDE = 'mcp__orkastery__';
+/**
+ * RM-067 (F4b, G2 e D1): as ferramentas do MCP do `ork` que um despacho do `grok` libera, as mesmas do `--allowedTools` do
+ * `claude-bg` no mesmo caso, sem o prefixo: no PLAN que fecha o bloco, as consultas, `ork_artifact_write` e
+ * `ork_decision_record`, em qualquer perfil; fora dele, as consultas e, no perfil `worktree`, `ork_git_status` e as sete
+ * mutações. As consultas do grafo entram com a flag do manifesto da raiz. Montada na chamada, como no `claude-bg`: no
+ * ciclo de imports, o valor importado pode ainda não existir quando este módulo carrega.
+ */
+function ferramentasDoGrok(perfil, plano, grafo) {
+    const semPrefixo = (nomes) => nomes.map((n) => n.slice(PREFIXO_DO_CLAUDE.length));
+    const consultas = [...semPrefixo(claude_bg_1.CONSULTAS_MCP), ...(grafo ? mcp_grafo_1.TOOLS_DO_GRAFO : [])];
+    if (plano)
+        return [...consultas, 'ork_artifact_write', 'ork_decision_record'];
+    return perfil === 'worktree' ? [...consultas, 'ork_git_status', ...semPrefixo(claude_bg_1.MUTACOES_WORKTREE)] : consultas;
+}
+/**
+ * RM-067 (F4b, G1): o que o servidor `--host grok` lista, para o perfil filho da instalação: a união dos dois casos de
+ * `ferramentasDoGrok` (o PLAN e o resto do bloco). O headless não aprova ferramenta em diálogo, então o servidor não lista
+ * nada que o `--allow` de algum despacho desse perfil não libere.
+ */
+function ferramentasServidasAoGrok(perfil, grafo) {
+    return [...new Set([...ferramentasDoGrok(perfil, false, grafo), ...ferramentasDoGrok(perfil, true, grafo)])];
+}
+/** D6: quanto o despacho espera a pasta da sessão ou o recibo do supervisor. */
+exports.ESPERA_PADRAO_MS = 60_000;
+const ID_DE_SESSAO = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const LIMITE_METADADO_BYTES = 65536;
+const LIMITE_STDERR_BYTES = 4096;
+/** O stderr do resultado: o despacho grava os primeiros 500 caracteres dele no ledger. */
+const LIMITE_STDERR_NO_RESULTADO = 500;
+/** D4: o ambiente do despacho, sem provider pago e sem `XAI_API_KEY`; o `GROK_HOME` do processo fica. */
+function ambienteDoDespacho(base = process.env) {
+    const env = (0, runtime_ambiente_1.ambienteDeAssinatura)(base);
+    for (const nome of exports.ENVS_REMOVIDAS_DO_DESPACHO)
+        delete env[nome];
+    return env;
+}
+/**
+ * O ambiente do filho: o do despacho, com o `GROK_HOME` do perfil (F3) e o contexto da condução por cima. Perfil de outro
+ * runtime, ou sem `grokHome`, recusa: cair para a casa do processo seria despachar pela conta errada. RM-067 (F4b): as
+ * duas variáveis que desligam o MCP de outros clientes vão por último, para nada as desfazer.
+ */
+function ambienteDoFilho(pedido, base = process.env) {
+    if (pedido.perfil && (pedido.perfil.runtime !== 'grok' || !pedido.perfil.grokHome))
+        throw new Error('runtime.profiles.invalid: perfil sem grokHome no despacho grok');
+    return { ...(0, runtime_profiles_1.ambienteComPerfil)(ambienteDoDespacho(base), pedido.perfil), ...(pedido.ambienteExtra ?? {}),
+        ...exports.AMBIENTE_SEM_MCP_DE_OUTROS_CLIENTES };
+}
+/**
+ * RM-067 (F3): o login do perfil é sempre do próprio CLI, com o `GROK_HOME` do perfil: `grok login` pelo navegador ou
+ * `grok login --device-auth` pelo código de dispositivo (G3, G4 da página). O `ork` nunca abre o `auth.json` que o
+ * `grok` grava.
+ */
+function comandoDeLogin(codigoDeDispositivo = false) {
+    return ['grok', 'login', ...(codigoDeDispositivo ? ['--device-auth'] : [])];
+}
+/**
+ * RM-067 (F3): a conferência de login do perfil. O `grok` não documenta um comando de status do login (fontes da página),
+ * e o `ork` nunca lê o `auth.json`: a conferência fica sem medida (`semConferencia`), o perfil segue no rodízio e quem
+ * prova o login é o próprio despacho, cujo erro de login do runtime vira `runtime.auth-missing` e tira o perfil.
+ */
+function conferirAuth(perfil) {
+    try {
+        ambienteDoFilho({ perfil: perfil ?? undefined });
+    }
+    catch (e) {
+        return { ok: false, detalhe: e.message };
+    }
+    return { ok: true, semConferencia: true,
+        detalhe: 'o grok nao documenta conferencia de login; o despacho prova o login (erro de login do runtime vira runtime.auth-missing)' };
+}
+/** O runtime está disponível? No PATH do ambiente informado (o do filho, no despacho). */
+function disponivel(env = process.env) {
+    return (0, util_1.noPath)('grok', env);
+}
+/** Versão do runtime, para quem lista os runtimes. */
+function versao() {
+    const r = (0, util_1.exec)('grok', ['--version'], undefined, 30000, ambienteDoDespacho());
+    return r.ok ? r.stdout.trim() : null;
+}
+/** A casa do `grok`: o `GROK_HOME` do ambiente ou `~/.grok`, como o guia de sessões diz. */
+function casaDoGrok(env = process.env) {
+    const valor = (env.GROK_HOME ?? '').trim();
+    return valor !== '' ? valor : path.join(os.homedir(), '.grok');
+}
+/** D3: o perfil de sandbox do `grok` para a postura; fora da tabela, recusa tipada. */
+function perfilDeSandbox(sandbox, colaboracao) {
+    if (colaboracao === 'plan')
+        return 'read-only';
+    if (sandbox === undefined)
+        return exports.PERFIL_DE_SANDBOX_PADRAO;
+    if (!Object.hasOwn(exports.PERFIL_DE_SANDBOX_DO_GROK, sandbox)) {
+        throw new Error(`runtime.unavailable: sandbox ${sandbox} sem perfil do grok`);
+    }
+    return exports.PERFIL_DE_SANDBOX_DO_GROK[sandbox];
+}
+/** O contexto do MCP do despacho, revalidado aqui como nos outros adaptadores; sem ele, `null`. */
+function contextoDoDespacho(pedido) {
+    if (!pedido.contextoRuntime)
+        return null;
+    if (pedido.vinculo && pedido.contextoRuntime.threadId !== pedido.vinculo.thread)
+        throw new Error('runtime.context.scope: thread do contexto difere do despacho');
+    return (0, runtime_context_1.validarContextoDoGrok)(pedido.contextoRuntime, pedido.cwd);
+}
+/** RM-067 (F4b, G2; F4c, D4): as ferramentas que o despacho libera, a mesma lista para o `--allow` e para o servidor do `ork`. */
+function ferramentasDoDespacho(pedido, contexto) {
+    return contexto ? ferramentasDoGrok(contexto.permissoesFilho, pedido.colaboracao === 'plan', contexto.grafoMcp) : [];
+}
+function comandoDoDespacho(pedido, ferramentas) {
+    const args = ['-p', pedido.prompt, '--output-format', 'streaming-json'];
+    if (pedido.sessionId)
+        args.push('-s', pedido.sessionId);
+    args.push('--cwd', pedido.cwd, '--trust');
+    if (pedido.model)
+        args.push('-m', pedido.model);
+    if (pedido.effort?.trim())
+        args.push('--effort', esforcoDoGrok(pedido.effort));
+    args.push('--sandbox', perfilDeSandbox(pedido.sandbox, pedido.colaboracao), '--no-auto-update');
+    // RM-067 (F4b, G2): com o MCP do ork, uma regra por ferramenta liberada, no fim, para o despacho sem contexto ficar igual
+    // e a retomada (que guarda o que vem depois do `-s`) levar as mesmas regras.
+    for (const ferramenta of ferramentas)
+        args.push('--allow', `MCPTool(orkastery__${ferramenta})`);
+    return ['grok', ...args];
+}
+/**
+ * D2: a linha de comando exata do despacho (usada também pelo `--dry-run`). O prompt fica no argumento 2, que o ledger
+ * mascara. Nunca `--yolo`, `--always-approve` nem `--permission-mode`.
+ *
+ * RM-067 (F4, E8): `--trust` confia a pasta do `--cwd`, a worktree da thread, que é o checkout do próprio projeto. O guia
+ * de regras de projeto do `grok` diz que o `AGENTS.md` só carrega na partida com a pasta confiada (`--trust` ou a
+ * concessão interativa, que o headless não tem), e o de permissões diz que a partida headless com instruções do projeto
+ * exige `--trust`. A confiança também liga, nessa pasta, as regras de permissão do projeto e os hooks de projeto que o
+ * `grok` lê; não aprova ferramenta nenhuma.
+ *
+ * RM-067 (F4b, G2): num projeto preparado, o comando leva no fim um `--allow MCPTool(orkastery__<ferramenta>)` por
+ * ferramenta do MCP do `ork` que o caso libera (`ferramentasDoGrok`), e nenhuma outra regra.
+ */
+function montarComando(pedido) {
+    return comandoDoDespacho(pedido, ferramentasDoDespacho(pedido, contextoDoDespacho(pedido)));
+}
+/** RM-067 (F4b, G3): a primeira linha da config que o `ork` grava na worktree; sem ela, o arquivo não é do `ork`. */
+exports.MARCA_DA_CONFIG_DO_FILHO = '# Gerado pelo ork para a sessao filha do grok; o ork reescreve este arquivo a cada despacho.';
+/**
+ * RM-067 (F4b, GO-FIX A2): o `.gitignore` da pasta `.grok` só esconde o que o `ork` grava nela, pelo nome. Regra ou arquivo
+ * novo que a sessão deixe em `.grok/` (o `grok` lê `.grok/rules/` na partida) segue visível ao git e à prova do GO.
+ */
+exports.IGNORADOS_DA_CONFIG_DO_FILHO = '/config.toml\n/.gitignore\n/.ork-*.tmp\n';
+const LIMITE_DA_CONFIG_BYTES = 65536;
+/** D1 da F4c: a única URL que a config da worktree aceita, a do servidor do `ork` no loopback. */
+const URL_DO_SERVIDOR_DO_ORK = /^http:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}\/mcp$/;
+/** D2 da F4c: o nome da variável do token, sem nada que o `grok` expandisse. */
+const NOME_DE_VARIAVEL = /^[A-Z_][A-Z0-9_]{0,63}$/;
+/**
+ * RM-067 (F4b, G3 e G7; F4c, D7): o `.grok/config.toml` da worktree, com o servidor do `ork` vinculado à thread e ao
+ * despacho. Desde a F4c, a entrada é a forma `url` do guia oficial (G16): a URL do servidor do `ork` no loopback e o
+ * `bearer_token_env_var` (G5), o nome da variável com o token, que o despacho põe só no ambiente do `grok`; nada de
+ * `command`, `args` ou `env`, porque o servidor não é mais filho do `grok`, e nada de token em arquivo, que a sessão de outra
+ * thread leria (GO-FIX 1, achado 1). O `grok` expande `${VAR}` na `url` (G16): valor com `$` recusa, porque o servidor
+ * alcançado seria outro. O texto volta pelo parser de TOML e o documento inteiro tem de ser exatamente a entrada pedida
+ * (GO-FIX S2).
+ */
+function configDoFilho(conexao, threadId) {
+    if (conexao.url.includes('$'))
+        throw new Error('runtime.context.conflict: url do servidor do ork tem $, que o grok expandiria; use uma url sem $');
+    if (!URL_DO_SERVIDOR_DO_ORK.test(conexao.url))
+        throw new Error('runtime.context.conflict: a url do servidor do ork nao e a do loopback local (http://127.0.0.1:<porta>/mcp)');
+    if (!NOME_DE_VARIAVEL.test(conexao.bearerTokenEnvVar))
+        throw new Error('runtime.context.conflict: o bearer_token_env_var do servidor do ork nao e um nome de variavel');
+    const texto = [exports.MARCA_DA_CONFIG_DO_FILHO, `# thread ${threadId}`, '[mcp_servers.orkastery]',
+        `url = ${JSON.stringify(conexao.url)}`, `bearer_token_env_var = ${JSON.stringify(conexao.bearerTokenEnvVar)}`].join('\n') + '\n';
+    let lido;
+    try {
+        lido = JSON.stringify((0, smol_toml_1.parse)(texto));
+    }
+    catch {
+        throw new Error('runtime.context.conflict: a config do servidor do ork nao sai como TOML valido');
+    }
+    const esperado = JSON.stringify({ mcp_servers: { orkastery: { url: conexao.url, bearer_token_env_var: conexao.bearerTokenEnvVar } } });
+    if (lido !== esperado)
+        throw new Error('runtime.context.conflict: a config do servidor do ork nao volta igual pelo TOML');
+    return texto;
+}
+/** O texto de um arquivo comum e pequeno, sem seguir link; ausente vira `null`, e o resto recusa. */
+function textoDaWorktree(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 new Error(`runtime.context.conflict: .grok/${path.basename(arquivo)} da worktree e link ou ilegivel; o ork nao escreve por cima`);
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > LIMITE_DA_CONFIG_BYTES)
+            throw new Error(`runtime.context.conflict: .grok/${path.basename(arquivo)} da worktree nao e arquivo comum pequeno`);
+        return fs.readFileSync(fd, 'utf8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Grava um arquivo pequeno por temporário e `rename`, na mesma pasta. */
+function gravarNaWorktree(arquivo, texto) {
+    const temp = path.join(path.dirname(arquivo), `.ork-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    try {
+        fs.writeFileSync(temp, texto, { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temp, arquivo);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}
+/**
+ * RM-067 (F4b, G3 e D3): grava a config da sessão filha na worktree, fora do git e sem apagar arquivo de ninguém. Recusa
+ * antes de escrever: `.grok` que é link ou não é pasta, `config.toml` ou `.gitignore` versionados, link no lugar de
+ * arquivo e config sem a marca do `ork`. O `.gitignore` com os nomes dos arquivos do `ork` só nasce quando falta (nunca
+ * reescreve o de outro), e o `git status` dos dois arquivos tem de sair vazio depois; se não sair, desfaz o que gravou e
+ * recusa.
+ */
+function gravarConfigDaWorktree(cwd, texto) {
+    const pasta = path.join(cwd, '.grok'), arquivo = path.join(pasta, 'config.toml'), ignorar = path.join(pasta, '.gitignore');
+    const st = fs.lstatSync(pasta, { throwIfNoEntry: false });
+    if (st && (st.isSymbolicLink() || !st.isDirectory()))
+        throw new Error('runtime.context.worktree: .grok da worktree e link ou nao e pasta; o ork nao grava a config da sessao por ele');
+    const git = (args) => {
+        const r = (0, util_1.exec)('git', args, cwd, 30000);
+        if (!r.ok)
+            throw new Error(`runtime.context.conflict: git ${args[0]} da worktree falhou`);
+        return r.stdout.trim();
+    };
+    const versionados = git(['ls-files', '--', '.grok/config.toml', '.grok/.gitignore']);
+    if (versionados) {
+        throw new Error(`runtime.context.conflict: ${versionados.split('\n').join(', ')} versionado na worktree; ` +
+            'o ork grava o servidor da sessao num arquivo fora do git');
+    }
+    const anterior = textoDaWorktree(arquivo);
+    if (anterior !== null && !anterior.startsWith(`${exports.MARCA_DA_CONFIG_DO_FILHO}\n`))
+        throw new Error('runtime.context.conflict: .grok/config.toml da worktree nao e do ork; mova o arquivo para o ork gravar o servidor da sessao');
+    const ignorarAntes = textoDaWorktree(ignorar);
+    if (!st)
+        fs.mkdirSync(pasta, { mode: 0o700 });
+    try {
+        if (ignorarAntes === null)
+            gravarNaWorktree(ignorar, exports.IGNORADOS_DA_CONFIG_DO_FILHO);
+        gravarNaWorktree(arquivo, texto);
+        if (git(['status', '--porcelain', '--untracked-files=all', '--', '.grok/config.toml', '.grok/.gitignore']))
+            throw new Error('runtime.context.conflict: a config da sessao ficaria visivel ao git na worktree; confira o .gitignore de .grok');
+    }
+    catch (e) {
+        // Desfaz só o que este despacho gravou: a config anterior do ork volta, e o que nasceu agora sai.
+        if (anterior !== null)
+            gravarNaWorktree(arquivo, anterior);
+        else
+            fs.rmSync(arquivo, { force: true });
+        if (ignorarAntes === null)
+            fs.rmSync(ignorar, { force: true });
+        if (!st) {
+            try {
+                fs.rmdirSync(pasta);
+            }
+            catch { /* sobrou arquivo que não é deste despacho */ }
+        }
+        throw e;
+    }
+}
+/**
+ * D11: a retomada de uma sessão interrompida, derivada do comando do despacho (o do ledger tem o prompt mascarado): o
+ * argumento 2 vira o texto da retomada e `-s <id>` vira `-r <id>`; o resto (cwd, modelo, esforço, sandbox) fica. O guia
+ * diz que a sessão interrompida guarda o estado até a última ferramenta concluída. Comando que não é do `grok`, ou sem
+ * `-s <id>`, devolve `null`.
+ */
+function montarComandoDeRetomada(comando, sessionId, texto = 'continue') {
+    if (comando[0] !== 'grok' || comando[1] !== '-p' || comando.length < 3)
+        return null;
+    const i = comando.indexOf('-s', 3);
+    if (i < 0 || comando[i + 1] !== sessionId)
+        return null;
+    return [...comando.slice(0, 2), texto, ...comando.slice(3, i), '-r', sessionId, ...comando.slice(i + 2)];
+}
+/**
+ * D5: a pasta `<casa>/sessions/<grupo>/<id>/` com `updates.jsonl` arquivo comum. A codificação do cwd no nome do grupo
+ * não é documentada, então a busca olha o id um nível abaixo de `sessions/`, sem seguir link. Exatamente um grupo com a
+ * sessão, ou `null`: o id que aparece em dois grupos não prova qual é a sessão despachada.
+ */
+function acharSessaoGrok(sessionId, casa = casaDoGrok()) {
+    if (!ID_DE_SESSAO.test(sessionId))
+        return null;
+    const raiz = path.join(casa, 'sessions');
+    let grupos;
+    try {
+        if (!fs.lstatSync(raiz).isDirectory())
+            return null;
+        grupos = fs.readdirSync(raiz, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const achadas = [];
+    for (const grupo of grupos) {
+        if (!grupo.isDirectory())
+            continue;
+        const dir = path.join(raiz, grupo.name, sessionId);
+        try {
+            if (!fs.lstatSync(dir).isDirectory())
+                continue;
+            const updates = path.join(dir, 'updates.jsonl');
+            const st = fs.lstatSync(updates);
+            if (st.isFile())
+                achadas.push({ dir, updates, tamanho: st.size, mtimeMs: st.mtimeMs });
+        }
+        catch { /* o grupo não tem a sessão */ }
+    }
+    return achadas.length === 1 ? achadas[0] : null;
+}
+/**
+ * RM-067 (F4): as sessões de uma casa do `grok` para o inventário (`ork sessions`), pela fonte que o próprio runtime grava:
+ * cada pasta `<casa>/sessions/<grupo>/<id>/` com o `updates.jsonl`. Como na prova de existência (D5), o `ork` lista nomes
+ * e lê o mtime e o tamanho do arquivo, nunca o conteúdo; a atividade é o mtime. O grupo é o cwd codificado, cuja
+ * codificação o guia não documenta, então o cwd da sessão fica sem valor. Link e entrada estranha deixam a consulta
+ * parcial (`ok: false`), nunca "zero sessões".
+ */
+function consultarSessoesGrok(casa = casaDoGrok()) {
+    const raiz = path.join(casa, 'sessions');
+    let grupos;
+    try {
+        const st = fs.lstatSync(raiz);
+        if (!st.isDirectory())
+            return { ok: false, ausente: false, sessoes: [], detalhe: 'sessions nao e pasta comum' };
+        grupos = fs.readdirSync(raiz, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ok: true, ausente: true, sessoes: [], detalhe: 'sem a pasta sessions' };
+        return { ok: false, ausente: false, sessoes: [], detalhe: 'pasta sessions inacessivel' };
+    }
+    const sessoes = [];
+    let parcial = false;
+    for (const grupo of grupos) {
+        if (!grupo.isDirectory()) {
+            parcial ||= grupo.isSymbolicLink();
+            continue;
+        }
+        let ids;
+        try {
+            ids = fs.readdirSync(path.join(raiz, grupo.name), { withFileTypes: true });
+        }
+        catch {
+            parcial = true;
+            continue;
+        }
+        for (const id of ids) {
+            if (!ID_DE_SESSAO.test(id.name))
+                continue;
+            if (!id.isDirectory()) {
+                parcial ||= id.isSymbolicLink();
+                continue;
+            }
+            try {
+                const st = fs.lstatSync(path.join(raiz, grupo.name, id.name, 'updates.jsonl'));
+                if (st.isFile())
+                    sessoes.push({ sessionId: id.name, kind: 'grok', atividadeEm: st.mtimeMs });
+                else
+                    parcial = true;
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    parcial = true;
+            }
+        }
+    }
+    return { ok: !parcial, ausente: false, sessoes,
+        detalhe: parcial ? 'inventario parcial; a pasta sessions tem link ou entrada ilegivel' : '' };
+}
+/** JSON pequeno de metadado do supervisor, sem seguir link; ausente ou ilegível vira `null`. */
+function lerMetadado(arquivo) {
+    let fd;
+    try {
+        fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > LIMITE_METADADO_BYTES)
+            return null;
+        const bytes = Buffer.alloc(st.size);
+        fs.readSync(fd, bytes, 0, st.size, 0);
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * A cauda do stderr do filho, redigida e sem corte; ausente vira vazio. GO-FIX 1 (A4): a janela começa no meio de uma
+ * linha, e esse pedaço sai inteiro antes da redação, para nenhum segredo cortado perder o prefixo que a redação reconhece.
+ */
+function caudaDoStderr(arquivo) {
+    let fd;
+    try {
+        fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return '';
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return '';
+        const n = Math.min(st.size, LIMITE_STDERR_BYTES), bytes = Buffer.alloc(n);
+        fs.readSync(fd, bytes, 0, n, st.size - n);
+        let texto = bytes.toString('utf8');
+        if (st.size > n) {
+            const quebra = texto.indexOf('\n');
+            texto = quebra < 0 ? '' : texto.slice(quebra + 1);
+        }
+        return (0, grok_events_1.redigirTextoGrok)(texto);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * GO-FIX 2 (N6): o fim do texto em até `limite` unidades UTF-16, a mesma unidade do `slice` de quem grava no ledger, que
+ * assim não tira nada; o corte não começa na metade baixa de um par substituto.
+ */
+function fimDoTexto(texto, limite) {
+    if (texto.length <= limite)
+        return texto;
+    const fim = texto.slice(-limite);
+    const primeira = fim.charCodeAt(0);
+    return primeira >= 0xdc00 && primeira <= 0xdfff ? fim.slice(1) : fim;
+}
+const pausa = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * D6: despacha a fase e confere no disco do runtime que a sessão existe. Nunca self-report: o id é do `ork`, a pasta é
+ * do `grok`, e a falha antes da sessão vem do recibo do supervisor e do objeto `error` do stream.
+ */
+function despachar(pedido) {
+    const sessionId = pedido.sessionId ?? (0, node_crypto_1.randomUUID)();
+    const falha = (erro, extra = {}) => ({ ok: false, comando: [], sessionId: null, verificada: false, stdout: '', stderr: '', erro, ...extra });
+    let comando;
+    let ambiente;
+    let contexto;
+    try {
+        contexto = contextoDoDespacho(pedido);
+    }
+    catch (e) {
+        return falha(`runtime.unavailable: ${e.message}`);
+    }
+    const ferramentas = ferramentasDoDespacho(pedido, contexto);
+    try {
+        comando = comandoDoDespacho({ ...pedido, sessionId }, ferramentas);
+        ambiente = ambienteDoFilho(pedido);
+    }
+    catch (e) {
+        return falha(e.message);
+    }
+    if (pedido.dryRun)
+        return { ok: true, comando, sessionId: null, verificada: false, stdout: '', stderr: '' };
+    if (!disponivel(ambiente))
+        return falha('runtime.unavailable: binario grok nao encontrado no PATH', { comando });
+    // O log nunca vai para a worktree: a prova do GO exige a worktree limpa.
+    if (!pedido.logDir || !path.isAbsolute(pedido.logDir)) {
+        return falha('runtime.unavailable: despacho grok sem o diretorio de logs da thread', { comando });
+    }
+    const logPath = path.join(pedido.logDir, `${sessionId}.grok.jsonl`);
+    // RM-067 (F4c, D6 e D7): com o MCP, o servidor do ork sobe antes de tudo, fora do sandbox do grok, com as ferramentas do
+    // --allow deste despacho; a config da worktree aponta para ele e vai antes do supervisor, porque o grok a lê na partida,
+    // com a pasta confiada (F4b, G3). O token vai só ao ambiente do grok (D2). Toda falha depois de o servidor subir o encerra.
+    let servidor = null;
+    if (contexto) {
+        const especificacao = contexto.servidor;
+        if (!especificacao.dispatchId)
+            return falha('runtime.unavailable: runtime.context.identity: o grok com o MCP do ork exige a identidade do despacho', { comando });
+        try {
+            servidor = (0, grok_mcp_1.iniciarServidorDoGrok)({ projeto: especificacao.projeto, threadId: especificacao.threadId,
+                dispatchId: especificacao.dispatchId, permissoesFilho: especificacao.permissoesFilho, transporteShip: especificacao.transporteShip,
+                ferramentas, logPath, conferirProcesso: perfilDeSandbox(pedido.sandbox, pedido.colaboracao) !== 'off' }, pedido.cwd, { ...ambiente, ...(especificacao.env ?? {}) });
+        }
+        catch (e) {
+            // GO-FIX 1 (achado 7): o erro de sistema (mkdir, open, spawn) também volta tipado.
+            const motivo = e.message;
+            return falha(motivo.startsWith('runtime.unavailable:') ? motivo : `runtime.unavailable: ${motivo}`, { comando });
+        }
+        try {
+            gravarConfigDaWorktree(pedido.cwd, configDoFilho({ url: servidor.url, bearerTokenEnvVar: grok_mcp_1.ENV_DO_TOKEN_DO_SERVIDOR_GROK }, contexto.threadId));
+        }
+        catch (e) {
+            servidor.encerrar();
+            return falha(`runtime.unavailable: ${e.message}`, { comando });
+        }
+    }
+    const ambienteDoGrok = servidor ? { ...ambiente, [grok_mcp_1.ENV_DO_TOKEN_DO_SERVIDOR_GROK]: servidor.token } : ambiente;
+    let sensores;
+    try {
+        sensores = (0, codex_runner_1.iniciarSupervisor)(comando, pedido.cwd, logPath, ambienteDoGrok);
+    }
+    catch (e) {
+        servidor?.encerrar();
+        return falha(`runtime.unavailable: o supervisor do grok nao iniciou (${e.code ?? 'erro'})`, { comando });
+    }
+    const base = { comando, logPath, ...sensores };
+    const casa = casaDoGrok(ambiente);
+    const prazo = Date.now() + (pedido.esperaMs ?? exports.ESPERA_PADRAO_MS);
+    for (;;) {
+        if (acharSessaoGrok(sessionId, casa))
+            return { ok: true, sessionId, verificada: true, stdout: '', stderr: '', ...base };
+        const recibo = lerMetadado(sensores.reciboPath);
+        if (recibo) {
+            servidor?.encerrar();
+            return falhaAntesDaSessao(recibo, sessionId, base);
+        }
+        if (Date.now() >= prazo)
+            break;
+        Atomics.wait(pausa, 0, 0, 100);
+    }
+    const recibo = lerMetadado(sensores.reciboPath);
+    if (recibo) {
+        servidor?.encerrar();
+        return falhaAntesDaSessao(recibo, sessionId, base);
+    }
+    // Filho vivo sem a pasta no prazo: a sessão segue, sem prova de existência ainda; o watcher a acompanha.
+    const processo = lerMetadado(sensores.processoPath);
+    if (processo?.filho && (0, codex_runner_1.estadoProcesso)(processo.filho) === 'vivo') {
+        return { ok: true, sessionId, verificada: false, stdout: '', stderr: '', ...base };
+    }
+    servidor?.encerrar();
+    return falha('runtime.unavailable: o supervisor do grok nao registrou o processo vivo no prazo', base);
+}
+/**
+ * O processo terminou antes de a sessão existir. A falha da conta vem do objeto `error` do stream e, sem ele, do stderr
+ * do próprio runtime; o rate limit de janela curta volta tipado para a fila; o resto é `runtime.unavailable` com o código.
+ */
+function falhaAntesDaSessao(recibo, sessionId, base) {
+    const estado = (0, grok_events_1.lerStreamGrok)(base.logPath, sessionId);
+    const cauda = caudaDoStderr(`${base.logPath}.stderr`);
+    const mensagem = estado?.erro?.mensagem ?? '';
+    const texto = [mensagem, cauda].filter(Boolean).join('\n');
+    const falhaDeConta = (0, grok_events_1.falhaDoErroGrok)(estado?.erro ?? null) ?? (cauda ? (0, grok_events_1.falhaDeContaDoTextoGrok)(cauda) : null);
+    const rateLimit = falhaDeConta ? null : (0, claude_bg_1.parseRateLimit)(texto);
+    // Ao ledger vai o fim da cauda, onde o erro mora; quem grava corta pelo começo.
+    const stderr = fimDoTexto(cauda, LIMITE_STDERR_NO_RESULTADO);
+    // O erro de spawn (o binário sumiu entre a conferência e o supervisor) vem antes do código, que o Node dá negativo.
+    const codigo = recibo.erro ?? recibo.exitCode ?? recibo.signal ?? 'sem codigo';
+    const erro = falhaDeConta ? `${falhaDeConta.motivo}: ${falhaDeConta.trecho}`
+        : rateLimit ? `limite de uso do runtime atingido: ${rateLimit.trecho}`
+            : `runtime.unavailable: o grok saiu ${codigo} antes de criar a sessao${mensagem ? `: ${mensagem}` : ''}`;
+    return { ok: false, sessionId: null, verificada: false, stdout: '', stderr, erro, falhaDeConta, rateLimit, ...base };
+}