@spec-wave/cli 0.10.0 → 0.11.1

package/src/commands/dev-agent.mjs

@@ -0,0 +1,568 @@
+// spec-wave dev-agent --install | --run
+//
+// Instala e executa o spec-wave-agent (daemon Rust) na máquina do dev. O
+// binário vem das releases do repo do agente (baixado com `gh release
+// download`, que usa as credenciais do próprio dev), a config é derivada do
+// .spec-wave.json do repositório e o serviço (systemd/launchd) é opcional.
+//
+// Convenção do repo: a lógica de decisão fica em funções puras exportadas
+// (testadas em test/dev-agent.test.mjs) e o I/O fica na função imperativa.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import {
+  chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync,
+  readFileSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILE } from '../config.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dir, '..', 'templates', 'agent');
+
+/** Repositório que publica as releases do agente. */
+export const AGENT_REPO = 'astratech-net-br/spec-wave-agent';
+export const BIN_NAME = 'spec-wave-agent';
+/** Instalação sem sudo. */
+export const BIN_DIR = path.join('.local', 'bin');
+export const AGENT_CONFIG = path.join('.config', 'spec-wave-agent', 'config.toml');
+/** Tag instalada — arquivo de estado escrito por nós.
+ *  NÃO detectamos versão executando o binário: versões antigas não têm
+ *  --version e subiriam o DAEMON no lugar de imprimir a versão. */
+export const STATE_FILE = path.join('.local', 'share', 'spec-wave-agent', 'installed-tag');
+/** Clone usado pelo --build (reaproveitado entre builds). */
+export const SRC_DIR = path.join('.local', 'share', 'spec-wave-agent', 'src');
+
+/** Marca de versão para binários compilados do fonte. */
+export function sourceTag(ref, sha) {
+  const short = (sha || '').slice(0, 7);
+  return `fonte:${ref}${short ? `@${short}` : ''}`;
+}
+
+// ---------------------------------------------------------------------------
+// Puro (testável)
+// ---------------------------------------------------------------------------
+
+const TARGETS = {
+  'linux:x64': 'x86_64-unknown-linux-gnu',
+  'darwin:arm64': 'aarch64-apple-darwin',
+  'win32:x64': 'x86_64-pc-windows-msvc',
+};
+
+/** Sufixo do executável na plataforma. */
+export function exeSuffix(platform) {
+  return platform === 'win32' ? '.exe' : '';
+}
+
+/**
+ * Nome do asset da release para a plataforma. Recebe platform/arch por
+ * parâmetro (em vez de ler process.*) para ser testável.
+ * @returns {string|null} null quando a plataforma não tem binário publicado
+ */
+export function assetNameFor(platform, arch) {
+  const target = TARGETS[`${platform}:${arch}`];
+  return target ? `${BIN_NAME}-${target}${exeSuffix(platform)}` : null;
+}
+
+/** Substitui {placeholders} — mesmo idiom do renderCommand do implement. */
+function render(template, vars) {
+  return template.replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
+}
+
+/**
+ * config.toml do agente a partir do .spec-wave.json. Nunca escreve token.
+ */
+export function renderAgentConfig({ owner, repo }) {
+  return `# spec-wave-agent — gerado por \`spec-wave dev-agent --install\`
+# Schema completo: https://github.com/${AGENT_REPO}#configuração
+
+repo = "${owner}/${repo}"
+queue_label = "spec-wave:dev-agent"
+
+# Defaults do agente (descomente para ajustar):
+#poll_interval_secs = 60       # consulta à fila quando ocioso
+#heartbeat_secs = 120          # renovação do lease
+#lease_ttl_secs = 600          # >= 4x heartbeat (validado no boot)
+#implement_timeout_secs = 14400  # teto de UMA feature inteira (4h)
+#cooldown_secs = 900           # issue processada sai da fila local por este tempo
+#max_executor_rounds = 8       # teto de rodadas do executor por feature
+
+# Executor (Claude Code). Para fixar o modelo, acrescente --model:
+#feature_command = "claude -p --model opus --output-format stream-json --verbose --permission-mode acceptEdits --allowedTools \\"Bash(npx:*),Bash(git:*),Edit,Write,Read,Glob,Grep,Task\\""
+
+# Origin alternativo (SSH, git self-hosted). Default: https://github.com/{repo}.git
+#remote_url = "git@github.com:${owner}/${repo}.git"
+`;
+}
+
+/**
+ * Unit do serviço a partir dos templates.
+ * @param {'systemd'|'launchd'} kind
+ */
+export function renderServiceUnit(kind, { home, bin, pathEnv }) {
+  const file = kind === 'launchd' ? 'dev.specwave.agent.plist' : 'spec-wave-agent.service';
+  const raw = readFileSync(path.join(TEMPLATES_DIR, file), 'utf-8');
+  return render(raw, { home, bin, path: pathEnv });
+}
+
+/** O diretório já está no PATH? */
+export function isOnPath(dir, pathEnv) {
+  if (!pathEnv) return false;
+  return pathEnv.split(path.delimiter).filter(Boolean).some((e) => path.resolve(e) === path.resolve(dir));
+}
+
+/**
+ * O que o --install vai fazer, para o relatório e o --dry-run.
+ * @param {{binPath, binInstalled, installedTag, targetTag, configPath,
+ *          configExists, service, servicePath, force}} ctx
+ * @returns {Array<{what: string, path: string, action: 'criar'|'atualizar'|'manter'}>}
+ */
+export function planInstall(ctx) {
+  const items = [];
+  const sameVersion = ctx.binInstalled
+    && !!ctx.installedTag
+    && ctx.installedTag === ctx.targetTag;
+  items.push({
+    what: `binário ${ctx.targetTag ?? ''}`.trim(),
+    path: ctx.binPath,
+    action: !ctx.binInstalled ? 'criar' : (sameVersion && !ctx.force ? 'manter' : 'atualizar'),
+  });
+  items.push({
+    what: 'config',
+    path: ctx.configPath,
+    action: !ctx.configExists ? 'criar' : (ctx.force ? 'atualizar' : 'manter'),
+  });
+  if (ctx.service) {
+    items.push({
+      what: `serviço (${ctx.service})`,
+      path: ctx.servicePath,
+      action: ctx.force ? 'atualizar' : 'criar',
+    });
+  }
+  return items;
+}
+
+const ACTION_MARK = { criar: chalk.green('+'), atualizar: chalk.yellow('~'), manter: chalk.dim('=') };
+
+export function renderInstallReport(items) {
+  return items
+    .map((i) => `${ACTION_MARK[i.action] ?? '?'} ${i.what}: ${chalk.dim(i.path)} ${chalk.dim(`(${i.action})`)}`)
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+function sh(cmd) {
+  return execSync(cmd, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+}
+
+function has(cmd) {
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try { sh(probe); return true; } catch { return false; }
+}
+
+/** Tag instalada (arquivo de estado), ou null se desconhecida. */
+function readInstalledTag(home) {
+  try { return readFileSync(path.join(home, STATE_FILE), 'utf-8').trim() || null; }
+  catch { return null; }
+}
+
+function writeInstalledTag(home, tag) {
+  const f = path.join(home, STATE_FILE);
+  mkdirSync(path.dirname(f), { recursive: true });
+  writeFileSync(f, `${tag}\n`, 'utf-8');
+}
+
+function readRepoConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    return { error: `${CONFIG_FILE} não encontrado. Rode \`spec-wave init\` neste repositório primeiro.` };
+  }
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    if (!cfg.owner || !cfg.repo) {
+      return { error: `${CONFIG_FILE} não contém owner/repo. Rode \`spec-wave init\` novamente.` };
+    }
+    return { cfg };
+  } catch (err) {
+    return { error: `${CONFIG_FILE} corrompido: ${err.message}` };
+  }
+}
+
+/** Checagens de pré-requisito no estilo do doctor: nunca lança. */
+function preflight(cfg) {
+  const problems = [];
+  const warnings = [];
+  if (!has('git')) problems.push('git não encontrado no PATH.');
+  if (!has('gh')) {
+    problems.push('gh (GitHub CLI) não encontrado — instale: https://cli.github.com');
+  } else {
+    try { sh('gh auth status'); }
+    catch { problems.push('gh não autenticado — rode `gh auth login`.'); }
+  }
+  if (!has('npx')) problems.push('npx não encontrado — instale Node 18+.');
+  if (!has('claude')) {
+    warnings.push('Claude Code (claude) não encontrado no PATH — o agente precisa dele para implementar.');
+  }
+  if (!cfg?.specKit?.command && !process.env.SPEC_WAVE_IMPLEMENT_CMD) {
+    warnings.push(
+      `${CONFIG_FILE} sem specKit.command — cada story precisa dele para ser implementada. ` +
+      'Configure "specKit": { "command": "claude -p \\"...{tasksFile}...\\" --permission-mode acceptEdits" } ' +
+      'ou exporte SPEC_WAVE_IMPLEMENT_CMD.'
+    );
+  }
+  return { problems, warnings };
+}
+
+function latestTag() {
+  try {
+    return sh(`gh release view --repo ${AGENT_REPO} --json tagName --jq .tagName`);
+  } catch (err) {
+    const msg = String(err.stderr || err.message || '');
+    if (/HTTP 404|Not Found|release not found/i.test(msg)) {
+      throw new Error(
+        `Nenhuma release publicada em ${AGENT_REPO} (ou você não tem acesso ao repositório privado). ` +
+        'Peça acesso à organização ou instale a partir do fonte (veja o README do agente).'
+      );
+    }
+    throw new Error(`Não foi possível consultar as releases de ${AGENT_REPO}: ${msg.trim() || err.message}`);
+  }
+}
+
+/** Baixa o asset + .sha256 num tempdir, confere o hash e devolve o caminho. */
+function downloadAsset(tag, asset) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'spec-wave-agent-'));
+  try {
+    sh(`gh release download ${tag} --repo ${AGENT_REPO} --pattern "${asset}" --pattern "${asset}.sha256" --dir "${dir}" --clobber`);
+  } catch (err) {
+    rmSync(dir, { recursive: true, force: true });
+    const msg = String(err.stderr || err.message || '');
+    if (/no assets match|asset.*not found/i.test(msg)) {
+      throw new Error(`A release ${tag} não tem o binário para esta plataforma (${asset}).`);
+    }
+    throw new Error(`Falha ao baixar ${asset} da release ${tag}: ${msg.trim() || err.message}`);
+  }
+  const binTmp = path.join(dir, asset);
+  const sumFile = path.join(dir, `${asset}.sha256`);
+  if (existsSync(sumFile)) {
+    const expected = readFileSync(sumFile, 'utf-8').trim().split(/\s+/)[0];
+    const actual = createHash('sha256').update(readFileSync(binTmp)).digest('hex');
+    if (expected !== actual) {
+      rmSync(dir, { recursive: true, force: true });
+      throw new Error(`Checksum do binário não confere (esperado ${expected}, obtido ${actual}).`);
+    }
+  }
+  return { dir, binTmp };
+}
+
+function installService({ kind, home, binPath, servicePath }) {
+  const pathEnv = [path.dirname(binPath), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin']
+    .filter((d, i, a) => a.indexOf(d) === i)
+    .join(':');
+  const content = renderServiceUnit(kind, { home, bin: binPath, pathEnv });
+  mkdirSync(path.dirname(servicePath), { recursive: true });
+  writeFileSync(servicePath, content, 'utf-8');
+  if (kind === 'systemd') {
+    execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
+    execSync('systemctl --user enable --now spec-wave-agent', { stdio: 'inherit' });
+  } else {
+    mkdirSync(path.join(home, 'Library', 'Logs'), { recursive: true });
+    try { execSync(`launchctl unload "${servicePath}"`, { stdio: ['pipe', 'pipe', 'pipe'] }); } catch { /* não estava carregado */ }
+    execSync(`launchctl load "${servicePath}"`, { stdio: 'inherit' });
+  }
+}
+
+async function install(options) {
+  const cwd = process.cwd();
+  const home = homedir();
+  const binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  const configPath = path.join(home, AGENT_CONFIG);
+
+  // 1. Repositório + pré-requisitos.
+  const { cfg, error } = readRepoConfig(cwd);
+  if (error) { p.log.error(error); process.exitCode = 1; return; }
+
+  const { problems, warnings } = preflight(cfg);
+  for (const w of warnings) p.log.warn(w);
+  if (problems.length > 0) {
+    p.log.error(`Pré-requisitos faltando:\n  - ${problems.join('\n  - ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Plataforma.
+  const asset = assetNameFor(process.platform, process.arch);
+  if (!asset) {
+    p.log.error(
+      `Sem binário publicado para ${process.platform}/${process.arch}. ` +
+      'Compile a partir do fonte (veja o README do agente).'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Versão alvo x instalada.
+  const spin = p.spinner();
+  spin.start('Consultando a release do agente...');
+  let targetTag;
+  try { targetTag = options.tag || latestTag(); }
+  catch (err) { spin.stop('Falhou.'); p.log.error(err.message); process.exitCode = 1; return; }
+  spin.stop(`Release alvo: ${chalk.bold(targetTag)}`);
+
+  const binInstalled = existsSync(binPath);
+  const installedTag = binInstalled ? readInstalledTag(home) : null;
+  const items = planInstall({
+    binPath, binInstalled, installedTag, targetTag, configPath,
+    configExists: existsSync(configPath),
+    service: options.service ? (process.platform === 'darwin' ? 'launchd' : 'systemd') : null,
+    servicePath: process.platform === 'darwin'
+      ? path.join(home, 'Library', 'LaunchAgents', 'dev.specwave.agent.plist')
+      : path.join(home, '.config', 'systemd', 'user', 'spec-wave-agent.service'),
+    force: !!options.force,
+  });
+  p.note(renderInstallReport(items), 'Plano de instalação');
+
+  if (options.dryRun) {
+    p.outro('Dry-run: nada foi instalado.');
+    return;
+  }
+
+  // 4. Binário.
+  const binItem = items[0];
+  if (binItem.action === 'manter') {
+    p.log.info(`Binário já está em ${targetTag} — nada a baixar (use --force para reinstalar).`);
+  } else {
+    const s = p.spinner();
+    s.start(`Baixando ${asset} (${targetTag})...`);
+    let tmp;
+    try { tmp = downloadAsset(targetTag, asset); }
+    catch (err) { s.stop('Falhou.'); p.log.error(err.message); process.exitCode = 1; return; }
+    try {
+      mkdirSync(path.dirname(binPath), { recursive: true });
+      copyFileSync(tmp.binTmp, binPath);
+      chmodSync(binPath, 0o755);
+      writeInstalledTag(home, targetTag);
+    } finally {
+      rmSync(tmp.dir, { recursive: true, force: true });
+    }
+    s.stop(`Binário instalado em ${chalk.cyan(binPath)}.`);
+  }
+
+  // 5-7. Config, serviço e avisos (compartilhado com o --build).
+  await finishSetup({ cfg, home, binPath, configPath, options, configAction: items[1].action,
+                      servicePath: options.service ? items[2].path : null });
+}
+
+/** Config + serviço + avisos finais — comum a --install e --build. */
+async function finishSetup({ cfg, home, binPath, configPath, options, configAction, servicePath }) {
+  if (configAction === 'manter') {
+    p.log.info(`Config mantida: ${configPath} já existe (use --force para regerar).`);
+  } else if (existsSync(configPath) && !options.yes) {
+    const ok = await p.confirm({ message: `Sobrescrever ${configPath}?`, initialValue: false });
+    if (p.isCancel(ok) || !ok) {
+      p.log.info('Config mantida.');
+    } else {
+      mkdirSync(path.dirname(configPath), { recursive: true });
+      writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+      p.log.success(`Config regravada em ${configPath}.`);
+    }
+  } else {
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+    p.log.success(`Config criada em ${chalk.cyan(configPath)} (repo ${cfg.owner}/${cfg.repo}).`);
+  }
+
+  if (options.service && process.platform === 'win32') {
+    p.log.warn('--service não é suportado no Windows (sem systemd/launchd). Use `spec-wave dev-agent --run`.');
+  } else if (options.service && servicePath) {
+    const kind = process.platform === 'darwin' ? 'launchd' : 'systemd';
+    try {
+      installService({ kind, home, binPath, servicePath });
+      p.log.success(
+        kind === 'systemd'
+          ? 'Serviço systemd habilitado. Logs: journalctl --user -u spec-wave-agent -f'
+          : `Serviço launchd carregado. Logs: tail -f ${home}/Library/Logs/spec-wave-agent.log`
+      );
+    } catch (err) {
+      p.log.warn(`Falha ao configurar o serviço: ${err.message}`);
+    }
+  }
+
+  const binDir = path.dirname(binPath);
+  if (!isOnPath(binDir, process.env.PATH)) {
+    p.log.warn(`${binDir} não está no PATH. Adicione ao seu shell:\n  export PATH="${binDir}:$PATH"`);
+  }
+  let ghLogin = null;
+  try { ghLogin = sh('gh api user --jq .login'); } catch { /* best-effort */ }
+  if (ghLogin && cfg.owner && ghLogin.toLowerCase() !== cfg.owner.toLowerCase()) {
+    p.log.info(
+      `A conta ativa do gh é ${ghLogin} e o repo é de ${cfg.owner}. Se o agente não enxergar as issues, ` +
+      'exporte o token da conta certa:\n  export GH_TOKEN=$(gh auth token -u <sua-conta>)' +
+      (options.service ? '\n  (no serviço: systemctl --user edit spec-wave-agent → Environment=GH_TOKEN=...)' : '')
+    );
+  }
+
+  p.outro(
+    `${chalk.green('✓')} Agente pronto.\n` +
+    `  Rodar agora:  ${chalk.cyan('spec-wave dev-agent --run')}\n` +
+    '  Enfileirar:   aplique a label spec-wave:dev-agent numa issue [FEATURE] já decomposta.'
+  );
+}
+
+/**
+ * --build: clona (ou atualiza) o repo do agente e compila com cargo.
+ * Alternativa ao --install para plataformas sem binário publicado (Mac Intel,
+ * Linux arm64) ou para rodar o código mais recente da main.
+ */
+async function build(options) {
+  const cwd = process.cwd();
+  const home = homedir();
+  const binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  const configPath = path.join(home, AGENT_CONFIG);
+  const srcDir = path.join(home, SRC_DIR);
+
+  const { cfg, error } = readRepoConfig(cwd);
+  if (error) { p.log.error(error); process.exitCode = 1; return; }
+
+  const { problems, warnings } = preflight(cfg);
+  if (!has('cargo')) {
+    problems.push('cargo (Rust) não encontrado — instale com: curl https://sh.rustup.rs -sSf | sh');
+  }
+  for (const w of warnings) p.log.warn(w);
+  if (problems.length > 0) {
+    p.log.error(`Pré-requisitos faltando:\n  - ${problems.join('\n  - ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const ref = options.tag || 'main';
+  const items = planInstall({
+    binPath, binInstalled: existsSync(binPath), installedTag: null,
+    targetTag: `fonte:${ref}`, configPath, configExists: existsSync(configPath),
+    service: options.service ? (process.platform === 'darwin' ? 'launchd' : 'systemd') : null,
+    servicePath: process.platform === 'darwin'
+      ? path.join(home, 'Library', 'LaunchAgents', 'dev.specwave.agent.plist')
+      : path.join(home, '.config', 'systemd', 'user', 'spec-wave-agent.service'),
+    force: !!options.force,
+  });
+  p.note(`${renderInstallReport(items)}\n${chalk.dim(`fonte: ${srcDir} (${ref})`)}`, 'Plano de build');
+
+  if (options.dryRun) { p.outro('Dry-run: nada foi compilado.'); return; }
+
+  // 1. Clone ou atualização do fonte.
+  const s = p.spinner();
+  try {
+    if (!existsSync(path.join(srcDir, '.git'))) {
+      s.start(`Clonando ${AGENT_REPO}...`);
+      mkdirSync(path.dirname(srcDir), { recursive: true });
+      sh(`gh repo clone ${AGENT_REPO} "${srcDir}"`);
+    } else {
+      s.start('Atualizando o fonte...');
+      sh(`git -C "${srcDir}" fetch --all --tags --prune`);
+    }
+    sh(`git -C "${srcDir}" checkout --quiet ${ref}`);
+    // Branch (não tag): traz os commits novos.
+    try { sh(`git -C "${srcDir}" merge --ff-only "origin/${ref}"`); } catch { /* tag/detached: ok */ }
+    s.stop(`Fonte pronto em ${chalk.cyan(srcDir)} (${ref}).`);
+  } catch (err) {
+    s.stop('Falhou.');
+    const msg = String(err.stderr || err.message || '');
+    p.log.error(
+      /not found|Could not resolve|permission/i.test(msg)
+        ? `Não foi possível clonar ${AGENT_REPO} — verifique se a conta ativa do gh tem acesso ao repositório privado.`
+        : `Falha ao preparar o fonte: ${msg.trim() || err.message}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Build (demora: mostra a saída do cargo ao vivo).
+  p.log.step('Compilando com cargo (pode levar alguns minutos)...');
+  try {
+    execSync('cargo build --release', { cwd: srcDir, stdio: 'inherit' });
+  } catch (err) {
+    p.log.error(`cargo build falhou: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Instala o binário compilado.
+  const built = path.join(srcDir, 'target', 'release', BIN_NAME + exeSuffix(process.platform));
+  if (!existsSync(built)) {
+    p.log.error(`Binário não encontrado após o build: ${built}`);
+    process.exitCode = 1;
+    return;
+  }
+  mkdirSync(path.dirname(binPath), { recursive: true });
+  copyFileSync(built, binPath);
+  chmodSync(binPath, 0o755);
+  let sha = '';
+  try { sha = sh(`git -C "${srcDir}" rev-parse HEAD`); } catch { /* best-effort */ }
+  writeInstalledTag(home, sourceTag(ref, sha));
+  p.log.success(`Binário instalado em ${chalk.cyan(binPath)} (${sourceTag(ref, sha)}).`);
+
+  await finishSetup({ cfg, home, binPath, configPath, options, configAction: items[1].action,
+                      servicePath: options.service ? items[2].path : null });
+}
+
+function run(options) {
+  const home = homedir();
+  let binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  if (!existsSync(binPath)) {
+    try { binPath = sh(process.platform === 'win32' ? `where ${BIN_NAME}` : `command -v ${BIN_NAME}`).split(/\r?\n/)[0]; }
+    catch {
+      p.log.error('spec-wave-agent não encontrado. Rode `spec-wave dev-agent --install` primeiro.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const configPath = path.join(home, AGENT_CONFIG);
+  if (!existsSync(configPath)) {
+    p.log.error(`Config do agente não encontrada em ${configPath}. Rode \`spec-wave dev-agent --install\`.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.log.step(`Executando ${chalk.dim(binPath)} — Ctrl+C encerra com checkpoint.`);
+  p.outro('Logs do agente abaixo.');
+  try {
+    execSync(`"${binPath}"`, {
+      stdio: 'inherit',
+      env: { ...process.env, RUST_LOG: options.debug ? 'debug' : (process.env.RUST_LOG || 'info') },
+    });
+  } catch (err) {
+    // Ctrl+C (SIGINT/SIGTERM) é saída normal: o agente faz checkpoint e sai.
+    if (err.signal === 'SIGINT' || err.signal === 'SIGTERM') return;
+    p.log.error(`Agente encerrou com erro: ${err.message}`);
+    process.exitCode = typeof err.status === 'number' ? err.status : 1;
+  }
+}
+
+export async function devAgent(options = {}) {
+  const modes = ['install', 'build', 'run'].filter((m) => options[m]);
+  if (modes.length > 1) {
+    console.error(`Use apenas um modo por vez (recebido: ${modes.map((m) => `--${m}`).join(', ')}).`);
+    process.exitCode = 1;
+    return;
+  }
+  if (modes.length === 0) {
+    console.error(
+      'Nada a fazer. Use:\n' +
+      '  spec-wave dev-agent --install   instala o agente a partir da release\n' +
+      '  spec-wave dev-agent --build     clona o repo e compila localmente\n' +
+      '  spec-wave dev-agent --run       executa o agente em foreground'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  p.intro(chalk.bold(`spec-wave dev-agent --${modes[0]}`));
+  if (options.install) return install(options);
+  if (options.build) return build(options);
+  run(options);
+}

package/src/commands/doctor.mjs

@@ -11,6 +11,7 @@ import { Octokit } from '@octokit/rest';
 import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import { CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { DEFAULT_MAX_TOKENS } from '../lib/claude.mjs';
 
 // Mesmo padrão de instanciação de github-rest.mjs, mas com o logger mudo:
 // aqui 404/403 são resultados esperados dos checks, não erros a logar.
@@ -297,6 +298,16 @@ async function checkAi(ctx) {
   if (fileAi.models && Object.keys(fileAi.models).length > 0) {
     notes.push(`Modelos por ação (ai.models): ${Object.entries(fileAi.models).map(([a, m]) => `${a}=${m}`).join(', ')}.`);
   }
+  // Teto de saída: quando o documento não cabe, a geração falha com
+  // TruncatedOutputError em vez de gravar um arquivo cortado — mostrar o valor
+  // resolvido evita ter que abrir o log do Action para descobri-lo.
+  const maxTokensNote = fileAi.maxTokens
+    ? `${fileAi.maxTokens} (ai.maxTokens)`
+    : `${DEFAULT_MAX_TOKENS} (default)`;
+  const byAction = fileAi.maxTokensByAction && Object.keys(fileAi.maxTokensByAction).length > 0
+    ? ` · por ação: ${Object.entries(fileAi.maxTokensByAction).map(([a, t]) => `${a}=${t}`).join(', ')}`
+    : '';
+  notes.push(`Teto de saída: ${maxTokensNote}${byAction}.`);
 
   let status = 'ok';
   if (process.env[provider.secret]) {

package/src/commands/generate-plan.mjs

@@ -8,6 +8,7 @@ import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 
 // Aviso anexado ao comentário quando o lint de idioma ainda reprova após o
@@ -41,7 +42,7 @@ Regras OBRIGATÓRIAS:
 - Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
 - Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
 
-export async function generatePlan({ issueNumber }) {
+export async function generatePlan({ issueNumber, force = false }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -69,6 +70,11 @@ export async function generatePlan({ issueNumber }) {
     return;
   }
 
+  // Ver generate-spec: não há guard aqui — a label já regera e sobrescreve.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log('Modo forçado ativo — plan.md será regerado (sobrescreve o existente).');
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/plan.md`;
@@ -154,6 +160,20 @@ export async function generatePlan({ issueNumber }) {
     }
 
     console.log(`plan.md criado em: ${filePath}`);
+  } catch (err) {
+    // Mesmo beco sem saída do generate-spec: o gatilho é `issues: [labeled]`,
+    // então com a label ainda aplicada re-adicioná-la não dispara nada. Remove
+    // o gatilho e reporta na issue; o erro segue propagando.
+    // (O catch acima, na crítica adversarial, cobre só aquele trecho.)
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan').catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `❌ **Falha ao gerar o plan.md**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`spec-wave:plan\` foi removida para destravar o gatilho — ` +
+      `adicione-a de novo para tentar outra vez.`
+    ).catch(() => {});
+    throw err;
   } finally {
     // Best-effort: nunca propaga erro (ver recordUsage).
     await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });