@orkastery/cli 0.5.3 → 0.6.0

package/dist/postura-local.js

@@ -0,0 +1,235 @@
+"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.POSTURAS_QUE_AFROUXAM = exports.ARQUIVO_POSTURA_LOCAL = exports.CONTRATO_POSTURA_LOCAL = void 0;
+exports.pastaPrivadaDaPostura = pastaPrivadaDaPostura;
+exports.caminhoDaPosturaLocal = caminhoDaPosturaLocal;
+exports.posturaAfrouxada = posturaAfrouxada;
+exports.comandoDeConfirmacao = comandoDeConfirmacao;
+exports.lerArquivoPrivado = lerArquivoPrivado;
+exports.raizRealDoEstado = raizRealDoEstado;
+exports.lerPosturaLocal = lerPosturaLocal;
+exports.recusaDePostura = recusaDePostura;
+exports.gravarArquivoPrivado = gravarArquivoPrivado;
+exports.revogarArquivoPrivado = revogarArquivoPrivado;
+exports.confirmarPosturaLocal = confirmarPosturaLocal;
+exports.revogarPosturaLocal = revogarPosturaLocal;
+/**
+ * RM-047 (fronteira de confiança, P1): a postura de sandbox que afrouxa vale só com a confirmação
+ * desta máquina.
+ *
+ * O `runtime.sandbox` mora no `orkastery.yaml`, que vem com o repositório. Um valor que afrouxa o
+ * sandbox do agente (hoje, `danger-full-access`, que no Codex vai junto com aprovação `never`) não
+ * pode valer só porque o manifesto clonado o declara: o despacho recusa com
+ * `runtime.sandbox-nao-confirmado` até a máquina confirmar a mesma postura no setup local, com
+ * `ork setup sandbox confirmar <postura>`.
+ *
+ * A confirmação fica em `.orkastery/private/postura-local.json`, na raiz de estado: pasta 0700 e
+ * arquivo 0600 do próprio usuário, nunca link e nunca rastreado pelo git. Ela guarda a postura e o
+ * caminho real da raiz, então não vale para outra postura nem para outro checkout.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const codex_1 = require("./adapters/codex");
+const estado_thread_1 = require("./estado-thread");
+const procedencia_1 = require("./procedencia");
+const locale_1 = require("./locale");
+const util_1 = require("./util");
+exports.CONTRATO_POSTURA_LOCAL = 'ork.postura-local/v1';
+exports.ARQUIVO_POSTURA_LOCAL = 'postura-local.json';
+const LIMITE_BYTES = 4096;
+/**
+ * As posturas de sandbox que afrouxam o padrão (`workspace-write`). `read-only` aperta e vale sem
+ * confirmação. Uma postura nova do runtime entra aqui antes de poder ser declarada.
+ */
+exports.POSTURAS_QUE_AFROUXAM = ['danger-full-access'];
+function uid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+function pastaPrivadaDaPostura(raiz) {
+    return path.join((0, estado_thread_1.raizDoEstado)(raiz), '.orkastery', 'private');
+}
+function caminhoDaPosturaLocal(raiz) {
+    return path.join(pastaPrivadaDaPostura(raiz), exports.ARQUIVO_POSTURA_LOCAL);
+}
+/** O manifesto pede uma postura que afrouxa o sandbox? */
+function posturaAfrouxada(manifesto) {
+    const sandbox = manifesto.runtime.sandbox ?? codex_1.SANDBOX_PADRAO;
+    return exports.POSTURAS_QUE_AFROUXAM.includes(sandbox) ? sandbox : null;
+}
+/** Comando que confirma a postura nesta máquina; vai em toda recusa. */
+function comandoDeConfirmacao(postura) {
+    return `ork setup sandbox confirmar ${postura}`;
+}
+/**
+ * RM-047 (P3): lê um arquivo de `.orkastery/private/` com as regras da confirmação local: pasta 0700 e
+ * arquivo 0600 do próprio usuário, nunca link, nunca rastreado pelo git, até 4 KiB e JSON válido.
+ * Devolve o objeto cru, ou `null` com o motivo.
+ */
+function lerArquivoPrivado(raiz, nome) {
+    const pasta = pastaPrivadaDaPostura(raiz), arquivo = path.join(pasta, nome);
+    const stPasta = fs.lstatSync(pasta, { throwIfNoEntry: false });
+    if (!stPasta)
+        return { bruto: null, motivo: 'sem confirmação local' };
+    const dono = uid();
+    if (!stPasta.isDirectory() || stPasta.isSymbolicLink() || (dono !== null && stPasta.uid !== dono) ||
+        (stPasta.mode & 0o077) !== 0)
+        return { bruto: null, motivo: '.orkastery/private precisa ser pasta 0700 do próprio usuário' };
+    const st = fs.lstatSync(arquivo, { throwIfNoEntry: false });
+    if (!st)
+        return { bruto: null, motivo: 'sem confirmação local' };
+    if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || (dono !== null && st.uid !== dono) ||
+        (st.mode & 0o077) !== 0 || st.size > LIMITE_BYTES) {
+        return { bruto: null, motivo: `${nome} precisa ser arquivo 0600 do próprio usuário` };
+    }
+    if ((0, procedencia_1.rastreadoPeloGit)(raiz, arquivo)) {
+        return { bruto: null, motivo: `${nome} está versionado no git e não vale como confirmação local` };
+    }
+    let bruto;
+    try {
+        bruto = JSON.parse(fs.readFileSync(arquivo, 'utf8'));
+    }
+    catch {
+        return { bruto: null, motivo: `${nome} com JSON inválido` };
+    }
+    if (!bruto || typeof bruto !== 'object' || Array.isArray(bruto))
+        return { bruto: null, motivo: `${nome} com JSON inválido` };
+    return { bruto: bruto, motivo: null };
+}
+/** Caminho real da raiz de estado: a confirmação local vale só para o checkout que a gravou. */
+function raizRealDoEstado(raiz) {
+    try {
+        return fs.realpathSync((0, estado_thread_1.raizDoEstado)(raiz));
+    }
+    catch {
+        return path.resolve(raiz);
+    }
+}
+/**
+ * Lê a confirmação local. `null` quando ela não existe ou não vale (pasta ou arquivo com dono ou modo
+ * errado, link, rastreado pelo git, JSON inválido, outra raiz); o motivo vai em `motivo`.
+ */
+function lerPosturaLocal(raiz) {
+    const { bruto: o, motivo } = lerArquivoPrivado(raiz, exports.ARQUIVO_POSTURA_LOCAL);
+    if (!o)
+        return { postura: null, motivo };
+    if (o.contrato !== exports.CONTRATO_POSTURA_LOCAL || typeof o.sandbox !== 'string' ||
+        typeof o.raiz !== 'string' || typeof o.confirmadoEm !== 'string' || typeof o.por !== 'string') {
+        return { postura: null, motivo: `${exports.ARQUIVO_POSTURA_LOCAL} fora do contrato ${exports.CONTRATO_POSTURA_LOCAL}` };
+    }
+    if (o.raiz !== raizRealDoEstado(raiz))
+        return { postura: null, motivo: 'a confirmação local é de outro checkout' };
+    return { postura: o, motivo: null };
+}
+/**
+ * A recusa do despacho: `null` quando a postura do manifesto vale nesta máquina (não afrouxa, ou
+ * foi confirmada localmente com o mesmo valor); senão o erro tipado com o comando que confirma.
+ * Só o Codex recebe a postura de sandbox do manifesto.
+ */
+function recusaDePostura(raiz, manifesto, runtime) {
+    if (runtime !== 'codex')
+        return null;
+    const postura = posturaAfrouxada(manifesto);
+    if (!postura)
+        return null;
+    const { postura: local, motivo } = lerPosturaLocal(raiz);
+    if (local && local.sandbox === postura)
+        return null;
+    const porque = local ? `a máquina confirmou ${local.sandbox}, não ${postura}` : motivo ?? 'sem confirmação local';
+    return `runtime.sandbox-nao-confirmado: o orkastery.yaml pede runtime.sandbox: ${postura}, que desliga o sandbox ` +
+        `do agente, e esta máquina não confirmou essa postura (${porque}). Nada foi despachado. O manifesto vem com o ` +
+        `repositório; quem decide afrouxar o sandbox é a máquina. Para aceitar nesta máquina: ${comandoDeConfirmacao(postura)}` +
+        ` (ou volte o manifesto para ${codex_1.SANDBOX_PADRAO}).`;
+}
+/**
+ * RM-047 (P3): grava um objeto em `.orkastery/private/<nome>` com as regras da confirmação local
+ * (pasta 0700, arquivo 0600 por temporário exclusivo e `rename`, nunca seguindo link).
+ */
+function gravarArquivoPrivado(raiz, nome, objeto) {
+    const pasta = pastaPrivadaDaPostura(raiz), arquivo = path.join(pasta, nome);
+    const estado = path.dirname(pasta);
+    const stEstado = fs.lstatSync(estado, { throwIfNoEntry: false });
+    if (stEstado && (!stEstado.isDirectory() || stEstado.isSymbolicLink()))
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.posturaEstadoLink);
+    fs.mkdirSync(estado, { recursive: true });
+    try {
+        fs.mkdirSync(pasta, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+    }
+    const stPasta = fs.lstatSync(pasta);
+    if (!stPasta.isDirectory() || stPasta.isSymbolicLink())
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.posturaPrivadaLink);
+    fs.chmodSync(pasta, 0o700);
+    if ((0, procedencia_1.rastreadoPeloGit)(raiz, arquivo)) {
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.posturaRastreada(nome));
+    }
+    const temp = path.join(pasta, `.${nome}.${(0, node_crypto_1.randomUUID)()}.tmp`);
+    const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, JSON.stringify(objeto, null, 2) + '\n');
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, arquivo);
+}
+/** Apaga um arquivo de `.orkastery/private/`; devolve se havia um. */
+function revogarArquivoPrivado(raiz, nome) {
+    const arquivo = path.join(pastaPrivadaDaPostura(raiz), nome);
+    const st = fs.lstatSync(arquivo, { throwIfNoEntry: false });
+    if (!st)
+        return false;
+    fs.rmSync(arquivo, { force: true });
+    return true;
+}
+/** Grava a confirmação local de uma postura de sandbox para este checkout. */
+function confirmarPosturaLocal(raiz, sandbox, por) {
+    if (!codex_1.SANDBOXES_DO_CODEX.includes(sandbox)) {
+        throw new Error(`runtime.sandbox-invalido: "${sandbox}" (aceitos: ${codex_1.SANDBOXES_DO_CODEX.join(', ')})`);
+    }
+    const postura = { contrato: exports.CONTRATO_POSTURA_LOCAL, sandbox, raiz: raizRealDoEstado(raiz), confirmadoEm: (0, util_1.agora)(), por };
+    gravarArquivoPrivado(raiz, exports.ARQUIVO_POSTURA_LOCAL, postura);
+    return postura;
+}
+/** Apaga a confirmação local; devolve se havia uma. */
+function revogarPosturaLocal(raiz) {
+    return revogarArquivoPrivado(raiz, exports.ARQUIVO_POSTURA_LOCAL);
+}

package/dist/preflight.js

@@ -51,6 +51,7 @@ const modos_1 = require("./modos");
 const setup_1 = require("./setup");
 const phase_1 = require("./phase");
 const runtimes_1 = require("./runtimes");
+const locale_1 = require("./locale");
 const codex_2 = require("./adapters/codex");
 const runtime_ambiente_1 = require("./runtime-ambiente");
 const slug_1 = require("./slug");
@@ -92,10 +93,10 @@ function umaskDoProcesso() {
 function sondasDeAmbiente(raiz, umask = umaskDoProcesso()) {
     const checks = [];
     const octal = (v) => '0' + v.toString(8).padStart(3, '0');
-    checks.push(umask === null ? { nome: 'umask', nivel: 'warn', detalhe: 'umask do processo nao medido nesta plataforma' }
-        : (umask & 0o022) === 0o022 ? { nome: 'umask', nivel: 'ok', detalhe: `umask ${octal(umask)} nega escrita de grupo e outros` }
-            : { nome: 'umask', nivel: 'warn', detalhe: `umask ${octal(umask)} permite escrita de grupo ou outros: o que o runtime criar sera recusado pelo sensor (bits 0o022)`,
-                correcao: 'umask 022 (ou 077) no shell que roda o ork e os runtimes' });
+    const m = (0, locale_1.msg)().doctor;
+    checks.push(umask === null ? { nome: 'umask', nivel: 'warn', detalhe: m.umaskNaoMedido }
+        : (umask & 0o022) === 0o022 ? { nome: 'umask', nivel: 'ok', detalhe: m.umaskOk(octal(umask)) }
+            : { nome: 'umask', nivel: 'warn', detalhe: m.umaskAberto(octal(umask)), correcao: m.umaskCorrecao });
     const estado = path.join((0, estado_thread_1.raizDoEstado)(raiz), '.orkastery');
     let st = null;
     try {
@@ -103,19 +104,19 @@ function sondasDeAmbiente(raiz, umask = umaskDoProcesso()) {
     }
     catch { /* ausencia e do check de estado do projeto */ }
     if (st)
-        checks.push(!st.isDirectory() || st.isSymbolicLink() ? { nome: 'permissoes do estado', nivel: 'fail', detalhe: `${estado} nao e diretorio real` }
-            : st.mode & 0o022 ? { nome: 'permissoes do estado', nivel: 'warn', detalhe: `${estado} com modo ${octal(st.mode & 0o777)}: grupo ou outros podem escrever no estado`, correcao: `chmod go-w ${estado}` }
-                : { nome: 'permissoes do estado', nivel: 'ok', detalhe: `${estado} com modo ${octal(st.mode & 0o777)}` });
+        checks.push(!st.isDirectory() || st.isSymbolicLink() ? { nome: 'permissoes do estado', nivel: 'fail', detalhe: m.estadoNaoDiretorio(estado) }
+            : st.mode & 0o022 ? { nome: 'permissoes do estado', nivel: 'warn', detalhe: m.estadoAberto(estado, octal(st.mode & 0o777)), correcao: `chmod go-w ${estado}` }
+                : { nome: 'permissoes do estado', nivel: 'ok', detalhe: m.estadoComModo(estado, octal(st.mode & 0o777)) });
     const privada = path.join(estado, 'private');
     let sp = null;
     try {
         sp = fs.lstatSync(privada);
     }
     catch { /* criada sob demanda */ }
-    checks.push(!sp ? { nome: 'pasta privada', nivel: 'ok', detalhe: `${privada} ausente: criada sob demanda com 0700` }
+    checks.push(!sp ? { nome: 'pasta privada', nivel: 'ok', detalhe: m.privadaAusente(privada) }
         : !sp.isDirectory() || sp.isSymbolicLink() || sp.uid !== process.getuid?.() || (sp.mode & 0o777) !== 0o700
-            ? { nome: 'pasta privada', nivel: 'fail', detalhe: `${privada} precisa ser diretorio 0700 do proprio usuario (modo ${octal(sp.mode & 0o777)}): recibo HITL e perfis recusam`, correcao: `chmod 700 ${privada}` }
-            : { nome: 'pasta privada', nivel: 'ok', detalhe: `${privada} com modo 0700` });
+            ? { nome: 'pasta privada', nivel: 'fail', detalhe: m.privadaAberta(privada, octal(sp.mode & 0o777)), correcao: `chmod 700 ${privada}` }
+            : { nome: 'pasta privada', nivel: 'ok', detalhe: m.privadaOk(privada) });
     return checks;
 }
 /**

package/dist/procedencia.js

@@ -0,0 +1,220 @@
+"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.rastreadoPeloGit = rastreadoPeloGit;
+exports.exigirCwdLocal = exigirCwdLocal;
+exports.cwdLocalOuNulo = cwdLocalOuNulo;
+exports.diretorioDaThread = diretorioDaThread;
+exports.exigirHostLocal = exigirHostLocal;
+exports.caminhoContidoOuNulo = caminhoContidoOuNulo;
+exports.exigirCaminhoContido = exigirCaminhoContido;
+/**
+ * RM-047 (fronteira de confiança, P2): procedência do estado que escolhe onde o `ork` roda.
+ *
+ * O `.orkastery/` é estado desta máquina, mas nada impede um repositório de versioná-lo, e o clone
+ * traz então `thread.json`, ledger, fila e arquivos de host escritos em outro lugar. Duas regras
+ * separam o estado local do que veio no clone:
+ *
+ * 1. Estado rastreado pelo git não vale como estado local para escolher diretório ou executável.
+ *    `thread.json`, ledger e fila rastreados não escolhem o cwd; `pulse-host.json` e
+ *    `master-host.json` rastreados não escolhem o transporte.
+ * 2. O cwd do agente e do git, quando sai do estado (worktree da thread, cwd do despacho no ledger,
+ *    cwd de um pedido da fila), só vale se for uma worktree que o `git worktree list` do próprio
+ *    repositório registra. A raiz do projeto, escolhida por quem roda o comando, segue valendo.
+ *
+ * As recusas são tipadas: `estado.rastreado`, `estado.worktree-nao-registrada` e
+ * `transporte.rastreado`. Cada mensagem diz o que fazer.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const estado_thread_1 = require("./estado-thread");
+const locale_1 = require("./locale");
+const util_1 = require("./util");
+/** Caminho relativo à árvore principal, com `/` (o formato do `git ls-files`). */
+function relativoAoRepositorio(principal, arquivo) {
+    const rel = path.relative(principal, path.resolve(arquivo));
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return rel.split(path.sep).join('/');
+}
+/**
+ * O arquivo está no índice do git da árvore principal? Sem git (projeto fora de repositório, git
+ * ausente), nada está rastreado. A consulta roda na raiz do projeto, como todo git do `ork`.
+ */
+function rastreadoPeloGit(raiz, arquivo) {
+    let principal;
+    try {
+        principal = (0, estado_thread_1.raizDoEstado)(raiz);
+    }
+    catch {
+        principal = path.resolve(raiz);
+    }
+    const rel = relativoAoRepositorio(principal, arquivo);
+    if (rel === null)
+        return false;
+    const r = (0, util_1.exec)('git', ['ls-files', '-z', '--', rel], principal, 30000);
+    return r.ok && r.stdout.split('\0').some(Boolean);
+}
+/** As worktrees que o git do repositório registra, pelo caminho real. */
+function worktreesRegistradas(principal) {
+    const r = (0, util_1.exec)('git', ['worktree', 'list', '--porcelain'], principal, 30000);
+    if (!r.ok)
+        return [];
+    return r.stdout.split('\n').filter(l => l.startsWith('worktree ')).map(l => {
+        const dir = l.slice('worktree '.length).trim();
+        try {
+            return fs.realpathSync(dir);
+        }
+        catch {
+            return path.resolve(dir);
+        }
+    });
+}
+function real(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+const ARQUIVO_DA_ORIGEM = {
+    thread: id => `.orkastery/threads/${id}/thread.json`,
+    ledger: id => `.orkastery/threads/${id}/ledger.jsonl`,
+    fila: () => '.orkastery/retry/fila.jsonl',
+};
+/**
+ * Confere o diretório que o estado escolheu para rodar git ou agente. Devolve o próprio diretório
+ * quando ele vale; senão lança `estado.rastreado` ou `estado.worktree-nao-registrada`.
+ *
+ * A raiz do projeto (o checkout de quem roda o comando) e a árvore principal valem sem consulta: não
+ * saem do estado.
+ */
+function exigirCwdLocal(raiz, threadId, dir, origem) {
+    let principal;
+    try {
+        principal = (0, estado_thread_1.raizDoEstado)(raiz);
+    }
+    catch {
+        principal = path.resolve(raiz);
+    }
+    const alvo = real(dir);
+    if (alvo === real(raiz) || alvo === real(principal))
+        return dir;
+    const arquivo = path.join(principal, ARQUIVO_DA_ORIGEM[origem](threadId));
+    if (rastreadoPeloGit(principal, arquivo)) {
+        const rel = path.relative(principal, arquivo);
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.rastreado(rel));
+    }
+    if (!path.isAbsolute(dir) || !fs.existsSync(dir) || !worktreesRegistradas(principal).includes(alvo)) {
+        const citado = JSON.stringify(String(dir)).slice(0, 200);
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.worktreeNaoRegistrada(citado, threadId));
+    }
+    return dir;
+}
+/** Como `exigirCwdLocal`, sem lançar: `null` quando o diretório não vale. */
+function cwdLocalOuNulo(raiz, threadId, dir, origem) {
+    try {
+        return exigirCwdLocal(raiz, threadId, dir, origem);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * O diretório de trabalho de uma thread: a worktree registrada dela, ou a raiz do projeto quando a
+ * thread não tem worktree.
+ */
+function diretorioDaThread(raiz, thread) {
+    return thread.worktree ? exigirCwdLocal(raiz, thread.id, thread.worktree, 'thread') : raiz;
+}
+/**
+ * O arquivo de host (`pulse-host.json`, `master-host.json`) escolhe o executável que recebe a
+ * mensagem. Só vale o arquivo local: versionado no git, ele veio com o repositório.
+ */
+function exigirHostLocal(raiz, arquivo) {
+    if (rastreadoPeloGit(raiz, arquivo)) {
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.transporteRastreado(path.basename(arquivo)));
+    }
+    const st = fs.lstatSync(arquivo, { throwIfNoEntry: false });
+    if (st && !st.isFile()) {
+        throw new locale_1.ErroDoCatalogo((m) => m.estado.transporteNaoComum(path.basename(arquivo)));
+    }
+}
+/** `filho` está dentro de `pai` (ou é o próprio `pai`), pelos caminhos reais? */
+function dentroDe(pai, filho) {
+    const rel = path.relative(pai, filho);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * Um ponteiro que o estado guarda (`location` do `handoff.json`, `arquivo` de uma claim, `promptPath`
+ * de uma sessão, arquivo de handoff ou de lição da memória) só é lido se, pelo caminho real (links
+ * resolvidos), cair na raiz do projeto, na árvore principal ou na worktree registrada da thread.
+ * Devolve o caminho real, ou `null` quando ele sai dessas raízes ou não existe.
+ */
+function caminhoContidoOuNulo(raiz, thread, caminho) {
+    let alvo;
+    try {
+        alvo = fs.realpathSync(caminho);
+    }
+    catch {
+        return null;
+    }
+    let principal;
+    try {
+        principal = (0, estado_thread_1.raizDoEstado)(raiz);
+    }
+    catch {
+        principal = path.resolve(raiz);
+    }
+    const raizes = [real(raiz), real(principal)];
+    if (thread?.worktree) {
+        const w = cwdLocalOuNulo(raiz, thread.id, thread.worktree, 'thread');
+        if (w)
+            raizes.push(real(w));
+    }
+    return raizes.some(r => dentroDe(r, alvo)) ? alvo : null;
+}
+/**
+ * Como `caminhoContidoOuNulo`, com a recusa tipada `ponteiro.fora-da-raiz` quando o arquivo existe
+ * mas sai das raízes. Arquivo ausente segue para quem chamou dizer que o ponteiro não resolve.
+ */
+function exigirCaminhoContido(raiz, thread, caminho, origem) {
+    const contido = caminhoContidoOuNulo(raiz, thread, caminho);
+    if (contido)
+        return contido;
+    const citado = JSON.stringify(String(origem)).slice(0, 200);
+    throw new locale_1.ErroDoCatalogo((m) => m.estado.ponteiroForaDaRaiz(citado));
+}