okstra 0.191.2 → 0.193.0

package/runtime/python/okstra_ctl/next_phase.py

@@ -71,8 +71,9 @@ HANDLED_TASK_TYPES = frozenset(
 )
 
 # implementation-option-selection 의 routing enum 중 phase 가 아닌 값.
+# `pending-direction-selection` 과 `blocked` 는 `_from_option_selection` 이
+# 명시 분기로 다룬다.
 _OPTION_SELECTION_NON_PHASE = {
-    "pending-direction-selection": STATUS_PENDING,
     "blocked": STATUS_BLOCKED,
 }
 
@@ -231,13 +232,22 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
         # release-handoff 는 `routingRecommendation`.
         return make(status=STATUS_BLOCKED, rationale=_selection_guidance(selection))
     if routing == "pending-direction-selection":
-        # 이 상태는 **성공**이다 — 비교가 끝났고 사용자가 방향을 고르면 된다.
-        # 그런데 근거가 비면 closeout 표에 `pending` 행이 없어 "Otherwise →
-        # /okstra-inspect status" 로 떨어지고, 사용자는 끝난 phase 를 들여다보라는
-        # 안내를 받는다. 실측(dev-10341): 1회차가 IO-001·IO-002 를 내고 여기서
-        # 멈췄는데 안내가 없어 같은 phase 가 세 번 더 돌았고, 그동안 워커가
-        # 무너지며 결과가 0건으로 나빠졌다.
-        return make(status=STATUS_PENDING, rationale=_direction_selection_reason(selection))
+        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 계획 단계의 위저드가
+        # 고르게 한다(`selected_direction_pick`). 그러니 다음 phase 는 지금 바로
+        # 시작할 수 있는 `implementation-planning` 이고 status 는 `ready` 다.
+        # 종전에는 phase 없는 `pending` 이었다: task 선택 화면이 `next: --
+        # (pending)` 을 찍어 목적지를 지웠고, task-type 화면은 추천 없이 방금
+        # 끝난 phase 의 재실행을 1번에 올렸다(실측 2026-09-09) — 근거 문장은
+        # "다시 돌리지 마세요" 라고 말하는데 화면은 그 반대를 권한 셈이다.
+        # 근거는 후보 id 를 이름으로 싣는다. 실측(dev-10341): 1회차가
+        # IO-001·IO-002 를 내고 안내 없이 멈춰 같은 phase 가 세 번 더 돌았다.
+        # 후보가 0건이면 고를 것이 없으므로 종전대로 phase 없는 pending 이다.
+        rationale = _direction_selection_reason(selection)
+        if not rationale:
+            return make(status=STATUS_PENDING)
+        return make(
+            phase="implementation-planning", status=STATUS_READY, rationale=rationale
+        )
     if routing in _OPTION_SELECTION_NON_PHASE:
         return make(status=_OPTION_SELECTION_NON_PHASE[routing])
     if not routing:

package/runtime/python/okstra_ctl/plan_items.py

@@ -763,8 +763,9 @@ REVERIFY_PREAMBLE = (
 # 정본 서술은 plan-body-verification.md §"Response format" 이지만 전달 채널은
 # 이 출력이다 — 큐는 모든 검증자 프롬프트에 verbatim 으로 실리는 유일한
 # 조각이라, 여기 실린 블록은 리드가 프롬프트를 어떻게 손 조립하든 도달한다.
-# 두 실측 실패 모양(`## <id>` 2해시 헤딩, `**Verdict:** AGREE` 굵게 안 콜론)을
-# 본문이 직접 금지한다.
+# 실측 실패 모양 중 `## <id>` 2해시 헤딩은 본문이 직접 금지한다. 라벨 변형
+# (`**Verdict:** AGREE`, `- Verdict: AGREE`)은 파서가 같은 필드로 읽으므로
+# (`verdict_blocks._field_match`) 금지하지 않고 그렇게 적는다.
 PLAN_VERIFY_RESPONSE_FORMAT = (
     "\n## Response format\n"
     "\n"
@@ -772,8 +773,9 @@ PLAN_VERIFY_RESPONSE_FORMAT = (
     "item's own id at exactly three hashes (`### P-...`). The collector parses "
     "`^### ` and nothing else — a block at any other depth is not an unparsed "
     "block; it is a verdict that was never recorded, and the round is scored "
-    "on the items that remain. Field labels keep the colon outside the bold: "
-    "`**Verdict**: AGREE`, never `**Verdict:** AGREE`.\n"
+    "on the items that remain. Field labels are bold with the colon outside: "
+    "`**Verdict**: AGREE`; the collector also reads `**Verdict:** AGREE` and "
+    "`- Verdict: AGREE` as the same field.\n"
     "\n"
     "### <item-id>\n"
     "**Verdict**: AGREE | DISAGREE(<a|b|c|d|e|f>) | SUPPLEMENT | UNVERIFIABLE\n"

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -255,7 +255,15 @@ def _parser() -> argparse.ArgumentParser:
     )
     apply_verdicts.add_argument(
         "--append", action="store_true",
-        help="add these votes to existing rows instead of replacing the round",
+        help="add these votes to the existing rows (the critic's tie vote); "
+             "without it every recorded verdict row is replaced, so a round "
+             "that was never closed with complete-round is refused first",
+    )
+    apply_verdicts.add_argument(
+        "--discard-open-rounds", action="store_true",
+        help="replace even the rows of a round that complete-round never "
+             "closed — the recovery path when those rows are being re-applied "
+             "from their result files in order; the discarded rows are listed",
     )
     complete = commands.add_parser(
         "complete-round",
@@ -1387,10 +1395,13 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             "advisory plan-body gating allows one verification round"
         )
     project_root = _probe_project_root(getattr(args, "run_manifest", None))
-    writer = (
-        _append_item_verdicts if getattr(args, "append", False)
-        else _replace_item_verdicts
-    )
+    append = bool(getattr(args, "append", False))
+    if not append:
+        _reject_uncompleted_round_loss(
+            recorded, rows, data.get("roundHistory"), args.round_number, target,
+            discard_open_rounds=bool(getattr(args, "discard_open_rounds", False)),
+        )
+    writer = _append_item_verdicts if append else _replace_item_verdicts
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             writer(item, rows[item["id"]], args.round_number, project_root)
@@ -1439,12 +1450,86 @@ def _append_item_verdicts(
     if clash:
         raise PlanItemContractError(
             f"plan item {item.get('id')} already has a vote from {clash} — "
-            "the extra vote must come from a worker who has not voted on it"
+            "the extra vote must come from a worker who has not voted on it. "
+            "--append is the critic's tie vote; a worker re-voting in a later "
+            "round is recorded without --append, after the earlier round is "
+            "closed with complete-round"
         )
     item["verdicts"] = [*current, *stamped]
     _remember_verified_hash(item)
 
 
+def _reject_uncompleted_round_loss(
+    recorded: Sequence[Mapping[str, Any]],
+    rows: Mapping[str, Any],
+    history: object,
+    round_number: int,
+    target: Path,
+    *,
+    discard_open_rounds: bool = False,
+) -> None:
+    """이번 라운드가 아직 닫히지 않은 다른 라운드의 표를 지우려 하면 쓰기 전에 거절한다.
+
+    `--append` 없는 apply-verdicts 는 항목의 verdicts 를 통째로 교체한다 — 지난
+    라운드 표는 `complete-round` 가 `planItems[].rounds` 에 스냅샷으로 남길 때만
+    살아남는다. 그 스냅샷 없이 교체하면 표는 복구할 수 없이 사라지고, 유일한
+    가드였던 `_reject_round_gap` 은 complete-round 안에 있어 사라진 뒤에야 말했다.
+    실측(2026-09-09, `fontsninja-v3-site` dev-10627 planning 002): r1·r2 를 닫지
+    않고 r3 를 적용해 큐 19건의 r1 표가 없어졌다.
+
+    이력이 없는 데이터(final-report `--data` 경로)는 대상이 아니다 — 라운드
+    스냅샷을 갖는 것은 convergence 소유 상태 파일뿐이다.
+    """
+    if not isinstance(history, list):
+        return
+    closed = {
+        row.get("round")
+        for row in history
+        if isinstance(row, Mapping) and isinstance(row.get("round"), int)
+    }
+    at_risk: dict[int, list[str]] = {}
+    for item in recorded:
+        if not isinstance(item, Mapping) or item.get("id") not in rows:
+            continue
+        for row in item.get("verdicts") or []:
+            if not isinstance(row, Mapping):
+                continue
+            recorded_round = row.get("round")
+            if (
+                isinstance(recorded_round, int)
+                and recorded_round != round_number
+                and recorded_round not in closed
+            ):
+                at_risk.setdefault(recorded_round, []).append(str(item.get("id")))
+    if not at_risk:
+        return
+    detail = "; ".join(
+        f"round {number}: {', '.join(sorted(set(ids)))}"
+        for number, ids in sorted(at_risk.items())
+    )
+    if discard_open_rounds:
+        # 복구 경로 — 잃어버린 라운드를 결과 파일에서 순서대로 다시 적용할 때는
+        # 지금 남은 뒤 라운드 표가 버려야 할 쪽이다. 무엇을 버리는지는 남긴다.
+        print(
+            f"apply-verdicts: discarding open-round verdicts ({detail})",
+            file=sys.stderr,
+        )
+        return
+    commands = " then ".join(
+        f"`okstra plan-items complete-round --state {target} "
+        f"--run-manifest <run-manifest> --round {number}`"
+        for number in sorted(at_risk)
+    )
+    raise PlanItemContractError(
+        f"round {round_number} would replace verdicts of a round that was never "
+        f"completed ({detail}) — apply-verdicts replaces every recorded row, and "
+        "only complete-round keeps a round's votes in planItems[].rounds. Close "
+        f"the earlier round first: run {commands}, then re-run this command. "
+        "If those rows are themselves being re-applied from their result files "
+        "in order, pass --discard-open-rounds. Nothing was written."
+    )
+
+
 def _gate_module() -> Any:
     # 부모 개수를 세면 체크아웃에서만 맞는다 — 설치본은 패키지가
     # `~/.okstra/lib/python/` 이라 validators 가 `~/.okstra/lib/` 아래다.

package/runtime/python/okstra_ctl/report_finalize.py

@@ -25,10 +25,15 @@ placeholders, which a v2 report never carries because its numeric cells are
 `null` until this step fills them. Substituting the tokens on a later retry
 then leaves the already-rendered html stale for `validators/validate-report-views.py`.
 
-The translation sidecar is NOT one of these steps. `render-views` overlays it,
-so a non-English run dispatches the translator before this sequence starts —
-after verifying the data.json is English, which is why `check-source` is also
-available as a standalone command.
+The translation sidecar is the `translate` step, between `check-source` and
+`render-views`: `render-views` overlays it, and `check-source` has to pass first
+because the extractor refuses a work list from a non-English source. It used to
+be a manual lead sequence outside this command (materialize the translator
+prompt, dispatch it, resume finalize at `render-views`), written only in a doc
+the lead lazy-reads; a lead that ran the whole sequence at once skipped it and
+the run kept an English view under a `ko` report (2026-09-09, fontsninja-v3-site
+dev-10628-3). `okstra_ctl.report_translation_dispatch` owns the step; an English
+report or an existing sidecar makes it a no-op.
 
 Every lead adapter drives Phase 7 through this module: the Codex adapter calls
 it in-process (``codex_dispatch``), and a Claude-led run reaches the same code
@@ -62,6 +67,7 @@ from .final_report_paths import (
 from .paths import task_dir, task_manifest_file
 from .report_view_artifacts import html_view_path
 from .release_gate import release_handoff_allowed
+from .report_translation_dispatch import TranslateOutcome, translate_report
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .stage_integrate import IntegrateError
 from .stage_targets import (
@@ -83,6 +89,7 @@ from okstra_project.phase_pointer import (
 
 STEP_PROJECT_ACTIVITY = "project-activity"
 STEP_CHECK_SOURCE = "check-source"
+STEP_TRANSLATE = "translate"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
@@ -96,6 +103,7 @@ STEP_ORDER = (
     # a Korean SSOT into English chrome, spawning follow-ups from it, and
     # validating it all succeed on a record the next phase cannot read.
     STEP_CHECK_SOURCE,
+    STEP_TRANSLATE,
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
@@ -112,6 +120,8 @@ V3_STEP_ORDER = (
     STEP_TOKEN_USAGE,
     STEP_PROJECT_ACTIVITY,
     STEP_CHECK_SOURCE,
+    # After the English gate, before the render that overlays its sidecar.
+    STEP_TRANSLATE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
     STEP_VALIDATE_RUN,
@@ -337,6 +347,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 str(ctx.data_path),
             ],
         ),
+        (
+            STEP_TRANSLATE,
+            ["<in-process>", "translate", str(ctx.data_path)],
+        ),
         (
             STEP_TOKEN_USAGE,
             [
@@ -782,6 +796,8 @@ def _run_finalize_step(
     """한 Phase 7 단계를 실행하고 그 단계의 종료 코드만 돌려준다."""
     if name == STEP_PROJECT_ACTIVITY:
         return _run_project_activity(ctx, command)
+    if name == STEP_TRANSLATE:
+        return _run_translate(ctx, command)
     if name == STEP_TEARDOWN_STAGES:
         return _teardown_stage_worktrees(ctx, command)
     if name == STEP_RECORD_GROUP_MEMORY:
@@ -801,6 +817,31 @@ def _run_finalize_step(
     )
 
 
+def _run_translate(
+    ctx: FinalizeContext,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """비영어 리포트의 번역 사이드카를 만든다. 영어 리포트는 건너뛴다.
+
+    실패는 다른 단계처럼 기록만 하고 시퀀스는 계속 돈다 — `render-views` 는
+    사이드카 없이 영어 열람본을 내고, `validate-run` 은 권고를 남기며, 결과의
+    `--only translate --only render-views …` 재개 힌트가 그 둘을 다시 돌린다.
+    """
+    try:
+        outcome = translate_report(
+            project_root=ctx.project_root,
+            workspace_root=ctx.workspace_root,
+            manifest_path=ctx.manifest_path,
+            manifest=_load_manifest(ctx.manifest_path),
+            data_path=ctx.data_path,
+        )
+    except (FinalizeError, OSError, JsonBoundaryError) as exc:
+        outcome = TranslateOutcome(1, "", f"translate failed: {exc}")
+    return subprocess.CompletedProcess(
+        command, outcome.returncode, outcome.stdout, outcome.stderr
+    )
+
+
 def _run_project_activity(
     ctx: FinalizeContext,
     command: Sequence[str],
@@ -932,15 +973,21 @@ _CLI_EPILOG = r"""Usage:
   okstra report-finalize --project-root <dir> --run-manifest <path> \
     --report <final-report-<task-type>-<seq>.md> [--team-state <path>]
 
-Runs the six Phase 7 steps in their contractual order against one final-report:
+Runs the Phase 7 steps in their contractual order against one final-report:
 
   1. project-activity  project the run's activity events into the data.json
   2. check-source      verify the data.json is the English SSOT
-  3. token-usage       substitute real token/cost numbers into the data.json
-  4. render-views      write the schema-v2 task-specific *.html sibling; v1
-                       keeps the legacy conditional interactive view
-  5. spawn-followups   turn section 4 rows into task stubs
-  6. validate-run      validate the finished run artifacts
+  3. translate         for a non-English reportLanguage, materialize and
+                       dispatch the translator worker and require its
+                       *.i18n.<lang>.json sidecar; a no-op for English or
+                       when the sidecar already exists
+  4. token-usage       substitute real token/cost numbers into the data.json
+  5. render-views      write the schema-v2 task-specific *.html sibling with
+                       the translation overlaid; v1 keeps the
+                       legacy conditional interactive view
+  6. spawn-followups   turn section 4 rows into task stubs
+  7. validate-run      validate the finished run artifacts
+  8. record-group-memory / 9. teardown-stages  after a clean validation
 
 Every step is idempotent, so re-running after a fixed failure is safe. The
 sequence stops at the first non-zero exit and reports which step failed, except

package/runtime/python/okstra_ctl/report_translation_dispatch.py

@@ -0,0 +1,300 @@
+"""Phase 7 `translate` 단계 — 번역 사이드카를 okstra 가 직접 만든다.
+
+비영어 리포트의 번역 워커는 종전에 리드의 수동 절차였다: `agent-prompt
+materialize --audience translator` 로 예약을 만들고, `worker-dispatch --workers
+translator` 로 띄우고, `report-finalize` 를 두 번에 나눠 도는 순서가 리드가
+lazy-read 하는 문서(`prompts/lead/report-writer.md`)에만 있었다. 실측(2026-09-09,
+fontsninja-v3-site dev-10628-3 implementation-option-selection, grok 리드): 리드가
+`report-finalize` 를 한 번에 돌려 번역 예약이 0건이었고, 디스패처는 0건을 거절할
+뿐 만들지 못한다(`dispatch_core._translator_job_from_reservation`). 검증은 권고
+한 줄을 남겼고 HTML 은 영어로 남았다.
+
+이 모듈은 그 절차를 `report-finalize` 의 한 단계로 내린다. 예약이 없으면 지시문과
+프롬프트를 발행하고(`agent-prompt materialize` 와 같은 코드), CLI 래퍼 디스패처로
+워커를 띄운 뒤 사이드카가 생겼는지 본다. 디스패치 기록과 결과 링크는
+`dispatch_core` 가 배치 안에서 이미 하므로 여기서 다시 하지 않는다.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from . import worker_dispatch
+from .agent.prompt_cli.cli import main as agent_prompt_main
+from .dispatch_core import translator_reservations
+from .dispatch_state import (
+    DispatchError,
+    load_json_object,
+    resolve_project_path,
+    resolve_required_path,
+)
+from .final_report_paths import translation_sidecar_path
+from .json_boundary import JsonBoundaryError
+
+TRANSLATOR_WORKER_ID = "translator"
+
+# 지시문의 언어 이름. 워커는 `**Report Language:**` 헤더로 코드를 받지만, 지시문은
+# 사람이 읽는 문장이라 이름으로 적는다. 표에 없는 코드는 코드 그대로 쓴다.
+_LANGUAGE_NAMES = {"ko": "Korean"}
+
+# 리드가 종전에 손으로 쓰던 지시문(실측 2026-09-08, fontsninja-nlpvibe dev-10786
+# requirements-discovery-002)과 같은 절차다. 명령은 `agents/workers/translator-worker.md`
+# 의 Procedure 와 같은 세 개이고, 결과·감사 경로는 프롬프트 앵커가 이름한다.
+_INSTRUCTIONS = """## Instructions
+
+Translate the finalized report into {language} faithfully. This is translation only: no analysis, no source edits.
+
+1. Run `okstra report-translate source --run-manifest {manifest}` and read the complete work list, in chunks if it is long. Copy the `Source digest` it prints.
+2. Write one translated block per `## T-NNN` item to the exact Result Path, using the same `## T-NNN` headings. Preserve every identifier, path, command, enum token, link, and qualification character for character.
+3. Publish with `okstra report-translate write --run-manifest {manifest} --source-digest <digest from step 1> --translations <Result Path>`, then run `okstra report-translate check-data --run-manifest {manifest}`. Fix the translation until that check passes; do not return on a failing check.
+4. Write a completion pointer to the Worker Result Path naming the translations file, the published sidecar, the digest, and the check result. Write the audit sidecar with reading, completeness, and terminology checks.
+
+Do not edit the canonical report, the narrative, the HTML, or any source file. All `.okstra` paths resolve from Project Root.
+"""
+
+
+@dataclass(frozen=True)
+class TranslateOutcome:
+    """`translate` 단계의 결과. `report_finalize` 가 CompletedProcess 로 옮긴다."""
+
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+class TranslateError(Exception):
+    """번역 워커를 예약하거나 띄우지 못했다. 메시지가 그 자리를 이름한다."""
+
+
+def report_language(manifest: Mapping[str, Any], data_path: Path) -> str:
+    """이 run 의 사람 리포트 언어. 매니페스트가 정본이고, 없으면 리포트의 meta.
+
+    매니페스트 `reportLanguage` 는 prepare 가 `report_language.resolve_report_language`
+    로 정한 값이고, 조립이 `meta.reportLanguage` 로 복사한다. 그 필드가 없는 옛
+    run 은 리포트에서 읽는다. 둘 다 없으면 영어다.
+    """
+    value = str(manifest.get("reportLanguage") or "").strip()
+    if value:
+        return value
+    if data_path.is_file():
+        try:
+            data = load_json_object(data_path, "final-report data")
+        except (DispatchError, JsonBoundaryError):
+            return "en"
+        meta = data.get("meta")
+        if isinstance(meta, Mapping):
+            value = str(meta.get("reportLanguage") or "").strip()
+    return value or "en"
+
+
+def translate_report(
+    *,
+    project_root: Path,
+    workspace_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    data_path: Path,
+) -> TranslateOutcome:
+    """비영어 리포트의 번역 사이드카를 있게 만든다. 영어 리포트는 할 일이 없다.
+
+    사이드카가 이미 있으면(앞선 호출, 또는 리드가 손으로 띄운 워커) 그대로 둔다.
+    없으면 예약을 보장하고 워커를 띄운 뒤, 사이드카의 존재로만 성공을 판정한다 —
+    워커의 종료 코드는 산출물의 존재를 대신하지 못한다.
+    """
+    lang = report_language(manifest, data_path)
+    if lang == "en":
+        return TranslateOutcome(0, f"skipped: reportLanguage is {lang!r}")
+    sidecar = translation_sidecar_path(data_path, lang)
+    if sidecar.is_file():
+        return TranslateOutcome(0, f"translation sidecar already present: {sidecar.name}")
+    try:
+        metadata_path = ensure_translator_reservation(
+            project_root, manifest_path, manifest, lang
+        )
+        dispatch = dispatch_translator(project_root, workspace_root, manifest_path)
+    except TranslateError as exc:
+        return TranslateOutcome(1, "", str(exc))
+    if sidecar.is_file():
+        return TranslateOutcome(
+            0,
+            f"translated into {lang!r}: {sidecar.name} (reservation "
+            f"{metadata_path.name})",
+            dispatch.stderr,
+        )
+    return TranslateOutcome(
+        1,
+        dispatch.stdout,
+        f"translator dispatch exited {dispatch.returncode} and left no "
+        f"translation sidecar at {sidecar}"
+        + (f": {dispatch.stderr.strip()}" if dispatch.stderr.strip() else ""),
+    )
+
+
+def ensure_translator_reservation(
+    project_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    lang: str,
+) -> Path:
+    """이 run 의 아직 안 띄운 translator 예약 하나를 돌려준다. 없으면 만든다.
+
+    Returns the invocation metadata path of that reservation.
+
+    예약이 둘이면 디스패처가 고를 수 없고 회수 명령도 없으므로 그대로 거절한다 —
+    그 상태는 리드가 다른 id 로 두 번 발행했을 때만 생긴다. 예약 id 는
+    `<task-type>-<seq>-translator` 이고, 같은 run 의 앞선 시도가 실패해 그 id 가
+    이미 쓰였으면 `-r2`, `-r3` 로 잇는다.
+    """
+    team_state = load_json_object(
+        resolve_required_path(project_root, manifest, "teamStatePath"), "team-state"
+    )
+    try:
+        candidates, seen = translator_reservations(project_root, manifest, team_state)
+    except DispatchError as exc:
+        raise TranslateError(f"translator reservation lookup failed: {exc}") from exc
+    if len(candidates) == 1:
+        return resolve_project_path(
+            project_root, str(candidates[0].get("metadataPath") or "")
+        )
+    if len(candidates) > 1:
+        raise TranslateError(
+            "translator dispatch requires exactly one canonical invocation "
+            f"reservation for this run; found {len(candidates)}. Translator "
+            "reservations seen: " + "; ".join(seen)
+        )
+    return _materialize_translator(project_root, manifest_path, manifest, lang, seen)
+
+
+def dispatch_translator(
+    project_root: Path, workspace_root: Path, manifest_path: Path,
+) -> TranslateOutcome:
+    """`okstra worker-dispatch --workers translator` 와 같은 코드를 프로세스 안에서 돈다.
+
+    디스패처는 결과 JSON 을 stdout 에 찍는다. Phase 7 의 stdout 은 finalize 결과
+    JSON 하나여야 하므로 여기서 받아 단계 결과로 넘긴다.
+    """
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            code = worker_dispatch.main([
+                "--project-root", str(project_root),
+                "--run-manifest", str(manifest_path),
+                "--workspace-root", str(workspace_root),
+                "--workers", TRANSLATOR_WORKER_ID,
+            ])
+        except (DispatchError, OSError) as exc:
+            raise TranslateError(f"translator dispatch failed: {exc}") from exc
+    return TranslateOutcome(code, out.getvalue(), err.getvalue())
+
+
+def _materialize_translator(
+    project_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    lang: str,
+    seen: list[str],
+) -> Path:
+    task_type = str(manifest.get("taskType") or "").strip()
+    if not task_type:
+        raise TranslateError("run manifest has no taskType")
+    run_dir = resolve_required_path(project_root, manifest, "runDirectoryPath")
+    base_id = f"{task_type}-{_seq(manifest, 'manifests')}-translator"
+    used = {entry.split(" ", 1)[0] for entry in seen}
+    invocation_id = base_id
+    attempt = 1
+    while invocation_id in used:
+        attempt += 1
+        invocation_id = f"{base_id}-r{attempt}"
+    prompt_seq = _seq(manifest, "prompts")
+    result_seq = _seq(manifest, "workerResults")
+    suffix = "" if attempt == 1 else f"-r{attempt}"
+    instruction = (
+        _instruction_root(project_root, manifest, run_dir)
+        / f"translator-instructions-{task_type}-{_seq(manifest, 'state')}{suffix}.md"
+    )
+    prompt = run_dir / "prompts" / f"translator-worker-prompt-{task_type}-{prompt_seq}{suffix}.md"
+    translations = (
+        run_dir / "worker-results"
+        / f"translator-translations-{task_type}-{result_seq}{suffix}.md"
+    )
+    worker_result = (
+        run_dir / "worker-results" / f"translator-worker-{task_type}-{result_seq}{suffix}.md"
+    )
+    if not instruction.is_file():
+        # 리드가 먼저 써 둔 지시문은 그대로 쓴다. 없을 때만 okstra 의 것을 쓴다.
+        instruction.parent.mkdir(parents=True, exist_ok=True)
+        instruction.write_text(
+            _INSTRUCTIONS.format(
+                language=_LANGUAGE_NAMES.get(lang, lang),
+                manifest=manifest_path.relative_to(project_root).as_posix()
+                if manifest_path.is_relative_to(project_root)
+                else str(manifest_path),
+            ),
+            encoding="utf-8",
+        )
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        code = agent_prompt_main([
+            "materialize",
+            "--project-root", str(project_root),
+            "--run-manifest", str(manifest_path),
+            "--invocation-id", invocation_id,
+            "--worker-id", TRANSLATOR_WORKER_ID,
+            "--audience", TRANSLATOR_WORKER_ID,
+            "--dispatch-kind", TRANSLATOR_WORKER_ID,
+            "--assignment-ref", TRANSLATOR_WORKER_ID,
+            "--instruction", str(instruction),
+            "--prompt", str(prompt),
+            "--result", str(translations),
+            "--audit-source", str(worker_result),
+            "--json",
+        ])
+    if code != 0:
+        raise TranslateError(
+            "translator prompt materialization failed: "
+            + (err.getvalue().strip() or out.getvalue().strip() or f"exit {code}")
+        )
+    try:
+        payload = json.loads(out.getvalue())
+    except json.JSONDecodeError as exc:
+        raise TranslateError(
+            f"translator materialization printed no JSON: {out.getvalue()[:200]!r}"
+        ) from exc
+    metadata = str(payload.get("metadataPath") or "")
+    if not metadata:
+        raise TranslateError("translator materialization named no metadataPath")
+    return resolve_project_path(project_root, metadata)
+
+
+def _instruction_root(
+    project_root: Path, manifest: Mapping[str, Any], run_dir: Path,
+) -> Path:
+    """지시문을 둘 디렉터리. materialize 는 `authorizedPaths.instructionRoots` 밖의
+    지시문을 거절하므로 그 목록에서 고른다 — 리드가 쓰던 `state/` 가 있으면 그것,
+    없으면 첫 항목, 목록이 없으면 run 의 `state/`."""
+    contract = manifest.get("agentContract")
+    authorized = contract.get("authorizedPaths") if isinstance(contract, Mapping) else None
+    roots = authorized.get("instructionRoots") if isinstance(authorized, Mapping) else None
+    candidates = [
+        resolve_project_path(project_root, str(root))
+        for root in (roots if isinstance(roots, list) else [])
+        if str(root).strip()
+    ]
+    for root in candidates:
+        if root.name == "state":
+            return root
+    return candidates[0] if candidates else run_dir / "state"
+
+
+def _seq(manifest: Mapping[str, Any], category: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise TranslateError("run manifest has no runSequencesByCategory object")
+    value = str(seqs.get(category) or seqs.get("manifests") or "").strip()
+    if not value:
+        raise TranslateError(f"run manifest has no {category} sequence")
+    return value