svharness 0.15.10 → 0.15.11

package/auto/auto-harness-detail-design.md

@@ -3,8 +3,8 @@
 > **文档定位**：`svharness auto` 模式的完整设计书，面向本系统的开发者与维护者。  
 > **上级文档**：`svharnessbuild/README.md`（CLI 总体规范）、`svharnessbuild/tmp/svharnessbuild-detail-design.md`（SDD）。  
 > **参照工程**：[snarktank/ralph](https://github.com/snarktank/ralph)（外循环思路）。  
-> **版本**：v2.5（2026-06-16，新增 Web 仪表盘、默认标志优化、优化容错）  
-> **最后更新**：2026-06-16
+> **版本**：v2.6（2026-06-26，任意错误不中断 + CostTracker 超限兜底优化）  
+> **最后更新**：2026-06-26
 
 ---
 
@@ -399,9 +399,10 @@ program
   .option('-y, --yes',               '跳过所有交互确认（推荐无人值守）')
   .option('--verbose',               '详细日志')
   // === 成本控制 ===
-  .option('--max-total-calls <n>',   '总 ACP 调用次数上限（含重试和优化），超出即冻结', '30')
+  .option('--max-total-calls <n>',   '总 ACP 调用次数上限（含重试和优化），超出即冻结', '100')
   .option('--budget-usd <amount>',   '费用预算上限（USD），超出暂停等待确认')
   .option('--cost-alert <amount>',   '单次调用费用告警阈值（USD）', '5')
+  .option('--no-auto-repair',        '禁用阶段失败自动修复（默认启用）')
   .action(runAuto);
 ```
 
@@ -440,20 +441,46 @@ class AutoOrchestrator {
     this.ensurePhaseRunnerReady();
 
     // === AGENT-2: 构建 ===
-    await this.runHarnessBuild();              // 驱动 S10→S80 全流程
+    try {
+      await this.runHarnessBuild();              // 驱动 S10→S80 全流程
+    } catch (err) {
+      // v2.6: 构建阶段失败不裸崩溃，先 emit build_failed 事件再终止
+      dashboardEventBus.emitBuildFailed(undefined);
+      throw new Error(`构建阶段失败：${err.message}；auto 构建终止，请在修复后重新执行`);
+    }
 
     // === AGENT-3 + AGENT-4: 审查 + 优化循环 ===
     let round = 0;
     while (round < this.ctx.maxOptimizeRounds) {
       round++;
-      const score = await this.runHarnessReview(round);   // 产出 第<n>评审报告.md
-      if (score.composite_score >= this.ctx.targetScore && score.gate_pass) {
+      let review;
+      try {
+        review = await this.runHarnessReview(round);   // 产出 第<n>评审报告.md
+      } catch (err) {
+        // v2.6: 资源限制（预算/调用次数超限）优雅终止，其他异常继续下一轮
+        if (err.message.includes('预算') || err.message.includes('调用次数') || err.message.includes('ACP 调用')) {
+          logger.error(`评审因资源限制终止：${err.message}`);
+          dashboardEventBus.emitBuildFailed(undefined);
+          throw err;
+        }
+        logger.warn(`评审异常：${err.message}，继续下一轮`);
+        continue;
+      }
+      if (review.composite_score >= this.ctx.targetScore && review.gate_pass) {
         await this.runFinalize();
         break;
       }
       // AGENT-4 两步：先写 第<n>轮修改-plan.md，再实施
-      await this.runOptimizePlan(round, score);
-      await this.runOptimizeImplement(round, score);
+      try {
+        await this.runOptimizePlan(round, score);
+        await this.runOptimizeImplement(round, score);
+      } catch (err) {
+        // v2.6: 资源限制 break，其他异常继续
+        if (err.message.includes('预算') || err.message.includes('次数')) {
+          break;
+        }
+        logger.warn(`第 ${round} 轮优化失败：${err.message}，继续下一轮`);
+      }
     }
   }
 }
@@ -620,13 +647,19 @@ class CostTracker {
   estimatedCostUsd: number;
   phaseCosts: Map<string, number>;
 
+  // v2.6: 80%/95% 预警告警标志（单次触发，不重复）
+  private budget80Warned = false;
+  private budget95Warned = false;
+  private calls80Warned = false;
+  private calls95Warned = false;
+
   constructor(
-    private maxTotalCalls: number,      // 默认 30
+    private maxTotalCalls: number,      // 默认 100（v2.6 从 30 提升）
     private budgetUsd: number | null,   // null = 不限制
     private alertThreshold: number,     // 默认 5 USD
   ) {}
 
-  async recordCall(phase: string, promptTokens: number, outputTokens: number): Promise<void> {
+  recordCall(phase: string, promptTokens = 0, outputTokens = 0): void {
     this.totalCalls++;
     const cost = estimateCost(promptTokens, outputTokens);
     this.estimatedCostUsd += cost;
@@ -635,14 +668,40 @@ class CostTracker {
     if (cost > this.alertThreshold) {
       logger.warn(`[成本] ${phase} 本次约 $${cost.toFixed(2)}，累计 $${this.estimatedCostUsd.toFixed(2)}`);
     }
+
+    // v2.6: 预算 80%/95% 预警告警
+    if (this.budgetUsd !== null) {
+      const usagePct = (this.estimatedCostUsd / this.budgetUsd) * 100;
+      if (usagePct >= 80 && usagePct < 95 && !this.budget80Warned) {
+        this.budget80Warned = true;
+        logger.warn(`[成本] 预算已使用 ${usagePct.toFixed(0)}%（$${this.estimatedCostUsd.toFixed(2)} / $${this.budgetUsd.toFixed(2)}），接近上限`);
+      }
+      if (usagePct >= 95 && !this.budget95Warned) {
+        this.budget95Warned = true;
+        logger.warn(`[成本] 预算已使用 ${usagePct.toFixed(0)}%（$${this.estimatedCostUsd.toFixed(2)} / $${this.budgetUsd.toFixed(2)}），即将达到上限`);
+      }
+    }
+
+    // v2.6: 调用次数 80%/95% 预警告警
+    if (this.maxTotalCalls > 0) {
+      const callsPct = (this.totalCalls / this.maxTotalCalls) * 100;
+      if (callsPct >= 80 && callsPct < 95 && !this.calls80Warned) {
+        this.calls80Warned = true;
+        logger.warn(`[成本] ACP 调用次数 ${this.totalCalls}/${this.maxTotalCalls}（${callsPct.toFixed(0)}%），接近上限`);
+      }
+      if (callsPct >= 95 && !this.calls95Warned) {
+        this.calls95Warned = true;
+        logger.warn(`[成本] ACP 调用次数 ${this.totalCalls}/${this.maxTotalCalls}（${callsPct.toFixed(0)}%），即将达到上限`);
+      }
+    }
+
     if (this.totalCalls >= this.maxTotalCalls) {
-      logger.warn(`[成本] 总调用次数 ${this.totalCalls} 已达上限 ${this.maxTotalCalls}，暂停等待确认`);
-      await enterCheckpoint('max-calls-exceeded');
+      throw new Error(`ACP 调用次数 ${this.totalCalls} 已超过上限 ${this.maxTotalCalls}，累计费用 $${this.estimatedCostUsd.toFixed(2)}`);
     }
     if (this.budgetUsd !== null && this.estimatedCostUsd >= this.budgetUsd) {
-      logger.warn(`[成本] 费用 $${this.estimatedCostUsd.toFixed(2)} 已达预算上限，暂停等待确认`);
-      await enterCheckpoint('budget-exceeded');
+      throw new Error(`ACP 估算费用 $${this.estimatedCostUsd.toFixed(2)} 已超过预算 $${this.budgetUsd.toFixed(2)}（${this.totalCalls} 次调用）`);
     }
+    dashboardEventBus.emitCostUpdated(this.estimatedCostUsd, this.totalCalls);
   }
 
   checkBudget(): 'ok' | 'alert' | 'exceeded';
@@ -650,10 +709,10 @@ class CostTracker {
 }
 ```
 
-**默认建议**（首次运行保守）：
+**默认建议**（v2.6 提升）：
 
-- `--max-total-calls 30`（约 $10–$30 API 成本）
-- `--max-optimize-rounds 2`（大多数场景 2 轮内要么通过要么卡住）
+- `--max-total-calls 100`（约 $30–$100 API 成本，覆盖完整构建+多轮优化）
+- `--max-optimize-rounds 5`（默认值不变）
 
 ### 4.5 完成标记协议
 
@@ -1265,25 +1324,68 @@ async function rerunOutdatedPhases(
 }
 ```
 
-### 6.4 失败重试策略
+### 6.4 失败重试策略（v2.6 重写）
+
+整个重试循环 + auto-repair + SKIPPED 跳过链，全部在 `PhaseRunner.runPhase()` 内实现。
+
+**流程图**：
+
+```
+for attempt = 0..maxRetriesPerPhase:
+  cost.recordCall()
+  ┌─ try-catch 捕获 CostTracker 异常 ──────────────┐
+  │  acpOk=false → tryResolveFromArtifacts(免费)     │
+  │    ├─ 命中 → DONE (「资源受限产物兜底」) ✅        │
+  │    └─ 未命中 → break 退出循环                    │
+  └─────────────────────────────────────────────────┘
+  ┌─ acpOk=true → ACP 调用 → 状态检查 ─────────────┐
+  │    ├─ 状态 DONE/SKIPPED → return ✅              │
+  │    ├─ 信号兜底 <PHASE_DONE/SKIP> → return ✅      │
+  │    └─ 产物兜底（检查磁盘产物）→ return ✅          │
+  └─────────────────────────────────────────────────┘
+
+重试循环结束后（尝试全部耗尽）：
+  1. emitPhaseFailed
+  2. if (autoRepair !== false):
+       tryAutoRepair() — 再次调 ACP 修复数据
+       ├─ ACP 修复成功 → DONE ✅
+       └─ 修复失败 → 日志警告
+  3. 标记 SKIPPED + writeBuildState → 继续下一阶段 ▶️
+     （不再 throw Error，构建不会中断）
+```
+
+**关键差异**（对比 v2.5）：
+
+| 方面 | v2.5 | v2.6 |
+|------|------|------|
+| retry 耗尽后 | `throw new Error()` | `tryAutoRepair()` + 标记 `SKIPPED` |
+| CostTracker 超限 | 异常穿透 → 进程终止 | try-catch 捕获 → 免费产物兜底 + `break` |
+| 仪表盘事件 | 无 `build_failed` | 新增全链路 `build_failed` 事件 |
+| YAML 写入 | 直接 `writeFile` | `.tmp` + `rename` 原子写入 |
+| 默认调用次数 | 30 | 100 |
+
+**`tryAutoRepair()` 实现**：
 
 ```typescript
-async retryPhase(phase: string, lastResult: AcpResult) {
-  // 分析失败原因
-  const doctorOutput = await runDoctor(this.harnessRoot, phase);
-  const fixPrompt = buildFixPrompt(phase, lastResult.output, doctorOutput);
-  
-  for (let attempt = 1; attempt <= MAX_RETRIES_PER_PHASE; attempt++) {
-    logger.warn(`${phase} 门禁未通过，第 ${attempt} 次修复尝试...`);
-    const retryResult = await this.acp.call({
-      workDir: this.harnessRoot,
-      prompt: fixPrompt
+private async tryAutoRepair(def, harnessRoot, phaseStartTime): Promise<boolean> {
+  try {
+    this.cost.recordCall(def.key + '_repair');
+    const result = await this.acp.call({
+      workDir: harnessRoot,
+      phase: def.key + '_repair',
+      prompt: wrapAcpPrompt(repairPrompt, `<PHASE_DONE>${def.short}</PHASE_DONE>`),
     });
-    const state = await readBuildState(this.harnessRoot);
-    if (state.phases[phase]?.status === 'DONE') return;
+    // 三级兜底：状态检查 → 信号兜底 → 产物兜底
+    const state = await readBuildState(harnessRoot);
+    if (phaseStatus(state, def.key) === 'DONE') return true;
+    const resolved = await this.tryResolveFromSignal(def, harnessRoot, result);
+    if (resolved) return true;
+    const artifactResolved = await this.tryResolveFromArtifacts(def, harnessRoot, result, phaseStartTime);
+    if (artifactResolved) return true;
+    return false;
+  } catch (err) {
+    return false;  // 任何异常不穿透，调用方标记 SKIPPED
   }
-  
-  throw new PhaseFailedError(phase, `超过最大重试次数 ${MAX_RETRIES_PER_PHASE}`);
 }
 ```
 
@@ -2171,8 +2273,11 @@ auto:
   dashboard: true            # v2.5 新增：启动本地 Web 仪表盘（端口 7879）
   dashboardPort: 7879        # 仪表盘 HTTP 端口
 
+  # v2.6 新增：阶段失败自动修复（默认启用）
+  autoRepair: true           # false 则禁用 ACP 自动修复，阶段失败后直接 SKIPPED
+
   # 成本控制
-  maxTotalCalls: 30
+  maxTotalCalls: 100         # v2.6 从 30 提升（对应约 $30-$100 API 成本）
   budgetUsd: null            # null = 不限制
   costAlertThreshold: 5      # USD，单次调用告警阈值
 
@@ -2180,6 +2285,7 @@ auto:
   acpMode: auto              # auto | sdk | cli-print
   acpTimeoutMs: 1800000      # 30 分钟（v2.4 从 10 分钟提升）
   maxRetriesPerPhase: 2      # 每阶段最大重试次数
+  autoRepair: true           # v2.6
   
   # 构建参数（同 svharness.config.yaml build 节）
   generateWiki: false        # build 时是否直接生成完整 wiki（false = 由 auto 驱动 ACP 生成）
@@ -2627,3 +2733,71 @@ PhaseRunner/AutoOrchestrator/CostTracker
       → broadcast SSE event → 浏览器三面板自动更新
 ```
 
+---
+
+## 附录：v2.6 实现修订记录（2026-06-26）
+
+根据审查与验证反馈，新增任意错误不中断机制与 CostTracker 超限兜底优化：
+
+| # | 文件 | 修订内容 | 类型 | 对应 § |
+|---|------|---------|------|--------|
+| 1 | `src/lib/auto-orchestrator.ts` | **runBuildPhases() try-catch**：初始构建失败时 `logger.error` + `emitBuildFailed` + 带上下文重新抛出 | Bug 修复 | §3.3 |
+| 2 | `src/lib/auto-orchestrator.ts` | **评审阶段 try-catch**：`runHarnessReview()` 单独 try-catch，资源限制优雅终止，其他异常继续下一轮 | 增强 | §3.3 |
+| 3 | `src/lib/auto-orchestrator.ts` | **优化循环 catch break**：CostTracker 超限时 `break` 而非 `continue`，避免下一轮再次触发崩溃 | Bug 修复 | §3.3 |
+| 4 | `src/lib/phase-runner.ts` | **重试耗尽 + auto-repair + SKIPPED**：ACP 重试（默认 3 次）全部耗尽后，先调 `tryAutoRepair()` 尝试 ACP 自动修复数据，修复失败则标记 SKIPPED 并继续下一阶段（不再 `throw Error`） | 新增 | §6.4 |
+| 5 | `src/lib/phase-runner.ts` | **CostTracker 超限兜底**：`cost.recordCall()` 包 try-catch，捕获后走 `else` 分支免费产物兜底 + `break` 退出重试循环；同时修复了 `if(acpOk)` 缺少闭合 brace 导致的代码结构 Bug | Bug 修复 | §6.4 |
+| 6 | `src/lib/phase-runner.ts` | **tryAutoRepair() 方法**：新增 `tryAutoRepair()` 私有方法，调用 ACP agent 诊断修复数据问题，叠加三级 fallback（状态/信号/产物） | 新增 | §6.4 |
+| 7 | `src/lib/auto-state.ts` | **YAML 原子写入**：`writeBuildState()` 改为先写 `.tmp` 再 `fs.rename` 原子替换；`readBuildState()` dedupe 修复路径也统一使用 `.tmp` + `rename` | 增强 | §6.5 |
+| 8 | `src/lib/cost-tracker.ts` | **80%/95% 预警告警**：新增 4 个一次性预警标志，预算/调用次数达到 80% 和 95% 时各触发一次 `logger.warn`；超限 `throw` 附带完整累计费用和调用次数信息 | 增强 | §4.4 |
+| 9 | `src/commands/auto.ts` | **默认值提升**：`maxTotalCalls` 默认 30→100；`autoRepair` 默认 `true` 传入 `AutoContext` | 配置 | §12.1 |
+| 10 | `src/index.ts` | **CLI 选项更新**：`--max-total-calls` 帮助文本更新为默认 100；新增 `--no-auto-repair` 选项 | 配置 | §3.1 |
+| 11 | `src/dashboard/event-bus.ts` | **build_failed 事件**：新增 `'build_failed'` 事件类型和 `emitBuildFailed()` 方法 | 新增 | §15.1 |
+| 12 | `src/dashboard/sse-handler.ts` | **build_failed 状态**：`build_failed` 事件将 `BuildSnapshot.status` 置为 `'failed'` | 增强 | §15.2 |
+| 13 | `src/dashboard/index.ts` | **事件路由**：`build_failed` 注册到事件订阅数组 | 增强 | §15.3 |
+| 14 | `src/dashboard/static/js/app.js` | **前端失败提示**：`build_failed` 处理器在日志面板显示 `❌ 构建失败` | 增强 | §15.5 |
+| 15 | `auto/templates/auto.config.example.yaml` | **示例值更新**：`maxTotalCalls: 100` | 配置 | §12.1 |
+
+### 架构变更
+
+```
+v2.5 → v2.6 关键变更：
+
+PhaseRunner.runPhase() 重试循环
+  ├── 原：cost.recordCall() 裸调用 → 异常穿透 → 进程终止
+  ├── 新：try-catch 捕获 → acpOk=false → else 分支免费产物兜底 → break
+
+  ├── 原：重试耗尽 → throw Error → 构建崩溃
+  └── 新：重试耗尽 → tryAutoRepair() → 修复成功 DONE / 修复失败 SKIPPED ▶️
+
+CostTracker.recordCall()
+  ├── 原：超限直接 throw
+  └── 新：80% → warn | 95% → warn | 100% → throw(含完整累计信息)
+
+auto-state.ts writeBuildState()
+  ├── 原：直接 writeFile
+  └── 新：writeFile(.tmp) → rename(.yaml) 原子写入
+
+仪表盘事件
+  └── 新增 build_failed（event-bus → sse-handler → app.js 全链路）
+```
+
+### 容器对比示意
+
+```
+v2.6 PhaseRunner 重试循环容器边界：
+
+for (attempt = 0; attempt <= maxRetries; attempt++) {   ← 容器：重试循环
+    try { cost.recordCall(); } catch { acpOk=false; }
+    if (acpOk) {
+        // ACP 调用 + 状态检查 + 信号兜底 + 产物兜底
+    } else {
+        // 资源耗尽：免费产物兜底 + break
+    }
+    if (attempt < maxRetries) { ... retry warning ... }
+}                                                         ← 容器闭合
+
+emitPhaseFailed                                           ← 在循环外
+if (autoRepair) { tryAutoRepair(); }                      ← 在循环外
+mark SKIPPED + writeBuildState + continue                 ← 在循环外
+```
+

package/auto/templates/auto.config.example.yaml

@@ -33,7 +33,7 @@ auto:
   acpMode: auto
   acpTimeoutMs: 600000
   maxRetriesPerPhase: 2
-  maxTotalCalls: 30
+  maxTotalCalls: 100
   budgetUsd: null
   costAlertThreshold: 5
 

package/dist/commands/auto.js

@@ -73,7 +73,7 @@ async function resolveAutoContext(positionalWorkdir, opts) {
         autoApprove: !!opts.autoApprove,
         yes: !!opts.yes,
         verbose: !!opts.verbose,
-        maxTotalCalls: normalizeInteger(opts.maxTotalCalls, 30, '--max-total-calls'),
+        maxTotalCalls: normalizeInteger(opts.maxTotalCalls, 100, '--max-total-calls'),
         budgetUsd: opts.budgetUsd ?? null,
         costAlertThreshold: normalizeNumber(opts.costAlertThreshold, 5, '--cost-alert'),
         acpMode: opts.acpMode === 'sdk' || opts.acpMode === 'cli-print' ? opts.acpMode : 'auto',
@@ -85,6 +85,7 @@ async function resolveAutoContext(positionalWorkdir, opts) {
         maxPhase: opts.maxPhase,
         goal: opts.goal,
         buildOverrides: opts,
+        autoRepair: opts.autoRepair ?? true,
     };
 }
 function normalizeNumber(value, fallback, name) {

package/dist/dashboard/event-bus.js

@@ -9,6 +9,9 @@ class DashboardEventBus extends node_events_1.EventEmitter {
     emitBuildCompleted(finalScore) {
         this.emitEvent('build_completed', { finalScore });
     }
+    emitBuildFailed(finalScore) {
+        this.emitEvent('build_failed', { finalScore });
+    }
     emitPhaseStarted(key, short, description, attempt) {
         this.emitEvent('phase_started', { key, short, description, attempt });
     }

package/dist/dashboard/index.js

@@ -24,7 +24,7 @@ function startDashboard(port = 7879) {
         server = (0, server_1.createServer)(event_bus_1.dashboardEventBus, sseManager);
         // Subscribe to all events from the bus and forward to SSE clients
         const eventTypes = [
-            'build_started', 'build_completed',
+            'build_started', 'build_completed', 'build_failed',
             'phase_started', 'phase_completed', 'phase_failed',
             'acp_output',
             'cost_updated', 'score_updated',

package/dist/dashboard/sse-handler.js

@@ -101,6 +101,9 @@ class SseManager {
                     this.buildSnapshot.score = event.data.finalScore;
                 }
                 break;
+            case 'build_failed':
+                this.buildSnapshot.status = 'failed';
+                break;
         }
     }
     getSnapshot() {

package/dist/dashboard/static/js/app.js

@@ -323,6 +323,11 @@ function connectSSE() {
       addLog({ type: 'success', text: `✅ 构建完成！${data.finalScore != null ? `最终评分: ${data.finalScore}` : ''}`, timestamp: Date.now() });
       updateStatus();
     },
+    build_failed() {
+      state.status = 'failed';
+      addLog({ type: 'error', text: '❌ 构建失败！请检查终端日志', timestamp: Date.now() });
+      updateStatus();
+    },
     phase_started(data) {
       state.currentPhase = data.key;
       state.phaseStatuses[data.key] = 'IN_PROGRESS';

package/dist/index.js

@@ -255,7 +255,7 @@ function main() {
         .option('--auto-approve', '自动通过无人值守下的表单门禁')
         .option('-y, --yes', '跳过交互确认')
         .option('--verbose', '显示详细日志')
-        .option('--max-total-calls <n>', 'ACP 调用次数上限（默认 30）', (v) => Number(v))
+        .option('--max-total-calls <n>', 'ACP 调用次数上限（默认 100）', (v) => Number(v))
         .option('--budget-usd <amount>', '费用预算上限（USD）', (v) => Number(v))
         .option('--cost-alert <amount>', '单次调用费用告警阈值（USD）', (v) => Number(v))
         .option('--acp-mode <mode>', 'ACP 模式：auto | cli-print | sdk')
@@ -264,6 +264,7 @@ function main() {
         .option('--prompt-dir <path>', '覆盖 auto phase prompt 模板目录')
         .option('--baseline-auto-extract <mode>', 'explicit | conservative | disabled')
         .option('--convert-endpoint <url>', 'markitdown_serve 基址')
+        .option('--no-auto-repair', '禁用阶段失败自动修复（默认启用）')
         .action(async (workdir, opts, cmd) => {
         try {
             await (0, auto_1.runAuto)(workdir, {

package/dist/lib/auto-orchestrator.js

@@ -67,7 +67,15 @@ class AutoOrchestrator {
         this.phaseRunner = new phase_runner_1.PhaseRunner(this.ctx, this.acp, this.cost);
         event_bus_1.dashboardEventBus.emitBuildStarted(phase_runner_1.PHASE_DEFS.length);
         await this.ensureReviewRubric();
-        await this.phaseRunner.runBuildPhases();
+        try {
+            await this.phaseRunner.runBuildPhases();
+        }
+        catch (err) {
+            const msg = err.message;
+            logger_1.logger.error(`[auto] 构建阶段执行失败：${msg}`);
+            event_bus_1.dashboardEventBus.emitBuildFailed(undefined);
+            throw new Error(`构建阶段失败：${msg}；auto 构建终止，请在修复后重新执行`);
+        }
         if (this.ctx.maxPhase && phaseNumber(this.ctx.maxPhase) < 85) {
             logger_1.logger.info(`已到达 --max-phase ${this.ctx.maxPhase}，跳过评审优化`);
             event_bus_1.dashboardEventBus.emitBuildCompleted(undefined);
@@ -77,7 +85,20 @@ class AutoOrchestrator {
         let finalReview;
         for (let round = 1; round <= this.ctx.maxOptimizeRounds; round++) {
             event_bus_1.dashboardEventBus.emitReviewStarted(round);
-            const review = await this.runHarnessReview(round);
+            let review;
+            try {
+                review = await this.runHarnessReview(round);
+            }
+            catch (err) {
+                const msg = err.message;
+                if (msg.includes('预算') || msg.includes('调用次数') || msg.includes('ACP 调用')) {
+                    logger_1.logger.error(`[auto] 第 ${round} 轮评审因资源限制终止：${msg}`);
+                    event_bus_1.dashboardEventBus.emitBuildFailed(undefined);
+                    throw err; // 资源限制是整个流程的硬终止
+                }
+                logger_1.logger.warn(`[auto] 第 ${round} 轮评审异常：${msg}，继续下一轮`);
+                continue;
+            }
             event_bus_1.dashboardEventBus.emitReviewCompleted(round, review.composite_score, review.critical_count);
             event_bus_1.dashboardEventBus.emitScoreUpdated(review.composite_score, round);
             if (review.composite_score >= this.ctx.targetScore &&
@@ -103,7 +124,12 @@ class AutoOrchestrator {
                 event_bus_1.dashboardEventBus.emitOptimizeCompleted(round);
             }
             catch (err) {
-                logger_1.logger.warn(`第 ${round} 轮优化执行失败：${err.message}，状态重置已完成，下一轮可继续`);
+                const msg = err.message;
+                if (msg.includes('预算') || msg.includes('次数') || msg.includes('ACP 调用')) {
+                    logger_1.logger.warn(`[auto] 第 ${round} 轮优化因资源限制终止：${msg}`);
+                    break; // 资源限制触发时终止优化循环，保留当前评分
+                }
+                logger_1.logger.warn(`第 ${round} 轮优化执行失败：${msg}，状态重置已完成，下一轮可继续`);
             }
         }
         event_bus_1.dashboardEventBus.emitCostUpdated(this.cost.report().estimatedCostUsd, this.cost.report().totalCalls);

package/dist/lib/auto-state.js

@@ -74,7 +74,9 @@ async function readBuildState(harnessRoot) {
         if (err instanceof js_yaml_1.default.YAMLException && err.message.includes('duplicated mapping key')) {
             const fixed = dedupePhases(raw);
             // Persist the fixed content so subsequent reads also succeed
-            await fs_extra_1.default.writeFile(statePath, fixed, 'utf8');
+            const tmpPath = statePath + '.tmp';
+            await fs_extra_1.default.writeFile(tmpPath, fixed, 'utf8');
+            await fs_extra_1.default.rename(tmpPath, statePath);
             const fixedBody = fixed.replace(/^#.*\n/gm, '');
             const state = (js_yaml_1.default.load(fixedBody) ?? {});
             state.phases = state.phases ?? {};
@@ -85,7 +87,12 @@ async function readBuildState(harnessRoot) {
 }
 async function writeBuildState(harnessRoot, state) {
     const statePath = node_path_1.default.join(harnessRoot, '.harness-build-state.yaml');
-    await fs_extra_1.default.writeFile(statePath, STATE_HEADER + js_yaml_1.default.dump(state, { lineWidth: 100, noRefs: true, sortKeys: false }), 'utf8');
+    const tmpPath = statePath + '.tmp';
+    const content = STATE_HEADER + js_yaml_1.default.dump(state, { lineWidth: 100, noRefs: true, sortKeys: false });
+    // Write to temp file first, then atomic rename to prevent partial writes
+    // on process kill. On the same filesystem, rename is atomic.
+    await fs_extra_1.default.writeFile(tmpPath, content, 'utf8');
+    await fs_extra_1.default.rename(tmpPath, statePath);
 }
 function phaseStatus(state, phase) {
     return state.phases?.[phase]?.status;

package/dist/lib/cost-tracker.js

@@ -11,6 +11,10 @@ class CostTracker {
     totalCalls = 0;
     estimatedCostUsd = 0;
     phaseCosts = new Map();
+    budget80Warned = false;
+    budget95Warned = false;
+    calls80Warned = false;
+    calls95Warned = false;
     constructor(maxTotalCalls, budgetUsd, alertThreshold) {
         this.maxTotalCalls = maxTotalCalls;
         this.budgetUsd = budgetUsd;
@@ -24,11 +28,35 @@ class CostTracker {
         if (cost > this.alertThreshold) {
             logger_1.logger.warn(`[成本] ${phase} 本次约 $${cost.toFixed(2)}，累计 $${this.estimatedCostUsd.toFixed(2)}`);
         }
+        // Budget pre-warnings (80% → 95% → hard limit)
+        if (this.budgetUsd !== null) {
+            const usagePct = (this.estimatedCostUsd / this.budgetUsd) * 100;
+            if (usagePct >= 80 && usagePct < 95 && !this.budget80Warned) {
+                this.budget80Warned = true;
+                logger_1.logger.warn(`[成本] 预算已使用 ${usagePct.toFixed(0)}%（$${this.estimatedCostUsd.toFixed(2)} / $${this.budgetUsd.toFixed(2)}），接近上限`);
+            }
+            if (usagePct >= 95 && !this.budget95Warned) {
+                this.budget95Warned = true;
+                logger_1.logger.warn(`[成本] 预算已使用 ${usagePct.toFixed(0)}%（$${this.estimatedCostUsd.toFixed(2)} / $${this.budgetUsd.toFixed(2)}），即将达到上限`);
+            }
+        }
+        // Call count pre-warnings (80% → 95% → hard limit)
+        if (this.maxTotalCalls > 0) {
+            const callsPct = (this.totalCalls / this.maxTotalCalls) * 100;
+            if (callsPct >= 80 && callsPct < 95 && !this.calls80Warned) {
+                this.calls80Warned = true;
+                logger_1.logger.warn(`[成本] ACP 调用次数 ${this.totalCalls}/${this.maxTotalCalls}（${callsPct.toFixed(0)}%），接近上限`);
+            }
+            if (callsPct >= 95 && !this.calls95Warned) {
+                this.calls95Warned = true;
+                logger_1.logger.warn(`[成本] ACP 调用次数 ${this.totalCalls}/${this.maxTotalCalls}（${callsPct.toFixed(0)}%），即将达到上限`);
+            }
+        }
         if (this.totalCalls > this.maxTotalCalls) {
-            throw new Error(`ACP 调用次数 ${this.totalCalls} 已超过上限 ${this.maxTotalCalls}`);
+            throw new Error(`ACP 调用次数 ${this.totalCalls} 已超过上限 ${this.maxTotalCalls}，累计费用 $${this.estimatedCostUsd.toFixed(2)}`);
         }
         if (this.budgetUsd !== null && this.estimatedCostUsd > this.budgetUsd) {
-            throw new Error(`ACP 估算费用 $${this.estimatedCostUsd.toFixed(2)} 已超过预算 $${this.budgetUsd.toFixed(2)}`);
+            throw new Error(`ACP 估算费用 $${this.estimatedCostUsd.toFixed(2)} 已超过预算 $${this.budgetUsd.toFixed(2)}（${this.totalCalls} 次调用）`);
         }
         event_bus_1.dashboardEventBus.emitCostUpdated(this.estimatedCostUsd, this.totalCalls);
     }

package/dist/lib/phase-prompt-loader.js

@@ -8,6 +8,7 @@ exports.renderPrompt = renderPrompt;
 exports.wrapAcpPrompt = wrapAcpPrompt;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../utils/logger");
 const auto_assets_1 = require("./auto-assets");
 async function loadPhasePrompt(templateName, vars, promptDirOverride) {
     const assets = (0, auto_assets_1.resolveAutoAssetPaths)(promptDirOverride);
@@ -21,6 +22,9 @@ async function loadPhasePrompt(templateName, vars, promptDirOverride) {
 function renderPrompt(template, vars) {
     return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (match, key) => {
         const value = vars[key];
+        if (value === undefined || value === null) {
+            logger_1.logger.warn(`prompt 模板中占位符 {{${key}}} 未提供值，保留原样`);
+        }
         return value === undefined || value === null ? match : String(value);
     });
 }

package/dist/lib/phase-runner.js

@@ -107,61 +107,108 @@ class PhaseRunner {
             logger_1.logger.plain(`\n--- ${def.key} prompt ---\n${prompt}\n`);
             return;
         }
-        // Prepend a non-interactive preamble to every ACP prompt.  This prevents
-        // Claude from asking questions or waiting for confirmation (it has no
-        // stdin backchannel in --print mode) and forces a completion signal as
-        // the very last line of output so the harness can detect phase completion
-        // reliably.
-        const boundedPrompt = (0, phase_prompt_loader_1.wrapAcpPrompt)(prompt, `<PHASE_DONE>${def.short}</PHASE_DONE>`);
         for (let attempt = 0; attempt <= this.ctx.maxRetriesPerPhase; attempt++) {
-            this.cost.recordCall(def.key);
-            const result = await this.acp.call({
-                workDir: harnessRoot,
-                phase: def.key,
-                prompt: boundedPrompt,
-                timeoutMs: this.ctx.acpTimeoutMs,
-                onData: (text) => event_bus_1.dashboardEventBus.emitAcpOutput(def.key, text),
-            });
-            await this.writeAcpLog(def.short, result.output, result.error);
-            if (!result.success) {
-                logger_1.logger.warn(`${def.key} ACP 调用失败：${result.error ?? 'unknown error'}`);
+            // Recalculate boundedPrompt inside the retry loop so each attempt gets:
+            // 1) A fresh wrap with the attempt number in context, and
+            // 2) Awareness of any partial artifacts left by previous attempts.
+            // Without this, every retry receives the same prompt and Claude would
+            // start from scratch rather than incrementally fixing.
+            const attemptPrompt = attempt > 0
+                ? `[重试第 ${attempt} 次] 这是第 ${attempt} 次尝试。如果上一次尝试已经产生了部分文件，请检查并修复它们，不要从头开始。\n${prompt}`
+                : prompt;
+            const boundedPrompt = (0, phase_prompt_loader_1.wrapAcpPrompt)(attemptPrompt, `<PHASE_DONE>${def.short}</PHASE_DONE>`);
+            // Try ACP call; on CostTracker budget/call-limit error, fall back to
+            // free recovery checks (signal + artifact detection) without crashing.
+            let acpOk = true;
+            try {
+                this.cost.recordCall(def.key);
             }
-            const after = await (0, auto_state_1.readBuildState)(harnessRoot);
-            const afterStatus = (0, auto_state_1.phaseStatus)(after, def.key);
-            if (afterStatus === 'DONE' || afterStatus === 'SKIPPED') {
-                const elapsed = Date.now() - phaseStartTime;
-                event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, afterStatus, elapsed);
-                const label = afterStatus === 'DONE' ? '✅ 完成' : '⏭️ 跳过';
-                logger_1.logger.success(`${def.key} ${label}`);
-                return;
+            catch (err) {
+                acpOk = false;
+                logger_1.logger.warn(`${def.key} 资源限制：${err.message}，跳过 ACP 调用并尝试产物兜底`);
             }
-            // Fallback: Claude may have emitted a completion signal in its text output
-            // but failed to edit the YAML state file.  Rely on the signal instead.
-            const resolved = await this.tryResolveFromSignal(def, harnessRoot, result);
-            if (resolved) {
-                const elapsed = Date.now() - phaseStartTime;
-                event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, resolved, elapsed);
-                const label = resolved === 'DONE' ? '✅ 完成（信号兜底）' : '⏭️ 跳过（信号兜底）';
-                logger_1.logger.success(`${def.key} ${label}`);
-                return;
+            if (acpOk) {
+                const result = await this.acp.call({
+                    workDir: harnessRoot,
+                    phase: def.key,
+                    prompt: boundedPrompt,
+                    timeoutMs: this.ctx.acpTimeoutMs,
+                    onData: (text) => event_bus_1.dashboardEventBus.emitAcpOutput(def.key, text),
+                });
+                await this.writeAcpLog(def.short, result.output, result.error);
+                if (!result.success) {
+                    logger_1.logger.warn(`${def.key} ACP 调用失败：${result.error ?? 'unknown error'}`);
+                }
+                const after = await (0, auto_state_1.readBuildState)(harnessRoot);
+                const afterStatus = (0, auto_state_1.phaseStatus)(after, def.key);
+                if (afterStatus === 'DONE' || afterStatus === 'SKIPPED') {
+                    const elapsed = Date.now() - phaseStartTime;
+                    event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, afterStatus, elapsed);
+                    const label = afterStatus === 'DONE' ? '✅ 完成' : '⏭️ 跳过';
+                    logger_1.logger.success(`${def.key} ${label}`);
+                    return;
+                }
+                // Fallback: Claude may have emitted a completion signal in its text output
+                // but failed to edit the YAML state file.  Rely on the signal instead.
+                const resolved = await this.tryResolveFromSignal(def, harnessRoot, result);
+                if (resolved) {
+                    const elapsed = Date.now() - phaseStartTime;
+                    event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, resolved, elapsed);
+                    const label = resolved === 'DONE' ? '✅ 完成（信号兜底）' : '⏭️ 跳过（信号兜底）';
+                    logger_1.logger.success(`${def.key} ${label}`);
+                    return;
+                }
+                // Fallback: detect phase completion by checking for expected output artifacts.
+                // Some phases (e.g. S40_extract_requirements) may have produced all required
+                // artifacts even though Claude failed to emit the completion signal or update the
+                // YAML state file.  Detect and resolve programmatically to avoid false retries.
+                const artifactResolved = await this.tryResolveFromArtifacts(def, harnessRoot, result, phaseStartTime);
+                if (artifactResolved) {
+                    const elapsed = Date.now() - phaseStartTime;
+                    event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, artifactResolved, elapsed);
+                    logger_1.logger.success(`${def.key} ✅ 完成（产物兜底检测）`);
+                    return;
+                }
             }
-            // Fallback: detect phase completion by checking for expected output artifacts.
-            // Some phases (e.g. S40_extract_requirements) may have produced all required
-            // artifacts even though Claude failed to emit the completion signal or update the
-            // YAML state file.  Detect and resolve programmatically to avoid false retries.
-            const artifactResolved = await this.tryResolveFromArtifacts(def, harnessRoot);
-            if (artifactResolved) {
-                const elapsed = Date.now() - phaseStartTime;
-                event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, artifactResolved, elapsed);
-                logger_1.logger.success(`${def.key} ✅ 完成（产物兜底检测）`);
-                return;
+            else {
+                // Budget/call-limit exhausted: skip ACP but try free artifact fallback.
+                // The previous ACP attempt (which was already paid for) may have left valid
+                // artifacts on disk even though the state file wasn't updated to DONE.
+                logger_1.logger.warn(`${def.key} 资源已耗尽，尝试产物兜底恢复...`);
+                const artifactResolved = await this.tryResolveFromArtifacts(def, harnessRoot, { success: true }, phaseStartTime);
+                if (artifactResolved) {
+                    const elapsed = Date.now() - phaseStartTime;
+                    event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, artifactResolved, elapsed);
+                    logger_1.logger.success(`${def.key} ✅ 完成（资源受限产物兜底）`);
+                    return;
+                }
+                // Break out of retry loop — no more ACP calls are possible.
+                break;
             }
             if (attempt < this.ctx.maxRetriesPerPhase) {
                 logger_1.logger.warn(`${def.key} 未更新为 DONE/SKIPPED，准备重试第 ${attempt + 1} 次`);
             }
         }
         event_bus_1.dashboardEventBus.emitPhaseFailed(def.key, 'state 未更新为 DONE/SKIPPED', this.ctx.maxRetriesPerPhase);
-        throw new Error(`${def.key} 未完成：state 未更新为 DONE/SKIPPED`);
+        // All retries exhausted — try ACP auto-repair before giving up
+        if (this.ctx.autoRepair !== false) {
+            logger_1.logger.warn(`${def.key} 重试耗尽，启动 ACP 自动修复...`);
+            const repaired = await this.tryAutoRepair(def, harnessRoot, phaseStartTime);
+            if (repaired) {
+                const elapsed = Date.now() - phaseStartTime;
+                event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, 'DONE', elapsed);
+                logger_1.logger.success(`${def.key} ✅ 完成（ACP 自动修复）`);
+                return;
+            }
+            logger_1.logger.warn(`${def.key} ACP 自动修复未生效`);
+        }
+        // Don't throw — mark as SKIPPED so the build continues to subsequent phases
+        logger_1.logger.warn(`${def.key} 已耗尽所有重试次数，标记 SKIPPED 后继续执行后续阶段`);
+        const skipState = await (0, auto_state_1.readBuildState)(harnessRoot);
+        (0, auto_state_1.setPhaseStatus)(skipState, def.key, 'SKIPPED');
+        skipState.phases[def.key].note = '重试耗尽且自动修复未生效，已自动跳过';
+        await (0, auto_state_1.writeBuildState)(harnessRoot, skipState);
+        event_bus_1.dashboardEventBus.emitPhaseCompleted(def.key, 'SKIPPED', Date.now() - phaseStartTime);
     }
     async runMechanicalPre(def) {
         if (!this.ctx.harnessRoot || this.ctx.dryRun)
@@ -270,8 +317,14 @@ class PhaseRunner {
             await (0, auto_state_1.writeBuildState)(harnessRoot, state);
             return targetStatus;
         }
-        // <AUTO_SIGNAL>: any signal value resolves as DONE (used by S85/optimize phases)
+        // <AUTO_SIGNAL>: resolves as DONE for any signal value.
+        // Note: this branch is only reachable for phase-runner phases (S10-S80),
+        // which all use <PHASE_DONE> signals via wrapAcpPrompt, not <AUTO_SIGNAL>.
+        // The <AUTO_SIGNAL> protocol is used by auto-optimize.ts and auto-review.ts
+        // which bypass PhaseRunner entirely.  If this fires unexpectedly, the log
+        // below provides an audit trail.
         if (autoSignal) {
+            logger_1.logger.warn(`${def.key} 收到意外 AUTO_SIGNAL「${autoSignal[1]}」（phase-runner 阶段应使用 PHASE_DONE）、自动标记 DONE`);
             const state = await (0, auto_state_1.readBuildState)(harnessRoot);
             (0, auto_state_1.setPhaseStatus)(state, def.key, 'DONE');
             await (0, auto_state_1.writeBuildState)(harnessRoot, state);
@@ -281,27 +334,48 @@ class PhaseRunner {
     }
     /**
      * Detect phase completion by checking for expected output artifacts on disk.
-     * Used as a last-resort fallback when Claude completed the work but failed to
-     * emit <PHASE_DONE> or update the YAML state file.
+     * Used when ACP succeeded but failed to emit a completion signal or update
+     * the YAML state file.
      *
-     * Each phase defines its own detection criteria.
+     * Only runs when result.success === true — ACP failure artifacts are too
+     * unreliable to use as a completion signal.
      */
-    async tryResolveFromArtifacts(def, harnessRoot) {
+    async tryResolveFromArtifacts(def, harnessRoot, result, phaseStartTime) {
+        // Only use artifact fallback when ACP actually succeeded.
+        // Failed ACP calls may leave partial/incomplete artifacts that would
+        // cause false-positive phase resolution, bypassing retry logic.
+        if (!result.success)
+            return null;
         try {
             switch (def.key) {
                 case 'S40_extract_requirements': {
                     const yamlDir = node_path_1.default.join(harnessRoot, 'requirements', 'yaml');
                     if (await fs_extra_1.default.pathExists(yamlDir)) {
                         const entries = await fs_extra_1.default.readdir(yamlDir);
-                        const yamlFiles = entries.filter((e) => e.endsWith('.yaml'));
+                        const yamlFiles = entries
+                            .filter((e) => e.endsWith('.yaml'));
                         if (yamlFiles.length > 0) {
-                            break; // qualified → mark DONE below
+                            // Verify at minimum that the yaml file has substantive content
+                            // created during or after this phase started.
+                            const validYamlFiles = (await Promise.all(yamlFiles.map(async (f) => {
+                                const fp = node_path_1.default.join(yamlDir, f);
+                                try {
+                                    const stat = await fs_extra_1.default.stat(fp);
+                                    return stat.size > 50 && stat.mtimeMs >= phaseStartTime - 5000;
+                                }
+                                catch {
+                                    return false;
+                                }
+                            }))).filter(Boolean);
+                            if (validYamlFiles.length > 0)
+                                break; // qualified
                         }
                     }
                     return null;
                 }
                 case 'S50_generate_specs': {
                     // specs/ must have at least one non-empty subdirectory
+                    // with a non-trivial .md or .yaml file (>100 bytes) created during this phase.
                     const specsDir = node_path_1.default.join(harnessRoot, 'specs');
                     let found = false;
                     if (await fs_extra_1.default.pathExists(specsDir)) {
@@ -309,24 +383,43 @@ class PhaseRunner {
                             .filter((e) => e !== '_work');
                         for (const sub of subs) {
                             const subDir = node_path_1.default.join(specsDir, sub);
-                            const stat = await fs_extra_1.default.stat(subDir);
+                            let stat;
+                            try {
+                                stat = await fs_extra_1.default.stat(subDir);
+                            }
+                            catch {
+                                continue;
+                            }
                             if (stat.isDirectory()) {
                                 const files = await fs_extra_1.default.readdir(subDir);
-                                if (files.some((f) => f.endsWith('.md') || f.endsWith('.yaml'))) {
-                                    found = true;
-                                    break; // break for loop only; 'found' carries the result
+                                for (const f of files) {
+                                    if (!f.endsWith('.md') && !f.endsWith('.yaml'))
+                                        continue;
+                                    const fp = node_path_1.default.join(subDir, f);
+                                    try {
+                                        const fstat = await fs_extra_1.default.stat(fp);
+                                        if (fstat.size > 100 && fstat.mtimeMs >= phaseStartTime - 5000) {
+                                            found = true;
+                                            break;
+                                        }
+                                    }
+                                    catch {
+                                        continue;
+                                    }
                                 }
+                                if (found)
+                                    break;
                             }
                         }
                     }
                     if (found)
-                        break; // break switch → mark DONE
+                        break;
                     return null;
                 }
                 case 'S60_process_references': {
                     // references/yaml/index.yaml is the primary output artifact
                     const indexYaml = node_path_1.default.join(harnessRoot, 'references', 'yaml', 'index.yaml');
-                    if (await fs_extra_1.default.pathExists(indexYaml)) {
+                    if (await fs_extra_1.default.pathExists(indexYaml) && await isRecentFile(indexYaml, phaseStartTime)) {
                         break; // qualified
                     }
                     // Also accept SKIPPED state if references/md/ is empty (no references to process)
@@ -345,27 +438,25 @@ class PhaseRunner {
                     return null;
                 }
                 case 'S65_customize_agent_env': {
-                    // agent-env/rules/ or agent-env/skills/ has content
+                    // agent-env/rules/ or agent-env/skills/ has content from this phase
                     const rulesDir = node_path_1.default.join(harnessRoot, 'agent-env', 'rules');
                     const skillsDir = node_path_1.default.join(harnessRoot, 'agent-env', 'skills');
-                    if (await hasNonEmptyFiles(rulesDir) || await hasAnySubdirWithFiles(skillsDir)) {
+                    if (await hasNonGitkeepEntries(rulesDir) || await hasAnySubdirWithFiles(skillsDir)) {
                         break; // qualified
                     }
                     return null;
                 }
                 case 'S70_runtime_assets': {
-                    // Check tasks/ or agent-env/skills/ or agent-env/rules/ for content
+                    // Check tasks/ for content; avoid skills/ overlap with S65 detection.
                     const s70TasksDir = node_path_1.default.join(harnessRoot, 'tasks');
-                    const s70SkillsDir = node_path_1.default.join(harnessRoot, 'agent-env', 'skills');
-                    if (await hasNonEmptyFiles(s70TasksDir) ||
-                        await hasAnySubdirWithFiles(s70SkillsDir)) {
+                    if (await hasNonGitkeepEntries(s70TasksDir)) {
                         break; // qualified
                     }
                     return null;
                 }
                 case 'S80_seed_memory': {
                     const memoryInbox = node_path_1.default.join(harnessRoot, 'agent-env', 'memory', 'inbox');
-                    if (await hasNonEmptyFiles(memoryInbox)) {
+                    if (await hasNonGitkeepEntries(memoryInbox)) {
                         break; // qualified
                     }
                     return null;
@@ -381,8 +472,53 @@ class PhaseRunner {
             await (0, auto_state_1.writeBuildState)(harnessRoot, state);
             return 'DONE';
         }
-        catch {
-            return null; // silently fall through to normal retry on any filesystem error
+        catch (err) {
+            // Log IO errors rather than swallowing them silently.
+            // Previously this was a bare catch {} which masked real filesystem
+            // issues (permissions, disk full, race conditions).
+            logger_1.logger.warn(`${def.key} 产物兜底检测异常：${err instanceof Error ? err.message : String(err)}`);
+            return null; // fall through to normal retry
+        }
+    }
+    /**
+     * Try to auto-repair a failed phase by calling ACP with a diagnosis prompt.
+     * The ACP agent inspects the harness, fixes data issues, and updates the state.
+     */
+    async tryAutoRepair(def, harnessRoot, phaseStartTime) {
+        try {
+            const desc = PHASE_DESC[def.key] ?? def.key;
+            const repairPrompt = `[ACP AUTO-REPAIR] 阶段 ${def.key}（${desc}）执行失败。\n\n` +
+                `请检查 harness 目录 ${harnessRoot}，识别并修复该阶段应产生的产物问题，\n` +
+                `然后更新 .harness-build-state.yaml 中 ${def.key} 的状态为 DONE。\n\n` +
+                `注意：\n` +
+                `1. 只关注 ${def.key} 阶段的问题，不要修改其他阶段的产物或状态\n` +
+                `2. 修复完成后务必在输出末尾输出 <PHASE_DONE>${def.short}</PHASE_DONE>\n`;
+            this.cost.recordCall(def.key + '_repair');
+            const result = await this.acp.call({
+                workDir: harnessRoot,
+                phase: def.key + '_repair',
+                prompt: (0, phase_prompt_loader_1.wrapAcpPrompt)(repairPrompt, `<PHASE_DONE>${def.short}</PHASE_DONE>`),
+                timeoutMs: this.ctx.acpTimeoutMs,
+            });
+            await this.writeAcpLog(def.short + '-repair', result.output, result.error);
+            // Check state
+            const after = await (0, auto_state_1.readBuildState)(harnessRoot);
+            const afterStatus = (0, auto_state_1.phaseStatus)(after, def.key);
+            if (afterStatus === 'DONE' || afterStatus === 'SKIPPED')
+                return true;
+            // Check signal fallback
+            const resolved = await this.tryResolveFromSignal(def, harnessRoot, result);
+            if (resolved)
+                return true;
+            // Check artifact fallback
+            const artifactResolved = await this.tryResolveFromArtifacts(def, harnessRoot, result, phaseStartTime);
+            if (artifactResolved)
+                return true;
+            return false;
+        }
+        catch (err) {
+            logger_1.logger.warn(`${def.key} 自动修复异常：${err instanceof Error ? err.message : String(err)}`);
+            return false;
         }
     }
     async writeAcpLog(phase, output, error) {
@@ -399,8 +535,8 @@ function phaseNumber(phase) {
     const match = phase.match(/^S(\d+)/i);
     return match ? Number(match[1]) : Number.POSITIVE_INFINITY;
 }
-/** Check if a directory exists and contains at least one file (excluding .gitkeep). */
-async function hasNonEmptyFiles(dir) {
+/** Check if a directory exists and contains at least one entry (excluding .gitkeep). */
+async function hasNonGitkeepEntries(dir) {
     if (!(await fs_extra_1.default.pathExists(dir)))
         return false;
     const entries = await fs_extra_1.default.readdir(dir);
@@ -422,3 +558,19 @@ async function hasAnySubdirWithFiles(dir) {
     }
     return false;
 }
+/**
+ * Check if a file was last modified at or after a given timestamp.
+ * Used to distinguish artifacts produced by the current phase attempt
+ * from stale files left by a previous build, preventing false-positive
+ * artifact detection.
+ */
+async function isRecentFile(filePath, sinceMs) {
+    try {
+        const stat = await fs_extra_1.default.stat(filePath);
+        // Allow 5-second tolerance for filesystem timestamp granularity
+        return stat.mtimeMs >= sinceMs - 5000;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.15.10",
+  "version": "0.15.11",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",