okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/run.py

@@ -5,7 +5,6 @@ This function replaces the ~50-step wiring that previously lived in bash
 `okstra.sh`. It is called by:
   - `okstra.sh` (thin wrapper: argv → prepare_task_bundle → optional exec claude)
   - `okstra-run` skill (collects inputs via AskUserQuestion → calls this)
-  - okstra-ctl rerun (passes recorded invocation argv through)
 
 The function is read-modify-write on disk inside per-task mutex; it does not
 mutate the calling process environment or rely on inherited env values for
@@ -16,7 +15,13 @@ state passing, and are read once at the start.
 from __future__ import annotations
 
 import hashlib
-from argparse import Action, ArgumentError, ArgumentParser, Namespace
+from argparse import (
+    Action,
+    ArgumentError,
+    ArgumentParser,
+    Namespace,
+    RawDescriptionHelpFormatter,
+)
 import json
 import os
 import re
@@ -30,7 +35,7 @@ from pathlib import Path
 from typing import Mapping, Sequence
 
 from okstra_project import project_json_path, upsert_project_json
-from okstra_project.state import slugify
+from okstra_project.slug import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
 from .stage_ledger import (
@@ -38,6 +43,7 @@ from .stage_ledger import (
     render_stage_ledger,
     stage_ledger_notice,
 )
+from .prior_planning import build_prior_planning_summary
 from .analysis_inputs import (
     ANALYSIS_TASK_TYPES,
     AnalysisInputError,
@@ -134,7 +140,7 @@ from .schema_excerpt import build_schema_excerpt
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
 from .role_requirements import RoleProfile, RoleProfileError, load_role_profile
-from .agent_invocation import (
+from .agent.invocation import (
     AgentInstruction,
     AgentInstructionSource,
     AgentInvocationRequest,
@@ -170,7 +176,9 @@ from .render import (
 )
 from okstra_project.dirs import okstra_home
 
+from . import cmux
 from .dispatch_state import (
+    BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
     detect_terminal_backend,
     generate_claude_session_id,
@@ -192,6 +200,7 @@ from .session import (
     write_claude_resume_command_file,
 )
 from .pr_template import PrTemplateError, resolve_pr_template_path
+from .worker_artifacts import worker_provider_id
 from .workers import (
     normalize_workers,
     resolve_optional_workers,
@@ -386,20 +395,33 @@ def _validate_approved_plan_conformance(path: Path) -> None:
     bad = malformed_conformance_stages(data)
     if not bad:
         return
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    declared_by_stage = {
+        stage.get("stage"): stage.get("conformanceTests")
+        for stage in (planning or {}).get("stages") or []
+        if isinstance(stage, dict)
+    }
     # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
     # 실패한 런에서 검증기는 stage 2 만 지목했지만 실제로는 2~7 전부였다.
+    # 기록값을 병기한다: 무엇과 다른지 말하지 않는 실패는 실행이 스스로
+    # 고칠 수 없다 (validate_selected_direction_ref 의 snapshotPath 선례).
     stages = ", ".join(str(number) for number in bad)
+    got_lines = "".join(
+        f"  stage {number}: got {declared_by_stage.get(number)!r}\n"
+        for number in bad
+    )
     raise PrepareError(
         f"approved plan data.json has malformed conformanceTests for stage(s) "
         f"{stages}: {data_path}\n"
         "  each declaring stage must read "
         "`<task_root>/qa/scripts/stage-<N>.<ext> "
-        "(requires=[db|io|http|external,...])` after the "
-        "`Conformance tests: stage-<N> — ` prefix "
-        "(prompts/profiles/implementation-planning.md), or carry "
+        "(requires=[db|io|http|external,...])` — the data.json value carries "
+        "only the remainder after the `Conformance tests: stage-<N> — ` "
+        "prefix (prompts/profiles/implementation-planning.md) — or carry "
         "`Conformance exemption: <reason>` instead.\n"
-        "  re-run implementation-planning so the declaration is regenerated in "
-        "that form, then approve it."
+        f"{got_lines}"
+        "  correct the stage's `conformanceTests` value in the data.json to "
+        "the expected form, then approve it."
     )
 
 
@@ -544,6 +566,9 @@ class PrepareInputs:
     # project.json → global config → 스킬 디폴트 순으로 해석된다.
     pr_template_path: str = ""
     render_only: bool = False
+    # 워커가 뜰 표면을 호출자가 명시할 때만 채운다. 빈 값이면 prepare 가 직전
+    # run 의 값을 물려받거나 새로 탐지한다(`_resolve_terminal_backend`).
+    terminal_backend: str = ""
     approve_plan_ack: bool = False
     # implementation 전용: 유저가 implementation-planning final-report 에서 고른
     # Option Candidate 이름. `--implementation-option <name>` 으로 전달되어
@@ -607,16 +632,28 @@ def _validate_approved_plan(path: str) -> None:
         raise PrepareError("\n".join(lines))
 
 
-_STAGE_VALIDATOR_PATH = (
-    Path(__file__).resolve().parents[2] / "validators"
-    / "validate-implementation-plan-stages.py"
-)
+def _stage_validator_path() -> Path:
+    """설치본·체크아웃·빌드 런타임 중 validators 를 실제로 가진 루트에서 해소한다.
+
+    부모 개수를 세는 계산은 세 배치 중 하나에서만 맞는다 — 설치본은 패키지가
+    `~/.okstra/lib/python/` 이라 validators 가 `~/.okstra/lib/` 아래에 있고,
+    체크아웃은 `<repo>/validators` 다.
+    """
+    from .paths import STAGE_VALIDATOR_RELATIVE, find_asset_root
+
+    root = find_asset_root(STAGE_VALIDATOR_RELATIVE)
+    if root is None:
+        raise PrepareError(
+            "could not locate validate-implementation-plan-stages.py."
+            f"{_INSTALL_HINT}"
+        )
+    return root.joinpath(*STAGE_VALIDATOR_RELATIVE)
 
 
 def _validate_stage_structure(plan_path: str) -> None:
     """Run validators/validate-implementation-plan-stages.py against the approved plan."""
     r = _subprocess.run(
-        [sys.executable, str(_STAGE_VALIDATOR_PATH), "--plan", plan_path],
+        [sys.executable, str(_stage_validator_path()), "--plan", plan_path],
         capture_output=True, text=True,
     )
     if r.returncode != 0:
@@ -684,6 +721,221 @@ def _ensure_task_directories(ctx: dict) -> None:
         Path(ctx[key]).mkdir(parents=True, exist_ok=True)
 
 
+_ARCHIVE_DIR_NAME = "archive"
+
+# 재실행 잔재를 걷어낼 디렉터리. `(디렉터리 이름, ctx 경로 키, 매니페스트 카테고리)`.
+# **이전 seq 파일을 읽는 소비자가 한 곳도 없는 디렉터리만** 넣는다. 조사 결과는
+# `_archive_prior_run_seqs` docstring 에 있다.
+_ROTATED_RUN_DIRS: tuple[tuple[str, str, str], ...] = (
+    ("worker-results", "WORKER_RESULTS_PATH", "workerResults"),
+    ("prompts", "RUN_PROMPTS_DIR", "prompts"),
+)
+
+_ARCHIVE_README_NAME = "README.md"
+
+
+def _seq_of_entry(name: str, task_type_segment: str) -> str:
+    """`*-<task-type>-NNN[.<ext>]` 항목의 seq. 아니면 빈 문자열.
+
+    `paths.next_run_seq` 가 카운트하는 것과 같은 모양을 고른다 — 파일과 확장자
+    없는 디렉터리(`duty-contracts-<task-type>-NNN/`) 둘 다. 이 규칙에 안 걸리는
+    항목(`.agent-invocations/`, 잠금 파일)은 seq 소유가 아니므로 건드리지 않는다.
+    """
+    match = re.search(
+        rf"-{re.escape(task_type_segment)}-(\d{{3,}})(?:\.[^.]+)?$", name
+    )
+    return match.group(1) if match else ""
+
+
+def _published_run_seqs(run_dir: Path, task_type_segment: str) -> dict[str, str]:
+    """최근 published 리포트를 낸 런이 카테고리별로 기록한 seq.
+
+    reports/ 는 회전 대상이 아니라 언제나 전부 남아 있고, 그 리포트를 연
+    매니페스트의 `runSequencesByCategory` 가 같은 런의 나머지 카테고리 seq 를
+    묶는 유일한 기록이다. 재실행이 카테고리별로 다른 속도로 올라가므로
+    (`paths.next_run_seq` 가 디렉터리마다 따로 스캔한다) 이 대응 없이는 "리포트
+    017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다.
+    """
+    reports = run_dir / "reports"
+    manifests = run_dir / "manifests"
+    if not reports.is_dir() or not manifests.is_dir():
+        return {}
+    # 리포트 파일명은 `-NNN.data.json` 처럼 확장자가 두 마디라 `_seq_of_entry`
+    # 의 한 마디 규칙에 안 걸린다. 그 규칙은 seq 카운터(`paths.next_run_seq`)와
+    # 맞추려고 있는 것이고, 여기서 필요한 건 리포트 이름 규칙이다.
+    report_seq_re = re.compile(
+        rf"^final-report-{re.escape(task_type_segment)}-(\d{{3,}})"
+        r"(?:\.data)?\.(?:md|json)$"
+    )
+    seqs = sorted(
+        {
+            match.group(1) for match in (
+                report_seq_re.match(path.name) for path in reports.iterdir()
+            ) if match
+        },
+        key=int,
+    )
+    if not seqs:
+        return {}
+    published = seqs[-1]
+    for path in manifests.glob(f"run-manifest-{task_type_segment}-*.json"):
+        try:
+            payload = load_owned_object(path, artifact="run manifest")
+        except (OSError, JsonBoundaryError) as exc:
+            # 못 읽은 매니페스트는 회전 판단의 근거를 줄이므로 알린다. prepare 를
+            # 세우지는 않는다 — 하한을 못 풀면 아무것도 안 옮기는 쪽으로 떨어진다.
+            print(
+                f"okstra: cannot read run manifest for archive floor: {path} ({exc})",
+                file=sys.stderr,
+            )
+            continue
+        categories = payload.get("runSequencesByCategory")
+        if not isinstance(categories, dict):
+            continue
+        if str(categories.get("reports") or "") != published:
+            continue
+        return {
+            key: str(value)
+            for key, value in categories.items()
+            if isinstance(value, str) and value
+        }
+    return {}
+
+
+def _archive_prior_run_seqs(ctx: dict) -> None:
+    """이 run dir 에 쌓인 이전 seq 산출물을 `archive/run-<seq>/` 로 옮긴다.
+
+    같은 `runs/<task-type>/` 에 24회 재실행한 task 에서 worker-results 에만
+    200개 넘는 파일이 쌓였고, 그 디렉터리를 글롭하는 검사들의 실패 건수가
+    재실행을 거치며 30 → 140 으로 늘었다. 재실행 자체는 정상 동작이므로 잔재를
+    치우는 자리는 prepare 다.
+
+    **회전 대상은 두 디렉터리뿐이다.** 소비자 전수 조사에서 이전 seq 파일을
+    읽는 소비자가 하나도 없는 곳만 골랐다:
+
+    - `worker-results/` — 읽는 쪽은 `run_audit._current_seq_results` 와
+      `context_cost._current_seq_worker_results` 둘인데 **둘 다 파일명의 최대
+      seq 로 스코핑**하며, 각각 이전 seq 혼입으로 생긴 실제 오측정 사례를
+      주석에 달고 있다.
+    - `prompts/` — 이전 seq 프롬프트를 경로로 여는 소비자가 없다.
+      `log_report` 는 `runs`/`prompts` 를 포함하는 경로를 rglob 하므로
+      `archive/run-NNN/prompts/` 도 계속 집계한다.
+
+    **`state/` 와 `logs/` 는 남긴다.** 둘 다 이전 seq 를 실제로 읽는다:
+
+    - `state/` — `okstra plan-items seed --prior-state` 가 이전 런의
+      `plan-body-verification-<task-type>-<seq>.json` 을, `prior_planning` 이
+      이전 런의 `convergence-<task-type>-<seq>.json` 을, `time-report` 가
+      타임라인이 기록한 모든 런의 `team-state-*.json` 을 연다. published 리포트를
+      상대로 하는 재실행은 그 리포트의 state seq 가 읽혀야 성립한다.
+    - `logs/` — `error_log_core` 가 `runs/*/logs/errors-*.jsonl` 을 한 단계
+      글롭으로만 훑는다. `archive/run-NNN/logs/` 는 그 패턴에 안 걸려서, 옮기면
+      `error-report`/`error-zip`/prepare 의 이전 런 오류 요약이 조용히 비게 된다.
+
+    보존 하한(floor)은 최근 published 리포트가 그 카테고리에 기록한 seq다. 그
+    seq 와 그 위는 전부 남고, 아래만 옮긴다. 매니페스트로 그 대응을 못 풀면
+    **아무것도 안 옮긴다** — 디렉터리의 최대 seq 를 하한으로 대신 쓰면 "한 seq 만
+    남기고 전부" 가 되어 보수적 기본값이 아니다. 하한이 언제나 최대 이전 seq
+    이하이므로 `paths.next_run_seq`(디렉터리의 **최대** seq 만 읽는다)가 보는
+    값은 변하지 않고, seq 배정은 단조성을 유지한다.
+
+    옮기기지 지우기가 아니다. 목적지가 이미 있으면 건너뛴다.
+    """
+    run_dir = Path(ctx["RUN_DIR"])
+    segment = ctx["TASK_TYPE_SEGMENT"]
+    archive_root = run_dir / _ARCHIVE_DIR_NAME
+    published = _published_run_seqs(run_dir, segment)
+    moved: list[tuple[str, str, str]] = []
+    for dir_name, ctx_key, category in _ROTATED_RUN_DIRS:
+        directory = Path(ctx[ctx_key])
+        if not directory.is_dir():
+            continue
+        by_seq: dict[str, list[Path]] = {}
+        for entry in directory.iterdir():
+            seq = _seq_of_entry(entry.name, segment)
+            if seq:
+                by_seq.setdefault(seq, []).append(entry)
+        floor = published.get(category, "")
+        if not by_seq or not floor:
+            # 하한을 못 정하면 아무것도 안 옮긴다. 디렉터리의 최대 seq 를 하한으로
+            # 대신 쓰면 "한 seq 만 남기고 전부" 가 되어 보수적 기본값이 아니다.
+            continue
+        for seq in sorted(by_seq, key=int):
+            if int(seq) >= int(floor):
+                continue
+            destination = archive_root / f"run-{seq}" / dir_name
+            destination.mkdir(parents=True, exist_ok=True)
+            for entry in by_seq[seq]:
+                target = destination / entry.name
+                if target.exists():
+                    continue
+                shutil.move(str(entry), str(target))
+                moved.append((seq, dir_name, entry.name))
+    if moved:
+        _write_archive_readme(archive_root, segment, published, moved)
+
+
+def _write_archive_readme(
+    archive_root: Path,
+    task_type_segment: str,
+    published: dict[str, str],
+    moved: list[tuple[str, str, str]],
+) -> None:
+    """archive/ 가 자기를 설명하게 한다.
+
+    이 디렉터리를 처음 보는 사람에게는 산출물이 사라진 것으로 보인다. 무엇이
+    어느 seq 에서 왜 옮겨졌고 되돌리는 방법이 무엇인지를 디렉터리 안에 적어,
+    이 대화 밖에서도 답이 나오게 한다.
+    """
+    counts: dict[tuple[str, str], int] = {}
+    for seq, dir_name, _name in moved:
+        counts[(seq, dir_name)] = counts.get((seq, dir_name), 0) + 1
+    rows = "\n".join(
+        f"| {seq} | `{dir_name}/` | {count} | `run-{seq}/{dir_name}/` |"
+        for (seq, dir_name), count in sorted(counts.items())
+    )
+    floors = ", ".join(
+        f"`{category}`={seq}" for category, seq in sorted(published.items())
+    ) or "해소 불가 (매니페스트에 published 리포트의 seq 대응이 없음)"
+    (archive_root / _ARCHIVE_README_NAME).write_text(
+        f"""# 재실행 잔재 보관소 — `runs/{task_type_segment}/`
+
+`okstra` 는 같은 `runs/{task_type_segment}/` 에 재실행할 때마다 새 seq 를
+배정한다. 이전 seq 산출물이 그대로 쌓이면 그 디렉터리를 글롭하는 검사들이 다른
+런의 파일까지 이 런의 것으로 세어, 실패 건수가 재실행마다 늘어난다. prepare 가
+그 잔재를 여기로 **옮긴다(지우지 않는다)**.
+
+## 이번에 옮긴 것
+
+| seq | 원래 디렉터리 | 항목 수 | 보관 위치 |
+|---|---|---|---|
+{rows}
+
+보존 하한: 최근 published 리포트가 기록한 seq — {floors}. 이 seq 와 그 위는
+원래 자리에 그대로 있다.
+
+## 옮기지 않는 것
+
+`reports/`, `manifests/`, `state/`, `status/`, `sessions/`, `logs/`, `carry/`,
+`user-responses/` 는 건드리지 않는다. 이전 seq 를 실제로 읽는 소비자가 있다 —
+`state/` 는 `okstra plan-items seed --prior-state` 와 `prior_planning`,
+`logs/` 는 `error-report` / `error-zip` 의 `runs/*/logs/errors-*.jsonl` 글롭.
+
+## 되돌리려면
+
+원래 자리로 되돌린다. 예:
+
+```sh
+mv run-<seq>/worker-results/* ../worker-results/
+```
+
+되돌린 뒤 그 seq 가 디렉터리의 최대 seq 가 되지 않는지 확인한다 — seq 배정
+(`okstra_ctl.paths.next_run_seq`)은 디렉터리의 최대 seq 만 읽는다.
+""",
+        encoding="utf-8",
+    )
+
+
 def _role_execution_refs_from_ctx(ctx: dict) -> list[str]:
     try:
         payload = json.loads(ctx.get("EXECUTION_IDENTITY_JSON") or "{}")
@@ -705,9 +957,7 @@ def _record_start(
     cwd: str,
     brief_sha256: str,
 ) -> None:
-    """record_start hook 호출. okstra-central.sh 의 bash wrapper 와 같은 동작
-    이지만 python 직접 호출이라 환경 변수 의존 없음.
-    """
+    """record_start hook 호출 — 중앙 인덱스에 이 run 의 시작을 기록한다."""
     from datetime import datetime, timezone
     from okstra_ctl import record_start
     from .locks import central_lock
@@ -715,7 +965,7 @@ def _record_start(
     home = okstra_home()
     home.mkdir(mode=0o700, parents=True, exist_ok=True)
     os.chmod(home, 0o700)
-    # bootstrap (okstra_central_bootstrap 와 동등) — 디렉터리·jsonl 파일 보장.
+    # 중앙 홈 bootstrap — 디렉터리·jsonl 파일 보장.
     for sub in ("archive", ".locks", "batches", "projects"):
         (home / sub).mkdir(exist_ok=True)
     for f in ("active.jsonl", "recent.jsonl"):
@@ -780,7 +1030,7 @@ def _remove_leaked_reservation(ctx: dict, run_seq: int) -> None:
             )
     except Exception as exc:  # noqa: BLE001 — cleanup 실패는 비치명적
         print(
-            f"okstra-central: reservation cleanup failed after record_start error ({exc})",
+            f"central index: reservation cleanup failed after record_start error ({exc})",
             file=sys.stderr,
         )
 
@@ -819,6 +1069,31 @@ def _record_artifact_runtime_render_only_event(inp: PrepareInputs, ctx: dict) ->
     )
 
 
+def _workers_flag_value(roster_csv: str) -> str:
+    """로스터 CSV 를 `--workers` 가 받는 어휘(provider id)로 되돌린다.
+
+    두 어휘가 다르다. 로스터 행은 슬롯 id(`codex-verifier`)이고 `--workers` 는
+    프로파일의 `Required workers:` 가 선언한 **provider 허용목록**이다
+    ([`workers.py`](workers.py)). 로스터를 그대로 실으면 재실행 argv 가
+    `unknown workers: codex-verifier` 로 죽는다 — 이 인자를 만드는 곳은 여기
+    하나뿐이므로 변환도 여기서 한다.
+
+    같은 provider 의 슬롯 둘은 한 항목으로 접힌다. 슬롯 수는 이 인자가 아니라
+    함께 실리는 `--role-count` · `--role-model` 이 나른다.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+    for token in (part.strip() for part in roster_csv.split(",")):
+        if not token:
+            continue
+        provider = worker_provider_id(token)
+        if provider in seen:
+            continue
+        seen.add(provider)
+        out.append(provider)
+    return ",".join(out)
+
+
 def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
     """rerun 충실 재현을 위한 canonical argv 재구성."""
     has_role_selection = bool(inp.role_counts_raw or inp.role_models_raw)
@@ -827,7 +1102,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         {} if inp.host_session_context.entry_mode == "current-session"
         else legacy_fallbacks
     )
-    workers = inp.workers_override or (
+    workers = inp.workers_override or _workers_flag_value(
         legacy_fallbacks.get("RECOMMENDED_ANALYSERS", "")
     )
     pairs = [
@@ -900,6 +1175,9 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ])
     if inp.render_only:
         argv.append("--render-only")
+    # `--terminal-backend` 은 일부러 빠진다. 그것은 "이번엔 표면 없이 간다"는
+    # 1회성 선언이지 task 의 성질이 아니다 — cmux 가 멀쩡한 기계에서의 rerun 은
+    # 다시 pane 을 받아야 한다.
     if not inp.plan_verification_enabled:
         argv.append("--no-plan-verification")
     argv.append("--yes")
@@ -1005,8 +1283,23 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         workspace_root / "templates" / "reports" / "final-report-v2.template.md"
     )
     lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
-    run_validator = workspace_root / "validators" / "validate-run.py"
-    brief_validator = workspace_root / "validators" / "validate-brief.py"
+    # validators 는 workspace_root 아래가 아니라 "실행 중인 파이썬 패키지와 짝이
+    # 되는 루트" 에 있다: 설치본은 `~/.okstra/lib/validators`, 체크아웃은
+    # `<repo>/validators`, 빌드 런타임은 `runtime/validators`. workspace_root 로
+    # 계산하면 `~/.okstra/bin/okstra.sh` 진입점(workspace_root=`~/.okstra`)이
+    # 신선한 설치에서도 "validate-run.py 없음" 으로 죽었다.
+    from .paths import (
+        BRIEF_VALIDATOR_RELATIVE,
+        RUN_VALIDATOR_RELATIVE,
+        find_asset_root,
+    )
+
+    run_validator = (
+        find_asset_root(RUN_VALIDATOR_RELATIVE) or workspace_root
+    ).joinpath(*RUN_VALIDATOR_RELATIVE)
+    brief_validator = (
+        find_asset_root(BRIEF_VALIDATOR_RELATIVE) or workspace_root
+    ).joinpath(*BRIEF_VALIDATOR_RELATIVE)
     for required in (
         task_index_template,
         final_report_template,
@@ -1596,14 +1889,16 @@ def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> N
     if not inp.qa_waiver:
         return
     from .conformance import apply_qa_waiver, parse_qa_waiver_arg
-    from .paths import task_dir
+    from .paths import task_conformance_manifest_file, task_dir
     parsed = parse_qa_waiver_arg(inp.qa_waiver)
     if parsed is None:
         raise PrepareError(
             f'--qa-waiver must be "<stageKey>:<reason>", got {inp.qa_waiver!r}'
         )
     stage_key, reason = parsed
-    manifest_path = task_dir(project_root, inp.task_group, inp.task_id) / "qa" / "conformance-manifest.json"
+    manifest_path = task_conformance_manifest_file(
+        task_dir(project_root, inp.task_group, inp.task_id)
+    )
     with worktree_provision_mutex(
         okstra_home(), inp.project_id, slugify(inp.task_group), slugify(inp.task_id),
     ):
@@ -1626,10 +1921,9 @@ def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: i
     the user re-waived this exact stage for this run via `--qa-waiver` (already
     applied upstream in `_apply_qa_waiver_if_requested`)."""
     from .conformance import clear_qa_waiver, parse_qa_waiver_arg
-    from .paths import task_dir
-    manifest_path = (
+    from .paths import task_conformance_manifest_file, task_dir
+    manifest_path = task_conformance_manifest_file(
         task_dir(project_root, inp.task_group, inp.task_id)
-        / "qa" / "conformance-manifest.json"
     )
     if not manifest_path.is_file():
         return
@@ -1723,7 +2017,7 @@ def _normalize_prepare_model_selection(
     profile_file: Path,
 ) -> tuple[CanonicalModelSelection, RoleProfile]:
     try:
-        _validate_critic_choice(inp.critic, inp.task_type)
+        _validate_critic_choice(inp.critic)
         profile = load_role_profile(profile_file)
         profile_workers = resolve_profile_workers(profile_file)
         has_worker_models = bool(
@@ -1805,7 +2099,9 @@ def _resolve_prepare_assignments(
         execution_provider_ids=provider_ids_for_snapshot,
     )
     host = _effective_host_session_context(inp, lead_runtime)
-    role_models = _materialize_selection_models(selection, context, host)
+    role_models = _materialize_selection_models(
+        selection, context, host, inp.lead_provider
+    )
     role_counts = _resolver_role_counts(profile, selection.role_counts)
     try:
         plan = resolve_assignments(
@@ -2104,6 +2400,7 @@ def _materialize_selection_models(
     selection: CanonicalModelSelection,
     context: AssignmentContext,
     host: HostSessionContext,
+    requested_lead_provider: str = "",
 ) -> dict[str, tuple[str, ...]]:
     role_models = dict(selection.role_models)
     for role, providers in selection.provider_constraints.items():
@@ -2123,9 +2420,81 @@ def _materialize_selection_models(
                 raise PrepareError(str(exc)) from exc
             resolved.append(str(model.model_ref))
         role_models[role] = tuple(resolved)
+    _apply_unselected_role_defaults(
+        role_models, context, host, requested_lead_provider
+    )
     return role_models
 
 
+_LEGACY_ROLE_DEFAULT_ENV = {
+    "leader": "OKSTRA_DEFAULT_LEAD_MODEL",
+    "report-writer": "OKSTRA_DEFAULT_REPORT_WRITER_MODEL",
+}
+
+
+def _apply_unselected_role_defaults(
+    role_models: dict[str, tuple[str, ...]],
+    context: AssignmentContext,
+    host: HostSessionContext,
+    requested_lead_provider: str,
+) -> None:
+    """아무도 고르지 않은 lead · report-writer 역할의 기본값을 채운다.
+
+    두 가지가 여기 모인다. **lead 의 provider 는 호스트가 정한다** —
+    codex 호스트의 in-session lead 는 codex 여야 하고 다른 provider 요청은
+    거부된다(`resolve_context_lead_provider`). 그리고
+    `OKSTRA_DEFAULT_LEAD_MODEL` · `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 은
+    문서화된 사용자 노브다([`usage.sh`](../lib/okstra/usage.sh)).
+
+    둘 다 레거시 바인딩 경로에만 있었다. 그래서 위저드로 연 런은 env 노브를
+    이미 무시했고, 호스트 고정은 렌더 단계(`render.py` `_lead_assignment`)에서
+    한 번 더 계산돼 두 값이 갈릴 수 있었다. 해소를 resolver 입력인
+    `role_models` 로 옮겨 모든 경로가 같은 값을 본다.
+
+    명시 선택(`--role-model` · `--lead-model` · `--report-writer-model` 및 그
+    변환 결과)이 이미 그 역할을 채웠으면 건드리지 않는다. env 는 기본값이지
+    오버라이드가 아니다.
+    """
+    # 호스트 적합성은 lead 를 누가 골랐든 prepare 에서 판정한다. 이 호출을
+    # 조건부로 두면 `--lead-provider` 가 명시된 런만 검사를 건너뛰고, 그 불일치가
+    # 렌더 단계에서 raw `HostCapabilityMismatch` 로 터진다 — prepare 가 이미
+    # worktree 와 상태 파일을 만든 뒤다.
+    try:
+        host_lead_provider = resolve_context_lead_provider(
+            context=context,
+            requested_provider=requested_lead_provider,
+        ).provider
+    except (
+        HostCapabilityMismatch,
+        HostNotRegistered,
+        ProviderUnavailable,
+    ) as exc:
+        raise PrepareError(str(exc)) from exc
+
+    for role, env_name in _LEGACY_ROLE_DEFAULT_ENV.items():
+        if role in role_models:
+            continue
+        if role == "leader":
+            # current-session lead 의 정체성은 호스트가 증언한 것뿐이다. 여기서
+            # 기본값을 채우면 호스트가 증언하지 않은 모델을 합성하게 된다 —
+            # 증언이 `unknown` 인 세션도 `unknown` 으로 남아야 한다.
+            if host.entry_mode == "current-session":
+                continue
+            provider = host_lead_provider
+        else:
+            provider = _fallback_legacy_provider(role, context, host)
+        raw_model = _legacy_claude_model_override(provider, env_name)
+        if not raw_model and role != "leader":
+            continue
+        try:
+            model = resolve_model_selection(context.pool, provider, role, raw_model)
+        except (ValueError, RuntimeError) as exc:
+            raise PrepareError(
+                f"{env_name}: {exc}" if raw_model else str(exc)
+            ) from exc
+        role_models[role] = (str(model.model_ref),)
+
+
 def _fallback_legacy_provider(
     role: str,
     context: AssignmentContext,
@@ -2502,7 +2871,7 @@ def _resolve_model_bindings(
 ) -> _ModelBindings:
     """worker 모델 + critic 선택 + executor 바인딩을 한 묶음으로 해소·검증한다."""
     m = _resolve_worker_models(inp, workers, context)
-    critic_choice = _validate_critic_choice(inp.critic, inp.task_type)
+    critic_choice = _validate_critic_choice(inp.critic)
     critic_model_execution = ""
     critic_meta = None
     if critic_choice in provider_ids("critic"):
@@ -2547,7 +2916,6 @@ def _resolve_model_bindings(
         resolved=translator_meta,
         role="translator",
     )
-    _reject_split_worker_models(executor_assignment, worker_assignments)
     invocation_assignments = _build_invocation_assignments(
         lead_assignment,
         worker_assignments,
@@ -2581,23 +2949,15 @@ def _resolve_model_bindings(
     )
 
 
-_CRITIC_REQUIRED_TASK_TYPES = frozenset({
-    "requirements-discovery",
-    "error-analysis",
-    "implementation-planning",
-    "final-verification",
-})
-
+def _validate_critic_choice(raw_value: str) -> str:
+    """critic 은 어느 phase 에서도 opt-in 이다 — 프로필이 `min: 0` 으로 선언한다.
 
-def _validate_critic_choice(raw_value: str, task_type: str = "") -> str:
+    위저드에서 "추가 안 함" 을 고를 수 있는 역할을 이 경로에서만 거부하면 같은
+    구성이 진입점마다 다르게 판정된다.
+    """
     critic_choice = (raw_value or "").strip().lower()
     allowed_critics = ["", *provider_ids("critic")]
     if critic_choice == "off":
-        if task_type in _CRITIC_REQUIRED_TASK_TYPES:
-            raise PrepareError(
-                "--critic off is not allowed; critic is required "
-                f"for {task_type}"
-            )
         return "off"
     if critic_choice not in allowed_critics:
         raise PrepareError(
@@ -2632,17 +2992,14 @@ def _project_assignment_plan(
             role="report-writer",
         )
     )
-    worker_rows = tuple(
-        row for row in plan.assignments
-        if row.role not in {"leader", "critic", "implementer", "report-writer"}
-    )
+    roster_rows = _worker_id_scope(plan)
     worker_assignments = tuple(
         _role_assignment(
             resolved=row,
             role=row.role,
-            worker_id=_canonical_worker_id(row, worker_rows),
+            worker_id=_canonical_worker_id(row, roster_rows),
         )
-        for row in worker_rows
+        for row in roster_rows
     )
     if report_rows:
         worker_assignments = (
@@ -2664,15 +3021,57 @@ def _project_assignment_plan(
     return [row.worker_id for row in worker_assignments], models
 
 
+def _analysis_worker_rows(
+    plan: AssignmentPlan,
+) -> tuple[ResolvedAssignment, ...]:
+    """워커로 디스패치되는 분석 역할 배정 — 리드·critic·실행자·리포트라이터 제외."""
+    return tuple(
+        row for row in plan.assignments
+        if row.role not in {"leader", "critic", "implementer", "report-writer"}
+    )
+
+
+def _worker_id_scope(
+    plan: AssignmentPlan,
+) -> tuple[ResolvedAssignment, ...]:
+    """worker_id 를 발급받는 배정 전체를 정본 순서로 모은다.
+
+    실행자를 앞에 세우는 것은 같은 (provider, 역할) 쌍이 겹칠 때 붙는 번호를
+    결정적으로 만들기 위해서다 — `worker_prompt_policy` 는 `EXECUTOR_WORKER_ID`
+    와 같은 id 를 실행자로 실체화하므로, 실행자 id 가 흔들리면 실행자 프롬프트가
+    통째로 바뀐다.
+    """
+    return (*plan.by_role("implementer"), *_analysis_worker_rows(plan))
+
+
 def _canonical_worker_id(
     assignment: ResolvedAssignment,
     rows: Sequence[ResolvedAssignment],
 ) -> str:
-    prior = sum(
-        row.provider_id == assignment.provider_id and row.ordinal < assignment.ordinal
-        for row in rows
-    )
-    return assignment.provider_id if prior == 0 else f"{assignment.provider_id}-{prior + 1}"
+    """로스터 슬롯의 worker_id — 언제나 `<provider>-<역할>`.
+
+    역할을 조건부로 붙이면(한 provider 가 두 슬롯을 차지할 때만) 같은 역할이
+    로스터 구성에 따라 다른 이름 모양을 갖는다: 같은 검증자가 어떤 런에서는
+    `codex`, 어떤 런에서는 `codex-verifier` 다. 그러면 `--workers` 인자를 손으로
+    조립할 수 없고 — 리드는 로스터를 먼저 읽어야만 슬롯을 지명할 수 있다.
+    항상 붙이면 id 가 자기 역할을 말한다.
+
+    같은 (provider, 역할) 쌍이 또 있으면(모델이 다른 검증자 둘) 두 번째부터
+    번호를 덧붙인다. `ordinal` 로는 셀 수 없다 — role 안에서만 매겨져
+    ([`assignment_resolver`](assignment_resolver.py)) implementer/claude 와
+    verifier/claude 가 둘 다 1 이다. 그래서 `rows` 순서에서 위치로 센다.
+
+    고정 id 인 `report-writer` 는 이 함수를 거치지 않는다.
+    """
+    provider = assignment.provider_id
+    prior_same_role = 0
+    for row in rows:
+        if row is assignment:
+            break
+        if row.provider_id == provider and row.role == assignment.role:
+            prior_same_role += 1
+    slot = f"{provider}-{assignment.role}"
+    return slot if prior_same_role == 0 else f"{slot}-{prior_same_role + 1}"
 
 
 def _project_model_bindings(
@@ -2695,7 +3094,7 @@ def _project_model_bindings(
         _role_assignment(
             resolved=executor_rows[0],
             role="executor",
-            worker_id=executor_rows[0].provider_id,
+            worker_id=_canonical_worker_id(executor_rows[0], _worker_id_scope(plan)),
         )
         if executor_rows
         else None
@@ -2711,8 +3110,6 @@ def _project_model_bindings(
         provider: _legacy_projection_from_plan(provider, plan, context)
         for provider in ("claude", "codex", "antigravity")
     }
-    _reject_executor_outside_roster(executor_assignment, workers)
-    _reject_split_worker_models(executor_assignment, workers)
     invocation_assignments = _build_invocation_assignments(
         lead_assignment,
         workers,
@@ -2799,64 +3196,6 @@ def _selected_execution_provider_ids(
     return tuple(dict.fromkeys(selected))
 
 
-def _reject_executor_outside_roster(
-    executor: RoleAssignment | None,
-    workers: tuple[RoleAssignment, ...],
-) -> None:
-    """Refuse an executor whose provider the roster never dispatches.
-
-    An implementation run opens its executor with `--workers <provider>`, so a
-    provider absent from the roster has no invocation to open. The legacy
-    selection path says so outright; the canonical path derived its roster from
-    role models alone, so `--executor <provider>` rendered fine and the run only
-    failed later, at `requested worker(s) are not in this run roster`.
-    """
-    if executor is None:
-        return
-    roster = {row.worker_id for row in workers if row.worker_id}
-    if executor.worker_id in roster:
-        return
-    raise PrepareError(
-        f"--executor {executor.worker_id} is not in this run's roster "
-        f"({', '.join(sorted(roster)) or 'empty'}); the executor is dispatched "
-        f"as a worker, so give it a roster slot — "
-        f"--role-model verifier={executor.worker_id}/<model> — or pick an "
-        f"executor already in the roster."
-    )
-
-
-def _reject_split_worker_models(
-    executor: RoleAssignment | None,
-    workers: tuple[RoleAssignment, ...],
-) -> None:
-    """Refuse one worker id standing for two roles on two different models.
-
-    The roster names a worker by provider, so an implementation run whose
-    executor and verifier are the same provider shares that id — but
-    `invocationAssignments["initial/<id>"]` can hold only one model, and it
-    holds the verifier's. Dispatch then looks the executor's role execution up
-    by that assignment, finds no row with a matching execution value, and stops
-    at `v2 execution identity does not match a canonical role execution`. The
-    render used to succeed and only the dispatch failed, by which point the run
-    had already claimed its stage.
-    """
-    if executor is None:
-        return
-    peer = next(
-        (row for row in workers if row.worker_id == executor.worker_id),
-        None,
-    )
-    if peer is None or peer.model_execution_value == executor.model_execution_value:
-        return
-    raise PrepareError(
-        f"worker {executor.worker_id!r} is the executor on "
-        f"{executor.model_execution_value!r} and a verifier on "
-        f"{peer.model_execution_value!r}; one worker id carries one model. "
-        f"Give both roles the same model, or pick a different --executor "
-        f"provider."
-    )
-
-
 def _resolve_executor_assignment(
     inp: PrepareInputs,
     workers: list[str],
@@ -3131,8 +3470,17 @@ def write_verification_target_snapshot(
     normalized = normalized.rstrip() + "\n"
     digest = "sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()
     path = instruction_set / "verification-target.md"
+    # 계산 규칙을 값과 함께 적는다. 워커는 이 다이제스트를 프롬프트 앵커로도
+    # 받는데, 규칙을 모르면 파일 전체 바이트로 재고 반드시 불일치를 본다 —
+    # 실측(2026-08-26): 그렇게 잰 검증자가 스냅샷이 변조됐다고 보고했다.
+    # 다이제스트 줄은 줄머리 앵커로 잘리므로(`_TARGET_DIGEST_RE`) 그 뒤에
+    # 붙는 이 줄은 본문에 들어가지 않는다.
     path.write_text(
-        normalized + f"- **Verification target digest:** `{digest}`\n",
+        normalized
+        + f"- **Verification target digest:** `{digest}`\n"
+        + "- **Digest rule:** `sha256` of the text above this line, with CRLF "
+          "and CR normalized to LF, trailing whitespace stripped, and exactly "
+          "one closing newline. This line and the digest line are not covered.\n",
         encoding="utf-8",
     )
     return path, digest
@@ -3276,6 +3624,15 @@ def _write_instruction_set_sources(
         clarification_body = attached_user_responses_section(
             Path(inp.approved_plan_path)
         )
+    elif inp.task_type == "implementation-planning" and inp.selected_direction_path:
+        # 새 계획 carry-in: 후보비교 리포트는 `--selected-direction` 으로 이미
+        # 정규화돼 들어가지만, 그 스냅샷이 싣는 것은 선택된 방향 자체뿐이다
+        # (`implementation_direction.write_selected_direction_snapshot`).
+        # 같은 사이드카의 `C-NNN` 답변은 그 경로로 오지 않는다 — 붙이지 않던
+        # 동안 사용자는 계획 런에 답변을 전달할 채널이 없었다.
+        clarification_body = attached_user_responses_section(
+            Path(inp.selected_direction_path)
+        )
     else:
         clarification_body = ""
     _stage_or_clear(
@@ -3294,6 +3651,15 @@ def _write_instruction_set_sources(
         build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent)
         if inp.task_type == "implementation-planning" else None
     )
+    # 새 계획을 여는 진입점은 `--selected-direction` 하나뿐이고
+    # (`run._validate_planning_entry_inputs`), 답변된 clarification 이 없는
+    # 재실행은 전부 이 경로로 들어온다. clarification 재실행 쪽은 직전 리포트를
+    # 이미 `clarification-response.md` 로 받으므로 여기서 또 싣지 않는다.
+    prior_planning_summary = (
+        build_prior_planning_summary(Path(ctx["TASK_MANIFEST_PATH"]).parent)
+        if inp.task_type == "implementation-planning" and inp.selected_direction_path
+        else ""
+    )
     packet = build_analysis_packet(
         task_key=ctx["TASK_KEY"],
         task_type=ctx["TASK_TYPE"],
@@ -3310,6 +3676,7 @@ def _write_instruction_set_sources(
             fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
         stage_ledger_json=render_stage_ledger(stage_ledger),
         stage_ledger_notice=stage_ledger_notice(stage_ledger),
+        prior_planning_summary=prior_planning_summary,
     )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (
@@ -3697,6 +4064,9 @@ def _write_bundle_artifacts(
     """
     _ensure_task_directories(ctx)
     migrate_legacy_run_artifacts(ctx)
+    # 회전은 legacy 이관 **뒤**다. 이관이 run dir 루트의 옛 평면 파일을 이 하위
+    # 디렉터리들로 옮기므로, 먼저 돌면 그 파일들이 회전 대상에서 빠진다.
+    _archive_prior_run_seqs(ctx)
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
     )
@@ -3842,11 +4212,37 @@ def _record_run_in_central_index(
         )
     except Exception as exc:
         print(
-            f"okstra-central: record_start failed; central index will be incomplete ({exc})",
+            f"central index: record_start failed; central index will be incomplete ({exc})",
             file=sys.stderr,
         )
         if run_seq_override is not None:
             _remove_leaked_reservation(ctx, run_seq_override)
+        return
+    _reconcile_prior_runs(ctx)
+
+
+def _reconcile_prior_runs(ctx: dict) -> None:
+    """이 프로젝트의 이전 run 행들을 디스크 사실로 재조정한다. 절대 치명적이지 않다.
+
+    `validators/validate-run.py` 가 종결 시점에 같은 재조정을 돌리지만, 검증까지
+    못 가고 죽은 run 은 그 경로를 타지 않아 `running` 인 채 남는다. 그런 행은
+    다음 run 이 시작될 때 여기서 abort 타임아웃으로 정리된다.
+
+    `_record_start` 가 중앙 락을 이미 놓은 뒤에 부른다 — flock 은 재진입 불가라
+    락 안에서 부르면 self-deadlock 이다(`locks.central_lock`).
+    """
+    from .reconcile import reconcile_home
+
+    project_id = str(ctx.get("PROJECT_ID", ""))
+    if not project_id:
+        return
+    try:
+        reconcile_home(okstra_home(), project=project_id)
+    except Exception as exc:  # noqa: BLE001 — 재조정 실패는 prepare 를 무르지 않는다
+        print(
+            f"central index: reconcile after record_start failed ({exc})",
+            file=sys.stderr,
+        )
 
 
 def _initial_workflow_ctx(
@@ -4037,6 +4433,75 @@ def _provision_task_and_stage(
         return _ProvisionedTask(worktree, None, fv_stage_arg)
 
 
+def _prior_run_backend(project_root: Path, inp: PrepareInputs) -> str:
+    """이 task 의 같은 phase 를 마지막으로 돌린 run 이 기록한 `terminalBackend`.
+    그런 run 이 없으면 "".
+
+    stage 하위 트리(`runs/<task-type>/stage-N/`)까지 함께 훑는다. stage 는 이
+    시점에 아직 정해지지 않았고, 어느 stage 였든 "같은 기계에서 방금 cmux 에
+    붙었다"는 사실은 같기 때문이다.
+    """
+    from .paths import runs_dir_of, task_dir
+
+    run_root = runs_dir_of(
+        task_dir(project_root, inp.task_group, inp.task_id)
+    ) / slugify(inp.task_type)
+    seq_pattern = re.compile(r"-(\d{3,})\.json$")
+    latest = (-1, "")
+    for manifest in run_root.rglob("run-manifest-*.json"):
+        if manifest.parent.name != "manifests":
+            continue
+        matched = seq_pattern.search(manifest.name)
+        if not matched:
+            continue
+        seq = int(matched.group(1))
+        if seq <= latest[0]:
+            continue
+        try:
+            payload = load_owned_object(manifest, artifact="run-manifest")
+        except JsonBoundaryError:
+            # 못 읽는 옛 매니페스트가 이 판정을 막을 이유는 없다 — 다음
+            # 후보를 계속 본다.
+            continue
+        latest = (seq, str(payload.get("terminalBackend") or ""))
+    return latest[1]
+
+
+def _resolve_terminal_backend(project_root: Path, inp: PrepareInputs) -> str:
+    """이 run 의 워커가 뜰 표면. 탐지는 하되, 조용한 강등은 하지 않는다.
+
+    표면은 사용자가 보는 것이다. cmux 아래에서 시작한 task 가 다음 run 부터
+    말없이 cli-wrapper 로 내려가면 워커는 pane 없이 백그라운드로 돌고, 리드는
+    매니페스트를 그대로 믿기 때문에 아무도 바뀐 줄 모른다. 실제로 그렇게
+    내려간다: 탐지의 마지막 단계는 cmux 소켓 ping 인데, codex 의
+    workspace-write 샌드박스는 AF_UNIX connect 를 EPERM 으로 막는다. 그래서
+    cmux pane 안에서 돌던 리드가 자기 샌드박스 안에서 `okstra render-bundle` 을
+    다시 실행하면 같은 cmux 가 그대로 떠 있는데도 탐지가 실패한다.
+
+    그래서 강등만 거부한다. 반대 방향(cli-wrapper → cmux-pane)은 화면에
+    드러나므로 막을 이유가 없다. 의도한 강등은 `--terminal-backend cli-wrapper`
+    로 선언한다 — 그때는 탐지도 하지 않는다.
+    """
+    requested = inp.terminal_backend.strip()
+    if requested:
+        return requested
+    detected = detect_terminal_backend()
+    if detected == BACKEND_CMUX_PANE:
+        return detected
+    if _prior_run_backend(project_root, inp) != BACKEND_CMUX_PANE:
+        return detected
+    observed, remedy = cmux.unreachable_advice(cmux.unreachable_reason())
+    raise PrepareError(" ".join(part for part in (
+        f"this task's previous {inp.task_type} run put its workers on cmux "
+        f"panes, and now {observed}.",
+        "Preparing now would move them to background cli-wrapper processes "
+        "with no surface to watch, so this run stops instead.",
+        remedy,
+        "To make the run wrapper-backed on purpose, pass "
+        "`--terminal-backend cli-wrapper`.",
+    ) if part))
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
@@ -4048,9 +4513,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         json.loads(runtime_resolution_json or "{}")
     except json.JSONDecodeError as exc:
         raise PrepareError(f"invalid runtime resolution data: {exc}") from exc
-    # Probed once here and reused below, so the gate and the manifest cannot
+    # Resolved once here and reused below, so the gate and the manifest cannot
     # disagree about which backend this run is on.
-    terminal_backend = detect_terminal_backend()
+    terminal_backend = _resolve_terminal_backend(project_root, inp)
     # Outside cmux only claude-code has a dispatch backend of its own. Under
     # cmux okstra owns the panes for every lead, so the render-only restriction
     # no longer applies to any runtime.
@@ -4105,20 +4570,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         terminal_backend=terminal_backend,
         requires_executor=requires_executor,
     )
-    if _uses_canonical_assignment_projection(inp):
-        workers, models = _project_assignment_plan(
-            inp,
-            assignment_plan,
-            assignment_context,
-        )
-        selected_reviewers = ",".join(workers)
-    else:
-        models = _resolve_model_bindings(
-            inp,
-            workers,
-            assignment_context,
-            requires_executor,
-        )
+    workers, models = _project_assignment_plan(
+        inp,
+        assignment_plan,
+        assignment_context,
+    )
+    selected_reviewers = ",".join(workers)
     execution_manifest = _build_static_execution_manifest(
         assignment_plan,
         assignment_context,
@@ -4135,8 +4592,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     _register_and_check_project(project_root, inp)
 
     # ---- paths under per-task mutex (writes run-context-*.json) ----
-    # OKSTRA_RUN_SEQ_OVERRIDE: okstra-ctl rerun / 테스트 hook 이 미리 reserve
-    # 한 seq 를 강제하는 user-knob 환경 변수.
+    # OKSTRA_RUN_SEQ_OVERRIDE: 테스트 hook 이 미리 reserve 한 seq 를 강제하는
+    # user-knob 환경 변수.
     raw_override = os.environ.get("OKSTRA_RUN_SEQ_OVERRIDE", "").strip()
     run_seq_override = int(raw_override) if raw_override else None
 
@@ -4235,7 +4692,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         # jsonl under ~/.claude/projects/<encoded-cwd>/. Leaving this blank
         # caused Phase 7 token-usage collection to fail (lead jsonl not
         # found) and the validator to report `sessionId=`.
-        claude_session_id = resolve_inproc_lead_session_id(project_root)
+        #
+        # 인코딩의 기준은 **부르는 세션의 cwd** 이지 대상 프로젝트 루트가 아니다.
+        # `--cwd` 로 다른 프로젝트를 몰 때 둘은 갈라지고, 프로젝트 루트로 인코딩한
+        # 디렉터리의 최신 파일은 이 런과 무관한 남의 세션이다.
+        claude_session_id = resolve_inproc_lead_session_id(Path.cwd())
     else:
         claude_session_id = generate_claude_session_id()
 
@@ -4430,9 +4891,37 @@ def _add_runtime_resolution_arguments(parser: ArgumentParser) -> None:
     )
 
 
+_CODEX_RUN_EPILOG = r"""The dry-run entry point for the Codex lead adapter. It runs with
+`--render-only --lead-runtime codex` fixed, materializes the normal okstra task
+bundle, and prints the rendered lead prompt without dispatching workers.
+
+Usage:
+  okstra codex-run --project-root <dir> --project-id <id> \
+    --task-group <tg> --task-id <tid> --task-type <type> \
+    --task-brief <path-or-rel> [--workers <list>] [--directive <text>] \
+    [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \
+    [--antigravity-model <m>] [--report-writer-model <m>] \
+    [--related-tasks <list>] [--base-ref <ref>] \
+    [--clarification-response <path>] [--work-category <cat>] \
+    [--selected-direction <selection-final-report.md>] \
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \
+    [--fix-cycle <yes|no>]
+
+  --render-only and --lead-runtime are owned by this command.
+  Worker dispatch is intentionally disabled here; use 'okstra codex-dispatch'
+  with the rendered run manifest for CLI-backed codex/antigravity workers.
+"""
+
+
 def build_prepare_argument_parser():
     """Build the shared flat-argument parser used by public prepare shims."""
-    p = ArgumentParser()
+    # 이 파서의 도움말이 사용자에게 닿는 경로는 `okstra codex-run --help` 뿐이다
+    # — render-bundle / run 은 Node 쪽 USAGE 를 찍고 --help 를 넘기지 않는다.
+    p = ArgumentParser(
+        prog="okstra codex-run",
+        epilog=_CODEX_RUN_EPILOG,
+        formatter_class=RawDescriptionHelpFormatter,
+    )
     p.add_argument("--workspace-root", required=True)
     p.add_argument("--project-root", required=True)
     p.add_argument("--project-id", required=True)
@@ -4550,6 +5039,17 @@ def build_prepare_argument_parser():
         ),
     )
     p.add_argument("--render-only", action="store_true", dest="render_only")
+    p.add_argument(
+        "--terminal-backend",
+        dest="terminal_backend",
+        choices=(BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE),
+        default="",
+        help=(
+            "워커가 뜰 표면을 명시한다. 미지정이면 탐지하되, 직전 run 이 "
+            "cmux-pane 이었는데 지금 cmux 에 못 붙는 경우 조용히 내려가지 "
+            "않고 멈춘다."
+        ),
+    )
     p.add_argument(
         "--no-plan-verification",
         action="store_false",
@@ -4740,6 +5240,7 @@ def main(argv: list[str]) -> int:
         reverify_scope=args.reverify_scope,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,
+        terminal_backend=args.terminal_backend,
         approve_plan_ack=args.approve_plan_ack,
         implementation_option=args.implementation_option,
         plan_verification_enabled=args.plan_verification_enabled,