okstra 0.1.0

package/runtime/python/okstra_ctl/index.py

@@ -0,0 +1,216 @@
+"""active/projects 인덱스 행 치환·기록."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .ids import build_run_id
+from .invocation import invocation_path, save_invocation
+from .jsonl import append_jsonl, read_jsonl, remove_jsonl_row, rotate_recent_if_needed
+from .project_meta import upsert_project_meta
+
+
+def _replace_or_append_active_row(home: Path, run_id: str, row: dict) -> None:
+    active = home / "active.jsonl"
+    rows = read_jsonl(active)
+    replaced = False
+    for i, r in enumerate(rows):
+        if r.get("runId") == run_id:
+            rows[i] = row
+            replaced = True
+            break
+    if not replaced:
+        append_jsonl(active, row)
+        return
+    tmp = active.with_suffix(".jsonl.tmp")
+    with tmp.open("w") as f:
+        for r in rows:
+            f.write(json.dumps(r, separators=(",", ":")) + "\n")
+    os.replace(tmp, active)
+
+
+def _replace_or_append_project_row(home: Path, project_id: str,
+                                   run_id: str, row: dict) -> None:
+    proj_index = home / "projects" / project_id / "index.jsonl"
+    rows = read_jsonl(proj_index)
+    replaced = False
+    for i, r in enumerate(rows):
+        if r.get("runId") == run_id:
+            rows[i] = row
+            replaced = True
+            break
+    if not replaced:
+        append_jsonl(proj_index, row)
+        return
+    proj_index.parent.mkdir(parents=True, exist_ok=True)
+    tmp = proj_index.with_suffix(".jsonl.tmp")
+    with tmp.open("w") as f:
+        for r in rows:
+            f.write(json.dumps(r, separators=(",", ":")) + "\n")
+    os.replace(tmp, proj_index)
+
+
+def record_start(home: Path, *, project_id: str, project_root: str,
+                 task_group: str, task_id: str, task_type: str,
+                 run_seq: int, when: str, workers: list, lead_model: str,
+                 run_dir_rel: str, final_report_rel: str,
+                 argv: list, cwd: str,
+                 env_overrides: dict,
+                 brief_sha256: str = "",
+                 initial_status: str = "running",
+                 final_status_rel: str = "") -> str:
+    """run 시작 시점의 인덱스/invocation/meta 를 1 트랜잭션으로 기록.
+    반환값: 생성된 runId.
+    """
+    run_id = build_run_id(project_id, task_group, task_id, task_type, run_seq)
+    inv_path_abs = invocation_path(home, project_id, task_group, task_id,
+                                   task_type, run_seq)
+    inv_path_rel = inv_path_abs.relative_to(home)
+    # 종결 상태(prepared/aborted/etc) 로 시작하는 경우 finishedAt 도 같이 채워
+    # 인덱스 위치를 active 가 아닌 recent 로 라우팅한다.
+    is_terminal = initial_status != "running"
+    row = {
+        "runId": run_id,
+        "projectId": project_id,
+        "projectRoot": project_root,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "taskKey": f"{task_group}/{task_id}",
+        "taskType": task_type,
+        "runSeq": run_seq,
+        "status": initial_status,
+        "startedAt": when,
+        "finishedAt": when if is_terminal else None,
+        "workers": workers,
+        "leadModel": lead_model,
+        "validation": "not-run",
+        "finalReportRel": final_report_rel,
+        # FINAL_STATUS_FILE 의 카운터(RUN_STATUS_SEQ) 는 RUN_MANIFESTS_SEQ
+        # 와 별개로 advance 한다(render-only/실패 prep 은 manifest 만 증가).
+        # 따라서 status 파일을 추적할 때는 manifest seq 를 추정해 glob 으로
+        # 찾지 말고 run 시작 시점의 정식 경로를 row 에 박아 두고 사용한다.
+        "finalStatusRel": final_status_rel,
+        "runDirRel": run_dir_rel,
+        "invocationFile": str(inv_path_rel),
+    }
+    # okstra-ctl 가 미리 'reserving' 예약 row 를 작성했을 수 있다(P1-2). 같은
+    # runId 의 예약 row 가 있으면 update; 없으면 append.
+    existing_rows = read_jsonl(home / "active.jsonl")
+    had_reservation = any(r.get("runId") == run_id for r in existing_rows)
+    if is_terminal:
+        # active 에 들어가지 않도록 — 이미 있던 reservation 이 있으면 제거하고 recent 로.
+        if had_reservation:
+            remove_jsonl_row(home / "active.jsonl",
+                             lambda r: r.get("runId") == run_id)
+        # 동일 runId 가 이미 recent.jsonl 에 있으면(예: 매니페스트 직후 사용자가
+        # 처음 okstra-ctl 을 실행해 자동 backfill 이 같은 terminal run 을 미리
+        # ingest 한 경우) 중복 append 를 방지하기 위해 기존 row 를 제거하고 새로
+        # 쓴다(replace). 그렇지 않으면 동일 runId 가 두 줄로 남아 prefix 해석이
+        # 모호해지고 runCount 도 재증가한다.
+        had_recent = bool(remove_jsonl_row(
+            home / "recent.jsonl", lambda r: r.get("runId") == run_id))
+        append_jsonl(home / "recent.jsonl", row)
+        # --render-only 나 launch-failure 같은 terminal 시작은 reconcile 의
+        # promote 경로를 거치지 않으므로 별도 rotation hook 이 필요하다.
+        # 그렇지 않으면 그런 run 만 누적된 환경에서 recent.jsonl 이 임계를
+        # 넘어도 archive 로 이동되지 않는다.
+        rotate_recent_if_needed(home)
+    else:
+        _replace_or_append_active_row(home, run_id, row)
+        had_recent = False
+    _replace_or_append_project_row(home, project_id, run_id, row)
+    save_invocation(home, project_id, task_group, task_id, task_type, run_seq, {
+        "runId": run_id,
+        "okstraVersion": os.environ.get("OKSTRA_SCRIPT_VERSION", ""),
+        "invokedAt": when,
+        "cwd": cwd,
+        "argv": argv,
+        "envOverrides": env_overrides,
+        "briefSha256": brief_sha256,
+        "backfilled": False,
+    })
+    # 예약이 이미 있었다면 runCount/activeCount 는 reserve 단계에서 이미 증가시켰다.
+    # 종결 상태로 시작했다면(terminal) activeCount 를 즉시 되돌린다.
+    # 또한 backfill 이 같은 runId 를 recent 에 미리 ingest 했었다면(had_recent)
+    # runCount 는 _apply_backfill_meta 에서 이미 가산되었고 activeCount 는
+    # 증가된 적이 없으므로, 여기서는 started/finished 모두 건너뛴다.
+    if had_recent:
+        upsert_project_meta(home, project_id, project_root=project_root,
+                            when=when, started=False, finished=False)
+    else:
+        upsert_project_meta(home, project_id, project_root=project_root,
+                            when=when, started=not had_reservation,
+                            finished=is_terminal)
+    return run_id
+
+
+def reserve_run_in_active(home: Path, *,
+                          project_id: str, project_root: str,
+                          task_group: str, task_id: str, task_type: str,
+                          run_seq: int, when: str,
+                          run_dir_rel: str, final_report_rel: str,
+                          final_status_rel: str = "") -> None:
+    """예약 row 를 active.jsonl 에 즉시 기록한다. 중앙 락 보호 필수.
+    record_start 가 나중에 같은 (project, group, task, task_type, seq) 를 만나면
+    이 row 를 update 한다.
+    """
+    run_id = build_run_id(project_id, task_group, task_id, task_type, run_seq)
+    inv_rel = invocation_path(home, project_id, task_group, task_id,
+                              task_type, run_seq).relative_to(home)
+    row = {
+        "runId": run_id,
+        "projectId": project_id,
+        "projectRoot": project_root,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "taskKey": f"{task_group}/{task_id}",
+        "taskType": task_type,
+        "runSeq": run_seq,
+        "status": "reserving",
+        "startedAt": when,
+        "finishedAt": None,
+        "workers": [],
+        "leadModel": "",
+        "validation": "not-run",
+        "finalReportRel": final_report_rel,
+        # 예약 시점 best-effort: 정상 run 은 RUN_STATUS_SEQ == RUN_MANIFESTS_SEQ
+        # 라 일치한다. record_start 가 실제 경로로 update 한다.
+        "finalStatusRel": final_status_rel,
+        "runDirRel": run_dir_rel,
+        "invocationFile": str(inv_rel),
+    }
+    append_jsonl(home / "active.jsonl", row)
+    # project index 도 미리 한 줄 — record_start 가 나중에 update 하므로 동일 row 형태로.
+    append_jsonl(home / "projects" / project_id / "index.jsonl", row)
+    # runCount/activeCount 는 예약 시점에 1회만 증가. record_start 는 had_reservation
+    # 일 때 started=False 로 호출되므로 중복 카운트 없음.
+    upsert_project_meta(home, project_id, project_root=project_root,
+                        when=when, started=True)
+
+
+def remove_reservation(home: Path, *, project_id: str, task_group: str,
+                       task_id: str, task_type: str, run_seq: int) -> None:
+    """예약 row 를 제거한다(spawn 실패 시 cleanup). 중앙 락 보호 필요.
+    같은 (project, group, task, task_type, seq) 의 'reserving' 행만 지운다.
+    예약 시점에 증가시켰던 runCount/activeCount 도 되돌린다.
+    """
+    run_id = build_run_id(project_id, task_group, task_id, task_type, run_seq)
+    def _match(r):
+        return (r.get("runId") == run_id and r.get("status") == "reserving")
+    removed = remove_jsonl_row(home / "active.jsonl", _match)
+    proj_index = home / "projects" / project_id / "index.jsonl"
+    if proj_index.is_file():
+        remove_jsonl_row(proj_index, _match)
+    if removed is None:
+        return
+    # reserve 가 카운터를 1 증가시켰으므로 활성/총 카운트를 되돌린다.
+    target = home / "projects" / project_id / "meta.json"
+    if not target.is_file():
+        return
+    meta = json.loads(target.read_text())
+    meta["runCount"] = max(0, int(meta.get("runCount", 0)) - 1)
+    meta["activeCount"] = max(0, int(meta.get("activeCount", 0)) - 1)
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(meta, indent=2) + "\n")
+    os.replace(tmp, target)

package/runtime/python/okstra_ctl/invocation.py

@@ -0,0 +1,49 @@
+"""invocation JSON 경로/저장/로드."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from .ids import _safe_fs_segment
+
+
+def invocation_path(home: Path, project_id: str,
+                    task_group: str, task_id: str, task_type: str,
+                    run_seq: int) -> Path:
+    """invocation JSON 파일 절대경로.
+    okstra 의 run_seq 는 (group, task_id, task_type) 별로 독립이므로 같은 project 안에
+    seq=1 인 run 이 여러 개일 수 있다. 따라서 파일명은 4-tuple 전체로 유일성을 보장한다.
+    """
+    seq = f"{run_seq:02d}" if run_seq < 100 else str(run_seq)
+    # 세그먼트를 평탄 조인하면 ('feature-8','email') 과 ('feature','8-email')
+    # 가 같은 파일로 충돌하므로, 각 세그먼트를 하위 디렉터리로 분리해 경계
+    # 정보를 손실 없이 보존한다. 또한 task_group/task_id 등은 CLI/manifest
+    # 에서 들어오는 미검증 값이므로 fs-safe 슬러그로 강제 정규화해 `/` 나
+    # `..` 가 invocations 디렉터리 밖으로 path 를 escape 시키는 것을 막는다.
+    return (home / "projects" / _safe_fs_segment(project_id) / "invocations"
+            / _safe_fs_segment(task_group) / _safe_fs_segment(task_id)
+            / _safe_fs_segment(task_type) / f"r{seq}.json")
+
+
+def save_invocation(home: Path, project_id: str,
+                    task_group: str, task_id: str, task_type: str,
+                    run_seq: int, payload: dict) -> None:
+    """invocation 을 원자적으로 저장(임시파일 + os.replace)."""
+    target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(payload, indent=2) + "\n")
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, target)
+
+
+def load_invocation(home: Path, project_id: str,
+                    task_group: str, task_id: str, task_type: str,
+                    run_seq: int) -> Optional[dict]:
+    """invocation JSON 을 읽는다. 없으면 None."""
+    target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
+    if not target.is_file():
+        return None
+    return json.loads(target.read_text())

package/runtime/python/okstra_ctl/jsonl.py

@@ -0,0 +1,84 @@
+"""jsonl I/O 및 회전."""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, List, Optional
+
+
+def append_jsonl(path: Path, row: dict) -> None:
+    """jsonl 파일 끝에 한 줄 append. 파일이 없으면 생성."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(row, separators=(",", ":")) + "\n"
+    with path.open("a") as f:
+        f.write(line)
+
+
+def read_jsonl(path: Path) -> List[dict]:
+    """jsonl 파일을 모두 읽어 dict 목록으로 반환. 파싱 실패 라인은 스킵."""
+    if not path.is_file():
+        return []
+    rows: List[dict] = []
+    for line in path.open():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def remove_jsonl_row(path: Path, match: Callable[[dict], bool]) -> Optional[dict]:
+    """match 가 True 인 첫 행을 제거하고 반환. 없으면 None.
+    임시 파일 + os.replace 로 원자적으로 교체한다.
+    """
+    if not path.is_file():
+        return None
+    removed: Optional[dict] = None
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with path.open() as src, tmp.open("w") as dst:
+        for line in src:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                row = json.loads(stripped)
+            except json.JSONDecodeError:
+                dst.write(line)
+                continue
+            if removed is None and match(row):
+                removed = row
+                continue
+            dst.write(line)
+    os.replace(tmp, path)
+    return removed
+
+
+def rotate_recent_if_needed(home: Path, max_rows: int = 2000,
+                            max_bytes: int = 5 * 1024 * 1024) -> Optional[Path]:
+    """recent.jsonl 이 임계를 넘으면 archive/YYYY/YYYY-MM.jsonl 로 이동.
+    이동 후 recent.jsonl 을 비운다. 회전이 발생했으면 archive 경로 반환.
+    """
+    recent = home / "recent.jsonl"
+    if not recent.is_file():
+        return None
+    rows = list(recent.open())
+    size_ok = recent.stat().st_size < max_bytes
+    rows_ok = len(rows) < max_rows
+    if size_ok and rows_ok:
+        return None
+    # archive 키는 첫 행의 finishedAt 월. 없으면 현재 월.
+    first_row = json.loads(rows[0]) if rows else {}
+    finished = first_row.get("finishedAt") or datetime.now(timezone.utc).replace(tzinfo=None).strftime("%Y-%m-%dT%H:%M:%SZ")
+    yyyy, yyyymm = finished[:4], finished[:7]
+    archive = home / "archive" / yyyy / f"{yyyymm}.jsonl"
+    archive.parent.mkdir(parents=True, exist_ok=True)
+    with archive.open("a") as out:
+        for line in rows:
+            out.write(line)
+    recent.write_text("")
+    return archive

package/runtime/python/okstra_ctl/listing.py

@@ -0,0 +1,156 @@
+"""list/format/show."""
+from __future__ import annotations
+
+import json
+import re as _re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from .jsonl import read_jsonl
+from .reconcile import _parse_iso
+
+
+def list_projects(home: Path, *, only_active: bool = False,
+                  sort_by: str = "recent") -> List[dict]:
+    """projects/<id>/meta.json 을 모두 읽어 정렬된 목록을 반환."""
+    base = home / "projects"
+    if not base.is_dir():
+        return []
+    items: List[dict] = []
+    for child in base.iterdir():
+        meta_file = child / "meta.json"
+        if not meta_file.is_file():
+            continue
+        meta = json.loads(meta_file.read_text())
+        # projectRoot 가 누락/빈 문자열이면 Path("").is_dir() 이 cwd 를 가리켜
+        # True 가 되므로(missing 으로 잡히지 않음), 빈 값은 명시적으로 missing
+        # 처리한다.
+        proj_root = meta.get("projectRoot") or ""
+        meta["missing"] = (not proj_root) or (not Path(proj_root).is_dir())
+        if only_active and int(meta.get("activeCount", 0)) <= 0:
+            continue
+        items.append(meta)
+    if sort_by == "name":
+        items.sort(key=lambda m: m.get("projectId", ""))
+    elif sort_by == "count":
+        items.sort(key=lambda m: int(m.get("runCount", 0)), reverse=True)
+    else:
+        items.sort(key=lambda m: m.get("lastRunAt", ""), reverse=True)
+    return items
+
+
+def format_projects_table(items: List[dict]) -> str:
+    """projects 테이블 텍스트 포맷팅."""
+    rows = [("PROJECT-ID", "RUNS", "ACTIVE", "LAST-RUN", "ROOT")]
+    for it in items:
+        root = it.get("projectRoot", "") + (" (MISSING)" if it.get("missing") else "")
+        rows.append((it.get("projectId", ""), str(it.get("runCount", 0)),
+                     str(it.get("activeCount", 0)), it.get("lastRunAt", ""),
+                     root))
+    widths = [max(len(r[i]) for r in rows) for i in range(5)]
+    lines = []
+    for r in rows:
+        lines.append("  ".join(c.ljust(widths[i]) for i, c in enumerate(r)))
+    return "\n".join(lines) + "\n"
+
+
+def _parse_since(value: str) -> Optional[datetime]:
+    """--since 파싱. 빈 문자열은 None(필터 없음). 형식 위반은 ValueError 로
+    fail-fast 한다. 이전엔 잘못된 값(`7days`)이 silently None 으로 강등되어
+    필터가 무력화됐고, rerun --filter --since <typo> 가 max-spawn 까지 모든
+    historical run 을 spawn 하던 회귀가 있었다.
+    """
+    if not value:
+        return None
+    m = _re.match(r"^(\d+)([dhm])$", value)
+    if m:
+        n, unit = int(m.group(1)), m.group(2)
+        delta = {"d": timedelta(days=n), "h": timedelta(hours=n),
+                 "m": timedelta(minutes=n)}[unit]
+        return datetime.now(timezone.utc).replace(tzinfo=None) - delta
+    try:
+        return datetime.strptime(value, "%Y-%m-%d")
+    except ValueError as exc:
+        raise ValueError(
+            f"invalid --since {value!r}: expected <N>[dhm] or YYYY-MM-DD"
+        ) from exc
+
+
+def list_runs(home: Path, *, project: str = "all", task_group: str = "all",
+              status: str = "all", since: str = "", limit: int = 0,
+              include_archive: bool = False) -> List[dict]:
+    """active + recent (옵션 archive) 를 합쳐 필터/정렬 후 반환."""
+    rows = read_jsonl(home / "active.jsonl") + read_jsonl(home / "recent.jsonl")
+    if include_archive:
+        archive_dir = home / "archive"
+        if archive_dir.is_dir():
+            for f in sorted(archive_dir.glob("*/*.jsonl")):
+                rows.extend(read_jsonl(f))
+    threshold = _parse_since(since)
+    out: List[dict] = []
+    for r in rows:
+        if project != "all" and r.get("projectId") != project:
+            continue
+        if task_group != "all" and r.get("taskGroup") != task_group:
+            continue
+        if status != "all" and r.get("status") != status:
+            continue
+        if threshold:
+            started = _parse_iso(r.get("startedAt", ""))
+            if started and started < threshold:
+                continue
+        out.append(r)
+    out.sort(key=lambda r: r.get("startedAt", ""), reverse=True)
+    if limit > 0:
+        out = out[:limit]
+    return out
+
+
+def format_runs_table(rows: List[dict]) -> str:
+    header = ("RUN-ID", "STATUS", "STARTED", "TASK-TYPE")
+    body = [(r.get("runId", ""), r.get("status", ""),
+             r.get("startedAt", ""), r.get("taskType", "")) for r in rows]
+    table = [header] + body
+    widths = [max(len(t[i]) for t in table) for i in range(4)]
+    lines = []
+    for t in table:
+        lines.append("  ".join(c.ljust(widths[i]) for i, c in enumerate(t)))
+    return "\n".join(lines) + "\n"
+
+
+def find_row_by_run_id(home: Path, run_id: str) -> Optional[dict]:
+    """active+recent+archive 를 모두 뒤져 runId 가 일치하는 최신 row 반환."""
+    rows = list_runs(home, include_archive=True)
+    for r in rows:
+        if r.get("runId") == run_id:
+            return r
+    return None
+
+
+def format_show(row: dict) -> str:
+    inv = row.get("invocationFile", "")
+    return (
+        f"runId           : {row.get('runId')}\n"
+        f"projectId       : {row.get('projectId')}\n"
+        f"projectRoot     : {row.get('projectRoot')}\n"
+        f"taskKey         : {row.get('taskGroup')}/{row.get('taskId')}\n"
+        f"taskType        : {row.get('taskType')}\n"
+        f"status          : {row.get('status')}\n"
+        f"startedAt       : {row.get('startedAt')}\n"
+        f"finishedAt      : {row.get('finishedAt')}\n"
+        f"workers         : {','.join(row.get('workers', []))}\n"
+        f"leadModel       : {row.get('leadModel')}\n"
+        f"validation      : {row.get('validation')}\n"
+        f"runDirRel       : {row.get('runDirRel')}\n"
+        f"finalReportRel  : {row.get('finalReportRel')}\n"
+        f"invocationFile  : {inv}\n"
+    )
+
+
+def absolute_final_report_path(row: dict) -> Optional[Path]:
+    project_root = row.get("projectRoot", "")
+    rel = row.get("finalReportRel", "")
+    if not project_root or not rel:
+        return None
+    return (Path(project_root) / rel).resolve()

package/runtime/python/okstra_ctl/locks.py

@@ -0,0 +1,42 @@
+"""중앙 락과 task-lock 파일명. 다른 okstra_ctl 모듈에 의존하지 않는다."""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+
+from .ids import _escape_segment_for_join, _safe_fs_segment
+
+
+@contextlib.contextmanager
+def central_lock(home):
+    """~/.okstra/.lock 위에 fcntl LOCK_EX. okstra-central.sh 의
+    okstra_central_with_lock 과 같은 파일을 사용하므로 record_start 와
+    상호 직렬화된다.
+    """
+    from pathlib import Path as _Path
+    home_p = _Path(home)
+    home_p.mkdir(parents=True, exist_ok=True)
+    lockfile = home_p / ".lock"
+    if not lockfile.exists():
+        lockfile.touch()
+    f = lockfile.open("r+")
+    try:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        f.close()
+
+
+def task_lock_filename(project_id: str, task_group: str, task_id: str,
+                       task_type: str) -> str:
+    """task-key + task-type 단위 mutex 파일명. ~/.okstra/.locks/ 아래에 위치한다.
+    okstra 의 RUN_DIR 가 task-type 별로 분리되므로 mutex 도 같은 입자에 둔다.
+    각 세그먼트는 먼저 fs-safe 슬러그로 정규화해 `/` 나 `..` 가 .locks 디렉터리
+    밖으로 mutex 를 escape 시키는 것을 막고, 이어서 `-` 를 `--` 로 escape 한
+    뒤 `-` 로 조인해 슬래시 경계를 보존한다(('p','feature-8','email','x') 와
+    ('p','feature','8-email','x') 가 같은 파일명으로 매핑되어 mutex 가 공유
+    되는 문제 방지).
+    """
+    parts = [_escape_segment_for_join(_safe_fs_segment(s))
+             for s in (project_id, task_group, task_id, task_type)]
+    return "-".join(parts) + ".lock"

package/runtime/python/okstra_ctl/material.py

@@ -0,0 +1,62 @@
+"""Analysis material body + related-tasks builders.
+
+bash `build_review_material`, `resolve_related_tasks_json`,
+`build_related_tasks_bullets`, `build_related_tasks_inline` 의 python 구현.
+brief 본문과 directive 를 합쳐 lead 가 읽을 `analysis-material.md` 본문을
+만들고, 이미 manifest 에 기록된 related-tasks 와 새 입력을 merge 한다.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+def build_analysis_material(brief_path: Path, directive: str = "") -> str:
+    """`analysis-material.md` 본문 문자열을 돌려준다."""
+    parts = ["# OKSTRA Analysis Material", "", "## Task Brief", ""]
+    parts.append(Path(brief_path).read_text(encoding="utf-8").rstrip())
+    if directive:
+        parts.append("")
+        parts.append("## Directive")
+        parts.append("")
+        parts.append(
+            "> Free-form directive supplied via `--directive`. Treat as a hard hint that may override default heuristics in lead, workers, and downstream skills (e.g. okstra-schedule's Gantt skip gate)."
+        )
+        parts.append("")
+        parts.append(directive)
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def resolve_related_tasks(
+    *, task_manifest_path: Optional[Path], raw_related: str
+) -> list[str]:
+    """기존 manifest 의 relatedTasks + 새 CSV 입력을 dedupe-merge."""
+    existing: list[str] = []
+    if task_manifest_path and Path(task_manifest_path).exists():
+        try:
+            manifest = json.loads(Path(task_manifest_path).read_text(encoding="utf-8"))
+            existing = manifest.get("relatedTasks") or []
+            if not isinstance(existing, list):
+                existing = []
+        except Exception:
+            existing = []
+    provided = [v.strip() for v in (raw_related or "").split(",") if v.strip()]
+    seen: set[str] = set()
+    out: list[str] = []
+    for v in [*existing, *provided]:
+        if not v or v in seen:
+            continue
+        seen.add(v)
+        out.append(v)
+    return out
+
+
+def related_tasks_bullets(items: list[str]) -> str:
+    if not items:
+        return "- None recorded"
+    return "\n".join(f"- `{v}`" for v in items)
+
+
+def related_tasks_inline(items: list[str]) -> str:
+    return ", ".join(items) if items else "None"

package/runtime/python/okstra_ctl/models.py

@@ -0,0 +1,63 @@
+"""Model display / execution-value resolution for okstra workers.
+
+bash `resolve_model_metadata` 의 동등한 python 구현. 사용자가 준 모델 alias
+또는 정식 이름을 `(display, execution_value)` 쌍으로 정규화한다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+CLAUDE_MAPPING = {
+    "opus": ("opus", "opus"),
+    "opus-4-7": ("opus-4-7", "claude-opus-4-7"),
+    "claude-opus-4-7": ("opus-4-7", "claude-opus-4-7"),
+    "sonnet": ("sonnet", "sonnet"),
+    "sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),
+    "claude-sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),
+    "haiku": ("haiku", "haiku"),
+    "haiku-4-5": ("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5": ("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5-20251001": ("haiku-4-5", "claude-haiku-4-5-20251001"),
+}
+GEMINI_MAPPING = {
+    "auto": ("auto", "auto"),
+    "gemini auto": ("auto", "auto"),
+    "pro": ("pro", "pro"),
+    "gemini pro": ("pro", "pro"),
+    "gemini 3 flash preview": ("Gemini 3 Flash Preview", "gemini-3-flash-preview"),
+    "gemini-3-flash-preview": ("Gemini 3 Flash Preview", "gemini-3-flash-preview"),
+    "gemini-3-pro-preview": ("Gemini 3 Pro Preview", "gemini-3-pro-preview"),
+}
+CODEX_MAPPING = {
+    "gpt-5.5": ("gpt-5.5", "gpt-5.5"),
+    "gpt-5.4": ("gpt-5.4", "gpt-5.4"),
+    "gpt-5.4-mini": ("gpt-5.4-mini", "gpt-5.4-mini"),
+    "gpt-5.3-codex": ("gpt-5.4", "gpt-5.4"),
+    "gpt-5.2": ("gpt-5.2", "gpt-5.2"),
+    "codex-auto-review": ("codex-auto-review", "codex-auto-review"),
+}
+PROVIDER_MAPPINGS = {"claude": CLAUDE_MAPPING, "gemini": GEMINI_MAPPING, "codex": CODEX_MAPPING}
+
+
+@dataclass
+class ModelAssignment:
+    display: str
+    execution: str
+
+
+def resolve_model_metadata(
+    *, provider: str, raw_value: str, default_display: str, default_execution: str,
+) -> ModelAssignment:
+    """alias → (display, execution_value). 알 수 없는 값은 그대로 통과.
+
+    provider: "claude" | "codex" | "gemini" (그 외는 mapping 미적용)
+    """
+    raw_value = (raw_value or "").strip()
+    value = raw_value or default_display
+    display = value
+    execution = raw_value or default_execution
+    normalized = value.strip().lower()
+    mapping = PROVIDER_MAPPINGS.get(provider)
+    if mapping and normalized in mapping:
+        display, execution = mapping[normalized]
+    return ModelAssignment(display=display, execution=execution)