okstra 0.136.0 → 0.137.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -11,6 +11,29 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import tmux
+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 .final_report_paths import (
     final_report_data_path as _final_report_data_path,
     final_report_markdown_path as _final_report_markdown_path,
@@ -18,74 +41,21 @@ from .final_report_paths import (
 from .lead_events import LeadEvent, append_lead_event
 from .path_hints import hydrate_active_run_context
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
-from .worker_prompt_body import analysis_prompt_body
+from .report_language import resolve_report_language
+from .worker_prompt_body import analysis_prompt_body, report_writer_prompt_body
+from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_policy import resolve_prompt_plan_for_manifest
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
-BACKEND_CLI_WRAPPER = "cli-wrapper"
-BACKEND_TMUX_PANE = "tmux-pane"
-BACKEND_MIXED = "mixed"
 LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
 LIVENESS_WRAPPER_STATUS = "wrapper-status"
 MAX_WORKER_ATTEMPTS = 2
-REPORT_WRITER_WORKER_ID = "report-writer"
 TERMINAL_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
 
 
-class DispatchError(Exception):
-    """Raised when a worker dispatch request cannot be executed."""
-
-
-@dataclass(frozen=True)
-class WorkerJob:
-    worker_id: str
-    provider: 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
-    dispatch_kind: str
-
-    @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,
-            "provider": self.provider,
-            "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,
-            "dispatchKind": self.dispatch_kind,
-            "command": self.command,
-        }
-
-
 @dataclass(frozen=True)
 class WorkerHandle:
     job: WorkerJob
@@ -202,20 +172,6 @@ def build_dispatch_plan(
     )
 
 
-def _validate_initial_prompts(
-    manifest: Mapping[str, Any],
-    jobs: Sequence[WorkerJob],
-) -> None:
-    records = [
-        PromptRecord(job.worker_id, job.dispatch_kind, job.prompt_path)
-        for job in jobs
-    ]
-    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, *, wait: bool = True) -> int:
     if wait:
         if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
@@ -334,6 +290,7 @@ def _job_from_roster_worker(
         result_rel=result_rel,
         project_root=project_root,
         manifest=manifest,
+        team_state=team_state,
         active_context=active_context,
         dispatch_kind=options.dispatch_kind,
         model=model,
@@ -350,7 +307,7 @@ def _job_from_roster_worker(
         result_path=_result_path_for_worker(worker_id, result_path, manifest, project_root),
         worker_result_path=result_path,
         completion_paths=_completion_paths(worker_id, result_path, manifest, project_root),
-        worktree_path=_worktree_path(active_context),
+        worktree_path=_worktree_path(manifest, active_context),
         role=_string_value(state.get("role")) or "worker",
         idle_timeout_seconds=options.idle_timeout_seconds,
         dispatch_kind=options.dispatch_kind,
@@ -412,7 +369,10 @@ def _job_from_file_worker(
 
 
 def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle:
-    _set_worker_status(plan.team_state_path, job.worker_id, "running", "", job.model_execution_value)
+    _set_worker_status(
+        plan.team_state_path, job.worker_id, "running", "",
+        model_execution_value=job.model_execution_value,
+    )
     handle = _start_job(plan, job)
     _record_dispatch(plan.team_state_path, handle, attempt, "running", "")
     _append_event(plan, "worker-dispatched", _attempt_details(job, attempt, handle))
@@ -595,30 +555,6 @@ def _record_matches(record: object, worker_id: str, kind: str, attempt: int) ->
     return isinstance(record, dict) and record.get("workerId") == worker_id and record.get("kind") == kind and record.get("attempt") == attempt
 
 
-def _set_worker_status(
-    team_state_path: Path, worker_id: str, status: str, reason: str, model: 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:
-                worker["model"] = model
-                worker["modelExecutionValue"] = model
-            _write_json(team_state_path, payload)
-            return
-
-
-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 _running_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
     payload = _load_json_object(team_state_path, "team-state")
     dispatches = payload.get("workerDispatches")
@@ -764,10 +700,6 @@ def _failure_reason(outcome: WorkerOutcome) -> str:
     return "worker dispatch failed"
 
 
-def _missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
-    return tuple(path for path in job.completion_paths if not path.is_file())
-
-
 def _mode_from_handles(handles: Sequence[WorkerHandle]) -> str:
     modes = {BACKEND_CLI_WRAPPER if h.degraded_from else h.job.backend for h in handles}
     if len(modes) == 1:
@@ -775,13 +707,6 @@ def _mode_from_handles(handles: Sequence[WorkerHandle]) -> str:
     return BACKEND_MIXED
 
 
-def _dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
-    backends = {job.backend for job in jobs}
-    if len(backends) == 1:
-        return next(iter(backends))
-    return BACKEND_MIXED
-
-
 def _validate_manifest(manifest: Mapping[str, Any], path: Path, required: str | None) -> None:
     if required is not None and manifest.get("leadRuntime") != required:
         raise DispatchError(f"run manifest is not a {required} lead run: {path}")
@@ -811,6 +736,7 @@ def _materialize_prompt_if_missing(
     result_rel: str,
     project_root: Path,
     manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
     active_context: Mapping[str, Any],
     dispatch_kind: str,
     model: str,
@@ -819,11 +745,20 @@ def _materialize_prompt_if_missing(
     if prompt_path.is_file():
         return
     prompt_path.parent.mkdir(parents=True, exist_ok=True)
+    audit_source_rel = ""
+    if worker_id == REPORT_WRITER_WORKER_ID:
+        # The report-writer's Result Path is the report data.json; its own worker
+        # result stays the markdown the audit sidecar is derived from.
+        audit_source_rel = result_rel
+        result_rel = str(_final_report_data_path(
+            Path(_require_string(manifest, "expectedReportPath"))
+        ))
     try:
         headers = worker_prompt_headers(
             project_root=project_root,
             prompt_rel=prompt_rel,
             result_rel=result_rel,
+            audit_source_rel=audit_source_rel or None,
             worker_id=worker_id,
             dispatch_kind=dispatch_kind,
             manifest=manifest,
@@ -840,13 +775,23 @@ def _materialize_prompt_if_missing(
     except ValueError as exc:
         raise DispatchError(str(exc)) from exc
     lines = list(headers)
-    if plan.audience in {
+    if plan.audience == "report-writer":
+        lines.extend(
+            report_writer_prompt_body(
+                manifest,
+                active_context,
+                team_state,
+                model,
+                resolve_report_language(project_root, manifest, active_context),
+            )
+        )
+    elif plan.audience in {
         "analysis",
         "implementation-executor",
         "implementation-verifier",
     }:
         if _string_value(manifest.get("taskType")) == "implementation":
-            worktree = _worktree_path(active_context)
+            worktree = _worktree_path(manifest, active_context)
             if not worktree:
                 raise DispatchError(
                     "implementation prompt generation requires a worktree path"
@@ -905,38 +850,6 @@ def _run_dir(plan: DispatchPlan) -> Path:
     return _resolve_project_path(plan.project_root, value) if value else plan.team_state_path.parent.parent
 
 
-def _worktree_path(active_context: Mapping[str, Any]) -> str:
-    worktree = active_context.get("executorWorktree")
-    if isinstance(worktree, dict):
-        return _string_value(worktree.get("path"))
-    return ""
-
-
-def _worker_state(team_state: Mapping[str, Any], worker_id: str) -> Mapping[str, Any]:
-    workers = team_state.get("workers")
-    if isinstance(workers, list):
-        for worker in workers:
-            if isinstance(worker, dict) 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")
-    return _require_string(paths, worker_id)
-
-
-def _load_json_object(path: Path, label: str) -> dict[str, Any]:
-    if not path.is_file():
-        raise DispatchError(f"{label} not found: {path}")
-    payload = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(payload, dict):
-        raise DispatchError(f"{label} must be a JSON object: {path}")
-    return payload
-
-
 def _load_optional_json(project_root: Path, value: Any) -> dict[str, Any]:
     if not isinstance(value, str) or not value.strip():
         return {}
@@ -946,38 +859,12 @@ def _load_optional_json(project_root: Path, value: Any) -> dict[str, Any]:
     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) -> Path:
-    return _resolve_project_path(project_root, _require_string(manifest, key))
-
-
-def _resolve_project_path(project_root: Path, value: str) -> Path:
-    path = Path(value)
-    return path if path.is_absolute() else project_root / path
-
-
 def _optional_path(value: object) -> Path | None:
     if not isinstance(value, str) or not value.strip():
         return None
     return Path(value)
 
 
-def _require_string(payload: Mapping[str, Any], key: str) -> str:
-    value = payload.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise DispatchError(f"required string missing: {key}")
-    return value.strip()
-
-
-def _string_value(value: Any) -> str:
-    return value.strip() if isinstance(value, str) else ""
-
-
-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 _run_seq(manifest: Mapping[str, Any]) -> str:
     seqs = manifest.get("runSequencesByCategory")
     if isinstance(seqs, Mapping):
@@ -985,11 +872,3 @@ def _run_seq(manifest: Mapping[str, Any]) -> str:
     return "001"
 
 
-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:
-    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)

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -0,0 +1,231 @@
+"""Worker dispatch plumbing shared by both lead dispatchers.
+
+`dispatch_core` (claude / external lead) and `codex_dispatch` (codex lead) differ
+in capability — only the former has tmux panes, blocking waits, and retry from a
+persisted record. What they do *not* differ in is the job value object and the
+run's state files: the same run-manifest keys, the same team-state document, the
+same wrapper argv.
+
+Those used to be two copies that had already drifted apart: one dispatcher
+wrapped a truncated team-state in `DispatchError` while the other let
+`json.JSONDecodeError` escape, one raised on an unknown `workerId` while the
+other silently did nothing, and one gated the worktree argument on task type
+while the other handed it to every phase. This module is the single reference
+point so a fix cannot land on one lead runtime only.
+
+Enforced by `tests/contract/test_dispatcher_shared_helpers.py`.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+
+BACKEND_CLI_WRAPPER = "cli-wrapper"
+BACKEND_TMUX_PANE = "tmux-pane"
+BACKEND_MIXED = "mixed"
+
+# The worktree argument grants the wrapper `--add-dir` write access outside
+# project-root. Only the phases whose workers mutate a stage worktree get it;
+# analysis phases write their artifacts under project-root (see the contract in
+# scripts/okstra-codex-exec.sh).
+WORKTREE_TASK_TYPES = frozenset({"implementation", "final-verification"})
+
+
+class DispatchError(Exception):
+    """Raised when a worker dispatch request cannot be executed."""
+
+
+@dataclass(frozen=True)
+class WorkerJob:
+    worker_id: str
+    provider: 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
+    dispatch_kind: str
+
+    @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,
+            "provider": self.provider,
+            "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,
+            "dispatchKind": self.dispatch_kind,
+            "command": self.command,
+        }
+
+
+# --- run-manifest reads -------------------------------------------------------
+
+def string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise DispatchError(f"missing required string field: {key}")
+    return value.strip()
+
+
+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 resolve_project_path(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def resolve_required_path(
+    project_root: Path, manifest: Mapping[str, Any], key: str
+) -> Path:
+    return resolve_project_path(project_root, require_string(manifest, key))
+
+
+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 WORKTREE_TASK_TYPES:
+        return ""
+    worktree = active_context.get("executorWorktree")
+    if not isinstance(worktree, Mapping):
+        return ""
+    return str(worktree.get("path") or "")
+
+
+# --- team-state document ------------------------------------------------------
+
+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 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 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 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)
+
+
+# --- job facts ----------------------------------------------------------------
+
+def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
+    backends = {job.backend for job in jobs}
+    if len(backends) == 1:
+        return next(iter(backends))
+    return BACKEND_MIXED
+
+
+def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
+    return tuple(path for path in job.completion_paths if not path.is_file())
+
+
+def validate_initial_prompts(
+    manifest: Mapping[str, Any], jobs: Sequence[WorkerJob]
+) -> None:
+    records = [
+        PromptRecord(job.worker_id, job.dispatch_kind, job.prompt_path)
+        for job in jobs
+    ]
+    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 utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

package/runtime/python/okstra_ctl/error_report.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 
 from okstra_ctl.task_target import resolve_task_root, project_rel
+from okstra_project import read_task_key
 from okstra_ctl.error_log_core import (
     glob_error_logs,
     parse_records,
@@ -80,13 +81,7 @@ def _timestamp_segment(now: dt.datetime) -> str:
 
 
 def build_and_write(task_root: Path, project_root: Path, now: dt.datetime) -> dict:
-    manifest_path = task_root / "task-manifest.json"
-    task_key = ""
-    if manifest_path.is_file():
-        try:
-            task_key = json.loads(manifest_path.read_text(encoding="utf-8")).get("taskKey", "")
-        except Exception:
-            task_key = ""
+    task_key = read_task_key(task_root)
     paths = glob_error_logs(task_root)
     records, skipped = parse_records(paths)
     agg = aggregate(records)

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -6,8 +6,12 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from .consumers import read_stage_consumer_state
-from .paths import RunRef
+from .consumers import (
+    FAILED_CARRY_STATUSES,
+    carry_head_commit,
+    read_stage_consumer_state,
+)
+from .paths import RunRef, task_manifest_file
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -23,7 +27,7 @@ class ImplementationOutcome:
 
 def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     task_root = Path(task_root)
-    manifest = _load_json(task_root / "task-manifest.json")
+    manifest = _load_json(task_manifest_file(task_root))
     workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
     if workflow.get("currentPhase") != "implementation":
         return ImplementationOutcome(completed=False, reason="current phase is not implementation")
@@ -32,7 +36,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     if not plan_run_root.is_dir():
         return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
 
-    stage_map = _load_stage_map(task_root, manifest)
+    stage_map = load_stage_map(task_root, manifest)
     if not stage_map:
         return ImplementationOutcome(completed=False, reason="stage map unavailable")
 
@@ -53,7 +57,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     return ImplementationOutcome(
         completed=True,
         stages=sorted(required_stages),
-        head_commit=str(latest_done.get("head_commit") or "") or _carry_head_commit(latest_carry),
+        head_commit=str(latest_done.get("head_commit") or "") or carry_head_commit(latest_carry),
         report_path=_latest_implementation_report(task_root),
         next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
         reason="all implementation stages have pass-grade carry and done rows",
@@ -67,7 +71,7 @@ def reconcile_implementation_outcome(project_root: Path, task_root: Path) -> boo
     if not outcome.completed:
         return False
 
-    manifest_path = task_root / "task-manifest.json"
+    manifest_path = task_manifest_file(task_root)
     manifest = _load_json(manifest_path)
     workflow = manifest.get("workflow")
     if not isinstance(workflow, dict):
@@ -110,7 +114,7 @@ def _load_json(path: Path) -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
-def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
+def load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
     plan_path = _source_plan_path(task_root, manifest)
     if not plan_path.is_file():
         return []
@@ -177,7 +181,7 @@ def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
 
 def _carry_passed(carry: dict[str, Any]) -> bool:
     status = str(carry.get("status") or "").lower()
-    if status in {"fail", "failed", "blocked", "error", "aborted"}:
+    if status in FAILED_CARRY_STATUSES:
         return False
     conformance = carry.get("conformance")
     if isinstance(conformance, dict):
@@ -188,21 +192,6 @@ def _carry_passed(carry: dict[str, Any]) -> bool:
     return not (isinstance(unverified, list) and unverified)
 
 
-def _carry_head_commit(carry: dict[str, Any]) -> str:
-    stage_range = carry.get("stageCommitRange")
-    if isinstance(stage_range, dict) and stage_range.get("head"):
-        return str(stage_range["head"])
-    for key in ("head_sha", "head_commit", "head"):
-        value = carry.get(key)
-        if value:
-            return str(value)
-    commits = carry.get("commits")
-    if isinstance(commits, list) and commits:
-        last = commits[-1]
-        if isinstance(last, dict) and last.get("sha"):
-            return str(last["sha"])
-    return ""
-
 
 def _latest_implementation_report(task_root: Path) -> str:
     reports = sorted(