okstra 0.64.1 → 0.66.0

package/docs/superpowers/plans/2026-06-10-p6-token-usage-incremental.md

@@ -0,0 +1,1029 @@
+# P6 Token usage collector 증분화 구현 plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `okstra-token-usage` collector 가 run 마다 세션 jsonl 전체를 재스캔하지 않고, 세션별 byte offset cursor + usage 이벤트 추출본 캐시로 새로 추가된 byte 만 읽게 한다 ([performance-improvement-plan-v2.md §P6](../../kr/performance-improvement-plan-v2.md)).
+
+**Architecture:** 캐시에는 **윈도우 적용 전** 압축 이벤트 추출본을 저장하고, `since`/`until` 윈도우 필터는 매 호출 시 이벤트 위에서 재평가한다. run 재시도로 윈도우가 좁아져도(`until` 이 `utc_now()` → 과거의 `runEndedAt` 으로 이동) 합계가 틀어지지 않는다. 캐시는 파생 데이터다 — 식별자 불일치·truncate·손상 시 조용히 폐기하고 전체 재스캔으로 폴백한다(fail-open). 스캔 구현은 증분/전체 공용 한 벌만 둔다(전체 스캔 = 빈 커서로 증분 스캔, DRY).
+
+**Tech Stack:** Python 3 표준 라이브러리만 (json, hashlib, os, pathlib). 신규 외부 의존성 없음.
+
+---
+
+## 배경과 정확성 제약
+
+- 현재 [collect.py:185](../../../scripts/okstra_token_usage/collect.py) 는 run 마다 모든 매칭 세션에 대해 [claude.py 의 `claude_session_totals`](../../../scripts/okstra_token_usage/claude.py) 를 호출해 jsonl 전체를 선형 재파싱한다.
+- [claude.py 의 `find_claude_team_sessions`](../../../scripts/okstra_token_usage/claude.py) 는 프로젝트 transcript 디렉토리의 **모든** `*.jsonl` 을 team needle 로 전체 스캔한다 (needle 미발견 파일은 매번 EOF 까지).
+- run 윈도우의 `until` 은 진행 중엔 `utc_now()`, 종료 후엔 `runEndedAt`/status mtime 으로 해소되므로 **호출 간 뒤로 이동할 수 있다** ([collect.py `_resolve_run_window`](../../../scripts/okstra_token_usage/collect.py)). 윈도우 적용 후 누계를 캐시하면 이 케이스에서 과대 집계가 된다 → 윈도우 적용 전 이벤트를 캐시해야 한다.
+- 여러 subagent 세션 aggregate(`_aggregate_totals`)·재dispatch suffix 매칭은 세션별 totals 위에서 동작하므로, 세션별 totals 가 동일하면 aggregate 도 동일하다.
+- Phase 7 final-report placeholder substitution([validators/validate-run.py](../../../validators/validate-run.py) → `collect()`)이 이 결과를 소비한다 — 정확성이 성능보다 우선.
+
+## 캐시 저장소 설계
+
+- 위치: `$OKSTRA_HOME/cache/token-usage/<transcript-dir-name>/<session-id>.json` (`OKSTRA_HOME` 미설정 시 `~/.okstra`). 세션 파일은 머신 전역(`~/.claude/projects/...`)이므로 캐시도 프로젝트 `.okstra/` 가 아닌 okstra home 에 둔다. 테스트는 기존 [tests/conftest.py](../../../tests/conftest.py) 의 `OKSTRA_HOME` 격리를 그대로 탄다.
+- 파일 스키마 (`schemaVersion: 1`):
+
+```json
+{
+  "schemaVersion": 1,
+  "identity": {"prefixLen": 256, "sha256": "<head-bytes hash>"},
+  "usage": {
+    "offset": 12345,
+    "agentName": "codex-worker",
+    "model": "claude-sonnet-4-6",
+    "events": [{"t": "2026-06-10T01:00:00.123Z", "i": 100, "o": 20, "c": 5, "c5": 5, "r": 9000, "u": 2}]
+  },
+  "needles": {"\"teamname\":\"okstra-…\"": {"offset": 12345, "found": false}}
+}
+```
+
+- 이벤트 키: `t`=timestamp, `i`/`o`=input/output, `c`=cache_creation 합, `c5`/`c1`=ephemeral 5m/1h, `r`=cache_read, `u`=tool_use 수. 0/부재 필드는 생략. ts 만 있는 레코드는 `{"t": …}` 로 저장(윈도우별 first/last ts 산출에 필요), 아무 기여도 없는 레코드는 저장하지 않는다.
+- 무효화 가드: (a) head 256 byte sha256 식별자 불일치 → 폐기, (b) `offset > 현재 파일 크기`(truncate) → usage 상태 리셋, (c) `schemaVersion` 불일치·JSON 손상 → 폐기. 모두 전체 재스캔 폴백.
+- 미완결 tail(개행 없는 마지막 라인)은 이번 호출 totals 에는 반영하되 커서를 전진시키지 않는다(transient) — 다음 호출에서 완결본으로 다시 읽으므로 이중 집계도 누락도 없다.
+- 쓰기는 tmp + `os.replace` 원자적, 실패는 무시(파생 데이터). 동시 collect 두 개가 같은 캐시에 쓰면 last-writer-wins — 최악의 경우 다음 호출이 일부 byte 를 다시 읽을 뿐 결과는 불변.
+- needle map 은 파일당 최대 16개(오래된 순 제거) — run 마다 team 이름이 달라 무한 증식하는 것 방지.
+
+## Non-goals (YAGNI)
+
+- codex/gemini 세션 증분화: 파일이 작고 윈도우 글롭으로 1개만 선택되므로 제외.
+- 캐시 GC: 세션 jsonl 이 삭제돼도 캐시 파일이 남지만 수 KB 수준 — 후속 과제로 미룬다.
+- `iter_jsonl` 의 다른 호출자(codex.py) 변경 없음.
+
+---
+
+### Task 0: 변경 전 기준값 스냅샷 (실제 jsonl 고정 fixture)
+
+DB/IO 변경 검증 규칙: mock 이 아닌 **실제 세션 jsonl** 로 전후 동일성을 증명한다. 현재 세션이 계속 append 되므로 파일을 먼저 /tmp 에 복사해 고정한다.
+
+**Files:** 코드 변경 없음. 산출물: `/tmp/p6-fixtures/*.jsonl`, `/tmp/p6-legacy-snapshot.json`, `/tmp/p6-snapshot.py`
+
+- [x] **Step 1: 실제 jsonl 3개를 고정 fixture 로 복사**
+
+```bash
+mkdir -p /tmp/p6-fixtures
+ls -S "$HOME/.claude/projects/-Volumes-Workspaces-workspace-projects-Okstra/"*.jsonl | head -3 | while read f; do cp "$f" /tmp/p6-fixtures/; done
+ls -lh /tmp/p6-fixtures/
+```
+
+- [x] **Step 2: 변경 전 코드로 기준값 저장 (전체 + 윈도우 변형 3종)**
+
+`/tmp/p6-snapshot.py` 로 저장 후 실행 (변경 후 검증에서 같은 스크립트를 재사용한다):
+
+```python
+import json, sys
+from datetime import datetime, timedelta
+from pathlib import Path
+sys.path.insert(0, "scripts")
+from okstra_token_usage.claude import claude_session_totals
+
+def windows(full):
+    s, e = full["startedAt"], full["endedAt"]
+    a = datetime.fromisoformat(s.replace("Z", "+00:00"))
+    b = datetime.fromisoformat(e.replace("Z", "+00:00"))
+    mid = (a + (b - a) / 2).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return {"first_half": {"until": mid}, "second_half": {"since": mid},
+            "mid_only": {"since": (a + (b - a) / 4).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                          "until": (a + 3 * (b - a) / 4).strftime("%Y-%m-%dT%H:%M:%SZ")}}
+
+kwargs = {}
+if len(sys.argv) > 1 and sys.argv[1] == "--incremental":
+    kwargs["incremental"] = True
+out = {}
+for f in sorted(Path("/tmp/p6-fixtures").glob("*.jsonl")):
+    full = claude_session_totals(f, **kwargs)
+    out[f.name] = {"full": full}
+    for name, w in windows(full).items():
+        out[f.name][name] = claude_session_totals(f, **w, **kwargs)
+json.dump(out, sys.stdout, indent=1, sort_keys=True, ensure_ascii=False)
+```
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+python3 /tmp/p6-snapshot.py > /tmp/p6-legacy-snapshot.json
+python3 -c "import json; d=json.load(open('/tmp/p6-legacy-snapshot.json')); print(len(d), 'files,', sum(v['full']['totalTokens'] for v in d.values()), 'total tokens')"
+```
+
+Expected: 파일 3개, totalTokens 합이 0 이 아닌 값.
+
+### Task 1: `okstra_home()` 단일 참조점 추출
+
+`OKSTRA_HOME` 해석이 [seeding.py `_okstra_home`](../../../scripts/okstra_ctl/seeding.py) 과 [run_context.py `_okstra_home`](../../../scripts/okstra_ctl/run_context.py) 에 중복. 새 캐시 모듈이 세 번째 호출자가 되므로 `okstra_project/dirs.py` 로 추출하고 기존 두 곳을 경유시킨다 (`okstra_ctl` → `okstra_project` import 는 기존 선례 다수).
+
+**Files:**
+- Modify: `scripts/okstra_project/dirs.py`
+- Modify: `scripts/okstra_ctl/seeding.py` (`_okstra_home` 제거)
+- Modify: `scripts/okstra_ctl/run_context.py` (`_okstra_home` 제거)
+- Test: `tests/test_okstra_token_usage_incremental.py` (신규 — 이 plan 의 모든 신규 테스트가 들어갈 파일)
+
+- [x] **Step 1: 실패하는 테스트 작성**
+
+```python
+"""P6: token usage collector 증분화 — byte cursor 캐시의 정확성 가드."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+
+def test_okstra_home_honors_env_isolation(monkeypatch, tmp_path):
+    """OKSTRA_HOME 단일 참조점: env override > ~/.okstra 기본값."""
+    from okstra_project.dirs import okstra_home
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "custom"))
+    assert okstra_home() == tmp_path / "custom"
+    monkeypatch.setenv("OKSTRA_HOME", "  ")
+    assert okstra_home() == Path.home() / ".okstra"
+```
+
+- [x] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v`
+Expected: FAIL — `ImportError: cannot import name 'okstra_home'`
+
+- [x] **Step 3: `dirs.py` 에 구현**
+
+```python
+import os  # 파일 상단 from __future__ 다음
+
+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"
+```
+
+- [x] **Step 4: seeding.py / run_context.py 의 로컬 `_okstra_home` 정의 삭제, `from okstra_project.dirs import okstra_home` 으로 대체하고 호출부 이름 변경**
+
+`grep -n "_okstra_home" scripts/okstra_ctl/*.py` 로 호출부 전수 확인 후 일괄 치환. docstring 의 `_okstra_home()` 언급도 갱신.
+
+- [x] **Step 5: 테스트 + 기존 suite 통과 확인 후 commit**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: PASS (기존 테스트 회귀 없음)
+
+```bash
+git add scripts/okstra_project/dirs.py scripts/okstra_ctl/seeding.py scripts/okstra_ctl/run_context.py tests/test_okstra_token_usage_incremental.py
+git commit -m "refactor(project-dirs): okstra_home() 단일 참조점 추출"
+```
+
+### Task 2: `cursor.py` — 세션별 캐시 load/save + 식별자 가드
+
+**Files:**
+- Create: `scripts/okstra_token_usage/cursor.py`
+- Test: `tests/test_okstra_token_usage_incremental.py`
+
+- [x] **Step 1: 실패하는 테스트 작성**
+
+```python
+def _write(p: Path, text: str) -> None:
+    p.write_bytes(text.encode("utf-8"))
+
+
+def test_cursor_cache_roundtrip_and_identity_guard(monkeypatch, tmp_path):
+    from okstra_token_usage import cursor
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    jsonl = tmp_path / "proj" / "sess.jsonl"
+    jsonl.parent.mkdir(parents=True)
+    _write(jsonl, '{"a":1}\n')
+
+    cache = cursor.load_cache(jsonl)            # 미스 → 빈 캐시
+    assert cache["usage"]["offset"] == 0
+    cache["usage"]["offset"] = 8
+    cursor.save_cache(jsonl, cache)
+
+    again = cursor.load_cache(jsonl)            # 히트
+    assert again["usage"]["offset"] == 8
+
+    _write(jsonl, '{"b":2}\n')                  # 같은 길이, 다른 내용 → 식별자 불일치
+    assert cursor.load_cache(jsonl)["usage"]["offset"] == 0
+
+
+def test_cursor_cache_corrupt_or_wrong_version_falls_back(monkeypatch, tmp_path):
+    from okstra_token_usage import cursor
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    jsonl = tmp_path / "proj" / "sess.jsonl"
+    jsonl.parent.mkdir(parents=True)
+    _write(jsonl, '{"a":1}\n')
+
+    cp = cursor.cache_path_for(jsonl)
+    cp.parent.mkdir(parents=True)
+    cp.write_text("not-json{")
+    assert cursor.load_cache(jsonl)["usage"]["offset"] == 0
+
+    cp.write_text(json.dumps({"schemaVersion": 999}))
+    assert cursor.load_cache(jsonl)["usage"]["offset"] == 0
+```
+
+- [x] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v -k cursor`
+Expected: FAIL — `ModuleNotFoundError: okstra_token_usage.cursor`
+
+- [x] **Step 3: `cursor.py` 구현**
+
+```python
+"""세션 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) -> 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
+```
+
+- [x] **Step 4: 통과 확인 후 commit**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v -k cursor`
+Expected: PASS
+
+```bash
+git add scripts/okstra_token_usage/cursor.py tests/test_okstra_token_usage_incremental.py
+git commit -m "feat(token-usage): 세션 캐시 cursor 모듈 — byte offset + 식별자 가드"
+```
+
+### Task 3: `claude_session_totals` 증분화 — 스캔 구현 단일화
+
+기존 누적 루프를 (a) 레코드→이벤트 추출, (b) byte cursor 전진 스캔, (c) 이벤트→윈도우 totals 세 함수로 분해한다. 전체 스캔은 "빈 커서로 증분 스캔" — 구현은 한 벌(DRY). 미완결 tail 라인은 transient 처리(집계엔 반영, 커서는 미전진).
+
+**Files:**
+- Modify: `scripts/okstra_token_usage/claude.py`
+- Test: `tests/test_okstra_token_usage_incremental.py`
+
+- [x] **Step 1: 실패하는 테스트 작성** (parity / 증분 / 윈도우 축소 / tail / truncate)
+
+```python
+REC_TPL = ('{{"type":"assistant","timestamp":"{ts}","message":{{"model":"claude-opus-4-7",'
+           '"usage":{{"input_tokens":{i},"output_tokens":{o},'
+           '"cache_creation_input_tokens":{c},"cache_read_input_tokens":{r}}},'
+           '"content":[{{"type":"tool_use"}},{{"type":"text"}}]}}}}')
+
+
+def _rec(ts, i=10, o=1, c=0, r=0):
+    return REC_TPL.format(ts=ts, i=i, o=o, c=c, r=r)
+
+
+def test_incremental_cold_equals_legacy_full_scan(monkeypatch, tmp_path):
+    """캐시 없는 첫 호출(incremental=True) == 비증분 전체 스캔. ts 없는 레코드,
+    cache_creation 5m/1h 분해, ts-only 레코드, 미완결 tail 까지 포함."""
+    from okstra_token_usage.claude import claude_session_totals
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    p = tmp_path / "s.jsonl"
+    lines = [
+        '{"agentName":"codex-worker","type":"system","timestamp":"2026-06-10T01:00:00Z"}',
+        _rec("2026-06-10T01:01:00Z", i=100, o=10, c=50, r=9000),
+        '{"type":"assistant","message":{"usage":{"input_tokens":7,"output_tokens":3,'
+        '"cache_creation_input_tokens":40,"cache_read_input_tokens":0,'
+        '"cache_creation":{"ephemeral_5m_input_tokens":30,"ephemeral_1h_input_tokens":10}}}}',
+        '{"type":"user","timestamp":"2026-06-10T02:00:00Z"}',
+    ]
+    p.write_bytes(("\n".join(lines) + "\n" + _rec("2026-06-10T03:00:00Z", i=5, o=5)).encode())  # tail 개행 없음
+
+    legacy = claude_session_totals(p)
+    cold = claude_session_totals(p, incremental=True)
+    assert cold == legacy
+    assert cold["inputTokens"] == 112 and cold["outputTokens"] == 18
+    assert cold["cacheCreationTokens"] == 90
+    assert cold["cacheCreation5mTokens"] == 80 and cold["cacheCreation1hTokens"] == 10
+    assert cold["cacheReadTokens"] == 9000
+    assert cold["toolUses"] == 2          # tool_use 블록 2개 (본문 1 + tail 1)
+    assert cold["agentName"] == "codex-worker"
+    assert cold["startedAt"] == "2026-06-10T01:00:00Z"
+    assert cold["endedAt"] == "2026-06-10T03:00:00Z"
+
+
+def test_incremental_warm_reads_only_new_bytes(monkeypatch, tmp_path):
+    """warm 호출이 캐시 구간을 재읽지 않음을 증명: 첫 스캔 후 이미 읽은 구간을
+    같은 길이의 쓰레기로 바꿔도(식별자 prefix 밖) 결과가 캐시에서 나온다."""
+    from okstra_token_usage.claude import claude_session_totals
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    p = tmp_path / "s.jsonl"
+    head = '{"f":"' + "x" * 300 + '"}\n'      # 식별자 prefix(256B) 채움
+    body = _rec("2026-06-10T01:00:00Z", i=100, o=10) + "\n"
+    p.write_bytes((head + body).encode())
+    first = claude_session_totals(p, incremental=True)
+    assert first["inputTokens"] == 100
+
+    garbage = b"#" * len(body.encode())       # body 구간만 파괴 (prefix 는 보존)
+    with p.open("r+b") as fh:
+        fh.seek(len(head.encode()))
+        fh.write(garbage)
+    with p.open("ab") as fh:
+        fh.write((_rec("2026-06-10T02:00:00Z", i=7, o=3) + "\n").encode())
+
+    warm = claude_session_totals(p, incremental=True)
+    assert warm["inputTokens"] == 107         # 캐시 100 + 신규 7 — body 재읽기 없음
+    fresh = claude_session_totals(p)          # 비증분은 파괴된 body 를 못 읽음
+    assert fresh["inputTokens"] == 7
+
+
+def test_incremental_window_shrink_matches_fresh_scan(monkeypatch, tmp_path):
+    """P6 핵심 정확성: 진행 중(until=now) 집계 후 run 종료로 until 이 과거로
+    이동해도, warm 결과 == 캐시 없는 전체 스캔 결과."""
+    from okstra_token_usage.claude import claude_session_totals
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    p = tmp_path / "s.jsonl"
+    p.write_bytes(("\n".join([
+        _rec("2026-06-10T01:00:00Z", i=100, o=10),
+        _rec("2026-06-10T02:00:00Z", i=200, o=20),
+        _rec("2026-06-10T03:00:00Z", i=400, o=40),
+    ]) + "\n").encode())
+
+    wide = claude_session_totals(p, since="2026-06-10T00:00:00Z",
+                                 until="2026-06-10T04:00:00Z", incremental=True)
+    assert wide["inputTokens"] == 700
+    narrow = claude_session_totals(p, since="2026-06-10T00:00:00Z",
+                                   until="2026-06-10T02:30:00Z", incremental=True)
+    fresh = claude_session_totals(p, since="2026-06-10T00:00:00Z",
+                                  until="2026-06-10T02:30:00Z")
+    assert narrow == fresh
+    assert narrow["inputTokens"] == 300       # 03:00 레코드 제외
+
+
+def test_incremental_tail_not_double_counted(monkeypatch, tmp_path):
+    """미완결 tail 은 transient: 이번 호출 집계에는 들어가되 커서는 미전진.
+    이후 완결되면 그때 1회만 커밋된다."""
+    from okstra_token_usage.claude import claude_session_totals
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    p = tmp_path / "s.jsonl"
+    p.write_bytes((_rec("2026-06-10T01:00:00Z", i=10, o=1) + "\n"
+                   + _rec("2026-06-10T02:00:00Z", i=5, o=2)).encode())  # 개행 없음
+    assert claude_session_totals(p, incremental=True)["inputTokens"] == 15
+    with p.open("ab") as fh:
+        fh.write(("\n" + _rec("2026-06-10T03:00:00Z", i=100, o=9) + "\n").encode())
+    out = claude_session_totals(p, incremental=True)
+    assert out["inputTokens"] == 115          # 5 가 두 번 세어지면 120
+    assert out == claude_session_totals(p)
+
+
+def test_incremental_truncate_triggers_full_rescan(monkeypatch, tmp_path):
+    from okstra_token_usage.claude import claude_session_totals
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    p = tmp_path / "s.jsonl"
+    p.write_bytes(("\n".join(_rec(f"2026-06-10T0{n}:00:00Z", i=10 * n, o=n)
+                             for n in (1, 2, 3)) + "\n").encode())
+    assert claude_session_totals(p, incremental=True)["inputTokens"] == 60
+    # 교체: 내용이 전혀 다른 더 짧은 파일
+    p.write_bytes((_rec("2026-06-10T09:00:00Z", i=8, o=1) + "\n").encode())
+    assert claude_session_totals(p, incremental=True)["inputTokens"] == 8
+```
+
+- [x] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v -k incremental`
+Expected: FAIL — `claude_session_totals() got an unexpected keyword argument 'incremental'`
+
+- [x] **Step 3: `claude.py` 재구성**
+
+기존 `claude_session_totals` 본문을 다음 세 함수 + 진입점으로 교체한다 (docstring 의 윈도우/보수성 설명은 유지·이전):
+
+```python
+"""Claude Code transcript collectors."""
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
+from .paths import claude_project_dir
+
+
+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 _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 = tail_model = None
+    try:
+        with jsonl_path.open("rb") as fh:
+            fh.seek(offset)
+            while True:
+                raw = fh.readline()
+                if not raw:
+                    break
+                complete = raw.endswith(b"\n")
+                rec = None
+                stripped = raw.strip()
+                if stripped:
+                    try:
+                        rec = json.loads(stripped.decode("utf-8"))
+                    except (UnicodeDecodeError, json.JSONDecodeError):
+                        rec = None
+                if not isinstance(rec, dict):
+                    rec = None
+                ev = _event_from_record(rec) if rec else None
+                if complete:
+                    offset = fh.tell()
+                    if rec:
+                        if agent_name is None and rec.get("agentName"):
+                            agent_name = rec["agentName"]
+                        if (model is None and rec.get("type") == "assistant"
+                                and isinstance(rec.get("message"), dict)
+                                and rec["message"].get("model")):
+                            model = rec["message"]["model"]
+                    if ev:
+                        events.append(ev)
+                else:
+                    if rec:
+                        if rec.get("agentName"):
+                            tail_agent = rec["agentName"]
+                        if (rec.get("type") == "assistant"
+                                and isinstance(rec.get("message"), dict)
+                                and rec["message"].get("model")):
+                            tail_model = rec["message"]["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, model,
+                        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
+    first_ts: str | None = None
+    last_ts: str | None = None
+    for ev in events:
+        ts = ev.get("t")
+        if ts and ((since and ts < since) or (until and ts > until)):
+            continue
+        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
+            if last_ts is None or ts > last_ts:
+                last_ts = ts
+    duration_ms = 0
+    if first_ts and last_ts:
+        try:
+            a = datetime.fromisoformat(first_ts.replace("Z", "+00:00"))
+            b = datetime.fromisoformat(last_ts.replace("Z", "+00:00"))
+            duration_ms = max(0, int((b - a).total_seconds() * 1000))
+        except ValueError:
+            duration_ms = 0
+    # '처리 토큰' total 에서 cache_read 는 제외한다. (기존 주석 유지 — 중복
+    # 카운트 부풀림 방지, cacheReadTokens 로 별도 노출, 비용은 0.1x 별도 반영)
+    total = input_t + output_t + cache_create_t
+    return {
+        "totalTokens": total,
+        "inputTokens": input_t,
+        "outputTokens": output_t,
+        "cacheCreationTokens": cache_create_t,
+        "cacheCreation5mTokens": cache_create_5m_t,
+        "cacheCreation1hTokens": cache_create_1h_t,
+        "cacheReadTokens": cache_read_t,
+        "toolUses": tool_uses,
+        "durationMs": duration_ms,
+        "agentName": agent_name,
+        "model": model,
+        "startedAt": first_ts,
+        "endedAt": last_ts,
+    }
+
+
+def claude_session_totals(
+    jsonl_path: Path, *, since: str | None = None, until: str | None = None,
+    incremental: bool = False,
+) -> dict:
+    """(기존 docstring 윈도우 설명 유지) + incremental=True 면 $OKSTRA_HOME
+    캐시의 byte cursor 이후만 읽는다. 캐시에는 윈도우 적용 전 이벤트가 저장
+    되므로 호출마다 다른 since/until 에도 결과는 전체 스캔과 동일하다.
+    """
+    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)
+```
+
+`iter_jsonl` import 는 claude.py 에서 제거된다(codex.py 는 계속 사용).
+
+- [x] **Step 4: 신규 + 기존 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py tests/test_okstra_token_usage_collect.py -v`
+Expected: PASS — 특히 기존 `test_claude_session_totals_window_filter`, `test_total_tokens_excludes_cache_read` 가 무수정 통과(parity 증거).
+
+- [x] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_token_usage/claude.py tests/test_okstra_token_usage_incremental.py
+git commit -m "feat(token-usage): claude_session_totals 증분 스캔 — 이벤트 추출본 캐시로 윈도우 재평가"
+```
+
+### Task 4: `find_claude_team_sessions` needle 스캔 증분화
+
+needle 미발견 파일은 매 collect 마다 EOF 까지 재스캔된다 — 파일별 needle cursor 로 신규 byte 만 검사한다. 구현은 한 벌: 비증분 = 일회용 entry 로 같은 스캐너 호출.
+
+**Files:**
+- Modify: `scripts/okstra_token_usage/claude.py`
+- Test: `tests/test_okstra_token_usage_incremental.py`
+
+- [x] **Step 1: 실패하는 테스트 작성**
+
+```python
+def test_team_needle_scan_is_incremental(monkeypatch, tmp_path):
+    """미발견 파일에 나중에 team 태그가 append 되면 warm 스캔이 발견해야 하고,
+    이미 읽은 구간은 재읽지 않아야 한다(읽은 구간 파괴로 증명)."""
+    from okstra_token_usage.claude import find_claude_team_sessions
+    from okstra_token_usage import paths as paths_mod
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    claude_root = tmp_path / "claude-home" / "projects"
+    cwd = tmp_path / "project"
+    encoded = "-" + str(cwd).strip("/").replace("/", "-")
+    proj_dir = claude_root / encoded
+    proj_dir.mkdir(parents=True)
+    monkeypatch.setattr(paths_mod, "CLAUDE_PROJECTS", claude_root)
+
+    pad = '{"f":"' + "x" * 300 + '"}\n'       # 식별자 prefix 밖에서 파괴 가능하게
+    other = '{"type":"user","text":"no team here"}\n'
+    (proj_dir / "sess-a.jsonl").write_bytes((pad + other).encode())
+
+    assert find_claude_team_sessions(cwd, "okstra-T1", incremental=True) == {}
+
+    with (proj_dir / "sess-a.jsonl").open("r+b") as fh:   # 읽은 구간 파괴
+        fh.seek(len(pad.encode()))
+        fh.write(b"#" * len(other.encode()))
+    with (proj_dir / "sess-a.jsonl").open("ab") as fh:    # 신규 구간에 태그 append
+        fh.write(b'{"team":{"teamName":"okstra-T1"}}\n')
+
+    found = find_claude_team_sessions(cwd, "okstra-T1", incremental=True)
+    assert "sess-a" in found
+    # found=True 캐시: 이후 호출은 파일을 읽지 않고도 매칭 유지
+    assert "sess-a" in find_claude_team_sessions(cwd, "okstra-T1", incremental=True)
+
+
+def test_team_needle_cache_caps_needle_count(monkeypatch, tmp_path):
+    from okstra_token_usage import cursor
+    from okstra_token_usage.claude import find_claude_team_sessions
+    from okstra_token_usage import paths as paths_mod
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    claude_root = tmp_path / "claude-home" / "projects"
+    cwd = tmp_path / "project"
+    encoded = "-" + str(cwd).strip("/").replace("/", "-")
+    proj_dir = claude_root / encoded
+    proj_dir.mkdir(parents=True)
+    monkeypatch.setattr(paths_mod, "CLAUDE_PROJECTS", claude_root)
+    p = proj_dir / "sess-a.jsonl"
+    p.write_bytes(b'{"type":"user"}\n')
+    for n in range(cursor.MAX_NEEDLES + 4):
+        find_claude_team_sessions(cwd, f"team-{n}", incremental=True)
+    assert len(cursor.load_cache(p)["needles"]) <= cursor.MAX_NEEDLES
+```
+
+- [x] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v -k needle`
+Expected: FAIL — `find_claude_team_sessions() got an unexpected keyword argument 'incremental'`
+
+- [x] **Step 3: `claude.py` 에 구현**
+
+```python
+def _needle_scan(jsonl_path: Path, entry: dict, needle_lower: str) -> bool:
+    """entry({'offset','found'}) 를 전진시키며 needle 존재 여부 반환.
+
+    미완결 tail 라인도 검사한다(부분 문자열 매칭은 라인 완결 후에도 유효하므로
+    found=True 는 그대로 커밋해도 안전). 단 offset 은 완결 라인까지만 전진.
+    """
+    if entry.get("found"):
+        return True
+    offset = entry.get("offset", 0) or 0
+    try:
+        size = jsonl_path.stat().st_size
+    except OSError:
+        return False
+    if offset > size:
+        offset = 0
+    try:
+        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, *,
+    incremental: bool = False,
+) -> dict[str, Path]:
+    """(기존 docstring 유지) + incremental=True 면 파일별 needle cursor 이후의
+    신규 byte 만 검사한다. needle(=team 이름)은 run 마다 다르므로 파일당
+    MAX_NEEDLES 개까지 오래된 순으로 보존한다.
+    """
+    proj_dir = claude_project_dir(cwd)
+    out: dict[str, Path] = {}
+    if not proj_dir.is_dir():
+        return out
+    needle_lower = f'"teamname":"{(team_name or "").lower()}"'
+    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
+```
+
+비고: `team_name` 이 빈 값이면 기존 코드도 매칭 0건이었으므로 루프 자체를 건너뛴다(결과 동일, 무의미한 전체 읽기 제거). 기존 `except OSError: continue` 의미는 `_needle_scan` 내부 OSError → False 로 보존.
+
+- [x] **Step 4: 통과 확인 후 commit**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py tests/test_okstra_token_usage_collect.py -v`
+Expected: PASS
+
+```bash
+git add scripts/okstra_token_usage/claude.py tests/test_okstra_token_usage_incremental.py
+git commit -m "feat(token-usage): team needle 스캔 증분화 — 파일별 needle cursor"
+```
+
+### Task 5: `collect()`/CLI 배선 — 증분 기본 on, `--no-cache` 킬스위치
+
+**Files:**
+- Modify: `scripts/okstra_token_usage/collect.py` (함수 시그니처 + 3개 호출부)
+- Modify: `scripts/okstra_token_usage/cli.py` (`--no-cache` 플래그)
+- Test: `tests/test_okstra_token_usage_incremental.py`
+
+- [x] **Step 1: 실패하는 테스트 작성** (collect e2e — cold/warm/no-cache 3-way 동일성; 기존 e2e fixture 패턴 재사용)
+
+```python
+def _stand_up_project(tmp_path, monkeypatch):
+    """기존 collect e2e 와 같은 fixture 패턴 (실제 파일 IO, mock 없음)."""
+    from okstra_token_usage import paths as paths_mod
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "okstra-home"))
+    project_root = tmp_path / "project"
+    run_dir = project_root / ".okstra" / "tasks" / "TG" / "TID" / "runs" / "phase"
+    run_dir.mkdir(parents=True)
+    claude_root = tmp_path / "claude-home" / "projects"
+    encoded = "-" + str(project_root).strip("/").replace("/", "-")
+    proj_dir = claude_root / encoded
+    proj_dir.mkdir(parents=True)
+    monkeypatch.setattr(paths_mod, "CLAUDE_PROJECTS", claude_root)
+    return project_root, run_dir, proj_dir
+
+
+def _strip_volatile(state: dict) -> dict:
+    """collectedAt 류 타임스탬프 제거 후 비교용 사본."""
+    s = json.loads(json.dumps(state))
+    s.get("usageSummary", {}).pop("collectedAt", None)
+    for blk in [s.get("leadUsage") or {}] + [w.get("usage") or {} for w in s.get("workers", [])]:
+        blk.pop("collectedAt", None)
+    return s
+
+
+def test_collect_cold_warm_nocache_identical(monkeypatch, tmp_path):
+    """재실행(2회 collect)·재dispatch aggregate 가 캐시 유무와 무관하게 동일."""
+    import importlib
+    collect_mod = importlib.import_module("okstra_token_usage.collect")
+    project_root, run_dir, proj_dir = _stand_up_project(tmp_path, monkeypatch)
+    team = "okstra-TG:TID:tid"
+
+    def session(sid, agent, ts0, ts1, i, o):
+        lines = [
+            json.dumps({"sessionId": sid, "agentName": agent,
+                        "team": {"teamName": team}, "timestamp": ts0,
+                        "type": "system"}, separators=(",", ":")),
+            json.dumps({"sessionId": sid, "type": "assistant", "timestamp": ts1,
+                        "message": {"model": "claude-sonnet-4-6",
+                                    "usage": {"input_tokens": i, "output_tokens": o,
+                                              "cache_creation_input_tokens": 0,
+                                              "cache_read_input_tokens": 0}}},
+                       separators=(",", ":")),
+        ]
+        (proj_dir / f"{sid}.jsonl").write_text("\n".join(lines) + "\n")
+
+    session("lead-sid", "lead", "2026-06-10T09:00:00Z", "2026-06-10T09:01:00Z", 10, 20)
+    session("codex-1", "codex-worker", "2026-06-10T10:00:00Z", "2026-06-10T10:05:00Z", 100, 200)
+    session("codex-2", "codex-worker-002", "2026-06-10T10:10:00Z", "2026-06-10T10:20:00Z", 300, 400)
+
+    ts_path = run_dir / "state" / "team-state-error-analysis-001.json"
+    ts_path.parent.mkdir(parents=True)
+    ts_path.write_text(json.dumps({
+        "schemaVersion": "1.0", "taskKey": "TG:TID:tid",
+        "runDirectoryPath": str(run_dir.relative_to(project_root)),
+        "team": {"teamName": team},
+        "runEndedAt": "2026-06-10T11:00:00Z",
+        "lead": {"sessionId": "lead-sid", "model": "opus"},
+        "workers": [{"workerId": "codex", "agent": "codex", "model": "gpt-5.5"}],
+    }))
+    (run_dir / "manifests").mkdir()
+    (run_dir / "manifests" / "run-manifest-error-analysis-001.json").write_text(
+        json.dumps({"createdAt": "2026-06-10T08:00:00Z"}))
+
+    cold = collect_mod.collect(ts_path, project_root=project_root)            # 캐시 생성
+    warm = collect_mod.collect(ts_path, project_root=project_root)            # 캐시 사용
+    nocache = collect_mod.collect(ts_path, project_root=project_root, incremental=False)
+    assert _strip_volatile(cold) == _strip_volatile(warm) == _strip_volatile(nocache)
+    assert cold["usageSummary"]["workerTotalTokens"] == 1000                  # aggregate 보존
+    assert cold["workers"][0]["usage"]["additionalSessionIds"] == ["codex-2"]
+```
+
+- [x] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_token_usage_incremental.py -v -k collect_cold`
+Expected: FAIL — `collect() got an unexpected keyword argument 'incremental'`
+
+- [x] **Step 3: `collect.py` 배선**
+
+```python
+def collect(team_state_path: Path, project_root: Path | None = None, *,
+            incremental: bool = True) -> dict:
+```
+
+내부 3개 호출부에 전달:
+- `find_claude_team_sessions(cwd, team_name, lead_sid, incremental=incremental)`
+- worker 루프: `claude_session_totals(path, since=run_since, until=run_until, incremental=incremental)`
+- lead: `claude_session_totals(lead_path, since=run_since, until=run_until, incremental=incremental)`
+
+- [x] **Step 4: `cli.py` 에 킬스위치 추가**
+
+```python
+    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)"
+        ),
+    )
+```
+
+호출부: `updated = collect(args.team_state, args.project_root, incremental=not args.no_cache)`
+
+- [x] **Step 5: 전체 테스트 통과 확인 후 commit**
+
+Run: `python3 -m pytest tests/ -q && python3 -m pytest scripts/okstra_token_usage/ -q`
+Expected: PASS (기존 collect e2e 4건은 incremental 기본 on 으로 통과해야 한다 — 그 자체가 회귀 가드)
+
+```bash
+git add scripts/okstra_token_usage/collect.py scripts/okstra_token_usage/cli.py tests/test_okstra_token_usage_incremental.py
+git commit -m "feat(token-usage): collect/CLI 증분 스캔 기본 활성화 + --no-cache 킬스위치"
+```
+
+### Task 6: 실측 검증 — Task 0 기준값과 diff + 타이밍
+
+mock 아님: Task 0 에서 고정한 **실제 세션 jsonl** 에 대해 변경 후 코드의 (a) 비증분, (b) 증분 cold, (c) 증분 warm 결과가 기준값과 모두 동일해야 한다.
+
+- [x] **Step 1: 전후 동일성 diff (3-way)**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+python3 /tmp/p6-snapshot.py > /tmp/p6-new-nocache.json
+OKSTRA_HOME=/tmp/p6-cache python3 /tmp/p6-snapshot.py --incremental > /tmp/p6-new-cold.json
+OKSTRA_HOME=/tmp/p6-cache python3 /tmp/p6-snapshot.py --incremental > /tmp/p6-new-warm.json
+diff /tmp/p6-legacy-snapshot.json /tmp/p6-new-nocache.json && \
+diff /tmp/p6-legacy-snapshot.json /tmp/p6-new-cold.json && \
+diff /tmp/p6-legacy-snapshot.json /tmp/p6-new-warm.json && echo "PARITY OK"
+```
+
+Expected: `PARITY OK` (diff 출력 없음). 다르면 **여기서 멈추고 원인 규명** — 캐시 설계 수정 전까지 다음 Task 진행 금지.
+
+- [x] **Step 2: warm 성능 측정 기록**
+
+```bash
+OKSTRA_HOME=/tmp/p6-cache-t python3 -c "
+import sys, time
+sys.path.insert(0, 'scripts')
+from pathlib import Path
+from okstra_token_usage.claude import claude_session_totals
+f = max(Path('/tmp/p6-fixtures').glob('*.jsonl'), key=lambda p: p.stat().st_size)
+t0 = time.perf_counter(); claude_session_totals(f, incremental=True); t1 = time.perf_counter()
+t2 = time.perf_counter(); claude_session_totals(f, incremental=True); t3 = time.perf_counter()
+print(f'{f.name}: cold={t1-t0:.3f}s warm={t3-t2:.3f}s ({(t1-t0)/(t3-t2):.0f}x)')"
+```
+
+Expected: warm 이 cold 보다 유의미하게 빠름 (수치를 CHANGES.md 항목에 기록).
+
+### Task 7: 문서/빌드 마무리
+
+**Files:**
+- Modify: `docs/kr/performance-improvement-plan-v2.md` (§구현 plan 링크 — P6 항목을 이 문서로)
+- Modify: `docs/kr/architecture.md` (storage 절에 캐시 경로 1줄), `docs/project-structure-overview.md` (`cursor.py` 항목), `docs/kr/cli.md` (`--no-cache`)
+- Modify: `CHANGES.md` (사용자 영향 라인 포함)
+
+- [x] **Step 1: v2 문서 링크 갱신**
+
+`- P2 / P3 / P4 / P5 / P6: 미작성` → P6 를 분리해 `- P6: docs/superpowers/plans/2026-06-10-p6-token-usage-incremental.md` 추가, 나머지는 미작성 유지.
+
+- [x] **Step 2: architecture/overview/cli 문서에 캐시 경로·플래그 반영**
+
+- [x] **Step 3: CHANGES.md 항목 추가** (`사용자 영향:` 라인 + Task 6 측정 수치)
+
+- [x] **Step 4: critique mode — 전체 diff 리뷰, 신규 식별자 grep 일관성 점검(`okstra_home`, `cursor`, `incremental`, `--no-cache`, `cache/token-usage`), build + 전체 테스트**
+
+```bash
+grep -rn "okstra_home\|token-usage.*cache\|no-cache" scripts/ docs/ --include="*.py" --include="*.md" | grep -v __pycache__ | grep -v runtime/
+npm run build && python3 -m pytest tests/ -q && node bin/okstra --version
+```
+
+- [x] **Step 5: Commit**
+
+```bash
+git add docs/ CHANGES.md
+git commit -m "docs(token-usage): P6 증분화 plan/architecture/CHANGES 반영"
+```
+
+---
+
+## 검증·집행 지점 (선언 ≠ 집행 구분)
+
+| 계약 | 집행 위치 |
+|---|---|
+| 윈도우 축소(재실행) 시 합계 불변 | `test_incremental_window_shrink_matches_fresh_scan` |
+| cold == legacy 전체 스캔 | `test_incremental_cold_equals_legacy_full_scan` + Task 6 실측 diff |
+| warm 이 기존 구간을 재읽지 않음 | `test_incremental_warm_reads_only_new_bytes` (읽은 구간 파괴 증명) |
+| tail 이중 집계 금지 | `test_incremental_tail_not_double_counted` |
+| truncate/교체 폴백 | `test_incremental_truncate_triggers_full_rescan` + cursor 식별자 테스트 |
+| 다중 세션 aggregate 보존 | `test_collect_cold_warm_nocache_identical` + 기존 collect e2e 무수정 통과 |
+| 실제 jsonl 전후 동일성 | Task 0 스냅샷 ↔ Task 6 diff (실파일, mock 없음) |