@miphamai/cli 0.68.0 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/commands/loop-scaffold.ts

@@ -64,10 +64,6 @@ function writeTemplate(
  * ├── .mipham/
  * │   ├── CLAUDE.md
  * │   ├── settings.json
- * │   ├── hooks/
- * │   │   ├── pre-tool-use.sh
- * │   │   ├── post-tool-use.sh
- * │   │   └── stop.sh
  * │   ├── agents/
  * │   │   └── verifier.md
  * │   └── skills/
@@ -103,13 +99,6 @@ export function scaffoldLoopKit(basePath: string): ScaffoldResult {
   // ── .mipham/settings.json ──
   writeTemplate(join(miphamDir, 'settings.json'), TEMPLATES.settingsJson, false, created, skipped)
 
-  // ── .mipham/hooks/ ──
-  const hooksDir = join(miphamDir, 'hooks')
-  ensureDir(hooksDir, created, skipped)
-  writeTemplate(join(hooksDir, 'pre-tool-use.sh'), TEMPLATES.preToolUse, true, created, skipped)
-  writeTemplate(join(hooksDir, 'post-tool-use.sh'), TEMPLATES.postToolUse, true, created, skipped)
-  writeTemplate(join(hooksDir, 'stop.sh'), TEMPLATES.stopHook, true, created, skipped)
-
   // ── .mipham/agents/ ──
   const agentsDir = join(miphamDir, 'agents')
   ensureDir(agentsDir, created, skipped)
@@ -180,7 +169,20 @@ const TEMPLATES = {
           deny: [],
         },
         hooks: {
-          PreToolUse: [],
+          // 示例：PreToolUse 拦截 Bash。脚本从 stdin 读 JSON（tool_name/tool_input），
+          // 输出 hookSpecificOutput JSON 决定 allow/deny；exit 2 = 拦截（stderr 作理由）。
+          PreToolUse: [
+            {
+              matcher: 'Bash',
+              hooks: [
+                {
+                  type: 'command',
+                  command: 'your-hook-script.sh',
+                  timeout: 60,
+                },
+              ],
+            },
+          ],
           PostToolUse: [],
           Stop: [],
           SessionStart: [],
@@ -192,37 +194,6 @@ const TEMPLATES = {
       2,
     ) + '\n',
 
-  preToolUse: `#!/bin/bash
-# PreToolUse hook — runs before each tool execution.
-# Tool name passed as \$1, input JSON as \$2.
-# Exit non-zero to block the tool.
-# Write JSON to stdout to modify the tool input.
-
-TOOL_NAME="\$1"
-TOOL_INPUT="\$2"
-
-echo "{\\"decision\\": \\"allow\\"}" >&2
-exit 0
-`,
-
-  postToolUse: `#!/bin/bash
-# PostToolUse hook — runs after each tool execution.
-# Tool name passed as \$1, result JSON as \$2.
-
-TOOL_NAME="\$1"
-TOOL_RESULT="\$2"
-
-exit 0
-`,
-
-  stopHook: `#!/bin/bash
-# Stop hook — runs when the AI session ends.
-# Use for cleanup, notifications, or saving state.
-
-echo "Session ended at \$(date)" >&2
-exit 0
-`,
-
   verifierAgent: `# Verifier Agent
 
 > Pre-commit audit specialist. Dispatched BEFORE committing to verify changes.
@@ -290,7 +261,7 @@ Verify staged changes against coding standards, security rules, and best practic
 
 ## Structure
 
-- \`.mipham/\` — Mipham Code configuration (CLAUDE.md, settings, hooks, agents, skills)
+- \`.mipham/\` — Mipham Code configuration (CLAUDE.md, settings.json, agents, skills)
 - \`.mcp.json\` — MCP server configuration
 - \`MEMORY.md\` — AI persistent memory
 - \`run.sh\` — Project launcher

package/src/config/loader.ts

@@ -28,6 +28,7 @@ import {
   DEFAULT_CROSS_SESSION_CONFIG,
 } from './defaults'
 import { getCredentialKey, encryptApiKey, decryptApiKey, ENC_PREFIX } from './credential-crypto'
+import type { SettingsHooks } from '../core/hooks-config'
 
 const MIPHAM_HOME = join(homedir(), '.mipham')
 const BACKUP_PREFIX = 'config.backup-'
@@ -139,7 +140,7 @@ function backupConfig(configPath: string): void {
  * Try to restore config from the most recent backup.
  * Returns true if restored successfully.
  */
-function tryRestoreFromBackup(configPath: string): boolean {
+export function tryRestoreFromBackup(configPath: string): boolean {
   try {
     if (!existsSync(MIPHAM_HOME)) return false
     const files = readdirSync(MIPHAM_HOME)
@@ -216,6 +217,60 @@ function loadMcpJson(cwd: string): McpServerConfig[] {
   return servers
 }
 
+/**
+ * Parsed `settings.json` (Claude Code convention): hooks + permissions.
+ * Hooks are additive across levels; permissions allow/deny are deduped unions.
+ */
+export interface SettingsJson {
+  hooks: SettingsHooks
+  permissions: { allow: string[]; deny: string[] }
+}
+
+/**
+ * Load `settings.json` — project-level `.mipham/settings.json` then user-level
+ * `~/.mipham/settings.json`. Mirrors the Claude Code convention (hooks additive,
+ * permissions merged), so users can migrate their Claude settings unchanged.
+ */
+export function loadSettingsJson(cwd: string = process.cwd()): SettingsJson {
+  const hooks: SettingsHooks = {}
+  const permissions = { allow: [] as string[], deny: [] as string[] }
+
+  const searchPaths = [join(cwd, '.mipham', 'settings.json'), join(MIPHAM_HOME, 'settings.json')]
+
+  for (const path of searchPaths) {
+    try {
+      if (!existsSync(path)) continue
+      const raw = readFileSync(path, 'utf-8')
+      const parsed = JSON.parse(raw) as {
+        hooks?: Record<string, unknown>
+        permissions?: { allow?: unknown; deny?: unknown }
+      }
+
+      if (parsed.hooks && typeof parsed.hooks === 'object') {
+        for (const [eventName, entries] of Object.entries(parsed.hooks)) {
+          if (!Array.isArray(entries)) continue
+          const bucket = (hooks as Record<string, unknown[]>)[eventName]
+          ;(hooks as Record<string, unknown[]>)[eventName] = [...(bucket ?? []), ...entries]
+        }
+      }
+
+      if (parsed.permissions) {
+        for (const key of ['allow', 'deny'] as const) {
+          const list = parsed.permissions[key]
+          if (!Array.isArray(list)) continue
+          for (const p of list) {
+            if (typeof p === 'string' && !permissions[key].includes(p)) permissions[key].push(p)
+          }
+        }
+      }
+    } catch {
+      // Silently skip malformed or missing settings.json files
+    }
+  }
+
+  return { hooks, permissions }
+}
+
 export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
   const configPath = join(cwd, '.mipham', 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')

package/src/core/claude-md-fix.ts

@@ -0,0 +1,28 @@
+/**
+ * CLAUDE.md fix — write the derivable-section headings that `findDerivableSections`
+ * flags into the document's `prompt-exclude` frontmatter, so `stripSections` stops
+ * injecting them into the system prompt every session.
+ */
+import { stringify as stringifyYaml } from 'yaml'
+import { parseFrontmatter, parsePromptExclude } from './instructions'
+
+export interface ApplyPromptExcludeResult {
+  content: string
+  added: string[]
+}
+
+/**
+ * Merge `headings` into the document's `prompt-exclude` frontmatter (creating the
+ * frontmatter block if absent). Preserves existing exclusions and other frontmatter
+ * fields; reports only the headings that were actually new.
+ */
+export function applyPromptExclude(content: string, headings: string[]): ApplyPromptExcludeResult {
+  const { data, content: body } = parseFrontmatter(content)
+  const existing = parsePromptExclude(data['prompt-exclude'])
+  const added = [...new Set(headings)].filter((h) => !existing.includes(h))
+  if (added.length === 0) return { content, added: [] }
+
+  data['prompt-exclude'] = [...existing, ...added]
+  const frontmatter = stringifyYaml(data)
+  return { content: `---\n${frontmatter}---\n${body}`, added }
+}

package/src/core/crsi-modify.ts

@@ -15,7 +15,7 @@
 import { randomUUID } from 'node:crypto'
 import { CrsiSandbox, validateBlastRadius } from './crsi-sandbox'
 import type { CrsiModificationResult } from './crsi-sandbox'
-import { appendEvalScore, getLastEvalScore } from './eval-harness'
+import { appendEvalScore, getLastEvalScore, regressedAnchors } from './eval-harness'
 import { mechanismSentinel, type RewardFn } from './reward-fn'
 
 export interface CrsiProposal {
@@ -102,6 +102,15 @@ export async function runCrsiModification(
   // 默认机制哨兵；可插拔——调用方传 opts.rewardFn 换用其他奖励源（如任务表现）。
   const rewardFn = opts?.rewardFn ?? mechanismSentinel()
   const report = await rewardFn.evaluate()
+  // 细粒度防回退：anchor 契约（安全/机制不变量）任一翻转 PASS→FAIL 即拒，
+  // 即使总分因新增契约而上升也被拦（比「总分不退化」更严格）。
+  const anchors = regressedAnchors(report.results ?? [])
+  if (anchors.length > 0) {
+    sandbox.rollback()
+    applied.phase = 'failed'
+    applied.error = `Anchor regression: ${anchors.join(', ')}`
+    return applied
+  }
   const last = getLastEvalScore(rewardFn.name)
   if (last !== null && report.score < last) {
     sandbox.rollback()

package/src/core/crsi-producer.ts

@@ -20,6 +20,9 @@ import { homedir } from 'node:os'
 /** 教训文件（相对仓库根）。预建，沙箱只能改已存在文件。 */
 export const LESSONS_FILE = 'apps/cli/crsi-lessons.md'
 
+/** 组件归因（修复决策，非因果断言）：失败最可能被哪个记忆组件的局部干预修复。 */
+export type MemoryComponent = 'experiential' | 'working' | 'invocation' | 'checker'
+
 /** 归一化的教训信号（insight 与 meta-rule 的公共面）。 */
 export interface CrsiSignal {
   category: string
@@ -27,6 +30,12 @@ export interface CrsiSignal {
   severity?: string
   suggestion: string
   evidence: string[]
+  /**
+   * 组件归因：该失败最可能被哪个记忆组件的局部干预修复。
+   * 缺省 experiential（现状 = 教训/技能/受管理规则，全属 E）。
+   * working/invocation/checker 待 ②③ 落地后由对应信号源产出。
+   */
+  component?: MemoryComponent
 }
 
 const SEVERITY_RANK: Record<string, number> = { critical: 0, warning: 1, info: 2 }
@@ -76,6 +85,7 @@ export function buildLessonContent(
     `## ${signal.category}: ${signal.title}`,
     '',
     `- 建议: ${signal.suggestion}`,
+    `- 组件: ${signal.component ?? 'experiential'}`,
   ]
   if (signal.severity) lines.push(`- 严重度: ${signal.severity}`)
   lines.push(`- 生成时间: ${timestamp}`, `- 来源: ${source}`, '', '### 证据')
@@ -188,6 +198,9 @@ export function managedRuleId(signal: CrsiSignal): string {
  * 只支持 timeout / tool-params 两类确定性 category，其余返回 null。
  */
 export function renderManagedRuleSource(signal: CrsiSignal): string | null {
+  // managed-rule 是「行为固化」，只处理 experiential 组件（timeout/tool-params 本质是 E）。
+  // working/invocation/checker 的修复走各自组件路径，不进这里。
+  if ((signal.component ?? 'experiential') !== 'experiential') return null
   const id = managedRuleId(signal)
   const warning = signal.suggestion || `CRSI 自动固化: ${signal.title}`
 

package/src/core/engine.ts

@@ -29,6 +29,8 @@ import { CrsiProvenanceBridge } from '../agent/crsi-provenance-bridge.js'
 import { McpClient } from '../mcp/client.js'
 import { ErrorSignatureDB } from './error-signature-db.js'
 import { PreFlightChecker } from './preflight-checker.js'
+import { PostFlightChecker, createDefaultPostFlightChecker } from './post-flight-checker'
+import { recordToolEvidence } from './working-memory'
 import { AutoCorrector } from './auto-corrector.js'
 import { MetaRuleEngine } from './meta-rule-engine.js'
 import { DreamEngine } from './dream-engine.js'
@@ -83,6 +85,7 @@ export class QueryEngine {
   private _autoMemory?: AutoMemoryEngine
   private _errorSignatureDB?: ErrorSignatureDB
   private _preflightChecker?: PreFlightChecker
+  private _postFlightChecker?: PostFlightChecker
   private _autoCorrector?: AutoCorrector
   private _metaRuleEngine?: MetaRuleEngine
   private _dreamEngine?: DreamEngine
@@ -1243,6 +1246,23 @@ export class QueryEngine {
       // Accumulate graft token savings from "[graft] tokens saved ≈ N" footers
       accumulateGraftSavings(result.content)
 
+      // ── PostFlightChecker — 事后验证「观察是否支撑变更」（Recuris C 组件）──
+      // 默认 no-checker 静默、rejected 只记录不阻塞（第一阶段只产证据，不强制拦截）。
+      const decision = this.getPostFlightChecker().check(name, {
+        params: effectiveParams,
+        result,
+      })
+      // 证据账本：supported/rejected 回灌工作记忆（供 Task 完成门读取）
+      recordToolEvidence(name, decision)
+      if (decision.verdict !== 'no-checker') {
+        this.context.getLog()?.append({
+          type: 'checker/decision',
+          at: Date.now(),
+          toolName: name,
+          decision,
+        })
+      }
+
       return result
     } catch (err) {
       // P1-3: Trigger PostToolUseFailure hook on tool execution errors
@@ -1488,6 +1508,17 @@ export class QueryEngine {
     return this._preflightChecker
   }
 
+  /**
+   * Recuris C 组件：Lazily-initialized PostFlightChecker singleton。
+   * 事后验证「工具/env 观察是否支撑变更」，与 PreFlightChecker（事前拦截）互补。
+   */
+  getPostFlightChecker(): PostFlightChecker {
+    if (!this._postFlightChecker) {
+      this._postFlightChecker = createDefaultPostFlightChecker()
+    }
+    return this._postFlightChecker
+  }
+
   /**
    * SIS Phase 2: Lazily-initialized AutoCorrector singleton.
    * Analyzes failed tool calls and suggests corrections based on

package/src/core/eval-harness.ts

@@ -18,19 +18,31 @@ import { ExperienceRuleEngine } from './rule-engine'
 import { ConstitutionLoader, DEFAULT_CONSTITUTION } from './constitution-loader'
 import { ErrorSignatureDB } from './error-signature-db'
 import { PreFlightChecker } from './preflight-checker'
+import { createDefaultPostFlightChecker } from './post-flight-checker'
+import { WorkingMemory } from './working-memory'
 import { RedTeam } from './red-team'
 import { isProtectedPath, validateBlastRadius, PROTECTED_CRITICAL_FILES } from './crsi-sandbox'
-import { produceRuleProposal, MANAGED_RULES_FILE } from './crsi-producer'
+import {
+  produceRuleProposal,
+  MANAGED_RULES_FILE,
+  buildLessonContent,
+  renderManagedRuleSource,
+} from './crsi-producer'
 import type { CrsiSignal } from './crsi-producer'
 import { loadBehaviorTasks, judgeBehaviorTask } from './behavior-tasks'
 
 // ── Types ──
 
+/** 契约角色：anchor = 安全/机制不变量（门强制不许回退）；target = 缺口/覆盖（应被补）。 */
+export type ContractRole = 'anchor' | 'target' | 'neutral'
+
 export interface EvalResult {
   id: string
   description: string
   passed: boolean
   detail?: string
+  /** 契约角色。缺省 neutral。 */
+  role?: ContractRole
 }
 
 export interface EvalReport {
@@ -42,6 +54,29 @@ export interface EvalReport {
   failures: string[]
 }
 
+/** anchor 契约 id 集合：安全/机制不变量，绝不许回退。门（crsi-modify）强制此集合零回退。 */
+export const ANCHOR_CONTRACT_IDS: ReadonlySet<string> = new Set([
+  'rule-timeout',
+  'rule-git-force',
+  'rule-disabled-skip',
+  'constitution-8-principles',
+  'constitution-facets',
+  'constitution-preamble',
+  'sandbox-protected-constitution',
+  'sandbox-protected-tests',
+  'sandbox-protected-machinery',
+  'protection-completeness',
+  'blast-radius-gate',
+  'red-team-zero-gaps',
+  'producer-rule-shape',
+  'producer-rule-idempotent',
+])
+
+/** 细粒度防回退：返回 role==='anchor' 且已 FAIL 的契约 id。空 = 无 anchor 回退。 */
+export function regressedAnchors(results: EvalResult[]): string[] {
+  return results.filter((r) => r.role === 'anchor' && !r.passed).map((r) => r.id)
+}
+
 // ── Rewards log (path A Phase 1: 奖励信号持久化) ──
 
 const SCORES_FILE = join(homedir(), '.mipham', 'crsi', 'eval-scores.jsonl')
@@ -228,6 +263,48 @@ export function runEval(): EvalReport {
       ruleProposal !== null && produceRuleProposal(frozenSignal, ruleProposal.newContent) === null,
   })
 
+  // ── 组件归因（ground truth：缺省 experiential、显式组件透传、非 experiential 不进 managed-rule） ──
+  results.push({
+    id: 'producer-component-tag',
+    description: '组件归因：缺省 experiential、显式组件透传、非 experiential 不进 managed-rule',
+    passed:
+      buildLessonContent(frozenSignal, 't', 'src').includes('- 组件: experiential') &&
+      buildLessonContent({ ...frozenSignal, component: 'checker' }, 't', 'src').includes(
+        '- 组件: checker',
+      ) &&
+      renderManagedRuleSource({ ...frozenSignal, component: 'working' }) === null &&
+      renderManagedRuleSource(frozenSignal) !== null,
+  })
+
+  // ── 事后检查器（ground truth：exit 0 判 supported、exit 非 0 判 rejected） ──
+  const postFlight = createDefaultPostFlightChecker()
+  results.push({
+    id: 'postflight-bash-exit',
+    description: '事后检查器：bash exit 0 判 supported、exit 非 0 判 rejected',
+    passed:
+      postFlight.check('Bash', { params: {}, result: { success: true, content: '' } }).verdict ===
+        'supported' &&
+      postFlight.check('Bash', { params: {}, result: { success: false, content: '', error: 'x' } })
+        .verdict === 'rejected',
+  })
+
+  // ── 工作记忆证据接地（ground truth：done 只能由 supported 推进，模型自称不算） ──
+  const wm = new WorkingMemory()
+  wm.setGoal('install-deps', 'install dependencies')
+  wm.observe('install-deps', { verdict: 'no-checker' })
+  const pendingAfterNoChecker = wm.getGoal('install-deps')!.status === 'pending'
+  wm.observe('install-deps', { verdict: 'supported', checkerId: 'bash-exit' })
+  const doneAfterSupported = wm.getGoal('install-deps')!.status === 'done'
+  wm.setGoal('edit-file', 'edit the file')
+  wm.observe('edit-file', { verdict: 'rejected', checkerId: 'edit-applied', reason: 'x' })
+  const blockedAfterRejected = wm.getGoal('edit-file')!.status === 'blocked'
+  results.push({
+    id: 'working-memory-evidence-gated',
+    description:
+      '工作记忆：done 只能由 checker supported 推进，rejected 置 blocked，模型自称（no-checker）不算',
+    passed: pendingAfterNoChecker && doneAfterSupported && blockedAfterRejected,
+  })
+
   // ── 行为缺口（ground truth：当前无规则覆盖的确定性拦截，如实判 FAIL） ──
   // producer 固化 tool-params 规则后，这些缺口翻转 PASS → 分数上升 =「证明更好」。
   const behaviorGaps: Array<{ id: string; command: string }> = [
@@ -246,15 +323,30 @@ export function runEval(): EvalReport {
       id: gap.id,
       description: `行为缺口未覆盖: ${gap.command}`,
       passed: r.warnings.length > 0,
+      role: 'target',
     })
   }
 
   // ── 行为任务集（ground truth：约束行为效果，确定性无 LLM） ──
   const behaviorTasks = loadBehaviorTasks()
   for (const task of behaviorTasks) {
-    results.push(judgeBehaviorTask(task, ruleEngine))
+    results.push({ ...judgeBehaviorTask(task, ruleEngine), role: 'target' })
   }
 
+  // 角色标注：anchor 走集中清单（门保护面单一真源），target 已在上方循环内联。
+  for (const r of results) {
+    if (ANCHOR_CONTRACT_IDS.has(r.id)) r.role = 'anchor'
+  }
+
+  // anchor 自检（ground truth：所有 anchor 契约必须全绿，否则门拒）。
+  const anchorFailures = results.filter((r) => r.role === 'anchor' && !r.passed).map((r) => r.id)
+  results.push({
+    id: 'anchor-gate',
+    description: '所有 anchor 契约必须全绿（细粒度防回退闸）',
+    passed: anchorFailures.length === 0,
+    ...(anchorFailures.length > 0 ? { detail: `回退的 anchor: ${anchorFailures.join(', ')}` } : {}),
+  })
+
   const passed = results.filter((r) => r.passed).length
   return {
     total: results.length,

package/src/core/fix-code.ts

@@ -0,0 +1,167 @@
+/**
+ * `/fix test` — LLM-driven repair of failing tests in the real repo.
+ *
+ * Reuses the `/crsi bench` closed loop (LLM generates → a frozen test judges the
+ * result) but applied to the caller's own codebase: the failing test is the frozen
+ * ground truth, and the LLM may only fix the *source*, never the test.
+ */
+
+/**
+ * Extract failing test-file paths from a `vitest run` output stream. Matches the
+ * ` FAIL  test/xxx.test.ts > describe > it` lines (vitest 4 default reporter).
+ */
+export function parseVitestFailures(output: string): string[] {
+  const files = new Set<string>()
+  const re = /^\s*FAIL\s+(\S+)/gm
+  let m
+  while ((m = re.exec(output))) {
+    files.add(m[1]!)
+  }
+  return [...files]
+}
+
+/**
+ * Extract relative import specifiers (`./foo`, `../bar`) from a test file — these
+ * are the candidate source files the failing test depends on. Package imports
+ * (`vitest`, `lodash`) and node builtins (`node:fs`) are ignored.
+ */
+export function collectLocalImports(testContent: string): string[] {
+  const imports: string[] = []
+  const re = /from\s+['"](\.[^'"]*)['"]/g
+  let m
+  while ((m = re.exec(testContent))) {
+    imports.push(m[1]!)
+  }
+  return imports
+}
+
+/**
+ * Build the LLM prompt that asks for a source-only fix. The test is declared
+ * frozen ground truth; the model must return the corrected source file contents.
+ */
+export function buildFixPrompt(opts: {
+  testPath: string
+  testContent: string
+  sourcePath: string
+  sourceContent: string
+  failure: string
+}): string {
+  const { testPath, testContent, sourcePath, sourceContent, failure } = opts
+  return [
+    'You are fixing a failing test in a real codebase.',
+    '',
+    'RULES:',
+    '- The test file is FROZEN ground truth. Do NOT modify the test.',
+    '- Only fix the SOURCE file so the test passes.',
+    '- Output ONLY the corrected source file contents — no markdown fences, no explanation.',
+    '',
+    `Failing test: ${testPath}`,
+    '```',
+    testContent,
+    '```',
+    '',
+    `Source to fix: ${sourcePath}`,
+    '```',
+    sourceContent,
+    '```',
+    '',
+    'Failure:',
+    failure,
+  ].join('\n')
+}
+
+export interface FixCodeDeps {
+  runVitest: (testFile: string) => { exitCode: number; output: string }
+  readFile: (path: string) => string | null
+  writeFile: (path: string, content: string) => void
+  generateFix: (prompt: string) => Promise<string>
+  resolveSourceFile: (testFile: string, specifier: string) => string
+}
+
+export interface FixTargetResult {
+  testFile: string
+  sourceFile: string | null
+  fixed: boolean
+  attempts: number
+  detail?: string
+}
+
+/**
+ * Repair one failing test: locate the first local source the test imports, ask
+ * the LLM for a source-only fix, verify it against the frozen test, and apply it
+ * (or restore the original in dry-run). Retries up to `maxRetries`, feeding each
+ * failure back into the next prompt.
+ */
+export async function fixCodeTarget(
+  deps: FixCodeDeps,
+  testFile: string,
+  opts?: { apply?: boolean; maxRetries?: number },
+): Promise<FixTargetResult> {
+  const apply = opts?.apply ?? false
+  const maxRetries = opts?.maxRetries ?? 3
+
+  const initial = deps.runVitest(testFile)
+  if (initial.exitCode === 0) {
+    return { testFile, sourceFile: null, fixed: true, attempts: 0, detail: 'test already passes' }
+  }
+
+  const testContent = deps.readFile(testFile)
+  if (testContent === null) {
+    return {
+      testFile,
+      sourceFile: null,
+      fixed: false,
+      attempts: 0,
+      detail: 'cannot read test file',
+    }
+  }
+
+  const specifiers = collectLocalImports(testContent)
+  if (specifiers.length === 0) {
+    return {
+      testFile,
+      sourceFile: null,
+      fixed: false,
+      attempts: 0,
+      detail: 'no local imports to locate a source file',
+    }
+  }
+
+  const sourceFile = deps.resolveSourceFile(testFile, specifiers[0]!)
+  const sourceContent = deps.readFile(sourceFile)
+  if (sourceContent === null) {
+    return { testFile, sourceFile, fixed: false, attempts: 0, detail: 'cannot read source file' }
+  }
+
+  let failure = initial.output
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const prompt = buildFixPrompt({
+      testPath: testFile,
+      testContent,
+      sourcePath: sourceFile,
+      sourceContent,
+      failure,
+    })
+    const fixedContent = await deps.generateFix(prompt)
+    if (!fixedContent) continue
+
+    deps.writeFile(sourceFile, fixedContent)
+    const result = deps.runVitest(testFile)
+
+    if (result.exitCode === 0) {
+      if (!apply) deps.writeFile(sourceFile, sourceContent)
+      return { testFile, sourceFile, fixed: true, attempts: attempt }
+    }
+
+    deps.writeFile(sourceFile, sourceContent)
+    failure = result.output
+  }
+
+  return {
+    testFile,
+    sourceFile,
+    fixed: false,
+    attempts: maxRetries,
+    detail: 'fix never passed the frozen test',
+  }
+}