okstra 0.134.0 → 0.136.0

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -457,7 +457,12 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
             else:
                 seen_workers.add(worker_id)
             if not _nonempty_string(audience) or audience not in _AUDIENCES:
-                errors.append(f"workers[{index}].audience is unsupported")
+                errors.append(
+                    f"workers[{index}].audience is unsupported: {audience!r}. "
+                    "Finding-producing workers (implementation verifiers included) "
+                    "use 'analysis'; only the report author uses 'report-writer'. "
+                    f"Allowed: {sorted(_AUDIENCES)}."
+                )
     findings = state.get("findings")
     if not isinstance(findings, list):
         errors.append("findings must be an array")
@@ -1821,7 +1826,11 @@ def _parse_workers(value: Any) -> list[dict[str, str]]:
         audience = _required_string(worker, "audience", f"workers[{index}]")
         if audience not in _AUDIENCES:
             raise ConvergenceContractError(
-                f"workers[{index}] has unsupported audience: {audience}"
+                f"workers[{index}] has unsupported audience: {audience}. "
+                "Convergence audience is a functional role, not a phase label: "
+                "every finding-producing worker uses 'analysis' (an "
+                "implementation run's verifiers included), and only the report "
+                f"author uses 'report-writer'. Allowed: {sorted(_AUDIENCES)}."
             )
         if worker_id in seen:
             raise ConvergenceContractError(f"duplicate workerId: {worker_id}")

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/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:

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Any
 
 from .consumers import read_stage_consumer_state
+from .paths import RunRef
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -27,7 +28,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     if workflow.get("currentPhase") != "implementation":
         return ImplementationOutcome(completed=False, reason="current phase is not implementation")
 
-    plan_run_root = task_root / "runs" / "implementation-planning"
+    plan_run_root = RunRef.from_task_root(task_root, "implementation-planning").run_dir
     if not plan_run_root.is_dir():
         return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
 
@@ -133,7 +134,7 @@ def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str,
 
 
 def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
-    carry_dir = task_root / "runs" / "implementation" / "carry"
+    carry_dir = RunRef.from_task_root(task_root, "implementation").carry_dir
     for carry_path in sorted(carry_dir.glob("stage-*.json")):
         value = _load_json(carry_path).get("sourcePlanPath")
         if isinstance(value, str) and value:
@@ -143,7 +144,7 @@ def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
     if isinstance(latest, str) and "implementation-planning" in latest:
         return _resolve_relative(task_root, latest)
 
-    reports = task_root / "runs" / "implementation-planning" / "reports"
+    reports = RunRef.from_task_root(task_root, "implementation-planning").reports_dir
     candidates = sorted(reports.glob("final-report-implementation-planning-*.md"))
     return candidates[-1] if candidates else Path()
 
@@ -170,7 +171,7 @@ def _project_root_from_task_root(task_root: Path) -> Path:
 
 
 def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
-    data = _load_json(task_root / "runs" / "implementation" / "carry" / f"stage-{stage}.json")
+    data = _load_json(RunRef.from_task_root(task_root, "implementation").carry(stage))
     return data or None
 
 
@@ -205,7 +206,7 @@ def _carry_head_commit(carry: dict[str, Any]) -> str:
 
 def _latest_implementation_report(task_root: Path) -> str:
     reports = sorted(
-        (task_root / "runs" / "implementation").glob(
+        RunRef.from_task_root(task_root, "implementation").run_dir.glob(
             "stage-*/reports/final-report-implementation-*.md"
         )
     )

package/runtime/python/okstra_ctl/models.py

@@ -22,6 +22,8 @@ CLAUDE = {
     "fable-5": ModelSpec("fable-5", "claude-fable-5"),
     "claude-fable-5": ModelSpec("fable-5", "claude-fable-5"),
     "opus": ModelSpec("opus", "opus", in_picker=True),
+    "opus-5": ModelSpec("opus-5", "claude-opus-5"),
+    "claude-opus-5": ModelSpec("opus-5", "claude-opus-5"),
     "opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
     "claude-opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
     "opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),

package/runtime/python/okstra_ctl/path_hints.py

@@ -12,6 +12,8 @@ from okstra_project.dirs import (
     okstra_home,
 )
 
+from .paths import runs_dir_of
+
 RUN_CONTEXT_KIND = "run-context"
 RUN_CONTEXT_SCHEMA_VERSION = "2.0"
 ACTIVE_CONTEXT_KIND = "active-run-context"
@@ -359,7 +361,7 @@ def _task_path_set(task_root: Path) -> dict[str, Path]:
         "instruction_set": instruction_set,
         "analysis_packet": instruction_set / "analysis-packet.md",
         "task_qa": task_root / "qa",
-        "runs_dir": task_root / "runs",
+        "runs_dir": runs_dir_of(task_root),
         "history_dir": history_dir,
         "timeline_file": history_dir / "timeline.json",
         "recap_dir": recap_dir,

package/runtime/python/okstra_ctl/paths.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import os
 import re
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Optional
 
@@ -30,6 +31,8 @@ __all__ = [
     "OKSTRA_RELATIVE",
     "TASKS_RELATIVE",
     "DISCOVERY_RELATIVE",
+    "RunRef",
+    "runs_dir_of",
     "compute_run_paths",
     "next_run_seq",
     "resolve_under_root",
@@ -40,6 +43,254 @@ __all__ = [
 ]
 
 
+_STAGED_TASK_TYPES = ("implementation", "final-verification")
+# 발견용: bash `find -name 'final-report-*.md'` 와 같은 범위 — seq 이전 세대의
+# 타임스탬프 파일명도 잡아야 옛 번들에서 조용히 실패하지 않는다.
+_REPORT_NAME_RE = re.compile(r"^final-report-.+\.md$")
+# seq 추출용: 정본 이름 `final-report-<task-type>-<NNN>.md` 일 때만.
+_REPORT_SEQ_RE = re.compile(r"^final-report-.+-(?P<seq>\d{3,})\.md$")
+_TASKS_SEGMENTS = Path(TASKS_RELATIVE).parts
+
+
+def _newest_report(reports_dir: Path) -> Optional[Path]:
+    """reports 디렉터리에서 mtime 최신 final-report. 동률이면 basename 큰 쪽."""
+    if not reports_dir.is_dir():
+        return None
+    found = [
+        entry for entry in reports_dir.iterdir()
+        if entry.is_file() and _REPORT_NAME_RE.match(entry.name)
+    ]
+    if not found:
+        return None
+    return max(found, key=lambda p: (p.stat().st_mtime, p.name))
+
+
+def _project_root_of(task_root: Path) -> Optional[Path]:
+    """canonical `<project>/.okstra/tasks/<g>/<t>` 일 때만 project root.
+
+    검증기는 이 형태가 아닌 트리(테스트 픽스처, 이식된 번들)에도 돌아간다.
+    그때는 project root 를 알 수 없으므로 지어내지 않고 None 을 돌려준다 —
+    경로 유래 ref 는 task_root 를 고정하므로 계산에 필요하지도 않다.
+    """
+    parts = task_root.parts
+    if len(parts) > len(_TASKS_SEGMENTS) + 2 and parts[-4:-2] == _TASKS_SEGMENTS:
+        return Path(*parts[:-4])
+    return None
+
+
+@dataclass(frozen=True)
+class RunRef:
+    """하나의 run 을 identity 로 지명하는 read-side 참조.
+
+    산출물 경로를 종류별로 계산해 돌려주되 내용은 읽지 않는다 — 파싱은
+    consumers / stage_targets / run_context 같은 기존 로더가 계속 소유한다.
+
+    stage 세그먼트는 아티팩트 종류마다 다르게 적용된다. run 디렉터리는
+    stage-isolated 이지만 carry 사이드카는 flat 이므로(stage N+1 이 N 의 사이드카를
+    N 의 run 레이아웃을 모른 채 찾아야 한다), 그 예외는 `carry()` 안에만 산다.
+    호출자가 `run_dir` 에서 손으로 올라가면 안 된다.
+
+    `compute_run_paths()` 가 같은 레이아웃을 write-side 에서 계산한다. 둘의 합의는
+    tests/contract/test_task_path_ssot.py 가 잠근다.
+    """
+
+    project_root: Optional[Path]
+    task_group: str
+    task_id: str
+    task_type: str
+    seq: Optional[int] = None
+    stage: Optional[int] = None
+    # 경로에서 만든 ref 는 받은 task_root 를 고정한다. identity 로 재계산하면
+    # canonical 하지 않은 트리에서 조용히 다른 곳을 가리킨다.
+    task_root_override: Optional[Path] = None
+    # 경로에서 만든 ref 는 찾은 파일을 그대로 고정한다 — 레거시 타임스탬프
+    # 이름은 identity 로 재구성할 수 없다.
+    report_override: Optional[Path] = None
+
+    @property
+    def task_root(self) -> Path:
+        if self.task_root_override is not None:
+            return self.task_root_override
+        if self.project_root is None:
+            raise ValueError("RunRef has neither a project_root nor a task_root")
+        return task_dir(self.project_root, self.task_group, self.task_id)
+
+    @property
+    def runs_dir(self) -> Path:
+        return runs_dir_of(self.task_root)
+
+    @property
+    def run_dir(self) -> Path:
+        segment = slugify(self.task_type)
+        run_dir = self.runs_dir / segment
+        if segment in _STAGED_TASK_TYPES and self.stage is not None:
+            return run_dir / f"stage-{int(self.stage)}"
+        return run_dir
+
+    @property
+    def reports_dir(self) -> Path:
+        return self.run_dir / "reports"
+
+    @property
+    def carry_dir(self) -> Path:
+        """implementation 의 carry 는 stage-SHARED 라 flat 이다(§carry 참고)."""
+        segment = slugify(self.task_type)
+        if segment == "implementation":
+            return self.runs_dir / segment / "carry"
+        return self.run_dir / "carry"
+
+    @property
+    def report(self) -> Path:
+        if self.report_override is not None:
+            return self.report_override
+        return self.reports_dir / f"final-report{self._suffix}.md"
+
+    @property
+    def manifest(self) -> Path:
+        return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
+
+    def carry(self, stage: int) -> Path:
+        """stage 의 carry 사이드카. implementation 은 stage-SHARED(flat)다."""
+        return self.carry_dir / f"stage-{int(stage)}.json"
+
+    @property
+    def _suffix(self) -> str:
+        if self.seq is None:
+            raise ValueError(
+                "RunRef.seq is unset — a seq-less ref can name the run directory "
+                "but not an artifact file. Use RunRef.latest() or pass seq."
+            )
+        return f"-{slugify(self.task_type)}-{int(self.seq):03d}"
+
+    @classmethod
+    def from_task_root(
+        cls,
+        task_root: Path,
+        task_type: str,
+        *,
+        seq: Optional[int] = None,
+        stage: Optional[int] = None,
+    ) -> "RunRef":
+        """task_root 경로만 쥔 호출자를 위한 어댑터.
+
+        받은 task_root 를 고정하므로 canonical 하지 않은 트리에서도 왕복한다.
+        복원되는 group/id 는 slug 세그먼트다.
+        """
+        task_root = Path(task_root)
+        return cls(
+            project_root=_project_root_of(task_root),
+            task_group=task_root.parent.name,
+            task_id=task_root.name,
+            task_type=task_type,
+            seq=seq,
+            stage=stage,
+            task_root_override=task_root,
+        )
+
+    @classmethod
+    def from_run_dir(cls, run_dir: Path, *, seq: Optional[int] = None) -> "RunRef":
+        """run 디렉터리에서 정체를 복원한다.
+
+        `<task_root>/runs/<task-type>[/stage-<N>]` 를 해석한다. `runs` 앵커가
+        없으면 ValueError — 관대한 폴백이 필요한 호출자는 직접 감싸라.
+        """
+        run_dir = Path(run_dir)
+        stage = None
+        if run_dir.name.startswith("stage-"):
+            stage = int(run_dir.name[len("stage-"):])
+            run_dir = run_dir.parent
+        if run_dir.parent.name != "runs":
+            raise ValueError(f"not an okstra run directory: {run_dir}")
+
+        return cls.from_task_root(
+            run_dir.parent.parent, run_dir.name, seq=seq, stage=stage
+        )
+
+    @classmethod
+    def from_report_path(cls, report_path: Path) -> "RunRef":
+        """final-report 경로에서 정체를 복원한다.
+
+        복원되는 task-group/task-id 는 slug 세그먼트다. slugify 가 멱등이라
+        경로 왕복에는 영향이 없지만, 원래 표기가 필요하면 task-manifest 를 읽어라.
+        """
+        report_path = Path(report_path)
+        if not _REPORT_NAME_RE.match(report_path.name):
+            raise ValueError(f"not a final-report path: {report_path}")
+        matched = _REPORT_SEQ_RE.match(report_path.name)
+        ref = cls.from_run_dir(
+            report_path.parent.parent,
+            seq=int(matched.group("seq")) if matched else None,
+        )
+        return replace(ref, report_override=report_path)
+
+    def sibling(self, task_type: str) -> "RunRef":
+        """같은 task 의 다른 task-type 을 가리키는 ref.
+
+        seq/stage 는 이 run 의 것이므로 형제에게 물려주지 않는다.
+        """
+        return replace(
+            self, task_type=task_type, seq=None, stage=None, report_override=None
+        )
+
+    @classmethod
+    def latest(
+        cls, project_root: Path, task_group: str, task_id: str, task_type: str
+    ) -> Optional["RunRef"]:
+        """task-type 의 최신 final-report 를 가리키는 ref. 없으면 None.
+
+        최신 기준은 mtime 이고, 동률이면 basename 이 큰 쪽이다 — bash
+        `find_latest_final_report` 와 wizard 가 쓰던 규칙을 그대로 옮긴 것이다.
+        stage 하위 디렉터리는 훑지 않는다(옮겨온 두 구현과 동일 범위).
+        """
+        ref = cls(
+            project_root=Path(project_root), task_group=task_group,
+            task_id=task_id, task_type=task_type,
+        )
+        best = _newest_report(ref.reports_dir)
+        return None if best is None else cls.from_report_path(best)
+
+    @classmethod
+    def latest_across(
+        cls,
+        project_root: Path,
+        task_group: str,
+        task_id: str,
+        task_types: Optional[tuple[str, ...]] = None,
+    ) -> Optional["RunRef"]:
+        """여러 task-type 을 가로질러 최신 final-report 를 가리키는 ref.
+
+        `task_types` 를 주지 않으면 runs/ 에 실제로 존재하는 모든 task-type 을
+        훑는다. 비교 규칙은 `latest` 와 같다(mtime, 동률이면 basename).
+        """
+        return cls.latest_under(
+            task_dir(project_root, task_group, task_id), task_types
+        )
+
+    @classmethod
+    def latest_under(
+        cls, task_root: Path, task_types: Optional[tuple[str, ...]] = None
+    ) -> Optional["RunRef"]:
+        """`latest_across` 의 task_root 진입점.
+
+        task-key 단축키/오타 진단을 이미 거쳐 task_root 를 손에 쥔 호출자
+        (bash resume-clarification)가 쓴다.
+        """
+        runs_dir = runs_dir_of(task_root)
+        if task_types is None:
+            if not runs_dir.is_dir():
+                return None
+            task_types = tuple(sorted(p.name for p in runs_dir.iterdir() if p.is_dir()))
+        candidates = [
+            found for task_type in task_types
+            if (found := _newest_report(runs_dir / task_type / "reports")) is not None
+        ]
+        if not candidates:
+            return None
+        return cls.from_report_path(
+            max(candidates, key=lambda p: (p.stat().st_mtime, p.name))
+        )
+
+
 def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
 
@@ -51,7 +302,15 @@ def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
 
 def task_runs_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task 의 runs 디렉터리: ``task_dir/runs``."""
-    return task_dir(project_root, task_group, task_id) / "runs"
+    return runs_dir_of(task_dir(project_root, task_group, task_id))
+
+
+def runs_dir_of(task_root: Path) -> Path:
+    """task_root 만 쥔 호출자를 위한 runs 디렉터리 접근자.
+
+    task-type 을 모르는 스캐너(backfill·error-log glob·context-cost)가 쓴다.
+    `runs` 세그먼트 리터럴은 이 함수와 `compute_run_paths` 에만 존재한다."""
+    return Path(task_root) / "runs"
 
 
 def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
@@ -161,7 +420,7 @@ def compute_run_paths(
     instruction_set = task_root / "instruction-set"
     analysis_packet = instruction_set / "analysis-packet.md"
     task_qa = task_root / "qa"
-    runs_dir = task_root / "runs"
+    runs_dir = runs_dir_of(task_root)
     history_dir = task_root / "history"
     timeline_file = history_dir / "timeline.json"
     recap_dir = task_root / "recap"

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -48,10 +48,10 @@ def resolve_plan_run_root_by_task_key(
     from . import paths
     from .consumers import read_consumers
 
-    reports_dir = (
-        paths.task_dir(project_root, task_group, task_id)
-        / "runs" / "implementation-planning" / "reports"
-    )
+    reports_dir = paths.RunRef(
+        project_root=project_root, task_group=task_group, task_id=task_id,
+        task_type="implementation-planning",
+    ).reports_dir
     if not reports_dir.is_dir():
         raise PrepareError(
             "container up: implementation-planning run 을 찾을 수 없습니다 "

package/runtime/python/okstra_ctl/render_final_report.py

@@ -492,7 +492,7 @@ def _enforce_schema(data: dict) -> None:
 # 있으나 표시이므로 실행에는 무해하다. 새 버전이 나오면 여기만 갱신한다.
 _DISPLAY_CONCRETE_CLAUDE = {
     "fable": "claude-fable-5",
-    "opus": "claude-opus-4-8",
+    "opus": "claude-opus-5",
     "sonnet": "claude-sonnet-4-6",
     "haiku": "claude-haiku-4-5",
 }

package/runtime/python/okstra_ctl/run.py

@@ -891,6 +891,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
 
 
 _INCLUDE_DIRECTIVE = re.compile(r"\{\{INCLUDE:([^}]+?)\}\}")
+_HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
 
 
 def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
@@ -901,6 +902,12 @@ def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
     contents replace the directive line in-place. Missing include targets
     raise PrepareError so a bad reference fails fast instead of silently
     leaving a `{{INCLUDE:...}}` token in the rendered profile.
+
+    The top-level result is stripped of HTML comments: the shared fragments
+    carry maintainer-only `<!-- ... -->` notes (edit-here-once guidance, dedup
+    rationale) that would otherwise ride into the rendered profile the lead
+    reads every run without changing a single instruction. Nested-include
+    bodies are left intact and get stripped once by this depth-0 pass.
     """
     if _depth > 4:
         raise PrepareError(
@@ -917,7 +924,11 @@ def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
             )
         return _expand_profile_includes(target, _depth + 1).rstrip("\n")
 
-    return _INCLUDE_DIRECTIVE.sub(_sub, text)
+    expanded = _INCLUDE_DIRECTIVE.sub(_sub, text)
+    if _depth == 0:
+        expanded = _HTML_COMMENT.sub("", expanded)
+        expanded = re.sub(r"\n{3,}", "\n\n", expanded)
+    return expanded
 
 
 # ---------------------------------------------------------------------------

package/runtime/python/okstra_ctl/wizard.py

@@ -84,7 +84,7 @@ from okstra_ctl.worktree import (
     preview_stage_worktree_decision,
     preview_worktree_decision,
 )
-from okstra_ctl.paths import task_dir, task_runs_dir
+from okstra_ctl.paths import RunRef, task_dir, task_runs_dir
 from okstra_ctl.work_categories import resolve_work_category
 from okstra_ctl.run_context import latest_run_inputs
 from okstra_project.dirs import project_json_path
@@ -1794,8 +1794,10 @@ def _list_implementation_planning_reports(
     # Run seq lives in the filename, not a per-run subdirectory: every
     # implementation-planning run writes into the same flat `reports/`
     # dir (see paths.py — `run_reports = runs/<task-type>/reports`).
-    reports_dir = (task_runs_dir(state.project_root, state.task_group, state.task_id)
-                   / "implementation-planning" / "reports")
+    reports_dir = RunRef(
+        project_root=state.project_root, task_group=state.task_group,
+        task_id=state.task_id, task_type="implementation-planning",
+    ).reports_dir
     if not reports_dir.is_dir():
         return []
     pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")

package/runtime/python/okstra_ctl/worker_artifact_paths.py

@@ -17,7 +17,11 @@ def audit_sidecar_rel(worker_result_rel: str) -> str:
     prefix, separator, suffix = basename.partition("-worker-")
     if not separator:
         raise WorkerArtifactPathError(
-            f"worker result path has no canonical -worker- token: {worker_result_rel}"
+            "worker result path has no canonical -worker- token: "
+            f"{worker_result_rel}. The audit sidecar is derived from the "
+            "canonical worker-result name `<role>-worker-<task-type>-<seq>.md` "
+            "(e.g. `codex-worker-implementation-001.md`); name the result that "
+            "way — a role label like `codex-verifier-...` drops the -worker- token."
         )
     audit_filename = f"{prefix}-worker-audit-{suffix}"
     return f"{directory}{slash}{audit_filename}" if slash else audit_filename

package/runtime/python/okstra_token_usage/collect.py

@@ -227,7 +227,9 @@ def _previous_run_end(run_dir: Path, suffix: str) -> str | None:
     return _run_end_estimate(run_dir, prev) or _run_manifest_created_at(run_dir, prev)
 
 
-def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
+def resolve_run_window(
+    team_state_path: Path, state: dict, *, relax_start: bool = True
+) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
     in-session lead 는 자기 run 을 사용자의 *세션 전체* jsonl 에 기록하므로,
@@ -238,26 +240,34 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
     (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백.
 
-    시작 완화: run-manifest createdAt 이 이 run 의 실제 lead/worker 세션보다
-    늦게 찍히면(관측: dev-9902 — createdAt 11:43Z 가 05:34Z 시작 세션보다 늦음)
-    since 가 앞선 세션을 잘라낸다. Task 3 이 기록한 `leadSessionIds[]` 세션의
-    첫 ts 최소값이 createdAt 보다 앞서면 그 값으로 since 를 앞당긴다.
-    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변.
-
-    완화 하한: 직전 run 의 종료 시각 이전으로는 내려가지 않는다
+    시작 완화(`relax_start`, 기본 True — 토큰 수집용): run-manifest createdAt 이
+    이 run 의 실제 lead/worker 세션보다 늦게 찍히면(관측: dev-9902 — createdAt
+    11:43Z 가 05:34Z 시작 세션보다 늦음) since 가 앞선 세션을 잘라낸다. Task 3 이
+    기록한 `leadSessionIds[]` 세션의 첫 ts 최소값이 createdAt 보다 앞서면 그 값으로
+    since 를 앞당긴다. `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존
+    동작 불변. 완화 하한: 직전 run 의 종료 시각 이전으로는 내려가지 않는다
     (`_previous_run_end`). 세션 jsonl 은 run 마다 새로 생기지 않으므로 하한이
-    없으면 같은 세션의 이전 run 이 이 윈도우에 통째로 들어온다."""
+    없으면 같은 세션의 이전 run 이 이 윈도우에 통째로 들어온다.
+
+    `relax_start=False` (세션 스코프 검증기 전용 — session-conformance /
+    forbidden-actions): 완화를 건너뛰고 since 를 createdAt 에 고정한다. createdAt
+    은 prep 시각이라 이 run 의 lead·worker 활동보다 반드시 앞서므로 건전한 하한이고,
+    재사용 세션에 섞인 같은 세션의 이전 run·다른 task 활동을 창에서 배제한다
+    (dev-10172 D-3: 이전 planning run 의 phase-6/7 앵커, 다른 task 의 git push 를
+    이 run 의 위반으로 오탐하던 근본 원인). 완화는 토큰을 놓치지 않으려고 세션
+    birth 까지 내려가지만, 검증기에는 그 관대함이 곧 오탐이다."""
     suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
     since = _run_manifest_created_at(run_dir, suffix)
-    earliest = _earliest_lead_session_ts(state, team_state_path)
-    if earliest and (since is None or earliest < since):
-        since = earliest
-    floor = _previous_run_end(run_dir, suffix)
-    if floor and since and since < floor:
-        since = floor
+    if relax_start:
+        earliest = _earliest_lead_session_ts(state, team_state_path)
+        if earliest and (since is None or earliest < since):
+            since = earliest
+        floor = _previous_run_end(run_dir, suffix)
+        if floor and since and since < floor:
+            since = floor
     until = state.get("runEndedAt") or _run_end_estimate(run_dir, suffix) or utc_now()
     return since, until
 

package/runtime/python/okstra_token_usage/pricing.py

@@ -4,7 +4,7 @@ Pricing is matched by substring against the model id recorded in the session
 transcript, so keys must reflect the *actual* model id form emitted by each
 provider:
 
-  * Anthropic — `claude-fable-5*`, `claude-opus-4-*`, `claude-sonnet-4-*`,
+  * Anthropic — `claude-fable-5*`, `claude-opus-5*`, `claude-opus-4-*`, `claude-sonnet-4-*`,
     `claude-haiku-4-5-*`, `claude-3-5-sonnet-*`, `claude-3-5-haiku-*`,
     `claude-3-opus-*`, `claude-3-haiku-*`.
   * OpenAI / Codex — `gpt-5*`, `gpt-4o*`, `gpt-4*`.
@@ -52,6 +52,9 @@ CLAUDE_PRICING = {
     # Claude Fable 5 (tier above Opus).
     "fable-5":    (10.0, 12.5, 1.0, 50.0),     # Fable 5 (cache prices derived from ratios)
 
+    # Claude Opus 5.
+    "opus-5":     (5.0, 6.25, 0.50, 25.0),     # Opus 5 (cache prices derived from ratios)
+
     # Claude 4 point releases (explicit so future divergence is easy to see).
     "opus-4-8":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.8 (cache prices derived from ratios)
     "opus-4-7":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.7 (cache prices derived from ratios)

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -96,6 +96,30 @@ diff and commits: describe only what actually changed. Mark checklist boxes
 docs box). If `commits`/`diffStat` are empty, tell the user there is nothing to
 describe and stop. **Never** append AI trailers/footers.
 
+### A3b. Identifier allowlist for the body
+
+Reviewers have never seen okstra, so an okstra-internal id reads as a nonsense
+token. Identifiers in the PR title and body come from this list and nothing else:
+
+| allowed | example |
+| --- | --- |
+| repo-relative source path, optionally with a line | `src/commands/pr/pr.mjs:42` |
+| symbol name that exists in the diff | `resolveTemplate()` |
+| branch name, commit subject, commit SHA | `feature/dev-9436`, `a1b2c3d` |
+| issue-tracker ticket id the reviewer can open | `dev-9436` |
+
+okstra's own artifact identifiers are out of the allowlist — drop them:
+
+- report item ids — `F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`
+- run artifact names and their `<task-type>-<seq>` suffixes —
+  `final-report-implementation-3.md`, `run-manifest-implementation-3.json`
+- phase / stage / worker labels — `final-verification`, `stage-2`, `codex-worker`
+- any path under `.okstra/` — reports, decisions, glossary, user-response sidecars
+
+When the only source for a claim is such an artifact, restate its substance in
+the reviewer's terms — what changed in the code, and why — instead of citing the
+id.
+
 ### A4. Output and offer to create the PR
 
 Print the filled PR body to chat as a single fenced markdown block. Then ask the