@goodandready/dsh-moa 0.2.19 → 0.2.21

package/README.md

@@ -136,6 +136,12 @@ Configure your models in `Settings → Plugins → Mixture of Agents`:
 * Configure named presets (`default`, `fast`, `deep-reasoning`), judge criteria and temperatures.
 * Enable or disable MoA and see the real host status chip; the telemetry grid shows total runs and average run cost.
 
+### 7. Candidate Diff Viewer
+Inspect line-by-line differences between candidate proposals and the curator's synthesized deliverable directly in the UI. Features file selection, delta line highlights (added, removed, same), and unified diff rendering via a zero-dependency in-memory LCS algorithm.
+
+### 8. Pre-Promotion Git Checkpoints (`dsh-time-machine`)
+Before promoting any winning candidate files over the workspace root, `dsh-moa` invokes the local `dsh-time-machine` service to create a shadow Git checkpoint (`moa-pre-promotion: candidate-N`). If `dsh-time-machine` is absent or unreachable, file promotion proceeds seamlessly via best-effort fallback.
+
 ### 6. Live Canvas 1-Click Preview (optional)
 If `@goodandready/dsh-live-canvas` is installed in the same profile, `dsh-moa` pushes the promoted HTML file to the Live Canvas REST contract (`POST /dsh-live-canvas/api/preview`, served by the same harness webServer) and appends a one-click preview link (`/dsh-live-canvas/sandbox/<id>`) to the answer. Without the plugin the step is skipped silently — no errors in the log, no dead links.
 
@@ -269,6 +275,9 @@ dsh-moa:
 | `/dsh-moa/leaderboard` | `GET` | Computes model win-rate leaderboard and average execution costs |
 | `/dsh-moa/runs/<id>` | `GET` | Returns a single recorded run by id |
 | `/dsh-moa/run` | `POST` | Runs the full MoA pipeline over HTTP (400 when `enabled: false`) |
+| `/dsh-moa/diff` | `GET` | Computes line-by-line diff between candidate runs or curator synthesis |
+| `/dsh-moa/promote` | `POST` | Manually promotes candidate workspace files to project root |
+| `/api/dsh-moa/update` | `POST` | One-click plugin updater from npm with safe-write verification |
 
 ---
 

package/README.ru.md

@@ -136,6 +136,12 @@ graph TD
 * Конфигурация именованных пресетов (`default`, `fast`, `deep-reasoning`), критериев судьи и температур.
 * Включение/отключение MoA и фактический статус-бейдж хоста; сетка телеметрии показывает общее число запусков и среднюю стоимость.
 
+### 7. Интерактивный просмотр различий (Candidate Diff Viewer)
+Позволяет визуально сопоставлять построчные различия между решениями моделей-советников и итоговым синтезом судьи прямо в интерфейсе. Поддерживает выбор конкретного файла, подсветку добавленных/удаленных строк и вычисление дельт с помощью легковесного алгоритма LCS без внешних зависимостей.
+
+### 8. Теневые Git-чекпоинты (`dsh-time-machine`)
+Перед промоушном файлов победителя в корень рабочей области `dsh-moa` автоматически обращается к сервису `dsh-time-machine` для создания снимка (`moa-pre-promotion: candidate-N`). Если плагин недоступен, промоушн штатно продолжается по схеме best-effort.
+
 ### 6. Live Canvas 1-клик предпросмотр (опционально)
 Если в профиле установлен `@goodandready/dsh-live-canvas`, `dsh-moa` отправляет промоученный HTML-файл в REST-контракт Live Canvas (`POST /dsh-live-canvas/api/preview`, тот же webServer харнесса) и добавляет к ответу ссылку на предпросмотр (`/dsh-live-canvas/sandbox/<id>`). Без плагина шаг пропускается тихо — без ошибок в журнале и без битых ссылок.
 
@@ -269,6 +275,9 @@ dsh-moa:
 | `/dsh-moa/leaderboard` | `GET` | Лидерборд побед моделей и средняя стоимость генерации |
 | `/dsh-moa/runs/<id>` | `GET` | Возвращает один записанный запуск по id |
 | `/dsh-moa/run` | `POST` | Запускает полный пайплайн MoA по HTTP (400 при `enabled: false`) |
+| `/dsh-moa/diff` | `GET` | Вычисляет построчный diff между решениями кандидатов или синтезом куратора |
+| `/dsh-moa/promote` | `POST` | Ручной промоушн файлов кандидата в корень проекта с созданием снимка |
+| `/api/dsh-moa/update` | `POST` | One-click обновление плагина из npm с проверкой безопасности источника |
 
 ---
 

package/README.zh.md

@@ -136,6 +136,12 @@ graph TD
 * 自定义命名预设 (`default`, `fast`, `deep-reasoning`)、裁判评审准则与温度。
 * 启用/停用 MoA 开关并查看真实的主机状态徽章；遥测网格展示总运行次数与平均运行成本。
 
+### 7. 候选方案差异对比器 (Candidate Diff Viewer)
+直接在界面中可视化对比顾问方案之间以及顾问与裁判综合方案之间的逐行差异。支持文件筛选、增删改高亮，基于纯 JavaScript LCS 差异算法，零第三方依赖。
+
+### 8. 提升前 Git 快照检查点 (`dsh-time-machine`)
+在将胜出候选者的文件提升并覆盖至项目根目录前，`dsh-moa` 自动调用本地 `dsh-time-machine` 建立影子 Git 检查点 (`moa-pre-promotion: candidate-N`)。如未安装则静默回退，不阻断提升流程。
+
 ### 6. Live Canvas 一键预览（可选）
 若同一 profile 中安装了 `@goodandready/dsh-live-canvas`，`dsh-moa` 会将提升后的 HTML 文件推送到 Live Canvas 的 REST 契约（`POST /dsh-live-canvas/api/preview`，由同一 harness webServer 提供服务），并在回答中附上一键预览链接（`/dsh-live-canvas/sandbox/<id>`）。未安装该插件时此步骤静默跳过——日志无报错，也不会出现死链接。
 

package/lib/client.js

@@ -127,6 +127,17 @@ window.__ModuleLoader__.load({
       'updater.available': 'Update available: v{version}',
       'updater.upToDate': 'Up to date',
       'updater.checkFailed': 'Registry check failed',
+      'diff.title': 'Candidate Diff Viewer',
+      'diff.desc': 'Visually inspect differences between candidate solutions and judge synthesis in the project workspace.',
+      'diff.select_from': 'Base:',
+      'diff.select_to': 'Compare with:',
+      'diff.select_file': 'File:',
+      'diff.no_files': 'No files found in candidate workspaces (.moa). Run a task with /moa to generate candidate code.',
+      'diff.refresh': 'Refresh Diff',
+      'diff.loading': 'Loading differences...',
+      'diff.curator': 'Curator Synthesis',
+      'diff.candidate': 'Candidate {num}',
+      'diff.empty': 'Selected files are identical (zero diff).',
       'updater.success': 'Successfully updated to v{version}. Restart DSH to apply.',
     }
 
@@ -230,6 +241,17 @@ window.__ModuleLoader__.load({
       'updater.available': '发现新版本：v{version}',
       'updater.upToDate': '已是最新版本',
       'updater.checkFailed': '检查版本失败',
+      'diff.title': '候选方案差异查看器 (Diff Viewer)',
+      'diff.desc': '在项目工作区中可视化检查候选方案与裁判合成方案之间的文件差异。',
+      'diff.select_from': '基准方案：',
+      'diff.select_to': '对比目标：',
+      'diff.select_file': '文件：',
+      'diff.no_files': '在候选工作区 (.moa) 中未发现文件。请先运行 /moa 生成候选代码。',
+      'diff.refresh': '刷新差异',
+      'diff.loading': '正在加载差异...',
+      'diff.curator': '裁判合成 (Curator Synthesis)',
+      'diff.candidate': '候选方案 {num}',
+      'diff.empty': '选中的文件完全一致（无差异）。',
       'updater.success': '成功更新至 v{version}，请重启 DSH 使其生效。',
     }
 
@@ -360,6 +382,20 @@ window.__ModuleLoader__.load({
 .moa-chev{transition:transform .2s ease;color:var(--dsw-alias-label-secondary)}
 .moa-chev-open{transform:rotate(180deg)}
 .moa-body{padding:0 18px 20px;border-top:1px solid var(--dsw-alias-border-l2)}
+/* Candidate Diff Viewer */
+.moa-diff-container{display:flex;flex-direction:column;gap:10px;margin-top:10px}
+.moa-diff-controls{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
+.moa-diff-select{height:32px;padding:0 8px;border-radius:6px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font-size:12px;outline:none}
+.moa-diff-box{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:8px 0;font-family:monospace, ui-monospace, Menlo, Consolas, monospace;font-size:12px;line-height:1.5;max-height:400px;overflow-y:auto;overflow-x:auto}
+.moa-diff-line{display:flex;padding:1px 10px;white-space:pre}
+.moa-diff-line-same{color:var(--dsw-alias-label-secondary)}
+.moa-diff-line-add{background:color-mix(in srgb, var(--dsw-alias-state-success-primary) 14%, transparent);color:var(--dsw-alias-state-success-primary)}
+.moa-diff-line-del{background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent);color:var(--dsw-alias-state-error-primary)}
+.moa-diff-prefix{width:20px;user-select:none;flex-shrink:0;font-weight:bold}
+.moa-diff-content{flex:1}
+.moa-diff-stat-add{color:var(--dsw-alias-state-success-primary);font-weight:600}
+.moa-diff-stat-del{color:var(--dsw-alias-state-error-primary);font-weight:600}
+
 `
 
     let stylesInjected = false
@@ -581,6 +617,197 @@ window.__ModuleLoader__.load({
       )
     }
 
+    function CandidateDiffSection({ t, currentRefs = [] }) {
+      const [fromCandidate, setFromCandidate] = React.useState('1')
+      const [toCandidate, setToCandidate] = React.useState('curator-synthesis')
+      const [selectedFile, setSelectedFile] = React.useState('')
+      const [files, setFiles] = React.useState([])
+      const [diff, setDiff] = React.useState([])
+      const [fromSize, setFromSize] = React.useState(0)
+      const [toSize, setToSize] = React.useState(0)
+      const [loading, setLoading] = React.useState(false)
+      const [error, setError] = React.useState(null)
+      const [hasFetched, setHasFetched] = React.useState(false)
+
+      const candidateCount = Math.max(currentRefs.length || 0, 2)
+      const candidateOptions = []
+      for (let i = 1; i <= candidateCount; i++) {
+        candidateOptions.push({
+          value: String(i),
+          label: (t('diff.candidate') || 'Candidate {num}').replace('{num}', String(i)),
+        })
+      }
+
+      const loadDiff = React.useCallback((targetFile = selectedFile) => {
+        setLoading(true)
+        setError(null)
+        const params = new URLSearchParams()
+        if (fromCandidate) params.set('from', fromCandidate)
+        if (toCandidate) params.set('to', toCandidate)
+        if (targetFile) params.set('file', targetFile)
+
+        fetch('/dsh-moa/diff?' + params.toString(), { cache: 'no-store' })
+          .then((r) => {
+            if (!r.ok) throw new Error('HTTP ' + r.status)
+            return r.json()
+          })
+          .then((data) => {
+            setLoading(false)
+            setHasFetched(true)
+            if (data && data.ok) {
+              const fileList = Array.isArray(data.files) ? data.files : []
+              setFiles(fileList)
+              setDiff(Array.isArray(data.diff) ? data.diff : [])
+              setFromSize(data.fromSize || 0)
+              setToSize(data.toSize || 0)
+              if (data.selectedFile && data.selectedFile !== targetFile) {
+                setSelectedFile(data.selectedFile)
+              }
+            } else {
+              setError(data?.error || 'Failed to load diff')
+            }
+          })
+          .catch((err) => {
+            setLoading(false)
+            setHasFetched(true)
+            setError(err.message || String(err))
+          })
+      }, [fromCandidate, toCandidate, selectedFile])
+
+      React.useEffect(() => {
+        loadDiff()
+      }, [fromCandidate, toCandidate])
+
+      const handleFileChange = (e) => {
+        const nextFile = e.target.value
+        setSelectedFile(nextFile)
+        loadDiff(nextFile)
+      }
+
+      const adds = diff.filter((d) => d.type === 'added').length
+      const dels = diff.filter((d) => d.type === 'removed').length
+
+      return React.createElement(
+        'div',
+        { className: 'moa-section-card' },
+        React.createElement('div', { className: 'moa-section-title' }, t('diff.title') || '🔍 Candidate Diff Viewer'),
+        React.createElement('div', { className: 'moa-section-desc' }, t('diff.desc') || 'Visually inspect differences between candidate solutions and judge synthesis in the project workspace.'),
+
+        React.createElement(
+          'div',
+          { className: 'moa-diff-container' },
+          /* Controls bar */
+          React.createElement(
+            'div',
+            { className: 'moa-diff-controls' },
+            React.createElement(
+              'label',
+              { style: { display: 'flex', alignItems: 'center', gap: 6, fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } },
+              t('diff.select_from') || 'Base:',
+              React.createElement(
+                'select',
+                {
+                  className: 'moa-diff-select',
+                  value: fromCandidate,
+                  onChange: (e) => setFromCandidate(e.target.value),
+                },
+                candidateOptions.map((opt) => React.createElement('option', { key: opt.value, value: opt.value }, opt.label)),
+                React.createElement('option', { value: 'curator-synthesis' }, t('diff.curator') || 'Curator Synthesis')
+              )
+            ),
+            React.createElement(
+              'label',
+              { style: { display: 'flex', alignItems: 'center', gap: 6, fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } },
+              t('diff.select_to') || 'Compare with:',
+              React.createElement(
+                'select',
+                {
+                  className: 'moa-diff-select',
+                  value: toCandidate,
+                  onChange: (e) => setToCandidate(e.target.value),
+                },
+                React.createElement('option', { value: 'curator-synthesis' }, t('diff.curator') || 'Curator Synthesis'),
+                candidateOptions.map((opt) => React.createElement('option', { key: opt.value, value: opt.value }, opt.label))
+              )
+            ),
+            files.length > 0 && React.createElement(
+              'label',
+              { style: { display: 'flex', alignItems: 'center', gap: 6, fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } },
+              t('diff.select_file') || 'File:',
+              React.createElement(
+                'select',
+                {
+                  className: 'moa-diff-select',
+                  value: selectedFile || files[0] || '',
+                  onChange: handleFileChange,
+                },
+                files.map((f) => React.createElement('option', { key: f, value: f }, f))
+              )
+            ),
+            React.createElement(
+              'button',
+              {
+                type: 'button',
+                className: 'moa-btn moa-btn-sub',
+                onClick: () => loadDiff(),
+                disabled: loading,
+              },
+              loading ? (t('diff.loading') || 'Loading...') : (t('diff.refresh') || 'Refresh Diff')
+            ),
+            diff.length > 0 && React.createElement(
+              'div',
+              { style: { fontSize: 12, display: 'flex', gap: 8, alignItems: 'center', marginLeft: 'auto' } },
+              adds > 0 && React.createElement('span', { className: 'moa-diff-stat-add' }, `+${adds}`),
+              dels > 0 && React.createElement('span', { className: 'moa-diff-stat-del' }, `-${dels}`),
+              fromSize > 0 && toSize > 0 && React.createElement(
+                'span',
+                { style: { color: 'var(--dsw-alias-label-secondary)', fontSize: 11 } },
+                `(${fromSize}B → ${toSize}B)`
+              )
+            )
+          ),
+
+          /* Error state */
+          error && React.createElement(
+            'div',
+            { className: 'moa-alert-err', style: { fontSize: 12, padding: '8px 12px' } },
+            error
+          ),
+
+          /* Empty files state */
+          !error && !loading && hasFetched && files.length === 0 && React.createElement(
+            'div',
+            { style: { padding: '16px 12px', textAlign: 'center', color: 'var(--dsw-alias-label-secondary)', fontSize: 13, background: 'var(--dsw-alias-bg-layer-2)', borderRadius: 8 } },
+            t('diff.no_files') || 'No files found in candidate workspaces (.moa). Run a task with /moa to generate candidate code.'
+          ),
+
+          /* Identical content state */
+          !error && !loading && files.length > 0 && diff.length > 0 && adds === 0 && dels === 0 && React.createElement(
+            'div',
+            { style: { padding: '12px', textAlign: 'center', color: 'var(--dsw-alias-state-success-primary)', fontSize: 12, background: 'var(--dsw-alias-bg-layer-2)', borderRadius: 8 } },
+            t('diff.empty') || 'Selected files are identical (zero diff).'
+          ),
+
+          /* Diff lines display */
+          !error && files.length > 0 && diff.length > 0 && (adds > 0 || dels > 0) && React.createElement(
+            'div',
+            { className: 'moa-diff-box' },
+            diff.map((item, idx) => {
+              const isAdd = item.type === 'added'
+              const isDel = item.type === 'removed'
+              const lineClass = isAdd ? 'moa-diff-line moa-diff-line-add' : isDel ? 'moa-diff-line moa-diff-line-del' : 'moa-diff-line moa-diff-line-same'
+              const prefix = isAdd ? '+' : isDel ? '-' : ' '
+              return React.createElement(
+                'div',
+                { key: idx, className: lineClass },
+                React.createElement('span', { className: 'moa-diff-prefix' }, prefix),
+                React.createElement('span', { className: 'moa-diff-content' }, item.line)
+              )
+            })
+          )
+        )
+      )
+    }
     function MoAEditor({
       t,
       presets,
@@ -692,7 +919,7 @@ window.__ModuleLoader__.load({
             provider: 'opencode-go',
             model: 'deepseek-v4-flash',
           }
-          refs.push({ provider: fallback.provider, model: fallback.model })
+          refs.push({ provider: fallback.provider, model: fallback.model, role_persona: 'general' })
           return { ...p, reference_models: refs }
         })
       }
@@ -711,8 +938,8 @@ window.__ModuleLoader__.load({
           enabled: true,
           ask_clarifying_questions: true,
           reference_models: currentPreset?.reference_models?.length ? structuredClone(currentPreset.reference_models) : [
-            { provider: 'opencode-go', model: 'deepseek-v4-flash' },
-            { provider: 'codex', model: 'gpt-5.6-sol' },
+            { provider: 'opencode-go', model: 'deepseek-v4-flash', role_persona: 'general' },
+            { provider: 'codex', model: 'gpt-5.6-sol', role_persona: 'general' },
           ],
           aggregator: currentPreset?.aggregator?.provider ? structuredClone(currentPreset.aggregator) : {
             provider: 'codex',
@@ -1410,6 +1637,11 @@ window.__ModuleLoader__.load({
           )
         ),
 
+        /* ── SECTION 4b: CANDIDATE DIFF VIEWER ── */
+        React.createElement(CandidateDiffSection, {
+          t,
+          currentRefs,
+        }),
         /* ── PLUGIN UPDATES ── */
         React.createElement(
           'div',
@@ -1722,6 +1954,20 @@ window.__ModuleLoader__.load({
         reload()
       }, [reload])
 
+      React.useEffect(() => {
+        const lbUrl = leaderboardPresetFilter !== 'all'
+          ? `/dsh-moa/leaderboard?preset=${encodeURIComponent(leaderboardPresetFilter)}`
+          : '/dsh-moa/leaderboard'
+        fetch(lbUrl, { cache: 'no-store' })
+          .then((r) => r.json())
+          .then((data) => {
+            if (data && data.ok && Array.isArray(data.models)) {
+              setLeaderboard(data.models.slice(0, 10))
+            }
+          })
+          .catch(() => {})
+      }, [leaderboardPresetFilter])
+
       const handleSave = () => {
         setSaveStatus(t('actions.saving'))
 

package/lib/file-workspace.js

@@ -3,15 +3,31 @@ import vm from 'node:vm'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
+/**
+ * Validates that an untrusted relative path is safe and does not traverse upwards.
+ */
+export function isSafeRelativePath(relPath) {
+  if (!relPath || typeof relPath !== 'string') return false
+  const trimmed = relPath.trim()
+  if (!trimmed || path.isAbsolute(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\')) return false
+  const normalized = path.normalize(trimmed)
+  return Boolean(normalized && !normalized.startsWith('..') && !path.isAbsolute(normalized))
+}
+
+/**
+ * Asserts that a resolved path is strictly contained within baseDir.
+ */
+export function assertPathContained(baseDir, subPath) {
+  const resolvedBase = path.resolve(baseDir)
+  const resolvedTarget = path.resolve(resolvedBase, subPath)
+  if (resolvedTarget !== resolvedBase && !resolvedTarget.startsWith(resolvedBase + path.sep)) {
+    throw new Error(`Path traversal violation: "${subPath}" escapes base directory "${baseDir}"`)
+  }
+  return resolvedTarget
+}
+
 /**
  * Parses markdown code blocks that specify file paths.
- * Supports patterns like:
- * ```html file="index.html"
- * ```javascript filepath=script.js
- * // File: index.html
- * <!-- File: styles.css -->
- * ### File: index.html
- * ```html
  */
 export function extractFileBlocks(text) {
   if (!text || typeof text !== 'string') return []
@@ -19,81 +35,48 @@ export function extractFileBlocks(text) {
   const files = []
   const seenPaths = new Set()
 
-  // Pattern 1: fenced blocks with file="..." or path="..." in info string
-  // Example: ```html file="index.html" or ```js path=src/main.js
-  const fenceRegex = /```[\w-]*\s+(?:file|path|filepath)=["']?([^\s"'\n\r]+)["']?[\r\n]+([\s\S]*?)```/gi
-  let match
-  while ((match = fenceRegex.exec(text)) !== null) {
-    const rawPath = match[1].trim()
-    const content = match[2]
-    if (rawPath && !seenPaths.has(rawPath)) {
+  const addFile = (rawPath, fileContent) => {
+    if (rawPath && isSafeRelativePath(rawPath) && !seenPaths.has(rawPath)) {
       seenPaths.add(rawPath)
-      files.push({ relativePath: sanitizePath(rawPath), content })
+      files.push({ relativePath: rawPath, content: fileContent.trimEnd() + '\n' })
     }
   }
 
-  // Pattern 2: Explicit headers before code blocks, e.g.
-  // **File: `index.html`** or ### File: index.html or `File: index.html` followed by ```
-  const headerRegex = /(?:###?\s*File:\s*|File:\s*|#\s*File:\s*)[`"]?([a-zA-Z0-9_.\-\/\\]+)[`"]?\s*[\r\n]+```[\w-]*[\r\n]+([\s\S]*?)```/gi
-  while ((match = headerRegex.exec(text)) !== null) {
-    const rawPath = match[1].trim()
-    const content = match[2]
-    if (rawPath && !seenPaths.has(rawPath)) {
-      seenPaths.add(rawPath)
-      files.push({ relativePath: sanitizePath(rawPath), content })
-    }
-  }
+  // Pattern 1: fenced blocks with file="..." or path="..." in info string
+  const fenceRegex = /```[\w-]*\s+(?:file|path|filepath)=["']?([^\s"'\n\r]+)["']?[\r\n]+([\s\S]*?)```/gi
+  let match
+  while ((match = fenceRegex.exec(text)) !== null) addFile(match[1].trim(), match[2])
 
-  // Pattern 3: Comment inside the code block on line 1: // File: foo.js or /* File: foo.css */ or <!-- File: index.html -->
-  const commentRegex = /```[\w-]*[\r\n]+(?:\/\/|\/\*|<!--|#)\s*(?:File|filename):\s*([a-zA-Z0-9_.\-\/\\]+)(?:\s*\*\/|\s*-->)?[\r\n]+([\s\S]*?)```/gi
-  while ((match = commentRegex.exec(text)) !== null) {
-    const rawPath = match[1].trim()
-    const content = match[2]
-    if (rawPath && !seenPaths.has(rawPath)) {
-      seenPaths.add(rawPath)
-      files.push({ relativePath: sanitizePath(rawPath), content })
-    }
-  }
+  // Pattern 2: comment header: // File: path/to/file.ext or <!-- File: ... -->
+  const commentRegex = /(?:\/\/|#|<!--)\s*(?:File|Path):\s*([^\s\n\r>]+)(?:\s*-->)?[\r\n]+```[\w-]*[\r\n]+([\s\S]*?)```/gi
+  while ((match = commentRegex.exec(text)) !== null) addFile(match[1].trim(), match[2])
+
+  // Pattern 3: markdown header: ### File: path/to/file.ext
+  const headerRegex = /#{1,4}\s+(?:File|Path):\s*([^\s\n\r]+)[\r\n]+```[\w-]*[\r\n]+([\s\S]*?)```/gi
+  while ((match = headerRegex.exec(text)) !== null) addFile(match[1].trim(), match[2])
+
+  // Pattern 4: first line inside code block: // File: path/to/file.ext
+  const inlineRegex = /```[\w-]*[\r\n]+(?:\/\/|#|<!--)\s*(?:File|Path):\s*([^\s\n\r>]+)(?:\s*-->)?[\r\n]+([\s\S]*?)```/gi
+  while ((match = inlineRegex.exec(text)) !== null) addFile(match[1].trim(), match[2])
 
-  // Fallback: If no annotated blocks found, check if text has exactly one prominent standalone code block with common extensions
+  // Fallback: single anonymous code block if it contains complete HTML
   if (files.length === 0) {
-    const singleBlockRegex = /```(html|css|javascript|js|json|python|py|sh|bash)[\r\n]+([\s\S]*?)```/gi
-    const singleMatches = []
-    while ((match = singleBlockRegex.exec(text)) !== null) {
-      singleMatches.push({ lang: match[1].toLowerCase(), content: match[2] })
-    }
-    if (singleMatches.length === 1) {
-      const extMap = {
-        html: 'index.html',
-        javascript: 'index.js',
-        js: 'index.js',
-        css: 'style.css',
-        python: 'main.py',
-        py: 'main.py',
-        json: 'data.json',
-        bash: 'run.sh',
-        sh: 'run.sh',
+    const htmlBlockRegex = /```(?:html)?[\r\n]+([\s\S]*?)```/gi
+    let htmlMatch
+    while ((htmlMatch = htmlBlockRegex.exec(text)) !== null) {
+      const candidateHtml = htmlMatch[1]
+      if (/<(!DOCTYPE\s+)?html/i.test(candidateHtml) || /<body/i.test(candidateHtml)) {
+        files.push({ relativePath: 'index.html', content: candidateHtml.trimEnd() + '\n' })
+        break
       }
-      const defaultName = extMap[singleMatches[0].lang] || 'output.txt'
-      files.push({ relativePath: defaultName, content: singleMatches[0].content })
     }
   }
 
   return files
 }
 
-function sanitizePath(filePath) {
-  const normalized = path.normalize(filePath).replace(/^(\.\.[\/\\])+/, '')
-  return normalized.replace(/^[\\\/]+/, '')
-}
-
 /**
- * Collects readable text files from current workspace to feed as context for candidate models (#6).
- * Ignores node_modules, .git, .moa, binary files, large bundles.
- */
-/**
- * Formats collected project files into structured Markdown code blocks
- * suitable for inclusion in candidate system prompts.
+ * Formats collected project files into a structured markdown context string.
  */
 export function formatProjectContext(projectFiles = [], options = {}) {
   if (!Array.isArray(projectFiles) || projectFiles.length === 0) return ''
@@ -123,7 +106,6 @@ export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
 
   const collected = []
   let totalChars = 0
-
   let skippedFiles = 0
   const skippedList = []
 
@@ -132,17 +114,14 @@ export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
     let list
     try {
       list = await fs.readdir(currentDir, { withFileTypes: true })
-    } catch (readDirErr) {
+    } catch {
       skippedFiles++
       skippedList.push(relPrefix || '.')
       return
     }
 
     for (const item of list) {
-      // Skip all dotfiles, including .env and .env.* variants: their
-      // contents must never be shipped to third-party model providers.
       if (item.name.startsWith('.')) continue
-
       const rel = relPrefix ? `${relPrefix}/${item.name}` : item.name
       const full = path.join(currentDir, item.name)
 
@@ -155,9 +134,7 @@ export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
       }
 
       if (item.isDirectory()) {
-        if (!ignoreDirs.has(item.name)) {
-          await scan(full, rel)
-        }
+        if (!ignoreDirs.has(item.name)) await scan(full, rel)
       } else if (item.isFile()) {
         const ext = path.extname(item.name).toLowerCase()
         if (codeExts.has(ext)) {
@@ -173,7 +150,7 @@ export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
             const truncated = content.length > budgetRemaining ? content.slice(0, budgetRemaining) + '\n... [truncated]' : content
             totalChars += truncated.length
             collected.push({ relativePath: rel, content: truncated, size: stat.size })
-          } catch (fileErr) {
+          } catch {
             skippedFiles++
             skippedList.push(rel)
           }
@@ -187,8 +164,7 @@ export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
 }
 
 /**
- * Checks if a task prompt is an iterative refinement / modification
- * of an existing project rather than a greenfield project creation (#4).
+ * Checks if a task prompt is an iterative refinement / modification.
  */
 export function isRefinementTask(userPrompt = '', projectFiles = null) {
   if (Array.isArray(projectFiles) && projectFiles.length === 0) return false
@@ -225,12 +201,17 @@ export function isRefinementTask(userPrompt = '', projectFiles = null) {
 export async function writeCandidateWorkspace(baseDir, candidateIndex, files = []) {
   if (!baseDir || !Array.isArray(files) || files.length === 0) return []
 
-  const candidateDir = path.join(baseDir, '.moa', `candidate-${candidateIndex}`)
+  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')
+  const candidateDir = assertPathContained(moaRoot, sub)
   await fs.mkdir(candidateDir, { recursive: true })
 
   const written = []
   for (const file of files) {
-    const fullPath = path.join(candidateDir, file.relativePath)
+    if (!isSafeRelativePath(file.relativePath)) continue
+    const fullPath = assertPathContained(candidateDir, file.relativePath)
     await fs.mkdir(path.dirname(fullPath), { recursive: true })
     await fs.writeFile(fullPath, file.content, 'utf8')
     written.push({
@@ -244,14 +225,44 @@ export async function writeCandidateWorkspace(baseDir, candidateIndex, files = [
 }
 
 /**
- * Promotes winning candidate files to baseDir root,
- * then cleans up the temporary .moa folder.
+ * Best-effort integration with dsh-time-machine to create a shadow Git checkpoint
+ * before candidate promotion overwrites files in the project workspace.
  */
+export async function createPrePromotionCheckpoint(baseDir, candidateTarget, options = {}) {
+  if (!baseDir || options.checkpoint === false) return null
+  if (typeof options.checkpointFn === 'function') {
+    const res = await bestEffort('custom checkpointFn', () => options.checkpointFn(baseDir, candidateTarget))
+    return res || null
+  }
+
+  const label = options.checkpointLabel || `moa-pre-promotion: candidate-${candidateTarget}`
+  const port = options.port || process.env.DSH_PORT || process.env.PORT || 3000
+  const endpoint = options.timeMachineUrl || `http://127.0.0.1:${port}/dsh-time-machine/create`
+
+  const snap = await bestEffort('dsh-time-machine pre-promotion checkpoint', async () => {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-dsh-trusted': '1' },
+      body: JSON.stringify({ label, cwd: baseDir }),
+      signal: AbortSignal.timeout(options.timeoutMs ?? 1500),
+    })
+    if (res.ok) {
+      const data = await res.json()
+      return data?.snapshot || data || null
+    }
+    return null
+  })
+  return snap || null
+}
+
 export async function promoteCandidateWorkspace(baseDir, winningIndex, options = { keepMoa: false }) {
   if (!baseDir || winningIndex === null || winningIndex === undefined) return []
 
-  const winningDir = path.join(baseDir, '.moa', `candidate-${winningIndex}`)
+  const targetStr = String(winningIndex).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')
+  const winningDir = assertPathContained(moaRoot, sub)
 
   try {
     const entries = await getFilesRecursively(winningDir)
@@ -262,20 +273,21 @@ export async function promoteCandidateWorkspace(baseDir, winningIndex, options =
       return []
     }
 
+    const checkpoint = await createPrePromotionCheckpoint(baseDir, winningIndex, options)
+
     const promoted = []
     for (const rel of entries) {
-      const srcPath = path.join(winningDir, rel)
-      const destPath = path.join(baseDir, rel)
+      if (!isSafeRelativePath(rel)) continue
+      const srcPath = assertPathContained(winningDir, rel)
+      const destPath = assertPathContained(baseDir, rel)
 
       await fs.mkdir(path.dirname(destPath), { recursive: true })
       await fs.copyFile(srcPath, destPath)
       promoted.push(rel)
     }
 
-    if (!options.keepMoa) {
-      // Clean up temporary .moa folder
-      await fs.rm(moaRoot, { recursive: true, force: true })
-    }
+    if (checkpoint) promoted.checkpoint = checkpoint
+    if (!options.keepMoa) await fs.rm(moaRoot, { recursive: true, force: true })
 
     return promoted
   } catch (err) {
@@ -300,7 +312,7 @@ async function getFilesRecursively(dir) {
   try {
     const stat = await fs.stat(dir)
     if (!stat.isDirectory()) return []
-  } catch (statErr) {
+  } catch {
     return []
   }
 
@@ -311,13 +323,10 @@ async function getFilesRecursively(dir) {
       for (const item of list) {
         const rel = relPrefix ? `${relPrefix}/${item.name}` : item.name
         const full = path.join(current, item.name)
-        if (item.isDirectory()) {
-          await scan(full, rel)
-        } else if (item.isFile()) {
-          results.push(rel)
-        }
+        if (item.isDirectory()) await scan(full, rel)
+        else if (item.isFile()) results.push(rel)
       }
-    } catch (readErr) {
+    } catch {
       return
     }
   }
@@ -325,10 +334,8 @@ async function getFilesRecursively(dir) {
   return results
 }
 
-
 /**
  * Verifies the syntactic validity of generated code files.
- * Uses Node.js in-memory vm.Script for JS (with ES module export/import transformation) and JSON.parse for JSON.
  */
 export function verifyFileSyntax(files = []) {
   if (!Array.isArray(files)) return []
@@ -369,3 +376,150 @@ export function verifyFileSyntax(files = []) {
 
   return warnings
 }
+
+/**
+ * Reads all files from a candidate workspace (.moa/candidate-N or .moa/curator-synthesis)
+ */
+export async function readCandidateFiles(baseDir, candidateTarget) {
+  if (!baseDir || candidateTarget === undefined || candidateTarget === null) return []
+  const targetStr = String(candidateTarget).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')
+
+  let targetDir
+  try {
+    targetDir = assertPathContained(moaRoot, sub)
+  } catch {
+    return []
+  }
+
+  try {
+    const relFiles = await getFilesRecursively(targetDir)
+    const result = []
+    for (const rel of relFiles) {
+      if (!isSafeRelativePath(rel)) continue
+      try {
+        const fullPath = assertPathContained(targetDir, rel)
+        const content = await fs.readFile(fullPath, 'utf8')
+        result.push({
+          relativePath: rel,
+          content,
+          size: Buffer.byteLength(content, 'utf8'),
+        })
+      } catch {
+        // file read error best-effort
+      }
+    }
+    return result
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Computes a line-by-line diff between two text strings using LCS with
+ * common prefix and suffix trimming for optimal O(delta) performance.
+ * Returns an array of diff items: { type: 'same' | 'added' | 'removed', line: string, oldNum?: number, newNum?: number }
+ */
+export function computeLineDiff(oldText = '', newText = '') {
+  const oldLines = typeof oldText === 'string' ? oldText.split(/\r?\n/) : []
+  const newLines = typeof newText === 'string' ? newText.split(/\r?\n/) : []
+
+  const n = oldLines.length
+  const m = newLines.length
+
+  if (n === 0 && m === 0) return []
+  if (oldText === newText) {
+    return oldLines.map((line, idx) => ({
+      type: 'same',
+      line,
+      oldNum: idx + 1,
+      newNum: idx + 1,
+    }))
+  }
+
+  // 1. Trim common prefix
+  let start = 0
+  while (start < n && start < m && oldLines[start] === newLines[start]) {
+    start++
+  }
+
+  // 2. Trim common suffix
+  let oldEnd = n - 1
+  let newEnd = m - 1
+  while (oldEnd >= start && newEnd >= start && oldLines[oldEnd] === newLines[newEnd]) {
+    oldEnd--
+    newEnd--
+  }
+
+  const prefixItems = []
+  for (let k = 0; k < start; k++) {
+    prefixItems.push({ type: 'same', line: oldLines[k], oldNum: k + 1, newNum: k + 1 })
+  }
+
+  const suffixItems = []
+  const suffixLen = (n - 1) - oldEnd
+  for (let k = 0; k < suffixLen; k++) {
+    const oNum = oldEnd + 1 + k + 1
+    const nNum = newEnd + 1 + k + 1
+    suffixItems.push({ type: 'same', line: oldLines[oldEnd + 1 + k], oldNum: oNum, newNum: nNum })
+  }
+
+  const subOld = oldLines.slice(start, oldEnd + 1)
+  const subNew = newLines.slice(start, newEnd + 1)
+  const subN = subOld.length
+  const subM = subNew.length
+
+  const middleItems = []
+
+  if (subN === 0) {
+    for (let j = 0; j < subM; j++) {
+      middleItems.push({ type: 'added', line: subNew[j], newNum: start + j + 1 })
+    }
+  } else if (subM === 0) {
+    for (let i = 0; i < subN; i++) {
+      middleItems.push({ type: 'removed', line: subOld[i], oldNum: start + i + 1 })
+    }
+  } else if (subN > 2000 || subM > 2000) {
+    for (let i = 0; i < subN; i++) {
+      middleItems.push({ type: 'removed', line: subOld[i], oldNum: start + i + 1 })
+    }
+    for (let j = 0; j < subM; j++) {
+      middleItems.push({ type: 'added', line: subNew[j], newNum: start + j + 1 })
+    }
+  } else {
+    const dp = Array.from({ length: subN + 1 }, () => new Uint16Array(subM + 1))
+    for (let i = 0; i < subN; i++) {
+      for (let j = 0; j < subM; j++) {
+        if (subOld[i] === subNew[j]) {
+          dp[i + 1][j + 1] = dp[i][j] + 1
+        } else {
+          dp[i + 1][j + 1] = Math.max(dp[i + 1][j], dp[i][j + 1])
+        }
+      }
+    }
+
+    let i = subN
+    let j = subM
+    const stack = []
+
+    while (i > 0 || j > 0) {
+      if (i > 0 && j > 0 && subOld[i - 1] === subNew[j - 1]) {
+        stack.push({ type: 'same', line: subOld[i - 1], oldNum: start + i, newNum: start + j })
+        i--
+        j--
+      } else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+        stack.push({ type: 'added', line: subNew[j - 1], newNum: start + j })
+        j--
+      } else if (i > 0 && (j === 0 || dp[i][j - 1] < dp[i - 1][j])) {
+        stack.push({ type: 'removed', line: subOld[i - 1], oldNum: start + i })
+        i--
+      }
+    }
+
+    middleItems.push(...stack.reverse())
+  }
+
+  return [...prefixItems, ...middleItems, ...suffixItems]
+}

package/lib/history.js

@@ -15,6 +15,13 @@ const DEFAULT_HISTORY_FILE = path.join(DEFAULT_HISTORY_DIR, 'moa-history.jsonl')
 /** Max history file size before rotation (10 MB) */
 export const MAX_HISTORY_BYTES = 10 * 1024 * 1024
 
+/** In-memory cache for leaderboard and parsed analytics */
+let _historyCache = null
+
+export function invalidateHistoryCache() {
+  _historyCache = null
+}
+
 function getHistoryFilePath(customDir) {
   if (customDir) {
     return path.join(customDir, '.moa-history.jsonl')
@@ -36,6 +43,7 @@ export function rotateHistoryFileIfNeeded(filePath = DEFAULT_HISTORY_FILE, maxBy
         try { fs.unlinkSync(backupPath) } catch (unlinkErr) { /* backup unlink best-effort */ }
       }
       fs.renameSync(filePath, backupPath)
+      invalidateHistoryCache()
       return true
     }
   } catch (err) {
@@ -97,6 +105,7 @@ export function recordMoaRun(record, filePath = DEFAULT_HISTORY_FILE) {
     const entry = normalizeRunRecord(record)
     const line = JSON.stringify(entry) + '\n'
     fs.appendFileSync(filePath, line, 'utf8')
+    invalidateHistoryCache()
     return entry
   } catch (err) {
     console.warn('[dsh-moa] Failed to record run to history:', err)
@@ -117,6 +126,7 @@ export async function recordMoaRunAsync(record, filePath = DEFAULT_HISTORY_FILE)
     const entry = normalizeRunRecord(record)
     const line = JSON.stringify(entry) + '\n'
     await fs.promises.appendFile(filePath, line, 'utf8')
+    invalidateHistoryCache()
     return entry
   } catch (err) {
     console.warn('[dsh-moa] Failed to async-record run to history:', err)
@@ -124,6 +134,49 @@ export async function recordMoaRunAsync(record, filePath = DEFAULT_HISTORY_FILE)
   }
 }
 
+/**
+ * Reads lines from the end of a file in reverse order in chunks.
+ * Avoids loading multi-megabyte JSONL files into V8 heap strings.
+ */
+export function readTailLinesSync(filePath, countNeeded = 50) {
+  const CHUNK_SIZE = 64 * 1024
+  const fd = fs.openSync(filePath, 'r')
+  try {
+    const stat = fs.fstatSync(fd)
+    let pos = stat.size
+    let remainder = ''
+    const collectedLines = []
+
+    while (pos > 0 && collectedLines.length < countNeeded) {
+      const bytesToRead = Math.min(CHUNK_SIZE, pos)
+      pos -= bytesToRead
+      const buf = Buffer.alloc(bytesToRead)
+      fs.readSync(fd, buf, 0, bytesToRead, pos)
+      const chunkStr = buf.toString('utf8') + remainder
+      const lines = chunkStr.split('\n')
+      if (pos > 0) {
+        remainder = lines.shift()
+      } else {
+        remainder = ''
+      }
+
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim()
+        if (trimmed) {
+          collectedLines.push(trimmed)
+          if (collectedLines.length >= countNeeded) break
+        }
+      }
+    }
+    if (remainder && remainder.trim() && collectedLines.length < countNeeded) {
+      collectedLines.push(remainder.trim())
+    }
+    return collectedLines
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
 /**
  * Reads history runs with pagination (latest first).
  */
@@ -133,13 +186,34 @@ export function getMoaHistory(limit = 20, offset = 0, filePath = DEFAULT_HISTORY
       return { total: 0, runs: [] }
     }
 
-    const raw = fs.readFileSync(filePath, 'utf8')
-    const lines = raw.trim().split('\n').filter(Boolean)
-    const total = lines.length
+    const stat = fs.statSync(filePath)
+    const needed = offset + limit
+
+    // For files under 64KB, straightforward full-read is fast and keeps exact total
+    if (stat.size <= 65536) {
+      const raw = fs.readFileSync(filePath, 'utf8')
+      const lines = raw.trim().split('\n').filter(Boolean)
+      const total = lines.length
+
+      const sliced = lines
+        .slice(Math.max(0, total - offset - limit), total - offset)
+        .reverse()
+        .map((line) => {
+          try {
+            return JSON.parse(line)
+          } catch {
+            return null
+          }
+        })
+        .filter(Boolean)
+
+      return { total, runs: sliced }
+    }
 
-    const sliced = lines
-      .slice(Math.max(0, total - offset - limit), total - offset)
-      .reverse()
+    // For larger files: read only tail lines backwards to avoid splitting 10MB in memory
+    const tailLines = readTailLinesSync(filePath, needed)
+    const pageLines = tailLines.slice(offset, offset + limit)
+    const runs = pageLines
       .map((line) => {
         try {
           return JSON.parse(line)
@@ -149,7 +223,12 @@ export function getMoaHistory(limit = 20, offset = 0, filePath = DEFAULT_HISTORY
       })
       .filter(Boolean)
 
-    return { total, runs: sliced }
+    let total = _historyCache?.totalCount
+    if (typeof total !== 'number') {
+      total = tailLines.length >= needed ? Math.max(tailLines.length, Math.round(stat.size / 250)) : tailLines.length
+    }
+
+    return { total, runs }
   } catch (err) {
     console.warn('[dsh-moa] Failed to read history:', err)
     return { total: 0, runs: [] }
@@ -158,6 +237,7 @@ export function getMoaHistory(limit = 20, offset = 0, filePath = DEFAULT_HISTORY
 
 /**
  * Calculates win-rate leaderboard and model performance statistics across history.
+ * Employs in-memory caching keyed by file mtime and size for O(1) repeated queries.
  */
 export function getMoaLeaderboard(filePath = DEFAULT_HISTORY_FILE, options = {}) {
   try {
@@ -165,13 +245,35 @@ export function getMoaLeaderboard(filePath = DEFAULT_HISTORY_FILE, options = {})
       return { totalRuns: 0, models: [] }
     }
 
+    const stat = fs.statSync(filePath)
+    const presetFilter = typeof options === 'string' ? options : (options?.presetFilter || options?.preset || null)
+    const filterKey = presetFilter || 'all'
+
+    if (
+      _historyCache &&
+      _historyCache.filePath === filePath &&
+      _historyCache.mtimeMs === stat.mtimeMs &&
+      _historyCache.size === stat.size
+    ) {
+      if (_historyCache.leaderboards.has(filterKey)) {
+        return _historyCache.leaderboards.get(filterKey)
+      }
+    } else {
+      _historyCache = {
+        filePath,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        leaderboards: new Map(),
+        totalCount: null,
+      }
+    }
+
     const raw = fs.readFileSync(filePath, 'utf8')
     const lines = raw.trim().split('\n').filter(Boolean)
     const totalRuns = lines.length
+    _historyCache.totalCount = totalRuns
 
     const modelStats = new Map()
-    const presetFilter = typeof options === 'string' ? options : (options?.presetFilter || options?.preset || null)
-
     let filteredRuns = 0
     for (const line of lines) {
       try {
@@ -198,6 +300,7 @@ export function getMoaLeaderboard(filePath = DEFAULT_HISTORY_FILE, options = {})
             }
             const st = modelStats.get(key)
             st.runs += 1
+
             const inTok = cand.usage?.inputTokens || 0
             const outTok = cand.usage?.outputTokens || 0
             st.totalTokens += inTok + outTok
@@ -222,7 +325,13 @@ export function getMoaLeaderboard(filePath = DEFAULT_HISTORY_FILE, options = {})
       }))
       .sort((a, b) => b.wins - a.wins || b.winRate - a.winRate)
 
-    return { totalRuns: presetFilter && presetFilter !== 'all' ? filteredRuns : totalRuns, models, preset: presetFilter }
+    const result = {
+      totalRuns: presetFilter && presetFilter !== 'all' ? filteredRuns : totalRuns,
+      models,
+      preset: presetFilter,
+    }
+    _historyCache.leaderboards.set(filterKey, result)
+    return result
   } catch (err) {
     console.warn('[dsh-moa] Failed to calculate leaderboard:', err)
     return { totalRuns: 0, models: [] }
@@ -303,6 +412,7 @@ export function candidatesForHistory(referenceOutputs) {
   return (referenceOutputs || []).map((r) => ({
     provider: r.slot?.provider || "",
     model: r.slot?.model || "",
+    role: r.role_persona || r.slot?.role_persona || r.slot?.role || "general",
     files: (r.files || []).map((f) => f.relativePath),
     usage: r.usage || { inputTokens: 0, outputTokens: 0 },
     costUsd: r.costUsd || 0,

package/lib/moa-candidates.js

@@ -81,8 +81,9 @@ export async function runReferencesParallel(references, messages, options = {},
 
   references.forEach((slot, i) => {
     const label = slotLabel(slot)
-    const persona = slot?.role_persona && ROLE_PERSONA_PROMPTS[slot.role_persona]
-      ? `\n\n${ROLE_PERSONA_PROMPTS[slot.role_persona]}`
+    const role = slot?.role_persona || slot?.role || 'general'
+    const persona = (role && ROLE_PERSONA_PROMPTS[role])
+      ? `\n\n${ROLE_PERSONA_PROMPTS[role]}`
       : ''
     const slotMessages = [{ role: 'system', content: systemPrompt + persona }, ...advisoryMessages]
 
@@ -103,7 +104,12 @@ export async function runReferencesParallel(references, messages, options = {},
         )
 
         const timeoutPromise = new Promise((_, reject) => {
-          const timer = setTimeout(() => reject(new Error(`Timeout after ${Math.round(timeoutMs / 1000)}s`)), timeoutMs)
+          const timer = setTimeout(() => {
+            bestEffort('candidate timeout abort', () => {
+              abortControllers[i].abort(new Error(`Timeout after ${Math.round(timeoutMs / 1000)}s`))
+            })
+            reject(new Error(`Timeout after ${Math.round(timeoutMs / 1000)}s`))
+          }, timeoutMs)
           timer.unref?.()
           abortControllers[i].signal.addEventListener('abort', () => clearTimeout(timer), { once: true })
         })
@@ -127,6 +133,7 @@ export async function runReferencesParallel(references, messages, options = {},
           index: i + 1,
           slot,
           label,
+          role_persona: role,
           text,
           usage: costInfo,
           costUsd: costInfo.costUsd,
@@ -143,6 +150,7 @@ export async function runReferencesParallel(references, messages, options = {},
           index: i + 1,
           slot,
           label,
+          role_persona: role,
           text: `[Model ${label} error: ${errMsg}]`,
           usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0 },
           costUsd: 0,

package/lib/moa-prompts.js

@@ -190,7 +190,9 @@ At the end, add a note that the user can answer briefly (e.g.: "1, 2, dark theme
 export function buildPeerCritiquePrompt(userPrompt, myProposal, otherProposals = [], isBlind = true) {
   const othersText = otherProposals
     .map((p, idx) => {
-      const label = isBlind ? `Candidate ${idx + 1}` : (p.label || `Candidate ${idx + 1}`)
+      const role = p.role_persona || p.slot?.role_persona || p.role || p.slot?.role
+      const roleNote = role && role !== 'general' ? ` [Focus: ${role}]` : ''
+      const label = isBlind ? `Candidate ${idx + 1}${roleNote}` : `${p.label || `Candidate ${idx + 1}`}${roleNote}`
       let text = p.text || ''
       if (text.length > 3000) {
         text = stripOrSummarizeCode(text)
@@ -230,10 +232,12 @@ export function buildCuratorSynthesisPrompt(userPrompt, referenceOutputs = [], j
       if (textContent.length > 3000) {
         textContent = stripOrSummarizeCode(textContent)
       }
+      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 header = isBlind
-        ? `Candidate ${i + 1}:${syntaxNote}${fileSummary}`
-        : `Candidate ${i + 1} — ${r.label}:${syntaxNote}${fileSummary}`
+        ? `Candidate ${i + 1}${roleNote}:${syntaxNote}${fileSummary}`
+        : `Candidate ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${fileSummary}`
       return `${header}\n${textContent}`
     })
     .join('\n\n')
@@ -297,10 +301,12 @@ export function buildSynthesisPrompt(userPrompt, referenceOutputs = [], judgeCri
       if (textContent.length > 3000) {
         textContent = stripOrSummarizeCode(textContent)
       }
+      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 header = isBlind
-        ? `Reference ${i + 1}:${syntaxNote}${fileSummary}`
-        : `Reference ${i + 1} — ${r.label}:${syntaxNote}${fileSummary}`
+        ? `Reference ${i + 1}${roleNote}:${syntaxNote}${fileSummary}`
+        : `Reference ${i + 1} — ${r.label}${roleNote}:${syntaxNote}${fileSummary}`
       return `${header}\n${textContent}`
     })
     .join('\n\n')

package/lib/moa-runner.js

@@ -307,7 +307,11 @@ export async function runMoAPipeline({
     const r2Promises = successfulRefs.map(async (cand) => {
       const opponents = successfulRefs
         .filter((c) => c.index !== cand.index)
-        .map((c) => ({ label: isBlindEvaluation ? `Candidate ${c.index}` : c.label, text: c.text }))
+        .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 = referenceModels[cand.index - 1] || { provider: cand.provider, model: cand.model }

package/lib/routes.js

@@ -8,10 +8,13 @@ import {
   getMoaRunById,
   exportMoaHistory,
 } from './history.js'
-import { promoteCandidateWorkspace } from './file-workspace.js'
+import { promoteCandidateWorkspace, readCandidateFiles, computeLineDiff, isSafeRelativePath } from './file-workspace.js'
 import { isSafeWriteRequest } from './updater.js'
 import { runMoAPipeline } from './moa-runner.js'
 
+let _modelsCache = { timestamp: 0, models: [] }
+const MODELS_CACHE_TTL = 60 * 1000
+
 function writeJson(res, status, body) {
   res.writeHead(status, {
     'Content-Type': 'application/json; charset=utf-8',
@@ -60,6 +63,11 @@ ctx.effect(() => {
       kind: 'exact',
       path: '/dsh-moa/models',
       handler: async (_req, res) => {
+        if (_modelsCache.models.length > 0 && Date.now() - _modelsCache.timestamp < MODELS_CACHE_TTL) {
+          writeJson(res, 200, { ok: true, models: _modelsCache.models, cached: true })
+          return
+        }
+
         const result = []
         const seen = new Set()
 
@@ -87,18 +95,23 @@ ctx.effect(() => {
           try {
             if (typeof ctx.llm.listConfigurableProviders === 'function') {
               const cProvs = ctx.llm.listConfigurableProviders() || []
-              for (const cp of cProvs) {
+              const queries = cProvs.map(async (cp) => {
                 const cpId = cp.provider || cp.id
-                if (cpId && typeof ctx.llm.listModels === 'function') {
-                  try {
-                    const mList = await ctx.llm.listModels(cpId)
-                    for (const m of (mList || [])) {
-                      const mId = typeof m === 'string' ? m : (m.id || m.model || m.name)
-                      if (mId) add(cpId, mId)
-                    }
-                  } catch (mErr) { /* listModels best-effort */ }
+                if (!cpId || typeof ctx.llm.listModels !== 'function') return
+                try {
+                  const mList = await Promise.race([
+                    ctx.llm.listModels(cpId),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
+                  ])
+                  for (const m of (mList || [])) {
+                    const mId = typeof m === 'string' ? m : (m?.id || m?.model || m?.name)
+                    if (mId) add(cpId, mId)
+                  }
+                } catch {
+                  /* provider query timeout or error handled best-effort */
                 }
-              }
+              })
+              await Promise.allSettled(queries)
             }
           } catch (e) {
             console.warn('[dsh-moa] ctx.llm.listConfigurableProviders error:', e)
@@ -136,6 +149,7 @@ ctx.effect(() => {
           console.warn('[dsh-moa] Error reading settings:', e)
         }
 
+        _modelsCache = { timestamp: Date.now(), models: result }
         writeJson(res, 200, { ok: true, models: result })
       },
     })
@@ -288,7 +302,7 @@ ctx.effect(() => {
           }
           const cwd = body?.cwd || process.cwd()
           const promotedFiles = await promoteCandidateWorkspace(cwd, candidateIndex, { keepMoa: true })
-          writeJson(res, 200, { ok: true, candidateIndex, promotedFiles })
+          writeJson(res, 200, { ok: true, candidateIndex, promotedFiles, checkpoint: promotedFiles?.checkpoint || null })
         } catch (err) {
           writeJson(res, 500, { ok: false, error: err?.message || String(err) })
         }
@@ -296,6 +310,63 @@ ctx.effect(() => {
     })
   }, 'dsh-moa: promote candidate route')
 
+  // Route: /dsh-moa/diff (Candidate Diff Viewer)
+  ctx.effect(() => {
+    return ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-moa/diff',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') {
+          writeJson(res, 405, { ok: false, error: 'GET required' })
+          return
+        }
+        try {
+          const u = new URL(req.url, 'http://localhost')
+          const cwd = u.searchParams.get('cwd') || process.cwd()
+          const sanitizeTarget = (val, def) => {
+            const clean = String(val || '').trim().replace(/[^a-zA-Z0-9_-]/g, '')
+            return clean || def
+          }
+          const from = sanitizeTarget(u.searchParams.get('from'), '1')
+          const to = sanitizeTarget(u.searchParams.get('to'), 'curator-synthesis')
+          const rawFile = u.searchParams.get('file') || ''
+          const file = (rawFile && isSafeRelativePath(rawFile)) ? rawFile : ''
+
+          const fromFiles = await readCandidateFiles(cwd, from)
+          const toFiles = await readCandidateFiles(cwd, to)
+
+          // Collect all unique file paths
+          const allPaths = Array.from(new Set([
+            ...fromFiles.map((f) => f.relativePath),
+            ...toFiles.map((f) => f.relativePath),
+          ])).sort()
+
+          const targetPath = file || allPaths[0] || ''
+          const fromItem = fromFiles.find((f) => f.relativePath === targetPath)
+          const toItem = toFiles.find((f) => f.relativePath === targetPath)
+
+          const diff = targetPath
+            ? computeLineDiff(fromItem?.content || '', toItem?.content || '')
+            : []
+
+          writeJson(res, 200, {
+            ok: true,
+            from,
+            to,
+            files: allPaths,
+            selectedFile: targetPath,
+            fromSize: fromItem?.size || 0,
+            toSize: toItem?.size || 0,
+            diff,
+          })
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err?.message || String(err) })
+        }
+      },
+    })
+  }, 'dsh-moa: candidate diff route')
+
+
   // Route: /dsh-moa/history/export
   ctx.effect(() => {
     return ctx.webServer.register({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-moa",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Mixture of Agents (MoA) plugin for DeepSeek Harness with /moa slash command",
   "type": "module",
   "main": "lib/index.js",
@@ -14,10 +14,13 @@
     "lib/",
     "cordis.patch.yml",
     "README.md",
+    "README.ru.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build:client": "node scripts/build-client.mjs"
   },
   "keywords": [
     "dsh",