okstra 0.1.0

package/runtime/python/okstra_ctl/path_resolve.py

@@ -0,0 +1,40 @@
+"""User-supplied file path resolution.
+
+bash `resolve_brief_path`, `resolve_clarification_response_path`,
+`relative_to_project_root` 의 python 구현. 우선순위: 절대/cwd-기준 → project
+root 기준 → None.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+
+def resolve_user_file(raw: str, project_root: Path) -> Optional[Path]:
+    """`raw` 가 (a) 절대경로 또는 cwd 기준으로 존재하면 그 절대경로
+    (b) project_root 기준으로 존재하면 그 경로 (c) 둘 다 실패면 None.
+
+    bash 구현과 동일 의미. cwd-우선이 의도된 동작이다 — 사용자가 IDE 에서
+    프로젝트 일부 디렉터리에 cd 한 채 상대경로를 줄 수 있어야 함.
+    """
+    if not raw:
+        return None
+    p = Path(raw)
+    if p.is_file():
+        return p.resolve()
+    if not p.is_absolute():
+        in_root = Path(project_root) / raw
+        if in_root.is_file():
+            return in_root.resolve()
+    return None
+
+
+def relative_to_project_root(path: Path, project_root: Path) -> str:
+    """project_root 안의 경로면 그 기준 상대경로 문자열을, 바깥이면 입력값
+    그대로 돌려준다."""
+    project_root = Path(project_root).resolve()
+    path = Path(path)
+    try:
+        return str(path.resolve().relative_to(project_root))
+    except (ValueError, OSError):
+        return str(path)

package/runtime/python/okstra_ctl/paths.py

@@ -0,0 +1,251 @@
+"""Pure path computation for an okstra run.
+
+Inputs: project root, identity (project-id/task-group/task-id), task-type,
+workspace root, optional run-seq override.
+
+Output: dict with every path value the bash render-context used to expose as
+environment variables (TASK_ROOT, RUN_DIR, RUN_MANIFESTS_DIR, RUN_MANIFEST_FILE,
+FINAL_REPORT_FILE, ...). 호출자가 이 dict 를 그대로 인자로 사용하거나
+`write_run_context()` 로 디스크에 박는다.
+
+이 모듈은 read-only 한 path 계산만 담당한다. 디렉터리 생성, 파일 쓰기,
+seq advancement 같은 부수효과는 `run_context.py` 가 담당한다.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+from okstra_project.state import slugify
+
+OKSTRA_RELATIVE = Path(".project-docs/okstra")
+TASKS_RELATIVE = OKSTRA_RELATIVE / "tasks"
+DISCOVERY_RELATIVE = OKSTRA_RELATIVE / "discovery"
+
+
+def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
+    """run_seq_dir 안에서 `*-<task-type>-NNN.<ext>` 파일을 스캔해 다음 seq 번호를
+    돌려준다. 디렉터리 부재 시 1.
+    """
+    pattern = re.compile(rf"-{re.escape(task_type_segment)}-(\d{{3}})\.[^.]+$")
+    max_seq = 0
+    if run_seq_dir.is_dir():
+        for entry in os.listdir(run_seq_dir):
+            full = run_seq_dir / entry
+            if not full.is_file():
+                continue
+            m = pattern.search(entry)
+            if m:
+                n = int(m.group(1))
+                if n > max_seq:
+                    max_seq = n
+    return max_seq + 1
+
+
+def _rel(project_root: Path, target: Path) -> str:
+    """target 을 project_root 기준 상대경로 문자열로 변환. project_root 바깥이면
+    절대경로 그대로 돌려준다(workspace-root 같은 경우)."""
+    try:
+        return str(target.resolve().relative_to(project_root.resolve()))
+    except (ValueError, OSError):
+        return str(target)
+
+
+def compute_run_paths(
+    *,
+    project_root: Path,
+    workspace_root: Path,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    task_type: str,
+    run_seq_override: Optional[int] = None,
+) -> dict:
+    """주어진 identity 와 task-type 에 대해 모든 path/segment 값을 계산해
+    dict 로 돌려준다. 부수효과 없음.
+
+    run_seq_override: 정수가 주어지면 7개 seq 모두 그 값으로 강제. okstra-ctl
+    rerun 처럼 외부에서 seq 를 미리 reserve 한 경로용. 미지정 시 디스크 스캔
+    결과로 결정.
+    """
+    project_root = Path(project_root)
+    workspace_root = Path(workspace_root)
+
+    task_group_segment = slugify(task_group)
+    task_id_segment = slugify(task_id)
+    task_type_segment = slugify(task_type)
+
+    if not task_group_segment or not task_id_segment:
+        raise ValueError(
+            "task-group and task-id must contain at least one alphanumeric character")
+    if not task_type_segment:
+        raise ValueError("task-type must contain at least one alphanumeric character")
+
+    okstra_root = project_root / OKSTRA_RELATIVE
+    tasks_root = project_root / TASKS_RELATIVE
+    discovery_dir = project_root / DISCOVERY_RELATIVE
+
+    task_root = tasks_root / task_group_segment / task_id_segment
+    task_manifest = task_root / "task-manifest.json"
+    task_index = task_root / "task-index.md"
+    instruction_set = task_root / "instruction-set"
+    runs_dir = task_root / "runs"
+    history_dir = task_root / "history"
+    timeline_file = history_dir / "timeline.json"
+
+    run_dir = runs_dir / task_type_segment
+    run_manifests = run_dir / "manifests"
+    run_state = run_dir / "state"
+    run_prompts = run_dir / "prompts"
+    run_reports = run_dir / "reports"
+    run_status = run_dir / "status"
+    run_sessions = run_dir / "sessions"
+    run_logs = run_dir / "logs"
+    worker_results = run_dir / "worker-results"
+
+    if run_seq_override is not None:
+        seq_int = int(run_seq_override)
+        seqs = {k: f"{seq_int:03d}" for k in (
+            "manifests", "prompts", "reports", "status", "state",
+            "sessions", "worker_results")}
+    else:
+        seqs = {
+            "manifests": f"{next_run_seq(run_manifests, task_type_segment):03d}",
+            "prompts": f"{next_run_seq(run_prompts, task_type_segment):03d}",
+            "reports": f"{next_run_seq(run_reports, task_type_segment):03d}",
+            "status": f"{next_run_seq(run_status, task_type_segment):03d}",
+            "state": f"{next_run_seq(run_state, task_type_segment):03d}",
+            "sessions": f"{next_run_seq(run_sessions, task_type_segment):03d}",
+            "worker_results": f"{next_run_seq(worker_results, task_type_segment):03d}",
+        }
+
+    suffixes = {k: f"-{task_type_segment}-{v}" for k, v in seqs.items()}
+    run_file_suffix = suffixes["reports"]
+
+    run_manifest_file = run_manifests / f"run-manifest{suffixes['manifests']}.json"
+    run_prompt_snapshot = run_prompts / f"claude-execution-prompt{suffixes['prompts']}.md"
+    claude_worker_prompt = run_prompts / f"claude-worker-prompt{suffixes['prompts']}.md"
+    codex_worker_prompt = run_prompts / f"codex-worker-prompt{suffixes['prompts']}.md"
+    gemini_worker_prompt = run_prompts / f"gemini-worker-prompt{suffixes['prompts']}.md"
+    report_writer_worker_prompt = run_prompts / f"report-writer-worker-prompt{suffixes['prompts']}.md"
+    final_report = run_reports / f"final-report{suffixes['reports']}.md"
+    final_status = run_status / f"final{suffixes['status']}.status"
+    team_state = run_state / f"team-state{suffixes['state']}.json"
+    final_report_template = instruction_set / "final-report-template.md"
+    reference_expectations = instruction_set / "reference-expectations.md"
+    claude_resume_command = run_sessions / f"claude-resume{suffixes['sessions']}.sh"
+    latest_task_file = discovery_dir / "latest-task.json"
+    task_catalog_file = discovery_dir / "task-catalog.json"
+    claude_worker_result = worker_results / f"claude-worker{suffixes['worker_results']}.md"
+    codex_worker_result = worker_results / f"codex-worker{suffixes['worker_results']}.md"
+    gemini_worker_result = worker_results / f"gemini-worker{suffixes['worker_results']}.md"
+    report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
+
+    run_validator_script = workspace_root / "validators" / "validate-run.py"
+
+    abs_paths = {
+        "PROJECT_ID": project_id,
+        "PROJECT_ROOT": str(project_root),
+        "WORKSPACE_ROOT": str(workspace_root),
+        "TASK_GROUP": task_group,
+        "TASK_ID": task_id,
+        "TASK_KEY": f"{project_id}:{task_group}:{task_id}",
+        "ANALYSIS_TYPE": task_type,
+        "TASK_GROUP_SEGMENT": task_group_segment,
+        "TASK_ID_SEGMENT": task_id_segment,
+        "TASK_TYPE_SEGMENT": task_type_segment,
+        "OKSTRA_ROOT": str(okstra_root),
+        "OKSTRA_TASKS_ROOT": str(tasks_root),
+        "OKSTRA_DISCOVERY_DIR": str(discovery_dir),
+        "TASK_ROOT": str(task_root),
+        "TASK_MANIFEST_FILE": str(task_manifest),
+        "TASK_INDEX_FILE": str(task_index),
+        "INSTRUCTION_SET_DIR": str(instruction_set),
+        "RUNS_DIR": str(runs_dir),
+        "HISTORY_DIR": str(history_dir),
+        "TIMELINE_FILE": str(timeline_file),
+        "RUN_DIR": str(run_dir),
+        "RUN_MANIFESTS_DIR": str(run_manifests),
+        "RUN_STATE_DIR": str(run_state),
+        "RUN_PROMPTS_DIR": str(run_prompts),
+        "RUN_REPORTS_DIR": str(run_reports),
+        "RUN_STATUS_DIR": str(run_status),
+        "RUN_SESSIONS_DIR": str(run_sessions),
+        "RUN_LOGS_DIR": str(run_logs),
+        "WORKER_RESULTS_DIR": str(worker_results),
+        "RUN_MANIFEST_FILE": str(run_manifest_file),
+        "RUN_PROMPT_SNAPSHOT_FILE": str(run_prompt_snapshot),
+        "CLAUDE_WORKER_PROMPT_FILE": str(claude_worker_prompt),
+        "CODEX_WORKER_PROMPT_FILE": str(codex_worker_prompt),
+        "GEMINI_WORKER_PROMPT_FILE": str(gemini_worker_prompt),
+        "REPORT_WRITER_WORKER_PROMPT_FILE": str(report_writer_worker_prompt),
+        "FINAL_REPORT_FILE": str(final_report),
+        "FINAL_STATUS_FILE": str(final_status),
+        "TEAM_STATE_FILE": str(team_state),
+        "FINAL_REPORT_TEMPLATE_FILE": str(final_report_template),
+        "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
+        "CLAUDE_RESUME_COMMAND_FILE": str(claude_resume_command),
+        "OKSTRA_LATEST_TASK_FILE": str(latest_task_file),
+        "OKSTRA_TASK_CATALOG_FILE": str(task_catalog_file),
+        "CLAUDE_WORKER_RESULT_FILE": str(claude_worker_result),
+        "CODEX_WORKER_RESULT_FILE": str(codex_worker_result),
+        "GEMINI_WORKER_RESULT_FILE": str(gemini_worker_result),
+        "REPORT_WRITER_WORKER_RESULT_FILE": str(report_writer_worker_result),
+        "RUN_VALIDATOR_SCRIPT": str(run_validator_script),
+        "RUN_MANIFEST_FILENAME": run_manifest_file.name,
+        "RUN_PROMPT_SNAPSHOT_FILENAME": run_prompt_snapshot.name,
+        "FINAL_REPORT_FILENAME": final_report.name,
+        "FINAL_STATUS_FILENAME": final_status.name,
+        "CLAUDE_RESUME_COMMAND_FILENAME": claude_resume_command.name,
+        "RUN_FILE_SUFFIX": run_file_suffix,
+        "RUN_MANIFESTS_SEQ": seqs["manifests"],
+        "RUN_PROMPTS_SEQ": seqs["prompts"],
+        "RUN_REPORTS_SEQ": seqs["reports"],
+        "RUN_STATUS_SEQ": seqs["status"],
+        "RUN_STATE_SEQ": seqs["state"],
+        "RUN_SESSIONS_SEQ": seqs["sessions"],
+        "WORKER_RESULTS_SEQ": seqs["worker_results"],
+        "LATEST_RUN_PATH": str(run_dir),
+    }
+    rel_pairs = [
+        ("OKSTRA_DISCOVERY_RELATIVE_PATH", discovery_dir),
+        ("OKSTRA_LATEST_TASK_RELATIVE_PATH", latest_task_file),
+        ("OKSTRA_TASK_CATALOG_RELATIVE_PATH", task_catalog_file),
+        ("TASK_ROOT_RELATIVE_PATH", task_root),
+        ("TASK_MANIFEST_RELATIVE_PATH", task_manifest),
+        ("TASK_INDEX_RELATIVE_PATH", task_index),
+        ("INSTRUCTION_SET_RELATIVE_PATH", instruction_set),
+        ("RUNS_RELATIVE_PATH", runs_dir),
+        ("HISTORY_RELATIVE_PATH", history_dir),
+        ("TIMELINE_RELATIVE_PATH", timeline_file),
+        ("RUN_DIR_RELATIVE_PATH", run_dir),
+        ("RUN_MANIFESTS_RELATIVE_PATH", run_manifests),
+        ("RUN_STATE_RELATIVE_PATH", run_state),
+        ("RUN_PROMPTS_RELATIVE_PATH", run_prompts),
+        ("RUN_REPORTS_RELATIVE_PATH", run_reports),
+        ("RUN_STATUS_RELATIVE_PATH", run_status),
+        ("RUN_SESSIONS_RELATIVE_PATH", run_sessions),
+        ("RUN_MANIFEST_RELATIVE_PATH", run_manifest_file),
+        ("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", run_prompt_snapshot),
+        ("CLAUDE_WORKER_PROMPT_RELATIVE_PATH", claude_worker_prompt),
+        ("CODEX_WORKER_PROMPT_RELATIVE_PATH", codex_worker_prompt),
+        ("GEMINI_WORKER_PROMPT_RELATIVE_PATH", gemini_worker_prompt),
+        ("REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH", report_writer_worker_prompt),
+        ("FINAL_REPORT_RELATIVE_PATH", final_report),
+        ("FINAL_STATUS_RELATIVE_PATH", final_status),
+        ("TEAM_STATE_RELATIVE_PATH", team_state),
+        ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
+        ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),
+        ("REFERENCE_EXPECTATIONS_RELATIVE_PATH", reference_expectations),
+        ("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", claude_resume_command),
+        ("RUN_VALIDATOR_RELATIVE_PATH", run_validator_script),
+        ("CLAUDE_WORKER_RESULT_RELATIVE_PATH", claude_worker_result),
+        ("CODEX_WORKER_RESULT_RELATIVE_PATH", codex_worker_result),
+        ("GEMINI_WORKER_RESULT_RELATIVE_PATH", gemini_worker_result),
+        ("REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", report_writer_worker_result),
+        ("LATEST_RUN_RELATIVE_PATH", run_dir),
+    ]
+    rel_paths = {key: _rel(project_root, target) for key, target in rel_pairs}
+    return {**abs_paths, **rel_paths}

package/runtime/python/okstra_ctl/project_meta.py

@@ -0,0 +1,51 @@
+"""프로젝트 meta.json 업서트."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def _project_meta_path(home: Path, project_id: str) -> Path:
+    return home / "projects" / project_id / "meta.json"
+
+
+def load_project_meta(home: Path, project_id: str) -> Optional[dict]:
+    """프로젝트 meta.json 을 읽는다. 없으면 None."""
+    p = _project_meta_path(home, project_id)
+    if not p.is_file():
+        return None
+    return json.loads(p.read_text())
+
+
+def upsert_project_meta(home: Path, project_id: str, *,
+                        project_root: str, when: str,
+                        started: bool = False, finished: bool = False) -> None:
+    """프로젝트 meta.json 을 read-modify-write 로 갱신.
+    started=True 면 runCount+1, activeCount+1, lastRunAt 갱신, 최초이면 firstRunAt 도 설정.
+    finished=True 면 activeCount-1, 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": project_root,
+            "firstRunAt": when,
+            "lastRunAt": when,
+            "runCount": 0,
+            "activeCount": 0,
+        }
+    meta["projectRoot"] = project_root
+    meta["lastRunAt"] = when
+    if started:
+        meta["runCount"] = int(meta.get("runCount", 0)) + 1
+        meta["activeCount"] = int(meta.get("activeCount", 0)) + 1
+    if finished:
+        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/reconcile.py

@@ -0,0 +1,166 @@
+"""reconciliation/normalization."""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
+from .locks import central_lock
+from .project_meta import upsert_project_meta
+
+
+DEFAULT_ABORT_AFTER_SECONDS = 12 * 3600  # 12시간 무진척이면 aborted 로 간주
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(tzinfo=None).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse_iso(ts: str) -> Optional[datetime]:
+    try:
+        return datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ")
+    except (ValueError, TypeError):
+        return None
+
+
+def normalize_central_status(manifest_status: str, validation_status: str) -> str:
+    """Map okstra manifest/validation statuses to control-center statuses."""
+    failed_values = {
+        "failed",
+        "contract-violation",
+        "contract-violated",
+        "validation-failed",
+    }
+    manifest_status = str(manifest_status or "")
+    validation_status = str(validation_status or "")
+    if manifest_status in failed_values or validation_status in failed_values:
+        return "failed"
+    if manifest_status in {"aborted", "prepared", "running", "in-progress"}:
+        return manifest_status
+    if manifest_status in {"error", "errored"}:
+        return "failed"
+    return "completed"
+
+
+def normalize_reconciled_report_status(validation_status: str) -> str:
+    """Final report existence means terminal success unless validation failed."""
+    return normalize_central_status("completed", validation_status)
+
+
+def _read_run_manifest_validation(project_root: Path, run_dir_rel: str,
+                                  task_type: str, run_seq: int) -> str:
+    """run-manifest 의 validation.status 를 읽는다. 못 읽으면 'not-run'.
+    완료/실패 여부를 정확히 반영하기 위함 — 단순히 final-report 존재만으로
+    'passed' 로 판정하면 contract-violation/failed 를 잘못 기록한다.
+    """
+    if not run_dir_rel:
+        return "not-run"
+    suffix = f"-{task_type}-{run_seq:03d}"
+    manifest = project_root / run_dir_rel / "manifests" / f"run-manifest{suffix}.json"
+    if not manifest.is_file():
+        return "not-run"
+    try:
+        data = json.loads(manifest.read_text())
+    except (OSError, json.JSONDecodeError):
+        return "not-run"
+    validation = data.get("validation")
+    if isinstance(validation, dict):
+        return str(validation.get("status") or "not-run")
+    if isinstance(validation, str):
+        return validation
+    return "not-run"
+
+
+def reconcile_active(home: Path, *,
+                     abort_after_seconds: int = DEFAULT_ABORT_AFTER_SECONDS,
+                     project: Optional[str] = None) -> dict:
+    """active.jsonl 의 각 행을 검사해 종결 추론. 종결된 행은 recent 로 이동.
+    project 가 주어지면 해당 projectId 행만 추론 대상으로 삼고, 다른 프로젝트
+    행은 그대로 보존한다(스코프 reconcile).
+    중앙 락 안에서 read-modify-write 하므로 동시에 일어나는 record_start 와
+    같은 active 행 append 가 누락되지 않는다.
+    """
+    with central_lock(home):
+        return _reconcile_active_locked(home,
+                                        abort_after_seconds=abort_after_seconds,
+                                        project=project)
+
+
+def _reconcile_active_locked(home: Path, *,
+                             abort_after_seconds: int,
+                             project: Optional[str] = None) -> dict:
+    active = home / "active.jsonl"
+    summary = {"completed": 0, "aborted": 0, "running": 0}
+    rows = read_jsonl(active)
+    if not rows:
+        return summary
+    survivors = []
+    promoted = []
+    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    for row in rows:
+        # project 필터: 스코프 외 행은 추론 없이 active 에 그대로 남긴다.
+        if project and row.get("projectId") != project:
+            survivors.append(row)
+            summary["running"] += 1
+            continue
+        project_root = Path(row.get("projectRoot", ""))
+        final_rel = row.get("finalReportRel", "")
+        final_abs = project_root / final_rel if final_rel else None
+        if final_abs and final_abs.is_file():
+            validation_status = _read_run_manifest_validation(
+                project_root, row.get("runDirRel", ""),
+                row.get("taskType", ""), int(row.get("runSeq", 0)))
+            # validate-okstra-run.py 가 아직 실행되지 않은 시점에는 final-report
+            # 만 존재하고 validation 은 'not-run' 으로 보고된다. 이때 promote 하면
+            # normalize_reconciled_report_status 가 'completed' 로 매핑하여 행이
+            # recent 로 옮겨가고, 이후 validator 가 failed/contract-violated 를
+            # 기록해도 reconcile 이 다시 보지 않아 영구히 잘못된 상태로 남는다.
+            # validation 이 terminal 신호('not-run' 이외) 일 때만 promote 하고,
+            # 그 외에는 active 에 유지해 후속 reconcile / abort timeout 에 맡긴다.
+            if validation_status and validation_status != "not-run":
+                row["status"] = normalize_reconciled_report_status(validation_status)
+                row["finishedAt"] = _now_iso()
+                row["validation"] = validation_status
+                promoted.append(row)
+                if row["status"] == "completed":
+                    summary["completed"] += 1
+                else:
+                    summary["completed"] += 0  # 실패도 종결로 분류하지만 카운터는 분리
+                continue
+        started = _parse_iso(row.get("startedAt", ""))
+        if started and (now - started).total_seconds() > abort_after_seconds:
+            row["status"] = "aborted"
+            row["finishedAt"] = _now_iso()
+            promoted.append(row)
+            summary["aborted"] += 1
+            continue
+        survivors.append(row)
+        summary["running"] += 1
+    if not promoted:
+        return summary
+    tmp = active.with_suffix(".jsonl.tmp")
+    with tmp.open("w") as f:
+        for row in survivors:
+            f.write(json.dumps(row, separators=(",", ":")) + "\n")
+    os.replace(tmp, active)
+    for row in promoted:
+        append_jsonl(home / "recent.jsonl", row)
+        proj_index = home / "projects" / row["projectId"] / "index.jsonl"
+        if proj_index.is_file():
+            existing = read_jsonl(proj_index)
+            for er in existing:
+                if er.get("runId") == row["runId"]:
+                    er.update({k: row[k] for k in ("status", "finishedAt", "validation")})
+            tmp = proj_index.with_suffix(".jsonl.tmp")
+            with tmp.open("w") as f:
+                for er in existing:
+                    f.write(json.dumps(er, separators=(",", ":")) + "\n")
+            os.replace(tmp, proj_index)
+        upsert_project_meta(home, row["projectId"],
+                            project_root=row["projectRoot"],
+                            when=row["finishedAt"], finished=True)
+    rotate_recent_if_needed(home)
+    return summary