okstra 0.1.0

package/runtime/python/okstra_ctl/__init__.py

@@ -0,0 +1,125 @@
+"""okstra-ctl 와 okstra-central 가 공유하는 순수 헬퍼 패키지.
+
+기존 단일 모듈 `okstra_ctl_lib` 를 도메인 단위 서브모듈로 분해한 결과이며,
+모든 public 심볼을 패키지 루트에서 재노출한다. 호출자는
+`from okstra_ctl import X` 형태로 직접 import 한다.
+"""
+from __future__ import annotations
+
+# Public API — keep import order topological (leaves first) to avoid surprises.
+from .ids import (
+    build_run_id,
+    parse_run_id,
+    run_id_to_session_name,
+    slugify_task_segment,
+    _escape_segment_for_join,
+    _safe_fs_segment,
+)
+from .locks import central_lock, task_lock_filename
+from .invocation import invocation_path, save_invocation, load_invocation
+from .jsonl import (
+    append_jsonl,
+    read_jsonl,
+    remove_jsonl_row,
+    rotate_recent_if_needed,
+)
+from .project_meta import (
+    _project_meta_path,
+    load_project_meta,
+    upsert_project_meta,
+)
+from .index import (
+    _replace_or_append_active_row,
+    _replace_or_append_project_row,
+    record_start,
+    reserve_run_in_active,
+    remove_reservation,
+)
+from .reconcile import (
+    DEFAULT_ABORT_AFTER_SECONDS,
+    _now_iso,
+    _parse_iso,
+    _read_run_manifest_validation,
+    _reconcile_active_locked,
+    normalize_central_status,
+    normalize_reconciled_report_status,
+    reconcile_active,
+)
+from .listing import (
+    _parse_since,
+    absolute_final_report_path,
+    find_row_by_run_id,
+    format_projects_table,
+    format_runs_table,
+    format_show,
+    list_projects,
+    list_runs,
+)
+from .resolver import ResolveError, _all_run_ids, resolve_last, resolve_run_id
+from .sequence import predict_next_run_seq
+from .tmux import _shell_quote, build_tmux_command
+from .batch import expand_selectors, make_batch_id, write_batch_meta
+from .backfill import (
+    _apply_backfill_meta,
+    backfill_project,
+    discover_project_roots,
+    mark_backfilled,
+)
+from .paths import compute_run_paths, next_run_seq
+from .run_context import (
+    compute_and_write_run_context,
+    read_run_context,
+    read_run_inputs,
+    task_mutex,
+    write_run_inputs,
+)
+
+__all__ = [
+    "DEFAULT_ABORT_AFTER_SECONDS",
+    "ResolveError",
+    "absolute_final_report_path",
+    "append_jsonl",
+    "backfill_project",
+    "build_run_id",
+    "build_tmux_command",
+    "central_lock",
+    "compute_and_write_run_context",
+    "compute_run_paths",
+    "discover_project_roots",
+    "expand_selectors",
+    "find_row_by_run_id",
+    "format_projects_table",
+    "format_runs_table",
+    "format_show",
+    "invocation_path",
+    "list_projects",
+    "list_runs",
+    "load_invocation",
+    "load_project_meta",
+    "make_batch_id",
+    "mark_backfilled",
+    "next_run_seq",
+    "normalize_central_status",
+    "normalize_reconciled_report_status",
+    "parse_run_id",
+    "predict_next_run_seq",
+    "read_jsonl",
+    "read_run_context",
+    "read_run_inputs",
+    "reconcile_active",
+    "record_start",
+    "remove_jsonl_row",
+    "remove_reservation",
+    "reserve_run_in_active",
+    "resolve_last",
+    "resolve_run_id",
+    "rotate_recent_if_needed",
+    "run_id_to_session_name",
+    "save_invocation",
+    "slugify_task_segment",
+    "task_lock_filename",
+    "task_mutex",
+    "upsert_project_meta",
+    "write_batch_meta",
+    "write_run_inputs",
+]

package/runtime/python/okstra_ctl/backfill.py

@@ -0,0 +1,253 @@
+"""프로젝트 backfill / discover."""
+from __future__ import annotations
+
+import json
+import os
+import re as _re
+from pathlib import Path
+from typing import List
+
+from .ids import build_run_id
+from .invocation import invocation_path, save_invocation
+from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
+from .project_meta import _project_meta_path
+from .reconcile import _now_iso, normalize_central_status
+
+
+def discover_project_roots(home: Path) -> List[tuple]:
+    """`~/.okstra/projects/<projectId>/meta.json` 을 권위 소스로 (project_id,
+    project_root) 목록을 반환한다.
+
+    신규 모델에서는 okstra.sh 가 첫 실행 시 PROJECT_ROOT 를 해석해
+    `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록하고,
+    record_start 가 그 PROJECT_ROOT 를 meta.json 에 mirror 한다. ctl 입장
+    에서는 한 번이라도 record_start 를 거친 프로젝트는 meta.json 에 등재
+    되어 있으므로, examples/projects 같은 외부 등록 디렉토리가 필요하지
+    않다.
+
+    meta.json 의 projectRoot 가 더 이상 디스크에 존재하지 않으면 스킵한다
+    (프로젝트가 이동/삭제된 경우). 기록 자체는 유지된다 — 사용자가 향후
+    이동된 위치에서 다시 record_start 를 수행하면 meta.json 이 갱신된다.
+    """
+    out: List[tuple] = []
+    projects_dir = home / "projects"
+    if not projects_dir.is_dir():
+        return out
+    for project_dir in sorted(p for p in projects_dir.iterdir() if p.is_dir()):
+        meta_file = project_dir / "meta.json"
+        if not meta_file.is_file():
+            continue
+        try:
+            meta = json.loads(meta_file.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        pid = str(meta.get("projectId") or "")
+        root = str(meta.get("projectRoot") or "")
+        if not pid or not root:
+            continue
+        if not Path(root).is_dir():
+            continue
+        out.append((pid, root))
+    return out
+
+
+def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
+                         started_times: List[str], finished_times: List[str],
+                         run_count_inc: int, active_count_inc: int) -> None:
+    """Backfill 전용 monotonic meta 갱신.
+    upsert_project_meta 는 lastRunAt 을 무조건 인자값으로 덮어쓰므로,
+    backfill 처럼 lexicographic 순서로 N 행을 적용하면 마지막 방문 행의
+    시각이 lastRunAt 이 되어 시계열이 깨진다. 여기서는 기존 meta 와 새
+    행들의 min/max 로 firstRunAt/lastRunAt 을 단조 갱신한다.
+    """
+    target = _project_meta_path(home, project_id)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.is_file():
+        meta = json.loads(target.read_text())
+    else:
+        meta = {"projectId": project_id, "projectRoot": str(project_root),
+                "firstRunAt": "", "lastRunAt": "",
+                "runCount": 0, "activeCount": 0}
+    meta["projectRoot"] = str(project_root)
+    first_pool = [t for t in started_times if t]
+    if meta.get("firstRunAt"):
+        first_pool.append(meta["firstRunAt"])
+    if first_pool:
+        meta["firstRunAt"] = min(first_pool)
+    last_pool = [t for t in (started_times + finished_times) if t]
+    if meta.get("lastRunAt"):
+        last_pool.append(meta["lastRunAt"])
+    if last_pool:
+        meta["lastRunAt"] = max(last_pool)
+    meta["runCount"] = int(meta.get("runCount", 0)) + run_count_inc
+    meta["activeCount"] = max(
+        0, int(meta.get("activeCount", 0)) + active_count_inc)
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(meta, indent=2) + "\n")
+    os.replace(tmp, target)
+
+
+def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
+    """타깃 프로젝트의 .project-docs/okstra/tasks 를 스캔해 누락된 run 을 인덱스에 채움.
+    실제 okstra 레이아웃: runs/<task_type>/manifests/run-manifest-<task_type>-<seq:03d>.json
+    이미 존재하는 runId 는 스킵. 새로 추가된 run 수를 반환.
+    """
+    base = project_root / ".project-docs" / "okstra" / "tasks"
+    if not base.is_dir():
+        return 0
+    existing_index = home / "projects" / project_id / "index.jsonl"
+    existing_ids = {r["runId"] for r in read_jsonl(existing_index)}
+    added = 0
+    # meta 는 행 단위가 아니라 배치 단위로 한 번만 갱신해 시계열을 보존한다.
+    started_times: List[str] = []
+    finished_times: List[str] = []
+    active_inc = 0
+    manifest_re = _re.compile(r"^run-manifest-(?P<tt>.+)-(?P<seq>\d+)\.json$")
+    for group_dir in sorted(p for p in base.iterdir() if p.is_dir()):
+        for task_dir in sorted(p for p in group_dir.iterdir() if p.is_dir()):
+            runs = task_dir / "runs"
+            if not runs.is_dir():
+                continue
+            for type_dir in sorted(p for p in runs.iterdir() if p.is_dir()):
+                manifests = type_dir / "manifests"
+                if not manifests.is_dir():
+                    continue
+                for mf in sorted(manifests.iterdir()):
+                    m = manifest_re.match(mf.name)
+                    if not m:
+                        continue
+                    task_type = m.group("tt")
+                    seq = int(m.group("seq"))
+                    try:
+                        manifest = json.loads(mf.read_text())
+                    except (OSError, json.JSONDecodeError):
+                        # 부분 기록 / 손상된 매니페스트를 빈 dict 로 강등해 row 를
+                        # 만들면, 빈 status 가 'completed' 로 normalize 되어
+                        # recent 에 박히고, 같은 runId 가 existing_ids 로 인덱싱
+                        # 되어 후속 reindex 가 정상화된 매니페스트를 다시 읽을
+                        # 기회를 잃는다. 이번 backfill 에서는 건너뛰어 다음
+                        # 스캔이 정상 데이터를 ingest 할 수 있도록 한다.
+                        continue
+                    # manifest 의 logical task key 가 디렉터리 슬러그와 다를 수
+                    # 있으므로 manifest 값을 우선 사용한다(디렉터리는 fallback).
+                    actual_group = manifest.get("taskGroup") or group_dir.name
+                    actual_task = manifest.get("taskId") or task_dir.name
+                    actual_type = manifest.get("taskType") or task_type
+                    run_id = build_run_id(project_id, actual_group,
+                                          actual_task, actual_type, seq)
+                    if run_id in existing_ids:
+                        continue
+                    # 실제 okstra.sh 가 쓰는 manifest 키:
+                    #   - runDirectoryPath (디렉터리)
+                    #   - expectedReportPath (보고서, 호환: reportPath)
+                    #   - validation: { status, passed, ... } 중첩 dict
+                    run_dir_rel = (manifest.get("runDirectoryPath")
+                                   or manifest.get("runDirPath", ""))
+                    final_rel = (manifest.get("expectedReportPath")
+                                 or manifest.get("reportPath")
+                                 or manifest.get("finalReportPath", ""))
+                    # status 파일 경로는 RUN_STATUS_SEQ 기반이라 manifest seq
+                    # 와 어긋날 수 있다. tail 이 정확한 파일을 추적하도록
+                    # 매니페스트가 기록한 expectedStatusPath /
+                    # finalStatusPath 를 우선 보존한다.
+                    final_status_rel = (
+                        manifest.get("expectedStatusPath")
+                        or manifest.get("finalStatusPath", ""))
+                    # 실제 okstra.sh 매니페스트는 worker 목록을
+                    # `recommendedWorkers`, lead model 을 `teamContract.leadModel`
+                    # 또는 `resultContract.leadModel` 에 저장한다. 평탄
+                    # `workers`/`leadModel` 키는 호환을 위한 fallback 으로만
+                    # 사용한다(없으면 backfill 시 메타데이터 손실).
+                    raw_workers = (manifest.get("recommendedWorkers")
+                                   or manifest.get("workers") or [])
+                    if not isinstance(raw_workers, list):
+                        raw_workers = []
+                    team_contract = manifest.get("teamContract") or {}
+                    result_contract = manifest.get("resultContract") or {}
+                    raw_lead_model = (
+                        (team_contract.get("leadModel") if isinstance(team_contract, dict) else "")
+                        or (result_contract.get("leadModel") if isinstance(result_contract, dict) else "")
+                        or manifest.get("leadModel", ""))
+                    raw_validation = manifest.get("validation")
+                    if isinstance(raw_validation, dict):
+                        validation_status = str(raw_validation.get("status") or "not-run")
+                    elif isinstance(raw_validation, str):
+                        validation_status = raw_validation
+                    else:
+                        validation_status = "not-run"
+                    inv_rel = invocation_path(
+                        home, project_id, actual_group, actual_task,
+                        actual_type, seq).relative_to(home)
+                    # okstra.sh manifest 는 createdAt/updatedAt 만 쓴다(P2 회귀).
+                    # 별도 startedAt/finishedAt 가 없으면 createdAt/updatedAt 으로 보강한다.
+                    started_at = (manifest.get("startedAt")
+                                  or manifest.get("createdAt", ""))
+                    finished_at = (manifest.get("finishedAt")
+                                   or manifest.get("updatedAt", "")
+                                   or started_at)
+                    normalized_status = normalize_central_status(
+                        manifest.get("status", ""), validation_status)
+                    # 비-터미널(running/in-progress) 매니페스트만 active 로 보내
+                    # lazy reconcile 의 정상 종결 경로에 합류시킨다.
+                    # prepared 는 record_start 가 terminal 로 취급하는 상태이고
+                    # (--render-only 실행 산출물), final-report 가 없어 12h 후
+                    # reconcile 이 aborted 로 오인 마킹할 위험이 있으므로 backfill
+                    # 단계에서 recent 로 직접 보낸다.
+                    is_non_terminal = normalized_status in {
+                        "running", "in-progress"}
+                    row = {
+                        "runId": run_id, "projectId": project_id,
+                        "projectRoot": str(project_root),
+                        "taskGroup": actual_group, "taskId": actual_task,
+                        "taskKey": f"{actual_group}/{actual_task}",
+                        "taskType": actual_type, "runSeq": seq,
+                        "status": normalized_status,
+                        "startedAt": started_at,
+                        "finishedAt": None if is_non_terminal else finished_at,
+                        "workers": raw_workers,
+                        "leadModel": raw_lead_model,
+                        "validation": validation_status,
+                        "runDirRel": run_dir_rel,
+                        "finalReportRel": final_rel,
+                        "finalStatusRel": final_status_rel,
+                        "invocationFile": str(inv_rel),
+                    }
+                    if is_non_terminal:
+                        append_jsonl(home / "active.jsonl", row)
+                    else:
+                        append_jsonl(home / "recent.jsonl", row)
+                    append_jsonl(existing_index, row)
+                    save_invocation(home, project_id, actual_group,
+                                    actual_task, actual_type, seq, {
+                        "runId": run_id, "okstraVersion": "",
+                        "invokedAt": row["startedAt"], "cwd": str(project_root),
+                        "argv": [], "envOverrides": {},
+                        "briefSha256": "",
+                        "backfilled": True,
+                    })
+                    if row["startedAt"]:
+                        started_times.append(row["startedAt"])
+                    if row["finishedAt"]:
+                        finished_times.append(row["finishedAt"])
+                    if is_non_terminal:
+                        active_inc += 1
+                    added += 1
+                    existing_ids.add(run_id)
+    if added:
+        # backfill 의 terminal 행도 reconcile 의 promote 경로를 거치지 않으므로
+        # 직접 rotation 을 트리거한다(과거 run 이 많은 프로젝트의 첫 backfill
+        # 에서 recent.jsonl 이 임계를 넘는 회귀 차단).
+        rotate_recent_if_needed(home)
+        _apply_backfill_meta(home, project_id, project_root,
+                             started_times=started_times,
+                             finished_times=finished_times,
+                             run_count_inc=added,
+                             active_count_inc=active_inc)
+    return added
+
+
+def mark_backfilled(home: Path) -> None:
+    state_file = home / "state.json"
+    state = json.loads(state_file.read_text()) if state_file.is_file() else {}
+    state["backfilledAt"] = _now_iso()
+    state_file.write_text(json.dumps(state, indent=2) + "\n")

package/runtime/python/okstra_ctl/batch.py

@@ -0,0 +1,62 @@
+"""배치 메타·셀렉터 확장."""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from .listing import list_runs
+from .resolver import resolve_last, resolve_run_id
+
+
+def make_batch_id() -> str:
+    """20260505T143012-a1b2c3 형식 배치 ID."""
+    ts = datetime.now(timezone.utc).replace(tzinfo=None).strftime("%Y%m%dT%H%M%S")
+    return f"{ts}-{secrets.token_hex(3)}"
+
+
+def write_batch_meta(home: Path, batch_id: str, payload: dict) -> Path:
+    target = home / "batches" / f"{batch_id}.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(payload, indent=2) + "\n")
+    os.replace(tmp, target)
+    return target
+
+
+def expand_selectors(home: Path, *, explicit: List[str], use_filter: bool,
+                     project: str, task_group: str, status: str, since: str,
+                     last: bool, from_stdin: bool,
+                     stdin_data: Optional[str] = None) -> List[str]:
+    """selector 들을 평탄화해 runId 목록을 반환. 중복 제거. 결정적 순서.
+    stdin_data: 호출자가 미리 읽어 전달한 stdin 페이로드. 자식 프로세스의
+    sys.stdin 이 heredoc 등으로 가려진 경우 caller 가 채워준다.
+    """
+    import sys as _sys
+    ids: List[str] = []
+    seen = set()
+
+    def add(rid: str) -> None:
+        if rid not in seen:
+            seen.add(rid); ids.append(rid)
+
+    if last:
+        add(resolve_last(home, project=project, task_group=task_group))
+    if use_filter:
+        rows = list_runs(home, project=project, task_group=task_group,
+                         status=status, since=since, include_archive=True)
+        for r in rows:
+            add(r["runId"])
+    if from_stdin:
+        source = (stdin_data.splitlines() if stdin_data is not None
+                  else _sys.stdin)
+        for line in source:
+            line = line.strip()
+            if line:
+                add(resolve_run_id(home, line))
+    for q in explicit:
+        add(resolve_run_id(home, q))
+    return ids

package/runtime/python/okstra_ctl/ids.py

@@ -0,0 +1,84 @@
+"""runId 빌드/파싱/세그먼트 escape, 세션명. 외부 모듈 의존 없음."""
+from __future__ import annotations
+
+import re as _re
+from typing import Dict
+
+
+# runId 형식: "<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>"
+# task-type 이 포함되는 이유: okstra.sh 의 RUN_DIR 은 task-type 단위 하위 디렉터리이고
+# 카테고리별 카운터(RUN_*_SEQ) 도 task-type 별로 독립이라, 같은 (group, task-id) 라도
+# task-type 이 다르면 별개의 run 으로 취급해야 한다.
+# run-seq 는 최소 2자리 zero-pad.
+_RUN_ID_PATTERN = _re.compile(
+    r"^(?P<projectId>[^/]+)/(?P<taskGroup>[^/]+)/(?P<taskId>[^/]+)"
+    r"/(?P<taskType>[^/]+)/r(?P<runSeq>\d+)$"
+)
+
+
+def build_run_id(project_id: str, task_group: str, task_id: str,
+                 task_type: str, run_seq: int) -> str:
+    """runId 5-tuple 을 단일 슬러그 문자열로 합친다.
+    각 세그먼트는 fs-safe 슬러그로 정규화한다 — 그렇지 않으면 task 식별자에
+    `/` 가 섞였을 때 (group='a/b', task='c') 와 (group='a', task='b/c') 가
+    동일 runId 'p/a/b/c/type/r01' 로 충돌해 중앙 인덱스에서 다른 run 을
+    가리키거나 show/rerun 이 잘못된 run 을 대상으로 동작한다. okstra.sh 가
+    프로젝트 로컬 디렉터리에서 사용하는 slugify_value 와 동일 규칙이라
+    raw 매니페스트 값과 일관된 키를 얻는다.
+    """
+    seq = f"{run_seq:02d}" if run_seq < 100 else str(run_seq)
+    return (f"{_safe_fs_segment(project_id)}/{_safe_fs_segment(task_group)}"
+            f"/{_safe_fs_segment(task_id)}/{_safe_fs_segment(task_type)}/r{seq}")
+
+
+def parse_run_id(run_id: str) -> Dict[str, object]:
+    """runId 슬러그를 5-tuple dict 로 분해한다. 형식이 틀리면 ValueError."""
+    match = _RUN_ID_PATTERN.match(run_id)
+    if not match:
+        raise ValueError(f"invalid runId: {run_id!r}")
+    return {
+        "projectId": match.group("projectId"),
+        "taskGroup": match.group("taskGroup"),
+        "taskId": match.group("taskId"),
+        "taskType": match.group("taskType"),
+        "runSeq": int(match.group("runSeq")),
+    }
+
+
+def _safe_fs_segment(value: str) -> str:
+    """파일시스템 경로 컴포넌트로 사용하기 전에 정규화한다.
+    task_group/task_id 등은 CLI 와 manifest 에서 들어오므로 검증되지 않은
+    상태이며, `/` 나 `..` 가 들어 있으면 invocations 디렉터리 밖으로
+    탈출해 다른 프로젝트의 central 트리를 오염시킬 수 있다. okstra.sh
+    의 slugify_value 와 동일한 규칙(`[a-z0-9-]+`) 으로 강제 정규화해
+    위험 문자를 모두 제거한다. 정규화 결과가 비어 있으면 `_` 로
+    대체해 빈 path 컴포넌트가 만들어지는 것도 차단한다.
+    """
+    slug = slugify_task_segment(value)
+    return slug if slug else "_"
+
+
+def _escape_segment_for_join(segment: str) -> str:
+    """세그먼트 내부의 `-` 를 `--` 로 escape 해 단일 `-` 조인 시에도
+    원래 슬래시 경계를 손실 없이 복원할 수 있게 한다.
+    슬러그 정규화 결과(`[a-z0-9-]+`) 와 호환되며, 디코더는 단일 `-` 가
+    경계, 이중 `-` 가 세그먼트 내부 하이픈임을 식별할 수 있다.
+    """
+    return segment.replace("-", "--")
+
+
+def run_id_to_session_name(run_id: str) -> str:
+    """tmux 세션명으로 변환한다. 'okstra-' 접두사 + 세그먼트 escape 후 `-` 조인.
+    예: 'a/b-c/r01' → 'okstra-a-b--c-r01'. 세그먼트 내부 `-` 는 `--` 로
+    이스케이프되어, 슬래시 위치가 다른 두 runId 가 동일 세션명으로
+    충돌하지 않는다. 세그먼트는 fs-safe 슬러그로 강제 정규화해
+    `..` 같은 traversal 토큰이 세션명에 그대로 노출되지 않게 한다.
+    """
+    parts = [_escape_segment_for_join(_safe_fs_segment(seg))
+             for seg in run_id.split("/")]
+    return "okstra-" + "-".join(parts)
+
+
+def slugify_task_segment(value: str) -> str:
+    """Match okstra.sh slugify_value for task directory segments."""
+    return _re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")