okstra 0.187.0 → 0.188.1

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

@@ -13,7 +13,7 @@ import os
 from pathlib import Path
 import shutil
 import tempfile
-from typing import get_args
+from typing import Any, Mapping, get_args
 
 from ..invocation import (
     AgentInstruction,
@@ -31,7 +31,13 @@ from ...assignment_environment import load_assignment_context
 from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
+from ...final_report_paths import final_report_data_path
 from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...report_synthesis_packet import (
+    ReportSynthesisPacketError,
+    materialize_report_synthesis_packet,
+)
+from ...worker_prompt_body import report_writer_input_lines
 from ...dispatch_state import detect_terminal_backend
 from .dynamic_verifier import (
     _dynamic_verifier_source,
@@ -54,6 +60,10 @@ from .run_identity import _validate_run_identity
 
 
 _AUDIENCES = frozenset(get_args(AgentAudience))
+# 결과 파일과 별개의 워커 결과 포인터를 가진 audience. 이들만 `--audit-source` 로
+# 두 번째 경로를 받고, 프롬프트에 `**Worker Result Path:**` 앵커가 생긴다.
+# 나머지 audience 의 결과는 하나뿐이고 감사 사이드카는 그 이름에서 파생된다.
+_POINTER_AUDIENCES = frozenset({"report-writer", "translator"})
 
 
 def _materialize(args: argparse.Namespace) -> PreparedAgentInvocation:
@@ -116,35 +126,6 @@ def _materialize_run(
         "result",
         must_exist=False,
     )
-    if args.audience == "report-writer" and not args.audit_source:
-        # The report writer is the one audience whose result path is not its own
-        # worker result: it writes the report body, while the audit sidecar is
-        # derived from its `.md`. With both collapsed into one value the prompt
-        # loses its `**Worker Result Path:**` anchor and the writer puts the
-        # report where the audit file belongs — silently, because every header
-        # is still present and well-formed. The roster path derives both from
-        # the manifest; a dynamic call has to name them.
-        #
-        # Which artifact `--result` names depends on the report contract, and
-        # `dispatch_state.dispatch_result_path` is what decides it. Naming only
-        # the v2 answer here sent v3 runs to the data.json, so the narrative
-        # `report-finalize` assembles from was never written and the phase
-        # failed later, at a place that does not point back here.
-        if uses_report_contract_v3(manifest):
-            expected = report_narrative_path(project_root, manifest)
-            raise AgentPromptCliError(
-                "report-writer materialization requires --audit-source: under "
-                f"report contract 3.0 --result is the narrative ({expected}), "
-                "which `report-finalize` assembles the report data.json from, "
-                "and --audit-source the worker-result .md the audit sidecar is "
-                "derived from"
-            )
-        raise AgentPromptCliError(
-            "report-writer materialization requires --audit-source: under "
-            "report contract 2.0 --result is the report data.json, and "
-            "--audit-source the worker-result .md the audit sidecar is "
-            "derived from"
-        )
     audit_source_path = (
         _authorized_path(
             project_root,
@@ -154,8 +135,68 @@ def _materialize_run(
             must_exist=False,
         )
         if args.audit_source
-        else result_path
+        else None
     )
+    if args.audience not in _POINTER_AUDIENCES:
+        # 결과가 하나뿐인 audience 다. 두 번째 경로는 워커(`**Result Path:**` 에
+        # 쓴다)와 수집기(jobs-file 의 workerResultPath 를 기다린다)에게 서로 다른
+        # 파일을 말하는 것밖에 못 한다. 실측(2026-09-02, fontsninja-v3-site
+        # dev-10626-1 error-analysis r04): 리드가 reverify 에 `-worker-` 이름을
+        # `--audit-source` 로 따로 넘겨 검증 디스패치 9건 중 8건이 결과를 다
+        # 쓰고도 `required worker artifact was not produced` 로 끝났다.
+        if (
+            audit_source_path is not None
+            and _normalized(audit_source_path) != _normalized(result_path)
+        ):
+            raise AgentPromptCliError(
+                f"{args.audience} materialization forbids --audit-source: this "
+                "audience writes one result and its audit sidecar derives from "
+                "that result's name. Name --result with the canonical `-worker-` "
+                "token instead (reverify: "
+                "<worker-id>-worker-reverify-r<N>-<task-type>-<seq>.md) and put "
+                "the same path in the jobs file's workerResultPath"
+            )
+        audit_source_path = result_path
+    elif args.audience == "report-writer":
+        if audit_source_path is None:
+            # The report writer is the one audience whose result path is not its
+            # own worker result: it writes the report body, while the audit
+            # sidecar is derived from its `.md`. With both collapsed into one
+            # value the prompt loses its `**Worker Result Path:**` anchor and the
+            # writer puts the report where the audit file belongs — silently,
+            # because every header is still present and well-formed. The roster
+            # path derives both from the manifest; a dynamic call has to name
+            # them.
+            #
+            # Which artifact `--result` names depends on the report contract, and
+            # `dispatch_state.dispatch_result_path` is what decides it. Naming
+            # only the v2 answer here sent v3 runs to the data.json, so the
+            # narrative `report-finalize` assembles from was never written and
+            # the phase failed later, at a place that does not point back here.
+            if uses_report_contract_v3(manifest):
+                expected = report_narrative_path(project_root, manifest)
+                raise AgentPromptCliError(
+                    "report-writer materialization requires --audit-source: "
+                    f"under report contract 3.0 --result is the narrative "
+                    f"({expected}), which `report-finalize` assembles the report "
+                    "data.json from, and --audit-source the worker-result .md "
+                    "the audit sidecar is derived from"
+                )
+            raise AgentPromptCliError(
+                "report-writer materialization requires --audit-source: under "
+                "report contract 2.0 --result is the report data.json, and "
+                "--audit-source the worker-result .md the audit sidecar is "
+                "derived from"
+            )
+        _validate_report_writer_paths(
+            project_root,
+            manifest,
+            worker_id=args.worker_id,
+            result_path=result_path,
+            audit_source_path=audit_source_path,
+        )
+    elif audit_source_path is None:
+        audit_source_path = result_path
     _validate_run_identity(
         manifest,
         worker_id=args.worker_id,
@@ -218,6 +259,17 @@ def _materialize_run(
         manifest=manifest,
         active_context=active_context,
     ))
+    body = instruction_path.read_text(encoding="utf-8")
+    if args.audience == "report-writer":
+        body = _with_inputs_section(
+            body,
+            _report_writer_input_lines(
+                project_root,
+                manifest,
+                active_context,
+                narrative_path=result_path,
+            ),
+        )
     request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
         worker_id=args.worker_id if identity is None else None,
@@ -227,7 +279,7 @@ def _materialize_run(
         assignment=assignment,
         instruction=AgentInstruction(
             anchor_lines=anchor_lines,
-            body=instruction_path.read_text(encoding="utf-8"),
+            body=body,
             source_paths=(AgentInstructionSource(
                 kind="project",
                 path=_relative(project_root, instruction_path),
@@ -259,6 +311,151 @@ def _materialize_run(
     return prepare_agent_invocation(request)
 
 
+def _normalized(path: Path) -> Path:
+    return Path(os.path.normpath(path))
+
+
+def _validate_report_writer_paths(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    *,
+    worker_id: str,
+    result_path: Path,
+    audit_source_path: Path,
+) -> None:
+    """report-writer 의 두 경로를 run 이 이미 정한 값에 못 박는다.
+
+    `--result` 는 조립이 읽는 서술문 경로다: 계약 3.0 이면 매니페스트의
+    `reportNarrativePath`, 2.0 이면 `expectedReportRecordPath` 의 data.json.
+    다른 경로에 쓴 서술문은 `report-finalize` 가 읽지 않는다. `--audit-source`
+    는 명부(team-state `workers[].resultPath`)의 워커 결과다: `okstra team
+    await` 는 그 파일이 있어야 명부 행을 completed 로 적는다. 실측(2026-09-02,
+    fontsninja-v3-site dev-10626-1 r04): 리드가 재시도마다 `-a2`/`-a3` 접미를
+    붙인 경로를 넘겨 서술문 세 벌이 조립 밖에 쌓였고, 결국 손으로 `cp` 했다.
+    교정 디스패치는 프롬프트 경로와 invocation ID 만 새로 하고 이 두 경로는
+    그대로 쓴다.
+    """
+    if uses_report_contract_v3(manifest):
+        expected_result = report_narrative_path(project_root, manifest)
+        what = "the narrative report-finalize assembles from (run manifest reportNarrativePath)"
+    else:
+        expected_result = final_report_data_path(_project_manifest_path(
+            project_root,
+            manifest.get("expectedReportRecordPath"),
+            "expected report record",
+            must_exist=False,
+        ))
+        what = "the report data.json (run manifest expectedReportRecordPath)"
+    if _normalized(result_path) != _normalized(expected_result):
+        raise AgentPromptCliError(
+            f"report-writer --result must be {what}: expected {expected_result}, "
+            f"got {result_path}. A corrective dispatch reuses this path with a "
+            "fresh prompt path and invocation ID"
+        )
+    roster_result = _roster_result_path(project_root, manifest, worker_id)
+    if (
+        roster_result is not None
+        and _normalized(audit_source_path) != _normalized(roster_result)
+    ):
+        raise AgentPromptCliError(
+            "report-writer --audit-source must be the roster's worker result "
+            f"(team-state workers[].resultPath): expected {roster_result}, got "
+            f"{audit_source_path}. `okstra team await` records the roster row "
+            "completed only when that file exists"
+        )
+
+
+def _load_team_state(project_root: Path, manifest: Mapping[str, Any]) -> Mapping[str, Any]:
+    """매니페스트가 가리키는 team-state. 없으면 빈 매핑."""
+    team_state_value = manifest.get("teamStatePath")
+    if not isinstance(team_state_value, str) or not team_state_value:
+        return {}
+    team_state_path = Path(team_state_value)
+    if not team_state_path.is_absolute():
+        team_state_path = project_root / team_state_path
+    if not team_state_path.is_file():
+        return {}
+    return _read_json_object(team_state_path, "team state")
+
+
+def _report_writer_input_lines(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    *,
+    narrative_path: Path,
+) -> list[str]:
+    """report-writer 의 `## Inputs` 줄. 로스터 경로(`worker_prompt_body`)와 같은 규칙.
+
+    계약 3.0 이면 합성 묶음을 여기서 만들고 그 한 줄을 싣는다; 그 전 계약은
+    옛 목록이다. 실측(2026-09-02, fontsninja-v3-site dev-10626-1 r04): run
+    갈래의 프롬프트에는 이 절이 없어, 작성자가 "읽을 게 없다"며 서술문을
+    거부했고 리드가 경로 22개를 손으로 열거하고서야 통과했다. 두 갈래가 같은
+    입력 표면을 내야 하는 이유다.
+    """
+    team_state = _load_team_state(project_root, manifest)
+    if not uses_report_contract_v3(manifest):
+        return report_writer_input_lines(manifest, active_context, team_state)
+    try:
+        _, markdown_path = materialize_report_synthesis_packet(
+            project_root=project_root,
+            manifest=manifest,
+            active_context=active_context,
+            team_state=team_state,
+            narrative_path=narrative_path,
+        )
+    except ReportSynthesisPacketError as exc:
+        defects = "; ".join(
+            f"owner={issue.owner} source={issue.label} path={issue.path} "
+            f"reason={issue.reason}"
+            for issue in exc.issues
+        )
+        raise AgentPromptCliError(
+            f"report synthesis packet contract defects: {defects}"
+        ) from exc
+    return [f"- Report synthesis packet: `{_relative(project_root, markdown_path)}`"]
+
+
+def _with_inputs_section(body: str, input_lines: list[str]) -> str:
+    """런타임 소유 입력 줄을 본문의 `## Inputs` 첫머리에 넣는다.
+
+    리드가 이미 그 절을 썼으면 그 제목 바로 아래에 끼워 한 절로 두고, 없으면
+    머리의 `**…:**` 헤더 블록 뒤에 절을 새로 연다.
+    """
+    lines = body.splitlines()
+    for index, line in enumerate(lines):
+        if line.strip() == "## Inputs":
+            merged = lines[: index + 1] + input_lines + lines[index + 1 :]
+            return "\n".join(merged) + "\n"
+    insert_at = 0
+    while insert_at < len(lines) and (
+        not lines[insert_at].strip() or lines[insert_at].startswith("**")
+    ):
+        insert_at += 1
+    section = ["## Inputs", *input_lines, ""]
+    if insert_at and lines[insert_at - 1].strip():
+        section = ["", *section]
+    return "\n".join(lines[:insert_at] + section + lines[insert_at:]) + "\n"
+
+
+def _roster_result_path(
+    project_root: Path, manifest: Mapping[str, Any], worker_id: str,
+) -> Path | None:
+    """명부가 이 워커에 적어 둔 `resultPath`. 행이 없으면 None."""
+    workers = _load_team_state(project_root, manifest).get("workers")
+    if not isinstance(workers, list):
+        return None
+    for row in workers:
+        if not isinstance(row, Mapping) or row.get("workerId") != worker_id:
+            continue
+        value = row.get("resultPath")
+        if not isinstance(value, str) or not value.strip():
+            return None
+        path = Path(value.strip())
+        return path if path.is_absolute() else project_root / path
+    return None
+
+
 def _materialize_standalone(
     args: argparse.Namespace,
     project_root: Path,

package/runtime/python/okstra_ctl/approval_decisions.py

@@ -127,10 +127,23 @@ def _ledger(path: Path, task_key: str, task_type: str, run_seq: str) -> dict[str
     expected = (task_key, task_type, run_seq)
     actual = (ledger.get("taskKey"), ledger.get("taskType"), ledger.get("runSeq"))
     if actual != expected:
-        raise ApprovalDecisionError("approval ledger identity does not match this run")
+        # 원장은 `runSeq` 를 세 자리 문자열로 적는다. 정수 `4` 를 넘긴 호출은
+        # 원장을 덤프해 보기 전까지 무엇이 달랐는지 알 수 없었다.
+        raise ApprovalDecisionError(
+            "approval ledger identity does not match this run: ledger has "
+            f"taskKey={actual[0]!r} taskType={actual[1]!r} runSeq={actual[2]!r}; "
+            f"this call passed taskKey={expected[0]!r} taskType={expected[1]!r} "
+            f"runSeq={expected[2]!r}"
+        )
     return ledger
 
 
+def normalize_run_seq(value: str) -> str:
+    """`4` → `004`. 원장과 run 산출물은 세 자리 0 패딩 문자열을 쓴다."""
+    text = str(value).strip()
+    return text.zfill(3) if text.isdigit() else text
+
+
 def _validate_option_set(
     options: Sequence[DecisionOption], classification: str,
     recommended_disposition: str,
@@ -280,7 +293,18 @@ def _options_from_args(args: argparse.Namespace) -> tuple[DecisionOption, ...]:
         args.option_added_work, args.option_direction_change,
     )
     if len({len(values) for values in fields}) != 1:
-        raise ApprovalDecisionError("every repeated option field needs the same count")
+        names = (
+            "role", "answer", "rationale", "disposition", "reach",
+            "scope-effect", "added-work", "direction-change",
+        )
+        counts = ", ".join(
+            f"--option-{name}={len(values)}" for name, values in zip(names, fields)
+        )
+        raise ApprovalDecisionError(
+            "every repeated option field needs the same count — repeat each "
+            f"--option-* flag once per option, including the ones --help marks "
+            f"optional: {counts}"
+        )
     return tuple(
         DecisionOption(role, answer, rationale, disposition, reach,
                        tuple(effect.split(",")) if effect else (), added, direction)
@@ -372,6 +396,7 @@ def _open_from_args(args: argparse.Namespace) -> None:
     values = vars(args).copy()
     values.pop("command")
     values["ledger_path"] = values.pop("ledger")
+    values["run_seq"] = normalize_run_seq(values["run_seq"])
     for key in tuple(values):
         if key.startswith("option_"):
             values.pop(key)

package/runtime/python/okstra_ctl/context_cost.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
 import sys
 from pathlib import Path
@@ -143,6 +144,19 @@ def _is_timestamped_legacy_artifact(path: Path) -> bool:
     return bool(TIMESTAMPED_ARTIFACT_RE.search(path.name))
 
 
+def _okstra_asset_home() -> Path:
+    """자산을 읽을 okstra 홈. `OKSTRA_HOME` 이 있으면 그쪽이다.
+
+    종전에는 `Path.home() / ".okstra"` 를 그대로 박아, 홈을 갈아끼운 호출자가
+    실제 사용자 설치본을 읽었다. `find_asset_root` 의 docstring 이 규정한 대로
+    `OKSTRA_HOME` 이 유일한 격리 이음새이므로 여기서도 그것을 먼저 본다.
+    실측: e2e scenario-23 이 샌드박스 홈을 지정하고도 `~/.okstra/templates/`
+    를 보고해, 설치본이 있는 기계와 없는 기계의 출력이 달랐다.
+    """
+    override = os.environ.get("OKSTRA_HOME")
+    return Path(override) if override else Path.home() / ".okstra"
+
+
 def _installed_or_dev(installed: Path, dev_relative: str) -> Path:
     """Prefer the user-machine install (what production runs read); fall back
     to the repo dev tree when running from an uninstalled checkout."""
@@ -153,7 +167,7 @@ def _installed_or_dev(installed: Path, dev_relative: str) -> Path:
 
 def _runtime_template(filename: str) -> Path:
     return _installed_or_dev(
-        Path.home() / ".okstra" / "templates" / filename,
+        _okstra_asset_home() / "templates" / filename,
         f"templates/{filename}",
     )
 
@@ -223,7 +237,7 @@ def _skill_assets_metric() -> dict:
     skill bodies + worker agent specs. These dominate the fixed per-run
     instruction footprint and are the prompt-diet ranking input."""
     entries = []
-    okstra_home = Path.home() / ".okstra"
+    okstra_home = _okstra_asset_home()
     claude_home = Path.home() / ".claude"
     for name in HOT_PATH_LEAD_RESOURCES:
         path = _installed_or_dev(

package/runtime/python/okstra_ctl/convergence.py

@@ -69,7 +69,12 @@ class RunArtifactAuthority:
 
 def validated_run_authority(manifest_path: Path) -> RunArtifactAuthority:
     supplied = Path(manifest_path)
-    if not supplied.is_absolute() or supplied.absolute() != supplied.resolve():
+    if not supplied.is_absolute():
+        # 같은 세션의 `team dispatch`·`agent-prompt materialize`·`convergence
+        # prepare-groups` 는 상대경로를 받는다. 이 명령만 거절하면 같은 값이
+        # 명령마다 다르게 취급된다. 심링크 없는 절대경로라는 요구는 그대로다.
+        supplied = Path.cwd() / supplied
+    if supplied.absolute() != supplied.resolve():
         raise ConvergenceContractError("run manifest path is not canonical")
     payload = load_owned_json_object(supplied)
     execution_manifest = None

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -7,10 +7,12 @@ import subprocess
 import time
 from dataclasses import dataclass, field, replace
 from datetime import datetime, timezone
+import os
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from .dispatch_state import (
+    CompletedWithoutResultError,
     BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
     BACKEND_MIXED,
@@ -1017,28 +1019,20 @@ def _translator_job_from_reservation(
         for row in collection
         if isinstance(row, Mapping)
     }
-    candidates: list[Mapping[str, Any]] = []
-    for path in sorted(reservation_root.glob("*.json")):
-        reservation = _load_json_object(path, "agent invocation reservation")
-        if (
-            set(reservation) == _TRANSLATOR_RESERVATION_KEYS
-            and reservation.get("schemaVersion") == "2.0"
-            and reservation.get("executionIdentityVersion") == 2
-            and reservation.get("assignmentRef") == "translator"
-            and reservation.get("audience") == "translator"
-            and reservation.get("dispatchKind") == "translator"
-            and reservation.get("dutyId") == "translator"
-            and reservation.get("participantRef") == execution.get("participantRef")
-            and reservation.get("roleExecutionRef") == execution.get("roleExecutionRef")
-            and _build_dispatch_id(
-                str(reservation.get("invocationId") or ""),
-                int(reservation.get("attempt") or 0),
-            ) not in dispatched_ids
-        ):
-            candidates.append(reservation)
+    run_manifest_rel = _string_value(manifest.get("runManifestPath"))
+    candidates, seen = _translator_reservation_candidates(
+        project_root,
+        reservation_root,
+        execution=execution,
+        dispatched_ids=dispatched_ids,
+        run_manifest_rel=run_manifest_rel,
+    )
     if len(candidates) != 1:
+        run_label = run_manifest_rel or "run manifest path unknown"
         raise DispatchError(
-            "translator dispatch requires exactly one canonical invocation reservation"
+            "translator dispatch requires exactly one canonical invocation "
+            f"reservation for this run ({run_label}); found {len(candidates)}. "
+            "Translator reservations seen: " + ("; ".join(seen) if seen else "none")
         )
     reservation = candidates[0]
     prompt_path = _resolve_project_path(
@@ -1098,6 +1092,86 @@ def _translator_job_from_reservation(
     )
 
 
+def _translator_reservation_candidates(
+    project_root: Path,
+    reservation_root: Path,
+    *,
+    execution: Mapping[str, Any],
+    dispatched_ids: set[str],
+    run_manifest_rel: str,
+) -> tuple[list[Mapping[str, Any]], list[str]]:
+    """이 run 이 디스패치할 수 있는 translator 예약과, 본 예약 전부의 요약.
+
+    예약 디렉터리(`prompts/.agent-invocations/`)는 run 이 아니라 task type 단위라
+    같은 task 의 이전 run 이 남긴 translator 예약이 함께 놓인다. translator 는
+    `assignmentRef` 가 접미 없는 `translator` 하나이고, 이전 run 의 디스패치는
+    이번 run 의 team-state 에 없으므로 "아직 디스패치 안 됨" 으로 읽혀 후보가
+    둘이 됐다 — 두 번째 run 부터 번역이 영영 막혔다(2026-09-03 실측,
+    fontsninja-v3-site dev-10626-1 r02·r04). 예약 자체는 run 을 모르지만 그 옆의
+    `.meta.json` 은 `contractSource.runManifestPath` 로 자기 run 을 안다. 그
+    값을 이번 run 의 `runManifestPath` 와 대조한다. 매니페스트가 그 경로를 안
+    가진 레거시 run 은 종전대로 run 을 가리지 않는다.
+    """
+    candidates: list[Mapping[str, Any]] = []
+    seen: list[str] = []
+    for path in sorted(reservation_root.glob("*.json")):
+        reservation = _load_json_object(path, "agent invocation reservation")
+        if not (
+            set(reservation) == _TRANSLATOR_RESERVATION_KEYS
+            and reservation.get("schemaVersion") == "2.0"
+            and reservation.get("executionIdentityVersion") == 2
+            and reservation.get("assignmentRef") == "translator"
+            and reservation.get("audience") == "translator"
+            and reservation.get("dispatchKind") == "translator"
+            and reservation.get("dutyId") == "translator"
+        ):
+            continue
+        invocation_id = str(reservation.get("invocationId") or "")
+        reservation_run = _reservation_run_manifest_rel(project_root, reservation)
+        dispatched = _build_dispatch_id(
+            invocation_id, int(reservation.get("attempt") or 0),
+        ) in dispatched_ids
+        seen.append(
+            f"{invocation_id} (run {reservation_run or 'unknown'}"
+            + (", dispatched" if dispatched else "")
+            + ")"
+        )
+        if dispatched:
+            continue
+        if (
+            reservation.get("participantRef") != execution.get("participantRef")
+            or reservation.get("roleExecutionRef") != execution.get("roleExecutionRef")
+        ):
+            continue
+        if run_manifest_rel and (
+            reservation_run is None
+            or os.path.normpath(reservation_run) != os.path.normpath(run_manifest_rel)
+        ):
+            continue
+        candidates.append(reservation)
+    return candidates, seen
+
+
+def _reservation_run_manifest_rel(
+    project_root: Path, reservation: Mapping[str, Any],
+) -> str | None:
+    """예약 옆 `.meta.json` 의 `contractSource.runManifestPath`. 못 읽으면 None."""
+    metadata_value = _string_value(reservation.get("metadataPath"))
+    if not metadata_value:
+        return None
+    try:
+        metadata = _load_json_object(
+            _resolve_project_path(project_root, metadata_value),
+            "agent invocation metadata",
+        )
+    except DispatchError:
+        return None
+    source = metadata.get("contractSource")
+    if not isinstance(source, Mapping):
+        return None
+    return _string_value(source.get("runManifestPath")) or None
+
+
 def _translator_prompt_outputs(
     project_root: Path, prompt_path: Path,
 ) -> tuple[Path, Path]:
@@ -1928,10 +2002,10 @@ def _finish_attempt(
         "mutation-present-unresolved",
     }:
         reason = _mutation_failure_reason(mutation)
-        _transition_job_status(plan, job, "error", reason)
         _update_dispatch_status(
             plan.team_state_path, job, attempt, "error", reason
         )
+        _transition_job_status(plan, job, "error", reason)
         details = _failure_details(job, attempt, outcome, reason)
         details["mutationAudit"] = mutation.change_summary()
         _append_event(plan, "worker-failed", details)
@@ -1940,13 +2014,20 @@ def _finish_attempt(
     settlement = _settle(plan, job, attempt, outcome)
     if settlement.completed:
         result_link = _link_result(plan, job, attempt)
-        _transition_job_status(plan, job, "completed", "")
+        # 디스패치 행을 먼저 종결한다. 명부 전이가 거절될 수 있고, 그 거절이
+        # 행보다 앞서면 행은 `running` 으로 남아 다음 await 가 같은 sidecar 를
+        # 다시 읽고 같은 자리에서 죽는다(`_link_result` 와 같은 결함 형태).
+        roster_refusal = _transition_roster_completed(plan, job, attempt)
         _update_dispatch_status(
             plan.team_state_path,
             job,
             attempt,
             "completed",
-            "; ".join(part for part in (settlement.note, result_link["reason"]) if part),
+            "; ".join(
+                part
+                for part in (settlement.note, result_link["reason"], roster_refusal)
+                if part
+            ),
         )
         details = _result_details(job, attempt, outcome)
         details["resultLink"] = result_link
@@ -1961,8 +2042,8 @@ def _finish_attempt(
         return False
     reason = settlement.reason
     status = "timeout" if outcome.timeout else "error"
-    _transition_job_status(plan, job, status, reason)
     _update_dispatch_status(plan.team_state_path, job, attempt, status, reason)
+    _transition_job_status(plan, job, status, reason)
     details = _failure_details(job, attempt, outcome, reason)
     if settlement.error_log_append is not None:
         details["errorLogAppend"] = settlement.error_log_append
@@ -1973,6 +2054,35 @@ def _finish_attempt(
     return mutation.retry_allowed if mutation is not None else True
 
 
+def _transition_roster_completed(
+    plan: DispatchPlan, job: WorkerJob, attempt: int,
+) -> str:
+    """명부 행을 completed 로 올리되, 거절은 이벤트와 사유로 돌려세운다.
+
+    명부는 `resultPath` 파일이 있어야 completed 를 받는다
+    (`_reject_completed_without_result`). 디스패치의 산출물은 전부 있는데 그
+    파일이 다른 경우 — 리드가 명부와 다른 포인터 경로로 재디스패치한 뒤 —
+    그 거절이 예외로 `await` 를 죽였고, 행이 `running` 으로 남아 다음 await 도
+    같은 자리에서 죽었다. 실측(2026-09-02~03, fontsninja-v3-site dev-10626-1
+    r04): report-writer a2·a3 행이 그렇게 남아, 정본 경로로 보낸 a4 가 도는
+    동안에도 `await` 가 즉시 exit 2 였다.
+
+    명부는 손대지 않는다 — 그 불변식(completed ⇒ 파일 있음)은 그대로다. 정본
+    경로를 쓰는 다음 디스패치가 그 파일을 쓰면 그때 completed 가 된다.
+    """
+    try:
+        _transition_job_status(plan, job, "completed", "")
+    except CompletedWithoutResultError as exc:
+        reason = f"roster not updated: {exc}"
+        _append_event(plan, "worker-roster-not-updated", {
+            **_event_execution_identity(job, attempt),
+            "dispatchWorkerResultPath": str(job.worker_result_path),
+            "reason": reason,
+        })
+        return reason
+    return ""
+
+
 def _audit_attempt(
     job: WorkerJob,
     outcome: WorkerOutcome,