okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py

@@ -41,6 +41,7 @@ _CLI_EPILOG = r"""Usage:
   okstra agent-prompt verify-completion [options]
   okstra agent-prompt record-dispatch [options]
   okstra agent-prompt link-result [options]
+  okstra agent-prompt refreeze-contracts --project-root <dir> --run-manifest <path> [--json]
 """
 
 
@@ -57,6 +58,12 @@ def _parser() -> argparse.ArgumentParser:
     _add_materialize_parser(commands)
     _add_completion_parsers(commands)
     _add_dispatch_parsers(commands)
+    operation = commands.add_parser(
+        "resolve-operation",
+        help="resolve the role, worker count and models an operation requires",
+    )
+    operation.add_argument("--operation", required=True)
+    operation.add_argument("--json", action="store_true")
     jobs = commands.add_parser("jobs", help="generate a verified jobs file without dispatching")
     _common_paths(jobs)
     jobs.add_argument("--run-manifest", required=True)
@@ -210,6 +217,15 @@ def _add_dispatch_parsers(commands: argparse._SubParsersAction) -> None:
     abandon.add_argument("--reason", required=True)
     abandon.add_argument("--json", action="store_true")
 
+    refreeze = commands.add_parser(
+        "refreeze-contracts",
+        help="re-freeze this run's duty contracts in the installed format "
+             "and stamp the manifest digest",
+    )
+    _common_paths(refreeze)
+    refreeze.add_argument("--run-manifest", required=True)
+    refreeze.add_argument("--json", action="store_true")
+
     link_result = commands.add_parser("link-result")
     _common_paths(link_result)
     link_result.add_argument("--run-manifest", required=True)
@@ -229,9 +245,99 @@ def _standalone_completion_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--json", action="store_true")
 
 
+def _refreeze_contracts(args: argparse.Namespace) -> dict[str, object]:
+    """이 run 의 계약을 설치본 형식으로 다시 동결한다. 사용자만 부른다."""
+    from ...contract_refreeze import (
+        ContractRefreezeError,
+        refreeze_run_contracts,
+    )
+    from ...paths import find_asset_root
+
+    workspace_root = find_asset_root(("prompts", "duties"), is_present=Path.is_dir)
+    if workspace_root is None:
+        raise AgentPromptCliError(
+            "agent duty catalog not found: no prompts/duties under OKSTRA_HOME "
+            "or this checkout"
+        )
+    try:
+        result = refreeze_run_contracts(
+            project_root=Path(args.project_root),
+            run_manifest_path=Path(args.run_manifest),
+            workspace_root=workspace_root,
+        )
+    except ContractRefreezeError as exc:
+        raise AgentPromptCliError(str(exc)) from exc
+    return {
+        "dutyRoot": result.duty_root,
+        "digest": result.digest,
+        "previousDigest": result.previous_digest,
+        "formatVersion": result.format_version,
+        "previousFormatVersion": result.previous_format_version,
+        "changed": result.changed,
+    }
+
+
+def _resolve_operation(operation_id: str) -> dict[str, object]:
+    """이 작업이 열 칸과 각 칸의 모델. 기술은 작업 이름만 알면 된다."""
+    from ...model_pool import ModelPool
+    from ...operation_invocation import (
+        OperationPreparationError,
+        resolve_operation_slots,
+    )
+    from ...paths import find_asset_root
+    from ...registry.provider_registry import default_provider_registry
+
+    root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
+    if root is None:
+        raise AgentPromptCliError(
+            "operation contracts not found: no agents/operations under "
+            "OKSTRA_HOME or this checkout"
+        )
+    try:
+        slots = resolve_operation_slots(
+            operation_id,
+            contract_root=root,
+            pool=ModelPool.from_registry(default_provider_registry()),
+        )
+    except OperationPreparationError as exc:
+        raise AgentPromptCliError(str(exc)) from exc
+    return {
+        "operation": operation_id,
+        "dutyId": slots[0].duty_id,
+        "roleId": slots[0].role_id,
+        "count": len(slots),
+        "slots": [
+            {
+                "ordinal": slot.ordinal,
+                "provider": slot.provider_id,
+                "modelRef": slot.model_ref,
+                "model": slot.display_name,
+            }
+            for slot in slots
+        ],
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     try:
         args = _parser().parse_args(argv)
+        if args.command == "resolve-operation":
+            payload = _resolve_operation(args.operation)
+            if args.json:
+                _emit(payload, True)
+            else:
+                # 기본 출력은 고정 텍스트다. 기술 본문이 모델에게 okstra 소유
+                # JSON 을 읽으라고 지시하면 그 해석이 곧 두 번째 파서가 된다.
+                print(f"operation: {payload['operation']}")
+                print(f"duty: {payload['dutyId']}")
+                print(f"role: {payload['roleId']}")
+                print(f"workers: {payload['count']}")
+                for slot in payload["slots"]:
+                    print(
+                        f"  slot {slot['ordinal']}: "
+                        f"provider={slot['provider']} model={slot['modelRef']}"
+                    )
+            return 0
         if args.command == "jobs":
             payload = generate_jobs(args)
             if args.json:
@@ -277,6 +383,20 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "verify-completion":
             _verify_completion(args)
             return 0
+        if args.command == "refreeze-contracts":
+            payload = _refreeze_contracts(args)
+            if args.json:
+                _emit(payload, True)
+            else:
+                print(f"duty root: {payload['dutyRoot']}")
+                print(f"catalog digest: {payload['digest']}")
+                print(
+                    "contract format: "
+                    f"{payload['previousFormatVersion']} -> {payload['formatVersion']}"
+                    if payload["changed"]
+                    else "contract format: already current"
+                )
+            return 0
         if args.command == "record-dispatch":
             _record_dispatch(args)
             return 0

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -41,6 +41,16 @@ from ...worker_prompt_policy import (
     is_verification_dispatch_kind,
 )
 from ...paths import okstra_home
+from ...contract_refreeze import (
+    CONTRACT_FORMAT_VERSION,
+    frozen_format_version,
+    refreeze_message,
+)
+from ...initial_prompt_materialization import (
+    InitialPromptMaterializationError,
+    implementation_anchor_lines,
+    required_resource_block,
+)
 from ...final_report_paths import final_report_data_path
 from ...final_report_schema import load_schema_version
 from ...report_inputs import report_narrative_path, uses_report_contract_v3
@@ -300,6 +310,12 @@ def _materialize_run(
         must_exist=True,
     )
     if contract.get("catalogDigest") != digest_duty_catalog(duty_root):
+        # 형식이 바뀐 릴리스를 설치하면 옛 run 의 다이제스트는 영영 맞지 않는다.
+        # "다이제스트 불일치" 만 말하면 읽는 쪽은 파일이 변조된 줄 알고 그 자리를
+        # 뒤진다 — 실측 2026-09-23: 한 세션이 dispatch-kind 별 분기를 찾다가
+        # 멈췄고, 원인은 그 사이에 일어난 설치였다.
+        if frozen_format_version(contract) != CONTRACT_FORMAT_VERSION:
+            raise AgentPromptCliError(refreeze_message(str(duty_root)))
         raise AgentPromptCliError("run duty snapshot catalog digest does not match")
     active_context_path = _project_manifest_path(
         project_root,
@@ -357,6 +373,13 @@ def _materialize_run(
             "--corrections requires report contract 3.0 (a Markdown narrative); "
             "this run uses an older contract"
         )
+    if args.audience in _RESOURCE_AUDIENCES and not is_reverify:
+        anchor_lines = anchor_lines + tuple(
+            _implementation_anchors(project_root, manifest_path, args.worker_id)
+        )
+        body = _with_required_resources(
+            project_root, manifest_path, args.worker_id, body
+        )
     request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
         worker_id=args.worker_id if identity is None else None,
@@ -410,6 +433,62 @@ def _materialize_run(
     return prepare_agent_invocation(request)
 
 
+# 디스패치 composer 가 필수 자원 블록을 싣는 audience. 이 명령으로 먼저 발행된
+# 프롬프트는 디스패치가 그대로 쓰므로, 블록을 여기서 붙이지 않으면 워커에 닿지 않는다.
+_RESOURCE_AUDIENCES = frozenset({"implementation-executor", "implementation-verifier"})
+
+
+def _implementation_anchors(
+    project_root: Path, manifest_path: Path, worker_id: str,
+) -> list[str]:
+    """디스패치 composer 와 같은 구현 앵커 줄."""
+    try:
+        return implementation_anchor_lines(
+            project_root=project_root,
+            run_manifest_path=manifest_path,
+            runtime_root=_runtime_root(),
+            worker_id=worker_id,
+        )
+    except InitialPromptMaterializationError as exc:
+        raise AgentPromptCliError(f"implementation prompt anchors: {exc}") from exc
+
+
+def _runtime_root() -> Path:
+    from ...paths import find_asset_root
+
+    root = find_asset_root(("prompts", "profiles"), is_present=Path.is_dir)
+    if root is None:
+        raise AgentPromptCliError(
+            "prompt profiles not found: no prompts/profiles under OKSTRA_HOME "
+            "or this checkout"
+        )
+    return root
+
+
+def _with_required_resources(
+    project_root: Path, manifest_path: Path, worker_id: str, body: str,
+) -> str:
+    """리드의 지시문 뒤에 composer 와 같은 필수 자원 블록을 붙인다.
+
+    executor 의 BLOCKING 게이트 세 본문, verifier 의 `_implementation-verifier.md`
+    (self-mock 검출기 호출문 포함), clarification 권한 블록, fix-run carry 다.
+    배송 방식(eager / lazy)은 run 매니페스트의 선언을 따른다.
+    """
+    runtime_root = _runtime_root()
+    try:
+        block = required_resource_block(
+            project_root=project_root,
+            run_manifest_path=manifest_path,
+            runtime_root=runtime_root,
+            worker_id=worker_id,
+        )
+    except InitialPromptMaterializationError as exc:
+        raise AgentPromptCliError(f"required prompt resources: {exc}") from exc
+    if not block:
+        return body
+    return body.rstrip() + "\n\n" + block + "\n"
+
+
 def _complete_run_reverify_body(
     args: argparse.Namespace, manifest: Mapping[str, Any],
     active_context: Mapping[str, Any], assignment: AgentModelAssignment,
@@ -956,17 +1035,43 @@ def _snapshot_standalone_duties(destination: Path) -> None:
             "OKSTRA_HOME or this checkout"
         )
     source = root.joinpath(*duties_relative)
+    # 공통 계약은 직무가 아니라 `agents/` 가 소유한다(ADR-0017). 동결본은 한
+    # 뿌리여야 하므로 여기서 함께 싣는다.
+    common_root = find_asset_root(("agents", "common.json"), is_present=Path.is_file)
+    if common_root is None:
+        raise AgentPromptCliError(
+            "agent common contract not found: no agents/common.json under "
+            "OKSTRA_HOME or this checkout"
+        )
+    common_source = common_root / "agents" / "common.json"
+
+    def _staged_digest() -> str:
+        staged = Path(tempfile.mkdtemp(prefix=".okstra-standalone-duties."))
+        try:
+            shutil.copytree(source, staged, dirs_exist_ok=True)
+            shutil.copyfile(common_source, staged / "common.json")
+            shutil.copytree(
+                common_source.parent / "roles", staged / "roles", dirs_exist_ok=True
+            )
+            return digest_duty_catalog(staged)
+        finally:
+            shutil.rmtree(staged, ignore_errors=True)
+
     if destination.exists():
-        if not destination.is_dir() or digest_duty_catalog(destination) != digest_duty_catalog(source):
+        if not destination.is_dir() or digest_duty_catalog(destination) != _staged_digest():
             raise AgentPromptCliError("standalone duty snapshot conflicts with existing files")
         return
     temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}.", dir=destination.parent))
     try:
         shutil.copytree(source, temporary, dirs_exist_ok=True)
+        shutil.copyfile(common_source, temporary / "common.json")
+        shutil.copytree(
+            common_source.parent / "roles", temporary / "roles", dirs_exist_ok=True
+        )
         try:
             os.rename(temporary, destination)
         except FileExistsError:
-            if digest_duty_catalog(destination) != digest_duty_catalog(source):
+            if digest_duty_catalog(destination) != _staged_digest():
                 raise AgentPromptCliError("standalone duty snapshot publication conflict")
     finally:
         if temporary.exists():

package/runtime/python/okstra_ctl/agent/prompt_cli/run_identity.py

@@ -58,56 +58,7 @@ def _validate_run_identity(
             ).duty_audience
         except ValueError as exc:
             raise AgentPromptCliError(str(exc)) from exc
-        if audience != expected and _manifest_issued_role_execution(
-            manifest, audience=audience, assignment_ref=assignment_ref
-        ):
-            # The prompt plan names a worker's role by worker id, so on an
-            # implementation run the executor's provider resolves to the
-            # executor role no matter which role execution is being targeted.
-            # But the manifest issues one role execution per role, and a
-            # provider serving as both executor and verifier gets two — a
-            # normal roster, since the verifier contract accepts reusing the
-            # executor's model behind its own session. Refusing the second
-            # audience made a role execution okstra had itself issued
-            # undispatchable, which costs the run an independent verifier.
-            expected = audience
     if audience != expected:
         raise AgentPromptCliError(
             f"audience {audience!r} does not match required audience {expected!r}"
         )
-
-
-def _manifest_issued_role_execution(
-    manifest: Mapping[str, Any],
-    *,
-    audience: str,
-    assignment_ref: str,
-) -> bool:
-    """Whether this run issued a role execution for that audience's role.
-
-    Keyed on the manifest's own rows, not on what the prompt plan infers from
-    a worker id: the question is whether okstra created the execution being
-    targeted, and only the manifest answers that.
-    """
-    from ...domain.role import RoleCatalogError, role_for_duty
-
-    try:
-        role = role_for_duty(audience)
-    except RoleCatalogError:
-        return False
-    assignments = manifest.get("invocationAssignments")
-    assignment = (
-        assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
-    )
-    provider = (
-        assignment.get("provider") if isinstance(assignment, Mapping) else None
-    )
-    if not provider:
-        return False
-    executions = manifest.get("roleExecutions")
-    return any(
-        isinstance(row, Mapping)
-        and row.get("role") == role
-        and row.get("provider") == provider
-        for row in (executions if isinstance(executions, list) else [])
-    )

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -500,7 +500,10 @@ def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
         "in it is taken. Never reuse or renumber one: a new stage takes the",
         "next number after the highest listed here, and reworking a completed",
         "stage means cancelling it and adding a new number, never editing it",
-        "in place. `sourcePlan` is the plan the completed stages were built",
+        "in place. The new plan declares every stage listed here as well as the",
+        "ones it adds — its rows run 1..N with no gap — because a plan whose",
+        "rows start above 1 is refused by every consumer that parses a Stage",
+        "Map. `sourcePlan` is the plan the completed stages were built",
         "against; `latestPlan` is the plan this list came from. When the two",
         "differ, the completed work followed the former and the numbering",
         "authority is the latter.",

package/runtime/python/okstra_ctl/application/open_worker.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
+from dataclasses import replace
 
 from ..domain.worker_runtime import (
     EnvironmentBlocked,
@@ -19,11 +20,15 @@ def open_worker(
     last_unavailable: SurfaceUnavailable | None = None
     for port in chain:
         try:
-            return port.spawn(request_for(port.surface))
+            handle = port.spawn(request_for(port.surface))
         except EnvironmentBlocked:
             raise
         except SurfaceUnavailable as exc:
             last_unavailable = exc
+            continue
+        if last_unavailable is None:
+            return handle
+        return replace(handle, fallback_reason=str(last_unavailable))
     if last_unavailable is None:
         raise SurfaceUnavailable("runtime chain is empty")
     raise last_unavailable

package/runtime/python/okstra_ctl/assignment_resolver.py

@@ -30,7 +30,7 @@ from .ports.host_model import (
     HostModelBindingPort,
     HostModelBindingRequest,
 )
-from .role_requirements import RoleProfile, RoleRequirement
+from .role_requirements import RoleProfile, RoleRequirement, StaticRoleRequirement
 
 
 TerminalBackend = Literal[
@@ -239,8 +239,17 @@ def resolve_model_assignment(
     host: HostSessionContext,
     environment: AssignmentEnvironment,
     entry_mode: Literal["current-session", "new-session"] = "new-session",
+    require_selectable: bool = True,
 ) -> ResolvedAssignment:
-    """Resolve one canonical model through the selected host execution path."""
+    """Resolve one canonical model through the selected host execution path.
+
+    `require_selectable=False` re-resolves a binding a run already recorded.
+    Selectability decides what a user may pick now; a run that picked a model
+    before it left the picker still has to finish. 실측 2026-09-23
+    (fontradar-v2-api dev-10860 implementation-planning-002): `gpt-5.6-sol` 이
+    카탈로그에서 목록 제외로 바뀌자, 그 모델로 이미 세 라운드를 돈 run 의 다음
+    디스패치가 `model binding changed: ... not-selectable` 로 막혔다.
+    """
     _validate_environment(host, environment)
     model = pool.resolve(model_ref)
     availability = pool.availability(
@@ -249,7 +258,9 @@ def resolve_model_assignment(
         host.host_id,
         entry_mode,
     )
-    if not availability.available:
+    if not availability.available and (
+        require_selectable or availability.reason != "not-selectable"
+    ):
         raise AssignmentResolutionError(
             f"model {model_ref!r} is unavailable: {availability.reason}"
         )
@@ -326,8 +337,8 @@ def resolve_model_selection(
     return selected
 
 
-def _static_requirements(profile: RoleProfile) -> tuple[RoleRequirement, ...]:
-    leader = RoleRequirement("leader", 1, 1, 1, "lead")
+def _static_requirements(profile: RoleProfile) -> tuple[StaticRoleRequirement, ...]:
+    leader = StaticRoleRequirement("leader", 1, 1, 1, "lead")
     return (leader, *(row for row in profile.roles if not row.dynamic))
 
 

package/runtime/python/okstra_ctl/cmux.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import shlex
 import shutil
 import socket
@@ -72,6 +73,10 @@ SOCKET_UNREACHABLE = "unreachable"
 
 SOCKET_PROBE_TIMEOUT_SECONDS = 2
 
+# cmux 가 돌려주는 식별자가 UUID 인지 ref 인지 가리는 자리. ref 는 번호가 다시
+# 매겨지므로 원장에 남길 수 없다.
+_UUID_PATTERN = re.compile(r"[0-9A-Fa-f]{8}(?:-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}")
+
 
 def cmux_cli_path() -> str:
     """Absolute path to the cmux CLI, or "" when cmux is not installed.
@@ -455,7 +460,11 @@ def spawn_worker_surface(
         owned_surface_ids=owned_surface_ids,
     )
     target = _pane_by_id(panes, placement.pane_id)
-    surface_uuid = _open_worker_surface(workspace, placement, target)
+    try:
+        surface_uuid = _create_surface(workspace, placement, target)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        _restore_lead_after_failed_spawn(workspace, owned_surface_ids)
+        raise
     try:
         renamed = rename_surface(surface_uuid, title)
         if renamed.returncode != 0:
@@ -475,10 +484,35 @@ def spawn_worker_surface(
             raise RuntimeError(
                 f"{exc}; cleanup failed for cmux surface {surface_uuid}: {cleanup_error}"
             ) from exc
+        finally:
+            _restore_lead_after_failed_spawn(workspace, owned_surface_ids)
         raise
     return surface_uuid
 
 
+def _restore_lead_after_failed_spawn(
+    workspace: str, owned_surface_ids: Collection[str]
+) -> None:
+    """실패한 분할이 리드에서 떼어 간 폭을 돌려준다.
+
+    폭을 되돌리는 자리는 창이 열린 뒤의 `_size_lead_pane` 하나뿐이었다. 실패한
+    시도는 리드에서 폭만 떼어 가고 끝났고, 실패가 반복되면 축소가 누적된다 —
+    실측 2026-09-21, jobs dev-10860: 강등 7건 뒤 리드가 64칼럼에서 14칼럼.
+
+    닫지 못한 창의 폭까지 되찾지는 않는다. 그 창은 `lead_target_width` 에서
+    남의 창으로 셈해져 usable 에서 빠지고, 리드는 남은 공간에서 제 몫을 가져
+    간다. 되찾으려면 okstra 가 자기 것이라 증명하지 못한 창의 경계를 미는
+    셈이라 그쪽이 더 나쁘다.
+
+    크기 조정이 실패해도 삼킨다: 호출자는 창을 열지 못한 사유를 들고 올라가는
+    중이고, 원장에 남아야 할 문장은 그쪽이다.
+    """
+    try:
+        _size_lead_pane(workspace, owned_surface_ids)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return
+
+
 def rename_surface(surface: str, title: str) -> subprocess.CompletedProcess[str]:
     """Set the tab title cmux shows for one surface.
 
@@ -686,27 +720,14 @@ def rpc(method: str, params: dict[str, Any]) -> dict[str, Any]:
     return payload if isinstance(payload, dict) else {}
 
 
-def _open_worker_surface(
-    workspace: str, placement: Placement, target: PaneGeometry
-) -> str:
-    before = open_surface_ids(workspace)
-    _create_surface(workspace, placement, target)
-    new_ids = open_surface_ids(workspace) - before
-    if len(new_ids) != 1:
-        raise RuntimeError(
-            f"cmux opened {len(new_ids)} surfaces where exactly one was expected"
-        )
-    return new_ids.pop()
-
-
 def open_surface_ids(workspace: str) -> set[str]:
     """Every surface UUID the workspace currently holds.
 
-    Dispatch diffs this set across a create to identify the new surface, rather
-    than translating the `OK surface:N` echo, because `list-pane-surfaces`
-    reports only the focused pane unless given a `--pane`, and the new pane is
-    not focused. Teardown intersects its recorded ids with it to tell a surface
-    that is still open from one that closed earlier in the run.
+    Teardown intersects its recorded ids with this set to tell a surface that is
+    still open from one that closed earlier in the run. It is teardown's only
+    caller: dispatch used to diff this set across a create to name the surface
+    it had just opened, and that is now `new-split --id-format uuids`, which
+    says the uuid outright.
     """
     return {
         surface_id
@@ -717,9 +738,22 @@ def open_surface_ids(workspace: str) -> set[str]:
 
 def _create_surface(
     workspace: str, placement: Placement, target: PaneGeometry
-) -> None:
+) -> str:
+    """새 창을 열고 그 표면의 UUID 를 준다.
+
+    UUID 는 cmux 가 스스로 말해 준다. `--id-format uuids` 를 주면 이 명령의 출력이
+    `OK <surface-uuid> <workspace-uuid>` 가 되고, 그 첫 UUID 가 새 창의 표면이다
+    (실측 2026-09-21, 폐기용 워크스페이스 1회 분할: echo 의 UUID 가 직후
+    `pane.list` 가 보여 준 새 창의 `surface_ids[0]` 과 같았다).
+
+    앞서는 분할 전후의 표면 목록 차집합으로 알아냈는데, 그 차집합이 실제 run 에서
+    여덟 번 중 여덟 번 비어 워커가 창에 붙지 못하고 빈 창만 남았다. 자기가 만든 것의
+    이름을 만든 쪽에 묻는 편이 두 번 읽어 비교하는 것보다 틀릴 자리가 적다.
+    """
     created = run_cmux(
         [
+            "--id-format",
+            "uuids",
             "new-split",
             placement.direction,
             "--workspace",
@@ -730,6 +764,21 @@ def _create_surface(
     )
     if created.returncode != 0:
         raise RuntimeError(created.stderr.strip() or "cmux could not open a pane")
+    return _surface_from_split_echo(created.stdout)
+
+
+def _surface_from_split_echo(stdout: str) -> str:
+    """`new-split` 의 출력에서 새 표면 UUID 만 꺼낸다.
+
+    ref(`surface:2`)는 받지 않는다. okstra 가 기록하고 나중에 닫는 이름이라, cmux 가
+    창을 여닫을 때마다 번호를 다시 매기는 ref 로는 엉뚱한 창을 닫게 된다.
+    """
+    parts = stdout.split()
+    if len(parts) >= 2 and parts[0] == "OK" and _UUID_PATTERN.fullmatch(parts[1]):
+        return parts[1]
+    raise RuntimeError(
+        f"cmux did not name the pane it opened: {stdout.strip()!r}"
+    )
 
 
 def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> None:

package/runtime/python/okstra_ctl/code_review_target.py

@@ -99,13 +99,13 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
 
 
 _CLI_EPILOG = r"""Usage:
-  okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] --json
+  okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
   okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
 
 Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
-reviewPath, round }. Stage mode reads the base commit from the stage
-registry row; branch mode falls back to the merge-base with the default
-branch. An empty worktreePath means the review reads the branch ref
+reviewPath, round }. `--base` sets the base in either mode. Without it, stage
+mode reads the base commit from the stage registry row and branch mode falls
+back to the merge-base with the default branch. An empty worktreePath means the review reads the branch ref
 instead of a checked-out tree. This is read-only — it never creates
 directories or files.
 """
@@ -124,7 +124,10 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
     parser.add_argument("--stage", type=int, default=0, help="stage number to review")
     parser.add_argument("--branch", default="", help="branch to review")
-    parser.add_argument("--base", default="", help="explicit base ref for branch mode")
+    parser.add_argument(
+        "--base", default="",
+        help="explicit base ref; overrides the stage registry base or the branch merge-base",
+    )
     parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
     parser.add_argument("--project-root", default="", help="explicit project root")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -138,7 +141,9 @@ def _resolve(args: argparse.Namespace, project_root: Path) -> dict:
     if args.task_key:
         if args.stage < 1:
             raise StateError("--task-key needs --stage <N>, N >= 1", stage="args")
-        return code_review_target_snapshot(project_root, args.task_key, args.stage)
+        return code_review_target_snapshot(
+            project_root, args.task_key, args.stage, base=args.base
+        )
     if args.branch:
         return _branch_snapshot(
             project_root, args.branch, args.base, _review_date(args.date)
@@ -204,7 +209,7 @@ def main(argv: list[str] | None = None) -> int:
 # 것으로 합쳐진다.
 
 def code_review_target_snapshot(
-    project_root: Path, task_key: str, stage: int
+    project_root: Path, task_key: str, stage: int, *, base: str = ""
 ) -> dict:
     """stage 코드 리뷰가 무엇을 읽고 결과를 어디에 쓰는지 해소한다.
 
@@ -218,6 +223,9 @@ def code_review_target_snapshot(
     표류한다: 다중의존 stage 는 오늘의 task-key worktree HEAD 를 받게 되어
     whole-task final-verification 이 stage 들을 병합한 뒤에는 base..head 구간이
     비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
+
+    `base` 가 주어지면 그 값을 쓴다 — 스킬이 기록된 base 를 보여 주고 사용자가
+    다른 ref 를 고른 경우다. 무시하면 사용자가 거부한 범위로 리뷰가 진행된다.
     """
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
@@ -241,7 +249,7 @@ def code_review_target_snapshot(
     coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
     stage_row = worktree_registry.get_stage_row(*coords, stage) or {}
     worktree_view = _stage_worktree_view(project_root, stage_row, stage)
-    base_commit = stage_row.get("base_ref") or _legacy_stage_base_commit(
+    base_commit = base or stage_row.get("base_ref") or _legacy_stage_base_commit(
         identity, stages, selected
     )
     review_path, round_no = code_review_paths.next_stage_review(