okstra 0.136.0 → 0.138.0

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(

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any
 
 from . import stage_targets
-from .design_prep import DesignPrepDecision, resolve_design_prep
+from .design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
 from .final_report_paths import final_report_data_path
 from .stage_reconcile import auto_reconcile_best_effort
 
@@ -56,7 +56,12 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
 def _resolve_stage_design_prep(plan_path: Path, stage: int) -> DesignPrepDecision:
     plan_data_path = final_report_data_path(plan_path)
     if plan_data_path.is_file():
-        return resolve_design_prep(plan_data_path, stage)
+        try:
+            return resolve_design_prep(plan_data_path, stage)
+        except DesignPrepError as exc:
+            # prepare catches ImplementationStageError → PrepareError; an
+            # untranslated DesignPrepError leaves okstra_ctl.run as a traceback.
+            raise _as_implementation_stage_error(exc) from exc
     return DesignPrepDecision(
         outcome="proceed",
         effective_items=(),