okstra 0.76.0 → 0.77.0

package/runtime/python/okstra_ctl/run.py

@@ -39,6 +39,7 @@ from .material import (
     resolve_related_tasks,
 )
 from .final_report_schema import load_schema
+from .lead_events import LeadEvent, append_lead_event
 from .models import ModelAssignment, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
@@ -266,6 +267,17 @@ class PrepareError(Exception):
     """surface to caller — task bundle prepare failed."""
 
 
+_ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex")
+
+
+def _normalize_lead_runtime(value: str) -> str:
+    runtime = (value or "claude-code").strip()
+    if runtime not in _ALLOWED_LEAD_RUNTIMES:
+        allowed = ", ".join(_ALLOWED_LEAD_RUNTIMES)
+        raise PrepareError(f"unsupported lead runtime: {runtime} (allowed: {allowed})")
+    return runtime
+
+
 @dataclass
 class PrepareInputs:
     workspace_root: Path
@@ -282,6 +294,7 @@ class PrepareInputs:
     codex_model: str = ""
     gemini_model: str = ""
     report_writer_model: str = ""
+    lead_runtime: str = "claude-code"
     executor: str = ""
     critic: str = ""
     related_tasks_raw: str = ""
@@ -932,6 +945,29 @@ def _brief_sha256(path: Path) -> str:
         return ""
 
 
+def _record_codex_render_only_event(inp: PrepareInputs, ctx: dict) -> None:
+    if inp.lead_runtime != "codex" or not inp.render_only:
+        return
+    append_lead_event(
+        Path(ctx["LEAD_EVENTS_PATH"]),
+        LeadEvent(
+            event_type="bundle-prepared",
+            lead_runtime="codex",
+            task_key=ctx["TASK_KEY"],
+            task_type=ctx["TASK_TYPE"],
+            run_seq=ctx["RUN_MANIFESTS_SEQ"],
+            timestamp=ctx["RUN_TIMESTAMP_ISO"],
+            details={
+                "dispatchMode": "render-only",
+                "workerDispatch": "not-started",
+                "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+                "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+                "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+            },
+        ),
+    )
+
+
 def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
     """rerun 충실 재현을 위한 canonical argv 재구성."""
     workers = inp.workers_override or ctx.get("RECOMMENDED_ANALYSERS", "")
@@ -951,6 +987,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL", "")),
         ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL", "")),
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL", "")),
+        ("--lead-runtime", inp.lead_runtime if inp.lead_runtime != "claude-code" else ""),
         ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--critic", inp.critic or ctx.get("CRITIC_CHOICE", "")),
         ("--related-tasks", inp.related_tasks_raw),
@@ -2013,6 +2050,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
     project_root = Path(inp.project_root)
+    lead_runtime = _normalize_lead_runtime(inp.lead_runtime)
+    if lead_runtime != "claude-code" and not inp.render_only:
+        raise PrepareError(
+            f"lead runtime `{lead_runtime}` is currently render-only; "
+            "use --render-only until the Codex dispatch adapter is implemented."
+        )
 
     # ---- input validation + asset resolution + roster/model 해소 ----
     # 각 단계는 명시적 입력/반환을 갖는 헬퍼로 분리되어 있다 (상단 phase 헬퍼
@@ -2197,6 +2240,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     ctx.update({
         "ANALYSIS_PROFILE": inp.task_type,
         "RECOMMENDED_ANALYSERS": selected_reviewers,
+        "LEAD_RUNTIME": lead_runtime,
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
         **handoff_tokens,
@@ -2235,6 +2279,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_VERSION": installed_version(),
         **workflow_state,
     })
+    if lead_runtime == "codex":
+        ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
+        ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
+        ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
         _reserve_final_verification_target(inp, ctx, ctx_stage_map)
 
@@ -2244,21 +2292,23 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
     )
-    # Always materialise the resume command script. Even in --render-only
-    # preparation flows the user (or a later non-interactive runner) may
-    # invoke it manually; deferring its creation until interactive launch
-    # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
-    # path that does not exist.
-    write_claude_resume_command_file(
-        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
-        project_root=project_root,
-        claude_session_id=claude_session_id,
-        task_key=ctx["TASK_KEY"],
-        task_type=ctx["TASK_TYPE"],
-        phase_state=ctx["CURRENT_RUN_STATUS"],
-        worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
-        prompt_seq=ctx["RUN_PROMPTS_SEQ"],
-    )
+    if lead_runtime == "claude-code":
+        # Always materialise the resume command script for Claude Code. Even in
+        # --render-only preparation flows the user (or a later non-interactive
+        # runner) may invoke it manually; deferring its creation until
+        # interactive launch leaves runs/<phase>/sessions/ empty and the
+        # manifest pointing at a path that does not exist. Codex runs resume via
+        # artifacts/checkpoints instead, so they intentionally leave this empty.
+        write_claude_resume_command_file(
+            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
+            project_root=project_root,
+            claude_session_id=claude_session_id,
+            task_key=ctx["TASK_KEY"],
+            task_type=ctx["TASK_TYPE"],
+            phase_state=ctx["CURRENT_RUN_STATUS"],
+            worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
+            prompt_seq=ctx["RUN_PROMPTS_SEQ"],
+        )
 
     # ---- fix-cycle 기록 (manifest 재작성 전 디스크 값으로 lazy-close 판정) ----
     # instruction-set 빌드보다 *앞*에서 호출해 이번 run 에서 새로 open 되는
@@ -2280,6 +2330,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- final status + manifest/discovery renders ----
     _finalize_status_and_render_manifests(inp, ctx, task_index_template)
+    _record_codex_render_only_event(inp, ctx)
 
     # ---- central index ----
     initial_status = "prepared" if inp.render_only else "running"
@@ -2354,6 +2405,17 @@ def main(argv: list[str]) -> int:
     p.add_argument("--codex-model", default="")
     p.add_argument("--gemini-model", default="")
     p.add_argument("--report-writer-model", default="")
+    p.add_argument(
+        "--lead-runtime",
+        default="claude-code",
+        choices=list(_ALLOWED_LEAD_RUNTIMES),
+        dest="lead_runtime",
+        help=(
+            "Lead runtime adapter. Default: claude-code. `codex` is accepted "
+            "for render-only artifact preparation while the dispatch adapter "
+            "is implemented."
+        ),
+    )
     p.add_argument("--executor", default="")
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
@@ -2490,6 +2552,7 @@ def main(argv: list[str]) -> int:
         codex_model=args.codex_model,
         gemini_model=args.gemini_model,
         report_writer_model=args.report_writer_model,
+        lead_runtime=args.lead_runtime,
         executor=args.executor,
         critic=args.critic,
         related_tasks_raw=args.related_tasks_raw,

package/runtime/python/okstra_token_usage/codex.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from .jsonl_io import iter_jsonl
-from .paths import CODEX_SESSIONS
+from .paths import CODEX_SESSIONS, ts_in_window
 
 
 def codex_session_total(jsonl_path: Path) -> dict:
@@ -47,9 +47,15 @@ def codex_session_total(jsonl_path: Path) -> dict:
 
 
 def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None:
-    """Find the codex rollout jsonl whose meta.cwd matches and timestamp falls in window."""
+    """Find the latest codex rollout jsonl in the requested window."""
+    sessions = find_codex_sessions(cwd, started_at, ended_at)
+    return sessions[-1] if sessions else None
+
+
+def find_codex_sessions(cwd: Path, started_at: str, ended_at: str) -> list[Path]:
+    """Find codex rollout jsonls whose meta.cwd matches the window."""
     if not CODEX_SESSIONS.is_dir() or not started_at or not ended_at:
-        return None
+        return []
     target_cwd = str(cwd)
     candidates: list[tuple[str, Path]] = []
     for p in CODEX_SESSIONS.rglob("rollout-*.jsonl"):
@@ -70,11 +76,10 @@ def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None
         if payload.get("cwd") != target_cwd:
             continue
         ts = payload.get("timestamp") or rec.get("timestamp") or ""
-        if not (started_at <= ts <= ended_at):
+        if not ts_in_window(ts, started_at, ended_at):
             continue
         candidates.append((ts, p))
     if not candidates:
-        return None
+        return []
     candidates.sort()
-    return candidates[-1][1]
-
+    return [path for _ts, path in candidates]

package/runtime/python/okstra_token_usage/collect.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import json
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 from okstra_project.dirs import OKSTRA_RELATIVE
 
 from .blocks import na_block, usage_block
@@ -12,8 +13,8 @@ from .claude import (
     find_claude_agent_sessions,
     find_claude_team_sessions,
 )
-from .codex import codex_session_total, find_codex_session
-from .gemini import find_gemini_session, gemini_session_total
+from .codex import codex_session_total, find_codex_session, find_codex_sessions
+from .gemini import find_gemini_session, find_gemini_sessions, gemini_session_total
 from .paths import claude_project_dir, utc_now
 from .pricing import codex_cost_usd, gemini_cost_usd
 
@@ -64,6 +65,8 @@ def _aggregate_totals(items: list[dict]) -> dict:
         "totalTokens": 0, "inputTokens": 0, "outputTokens": 0,
         "cacheCreationTokens": 0, "cacheCreation5mTokens": 0, "cacheCreation1hTokens": 0,
         "cacheReadTokens": 0,
+        "cachedInputTokens": 0, "reasoningOutputTokens": 0,
+        "cachedTokens": 0, "thoughtsTokens": 0, "toolTokens": 0,
         "toolUses": 0, "durationMs": 0,
         "agentName": None, "model": None,
         "startedAt": None, "endedAt": None,
@@ -71,7 +74,8 @@ def _aggregate_totals(items: list[dict]) -> dict:
     for t in items:
         for k in ("totalTokens", "inputTokens", "outputTokens",
                   "cacheCreationTokens", "cacheCreation5mTokens", "cacheCreation1hTokens",
-                  "cacheReadTokens", "toolUses"):
+                  "cacheReadTokens", "cachedInputTokens", "reasoningOutputTokens",
+                  "cachedTokens", "thoughtsTokens", "toolTokens", "toolUses"):
             aggregate[k] += t.get(k, 0) or 0
         if aggregate["agentName"] is None and t.get("agentName"):
             aggregate["agentName"] = t["agentName"]
@@ -207,6 +211,233 @@ def resolve_team_name(state: dict) -> str:
     return team_name
 
 
+def _resolve_project_path(project_root: Path, raw_path: str) -> Path | None:
+    if not raw_path:
+        return None
+    path = Path(raw_path)
+    return path if path.is_absolute() else project_root / path
+
+
+def _load_lead_event_records(project_root: Path, state: dict) -> list[dict]:
+    path = _resolve_project_path(project_root, state.get("leadEventsPath", ""))
+    if path is None or not path.is_file():
+        return []
+    records = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def _codex_worker_windows(project_root: Path, state: dict) -> dict[str, list[tuple[str, str]]]:
+    active: dict[tuple[str, str], str] = {}
+    windows: dict[str, list[tuple[str, str]]] = {}
+    for event in _load_lead_event_records(project_root, state):
+        details = event.get("details") or {}
+        if not isinstance(details, dict):
+            continue
+        worker_id = str(details.get("workerId") or "").strip()
+        if not worker_id:
+            continue
+        attempt = str(details.get("attempt") or "")
+        key = (worker_id, attempt)
+        event_type = event.get("eventType")
+        timestamp = str(event.get("timestamp") or "").strip()
+        if not timestamp:
+            continue
+        if event_type == "worker-dispatched":
+            active[key] = timestamp
+        elif event_type in {"worker-result-collected", "worker-failed"}:
+            started_at = active.pop(key, "")
+            if started_at:
+                windows.setdefault(worker_id, []).append((started_at, timestamp))
+    running_workers = {
+        str(worker.get("workerId") or "").strip()
+        for worker in state.get("workers", [])
+        if isinstance(worker, dict) and worker.get("status") == "running"
+    }
+    if running_workers:
+        open_until = utc_now()
+        for (worker_id, _attempt), started_at in active.items():
+            if worker_id in running_workers:
+                windows.setdefault(worker_id, []).append((started_at, open_until))
+    return windows
+
+
+def _codex_runtime_provider(worker: dict) -> str:
+    worker_id = str(worker.get("workerId") or "").strip()
+    agent = str(worker.get("agent") or "").strip()
+    if worker_id == "report-writer":
+        return "codex"
+    if agent in {"codex", "gemini"}:
+        return agent
+    return ""
+
+
+def _cli_sessions_for_windows(
+    provider: str,
+    project_root: Path,
+    windows: list[tuple[str, str]],
+) -> list[Path]:
+    sessions: list[Path] = []
+    seen: set[Path] = set()
+    for started_at, ended_at in windows:
+        if provider == "codex":
+            matches = find_codex_sessions(project_root, started_at, ended_at)
+        elif provider == "gemini":
+            matches = find_gemini_sessions(project_root, started_at, ended_at)
+        else:
+            matches = []
+        for path in matches:
+            if path not in seen:
+                seen.add(path)
+                sessions.append(path)
+    return sessions
+
+
+def _cli_session_totals(provider: str, session_paths: list[Path]) -> list[dict]:
+    totals = []
+    for session_path in session_paths:
+        if provider == "codex":
+            total = codex_session_total(session_path)
+        else:
+            total = gemini_session_total(session_path)
+        if total.get("available"):
+            totals.append(total)
+    return totals
+
+
+def _cli_usage_block(provider: str, totals: dict, session_paths: list[Path]) -> dict:
+    block = usage_block(totals, source=f"{provider}-cli")
+    block["cliTotalTokens"] = totals.get("totalTokens", 0) or 0
+    block["cliSessionPaths"] = [str(path) for path in session_paths]
+    if totals.get("model"):
+        block["model"] = totals["model"]
+        block["cliModel"] = totals["model"]
+    if provider == "codex":
+        cost = codex_cost_usd(
+            totals.get("model"),
+            totals.get("inputTokens", 0) or 0,
+            totals.get("cachedInputTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+    else:
+        cost = gemini_cost_usd(
+            totals.get("model"),
+            totals.get("inputTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+    if cost is not None:
+        block["cliEstimatedCostUsd"] = cost
+    return block
+
+
+def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
+    windows_by_worker = _codex_worker_windows(project_root, state)
+    state["leadUsage"] = na_block(
+        "Codex lead token accounting is not available yet; worker CLI usage is collected from provider logs."
+    )
+    for worker in state.get("workers", []):
+        if not isinstance(worker, dict):
+            continue
+        provider = _codex_runtime_provider(worker)
+        if not provider:
+            worker["usage"] = na_block(
+                f"worker provider is not CLI-backed in Codex runtime: {worker.get('agent') or worker.get('workerId')}"
+            )
+            continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        windows = windows_by_worker.get(worker_id, [])
+        if not windows:
+            worker["usage"] = na_block(
+                f"no lead-events dispatch window found for workerId={worker_id}"
+            )
+            continue
+        session_paths = _cli_sessions_for_windows(provider, project_root, windows)
+        totals = _cli_session_totals(provider, session_paths)
+        if not totals:
+            worker["usage"] = na_block(
+                f"no {provider} CLI session found in lead-events dispatch window"
+            )
+            continue
+        worker["usage"] = _cli_usage_block(
+            provider,
+            _aggregate_totals(totals),
+            session_paths,
+        )
+    _populate_usage_summary(state, team_name=resolve_team_name(state), sessions_found=0)
+    return state
+
+
+def _populate_usage_summary(
+    state: dict,
+    *,
+    team_name: str,
+    sessions_found: int,
+    unattributed_sessions: list[str] | None = None,
+    unattributed_usage: dict[str, Any] | None = None,
+) -> None:
+    workers = state.get("workers", [])
+    lead = state.get("leadUsage") or {}
+    lead_total = lead.get("totalTokens", 0) or 0
+    lead_billable = lead.get("billableEquivalentTokens", 0) or 0
+    lead_cost = lead.get("estimatedCostUsd", 0) or 0
+    worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
+    worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
+    worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
+    cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
+    if unattributed_usage is not None:
+        worker_total += unattributed_usage.get("totalTokens", 0) or 0
+        worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
+        worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
+
+    unmatched_models: list[str] = []
+    if lead.get("model") and lead.get("estimatedCostUsd") is None and (lead.get("totalTokens") or 0) > 0:
+        unmatched_models.append(lead["model"])
+    for w in workers:
+        u = w.get("usage") or {}
+        if (
+            u.get("source") not in {"codex-cli", "gemini-cli"}
+            and u.get("model")
+            and u.get("estimatedCostUsd") is None
+            and (u.get("totalTokens") or 0) > 0
+        ):
+            unmatched_models.append(u["model"])
+        if u.get("cliModel") and u.get("cliEstimatedCostUsd") is None and (u.get("cliTotalTokens") or 0) > 0:
+            unmatched_models.append(u["cliModel"])
+    state["usageSummary"] = {
+        "leadTotalTokens": lead_total,
+        "workerTotalTokens": worker_total,
+        "grandTotalTokens": lead_total + worker_total,
+        "leadBillableEquivalentTokens": lead_billable,
+        "workerBillableEquivalentTokens": worker_billable,
+        "grandBillableEquivalentTokens": lead_billable + worker_billable,
+        "estimatedCostUsd": {
+            "lead": round(lead_cost, 4),
+            "claudeWorkers": round(worker_cost, 4),
+            "cliWorkers": round(cli_cost, 4),
+            "grandTotal": round(lead_cost + worker_cost + cli_cost, 4),
+        },
+        "collectedAt": utc_now(),
+        "teamName": team_name,
+        "sessionsFound": sessions_found,
+        "unmatchedModels": sorted(set(unmatched_models)),
+        "unattributedTeamSessions": unattributed_sessions or [],
+        "unattributedWorkerUsage": unattributed_usage,
+        "definitions": {
+            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
+            "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",
+            "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers Codex/Gemini CLI calls billed under those providers.",
+        },
+    }
+
+
 def collect(team_state_path: Path, project_root: Path | None = None, *,
             incremental: bool = True) -> dict:
     # incremental: 세션 jsonl 스캔에 byte cursor 캐시 사용 (P6). 캐시는 윈도우
@@ -218,6 +449,8 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     task_key = state.get("taskKey", "")
     team_name = resolve_team_name(state)
     lead_sid = (state.get("lead") or {}).get("sessionId")
+    if state.get("leadRuntime") == "codex":
+        return _collect_codex_runtime_usage(state, cwd)
 
     # 1) Claude sessions (lead + claude-side workers). Cache totals at scan
     # time so we don't re-read the jsonl when a worker matches multiple
@@ -372,56 +605,13 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             "cannot be mapped to a specific workerId."
         )
 
-    # Aggregate summary.
-    lead = state.get("leadUsage") or {}
-    workers = state.get("workers", [])
-    lead_total = lead.get("totalTokens", 0) or 0
-    lead_billable = lead.get("billableEquivalentTokens", 0) or 0
-    lead_cost = lead.get("estimatedCostUsd", 0) or 0
-    worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
-    worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
-    worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
-    cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
-    if unattributed_usage is not None:
-        worker_total += unattributed_usage.get("totalTokens", 0) or 0
-        worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
-        worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
-
-    # Surface models whose pricing lookup failed so the silent-zero case is visible.
-    unmatched_models: list[str] = []
-    if lead.get("model") and lead.get("estimatedCostUsd") is None and (lead.get("totalTokens") or 0) > 0:
-        unmatched_models.append(lead["model"])
-    for w in workers:
-        u = w.get("usage") or {}
-        if u.get("model") and u.get("estimatedCostUsd") is None and (u.get("totalTokens") or 0) > 0:
-            unmatched_models.append(u["model"])
-        if u.get("cliModel") and u.get("cliEstimatedCostUsd") is None and (u.get("cliTotalTokens") or 0) > 0:
-            unmatched_models.append(u["cliModel"])
-    state["usageSummary"] = {
-        "leadTotalTokens": lead_total,
-        "workerTotalTokens": worker_total,
-        "grandTotalTokens": lead_total + worker_total,
-        "leadBillableEquivalentTokens": lead_billable,
-        "workerBillableEquivalentTokens": worker_billable,
-        "grandBillableEquivalentTokens": lead_billable + worker_billable,
-        "estimatedCostUsd": {
-            "lead": round(lead_cost, 4),
-            "claudeWorkers": round(worker_cost, 4),
-            "cliWorkers": round(cli_cost, 4),
-            "grandTotal": round(lead_cost + worker_cost + cli_cost, 4),
-        },
-        "collectedAt": utc_now(),
-        "teamName": team_name,
-        "sessionsFound": len(claude_sessions),
-        "unmatchedModels": sorted(set(unmatched_models)),
-        "unattributedTeamSessions": unattributed_sessions,
-        "unattributedWorkerUsage": unattributed_usage,
-        "definitions": {
-            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
-            "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",
-            "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers Codex/Gemini CLI calls billed under those providers.",
-        },
-    }
+    _populate_usage_summary(
+        state,
+        team_name=team_name,
+        sessions_found=len(claude_sessions),
+        unattributed_sessions=unattributed_sessions,
+        unattributed_usage=unattributed_usage,
+    )
     return state
 
 
@@ -435,4 +625,3 @@ def _infer_project_root(team_state_path: Path, state: dict) -> Path:
             return p
         p = p.parent
     raise SystemExit(f"could not infer project root from {team_state_path}")
-

package/runtime/python/okstra_token_usage/gemini.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from .paths import GEMINI_TMP
+from .paths import GEMINI_TMP, ts_in_window
 
 
 def gemini_session_total(json_path: Path) -> dict:
@@ -40,9 +40,15 @@ def gemini_session_total(json_path: Path) -> dict:
 
 
 def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:
-    """Find the gemini chat session whose first user message references the project."""
+    """Find the latest gemini chat session in the requested window."""
+    sessions = find_gemini_sessions(project_root, started_at, ended_at)
+    return sessions[-1] if sessions else None
+
+
+def find_gemini_sessions(project_root: Path, started_at: str, ended_at: str) -> list[Path]:
+    """Find gemini chat sessions whose first user message references the project."""
     if not GEMINI_TMP.is_dir() or not started_at or not ended_at:
-        return None
+        return []
     project_str = str(project_root)
     candidates: list[tuple[str, Path]] = []
     for p in GEMINI_TMP.glob("*/chats/session-*.json"):
@@ -51,7 +57,7 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
         except (OSError, json.JSONDecodeError):
             continue
         start = data.get("startTime") or ""
-        if not (started_at <= start <= ended_at):
+        if not ts_in_window(start, started_at, ended_at):
             continue
         # Match by content: first user message should mention project root or task path.
         msgs = data.get("messages") or []
@@ -71,7 +77,6 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
                 candidates.append((start, p))
             break
     if not candidates:
-        return None
+        return []
     candidates.sort()
-    return candidates[-1][1]
-
+    return [path for _start, path in candidates]

package/runtime/skills/okstra-setup/SKILL.md

@@ -251,7 +251,7 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 
 `release-handoff` fills the PR body from a template. By default it uses the
 bundled skill template at
-`~/.claude/skills/okstra-run/templates/pr-body.template.md`. Most projects
+`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.