okstra 0.186.6 → 0.187.0

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -15,7 +15,7 @@ import re
 from pathlib import Path
 from typing import NamedTuple
 
-from .stage_targets import PrepareError
+from .prepare_error import PrepareError
 
 _FINAL_REPORT_RE = re.compile(
     r"final-report-implementation-planning-(\d+)\.data\.json$"

package/runtime/python/okstra_ctl/plan_validate_cli.py

@@ -0,0 +1,51 @@
+"""`okstra plan-validate` 의 프로젝션 — 승인 계획 문서의 구조 검증.
+
+원래 `src/commands/execute/plan-validate.mts` 의 문자열 리터럴 안에 있던 코드다
+(docs/coding-rules.md R1 위반). 로직은 그대로 옮겼다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra plan-validate <plan-path>
+
+Output: JSON { ok: true, planPath } on success.
+On failure: { ok: false, reason } with non-zero exit code.
+
+Use this in flows that need to confirm a plan was approved without invoking
+the full prepare_task_bundle pipeline.
+"""
+_CLI_DESCRIPTION = "Verify an approved-plan file has a recognised approval marker."
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra plan-validate")
+    parser.add_argument("plan_path", metavar="plan-path")
+    args = parser.parse_args(argv)
+
+    # run.py 는 무거운 모듈이라 import 시점을 이 함수 안으로 미룬다 —
+    # `--help` 만 부르는 호출에 prepare 전체를 적재하지 않기 위해서다.
+    from .run import PrepareError, _validate_approved_plan
+
+    try:
+        _validate_approved_plan(args.plan_path)
+    except PrepareError as exc:
+        print(json.dumps({
+            "ok": False, "stage": "validation",
+            "reason": str(exc), "planPath": args.plan_path,
+        }))
+        return 1
+
+    print(json.dumps({"ok": True, "planPath": args.plan_path}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/plan_verify_cli.py

@@ -0,0 +1,80 @@
+"""`okstra plan-verify` 의 진입점.
+
+판정 로직은 `validators/validate-run.py --section plan-body` 가 전부 갖고 있다.
+이 모듈이 하는 일은 둘뿐이다 — 그 `--section` 값을 이 명령이 정하는 것으로
+못박고, 자기 이름의 도움말을 갖는 것. 검증기의 파서를 그대로 보여 주면 prog 가
+`validate-run.py` 로 나오고, 여기서 금지된 `--section` 이 선택 가능한 플래그로
+보인다.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from .report_finalize import resolve_workspace_validator
+
+_CLI_EPILOG = r"""Usage:
+  okstra plan-verify --narrative <report-writer-narrative.md> --state <plan-body-verification.json>
+  okstra plan-verify --report <final-report-implementation-planning-<seq>.data.json>
+
+Recomputes the gate from the convergence-owned state's `planItems[].verdicts`
+before publication. The `--report` form reads historical v2 reports. It runs
+every plan-body contract check that a round can be judged on its own — verdict
+provenance, fixability, subject substance, self-fix grouping, round recording,
+clarification matching, and the state-file round history.
+
+Emits one JSON object:
+
+  gate.recomputed      the gate value this round's votes actually support
+  gate.blockedBy       the `gateBlockedBy` causes, recomputed
+  gate.blockingItems   the plan items classified `majority-disagree`
+  gate.items[]         per-item classification
+  failures[]           blocking contract violations — exit code 2 when non-empty
+  advisories[]         contract findings that are recorded, not round-blocking
+  warnings[]           advisory signals (self-fix recurrence, uniform verifier)
+
+Exit code 0 means no blocking failure, not "no finding". What blocks is the
+allowlist in `scripts/okstra_ctl/blocking_checks.py` — the same set the finished
+run's validation blocks on, so a finding the completed run would let pass cannot
+hold a round open mid-loop. Everything else lands in `advisories[]` and on
+stderr as `validate-run: advisory — ...`; record it, then continue the round.
+
+Run this at every round boundary and record what it returns. The single-vote
+blocking kinds, the advisory-only kinds and the P-Var / P-Rb exemptions live in
+this one implementation — a lead that tallies the verdicts by hand instead is
+re-deriving them per round, and a round scored wrong spends its self-fix budget
+on the wrong items.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra plan-verify",
+        description="Score the §5.5.9 plan-body gate for one self-fix round.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--workspace-root", required=True,
+                        help=argparse.SUPPRESS)
+    parser.add_argument("--narrative", default="",
+                        help="the report-writer narrative this round scored")
+    parser.add_argument("--state", default="",
+                        help="the convergence-owned plan-body-verification.json")
+    parser.add_argument("--report", default="",
+                        help="a historical v2 final-report .data.json")
+    args = parser.parse_args(argv)
+
+    forwarded: list[str] = ["--section", "plan-body"]
+    for flag in ("narrative", "state", "report"):
+        value = getattr(args, flag)
+        if value:
+            forwarded += [f"--{flag}", value]
+
+    validator = resolve_workspace_validator(Path(args.workspace_root), "validate-run.py")
+    return subprocess.run([sys.executable, str(validator), *forwarded], check=False).returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/prepare_error.py

@@ -0,0 +1,20 @@
+"""task bundle prepare 실패 타입.
+
+`stage_targets` 안에 있던 것을 leaf 로 뽑았다. 그 모듈의 도크스트링은 이 예외가
+"저수준 모듈에 정의"돼 있다고 적었지만, 실제로는 944줄에 `stage_integrate` 를
+끌어오는 모듈이었다. 그래서 예외 타입 하나가 필요한 `plan_run_root` 가
+`stage_targets` 전체를 끌어오게 되고, 반대로 `stage_targets` 는
+`plan_run_root` 를 함수 본문에서 지연 import 해야 했다.
+
+`stage_targets` 와 `run` 이 이 이름을 재노출하므로 기존 호출부는 바뀌지 않는다.
+이 모듈은 아무것도 import 하지 않는다.
+"""
+from __future__ import annotations
+
+
+class PrepareError(Exception):
+    """surface to caller — task bundle prepare failed.
+
+    run.py(final-verification) 와 container.py 가 whole-task 통합 헬퍼의 실패를
+    같은 타입으로 받는다.
+    """

package/runtime/python/okstra_ctl/prior_planning.py

@@ -0,0 +1,157 @@
+"""직전 implementation-planning run 이 남긴 계획 맥락을 packet 용으로 좁힌다.
+
+계획 run 이 실패한 뒤 `--selected-direction` 으로 다시 도는 경우, 새 run 은 직전
+run 의 산출물을 하나도 받지 못했다. analysis packet 에 그것을 실을 자리가 없었고
+(`analysis_packet.build_analysis_packet` 에 직전 finding·판정·리포트를 받는 인자가
+없었다), 판정 이월은 답변된 clarification 이 있는 경로에만 있다
+(`incremental_scope.decide_scope` 는 답변된 `C-NNN` 이 없으면 `full` 을 되돌린다).
+그래서 planner 들이 brief 에서 전부 다시 유도했고, 같은 이견이 새 `P-*` 번호로
+다시 열렸다.
+
+이 모듈은 그 재유도를 줄일 만큼만 모은다 — clarification 행, Stage Map 한 줄씩,
+직전 수렴이 못 가른 finding, 그리고 나머지를 위한 리포트 경로. 리포트 전문은
+싣지 않는다: 그 중복이 실측 283K 리포트로 892K 중복 읽기를 만들어 report-writer 를
+timeout 시킨 적이 있다(`clarification_items.carry` 참고).
+
+판정은 소유하지 않는다. 이 블록은 사실 기록이고, 승인되지 않은 계획을 그대로
+복사하라는 지시가 아니다 — 그 문장은 packet 블록 머리글이 직접 말한다
+(`analysis_packet._prior_planning_block`).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+from .clarification_items import carried_clarification_rows
+from .final_report_paths import final_report_data_path
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .paths import RunRef, infer_project_root, project_rel
+
+
+PLANNING_TASK_TYPE = "implementation-planning"
+# 직전 run 이 끝내지 못한 두 상태. `convergence_engine._CLASSIFICATION_COUNT_KEYS`
+# 의 어휘를 그대로 쓴다 — 새 어휘를 만들면 같은 finding 이 run 마다 다르게 읽힌다.
+UNSETTLED_CLASSIFICATIONS = ("contested", "worker-unique")
+_SUMMARY_LIMIT = 200
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def build_prior_planning_summary(task_root: Path) -> str:
+    """이 task 의 직전 계획 run 요약. 직전 run 이 없으면 빈 문자열.
+
+    직전 리포트 해소는 wizard / interactive 진입점이 쓰는 것과 같다
+    (`RunRef.latest_under`: mtime 최신, 동률이면 basename, `.data.json` 우선).
+    같은 task-type 으로 좁히므로 다른 phase 의 리포트를 계획 맥락으로 집지 않는다.
+    """
+    task_root = Path(task_root)
+    ref = RunRef.latest_under(task_root, (PLANNING_TASK_TYPE,))
+    if ref is None:
+        return ""
+    report = ref.report
+    project_root = infer_project_root(task_root)
+    sections = [f"- Prior planning report: `{project_rel(report, project_root)}`"]
+    rows = carried_clarification_rows(report)
+    if rows:
+        sections.append(f"### Prior Clarification Items\n\n{rows}")
+    stage_map = _stage_map_lines(report)
+    if stage_map:
+        sections.append(
+            "### Prior Stage Map\n\n"
+            "`stage | title | depends-on`, as the prior plan wrote it.\n\n"
+            + "\n".join(stage_map)
+        )
+    unsettled = _unsettled_finding_lines(ref)
+    if unsettled:
+        sections.append(
+            "### Findings the prior run left unsettled\n\n"
+            + "\n".join(unsettled)
+        )
+    return "\n\n".join(sections)
+
+
+def _stage_map_lines(report: Path) -> list[str]:
+    """직전 계획의 Stage Map 을 스테이지당 한 줄로.
+
+    `stageMap` 이 정본이고 `stages` 는 그것이 없는 리포트를 위한 폴백이다 —
+    `plan_items._planning_stage_rows` 가 쓰는 것과 같은 우선순위다.
+    """
+    planning = _planning(report)
+    rows = planning.get("stageMap")
+    if not isinstance(rows, list) or not rows:
+        rows = planning.get("stages")
+    if not isinstance(rows, list):
+        return []
+    lines = []
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        stage = row.get("stage")
+        if not isinstance(stage, int) or isinstance(stage, bool):
+            continue
+        title = _one_line(row.get("title")) or "(untitled)"
+        depends = _one_line(row.get("dependsOn")) or "(unrecorded)"
+        lines.append(f"- {stage} | {title} | depends-on: {depends}")
+    return lines
+
+
+def _unsettled_finding_lines(ref: RunRef) -> list[str]:
+    """직전 수렴이 `contested` / `worker-unique` 로 닫은 finding 한 줄씩.
+
+    상태 파일이 없거나 못 읽으면 빈 목록이다. 없는 것이 정상 분기다 — 수렴을
+    돌기 전에 죽은 run, 그리고 디렉터리별 seq 가 갈린 run 이 둘 다 여기로 온다
+    (`RunRef.convergence_state` 참고).
+
+    seq 를 못 읽은 ref 도 같다. 옛 타임스탬프 이름의 리포트가 그 경우이고, 그
+    이름에서는 상태 파일 이름을 재구성할 수 없다.
+    """
+    if ref.seq is None:
+        return []
+    state = _load_object(ref.convergence_state)
+    findings = state.get("findings")
+    if not isinstance(findings, list):
+        return []
+    lines = []
+    for finding in findings:
+        if not isinstance(finding, Mapping):
+            continue
+        classification = finding.get("classification")
+        if classification not in UNSETTLED_CLASSIFICATIONS:
+            continue
+        finding_id = _one_line(finding.get("findingId"))
+        if not finding_id:
+            continue
+        summary = _one_line(finding.get("summary")) or "(no summary recorded)"
+        lines.append(f"- `{finding_id}` ({classification}) — {summary}")
+    return lines
+
+
+def _planning(report: Path) -> Mapping[str, Any]:
+    data = _load_object(final_report_data_path(report))
+    planning = data.get("implementationPlanning")
+    return planning if isinstance(planning, Mapping) else {}
+
+
+def _load_object(path: Path) -> Mapping[str, Any]:
+    """소유한 JSON 객체, 못 읽으면 빈 매핑.
+
+    이 블록은 전부 최선 노력이다. 직전 run 의 산출물이 깨졌다고 새 run 의 준비를
+    막으면, 다시 도는 이유였던 그 실패가 재실행 자체를 못 하게 만든다.
+    """
+    try:
+        data = load_owned_object(path, artifact="prior planning artifact")
+    except (JsonBoundaryError, OSError):
+        # expected-miss: 직전 run 이 남기지 못했거나 깨뜨린 파일. 이 블록은
+        # 맥락일 뿐이라 없는 상태가 정상 분기고, 소비처는 해당 하위 블록을
+        # 생략한다.
+        return {}
+    return data if isinstance(data, Mapping) else {}
+
+
+def _one_line(value: object) -> str:
+    if not isinstance(value, str):
+        return ""
+    collapsed = _WHITESPACE_RE.sub(" ", value).strip()
+    if len(collapsed) <= _SUMMARY_LIMIT:
+        return collapsed
+    return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"

package/runtime/python/okstra_ctl/profile_show.py

@@ -107,9 +107,26 @@ def _write_stdout(text: str) -> None:
             os.close(devnull)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra profile show <task-type> [--resolved]
+
+  --resolved   expand {{INCLUDE:}} targets and append the lazy-read sidecars
+
+A profile is assembled from the top-level body, its {{INCLUDE:}} targets, and
+the sidecars its own table names — so grepping the top-level file and finding
+nothing does not mean the rule is absent. This prints all of it, so one grep
+answers "does this task-type cover X".
+
+Read-only: writes no manifest and registers no run. That is what separates it
+from 'okstra render-bundle', which answers the same question with side effects.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        prog="okstra profile show",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra profile",
         description="Print a phase profile, optionally fully resolved (read-only).",
     )
     parser.add_argument("command", choices=("show",))

package/runtime/python/okstra_ctl/project_setup_cli.py

@@ -0,0 +1,140 @@
+"""프로젝트 루트 해석·project.json upsert·PR 템플릿 해석의 CLI 경계.
+
+이 네 갈래는 원래 `config.mts` · `setup.mts` · `check-project.mts` 안에
+파이썬 소스 배열로 각각 복사돼 있었다(docs/coding-rules.md R1 위반, 그리고
+같은 해석을 네 벌 유지하는 중복). 로직은 그대로 옮겼고 출력 형식도 그대로다 —
+호출부의 파서를 건드리지 않기 위해서다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    project_json_path,
+    resolve_project_root,
+    upsert_project_json,
+)
+
+from .json_boundary import JsonBoundaryError, load_owned_object
+
+
+def _resolve(args: argparse.Namespace) -> int:
+    """`PROJECT_ROOT` / `PROJECT_JSON` 또는 `RESOLVER_ERROR` 태그 줄."""
+    try:
+        pr = resolve_project_root(explicit_root=args.explicit_root, cwd=args.cwd)
+    except ResolverError as exc:
+        print("RESOLVER_ERROR", exc)
+        return 0
+    print("PROJECT_ROOT", pr)
+    print("PROJECT_JSON", project_json_path(pr))
+    return 0
+
+
+def _resolve_root(args: argparse.Namespace) -> int:
+    """루트 경로만 stdout 으로.
+
+    `--on-error` 로 실패 취급이 갈린다. `fail` 은 stderr + 비0(엄격한 호출부),
+    `empty` 는 아무것도 내지 않고 0(autofill 처럼 실패해도 진행하는 호출부).
+    두 갈래를 한 구현 안에 두는 이유는, 예전에 셸과 TS 가 같은 해석을 각자
+    베껴 두어 갈라질 수 있었기 때문이다.
+    """
+    try:
+        root = resolve_project_root(explicit_root=args.explicit_root, cwd=args.cwd)
+    except ResolverError as exc:
+        if args.on_error == "fail":
+            sys.stderr.write(f"{args.error_prefix}{exc}\n")
+            return args.error_code
+        return 0
+    print(root)
+    return 0
+
+
+def _upsert(args: argparse.Namespace) -> int:
+    """`--format tagged` 는 `OK <json>` / `ERROR <msg>`, `strict` 는 stderr + 비0."""
+    try:
+        result = upsert_project_json(Path(args.project_root), args.project_id)
+    except ResolverError as exc:
+        if args.format == "strict":
+            sys.stderr.write(f"project.json upsert failed: {exc}\n")
+            return 1
+        print("ERROR", exc)
+        return 0
+    if args.format == "tagged":
+        print("OK", json.dumps(result))
+    return 0
+
+
+def _project_json(args: argparse.Namespace) -> int:
+    """`<projectId>\t<projectRoot>` 한 줄. 해석·파일 어느 쪽이든 없으면 아무것도 내지 않는다."""
+    try:
+        root = resolve_project_root(explicit_root=args.explicit_root or "")
+    except ResolverError:
+        return 0
+    path = project_json_path(Path(root))
+    if not path.is_file():
+        return 0
+    try:
+        data = load_owned_object(path, artifact="project.json")
+    except JsonBoundaryError:
+        # 깨진 project.json 은 autofill 을 끄는 신호다 — 이 경로의 호출부는
+        # 값을 못 얻으면 사용자에게 직접 묻는다. 여기서 죽이면 물어볼 기회도 없다.
+        return 0
+    print(f"{data.get('projectId', '')}\t{root}")
+    return 0
+
+
+def _pr_template(args: argparse.Namespace) -> int:
+    from .pr_template import PrTemplateError, resolve_pr_template_path
+
+    try:
+        resolved = resolve_pr_template_path(Path(args.project_root))
+    except PrTemplateError as exc:
+        print(json.dumps({"ok": False, "reason": str(exc)}))
+        return 0
+    print(json.dumps({
+        "ok": True, "path": str(resolved.path), "source": resolved.source,
+    }))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra project-setup")
+    sub = parser.add_subparsers(dest="op", required=True)
+
+    resolve = sub.add_parser("resolve")
+    resolve.add_argument("--explicit-root", default="")
+    resolve.add_argument("--cwd", required=True)
+    resolve.set_defaults(handler=_resolve)
+
+    resolve_root = sub.add_parser("resolve-root")
+    resolve_root.add_argument("--explicit-root", default="")
+    resolve_root.add_argument("--cwd", default="")
+    resolve_root.add_argument("--on-error", choices=("fail", "empty"), default="fail")
+    resolve_root.add_argument("--error-prefix", default="")
+    resolve_root.add_argument("--error-code", type=int, default=2)
+    resolve_root.set_defaults(handler=_resolve_root)
+
+    upsert = sub.add_parser("upsert")
+    upsert.add_argument("--project-root", required=True)
+    upsert.add_argument("--project-id", required=True)
+    upsert.add_argument("--format", choices=("tagged", "strict"), default="tagged")
+    upsert.set_defaults(handler=_upsert)
+
+    project_json = sub.add_parser("project-json")
+    project_json.add_argument("--explicit-root", default="")
+    project_json.set_defaults(handler=_project_json)
+
+    pr_template = sub.add_parser("pr-template")
+    pr_template.add_argument("--project-root", required=True)
+    pr_template.set_defaults(handler=_pr_template)
+
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/recap.py

@@ -213,8 +213,29 @@ def _add_common(sp) -> None:
     sp.add_argument("--cwd", default=".")
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra recap assemble <task-root|task-key> [--project-root <dir>] [--cwd <dir>]
+  okstra recap record <task-root|task-key> --kind <summary|qa> --mode <artifact|code> \
+    [--question <text>] --answer <text> [--citation <path:line> ...]
+  okstra recap note <task-root|task-key> \
+    --kind <verification-evidence|decision-draft|analysis-note> --slug <topic> \
+    --purpose <text> --scope-note <text> (--body <markdown> | --body-file <path>)
+
+`assemble` is read-only and prints a JSON summary of phase transitions across runs.
+`record` appends one line to <task-root>/recap/recap-log.jsonl; it never mutates
+other task artifacts.
+`note` writes an agent-authored markdown note to <task-root>/notes/ and prints its
+path plus the `--clarification-response` argument for feeding it into a later run.
+"""
+_CLI_DESCRIPTION = "Assemble a task's run-to-run phase recap, append a recap log entry, or write an agent note."
+
+
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="okstra recap")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra recap")
     sub = parser.add_subparsers(dest="command", required=True)
 
     p_asm = sub.add_parser("assemble", help="assemble run-to-run phase transitions")

package/runtime/python/okstra_ctl/reconcile.py

@@ -227,3 +227,87 @@ def _reconcile_recent_locked(home: Path, *, project: Optional[str] = None) -> di
     for pid, urows in updated_by_project.items():
         _sync_project_index(home, pid, urows)
     return summary
+
+
+def reconcile_home(home: Path, *, project: Optional[str] = None) -> dict:
+    """active 승격과 recent in-place 갱신을 한 번에 수행하는 단일 호출점.
+
+    두 함수는 서로 다른 파일을 보지만 같은 사실(디스크 run-manifest 의
+    validation)을 근거로 삼는 한 쌍이다. active 만 돌리면 `--render-only` 로
+    recent 에 prepared 로 박힌 행이 영영 갱신되지 않고, recent 만 돌리면 끝난
+    run 이 active 에 running 으로 남는다. 호출자가 한쪽만 부를 수 있는 표면을
+    남기지 않기 위해 여기서 묶는다.
+
+    project 를 주면 해당 projectId 행만 대상으로 삼는다. 두 함수 각각이 중앙
+    락을 잡았다 놓으므로, 이 함수를 central_lock 안에서 부르면 self-deadlock
+    이다(flock 은 재진입 불가).
+    """
+    return {
+        "active": reconcile_active(home, project=project),
+        "recent": reconcile_recent(home, project=project),
+    }
+
+
+def settle_run_row(home: Path, *, project_id: str, execution_manifest_rel: str,
+                   validation_status: str) -> bool:
+    """검증기가 방금 확정한 판정을 그 run 의 인덱스 행에 그대로 기록한다.
+
+    `reconcile_*` 는 디스크에서 상태를 **추론**한다 — 어느 run 이 끝났는지 모르는
+    호출자를 위한 경로다. 검증기는 자기가 방금 무엇을 썼는지 알고 있으므로 추론할
+    것이 없고, 추론에 맡기면 실제로 틀린다: `reconcile_recent` 는 이미 종결 상태인
+    행을 갱신 대상에서 빼므로, 한 번 `failed` 로 굳은 뒤 고쳐서 다시 통과시킨 run
+    이 인덱스에는 영영 `failed` 로 남는다(검증 재실행은 흔한 흐름이다).
+
+    행은 `executionManifestPath` 로 찾는다 — `runDirRel` 은 같은 task-type 의 여러
+    run-seq 가 공유해 유일하지 않다. 그 필드가 없는 옛 행은 못 찾고 False 를
+    돌려주며, 그런 행은 `reconcile_home` 의 일반 스윕이 맡는다.
+
+    반환값: 행을 찾아 기록했으면 True.
+    """
+    with central_lock(home):
+        return _settle_run_row_locked(
+            home, project_id=project_id,
+            execution_manifest_rel=execution_manifest_rel,
+            validation_status=validation_status)
+
+
+def _matches_run(row: dict, project_id: str, execution_manifest_rel: str) -> bool:
+    return (row.get("projectId") == project_id
+            and str(row.get("executionManifestPath") or "") == execution_manifest_rel)
+
+
+def _settle_run_row_locked(home: Path, *, project_id: str,
+                           execution_manifest_rel: str,
+                           validation_status: str) -> bool:
+    # 빈 키는 따로 막지 않는다 — `_matches_run` 의 문자열 동일성 비교가 어떤 행도
+    # 고르지 않으므로 결과가 같다(`test_settle_run_row_needs_both_...` 이 고정).
+    status = normalize_reconciled_report_status(validation_status)
+    finished_at = _now_iso()
+
+    active = home / "active.jsonl"
+    rows = read_run_index(active)
+    survivors = [r for r in rows
+                 if not _matches_run(r, project_id, execution_manifest_rel)]
+    promoted = [r for r in rows
+                if _matches_run(r, project_id, execution_manifest_rel)]
+    if promoted:
+        for row in promoted:
+            row["status"] = status
+            row["finishedAt"] = finished_at
+            row["validation"] = validation_status
+        _publish_promoted(home, active, survivors, promoted)
+        return True
+
+    recent = home / "recent.jsonl"
+    rows = read_run_index(recent)
+    updated = [r for r in rows
+               if _matches_run(r, project_id, execution_manifest_rel)]
+    if not updated:
+        return False
+    for row in updated:
+        row["status"] = status
+        row["finishedAt"] = finished_at
+        row["validation"] = validation_status
+    rewrite_jsonl(recent, [slim_run_row(row) for row in rows])
+    _sync_project_index(home, project_id, updated)
+    return True

package/runtime/python/okstra_ctl/registry/host_registry.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import inspect
 from collections.abc import Iterable, Mapping
+from functools import lru_cache
 from pathlib import Path
 
 from okstra_project.dirs import okstra_home
@@ -158,7 +159,23 @@ def default_host_registry(
     bundled_root = Path(__file__).resolve().parents[1] / "adapters" / "hosts"
     user_root = okstra_home() / "adapters" / "hosts"
     providers = provider_registry or default_provider_registry()
-    return HostAdapterRegistry.from_roots((bundled_root, user_root), providers)
+    return _host_registry_for_roots(bundled_root, user_root, providers)
+
+
+@lru_cache(maxsize=None)
+def _host_registry_for_roots(
+    bundled_root: Path,
+    user_root: Path,
+    provider_registry: ProviderRegistry,
+) -> HostAdapterRegistry:
+    """discovery root 조합마다 레지스트리를 한 번만 조립한다.
+
+    `from_roots` 는 매니페스트를 디스크에서 훑고 어댑터 팩토리 모듈을 importlib
+    로 적재하므로 호출당 비용이 크다. 호출부(위저드의 역할/모델 프롬프트 등)는
+    같은 root 로 이걸 루프 안에서 반복 호출한다. `default_provider_registry` 의
+    `_registry_for_roots` 와 같은 캐시 형태를 쓴다.
+    """
+    return HostAdapterRegistry.from_roots((bundled_root, user_root), provider_registry)
 
 
 def _load_entries(