"""Harness² 接线层：把 cloud/harness2.py 的三个协议落到真实 codex 任务上。

控制面 API：
  POST /uploads（multipart + paths JSON）-> upload_id
  POST /tasks（upload_id 绑定 + idempotency_key 幂等）-> 任务排队
  GET  /tasks/{id}        轮询终态（completed / failed / interrupted /
                          merged / merge-failed）
  GET  /tasks/{id}/trace  轨迹（探针的 trajectory 来源）
  GET  /tasks/{id}/cost   成本（usd_micros / 1e6；无价 token 不计入 USD，
                          这是现有 cost 模型的边界，不是本层漏算）
  GET  /tasks/{id}/files  读任务 worktree 文件（产物资产端点；
                          cloud/跨机任务回 409，见下）
  POST /tasks/{id}/cancel 超时取消，不留孤儿任务继续烧钱
认证：X-API-Key 请求头；密钥只由调用方持有，本模块不读、不存、
不打印密钥。

三类任务是怎么跑的：
- 探针（CodexProbeAdapter.execute）：bundle = 源文件 + harness 树。
  Worker 派发时把 bundle 经 host.py --seed-dir 拷进 worktree，harness
  文件会覆盖仓库同名文件——这正是探针要的效果：同一任务在不同
  harness 下跑。prompt = 原任务 prompt + 一段交付脚注（见
  _PROBE_DELIVERABLE_FOOTER），因为评审只看最终回复：agent 必须
  把交付物完整写在最终回复里，不能只说“文件已写好”。
  文件型产物走两层（产物资产）：①经 GET /tasks/{id}/files 读
  worktree 新增/改动文件（端点为准；本地任务走本地 worktree，
  租户 Docker 任务走 tenants 下的任务级子目录）；②所有执行器
  都可用回复里的 DELIVERABLE FILE 块（agent 自报，端点结果
  优先）。边界仍在：cloud/跨机任务端点回 409，此时只有第②层
  可用，且内容以 agent 自报为准（可能截断，截断有标记）。
- 编辑（CodexEditor.edit）：bundle = context/ 前缀的证据树（task.md /
  rollouts / deliverables / harness / library / pool / decisions）。
  agent 在 worktree 的 context/harness/ 里改文件，最终回复里用
  文件块只输出改动的文件（没改的省略即继承），外加 <notes> 块。
  接线层解析文件块、落到该阶段的 fallback 树上，再走核心校验。
  最终回复里既没有文件块也没有 <notes>，或文件块路径越界、未
  闭合，都算该阶段失败：核心循环给一次修正机会，再失败回落到
  fallback 树——绝不把“没看懂输出格式”静默当成“无需改动”。
- 选择（CodexSelector.select）与反思（CodexReflector.reflect）：同款
  bundle + 最终回复解析（```choice + <why>；<experience> + <edits>），
  不读 worktree 文件。选择失败时核心循环回落到已交付终版；反思
  三项不全时返回 {}，不入库。

幂等与断点续跑：每个任务都带 idempotency_key =
f"h2-{run_tag}-{role}-{label}"。同一 run_tag 重跑时服务端直接返回
已有任务（200 而非 201），已终态的任务直接复用结果——这是断点
续跑语义，不是 bug；想从头重跑必须换 run_tag。注意：换了 harness
内容但沿用旧 run_tag 时，旧任务结果会被复用，改进轮次就白跑了，
所以 run_tag 必须随“任务 + harness 基线 + 参数”一起变，调用方
（见 examples/harness2_run.py）默认用时间戳生成，显式 --run-tag
只用于“接着上次断点跑”。

成本与审批：本层不拼任何 codex 参数、不改任务默认值。model /
effort / approval / environment_id / executor 全部由调用方透传，
缺省时走 Worker 现有默认值；探针与编辑任务走与普通任务完全相同
的执行器、沙箱、租户隔离、配额门与审计。长任务走 #133 的自动续
跑；接线层单任务超时默认 3600 秒，超时先取消任务再记失败（探针）
或抛错走回落（编辑/选择/反思），不留任务在后台继续烧钱。

本层是同步阻塞的：improve_task 每一步都要等任务终态。k=1
parallel 一轮 = 1 base + 2 候选 + 1 终版探针 + 3 编辑 + 1 选择 +
1 反思 ≈ 9 个任务串行等待，每个都可能几分钟——这是方法本身的
成本（上游同款：4k 次执行 + 3k 次改进会话），不是本层低效。
"""

from __future__ import annotations

import json
import re
import time
import urllib.error
import urllib.parse
import urllib.request
import uuid
from dataclasses import dataclass, field
from pathlib import Path
from typing import Protocol

from .harness2 import (
    EditResult,
    Rollout,
    Tree,
    improve_task,
    parse_choice,
    parse_deliverable_files,
    parse_experience,
    parse_harness_files,
    parse_no_change,
    parse_notes,
    parse_why,
    read_tree,
)

TERMINAL_STATUSES = frozenset(
    {"completed", "failed", "interrupted", "merged", "merge-failed"}
)
DEFAULT_TASK_TIMEOUT_SECONDS = 3600
DEFAULT_POLL_SECONDS = 10
TRACE_MAX_CHARS = 50000

_TAG_RX = re.compile(r"[A-Za-z0-9_.][A-Za-z0-9_.\-]*\Z")
_SEED_TAG_RX = re.compile(r"s\d+(-|\Z)")


def validate_run_tag(tag: str) -> None:
    """校验 run_tag 形状（上游 schedule.validate_tag 的对照补齐）。

    run_tag 会进幂等键与路径段：空串表示“调用方稍后生成”，不
    校验；非空时只允许字母数字与 _ . -、首字符不能是 -、不能
    以 s + 数字开头（上游用 s<n> 段表示 seed，撞名会把两轮的
    产物算到同一命名空间）。
    """
    if not tag:
        return
    if not _TAG_RX.match(tag):
        raise ValueError(
            f"run_tag {tag!r} must match [A-Za-z0-9_.-] with no leading '-' "
            "and no '/'")
    if _SEED_TAG_RX.match(tag):
        raise ValueError(
            f"run_tag {tag!r} must not start with a seed segment like 's1'")


def preflight_checks(*, base_harness_dir: str | Path, source_dir: str | Path | None = None,
                     prompt: str = "", run_tag: str = "",
                     base_url: str | None = None) -> tuple[list[str], list[str]]:
    """建任务前的本地 + 可达性预检（2026-10-29 对照补齐）。

    返回 (errors, warnings)：errors 非空时调用方不得建任务；
    warnings 只告警（health 探针失败、run_tag 为空待生成等不
    拦任务）。本函数不读密钥、不建任务，--check 可离线跑。
    """
    errors: list[str] = []
    warnings: list[str] = []
    base_dir = Path(base_harness_dir)
    agents = base_dir / "AGENTS.md"
    if not base_dir.is_dir():
        errors.append(f"base-harness-dir 不存在或不是目录：{base_harness_dir}")
    elif not agents.is_file() or not agents.read_text(
            encoding="utf-8", errors="replace").strip():
        errors.append(f"base-harness-dir 里没有可用的 AGENTS.md：{base_harness_dir}")
    if source_dir is not None and str(source_dir) != "":
        if not Path(source_dir).is_dir():
            errors.append(f"source-dir 不存在或不是目录：{source_dir}")
    if not (prompt or "").strip():
        errors.append("需要 --prompt 或 --prompt-file（任务提示为空）")
    if run_tag:
        try:
            validate_run_tag(run_tag)
        except ValueError as exc:
            errors.append(str(exc))
    if base_url:
        try:
            req = urllib.request.Request(base_url.rstrip("/") + "/health")
            with urllib.request.urlopen(req, timeout=10) as resp:
                if resp.status != 200:
                    warnings.append(f"控制面 health 非 200：{resp.status}")
        except Exception as exc:
            warnings.append(f"控制面 health 探针失败（不拦任务）：{type(exc).__name__}: {exc}")
    return errors, warnings


def unwrap_result_text(raw: str) -> str:
    """把服务端 result_text 的 JSON 信封拆开，只取 agent 的最终回复。

    2026-10-29 诊断的真根因：控制面返回的 result_text 不是 agent
    原文，而是一层 JSON 信封（task / thread_id / cwd / status /
    text / usage …），text 字段里才是最终回复。接线层此前原样把
    信封当回复用：notes / choice / experience 的正则不锚定行首，
    在信封里照样命中，所以三轮里只有行首锚定的文件块解析一直
    看不见块——编辑明明发了块，却被判成 notes-only、无改动、
    格式错误。拆信封放在 run_task 这一个 choke point：探针、
    编辑、选择、反思四路共用它，一处拆全受益；拆不开（非
    JSON、无 text 字段、text 非字符串）时原样返回，不丢内容。
    """
    if not raw or not raw.lstrip().startswith("{"):
        return raw
    try:
        obj = json.loads(raw)
    except ValueError:
        return raw
    if isinstance(obj, dict) and isinstance(obj.get("text"), str):
        return obj["text"]
    return raw

_PROBE_DELIVERABLE_FOOTER = """

[DELIVERABLE — READ THIS BEFORE YOU FINISH]
Your final reply IS the deliverable that will be judged. When you finish,
write the complete deliverable in your final reply itself — do not only say
"done" or "the file is written". If the task asks for a file, also write the
file in the worktree, but the final reply must still contain the full content
a reviewer needs to judge the work.
If you created deliverable files (a page, a report, an image manifest),
also paste each file's full content in your final reply as a block:
=== DELIVERABLE FILE: <relative path> ===
<complete file content>
=== END DELIVERABLE FILE ===
"""

_EDITOR_OUTPUT_FORMAT = """

# OUTPUT FORMAT — YOU MUST FOLLOW THIS EXACTLY
Edit the files under context/harness/ in the worktree. Then, in your final
reply, output ONLY the files you changed, one block per file, in this format
(files you did not change are inherited automatically — do NOT re-emit them):

=== HARNESS FILE: <relative path on the editable surface> ===
<the file's COMPLETE new content>
=== END HARNESS FILE ===

Example (a one-line file changed in full — your blocks must contain the
COMPLETE new content, not a diff and not a description of the change):

=== HARNESS FILE: scripts/summarize.py ===
print("Total: 85.15")
=== END HARNESS FILE ===

Then a <notes>...</notes> block: what you changed, and the exact trajectory
moment that justifies each change.

HARD RULES — READ CAREFULLY, THEY ARE MACHINE-CHECKED:
1. A change described only in <notes> is NOT a change. If you changed a
   file, its COMPLETE new content MUST appear in a file block above, or the
   change is discarded and this attempt counts as FAILED.
2. If nothing in the evidence justifies a change, you MUST emit an explicit
   <no-change>...</no-change> block with the reason, and no file blocks.
   Saying "no change needed" only in <notes> is NOT enough — without the
   marker the attempt counts as FAILED.
3. File blocks and a <no-change> marker in the same reply contradict each
   other and the attempt counts as FAILED.
"""

_SELECTOR_OUTPUT_FORMAT = """

# OUTPUT FORMAT — YOU MUST FOLLOW THIS EXACTLY
Reply with a ```choice block containing only the chosen candidate id, and a
<why>...</why> block explaining the decision in one paragraph.
"""

_REFLECTOR_OUTPUT_FORMAT = """

# EVIDENCE NOTE
context/harness/ is the adopted harness; context/base_harness/ is the
unmodified base harness; context/pool/<label>/ holds each candidate harness
plus its rollout. Compare them before writing.

# OUTPUT FORMAT — YOU MUST FOLLOW THIS EXACTLY
Reply with an <edits>...</edits> block (one row per changed component, with
its observed effect and a verdict), then an <experience>...</experience>
block with exactly these lines: `cue: ...`, `lesson: ...`, `evidence: ...`,
`confidence: ...`. If no lesson is supported by an observed contrast, reply
with the single line NO_ENTRY instead of inventing one.
"""


# ---------------------------------------------------------------------------
# 客户端协议与 HTTP 实现
# ---------------------------------------------------------------------------


@dataclass
class TaskState:
    task_id: str
    status: str
    result_text: str = ""
    error_text: str = ""


class TaskClient(Protocol):
    """控制面客户端协议：HTTP 实现见 HttpTaskClient，测试用假实现。"""

    def upload(self, files: dict[str, bytes]) -> str:
        """上传一包文件（相对路径 -> 内容），返回 upload_id。"""
        ...

    def create_task(self, *, project_id: str, prompt: str, upload_id: str | None = None,
                    idempotency_key: str | None = None, model: str | None = None,
                    effort: str | None = None, approval: str | None = None,
                    environment_id: str | None = None, executor: str | None = None,
                    no_time_limit: bool = False) -> str:
        """建任务，返回任务 id；同幂等键返回已有任务 id，不建重复。"""
        ...

    def get_task(self, task_id: str) -> TaskState:
        ...

    def get_trace_text(self, task_id: str) -> str:
        """轨迹渲染文本；读不到时返回空串（调用方用最终回复兜底）。"""
        ...

    def get_task_files(self, task_id: str, path: str = "") -> dict:
        """GET /tasks/{id}/files：不传 path 列 worktree 文件，传 path
        读单个文件。服务端对 cloud/跨机任务回 409，调用方须把
        409 当成“无文件通道”、不得当成探针失败。"""
        ...

    def get_cost_usd(self, task_id: str) -> float:
        """有价成本 USD；读不到时返回 0.0，不炸轮次。"""
        ...

    def cancel_task(self, task_id: str) -> None:
        ...


def build_multipart(files: dict[str, bytes]) -> tuple[bytes, str]:
    """按服务端 cloud/uploads.py 的解析器能读懂的格式编码 multipart。

    paths 字段是 JSON 字符串数组，与 file part 一一对应；part 名用
    file（服务端只按顺序取 files，不认 part 名）。编码结果可用
    cloud.uploads.parse_multipart + parse_paths_field 原样解回，
    见 test_harness2_tasks.py 的往返测试。
    """
    boundary = "----harness2-" + uuid.uuid4().hex
    paths = sorted(files)
    parts: list[bytes] = []
    parts.append(
        b"--" + boundary.encode() + b"\r\n"
        b'Content-Disposition: form-data; name="paths"\r\n\r\n'
        + json.dumps(paths).encode() + b"\r\n"
    )
    for path in paths:
        parts.append(
            b"--" + boundary.encode() + b"\r\n"
            + f'Content-Disposition: form-data; name="file"; filename="{path}"\r\n'.encode()
            + b"Content-Type: application/octet-stream\r\n\r\n"
            + files[path] + b"\r\n"
        )
    parts.append(b"--" + boundary.encode() + b"--\r\n")
    return b"".join(parts), f"multipart/form-data; boundary={boundary}"


class HttpTaskClient:
    """基于标准库 urllib 的控制面客户端（零第三方依赖，与项目风格一致）。

    瞬断重试（2026-10-29 真实首跑教训）：VM 到公网控制面的连接会
    偶发中途断开（RemoteDisconnected / IncompleteRead），一次断开
    就让整轮提前收尾，尽管服务端任务还在跑。_request 对传输错误与
    502 / 503 / 429 最多重试 3 次（退避 1s、3s），其它 HTTP 错误
    （401 / 403 / 400 等服务端裁决）不重试。重试安全的前提是调用
    方都带 idempotency_key（本层所有建任务调用都带）与“上传包
    未绑定即孤儿包”的语义：重试建任务时服务端返回已有任务，不
    重复建；重试上传时最多多出一个 24 小时后过期的孤儿包。
    """

    def __init__(self, base_url: str, api_key: str, *, timeout: int = 60,
                 max_attempts: int = 3):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.timeout = timeout
        self.max_attempts = max(1, max_attempts)

    def _request(self, method: str, path: str, body: bytes | None = None,
                 content_type: str | None = None) -> dict:
        req = urllib.request.Request(
            self.base_url + path, data=body, method=method)
        req.add_header("X-API-Key", self.api_key)
        if content_type:
            req.add_header("Content-Type", content_type)
        elif body is not None:
            req.add_header("Content-Type", "application/json")
        last_exc: Exception | None = None
        for attempt in range(1, self.max_attempts + 1):
            try:
                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
                    raw = resp.read()
            except urllib.error.HTTPError as exc:
                if exc.code in (502, 503, 429) and attempt < self.max_attempts:
                    last_exc = exc
                    time.sleep(1 if attempt == 1 else 3)
                    continue
                detail = exc.read().decode("utf-8", errors="replace")[:500]
                raise RuntimeError(
                    f"{method} {path} -> HTTP {exc.code}: {detail}") from exc
            except (urllib.error.URLError, ConnectionError, TimeoutError,
                    OSError) as exc:
                # RemoteDisconnected / IncompleteRead 都落在这里（前者是
                # ConnectionResetError / http.client 子类，后者是
                # http.client.HTTPException，而 HTTPException 不是
                # OSError——见下方 except。
                if attempt < self.max_attempts:
                    last_exc = exc
                    time.sleep(1 if attempt == 1 else 3)
                    continue
                raise RuntimeError(
                    f"{method} {path} -> transport error: {exc}") from exc
            except Exception as exc:  # http.client.HTTPException 等非 OSError
                if exc.__class__.__name__ in (
                        "RemoteDisconnected", "IncompleteRead", "BadStatusLine",
                        "HTTPException") and attempt < self.max_attempts:
                    last_exc = exc
                    time.sleep(1 if attempt == 1 else 3)
                    continue
                raise
            break
        else:
            raise RuntimeError(
                f"{method} {path} -> transport error: {last_exc}")
        try:
            obj = json.loads(raw.decode("utf-8"))
        except ValueError as exc:
            raise RuntimeError(f"{method} {path} -> non-JSON response") from exc
        if not isinstance(obj, dict):
            raise RuntimeError(f"{method} {path} -> unexpected response shape")
        return obj

    def upload(self, files: dict[str, bytes]) -> str:
        if not files:
            raise ValueError("upload requires at least one file")
        body, content_type = build_multipart(files)
        obj = self._request("POST", "/uploads", body=body, content_type=content_type)
        upload_id = obj.get("upload_id")
        if not upload_id:
            raise RuntimeError(f"/uploads did not return an upload_id: {obj!r}"[:300])
        return str(upload_id)

    def create_task(self, *, project_id: str, prompt: str, upload_id: str | None = None,
                    idempotency_key: str | None = None, model: str | None = None,
                    effort: str | None = None, approval: str | None = None,
                    environment_id: str | None = None, executor: str | None = None,
                    no_time_limit: bool = False) -> str:
        payload: dict = {"project_id": project_id, "prompt": prompt}
        if upload_id is not None:
            payload["upload_id"] = upload_id
        if idempotency_key is not None:
            payload["idempotency_key"] = idempotency_key
        if model is not None:
            payload["model"] = model
        if effort is not None:
            payload["effort"] = effort
        if approval is not None:
            payload["approval"] = approval
        if environment_id is not None:
            payload["environment_id"] = environment_id
        if executor is not None:
            payload["executor"] = executor
        if no_time_limit:
            payload["no_time_limit"] = True
        obj = self._request("POST", "/tasks", body=json.dumps(payload).encode())
        task_id = obj.get("id")
        if not task_id:
            raise RuntimeError(f"/tasks did not return an id: {obj!r}"[:300])
        return str(task_id)

    def get_task(self, task_id: str) -> TaskState:
        obj = self._request("GET", f"/tasks/{task_id}")
        return TaskState(
            task_id=task_id,
            status=str(obj.get("status") or ""),
            result_text=str(obj.get("result_text") or ""),
            error_text=str(obj.get("error_text") or ""),
        )

    def get_trace_text(self, task_id: str) -> str:
        try:
            obj = self._request("GET", f"/tasks/{task_id}/trace")
        except Exception:
            return ""
        entries = obj.get("entries") or []
        lines: list[str] = []
        for entry in entries:
            if not isinstance(entry, dict):
                continue
            kind = entry.get("kind") or entry.get("type") or "entry"
            text = entry.get("text") or entry.get("message") or ""
            if not text:
                text = json.dumps(entry, ensure_ascii=False)[:1000]
            lines.append(f"[{kind}] {text}")
        rendered = "\n".join(lines).strip()
        return rendered[:TRACE_MAX_CHARS] if rendered else ""

    def get_task_files(self, task_id: str, path: str = "") -> dict:
        q = f"?path={urllib.parse.quote(path)}" if path else ""
        return self._request("GET", f"/tasks/{task_id}/files{q}")

    def get_cost_usd(self, task_id: str) -> float:
        try:
            obj = self._request("GET", f"/tasks/{task_id}/cost")
        except Exception:
            return 0.0
        try:
            return float(obj.get("usd_micros") or 0) / 1_000_000
        except (TypeError, ValueError):
            return 0.0

    def cancel_task(self, task_id: str) -> None:
        try:
            self._request("POST", f"/tasks/{task_id}/cancel", body=b"{}")
        except Exception:
            pass  # 终态任务取消会 400，本来就不用再取消；其它错误也不炸轮次


@dataclass
class CompletedTask:
    task_id: str
    state: TaskState
    cost_usd: float = 0.0
    trace_text: str = ""


def run_task(
    client: TaskClient,
    *,
    project_id: str,
    prompt: str,
    files: dict[str, bytes] | None = None,
    idempotency_key: str | None = None,
    model: str | None = None,
    effort: str | None = None,
    approval: str | None = None,
    environment_id: str | None = None,
    executor: str | None = None,
    no_time_limit: bool = False,
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS,
    poll_seconds: int = DEFAULT_POLL_SECONDS,
) -> CompletedTask:
    """建任务、轮询到终态、读成本与轨迹。超时先取消再抛 TimeoutError。"""
    upload_id = client.upload(files) if files else None
    task_id = client.create_task(
        project_id=project_id, prompt=prompt, upload_id=upload_id,
        idempotency_key=idempotency_key, model=model, effort=effort,
        approval=approval, environment_id=environment_id, executor=executor,
        no_time_limit=no_time_limit)
    deadline = time.time() + timeout_seconds
    state = client.get_task(task_id)
    while state.status not in TERMINAL_STATUSES:
        if time.time() >= deadline:
            client.cancel_task(task_id)
            raise TimeoutError(
                f"task {task_id} did not reach a terminal status within "
                f"{timeout_seconds}s (last status: {state.status})")
        time.sleep(poll_seconds)
        state = client.get_task(task_id)
    # 拆信封的唯一位置：run_task 是探针、编辑、选择、反思四路的
    # 共同 choke point，在这里拆一次，全路受益；各 TaskClient 的
    # get_task 保持原样返回服务端原文。
    state = TaskState(
        task_id=state.task_id, status=state.status,
        result_text=unwrap_result_text(state.result_text),
        error_text=state.error_text,
    )
    return CompletedTask(
        task_id=task_id, state=state,
        cost_usd=client.get_cost_usd(task_id),
        trace_text=client.get_trace_text(task_id),
    )


def _flatten_dir(root: Path, prefix: str = "") -> dict[str, bytes]:
    """把一个目录展平成 {相对路径: 内容}；符号链接与 __pycache__ 跳过。"""
    out: dict[str, bytes] = {}
    root = Path(root)
    if not root.is_dir():
        return out
    for p in sorted(root.rglob("*")):
        if not p.is_file() or p.is_symlink() or "__pycache__" in p.parts:
            continue
        rel = str(p.relative_to(root))
        out[(prefix + rel) if prefix else rel] = p.read_bytes()
    return out


def _tree_to_files(tree: Tree) -> dict[str, bytes]:
    return {rel: content.encode("utf-8") for rel, content in tree.items()}


# ---------------------------------------------------------------------------
# 三个协议的真实任务实现
# ---------------------------------------------------------------------------


@dataclass
class CodexProbeAdapter:
    """探针 adapter：每个 label 跑一个真实 codex 任务。

    source_files：原任务需要的源文件（如 ledger.csv），会随 harness
    一起 seed 进 worktree；与 harness 路径冲突时 harness 优先（探针
    的意义就是让 harness 覆盖仓库默认值）。调用方应在 source_files
    里避免与 harness 路径重名——重名时源文件会被静默覆盖，本层
    不为此报错（与 seed“用户文件优先”的语义一致）。
    """

    client: TaskClient
    project_id: str
    task_id: str
    prompt: str
    base: Tree
    run_tag: str
    source_files: dict[str, bytes] = field(default_factory=dict)
    environment_id: str | None = None
    executor: str | None = None
    model: str | None = None
    effort: str | None = None
    approval: str | None = None
    no_time_limit: bool = False
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS
    domain: str = "general"

    def base_harness(self) -> Tree:
        return dict(self.base)

    def execute(self, label: str, harness: Tree) -> Rollout:
        files = dict(self.source_files)
        files.update(_tree_to_files(harness))
        try:
            done = run_task(
                self.client, project_id=self.project_id,
                prompt=self.prompt + _PROBE_DELIVERABLE_FOOTER,
                files=files,
                idempotency_key=f"h2-{self.run_tag}-probe-{label}",
                model=self.model, effort=self.effort, approval=self.approval,
                environment_id=self.environment_id, executor=self.executor,
                no_time_limit=self.no_time_limit,
                timeout_seconds=self.timeout_seconds)
        except Exception as exc:
            return Rollout(label=label, ok=False, delivered=False,
                           error=f"{type(exc).__name__}: {exc}"[:400])
        state = done.state
        delivered = state.status == "completed" and bool(state.result_text.strip())
        deliverable_files = self._collect_deliverable_files(done.task_id, files)
        # 回复里的产物文件块是补充通道（所有执行器都可用）；
        # 端点读到的文件为准，冲突时不覆盖端点结果。
        for name, content in parse_deliverable_files(
                state.result_text or "").items():
            deliverable_files.setdefault(name, content)
        return Rollout(
            label=label, ok=state.status == "completed", delivered=delivered,
            deliverable_text=state.result_text,
            trajectory=done.trace_text or state.result_text,
            cost_usd=done.cost_usd,
            error="" if state.status == "completed" else (
                state.error_text or f"task ended as {state.status}")[:400],
            deliverable_files=deliverable_files,
        )

    def _collect_deliverable_files(self, task_id: str,
                                   seed_files: dict[str, bytes]) -> dict[str, str]:
        """经 GET /tasks/{id}/files 读探针 worktree 里新增的文件。

        取 seed 里没有的新文件，以及内容被改过的 seed 文件（与
        seed 字节比对，不一致才算产物）；跳过隐藏文件、最多收
        8 个、最多读 16 个；端点不可用（cloud/跨机 409、读错）
        时返回空 dict——文件产物是 enrichment，绝不能因此炸轮次。
        """
        try:
            listing = self.client.get_task_files(task_id)
        except Exception:
            return {}
        out: dict[str, str] = {}
        reads = 0
        for entry in listing.get("entries") or []:
            if not isinstance(entry, dict):
                continue
            path = entry.get("path") or ""
            if not path or path.startswith("."):
                continue
            if len(out) >= 8 or reads >= 16:
                break
            try:
                data = self.client.get_task_files(task_id, path)
            except Exception:
                continue
            reads += 1
            content = data.get("content")
            if not isinstance(content, str):
                continue
            seed = seed_files.get(path)
            if seed is not None and seed.decode("utf-8", errors="replace") == content:
                continue
            out[path] = content
        return out


@dataclass
class CodexEditor:
    """编辑器：一个 codex 任务，证据 seed 进 worktree，改动以文件块回读。"""

    client: TaskClient
    project_id: str
    run_tag: str
    environment_id: str | None = None
    executor: str | None = None
    model: str | None = None
    effort: str | None = None
    approval: str | None = None
    no_time_limit: bool = False
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS

    def edit(self, mission: str, context_dir: Path, label: str) -> EditResult:
        """编辑任务：格式错误给一次带反馈的纠正机会，再错才如实回落。

        背景（2026-10-29 两轮真实轮次）：编辑在 <notes> 里声称改
        动、却不发文件块，旧契约把 notes-only 当“无需改动”采纳，
        改动无声丢失；且方法层的阶段循环里编辑异常是直接 break（不
        重试），所以纠正必须发生在本层。格式重试用独立幂等键
        （…-edit-{label}.fmt2），不复用首个任务、不重复计费到同
        一任务；任务本身失败（非 completed）仍直接抛错、不重试。
        """
        files = _flatten_dir(context_dir, prefix="context/")
        files["context/MISSION.md"] = mission.encode("utf-8")
        last_err = ""
        total_cost = 0.0
        for attempt in (1, 2):
            prompt = mission + _EDITOR_OUTPUT_FORMAT
            if last_err:
                prompt += (
                    "\n\n# YOUR PREVIOUS REPLY WAS REJECTED\n\n"
                    f"{last_err}\n\nFix the output format and reply again: "
                    "changed files MUST appear as === HARNESS FILE === blocks "
                    "with their COMPLETE new content, or, if truly no change "
                    "is justified, emit <no-change>...</no-change>.")
            done = run_task(
                self.client, project_id=self.project_id,
                prompt=prompt,
                files=files,
                idempotency_key=f"h2-{self.run_tag}-edit-{label}"
                + ("" if attempt == 1 else ".fmt2"),
                model=self.model, effort=self.effort, approval=self.approval,
                environment_id=self.environment_id, executor=self.executor,
                no_time_limit=self.no_time_limit,
                timeout_seconds=self.timeout_seconds)
            state = done.state
            if state.status != "completed":
                raise RuntimeError(
                    f"editor task {done.task_id} ended as {state.status}: "
                    f"{state.error_text}"[:400])
            total_cost += done.cost_usd
            text = state.result_text or ""
            try:
                changed = parse_harness_files(text)
                notes = parse_notes(text)
                no_change = parse_no_change(text)
            except ValueError as exc:
                last_err = f"output-format error: {exc}"
                continue
            if changed and no_change:
                last_err = ("output-format error: reply contains both harness "
                            "file blocks and a <no-change> marker")
                continue
            if not changed and not no_change:
                last_err = ("output-format error: reply contains neither "
                            "harness file blocks nor a <no-change> marker; "
                            "a change described only in <notes> is discarded")
                continue
            base_tree = read_tree(Path(context_dir) / "harness")
            merged = dict(base_tree)
            merged.update(changed)
            return EditResult(tree=merged, notes=notes, cost_usd=total_cost)
        raise ValueError(
            f"editor reply failed output-format validation twice: {last_err}")


@dataclass
class CodexSelector:
    """选择器：一个 codex 任务，候选产物 seed 进 worktree，只解析最终回复。"""

    client: TaskClient
    project_id: str
    run_tag: str
    environment_id: str | None = None
    executor: str | None = None
    model: str | None = None
    effort: str | None = None
    approval: str | None = None
    no_time_limit: bool = False
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS

    def select(self, mission: str, context_dir: Path) -> tuple[str, str, float]:
        files = _flatten_dir(context_dir, prefix="context/")
        files["context/MISSION.md"] = mission.encode("utf-8")
        done = run_task(
            self.client, project_id=self.project_id,
            prompt=mission + _SELECTOR_OUTPUT_FORMAT,
            files=files,
            idempotency_key=f"h2-{self.run_tag}-select-{Path(context_dir).name}",
            model=self.model, effort=self.effort, approval=self.approval,
            environment_id=self.environment_id, executor=self.executor,
            no_time_limit=self.no_time_limit,
            timeout_seconds=self.timeout_seconds)
        state = done.state
        if state.status != "completed":
            raise RuntimeError(
                f"selector task {done.task_id} ended as {state.status}: "
                f"{state.error_text}"[:400])
        choice = parse_choice(state.result_text or "")
        if not choice:
            raise ValueError("selector task returned no ```choice block")
        return choice, parse_why(state.result_text or ""), done.cost_usd


@dataclass
class CodexReflector:
    """反思器：一个 codex 任务，解析 <experience>；三项不全返回 {}。"""

    client: TaskClient
    project_id: str
    run_tag: str
    environment_id: str | None = None
    executor: str | None = None
    model: str | None = None
    effort: str | None = None
    approval: str | None = None
    no_time_limit: bool = False
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS

    def reflect(self, mission: str, context_dir: Path) -> dict:
        files = _flatten_dir(context_dir, prefix="context/")
        files["context/MISSION.md"] = mission.encode("utf-8")
        done = run_task(
            self.client, project_id=self.project_id,
            prompt=mission + _REFLECTOR_OUTPUT_FORMAT,
            files=files,
            idempotency_key=f"h2-{self.run_tag}-reflect-{Path(context_dir).name}",
            model=self.model, effort=self.effort, approval=self.approval,
            environment_id=self.environment_id, executor=self.executor,
            no_time_limit=self.no_time_limit,
            timeout_seconds=self.timeout_seconds)
        state = done.state
        if state.status != "completed":
            return {}
        return parse_experience(state.result_text or "")


def run_improvement_via_tasks(
    client: TaskClient,
    *,
    project_id: str,
    task_id: str,
    prompt: str,
    base_harness: Tree,
    run_tag: str,
    work_dir: Path,
    domain: str = "general",
    source_files: dict[str, bytes] | None = None,
    k: int = 1,
    mode: str = "parallel",
    library_root: Path | None = None,
    budget_usd: float | None = None,
    max_sessions: int | None = None,
    model: str | None = None,
    role_models: dict[str, str | None] | None = None,
    effort: str | None = None,
    approval: str | None = None,
    environment_id: str | None = None,
    executor: str | None = None,
    no_time_limit: bool = False,
    timeout_seconds: int = DEFAULT_TASK_TIMEOUT_SECONDS,
):
    """一站式：用真实 codex 任务跑一轮完整改进，返回 ImprovementResult。

    library_root 为空时不建经验库（只跑改进、不入库）；非空时按
    domain 建库。auto_apply 恒为 False——采纳的树只入库待评审，
    不自动成为后续任务的 base（见 docs/harness2.md 安全一节）。

    分角色模型：role_models 键为 probe / editor / selector /
    reflector，非空值覆盖该角色的 model；缺键或空值时回落到
    共享 model；两者都空时不传 model（服务端默认模型）。默认
    行为与此前完全一致——本参数只提供分流能力，不替用户选
    模型（有价模型会产生真实成本，见 docs/harness2.md）。
    """
    from .harness2 import Library

    roles = role_models or {}

    def _role_model(role: str) -> str | None:
        return roles.get(role) or model

    adapter = CodexProbeAdapter(
        client=client, project_id=project_id, task_id=task_id, prompt=prompt,
        base=base_harness, run_tag=run_tag,
        source_files=source_files or {}, environment_id=environment_id,
        executor=executor, model=_role_model("probe"), effort=effort,
        approval=approval,
        no_time_limit=no_time_limit, timeout_seconds=timeout_seconds,
        domain=domain)
    shared = dict(environment_id=environment_id, executor=executor,
                  effort=effort, approval=approval, no_time_limit=no_time_limit,
                  timeout_seconds=timeout_seconds)
    editor = CodexEditor(client=client, project_id=project_id, run_tag=run_tag,
                         model=_role_model("editor"), **shared)
    selector = CodexSelector(client=client, project_id=project_id, run_tag=run_tag,
                             model=_role_model("selector"), **shared)
    reflector = CodexReflector(client=client, project_id=project_id, run_tag=run_tag,
                               model=_role_model("reflector"), **shared)
    library = Library(library_root, domain) if library_root is not None else None
    validate_run_tag(run_tag)
    return improve_task(
        adapter, editor, selector=selector, reflector=reflector,
        work_dir=work_dir, k=k, mode=mode, library=library,
        auto_apply=False, budget_usd=budget_usd, max_sessions=max_sessions)


def run_sweep(client, *, project_id, runs, work_root, library_root=None):
    """批量跑多轮改进：共享经验库、单轮失败隔离、汇总报告。

    runs：每轮一个 dict，键为 run_improvement_via_tasks 的参数，
    run_tag 必填；client / project_id / work_dir / library_root
    由本函数统管，出现在 spec 里会被忽略（不报错）。每轮
    work_dir = work_root/<run_tag>。library_root 非空时所有轮
    共享同一库——已入库的经验会被后续轮读到，即上游 sweep 的
    library restore 语义；为空时各轮都不入库（仍汇总）。

    单轮抛错只记入报告的 error，不中断后续轮（dead 隔离）。
    返回报告 dict：runs 逐轮（ok / chosen_label / deliverable
    前 500 字 / cost / library_entry / error）+ totals（轮数、
    成功轮数、总成本）。
    """
    work_root = Path(work_root)
    report_runs = []
    total_cost = 0.0
    n_ok = 0
    for spec in runs:
        spec = dict(spec)
        run_tag = spec.pop("run_tag", "")
        for owned in ("client", "project_id", "work_dir", "library_root"):
            spec.pop(owned, None)
        entry = {"run_tag": run_tag, "ok": False, "chosen_label": None,
                 "deliverable_text": "", "total_cost_usd": 0.0,
                 "library_entry": None, "error": None}
        try:
            if not run_tag:
                raise ValueError("sweep 每轮必须给 run_tag（用作 work_dir 子目录）")
            validate_run_tag(run_tag)
            result = run_improvement_via_tasks(
                client, project_id=project_id, run_tag=run_tag,
                work_dir=work_root / run_tag,
                library_root=library_root, **spec)
            entry["ok"] = bool(result.ok)
            entry["chosen_label"] = result.selection.chosen_label
            chosen = result.mode_result.rollouts.get(result.selection.chosen_label)
            if chosen is not None:
                entry["deliverable_text"] = (chosen.deliverable_text or "")[:500]
            entry["total_cost_usd"] = result.mode_result.total_cost_usd
            entry["library_entry"] = result.library_entry
            total_cost += result.mode_result.total_cost_usd
            n_ok += 1 if result.ok else 0
        except Exception as exc:
            entry["error"] = f"{type(exc).__name__}: {exc}"[:400]
        report_runs.append(entry)
    return {"runs": report_runs,
            "totals": {"n_runs": len(report_runs), "n_ok": n_ok,
                       "total_cost_usd": total_cost}}


__all__ = [
    "TERMINAL_STATUSES", "DEFAULT_TASK_TIMEOUT_SECONDS", "DEFAULT_POLL_SECONDS",
    "TRACE_MAX_CHARS", "TaskState", "TaskClient", "build_multipart",
    "HttpTaskClient", "CompletedTask", "run_task",
    "CodexProbeAdapter", "CodexEditor", "CodexSelector", "CodexReflector",
    "run_improvement_via_tasks", "run_sweep", "validate_run_tag", "preflight_checks",
]