okstra 0.96.1 → 0.97.1

package/runtime/python/okstra_ctl/report_views.py

@@ -63,6 +63,7 @@ from .clarification_items import (
     parse_clarification_items,
     parse_meta_cell,
     scan_approval_gate,
+    section_1_present_but_unparsed,
 )
 from .md_table import is_separator_row as _is_separator_row
 
@@ -716,6 +717,28 @@ def _col_class(col_idx: int, narrow_cols: set[int]) -> str:
     return ' class="td-narrow"' if col_idx in narrow_cols else ""
 
 
+_DANGEROUS_URL_SCHEME_RE = re.compile(
+    r"^(?:javascript|data|vbscript):", re.IGNORECASE
+)
+_URL_CONTROL_CHARS_RE = re.compile(r"[\x00-\x20]")
+
+
+def _safe_href(url: str) -> str:
+    """Neutralise a markdown link target so it cannot become a script
+    vector in the offline HTML report.
+
+    The self-contained report is opened locally from disk, so a
+    ``javascript:``/``data:``/``vbscript:`` href in any worker-authored
+    cell would execute attacker JS on click. ``html.escape`` in
+    ``_inline`` only neutralises quotes, not the scheme, so strip such
+    schemes here. Browsers strip ASCII whitespace/control chars from an
+    href before resolving the scheme (so ``java\\tscript:`` executes); strip
+    that same class before matching to close the bypass. Relative paths,
+    fragments, ``http(s):`` and ``mailto:`` pass through unchanged."""
+    stripped = _URL_CONTROL_CHARS_RE.sub("", url or "")
+    return "#" if _DANGEROUS_URL_SCHEME_RE.match(stripped) else url
+
+
 def _inline(text: str) -> str:
     out = html.escape(text)
     # Restore inline markdown after escaping (we re-process the escaped
@@ -723,7 +746,7 @@ def _inline(text: str) -> str:
     out = _INLINE_CODE_PATTERN.sub(lambda m: f"<code>{m.group(1)}</code>", out)
     out = _BOLD_PATTERN.sub(lambda m: f"<strong>{m.group(1)}</strong>", out)
     out = _LINK_PATTERN.sub(
-        lambda m: f'<a href="{m.group(2)}">{m.group(1)}</a>', out
+        lambda m: f'<a href="{_safe_href(m.group(2))}">{m.group(1)}</a>', out
     )
     # Preserve explicit <br> line breaks used inside compact meta cells (the
     # markdown source intentionally stacks short fields with <br>). html.escape
@@ -885,14 +908,19 @@ def plan_approval_context(
 def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
     """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
     접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
-    허용하고, 그래도 없으면 첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가
-    되어 브라우저 자동선택분의 묵시 Export 를 차단한다."""
+    허용하되, 후보 이름이 서로의 접두여서 둘 이상이 매칭되면 모호하므로 채택하지
+    않고 첫 후보로 폴백한다 — 임의의 한 후보를 권장으로 잘못 표시하느니 결정적인
+    폴백이 낫다. 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의 묵시
+    Export 를 차단한다."""
     if rec_name in names:
         return rec_name
     if rec_name:
-        for name in names:
-            if name.startswith(rec_name) or rec_name.startswith(name):
-                return name
+        matches = [
+            name for name in names
+            if name.startswith(rec_name) or rec_name.startswith(name)
+        ]
+        if len(matches) == 1:
+            return matches[0]
     return names[0]
 
 
@@ -964,6 +992,19 @@ def render_html_view(
     one when the report no longer needs a view."""
     src_text = src_md_path.read_text(encoding="utf-8")
     html_path = src_md_path.with_name(src_md_path.stem + ".html")
+    # Fail-closed on §1 heading drift: when a `## 1. Clarification Items`
+    # heading exists but its strict form does not parse,
+    # `report_has_clarification_items` returns False (lenient parse), so a
+    # report with real C-rows would silently get no interactive view and the
+    # user would lose the only way to answer. `validate-report-views.py`
+    # already refuses this case; refuse loudly here too instead of skipping.
+    if section_1_present_but_unparsed(src_text):
+        raise ValueError(
+            "final-report has a `## 1. Clarification Items` heading but its "
+            "strict format does not parse (heading/anchor/format drift) — "
+            "re-render the report so §1 matches the schema before generating "
+            "the HTML view."
+        )
     approval_ctx = plan_approval_context(src_md_path, src_text)
     if not report_has_clarification_items(src_text) and approval_ctx is None:
         if html_path.is_file():

package/runtime/python/okstra_ctl/run.py

@@ -51,6 +51,7 @@ from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
     inject_lead_prompt_computed_tokens,
+    migrate_legacy_run_artifacts,
     render_active_run_context,
     render_latest_task_discovery,
     render_reference_expectations,
@@ -90,13 +91,13 @@ from .workers import (
 from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from . import stage_targets as _stage_targets
+from . import stage_integrate as _stage_integrate
 from . import implementation_stage as _implementation_stage
 from .stage_reconcile import (
     auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
 )
 from .worktree import (
     WorktreeProvision,
-    okstra_clean_gate_excludes,
     provision_task_worktree,
 )
 
@@ -129,7 +130,9 @@ IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN = re.compile(
     re.MULTILINE,
 )
 
-_FRONTMATTER_BLOCK_PATTERN = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+# validators/validate-run.py:_FRONTMATTER_BLOCK_RE 의 미러 — 선행 BOM/빈 줄을
+# 허용해 두 모듈이 같은 리포트의 frontmatter 게이트를 동일하게 판정하게 한다.
+_FRONTMATTER_BLOCK_PATTERN = re.compile(r"\A\ufeff?\s*---\n(.*?)\n---\n", re.DOTALL)
 
 
 def _extract_frontmatter_block(body: str) -> str | None:
@@ -269,8 +272,18 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
         encoding="utf-8",
     )
     md_tmp.write_text(rendered, encoding="utf-8")
+    # 두 파일을 같이 atomic 하게 commit 할 수 없으므로, 첫 replace 직전의
+    # data.json 바이트를 보관했다가 markdown replace 가 실패하면 data.json 을
+    # 되돌린다. 이렇게 하면 부분 실패가 "둘 다 approved 이전(consistent)" 상태로
+    # 수렴해 이후 _validate_data_json_approval_consistency 의 hard-fail 을 막는다
+    # (남는 불일치 창은 두 replace 사이의 hard process kill 뿐).
+    data_prev = data_path.read_bytes()
     data_tmp.replace(data_path)
-    md_tmp.replace(path)
+    try:
+        md_tmp.replace(path)
+    except OSError:
+        data_path.write_bytes(data_prev)
+        raise
     return True
 
 
@@ -453,11 +466,6 @@ def _resolve_effective_stages(
         raise _stage_target_prepare_error(exc) from exc
 
 
-def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
-    """Compatibility wrapper for tests and older internal callers."""
-    return _stage_targets.commit_is_ancestor(project_root, ancestor, descendant)
-
-
 def _check_multi_dep_merged(project_root, plan_run_root, latest,
                             pred_commits: dict, candidate_base: str,
                             stage_n: int) -> None:
@@ -699,61 +707,6 @@ def _ensure_task_directories(ctx: dict) -> None:
         Path(ctx[key]).mkdir(parents=True, exist_ok=True)
 
 
-def _migrate_legacy_run_artifacts(ctx: dict) -> None:
-    """run/<task-type>/ 바로 아래에 남아 있을 수 있는 legacy 파일을 카테고리
-    하위 디렉터리(`manifests/`, `state/`, ...) 로 이동한다.
-    """
-    project_root = Path(ctx["PROJECT_ROOT"])
-    task_root = Path(ctx["TASK_ROOT"])
-    run_dir = Path(ctx["RUN_DIR"])
-    if not run_dir.is_dir():
-        return
-    legacy = [
-        ("run-manifest-", ".json", Path(ctx["RUN_MANIFESTS_DIR"])),
-        ("team-state-", ".json", Path(ctx["RUN_STATE_DIR"])),
-        ("claude-execution-prompt-", ".md", Path(ctx["RUN_PROMPTS_DIR"])),
-        ("final-report-", ".md", Path(ctx["RUN_REPORTS_DIR"])),
-        ("final-", ".status", Path(ctx["RUN_STATUS_DIR"])),
-        ("claude-resume-", ".sh", Path(ctx["RUN_SESSIONS_DIR"])),
-    ]
-    rewrites: dict[str, str] = {}
-    for entry in run_dir.iterdir():
-        if not entry.is_file():
-            continue
-        for prefix, suffix, target_dir in legacy:
-            if not (entry.name.startswith(prefix) and entry.name.endswith(suffix)):
-                continue
-            target_dir.mkdir(parents=True, exist_ok=True)
-            dest = target_dir / entry.name
-            old_rel = str(entry.relative_to(project_root))
-            new_rel = str(dest.relative_to(project_root))
-            if dest.exists():
-                try:
-                    if entry.read_bytes() == dest.read_bytes():
-                        entry.unlink()
-                        rewrites[old_rel] = new_rel
-                except Exception:
-                    pass
-                break
-            shutil.move(str(entry), str(dest))
-            rewrites[old_rel] = new_rel
-            break
-    if not rewrites:
-        return
-    for path in task_root.rglob("*"):
-        if not path.is_file() or path.suffix not in {".json", ".md", ".txt", ".sh"}:
-            continue
-        try:
-            original = path.read_text(encoding="utf-8")
-        except Exception:
-            continue
-        updated = original
-        for o, n in rewrites.items():
-            updated = updated.replace(o, n)
-        if updated != original:
-            path.write_text(updated, encoding="utf-8")
-
-
 def _record_start(
     *,
     workspace_root: Path,
@@ -766,10 +719,10 @@ def _record_start(
     """record_start hook 호출. okstra-central.sh 의 bash wrapper 와 같은 동작
     이지만 python 직접 호출이라 환경 변수 의존 없음.
     """
-    import fcntl
     import json as _json
     from datetime import datetime, timezone
     from okstra_ctl import record_start
+    from .locks import central_lock
 
     home = okstra_home()
     home.mkdir(mode=0o700, parents=True, exist_ok=True)
@@ -787,10 +740,9 @@ def _record_start(
             "backfilledAt": None,
         }, indent=2) + "\n", encoding="utf-8")
         os.chmod(state_file, 0o600)
-    lockfile = home / ".lock"
-    lockfile.touch()
-    with lockfile.open("r+") as lock:
-        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+    # 중앙 인덱스 락은 reconcile.py 와 공유하는 central_lock 단일 기준점을 쓴다.
+    # 직접 flock 을 손으로 깔면 락 파일/모드가 두 경로에서 갈라질 수 있다.
+    with central_lock(home):
         record_start(
             home,
             project_id=ctx["PROJECT_ID"],
@@ -814,6 +766,31 @@ def _record_start(
         )
 
 
+def _remove_leaked_reservation(ctx: dict, run_seq: int) -> None:
+    """record_start 가 실패해 'reserving' row 를 'running' 으로 승격하지 못했을 때,
+    rerun 이 미리 박아 둔 예약 row 를 중앙 락 아래에서 제거해 누수를 막는다.
+    cleanup 자체가 실패해도 best-effort — prepare 결과를 무르지 않는다."""
+    from okstra_ctl import remove_reservation
+    from .locks import central_lock
+
+    try:
+        home = okstra_home()
+        with central_lock(home):
+            remove_reservation(
+                home,
+                project_id=ctx["PROJECT_ID"],
+                task_group=ctx["TASK_GROUP"],
+                task_id=ctx["TASK_ID"],
+                task_type=ctx.get("TASK_TYPE", ""),
+                run_seq=run_seq,
+            )
+    except Exception as exc:  # noqa: BLE001 — cleanup 실패는 비치명적
+        print(
+            f"okstra-central: reservation cleanup failed after record_start error ({exc})",
+            file=sys.stderr,
+        )
+
+
 def _brief_sha256(path: Path) -> str:
     import hashlib
 
@@ -1012,18 +989,28 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                 "--approved-plan <path-to-final-report.md>"
             )
         if inp.task_type == "implementation":
-            if inp.approve_plan_ack:
-                # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
-                # 파일의 frontmatter approved 를 true 로 toggle 한 뒤 동일한 검증
-                # 경로(`_validate_approved_plan`) 를 그대로 통과시킨다.
-                _apply_cli_approval(inp.approved_plan_path)
-            if inp.implementation_option:
-                # 유저가 고른 Option Candidate 이름을 approved-plan frontmatter 의
-                # `implementation-option:` 라인에 기록한다. 빈 값이면 implementation 이
-                # plan 의 `Recommended Option` 으로 폴백하므로 호출하지 않는다.
-                _apply_cli_implementation_option(
-                    inp.approved_plan_path, inp.implementation_option
-                )
+            # --approve / --implementation-option 은 공유 approved-plan 파일에
+            # read-modify-write 한다. 같은 task-key 의 동시 stage run 둘이 둘 다
+            # 이 플래그를 주면 후발 write 가 선발의 frontmatter 변경을 덮어쓴다
+            # (lost update). 두 mutation 을 per-task-key 락으로 직렬화한다.
+            if inp.approve_plan_ack or inp.implementation_option:
+                with worktree_provision_mutex(
+                    okstra_home(), inp.project_id,
+                    slugify(inp.task_group), slugify(inp.task_id),
+                ):
+                    if inp.approve_plan_ack:
+                        # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로
+                        # 모델링한다. frontmatter approved 를 true 로 toggle 한 뒤
+                        # 동일한 검증 경로(`_validate_approved_plan`)를 통과시킨다.
+                        _apply_cli_approval(inp.approved_plan_path)
+                    if inp.implementation_option:
+                        # 유저가 고른 Option Candidate 이름을 approved-plan
+                        # frontmatter 의 `implementation-option:` 라인에 기록한다.
+                        # 빈 값이면 implementation 이 plan 의 `Recommended Option`
+                        # 으로 폴백하므로 호출하지 않는다.
+                        _apply_cli_implementation_option(
+                            inp.approved_plan_path, inp.implementation_option
+                        )
             _validate_approved_plan(inp.approved_plan_path)
             _validate_stage_structure(inp.approved_plan_path)
         else:
@@ -1177,7 +1164,15 @@ def _materialize_release_handoff_input(
 
 
 def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
-    """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
+    """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다.
+
+    이 read-modify-write 는 같은 task-key 의 동시 implementation run 이 거치는
+    `_clear_stale_stage_waiver` 와 동일한 conformance-manifest.json 을 건드린다.
+    `_clear_stale_stage_waiver` 는 prepare_task_bundle 의 worktree_provision_mutex
+    안에서 실행되므로, 이 함수도 같은 per-task-key 락을 잡아 두 writer 를
+    직렬화한다. 락이 없으면 후발 write 가 선발의 waiver 변경을 덮어써(lost update)
+    verifier 가 Tier 3 conformance 를 건너뛰고 stage 를 가린다.
+    """
     if not inp.qa_waiver:
         return
     from .conformance import apply_qa_waiver, parse_qa_waiver_arg
@@ -1189,13 +1184,16 @@ def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> N
         )
     stage_key, reason = parsed
     manifest_path = task_dir(project_root, inp.task_group, inp.task_id) / "qa" / "conformance-manifest.json"
-    if not manifest_path.is_file():
-        raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
-    manifest = json.loads(manifest_path.read_text())
-    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    if not apply_qa_waiver(manifest, stage_key, reason, at=when):
-        raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
-    manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
+    with worktree_provision_mutex(
+        okstra_home(), inp.project_id, slugify(inp.task_group), slugify(inp.task_id),
+    ):
+        if not manifest_path.is_file():
+            raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
+        manifest = json.loads(manifest_path.read_text())
+        when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        if not apply_qa_waiver(manifest, stage_key, reason, at=when):
+            raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
+        manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
 
 
 def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: int) -> None:
@@ -1443,19 +1441,13 @@ def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> No
 
 
 def _is_ancestor(cwd, commit, head) -> bool:
-    if not commit or not head:
-        return False
-    r = _subprocess.run(
-        ["git", "-C", str(cwd), "merge-base", "--is-ancestor", commit, head],
-        capture_output=True, text=True,
-    )
-    return r.returncode == 0
+    from .worktree import is_ancestor
+    return is_ancestor(cwd, commit, head)
 
 
 def _is_dirty_excluding_okstra(cwd) -> bool:
-    excludes = [f":(exclude){p}" for p in okstra_clean_gate_excludes(Path(cwd))]
-    out = _git_out(cwd, "status", "--short", "--", ".", *excludes)
-    return bool(out.strip())
+    from .worktree import is_dirty_excluding_okstra
+    return is_dirty_excluding_okstra(cwd)
 
 
 def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
@@ -1469,6 +1461,24 @@ def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeP
     )
 
 
+def _format_integration(integ) -> str:
+    """stage 자동 통합 결과를 사람이 읽을 한국어 마크다운 블록으로 만든다."""
+    def _csv(xs):
+        return ", ".join(str(x) for x in xs) if xs else "없음"
+
+    skipped = "; ".join(f"stage {n}({why})" for n, why in integ.teardown_skipped)
+    lines = [
+        "- **Stage 자동 통합 결과** (whole-task final-verification):",
+        "- **머지된 stage:** " + _csv(integ.merged),
+        "- **이미 머지됨:** " + _csv(integ.already_merged),
+        "- **정리(teardown)된 stage:** " + _csv(integ.torn_down),
+        "- **정리 보류:** " + (skipped or "없음"),
+    ]
+    for w in integ.warnings:
+        lines.append("- **경고:** " + w)
+    return "\n".join(lines)
+
+
 def _reserve_final_verification_target(
     inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
 ) -> None:
@@ -1510,7 +1520,19 @@ def _reserve_final_verification_target(
         wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
         anchor = _reg.get_implementation_base(
             inp.project_id, inp.task_group, inp.task_id) or ""
+        try:
+            integ = _stage_integrate.integrate_stages(
+                project_id=inp.project_id, task_group=inp.task_group,
+                task_id=inp.task_id, task_worktree_path=wt_path,
+                stage_map=ctx_stage_map, done_rows=done_rows,
+            )
+        except _stage_integrate.IntegrateError as exc:
+            raise PrepareError(str(exc)) from exc
+        ctx["STAGE_INTEGRATION"] = _format_integration(integ)
         head = _git_out(wt_path, "rev-parse", "HEAD")
+        # integrate 가 registry 기반으로 머지/skip 한 것과 별개로, 각 stage done
+        # commit 이 실제 task HEAD 의 ancestor 인지 ground-truth 로 확인한다 —
+        # stage-key 가 이미 teardown 된 stage 라도 커밋이 HEAD 에 남아있으면 통과.
         from .consumers import latest_done_by_stage
         merged = {s: _is_ancestor(wt_path, r.get("head_commit", ""), head)
                   for s, r in latest_done_by_stage(done_rows).items()}
@@ -2060,7 +2082,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- prepare directories + cleanup ----
     _ensure_task_directories(ctx)
-    _migrate_legacy_run_artifacts(ctx)
+    migrate_legacy_run_artifacts(ctx)
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
     )
@@ -2121,8 +2143,14 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     except Exception as exc:
         print(
             f"okstra-central: record_start failed; central index will be incomplete ({exc})",
-            file=__import__("sys").stderr,
+            file=sys.stderr,
         )
+        # rerun 경로는 spawn 전에 'reserving' row 를 미리 박아 둔다
+        # (OKSTRA_RUN_SEQ_OVERRIDE 가 그 seq 를 강제한다). record_start 가
+        # 'reserving' → 'running' 승격에 실패하면 그 row 가 active.jsonl 에
+        # 영구히 남아 activeCount 를 부풀린다. 예약 seq 를 알 때만 정리한다.
+        if run_seq_override is not None:
+            _remove_leaked_reservation(ctx, run_seq_override)
 
     if not inp.render_only:
         _provision_settings_symlink(inp)

package/runtime/python/okstra_ctl/run_index_row.py

@@ -0,0 +1,118 @@
+"""run-index row 의 생성/축약/복원 단일 참조점.
+
+디스크에는 slim(14필드)로 저장하고, reader 는 hydrate 로 full(18필드)을 받는다.
+파생 4필드(taskType/runSeq/taskKey/invocationFile)는 runId 와 평면
+taskGroup/taskId 로부터 무손실 복원 가능하다. projectId 는 runId 슬러그가
+대소문자를 정규화(lowercase/slugify)해 raw 값을 잃으므로 파생이 아니라
+slim row 에 raw 로 보존한다 — taskGroup/taskId 와 동일한 이유다.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from .ids import build_run_id, parse_run_id
+from .invocation import invocation_path
+from .jsonl import read_jsonl
+
+DERIVED_FIELDS = ("taskType", "runSeq", "taskKey", "invocationFile")
+
+
+def build_run_index_row(*, project_id: str, project_root: str,
+                        task_group: str, task_id: str, task_type: str,
+                        run_seq: int, status: str, started_at: str,
+                        finished_at: Optional[str], workers: list, lead_model: str,
+                        validation: str, run_dir_rel: str,
+                        final_report_rel: str, final_status_rel: str) -> dict:
+    """slim run-index row(14필드)를 만든다. 파생 4필드는 포함하지 않는다."""
+    return {
+        "runId": build_run_id(project_id, task_group, task_id,
+                              task_type, run_seq),
+        "projectId": project_id,
+        "projectRoot": project_root,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "status": status,
+        "startedAt": started_at,
+        "finishedAt": finished_at,
+        "workers": workers,
+        "leadModel": lead_model,
+        "validation": validation,
+        "finalReportRel": final_report_rel,
+        "finalStatusRel": final_status_rel,
+        "runDirRel": run_dir_rel,
+    }
+
+
+def slim_run_row(row: dict) -> dict:
+    """파생 4필드를 제거한 새 dict. 이미 slim 이면 동일(멱등).
+    runId 가 없는 row(예: 옛 event-log 스키마)는 변형 없이 사본 반환."""
+    if "runId" not in row:
+        return dict(row)
+    return {k: v for k, v in row.items() if k not in DERIVED_FIELDS}
+
+
+def hydrate_run_row(row: dict) -> dict:
+    """slim/full row 를 받아 파생 4필드를 채운 full dict. 멱등.
+    taskKey 는 runId(slug)가 아닌 평면 raw taskGroup/taskId 로 조합한다.
+    projectId 는 raw 값이 slim row 에 보존되므로 runId 에서 복원하지 않는다 —
+    슬러그가 대소문자를 잃기 때문. 누락 시(방어용)만 parsed 값으로 채운다.
+    runId 가 없는 row(예: 옛 event-log 스키마)는 변형 없이 사본 반환.
+    runId 가 있으나 형식이 깨진 row 는 5-세그먼트 구조가 남아있으면 taskType/
+    runSeq 만 best-effort 로 복원한다 — slim row 는 이 둘을 따로 저장하지 않으므로,
+    버전 차이/손상으로 strict 파싱이 실패하면 predict_next_run_seq 가 이 row 를
+    max-seq 스캔에서 통째로 누락해 seq 가 충돌할 수 있기 때문. 그래도 한 줄의
+    손상이 read_run_index 의 다른 소비자(list_runs/reconcile)를 죽이지 않는다.
+    """
+    if "runId" not in row:
+        return dict(row)
+    try:
+        parsed = parse_run_id(row["runId"])
+    except ValueError:
+        out = dict(row)
+        parts = str(row["runId"]).split("/")
+        if len(parts) >= 5 and parts[-1][:1] == "r" and parts[-1][1:].isdigit():
+            out.setdefault("taskType", parts[-2])
+            out.setdefault("runSeq", int(parts[-1][1:]))
+        return out
+    out = dict(row)
+    out.setdefault("projectId", parsed["projectId"])
+    out["taskType"] = parsed["taskType"]
+    out["runSeq"] = parsed["runSeq"]
+    out["taskKey"] = f"{row.get('taskGroup', '')}/{row.get('taskId', '')}"
+    out["invocationFile"] = str(invocation_path(
+        Path(""), parsed["projectId"], parsed["taskGroup"], parsed["taskId"],
+        parsed["taskType"], parsed["runSeq"]))
+    return out
+
+
+def read_run_index(path: Path) -> list:
+    """run-index jsonl 을 읽어 각 row 를 hydrate 한 full row 목록 반환."""
+    return [hydrate_run_row(r) for r in read_jsonl(path)]
+
+
+def _rewrite_slim(path: Path) -> int:
+    rows = read_jsonl(path)
+    if not rows:
+        return 0
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with tmp.open("w") as f:
+        for r in rows:
+            f.write(json.dumps(slim_run_row(r), separators=(",", ":")) + "\n")
+    os.replace(tmp, path)
+    return len(rows)
+
+
+def reindex_slim(home: Path) -> int:
+    """기존 run-index 파일들을 slim 으로 일괄 재작성. 멱등. 변환 row 총수 반환."""
+    total = 0
+    targets = [home / "recent.jsonl", home / "active.jsonl"]
+    projects = home / "projects"
+    if projects.is_dir():
+        targets += sorted(projects.glob("*/index.jsonl"))
+    for path in targets:
+        if path.is_file():
+            total += _rewrite_slim(path)
+    return total

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -39,8 +39,14 @@ _REF_RE = re.compile(r'"\$ref"\s*:\s*"#/\$defs/([^"]+)"')
 
 
 def _refs_in(obj) -> set[str]:
-    """Every ``#/$defs/<name>`` referenced anywhere inside ``obj``."""
-    return set(_REF_RE.findall(json.dumps(obj)))
+    """Every ``#/$defs/<name>`` referenced anywhere inside ``obj``.
+
+    ``ensure_ascii=False`` keeps non-ASCII ``$defs`` names in their literal
+    form so the captured ref matches the actual ``$defs`` dict key; with the
+    default escaping a non-ASCII name would dump as ``\\uXXXX`` and the closure
+    would prune the def as unreachable, leaving a dangling ``$ref``.
+    """
+    return set(_REF_RE.findall(json.dumps(obj, ensure_ascii=False)))
 
 
 def _conditional_applies(entry: dict, task_type: str) -> bool:

package/runtime/python/okstra_ctl/sequence.py

@@ -6,8 +6,8 @@ from pathlib import Path
 from typing import Optional
 
 from .ids import slugify_task_segment
-from .jsonl import read_jsonl
 from .paths import task_runs_dir
+from .run_index_row import read_run_index
 
 
 def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
@@ -41,7 +41,7 @@ def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
                     max_seq = n
     if home is not None and project_id is not None:
         for src in ("active.jsonl", "recent.jsonl"):
-            for r in read_jsonl(home / src):
+            for r in read_run_index(home / src):
                 if (r.get("projectId") == project_id
                         and r.get("taskGroup") == task_group
                         and r.get("taskId") == task_id