@polymorphism-tech/morph-spec 9.4.0 → 9.6.0

package/framework/hooks/claude-code/core/gate-guard.js

@@ -4,7 +4,6 @@
 import { loadState, stateExists, getActiveFeature } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { gateFromQuestion } from '../../shared/gate-question.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
 import { resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { locateFeatureForQuestion } from '../../shared/feature-locator.js';
 
@@ -61,7 +60,6 @@ function checkAskUserQuestion(input, sessionRoot) {
     const decision = getDecision(state, feature, gate);
     if (!decision) continue;
     if (decision.pause === false) {
-      logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return contextResult(
         `⚠️ [morph-spec] GATE OVER-PAUSE — você apresentou o Gate "${gate}" via AskUserQuestion, ` +
         `mas a decisão registrada em state.json (gateDecisions.${gate}) era pause:false ` +
@@ -72,7 +70,6 @@ function checkAskUserQuestion(input, sessionRoot) {
         'PostToolUse'
       );
     }
-    logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
     return null;
   }
   return null;
@@ -94,8 +91,6 @@ function checkStateEdit(input, sessionRoot) {
   if (!state) return null;
   const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
   if (!feature) return null;
-
-  let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
   for (const gate of ['plan', 'uiux', 'review']) {
     const g = gates[gate];
@@ -104,7 +99,6 @@ function checkStateEdit(input, sessionRoot) {
     const decision = getDecision(state, feature, gate);
     if (!decision) continue;
     if (decision.pause === true) {
-      logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return contextResult(
         `⚠️ [morph-spec] GATE SKIPPED PAUSE — o Gate "${gate}" foi marcado approvedBy:"auto", ` +
         `mas a decisão registrada (gateDecisions.${gate}) era pause:true ` +
@@ -114,9 +108,7 @@ function checkStateEdit(input, sessionRoot) {
         'PostToolUse'
       );
     }
-    checked = true;
   }
-  if (checked) logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
   return null;
 }
 

package/framework/hooks/claude-code/core/heavy-gate.js

@@ -5,7 +5,7 @@
 
 import { stateExists } from '../../shared/state-reader.js';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
-import { heavyKind, leaseTtlMs } from '../../shared/heavy-command.js';
+import { heavyClass, heavyKind, leaseTtlMs } from '../../shared/heavy-command.js';
 
 const HOOK_BUDGET_SEC = 540;
 
@@ -18,7 +18,7 @@ export async function run(payload, deps = {}) {
     if (!kind || !payload?.tool_use_id) return null;
 
     // Loaded only here: this link runs on every Bash call and almost none is heavy.
-    const { readHeavyConfig } = await import('../../shared/heavy-config.js');
+    const { minFreeMemFor, readHeavyConfig } = await import('../../shared/heavy-config.js');
     const { acquireHeavy, describeBusy, heavyDir } = await import('../../shared/heavy-slots.js');
     const env = deps.env ?? process.env;
     const dir = env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
@@ -26,6 +26,7 @@ export async function run(payload, deps = {}) {
     const config = readHeavyConfig(dir, env);
     if (!config.enabled || !config.gateBash) return null;
 
+    const memClass = heavyClass(kind);
     const result = (deps.acquire ?? acquireHeavy)({
       dir: heavyDir(env),
       slots: config.slots,
@@ -33,7 +34,8 @@ export async function run(payload, deps = {}) {
       feature: null,
       node: null,
       cwd: dir,
-      minFreeMemGb: config.minFreeMemGb,
+      kind: memClass,
+      minFreeMemGb: minFreeMemFor(config, memClass),
       waitTimeoutMs: Math.min(config.waitTimeoutSec, HOOK_BUDGET_SEC) * 1000,
       maxHoldMs: config.maxHoldMinutes * 60_000,
       lease: { id: payload.tool_use_id, ttlMs: leaseTtlMs(input, env) },

package/framework/hooks/claude-code/core/loop-detect.js

@@ -5,7 +5,6 @@ import { join } from 'path';
 import { stateExists } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { getCommandSignature } from '../../shared/payload-utils.js';
-import { logEvent } from '../../shared/activity-logger.js';
 
 const MAX_BUFFER = 15;
 const LOOP_WINDOW = 8;
@@ -60,8 +59,6 @@ export async function run(payload) {
 
     writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
 
-    logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
-
     const sigList = [...uniqueSigs].join(', ');
     return contextResult(
       `⚠️ [morph-spec] LOOP DETECTED — the last ${LOOP_WINDOW} actions repeat only ${uniqueSigs.size} pattern(s): ${sigList}\n\n` +

package/framework/hooks/claude-code/core/pre-bash-denylist.js

@@ -54,8 +54,9 @@ export async function run(payload) {
     }
 
     for (const rule of denylist.executableArgs || []) {
+      if (rule.subagentOnly && !payload.agent_id) continue;
       if (matchesExecutableRule(command, rule)) {
-        const shown = [rule.executable, ...(rule.flags || []).map((group) => group[0]), rule.args[0]].join(' ');
+        const shown = rule.display ?? [rule.executable, ...(rule.flags || []).map((group) => group[0]), rule.args[0]].join(' ');
         return blockResult(`Comando bloqueado pela denylist: \`${shown}\` ${rule.reason}.`);
       }
     }

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -9,7 +9,6 @@ import {
   PROTECTED_SPEC_FILES
 } from '../../shared/phase-utils.js';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, getToolName, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { ERRATA_HEADING, errataViolation } from '../../shared/errata.js';
 
@@ -57,7 +56,6 @@ export async function run(payload) {
     // Generated only by the CLI: a hand-written one would carry checks the parser never judged.
     // Decided before the creation carve-out, since chore/hotfix are born with the plan gate stamped.
     if (filename === CHECKS_FILE) {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
       return blockResult(
         `MORPH-SPEC: '${CHECKS_FILE}' is generated — never written by hand.\n` +
         `Edit 2-plan/plan.md and run \`morph-spec plan-check ${featureName}\`: it parses the plan and writes ${CHECKS_FILE}.\n` +
@@ -67,7 +65,6 @@ export async function run(payload) {
     }
 
     if (!isGateApproved(featureName, requiredGate, root)) {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       return null;
     }
 
@@ -76,7 +73,6 @@ export async function run(payload) {
     // A file not yet on disk is its CREATION (chore/hotfix are born with `plan` stamped), not an edit of a frozen spec.
     // The criterion is existence, never `approvedBy`: by signature, deleting a spec first would license rewriting it.
     if (!existsSync(absPath)) {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'ok:absent');
       return null;
     }
 
@@ -90,11 +86,8 @@ export async function run(payload) {
     } catch {}
 
     if (errataCheck?.ok) {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       return null;
     }
-
-    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     return blockResult(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
       `Editing an approved artifact breaks its contract.\n\n` +

package/framework/hooks/claude-code/core/validate-completion.js

@@ -7,7 +7,6 @@ import {
   stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
-import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 import { sliceProgress, sliceReportPath, inspectReport } from '../../shared/slice-progress.js';
@@ -145,9 +144,6 @@ export async function run(payload) {
       'MORPH-SPEC:',
       ...warnings.map(w => `  ${w}`),
     ].join('\n');
-
-    logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
-    logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
     return contextResult(message, 'Stop');
   } catch {
     return null;

package/framework/hooks/claude-code/core/worktree-context.js

@@ -13,7 +13,6 @@ import { sliceProgress } from '../../shared/slice-progress.js';
 import { collectNextSignals, decideNext, formatNext } from '../../shared/next-step.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
-import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
 import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
 import { kickGraphRefresh, seedFromPrimary } from '../../shared/graph-refresh.js';
 import { kickAgentReap } from '../../shared/agent-reap.js';
@@ -226,7 +225,6 @@ export async function run(payload) {
       return null;
     }
 
-    try { rotateActivityLogIfLarge(dir); } catch {}
     try { rotateEventsLogIfLarge(dir); } catch {}
     // Only the ROOT's graph is refreshed in background: a detached process holding a worktree directory made `finish` fail on win32.
     try { seedFromPrimary(dir); } catch {}

package/framework/hooks/claude-code/statusline.py

@@ -457,49 +457,13 @@ def get_active_features(cwd):
     return result
 
 
-def get_last_hook(cwd):
-    """Name of the most recent hook from .morph/logs/activity.jsonl.
-
-    activity-logger.js (R1.2) writes append-only JSONL now, one event per
-    line (`{"kind": "hook", ...}` or `{"kind": "event", ...}`), instead of a
-    single JSON doc rewritten whole on every call. The log can grow up to the
-    rotation threshold (2 MB, see ROTATE_THRESHOLD_BYTES in activity-logger.js)
-    between SessionStarts, and this function runs on every prompt redraw, so
-    only the trailing slice is read — never the whole file.
-
-    The age is deliberately not shown: activity-logger.js only records
-    HH:MM:SS, so any age computed from it is wrong across midnight.
-    """
-    try:
-        path = Path(cwd) / '.morph' / 'logs' / 'activity.jsonl'
-        size = path.stat().st_size
-        tail_bytes = 8192
-        with path.open('rb') as f:
-            if size > tail_bytes:
-                f.seek(-tail_bytes, 2)
-            tail = f.read().decode('utf-8', errors='ignore')
-        for line in reversed(tail.splitlines()):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                obj = json.loads(line)
-            except Exception:
-                continue
-            if obj.get('kind') == 'hook':
-                return obj.get('name') or None
-        return None
-    except Exception:
-        return None
-
-
 # ── Line renderers ────────────────────────────────────────────────────────────
 
-def render_morph_line(feature, hook_name, columns):
+def render_morph_line(feature, columns):
     """Line 0 — the active MORPH feature.
 
     Goes through join_to_width like the status line: a feature name plus phase,
-    slice bar, gate and hook is the longest thing this script prints, and a
+    slice bar and gate is the longest thing this script prints, and a
     wrapping line 0 would defeat the whole point of the single-row layout.
     """
     parts = [(0, f"{CYAN}{BOLD}► {feature['name']}{R}")]
@@ -523,9 +487,6 @@ def render_morph_line(feature, hook_name, columns):
     if feature['pending']:
         parts.append((2, f"{RED}⛔ gate: {feature['pending']}{R}"))
 
-    if hook_name:
-        parts.append((4, f"{GRAY}🪝 {hook_name}{R}"))
-
     return join_to_width(parts, columns)
 
 
@@ -722,10 +683,8 @@ def main():
         # worktree. In the primary tree it resurrects stale feature names
         # during unrelated work, so there the status line is a single row.
         if get_worktree_label(payload, cwd):
-            hook_name = get_last_hook(cwd)
             for feature in get_active_features(cwd):
-                print(render_morph_line(feature, hook_name, columns))
-                hook_name = None  # annotate the first line only
+                print(render_morph_line(feature, columns))
 
         status_line = render_status_line(payload, cwd, settings, columns)
         if status_line:

package/framework/hooks/shared/build-check.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 
 const DOTNET_BUILD_CMD = 'dotnet build --no-restore --nologo -v q';
 const TSC_BUILD_CMD = 'npx tsc --noEmit';
+const ESLINT_CONFIGS = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs'];
 
 export function isDotnetStack(s) {
   return s.includes('dotnet') || s.includes('aspnet');
@@ -13,26 +14,9 @@ function isFrontendStack(s) {
   return s.includes('nextjs') || s.includes('node') || s.includes('react') || s.includes('vue');
 }
 
-// Single stack only: a compound stack resolves to `dotnet build` alone. Use
-// `getBuildSteps()` for those.
-export function getBuildCommand(stack, hasTsConfig = false) {
-  if (!stack) return null;
-  const s = stack.toLowerCase();
-
-  if (isDotnetStack(s)) {
-    return DOTNET_BUILD_CMD;
-  }
-
-  if (isFrontendStack(s) && hasTsConfig) {
-    return TSC_BUILD_CMD;
-  }
-
-  return null;
-}
-
 // A compound stack checks BOTH sides, each from its own directory.
 // `backendTarget` names the solution when the backend directory holds none.
-export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTarget } = {}) {
+export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTarget, lintFiles = [] } = {}) {
   if (!stack || !cwd) return [];
   const s = stack.toLowerCase();
   const steps = [];
@@ -51,6 +35,15 @@ export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTa
     ) {
       steps.push({ command: TSC_BUILD_CMD, cwd: frontendDir });
     }
+    // Only the files the feature touched: legacy lint debt never turns a feature's verify red.
+    if (
+      lintFiles.length > 0 &&
+      ESLINT_CONFIGS.some((name) => existsSync(join(frontendDir, name))) &&
+      existsSync(join(frontendDir, 'node_modules', 'eslint'))
+    ) {
+      const files = lintFiles.map((file) => JSON.stringify(file)).join(' ');
+      steps.push({ command: `npx eslint --quiet --no-warn-ignored ${files}`, cwd: frontendDir });
+    }
   }
 
   return steps;
@@ -68,7 +61,7 @@ export function parseBuildResult(exitCode, output) {
 
 /** @returns {{ status: 'pass'|'fail'|'skip', output: string }} */
 export function runBuildCheck(cwd, stack, timeout = 30000, paths = {}) {
-  const steps = getBuildSteps(stack, { cwd, frontendPath: paths.frontendPath, backendPath: paths.backendPath, backendTarget: paths.backendTarget });
+  const steps = getBuildSteps(stack, { cwd, frontendPath: paths.frontendPath, backendPath: paths.backendPath, backendTarget: paths.backendTarget, lintFiles: paths.lintFiles });
   if (steps.length === 0) return { status: 'skip', output: '' };
 
   const failures = [];

package/framework/hooks/shared/comment-rules.js

@@ -37,6 +37,15 @@ function isBanner(text) {
   return words === '' || /^[-=*#~_+]{3,}.*[-=*#~_+]{3,}$/.test(body);
 }
 
+const CODE_KEYWORD = /^(?:const|let|var|return|await|throw|if|else|for|foreach|while|switch|import|export|using|new|public|private|protected|internal|function|class)\b/;
+
+function isCommentedCode(text) {
+  const body = bodyOf(text);
+  if (/^[}\])]+[;,)]*$/.test(body)) return true;
+  if (/\{$/.test(body)) return CODE_KEYWORD.test(body) || /[=(]/.test(body);
+  return /;$/.test(body) && (CODE_KEYWORD.test(body) || /[=(.]/.test(body));
+}
+
 function isDocComment(text, isCs) {
   return isCs ? /^\/\/\/(?!\/)/.test(text) : /^\/\*\*(?!\*)/.test(text);
 }
@@ -103,7 +112,7 @@ function addedRegionLines(before, after) {
   return out;
 }
 
-/** @returns {Array<{ line: number, rule: 'process'|'banner'|'doc-comment'|'long-block', text: string }>} */
+/** @returns {Array<{ line: number, rule: 'process'|'banner'|'commented-code'|'doc-comment'|'long-block', text: string }>} */
 export function commentFindings({ file, before, after, docCommentsForbidden: docForbidden = false }) {
   const isCs = /\.cs$/i.test(file);
   const all = commentLines(after, file);
@@ -120,6 +129,7 @@ export function commentFindings({ file, before, after, docCommentsForbidden: doc
     if (ALLOWED.some((re) => re.test(text))) continue;
     if (citesProcess(text)) flag(line, 'process', text);
     else if (isBanner(text)) flag(line, 'banner', text);
+    else if (!isDocComment(text, isCs) && isCommentedCode(text)) flag(line, 'commented-code', text);
   }
   for (const { line, text } of addedRegionLines(before, after)) flag(line, 'banner', text);
 

package/framework/hooks/shared/feature-locator.js

@@ -4,6 +4,7 @@
 
 import { execSync } from 'child_process';
 import { loadState } from './state-reader.js';
+import { morphBranchFeature } from './git-paths.js';
 
 // `loadState`, not a directory listing: it also sees features only the index carries.
 export function featureNamesIn(root) {
@@ -55,26 +56,27 @@ export function unrecognizedSlugLike(text, names) {
   return tokens.find((t) => !known.has(t)) ?? null;
 }
 
-// The session root wins a feature present in both trees: it is where
-// `morph-spec approve` would write from that cwd.
+// The tree on `morph/<f>` owns the feature and wins: the primary root only carries its index
+// entry, and `morph-spec approve` refuses any other tree. Without an owner, the session root wins.
 export function locateFeatureForQuestion(text, sessionRoot) {
   const trees = allWorkTrees(sessionRoot);
   const localNames = featureNamesIn(sessionRoot);
+  const ownerOr = (name, root) => trees.find((t) => morphBranchFeature(t) === name) ?? root;
 
   const local = featureNamedIn(text, localNames);
-  if (local) return { name: local, root: sessionRoot };
+  if (local) return { name: local, root: ownerOr(local, sessionRoot) };
 
   for (const root of trees) {
     if (root === sessionRoot) continue;
     const found = featureNamedIn(text, featureNamesIn(root));
-    if (found) return { name: found, root };
+    if (found) return { name: found, root: ownerOr(found, root) };
   }
 
   const allNames = trees.flatMap(featureNamesIn);
   if (unrecognizedSlugLike(text, allNames)) return null;
 
   // With exactly ONE feature in the tree there is nothing else the answer could be about.
-  if (localNames.length === 1) return { name: localNames[0], root: sessionRoot };
+  if (localNames.length === 1) return { name: localNames[0], root: ownerOr(localNames[0], sessionRoot) };
 
   return null;
 }

package/framework/hooks/shared/heavy-command.js

@@ -106,6 +106,18 @@ export function heavyKind(command) {
   return null;
 }
 
+const E2E_CLASS = /\be2e\b|playwright|compose up/;
+const UNIT_CLASS = /^(tests|(npx )?(vitest|jest)|(npm|pnpm|yarn|bun) (test|run test(:\S+)?))$/;
+
+// Maps a `heavyKind` label or a verify node to the RAM class it pays. `dotnet test` and anything
+// unknown stay `build`: they compile before running, and the fallback must never lower a floor.
+export function heavyClass(label) {
+  const s = String(label ?? '').toLowerCase().trim();
+  if (E2E_CLASS.test(s)) return 'e2e';
+  if (UNIT_CLASS.test(s)) return 'unit';
+  return 'build';
+}
+
 // The lease has no live process to watch: this TTL is the only thing that frees it after a
 // denied or interrupted call.
 const BASH_DEFAULT_TIMEOUT_MS = 2 * 60_000;

package/framework/hooks/shared/heavy-config.js

@@ -7,6 +7,7 @@ export const HEAVY_DEFAULTS = Object.freeze({
   enabled: true,
   slots: 2,
   minFreeMemGb: 4,
+  minFreeMemGbByKind: Object.freeze({ unit: 1.5, build: 4, e2e: 4 }),
   waitTimeoutSec: 600,
   maxHoldMinutes: 90,
   shutdownBuildServer: true,
@@ -14,11 +15,16 @@ export const HEAVY_DEFAULTS = Object.freeze({
   gateBash: false,
 });
 
+export const HEAVY_KINDS = Object.freeze(['unit', 'build', 'e2e']);
+
 const isBool = (v) => typeof v === 'boolean';
+const isGb = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const VALID = {
   enabled: isBool,
   slots: (v) => Number.isInteger(v) && v >= 1,
-  minFreeMemGb: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  minFreeMemGb: isGb,
+  minFreeMemGbByKind: isPlainObject,
   waitTimeoutSec: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
   maxHoldMinutes: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0,
   shutdownBuildServer: isBool,
@@ -40,6 +46,7 @@ export function resolveHeavyConfig(config, env = process.env) {
   const out = { ...HEAVY_DEFAULTS };
   const warnings = [];
   const raw = config?.heavy;
+  let byKind = {};
 
   if (raw !== undefined) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -47,12 +54,15 @@ export function resolveHeavyConfig(config, env = process.env) {
     } else {
       for (const [key, value] of Object.entries(raw)) {
         if (!(key in VALID)) warnings.push(`heavy.${key} não existe; ignorada`);
+        else if (key === 'minFreeMemGbByKind' && VALID[key](value)) byKind = value;
         else if (VALID[key](value)) out[key] = value;
         else warnings.push(`heavy.${key} inválida (${JSON.stringify(value)}); usando ${JSON.stringify(HEAVY_DEFAULTS[key])}`);
       }
     }
   }
 
+  out.minFreeMemGbByKind = resolveByKind(byKind, isGb(raw?.minFreeMemGb) ? raw.minFreeMemGb : null, warnings);
+
   if (/^(off|0|false)$/i.test(env.MORPH_HEAVY ?? '')) out.enabled = false;
   const envSlots = Number(env.MORPH_HEAVY_SLOTS);
   if (env.MORPH_HEAVY_SLOTS !== undefined && VALID.slots(envSlots)) out.slots = envSlots;
@@ -60,6 +70,23 @@ export function resolveHeavyConfig(config, env = process.env) {
   return { ...out, warnings };
 }
 
+// An explicit `minFreeMemGb` without a per-kind entry still governs that kind:
+// a project that set 0 (RAM check off) or a stricter floor keeps it after the split.
+function resolveByKind(byKind, explicitFloor, warnings) {
+  const out = {};
+  for (const kind of HEAVY_KINDS) out[kind] = explicitFloor ?? HEAVY_DEFAULTS.minFreeMemGbByKind[kind];
+  for (const [kind, value] of Object.entries(byKind)) {
+    if (!HEAVY_KINDS.includes(kind)) warnings.push(`heavy.minFreeMemGbByKind.${kind} não existe; use ${HEAVY_KINDS.join(', ')}`);
+    else if (isGb(value)) out[kind] = value;
+    else warnings.push(`heavy.minFreeMemGbByKind.${kind} inválida (${JSON.stringify(value)}); usando ${out[kind]}`);
+  }
+  return out;
+}
+
+export function minFreeMemFor(config, kind) {
+  return config.minFreeMemGbByKind?.[kind] ?? config.minFreeMemGb;
+}
+
 export function readHeavyConfig(projectPath, env = process.env) {
   return resolveHeavyConfig(readProjectConfig(projectPath), env);
 }

package/framework/hooks/shared/heavy-slots.js

@@ -49,6 +49,8 @@ function liveHoldersPruningStale(dir, ctx) {
   return live;
 }
 
+const kindSuffix = (kind) => (kind ? ` (${kind})` : '');
+
 function blockedText(blocked, slots, now) {
   const holders = blocked.holders.map((h) => describeHolder(h, now)).join('; ');
   if (blocked.reason === 'exclusive') return `aguardando limpeza do servidor de build (${describeHolder(blocked.exclusive, now)})`;
@@ -56,14 +58,14 @@ function blockedText(blocked, slots, now) {
     const cause = blocked.holders.length
       ? `slots em uso: ${holders}`
       : 'nenhum slot em uso: a pressão vem de fora do semáforo (vmmem do WSL, IDE, outros processos)';
-    return `aguardando RAM livre: ${blocked.freeGb.toFixed(1)} GB < ${blocked.minFreeMemGb} GB mínimos — ${cause}`;
+    return `aguardando RAM livre${kindSuffix(blocked.kind)}: ${blocked.freeGb.toFixed(1)} GB < ${blocked.minFreeMemGb} GB mínimos — ${cause}`;
   }
   return `aguardando slot pesado (${blocked.holders.length}/${slots}): ${holders}`;
 }
 
 function tryClaim(dir, opts, ctx) {
   const {
-    slots, label, feature, node, cwd, minFreeMemGb, freeMem, lease: leaseSpec,
+    slots, label, feature, node, cwd, minFreeMemGb, freeMem, kind, lease: leaseSpec,
   } = opts;
   const guarded = withClaimMutex(dir, () => {
     const holders = liveHoldersPruningStale(dir, ctx);
@@ -71,7 +73,7 @@ function tryClaim(dir, opts, ctx) {
     if (exclusive) return { blocked: { reason: 'exclusive', holders, exclusive } };
     if (holders.length >= slots) return { blocked: { reason: 'slots', holders } };
     const freeGb = freeMem() / GB;
-    if (minFreeMemGb > 0 && freeGb < minFreeMemGb) return { blocked: { reason: 'memory', holders, freeGb, minFreeMemGb } };
+    if (minFreeMemGb > 0 && freeGb < minFreeMemGb) return { blocked: { reason: 'memory', holders, freeGb, minFreeMemGb, kind } };
 
     for (let i = 0; i < slots + holders.length + 1; i++) {
       const path = join(dir, `slot-${i}.lock`);
@@ -124,7 +126,13 @@ export function acquireHeavy(opts) {
     const { blocked } = attempt;
     if (waited >= waitTimeoutMs) {
       return {
-        status: 'busy', reason: blocked.reason, holders: blocked.holders, freeGb: blocked.freeGb ?? null, waitedMs: waited,
+        status: 'busy',
+        reason: blocked.reason,
+        holders: blocked.holders,
+        freeGb: blocked.freeGb ?? null,
+        minFreeMemGb: claimOpts.minFreeMemGb,
+        kind: opts.kind ?? null,
+        waitedMs: waited,
       };
     }
     if (blocked.reason !== 'contended' && now() - lastReport >= REPORT_EVERY_MS) {
@@ -135,6 +143,32 @@ export function acquireHeavy(opts) {
   }
 }
 
+// For a holder whose next node needs more RAM than it was admitted with: it keeps its slot and
+// waits only on memory, since re-claiming would hit the re-entrant path and skip the check.
+export function awaitFreeMemory(opts) {
+  const {
+    minFreeMemGb, waitTimeoutMs, kind = null,
+    now = Date.now, sleep = sleepSync, freeMem = freemem, log = (m) => process.stderr.write(`${m}\n`),
+  } = opts;
+  const start = now();
+  let lastReport = -Infinity;
+  for (;;) {
+    const freeGb = freeMem() / GB;
+    const waited = now() - start;
+    if (!(minFreeMemGb > 0) || freeGb >= minFreeMemGb) return { status: 'acquired', waitedMs: waited };
+    if (waited >= waitTimeoutMs) {
+      return {
+        status: 'busy', reason: 'memory', holders: [], freeGb, minFreeMemGb, kind, waitedMs: waited,
+      };
+    }
+    if (now() - lastReport >= REPORT_EVERY_MS) {
+      log(`aguardando RAM livre${kindSuffix(kind)}: ${freeGb.toFixed(1)} GB < ${minFreeMemGb} GB mínimos, segurando o slot já tomado`);
+      lastReport = now();
+    }
+    sleep(Math.min(POLL_MS, Math.max(1, waitTimeoutMs - waited)));
+  }
+}
+
 export function updateLease(lease, patch) {
   if (!lease) return;
   try {
@@ -168,7 +202,9 @@ export function releaseLeaseById(dir, id) {
 export function describeBusy(result, config) {
   const waited = Math.round(result.waitedMs / 1000);
   if (result.reason === 'memory') {
-    return `sem RAM livre há ${waited}s (${result.freeGb?.toFixed(1)} GB < ${config.minFreeMemGb} GB mínimos, heavy.minFreeMemGb)`;
+    const floor = result.minFreeMemGb ?? config.minFreeMemGb;
+    const key = result.kind ? `heavy.minFreeMemGbByKind.${result.kind}` : 'heavy.minFreeMemGb';
+    return `sem RAM livre há ${waited}s (${result.freeGb?.toFixed(1)} GB < ${floor} GB mínimos${kindSuffix(result.kind)}, ${key})`;
   }
   if (result.reason === 'exclusive') return `limpeza do servidor de build ainda em curso após ${waited}s`;
   return `${result.holders.length}/${config.slots} slots pesados ocupados por ${waited}s (heavy.waitTimeoutSec)`;

package/framework/hooks/shared/hook-response.js

@@ -30,10 +30,6 @@ export function blockResult(reason) {
   return { decision: 'block', reason };
 }
 
-export function approveResult(context) {
-  return context ? { decision: 'approve', additionalContext: context } : null;
-}
-
 export function contextResult(text, eventName) {
   return { hookSpecificOutput: { hookEventName: eventName, additionalContext: text } };
 }

package/framework/hooks/shared/payload-utils.js

@@ -1,29 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync } from 'fs';
-import { dirname, join, isAbsolute } from 'path';
-
-// A sub-agent may edit inside its own worktree: the build root comes from the
-// file, not from the session's cwd.
-export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.json']) {
-  try {
-    if (!filePath) return fallbackCwd;
-    let p = String(filePath).replace(/\\/g, '/');
-    if (!isAbsolute(p)) p = join(fallbackCwd, p);
-
-    let dir = dirname(p);
-    let prev = null;
-    while (dir && dir !== prev) {
-      for (const marker of markers) {
-        if (existsSync(join(dir, marker))) return dir;
-      }
-      prev = dir;
-      dir = dirname(dir);
-    }
-    return fallbackCwd;
-  } catch {
-    return fallbackCwd;
-  }
-}
+import { join, isAbsolute } from 'path';
 
 // State is resolved from the target PATH, never the session: a session in the
 // primary root may write a feature that lives in a worktree. `lastIndexOf` picks
@@ -58,16 +34,6 @@ export function getFilePath(payload) {
   return raw.replace(/\\/g, '/');
 }
 
-export function getContentToValidate(payload) {
-  const input = payload?.tool_input;
-  if (!input) return '';
-  return input.content || input.new_string || '';
-}
-
-export function isWriteOperation(payload) {
-  return typeof payload?.tool_input?.content === 'string';
-}
-
 export function getToolName(payload) {
   return payload?.tool_name || 'unknown';
 }