@aksp/opencrew 1.6.2 → 1.7.0

package/templates/_opencrew/core/scripts/estado/arquivo.mjs

@@ -0,0 +1,53 @@
+// Leitura e gravação de `crews/<crew>/state.json`: inteira ou nenhuma.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 3 e 6 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+
+/** O Windows recusa a troca de nome com um destes códigos enquanto outro processo lê o arquivo. */
+const RECUSAS = ['EPERM', 'EBUSY', 'EACCES'];
+/** Depois da primeira tentativa: até 3 repetições, uma a cada 100 ms (cerca de 300 ms ao todo). */
+const REPETICOES = 3;
+const INTERVALO_MS = 100;
+
+const pausa = (ms) => new Promise((seguir) => { setTimeout(seguir, ms); });
+
+/** O estado gravado, ou `null` quando o arquivo falta ou está ilegível (pela metade, sem `agents` em lista). */
+export async function lerEstado(arquivo) {
+  try {
+    const estado = JSON.parse((await fs.readFile(arquivo, 'utf8')).replace(/^\uFEFF/, ''));
+    return Array.isArray(estado?.agents) ? estado : null;
+  } catch {
+    return null;
+  }
+}
+
+async function trocarNome(de, para, { renomear = fs.rename, esperar = pausa }) {
+  for (let repeticao = 0; ; repeticao++) {
+    try {
+      return await renomear(de, para);
+    } catch (erro) {
+      if (!RECUSAS.includes(erro?.code) || repeticao === REPETICOES) throw erro;
+      await esperar(INTERVALO_MS);
+    }
+  }
+}
+
+/**
+ * Grava o estado num temporário da mesma pasta (`state.json.<pid>.tmp`) e troca o nome: quem lê
+ * vê o arquivo antigo ou o novo, nunca um pela metade.
+ * @param {string} arquivo caminho do `state.json`
+ * @param {object} estado
+ * @param {{ renomear?: Function, esperar?: Function }} [deps] SÓ PARA TESTE: a troca de nome
+ *   (`(de, para) => Promise`) e a espera entre as tentativas (`(ms) => Promise`)
+ * @returns {Promise<boolean>} `false` quando desistiu: o arquivo fica como estava e o temporário é apagado
+ */
+export async function gravarEstado(arquivo, estado, deps = {}) {
+  const temporario = `${arquivo}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(temporario, `${JSON.stringify(estado, null, 2)}\n`);
+    await trocarNome(temporario, arquivo, deps);
+    return true;
+  } catch {
+    await fs.rm(temporario, { force: true }).catch(() => {});
+    return false;
+  }
+}

package/templates/_opencrew/core/scripts/estado/decisao.mjs

@@ -0,0 +1,56 @@
+// O que fazer com um evento: aplicar, montar o estado de novo antes, ou ignorar. Puro, como o
+// núcleo: recebe o estado lido (ou `null`) e o evento, não toca em disco.
+// Spec: fase-e1-escritorio-ao-vivo.md, regra 5 e §6 (repositório do OpenCrew).
+import { proximoEstado } from './nucleo.mjs';
+
+/** Os motivos de `ESTADO:IGNORADO` (o texto depois do travessão). */
+export const MOTIVO = {
+  desligado: 'escritório desligado (ligue com /opencrew dashboard)',
+  semElenco: 'crew-party.csv ausente ou sem agentes',
+  agenteDesconhecido: (id, ids) => `agente "${id}" não está no elenco da crew. Ids válidos: ${ids.join(', ')}`,
+  pularSemAgente: (ids) => `o evento pular precisa de --agente. Ids válidos: ${ids.join(', ')}`,
+  semEstado: 'sem estado desta execução',
+  naoGravou: 'não foi possível gravar o estado',
+  inesperado: (erro) => `erro inesperado: ${erro?.message ?? erro}`,
+};
+
+const USAM_AGENTE = ['passo', 'checkpoint', 'pular'];
+/** Eventos que montam o estado quando ele falta; os outros são ignorados sem ele. */
+const MONTAM = ['iniciar', 'passo', 'checkpoint'];
+const ENCERRADA = ['completed', 'failed'];
+
+function motivoParaIgnorar(anterior, { tipo, agente, elenco }) {
+  const ids = elenco.map((a) => a.id);
+  if (!ids.length) return MOTIVO.semElenco;
+  const pedeAgente = USAM_AGENTE.includes(tipo);
+  if (pedeAgente && agente && !ids.includes(agente)) return MOTIVO.agenteDesconhecido(agente, ids);
+  if (tipo === 'pular' && !agente) return MOTIVO.pularSemAgente(ids);
+  return anterior || MONTAM.includes(tipo) ? null : MOTIVO.semEstado;
+}
+
+/**
+ * `passo` e `checkpoint` montam o estado de novo quando ele falta ou está ilegível, quando o
+ * `passo --n 1` chega sobre uma execução encerrada, e quando o agente do evento está no elenco
+ * mas não no estado gravado (elenco editado sem um `iniciar` depois).
+ */
+function pedeRecriar(anterior, { tipo, n, agente }) {
+  if (tipo !== 'passo' && tipo !== 'checkpoint') return false;
+  if (!anterior) return true;
+  if (tipo === 'passo' && n === 1 && ENCERRADA.includes(anterior.status)) return true;
+  return Boolean(agente) && !anterior.agents.some((a) => a?.id === agente);
+}
+
+/**
+ * @param {object|null} anterior o estado lido do `state.json`; `null` se falta ou está ilegível
+ * @param {object} evento o evento do núcleo, sempre com `crew`, `elenco` e `agora`
+ * @returns {{ ignorado: string } | { estado: object, recriado: boolean }} o motivo para não
+ *   mexer em nada, ou o estado a gravar (`recriado`: foi montado de novo, como no `iniciar`,
+ *   herdando só o `step.total`)
+ */
+export function decidir(anterior, evento) {
+  const motivo = motivoParaIgnorar(anterior, evento);
+  if (motivo) return { ignorado: motivo };
+  const recriado = pedeRecriar(anterior, evento);
+  const base = recriado ? proximoEstado(null, { ...evento, tipo: 'iniciar', passos: anterior?.step?.total }) : anterior;
+  return { estado: proximoEstado(base, evento), recriado };
+}

package/templates/_opencrew/core/scripts/estado/elenco.mjs

@@ -0,0 +1,58 @@
+// O elenco de uma crew, lido de `crew-party.csv` (cabeçalho id,displayName,title,icon,path,execution;
+// crew antiga pode não ter a coluna `id`).
+// Spec: fase-e1-escritorio-ao-vivo.md, regra 2 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Texto CSV → linhas, cada uma com os seus campos (sem as aspas e sem espaço nas pontas). Entre
+ * aspas o campo pode ter vírgula, quebra de linha e `""` (uma aspa). Uma passada só, caractere a
+ * caractere: aspa que não fecha leva o resto do texto para o campo, nunca trava.
+ */
+export function lerCsv(texto) {
+  const linhas = [];
+  let linha = [];
+  let campo = '';
+  let aspas = false;
+  const fechaCampo = () => { linha.push(campo.trim()); campo = ''; };
+  const fechaLinha = () => { fechaCampo(); linhas.push(linha); linha = []; };
+  for (let i = 0; i < texto.length; i++) {
+    const c = texto[i];
+    if (c === '"' && aspas && texto[i + 1] === '"') campo += texto[i++];
+    else if (c === '"') aspas = !aspas;
+    else if (aspas || !',\r\n'.includes(c)) campo += c;
+    else if (c === ',') fechaCampo();
+    else if (c === '\n' || texto[i + 1] !== '\n') fechaLinha(); // `\r\n` fecha a linha uma vez só
+  }
+  if (campo || linha.length) fechaLinha();
+  return linhas;
+}
+
+/** O id que o nome do arquivo do agente dá: `./agents/x.agent.md` → `x`; outro caminho, nenhum. */
+const idDoCaminho = (caminho = '') => caminho.match(/([^/\\]+)\.agent\.md$/i)?.[1] ?? '';
+
+/**
+ * O elenco, na ordem do arquivo: `[{ id, name, icon }]`. As colunas `id`, `displayName`, `icon` e
+ * `path` são achadas pelo nome no cabeçalho. Linha sem `id` (crew antiga, de antes de o cabeçalho
+ * ser fixo) usa o nome do arquivo em `path`. Sem nenhum dos dois, ou com `id` repetido, a linha
+ * fica de fora; sem `displayName`, o nome é o `id`.
+ */
+export function elencoDoCsv(texto) {
+  const [cabecalho = [], ...linhas] = lerCsv(texto.replace(/^\uFEFF/, ''));
+  const colunas = ['id', 'displayname', 'icon', 'path'].map((c) => cabecalho.findIndex((h) => h.toLowerCase() === c));
+  const [id, nome, icone, caminho] = colunas;
+  const vistos = new Set();
+  return linhas
+    .map((l) => ({ l, i: l[id] || idDoCaminho(l[caminho]) }))
+    .map(({ l, i }) => ({ id: i, name: l[nome] || i, icon: l[icone] ?? '' }))
+    .filter((a) => a.id && !vistos.has(a.id) && vistos.add(a.id));
+}
+
+/** O elenco da crew; lista vazia quando o `crew-party.csv` falta, não abre ou não tem agentes. */
+export async function lerElenco(pastaDaCrew) {
+  try {
+    return elencoDoCsv(await fs.readFile(path.join(pastaDaCrew, 'crew-party.csv'), 'utf8'));
+  } catch {
+    return [];
+  }
+}

package/templates/_opencrew/core/scripts/estado/nucleo.mjs

@@ -0,0 +1,113 @@
+// Núcleo puro do estado da execução: (estado, evento) → estado novo. Não lê relógio nem disco:
+// a hora chega em `evento.agora` e o elenco em `evento.elenco`. O estado recebido nunca é alterado.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 1 e 2 e §4 (repositório do OpenCrew).
+
+/** Agente que ainda não entregou. `delivering` só existe em arquivo da 1.6.x. */
+const ATIVOS = ['working', 'checkpoint', 'delivering'];
+/** Quem o `falhar` derruba. */
+const EM_CURSO = ['working', 'checkpoint'];
+
+const texto = (v) => (typeof v === 'string' ? v : '');
+const aPartirDe = (minimo, v) => (Number.isInteger(v) && v >= minimo ? v : null);
+
+function agenteNormal(a) {
+  return { id: texto(a?.id), name: texto(a?.name), icon: texto(a?.icon), status: texto(a?.status) || 'idle', label: texto(a?.label) };
+}
+
+/** O estado lido, no formato de hoje: agentes sem `desk` e com `label`, `step` completo. */
+function normalizar(e) {
+  const { step, handoff } = e;
+  return {
+    ...e,
+    crew: texto(e.crew),
+    status: texto(e.status),
+    step: { current: aPartirDe(0, step?.current) ?? 0, total: aPartirDe(1, step?.total), label: texto(step?.label) },
+    agents: (Array.isArray(e.agents) ? e.agents : []).map(agenteNormal),
+    handoff: handoff && typeof handoff === 'object' ? handoff : null,
+    startedAt: e.startedAt ?? null,
+  };
+}
+
+/** Só os campos da §4, na ordem dela; o que é de um status só não sobrevive a ele. */
+function fechar(e, agora) {
+  return {
+    crew: e.crew,
+    status: e.status,
+    step: e.step,
+    agents: e.agents,
+    handoff: e.handoff,
+    ...(e.status === 'failed' ? { motivo: texto(e.motivo) } : {}),
+    startedAt: e.startedAt,
+    updatedAt: agora,
+    ...(e.status === 'completed' ? { completedAt: e.completedAt } : {}),
+    ...(e.status === 'failed' ? { failedAt: e.failedAt } : {}),
+  };
+}
+
+const trocar = (agents, quem, status) => agents.map((a) => (quem(a) ? { ...a, status } : a));
+
+/** `--n` grava `step.current`; `--rotulo` grava `step.label` (sem ele: vazio). */
+const comPasso = (step, { n, rotulo }) => ({ ...step, current: aPartirDe(1, n) ?? step.current, label: texto(rotulo) });
+
+function iniciar(_anterior, { crew, elenco, passos, agora }) {
+  return {
+    crew: texto(crew),
+    status: 'running',
+    step: { current: 0, total: aPartirDe(1, passos), label: '' },
+    agents: elenco.map((a) => agenteNormal({ ...a, status: 'idle', label: '' })),
+    handoff: null,
+    startedAt: agora,
+  };
+}
+
+function passo(estado, evento) {
+  const base = { ...estado, status: 'running', step: comPasso(estado.step, evento) };
+  const alvo = evento.agente ? estado.agents.find((a) => a.id === evento.agente) : null;
+  if (!alvo) return base;
+  const outros = estado.agents.filter((a) => a !== alvo && ATIVOS.includes(a.status));
+  const agents = estado.agents.map((a) => {
+    if (a === alvo) return { ...a, status: 'working', label: texto(evento.rotulo) };
+    return outros.includes(a) ? { ...a, status: 'done' } : a;
+  });
+  const bastao = { from: outros[0]?.id, to: alvo.id, message: texto(evento.mensagem), completedAt: evento.agora };
+  return { ...base, agents, handoff: outros.length ? bastao : estado.handoff };
+}
+
+function checkpoint(estado, evento) {
+  const agents = evento.agente ? trocar(estado.agents, (a) => a.id === evento.agente, 'checkpoint') : estado.agents;
+  return { ...estado, status: 'checkpoint', step: comPasso(estado.step, evento), agents };
+}
+
+function pular(estado, { agente }) {
+  return { ...estado, agents: agente ? trocar(estado.agents, (a) => a.id === agente, 'skipped') : estado.agents };
+}
+
+function concluir(estado, { agora }) {
+  return { ...estado, status: 'completed', completedAt: agora, agents: trocar(estado.agents, (a) => a.status !== 'skipped', 'done') };
+}
+
+function falhar(estado, { motivo, agora }) {
+  const agents = trocar(estado.agents, (a) => EM_CURSO.includes(a.status), 'failed');
+  return { ...estado, status: 'failed', failedAt: agora, motivo: texto(motivo), agents };
+}
+
+const TRANSICOES = { iniciar, passo, checkpoint, pular, concluir, falhar };
+
+/** Os seis eventos da regra 2, na ordem em que o runner os usa. */
+export const EVENTOS = Object.keys(TRANSICOES);
+
+/**
+ * O estado depois do evento.
+ * @param {object|null} estado o estado atual, como está no `state.json` (da 1.6.x também); o
+ *   `iniciar` não o lê
+ * @param {object} evento `{ tipo, agora, … }` · `tipo`: um dos `EVENTOS` · `agora`: a hora, em ISO
+ *   · no `iniciar`: `crew`, `elenco` (`[{ id, name, icon }]`) e `passos` · nos outros, conforme o
+ *   evento: `n`, `agente`, `rotulo`, `mensagem`, `motivo`. Agente que não está no estado vale como
+ *   evento sem agente.
+ * @returns {object} o estado novo, no formato da §4 da spec (`step.total` vazio é `null`)
+ */
+export function proximoEstado(estado, evento) {
+  if (!Object.hasOwn(TRANSICOES, evento.tipo)) throw new Error(`Evento desconhecido: ${evento.tipo}`);
+  const atual = evento.tipo === 'iniciar' ? null : normalizar(estado);
+  return fechar(TRANSICOES[evento.tipo](atual, evento), evento.agora);
+}

package/templates/_opencrew/core/scripts/estado/preferencia.mjs

@@ -0,0 +1,24 @@
+// O escritório está ligado? A preferência mora em `_opencrew/_memory/preferences.md`.
+// Spec: fase-e1-escritorio-ao-vivo.md, regra 9 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+// A linha da preferência: `- **Dashboard:** <valor>` (a que o onboarding grava) ou
+// `Dashboard: <valor>`, sem diferenciar maiúsculas. Comentário e texto corrido não contam.
+const LINHA = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?dashboard(?:\*\*)?:(?:\*\*)?[ \t]*(\S*)/im;
+
+/**
+ * Pura: o texto de `preferences.md` liga o escritório? Vale a primeira linha da preferência. A marca
+ * de ordem de bytes que o PowerShell do Windows e alguns editores gravam no início do arquivo não
+ * faz parte da linha.
+ */
+export const ligadoNoTexto = (texto) => texto.replace(/^\uFEFF/, '').match(LINHA)?.[1].toLowerCase() === 'enabled';
+
+/** Desligado por padrão: sem o arquivo, sem a linha ou com outro valor, a resposta é `false`. */
+export async function escritorioLigado(raiz) {
+  try {
+    return ligadoNoTexto(await fs.readFile(path.join(raiz, '_opencrew', '_memory', 'preferences.md'), 'utf8'));
+  } catch {
+    return false;
+  }
+}

package/templates/_opencrew/core/scripts/estado.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Estado da execução de uma crew, para o escritório ao vivo: grava `crews/<crew>/state.json`,
+// e só ele. Quem grava é este script, um comando por evento — a IA não monta o JSON.
+// Uso (na pasta do projeto): node _opencrew/core/scripts/estado.mjs <crew> <evento> [opções]
+//   iniciar    [--passos N]
+//   passo      [--n K] [--agente <id>] [--rotulo "<texto>"] [--mensagem "<texto>"]
+//   checkpoint [--n K] [--agente <id>] [--rotulo "<texto>"]
+//   pular      --agente <id>
+//   concluir
+//   falhar     [--motivo "<texto>"]
+// <crew> é o nome da pasta em `crews/`. Só grava com `Dashboard: enabled` em
+// `_opencrew/_memory/preferences.md`.
+// Última linha da saída (o runner lê esta linha): ESTADO:OK, ESTADO:OK — estado recriado ou
+// ESTADO:IGNORADO — <motivo>. Código de saída: 0 sempre que a linha ESTADO: sai · 1 = erro de uso
+// (crew ou evento faltando, evento fora da lista, pasta sem `_opencrew/`, crew inexistente ou
+// fora de `crews/`); com código 1 não há linha ESTADO: e nada é escrito.
+// Spec: fase-e1-escritorio-ao-vivo.md (repositório do OpenCrew).
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { MSG, dentroDoProjeto, ehPrincipal } from './comum.mjs';
+import { USO, lerArgs, limparTexto } from './estado/argumentos.mjs';
+import { EVENTOS } from './estado/nucleo.mjs';
+import { MOTIVO, decidir } from './estado/decisao.mjs';
+import { lerElenco } from './estado/elenco.mjs';
+import { lerEstado, gravarEstado } from './estado/arquivo.mjs';
+import { escritorioLigado } from './estado/preferencia.mjs';
+
+const OK = 'ESTADO:OK';
+const RECRIADO = 'ESTADO:OK — estado recriado';
+/** A resposta é sempre uma linha só, mesmo que o motivo traga um id ou um erro com quebra. */
+const ignorado = (motivo) => `ESTADO:IGNORADO — ${motivo}`.replace(/\s*[\r\n]+\s*/g, ' ');
+
+const LISTA = EVENTOS.join(', ');
+
+function ehPasta(caminho) {
+  try {
+    return statSync(caminho).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Onde fica a crew, ou o erro de uso. A crew é uma pasta direta de `crews/` (`crews/<nome>`
+ * também vale): só assim o único arquivo escrito é `crews/<crew>/state.json`.
+ * @returns {{ erro: string } | { pasta: string, crew: string }}
+ */
+function localizar(raiz, { crew, evento }) {
+  if (!crew) return { erro: 'Falta o nome da crew.' };
+  if (!evento) return { erro: `Falta o evento. Eventos: ${LISTA}.` };
+  if (!EVENTOS.includes(evento)) return { erro: `Evento desconhecido: ${limparTexto(evento)}. Eventos: ${LISTA}.` };
+  if (!ehPasta(path.join(raiz, '_opencrew'))) return { erro: MSG.semRaiz };
+  const base = path.resolve(raiz, 'crews');
+  const nome = crew.replace(/^crews[\\/]+/, '');
+  if (!dentroDoProjeto(base, nome)) return { erro: MSG.foraDoProjeto(limparTexto(crew)) };
+  const pasta = path.resolve(base, nome);
+  if (path.dirname(pasta) !== base || !ehPasta(pasta)) return { erro: MSG.crewNaoEncontrada(limparTexto(crew)) };
+  return { pasta, crew: path.basename(pasta) };
+}
+
+/** Confere a preferência, lê o elenco e o estado, decide e grava. Devolve a linha `ESTADO:`. */
+async function responder({ raiz, pasta, crew }, args, deps) {
+  if (!(await escritorioLigado(raiz))) return ignorado(MOTIVO.desligado);
+  const agora = (deps.agora ?? (() => new Date().toISOString()))();
+  const evento = { tipo: args.evento, ...args.opcoes, crew, elenco: await lerElenco(pasta), agora };
+  const arquivo = path.join(pasta, 'state.json');
+  const decisao = decidir(await lerEstado(arquivo), evento);
+  if (decisao.ignorado) return ignorado(decisao.ignorado);
+  if (!(await gravarEstado(arquivo, decisao.estado, deps))) return ignorado(MOTIVO.naoGravou);
+  return decisao.recriado ? RECRIADO : OK;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto) e `escrever`; SÓ PARA TESTE: `agora` (a hora,
+ *   em ISO), `renomear` e `esperar` (a troca de nome e a espera da gravação)
+ * @returns {Promise<number>} 0 = a linha `ESTADO:` saiu · 1 = erro de uso (a linha de uso e o
+ *   motivo, sem linha `ESTADO:`, nada escrito)
+ */
+export async function main(argv, deps = {}) {
+  const { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = deps;
+  const args = lerArgs(argv);
+  const local = localizar(cwd, args);
+  if (local.erro) {
+    escrever(USO);
+    escrever(local.erro);
+    return 1;
+  }
+  // O escritório nunca para a execução: o que der errado daqui em diante vira ESTADO:IGNORADO.
+  escrever(await responder({ raiz: cwd, ...local }, args, deps).catch((erro) => ignorado(MOTIVO.inesperado(erro))));
+  return 0;
+}
+
+if (ehPrincipal(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

package/templates/_opencrew/core/scripts/verificar.mjs

@@ -11,10 +11,11 @@
 // obrigatória faltando, pasta sem `_opencrew/`, crew inexistente, crew ou caminho fora do
 // projeto, nenhum caminho da lista existe) ou erro que impediu a verificação inteira; com
 // código 1 não há linha VERIFICACAO:.
-// Specs: fase-u1-revisor-com-dentes.md e fase-r1-reparos-1-6-1.md (repositório do OpenCrew).
+// Specs: fase-u1-revisor-com-dentes.md, fase-r1-reparos-1-6-1.md e fase-r2-update-e-envio-seguros.md
+// (regra 23: "dentro do projeto" pelo texto ou pelo lugar real), no repositório do OpenCrew.
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { erroDeUso, ehPrincipal } from './comum.mjs';
+import { erroDeUso, ehPrincipal, relativoAoProjeto } from './comum.mjs';
 import { USO, lerArgs, lerItemDaLista } from './verificar/argumentos.mjs';
 import { lerItem } from './verificar/arquivos.mjs';
 import { lerLimites, lerDominioDoSite, semFrontmatter } from './verificar/leitura.mjs';
@@ -102,9 +103,11 @@ function semRepetidas(raiz, entradas) {
   });
 }
 
-/** Caminho absoluto de dentro do projeto aparece no relatório como o relativo. */
+/** No relatório, o absoluto de dentro do projeto (também por link, junção ou nome curto) sai como o relativo. */
 function nomeNoRelatorio(raiz, arquivo) {
-  return path.isAbsolute(arquivo) ? path.relative(raiz, arquivo).split(path.sep).join('/') : arquivo;
+  const relativo = relativoAoProjeto(raiz, arquivo);
+  const comoEscrito = !path.isAbsolute(arquivo) && path.resolve(raiz, relativo) === path.resolve(raiz, arquivo);
+  return comoEscrito ? arquivo : relativo;
 }
 
 function resumir(arquivos, naoTexto, notas) {

package/templates/_opencrew/core/skills.engine.md

@@ -54,6 +54,7 @@ Frontmatter fields:
   - `dependencies`: Array of npm/pip packages to install
 - `env` (array): List of required environment variable names
 - `categories` (array): Classification tags (e.g., scraping, design, analytics)
+- `side_effects` (string, optional): `irreversible` for a skill that publishes or sends — read by Operation 6
 
 Body: Markdown instructions injected into agent context at runtime.
 
@@ -382,7 +383,7 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
 1. **Skip native skills**: `web_search` and `web_fetch` do not need instruction injection —
    they are handled natively.
 
-2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, and `type` fields.
+2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, `type` and `side_effects` fields.
 
 3. **Build the Tier 1 index** and append after all agent instructions:
    ```
@@ -394,8 +395,9 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
    you are invoking and the system will load its full instructions.
 
    - {skill-id}: {description from frontmatter} (type: {type})
-   - {skill-id}: {description from frontmatter} (type: {type})
+   - {skill-id}: {description from frontmatter} (type: {type}) — irreversível: carregue as instruções desta skill e peça a confirmação antes de usar
    ```
+   The second form is for every skill with `side_effects: irreversible`.
 
 4. **Tier 2 loading** — When the step's instructions explicitly reference a skill
    (e.g., the step file says "use image-creator to render the slides"), OR when the
@@ -412,7 +414,9 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
 5. **Step-level skill hints**: If the step's frontmatter contains a `skills_needed:` field
    (e.g., `skills_needed: [image-creator]`), load Tier 2 for those skills immediately
    without waiting for the agent to request them. This allows the Architect to pre-declare
-   which skills a step will need.
+   which skills a step will need. A skill with `side_effects: irreversible` always gets Tier 2
+   before its first use, even when no step names it: an MCP tool can be called without the body,
+   and the confirmation rules live there.
 
 6. **Missing skill handling**: If a skill listed in an agent's frontmatter was not resolved
    during Operation 5, skip it silently — the user was already warned during resolution.

package/templates/gitignore

@@ -8,4 +8,5 @@ _opencrew/_memory/company.md
 _opencrew/_memory/preferences.md
 _opencrew/_browser_profile/
 _opencrew/logs/
+.opencrew-backup/
 .claude/settings.local.json

package/templates/skills/blotato/SKILL.md

@@ -20,6 +20,7 @@ mcp:
   url: "https://mcp.blotato.com/mcp"
   headers:
     blotato-api-key: BLOTATO_API_KEY
+side_effects: irreversible
 env:
   - BLOTATO_API_KEY
 categories: [social-media, automation, publishing, scheduling]
@@ -35,19 +36,47 @@ Use Blotato when you need to publish or schedule social media posts across multi
 
 You have access to Blotato for social media publishing.
 
-### Key workflow
+### Workflow
 
-1. Use `blotato_list_accounts` to get account IDs and platforms
-2. If post includes images or videos, upload them with `blotato_upload_media` first and use the returned media IDs in `blotato_create_post`
-3. Use `blotato_create_post` to publish or schedule
-4. Use `blotato_get_post_status` to confirm success
+Publishing is **irreversible**: a post cannot be taken back once it is live. The rule below is
+about the **action**, whatever the tool is called on the server: before ANY call that publishes,
+schedules or deletes, follow this order. The messages to the user are in PT-BR, as written here.
+
+1. List the connected accounts (`blotato_list_accounts`, read-only) to get the account IDs and
+   platforms. Send nothing to Blotato yet, not even media.
+2. **Preview (prévia)** — show the user exactly this, filled in:
+   ```
+   Vou publicar isto:
+   Contas: {conta} ({rede}), …
+   Quando: agora, ou agendado para {data e hora}
+   Texto ({N} caracteres): {texto}
+   Mídia: {arquivos}, ou nenhuma
+   Para publicar, responda com a palavra publicar. Qualquer outra resposta cancela.
+   ```
+   (`Quando`: write `agora` or `agendado para …`. `Mídia`: the file names, or `nenhuma`.)
+3. Wait for the word **publicar**. Any other answer — including silence, "ok" or "sim" — cancels:
+   say "Nada foi publicado." and stop.
+4. Only after the word: upload the media, if any (`blotato_upload_media`), then make **one single
+   call** that publishes or schedules (`blotato_create_post`; if the server takes one account per
+   call, once per account of the preview and never twice for the same account).
+5. On success: check the result (`blotato_get_post_status`) and save the post URL and ID to the
+   step output file immediately.
+6. On failure, timeout or missing answer: do NOT repeat the call again, in this step or in a retry.
+   Tell the user: "⚠️ Não recebi a confirmação do Blotato. A publicação pode já ter saído. Confira
+   no painel antes de tentar de novo. Não vou repetir sozinho."
+7. One confirmation is worth one publication. If this step runs again in the same run (a retry, or
+   back from a rejected review), show the preview again, after this line: "Este passo já tentou
+   publicar nesta execução. Confira se saiu antes de confirmar de novo." — and wait for the word.
+8. A call that **deletes** (a post, a scheduled post, media) follows the same order with its own
+   word: "Vou apagar isto: {o que será apagado}. Para apagar, responda com a palavra apagar.
+   Qualquer outra resposta cancela." Any other answer: "Nada foi apagado."
 
 ### Best practices
 
-- Always call `blotato_list_accounts` first to get valid account IDs
 - For scheduled posts, use ISO 8601 format for datetime
-- After posting, poll `blotato_get_post_status` until status is "published" or "scheduled"
-- If status is "failed", report the error details to the user
+- After the publishing call, read `blotato_get_post_status` until status is "published" or
+  "scheduled" — reading the status is safe; calling `blotato_create_post` again is not
+- If status is "failed", report the error details to the user and let them decide
 
 ### Requirements
 
@@ -57,7 +86,7 @@ You have access to Blotato for social media publishing.
 ## Available operations
 
 - **List Accounts** -- Retrieve connected social media accounts and their platform types
-- **Upload Media** -- Upload images and videos for use in posts
-- **Create Post** -- Publish or schedule a post to one or more platforms
+- **Upload Media** -- Upload images and videos for use in posts (only after the word)
+- **Create Post** -- Publish or schedule a post to one or more platforms (only after the word)
 - **Get Post Status** -- Monitor publishing status (published, scheduled, failed)
 - **Multi-platform Publishing** -- Post the same content across Instagram, LinkedIn, Twitter/X, TikTok, YouTube simultaneously

package/templates/skills/image-ai-generator/SKILL.md

@@ -15,7 +15,7 @@ version: "1.0.0"
 script:
   path: scripts/generate.py
   runtime: python
-  invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
+  invoke: "python3 {skill_path}/scripts/generate.py --prompt-file \"{prompt_file}\" --output \"{output}\" --mode \"{mode}\""
 env:
   - OPENROUTER_API_KEY
 categories: [assets, images, ai, generation]
@@ -56,11 +56,22 @@ Use the Image Generator when you need to create visual assets from text prompts.
 `python3` (macOS/Linux). **On Windows** use `py -3` instead (or `python` if the `py` launcher is
 not installed).
 
+**The prompt goes in a file.** Write it with your file-writing tool, in UTF-8, next to the image
+(`crews/{crew}/output/{run_id}/assets/image-name.prompt.txt`). Never put the prompt inside a shell
+command: write it to a file and pass `--prompt-file`. The shell rewrites `$`, quotes and backticks
+in a typed text (a price like "R$50" reaches the model wrong, and the image is still charged). The
+old `--prompt` option is still accepted, for crews created before; do not use it.
+
+**File names.** Every path in the command (`--prompt-file`, `--output`, `--reference`, `--batch`)
+follows the safe-name rule (nome seguro) of `_opencrew/core/runner.pipeline.md` — letters, digits,
+space and `. _ - / \ : ( )`, between double quotes. With any other character do not run the
+command: ask the user to rename the file.
+
 ### Single image generation
 
 ```bash
 python3 {skill_path}/scripts/generate.py \
-  --prompt "A detailed description of the image to generate" \
+  --prompt-file "crews/{crew}/output/{run_id}/assets/image-name.prompt.txt" \
   --output "crews/{crew}/output/{run_id}/assets/image-name.jpg" \
   --mode test
 ```
@@ -71,7 +82,7 @@ Use `--reference` to send a local image to the model as visual context. The mode
 
 ```bash
 python3 {skill_path}/scripts/generate.py \
-  --prompt "A social media banner featuring the company logo prominently in the center" \
+  --prompt-file "crews/{crew}/output/{run_id}/assets/banner.prompt.txt" \
   --output "crews/{crew}/output/{run_id}/assets/banner.jpg" \
   --reference "crews/{crew}/assets/logo.png" \
   --mode production
@@ -87,7 +98,8 @@ python3 {skill_path}/scripts/generate.py \
   --mode production
 ```
 
-The batch JSON file should contain:
+Write the batch JSON file with your file-writing tool, in UTF-8 (the prompts inside it never go
+through the shell). It should contain:
 ```json
 [
   {"prompt": "Description of image 1", "output": "path/to/image1.jpg"},
@@ -115,13 +127,14 @@ Each item can optionally include a `"reference": "path/to/ref.png"` field.
 
 ## Available operations
 
-- **Single generation** — Generate one image from a text prompt
+- **Single generation** — Generate one image from a text prompt saved in a file
 - **Batch generation** — Generate multiple images from a JSON batch file
 - **Mode selection** — Choose between test (cheap) and production (high-quality) models
 - **Reference image** — Send a logo/mascot/brand asset as visual context for the generation
 
 ## Error handling
 
+- If the prompt file is missing or empty, or the batch file cannot be read (not UTF-8, invalid JSON), the script says so in one line and exits with code 1. Show the message to the user; nothing was generated or charged.
 - If `OPENROUTER_API_KEY` is not set, the script exits with an error message. Set it in your `.env` file or environment.
 - If the API returns an error, the script prints the error code and body, then exits with code 1.
 - If no image is found in the API response, the script reports which model was used and exits with code 1.