@angli/unit-test-tool 0.1.0

package/src/core/tools/run-with-claude-cli.ts

@@ -0,0 +1,926 @@
+import { createHash } from 'node:crypto'
+import fg from 'fast-glob'
+import path from 'node:path'
+import type { AppContext } from '../../cli/context/create-context.js'
+import type { BaseToolResult, CandidateFile, TaskItem } from '../../types/index.js'
+import { executeClaudeCli } from '../executor/claude-cli-executor.js'
+import { verifyAll } from './verify-all.js'
+import { rulePlanner } from '../planner/rule-planner.js'
+import { buildFinalReport } from '../reporter/index.js'
+
+export interface RunWithClaudeCliInput {
+  targetFile?: string
+  topN?: number
+  allowedTools?: string[]
+  permissionMode?: string
+  timeoutMs?: number
+  excludeTargets?: string[]
+}
+
+type TaskRunStatus = 'passed' | 'noop' | 'cli_failed' | 'verify_failed'
+
+type TaskRunRecord = {
+  taskId: string
+  targetFile: string
+  attemptCount: number
+  promptPath?: string
+  changedTestFiles?: string[]
+  relatedTestFiles?: string[]
+  verifyResult?: 'passed' | 'failed'
+  status: TaskRunStatus
+  stdout?: string
+  stderr?: string
+  summary: string
+}
+
+export async function runWithClaudeCli(
+  ctx: AppContext,
+  input: RunWithClaudeCliInput = {}
+): Promise<BaseToolResult & { targetFile?: string }> {
+  ctx.logger.info('[run] step=select-target status=start')
+  const coverageSummary = await ctx.reportStore.loadCoverageSummary<{ coverageSnapshot?: Parameters<typeof pickRecommendedTask>[2] }>()
+  const target = input.targetFile
+    ? await buildTaskFromExplicitTarget(ctx, input.targetFile)
+    : await pickRecommendedTask(
+        ctx,
+        input.topN ?? 5,
+        coverageSummary?.coverageSnapshot,
+        input.excludeTargets
+      )
+
+  if (!target) {
+    ctx.logger.warn('[run] step=select-target status=empty')
+    return {
+      ok: false,
+      phase: 'WRITING_TESTS',
+      summary: '没有找到可执行的补测目标。请先运行 analyze 或通过 --file 指定目标文件。',
+      nextAction: 'analyze'
+    }
+  }
+
+  const beforeSnapshot = await captureTestSnapshot(ctx)
+  const firstAttemptTimestamp = ctx.clock.nowIso()
+  const promptText = buildExecutionPrompt(ctx, target.task)
+  const promptPath = await persistPrompt(
+    ctx,
+    target.task.taskId,
+    1,
+    promptText,
+    target.task.targetFile,
+    firstAttemptTimestamp
+  )
+  const stdoutPath = buildTaskOutputPath(
+    ctx,
+    target.task.taskId,
+    1,
+    'stdout',
+    target.task.targetFile,
+    firstAttemptTimestamp
+  )
+  const stderrPath = buildTaskOutputPath(
+    ctx,
+    target.task.taskId,
+    1,
+    'stderr',
+    target.task.targetFile,
+    firstAttemptTimestamp
+  )
+  const runPromptPath = await appendRunPrompt(
+    ctx,
+    target.task.taskId,
+    1,
+    target.task.targetFile,
+    firstAttemptTimestamp,
+    promptPath
+  )
+  await appendRunEvent(ctx, {
+    taskId: target.task.taskId,
+    targetFile: target.task.targetFile,
+    attemptCount: 1,
+    promptPath,
+    status: 'passed',
+    summary: 'prompt recorded'
+  }, 'cli_run_attempt', {
+    promptPreview: buildPreview(promptText),
+    stdoutPath,
+    stderrPath,
+    runPromptPath
+  })
+
+  ctx.logger.info(`[run] step=select-target status=ok taskId=${target.task.taskId} target=${target.task.targetFile}`)
+
+  await ctx.eventStore.append({
+    eventType: 'cli_run_started',
+    phase: 'WRITING_TESTS',
+    taskId: target.task.taskId,
+    message: `selected ${target.task.targetFile}`,
+    data: {
+      targetFile: target.task.targetFile,
+      recommendedTargets: target.recommendedTargets,
+      promptPath,
+      attemptCount: 1
+    },
+    timestamp: ctx.clock.nowIso()
+  })
+
+  await ctx.stateStore.save({
+    phase: 'WRITING_TESTS',
+    status: 'running',
+    currentTaskId: target.task.taskId,
+    coverageSnapshot: undefined,
+    totals: {
+      pending: 0,
+      running: 1,
+      passed: 0,
+      failed: 0,
+      blocked: 0
+    },
+    lastAction: 'run',
+    nextSuggestedAction: 'verify',
+    updatedAt: ctx.clock.nowIso()
+  })
+
+  ctx.logger.info(`[run] step=claude-cli status=start attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile}`)
+  const firstRun = await executeClaudeCli({
+    cwd: ctx.projectPath,
+    prompt: promptText,
+    allowedTools: input.allowedTools,
+    permissionMode: input.permissionMode,
+    outputFormat: 'text',
+    timeoutMs: input.timeoutMs,
+    onProgress: (elapsedMs) => {
+      ctx.logger.info(`[run] step=claude-cli status=waiting attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${elapsedMs}`)
+    },
+    taskMeta: {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      strategy: target.task.strategy,
+      attemptCount: 1
+    }
+  })
+
+  const firstStdoutPath = await persistOutput(
+    ctx,
+    target.task.taskId,
+    1,
+    'stdout',
+    target.task.targetFile,
+    firstAttemptTimestamp,
+    firstRun.stdout
+  )
+  const firstStderrPath = await persistOutput(
+    ctx,
+    target.task.taskId,
+    1,
+    'stderr',
+    target.task.targetFile,
+    firstAttemptTimestamp,
+    firstRun.stderr
+  )
+  if (firstRun.stdout?.trim()) {
+    ctx.logger.info(`[run] step=claude-cli status=stdout attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(firstRun.stdout)}`)
+  }
+  if (firstRun.stderr?.trim()) {
+    ctx.logger.warn(`[run] step=claude-cli status=stderr attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(firstRun.stderr)}`)
+  }
+
+  if (!firstRun.ok) {
+    const stderrText = firstRun.stderr?.trim() || ''
+    const stdoutText = firstRun.stdout?.trim() || ''
+    ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} category=${firstRun.failureCategory ?? 'unknown'}`)
+    if (stderrText) {
+      ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(stderrText)}`)
+    }
+    if (stdoutText) {
+      ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(stdoutText)}`)
+    }
+    const failureMessage = stderrText || stdoutText || 'unknown error'
+    await appendRunEvent(ctx, {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      attemptCount: 1,
+      promptPath,
+      status: 'cli_failed',
+      stdout: stdoutText || undefined,
+      stderr: stderrText || undefined,
+      summary: `Claude CLI 执行失败：${firstRun.failureCategory ?? 'unknown'}。`
+    }, 'cli_run_failed', {
+      stdoutPath: firstStdoutPath,
+      stderrPath: firstStderrPath
+    })
+    await markRunFailed(ctx, target.task, failureMessage)
+    return {
+      ok: false,
+      phase: 'WRITING_TESTS',
+      summary: `Claude CLI 执行失败：${firstRun.failureCategory ?? 'unknown'}。`,
+      nextAction: 'manual-intervention',
+      targetFile: target.task.targetFile,
+      artifacts: {
+        stderr: stderrText || undefined,
+        stdout: stdoutText || undefined
+      }
+    }
+  }
+
+  ctx.logger.info(`[run] step=claude-cli status=done attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${firstRun.durationMs}`)
+
+  ctx.logger.info('[run] step=verify status=start attempt=1')
+  const verifyResult = await verifyAll(ctx)
+  if (verifyResult.ok) {
+    ctx.logger.info('[run] step=verify status=ok attempt=1')
+    const noOpResult = await validateTestChanges(ctx, target.task, beforeSnapshot)
+    if (!noOpResult.ok) {
+      await appendRunEvent(ctx, {
+        taskId: target.task.taskId,
+        targetFile: target.task.targetFile,
+        attemptCount: 1,
+        promptPath,
+        changedTestFiles: noOpResult.changedTestFiles,
+        relatedTestFiles: noOpResult.relatedTestFiles,
+        verifyResult: 'passed',
+        status: 'noop',
+        summary: noOpResult.summary
+      }, 'cli_run_failed', {
+        stdoutPath: firstStdoutPath,
+        stderrPath: firstStderrPath
+      })
+      await markRunFailed(ctx, target.task, noOpResult.summary)
+      return noOpResult
+    }
+    await appendRunEvent(ctx, {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      attemptCount: 1,
+      promptPath,
+      changedTestFiles: noOpResult.changedTestFiles,
+      relatedTestFiles: noOpResult.relatedTestFiles,
+      verifyResult: 'passed',
+      status: 'passed',
+      summary: `Claude CLI 已完成 ${target.task.targetFile} 的补测并通过全量验证。`
+    }, 'cli_run_completed', {
+      stdoutPath: firstStdoutPath,
+      stderrPath: firstStderrPath
+    })
+    await markRunPassed(ctx, target.task)
+    return await buildSuccessResult(
+      ctx,
+      target.task.targetFile,
+      target.recommendedTargets,
+      noOpResult.changedTestFiles,
+      noOpResult.relatedTestFiles
+    )
+  }
+
+  ctx.logger.warn(`[run] step=verify status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile}`)
+
+  ctx.logger.info(`[run] step=claude-cli status=start attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile}`)
+  const retryAttemptTimestamp = ctx.clock.nowIso()
+  const retryPromptText = buildRetryExecutionPrompt(ctx, target.task, verifyResult.artifacts?.stderr)
+  const retryPromptPath = await persistPrompt(
+    ctx,
+    target.task.taskId,
+    2,
+    retryPromptText,
+    target.task.targetFile,
+    retryAttemptTimestamp
+  )
+  const retryStdoutPath = buildTaskOutputPath(
+    ctx,
+    target.task.taskId,
+    2,
+    'stdout',
+    target.task.targetFile,
+    retryAttemptTimestamp
+  )
+  const retryStderrPath = buildTaskOutputPath(
+    ctx,
+    target.task.taskId,
+    2,
+    'stderr',
+    target.task.targetFile,
+    retryAttemptTimestamp
+  )
+  const retryRunPromptPath = await appendRunPrompt(
+    ctx,
+    target.task.taskId,
+    2,
+    target.task.targetFile,
+    retryAttemptTimestamp,
+    retryPromptPath
+  )
+  await appendRunEvent(ctx, {
+    taskId: target.task.taskId,
+    targetFile: target.task.targetFile,
+    attemptCount: 2,
+    promptPath: retryPromptPath,
+    status: 'passed',
+    verifyResult: 'failed',
+    summary: 'retry prompt recorded'
+  }, 'cli_run_attempt', {
+    promptPreview: buildPreview(retryPromptText),
+    stdoutPath: retryStdoutPath,
+    stderrPath: retryStderrPath,
+    runPromptPath: retryRunPromptPath
+  })
+  const retryRun = await executeClaudeCli({
+    cwd: ctx.projectPath,
+    prompt: retryPromptText,
+    allowedTools: input.allowedTools,
+    permissionMode: input.permissionMode,
+    outputFormat: 'text',
+    timeoutMs: input.timeoutMs,
+    onProgress: (elapsedMs) => {
+      ctx.logger.info(`[run] step=claude-cli status=waiting attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${elapsedMs}`)
+    },
+    taskMeta: {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      strategy: target.task.strategy,
+      attemptCount: 2
+    }
+  })
+
+  const retryStdoutSaved = await persistOutput(
+    ctx,
+    target.task.taskId,
+    2,
+    'stdout',
+    target.task.targetFile,
+    retryAttemptTimestamp,
+    retryRun.stdout
+  )
+  const retryStderrSaved = await persistOutput(
+    ctx,
+    target.task.taskId,
+    2,
+    'stderr',
+    target.task.targetFile,
+    retryAttemptTimestamp,
+    retryRun.stderr
+  )
+  if (retryRun.stdout?.trim()) {
+    ctx.logger.info(`[run] step=claude-cli status=stdout attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(retryRun.stdout)}`)
+  }
+  if (retryRun.stderr?.trim()) {
+    ctx.logger.warn(`[run] step=claude-cli status=stderr attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(retryRun.stderr)}`)
+  }
+
+  if (!retryRun.ok) {
+    const stderrText = retryRun.stderr?.trim() || ''
+    const stdoutText = retryRun.stdout?.trim() || ''
+    ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} category=${retryRun.failureCategory ?? 'unknown'}`)
+    if (stderrText) {
+      ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(stderrText)}`)
+    }
+    if (stdoutText) {
+      ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(stdoutText)}`)
+    }
+    const failureMessage = stderrText || stdoutText || 'unknown error'
+    await appendRunEvent(ctx, {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      attemptCount: 2,
+      promptPath: retryPromptPath,
+      status: 'cli_failed',
+      verifyResult: 'failed',
+      stdout: stdoutText || undefined,
+      stderr: stderrText || undefined,
+      summary: `Claude CLI 重试失败：${retryRun.failureCategory ?? 'unknown'}。`
+    }, 'cli_run_failed', {
+      stdoutPath: retryStdoutSaved,
+      stderrPath: retryStderrSaved
+    })
+    await markRunFailed(ctx, target.task, failureMessage)
+    return {
+      ok: false,
+      phase: 'WRITING_TESTS',
+      summary: `Claude CLI 重试失败：${retryRun.failureCategory ?? 'unknown'}。`,
+      nextAction: 'manual-intervention',
+      targetFile: target.task.targetFile,
+      artifacts: {
+        stderr: stderrText || undefined,
+        stdout: stdoutText || undefined
+      }
+    }
+  }
+
+  ctx.logger.info(`[run] step=claude-cli status=done attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${retryRun.durationMs}`)
+
+  ctx.logger.info('[run] step=verify status=start attempt=2')
+  const retriedVerify = await verifyAll(ctx)
+  if (!retriedVerify.ok) {
+    ctx.logger.error(`[run] step=verify status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile}`)
+    await appendRunEvent(ctx, {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      attemptCount: 2,
+      promptPath: retryPromptPath,
+      status: 'verify_failed',
+      verifyResult: 'failed',
+      summary: 'Claude CLI 已重试一次，但全量验证仍失败。'
+    }, 'cli_run_failed', {
+      stdoutPath: retryStdoutSaved,
+      stderrPath: retryStderrSaved
+    })
+    await markRunFailed(ctx, target.task, retriedVerify.artifacts?.stderr)
+    return {
+      ok: false,
+      phase: 'VERIFYING_FULL',
+      summary: 'Claude CLI 已重试一次，但全量验证仍失败。',
+      nextAction: 'manual-intervention',
+      targetFile: target.task.targetFile,
+      artifacts: retriedVerify.artifacts
+    }
+  }
+
+  const noOpResult = await validateTestChanges(ctx, target.task, beforeSnapshot)
+  if (!noOpResult.ok) {
+    await appendRunEvent(ctx, {
+      taskId: target.task.taskId,
+      targetFile: target.task.targetFile,
+      attemptCount: 2,
+      promptPath: retryPromptPath,
+      changedTestFiles: noOpResult.changedTestFiles,
+      relatedTestFiles: noOpResult.relatedTestFiles,
+      verifyResult: 'passed',
+      status: 'noop',
+      summary: noOpResult.summary
+    }, 'cli_run_failed', {
+      stdoutPath: retryStdoutSaved,
+      stderrPath: retryStderrSaved
+    })
+    await markRunFailed(ctx, target.task, noOpResult.summary)
+    return noOpResult
+  }
+
+  await appendRunEvent(ctx, {
+    taskId: target.task.taskId,
+    targetFile: target.task.targetFile,
+    attemptCount: 2,
+    promptPath: retryPromptPath,
+    changedTestFiles: noOpResult.changedTestFiles,
+    relatedTestFiles: noOpResult.relatedTestFiles,
+    verifyResult: 'passed',
+    status: 'passed',
+    summary: `Claude CLI 已完成 ${target.task.targetFile} 的补测并通过全量验证。`
+  }, 'cli_run_completed', {
+    stdoutPath: retryStdoutSaved,
+    stderrPath: retryStderrSaved
+  })
+
+  await markRunPassed(ctx, target.task)
+  return await buildSuccessResult(
+    ctx,
+    target.task.targetFile,
+    target.recommendedTargets,
+    noOpResult.changedTestFiles,
+    noOpResult.relatedTestFiles
+  )
+}
+
+async function pickRecommendedTask(
+  ctx: AppContext,
+  topN: number,
+  coverageSnapshot?: Record<string, unknown>,
+  excludeTargets: string[] = []
+): Promise<{ task: TaskItem; recommendedTargets: string[] } | undefined> {
+  const testDirNames = await detectTestDirNames(ctx)
+  ctx.logger.info('[run] step=scan status=start')
+  ctx.logger.debug('[run] step=scan params', { include: ctx.config.include, exclude: ctx.config.exclude })
+  const files = await fg(ctx.config.include, {
+    cwd: ctx.projectPath,
+    ignore: ctx.config.exclude,
+    onlyFiles: true,
+    absolute: false
+  })
+
+  const candidates: CandidateFile[] = files
+    .filter((file) => !isTestFile(file) && !excludeTargets.includes(file))
+    .map((file) => ({ targetFile: file }))
+
+  ctx.logger.info(`[run] step=scan status=ok total=${files.length} candidates=${candidates.length} topN=${topN}`)
+
+  ctx.logger.info(`[run] step=rank status=start candidates=${candidates.length}`)
+  const ranked = await rulePlanner(ctx, candidates, coverageSnapshot)
+  const shortlist = ranked.slice(0, topN)
+  const selected = shortlist[0]
+  if (!selected) return undefined
+
+  return {
+    task: toTaskItem(selected, testDirNames),
+    recommendedTargets: shortlist.map((item) => item.targetFile)
+  }
+}
+
+async function buildTaskFromExplicitTarget(
+  ctx: AppContext,
+  targetFile: string
+): Promise<{ task: TaskItem; recommendedTargets: string[] } | undefined> {
+  const testDirNames = await detectTestDirNames(ctx)
+  const ranked = await rulePlanner(ctx, [{ targetFile }])
+  const selected = ranked[0]
+  if (!selected) return undefined
+
+  return {
+    task: toTaskItem(selected, testDirNames),
+    recommendedTargets: [selected.targetFile]
+  }
+}
+
+function toTaskItem(candidate: Awaited<ReturnType<typeof rulePlanner>>[number], testDirNames: string[]): TaskItem {
+  return {
+    taskId: candidate.taskId,
+    targetFile: candidate.targetFile,
+    testFiles: candidate.analyzerFacts.existingTest.testFilePaths,
+    score: candidate.baseScore,
+    reasons: candidate.reasons,
+    estimatedDifficulty: candidate.estimatedDifficulty,
+    strategy: candidate.suggestedStrategy ?? 'pure-logic',
+    status: 'pending',
+    attemptCount: 0,
+    testDirNames,
+    analyzerFacts: candidate.analyzerFacts
+  }
+}
+
+function buildExecutionPrompt(ctx: AppContext, task: TaskItem): string {
+  return [
+    ctx.prompts.buildSystemPrompt(),
+    ctx.prompts.buildTaskPrompt(task),
+    ctx.prompts.buildEditBoundaryPrompt(task),
+    '直接在当前工作区完成修改。完成后请给出简洁摘要，包括修改了哪些测试文件、验证结果和遗留问题。'
+  ].join('\n\n')
+}
+
+function buildRetryExecutionPrompt(ctx: AppContext, task: TaskItem, failure?: string | string[]): string {
+  const failureText = Array.isArray(failure) ? failure.join('\n') : failure ?? '未知验证失败'
+  return [
+    buildExecutionPrompt(ctx, task),
+    ctx.prompts.buildRetryPrompt(task, failureText),
+    '下面是上一轮全量验证失败日志，请只针对这些失败修复测试，不要扩展范围：',
+    failureText
+  ].join('\n\n')
+}
+
+function truncateLog(text: string, maxLen = 2000): string {
+  if (text.length <= maxLen) return JSON.stringify(text)
+  return JSON.stringify(`${text.slice(0, maxLen)}...<truncated>`)
+}
+
+async function persistPrompt(
+  ctx: AppContext,
+  taskId: string,
+  attemptCount: number,
+  prompt: string,
+  targetFile: string,
+  timestamp: string
+): Promise<string> {
+  await ctx.fileSystem.ensureDir(ctx.paths.promptsDir)
+  const fileName = buildRunArtifactName(taskId, attemptCount, targetFile, timestamp, 'prompt')
+  const promptPath = path.join(ctx.paths.promptsDir, fileName)
+  await ctx.fileSystem.writeText(promptPath, prompt)
+  return promptPath
+}
+
+async function appendRunPrompt(
+  ctx: AppContext,
+  taskId: string,
+  attemptCount: number,
+  targetFile: string,
+  timestamp: string,
+  promptPath: string
+): Promise<string> {
+  await ctx.fileSystem.ensureDir(ctx.paths.promptRunsDir)
+  const runPromptPath = path.join(ctx.paths.promptRunsDir, `run-${ctx.runId}.prompt.log`)
+  const attemptLabel = `a${attemptCount}`
+  const content = [
+    '===== TASK PROMPT START =====',
+    `taskId: ${taskId}`,
+    `attempt: ${attemptCount}`,
+    `attemptLabel: ${attemptLabel}`,
+    `targetFile: ${targetFile}`,
+    `timestamp: ${timestamp}`,
+    `promptPath: ${promptPath}`,
+    `promptFile: ${path.basename(promptPath)}`,
+    '===== TASK PROMPT END =====',
+    ''
+  ].join('\n')
+  await ctx.fileSystem.appendText(runPromptPath, content)
+  return runPromptPath
+}
+
+async function appendRunEvent(
+  ctx: AppContext,
+  record: TaskRunRecord,
+  eventType = 'cli_run_attempt',
+  extraData?: Record<string, unknown>
+): Promise<void> {
+  const targetBaseName = path.basename(record.targetFile, path.extname(record.targetFile))
+  const attemptLabel = `a${record.attemptCount}`
+  await ctx.eventStore.append({
+    eventType,
+    phase: record.status === 'verify_failed' ? 'VERIFYING_FULL' : record.status === 'passed' ? 'DONE' : 'WRITING_TESTS',
+    taskId: record.taskId,
+    message: record.summary,
+    data: {
+      runId: ctx.runId,
+      taskId: record.taskId,
+      attemptLabel,
+      targetBaseName,
+      targetFile: record.targetFile,
+      attemptCount: record.attemptCount,
+      promptPath: record.promptPath,
+      changedTestFiles: record.changedTestFiles,
+      relatedTestFiles: record.relatedTestFiles,
+      verifyResult: record.verifyResult,
+      status: record.status,
+      stdout: record.stdout ? truncateLog(record.stdout, 500) : undefined,
+      stderr: record.stderr ? truncateLog(record.stderr, 500) : undefined,
+      ...extraData
+    },
+    timestamp: ctx.clock.nowIso()
+  })
+}
+
+function buildPreview(prompt: string, maxLen = 240): string {
+  const compact = prompt.replace(/\s+/g, ' ').trim()
+  return compact.length <= maxLen ? compact : `${compact.slice(0, maxLen)}...`
+}
+
+function buildRunArtifactName(
+  taskId: string,
+  attemptCount: number,
+  targetFile: string,
+  timestamp: string,
+  suffix: 'prompt' | 'stdout' | 'stderr'
+): string {
+  const baseName = path.basename(targetFile, path.extname(targetFile))
+  const safeBaseName = baseName.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-')
+  const pathHash = hashContent(normalizePath(targetFile)).slice(0, 8)
+  const safeTimestamp = formatArtifactTimestamp(timestamp)
+  return `${taskId}-a${attemptCount}-${safeBaseName}-${pathHash}-${safeTimestamp}.${suffix}${suffix === 'prompt' ? '.txt' : '.log'}`
+}
+
+function formatArtifactTimestamp(timestamp: string): string {
+  return timestamp.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
+}
+
+function buildTaskOutputPath(
+  ctx: AppContext,
+  taskId: string,
+  attemptCount: number,
+  stream: 'stdout' | 'stderr',
+  targetFile: string,
+  timestamp: string
+): string {
+  return path.join(ctx.paths.logsPath, buildRunArtifactName(taskId, attemptCount, targetFile, timestamp, stream))
+}
+
+async function persistOutput(
+  ctx: AppContext,
+  taskId: string,
+  attemptCount: number,
+  stream: 'stdout' | 'stderr',
+  targetFile: string,
+  timestamp: string,
+  content?: string
+): Promise<string | undefined> {
+  if (!content?.trim()) return undefined
+  await ctx.fileSystem.ensureDir(ctx.paths.logsPath)
+  const outputPath = buildTaskOutputPath(ctx, taskId, attemptCount, stream, targetFile, timestamp)
+  await ctx.fileSystem.writeText(outputPath, content)
+  return outputPath
+}
+
+type TestSnapshot = Record<string, string>
+
+type TestChangeValidationResult = (BaseToolResult & { targetFile?: string }) & {
+  changedTestFiles: string[]
+  relatedTestFiles: string[]
+}
+
+async function captureTestSnapshot(ctx: AppContext): Promise<TestSnapshot> {
+  const files = await fg(buildTestSnapshotPatterns(ctx.config.testDirNames), {
+    cwd: ctx.projectPath,
+    ignore: ctx.config.exclude,
+    onlyFiles: true,
+    absolute: false
+  })
+
+  const snapshotEntries = await Promise.all(
+    files.map(async (file) => {
+      const content = await ctx.fileSystem.readText(path.join(ctx.projectPath, file))
+      return [file, hashContent(content ?? '')] as const
+    })
+  )
+
+  return Object.fromEntries(snapshotEntries)
+}
+
+async function validateTestChanges(
+  ctx: AppContext,
+  task: TaskItem,
+  beforeSnapshot: TestSnapshot
+): Promise<TestChangeValidationResult> {
+  const afterSnapshot = await captureTestSnapshot(ctx)
+  const changedTestFiles = Object.keys(afterSnapshot)
+    .filter((file) => beforeSnapshot[file] !== afterSnapshot[file])
+    .sort()
+
+  const relatedTestFiles = findRelatedTestFiles(task, changedTestFiles)
+  if (relatedTestFiles.length > 0) {
+    ctx.logger.info(
+      `[run] step=test-change status=ok taskId=${task.taskId} target=${task.targetFile} changed=${relatedTestFiles.join(',')}`
+    )
+    return {
+      ok: true,
+      phase: 'DONE',
+      summary: '检测到目标相关测试变更。',
+      targetFile: task.targetFile,
+      changedTestFiles,
+      relatedTestFiles
+    }
+  }
+
+  ctx.logger.warn(
+    `[run] step=test-change status=noop taskId=${task.taskId} target=${task.targetFile} changed=${changedTestFiles.join(',') || 'none'}`
+  )
+  return {
+    ok: false,
+    phase: 'WRITING_TESTS',
+    summary: `Claude CLI 未产出 ${task.targetFile} 的相关测试变更，本次视为 no-op。`,
+    nextAction: 'manual-intervention',
+    targetFile: task.targetFile,
+    artifacts: {
+      changedTestFiles: changedTestFiles.length > 0 ? changedTestFiles : undefined,
+      relatedTestFiles: relatedTestFiles.length > 0 ? relatedTestFiles : undefined
+    },
+    changedTestFiles,
+    relatedTestFiles
+  }
+}
+
+function findRelatedTestFiles(task: TaskItem, changedTestFiles: string[]): string[] {
+  if (changedTestFiles.length === 0) return []
+
+  const existingMatches = new Set(task.testFiles)
+  const baseName = path.basename(task.targetFile, path.extname(task.targetFile))
+  const targetDir = path.dirname(task.targetFile)
+  const normalizedTargetDir = normalizePath(targetDir)
+  const moduleDirName = path.basename(targetDir)
+
+  return changedTestFiles.filter((file) => {
+    if (existingMatches.has(file)) return true
+
+    const normalizedFile = normalizePath(file)
+    const fileName = path.basename(file)
+    const fileBaseName = path.basename(fileName, path.extname(fileName))
+    if (fileBaseName === baseName || fileBaseName === `${baseName}.test` || fileBaseName === `${baseName}.spec`) {
+      return true
+    }
+
+    if (normalizedFile.startsWith(`${normalizedTargetDir}/`)) return true
+    if (normalizedFile.includes(`/${moduleDirName}/`) && isTestFile(file)) return true
+
+    return false
+  })
+}
+
+function buildTestSnapshotPatterns(testDirNames?: string[]): string[] {
+  const configured = testDirNames?.filter(Boolean) ?? ['__test__', '__tests__']
+  return [
+    '**/*.test.*',
+    '**/*.spec.*',
+    ...configured.map((dir) => `**/${dir}/**/*.*`)
+  ]
+}
+
+function hashContent(content: string): string {
+  return createHash('sha1').update(content).digest('hex')
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/')
+}
+
+async function markRunFailed(
+  ctx: AppContext,
+  task: TaskItem,
+  error?: string | string[],
+  loopSummary?: {
+    iterationCount: number
+    completedTargets: number
+    blockedTargets: number
+    noOpTargets: number
+    lastCompletedTarget?: string
+  }
+) {
+  const message = Array.isArray(error) ? error.join('\n') : error ?? 'unknown error'
+  await ctx.stateStore.save({
+    phase: 'BLOCKED',
+    status: 'failed',
+    currentTaskId: task.taskId,
+    lastError: message,
+    loopSummary,
+    totals: {
+      pending: 0,
+      running: 0,
+      passed: 0,
+      failed: 1,
+      blocked: 0
+    },
+    lastAction: 'run',
+    nextSuggestedAction: 'manual-intervention',
+    updatedAt: ctx.clock.nowIso()
+  })
+
+  await ctx.eventStore.append({
+    eventType: 'cli_run_failed',
+    phase: 'BLOCKED',
+    taskId: task.taskId,
+    message,
+    timestamp: ctx.clock.nowIso()
+  })
+}
+
+async function markRunPassed(
+  ctx: AppContext,
+  task: TaskItem,
+  loopSummary?: {
+    iterationCount: number
+    completedTargets: number
+    blockedTargets: number
+    noOpTargets: number
+    lastCompletedTarget?: string
+  }
+) {
+  await ctx.stateStore.save({
+    phase: 'DONE',
+    status: 'done',
+    currentTaskId: task.taskId,
+    loopSummary,
+    totals: {
+      pending: 0,
+      running: 0,
+      passed: 1,
+      failed: 0,
+      blocked: 0
+    },
+    lastAction: 'run',
+    nextSuggestedAction: 'report',
+    updatedAt: ctx.clock.nowIso()
+  })
+
+  await ctx.eventStore.append({
+    eventType: 'cli_run_completed',
+    phase: 'DONE',
+    taskId: task.taskId,
+    message: `completed ${task.targetFile}`,
+    timestamp: ctx.clock.nowIso()
+  })
+}
+
+async function buildSuccessResult(
+  ctx: AppContext,
+  targetFile: string,
+  recommendedTargets: string[],
+  changedTestFiles?: string[],
+  relatedTestFiles?: string[]
+) {
+  const report = await buildFinalReport(ctx)
+  await ctx.reportStore.saveFinalReport(report)
+  return {
+    ok: true,
+    phase: 'DONE' as const,
+    summary: `Claude CLI 已完成 ${targetFile} 的补测并通过全量验证。`,
+    nextAction: 'report',
+    targetFile,
+    artifacts: {
+      finalReportPath: ctx.paths.finalReportPath,
+      recommendedTargets,
+      changedTestFiles,
+      relatedTestFiles
+    }
+  }
+}
+
+function isTestFile(file: string): boolean {
+  return /(\.test|\.spec)\.[jt]sx?$/.test(file) || file.includes('__test__/') || file.includes('__tests__/')
+}
+
+async function detectTestDirNames(ctx: AppContext): Promise<string[]> {
+  if (ctx.cache.detectedTestDirNames) return ctx.cache.detectedTestDirNames
+
+  const configured = ctx.config.testDirNames?.filter(Boolean) ?? ['__test__', '__tests__']
+  const jestConfigPath = path.join(ctx.projectPath, 'jest.config.js')
+  const jestConfig = await ctx.fileSystem.readText(jestConfigPath)
+  if (!jestConfig) {
+    ctx.cache.detectedTestDirNames = configured
+    return configured
+  }
+
+  const detected = configured.filter((dir) => jestConfig.includes(dir))
+  const result = detected.length > 0 ? detected : configured
+  ctx.cache.detectedTestDirNames = result
+  return result
+}