okstra 0.135.0 → 0.137.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -23,20 +23,41 @@ from .final_report_paths import (
     final_report_markdown_path as _final_report_markdown_path,
 )
 from .lead_events import LeadEvent, append_lead_event
+from .dispatch_state import (
+    BACKEND_CLI_WRAPPER,
+    BACKEND_MIXED,
+    BACKEND_TMUX_PANE,
+    DispatchError,
+    WorkerJob,
+    dispatch_mode as _dispatch_mode,
+    load_json_object as _load_json_object,
+    missing_completion_paths as _missing_completion_paths,
+    require_string as _require_string,
+    resolve_project_path as _resolve_project_path,
+    resolve_required_path as _resolve_required_path,
+    set_dispatch_mode as _set_dispatch_mode,
+    set_worker_status as _set_worker_status,
+    string_list as _string_list,
+    string_value as _string_value,
+    utc_now as _utc_now,
+    validate_initial_prompts as _validate_initial_prompts,
+    worker_prompt_path as _worker_prompt_path,
+    worker_state as _worker_state,
+    worktree_path as _worktree_path,
+    write_json as _write_json,
+)
 from .path_hints import hydrate_active_run_context
 from .report_finalize import (
     STEP_VALIDATE_RUN,
     FinalizeContext,
     FinalizeError,
     project_relative_path as _project_relative_path,
-    require_string as _require_string,
     resolve_optional_path as _resolve_optional_path,
-    resolve_project_path as _resolve_project_path,
     run_finalize,
     run_seq as _run_seq,
-    string_value as _string_value,
 )
 from .wrapper_status import status_path_for_prompt
+from .report_language import resolve_report_language
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_body import (
@@ -45,6 +66,8 @@ from .worker_prompt_body import (
     existing_input_lines as _existing_input_lines,
     instruction_path as _instruction_path,
     mcp_pointer_line as _mcp_pointer_line,
+    report_writer_prompt_body,
+    REPORT_WRITER_WORKER_ID,
 )
 from .worker_prompt_policy import (
     PromptPlan,
@@ -56,58 +79,7 @@ SUPPORTED_CLI_WORKERS = {
     "codex": "okstra-codex-exec.sh",
     "antigravity": "okstra-antigravity-exec.sh",
 }
-BACKEND_CLI_WRAPPER = "cli-wrapper"
-BACKEND_MIXED = "mixed"
 MAX_WORKER_ATTEMPTS = 2
-REPORT_WRITER_WORKER_ID = "report-writer"
-REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
-
-
-class DispatchError(Exception):
-    """Raised when a Codex dispatch request cannot be executed."""
-
-
-@dataclass(frozen=True)
-class WorkerDispatch:
-    worker_id: str
-    backend: str
-    project_root: Path
-    model_execution_value: str
-    wrapper_path: Path
-    prompt_path: Path
-    result_path: Path
-    worker_result_path: Path
-    completion_paths: tuple[Path, ...]
-    worktree_path: str
-    role: str
-    idle_timeout_seconds: int
-
-    @property
-    def command(self) -> list[str]:
-        return [
-            str(self.wrapper_path),
-            str(self.project_root),
-            self.model_execution_value,
-            str(self.prompt_path),
-            self.worktree_path,
-            self.role,
-            str(self.idle_timeout_seconds),
-        ]
-
-    def to_payload(self) -> dict[str, Any]:
-        return {
-            "workerId": self.worker_id,
-            "backend": self.backend,
-            "modelExecutionValue": self.model_execution_value,
-            "wrapperPath": str(self.wrapper_path),
-            "promptPath": str(self.prompt_path),
-            "resultPath": str(self.result_path),
-            "workerResultPath": str(self.worker_result_path),
-            "completionPaths": [str(path) for path in self.completion_paths],
-            "worktreePath": self.worktree_path,
-            "role": self.role,
-            "command": self.command,
-        }
 
 
 @dataclass(frozen=True)
@@ -118,7 +90,7 @@ class DispatchPlan:
     team_state_path: Path
     lead_events_path: Path
     manifest: Mapping[str, Any]
-    workers: tuple[WorkerDispatch, ...]
+    workers: tuple[WorkerJob, ...]
 
     def to_payload(self, *, dry_run: bool) -> dict[str, Any]:
         return {
@@ -158,9 +130,7 @@ def build_dispatch_plan(
         requested_workers,
         enable_codex_report_writer=enable_codex_report_writer,
     )
-    team_state_path = _resolve_required_path(
-        project_root, manifest, "teamStatePath", "team-state"
-    )
+    team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
     team_state = _load_json_object(team_state_path, "team-state")
     _mark_skipped_workers(
         team_state_path,
@@ -175,9 +145,7 @@ def build_dispatch_plan(
     active_context = _load_optional_json_object(
         _resolve_optional_path(project_root, manifest.get("activeRunContextPath"))
     )
-    lead_events_path = _resolve_required_path(
-        project_root, manifest, "leadEventsPath", "lead events"
-    )
+    lead_events_path = _resolve_required_path(project_root, manifest, "leadEventsPath")
     _materialize_missing_worker_prompts(
         project_root=project_root,
         manifest=manifest,
@@ -213,20 +181,6 @@ def build_dispatch_plan(
     )
 
 
-def _validate_initial_prompts(
-    manifest: Mapping[str, Any],
-    workers: Sequence[WorkerDispatch],
-) -> None:
-    records = [
-        PromptRecord(worker.worker_id, "initial", worker.prompt_path)
-        for worker in workers
-    ]
-    errors = validate_initial_prompt_records(manifest=manifest, records=records)
-    if errors:
-        task_type = _require_string(manifest, "taskType")
-        raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
-
-
 def dispatch_plan(plan: DispatchPlan) -> int:
     _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
     for worker in plan.workers:
@@ -244,7 +198,7 @@ def dispatch_plan(plan: DispatchPlan) -> int:
     return 0
 
 
-def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerDispatch) -> int:
+def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
     for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
         _record_worker_attempt(plan, worker, attempt, "running")
         attempt_details = _attempt_event_details(worker, attempt)
@@ -305,7 +259,7 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerDispatch) -> i
     return 1
 def _record_worker_attempt(
     plan: DispatchPlan,
-    worker: WorkerDispatch,
+    worker: WorkerJob,
     attempt: int,
     status: str,
     reason: str = "",
@@ -327,7 +281,7 @@ def _record_worker_attempt(
 
 
 def _matches_worker_attempt(
-    record: object, worker: WorkerDispatch, attempt: int
+    record: object, worker: WorkerJob, attempt: int
 ) -> bool:
     return (
         isinstance(record, dict)
@@ -338,7 +292,7 @@ def _matches_worker_attempt(
 
 
 def _worker_dispatch_record(
-    worker: WorkerDispatch, attempt: int, status: str, reason: str
+    worker: WorkerJob, attempt: int, status: str, reason: str
 ) -> dict[str, Any]:
     provider = "codex" if worker.worker_id == REPORT_WRITER_WORKER_ID else worker.worker_id
     return {
@@ -515,9 +469,7 @@ def _render_missing_report_writer_prompt(
     report_writer_codex_model: str,
 ) -> str:
     worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
-    markdown_path = _resolve_required_path(
-        project_root, manifest, "expectedReportPath", "report"
-    )
+    markdown_path = _resolve_required_path(project_root, manifest, "expectedReportPath")
     data_json_path = _final_report_data_path(markdown_path)
     result_rel = _project_relative_path(project_root, data_json_path)
     worker_result_rel = _require_string(worker_state, "resultPath")
@@ -535,12 +487,13 @@ def _render_missing_report_writer_prompt(
         result_rel=result_rel,
         audit_source_rel=worker_result_rel,
     )
-    lines.extend([
-        f"**Worker Result Path:** {worker_result_rel}",
-        f"**Model:** Report writer worker, {model}",
-        f"**Report Language:** {_resolve_report_language(project_root, manifest, active_context)}",
-    ])
-    lines.extend(_report_writer_prompt_body(manifest, active_context, team_state))
+    lines.extend(report_writer_prompt_body(
+        manifest,
+        active_context,
+        team_state,
+        model,
+        resolve_report_language(project_root, manifest, active_context),
+    ))
     return "\n".join(lines).rstrip() + "\n"
 
 
@@ -555,7 +508,7 @@ def _build_worker_dispatch(
     okstra_bin: Path | None,
     idle_timeout_seconds: int,
     report_writer_codex_model: str,
-) -> WorkerDispatch:
+) -> WorkerJob:
     if worker_id == REPORT_WRITER_WORKER_ID:
         return _build_report_writer_dispatch(
             project_root=project_root,
@@ -576,8 +529,9 @@ def _build_worker_dispatch(
     wrapper = _resolve_wrapper(worker_id, workspace_root, okstra_bin)
     worktree_path = _worktree_path(manifest, active_context)
     role = _pane_role(prompt_path)
-    return WorkerDispatch(
+    return WorkerJob(
         worker_id=worker_id,
+        provider=worker_id,
         backend=BACKEND_CLI_WRAPPER,
         project_root=project_root,
         model_execution_value=model_execution_value,
@@ -589,6 +543,7 @@ def _build_worker_dispatch(
         worktree_path=worktree_path,
         role=role,
         idle_timeout_seconds=idle_timeout_seconds,
+        dispatch_kind="initial",
     )
 
 
@@ -601,7 +556,7 @@ def _build_report_writer_dispatch(
     okstra_bin: Path | None,
     idle_timeout_seconds: int,
     report_writer_codex_model: str,
-) -> WorkerDispatch:
+) -> WorkerJob:
     model_execution_value = (report_writer_codex_model or "").strip()
     if not model_execution_value:
         raise DispatchError(
@@ -612,15 +567,17 @@ def _build_report_writer_dispatch(
         project_root, _worker_prompt_path(manifest, REPORT_WRITER_WORKER_ID)
     )
     data_json_path = _final_report_data_path(
-        _resolve_required_path(project_root, manifest, "expectedReportPath", "report")
+        _resolve_required_path(project_root, manifest, "expectedReportPath")
     )
     markdown_path = _final_report_markdown_path(data_json_path)
     worker_result_path = _resolve_project_path(
         project_root, _require_string(worker_state, "resultPath")
     )
     _replace_report_writer_model_line(prompt_path, model_execution_value)
-    return WorkerDispatch(
+    return WorkerJob(
         worker_id=REPORT_WRITER_WORKER_ID,
+        # codex 경로의 report-writer 는 claude 가 아니라 codex wrapper 로 돈다.
+        provider="codex",
         backend=BACKEND_CLI_WRAPPER,
         project_root=project_root,
         model_execution_value=model_execution_value,
@@ -636,46 +593,10 @@ def _build_report_writer_dispatch(
         worktree_path="",
         role=REPORT_WRITER_WORKER_ID,
         idle_timeout_seconds=idle_timeout_seconds,
+        dispatch_kind="initial",
     )
 
 
-def _report_writer_prompt_body(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-) -> list[str]:
-    return [
-        "",
-        "# Report Writer Worker Dispatch",
-        "",
-        "## Role",
-        (
-            "You are the Report writer worker. Author the final-report data.json "
-            "and the worker-results audit file."
-        ),
-        "",
-        "## Task",
-        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
-        f"- Task type: `{_require_string(manifest, 'taskType')}`",
-        "",
-        "## Inputs",
-        *_report_writer_input_lines(manifest, active_context, team_state),
-        "",
-        _mcp_pointer_line(),
-        "",
-        "## Output Contract",
-        "You are the author of TWO files:",
-        "- The final-report data.json at Result Path.",
-        "- The worker-results audit file at Audit sidecar path.",
-        (
-            'After writing the data.json, invoke "okstra render-final-report '
-            '<Result Path>" so the markdown sibling is rendered before you return.'
-        ),
-        "Do not return the report inline.",
-        "Copy Report Language verbatim into data.json.meta.reportLanguage.",
-    ]
-
-
 def _base_prompt_headers(
     *,
     project_root: Path,
@@ -715,43 +636,6 @@ def _initial_prompt_plan(
         raise DispatchError(str(exc)) from exc
 
 
-def _report_writer_input_lines(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-) -> list[str]:
-    inputs = [
-        ("Task brief", _instruction_path(manifest, active_context, "taskBriefPath")),
-        ("Analysis profile", _instruction_path(manifest, active_context, "analysisProfilePath")),
-        ("Analysis material", _instruction_path(manifest, active_context, "analysisMaterialPath")),
-        ("Reference expectations", _instruction_path(manifest, active_context, "referenceExpectationsPath")),
-        ("Clarification response", _instruction_path(manifest, active_context, "clarificationResponsePath")),
-        ("Final report template", _instruction_path(manifest, active_context, "finalReportTemplatePath")),
-        ("Final report schema", _instruction_path(manifest, active_context, "finalReportSchemaPath")),
-        ("Worker results directory", _string_value(manifest.get("workerResultsDirectoryPath"))),
-    ]
-    lines = _existing_input_lines(inputs)
-    lines.extend(_analysis_worker_result_lines(team_state))
-    return lines or ["- No report-writer inputs were recorded in active-run-context."]
-
-
-def _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
-    lines = []
-    workers = team_state.get("workers")
-    if not isinstance(workers, list):
-        return lines
-    for worker in workers:
-        if not isinstance(worker, Mapping):
-            continue
-        worker_id = worker.get("workerId")
-        if worker_id == REPORT_WRITER_WORKER_ID:
-            continue
-        result_path = _string_value(worker.get("resultPath"))
-        if result_path:
-            lines.append(f"- Analysis result ({worker_id}): `{result_path}`")
-    return lines
-
-
 def _analysis_pane_role(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -864,54 +748,6 @@ def _clarification_response_section(
     ]
 
 
-def _resolve_report_language(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> str:
-    for value in _report_language_candidates(project_root):
-        if value == "auto":
-            return _infer_report_language(project_root, manifest, active_context)
-        if value:
-            return value
-    return _infer_report_language(project_root, manifest, active_context)
-
-
-def _report_language_candidates(project_root: Path) -> list[str]:
-    okstra_home = Path(os.environ.get("OKSTRA_HOME") or Path.home() / ".okstra")
-    return [
-        _read_report_language(project_root / ".okstra" / "project.json", "project"),
-        _read_report_language(okstra_home / "config.json", "global"),
-    ]
-
-
-def _read_report_language(path: Path, label: str) -> str:
-    if not path.is_file():
-        return ""
-    value = _load_json_object(path, f"{label} config").get("reportLanguage")
-    if value in (None, ""):
-        return ""
-    if isinstance(value, str) and value in REPORT_LANGUAGE_VALUES:
-        return value
-    raise DispatchError(f"{label} config reportLanguage must be en, ko, or auto: {path}")
-
-
-def _infer_report_language(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> str:
-    task_brief = _instruction_path(manifest, active_context, "taskBriefPath")
-    if not task_brief:
-        return "en"
-    path = _resolve_project_path(project_root, task_brief)
-    if not path.is_file():
-        return "en"
-    text = path.read_text(encoding="utf-8", errors="replace")[:16000]
-    hangul_count = sum(1 for char in text if "\uac00" <= char <= "\ud7a3")
-    return "ko" if hangul_count >= 10 else "en"
-
-
 def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
     if manifest.get("leadRuntime") != "codex":
         raise DispatchError(f"run manifest is not a Codex lead run: {path}")
@@ -1066,7 +902,7 @@ def _resolve_wrapper(
 
 def _run_worker(
     plan: DispatchPlan,
-    worker: WorkerDispatch,
+    worker: WorkerJob,
 ) -> subprocess.CompletedProcess[str]:
     if worker.backend == BACKEND_CLI_WRAPPER:
         return _run_cli_wrapper_worker(plan, worker)
@@ -1075,7 +911,7 @@ def _run_worker(
 
 def _run_cli_wrapper_worker(
     plan: DispatchPlan,
-    worker: WorkerDispatch,
+    worker: WorkerJob,
 ) -> subprocess.CompletedProcess[str]:
     env = {
         **os.environ,
@@ -1093,7 +929,7 @@ def _run_cli_wrapper_worker(
 
 def _post_process_report_writer_result(
     plan: DispatchPlan,
-    worker: WorkerDispatch,
+    worker: WorkerJob,
 ) -> dict[str, Any]:
     if worker.worker_id != REPORT_WRITER_WORKER_ID:
         return {"ok": True, "reason": "", "steps": []}
@@ -1137,14 +973,7 @@ def _append_event(
     )
 
 
-def _dispatch_mode(workers: Sequence[WorkerDispatch]) -> str:
-    backends = {worker.backend for worker in workers}
-    if len(backends) == 1:
-        return next(iter(backends))
-    return BACKEND_MIXED
-
-
-def _event_details(worker: WorkerDispatch) -> dict[str, Any]:
+def _event_details(worker: WorkerJob) -> dict[str, Any]:
     return {
         "dispatchMode": worker.backend,
         "workerId": worker.worker_id,
@@ -1156,7 +985,7 @@ def _event_details(worker: WorkerDispatch) -> dict[str, Any]:
     }
 
 
-def _attempt_event_details(worker: WorkerDispatch, attempt: int) -> dict[str, Any]:
+def _attempt_event_details(worker: WorkerJob, attempt: int) -> dict[str, Any]:
     return {
         **_event_details(worker),
         "attempt": attempt,
@@ -1176,69 +1005,6 @@ def _should_retry_missing_result(
     )
 
 
-def _missing_completion_paths(worker: WorkerDispatch) -> list[Path]:
-    return [path for path in worker.completion_paths if not path.is_file()]
-
-
-def _set_worker_status(
-    team_state_path: Path,
-    worker_id: str,
-    status: str,
-    reason: str,
-    *,
-    model_execution_value: str = "",
-) -> None:
-    payload = _load_json_object(team_state_path, "team-state")
-    workers = payload.get("workers")
-    if not isinstance(workers, list):
-        raise DispatchError(f"team-state workers must be an array: {team_state_path}")
-    for worker in workers:
-        if isinstance(worker, dict) and worker.get("workerId") == worker_id:
-            worker["status"] = status
-            worker["reason"] = reason
-            if model_execution_value:
-                worker["model"] = model_execution_value
-                worker["modelExecutionValue"] = model_execution_value
-            _write_json(team_state_path, payload)
-            return
-    raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
-
-
-def _set_dispatch_mode(team_state_path: Path, dispatch_mode: str) -> None:
-    payload = _load_json_object(team_state_path, "team-state")
-    payload["dispatchMode"] = dispatch_mode
-    _write_json(team_state_path, payload)
-
-
-def _worker_state(team_state: Mapping[str, Any], worker_id: str) -> Mapping[str, Any]:
-    workers = team_state.get("workers")
-    if not isinstance(workers, list):
-        raise DispatchError("team-state workers must be an array")
-    for worker in workers:
-        if isinstance(worker, Mapping) and worker.get("workerId") == worker_id:
-            return worker
-    raise DispatchError(f"team-state has no workerId={worker_id}")
-
-
-def _worker_prompt_path(manifest: Mapping[str, Any], worker_id: str) -> str:
-    paths = manifest.get("workerPromptPathByWorkerId")
-    if not isinstance(paths, Mapping):
-        raise DispatchError("run manifest has no workerPromptPathByWorkerId object")
-    return _require_string(paths, worker_id)
-
-
-def _worktree_path(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> str:
-    if manifest.get("taskType") not in {"implementation", "final-verification"}:
-        return ""
-    worktree = active_context.get("executorWorktree")
-    if not isinstance(worktree, Mapping):
-        return ""
-    return str(worktree.get("path") or "")
-
-
 def _pane_role(prompt_path: Path) -> str:
     if not prompt_path.is_file():
         raise DispatchError(f"worker prompt not found: {prompt_path}")
@@ -1250,39 +1016,12 @@ def _pane_role(prompt_path: Path) -> str:
     return "worker"
 
 
-def _load_json_object(path: Path, label: str) -> dict[str, Any]:
-    if not path.is_file():
-        raise DispatchError(f"{label} not found: {path}")
-    try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        raise DispatchError(f"{label} is invalid JSON: {path}: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise DispatchError(f"{label} must be a JSON object: {path}")
-    return payload
-
-
 def _load_optional_json_object(path: Path | None) -> dict[str, Any]:
     if path is None or not path.is_file():
         return {}
     return hydrate_active_run_context(_load_json_object(path, "active-run-context"))
 
 
-def _resolve_required_path(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    key: str,
-    label: str,
-) -> Path:
-    return _resolve_project_path(project_root, _require_string(manifest, key))
-
-
-def _string_list(value: Any) -> list[str]:
-    if not isinstance(value, list):
-        return []
-    return [str(item).strip() for item in value if str(item).strip()]
-
-
 def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     if exit_code != 0:
         return f"wrapper exited with code {exit_code}"
@@ -1323,20 +1062,6 @@ def _parse_idle_timeout(raw: str) -> int:
     return value
 
 
-def _utc_now() -> str:
-    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    # Write via temp file + os.replace so a crash mid-write cannot leave a
-    # truncated team-state.json that every later _load_json_object rejects;
-    # os.replace is atomic on POSIX, matching run_context._atomic_write_json.
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
-                   encoding="utf-8")
-    os.replace(tmp, path)
-
-
 def _print_json(payload: Mapping[str, Any]) -> None:
     print(json.dumps(payload, ensure_ascii=False, indent=2))
 

package/runtime/python/okstra_ctl/consumers.py

@@ -202,7 +202,7 @@ def pr_covered_stages(rows: List[Dict[str, Any]]) -> set:
 # `runs/implementation/carry/stage-<N>.json`. The `done` row in consumers.jsonl
 # is a derived index that the lead appends by hand (per the implementation
 # profile) — so it can be missing even when the stage actually finished. The
-# dependency gate (`_resolve_stage_base_commit`) reads `done.head_commit`, so a
+# dependency gate (`stage_targets.resolve_stage_base_commit`) reads `done.head_commit`, so a
 # missing `done` row wrongly blocks downstream stages. We treat the carry file
 # as the source of truth and backfill the missing `done` rows from it before
 # the gate runs. A stage with no carry, or an unfinished carry, is left blocked
@@ -218,7 +218,9 @@ def _carry_stage_number(carry: Dict[str, Any], filename: str) -> Optional[int]:
     return int(m.group(1)) if m else None
 
 
-_FAILED_CARRY_STATUSES = ("fail", "failed", "blocked", "error", "aborted")
+FAILED_CARRY_STATUSES = ("fail", "failed", "blocked", "error", "aborted")
+"""carry 가 실패를 명시하는 status 값. 이 목록은 하나의 business fact 다 —
+implementation_outcome 의 pass-grade 판정도 같은 목록을 본다."""
 
 
 def _carry_is_complete(carry: Dict[str, Any]) -> bool:
@@ -227,12 +229,12 @@ def _carry_is_complete(carry: Dict[str, Any]) -> bool:
     # Treat it as complete unless it explicitly records a failure status. The
     # real backfill guard is whether a head commit can be extracted.
     status = carry.get("status")
-    if status is not None and str(status).lower() in _FAILED_CARRY_STATUSES:
+    if status is not None and str(status).lower() in FAILED_CARRY_STATUSES:
         return False
     return True
 
 
-def _carry_head_commit(carry: Dict[str, Any]) -> str:
+def carry_head_commit(carry: Dict[str, Any]) -> str:
     rng = carry.get("stageCommitRange")
     if isinstance(rng, dict) and rng.get("head"):
         return str(rng["head"])
@@ -288,7 +290,7 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
             continue
         if not _carry_is_complete(carry):
             continue
-        head = _carry_head_commit(carry)
+        head = carry_head_commit(carry)
         if not head:
             continue
         impl_key = key_by_stage.get(stage) or carry.get("impl_task_key") or fallback_key