okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/wizard.py

@@ -20,6 +20,7 @@ imports this module directly.
 from __future__ import annotations
 
 import copy
+import hashlib
 import json
 import math
 import re
@@ -31,7 +32,16 @@ from typing import Any, Callable, Optional
 
 from okstra_ctl.application.advance_wizard import plan_prompt
 from okstra_ctl.application.resolve_assignment import resolve_lead_provider
+from okstra_ctl.assignment_environment import load_assignment_context
+from okstra_ctl.assignment_resolver import (
+    AssignmentContext,
+    AssignmentResolutionError,
+    RoleInstance,
+    resolve_assignments,
+    resolve_model_assignment,
+)
 from okstra_ctl.domain.host import (
+    CurrentSessionModelAttestation,
     HostCapabilityMismatch,
     HostNotRegistered,
     HostSessionContext,
@@ -44,8 +54,19 @@ from okstra_ctl.domain.wizard.interaction import (
     WizardPrompt,
     normalize_planned_answer,
 )
+from okstra_ctl.dispatch_state import detect_terminal_backend
 from okstra_ctl.registry.host_registry import default_host_registry
 from okstra_ctl.registry.provider_registry import default_provider_registry
+from okstra_ctl.model_defaults import ModelDefaultScopes, default_candidates
+from okstra_ctl.model_pool import ModelPool
+from okstra_ctl import next_phase
+from okstra_ctl.legacy_model_selection import serialize_host_session_context
+from okstra_ctl.role_requirements import (
+    RoleProfile,
+    RoleProfileError,
+    RoleRequirement,
+    load_role_profile,
+)
 from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.brief_frontmatter import read_brief_frontmatter
 from okstra_ctl.analysis_inputs import (
@@ -72,6 +93,7 @@ from okstra_ctl.clarification_items import (
     sidecar_answers,
     user_response_sidecars,
 )
+from okstra_ctl.convergence_store import write_json_atomic
 from okstra_ctl.incremental_scope import (
     parse_stage_graph,
     preview_link_availability_for_report,
@@ -96,8 +118,10 @@ from okstra_ctl.run import (
     _apply_cli_implementation_option,
     _extract_frontmatter_block,
     _load_final_report_data_if_present,
+    _assignment_resolution_message,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
+    _model_default_scopes,
     recommended_role_models,
 )
 from okstra_ctl.stage_map import (
@@ -406,6 +430,12 @@ _STEP_TO_GROUP: dict[str, str] = {
 
 @dataclass
 class WizardState:
+    # execution identity v2: role-first canonical model selections
+    execution_identity_version: int = 1
+    role_counts: dict[str, int] = field(default_factory=dict)
+    role_models: dict[str, list[str]] = field(default_factory=dict)
+    role_selection_order: list[str] = field(default_factory=list)
+
     # bootstrap
     workspace_root: str = ""
     project_root: str = ""
@@ -524,11 +554,19 @@ class WizardState:
     answered: list[str] = field(default_factory=list)
 
     def to_json(self) -> dict[str, Any]:
-        return asdict(self)
+        payload = asdict(self)
+        payload.pop("execution_identity_version")
+        payload["executionIdentityVersion"] = 2
+        payload["roleCounts"] = payload.pop("role_counts")
+        payload["roleModels"] = payload.pop("role_models")
+        payload["roleSelectionOrder"] = payload.pop("role_selection_order")
+        for field_name in _V1_PROVIDER_STATE_FIELDS:
+            payload.pop(field_name, None)
+        return payload
 
     @classmethod
     def from_json(cls, d: dict[str, Any]) -> "WizardState":
-        return cls(**d)
+        return _wizard_state_from_json(d)
 
 
 @dataclass
@@ -550,8 +588,14 @@ class Prompt:
     # only meaningful when kind == "pick_group": one entry per AskUserQuestion tab
     questions: list["Prompt"] = field(default_factory=list)
 
+    @property
+    def id(self) -> str:
+        """Stable public identifier shared by static and role-instance prompts."""
+        return self.step
+
     def to_json(self) -> dict[str, Any]:
         out = {
+            "id": self.step,
             "step": self.step,
             "kind": self.kind,
             "label": self.label,
@@ -959,6 +1003,981 @@ def _profile_path(workspace_root: Path, task_type: str) -> Path:
     return workspace_root / "prompts" / "profiles" / f"{task_type}.md"
 
 
+_V2_STATE_FIELDS = (
+    "roleCounts",
+    "roleModels",
+    "roleSelectionOrder",
+)
+_V1_PROVIDER_STATE_FIELDS = (
+    "workers_override",
+    "lead_provider",
+    "lead_model",
+    "claude_model",
+    "codex_model",
+    "antigravity_model",
+    "grok_model",
+    "kimi_model",
+    "report_writer_provider",
+    "report_writer_model",
+    "executor",
+    "critic",
+)
+_V1_PROVIDER_STATE_JSON_FIELDS = frozenset({
+    *_V1_PROVIDER_STATE_FIELDS,
+    "workers",
+    "leadProvider",
+    "leadModel",
+    "claudeModel",
+    "codexModel",
+    "antigravityModel",
+    "grokModel",
+    "kimiModel",
+    "reportWriterProvider",
+    "reportWriterModel",
+})
+
+
+def _load_role_profile_for_state(state: WizardState) -> RoleProfile:
+    try:
+        return load_role_profile(
+            _profile_path(Path(state.workspace_root), state.task_type)
+        )
+    except RoleProfileError as exc:
+        raise WizardError(str(exc)) from exc
+
+
+def _role_selection_enabled(state: WizardState) -> bool:
+    if (
+        state.execution_identity_version != 2
+        or not state.workspace_root
+        or not state.task_type
+    ):
+        return False
+    try:
+        load_role_profile(_profile_path(Path(state.workspace_root), state.task_type))
+    except (OSError, RoleProfileError):
+        return False
+    return True
+
+
+def _legacy_value(payload: dict[str, Any], snake: str, camel: str) -> Any:
+    return payload.get(snake, payload.get(camel, ""))
+
+
+def _legacy_model_ref(
+    pool: ModelPool,
+    provider: str,
+    role: str,
+    raw_model: Any,
+) -> str | None:
+    provider_id = provider.strip().lower()
+    if not provider_id:
+        return None
+    model_value = raw_model.strip() if isinstance(raw_model, str) else ""
+    try:
+        model = (
+            pool.resolve_alias(provider_id, model_value)
+            if model_value
+            else pool.default_candidate(provider_id, role)
+        )
+    except (ValueError, RuntimeError):
+        return None
+    if model is None:
+        return None
+    availability = pool.availability(str(model.model_ref), role)
+    return str(model.model_ref) if availability.available else None
+
+
+def _legacy_worker_providers(payload: dict[str, Any]) -> list[str]:
+    raw = _legacy_value(payload, "workers_override", "workers")
+    if isinstance(raw, list):
+        values = raw
+    elif isinstance(raw, str):
+        values = raw.split(",")
+    else:
+        values = []
+    return [
+        value.strip().lower()
+        for value in values
+        if isinstance(value, str)
+        and value.strip()
+        and value.strip().lower() != "report-writer"
+    ]
+
+
+def _initial_cross_verification_requirement(
+    profile: RoleProfile,
+) -> RoleRequirement | None:
+    return next((
+        requirement
+        for requirement in profile.roles
+        if not requirement.dynamic
+        and requirement.role in {
+            "analyser",
+            "designer",
+            "planner",
+            "verifier",
+        }
+    ), None)
+
+
+def _convert_v1_provider_selections(
+    state: WizardState,
+    payload: dict[str, Any],
+) -> None:
+    if not _role_selection_enabled(state):
+        return
+    profile = _load_role_profile_for_state(state)
+    pool = ModelPool.from_registry(default_provider_registry())
+    cross_requirement = _initial_cross_verification_requirement(profile)
+    providers = _legacy_worker_providers(payload)
+    if cross_requirement is not None:
+        selected_count = cross_requirement.recommended_count
+        if providers and cross_requirement.min_count < cross_requirement.max_count:
+            selected_count = min(
+                cross_requirement.max_count,
+                max(cross_requirement.min_count, len(providers)),
+            )
+        if cross_requirement.min_count < cross_requirement.max_count:
+            state.role_counts[cross_requirement.role] = selected_count
+            count_id = f"role-count:{cross_requirement.role}"
+            state.role_selection_order.append(count_id)
+        if not providers:
+            providers = [
+                model.provider_id
+                for model in pool.default_candidates(cross_requirement.role)
+            ]
+        for ordinal, provider in enumerate(providers[:selected_count], start=1):
+            raw_model = _legacy_value(
+                payload,
+                f"{provider}_model",
+                f"{provider}Model",
+            )
+            model_ref = _legacy_model_ref(
+                pool,
+                provider,
+                cross_requirement.role,
+                raw_model,
+            )
+            if model_ref is None:
+                break
+            state.role_models.setdefault(cross_requirement.role, []).append(model_ref)
+            state.role_selection_order.append(
+                f"role-model:{cross_requirement.role}:{ordinal}"
+            )
+
+    provider_rows = (
+        (
+            "leader",
+            _legacy_value(payload, "lead_provider", "leadProvider") or "claude",
+            _legacy_value(payload, "lead_model", "leadModel"),
+        ),
+        (
+            "report-writer",
+            _legacy_value(
+                payload,
+                "report_writer_provider",
+                "reportWriterProvider",
+            ) or "claude",
+            _legacy_value(
+                payload,
+                "report_writer_model",
+                "reportWriterModel",
+            ),
+        ),
+        (
+            "implementer",
+            _legacy_value(payload, "executor", "executor") or "claude",
+            _legacy_value(
+                payload,
+                f"{_legacy_value(payload, 'executor', 'executor') or 'claude'}_model",
+                f"{_legacy_value(payload, 'executor', 'executor') or 'claude'}Model",
+            ),
+        ),
+        (
+            "critic",
+            _legacy_value(payload, "critic", "critic"),
+            _legacy_value(
+                payload,
+                f"{_legacy_value(payload, 'critic', 'critic')}_model",
+                f"{_legacy_value(payload, 'critic', 'critic')}Model",
+            ),
+        ),
+    )
+    static_roles = {
+        requirement.role
+        for requirement in profile.roles
+        if not requirement.dynamic and requirement.min_count > 0
+    }
+    if state.host_entry_mode == "spawn-process":
+        static_roles.add("leader")
+    for role, provider, raw_model in provider_rows:
+        if role not in static_roles or not isinstance(provider, str) or not provider:
+            continue
+        model_ref = _legacy_model_ref(pool, provider, role, raw_model)
+        if model_ref is None:
+            continue
+        state.role_models[role] = [model_ref]
+        state.role_selection_order.append(f"role-model:{role}:1")
+
+
+def _wizard_state_from_json(payload: dict[str, Any]) -> WizardState:
+    if not isinstance(payload, dict):
+        raise WizardError("wizard state must be a JSON object")
+    data = dict(payload)
+    version = data.pop("executionIdentityVersion", None)
+    has_v2_fields = any(field_name in data for field_name in _V2_STATE_FIELDS)
+    has_v1_fields = any(
+        field_name in data for field_name in _V1_PROVIDER_STATE_JSON_FIELDS
+    )
+    if version == 2:
+        if has_v1_fields or not all(field_name in data for field_name in _V2_STATE_FIELDS):
+            raise WizardError("mixed wizard state versions are not allowed")
+        data["role_counts"] = data.pop("roleCounts")
+        data["role_models"] = data.pop("roleModels")
+        data["role_selection_order"] = data.pop("roleSelectionOrder")
+        data["execution_identity_version"] = 2
+        _validate_v2_state_fields(data)
+    elif version in (None, 1):
+        if has_v2_fields:
+            raise WizardError("mixed wizard state versions are not allowed")
+        data.pop("execution_identity_version", None)
+    else:
+        raise WizardError(f"unsupported wizard state version: {version!r}")
+    allowed = WizardState.__dataclass_fields__.keys()
+    state = WizardState(**{key: value for key, value in data.items() if key in allowed})
+    if version != 2:
+        state.execution_identity_version = 2
+        _convert_v1_provider_selections(state, payload)
+        # v1 은 리더 확인 칸이 없었다. 변환 재개 시 다시 묻지 않는다.
+        if (
+            state.host_entry_mode == "current-session"
+            and _LEADER_SESSION_STEP not in state.answered
+        ):
+            state.answered.append(_LEADER_SESSION_STEP)
+        if (
+            state.host_entry_mode == "current-session"
+            and _LEADER_SESSION_STEP not in state.role_selection_order
+        ):
+            state.role_selection_order.insert(0, _LEADER_SESSION_STEP)
+    return state
+
+
+def _validate_v2_state_fields(data: dict[str, Any]) -> None:
+    role_counts = data.get("role_counts")
+    role_models = data.get("role_models")
+    selection_order = data.get("role_selection_order")
+    if not isinstance(role_counts, dict) or not all(
+        isinstance(role, str)
+        and isinstance(count, int)
+        and not isinstance(count, bool)
+        for role, count in role_counts.items()
+    ):
+        raise WizardError("wizard state roleCounts must map roles to integers")
+    if not isinstance(role_models, dict) or not all(
+        isinstance(role, str)
+        and isinstance(models, list)
+        and all(isinstance(model_ref, str) for model_ref in models)
+        for role, models in role_models.items()
+    ):
+        raise WizardError("wizard state roleModels must map roles to modelRef arrays")
+    if not isinstance(selection_order, list) or not all(
+        isinstance(step_id, str) for step_id in selection_order
+    ):
+        raise WizardError("wizard state roleSelectionOrder must be a string array")
+
+
+def _role_count_prompt_id(role: str) -> str:
+    return f"role-count:{role}"
+
+
+def _role_add_prompt_id(role: str) -> str:
+    return f"role-add:{role}"
+
+
+def _role_model_prompt_id(role: str, ordinal: int) -> str:
+    return f"role-model:{role}:{ordinal}"
+
+
+_LEADER_SESSION_STEP = "leader-session"
+
+
+def _is_role_selection_step(step_id: str) -> bool:
+    return step_id == _LEADER_SESSION_STEP or step_id.startswith(
+        ("role-count:", "role-model:", "role-add:")
+    )
+
+
+def _selected_role_count(
+    state: WizardState,
+    requirement: RoleRequirement,
+) -> int:
+    if requirement.min_count == requirement.max_count:
+        return requirement.min_count
+    if requirement.role in state.role_counts:
+        return state.role_counts[requirement.role]
+    # min=0 선택 역할(예: critic)은 사용자가 열기 전까지 기본 0
+    if requirement.min_count == 0:
+        return 0
+    return requirement.recommended_count
+
+
+def _selectable_static_requirements(
+    state: WizardState,
+    profile: RoleProfile,
+) -> tuple[RoleRequirement, ...]:
+    requirements: list[RoleRequirement] = []
+    if state.host_entry_mode == "spawn-process":
+        requirements.append(RoleRequirement("leader", 1, 1, 1, "lead"))
+    requirements.extend(
+        requirement
+        for requirement in profile.roles
+        if not requirement.dynamic
+        and _selected_role_count(state, requirement) > 0
+    )
+    return tuple(requirements)
+
+
+def _leader_session_prompt(state: WizardState) -> Prompt:
+    """current-session 리더 칸: 모델/effort 표시만 하고 role_models 에 쓰지 않는다."""
+    attestation = _host_session_context(state).current_model
+    model_ref = (
+        attestation.normalized_model_ref
+        or attestation.observed_model
+        or "current-session"
+    )
+    steps = _load_wizard_root(state.workspace_root)["steps"]
+    raw = steps.get("leader_session") or {}
+    effort_suffix = ""
+    if attestation.effort:
+        effort_template = raw.get("effort_suffix", " · effort {effort}")
+        effort_suffix = effort_template.format(effort=attestation.effort)
+    prompt = _p(
+        state.workspace_root,
+        "leader_session",
+        model_ref=model_ref,
+        effort_suffix=effort_suffix,
+    )
+    continue_label = prompt["options"].get("continue", "계속")
+    return Prompt(
+        step=_LEADER_SESSION_STEP,
+        kind="pick",
+        label=prompt["label"],
+        options=[_opt("continue", continue_label)],
+        echo_template=prompt["echo_template"],
+    )
+
+
+def _count_prompt(
+    state: WizardState,
+    requirement: RoleRequirement,
+) -> Prompt:
+    prompt = _p(
+        state.workspace_root,
+        "role_count",
+        role=requirement.role,
+        minimum=str(requirement.min_count),
+        maximum=str(requirement.max_count),
+        default=str(requirement.recommended_count),
+    )
+    return Prompt(
+        step=_role_count_prompt_id(requirement.role),
+        kind="pick",
+        label=prompt["label"],
+        options=[
+            _opt(
+                str(count),
+                prompt["options"]["count"].format(
+                    count=count,
+                    default_suffix=(
+                        prompt["options"].get("default_suffix", "")
+                        if count == requirement.recommended_count
+                        else ""
+                    ),
+                ),
+            )
+            for count in range(requirement.min_count, requirement.max_count + 1)
+        ],
+        echo_template=prompt["echo_template"],
+    )
+
+
+def _role_add_prompt(
+    state: WizardState,
+    requirement: RoleRequirement,
+) -> Prompt:
+    """min=0 선택 역할: 기본은 추가 안 함, 추가 시 1..max 수량을 이 스텝에서 고른다."""
+    prompt = _p(
+        state.workspace_root,
+        "role_add",
+        role=requirement.role,
+        maximum=str(requirement.max_count),
+    )
+    options = [
+        _opt(
+            "0",
+            prompt["options"]["skip"].format(
+                default_suffix=prompt["options"].get("default_suffix", ""),
+            ),
+        ),
+    ]
+    for count in range(1, requirement.max_count + 1):
+        options.append(
+            _opt(
+                str(count),
+                prompt["options"]["add"].format(count=count),
+            )
+        )
+    return Prompt(
+        step=_role_add_prompt_id(requirement.role),
+        kind="pick",
+        label=prompt["label"],
+        options=options,
+        echo_template=prompt["echo_template"],
+    )
+
+
+def _role_default_candidates(
+    state: WizardState,
+    role: str,
+    pool: ModelPool,
+    scopes: ModelDefaultScopes | None = None,
+) -> tuple[str, ...]:
+    try:
+        selected_scopes = scopes or _model_default_scopes(Path(state.project_root))
+        scoped = default_candidates(role, selected_scopes)
+    except (PrepareError, ValueError) as exc:
+        raise WizardError(str(exc)) from exc
+    if scoped:
+        for model_ref in scoped:
+            availability = pool.availability(
+                model_ref,
+                role,
+                state.host_runtime,
+                "new-session",
+            )
+            if not availability.available:
+                raise WizardError(
+                    f"configured default model {model_ref!r} is unavailable for "
+                    f"role {role!r}: {availability.reason}"
+                )
+        return tuple(scoped)
+    return tuple(
+        str(model.model_ref) for model in pool.default_candidates(role)
+    )
+
+
+def _role_model_options(
+    state: WizardState,
+    profile: RoleProfile,
+    role: str,
+    ordinal: int,
+    context: AssignmentContext,
+    scopes: ModelDefaultScopes,
+) -> list[Option]:
+    pool = context.pool
+    defaults = _role_default_candidates(state, role, pool, scopes)
+    if defaults:
+        offset = (ordinal - 1) % len(defaults)
+        defaults = (*defaults[offset:], *defaults[:offset])
+    candidate_refs = [
+        *defaults,
+        *(str(model.model_ref) for model in pool.list(role=role)),
+    ]
+    ordered_refs = tuple(dict.fromkeys(candidate_refs))
+    default_refs = frozenset(defaults)
+    prompt = _p(
+        state.workspace_root,
+        "role_model",
+        role=role,
+        ordinal="1",
+        count="1",
+    )
+    options: list[Option] = []
+    for model_ref in ordered_refs:
+        availability = pool.availability(
+            model_ref,
+            role,
+            state.host_runtime,
+            "new-session",
+        )
+        if not availability.available:
+            continue
+        candidate_models = {
+            selected_role: tuple(models)
+            for selected_role, models in state.role_models.items()
+        }
+        selected = list(candidate_models.get(role, ()))[: ordinal - 1]
+        selected.append(model_ref)
+        candidate_models[role] = tuple(selected)
+        if not _role_selection_can_complete(
+            state,
+            profile,
+            context,
+            candidate_models,
+            scopes,
+        ):
+            continue
+        model = pool.resolve(model_ref)
+        options.append(_opt(
+            model_ref,
+            prompt["options"]["model"].format(
+                model_ref=model_ref,
+                display=model.display_name,
+                default_suffix=(
+                    prompt["options"].get("default_suffix", "")
+                    if model_ref in default_refs
+                    else ""
+                ),
+            ),
+        ))
+    if not options:
+        _validate_role_selection_feasibility(state, profile, context, scopes)
+        raise WizardError(f"role {role!r} has no executable model candidates")
+    return options
+
+
+def _model_prompt(
+    state: WizardState,
+    profile: RoleProfile,
+    requirement: RoleRequirement,
+    ordinal: int,
+    context: AssignmentContext,
+    scopes: ModelDefaultScopes,
+) -> Prompt:
+    prompt = _p(
+        state.workspace_root,
+        "role_model",
+        role=requirement.role,
+        ordinal=str(ordinal),
+        count=str(_selected_role_count(state, requirement)),
+    )
+    return Prompt(
+        step=_role_model_prompt_id(requirement.role, ordinal),
+        kind="pick",
+        label=prompt["label"],
+        options=_role_model_options(
+            state,
+            profile,
+            requirement.role,
+            ordinal,
+            context,
+            scopes,
+        ),
+        echo_template=prompt["echo_template"],
+    )
+
+
+def _rewind_invalid_role_models(
+    state: WizardState,
+    requirements: tuple[RoleRequirement, ...],
+    requirement_index: int,
+    model_index: int,
+) -> None:
+    requirement = requirements[requirement_index]
+    del state.role_models[requirement.role][model_index:]
+    invalid_ids: set[str] = set()
+    for later_index, later_requirement in enumerate(
+        requirements[requirement_index:],
+        start=requirement_index,
+    ):
+        first_ordinal = model_index + 1 if later_index == requirement_index else 1
+        later_count = _selected_role_count(state, later_requirement)
+        invalid_ids.update(
+            _role_model_prompt_id(later_requirement.role, ordinal)
+            for ordinal in range(first_ordinal, later_count + 1)
+        )
+        if later_index != requirement_index:
+            state.role_models.pop(later_requirement.role, None)
+    state.role_selection_order = [
+        step_id for step_id in state.role_selection_order
+        if step_id not in invalid_ids
+    ]
+    state.answered = [
+        step_id for step_id in state.answered if step_id not in invalid_ids
+    ]
+
+
+def _discard_invalid_previous_models(
+    state: WizardState,
+    profile: RoleProfile,
+    requirements: tuple[RoleRequirement, ...],
+    context: AssignmentContext,
+    scopes: ModelDefaultScopes,
+) -> None:
+    selected_models = {
+        role: tuple(models) for role, models in state.role_models.items()
+    }
+    if _role_selection_error(
+        state,
+        profile,
+        context,
+        selected_models,
+        scopes,
+    ) is None:
+        return
+    selected_prefix: dict[str, tuple[str, ...]] = {}
+    for requirement_index, requirement in enumerate(requirements):
+        count = _selected_role_count(state, requirement)
+        selected = state.role_models.get(requirement.role, [])
+        if len(selected) > count:
+            raise WizardError(
+                f"role {requirement.role!r} has {len(selected)} models for "
+                f"{count} instances"
+            )
+        for index, model_ref in enumerate(selected):
+            candidate_prefix = dict(selected_prefix)
+            candidate_prefix[requirement.role] = tuple(selected[: index + 1])
+            if _role_selection_can_complete(
+                state,
+                profile,
+                context,
+                candidate_prefix,
+                scopes,
+            ):
+                continue
+            _rewind_invalid_role_models(
+                state,
+                requirements,
+                requirement_index,
+                index,
+            )
+            return
+        if selected:
+            selected_prefix[requirement.role] = tuple(selected)
+
+
+def _host_session_context(state: WizardState) -> HostSessionContext:
+    native_provider = default_host_registry().resolve(
+        state.host_runtime
+    ).descriptor.native_provider_id
+    return HostSessionContext(
+        host_id=state.host_runtime,
+        entry_mode=state.host_entry_mode,
+        available_functions=frozenset(state.available_functions),
+        interaction_surface="wizard",
+        current_model=CurrentSessionModelAttestation.unknown(native_provider),
+    )
+
+
+def _role_selection_error(
+    state: WizardState,
+    profile: RoleProfile,
+    context: AssignmentContext,
+    role_models: dict[str, tuple[str, ...]],
+    scopes: ModelDefaultScopes,
+) -> str | None:
+    try:
+        resolve_assignments(
+            profile=profile,
+            role_counts=dict(state.role_counts),
+            role_models=role_models,
+            scopes=scopes,
+            pool=context.pool,
+            host=_host_session_context(state),
+            environment=context.environment,
+        )
+    except AssignmentResolutionError as exc:
+        return _assignment_resolution_message(exc)
+    except (PrepareError, ValueError, RuntimeError) as exc:
+        return str(exc)
+    return None
+
+
+def _executable_role_models(
+    state: WizardState,
+    profile: RoleProfile,
+    requirement: RoleRequirement,
+    context: AssignmentContext,
+) -> tuple[str, ...]:
+    host = _host_session_context(state)
+    candidates: list[str] = []
+    instance = RoleInstance(requirement.role, requirement.duty, 1)
+    for model in context.pool.list(role=requirement.role):
+        model_ref = str(model.model_ref)
+        try:
+            resolve_model_assignment(
+                instance=instance,
+                model_ref=model_ref,
+                pool=context.pool,
+                host=host,
+                environment=context.environment,
+            )
+        except (AssignmentResolutionError, ValueError, RuntimeError):
+            continue
+        candidates.append(model_ref)
+    return tuple(candidates)
+
+
+def _completed_role_models(
+    state: WizardState,
+    profile: RoleProfile,
+    context: AssignmentContext,
+    role_models: dict[str, tuple[str, ...]],
+) -> dict[str, tuple[str, ...]] | None:
+    completed = {role: list(models) for role, models in role_models.items()}
+    for requirement in _selectable_static_requirements(state, profile):
+        count = _selected_role_count(state, requirement)
+        selected = completed.setdefault(requirement.role, [])
+        if len(selected) > count:
+            return None
+        candidates = _executable_role_models(state, profile, requirement, context)
+        if not candidates or any(model not in candidates for model in selected):
+            return None
+        # 같은 역할 패널의 model_ref 는 서로 달라야 한다.
+        if len(set(selected)) < len(selected):
+            return None
+        used = set(selected)
+        remaining = [model for model in candidates if model not in used]
+        if len(remaining) < count - len(selected):
+            return None
+        while len(selected) < count:
+            model_ref = next(
+                model for model in candidates if model not in used
+            )
+            selected.append(model_ref)
+            used.add(model_ref)
+    return {role: tuple(models) for role, models in completed.items()}
+
+
+def _role_selection_can_complete(
+    state: WizardState,
+    profile: RoleProfile,
+    context: AssignmentContext,
+    role_models: dict[str, tuple[str, ...]],
+    scopes: ModelDefaultScopes,
+) -> bool:
+    completed = _completed_role_models(state, profile, context, role_models)
+    return completed is not None and _role_selection_error(
+        state,
+        profile,
+        context,
+        completed,
+        scopes,
+    ) is None
+
+
+def _validate_role_selection_feasibility(
+    state: WizardState,
+    profile: RoleProfile,
+    context: AssignmentContext | None = None,
+    scopes: ModelDefaultScopes | None = None,
+) -> None:
+    assignment_context = context or load_assignment_context(
+        host_runtime=state.host_runtime,
+        terminal_backend=detect_terminal_backend(),
+    )
+    selected_scopes = scopes or _model_default_scopes(Path(state.project_root))
+    error = _role_selection_error(
+        state,
+        profile,
+        assignment_context,
+        {
+            role: tuple(models) for role, models in state.role_models.items()
+        },
+        selected_scopes,
+    )
+    if error is not None:
+        raise WizardError(error)
+
+
+def next_role_prompt(state: WizardState) -> Prompt | None:
+    """Ask every adjustable count before one model question per role instance."""
+    if not _role_selection_enabled(state) or not _identity_ready(state):
+        return None
+    state.use_defaults = False
+    # current-session: 리더는 읽기 전용 확인 칸만 먼저 보여 준다.
+    if (
+        state.host_entry_mode == "current-session"
+        and _LEADER_SESSION_STEP not in state.answered
+        and _LEADER_SESSION_STEP not in state.role_selection_order
+    ):
+        return _leader_session_prompt(state)
+    profile = _load_role_profile_for_state(state)
+    for requirement in profile.roles:
+        # 필수 수량: min < max 이고 min > 0 일 때만.
+        if (
+            requirement.dynamic
+            or requirement.min_count == requirement.max_count
+            or requirement.min_count == 0
+        ):
+            continue
+        if requirement.role not in state.role_counts:
+            return _count_prompt(state, requirement)
+        count = state.role_counts[requirement.role]
+        if count < requirement.min_count or count > requirement.max_count:
+            raise WizardError(
+                f"role {requirement.role!r} count must be in "
+                f"{requirement.min_count}..{requirement.max_count}: {count}"
+            )
+    for requirement in profile.roles:
+        # 선택 역할(min=0, max>0): 기본은 추가 안 함. role-add 로만 연다.
+        if (
+            requirement.dynamic
+            or requirement.min_count != 0
+            or requirement.max_count == 0
+        ):
+            continue
+        if requirement.role not in state.role_counts:
+            return _role_add_prompt(state, requirement)
+        count = state.role_counts[requirement.role]
+        if count < 0 or count > requirement.max_count:
+            raise WizardError(
+                f"role {requirement.role!r} count must be in "
+                f"0..{requirement.max_count}: {count}"
+            )
+    requirements = _selectable_static_requirements(state, profile)
+    try:
+        scopes = _model_default_scopes(Path(state.project_root))
+    except (PrepareError, ValueError) as exc:
+        raise WizardError(str(exc)) from exc
+    context = load_assignment_context(
+        host_runtime=state.host_runtime,
+        terminal_backend=detect_terminal_backend(),
+    )
+    _discard_invalid_previous_models(
+        state,
+        profile,
+        requirements,
+        context,
+        scopes,
+    )
+    for requirement in requirements:
+        count = _selected_role_count(state, requirement)
+        selected = state.role_models.get(requirement.role, [])
+        if len(selected) < count:
+            return _model_prompt(
+                state,
+                profile,
+                requirement,
+                len(selected) + 1,
+                context,
+                scopes,
+            )
+    _validate_role_selection_feasibility(state, profile, context, scopes)
+    return None
+
+
+def _validate_submitted_role_model(
+    state: WizardState,
+    profile: RoleProfile,
+) -> None:
+    try:
+        scopes = _model_default_scopes(Path(state.project_root))
+    except (PrepareError, ValueError) as exc:
+        raise WizardError(str(exc)) from exc
+    context = load_assignment_context(
+        host_runtime=state.host_runtime,
+        terminal_backend=detect_terminal_backend(),
+    )
+    role_models = {
+        role: tuple(models) for role, models in state.role_models.items()
+    }
+    requirements = _selectable_static_requirements(state, profile)
+    complete = all(
+        len(role_models.get(requirement.role, ()))
+        == _selected_role_count(state, requirement)
+        for requirement in requirements
+    )
+    if complete:
+        _validate_role_selection_feasibility(state, profile, context, scopes)
+        return
+    if not _role_selection_can_complete(
+        state,
+        profile,
+        context,
+        role_models,
+        scopes,
+    ):
+        raise WizardError("selected role model leaves no complete role assignment")
+
+
+def _submit_role_prompt(state: WizardState, prompt: Prompt, value: str) -> str:
+    if prompt.step == _LEADER_SESSION_STEP:
+        if value != "continue":
+            raise WizardError("leader session step accepts only 'continue'")
+        # role_models["leader"] 에 쓰지 않는다 — 현재 세션 모델을 그대로 쓴다.
+        return "leader-session: continue"
+    if prompt.step.startswith("role-count:"):
+        role = prompt.step.split(":", 1)[1]
+        profile = _load_role_profile_for_state(state)
+        requirement = next(
+            (row for row in profile.roles if row.role == role),
+            None,
+        )
+        if (
+            requirement is None
+            or requirement.dynamic
+            or requirement.min_count == requirement.max_count
+            or requirement.min_count == 0
+        ):
+            raise WizardError(f"role {role!r} does not accept a count selection")
+        try:
+            count = int(value)
+        except ValueError as exc:
+            raise WizardError(f"role {role!r} count must be an integer") from exc
+        if count < requirement.min_count or count > requirement.max_count:
+            raise WizardError(
+                f"role {role!r} count must be in "
+                f"{requirement.min_count}..{requirement.max_count}: {count}"
+            )
+        state.role_counts[role] = count
+        state.role_models.pop(role, None)
+        return f"role-count: {role}={count}"
+    if prompt.step.startswith("role-add:"):
+        role = prompt.step.split(":", 1)[1]
+        profile = _load_role_profile_for_state(state)
+        requirement = next(
+            (row for row in profile.roles if row.role == role),
+            None,
+        )
+        if (
+            requirement is None
+            or requirement.dynamic
+            or requirement.min_count != 0
+            or requirement.max_count == 0
+        ):
+            raise WizardError(f"role {role!r} does not accept an optional add")
+        allowed = {option.value for option in prompt.options}
+        if value not in allowed:
+            raise WizardError(
+                f"role {role!r} add selection must be one of "
+                f"{sorted(allowed, key=int)}: {value}"
+            )
+        try:
+            count = int(value)
+        except ValueError as exc:
+            raise WizardError(f"role {role!r} count must be an integer") from exc
+        if count < 0 or count > requirement.max_count:
+            raise WizardError(
+                f"role {role!r} count must be in "
+                f"0..{requirement.max_count}: {count}"
+            )
+        state.role_counts[role] = count
+        state.role_models.pop(role, None)
+        return f"role-add: {role}={count}"
+    _, role, ordinal_raw = prompt.step.split(":", 2)
+    ordinal = int(ordinal_raw)
+    allowed = {option.value for option in prompt.options}
+    if value not in allowed:
+        raise WizardError(
+            f"model {value!r} is not a compatible candidate for role {role!r}"
+        )
+    selected = state.role_models.setdefault(role, [])
+    if ordinal != len(selected) + 1:
+        raise WizardError(
+            f"role {role!r} model selection is out of order at ordinal {ordinal}"
+        )
+    selected.append(value)
+    try:
+        profile = _load_role_profile_for_state(state)
+        _validate_submitted_role_model(state, profile)
+    except WizardError:
+        selected.pop()
+        raise
+    return f"role-model: {role}#{ordinal}={value}"
+
+
 def _load_profile_workers(workspace_root: Path, task_type: str) -> list[str]:
     return resolve_profile_workers(_profile_path(workspace_root, task_type))
 
@@ -1270,6 +2289,30 @@ def _contract_outcome_suffix(entry: dict) -> str:
     return ""
 
 
+def _next_phase_cell(raw: Any) -> str:
+    """task picker 한 줄에 실을 다음 phase 표기.
+
+    `phase` 만 싣고 `status` 를 버리면 "아직 여기 있다" 가 "다음으로 갈 수 있다"
+    로 읽힌다. prepare 는 끝나지 않은 run 의 포인터를 `ready` → `pending` 으로
+    내리면서 `phase` 는 남겨두므로(`render._derive_next_recommended_phase`),
+    준비만 된 implementation 태스크의 포인터가
+    `{"phase": "final-verification", "status": "pending"}` 이다. status 를 안
+    보면 그 줄이 `next: final-verification` 으로 찍혀 착수 가능한 것처럼 읽힌다.
+
+    그래서 `ready` 가 아닌 status 는 괄호로 함께 싣는다. `okstra-inspect` 의
+    status 표는 같은 정보를 `*` 마커로 싣지만(`facets/status.md`), 그쪽은 표
+    아래 범례 한 줄을 붙일 수 있는 자리다. picker 옵션은 라벨 한 줄이 전부라
+    범례를 둘 데가 없으므로 status 이름을 그대로 적는다. phase 를 `--` 로
+    지우지 않는 이유는 그 이름이 "어디로 가는 태스크인가" 라는 정보를 여전히
+    나르기 때문이다 — 지우는 것은 착수 가능성만이 아니라 목적지까지 지운다.
+    """
+    pointer = next_phase.promote(raw)
+    cell = pointer["phase"] or "--"
+    if pointer["status"] == next_phase.STATUS_READY:
+        return cell
+    return f"{cell} ({pointer['status']})"
+
+
 def _build_task_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_pick")
     project_root = Path(state.project_root)
@@ -1285,7 +2328,7 @@ def _build_task_pick(state: WizardState) -> Prompt:
         # catalog entries are flat (render_task_catalog_discovery) — there is
         # no nested "workflow" object here, unlike task-manifest.json.
         phase = entry.get("currentPhase") or ttype
-        nxt = entry.get("nextRecommendedPhase") or ""
+        nxt = _next_phase_cell(entry.get("nextRecommendedPhase"))
         suffix = latest_suffix if key == latest_key else ""
         label = f"{key}  ·  {phase}  ·  next: {nxt}{_contract_outcome_suffix(entry)}{suffix}"
         options.append(_opt(value=key, label=label))
@@ -1325,8 +2368,7 @@ def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
     # task_type seeded from manifest's nextRecommendedPhase as the recommended default
     root = find_task_root(Path(state.project_root), value)
     manifest = (read_task_manifest(root) or {}) if root else {}
-    workflow = manifest.get("workflow") or {}
-    state.task_type = workflow.get("nextRecommendedPhase") or ""
+    state.task_type = next_phase.autofill_task_type(manifest)
     return f"task: {value}"
 
 
@@ -1770,8 +2812,18 @@ def _build_task_type(state: WizardState) -> Prompt:
 
     workflow = _existing_task_workflow(state)
     revision_requested = _latest_revision_requested_analysis_type(state)
+    # 포인터에서 phase 를 꺼내는 것은 `status` 가 `ready` 일 때뿐이다. prepare 는
+    # 실행이 끝나지 않은 run 의 포인터를 일부러 `pending` 으로 내려두는데
+    # (`render._derive_next_recommended_phase`), 여기서 status 를 안 보고 `phase`
+    # 만 꺼내면 그 방어를 그대로 우회한다 — 기록된 사례가 `implementation` 이
+    # `prepared` 상태인데 `final-verification` 이 추천으로 뜬 것이다. 판정은
+    # 셸 진입점이 쓰는 것과 같은 함수(`next_phase.autofill_task_type`)로 한다.
+    #
+    # `ready` 가 아니면 추천은 비고, 아래 `currentPhase` 재실행 옵션이 남는다.
+    # 실패한 run 의 포인터가 `{"phase": "", "status": "blocked"}` 라는 점에서
+    # 그것이 맞는 제안이다 — 그 옵션은 포인터가 아니라 `currentPhase` 에서 온다.
     recommended = (revision_requested or state.task_type
-                   or workflow.get("nextRecommendedPhase") or "")
+                   or next_phase.autofill_task_type({"workflow": workflow}))
     if not recommended and not workflow:
         recommended = TASK_TYPE_VALUES[0]
     add(recommended, recommended_suffix)
@@ -3534,6 +4586,14 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
     report_writer_provider = state.report_writer_provider or "claude"
     state.report_writer_model = _safe_model(
         report_writer_provider, inputs.get("reportWriterModel"))
+    if _role_selection_enabled(state):
+        conversion_payload = dict(inputs)
+        conversion_payload.setdefault("grokModel", state.grok_model)
+        conversion_payload.setdefault("kimiModel", state.kimi_model)
+        state.role_counts.clear()
+        state.role_models.clear()
+        state.role_selection_order.clear()
+        _convert_v1_provider_selections(state, conversion_payload)
     directive = inputs.get("directive")
     state.directive = directive if isinstance(directive, str) else ""
     related = inputs.get("relatedTasks")
@@ -3579,6 +4639,7 @@ def _role_model_lines(state: WizardState) -> str:
         .resolve(state.host_runtime)
         .descriptor.native_provider_id
         or "",
+        report_writer_provider=state.report_writer_provider or "claude",
     )
     roster = _resolved_roster(state)
     impl = state.task_type == "implementation"
@@ -4116,7 +5177,15 @@ def _build_edit_target(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "edit_target")
     # offer every step that has been answered.
     options: list[Option] = []
-    for sid in state.answered:
+    selection_ids = [
+        *state.answered,
+        *(
+            step_id
+            for step_id in state.role_selection_order
+            if step_id not in state.answered
+        ),
+    ]
+    for sid in selection_ids:
         if sid in (S_CONFIRM, S_EDIT_TARGET):
             continue
         options.append(_opt(sid, sid))
@@ -4128,11 +5197,59 @@ def _build_edit_target(state: WizardState) -> Prompt:
     )
 
 
+def _reset_role_selection_from(state: WizardState, target_step: str) -> None:
+    try:
+        target_index = state.role_selection_order.index(target_step)
+    except ValueError as exc:
+        raise WizardError(f"unknown role selection step: {target_step!r}") from exc
+    kept_ids = state.role_selection_order[:target_index]
+    kept_counts = {
+        step_id.split(":", 1)[1]
+        for step_id in kept_ids
+        if step_id.startswith(("role-count:", "role-add:"))
+    }
+    kept_models: dict[str, int] = {}
+    for step_id in kept_ids:
+        if not step_id.startswith("role-model:"):
+            continue
+        _, role, _ = step_id.split(":", 2)
+        kept_models[role] = kept_models.get(role, 0) + 1
+    state.role_counts = {
+        role: count
+        for role, count in state.role_counts.items()
+        if role in kept_counts
+    }
+    state.role_models = {
+        role: models[:kept_models[role]]
+        for role, models in state.role_models.items()
+        if kept_models.get(role, 0) > 0
+    }
+    removed_ids = set(state.role_selection_order[target_index:])
+    state.role_selection_order = kept_ids
+    state.answered = [
+        step_id for step_id in state.answered if step_id not in removed_ids
+    ]
+
+
+def _clear_role_selection(state: WizardState) -> None:
+    state.role_counts.clear()
+    state.role_models.clear()
+    state.role_selection_order.clear()
+    state.answered = [
+        step_id
+        for step_id in state.answered
+        if not _is_role_selection_step(step_id)
+    ]
+
+
 def _submit_edit_target(state: WizardState, value: str) -> Optional[str]:
-    if not any(s.id == value for s in STEPS):
+    if _is_role_selection_step(value):
+        _reset_role_selection_from(state, value)
+    elif any(s.id == value for s in STEPS):
+        _reset_from(state, value)
+    else:
         raise WizardError(f"unknown step: {value!r}")
     state.edit_target = value
-    _reset_from(state, value)
     state.confirmed = None
     state.edit_target = ""
     return f"edit-target: {value} (rewinding)"
@@ -4379,23 +5496,28 @@ STEPS: list[Step] = [
          owns=("handoff_mode", "handoff_stages", "approved_plan_path")),
     Step(S_EXECUTOR,
          applies=lambda s: (s.task_type == "implementation"
+                            and not _role_selection_enabled(s)
                             and bool(s.approved_plan_path)
                             and not s.executor),
          build=_build_executor, submit=_submit_executor,
          owns=("executor",)),
     Step(S_CRITIC_PICK,
-         applies=lambda s: (s.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification")
+         applies=lambda s: (not _role_selection_enabled(s)
+                            and s.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification")
                             and not s.critic
                             and not s.critic_pending_text
                             and S_CRITIC_PICK not in s.answered),
          build=_build_critic_pick, submit=_submit_critic_pick,
          owns=("critic", "critic_pending_text")),
     Step(S_CRITIC_TEXT,
-         applies=lambda s: (s.critic_pending_text and S_CRITIC_TEXT not in s.answered),
+         applies=lambda s: (not _role_selection_enabled(s)
+                            and s.critic_pending_text
+                            and S_CRITIC_TEXT not in s.answered),
          build=_build_critic_text, submit=_submit_critic_text,
          owns=("critic", "critic_pending_text")),
     Step(S_DEFAULTS_OR_CUSTOM,
          applies=lambda s: (_identity_ready(s)
+                            and not _role_selection_enabled(s)
                             and s.use_defaults is None),
          build=_build_defaults_or_custom, submit=_submit_defaults_or_custom,
          owns=("use_defaults",)),
@@ -4408,6 +5530,7 @@ STEPS: list[Step] = [
     # still skipped because it runs lead + executor only.
     Step(S_WORKERS_OVERRIDE,
          applies=lambda s: (s.task_type != "implementation"
+                            and not _role_selection_enabled(s)
                             and any(
                                 w != "report-writer"
                                 for w in (s.profile_workers
@@ -4419,23 +5542,27 @@ STEPS: list[Step] = [
     # "직접 선택" 을 고른 run 에서만 등장한다 — 기본 로스터에서 워커를 빼는
     # 축소가 가능한 유일한 화면.
     Step(S_WORKERS_CUSTOM,
-         applies=lambda s: (s.workers_custom_pending
+         applies=lambda s: (not _role_selection_enabled(s)
+                            and s.workers_custom_pending
                             and S_WORKERS_CUSTOM not in s.answered),
          build=_build_workers_custom, submit=_submit_workers_custom,
          owns=("workers_override", "workers_custom_pending")),
     Step(S_LEAD_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and S_LEAD_MODEL not in s.answered),
          build=_build_lead_model, submit=_submit_lead_model,
          owns=("lead_provider", "lead_model")),
     Step(S_EXECUTOR_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type == "implementation"
                             and S_EXECUTOR_MODEL not in s.answered),
          build=_build_executor_model, submit=_submit_executor_model,
          owns=("claude_model", "codex_model", "antigravity_model")),
     Step(S_CLAUDE_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type != "implementation"
                             and "claude" in _resolved_roster(s)
                             and S_CLAUDE_MODEL not in s.answered),
@@ -4443,6 +5570,7 @@ STEPS: list[Step] = [
          owns=("claude_model",)),
     Step(S_CODEX_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type != "implementation"
                             and "codex" in _resolved_roster(s)
                             and S_CODEX_MODEL not in s.answered),
@@ -4450,6 +5578,7 @@ STEPS: list[Step] = [
          owns=("codex_model",)),
     Step(S_ANTIGRAVITY_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type != "implementation"
                             and "antigravity" in _resolved_roster(s)
                             and S_ANTIGRAVITY_MODEL not in s.answered),
@@ -4457,6 +5586,7 @@ STEPS: list[Step] = [
          owns=("antigravity_model",)),
     Step(S_GROK_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type != "implementation"
                             and "grok" in _resolved_roster(s)
                             and S_GROK_MODEL not in s.answered),
@@ -4464,6 +5594,7 @@ STEPS: list[Step] = [
          owns=("grok_model",)),
     Step(S_KIMI_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and s.task_type != "implementation"
                             and "kimi" in _resolved_roster(s)
                             and S_KIMI_MODEL not in s.answered),
@@ -4471,6 +5602,7 @@ STEPS: list[Step] = [
          owns=("kimi_model",)),
     Step(S_REPORT_WRITER_MODEL,
          applies=lambda s: (s.use_defaults is False
+                            and not _role_selection_enabled(s)
                             and (s.task_type == "implementation"
                                  or "report-writer" in _resolved_roster(s))
                             and S_REPORT_WRITER_MODEL not in s.answered),
@@ -4590,7 +5722,7 @@ def _identity_ready(s: WizardState) -> bool:
     if s.task_type in _STAGE_SCOPED_TASK_TYPES:
         if not s.approved_plan_path:
             return False
-    if s.task_type == "implementation":
+    if s.task_type == "implementation" and not _role_selection_enabled(s):
         if not s.executor:
             return False
     if (s.task_type == "release-handoff"
@@ -4600,6 +5732,24 @@ def _identity_ready(s: WizardState) -> bool:
 
 
 def _ready_for_confirm(s: WizardState) -> bool:
+    if _role_selection_enabled(s):
+        try:
+            if next_role_prompt(s) is not None:
+                return False
+        except WizardError:
+            return False
+        followup_ids = [
+            S_DIRECTIVE_PICK,
+            S_DIRECTIVE,
+            S_RELATED_TASKS_PICK,
+            S_RELATED_TASKS,
+            S_CLARIFICATION_PICK,
+            S_CLARIFICATION,
+            S_PR_TEMPLATE_PICK,
+            S_PR_TEMPLATE,
+            S_PR_TEMPLATE_SCOPE,
+        ]
+        return not any(STEP_BY_ID[step_id].applies(s) for step_id in followup_ids)
     if s.use_defaults is None:
         return False
     # Worker roster is required regardless of the defaults / customize
@@ -4631,6 +5781,12 @@ def _reset_from(state: WizardState, target_step: str) -> None:
     idx = next((i for i, s in enumerate(STEPS) if s.id == target_step), -1)
     if idx < 0:
         return
+    role_boundary = next(
+        i for i, step in enumerate(STEPS)
+        if step.id == S_DEFAULTS_OR_CUSTOM
+    )
+    if idx < role_boundary:
+        _clear_role_selection(state)
     # A later step may own a field an earlier answered step also owns —
     # `handoff_stage_pick` owns `approved_plan_path` because it resolves the
     # plan on its own. Clearing it while rewinding to a step in front of it
@@ -4687,6 +5843,8 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "selected_stages": "",
     "handoff_mode": "", "handoff_stages": "",
     "executor": "", "critic": "", "critic_pending_text": False,
+    "execution_identity_version": 1,
+    "role_counts": {}, "role_models": {}, "role_selection_order": [],
     "reuse_previous": None,
     "use_defaults": None, "workers_override": "",
     "workers_custom_pending": False,
@@ -4711,6 +5869,8 @@ def _reset_field(state: WizardState, fname: str) -> None:
         # copy mutable defaults
         if isinstance(default, list):
             setattr(state, fname, [])
+        elif isinstance(default, dict):
+            setattr(state, fname, {})
         else:
             setattr(state, fname, default)
 
@@ -4725,6 +5885,7 @@ def init_state(
 ) -> WizardState:
     """Bootstrap a new wizard state."""
     return WizardState(
+        execution_identity_version=2,
         workspace_root=workspace_root,
         project_root=project_root,
         project_id=project_id,
@@ -4764,6 +5925,10 @@ def next_prompt(state: WizardState) -> Prompt:
     if state.confirmed:
         return Prompt(step=S_DONE, kind="done")
     for step in STEPS:
+        if step.id == S_DEFAULTS_OR_CUSTOM:
+            role_prompt = next_role_prompt(state)
+            if role_prompt is not None:
+                return role_prompt
         if step.id in state.answered and not step.repeatable:
             continue
         if step.applies(state):
@@ -4800,6 +5965,13 @@ def _sim_advance(state: WizardState, prompt: Prompt) -> None:
     """기본답으로 한 화면 전진한다. progress 를 재계산하는 submit()/
     _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
     try:
+        if _is_role_selection_step(prompt.step):
+            _submit_role_prompt(state, prompt, _sim_answer(prompt))
+            if prompt.step not in state.answered:
+                state.answered.append(prompt.step)
+            if prompt.step not in state.role_selection_order:
+                state.role_selection_order.append(prompt.step)
+            return
         if prompt.kind == "pick_group":
             for q in prompt.questions:
                 STEP_BY_ID[q.step].submit(state, _sim_answer(q))
@@ -4980,6 +6152,14 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     value = _normalize_interaction_answer(state, prompt, plan, value)
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
+    if _is_role_selection_step(prompt.step):
+        echo = _submit_role_prompt(state, prompt, value or "")
+        if prompt.step not in state.answered:
+            state.answered.append(prompt.step)
+        if prompt.step not in state.role_selection_order:
+            state.role_selection_order.append(prompt.step)
+        nxt = next_prompt(state)
+        return {"echo": echo, "next": prompt_payload(state, nxt)}
     step = STEP_BY_ID[prompt.step]
     echo = step.submit(state, value or "")
     if prompt.step not in state.answered:
@@ -5005,15 +6185,45 @@ def _stage_intent(state: WizardState) -> WizardStageIntent:
         raise WizardError(str(exc)) from exc
 
 
-def render_args(state: WizardState) -> dict[str, str]:
+def render_role_args(state: WizardState) -> list[str]:
+    """Return ordered canonical role count/model CLI tokens."""
+    role_argv: list[str] = []
+    if _role_selection_enabled(state):
+        profile = _load_role_profile_for_state(state)
+        requirements = _selectable_static_requirements(state, profile)
+        for requirement in profile.roles:
+            if (
+                requirement.dynamic
+                or requirement.min_count == requirement.max_count
+            ):
+                continue
+            if requirement.role not in state.role_counts:
+                continue
+            count = state.role_counts[requirement.role]
+            if count <= 0:
+                continue
+            role_argv.extend([
+                "--role-count",
+                f"{requirement.role}={count}",
+            ])
+        ordered_roles = [requirement.role for requirement in requirements]
+    else:
+        ordered_roles = []
+    for role in state.role_models:
+        if role not in ordered_roles:
+            ordered_roles.append(role)
+    for role in ordered_roles:
+        for model_ref in state.role_models.get(role, []):
+            role_argv.extend(["--role-model", f"{role}={model_ref}"])
+    return role_argv
+
+
+def render_args(state: WizardState) -> dict[str, Any]:
     """Convert finalized state into ``okstra render-bundle`` argument map."""
     if state.aborted:
         raise WizardError(
             "wizard was aborted by the user — render-args is unavailable"
         )
-    workers = state.workers_override.strip()
-    if state.task_type == "implementation":
-        workers = ""  # profile-default roster is mandatory for impl
     base_ref = (
         ""
         if state.reuse_worktree or state.task_type == "final-verification"
@@ -5030,15 +6240,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         for path in (state.feature_evidence_path, state.project_evidence_path)
         if path
     ]
-    worker_models = ",".join(
-        f"{provider}={model}"
-        for provider, model in (
-            ("grok", state.grok_model),
-            ("kimi", state.kimi_model),
-        )
-        if model
-    )
-    return {
+    rendered: dict[str, Any] = {
         "project-root": state.project_root,
         "project-id": state.project_id,
         "task-group": state.task_group,
@@ -5047,22 +6249,11 @@ def render_args(state: WizardState) -> dict[str, str]:
         "task-brief": state.brief_path,
         "analysis-target": state.analysis_target,
         "evidence-inputs": ",".join(evidence_paths),
-        "executor": state.executor,
-        "critic": state.critic,
         "approved-plan": state.approved_plan_path,
         "stage": stage_intent.stage,
         "stages": state.handoff_stages,
         "base-ref": base_ref,
-        "workers": workers,
         "directive": state.directive,
-        "lead-provider": state.lead_provider,
-        "lead-model": state.lead_model,
-        "claude-model": state.claude_model,
-        "codex-model": state.codex_model,
-        "antigravity-model": state.antigravity_model,
-        "worker-model": worker_models,
-        "report-writer-provider": state.report_writer_provider,
-        "report-writer-model": state.report_writer_model,
         "related-tasks": state.related_tasks_raw,
         "clarification-response": state.clarification_response_path,
         "selected-direction": state.selected_direction_path,
@@ -5072,7 +6263,36 @@ def render_args(state: WizardState) -> dict[str, str]:
         ),
         "pr-template-path": pr_template,
         "fix-cycle": state.fix_cycle,
+        "host-session-context-json": serialize_host_session_context(
+            _host_session_context(state)
+        ),
     }
+    role_argv = render_role_args(state)
+    rendered["role-count"] = [
+        role_argv[index + 1]
+        for index, token in enumerate(role_argv)
+        if token == "--role-count"
+    ]
+    rendered["role-model"] = [
+        role_argv[index + 1]
+        for index, token in enumerate(role_argv)
+        if token == "--role-model"
+    ]
+    return rendered
+
+
+def _render_argv(rendered: dict[str, Any], *, host_runtime: str) -> list[str]:
+    """Flatten render arguments into the canonical render-bundle argv."""
+    argv = ["--lead-runtime", host_runtime]
+    for name, raw_value in rendered.items():
+        values = raw_value if isinstance(raw_value, list) else [raw_value]
+        for value in values:
+            if not isinstance(value, str):
+                raise WizardError(
+                    f"wizard render arg --{name} must be a string"
+                )
+            argv.extend([f"--{name}", value])
+    return argv
 
 
 def _clarification_sidecar_line(state: WizardState) -> Optional[str]:
@@ -5172,37 +6392,77 @@ def confirmation_block(state: WizardState) -> str:
     worktree_line = _worktree_preview_line(state)
     if worktree_line is not None:
         lines.append(worktree_line)
-    if state.task_type == "implementation":
+    role_selection = _role_selection_enabled(state)
+    if state.task_type == "implementation" and not role_selection:
         lines.append(f"  executor      : {state.executor or '(default)'}")
         lines.append(
             _msg(state.workspace_root, "confirmation", "workers_implementation_default")
         )
-    else:
+    elif not role_selection:
         roster = state.workers_override or ",".join(state.profile_workers) or "(profile default)"
         lines.append(f"  workers       : {roster}")
-    lines.append(
-        f"  lead          : {state.lead_provider or 'claude'} / "
-        f"{state.lead_model or 'default'}"
-    )
-    if state.claude_model:
-        lines.append(f"  claude-model  : {state.claude_model}")
-    if state.codex_model:
-        lines.append(f"  codex-model   : {state.codex_model}")
-    if state.antigravity_model:
-        lines.append(f"  antigravity-model  : {state.antigravity_model}")
-    if state.grok_model:
-        lines.append(f"  grok-model    : {state.grok_model}")
-    if state.kimi_model:
-        lines.append(f"  kimi-model    : {state.kimi_model}")
-    if state.report_writer_model or state.report_writer_provider:
+    if role_selection:
+        profile = _load_role_profile_for_state(state)
+        if state.host_entry_mode == "current-session":
+            lines.append(_msg(
+                state.workspace_root,
+                "confirmation",
+                "static_role",
+                role="leader",
+                ordinal="1",
+                model="current-session",
+            ))
+        for requirement in _selectable_static_requirements(state, profile):
+            count = _selected_role_count(state, requirement)
+            selected = state.role_models.get(requirement.role, [])
+            for ordinal in range(1, count + 1):
+                model_ref = (
+                    selected[ordinal - 1]
+                    if ordinal <= len(selected)
+                    else "(selection required)"
+                )
+                lines.append(_msg(
+                    state.workspace_root,
+                    "confirmation",
+                    "static_role",
+                    role=requirement.role,
+                    ordinal=str(ordinal),
+                    model=model_ref,
+                ))
+        for requirement in profile.roles:
+            if not requirement.dynamic:
+                continue
+            lines.append(_msg(
+                state.workspace_root,
+                "confirmation",
+                "dynamic_role",
+                role=requirement.role,
+            ))
+    else:
         lines.append(
-            f"  report-writer : {state.report_writer_provider or 'claude'} / "
-            f"{state.report_writer_model or 'default'}"
+            f"  lead          : {state.lead_provider or 'claude'} / "
+            f"{state.lead_model or 'default'}"
         )
+        if state.claude_model:
+            lines.append(f"  claude-model  : {state.claude_model}")
+        if state.codex_model:
+            lines.append(f"  codex-model   : {state.codex_model}")
+        if state.antigravity_model:
+            lines.append(f"  antigravity-model  : {state.antigravity_model}")
+        if state.grok_model:
+            lines.append(f"  grok-model    : {state.grok_model}")
+        if state.kimi_model:
+            lines.append(f"  kimi-model    : {state.kimi_model}")
+        if state.report_writer_model or state.report_writer_provider:
+            lines.append(
+                f"  report-writer : {state.report_writer_provider or 'claude'} / "
+                f"{state.report_writer_model or 'default'}"
+            )
     lines.append(f"  directive     : {state.directive or '(none)'}")
     if state.related_tasks_raw:
         lines.append(f"  related-tasks : {state.related_tasks_raw}")
-    if state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification"):
+    if (not role_selection
+            and state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification")):
         lines.append(f"  critic        : {state.critic or '(off)'}")
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
@@ -5269,8 +6529,10 @@ def wizard_outcome(state: WizardState) -> dict[str, Any]:
         raise WizardError("wizard was aborted by the user — outcome is unavailable")
     if state.confirmed is not True:
         raise WizardError("wizard is not complete — outcome is unavailable")
+    rendered = render_args(state)
     return {
-        "renderArgs": render_args(state),
+        "renderArgs": rendered,
+        "renderArgv": _render_argv(rendered, host_runtime=state.host_runtime),
         "orchestration": {"chainStages": _stage_intent(state).chain_stages},
         "persistActions": _wizard_persist_actions(state),
         "confirmationText": confirmation_block(state),
@@ -5279,16 +6541,136 @@ def wizard_outcome(state: WizardState) -> dict[str, Any]:
 
 # ---- File I/O helpers (used by CLI) -------------------------------------
 
+_LEGACY_SOURCE_FIELD = "legacySource"
+
+
+def _legacy_v2_companion_path(path: Path) -> Path:
+    return path.with_name(f"{path.name}.v2.json")
+
+
+def _content_addressed_v2_companion_path(
+    path: Path,
+    source_digest: str,
+    suffix: int | None = None,
+) -> Path:
+    numbered = f".{suffix}" if suffix is not None else ""
+    return path.with_name(f"{path.name}.v2.{source_digest}{numbered}.json")
+
+
+def _content_addressed_v2_companion_paths(
+    path: Path,
+    source_digest: str,
+) -> tuple[Path, ...]:
+    canonical = _content_addressed_v2_companion_path(path, source_digest)
+    numbered_prefix = f"{path.name}.v2.{source_digest}."
+    numbered = tuple(sorted(
+        candidate
+        for candidate in path.parent.iterdir()
+        if candidate.is_file()
+        and candidate.name.startswith(numbered_prefix)
+        and candidate.name.endswith(".json")
+    ))
+    return (canonical, *numbered)
+
+
+def _available_v2_companion_path(path: Path, source_digest: str) -> Path:
+    candidate = _content_addressed_v2_companion_path(path, source_digest)
+    suffix = 1
+    while candidate.exists():
+        candidate = _content_addressed_v2_companion_path(
+            path,
+            source_digest,
+            suffix,
+        )
+        suffix += 1
+    return candidate
+
+
+def _legacy_source_metadata(path: Path, source: bytes) -> dict[str, str]:
+    return {
+        "path": str(path.resolve()),
+        "sha256": hashlib.sha256(source).hexdigest(),
+    }
+
+
+def _matching_v2_companion(
+    path: Path,
+    source_metadata: dict[str, str],
+) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if payload.get("executionIdentityVersion") != 2:
+        return None
+    if payload.get(_LEGACY_SOURCE_FIELD) != source_metadata:
+        return None
+    return payload
+
+
+def _load_matching_v2_state(
+    paths: tuple[Path, ...],
+    source_metadata: dict[str, str],
+) -> tuple[WizardState | None, Path | None]:
+    for companion_path in paths:
+        payload = _matching_v2_companion(companion_path, source_metadata)
+        if payload is None:
+            continue
+        try:
+            return WizardState.from_json(payload), companion_path
+        except WizardError:
+            continue
+    return None, None
+
+
 def load_state_file(path: Path) -> WizardState:
-    data = json.loads(Path(path).read_text(encoding="utf-8"))
-    return WizardState.from_json(data)
+    source_path = Path(path)
+    source = source_path.read_bytes()
+    data = json.loads(source)
+    source_version = data.get("executionIdentityVersion", 1)
+    source_metadata = _legacy_source_metadata(source_path, source)
+    source_digest = source_metadata["sha256"]
+    resumed_state = None
+    companion_path = None
+    if source_version in (None, 1):
+        content_paths = _content_addressed_v2_companion_paths(
+            source_path,
+            source_digest,
+        )
+        resumed_state, companion_path = _load_matching_v2_state(
+            content_paths,
+            source_metadata,
+        )
+        if resumed_state is None:
+            resumed_state, _ = _load_matching_v2_state(
+                (_legacy_v2_companion_path(source_path),),
+                source_metadata,
+            )
+    state = resumed_state or WizardState.from_json(data)
+    state._source_execution_identity_version = source_version
+    if source_version in (None, 1):
+        state._legacy_source_metadata = source_metadata
+        state._v2_companion_path = companion_path or _available_v2_companion_path(
+            source_path,
+            source_digest,
+        )
+    return state
+
+
+def _save_resumed_state_file(path: Path, state: WizardState) -> None:
+    """Persist native v2 state while keeping legacy resume sources read-only."""
+    if getattr(state, "_source_execution_identity_version", 2) in (None, 1):
+        payload = state.to_json()
+        payload[_LEGACY_SOURCE_FIELD] = state._legacy_source_metadata
+        write_json_atomic(state._v2_companion_path, payload)
+        return
+    save_state_file(path, state)
 
 
 def save_state_file(path: Path, state: WizardState) -> None:
-    Path(path).write_text(
-        json.dumps(state.to_json(), indent=2, ensure_ascii=False),
-        encoding="utf-8",
-    )
+    write_json_atomic(Path(path), state.to_json())
 
 
 # ---- CLI entrypoint -----------------------------------------------------
@@ -5366,6 +6748,7 @@ def _cli(argv: list[str]) -> int:
 
     if args.cmd == "step":
         state = load_state_file(state_path)
+        persisted_state = copy.deepcopy(state)
         if args.no_submit and args.answer is not None:
             print(json.dumps(
                 {"ok": False, "error": "--no-submit and --answer are mutually exclusive"},
@@ -5390,7 +6773,7 @@ def _cli(argv: list[str]) -> int:
             else:
                 result = submit(state, args.answer)
         except WizardError as exc:
-            save_state_file(state_path, state)
+            _save_resumed_state_file(state_path, persisted_state)
             try:
                 current = prompt_payload(state, next_prompt(state))
             except WizardError:
@@ -5402,7 +6785,7 @@ def _cli(argv: list[str]) -> int:
             print(json.dumps({"ok": False, "error": str(exc), "current": current},
                              ensure_ascii=False, indent=2))
             return 0
-        save_state_file(state_path, state)
+        _save_resumed_state_file(state_path, state)
         print(json.dumps({"ok": True, **result}, ensure_ascii=False, indent=2))
         return 0