@polymorphism-tech/morph-spec 9.6.0 → 9.8.0

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

@@ -51,8 +51,14 @@ function liveHoldersPruningStale(dir, ctx) {
 
 const kindSuffix = (kind) => (kind ? ` (${kind})` : '');
 
+// Two full verify suites never run together; a sub-agent filter or a build only takes a slot.
+export const isVerifySuite = ({ label, node }) => label === 'verify' && node === 'tests';
+
+const runningSuite = (holders, ownPath = null) => holders.find((h) => h.path !== ownPath && isVerifySuite(h));
+
 function blockedText(blocked, slots, now) {
   const holders = blocked.holders.map((h) => describeHolder(h, now)).join('; ');
+  if (blocked.reason === 'suite') return `aguardando o verify de outra feature terminar a suíte de testes (${describeHolder(blocked.holders[0], now)})`;
   if (blocked.reason === 'exclusive') return `aguardando limpeza do servidor de build (${describeHolder(blocked.exclusive, now)})`;
   if (blocked.reason === 'memory') {
     const cause = blocked.holders.length
@@ -65,13 +71,16 @@ function blockedText(blocked, slots, now) {
 
 function tryClaim(dir, opts, ctx) {
   const {
-    slots, label, feature, node, cwd, minFreeMemGb, freeMem, kind, lease: leaseSpec,
+    slots, label, feature, node, cwd, minFreeMemGb, freeMem, kind, suite, 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 } };
+    // A full queue is the deeper reason: with no free slot, waiting out the other suite is not enough.
     if (holders.length >= slots) return { blocked: { reason: 'slots', holders } };
+    const running = suite ? runningSuite(holders) : null;
+    if (running) return { blocked: { reason: 'suite', holders: [running] } };
     const freeGb = freeMem() / GB;
     if (minFreeMemGb > 0 && freeGb < minFreeMemGb) return { blocked: { reason: 'memory', holders, freeGb, minFreeMemGb, kind } };
 
@@ -116,10 +125,18 @@ export function acquireHeavy(opts) {
     return { status: 'acquired', lease: null, waitedMs: 0, reentrant: true };
   }
 
+  return pollClaim(() => tryClaim(dir, claimOpts, ctx), {
+    ...opts, now, sleep, log, minFreeMemGb: claimOpts.minFreeMemGb,
+  });
+}
+
+function pollClaim(claim, {
+  slots, waitTimeoutMs, minFreeMemGb = 0, kind = null, now, sleep, log,
+}) {
   const start = now();
   let lastReport = -Infinity;
   for (;;) {
-    const attempt = tryClaim(dir, claimOpts, ctx);
+    const attempt = claim();
     if (attempt.lease) return { status: 'acquired', lease: attempt.lease, waitedMs: now() - start };
 
     const waited = now() - start;
@@ -130,8 +147,8 @@ export function acquireHeavy(opts) {
         reason: blocked.reason,
         holders: blocked.holders,
         freeGb: blocked.freeGb ?? null,
-        minFreeMemGb: claimOpts.minFreeMemGb,
-        kind: opts.kind ?? null,
+        minFreeMemGb,
+        kind,
         waitedMs: waited,
       };
     }
@@ -143,6 +160,25 @@ export function acquireHeavy(opts) {
   }
 }
 
+// Keeps the slot held while it waits: releasing it would let a build or filter take the place.
+export function enterVerifySuite(opts) {
+  const {
+    dir, lease, maxHoldMs,
+    now = Date.now, sleep = sleepSync, isAlive = pidAlive, log = (m) => process.stderr.write(`${m}\n`),
+  } = opts;
+  const ctx = { now, isAlive, maxHoldMs };
+  const claim = () => {
+    const guarded = withClaimMutex(dir, () => {
+      const running = runningSuite(scanHolders(dir, ctx).live, lease.path);
+      if (running) return { blocked: { reason: 'suite', holders: [running] } };
+      updateLease(lease, { node: 'tests' });
+      return { lease };
+    }, ctx);
+    return guarded ? guarded.value : { blocked: { reason: 'contended', holders: [] } };
+  };
+  return pollClaim(claim, { ...opts, now, sleep, log });
+}
+
 // 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) {
@@ -206,6 +242,7 @@ export function describeBusy(result, config) {
     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 === 'suite') return `o verify de outra feature segue na suíte de testes após ${waited}s (heavy.waitTimeoutSec)`;
   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/host-services.js

@@ -0,0 +1,433 @@
+// Host processes that the e2e stack runs next to compose (api, portal), one PID file per project.
+// Nothing here imports e2e-check.js: it imports this module, and the timing constants mirror its own.
+
+import { execFileSync, spawn, spawnSync } from 'child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import { tokenize } from './command-tokens.js';
+import { pidAlive } from './process-alive.js';
+
+export const DEFAULT_HOST_TIMEOUT = 180_000;
+
+const HEALTH_POLL_MS = 2_000;
+
+const OUTPUT_TAIL_LINES = 20;
+
+const NO_HEALTH_GRACE_MS = 2_000;
+
+const KILL_WAIT_MS = 5_000;
+
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export function hostStatePath(gitCommonDir, projectName) {
+  return join(gitCommonDir, 'morph-spec', `e2e-host-${projectName}.json`);
+}
+
+export function hostLogPath(gitCommonDir, projectName, name) {
+  return join(gitCommonDir, 'morph-spec', `e2e-host-${projectName}-${name}.log`);
+}
+
+/** Process creation time as the OS reports it, or null when the PID is gone. */
+export function readProcessCreatedAt(pid, platform = process.platform) {
+  try {
+    const out = platform === 'win32'
+      ? execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+        `(Get-Process -Id ${Number(pid)}).StartTime.ToFileTimeUtc()`],
+      { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] })
+      : execFileSync('ps', ['-o', 'lstart=', '-p', String(Number(pid))],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolves `${VAR}` in `env` and `health`: stack env first, then `process.env`. */
+export function interpolateEnv(service, stackEnv = {}) {
+  const missing = new Set();
+  const sub = (text) => String(text).replace(VAR_RE, (_, name) => {
+    const value = stackEnv?.[name] ?? process.env[name];
+    if (value === undefined || value === null || value === '') {
+      missing.add(name);
+      return '';
+    }
+    return String(value);
+  });
+  const env = {};
+  for (const [key, value] of Object.entries(service.env ?? {})) env[key] = sub(value);
+  const health = service.health ? sub(service.health) : null;
+  return { env, health, missing: [...missing] };
+}
+
+const SERVICE_KEYS = new Set(['name', 'cwd', 'build', 'start', 'env', 'health', 'timeoutMs']);
+
+function validateServices(services) {
+  if (!Array.isArray(services)) return 'e2e.hostServices must be an array';
+  const seen = new Set();
+  for (const [i, svc] of services.entries()) {
+    const label = typeof svc?.name === 'string' && svc.name ? `"${svc.name}"` : `#${i}`;
+    if (!svc || typeof svc !== 'object' || Array.isArray(svc)) return `e2e.hostServices[${i}] must be an object`;
+    if (typeof svc.name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(svc.name)) {
+      return `e2e.hostServices[${i}].name must be a non-empty string of [A-Za-z0-9._-]`;
+    }
+    if (seen.has(svc.name)) return `e2e.hostServices has two services named "${svc.name}"`;
+    seen.add(svc.name);
+    const unknown = Object.keys(svc).find((key) => !SERVICE_KEYS.has(key));
+    if (unknown) return `hostService ${label}: unknown field "${unknown}"`;
+    if (typeof svc.start !== 'string' || !svc.start.trim()) return `hostService ${label}: "start" must be a non-empty string`;
+    for (const field of ['cwd', 'build', 'health']) {
+      if (svc[field] !== undefined && typeof svc[field] !== 'string') return `hostService ${label}: "${field}" must be a string`;
+    }
+    if (svc.env !== undefined) {
+      if (!svc.env || typeof svc.env !== 'object' || Array.isArray(svc.env)) return `hostService ${label}: "env" must be an object`;
+      for (const [key, value] of Object.entries(svc.env)) {
+        if (typeof value !== 'string' && typeof value !== 'number') {
+          return `hostService ${label}: env.${key} must be a string or number`;
+        }
+      }
+    }
+    if (svc.timeoutMs !== undefined && !(Number.isFinite(svc.timeoutMs) && svc.timeoutMs > 0)) {
+      return `hostService ${label}: "timeoutMs" must be a positive number`;
+    }
+  }
+  return null;
+}
+
+function readState(gitCommonDir, projectName) {
+  try {
+    const parsed = JSON.parse(readFileSync(hostStatePath(gitCommonDir, projectName), 'utf8').replace(/^/, ''));
+    return Array.isArray(parsed?.services) ? parsed.services : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(gitCommonDir, projectName, records) {
+  const target = hostStatePath(gitCommonDir, projectName);
+  if (records.length === 0) {
+    try { unlinkSync(target); } catch { /* already gone */ }
+    return;
+  }
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${target}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify({ version: 1, project: projectName, services: records }, null, 2)}\n`, 'utf8');
+  renameSync(tmp, target);
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const PROBE_SCRIPT =
+  'fetch(process.argv[1],{signal:AbortSignal.timeout(Number(process.argv[2]))})' +
+  '.then(r=>process.exit(r.status<500?0:1),()=>process.exit(1))';
+
+function probeHealth(url, timeoutMs = 1_500) {
+  const r = spawnSync(process.execPath, ['-e', PROBE_SCRIPT, url, String(timeoutMs)], {
+    timeout: timeoutMs + 1_000,
+    windowsHide: true,
+    stdio: 'ignore',
+  });
+  return r.status === 0;
+}
+
+// Only the recorded identity may be killed: a recycled PID belongs to someone else.
+function killRecord(record, readCreatedAt) {
+  if (!running(record.pid)) {
+    return { killed: false, warning: `hostService "${record.name}": PID ${record.pid} was no longer running; record dropped` };
+  }
+  const current = readCreatedAt(record.pid);
+  if (!record.createdAt || current !== record.createdAt) {
+    return {
+      killed: false,
+      warning: `hostService "${record.name}": PID ${record.pid} is alive but its creation time differs ` +
+        `from the recorded one (recycled PID); not killed, record dropped`,
+    };
+  }
+  if (process.platform === 'win32') killWindowsTree(record.pid);
+  else killPosixGroup(record.pid);
+  return { killed: true };
+}
+
+function waitUntil(predicate) {
+  const deadline = Date.now() + KILL_WAIT_MS;
+  while (!predicate() && Date.now() < deadline) sleep(100);
+  return predicate();
+}
+
+// The process that spawned the shell blocks in a sync loop and never reaps it: a zombie is not alive.
+function running(pid) {
+  if (!pidAlive(pid)) return false;
+  if (process.platform === 'win32') return true;
+  const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8' });
+  return r.status !== 0 || !String(r.stdout).trim().startsWith('Z');
+}
+
+function groupAlive(pgid) {
+  const r = spawnSync('ps', ['-A', '-o', 'pgid=,stat='], { encoding: 'utf8' });
+  if (r.status !== 0) {
+    try {
+      process.kill(-pgid, 0);
+      return true;
+    } catch (err) {
+      return err?.code === 'EPERM';
+    }
+  }
+  return String(r.stdout).split('\n').some((line) => {
+    const [group, stat = ''] = line.trim().split(/\s+/);
+    return Number(group) === pgid && !stat.startsWith('Z');
+  });
+}
+
+// The port belongs to the grandchild, not the shell: wait on the whole group.
+function killPosixGroup(pgid) {
+  try { process.kill(-pgid, 'SIGTERM'); } catch { /* group already gone */ }
+  if (!waitUntil(() => !groupAlive(pgid))) {
+    try { process.kill(-pgid, 'SIGKILL'); } catch { /* group already gone */ }
+    waitUntil(() => !groupAlive(pgid));
+  }
+}
+
+const WIN_SNAPSHOT =
+  'Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ p = $_.ProcessId; pp = $_.ParentProcessId; ' +
+  't = if ($_.CreationDate) { $_.CreationDate.ToFileTimeUtc() } else { 0 } } } | ConvertTo-Json -Compress';
+
+function windowsSnapshot() {
+  try {
+    const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', WIN_SNAPSHOT],
+      { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 });
+    const parsed = JSON.parse(out.trim() || '[]');
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return [];
+  }
+}
+
+// Windows keeps a dead parent's PID in ParentProcessId, so a child only counts when born after its parent.
+function windowsDescendants(rows, roots) {
+  const byPid = new Map(rows.map((r) => [r.p, r]));
+  const found = [];
+  const queue = [...roots];
+  while (queue.length > 0) {
+    const parent = byPid.get(queue.shift());
+    if (!parent) continue;
+    for (const row of rows) {
+      if (row.pp === parent.p && row.p !== parent.p && row.t >= parent.t && !found.includes(row.p) && !roots.includes(row.p)) {
+        found.push(row.p);
+        queue.push(row.p);
+      }
+    }
+  }
+  return found;
+}
+
+// Every PID goes through process.kill: killing via a console tool is banned in hooks (doctor-procs canary).
+// The rescan catches a child spawned between the snapshot and its parent's death.
+function killWindowsTree(rootPid) {
+  const first = windowsSnapshot();
+  const killed = [rootPid, ...windowsDescendants(first, [rootPid])];
+  for (const pid of killed) {
+    try { process.kill(pid); } catch { /* already gone */ }
+  }
+  const killedRows = first.filter((r) => killed.includes(r.p));
+  const rescan = windowsSnapshot().filter((r) => !killed.includes(r.p));
+  const stragglers = windowsDescendants([...killedRows, ...rescan], killed);
+  for (const pid of stragglers) {
+    try { process.kill(pid); } catch { /* already gone */ }
+  }
+  waitUntil(() => [...killed, ...stragglers].every((pid) => !pidAlive(pid)));
+}
+
+function tailLines(text, n = OUTPUT_TAIL_LINES) {
+  return String(text || '').trimEnd().split(/\r?\n/).slice(-n).join('\n');
+}
+
+function readLogTail(path) {
+  try { return tailLines(readFileSync(path, 'utf8')); } catch { return ''; }
+}
+
+/** @returns {{ killed: string[], skipped: string[], warnings: string[] }} */
+export function stopHostServices(gitCommonDir, projectName, { readCreatedAt = readProcessCreatedAt } = {}) {
+  const result = { killed: [], skipped: [], warnings: [] };
+  if (!gitCommonDir) return result;
+  const records = readState(gitCommonDir, projectName);
+  if (!records) return result;
+  for (const record of records) {
+    const outcome = killRecord(record, readCreatedAt);
+    if (outcome.killed) result.killed.push(record.name);
+    else {
+      result.skipped.push(record.name);
+      result.warnings.push(outcome.warning);
+    }
+  }
+  writeState(gitCommonDir, projectName, []);
+  return result;
+}
+
+/** Liveness by PID only: the creation-time read is too slow for a poll. */
+export function hostServicesStatus(gitCommonDir, projectName) {
+  const records = readState(gitCommonDir, projectName) ?? [];
+  return records.map((r) => {
+    const alive = pidAlive(r.pid);
+    return { name: r.name, pid: r.pid, alive, health: r.health ? alive && probeHealth(r.health) : null };
+  });
+}
+
+// A detached cmd.exe has no console, so the console apps it starts get a fresh one and drop the
+// log handles; a detached node holding the shell keeps them inherited down the tree.
+const WIN_LAUNCHER =
+  "const c=require('child_process').spawn(process.argv[1],{shell:true,stdio:'inherit',windowsHide:true});" +
+  'c.on(\'exit\',(k)=>process.exit(k??1))';
+
+function launch(svc, ctx, deadline, exec) {
+  const fail = (reason, output = '') => ({ ok: false, reason: `hostService "${svc.name}": ${reason}`, output });
+  const remaining = () => deadline - Date.now();
+
+  if (svc.build) {
+    const [file, ...args] = tokenize(svc.build);
+    const built = exec(file, args, { cwd: svc.dir, env: svc.childEnv, timeout: remaining() });
+    // A build killed at its timeout comes back as a plain non-zero exit: the deadline decides first.
+    if (remaining() <= 0) return fail(`timed out after ${svc.timeoutMs} ms during build`, tailLines(built.output));
+    if (built.code !== 0) return fail(`build failed (${svc.build}, exit ${built.code})`, tailLines(built.output));
+  }
+
+  const log = hostLogPath(ctx.gitCommonDir, ctx.projectName, svc.name);
+  mkdirSync(join(ctx.gitCommonDir, 'morph-spec'), { recursive: true });
+  const fd = openSync(log, 'w');
+  let child;
+  try {
+    // The CLI ends with process.exit: the child must own its group and hold none of our pipes.
+    const win = process.platform === 'win32';
+    child = spawn(win ? process.execPath : svc.start, win ? ['-e', WIN_LAUNCHER, svc.start] : [], {
+      cwd: svc.dir,
+      env: { ...process.env, ...svc.childEnv },
+      shell: !win,
+      detached: true,
+      windowsHide: true,
+      stdio: ['ignore', fd, fd],
+    });
+    child.on('error', () => {});
+    child.unref();
+  } finally {
+    closeSync(fd);
+  }
+  if (!child?.pid) return fail(`could not start (${svc.start})`, readLogTail(log));
+
+  const record = {
+    name: svc.name,
+    pid: child.pid,
+    createdAt: ctx.readCreatedAt(child.pid),
+    stamp: ctx.stamp ?? null,
+    log,
+    health: svc.health,
+  };
+
+  if (!svc.health) {
+    sleep(Math.min(NO_HEALTH_GRACE_MS, Math.max(remaining(), 0)));
+    if (!running(child.pid)) return { ...fail('exited right after start', readLogTail(log)), record };
+    return { ok: true, record };
+  }
+
+  while (true) {
+    if (probeHealth(svc.health)) return { ok: true, record };
+    if (!running(child.pid)) return { ...fail('exited before its health check went green', readLogTail(log)), record };
+    if (remaining() <= 0) {
+      return { ...fail(`health ${svc.health} not green within ${svc.timeoutMs} ms`, readLogTail(log)), record };
+    }
+    sleep(Math.min(HEALTH_POLL_MS, remaining()));
+  }
+}
+
+function isReusable(record, svc, ctx) {
+  if (!record || !running(record.pid)) return false;
+  if (ctx.readCreatedAt(record.pid) !== record.createdAt) return false;
+  return svc.health ? probeHealth(svc.health) : true;
+}
+
+/** @returns {{ status: 'pass'|'fail'|'skip', reused: boolean, services: object[], warnings: string[], reason?: string, output?: string }} */
+export function startHostServices(cwd, options = {}, exec) {
+  const {
+    services,
+    env: stackEnv = {},
+    gitCommonDir,
+    projectName,
+    stamp = null,
+    forceFresh = false,
+    readCreatedAt = readProcessCreatedAt,
+  } = options;
+
+  if (services === undefined || (Array.isArray(services) && services.length === 0)) {
+    return { status: 'skip', reused: false, services: [], warnings: [], reason: 'no e2e.hostServices configured' };
+  }
+  const invalid = validateServices(services);
+  if (invalid) return { status: 'fail', reused: false, services: [], warnings: [], reason: invalid };
+
+  const resolved = [];
+  for (const svc of services) {
+    const { env, health, missing } = interpolateEnv(svc, stackEnv);
+    if (missing.length > 0) {
+      return {
+        status: 'fail',
+        reused: false,
+        services: [],
+        warnings: [],
+        reason: `hostService "${svc.name}": no value for ${missing.map((v) => `\${${v}}`).join(', ')} ` +
+          '(looked in the e2e stack env and the process env)',
+      };
+    }
+    const dir = resolve(cwd, svc.cwd ?? '.');
+    if (!existsSync(dir)) {
+      return { status: 'fail', reused: false, services: [], warnings: [], reason: `hostService "${svc.name}": cwd ${dir} does not exist` };
+    }
+    resolved.push({
+      name: svc.name,
+      dir,
+      build: svc.build,
+      start: svc.start,
+      health,
+      timeoutMs: svc.timeoutMs ?? DEFAULT_HOST_TIMEOUT,
+      childEnv: { ...stackEnv, ...env },
+    });
+  }
+
+  const ctx = { gitCommonDir, projectName, stamp, readCreatedAt };
+  const previous = readState(gitCommonDir, projectName) ?? [];
+  const sameSet = previous.length === resolved.length && resolved.every((s) => previous.some((r) => r.name === s.name));
+  const divergent = forceFresh || !sameSet || previous.some((r) => r.stamp !== stamp);
+  const warnings = divergent && previous.length > 0
+    ? stopHostServices(gitCommonDir, projectName, { readCreatedAt }).warnings
+    : [];
+  const prior = divergent ? [] : previous;
+
+  const records = [];
+  const startedNow = [];
+  const out = [];
+  for (const [i, svc] of resolved.entries()) {
+    const old = prior.find((r) => r.name === svc.name);
+    if (isReusable(old, svc, ctx)) {
+      records.push(old);
+      out.push({ name: svc.name, pid: old.pid, reused: true, log: old.log });
+      continue;
+    }
+    if (old) {
+      const killed = killRecord(old, readCreatedAt);
+      if (killed.warning) warnings.push(killed.warning);
+    }
+
+    const result = launch(svc, ctx, Date.now() + svc.timeoutMs, exec);
+    if (!result.ok) {
+      for (const r of [...startedNow, result.record].filter(Boolean)) killRecord(r, readCreatedAt);
+      const unreached = resolved.slice(i + 1).map((s) => prior.find((r) => r.name === s.name)).filter(Boolean);
+      const kept = [...records.filter((r) => !startedNow.includes(r)), ...unreached];
+      writeState(gitCommonDir, projectName, kept);
+      return { status: 'fail', reused: false, services: out, warnings, reason: result.reason, output: result.output };
+    }
+    records.push(result.record);
+    startedNow.push(result.record);
+    writeState(gitCommonDir, projectName, records);
+    out.push({ name: svc.name, pid: result.record.pid, reused: false, log: result.record.log });
+  }
+
+  return { status: 'pass', reused: startedNow.length === 0, services: out, warnings };
+}

package/framework/schemas/config.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MORPH-SPEC .morph/config/config.json",
-  "description": "Describes project.tests[] — the plural declaration of the project's test suites — and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
+  "description": "Describes project.tests[] — the plural declaration of the project's test suites —, e2e.hostServices and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
   "type": "object",
   "additionalProperties": true,
   "properties": {
@@ -57,7 +57,7 @@
               "expectedCount": {
                 "type": "integer",
                 "minimum": 0,
-                "description": "Recorded baseline. Written ONLY by `morph-spec verify --record-baseline`, from a green run — never typed by hand."
+                "description": "Recorded baseline, kept only for `node-test` and `evals` (ignored, and removed by --record-baseline, on the other runners). Written ONLY by `morph-spec verify --record-baseline`, from a green run — never typed by hand."
               },
               "timeoutMs": {
                 "type": "integer",
@@ -119,6 +119,58 @@
         }
       }
     },
+    "e2e": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The verification stack of `e2e up` and of the verify e2e node. Only hostServices is described here; the other keys (auth, command, portEnvNames, ...) stay open.",
+      "properties": {
+        "hostServices": {
+          "type": "array",
+          "description": "Apps that run as host processes next to the compose stack, when building them inside the Docker VM is expensive: compose keeps only the dependencies. Order on `e2e up` and on the verify e2e node: compose up --wait, then each service in array order (build, start detached, health), then the auth seed. They stay up until `e2e down`, `finish`, `delete` or `worktree remove`. Reused while the code stamp (HEAD + status + diff) matches and health is green; a divergent stamp or --fresh/--fresh-e2e kills, rebuilds and restarts them. A failure (build exit != 0, timeout, health never green) fails `e2e up` (exit 1) and the e2e node with the service name and its log tail, kills what this run started and skips the seed. The authority at runtime is validateServices() in framework/hooks/shared/host-services.js.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "start"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9._-]+$",
+                "description": "Unique in the array. Names the log file (<git-common-dir>/morph-spec/e2e-host-<project>-<name>.log) and every message about the service."
+              },
+              "cwd": {
+                "type": "string",
+                "default": ".",
+                "description": "Working directory of build and start, relative to the project root. One that does not exist refuses."
+              },
+              "build": {
+                "type": "string",
+                "description": "Runs before start; a non-zero exit fails the bring-up."
+              },
+              "start": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The process, started detached; its output goes to the service log."
+              },
+              "env": {
+                "type": "object",
+                "additionalProperties": { "type": ["string", "number"] },
+                "description": "Added on top of process.env and the stack env (port block + e2e.auth.envFile). ${VAR} is resolved from the stack env, then process.env; a VAR with no value (or an empty one) refuses before any build, naming the variable and the service."
+              },
+              "health": {
+                "type": "string",
+                "description": "URL polled until it answers with an HTTP status below 500. ${VAR} interpolates like env. Without it, a process still alive 2 s after start counts as ready."
+              },
+              "timeoutMs": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 180000,
+                "description": "Ceiling for build + start + health together."
+              }
+            }
+          }
+        }
+      }
+    },
     "finishBackup": {
       "type": "object",
       "additionalProperties": true,

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_use: Use quando for iniciar um novo projeto de LP com o template Umbraco genérico
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.8.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_use: Use quando o usuário pedir "use /migrate-lp-to-umbraco {projeto}" ou descrever a necessidade de migrar uma LP para Umbraco
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.8.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Executa as fatias do plano de uma feature morph-spec — dispatch p
 version: core
 when_to_use: Use com o gate do plano aprovado, em "use /morph-apply {feature}" ou "implementar feature"
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.8.0"
 ---
 
 # morph-apply
@@ -129,7 +129,7 @@ config **antes** do verify: o stamp grava o HEAD, e código ou `config.json` com
 
 Depois `morph-spec verify {feature} --json`, **sem filtro** — nunca recorte o
 verify da feature. `--filter` é do loop do próprio sub-agente; o Gate 3 e o CI rodam a suíte
-inteira. Nó de teste sem `expectedCount`, ou fatia que apagou teste de propósito (limpeza, `morph-spec tests-audit`): acrescente `--record-baseline` a ESTA rodada — ela mede e
+inteira. Nó `node-test`/`evals` sem `expectedCount`, ou fatia que apagou teste de propósito (limpeza, `morph-spec tests-audit`): acrescente `--record-baseline` a ESTA rodada — ela mede e
 prova de uma vez; nunca um segundo verify só para gravar a baseline. Vermelho: corrija com `verify.feedback` (direto no código, ou re-despachando a fatia dona)
 e rode de novo; **3 tentativas** sem verde → `AskUserQuestion` ("Verify de {feature} vermelho após 3
 tentativas — aceitar com ressalva, continuar tentando, ou parar?"). Quem conta é o `feature.json`:

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_use: Use quando chegar "/morph-hotfix {feature}", quando a morph-plan rotear o pedido como workType hotfix, ou quando o usuário disser "produção caiu / hotfix / urgente" a respeito de um incidente
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.8.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Cuida da RAM e da CPU da máquina enquanto o morph-spec trabalha
 version: core
 when_to_use: Use quando a máquina estiver lenta ou sem RAM, um comando pesado esperou ou foi recusado pela fila, sobrou worktree de sub-agent, ou vários sub-agents pesados vão rodar em paralelo
 user-invocable: false
-cliVersion: "9.6.0"
+cliVersion: "9.8.0"
 ---
 
 # morph-machine

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

@@ -4,7 +4,7 @@ description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo
 version: core
 when_to_use: Use quando a tarefa for PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisar decidir modelo, prompt e aprovação
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.8.0"
 stacks:
   - dotnet
   - nextjs