okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_project/state.py

@@ -1,6 +1,6 @@
 """Read-side state accessors over okstra's on-disk authority files.
 
-Skills, okstra.sh, and okstra-ctl all read the same files through this module
+Skills and okstra.sh read the same files through this module
 so identity / discovery values are derived from disk on every call instead of
 being passed via process environment. This keeps concurrent claude-code skill
 invocations isolated — each call reads the authoritative state at the moment
@@ -34,6 +34,13 @@ from .dirs import (
     TASK_MANIFEST_FILENAME,
     TASKS_RELATIVE,
 )
+# 포인터 승격은 순수 값 연산이라 하위 계층이 소유한다. 예전에는 함수 본문에서
+# okstra_ctl.next_phase 를 지연 import 했다 — okstra_ctl 패키지 __init__ 이
+# 이 모듈의 slugify 를 도로 끌어와 순환이 됐기 때문이다.
+from .phase_pointer import promote as promote_phase_pointer
+# slug 규칙은 leaf 가 소유한다 — okstra_ctl 이 이 모듈을 거치지 않고 규칙만
+# 가져갈 수 있어야 패키지 __init__ 을 통한 순환이 생기지 않는다.
+from .slug import slugify  # noqa: F401 — 재노출: 기존 호출부가 state 에서 끌어온다
 
 
 class StateError(Exception):
@@ -53,31 +60,6 @@ def _load_json(path: Path) -> Optional[dict]:
         raise StateError(f"failed to parse {path}: {exc}") from exc
 
 
-def _next_phase():
-    """`okstra_ctl.next_phase` 를 호출 시점에 가져온다.
-
-    모듈 최상단에서 import 하면 순환이 된다 — `okstra_ctl/__init__.py` 가
-    `.ids` 를 거쳐 이 모듈의 `slugify` 를 도로 import 하기 때문에, 여기서
-    okstra_ctl 을 먼저 끌어오면 아직 정의되지 않은 이름을 찾다가 ImportError 로
-    죽는다. 같은 파일의 `_reconcile_task_root_best_effort` 도 같은 이유로 지연
-    import 를 쓴다.
-    """
-    from okstra_ctl import next_phase
-
-    return next_phase
-
-
-def slugify(value: str) -> str:
-    """task-group / task-id segment 를 디스크 경로용 slug 로 정규화한다.
-
-    소문자화 + 알파넘 외 문자 → '-' 로 collapse.
-    okstra.sh 의 path-resolve.sh slug 규칙과 일치해야 한다.
-    """
-    value = (value or "").lower()
-    value = re.sub(r"[^a-z0-9]+", "-", value).strip("-")
-    return value
-
-
 def read_task_catalog(project_root: Path) -> list[dict]:
     """project-level task-catalog.json 을 list[dict] 로 돌려준다.
 
@@ -117,7 +99,7 @@ def read_task_manifest(task_root: Path) -> Optional[dict]:
     workflow = manifest.get("workflow")
     if not isinstance(workflow, dict):
         return manifest
-    workflow["nextRecommendedPhase"] = _next_phase().promote(
+    workflow["nextRecommendedPhase"] = promote_phase_pointer(
         workflow.get("nextRecommendedPhase")
     )
     # routingStatus 는 포인터 status 로 흡수됐다 — 승격과 같은 자리에서 지운다.
@@ -143,11 +125,20 @@ def read_task_key(task_root: Path) -> str:
 
 
 def _reconcile_task_root_best_effort(project_root: Path, task_root: Path) -> None:
+    """카탈로그가 가리키는 task-root 를 정본 산출물로 치유한다(best-effort).
+
+    import 를 함수 본문에 두는 이유는 순환이 아니다 — 순환은 없다. 하위 계층인
+    okstra_project 가 상위 계층 okstra_ctl 을 import 시점에 끌어오지 않게 하려는
+    것이다. 이 치유는 읽기측 해석의 부가 동작이므로, 실패해도 해석 자체는
+    계속돼야 한다.
+    """
     try:
         from okstra_ctl.implementation_outcome import reconcile_implementation_outcome
 
         reconcile_implementation_outcome(project_root, task_root)
     except Exception:
+        # expected-miss: 치유는 부가 동작이다. 여기서 던지면 단순 조회가
+        # 실패한다. 무엇이 치유되지 않았는지는 다음 run 의 정합성 검사가 잡는다.
         return
 
 
@@ -195,7 +186,7 @@ def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
     raw = workflow.get("nextRecommendedPhase")
     if raw is None:
         raw = entry.get("nextRecommendedPhase")
-    out["nextRecommendedPhase"] = _next_phase().promote(raw)
+    out["nextRecommendedPhase"] = promote_phase_pointer(raw)
     out.update(derived_task_status(manifest))
     return out
 
@@ -350,7 +341,7 @@ def list_project_tasks(
 def resolve_task_identity(project_root: Path, task_key: str) -> dict:
     """task-key 한 줄로 manifest + 경로를 한 번에 반환.
 
-    skill / okstra.sh / okstra-ctl 모두가 이 함수를 호출해 같은 dict 를 받는다.
+    skill 과 okstra.sh 모두가 이 함수를 호출해 같은 dict 를 받는다.
     StateError: task root 또는 manifest 없음.
     """
     task_root = find_task_root(project_root, task_key)
@@ -379,7 +370,7 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
         "taskType": manifest.get("taskType") or "",
         "currentPhase": workflow.get("currentPhase") or "",
         "currentPhaseState": workflow.get("currentPhaseState") or "",
-        "nextRecommendedPhase": _next_phase().promote(
+        "nextRecommendedPhase": promote_phase_pointer(
             workflow.get("nextRecommendedPhase")
         ),
         "lastCompletedPhase": workflow.get("lastCompletedPhase") or "",
@@ -410,7 +401,7 @@ def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
             "currentPhase": workflow.get("currentPhase"),
             "currentPhaseState": workflow.get("currentPhaseState"),
             "lastCompletedPhase": workflow.get("lastCompletedPhase"),
-            "nextRecommendedPhase": _next_phase().promote(
+            "nextRecommendedPhase": promote_phase_pointer(
                 workflow.get("nextRecommendedPhase")
             ),
             "phaseStates": workflow.get("phaseStates"),
@@ -421,202 +412,3 @@ def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
         "modelAssignments": manifest.get("modelAssignments"),
         "latestRunPath": manifest.get("latestRunPath"),
     }
-
-
-def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
-    """stage-map inspect 용 read-side view: Stage Map + done 처리된 stage 번호.
-
-    Stage Map 파싱과 planning run-root 위치를 caller 에게 노출하지 않는다 —
-    Node inspect 가 okstra_ctl 의 private 심볼을 import 하거나 `runs/` 경로를
-    직접 조립하지 않도록 하는 어댑터다.
-    """
-    from okstra_ctl.consumers import read_stage_consumer_state
-    from okstra_ctl.paths import RunRef
-    from okstra_ctl.stage_map import (
-        PlanningDetail,
-        StageMapError,
-        load_planning_detail,
-        load_task_stage_map,
-        merge_planning_detail,
-    )
-
-    identity = resolve_task_identity(project_root, task_key)
-    task_root = Path(identity["taskRoot"])
-    try:
-        stage_snapshot = load_task_stage_map(task_root, identity["manifest"])
-        detail = (
-            load_planning_detail(Path(stage_snapshot.source_plan_path))
-            if stage_snapshot.source_plan_path
-            else PlanningDetail({}, {})
-        )
-    except StageMapError as exc:
-        raise StateError(str(exc), stage=exc.code) from exc
-    plan_run_root = RunRef.from_task_root(
-        task_root, "implementation-planning"
-    ).run_dir
-    done: list[int] = []
-    if plan_run_root.is_dir():
-        done = sorted(
-            read_stage_consumer_state(
-                plan_run_root, recover_from_carry=True
-            ).done_stages
-        )
-    return {
-        "taskKey": identity["taskKey"],
-        "taskRoot": identity["taskRoot"],
-        "state": stage_snapshot.state,
-        "sourcePlanPath": stage_snapshot.source_plan_path,
-        "stages": merge_planning_detail(stage_snapshot.stages, detail),
-        "doneStages": done,
-        "planning": detail.task_narratives,
-    }
-
-
-def code_review_target_snapshot(
-    project_root: Path, task_key: str, stage: int
-) -> dict:
-    """stage 코드 리뷰가 무엇을 읽고 결과를 어디에 쓰는지 해소한다.
-
-    stage_map_read_side_snapshot 과 같은 결: caller 는 registry 행도, run-root
-    레이아웃도, stage base 규칙도 보지 않는다. stage_targets 의
-    StageTargetError 도 StateError 로 바꿔 던진다 — caller 가 그 예외를 잡으려고
-    okstra_ctl 을 import 하지 않도록.
-
-    base 는 stage worktree 를 만들 때 registry 행에 적힌 `base_ref` 다 — 그
-    stage 가 실제로 갈라져 나온 커밋. 리뷰 시점에 규칙으로 다시 계산하면
-    표류한다: 다중의존 stage 는 오늘의 task-key worktree HEAD 를 받게 되어
-    whole-task final-verification 이 stage 들을 병합한 뒤에는 base..head 구간이
-    비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
-    """
-    from okstra_ctl import code_review_paths, worktree_registry
-    from okstra_ctl.stage_map import StageMapError, load_task_stage_map
-
-    identity = resolve_task_identity(project_root, task_key)
-    task_root = Path(identity["taskRoot"])
-    try:
-        stage_snapshot = load_task_stage_map(task_root, identity["manifest"])
-    except StageMapError as exc:
-        raise StateError(str(exc), stage=exc.code) from exc
-    if stage_snapshot.state != "ready":
-        raise StateError(
-            "implementation-planning Stage Map is missing",
-            stage="missing",
-        )
-    stages = stage_snapshot.stages
-    selected = next((s for s in stages if s["stage_number"] == stage), None)
-    if selected is None:
-        raise StateError(
-            f"stage {stage} is not in the Stage Map for {task_key}",
-            stage="stage_missing",
-        )
-
-    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
-    stage_row = worktree_registry.get_stage_row(*coords, stage) or {}
-    worktree_view = _stage_worktree_view(project_root, stage_row, stage)
-    base_commit = stage_row.get("base_ref") or _legacy_stage_base_commit(
-        identity, stages, selected
-    )
-    review_path, round_no = code_review_paths.next_stage_review(
-        code_review_paths.stage_review_dir(
-            project_root, identity["taskGroup"], identity["taskId"]
-        ),
-        stage,
-    )
-    return {
-        "mode": "stage",
-        "taskKey": identity["taskKey"],
-        "taskRoot": identity["taskRoot"],
-        "stage": stage,
-        **worktree_view,
-        "baseCommit": base_commit,
-        "reviewPath": str(review_path),
-        "round": round_no,
-    }
-
-
-def _legacy_stage_base_commit(
-    identity: dict, stages: list[dict], selected: dict
-) -> str:
-    """`base_ref` 를 남기지 않은 옛 registry 행의 base 를 규칙에서 되살린다.
-
-    provision 이 base_ref 를 기록하기 전에 만들어진 stage 행에만 쓰인다. 규칙
-    자체는 stage_targets 가 소유하며 여기서 다시 유도하지 않는다.
-    """
-    from okstra_ctl import stage_targets, worktree_registry
-    from okstra_ctl.paths import RunRef
-
-    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
-    plan_run_root = RunRef.from_task_root(
-        Path(identity["taskRoot"]), "implementation-planning"
-    ).run_dir
-    lifecycle = stage_targets.read_stage_lifecycle_snapshot(
-        stages, plan_run_root, recover_from_carry=True
-    )
-    # The anchor and the multi-dep candidate base must come from the task-key
-    # worktree HEAD, where stage work accumulates — not from the invocation
-    # cwd, which may sit on an older or unrelated commit.
-    task_entry = worktree_registry.lookup(*coords)
-    task_worktree = Path(
-        (task_entry.worktree_path if task_entry else "") or identity["projectRoot"]
-    )
-    anchor = worktree_registry.get_implementation_base(*coords) or ""
-    try:
-        return stage_targets.resolve_stage_base_commit(
-            selected,
-            lifecycle.done_rows,
-            anchor_base_commit=anchor,
-            candidate_base=_git_out(task_worktree, "rev-parse", "HEAD"),
-            project_root=task_worktree,
-            plan_run_root=plan_run_root,
-        )
-    except stage_targets.StageTargetError as exc:
-        raise StateError(
-            f"stage {selected['stage_number']} has no recorded base_ref and its "
-            f"base could not be derived: {exc}",
-            stage="stage_base_unresolved",
-        ) from exc
-
-
-def _stage_worktree_view(project_root: Path, stage_row: dict, stage: int) -> dict:
-    """한 stage 의 worktree 경로 / 브랜치 / head 커밋.
-
-    철거된 stage worktree 는 오류가 아니다: whole-task final-verification 이
-    디렉터리를 지워도 브랜치는 남고, 리뷰가 필요한 커밋은 그 브랜치에 그대로
-    있다.
-    """
-    branch = stage_row.get("branch") or ""
-    if not branch:
-        raise StateError(
-            f"stage {stage} has no registry branch — review it in branch mode",
-            stage="stage_branch_missing",
-        )
-    worktree_path = ""
-    if stage_row.get("status") == "active" and stage_row.get("worktree_path"):
-        candidate = Path(stage_row["worktree_path"])
-        if candidate.is_dir():
-            worktree_path = str(candidate)
-    head_source = Path(worktree_path) if worktree_path else Path(project_root)
-    head_ref = "HEAD" if worktree_path else branch
-    head_commit = _git_out(head_source, "rev-parse", head_ref)
-    if not head_commit:
-        raise StateError(
-            f"stage {stage} head could not be resolved: branch {branch!r} is "
-            f"not readable from {head_source}",
-            stage="stage_head_unresolved",
-        )
-    return {
-        "worktreePath": worktree_path,
-        "branch": branch,
-        "headCommit": head_commit,
-    }
-
-
-def _git_out(repo: Path, *args: str) -> str:
-    """git 호출의 stdout. 실패는 빈 문자열 — 호출자가 부재를 판단한다."""
-    result = subprocess.run(
-        ["git", "-C", str(repo), *args],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    return result.stdout.strip() if result.returncode == 0 else ""

package/runtime/python/okstra_token_usage/claude.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import sys
 import re
 from datetime import datetime
 from pathlib import Path
@@ -158,8 +159,15 @@ def _advance_usage_scan(jsonl_path: Path, usage_state: dict) -> dict:
                     if ev:
                         tail_events.append(ev)
                     break
-    except OSError:
+    except FileNotFoundError:
+        # expected-miss: 세션 jsonl 은 열거된 뒤 사라질 수 있고(정리·회전), 아직
+        # 한 줄도 안 쓴 세션은 파일 자체가 없다. 읽을 것이 없는 것이 정상이다.
         pass
+    except OSError as exc:
+        # 파일은 있는데 못 읽은 것은 다르다. 읽다 만 상태로 반환하면 토큰 집계가
+        # 실제보다 적게 나오는데 리포트에는 정상 수치처럼 찍힌다.
+        print(f"token-usage: partial read of {jsonl_path} ({exc})",
+              file=sys.stderr)
     usage_state.update(offset=offset, events=events,
                        agentName=agent_name, model=model)
     return {"events": events + tail_events,

package/runtime/python/okstra_token_usage/cli.py

@@ -14,7 +14,9 @@ from .report import (
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
+    parser = argparse.ArgumentParser(
+        prog="okstra token-usage",
+        description=__doc__)
     parser.add_argument(
         "team_state",
         type=Path,

package/runtime/python/okstra_token_usage/collect.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import sys
 import os
 from datetime import datetime, timezone
 from pathlib import Path
@@ -113,22 +114,76 @@ def _aggregate_totals(items: list[dict]) -> dict:
 def run_artifact_suffix(team_state_path: Path) -> str | None:
     """``team-state-<task-type>-<seq>.json`` → ``<task-type>-<seq>``.
 
-    이 접미사로 *같은 run* 의 run-manifest / status 를 정확히 짚는다. task 디렉토리
-    한 곳에 여러 run(재시도·이전 phase·레거시 타임스탬프)의 산출물이 섞여 있어,
-    glob 으로 아무거나 집으면 엉뚱한 run 의 시각을 쓰게 된다(관측: 가장 오래된
-    레거시 manifest 의 createdAt 을 집어 윈도우가 한 달로 벌어짐)."""
+    task 디렉토리 한 곳에 여러 run(재시도·이전 phase·레거시 타임스탬프)의 산출물이
+    섞여 있어, glob 으로 아무거나 집으면 엉뚱한 run 의 시각을 쓰게 된다(관측: 가장
+    오래된 레거시 manifest 의 createdAt 을 집어 윈도우가 한 달로 벌어짐).
+
+    **접미사가 곧 매니페스트 이름은 아니다.** okstra 는 카테고리별로 seq 를 따로
+    매기므로 한 run 이 `manifests: 025` 와 `state: 023` 을 동시에 가질 수 있다.
+    run-manifest 는 `_run_manifest_for_team_state` 가 매니페스트의 `teamStatePath`
+    역참조로 짚는다. status 산출물은 team-state 와 같은 카테고리라 이 접미사로
+    계속 짚는다."""
     name = team_state_path.name
     if not (name.startswith("team-state-") and name.endswith(".json")):
         return None
     return name[len("team-state-"):-len(".json")]
 
 
-def _run_manifest_created_at(run_dir: Path, suffix: str) -> str | None:
-    p = run_dir / "manifests" / f"run-manifest-{suffix}.json"
+def _read_json_or_none(path: Path) -> dict | None:
     try:
-        return json.loads(p.read_text()).get("createdAt")
+        data = json.loads(path.read_text())
     except (OSError, json.JSONDecodeError):
         return None
+    return data if isinstance(data, dict) else None
+
+
+def _run_manifest_for_team_state(
+    run_dir: Path, suffix: str, team_state_path: Path
+) -> dict | None:
+    """이 team-state 가 속한 run 의 매니페스트.
+
+    접미사가 곧 매니페스트 이름이라는 전제는 카테고리별 seq 가 갈리는 순간
+    깨진다. 실측(2026-08-27, fontsninja-nlpvibe `nestjs-migration-…`): 한 run 의
+    `manifests` 가 025, `state`·`prompts`·`worker-results` 가 023, `reports` 가
+    017 이었다. team-state 이름에서 뽑은 `023` 으로 매니페스트를 집으면 **12시간
+    전 run** 의 `createdAt`(04:45:34Z) 이 창의 시작이 되고, 그 사이 같은 세션이
+    돈 이전 run 들이 통째로 창에 들어온다 — `relax_start=False` 가 막으려던 바로
+    그 오탐이다(그 run 에서 로스터에 없는 워커 5명이 이 run 의 위반으로 보고됐다).
+
+    매니페스트는 자기 team-state 를 `teamStatePath` 에 적으므로 그것으로 맞춘다.
+    맞는 것이 없으면 접미사 방식으로 돌아간다 — 그 필드가 없던 옛 매니페스트다.
+    """
+    direct = run_dir / "manifests" / f"run-manifest-{suffix}.json"
+    # `Path.glob` 는 디렉터리가 없어도 빈 결과를 낸다 — 감쌀 예외가 없다.
+    candidates = [
+        direct,
+        *sorted((run_dir / "manifests").glob("run-manifest-*.json")),
+    ]
+    for path in candidates:
+        data = _read_json_or_none(path)
+        if data is None:
+            continue
+        recorded = str(data.get("teamStatePath") or "")
+        if recorded and Path(recorded).name == team_state_path.name:
+            return data
+    return _read_json_or_none(direct)
+
+
+def _created_at_by_suffix(run_dir: Path, suffix: str) -> str | None:
+    """접미사가 곧 매니페스트 이름인 조회.
+
+    **다른** run 을 접미사로 지목할 때만 쓴다(`_previous_run_end`). 이번 run 은
+    team-state 로 맞춰야 한다 — 두 접미사가 갈리는 run 이 실재한다.
+    """
+    data = _read_json_or_none(run_dir / "manifests" / f"run-manifest-{suffix}.json")
+    return None if data is None else data.get("createdAt")
+
+
+def _run_manifest_created_at(
+    run_dir: Path, suffix: str, team_state_path: Path
+) -> str | None:
+    data = _run_manifest_for_team_state(run_dir, suffix, team_state_path)
+    return None if data is None else data.get("createdAt")
 
 
 def _run_end_estimate(run_dir: Path, suffix: str) -> str | None:
@@ -233,9 +288,15 @@ def _previous_run_end(run_dir: Path, suffix: str) -> str | None:
         ended_at = prev_state.get("runEndedAt")
         if ended_at:
             return str(ended_at)
-    except (OSError, json.JSONDecodeError):
+    except OSError:
+        # expected-miss: 직전 run 이 team-state 를 남기지 않고 끝났으면 파일이
+        # 없다. 아래 두 추정 경로가 바로 그 경우를 위한 폴백이다.
         pass
-    return _run_end_estimate(run_dir, prev) or _run_manifest_created_at(run_dir, prev)
+    except json.JSONDecodeError as exc:
+        # 파일은 있는데 깨진 것은 폴백이 상정한 상황이 아니다.
+        print(f"token-usage: team-state for the previous run ({prev}) is not "
+              f"valid JSON, estimating instead ({exc})", file=sys.stderr)
+    return _run_end_estimate(run_dir, prev) or _created_at_by_suffix(run_dir, prev)
 
 
 def resolve_run_window(
@@ -271,7 +332,7 @@ def resolve_run_window(
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
-    since = _run_manifest_created_at(run_dir, suffix)
+    since = _run_manifest_created_at(run_dir, suffix, team_state_path)
     if relax_start:
         earliest = _earliest_lead_session_ts(state, team_state_path)
         if earliest and (since is None or earliest < since):

package/runtime/python/okstra_token_usage/cursor.py

@@ -92,4 +92,6 @@ def save_cache(jsonl_path: Path, cache: dict) -> None:
         tmp.write_text(json.dumps(cache, ensure_ascii=False, separators=(",", ":")))
         os.replace(tmp, p)
     except OSError:
+        # expected-miss: 이 캐시는 jsonl 에서 언제든 다시 만들 수 있는 파생물이다.
+        # 저장에 실패해도 집계 결과가 달라지지 않으므로 없는 것이 정상 분기다.
         pass

package/runtime/python/okstra_token_usage/grok.py

@@ -11,7 +11,7 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Mapping
-from urllib.parse import quote, unquote
+from urllib.parse import unquote
 
 from .jsonl_io import iter_jsonl
 from .paths import ts_in_window
@@ -132,10 +132,6 @@ def find_grok_sessions(
     return sorted(matches)
 
 
-def grok_session_dir_name(cwd: Path) -> str:
-    return quote(str(cwd), safe="")
-
-
 def grok_session_is_non_interactive(updates_path: Path) -> bool:
     """워커 래퍼 세션은 prompt_context.is_non_interactive 가 true 이다."""
     context_path = updates_path.parent / "prompt_context.json"

package/runtime/python/okstra_token_usage/paths.py

@@ -72,3 +72,29 @@ def claude_project_dir(cwd: Path, projects_root: Path | None = None) -> Path:
     # `projects_root` 는 테스트/진단용 주입 시드 — 기본은 실제 ~/.claude/projects.
     encoded = "-" + str(cwd).strip("/").replace("/", "-")
     return (projects_root or CLAUDE_PROJECTS) / encoded
+
+
+def find_session_jsonl(
+    session_id: str, cwd: Path, projects_root: Path | None = None
+) -> Path | None:
+    """세션 id 하나의 transcript 경로. 못 찾으면 None.
+
+    프로젝트로 인코딩된 디렉터리를 먼저 보고, 없으면 projects_root 아래의
+    모든 인코딩 디렉터리를 훑는다. 리드 세션의 cwd 가 대상 프로젝트 루트와
+    다를 수 있기 때문이다 — `okstra preflight --cwd <다른 프로젝트>` 는
+    지원되는 실행 방식이고, 그때 transcript 는 **리드 세션의 cwd** 로 인코딩된
+    디렉터리에 놓인다. 프로젝트 디렉터리만 보면 실재하는 세션을 없다고 답한다.
+
+    세션 id 는 전역 유일하므로 디렉터리를 넓혀도 다른 세션을 잘못 집지 않는다.
+    파일 내용을 읽지 않는 경로 조회다.
+    """
+    if not session_id:
+        return None
+    direct = claude_project_dir(cwd, projects_root) / f"{session_id}.jsonl"
+    if direct.is_file():
+        return direct
+    root = projects_root or CLAUDE_PROJECTS
+    try:
+        return next(iter(sorted(root.glob(f"*/{session_id}.jsonl"))), None)
+    except OSError:
+        return None

package/runtime/python/okstra_token_usage/pricing.py

@@ -8,14 +8,15 @@ provider:
     `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*`.
-  * Google / Gemini — `gemini-3.6-flash*`, `gemini-3.5-flash*`, `gemini-3.1-pro*`, `gemini-3-flash*`,
+  * Google / Gemini — `gemini-3.7-flash*`, `gemini-3.6-flash*`, `gemini-3.5-flash*`, `gemini-3.1-pro*`, `gemini-3-flash*`,
     `gemini-2.5-pro*`, `gemini-2.5-flash*`, `gemini-2.0-flash*`.
 
 Matching prefers the longest key that is a substring of the model id (most
 specific wins), so table ordering does not affect the result. Update when
 providers change list pricing.
 
-Sources (last verified 2026-08-03, public list prices, USD per 1M tokens):
+Sources (last verified 2026-08-03 — Google table re-verified 2026-08-26,
+public list prices, USD per 1M tokens):
   * Anthropic: https://www.anthropic.com/pricing
   * OpenAI:    https://openai.com/api/pricing
   * Google:    https://ai.google.dev/gemini-api/docs/pricing
@@ -74,9 +75,10 @@ CLAUDE_PRICING = {
 # Anthropic 1h ephemeral cache_creation multiplier on the base input rate.
 CLAUDE_CACHE_CREATE_1H_MULT = 2.0
 
-# Legacy / non-selectable codex prices. Selectable-model prices (the aliases the
-# picker offers) live in the model catalog and are merged in below via
-# `catalog_pricing("codex")`. Substring match order is now longest-key-first
+# Codex prices for slugs the provider catalog no longer offers. Prices for
+# registered models -- selectable or hidden -- live in the model catalog and are
+# merged in below via `catalog_pricing("codex")`. Substring match order is
+# longest-key-first
 # (see `_match_pricing`), so this dict's ordering no longer affects matching.
 # For models with no published cached-input rate (o1-pro, o3-pro), cached is set
 # equal to input as a conservative no-discount default.
@@ -84,6 +86,10 @@ _LEGACY_CODEX_PRICING = {
     # model substring -> (input USD/1M, cached_input USD/1M, output USD/1M).
 
     # GPT-5 series.
+    # gpt-5.6 was dropped from the provider catalog; its rate stays so past runs
+    # keep pricing. Substring matching means sol / terra / luna resolve here too
+    # -- the 5.6 family rate, not a per-variant price we have a source for.
+    "gpt-5.6":      (5.00,  0.50,  30.0),
     "gpt-5.2-pro":  (21.0,  2.10,  168.0),
     "gpt-5.1":      (1.25,  0.125, 10.0),
     "gpt-5-mini":   (0.25,  0.025, 2.00),
@@ -126,8 +132,14 @@ GEMINI_PRICING = {
     # forms appear in the wild, so include both for the new 3.x families.
 
     # Gemini 3 series.
-    "3.6-flash":       (1.50, 7.50),
-    "3-6-flash":       (1.50, 7.50),
+    # 3.7 Flash 와 3.6 Flash 는 2026-12-31 까지 도입 요율 $0.75/$3.75 이고
+    # 2027-01-01 에 표준 요율 $1.50/$7.50 으로 오른다(2026-08-26 확인). 이 표에는
+    # 시점 개념이 없으므로 지금 청구되는 값을 담는다 — 그날 이후 두 계열을
+    # (1.50, 7.50) 으로 갱신해야 한다.
+    "3.7-flash":       (0.75, 3.75),
+    "3-7-flash":       (0.75, 3.75),
+    "3.6-flash":       (0.75, 3.75),
+    "3-6-flash":       (0.75, 3.75),
     "3.5-flash":       (1.50, 9.00),
     "3-5-flash":       (1.50, 9.00),
     "3.1-pro":         (2.00, 12.0),

package/runtime/schemas/convergence-critic-results-v1.0.schema.json

@@ -31,6 +31,11 @@
           "items": { "type": "string", "pattern": "\\S" }
         },
         "originEvidence": { "type": "string", "pattern": "\\S" },
+        "duplicateOf": {
+          "type": "string",
+          "pattern": "\\S",
+          "description": "The existing finding id (`F-NNN`) this candidate overlaps. A declared duplicate is recorded and skips gap verification entirely; restating the finding instead costs one verification round to reject it. The shape stays free-form because `findingId` is free-form in convergence-groups-v2.0; `okstra convergence apply-critic-gaps` owns the check that the id names a finding the state actually carries."
+        },
         "severity": { "enum": ["critical", "major", "minor"] },
         "evidenceArtifacts": {
           "type": "array",

package/runtime/schemas/execution-manifest-v2.schema.json

@@ -236,10 +236,7 @@
         "dutyId",
         "dispatchKind",
         "round",
-        "inputDigest",
-        "writePolicy",
-        "writePolicyDigest",
-        "writeEnforcement"
+        "inputDigest"
       ],
       "properties": {
         "invocationRef": {"type": "string", "pattern": "\\S"},
@@ -250,10 +247,7 @@
         "dutyId": {"type": "string", "pattern": "\\S"},
         "dispatchKind": {"type": "string", "pattern": "\\S"},
         "round": {"type": "integer", "minimum": 1},
-        "inputDigest": {"$ref": "#/$defs/Digest"},
-        "writePolicy": {"$ref": "#/$defs/WritePolicy"},
-        "writePolicyDigest": {"$ref": "#/$defs/Digest"},
-        "writeEnforcement": {"$ref": "#/$defs/WriteEnforcement"}
+        "inputDigest": {"$ref": "#/$defs/Digest"}
       },
       "additionalProperties": false
     },
@@ -268,7 +262,10 @@
         "resultPath",
         "errorPath",
         "changeSummary",
-        "evidenceSealRef"
+        "evidenceSealRef",
+        "writePolicy",
+        "writePolicyDigest",
+        "writeEnforcement"
       ],
       "properties": {
         "invocationRef": {"type": "string", "pattern": "\\S"},
@@ -279,7 +276,10 @@
         "resultPath": {"type": ["string", "null"]},
         "errorPath": {"type": ["string", "null"]},
         "changeSummary": {"type": "object"},
-        "evidenceSealRef": {"type": ["string", "null"]}
+        "evidenceSealRef": {"type": ["string", "null"]},
+        "writePolicy": {"$ref": "#/$defs/WritePolicy"},
+        "writePolicyDigest": {"$ref": "#/$defs/Digest"},
+        "writeEnforcement": {"$ref": "#/$defs/WriteEnforcement"}
       },
       "additionalProperties": false
     },