@polymorphism-tech/morph-spec 8.42.0 → 8.43.0

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

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { freemem, homedir } from 'node:os';
+import { join } from 'node:path';
+import { pidAlive } from './process-alive.js';
+
+export const GB = 1024 ** 3;
+export const WRITE_GRACE_MS = 5000;
+export const EXCLUSIVE_MAX_AGE_MS = 2 * 60 * 1000;
+export const SLOT_FILE = /^slot-\d+\.lock$/;
+
+export function heavyDir(env = process.env, { platform = process.platform, home = homedir() } = {}) {
+  if (env.MORPH_HEAVY_DIR) return env.MORPH_HEAVY_DIR;
+  if (platform === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'morph-spec', 'heavy');
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'morph-spec', 'heavy');
+}
+
+export const mtimeOf = (path) => {
+  try { return statSync(path).mtimeMs; } catch { return null; }
+};
+
+const leaseTtlMs = (meta) => (Number.isFinite(meta.ttlMs) && meta.ttlMs > 0 ? meta.ttlMs : Infinity);
+
+export function readLockFile(path, { now, isAlive, maxHoldMs }) {
+  const t = now();
+  let meta;
+  try {
+    meta = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    const mtime = mtimeOf(path);
+    if (mtime === null) return null;
+    const writing = t - mtime < WRITE_GRACE_MS;
+    return { path, pid: null, since: null, label: '(gravando)', live: writing, unreadable: true };
+  }
+  const age = t - Date.parse(meta.since);
+  const inWindow = age >= 0 && age < maxHoldMs;
+  // A per-call lease belongs to a hook process that is long gone: only its TTL says when it lapses.
+  const live = meta.leaseId ? inWindow && age < leaseTtlMs(meta) : inWindow && Boolean(isAlive(meta.pid));
+  return { ...meta, path, live };
+}
+
+export function scanHolders(dir, ctx) {
+  let names = [];
+  try { names = readdirSync(dir).filter((n) => SLOT_FILE.test(n)); } catch { return { live: [], stale: [] }; }
+  const live = [];
+  const stale = [];
+  for (const name of names) {
+    const holder = readLockFile(join(dir, name), ctx);
+    if (!holder) continue;
+    (holder.live ? live : stale).push(holder);
+  }
+  return { live, stale };
+}
+
+export function readHolders(dir, ctx) {
+  return scanHolders(dir, ctx).live;
+}
+
+export function readExclusive(dir, ctx) {
+  const holder = readLockFile(join(dir, 'exclusive.lock'), { ...ctx, maxHoldMs: EXCLUSIVE_MAX_AGE_MS });
+  return holder?.live ? holder : null;
+}
+
+const ageText = (ms) => {
+  const min = Math.floor(ms / 60000);
+  return min < 1 ? `${Math.max(0, Math.floor(ms / 1000))}s` : `${min}m`;
+};
+
+export function describeHolder(h, now = Date.now()) {
+  const what = [h.label, [h.feature, h.node].filter(Boolean).join('/')].filter(Boolean).join(' ');
+  const age = h.since ? `, há ${ageText(now - Date.parse(h.since))}` : '';
+  const who = h.leaseId ? 'chamada Bash' : `pid ${h.pid ?? '?'}`;
+  return `${what || 'processo'}, ${who}${age}`;
+}
+
+export function heavyStatus({
+  dir, maxHoldMs, now = Date.now, isAlive = pidAlive, freeMem = freemem,
+}) {
+  const ctx = { now, isAlive, maxHoldMs };
+  return {
+    dir,
+    holders: readHolders(dir, ctx),
+    exclusive: readExclusive(dir, ctx),
+    freeGb: freeMem() / GB,
+  };
+}

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

@@ -0,0 +1,207 @@
+import {
+  closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { freemem } from 'node:os';
+import { join } from 'node:path';
+import { pidAlive } from './process-alive.js';
+import {
+  GB, SLOT_FILE, describeHolder, mtimeOf, readExclusive, scanHolders,
+} from './heavy-holders.js';
+
+export { heavyDir, heavyStatus, describeHolder } from './heavy-holders.js';
+
+const MUTEX_STALE_MS = 10_000;
+const POLL_MS = 500;
+const REPORT_EVERY_MS = 30_000;
+
+export function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(1, ms));
+}
+
+function withClaimMutex(dir, fn, { now }) {
+  const path = join(dir, 'claim.lock');
+  for (let attempt = 0; attempt < 50; attempt++) {
+    try {
+      mkdirSync(path);
+      try {
+        return { value: fn() };
+      } finally {
+        try { rmdirSync(path); } catch { /* já removido */ }
+      }
+    } catch (err) {
+      if (err?.code !== 'EEXIST') return null;
+      const mtime = mtimeOf(path);
+      if (mtime !== null && now() - mtime > MUTEX_STALE_MS) {
+        try { rmdirSync(path); } catch { /* outro já recolheu */ }
+      } else {
+        sleepSync(20);
+      }
+    }
+  }
+  return null;
+}
+
+function liveHoldersPruningStale(dir, ctx) {
+  const { live, stale } = scanHolders(dir, ctx);
+  for (const holder of stale) {
+    try { unlinkSync(holder.path); } catch { /* já solto */ }
+  }
+  return live;
+}
+
+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)})`;
+  if (blocked.reason === 'memory') {
+    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 slot pesado (${blocked.holders.length}/${slots}): ${holders}`;
+}
+
+function tryClaim(dir, opts, ctx) {
+  const {
+    slots, label, feature, node, cwd, minFreeMemGb, freeMem, lease: leaseSpec,
+  } = opts;
+  const guarded = withClaimMutex(dir, () => {
+    const holders = liveHoldersPruningStale(dir, ctx);
+    const exclusive = readExclusive(dir, 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 } };
+
+    for (let i = 0; i < slots + holders.length + 1; i++) {
+      const path = join(dir, `slot-${i}.lock`);
+      try {
+        const fd = openSync(path, 'wx');
+        const meta = {
+          pid: leaseSpec ? null : process.pid,
+          since: new Date(ctx.now()).toISOString(),
+          label,
+          feature,
+          node,
+          cwd,
+          ...(leaseSpec ? { leaseId: leaseSpec.id, ttlMs: leaseSpec.ttlMs } : {}),
+        };
+        writeSync(fd, JSON.stringify(meta));
+        closeSync(fd);
+        return { lease: { path, pid: meta.pid, slot: i, meta } };
+      } catch (err) {
+        if (err?.code !== 'EEXIST') return { blocked: { reason: 'slots', holders } };
+      }
+    }
+    return { blocked: { reason: 'slots', holders } };
+  }, ctx);
+  return guarded ? guarded.value : { blocked: { reason: 'contended', holders: [] } };
+}
+
+export function acquireHeavy(opts) {
+  const {
+    dir, slots, waitTimeoutMs, maxHoldMs,
+    now = Date.now, sleep = sleepSync, isAlive = pidAlive, freeMem = freemem,
+    log = (m) => process.stderr.write(`${m}\n`), env = process.env,
+  } = opts;
+  const ctx = { now, isAlive, maxHoldMs };
+  const claimOpts = { ...opts, freeMem, minFreeMemGb: opts.minFreeMemGb ?? 0 };
+
+  try { mkdirSync(dir, { recursive: true }); } catch { return { status: 'acquired', lease: null, waitedMs: 0, unavailable: true }; }
+
+  const leaseOwner = Number(env.MORPH_HEAVY_LEASE);
+  if (Number.isInteger(leaseOwner) && leaseOwner > 0 && scanHolders(dir, ctx).live.some((h) => h.pid === leaseOwner)) {
+    return { status: 'acquired', lease: null, waitedMs: 0, reentrant: true };
+  }
+
+  const start = now();
+  let lastReport = -Infinity;
+  for (;;) {
+    const attempt = tryClaim(dir, claimOpts, ctx);
+    if (attempt.lease) return { status: 'acquired', lease: attempt.lease, waitedMs: now() - start };
+
+    const waited = now() - start;
+    const { blocked } = attempt;
+    if (waited >= waitTimeoutMs) {
+      return {
+        status: 'busy', reason: blocked.reason, holders: blocked.holders, freeGb: blocked.freeGb ?? null, waitedMs: waited,
+      };
+    }
+    if (blocked.reason !== 'contended' && now() - lastReport >= REPORT_EVERY_MS) {
+      log(blockedText(blocked, slots, now()));
+      lastReport = now();
+    }
+    sleep(Math.min(POLL_MS, Math.max(1, waitTimeoutMs - waited)));
+  }
+}
+
+export function updateLease(lease, patch) {
+  if (!lease) return;
+  try {
+    const current = JSON.parse(readFileSync(lease.path, 'utf8'));
+    if (current.pid !== lease.pid) return;
+    writeFileSync(lease.path, JSON.stringify({ ...current, ...patch }));
+  } catch { /* o lease foi recolhido; nada a atualizar */ }
+}
+
+export function releaseHeavy(lease) {
+  if (!lease) return;
+  try {
+    if (JSON.parse(readFileSync(lease.path, 'utf8')).pid === lease.pid) unlinkSync(lease.path);
+  } catch { /* já solto */ }
+}
+
+export function releaseLeaseById(dir, id) {
+  let names = [];
+  try { names = readdirSync(dir).filter((n) => SLOT_FILE.test(n)); } catch { return false; }
+  for (const name of names) {
+    const path = join(dir, name);
+    try {
+      if (JSON.parse(readFileSync(path, 'utf8')).leaseId !== id) continue;
+      unlinkSync(path);
+      return true;
+    } catch { /* já solto, ou ainda sendo gravado */ }
+  }
+  return false;
+}
+
+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)`;
+  }
+  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)`;
+}
+
+export function runExclusive(opts, fn) {
+  const {
+    dir, label, maxHoldMs, now = Date.now, isAlive = pidAlive,
+  } = opts;
+  const ctx = { now, isAlive, maxHoldMs };
+  try { mkdirSync(dir, { recursive: true }); } catch { return { ran: false, reason: 'unavailable', holders: [] }; }
+
+  const own = Number((opts.env ?? process.env).MORPH_HEAVY_LEASE);
+  const claimed = withClaimMutex(dir, () => {
+    const holders = liveHoldersPruningStale(dir, ctx).filter((h) => h.pid !== own);
+    if (holders.length) return { ran: false, reason: 'holders', holders };
+    if (readExclusive(dir, ctx)) return { ran: false, reason: 'exclusive', holders: [] };
+    try {
+      const fd = openSync(join(dir, 'exclusive.lock'), 'wx');
+      writeSync(fd, JSON.stringify({ pid: process.pid, since: new Date(now()).toISOString(), label }));
+      closeSync(fd);
+    } catch {
+      return { ran: false, reason: 'exclusive', holders: [] };
+    }
+    return { ran: true };
+  }, ctx);
+
+  if (!claimed) return { ran: false, reason: 'contended', holders: [] };
+  if (!claimed.value.ran) return claimed.value;
+
+  try {
+    return { ran: true, result: fn() };
+  } finally {
+    try { unlinkSync(join(dir, 'exclusive.lock')); } catch { /* já solto */ }
+  }
+}

package/framework/hooks/shared/process-alive.js

@@ -0,0 +1,8 @@
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}

package/framework/hooks/shared/worktree-root.js

@@ -0,0 +1,93 @@
+/**
+ * worktree-root.js — onde as worktrees do morph-spec moram, num lugar só.
+ *
+ * Padrão: `<raiz>/worktrees/<nome>` (mais o legado `.worktrees/`). Com `worktree.root` na
+ * config (ou `MORPH_WORKTREE_ROOT`), as novas nascem em `<root>/<chave-do-repo>/<nome>`, FORA da
+ * árvore aberta no editor. A chave é `basename-<hash da raiz>`: só o basename colidiria entre dois
+ * repositórios de mesmo nome que dividem o mesmo root.
+ *
+ * Um root DENTRO da raiz é recusado: toda lista que se orienta pelo nome do container
+ * (.gitignore, graphifyignore, descoberta de testes, tar do --linux, globs do editor) deixaria de
+ * enxergá-lo, em silêncio. Recusado, vale o padrão e o motivo volta em `warning`.
+ *
+ * O predicado "está no container" é a UNIÃO do layout configurado com o padrão e o legado: uma
+ * worktree que já existe continua reconhecida depois que a chave muda. Mora em `hooks/shared`
+ * porque hook não importa `src/`; o `src/` importa daqui.
+ *
+ * @module worktree-root
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { basename, isAbsolute, join, relative, resolve } from 'path';
+
+// No leading dot (C1): Jest escapes it inside an absolute `rootDir` glob, so `.worktrees/` made a whole
+// frontend suite report 0 tests without an error. `.worktrees/` is the pre-C1 name, still read everywhere.
+export const WORKTREES_DIR = 'worktrees';
+export const LEGACY_WORKTREES_DIR = '.worktrees';
+export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+const foldCase = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+
+/** `basename-<8 hex do hash da raiz>` — estável entre `R:` e `r:` no Windows. */
+export function repoKey(primaryRoot) {
+  const root = fwd(resolve(primaryRoot));
+  const hash = createHash('sha1').update(foldCase(root)).digest('hex').slice(0, 8);
+  return `${basename(root)}-${hash}`;
+}
+
+function configuredRoot(primaryRoot, env) {
+  if (typeof env.MORPH_WORKTREE_ROOT === 'string' && env.MORPH_WORKTREE_ROOT.trim()) return env.MORPH_WORKTREE_ROOT.trim();
+  try {
+    const raw = readFileSync(join(primaryRoot, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '');
+    const value = JSON.parse(raw)?.worktree?.root;
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * @param {string} primaryRoot
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ dir: string|null, base?: string, warning?: string }} `dir` = `<root>/<repoKey>`
+ */
+export function externalContainer(primaryRoot, { env = process.env } = {}) {
+  const configured = configuredRoot(primaryRoot, env);
+  if (!configured) return { dir: null };
+  const expanded = configured === '~' || /^~[\\/]/.test(configured) ? join(homedir(), configured.slice(1)) : configured;
+  const base = resolve(primaryRoot, expanded);
+  if (isInside(resolve(primaryRoot), base)) {
+    return { dir: null, warning: `worktree.root (${configured}) fica dentro da raiz do projeto; ignorado, valem worktrees/ — as listas de exclusão se orientam por esse nome` };
+  }
+  return { dir: fwd(join(base, repoKey(primaryRoot))), base: fwd(base) };
+}
+
+/** Where a NEW worktree lands. */
+export function newWorktreesDir(primaryRoot, opts) {
+  return externalContainer(primaryRoot, opts).dir ?? `${fwd(resolve(primaryRoot))}/${WORKTREES_DIR}`;
+}
+
+/** Every directory that counts as "the container", external first. Forward slashes. */
+export function containerDirs(primaryRoot, opts) {
+  const root = fwd(resolve(primaryRoot));
+  const external = externalContainer(primaryRoot, opts).dir;
+  return [...(external ? [external] : []), ...WORKTREE_DIR_NAMES.map((name) => `${root}/${name}`)];
+}
+
+/** Is `path` under any of `dirs` (a `containerDirs` result)? Ask `containerDirs` once per audit, not once per path. */
+export function isUnder(dirs, path) {
+  const target = foldCase(fwd(resolve(path)));
+  return dirs.some((dir) => target.startsWith(`${foldCase(dir)}/`));
+}
+
+export function isInContainer(primaryRoot, path, opts) {
+  return isUnder(containerDirs(primaryRoot, opts), path);
+}

package/framework/schemas/config.schema.json

@@ -149,6 +149,86 @@
           ]
         }
       }
+    },
+    "heavy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Slots per USER (shared by every session on the machine, kept in %LOCALAPPDATA%/morph-spec/heavy on Windows and ~/.local/state/morph-spec/heavy elsewhere) for the heavy nodes: build, tests and e2e of `verify`, `e2e up`, and `morph-spec heavy run`. A value it cannot read falls back to the default with a warning - this block never blocks work by being wrong. `MORPH_HEAVY=off` switches the whole semaphore off (the test suite does), `MORPH_HEAVY_SLOTS` overrides `slots`, `MORPH_HEAVY_DIR` moves the directory.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "false turns the semaphore off: no slot is taken, no RAM is checked, and `dotnet build-server shutdown` is never run (without the semaphore nothing proves another session is not compiling)."
+        },
+        "slots": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 2,
+          "description": "How many heavy nodes run at once on this machine."
+        },
+        "minFreeMemGb": {
+          "type": "number",
+          "minimum": 0,
+          "default": 4,
+          "description": "Free RAM (os.freemem) below which a heavy node WAITS instead of starting and dying 'killed' for memory. It waits with or without a slot holder - the pressure often comes from outside (WSL vmmem, the IDE). 0 disables the check."
+        },
+        "waitTimeoutSec": {
+          "type": "number",
+          "minimum": 0,
+          "default": 600,
+          "description": "How long to wait for a slot or for RAM. On timeout `verify` exits 3 (busy) and persists NOTHING - a queue is neither a green nor a red gate. 0 means do not wait."
+        },
+        "maxHoldMinutes": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 90,
+          "description": "A slot held longer than this is treated as stale even if its pid is alive (pid reuse)."
+        },
+        "shutdownBuildServer": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run `dotnet build-server shutdown` at the end of a feature-scope `verify` and of `e2e down`, only when no slot is held and no dotnet build/test is alive. Never at the end of a task-scope verify: every task would pay a cold compiler."
+        },
+        "disableNodeReuse": {
+          "type": "boolean",
+          "default": false,
+          "description": "Set MSBUILDDISABLENODEREUSE=1 while a heavy node runs, so MSBuild worker nodes do not stay resident."
+        },
+        "gateBash": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt-in. A PreToolUse hook takes a slot before a raw heavy Bash command (dotnet build|test|publish|pack, npm|pnpm|yarn test|build, vitest, jest, docker compose up|build, ...) runs and the matching Post hook gives it back. Waits up to heavy.waitTimeoutSec (capped below the hook timeout), then refuses the call with a busy message instead of running it. Foreground Bash only: a run_in_background call is not gated, and a call denied or interrupted after the hook keeps its slot until its timeout lapses, and that timeout starts before the permission prompt."
+        }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Worktree behaviour of this project. Other keys are left open; the readers are src/lib/worktree/vscode-settings.js and src/lib/worktree/agent-reaper.js.",
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where NEW worktrees are created, outside the project tree: they land in <root>/<repo>-<hash>/<name> (the hash keeps two repos with the same folder name apart). Absolute, `~/...`, or relative to the primary root. A path that resolves INSIDE the project root is ignored with a warning, because every exclusion list (.gitignore, graph ignore, test discovery, the --linux tar, editor globs) is keyed on worktrees/. Existing worktrees under worktrees/ keep being recognised. `MORPH_WORKTREE_ROOT` overrides it for one run."
+        },
+        "editorSettings": {
+          "type": "boolean",
+          "default": true,
+          "description": "false stops `init`, `update`, `worktree setup|provision` and `doctor --worktrees --prune` from adding the worktree/node_modules (and, on .NET, bin/obj) excludes to .vscode/settings.json. `MORPH_EDITOR_SETTINGS=0` does the same for one run."
+        },
+        "reap": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "graceMinutes": {
+              "type": "number",
+              "minimum": 0,
+              "default": 30,
+              "description": "How long a sub-agent's events.jsonl must stay quiet after its AgentUsage before `worktree reap` removes the tree: a stopped agent can still be resumed by SendMessage. An invalid value falls back to 30."
+            }
+          }
+        }
+      }
     }
   }
 }

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-apply
@@ -107,6 +107,8 @@ while (true):
     // de uma task não paga a suíte inteira). `--filter {ids}` só para FORÇAR a
     // escolha de nós; `--full` desliga o recorte.
     run: morph-spec verify {feature} {task.id} --json
+    // exit 3 / status == 'busy': fila de slot pesado cheia, NÃO vermelho — nada foi verificado nem gravado.
+    // Repita a mesma chamada; não conta como tentativa e não dispara o loop de correção.
     if verify.status == 'fail':
       // vermelho: feedback determinístico direto ao loop, SEM gastar o juiz LLM.
       feedback = verify.feedback   // usado como input do próximo attempt
@@ -238,7 +240,10 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
        por decisão sua; ao concluir, o relatório final substitui o parcial, sem o
        `PARCIAL`. Sem limite declarado, bastam os commits por marco.
     6. PROCESSOS: NUNCA `taskkill /IM node.exe` (derruba os MCPs de todas as
-       sessões). Encerre dev server pelo PID que você mesmo subiu.
+       sessões). Encerre dev server pelo PID que você mesmo subiu. Build e
+       suíte pesados (`dotnet build`, `dotnet test`, `docker compose up`) rodam
+       por `morph-spec heavy run -- <comando>`: exit 3 é fila cheia, não erro do
+       código — espere e repita.
     7. RETORNO: o relatório no arquivo canônico é o retorno. `SendMessage` não é
        substituto do relatório e não deve ser chamado.
     8. MUTAÇÃO: nunca altere, reverta, mova ou apague código de produção para ver
@@ -296,7 +301,7 @@ Quando o `morph-spec dag {feature}` reporta `isolation.recommended: "worktree"`
 1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. O worktree vem do hook `WorktreeCreate` do morph: nasce em `worktrees/<n>` na branch `morph-task/<n>`, com junctions (`node_modules`, `.claude`, `.morph/framework`) e `.morph/worktree.env` já prontos — se faltar infra mesmo assim, o agente roda `morph-spec worktree link --all` (fail-open); se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). Dev server/compose dentro do worktree já sai nas portas do bloco (o hook `worktree-env-inject` prefixa o comando; fora do Claude, `eval "$(morph-spec env)"`). O worktree nasce da branch `morph/<feature>` quando a sessão está nela (o trabalho já integrado da feature vem junto, sem `merge` manual) e com os `.env*` da raiz copiados — o prompt de dispatch não manda o agente preparar nada disso. Sessão fora de `morph/<feature>` (orquestrador na raiz) faz o worktree nascer da default: aí, e só aí, o prompt abre com `git merge --ff-only morph/<feature>`. O agente commita na branch do worktree como último ato e reporta a branch. Ele não roda `morph-spec verify` (cláusula 3): a prova é o verify do orquestrador depois do merge.
 2. **Integração (orquestrador, a cada relatório que chega):** faça o merge de cada branch reportada, uma por vez, na ordem de chegada — `git merge --no-ff <branch>`. Conflito → `git merge --abort`, marque a task de volta a `pending` com nota "merge conflict — reexecutar sequencial", siga para a próxima branch. Os paths em conflito são exatamente os de `isolation.collisions` do dag.
 3. **Pós-merge:** `verify {feature} {taskId}` no merge de cada task (dispatch rolling, §3b), depois `morph-eval` + `morph-spec score`; `morph-spec verify {feature} --json` de escopo feature UMA vez, quando nada mais está em voo (o merge é o novo ponto de integração — verificação compartilhada obrigatória).
-4. **Cleanup:** o hook `WorktreeRemove` remove o worktree **limpo** ao fim do subagent (branch sobrevive) — mas não conte com ele: rode `morph-spec worktree remove --target <path>` por worktree que sobrou (NUNCA `git worktree remove` cru — as junctions do passo 1 seriam atravessadas e o `node_modules`/`.claude` da raiz apagados) + `git branch -d morph-task/<n>` das branches integradas + `git worktree prune` (fail-open). Worktree sujo (subagent não commitou) fica, vira `unintegrated-work` no `doctor --worktrees`, e a task volta a `pending`. Branches não integradas ficam e são registradas no recap com o motivo.
+4. **Cleanup:** o hook `WorktreeRemove` remove o worktree **limpo** ao fim do subagent (branch sobrevive) — mas não conte com ele: rode `morph-spec worktree remove --target <path>` por worktree que sobrou (NUNCA `git worktree remove` cru — as junctions do passo 1 seriam atravessadas e o `node_modules`/`.claude` da raiz apagados) + `git branch -d morph-task/<n>` das branches integradas + `git worktree prune` (fail-open). Depois de cada retorno de agent com `isolation`, e ao fim do batch, rode `morph-spec worktree reap --json`: remove só o worktree de `agent-<hex>` que parou limpo e sem commit exclusivo, e lista o resto com a razão (`not-a-registered-worktree` no `remove --target` seguinte = o reaper já o levou). Worktree sujo (subagent não commitou) fica, vira `agent-worktree-leftover` no `doctor --worktrees`, e a task volta a `pending`. Branches não integradas ficam e são registradas no recap com o motivo.
 5. **Agente morto no meio:** se commitou, a branch sobrevive (retomável); senão, a task volta a `pending` na lane sequencial. Registre a falha de protocolo no recap.
 
 > Anti-padrões: não misture unidades isoladas e não-isoladas no mesmo batch; o subagent nunca faz merge (integração é exclusiva do orquestrador).

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.42.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-implement
@@ -132,7 +132,10 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
       por decisão sua; ao concluir, o relatório final substitui o parcial, sem o
       `PARCIAL`. Sem limite declarado, bastam os commits por marco.
    6. PROCESSOS: NUNCA `taskkill /IM node.exe` (derruba os MCPs de todas as
-      sessões). Encerre dev server pelo PID que você mesmo subiu.
+      sessões). Encerre dev server pelo PID que você mesmo subiu. Build e
+      suíte pesados (`dotnet build`, `dotnet test`, `docker compose up`) rodam
+      por `morph-spec heavy run -- <comando>`: exit 3 é fila cheia, não erro do
+      código — espere e repita.
    7. RETORNO: o relatório no arquivo canônico é o retorno. `SendMessage` não é
       substituto do relatório e não deve ser chamado.
    8. MUTAÇÃO: nunca altere, reverta, mova ou apague código de produção para ver
@@ -153,7 +156,9 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    deixa o disco a meio caminho — e um relatório lido sobre uma árvore que ninguém conferiu avalia
    um estado que ninguém quis. Árvore inesperadamente suja ou `markers` não vazio é falha de
    protocolo: registre no recap antes de pontuar. Essa saída serve ao passo 7 enquanto a árvore
-   não mudar; depois de uma correção sua, rode de novo.
+   não mudar; depois de uma correção sua, rode de novo. Dispatch com `isolation: "worktree"`:
+   depois de ler o relatório, `morph-spec worktree reap --json` remove o worktree do agent que parou
+   limpo e sem commit exclusivo; o que fica vem listado com a razão.
 
    Após o retorno do dispatch: **leia primeiro** `.morph/features/{feature}/3-implement/reports/[ID].md`
    — é o valor de retorno autoritativo. Trate a mensagem de texto do sub-agent, se chegou inteira,
@@ -267,7 +272,7 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    > tasks.json + recap.md + `taskScores` do feature.json. **NÃO escreva o trace
    > manualmente** — a escrita manual foi removida da cerimônia por task.
 
-9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Não rode a suíte de testes inteira do projeto por conta própria ao fim da task quando invocada pela `morph-apply` — a verificação determinística (`morph-spec verify {feature} {task}`) é do orquestrador, logo após seu retorno (ver morph-apply §3a). **Única exceção:** a execução de evidência do passo 5 — só o nó `evals`, filtrado, com `--skip-e2e`, nunca persistida (`--no-persist`); ela não é a verificação da task e não substitui a do orquestrador. **A divisão:** no loop por task o recorte é **automático** — o `group` da task escolhe as suítes e os arquivos de teste dos `outputs` (passo 8) estreitam o comando dentro de cada uma (o relógio de uma task não paga a suíte inteira); `--filter {ids}` só força a escolha de suítes (um nó não casado aparece como `skip` nomeando o filtro, e um filtro que não casa nada é erro de uso, exit 2) e `--full` desliga o recorte. O sub-agent despachado roda só o filtro dos próprios testes, uma vez (cláusula 3), e nunca o `verify`. A suíte **inteira** roda no Gate 3 e no CI, sem filtro — `verify {feature}` nunca recorta. A suíte completa de um projeto grande não cabe numa invocação de Bash do harness — rode em background ou por partes, nunca "suba o limite" (não há constante de timeout global no CLI). Detalhe e forma de `project.tests[]`: `.morph/framework/CLI.md`, seção "Suítes de teste". Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
+9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Não rode a suíte de testes inteira do projeto por conta própria ao fim da task quando invocada pela `morph-apply` — a verificação determinística (`morph-spec verify {feature} {task}`) é do orquestrador, logo após seu retorno (ver morph-apply §3a). **`verify` com exit 3** (`status: "busy"`) é fila de slot pesado cheia, não vermelho: nada foi verificado e nada foi gravado — repita a mesma chamada em vez de abrir uma tentativa de correção. **Única exceção:** a execução de evidência do passo 5 — só o nó `evals`, filtrado, com `--skip-e2e`, nunca persistida (`--no-persist`); ela não é a verificação da task e não substitui a do orquestrador. **A divisão:** no loop por task o recorte é **automático** — o `group` da task escolhe as suítes e os arquivos de teste dos `outputs` (passo 8) estreitam o comando dentro de cada uma (o relógio de uma task não paga a suíte inteira); `--filter {ids}` só força a escolha de suítes (um nó não casado aparece como `skip` nomeando o filtro, e um filtro que não casa nada é erro de uso, exit 2) e `--full` desliga o recorte. O sub-agent despachado roda só o filtro dos próprios testes, uma vez (cláusula 3), e nunca o `verify`. A suíte **inteira** roda no Gate 3 e no CI, sem filtro — `verify {feature}` nunca recorta. A suíte completa de um projeto grande não cabe numa invocação de Bash do harness — rode em background ou por partes, nunca "suba o limite" (não há constante de timeout global no CLI). Detalhe e forma de `project.tests[]`: `.morph/framework/CLI.md`, seção "Suítes de teste". Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
 
 ## Output esperado
 - Código implementado conforme o standard consultado (direto ou via sub-agent)