okstra 0.136.0 → 0.138.0

package/runtime/python/okstra_ctl/set_work_status.py

@@ -15,6 +15,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.paths import task_dir, task_manifest_file
 from okstra_project import (
     ResolverError,
     StateError,
@@ -40,7 +41,7 @@ def _manifest_path(project_root: Path, entry: dict) -> Path:
     id_seg = entry.get("taskIdPathSegment") or slugify_task_segment(
         entry.get("taskId", "")
     )
-    return project_root / ".okstra" / "tasks" / group_seg / id_seg / "task-manifest.json"
+    return task_manifest_file(task_dir(project_root, group_seg, id_seg))
 
 
 def main(argv: list[str] | None = None) -> int:

package/runtime/python/okstra_ctl/stage_targets.py

@@ -8,10 +8,12 @@ the stage lifecycle rules behind one interface instead of leaking raw
 from __future__ import annotations
 
 import heapq
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
+from .stage_integrate import IntegrateResult
+
 
 RUN_STEP_BUDGET = 8
 
@@ -38,6 +40,29 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
+@dataclass(frozen=True)
+class FinalVerificationTargetRequest:
+    """Semantic inputs needed to acquire one final-verification target."""
+
+    project_root: Path
+    project_id: str
+    task_group: str
+    task_id: str
+    work_category: str
+    approved_plan_path: Path
+    stage: int | None
+    stage_map: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetAcquisition:
+    """Resolved target facts returned to the prepare adapter."""
+
+    target: FinalVerificationTarget
+    worktree_branch: str
+    integration_result: IntegrateResult | None
+
+
 @dataclass(frozen=True)
 class StageLifecycle:
     stage: int
@@ -49,6 +74,23 @@ class StageLifecycle:
     pr_covered: bool
     head_commit: str
     report_path: str
+    step_count: int
+    deps_satisfied: bool
+    blocked_by: list[int]
+
+    @property
+    def status(self) -> str:
+        """Lifecycle state, in precedence order: done > active > ready > blocked.
+
+        ``started`` and ``reserved`` collapse into ``active`` because every
+        caller that distinguishes them already words the two the same way (see
+        the numeric-request error in ``resolve_effective_stages``).
+        """
+        if self.done:
+            return "done"
+        if self.started or self.reserved:
+            return "active"
+        return "ready" if self.deps_satisfied else "blocked"
 
     def handoff_eligibility_record(self) -> dict[str, Any]:
         reasons: list[str] = []
@@ -92,14 +134,67 @@ class StageLifecycleSnapshot:
         requested: str,
         budget: int = RUN_STEP_BUDGET,
     ) -> list[int]:
-        return resolve_effective_stages(
-            self.stage_map,
-            self.done_stages,
-            requested,
-            budget=budget,
-            started_stages=self.started_stages,
-            reserved_stages=self.reserved_stages,
+        """Return ordered stage numbers this run should execute.
+
+        ``requested`` is ``"auto"`` or a decimal string. Auto selection returns
+        every stage reporting ``ready`` within the step budget; numeric
+        selection returns one forced stage. Readiness itself is not decided
+        here — ``StageLifecycle.status`` is the single judgment point.
+        """
+        if requested != "auto":
+            return [self._forced_stage(requested)]
+
+        ready = [lc for lc in self.lifecycles if lc.status == "ready"]
+        if not ready:
+            raise StageTargetError(self._no_ready_stage_reason())
+
+        batch: list[int] = []
+        total = 0
+        for lifecycle in ready:
+            if batch and total + lifecycle.step_count > budget:
+                break
+            batch.append(lifecycle.stage)
+            total += lifecycle.step_count
+        return batch
+
+    def _forced_stage(self, requested: str) -> int:
+        try:
+            n = int(requested)
+        except ValueError as exc:
+            raise StageTargetError(
+                f"--stage must be 'auto' or an integer, got {requested!r}"
+            ) from exc
+        by_number = {lc.stage: lc for lc in self.lifecycles}
+        lifecycle = by_number.get(n)
+        if lifecycle is None:
+            raise StageTargetError(
+                f"--stage {n} not in Stage Map (have {list(by_number)})"
+            )
+        if lifecycle.status == "done":
+            raise StageTargetError(
+                f"--stage {n} already completed (consumers.jsonl status:done exists)"
+            )
+        if lifecycle.status == "active":
+            # Wording is load-bearing: okstra-run's unattended chain matches it
+            # to terminate normally instead of raising an exception gate.
+            raise StageTargetError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
+        return n
+
+    def _no_ready_stage_reason(self) -> str:
+        blocked = [lc for lc in self.lifecycles if lc.status == "blocked"]
+        if not blocked:
+            return (
+                "no stage is ready: every stage is done or occupied by "
+                "another run"
+            )
+        detail = "; ".join(
+            f"stage {lc.stage} blocked by "
+            + ", ".join(str(d) for d in lc.blocked_by)
+            for lc in blocked
         )
+        return f"no stage is ready: {detail}"
 
     def resolve_implementation_stage(self, requested: str) -> int:
         return self.resolve_effective_stages(requested)[0]
@@ -131,9 +226,16 @@ def stage_lifecycle_snapshot_from_state(
     for stage in stage_map:
         stage_number = stage["stage_number"]
         done_row = consumer_state.done_by_stage.get(stage_number) or {}
+        depends_on = list(stage.get("depends_on") or [])
+        blocked_by = [
+            d for d in depends_on if d not in consumer_state.done_stages
+        ]
         lifecycles.append(StageLifecycle(
             stage=stage_number,
-            depends_on=list(stage.get("depends_on") or []),
+            depends_on=depends_on,
+            step_count=int(stage.get("step_count") or 0),
+            deps_satisfied=not blocked_by,
+            blocked_by=blocked_by,
             done=stage_number in consumer_state.done_stages,
             started=stage_number in consumer_state.started_stages,
             reserved=stage_number in reserved,
@@ -198,56 +300,22 @@ def resolve_effective_stages(
     started_stages: set[int] | None = None,
     reserved_stages: set[int] | None = None,
 ) -> list[int]:
-    """Return ordered stage numbers this run should execute.
+    """Adapter over ``StageLifecycleSnapshot.resolve_effective_stages``.
 
-    ``requested`` is ``"auto"`` or a decimal string. Auto selection returns all
-    ready stages within the step budget, excluding done/started/reserved stages.
-    Numeric selection returns one forced stage.
+    Entry point for callers holding raw stage-map and consumer sets rather than
+    a snapshot. It only assembles the snapshot; the readiness judgment lives on
+    ``StageLifecycle.status``.
     """
-    started_stages = started_stages or set()
-    reserved_stages = reserved_stages or set()
-    occupied = done_stages | started_stages | reserved_stages
-    if requested != "auto":
-        try:
-            n = int(requested)
-        except ValueError as exc:
-            raise StageTargetError(
-                f"--stage must be 'auto' or an integer, got {requested!r}"
-            ) from exc
-        target = next((s for s in stages if s["stage_number"] == n), None)
-        if target is None:
-            raise StageTargetError(
-                f"--stage {n} not in Stage Map "
-                f"(have {[s['stage_number'] for s in stages]})"
-            )
-        if n in done_stages:
-            raise StageTargetError(
-                f"--stage {n} already completed (consumers.jsonl status:done exists)"
-            )
-        if n in started_stages or n in reserved_stages:
-            raise StageTargetError(
-                f"--stage {n} already in progress or reserved by another run"
-            )
-        return [n]
-
-    ready = [
-        s for s in stages
-        if s["stage_number"] not in occupied
-        and all(d in done_stages for d in s["depends_on"])
+    rows: list[dict[str, Any]] = [
+        {"stage": n, "status": "done"} for n in sorted(done_stages)
     ]
-    if not ready:
-        raise StageTargetError(
-            "no stage is ready: every remaining stage has unsatisfied depends-on"
-        )
-    batch: list[int] = []
-    total = 0
-    for stage in ready:
-        step_count = stage.get("step_count", 0) or 0
-        if batch and total + step_count > budget:
-            break
-        batch.append(stage["stage_number"])
-        total += step_count
-    return batch
+    rows += [
+        {"stage": n, "status": "started"} for n in sorted(started_stages or set())
+    ]
+    snapshot = stage_lifecycle_snapshot_from_rows(
+        stages, rows, reserved_stages=reserved_stages,
+    )
+    return snapshot.resolve_effective_stages(requested, budget=budget)
 
 
 def resolve_implementation_stage(
@@ -430,7 +498,7 @@ def resolve_stage_base_commit(
     )
 
 
-def resolve_whole_task_target(
+def _resolve_whole_task_target(
     *,
     stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]],
@@ -490,65 +558,80 @@ def _merged_stage_map(
     }
 
 
-def resolve_and_integrate_whole_task(
+def _resolve_and_integrate_whole_task_unlocked(
     *, project_id: str, task_group: str, task_id: str,
     task_worktree_path: str, stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
 ) -> dict[str, Any]:
-    """whole-task stage 통합(머지[+선택 teardown]) → 게이트 강제 → target 해소.
-
-    final-verification(teardown=True)과 container(teardown=False)의 단일 참조점.
-    ctx/PrepareInputs 결합 없는 헬퍼. 머지 충돌·미머지·dirty(.okstra 외)면
-    `PrepareError`. 반환: head_commit / merged_stage_map / target_ref / target /
-    integrate_result.
-
-    머지(`git merge`)+teardown 은 task-key 단위 `worktree_provision_mutex` 로
-    감싼다 — 동시 `container up` 둘 또는 container up × whole-task
-    final-verification 이 같은 공유 worktree 의 index/HEAD 에 동시에 머지하면
-    index.lock 충돌·반쯤 적용된 머지로 트리가 깨진다. 두 호출 지점(container 의
-    `_integrate_source_tree`, run.py 의 `_reserve_final_verification_target`)
-    모두 이 락 밖에서 진입하므로 self-deadlock 없이 여기서 1회만 잡는다."""
+    """Integrate and resolve a whole-task target while the caller owns the lock."""
     from .stage_integrate import IntegrateError, integrate_stages
     from .worktree import _git, is_dirty_excluding_okstra
-    from .locks import worktree_provision_mutex
-    from okstra_project.dirs import okstra_home
-    from okstra_project.state import slugify
 
-    with worktree_provision_mutex(
-        okstra_home(), project_id, slugify(task_group), slugify(task_id),
-    ):
-        try:
-            integ = integrate_stages(
-                project_id=project_id, task_group=task_group, task_id=task_id,
-                task_worktree_path=task_worktree_path, stage_map=stage_map,
-                done_rows=done_rows, teardown=teardown,
-            )
-        except IntegrateError as exc:
-            raise PrepareError(str(exc)) from exc
-
-        head = _git(task_worktree_path, "rev-parse", "HEAD").stdout.strip()
-        merged = _merged_stage_map(task_worktree_path, done_rows, head)
-        try:
-            target = resolve_whole_task_target(
-                stage_map=stage_map, done_rows=done_rows, anchor_base=anchor_base,
-                task_worktree_path=task_worktree_path, task_head=head,
-                task_dirty=is_dirty_excluding_okstra(task_worktree_path),
-                merged=merged,
-            )
-        except StageTargetError as exc:
-            raise PrepareError(str(exc)) from exc
+    try:
+        integration = integrate_stages(
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_worktree_path=task_worktree_path,
+            stage_map=stage_map,
+            done_rows=done_rows,
+            teardown=teardown,
+        )
+    except IntegrateError as exc:
+        raise PrepareError(str(exc)) from exc
+
+    head = _git(task_worktree_path, "rev-parse", "HEAD").stdout.strip()
+    merged = _merged_stage_map(task_worktree_path, done_rows, head)
+    try:
+        target = _resolve_whole_task_target(
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            task_worktree_path=task_worktree_path,
+            task_head=head,
+            task_dirty=is_dirty_excluding_okstra(task_worktree_path),
+            merged=merged,
+        )
+    except StageTargetError as exc:
+        raise PrepareError(str(exc)) from exc
     return {
         "head_commit": head,
         "merged_stage_map": merged,
         "target_ref": target.head,
         "target": target,
-        "integrate_result": integ,
+        "integrate_result": integration,
     }
 
 
-def resolve_single_stage_target(
+def resolve_and_integrate_whole_task(
+    *, project_id: str, task_group: str, task_id: str,
+    task_worktree_path: str, stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
+) -> dict[str, Any]:
+    """Locked whole-task integration interface shared with the container."""
+    from okstra_project.dirs import okstra_home
+    from okstra_project.state import slugify
+
+    from .locks import worktree_provision_mutex
+
+    with worktree_provision_mutex(
+        okstra_home(), project_id, slugify(task_group), slugify(task_id),
+    ):
+        return _resolve_and_integrate_whole_task_unlocked(
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_worktree_path=task_worktree_path,
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            teardown=teardown,
+        )
+
+
+def _resolve_single_stage_target(
     *,
-    requested_stage: str,
+    requested_stage: int,
     done_rows: list[dict[str, Any]],
     stage_base: str,
     stage_worktree_path: str,
@@ -558,7 +641,7 @@ def resolve_single_stage_target(
     """Resolve single-stage final-verification target, enforcing all gates."""
     from .consumers import latest_done_by_stage
 
-    n = int(requested_stage)
+    n = requested_stage
     done_by_stage = latest_done_by_stage(done_rows)
     if n not in done_by_stage:
         raise StageTargetError(
@@ -583,3 +666,149 @@ def resolve_single_stage_target(
         stages=[n],
         reports=[done_by_stage[n].get("report_path", "")],
     )
+
+
+def _read_final_verification_done_rows(
+    request: FinalVerificationTargetRequest,
+    registry_coordinates: tuple[str, str, str],
+) -> list[dict[str, Any]]:
+    from .consumers import backfill_done_from_carry, read_stage_consumer_state
+    from .plan_run_root import plan_run_root_from_approved_plan
+    from .stage_reconcile import auto_reconcile_best_effort
+
+    plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
+    backfill_done_from_carry(plan_run_root)
+    project_id, task_group, task_id = registry_coordinates
+    auto_reconcile_best_effort(
+        replace(
+            request,
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+        ),
+        plan_run_root,
+    )
+    return read_stage_consumer_state(plan_run_root).done_rows
+
+
+def _final_verification_registry_coordinates(
+    request: FinalVerificationTargetRequest,
+) -> tuple[str, str, str]:
+    from okstra_project.state import slugify
+
+    def segment(value: str) -> str:
+        return slugify(value) or "_"
+
+    return (
+        segment(request.project_id),
+        segment(request.task_group),
+        segment(request.task_id),
+    )
+
+
+def _acquire_single_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    from . import worktree_registry
+    from .worktree import _git, is_dirty_excluding_okstra
+
+    stage = request.stage
+    assert stage is not None
+    row = worktree_registry.get_stage_row(*registry_coordinates, stage)
+    worktree_path = (row or {}).get("worktree_path", "")
+    head = ""
+    if worktree_path and Path(worktree_path).is_dir():
+        head_result = _git(worktree_path, "rev-parse", "HEAD")
+        if head_result.returncode == 0:
+            head = head_result.stdout.strip()
+    if not head:
+        worktree_path = ""
+    target = _resolve_single_stage_target(
+        requested_stage=stage,
+        done_rows=done_rows,
+        stage_base=(row or {}).get("base_ref", ""),
+        stage_worktree_path=worktree_path,
+        stage_head=head,
+        stage_dirty=(
+            is_dirty_excluding_okstra(worktree_path) if worktree_path else False
+        ),
+    )
+    return FinalVerificationTargetAcquisition(
+        target=target,
+        worktree_branch=(row or {}).get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_whole_task_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    from . import worktree_registry
+
+    project_id, task_group, task_id = registry_coordinates
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    worktree_path = (
+        entry.worktree_path if entry is not None else str(request.project_root)
+    )
+    whole = _resolve_and_integrate_whole_task_unlocked(
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+        task_worktree_path=worktree_path,
+        stage_map=list(request.stage_map),
+        done_rows=done_rows,
+        anchor_base=(
+            worktree_registry.get_implementation_base(
+                project_id, task_group, task_id
+            )
+            or ""
+        ),
+        teardown=True,
+    )
+    return FinalVerificationTargetAcquisition(
+        target=whole["target"],
+        worktree_branch=entry.branch if entry is not None else "",
+        integration_result=whole["integrate_result"],
+    )
+
+
+def acquire_final_verification_target(
+    request: FinalVerificationTargetRequest,
+) -> FinalVerificationTargetAcquisition:
+    """Acquire a stable final-verification target behind one task-key lock."""
+    from okstra_project.dirs import okstra_home
+    from okstra_project.state import slugify
+
+    from .locks import worktree_provision_mutex
+
+    try:
+        with worktree_provision_mutex(
+            okstra_home(),
+            request.project_id,
+            slugify(request.task_group),
+            slugify(request.task_id),
+        ):
+            registry_coordinates = _final_verification_registry_coordinates(request)
+            done_rows = _read_final_verification_done_rows(
+                request,
+                registry_coordinates,
+            )
+            if request.stage is not None:
+                return _acquire_single_stage_target(
+                    request,
+                    done_rows,
+                    registry_coordinates,
+                )
+            return _acquire_whole_task_target(
+                request,
+                done_rows,
+                registry_coordinates,
+            )
+    except PrepareError:
+        raise
+    except (OSError, RuntimeError, StageTargetError, ValueError) as exc:
+        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/time_report.py

@@ -14,12 +14,13 @@ import json
 import sys
 from pathlib import Path
 
-from okstra_ctl.paths import resolve_under_root
+from okstra_ctl.paths import resolve_under_root, task_timeline_file
+from okstra_project import read_task_key
 from okstra_ctl.task_target import resolve_task_root
 
 
 def load_runs(task_root: Path) -> tuple[list[dict], bool]:
-    path = task_root / "history" / "timeline.json"
+    path = task_timeline_file(task_root)
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError):
@@ -30,12 +31,6 @@ def load_runs(task_root: Path) -> tuple[list[dict], bool]:
     return runs, False
 
 
-def _task_key(task_root: Path) -> str:
-    try:
-        return json.loads((task_root / "task-manifest.json").read_text(encoding="utf-8")).get("taskKey", "")
-    except (OSError, ValueError):
-        return ""
-
 
 def _duration_ms(block) -> int:
     """usage / leadUsage block 의 durationMs — na_block·missing·None 은 0."""
@@ -194,7 +189,7 @@ def main(argv: list[str] | None = None) -> int:
 
     task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
     runs, _ = load_runs(task_root)
-    result = {"ok": True, "taskKey": _task_key(task_root)}
+    result = {"ok": True, "taskKey": read_task_key(task_root)}
     result.update(aggregate_time(runs, project_root))
     print(json.dumps(result, ensure_ascii=False, indent=2))
     return 0