@goodandready/dsh-moa 0.2.37 → 0.2.39

package/README.md

@@ -140,7 +140,7 @@ Configure your models in `Settings → Plugins → Mixture of Agents`:
 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.
+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 is blocked (fail-closed) to protect uncheckpointed workspace files against unintended overwrites (override with `force: true` only when automated checkpoints are explicitly unneeded).
 
 ### 9. Automated Test Execution Gate
 When `test_gate_enabled: true` and `test_command` (e.g. `npm test` or `pytest`) are configured, candidate code is executed in an ephemeral sandbox overlay. The judge receives concrete test outcomes, durations, and output logs to ground decisions in objective verification.

package/README.ru.md

@@ -140,7 +140,7 @@ graph TD
 Позволяет визуально сопоставлять построчные различия между решениями моделей-советников и итоговым синтезом судьи прямо в интерфейсе. Поддерживает выбор конкретного файла, подсветку добавленных/удаленных строк и вычисление дельт с помощью легковесного алгоритма LCS без внешних зависимостей.
 
 ### 8. Теневые Git-чекпоинты (`dsh-time-machine`)
-Перед промоушном файлов победителя в корень рабочей области `dsh-moa` автоматически обращается к сервису `dsh-time-machine` для создания снимка (`moa-pre-promotion: candidate-N`). Если плагин недоступен, промоушн штатно продолжается по схеме best-effort.
+Перед промоушном файлов победителя в корень рабочей области `dsh-moa` автоматически обращается к сервису `dsh-time-machine` для создания снимка (`moa-pre-promotion: candidate-N`). Если плагин недоступен или создание снимка завершилось ошибкой, перезапись файлов блокируется во избежание потери несохранённых данных (переопределяется параметром `force: true`, только если создание снимков намеренно отключено).
 
 ### 9. Автоматический шлюз выполнения тестов (Automated Test Execution Gate)
 При включении `test_gate_enabled: true` и указании тестовой команды (`test_command`, например `npm test` или `pytest`) каждый кандидат запускается в изолированном оверлейном окружении. Судья получает объективный вердикт с кодами возврата, временем исполнения и логами тестов до вынесения итогового решения.

package/README.zh.md

@@ -140,7 +140,7 @@ graph TD
 直接在界面中可视化对比顾问方案之间以及顾问与裁判综合方案之间的逐行差异。支持文件筛选、增删改高亮，基于纯 JavaScript LCS 差异算法，零第三方依赖。
 
 ### 8. 提升前 Git 快照检查点 (`dsh-time-machine`)
-在将胜出候选者的文件提升并覆盖至项目根目录前，`dsh-moa` 自动调用本地 `dsh-time-machine` 建立影子 Git 检查点 (`moa-pre-promotion: candidate-N`)。如未安装则静默回退，不阻断提升流程。
+在将胜出候选者的文件提升并覆盖至项目根目录前，`dsh-moa` 自动调用本地 `dsh-time-machine` 建立影子 Git 检查点 (`moa-pre-promotion: candidate-N`)。如 `dsh-time-machine` 未安装或无法访问，文件提升将被阻断以防止未备份的项目文件被意外覆盖（仅在明确不需要检查点时可通过 `force: true` 覆盖）。
 
 ### 18. 平滑降级与本地容灾恢复 (Local Fallback Resilience)
 当 `local_fallback_enabled: true` 时，因网络中断、超时或速率限制（429/500）而失败的候选模型会自动使用配置的本地模型（Ollama / MiniPC）恢复。每个后备模型都拥有独立的超时执行配额与关联主 turn signal 的隔离取消控制器，防止云端超时耗尽本地恢复时间。同时严格检测终止错误与流中断，确保安全容灾且杜绝已取消 turn 的延迟文件提升。

package/lib/file-workspace.js

@@ -2,7 +2,12 @@ import { bestEffort } from './best-effort.js'
 import { logger } from './logger.js'
 import vm from 'node:vm'
 import fs from 'node:fs/promises'
+import fsSync from 'node:fs'
 import path from 'node:path'
+/**
+ * In-memory serialization mutex to prevent interleaved promotions to the same baseDir.
+ */
+const promotionLocks = new Map()
 
 /**
  * Validates that an untrusted relative path is safe and does not traverse upwards.
@@ -12,12 +17,12 @@ export function isSafeRelativePath(relPath) {
   const trimmed = relPath.trim()
   if (!trimmed || path.isAbsolute(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\')) return false
   const normalized = path.normalize(trimmed)
-  if (!normalized || normalized === '.' || normalized.startsWith('..') || path.isAbsolute(normalized)) return false
-  return true
+  return !(!normalized || normalized === '.' || normalized.startsWith('..') || path.isAbsolute(normalized))
 }
 
 /**
- * Asserts that a resolved path is strictly contained within baseDir.
+ * Asserts that a resolved path is strictly contained within baseDir, verifying
+ * both lexical boundaries and physical canonical symlink resolution.
  */
 export function assertPathContained(baseDir, subPath) {
   const resolvedBase = path.resolve(baseDir)
@@ -25,18 +30,66 @@ export function assertPathContained(baseDir, subPath) {
   if (resolvedTarget !== resolvedBase && !resolvedTarget.startsWith(resolvedBase + path.sep)) {
     throw new Error(`Path traversal violation: "${subPath}" escapes base directory "${baseDir}"`)
   }
+
+  try {
+    const realBase = fsSync.realpathSync(resolvedBase)
+    try {
+      const realTarget = fsSync.realpathSync(resolvedTarget)
+      if (realTarget !== realBase && !realTarget.startsWith(realBase + path.sep)) {
+        throw new Error(`Path traversal violation: symlink "${subPath}" resolves outside "${baseDir}"`)
+      }
+    } catch (targetErr) {
+      if (targetErr?.code === 'ENOENT') {
+        let curr = path.dirname(resolvedTarget)
+        while (curr === resolvedBase || curr.startsWith(resolvedBase + path.sep)) {
+          try {
+            const realCurr = fsSync.realpathSync(curr)
+            if (realCurr !== realBase && !realCurr.startsWith(realBase + path.sep)) {
+              throw new Error(`Path traversal violation: symlink ancestor in "${subPath}" resolves outside "${baseDir}"`)
+            }
+            break
+          } catch (ancestorErr) {
+            if (ancestorErr?.code === 'ENOENT') {
+              const parent = path.dirname(curr)
+              if (parent === curr) break
+              curr = parent
+              continue
+            }
+            throw ancestorErr
+          }
+        }
+      } else {
+        throw targetErr
+      }
+    }
+  } catch (baseErr) {
+    if (baseErr?.message?.startsWith('Path traversal violation')) throw baseErr
+  }
+
   return resolvedTarget
 }
 
+/**
+ * Resolves directory paths for candidate sandboxes with optional runId scoping.
+ */
+export function resolveCandidateFolder(baseDir, candidateTarget, options = {}) {
+  const targetStr = String(candidateTarget ?? 1).trim()
+  const sanitizedTarget = targetStr.replace(/[^a-zA-Z0-9_-]/g, '')
+  const sub = /^\d+$/.test(sanitizedTarget) ? `candidate-${sanitizedTarget}` : (sanitizedTarget || 'candidate-1')
+  const rawRunId = typeof options === 'string' ? options : options?.runId
+  const safeRunId = rawRunId ? String(rawRunId).trim().replace(/[^a-zA-Z0-9_-]/g, '') : null
+  const moaRoot = path.join(baseDir, '.moa')
+  const runRoot = safeRunId ? assertPathContained(moaRoot, safeRunId) : moaRoot
+  return { moaRoot, runRoot, safeRunId, sub, candidateDir: assertPathContained(runRoot, sub) }
+}
+
 /**
  * Parses markdown code blocks that specify file paths.
  */
 export function extractFileBlocks(text) {
   if (!text || typeof text !== 'string') return []
-
   const files = []
   const seenPaths = new Set()
-
   const addFile = (rawPath, fileContent) => {
     if (rawPath && isSafeRelativePath(rawPath) && !seenPaths.has(rawPath)) {
       seenPaths.add(rawPath)
@@ -44,24 +97,19 @@ export function extractFileBlocks(text) {
     }
   }
 
-  // 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 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: single anonymous code block if it contains complete HTML
   if (files.length === 0) {
     const htmlBlockRegex = /```(?:html)?[\r\n]+([\s\S]*?)```/gi
     let htmlMatch
@@ -73,7 +121,6 @@ export function extractFileBlocks(text) {
       }
     }
   }
-
   return files
 }
 
@@ -99,13 +146,8 @@ export function formatProjectContext(projectFiles = [], options = {}) {
 
 export async function collectProjectContext(baseDir, maxCharBudget = 16000) {
   if (!baseDir) return { files: [], totalChars: 0, skippedFiles: 0, skippedList: [] }
-
   const ignoreDirs = new Set(['node_modules', '.git', '.moa', '.worktrees', 'dist', 'build', '.dsh', '.next', '.nuxt', '.cache', 'coverage', '.turbo', '.idea', '.vscode'])
-  const codeExts = new Set([
-    '.html', '.htm', '.css', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx',
-    '.vue', '.svelte', '.json', '.py', '.md', '.txt', '.sh', '.yaml', '.yml',
-  ])
-
+  const codeExts = new Set(['.html', '.htm', '.css', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.json', '.py', '.md', '.txt', '.sh', '.yaml', '.yml'])
   const collected = []
   let totalChars = 0
   let skippedFiles = 0
@@ -173,57 +215,48 @@ export function isRefinementTask(userPrompt = '', projectFiles = null) {
   const p = userPrompt.toLowerCase().trim()
   if (!p) return false
 
-  // Greenfield creation phrases - ALWAYS fresh task
-  const freshPhrases = [
-    'from scratch', 'new project', 'new app', 'create a new', 'build a new', 'generate a new',
-    '从头开始', '新建项目', '创建项目', '新应用', '新建应用',
-    'с нуля', 'новый проект', 'новое приложение', 'создай проект', 'создай приложение', 'создай игру', 'создай сервис',
-    'сделай проект', 'сделай приложение', 'сделай игру',
-  ]
-  if (freshPhrases.some((phrase) => p.includes(phrase))) {
-    return false
-  }
-
-  // Modification keywords
-  const modKeywords = [
-    'add', 'change', 'update', 'fix', 'modify', 'refactor', 'improve', 'enhance', 'adjust',
-    'style', 'css', 'color', 'theme', 'bug',
-    '添加', '修改', '更新', '修复', '重构', '改进', '调整', '样式', '颜色', '主题',
-    'добавь', 'измени', 'поменяй', 'исправь', 'обнови', 'переделай', 'доработай', 'удали',
-    'темн', 'светл', 'цвет', 'кнопк', 'баг',
-  ]
+  const freshPhrases = ['from scratch', 'new project', 'new app', 'create a new', 'build a new', 'generate a new', '从头开始', '新建项目', '创建项目', '新应用', '新建应用', 'с нуля', 'новый проект', 'новое приложение', 'создай проект', 'создай приложение', 'создай игру', 'создай сервис', 'сделай проект', 'сделай приложение', 'сделай игру']
+  if (freshPhrases.some((phrase) => p.includes(phrase))) return false
 
+  const modKeywords = ['add', 'change', 'update', 'fix', 'modify', 'refactor', 'improve', 'enhance', 'adjust', 'style', 'css', 'color', 'theme', 'bug', '添加', '修改', '更新', '修复', '重构', '改进', '调整', '样式', '颜色', '主题', 'добавь', 'измени', 'поменяй', 'исправь', 'обнови', 'переделай', 'доработай', 'удали', 'темн', 'светл', 'цвет', 'кнопк', 'баг']
   return modKeywords.some((kw) => p.includes(kw))
 }
 
 /**
- * Writes candidate files into an isolated candidate workspace:
- * <baseDir>/.moa/candidate-<index>/
+ * Writes candidate files into an isolated candidate workspace.
+ * Uses atomic staging and swap to prevent stale file accumulation and dirty snapshots.
  */
-export async function writeCandidateWorkspace(baseDir, candidateIndex, files = []) {
+export async function writeCandidateWorkspace(baseDir, candidateIndex, files = [], options = {}) {
   if (!baseDir || !Array.isArray(files) || files.length === 0) return []
+  const { runRoot, sub, candidateDir } = resolveCandidateFolder(baseDir, candidateIndex, options)
+  await fs.mkdir(runRoot, { recursive: true })
 
-  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 tempSub = `.tmp-${sub}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+  const tempCandidateDir = assertPathContained(runRoot, tempSub)
+  await fs.mkdir(tempCandidateDir, { recursive: true })
 
-  const written = []
-  for (const file of files) {
-    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({
-      relativePath: file.relativePath,
-      fullPath,
-      size: Buffer.byteLength(file.content, 'utf8'),
-    })
-  }
+  try {
+    const written = []
+    for (const file of files) {
+      if (!isSafeRelativePath(file.relativePath)) continue
+      const fullPath = assertPathContained(tempCandidateDir, file.relativePath)
+      await fs.mkdir(path.dirname(fullPath), { recursive: true })
+      await fs.writeFile(fullPath, file.content, 'utf8')
+      written.push({
+        relativePath: file.relativePath,
+        fullPath: path.join(candidateDir, file.relativePath),
+        size: Buffer.byteLength(file.content, 'utf8'),
+      })
+    }
 
-  return written
+    if (written.length === 0 && files.length > 0) throw new Error('No valid files could be written to candidate workspace')
+    await fs.rm(candidateDir, { recursive: true, force: true })
+    await fs.rename(tempCandidateDir, candidateDir)
+    return written
+  } catch (err) {
+    await bestEffort('clean tempCandidateDir on error', () => fs.rm(tempCandidateDir, { recursive: true, force: true }))
+    throw err
+  }
 }
 
 /**
@@ -238,8 +271,6 @@ export async function createPrePromotionCheckpoint(baseDir, candidateTarget, opt
   }
 
   const label = options.checkpointLabel || `moa-pre-promotion: candidate-${candidateTarget}`
-
-  // 1. Direct Cordis timeMachineEngine service call if available
   if (options.timeMachineEngine && typeof options.timeMachineEngine.createSnapshot === 'function') {
     const snap = await bestEffort('dsh-time-machine direct service createSnapshot', async () => {
       return await options.timeMachineEngine.createSnapshot(label, { cwd: baseDir })
@@ -247,7 +278,6 @@ export async function createPrePromotionCheckpoint(baseDir, candidateTarget, opt
     if (snap) return snap
   }
 
-  // 2. HTTP endpoint call if port or timeMachineUrl is provided
   const port = options.port || options.webServerPort || process.env.DSH_PORT || process.env.PORT
   if (!port && !options.timeMachineUrl) {
     logger.warn('[dsh-moa] Cannot create pre-promotion checkpoint: webServerPort is unknown and no timeMachineUrl provided')
@@ -255,7 +285,6 @@ export async function createPrePromotionCheckpoint(baseDir, candidateTarget, opt
   }
 
   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',
@@ -272,20 +301,39 @@ export async function createPrePromotionCheckpoint(baseDir, candidateTarget, opt
   return snap || null
 }
 
+/**
+ * Promotes winning candidate workspace files into the base workspace.
+ * Serialized per baseDir and verifies symlink boundaries on promotion.
+ */
 export async function promoteCandidateWorkspace(baseDir, winningIndex, options = { keepMoa: false }) {
   if (!baseDir || winningIndex === null || winningIndex === undefined) return []
 
-  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)
+  const key = path.resolve(baseDir)
+  const prevLock = promotionLocks.get(key) || Promise.resolve()
+  let releaseLock
+  const currentLock = new Promise((resolve) => { releaseLock = resolve })
+  promotionLocks.set(key, currentLock)
+
+  try {
+    await prevLock
+    return await doPromoteCandidateWorkspace(baseDir, winningIndex, options)
+  } finally {
+    releaseLock()
+    if (promotionLocks.get(key) === currentLock) {
+      promotionLocks.delete(key)
+    }
+  }
+}
+
+async function doPromoteCandidateWorkspace(baseDir, winningIndex, options = { keepMoa: false }) {
+  const { runRoot, moaRoot, safeRunId, candidateDir: winningDir } = resolveCandidateFolder(baseDir, winningIndex, options)
+  const cleanupTarget = safeRunId ? runRoot : moaRoot
 
   try {
     const entries = await getFilesRecursively(winningDir)
     if (entries.length === 0) {
       if (!options.keepMoa) {
-        await bestEffort('clean moaRoot on empty candidate', () => fs.rm(moaRoot, { recursive: true, force: true }))
+        await bestEffort('clean empty candidate folder', () => fs.rm(cleanupTarget, { recursive: true, force: true }))
       }
       return []
     }
@@ -298,35 +346,61 @@ export async function promoteCandidateWorkspace(baseDir, winningIndex, options =
     }
 
     const promoted = []
+    const baseReal = await fs.realpath(baseDir).catch(() => path.resolve(baseDir))
+
     for (const rel of entries) {
       if (!isSafeRelativePath(rel)) continue
       const srcPath = assertPathContained(winningDir, rel)
       const destPath = assertPathContained(baseDir, rel)
 
+      try {
+        const destLstat = await fs.lstat(destPath)
+        if (destLstat.isSymbolicLink()) {
+          const destReal = await fs.realpath(destPath)
+          if (destReal !== baseReal && !destReal.startsWith(baseReal + path.sep)) {
+            throw new Error(`Path traversal violation: promotion destination symlink "${rel}" resolves outside "${baseDir}"`)
+          }
+          await fs.unlink(destPath)
+        }
+      } catch (lstatErr) {
+        if (lstatErr?.code !== 'ENOENT') throw lstatErr
+      }
+
       await fs.mkdir(path.dirname(destPath), { recursive: true })
       await fs.copyFile(srcPath, destPath)
       promoted.push(rel)
     }
 
     if (checkpoint) promoted.checkpoint = checkpoint
-    if (!options.keepMoa) await fs.rm(moaRoot, { recursive: true, force: true })
+    if (!options.keepMoa) await fs.rm(cleanupTarget, { recursive: true, force: true })
 
     return promoted
   } catch (err) {
     if (!options.keepMoa) {
-      await bestEffort('clean moaRoot on promote error', () => fs.rm(moaRoot, { recursive: true, force: true }))
+      await bestEffort('clean candidate on promote error', () => fs.rm(cleanupTarget, { recursive: true, force: true }))
     }
     throw err
   }
 }
 
 /**
- * Cleans up any left-over .moa candidate folder.
+ * Cleans up candidate workspaces, optionally scoped to a single runId.
  */
-export async function cleanMoaWorkspaces(baseDir) {
+export async function cleanMoaWorkspaces(baseDir, options = {}) {
   if (!baseDir) return
+  const rawRunId = typeof options === 'string' ? options : options?.runId
+  const safeRunId = rawRunId ? String(rawRunId).trim().replace(/[^a-zA-Z0-9_-]/g, '') : null
   const moaRoot = path.join(baseDir, '.moa')
-  await bestEffort('cleanMoaWorkspaces', () => fs.rm(moaRoot, { recursive: true, force: true }))
+  if (safeRunId) {
+    const runRoot = path.join(moaRoot, safeRunId)
+    await bestEffort('cleanMoaWorkspaces runId', () => fs.rm(runRoot, { recursive: true, force: true }))
+    await bestEffort('clean empty moaRoot', async () => {
+      const remaining = await fs.readdir(moaRoot)
+      if (remaining.length === 0) await fs.rmdir(moaRoot)
+    })
+  } else {
+    await bestEffort('cleanMoaWorkspaces', () => fs.rm(moaRoot, { recursive: true, force: true }))
+  }
 }
 
 async function getFilesRecursively(dir) {
@@ -338,6 +412,13 @@ async function getFilesRecursively(dir) {
     return []
   }
 
+  let realDir
+  try {
+    realDir = await fs.realpath(dir)
+  } catch {
+    realDir = path.resolve(dir)
+  }
+
   async function scan(current, relPrefix = '') {
     let list
     try {
@@ -345,6 +426,18 @@ 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.isSymbolicLink()) {
+          try {
+            const realTarget = await fs.realpath(full)
+            if (realTarget === realDir || realTarget.startsWith(realDir + path.sep)) {
+              const st = await fs.stat(full)
+              if (st.isFile()) results.push(rel)
+            }
+          } catch (err) { logger.debug?.('[dsh-moa] symlink inspect skipped', err) }
+          continue
+        }
+
         if (item.isDirectory()) await scan(full, rel)
         else if (item.isFile()) results.push(rel)
       }
@@ -377,11 +470,7 @@ export function verifyFileSyntax(files = []) {
           .replace(/^([ \t]*)export\s+\*\s+from\s+[^;\n]+;?/gm, '$1')
         new vm.Script(transformed)
       } catch (err) {
-        warnings.push({
-          file: file.relativePath,
-          error: err?.message || String(err),
-          line: err?.lineNumber || 1,
-        })
+        warnings.push({ file: file.relativePath, error: err?.message || String(err), line: err?.lineNumber || 1 })
       }
     } else if (ext === '.json') {
       try {
@@ -395,23 +484,18 @@ export function verifyFileSyntax(files = []) {
       }
     }
   }
-
   return warnings
 }
 
 /**
- * Reads all files from a candidate workspace (.moa/candidate-N or .moa/curator-synthesis)
+ * Reads all files from a candidate workspace (.moa/candidate-N, .moa/curator-synthesis, or scoped under runId).
  */
-export async function readCandidateFiles(baseDir, candidateTarget) {
+export async function readCandidateFiles(baseDir, candidateTarget, options = {}) {
   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)
+    const resolved = resolveCandidateFolder(baseDir, candidateTarget, options)
+    targetDir = resolved.candidateDir
   } catch {
     return []
   }
@@ -419,16 +503,21 @@ export async function readCandidateFiles(baseDir, candidateTarget) {
   try {
     const relFiles = await getFilesRecursively(targetDir)
     const result = []
+    const realTarget = await fs.realpath(targetDir).catch(() => targetDir)
+
     for (const rel of relFiles) {
       if (!isSafeRelativePath(rel)) continue
       try {
         const fullPath = assertPathContained(targetDir, rel)
+        const st = await fs.lstat(fullPath)
+        if (st.isSymbolicLink()) {
+          const realFile = await fs.realpath(fullPath)
+          if (realFile !== realTarget && !realFile.startsWith(realTarget + path.sep)) {
+            continue
+          }
+        }
         const content = await fs.readFile(fullPath, 'utf8')
-        result.push({
-          relativePath: rel,
-          content,
-          size: Buffer.byteLength(content, 'utf8'),
-        })
+        result.push({ relativePath: rel, content, size: Buffer.byteLength(content, 'utf8') })
       } catch {
         // file read error best-effort
       }
@@ -442,95 +531,59 @@ export async function readCandidateFiles(baseDir, candidateTarget) {
 /**
  * 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
-
+  const n = oldLines.length, 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,
-    }))
+    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 (start < n && start < m && oldLines[start] === newLines[start]) start++
+  let oldEnd = n - 1, 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 })
-  }
+  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 })
+    suffixItems.push({ type: 'same', line: oldLines[oldEnd + 1 + k], oldNum: oldEnd + 2 + k, newNum: newEnd + 2 + k })
   }
 
   const subOld = oldLines.slice(start, oldEnd + 1)
   const subNew = newLines.slice(start, newEnd + 1)
-  const subN = subOld.length
-  const subM = subNew.length
-
+  const subN = subOld.length, 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 })
-    }
+    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 })
-    }
+    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 })
-    }
+    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])
-        }
+        dp[i + 1][j + 1] = subOld[i] === subNew[j] ? dp[i][j] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
       }
     }
 
-    let i = subN
-    let j = subM
+    let i = subN, 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--
+        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--
@@ -539,7 +592,6 @@ export function computeLineDiff(oldText = '', newText = '') {
         i--
       }
     }
-
     middleItems.push(...stack.reverse())
   }