@goodandready/dsh-moa 0.2.25 → 0.2.26

package/lib/client.js

@@ -63,6 +63,10 @@ window.__ModuleLoader__.load({
       'aggregator.peer_hint': 'Candidates critique each other\'s solutions and refine their code before final judge synthesis.',
       'aggregator.override_label': 'Allow Candidate Override Actions',
       'aggregator.override_hint': 'Keeps candidate workspaces in .moa to let you apply any candidate files via chat command.',
+      'aggregator.test_gate_label': 'Test Execution Gate (Automatic Sandbox Testing)',
+      'aggregator.test_gate_hint': 'Executes test suite inside candidate sandboxes before judge review. Real test results guide winner selection.',
+      'aggregator.test_cmd_placeholder': 'e.g. npm test or node --test',
+      'aggregator.test_timeout_label': 'Test timeout (sec):',
       'proposers.role_label': 'Persona:',
       'proposers.role_general': 'General',
       'proposers.role_minimalist': 'Minimalist',
@@ -177,6 +181,10 @@ window.__ModuleLoader__.load({
       'aggregator.peer_hint': '在主裁判终审前，各候选模型互相审阅并改进彼此的方案代码。',
       'aggregator.override_label': '允许手动候选方案提拔操作 (Override)',
       'aggregator.override_hint': '在 .moa 目录中保留候选模型的工作区，允许通过聊天命令提拔任意候选模型的文件。',
+      'aggregator.test_gate_label': '测试门禁 (沙箱自动化测试)',
+      'aggregator.test_gate_hint': '在裁判评审前在候选沙箱中执行测试套件，真实测试结果将指导获胜者评选。',
+      'aggregator.test_cmd_placeholder': '例如 npm test 或 node --test',
+      'aggregator.test_timeout_label': '测试超时时间 (秒):',
       'proposers.role_label': '工程角色画像：',
       'proposers.role_general': '通用平衡 (General)',
       'proposers.role_minimalist': '极简标准库 (Minimalist)',
@@ -1273,6 +1281,52 @@ window.__ModuleLoader__.load({
                 { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)', marginLeft: 22 } },
                 t('aggregator.override_hint')
               ),
+              React.createElement(
+                'label',
+                { style: { display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: 13, fontWeight: 500, marginTop: 8 } },
+                React.createElement('input', {
+                  type: 'checkbox',
+                  checked: Boolean(currentPreset.test_gate_enabled),
+                  onChange: (e) => updateCurrentPreset((p) => ({ ...p, test_gate_enabled: e.target.checked })),
+                  style: { accentColor: 'var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))', cursor: 'pointer' },
+                }),
+                t('aggregator.test_gate_label')
+              ),
+              React.createElement(
+                'div',
+                { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)', marginLeft: 22 } },
+                t('aggregator.test_gate_hint')
+              ),
+              Boolean(currentPreset.test_gate_enabled) &&
+                React.createElement(
+                  'div',
+                  { style: { marginLeft: 22, marginTop: 6, display: 'flex', flexDirection: 'column', gap: 6 } },
+                  React.createElement('input', {
+                    type: 'text',
+                    className: 'moa-input',
+                    style: { fontSize: 12, height: 28 },
+                    placeholder: t('aggregator.test_cmd_placeholder'),
+                    value: currentPreset.test_command || '',
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, test_command: e.target.value })),
+                  }),
+                  React.createElement(
+                    'div',
+                    { style: { display: 'flex', alignItems: 'center', gap: 8 } },
+                    React.createElement('span', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, t('aggregator.test_timeout_label')),
+                    React.createElement('input', {
+                      type: 'number',
+                      className: 'moa-input',
+                      style: { width: 70, height: 26, fontSize: 12 },
+                      min: 5,
+                      max: 120,
+                      value: currentPreset.test_gate_timeout_sec ?? 15,
+                      onChange: (e) => {
+                        const val = parseInt(e.target.value, 10)
+                        updateCurrentPreset((p) => ({ ...p, test_gate_timeout_sec: isNaN(val) ? 15 : val }))
+                      },
+                    })
+                  )
+                ),
               /* Fallback Judges Chain */
               React.createElement(
                 'div',

package/lib/history.js

@@ -416,5 +416,11 @@ export function candidatesForHistory(referenceOutputs) {
     files: (r.files || []).map((f) => f.relativePath),
     usage: r.usage || { inputTokens: 0, outputTokens: 0 },
     costUsd: r.costUsd || 0,
+    testResult: r.testResult ? {
+      passed: r.testResult.passed,
+      exitCode: r.testResult.exitCode,
+      summary: r.testResult.summary,
+      durationMs: r.testResult.durationMs,
+    } : null,
   }))
 }

package/lib/index.js

@@ -74,6 +74,9 @@ export const PresetSchema = z.object({
   allow_candidate_override: z.boolean().default(false),
   max_tokens: z.number().default(4096),
   judge_criteria: z.string().default(''),
+  test_gate_enabled: z.boolean().default(false),
+  test_command: z.string().default(''),
+  test_gate_timeout_sec: z.number().default(15),
 })
 
 export const Config = z.object({
@@ -394,3 +397,5 @@ export function apply(ctx, config) {
     })
   }, 'dsh-moa: llm stream interceptor')
 }
+
+export { executeTestGateForCandidates, runCandidateTestGate } from './moa-test-gate.js'

package/lib/moa-prompts.js

@@ -57,6 +57,12 @@ export const ROLE_PERSONA_PROMPTS = {
   general: '',
 }
 
+export const TEST_GATE_DIRECTIVE = `### 🧪 Test Execution Gate Directive:
+Some or all candidates were evaluated by executing real project tests against their sandbox implementations.
+CRITICAL JUDGE DIRECTIVE: Test execution results are empirical ground truth.
+- A candidate whose code passes all tests (PASS) must be strongly favored over candidates whose code causes test failures or exceptions (FAIL).
+- If a candidate with test failures is chosen due to significantly superior architecture, you MUST explicitly identify and repair the failing test/code in your final synthesis deliverable.`
+
 export const SYNTAX_CORRECTION_DIRECTIVE = `### ⚠️ Syntax Warning & Auto-Fix Directive:
 Some candidate proposals have detected syntax flaws (annotated with [⚠️ Syntax Warning]).
 CRITICAL JUDGE DIRECTIVE: If a candidate with a syntax flaw presents superior architecture, algorithm, or engineering logic compared to other candidates, DO NOT reject them solely for this syntax flaw!
@@ -235,10 +241,14 @@ export function buildCuratorSynthesisPrompt(userPrompt, referenceOutputs = [], j
       const role = r.role_persona || r.slot?.role_persona || r.role || r.slot?.role
       const roleNote = role && role !== 'general' ? ` [Focus: ${role}]` : ''
       const syntaxNote = r.syntaxWarning ? ` [⚠️ Syntax Warning: ${r.syntaxWarning}]` : ''
+      const testNote = r.testResult ? ` [🧪 Test Gate: ${r.testResult.summary}]` : ''
       const header = isBlind
-        ? `Candidate ${i + 1}${roleNote}:${syntaxNote}${fileSummary}`
-        : `Candidate ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${fileSummary}`
-      return `${header}\n${textContent}`
+        ? `Candidate ${i + 1}${roleNote}:${syntaxNote}${testNote}${fileSummary}`
+        : `Candidate ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${testNote}${fileSummary}`
+      const testReport = r.testResult
+        ? `\n\n[🧪 Test Execution Gate Report]:\n- Status: ${r.testResult.passed ? 'PASSED ✅' : 'FAILED ❌'} (Exit code: ${r.testResult.exitCode})\n- Duration: ${r.testResult.durationMs}ms\n- Output:\n\`\`\`\n${r.testResult.output}\n\`\`\``
+        : ''
+      return `${header}\n${textContent}${testReport}`
     })
     .join('\n\n')
 
@@ -258,6 +268,7 @@ ${joined}
 ${ANTIPATTERNS_RUBRIC}
 
 ${LANGUAGE_MIRRORING_DIRECTIVE}
+${referenceOutputs.some((r) => r.testResult) ? `\n${TEST_GATE_DIRECTIVE}\n` : ''}
 ${referenceOutputs.some((r) => r.syntaxWarning) ? `
 ${SYNTAX_CORRECTION_DIRECTIVE}
 ` : ''}
@@ -304,10 +315,14 @@ export function buildSynthesisPrompt(userPrompt, referenceOutputs = [], judgeCri
       const role = r.role_persona || r.slot?.role_persona || r.role || r.slot?.role
       const roleNote = role && role !== 'general' ? ` [Focus: ${role}]` : ''
       const syntaxNote = r.syntaxWarning ? ` [⚠️ Syntax Warning: ${r.syntaxWarning}]` : ''
+      const testNote = r.testResult ? ` [🧪 Test Gate: ${r.testResult.summary}]` : ''
       const header = isBlind
-        ? `Reference ${i + 1}${roleNote}:${syntaxNote}${fileSummary}`
-        : `Reference ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${fileSummary}`
-      return `${header}\n${textContent}`
+        ? `Reference ${i + 1}${roleNote}:${syntaxNote}${testNote}${fileSummary}`
+        : `Reference ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${testNote}${fileSummary}`
+      const testReport = r.testResult
+        ? `\n\n[🧪 Test Execution Gate Report]:\n- Status: ${r.testResult.passed ? 'PASSED ✅' : 'FAILED ❌'} (Exit code: ${r.testResult.exitCode})\n- Duration: ${r.testResult.durationMs}ms\n- Output:\n\`\`\`\n${r.testResult.output}\n\`\`\``
+        : ''
+      return `${header}\n${textContent}${testReport}`
     })
     .join('\n\n')
 
@@ -326,6 +341,7 @@ ${joined}
 ${ANTIPATTERNS_RUBRIC}
 
 ${LANGUAGE_MIRRORING_DIRECTIVE}
+${referenceOutputs.some((r) => r.testResult) ? `\n${TEST_GATE_DIRECTIVE}\n` : ''}
 ${referenceOutputs.some((r) => r.syntaxWarning) ? `\n${SYNTAX_CORRECTION_DIRECTIVE}\n` : ''}
 Instructions:
 Your response MUST be structured into three clear parts:

package/lib/moa-runner.js

@@ -1,28 +1,21 @@
-import { bestEffort } from './best-effort.js'
-/**
- * DeepSeek Harness Mixture of Agents (MoA) — Runner Engine
- * Parallel fan-out, Consilium Round 2 peer critique, aggregator synthesis & streaming.
- */
-
 import path from 'node:path'
 import crypto from 'node:crypto'
+import { bestEffort } from './best-effort.js'
 import { extractFileBlocks, collectProjectContext, formatProjectContext, isRefinementTask, writeCandidateWorkspace, promoteCandidateWorkspace, cleanMoaWorkspaces, verifyFileSyntax } from './file-workspace.js'
 import { estimateTokenCost, summarizeMoAUsage } from './pricing.js'
 import { recordMoaRun, recordMoaRunAsync, candidatesForHistory } from './history.js'
 import { createPromotedPreview } from './live-canvas.js'
 import { slotLabel, cleanAdvisoryMessages, isBroadPromptRequiringQuestions, buildQuestionSynthesisPrompt, buildCuratorSynthesisPrompt, buildSynthesisPrompt, buildPeerCritiquePrompt, ROLE_PERSONA_PROMPTS, SYSTEM_ROLE_PROPOSER, ANTIPATTERNS_RUBRIC } from './moa-prompts.js'
 import { parseWinnerIndex, parseRecommendedAssembler, parseMoACommand, stripOrSummarizeCode, formatMoAResponse } from './moa-parser.js'
+import { REFERENCE_SYSTEM_PROMPT, callWithTransientRetry, runReferencesParallel } from './moa-candidates.js'
+import { executeTestGateForCandidates, runCandidateTestGate } from './moa-test-gate.js'
 
 // Re-exports for consumers & backward compatibility
 export { slotLabel, cleanAdvisoryMessages, isBroadPromptRequiringQuestions, buildQuestionSynthesisPrompt, buildCuratorSynthesisPrompt, buildSynthesisPrompt, ANTIPATTERNS_RUBRIC } from './moa-prompts.js'
 export { parseWinnerIndex, parseRecommendedAssembler, parseMoACommand, stripOrSummarizeCode, formatMoAResponse } from './moa-parser.js'
 export { estimateTokenCost, summarizeMoAUsage } from './pricing.js'
-
-/**
- * Invokes LLM call with transient retry for recoverable network/rate-limit errors.
- */
-import { REFERENCE_SYSTEM_PROMPT, callWithTransientRetry, runReferencesParallel } from './moa-candidates.js'
-export { REFERENCE_SYSTEM_PROMPT, callWithTransientRetry, runReferencesParallel }
+export { REFERENCE_SYSTEM_PROMPT, callWithTransientRetry, runReferencesParallel } from './moa-candidates.js'
+export { executeTestGateForCandidates, runCandidateTestGate } from './moa-test-gate.js'
 
 /**
  * Executes the full Mixture of Agents pipeline.
@@ -39,18 +32,18 @@ export async function runMoAPipeline({
   liveCanvas = null,
   onStreamDelta = null,
   signal = null,
+  testGateEnabled = null,
+  testCommand = null,
+  execFn = null,
 }) {
   if (signal?.aborted) return { error: new Error('Turn aborted') }
   const startTime = Date.now()
 
   // 1. Resolve configurations
   const referenceModels = Array.isArray(preset?.reference_models) && preset.reference_models.length > 0
-    ? preset.reference_models
-    : [{ provider: 'opencode-go', model: 'deepseek-v4-flash' }]
-
+    ? preset.reference_models : [{ provider: 'opencode-go', model: 'deepseek-v4-flash' }]
   const primaryJudge = preset?.aggregator?.provider && preset?.aggregator?.model
-    ? preset.aggregator
-    : { provider: 'codex', model: 'gpt-5.6-sol' }
+    ? preset.aggregator : { provider: 'codex', model: 'gpt-5.6-sol' }
 
   const fallbackJudges = Array.isArray(preset?.aggregator_fallbacks) ? preset.aggregator_fallbacks : []
   const judgesChain = [primaryJudge, ...fallbackJudges]
@@ -60,17 +53,12 @@ export async function runMoAPipeline({
   const maxTokens = typeof preset?.max_tokens === 'number' ? preset.max_tokens : 4096
   const judgeCriteria = preset?.judge_criteria || ''
   const isFastMode = referenceModels.length === 1 && !preset?.curator_synthesis
-  const isCuratorSynthesis = Boolean(preset?.curator_synthesis)
-  const isStreamAggregator = preset?.stream_aggregator !== false
-  const isQuorumEnabled = Boolean(preset?.quorum_enabled)
-  const gracePeriodSec = typeof preset?.grace_period_sec === 'number' ? preset.grace_period_sec : 10
-  const candidateRetries = 1
-  const refTimeoutSec = typeof preset?.reference_timeout_sec === 'number' ? preset.reference_timeout_sec : 60
+  const isCuratorSynthesis = Boolean(preset?.curator_synthesis), isStreamAggregator = preset?.stream_aggregator !== false
+  const isQuorumEnabled = Boolean(preset?.quorum_enabled), gracePeriodSec = typeof preset?.grace_period_sec === 'number' ? preset.grace_period_sec : 10
+  const candidateRetries = 1, refTimeoutSec = typeof preset?.reference_timeout_sec === 'number' ? preset.reference_timeout_sec : 60
   const aggTimeoutSec = typeof preset?.aggregator_timeout_sec === 'number' ? preset.aggregator_timeout_sec : 180
-  const isBlindEvaluation = Boolean(preset?.blind_evaluation)
-  const isPeerCritiqueEnabled = Boolean(preset?.peer_critique_enabled)
-  const allowCandidateOverride = Boolean(preset?.allow_candidate_override)
-  const runId = crypto.randomUUID()
+  const isBlindEvaluation = Boolean(preset?.blind_evaluation), isPeerCritiqueEnabled = Boolean(preset?.peer_critique_enabled)
+  const allowCandidateOverride = Boolean(preset?.allow_candidate_override), runId = crypto.randomUUID()
 
   // 2. Collect project context for refinement tasks
   const collectedCtx = await collectProjectContext(cwd, 16000)
@@ -159,10 +147,20 @@ export async function runMoAPipeline({
     const files = extractFileBlocks(ref.text)
     ref.files = files
     if (files.length > 0) {
+      ref.syntaxWarning = (verifyFileSyntax(files) || []).map((w) => `${w.file}: ${w.error}`).join('; ')
       await writeCandidateWorkspace(cwd, i + 1, files)
     }
   }
 
+  // 5b. Test Execution Gate
+  await executeTestGateForCandidates({
+    cwd,
+    referenceOutputs,
+    preset,
+    options: { testGateEnabled, testCommand, execFn },
+    onProgress,
+  })
+
   // 6. Questionnaire synthesis branch
   if (needsQuestions) {
     if (typeof onProgress === 'function') {
@@ -188,11 +186,7 @@ export async function runMoAPipeline({
       qUsage = estimateTokenCost(primaryJudge, qFallbackUsage, prices)
     } catch (err) {
       console.warn('[dsh-moa] Questionnaire synthesis failed, proceeding with fallback questions:', err)
-      questionsContent = `### Clarification of Requirements: "${userPrompt}"\n\n` +
-        '1. **Architecture & Scope**: Single-file deliverable or multi-module project structure?\n' +
-        '2. **Design & Style**: Minimalist, dark mode, or clean neutral theme?\n' +
-        '3. **Functional Priorities**: Core MVP or comprehensive extended implementation?\n\n' +
-        '*Reply with your preferences (e.g. "1, 2") or proceed with defaults.*'
+      questionsContent = `### Clarification of Requirements: "${userPrompt}"\n\n1. **Architecture & Scope**: Single-file deliverable or multi-module project structure?\n2. **Design & Style**: Minimalist, dark mode, or clean neutral theme?\n3. **Functional Priorities**: Core MVP or comprehensive extended implementation?\n\n*Reply with your preferences (e.g. "1, 2") or proceed with defaults.*`
     }
 
     await cleanMoaWorkspaces(cwd)
@@ -344,6 +338,13 @@ export async function runMoAPipeline({
       }
     })
     await Promise.allSettled(r2Promises)
+    await executeTestGateForCandidates({
+      cwd,
+      referenceOutputs: successfulRefs,
+      preset,
+      options: { testGateEnabled, testCommand, execFn },
+      onProgress,
+    })
   }
 
   // 8. Synthesis phase via primary judge or fallback chain
@@ -513,9 +514,7 @@ export async function* streamMoATurn({ targetPreset, userPrompt, messages, callL
     callLlm,
     cwd,
     onProgress: pushUpdate,
-    onStreamDelta: (delta) => {
-      pushUpdate(delta)
-    },
+    onStreamDelta: (delta) => pushUpdate(delta),
     prices,
     historyFilePath,
     liveCanvas,

package/lib/moa-test-gate.js

@@ -0,0 +1,236 @@
+import os from 'node:os'
+import fs from 'node:fs/promises'
+import fsSync from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { assertPathContained } from './file-workspace.js'
+
+/**
+ * Resolves the directory for candidate sandbox.
+ */
+export function resolveCandidateDir(baseDir, candidateIndex) {
+  if (!baseDir || candidateIndex === null || candidateIndex === undefined) return null
+  const targetStr = String(candidateIndex).trim()
+  const sanitizedTarget = targetStr.replace(/[^a-zA-Z0-9_-]/g, '')
+  const sub = /^\d+$/.test(sanitizedTarget) ? `candidate-${sanitizedTarget}` : (sanitizedTarget || 'candidate-1')
+  const moaRoot = path.join(baseDir, '.moa')
+  return assertPathContained(moaRoot, sub)
+}
+
+/**
+ * Executes a test command in a candidate sandbox or ephemeral test staging directory.
+ *
+ * @param {object} params
+ * @param {string} params.cwd - Project root workspace directory
+ * @param {number|string} params.candidateIndex - Index of candidate (1, 2, ...)
+ * @param {string} params.testCommand - Shell command to execute (e.g. "npm test", "node --test")
+ * @param {number} [params.timeoutMs=15000] - Execution timeout in ms
+ * @param {number} [params.maxOutputChars=2000] - Maximum captured output chars
+ * @param {function} [params.execFn] - Optional mock/test runner function
+ * @returns {Promise<object|null>} Test result object or null if skipped
+ */
+export async function runCandidateTestGate({
+  cwd,
+  candidateIndex,
+  testCommand,
+  timeoutMs = 15000,
+  maxOutputChars = 2000,
+  execFn = null,
+}) {
+  if (!cwd || !testCommand || typeof testCommand !== 'string') {
+    return null
+  }
+
+  const trimmedCmd = testCommand.trim()
+  if (!trimmedCmd) return null
+
+  const candidateDir = resolveCandidateDir(cwd, candidateIndex)
+  if (!candidateDir || !fsSync.existsSync(candidateDir)) {
+    return null
+  }
+
+  const startTime = Date.now()
+  let stageDir = null
+  let executionDir = candidateDir
+
+  try {
+    const basePkg = path.join(cwd, 'package.json')
+    const candPkg = path.join(candidateDir, 'package.json')
+    if (fsSync.existsSync(basePkg) && !fsSync.existsSync(candPkg)) {
+      stageDir = await fs.mkdtemp(path.join(os.tmpdir(), `moa-test-stage-${candidateIndex}-`))
+
+      await fs.cp(cwd, stageDir, {
+        recursive: true,
+        filter: (src) => {
+          const rel = path.relative(cwd, src)
+          if (!rel) return true
+          const parts = rel.split(path.sep)
+          if (parts[0] === 'node_modules' || parts[0] === '.git' || parts[0] === '.moa') {
+            return false
+          }
+          return true
+        },
+      })
+
+      await fs.cp(candidateDir, stageDir, { recursive: true })
+      executionDir = stageDir
+    }
+
+    const resolvedCmd = trimmedCmd
+      .replaceAll('{candidateDir}', candidateDir)
+      .replaceAll('{baseDir}', cwd)
+      .replaceAll('{stageDir}', executionDir)
+
+    let exitCode = 0
+    let stdout = ''
+    let stderr = ''
+
+    if (typeof execFn === 'function') {
+      const customRes = await execFn({
+        cwd: executionDir,
+        candidateDir,
+        command: resolvedCmd,
+        timeoutMs,
+      })
+      exitCode = customRes?.exitCode ?? (customRes?.passed ? 0 : 1)
+      stdout = customRes?.stdout || ''
+      stderr = customRes?.stderr || ''
+    } else {
+      const nodePath = path.join(cwd, 'node_modules')
+      const env = {
+        ...process.env,
+        MOA_CANDIDATE_INDEX: String(candidateIndex),
+        MOA_CANDIDATE_DIR: candidateDir,
+        MOA_BASE_DIR: cwd,
+        NODE_PATH: process.env.NODE_PATH ? `${nodePath}:${process.env.NODE_PATH}` : nodePath,
+      }
+
+      const runPromise = new Promise((resolve) => {
+        let child
+        try {
+          child = spawn(resolvedCmd, {
+            cwd: executionDir,
+            shell: true,
+            env,
+            timeout: timeoutMs,
+          })
+        } catch (spawnErr) {
+          resolve({ exitCode: 1, stdout: '', stderr: spawnErr.message || String(spawnErr) })
+          return
+        }
+
+        const outChunks = []
+        const errChunks = []
+
+        child.stdout?.on('data', (d) => outChunks.push(d))
+        child.stderr?.on('data', (d) => errChunks.push(d))
+
+        child.on('error', (err) => {
+          resolve({ exitCode: 1, stdout: Buffer.concat(outChunks).toString('utf8'), stderr: err.message || String(err) })
+        })
+
+        child.on('close', (code, sig) => {
+          const combinedErr = Buffer.concat(errChunks).toString('utf8')
+          const finalErr = sig ? `${combinedErr}\nProcess terminated by signal ${sig}`.trim() : combinedErr
+          resolve({
+            exitCode: code ?? (sig ? 128 : 1),
+            stdout: Buffer.concat(outChunks).toString('utf8'),
+            stderr: finalErr,
+          })
+        })
+      })
+
+      const execResult = await runPromise
+      exitCode = execResult.exitCode
+      stdout = execResult.stdout
+      stderr = execResult.stderr
+    }
+
+    const durationMs = Date.now() - startTime
+    const combinedOutput = [stdout, stderr].filter(Boolean).join('\n').trim()
+    const truncatedOutput = combinedOutput.length > maxOutputChars
+      ? `${combinedOutput.slice(0, maxOutputChars)}\n...[output truncated by Test Gate]`
+      : combinedOutput
+
+    const passed = exitCode === 0
+    const summary = passed
+      ? `PASS (${durationMs}ms)`
+      : `FAIL (code ${exitCode}, ${durationMs}ms)`
+
+    return {
+      candidateIndex,
+      passed,
+      exitCode,
+      durationMs,
+      command: resolvedCmd,
+      output: truncatedOutput,
+      summary,
+    }
+  } catch (err) {
+    const durationMs = Date.now() - startTime
+    return {
+      candidateIndex,
+      passed: false,
+      exitCode: 1,
+      durationMs,
+      command: trimmedCmd,
+      output: `Test Gate Error: ${err.message || String(err)}`,
+      summary: `ERROR (${err.message || 'unknown'})`,
+    }
+  } finally {
+    if (stageDir) {
+      try {
+        await fs.rm(stageDir, { recursive: true, force: true })
+      } catch {}
+    }
+  }
+}
+
+/**
+ * Runs Test Execution Gate across all successful candidates with generated files.
+ */
+export async function executeTestGateForCandidates({
+  cwd,
+  referenceOutputs = [],
+  preset = {},
+  options = {},
+  onProgress = null,
+}) {
+  const isEnabled = Boolean(options.testGateEnabled ?? preset.test_gate_enabled)
+  const testCmd = options.testCommand || preset.test_command
+  if (!isEnabled || !testCmd || !cwd) {
+    return []
+  }
+
+  const timeoutMs = (preset.test_gate_timeout_sec || 15) * 1000
+  const maxOutputChars = preset.test_gate_max_output_chars || 2000
+
+  if (typeof onProgress === 'function') {
+    onProgress('🧪 *Test Execution Gate: Running test suite against candidate sandboxes...*\n')
+  }
+
+  const results = []
+  for (const ref of referenceOutputs) {
+    if (!ref.ok || !ref.files || ref.files.length === 0) continue
+
+    const res = await runCandidateTestGate({
+      cwd,
+      candidateIndex: ref.index,
+      testCommand: testCmd,
+      timeoutMs,
+      maxOutputChars,
+      execFn: options.execFn,
+    })
+
+    if (res) {
+      ref.testResult = res
+      results.push(res)
+      if (typeof onProgress === 'function') {
+        const icon = res.passed ? '✅' : '❌'
+        onProgress(`🧪 *Candidate ${ref.index}: ${icon} ${res.summary}*\n`)
+      }
+    }
+  }
+
+  return results
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-moa",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "Mixture of Agents (MoA) plugin for DeepSeek Harness with /moa slash command",
   "type": "module",
   "main": "lib/index.js",