okstra 0.187.0 → 0.188.0

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -26,7 +26,7 @@ import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable, Mapping, Sequence
+from typing import Any, Callable, Iterable, Mapping, Sequence
 
 from . import cmux
 from .agent.invocation import (
@@ -985,6 +985,25 @@ def _project_or_absolute(project_root: Path, value: str) -> Path:
     return path if path.is_absolute() else project_root / path
 
 
+def prompt_anchor_values(
+    prompt_path: Path, labels: Iterable[str],
+) -> dict[str, str]:
+    """`**<label>:** <value>` 앵커 줄을 라벨별로 읽는다. 첫 번째 값이 이긴다.
+
+    앵커는 materialize 가 문서 머리에 쓰고, 본문(리드 지시문)이 같은 라벨을
+    예시로 되풀이할 수 있다. `_prompt_write_paths` 는 마지막 값을 취하는데
+    그것은 write-policy 의 허용 집합을 넓힐 뿐이지만, 여기서 읽는 값은 워커가
+    실제로 쓰는 경로의 판정 기준이므로 머리의 것이어야 한다.
+    """
+    values: dict[str, str] = {}
+    for line in prompt_path.read_text(encoding="utf-8").splitlines():
+        for label in labels:
+            prefix = f"**{label}:** "
+            if label not in values and line.startswith(prefix):
+                values[label] = line.removeprefix(prefix).strip()
+    return values
+
+
 def _execution_dispatch_round(dispatch_kind: str) -> int:
     prefix = "reverify-r"
     if not dispatch_kind.startswith(prefix):
@@ -1477,6 +1496,14 @@ def _task_project_root(team_state_path: Path) -> Path | None:
     return None
 
 
+class CompletedWithoutResultError(DispatchError):
+    """명부의 `resultPath` 파일 없이 `completed` 로 적으려 했다.
+
+    `_finish_attempt` 가 이 거절을 데이터로 돌려세우기 위해 구분한다 — 디스패치
+    자신의 산출물은 있는데 명부가 가리키는 파일이 다른 경우다.
+    """
+
+
 def _reject_completed_without_result(
     team_state_path: Path, worker_id: str, worker: Mapping[str, Any]
 ) -> None:
@@ -1505,7 +1532,7 @@ def _reject_completed_without_result(
         candidate = project_root / candidate
     if candidate.is_file():
         return
-    raise DispatchError(
+    raise CompletedWithoutResultError(
         f"worker {worker_id} cannot be recorded completed: its result "
         f"{relative} does not exist. Record the terminal status the dispatch "
         "actually reached (`error` / `timeout` / `not-run`) with a reason."
@@ -1676,7 +1703,7 @@ def worker_session_ids(
     for record in dispatches if isinstance(dispatches, list) else []:
         if not isinstance(record, Mapping):
             continue
-        if worker_id is not None and record.get("workerId") != worker_id:
+        if worker_id is not None and _dispatch_worker_key(record) != worker_id:
             continue
         session_id = str(record.get("sessionId") or "").strip()
         if session_id and session_id not in session_ids:
@@ -1684,6 +1711,27 @@ def worker_session_ids(
     return session_ids
 
 
+def _dispatch_worker_key(record: Mapping[str, Any]) -> str:
+    """The `workers[]` row a dispatch record belongs to.
+
+    A v1 record names it as `workerId`. A v2 record carries execution identity
+    instead and no `workerId` (`_dispatch_record`), so its row is the one the
+    roster keys off the assignment ref's last segment — `critic/scope` is the
+    row `scope`, `initial/claude-analyser` the row `claude-analyser` — the same
+    projection `v2_worker_state_key` makes for the jobs file. Matching on
+    `workerId` alone found no v2 record, so a pane worker's session id was never
+    read and every v2 pane worker stayed `unavailable` (observed 2026-09-02,
+    dev-10626 r04: the critic's session was on disk with 79 usage records).
+    """
+    worker_id = str(record.get("workerId") or "").strip()
+    if worker_id:
+        return worker_id
+    assignment_ref = record.get("assignmentRef")
+    if not isinstance(assignment_ref, str):
+        return ""
+    return assignment_ref.rsplit("/", 1)[-1].strip()
+
+
 def dispatch_result_path(
     worker_id: str,
     worker_result_path: Path,
@@ -2120,10 +2168,82 @@ def worker_jobs_from_file(
         for item in workers
         if isinstance(item, Mapping)
     ]
+    _validate_jobs_file_prompt_anchors(jobs)
     _validate_v2_jobs_file_authority(manifest, jobs)
     return jobs
 
 
+def _normalized_path(path: Path) -> Path:
+    return Path(os.path.normpath(path))
+
+
+def _validate_jobs_file_prompt_anchors(jobs: Sequence[WorkerJob]) -> None:
+    """jobs-file 의 결과 경로가 프롬프트 앵커와 같은 파일인지 본다.
+
+    워커는 프롬프트의 `**Result Path:**` 에 쓰고(포인터를 가진 report-writer 는
+    `**Worker Result Path:**` 에 포인터를), 수집기는 jobs-file 의
+    `workerResultPath` 를 기다린다. 두 값은 리드가 따로 적으므로 어긋날 수 있고,
+    어긋나면 워커가 결과를 다 써도 `required worker artifact was not produced`
+    로 끝나 같은 프롬프트가 한 번 더 돈다. 실측(2026-09-02, fontsninja-v3-site
+    dev-10626-1 error-analysis r04): 검증 디스패치 9건 중 8건이 이 형태였고
+    재시도 6건이 같은 이유로 실패했다.
+
+    report-writer 는 한 가지를 더 본다 — 프롬프트의 `**Result Path:**`(서술문)가
+    `dispatch_result_path` 가 정한 조립 입력과 같은가. 다르면 서술문은 써지지만
+    `report-finalize` 가 읽는 자리에는 아무것도 없다.
+
+    프롬프트 파일이 아직 없는 잡은 건너뛴다. 실제 디스패치는 같은 파일을
+    write-policy 검사(`_prompt_write_paths`)가 반드시 읽으므로 빠져나갈 자리가
+    없고, 단위 테스트의 빈 경로만 여기서 면제된다.
+    """
+    errors: list[str] = []
+    for job in jobs:
+        if not job.prompt_path.is_file():
+            continue
+        anchors = prompt_anchor_values(
+            job.prompt_path, ("Result Path", "Worker Result Path"),
+        )
+        label = (
+            "Worker Result Path"
+            if anchors.get("Worker Result Path")
+            else "Result Path"
+        )
+        declared = anchors.get(label)
+        if not declared:
+            continue
+        declared_path = _normalized_path(
+            _project_or_absolute(job.project_root, declared)
+        )
+        accepted = {
+            _normalized_path(path)
+            for path in (job.worker_result_path, *job.result_aliases)
+        }
+        if declared_path not in accepted:
+            errors.append(
+                f"{job.worker_id}: workerResultPath {job.worker_result_path} "
+                f"differs from the prompt's **{label}:** {declared_path}"
+            )
+        narrative = anchors.get("Result Path")
+        if (
+            label == "Worker Result Path"
+            and narrative
+            and _normalized_path(job.result_path)
+            != _normalized_path(job.worker_result_path)
+            and _normalized_path(_project_or_absolute(job.project_root, narrative))
+            != _normalized_path(job.result_path)
+        ):
+            errors.append(
+                f"{job.worker_id}: the prompt's **Result Path:** {narrative} is "
+                f"not the result this run assembles from ({job.result_path})"
+            )
+    if errors:
+        raise DispatchError(
+            "jobs file result paths differ from the prompt anchors — the worker "
+            "writes where the prompt says, so the jobs file must name that path: "
+            + "; ".join(errors)
+        )
+
+
 def _worker_job_from_file(
     project_root: Path,
     item: Mapping[str, Any],
@@ -2136,6 +2256,14 @@ def _worker_job_from_file(
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],
 ) -> WorkerJob:
+    # 빠진 필드를 한꺼번에 댄다. 하나씩 거절하던 동안 세 워커짜리 파일 하나를
+    # 통과시키는 데 dry-run 세 번이 들었다(2026-09-02 실측).
+    missing = _missing_required_strings(item)
+    if missing:
+        raise DispatchError(
+            "jobs file worker is missing required string fields: "
+            + ", ".join(missing)
+        )
     identity = worker_execution_identity(item)
     worker_id = (
         require_string(item, "workerId")
@@ -2218,6 +2346,25 @@ def _worker_job_from_file(
     )
 
 
+_V1_JOB_REQUIRED_STRINGS = (
+    "workerId", "promptPath", "workerResultPath", "modelExecutionValue", "role",
+)
+_V2_JOB_REQUIRED_STRINGS = (
+    "provider", "assignmentRef", "participantRef", "roleExecutionRef",
+    "executionLabel", "dutyId", "invocationRef", "promptPath",
+    "workerResultPath", "modelExecutionValue", "role",
+)
+
+
+def _missing_required_strings(item: Mapping[str, Any]) -> list[str]:
+    keys = (
+        _V2_JOB_REQUIRED_STRINGS
+        if item.get("schemaVersion") == "2.0"
+        else _V1_JOB_REQUIRED_STRINGS
+    )
+    return [key for key in keys if not string_value(item.get(key))]
+
+
 def worker_execution_identity(
     item: Mapping[str, Any],
 ) -> dict[str, Any] | None:

package/runtime/python/okstra_ctl/domain/worker_presentation.py

@@ -30,6 +30,8 @@ Sink = Callable[[str], str | None]
 Channel = Literal["stdout", "stderr"]
 SinkSpec = tuple[Channel, Sink]
 ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
+# 이벤트가 실어 온 토큰 사용량 스냅샷(공급자 어휘 그대로). 없으면 None.
+ObserveUsage = Callable[[Mapping[str, Any]], Mapping[str, Any] | None]
 
 WORKER = "worker"
 
@@ -113,6 +115,11 @@ class JsonEvents:
 
     normalise: Normalise
     observe: ObserveServedModel
+    # 어떤 CLI 는 토큰 사용량을 홈 디렉터리의 트랜스크립트가 아니라 이 스트림에만
+    # 싣는다(agy 의 `result.usage`). 어댑터가 그 스냅샷을 읽는 법을 넘기면
+    # 러너가 마지막 값을 status 사이드카에 적어, 수집기가 로그를 다시 파싱하지
+    # 않아도 된다. 어느 CLI 가 그런지는 이 계층이 알 필요도, 알아서도 안 된다.
+    observe_usage: ObserveUsage | None = None
     # 어떤 CLI 의 streaming-json 은 문장이 아니라 토큰을 한 줄씩 보낸다. 붙이지
     # 않으면 pane 이 한 글자 한 줄이 된다. 기본은 끄고, 그런 CLI 의 어댑터가 켠다 —
     # 어느 CLI 가 그런지는 이 계층이 알 필요도, 알아서도 안 되는 사실이다.

package/runtime/python/okstra_ctl/exact_coverage.py

@@ -7,6 +7,11 @@ from dataclasses import dataclass
 from typing import Literal
 
 
+# 판정 우선순위 — 여러 조건이 동시에 성립할 때 앞선 것이 이긴다. 저작 계약이
+# 이 순서를 작성자에게 말하므로 `calculate_exact_coverage` 의 분기와 함께 간다.
+COVERAGE_VERDICT_PRECEDENCE = ("contradicted", "under", "over", "exact")
+
+
 class ExactCoverageError(ValueError):
     """Raised when coverage input cannot define a valid comparison."""
 

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 import json
 import re
 from pathlib import Path
-from typing import Any
+from typing import Any, Mapping
 
 class SchemaError(ValueError):
     """Raised when a schema itself is malformed (e.g. a $ref points
@@ -334,6 +334,234 @@ class _Validator:
         self.errors.append(f"{_format_path(path)}: {message}")
 
 
+def verdict_token_rule(schema: Mapping[str, Any], task_type: str) -> tuple[str, ...]:
+    """이 task type 의 `finalVerdict.verdictToken` 에 스키마가 허용하는 값.
+
+    스키마는 `allOf` 의 if/then 가지로 세 묶음을 나눈다(분석형 enum,
+    final-verification enum, 나머지 `not-applicable` const). 작성기는 그 가지를
+    읽지 못해 `analysis-complete` 를 error-analysis 에 썼고(2026-09-02 실측),
+    조립이 아니라 HTML 렌더에서야 거절됐다. 여기서 뽑아 저작 계약에 싣는다.
+    가지가 없으면 빈 튜플이다 — 제약이 없다는 뜻이지 실패가 아니다.
+    """
+    def _walk(node: Any) -> tuple[str, ...]:
+        if isinstance(node, dict):
+            condition = node.get("if")
+            then = node.get("then")
+            if isinstance(condition, dict) and isinstance(then, dict):
+                header = (condition.get("properties") or {}).get("header") or {}
+                selector = (header.get("properties") or {}).get("taskType") or {}
+                allowed = selector.get("enum")
+                if allowed is None and "const" in selector:
+                    allowed = [selector["const"]]
+                if isinstance(allowed, list) and task_type in allowed:
+                    verdict = (then.get("properties") or {}).get("finalVerdict") or {}
+                    token = (verdict.get("properties") or {}).get("verdictToken") or {}
+                    if "const" in token:
+                        return (str(token["const"]),)
+                    if isinstance(token.get("enum"), list):
+                        return tuple(str(value) for value in token["enum"])
+            for value in node.values():
+                found = _walk(value)
+                if found:
+                    return found
+        elif isinstance(node, list):
+            for value in node:
+                found = _walk(value)
+                if found:
+                    return found
+        return ()
+
+    return _walk(dict(schema))
+
+
+def task_block_rules(schema: Mapping[str, Any], block_key: str) -> tuple[str, ...]:
+    """이 task type 의 데이터 블록(`properties[block_key]`)이 요구하는 모양을 한
+    객체당 한 줄의 저작 계약 문장으로 편다.
+
+    리드는 report-writer 지시문을 쓸 때 블록 안쪽의 필수 필드·식별자 패턴·
+    정수 필드·고정 길이 배열을 알 길이 프롬프트 경로에 없어 스키마 JSON 을
+    손으로 파싱했고, 그래도 놓친 만큼 같은 리포트를 다시 썼다(2026-09-03 실측,
+    dev-10626 implementation-option-selection: 네 회차). 여기서 뽑아 합성 묶음의
+    저작 계약에 싣는다. 블록이 없거나 객체가 아니면 빈 튜플이다.
+
+    경로는 스키마 키다(`rankedOptions[]` 는 `- Item N` 목록의 각 항목). 같은
+    정의(`$ref`)가 두 경로에 나오면 두 번째는 첫 경로를 가리킨다 — 랭킹 옵션과
+    감사 항목이 하위 구조 여섯 개를 공유한다.
+    """
+    root = dict(schema)
+    block = (root.get("properties") or {}).get(block_key)
+    if not isinstance(block, dict):
+        return ()
+    lines: list[str] = []
+    described: dict[str, str] = {}
+    _describe_object(root, block, block_key, lines, described)
+    return tuple(lines)
+
+
+def _resolved(root: dict, node: Any) -> tuple[dict, str | None]:
+    """`$ref` 를 풀고, allOf 가지의 properties/required 를 얕게 합친다.
+
+    반환값의 둘째는 이 노드가 가리킨 정의 이름 — 같은 정의를 두 경로에서
+    두 번 펴지 않기 위해 쓴다.
+    """
+    if not isinstance(node, dict):
+        return {}, None
+    ref_name: str | None = None
+    if "$ref" in node:
+        ref_name = str(node["$ref"]).rsplit("/", 1)[-1]
+        node = _resolve_ref(node["$ref"], root)
+    merged = dict(node)
+    for branch in node.get("allOf") or []:
+        resolved, branch_ref = _resolved(root, branch)
+        if ref_name is None:
+            ref_name = branch_ref
+        properties = dict(merged.get("properties") or {})
+        for key, value in (resolved.get("properties") or {}).items():
+            existing = properties.get(key)
+            properties[key] = {**existing, **value} if isinstance(existing, dict) else value
+        merged["properties"] = properties
+        merged["required"] = list(
+            dict.fromkeys([*(merged.get("required") or []), *(resolved.get("required") or [])])
+        )
+        for keyword in ("type", "pattern", "const", "enum", "minItems", "maxItems", "items", "prefixItems"):
+            if keyword in resolved and keyword not in merged:
+                merged[keyword] = resolved[keyword]
+    return merged, ref_name
+
+
+def _describe_object(
+    root: dict, node: Any, path: str, lines: list[str], described: dict[str, str],
+) -> None:
+    schema, ref_name = _resolved(root, node)
+    if ref_name and ref_name in described:
+        lines.append(f"`{path}`: same shape as `{described[ref_name]}`")
+        return
+    if ref_name:
+        described[ref_name] = path
+    properties = schema.get("properties") or {}
+    required = [key for key in (schema.get("required") or []) if isinstance(key, str)]
+    optional = [key for key in properties if key not in required]
+    parts: list[str] = []
+    if required:
+        parts.append("required " + ", ".join(f"`{key}`" for key in required))
+    if optional:
+        parts.append("optional " + ", ".join(f"`{key}`" for key in optional))
+    nested: list[tuple[str, Any]] = []
+    for key, value in properties.items():
+        constraint = _describe_property(root, value, f"{path}.{key}", nested)
+        if constraint:
+            parts.append(f"`{key}` {constraint}")
+    lines.append(f"`{path}`: " + "; ".join(parts))
+    for child_path, child in nested:
+        _describe_object(root, child, child_path, lines, described)
+
+
+def _describe_property(
+    root: dict, node: Any, path: str, nested: list[tuple[str, Any]],
+) -> str:
+    """한 속성의 제약을 한 구절로. 객체 자식은 `nested` 에 넣어 자기 줄을 받는다."""
+    schema, _ref = _resolved(root, node)
+    branches = schema.get("oneOf") or schema.get("anyOf") or []
+    nullable = False
+    if branches:
+        resolved_branches = [_resolved(root, branch)[0] for branch in branches]
+        nullable = any(branch.get("type") == "null" for branch in resolved_branches)
+        others = [branch for branch in branches if _resolved(root, branch)[0].get("type") != "null"]
+        if len(others) == 1:
+            schema = _resolved(root, others[0])[0] | {"__branch": others[0]}
+    types = schema.get("type")
+    types = types if isinstance(types, list) else ([types] if types else [])
+    if "null" in types:
+        nullable = True
+        types = [item for item in types if item != "null"]
+    suffix = " or `_none_`" if nullable else ""
+    if "const" in schema:
+        return f"exactly `{schema['const']}`{suffix}"
+    if isinstance(schema.get("enum"), list):
+        return "one of " + ", ".join(f"`{value}`" for value in schema["enum"]) + suffix
+    if "properties" in schema or types == ["object"]:
+        nested.append((path, schema.get("__branch", node)))
+        return f"object (see `{path}`){suffix}"
+    if types == ["array"] or "items" in schema or "prefixItems" in schema:
+        return _describe_array(root, schema, path, nested) + suffix
+    if types == ["integer"]:
+        return "integer" + _range(schema) + suffix
+    if types == ["number"]:
+        return "number" + _range(schema) + suffix
+    if types == ["string"]:
+        pattern = schema.get("pattern")
+        return (f"matches `{pattern}`" if pattern else "string") + suffix
+    if types == ["boolean"]:
+        return "`true` or `false`" + suffix
+    return ""
+
+
+def _describe_array(
+    root: dict, schema: dict, path: str, nested: list[tuple[str, Any]],
+) -> str:
+    minimum = schema.get("minItems")
+    maximum = schema.get("maxItems")
+    if maximum == 0:
+        return "must be empty (`> _none_`)"
+    if minimum is not None and minimum == maximum:
+        size = f"exactly {maximum} items"
+    else:
+        bounds = [
+            text
+            for text in (
+                f"at least {minimum}" if minimum else "",
+                f"at most {maximum}" if maximum is not None else "",
+            )
+            if text
+        ]
+        size = "list" + (f" ({', '.join(bounds)})" if bounds else "")
+    prefix_items = schema.get("prefixItems")
+    if isinstance(prefix_items, list) and prefix_items:
+        order = _prefix_order(root, prefix_items)
+        first, _ = _resolved(root, prefix_items[0])
+        if "properties" in first:
+            nested.append((f"{path}[]", prefix_items[0]))
+            return f"{size} in this order: {order}; each item (see `{path}[]`)"
+        return f"{size} in this order: {order}"
+    items = schema.get("items")
+    item_schema, _ = _resolved(root, items) if items is not None else ({}, None)
+    if "properties" in item_schema:
+        nested.append((f"{path}[]", items))
+        return f"{size} of objects (see `{path}[]`)"
+    if "pattern" in item_schema:
+        return f"{size} of strings matching `{item_schema['pattern']}`"
+    if isinstance(item_schema.get("enum"), list):
+        return f"{size}, each one of " + ", ".join(f"`{value}`" for value in item_schema["enum"])
+    if item_schema.get("type"):
+        return f"{size} of {item_schema['type']}"
+    return size
+
+
+def _prefix_order(root: dict, prefix_items: list) -> str:
+    """고정 순서 배열의 각 자리가 못 박은 값 — `criterion` 처럼 상수인 속성."""
+    labels: list[str] = []
+    for item in prefix_items:
+        merged, _ = _resolved(root, item)
+        consts = [
+            f"`{key}`=`{value['const']}`"
+            for key, value in (merged.get("properties") or {}).items()
+            if isinstance(value, dict) and "const" in value
+        ]
+        labels.append(", ".join(consts) if consts else "item")
+    return "; ".join(labels)
+
+
+def _range(schema: dict) -> str:
+    low, high = schema.get("minimum"), schema.get("maximum")
+    if low is not None and high is not None:
+        return f" {low}..{high}"
+    if low is not None:
+        return f" >= {low}"
+    if high is not None:
+        return f" <= {high}"
+    return ""
+
+
 def validate(data: Any, schema: dict) -> list[str]:
     """Validate ``data`` against ``schema``. Returns the list of human-
     readable error messages (empty when the data is valid)."""

package/runtime/python/okstra_ctl/implementation_options.py

@@ -26,6 +26,11 @@ MIN_CRITERION_VALUE = 1
 MAX_CRITERION_VALUE = 5
 MIN_FEASIBLE_VOTES = 2
 MAX_RANKED_OPTIONS = 3
+# 분석자 한 명이 낼 수 있는 원시 후보(`rankedOptions` + `candidateAudit`) 수.
+# 저작 계약(`report_synthesis_packet`)이 같은 값을 작성자에게 말한다 — 리터럴로
+# 두던 동안 계약은 `proposedBy` 를 `string` 으로만 적었고, 리드가 세 이름을
+# 쉼표로 이어 쓰라고 지시해 한 라운드를 버렸다(2026-09-03 실측).
+MAX_RAW_CANDIDATES_PER_ANALYSER = 3
 CANDIDATE_COMPARISON_ROUTING = "pending-direction-selection"
 NO_VALID_OPTIONS_ROUTING = "blocked"
 
@@ -362,9 +367,9 @@ def _validate_candidate_ids_and_caps(
     analyser_set = set(participating_analysers)
     if any(worker not in analyser_set for worker in counts):
         errors.append("every candidate proposedBy must name a participating analyser")
-    if any(count > 3 for count in counts.values()):
+    if any(count > MAX_RAW_CANDIDATES_PER_ANALYSER for count in counts.values()):
         errors.append("each analyser may submit at most three raw candidates")
-    if len(candidate_ids) > len(analyser_set) * 3:
+    if len(candidate_ids) > len(analyser_set) * MAX_RAW_CANDIDATES_PER_ANALYSER:
         errors.append("total raw candidates exceed analyser count times three")
 
 

package/runtime/python/okstra_ctl/render_final_report.py

@@ -480,7 +480,7 @@ def _enforce_schema(data: dict) -> dict | None:
 # 구체버전 계열로 돌았는지" 가독성만 준다. CLI 가 실제 고른 버전과 다를 수
 # 있으나 표시이므로 실행에는 무해하다. 새 버전이 나오면 여기만 갱신한다.
 _DISPLAY_CONCRETE_CLAUDE = {
-    "fable": "claude-fable-5",
+    "fable": "claude-fable-5-1",
     "opus": "claude-opus-5",
     "sonnet": "claude-sonnet-5",
     "haiku": "claude-haiku-4-5",

package/runtime/python/okstra_ctl/report_finalize.py

@@ -349,6 +349,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 # 방향 선택 게이트를 통과할 수 없었다.
                 "--source-report",
                 sidecar_source_rel(markdown_path),
+                # 머리말 소요 시간의 출처. 보고서 seq 로 되짚으면 seq 가 갈린
+                # run 의 team-state 를 읽는다 — 여기서는 이미 알고 있다.
+                "--team-state",
+                str(ctx.team_state_path),
             ],
         ),
         (
@@ -745,7 +749,9 @@ def _parser() -> argparse.ArgumentParser:
         required=True,
         help="final-report record (.data.json); a leftover markdown path still locates the sibling record",
     )
-    parser.add_argument("--workspace-root", required=True)
+    # `okstra report-finalize` 래퍼(src/lib/python-command.mts)가 넣고, 사용자가
+    # 직접 주면 거절한다. usage 에 필수로 찍히면 그 거절과 모순되므로 감춘다.
+    parser.add_argument("--workspace-root", required=True, help=argparse.SUPPRESS)
     parser.add_argument(
         "--team-state",
         default="",