@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

package/src/commands/e2e/e2e.js

@@ -42,9 +42,13 @@ import {
 import { isSecondaryWorktree } from '../../../framework/hooks/shared/git-paths.js';
 import { buildComposeEnv } from '../../lib/e2e/compose-env.js';
 import { findWorktreeForFeature, resolvePrimaryRoot } from '../project/worktree.js';
+import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
+import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 
 /** Exit code for a usage error, matching `verify`'s convention. */
 const EXIT_USAGE = 2;
+const EXIT_BUSY = 3;
 
 // ============================================================================
 // Shared context
@@ -158,13 +162,27 @@ export async function e2eUpCommand(featureName, options = {}) {
     process.exit(EXIT_USAGE);
   }
 
-  const result = bringUpStack(ctx.cwd, {
-    composeFile: ctx.composeFile,
-    projectName: ctx.projectName,
-    gitCommonDir: ctx.gitCommonDir,
-    env: ctx.env,
-    forceFresh: Boolean(options.fresh),
-  });
+  const gate = createHeavyGate({ projectPath: ctx.cwd, label: 'e2e up', feature: featureName });
+  let result;
+  try {
+    gate.enter('e2e');
+    result = bringUpStack(ctx.cwd, {
+      composeFile: ctx.composeFile,
+      projectName: ctx.projectName,
+      gitCommonDir: ctx.gitCommonDir,
+      env: ctx.env,
+      forceFresh: Boolean(options.fresh),
+    });
+  } catch (err) {
+    if (!(err instanceof HeavyBusyError)) throw err;
+    if (options.json) {
+      console.log(JSON.stringify({ status: 'busy', feature: featureName, busy: { reason: err.reason, waitedMs: err.waitedMs } }, null, 2));
+    }
+    console.error(chalk.yellow(`\n⏳ e2e up não rodou: ${err.message}. Tente de novo quando liberar (\`morph-spec heavy status\`).\n`));
+    process.exit(EXIT_BUSY);
+  } finally {
+    gate.release();
+  }
 
   const auth =
     result.status === 'pass'
@@ -313,10 +331,11 @@ export async function e2eDownCommand(featureName, options = {}) {
     volumes: Boolean(options.volumes),
   });
   const stampDeleted = deleteStamp(ctx.gitCommonDir, ctx.projectName);
+  const cleanup = afterHeavyRun({ projectPath: ctx.cwd, config: readHeavyConfig(ctx.cwd), scope: 'e2e-down' });
 
   if (options.json) {
     console.log(JSON.stringify(
-      { feature: featureName, project: ctx.projectName, tree: ctx.tree, status: result.status, stampDeleted },
+      { feature: featureName, project: ctx.projectName, tree: ctx.tree, status: result.status, stampDeleted, cleanup },
       null, 2,
     ));
   } else if (result.status === 'pass') {

package/src/commands/mcp/mcp-setup.js

@@ -100,13 +100,14 @@ export async function mcpSetupCommand(name, options) {
     const integrations = await detectIntegrations(targetPath);
     const claudeConfig = await detectClaudeConfig(targetPath);
     const existingMcps = claudeConfig.mcpServers || [];
+    const enabledPlugins = claudeConfig.enabledPlugins || [];
 
     if (options.list) {
-      return showStatusList(targetPath, stack, existingMcps, integrations);
+      return showStatusList(targetPath, stack, existingMcps, integrations, enabledPlugins);
     }
 
     if (options.auto) {
-      return autoInstall(targetPath, stack, existingMcps, integrations);
+      return autoInstall(targetPath, stack, existingMcps, integrations, enabledPlugins);
     }
 
     if (name) {
@@ -114,7 +115,7 @@ export async function mcpSetupCommand(name, options) {
     }
 
     // Interactive wizard
-    return interactiveWizard(targetPath, stack, existingMcps, integrations);
+    return interactiveWizard(targetPath, stack, existingMcps, integrations, enabledPlugins);
   } catch (err) {
     console.error(chalk.red(`Error: ${err.message}`));
     process.exit(1);
@@ -124,8 +125,8 @@ export async function mcpSetupCommand(name, options) {
 /**
  * Show MCP status list (--list)
  */
-async function showStatusList(targetPath, stack, existingMcps, integrations) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations });
+async function showStatusList(targetPath, stack, existingMcps, integrations, enabledPlugins) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations, enabledPlugins });
   const statusRows = formatMcpStatusTable(orchestration, {});
 
   console.log(chalk.cyan('\n  MCP Server Status\n'));
@@ -158,8 +159,8 @@ async function showStatusList(targetPath, stack, existingMcps, integrations) {
 /**
  * Auto-install credential-free MCPs (--auto)
  */
-async function autoInstall(targetPath, stack, existingMcps, integrations) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { autoOnly: true, integrations });
+async function autoInstall(targetPath, stack, existingMcps, integrations, enabledPlugins) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { autoOnly: true, integrations, enabledPlugins });
   const autoNames = Object.keys(orchestration.autoInstallable);
 
   if (autoNames.length === 0) {
@@ -419,8 +420,8 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
 /**
  * Interactive wizard showing all MCPs
  */
-async function interactiveWizard(targetPath, stack, existingMcps, integrations) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations });
+async function interactiveWizard(targetPath, stack, existingMcps, integrations, enabledPlugins) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations, enabledPlugins });
 
   console.log(chalk.cyan('\n  MCP Setup Wizard'));
   console.log(chalk.gray(`  Stack: ${stack}`));

package/src/commands/project/doctor-procs.js

@@ -0,0 +1,162 @@
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { listProcesses } from '../../lib/procs/list.js';
+import { classifyProcs } from '../../lib/procs/classify.js';
+import { readMcpConfig, findDuplicateMcps, mcpCommandTokens } from '../../lib/procs/mcp-config.js';
+import { inspectWslConfig } from '../../lib/procs/wslconfig.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { heavyDir, heavyStatus } from '../../../framework/hooks/shared/heavy-holders.js';
+
+function readHolderPids(targetPath) {
+  try {
+    const config = readHeavyConfig(targetPath);
+    const { holders } = heavyStatus({ dir: heavyDir(), maxHoldMs: config.maxHoldMinutes * 60_000 });
+    return holders.map((h) => h.pid).filter(Number.isInteger);
+  } catch {
+    return [];
+  }
+}
+
+export function formatAge(ms) {
+  if (ms === null) return '?';
+  const min = Math.floor(ms / 60000);
+  if (min < 60) return `${min}min`;
+  const h = Math.floor(min / 60);
+  if (h < 48) return `${h}h${String(min % 60).padStart(2, '0')}`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+const VERDICT_TEXT = {
+  orphan: 'órfão — `--prune` encerra por PID',
+  protected: 'protegido',
+  'build-server': 'nó de build',
+};
+
+export function collectProcsReport(targetPath, deps = {}) {
+  const d = { listProcesses, readMcpConfig, inspectWslConfig, now: Date.now(), ...deps };
+  d.holderPids ??= readHolderPids(targetPath);
+  const listing = d.listProcesses();
+  const mcp = d.readMcpConfig({ projectDir: targetPath });
+
+  let procs;
+  let vmmemMb = 0;
+  if (listing.procs === null) {
+    procs = { status: 'skip', reason: listing.reason };
+  } else {
+    const { rows, sessions } = classifyProcs(listing.procs, {
+      now: d.now,
+      mcpTokens: mcpCommandTokens(mcp),
+      holderPids: d.holderPids,
+    });
+    procs = { status: 'ok', sessions, total: rows.length, rows };
+    const vmmem = listing.procs.filter((p) => p.name.startsWith('vmmem')).reduce((sum, p) => sum + p.rss, 0);
+    vmmemMb = Math.round(vmmem / (1024 * 1024));
+  }
+
+  return {
+    procs,
+    mcp: {
+      duplicates: findDuplicateMcps(mcp),
+      unreadable: mcp.unreadable,
+      servers: mcp.servers.length,
+      pluginServers: mcp.pluginServers.length,
+    },
+    wsl: { ...d.inspectWslConfig(), vmmemMb },
+  };
+}
+
+function renderProcs(procs) {
+  if (procs.status === 'skip') {
+    console.log(chalk.gray(`  ○ Processos — não verificado: ${procs.reason}`));
+    return;
+  }
+  const orphans = procs.rows.filter((r) => r.orphan);
+  console.log(`  ${chalk.bold('Processos')} — ${procs.total} candidato(s) (node, dotnet, testhost, esbuild, chrome headless), `
+    + `${procs.total - orphans.length} com pai vivo, ${orphans.length} sem pai; ${procs.sessions} sessão(ões) do Claude viva(s)`);
+  if (!orphans.length) {
+    console.log(chalk.green('  ✓ nenhum processo órfão'));
+    return;
+  }
+  for (const r of orphans) {
+    const label = VERDICT_TEXT[r.verdict] ?? r.verdict;
+    const mark = r.verdict === 'orphan' ? chalk.yellow('  ⚠') : chalk.gray('  ○');
+    console.log(`${mark} pid ${r.pid} ${r.name} ${r.rssMb} MB, ${formatAge(r.ageMs)} — ${label}${r.reason ? `: ${r.reason}` : ''}`);
+    if (r.cmd) console.log(chalk.gray(`      ${r.cmd.length > 110 ? `${r.cmd.slice(0, 107)}...` : r.cmd}`));
+  }
+}
+
+function renderMcp(mcp) {
+  console.log(`  ${chalk.bold('MCP duplicado')} — ${mcp.servers} servidor(es) de configuração, ${mcp.pluginServers} de plugin`);
+  if (!mcp.duplicates.length) console.log(chalk.green('  ✓ nenhum MCP declarado no projeto e também entregue por plugin'));
+  for (const dup of mcp.duplicates) {
+    console.log(chalk.yellow(`  ⚠ ${dup.server}: declarado em ${dup.declaredIn.join(', ')} e entregue pelo plugin ${dup.plugin} — sobem 2 processos`));
+    console.log(chalk.gray(`      tools: ${dup.toolNames.join(' e ')}`));
+    console.log(chalk.gray(`      conserto (só sugestão): remova "${dup.server}" do .mcp.json, ou desligue o plugin ${dup.plugin}`));
+  }
+  for (const file of mcp.unreadable) console.log(chalk.gray(`  ○ não verificado: ${file} (ilegível)`));
+}
+
+function renderWsl(wsl) {
+  if (wsl.status === 'skip') {
+    console.log(chalk.gray(`  ○ WSL — não verificado: ${wsl.reason}`));
+    return;
+  }
+  const held = wsl.vmmemMb > 0 ? ` (vmmem segura ${wsl.vmmemMb} MB agora)` : '';
+  if (wsl.status === 'missing') console.log(chalk.yellow(`  ⚠ WSL — ${wsl.path} ausente${held}`));
+  else if (wsl.suggestion) console.log(chalk.yellow(`  ⚠ WSL — ${wsl.path} sem limite de memória ou sem devolução gradual${held}`));
+  else console.log(chalk.green(`  ✓ WSL — ${wsl.path} com memory=${wsl.memory} e autoMemoryReclaim=${wsl.autoMemoryReclaim}`));
+  if (wsl.suggestion) {
+    console.log(chalk.gray('      conserto (só sugestão; o morph-spec não escreve fora do repo), acrescente a esse arquivo:'));
+    for (const line of wsl.suggestion.split('\n')) console.log(chalk.gray(`        ${line}`));
+    console.log(chalk.gray('      depois rode `wsl --shutdown` para o WSL reler o arquivo'));
+  }
+}
+
+function renderPrune(results) {
+  console.log(`  ${chalk.bold('Poda')}`);
+  if (!results.length) {
+    console.log(chalk.green('  ✓ nada a podar'));
+    return;
+  }
+  for (const r of results) {
+    const line = `pid ${r.pid} ${r.name}${r.reason ? ` — ${r.reason}` : ''}`;
+    if (r.outcome === 'killed') console.log(chalk.green(`  ✓ encerrado: ${line}`));
+    else if (r.outcome === 'skipped') console.log(chalk.gray(`  ○ pulado: ${line}`));
+    else console.log(chalk.red(`  ✗ falhou: ${line}`));
+  }
+}
+
+export async function doctorProcsCommand(targetPath, options = {}) {
+  const report = collectProcsReport(targetPath, options.deps);
+
+  if (options.prune) {
+    const { pruneOrphans } = await import('../../lib/procs/prune.js');
+    const { afterHeavyRun } = await import('../../lib/heavy/cleanup.js');
+    report.prune = report.procs.status === 'ok' ? pruneOrphans(report.procs.rows, options.pruneDeps) : [];
+    report.buildServer = afterHeavyRun({
+      projectPath: targetPath, config: readHeavyConfig(targetPath), scope: 'prune', deps: options.cleanupDeps,
+    });
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    logger.header(options.prune ? 'Processos e memória (com --prune)' : 'Processos e memória (somente leitura)');
+    renderProcs(report.procs);
+    logger.blank();
+    renderMcp(report.mcp);
+    logger.blank();
+    renderWsl(report.wsl);
+    if (report.prune) {
+      logger.blank();
+      renderPrune(report.prune);
+      const bs = report.buildServer;
+      const mark = bs.status === 'ran' ? chalk.green('✓') : bs.status === 'failed' ? chalk.red('✗') : chalk.gray('○');
+      console.log(`  ${mark} nós de build (dotnet build-server shutdown): ${bs.status}${bs.reason ? ` — ${bs.reason}` : ''}`);
+    }
+    logger.blank();
+  }
+
+  process.exitCode = report.prune?.some((r) => r.outcome === 'failed') ? 1 : 0;
+  return report;
+}

package/src/commands/project/doctor.js

@@ -725,7 +725,24 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
       }
     }
 
+    const { reapAgentWorktrees } = await import('../../lib/worktree/agent-reaper.js');
+    const reap = await reapAgentWorktrees(targetPath);
+    if (reap.ok) {
+      const gone = reap.reaped.map((r) => r.path ?? r.branch);
+      prune.agentReap = { reaped: gone, branchesDeleted: reap.branchesDeleted, preserved: reap.preserved, ...(reap.busy ? { busy: true } : {}) };
+      if (!options.json && gone.length) logger.success(`sobras de sub-agent removidas: ${gone.join(', ')}`);
+      if (!options.json && reap.busy) logger.warn('reaper de sub-agent já em execução em outro processo; nada foi feito nesta rodada');
+    }
+
     const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { applyEditorSettings } = await import('../../lib/worktree/vscode-settings.js');
+    const editor = applyEditorSettings(resolvePrimaryRoot(targetPath));
+    if (editor.status !== 'off') {
+      prune.editorSettings = editor;
+      if (!options.json && editor.status === 'write') logger.success(`.vscode/settings.json: ${editor.added.length} exclusão(ões) de worktree adicionada(s)`);
+      if (!options.json && editor.status === 'suggest') logger.warn(`.vscode/settings.json não foi alterado (${editor.reason}); cole isto nele:\n${editor.snippet}`);
+    }
+
     const { applyBackupRetention, summarizeRetention } = await import('../../lib/worktree/finish-backup.js');
     // The explicit prune is the one that reaches the backups written before the
     // retention existed (no manifest): the automatic one never touches them.
@@ -788,6 +805,9 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   if (problems.some(prunable) && !options.prune) {
     logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos e os diretórios vazios.');
   }
+  if (issues.some((i) => i.type === 'agent-worktree-leftover' && i.reapable) && !options.prune) {
+    logger.dim('\n  Rode `morph-spec worktree reap` (ou `doctor --worktrees --prune`) para remover as sobras de sub-agent que já pararam.');
+  }
   if (!problems.length) {
     logger.success('Nenhuma inconsistência — os itens acima são informativos.');
     return true;
@@ -932,25 +952,38 @@ export async function doctorAiCommand(targetPath, options = {}) {
 }
 
 export async function doctorCommand(options = {}) {
-  // `--json` and `--prune` only mean something under `--worktrees`. Falling
+  // `--json` and `--prune` only mean something under `--worktrees` or `--procs`. Falling
   // through to the human health check would hand a script a banner and a table
   // where it asked for JSON — a caller has no way to notice a flag that was
   // dropped in silence, so refuse instead of pretending.
   const scoped = ['json', 'prune'].filter((f) => options[f]);
-  if (scoped.length && !options.worktrees) {
+  if (scoped.length && !options.worktrees && !options.procs) {
     const flags = scoped.map((f) => `--${f}`).join(' e ');
-    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\`.`);
+    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\` ou \`morph-spec doctor --procs\`.`);
     logger.dim(`  Rode: morph-spec doctor --worktrees ${scoped.map((f) => `--${f}`).join(' ')}`);
     process.exitCode = 1;
     return false;
   }
 
+  // `--prune` é uma flag só e poda coisas diferentes em cada modo; juntar os dois
+  // modos faria as duas podas destrutivas rodarem sob um único pedido.
+  if (options.procs) {
+    const conflicts = ['full', 'mcp', 'worktrees', 'reset'].filter((f) => options[f]);
+    if (conflicts.length) {
+      const flags = conflicts.map((f) => `--${f}`).join(' e ');
+      logger.error(`--procs não se combina com ${flags} — cada superfície tem o seu relatório, o seu código de saída e a sua poda.`);
+      logger.dim('  Rode: morph-spec doctor --procs');
+      process.exitCode = 1;
+      return false;
+    }
+  }
+
   // `--ai` é superfície própria (D1). Combiná-la com outra superfície pediria
   // dois relatórios com dois códigos de saída no mesmo processo — o segundo
   // apagaria o primeiro em silêncio. Mesmo molde da guarda acima: recusa em
   // vez de fingir.
   if (options.ai) {
-    const conflicts = ['full', 'mcp', 'worktrees'].filter((f) => options[f]);
+    const conflicts = ['full', 'mcp', 'worktrees', 'procs'].filter((f) => options[f]);
     if (conflicts.length) {
       const flags = conflicts.map((f) => `--${f}`).join(' e ');
       logger.error(`--ai não se combina com ${flags} — cada superfície tem o seu relatório e o seu código de saída.`);
@@ -1011,6 +1044,11 @@ export async function doctorCommand(options = {}) {
     return clean;
   }
 
+  if (options.procs) {
+    const { doctorProcsCommand } = await import('./doctor-procs.js');
+    return doctorProcsCommand(process.cwd(), options);
+  }
+
   const targetPath = process.cwd();
 
   logger.header('MORPH-SPEC Health Check');

package/src/commands/project/heavy.js

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
+import { describeHolder, heavyDir, heavyStatus } from '../../../framework/hooks/shared/heavy-slots.js';
+
+const EXIT_BUSY = 3;
+const NEEDS_CMD_SHIM = /^(npm|npx|pnpm|yarn)$/;
+
+export function heavyStatusCommand(options = {}) {
+  const config = readHeavyConfig(process.cwd());
+  const status = heavyStatus({ dir: heavyDir(), maxHoldMs: config.maxHoldMinutes * 60_000 });
+  const report = {
+    enabled: config.enabled,
+    slots: config.slots,
+    minFreeMemGb: config.minFreeMemGb,
+    dir: status.dir,
+    freeGb: Number(status.freeGb.toFixed(2)),
+    holders: status.holders.map(({ pid, label, feature, node, cwd, since, leaseId }) => ({ pid, label, feature, node, cwd, since, ...(leaseId ? { leaseId } : {}) })),
+    exclusive: status.exclusive ? { pid: status.exclusive.pid, label: status.exclusive.label, since: status.exclusive.since } : null,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  logger.header('Slots de nós pesados (build, testes, e2e)');
+  if (!config.enabled) console.log(chalk.yellow('  ⚠ semáforo desligado (heavy.enabled: false ou MORPH_HEAVY=off)'));
+  console.log(chalk.gray(`  diretório: ${report.dir}`));
+  const memMark = report.freeGb < config.minFreeMemGb ? chalk.yellow('⚠') : chalk.green('✓');
+  console.log(`  ${memMark} RAM livre: ${report.freeGb.toFixed(1)} GB (mínimo ${config.minFreeMemGb} GB)`);
+  console.log(`  slots em uso: ${status.holders.length}/${config.slots}`);
+  for (const h of status.holders) console.log(chalk.gray(`    • ${describeHolder(h)}${h.cwd ? ` — ${h.cwd}` : ''}`));
+  if (status.exclusive) console.log(chalk.yellow(`  ⚠ limpeza do servidor de build em curso (${describeHolder(status.exclusive)})`));
+  logger.blank();
+  return report;
+}
+
+export function heavyRunCommand(command, options = {}) {
+  const [file, ...args] = command;
+  const gate = createHeavyGate({ projectPath: process.cwd(), label: options.label ?? 'run' });
+  try {
+    gate.enter(file);
+  } catch (err) {
+    if (!(err instanceof HeavyBusyError)) throw err;
+    console.error(chalk.yellow(`\n⏳ ${file} não rodou: ${err.message}. Tente de novo quando liberar (\`morph-spec heavy status\`).\n`));
+    process.exit(EXIT_BUSY);
+  }
+
+  const exe = process.platform === 'win32' && NEEDS_CMD_SHIM.test(file) ? `${file}.cmd` : file;
+  const res = spawnSync(exe, args, { stdio: 'inherit', shell: exe.endsWith('.cmd') });
+  gate.release();
+
+  if (res.error) {
+    console.error(chalk.red(`\n❌ não consegui executar ${file}: ${res.error.message}\n`));
+    process.exit(127);
+  }
+  process.exit(res.status ?? 1);
+}

package/src/commands/project/init.js

@@ -288,7 +288,7 @@ export async function initCommand(options) {
         spinner.stop();
         const existingMcps = claudeConfigDetected?.mcpServers || [];
         const orchestration = orchestrateMcpSetup(targetPath, detectedStack, existingMcps,
-          { integrations: config.project?.integrations ?? [] });
+          { integrations: config.project?.integrations ?? [], enabledPlugins: claudeConfigDetected?.enabledPlugins ?? [] });
 
         const autoNames = Object.keys(orchestration.autoInstallable);
         const manualNames = Object.keys(orchestration.needsManualSetup);

package/src/commands/project/update.js

@@ -33,6 +33,7 @@ import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
 import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 import { createEffects } from '../../lib/installers/effects.js';
+import { applyEditorSettings } from '../../lib/worktree/vscode-settings.js';
 import { registerProject } from '../../lib/projects/registry.js';
 import {
   writeGraphifyignore, describeOutdatedIgnore, graphifyignoreTracked,
@@ -729,6 +730,9 @@ export async function updateCommand(options = {}) {
     await updateGitignore(targetPath, fx);
     await ensureGitattributes(targetPath, fx);
 
+    updateSpinner.text = 'Editor excludes for worktrees (.vscode/settings.json)...';
+    try { applyEditorSettings(targetPath, { fx }); } catch { /* fail-open */ }
+
     // Migration: a .graphifyignore the previous version generated and nobody
     // edited is swapped for the current one when its RULES change (test doubles
     // and fixtures back in the graph — a header-only difference is left alone);

package/src/commands/project/worktree-reap.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import { reapAgentWorktrees } from '../../lib/worktree/agent-reaper.js';
+
+const label = (item) => item.path ?? item.branch ?? item.hex;
+
+function printReport(out) {
+  const mode = out.dryRun ? ' (simulação)' : '';
+  console.log(chalk.bold(`\nWorktrees de sub-agent${mode} — graça de ${out.graceMinutes} min\n`));
+  if (out.busy) console.log(chalk.yellow('  ⏳ outro reaper está em execução; nada foi feito\n'));
+
+  for (const item of out.wouldReap ?? []) console.log(chalk.cyan(`  → removeria: ${label(item)}`));
+  for (const item of out.reaped) console.log(chalk.green(`  ✓ removido: ${label(item)}${item.backup ? chalk.gray(` (backup: ${item.backup})`) : ''}`));
+  for (const item of out.preserved) {
+    console.log(chalk.yellow(`  ⚠ preservado: ${label(item)} — ${item.reason}${item.detail ? `: ${item.detail}` : ''}`));
+  }
+  if (out.active) console.log(chalk.gray(`  ${out.active} agente(s) ainda ativo(s), intocado(s)`));
+  const nothing = !out.reaped.length && !out.preserved.length && !out.active && !(out.wouldReap ?? []).length;
+  if (nothing && !out.busy) console.log(chalk.green('  ✓ nenhuma worktree de sub-agent sobrando'));
+  console.log();
+}
+
+export async function worktreeReapCommand(options = {}) {
+  const grace = options.grace === undefined ? undefined : Number(options.grace);
+  if (grace !== undefined && !(Number.isFinite(grace) && grace >= 0)) {
+    console.error(chalk.red(`--grace precisa ser um número de minutos >= 0 (recebi "${options.grace}")`));
+    process.exit(2);
+  }
+
+  const out = await reapAgentWorktrees(options.cwd || process.cwd(), { dryRun: options.dryRun === true, graceMinutes: grace });
+  if (options.json) console.log(JSON.stringify(out));
+  else if (out.ok) printReport(out);
+  else console.log(chalk.gray(`  fora de um repositório git — nada a fazer (${out.error})`));
+  return out;
+}