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

package/scripts/protected-state-check.js

@@ -5,6 +5,7 @@ const {
 	assertProtectedWriteAllowed,
 	recordProtectedStateAuditEvent,
 } = require('../lib/protected-state-surfaces');
+const { authorizeAndConsumeProtectedStateWrites } = require('../lib/protected-state-authority');
 
 function parseNameStatus(output) {
 	const files = [];
@@ -41,35 +42,60 @@ function getStagedFiles() {
 	return parseNameStatus(output);
 }
 
-function getAllowedSurfaces() {
-	return new Set(
-		String(process.env.FORGE_PROTECTED_STATE_ALLOWED_SURFACES || '')
-			.split(',')
-			.map(surface => surface.trim())
-			.filter(Boolean),
-	);
+function getStagedContent(file) {
+	if (process.env.FORGE_PROTECTED_STATE_STAGED_CONTENTS_JSON) {
+		const contents = JSON.parse(process.env.FORGE_PROTECTED_STATE_STAGED_CONTENTS_JSON);
+		return Object.prototype.hasOwnProperty.call(contents, file) ? contents[file] : null;
+	}
+
+	try {
+		return execFileSync('git', ['show', `:${file}`], {
+			encoding: null,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+	} catch (_error) {
+		return null;
+	}
 }
 
-function main() {
+async function main() {
 	const actor =
 		process.env.FORGE_PROTECTED_STATE_ACTOR ||
 		process.env.FORGE_ACTOR ||
 		process.env.USER ||
 		process.env.USERNAME ||
 		'unknown';
-	const allowedSurfaces = getAllowedSurfaces();
-	const decisions = getStagedFiles()
+	const probes = getStagedFiles()
 		.map(file => {
 			const probe = assertProtectedWriteAllowed(file, { actor, operation: 'staged_edit' });
-			if (probe.requiredSurface && allowedSurfaces.has(probe.requiredSurface)) {
-				return assertProtectedWriteAllowed(file, {
+			if (!probe.requiredSurface) return { probe };
+
+			const content = getStagedContent(probe.path);
+			if (content === null) return { probe };
+			return {
+				probe,
+				request: {
 					actor,
-					operation: 'staged_edit',
-					viaForgeApi: true,
 					surface: probe.requiredSurface,
-				});
-			}
-			return probe;
+					path: probe.path,
+					content,
+					operation: 'staged_edit',
+				},
+			};
+		});
+	const protectedProbes = probes.filter(entry => entry.request);
+	const authorization = await authorizeAndConsumeProtectedStateWrites(
+		process.cwd(),
+		protectedProbes.map(entry => entry.request),
+	);
+	let authorizationIndex = 0;
+	const decisions = probes
+		.map(entry => {
+			if (!entry.request) return entry.probe;
+			const trustedDecision = authorization.decisions[authorizationIndex++];
+			return trustedDecision.allowed
+				? trustedDecision
+				: { ...entry.probe, ...trustedDecision, repairHint: entry.probe.repairHint };
 		})
 		.filter(decision => !decision.allowed);
 
@@ -89,16 +115,15 @@ function main() {
 	for (const decision of decisions) {
 		console.error(`  - ${decision.path} [${decision.requiredSurface}]`);
 		console.error(`    Decision: ${decision.decision}`);
+		console.error(`    Reason: ${decision.reason}`);
 		console.error(`    Repair: ${decision.repairHint}`);
 	}
 	console.error('');
-	console.error('Use the owning Forge or Beads API surface, then stage the generated result if that command explicitly owns it.');
+	console.error('Use the owning Forge API surface, then stage the generated result if that command explicitly owns it.');
 	process.exit(1);
 }
 
-try {
-	main();
-} catch (error) {
+main().catch(error => {
 	console.error(`Protected state check failed: ${error.message}`);
 	process.exit(1);
-}
+});

package/scripts/run-command-eval.js

@@ -20,6 +20,7 @@ const {
 } = require('./lib/eval-runner');
 const { gradeTranscript } = require('./lib/grading');
 const { saveEvalResult } = require('./lib/eval-storage');
+const { verifyEvalReplay } = require('./lib/eval-evidence');
 
 // ---------------------------------------------------------------------------
 // parseArgs
@@ -89,6 +90,7 @@ function runShellCommand(command, worktreePath) {
  * @param {string} [options._basePath] — eval-logs base path for testing
  * @param {boolean} [options._skipWorktree=false] — skip worktree creation for unit tests
  * @param {Function} [options._executeOverride] — injectable command executor for testing
+ * @param {{envelope: object, inputs: {skill: string, tool: string}}} [options.replay] — exact-SHA replay binding
  * @returns {Promise<{ command: string, results: Array, overall_score: number, passed: boolean, duration_ms: number }>}
  */
 async function runEvalPipeline(evalSetPath, options = {}) {
@@ -98,6 +100,8 @@ async function runEvalPipeline(evalSetPath, options = {}) {
   const execOverride = options._executeOverride || null;
   const invokeGrader = options._invokeGrader || null;
   const basePath = options._basePath || undefined;
+  const hasReplay = Object.hasOwn(options, 'replay');
+  const replay = options.replay;
 
   const startTime = Date.now();
 
@@ -105,10 +109,34 @@ async function runEvalPipeline(evalSetPath, options = {}) {
   const evalSet = loadEvalSet(evalSetPath);
   const { command, queries } = evalSet;
 
+  let replayEvidence = null;
+  if (hasReplay) {
+    if (!replay || typeof replay !== 'object' || Array.isArray(replay)) throw new Error('replay must be an object');
+    for (const field of Object.keys(replay)) {
+      if (!['envelope', 'inputs'].includes(field)) throw new Error(`Unknown field 'replay.${field}'`);
+    }
+    if (!Object.hasOwn(replay, 'envelope')) throw new Error('replay.envelope is required');
+    if (!replay.inputs || typeof replay.inputs !== 'object' || Array.isArray(replay.inputs)) {
+      throw new Error('replay.inputs must be an object');
+    }
+    for (const field of Object.keys(replay.inputs)) {
+      if (!['skill', 'tool'].includes(field)) throw new Error(`Unknown field 'replay.inputs.${field}'`);
+    }
+    for (const field of ['skill', 'tool']) {
+      if (!Object.hasOwn(replay.inputs, field)) throw new Error(`replay.inputs.${field} is required`);
+    }
+    replayEvidence = verifyEvalReplay(replay.envelope, {
+      evalSet,
+      skill: replay.inputs.skill,
+      tool: replay.inputs.tool,
+    });
+    if (skipWorktree) throw new Error('Replay worktree verification cannot be skipped');
+  }
+
   // 2. Create eval worktree (unless skipped for testing)
   let worktreePath = null;
   if (!skipWorktree) {
-    const wt = await createEvalWorktree();
+    const wt = await createEvalWorktree(replayEvidence ? replayEvidence.head_sha : undefined);
     worktreePath = wt.path;
   }
 

package/scripts/sync-d20-audit.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pre-commit auto-heal for the D20 bd call-site kill-list artifact.
+ *
+ * The `d20-audit-artifact-current` release gate compares the checked-in kill-list
+ * against a live re-scan, so any commit that shifts the bd call-site census leaves the
+ * artifact stale until someone runs `forge release regen-audit`. Five builders in a row
+ * forgot, and each found out a full CI round later (kernel issue 4cf2c43d).
+ *
+ * This removes the regen from the human's list, the same way scripts/sync-agent-skills.js
+ * removed the `.agents/skills` mirror regen: gate on a cheap changed-path predicate,
+ * regenerate, re-stage, succeed quietly. The release gate stays as the backstop for
+ * anything committed without this hook.
+ *
+ * The predicate is `isBdCensusPath`, exported by the gate's own module, so the hook and
+ * the gate always agree on which files count. The artifact itself is not a census path,
+ * so re-staging it cannot re-trigger the hook.
+ *
+ * The guarantee, stated honestly: the auto-heal applies when the counted staged paths
+ * match the working tree. It decides from the index but regenerates from the working tree
+ * (`auditBdCallSites` walks the filesystem), so those two agree only when the counted paths
+ * are staged whole. When any of them is partially staged the hook regenerates nothing, says
+ * so on stderr, and defers to a manual `forge release regen-audit` plus the
+ * `d20-audit-artifact-current` release gate — which still fails a genuinely stale artifact.
+ */
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { AUDIT_ARTIFACT, isBdCensusPath, writeAuditArtifact } = require('../lib/release-readiness');
+
+function repoRoot(exec = execFileSync) {
+  try {
+    return exec('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return path.resolve(__dirname, '..');
+  }
+}
+
+/**
+ * Parses `git diff --cached --name-status -z`: a flat NUL-delimited token stream of a
+ * status followed by its path — `A\0path\0`, and `R100\0old\0new\0` for a rename or copy,
+ * which is read from both sides because both shift the census (the old path leaves it and
+ * the new one may not enter it).
+ *
+ * NUL delimiting is what makes this safe. Git's default output quotes and backslash-
+ * escapes pathnames with non-ASCII or special characters, and no line/tab split can
+ * represent a pathname that itself contains a tab or a newline. Under -z the pathnames are
+ * verbatim, so nothing here may trim them — a mis-read path silently drops a
+ * census-impacting change and skips the regen this hook exists to perform.
+ */
+function parseStagedNameStatus(output) {
+  const tokens = output.split('\0');
+  const files = [];
+
+  for (let index = 0; index < tokens.length; index++) {
+    const status = tokens[index];
+    if (status.length === 0) {
+      continue;
+    }
+    const pathCount = /^[RC]/.test(status) ? 2 : 1;
+    files.push(...tokens.slice(index + 1, index + 1 + pathCount).filter(Boolean));
+    index += pathCount;
+  }
+
+  return [...new Set(files)];
+}
+
+function stagedPaths(projectRoot, exec = execFileSync) {
+  return parseStagedNameStatus(
+    exec('git', ['-C', projectRoot, 'diff', '--cached', '--name-status', '-z', '--diff-filter=ACMRDT'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }),
+  );
+}
+
+/**
+ * Parses a bare NUL-delimited path list (`git diff --name-only -z`). Same rule as
+ * parseStagedNameStatus: under -z the pathnames are verbatim, so nothing here may trim them.
+ */
+function parseNulPaths(output) {
+  return output.split('\0').filter(Boolean);
+}
+
+/**
+ * Of the given paths, the ones whose working-tree content differs from their staged content.
+ * `git diff` without `--cached` is index-vs-worktree, which is exactly the question the
+ * auto-heal must answer before regenerating an artifact it builds from the working tree.
+ */
+function worktreeModifiedPaths(projectRoot, paths, exec = execFileSync) {
+  if (paths.length === 0) {
+    return [];
+  }
+
+  return parseNulPaths(
+    exec('git', ['-C', projectRoot, 'diff', '--name-only', '-z', '--', ...paths], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }),
+  );
+}
+
+function stageArtifact(projectRoot, relativePath) {
+  execFileSync('git', ['-C', projectRoot, 'add', '--', relativePath], {
+    stdio: ['ignore', 'ignore', 'inherit'],
+  });
+}
+
+function run(deps) {
+  const { projectRoot, staged, worktreeModified, isCensusPath, writeArtifact, stage, log, warn } = deps;
+
+  const triggers = staged().filter(filePath => isCensusPath(projectRoot, filePath));
+  if (triggers.length === 0) {
+    return { regenerated: false, triggers: [], partiallyStaged: [] };
+  }
+
+  const partiallyStaged = worktreeModified(projectRoot, triggers);
+  if (partiallyStaged.length > 0) {
+    warn(
+      `sync-d20-audit: SKIPPED — the index is partially staged, so ${AUDIT_ARTIFACT} was NOT regenerated.\n` +
+      `  Staged and separately modified in the working tree: ${partiallyStaged.join(', ')}\n` +
+      '  The artifact is built from the working tree, so regenerating it now would commit a\n' +
+      '  census of content this commit does not contain.\n' +
+      `  Run \`forge release regen-audit\` and stage ${AUDIT_ARTIFACT} yourself if this commit\n` +
+      '  shifts the bd call-site census; the d20-audit-artifact-current gate checks it either way.',
+    );
+    return { regenerated: false, triggers, partiallyStaged };
+  }
+
+  writeArtifact(projectRoot);
+  stage(projectRoot, AUDIT_ARTIFACT);
+  log(`sync-d20-audit: regenerated ${AUDIT_ARTIFACT} (census paths staged: ${triggers.join(', ')})`);
+  return { regenerated: true, triggers, partiallyStaged: [] };
+}
+
+function main() {
+  const projectRoot = repoRoot();
+  try {
+    run({
+      projectRoot,
+      staged: () => stagedPaths(projectRoot),
+      worktreeModified: (root, paths) => worktreeModifiedPaths(root, paths),
+      isCensusPath: isBdCensusPath,
+      writeArtifact: root => writeAuditArtifact(root),
+      stage: stageArtifact,
+      log: message => console.log(message),
+      warn: message => console.error(message),
+    });
+  } catch (error) {
+    console.error(`sync-d20-audit: failed to regenerate ${AUDIT_ARTIFACT} — ${error.message}`);
+    console.error('Run `forge release regen-audit` and stage the result, or fix the error above.');
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  run,
+  parseStagedNameStatus,
+  parseNulPaths,
+  stagedPaths,
+  worktreeModifiedPaths,
+  repoRoot,
+};

package/scripts/test-full-suite.js

@@ -13,6 +13,8 @@ const {
   readNewestProfile,
   walkTests,
 } = require('./test-ci-shard');
+const { createProcessTree, signalExitCode } = require('./process-tree');
+const { stripGitHookEnv } = require('./test');
 
 const rootDir = path.join(__dirname, '..');
 const reportDir = path.join(rootDir, 'test-results');
@@ -81,6 +83,29 @@ function walkAllTests(dir) {
   return results;
 }
 
+function assertExactShardAssignment(allTests, shardSpecs) {
+  const expectedFiles = new Set(allTests);
+  const assignedFiles = new Set();
+
+  for (const shard of shardSpecs) {
+    for (const file of shard.files) {
+      if (!expectedFiles.has(file)) {
+        throw new Error(`Test file ${file} is not part of the full suite`);
+      }
+      if (assignedFiles.has(file)) {
+        throw new Error(`Test file ${file} belongs to more than exactly one shard`);
+      }
+      assignedFiles.add(file);
+    }
+  }
+
+  for (const file of expectedFiles) {
+    if (!assignedFiles.has(file)) {
+      throw new Error(`Test file ${file} was omitted from the shard assignment`);
+    }
+  }
+}
+
 function buildShardSpecs(allTests, shardTotal, durationMap = new Map()) {
   const specs = [];
   for (let shardIndex = 0; shardIndex < shardTotal; shardIndex += 1) {
@@ -100,63 +125,247 @@ function buildShardSpecs(allTests, shardTotal, durationMap = new Map()) {
       source: plan.source,
     });
   }
+  assertExactShardAssignment(allTests, specs);
   return specs;
 }
 
+function buildShardTestArgs({ junitPath, files, root = rootDir }) {
+  return [
+    'test',
+    '--timeout',
+    '30000',
+    '--reporter=junit',
+    '--reporter-outfile',
+    junitPath,
+    ...files.map((file) => path.resolve(root, file)),
+  ];
+}
+
+function parseShardReceipt(output) {
+  if (typeof output !== 'string') return null;
+  const root = output.match(/^\s*(?:<\?xml\b[^?]*\?>\s*)?<testsuites\b([^>]*)>[\s\S]*<\/testsuites\s*>\s*$/);
+  const openingTags = output.match(/<testsuites\b/g) || [];
+  const closingTags = output.match(/<\/testsuites\s*>/g) || [];
+  if (!root || openingTags.length !== 1 || closingTags.length !== 1) return null;
+
+  const readAttribute = (name) => root[1].match(new RegExp('\\b' + name + '="(\\d+)"'));
+  const requiredAttributes = ['tests', 'assertions', 'failures', 'skipped'];
+  const values = requiredAttributes.map(readAttribute);
+  const hasInvalidRequiredAttribute = requiredAttributes.some((name, index) => {
+    const occurrences = root[1].match(new RegExp('\\b' + name + '\\s*=', 'g')) || [];
+    return occurrences.length !== 1 || !values[index];
+  });
+  const errorsOccurrences = root[1].match(/\berrors\s*=/g) || [];
+  const errorsAttribute = readAttribute('errors');
+  if (hasInvalidRequiredAttribute
+    || errorsOccurrences.length > 1
+    || (errorsOccurrences.length === 1 && !errorsAttribute)) return null;
+
+  const tests = Number.parseInt(values[0][1], 10);
+  const assertions = Number.parseInt(values[1][1], 10);
+  const failed = Number.parseInt(values[2][1], 10);
+  const errors = Number.parseInt(errorsAttribute?.[1] || '0', 10);
+  const skipped = Number.parseInt(values[3][1], 10);
+  const passed = tests - failed - errors - skipped;
+  if (tests === 0 || passed < 0) return null;
+  return { assertions, errors, failed, passed, skipped, tests };
+}
+
+function aggregateShardReceipts(receipts, expectedCount) {
+  const totals = {
+    assertions: 0,
+    errors: 0,
+    failed: 0,
+    passed: 0,
+    skipped: 0,
+    tests: 0,
+  };
+  const seen = new Set();
+  let incomplete = receipts.length !== expectedCount;
+  let failedProcess = false;
+
+  for (const receipt of receipts) {
+    if (receipt === null || typeof receipt !== 'object'
+      || !Number.isInteger(receipt.index)
+      || receipt.index < 0
+      || receipt.index >= expectedCount
+      || seen.has(receipt.index)) {
+      incomplete = true;
+      continue;
+    }
+    seen.add(receipt.index);
+    if (!Number.isInteger(receipt.code)) {
+      incomplete = true;
+    } else {
+      failedProcess ||= receipt.code !== 0;
+    }
+
+    const parsed = parseShardReceipt(receipt.output);
+    if (!parsed) {
+      incomplete = true;
+      continue;
+    }
+    for (const key of Object.keys(totals)) totals[key] += parsed[key];
+  }
+
+  incomplete ||= seen.size !== expectedCount;
+  const status = incomplete
+    ? 'INCOMPLETE'
+    : (failedProcess || totals.failed > 0 || totals.errors > 0 ? 'FAIL' : 'PASS');
+  return { ...totals, exitCode: status === 'PASS' ? 0 : 1, status };
+}
+
 function spawnShard(shard, options = {}) {
   const spawn = options.spawn || defaultSpawn;
   const env = options.env || process.env;
   const bunCommand = options.bunCommand || env.BUN_EXE || process.env.BUN_EXE || 'bun';
   const labelPrefix = options.labelPrefix || 'local-full';
-  fs.mkdirSync(reportDir, { recursive: true });
-  const junitPath = path.join(reportDir, `${labelPrefix}-shard-${shard.index}.xml`);
+  const targetReportDir = options.reportDirectory || reportDir;
+  const platform = options.platform || process.platform;
+  const processTree = options.processTree || createProcessTree({ env, platform });
+  const resolvedReportDir = path.resolve(targetReportDir);
+  const junitPath = path.resolve(resolvedReportDir, `${labelPrefix}-shard-${shard.index}.xml`);
+  if (path.dirname(junitPath) !== resolvedReportDir) {
+    return Promise.reject(new Error('label prefix must produce a receipt directly inside test-results'));
+  }
+  fs.mkdirSync(resolvedReportDir, { recursive: true });
 
   return new Promise((resolve, reject) => {
-    const child = spawn(bunCommand, [
-      'test',
-      '--timeout',
-      '30000',
-      '--reporter=junit',
-      '--reporter-outfile',
-      junitPath,
-      ...shard.files,
-    ], {
-      cwd: rootDir,
-      env,
-      shell: false,
-      stdio: 'inherit',
+    const reservation = processTree.reserveChild({
+      command: bunCommand,
+      kind: 'test-shard',
+      label: `${labelPrefix}-shard-${shard.index}`,
     });
+    if (!reservation) {
+      reject(new Error('test shard ownership manifest is unavailable'));
+      return;
+    }
+
+    let child;
+    let settled = false;
+    const finish = (code, output) => {
+      if (settled) return;
+      settled = true;
+      processTree.unregisterChild(reservation);
+      resolve({ code, index: shard.index, output });
+    };
+    try {
+      fs.rmSync(junitPath, { force: true });
+      child = spawn(bunCommand, buildShardTestArgs({
+        junitPath,
+        files: shard.files,
+      }), {
+        cwd: rootDir,
+        env,
+        shell: false,
+        stdio: 'inherit',
+        detached: platform !== 'win32',
+        windowsHide: true,
+      });
+      child.on('error', (error) => {
+        if (settled) return;
+        settled = true;
+        processTree.unregisterChild(reservation);
+        reject(error);
+      });
+      if (!processTree.registerChild(reservation, child)) {
+        settled = true;
+        if (typeof processTree.abortChild === 'function') {
+          processTree.abortChild(reservation, child);
+        } else {
+          try {
+            child.kill?.('SIGKILL');
+          } finally {
+            processTree.cleanup?.('SIGKILL');
+            processTree.unregisterChild(reservation);
+          }
+        }
+        reject(new Error('test shard process could not be registered'));
+        return;
+      }
+    } catch (error) {
+      if (!settled) processTree.unregisterChild(reservation);
+      reject(error);
+      return;
+    }
 
-    child.on('error', reject);
     child.on('close', (code) => {
-      resolve(code ?? 1);
+      let output = null;
+      try {
+        output = fs.readFileSync(junitPath, 'utf8');
+      } catch {}
+      finish(code ?? 1, output);
     });
   });
 }
 
 async function runFullSuiteInParallel(args = {}, deps = {}) {
-  const allTests = deps.allTests || listAllFullSuiteTests();
-  const shardTotal = Number.isInteger(args.shards) && args.shards > 0
-    ? args.shards
-    : getDefaultShardCount(deps.cpuCount);
-  const profile = deps.profile || readNewestProfile(reportDir);
-  const durationMap = deps.durationMap || createDurationMap(profile);
-  const shardSpecs = buildShardSpecs(allTests, shardTotal, durationMap);
-
-  if (shardSpecs.length === 0) {
-    console.log('No unit test files discovered for local full-suite run');
-    return 0;
-  }
+  const env = deps.env || process.env;
+  const platform = deps.platform || process.platform;
+  const processTree = deps.processTree || createProcessTree({ env, platform });
+  let signal = null;
+  let completed = false;
+  const removeSignalHandlers = processTree.installSignalHandlers((received) => {
+    signal = received;
+  });
+
+  try {
+    const allTests = deps.allTests || listAllFullSuiteTests();
+    const shardTotal = Number.isInteger(args.shards) && args.shards > 0
+      ? args.shards
+      : getDefaultShardCount(deps.cpuCount);
+    const profile = deps.profile || readNewestProfile(reportDir);
+    const durationMap = deps.durationMap || createDurationMap(profile);
+    const shardSpecs = buildShardSpecs(allTests, shardTotal, durationMap);
 
-  console.log(`Running local full suite in ${shardSpecs.length} shard(s)`);
-  const results = await Promise.all(shardSpecs.map((shard) => spawnShard(shard, {
-    bunCommand: deps.bunCommand,
-    env: deps.env,
-    labelPrefix: args.labelPrefix,
-    spawn: deps.spawn,
-  })));
+    if (shardSpecs.length === 0) {
+      const exitCode = signal ? signalExitCode(signal) : 1;
+      console.log('Full suite aggregate: status=INCOMPLETE tests=0 assertions=0 passed=0 failed=0 errors=0 skipped=0');
+      console.log('Full suite exit: ' + exitCode);
+      completed = true;
+      return exitCode;
+    }
 
-  return results.some((code) => code !== 0) ? 1 : 0;
+    fs.mkdirSync(reportDir, { recursive: true });
+    const runReportDir = fs.mkdtempSync(path.join(reportDir, 'full-suite-'));
+
+    console.log(`Running local full suite in ${shardSpecs.length} shard(s)`);
+    const childEnv = stripGitHookEnv(
+      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,
+        platform,
+        processTree,
+      })));
+    } catch (error) {
+      console.error('Full suite shard execution failed:', error);
+      const exitCode = signal ? signalExitCode(signal) : 1;
+      console.log('Full suite aggregate: status=INCOMPLETE tests=0 assertions=0 passed=0 failed=0 errors=0 skipped=0');
+      console.log('Full suite exit: ' + exitCode);
+      return exitCode;
+    }
+
+    const aggregate = aggregateShardReceipts(results, shardSpecs.length);
+    const exitCode = signal ? signalExitCode(signal) : aggregate.exitCode;
+    if (signal) aggregate.status = 'INCOMPLETE';
+    if (aggregate.status === 'PASS' && exitCode === 0) {
+      fs.rmSync(runReportDir, { force: true, recursive: true });
+    }
+    console.log(`Full suite aggregate: status=${aggregate.status} tests=${aggregate.tests} assertions=${aggregate.assertions} passed=${aggregate.passed} failed=${aggregate.failed} errors=${aggregate.errors} skipped=${aggregate.skipped}`);
+    console.log(`Full suite exit: ${exitCode}`);
+    completed = true;
+    return exitCode;
+  } finally {
+    removeSignalHandlers();
+    processTree.cleanup(signal || !completed ? 'SIGKILL' : 'SIGTERM');
+  }
 }
 
 async function main(argv = process.argv.slice(2), deps = {}) {
@@ -175,6 +384,9 @@ if (require.main === module) {
 }
 
 module.exports = {
+  aggregateShardReceipts,
+  assertExactShardAssignment,
+  buildShardTestArgs,
   buildShardSpecs,
   getDefaultShardCount,
   listAllFullSuiteTests,