@aksp/opencrew 1.6.3 → 1.7.0

package/templates/_opencrew/core/scripts/escritorio/servidor.mjs

@@ -0,0 +1,78 @@
+// Servidor do escritório: só leitura, só neste computador, com rotas fechadas.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 13 a 15 (repositório do OpenCrew).
+import http from 'node:http';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { lerCrews } from './leitura.mjs';
+import { projetoDe } from './projeto.mjs';
+
+// Vão em TODA resposta. Nenhuma resposta leva `Access-Control-*`: outra origem não lê o estado.
+const CABECALHOS = {
+  'Cache-Control': 'no-store',
+  'X-Content-Type-Options': 'nosniff',
+  'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'",
+};
+const TEXTO = 'text/plain; charset=utf-8';
+const JSON_UTF8 = 'application/json; charset=utf-8';
+const TIPOS = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' };
+const SEM_TIPO = 'application/octet-stream';
+
+const MSG_HOST = (porta) => `Abra por http://127.0.0.1:${porta}`;
+
+function responder(res, status, { corpo, tipo = TEXTO, extras = {} }) {
+  res.writeHead(status, { ...CABECALHOS, 'Content-Type': tipo, 'Content-Length': Buffer.byteLength(corpo), ...extras });
+  res.end(corpo);
+}
+
+/**
+ * O pedido veio para este endereço? Uma página de fora que aponte um nome dela para 127.0.0.1
+ * chega com o nome dela no `Host`; só valem `127.0.0.1` e `localhost`, com a porta real.
+ */
+function hostAceito(req) {
+  const porta = req.socket.localPort;
+  const host = String(req.headers.host ?? '').toLowerCase();
+  return host === `127.0.0.1:${porta}` || host === `localhost:${porta}`;
+}
+
+/** Arquivo da página pelo nome da lista; null quando o caminho não é rota ou o arquivo falta. */
+async function lerArquivo(ctx, caminho) {
+  const nome = ctx.rotas.get(caminho);
+  if (!nome) return null;
+  const corpo = await fs.readFile(path.join(ctx.pasta, nome)).catch(() => null);
+  return corpo && { corpo, tipo: TIPOS[path.extname(nome)] ?? SEM_TIPO };
+}
+
+async function atender(req, res, ctx) {
+  if (!hostAceito(req)) return responder(res, 421, { corpo: MSG_HOST(req.socket.localPort) });
+  if (req.method !== 'GET') return responder(res, 405, { corpo: 'Método não permitido', extras: { Allow: 'GET' } });
+  const caminho = req.url.split('?')[0];
+  if (caminho === '/estado') {
+    const corpo = JSON.stringify({ projeto: ctx.projeto, crews: await lerCrews(ctx.raiz) });
+    return responder(res, 200, { corpo, tipo: JSON_UTF8 });
+  }
+  const arquivo = await lerArquivo(ctx, caminho);
+  return arquivo ? responder(res, 200, arquivo) : responder(res, 404, { corpo: 'Não encontrado' });
+}
+
+function falhar(res) {
+  if (res.headersSent) res.destroy();
+  else responder(res, 500, { corpo: 'Erro interno' });
+}
+
+/**
+ * Cria o servidor (sem abrir a porta: quem abre é `abrir`, em `porta.mjs`).
+ * @param {object} o
+ * @param {string} o.raiz pasta do projeto (a que tem `_opencrew/` e `crews/`)
+ * @param {string} o.pasta pasta da página (`_opencrew/core/escritorio/`)
+ * @param {string[]} o.arquivos nomes servidos dessa pasta. É uma lista fixa: o caminho do pedido
+ *   é comparado com ela e nunca é juntado a uma pasta, e a pasta nunca é lida para montar rota
+ * @returns {import('node:http').Server}
+ */
+export function criarServidor({ raiz, pasta, arquivos }) {
+  const rotas = new Map([['/', 'index.html'], ...arquivos.map((nome) => [`/${nome}`, nome])]);
+  const ctx = { raiz, pasta, rotas, projeto: projetoDe(raiz) };
+  // Sem `Host` o pedido também chega aqui e leva o 421 com os cabeçalhos, e não o 400 do Node.
+  return http.createServer({ requireHostHeader: false }, (req, res) => {
+    atender(req, res, ctx).catch(() => falhar(res));
+  });
+}

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Escritório do OpenCrew — servidor local da página que mostra a equipe trabalhando.
+// Uso: node _opencrew/core/scripts/escritorio.mjs [--porta <1024 a 65535>]
+//   Rode na pasta do projeto (a que contém `_opencrew/`). Sem --porta, começa na 4747.
+// Só leitura e só neste computador: escuta em 127.0.0.1, aceita só GET e não escreve em disco.
+// Serve a página (`_opencrew/core/escritorio/`) e `GET /estado`, que lê `crews/*/state.json` a
+// cada pedido.
+// Porta ocupada: se quem responde nela é o escritório deste mesmo projeto, avisa e sai com 0, sem
+// subir outro; senão tenta a seguinte, até 10 portas ao todo.
+// Código de saída: 0 = escritório aberto (o processo segue rodando até Ctrl+C) ou já aberto ·
+// 1 = erro de uso (porta inválida, pasta sem `_opencrew/`) ou nenhuma das 10 portas livre.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 13 a 15 (repositório do OpenCrew).
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ehPrincipal } from './comum.mjs';
+import { criarServidor } from './escritorio/servidor.mjs';
+import { abrir, sondar, procurar } from './escritorio/porta.mjs';
+import { projetoDe } from './escritorio/projeto.mjs';
+
+/**
+ * Os arquivos da página, um a um: é a lista inteira do que o servidor entrega além de `/estado`.
+ * Arquivo novo em `_opencrew/core/escritorio/` só é servido depois de entrar aqui.
+ */
+export const ARQUIVOS = [
+  'index.html', 'app.js', 'painel.js', 'rotulos.js', 'cena.js',
+  'sprites.js', 'sprites-sala.js', 'sprites-mesa.js',
+  'modelo.js', 'modelo-mesas.js', 'modelo-textos.js', 'modelo-estado.js', 'modelo-agentes.js',
+  'modelo-visao.js', 'modelo-pagina.js', 'demo.js',
+  'escala.js', 'rota.js', 'animacao.js', 'quadro.js',
+];
+
+const PORTA_PADRAO = 4747;
+const PORTA_MINIMA = 1024;
+const PORTA_MAXIMA = 65535;
+
+// Instalado, este script fica em `_opencrew/core/scripts/` e a página em `_opencrew/core/escritorio/`.
+const PASTA_DA_PAGINA = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'escritorio');
+
+const endereco = (porta) => `http://127.0.0.1:${porta}`;
+
+const USO = `Uso: node _opencrew/core/scripts/escritorio.mjs [--porta <${PORTA_MINIMA} a ${PORTA_MAXIMA}>]`;
+const MSG = {
+  aberto: (porta) => `Escritório aberto em ${endereco(porta)} — Ctrl+C para fechar`,
+  jaAberto: (porta) => `O escritório já está aberto em ${endereco(porta)}`,
+  semPorta: (a, b) => `Não foi possível abrir o escritório: as portas ${a} a ${b} estão ocupadas. Use --porta.`,
+  foraDaRaiz: 'Rode este comando na pasta do projeto (a que contém _opencrew/).',
+  portaInvalida: `Porta inválida: use --porta com um número de ${PORTA_MINIMA} a ${PORTA_MAXIMA}.`,
+};
+
+const ehPasta = (p) => existsSync(p) && statSync(p).isDirectory();
+
+/**
+ * A porta pedida em `--porta N` ou `--porta=N` (a última vale); sem a opção, a padrão.
+ * @returns {number|null} null quando o valor não é um inteiro de 1024 a 65535
+ */
+function lerPorta(argv) {
+  let porta = PORTA_PADRAO;
+  for (let i = 0; i < argv.length; i++) {
+    const opcao = argv[i].match(/^--porta(?:=(.*))?$/s);
+    if (!opcao) continue;
+    const valor = opcao[1] ?? argv[++i] ?? '';
+    const numero = /^\d{1,5}$/.test(valor) ? Number(valor) : 0;
+    if (numero < PORTA_MINIMA || numero > PORTA_MAXIMA) return null;
+    porta = numero;
+  }
+  return porta;
+}
+
+/**
+ * Erro de uso, na ordem: porta inválida → pasta atual sem `_opencrew/`.
+ * @returns {string[]|null} as linhas em PT-BR, ou null quando está tudo certo
+ */
+function erroDeUso(porta, cwd) {
+  if (porta === null) return [MSG.portaInvalida, USO];
+  if (!ehPasta(path.join(cwd, '_opencrew'))) return [MSG.foraDaRaiz];
+  return null;
+}
+
+/**
+ * Sobe o escritório do projeto que mora em `cwd`, ou reconhece o que já está aberto.
+ * @param {string[]} argv argumentos da linha de comando
+ * @param {object} [o]
+ * @param {string} [o.cwd] pasta do projeto
+ * @param {(linha: string) => void} [o.escrever] recebe cada linha da saída
+ * @param {string} [o.pasta] pasta da página
+ * @param {string[]} [o.arquivos] nomes servidos da pasta da página
+ * @param {(servidor: object, porta: number) => Promise<boolean>} [o.abrir] SÓ PARA TESTE: tenta
+ *   abrir a porta (serve para simular portas ocupadas sem ocupá-las)
+ * @param {(porta: number) => Promise<string|null>} [o.sondar] SÓ PARA TESTE: o `projeto` de quem
+ *   responde na porta
+ * @returns {Promise<{ code: number, porta?: number, servidor?: import('node:http').Server }>}
+ *   `code` 0 com `porta` (escritório aberto ou já aberto) ou 1; `servidor` só quando este
+ *   comando abriu um — é ele que mantém o processo vivo
+ */
+export async function main(argv, o = {}) {
+  const { cwd = process.cwd(), escrever = (linha) => process.stdout.write(`${linha}\n`), pasta = PASTA_DA_PAGINA, arquivos = ARQUIVOS } = o;
+  const inicial = lerPorta(argv);
+  const erro = erroDeUso(inicial, cwd);
+  if (erro) {
+    erro.forEach((linha) => escrever(linha));
+    return { code: 1 };
+  }
+  const servidor = criarServidor({ raiz: cwd, pasta, arquivos });
+  const tentar = (porta) => (o.abrir ?? abrir)(servidor, porta);
+  const r = await procurar({ inicial, projeto: projetoDe(cwd), abrir: tentar, sondar: o.sondar ?? sondar });
+  if (r.tipo === 'sem-porta') {
+    escrever(MSG.semPorta(inicial, r.ultima));
+    return { code: 1 };
+  }
+  escrever(r.tipo === 'aberto' ? MSG.aberto(r.porta) : MSG.jaAberto(r.porta));
+  return r.tipo === 'aberto' ? { code: 0, porta: r.porta, servidor } : { code: 0, porta: r.porta };
+}
+
+if (ehPrincipal(import.meta.url)) {
+  main(process.argv.slice(2)).then(({ code }) => { process.exitCode = code; });
+}

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

@@ -0,0 +1,61 @@
+// Linha de comando do `estado.mjs`: a crew, o evento, as opções e a linha de uso.
+// Spec: fase-e1-escritorio-ao-vivo.md, §3 e regra 7 (repositório do OpenCrew).
+
+export const USO = 'Uso: node _opencrew/core/scripts/estado.mjs <crew> <evento> [opções]';
+
+/** Teto, em caracteres visíveis, de `--rotulo`, `--mensagem` e `--motivo`. */
+export const TETO = 120;
+
+const OPCAO = /^--(passos|n|agente|rotulo|mensagem|motivo)(?:=(.*))?$/s;
+const QUEBRA = /[\r\n\v\f\u0085\u2028\u2029]+/g;
+const segmentador = new Intl.Segmenter('pt', { granularity: 'grapheme' });
+
+/**
+ * Texto recebido é dado: fica numa linha (quebra de linha vira espaço) e com até 120 caracteres.
+ * O corte conta caracteres visíveis, por isso nunca parte um emoji ao meio. O laço para no 121º
+ * segmento: no Node 20 cada segmento guarda uma cópia da entrada, e guardar todos custaria caro.
+ */
+export function limparTexto(valor) {
+  const linha = String(valor).replace(QUEBRA, ' ').trim();
+  let fim = 0;
+  let visiveis = 0;
+  for (const { index, segment } of segmentador.segment(linha)) {
+    if (visiveis++ === TETO) break;
+    fim = index + segment.length;
+  }
+  return linha.slice(0, fim);
+}
+
+/** Inteiro a partir de 1; qualquer outra coisa é `null` (a opção não vale). */
+const inteiro = (valor) => (/^\d{1,9}$/.test(valor ?? '') && Number(valor) >= 1 ? Number(valor) : null);
+
+/** As opções como o núcleo as recebe: ausente ou inválida é `null` (número, agente) ou vazio (texto). */
+function converter(cru) {
+  return {
+    passos: inteiro(cru.passos),
+    n: inteiro(cru.n),
+    agente: limparTexto(cru.agente ?? '') || null,
+    rotulo: limparTexto(cru.rotulo ?? ''),
+    mensagem: limparTexto(cru.mensagem ?? ''),
+    motivo: limparTexto(cru.motivo ?? ''),
+  };
+}
+
+/**
+ * `argv` → `{ crew, evento, opcoes: { passos, n, agente, rotulo, mensagem, motivo } }`. Os dois
+ * primeiros argumentos soltos são a crew e o evento (indefinidos, se faltam). Opção vale como
+ * `--nome valor` e `--nome=valor`; opção sem valor (a última, ou seguida de outra opção) não
+ * consome o argumento seguinte.
+ */
+export function lerArgs(argv) {
+  const soltos = [];
+  const cru = {};
+  for (let i = 0; i < argv.length; i++) {
+    const [, nome, colado] = argv[i].match(OPCAO) ?? [];
+    if (!nome) soltos.push(argv[i]);
+    else if (colado !== undefined) cru[nome] = colado;
+    else if (i + 1 < argv.length && !OPCAO.test(argv[i + 1])) cru[nome] = argv[++i];
+  }
+  const [crew, evento] = soltos.filter((s) => !s.startsWith('--'));
+  return { crew, evento, opcoes: converter(cru) };
+}

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; });
+}