okstra 0.64.1 → 0.66.0

package/runtime/python/okstra_project/dirs.py

@@ -9,11 +9,12 @@ DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·m
 중복으로 박혀 있었고, 디렉토리 이름을 바꾸려면 60+ 파일을 동시에 수정해야 했다.
 이 모듈은 그 비용을 한 줄 수정으로 줄인다.
 
-의존성 0 (Path only). `paths.py` 와 `state.py` 양쪽에서 import 되므로 순환 위험을
+의존성 0 (stdlib only). `paths.py` 와 `state.py` 양쪽에서 import 되므로 순환 위험을
 피하기 위해 다른 okstra 모듈을 import 하지 않는다.
 """
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 OKSTRA_DIR_NAME = ".okstra"
@@ -39,6 +40,14 @@ TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
 LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
 
 
+def okstra_home() -> Path:
+    """`~/.okstra` 절대 path. 테스트/설치 환경에서 `OKSTRA_HOME` env 로 override."""
+    override = os.environ.get("OKSTRA_HOME", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / ".okstra"
+
+
 def okstra_root(project_root: Path) -> Path:
     """`<project_root>/.okstra` 절대 path."""
     return Path(project_root) / OKSTRA_RELATIVE

package/runtime/python/okstra_token_usage/claude.py

@@ -1,66 +1,151 @@
 """Claude Code transcript collectors."""
 from __future__ import annotations
 
+import json
 from datetime import datetime
 from pathlib import Path
-from .jsonl_io import iter_jsonl
-from .paths import claude_project_dir
 
+from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
+from .paths import claude_project_dir, ts_in_window
 
-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).
+def _event_from_record(rec: dict) -> dict | None:
+    """jsonl 레코드 1개 → 압축 이벤트. 집계에 기여하지 않으면 None.
+
+    키: t=timestamp, i/o=input/output, c=cache_creation 합, c5/c1=ephemeral
+    5m/1h, r=cache_read, u=tool_use 수. 0/부재 필드는 생략(캐시 크기 절약).
+    ts-only 레코드도 보존한다 — 임의 윈도우의 first/last ts 산출에 필요.
     """
+    msg = rec.get("message")
+    if not isinstance(msg, dict):
+        msg = {}
+    ev: dict = {}
+    usage = msg.get("usage")
+    if usage:
+        for src, key in (("input_tokens", "i"), ("output_tokens", "o"),
+                         ("cache_read_input_tokens", "r")):
+            v = usage.get(src, 0) or 0
+            if v:
+                ev[key] = v
+        cc_total = usage.get("cache_creation_input_tokens", 0) or 0
+        if cc_total:
+            ev["c"] = cc_total
+        cc_break = usage.get("cache_creation") or {}
+        if isinstance(cc_break, dict) and (
+                cc_break.get("ephemeral_5m_input_tokens") is not None
+                or cc_break.get("ephemeral_1h_input_tokens") is not None):
+            v5 = cc_break.get("ephemeral_5m_input_tokens", 0) or 0
+            v1 = cc_break.get("ephemeral_1h_input_tokens", 0) or 0
+            if v5:
+                ev["c5"] = v5
+            if v1:
+                ev["c1"] = v1
+        elif cc_total:
+            # API 분해가 없으면 전부 5m 티어로(1.25x — 더 싼 가정, 기존 동작).
+            ev["c5"] = cc_total
+    if rec.get("type") == "assistant":
+        tools = sum(1 for b in (msg.get("content") or [])
+                    if isinstance(b, dict) and b.get("type") == "tool_use")
+        if tools:
+            ev["u"] = tools
+    ts = rec.get("timestamp") or msg.get("timestamp")
+    if ts:
+        ev["t"] = ts
+    return ev or None
+
+
+def _session_meta_from_record(rec: dict) -> tuple[str | None, str | None]:
+    """레코드에서 (agentName, model) 후보 추출 — 둘 다 first-non-null 정책."""
+    agent = rec.get("agentName") or None
+    model = None
+    if rec.get("type") == "assistant":
+        msg = rec.get("message")
+        if isinstance(msg, dict) and msg.get("model"):
+            model = msg["model"]
+    return agent, model
+
+
+def _advance_usage_scan(jsonl_path: Path, usage_state: dict) -> dict:
+    """`usage_state['offset']` 이후의 완결 라인을 읽어 이벤트를 커밋하고,
+    개행 없는 마지막 라인은 transient 로만 반영한 view 를 돌려준다.
+
+    transient tail: 아직 쓰는 중일 수 있는 라인 — 이번 집계에는 포함하되
+    커서를 전진시키지 않아, 다음 호출이 완결본으로 다시 읽는다(이중 집계도
+    누락도 없음). 깨진 utf-8 / JSON / 비-dict 라인은 건너뛰되 커서는 전진
+    (구버전은 text-mode 디코드 실패 시 collect 전체가 죽었다 — fail-open 개선).
+    """
+    events = list(usage_state.get("events") or [])
+    agent_name = usage_state.get("agentName")
+    model = usage_state.get("model")
+    offset = usage_state.get("offset", 0) or 0
+    try:
+        size = jsonl_path.stat().st_size
+    except OSError:
+        size = 0
+    if offset > size:
+        # 식별자 가드를 통과했더라도 truncate 방어 — 처음부터 재스캔.
+        events, agent_name, model, offset = [], None, None, 0
+    tail_events: list[dict] = []
+    tail_agent: str | None = None
+    tail_model: str | None = None
+    try:
+        with jsonl_path.open("rb") as fh:
+            fh.seek(offset)
+            while True:
+                raw = fh.readline()
+                if not raw:
+                    break
+                rec = None
+                stripped = raw.strip()
+                if stripped:
+                    try:
+                        parsed = json.loads(stripped.decode("utf-8"))
+                        rec = parsed if isinstance(parsed, dict) else None
+                    except (UnicodeDecodeError, json.JSONDecodeError):
+                        rec = None
+                ev = _event_from_record(rec) if rec else None
+                rec_agent, rec_model = _session_meta_from_record(rec) if rec else (None, None)
+                if raw.endswith(b"\n"):
+                    offset = fh.tell()
+                    if agent_name is None and rec_agent:
+                        agent_name = rec_agent
+                    if model is None and rec_model:
+                        model = rec_model
+                    if ev:
+                        events.append(ev)
+                else:
+                    tail_agent, tail_model = rec_agent, rec_model
+                    if ev:
+                        tail_events.append(ev)
+                    break
+    except OSError:
+        pass
+    usage_state.update(offset=offset, events=events,
+                       agentName=agent_name, model=model)
+    return {"events": events + tail_events,
+            "agentName": agent_name if agent_name is not None else tail_agent,
+            "model": model if model is not None else tail_model}
+
+
+def _totals_from_events(events: list[dict], agent_name: str | None,
+                        model: str | None,
+                        since: str | None, until: str | None) -> dict:
     input_t = output_t = cache_create_t = cache_read_t = 0
     cache_create_5m_t = cache_create_1h_t = 0
     tool_uses = 0
-    agent_name: str | None = None
-    model: str | None = None
     first_ts: str | None = None
     last_ts: str | None = None
-    for rec in iter_jsonl(jsonl_path):
-        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:
+    for ev in events:
+        ts = ev.get("t")
+        if ts and not ts_in_window(ts, since, until):
             continue
-        usage = msg.get("usage")
-        if usage:
-            input_t += usage.get("input_tokens", 0) or 0
-            output_t += usage.get("output_tokens", 0) or 0
-            cc_total = usage.get("cache_creation_input_tokens", 0) or 0
-            cache_create_t += cc_total
-            cache_read_t += usage.get("cache_read_input_tokens", 0) or 0
-            # Split into 5m / 1h ephemeral tiers when the API breakdown is
-            # present. If only the aggregate is given, attribute all of it to
-            # the 5m tier (1.25x — the cheaper assumption, matches prior
-            # behavior).
-            cc_break = usage.get("cache_creation") or {}
-            if isinstance(cc_break, dict) and (cc_break.get("ephemeral_5m_input_tokens") is not None
-                                               or cc_break.get("ephemeral_1h_input_tokens") is not None):
-                cache_create_5m_t += cc_break.get("ephemeral_5m_input_tokens", 0) or 0
-                cache_create_1h_t += cc_break.get("ephemeral_1h_input_tokens", 0) or 0
-            else:
-                cache_create_5m_t += cc_total
-        if rec.get("type") == "assistant":
-            for block in (msg.get("content") or []):
-                if isinstance(block, dict) and block.get("type") == "tool_use":
-                    tool_uses += 1
+        input_t += ev.get("i", 0)
+        output_t += ev.get("o", 0)
+        cache_create_t += ev.get("c", 0)
+        cache_create_5m_t += ev.get("c5", 0)
+        cache_create_1h_t += ev.get("c1", 0)
+        cache_read_t += ev.get("r", 0)
+        tool_uses += ev.get("u", 0)
         if ts:
             if first_ts is None or ts < first_ts:
                 first_ts = ts
@@ -97,7 +182,75 @@ def claude_session_totals(
     }
 
 
-def find_claude_team_sessions(cwd: Path, team_name: str, lead_sid: str | None = None) -> dict[str, Path]:
+def claude_session_totals(
+    jsonl_path: Path, *, since: str | None = None, until: str | None = None,
+    incremental: bool = False,
+) -> 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).
+
+    ``incremental=True`` 면 $OKSTRA_HOME 캐시의 byte cursor 이후만 읽는다.
+    캐시에는 윈도우 적용 전 이벤트가 저장되므로 호출마다 다른 since/until
+    에도 결과는 전체 스캔과 동일하다 (P6 plan 참조).
+    """
+    if incremental:
+        cache = load_cache(jsonl_path)
+        view = _advance_usage_scan(jsonl_path, cache["usage"])
+        save_cache(jsonl_path, cache)
+    else:
+        view = _advance_usage_scan(jsonl_path, fresh_cache()["usage"])
+    return _totals_from_events(view["events"], view["agentName"],
+                               view["model"], since, until)
+
+
+def _needle_scan(jsonl_path: Path, entry: dict, needle_lower: str) -> bool:
+    """entry({'offset','found'}) 를 전진시키며 needle 존재 여부 반환.
+
+    미완결 tail 라인도 검사한다 — 부분 문자열 매칭은 라인 완결 후에도 유효
+    하므로 found=True 는 그대로 커밋해도 안전하다. 단 offset 은 완결 라인
+    까지만 전진해, 미완결 tail 은 다음 호출이 다시 본다.
+    """
+    if entry.get("found"):
+        return True
+    offset = entry.get("offset", 0) or 0
+    try:
+        if offset > jsonl_path.stat().st_size:
+            offset = 0  # truncate/교체 방어
+        with jsonl_path.open("rb") as fh:
+            fh.seek(offset)
+            while True:
+                raw = fh.readline()
+                if not raw:
+                    break
+                if needle_lower in raw.decode("utf-8", errors="replace").lower():
+                    entry["found"] = True
+                    entry["offset"] = offset
+                    return True
+                if raw.endswith(b"\n"):
+                    offset = fh.tell()
+    except OSError:
+        return False
+    entry["offset"] = offset
+    return False
+
+
+def find_claude_team_sessions(
+    cwd: Path,
+    team_name: str,
+    lead_sid: str | None = None,
+    projects_root: Path | None = None,
+    *,
+    incremental: bool = False,
+) -> dict[str, Path]:
     """Map sessionId -> jsonl path for all jsonls tagged with `team_name`.
 
     Matching is case-insensitive on the teamName needle to tolerate runs where
@@ -107,25 +260,37 @@ def find_claude_team_sessions(cwd: Path, team_name: str, lead_sid: str | None =
     If `lead_sid` is provided and exists in the project dir, it is always
     included even when no teamName needle matches — this lets us recover lead
     usage in fallback runs that never wrote `team.teamName` into team-state.
+
+    `projects_root` 는 테스트/진단용 주입 시드 — 기본은 실제 ~/.claude/projects.
+
+    ``incremental=True`` 면 파일별 needle cursor 이후의 신규 byte 만 검사한다.
+    needle(=team 이름)은 run 마다 다르므로 파일당 MAX_NEEDLES 개까지 오래된
+    순으로 교체 보존한다.
     """
-    proj_dir = claude_project_dir(cwd)
+    proj_dir = claude_project_dir(cwd, projects_root)
     out: dict[str, Path] = {}
     if not proj_dir.is_dir():
         return out
     needle_lower = f'"teamname":"{(team_name or "").lower()}"'
-    have_team = bool(team_name)
-    for p in proj_dir.glob("*.jsonl"):
-        try:
-            with p.open() as fh:
-                for chunk in fh:
-                    if have_team and needle_lower in chunk.lower():
-                        out[p.stem] = p
-                        break
-        except OSError:
-            continue
+    if team_name:
+        for p in proj_dir.glob("*.jsonl"):
+            if incremental:
+                cache = load_cache(p)
+                needles = cache.setdefault("needles", {})
+                entry = needles.get(needle_lower)
+                if entry is None:
+                    entry = {"offset": 0, "found": False}
+                    while len(needles) >= MAX_NEEDLES:
+                        needles.pop(next(iter(needles)))
+                    needles[needle_lower] = entry
+                if _needle_scan(p, entry, needle_lower):
+                    out[p.stem] = p
+                save_cache(p, cache)
+            else:
+                if _needle_scan(p, {"offset": 0, "found": False}, needle_lower):
+                    out[p.stem] = p
     if lead_sid:
         direct = proj_dir / f"{lead_sid}.jsonl"
         if direct.is_file():
             out.setdefault(lead_sid, direct)
     return out
-

package/runtime/python/okstra_token_usage/cli.py

@@ -39,6 +39,14 @@ def main() -> int:
         action="store_true",
         help="Also print a one-line summary to stderr",
     )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help=(
+            "Disable the incremental session-scan cache and force a full "
+            "linear rescan of every session jsonl (correctness fallback)"
+        ),
+    )
     parser.add_argument(
         "--substitute-data",
         type=Path,
@@ -58,7 +66,8 @@ def main() -> int:
         print(f"team-state not found: {args.team_state}", file=sys.stderr)
         return 2
 
-    updated = collect(args.team_state, args.project_root)
+    updated = collect(args.team_state, args.project_root,
+                      incremental=not args.no_cache)
 
     if args.write:
         args.team_state.write_text(

package/runtime/python/okstra_token_usage/collect.py

@@ -86,7 +86,7 @@ def _aggregate_totals(items: list[dict]) -> dict:
     return aggregate
 
 
-def _run_window_suffix(team_state_path: Path) -> str | None:
+def run_artifact_suffix(team_state_path: Path) -> str | None:
     """``team-state-<task-type>-<seq>.json`` → ``<task-type>-<seq>``.
 
     이 접미사로 *같은 run* 의 run-manifest / status 를 정확히 짚는다. task 디렉토리
@@ -118,7 +118,7 @@ def _run_end_estimate(run_dir: Path, suffix: str) -> str | 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]:
+def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
     in-session lead 는 자기 run 을 사용자의 *세션 전체* jsonl 에 기록하므로,
@@ -128,7 +128,7 @@ def _resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     이 run 의 run-manifest createdAt, 종료 = team-state.runEndedAt → 이 run 의
     status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
     (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백."""
-    suffix = _run_window_suffix(team_state_path)
+    suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
@@ -137,37 +137,42 @@ def _resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     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>`
-    # convention if team-state did not record one. Matching downstream is
-    # case-insensitive so either casing works.
-    # Lead-written teamName lives at one of two paths depending on which
-    # version of the contract the run was authored under:
-    #   - nested:  state.team.teamName        (current documented schema)
-    #   - root:    state.teamName             (older convention; still common in
-    #                                          actual runs because the team
-    #                                          contract docs did not pin the
-    #                                          location until v0.24)
-    # Read both; whichever is non-empty wins. The fallback derives a short
-    # team name from task-id only and routinely mis-matches multi-segment
-    # task keys (e.g. `okstra-fontsninja-classifier-v2:DEV-9389:DEV-9389`),
-    # so it is a last resort.
-    state_team = (state.get("team") or {})
+def resolve_team_name(state: dict) -> str:
+    """team-state 에서 이 run 의 team name 을 해소한다.
+
+    Phase 3 TeamCreate 성공 시 lead 가 기록한 값을 우선한다. 기록 위치는 계약
+    버전에 따라 둘 중 하나다:
+      - nested:  state.team.teamName        (현재 문서화된 스키마)
+      - root:    state.teamName             (v0.24 이전 관행; 실 run 에 여전히 흔함)
+    둘 다 비어 있으면 `okstra-<task-id>` 관례로 폴백 — task-id 만 쓰므로
+    multi-segment task key 에서 빈번히 mis-match 하는 최후 수단이다.
+    """
+    state_team = state.get("team") or {}
     team_name = state_team.get("teamName") or state.get("teamName") or ""
     if not team_name:
+        task_key = state.get("taskKey", "")
         task_id = task_key.rsplit(":", 1)[-1] if task_key else ""
         team_name = f"okstra-{task_id}" if task_id else ""
+    return team_name
+
+
+def collect(team_state_path: Path, project_root: Path | None = None, *,
+            incremental: bool = True) -> dict:
+    # incremental: 세션 jsonl 스캔에 byte cursor 캐시 사용 (P6). 캐시는 윈도우
+    # 적용 전 이벤트를 저장하므로 결과는 전체 스캔과 동일 — False 는 캐시 경로를
+    # 완전히 우회하는 정확성 폴백(CLI --no-cache).
+    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", "")
+    team_name = resolve_team_name(state)
     lead_sid = (state.get("lead") or {}).get("sessionId")
 
     # 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
     # sessions.
-    claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
+    claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid,
+                                                incremental=incremental)
     by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
     # Team-tagged non-lead sessions that carry no agentName. These are almost
@@ -182,7 +187,8 @@ 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, since=run_since, until=run_until)
+        totals = claude_session_totals(path, since=run_since, until=run_until,
+                                       incremental=incremental)
         agent = totals.get("agentName")
         if agent:
             by_agent.setdefault(agent, []).append((sid, path, totals))
@@ -191,7 +197,8 @@ 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, since=run_since, until=run_until)
+        totals = claude_session_totals(lead_path, since=run_since, until=run_until,
+                                       incremental=incremental)
         state["leadUsage"] = usage_block(totals, source="claude-jsonl")
         state["leadUsage"]["sessionId"] = lead_sid
     else:

package/runtime/python/okstra_token_usage/cursor.py

@@ -0,0 +1,93 @@
+"""세션 jsonl 증분 스캔 캐시 — byte cursor + usage 이벤트 추출본 (P6).
+
+캐시에는 *윈도우 적용 전* 이벤트 추출본을 저장하고, since/until 윈도우는 매
+호출 시 이벤트 위에서 재평가한다. run 재시도로 윈도우가 좁아져도(until 이
+과거로 이동) 합계가 틀어지지 않는 이유다.
+
+캐시는 파생 데이터다: head-bytes 식별자 불일치(파일 교체)·truncate·손상 시
+조용히 폐기하고 전체 재스캔으로 폴백한다(fail-open). 쓰기는 tmp+os.replace
+원자적. 동시 collect 가 같은 캐시를 쓰면 last-writer-wins — 최악의 경우 다음
+호출이 일부 byte 를 다시 읽을 뿐 결과는 불변.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home
+
+CACHE_SCHEMA_VERSION = 1
+IDENTITY_PREFIX_BYTES = 256
+MAX_NEEDLES = 16
+
+
+def cache_path_for(jsonl_path: Path) -> Path:
+    """`$OKSTRA_HOME/cache/token-usage/<transcript-dir-name>/<session>.json`."""
+    return (okstra_home() / "cache" / "token-usage"
+            / jsonl_path.parent.name / f"{jsonl_path.stem}.json")
+
+
+def fresh_cache(identity: dict | None = None) -> dict:
+    return {
+        "schemaVersion": CACHE_SCHEMA_VERSION,
+        "identity": identity,
+        "usage": {"offset": 0, "agentName": None, "model": None, "events": []},
+        "needles": {},
+    }
+
+
+def _file_identity(jsonl_path: Path) -> dict | None:
+    try:
+        with jsonl_path.open("rb") as fh:
+            prefix = fh.read(IDENTITY_PREFIX_BYTES)
+    except OSError:
+        return None
+    return {"prefixLen": len(prefix), "sha256": hashlib.sha256(prefix).hexdigest()}
+
+
+def _identity_matches(jsonl_path: Path, identity: object) -> bool:
+    if not isinstance(identity, dict):
+        return False
+    want_len = identity.get("prefixLen") or 0
+    try:
+        with jsonl_path.open("rb") as fh:
+            prefix = fh.read(want_len)
+    except OSError:
+        return False
+    if len(prefix) != want_len:
+        return False  # 캐시 시점보다 짧아짐 → truncate/교체
+    return hashlib.sha256(prefix).hexdigest() == identity.get("sha256")
+
+
+def load_cache(jsonl_path: Path) -> dict:
+    """파일에 대응하는 캐시. 미스·손상·버전/식별자 불일치면 빈 캐시.
+
+    identity 는 이번 스캔 시점 기준으로 갱신해 둔다 — 첫 256B 미만이던 파일이
+    자란 경우 prefix 를 늘려 잡기 위함(append-only 라 기존 prefix 는 불변).
+    """
+    identity = _file_identity(jsonl_path)
+    p = cache_path_for(jsonl_path)
+    try:
+        cache = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return fresh_cache(identity)
+    if not isinstance(cache, dict) or cache.get("schemaVersion") != CACHE_SCHEMA_VERSION:
+        return fresh_cache(identity)
+    if not _identity_matches(jsonl_path, cache.get("identity")):
+        return fresh_cache(identity)
+    cache["identity"] = identity
+    return cache
+
+
+def save_cache(jsonl_path: Path, cache: dict) -> None:
+    """원자적 저장. 실패는 무시 — 캐시는 파생 데이터, 결과에 영향 없음."""
+    p = cache_path_for(jsonl_path)
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(cache, ensure_ascii=False, separators=(",", ":")))
+        os.replace(tmp, p)
+    except OSError:
+        pass

package/runtime/python/okstra_token_usage/paths.py

@@ -15,8 +15,35 @@ def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def claude_project_dir(cwd: Path) -> Path:
+def _floor_to_second(ts: str) -> datetime | None:
+    try:
+        moment = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return moment.replace(microsecond=0)
+
+
+def ts_in_window(ts: str, since: str | None, until: str | None) -> bool:
+    """ts 가 run 윈도우 [since, until] 안인지 — 초 단위로 절삭해 비교한다.
+
+    세션 jsonl 의 ts 는 밀리초(`…00.123Z`), 윈도우 끝점(run-manifest createdAt /
+    status mtime)은 초(`…00Z`) 정밀도라 문자열 비교는 '.' < 'Z' 탓에 경계 초의
+    레코드를 잘못 떨군다. 파싱 불가한 끝점은 개방 경계로, 파싱 불가한 ts 는
+    포함으로 취급한다(빈 ts 를 포함시키는 기존 동작과 동일 원칙).
+    """
+    moment = _floor_to_second(ts)
+    if moment is None:
+        return True
+    lo = _floor_to_second(since) if since else None
+    hi = _floor_to_second(until) if until else None
+    return not ((lo is not None and moment < lo) or (hi is not None and moment > hi))
+
+
+def claude_project_dir(cwd: Path, projects_root: Path | None = None) -> Path:
     # Claude Code encodes cwd by replacing "/" with "-" (leading slash → leading "-").
+    # `projects_root` 는 테스트/진단용 주입 시드 — 기본은 실제 ~/.claude/projects.
     encoded = "-" + str(cwd).strip("/").replace("/", "-")
-    return CLAUDE_PROJECTS / encoded
+    return (projects_root or CLAUDE_PROJECTS) / encoded
 

package/runtime/python/okstra_token_usage/pricing.py

@@ -4,9 +4,9 @@ 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-opus-4-*`, `claude-sonnet-4-*`, `claude-haiku-4-5-*`,
-    `claude-3-5-sonnet-*`, `claude-3-5-haiku-*`, `claude-3-opus-*`,
-    `claude-3-haiku-*`.
+  * Anthropic — `claude-fable-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*`.
   * Google / Gemini — `gemini-2.5-pro*`, `gemini-2.5-flash*`, `gemini-2.0-flash*`.
 
@@ -45,7 +45,11 @@ CLAUDE_PRICING = {
     "3-sonnet":   (3.0, 3.75, 0.30, 15.0),     # legacy 3 Sonnet
     "3-haiku":    (0.25, 0.30, 0.03, 1.25),    # Haiku 3
 
+    # Claude Fable 5 (tier above Opus).
+    "fable-5":    (10.0, 12.5, 1.0, 50.0),     # Fable 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)
     "opus-4-6":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.6 (legacy; pricing matches 4.7 per Anthropic)
     "sonnet-4-6": (3.0, 3.75, 0.30, 15.0),     # Sonnet 4.6 (cache prices derived from ratios)