okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/worker_artifacts.py

@@ -1,35 +1,94 @@
-"""Provider-registry-derived worker artifact paths."""
+"""로스터 worker_id 어휘와 그로부터 나오는 아티팩트 경로."""
 from __future__ import annotations
 
 from pathlib import Path
 from typing import Any, Mapping
 
+from .domain.role import ROLE_DEFINITIONS
 from .models import provider_ids
 
+# worker_id 접미사로 쓰이는 역할 토큰 — 역할 카탈로그가 정본이다.
+# 이 모듈은 leaf 로 남아야 한다(`worker_prompt_body` 를 끌어오면
+# `run_context` ↔ `path_hints` 순환이 된다). 그래서 고정 worker_id 인
+# `report-writer` 는 이름으로 특수 처리하지 않는다 — 마지막 하이픈 뒤가
+# `writer` 라 어느 역할 토큰과도 맞지 않아 자연히 접미사 없음으로 떨어진다.
+_ROLE_SUFFIX_TOKENS = frozenset(
+    definition.id for definition in ROLE_DEFINITIONS
+)
 
-def artifact_worker_ids() -> list[str]:
-    """All analysis worker ids plus the non-analysis report writer slot."""
-    return [*provider_ids("analyser"), "report-writer"]
 
+def worker_role_suffix(worker_id: str) -> str:
+    """worker_id 에서 provider 뒤에 붙은 역할 접미사. 없으면 빈 문자열.
 
-def artifacts_from_context(
-    ctx: Mapping[str, Any], *, relative: bool
-) -> dict[str, dict[str, str]]:
-    """Derive prompt/result/error paths without provider-specific branches."""
+    `claude-verifier` → `verifier`, `claude-verifier-2` → `verifier-2`,
+    `claude` → `""`, `report-writer` → `""`.
+    """
+    stem, separator, tail = worker_id.rpartition("-")
+    ordinal = ""
+    if separator and tail.isdigit():
+        ordinal, worker_id = f"-{tail}", stem
+    _, separator, role = worker_id.rpartition("-")
+    if not separator or role not in _ROLE_SUFFIX_TOKENS:
+        return ""
+    return f"{role}{ordinal}"
+
+
+def worker_provider_id(worker_id: str) -> str:
+    """역할 접미사가 붙은 worker_id 에서 provider id 를 되돌린다.
+
+    한 provider 가 로스터에서 두 슬롯 이상을 차지하면 슬롯마다
+    `claude-implementer` · `claude-verifier` 처럼 역할이 붙는다. 그 접미사를 떼면
+    provider registry 가 아는 id 로 돌아간다 — 접미사가 없는 id 는 그대로 남는다.
+    """
+    suffix = worker_role_suffix(worker_id)
+    return worker_id[: -(len(suffix) + 1)] if suffix else worker_id
+
+
+def roster_worker_ids(ctx: Mapping[str, Any]) -> list[str]:
+    """이 런이 실제로 여는 worker_id 목록.
+
+    같은 provider 가 실행자와 검증자를 겸하면 로스터에 `claude` 와 `claude-2` 가
+    함께 서므로, provider registry 목록으로는 두 번째 슬롯의 경로를 만들 수 없다.
+    로스터를 싣지 않은 ctx(경로 힌트에서 되살린 레거시 컨텍스트)에서는 registry
+    목록으로 돌아간다 — 그 경우 접미사 id 는 애초에 등장하지 않는다.
+    """
+    roster = [
+        part.strip()
+        for part in str(ctx.get("RECOMMENDED_ANALYSERS", "") or "").split(",")
+        if part.strip()
+    ]
+    return roster or [*provider_ids("analyser"), "report-writer"]
+
+
+def worker_artifact_paths(
+    ctx: Mapping[str, Any], worker_id: str, *, relative: bool
+) -> dict[str, str]:
+    """worker_id 하나의 prompt/result/errors 경로.
+
+    경로는 id 에서 직접 만들어지므로 로스터에 없는 id 로도 부를 수 있다 —
+    payload 로만 전달된 워커 행을 되살릴 때 필요하다.
+    """
     prompt_root = _context_root(ctx, "RUN_PROMPTS", relative)
     result_root = _context_root(ctx, "WORKER_RESULTS", relative)
     task_type = str(ctx.get("TASK_TYPE_SEGMENT", ""))
     prompt_suffix = f"-{task_type}-{ctx.get('RUN_PROMPTS_SEQ', '')}"
     result_suffix = f"-{task_type}-{ctx.get('WORKER_RESULTS_SEQ', '')}"
     return {
-        worker_id: {
-            "promptPath": str(prompt_root / f"{worker_id}-worker-prompt{prompt_suffix}.md"),
-            "resultPath": str(result_root / f"{worker_id}-worker{result_suffix}.md"),
-            "errorsSidecarPath": str(
-                result_root / f"{worker_id}-worker-errors{result_suffix}.json"
-            ),
-        }
-        for worker_id in artifact_worker_ids()
+        "promptPath": str(prompt_root / f"{worker_id}-worker-prompt{prompt_suffix}.md"),
+        "resultPath": str(result_root / f"{worker_id}-worker{result_suffix}.md"),
+        "errorsSidecarPath": str(
+            result_root / f"{worker_id}-worker-errors{result_suffix}.json"
+        ),
+    }
+
+
+def artifacts_from_context(
+    ctx: Mapping[str, Any], *, relative: bool
+) -> dict[str, dict[str, str]]:
+    """이 런의 로스터 worker_id 별 prompt/result/errors 경로."""
+    return {
+        worker_id: worker_artifact_paths(ctx, worker_id, relative=relative)
+        for worker_id in roster_worker_ids(ctx)
     }
 
 

package/runtime/python/okstra_ctl/worker_audit_check.py

@@ -18,8 +18,30 @@ from okstra_ctl.worker_audit_ledger import (
 )
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra worker-audit-check --run-dir <runs/<task-type>/> --task-type <type> \
+    --seq <nnn> [--worker <id>]
+
+  --run-dir    the run directory; worker-results/ and prompts/ hang off it
+  --worker     check only this worker (default: every worker in the run)
+
+Emits one JSON object — `{ok, failures[]}` — and exits 2 when failures[] is
+non-empty, 0 otherwise.
+
+Runs the Phase 7 audit-sidecar rules now, while the worker session is still
+alive: that every result file carries no `## 0. Reading Confirmation` heading,
+that its audit sidecar exists, and that every backticked `path:line` citation
+has a matching Evidence read row in that sidecar.
+
+Call it right after collecting a worker result. The same failure at Phase 7
+leaves only a retroactive edit — which breaks the audit chain — or a failed run.
+"""
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra worker-audit-check",
         description="Check one run's worker audit sidecars (read-only).",
     )

package/runtime/python/okstra_ctl/worker_dispatch.py

@@ -65,8 +65,29 @@ def _backend_payload(backend_plan, *, dry_run: bool) -> dict[str, Any]:
     return payload
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra worker-dispatch --project-root <dir> --run-manifest <path> \
+    [--workers <cli-assigned-worker-ids>] [--dry-run] \
+    [--idle-timeout-seconds <n>]
+
+This command reads a prepared run manifest and dispatches only assignments
+whose persisted runner is 'cli-wrapper'. It verifies each invocation contract
+before execution and uses the persisted provider, model, and registered CLI.
+Native-session assignments remain owned by the active host session.
+
+Missing worker prompt files are generated automatically from the immutable run snapshot.
+Existing prompt and metadata files are never overwritten.
+When report-writer completes, this command also runs the idempotent post-report
+steps: token-usage substitution, render-views, spawn-followups, and validate-run.
+
+  --workspace-root and --okstra-bin are owned by this command.
+"""
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra worker-dispatch",
         description="Dispatch verified CLI-backed workers for a prepared run.",
     )

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -404,8 +404,41 @@ def probe_target(team_state_value: str, worker_id: str) -> ProbeTarget:
     return ProbeTarget(mode, artifact, dispatched_at, result_path)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra worker-liveness [--team-state <path> --worker <worker-id>]...
+                         [--max-idle <seconds>] [--launch-grace <seconds>] [--json]
+  okstra worker-liveness --wait [--team-state <path> --worker <worker-id>]...
+                         [--interval <seconds>] [--timeout <seconds>]
+
+--wait polls until every named worker's persisted resultPath lands (exit 0), one
+          worker probes unhealthy (exit 1), or --timeout passes (exit 2).
+          Defaults: --interval 20, --timeout 2400. Run it as a background
+          command and branch on the exit code. Use this instead of writing a
+          poll loop: both the "is it done" test (the persisted resultPath, not a
+          filename you assemble) and the "is it dead" test live in here, and a
+          hand-written loop re-derives them and gets one wrong. A worker row
+          without a resultPath is refused rather than waited on by guess.
+
+--team-state and --worker select one pending worker. The worker row's
+          livenessMode picks the probe: audit-heartbeat reads the in-process
+          worker audit sidecar path and reports stalled past the heartbeat
+          cadence; wrapper-status reports did-not-launch when no prompt sibling
+          .log or .status.json exists past the launch grace. Both graces begin
+          at workers[].startedAt, never at an artifact mtime — the audit sidecar
+          is reused on re-dispatch, so the previous attempt's last heartbeat is
+          not this dispatch's signal.
+
+Output: JSON { ok, checkedAt, probes[], unhealthy[] }, plus { outcome, pending[],
+waitedSeconds } under --wait. Exit 1 when any worker is stalled or did not
+launch, so a caller can branch on the exit code. Read-only: it reports, it never
+kills or re-dispatches.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra worker-liveness",
         description="Report whether pending workers are still alive (read-only).",
     )

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -22,6 +22,7 @@ def analysis_prompt_body(
     worker_id: str,
     model: str,
     plan: PromptPlan,
+    approved_plan_path: str = "",
 ) -> list[str]:
     """Render the provider-neutral body for an initial analysis audience."""
     label = analysis_worker_label(worker_id)
@@ -40,7 +41,7 @@ def analysis_prompt_body(
         f"- Task type: `{_require_string(manifest, 'taskType')}`",
         "",
         "## Inputs",
-        *analysis_input_lines(manifest, active_context, plan),
+        *analysis_input_lines(manifest, active_context, plan, approved_plan_path),
         "",
         mcp_pointer_line(),
         "",
@@ -54,10 +55,22 @@ def analysis_input_lines(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
     plan: PromptPlan,
+    approved_plan_path: str = "",
 ) -> list[str]:
     if plan.packet_only:
         packet_path = instruction_path(manifest, active_context, "analysisPacketPath")
-        return existing_input_lines((("Primary analysis packet", packet_path),))
+        # 승인 계획은 `## Inputs` 에 실어야 한다. 워커의 읽기 범위는 이 절과
+        # `[Required reading]`·검증 대상 경로만 허용하는데(`**Read scope:**`),
+        # 패킷은 Tier 1 을 "원 브리프/승인 계획의 `validation` 세트" 로 정의하고
+        # 승인 계획의 requirements·scope 까지 요구한다. 경로가 여기 없으면 범위를
+        # 지키는 워커는 그 요구를 만족시킬 방법이 없다 — 실측(2026-08-26,
+        # `fontsninja-nlpvibe` final-verification): 범위를 지킨 검증자는 Tier 1 을
+        # 무엇으로 볼지 몰라 `tsc --noEmit` 으로 대체했고, 범위를 넘은 검증자만
+        # 계약대로의 산출물을 냈다.
+        return existing_input_lines((
+            ("Primary analysis packet", packet_path),
+            ("Approved plan", approved_plan_path),
+        ))
     inputs = [
         ("Primary analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
         ("Task brief", instruction_path(manifest, active_context, "taskBriefPath")),

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -221,6 +221,47 @@ def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
     return [f"normalized initial analysis prompts differ across workers: {workers}"]
 
 
+# reverify 응답 계약 블록. `prompts/lead/convergence.md`
+# §"Required reverify output contract (BLOCKING)" 가 정본이고, 리드는 그 블록을
+# 변종별 응답 형식 뒤에 그대로 덧붙인다.
+#
+# 바이트 단위로 비교하지 않는다 — 손으로 복사하는 블록이라 공백·줄바꿈이 흔들리고,
+# 그 흔들림으로 디스패치를 막으면 규칙이 아니라 서식을 강제하게 된다. 세 항목이
+# 각각 무엇을 요구하는지 식별하는 토큰으로 본다.
+_OUTPUT_CONTRACT_HEADING = "## Output Contract"
+_OUTPUT_CONTRACT_CLAUSES = (
+    ("result-path write", ("Result Path", "before returning")),
+    ("audit sidecar write", ("Audit sidecar path", "before returning")),
+    ("no inline-only response", ("inline",)),
+)
+
+
+def _validate_output_contract_block(text: str) -> list[str]:
+    """응답 계약 블록이 프롬프트에 실려 있는지.
+
+    빠지면 워커가 결과를 파일로 쓰지 않고 인라인으로만 답하는 경로가 열린다 —
+    그 run 은 결과 파일이 없는 채로 dispatch 만 성공한 것처럼 보인다.
+    """
+    if _OUTPUT_CONTRACT_HEADING not in text:
+        return [
+            f"`{_OUTPUT_CONTRACT_HEADING}` block is required "
+            "(convergence.md §\"Required reverify output contract\")"
+        ]
+    tail = text.split(_OUTPUT_CONTRACT_HEADING, 1)[1]
+    missing = [
+        label
+        for label, tokens in _OUTPUT_CONTRACT_CLAUSES
+        if not all(token.lower() in tail.lower() for token in tokens)
+    ]
+    if missing:
+        return [
+            "output contract block is missing its "
+            + ", ".join(missing)
+            + " clause"
+        ]
+    return []
+
+
 def validate_reverify_prompt(
     text: str,
     *,
@@ -268,6 +309,7 @@ def validate_reverify_prompt(
         and boundary_position > first_heading.start()
     ):
         errors.append("phase boundary block must precede reverify instructions")
+    errors.extend(_validate_output_contract_block(normalized))
     return errors
 
 
@@ -351,7 +393,9 @@ def validate_initial_prompt_records(
         )
         if plan.equality_group:
             group = equality_groups.setdefault(plan.equality_group, {})
-            group[record.worker_id] = text
+            # 최초 프롬프트의 동등성만 비교한다. 같은 역할의 교정 호출은 최초
+            # assignment 를 재사용할 수 있지만 지시문은 의도적으로 달라진다.
+            group.setdefault(record.worker_id, text)
     for prompts in equality_groups.values():
         errors.extend(validate_analysis_prompt_set(prompts))
     return errors
@@ -365,15 +409,34 @@ def _validate_model_header(text: str, expected_model: str | None) -> list[str]:
     """
     if expected_model is None:
         return []
-    task_text = text.split("\n\n## Task Instructions\n\n", 1)[-1]
-    model = _model_value(_header_values(task_text, MODEL_HEADER))
+    model = _model_value(_header_values(text, MODEL_HEADER))
     if model is None:
         return ["exactly one non-empty **Model:** <label>, <model> header is required"]
-    if model != expected_model:
+    if not _model_header_matches(model, expected_model):
         return [f"prompt model does not match requested model: {expected_model}"]
     return []
 
 
+def validate_prompt_model_header(text: str, expected_model: str) -> list[str]:
+    """`**Model:**` 헤더가 이 디스패치가 실제로 돌릴 모델을 가리키는가.
+
+    재료화는 호출자가 넘긴 모델로 판정한다. 그 값이 옳아도 프롬프트 본문의
+    헤더가 다르면 어긋남은 `validate-run` 에서야 드러나는데, 그때는 프롬프트가
+    이미 나가고 다이제스트가 기록된 뒤라 그 run 안에서 고칠 수 없다 — 프롬프트를
+    고치면 다이제스트 위조가 된다. `record-dispatch` 는 워커가 돌기 전 마지막
+    지점이고, 거기서는 **기록된 배정값** 을 쓸 수 있다.
+
+    묻는 것은 "적혀 있다면 이 모델인가" 하나다. 헤더가 없는 것은 여기서 볼
+    문제가 아니다 — 어떤 audience 가 그 헤더를 실어야 하는지는 프롬프트 계약이
+    audience 를 알고 판정한다. 여기서 부재까지 막으면 헤더를 요구하지 않는
+    디스패치가 전부 막힌다.
+    """
+    task_text = text.split("\n\n## Task Instructions\n\n", 1)[-1]
+    if _model_value(_header_values(task_text, MODEL_HEADER)) is None:
+        return []
+    return _validate_model_header(text, expected_model)
+
+
 def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
     errors = [
         *_validate_delivery_mode(
@@ -462,13 +525,41 @@ def _header_values(text: str, prefix: str) -> list[str]:
     ]
 
 
+def _model_header_matches(got: str, expected: str) -> bool:
+    """표시 alias 와 실행 id 를 같은 요청으로 본다.
+
+    헤더는 `opus-5` 이고 잡의 실행 값은 `claude-opus-5` 인 경우가 있다.
+    콤마 형식의 두 번째 칸과 실행 값이 문자열로 다를 뿐이면 거절하지 않는다.
+
+    `<provider>/<model>` 표기도 받는다. 위저드가 사용자에게 모델을 보여 줄 때
+    쓰는 표기가 정확히 그것(`claude/sonnet`)이라, 지시문에 그대로 옮겨 적는 것이
+    자연스러운 실수가 아니라 자연스러운 선택이다. provider 는 이 헤더의 판정
+    대상이 아니다 — 별도의 `**Provider:**` 헤더가 담당한다. 그래서 앞의 한 칸을
+    떼고 모델끼리 비교한다. 다른 모델이면 떼고 나서도 안 맞으므로 이 관용이
+    불일치를 가리지는 않는다(`claude/opus-5` 대 `sonnet` 은 그대로 실패).
+    """
+    if got == expected:
+        return True
+    got_l, expected_l = got.lower(), expected.lower()
+    if got_l == expected_l:
+        return True
+    if expected_l.endswith("-" + got_l) or got_l.endswith("-" + expected_l):
+        return True
+    if "/" in got_l:
+        return _model_header_matches(got_l.rsplit("/", 1)[1], expected_l)
+    return False
+
+
 def _model_value(values: list[str]) -> str | None:
     if len(values) != 1:
         return None
-    parts = [part.strip() for part in values[0].rsplit(",", 1)]
-    if len(parts) != 2 or not all(parts):
+    raw = values[0].strip()
+    if not raw:
         return None
-    return parts[1]
+    parts = [part.strip() for part in raw.rsplit(",", 1)]
+    if len(parts) == 2 and all(parts):
+        return parts[1]
+    return raw
 
 
 def _resolve_record_plan(

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -82,7 +82,7 @@ PLAIN_FILE_WRITE_HEADER = (
     "brain folder, so an artifact write under `<PROJECT_ROOT>/.okstra/` is "
     "rejected and the run ends with no result file."
 )
-ANTIGRAVITY_WORKER_ID = "antigravity"
+ANTIGRAVITY_PROVIDER = "antigravity"
 
 
 def worker_prompt_headers(
@@ -141,7 +141,7 @@ def worker_prompt_headers(
         f"**Errors sidecar path:** {errors_sidecar_path}",
         READ_SCOPE_HEADER,
     ])
-    if worker_id == ANTIGRAVITY_WORKER_ID:
+    if _worker_provider(manifest, worker_id) == ANTIGRAVITY_PROVIDER:
         headers.append(PLAIN_FILE_WRITE_HEADER)
     if _string_value(manifest.get("taskType")) == "improvement-discovery":
         headers.append(
@@ -153,6 +153,28 @@ def worker_prompt_headers(
     return headers
 
 
+def _worker_provider(manifest: Mapping[str, Any], worker_id: str) -> str:
+    """이 워커를 실행할 공급자.
+
+    `agy` 의 artifact store 는 공급자의 성질이지 워커 칸 이름의 성질이 아니다.
+    종전에는 `worker_id == "antigravity"` 로 걸렀는데, 워커 id 가 공급자 이름과
+    같은 것은 기본 로스터뿐이다 — 역할 접미사가 붙은 칸(`antigravity-planner`
+    등)은 전부 이 안전장치를 못 받았고, 그 프롬프트를 재검증에 쓰려던 리드는
+    계약(`prompts/lead/convergence.md` §"Required reverify-prompt anchor
+    headers")대로 라운드를 중단해야 했다.
+
+    로스터 행을 못 찾으면 종전 규칙으로 떨어진다 — 그 자리에선 공급자를 알
+    방법이 없고, 헤더를 빼면 계약이 fail-closed 로 막는다.
+    """
+    workers = manifest.get("workerAssignments")
+    if isinstance(workers, list):
+        for row in workers:
+            if isinstance(row, Mapping) and row.get("workerId") == worker_id:
+                value = row.get("provider")
+                return value if isinstance(value, str) else ""
+    return worker_id
+
+
 def _final_verification_target_headers(
     active_context: Mapping[str, Any],
 ) -> list[str]:

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Literal, Mapping
 
-from .agent_invocation import AgentAudience
+from .agent.invocation import AgentAudience
 from .analysis_inputs import ANALYSIS_TASK_TYPES
 
 
@@ -90,6 +90,10 @@ class PromptPlan:
     required_headers: tuple[str, ...]
     max_body_lines: int | None
     max_directive_lines: int | None
+    # 이 audience 의 `## Inputs` 가 승인 계획을 함께 열거하는가. 승인 계획을
+    # 기준으로 판정하라고 요구하는 phase 만 참이다 — 없는 phase 에 실으면
+    # 열거만 되고 열 파일이 없는 줄이 된다.
+    include_approved_plan: bool = False
 
 
 def resolve_prompt_plan(
@@ -149,6 +153,7 @@ def resolve_prompt_plan(
             duty_audience=analysis_duty,
             equality_group=analysis_equality_group,
             packet_only=True,
+            include_approved_plan=True,
             required_headers=FINAL_VERIFICATION_HEADERS,
             max_body_lines=96,
             max_directive_lines=40,
@@ -191,6 +196,7 @@ def _plan(
     duty_audience: AgentAudience | None = None,
     equality_group: str | None = None,
     packet_only: bool = False,
+    include_approved_plan: bool = False,
     allow_coding_preflight: bool = False,
     required_headers: tuple[str, ...] = (),
     max_body_lines: int | None = None,
@@ -201,6 +207,7 @@ def _plan(
         duty_audience=duty_audience or _duty_audience(audience),
         equality_group=equality_group,
         packet_only=packet_only,
+        include_approved_plan=include_approved_plan,
         allow_coding_preflight=allow_coding_preflight,
         required_headers=_worker_facing_headers(audience, required_headers),
         max_body_lines=max_body_lines,
@@ -261,14 +268,22 @@ def critic_assignment_ref(task_type: str) -> str:
 
 
 def _executor_worker_id(manifest: Mapping[str, Any]) -> str | None:
+    """실행자의 **worker_id**. provider 이름이 아니다.
+
+    한 provider 가 실행자와 검증자를 겸하면 슬롯마다 역할이 붙어 실행자의 id 는
+    `codex-implementer` 가 된다. 여기서 provider(`codex`)를 돌려주면 실행자가
+    자기 자신과 매칭되지 않아 검증자 프롬프트로 실체화되고, 그 사실은
+    `agent invocation duty does not match expected audience` 로 디스패치 단계에서야
+    드러난다.
+    """
     team_contract = manifest.get("teamContract")
     if not isinstance(team_contract, Mapping):
         return None
     executor = team_contract.get("executor")
     if not isinstance(executor, Mapping):
         return None
-    provider = executor.get("provider")
-    return provider.strip() if isinstance(provider, str) and provider.strip() else None
+    worker_id = executor.get("workerId")
+    return worker_id.strip() if isinstance(worker_id, str) and worker_id.strip() else None
 
 
 def _required_string(payload: Mapping[str, Any], key: str) -> str:

package/runtime/python/okstra_ctl/worker_request.py

@@ -54,7 +54,8 @@ def build_request(
         project_root=root,
         worktree_path=worktree,
         # Nobody is at the keyboard to answer an approval prompt, so the gate is
-        # open and the boundary comes from the write scope instead.
+        # open. The write scope tells the worker where it belongs; nothing in the
+        # CLI stops it leaving, so the run checks that after the fact.
         policy=ExecutionPolicy(
             auto_approve=True,
             write_scope=write_scope(root, worktree, role),

package/runtime/python/okstra_ctl/worker_runner.py

@@ -10,6 +10,7 @@ SIGTERM a healthy worker in the middle of a long reasoning stretch.
 """
 from __future__ import annotations
 
+import dataclasses
 import json
 import os
 import selectors
@@ -21,6 +22,7 @@ from typing import Any, Callable, Mapping
 
 from .domain.provider import ServedModelAttestation, ServedModelNormalizer
 from .domain.worker_exec import (
+    NO_RESULT_EXIT_CODE,
     SERVED_MODEL_MISMATCH_EXIT_CODE,
     ExecCommand,
     ExecutionStrategy,
@@ -226,11 +228,9 @@ def _with_served_model_observation(
         observation.record(observed)
         return observed
 
-    return JsonEvents(
-        normalise=presentation.normalise,
-        observe=observe,
-        join_adjacent_text=presentation.join_adjacent_text,
-    )
+    # 필드를 손으로 옮기지 않는다 — 그렇게 하던 동안 어댑터가 선언한
+    # `is_conclusion` 이 여기서 떨어져 나가, grok 의 종결 판정이 무효였다.
+    return dataclasses.replace(presentation, observe=observe)
 
 
 class _ServedModelObservation:
@@ -393,11 +393,16 @@ def _pump(
     strategy.flush(transcript)
 
     exit_code = process.wait()
-    if closing_text is None and isinstance(strategy, JsonEvents):
-        # JSON 스트림은 결과 이벤트로 끝나야 한다. 텍스트를 흘리는 CLI 에는
-        # 놓칠 결과 이벤트가 없다.
+    if isinstance(strategy, JsonEvents) and not strategy.concluded():
+        # JSON 스트림은 그 어휘의 종결 이벤트로 끝나야 한다. 텍스트를 흘리는
+        # CLI 에는 놓칠 종결 이벤트가 없다. 무엇이 종결인지는 전략이 안다.
         transcript.note("no result event in the CLI's output")
-    elif closing_text is not None:
+        if exit_code == 0 and not timed_out:
+            # 실측(dev-10341, 한 CLI 4회): 종결 이벤트도 산출물도 없이 exit 0.
+            # 그대로 돌려주면 사이드카와 셸 소비자에게는 성공으로 읽힌다.
+            # CLI 자신의 비영 코드는 보존한다 — 그쪽이 더 구체적인 사실이다.
+            exit_code = NO_RESULT_EXIT_CODE
+    if closing_text is not None:
         # Result 는 format_* 가 줄을 만들지 않는다. 아카이브 결론은 러너가 적는다.
         # 상한 밖에 둔다 — 잘린 결론은 사후 분석 전체를 잃게 한다.
         if isinstance(strategy, JsonEvents):
@@ -559,6 +564,8 @@ def _terminate(process: subprocess.Popen[bytes]) -> None:
         try:
             os.killpg(process.pid, signal.SIGKILL)
         except ProcessLookupError:
+            # expected-miss: SIGTERM 유예 사이에 그룹이 스스로 끝난 경우다.
+            # 죽이려던 대상이 이미 없는 것은 성공이지 실패가 아니다.
             pass
         process.wait()
 

package/runtime/python/okstra_ctl/worker_state.py

@@ -18,8 +18,23 @@ def _validated_team_state_path(value: str) -> Path:
     return path
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra worker-state transition --team-state <path> --worker <worker-id> \
+    --status <in-progress|completed|timeout|error|not-run> \
+    [--reason <text>] [--model <execution-value>]
+
+in-progress records startedAt and clears endedAt. completed, timeout, and error
+record endedAt. timeout, error, and not-run require --reason.
+"""
+_CLI_DESCRIPTION = "Atomically transition persisted worker status."
+
+
 def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="okstra worker-state")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra worker-state")
     commands = parser.add_subparsers(dest="command", required=True)
     transition = commands.add_parser(
         "transition", help="atomically transition one worker status"

package/runtime/python/okstra_ctl/workflow.py

@@ -54,7 +54,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
             "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n"
             "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
-            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique)"
+            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique / unverified)"
         ),
     },
     "project-analysis": {
@@ -173,6 +173,22 @@ def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
     return {phase: render_forbidden(items) for phase, items in data.items()}
 
 
+def phase_position(task_type: str) -> str:
+    """이 phase 가 생애주기 몇 번째인지 — `"5 of 7"`.
+
+    리드는 자기가 어느 칸을 도는지만 알고 지도를 못 본다. 다음 phase 이름은
+    이 run 의 리포트가 정하므로 계속 감추지만(`WORKFLOW_NEXT_RECOMMENDED_PHASE`
+    가 빈 문자열인 이유), 위치를 감출 이유는 없다 — 위치를 모르면 중간 단계를
+    도는 run 이 자기가 마지막인 것처럼 결론을 낸다.
+
+    `PHASE_SEQUENCE` 밖의 사이드트랙 task-type(improvement-discovery 등)은
+    생애주기 칸이 없으므로 빈 문자열이다.
+    """
+    if task_type not in PHASE_SEQUENCE:
+        return ""
+    return f"{PHASE_SEQUENCE.index(task_type) + 1} of {len(PHASE_SEQUENCE)}"
+
+
 def compute_workflow_state(
     *,
     task_type: str,
@@ -219,6 +235,7 @@ def compute_workflow_state(
         "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
+        "WORKFLOW_PHASE_POSITION": phase_position(task_type),
         # 값이 아니라 자리표시자다. 실제 포인터는 리포트 라우팅에서 투영돼
         # 매니페스트의 `workflow.nextRecommendedPhase` 구조체로 저장된다.
         # 이 ctx 값은 그 구조체로 대체되지 않는다 — 남은 소비자는