feat(24_miracle): external-Judge evaluation and replay-driven HL loop

[thugongheng]

概述

本 PR 将 24_miracle 接入迁移到 worktree/framework 基线，并完成原适配器 PR 评审提出的全部必修修改。

主要新增：

• 跨平台 external-Judge 评测适配器；
• Windows/Linux 进程树清理；
• result/progress 原子写入与中断恢复；
• 严格的同 session 矩阵断点续跑；
• Framework 统一 game 事件封装；
• 退出码、超时、异常、Replay SHA 和清理状态等一手字段；
• 基础设施异常分类；
• Replay 驱动的 Coding Agent 迭代入口；
• 一个完整、脱敏的最小 HL smoke 闭环报告。

本 PR 是原 PR #1 基于新 Framework 的迁移版本。原 PR 暂不关闭，由维护者决定后续处理方式。

原评审问题修复

• run.toml 已包含 Framework 要求的生命周期字段。
• Matrix 事件复用统一 Framework envelope。
• CI 可从 events.jsonl 独立重算 attempts、valid games 和 win rate。
• --resume 会验证 manifest、完整 plan、run identity、代码/资产哈希，以及 progress/events/audit 一致性。
• 已完成的 attempt 不会重跑。
• POSIX 自有子进程会被显式 wait() 回收。
• vendor result JSON 使用临时文件、flush/fsync 和 replace。
• vendor exception、非零返回码和 cleanup failure 不会被包装成有效胜负。
• MatchAttempt 的一手字段完整传入 GameOutcome 和最终 events。
• Matrix 输出使用候选目录验证、事务式 promotion 和中断恢复。
• Windows 原子写使用唯一临时文件，并仅对明确的临时共享错误进行有界重试。
• Judge/Replay 路径在启动前规范化为绝对执行路径，避免受 Judge cwd 影响。

测试与验收

最新完整测试结果：

• Windows Python 3.13：298 passed
• Windows Python 3.11：298 passed
• Linux Python 3.11：297 passed，1 skipped

Linux 唯一 skip：

test_upstream_aggregate_emits_invalid_toml_on_windows

该测试只验证 Windows 路径分隔符行为；Linux Results pipeline 已实际运行并通过。

其他验收：

• Windows/Linux 真实 promotion 进程强杀与恢复通过；
• Linux POSIX 进程树测试通过；
• 本地 iteration data check：4 valid，0 invalid；
• 无残留 Judge/AI/run_match 进程；
• 提交的 HL 审计材料无本机路径或凭据。

最小 HL 闭环

本 PR 完成了一次可审计的最小 smoke 闭环：

1. 注册不可变策略 miracle_ifelse/v0；
2. 对 rank04 train 和 rank09 validation 进行换边评测；
3. 只向 Codex 提供脱敏后的 rank04 训练回放；
4. 在隔离工作区中调用一次 Codex；
5. 保存不可变策略 miracle_ifelse/v1；
6. 使用相同的四局计划重新评测 v1。

结果：

• v0：4 valid，2W/2L；
• v1：4 valid，2W/2L；
• validation raw：0.5；
• validation evo：0.5；
• gain：0.0；
• Codex 调用：1 次；
• tool calls：10；
• token：135,157 input / 1,459 output / 136,616 total；
• Agent wall-clock：52.88 秒。

v1 的修改是将 camp1 默认 opening 从 FF 改为 SF。

该结果属于非确定性、小样本基础设施 smoke。闭环成功表示流程已跑通，不代表 v1 相比 v0 获得了统计显著的性能提升。

审计限制

成功 iteration session 在运行前遗漏了 manifest.json。

本地证据中已补充 post-hoc reconstructed manifest，并明确标记：

• manifest_status=POSTHOC_RECONSTRUCTED
• manifest_missing_at_execution=true
• pre_registered=false
• generated_after_completion=true

该文件仅用于事后审计，不表述为预注册记录。

Provider 原始 JSONL、Replay、策略副本、人类对手源码、二进制、.smoke/ session 和本机路径均只保留在本地，不进入本 PR。

不在本 PR 范围内

• 不运行新的完整矩阵；
• 不进行 RL 训练；
• 不进行 hidden evaluation；
• 不上传 Results；
• 不声称 v1 优于 v0。

[thugongheng]

已追加修复提交 0c6f40d：

• 清理公开 protocol/roster 中的本机绝对路径；
• protocol/roster 控制输入 SHA 改为 UTF-8 + LF 规范化计算；
• 策略、Judge、exe、zip 仍使用原始字节 SHA；
• 保留历史执行 protocol SHA 866696fd...，公开脱敏控制副本 SHA 为 f64b948c...；
• Windows Python 3.13：310 passed，6 skipped，0 failed；
• tracked 最终树本机路径扫描为 0；
• 未运行 Judge、AI、比赛或矩阵。

该 follow-up commit 清理了 PR 最终树，但早先提交历史中仍存在原路径。如要求历史也完全清除，请决定是否改写相关旧提交。

[wkj2333666]

请求修改，当前不建议合并。\n\n我基于最新提交 0c6f40d 复核到 310 passed、6 skipped，但仍有以下阻断问题：\n\n1. [P1] 显式运行时路径没有真正作用于 manifest。tools/miracle_matrix.py:438 在 record_manifest 时仍使用全局 IFELSE/JUDGE，而不是命令行传入的 args.ifelse_dir/args.judge_dir。使用 --judge-dir/--ifelse-dir 指向临时或非默认资产时，会读取错误资产；默认路径不存在时甚至会在 dry-run 写 manifest 前抛 FileNotFoundError。请改为对 args.ifelse_dir/main.py 和 args.judge_dir/main.py 求 SHA，并增加显式路径回归测试。\n\n2. [P1] resume 没有重新验证当前外部资产。_run_resume 只把 protocol/roster 中的期望 SHA 与旧 manifest 比较；verify_session_for_resume 也只检查 manifest 中保存的 SHA，没有对当前 judge、ifelse、opponent archives、extracted/build roots 求 SHA。这样在 session 创建后替换 Judge 或对手资产，resume 仍可能继续执行，破坏“身份冻结”和可复现性。resume 在调用 r.resume() 前应使用当前 CLI 路径执行与新建 session 相同的 verify_hashes，并在失败时保持 session 字节不变。\n\n3. [P2] vendor/miracle_local/run_match.py:5-7 仍包含 C:\Users\gongh... 和作者本机目录。这个与本 PR 声称的“tracked 最终树本机路径扫描为 0”不一致，也不适合作为公开仓库内容。请改为不含本机目录的逻辑 provenance 标识，并加入覆盖 vendor 文件的扫描测试。\n\n上述问题都能在不运行 Judge/比赛的情况下用单元测试复现。修复并补测试后再重新请求 review。

[wkj2333666]

自动审阅未进入模型调用：该 PR 包含 76 个文件、12251 行新增，完整 diff 超过 350000 字节上限。为避免模型只看到截断前缀后误放行，required check 已按 fail-closed 失败。请将 external Judge/adapter、replay 数据与协议、HL iteration、CLI/文档/测试拆成可独立验证的 PR，并确保每个完整 diff 低于上限后重新触发审核。运行记录：https://github.com/SAST-agent/AgentBenchFramework/actions/runs/30259872810