@goodandready/dsh-moa 0.2.61 → 0.2.62

package/lib/pipeline/candidates.js

@@ -0,0 +1,99 @@
+import { runReferencesParallel } from '../moa-candidates.js'
+import { extractFileBlocks, writeCandidateWorkspace, cleanMoaWorkspaces } from '../workspace/fs.js'
+import { verifyFileSyntax } from '../workspace/diff.js'
+import { executeTestGateForCandidates } from '../moa-test-gate.js'
+import { slotLabel } from '../moa-prompts.js'
+
+export async function stageCandidateRound1({
+  effectiveReferences,
+  enrichedMessages,
+  candidateSystemPrompt,
+  refTemp,
+  preset,
+  maxTokens,
+  prices,
+  refTimeoutSec,
+  isQuorumEnabled,
+  gracePeriodSec,
+  candidateRetries,
+  signal,
+  callLlm,
+  onProgress,
+  cwd,
+  runId,
+  startTime,
+  primaryJudge,
+  isRefinement,
+  isFastMode,
+  collectedCtx,
+  testGateEnabled,
+  testCommand,
+  execFn,
+}) {
+  const referenceOutputs = await runReferencesParallel(
+    effectiveReferences,
+    enrichedMessages,
+    {
+      systemPrompt: candidateSystemPrompt,
+      temperature: refTemp,
+      temperature_gradient_enabled: Boolean(preset?.temperature_gradient_enabled),
+      local_fallback_enabled: Boolean(preset?.local_fallback_enabled),
+      local_fallback_models: preset?.local_fallback_models || [],
+      maxTokens,
+      prices,
+      timeoutSec: refTimeoutSec,
+      quorumEnabled: isQuorumEnabled,
+      gracePeriodSec,
+      maxRetries: candidateRetries,
+      signal,
+    },
+    callLlm,
+    onProgress
+  )
+
+  if (signal?.aborted) {
+    await cleanMoaWorkspaces(cwd, { runId })
+    return { ok: false, abort: true, error: new Error('Turn aborted') }
+  }
+
+  const successfulRefs = referenceOutputs.filter((r) => r.ok)
+  if (successfulRefs.length === 0) {
+    const reasons = referenceOutputs.map((r) => `${r.label}: ${r.error || 'unknown error'}`).join('; ')
+    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 failurePayload = {
+      kind: 'failure', content: `⚠️ All advisor models (${referenceOutputs.length}) failed: ${reasons}`,
+      aggregator: slotLabel(primaryJudge), references: referenceOutputs, presetName: preset?.name || 'default',
+      isRefinement, isFastMode, winningIndex: 0, winnerModel: 'none', promotedFiles: [],
+      usage: { totalTokens, totalCostUsd, 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: Date.now() - startTime,
+    }
+    return { ok: false, failurePayload }
+  }
+
+  for (let i = 0; i < referenceOutputs.length; i++) {
+    const ref = referenceOutputs[i]
+    if (!ref.ok) continue
+    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, { runId })
+    }
+  }
+
+  if (signal?.aborted) {
+    await cleanMoaWorkspaces(cwd, { runId })
+    return { ok: false, abort: true, error: new Error('Turn aborted') }
+  }
+
+  await executeTestGateForCandidates({
+    cwd,
+    referenceOutputs,
+    preset,
+    options: { testGateEnabled, testCommand, execFn, runId },
+    onProgress,
+  })
+
+  return { ok: true, referenceOutputs, successfulRefs }
+}

package/lib/pipeline/context.js

@@ -0,0 +1,107 @@
+import { collectProjectContext, formatProjectContext, isRefinementTask } from '../workspace/scanner.js'
+import { applyBudgetGuardrails, createBudgetAbortPayload } from '../moa-budget.js'
+import { extractPriorTurnBaseline, pruneMultiTurnMessages } from '../moa-context.js'
+import { REFERENCE_SYSTEM_PROMPT } from '../moa-candidates.js'
+import { isBroadPromptRequiringQuestions } from '../moa-prompts.js'
+
+export async function stageProjectContext({
+  userPrompt,
+  messages = [],
+  preset,
+  cwd,
+  prices,
+  maxTokens,
+  startTime,
+  onProgress,
+}) {
+  const referenceModels = Array.isArray(preset?.reference_models) && preset.reference_models.length > 0
+    ? preset.reference_models : [{ provider: '', model: '' }]
+  const primaryJudge = preset?.aggregator?.provider && preset?.aggregator?.model
+    ? preset.aggregator : { provider: '', model: '' }
+  const fallbackJudges = Array.isArray(preset?.aggregator_fallbacks) ? preset.aggregator_fallbacks : []
+  const judgesChain = [primaryJudge, ...fallbackJudges]
+  const refTemp = typeof preset?.reference_temperature === 'number' ? preset.reference_temperature : 0.6
+  const aggTemp = typeof preset?.aggregator_temperature === 'number' ? preset.aggregator_temperature : 0.4
+  const judgeCriteria = preset?.judge_criteria || ''
+  let 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 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 collectedCtx = await collectProjectContext(cwd, 16000)
+  const isRefinement = Boolean(collectedCtx?.files?.length > 0 && isRefinementTask(userPrompt, collectedCtx.files))
+  let projectContext = ''
+  if (collectedCtx?.skippedFiles > 0 && typeof onProgress === 'function') {
+    const preview = collectedCtx.skippedList.slice(0, 3).join(', ')
+    const more = collectedCtx.skippedList.length > 3 ? ` (+${collectedCtx.skippedList.length - 3})` : ''
+    onProgress(`⚠️ *Workspace scan note: ${collectedCtx.skippedFiles} file(s) skipped (${preview}${more})*\n`)
+  }
+  if (isRefinement) {
+    if (typeof onProgress === 'function') {
+      onProgress('🔍 *Reading project files for refinement context...*\n')
+    }
+    projectContext = formatProjectContext(collectedCtx.files, {
+      skippedFiles: collectedCtx.skippedFiles,
+      skippedList: collectedCtx.skippedList,
+    })
+  }
+
+  const budgetCheck = applyBudgetGuardrails({
+    references: referenceModels,
+    enabled: preset?.budget_guard_enabled,
+    maxBudgetUsd: preset?.max_budget_usd,
+    action: preset?.budget_action || 'trim',
+    prices,
+    promptLength: (userPrompt?.length || 1000) + (judgeCriteria?.length || 0) + (projectContext ? projectContext.length : 0),
+    judgeCriteria,
+    projectContext,
+    messages,
+    maxTokens,
+    peerCritiqueEnabled: isPeerCritiqueEnabled,
+    aggregator: primaryJudge,
+    judgeModels: preset?.multi_judge_enabled ? preset?.judge_models : [],
+  })
+
+  if (!budgetCheck.allowed) {
+    const abortPayload = createBudgetAbortPayload({
+      reason: budgetCheck.reason, primaryJudge, referenceOutputs: [], currentSpentUsd: 0,
+      preset, isRefinement, isFastMode, collectedCtx, startTime,
+    })
+    return { ok: false, abortPayload }
+  }
+
+  const effectiveReferences = budgetCheck.references
+  if (effectiveReferences.length === 1 && !preset?.curator_synthesis) {
+    isFastMode = true
+  }
+  if (budgetCheck.action === 'trim' && typeof onProgress === 'function') {
+    onProgress(`✂️ *${budgetCheck.reason}*\n`)
+  }
+
+  const priorTurnBaseline = preset?.multi_turn_enabled !== false ? extractPriorTurnBaseline(messages) : null
+  const prunedHistory = preset?.multi_turn_enabled !== false ? pruneMultiTurnMessages(messages) : messages
+  const candidateSystemPrompt = projectContext
+    ? `${REFERENCE_SYSTEM_PROMPT}\n\n### Current Project Files & Context:\n${projectContext}`
+    : REFERENCE_SYSTEM_PROMPT
+  const askClarifyingQuestions = preset?.ask_clarifying_questions !== false
+  const needsQuestions = askClarifyingQuestions && isBroadPromptRequiringQuestions(userPrompt, messages)
+  const enrichedMessages = [...prunedHistory, { role: 'user', content: userPrompt }]
+
+  return {
+    ok: true,
+    referenceModels, primaryJudge, fallbackJudges, judgesChain,
+    refTemp, aggTemp, maxTokens, judgeCriteria, isFastMode, isCuratorSynthesis,
+    isStreamAggregator, isQuorumEnabled, gracePeriodSec, candidateRetries,
+    refTimeoutSec, aggTimeoutSec, isBlindEvaluation, isPeerCritiqueEnabled,
+    allowCandidateOverride, collectedCtx, isRefinement, projectContext,
+    effectiveReferences, priorTurnBaseline, candidateSystemPrompt,
+    needsQuestions, enrichedMessages,
+  }
+}

package/lib/pipeline/fast-mode.js

@@ -0,0 +1,100 @@
+import { logger } from '../logger.js'
+import { promoteCandidateWorkspace, cleanMoaWorkspaces } from '../workspace/fs.js'
+import { createPromotedPreview } from '../live-canvas.js'
+import { recordMoaRunAsync, candidatesForHistory } from '../history.js'
+
+export async function stageFastMode({
+  successfulRefs,
+  referenceOutputs,
+  allowCandidateOverride,
+  promoteOpts,
+  cwd,
+  runId,
+  signal,
+  userPrompt,
+  preset,
+  isRefinement,
+  historyFilePath,
+  startTime,
+  collectedCtx,
+  liveCanvas,
+}) {
+  if (signal?.aborted) {
+    await cleanMoaWorkspaces(cwd, { runId })
+    return { ok: false, abort: true, error: new Error('Turn aborted') }
+  }
+  const single = successfulRefs[0]
+  let promotedFiles = [], promoteErr = null
+  if (single.files?.length > 0) {
+    try {
+      promotedFiles = await promoteCandidateWorkspace(cwd, single.index, { ...promoteOpts, runId, keepMoa: allowCandidateOverride })
+    } catch (e) { promoteErr = e }
+  } else if (!allowCandidateOverride) {
+    await cleanMoaWorkspaces(cwd, { runId })
+  }
+  if (promoteErr) {
+    if (!allowCandidateOverride) await cleanMoaWorkspaces(cwd, { runId })
+    if (signal?.aborted || promoteErr?.message?.includes('aborted') || promoteErr?.name === 'AbortError' || promoteErr?.message === 'Turn aborted') {
+      return { ok: false, abort: true, error: new Error('Turn aborted') }
+    }
+    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, isFastMode: true, candidates: candidatesForHistory(referenceOutputs),
+        aggregator: null, winnerIndex: 0, winnerModel: 'none',
+        promotedFiles: [], totalTokens, totalCostUsd, durationMs,
+        error: promoteErr?.message || String(promoteErr),
+      }, historyFilePath || undefined)
+    } catch (histErr) {
+      logger.warn('[dsh-moa] Failed to record fast synthesis failure in history:', histErr?.message || histErr)
+    }
+    return {
+      ok: false,
+      payload: {
+        kind: 'failure', error: promoteErr,
+        content: '🛑 Checkpoint or Promotion Failure: ' + (promoteErr?.message || String(promoteErr)),
+        aggregator: 'Fast Mode (Direct)', references: referenceOutputs,
+        presetName: preset?.name || 'default', isRefinement, isFastMode: true,
+        winningIndex: 0, winnerModel: 'none', promotedFiles: [], runId,
+        usage: {
+          totalTokens, totalCostUsd,
+          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,
+      }
+    }
+  }
+
+  const livePreview = await createPromotedPreview(liveCanvas, cwd, promotedFiles, referenceOutputs, { winningIndex: single.index })
+  const totalTokens = single.usage?.totalTokens || 0
+  const totalCostUsd = Number((single.costUsd || 0).toFixed(5))
+  const durationMs = Date.now() - startTime
+
+  try {
+    await recordMoaRunAsync({
+      id: runId, cwd, prompt: userPrompt, preset: preset?.name || 'default',
+      isRefinement, isFastMode: true, candidates: candidatesForHistory(referenceOutputs),
+      aggregator: null, winnerIndex: single.index, winnerModel: single.label,
+      promotedFiles, totalTokens, totalCostUsd, durationMs,
+    }, historyFilePath || undefined)
+  } catch (histErr) {
+    logger.warn('[dsh-moa] Failed to record fast synthesis run in history:', histErr?.message || histErr)
+  }
+
+  return {
+    ok: true,
+    payload: {
+      kind: 'synthesis', content: single.text, aggregator: 'Fast Mode (Direct)', references: referenceOutputs,
+      presetName: preset?.name || 'default', isRefinement, isFastMode: true, winningIndex: single.index,
+      winnerModel: single.label, promotedFiles, runId, ...(livePreview ? { liveCanvas: livePreview } : {}),
+      usage: { totalTokens, totalCostUsd, 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/multi-judge.js

@@ -0,0 +1,37 @@
+import { runMultiJudgePhase } from '../moa-multi-judge.js'
+import { createBudgetAbortPayload } from '../moa-budget.js'
+import { cleanMoaWorkspaces } from '../workspace/fs.js'
+
+export async function stageMultiJudge({
+  preset,
+  successfulRefs,
+  referenceOutputs,
+  primaryJudge,
+  userPrompt,
+  judgeCriteria,
+  prices,
+  maxTokens,
+  callLlm,
+  signal,
+  onProgress,
+  cwd,
+  runId,
+  isRefinement,
+  isFastMode,
+  collectedCtx,
+  startTime,
+}) {
+  const currentRefSpent = referenceOutputs.reduce((acc, r) => acc + (r.costUsd || 0), 0)
+  const panelPhase = await runMultiJudgePhase({
+    preset, successfulRefs, primaryJudge, userPrompt, judgeCriteria, prices, maxTokens, callLlm, signal, onProgress, currentSpent: currentRefSpent,
+  })
+  if (panelPhase.abort) {
+    await cleanMoaWorkspaces(cwd, { runId })
+    const abortPayload = createBudgetAbortPayload({
+      reason: panelPhase.reason, primaryJudge, referenceOutputs, currentSpentUsd: currentRefSpent,
+      preset, isRefinement, isFastMode, collectedCtx, startTime,
+    })
+    return { ok: false, abortPayload }
+  }
+  return { ok: true, multiJudgeResult: panelPhase.result }
+}

package/lib/pipeline/peer-critique.js

@@ -0,0 +1,113 @@
+import { logger } from '../logger.js'
+import { estimateRound2Cost, estimateDownstreamCost, checkPhaseBudget, createBudgetAbortPayload } from '../moa-budget.js'
+import { buildPeerCritiquePrompt } from '../moa-prompts.js'
+import { callWithTransientRetry } from '../moa-candidates.js'
+import { extractFileBlocks, writeCandidateWorkspace, cleanMoaWorkspaces } from '../workspace/fs.js'
+import { verifyFileSyntax } from '../workspace/diff.js'
+import { estimateTokenCost } from '../pricing.js'
+import { executeTestGateForCandidates } from '../moa-test-gate.js'
+
+export async function stagePeerCritique({
+  isPeerCritiqueEnabled,
+  successfulRefs,
+  referenceOutputs,
+  preset,
+  prices,
+  maxTokens,
+  primaryJudge,
+  userPrompt,
+  isBlindEvaluation,
+  refTemp,
+  refTimeoutSec,
+  candidateRetries,
+  signal,
+  callLlm,
+  onProgress,
+  cwd,
+  runId,
+  isRefinement,
+  isFastMode,
+  collectedCtx,
+  startTime,
+  options: { testGateEnabled, testCommand, execFn } = {},
+}) {
+  let runRound2 = isPeerCritiqueEnabled && successfulRefs.length > 1
+  if (runRound2 && preset?.budget_guard_enabled && preset?.max_budget_usd > 0) {
+    const currentSpent = referenceOutputs.reduce((acc, r) => acc + (r.costUsd || 0), 0)
+    const r2Next = estimateRound2Cost(successfulRefs, prices, maxTokens)
+    const downNext = estimateDownstreamCost(primaryJudge, preset?.judge_models, successfulRefs.length, prices, maxTokens)
+    const phaseCheck = checkPhaseBudget({
+      phaseName: 'Consilium Round 2', currentSpentUsd: currentSpent, nextPhaseCostUsd: r2Next + downNext,
+      maxBudgetUsd: preset.max_budget_usd, action: preset.budget_action || 'trim', enabled: true,
+    })
+    if (!phaseCheck.allowed) {
+      if (phaseCheck.action === 'abort') {
+        await cleanMoaWorkspaces(cwd, { runId })
+        const abortPayload = createBudgetAbortPayload({
+          reason: phaseCheck.reason, primaryJudge, referenceOutputs, currentSpentUsd: currentSpent,
+          preset, isRefinement, isFastMode, collectedCtx, startTime,
+        })
+        return { ok: false, abortPayload }
+      }
+      runRound2 = false
+      if (typeof onProgress === 'function') {
+        onProgress(`✂️ *Skipping Round 2 to stay within budget ($${preset.max_budget_usd.toFixed(4)})*\n`)
+      }
+    }
+  }
+
+  if (runRound2) {
+    if (typeof onProgress === 'function') {
+      onProgress('🤝 *Consilium Round 2: Candidates reviewing peer proposals in parallel...*\n')
+    }
+    const r2Promises = successfulRefs.map(async (cand) => {
+      const opponents = successfulRefs
+        .filter((c) => c.index !== cand.index)
+        .map((c) => ({
+          label: isBlindEvaluation ? `Candidate ${c.index}` : c.label,
+          role_persona: c.role_persona || c.slot?.role_persona,
+          text: c.text,
+        }))
+      const r2Prompt = buildPeerCritiquePrompt(userPrompt, cand.text, opponents, isBlindEvaluation)
+      try {
+        const slot = cand.slot || { provider: cand.provider, model: cand.model }
+        const res = await callWithTransientRetry(callLlm, {
+          provider: slot.provider,
+          model: slot.model,
+          messages: [{ role: 'user', content: r2Prompt }],
+          temperature: refTemp,
+          maxTokens,
+          timeoutMs: refTimeoutSec * 1000,
+          signal,
+        }, candidateRetries)
+        const refinedText = typeof res === 'string' ? res : (res?.content || res?.text || cand.text)
+        cand.text = refinedText
+        const r2Files = extractFileBlocks(refinedText)
+        if (r2Files.length > 0) {
+          cand.files = r2Files
+          cand.syntaxWarning = (verifyFileSyntax(r2Files) || []).map((w) => `${w.file}: ${w.error}`).join('; ')
+          await writeCandidateWorkspace(cwd, cand.index, r2Files, { runId })
+        }
+        if (typeof res === 'object' && res?.usage) {
+          cand.usage.inputTokens = (cand.usage.inputTokens || 0) + (res.usage.inputTokens || 0)
+          cand.usage.outputTokens = (cand.usage.outputTokens || 0) + (res.usage.outputTokens || 0)
+          cand.usage.totalTokens = (cand.usage.totalTokens || 0) + (res.usage.totalTokens || 0)
+          const extraCost = estimateTokenCost(slot, res.usage, prices)
+          cand.costUsd = Number(((cand.costUsd || 0) + extraCost.costUsd).toFixed(5))
+        }
+      } catch (r2Err) {
+        logger.warn(`[dsh-moa] Round 2 peer critique failed for candidate ${cand.index}:`, r2Err?.message || r2Err)
+      }
+    })
+    await Promise.allSettled(r2Promises)
+    await executeTestGateForCandidates({
+      cwd,
+      referenceOutputs: successfulRefs,
+      preset,
+      options: { testGateEnabled, testCommand, execFn, runId },
+      onProgress,
+    })
+  }
+
+  return { ok: true }
+}

package/lib/pipeline/promotion.js

@@ -0,0 +1,114 @@
+import { logger } from '../logger.js'
+import { parseWinnerIndex, parseRecommendedAssembler } from '../moa-parser.js'
+import { extractFileBlocks, writeCandidateWorkspace, promoteCandidateWorkspace, cleanMoaWorkspaces } from '../workspace/fs.js'
+import { createPromotedPreview } from '../live-canvas.js'
+import { summarizeMoAUsage } from '../pricing.js'
+import { generateMoABenchmarkReport } from '../moa-report.js'
+import { parseFileScores } from '../moa-workbench.js'
+import { recordMoaRunAsync, candidatesForHistory } from '../history.js'
+import { slotLabel } from '../moa-prompts.js'
+
+export async function stagePromotion({
+  synthesizedText,
+  referenceOutputs,
+  successfulRefs,
+  multiJudgeResult,
+  isCuratorSynthesis,
+  allowCandidateOverride,
+  promoteOpts,
+  cwd,
+  runId,
+  signal,
+  liveCanvas,
+  startTime,
+  chosenJudge,
+  aggUsage,
+  userPrompt,
+  preset,
+  isRefinement,
+  isFastMode,
+  effectiveReferences,
+  referenceModels,
+  historyFilePath,
+  collectedCtx,
+}) {
+  const winningIndex = (multiJudgeResult?.consensus && multiJudgeResult?.winningCandidateIndex)
+    ? multiJudgeResult.winningCandidateIndex
+    : parseWinnerIndex(synthesizedText, 1, referenceOutputs.length)
+
+  const recommendedAssembler = isCuratorSynthesis
+    ? parseRecommendedAssembler(synthesizedText, winningIndex, referenceOutputs.length)
+    : null
+
+  const synthesizedFiles = extractFileBlocks(synthesizedText)
+  let promotedFiles = []
+  const keepWorkspaces = allowCandidateOverride
+
+  if (signal?.aborted) {
+    if (!keepWorkspaces) await cleanMoaWorkspaces(cwd, { runId })
+    return { ok: false, abort: true, error: new Error('Turn aborted') }
+  }
+
+  try {
+    if (synthesizedFiles.length > 0) {
+      await writeCandidateWorkspace(cwd, 'curator-synthesis', synthesizedFiles, { runId })
+      promotedFiles = await promoteCandidateWorkspace(cwd, 'curator-synthesis', { ...promoteOpts, runId, keepMoa: keepWorkspaces })
+    } else if (referenceOutputs[winningIndex - 1]?.files?.length > 0) {
+      promotedFiles = await promoteCandidateWorkspace(cwd, winningIndex, { ...promoteOpts, runId, keepMoa: keepWorkspaces })
+    } else if (successfulRefs[0]?.files?.length > 0) {
+      const fallbackIdx = successfulRefs[0].index
+      promotedFiles = await promoteCandidateWorkspace(cwd, fallbackIdx, { ...promoteOpts, runId, keepMoa: keepWorkspaces })
+    } else if (!keepWorkspaces) {
+      await cleanMoaWorkspaces(cwd, { runId })
+    }
+  } catch (promoteErr) {
+    if (!keepWorkspaces) await cleanMoaWorkspaces(cwd, { runId })
+    if (signal?.aborted || promoteErr?.message === 'Turn aborted') return { ok: false, abort: true, error: new Error('Turn aborted') }
+    throw promoteErr
+  }
+
+  const livePreview = await createPromotedPreview(liveCanvas, cwd, promotedFiles, referenceOutputs, { winningIndex, synthesizedFiles })
+  const durationMs = Date.now() - startTime
+  const usageSummary = summarizeMoAUsage(referenceOutputs, aggUsage, multiJudgeResult?.totalUsage)
+  const winningRef = referenceOutputs[winningIndex - 1]
+  const winnerModel = winningRef?.label || slotLabel(effectiveReferences[0] || referenceModels[0])
+  const finalAggLabel = slotLabel(chosenJudge)
+
+  let benchmarkReport = null
+  if (preset?.report_generation_enabled) {
+    benchmarkReport = generateMoABenchmarkReport({
+      runId, timestamp: new Date().toISOString(), preset: preset?.name || 'default',
+      prompt: userPrompt, durationMs, usage: usageSummary, costUsd: usageSummary.totalCostUsd,
+      candidates: referenceOutputs, winningIndex, winningLabel: winnerModel,
+      consensus: multiJudgeResult, testGate: referenceOutputs.filter((r) => r.testResult).map((r) => r.testResult),
+      isComposite: Boolean(preset?.composite_merge_enabled),
+    })
+  }
+
+  const fileScores = (preset?.interactive_workbench_enabled)
+    ? parseFileScores(synthesizedText, referenceOutputs)
+    : null
+
+  try {
+    await recordMoaRunAsync({
+      id: runId, cwd, prompt: userPrompt, preset: preset?.name || 'default', isRefinement,
+      candidates: candidatesForHistory(referenceOutputs),
+      aggregator: { provider: chosenJudge.provider, model: chosenJudge.model, usage: aggUsage, costUsd: aggUsage.costUsd },
+      winnerIndex: winningIndex, winnerModel, promotedFiles, benchmarkReport, consensus: multiJudgeResult,
+      fileScores, totalTokens: usageSummary.totalTokens, totalCostUsd: usageSummary.totalCostUsd, durationMs,
+    }, historyFilePath || undefined)
+  } catch (histErr) {
+    logger.warn('[dsh-moa] Failed to record run in history:', histErr)
+  }
+
+  return {
+    ok: true,
+    payload: {
+      kind: 'synthesis', content: synthesizedText, aggregator: isFastMode ? 'Fast Mode (Direct)' : finalAggLabel,
+      references: referenceOutputs, presetName: preset?.name || 'default', isRefinement, isFastMode, isCuratorSynthesis,
+      recommendedAssembler, winningIndex, winnerModel, promotedFiles, runId, allowCandidateOverride,
+      benchmarkReport, consensus: multiJudgeResult, fileScores, ...(livePreview ? { liveCanvas: livePreview } : {}),
+      usage: usageSummary, skippedFiles: collectedCtx?.skippedFiles || 0, skippedList: collectedCtx?.skippedList || [], durationMs,
+    }
+  }
+}

package/lib/pipeline/questions.js

@@ -0,0 +1,79 @@
+import { logger } from '../logger.js'
+import { buildQuestionSynthesisPrompt, slotLabel } from '../moa-prompts.js'
+import { callWithTransientRetry } from '../moa-candidates.js'
+import { estimateTokenCost } from '../pricing.js'
+import { cleanMoaWorkspaces } from '../workspace/fs.js'
+import { recordMoaRunAsync, candidatesForHistory } from '../history.js'
+
+export async function stageClarifyingQuestions({
+  userPrompt,
+  referenceOutputs,
+  primaryJudge,
+  aggTimeoutSec,
+  prices,
+  callLlm,
+  cwd,
+  runId,
+  preset,
+  isRefinement,
+  isFastMode,
+  collectedCtx,
+  startTime,
+  historyFilePath,
+  onProgress,
+}) {
+  if (typeof onProgress === 'function') {
+    onProgress('📋 *Judge synthesizes the clarification questionnaire...*\n')
+  }
+  const questionPrompt = buildQuestionSynthesisPrompt(userPrompt, referenceOutputs)
+  let questionsContent = ''
+  let qUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0 }
+  try {
+    const qRes = await callWithTransientRetry(callLlm, {
+      provider: primaryJudge.provider,
+      model: primaryJudge.model,
+      messages: [{ role: 'user', content: questionPrompt }],
+      temperature: 0.3,
+      maxTokens: 2048,
+      timeoutMs: aggTimeoutSec * 1000,
+    }, 1)
+    questionsContent = typeof qRes === 'string' ? qRes : (qRes?.content || qRes?.text || '')
+    const qFallbackUsage = (typeof qRes === 'object' && qRes?.usage) ? qRes.usage : {
+      inputTokens: Math.max(1, Math.round(questionPrompt.length / 4)),
+      outputTokens: Math.max(1, Math.round(questionsContent.length / 4)),
+    }
+    qUsage = estimateTokenCost(primaryJudge, qFallbackUsage, prices)
+  } catch (err) {
+    logger.warn('[dsh-moa] Questionnaire synthesis failed, proceeding with fallback questions:', err)
+    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, { runId })
+  const totalTokens = referenceOutputs.reduce((acc, r) => acc + (r.usage?.totalTokens || 0), 0) + qUsage.totalTokens
+  const totalCostUsd = Number((referenceOutputs.reduce((acc, r) => acc + (r.costUsd || 0), 0) + qUsage.costUsd).toFixed(5))
+  const durationMs = Date.now() - startTime
+  try {
+    await recordMoaRunAsync({
+      cwd,
+      prompt: userPrompt,
+      preset: preset?.name || 'default',
+      isRefinement,
+      candidates: candidatesForHistory(referenceOutputs),
+      aggregator: { provider: primaryJudge.provider, model: primaryJudge.model, usage: qUsage, costUsd: qUsage.costUsd },
+      winnerIndex: -1,
+      winnerModel: 'none',
+      promotedFiles: [],
+      totalTokens,
+      totalCostUsd,
+      durationMs,
+    }, historyFilePath || undefined)
+  } catch (histErr) {
+    logger.warn('[dsh-moa] Failed to record questionnaire run in history:', histErr?.message || histErr)
+  }
+  return {
+    kind: 'questions', content: questionsContent, aggregator: slotLabel(primaryJudge),
+    references: referenceOutputs, presetName: preset?.name || 'default', isRefinement, isFastMode,
+    winningIndex: 0, winnerModel: 'none', promotedFiles: [],
+    usage: { totalTokens, totalCostUsd, candidates: referenceOutputs.map((r) => ({ label: r.label, usage: r.usage, costUsd: r.costUsd })), aggregator: qUsage },
+    skippedFiles: collectedCtx?.skippedFiles || 0, skippedList: collectedCtx?.skippedList || [], durationMs,
+  }
+}