okstra 0.107.2 → 0.109.0

package/runtime/python/okstra_token_usage/collect.py

@@ -131,6 +131,53 @@ 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 _project_root_from_team_state(team_state_path: Path) -> Path | None:
+    """team-state path(`<root>/.okstra/tasks/.../state/team-state-*.json`)에서
+    프로젝트 루트(`.okstra` 를 담은 디렉토리)를 되짚는다. 못 찾으면 None."""
+    for parent in team_state_path.resolve().parents:
+        if parent.name == OKSTRA_RELATIVE.name:
+            return parent.parent
+    return None
+
+
+def _session_first_ts(jsonl_path: Path) -> str | None:
+    """세션 jsonl 의 최소 timestamp — reconstruct_needles_from_workers 와 동일한
+    top-level `timestamp` 규칙. 파일 부재/파싱 실패 레코드는 건너뛴다."""
+    first_ts: str | None = None
+    try:
+        with jsonl_path.open(encoding="utf-8") as fh:
+            for raw in fh:
+                try:
+                    rec = json.loads(raw)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    continue
+                ts = rec.get("timestamp")
+                if ts and (first_ts is None or ts < first_ts):
+                    first_ts = ts
+    except OSError:
+        return None
+    return first_ts
+
+
+def _earliest_lead_session_ts(state: dict, team_state_path: Path) -> str | None:
+    """`state["leadSessionIds"]` 각 lead 세션 jsonl 첫 ts 중 최소값. 부재하거나
+    어느 세션에서도 ts 를 못 찾으면 None. proj_dir 은 team-state path 에서 되짚은
+    프로젝트 루트에 `claude_project_dir` 규칙을 적용해 해소한다."""
+    lead_ids = [sid for sid in (state.get("leadSessionIds") or []) if sid]
+    if not lead_ids:
+        return None
+    project_root = _project_root_from_team_state(team_state_path)
+    if project_root is None:
+        return None
+    proj_dir = claude_project_dir(project_root)
+    earliest: str | None = None
+    for sid in lead_ids:
+        ts = _session_first_ts(proj_dir / f"{sid}.jsonl")
+        if ts and (earliest is None or ts < earliest):
+            earliest = ts
+    return earliest
+
+
 def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
@@ -140,12 +187,21 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     $416 / 3h). 토큰 집계를 이 윈도우로 스코핑해 그 run 분만 센다. 시작 =
     이 run 의 run-manifest createdAt, 종료 = team-state.runEndedAt → 이 run 의
     status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
-    (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백."""
+    (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백.
+
+    시작 완화: run-manifest createdAt 이 이 run 의 실제 lead/worker 세션보다
+    늦게 찍히면(관측: dev-9902 — createdAt 11:43Z 가 05:34Z 시작 세션보다 늦음)
+    since 가 앞선 세션을 잘라낸다. Task 3 이 기록한 `leadSessionIds[]` 세션의
+    첫 ts 최소값이 createdAt 보다 앞서면 그 값으로 since 를 앞당긴다.
+    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변."""
     suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
     since = _run_manifest_created_at(run_dir, suffix)
+    earliest = _earliest_lead_session_ts(state, team_state_path)
+    if earliest and (since is None or earliest < since):
+        since = earliest
     until = state.get("runEndedAt") or _run_end_estimate(run_dir, suffix) or utc_now()
     return since, until
 
@@ -214,6 +270,55 @@ def resolve_team_name(state: dict) -> str:
     return team_name
 
 
+def resolve_team_needles(state: dict) -> list[str]:
+    """이 run 에 속한 harness teamName(`session-<leadSid-prefix>`) 전체.
+
+    lead 재발급마다 세대가 갈리므로 team-state.teamName 단일값으로는 후속
+    세대 워커를 놓친다. 축1 이 기록한 `observedTeamNames[]` 를 정본으로 쓰고,
+    수동 정정으로 teamName 에 직접 박힌 `session-*` 값도 흡수한다.
+    audit label(`okstra-<task-key>`) 은 harness needle 이 아니므로 제외한다.
+    """
+    needles: set[str] = set()
+    for name in state.get("observedTeamNames") or []:
+        if isinstance(name, str) and name.startswith("session-"):
+            needles.add(name)
+    label = resolve_team_name(state)
+    if label.startswith("session-"):
+        needles.add(label)
+    return sorted(needles)
+
+
+def resolve_team_needles_with_source(
+    state: dict, cwd, since, until, projects_root=None,
+) -> tuple[list[str], str]:
+    """세 소비처(collect + 두 validator) 공통 needle 조립 규칙.
+
+    needle 은 `resolve_team_needles(state)` 만으로 조립한다 — 축1 의
+    `observedTeamNames[]` 세대들 + `session-*` 형태의 수동 정정 라벨. audit
+    label(`okstra-<task-key>`)은 needle 로 절대 쓰지 않는다: 하네스 jsonl 은
+    `session-*` teamName 만 실어(okstra-lead-contract.md), 라벨은 여러 run 이
+    공유하는 task-key 파생값이라 needle 로 쓰면 같은 task-key 의 다른 run 세션을
+    끌어와 cross-run mis-attribution 을 일으킨다(spec §2.1 이 배제하는 바로 그
+    실패). `resolve_team_name` 은 표시 라벨(`usageSummary.teamName`) 전용.
+
+    `resolve_team_needles` 가 비면(observedTeamNames 미기록 legacy run) 축4 의
+    `reconstruct_needles_from_workers` 로 run window 안 워커 jsonl 의 `session-*`
+    teamName 을 best-effort 복구하고 `reconstructed-from-workers` provenance 를
+    돌려준다 — window 로 스코핑되므로 타 run 을 안전하게 배제한다. 그마저 비면
+    `none`. 반환한 source 는 각 소비처가 자기 관례대로 표면화한다
+    (collect → usageSummary.needleSource).
+    """
+    needles = resolve_team_needles(state)
+    if needles:
+        return needles, "observed-team-names"
+    reconstructed = reconstruct_needles_from_workers(
+        cwd, since, until, projects_root=projects_root
+    )
+    if reconstructed:
+        return reconstructed, "reconstructed-from-workers"
+    return [], "none"
+
+
 def _resolve_project_path(project_root: Path, raw_path: str) -> Path | None:
     if not raw_path:
         return None
@@ -407,7 +512,8 @@ def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
             _aggregate_totals(totals),
             session_paths,
         )
-    _populate_usage_summary(state, team_name=resolve_team_name(state), sessions_found=0)
+    _populate_usage_summary(state, team_name=resolve_team_name(state),
+                            sessions_found=0, needle_source="none")
     return state
 
 
@@ -418,6 +524,7 @@ def _populate_usage_summary(
     sessions_found: int,
     unattributed_sessions: list[str] | None = None,
     unattributed_usage: dict[str, Any] | None = None,
+    needle_source: str = "observed-team-names",
 ) -> None:
     workers = state.get("workers", [])
     lead = state.get("leadUsage") or {}
@@ -462,6 +569,7 @@ def _populate_usage_summary(
         },
         "collectedAt": utc_now(),
         "teamName": team_name,
+        "needleSource": needle_source,
         "sessionsFound": sessions_found,
         "unmatchedModels": sorted(set(unmatched_models)),
         "unattributedTeamSessions": unattributed_sessions or [],
@@ -490,9 +598,24 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
 
     # 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,
+    # sessions. needle 집합(observedTeamNames 여러 세대)으로 스캔하고, 없으면
+    # 워커 jsonl 에서 복구한다 — team_name 은 표시 라벨 전용.
+    team_needles, needle_source = resolve_team_needles_with_source(
+        state, cwd, run_since, run_until
+    )
+    claude_sessions = find_claude_team_sessions(cwd, team_needles, lead_sid,
                                                 incremental=incremental)
+    # Task 9: 축1 기록(observed-team-names)으로 발견한 세션들의 min first-ts 로
+    # run_since 를 완화한다. session-* needle 은 세션 고유라 발견 세션은 이 run
+    # 것이므로 안전. 불확실한 reconstruct/none source 는 완화하지 않는다(오귀속 방지).
+    if needle_source == "observed-team-names":
+        found_earliest = None
+        for path in claude_sessions.values():
+            ts = _session_first_ts(path)
+            if ts and (found_earliest is None or ts < found_earliest):
+                found_earliest = ts
+        if found_earliest and (run_since is None or found_earliest < run_since):
+            run_since = found_earliest
     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
@@ -623,6 +746,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
         sessions_found=len(claude_sessions),
         unattributed_sessions=unattributed_sessions,
         unattributed_usage=unattributed_usage,
+        needle_source=needle_source,
     )
     return state
 
@@ -637,3 +761,38 @@ 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}")
+
+
+def reconstruct_needles_from_workers(cwd, since, until, projects_root=None) -> list[str]:
+    """observedTeamNames 가 없는 과거 run 의 best-effort 복구: run window 안
+    워커 jsonl(agentName 존재)이 달고 있는 session-* teamName variant 집합.
+    """
+    from okstra_token_usage.paths import claude_project_dir, ts_in_window
+    proj_dir = claude_project_dir(cwd, projects_root)
+    found: set[str] = set()
+    if not proj_dir.is_dir():
+        return []
+    for p in proj_dir.glob("*.jsonl"):
+        agent = team = first_ts = None
+        try:
+            with p.open(encoding="utf-8") as fh:
+                for raw in fh:
+                    try:
+                        rec = json.loads(raw)
+                    except (json.JSONDecodeError, UnicodeDecodeError):
+                        continue
+                    if agent is None and rec.get("agentName"):
+                        agent = rec["agentName"]
+                    if team is None and rec.get("teamName"):
+                        team = rec["teamName"]
+                    ts = rec.get("timestamp")
+                    if ts and (first_ts is None or ts < first_ts):
+                        first_ts = ts
+        except OSError:
+            continue
+        # 의도적 divergence: 이 untrusted best-effort 경로에서는 ts 를 못 구한
+        # 워커를 제외한다 (ts_in_window 의 파싱 실패→포함 정책과 반대).
+        if agent and team and str(team).startswith("session-") \
+                and first_ts and ts_in_window(first_ts, since, until):
+            found.add(team)
+    return sorted(found)

package/runtime/python/okstra_vendor/__init__.py

@@ -11,6 +11,9 @@ Currently vendored:
   - markupsafe 3.0.3 (BSD-3-Clause) — jinja2 dependency. C extension
     (`_speedups.c` / `_speedups.pyi`) is stripped; the pure-python
     `_native` fallback is used at import time.
+  - networkx (BSD-3-Clause) — graph model + community detection for okstra-graphify.
+  - graphify 0.4.23 (MIT) — knowledge-graph pipeline for okstra-graphify. tree-sitter
+    native bindings are NOT vendored; okstra-graphify only indexes .okstra/ docs.
 
 Source provenance and licenses are preserved verbatim under each
 sub-package. Do not edit vendored files in place — re-vendor from PyPI
@@ -22,8 +25,21 @@ re-routing, those would either fail (no system install) or resolve to
 unrelated user-installed copies. We register the vendored copies in
 `sys.modules` under their canonical top-level names so jinja2's internal
 imports find them deterministically.
+
+networkx and graphify need a stronger mechanism than jinja2/markupsafe.
+Both use *self-referential* absolute imports (networkx's `__init__` does
+`from networkx.lazy_imports import ...`; graphify submodules do `import
+networkx`). Those fire while the package body is still executing, before a
+post-hoc `sys.modules.setdefault` could run — so on a machine that also has
+these libraries pip-installed globally, the self-import would resolve to the
+global copy and cache it under the canonical name. `_vendor_as_toplevel`
+registers the module in `sys.modules` under its canonical name *before*
+executing its body, so every self-referential import resolves back into the
+vendored tree deterministically. networkx is loaded before graphify because
+graphify's cluster/export/serve modules import networkx at module-load time.
 """
 
+import importlib.util as _importlib_util
 import sys as _sys
 
 # Register markupsafe alias BEFORE importing jinja2 — jinja2's __init__
@@ -35,3 +51,28 @@ _sys.modules.setdefault("markupsafe", _markupsafe)
 
 from . import jinja2 as _jinja2  # noqa: E402
 _sys.modules.setdefault("jinja2", _jinja2)
+
+
+def _vendor_as_toplevel(top_name, vendored_name):
+    """Load a vendored sub-package under its canonical top-level name.
+
+    Registers the module in ``sys.modules`` before executing its body so
+    that self-referential absolute imports inside the package resolve to the
+    vendored copy rather than a globally pip-installed one.
+    """
+    if top_name in _sys.modules:
+        return _sys.modules[top_name]
+    vendored_spec = _importlib_util.find_spec(vendored_name)
+    top_spec = _importlib_util.spec_from_file_location(
+        top_name,
+        vendored_spec.origin,
+        submodule_search_locations=list(vendored_spec.submodule_search_locations),
+    )
+    module = _importlib_util.module_from_spec(top_spec)
+    _sys.modules[top_name] = module
+    top_spec.loader.exec_module(module)
+    return module
+
+
+_networkx = _vendor_as_toplevel("networkx", __name__ + ".networkx")
+_graphify = _vendor_as_toplevel("graphify", __name__ + ".graphify")

package/runtime/python/okstra_vendor/graphify/.vendored-version

@@ -0,0 +1 @@
+0.4.23

package/runtime/python/okstra_vendor/graphify/__init__.py

@@ -0,0 +1,28 @@
+"""graphify - extract · build · cluster · analyze · report."""
+
+
+def __getattr__(name):
+    # Lazy imports so `graphify install` works before heavy deps are in place.
+    _map = {
+        "extract": ("graphify.extract", "extract"),
+        "collect_files": ("graphify.extract", "collect_files"),
+        "build_from_json": ("graphify.build", "build_from_json"),
+        "cluster": ("graphify.cluster", "cluster"),
+        "score_all": ("graphify.cluster", "score_all"),
+        "cohesion_score": ("graphify.cluster", "cohesion_score"),
+        "god_nodes": ("graphify.analyze", "god_nodes"),
+        "surprising_connections": ("graphify.analyze", "surprising_connections"),
+        "suggest_questions": ("graphify.analyze", "suggest_questions"),
+        "generate": ("graphify.report", "generate"),
+        "to_json": ("graphify.export", "to_json"),
+        "to_html": ("graphify.export", "to_html"),
+        "to_svg": ("graphify.export", "to_svg"),
+        "to_canvas": ("graphify.export", "to_canvas"),
+        "to_wiki": ("graphify.wiki", "to_wiki"),
+    }
+    if name in _map:
+        import importlib
+        mod_name, attr = _map[name]
+        mod = importlib.import_module(mod_name)
+        return getattr(mod, attr)
+    raise AttributeError(f"module 'graphify' has no attribute {name!r}")