okstra 0.160.0 → 0.162.0

package/runtime/python/okstra_ctl/team.py

@@ -1,4 +1,9 @@
-"""Neutral okstra team CLI for external tmux-pane worker dispatch."""
+"""Neutral okstra team CLI for pane-backed worker dispatch.
+
+Outside cmux this is the external lead's door onto tmux panes. Under cmux it
+is every lead's door onto cmux surfaces, because okstra owns the panes there
+rather than the host. Which backend a run uses is read from its run manifest.
+"""
 from __future__ import annotations
 
 import argparse
@@ -7,8 +12,10 @@ import sys
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from . import cmux
 from . import tmux
 from .dispatch_core import (
+    BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
     DispatchError,
     DispatchPlan,
@@ -51,7 +58,7 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def _add_dispatch_parser(sub) -> None:
-    parser = sub.add_parser("dispatch", help="dispatch tmux-pane workers")
+    parser = sub.add_parser("dispatch", help="dispatch pane-backed workers")
     _add_run_args(parser)
     parser.add_argument("--workers", default="")
     parser.add_argument("--jobs-file", default="")
@@ -61,7 +68,7 @@ def _add_dispatch_parser(sub) -> None:
 
 
 def _add_await_parser(sub) -> None:
-    parser = sub.add_parser("await", help="wait for tmux-pane workers")
+    parser = sub.add_parser("await", help="wait for pane-backed workers")
     _add_run_args(parser)
     parser.add_argument("--poll-interval-seconds", type=int, default=5)
     parser.add_argument("--timeout-seconds", type=int, default=None)
@@ -70,7 +77,7 @@ def _add_await_parser(sub) -> None:
 
 
 def _add_teardown_parser(sub) -> None:
-    parser = sub.add_parser("teardown", help="kill tmux-pane workers")
+    parser = sub.add_parser("teardown", help="reclaim this run's worker panes")
     _add_run_args(parser)
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("--json", action="store_true")
@@ -94,8 +101,8 @@ def _dispatch(args) -> int:
         okstra_bin=Path(args.okstra_bin),
         requested_workers=requested,
         idle_timeout_seconds=args.idle_timeout_seconds,
-        required_lead_runtime="external",
-        default_backend=BACKEND_TMUX_PANE,
+        required_lead_runtime=None if _is_cmux_run(manifest) else "external",
+        default_backend=_manifest_backend(manifest),
         supported_worker_wrappers=_SUPPORTED_WRAPPERS,
         unsupported_worker_label="external lead",
         dispatch_kind=args.dispatch_kind,
@@ -133,13 +140,13 @@ def _teardown(args) -> int:
     team_state_path = _resolve_project_path(project_root, _require_string(manifest, "teamStatePath"))
     team_state = _load_json(team_state_path, "team-state")
     run_dir = _resolve_project_path(project_root, _require_string(manifest, "runDirectoryPath"))
-    lead_pane = tmux.resolve_caller_pane()
-    panes = _teardown_panes(team_state, run_dir, lead_pane)
+    panes = _reclaimable_panes(manifest, team_state, run_dir)
     if args.dry_run:
         _emit_teardown(args.json, panes)
         return 0
+    reclaim = cmux.close_surface if _is_cmux_run(manifest) else tmux.kill_pane
     for pane in panes:
-        tmux.kill_pane(pane["paneId"])
+        reclaim(pane["paneId"])
     _mark_teardown_errors(team_state_path)
     _emit_teardown(args.json, panes)
     return 0
@@ -158,7 +165,7 @@ def _plan_for_existing(
         lead_events_path=_resolve_project_path(root, _require_string(manifest, "leadEventsPath")),
         manifest=manifest,
         jobs=(),
-        default_backend=BACKEND_TMUX_PANE,
+        default_backend=_manifest_backend(manifest),
     )
 
 
@@ -174,12 +181,25 @@ def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
     }
 
 
-def _teardown_panes(team_state: Mapping[str, Any], run_dir: Path, lead_pane: str) -> list[dict[str, str]]:
+def _reclaimable_panes(
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any], run_dir: Path
+) -> list[dict[str, str]]:
+    """Everything this run owns and may close.
+
+    Under cmux the recorded ids are the whole list. There is no per-pane tag API
+    to sweep with, and scanning by title would be worse than nothing: cmux labels
+    its own agent surfaces with the same glyph okstra's tmux cleanup treats as a
+    teammate marker, so a sweep could close the lead. Only surfaces okstra
+    created are recorded, so only those can be closed.
+    """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
     for record in team_state.get("workerDispatches", []):
         if isinstance(record, dict):
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
+    if _is_cmux_run(manifest):
+        return panes
+    lead_pane = tmux.resolve_caller_pane()
     for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
         _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
@@ -208,10 +228,29 @@ def _emit_teardown(as_json: bool, panes: list[dict[str, str]]) -> None:
         print(f"{pane['paneId']}\t{pane['kind']}")
 
 
+def _manifest_backend(manifest: Mapping[str, Any]) -> str:
+    """The backend prepare recorded for this run.
+
+    Deliberately not a flag on this command: the manifest already answers it,
+    and a flag would be a second answer free to disagree. A manifest written
+    before the field existed reads as tmux, which is what those runs used.
+    """
+    return str(manifest.get("terminalBackend") or "") or BACKEND_TMUX_PANE
+
+
+def _is_cmux_run(manifest: Mapping[str, Any]) -> bool:
+    return _manifest_backend(manifest) == BACKEND_CMUX_PANE
+
+
 def _validate_external_manifest(manifest: Mapping[str, Any]) -> None:
     runtime = manifest.get("leadRuntime")
     if runtime == "external":
         return
+    if _is_cmux_run(manifest):
+        # Under cmux okstra owns the panes for every lead, so this command is no
+        # longer the external lead's private door and the advice below no longer
+        # applies — there is nowhere else for a codex or Claude Code lead to go.
+        return
     if runtime == "codex":
         raise DispatchError("use okstra codex-dispatch for leadRuntime=codex")
     if runtime == "claude-code":

package/runtime/python/okstra_ctl/wizard.py

@@ -56,7 +56,10 @@ from okstra_ctl.clarification_items import (
     sidecar_answers,
     user_response_sidecars,
 )
-from okstra_ctl.incremental_scope import preview_link_availability_for_report
+from okstra_ctl.incremental_scope import (
+    parse_stage_graph,
+    preview_link_availability_for_report,
+)
 from okstra_ctl.design_prep import (
     DesignPrepError,
     load_design_prep_items,
@@ -342,6 +345,8 @@ S_RELATED_TASKS_PICK = "related_tasks_pick"
 S_RELATED_TASKS = "related_tasks"
 S_CLARIFICATION_PICK = "clarification_pick"
 S_CLARIFICATION = "clarification"
+S_REVERIFY_SCOPE_PICK = "reverify_scope_pick"
+S_REVERIFY_SCOPE_STAGES = "reverify_scope_stages"
 S_PR_TEMPLATE_PICK = "pr_template_pick"
 S_PR_TEMPLATE = "pr_template"
 S_PR_TEMPLATE_SCOPE = "pr_template_scope"
@@ -473,6 +478,10 @@ class WizardState:
     clarification_response_path: str = ""
     clarification_pending_text: bool = False
     last_final_report_cached: str = ""
+    # "" | "auto" | "full" | "<stage csv>" — 사용자가 고른 이번 재실행의 재검증
+    # 범위. implementation-planning 재실행에서 좁힐 여지가 있을 때만 채워진다.
+    reverify_scope: str = ""
+    reverify_scope_pending_text: bool = False
     pr_template_path: str = ""
     pr_template_pending_text: bool = False
     pr_template_scope: str = ""  # "once" | "project" | "global"
@@ -3002,6 +3011,128 @@ def _submit_clarification_pick(state: WizardState, value: str) -> Optional[str]:
     return _submit_optional_cached_pick(state, value, _CLARIFICATION_PICK_SPEC)
 
 
+def _carried_planning_report(state: WizardState) -> Optional[Path]:
+    """이번 재실행이 이어받는 직전 implementation-planning 리포트 (없으면 None)."""
+    if state.task_type != "implementation-planning":
+        return None
+    if not state.clarification_response_path or not state.project_root:
+        return None
+    report = _resolve_path(
+        state.clarification_response_path, Path(state.project_root)
+    )
+    return report if report.is_file() else None
+
+
+def _reverify_scope_preview(state: WizardState) -> Optional[dict]:
+    """답변된 id 가 직전 리포트의 stage 로 되짚어지는지 — 범위 판정의 앞 절반."""
+    report = _carried_planning_report(state)
+    if report is None:
+        return None
+    return preview_link_availability_for_report(
+        report, set(sidecar_answers(report))
+    )
+
+
+def _reverify_scope_pick_required(state: WizardState) -> bool:
+    """좁힐 여지가 있는 재실행에서만 범위를 묻는다.
+
+    링크가 끊겨 full 이 이미 확정된 재실행에서 물으면 어떤 답도 판정을 바꾸지
+    못한다 — 고를 수 없는 선택지를 내미는 화면이 하나 느는 것뿐이다. 그 경우
+    확인 블록의 `reverify-scope: full 예상` 줄이 이유까지 같이 알려준다.
+    """
+    preview = _reverify_scope_preview(state)
+    return preview is not None and not preview["wouldForceFull"]
+
+
+def _reverify_scope_step_pending(state: WizardState) -> bool:
+    """범위 질문이 아직 안 끝났는가 — confirm 진입을 막는 게이트."""
+    if state.reverify_scope_pending_text:
+        return True
+    return _reverify_scope_pick_required(state) and not state.reverify_scope
+
+
+def _prior_stage_numbers(state: WizardState) -> set[int]:
+    """직전 리포트 Stage Map 의 stage 번호. 읽을 수 없으면 WizardError."""
+    t = _p(state.workspace_root, "reverify_scope_stages")
+    report = _carried_planning_report(state)
+    if report is None:
+        raise WizardError(
+            t["errors"]["no_stage_map"].format(reason="carried report not found")
+        )
+    data_path = final_report_data_path(report)
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+        stages = {num for num, _ in parse_stage_graph(data)}
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        raise WizardError(
+            t["errors"]["no_stage_map"].format(reason=str(exc))
+        ) from exc
+    if not stages:
+        raise WizardError(
+            t["errors"]["no_stage_map"].format(reason="stage map is empty")
+        )
+    return stages
+
+
+def _build_reverify_scope_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "reverify_scope_pick")
+    opts = t["options"]
+    return Prompt(
+        step=S_REVERIFY_SCOPE_PICK, kind="pick", label=t["label"],
+        options=[
+            _opt("auto", opts["auto"]),
+            _opt("full", opts["full"]),
+            _opt(PICK_TYPE_CUSTOM, opts[PICK_TYPE_CUSTOM]),
+        ],
+        echo_template=t["echo_template"])
+
+
+def _submit_reverify_scope_pick(state: WizardState, value: str) -> Optional[str]:
+    t = _p(state.workspace_root, "reverify_scope_pick")
+    picked = value.strip().lower()
+    if picked == PICK_TYPE_CUSTOM:
+        state.reverify_scope = ""
+        state.reverify_scope_pending_text = True
+        return "reverify-scope: 직접 입력"
+    if picked not in ("auto", "full"):
+        raise WizardError(
+            f"expected 'auto' / 'full' / {PICK_TYPE_CUSTOM!r}, got: {value!r}"
+        )
+    state.reverify_scope = picked
+    state.reverify_scope_pending_text = False
+    return t["echo_suffixes"][picked]
+
+
+def _build_reverify_scope_stages(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "reverify_scope_stages")
+    return Prompt(
+        step=S_REVERIFY_SCOPE_STAGES, kind="text", label=t["label"],
+        echo_template=t["echo_template"])
+
+
+def _submit_reverify_scope_stages(state: WizardState, value: str) -> Optional[str]:
+    t = _p(state.workspace_root, "reverify_scope_stages")
+    tokens = [token.strip() for token in value.split(",") if token.strip()]
+    if not tokens:
+        state.reverify_scope = "auto"
+        state.reverify_scope_pending_text = False
+        return t["echo_suffixes"]["auto"]
+    for token in tokens:
+        if not token.isdigit():
+            raise WizardError(t["errors"]["not_a_number"].format(token=token))
+    known = _prior_stage_numbers(state)
+    picked = sorted({int(token) for token in tokens})
+    unknown = [num for num in picked if num not in known]
+    if unknown:
+        raise WizardError(t["errors"]["unknown_stage"].format(
+            stages=", ".join(str(num) for num in unknown),
+            known=", ".join(str(num) for num in sorted(known)),
+        ))
+    state.reverify_scope = ",".join(str(num) for num in picked)
+    state.reverify_scope_pending_text = False
+    return t["echo_template"].format(value=state.reverify_scope)
+
+
 def _suggest_project_pr_template(state: WizardState) -> str:
     """project.json 의 prTemplatePath 필드를 읽어 경로 문자열로 반환.
 
@@ -4232,14 +4363,32 @@ STEPS: list[Step] = [
                             and S_PR_TEMPLATE_SCOPE not in s.answered),
          build=_build_pr_template_scope, submit=_submit_pr_template_scope,
          owns=("pr_template_scope",)),
+    # 재검증 범위는 clarification-response 가 정해진 뒤에야 판정할 수 있고,
+    # 확인 블록은 full 재검증 비용을 물기 전 마지막 되돌림 지점이다. 그래서
+    # 이 질문은 confirm 바로 앞에 선다.
+    Step(S_REVERIFY_SCOPE_PICK,
+         applies=lambda s: (_ready_for_confirm(s)
+                            and not s.reverify_scope_pending_text
+                            and not s.reverify_scope
+                            and _reverify_scope_pick_required(s)),
+         build=_build_reverify_scope_pick, submit=_submit_reverify_scope_pick,
+         owns=("reverify_scope", "reverify_scope_pending_text")),
+    Step(S_REVERIFY_SCOPE_STAGES,
+         applies=lambda s: (s.reverify_scope_pending_text
+                            and S_REVERIFY_SCOPE_STAGES not in s.answered),
+         build=_build_reverify_scope_stages,
+         submit=_submit_reverify_scope_stages,
+         owns=("reverify_scope", "reverify_scope_pending_text")),
     Step(S_FIX_CYCLE_CONFIRM,
          applies=lambda s: (_ready_for_confirm(s)
+                            and not _reverify_scope_step_pending(s)
                             and _fix_cycle_confirm_required(s)
                             and not s.fix_cycle),
          build=_build_fix_cycle_confirm, submit=_submit_fix_cycle_confirm,
          owns=("fix_cycle",)),
     Step(S_CONFIRM,
          applies=lambda s: (_ready_for_confirm(s)
+                            and not _reverify_scope_step_pending(s)
                             and (not _fix_cycle_confirm_required(s)
                                  or bool(s.fix_cycle))
                             and s.confirmed is None),
@@ -4357,6 +4506,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "directive_pending_text": False,
     "related_tasks_raw": "", "related_tasks_pending_text": False,
     "clarification_response_path": "", "clarification_pending_text": False,
+    "reverify_scope": "", "reverify_scope_pending_text": False,
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
     "fix_cycle": "",
@@ -4650,31 +4800,34 @@ def render_args(state: WizardState) -> dict[str, str]:
         "report-writer-model": state.report_writer_model,
         "related-tasks": state.related_tasks_raw,
         "clarification-response": state.clarification_response_path,
+        "reverify-scope": (
+            state.reverify_scope
+            if state.task_type == "implementation-planning" else ""
+        ),
         "pr-template-path": pr_template,
         "fix-cycle": state.fix_cycle,
     }
 
 
 def _reverify_scope_line(state: WizardState) -> Optional[str]:
-    """이번 clarification 재실행이 좁혀질지 — 확인 단계에서 미리 보여주는 줄.
-
-    이 판정의 절반(답변된 id 가 stage 로 되짚어지는지)은 base SHA 없이 결정되고
-    직전 리포트만 있으면 이미 정해져 있다. 그런데 지금까지는 `okstra recap
-    assemble` 을 따로 돌려야만 보였고, run 이 시작된 뒤에 full 로 밝혀지면 두
-    시간을 물린 뒤였다. 확인 단계는 그 전에 되돌릴 수 있는 마지막 지점이다.
+    """이번 clarification 재실행이 좁혀질지 — 확인 단계에서 보여주는 줄.
+
+    사용자가 범위를 직접 골랐으면 그 선택을 찍는다. 고르지 않았으면(또는 좁힐
+    수 없어 질문 자체가 안 뜬 경우) 예측을 찍는다. 예측의 절반(답변된 id 가
+    stage 로 되짚어지는지)은 base SHA 없이 직전 리포트만으로 이미 정해져 있는데,
+    지금까지는 `okstra recap assemble` 을 따로 돌려야만 보였고 run 이 시작된 뒤
+    full 로 밝혀지면 두 시간을 물린 뒤였다. 확인 단계는 그 전에 되돌릴 수 있는
+    마지막 지점이다.
     """
-    if state.task_type != "implementation-planning":
-        return None
-    if not state.clarification_response_path or not state.project_root:
+    preview = _reverify_scope_preview(state)
+    if preview is None:
         return None
-    report = _resolve_path(
-        state.clarification_response_path, Path(state.project_root)
-    )
-    if not report.is_file():
-        return None
-    preview = preview_link_availability_for_report(
-        report, set(sidecar_answers(report))
-    )
+    if state.reverify_scope == "full":
+        return _msg(state.workspace_root, "confirmation",
+                    "reverify_scope_user_full")
+    if state.reverify_scope and state.reverify_scope != "auto":
+        return _msg(state.workspace_root, "confirmation",
+                    "reverify_scope_user_stages", stages=state.reverify_scope)
     if not preview["wouldForceFull"]:
         return _msg(state.workspace_root, "confirmation",
                     "reverify_scope_incremental")

package/runtime/skills/okstra-run/SKILL.md

@@ -142,6 +142,7 @@ That is the entire interactive flow. The wizard handles:
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills workers·model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
+- **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm`, and **only when the re-run is narrowable** (every answered `C-NNN` traces back to a stage in the prior report). 3 options: `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. When the re-run is not narrowable the step does not appear — full is already fixed, and the confirmation block's `reverify-scope` line says which answered id broke the link,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
 

package/runtime/validators/validate-workflow.sh

@@ -39,6 +39,12 @@ SECONDARY_BRIEF_FILENAME="validation-brief-secondary.md"
 export OKSTRA_SKIP_INSTALL_CHECK="${OKSTRA_SKIP_INSTALL_CHECK:-1}"
 export OKSTRA_CTL_SKIP_RECONCILE="${OKSTRA_CTL_SKIP_RECONCILE:-1}"
 export OKSTRA_CTL_SKIP_BACKFILL="${OKSTRA_CTL_SKIP_BACKFILL:-1}"
+# Same reason as the three above: the synthetic run must render the same way on
+# every machine. cmux outranks tmux when present, so a maintainer running this
+# from inside cmux would otherwise get the cmux adapter and a lead-session
+# requirement this fixture never simulates. The cmux path has its own coverage
+# in tests/run/test_cmux*.py and tests/contract/test_validate_session_conformance.py.
+export CMUX_WORKSPACE_ID=""
 
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"

package/runtime/validators/validate_session_conformance.py

@@ -112,9 +112,19 @@ _ENTRY_GUARD_READS = (
     ),
 )
 
+# 환경으로 선택되는 어댑터라 lead 의 런타임이 이 파일을 가르쳐 주지 않는다.
+# 읽지 않은 lead 는 자기 런타임이 아는 방식 — cmux 경로에서는 okstra 가 소유한
+# 디스패치를 host 네이티브로 가로채는 방식 — 으로 되돌아간다.
+CMUX_ADAPTER_BASENAME = "cmux.md"
+CMUX_ADAPTER_NAME = "cmux"
+_CMUX_ADAPTER_CITE = "prompts/lead/adapters/cmux.md"
+
 # Read 증거는 basename 으로 거른다 — 절대 경로는 레이어(repo / runtime / 설치본)
 # 마다 다르지만 basename 은 동일하다. 목록이 갈리지 않도록 기대치에서 파생한다.
-_ENTRY_GUARD_BASENAMES = tuple(row.basename for row in _ENTRY_GUARD_READS)
+_TRACKED_READ_BASENAMES = (
+    *(row.basename for row in _ENTRY_GUARD_READS),
+    CMUX_ADAPTER_BASENAME,
+)
 
 
 @dataclass
@@ -208,7 +218,7 @@ def _scan_one_jsonl(
                         progress.append((ts, m.group("phase"), line))
                 elif block.get("type") == "tool_use" and block.get("name") == "Read":
                     base = Path(str((block.get("input") or {}).get("file_path") or "")).name
-                    if base in _ENTRY_GUARD_BASENAMES:
+                    if base in _TRACKED_READ_BASENAMES:
                         reads.setdefault(base, []).append(ts)
     return progress, reads, agent_name
 
@@ -334,7 +344,7 @@ def _sidecar_read_from_event(event) -> tuple[str, str] | None:
     if not isinstance(basename, str) or not basename:
         raw_path = details.get("path") or details.get("filePath")
         basename = Path(str(raw_path or "")).name
-    if basename not in _ENTRY_GUARD_BASENAMES:
+    if basename not in _TRACKED_READ_BASENAMES:
         return None
     return (basename, event.timestamp)
 
@@ -752,6 +762,29 @@ def _instruction_set_dir(run_dir: Path, suffix: str | None, project_root: Path)
     return path if path.is_dir() else None
 
 
+def _check_cmux_adapter_read(
+    evidence: _LeadEvidence, team_state: dict, errors: list[str]
+) -> None:
+    """검사 4 — cmux 어댑터 읽음. 모든 task-type 에 적용된다.
+
+    다른 어댑터는 lead 의 런타임이 고르지만 이것은 환경이 고른다. 그래서 읽지
+    않은 lead 에게는 이 경로가 존재한다는 사실 자체가 닿지 않고, 자기 런타임이
+    아는 host 네이티브 디스패치로 되돌아간다 — cmux 경로에서 okstra 가 소유한
+    바로 그 일이다."""
+    adapter = team_state.get("leadAdapter")
+    name = str(adapter.get("name", "")).strip() if isinstance(adapter, dict) else ""
+    if name != CMUX_ADAPTER_NAME:
+        return
+    if evidence.sidecar_reads.get(CMUX_ADAPTER_BASENAME):
+        return
+    errors.append(
+        f"cmux adapter: no `Read` of `{CMUX_ADAPTER_BASENAME}` found in the "
+        "selected adapter evidence source within this run's window — the cmux "
+        "adapter is selected by environment, not by lead runtime, so it MUST be "
+        f"read before dispatch ({_CMUX_ADAPTER_CITE})."
+    )
+
+
 def _check_implementation_entry_guard(
     evidence: _LeadEvidence, errors: list[str], instruction_set: Path | None
 ) -> None:
@@ -837,6 +870,7 @@ def validate_session_conformance(
         result.errors.append(error)
         return result
     _check_progress_checkpoints(evidence, team_state, run_dir, suffix, result.errors)
+    _check_cmux_adapter_read(evidence, team_state, result.errors)
     if task_type == "implementation":
         _check_implementation_entry_guard(
             evidence,