okstra 0.186.7 → 0.187.0

package/runtime/bin/lib/okstra/interactive.sh

@@ -52,6 +52,14 @@ split_task_key() {
   TASK_ID="$key_id"
 }
 
+# okstra_ctl.interactive_cli 호출 공용 래퍼. 조회 로직은 전부 그 모듈에 있다 —
+# 예전에는 이 파일이 파이썬 heredoc 6개(153줄)로 같은 일을 했고, 셸 문자열 안이라
+# import 도 테스트도 닿지 않았다(docs/coding-rules.md R1).
+_okstra_interactive_cli() {
+  PYTHONPATH="${OKSTRA_PYTHONPATH}${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m okstra_ctl.interactive_cli "$@"
+}
+
 resolve_task_root_for_shortcut() {
   local project_root="$1"
   local project_id="$2"
@@ -59,75 +67,9 @@ resolve_task_root_for_shortcut() {
   local task_id="$4"
 
   local resolved=""
-  resolved="$(python3 - "$OKSTRA_PYTHONPATH" "$project_root" "$project_id" "$task_group" "$task_id" <<'PY'
-import json, os, sys
-from pathlib import Path
-
-# task root 의 slug 경로 구성은 okstra_ctl.paths.task_dir(SSOT) 에 위임한다.
-# 과거 이 heredoc 은 slugify 와 `.okstra/tasks/<slug>/<slug>` 구조를 자체
-# 재구현해 규칙 변경 시 silent drift 위험이 있었다. project-resolver.sh 와
-# 동일하게 $OKSTRA_PYTHONPATH 를 sys.path 에 올려 패키지를 import 한다.
-sys.path.insert(0, sys.argv[1])
-from okstra_ctl.paths import task_dir
-
-project_root = Path(sys.argv[2])
-project_id = sys.argv[3]
-task_group = sys.argv[4]
-task_id = sys.argv[5]
-
-requested_key = f"{project_id}:{task_group}:{task_id}"
-requested_key_ci = requested_key.lower()
-
-candidates = []
-
-catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
-catalog_keys = []
-if catalog_path.is_file():
-    try:
-        catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
-    except Exception as exc:
-        sys.stderr.write(f"resolve_task_root: failed to parse {catalog_path}: {exc}\n")
-        catalog = None
-    if isinstance(catalog, dict):
-        catalog_project_id = catalog.get("projectId")
-        tasks = catalog.get("tasks") or []
-        for entry in tasks:
-            if not isinstance(entry, dict):
-                continue
-            entry_key = entry.get("taskKey") or ""
-            if not isinstance(entry_key, str) or not entry_key:
-                continue
-            entry_belongs_to_project = (
-                catalog_project_id == project_id
-                or entry.get("projectId") == project_id
-                or entry_key.startswith(f"{project_id}:")
-            )
-            if entry_belongs_to_project:
-                catalog_keys.append(entry_key)
-            if entry_key.lower() == requested_key_ci:
-                rel = entry.get("taskRootPath") or entry.get("taskRoot")
-                if isinstance(rel, str) and rel:
-                    abs_path = (project_root / rel).resolve() if not os.path.isabs(rel) else Path(rel)
-                    if abs_path.is_dir():
-                        print(f"OK\t{abs_path}")
-                        sys.exit(0)
-                    candidates.append(str(abs_path))
-
-slug_path = task_dir(project_root, task_group, task_id)
-if slug_path.is_dir():
-    print(f"OK\t{slug_path}")
-    sys.exit(0)
-candidates.append(str(slug_path))
-
-# Failure path: emit diagnostics so the wrapper can show them.
-print("MISSING")
-print(f"REQUESTED\t{requested_key}")
-for cand in candidates:
-    print(f"TRIED\t{cand}")
-for key in sorted(set(catalog_keys)):
-    print(f"AVAILABLE\t{key}")
-PY
-)"
+  resolved="$(_okstra_interactive_cli resolve-task-root \
+    --project-root "$project_root" --project-id "$project_id" \
+    --task-group "$task_group" --task-id "$task_id")"
 
   local status=""
   status="$(printf '%s' "$resolved" | head -n 1 | awk -F '\t' '{print $1}')"
@@ -176,53 +118,17 @@ autofill_from_manifest() {
     return 0
   fi
 
-  PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 - "$manifest_project_root" "$manifest_task_root" <<'PY' || true
-import sys
-from pathlib import Path
-
-from okstra_ctl.implementation_outcome import reconcile_implementation_outcome
-
-try:
-    reconcile_implementation_outcome(Path(sys.argv[1]), Path(sys.argv[2]))
-except Exception:
-    pass
-PY
+  _okstra_interactive_cli reconcile-outcome \
+    --project-root "$manifest_project_root" --task-root "$manifest_task_root" || true
 
-  local need_brief_val need_type_val
-  need_brief_val="$([[ -z "$BRIEF_PATH" ]] && printf '1' || printf '0')"
-  need_type_val="$([[ -z "$TASK_TYPE" ]] && printf '1' || printf '0')"
   local autofill_output=""
-  # autofill 은 편의 기능이라 실패해도 run 을 끊으면 안 된다. heredoc 이
-  # okstra_ctl 을 import 하므로 설치가 깨지면 non-zero 로 끝나는데, okstra.sh 는
-  # `set -euo pipefail` 이라 이 평범한 대입 하나가 run 을 통째로 중단시킨다.
-  # 위 reconcile 호출(:189)이 같은 이유로 `|| true` 를 달고 있다.
-  autofill_output="$(PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 - "$manifest_path" "$need_brief_val" "$need_type_val" <<'PY'
-import json, sys
-
-from okstra_ctl import next_phase
-
-path = sys.argv[1]
-need_brief = sys.argv[2] == "1"
-need_type = sys.argv[3] == "1"
-try:
-    data = json.loads(open(path, "r", encoding="utf-8").read())
-except Exception as exc:
-    sys.stderr.write(f"autofill_from_manifest: failed to parse {path}: {exc}\n")
-    sys.exit(0)
-
-brief = ""
-task_type = ""
-if need_brief:
-    brief = (data.get("taskBriefPath") or "").strip()
-if need_type:
-    # 포인터 판정은 Python SSOT 가 갖는다 — `ready` 가 아니면 빈 문자열이라
-    # 셸이 센티널 목록을 따로 들고 있을 이유가 없다.
-    task_type = next_phase.autofill_task_type(data)
-
-print(f"BRIEF={brief}")
-print(f"TYPE={task_type}")
-PY
-)" || true
+  # autofill 은 편의 기능이라 실패해도 run 을 끊으면 안 된다. 모듈이 okstra_ctl 을
+  # import 하므로 설치가 깨지면 비-0 으로 끝나는데, okstra.sh 는 `set -euo pipefail`
+  # 이라 이 평범한 대입 하나가 run 을 통째로 중단시킨다. 위 reconcile 호출이 같은
+  # 이유로 `|| true` 를 달고 있다.
+  autofill_output="$(_okstra_interactive_cli autofill --manifest "$manifest_path" \
+    $( [[ -z "$BRIEF_PATH" ]] && printf -- "--need-brief" ) \
+    $( [[ -z "$TASK_TYPE" ]] && printf -- "--need-type" ))" || true
 
   local manifest_brief=""
   local manifest_type=""
@@ -304,19 +210,8 @@ find_latest_final_report() {
   }
 
   local found=""
-  found="$(PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 - \
-             "$task_root" "$task_type_filter" <<'PY'
-import sys
-from okstra_ctl.paths import RunRef
-
-task_root, task_type_filter = sys.argv[1:3]
-types = ((task_type_filter,) if task_type_filter
-         else ("error-analysis", "requirements-discovery"))
-ref = RunRef.latest_under(task_root, types)
-if ref is not None:
-    sys.stdout.write(f"{ref.report}\t{ref.task_type}")
-PY
-)" || return 1
+  found="$(_okstra_interactive_cli latest-report \
+    --task-root "$task_root" --task-type "$task_type_filter")" || return 1
 
   if [[ -z "$found" ]]; then
     printf 'resume-clarification: no final-report found for task %s:%s under %s/runs\n' \
@@ -386,12 +281,7 @@ run_resume_clarification() {
     exit 1
   fi
   local resume_brief_rel=""
-  resume_brief_rel="$(python3 - "$manifest_file" <<'PY'
-import json, sys
-data = json.loads(open(sys.argv[1], "r", encoding="utf-8").read())
-print((data.get("taskBriefPath") or "").strip())
-PY
-)"
+  resume_brief_rel="$(_okstra_interactive_cli manifest-brief --manifest "$manifest_file")"
   if [[ -z "$resume_brief_rel" ]]; then
     printf 'resume-clarification: manifest missing taskBriefPath: %s\n' "$manifest_file" >&2
     exit 1
@@ -403,46 +293,9 @@ PY
   local resume_extra_args=()
   while IFS= read -r -d '' _arg; do
     resume_extra_args+=("$_arg")
-  done < <(PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 - \
-             "$PROJECT_ROOT" "$TASK_GROUP" "$TASK_ID" "$resolved_type" <<'PY'
-import sys
-from okstra_ctl.run_context import latest_run_inputs
-from okstra_ctl.ids import slugify_task_segment
-
-project_root, task_group, task_id, task_type = sys.argv[1:5]
-inputs = latest_run_inputs(
-    project_root, task_group, task_id,
-    phase_segment=slugify_task_segment(task_type))
-
-
-def emit(flag, value):
-    if value:
-        sys.stdout.write(flag + "\0" + value + "\0")
-
-
-def model(value):
-    # 직전 run 의 모델 display 값. "default"/빈 값은 phase 기본값을 뜻하므로 넘기지
-    # 않는다(명시 플래그로 고정하면 안 됨).
-    return value if isinstance(value, str) and value not in ("", "default") else ""
-
-
-workers = inputs.get("workers")
-if isinstance(workers, list):
-    workers = ",".join(w for w in workers if isinstance(w, str))
-elif not isinstance(workers, str):
-    workers = ""
-emit("--workers", workers)
-emit("--lead-model", model(inputs.get("leadModel")))
-emit("--claude-model", model(inputs.get("claudeModel")))
-emit("--codex-model", model(inputs.get("codexModel")))
-emit("--antigravity-model", model(inputs.get("antigravityModel")))
-emit("--report-writer-model", model(inputs.get("reportWriterModel")))
-directive = inputs.get("directive")
-emit("--directive", directive if isinstance(directive, str) else "")
-related = inputs.get("relatedTasks")
-emit("--related-tasks", related if isinstance(related, str) else "")
-PY
-)
+  done < <(_okstra_interactive_cli resume-args \
+    --project-root "$PROJECT_ROOT" --task-group "$TASK_GROUP" \
+    --task-id "$TASK_ID" --task-type "$resolved_type")
 
   if [[ "${OKSTRA_RESUME_CLARIFICATION_DRY_RUN:-false}" == "true" ]]; then
     printf 'resume-clarification (dry-run):\n' >&2

package/runtime/bin/lib/okstra/project-resolver.sh

@@ -1,59 +1,36 @@
 # shellcheck shell=bash
 
-# bash wrappers around scripts/okstra_project resolver. okstra.sh 가 시작 시
-# PROJECT_ROOT 를 확정하고 <PROJECT_ROOT>/.okstra/project.json 을
-# upsert 한다. 과거 conf 파일 모델은 폐기되었다.
+# scripts/okstra_project 리졸버의 bash 래퍼. okstra.sh 가 시작 시 PROJECT_ROOT 를
+# 확정하고 <PROJECT_ROOT>/.okstra/project.json 을 upsert 한다. 과거 conf 파일
+# 모델은 폐기되었다.
+#
+# 해석 자체는 `okstra_ctl.project_setup_cli` 한 곳에만 있다. 예전에는 이 파일이
+# 파이썬 heredoc 4개로 같은 해석을 다시 적었고, TS 쪽(config/setup/check-project)
+# 도 각자 한 벌씩 더 갖고 있었다 — 갈라져도 아무도 몰랐다.
 
-# 절대경로(또는 빈 문자열) 를 stdout 으로 출력한다. 실패 시 stderr 에 메시지를
-# 남기고 비-0 종료. autofill 처럼 best-effort 호출자가 에러를 무시할 수 있도록
-# strict/safe 두 종류를 분리한다.
+# PYTHONPATH 는 호출 시점의 $OKSTRA_PYTHONPATH 를 앞에 둔다(설치본/레포 양쪽).
+_okstra_project_cli() {
+  PYTHONPATH="${OKSTRA_PYTHONPATH}${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m okstra_ctl.project_setup_cli "$@"
+}
+
+# 절대경로를 stdout 으로. 실패 시 stderr 에 메시지를 남기고 비-0 종료.
 resolve_project_root_strict() {
-  local explicit="${1-}"
-  python3 - "$OKSTRA_PYTHONPATH" "$explicit" <<'PY'
-import os, sys
-sys.path.insert(0, sys.argv[1])
-from okstra_project import resolve_project_root, ResolverError
-explicit = sys.argv[2] if len(sys.argv) > 2 else ""
-try:
-    p = resolve_project_root(explicit_root=explicit, cwd=os.getcwd())
-except ResolverError as exc:
-    sys.stderr.write(f"resolve_project_root: {exc}\n")
-    sys.exit(1)
-print(p)
-PY
+  _okstra_project_cli resolve-root \
+    --explicit-root "${1-}" --cwd "$PWD" \
+    --on-error fail --error-prefix "resolve_project_root: " --error-code 1
 }
 
 # 실패해도 0 으로 종료하고 stdout 은 빈 문자열(autofill 등 best-effort 경로용).
 resolve_project_root_safe() {
-  local explicit="${1-}"
-  python3 - "$OKSTRA_PYTHONPATH" "$explicit" <<'PY'
-import os, sys
-sys.path.insert(0, sys.argv[1])
-from okstra_project import resolve_project_root, ResolverError
-explicit = sys.argv[2] if len(sys.argv) > 2 else ""
-try:
-    p = resolve_project_root(explicit_root=explicit, cwd=os.getcwd())
-except ResolverError:
-    sys.exit(0)
-print(p)
-PY
+  _okstra_project_cli resolve-root \
+    --explicit-root "${1-}" --cwd "$PWD" --on-error empty
 }
 
 # project.json upsert. 충돌(projectId 불일치) 시 비-0 종료 + stderr 메시지.
 upsert_project_json() {
-  local project_root="$1"
-  local project_id="$2"
-  python3 - "$OKSTRA_PYTHONPATH" "$project_root" "$project_id" <<'PY'
-import sys
-sys.path.insert(0, sys.argv[1])
-from pathlib import Path
-from okstra_project import upsert_project_json, ResolverError
-try:
-    upsert_project_json(Path(sys.argv[2]), sys.argv[3])
-except ResolverError as exc:
-    sys.stderr.write(f"project.json upsert failed: {exc}\n")
-    sys.exit(1)
-PY
+  _okstra_project_cli upsert \
+    --project-root "$1" --project-id "$2" --format strict
 }
 
 # `okstra setup` 이 이미 기록한 값을 다시 묻지 않기 위한 자동 채움. 프로젝트
@@ -61,23 +38,8 @@ PY
 autofill_from_project_json() {
   [[ -n "$PROJECT_ID" && -n "$PROJECT_ROOT" ]] && return 0
   local resolved
-  resolved="$(python3 - "$OKSTRA_PYTHONPATH" "$PROJECT_ROOT_OVERRIDE" <<'PY' || true
-import json, sys
-from pathlib import Path
-sys.path.insert(0, sys.argv[1])
-from okstra_project import project_json_path
-from okstra_project.resolver import resolve_project_root
-try:
-    root = resolve_project_root(explicit_root=sys.argv[2] or "")
-except Exception:
-    sys.exit(0)
-path = project_json_path(Path(root))
-if not path.is_file():
-    sys.exit(0)
-data = json.loads(path.read_text(encoding="utf-8"))
-print(f"{data.get('projectId', '')}\t{root}")
-PY
-)"
+  resolved="$(_okstra_project_cli project-json \
+    --explicit-root "$PROJECT_ROOT_OVERRIDE" || true)"
   [[ -z "$resolved" ]] && return 0
   [[ -z "$PROJECT_ID" ]] && PROJECT_ID="${resolved%%$'\t'*}"
   [[ -z "$PROJECT_ROOT" ]] && PROJECT_ROOT="${resolved##*$'\t'}"

package/runtime/bin/lib/okstra/usage.sh

@@ -11,7 +11,7 @@ summary:
 
   Skills, worker agents, and the codex wrapper are installed once per user under
   ~/.claude and ~/.okstra by scripts/okstra-install.sh. The user's settings.json
-  is never modified; okstra-ctl prepare provisions the project's
+  is never modified; `okstra setup` and the prepare path provision the project's
   .claude/settings.local.json as a symlink to ~/.okstra/templates/settings.local.json,
   which Claude Code auto-loads.
 
@@ -99,7 +99,7 @@ options:
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
-  --worker-model       Provider-qualified worker override CSV, e.g. grok=grok-4.5,kimi=kimi-k3.
+  --worker-model       Provider-qualified worker override CSV, e.g. grok=grok-4.6,kimi=kimi-k3.
   --report-writer-provider
                       Provider for report writer. Supported: claude, codex. Default: claude.
   --report-writer-model
@@ -136,7 +136,7 @@ model defaults:
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   Grok worker: grok-4.6
-  Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic)
+  Kimi worker: kimi-k3
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity | grok | kimi)
 
 output:

package/runtime/bin/okstra-compact-reminder.sh

@@ -16,11 +16,7 @@ home="${OKSTRA_HOME:-$HOME/.okstra}"
 export PYTHONPATH="${_dir}:${home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
 
 _stdin="$(cat 2>/dev/null || true)"
-cwd="$(printf '%s' "$_stdin" | python3 -c 'import json,sys
-try:
-    print(json.load(sys.stdin).get("cwd","") or "")
-except Exception:
-    pass' 2>/dev/null || true)"
+cwd="$(printf '%s' "$_stdin" | python3 -m okstra_ctl.pane_reclaim --cwd-from-hook-stdin 2>/dev/null || true)"
 [ -n "$cwd" ] || cwd="$PWD"
 
 while IFS= read -r run_dir; do

package/runtime/bin/okstra-error-log.py

@@ -8,9 +8,15 @@ re-exports the writer's names so the contract tests keep reading one module.
 from __future__ import annotations
 
 import argparse
+import sys
 from pathlib import Path
 
-from okstra_ctl.error_log_write import (
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_ctl/error_log_write.py")
+
+from okstra_ctl.error_log_write import (  # noqa: E402
     ALLOWED_AGENT_ROLES,
     ALLOWED_AGENTS,
     ALLOWED_CAUSES,
@@ -48,8 +54,19 @@ __all__ = [
 ]
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra error-log <subcommand> [...]      # e.g. append-observed / append-from-worker
+
+See `okstra error-log append-observed --help` for that subcommand's options.
+"""
+
+
 def _build_parser():
-    p = argparse.ArgumentParser(description="OKSTRA error log helper")
+    p = argparse.ArgumentParser(
+        prog="okstra error-log",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="OKSTRA error log helper")
     sub = p.add_subparsers(dest="cmd", required=True)
 
     obs = sub.add_parser("append-observed",

package/runtime/bin/okstra-import-check.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""한 모듈이 현재 PYTHONPATH 로 import 되는지 확인한다 — `okstra doctor` 전용.
+
+별도 파일인 이유: 이 프로브는 `okstra_ctl` 자체의 import 가능성도 검사한다.
+`python3 -m okstra_ctl.<x>` 로 부르면 검사 대상이 못 뜰 때 프로브도 같이 죽어
+"모듈이 없다"와 "프로브가 없다"를 구분할 수 없다. 그래서 okstra 를 import 하지
+않는 독립 파일로 두고 경로로 호출한다.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 1:
+        sys.stderr.write("usage: okstra-import-check.py <module>\n")
+        return 2
+    name = argv[0]
+    module = importlib.import_module(name)
+    print(getattr(module, "__name__", name))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/bin/okstra-inject-report-index.py

@@ -21,10 +21,10 @@ import argparse
 import sys
 from pathlib import Path
 
-_HERE = Path(__file__).resolve().parent
-# Make ``okstra_ctl`` importable for in-repo invocation (the installed
-# runtime adds ``~/.okstra/lib/python`` via the wrapper scripts).
-sys.path.insert(0, str(_HERE))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_ctl/render_final_report.py")
 
 from okstra_ctl.i18n import SUPPORTED_LANGS  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
@@ -35,6 +35,7 @@ from okstra_ctl.render_final_report import (  # noqa: E402
 
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra inject-report-index",
         description="Inject the top-of-report index + scroll anchors into a free-form markdown report.",
     )
     parser.add_argument(

package/runtime/bin/okstra-provider-exec.py

@@ -9,23 +9,16 @@ write scope in the order the CLIs are told it, and the role's idle budget.
 from __future__ import annotations
 
 import json
-import os
 import shutil
 import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping
 
-_HERE = Path(__file__).resolve().parent
-# ``okstra_ctl`` sits beside this file in the repo (``scripts/``) but under
-# ``~/.okstra/lib/python/`` once installed, and the four-line shell entrypoints
-# that exec this script set no PYTHONPATH. Offer both, repo first.
-_HOME_LIB = (
-    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra"))) / "lib" / "python"
-)
-sys.path.insert(0, str(_HERE))
-if _HOME_LIB.is_dir() and str(_HOME_LIB) not in sys.path:
-    sys.path.append(str(_HOME_LIB))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_ctl/domain/provider.py")
 
 from okstra_ctl.domain.provider import (  # noqa: E402
     ProviderSpec,
@@ -54,7 +47,7 @@ from okstra_ctl.write_policy import (  # noqa: E402
     write_policy_from_payload,
 )
 from okstra_ctl.model_pool import ModelPool  # noqa: E402
-from okstra_ctl.agent_invocation import (  # noqa: E402
+from okstra_ctl.agent.invocation import (  # noqa: E402
     AgentInvocationError,
     agent_model_assignment_from_payload,
     invocation_metadata_identity,
@@ -259,11 +252,12 @@ def _v2_status_extra(
         recorded = project_root / recorded
     if recorded.resolve(strict=False) != prompt_path.resolve(strict=True):
         raise PreflightError(64, "invocation metadata prompt does not match wrapper")
-    role_execution, invocation, pool = _execution_authority(
+    role_execution, attempt_row, pool = _execution_authority(
         metadata=metadata,
         project_root=project_root,
         role_execution_ref=identity.role_execution_ref,
         invocation_ref=identity.invocation_ref,
+        attempt=identity.attempt,
     )
     binding = role_execution.binding
     if (
@@ -290,9 +284,9 @@ def _v2_status_extra(
         return ""
 
     try:
-        write_policy = write_policy_from_payload(invocation.write_policy)
+        write_policy = write_policy_from_payload(attempt_row.write_policy)
         write_enforcement = write_enforcement_from_payload(
-            invocation.write_enforcement
+            attempt_row.write_enforcement
         )
     except ValueError as exc:
         raise PreflightError(64, f"invocation write contract is invalid: {exc}") from exc
@@ -312,7 +306,7 @@ def _v2_status_extra(
             "level": "unknown",
             "source": "unavailable",
         },
-        "writePolicyDigest": invocation.write_policy_digest,
+        "writePolicyDigest": attempt_row.write_policy_digest,
         "writeEnforcement": write_enforcement.to_payload(),
     }, verify_attestation, write_policy, write_enforcement)
 
@@ -323,6 +317,7 @@ def _execution_authority(
     project_root: Path,
     role_execution_ref: str,
     invocation_ref: str,
+    attempt: int,
 ):
     source = metadata.get("contractSource")
     manifest_raw = source.get("runManifestPath") if isinstance(source, Mapping) else None
@@ -353,9 +348,19 @@ def _execution_authority(
         raise PreflightError(
             64, "invocation metadata invocation does not match run manifest"
         )
+    # 쓰기 계약은 이 시도의 행에 있다. invocation 으로 찾으면 재시도가 1회차의
+    # 허용 경로를 물고 자기 로그·상태 사이드카를 못 쓴다.
+    attempt_row = next((
+        row for row in manifest.attempts
+        if row.invocation_ref == invocation_ref and row.attempt == attempt
+    ), None)
+    if attempt_row is None:
+        raise PreflightError(
+            64, "invocation metadata attempt does not match run manifest"
+        )
     return (
         role_execution,
-        invocation,
+        attempt_row,
         ModelPool.from_registry(default_provider_registry()),
     )
 

package/runtime/bin/okstra-render-final-report.py

@@ -19,12 +19,10 @@ import argparse
 import sys
 from pathlib import Path
 
-_HERE = Path(__file__).resolve().parent
-# Make ``okstra_ctl`` and ``okstra_vendor`` importable when running from
-# repo (``scripts/`` is the parent of these packages). The installed
-# runtime adds ``~/.okstra/lib/python`` to PYTHONPATH via the wrapper
-# scripts; for in-repo invocation we add ``scripts/`` explicitly.
-sys.path.insert(0, str(_HERE))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_ctl/render_final_report.py")
 
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
@@ -34,8 +32,20 @@ from okstra_ctl.render_final_report import (  # noqa: E402
 )
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra render-final-report <path-to-final-report.data.json>
+
+schemaVersion 1.0
+keeps the legacy Markdown template; schemaVersion 2.0 selects the full reading
+copy template. Human HTML is rendered separately from the same data.json.
+"""
+
+
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra render-final-report",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Render a final-report markdown from its JSON SSOT.",
     )
     parser.add_argument(