okstra 0.1.0

package/runtime/python/okstra_project/resolver.py

@@ -0,0 +1,126 @@
+"""PROJECT_ROOT 해석과 project.json 갱신 로직."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+PROJECT_JSON_RELATIVE = Path(".project-docs/okstra/project.json")
+
+
+class ResolverError(Exception):
+    """PROJECT_ROOT 해석 또는 project.json 충돌 실패."""
+
+
+def project_json_path(project_root: Path) -> Path:
+    return Path(project_root) / PROJECT_JSON_RELATIVE
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _ancestor_with_project_json(start: Path) -> Optional[Path]:
+    """start 부터 위로 올라가며 `.project-docs/okstra/project.json` 보유 디렉터리를 찾는다."""
+    cur = Path(start).resolve()
+    while True:
+        if (cur / PROJECT_JSON_RELATIVE).is_file():
+            return cur
+        if cur.parent == cur:
+            return None
+        cur = cur.parent
+
+
+def _git_toplevel(cwd: Path) -> Optional[Path]:
+    try:
+        rc = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(cwd), capture_output=True, text=True, check=False,
+        )
+    except (OSError, FileNotFoundError):
+        return None
+    if rc.returncode != 0:
+        return None
+    line = rc.stdout.strip()
+    if not line:
+        return None
+    p = Path(line)
+    return p if p.is_dir() else None
+
+
+def resolve_project_root(*, explicit_root: str = "",
+                          cwd: Optional[str] = None) -> Path:
+    """PROJECT_ROOT 를 해석한다.
+
+    우선순위:
+      1. explicit_root (CLI `--project-root`) — 비어있지 않으면 그대로 절대화.
+      2. cwd 또는 그 조상 중 `.project-docs/okstra/project.json` 보유 디렉터리.
+      3. cwd 의 `git rev-parse --show-toplevel`.
+    셋 다 실패하면 ResolverError.
+    """
+    if explicit_root:
+        p = Path(explicit_root).expanduser().resolve()
+        if not p.is_dir():
+            raise ResolverError(
+                f"--project-root path does not exist or is not a directory: {p}")
+        return p
+    cwd_path = Path(cwd or os.getcwd()).resolve()
+    ancestor = _ancestor_with_project_json(cwd_path)
+    if ancestor is not None:
+        return ancestor
+    git_top = _git_toplevel(cwd_path)
+    if git_top is not None:
+        return git_top.resolve()
+    raise ResolverError(
+        "PROJECT_ROOT 를 해석할 수 없습니다. "
+        "--project-root 를 명시하거나, 프로젝트 루트(또는 그 하위)에서 실행하거나, "
+        "git 작업 트리 안에서 실행해 주십시오.")
+
+
+def upsert_project_json(project_root: Path, project_id: str, *,
+                         now: Optional[str] = None) -> dict:
+    """project.json 을 읽거나 새로 만든다.
+
+    - 파일이 있으면 projectId 가 인자와 일치해야 한다(불일치 시 ResolverError).
+      projectRoot 는 현재 절대경로로 갱신, updatedAt 도 갱신.
+    - 파일이 없으면 디렉터리를 만들고 4-필드 JSON 을 작성한다.
+    반환값은 결과 dict.
+    """
+    if not project_id:
+        raise ResolverError("project_id is required for upsert_project_json")
+    target = project_json_path(project_root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    when = now or _now_iso()
+    abs_root = str(Path(project_root).resolve())
+    if target.is_file():
+        try:
+            data = json.loads(target.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ResolverError(
+                f"project.json 을 읽을 수 없습니다: {target} ({exc})") from exc
+        existing_id = str(data.get("projectId") or "")
+        if existing_id and existing_id != project_id:
+            raise ResolverError(
+                f"projectId 불일치: project.json={existing_id!r}, "
+                f"인자={project_id!r}. "
+                f"동일 PROJECT_ROOT 에서는 하나의 projectId 만 사용할 수 있습니다.")
+        result = {
+            "projectId": project_id,
+            "projectRoot": abs_root,
+            "createdAt": str(data.get("createdAt") or when),
+            "updatedAt": when,
+        }
+    else:
+        result = {
+            "projectId": project_id,
+            "projectRoot": abs_root,
+            "createdAt": when,
+            "updatedAt": when,
+        }
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
+    os.replace(tmp, target)
+    return result

package/runtime/python/okstra_project/state.py

@@ -0,0 +1,170 @@
+"""Read-only state accessors over okstra's on-disk authority files.
+
+Skills, okstra.sh, and okstra-ctl all read the same files through this module
+so identity / discovery values are derived from disk on every call instead of
+being passed via process environment. This keeps concurrent claude-code skill
+invocations isolated — each call reads the authoritative state at the moment
+it runs and never sees stale snapshots inherited from a parent process.
+
+권위 파일 매핑:
+  - <PROJECT_ROOT>/.project-docs/okstra/project.json
+      -> {projectId, projectRoot, ...}
+  - <PROJECT_ROOT>/.project-docs/okstra/discovery/task-catalog.json
+      -> tasks[]: 각 task 의 stable identity 와 phase pointer
+  - <PROJECT_ROOT>/.project-docs/okstra/discovery/latest-task.json
+      -> 가장 최근에 prepare/run 된 task 의 포인터
+  - <task-root>/task-manifest.json
+      -> 한 task 의 manifest (workflow.* phase 정보 포함)
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+DISCOVERY_RELATIVE = Path(".project-docs/okstra/discovery")
+TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
+LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
+TASKS_RELATIVE = Path(".project-docs/okstra/tasks")
+
+
+class StateError(Exception):
+    """state file 읽기/파싱 실패 — 호출자가 surface 해야 할 오류."""
+
+
+def _load_json(path: Path) -> Optional[dict]:
+    if not path.is_file():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise StateError(f"failed to parse {path}: {exc}") from exc
+
+
+def slugify(value: str) -> str:
+    """task-group / task-id segment 를 디스크 경로용 slug 로 정규화한다.
+
+    소문자화 + 알파넘 외 문자 → '-' 로 collapse.
+    okstra.sh 의 path-resolve.sh slug 규칙과 일치해야 한다.
+    """
+    value = (value or "").lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value).strip("-")
+    return value
+
+
+def read_task_catalog(project_root: Path) -> list[dict]:
+    """project-level task-catalog.json 을 list[dict] 로 돌려준다.
+
+    파일이 없으면 빈 리스트(아직 task 가 prepare 되지 않은 신규 프로젝트).
+    파싱 실패 시 StateError.
+    """
+    catalog = _load_json(Path(project_root) / TASK_CATALOG_RELATIVE)
+    if not isinstance(catalog, dict):
+        return []
+    tasks = catalog.get("tasks")
+    return [t for t in tasks if isinstance(t, dict)] if isinstance(tasks, list) else []
+
+
+def read_latest_task(project_root: Path) -> Optional[dict]:
+    """latest-task.json 을 dict 로. 파일 없으면 None."""
+    return _load_json(Path(project_root) / LATEST_TASK_RELATIVE)
+
+
+def read_task_manifest(task_root: Path) -> Optional[dict]:
+    """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None."""
+    return _load_json(Path(task_root) / "task-manifest.json")
+
+
+def parse_task_key(task_key: str) -> tuple[str, str, str]:
+    """`project-id:task-group:task-id` 를 3-tuple 로 분해.
+
+    형식 불일치 시 StateError.
+    """
+    parts = (task_key or "").split(":")
+    if len(parts) != 3 or not all(parts):
+        raise StateError(
+            f"invalid task-key: {task_key!r} (expected project-id:task-group:task-id)")
+    return parts[0], parts[1], parts[2]
+
+
+def find_task_root(project_root: Path, task_key: str) -> Optional[Path]:
+    """task-key 로 task root 디렉터리를 해석한다.
+
+    해석 우선순위:
+      1. task-catalog.json 의 같은 taskKey 항목의 taskRootPath
+      2. <PROJECT_ROOT>/.project-docs/okstra/tasks/<slug-group>/<slug-id>/
+
+    어느 쪽도 디렉터리로 존재하지 않으면 None.
+    """
+    project_root = Path(project_root)
+    _, task_group, task_id = parse_task_key(task_key)
+    requested_ci = task_key.lower()
+
+    for entry in read_task_catalog(project_root):
+        entry_key = entry.get("taskKey") or ""
+        if not isinstance(entry_key, str) or entry_key.lower() != requested_ci:
+            continue
+        rel = entry.get("taskRootPath") or entry.get("taskRoot") or ""
+        if isinstance(rel, str) and rel:
+            abs_path = project_root / rel if not Path(rel).is_absolute() else Path(rel)
+            if abs_path.is_dir():
+                return abs_path
+
+    slug_path = project_root / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
+    if slug_path.is_dir():
+        return slug_path
+    return None
+
+
+def list_project_tasks(project_root: Path) -> list[dict]:
+    """skill UI 에 보여줄 task 후보 목록을 돌려준다.
+
+    각 항목은 task-catalog.json 의 entry 그대로 + 디스크 존재 여부 확인.
+    존재하지 않는 task root 는 skip(stale catalog 항목)한다.
+    """
+    project_root = Path(project_root)
+    out = []
+    for entry in read_task_catalog(project_root):
+        entry_key = entry.get("taskKey") or ""
+        if not isinstance(entry_key, str) or not entry_key:
+            continue
+        root = find_task_root(project_root, entry_key)
+        if root is None:
+            continue
+        out.append({**entry, "_resolvedTaskRoot": str(root)})
+    return out
+
+
+def resolve_task_identity(project_root: Path, task_key: str) -> dict:
+    """task-key 한 줄로 manifest + 경로를 한 번에 반환.
+
+    skill / okstra.sh / okstra-ctl 모두가 이 함수를 호출해 같은 dict 를 받는다.
+    StateError: task root 또는 manifest 없음.
+    """
+    task_root = find_task_root(project_root, task_key)
+    if task_root is None:
+        raise StateError(f"task root not found for {task_key!r}")
+    manifest = read_task_manifest(task_root)
+    if manifest is None:
+        raise StateError(f"task-manifest.json missing under {task_root}")
+    workflow = manifest.get("workflow") or {}
+    if not isinstance(workflow, dict):
+        workflow = {}
+    project_id, task_group, task_id = parse_task_key(task_key)
+    return {
+        "projectId": project_id,
+        "projectRoot": str(project_root),
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "taskKey": task_key,
+        "taskRoot": str(task_root),
+        "taskType": manifest.get("taskType") or "",
+        "currentPhase": workflow.get("currentPhase") or "",
+        "currentPhaseState": workflow.get("currentPhaseState") or "",
+        "nextRecommendedPhase": workflow.get("nextRecommendedPhase") or "",
+        "lastCompletedPhase": workflow.get("lastCompletedPhase") or "",
+        "awaitingApproval": bool(workflow.get("awaitingApproval", False)),
+        "taskBriefPath": manifest.get("taskBriefPath") or "",
+        "manifest": manifest,
+    }

package/runtime/python/okstra_token_usage/__init__.py

@@ -0,0 +1,26 @@
+"""okstra token usage collector — package form of the legacy okstra-token-usage.py script."""
+from __future__ import annotations
+
+from .blocks import na_block, usage_block
+from .claude import claude_session_totals, find_claude_team_sessions
+from .codex import codex_session_total, find_codex_session
+from .collect import collect
+from .gemini import find_gemini_session, gemini_session_total
+from .jsonl_io import iter_jsonl
+from .paths import (
+    CLAUDE_PROJECTS,
+    CODEX_SESSIONS,
+    GEMINI_TMP,
+    claude_project_dir,
+    utc_now,
+)
+from .pricing import (
+    CLAUDE_PRICING,
+    CODEX_PRICING,
+    GEMINI_PRICING,
+    claude_billable_equivalent,
+    claude_cost_usd,
+    codex_cost_usd,
+    gemini_cost_usd,
+)
+from .report import substitute_final_report

package/runtime/python/okstra_token_usage/blocks.py

@@ -0,0 +1,62 @@
+"""Per-source usage block constructors (consumed by collect())."""
+from __future__ import annotations
+
+from .paths import utc_now
+from .pricing import (
+    claude_billable_equivalent,
+    claude_cost_usd,
+    codex_cost_usd,
+    gemini_cost_usd,
+)
+
+
+def usage_block(totals: dict, source: str, note: str | None = None) -> dict:
+    block = {
+        "totalTokens": totals.get("totalTokens", 0) or 0,
+        "inputTokens": totals.get("inputTokens", 0) or 0,
+        "outputTokens": totals.get("outputTokens", 0) or 0,
+        "toolUses": totals.get("toolUses", 0) or 0,
+        "durationMs": totals.get("durationMs", 0) or 0,
+        "source": source,
+        "collectedAt": utc_now(),
+    }
+    for key in ("cacheCreationTokens", "cacheReadTokens", "cachedInputTokens",
+                "reasoningOutputTokens", "cachedTokens", "thoughtsTokens", "toolTokens"):
+        if totals.get(key):
+            block[key] = totals[key]
+
+    # Billable-equivalent + cost.
+    if source == "claude-jsonl":
+        be = claude_billable_equivalent(
+            totals.get("inputTokens", 0) or 0,
+            totals.get("cacheCreationTokens", 0) or 0,
+            totals.get("cacheReadTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+        block["billableEquivalentTokens"] = be
+        cost = claude_cost_usd(
+            totals.get("model"),
+            totals.get("inputTokens", 0) or 0,
+            totals.get("cacheCreationTokens", 0) or 0,
+            totals.get("cacheReadTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+        if cost is not None:
+            block["estimatedCostUsd"] = cost
+        if totals.get("model"):
+            block["model"] = totals["model"]
+    if note:
+        block["note"] = note
+    return block
+
+
+def na_block(reason: str) -> dict:
+    return {
+        "totalTokens": 0,
+        "toolUses": 0,
+        "durationMs": 0,
+        "source": "unavailable",
+        "collectedAt": utc_now(),
+        "note": reason,
+    }
+

package/runtime/python/okstra_token_usage/claude.py

@@ -0,0 +1,97 @@
+"""Claude Code transcript collectors."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from .jsonl_io import iter_jsonl
+from .paths import claude_project_dir
+
+
+def claude_session_totals(jsonl_path: Path) -> dict:
+    """Return totals + agentName + assistant model + time window for a Claude session jsonl."""
+    input_t = output_t = cache_create_t = cache_read_t = 0
+    tool_uses = 0
+    agent_name: str | None = None
+    model: str | None = None
+    first_ts: str | None = None
+    last_ts: str | None = None
+    started_at: str | None = None
+    ended_at: 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 {}
+        usage = msg.get("usage")
+        if usage:
+            input_t += usage.get("input_tokens", 0) or 0
+            output_t += usage.get("output_tokens", 0) or 0
+            cache_create_t += usage.get("cache_creation_input_tokens", 0) or 0
+            cache_read_t += usage.get("cache_read_input_tokens", 0) or 0
+        if rec.get("type") == "assistant":
+            if model is None and msg.get("model"):
+                model = msg["model"]
+            for block in (msg.get("content") or []):
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    tool_uses += 1
+        ts = rec.get("timestamp") or (msg.get("timestamp") if isinstance(msg, dict) else None)
+        if ts:
+            if first_ts is None or ts < first_ts:
+                first_ts = ts
+            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 = input_t + output_t + cache_create_t + cache_read_t
+    return {
+        "totalTokens": total,
+        "inputTokens": input_t,
+        "outputTokens": output_t,
+        "cacheCreationTokens": cache_create_t,
+        "cacheReadTokens": cache_read_t,
+        "toolUses": tool_uses,
+        "durationMs": duration_ms,
+        "agentName": agent_name,
+        "model": model,
+        "startedAt": first_ts,
+        "endedAt": last_ts,
+    }
+
+
+def find_claude_team_sessions(cwd: Path, team_name: str, lead_sid: str | None = None) -> 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
+    the lead recorded `team.teamName` with a different case than the harness
+    serialised into the transcript (e.g. `okstra-DEV-6827` vs `okstra-dev-6827`).
+
+    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.
+    """
+    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()}"'
+    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 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

@@ -0,0 +1,84 @@
+"""Command-line entry point for the package."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from .collect import collect
+from .report import substitute_final_report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("team_state", type=Path, help="Path to team-state JSON file")
+    parser.add_argument("--project-root", type=Path, default=None,
+                        help="Override project root (default: inferred from team-state path)")
+    parser.add_argument("--write", action="store_true",
+                        help="Write the updated team-state back to the same path (default: print to stdout)")
+    parser.add_argument("--summary", action="store_true",
+                        help="Also print a one-line summary to stderr")
+    parser.add_argument("--substitute-final-report", type=Path, default=None,
+                        help="After collecting usage, substitute {{LEAD_TOTAL_TOKENS}} / {{LEAD_BILLABLE_TOKENS}} / "
+                             "{{LEAD_COST_USD}} / {{WORKER_TOTAL_TOKENS}} / {{WORKER_BILLABLE_TOKENS}} / "
+                             "{{WORKER_COST_USD}} / {{GRAND_TOTAL_TOKENS}} / {{GRAND_BILLABLE_TOKENS}} / "
+                             "{{GRAND_COST_USD}} / {{CLI_COST_USD}} placeholders in the given final-report file "
+                             "with concrete values from the freshly computed usageSummary.")
+    args = parser.parse_args()
+
+    if not args.team_state.is_file():
+        print(f"team-state not found: {args.team_state}", file=sys.stderr)
+        return 2
+
+    updated = collect(args.team_state, args.project_root)
+
+    if args.write:
+        args.team_state.write_text(json.dumps(updated, indent=2, ensure_ascii=False) + "\n")
+    else:
+        json.dump(updated, sys.stdout, indent=2, ensure_ascii=False)
+        sys.stdout.write("\n")
+
+    if args.summary:
+        s = updated.get("usageSummary") or {}
+        cost = s.get("estimatedCostUsd") or {}
+        print(
+            f"raw: lead={s.get('leadTotalTokens', 0):,} workers={s.get('workerTotalTokens', 0):,} "
+            f"grand={s.get('grandTotalTokens', 0):,}",
+            file=sys.stderr,
+        )
+        print(
+            f"billable-equiv: lead={s.get('leadBillableEquivalentTokens', 0):,} "
+            f"workers={s.get('workerBillableEquivalentTokens', 0):,} "
+            f"grand={s.get('grandBillableEquivalentTokens', 0):,}",
+            file=sys.stderr,
+        )
+        print(
+            f"cost USD: lead=${cost.get('lead', 0):.2f} claude-workers=${cost.get('claudeWorkers', 0):.2f} "
+            f"cli-workers=${cost.get('cliWorkers', 0):.2f} grand=${cost.get('grandTotal', 0):.2f}",
+            file=sys.stderr,
+        )
+        print(f"sessions={s.get('sessionsFound', 0)} team={s.get('teamName', '')}", file=sys.stderr)
+
+    if args.substitute_final_report is not None:
+        replaced = substitute_final_report(args.substitute_final_report, updated)
+        if replaced < 0:
+            print(
+                f"final-report substitution skipped: file not found at {args.substitute_final_report}",
+                file=sys.stderr,
+            )
+        elif replaced == 0:
+            print(
+                f"final-report substitution: no token placeholders found at {args.substitute_final_report}",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"final-report substitution: replaced {replaced} placeholder occurrence(s) in {args.substitute_final_report}",
+                file=sys.stderr,
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/python/okstra_token_usage/codex.py

@@ -0,0 +1,80 @@
+"""Codex CLI rollout collectors."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from .jsonl_io import iter_jsonl
+from .paths import CODEX_SESSIONS
+
+
+def codex_session_total(jsonl_path: Path) -> dict:
+    """Return last token_count snapshot from a codex rollout jsonl."""
+    last: dict | None = None
+    cwd_val: str | None = None
+    model_val: str | None = None
+    started: str | None = None
+    ended: str | None = None
+    for rec in iter_jsonl(jsonl_path):
+        if rec.get("type") == "session_meta":
+            payload = rec.get("payload") or {}
+            cwd_val = payload.get("cwd")
+            started = payload.get("timestamp")
+        elif rec.get("type") == "turn_context":
+            payload = rec.get("payload") or {}
+            if model_val is None and payload.get("model"):
+                model_val = payload["model"]
+        elif rec.get("type") == "event_msg":
+            payload = rec.get("payload") or {}
+            if payload.get("type") == "token_count":
+                last = payload
+                ended = rec.get("timestamp")
+    if last is None:
+        return {"totalTokens": 0, "cwd": cwd_val, "model": model_val, "available": False}
+    info = last.get("info") or {}
+    total = info.get("total_token_usage") or {}
+    return {
+        "totalTokens": total.get("total_tokens", 0) or 0,
+        "inputTokens": total.get("input_tokens", 0) or 0,
+        "cachedInputTokens": total.get("cached_input_tokens", 0) or 0,
+        "outputTokens": total.get("output_tokens", 0) or 0,
+        "reasoningOutputTokens": total.get("reasoning_output_tokens", 0) or 0,
+        "cwd": cwd_val,
+        "model": model_val,
+        "startedAt": started,
+        "endedAt": ended,
+        "available": True,
+    }
+
+
+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."""
+    if not CODEX_SESSIONS.is_dir() or not started_at or not ended_at:
+        return None
+    target_cwd = str(cwd)
+    candidates: list[tuple[str, Path]] = []
+    for p in CODEX_SESSIONS.rglob("rollout-*.jsonl"):
+        try:
+            with p.open() as fh:
+                first = fh.readline()
+        except OSError:
+            continue
+        if not first:
+            continue
+        try:
+            rec = json.loads(first)
+        except json.JSONDecodeError:
+            continue
+        if rec.get("type") != "session_meta":
+            continue
+        payload = rec.get("payload") or {}
+        if payload.get("cwd") != target_cwd:
+            continue
+        ts = payload.get("timestamp") or rec.get("timestamp") or ""
+        if not (started_at <= ts <= ended_at):
+            continue
+        candidates.append((ts, p))
+    if not candidates:
+        return None
+    candidates.sort()
+    return candidates[-1][1]
+