forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/scripts/test-full-suite.js

@@ -5,24 +5,58 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { spawn: defaultSpawn } = require('node:child_process');
+const { stripVTControlCharacters } = require('node:util');
 
 const {
   createDurationMap,
   getShardPlan,
   getUnitTestRoots,
+  normalizePath,
   readNewestProfile,
   walkTests,
 } = require('./test-ci-shard');
+const {
+  buildProfile,
+  parseJUnitFiles,
+  parseJUnitTestcases,
+  walk: walkProfileFiles,
+} = require('./test-profile');
 const { createProcessTree, signalExitCode } = require('./process-tree');
 const { stripGitHookEnv } = require('./test');
+const { redact } = require('../lib/audit-evidence');
 
 const rootDir = path.join(__dirname, '..');
 const reportDir = path.join(rootDir, 'test-results');
+const RESOURCE_LANES = new Set(['unit', 'subprocess', 'exclusive']);
+const RESOURCE_LANE_RANK = new Map([
+  ['unit', 0],
+  ['subprocess', 1],
+  ['exclusive', 2],
+]);
+const DEFAULT_SHARD_TIMEOUT_MS = 30000;
+const STDERR_TAIL_LIMIT = 4096;
+const STDERR_OMITTED_LINE = '[stderr line omitted]\n';
+const JS_FAMILY_EXTENSIONS = ['.js', '.cjs', '.mjs', '.jsx', '.ts', '.cts', '.mts', '.tsx'];
+const FORGE_COORDINATION_ENV = new Set([
+  'FORGE_ACTOR',
+  'FORGE_SESSION_ID',
+  'FORGE_WORKTREE_ID',
+  'FORGE_LEASE_TTL_MS',
+]);
+
+function stripFullSuiteChildEnv(env) {
+  const childEnv = stripGitHookEnv(env);
+  for (const key of Object.keys(childEnv)) {
+    if (FORGE_COORDINATION_ENV.has(key.toUpperCase())) delete childEnv[key];
+  }
+  return childEnv;
+}
 
 function parseArgs(argv) {
   const args = {
     labelPrefix: 'local-full',
     shards: null,
+    timeoutMs: DEFAULT_SHARD_TIMEOUT_MS,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -31,11 +65,20 @@ function parseArgs(argv) {
 
     if (current === '--label-prefix') args.labelPrefix = next;
     if (current === '--shards') args.shards = Number.parseInt(next, 10);
+    if (current === '--timeout') args.timeoutMs = parseTimeoutMs(next);
   }
 
   return args;
 }
 
+function parseTimeoutMs(value) {
+  const timeoutMs = Number(value);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('--timeout must be a positive integer');
+  }
+  return timeoutMs;
+}
+
 function getDefaultShardCount(cpuCount = os.cpus().length) {
   if (!Number.isInteger(cpuCount) || cpuCount <= 1) return 1;
   return Math.max(2, Math.min(4, cpuCount - 1));
@@ -129,11 +172,440 @@ function buildShardSpecs(allTests, shardTotal, durationMap = new Map()) {
   return specs;
 }
 
-function buildShardTestArgs({ junitPath, files, root = rootDir }) {
+function strongestResourceLane(left, right) {
+  return RESOURCE_LANE_RANK.get(left) >= RESOURCE_LANE_RANK.get(right) ? left : right;
+}
+
+function tokenizeResourceSyntax(source) {
+  const tokens = [];
+  let index = 0;
+  while (index < source.length) {
+    const current = source[index];
+    if (/\s/.test(current)) {
+      index += 1;
+      continue;
+    }
+    if (current === '/' && source[index + 1] === '/') {
+      index = source.indexOf('\n', index + 2);
+      if (index === -1) break;
+      continue;
+    }
+    if (current === '/' && source[index + 1] === '*') {
+      const end = source.indexOf('*/', index + 2);
+      index = end === -1 ? source.length : end + 2;
+      continue;
+    }
+    if (current === '"' || current === "'") {
+      const quote = current;
+      let value = '';
+      index += 1;
+      while (index < source.length && source[index] !== quote) {
+        if (source[index] === '\\' && index + 1 < source.length) index += 1;
+        value += source[index];
+        index += 1;
+      }
+      index += 1;
+      tokens.push({ type: 'string', value });
+      continue;
+    }
+    if (current === '`') {
+      let dynamic = false;
+      let value = '';
+      index += 1;
+      while (index < source.length && source[index] !== '`') {
+        if (source[index] === '\\' && index + 1 < source.length) {
+          index += 1;
+        } else if (source[index] === '$' && source[index + 1] === '{') {
+          dynamic = true;
+        }
+        value += source[index];
+        index += 1;
+      }
+      index += 1;
+      tokens.push({ type: dynamic ? 'dynamic-string' : 'string', value });
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(current)) {
+      const start = index;
+      index += 1;
+      while (index < source.length && /[A-Za-z0-9_$]/.test(source[index])) index += 1;
+      tokens.push({ type: 'identifier', value: source.slice(start, index) });
+      continue;
+    }
+    tokens.push({ type: 'punctuator', value: current });
+    index += 1;
+  }
+  return tokens;
+}
+
+function inspectTestResourceSource(source, file, classifySource) {
+  const marker = source.match(/^\s*\/\/\s*forge-test-resource:\s*([^\s]+)\s*$/m);
+  let resource = 'unit';
+  if (marker) {
+    if (!RESOURCE_LANES.has(marker[1])) {
+      throw new Error(`Unknown full-suite resource lane ${marker[1]} in ${file}`);
+    }
+    resource = marker[1];
+  }
+  if (classifySource) {
+    const classified = classifySource(source, file);
+    if (!RESOURCE_LANES.has(classified)) {
+      throw new Error(`Unknown full-suite resource lane ${classified} in ${file}`);
+    }
+    resource = strongestResourceLane(resource, classified);
+  }
+
+  const imports = [];
+  const recordImport = (specifier) => {
+    if (specifier === 'child_process' || specifier === 'node:child_process') {
+      resource = strongestResourceLane(resource, 'subprocess');
+    } else if (specifier.startsWith('.')) {
+      imports.push(specifier);
+    }
+  };
+  const tokens = tokenizeResourceSyntax(source);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const previous = tokens[index - 1];
+    const next = tokens[index + 1];
+    if (token.value === 'Bun'
+      && next?.value === '.'
+      && (tokens[index + 2]?.value === 'spawn' || tokens[index + 2]?.value === 'spawnSync')
+      && tokens[index + 3]?.value === '(') {
+      resource = strongestResourceLane(resource, 'subprocess');
+      continue;
+    }
+    if ((token.value === 'require' || token.value === 'import')
+      && previous?.value !== '.'
+      && next?.value === '(') {
+      const argument = tokens[index + 2];
+      if (argument?.type === 'string' && tokens[index + 3]?.value === ')') {
+        recordImport(argument.value);
+      } else {
+        resource = strongestResourceLane(resource, 'subprocess');
+      }
+      continue;
+    }
+    if (token.value !== 'import' && token.value !== 'export') continue;
+    if (next?.type === 'string') {
+      recordImport(next.value);
+      continue;
+    }
+    for (let cursor = index + 1; cursor < tokens.length && tokens[cursor].value !== ';'; cursor += 1) {
+      if (tokens[cursor].value === 'from' && tokens[cursor + 1]?.type === 'string') {
+        recordImport(tokens[cursor + 1].value);
+        break;
+      }
+    }
+  }
+  return { imports, resource };
+}
+
+function isWithinRoot(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function createTestResourceClassifier(options = {}) {
+  const root = path.resolve(options.root || rootDir);
+  const realRoot = fs.realpathSync(root);
+  const readFile = options.readFile || ((target) => fs.readFileSync(target, 'utf8'));
+  const moduleCache = new Map();
+  const resolutionCache = new Map();
+  const resultCache = new Map();
+
+  const resolveLocalImport = (fromFile, specifier) => {
+    const cacheKey = `${fromFile}\0${specifier}`;
+    if (resolutionCache.has(cacheKey)) return resolutionCache.get(cacheKey);
+    const base = path.resolve(path.dirname(fromFile), specifier);
+    if (!isWithinRoot(realRoot, base)) {
+      resolutionCache.set(cacheKey, null);
+      return null;
+    }
+    const candidates = [
+      base,
+      ...JS_FAMILY_EXTENSIONS.map((extension) => base + extension),
+      ...JS_FAMILY_EXTENSIONS.map((extension) => path.join(base, `index${extension}`)),
+    ];
+    for (const candidate of candidates) {
+      let stats;
+      try {
+        stats = fs.statSync(candidate);
+      } catch {
+        continue;
+      }
+      if (!stats.isFile()) continue;
+      const resolved = fs.realpathSync(candidate);
+      if (!isWithinRoot(realRoot, resolved)) {
+        resolutionCache.set(cacheKey, null);
+        return null;
+      }
+      resolutionCache.set(cacheKey, resolved);
+      return resolved;
+    }
+    resolutionCache.set(cacheKey, null);
+    return null;
+  };
+
+  const inspectModule = (absoluteFile) => {
+    if (moduleCache.has(absoluteFile)) return moduleCache.get(absoluteFile);
+    let inspected;
+    try {
+      const source = readFile(absoluteFile);
+      if (typeof source !== 'string') throw new TypeError('resource source reader must return a string');
+      inspected = inspectTestResourceSource(source, path.relative(root, absoluteFile), options.classifySource);
+    } catch (error) {
+      if (error && /Unknown full-suite resource lane/.test(error.message)) throw error;
+      inspected = { imports: [], resource: 'subprocess' };
+    }
+    moduleCache.set(absoluteFile, inspected);
+    return inspected;
+  };
+
+  const classifyModule = (absoluteFile, visiting) => {
+    if (resultCache.has(absoluteFile)) {
+      return { complete: true, resource: resultCache.get(absoluteFile) };
+    }
+    if (visiting.has(absoluteFile)) return { complete: false, resource: 'unit' };
+
+    visiting.add(absoluteFile);
+    const inspected = inspectModule(absoluteFile);
+    let resource = inspected.resource;
+    let complete = true;
+    if (resource !== 'exclusive') {
+      for (const specifier of inspected.imports) {
+        const resolved = resolveLocalImport(absoluteFile, specifier);
+        if (!resolved) {
+          resource = strongestResourceLane(resource, 'subprocess');
+          continue;
+        }
+        const dependency = classifyModule(resolved, visiting);
+        resource = strongestResourceLane(resource, dependency.resource);
+        complete = complete && dependency.complete;
+        if (resource === 'exclusive') {
+          complete = true;
+          break;
+        }
+      }
+    }
+    visiting.delete(absoluteFile);
+    if (complete) resultCache.set(absoluteFile, resource);
+    return { complete, resource };
+  };
+
+  return (file) => {
+    const absoluteFile = path.resolve(root, file);
+    if (!isWithinRoot(root, absoluteFile)) return 'subprocess';
+    let realFile;
+    try {
+      realFile = fs.realpathSync(absoluteFile);
+    } catch {
+      return 'subprocess';
+    }
+    if (!isWithinRoot(realRoot, realFile)) return 'subprocess';
+    return classifyModule(realFile, new Set()).resource;
+  };
+}
+
+function classifyTestResource(file, options = {}) {
+  return createTestResourceClassifier(options)(file);
+}
+
+async function loadTestResourceMap(allTests, options = {}) {
+  const classify = createTestResourceClassifier(options);
+  const uniqueFiles = [...new Set(allTests)];
+  const entries = uniqueFiles.map((file) => [file, classify(file)]);
+  return new Map(entries);
+}
+
+function buildResourceLanePlan(allTests, shardTotal, durationMap = new Map(), options = {}) {
+  const classify = options.classify || ((file) => classifyTestResource(file, options));
+  const subprocessShardTotal = Number.isInteger(options.subprocessShardTotal)
+    && options.subprocessShardTotal > 0
+    ? options.subprocessShardTotal
+    : shardTotal;
+  const buckets = {
+    exclusive: [],
+    subprocess: [],
+    unit: [],
+  };
+  for (const file of allTests) {
+    const resource = classify(file);
+    if (!RESOURCE_LANES.has(resource)) {
+      throw new Error(`Unknown full-suite resource lane ${resource} for ${file}`);
+    }
+    buckets[resource].push(file);
+  }
+
+  const lanes = [];
+  const addShardedLane = (name, shardCap, concurrencyCap = shardCap) => {
+    if (buckets[name].length === 0) return;
+    const shardCount = Math.min(shardCap, shardTotal, buckets[name].length);
+    lanes.push({
+      concurrency: Math.min(concurrencyCap, shardCount),
+      name,
+      shards: buildShardSpecs(buckets[name], shardCount, durationMap),
+    });
+  };
+  addShardedLane('unit', 4);
+  if (buckets.subprocess.length > 0) {
+    const shardCount = Math.min(subprocessShardTotal, buckets.subprocess.length);
+    lanes.push({
+      concurrency: Math.min(3, shardCount),
+      name: 'subprocess',
+      // Extra shards improve tail balancing without increasing the worker budget.
+      shards: buildShardSpecs(buckets.subprocess, shardCount, durationMap),
+    });
+  }
+  if (buckets.exclusive.length > 0) {
+    lanes.push({
+      concurrency: 1,
+      name: 'exclusive',
+      shards: buckets.exclusive.map((file) => ({ files: [file], source: 'exclusive' })),
+    });
+  }
+
+  let nextIndex = 0;
+  for (const lane of lanes) {
+    for (const shard of lane.shards) {
+      shard.index = nextIndex;
+      nextIndex += 1;
+    }
+  }
+  assertExactShardAssignment(allTests, lanes.flatMap((lane) => lane.shards));
+  return lanes;
+}
+
+// A subprocess-lane worker owns two OS processes on Windows: the shard's own bun
+// runtime plus the bun.exe grandchild its tests spawn. Counting such a worker as
+// one budget unit oversubscribes small runners (3 workers is ~6 processes on 4
+// vCPU), so weight the grant by real process cost instead of by worker count.
+function laneWorkerCost(laneName, platform = process.platform) {
+  if (platform !== 'win32') return 1;
+  return laneName === 'unit' ? 1 : 2;
+}
+
+function computeLaneGrants(lanes, options = {}) {
+  const platform = options.platform || process.platform;
+  const workerBudget = Number.isInteger(options.workerBudget) && options.workerBudget > 0
+    ? options.workerBudget
+    : null;
+  const sharedLanes = lanes.filter((lane) => lane.name !== 'exclusive');
+  const overlapsSubprocess = sharedLanes.some((lane) => lane.name === 'subprocess');
+  const grants = new Map();
+  for (const lane of lanes) {
+    grants.set(lane, {
+      cost: laneWorkerCost(lane.name, platform),
+      deferred: false,
+      granted: lane.concurrency,
+      workerBudget,
+    });
+  }
+  if (workerBudget === null) {
+    for (const lane of sharedLanes) {
+      // One unit worker fills otherwise-idle CPU without recreating broad process pressure.
+      grants.get(lane).granted = overlapsSubprocess && lane.name === 'unit' ? 1 : lane.concurrency;
+    }
+    return grants;
+  }
+  // An explicit shard count is an operator-imposed cap on total concurrent
+  // children; reserve the budget for heavier subprocess workers first and
+  // defer leftover lanes until capacity frees instead of exceeding it.
+  const ordered = [...sharedLanes].sort(
+    (left, right) => (left.name === 'subprocess' ? 0 : 1) - (right.name === 'subprocess' ? 0 : 1),
+  );
+  let reservedCost = 0;
+  for (const [position, lane] of ordered.entries()) {
+    const entry = grants.get(lane);
+    const want = overlapsSubprocess && lane.name === 'unit' ? 1 : lane.concurrency;
+    const affordable = Math.floor(Math.max(0, workerBudget - reservedCost) / entry.cost);
+    // The strongest lane always keeps one worker so the suite can never stall at zero.
+    const granted = position === 0
+      ? Math.max(1, Math.min(want, affordable))
+      : Math.min(want, affordable);
+    entry.granted = granted;
+    entry.deferred = granted === 0;
+    if (entry.deferred) {
+      entry.deferredConcurrency = Math.max(
+        1,
+        Math.min(lane.concurrency, Math.floor(workerBudget / entry.cost)),
+      );
+    }
+    reservedCost += granted * entry.cost;
+  }
+  return grants;
+}
+
+async function runLaneSchedule(lanes, execute, cancel = () => {}, options = {}) {
+  const runLane = async (lane, concurrency = lane.concurrency, schedule = { stopped: false }) => {
+    const laneResults = new Array(lane.shards.length);
+    let nextIndex = 0;
+    let stopped = false;
+    const worker = async () => {
+      while (!stopped && !schedule.stopped) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= lane.shards.length) return;
+        try {
+          laneResults[index] = await execute(lane.shards[index], lane);
+        } catch (error) {
+          stopped = true;
+          if (!schedule.stopped) {
+            schedule.stopped = true;
+            cancel(error);
+          }
+          throw error;
+        }
+      }
+    };
+    const workers = Array.from(
+      { length: Math.min(concurrency, lane.shards.length) },
+      () => worker(),
+    );
+    const settled = await Promise.allSettled(workers);
+    const failure = settled.find((result) => result.status === 'rejected');
+    if (failure) throw failure.reason;
+    return laneResults;
+  };
+
+  const resultsByLane = new Map();
+  const sharedLanes = lanes.filter((lane) => lane.name !== 'exclusive');
+  const sharedSchedule = { stopped: false };
+  const grants = options.grants || computeLaneGrants(lanes, options);
+  const deferredLanes = sharedLanes.filter((lane) => grants.get(lane).deferred);
+  const immediateLanes = sharedLanes.filter((lane) => !grants.get(lane).deferred);
+  const settledSharedLanes = await Promise.allSettled(immediateLanes.map(async (lane) => {
+    resultsByLane.set(lane, await runLane(lane, grants.get(lane).granted, sharedSchedule));
+  }));
+  const sharedFailure = settledSharedLanes.find((result) => result.status === 'rejected');
+  if (sharedFailure) throw sharedFailure.reason;
+  // Budget-exhausted lanes start only after reserved capacity has been released.
+  const settledDeferredLanes = await Promise.allSettled(deferredLanes.map(async (lane) => {
+    resultsByLane.set(lane, await runLane(lane, grants.get(lane).deferredConcurrency, sharedSchedule));
+  }));
+  const deferredFailure = settledDeferredLanes.find((result) => result.status === 'rejected');
+  if (deferredFailure) throw deferredFailure.reason;
+
+  for (const lane of lanes.filter((candidate) => candidate.name === 'exclusive')) {
+    resultsByLane.set(lane, await runLane(lane));
+  }
+  return lanes.flatMap((lane) => {
+    const laneResults = resultsByLane.get(lane);
+    if (!laneResults) throw new Error(`Missing results for resource lane ${lane.name}`);
+    return laneResults;
+  });
+}
+
+function buildShardTestArgs({
+  junitPath,
+  files,
+  root = rootDir,
+  timeoutMs = DEFAULT_SHARD_TIMEOUT_MS,
+}) {
   return [
     'test',
     '--timeout',
-    '30000',
+    String(parseTimeoutMs(timeoutMs)),
     '--reporter=junit',
     '--reporter-outfile',
     junitPath,
@@ -171,6 +643,106 @@ function parseShardReceipt(output) {
   return { assertions, errors, failed, passed, skipped, tests };
 }
 
+function extractFailedTestCases(output, limit = 20) {
+  const failures = [];
+  for (const { attrs, body } of parseJUnitTestcases(output)) {
+    const type = body.match(/<(failure|error)\b/)?.[1];
+    if (!type) continue;
+    failures.push({
+      file: attrs.file || attrs.classname || 'unknown',
+      line: attrs.line || '',
+      name: attrs.name || 'unknown',
+      type,
+    });
+    if (failures.length >= limit) break;
+  }
+  return failures;
+}
+
+function classifyShardFailure(result) {
+  if (result?.signal) return 'signal';
+  const output = typeof result?.output === 'string' ? result.output : '';
+  const stderrTail = typeof result?.stderrTail === 'string' ? result.stderrTail : '';
+  const parsed = parseShardReceipt(output);
+  const failedReceipt = parsed && (parsed.failed > 0 || parsed.errors > 0);
+  const hasTimeoutDiagnostic = (value) => /\b(?:etimedout|timed?\s*out|timeout\s*(?:error|exception))\b/i.test(value);
+  const failedOutput = failedReceipt
+    ? parseJUnitTestcases(output)
+      .map(({ body }) => body)
+      .filter(body => /<(?:failure|error)\b/.test(body))
+      .join('\n')
+    : '';
+  const stderrDiagnostics = stripVTControlCharacters(stderrTail).split(/\r?\n/)
+    .filter(line => !/^\s*\((?:pass|fail|skip|todo)\)(?:\s|$)/i.test(line))
+    .join('\n');
+  if (hasTimeoutDiagnostic(failedOutput) || hasTimeoutDiagnostic(stderrDiagnostics)) return 'test-timeout';
+  if (failedReceipt) return 'test-failure';
+  if (parsed) return 'post-junit-exit';
+  return 'incomplete-receipt';
+}
+
+function createStderrTailCollector() {
+  let tail = '';
+  let pending = '';
+  let discardingLine = false;
+  const append = (value) => {
+    tail = (tail + value).slice(-STDERR_TAIL_LIMIT);
+  };
+
+  return {
+    write(chunk) {
+      let text = String(chunk);
+      if (discardingLine) {
+        const newline = text.indexOf('\n');
+        if (newline === -1) return;
+        text = text.slice(newline + 1);
+        discardingLine = false;
+      }
+      pending += text;
+      while (pending) {
+        const newline = pending.indexOf('\n');
+        if (newline !== -1) {
+          const line = pending.slice(0, newline + 1);
+          pending = pending.slice(newline + 1);
+          append(line.length > STDERR_TAIL_LIMIT ? STDERR_OMITTED_LINE : redact(line));
+          continue;
+        }
+        if (pending.length > STDERR_TAIL_LIMIT) {
+          pending = '';
+          discardingLine = true;
+          append(STDERR_OMITTED_LINE);
+        }
+        break;
+      }
+    },
+    value() {
+      if (!discardingLine && pending) append(redact(pending));
+      pending = '';
+      return tail;
+    },
+  };
+}
+
+function writeDurationProfile({ allTests, label, outputPath, runReportDir }) {
+  const files = walkProfileFiles(runReportDir, '.xml');
+  if (files.length === 0) return false;
+  const metrics = parseJUnitFiles(files);
+  const measured = new Set(metrics.allFileDurations.map((entry) => normalizePath(entry.file)));
+  if (!allTests.every((file) => measured.has(normalizePath(file)))) return false;
+
+  const profile = buildProfile({ integrationSkipped: false, label: label || 'local-full' }, metrics);
+  const target = path.resolve(outputPath);
+  const temporary = `${target}.tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(profile, null, 2));
+    fs.renameSync(temporary, target);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  return true;
+}
+
 function aggregateShardReceipts(receipts, expectedCount) {
   const totals = {
     assertions: 0,
@@ -223,6 +795,7 @@ function spawnShard(shard, options = {}) {
   const targetReportDir = options.reportDirectory || reportDir;
   const platform = options.platform || process.platform;
   const processTree = options.processTree || createProcessTree({ env, platform });
+  const stderrStream = options.stderrStream || process.stderr;
   const resolvedReportDir = path.resolve(targetReportDir);
   const junitPath = path.resolve(resolvedReportDir, `${labelPrefix}-shard-${shard.index}.xml`);
   if (path.dirname(junitPath) !== resolvedReportDir) {
@@ -243,28 +816,44 @@ function spawnShard(shard, options = {}) {
 
     let child;
     let settled = false;
-    const finish = (code, output) => {
+    let stderrDrainListener = null;
+    const stderrTail = createStderrTailCollector();
+    const clearStderrDrainListener = () => {
+      if (!stderrDrainListener) return;
+      stderrStream.off('drain', stderrDrainListener);
+      stderrDrainListener = null;
+    };
+    const finish = (code, output, signal) => {
       if (settled) return;
       settled = true;
+      clearStderrDrainListener();
       processTree.unregisterChild(reservation);
-      resolve({ code, index: shard.index, output });
+      const result = { code, index: shard.index, output };
+      if (code !== 0) {
+        if (signal) result.signal = signal;
+        const retainedStderr = stderrTail.value();
+        if (retainedStderr) result.stderrTail = retainedStderr;
+      }
+      resolve(result);
     };
     try {
       fs.rmSync(junitPath, { force: true });
       child = spawn(bunCommand, buildShardTestArgs({
         junitPath,
         files: shard.files,
+        timeoutMs: options.timeoutMs,
       }), {
         cwd: rootDir,
         env,
         shell: false,
-        stdio: 'inherit',
+        stdio: ['inherit', 'inherit', 'pipe'],
         detached: platform !== 'win32',
         windowsHide: true,
       });
       child.on('error', (error) => {
         if (settled) return;
         settled = true;
+        clearStderrDrainListener();
         processTree.unregisterChild(reservation);
         reject(error);
       });
@@ -283,18 +872,37 @@ function spawnShard(shard, options = {}) {
         reject(new Error('test shard process could not be registered'));
         return;
       }
+      child.stderr?.on('data', (chunk) => {
+        const canContinue = stderrStream.write(chunk);
+        stderrTail.write(chunk);
+        if (
+          canContinue === false
+          && !stderrDrainListener
+          && typeof child.stderr.pause === 'function'
+          && typeof child.stderr.resume === 'function'
+          && typeof stderrStream.once === 'function'
+          && typeof stderrStream.off === 'function'
+        ) {
+          child.stderr.pause();
+          stderrDrainListener = () => {
+            stderrDrainListener = null;
+            if (!settled) child.stderr.resume();
+          };
+          stderrStream.once('drain', stderrDrainListener);
+        }
+      });
     } catch (error) {
       if (!settled) processTree.unregisterChild(reservation);
       reject(error);
       return;
     }
 
-    child.on('close', (code) => {
+    child.on('close', (code, signal) => {
       let output = null;
       try {
         output = fs.readFileSync(junitPath, 'utf8');
       } catch {}
-      finish(code ?? 1, output);
+      finish(code ?? 1, output, signal);
     });
   });
 }
@@ -305,6 +913,7 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
   const processTree = deps.processTree || createProcessTree({ env, platform });
   let signal = null;
   let completed = false;
+  let scheduleCancelled = false;
   const removeSignalHandlers = processTree.installSignalHandlers((received) => {
     signal = received;
   });
@@ -314,9 +923,23 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
     const shardTotal = Number.isInteger(args.shards) && args.shards > 0
       ? args.shards
       : getDefaultShardCount(deps.cpuCount);
+    const subprocessShardTotal = Number.isInteger(args.shards) && args.shards > 0
+      ? shardTotal
+      : Math.max(6, shardTotal);
     const profile = deps.profile || readNewestProfile(reportDir);
     const durationMap = deps.durationMap || createDurationMap(profile);
-    const shardSpecs = buildShardSpecs(allTests, shardTotal, durationMap);
+    const resourceMap = deps.classify
+      ? null
+      : await loadTestResourceMap(allTests, {
+        classifySource: deps.classifySource,
+        readFile: deps.readFile,
+        root: deps.root || rootDir,
+      });
+    const lanePlan = buildResourceLanePlan(allTests, shardTotal, durationMap, {
+      classify: deps.classify || ((file) => resourceMap.get(file)),
+      subprocessShardTotal,
+    });
+    const shardSpecs = lanePlan.flatMap((lane) => lane.shards);
 
     if (shardSpecs.length === 0) {
       const exitCode = signal ? signalExitCode(signal) : 1;
@@ -330,20 +953,47 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
     const runReportDir = fs.mkdtempSync(path.join(reportDir, 'full-suite-'));
 
     console.log(`Running local full suite in ${shardSpecs.length} shard(s)`);
-    const childEnv = stripGitHookEnv(
+    const laneGrants = computeLaneGrants(lanePlan, { platform, workerBudget: shardTotal });
+    for (const lane of lanePlan) {
+      const grant = laneGrants.get(lane);
+      const granted = grant.deferred ? grant.deferredConcurrency : grant.granted;
+      const files = lane.shards.reduce((total, shard) => total + shard.files.length, 0);
+      console.log(`Resource lane ${lane.name}: files=${files} shards=${lane.shards.length} concurrency=${granted} (nominal=${lane.concurrency} cost=${grant.cost} budget=${shardTotal}${grant.deferred ? ' deferred' : ''})`);
+    }
+    const childEnv = stripFullSuiteChildEnv(
       typeof processTree.envFor === 'function' ? processTree.envFor(env) : env,
     );
     let results;
     try {
-      results = await Promise.all(shardSpecs.map((shard) => spawnShard(shard, {
-        bunCommand: deps.bunCommand,
-        env: childEnv,
-        labelPrefix: args.labelPrefix,
-        reportDirectory: runReportDir,
-        spawn: deps.spawn,
+      const nodeExecutable = deps.nodeExecutable ?? (
+        process.versions.bun ? globalThis.Bun?.which?.('node') : process.execPath
+      );
+      if (typeof nodeExecutable !== 'string' || !path.isAbsolute(nodeExecutable)) {
+        throw new Error('Full suite requires an absolute Node executable');
+      }
+      childEnv.FORGE_TEST_NODE_EXECUTABLE = nodeExecutable;
+      results = await runLaneSchedule(lanePlan, async (shard, lane) => ({
+        ...await spawnShard(shard, {
+          bunCommand: deps.bunCommand,
+          env: childEnv,
+          labelPrefix: args.labelPrefix,
+          reportDirectory: runReportDir,
+          spawn: deps.spawn,
+          platform,
+          processTree,
+          stderrStream: deps.stderrStream,
+          timeoutMs: args.timeoutMs,
+        }),
+        resource: lane.name,
+      }), () => {
+        if (scheduleCancelled) return;
+        scheduleCancelled = true;
+        processTree.cleanup('SIGKILL');
+      }, {
+        grants: laneGrants,
         platform,
-        processTree,
-      })));
+        workerBudget: shardTotal,
+      });
     } catch (error) {
       console.error('Full suite shard execution failed:', error);
       const exitCode = signal ? signalExitCode(signal) : 1;
@@ -352,9 +1002,36 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
       return exitCode;
     }
 
+    const nonzeroShards = results.filter((result) => result.code !== 0);
+    if (nonzeroShards.length > 0) {
+      console.error(`Full suite non-zero shards: ${nonzeroShards.map((result) => {
+        let diagnostic = `${result.index}:${result.resource}:exit=${result.code} cause=${classifyShardFailure(result)}`;
+        if (result.signal) diagnostic += ` signal=${result.signal}`;
+        const stderrTail = result.stderrTail?.trim();
+        if (stderrTail) diagnostic += ` stderr=${JSON.stringify(stderrTail)}`;
+        return diagnostic;
+      }).join(', ')}`);
+      const failedTests = nonzeroShards.flatMap((result) => extractFailedTestCases(result.output));
+      if (failedTests.length > 0) {
+        console.error(`Full suite failing tests: ${failedTests.map((failure) => `${failure.file}${failure.line ? `:${failure.line}` : ''} (${failure.name})`).join(', ')}`);
+      }
+    }
     const aggregate = aggregateShardReceipts(results, shardSpecs.length);
     const exitCode = signal ? signalExitCode(signal) : aggregate.exitCode;
     if (signal) aggregate.status = 'INCOMPLETE';
+    if (aggregate.status !== 'INCOMPLETE') {
+      const labelPrefix = args.labelPrefix || 'local-full';
+      try {
+        (deps.writeDurationProfile || writeDurationProfile)({
+          allTests,
+          label: labelPrefix,
+          outputPath: deps.profileOutputPath || path.join(reportDir, `${labelPrefix}.profile.json`),
+          runReportDir,
+        });
+      } catch (error) {
+        console.warn(`Full suite profile was not updated: ${error.message}`);
+      }
+    }
     if (aggregate.status === 'PASS' && exitCode === 0) {
       fs.rmSync(runReportDir, { force: true, recursive: true });
     }
@@ -364,7 +1041,7 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
     return exitCode;
   } finally {
     removeSignalHandlers();
-    processTree.cleanup(signal || !completed ? 'SIGKILL' : 'SIGTERM');
+    if (!scheduleCancelled) processTree.cleanup(signal || !completed ? 'SIGKILL' : 'SIGTERM');
   }
 }
 
@@ -386,13 +1063,22 @@ if (require.main === module) {
 module.exports = {
   aggregateShardReceipts,
   assertExactShardAssignment,
+  buildResourceLanePlan,
   buildShardTestArgs,
   buildShardSpecs,
+  classifyShardFailure,
+  classifyTestResource,
+  computeLaneGrants,
+  extractFailedTestCases,
+  laneWorkerCost,
   getDefaultShardCount,
   listAllFullSuiteTests,
+  loadTestResourceMap,
   main,
   parseArgs,
+  runLaneSchedule,
   runFullSuiteInParallel,
   spawnShard,
   walkAllTests,
+  writeDurationProfile,
 };