@orkastery/cli 0.2.0 → 0.3.0

package/dist/ocupacao.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * Politica de OCUPACAO DE VAGA por estado real (correcao do escalonador, 09/2026).
+ *
+ * O incidente que este arquivo corrige: o escalonador contava "em andamento" pela
+ * EXISTENCIA da thread aberta, e nao por haver um agente executando de fato. Threads
+ * orfas presas ha dias em gates nao-finalizaveis seguravam as vagas de
+ * `concurrency.max_parallel_threads` para sempre (em producao: em_andamento=0 e 15
+ * threads em `concurrency.limite`, porque 3 orfas ocupavam as 3 vagas sem rodar nada).
+ *
+ * A regra que mora aqui, e SO aqui (domicilio unico, consumido por `board.ts` e
+ * `orquestracao.ts`): uma thread tem PROCURA ATIVA quando a sessao do seu ultimo
+ * despacho esta `working` no runtime, ou quando houve atividade recente no ledger de
+ * uma thread ja despachada (fase em execucao entre eventos). Pausa humana aberta,
+ * impedimento nao-transitorio aberto e stale (sem rodar ha mais que
+ * `concurrency.stale_after_min`) NAO ocupam vaga: a vaga volta para quem esta pronto.
+ *
+ * Tudo e DERIVADO de `thread.json`, `ledger.jsonl` e da lista de sessoes do runtime:
+ * avaliar ocupacao nao grava nada, e por isso e deterministico e seguro de rodar em
+ * laco. O registro verificavel da devolucao de vaga e o `ork board reap`, que grava
+ * `slot_released` no ledger da thread devolvida.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENTOS_QUE_DESTRAVAM = exports.PAUSA_PREVISTA = void 0;
+exports.ehAprovacaoHumana = ehAprovacaoHumana;
+exports.ehPausaPrevista = ehPausaPrevista;
+exports.faseTemPausaPrevista = faseTemPausaPrevista;
+exports.avaliarOcupacao = avaliarOcupacao;
+const ledger_1 = require("./ledger");
+const sessoes_adopt_1 = require("./sessoes-adopt");
+/** Estado que o `ork phase run` grava quando o bloco despachado pausa ao fim. */
+exports.PAUSA_PREVISTA = 'prevista ao fim do bloco';
+/**
+ * Eventos que destravam uma reprovacao de gate.
+ *
+ * `phase_dispatch` entra pela porta da frente: o `ork phase run` grava `gate_blocked`
+ * ANTES de despachar e aborta o despacho, entao um `phase_dispatch` posterior so existe
+ * se aquele bloqueio deixou de valer.
+ */
+exports.EVENTOS_QUE_DESTRAVAM = [
+    ledger_1.TIPOS_DE_EVENTO.gateLiberado,
+    ledger_1.TIPOS_DE_EVENTO.faseDespachada,
+    ledger_1.TIPOS_DE_EVENTO.leaseAdquirido,
+    ledger_1.TIPOS_DE_EVENTO.rateLimitRetomado,
+    ledger_1.TIPOS_DE_EVENTO.shipConcluido,
+    ledger_1.TIPOS_DE_EVENTO.masterConcluido,
+];
+/** O evento e uma autorizacao humana ja registrada (`ork gate approve`)? */
+function ehAprovacaoHumana(e) {
+    return e.tipo === ledger_1.TIPOS_DE_EVENTO.pausaHumana && e.estado === 'aprovado';
+}
+/** O evento e a pausa PREVISTA gravada no despacho do ultimo bloco? */
+function ehPausaPrevista(e) {
+    return e.tipo === ledger_1.TIPOS_DE_EVENTO.pausaHumana && e.estado === exports.PAUSA_PREVISTA;
+}
+/** Auto depende do bloco; demais modos conservam o fallback durável após avanço de fase. */
+function faseTemPausaPrevista(thread) {
+    return thread.modo !== 'auto' || thread.blocos.some(b => b.pausa && b.fases.includes(thread.faseAtual));
+}
+/** sessionId do ultimo despacho: o ledger primeiro, o `thread.json` como reserva. */
+function ultimaSessao(thread, eventos) {
+    for (let i = eventos.length - 1; i >= 0; i--) {
+        const s = eventos[i].sessionId;
+        if (typeof s === 'string' && s !== '')
+            return s;
+    }
+    const registrada = thread.sessoes[thread.sessoes.length - 1];
+    return registrada && registrada.sessionId ? registrada.sessionId : null;
+}
+/**
+ * Carimbo do ultimo sinal de vida: o evento mais novo do ledger que seja TRABALHO da
+ * thread. `slot_released` fica de fora: e contabilidade do escalonador, e se contasse
+ * como atividade a thread stale rejuvenesceria no exato momento em que e expulsa.
+ */
+function ultimaAtividadeEm(eventos) {
+    for (let i = eventos.length - 1; i >= 0; i--) {
+        if (eventos[i].tipo !== ledger_1.TIPOS_DE_EVENTO.vagaLiberada)
+            return eventos[i].ts;
+    }
+    return null;
+}
+/** A thread tem pausa humana ABERTA? Mesmas tres fontes do monitor, resumidas. */
+function pausaHumanaAberta(thread, eventos) {
+    if (thread.status === 'pausada' && faseTemPausaPrevista(thread)) {
+        return { desdeEm: thread.atualizadaEm, evidencia: 'thread.json (status: pausada)' };
+    }
+    const indiceDaFase = (fase) => typeof fase === 'string' ? thread.fases.indexOf(fase) : -1;
+    for (let i = 0; i < eventos.length; i++) {
+        const e = eventos[i];
+        const prevista = ehPausaPrevista(e);
+        const escalada = e.tipo === ledger_1.TIPOS_DE_EVENTO.gateBloqueado && e.motivo === 'human.pending';
+        if (!prevista && !escalada)
+            continue;
+        const iFase = indiceDaFase(e.fase);
+        // Na pausa prevista, redespachar a MESMA fase nao resolve pausa nenhuma: so o
+        // avanco para fase posterior, a aprovacao humana ou o MASTER concluido resolvem.
+        const resolvida = eventos.slice(i + 1).some((p) => {
+            if (ehAprovacaoHumana(p))
+                return true;
+            if (p.tipo === ledger_1.TIPOS_DE_EVENTO.masterConcluido)
+                return true;
+            if (escalada && exports.EVENTOS_QUE_DESTRAVAM.includes(p.tipo))
+                return true;
+            return (prevista && p.tipo === ledger_1.TIPOS_DE_EVENTO.faseDespachada && indiceDaFase(p.fase) > iFase);
+        });
+        if (resolvida)
+            continue;
+        return {
+            desdeEm: e.ts,
+            evidencia: prevista
+                ? `ledger ${ledger_1.TIPOS_DE_EVENTO.pausaHumana} (${exports.PAUSA_PREVISTA}) em ${e.ts}`
+                : `ledger ${ledger_1.TIPOS_DE_EVENTO.gateBloqueado} (human.pending) em ${e.ts}`,
+        };
+    }
+    return null;
+}
+/** Gate tipado reprovado sem destravamento: o impedimento nao-transitorio aberto. */
+function impedimentoAberto(eventos) {
+    for (let i = eventos.length - 1; i >= 0; i--) {
+        const e = eventos[i];
+        if (e.tipo !== ledger_1.TIPOS_DE_EVENTO.gateBloqueado && e.tipo !== 'phase_wait')
+            continue;
+        if (typeof e.motivo !== 'string')
+            continue;
+        const motivo = e.motivo;
+        // `human.pending` ja e pausa humana; `claims.unverifiable` avisa mas nao bloqueia.
+        if (motivo === 'human.pending' || motivo === 'claims.unverifiable')
+            continue;
+        const resolvido = eventos
+            .slice(i + 1)
+            .some((p) => exports.EVENTOS_QUE_DESTRAVAM.includes(p.tipo) || ehAprovacaoHumana(p));
+        if (resolvido)
+            continue;
+        return {
+            motivo,
+            desdeEm: e.ts,
+            evidencia: `ledger ${e.tipo} (${motivo}) em ${e.ts}`,
+        };
+    }
+    return null;
+}
+/** Minutos inteiros entre dois carimbos ISO (nunca negativo). */
+function minutos(desdeEm, ateEm) {
+    const inicio = Date.parse(desdeEm);
+    const fim = Date.parse(ateEm);
+    if (!Number.isFinite(inicio) || !Number.isFinite(fim))
+        return 0;
+    return Math.max(0, Math.floor((fim - inicio) / 60000));
+}
+/**
+ * Avalia a PROCURA ATIVA de uma thread, na ordem que decide a vaga:
+ *
+ *   1. sessao `working` no runtime ocupa vaga, mesmo com pausa prevista no ledger --
+ *      a pausa so chega quando a sessao terminar (licao do incidente de 05/09/2026);
+ *   2. sessao `blocked` e pausa humana JA chegada (HITL no runtime): nao ocupa;
+ *   3. pausa humana aberta nao ocupa: esperar humano nao e executar;
+ *   4. impedimento nao-transitorio aberto nao ocupa;
+ *   5. despachada e parada ha mais que `staleMin` vira `stale` e devolve a vaga;
+ *   6. o resto esta `ociosa`: pronta (inclusive entre fases, com a sessao do bloco
+ *      anterior terminada ou o runtime nao consultado), e entra por FIFO quando
+ *      houver vaga -- e ai conta contra o limite, como sempre contou.
+ */
+function avaliarOcupacao(thread, eventos, opcoes) {
+    const sessionId = ultimaSessao(thread, eventos);
+    const sessaoEstado = opcoes.estados === null || sessionId === null
+        ? null
+        : opcoes.estados.get(sessionId) ?? null;
+    const base = { sessionId, sessaoEstado };
+    if (thread.status === 'fechada') {
+        return {
+            ...base,
+            classe: 'ociosa',
+            ocupaVaga: false,
+            motivo: null,
+            detalhe: 'thread fechada nao disputa vaga',
+            evidencia: 'thread.json (status: fechada)',
+        };
+    }
+    const registro = (0, sessoes_adopt_1.ehRegistroDeAdocao)(thread);
+    if (!registro && (sessaoEstado === 'working' || (sessaoEstado === '' && sessionId !== null))) {
+        return {
+            ...base,
+            classe: 'ativa',
+            ocupaVaga: true,
+            motivo: null,
+            detalhe: `sessao ${String(sessionId).slice(0, 8)} trabalhando no runtime`,
+            evidencia: `claude agents --json (sessao ${String(sessionId).slice(0, 8)} state=working)`,
+        };
+    }
+    if (sessaoEstado === 'blocked') {
+        return {
+            ...base,
+            classe: 'pausa-humana',
+            ocupaVaga: false,
+            motivo: 'human.pending',
+            detalhe: `sessao ${String(sessionId).slice(0, 8)} BLOQUEADA no runtime esperando acao humana: ` +
+                'esperar humano nao ocupa vaga da maquina',
+            evidencia: `claude agents --json (sessao ${String(sessionId).slice(0, 8)} state=blocked)`,
+        };
+    }
+    const pausa = pausaHumanaAberta(thread, eventos);
+    if (pausa) {
+        return {
+            ...base,
+            classe: 'pausa-humana',
+            ocupaVaga: false,
+            motivo: 'human.pending',
+            detalhe: `pausa humana aberta ha ${minutos(pausa.desdeEm, opcoes.agora)} min: ` +
+                'esperar veredito humano nao ocupa vaga da maquina',
+            evidencia: pausa.evidencia,
+        };
+    }
+    if (registro)
+        return { ...base, classe: 'ociosa', ocupaVaga: false, motivo: null,
+            detalhe: 'registro de adoção não disputa vaga de trabalho',
+            evidencia: 'thread.json: origem de adoção, sem sessão despachada' };
+    const impedimento = impedimentoAberto(eventos);
+    if (impedimento) {
+        return {
+            ...base,
+            classe: 'impedida',
+            ocupaVaga: false,
+            motivo: impedimento.motivo,
+            detalhe: `gate ${impedimento.motivo} aberto ha ${minutos(impedimento.desdeEm, opcoes.agora)} min ` +
+                'sem evento que destrave: impedimento nao-transitorio nao ocupa vaga',
+            evidencia: impedimento.evidencia,
+        };
+    }
+    const foiDespachada = sessionId !== null;
+    const atividadeEm = ultimaAtividadeEm(eventos);
+    if (foiDespachada && atividadeEm !== null) {
+        const paradaHaMin = minutos(atividadeEm, opcoes.agora);
+        if (paradaHaMin >= opcoes.staleMin) {
+            return {
+                ...base,
+                classe: 'stale',
+                ocupaVaga: false,
+                motivo: 'vaga.stale',
+                detalhe: `despachada e sem atividade ha ${paradaHaMin} min (limite ${opcoes.staleMin} min, ` +
+                    'concurrency.stale_after_min) com sessao nao-working: a vaga foi devolvida',
+                evidencia: `ledger parado desde ${atividadeEm}` +
+                    (sessaoEstado !== null
+                        ? `; sessao ${String(sessionId).slice(0, 8)} state=${sessaoEstado}`
+                        : opcoes.estados !== null
+                            ? `; sessao ${String(sessionId).slice(0, 8)} fora da lista do runtime`
+                            : '; runtime nao consultado'),
+            };
+        }
+        // Sessao nao-working (ou runtime nao consultado) com atividade recente: a thread
+        // esta entre fases, pronta para o proximo despacho. Ela disputa vaga por FIFO,
+        // nao por posse -- e continua contando contra o limite quando recebe a vaga.
+    }
+    return {
+        ...base,
+        classe: 'ociosa',
+        ocupaVaga: false,
+        motivo: null,
+        detalhe: foiDespachada
+            ? 'pronta para o proximo despacho: a sessao do bloco anterior terminou'
+            : 'pronta para rodar: sem despacho ativo, sem pausa e sem impedimento',
+        evidencia: !foiDespachada
+            ? 'thread.json + ledger sem despacho em aberto'
+            : opcoes.estados !== null
+                ? `sessao ${String(sessionId).slice(0, 8)} nao-working na lista do runtime`
+                : `sessao ${String(sessionId).slice(0, 8)} com runtime nao consultado`,
+    };
+}

package/dist/onboarding.js

@@ -0,0 +1,303 @@
+"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.ETAPAS_ONBOARDING = exports.PAUTA_ONBOARDING = exports.CONTRATO_ONBOARDING = void 0;
+exports.caminhoOnboarding = caminhoOnboarding;
+exports.validarConteudo = validarConteudo;
+exports.jsonCanonico = jsonCanonico;
+exports.onboardingPadrao = onboardingPadrao;
+exports.lerOnboarding = lerOnboarding;
+exports.gravarEtapa = gravarEtapa;
+exports.resetarOnboarding = resetarOnboarding;
+exports.textoDaPauta = textoDaPauta;
+/** Entrevista determinística; hosts conduzem a conversa a partir desta pauta. */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const manifest_1 = require("./manifest");
+const project_state_1 = require("./project-state");
+const ledger_1 = require("./ledger");
+const policies_1 = require("./policies");
+const horario_1 = require("./horario");
+exports.CONTRATO_ONBOARDING = 'ork.onboarding/v1';
+exports.PAUTA_ONBOARDING = [
+    { etapa: 'maestro', pergunta: `Quem conduz o projeto, quais são seus objetivos e preferências, e em qual fuso horário o Orkastery deve mostrar horários? Informe o fuso como nome IANA, ex.: {"fuso":"${horario_1.FUSO_DE_BRASILIA}"}; ele orienta ${horario_1.CHAVE_DO_FUSO} no manifesto, sem editá-lo.` },
+    { etapa: 'credenciais', pergunta: 'Quais provedores públicos e nomes de variáveis em env serão usados? Segredos somente em ~/.hermes/.env; nunca informe valores.' },
+    { etapa: 'bancos', pergunta: 'Quais bancos públicos e nomes de variáveis em env configuram as conexões? Nunca informe DSN ou senha; valores somente em ~/.hermes/.env.' },
+    { etapa: 'memoria', pergunta: 'Deseja OrkMind? Informe {"modo":"orkmind"} ou {"modo":"files"}; a escolha orienta memory.mode no manifesto, sem editá-lo.' },
+    { etapa: 'produtos', pergunta: 'Quais produtos e repositórios públicos pertencem ao projeto?' },
+    { etapa: 'topologia', pergunta: 'Como se distribuem ambientes e serviços? Informe identificadores públicos.' },
+    { etapa: 'arquitetura', pergunta: 'Quais decisões e restrições de arquitetura devem orientar o trabalho?' },
+    { etapa: 'skills', pergunta: 'Quais capacidades e skills serão necessárias?' },
+    { etapa: 'auditores', pergunta: 'Quais auditorias e cadências são desejadas?' },
+];
+exports.ETAPAS_ONBOARDING = exports.PAUTA_ONBOARDING.map(p => p.etapa);
+function caminhoOnboarding(raiz) {
+    return (0, project_state_1.stateFile)(raiz, 'onboarding.json');
+}
+function objeto(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(v));
+}
+/** Recusa antes de persistir. Diagnósticos nunca incluem a entrada recebida. */
+function invalido() { throw new Error('onboarding.input.invalid: use JSON público e referências de variáveis; segredos somente em ~/.hermes/.env'); }
+function textoSeguro(v) {
+    return !(0, policies_1.procurarSegredos)(v).length &&
+        !/[a-z][a-z0-9+.-]*:\/\/[^\s/]*@/i.test(v) &&
+        !/\b(?:senha|password|secret|token|api[_-]?key|authorization)\s*[:=]\s*\S+/i.test(v) &&
+        !/\bBearer\s+\S+|-----BEGIN|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\./.test(v);
+}
+function validarJson(v, profundidade = 0) {
+    if (profundidade > 12)
+        invalido();
+    if (v === null || typeof v === 'boolean')
+        return;
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v))
+            invalido();
+        return;
+    }
+    if (typeof v === 'string') {
+        if (!textoSeguro(v))
+            invalido();
+        return;
+    }
+    if (Array.isArray(v)) {
+        for (const item of v)
+            validarJson(item, profundidade + 1);
+        return;
+    }
+    if (!objeto(v))
+        invalido();
+    for (const [k, item] of Object.entries(v)) {
+        if (['__proto__', 'constructor', 'prototype'].includes(k) || !textoSeguro(k))
+            invalido();
+        if (/(?:senha|password|secret|token|api[_-]?key|authorization|credential|credencial|dsn|private[_-]?key)/i.test(k)) {
+            if (!/_env$/.test(k) || typeof item !== 'string' || !/^[A-Z][A-Z0-9_]{1,127}$/.test(item))
+                invalido();
+        }
+        validarJson(item, profundidade + 1);
+    }
+}
+function validarConteudo(etapa, conteudo) {
+    validarJson(conteudo);
+    if (Buffer.byteLength(JSON.stringify(conteudo)) > 16384)
+        invalido();
+    // I-35: o fuso do dono, quando informado, precisa ser um nome IANA que o Intl aceita.
+    if (etapa === 'maestro' && objeto(conteudo) && Object.hasOwn(conteudo, 'fuso') && (0, horario_1.normalizarFuso)(conteudo.fuso) === undefined)
+        invalido();
+    // Etapas sensíveis usam um formato fechado: não há espaço para texto de credenciais.
+    if (etapa === 'credenciais' || etapa === 'bancos') {
+        if (!objeto(conteudo))
+            invalido();
+        for (const [k, v] of Object.entries(conteudo)) {
+            if (k === 'env') {
+                if (!Array.isArray(v) || v.some(x => typeof x !== 'string' || !/^[A-Z][A-Z0-9_]{1,127}$/.test(x)))
+                    invalido();
+            }
+            else if (k === 'provedor' || k === 'banco') {
+                if (typeof v !== 'string' || !/^[a-zA-Z][a-zA-Z0-9._ -]{0,79}$/.test(v))
+                    invalido();
+            }
+            else
+                invalido();
+        }
+    }
+}
+/** Chaves ordenadas recursivamente; a ordem de arrays continua significativa. */
+function jsonCanonico(v) {
+    if (Array.isArray(v))
+        return '[' + v.map(jsonCanonico).join(',') + ']';
+    if (objeto(v))
+        return '{' + Object.keys(v).sort().map(k => JSON.stringify(k) + ':' + jsonCanonico(v[k])).join(',') + '}';
+    return JSON.stringify(v);
+}
+function sha(v) { return (0, node_crypto_1.createHash)('sha256').update(jsonCanonico(v)).digest('hex'); }
+function onboardingPadrao() {
+    return { contrato: exports.CONTRATO_ONBOARDING, atualizadoEm: null,
+        etapas: Object.fromEntries(exports.ETAPAS_ONBOARDING.map(e => [e, null])) };
+}
+function lerArquivo(raiz) {
+    const arquivo = caminhoOnboarding(raiz);
+    if (fs.statSync(arquivo).size > 256 * 1024)
+        legadoInvalido();
+    return JSON.parse(fs.readFileSync(arquivo, 'utf8'));
+}
+function dataMaisRecente(datas) {
+    return datas.filter((d) => typeof d === 'string' && Number.isFinite(Date.parse(d)))
+        .reduce((maior, d) => maior === null || Date.parse(d) > Date.parse(maior) ? d : maior, null);
+}
+function normalizar(bruto) {
+    const estado = onboardingPadrao();
+    if (!objeto(bruto) || !objeto(bruto.etapas))
+        return estado;
+    for (const etapa of exports.ETAPAS_ONBOARDING) {
+        const r = bruto.etapas[etapa];
+        if (!objeto(r) || typeof r.por !== 'string' || !r.por.trim() || r.por.length > 120 || !textoSeguro(r.por) ||
+            typeof r.respondidaEm !== 'string' || !Number.isFinite(Date.parse(r.respondidaEm)))
+            continue;
+        try {
+            validarConteudo(etapa, r.conteudo);
+            estado.etapas[etapa] = { por: r.por, respondidaEm: r.respondidaEm, conteudo: r.conteudo };
+        }
+        catch { /* entrada legada insegura permanece pendente */ }
+    }
+    const datas = Object.values(estado.etapas).filter((r) => !!r).map(r => r.respondidaEm);
+    estado.atualizadoEm = dataMaisRecente([bruto.atualizadoEm, ...datas]);
+    return estado;
+}
+function lerOnboarding(raiz) {
+    const state = (0, project_state_1.projectState)(raiz);
+    try {
+        const value = lerArquivo(raiz);
+        if (state.linked && (!objeto(value) || !objeto(value.etapas)))
+            throw new Error('project-state.source.invalid');
+        return normalizar(value);
+    }
+    catch {
+        if (state.linked)
+            throw new Error('project-state.source.unavailable');
+        return onboardingPadrao();
+    }
+}
+function legadoInvalido() {
+    throw new Error('onboarding.legacy.invalid: escrita recusada para preservar respostas não representáveis; revise o arquivo ou use reset explícito da etapa.');
+}
+/** Chamada somente sob trava; uma leitura tolerante não autoriza descarte na escrita. */
+function lerParaMutacao(raiz, reset = []) {
+    let bruto;
+    try {
+        bruto = lerArquivo(raiz);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { estado: onboardingPadrao(), descartadas: [] };
+        legadoInvalido();
+    }
+    if (!objeto(bruto) || !objeto(bruto.etapas))
+        legadoInvalido();
+    const estado = normalizar(bruto);
+    const descartadas = Object.entries(bruto.etapas).filter(([etapa, valor]) => valor !== null &&
+        (!exports.ETAPAS_ONBOARDING.includes(etapa) || estado.etapas[etapa] === null)).map(([etapa]) => etapa);
+    if (descartadas.some(etapa => !reset.includes(etapa)))
+        legadoInvalido();
+    return { estado, descartadas };
+}
+function exigirEtapa(etapa) {
+    if (!exports.ETAPAS_ONBOARDING.includes(etapa))
+        invalido();
+    return etapa;
+}
+function exigirAutor(por) {
+    if (typeof por !== 'string' || !por.trim() || por.length > 120 || !textoSeguro(por))
+        invalido();
+}
+function persistir(raiz, estado) {
+    const arquivo = caminhoOnboarding(raiz), temporario = arquivo + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
+    fs.mkdirSync(path.dirname(arquivo), { recursive: true });
+    try {
+        fs.writeFileSync(temporario, JSON.stringify(estado, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temporario, arquivo);
+    }
+    finally {
+        if (fs.existsSync(temporario))
+            fs.unlinkSync(temporario);
+    }
+}
+/** Serializa toda a mutação. Nunca toma uma trava por idade ou remove trava alheia. */
+function comTrava(raiz, alterar) {
+    const trava = caminhoOnboarding(raiz) + '.lock';
+    fs.mkdirSync(path.dirname(trava), { recursive: true });
+    const limite = Date.now() + 5000;
+    let fd;
+    for (;;) {
+        try {
+            fd = fs.openSync(trava, 'wx', 0o600);
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            if (Date.now() >= limite)
+                throw new Error('onboarding.busy: entrevista em uso; tente novamente. Se persistir, confira o encerramento dos escritores antes de remover onboarding.json.lock.');
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        return alterar();
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(trava);
+    }
+}
+function gravarEtapa(raiz, nome, conteudo, por = 'owner') {
+    const etapa = exigirEtapa(nome);
+    exigirAutor(por);
+    validarConteudo(etapa, conteudo);
+    return comTrava(raiz, () => {
+        const { estado } = lerParaMutacao(raiz), anterior = estado.etapas[etapa];
+        if (anterior && jsonCanonico(anterior.conteudo) === jsonCanonico(conteudo))
+            return estado;
+        const timestamp = new Date().toISOString();
+        estado.etapas[etapa] = { respondidaEm: timestamp, por, conteudo };
+        estado.atualizadoEm = dataMaisRecente([estado.atualizadoEm, timestamp]);
+        persistir(raiz, estado);
+        (0, ledger_1.registrar)((0, manifest_1.dirEstado)((0, project_state_1.projectState)(raiz).root), 'projeto', ledger_1.TIPOS_DE_EVENTO.onboardingRegistrado, { acao: 'set', etapa, por, sha256: sha(conteudo) });
+        return estado;
+    });
+}
+function resetarOnboarding(raiz, nome, por = 'owner') {
+    exigirAutor(por);
+    const etapas = nome === undefined ? exports.ETAPAS_ONBOARDING : [exigirEtapa(nome)];
+    return comTrava(raiz, () => {
+        const { estado, descartadas } = lerParaMutacao(raiz, etapas);
+        const alteradas = etapas.filter(e => estado.etapas[e] !== null || descartadas.includes(e));
+        if (!alteradas.length)
+            return estado;
+        for (const etapa of alteradas)
+            estado.etapas[etapa] = null;
+        estado.atualizadoEm = dataMaisRecente([estado.atualizadoEm, new Date().toISOString()]);
+        persistir(raiz, estado);
+        for (const etapa of alteradas)
+            (0, ledger_1.registrar)((0, manifest_1.dirEstado)((0, project_state_1.projectState)(raiz).root), 'projeto', ledger_1.TIPOS_DE_EVENTO.onboardingRegistrado, { acao: 'reset', etapa, por, sha256: sha(null) });
+        return estado;
+    });
+}
+function textoDaPauta(estado = onboardingPadrao()) {
+    return ['Onboarding do projeto (' + exports.CONTRATO_ONBOARDING + ')',
+        ...exports.PAUTA_ONBOARDING.map(({ etapa, pergunta }) => `${estado.etapas[etapa] ? '[respondida]' : '[pendente]'} ${etapa}: ${pergunta}`),
+        'Responda com ork onboarding set <etapa> --conteudo <JSON> --por <quem>.'].join('\n');
+}