okstra 0.60.1 → 0.60.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.60.1",
+  "version": "0.60.3",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.60.1",
-  "builtAt": "2026-06-09T04:37:38.373Z",
+  "package": "0.60.3",
+  "builtAt": "2026-06-09T06:44:22.023Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/render_final_report.py

@@ -522,7 +522,12 @@ def render_to_file(
     except json.JSONDecodeError as exc:
         raise FinalReportRenderError(f"invalid JSON in {data_path}: {exc}") from exc
 
-    resolved_template = template_path or find_default_template(data_path)
+    # 템플릿은 data.json 위치가 아니라 이 모듈(설치본은 ~/.okstra/lib/python,
+    # repo 는 scripts/) 위치 기준으로 찾는다. data_path 를 start 로 넘기면
+    # 프로젝트의 .okstra 트리만 위로 뒤지다 templates/reports 를 못 찾아
+    # 설치본에서 항상 'could not locate template' 으로 실패한다(OKSTRA_HOME 을
+    # 수동 설정해야 했던 원인). 프로젝트별 override 는 --template 으로 한다.
+    resolved_template = template_path or find_default_template()
     rendered = render(
         data,
         template_path=resolved_template,

package/runtime/python/okstra_token_usage/claude.py

@@ -7,8 +7,21 @@ from .jsonl_io import iter_jsonl
 from .paths import claude_project_dir
 
 
-def claude_session_totals(jsonl_path: Path) -> dict:
-    """Return totals + agentName + assistant model + time window for a Claude session jsonl."""
+def claude_session_totals(
+    jsonl_path: Path, *, since: str | None = None, until: str | None = None
+) -> dict:
+    """Return totals + agentName + assistant model + time window for a Claude session jsonl.
+
+    ``since`` / ``until`` are ISO-8601 timestamp strings (UTC ``...Z``). When
+    given, only records whose ``timestamp`` falls within ``[since, until]`` are
+    counted toward tokens / tool_uses / duration. This is the run-scoping seam:
+    an **in-session** lead writes its run into the user's whole-session jsonl,
+    so without a window the totals swallow every unrelated turn (observed:
+    lead billed 1.7억 tokens / $416 / 3h for a single requirements-discovery
+    run). ``agentName`` / ``model`` are session metadata and are read from the
+    whole file regardless of the window. Records without a timestamp are kept
+    (conservative — never silently drop usage when we can't place it in time).
+    """
     input_t = output_t = cache_create_t = cache_read_t = 0
     cache_create_5m_t = cache_create_1h_t = 0
     tool_uses = 0
@@ -20,6 +33,12 @@ def claude_session_totals(jsonl_path: Path) -> dict:
         if agent_name is None and rec.get("agentName"):
             agent_name = rec["agentName"]
         msg = rec.get("message") or {}
+        ts = rec.get("timestamp") or (msg.get("timestamp") if isinstance(msg, dict) else None)
+        in_window = not (ts and ((since and ts < since) or (until and ts > until)))
+        if rec.get("type") == "assistant" and model is None and msg.get("model"):
+            model = msg["model"]
+        if not in_window:
+            continue
         usage = msg.get("usage")
         if usage:
             input_t += usage.get("input_tokens", 0) or 0
@@ -39,12 +58,9 @@ def claude_session_totals(jsonl_path: Path) -> dict:
             else:
                 cache_create_5m_t += cc_total
         if rec.get("type") == "assistant":
-            if model is None and msg.get("model"):
-                model = msg["model"]
             for block in (msg.get("content") or []):
                 if isinstance(block, dict) and block.get("type") == "tool_use":
                     tool_uses += 1
-        ts = rec.get("timestamp") or (msg.get("timestamp") if isinstance(msg, dict) else None)
         if ts:
             if first_ts is None or ts < first_ts:
                 first_ts = ts
@@ -58,7 +74,12 @@ def claude_session_totals(jsonl_path: Path) -> dict:
             duration_ms = max(0, int((b - a).total_seconds() * 1000))
         except ValueError:
             duration_ms = 0
-    total = input_t + output_t + cache_create_t + cache_read_t
+    # '처리 토큰' total 에서 cache_read 는 제외한다. claude 는 매 턴 직전까지의
+    # 컨텍스트 전체를 캐시에서 재읽기(cache_read)하므로, 단순 합산하면 같은 토큰을
+    # 턴 수만큼 중복 카운트해 처리량이 비현실적으로 부풀려진다(예: in-session
+    # lead 가 1.7억으로 표시됨). cache_read 는 cacheReadTokens 로 따로 노출되고,
+    # 비용은 pricing 이 0.1x 단가로 별도 반영하므로 total 에서 빼도 비용은 불변.
+    total = input_t + output_t + cache_create_t
     return {
         "totalTokens": total,
         "inputTokens": input_t,

package/runtime/python/okstra_token_usage/collect.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import json
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from okstra_project.dirs import OKSTRA_RELATIVE
 
@@ -86,9 +86,61 @@ def _aggregate_totals(items: list[dict]) -> dict:
     return aggregate
 
 
+def _run_window_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 을 집어 윈도우가 한 달로 벌어짐)."""
+    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"
+    try:
+        return json.loads(p.read_text()).get("createdAt")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _run_end_estimate(run_dir: Path, suffix: str) -> str | None:
+    """run 종료 근사 — 같은 run 의 status 산출물 mtime(reconcile 후 고정, Phase 7
+    재렌더로도 바뀌지 않음). 완료 전(status 부재)이면 None."""
+    p = run_dir / "status" / f"final-{suffix}.status"
+    try:
+        mtime = p.stat().st_mtime
+    except OSError:
+        return None
+    return datetime.fromtimestamp(mtime, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
+    """이 run 의 [시작, 종료] ISO 윈도우.
+
+    in-session lead 는 자기 run 을 사용자의 *세션 전체* jsonl 에 기록하므로,
+    윈도우 없이 합산하면 무관한 모든 턴(다른 작업·대화)이 lead 토큰·시간에
+    섞여 폭증한다(관측: requirements-discovery 한 run 에 lead 1.7억 토큰 /
+    $416 / 3h). 토큰 집계를 이 윈도우로 스코핑해 그 run 분만 센다. 시작 =
+    이 run 의 run-manifest createdAt, 종료 = team-state.runEndedAt → 이 run 의
+    status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
+    (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백."""
+    suffix = _run_window_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)
+    until = state.get("runEndedAt") or _run_end_estimate(run_dir, suffix) or utc_now()
+    return since, until
+
+
 def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
+    run_since, run_until = _resolve_run_window(team_state_path, state)
     task_key = state.get("taskKey", "")
     # Prefer the team name actually persisted in team-state (set during Phase 3
     # when TeamCreate succeeded); only fall back to the `okstra-<task-id>`
@@ -130,7 +182,7 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         if sid == lead_sid:
             lead_path = path
             continue
-        totals = claude_session_totals(path)
+        totals = claude_session_totals(path, since=run_since, until=run_until)
         agent = totals.get("agentName")
         if agent:
             by_agent.setdefault(agent, []).append((sid, path, totals))
@@ -139,7 +191,7 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
 
     # Lead.
     if lead_path is not None:
-        totals = claude_session_totals(lead_path)
+        totals = claude_session_totals(lead_path, since=run_since, until=run_until)
         state["leadUsage"] = usage_block(totals, source="claude-jsonl")
         state["leadUsage"]["sessionId"] = lead_sid
     else:

package/runtime/templates/reports/final-report.template.md

@@ -32,6 +32,23 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% for row in followUpTasks if row.origin == 'phase-continuation' %}{% if loop.first %}- Next Step: run `/okstra-run`, select task `{{ header.taskKey }}`, choose task-type `{{ row.suggestedTaskType }}`
 {% endif %}{% endfor %}- Okstra Version: `{{ header.okstraVersion }}`
 
+{% if clarificationCarryIn and clarificationCarryIn.sourceFile %}
+## 0. Clarification Response Carried In From Previous Run
+
+- Source file: `{{ clarificationCarryIn.sourceFile }}`
+- {{ t("sectionIntro.clarificationCarryIn") }}
+
+{% endif %}
+## Summary of the Problem or Verification Target
+
+{{ t("sectionIntro.ticketCoverage") }}
+
+| {{ t("columns.recordMeta") }} | {{ t("columns.summary") }} |
+|--------|------------|
+{% for row in summary -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>{{ t("columns.source") }}: {{ row.source }} | {{ row.summary }} |
+{% endfor %}
+
 ## Verdict Card
 
 {{ t("sectionIntro.verdictCard") }}
@@ -599,23 +616,6 @@ Acceptance: {{ stage.acceptance }}
 | {{ t("verdictCard.rationaleLabel") }} | {{ finalVerdict.rationaleRowIds | join(', ') }} |
 | {{ t("verdictCard.nextStepLabel") }} | {{ finalVerdict.nextStep }} |
 
-{% if clarificationCarryIn and clarificationCarryIn.sourceFile %}
-## 0. Clarification Response Carried In From Previous Run
-
-- Source file: `{{ clarificationCarryIn.sourceFile }}`
-- {{ t("sectionIntro.clarificationCarryIn") }}
-
-{% endif %}
-## Summary of the Problem or Verification Target
-
-{{ t("sectionIntro.ticketCoverage") }}
-
-| {{ t("columns.recordMeta") }} | {{ t("columns.summary") }} |
-|--------|------------|
-{% for row in summary -%}
-| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>{{ t("columns.source") }}: {{ row.source }} | {{ row.summary }} |
-{% endfor %}
-
 {% if ticketCoverage.omit %}
 {# Ticket Coverage omitted entirely — release-handoff / final-verification #}
 {%- else %}