okstra 0.186.7 → 0.188.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/antigravity.py

@@ -1,18 +1,64 @@
 """Antigravity (`agy`) CLI usage collector.
 
 공식 headless 문서는 ``--output-format json`` / ``stream-json`` 의 최종
-``usage`` 객체에 토큰을 둔다. okstra 는 이미 ``stream-json`` 으로 호출하고
-그 줄을 워커 로그에 남긴다. 정본은 마지막 ``result.usage`` 이다.
+``usage`` 객체에 토큰을 둔다. okstra 는 ``stream-json`` 으로 호출하고, 러너가
+스트림의 마지막 ``usage`` 스냅샷을 래퍼 status 사이드카의 ``usage`` 에 적는다
+(`worker_runner`) — 그것이 정본이다. 워커 로그는 러너가 사람이 읽는 줄로 옮겨
+적은 것이라 stream-json 이 아니다. raw stream-json 로그를 읽는 경로는 러너
+이전의 로그를 위해 남긴다.
 """
 from __future__ import annotations
 
+import json
 from pathlib import Path
+from typing import Any, Mapping
 
 from .jsonl_io import iter_jsonl
 
 
+def _usage_total(usage: Mapping[str, Any], model: str | None) -> dict:
+    return {
+        "totalTokens": usage.get("total_tokens", 0) or 0,
+        "inputTokens": usage.get("input_tokens", 0) or 0,
+        "outputTokens": usage.get("output_tokens", 0) or 0,
+        "thoughtsTokens": usage.get("thinking_tokens", 0) or 0,
+        "cacheReadTokens": usage.get("cache_read_tokens", 0) or 0,
+        "model": model,
+        "available": True,
+    }
+
+
+def _read_status(status_path: Path) -> dict | None:
+    try:
+        data = json.loads(status_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def status_carries_usage(path: Path) -> bool:
+    """이 경로가 ``usage`` 스냅샷을 실은 래퍼 status 사이드카인가."""
+    if not path.name.endswith(".status.json"):
+        return False
+    status = _read_status(path)
+    return isinstance((status or {}).get("usage"), dict) and bool(status["usage"])
+
+
+def antigravity_status_total(status_path: Path) -> dict:
+    """래퍼 status 사이드카의 ``usage`` 스냅샷. 모델은 served-model 관측값이다."""
+    status = _read_status(status_path) or {}
+    usage = status.get("usage")
+    if not isinstance(usage, dict) or not usage:
+        return {"totalTokens": 0, "available": False}
+    attestation = status.get("servedModelAttestation")
+    model = (
+        attestation.get("observedModel") if isinstance(attestation, dict) else None
+    )
+    return _usage_total(usage, model if isinstance(model, str) and model else None)
+
+
 def antigravity_session_total(json_path: Path) -> dict:
-    """stream-json 로그에서 마지막 result.usage 를 읽는다."""
+    """raw stream-json 로그에서 마지막 result.usage 를 읽는다."""
     result_usage: dict | None = None
     step_usage: dict | None = None
     model: str | None = None
@@ -35,15 +81,7 @@ def antigravity_session_total(json_path: Path) -> dict:
     usage = result_usage or step_usage
     if usage is None:
         return {"totalTokens": 0, "available": False}
-    return {
-        "totalTokens": usage.get("total_tokens", 0) or 0,
-        "inputTokens": usage.get("input_tokens", 0) or 0,
-        "outputTokens": usage.get("output_tokens", 0) or 0,
-        "thoughtsTokens": usage.get("thinking_tokens", 0) or 0,
-        "cacheReadTokens": usage.get("cache_read_tokens", 0) or 0,
-        "model": model,
-        "available": True,
-    }
+    return _usage_total(usage, model)
 
 
 def find_antigravity_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:

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,