okstra 0.172.0 → 0.174.0

package/runtime/python/okstra_ctl/session.py

@@ -1,21 +1,22 @@
 """Claude session helpers.
 
-bash session.sh 의 python 구현. claude session id 생성, resume command
-파일 작성.
+bash session.sh 의 python 구현. lead claude 세션 관측, resume command
+파일 작성. 세션 id 발급기는 워커 dispatch 도 쓰므로
+`dispatch_state.generate_claude_session_id` 에 있다.
 """
 from __future__ import annotations
 
 import json
 import os
-import uuid
 from pathlib import Path
+from typing import Collection
 
-from .dispatch_state import DispatchError, mutate_team_state
-
-
-def generate_claude_session_id() -> str:
-    """UUIDv4 문자열."""
-    return str(uuid.uuid4())
+from .dispatch_state import (
+    DispatchError,
+    load_json_object,
+    mutate_team_state,
+    worker_session_ids,
+)
 
 
 def _claude_projects_dir_for(cwd: Path) -> Path:
@@ -76,7 +77,11 @@ def _session_mentions(jsonl_path: Path, needle: str) -> bool:
         return False
 
 
-def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
+def resolve_lead_session_id_for_run(
+    project_root: Path,
+    run_dir: Path,
+    exclude_session_ids: Collection[str] = (),
+) -> str:
     """`run_dir` 를 다룬 lead 세션 중 가장 최근 수정된 것의 id, 없으면 ''.
 
     프로젝트 디렉토리의 최신 jsonl 을 그대로 집으면(``resolve_inproc_lead_session_id``)
@@ -84,6 +89,12 @@ def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
     (dev-10172): 남의 세션이 `leadSessionIds` 에 들어가 run 비용이 $80 → $207 로
     부풀고, 그 세션의 PROGRESS 라인이 conformance 스캔에 섞여 오탐을 냈다.
     자기 run 의 산출물 경로를 언급한 세션만 후보로 인정해 그 오염을 막는다.
+
+    `exclude_session_ids` 는 같은 run **안**의 오염을 막는다. cmux 워커는
+    `agentName` 을 안 남겨 아래 필터를 통과하고, 워커 세션도 자기 run 의 산출물
+    경로를 언급하므로 needle 에도 걸린다. 워커가 리드보다 늦게 끝나면 mtime
+    정렬에서 먼저 잡혀 워커 세션이 리드로 기록된다 — dispatch 가 발급한 id 를
+    호출자가 넘겨 그 세션들을 후보에서 뺀다.
     """
     proj_dir = _claude_projects_dir_for(project_root)
     try:
@@ -91,7 +102,10 @@ def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
     except OSError:
         return ""
     needle = str(run_dir)
+    excluded = set(exclude_session_ids)
     for path in sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True):
+        if path.stem in excluded:
+            continue
         if _session_has_agent_name(path):
             continue
         if _session_mentions(path, needle):
@@ -103,17 +117,36 @@ def record_observed_lead_session(project_root: Path, team_state_path: Path) -> s
     """이 run 의 live lead 세션을 관측해 team-state 에 append(멱등). 이 run 을
     다룬 lead 세션을 못 찾거나 중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이
     여기에 모은다.
+
+    후보에서 뺄 워커 세션 id 는 append 대상인 team-state 자체가 들고 있다 —
+    dispatch 가 `workerDispatches[].sessionId` 에 적어 둔 값이라, 관측 시점에
+    이 run 이 연 워커 세션의 목록은 그 파일 하나로 완결된다.
     """
-    sid = resolve_lead_session_id_for_run(project_root, team_state_path.parent.parent)
+    try:
+        team_state = load_json_object(team_state_path, "team-state")
+    except (DispatchError, OSError):
+        team_state = {}
+    sid = resolve_lead_session_id_for_run(
+        project_root,
+        team_state_path.parent.parent,
+        exclude_session_ids=worker_session_ids(team_state),
+    )
     if not sid:
         return ""
     def add_observed_session(state: dict) -> bool:
         lead_ids = state.setdefault("leadSessionIds", [])
+        observed = state.setdefault("observedTeamNames", [])
+        # 두 키가 list 가 아니면 `sid in None` 이 TypeError 를, `str.append` 가
+        # AttributeError 를 낸다. 그 예외는 아래 `(DispatchError, OSError)` 도
+        # `observe_lead_session` 의 `OSError` 도 통과해 dispatch 를 죽인다 —
+        # 관측이 호출자를 깨뜨리지 않는다는 계약을 docstring 이 아니라 여기서
+        # 지킨다. 관측을 건너뛰면 이 run 은 관측 이전과 같은 상태로 남는다.
+        if not isinstance(lead_ids, list) or not isinstance(observed, list):
+            return False
         if sid in lead_ids:
             return False
         lead_ids.append(sid)
         team = f"session-{sid[:8]}"
-        observed = state.setdefault("observedTeamNames", [])
         if team not in observed:
             observed.append(team)
         return True
@@ -125,6 +158,30 @@ def record_observed_lead_session(project_root: Path, team_state_path: Path) -> s
     return sid if changed else ""
 
 
+def observe_lead_session(project_root: Path, team_state_path: Path) -> None:
+    """단계 경계에서 부르는 부수효과 — 관측 실패를 호출자에게 내지 않는다.
+
+    리드 세션은 resume·compaction 으로 세대가 갈리므로 prepare 때 적힌 단 하나의
+    id 는 런 구간에 레코드가 없는 죽은 세션을 가리킬 수 있다. 리드가 반드시
+    지나가는 지점마다 관측해 `leadSessionIds` 에 세대를 모은다 — 리드의 협조를
+    요구하지 않는 것이 요점이다.
+
+    잡는 범위가 OSError 뿐인 이유: 이 아래 호출들이 각자 자기 실패를 흡수하고,
+    그러고도 밖으로 나오는 것이 후보 정렬의 `p.stat()` 이다 — 스캔 도중 세션
+    jsonl 이 사라지면 여기서 OSError 가 난다. team-state 읽기·쓰기
+    (`load_json_object` / `mutate_team_state`)와 세션 본문 스캔이 그 흡수
+    지점이고, 비정상 team-state 가 낼 TypeError/AttributeError 는 잡는 대신 아예
+    내지 않는 쪽으로 막는다 — append 대상 키(`leadSessionIds` /
+    `observedTeamNames`)는 `add_observed_session` 이, 제외 집합의 출처
+    (`workerDispatches`)는 `worker_session_ids` 가 각각 비-list 를 걸러낸다.
+    더 넓게 잡으면 team-state 를 깨뜨리는 진짜 버그까지 조용히 삼킨다.
+    """
+    try:
+        record_observed_lead_session(project_root, team_state_path)
+    except OSError:
+        return
+
+
 def write_claude_resume_command_file(
     *,
     resume_command_path: Path,

package/runtime/python/okstra_ctl/team.py

@@ -1,9 +1,9 @@
 """Neutral okstra team CLI for pane-backed worker dispatch.
 
-Outside cmux this is the door onto tmux panes for hosts whose descriptor owns
-the team lifecycle. Under cmux it is every lead's door onto cmux surfaces,
-because okstra owns the panes there rather than the host. Which backend a run
-uses is read from its run manifest.
+Under cmux this is every lead's door onto cmux surfaces, because okstra owns the
+panes there rather than the host. Outside cmux a worker owns no pane at all — it
+runs as a cli-wrapper subprocess — so there is nothing for teardown to reclaim.
+Which backend a run uses is read from its run manifest.
 """
 from __future__ import annotations
 
@@ -15,14 +15,13 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import cmux
-from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
 from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON, mutate_team_state
 from .dispatch_core import (
+    BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
-    BACKEND_TMUX_PANE,
     DispatchError,
     DispatchPlan,
     await_dispatches,
@@ -31,6 +30,7 @@ from .dispatch_core import (
 from .ports.worker_dispatch import WorkerDispatchRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
+from .session import observe_lead_session
 
 
 _SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
@@ -100,6 +100,7 @@ def _dispatch(args) -> int:
     if args.jobs_file and args.workers:
         raise DispatchError("--jobs-file and --workers cannot be combined")
     manifest = _load_manifest(args.project_root, args.run_manifest)
+    _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
     terminal_backend = _manifest_backend(manifest)
     lead_runtime = _require_string(manifest, "leadRuntime")
     fallback_port = default_host_registry().resolve(
@@ -137,6 +138,7 @@ def _dispatch(args) -> int:
 def _await(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
     _validate_team_manifest(manifest)
+    _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
     plan = _plan_for_existing(Path(args.project_root), Path(args.workspace_root), Path(args.run_manifest), manifest)
     code = await_dispatches(
         plan,
@@ -157,21 +159,46 @@ def _teardown(args) -> int:
     project_root = Path(args.project_root).resolve()
     team_state_path = _resolve_project_path(project_root, _require_string(manifest, "teamStatePath"))
     team_state = _load_json(team_state_path, "team-state")
-    run_dir = _resolve_project_path(project_root, _require_string(manifest, "runDirectoryPath"))
-    panes = _reclaimable_panes(manifest, team_state, run_dir)
+    panes = _reclaimable_panes(manifest, team_state)
     if args.dry_run:
         _emit_teardown(args.json, panes)
         return 0
-    reclaim = cmux.close_surface if _is_cmux_run(manifest) else tmux.kill_pane
-    for pane in panes:
-        reclaim(pane["paneId"])
     if _is_cmux_run(manifest):
+        for pane in panes:
+            cmux.close_surface(pane["paneId"])
         _restore_lead_width()
     _mark_teardown_errors(team_state_path)
     _emit_teardown(args.json, panes)
     return 0
 
 
+def _observe_lead_session_from_manifest(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> None:
+    """Collect this run's lead session generations at a phase boundary.
+
+    Resume and compaction split a lead across several session files, so the one
+    id written at prepare time can name a session holding no record of the run.
+    Dispatch and await are the boundaries a lead cannot route around, which is
+    why the observation hangs off them instead of a call the lead has to make.
+
+    `--dry-run` observes too, because the hook sits ahead of the dry-run return
+    on purpose: moving it behind would lose the generation a lead was on when a
+    dispatch failed. What gets appended is not a rehearsal either — that lead
+    really did cross this boundary, whatever the dispatch went on to do.
+
+    A manifest missing `teamStatePath` leaves nothing to observe into; that is
+    the command's own failure to report, not this side effect's.
+    """
+    try:
+        team_state_path = _resolve_project_path(
+            project_root, _require_string(manifest, "teamStatePath")
+        )
+    except DispatchError:
+        return
+    observe_lead_session(project_root, team_state_path)
+
+
 def _plan_for_existing(
     project_root: Path, workspace_root: Path, run_manifest_path: Path, manifest: Mapping[str, Any]
 ) -> DispatchPlan:
@@ -202,15 +229,16 @@ def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
 
 
 def _reclaimable_panes(
-    manifest: Mapping[str, Any], team_state: Mapping[str, Any], run_dir: Path
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any]
 ) -> list[dict[str, str]]:
     """Everything this run owns and may close.
 
-    Under cmux the recorded ids are the only candidates. There is no per-pane tag
-    API to sweep with, and scanning by title would be worse than nothing: cmux
-    labels its own agent surfaces with the same glyph okstra's tmux cleanup
-    treats as a teammate marker, so a sweep could close the lead. Only surfaces
-    okstra created are recorded, so only those can be closed.
+    The recorded ids are the only candidates. There is no per-pane tag API to
+    sweep with, and scanning by title would be worse than nothing: cmux labels
+    its own agent surfaces with the same glyph the harness uses for a teammate
+    pane, so a sweep could close the lead. Only surfaces okstra created are
+    recorded, so only those can be closed. A cli-wrapper run records no surface
+    at all, which is why it reclaims nothing.
     """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
@@ -219,17 +247,15 @@ def _reclaimable_panes(
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
     if _is_cmux_run(manifest):
         return _still_open_surfaces(panes)
-    lead_pane = tmux.resolve_caller_pane()
-    for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
-        _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
 
 
 def _still_open_surfaces(panes: list[dict[str, str]]) -> list[dict[str, str]]:
     """The recorded surfaces cmux still shows.
 
-    `workerDispatches` is append-only and nothing prunes it, so a surface closed
-    at an earlier round boundary stays recorded for the rest of the run. Taking
+    Nothing prunes `workerDispatches` — a repeat of one `dispatchId` replaces
+    that row in place, and no row is ever dropped — so a surface closed at an
+    earlier round boundary stays recorded for the rest of the run. Taking
     the ledger as the residual set makes the run-end cleanup gate offer to close
     panes that left the screen rounds ago, on a workspace holding none.
 
@@ -294,10 +320,10 @@ def _manifest_backend(manifest: Mapping[str, Any]) -> str:
     """The backend prepare recorded for this run.
 
     Deliberately not a flag on this command: the manifest already answers it,
-    and a flag would be a second answer free to disagree. A manifest written
-    before the field existed reads as tmux, which is what those runs used.
+    and a flag would be a second answer free to disagree. A manifest with no
+    recorded backend reads as cli-wrapper, the pane-less path.
     """
-    return str(manifest.get("terminalBackend") or "") or BACKEND_TMUX_PANE
+    return str(manifest.get("terminalBackend") or "") or BACKEND_CLI_WRAPPER
 
 
 def _is_cmux_run(manifest: Mapping[str, Any]) -> bool:

package/runtime/python/okstra_ctl/tmux.py

@@ -1,39 +1,32 @@
-"""tmux command helpers for okstra-owned panes."""
+"""tmux command helpers for okstra-owned container and rerun sessions.
+
+Worker dispatch does not come through here. Workers land in a cmux surface or,
+outside cmux, in a cli-wrapper subprocess — neither owns a tmux pane. What is
+left is the two places that use tmux purely as a way to hold a long-lived
+background process: the container watcher/tail panes and `cmd-rerun.sh`'s
+detached spawn.
+"""
 from __future__ import annotations
 
-import os
 import shlex
 import shutil
 import subprocess
-from dataclasses import dataclass
-from pathlib import Path
 from typing import Optional, Sequence
 
 
-# container watcher/tail pane 전용 태그. SessionEnd `--reap`
-# (scripts/okstra-trace-cleanup.sh `_tag_in_scope`)는 `@okstra_trace_run` /
-# `@okstra_worker_run` 만 스캔하므로, 이 태그가 붙은 pane 은 세션 종료 후에도
-# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식의 핵심.
+# container watcher/tail pane 전용 태그. 이 태그가 붙은 pane 은 세션 종료 후에도
+# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식이다. 예전에는 SessionEnd 의
+# `okstra-trace-cleanup.sh --reap` 이 다른 태그만 스캔한다는 사실이 그 생존을
+# 지탱했지만, 지금은 그 모드와 훅 자체가 없어 pane 을 세션 경계에서 회수하는
+# 주체가 아예 없다. 회수는 `down` / `stop-watcher` 의 스코프 reap 뿐이다.
 CONTAINER_TAG_OPTION = "@okstra_container_run"
 
 
-@dataclass(frozen=True)
-class TmuxPane:
-    pane_id: str
-    title: str
-    run_dir: str
-    kind: str
-
-
 def _shell_quote(s: str) -> str:
     """POSIX shell 안전 인용. shlex.quote 가 모든 메타문자를 처리한다."""
     return shlex.quote(s)
 
 
-def _canonical_run_dir(run_dir: Path) -> str:
-    return str(run_dir.resolve())
-
-
 def build_tmux_command(*, session_name: str, cwd: str, run_seq: int,
                        argv: list, okstra_script: str,
                        extra_env: Optional[dict] = None) -> list:
@@ -69,79 +62,6 @@ def run_tmux(
     )
 
 
-def resolve_caller_pane(start_pid: int | None = None) -> str:
-    try:
-        panes = run_tmux(["list-panes", "-a", "-F", "#{pane_pid} #{pane_id}"])
-    except (OSError, subprocess.SubprocessError):
-        return ""
-    if panes.returncode != 0 or not panes.stdout.strip():
-        return ""
-    pane_by_pid = _pane_ids_by_pid(panes.stdout)
-    pid = str(start_pid or os.getpid())
-    for _ in range(16):
-        if not pid or pid == "0":
-            return ""
-        if pid in pane_by_pid:
-            return pane_by_pid[pid]
-        pid = _parent_pid(pid)
-    return ""
-
-
-def _pane_ids_by_pid(output: str) -> dict[str, str]:
-    result: dict[str, str] = {}
-    for line in output.splitlines():
-        parts = line.split(maxsplit=1)
-        if len(parts) == 2:
-            result[parts[0]] = parts[1]
-    return result
-
-
-def _parent_pid(pid: str) -> str:
-    try:
-        result = subprocess.run(
-            ["ps", "-o", "ppid=", "-p", pid],
-            capture_output=True,
-            text=True,
-            timeout=3,
-            check=False,
-        )
-    except (OSError, subprocess.SubprocessError):
-        return ""
-    if result.returncode != 0:
-        return ""
-    return result.stdout.strip()
-
-
-def split_worker_pane(
-    *,
-    target_pane: str,
-    cwd: Path,
-    command: Sequence[str],
-    title: str,
-    run_dir: Path,
-) -> str:
-    result = run_tmux(
-        [
-            "split-window",
-            "-h",
-            "-P",
-            "-F",
-            "#{pane_id}",
-            "-c",
-            str(cwd),
-            "-t",
-            target_pane,
-            shlex.join(command),
-        ]
-    )
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux split-window failed")
-    pane_id = result.stdout.strip()
-    set_pane_title(pane_id, title)
-    tag_pane(pane_id, run_dir)
-    return pane_id
-
-
 def new_detached_session(
     session_name: str, cwd: str, first_cmd: str | None = None
 ) -> str:
@@ -175,9 +95,9 @@ def split_container_pane(
 ) -> Optional[str]:
     """container watcher/tail pane 을 split 하고 container 전용 태그만 부착한다.
 
-    reap 가 스캔하는 두 worker/trace 태그는 절대 부착하지 않는다 — tag_pane 의
-    기본 경로를 거치지 않고 CONTAINER_TAG_OPTION 으로 직접 set-option 한다.
-    session_pane 가 빈값/None(tmux 미사용 경로)이면 raise 없이 None 반환(degrade).
+    reap 가 스캔하는 trace 태그는 절대 부착하지 않는다 — CONTAINER_TAG_OPTION 으로
+    직접 set-option 한다. session_pane 가 빈값/None(tmux 미사용 경로)이면 raise
+    없이 None 반환(degrade).
     """
     if not session_pane:
         return None
@@ -196,9 +116,9 @@ def split_container_pane(
 def tag_container_pane(pane_id: str, scope_value: str) -> None:
     """container 전용 태그(CONTAINER_TAG_OPTION)만 부착한다.
 
-    reap 가 스캔하는 worker/trace 태그(tag_pane 기본 경로)는 절대 거치지 않는다 —
-    이 태그가 붙은 pane 은 세션 종료 후에도 생존하고 `down`/`stop-watcher` 의
-    스코프 reap 로만 회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
+    reap 가 스캔하는 trace 태그는 절대 거치지 않는다 — 이 태그가 붙은 pane 은
+    세션 종료 후에도 생존하고 `down`/`stop-watcher` 의 스코프 reap 로만
+    회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
     run_tmux(["set-option", "-p", "-t", pane_id, CONTAINER_TAG_OPTION, scope_value])
 
 
@@ -208,56 +128,6 @@ def set_pane_title(pane_id: str, title: str) -> None:
         raise RuntimeError(result.stderr.strip() or "tmux select-pane failed")
 
 
-def tag_pane(
-    pane_id: str, run_dir: Path, *, option: str = "@okstra_worker_run"
-) -> None:
-    result = run_tmux(
-        ["set-option", "-p", "-t", pane_id, option, _canonical_run_dir(run_dir)]
-    )
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux set-option failed")
-
-
-def capture_pane(pane_id: str, *, last_lines: int = 200) -> str:
-    result = run_tmux(
-        ["capture-pane", "-p", "-t", pane_id, "-S", f"-{last_lines}"]
-    )
-    if result.returncode != 0:
-        return ""
-    return result.stdout
-
-
-def list_run_panes(run_dir: Path, *, lead_pane: str = "") -> list[TmuxPane]:
-    canonical = _canonical_run_dir(run_dir)
-    try:
-        result = run_tmux(
-            [
-                "list-panes",
-                "-a",
-                "-F",
-                "#{pane_id}\t#{pane_title}\t#{@okstra_worker_run}\t#{@okstra_trace_run}",
-            ]
-        )
-    except (OSError, subprocess.SubprocessError):
-        return []
-    if result.returncode != 0:
-        return []
-    return _parse_run_panes(result.stdout, canonical, lead_pane)
-
-
-def _parse_run_panes(output: str, canonical: str, lead_pane: str) -> list[TmuxPane]:
-    panes: list[TmuxPane] = []
-    for line in output.splitlines():
-        pane_id, title, worker_run, trace_run = (line.split("\t") + [""] * 4)[:4]
-        if not pane_id or pane_id == lead_pane:
-            continue
-        if worker_run == canonical:
-            panes.append(TmuxPane(pane_id, title, worker_run, "worker"))
-        elif trace_run == canonical:
-            panes.append(TmuxPane(pane_id, title, trace_run, "trace"))
-    return panes
-
-
 def kill_pane(pane_id: str) -> None:
     try:
         run_tmux(["kill-pane", "-t", pane_id])

package/runtime/python/okstra_ctl/user_response.py

@@ -20,6 +20,7 @@ from typing import Optional
 
 from okstra_ctl.report_views import (
     PLAN_DECISION_APPROVED,
+    normalize_direction_selection_identity,
     serialize_user_response, UserResponseEntry, UserPlanDecision, infer_run_meta,
     parse_expected_form_options,
 )
@@ -36,6 +37,9 @@ from okstra_ctl.clarification_items import (
 _PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
 _ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
+_DIRECTION_SELECTION_HEADING_RE = re.compile(
+    r"^## DIRECTION SELECTION\s*$", re.MULTILINE
+)
 _ANALYSIS_SIDECAR_HEADING_RE = re.compile(
     r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
 )
@@ -79,6 +83,20 @@ class AnalysisReviewRecord:
     seq: str
 
 
+@dataclass(frozen=True)
+class DirectionSelectionRecord:
+    status: str
+    option_id: str
+    option_name: str
+    confirmed: bool
+    selection_note: str
+    constraints: str
+    source_report: str
+    source_data: str
+    source_data_sha256: str
+    seq: str
+
+
 _ANALYSIS_REVIEW_STATUSES = frozenset({
     "accepted",
     "revision-requested",
@@ -405,6 +423,19 @@ def _field(block: str, key: str) -> Optional[str]:
     return m.group(1) if m else None
 
 
+def _direction_identity_fields(block: str) -> tuple[str, str]:
+    match = re.search(
+        r"^- Option-ID:[ \t]*(?P<option_id>[^\r\n]*)\r?\n"
+        r"- Option-Name:[ \t]*(?P<option_name>[^\r\n]*)\r?\n"
+        r"- Confirmed:",
+        block,
+        re.MULTILINE,
+    )
+    if match is None:
+        return "", ""
+    return match.group("option_id"), match.group("option_name")
+
+
 def _value(block: str) -> str:
     # Value 는 "- Value:" 다음 줄들의 "  > " 인용 블록.
     m = re.search(r"^- Value:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE)
@@ -414,6 +445,50 @@ def _value(block: str) -> str:
     return "\n".join(lines).strip()
 
 
+def parse_direction_selection(
+    sidecar_text: str,
+) -> DirectionSelectionRecord | None:
+    matches = list(_DIRECTION_SELECTION_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise UserResponseError(
+            "DIRECTION SELECTION requires exactly one block"
+        )
+    block = sidecar_text[matches[0].end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    if status != "selected":
+        raise UserResponseError("DIRECTION SELECTION Status must be selected")
+    confirmed = _field(block, "Confirmed")
+    if confirmed != "true":
+        raise UserResponseError("DIRECTION SELECTION Confirmed must be true")
+    raw_option_id, raw_option_name = _direction_identity_fields(block)
+    try:
+        option_id, option_name = normalize_direction_selection_identity(
+            raw_option_id,
+            raw_option_name,
+        )
+    except ValueError as error:
+        raise UserResponseError(str(error)) from error
+    return DirectionSelectionRecord(
+        status=status,
+        option_id=option_id,
+        option_name=option_name,
+        confirmed=True,
+        selection_note=_quoted_review_value(block, "Selection-Note"),
+        constraints=_quoted_review_value(block, "Constraints"),
+        source_report=_sidecar_metadata_value(sidecar_text, "source-report"),
+        source_data=_sidecar_metadata_value(sidecar_text, "source-data"),
+        source_data_sha256=_sidecar_metadata_value(
+            sidecar_text, "source-data-sha256"
+        ),
+        seq=_sidecar_metadata_value(sidecar_text, "seq"),
+    )
+
+
 def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
     """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
     blocks. The ``## PLAN DECISION`` block is skipped (read separately by