@polymorphism-tech/morph-spec 8.41.0 → 8.43.0

package/src/commands/project/worktree.js

@@ -58,6 +58,21 @@ import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/ho
 // rationale documented there); re-exported here so existing importers and the
 // dependency-matrix row keep pointing at this file.
 import { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES } from '../../lib/worktree/dirs.js';
+import { applyEditorSettings } from '../../lib/worktree/vscode-settings.js';
+import { copyWorktreeIncludes } from '../../lib/worktree/worktree-include.js';
+import { containerDirs, externalContainer, newWorktreesDir } from '../../../framework/hooks/shared/worktree-root.js';
+
+/** Fail-open: the editor file is a convenience, never a reason a worktree is not created. */
+function rootAndEditorReport(root) {
+  const { warning } = externalContainer(root);
+  const worktreeRoot = warning ? { worktreeRootWarning: warning } : {};
+  try {
+    const report = applyEditorSettings(root);
+    return report.status === 'off' ? worktreeRoot : { ...worktreeRoot, editorSettings: report };
+  } catch {
+    return worktreeRoot;
+  }
+}
 export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES };
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
@@ -146,7 +161,8 @@ export function worktreeExists(worktreePath, cwd = process.cwd()) {
 export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   const normalizedCwd = cwd.replace(/\\/g, '/');
-  return `${normalizedCwd}/${WORKTREES_DIR}/${feature}${suffix}`;
+  const container = externalContainer(normalizedCwd).dir ?? `${normalizedCwd}/${WORKTREES_DIR}`;
+  return `${container}/${feature}${suffix}`;
 }
 
 /**
@@ -514,7 +530,7 @@ export async function runWorktreeSetup(feature, options = {}) {
     }
 
     // Create worktree directory parent if needed
-    const parentDir = join(cwd, WORKTREES_DIR);
+    const parentDir = newWorktreesDir(cwd);
     if (!existsSync(parentDir)) {
       mkdirSync(parentDir, { recursive: true });
     }
@@ -524,6 +540,7 @@ export async function runWorktreeSetup(feature, options = {}) {
 
     // Set up infrastructure junctions (node_modules, .claude, .morph/framework).
     setupInfraLinks(worktreePath, cwd);
+    const included = copyWorktreeIncludes(worktreePath, cwd);
 
     // Fleet env: allocate this feature's deterministic port block and write the
     // worktree-local manifest (.morph/worktree.env). Fail-open — a worktree
@@ -573,9 +590,11 @@ export async function runWorktreeSetup(feature, options = {}) {
       branch,
       branchedFrom,
       feature,
+      ...(included.length ? { worktreeInclude: included } : {}),
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       ...(graph.seeded ? { graph: 'seeded' } : {}),
+      ...rootAndEditorReport(resolvePrimaryRoot(cwd)),
       nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
     };
   } catch (err) {
@@ -699,13 +718,14 @@ export async function runWorktreeProvision(name, options = {}) {
       }
     }
 
-    const parentDir = join(root, WORKTREES_DIR);
+    const parentDir = newWorktreesDir(root);
     if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
 
     execFileSync('git', ['worktree', 'add', worktreePath, branch], { cwd: root, stdio: 'pipe' });
 
     setupInfraLinks(worktreePath, root);
     const envFiles = copyRootEnvFiles(worktreePath, root);
+    const included = copyWorktreeIncludes(worktreePath, root);
     // A tree born from `morph/<f>` works FOR that feature: MORPH_FEATURE says
     // so, while the port block stays the task's own (`task/<name>`).
     const forFeature = String(options.base || '').match(/^morph\/(.+)$/)?.[1] ?? null;
@@ -724,9 +744,11 @@ export async function runWorktreeProvision(name, options = {}) {
       name,
       ...(forFeature ? { feature: forFeature } : {}),
       ...(envFiles.length ? { envFiles } : {}),
+      ...(included.length ? { worktreeInclude: included } : {}),
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       ...(graph.seeded ? { graph: 'seeded' } : {}),
+      ...rootAndEditorReport(root),
     };
   } catch (err) {
     return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), name };
@@ -886,7 +908,7 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
  * Parse `git worktree list --porcelain` into structured entries.
  * Fail-open: returns `[]` on any git error (e.g. not a git repo).
  * @param {string} cwd
- * @returns {Array<{ path: string, branch: string|null, head: string|null }>}
+ * @returns {Array<{ path: string, branch: string|null, head: string|null, locked: boolean }>}
  */
 export function parseWorktreeList(cwd) {
   let output;
@@ -901,7 +923,9 @@ export function parseWorktreeList(cwd) {
   for (const line of output.split('\n')) {
     if (line.startsWith('worktree ')) {
       if (current) entries.push(current);
-      current = { path: line.slice('worktree '.length).trim().replace(/\\/g, '/'), branch: null, head: null };
+      current = { path: line.slice('worktree '.length).trim().replace(/\\/g, '/'), branch: null, head: null, locked: false };
+    } else if (/^locked(\s|$)/.test(line) && current) {
+      current.locked = true;
     } else if (line.startsWith('branch ') && current) {
       current.branch = line.slice('branch '.length).trim();
     } else if (line.startsWith('HEAD ') && current) {
@@ -937,8 +961,8 @@ export function findWorktreeForFeature(feature, root) {
 
   let match = entries.find((e) => e.branch === refName);
   if (!match) {
-    const guess = buildWorktreePath(feature, root).replace(/\\/g, '/');
-    match = entries.find((e) => e.path === guess);
+    const guesses = containerDirs(root).map((dir) => `${dir}/${feature}`);
+    match = entries.find((e) => guesses.includes(e.path));
   }
   if (!match) return null;
 
@@ -1388,6 +1412,12 @@ export function pickRemovalFailure(stderrs) {
  * `stamp` names the backup; `finish` passes the one it gave the shed, so both
  * folders of that finish count as one backup under the retention.
  *
+ * `relinkOnFailure` (the agent reaper) also restores the junctions when git
+ * FAILED, not only when we refused: the reaper removes trees on a schedule, and
+ * a lock that leaves a possibly-live agent without `.claude` kills its hooks.
+ * Off by default — a person retrying a failed removal by hand is what the
+ * unlinked state protects. A tree git already de-registered has nothing to link.
+ *
  * @param {string} worktreePath
  * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean, stamp?: string }} ctx
  * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
@@ -1395,7 +1425,7 @@ export function pickRemovalFailure(stderrs) {
  *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
  *   removalFailure: {kind: string, detail: string}|null }>}
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, stamp }) {
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, relinkOnFailure = false, stamp }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
   //
@@ -1463,7 +1493,8 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   // and the caller falls back to telling the user to run `worktree link --all`.
   const refused = !canRemove;
   let relinked = false;
-  if (refused && unlinked.length && existsSync(worktreePath)) {
+  const relinkAfterFailure = relinkOnFailure && !refused && !worktreeRemoved && !removalFailure?.alreadyDeregistered;
+  if ((refused || relinkAfterFailure) && unlinked.length && existsSync(worktreePath)) {
     try {
       setupInfraLinks(worktreePath, root);
       relinked = true;
@@ -1471,7 +1502,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   }
   // What the caller must tell the user about on the FAILURE path: the worktree
   // survived without its shared infra, on purpose.
-  const infraLeftUnlinked = (!worktreeRemoved && !refused) ? unlinked : [];
+  const infraLeftUnlinked = (!worktreeRemoved && !refused && !relinked) ? unlinked : [];
 
   // Every branch names `morph-spec worktree remove` and NEVER `git worktree
   // remove`. The raw command follows the junctions this function manages, and a
@@ -1508,8 +1539,14 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
               + (removalFailure.kind === 'in-use' ? ' — EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd nele)' : '')
               + `${removalFailure.detail ? ` (${removalFailure.detail})` : ''}. \`${removeCmd}\` não o alcança mais — o git não o conhece. Feche o que o usa, confira que está vazio e sem junction, e apague só o diretório (sem recursão)`
           : removalFailure?.kind === 'in-use'
-            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
-            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
+            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). `
+              + (relinked
+                ? `A infra compartilhada foi RESTAURADA — o worktree segue utilizável. Feche o que está usando o diretório e rode \`${removeCmd}\``
+                : `A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``)
+            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. `
+              + (relinked
+                ? `A infra compartilhada foi RESTAURADA — o worktree segue utilizável. Rode \`${removeCmd}\` para tentar de novo`
+                : `A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`);
 
   return {
     worktreeRemoved,
@@ -1580,8 +1617,9 @@ export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
 // ── remove ───────────────────────────────────────────────────────────────
 
 /**
- * Command handler for `morph-spec worktree remove <feature>` /
- * `morph-spec worktree remove --target <path>`.
+ * Non-exiting core of `morph-spec worktree remove <feature>` /
+ * `morph-spec worktree remove --target <path>` — returns `{ out, code }` instead
+ * of printing and exiting, so the agent reaper can call it in a loop.
  *
  * WHY THIS EXISTS: `teardownWorktree` — the only removal that drops the infra
  * junctions before letting git near the directory — used to be reachable ONLY
@@ -1600,13 +1638,14 @@ export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
  * closing a feature is still `morph-spec finish`.
  *
  * @param {string|undefined} featureArg
- * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, cwd?: string }} [options]
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, relinkOnFailure?: boolean, cwd?: string }} [options]
+ * @returns {Promise<{ out: object, code: 0|1 }>}
  */
-export async function worktreeRemoveCommand(featureArg, options = {}) {
+export async function runWorktreeRemove(featureArg, options = {}) {
   const cwdArg = options.cwd || process.cwd();
-  const emit = (obj, code) => { console.log(JSON.stringify(obj)); process.exit(code); };
+  const outcome = (out, code) => ({ out, code });
 
-  if (!isGitRepo(cwdArg)) emit({ removed: false, error: 'not-a-git-repo' }, 1);
+  if (!isGitRepo(cwdArg)) return outcome({ removed: false, error: 'not-a-git-repo' }, 1);
   const root = resolvePrimaryRoot(cwdArg);
 
   let worktreePath = null;
@@ -1623,11 +1662,11 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     // is the same path-traversal class already fixed in delete/archive.
     const entry = parseWorktreeList(root).find((e) => e.path === worktreePath);
     if (!entry) {
-      emit({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
+      return outcome({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
         hint: 'o path precisa ser um worktree registrado neste repo — confira `morph-spec worktree list`' }, 1);
     }
     if (worktreePath === root) {
-      emit({ removed: false, error: 'refuses-primary-root', path: worktreePath,
+      return outcome({ removed: false, error: 'refuses-primary-root', path: worktreePath,
         hint: 'a raiz primária nunca é removível por este comando' }, 1);
     }
     branch = entry.branch ? entry.branch.replace(/^refs\/heads\//, '') : null;
@@ -1640,12 +1679,12 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     }
   } else {
     if (!isValidFeatureName(feature)) {
-      emit({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
+      return outcome({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
         hint: 'informe <feature> (kebab-case) ou use --target <path>' }, 1);
     }
     const found = findWorktreeForFeature(feature, root);
     if (!found || found.path.replace(/\\/g, '/') === root) {
-      emit({ removed: false, error: 'no-worktree-for-feature', feature, root,
+      return outcome({ removed: false, error: 'no-worktree-for-feature', feature, root,
         hint: `nenhum worktree separado para "${feature}" — confira \`morph-spec worktree list\`` }, 1);
     }
     worktreePath = found.path;
@@ -1656,7 +1695,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // is MORE likely to hit it: the natural moment to run it is right after
   // working inside the worktree.
   if (cwdIsInsideWorktree(cwdArg, worktreePath)) {
-    emit({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
+    return outcome({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
       hint: `saia do worktree antes de removê-lo — o processo trava o próprio diretório de trabalho. Rode de novo a partir de "${root}"` }, 1);
   }
 
@@ -1666,7 +1705,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // refusal IS the deferral.
   if (sessionAnchoredInWorktree(worktreePath)) {
     const again = featureAddressable && feature ? `morph-spec worktree remove ${feature}` : `morph-spec worktree remove --target "${worktreePath}"`;
-    emit({ removed: false, error: 'session-anchored-in-worktree', path: worktreePath, root,
+    return outcome({ removed: false, error: 'session-anchored-in-worktree', path: worktreePath, root,
       hint: `a sessão do Claude Code que rodou este comando está ancorada neste worktree — os hooks dela resolvem \`.morph/framework\` por ele, e desmontá-lo quebraria todo tool call seguinte (e o diretório seguiria travado pela sessão). Feche esta sessão e rode \`${again}\` de uma sessão aberta em "${root}"` }, 1);
   }
 
@@ -1681,12 +1720,12 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     try {
       status = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: worktreePath, stdio: 'pipe' }).toString();
     } catch {
-      emit({ removed: false, error: 'status-failed', path: worktreePath, root,
+      return outcome({ removed: false, error: 'status-failed', path: worktreePath, root,
         hint: 'não foi possível provar que o worktree está limpo — nada foi removido' }, 1);
     }
     const dirt = withoutLeftoverIgnore(worktreePath, status.split(/\r?\n/).filter((l) => l.trim()));
     if (dirt.length) {
-      emit({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
+      return outcome({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
         hint: `o worktree tem trabalho não commitado — commit ou descarte antes, ou rode \`morph-spec worktree remove --target "${worktreePath}"\` sem --if-clean para remover com backup` }, 1);
     }
   }
@@ -1725,6 +1764,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     // Removing a worktree is not closing a feature: the branch is the work, and
     // deleting it here would discard unintegrated commits. Opt-in only.
     deleteBranch: options.deleteBranch === true,
+    relinkOnFailure: options.relinkOnFailure === true,
     // Re-run advice must address the worktree the way it was addressable here:
     // a `--target` worktree has no feature name that would resolve.
     addressByTarget: !featureAddressable,
@@ -1763,7 +1803,18 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     const retention = enforceBackupRetention(root, { protectStamps: [stamp] });
     if (retention) out.backupRetention = retention;
   }
-  emit(out, teardown.worktreeRemoved ? 0 : 1);
+  return outcome(out, teardown.worktreeRemoved ? 0 : 1);
+}
+
+/**
+ * `morph-spec worktree remove` — prints the JSON verdict and exits with its code.
+ * @param {string|undefined} featureArg
+ * @param {object} [options] - see `runWorktreeRemove`
+ */
+export async function worktreeRemoveCommand(featureArg, options = {}) {
+  const { out, code } = await runWorktreeRemove(featureArg, options);
+  console.log(JSON.stringify(out));
+  process.exit(code);
 }
 
 // ── list ─────────────────────────────────────────────────────────────────

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/ai/code-audit.js

@@ -25,7 +25,7 @@
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { collectProjectFiles } from './ai-project-scan.js';
-import { stripComments } from './comment-stripper.js';
+import { stripComments } from '../../../framework/hooks/shared/comment-stripper.js';
 
 /** Símbolos renomeados antes do 1.0 GA, e o nome vivo de cada um. */
 export const RENAMED_SYMBOLS = {

package/src/lib/ai/registry-audit.js

@@ -22,7 +22,7 @@ import { readFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { isAbsolute, join, basename } from 'node:path';
 import { collectProjectFiles } from './ai-project-scan.js';
-import { jsoncToJson } from './comment-stripper.js';
+import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
 
 /** Limite de tamanho para um JSON candidato (bytes de texto) — evita ler dumps. */
 const MAX_JSON_CHARS = 512 * 1024;