okstra 0.135.0 → 0.137.0

package/runtime/python/okstra_ctl/context_cost.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
+from okstra_ctl.paths import RunRef, runs_dir_of, task_manifest_file
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
 
@@ -102,7 +103,7 @@ def _find_current_run_dir(
     task_type = manifest.get("workflow", {}).get("currentPhase") or manifest.get("taskType")
     if not isinstance(task_type, str) or not task_type:
         return None
-    candidate = task_root / "runs" / task_type
+    candidate = RunRef.from_task_root(task_root, task_type).run_dir
     return candidate if candidate.is_dir() else None
 
 
@@ -244,7 +245,7 @@ def _lead_phase1_metric(
         instruction_set = task_root / "instruction-set"
         packet = instruction_set / "analysis-packet.md"
         files = [
-            task_root / "task-manifest.json",
+            task_manifest_file(task_root),
             active_path,
             instruction_set / "analysis-profile.md",
             packet if packet.is_file() else instruction_set / "task-brief.md",
@@ -264,7 +265,7 @@ def _lead_phase1_metric(
                 state_dir, f"team-state-{current_phase}-*.json"
             )
         files = [
-            task_root / "task-manifest.json",
+            task_manifest_file(task_root),
             task_root / "instruction-set" / "task-brief.md",
             task_root / "instruction-set" / "analysis-profile.md",
         ]
@@ -401,13 +402,13 @@ def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: P
 
 
 def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
-    manifest = _load_json(task_root / "task-manifest.json")
+    manifest = _load_json(task_manifest_file(task_root))
     run_dir = _find_current_run_dir(task_root, manifest, project_root)
     all_task_files = _all_files(task_root)
     task_file_count, task_bytes = _count_files(all_task_files)
     current_run_file_count, current_run_bytes = _count_files(_all_files(run_dir)) if run_dir else (0, 0)
     legacy_timestamp_files = [
-        path for path in (task_root / "runs").rglob("*")
+        path for path in runs_dir_of(task_root).rglob("*")
         if path.is_file() and _is_timestamped_legacy_artifact(path)
     ]
 

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_log_core.py

@@ -8,9 +8,11 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .paths import runs_dir_of
+
 
 def glob_error_logs(task_root: Path) -> list[Path]:
-    runs = task_root / "runs"
+    runs = runs_dir_of(task_root)
     if not runs.exists():
         return []
     flat = runs.glob("*/logs/errors-*.jsonl")

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/handoff.py

@@ -14,6 +14,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
+from .paths import RunRef
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
                        nested_worktree_excludes, is_ancestor, merge_branch,
@@ -62,7 +63,7 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
                           f"{project_id}:{task_group}:{task_id}")
     if root is None:
         return ""
-    reports_dir = root / "runs" / "final-verification" / "reports"
+    reports_dir = RunRef.from_task_root(root, "final-verification").reports_dir
     for dj in sorted(reports_dir.glob("final-report-*.data.json"),
                      reverse=True):
         try: