@polymorphism-tech/morph-spec 8.41.0 → 8.43.0

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

@@ -51,34 +51,35 @@ import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registr
 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';
+import { isInContainer } from '../../shared/worktree-root.js';
+import { isSecondaryWorktree, resolveGitCommonDir } from '../../shared/git-paths.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-function gitRevParse(arg, dir) {
-  return execSync(`git rev-parse ${arg}`, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] })
-    .toString()
-    .trim();
-}
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
 
-/**
- * A secondary git worktree has a `--git-dir` (worktree-private, under
- * `.../.git/worktrees/{name}`) distinct from its `--git-common-dir` (the
- * primary repo's shared `.git`). In the primary root both resolve to the
- * same path. Any git error (not a repo at all) is treated as "not a
- * worktree" — fail-open.
- */
-function isSecondaryWorktree(dir) {
+// Inside a worktree Claude Code keeps CLAUDE_PROJECT_DIR at the project root and moves only the payload `cwd`.
+function sessionDir(payload) {
+  const base = projectDir();
+  const cwd = typeof payload?.cwd === 'string' ? payload.cwd : '';
+  if (!cwd || samePath(resolve(cwd), resolve(base))) return base;
   try {
-    const gitDir = gitRevParse('--git-dir', dir);
-    const commonDir = gitRevParse('--git-common-dir', dir);
-    return gitDir !== commonDir;
+    const common = resolveGitCommonDir(cwd);
+    return common && samePath(resolve(common), resolve(resolveGitCommonDir(base) ?? '')) && isSecondaryWorktree(cwd) ? cwd : base;
   } catch {
-    return false;
+    return base;
   }
 }
 
+function gitRevParse(arg, dir) {
+  return execSync(`git rev-parse ${arg}`, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] })
+    .toString()
+    .trim();
+}
+
 /** Feature name from the current branch, if it matches `morph/{feature}`. */
 function featureFromBranch(dir) {
   try {
@@ -118,8 +119,7 @@ function isOutsideContainer(dir) {
   try {
     const common = resolve(dir, gitRevParse('--git-common-dir', dir)).replace(/\\/g, '/');
     const root = common.replace(/\/\.git$/, '');
-    const norm = resolve(dir).replace(/\\/g, '/');
-    return !['worktrees', '.worktrees'].some((d) => norm.startsWith(`${root}/${d}/`));
+    return !isInContainer(root, dir);
   } catch {
     return false;
   }
@@ -280,7 +280,7 @@ function claimBlock(dir, feature, sessionId) {
  */
 export async function run(payload) {
   try {
-    const dir = projectDir();
+    const dir = sessionDir(payload);
     // The SessionStart payload carries session_id — the identity the claim
     // registry uses to tell "me" from "another session".
     const sessionId = payload?.session_id || `pid-${process.pid}`;
@@ -303,6 +303,7 @@ export async function run(payload) {
     // Returns immediately — nothing here waits on graphify.
     try { seedFromPrimary(dir); } catch { /* non-blocking — a no-op on the root */ }
     try { kickGraphRefresh(dir); } catch { /* non-blocking */ }
+    try { kickAgentReap(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const task = taskFromBranch(dir);

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

@@ -43,8 +43,7 @@ import { homedir } from 'os';
 import { stateExists } from '../../shared/state-reader.js';
 import { resolveGitCommonDir } from '../../shared/git-paths.js';
 import { runMorphSpec } from '../../shared/morph-cli.js';
-
-const WORKTREES_DIR = 'worktrees';
+import { newWorktreesDir } from '../../shared/worktree-root.js';
 
 const fwd = (p) => String(p).replace(/\\/g, '/');
 
@@ -152,14 +151,15 @@ function defaultBranch(root) {
  */
 function gitFallback(root, name, base) {
   const branch = `morph-task/${name}`;
-  const path = `${root}/${WORKTREES_DIR}/${name}`;
+  const container = newWorktreesDir(root);
+  const path = `${container}/${name}`;
   if (existsSync(path)) return { path };
   try { git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], root); }
   catch {
     const from = base || defaultBranch(root);
     git(from ? ['branch', branch, from] : ['branch', branch], root);
   }
-  mkdirSync(join(root, WORKTREES_DIR), { recursive: true });
+  mkdirSync(container, { recursive: true });
   git(['worktree', 'add', path, branch], root);
   return { path };
 }

package/framework/hooks/shared/agent-reap.js

@@ -0,0 +1,89 @@
+/**
+ * agent-reap.js — dispara `morph-spec worktree reap` em background no SessionStart.
+ *
+ * O hook de SessionStart tem 5 s de timeout e o reaper mede git por árvore: por isso o
+ * disparo só olha o disco (nenhum subprocesso) e solta este arquivo como worker DESTACADO
+ * (`--run <raiz>`), que chama o CLI. Só a raiz: o worker nasce com `cwd` no git common dir
+ * e nunca segura o diretório de uma worktree.
+ *
+ * Fail-open em tudo. `MORPH_WORKTREE_REAP=0` desliga.
+ *
+ * @module agent-reap
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { isSecondaryWorktree, resolveGitCommonDir } from './git-paths.js';
+import { primaryTree } from './graph-freshness.js';
+import { runMorphSpec } from './morph-cli.js';
+
+const WORKER = fileURLToPath(import.meta.url);
+const THROTTLE_MS = 10 * 60_000;
+const WORKER_TIMEOUT_MS = 15 * 60_000;
+const ADMIN_DIR = /^agent-[0-9a-f]+\d*$/;
+const AGENT_BRANCH_FILE = /^agent-[0-9a-f]+$/;
+
+function anyEntry(dir, pattern) {
+  try { return readdirSync(dir).some((name) => pattern.test(name)); } catch { return false; }
+}
+
+/** Uma worktree de agent registrada, ou uma branch `morph-task/agent-*` (solta ou empacotada). */
+export function hasAgentLeftovers(common) {
+  if (anyEntry(join(common, 'worktrees'), ADMIN_DIR)) return true;
+  if (anyEntry(join(common, 'refs', 'heads', 'morph-task'), AGENT_BRANCH_FILE)) return true;
+  try {
+    return /refs\/heads\/morph-task\/agent-[0-9a-f]+/.test(readFileSync(join(common, 'packed-refs'), 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function recentlyKicked(marker, now) {
+  try {
+    const age = now - Number(readFileSync(marker, 'utf8'));
+    return age >= 0 && age < THROTTLE_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} dir - diretório do projeto da sessão
+ * @returns {{ kicked: boolean, reason?: string, pid?: number }}
+ */
+export function kickAgentReap(dir, { spawnFn = spawn, env = process.env, now = Date.now } = {}) {
+  if (env.MORPH_WORKTREE_REAP === '0') return { kicked: false, reason: 'disabled' };
+  const common = resolveGitCommonDir(dir);
+  const root = common && primaryTree(dir);
+  if (!root) return { kicked: false, reason: 'not-a-repo' };
+  if (isSecondaryWorktree(dir)) return { kicked: false, reason: 'secondary-worktree' };
+  if (!hasAgentLeftovers(common)) return { kicked: false, reason: 'nothing-to-reap' };
+
+  const marker = join(common, 'morph-spec', 'agent-reap.kick');
+  if (recentlyKicked(marker, now())) return { kicked: false, reason: 'throttled' };
+  try {
+    mkdirSync(join(common, 'morph-spec'), { recursive: true });
+    writeFileSync(marker, String(now()));
+    const child = spawnFn(process.execPath, [WORKER, '--run', root], {
+      cwd: common, env, detached: true, stdio: 'ignore', windowsHide: true,
+    });
+    child.on?.('error', () => {});
+    child.unref?.();
+    return { kicked: true, pid: child.pid };
+  } catch {
+    return { kicked: false, reason: 'spawn-failed' };
+  }
+}
+
+const isMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const norm = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
+  return norm(argv1) === norm(WORKER);
+})();
+
+if (isMain && process.argv[2] === '--run' && process.argv[3] && existsSync(process.argv[3])) {
+  try { runMorphSpec(['worktree', 'reap', '--json'], { cwd: process.argv[3], timeoutMs: WORKER_TIMEOUT_MS }); } catch { /* fail-open */ }
+}

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

@@ -0,0 +1,171 @@
+/**
+ * The comment shapes the `architecture-code-comments` standard forbids in
+ * every case, judged only on the comments an edit ADDED. Whether a short
+ * comment restates the code is not decidable here; that stays with the
+ * Gate 3 evaluator and the `code-budget` density.
+ *
+ * @module comment-rules
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+import { citesProcess, commentLines } from './comment-scanner.js';
+
+export const MAX_BLOCK_LINES = 3;
+
+const ALLOWED = [
+  /READS STANDARDS?:/,
+  /\bVERIFY:/,
+  /eslint-(?:disable|enable)/,
+  /@ts-(?:ignore|expect-error|nocheck|check)/,
+  /<auto-generated/i,
+  /prettier-ignore/,
+  /ReSharper\s+(?:disable|restore)/,
+  /@(?:vitest|jest)-environment/,
+  /^\/\/\/\s*<reference\b/,
+  /^#!/,
+  /istanbul ignore|c8 ignore|v8 ignore/,
+];
+
+const DECORATION = /[-=*#~_+]{3,}/;
+const REGION = /^\s*#\s*(?:end)?region\b/;
+
+function bodyOf(text) {
+  return text.replace(/^(?:\/\/+|\/\*+|\*+)/, '').replace(/\*+\/$/, '').trim();
+}
+
+function isBanner(text) {
+  const body = bodyOf(text);
+  if (REGION.test(body)) return true;
+  if (!DECORATION.test(body)) return false;
+  const words = body.replace(/[-=*#~_+|]/g, '').trim();
+  return words === '' || /^[-=*#~_+]{3,}.*[-=*#~_+]{3,}$/.test(body);
+}
+
+function isDocComment(text, isCs) {
+  return isCs ? /^\/\/\/(?!\/)/.test(text) : /^\/\*\*(?!\*)/.test(text);
+}
+
+function nearest(startDir, test) {
+  let dir = startDir;
+  for (;;) {
+    const hit = test(dir);
+    if (hit) return hit;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Doc-comments are allowed only on a package consumed outside the repo. When
+ * that cannot be read from the nearest project file, the rule stays quiet.
+ *
+ * @param {string} file - absolute path of the edited file
+ * @returns {boolean}
+ */
+export function docCommentsForbidden(file) {
+  const dir = dirname(file);
+  if (/\.cs$/i.test(file)) {
+    const proj = nearest(dir, (d) => {
+      try {
+        const name = readdirSync(d).find((n) => /\.csproj$/i.test(n));
+        return name ? join(d, name) : null;
+      } catch {
+        return null;
+      }
+    });
+    if (!proj) return false;
+    const xml = readFileSync(proj, 'utf8');
+    return !/<(?:IsPackable|GeneratePackageOnBuild)>\s*true\s*</i.test(xml) && !/<PackageId>/i.test(xml);
+  }
+  const pkg = nearest(dir, (d) => (existsSync(join(d, 'package.json')) ? join(d, 'package.json') : null));
+  if (!pkg) return false;
+  return JSON.parse(readFileSync(pkg, 'utf8')).private === true;
+}
+
+/** Lines of `after` whose comment is not one `before` already had (moved comments do not count). */
+function addedCommentLines(before, after, file) {
+  const remaining = new Map();
+  for (const text of commentLines(before, file).values()) {
+    remaining.set(text, (remaining.get(text) ?? 0) + 1);
+  }
+  const added = new Map();
+  for (const [line, text] of commentLines(after, file)) {
+    const left = remaining.get(text) ?? 0;
+    if (left > 0) remaining.set(text, left - 1);
+    else added.set(line, text);
+  }
+  return added;
+}
+
+function addedRegionLines(before, after) {
+  const old = new Map();
+  for (const row of before.split('\n')) {
+    if (REGION.test(row)) old.set(row.trim(), (old.get(row.trim()) ?? 0) + 1);
+  }
+  const out = [];
+  after.split('\n').forEach((row, i) => {
+    if (!REGION.test(row)) return;
+    const left = old.get(row.trim()) ?? 0;
+    if (left > 0) old.set(row.trim(), left - 1);
+    else out.push({ line: i + 1, text: row.trim() });
+  });
+  return out;
+}
+
+/**
+ * @param {{ file: string, before: string, after: string, docCommentsForbidden?: boolean }} input
+ * @returns {Array<{ line: number, rule: 'process'|'banner'|'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);
+  const added = addedCommentLines(before, after, file);
+  const findings = [];
+  const flagged = new Set();
+  const flag = (line, rule, text) => {
+    if (flagged.has(line)) return;
+    flagged.add(line);
+    findings.push({ line, rule, text });
+  };
+
+  for (const [line, text] of added) {
+    if (ALLOWED.some((re) => re.test(text))) continue;
+    if (citesProcess(text)) flag(line, 'process', text);
+    else if (isBanner(text)) flag(line, 'banner', text);
+  }
+  for (const { line, text } of addedRegionLines(before, after)) flag(line, 'banner', text);
+
+  if (docForbidden) {
+    for (const [line, text] of added) {
+      const opensBlock = !isCs || !isDocComment(all.get(line - 1) ?? '', isCs);
+      if (isDocComment(text, isCs) && opensBlock) flag(line, 'doc-comment', text);
+    }
+  }
+
+  const rows = after.split('\n');
+  const lines = [...all.keys()]
+    .filter((line) => (rows[line - 1] ?? '').trim() === all.get(line))
+    .sort((a, b) => a - b);
+  let run = [];
+  const closeRun = () => {
+    if (run.length && isDocComment(all.get(run[0]), isCs)) {
+      run = [];
+      return;
+    }
+    const addedInRun = run.filter((l) => added.has(l) && !ALLOWED.some((re) => re.test(all.get(l))));
+    if (addedInRun.length > MAX_BLOCK_LINES) {
+      flag(run[0], 'long-block', `${run.length} linhas: ${all.get(run[0])}`);
+    }
+    run = [];
+  };
+  for (const line of lines) {
+    if (run.length && line !== run[run.length - 1] + 1) closeRun();
+    run.push(line);
+  }
+  closeRun();
+
+  return findings.sort((a, b) => a.line - b.line);
+}

package/{src/lib/validators/code-budget → framework/hooks/shared}/comment-scanner.js

@@ -5,10 +5,10 @@
  * comentário de string para o `doctor --ai`, com a sintaxe de TS/JS ligada
  * fora do C#. Um regex por linha confundiria `https://` com comentário.
  *
- * @module code-budget-comment-scanner
+ * @module comment-scanner
  */
 
-import { stripComments } from '../../ai/comment-stripper.js';
+import { stripComments } from './comment-stripper.js';
 
 /** Vocabulário de processo do morph-spec, fora o id de task (abaixo). */
 const PROCESS_CITATION = [

package/{src/lib/ai → framework/hooks/shared}/comment-stripper.js

@@ -11,7 +11,8 @@
  *     canônico `model-registry.v2.json` usa e que o leitor C# do kit aceita de
  *     propósito (`JsonCommentHandling.Skip`, `AllowTrailingCommas`);
  *   - `dotnet-test-introspection.js` — lê o `global.json` por `jsoncToJson`;
- *   - `validators/code-budget/comment-scanner.js` — acha as linhas de
+ *   - `comment-scanner.js` (ao lado; lido pelo `code-budget` e pelo hook
+ *     `comment-guard`) — acha as linhas de
  *     comentário de `.cs`/`.ts`/`.js`, e é o único que liga a opção `js`.
  *
  * **Por que não um regex.** O exemplar tem `"http://localhost:11434/v1"` e uma

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

@@ -675,7 +675,7 @@ function sleep(ms) {
 
 /** Tear the stack down. Best-effort: teardown failure never fails a check. */
 export function tearDownStack(cwd, { composeFile, projectName, env, volumes = false } = {}, exec = defaultExec) {
-  const args = [...composeArgs(composeFile, projectName), 'down'];
+  const args = [...composeArgs(composeFile, projectName), 'down', '--remove-orphans'];
   if (volumes) args.push('-v');
   const result = exec('docker', args, { cwd, env });
   return { status: result.code === 0 ? 'pass' : 'fail', output: result.output };
@@ -863,6 +863,7 @@ export function runE2eCheck(cwd, options = {}) {
     insideWorktree = isSecondaryWorktree(cwd),
     healthTimeout = DEFAULT_HEALTH_TIMEOUT,
     specTimeout = DEFAULT_SPEC_TIMEOUT,
+    beforeHeavy = null,
     _exec: exec = defaultExec,
   } = options;
 
@@ -910,6 +911,7 @@ export function runE2eCheck(cwd, options = {}) {
     : {};
   const composeEnv = { COMPOSE_PROJECT_NAME: projectName, ...authEnv, ...(env || {}) };
 
+  if (typeof beforeHeavy === 'function') beforeHeavy();
   const up = bringUpStack(
     cwd,
     { composeFile, projectName, gitCommonDir, env: composeEnv, forceFresh, healthTimeout },

package/framework/hooks/shared/graph-refresh.js

@@ -50,6 +50,7 @@ import { fileURLToPath } from 'url';
 import { readPrimaryHead, resolveGitCommonDir, workTreeTop } from './git-paths.js';
 import { findFirstOnPath, quoteForCmd } from './morph-cli.js';
 import { ensureCommonExclude } from './git-exclude.js';
+import { pidAlive } from './process-alive.js';
 import {
   GRAPH_DIR, graphFile, graphFreshness, ignoreRulesHash, primaryTree, readRefreshRecord,
   recordRefreshRun, refreshPending, treeKey, writeRefreshRecord,
@@ -110,15 +111,6 @@ function mtimeOf(path) {
   }
 }
 
-function pidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err?.code === 'EPERM';
-  }
-}
-
 /**
  * Estado do lock do repositório — o que `graph status` mostra como "refresh em
  * andamento". A idade conta da última renovação: um lock de processo morto,

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

@@ -0,0 +1,128 @@
+import { tokenize } from './command-tokens.js';
+
+const DOTNET_HEAVY = new Set(['build', 'test', 'publish', 'pack', 'msbuild', 'vstest']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const HEAVY_SCRIPT = /^(test|build)(:.+)?$/;
+const WRAPPERS = new Set(['time', 'nohup', 'nice', 'command', 'exec', 'env']);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const INFO_FLAGS = new Set(['--help', '-h', '--version', '-?']);
+
+function splitSegments(command) {
+  const segments = [];
+  let current = '';
+  let quote = null;
+  const s = String(command || '');
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = null;
+      else if (ch === '\\' && quote === '"') current += s[++i] ?? '';
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; current += ch; continue; }
+    if (ch === '\\') { current += ch + (s[++i] ?? ''); continue; }
+    if (';|&\n'.includes(ch)) { segments.push(current); current = ''; continue; }
+    current += ch;
+  }
+  segments.push(current);
+  return segments;
+}
+
+function executable(token) {
+  return token.replace(/^.*[\\/]/, '').replace(/\.(exe|cmd|bat|ps1)$/i, '').toLowerCase();
+}
+
+function skipWrappers(tokens) {
+  let i = 0;
+  for (;;) {
+    const t = tokens[i];
+    if (t === undefined) return [];
+    if (ASSIGNMENT.test(t)) { i++; continue; }
+    if (t === 'timeout') { i += 2; continue; }
+    if (WRAPPERS.has(executable(t))) { i++; continue; }
+    return tokens.slice(i);
+  }
+}
+
+const DOCKER_VALUE_FLAGS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '-H', '--host', '--context']);
+
+function firstArg(args, valueFlags = new Set()) {
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith('-')) return args[i];
+    if (valueFlags.has(args[i])) i++;
+  }
+  return undefined;
+}
+
+function kindOfTokens(tokens) {
+  const [head, ...args] = tokens;
+  if (!head || args.some((a) => INFO_FLAGS.has(a))) return null;
+  const exe = executable(head);
+  const sub = firstArg(args, exe === 'docker' || exe === 'docker-compose' ? DOCKER_VALUE_FLAGS : undefined);
+
+  if (exe === 'dotnet') return DOTNET_HEAVY.has(sub) ? `dotnet ${sub}` : null;
+  if (exe === 'msbuild') return 'msbuild';
+  if (exe === 'vitest' || exe === 'jest') return exe;
+  if (exe === 'playwright') return sub === 'test' ? 'playwright test' : null;
+  if (exe === 'next' || exe === 'vite') return sub === 'build' ? `${exe} build` : null;
+
+  if (PACKAGE_MANAGERS.has(exe)) {
+    if (sub === 'test' || sub === 'build') return `${exe} ${sub}`;
+    if (sub === 'run' || sub === 'run-script') {
+      const script = args.slice(args.indexOf(sub) + 1).find((t) => !t.startsWith('-'));
+      return script && HEAVY_SCRIPT.test(script) ? `${exe} run ${script}` : null;
+    }
+    return null;
+  }
+
+  if (exe === 'npx' || exe === 'bunx') {
+    if (sub === 'vitest' || sub === 'jest') return `npx ${sub}`;
+    const rest = args.slice(args.indexOf(sub) + 1).find((t) => !t.startsWith('-'));
+    if (sub === 'playwright') return rest === 'test' ? 'npx playwright test' : null;
+    if (sub === 'next') return rest === 'build' ? 'npx next build' : null;
+    return null;
+  }
+
+  if (exe === 'docker-compose') return sub === 'up' || sub === 'build' ? `docker-compose ${sub}` : null;
+  if (exe === 'docker') {
+    if (sub === 'build' || sub === 'buildx') return `docker ${sub}`;
+    if (sub === 'compose') {
+      const action = firstArg(args.slice(args.indexOf(sub) + 1), DOCKER_VALUE_FLAGS);
+      return action === 'up' || action === 'build' ? `docker compose ${action}` : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first heavy command of a Bash command line, as a label, or null. Looks at the executable of
+ * each `;`/`&&`/`||`/`|`/newline segment, so `morph-spec heavy run -- dotnet test` and `echo "dotnet build"`
+ * are not heavy: the first runs under its own slot, the second runs nothing.
+ * @param {string} command
+ * @returns {string|null}
+ */
+export function heavyKind(command) {
+  for (const segment of splitSegments(command)) {
+    const tokens = skipWrappers(tokenize(segment.replace(/^[\s({]+/, '').replace(/[\s)}]+$/, '')));
+    const kind = kindOfTokens(tokens);
+    if (kind) return kind;
+  }
+  return null;
+}
+
+/**
+ * How long a foreground Bash call can run: its own `timeout` (capped at the platform maximum) plus slack.
+ * The lease has no live process to watch, so this is the only thing that frees it after a denied or
+ * interrupted call.
+ */
+const BASH_DEFAULT_TIMEOUT_MS = 2 * 60_000;
+const BASH_MAX_TIMEOUT_MS = 10 * 60_000;
+const LEASE_SLACK_MS = 30_000;
+
+export function leaseTtlMs(toolInput, env = process.env) {
+  const fallback = Number(env.BASH_DEFAULT_TIMEOUT_MS) || BASH_DEFAULT_TIMEOUT_MS;
+  const max = Math.max(Number(env.BASH_MAX_TIMEOUT_MS) || BASH_MAX_TIMEOUT_MS, fallback);
+  const asked = Number(toolInput?.timeout);
+  return Math.min(Number.isFinite(asked) && asked > 0 ? asked : fallback, max) + LEASE_SLACK_MS;
+}

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

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONFIG_FILE = join('.morph', 'config', 'config.json');
+
+export const HEAVY_DEFAULTS = Object.freeze({
+  enabled: true,
+  slots: 2,
+  minFreeMemGb: 4,
+  waitTimeoutSec: 600,
+  maxHoldMinutes: 90,
+  shutdownBuildServer: true,
+  disableNodeReuse: false,
+  gateBash: false,
+});
+
+const isBool = (v) => typeof v === 'boolean';
+const VALID = {
+  enabled: isBool,
+  slots: (v) => Number.isInteger(v) && v >= 1,
+  minFreeMemGb: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  waitTimeoutSec: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  maxHoldMinutes: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0,
+  shutdownBuildServer: isBool,
+  disableNodeReuse: isBool,
+  gateBash: isBool,
+};
+
+export function readProjectConfig(projectPath) {
+  const file = join(projectPath, CONFIG_FILE);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveHeavyConfig(config, env = process.env) {
+  const out = { ...HEAVY_DEFAULTS };
+  const warnings = [];
+  const raw = config?.heavy;
+
+  if (raw !== undefined) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      warnings.push('`heavy` no config.json não é um objeto; usando os padrões');
+    } else {
+      for (const [key, value] of Object.entries(raw)) {
+        if (!(key in VALID)) warnings.push(`heavy.${key} não existe; ignorada`);
+        else if (VALID[key](value)) out[key] = value;
+        else warnings.push(`heavy.${key} inválida (${JSON.stringify(value)}); usando ${JSON.stringify(HEAVY_DEFAULTS[key])}`);
+      }
+    }
+  }
+
+  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;
+
+  return { ...out, warnings };
+}
+
+export function readHeavyConfig(projectPath, env = process.env) {
+  return resolveHeavyConfig(readProjectConfig(projectPath), env);
+}