@goodandready/dsh-moa 0.2.79 → 0.2.80

package/lib/client.js

@@ -249,7 +249,14 @@ window.__ModuleLoader__.load({
       "aggregator.hard_budget_limit_label": "Max Cost Per Turn (USD):",
       "aggregator.hard_budget_policy_label": "Exceed Policy:",
       "aggregator.hard_budget_policy_downgrade": "Auto-Downgrade to Local/Economic",
-      "aggregator.hard_budget_policy_fail": "Fail-Closed (Halt Execution)"
+      "aggregator.hard_budget_policy_fail": "Fail-Closed (Halt Execution)",
+      "aggregator.rebuttal_debate_title": "\u{1F5E3}\uFE0F Multi-Round Rebuttal Debate",
+      "aggregator.rebuttal_debate_desc": "Candidates cross-examine peer solutions and expose flaws before judge arbitration.",
+      "aggregator.rebuttal_rounds_label": "Debate Rounds:",
+      "aggregator.embedding_clustering_title": "\u{1F9ED} Blind Embedding Clustering",
+      "aggregator.embedding_clustering_desc": "Bypass LLM Judge when candidate embeddings converge into a dominant cluster (>= threshold).",
+      "aggregator.embedding_threshold_label": "Consensus Similarity Threshold:",
+      "aggregator.fallback_to_judge_label": "Fallback to Judge if Opinion Splits"
     };
     const zh = {
       title: "\u667A\u80FD\u4F53\u6DF7\u5408 (MoA)",
@@ -489,7 +496,14 @@ window.__ModuleLoader__.load({
       "aggregator.hard_budget_limit_label": "\u5355\u8F6E\u9884\u7B97\u4E0A\u9650 (USD):",
       "aggregator.hard_budget_policy_label": "\u8D85\u989D\u7B56\u7565:",
       "aggregator.hard_budget_policy_downgrade": "\u81EA\u52A8\u964D\u7EA7\u81F3\u672C\u5730/\u7ECF\u6D4E\u6A21\u578B",
-      "aggregator.hard_budget_policy_fail": "\u5B89\u5168\u7194\u65AD (\u505C\u6B62\u6267\u884C)"
+      "aggregator.hard_budget_policy_fail": "\u5B89\u5168\u7194\u65AD (\u505C\u6B62\u6267\u884C)",
+      "aggregator.rebuttal_debate_title": "\u{1F5E3}\uFE0F \u591A\u8F6E\u53CD\u9A73\u8FA9\u8BBA\u673A\u5236",
+      "aggregator.rebuttal_debate_desc": "\u5019\u9009\u6A21\u578B\u5728\u88C1\u5224\u4EF2\u88C1\u524D\u76F8\u4E92\u4EA4\u53C9\u5BA1\u67E5\u5E76\u6307\u51FA\u5BF9\u65B9\u6F0F\u6D1E\u4E0E\u7F3A\u9677\u3002",
+      "aggregator.rebuttal_rounds_label": "\u8FA9\u8BBA\u8F6E\u6570:",
+      "aggregator.embedding_clustering_title": "\u{1F9ED} \u76F2\u5411\u91CF\u5D4C\u5165\u805A\u7C7B",
+      "aggregator.embedding_clustering_desc": "\u5F53\u5019\u9009\u65B9\u6848\u7684\u5411\u91CF\u5D4C\u5165\u9AD8\u5EA6\u6536\u655B\u5E76\u5F62\u6210\u4E3B\u5BFC\u805A\u7C7B\u65F6\uFF0C\u7ED5\u8FC7LLM\u88C1\u5224\u76F4\u63A5\u4EA7\u51FA\u8D28\u5FC3\u5019\u9009\u3002",
+      "aggregator.embedding_threshold_label": "\u5171\u8BC6\u76F8\u4F3C\u5EA6\u9608\u503C:",
+      "aggregator.fallback_to_judge_label": "\u610F\u89C1\u5206\u6B67\u65F6\u56DE\u9000\u81F3\u88C1\u5224"
     };
     function makeT(dict, fallback) {
       return function t(key, vars) {
@@ -2404,7 +2418,6 @@ window.__ModuleLoader__.load({
                   )
                 )
               ),
-              // --- src/client/86-card-aggregator-ext2.js ---
               /* Pre-Judge Local Syntax Gate (#303) & Early Semantic Consensus (#299) */
               React.createElement(
                 "div",
@@ -2442,6 +2455,86 @@ window.__ModuleLoader__.load({
                   t("aggregator.early_consensus_desc") || "Bypass the expensive judge round when reference models converge on equivalent code solutions."
                 )
               ),
+              /* Multi-Round Rebuttal Debate (#298) & Blind Embedding Clustering (#312) */
+              React.createElement(
+                "div",
+                { style: { display: "flex", flexDirection: "column", gap: 6, padding: "8px 12px", background: "var(--dsw-alias-bg-layer-2)", borderRadius: 8, border: "1px solid var(--dsw-alias-border-l2)", marginTop: 8 } },
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.rebuttal_debate_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, rebuttal_debate_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.rebuttal_debate_title") || "\u{1F5E3}\uFE0F Multi-Round Rebuttal Debate"
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)", marginLeft: 22 } },
+                  t("aggregator.rebuttal_debate_desc") || "Candidates cross-examine peer solutions and expose flaws before judge arbitration."
+                ),
+                Boolean(currentPreset.rebuttal_debate_enabled) && React.createElement(
+                  "div",
+                  { style: { display: "flex", alignItems: "center", gap: 8, marginLeft: 22, marginTop: 4 } },
+                  React.createElement("span", { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)" } }, t("aggregator.rebuttal_rounds_label") || "Debate Rounds:"),
+                  React.createElement("input", {
+                    type: "number",
+                    min: 1,
+                    max: 3,
+                    value: currentPreset.rebuttal_rounds || 1,
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, rebuttal_rounds: Math.min(3, Math.max(1, Number(e.target.value) || 1)) })),
+                    style: { width: 50, padding: "2px 6px", fontSize: 12, borderRadius: 4, border: "1px solid var(--dsw-alias-border-l2)", background: "var(--dsw-alias-bg-layer-1)" }
+                  })
+                ),
+                React.createElement(
+                  "label",
+                  { style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer", fontSize: 13, fontWeight: 500, marginTop: 6 } },
+                  React.createElement("input", {
+                    type: "checkbox",
+                    checked: Boolean(currentPreset.embedding_clustering_enabled),
+                    onChange: (e) => updateCurrentPreset((p) => ({ ...p, embedding_clustering_enabled: e.target.checked })),
+                    style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))", cursor: "pointer" }
+                  }),
+                  t("aggregator.embedding_clustering_title") || "\u{1F9ED} Blind Embedding Clustering"
+                ),
+                React.createElement(
+                  "div",
+                  { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)", marginLeft: 22 } },
+                  t("aggregator.embedding_clustering_desc") || "Bypass LLM Judge when candidate embeddings converge into a dominant cluster (>= threshold)."
+                ),
+                Boolean(currentPreset.embedding_clustering_enabled) && React.createElement(
+                  "div",
+                  { style: { display: "flex", flexDirection: "column", gap: 4, marginLeft: 22, marginTop: 4 } },
+                  React.createElement(
+                    "div",
+                    { style: { display: "flex", alignItems: "center", gap: 8 } },
+                    React.createElement("span", { style: { fontSize: 12, color: "var(--dsw-alias-label-secondary)" } }, t("aggregator.embedding_threshold_label") || "Consensus Similarity Threshold:"),
+                    React.createElement("input", {
+                      type: "number",
+                      step: 0.01,
+                      min: 0.5,
+                      max: 0.99,
+                      value: currentPreset.embedding_consensus_threshold ?? 0.88,
+                      onChange: (e) => updateCurrentPreset((p) => ({ ...p, embedding_consensus_threshold: Number(e.target.value) || 0.88 })),
+                      style: { width: 60, padding: "2px 6px", fontSize: 12, borderRadius: 4, border: "1px solid var(--dsw-alias-border-l2)", background: "var(--dsw-alias-bg-layer-1)" }
+                    })
+                  ),
+                  React.createElement(
+                    "label",
+                    { style: { display: "flex", alignItems: "center", gap: 6, cursor: "pointer", fontSize: 12 } },
+                    React.createElement("input", {
+                      type: "checkbox",
+                      checked: currentPreset.fallback_to_judge_on_split !== false,
+                      onChange: (e) => updateCurrentPreset((p) => ({ ...p, fallback_to_judge_on_split: e.target.checked })),
+                      style: { accentColor: "var(--dsw-alias-state-brand-primary, var(--dsw-alias-label-primary))" }
+                    }),
+                    t("aggregator.fallback_to_judge_label") || "Fallback to Judge if Opinion Splits"
+                  )
+                )
+              ),
+              // --- src/client/86-card-aggregator-ext2.js ---
               /* Multi-Turn Context & Diff Pruning (#176) */
               React.createElement(
                 "div",

package/lib/events.js

@@ -22,6 +22,8 @@ export const MOA_EVENTS = {
   CRITIQUE_COMPLETE: 'moa/critique-complete',
   JUDGE_VERDICT: 'moa/judge-verdict',
   CONTEXT_PRUNING: 'moa/context-pruning',
+  DEBATE_ROUND: 'moa/debate-round',
+  EMBEDDING_CLUSTER: 'moa/embedding-cluster',
   CACHE_HIT: 'moa/cache-hit',
   RUN_FINISH: 'moa/run-finish',
 }

package/lib/moa-schema.js

@@ -112,6 +112,12 @@ export const PresetSchema = z.object({
   hard_budget_guard_enabled: z.boolean().default(false),
   hard_budget_limit_usd: z.number().default(0.02),
   hard_budget_policy: z.string().default('auto_downgrade'),
+  rebuttal_debate_enabled: z.boolean().default(false),
+  rebuttal_rounds: z.number().default(1),
+  rebuttal_max_critique_tokens: z.number().default(1024),
+  embedding_clustering_enabled: z.boolean().default(false),
+  embedding_consensus_threshold: z.number().default(0.88),
+  fallback_to_judge_on_split: z.boolean().default(true),
 })
 
 export const Config = z.object({
@@ -170,6 +176,12 @@ export const Config = z.object({
   hard_budget_guard_enabled: z.boolean().default(false).volatile(),
   hard_budget_limit_usd: z.number().default(0.02).volatile(),
   hard_budget_policy: z.string().default('auto_downgrade').volatile(),
+  rebuttal_debate_enabled: z.boolean().default(false).volatile(),
+  rebuttal_rounds: z.number().default(1).volatile(),
+  rebuttal_max_critique_tokens: z.number().default(1024).volatile(),
+  embedding_clustering_enabled: z.boolean().default(false).volatile(),
+  embedding_consensus_threshold: z.number().default(0.88).volatile(),
+  fallback_to_judge_on_split: z.boolean().default(true).volatile(),
   smart_routing_model: ModelSlotSchema.default({ provider: '', model: '' }).volatile(),
   prices: z.dict(PriceRow).default({}).volatile(),
   presets: z.array(PresetSchema).default([

package/lib/pipeline/embedding-clustering.js

@@ -0,0 +1,456 @@
+/**
+ * Blind Embedding Clustering for Zero-LLM Fast Consensus (#312)
+ *
+ * Clusters candidate responses using local high-dimensional n-gram semantic embeddings.
+ * When a dominant cluster exhibits high semantic convergence (cosine similarity >= threshold),
+ * the plugin automatically promotes the cluster centroid candidate without invoking
+ * the expensive LLM Judge, saving significant tokens and latency.
+ */
+
+import { logger } from '../logger.js'
+import { promoteCandidateWorkspace, cleanMoaWorkspaces } from '../workspace/fs.js'
+import { createPromotedPreview } from '../live-canvas.js'
+import { recordMoaRunAsync, candidatesForHistory } from '../history.js'
+import { emitEvent, MOA_EVENTS } from '../events.js'
+import { estimateTokenCost } from '../pricing.js'
+
+const EMBEDDING_DIMENSIONS = 1024
+
+/**
+ * 32-bit FNV-1a hash function for strings
+ * @param {string} str
+ * @returns {number}
+ */
+export function fnv1a32(str) {
+  let hash = 2166136261
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i)
+    hash = Math.imul(hash, 16777619)
+  }
+  return hash >>> 0
+}
+
+/**
+ * Normalizes text/code for embedding extraction.
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeText(text = '') {
+  if (typeof text !== 'string') return ''
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/.*$/gm, '')
+    .replace(/(^|\s)#.*$/gm, '$1')
+    .replace(/\r?\n/g, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .trim()
+    .toLowerCase()
+}
+
+/**
+ * Generates a unit-normalized Float32Array embedding vector from text
+ * using word tokens, code operators, and character n-grams.
+ * @param {string} text
+ * @param {number} [dimensions=1024]
+ * @returns {Float32Array}
+ */
+export function generateEmbedding(text = '', dimensions = EMBEDDING_DIMENSIONS) {
+  const vector = new Float32Array(dimensions)
+  const normalized = normalizeText(text)
+  if (!normalized) return vector
+
+  // 1. Tokens including keywords, identifiers, and syntax operators
+  const tokens = normalized.match(/[a-z0-9_$]+|===|!==|<=|>=|=>|\+\+|--|&&|\|\||\.\.\.|[{}()[\];,+\-*\/%=<>!&|^~?:.]/g) || []
+  const counts = new Map()
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]
+    const h = fnv1a32(t) % dimensions
+    counts.set(h, (counts.get(h) || 0) + 1.2)
+
+    // Token bigrams
+    if (i < tokens.length - 1) {
+      const bigram = `${t}_${tokens[i + 1]}`
+      const h2 = fnv1a32(bigram) % dimensions
+      counts.set(h2, (counts.get(h2) || 0) + 0.8)
+    }
+  }
+
+  // 2. Character 3-grams for morphology and syntax
+  const charSpan = Math.min(normalized.length, 12000)
+  for (let i = 0; i <= charSpan - 3; i++) {
+    const trigram = normalized.slice(i, i + 3)
+    const h3 = fnv1a32(trigram) % dimensions
+    counts.set(h3, (counts.get(h3) || 0) + 0.3)
+  }
+
+  // 3. Sublinear TF weighting: 1 + ln(count)
+  let sumSq = 0
+  for (const [bucket, count] of counts.entries()) {
+    const val = 1 + Math.log(count)
+    vector[bucket] = val
+    sumSq += val * val
+  }
+
+  // 4. L2 Normalization
+  if (sumSq > 0) {
+    const norm = Math.sqrt(sumSq)
+    for (let i = 0; i < dimensions; i++) {
+      vector[i] /= norm
+    }
+  }
+
+  return vector
+}
+
+/**
+ * Computes cosine similarity between two unit-normalized vectors.
+ * Dot product equals cosine similarity for unit vectors.
+ * @param {Float32Array} vecA
+ * @param {Float32Array} vecB
+ * @returns {number}
+ */
+export function computeCosineSimilarity(vecA, vecB) {
+  if (!vecA || !vecB || vecA.length !== vecB.length) return 0.0
+  let dot = 0
+  for (let i = 0; i < vecA.length; i++) {
+    dot += vecA[i] * vecB[i]
+  }
+  const clamped = Math.max(0.0, Math.min(1.0, dot))
+  return Number(clamped.toFixed(4))
+}
+
+/**
+ * Builds pairwise cosine similarity matrix for candidate solutions.
+ * @param {Array<object>} candidates
+ * @returns {{ vectors: Float32Array[], matrix: number[][] }}
+ */
+export function buildSimilarityMatrix(candidates = []) {
+  const n = candidates.length
+  const vectors = candidates.map((c) => generateEmbedding(c.text || ''))
+  const matrix = Array.from({ length: n }, () => new Array(n).fill(0))
+
+  for (let i = 0; i < n; i++) {
+    matrix[i][i] = 1.0
+    for (let j = i + 1; j < n; j++) {
+      const sim = computeCosineSimilarity(vectors[i], vectors[j])
+      matrix[i][j] = sim
+      matrix[j][i] = sim
+    }
+  }
+
+  return { vectors, matrix }
+}
+
+/**
+ * Clusters candidate embeddings and determines if consensus was reached.
+ * @param {Array<object>} candidates
+ * @param {object} [options={}]
+ * @returns {object}
+ */
+export function clusterCandidateEmbeddings(candidates = [], options = {}) {
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.88
+  const fallbackToJudgeOnSplit = options.fallbackToJudgeOnSplit !== false
+  const minMajorityRatio = typeof options.minMajorityRatio === 'number' ? options.minMajorityRatio : 0.60
+
+  if (!Array.isArray(candidates) || candidates.length < 2) {
+    return {
+      consensusReached: false,
+      threshold,
+      clusters: [],
+      dominantCluster: null,
+      centroidCandidate: null,
+      centroidIndex: 0,
+      similarityMatrix: [],
+      fallbackToJudge: fallbackToJudgeOnSplit,
+      reason: 'Insufficient candidates (need at least 2)',
+    }
+  }
+
+  const n = candidates.length
+  const { vectors, matrix } = buildSimilarityMatrix(candidates)
+
+  // Threshold clustering: connect candidates with pairwise similarity >= threshold
+  const clusters = []
+  const assigned = new Set()
+
+  for (let i = 0; i < n; i++) {
+    if (assigned.has(i)) continue
+    const clusterMembers = [i]
+    assigned.add(i)
+
+    // Find all peers reachable with similarity >= threshold
+    for (let j = 0; j < n; j++) {
+      if (assigned.has(j)) continue
+      // Qualifies if similarity to cluster seed or average to cluster >= threshold
+      const simToSeed = matrix[i][j]
+      const avgSim = clusterMembers.reduce((sum, idx) => sum + matrix[j][idx], 0) / clusterMembers.length
+      if (simToSeed >= threshold || avgSim >= threshold) {
+        clusterMembers.push(j)
+        assigned.add(j)
+      }
+    }
+    clusters.push(clusterMembers)
+  }
+
+  // Find dominant cluster (maximum members)
+  clusters.sort((a, b) => b.length - a.length)
+  const largestCluster = clusters[0] || []
+
+  // Compute intra-cluster average similarity
+  let intraClusterSimSum = 0
+  let pairCount = 0
+  for (let a = 0; a < largestCluster.length; a++) {
+    for (let b = a + 1; b < largestCluster.length; b++) {
+      intraClusterSimSum += matrix[largestCluster[a]][largestCluster[b]]
+      pairCount++
+    }
+  }
+  const avgIntraSimilarity = pairCount > 0 ? Number((intraClusterSimSum / pairCount).toFixed(4)) : 1.0
+
+  // Majority condition: cluster has >= required members and high internal similarity
+  const requiredCount = Math.max(2, Math.ceil(n * minMajorityRatio))
+  const consensusReached = largestCluster.length >= requiredCount && (avgIntraSimilarity >= threshold || largestCluster.length === n)
+
+  let centroidIndex = -1
+  let centroidCandidate = null
+
+  if (consensusReached) {
+    // Select centroid: member with highest average similarity to peers in the dominant cluster
+    let bestAvgSim = -1
+    for (const idx of largestCluster) {
+      let simTotal = 0
+      for (const peerIdx of largestCluster) {
+        if (idx !== peerIdx) simTotal += matrix[idx][peerIdx]
+      }
+      const candidateAvg = largestCluster.length > 1 ? simTotal / (largestCluster.length - 1) : 1.0
+
+      // Favor syntactically valid candidates in tie/near-tie situations
+      const hasSyntaxError = candidates[idx].syntaxValidation?.valid === false
+      const adjustedScore = candidateAvg - (hasSyntaxError ? 0.05 : 0)
+
+      if (adjustedScore > bestAvgSim) {
+        bestAvgSim = adjustedScore
+        centroidIndex = idx
+      }
+    }
+
+    centroidCandidate = candidates[centroidIndex] || null
+  }
+
+  const dominantClusterInfo = {
+    size: largestCluster.length,
+    memberIndices: largestCluster.map((i) => candidates[i].index ?? (i + 1)),
+    avgSimilarity: avgIntraSimilarity,
+  }
+
+  return {
+    consensusReached,
+    threshold,
+    dominantCluster: dominantClusterInfo,
+    clusters: clusters.map((c, id) => ({
+      id,
+      size: c.length,
+      indices: c.map((i) => candidates[i].index ?? (i + 1)),
+    })),
+    centroidCandidate,
+    centroidIndex: centroidCandidate ? (centroidCandidate.index ?? (centroidIndex + 1)) : 0,
+    similarityMatrix: matrix,
+    fallbackToJudge: !consensusReached && fallbackToJudgeOnSplit,
+    reason: consensusReached
+      ? `Blind embedding consensus reached (${largestCluster.length}/${n} models converged with avg similarity ${avgIntraSimilarity} >= ${threshold})`
+      : `No dominant embedding cluster converged (largest has ${largestCluster.length}/${n} with avg sim ${avgIntraSimilarity} < ${threshold})`,
+  }
+}
+
+/**
+ * Estimates saved tokens and USD cost from bypassing the judge round.
+ * @param {Array<object>} candidates
+ * @param {string} userPrompt
+ * @param {number} maxTokens
+ * @param {object} prices
+ * @returns {{ skippedTokens: number, skippedCostUsd: number }}
+ */
+export function estimateSkippedJudgeUsage(candidates = [], userPrompt = '', maxTokens = 4096, prices = {}) {
+  const candidateChars = candidates.reduce((acc, c) => acc + (c.text?.length || 0), 0)
+  const promptChars = userPrompt.length
+  const estimatedInputTokens = Math.round((candidateChars + promptChars) / 3.8)
+  const estimatedOutputTokens = Math.min(maxTokens, 1500)
+  const skippedTokens = estimatedInputTokens + estimatedOutputTokens
+
+  const costEst = estimateTokenCost({
+    provider: 'default',
+    model: 'judge',
+    inputTokens: estimatedInputTokens,
+    outputTokens: estimatedOutputTokens,
+    prices,
+  })
+
+  return {
+    skippedTokens,
+    skippedCostUsd: Number((costEst?.costUsd || 0.005).toFixed(5)),
+  }
+}
+
+/**
+ * Evaluates candidate responses for blind embedding clustering and executes fast zero-LLM consensus if reached.
+ * @param {object} params
+ * @returns {Promise<{ ok: boolean, consensusReached: boolean, payload?: object, error?: Error, abort?: boolean }>}
+ */
+export async function stageEmbeddingClustering({
+  successfulRefs = [],
+  referenceOutputs = [],
+  preset = {},
+  userPrompt = '',
+  prices = {},
+  maxTokens = 4096,
+  cwd = process.cwd(),
+  runId = '',
+  signal = null,
+  promoteOpts = {},
+  allowCandidateOverride = false,
+  isRefinement = false,
+  historyFilePath = null,
+  startTime = Date.now(),
+  collectedCtx = null,
+  liveCanvas = null,
+  ctx = null,
+}) {
+  const enabled = Boolean(preset?.embedding_clustering_enabled || preset?.embeddingClusteringEnabled)
+  const threshold = typeof (preset?.embedding_consensus_threshold ?? preset?.embeddingConsensusThreshold) === 'number'
+    ? (preset.embedding_consensus_threshold ?? preset.embeddingConsensusThreshold)
+    : 0.88
+  const fallbackToJudgeOnSplit = (preset?.fallback_to_judge_on_split ?? preset?.fallbackToJudgeOnSplit) !== false
+
+  if (!enabled || successfulRefs.length < 2) {
+    return { ok: true, consensusReached: false }
+  }
+
+  const result = clusterCandidateEmbeddings(successfulRefs, {
+    threshold,
+    fallbackToJudgeOnSplit,
+  })
+
+  emitEvent(ctx, MOA_EVENTS.EMBEDDING_CLUSTER, {
+    runId,
+    consensusReached: result.consensusReached,
+    threshold,
+    dominantCluster: result.dominantCluster,
+    clusters: result.clusters,
+    centroidIndex: result.centroidIndex,
+    fallbackToJudge: result.fallbackToJudge,
+    reason: result.reason,
+  })
+
+  if (!result.consensusReached || !result.centroidCandidate) {
+    logger.info(`[dsh-moa] Embedding clustering: ${result.reason}. Proceeding to arbitration.`)
+    return { ok: true, consensusReached: false, fallbackToJudge: result.fallbackToJudge }
+  }
+
+  const winner = result.centroidCandidate
+  logger.info(`[dsh-moa] Blind embedding fast consensus reached! Winner centroid: candidate ${result.centroidIndex}`)
+
+  // Promote centroid candidate files to project workspace
+  let promotedFiles = []
+  let promoteErr = null
+  if (winner.files?.length > 0) {
+    try {
+      promotedFiles = await promoteCandidateWorkspace(cwd, winner.index, {
+        ...promoteOpts,
+        runId,
+        keepMoa: allowCandidateOverride,
+      })
+    } catch (err) {
+      promoteErr = err
+    }
+  } else if (!allowCandidateOverride) {
+    await cleanMoaWorkspaces(cwd, { runId })
+  }
+
+  if (promoteErr) {
+    if (!allowCandidateOverride) await cleanMoaWorkspaces(cwd, { runId })
+    if (signal?.aborted || promoteErr?.message?.includes('aborted')) {
+      return { ok: false, consensusReached: true, abort: true, error: new Error('Turn aborted') }
+    }
+  }
+
+  const skippedUsage = estimateSkippedJudgeUsage(successfulRefs, userPrompt, maxTokens, prices)
+  const livePreview = await createPromotedPreview(liveCanvas, cwd, promotedFiles, referenceOutputs, {
+    winningIndex: winner.index,
+  })
+
+  const totalTokens = referenceOutputs.reduce((acc, r) => acc + (r.usage?.totalTokens || 0), 0)
+  const totalCostUsd = Number(referenceOutputs.reduce((acc, r) => acc + (r.costUsd || 0), 0).toFixed(5))
+  const durationMs = Date.now() - startTime
+
+  try {
+    await recordMoaRunAsync({
+      id: runId,
+      cwd,
+      prompt: userPrompt,
+      preset: preset?.name || 'default',
+      isRefinement,
+      isEarlyConsensus: true,
+      isEmbeddingConsensus: true,
+      candidates: candidatesForHistory(referenceOutputs),
+      aggregator: 'Blind Embedding Consensus (Bypassed)',
+      winnerIndex: winner.index,
+      winnerModel: winner.label,
+      promotedFiles,
+      totalTokens,
+      totalCostUsd,
+      skippedJudgeTokens: skippedUsage.skippedTokens,
+      durationMs,
+    }, historyFilePath || undefined)
+  } catch (histErr) {
+    logger.warn('[dsh-moa] Failed to record embedding consensus in history:', histErr?.message || histErr)
+  }
+
+  emitEvent(ctx, MOA_EVENTS.RUN_FINISH, {
+    runId,
+    durationMs,
+    totalTokens,
+    totalCostUsd,
+    promotedFiles,
+    winnerIndex: winner.index,
+    isEarlyConsensus: true,
+    isEmbeddingConsensus: true,
+  })
+
+  return {
+    ok: true,
+    consensusReached: true,
+    payload: {
+      kind: 'synthesis',
+      content: winner.text,
+      aggregator: 'Blind Embedding Consensus (Bypassed)',
+      references: referenceOutputs,
+      presetName: preset?.name || 'default',
+      isRefinement,
+      isEarlyConsensus: true,
+      isEmbeddingConsensus: true,
+      winningIndex: winner.index,
+      winnerModel: winner.label,
+      promotedFiles,
+      runId,
+      embeddingInfo: {
+        dominantCluster: result.dominantCluster,
+        threshold,
+        clusters: result.clusters,
+        centroidIndex: result.centroidIndex,
+      },
+      ...(livePreview ? { liveCanvas: livePreview } : {}),
+      usage: {
+        totalTokens,
+        totalCostUsd,
+        skippedJudgeTokens: skippedUsage.skippedTokens,
+        skippedJudgeCostUsd: skippedUsage.skippedCostUsd,
+        candidates: referenceOutputs.map((r) => ({ label: r.label, usage: r.usage, costUsd: r.costUsd })),
+        aggregator: { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0 },
+      },
+      skippedFiles: collectedCtx?.skippedFiles || 0,
+      skippedList: collectedCtx?.skippedList || [],
+      durationMs,
+    },
+  }
+}

package/lib/pipeline/rebuttal-debate.js

@@ -0,0 +1,335 @@
+/**
+ * Multi-Round Rebuttal Debate between Candidates (#298)
+ *
+ * Implements multi-round cross-examination and rebuttal discussion between candidate models
+ * before final arbitration by the Judge. Candidates anonymize and analyze peer solutions,
+ * identify flaws, security edge-cases, and hallucinations, and refine their own answers.
+ * The structured debate protocol is then passed to the Judge for weighted arbitration.
+ */
+
+import { logger } from '../logger.js'
+import { callWithTransientRetry } from '../moa-candidates.js'
+import { extractFileBlocks, writeCandidateWorkspace } from '../workspace/fs.js'
+import { verifyFileSyntax } from '../workspace/diff.js'
+import { estimateTokenCost } from '../pricing.js'
+import { emitEvent, MOA_EVENTS } from '../events.js'
+
+/**
+ * Builds the rebuttal prompt for a candidate in a given debate round.
+ * @param {object} params
+ * @returns {string}
+ */
+export function buildRebuttalPrompt({
+  userPrompt,
+  candidateText,
+  opponentAnswers,
+  roundNumber = 1,
+  totalRounds = 1,
+  isBlind = true,
+}) {
+  const opponentsFormatted = opponentAnswers
+    .map((op, idx) => {
+      const label = op.label || `Candidate ${idx + 1}`
+      const persona = op.role_persona ? ` [Persona: ${op.role_persona}]` : ''
+      return `### ⚔️ Peer Solution [${label}]${persona}:\n${op.text}`
+    })
+    .join('\n\n')
+
+  return `You are an expert software engineer participating in a rigorous Multi-Agent Consilium Rebuttal Debate (Round ${roundNumber} of ${totalRounds}).
+Your objective is to stress-test peer solutions, expose bugs, logical vulnerabilities, and hallucinations, and defend and refine your own solution.
+
+=== ORIGINAL USER REQUEST ===
+${userPrompt}
+
+=== YOUR PREVIOUS PROPOSAL ===
+${candidateText}
+
+=== ALTERNATIVE PEER SOLUTIONS ===
+${opponentsFormatted}
+
+=== REBUTTAL DEBATE INSTRUCTIONS ===
+Analyze the peer solutions with uncompromising technical rigor.
+Structure your response EXACTLY into these three labeled sections:
+
+### CRITIQUE OF PEERS
+For each peer candidate, cite concrete issues:
+- Identify logic bugs, off-by-one errors, uncaught exceptions, or security holes.
+- Highlight missing edge cases or unhandled failure states.
+- Point out inaccurate assumptions or hallucinations.
+
+### REBUTTAL & DEFENSE
+- Address the potential weaknesses or tradeoffs in your own approach.
+- Explain why your architectural or algorithmic choices are superior or more maintainable.
+
+### REFINED SOLUTION
+- Provide your complete, improved, and final solution incorporating valid insights from the debate.
+- Output complete code without placeholders or omissions.`
+}
+
+/**
+ * Parses structured rebuttal debate output from a model response.
+ * @param {string} rawText
+ * @returns {{ critiqueText: string, defenseText: string, refinedText: string }}
+ */
+export function parseRebuttalResponse(rawText = '') {
+  if (typeof rawText !== 'string') {
+    return { critiqueText: '', defenseText: '', refinedText: '' }
+  }
+
+  let critiqueText = ''
+  let defenseText = ''
+  let refinedText = rawText
+
+  const critiqueMatch = rawText.match(/### CRITIQUE OF PEERS\s*([\s\S]*?)(?=### REBUTTAL & DEFENSE|### REFINED SOLUTION|$)/i)
+  if (critiqueMatch) {
+    critiqueText = critiqueMatch[1].trim()
+  }
+
+  const defenseMatch = rawText.match(/### REBUTTAL & DEFENSE\s*([\s\S]*?)(?=### REFINED SOLUTION|$)/i)
+  if (defenseMatch) {
+    defenseText = defenseMatch[1].trim()
+  }
+
+  const refinedMatch = rawText.match(/### REFINED SOLUTION\s*([\s\S]*)$/i)
+  if (refinedMatch && refinedMatch[1].trim().length > 50) {
+    refinedText = refinedMatch[1].trim()
+  }
+
+  return {
+    critiqueText,
+    defenseText,
+    refinedText,
+  }
+}
+
+/**
+ * Executes a single round of rebuttal debate across all active candidates.
+ * @param {object} params
+ * @returns {Promise<{ round: number, critiques: Array<object>, updatedCandidates: Array<object> }>}
+ */
+export async function executeDebateRound({
+  candidates = [],
+  userPrompt = '',
+  roundNumber = 1,
+  totalRounds = 1,
+  isBlindEvaluation = true,
+  callLlm,
+  refTemp = 0.5,
+  maxTokens = 4096,
+  refTimeoutSec = 60,
+  candidateRetries = 2,
+  prices = {},
+  signal = null,
+  onProgress = null,
+  cwd = process.cwd(),
+  runId = '',
+  ctx = null,
+}) {
+  if (typeof onProgress === 'function') {
+    onProgress(`🗣️ *Rebuttal Debate Round ${roundNumber}/${totalRounds}: Candidates cross-examining peer solutions in parallel...*\n`)
+  }
+
+  const roundCritiques = []
+
+  const debatePromises = candidates.map(async (cand) => {
+    const opponents = candidates
+      .filter((c) => c.index !== cand.index)
+      .map((c) => ({
+        index: c.index,
+        label: isBlindEvaluation ? `Candidate ${c.index}` : c.label,
+        role_persona: c.role_persona || c.slot?.role_persona,
+        text: c.text,
+      }))
+
+    const rebuttalPrompt = buildRebuttalPrompt({
+      userPrompt,
+      candidateText: cand.text,
+      opponentAnswers: opponents,
+      roundNumber,
+      totalRounds,
+      isBlind: isBlindEvaluation,
+    })
+
+    const slot = cand.slot || { provider: cand.provider, model: cand.model }
+
+    try {
+      const res = await callWithTransientRetry(
+        callLlm,
+        {
+          provider: slot.provider,
+          model: slot.model,
+          messages: [{ role: 'user', content: rebuttalPrompt }],
+          temperature: refTemp,
+          maxTokens,
+          timeoutMs: refTimeoutSec * 1000,
+          signal,
+          onProgress,
+        },
+        candidateRetries
+      )
+
+      const parsed = parseRebuttalResponse(res.text)
+      const costEst = estimateTokenCost({
+        provider: slot.provider,
+        model: slot.model,
+        inputTokens: res.usage?.inputTokens || 0,
+        outputTokens: res.usage?.outputTokens || 0,
+        cacheHitTokens: res.usage?.cacheHitTokens || 0,
+        prices,
+      })
+
+      const newFiles = extractFileBlocks(parsed.refinedText)
+      if (newFiles.length > 0) {
+        await writeCandidateWorkspace(cwd, cand.index, newFiles, { runId })
+      }
+
+      const syntaxValidation = verifyFileSyntax(newFiles)
+
+      const critiqueRecord = {
+        candidateIndex: cand.index,
+        candidateLabel: isBlindEvaluation ? `Candidate ${cand.index}` : cand.label,
+        critique: parsed.critiqueText,
+        defense: parsed.defenseText,
+      }
+      roundCritiques.push(critiqueRecord)
+
+      return {
+        ...cand,
+        text: parsed.refinedText,
+        files: newFiles.length > 0 ? newFiles : cand.files,
+        syntaxValidation: syntaxValidation.valid ? syntaxValidation : cand.syntaxValidation,
+        usage: {
+          inputTokens: (cand.usage?.inputTokens || 0) + (res.usage?.inputTokens || 0),
+          outputTokens: (cand.usage?.outputTokens || 0) + (res.usage?.outputTokens || 0),
+          totalTokens: (cand.usage?.totalTokens || 0) + (res.usage?.totalTokens || 0),
+        },
+        costUsd: Number(((cand.costUsd || 0) + (costEst?.costUsd || 0)).toFixed(5)),
+        lastDebateCritique: parsed.critiqueText,
+        lastDebateDefense: parsed.defenseText,
+      }
+    } catch (err) {
+      logger.warn(`[dsh-moa] Candidate ${cand.index} rebuttal debate round ${roundNumber} failed:`, err?.message || err)
+      return cand
+    }
+  })
+
+  const updatedCandidates = await Promise.all(debatePromises)
+
+  emitEvent(ctx, MOA_EVENTS.DEBATE_ROUND, {
+    runId,
+    roundNumber,
+    totalRounds,
+    critiquesCount: roundCritiques.length,
+    activeCandidates: updatedCandidates.length,
+  })
+
+  return {
+    round: roundNumber,
+    critiques: roundCritiques,
+    updatedCandidates,
+  }
+}
+
+/**
+ * Formats accumulated debate protocol into a clean markdown directive for the Judge.
+ * @param {Array<object>} debateRounds
+ * @returns {string}
+ */
+export function formatDebateDirective(debateRounds = []) {
+  if (!Array.isArray(debateRounds) || debateRounds.length === 0) return ''
+
+  const sections = []
+  sections.push('=== ⚔️ MULTI-ROUND REBUTTAL DEBATE PROTOCOL ===')
+  sections.push('The candidate models engaged in peer cross-examination prior to arbitration.')
+  sections.push('CRITICAL JUDGE DIRECTIVE: Heavily weight valid vulnerabilities or bugs identified by peers.')
+
+  for (const r of debateRounds) {
+    sections.push(`\n--- Debate Round ${r.round} ---`)
+    for (const c of r.critiques || []) {
+      if (c.critique) {
+        sections.push(`[${c.candidateLabel}] Critiques of peers:\n${c.critique}`)
+      }
+      if (c.defense) {
+        sections.push(`[${c.candidateLabel}] Defense & Justification:\n${c.defense}`)
+      }
+    }
+  }
+
+  sections.push('\n==============================================')
+  return sections.join('\n')
+}
+
+/**
+ * Orchestrates multi-round rebuttal debate phase (#298).
+ * @param {object} params
+ * @returns {Promise<{ ok: boolean, updatedCandidates: Array<object>, debateDirective: string, totalCritiques: number, rounds: Array<object> }>}
+ */
+export async function runRebuttalDebatePhase({
+  candidates = [],
+  userPrompt = '',
+  preset = {},
+  prices = {},
+  maxTokens = 4096,
+  isBlindEvaluation = true,
+  callLlm,
+  signal = null,
+  onProgress = null,
+  cwd = process.cwd(),
+  runId = '',
+  ctx = null,
+}) {
+  const enabled = Boolean(preset?.rebuttal_debate_enabled || preset?.rebuttalDebateEnabled)
+  if (!enabled || candidates.length < 2) {
+    return {
+      ok: true,
+      updatedCandidates: candidates,
+      debateDirective: '',
+      totalCritiques: 0,
+      rounds: [],
+    }
+  }
+
+  const configuredRounds = preset?.rebuttal_rounds ?? preset?.rebuttalRounds ?? 1
+  const totalRounds = Math.min(3, Math.max(1, Number(configuredRounds) || 1))
+
+  let currentCandidates = [...candidates]
+  const debateRounds = []
+
+  for (let r = 1; r <= totalRounds; r++) {
+    if (signal?.aborted) {
+      break
+    }
+
+    const roundResult = await executeDebateRound({
+      candidates: currentCandidates,
+      userPrompt,
+      roundNumber: r,
+      totalRounds,
+      isBlindEvaluation,
+      callLlm,
+      refTemp: preset?.reference_temperature ?? 0.5,
+      maxTokens,
+      refTimeoutSec: preset?.reference_timeout_sec ?? 60,
+      prices,
+      signal,
+      onProgress,
+      cwd,
+      runId,
+      ctx,
+    })
+
+    debateRounds.push(roundResult)
+    currentCandidates = roundResult.updatedCandidates
+  }
+
+  const totalCritiques = debateRounds.reduce((acc, r) => acc + (r.critiques?.length || 0), 0)
+  const debateDirective = formatDebateDirective(debateRounds)
+
+  return {
+    ok: true,
+    updatedCandidates: currentCandidates,
+    debateDirective,
+    totalCritiques,
+    rounds: debateRounds,
+  }
+}

package/lib/pipeline/runner.js

@@ -25,6 +25,8 @@ import { runSecurityAuditGate } from './security-fuzzer.js'
 import { runCoveVerificationGate } from './cove-verifier.js'
 import { runProfilerGate } from './runtime-profiler.js'
 import { runMutationGate } from './mutation-tester.js'
+import { stageEmbeddingClustering } from './embedding-clustering.js'
+import { runRebuttalDebatePhase } from './rebuttal-debate.js'
 import { emitEvent, MOA_EVENTS } from '../events.js'
 
 export async function runMoAPipeline({
@@ -119,7 +121,7 @@ export async function runMoAPipeline({
     })
     return candStage.failurePayload
   }
-  const { referenceOutputs, successfulRefs, adversarialTddResult } = candStage
+  let { referenceOutputs, successfulRefs, adversarialTddResult } = candStage
 
   for (const ref of referenceOutputs) {
     emitEvent(ctx, MOA_EVENTS.CANDIDATE_COMPLETE, {
@@ -202,6 +204,32 @@ export async function runMoAPipeline({
     }
   }
 
+  // Pre-Judge Stage 4.6: Blind Embedding Clustering for Zero-LLM Fast Consensus (#312)
+  if ((preset?.embedding_clustering_enabled || preset?.embeddingClusteringEnabled) && successfulRefs.length > 1) {
+    const embedRes = await stageEmbeddingClustering({
+      successfulRefs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      referenceOutputs,
+      preset,
+      userPrompt,
+      prices,
+      maxTokens: ctxStage.maxTokens,
+      cwd,
+      runId,
+      signal,
+      promoteOpts,
+      allowCandidateOverride: ctxStage.allowCandidateOverride,
+      isRefinement: ctxStage.isRefinement,
+      historyFilePath,
+      startTime,
+      collectedCtx: ctxStage.collectedCtx,
+      liveCanvas,
+      ctx,
+    })
+    if (embedRes.consensusReached) {
+      return embedRes.payload
+    }
+  }
+
   if (signal?.aborted) {
     await cleanMoaWorkspaces(cwd, { runId })
     return { error: new Error('Turn aborted') }
@@ -228,6 +256,35 @@ export async function runMoAPipeline({
     })
   }
 
+  // Stage 5.2: Multi-Round Rebuttal Debate between Candidates (#298)
+  let debateDirective = null
+  if ((preset?.rebuttal_debate_enabled || preset?.rebuttalDebateEnabled) && successfulRefs.length > 1) {
+    const debateRes = await runRebuttalDebatePhase({
+      candidates: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      userPrompt,
+      preset,
+      prices,
+      maxTokens: ctxStage.maxTokens,
+      isBlindEvaluation: ctxStage.isBlindEvaluation,
+      callLlm,
+      signal,
+      onProgress,
+      cwd,
+      runId,
+      ctx,
+    })
+    if (debateRes.ok && debateRes.debateDirective) {
+      debateDirective = debateRes.debateDirective
+      if (debateRes.updatedCandidates?.length > 0) {
+        successfulRefs = debateRes.updatedCandidates
+        referenceOutputs = referenceOutputs.map((r) => {
+          const matching = successfulRefs.find((c) => c.index === r.index || c.label === r.label)
+          return matching ? { ...r, text: matching.text } : r
+        })
+      }
+    }
+  }
+
   if (signal?.aborted) {
     await cleanMoaWorkspaces(cwd, { runId })
     return { error: new Error('Turn aborted') }
@@ -372,7 +429,7 @@ export async function runMoAPipeline({
     preset: effectivePreset,
     successfulRefs: candidatesForJudge,
     referenceOutputs: sanitizedReferenceOutputs, primaryJudge: effectivePrimaryJudge,
-    userPrompt, judgeCriteria: [ctxStage.judgeCriteria, coveDirective, securityDirective, profilerDirective, mutationDirective, privacyDirective].filter(Boolean).join('\n\n'), prices, maxTokens: ctxStage.maxTokens,
+    userPrompt, judgeCriteria: [ctxStage.judgeCriteria, debateDirective, coveDirective, securityDirective, profilerDirective, mutationDirective, privacyDirective].filter(Boolean).join('\n\n'), prices, maxTokens: ctxStage.maxTokens,
     callLlm, signal, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     isFastMode: ctxStage.isFastMode, collectedCtx: ctxStage.collectedCtx, startTime,
   })
@@ -430,7 +487,7 @@ export async function runMoAPipeline({
     }
   }
 
-  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, coveDirective, securityDirective, profilerDirective, mutationDirective, privacyDirective, pruningDirective, ctxStage.stackAwareDirective, ctxStage.developerPreferencesDirective].filter(Boolean).join("\n\n") || null
+  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, debateDirective, coveDirective, securityDirective, profilerDirective, mutationDirective, privacyDirective, pruningDirective, ctxStage.stackAwareDirective, ctxStage.developerPreferencesDirective].filter(Boolean).join("\n\n") || null
 
   // Stage 7: Synthesis Phase
   const synthRes = await stageSynthesis({

package/package.json

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