@polymorphism-tech/morph-spec 8.42.0 → 8.43.0

package/framework/evals/proof-rubrics/mutation-proof.md

@@ -10,24 +10,39 @@ Um teste verde prova que o código roda. Só a **mutação** prova que o teste M
 propósito a linha que carrega a decisão e veja quem grita. Se ninguém grita, a suíte é decoração —
 e foi assim que 11 testes verdes cobriram um artefato que o build recusava.
 
-A pergunta desta rubrica é sempre a mesma: **você mutou o call site que carrega a decisão, rodou a
-suíte inteira, leu o MOTIVO da falha, e devolveu o arquivo byte a byte?**
+A pergunta desta rubrica é sempre a mesma: **você mutou o call site que carrega a decisão, provou
+cada sobrevivente contra a suíte inteira, leu o MOTIVO da falha, e devolveu o arquivo byte a byte
+— com o binário provado?**
+
+O método é `morph-spec mutate` (manifesto de mutantes → uma chamada → a seção pronta). Você escolhe
+os mutantes; a ferramenta escolhe o subconjunto de testes, roda o lote, refaz todo sobrevivente com o
+mutante compilado de verdade contra a suíte INTEIRA e reverte por bytes.
 
 ## Bandas 0-10
 
 | 0-3 | 4-6 | 7-8 | 9-10 |
 |---|---|---|---|
-| Nenhuma mutação. Ou mutação declarada sem diff, sem md5 e sem testes nomeados — afirmação, não prova. Ou revert por `git checkout --`, que descarta trabalho não commitado de terceiros | Mutou, mas no lugar errado (o `if` refatorado, não o call site que decide) ou com filtro estreito ("derrubou 3" medido sobre 40 testes de um arquivo só). Reportou md5 sem ler o motivo da falha | Mutação no call site certo, suíte inteira, diff e md5 antes/depois. Falta o MOTIVO literal da falha, ou uma cláusula de um predicado composto ficou sem rodada própria | Uma rodada por cláusula, cada uma com arquivo:linha, diff, md5 antes/depois, contagem sobre a suíte INTEIRA e a mensagem literal de falha. Revert por snapshot de bytes + `os.utime`, com `git status --porcelain src/` vazio ao fim |
+| Nenhuma mutação. Ou mutação declarada sem diff, sem md5 e sem testes nomeados — afirmação, não prova. Ou revert por `git checkout --`, que descarta trabalho não commitado de terceiros | Mutou, mas no lugar errado (o `if` refatorado, não o call site que decide) ou declarou "sobreviveu" / "derruba N" a partir de um filtro escolhido por você ("derrubou 3" medido sobre 40 testes de um arquivo só). Reportou md5 sem ler o motivo da falha | Mutação no call site certo, todo sobrevivente refeito contra a suíte INTEIRA, diff e md5 antes/depois. Falta o MOTIVO literal da falha, ou uma cláusula de um predicado composto ficou sem rodada própria | Uma rodada por cláusula, cada uma com arquivo:linha, diff, md5 antes/depois, contagem com o ESCOPO dito (`≥K de N` no subconjunto que a ferramenta escolheu; `K de M` na suíte inteira) e a mensagem literal de falha. Revert por snapshot de bytes com escrita nova, rebuild forçado e DLL final igual (md5) à de antes do 1º mutante, com `git status --porcelain src/` vazio ao fim |
 
 ## Anti-padrões literais
 
 - **Mutar o `if` refatorado em vez do call site que carrega a decisão** — o extract-method moveu a
   regra; o teste continua batendo no invólucro. Ancore onde o valor é DECIDIDO. (memória: guard do
   remédio, cuja checagem real vivia duas camadas acima do `if` mutado)
-- **Rodar com filtro e reportar "derruba N"** — "3 de 40" e "3 de 2684" são afirmações diferentes.
-  Só a suíte **inteira** autoriza a frase "derruba N". (memória: F30, filtro no Gate 3)
+- **Reportar "sobreviveu" ou "derruba N" a partir de um filtro que você escolheu** — "3 de 40" e
+  "3 de 2684" são afirmações diferentes. **"Sobreviveu" só vale contra a suíte INTEIRA**, com o
+  mutante compilado de verdade. **"Morto" pode sair de um subconjunto, se a ferramenta o escolheu**
+  (testes que a feature alterou + os que citam o tipo mutado): teste que falha no subconjunto falha
+  na suíte, então a morte é a mesma — mas a contagem passa a ser piso (`≥K de N (subconjunto)`), e
+  `K de M` só existe medido na suíte inteira. (memória: F30, filtro no Gate 3)
+- **Contar como morto o teste instável** — morte na suíte inteira só vale se a mesma falha se repete
+  na segunda rodada (dos testes que falharam, isolados, ou da suíte inteira). Medido: um teste de host, sem relação com o mutante,
+  "derrubou" um mutante uma vez; em sete rodadas o mutante sobreviveu seis. Falha que não se
+  repete é sobrevivente com razão dita, não morte. (mesma rodada: `out var` removido que só compila
+  no schemata é `build-error`, não morto)
 - **Filtro tão estreito que a prova fica vácua** — mutar e rodar só o teste que você já sabia que
-  quebraria não testa nada além da sua própria expectativa.
+  quebraria não testa nada além da sua própria expectativa. O subconjunto é da ferramenta, nunca
+  seu: escolhido à mão, ele volta a ser a sua expectativa.
 - **Aceitar um seed sem perguntar "que sequência real produz este seed?"** — fixture que só existe
   no teste prova o teste, não o sistema.
 - **Imprimir `diff` + md5 e parar por aí** — md5 prova que ALGO mudou, nunca O QUÊ. Sem a mensagem
@@ -36,13 +51,23 @@ suíte inteira, leu o MOTIVO da falha, e devolveu o arquivo byte a byte?**
 - **Reverter por replace reverso, ou por `git checkout --`** — o replace reverso erra em arquivo com
   ocorrências repetidas; o `git checkout --` **apaga alterações não commitadas de outra pessoa** e
   aconteceu de verdade num Gate 3 desta epic. Reverta por **snapshot/restore de bytes** (cópia feita
-  ANTES) + `os.utime` para devolver o mtime, e confirme por `md5sum`.
+  ANTES), por escrita nova, e confirme por `md5sum`.
+- **Devolver o mtime original com `os.utime` depois de restaurar** — os bytes voltam, mas com data
+  ANTIGA o arquivo fica mais velho que a DLL do último mutante: o MSBuild acha o binário em dia, não
+  recompila, e a rodada-base roda sobre o mutante (falso vermelho, ou pior: falso verde). Medido num
+  projeto .NET 10 de 697 arquivos: restore com data antiga → build de 1,9 s, nenhum `CoreCompile`,
+  DLL do mutante intacta; escrita nova → DLL de volta ao md5 da baseline. Restaure por **escrita
+  nova**, force o rebuild e **prove que o binário é o do disco** (md5 da DLL == a construída da
+  árvore limpa antes do 1º mutante).
 - **Escrever a mutação por heredoc do shell quando ela contém barra invertida** — o transporte come
   o escape: `\b` vira o byte `0x08`, `\n` vira quebra de linha real, e o regex mutado **não é o que
   você escreveu**. Sintoma: a mutação parece aplicada e o resultado não muda, ou o arquivo quebra
   num ponto que você não tocou. Diagnóstico em um comando: `cat -A` mostra `^H` onde devia estar
-  `\b`. Saída: patch por **índice de linha** com o conteúdo montado sem barra invertida no fonte
-  (`String.fromCharCode(92)`), ou ferramenta de edição estrutural — nunca heredoc.
+  `\b`. Medido: o transporte do Bash reduz `\\` a `\` e decodifica escapes unicode, até dentro de
+  heredoc de aspas simples. Saída: o manifesto de `morph-spec mutate` com a barra invertida do código
+  escrita como o token `{{BS}}` (a ferramenta a expande), ou patch por **índice de linha** com o
+  conteúdo montado sem barra invertida no fonte (`String.fromCharCode(92)`) — nunca a barra invertida
+  crua num heredoc.
   (memória: **três agentes** desta epic tropeçaram nisto; dois descartaram o resultado, um só
   descobriu ao conferir os bytes)
 - **Mutar antes de commitar o fix** — se a sessão morrer no meio, o que sobrevive é a mutação, não a
@@ -69,9 +94,14 @@ Na seção `## Mutações` do `evaluator-report.md`, uma linha por mutação, co
 ```markdown
 | # | Arquivo:linha | Mutação (diff) | md5 antes | md5 depois | Testes derrubados | Motivo da falha |
 |---|---|---|---|---|---|---|
-| M1 | src/lib/x.js:42 | `- if (a && b)` / `+ if (a)` | abc… | def… | 3 de 2684 | `expected 3 got 0` em x.test.js:88 |
+| M1 | src/lib/x.js:42 | `- if (a && b)` / `+ if (a)` | abc… | def… | ≥3 de 212 (subconjunto) | `expected 3 got 0` em x.test.js:88 |
+| M2 | src/lib/y.js:7 | `- return ok` / `+ return true` | 123… | 456… | 0 de 2684 (SOBREVIVEU, suíte inteira) | nenhum teste falhou na suíte inteira |
 ```
 
-E, ao fim da seção: **Reversão:** snapshot/restore de bytes + `os.utime`; `git status --porcelain
-src/` vazio. Feature sem código de produção declara a seção com a linha
-`não aplicável — feature sem código de produção`.
+A coluna "Testes derrubados" sempre diz o escopo: `≥K de N (subconjunto)` é piso; `K de M (suíte
+inteira)` é contagem; sobrevivente é sempre `0 de M (suíte inteira)`. `morph-spec mutate` imprime a
+seção inteira nesse formato — cole-a, não a redigite.
+
+E, ao fim da seção: **Reversão:** snapshot/restore de bytes por escrita nova; DLL final igual (md5)
+à de antes do 1º mutante; `git status --porcelain src/` vazio. Feature sem código de produção
+declara a seção com a linha `não aplicável — feature sem código de produção`.

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * heavy-gate.js — PreToolUse hook (Bash matcher), link of the Bash chain before worktree-env-inject.
+ *
+ * A sub-agent that runs `dotnet build` or `npm test` straight through Bash bypasses the heavy-node
+ * semaphore that `morph-spec verify` respects. With `heavy.gateBash: true` this hook takes a slot
+ * before such a command runs and `heavy-release` gives it back on Post/PostFailure, matched by
+ * `tool_use_id`. It never rewrites the command: a rewrite would be judged against the user's
+ * permission rules in its rewritten form, and would auto-approve what the prompt would have asked.
+ *
+ * A slot taken here has no live process to watch — the hook exits at once — so it lapses by TTL
+ * (the call's own timeout plus slack). A call refused by a permission rule or interrupted by the
+ * user fires no Post hook and keeps its slot until then.
+ *
+ * Waits below the platform's 600 s hook timeout, because a timed-out PreToolUse hook lets the call
+ * run: the refusal has to come from here. Fail-open otherwise.
+ */
+
+import { stateExists } from '../../shared/state-reader.js';
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { heavyKind, leaseTtlMs } from '../../shared/heavy-command.js';
+
+const HOOK_BUDGET_SEC = 540;
+
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @param {{ env?: object, acquire?: Function }} [deps] - test seams; production passes none
+ * @returns {Promise<object|null>} a block result when no slot came free, else null (pass)
+ */
+export async function run(payload, deps = {}) {
+  try {
+    if (payload?.tool_name && payload.tool_name !== 'Bash') return null;
+    const input = payload?.tool_input ?? {};
+    if (input.run_in_background) return null;
+    const kind = heavyKind(input.command);
+    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 { 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();
+    if (!stateExists(dir)) return null;
+    const config = readHeavyConfig(dir, env);
+    if (!config.enabled || !config.gateBash) return null;
+
+    const result = (deps.acquire ?? acquireHeavy)({
+      dir: heavyDir(env),
+      slots: config.slots,
+      label: kind,
+      feature: null,
+      node: null,
+      cwd: dir,
+      minFreeMemGb: config.minFreeMemGb,
+      waitTimeoutMs: Math.min(config.waitTimeoutSec, HOOK_BUDGET_SEC) * 1000,
+      maxHoldMs: config.maxHoldMinutes * 60_000,
+      lease: { id: payload.tool_use_id, ttlMs: leaseTtlMs(input, env) },
+      env,
+      log: () => {},
+    });
+    if (result.status !== 'busy') return null;
+
+    return blockResult(
+      `⏳ \`${kind}\` não rodou: ${describeBusy(result, config)}. Não é falha do código — aguarde e repita o MESMO comando. `
+      + '`morph-spec heavy status` mostra quem segura os slots; `heavy.gateBash: false` desliga esta espera.',
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * heavy-release.js — PostToolUse / PostToolUseFailure link: gives back the slot `heavy-gate` took
+ * for this Bash call, matched by `tool_use_id`.
+ *
+ * Silent and fail-open. A call that fires neither event (refused by a rule, interrupted) leaves its
+ * slot to the TTL. Releasing is not deciding, so this link is safe in the async failure binding.
+ */
+
+import { existsSync } from 'node:fs';
+import { stateExists } from '../../shared/state-reader.js';
+import { runStandalone } from '../../shared/hook-response.js';
+
+/**
+ * @param {object} payload - PostToolUse or PostToolUseFailure stdin payload
+ * @param {{ env?: object }} [deps] - test seam
+ * @returns {Promise<null>}
+ */
+export async function run(payload, deps = {}) {
+  try {
+    if (payload?.tool_name !== 'Bash' || !payload.tool_use_id) return null;
+    const env = deps.env ?? process.env;
+    if (!stateExists(env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd())) return null;
+    // Runs after every tool call: pay for the slot module only when a semaphore directory exists.
+    const { heavyDir } = await import('../../shared/heavy-holders.js');
+    const dir = heavyDir(env);
+    if (!existsSync(dir)) return null;
+    const { releaseLeaseById } = await import('../../shared/heavy-slots.js');
+    releaseLeaseById(dir, payload.tool_use_id);
+  } catch { /* fail-open */ }
+  return null;
+}
+
+await runStandalone(run);

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/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);
+}