okstra 0.136.0 → 0.138.0

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

package/runtime/python/okstra_ctl/context_cost.py

@@ -13,7 +13,7 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
-from okstra_ctl.paths import RunRef, runs_dir_of
+from okstra_ctl.paths import RunRef, runs_dir_of, task_manifest_file
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
 
@@ -245,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",
@@ -265,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",
         ]
@@ -402,7 +402,7 @@ 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)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -11,81 +11,52 @@ 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_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,
 )
 from .lead_events import LeadEvent, append_lead_event
+from .initial_prompt_materialization import (
+    InitialPromptMaterializationError,
+    InitialPromptMaterializationRequest,
+    InitialPromptWorkerRequest,
+    PromptDeliveryMode,
+    materialize_initial_prompts,
+)
 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 .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
-from .worker_prompt_policy import resolve_prompt_plan_for_manifest
+from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 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
@@ -146,6 +117,15 @@ class _BuildOptions:
     dispatch_kind: str
 
 
+@dataclass(frozen=True)
+class _RosterWorkerFacts:
+    worker_id: str
+    model: str
+    provider: str
+    result_path: str
+    role: str
+
+
 def build_dispatch_plan(
     *,
     project_root: Path,
@@ -178,18 +158,22 @@ def build_dispatch_plan(
         unsupported_worker_label=unsupported_worker_label,
         dispatch_kind=dispatch_kind,
     )
-    jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options) if jobs_file else _jobs_from_roster(
-        project_root,
-        workspace_root,
-        manifest,
-        team_state,
-        active_context,
-        requested_workers,
-        enable_report_writer,
-        report_writer_model,
-        options,
-    )
-    _validate_initial_prompts(manifest, jobs)
+    if jobs_file:
+        jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
+        _validate_initial_prompts(manifest, jobs)
+    else:
+        jobs = _jobs_from_roster(
+            project_root,
+            workspace_root,
+            manifest_path,
+            manifest,
+            team_state,
+            active_context,
+            requested_workers,
+            enable_report_writer,
+            report_writer_model,
+            options,
+        )
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -202,20 +186,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):
@@ -264,6 +234,7 @@ def await_dispatches(
 def _jobs_from_roster(
     project_root: Path,
     workspace_root: Path,
+    manifest_path: Path,
     manifest: Mapping[str, Any],
     team_state: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -274,12 +245,27 @@ def _jobs_from_roster(
 ) -> list[WorkerJob]:
     selected = _select_workers(manifest, requested_workers, enable_report_writer, options)
     _mark_roster_skips(project_root, manifest, team_state, selected, requested_workers, options)
+    worker_facts, prompt_paths = _materialize_roster_prompts(
+        project_root,
+        workspace_root,
+        manifest_path,
+        manifest,
+        team_state,
+        selected,
+        report_writer_model,
+        options,
+    )
     return [
         _job_from_roster_worker(
-            project_root, workspace_root, manifest, team_state, active_context,
-            worker_id, report_writer_model, options,
+            project_root,
+            workspace_root,
+            manifest,
+            active_context,
+            fact,
+            prompt_path,
+            options,
         )
-        for worker_id in selected
+        for fact, prompt_path in zip(worker_facts, prompt_paths, strict=True)
     ]
 
 
@@ -314,49 +300,87 @@ def _job_from_roster_worker(
     project_root: Path,
     workspace_root: Path,
     manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
     active_context: Mapping[str, Any],
-    worker_id: str,
-    report_writer_model: str,
+    fact: _RosterWorkerFacts,
+    prompt_path: Path,
     options: _BuildOptions,
 ) -> WorkerJob:
-    state = _worker_state(team_state, worker_id)
-    provider = _provider_for_worker(worker_id)
-    model = _model_for_worker(worker_id, state, report_writer_model)
-    prompt_rel = _worker_prompt_path(manifest, worker_id)
-    result_rel = _require_string(state, "resultPath")
-    prompt_path = _resolve_project_path(project_root, prompt_rel)
-    result_path = _resolve_project_path(project_root, result_rel)
-    _materialize_prompt_if_missing(
-        prompt_path=prompt_path,
-        prompt_rel=prompt_rel,
-        worker_id=worker_id,
-        result_rel=result_rel,
-        project_root=project_root,
-        manifest=manifest,
-        active_context=active_context,
-        dispatch_kind=options.dispatch_kind,
-        model=model,
-        role=_string_value(state.get("role")) or "worker",
-    )
+    result_path = _resolve_project_path(project_root, fact.result_path)
     return WorkerJob(
-        worker_id=worker_id,
-        provider=provider,
+        worker_id=fact.worker_id,
+        provider=fact.provider,
         backend=options.default_backend,
         project_root=project_root,
-        model_execution_value=model,
-        wrapper_path=_resolve_wrapper(provider, workspace_root, options),
+        model_execution_value=fact.model,
+        wrapper_path=_resolve_wrapper(fact.provider, workspace_root, options),
         prompt_path=prompt_path,
-        result_path=_result_path_for_worker(worker_id, result_path, manifest, project_root),
+        result_path=_result_path_for_worker(
+            fact.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),
-        role=_string_value(state.get("role")) or "worker",
+        completion_paths=_completion_paths(
+            fact.worker_id, result_path, manifest, project_root
+        ),
+        worktree_path=_worktree_path(manifest, active_context),
+        role=fact.role,
         idle_timeout_seconds=options.idle_timeout_seconds,
         dispatch_kind=options.dispatch_kind,
     )
 
 
+def _materialize_roster_prompts(
+    project_root: Path,
+    workspace_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    selected: Sequence[str],
+    report_writer_model: str,
+    options: _BuildOptions,
+) -> tuple[tuple[_RosterWorkerFacts, ...], tuple[Path, ...]]:
+    worker_facts = tuple(
+        _roster_worker_facts(team_state, worker_id, report_writer_model)
+        for worker_id in selected
+    )
+    try:
+        prompt_paths = materialize_initial_prompts(
+            InitialPromptMaterializationRequest(
+                project_root=project_root,
+                run_manifest_path=manifest_path,
+                runtime_root=workspace_root,
+                delivery_mode=_delivery_mode(options.default_backend),
+                workers=tuple(
+                    InitialPromptWorkerRequest(fact.worker_id, fact.model)
+                    for fact in worker_facts
+                ),
+            )
+        )
+    except InitialPromptMaterializationError as exc:
+        raise DispatchError(f"{exc.reason}: {exc}") from exc
+    return worker_facts, prompt_paths
+
+
+def _roster_worker_facts(
+    team_state: Mapping[str, Any],
+    worker_id: str,
+    report_writer_model: str,
+) -> _RosterWorkerFacts:
+    state = _worker_state(team_state, worker_id)
+    return _RosterWorkerFacts(
+        worker_id=worker_id,
+        model=_model_for_worker(worker_id, state, report_writer_model),
+        provider=_provider_for_worker(worker_id),
+        result_path=_require_string(state, "resultPath"),
+        role=_string_value(state.get("role")) or "worker",
+    )
+
+
+def _delivery_mode(default_backend: str) -> PromptDeliveryMode:
+    if default_backend == BACKEND_TMUX_PANE:
+        return PromptDeliveryMode.LAZY_PATH_REFERENCE
+    return PromptDeliveryMode.EAGER_INCLUDE
+
+
 def _jobs_from_file(
     project_root: Path,
     workspace_root: Path,
@@ -412,7 +436,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 +622,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 +767,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 +774,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}")
@@ -803,71 +795,6 @@ def _resolve_wrapper(provider: str, workspace_root: Path, options: _BuildOptions
     raise DispatchError(f"{script} not found (searched: {', '.join(str(c) for c in candidates)})")
 
 
-def _materialize_prompt_if_missing(
-    *,
-    prompt_path: Path,
-    prompt_rel: str,
-    worker_id: str,
-    result_rel: str,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    dispatch_kind: str,
-    model: str,
-    role: str,
-) -> None:
-    if prompt_path.is_file():
-        return
-    prompt_path.parent.mkdir(parents=True, exist_ok=True)
-    try:
-        headers = worker_prompt_headers(
-            project_root=project_root,
-            prompt_rel=prompt_rel,
-            result_rel=result_rel,
-            worker_id=worker_id,
-            dispatch_kind=dispatch_kind,
-            manifest=manifest,
-            active_context=active_context,
-        )
-    except WorkerPromptHeaderError as exc:
-        raise DispatchError(str(exc)) from exc
-    try:
-        plan = resolve_prompt_plan_for_manifest(
-            manifest=manifest,
-            worker_id=worker_id,
-            dispatch_kind=dispatch_kind,
-        )
-    except ValueError as exc:
-        raise DispatchError(str(exc)) from exc
-    lines = list(headers)
-    if plan.audience in {
-        "analysis",
-        "implementation-executor",
-        "implementation-verifier",
-    }:
-        if _string_value(manifest.get("taskType")) == "implementation":
-            worktree = _worktree_path(active_context)
-            if not worktree:
-                raise DispatchError(
-                    "implementation prompt generation requires a worktree path"
-                )
-            lines.append(f"**Worktree:** {worktree}")
-        try:
-            lines.extend(
-                analysis_prompt_body(
-                    manifest,
-                    active_context,
-                    worker_id,
-                    model,
-                    role,
-                    plan,
-                )
-            )
-        except ValueError as exc:
-            raise DispatchError(str(exc)) from exc
-    prompt_path.write_text("\n".join([*lines, ""]), encoding="utf-8")
-
-
 def _provider_for_worker(worker_id: str) -> str:
     if worker_id == REPORT_WRITER_WORKER_ID:
         return "claude"
@@ -905,38 +832,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,50 +841,14 @@ 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):
         return _string_value(seqs.get("manifests")) or "001"
     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)