@polymorphism-tech/morph-spec 9.5.0 → 9.7.0

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

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

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

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

package/framework/hooks/shared/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 };
+}