@goodandready/dsh-moa 0.2.36 → 0.2.38

package/README.md

@@ -170,7 +170,7 @@ Seamlessly retains synthesized baseline code from prior turns while pruning inte
 `report_generation_enabled` generates comprehensive Markdown & JSON reports detailing candidate metrics, agreement scores, test gate results, and cost breakdowns via `GET /dsh-moa/runs/:id/report`.
 
 ### 18. Graceful Degradation & Local Fallback Resilience
-When `local_fallback_enabled: true`, candidates that fail due to network outages or rate limits (429/500) automatically recover using configured local models (Ollama / MiniPC).
+When `local_fallback_enabled: true`, candidates that fail due to network outages, timeouts, or rate limits (429/500) automatically recover using configured local models (Ollama / MiniPC). Each fallback model operates with an independent execution budget and an isolated controller linked to the parent turn signal, preventing cloud timeouts from starving fallback models. Additionally, terminal errors and aborted streams are strictly classified, ensuring reliable error propagation and failover.
 
 ### 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.

package/README.ru.md

@@ -170,7 +170,7 @@ graph TD
 При включении `report_generation_enabled` генерируется подробный аналитический отчет с матрицей моделей, временами задержек, оценками судей, расходами и результатами тестов. Отчет доступен по API `GET /dsh-moa/runs/:id/report?format=md`.
 
 ### 18. Плавная деградация и локальный фоллбэк
-Опция `local_fallback_enabled` позволяет задать резервные локальные модели (Ollama, vLLM, MiniPC), к которым плагин бесшовно обращается при сбоях сетевых API или превышении лимитов rate limit (429/500).
+Опция `local_fallback_enabled` позволяет задать резервные локальные модели (Ollama, vLLM, MiniPC), к которым плагин бесшовно обращается при сбоях сетевых API, таймаутах или превышении лимитов rate limit (429/500). Каждая фоллбэк-модель запускается с независимым бюджетом времени и изолированным контроллером отмены, связанным с сигналом основного хода, предотвращая исчерпание времени ожидания из-за задержек облачных провайдеров. Стриминговые сбои и терминальные ошибки классифицируются типизированными исключениями с гарантированной защитой от позднего промоушна.
 
 ### 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>`). Без плагина шаг пропускается тихо — без ошибок в журнале и без битых ссылок.

package/README.zh.md

@@ -142,6 +142,9 @@ graph TD
 ### 8. 提升前 Git 快照检查点 (`dsh-time-machine`)
 在将胜出候选者的文件提升并覆盖至项目根目录前，`dsh-moa` 自动调用本地 `dsh-time-machine` 建立影子 Git 检查点 (`moa-pre-promotion: candidate-N`)。如未安装则静默回退，不阻断提升流程。
 
+### 18. 平滑降级与本地容灾恢复 (Local Fallback Resilience)
+当 `local_fallback_enabled: true` 时，因网络中断、超时或速率限制（429/500）而失败的候选模型会自动使用配置的本地模型（Ollama / MiniPC）恢复。每个后备模型都拥有独立的超时执行配额与关联主 turn signal 的隔离取消控制器，防止云端超时耗尽本地恢复时间。同时严格检测终止错误与流中断，确保安全容灾且杜绝已取消 turn 的延迟文件提升。
+
 ### 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/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())
   }