@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

package/src/lib/procs/classify.js

@@ -0,0 +1,91 @@
+export const MIN_ORPHAN_AGE_MS = 15 * 60 * 1000;
+
+const PLAIN_CANDIDATES = new Set(['node', 'dotnet', 'testhost', 'esbuild']);
+const CHROME_NAMES = new Set(['chrome', 'chromium', 'msedge', 'chrome-headless-shell']);
+const BUILD_SERVER_NAMES = new Set(['vbcscompiler', 'msbuild']);
+const BUILD_SERVER_CMD = /vbcscompiler|\/nodemode:\d|msbuild(?:taskhost)?\.dll|razorserver/i;
+const AUTOMATION_CHROME = /--headless|--remote-debugging-pipe|playwright|puppeteer/i;
+const CLAUDE_CLI = /@anthropic-ai[\\/]claude-code/i;
+
+export function normalizeCmd(cmd) {
+  return String(cmd ?? '').toLowerCase().replace(/\\/g, '/');
+}
+
+export function categorize(proc) {
+  const cmd = proc.cmd ?? '';
+  if (BUILD_SERVER_NAMES.has(proc.name)) return 'build-server';
+  if (proc.name === 'dotnet' && BUILD_SERVER_CMD.test(cmd)) return 'build-server';
+  if (CHROME_NAMES.has(proc.name)) {
+    return AUTOMATION_CHROME.test(cmd) && !/--type=/.test(cmd) ? 'chrome-headless' : null;
+  }
+  return PLAIN_CANDIDATES.has(proc.name) ? proc.name : null;
+}
+
+export function isClaudeSession(proc) {
+  return proc.name === 'claude' || CLAUDE_CLI.test(proc.cmd ?? '');
+}
+
+function protectionReason(proc, { mcpTokens, holderPids }) {
+  if (holderPids.has(proc.pid)) return 'segura slot do semáforo pesado';
+  const cmd = normalizeCmd(proc.cmd);
+  if (/graph-refresh\.js/.test(cmd) && /--run\b/.test(cmd)) return 'worker de refresh do grafo';
+  const token = mcpTokens.find((t) => cmd.includes(t));
+  if (token) return `linha de comando de MCP configurado (${token})`;
+  return null;
+}
+
+export function classifyProcs(procs, { now = Date.now(), mcpTokens = [], holderPids = [], minAgeMs = MIN_ORPHAN_AGE_MS } = {}) {
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  const tokens = mcpTokens.map((t) => String(t).toLowerCase());
+  const holders = new Set(holderPids);
+
+  const liveParent = (p) => {
+    const parent = byPid.get(p.ppid);
+    if (!parent) return null;
+    if (parent.startedMs !== null && p.startedMs !== null && parent.startedMs > p.startedMs) return null;
+    return parent;
+  };
+
+  const rows = [];
+  for (const proc of procs) {
+    const category = categorize(proc);
+    if (!category) continue;
+    const orphan = proc.ppid > 4 && liveParent(proc) === null;
+    const ageMs = proc.startedMs === null ? null : Math.max(0, now - proc.startedMs);
+    const row = {
+      pid: proc.pid,
+      ppid: proc.ppid,
+      name: proc.name,
+      category,
+      cmd: proc.cmd,
+      rssMb: Math.round(proc.rss / (1024 * 1024)),
+      startedMs: proc.startedMs,
+      ageMs,
+      orphan,
+      verdict: 'alive-parent',
+      reason: null,
+    };
+    if (orphan) {
+      const protectedBy = category === 'build-server' ? null : protectionReason(proc, { mcpTokens: tokens, holderPids: holders });
+      if (category === 'build-server') {
+        row.verdict = 'build-server';
+        row.reason = 'nó de build reutilizável pode servir outra sessão; encerre com `dotnet build-server shutdown` quando ocioso';
+      } else if (protectedBy) {
+        row.verdict = 'protected';
+        row.reason = protectedBy;
+      } else if (ageMs === null) {
+        row.verdict = 'protected';
+        row.reason = 'idade desconhecida';
+      } else if (ageMs < minAgeMs) {
+        row.verdict = 'protected';
+        row.reason = `mais novo que ${Math.round(minAgeMs / 60000)} min`;
+      } else {
+        row.verdict = 'orphan';
+      }
+    }
+    rows.push(row);
+  }
+
+  const sessions = procs.filter(isClaudeSession).length;
+  return { rows, sessions };
+}

package/src/lib/procs/list.js

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const PS_PROJECTION = "[pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId; name = $_.Name; cmd = $_.CommandLine; rss = [int64]$_.WorkingSetSize; started = if ($_.CreationDate) { $_.CreationDate.ToUniversalTime().ToString('o') } else { $null } }";
+const PS_PREFIX = '[Console]::OutputEncoding = [Text.Encoding]::UTF8; ';
+
+export function defaultProcExec(file, args, { timeout = 30000 } = {}) {
+  try {
+    const output = execFileSync(file, args, {
+      encoding: 'utf8',
+      timeout,
+      windowsHide: true,
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { code: 0, output };
+  } catch (err) {
+    return {
+      code: err.status ?? 1,
+      output: `${err.stdout ?? ''}${err.stderr ?? ''}`,
+      missing: err.code === 'ENOENT',
+    };
+  }
+}
+
+export function normalizeProcName(name) {
+  return String(name ?? '').toLowerCase().replace(/\.exe$/, '');
+}
+
+function toProc(p) {
+  const startedMs = typeof p.startedMs === 'number' ? p.startedMs : p.started ? Date.parse(p.started) : null;
+  return {
+    pid: Number(p.pid),
+    ppid: Number(p.ppid ?? 0),
+    name: normalizeProcName(p.name),
+    cmd: typeof p.cmd === 'string' && p.cmd.length ? p.cmd : null,
+    rss: Number(p.rss ?? 0),
+    startedMs: Number.isFinite(startedMs) ? startedMs : null,
+  };
+}
+
+export function parseWindowsProcs(text) {
+  const trimmed = String(text ?? '').trim();
+  if (!trimmed) return [];
+  const raw = JSON.parse(trimmed);
+  return (Array.isArray(raw) ? raw : [raw]).filter((p) => p && Number.isInteger(p.pid)).map(toProc);
+}
+
+export function parseEtime(etime) {
+  const m = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(String(etime).trim());
+  if (!m) return null;
+  const [, d = 0, h = 0, min, s] = m;
+  return ((Number(d) * 24 + Number(h)) * 60 + Number(min)) * 60 + Number(s);
+}
+
+export function parsePosixProcs(text, now = Date.now()) {
+  const procs = [];
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\d+)\s+(\S+)\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const seconds = parseEtime(m[3]);
+    procs.push(toProc({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      name: m[5].split('/').pop(),
+      cmd: m[6] || m[5],
+      rss: Number(m[4]) * 1024,
+      startedMs: seconds === null ? null : now - seconds * 1000,
+    }));
+  }
+  return procs;
+}
+
+function fromFixture(path) {
+  const raw = JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  return (Array.isArray(raw) ? raw : []).map(toProc);
+}
+
+function windowsScript(filter) {
+  const query = filter ? `Get-CimInstance Win32_Process -Filter "${filter}"` : 'Get-CimInstance Win32_Process';
+  return `${PS_PREFIX}${query} | ForEach-Object { ${PS_PROJECTION} } | ConvertTo-Json -Compress`;
+}
+
+const POSIX_COLUMNS = 'pid=,ppid=,etime=,rss=,comm=,args=';
+
+function runList({ pid = null, exec, platform, now }) {
+  if (platform === 'win32') {
+    const filter = pid === null ? '' : `ProcessId=${Number(pid)}`;
+    const res = exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', windowsScript(filter)]);
+    if (res.code !== 0) return { procs: null, reason: `PowerShell falhou (exit ${res.code})` };
+    try {
+      return { procs: parseWindowsProcs(res.output), reason: null };
+    } catch {
+      return { procs: null, reason: 'saída do PowerShell ilegível' };
+    }
+  }
+  if (platform === 'linux' || platform === 'darwin') {
+    const args = pid === null ? ['-eo', POSIX_COLUMNS] : ['-p', String(Number(pid)), '-o', POSIX_COLUMNS];
+    const res = exec('ps', args);
+    if (res.code !== 0 && pid === null) return { procs: null, reason: `ps falhou (exit ${res.code})` };
+    return { procs: parsePosixProcs(res.output, now), reason: null };
+  }
+  return { procs: null, reason: `plataforma ${platform} sem listador de processos` };
+}
+
+export function listProcesses({ exec = defaultProcExec, platform = process.platform, now = Date.now(), env = process.env } = {}) {
+  if (env.MORPH_PROCS_FIXTURE) {
+    try {
+      return { procs: fromFixture(env.MORPH_PROCS_FIXTURE), reason: null };
+    } catch {
+      return { procs: null, reason: 'MORPH_PROCS_FIXTURE ilegível' };
+    }
+  }
+  return runList({ exec, platform, now });
+}
+
+export function readProcess(pid, { exec = defaultProcExec, platform = process.platform, now = Date.now(), env = process.env } = {}) {
+  if (env.MORPH_PROCS_FIXTURE) {
+    const { procs } = listProcesses({ env });
+    return procs?.find((p) => p.pid === pid) ?? null;
+  }
+  const { procs } = runList({ pid, exec, platform, now });
+  return procs?.find((p) => p.pid === pid) ?? null;
+}

package/src/lib/procs/mcp-config.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
+import { readEnabledPlugins } from '../detectors/claude-config-detector.js';
+
+const GENERIC_TOKENS = new Set([
+  'cmd', 'cmd.exe', 'npx', 'npx.cmd', 'npm', 'node', 'node.exe', 'python', 'python3', 'uv', 'uvx',
+  'dotnet', 'docker', 'run', 'exec', 'bash', 'sh', 'powershell', 'pwsh',
+]);
+
+const toolNamePart = (s) => String(s).replace(/[^A-Za-z0-9_-]/g, '_');
+
+function readJsonc(file, unreadable) {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(jsoncToJson(readFileSync(file, 'utf8').replace(/^/, '')));
+  } catch {
+    unreadable.push(file);
+    return null;
+  }
+}
+
+function sameDir(a, b) {
+  const norm = (p) => resolve(p).replace(/\\/g, '/').replace(/\/$/, '');
+  const [x, y] = [norm(a), norm(b)];
+  return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+
+function toServers(map, scope, extra = {}) {
+  return Object.entries(map && typeof map === 'object' ? map : {}).map(([name, cfg]) => ({
+    name,
+    scope,
+    command: cfg?.command ?? null,
+    args: Array.isArray(cfg?.args) ? cfg.args.map(String) : [],
+    url: cfg?.url ?? null,
+    ...extra,
+  }));
+}
+
+function pluginMcpServers(installPath, plugin, unreadable) {
+  const doc = readJsonc(join(installPath, '.mcp.json'), unreadable);
+  if (!doc || typeof doc !== 'object') return [];
+  const map = doc.mcpServers && typeof doc.mcpServers === 'object' ? doc.mcpServers : doc;
+  return toServers(map, 'plugin', { plugin });
+}
+
+function pickInstall(entries, projectDir) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e?.installPath) : [];
+  return list.find((e) => e.projectPath && sameDir(e.projectPath, projectDir)) ?? list.find((e) => e.scope === 'user') ?? list[0] ?? null;
+}
+
+export function readMcpConfig({ projectDir, home = homedir() }) {
+  const unreadable = [];
+  const servers = [];
+
+  const project = readJsonc(join(projectDir, '.mcp.json'), unreadable);
+  servers.push(...toServers(project?.mcpServers, 'project'));
+
+  const userDoc = readJsonc(join(home, '.claude.json'), unreadable);
+  servers.push(...toServers(userDoc?.mcpServers, 'user'));
+  const projectKey = Object.keys(userDoc?.projects ?? {}).find((k) => sameDir(k, projectDir));
+  if (projectKey) servers.push(...toServers(userDoc.projects[projectKey]?.mcpServers, 'local'));
+
+  const enabledPlugins = readEnabledPlugins(projectDir, home);
+  const installed = readJsonc(join(home, '.claude', 'plugins', 'installed_plugins.json'), unreadable)?.plugins ?? {};
+  const pluginServers = [];
+  for (const id of enabledPlugins) {
+    const install = pickInstall(installed[id], projectDir);
+    if (install) pluginServers.push(...pluginMcpServers(install.installPath, id.split('@')[0], unreadable));
+  }
+
+  return { servers, pluginServers, enabledPlugins, unreadable };
+}
+
+export function findDuplicateMcps({ servers, pluginServers }) {
+  const duplicates = [];
+  for (const ps of pluginServers) {
+    const declared = servers.filter((s) => s.name === ps.name);
+    if (!declared.length) continue;
+    duplicates.push({
+      server: ps.name,
+      plugin: ps.plugin,
+      declaredIn: [...new Set(declared.map((s) => s.scope))],
+      toolNames: [`mcp__${ps.name}`, `mcp__plugin_${toolNamePart(ps.plugin)}_${toolNamePart(ps.name)}`],
+    });
+  }
+  return duplicates;
+}
+
+export function mcpCommandTokens({ servers, pluginServers }) {
+  const tokens = new Set();
+  for (const s of [...servers, ...pluginServers]) {
+    if (s.url && !s.command) continue;
+    for (const raw of [s.command, ...s.args]) {
+      if (typeof raw !== 'string') continue;
+      const token = raw.toLowerCase().replace(/\\/g, '/');
+      if (token.length < 4 || /^[-/]/.test(token) || token.includes('${') || GENERIC_TOKENS.has(token)) continue;
+      tokens.add(token);
+    }
+  }
+  return [...tokens];
+}

package/src/lib/procs/prune.js

@@ -0,0 +1,25 @@
+import { readProcess } from './list.js';
+
+export function pruneOrphans(rows, { read = readProcess, kill = (pid) => process.kill(pid) } = {}) {
+  const results = [];
+  for (const row of rows) {
+    if (row.verdict !== 'orphan') continue;
+    const fresh = read(row.pid);
+    const base = { pid: row.pid, name: row.name };
+    if (!fresh) {
+      results.push({ ...base, outcome: 'skipped', reason: 'já encerrado' });
+      continue;
+    }
+    if (fresh.startedMs !== row.startedMs || fresh.cmd !== row.cmd || fresh.name !== row.name) {
+      results.push({ ...base, outcome: 'skipped', reason: 'o PID foi reaproveitado por outro processo' });
+      continue;
+    }
+    try {
+      kill(row.pid);
+      results.push({ ...base, outcome: 'killed' });
+    } catch (err) {
+      results.push({ ...base, outcome: 'failed', reason: err?.code ?? err?.message ?? 'erro desconhecido' });
+    }
+  }
+  return results;
+}

package/src/lib/procs/wslconfig.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, totalmem } from 'node:os';
+
+const GB = 1024 ** 3;
+
+export function parseWslConfig(text) {
+  const sections = {};
+  let current = null;
+  for (const raw of String(text).replace(/^/, '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const header = /^\[([^\]]+)\]$/.exec(line);
+    if (header) {
+      current = header[1].trim().toLowerCase();
+      sections[current] ??= {};
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq < 0 || current === null) continue;
+    sections[current][line.slice(0, eq).trim().toLowerCase()] = line.slice(eq + 1).trim();
+  }
+  return sections;
+}
+
+export function suggestedMemoryGb(totalMemBytes) {
+  return Math.max(4, Math.floor((totalMemBytes / GB) * 0.4));
+}
+
+function suggestion({ memory, reclaim, totalMemBytes }) {
+  const lines = [];
+  if (!memory) lines.push('[wsl2]', `memory=${suggestedMemoryGb(totalMemBytes)}GB`);
+  if (!reclaim) lines.push('[experimental]', 'autoMemoryReclaim=gradual');
+  return lines.length ? lines.join('\n') : null;
+}
+
+export function inspectWslConfig({
+  home = homedir(),
+  platform = process.platform,
+  totalMemBytes = totalmem(),
+  exists = existsSync,
+  read = (p) => readFileSync(p, 'utf8'),
+} = {}) {
+  if (platform !== 'win32') return { status: 'skip', reason: 'WSL só existe no Windows' };
+  const path = join(home, '.wslconfig');
+  if (!exists(path)) {
+    return {
+      status: 'missing',
+      path,
+      memory: null,
+      autoMemoryReclaim: null,
+      suggestion: suggestion({ memory: null, reclaim: null, totalMemBytes }),
+    };
+  }
+  let sections;
+  try {
+    sections = parseWslConfig(read(path));
+  } catch {
+    return { status: 'skip', reason: `${path} ilegível` };
+  }
+  const memory = sections.wsl2?.memory ?? null;
+  const autoMemoryReclaim = sections.experimental?.automemoryreclaim ?? null;
+  return {
+    status: 'present',
+    path,
+    memory,
+    autoMemoryReclaim,
+    suggestion: suggestion({ memory, reclaim: autoMemoryReclaim, totalMemBytes }),
+  };
+}

package/src/lib/projects/registry.js

@@ -42,8 +42,12 @@ export function isMorphProject(dir) {
 
 /** A worktree checkout is part of its repo's project, never a project of its own. */
 function insideWorktreeContainer(dir) {
-  const parent = basename(dirname(dir));
-  return WORKTREE_DIR_NAMES.includes(parent);
+  if (WORKTREE_DIR_NAMES.includes(basename(dirname(dir)))) return true;
+  try {
+    return /[\\/]\.git[\\/]worktrees[\\/][^\\/]+\s*$/.test(readFileSync(join(dir, '.git'), 'utf8'));
+  } catch {
+    return false;
+  }
 }
 
 function projectName(dir) {

package/src/lib/risk-detector.js

@@ -15,8 +15,8 @@
  *   - e2eStatus + e2eReason + gate    — nó e2e do último verify. Um `skip`
  *     cuja razão NÃO seja dispensa legítima pausa SÓ no ship (gate 'review').
  *     Sem escopo (stamp sem o campo) cai do mesmo lado seguro que `unknown`
- *   - verificationStale + gate: bool/str — stamp com sha != HEAD pausa SÓ no
- *     ship (gate 'review') — código mudou depois do último verify
+ *   - verificationStale + gate: bool/str — stamp de um commit cujo código já mudou
+ *     (fora de .morph/) pausa SÓ no ship (gate 'review')
  *   - evalScoreSource + gate: str     — no ship, score que NÃO veio do avaliador
  *     independente pausa (auto-avaliação não decide o Gate 3)
  *   - mutationProof + gate: object    — { section, min, productionCode } lido do
@@ -274,7 +274,7 @@ export function shouldPauseGate(config, signals) {
   if (signals.gate === 'review' && signals.verificationStale === true) {
     return {
       pause: true,
-      reason: 'verification stamp desatualizado (sha difere do HEAD) — rode `morph-spec verify` de novo antes do ship',
+      reason: 'verification stamp desatualizado (o código mudou depois do commit do stamp) — rode `morph-spec verify` de novo antes do ship',
     };
   }
 

package/src/lib/tasks/eval-node.js

@@ -36,7 +36,7 @@ import { join, resolve, sep } from 'path';
 import { tmpdir } from 'os';
 
 import { isInside } from './test-runner.js';
-import { readAiPin } from '../standards/verified-against.js';
+import { resolveAiPin } from '../ai/pin-drift.js';
 
 /** The runner kind. One spelling, imported by every reader. */
 export const EVAL_RUNNER = 'evals';
@@ -72,34 +72,6 @@ export function cacheRelevantPackages(packages) {
   return out;
 }
 
-/**
- * Read the pin from a project, wherever the framework lives.
- *
- * Two roots, ONE reader: this repository carries `framework/ai-pin.json` at the
- * top; an installed project carries it under `.morph/framework/`. `readAiPin`
- * appends `framework/ai-pin.json` to whatever root it is given, so both cases
- * are the same function with a different argument — never a second parser.
- *
- * Returns null when neither exists: a project with no pin simply has no stamp
- * ruler, and refusing to run there would make the eval node unusable outside
- * this framework's own stack.
- *
- * @param {string} projectPath
- * @returns {{pinnedAt: string, packages: object}|null}
- */
-export function readProjectPin(projectPath) {
-  for (const root of [projectPath, join(projectPath, '.morph')]) {
-    try {
-      return readAiPin(root);
-    } catch {
-      // Next candidate. The throw is readAiPin's contract for "no pin here",
-      // and it is the reason this loop exists instead of an existsSync probe
-      // that would duplicate the path knowledge.
-    }
-  }
-  return null;
-}
-
 /**
  * Resolve every path an eval node names, against the project root.
  *
@@ -256,11 +228,9 @@ export function evalPreflight(projectPath, node, options = {}) {
     return { status: 'fail', reason: `eval-cache-empty: ${cacheRoot} não contém nenhuma entrada de cache` };
   }
 
-  const pin = readProjectPin(projectPath);
+  const pin = resolveAiPin(projectPath);
   if (!pin) {
-    // No pin, no ruler — and a project without one is a legitimate case, not a
-    // failure: the stamp check simply does not apply. Saying so is the point;
-    // silently treating it as "stamp ok" would be the same thing said badly.
+    // No pin in the project or in the CLI package: nothing to stamp against.
     return { status: null, reason: null };
   }
 
@@ -315,7 +285,7 @@ export function evalNodeEnv(node, projectPath, options = {}) {
     MORPH_EVAL_ENVFILE: envFile,
   };
 
-  const pin = readProjectPin(projectPath);
+  const pin = resolveAiPin(projectPath);
   if (pin) {
     // Compact, and only the packages that decide the cache format. The fixture
     // stamps from THIS, so it never has to read (or parse) the pin itself.

package/src/lib/tasks/linux-runner.js

@@ -38,6 +38,7 @@
  * @module linux-runner
  */
 
+import { createHash } from 'crypto';
 import { resolve } from 'path';
 
 import { defaultExec, isDockerAvailable } from '../../../framework/hooks/shared/e2e-check.js';
@@ -174,9 +175,10 @@ export function buildContainerScript({ nodes }) {
  * @param {{ projectPath: string, image: string, script: string }} params
  * @returns {string[]}
  */
-export function buildLinuxArgv({ projectPath, image, script }) {
+export function buildLinuxArgv({ projectPath, image, script, runId = null }) {
   return [
     'run', '--rm',
+    ...(runId ? ['--label', `${LABEL_RUN}=${runId}`, '--label', `${LABEL_ROOT}=${rootHash(projectPath)}`] : []),
     // Read-only, and mounted at /src: the SOURCE of the copy, never the tree
     // the tests run from. See the module docs for why that distinction is the
     // entire point of the flag.
@@ -269,8 +271,14 @@ export function runLinuxSuite({ projectPath, nodes, image, timeout, exec = defau
   }
 
   const script = buildContainerScript({ nodes: runnable });
-  const argv = buildLinuxArgv({ projectPath, image: resolvedImage, script });
-  const run = exec('docker', argv, { cwd: projectPath, timeout });
+  const runId = `${process.pid}-${Date.now().toString(36)}`;
+  const argv = buildLinuxArgv({ projectPath, image: resolvedImage, script, runId });
+  let run;
+  try {
+    run = exec('docker', argv, { cwd: projectPath, timeout });
+  } finally {
+    reapLabeledContainers({ runId, exec, cwd: projectPath });
+  }
 
   const results = splitByMarkers(run.output, runnable).map((r) =>
     r.exitCode === null && !r.reason
@@ -291,6 +299,25 @@ export function runLinuxSuite({ projectPath, nodes, image, timeout, exec = defau
   return { results: [...enriched, ...refused], environment, argv, script, containerCode: run.code };
 }
 
+export const LABEL_RUN = 'morph-spec.verify';
+export const LABEL_ROOT = 'morph-spec.root';
+
+export function rootHash(projectPath) {
+  const root = resolve(projectPath).replace(/\\/g, '/');
+  const key = process.platform === 'win32' ? root.toLowerCase() : root;
+  return createHash('sha1').update(key).digest('hex').slice(0, 12);
+}
+
+// A timeout kills the docker client, not the container: `--rm` never fires for it.
+export function reapLabeledContainers({ runId, exec, cwd }) {
+  try {
+    const listed = exec('docker', ['ps', '-aq', '--filter', `label=${LABEL_RUN}=${runId}`], { cwd, timeout: 15_000 });
+    if (listed.code !== 0) return;
+    const ids = String(listed.output ?? '').split(/\s+/).filter((id) => /^[0-9a-f]{6,64}$/i.test(id));
+    if (ids.length) exec('docker', ['rm', '-f', ...ids], { cwd, timeout: 30_000 });
+  } catch { /* limpeza best-effort: nunca muda o veredito da suíte */ }
+}
+
 /** Last few lines of the container output — enough to name a pull failure. */
 function tail(output, lines = 5) {
   return String(output || '').split('\n').slice(-lines).join('\n').trim();

package/src/lib/tasks/test-runner.js

@@ -349,7 +349,7 @@ export function resolveTestBuildTargets(node) {
  * application's solution and may therefore never have been restored at all.
  * F29's project was exactly that project.
  */
-function dotnetBuildCommandFor(target, projectPath) {
+export function dotnetBuildCommandFor(target, projectPath) {
   const base = getBuildSteps('dotnet', { cwd: projectPath || '.' })[0]?.command;
   if (!base) return null;
   const [verb, subcommand, ...flags] = base.split(/\s+/);

package/src/lib/validators/contracts/contract-compliance-validator.js

@@ -1,56 +1,21 @@
-/**
- * Contract Compliance Validator
- *
- * Parses contracts.cs from feature outputs and verifies that the project code
- * actually implements all defined interfaces, methods, DTOs, and enums.
- *
- * MORPH-SPEC 3.0 - Phase A: Active Validation Pipeline
- */
-
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { glob } from 'glob';
 import chalk from 'chalk';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../../core/paths/output-schema.js';
 
-/**
- * Validate that contracts.cs interfaces are implemented in project code
- *
- * @param {string} projectPath - Project root path
- * @param {string} featureName - Feature name
- * @param {Object} options - Options
- * @returns {Object} { status, errors, warnings, issues, coverage }
- */
 export async function validateContracts(projectPath, featureName, options = {}) {
-  // `'contracts'` is not an output type — `getAbsoluteOutputPath` threw
-  // "Unknown output type" on every call. The runner already resolves this the
-  // right way before deciding to schedule this validator
-  // (`resolveContractsOutputType()`); using the same resolver here is what
-  // keeps the two from disagreeing again.
   const contractsPath = getAbsoluteOutputPath(projectPath, featureName, resolveContractsOutputType());
 
-  if (!existsSync(contractsPath)) {
-    return {
-      status: 'ok',
-      errors: 0,
-      warnings: 0,
-      issues: [],
-      coverage: null,
-      message: 'No contracts.cs found — skipping'
-    };
-  }
+  const skipped = (message) => ({ status: 'ok', errors: 0, warnings: 0, issues: [], coverage: null, message });
+
+  if (!existsSync(contractsPath)) return skipped('No spec.md found — skipping');
 
   const contractsContent = readFileSync(contractsPath, 'utf-8');
   const contracts = parseContracts(contractsContent);
 
   if (contracts.interfaces.length === 0 && contracts.records.length === 0 && contracts.enums.length === 0) {
-    return {
-      status: 'ok',
-      errors: 0,
-      warnings: 1,
-      issues: [{ level: 'warning', message: 'contracts.cs exists but no interfaces/records/enums found' }],
-      coverage: null
-    };
+    return skipped('spec.md declares no interfaces/records/enums — skipping');
   }
 
   // Find all .cs files in the project (excluding .morph outputs, bin, obj)
@@ -168,9 +133,6 @@ export async function validateContracts(projectPath, featureName, options = {})
   };
 }
 
-/**
- * Parse contracts.cs content and extract interfaces, records, and enums
- */
 function parseContracts(content) {
   const interfaces = [];
   const records = [];