@polymorphism-tech/morph-spec 8.42.0 → 8.43.0

package/src/commands/validation/mutate.js

@@ -0,0 +1,200 @@
+import chalk from 'chalk';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveTestBuildTargets } from '../../lib/tasks/test-runner.js';
+import { dotnetTestMode } from '../../lib/tasks/dotnet-test-introspection.js';
+import { dotnetBuildCommands } from '../../lib/mutation/commands.js';
+import { resolveTestNodes } from '../../lib/tasks/test-nodes.js';
+import { changedPathsAgainst, detectDefaultBranch, getHeadSha } from '../../lib/git/default-branch.js';
+import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { BACKSLASH_TOKEN, ManifestError } from '../../lib/mutation/manifest.js';
+import { groupByNode, loadPlan } from '../../lib/mutation/plan.js';
+import { dotnetSubset, jsSubset, testProjectDirsOf } from '../../lib/mutation/subset.js';
+import { dotnetAdapter, genericAdapter, spawnExec } from '../../lib/mutation/adapters.js';
+import { runMutation } from '../../lib/mutation/runner.js';
+import { renderSection, summarize } from '../../lib/mutation/report.js';
+import { readJournal, restoreSnapshot } from '../../lib/mutation/snapshot.js';
+
+const EXIT = { ok: 0, failed: 1, usage: 2, busy: 3, unsafe: 4 };
+const KEEP_RUNS = 2;
+const DEFAULT_JOBS = 2;
+
+/**
+ * One heavy slot per worker: the first waits like any heavy node, the others
+ * are taken only if free right now. The run uses as many workers as it got,
+ * so a busy machine degrades to sequential instead of queueing.
+ */
+export function workerGate({ root, feature, jobs }) {
+  const config = readHeavyConfig(root);
+  const gates = [createHeavyGate({ projectPath: root, label: 'mutate', feature, config })];
+  const quiet = { ...config, waitTimeoutSec: 0, warnings: [] };
+  for (let i = 1; i < jobs; i++) {
+    const { MORPH_HEAVY_LEASE: _inherited, ...env } = process.env;
+    gates.push(createHeavyGate({ projectPath: root, label: 'mutate', feature, config: quiet, env }));
+  }
+  let acquired = 0;
+  return {
+    get jobs() { return acquired; },
+    enter(node) {
+      gates[0].enter(node);
+      acquired = 1;
+      for (const gate of gates.slice(1)) {
+        try { gate.enter(node); acquired += 1; } catch (err) {
+          if (!(err instanceof HeavyBusyError)) throw err;
+          break;
+        }
+      }
+    },
+    release() {
+      for (const gate of [...gates].reverse()) gate.release();
+      acquired = 0;
+    },
+  };
+}
+
+const gitOut = (cwd, args) => execFileSync('git', args, { cwd, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
+
+function workRoot(root) {
+  const common = resolveGitCommonDir(root);
+  return common ? join(common, 'morph-spec', 'mutation') : join(root, '.morph', 'tmp', 'mutation');
+}
+
+function pruneOldRuns(base, keep) {
+  if (!existsSync(base)) return;
+  const runs = readdirSync(base).sort();
+  for (const name of runs.slice(0, Math.max(0, runs.length - keep))) {
+    const done = ['g0', 'g1', 'g2', 'g3'].every((g) => {
+      const journal = readJournal(join(base, name, g, 'snapshot'));
+      return journal === null || journal.state === 'restored';
+    });
+    if (done) rmSync(join(base, name), { recursive: true, force: true });
+  }
+}
+
+function fail(message, code) {
+  console.error(chalk.red(message));
+  process.exitCode = code;
+  return null;
+}
+
+export function restoreLatest(root, out = console) {
+  const base = workRoot(root);
+  if (!existsSync(base)) { out.log('nada a restaurar: nenhuma rodada de mutação registrada'); return []; }
+  const restored = [];
+  for (const run of readdirSync(base).sort()) {
+    for (const group of readdirSync(join(base, run))) {
+      const journal = readJournal(join(base, run, group, 'snapshot'));
+      if (!journal || journal.state === 'restored') continue;
+      const report = restoreSnapshot(journal);
+      restored.push({ run, group, files: report });
+      out.log(`${run}/${group}: ${report.every((r) => r.ok) ? 'restaurado' : 'FALHOU'} — ${report.map((r) => `${r.file} ${r.ok ? 'ok' : 'md5 diverge'}`).join(', ')}`);
+    }
+  }
+  if (restored.length === 0) out.log('nada a restaurar: toda rodada registrada já foi restaurada');
+  return restored;
+}
+
+function subsetFor({ node, group, root, options }) {
+  if (options.subset === false) return { usable: false, reason: '--no-subset' };
+  const mutatedFiles = group.regions.map((r) => r.file);
+  if (node.runner === 'dotnet') {
+    const base = detectDefaultBranch(root);
+    const changed = base ? changedPathsAgainst(base, root) : [];
+    return dotnetSubset({ root, testProjectDirs: testProjectDirsOf(root, resolveTestBuildTargets(node)), mutatedFiles, changed });
+  }
+  return jsSubset({ runner: node.runner, command: node.command, root, mutatedFiles });
+}
+
+export async function mutateCommand(feature, options = {}) {
+  const root = resolve(options.cwd ?? process.cwd());
+  if (options.restore) { restoreLatest(root); return null; }
+
+  const planPath = resolve(root, options.plan ?? join('.morph', 'features', feature ?? '', '4-review', 'mutants.json'));
+  if (!existsSync(planPath)) return fail(`manifesto não encontrado: ${planPath}\nEscreva-o com a ferramenta Write, se você a tem; só com Bash, heredoc de delimitador entre aspas simples, com a barra invertida do código como ${BACKSLASH_TOKEN} — formato em .morph/framework/CLI.md, seção mutate.`, EXIT.usage);
+
+  let regions;
+  try {
+    regions = loadPlan({ root, planPath });
+  } catch (err) {
+    if (err instanceof ManifestError) return fail(err.message, EXIT.usage);
+    if (err instanceof SyntaxError) return fail(`${err.message}\nSe o manifesto tem barra invertida, o transporte do Bash pode tê-la alterado: escreva cada uma como ${BACKSLASH_TOKEN}, que a ferramenta expande.`, EXIT.usage);
+    throw err;
+  }
+
+  const { nodes } = resolveTestNodes(root);
+  const { groups, orphans } = groupByNode(regions, nodes, root);
+  if (orphans.length > 0) {
+    return fail(`nenhuma suíte declarada roda: ${orphans.map((o) => `${o.id} (${o.file})`).join(', ')}\nDeclare o nó em project.tests[] (.morph/config/config.json).`, EXIT.usage);
+  }
+  const mtp = groups.find((g) => g.node.runner === 'dotnet' && dotnetTestMode(resolve(root, g.node.cwd || '.')) === 'mtp');
+  if (mtp) return fail(`a suíte "${mtp.node.id}" roda no Microsoft.Testing.Platform (global.json): o TRX do VSTest, de onde o veredito e o motivo saem, não existe nela. Suporte a MTP ainda não há — rode a mutação com a suíte inteira à mão.`, EXIT.usage);
+  const uncompilable = groups.find((g) => g.node.runner === 'dotnet' && dotnetBuildCommands(g.node, root).length === 0);
+  if (uncompilable) return fail(`a suíte "${uncompilable.node.id}" não aponta nenhum .csproj (solution, ou nada): sem saber o que compilar, todo mutante rodaria sobre o binário antigo e sairia "sobrevivente". Declare o campo build no nó (config.json, project.tests[]).`, EXIT.usage);
+  const preDecided = groups.find((g) => g.node.status);
+  if (preDecided) return fail(`a suíte "${preDecided.node.id}" já vem decidida como ${preDecided.node.status}: ${preDecided.node.reason ?? ''}`, EXIT.usage);
+
+  if (!options.allowDirty) {
+    const dirty = gitOut(root, ['status', '--porcelain', '--', ...new Set(regions.map((r) => r.file))]).trim();
+    if (dirty) return fail(`há alteração não commitada nos arquivos a mutar:\n${dirty}\nCommite o fix ANTES de mutar (ou use --allow-dirty sabendo que o snapshot é o único caminho de volta).`, EXIT.usage);
+  }
+
+  const runId = `mut-${Date.now().toString(36)}`;
+  const base = workRoot(root);
+  pruneOldRuns(base, KEEP_RUNS);
+  const git = { porcelain: () => gitOut(root, ['status', '--porcelain', '--', '.', ':(exclude).morph']), head: () => getHeadSha(root) };
+  const jobs = Math.max(1, Number.isInteger(options.jobs) ? options.jobs : DEFAULT_JOBS);
+  const gate = workerGate({ root, feature: feature ?? null, jobs });
+  const exec = options.exec ?? spawnExec;
+
+  const merged = { wallMs: 0, mutants: [], timings: [], restore: { files: [], ok: true, treeClean: true }, binary: { proof: 'unavailable', projects: [] }, baseline: {}, method: { schemata: 0, rebuild: 0, subset: {} } };
+  const subsets = [];
+  try {
+    for (const [index, group] of groups.entries()) {
+      const workDir = join(base, runId, `g${index}`);
+      mkdirSync(workDir, { recursive: true });
+      const subset = subsetFor({ node: group.node, group, root, options });
+      subsets.push(subset);
+      const timeoutMs = options.timeoutMs ?? group.node.timeoutMs ?? 900_000;
+      const make = group.node.runner === 'dotnet' ? dotnetAdapter : genericAdapter;
+      const adapter = make({ node: group.node, root, workDir, exec, subset, timeoutMs });
+      const result = await runMutation({ root, node: group.node, regions: group.regions, workDir, runId, exec, adapter, gate, git, options: { timeoutMs, jobs }, log: (m) => options.json || console.error(chalk.gray(m)) });
+      merged.mutants.push(...result.mutants);
+      merged.timings.push(...result.timings);
+      merged.wallMs += result.wallMs;
+      merged.restore.files.push(...result.restore.files);
+      merged.restore.ok &&= result.restore.ok;
+      merged.restore.treeClean &&= result.restore.treeClean;
+      merged.restore.porcelainAfter = result.restore.porcelainAfter;
+      if (result.binary.proof !== 'unavailable') merged.binary = ['mismatch', 'unlocated'].includes(merged.binary.proof) ? merged.binary : result.binary;
+      merged.baseline = { ...merged.baseline, ...Object.fromEntries(Object.entries(result.baseline).filter(([, v]) => v)) };
+      merged.method.schemata += result.method.schemata;
+      merged.method.rebuild += result.method.rebuild;
+      merged.method.subset = result.method.subset;
+      merged.method.jobs = Math.max(merged.method.jobs ?? 1, result.method.jobs);
+    }
+  } catch (err) {
+    if (err instanceof HeavyBusyError) return fail(`suíte não rodou: ${err.message}. Tente de novo quando liberar (morph-spec heavy status).`, EXIT.busy);
+    if (err.code === 'baseline-build-failed') return fail(`${err.message}\n${String(err.output ?? '').split('\n').slice(-12).join('\n')}`, EXIT.failed);
+    throw err;
+  }
+
+  const order = new Map(regions.map((r, i) => [r.id, i]));
+  merged.mutants.sort((a, b) => order.get(a.id) - order.get(b.id));
+  const section = renderSection(merged, { head: git.head(), date: new Date().toISOString().slice(0, 10), subset: subsets[0] ?? null });
+  const outPath = resolve(root, options.out ?? join('.morph', 'features', feature ?? '_', '4-review', 'mutation-section.md'));
+  mkdirSync(join(outPath, '..'), { recursive: true });
+  writeFileSync(outPath, section);
+
+  const tally = summarize(merged);
+  if (options.json) console.log(JSON.stringify({ ...merged, tally, section: outPath }, null, 2));
+  else {
+    console.log(section);
+    console.log(chalk.gray(`seção gravada em ${outPath}`));
+    console.log(`${chalk.green(`${tally.killed} mortos`)} · ${tally.survived ? chalk.yellow(`${tally.survived} sobreviveram`) : '0 sobreviveram'} · ${tally['build-error']} não compilaram · ${tally.inconclusive} inconclusivos`);
+  }
+  if (!merged.restore.ok || ['mismatch', 'unlocated'].includes(merged.binary.proof) || !merged.restore.treeClean) process.exitCode = EXIT.unsafe;
+  return { ...merged, tally, section: outPath };
+}

package/src/commands/validation/verify.js

@@ -9,6 +9,9 @@ import { getHeadSha } from '../../lib/git/default-branch.js';
 import { EVAL_RUNNER } from '../../lib/tasks/eval-node.js';
 import { buildVerifyEvent, recordVerifyEvent, findRepeatedVerify } from '../../lib/telemetry/verify-event.js';
 import { treeFingerprint } from '../../lib/git/tree-fingerprint.js';
+import { HeavyBusyError } from '../../lib/heavy/gate.js';
+import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 
 /** ✓ pass · ✗ fail · – skip */
 function statusIcon(status) {
@@ -252,9 +255,27 @@ export async function verifyCommand(featureName, taskId, options = {}) {
       console.error(chalk.red(`\n❌ ${err.message}\n`));
       process.exit(2);
     }
+    // Ocupado não é veredito: nada foi verificado, então não há stamp nem
+    // evento, e o exit 3 diz "tente de novo", nunca "vermelho".
+    if (err instanceof HeavyBusyError) {
+      if (options.json) {
+        const holders = err.holders.map(({ pid, label, feature, node, since }) => ({ pid, label, feature, node, since }));
+        console.log(JSON.stringify({
+          status: 'busy', persisted: false, busy: { reason: err.reason, holders, freeGb: err.freeGb, waitedMs: err.waitedMs },
+        }, null, 2));
+      }
+      console.error(chalk.yellow(`\n⏳ verify não rodou: ${err.message}. Não é vermelho — tente de novo quando liberar (\`morph-spec heavy status\`).\n`));
+      process.exit(3);
+    }
     throw err;
   }
 
+  const cleanup = afterHeavyRun({
+    projectPath: process.cwd(),
+    config: readHeavyConfig(process.cwd()),
+    scope: taskId ? 'task' : 'feature',
+  });
+
   const scopeKey = taskId ? `taskVerifications.${taskId}` : 'verifications.feature';
   // `--record-baseline` is config maintenance, not gate evidence: it measures
   // the suite in order to write `expectedCount`. Persisting a `verification`
@@ -343,10 +364,14 @@ export async function verifyCommand(featureName, taskId, options = {}) {
   }
 
   if (options.json) {
-    const output = { ...result, persisted: persist, ...(persist ? {} : { reason }), repeatOf };
+    const output = { ...result, persisted: persist, ...(persist ? {} : { reason }), repeatOf, cleanup };
     console.log(JSON.stringify(output, null, 2));
   } else {
     console.log(formatVerifyResult(result));
+    if (cleanup.status !== 'skipped') {
+      const mark = cleanup.status === 'ran' ? chalk.green('✓') : chalk.yellow('⚠');
+      console.log(chalk.gray(`${mark} dotnet build-server shutdown: ${cleanup.status}${cleanup.reason ? ` (${cleanup.reason})` : ''}\n`));
+    }
     if (repeatOf) {
       console.log(chalk.yellow(`⚠️  Mesma árvore do verify de feature de ${repeatOf.ts} (${repeatOf.status}): nada mudou fora de .morph/ desde então. `
         + 'Esta rodada não prova nada novo — reuse o resultado anterior, a menos que o ambiente (Docker, banco, serviço externo) tenha mudado.\n'));

package/src/dashboard/scanner/features-scanner.js

@@ -26,7 +26,7 @@ import { GATE_PREREQ } from '../../core/state/gate-order.js';
 import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
 import { evaluatorVerdictFromText } from '../../lib/evaluator-report.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
-import { WORKTREE_DIR_NAMES } from '../../lib/worktree/dirs.js';
+import { containerDirs } from '../../../framework/hooks/shared/worktree-root.js';
 import { canonicalPath, isInside, readMorphConfig } from '../../lib/tasks/test-runner.js';
 import { isFinished } from './feature-status.js';
 
@@ -79,9 +79,9 @@ function collectLocations(projectDir) {
   for (const name of subdirs(rootFeatures)) {
     if (existsSync(join(rootFeatures, name, 'feature.json'))) slot(name).root = join(rootFeatures, name);
   }
-  for (const wtDirName of WORKTREE_DIR_NAMES) {
-    for (const wt of subdirs(join(projectDir, wtDirName))) {
-      const wtFeatures = join(projectDir, wtDirName, wt, '.morph', 'features');
+  for (const container of containerDirs(projectDir)) {
+    for (const wt of subdirs(container)) {
+      const wtFeatures = join(container, wt, '.morph', 'features');
       for (const name of subdirs(wtFeatures)) {
         if (existsSync(join(wtFeatures, name, 'feature.json'))) slot(name).worktrees.push(join(wtFeatures, name));
       }

package/src/dashboard/scanner/project-api.js

@@ -12,7 +12,7 @@ import { join } from 'path';
 import { existsSync, readdirSync } from 'fs';
 import { scanFeatures, readFeatureDetail, readFeatureFile } from './features-scanner.js';
 import { createEventStore, buildFeed, lastActivityByFeature, ALL_KINDS, DEFAULT_KINDS } from './activity-scanner.js';
-import { WORKTREE_DIR_NAMES } from '../../lib/worktree/dirs.js';
+import { containerDirs } from '../../../framework/hooks/shared/worktree-root.js';
 import { isFinished } from './feature-status.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
@@ -51,11 +51,11 @@ export function isMorphDataReload(path) {
  */
 export function watchTargets(projectDir) {
   const morphDirs = [join(projectDir, '.morph')];
-  for (const name of WORKTREE_DIR_NAMES) {
+  for (const container of containerDirs(projectDir)) {
     let entries = [];
-    try { entries = readdirSync(join(projectDir, name), { withFileTypes: true }); } catch { continue; }
+    try { entries = readdirSync(container, { withFileTypes: true }); } catch { continue; }
     for (const e of entries) {
-      if (e.isDirectory()) morphDirs.push(join(projectDir, name, e.name, '.morph'));
+      if (e.isDirectory()) morphDirs.push(join(container, e.name, '.morph'));
     }
   }
   const targets = [];

package/src/lib/detectors/claude-config-detector.js

@@ -11,21 +11,50 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
+/**
+ * Plugin ids (`name@marketplace`) that are switched ON. User settings first, then
+ * the project's; a later file overrides an earlier one, and `false` turns one off.
+ *
+ * @param {string} targetPath - Root path of the project
+ * @param {string} [home] - Home directory holding `.claude/settings.json`
+ * @returns {string[]}
+ */
+export function readEnabledPlugins(targetPath, home = homedir()) {
+  const merged = new Map();
+  const files = [
+    join(home, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.local.json'),
+  ];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    try {
+      const map = JSON.parse(readFileSync(file, 'utf8').replace(/^/, '')).enabledPlugins;
+      if (!map || typeof map !== 'object') continue;
+      for (const [id, on] of Object.entries(map)) merged.set(id, on === true);
+    } catch { /* invalid JSON */ }
+  }
+  return [...merged].filter(([, on]) => on).map(([id]) => id);
+}
+
 /**
  * Detect Claude Code configuration for a project.
  *
  * @param {string} targetPath - Root path of the project
- * @returns {{ plugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
+ * @returns {{ plugins: string[], enabledPlugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
  */
 export function detectClaudeConfig(targetPath) {
   const result = {
     plugins: [],
+    enabledPlugins: [],
     mcpServers: [],
     customSkills: [],
     customCommands: [],
     hooks: [],
   };
 
+  result.enabledPlugins = readEnabledPlugins(targetPath);
+
   const mcpJsonNames = new Set();
 
   try {

package/src/lib/heavy/cleanup.js

@@ -0,0 +1,70 @@
+import { readdirSync } from 'node:fs';
+import { getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
+import { listProcesses, defaultProcExec } from '../procs/list.js';
+import { readProjectConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { heavyDir, runExclusive } from '../../../framework/hooks/shared/heavy-slots.js';
+
+const DOTNET_ACTIVE = /\bdotnet(?:\.exe)?["']?\s+(?:build|test|publish|pack|msbuild|restore|run|watch|vstest)\b/i;
+const IDLE_WORKER = /\/nodemode:\d|vbcscompiler|razorserver/i;
+const SHUTDOWN_SCOPES = new Set(['feature', 'e2e-down', 'prune']);
+const SHUTDOWN_TIMEOUT_MS = 30_000;
+const TAIL_CHARS = 400;
+
+function hasDotnet(projectPath) {
+  const config = readProjectConfig(projectPath);
+  const stack = config?.project?.stack;
+  try {
+    if (stack && getBuildSteps(stack, { cwd: projectPath }).some((s) => /\bdotnet\b/.test(s.command))) return true;
+  } catch { /* stack sem passo de build */ }
+  try {
+    return readdirSync(projectPath).some((n) => /\.(sln|slnx|csproj)$/i.test(n));
+  } catch {
+    return false;
+  }
+}
+
+export function dotnetBusy(procs) {
+  return procs.some((p) => {
+    if (p.name === 'testhost') return true;
+    const cmd = p.cmd ?? '';
+    if (p.name === 'vbcscompiler' || IDLE_WORKER.test(cmd)) return false;
+    if (p.name === 'msbuild') return true;
+    return p.name === 'dotnet' && DOTNET_ACTIVE.test(cmd);
+  });
+}
+
+export function afterHeavyRun({ projectPath, config, scope, env = process.env, deps = {} }) {
+  const {
+    exec = defaultProcExec, list = listProcesses, dotnet = hasDotnet, exclusive = runExclusive,
+  } = deps;
+
+  if (!config.enabled) return { status: 'skipped', reason: 'semáforo desligado: sem ele nada prova que outra sessão não está compilando' };
+  if (!config.shutdownBuildServer) return { status: 'skipped', reason: 'desligado em heavy.shutdownBuildServer' };
+  if (!SHUTDOWN_SCOPES.has(scope)) {
+    return { status: 'skipped', reason: 'escopo de task: o servidor de compilação segue quente para a próxima task' };
+  }
+  if (!dotnet(projectPath)) return { status: 'skipped', reason: 'projeto sem .NET' };
+
+  const guarded = exclusive({
+    dir: heavyDir(env), label: 'build-server-shutdown', maxHoldMs: config.maxHoldMinutes * 60_000, env,
+  }, () => {
+    const listing = list();
+    if (listing.procs === null) return { status: 'skipped', reason: `não consegui listar processos (${listing.reason})` };
+    if (dotnetBusy(listing.procs)) return { status: 'skipped', reason: 'há dotnet build/test vivo fora do semáforo' };
+
+    const res = exec('dotnet', ['build-server', 'shutdown'], { timeout: SHUTDOWN_TIMEOUT_MS });
+    if (res.missing) return { status: 'skipped', reason: 'dotnet indisponível no PATH' };
+    if (res.code !== 0) {
+      return { status: 'failed', reason: `dotnet build-server shutdown saiu ${res.code}`, output: String(res.output ?? '').slice(-TAIL_CHARS) };
+    }
+    return { status: 'ran' };
+  });
+
+  if (!guarded.ran) {
+    const why = guarded.reason === 'holders'
+      ? 'outra sessão segura slot do semáforo pesado'
+      : `semáforo indisponível (${guarded.reason})`;
+    return { status: 'skipped', reason: why };
+  }
+  return guarded.result;
+}

package/src/lib/heavy/gate.js

@@ -0,0 +1,96 @@
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import {
+  acquireHeavy, describeBusy, heavyDir, releaseHeavy, updateLease,
+} from '../../../framework/hooks/shared/heavy-slots.js';
+
+export class HeavyBusyError extends Error {
+  constructor(result, config) {
+    super(HeavyBusyError.message(result, config));
+    this.name = 'HeavyBusyError';
+    this.code = 'heavy-busy';
+    this.reason = result.reason;
+    this.holders = result.holders;
+    this.freeGb = result.freeGb;
+    this.waitedMs = result.waitedMs;
+  }
+
+  static message(result, config) {
+    return describeBusy(result, config);
+  }
+}
+
+const NODE_REUSE_ENV = 'MSBUILDDISABLENODEREUSE';
+const LEASE_ENV = 'MORPH_HEAVY_LEASE';
+
+export function createHeavyGate({
+  projectPath, label = 'verify', feature = null, config = readHeavyConfig(projectPath),
+  env = process.env, deps = {}, log = (m) => process.stderr.write(`${m}\n`),
+} = {}) {
+  let entered = false;
+  let lease = null;
+  let waitedMs = 0;
+  let exitHandler = null;
+  let saved = null;
+
+  const restoreEnv = () => {
+    if (!saved) return;
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete env[key];
+      else env[key] = value;
+    }
+    saved = null;
+  };
+
+  const release = () => {
+    if (exitHandler) process.removeListener('exit', exitHandler);
+    exitHandler = null;
+    releaseHeavy(lease);
+    lease = null;
+    restoreEnv();
+    entered = false;
+  };
+
+  return {
+    config,
+    get waitedMs() { return waitedMs; },
+
+    enter(node) {
+      if (entered) {
+        updateLease(lease, { node });
+        return;
+      }
+      for (const warning of config.warnings ?? []) log(`heavy: ${warning}`);
+
+      if (config.enabled) {
+        const result = acquireHeavy({
+          dir: heavyDir(env),
+          slots: config.slots,
+          label,
+          feature,
+          node,
+          cwd: projectPath,
+          minFreeMemGb: config.minFreeMemGb,
+          waitTimeoutMs: config.waitTimeoutSec * 1000,
+          maxHoldMs: config.maxHoldMinutes * 60_000,
+          env,
+          log,
+          ...deps,
+        });
+        if (result.status === 'busy') throw new HeavyBusyError(result, config);
+        lease = result.lease;
+        waitedMs = result.waitedMs;
+      }
+
+      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV] };
+      if (config.disableNodeReuse) env[NODE_REUSE_ENV] = '1';
+      if (lease) env[LEASE_ENV] = String(process.pid);
+      entered = true;
+      if (lease) {
+        exitHandler = release;
+        process.once('exit', exitHandler);
+      }
+    },
+
+    release,
+  };
+}

package/src/lib/installers/mcp-installer.js

@@ -11,6 +11,7 @@ import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { homedir } from 'os';
 import { installMcpServers } from '../../utils/claude-settings-manager.js';
+import { mcpServerNames } from '../../utils/agents-installer.js';
 
 /**
  * Load the enhanced MCP registry (v3.0.0)
@@ -56,9 +57,11 @@ export function filterByStack(registry, stack, integrations = []) {
  * Match detected MCP servers against the registry
  * @param {Array} existingServers - From detectClaudeConfig().mcpServers
  * @param {Object} registry - MCP registry
+ * @param {string[]} [enabledPlugins] - From detectClaudeConfig().enabledPlugins. A plugin
+ *   that ships the server already runs it, and writing it to `.mcp.json` too starts it twice.
  * @returns {Object} Map of mcpName → { installed: true, source }
  */
-export function getInstalledMcps(existingServers, registry) {
+export function getInstalledMcps(existingServers, registry, enabledPlugins = []) {
   const installed = {};
   const registryNames = Object.keys(registry.mcps);
 
@@ -71,6 +74,15 @@ export function getInstalledMcps(existingServers, registry) {
     }
   }
 
+  const prefixes = enabledPlugins.map(id => `plugin_${String(id).split('@')[0].replace(/[^A-Za-z0-9_-]/g, '_')}_`);
+  for (const regName of registryNames) {
+    if (installed[regName]) continue;
+    const names = mcpServerNames(regName, registry.mcps[regName]);
+    if (names.some(n => prefixes.some(p => n.startsWith(p)))) {
+      installed[regName] = { installed: true, source: 'plugin' };
+    }
+  }
+
   return installed;
 }
 
@@ -597,12 +609,13 @@ export function generateSetupInstructions(name, mcpEntry) {
  * @param {Object} options
  * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
  * @param {string[]} [options.integrations] - `project.integrations`, matched like the stack
+ * @param {string[]} [options.enabledPlugins] - `detectClaudeConfig().enabledPlugins`
  * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
  */
 export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
   const registry = loadMcpRegistry();
   const relevant = filterByStack(registry, stack, options.integrations ?? []);
-  const installed = getInstalledMcps(existingMcps || [], registry);
+  const installed = getInstalledMcps(existingMcps || [], registry, options.enabledPlugins ?? []);
 
   const autoInstallable = {};
   const alreadyInstalled = {};

package/src/lib/mutation/adapters.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { dotnetBuildCommands, withFilter, withTrx, withoutBuild } from './commands.js';
+import { methodOf, parseTrx } from './trx.js';
+import { stripAnsi } from '../tasks/test-runner.js';
+
+const MAX_CAPTURE = 16 * 1024 * 1024;
+
+export function spawnExec(command, { cwd, env, timeoutMs }) {
+  return new Promise((done) => {
+    const start = Date.now();
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const child = spawn(command, { cwd, env, shell: true, windowsHide: true });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { if (stdout.length < MAX_CAPTURE) stdout += chunk; });
+    child.stderr.on('data', (chunk) => { if (stderr.length < MAX_CAPTURE) stderr += chunk; });
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    const finish = (status) => { clearTimeout(timer); done({ status, stdout, stderr, durationMs: Date.now() - start, timedOut }); };
+    child.on('error', (err) => { stderr += String(err.message); finish(null); });
+    child.on('close', (status) => finish(status));
+  });
+}
+
+const FAIL_LINE = /^\s*(?:FAIL|✗|×|✖|not ok)\b|AssertionError|Error:|Expected/i;
+
+function genericFailures(output) {
+  const lines = stripAnsi(output).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const first = lines.findIndex((l) => FAIL_LINE.test(l));
+  if (first === -1) return lines.slice(-3).map((l) => ({ name: l, message: '' }));
+  return [{ name: lines[first], message: lines.slice(first + 1, first + 3).join(' ⏎ ') }];
+}
+
+export function dotnetAdapter({ node, root, workDir, exec, subset, timeoutMs }) {
+  const cwd = resolve(root, node.cwd || '.');
+  const trxDir = join(workDir, 'trx');
+  mkdirSync(trxDir, { recursive: true });
+  const base = withoutBuild(node.command);
+  const filterOf = { subset: () => subset.filter, names: (filter) => filter };
+  const commandFor = (scope, label, filter) => withTrx(
+    scope === 'full' ? base : withFilter(base, filterOf[scope](filter)),
+    { dir: trxDir, name: `${label}.trx` },
+  );
+  const runTests = async ({ scope, label, env, filter }) => {
+    const trxPath = join(trxDir, `${label}.trx`);
+    const r = await exec(commandFor(scope, label, filter), { cwd, env, timeoutMs, label });
+    if (!existsSync(trxPath)) {
+      return { outcome: 'crash', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs, note: r.timedOut ? `timeout de ${timeoutMs} ms` : `sem TRX (exit ${r.status})` };
+    }
+    const t = parseTrx(readFileSync(trxPath, 'utf8'));
+    if (!t.parsed || t.aborted > 0 || /abort/i.test(t.runOutcome ?? '')) {
+      return { outcome: 'crash', executed: t.executed, total: t.total, failed: t.failed, failedTests: t.failedTests, durationMs: r.durationMs, note: 'a rodada foi abortada (testhost caiu ou estourou o tempo)' };
+    }
+    return { outcome: t.failed > 0 ? 'red' : 'green', executed: t.executed, total: t.total, failed: t.failed, failedTests: t.failedTests, durationMs: r.durationMs };
+  };
+  return {
+    kind: 'dotnet',
+    hasSubset: Boolean(subset?.usable),
+    buildCommands: dotnetBuildCommands(node, root),
+    cwd,
+    runTests,
+    reproduce: ({ names, label, env }) => runTests({
+      scope: 'names',
+      label,
+      env,
+      filter: [...new Set(names.map(methodOf))].map((n) => `FullyQualifiedName~${n}`).join('|'),
+    }),
+  };
+}
+
+export function genericAdapter({ node, root, exec, subset, timeoutMs }) {
+  const cwd = resolve(root, node.cwd || '.');
+  return {
+    kind: node.runner,
+    hasSubset: Boolean(subset?.usable),
+    buildCommands: [],
+    cwd,
+    async runTests({ scope, label, env }) {
+      const command = scope === 'subset' ? subset.command : node.command;
+      const r = await exec(command, { cwd, env, timeoutMs, label });
+      if (r.timedOut) return { outcome: 'crash', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs, note: `timeout de ${timeoutMs} ms` };
+      if (r.status === 0) return { outcome: 'green', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs };
+      const failedTests = genericFailures(`${r.stdout}\n${r.stderr}`);
+      return { outcome: 'red', executed: null, total: null, failed: failedTests.length, failedTests, durationMs: r.durationMs };
+    },
+  };
+}