@polymorphism-tech/morph-spec 10.1.1 → 10.5.2

package/src/commands/state/report-check.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { implementProgress, parseReport, reportPath } from '../../../framework/hooks/shared/report-progress.js';
@@ -14,6 +15,8 @@ import { isTestPath } from '../../lib/graph/sanitize.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { collectReviewRequirement } from './gate-check.js';
 import { featureGeneratesMedia } from '../../lib/plan/media.js';
+import { resolveBaseRef } from '../../lib/git/branch-classifier.js';
+import { reviewConfirmation } from '../../lib/review-confirmation.js';
 
 /** Each review report: complete when it carries a readable verdict and is not partial. */
 export function inspectReviewReports(cwd, feature) {
@@ -75,10 +78,44 @@ function treeFor(cwd, feature, beforeEval) {
   const tree = treeState(cwd, { snapshot });
   if (!beforeEval) return { tree };
   const reviewModels = reviewDispatch(cwd, feature);
+  const gate3 = gate3Briefing(cwd, feature);
   const next = snapshotTree(cwd);
-  if (!next) return { tree, beforeEval: null, reviewModels };
+  if (!next) return { tree, beforeEval: null, reviewModels, gate3 };
   atomicWriteJson(path, next);
-  return { tree, beforeEval: { at: next.at, files: Object.keys(next.files).length }, reviewModels };
+  return { tree, beforeEval: { at: next.at, files: Object.keys(next.files).length }, reviewModels, gate3 };
+}
+
+function gitLine(cwd, args) {
+  try {
+    return execFileSync('git', args, { cwd, stdio: 'pipe' }).toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function readVerification(cwd, feature) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8')).verification ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// What every dispatch needs, in one read. `redispatch: null` = no report yet, every required role goes.
+function gate3Briefing(cwd, feature) {
+  const sha = gitLine(cwd, ['rev-parse', 'HEAD']);
+  const defaultRef = resolveBaseRef(detectDefaultBranch(cwd), cwd);
+  const reports = reviewReports(cwd, feature);
+  const anyReport = Object.values(reports).some((report) => report.status !== 'missing');
+  const moved = anyReport && sha ? reviewConfirmation(cwd, reports, sha).moved : [];
+  const { checks } = readPlanChecks(cwd, feature);
+  return {
+    base: defaultRef ? gitLine(cwd, ['merge-base', defaultRef, 'HEAD']) : null,
+    sha,
+    flaky: readVerification(cwd, feature)?.flaky ?? [],
+    e2eChecks: (checks?.checks ?? []).filter((check) => check.proof === 'e2e').map((check) => check.id),
+    redispatch: anyReport ? moved.filter((role) => !role.skippable).map((role) => role.role) : null,
+  };
 }
 
 export function reportCheckCommand(feature, options = {}) {
@@ -128,6 +165,11 @@ function printHuman(obj) {
     const m = obj.reviewModels;
     console.log(chalk.gray(`  dispatch: verifier ${m.verifier.model}, reviewer ${m.reviewer.model}${m.security.required ? `, security ${m.security.model}` : ''}`));
   }
+  if (obj.gate3) {
+    const g = obj.gate3;
+    console.log(chalk.gray(`  gate 3: base ${g.base?.slice(0, 8) ?? '-'}, sha ${g.sha?.slice(0, 8) ?? '-'}`
+      + `${g.redispatch ? `, voltam: ${g.redispatch.join(', ') || 'nenhum'}` : ''}${g.flaky.length ? `, instáveis: ${g.flaky.join(', ')}` : ''}`));
+  }
   printTree(obj.tree);
   console.log('');
 }

package/src/commands/validation/verify.js

@@ -15,6 +15,25 @@ import { memoryBusyHint } from '../../lib/heavy/live-stacks.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { runCiVerify, CiUsageError, reusableLocalStamp } from '../../lib/ci/ci-verify.js';
 import { syncStackRules } from '../../lib/installers/stack-sync.js';
+import {
+  DETACH_RUN_ENV, DETACH_STAGE_ENV, DETACH_WORKER_ENV, launchWorker, markWorkerExit, runFilesOf, superviseVerify,
+} from '../../lib/verify/detached.js';
+import { watchRun } from '../../lib/heavy/watchdog.js';
+
+const detachedArgs = () => process.argv.slice(2).filter((arg) => arg !== '--detach');
+
+async function runDetached(featureName, options) {
+  const result = await superviseVerify({ feature: featureName, args: detachedArgs() });
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.died) {
+    const reason = 'a rodada destacada parou sem resultado';
+    if (options.json) console.log(JSON.stringify({ status: 'busy', persisted: false, reason }));
+    else console.error(chalk.yellow(`⏳ ${reason}: sem stamp, não é vermelho.`));
+  } else if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  process.exit(result.exitCode);
+}
 
 function statusIcon(status) {
   if (status === 'pass') return chalk.green('✓');
@@ -109,12 +128,15 @@ const PARTIAL_RUN_FLAGS = [['filter', 'filtered'], ['skipTests', 'skip-tests'],
 const CI_EXCLUSIVE_FLAGS = [
   ['filter', '--filter'], ['skipTests', '--skip-tests'], ['skipBuild', '--skip-build'], ['skipE2e', '--skip-e2e'],
   ['freshE2e', '--fresh-e2e'], ['linux', '--linux'], ['recordBaseline', '--record-baseline'], ['refreshCache', '--refresh-cache'],
-  ['noPersist', '--no-persist'],
+  ['noPersist', '--no-persist'], ['fresh', '--fresh'], ['affected', '--affected'],
 ];
 
-async function runLocalVerify(featureName, options) {
+async function runLocalVerify(featureName, options, fingerprint) {
   try {
     return await runVerify(process.cwd(), featureName, {
+      fingerprint,
+      fresh: options.fresh,
+      affected: options.affected,
       timeout: options.timeout,
       skipTests: options.skipTests,
       skipBuild: options.skipBuild,
@@ -164,6 +186,28 @@ function exitWithReusedStamp(featureName, reused, why, options) {
 // Exit 2 is "the command cannot mean what you typed" (unknown feature, `--filter` matching
 // nothing, `--record-baseline` without config.json, `--linux` without Docker): never a verdict.
 export async function verifyCommand(featureName, options = {}) {
+  const stage = process.env[DETACH_STAGE_ENV];
+  if (stage === 'launch') {
+    launchWorker({ argv: process.argv.slice(2) });
+    process.exit(0);
+  }
+  if (stage === 'watchdog') {
+    const { exit, err } = runFilesOf(process.env[DETACH_RUN_ENV]);
+    await watchRun({
+      workerPid: Number(process.env[DETACH_WORKER_ENV]), exitFile: exit, errFile: err,
+      projectPath: process.cwd(), feature: featureName, config: readHeavyConfig(process.cwd()),
+    });
+    process.exit(0);
+  }
+  if (stage === 'worker') {
+    markWorkerExit(process.env[DETACH_RUN_ENV]);
+    // A verify nested in a test suite must not report as this run.
+    delete process.env[DETACH_STAGE_ENV];
+    delete process.env[DETACH_RUN_ENV];
+    // Out of a shell's reach there is no call timeout to beat, so the queue never needs to refuse.
+    process.env.MORPH_HEAVY_WAIT_SEC = String(readHeavyConfig(process.cwd()).detachedWaitMinutes * 60);
+  }
+
   let feature;
   try {
     feature = getFeature(featureName);
@@ -174,6 +218,7 @@ export async function verifyCommand(featureName, options = {}) {
     console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
     process.exit(2);
   }
+  if (options.detach) await runDetached(featureName, options);
 
   syncStackRules(process.cwd(), { persistTags: false, log: (line) => console.error(chalk.gray(line)) });
 
@@ -214,14 +259,17 @@ export async function verifyCommand(featureName, options = {}) {
   // Taken before the run: it is the tree the run is about to read.
   const fingerprint = treeFingerprint(process.cwd());
 
-  const result = ci ? ci.result : await runLocalVerify(featureName, options);
+  const result = ci ? ci.result : await runLocalVerify(featureName, options, fingerprint);
 
   const cleanup = ci ? { status: 'skipped', reason: 'ci' } : afterHeavyRun({
     projectPath: process.cwd(),
     config: readHeavyConfig(process.cwd()),
+    onlyUnderPressure: true,
   });
 
-  const historyKey = 'verifications.feature';
+  // Only a complete run may stand in for the proof the review gate asks for: the affected one keeps its own record.
+  const scopedRun = result.scope === 'affected';
+  const historyKey = scopedRun ? 'verifications.affected' : 'verifications.feature';
   // A run that measured only part of the suite must not stand in for the proof a gate asks for:
   // --filter and --skip-*, or a --record-baseline that recorded nothing; --no-persist keeps its own reason.
   const partialRun = options.noPersist ? null : PARTIAL_RUN_FLAGS.find(([flag]) => options[flag])?.[1] ?? null;
@@ -234,7 +282,7 @@ export async function verifyCommand(featureName, options = {}) {
 
   let compact = null;
   if (persist) {
-    const prevEntry = feature.verifications?.feature;
+    const prevEntry = feature.verifications?.[scopedRun ? 'affected' : 'feature'];
     const now = new Date().toISOString();
     compact = {
       status: result.status,
@@ -242,6 +290,7 @@ export async function verifyCommand(featureName, options = {}) {
       attempts: (prevEntry?.attempts ?? 0) + 1,
       failStreak: result.status === 'fail' ? (prevEntry?.failStreak ?? 0) + 1 : 0,
       updatedAt: now,
+      ...(scopedRun ? { sha: getHeadSha(process.cwd()) } : {}),
     };
     await updateFeature(featureName, historyKey, compact);
 
@@ -254,9 +303,10 @@ export async function verifyCommand(featureName, options = {}) {
       e2eReason: result.nodes.e2e.status === 'skip' ? (result.nodes.e2e.reason ?? null) : null,
       sha: ci ? ci.run.headSha : getHeadSha(process.cwd()),
       ts: now,
+      ...(result.flaky?.length ? { flaky: result.flaky } : {}),
       ...(ci ? { source: 'ci', ciRun: ci.run.url } : {}),
     };
-    await updateFeature(featureName, 'verification', stamp);
+    if (!scopedRun) await updateFeature(featureName, 'verification', stamp);
   }
 
   // A run over the exact tree of the previous one proves nothing
@@ -266,7 +316,7 @@ export async function verifyCommand(featureName, options = {}) {
     const cwd = process.cwd();
     if (persist && !ci) repeatOf = findRepeatedVerify(cwd, { feature: featureName, fingerprint });
     const tree = resolve(cwd).replace(/\\/g, '/') === resolvePrimaryRoot(cwd) ? 'root' : 'worktree';
-    recordVerifyEvent(cwd, buildVerifyEvent(result, { sha: ci ? ci.run.headSha : getHeadSha(cwd), tree, persisted: persist, reason, fingerprint, source: ci ? 'ci' : 'local' }));
+    recordVerifyEvent(cwd, buildVerifyEvent(result, { sha: ci ? ci.run.headSha : getHeadSha(cwd), tree, persisted: persist && !scopedRun, reason: scopedRun ? 'affected' : reason, fingerprint, source: ci ? 'ci' : 'local' }));
   } catch { /* telemetry never changes the verdict */ }
 
   // The refusal always goes to stderr, so it survives --json (whose stdout has

package/src/core/state/state-manager.js

@@ -521,27 +521,3 @@ export function getApprovalGate(featureName, gate) {
   return feature.approvalGates[gate] || null;
 }
 
-export function getApprovalHistory(featureName) {
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  if (!feature || !feature.approvalGates) {
-    return [];
-  }
-
-  const history = [];
-
-  Object.entries(feature.approvalGates).forEach(([gate, data]) => {
-    if (data.timestamp) {
-      history.push({
-        gate,
-        approved: data.approved,
-        timestamp: data.timestamp,
-        approvedBy: data.approvedBy || data.rejectedBy,
-        reason: data.reason
-      });
-    }
-  });
-
-  return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
-}

package/src/dashboard/app/main.jsx

@@ -1,13 +1,13 @@
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
-import App from './App.jsx';
-import './styles/index.css';
-
-createRoot(document.getElementById('root')).render(
-  <StrictMode>
-    <BrowserRouter>
-      <App />
-    </BrowserRouter>
-  </StrictMode>
-);
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import App from './App.jsx';
+import './styles/index.css';
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>
+);

package/src/dashboard/vite.config.js

@@ -1,24 +1,24 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import tailwindcss from '@tailwindcss/vite';
-import morphDataPlugin from './vite-plugin-morph-data.js';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const frameworkDir = resolve(__dirname, '..', '..', 'framework');
-const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
-
-export default defineConfig({
-  root: __dirname,
-  plugins: [
-    react(),
-    tailwindcss(),
-    morphDataPlugin(frameworkDir, projectDir),
-  ],
-  server: {
-    port: 3200,
-  },
-});
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import morphDataPlugin from './vite-plugin-morph-data.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const frameworkDir = resolve(__dirname, '..', '..', 'framework');
+const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [
+    react(),
+    tailwindcss(),
+    morphDataPlugin(frameworkDir, projectDir),
+  ],
+  server: {
+    port: 3200,
+  },
+});

package/src/lib/heavy/cleanup.js

@@ -1,4 +1,5 @@
 import { readdirSync } from 'node:fs';
+import { freemem } from 'node:os';
 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';
@@ -8,6 +9,7 @@ const DOTNET_ACTIVE = /\bdotnet(?:\.exe)?["']?\s+(?:build|test|publish|pack|msbu
 const IDLE_WORKER = /\/nodemode:\d|vbcscompiler|razorserver/i;
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const TAIL_CHARS = 400;
+const GB = 1024 ** 3;
 
 function hasDotnet(projectPath) {
   const config = readProjectConfig(projectPath);
@@ -32,14 +34,18 @@ export function dotnetBusy(procs) {
   });
 }
 
-export function afterHeavyRun({ projectPath, config, env = process.env, deps = {} }) {
+export function afterHeavyRun({ projectPath, config, env = process.env, onlyUnderPressure = false, deps = {} }) {
   const {
-    exec = defaultProcExec, list = listProcesses, dotnet = hasDotnet, exclusive = runExclusive,
+    exec = defaultProcExec, list = listProcesses, dotnet = hasDotnet, exclusive = runExclusive, freeMem = freemem,
   } = 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 (!dotnet(projectPath)) return { status: 'skipped', reason: 'projeto sem .NET' };
+  // A warm compiler is what makes the next round short; twice the floor keeps the next queue open.
+  if (onlyUnderPressure && freeMem() / GB >= config.minFreeMemGb * 2) {
+    return { status: 'skipped', reason: 'RAM livre de sobra: o compilador fica quente para a próxima rodada' };
+  }
 
   const guarded = exclusive({
     dir: heavyDir(env), label: 'build-server-shutdown', maxHoldMs: config.maxHoldMinutes * 60_000, env,

package/src/lib/heavy/gate.js

@@ -1,8 +1,11 @@
+import { availableParallelism, freemem } from 'node:os';
 import { minFreeMemFor, readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { heavyClass } from '../../../framework/hooks/shared/heavy-command.js';
+import { GB } from '../../../framework/hooks/shared/heavy-holders.js';
 import {
   acquireHeavy, awaitFreeMemory, describeBusy, enterVerifySuite, heavyDir, isVerifySuite, releaseHeavy, updateLease,
 } from '../../../framework/hooks/shared/heavy-slots.js';
+import { reclaimUnlessDisabled } from './reclaim.js';
 
 export class HeavyBusyError extends Error {
   constructor(result, config) {
@@ -24,6 +27,9 @@ export class HeavyBusyError extends Error {
 
 const NODE_REUSE_ENV = 'MSBUILDDISABLENODEREUSE';
 const LEASE_ENV = 'MORPH_HEAVY_LEASE';
+const CPU_ENV = 'DOTNET_PROCESSOR_COUNT';
+
+export const cpuShareOf = (slots, cores = availableParallelism()) => Math.max(2, Math.floor(cores / slots));
 
 export function createHeavyGate({
   projectPath, label = 'verify', feature = null, config = readHeavyConfig(projectPath),
@@ -36,6 +42,19 @@ export function createHeavyGate({
   let suiteEntered = false;
   let exitHandler = null;
   let saved = null;
+  let reclaimed = false;
+  const politeRun = config.enabled && config.yieldToUser;
+
+  const reclaimBelow = (floor) => {
+    const { freeMem = freemem, reclaim = reclaimUnlessDisabled } = deps;
+    if (reclaimed || !config.reclaimIdleMinutes || freeMem() / GB >= floor) return;
+    reclaimed = true;
+    try {
+      const { freed, containers = [] } = reclaim({ projectPath, feature, config, env });
+      const gone = [...freed, ...containers];
+      if (gone.length) log(`heavy: RAM abaixo do piso, derrubei stacks paradas: ${gone.join(', ')}`);
+    } catch {}
+  };
 
   const restoreEnv = () => {
     if (!saved) return;
@@ -59,6 +78,7 @@ export function createHeavyGate({
   const raiseFloor = (kind) => {
     const floor = minFreeMemFor(config, kind);
     if (!lease || floor <= admittedGb) return;
+    reclaimBelow(floor);
     const result = awaitFreeMemory({
       minFreeMemGb: floor, waitTimeoutMs: config.waitTimeoutSec * 1000, kind, log, ...deps,
     });
@@ -85,6 +105,7 @@ export function createHeavyGate({
   return {
     config,
     get waitedMs() { return waitedMs; },
+    get cpuShare() { return politeRun ? cpuShareOf(config.slots) : null; },
 
     enter(node, kind = heavyClass(node)) {
       const suite = isVerifySuite({ label, node });
@@ -98,6 +119,7 @@ export function createHeavyGate({
 
       if (config.enabled) {
         const minFreeMemGb = minFreeMemFor(config, kind);
+        reclaimBelow(minFreeMemGb);
         const result = acquireHeavy({
           dir: heavyDir(env),
           slots: config.slots,
@@ -121,8 +143,9 @@ export function createHeavyGate({
         waitedMs = result.waitedMs;
       }
 
-      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV] };
+      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV], [CPU_ENV]: env[CPU_ENV] };
       if (config.disableNodeReuse) env[NODE_REUSE_ENV] = '1';
+      if (politeRun) env[CPU_ENV] ??= String(cpuShareOf(config.slots));
       if (lease) env[LEASE_ENV] = String(process.pid);
       entered = true;
       if (lease) {

package/src/lib/heavy/reclaim.js

@@ -0,0 +1,107 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultExec } from '../../../framework/hooks/shared/e2e-check.js';
+import { heavyDir, readHolders } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
+import { EVENTS_FILE } from '../../../framework/hooks/shared/telemetry-logger.js';
+import { tearDownFeatureStack } from '../e2e/stack-teardown.js';
+import { projectKey, readRegistry } from '../projects/registry.js';
+import { resolveFeatureTree } from '../worktree/feature-truth.js';
+import { afterHeavyRun } from './cleanup.js';
+import { liveE2eStacks, repoMainRoot } from './live-stacks.js';
+
+const DOCKER_TIMEOUT_MS = 10_000;
+
+function lastActivityMs(tree) {
+  try {
+    return statSync(join(tree, EVENTS_FILE)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function liveHolders(config, env, now) {
+  return readHolders(heavyDir(env), { now, isAlive: pidAlive, maxHoldMs: config.maxHoldMinutes * 60_000 });
+}
+
+function registeredRoots() {
+  try {
+    return readRegistry().projects.map((p) => p.dir);
+  } catch {
+    return [];
+  }
+}
+
+const uniqueRoots = (roots) => [...new Map(roots.map((r) => [projectKey(r), r])).values()];
+
+// One daemon answers for every project: asking it once per project would add a hung timeout each.
+function onceByArgs(exec) {
+  const seen = new Map();
+  return (file, args, opts) => {
+    const key = args.join(' ');
+    if (!seen.has(key)) seen.set(key, exec(file, args, opts));
+    return seen.get(key);
+  };
+}
+
+function reclaimStacks({ root, feature, held, idleMs, now, stacks, treeOf, activityOf, tearDown, exec }) {
+  const freed = [];
+  for (const stack of stacks(root, { exec })) {
+    if (!stack.feature || stack.state === 'unknown' || stack.feature === feature || held.has(stack.feature)) continue;
+    const archived = stack.state === 'archived';
+    // A feature without a worktree lives in the root that listed it.
+    const tree = archived ? null : treeOf(stack.feature, root) ?? root;
+    if (!archived) {
+      // Unknown activity counts as live: another session's verifier may be navigating this stack.
+      const last = activityOf(tree);
+      if (last === null || now() - last < idleMs) continue;
+    }
+    // An active feature keeps its data: the next `e2e up` only rebuilds.
+    const result = tearDown(stack.feature, { root, worktreePath: tree, volumes: archived });
+    if (result?.status !== 'fail') freed.push(stack.feature);
+  }
+  return freed;
+}
+
+function reclaimContainers(prefixes, exec) {
+  const removed = [];
+  for (const prefix of prefixes) {
+    const ps = exec('docker', ['ps', '-a', '--filter', `name=^${prefix}`, '--format', '{{.Names}}'], { timeout: DOCKER_TIMEOUT_MS });
+    if (ps.code !== 0) continue;
+    for (const name of String(ps.output ?? '').split(/\r?\n/).map((n) => n.trim()).filter(Boolean)) {
+      if (exec('docker', ['rm', '-f', name], { timeout: DOCKER_TIMEOUT_MS }).code === 0) removed.push(name);
+    }
+  }
+  return removed;
+}
+
+/** The entry every real caller uses: a test suite faking low RAM must never reach this machine's stacks. */
+export function reclaimUnlessDisabled(options) {
+  if (process.env.MORPH_HEAVY_RECLAIM === 'off') return { freed: [], containers: [] };
+  return reclaimMemory(options);
+}
+
+export function reclaimMemory({ projectPath, feature = null, config, env = process.env, deps = {} }) {
+  const {
+    stacks = liveE2eStacks, tearDown = tearDownFeatureStack, treeOf = (f, root) => resolveFeatureTree(f, root).tree,
+    activityOf = lastActivityMs, holders = liveHolders, buildServer = afterHeavyRun, now = Date.now,
+    roots = registeredRoots, exec = defaultExec,
+  } = deps;
+  if (!config.reclaimIdleMinutes) return { freed: [], containers: [] };
+
+  const cachedExec = onceByArgs(exec);
+  const live = holders(config, env, now());
+  const held = new Set(live.map((h) => h.feature).filter(Boolean));
+  const idleMs = config.reclaimIdleMinutes * 60_000;
+
+  const freed = uniqueRoots([repoMainRoot(projectPath), ...roots()]).flatMap((root) => reclaimStacks({
+    root, feature, held, idleMs, now, stacks, treeOf, activityOf, tearDown, exec: cachedExec,
+  }));
+
+  // A test container has no owner to ask: any holder that may be testing protects them all.
+  const testing = live.some((h) => h.node === 'tests' || !h.node);
+  const containers = testing ? [] : reclaimContainers(config.reclaimContainers, exec);
+
+  buildServer({ projectPath, config, env, onlyUnderPressure: true });
+  return { freed, containers };
+}

package/src/lib/heavy/watchdog.js

@@ -0,0 +1,46 @@
+import { appendFileSync, existsSync, writeFileSync } from 'node:fs';
+import { freemem } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { GB } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
+import { stopTree } from '../procs/prune.js';
+import { reclaimUnlessDisabled } from './reclaim.js';
+
+const SAMPLE_MS = 10_000;
+const LOW_SAMPLES_TO_STOP = 6;
+const EXIT_BUSY = '3';
+
+/** The floor judges only the start of a node; this judges the middle of one. It only ever stops its own run. */
+export async function watchRun({
+  workerPid, exitFile, errFile, projectPath, feature, config, env = process.env, deps = {},
+}) {
+  const {
+    freeMem = freemem, isAlive = pidAlive, wait = sleep, sampleMs = SAMPLE_MS, reclaim = reclaimUnlessDisabled,
+    list, kill,
+  } = deps;
+  if (!config.criticalFreeMemGb) return 'off';
+
+  let low = 0;
+  while (isAlive(workerPid) && !existsSync(exitFile)) {
+    const freeGb = freeMem() / GB;
+    if (freeGb >= config.criticalFreeMemGb) {
+      low = 0;
+    } else {
+      low += 1;
+      if (low === 1) {
+        try {
+          reclaim({ projectPath, feature, config, env });
+        } catch {}
+      }
+      if (low >= LOW_SAMPLES_TO_STOP) {
+        if (existsSync(exitFile)) return 'finished';
+        stopTree(workerPid, { list, kill });
+        appendFileSync(errFile, `verify parado: ${freeGb.toFixed(1)} GB livres, abaixo de heavy.criticalFreeMemGb (${config.criticalFreeMemGb}) por ${LOW_SAMPLES_TO_STOP} leituras. Não é vermelho.\n`);
+        writeFileSync(exitFile, EXIT_BUSY);
+        return 'stopped';
+      }
+    }
+    await wait(sampleMs);
+  }
+  return 'finished';
+}

package/src/lib/next-step.js

@@ -6,5 +6,6 @@ export function nextStepFor(featureName, tree) {
   const signals = collectNextSignals(featureName, tree);
   if (!signals) return null;
   signals.verificationStale = treeMovedSince(tree, signals.verification?.sha);
+  signals.affectedStale = treeMovedSince(tree, signals.affected?.sha);
   return { ...decideNext(signals), phase: signals.phase, failStreak: signals.failStreak };
 }

package/src/lib/plan/checks.js

@@ -103,7 +103,7 @@ export function validatePlan(plan, { workType = null, riskRules = true, text = n
     } else if (riskRules && proof === 'teste' && risk === null) {
       errors.push(`${c.id}: "prova: teste" sem "risco:" (${RISK_KINDS.join(' | ')}) — sem risco, a prova é "leitura" ou "e2e"${at(c.line)}`);
     } else if (risk && proof === 'leitura') {
-      warnings.push(`${c.id}: risco "${risk}" provado só por leitura${at(c.line)}`);
+      (riskRules ? errors : warnings).push(`${c.id}: risco "${risk}" provado só por leitura — quem tem risco se prova executando ("teste" ou "e2e")${at(c.line)}`);
     }
     if (canonicalRung(c.rung) === false) {
       errors.push(`${c.id}: degrau "${c.rung}" fora de ${REWORK_RUNGS.join(' | ')}${at(c.line)}`);

package/src/lib/plan/critique.js

@@ -1,8 +1,21 @@
 import { existsSync, readFileSync } from 'fs';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { featureGeneratesMedia } from './media.js';
 
 export const CRITIQUE_EXEMPT_WORK_TYPES = ['chore', 'hotfix'];
 
+const SMALL_PLAN_MAX_CHECKS = 3;
+const SMALL_PLAN_PROOFS = ['teste', 'leitura'];
+
+/** A plan this size has little for a fresh reader to catch; a rung or a proof outside the code does. */
+export function isSmallPlan(checks, planText = '') {
+  const scenarios = checks?.checks ?? [];
+  return scenarios.length > 0
+    && scenarios.length <= SMALL_PLAN_MAX_CHECKS
+    && scenarios.every((scenario) => SMALL_PLAN_PROOFS.includes(scenario.proof) && !scenario.rung)
+    && !featureGeneratesMedia(planText);
+}
+
 const PLAN_HASH_RE = /^\*\*Plan-Hash:\*\*\s*`?([0-9a-f]{64})`?\s*$/m;
 const APPLIED_RE = /^\*\*Aplicado-em:\*\*\s*`?([0-9a-f]{64})`?\s*$/gm;
 
@@ -21,8 +34,15 @@ export function readPlanCritique(cwd, featureName, { workType, planChecks }) {
   if (CRITIQUE_EXEMPT_WORK_TYPES.includes(workType)) return 'exempt';
   const currentHash = planChecks?.status === 'fresh' ? planChecks.checks?.planHash : null;
   if (!currentHash) return null;
+  if (isSmallPlan(planChecks.checks, readText(getAbsoluteOutputPath(cwd, featureName, 'plan')) ?? '')) return 'exempt';
   const path = getAbsoluteOutputPath(cwd, featureName, 'planCritique');
-  let text = null;
-  try { text = existsSync(path) ? readFileSync(path, 'utf8') : null; } catch { text = null; }
-  return critiqueStatus(text, currentHash);
+  return critiqueStatus(readText(path), currentHash);
+}
+
+function readText(path) {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
 }

package/src/lib/procs/prune.js

@@ -1,4 +1,26 @@
-import { readProcess } from './list.js';
+import { listProcesses, readProcess } from './list.js';
+
+export function descendantsOf(pid, procs) {
+  const found = [];
+  const queue = [pid];
+  while (queue.length) {
+    const parent = queue.shift();
+    for (const child of procs.filter((p) => p.ppid === parent && !found.includes(p.pid))) {
+      found.push(child.pid);
+      queue.push(child.pid);
+    }
+  }
+  return found;
+}
+
+export function stopTree(pid, { list = listProcesses, kill = (target) => process.kill(target) } = {}) {
+  const { procs } = list();
+  for (const target of [...descendantsOf(pid, procs ?? []).reverse(), pid]) {
+    try {
+      kill(target);
+    } catch {}
+  }
+}
 
 export function pruneOrphans(rows, { read = readProcess, kill = (pid) => process.kill(pid) } = {}) {
   const results = [];