harness2: recursive harness optimization wired to real codex tasks

Port Google Research's Harness^2 method layer (model weights frozen,
only the surrounding harness is optimized): Propose-Probe-Compose with
INV/DOM/AGG editors, parallel/sequential modes, per-domain experience
library, anonymous-product selection, k<=3 hard cap and budget gate.
Execution goes only through the existing control-plane API (upload ->
task with idempotency key -> poll -> trace/cost -> cancel on timeout);
no new server endpoints, no codex flags composed, tasks inherit the
normal executor/sandbox/quota/audit path.

Wiring lessons from four real rounds against production (project
wwww, ledger task): HttpTaskClient retries transient disconnects and
502/503/429 (3 attempts); editors get a worked file-block example, an
explicit <no-change> marker and one feedback retry (.fmt2) instead of
silently accepting notes-only replies; run_task unwraps the server's
result_text JSON envelope (text field holds the real reply) — without
this, line-anchored file-block parsing could never see blocks the
agents were actually emitting. Final round (real4) fully green:
all stages landed, selection non-fallback, experience入库, probe
delivers the correct signed total 85.15.

Tests: 35 harness tests (17 method + 18 wiring incl. fake-control-plane
full round, idempotent replay, retry, format retry, envelope round).
Deliberate deviations from upstream are documented in docs/harness2.md
(no network-unrestricted/sandbox-disabled defaults, auto_apply off,
no benchmark/scorer, probe deliverable = final reply text).

examples/harness2_demo.py

@@ -0,0 +1,138 @@
+"""Harness² 融合演示：不花模型钱，跑通一轮完整改进。
+
+用法（在项目根目录）：
+    python3 examples/harness2_demo.py --mode parallel --k 1
+    python3 examples/harness2_demo.py --mode sequential --k 1 --output /tmp/h2demo
+
+任务是对账本求和。base harness 的脚本只加正数（账本含一笔负数 credit，
+base 会漏掉它）；确定性编辑器去掉正数过滤；选择器按产物挑带符号和；
+反思器把“正负都要算”写进经验库。跑完打印：被采纳的产物、回落情况、
+经验库条目位置。真实接线时，这里的三个确定性类换成 codex 任务
+（见 docs/harness2.md），执行器换成 Worker 的任务执行，循环本身不变。
+"""
+
+import argparse
+import csv
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from cloud.harness2 import (  # noqa: E402
+    EditResult, Library, Rollout, improve_task, read_tree, write_tree,
+)
+
+BASE_SCRIPT = """import csv
+import sys
+from decimal import Decimal
+with open(sys.argv[1]) as f:
+    amounts = [Decimal(r['amount']) for r in csv.DictReader(f)]
+print(f"Total: {sum((a for a in amounts if a > 0), Decimal(0)):.2f}")
+"""
+
+BASE_TREE = {
+    "AGENTS.md": "Use scripts/summarize.py to total the ledger.\n",
+    "scripts/summarize.py": BASE_SCRIPT,
+}
+
+
+class LedgerAdapter:
+    task_id = "ledger-1"
+    domain = "accounting"
+    prompt = "Sum every signed amount in ledger.csv. Return Total: with two decimals."
+
+    def __init__(self, root):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.ledger = self.root / "ledger.csv"
+        self.ledger.write_text("amount\n100.25\n-20.10\n5.00\n", encoding="utf-8")
+        self.executions = 0
+
+    def base_harness(self):
+        return dict(BASE_TREE)
+
+    def execute(self, label, harness):
+        self.executions += 1
+        work = self.root / "runs" / label
+        work.mkdir(parents=True, exist_ok=True)
+        write_tree(harness, work / "harness")
+        proc = subprocess.run(
+            [sys.executable, str(work / "harness" / "scripts" / "summarize.py"),
+             str(self.ledger)], capture_output=True, text=True, timeout=10)
+        out = proc.stdout.strip()
+        return Rollout(label=label, ok=proc.returncode == 0,
+                       delivered=out.startswith("Total:"), deliverable_text=out,
+                       trajectory="[ACTION] Run scripts/summarize.py\n[OBSERVATION]\n" + out,
+                       cost_usd=0.01)
+
+    def validate_tree(self, harness):
+        if "scripts/summarize.py" not in harness:
+            raise ValueError("The local executor requires scripts/summarize.py")
+
+
+class FixEditor:
+    def edit(self, mission, context_dir, label):
+        harness_dir = Path(context_dir) / "harness"
+        script = harness_dir / "scripts" / "summarize.py"
+        script.write_text(script.read_text().replace(" if a > 0", ""), encoding="utf-8")
+        return EditResult(tree=read_tree(harness_dir),
+                          notes="Keep signed amounts: the base total omitted credits.")
+
+
+class PickSignedSelector:
+    def select(self, mission, context_dir):
+        for path in sorted((Path(context_dir) / "candidates").glob("*.md")):
+            if "Total: 85.15" in path.read_text():
+                return path.stem, "The signed total matches the source ledger.", 0.0
+        raise ValueError("no candidate with the signed total")
+
+
+class LedgerReflector:
+    def reflect(self, mission, context_dir):
+        root = Path(context_dir)
+        changed = (root / "harness" / "scripts" / "summarize.py").read_text() != (
+            root / "base_harness" / "scripts" / "summarize.py").read_text()
+        if not changed:
+            return {}
+        return {
+            "cue": "When a ledger includes credits and debits",
+            "lesson": "Include both signs when summing in scripts/summarize.py.",
+            "evidence": "Removing the positive-only filter changed the probe total to "
+                        "include the credits omitted by the base trajectory.",
+            "confidence": "high for this observed arithmetic contrast",
+        }
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mode", default="parallel", choices=["parallel", "sequential"])
+    ap.add_argument("--k", type=int, default=1)
+    ap.add_argument("--output", default="")
+    args = ap.parse_args()
+    tmp = None
+    root = Path(args.output) if args.output else Path(tempfile.mkdtemp(prefix="h2demo-"))
+    if not args.output:
+        tmp = root
+    adapter = LedgerAdapter(root)
+    library = Library(root / "library", "accounting")
+    result = improve_task(adapter, FixEditor(), selector=PickSignedSelector(),
+                          reflector=LedgerReflector(), work_dir=root / "work",
+                          k=args.k, mode=args.mode, library=library)
+    chosen = result.mode_result.rollouts[result.selection.chosen_label]
+    print(f"mode={result.mode} k={args.k} ok={result.ok}")
+    print(f"executions={adapter.executions} (base + candidates + finals)")
+    print(f"chosen={result.selection.chosen_label} deliverable={chosen.deliverable_text}")
+    print(f"fell_back={result.mode_result.fell_back or 'none'}")
+    print(f"library_entry={result.library_entry}")
+    print(f"experience={result.experience.get('lesson', '(none)')}")
+    print(f"work_dir={root}")
+    assert chosen.deliverable_text == "Total: 85.15", "demo must end at the signed total"
+    assert result.library_entry is not None, "demo must enter the library"
+    print("demo OK: signed total adopted and stored in the library")
+    _ = tmp
+
+
+if __name__ == "__main__":
+    main()

examples/harness2_run.py

@@ -0,0 +1,133 @@
+"""用真实 codex 任务跑一轮 Harness² 改进（接线层 CLI）。
+
+这会创建真实任务、花真实模型配额——所以默认只打印计划，不建任务：
+先跑一遍不带 --yes 看计划，确认项目、任务数与预算无误后，再带
+--yes 重跑。第一次请务必用测试项目，不要直接指生产项目。
+
+密钥不走命令行参数（ps 可见）：用环境变量 CODEX_API_KEY。
+
+示例：
+    export CODEX_API_KEY='...'
+    python3 examples/harness2_run.py --base-url http://127.0.0.1:8765 \\
+        --project-id <test-project> --prompt-file task.md \\
+        --base-harness-dir ./my-base-harness --source-dir ./task-source \\
+        --mode parallel --k 1 --budget 5 --output runs/h2-real-1
+    # 看计划无误后，加 --yes 重跑（同一 run_tag 可断点续跑；想从头
+    # 重跑就换 --run-tag 或不传，让它自动生成新的时间戳 tag）。
+
+base-harness-dir：一个目录，里面就是 harness 树（AGENTS.md、
+.agents/、scripts/、.codex/……），按原样读入；不存在或 AGENTS.md
+为空时直接报错，不跑。
+source-dir（可选）：原任务需要的源文件，会随 harness 一起 seed 进
+每个探针任务的 worktree；与 harness 路径重名时 harness 优先。
+"""
+
+import argparse
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from cloud.harness2 import read_tree  # noqa: E402
+from cloud.harness2_tasks import (  # noqa: E402
+    HttpTaskClient, run_improvement_via_tasks,
+)
+
+
+def _flatten(root: Path) -> dict[str, bytes]:
+    out: dict[str, bytes] = {}
+    if not root or not root.is_dir():
+        return out
+    for p in sorted(root.rglob("*")):
+        if p.is_file() and not p.is_symlink() and "__pycache__" not in p.parts:
+            out[str(p.relative_to(root))] = p.read_bytes()
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base-url", required=True, help="控制面地址，如 http://127.0.0.1:8765")
+    ap.add_argument("--project-id", required=True)
+    ap.add_argument("--prompt", default="")
+    ap.add_argument("--prompt-file", default="")
+    ap.add_argument("--task-id", default="h2-task-1")
+    ap.add_argument("--domain", default="general")
+    ap.add_argument("--base-harness-dir", required=True)
+    ap.add_argument("--source-dir", default="")
+    ap.add_argument("--mode", default="parallel", choices=["parallel", "sequential"])
+    ap.add_argument("--k", type=int, default=1)
+    ap.add_argument("--budget", type=float, default=None)
+    ap.add_argument("--run-tag", default="")
+    ap.add_argument("--output", default="")
+    ap.add_argument("--library-root", default="")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--effort", default=None)
+    ap.add_argument("--approval", default=None)
+    ap.add_argument("--environment-id", default=None)
+    ap.add_argument("--executor", default=None)
+    ap.add_argument("--no-time-limit", action="store_true")
+    ap.add_argument("--timeout", type=int, default=3600)
+    ap.add_argument("--yes", action="store_true", help="确认创建真实任务并消费配额")
+    args = ap.parse_args()
+
+    api_key = os.environ.get("CODEX_API_KEY")
+    if not api_key:
+        print("缺少 CODEX_API_KEY 环境变量（密钥不接受命令行参数）", file=sys.stderr)
+        return 2
+    prompt = args.prompt
+    if args.prompt_file:
+        prompt = Path(args.prompt_file).read_text(encoding="utf-8")
+    if not prompt.strip():
+        print("需要 --prompt 或 --prompt-file", file=sys.stderr)
+        return 2
+    base = read_tree(args.base_harness_dir)
+    if not base.get("AGENTS.md", "").strip():
+        print(f"base-harness-dir 里没有可用的 AGENTS.md：{args.base_harness_dir}",
+              file=sys.stderr)
+        return 2
+    run_tag = args.run_tag or time.strftime("h2-%Y%m%d-%H%M%S")
+    # 任务数（k=1 parallel）：1 base + 2 候选 + 1 终版探针 + 3 编辑
+    # + 1 选择 + 1 反思 = 9；sequential 同为 9；k 越大按 3k+? 线性涨，
+    # 上限 k=3 时 parallel 为 1 + 6 + 3 探针 + 9 编辑 + 1 选择 + 1 反思 = 21。
+    n_probes = 1 + 3 * args.k  # 两种模式同款：1 base + 每轮 2 候选 + 1 终版
+    n_edits = 3 * args.k
+    plan = (f"计划：项目 {args.project_id}，任务 {args.task_id}，"
+            f"mode={args.mode} k={args.k}，run_tag={run_tag}，"
+            f"约 {n_probes} 个探针 + {n_edits} 个编辑 + 1 选择 + 1 反思 = "
+            f"{n_probes + n_edits + 2} 个真实任务，"
+            f"budget_usd={args.budget}，base 文件 {len(base)} 个。")
+    print(plan)
+    if not args.yes:
+        print("未带 --yes：只打印计划，不创建任何任务。确认无误后加 --yes 重跑。")
+        return 0
+    work_dir = Path(args.output) if args.output else Path(tempfile.mkdtemp(prefix="h2run-"))
+    client = HttpTaskClient(args.base_url, api_key)
+    result = run_improvement_via_tasks(
+        client, project_id=args.project_id, task_id=args.task_id, prompt=prompt,
+        base_harness=base, run_tag=run_tag, work_dir=work_dir, domain=args.domain,
+        source_files=_flatten(Path(args.source_dir)) if args.source_dir else None,
+        k=args.k, mode=args.mode,
+        library_root=Path(args.library_root) if args.library_root else None,
+        budget_usd=args.budget, model=args.model, effort=args.effort,
+        approval=args.approval, environment_id=args.environment_id,
+        executor=args.executor, no_time_limit=args.no_time_limit,
+        timeout_seconds=args.timeout)
+    d = result.to_dict()
+    chosen = result.mode_result.rollouts.get(result.selection.chosen_label)
+    print(f"ok={result.ok} chosen={result.selection.chosen_label} "
+          f"fallback={result.selection.fallback} "
+          f"fell_back={result.mode_result.fell_back or 'none'} "
+          f"budget_exceeded={result.budget_exceeded}")
+    print(f"deliverable={(chosen.deliverable_text if chosen else '')[:500]}")
+    print(f"total_cost_usd={result.mode_result.total_cost_usd} "
+          f"library_entry={result.library_entry}")
+    print(f"work_dir={work_dir}")
+    print(f"full_result={d}")
+    return 0 if result.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())